avo 4.1.0 → 4.1.2

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

@@ -0,0 +1,186 @@
+---
+name: avo-multitenancy
+description: Scope the Avo admin per tenant — account, team, or organization — so each customer only sees their own data. Covers route-based tenancy (mount Avo under /:tenant_id + config.default_url_options + a set_tenant before_action) and session-based tenancy with an account switcher, all built on the Avo::Current.tenant / tenant_id attributes you populate yourself. Use when the user wants to scope the admin per account/team/org, make each customer see only their own data in the admin, add tenant scoping, build a multi-tenant admin, add an account/tenant switcher, mount the admin under /:account_id, or have the admin switch data based on the current account — including Rails-shaped requests with no mention of Avo like "the admin should switch data based on the current account" or "each client should only see their own records."
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch
+metadata:
+  requires-gem: none — Community (subdomain/multi-URL tenancy needs a special license)
+---
+
+> **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 Multitenancy
+
+Multitenancy adds a layer just below authentication: a signed-in user no longer acts as *themselves* but *on behalf of a tenant* — an `Account`, a `Team`, an `Organization`, whatever you model. The job of this skill is to answer one question on every request: **which tenant is the current user acting for?** — and to make Avo scope its data to it.
+
+The whole thing hangs on two attributes Avo ships on `Avo::Current`: **`tenant_id`** and **`tenant`**. Both are deliberately left empty — Avo never populates them. **There is no `config.tenant` option and no dedicated setting**; you set the values yourself in a `before_action`, and your resources/queries then read `Avo::Current.tenant` to filter. Everything below is a recipe for doing that cleanly, either from the URL (route-based) or from the session (session-based).
+
+Authentication ("who is signed in") is the layer *above* this — that's the **avo-authentication** skill, and it's a prerequisite: `Avo::Current.user` must resolve before you can look up which accounts they belong to.
+
+## Docs
+
+Authoritative docs — fetch on demand rather than guessing, and verify every 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
+- Multitenancy guide: https://docs.avohq.io/4.0/multitenancy.md
+- `Avo::Current` (the `tenant` / `tenant_id` attributes): https://docs.avohq.io/4.0/avo-current.md
+- `config.default_url_options` reference: https://docs.avohq.io/4.0/customization-api.md
+- Acts As Tenant integration (subdomain / row-level): https://docs.avohq.io/4.0/guides/acts_as_tenant_integration.md
+
+License: **Community** (built into every Avo install). One exception: **subdomain / multi-URL tenancy** (e.g. `acct-a.example.com`, `acct-b.example.com`) is one application per URL and needs a special license — reach out to avohq.io. Path-based (`/:tenant_id`) and session-based tenancy on a single URL are Community.
+
+## When this applies
+
+**Explicit (Avo named):** "populate `Avo::Current.tenant` / `tenant_id`", "mount Avo under `/:tenant_id`", "set `config.default_url_options` for multitenancy", "add a `set_tenant` before_action", "scope Avo resources to the current account/team", "build an account switcher for Avo".
+
+**Implicit (Rails-shaped, no mention of Avo):** "scope the admin per account / team / organization", "each customer should only see their own data in the admin", "make the admin multi-tenant", "add tenant scoping", "add an account / tenant switcher", "mount the admin under `/:account_id`", "the admin should switch the data based on the current account", "each client should only see their own records in the admin panel".
+
+Pick the strategy from what the user describes:
+
+- Tenant should live **in the URL** (`/foo/resources/...`, shareable/bookmarkable per tenant, deep links carry the tenant) → **Route-based tenancy**.
+- Tenant should be **remembered per session** and toggled with a switcher, URL unchanged → **Session-based tenancy**.
+- Tenant should be a **subdomain** with row-level scoping via a gem → point at **Acts As Tenant** (special license; see Docs).
+
+## Workflow
+
+First confirm authentication is wired (`Avo::Current.user` resolves — see **avo-authentication**), then read `config/routes.rb` and `config/initializers/avo.rb` to see what exists, and apply only what's missing. In the examples below the tenant model is `Account`; substitute the app's real tenant model (`Team`, `Organization`, …).
+
+### Route-based tenancy
+
+The user hits `https://example.com/foo/...` and everything scopes to the `foo` tenant. Three pieces, all required.
+
+**1. Mount Avo under the tenant scope.** Wrap `mount_avo` in a `scope "/:tenant_id"`:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  scope "/:tenant_id" do
+    mount_avo
+  end
+end
+```
+
+**2. Keep the tenant in every generated URL.** Because Avo now lives under `/:tenant_id`, every path Avo generates must carry that segment or the links drop the tenant and 404. Add it to `config.default_url_options` and Avo appends `params[:tenant_id]` to every path it builds:
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.default_url_options = [:tenant_id]
+end
+```
+
+This is **not optional** — skip it and navigation breaks the moment you click a second link. `default_url_options` also accepts a block (returning an array) when the value must be computed, but the array form is what route-based tenancy needs.
+
+**3. Set the tenant on each request.** Extract the id from `params[:tenant_id]` in a `prepend_before_action`, packaged as a concern and included into `Avo::ApplicationController`:
+
+```ruby
+# app/controllers/concerns/multitenancy.rb
+module Multitenancy
+  extend ActiveSupport::Concern
+
+  included do
+    prepend_before_action :set_tenant
+  end
+
+  def set_tenant
+    Avo::Current.tenant_id = params[:tenant_id]
+    Avo::Current.tenant = Account.find(params[:tenant_id])
+  end
+end
+```
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  # configuration values (including default_url_options from step 2)
+end
+
+Rails.configuration.to_prepare do
+  Avo::ApplicationController.include Multitenancy
+end
+```
+
+Now visiting `https://example.com/foo` sets `Avo::Current.tenant_id` to `"foo"` and `Avo::Current.tenant` to that `Account`. Your resources read `Avo::Current.tenant` to filter records (e.g. scope `query` in the resource, or `default_scope`/`acts_as_tenant` on the model).
+
+### Session-based tenancy
+
+Simpler — the routing is untouched, the tenant is remembered in the session and changed with a switcher.
+
+**1. Set the tenant from the session on each request.** Same concern-included-via-`to_prepare` shape, but read the id from `session` with a sensible fallback:
+
+```ruby
+# app/controllers/concerns/multitenancy.rb
+module Multitenancy
+  extend ActiveSupport::Concern
+
+  included do
+    prepend_before_action :set_tenant
+  end
+
+  def set_tenant
+    Avo::Current.tenant = Account.find(session[:tenant_id] || current_user.accounts.first.id)
+  end
+end
+```
+
+```ruby
+# config/initializers/avo.rb
+Rails.configuration.to_prepare do
+  Avo::ApplicationController.include Multitenancy
+end
+```
+
+**2. Add an account switcher** — a route, a controller that writes the session, and a partial that renders the links:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  put "switch_account/:id", to: "avo/switch_accounts#update", as: :switch_account
+end
+```
+
+```ruby
+# app/controllers/avo/switch_accounts_controller.rb
+class Avo::SwitchAccountsController < Avo::ApplicationController
+  def update
+    # set the new tenant in session
+    session[:tenant_id] = params[:id]
+
+    redirect_back fallback_location: root_path
+  end
+end
+```
+
+```erb
+<%# app/views/avo/_session_switcher.html.erb %>
+<% current_user.accounts.each do |account| %>
+  <%= link_to account.name, switch_account_path(account.id), class: class_names({"underline": session[:tenant_id].to_s == account.id.to_s}), data: {turbo_method: :put} %>
+<% end %>
+```
+
+The switch route is defined in the **main app's** `routes.draw` (not inside a scope), and `Avo::SwitchAccountsController` subclasses `Avo::ApplicationController` so the `set_tenant` before_action and Avo's auth still run. You then render `_session_switcher` somewhere visible in the admin (a custom sidebar / resource tool / view override) — the docs supply the partial but not the mount point, so wire it into wherever the app surfaces admin chrome.
+
+### Subdomain / row-level (Acts As Tenant)
+
+If the ask is subdomain-per-tenant (`sah.example.org`) or row-level DB scoping via the [`acts_as_tenant`](https://github.com/ErwinM/acts_as_tenant) gem, don't hand-roll it — follow the dedicated **Acts As Tenant integration** guide (see Docs). Note the license caveat: more than one URL per app needs a special Avo license.
+
+## Gotchas
+
+- **There is no config option for the tenant.** `Avo::Current.tenant` / `tenant_id` are empty attributes Avo never fills. You *must* set them yourself in a `before_action` — if you're hunting for a `config.tenant =` setting, it doesn't exist. Verified in Avo source: the two attributes carry the comment "here so the user can add them on their own will."
+- **Route-based tenancy without `config.default_url_options = [:tenant_id]` silently breaks navigation.** The first page renders (its URL already has the segment), but every link Avo generates omits the tenant and 404s. This is the single most common route-based mistake. The `customization-api` example uses `[:account_id]` — match the array element to your actual scope param name.
+- **Include the concern via `Rails.configuration.to_prepare`, not a bare `include` at the top of the initializer.** `Avo::ApplicationController` is reloaded in development; a one-time include is lost on the next reload and `set_tenant` stops firing. `to_prepare` re-runs on every reload so the concern survives. See **avo-engine-internals** for why `Avo::Current` and the engine's controllers behave this way.
+- **`Avo::ApplicationController` does not inherit from your app's `ApplicationController`.** App helpers, concerns, and before_actions aren't available inside it. Keep `set_tenant` self-contained (use `params`, `session`, `current_user`, `Avo::Current`); to share real app logic, extend Avo's base controller the supported way — the **avo-controllers** skill.
+- **Prefer `prepend_before_action`.** The tenant must be set *before* any other Avo before_action that might read `Avo::Current.tenant` (authorization scopes, resource queries), so prepend it to run first.
+- **Authentication is a prerequisite.** `current_user` / `Avo::Current.user` must resolve before session-based `set_tenant` can call `current_user.accounts` — a `nil` user raises here. Wire auth first (**avo-authentication**).
+- **Setting the tenant ≠ filtering the data.** These recipes only populate `Avo::Current.tenant`. You still have to *use* it — scope your resources' `query`, add a model `default_scope`, or use `acts_as_tenant` — or every tenant will keep seeing every record.
+- **Handle a missing/invalid tenant.** `Account.find(params[:tenant_id])` raises `RecordNotFound` on a bad or absent segment, and you should also confirm the current user is actually a member of that tenant — otherwise the URL is an authorization hole where anyone can swap the id to view another tenant's admin.
+- **Verify before writing.** Names drift between versions — confirm `default_url_options`, the `Avo::Current` attributes, and `mount_avo` against the docs URLs above or the app's installed Avo source rather than trusting memory.
+
+## Report
+
+When done, tell the user:
+
+- Which files you touched (full absolute paths) — typically `config/routes.rb`, `config/initializers/avo.rb`, `app/controllers/concerns/multitenancy.rb`, and for session-based tenancy `app/controllers/avo/switch_accounts_controller.rb` + `app/views/avo/_session_switcher.html.erb`.
+- Which strategy you implemented (route-based vs session-based) and how the tenant is resolved each request (`params[:tenant_id]` vs `session[:tenant_id]`), plus — for route-based — that `config.default_url_options` is set so links keep the tenant.
+- That `Avo::Current.tenant` / `tenant_id` are now populated, and the explicit next step: **actually scope the data** (resource `query`, model scope, or `acts_as_tenant`) — setting the tenant alone does not filter records.
+- Any gaps left for the user: where to render `_session_switcher`, the membership check guarding against tenant-id tampering, and — if they asked for subdomains — the special-license caveat and the Acts As Tenant guide.
+- Handoffs: **avo-authentication** if `current_user` isn't wired yet; **avo-controllers** if `set_tenant` needs shared app logic; **avo-authorization** to enforce per-tenant record access with policies.

data/lib/avo/skills/avo-navigation-search/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: avo-navigation-search
+description: >-
+  Navigate and search an Avo admin — per-resource search (`self.search`), searching across fields
+  and through associations, search authorization and result limits, breadcrumbs, keyboard
+  shortcuts, and the auto-generated sidebar. Use when the user wants to make a resource
+  searchable, search by email or across several columns, search through an association, authorize
+  or limit search results, change breadcrumbs, add a hotkey, or hide something from the sidebar.
+  The menu editor DSL and the Cmd+K global palette are add-ons and ship their own skills.
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch
+metadata:
+  requires-gem: none — per-resource search, breadcrumbs, hotkeys and the auto sidebar are Community; the menu editor (avo-menu) and global search (avo-advanced_search) ship their own skills
+---
+
+> **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 Navigation & Search
+
+> **Two neighbouring subjects live in their own gems.** The sidebar menu **editor** DSL is `avo-menu`, and the Cmd+K **global** search palette is `avo-advanced_search` — each ships its own skill inside its own gem, pinned to that gem's version. Everything on this page is Community: per-resource search, breadcrumbs, keyboard shortcuts, and the auto-generated sidebar.
+>
+> Re-run the Avo skills loader to see which of those gems this app has. If it reports one missing from `Gemfile.lock`, name the add-on rather than describing a feature the app cannot use.
+
+This skill owns everything about **getting around** an Avo admin and **finding records** in it: the three configurable menus, per-resource search, the global Cmd+K palette, breadcrumbs, and keyboard shortcuts.
+
+Two files do almost all the work:
+
+- **`config/initializers/avo.rb`** — the menus (`config.main_menu`, `config.profile_menu`, `config.header_menu`), the global search hash (`config.global_search`), keyboard-shortcut master switches (`config.hotkeys`), and the starting breadcrumb (`config.set_initial_breadcrumbs`).
+- **`app/avo/resources/<name>.rb`** — per-resource `self.search = { query: … }` (what makes a resource searchable at all), plus `self.hotkey` and `self.visible_on_sidebar` on the resource class.
+
+**Licensing — state this up front, it changes what you can offer:**
+
+- The **menu editor** (`main_menu` / `profile_menu` / `header_menu` DSL) is a **paid add-on** (`avo-menu`). Without it, Avo auto-generates the sidebar from registered resources and you tune the menu only through `self.visible_on_sidebar` / `self.icon` / `self.hotkey` on each resource.
+- **Global search** (the Cmd+K palette) is a **paid add-on** (`avo-advanced_search`). Without it, per-resource `self.search` still gives each resource its own Index search bar.
+- **Per-resource `self.search`, breadcrumbs, and keyboard shortcuts are Community** — always available.
+
+If the user's install lacks the add-on, say so and fall back to the Community path rather than writing DSL that won't load.
+
+## 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
+- Menu editor guide: https://docs.avohq.io/4.0/menu-editor.md — API reference: https://docs.avohq.io/4.0/menu-editor-api.md
+- Search guide: https://docs.avohq.io/4.0/search.md — API reference: https://docs.avohq.io/4.0/search-api.md
+- Breadcrumbs: https://docs.avohq.io/4.0/breadcrumbs.md
+- Keyboard shortcuts: https://docs.avohq.io/4.0/keyboard-shortcuts.md
+- Authorization (the `search?` policy method): https://docs.avohq.io/4.0/authorization.md
+
+## When this applies
+
+**Explicit (Avo named):** "reorder the Avo sidebar", "add a `main_menu` section", "group resources in the Avo menu", "add a `link_to` to our docs in the sidebar", "hide `TeamMembership` from the Avo menu", "add `self.search` to the `User` resource", "set up the Avo global search / Cmd+K", "add a `hotkey` to a menu item", "add breadcrumbs to a custom Avo page", "add a sign-out link to the Avo profile menu".
+
+**Implicit (product-shaped, no mention of Avo):** "organize the admin sidebar into sections", "group my models under headings", "put a billing link in the admin nav", "let non-admins not see the audit-log resource in the menu", "add a command palette / Cmd+K to the admin", "make users searchable in the admin", "let support staff look up a customer by email", "search across all records at once", "jump to Orders with a keyboard shortcut", "collapse the sidebar groups by default", "add a way to sign out from the profile dropdown".
+
+**Boundary:** `self.search` lives on the resource file, so it overlaps the resources vertical — **this skill owns search.** For the resource file's *other* attributes (title, icon, includes, `visible_on_sidebar` semantics) cross-link **avo-resources**. For the `search?` / `index?` policy methods cross-link **avo-authorization**. For picking menu-item icon names cross-link **avo-menu-icons**; for menu/appearance styling cross-link **avo-branding-appearance**.
+
+## Workflow
+
+1. **Read `config/initializers/avo.rb`.** Does it already define `config.main_menu`? If yes, the menu editor is in play (edit the DSL). If no, the sidebar is auto-generated — either propose adding `config.main_menu` (needs the `avo-menu` add-on) or tune per-resource attributes.
+2. **Classify the request** as *menus* (§Menus), *search* (§Search), *breadcrumbs*, or *shortcuts*. Many requests are one of these squarely; a few ("command palette that searches everything") touch both menus and search.
+3. **Confirm the license** for what you're about to write — menu DSL and global search both require paid add-ons (see above). Fall back to Community equivalents when the add-on isn't present.
+4. **Fetch the matching doc page** from the Docs list before writing DSL, and verify option names against it or the installed source.
+5. **Edit the right file**, preserving surrounding indentation and style. Menus and global search → the initializer; `self.search` / `self.hotkey` → the resource file; breadcrumbs on a custom page → that page's controller action.
+6. **Report** what you changed and any add-on / policy / model prerequisite still needed (see §Report).
+
+---
+
+## Menus
+
+The sidebar menu **editor** — `config.main_menu`, `config.profile_menu`, sections, groups, sub-items, visibility rules — is the `avo-menu` add-on, and its instructions ship inside that gem. Re-run the Avo skills loader and read the **avo-menu** skill from the path it prints. If the loader reports the gem missing from `Gemfile.lock`, this app does not have it; say so rather than writing DSL that will not render, and use the Community path below.
+
+### Community fallback (no `avo-menu`)
+
+Without the menu editor the sidebar is auto-generated; control it from each resource file: `self.visible_on_sidebar = false` to hide, `self.icon` for the icon, `self.hotkey` for a jump shortcut. (These attributes belong to **avo-resources**; the sidebar effect is the navigation part.)
+
+## Search
+
+Search is configured **once per resource** via `self.search`, and that one `query:` proc powers every surface: the Index search bar, the global Cmd+K palette, searchable association pickers, and kanban card pickers. **Without `self.search`, a resource has no Index search bar and is skipped by global search.**
+
+```ruby
+# app/avo/resources/user.rb
+class Avo::Resources::User < Avo::BaseResource
+  self.search = {
+    query: -> { query.ransack(first_name_cont: q, last_name_cont: q, m: "or").result(distinct: false) }
+  }
+end
+```
+
+- `q` — the stripped search string. (`params[:q]` for the raw value.)
+- `query` — the base scope **with authorization scopes already applied**; always search off it.
+- Avo recommends [ransack](https://github.com/activerecord-hackery/ransack) but it isn't mandatory — the proc can run any query. If using ransack, add `gem "ransack"`.
+
+### Search by email / across fields, and through associations
+
+```ruby
+# Widen the fields searched:
+query.ransack(first_name_cont: q, last_name_cont: q, email_cont: q, m: "or").result(distinct: false)
+```
+
+To match on an associated model's columns, join it and prefix the ransack keys with the association name (assuming `Application belongs_to :client`):
+
+```ruby
+class Avo::Resources::Application < Avo::BaseResource
+  self.search = {
+    query: -> {
+      query.joins(:client).ransack(
+        id_eq: q,
+        name_cont: q,
+        client_email_cont: q,
+        client_phone_number_cont: q,
+        m: "or"
+      ).result(distinct: false)
+    }
+  }
+end
+```
+
+### Different query per surface (`search_type`)
+
+One proc can branch on `search_type` to run a wider search in the global palette than in an association picker:
+
+```ruby
+self.search = {
+  query: -> {
+    case search_type
+    when :global       # navbar Cmd+K — widest, includes email
+      query.ransack(first_name_cont: q, last_name_cont: q, email_cont: q, m: "or").result(distinct: false)
+    when :association  # picker — tightest
+      query.ransack(first_name_cont: q).result(distinct: false)
+    else               # :resource — the Index search bar
+      query.ransack(first_name_cont: q, last_name_cont: q, m: "or").result(distinct: false)
+    end
+  }
+}
+```
+
+`search_type` is `:resource`, `:global`, or `:association`. It is **injected only by the paid search layer** (`avo-advanced_search`) — on a Community-only install the local is undefined and referencing it raises. The kanban card picker doesn't inject it (or a `q` local) either. Guard with `defined?(search_type)` when a Community install or the kanban picker might hit the proc; the kanban picker reads the term from `params[:q]`.
+
+### Authorize search
+
+Search obeys the `search?` policy method — if it returns false the resource is dropped from global search and its Index search bar is hidden.
+
+```ruby
+class UserPolicy < ApplicationPolicy
+  def search?
+    true
+  end
+end
+```
+
+(If `search?` is already used for something else, alias it via `config.authorization_methods = { search: "avo_search?" }`.) See **avo-authorization**.
+
+### Limit results
+
+Avo caps each resource's results at `config.search_results_count` (default `8`) — **unless your proc already calls `.limit()`, in which case your limit wins**. The dedicated global results page ignores the cap.
+
+```ruby
+config.search_results_count = 16   # global, in the initializer
+# or per resource: query.ransack(name_cont: q).result(distinct: false).limit(current_user.admin? ? 30 : 10)
+```
+
+### Global search (Cmd+K palette)
+
+One palette spanning every resource is the `avo-advanced_search` add-on, and its instructions ship inside that gem — read the **avo-advanced-search** skill from the path the loader prints. Everything above on this page is Community and works without it.
+
+### Custom (non-ActiveRecord) providers
+
+Back search with Elasticsearch etc. by returning an **array of hashes** from `query:` instead of a relation:
+
+```ruby
+query: -> {
+  [
+    { _id: 1, _label: "Record One", _url: "https://example.com/1", _description: "…", _avatar: "https://…", _avatar_type: :rounded }
+  ].first(config_or_number)   # array results are NOT auto-capped — cap yourself
+}
+```
+
+---
+
+## Breadcrumbs (Community)
+
+Avo builds a breadcrumb trail automatically for resource views. Two things you'd configure:
+
+**Change where every trail starts** — `config.set_initial_breadcrumbs` in the initializer (runs in controller context; use the `avo` proxy for engine paths):
+
+```ruby
+# config/initializers/avo.rb
+config.set_initial_breadcrumbs do
+  add_breadcrumb title: "Home", path: avo.root_path, icon: "tabler/outline/home"
+  add_breadcrumb title: "Team", path: avo.resources_teams_path
+end
+# Leave the block empty to start trails with no initial crumbs.
+```
+
+**Add crumbs on a custom page** — call `add_breadcrumb` in the page's controller action:
+
+```ruby
+class Avo::ToolsController < Avo::ApplicationController
+  def custom_tool
+    add_breadcrumb title: "Custom tool", path: avo.custom_tool_path   # omit path: for the current (unlinked) crumb
+  end
+end
+```
+
+`add_breadcrumb` options: `title:` (required), `path:` (omit → plain text), `icon:`, `initials:`, `avatar:`. Internal Avo links need the `avo.` prefix (Rails engine path rules).
+
+## Keyboard shortcuts (Community)
+
+All shortcuts are on by default; each bound control shows a small `<kbd>` badge, and `?` opens the reference modal for the current page. Shortcuts never fire while typing in an input/textarea/select/contenteditable.
+
+```ruby
+# config/initializers/avo.rb
+config.hotkeys = {
+  enabled: true,          # master switch
+  show_key_badges: true   # inline <kbd> badges next to buttons/links
+}
+```
+
+Built-in highlights: `Cmd/Ctrl+K` global search · `Shift+\` toggle sidebar · `B` go back · `/` focus Index search · `C` new record · `A` actions menu · `V T` / `V G` / `V M` switch table/grid/map view. (Full table on the keyboard-shortcuts doc page.)
+
+Add your own on any control with a `data-hotkey` attribute (re-bound on every Turbo navigation):
+
+```html
+<a href="/avo/posts/new" data-hotkey="c">New post</a>
+<button data-hotkey="Meta+Enter Control+Enter">Save</button>  <!-- space = platform alternatives -->
+```
+
+Jump-to-menu-item shortcuts go through the menu `hotkey:` option, or `self.hotkey` on the resource class (see §Menus).
+
+---
+
+## Gotchas
+
+- **Menu editor and global search are paid add-ons.** Writing `config.main_menu` or relying on the Cmd+K palette on an install without `avo-menu` / the global-search add-on won't work — check first, and fall back to per-resource `self.visible_on_sidebar` / `self.search` (both Community).
+- **`all_resources` respects `index?` authorization.** A resource missing from the menu is usually a policy returning false, not a bug.
+- **Menu `action` items must be standalone.** `self.standalone = true` is required (the menu has no selected record); others are skipped with a log warning. Top-level `action` also needs `resource:`; nested it's inherited.
+- **`profile_menu` and `header_menu` render only `link_to`.** `resource`, `dashboard`, `action`, etc. are silently ignored there. The profile menu adds sign-out for you.
+- **`icon:` isn't universal.** It works on `section` and individual items, **not** on `group` or on sub-items nested inside a `resource` block.
+- **Ransack v4+ needs an allowlist.** Add `ransackable_attributes` (and often `ransackable_associations`) to any model you search, or the query raises.
+- **`search_type` is undefined on Community-only installs and in the kanban picker.** It's injected by the paid search layer for the index/global/association surfaces only. Guard with `defined?(search_type)`; the kanban picker reads `params[:q]` and detects the board via `params[:for_kanban_board]`.
+- **Custom array-result providers aren't auto-capped.** `config.search_results_count` only applies to relations without their own `.limit()` — cap arrays yourself with `.first(N)`.
+- **`.limit()` in your `query:` proc always wins** over `config.search_results_count`.
+- **`search_on_type` can't be a lambda.** Any Proc is truthy, so it behaves as `true`; use a plain boolean. (`enabled` and `navigation_section` do accept lambdas.)
+- **`self.description` and search `item` titles can render raw HTML** in adjacent surfaces — never interpolate user-editable content (stored-XSS). See **avo-resources**.
+- **Internal breadcrumb/menu paths need the `avo.` prefix** (Rails engine path helper rules), e.g. `avo.resources_teams_path`.
+
+## Report
+
+When done, tell the user:
+
+- Which file(s) you edited (full paths) — the initializer, which resource file(s), and/or which custom-page controller.
+- What you changed: menu structure (sections/groups/items added, reordered, or hidden), which `self.search` procs you added and the fields/associations they cover, global-search settings, breadcrumbs, or hotkeys.
+- Any **add-on** the change depends on (`avo-menu` for the menu DSL, `avo-advanced_search` for Cmd+K global search) and whether it appears to be installed.
+- Any **prerequisite still needed**: a policy method (`index?` for `all_resources`, `search?` for search — see **avo-authorization**), `ransackable_attributes` on the searched model, `self.standalone = true` on a menu action, or `gem "ransack"`.
+- Note when you fell back to a Community path (per-resource `visible_on_sidebar` / `self.search`) because an add-on wasn't present.

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

@@ -0,0 +1,190 @@
+---
+name: avo-performance
+description: Make the Avo admin fast and fix stale or wrong cached rows — pick and force a cache store (config.cache_store, Solid Cache), control index row caching (cache_resources_on_index_view, cache_hash), and bust stale caches. Use when the user wants to speed up the admin, cache admin index rows, or fix caching side-effects — both Avo phrasings ("speed up the Avo admin", "why is the Avo index slow", "set up Solid Cache for Avo", "override cache_hash on a resource", "disable cache_resources_on_index_view") and Rails-shaped ones without Avo ("the admin is slow / the index page takes forever", "speed up the admin", "admin rows don't update after I change a related record", "stale data on the admin list", "admin links point to the old mount path after I moved it", "cache admin index rows"). For N+1 on the index — the single biggest slowness cause — see the self.includes option in avo-resources.
+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 Performance & Caching
+
+Avo leans on the application's cache to speed up the admin, most visibly by caching **each row on the Index view** (and each item on the Grid view). This skill covers the two levers that decide how fast an Avo screen feels: **eliminating N+1 queries** (the biggest cause of a slow index, handled by the sibling **avo-resources** skill) and **caching index rows correctly** so they're fast *and* accurate. The flip side of caching is stale rows — a record that still shows the old value after an associated record changed, or a link that still points at the old mount path — and most requests that land here are really "the admin is slow" or "the admin shows stale data." Cache config is global, in `config/initializers/avo.rb`; per-row cache keys are a resource method (`cache_hash`) at `app/avo/resources/<name>.rb`.
+
+## 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
+- Performance & caching: https://docs.avohq.io/4.0/performance.md
+- `cache_hash` reference: https://docs.avohq.io/4.0/resources-api.md#cache_hash
+- Solid Cache: https://github.com/rails/solid_cache
+
+## When this applies
+
+**Explicit (Avo named):** "speed up the Avo admin", "cache the Avo index rows", "why is the Avo index slow", "set `config.cache_store` / use Solid Cache with Avo", "turn off `cache_resources_on_index_view`", "override `cache_hash` on the `User` resource", "Avo keeps showing a stale cached row".
+
+**Implicit (Rails-shaped, no mention of Avo):** "the admin is slow", "the admin index page takes forever to load", "speed up the admin", "cache the admin index rows", "the admin list shows stale data", "admin rows don't update after I change a related record", "a comment count on the admin doesn't refresh when I add a comment", "admin links point to the old mount path after I moved the admin", "I changed where the admin is mounted and its links are broken".
+
+If the complaint is purely load time (not staleness), **check N+1 first** — see step 1. Caching hides N+1 on warm requests but the cold request and any cache miss stay slow.
+
+## Workflow
+
+### 1. Rule out N+1 before touching cache config
+
+The most common reason an Avo index is slow is N+1 queries from association or attachment fields, **not** missing cache. Caching only masks it on cache hits. Eager-load on the resource before anything else — this is the **avo-resources** skill's `self.includes` / `self.attachments`:
+
+```ruby
+# app/avo/resources/post.rb
+class Avo::Resources::Post < Avo::BaseResource
+  self.includes = [:user, :tags]     # associations shown on Index
+  self.attachments = [:cover_photo]  # Active Storage attachments on Index
+end
+```
+
+To *see* where time goes, optionally turn on ViewComponent instrumentation (step 6) — but only in development, it's a perf cost itself.
+
+### 2. Understand which cache store Avo is using
+
+Avo picks its store automatically:
+
+- **Production** → `Rails.cache`, **unless** that's a `MemoryStore` or `NullStore`; then Avo falls back to `:file_store` at `tmp/cache`.
+- **Every other environment** (development, test, custom) → always `:file_store` at `tmp/cache`.
+
+So on a fresh app with the default `MemoryStore`, Avo is silently on the file store in production. That's usually the thing to fix — move to a real shared store (step 4).
+
+Check what's live from the Rails console:
+
+```ruby
+Avo.cache_store.class   # what Avo actually uses
+Rails.cache.class       # what the app is configured with
+```
+
+### 3. Force a specific cache store (optional)
+
+Override Avo's choice with `config.cache_store`. It takes a store **object**, or a lambda when you want different stores per environment:
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.cache_store = ActiveSupport::Cache.lookup_store(:solid_cache_store)
+
+  # lambda form — evaluated per request, handy for env-specific stores:
+  config.cache_store = -> { ActiveSupport::Cache.lookup_store(:solid_cache_store) }
+end
+```
+
+### 4. Set up Solid Cache (recommended production store)
+
+Avo integrates cleanly with [Solid Cache](https://github.com/rails/solid_cache) — a DB-backed store that's shared across all Puma workers and processes. Install:
+
+```bash
+bundle add solid_cache
+bin/rails solid_cache:install:migrations
+bin/rails db:migrate
+```
+
+Point Rails at it (Avo will then use it automatically, since it's `Rails.cache`):
+
+```ruby
+# config/environments/production.rb
+config.cache_store = :solid_cache_store
+```
+
+You only need `config.cache_store` in the Avo initializer (step 3) if you want Avo on a *different* store than the rest of the app.
+
+### 5. Control index row caching
+
+Row caching is on by default everywhere except development. Two knobs:
+
+```ruby
+# config/initializers/avo.rb
+config.cache_resources_on_index_view = false   # disable row caching entirely
+```
+
+- **`cache_resources_on_index_view`** — Boolean. Default: enabled in every environment except development. Turn it off when cached rows would leak the wrong content between requests — most importantly when fields are **shown/hidden per role** (see the Gotchas, and the **avo-admin-config** and **avo-authorization** skills).
+
+- **`cache_hash(parent_record)`** — the resource method that computes each row's cache key. The default is `[record, file_hash]` (plus the parent record in association tables). `file_hash` is an MD5 of the **resource file and its policy file**, so editing either one auto-busts every cached row for that resource — but a change to the *data* or to an *association* does not, unless you tell it to (step 6 below and the next section). Override it per resource to fold more into the key:
+
+```ruby
+# app/avo/resources/user.rb
+class Avo::Resources::User < Avo::BaseResource
+  def fields
+    # ...
+  end
+
+  def cache_hash(parent_record)
+    # include record.post so the row re-renders when the post changes
+    result = [record, file_hash, record.post]
+    result << parent_record if parent_record.present?
+    result
+  end
+end
+```
+
+### 6. Log ViewComponent render times (development only)
+
+Avo's UI is ViewComponents; to profile them like partials, enable instrumentation and a log subscriber:
+
+```ruby
+# config/application.rb or config/environments/development.rb
+config.view_component.instrumentation_enabled = true
+```
+
+```ruby
+# config/initializers/view_component.rb
+module ViewComponent
+  class LogSubscriber < ActiveSupport::LogSubscriber
+    define_method :'!render' do |event|
+      info do
+        message = +"  Rendered #{event.payload[:name]}"
+        message << " (Duration: #{event.duration.round(1)}ms"
+        message << " | Allocations: #{event.allocations})"
+      end
+    end
+  end
+end
+
+ViewComponent::LogSubscriber.attach_to :view_component
+```
+
+Keep this in development only — it measurably slows down rendering, so don't leave it on in production.
+
+## Fixing stale / incorrect cached rows
+
+Because each Index row is cached, a row can lag reality. The usual cases:
+
+- **Row doesn't update when an associated record changes** (e.g. a `Post` row showing a stale comment count after a `Comment` is added). Two fixes, pick one:
+  - Add `touch: true` on the child's `belongs_to`, so writing the child touches the parent and moves it out of its cache key:
+    ```ruby
+    class Comment < ApplicationRecord
+      belongs_to :post, touch: true
+    end
+    ```
+  - Or fold the association into the resource's `cache_hash` (step 5) so the key changes when the association changes.
+
+- **Links point at the old mount path after you move the admin** (`root_path` change). Cached rows cache the control/`belongs_to`/`record_link` URLs too, and a `root_path` change does **not** invalidate those keys. Clear the cache once with `Rails.cache.clear`, or add `root_path` to the resource's `cache_hash`.
+
+These are ordinary Rails caching side-effects, not Avo bugs — the same reasoning applies to fragment caching anywhere.
+
+## Gotchas
+
+- **N+1 first, cache second.** A slow index is almost always missing `self.includes`/`self.attachments` (the **avo-resources** skill), not missing cache. Caching only helps warm requests; the cold request stays slow. Fix the queries before tuning the store.
+- **Don't use `MemoryStore` in production.** It isn't shared across Puma workers/processes, so each worker holds a different cache. Avo rejects it and silently falls back to `:file_store` at `tmp/cache` — which is why a "cached" prod app can still feel slow. Use a shared store (Solid Cache, Redis, Memcached).
+- **Stale rows when associations change.** A row won't re-render on an associated change by itself → add `belongs_to …, touch: true` on the child, or add the association to the resource's `cache_hash`.
+- **Moving the admin doesn't bust cached links.** Changing `root_path` leaves cached row URLs pointing at the old mount path → `Rails.cache.clear` once, or add `root_path` to `cache_hash`.
+- **Editing the resource or policy file *does* bust the cache automatically** — `file_hash` (part of the default `cache_hash`) hashes both files. So config changes take effect immediately; only *data*/*association* changes need the fixes above.
+- **Turn off row caching when fields depend on the viewer.** If you show/hide or change fields **by role** (per-user visibility, authorization-driven fields), a row cached for one user can be served to another. Set `config.cache_resources_on_index_view = false` — the flag is listed in the **avo-admin-config** skill, and role-based field visibility is the **avo-authorization** skill's territory.
+- **ViewComponent logging is a dev tool.** Instrumentation slows rendering; enable it to profile, then remove it — never leave it on in production.
+- **Verify before writing.** Option names and defaults drift between versions — confirm against the docs URLs above or the app's installed Avo source (`Avo.cache_store`, `Avo.configuration.cache_resources_on_index_view`) rather than trusting memory.
+
+## Report
+
+When done, tell the user:
+
+- What you diagnosed — N+1 vs. cold-cache vs. staleness — and how you confirmed it (e.g. `Avo.cache_store.class`, ViewComponent timings, missing `self.includes`).
+- Which files you changed (full paths): the initializer (`config.cache_store`, `config.cache_resources_on_index_view`), any resource `cache_hash` override, model `touch: true`, Solid Cache install/migration.
+- The cache store now in effect and why (default pick vs. forced), plus any commands run (`bundle add`, `solid_cache:install:migrations`, `db:migrate`, `Rails.cache.clear`).
+- For staleness fixes: exactly what now busts the cache (touch, `cache_hash` addition, or a one-time clear) and any change still needed elsewhere (add `self.includes` in avo-resources, disable row caching for role-based fields, run pending migrations).
+- Anything left for the user: restart/redeploy so initializer changes load, warm the cache, or verify the store is reachable in production.