avo 4.1.0 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bab30be7824485fe6b7fe08f097ecf321608025991b308464ea9499699b3411e
-  data.tar.gz: 270ef2625f618fc06ba8e39709a1b71b15ce9688fb3fb03a64e94cae6c23b19c
+  metadata.gz: 11f187415959e9efda4f7f7a84fe5aa9c826762d444c08104201d9c176cd2022
+  data.tar.gz: 14561031f960b84adb95eb3dc5b6fa16b5c1703a2dd04d15e92a305bb031470b
 SHA512:
-  metadata.gz: d3eabb56f5178fbebde61e38e75da740659d95c64b2a0f061768bfbeb143b9c2ea9790c790283a4f94a78ffed2682e22ce001a67caac711373186c1fe4692086
-  data.tar.gz: 05ce85249eb5670b492da7d42851f9a5fc833ad1e15d6e7182a7be4295195047e0a90a341b1151504b5e56ea175d3202b6b3c01848491612ce200d10fc8b9221
+  metadata.gz: 357090778d39bbe290687ea6176397a4eb33441e0e7c79c033630cfdf18252fb7328b0b2bcd9a652fac46c1689a50d9375cd96abd162db6d586299fe80fd277a
+  data.tar.gz: 6d9a566fb0fa4bee1fbe1790a2e1a92a174aaf5c76952afe11be2c14330fd532732f9fe77dee42f6a6bf143f935883e822d58ca57da1011f399e621309d04207

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    avo (4.1.0)
+    avo (4.1.1)
       actionview (>= 6.1)
       active_link_to
       activerecord (>= 6.1)

data/app/assets/builds/avo/application.css

@@ -16,6 +16,7 @@
     --color-red-500: oklch(63.7% 0.237 25.331);
     --color-red-600: oklch(57.7% 0.245 27.325);
     --color-red-700: oklch(50.5% 0.213 27.518);
+    --color-red-950: oklch(25.8% 0.092 26.042);
     --color-orange-50: oklch(98% 0.016 73.684);
     --color-orange-100: oklch(95.4% 0.038 75.164);
     --color-orange-300: oklch(83.7% 0.128 66.29);
@@ -59,6 +60,7 @@
     --color-emerald-500: oklch(69.6% 0.17 162.48);
     --color-emerald-600: oklch(59.6% 0.145 163.225);
     --color-emerald-700: oklch(50.8% 0.118 165.612);
+    --color-emerald-950: oklch(26.2% 0.051 172.552);
     --color-teal-50: oklch(98.4% 0.014 180.72);
     --color-teal-100: oklch(95.3% 0.051 180.801);
     --color-teal-300: oklch(85.5% 0.138 181.071);
@@ -1419,6 +1421,9 @@
   .w-16 {
     width: calc(var(--spacing) * 16);
   }
+  .w-32 {
+    width: calc(var(--spacing) * 32);
+  }
   .w-64 {
     width: calc(var(--spacing) * 64);
   }
@@ -2130,6 +2135,9 @@
   .bg-indigo-500 {
     background-color: var(--color-indigo-500);
   }
+  .bg-indigo-600 {
+    background-color: var(--color-indigo-600);
+  }
   .bg-lime-50 {
     background-color: var(--color-lime-50);
   }
@@ -2745,6 +2753,9 @@
   .opacity-50 {
     opacity: 50%;
   }
+  .opacity-60 {
+    opacity: 60%;
+  }
   .opacity-75 {
     opacity: 75%;
   }
@@ -2836,6 +2847,10 @@
     --tw-ease: var(--ease-out);
     transition-timing-function: var(--ease-out);
   }
+  .select-all {
+    -webkit-user-select: all;
+    user-select: all;
+  }
   .select-none {
     -webkit-user-select: none;
     user-select: none;
@@ -3796,18 +3811,33 @@
       border-color: color-mix(in oklab, var(--color-orange-500) 30%, transparent);
     }
   }
+  .dark\:bg-blue-900:where(.dark, .dark *) {
+    background-color: var(--color-blue-900);
+  }
   .dark\:bg-blue-950\/40:where(.dark, .dark *) {
     background-color: color-mix(in srgb, oklch(28.2% 0.091 267.935) 40%, transparent);
     @supports (color: color-mix(in lab, red, red)) {
       background-color: color-mix(in oklab, var(--color-blue-950) 40%, transparent);
     }
   }
+  .dark\:bg-emerald-950\/30:where(.dark, .dark *) {
+    background-color: color-mix(in srgb, oklch(26.2% 0.051 172.552) 30%, transparent);
+    @supports (color: color-mix(in lab, red, red)) {
+      background-color: color-mix(in oklab, var(--color-emerald-950) 30%, transparent);
+    }
+  }
   .dark\:bg-orange-950\/30:where(.dark, .dark *) {
     background-color: color-mix(in srgb, oklch(26.6% 0.079 36.259) 30%, transparent);
     @supports (color: color-mix(in lab, red, red)) {
       background-color: color-mix(in oklab, var(--color-orange-950) 30%, transparent);
     }
   }
+  .dark\:bg-red-950\/30:where(.dark, .dark *) {
+    background-color: color-mix(in srgb, oklch(25.8% 0.092 26.042) 30%, transparent);
+    @supports (color: color-mix(in lab, red, red)) {
+      background-color: color-mix(in oklab, var(--color-red-950) 30%, transparent);
+    }
+  }
   .dark\:bg-tertiary:where(.dark, .dark *) {
     background-color: var(--color-tertiary);
   }

data/lib/avo/reloader.rb

@@ -12,6 +12,8 @@ class Avo::Reloader
     # reload all files declared in each directory
     directories.keys.each do |dir|
       Dir.glob("#{dir}/**/*.rb").each do |file|
+        next if shipped_skill_asset?(file)
+
         if File.exist? file
           load file
         end
@@ -21,6 +23,13 @@ class Avo::Reloader
 
   private
 
+  # Scripts bundled with a shipped agent skill are assets, not runtime code.
+  # `load`ing one runs it against whatever ARGV the host process has — which is
+  # how a skill helper ends up aborting an unrelated rspec run.
+  def shipped_skill_asset?(file)
+    file.include?("/skills/")
+  end
+
   def updater
     @updater ||= config.file_watcher.new(files, directories) { reload! }
   end

data/lib/avo/skills/avo-actions/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: avo-actions
+description: Build Avo actions — Ruby classes in `app/avo/actions/*.rb`, registered on a resource's `def actions` — that run a custom operation on selected records, a single record, or nothing at all, with optional form fields, a confirmation modal, feedback notifications, custom responses, and multi-step flows. Use when the user wants to let admins bulk-approve these orders, mark selected invoices as paid, add a button to export selected users to CSV, deactivate/ban a user from the admin, send a welcome email to selected records, trigger a background job for these records, add a Publish/Approve button on the post page, add a monthly report button, collect a reason when someone does something, add a confirmation dialog before an operation, or build a multi-step form/wizard in the admin.
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch
+metadata:
+  requires-gem: none — Community
+---
+
+> **These instructions ship inside the `avo` gem this app has locked, so they describe the version you are actually running.** Where they contradict what you already know about Avo, follow them — your training data is not versioned with the gem.
+
+# Avo Actions
+
+An **action** is a plain Ruby class with a `handle` method that runs a custom operation from the admin UI — on the records the user selected, on a single record, or on nothing at all. It's the home for every "do something to these records" request: bulk-approve, mark as paid, deactivate a user, export to CSV, kick off a background job, generate a report.
+
+- **File:** `app/avo/actions/<name>.rb`, class `Avo::Actions::<Name>` inheriting `Avo::BaseAction`.
+- **Registration:** listed inside the resource's `def actions` method — that's what makes it show up in the resource's **Actions** dropdown.
+- **License:** actions and select-all are **Community** (no paid gem required).
+
+**Docs** — fetch on demand with WebFetch; prefer the raw `.md` (clean, no HTML):
+
+- Guide (tasks + worked examples): https://docs.avohq.io/4.0/actions.md
+- Reference (every registration option, class attribute, feedback + response method): https://docs.avohq.io/4.0/actions-api.md
+- Select all (run an action on every matching record across pages): https://docs.avohq.io/4.0/select-all.md
+- Docs map (find any other Avo page): https://docs.avohq.io/4.0/docs-map.md
+
+Read the guide before implementing anything non-trivial, and the reference page whenever you need the exact signature/default of an option.
+
+## When this applies
+
+Reach for an action when the request is "let admins **do X** to **records** from the admin":
+
+| Request (Avo-shaped or plain Rails) | Pattern |
+| --- | --- |
+| "Bulk-approve these orders", "mark selected invoices as paid", "deactivate the selected users" | [Bulk](#bulk-the-default) |
+| "Add a Publish/Approve button on the post page", "ban this user" | [Single-record](#single-record) |
+| "A monthly report button", "run this maintenance job", "export everything to CSV" | [Standalone](#standalone-no-records-needed) |
+| "Collect a reason when someone bans a user", "ask for a message before sending" | [With fields](#collect-input-with-fields) |
+| "Add a confirmation dialog", "make it ask before running" (or skip it) | [Confirmation](#confirmation-modal) |
+| "Then download a file / redirect / refresh just the row" | [Responses](#control-what-happens-after) |
+| "A multi-step form / wizard" | [multi-step flow](#multi-step-flows-wizards) |
+| "Run it on all matching records, not just this page" | [Select all](#run-on-all-matching-records-select-all) |
+
+Note the boundary: the action is what **runs the operation** and, by default, appears in the resource's **Actions** dropdown. If the user specifically wants it rendered as a **dedicated button or custom control** outside that dropdown (relabel a default button, a button in the row, a bespoke dropdown), that *placement* is a separate paid add-on — use the **`avo-custom-controls`** skill for it. Build the action here; wire the button there.
+
+## Workflow
+
+### 1. Generate the action
+
+```bash
+bin/rails generate avo:action toggle_inactive
+```
+
+Creates `app/avo/actions/toggle_inactive.rb` with a commented skeleton for `visible`, `fields`, and `handle`. Flags:
+
+```bash
+# Standalone action (runs without selected records)
+bin/rails generate avo:action generate_monthly_report --standalone
+
+# Namespaced -> app/avo/actions/admin/approve_user.rb, class Avo::Actions::Admin::ApproveUser
+bin/rails generate avo:action admin/approve_user
+```
+
+If you're writing the file by hand, mirror that path/class convention exactly.
+
+### 2. Write `handle`
+
+`handle` holds the business logic. It receives keyword arguments — take what you need and swallow the rest with `**args`:
+
+```ruby
+# app/avo/actions/toggle_inactive.rb
+class Avo::Actions::ToggleInactive < Avo::BaseAction
+  self.name = "Toggle Inactive"
+
+  def handle(query:, fields:, current_user:, resource:, **args)
+    query.each do |record|
+      record.update!(inactive: !record.inactive)
+    end
+
+    succeed "Toggled status for #{query.count} records"
+  end
+end
+```
+
+The keyword arguments:
+
+- `query` — the selected record(s). **Always an array**, even for a single record (`records` is an alias).
+- `fields` — values submitted through the action's form fields (see below).
+- `current_user` — the authenticated user.
+- `resource` — the Avo resource instance that triggered the action.
+- `request` — the current `ActionDispatch::Request` (add `request:` to the signature to use it).
+
+### 3. Register it on the resource
+
+```ruby
+# app/avo/resources/user.rb
+class Avo::Resources::User < Avo::BaseResource
+  def actions
+    action Avo::Actions::ToggleInactive
+    action Avo::Actions::SendWelcomeEmail, icon: "heroicons/outline/envelope"
+
+    divider label: "Danger zone"
+    action Avo::Actions::BanUser
+  end
+end
+```
+
+Registration options passed alongside the class:
+
+- `icon:` — icon shown next to the action in the dropdown (Heroicons or Tabler path; default `"tabler/outline/player-play"`).
+- `arguments:` — a Hash (or a proc returning one) of custom data available as `arguments` everywhere in the action class (`handle`, `fields`, and the modal blocks). Encrypted + Base64-encoded in URLs, so it's safe for sensitive values.
+- `divider label: "..."` — a visual separator to group related actions.
+
+With no further config the action shows on **Index** and **Show** (hidden on **New**), asks "Are you sure?" in a confirmation modal, runs `handle`, flashes a green success notification, and reloads the page.
+
+## Action patterns
+
+### Bulk (the default)
+Iterate `query` — the checked rows on **Index**. Nothing special to set; this is the out-of-the-box behavior.
+
+```ruby
+def handle(query:, **args)
+  query.each { |order| order.approve! }
+  succeed "Approved #{query.count} orders"
+end
+```
+
+### Single-record
+Same `handle` — on **Show** (or via row controls) `query` is just that one record, still wrapped in an array. Use `visible` to pin it to a view when appropriate:
+
+```ruby
+self.visible = -> { view.show? }
+
+def handle(query:, **args)
+  post = query.first
+  post.publish!
+  succeed "Published #{post.title}"
+end
+```
+
+### Standalone (no records needed)
+For global reports, maintenance tasks, background jobs. Set the attribute (or generate with `--standalone`); it stays enabled with nothing selected and `handle` gets an empty `query`:
+
+```ruby
+class Avo::Actions::GenerateMonthlyReport < Avo::BaseAction
+  self.standalone = true
+
+  def handle(**args)
+    ReportJob.perform_later(current_user)
+    inform "Report queued — you'll get an email when it's ready."
+  end
+end
+```
+
+### Collect input with fields
+Define `fields` to render form inputs in the modal; the submitted values arrive as `fields`. Same field DSL as resources. On a single record the fields are hydrated from it; otherwise they're plain inputs.
+
+```ruby
+def fields
+  field :notify_user, as: :boolean
+  field :message, as: :textarea
+end
+
+def handle(query:, fields:, **args)
+  query.each do |user|
+    user.deactivate!
+    user.notify(fields[:message]) if fields[:notify_user]
+  end
+  succeed "Done"
+end
+```
+
+### Confirmation modal
+The modal is on by default. Customize its text (each may be a string or a block with access to `resource`, `record`, `view`, `arguments`, `query`), or turn it off for safe actions:
+
+```ruby
+self.name = "Release fish"
+self.description = "Release the fish back into the ocean"
+self.message = -> { record ? "Release #{record.name}?" : "Release the fish?" }
+self.confirm_button_label = "Release"
+self.cancel_button_label = "Keep"
+
+self.confirmation = false               # skip the modal, run immediately on click
+self.close_modal_on_backdrop_click = false  # don't lose a filled-in form on a stray click
+```
+
+### Give feedback
+Queue one or more notifications from inside `handle` — call several to stack them. With no explicit feedback Avo shows a generic "Action ran successfully" info alert.
+
+```ruby
+succeed "Green — success"                      # green
+inform "Blue — info"                            # blue
+warn "Orange — heads up", timeout: :forever     # orange; stays until dismissed
+error "Red — failure", timeout: 8000            # red; timeout in ms
+silent                                           # suppress the default notification (e.g. before a redirect)
+```
+
+### Control what happens after
+`handle` also picks the UI response. Default is a full-page `reload`; the last response method called wins:
+
+| Method | Effect |
+| --- | --- |
+| `reload` | Full-page reload (default). |
+| `redirect_to path` | Redirect elsewhere (accepts `allow_other_host:`, `status:`). |
+| `download data, "file.csv"` | Trigger a file download. **Pair with `self.turbo = false`** for a real file response. |
+| `keep_modal_open` | Keep the modal + user input (show an error and let them retry). |
+| `close_modal` / `do_nothing` | Close the modal, leave the page as-is. |
+| `reload_records(query)` | Refresh only the affected rows/cards. **Index only — not associations.** |
+| `navigate_to_action Other, arguments: {...}` | Chain into another action (see below). |
+| `append_to_response -> { [turbo_stream...] }` | Add your own turbo-stream responses. |
+
+### Multi-step flows (wizards)
+`navigate_to_action` passes `arguments` to a second action's modal — step 1 collects choices, step 2 renders only the relevant fields and performs the work. The second action is usually `self.visible = -> { false }` so it's reachable only through the flow. See the guide's "Build a multi-step flow" for a full two-file example.
+
+### Trigger an action from a link
+To open an action's modal from a field, dashboard card, or partial, call the class's `link_arguments` with a resource instance; it returns `[path, data]` for `link_to`:
+
+```ruby
+path, data = Avo::Actions::City::Update.link_arguments(
+  resource: resource,
+  arguments: { cities: [resource.record.id], render_name: true }
+)
+link_to resource.record.name, path, data: data
+```
+
+### Run on all matching records (select all)
+When an index spans multiple pages, checking "Select all" offers to select **every matching record across all pages**, not just the visible ones. Avo serializes the (encrypted) query and rebuilds it in the action, so `handle`'s `query` covers the whole filtered set. This works out of the box — no code — but see the gotcha below if it silently disables itself.
+
+## Gotchas
+
+- **`query` is always an array.** Even a single-record action gets `[record]`. Use `query.first` for the one-record case; don't call record methods on `query` directly. `records` is an alias.
+- **"My action doesn't show up" is usually the policy.** With Pundit, `act_on?` in the resource's policy gates action visibility (and `authorize` on the action gates it further). Check the policy first. See the **`avo-authorization`** skill.
+- **The modal is a NEW request.** Params from the Index/Show page that opened it are **not** available in `fields`/`handle`. To prefill from the triggering page, parse `request.referer`:
+  ```ruby
+  field :source, as: :hidden, default: -> {
+    URI.parse(request.referer).query.to_s.include?("hey=ya") ? :yes : :no
+  }
+  ```
+- **`reload_records` is Index-only.** It doesn't work on association tables — use `reload` there.
+- **Notification bodies truncate at ~320 characters.** Keep `succeed`/`error` messages short; put long output in a `download` or a redirect.
+- **File downloads need `self.turbo = false`.** Otherwise Turbo intercepts the response and the download won't fire.
+- **Standalone actions need `self.standalone = true`** — otherwise they're disabled when nothing is selected.
+- **Select-all silently disabled?** Query serialization failed. A common cause: a model `normalizes` proc, which raises `TypeError: no _dump_data is defined for class Proc` when a filter hits the normalized attribute. Fix in `config/application.rb`:
+  ```ruby
+  config.active_record.marshalling_format_version = 7.1
+  ```
+- **Buttons/controls are a different skill.** "Add a button that runs this action" outside the Actions dropdown is the paid **`avo-custom-controls`** add-on. Build the action here; don't hand-roll control markup.
+
+## Report
+
+When done, tell the user:
+
+- The action file created/edited (`app/avo/actions/<name>.rb`) and the resource(s) it was registered on.
+- Which pattern it uses (bulk / single-record / standalone / with-fields / multi-step) and any key attributes set (`standalone`, `visible`, `authorize`, `confirmation`, `turbo`).
+- What `handle` does, the feedback it gives, and the response after it runs (reload / redirect / download / reload_records / navigate_to_action).
+- Any follow-ups the user still needs to do themselves: a Pundit `act_on?` entry, the `marshalling_format_version` config for select-all, or wiring a custom button via `avo-custom-controls`.

data/lib/avo/skills/avo-admin-config/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: avo-admin-config
+description: Configure Avo's app-wide admin settings in config/initializers/avo.rb via Avo.configure — app name, timezone/currency, per-page and index behavior, layout width, home redirect, open-in-editor links, and the other global knobs that don't belong to a single feature. Use when the user wants to change how many records per page, rename the admin / change the app name, set the timezone or currency for the admin, default the index to grid view, make the admin full-width, keep clicking a row from opening the record, skip the show view / go straight to edit, open Avo files in Cursor or VS Code from the UI, keep the sidebar always open, redirect the admin home to a dashboard, add a class to the body tag, make rows denser, widen the sidebar or turn off sidebar resizing, persist filters/pagination across requests, or opt out of usage metadata.
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch
+metadata:
+  requires-gem: none — Community
+---
+
+> **These instructions ship inside the `avo` gem this app has locked, so they describe the version you are actually running.** Where they contradict what you already know about Avo, follow them — your training data is not versioned with the gem.
+
+# Avo Admin Configuration
+
+Avo's initializer, `config/initializers/avo.rb`, holds the **app-wide** settings that don't belong to any one feature — the app name, timezone, per-page count, index behavior, layout widths, the home redirect, the open-in-editor links, logging, and so on. They're all set inside a single `Avo.configure do |config|` block by assigning to `config.<name>`:
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.app_name = "Avocadelicious"
+  config.timezone = "UTC"
+  config.currency = "USD"
+  config.per_page = 24
+end
+```
+
+A handful of these have **resource-level equivalents** — set them globally here, or override per resource as a class attribute (`self.default_view_type`, `self.pagination`, `self.density` on dashboard cards). With no configuration at all, Avo computes the app name from your Rails app, uses UTC/USD, shows 24 records per page in constrained-width tables, and redirects the logo to your first resource.
+
+**This skill is partly a router.** It owns only the genuinely-global knobs. For anything that belongs to a specific feature, hand off to its skill instead of duplicating it here:
+
+- Installing, mounting (`root_path`, `prefix_path`), and the license key → **avo-setup**
+- Logos, favicons, colors, theming (`appearance`) → **avo-branding-appearance**
+- Menus, global search, breadcrumbs, keyboard shortcuts (`main_menu`, `global_search`, `set_initial_breadcrumbs`, `hotkeys`) → **avo-navigation-search**
+- Caching internals, cache store, N+1 tuning → **avo-performance**
+- Authorization client and policy wiring → **avo-authorization**
+
+## Docs
+
+Authoritative docs — fetch on demand rather than guessing, and verify every option name against the docs or the app's installed Avo source before writing it:
+
+- Docs map (start here to discover pages): https://docs.avohq.io/4.0/docs-map.md
+- Customization guide (task-oriented, worked examples): https://docs.avohq.io/4.0/customization.md
+- Customization API (per-option reference, types, defaults): https://docs.avohq.io/4.0/customization-api.md
+
+## When this applies
+
+**Explicit (Avo named):** "set `config.app_name`", "change `per_page` in the Avo initializer", "set `default_view_type` to `:grid`", "use `container_width = :full`", "set `resource_default_view = :edit`", "configure `default_editor_url`", "enable `persistence`", "set `body_classes`".
+
+**Implicit (Rails-shaped, no mention of Avo):** "change how many records show per page in the admin", "rename the admin / change the app name in the top bar", "set the timezone/currency the admin displays", "default the admin list to grid/card view", "make the admin full-width", "clicking a row shouldn't open the record", "skip the show page and go straight to edit", "open the admin's source files in Cursor/VS Code from the UI", "keep the sidebar always open / hide the collapse button", "make the sidebar wider by default", "stop people resizing the sidebar", "send people to a dashboard when they open the admin", "add a CSS class to the `<body>` tag", "make the admin rows denser / tighter", "keep my filters and pagination when I navigate away", "stop the admin from phoning home usage stats".
+
+## Common settings
+
+Every option below is a `config.<name>` assignment inside `Avo.configure`. Most accept a literal value or a block/proc evaluated per request (useful for `I18n` lookups or per-user logic).
+
+### Naming and locale
+
+```ruby
+config.app_name = "Avocadelicious"              # navbar label next to the logo
+config.app_name = -> { I18n.t "app_name" }      # block form for dynamic/i18n names
+config.timezone = "UTC"                          # for date/datetime fields
+config.currency = "USD"                          # for currency fields
+config.locale   = "en-US"                        # force Avo's UI locale (default: I18n.default_locale)
+```
+
+`app_name` defaults to the humanized Rails application class name. To replace the single app-name link with a list of navbar links, that's the **header menu** → **avo-navigation-search**.
+
+### Index view behavior
+
+```ruby
+config.per_page = 24                             # default page size (default 24)
+config.per_page_steps = [12, 24, 48, 72]         # options in the per-page picker
+config.via_per_page = 8                          # page size inside has_many association tables
+config.default_view_type = :grid                 # :table (default), :grid, :map, or a custom view type
+config.first_sorting_option = :asc               # direction on first sort click (default :desc)
+config.density = :tight                          # row height: :tight, :normal (default), :relaxed
+config.field_wrapper_layout = :stacked           # label above value everywhere (default :inline)
+config.click_row_to_view_record = false          # stop the whole row linking to Show (default true)
+config.id_links_to_resource = true               # render id fields as links to the record (default false)
+config.cache_resources_on_index_view = false     # disable per-row index caching (default true)
+config.search_debounce = 300                     # ms to wait after typing before searching (default 300)
+config.pagination = { type: :countless }         # global pagination defaults; same keys as self.pagination
+```
+
+`default_view_type`, `pagination`, and `density` (on dashboard cards) also exist as per-resource class attributes — set globally here, override per resource. Row-control placement (`resource_row_controls_config`) lives on the table-view docs.
+
+### Layout
+
+```ruby
+config.container_width = :full                            # one width for all views
+config.container_width = { index: :full, show: :small }   # or per view / group alias
+config.sidebar = {                                        # the sidebar's three knobs, merged over the defaults
+  toggle_visible: false,                                  # hide the collapse button → sidebar stays open on desktop (default true)
+  resizable: false,                                       # remove the drag-to-resize handle (default true)
+  default_width: 320                                      # px the sidebar starts at before a user drags it (default 256)
+}
+config.hide_layout_when_printing = true                   # drop sidebar/navbar/footer when printing
+config.body_classes = "custom-theme compact-layout"       # add classes to <body>; also accepts an Array or a block
+```
+
+`config.sidebar` is a hash merged over `{toggle_visible: true, resizable: true, default_width: 256}`, so set only the keys you change. On desktop the sidebar edge is a drag handle: users resize it and the width persists **per browser** (a cookie, not a user preference). `default_width` sets the starting width and is clamped to `200`–`480` — an unparseable value falls back to `256` rather than clamping to the minimum. Both settings apply at `lg` (1024px) and wider only; below that the sidebar is a full-height overlay at the 256px default. A width the user has dragged to wins over `default_width`. The flat `config.sidebar_toggle_visible = false` still works and writes into `config.sidebar[:toggle_visible]`, but the hash is the canonical home.
+
+`container_width` values are `:large` (default index), `:small` (default show/forms), and `:full`. The hash form accepts individual views (`:index`, `:show`, `:new`, `:edit`, `:create`, `:update`) and group aliases (`:forms`, `:display`, `:single`); a specific key wins over an alias. The `body_classes` block runs in Avo's `ExecutionContext`, so it has `current_user`, `request`, and `params`.
+
+### Navigation home and record flow
+
+```ruby
+config.home_path = "/avo/dashboard"                       # where the logo / "/avo" redirects
+config.home_path = -> { avo_dashboards.dashboard_path(:dashy) }   # block form has route helpers
+config.resource_default_view = :edit                      # skip the Show view; go straight to Edit
+config.alert_dismiss_time = 8000                          # ms before flash alerts auto-dismiss (default 5000)
+```
+
+Pair `home_path` with `set_initial_breadcrumbs` for a cohesive landing (breadcrumbs detail → **avo-navigation-search**). Setting `home_path` also hides the development-only "Get started" sidebar item.
+
+### Editor and development
+
+```ruby
+config.default_editor_url = "vscode://file/%{path}"       # the </> "open in editor" links (dev only)
+config.view_component_path = "app/frontend/components"     # where generated field view_components land
+config.model_generator_hook = false                       # stop `rails g model` from also generating an Avo resource
+```
+
+In `development`, Avo renders a small `</>` icon next to resources, actions, filters, dashboards, cards, and forms; clicking it opens that class's source file via `default_editor_url`, where `%{path}` is the absolute file path. It **defaults to Cursor** (`cursor://file/%{path}`) — switch the scheme for VS Code (`vscode://file/%{path}`), Sublime (`subl://open?url=file://%{path}`), etc.
+
+### Other global knobs
+
+```ruby
+config.set_context do                                     # attach a payload to the global `context` object
+  { params: request.params }
+end
+
+config.persistence = { driver: :session }                # keep association pagination + static filters across requests
+
+config.associations = {                                   # global association defaults (set only what you change)
+  lookup_list_limit: 1000,
+  frames: { loading: :lazy, auto_load_for: 15.minutes }
+}
+
+config.turbo = -> { { instant_click: true } }             # Turbo behavior inside Avo
+config.default_url_options = [:account_id]                # params appended to every generated path (route multitenancy)
+config.logger = -> { ActiveSupport::Logger.new(Rails.root.join("log", "avo.log")) }
+config.exclude_from_status = ["license_key", "ip"]        # items hidden on /avo_private/status (license_key hidden by default)
+config.send_metadata = false                              # opt out of usage metadata (Community licenses only)
+```
+
+## Gotchas
+
+- **`container_width` replaces the Avo-3 booleans.** `config.full_width_container = true` → `config.container_width = :full`; `config.full_width_index_view = true` → `config.container_width = { index: :full }`; `full_width_container = false` → just remove the line. It raises `ArgumentError` on an unknown width or hash key.
+- **`resource_default_view` replaces `skip_show_view`.** The old `config.skip_show_view = true` is now `config.resource_default_view = :edit` (default `:show`). This retargets row links, post-create/update redirects, and association links to Edit.
+- **`persistence: { driver: :session }` can overflow the cookie store.** Rails' default cookie session store is capped at 4096 bytes; many stored pagination + filter states raise `ActionDispatch::Cookies::CookieOverflow`. Move to a scalable session store (Redis, Memcache) before enabling it broadly.
+- **`default_editor_url` defaults to Cursor.** If a user's `</>` icons open Cursor unexpectedly, that's the default — point it at their editor. The icons only render in `development`.
+- **Disable `cache_resources_on_index_view` when fields vary by role.** The index cache key uses the record's `id`/`created_at` and the resource file md5 — **not the current user** — so a resource that shows/hides fields per role (`visibility:`) will serve one user's row layout to another. Turn it off there. For the caching model and cache store, see **avo-performance**; for role-based field visibility, see **avo-authorization**.
+- **Sidebar resizing is a drag-only gesture.** It doesn't satisfy [WCAG 2.2 SC 2.5.7 (Dragging Movements)](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html), so an app working to an AA conformance claim or a VPAT should set `config.sidebar = {resizable: false}`. Related: sidebar labels now truncate with an ellipsis (plus a hover tooltip) instead of wrapping — if a menu relied on long labels wrapping, shorten them or widen the sidebar.
+- **`click_row_to_view_record` is JS-enhanced.** Making a `<tr>` behave as a link isn't native HTML; Avo does it with JavaScript, which can have side effects. Disabling it (`false`) reserves navigation for the explicit row controls.
+- **Verify before writing.** Option names and defaults drift between versions and several were renamed in Avo 4 — check the docs URLs above or the app's installed `lib/avo/configuration.rb` rather than trusting memory.
+
+## Report
+
+When done, tell the user:
+
+- The exact `config.<name>` lines you added or changed in `config/initializers/avo.rb`, and what each does.
+- Any Avo-3 → Avo-4 rename you applied (`container_width`, `resource_default_view`) and the old line it replaced.
+- Follow-ups the change implies: a server restart to reload the initializer; a scalable session store if you enabled `persistence`; disabling `cache_resources_on_index_view` if they gate fields by role.
+- When a setting has a per-resource equivalent (`default_view_type`, `pagination`, `density`), note it so they know they can override it on individual resources.
+- Redirect anything out of scope to the right skill: install/mount/license → **avo-setup**, appearance/theming → **avo-branding-appearance**, menus/search/breadcrumbs/shortcuts → **avo-navigation-search**, caching depth → **avo-performance**, authorization → **avo-authorization**.