### Run the Dummy Application Source: https://github.com/avo-hq/avo/blob/main/agents.md Starts the development server and asset watchers using Overmind. ```bash AVO_LICENSE_KEY=license_123 bin/dev # starts web + js/css/custom-js watchers via overmind ``` -------------------------------- ### Start PostgreSQL Service Source: https://github.com/avo-hq/avo/blob/main/agents.md Initializes the PostgreSQL 16 service required for the development environment. ```bash sudo pg_ctlcluster 16 main start ``` -------------------------------- ### Run the dummy application Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Starts the Rails server along with JS and CSS bundling processes. ```bash bin/dev ``` -------------------------------- ### Build and watch assets Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Commands to install dependencies and compile assets for local development. ```bash yarn install ``` ```bash yarn build ``` ```bash yarn build --watch ``` -------------------------------- ### Configure Docker environment variables Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Example configuration for the .env.test file when using Docker. ```text POSTGRES_HOST=localhost POSTGRES_PORT=5433 POSTGRES_USERNAME=postgres POSTGRES_PASSWORD= ``` -------------------------------- ### Stimulus Frame Manipulation Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-06-09-001-feat-manual-turbo-frame-loading-plan.md Examples of existing Stimulus controller patterns for manipulating Turbo Frame sources and reloading. ```javascript this.parentTurboFrame.src = url ``` ```javascript frame.reload() ``` -------------------------------- ### Initialize Development and Test Databases Source: https://github.com/avo-hq/avo/blob/main/agents.md Sets up the database schema and seeds the development environment with an admin user. ```bash # Development DB AVO_LICENSE_KEY=license_123 bin/rails db:create AVO_LICENSE_KEY=license_123 bin/rails db:migrate AVO_LICENSE_KEY=license_123 AVO_ADMIN_PASSWORD=secret bin/rails db:seed # Test DB (schema only — load separately, migrate does not target it) AVO_LICENSE_KEY=license_123 RAILS_ENV=test bin/rails db:schema:load ``` -------------------------------- ### Define Conditional Row Class Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-05-05-001-feat-table-view-row-options-plan.md Example of a conditional class logic based on record attributes. ```ruby class: -> { record.id.even? ? "even" : "odd" } ``` -------------------------------- ### Seed the dummy application database Source: https://github.com/avo-hq/avo/blob/main/agents.md Run this command within the dummy application directory to initialize the database and create the admin user. ```sh cd spec/dummy && rails db:seed ``` -------------------------------- ### Run migration and test scripts Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Commands to prepare the database and execute test suites. ```bash bin/rails db:migrate ``` ```bash cp spec/dummy/.env.test.sample spec/dummy/.env.test ``` ```bash bin/test ``` ```bash bin/test unit ``` ```bash bin/test system ``` ```bash bin/test ./spec/features/hq_spec.rb ``` -------------------------------- ### Define checkbox list field in DSL Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-05-22-001-feat-checkbox-list-field-plan.md Use the checkbox_list field type with an options lambda to define selectable items. The second example demonstrates the v2-shaped block supporting additional metadata like descriptions and images. ```ruby field :addon_ids, as: :checkbox_list, options: -> { Addon.all.map { |a| { id: a.id, title: a.name } } } # v2-shaped block (already supported by the v1 hash contract; # extra keys are tolerated and ignored until v2): field :addon_ids, as: :checkbox_list, options: -> { Addon.all.map do |a| { id: a.id, title: a.name, description: a.summary, image_url: a.icon_url, image_format: "circle" } end } ``` -------------------------------- ### Seed the database Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Populates the database with dummy data and creates a default user. ```bash AVO_ADMIN_PASSWORD=secreto bin/rails db:seed ``` -------------------------------- ### Normalize configuration values in Branding#initialize Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-05-06-001-feat-brand-color-overrides-plan.md Pattern for normalizing configuration arrays to strings during initialization. ```ruby Array(config[:neutrals]).map(&:to_s).freeze ``` -------------------------------- ### Build Frontend Assets Source: https://github.com/avo-hq/avo/blob/main/agents.md Compiles JavaScript and CSS assets required for the application interface. ```bash yarn build:js yarn build:css yarn build:custom-js ``` -------------------------------- ### Run Linting Tools Source: https://github.com/avo-hq/avo/blob/main/agents.md Executes linters for Ruby, ERB, and JavaScript files. ```bash bundle exec standardrb # Ruby (StandardRB) bundle exec erb_lint --lint-all # ERB yarn eslint app/javascript # JS ``` -------------------------------- ### Define Manual Loading in DSL Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-06-09-001-feat-manual-turbo-frame-loading-plan.md Configure manual loading for tabs and associations using the loading: :manual option. ```text # Tabs — every manual tab shows its own Load button tab title: "Orders", loading: :manual do field :orders, as: :has_many end # Associations — placeholder + Load button on the Show page field :orders, as: :has_many, loading: :manual # Unchanged: omitting `loading:` keeps eager/lazy exactly as today tab title: "Address", lazy_load: true do ... end # still lazy field :comments, as: :has_many # still eager/lazy per context ``` -------------------------------- ### Configure local gem path Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Updates the Gemfile to point to a local clone of the Avo repository. ```ruby gem 'avo', path: '../avo' # or gemspec path: '../avo' ``` -------------------------------- ### Run a system spec shard locally Source: https://github.com/avo-hq/avo/blob/main/spec/system/avo/read_about_groups.md Executes a specific group of system specs in parallel after preparing the database. ```bash bundle exec rake parallel:drop parallel:create parallel:migrate && bundle exec parallel_rspec spec/system/avo/group_1 ``` -------------------------------- ### Manage fast-seed snapshots Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Commands for performing fast database resets and regenerating the committed seed snapshot. ```bash # First-time setup (also: anytime you want to reset the dummy DB) bin/setup --fast # Or directly: bin/rails app:db:fast_seed ``` ```bash bin/rails app:db:fast_seed:rebuild git add spec/dummy/db/fast_seed/ git commit -m "Refresh fast-seed snapshot" ``` -------------------------------- ### Execute Test Suite Source: https://github.com/avo-hq/avo/blob/main/agents.md Runs various test categories including unit, system, and specific file tests. ```bash bin/test # everything (slow) bin/test unit # feature + controller + component (fast) bin/test system # system/browser tests (builds assets first, slow) bin/test ./spec/requests/avo/home_request_spec.rb # single file ``` -------------------------------- ### Configure Turbo Frame Loading Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-06-09-001-feat-manual-turbo-frame-loading-plan.md Standard implementation for rendering a Turbo Frame with dynamic loading attributes. ```ruby turbo_frame_tag @field.turbo_frame, src: @field.frame_url, loading: turbo_frame_loading ``` -------------------------------- ### Annotate Models Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Updates the schema structure for models within the dummy application. ```bash annotate --models --exclude fixtures ``` -------------------------------- ### Mode and Surface Resolution Logic Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-06-09-001-feat-manual-turbo-frame-loading-plan.md Logic flow for determining whether to use manual loading based on the loading attribute. ```text loading: omitted -> manual? == false -> existing eager/lazy path (UNCHANGED) loading: :manual -> manual? == true -> placeholder + Load button, no src (gated by view.display? — ignored in Edit/New) ``` -------------------------------- ### Normalize Locale Files Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Sorts locale keys alphabetically within the project files. ```bash i18n-tasks normalize ``` -------------------------------- ### ExecutionContext Handling Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-05-22-001-feat-checkbox-list-field-plan.md Pattern for resolving callable options within field contexts. ```ruby target.respond_to?(:call) ? instance_exec(&target) : target ``` -------------------------------- ### Turbo Frame Lifecycle Diagram Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-06-09-001-feat-manual-turbo-frame-loading-plan.md Visual representation of the frame lifecycle from initial render to successful content swap or error handling. ```text render (display view, manual?) click Load success ┌───────────────────────────┐ user ┌──────────────────────┐ swap ┌──────────────┐ │ NO src │ ─────▶ │ controller sets src= │ ─────▶ │ real content │ │ data-manual-frame │ │ LoadingComponent / │ │ (focus moved)│ │ [Load button] (aria-label)│ │ aria-busy spinner │ └──────────────┘ └───────────────────────────┘ └─────────┬────────────┘ ▲ │ 500 / error │ reveal (tabs): classList toggle ▼ │ → NO fetch (no src) ┌──────────────────────┐ └────────────────────────────── │ inline error + Retry │ (global 500 handler skips │ (Retry re-sets src) │ data-manual-frame) └──────────────────────┘ ``` -------------------------------- ### Register global hotkeys Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Define custom actions for shortcuts that do not map to specific elements by adding entries to the global hotkeys registry. ```javascript const ELEMENT_HOTKEYS = [ { hotkey: 'r r r', handle: () => window.StreamActions.turbo_reload() }, { hotkey: 'g h', handle: () => Turbo.visit('/') }, ] ``` ```javascript const DIRECT_HOTKEYS = [ { match: (e) => e.key === '?' || (e.shiftKey && e.code === 'Slash'), handle: () => document.dispatchEvent(new Event('persistent-modal:toggle')), }, ] ``` -------------------------------- ### Brand Configuration and CSS Emission Flow Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-05-06-001-feat-brand-color-overrides-plan.md Conceptual flow for configuring brand colors, validating inputs, and rendering CSS overrides in the application head. ```text config.branding = { neutral_colors: { light: { 25..950 }, dark: { 25..950 } }, accent_colors: { light: { color:, content:, foreground: }, dark: { ... } } } │ ▼ Avo::Configuration::Branding#initialize ├─ assigns @neutral_colors, @accent_colors └─ validates each (raises ArgumentError listing missing shades / missing schemes if incomplete) │ ▼ Branding#brand_css_overrides → CSS string or nil │ ▼ _brand_overrides.html.erb (rendered in layout , AFTER application.css link) └─ emits │ ▼ Cascade resolves at runtime: - No theme class on → :root values apply (the brand) - .neutral-theme-slate → slate beats :root by specificity - .accent-theme-blue → blue beats :root by specificity Picker swatches read CSS variables: .color-scheme-switcher__theme-preview--brand { background: var(--color-avo-neutral-400); } .color-scheme-switcher__accent-preview--brand, .color-scheme-switcher__accent-badge-preview--brand { background: var(--color-accent); } ``` -------------------------------- ### Table View Row Options Architecture Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-05-05-001-feat-table-view-row-options-plan.md Visual representation of the data flow from resource configuration to the final HTML rendering of table rows. ```text ┌──────────────────────────────────────────────────────────────────────┐ │ Avo::Resources::Message │ │ self.table_view = { row_options: { class: -> { ... }, data: ... }} │ │ │ │ └─────────┼────────────────────────────────────────────────────────────┘ │ class_attribute storage on Resources::Base ▼ ┌──────────────────────────────────────────────────────────────────────┐ │ Avo::Index::TableRowComponent │ │ def view = @reflection.present? ? :has_many : :index │ │ │ │ def merged_tr_attributes │ │ Avo::Concerns::TableRowOptionsMerger.call( │ │ avo_attributes: { id:, class:, data: }, │ │ user_options: @resource.class.table_view, │ │ record: @resource.record, resource: @resource, view: view │ │ ) │ │ end │ └──────────────────────────────────────────────────────────────────────┘ │ called inline in .html.erb (after cache boundary) ▼ ┌──────────────────────────────────────────────────────────────────────┐ │ Avo::Concerns::TableRowOptionsMerger.call │ │ 1. Resolve top-level block: instance_exec via ExecutionContext │ │ 2. For each key, resolve per-value block (same path) │ │ 3. Validate return types per R11; raise/log on mismatch │ │ 4. Enforce denylist: id, role, aria-selected, on*, tabindex, │ │ contenteditable, draggable -> raise in dev, log in prod │ │ 5. Class merge: class_names(avo_class, user_class) │ │ 6. Data merge: │ │ a. Token-concat: controller, action (Rails token_list) │ │ b. Avo-wins on reserved keys; warn if user set them in dev │ │ c. Last-wins for non-reserved keys │ │ 7. Pass-through for other HTML attributes │ │ 8. Wrap in ActiveSupport::Notifications.instrument │ │ "avo.row_options.evaluate" │ └──────────────────────────────────────────────────────────────────────┘ │ ▼ content_tag :tr, **merged_attributes do ... end ``` -------------------------------- ### Update Appraisal gemfiles Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Run this command after modifying the main Gemfile to ensure versioned gemfiles are synchronized. ```bash bundle exec appraisal install ``` -------------------------------- ### CSS Component Import Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-05-22-001-feat-checkbox-list-field-plan.md Directive for adding new component styles to the application stylesheet. ```css @import "./css/components/ui/checkbox_list.css"; ``` -------------------------------- ### Manage Missing I18n Keys Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Commands for adding missing translation keys to locale files, either manually or via automated translation. ```bash i18n-tasks add-missing ``` ```bash OPENAI_API_KEY=TOKEN bundle exec i18n-tasks translate-missing --backend=openai ``` -------------------------------- ### Configure Table View Row Options Source: https://github.com/avo-hq/avo/blob/main/docs/plans/2026-05-05-001-feat-table-view-row-options-plan.md Defines the structure for applying conditional classes to table rows using the self.table_view configuration. ```ruby self.table_view = { row_options: { class: -> { record. ... } } } ``` ```ruby self.table_view = { row_options: { ... } } ``` -------------------------------- ### Define row options using a block Source: https://github.com/avo-hq/avo/blob/main/docs/brainstorms/2026-05-04-resource-table-view-row-options-requirements.md Use a single block to evaluate multiple row options dynamically for a resource. ```ruby self.table_view = { row_options: -> { { class: record.role == "agent" ? "bg-blue-50 dark:bg-blue-950/40" : "", data: { test_id: "message-row", role: record.role }, title: "Message from #{record.role}" } } } ``` -------------------------------- ### Interact with datepicker helpers Source: https://github.com/avo-hq/avo/blob/main/CONTRIBUTING.MD Methods to manipulate the datepicker component during system tests. ```ruby open_picker close_picker set_picker_day "January 2, 2000" set_picker_hour 17 set_picker_minute 17 set_picker_second 17 ``` -------------------------------- ### Branch row options by render context Source: https://github.com/avo-hq/avo/blob/main/docs/brainstorms/2026-05-04-resource-table-view-row-options-requirements.md Use the view variable to conditionally apply styles based on whether the table is rendered in an index or has_many context. ```ruby class: -> { view == :index && record.role == "agent" ? "bg-blue-50 dark:bg-blue-950/40" : "" } ```