avo 4.1.0 → 4.1.2

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

@@ -0,0 +1,168 @@
+---
+name: avo-associations
+description: >-
+  Wire Active Record relationships into Avo resources as association fields (`field :x, as:
+  :belongs_to | :has_one | :has_many | :has_and_belongs_to_many`) inside `def fields`, including
+  polymorphic and `has_many :through` relations, type-to-search pickers, extra join-table fields
+  at attach time, and nested create-in-form. Use when the user wants to link one record to another
+  or surface related records — in Avo terms ("add a belongs_to field", "show a has_many panel",
+  "make the association searchable", "polymorphic belongs_to", "has_many through with
+  attach_fields", "use_resource / attach_scope") or in plain Rails terms ("a post belongs to a
+  user", "show all of a user's orders on their page", "connect users and teams with a join table",
+  "the user dropdown is too long — make it type-to-search", "a comment can belong to a post or a
+  project", "add extra fields when attaching a member to a team", "create the related record right
+  from the form", "link these two models in the admin").
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch
+metadata:
+  requires-gem: none — Community; searchable association pickers need avo-advanced_search, which ships its own skill
+---
+
+> **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 Associations
+
+> **Searchable pickers live in their own gem.** Turning a long association dropdown into a type-to-search field is `avo-advanced_search`, whose skill ships inside that gem. Declaring and configuring association fields — everything on this page — is Community.
+>
+> Re-run the Avo skills loader before recommending a searchable picker; if the gem is absent from `Gemfile.lock`, `searchable: true` falls back to a plain select with no error.
+
+Avo turns Rails [Active Record associations](https://guides.rubyonrails.org/association_basics.html) into fields. You declare one line in the resource's `def fields` and Avo renders it per view: a `belongs_to` becomes a link on Show/Index and a dropdown (or search picker) on the forms; `has_one`, `has_many`, and `has_and_belongs_to_many` render as panels below the record's fields with attach / detach / create controls.
+
+These fields live in `app/avo/resources/<model>.rb`, the same place as every other field. This skill is where relationship-shaped requests land — "a post belongs to a user", "show a user's orders", "connect users and teams", "make the picker type-to-search". For non-association fields (text, number, select, file…) use `avo-fields`; for creating or configuring the resource shell itself use `avo-resources`; for who can attach/detach/create use `avo-authorization`.
+
+**Docs** (fetch on demand with WebFetch — verify option names and edge cases against the live pages, don't guess):
+- Docs map: https://docs.avohq.io/4.0/docs-map.md
+- Overview & STI: https://docs.avohq.io/4.0/associations.md
+- Belongs to: https://docs.avohq.io/4.0/associations/belongs_to.md
+- Has one: https://docs.avohq.io/4.0/associations/has_one.md
+- Has many (+ `:through`, `attach_fields`): https://docs.avohq.io/4.0/associations/has_many.md
+- Has and belongs to many: https://docs.avohq.io/4.0/associations/has_and_belongs_to_many.md
+- Searchable associations (guide): https://docs.avohq.io/4.0/associations/searchable.md
+- Searchable associations (API): https://docs.avohq.io/4.0/associations/searchable-api.md
+- Authorization (association buttons & policies): https://docs.avohq.io/4.0/authorization.md#associations
+
+## When this applies
+
+Use this skill when the request is about **one record relating to another**, in any phrasing:
+
+- Direct Avo asks: "add a `belongs_to`", "show a `has_many` panel", "make it searchable", "polymorphic `belongs_to`", "`has_many :through` with `attach_fields`".
+- Rails-shaped asks without Avo words: "a post belongs to a user", "a user has one profile", "show all of a user's orders on their page", "connect users and teams with a join table".
+- Product-shaped asks: "the author dropdown is too long — let me type to search", "a comment can belong to a post *or* a project", "add a rating when I attach a member to a team", "create the related record right from the form".
+
+If the request is about a scalar attribute (a string, a number, a file, an enum select) rather than a link between records, it's an `avo-fields` task, not this one.
+
+## Workflow
+
+1. **Confirm the Rails association exists.** Association fields are a *view* of an Active Record association — Avo does not create it. Check the model (`app/models/<model>.rb`) for the matching `belongs_to` / `has_one` / `has_many` / `has_and_belongs_to_many` (and the inverse on the other model). If it's missing, add it to the model first, and set `inverse_of` on both sides.
+
+2. **Pick the field type** from the [Association types](#association-types) table — it mirrors the Rails macro one-to-one.
+
+3. **Add the field** to `def fields` in `app/avo/resources/<model>.rb`:
+
+   ```ruby
+   # app/avo/resources/post.rb
+   class Avo::Resources::Post < Avo::BaseResource
+     def fields
+       field :id, as: :id
+       field :title, as: :text
+
+       field :user, as: :belongs_to      # Post belongs_to :user
+       field :comments, as: :has_many    # Post has_many :comments
+     end
+   end
+   ```
+
+   The field name is the **association name**, not a column — `field :user` maps to `belongs_to :user` (the `user_id` column is implicit). A `has_many` field's counterpart lives on the *other* resource: `Post has_many :comments` is `field :comments, as: :has_many` on the Post resource, and the reciprocal `field :post, as: :belongs_to` on the Comment resource.
+
+4. **Layer options** as needed (see [Key options](#key-options)) — scope the attach list, point at a different resource, make it searchable, allow nested creation, etc.
+
+5. **Verify buttons follow the target resource's policy.** Attach/detach/create/destroy visibility comes from the *target* resource's Pundit policy, using **plural** method names (see [Gotchas](#gotchas)). If a button must appear or disappear, that's an `avo-authorization` change, not an option here.
+
+## Association types
+
+| Rails association on the model | Avo field declaration |
+| --- | --- |
+| `belongs_to :user` | `field :user, as: :belongs_to` |
+| `belongs_to :commentable, polymorphic: true` | `field :commentable, as: :belongs_to, polymorphic_as: :commentable, types: [::Post, ::Project]` |
+| `has_one :admin` | `field :admin, as: :has_one` |
+| `has_many :comments` | `field :comments, as: :has_many` |
+| `has_many :members, through: :memberships` | `field :members, as: :has_many, through: :memberships` |
+| `has_and_belongs_to_many :teams` | `field :teams, as: :has_and_belongs_to_many` |
+
+`has_one`, `has_many`, and `has_and_belongs_to_many` render only on the **Show** view by default; add `show_on: :edit` to also surface them on the edit form (still rendered with the show-view component — for editable-in-form use `nested`).
+
+## Key options
+
+Most options are shared across the association fields; a handful are type-specific. Confirm exact behavior against the linked docs before relying on an edge case.
+
+**Shared by all association fields**
+
+| Option | What it does |
+| --- | --- |
+| `searchable` | Replaces the `<select>` / attach picker with a type-as-you-search input. **Paid add-on** + needs a query source — see [Searchable](#searchable-associations). |
+| `attach_scope` | `-> { query.non_admins }` — scopes the records offered in the **attach modal / dropdown** (locals: `query`, `parent`). Note: does *not* filter the listed rows of a `has_many`/HABTM — use `scope` or a Pundit policy scope for that. |
+| `use_resource` | Render/redirect through a different resource, e.g. `use_resource: Avo::Resources::PhotoComment` (class or string). |
+| `name` | Overrides the panel/label text (`has_many`, HABTM). Also achievable via [field i18n](https://docs.avohq.io/4.0/i18n.md). |
+| `description` | Sub-title text under the panel title. Keep it cheap under `loading: :manual` — the lambda runs on the placeholder too. |
+| `scope` | `-> { query.approved }` — scopes the **rows displayed** in a `has_many`/HABTM table (locals: `query`, `parent`, `resource`, `parent_resource`). |
+| `loading` | `:manual` defers the frame fetch behind a **Load** button (heavy associations); `:lazy` is the default. |
+| `linkable` | Makes the panel title open the association table on its own page. |
+| `reloadable` | Adds a reload icon on the panel (boolean or a lambda gated on e.g. `current_user.admin?`). |
+| `nested` | Create/edit the related record inline in the parent form. **Requires the `avo-nested` gem.** `nested: true` = `{ on: :forms }`; `limit:` caps rows on `has_many`/HABTM. |
+| `attach_using` | `:checkbox_list` renders the attach modal as a multi-select checkbox list instead of a single-select dropdown (`has_many`, HABTM). |
+| `discreet_pagination` | Hides pagination chrome when there's only one page. |
+| `hide_search_input` / `hide_filter_button` | Hide the search box / filters button on the association table. |
+| `link_to_child_resource` | STI: link rows to the child resource instead of the parent (see [Gotchas](#gotchas)). |
+| `for_attribute` | Point a differently-named field at the same association (declare it twice with different scopes/names). |
+
+**`belongs_to`-only**
+
+| Option | What it does |
+| --- | --- |
+| `polymorphic_as:` + `types:` | Turns the field polymorphic. `polymorphic_as: :commentable, types: [::Post, ::Project]` — the two must be used together, matching a `belongs_to :commentable, polymorphic: true` on the model. Renders two dropdowns: pick the type, then the record. |
+| `polymorphic_help` | Help text for the **type** dropdown (use `help:` for the record dropdown). |
+| `can_create` | `true`/`false` — show/hide the "create new" link on the form. Overridden by the target resource's `create?` policy (see [Gotchas](#gotchas)). |
+| `allow_via_detaching` | Keeps the field editable when you reached the record *through* that association (which otherwise disables it). |
+| `link_to_record` | `true` makes the Index cell link to the current row's record instead of the associated one. |
+
+### `has_many :through` and `attach_fields`
+
+For a join model with its own columns, expose those columns **at attach time** with `attach_fields` (a lambda that declares fields, evaluated against the join model):
+
+```ruby
+# Team has_many :members, through: :memberships — Membership has a `role` column
+field :members,
+  as: :has_many,
+  through: :memberships,
+  attach_fields: -> {
+    field :role, as: :text
+  }
+```
+
+The extra fields render inside the attach modal and their values persist on the join row. `attach_fields` **only persists on `has_many :through`** — it exists but is a no-op on a plain `has_many` / HABTM. If the through model is polymorphic, add the type as a hidden field: `field :membership_type, as: :hidden, default: "TheType"`.
+
+### Searchable associations
+
+Turning a long `belongs_to` / `has_many` picker into a type-to-search field 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. Without the gem `searchable: true` falls back to a plain select with no error, so check before recommending it.
+
+## Gotchas
+
+- **Set `inverse_of` on the model association.** Avo relies on it to resolve the reciprocal; missing it causes wrong/empty attach lists and save bugs. Set it on both sides.
+- **The Rails association must exist first.** Adding `field :x, as: :has_many` does nothing if the model has no `has_many :x`.
+- **`has_*` fields are hidden on Edit by default.** Add `show_on: :edit` to surface them on the form. For editing the related record *in* the form (not just displaying it), use `nested` — which needs the `avo-nested` gem.
+- **Attach/detach/create/destroy buttons come from the *target* resource's Pundit policy**, and the method names are **plural, matching the association name**: `attach_users?`, `detach_users?`, `create_users?`, `destroy_users?`, `view_users?`, `show_users?` — *not* the singular `detach_user?`. This is the #1 "why isn't my button showing" cause. Cross-link `avo-authorization`.
+- **`can_create: true` is still vetoed by the policy.** If the target resource's `create?` returns `false`, no create link appears regardless of `can_create`.
+- **A `belongs_to` field is disabled when you arrive through that same association.** Editing a Comment reached via a Post's comments panel disables the `post` field. Set `allow_via_detaching: true` to re-enable it.
+- **`polymorphic_as` and `types` are a pair** — using one without the other raises. `types` is an array of model classes (`[::Post, ::Project]`), matching a `polymorphic: true` `belongs_to`.
+- **`attach_scope` does not filter listed rows**, only the attach picker. To hide rows from a `has_many`/HABTM table, use `scope` or a Pundit policy scope.
+- **STI child resources must set `self.model_class`.** When a parent class and STI children share a table, give each child resource `self.model_class = "SuperUser"` so Avo maps it correctly. To route association rows / index clicks to the child resource instead of the parent, use `self.link_to_child_resource = true` on the parent resource or `link_to_child_resource:` on the field.
+- **Searchable can look "broken" but be misconfigured** — no query source means an empty picker, not an error. And it's a paid add-on.
+
+## Report
+
+After wiring the association, tell the user:
+
+- The field(s) added and to which resource file (absolute path), with the `as:` type.
+- Any **model** change you made or that's still required (the Rails association, `inverse_of`), since Avo only *renders* the association.
+- Options applied and why (searchable, scope, nested, `attach_fields`, polymorphic, etc.).
+- Any **paid add-on** dependency introduced (`searchable` → advanced-search; `nested` → `avo-nested` gem) and whether it still needs installing / a query source.
+- If button visibility matters, a pointer that attach/detach/create/destroy are governed by the target resource's **plural** policy methods — hand off to `avo-authorization` if changes are needed.

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

@@ -0,0 +1,193 @@
+---
+name: avo-authentication
+description: Tell Avo who the current user is, gate access to the admin, and wire up roles, the sidebar profile widget, and the sign-out link — all in config/initializers/avo.rb and routes.rb. Use when the user wants to set config.current_user_method, integrate Devise or the Rails 8 auth scaffold, restrict Avo with authenticate_with or a route-level `authenticate :user`, add lightweight is_admin?/is_developer? roles, or fix the profile/sign-out UI — including Rails-shaped requests with no mention of Avo like "put the admin behind login", "require login to see the admin", "only let admins into the admin panel", "the admin shows 'Avo user' instead of my name", "add a logout button to the admin", "show the signed-in user's avatar in the sidebar", or "the admin doesn't know who's logged in".
+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 Authentication
+
+Authentication in Avo answers one question: **who is the current user, and are they allowed in the door?** It is two separate jobs that people constantly conflate — (1) telling Avo how to fetch the signed-in user (`current_user_method`), and (2) restricting who can reach the admin at all (`authenticate :user` in the router, or `authenticate_with` in the initializer). Avo makes no assumptions about your auth stack: Devise, the Rails 8 scaffold, a homegrown session — any of them work once you point Avo at the right method. Almost everything here lives in `config/initializers/avo.rb`, with the door-gating half in `config/routes.rb`.
+
+**Setting the current user is a prerequisite for everything else** — the profile widget, the sign-out link, roles, and (most importantly) **authorization policies**. A `current_user` that returns `nil` is the single most common reason Pundit/policy rules silently misbehave. If the user is doing authorization work, do this first. Authentication is "who gets in the door"; **avo-authorization** is "what they can do once inside" — this skill is only the former.
+
+## Docs
+
+Authoritative docs — fetch on demand rather than guessing, and verify every config 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
+- Authentication guide: https://docs.avohq.io/4.0/authentication.md
+- Rails 8 auth scaffold guide: https://docs.avohq.io/4.0/guides/rails-authentication-scaffold.md
+- Authorization (the sibling concern): https://docs.avohq.io/4.0/authorization.md
+
+License: **Community** (built into every Avo install — no paid add-on required).
+
+## When this applies
+
+**Explicit (Avo named):** "set `config.current_user_method`", "hook Avo up to Devise", "get Avo working with the Rails 8 authentication scaffold", "restrict Avo to admins", "use `authenticate_with`", "add `is_admin?` / `is_developer?` roles", "customize the Avo sign-out path", "fix the Avo profile widget".
+
+**Implicit (Rails-shaped, no mention of Avo):** "put the admin behind login", "require login to see the admin", "only let admins into the admin panel", "the admin shows 'Avo user' instead of my name", "the admin doesn't know who's logged in", "add a logout button to the admin", "show the signed-in user's avatar in the sidebar", "my admin panel is wide open to anyone", "policies aren't being enforced in the admin" (usually a missing `current_user` — start here, then hand to avo-authorization).
+
+## Workflow
+
+Read `config/initializers/avo.rb` first to see what's already configured, then apply only what's missing. Identify the app's auth stack (grep the Gemfile / `ApplicationController`): Devise, the Rails 8 scaffold (`Current.user`, an `Authentication` concern), or something custom.
+
+### 1. Tell Avo who `current_user` is
+
+Avo does **not** guess your auth provider — out of the box `current_user` returns `nil`. Set `config.current_user_method` to a method name (a Symbol) or a block.
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  # Devise: the method is literally current_user
+  config.current_user_method = :current_user
+
+  # Another provider (e.g. a current_admin helper):
+  # config.current_user_method = :current_admin
+
+  # Or a block — needed when the user comes off a global like the
+  # Rails 8 scaffold's Current.user, not a controller helper method:
+  # config.current_user_method do
+  #   Current.user
+  # end
+end
+```
+
+- **Devise** → `:current_user` (or `:current_admin`, matching your Devise model).
+- **Custom helper method** → the Symbol name of that method.
+- **A thread-local / global** (Rails 8 scaffold, `Current` attributes) → the block form returning `Current.user`.
+
+### 2. Gate the door — who is allowed to reach Avo
+
+Setting `current_user` identifies the user but does **not** keep anyone out. Two ways to actually restrict access:
+
+**A. Route-level (preferred with Devise).** Wrap the mount in Devise's `authenticate` in `config/routes.rb`. Nothing inside is even routable unless the user is signed in:
+
+```ruby
+# config/routes.rb — require any signed-in user
+authenticate :user do
+  mount_avo
+end
+
+# Only a subset of users (e.g. admins). The lambda receives the user:
+authenticate :user, ->(user) { user.admin? } do
+  mount_avo
+end
+```
+
+**B. Initializer-level via `authenticate_with`.** A block run as a `before_action` inside Avo's controller — use it when you're not on Devise or want the check in the initializer:
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.authenticate_with do
+    # Runs inside Avo's ApplicationController — see the gotcha below.
+    redirect_to main_app.root_path unless session[:user_id] == 1
+  end
+end
+```
+
+⚠️ **`authenticate_with` runs inside Avo's own `ApplicationController`, which does NOT inherit from your app's `ApplicationController`.** Your app's helper methods, concerns, and `before_action`s are **not** available in this block — calling `authenticate_admin_user!` or a custom helper will raise `NoMethodError`. Write the check inline against primitives that *are* available (`session`, `request`, `params`, `main_app` URL helpers). To share real app logic instead of inlining it, extend Avo's base controller — that's the **avo-controllers** skill.
+
+### 3. Rails 8 authentication scaffold — it counts as "custom auth"
+
+The Rails 8 `bin/rails generate authentication` scaffold is **not** plug-and-play; Avo treats it as custom auth and it needs three explicit steps (full walkthrough in the scaffold guide above):
+
+1. `config.current_user_method { Current.user }` — the scaffold stores the user on `Current.user`.
+2. `config.sign_out_path_name = :session_path` — the scaffold signs out via `SessionsController`.
+3. Eject Avo's `ApplicationController` and include the scaffold's `Authentication` concern there, then `prepend_before_action :require_authentication` (and `delegate :new_session_path, to: :main_app`). This is the door-gating step — steps 1–2 alone identify the user but don't lock anyone out.
+
+If the user mentions the Rails 8 scaffold (or you see `Current.user` + an `Authentication` concern instead of Devise), point them at the scaffold guide and don't try to shortcut step 3.
+
+### 4. Lightweight roles — `is_admin?` and `is_developer?`
+
+Avo ships two deliberately minimal roles, resolved by calling a method on the `current_user`:
+
+- `is_admin?` → the user can reach the private **Avo Status** page (`/avo_private/status`, under your mount path) and sees its sidebar link in production.
+- `is_developer?` → same Status-page access, **plus** full backtraces on non-validation errors (e.g. an API call that blows up during save) instead of a generic "Something went wrong".
+
+Check them yourself anywhere with `Avo::Current.user_is_admin?` / `Avo::Current.user_is_developer?`. Point Avo at differently-named predicate methods via the initializer:
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.is_admin_method = :is_admin?          # default
+  config.is_developer_method = :is_developer?  # default
+  # e.g. config.is_admin_method = :staff?
+end
+```
+
+**These roles are not a general authorization system** — they only gate the Status page and developer backtraces. Restricting which resources/actions a user can see is authorization (policies): the **avo-authorization** skill.
+
+### 5. The sidebar profile widget
+
+The sidebar footer shows a small profile widget for the object returned by `current_user_method`, reading three things off it by duck-typing:
+
+- **Name** — calls `name`; if absent/blank, falls back to `email`, then `email_address` (the Rails 8 scaffold's column), and finally the literal **"Avo user"**. So "the admin shows 'Avo user' instead of my name" means the user object responds to none of `name`/`email`/`email_address` — add a `name` (or `email`) method to the model.
+- **Avatar** — calls `avatar`, used as the photo's `src`. Add an `avatar` method returning an image URL to "show the signed-in user's avatar in the sidebar".
+- **Title** — calls `avo_title`, shown under the name. Define `avo_title` on the user model for a role/label line.
+
+```ruby
+# app/models/user.rb — give the widget something to show
+class User < ApplicationRecord
+  def name = "#{first_name} #{last_name}"
+  def avatar = gravatar_url          # any image URL
+  def avo_title = admin? ? "Administrator" : "Member"
+end
+```
+
+### 6. The sign-out link
+
+The sign-out item lives in the sidebar footer's three-dots menu. Avo shows it automatically if your app responds to `destroy_user_session_path` (the Devise default). Otherwise it's hidden until you name the path. Two knobs:
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  # Customize just the "user" segment: User -> current_user gives
+  # destroy_current_user_session_path. current_admin -> destroy_current_admin_session_path.
+  config.current_user_resource_name = :current_user   # default: "user"
+
+  # Or specify the whole path helper outright (wins over the above if both set):
+  # config.sign_out_path_name = :logout_path          # Rails 8 scaffold: :session_path
+end
+```
+
+So "add a logout button to the admin" = pick whichever of these matches an existing route helper in `bin/rails routes`. The link fires a `DELETE`, so the target route must accept it.
+
+## Key options
+
+| Option | Where | Does | Tiny example |
+| --- | --- | --- | --- |
+| `config.current_user_method` | initializer | How Avo fetches the signed-in user (Symbol or block) | `config.current_user_method = :current_user` |
+| `authenticate :user do … end` | routes.rb | Gate the mount to signed-in users (Devise) | `authenticate :user, ->(u){ u.admin? } { mount_avo }` |
+| `config.authenticate_with` | initializer | `before_action` check inside Avo's controller | `config.authenticate_with { redirect_to "/" unless … }` |
+| `config.is_admin_method` | initializer | Predicate for the admin role | `config.is_admin_method = :staff?` |
+| `config.is_developer_method` | initializer | Predicate for the developer role | `config.is_developer_method = :is_developer?` |
+| `Avo::Current.user_is_admin?` | anywhere | Read the admin role at runtime | `redirect_to root_path unless Avo::Current.user_is_admin?` |
+| `config.current_user_resource_name` | initializer | "user" segment of the sign-out path | `config.current_user_resource_name = :current_admin` |
+| `config.sign_out_path_name` | initializer | Full sign-out path helper (wins over the above) | `config.sign_out_path_name = :logout_path` |
+| `name` / `email` / `avatar` / `avo_title` | user model | Feed the sidebar profile widget | `def avo_title = "Administrator"` |
+
+## Gotchas
+
+- **`current_user` is the prerequisite for authorization.** If it returns `nil`, policies silently misbehave — a user with no identity fails or skips every rule in confusing ways. When "policies aren't working", check `current_user_method` first, *then* go to **avo-authorization**.
+- **Identifying the user ≠ locking the door.** `current_user_method` only tells Avo *who* someone is; it does not keep anyone out. You still need `authenticate :user` (routes) or `authenticate_with` (initializer). It's easy to wire up `current_user` and leave the admin wide open.
+- **`authenticate_with` can't see your app's controller.** Avo's `ApplicationController` does not inherit from the app's `ApplicationController`, so app helper methods/concerns are unavailable inside the block — write the logic inline, or extend Avo's controller via **avo-controllers**.
+- **Rails 8 scaffold is custom auth.** It needs all three steps (current user via `Current.user`, `sign_out_path_name = :session_path`, and ejecting the controller to `include Authentication` + `prepend_before_action :require_authentication`). Steps 1–2 without step 3 leave the admin unguarded.
+- **Roles are minimal by design.** `is_admin?` / `is_developer?` gate only the `/avo_private/status` page and developer backtraces — they are **not** resource-level authorization. Don't reach for them to hide records or actions; that's policies.
+- **"Avo user" in the widget** means the user object responds to none of `name` / `email` / `email_address`. Add one of those methods to the model, not any Avo config.
+- **Sign-out hidden?** The path helper must actually exist and accept `DELETE`. Confirm with `bin/rails routes` before setting `sign_out_path_name` / `current_user_resource_name`; `sign_out_path_name` wins if both are set.
+- **Verify before writing.** Config names drift between versions — check the docs URLs above or the app's installed Avo source (`Avo::Configuration`) rather than trusting memory.
+
+## Report
+
+When done, tell the user:
+
+- Which files you touched (full paths) — typically `config/initializers/avo.rb`, and possibly `config/routes.rb`, an ejected `app/controllers/avo/application_controller.rb`, or the user model.
+- How Avo now resolves `current_user` (Devise `:current_user`, a custom method, or a `Current.user` block), and how the door is gated (route-level `authenticate :user` vs `authenticate_with`) — or flag explicitly if the admin is **not** gated yet.
+- Any roles configured (`is_admin_method` / `is_developer_method`) and what they unlock (Status page, developer backtraces) — noting they are not general authorization.
+- Any profile-widget or sign-out changes (methods added to the model, `current_user_resource_name` / `sign_out_path_name`).
+- Next steps: if this was groundwork for restricting resources/actions, hand off to **avo-authorization** (policies now that `current_user` is set); if `authenticate_with` needs real app logic, hand off to **avo-controllers**; if on the Rails 8 scaffold, confirm all three guide steps are done.

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

@@ -0,0 +1,74 @@
+---
+name: avo-aware
+description: >-
+  Map a Rails change onto the Avo admin surface it affects, and route the edit to the skill that
+  owns it. Read this after the Avo skills loader has decided a model change has an admin dimension
+  — a new or changed column, a new model, an enum or status column, a new association, or a
+  capability like "admins can approve orders". Carries the Rails-change-to-Avo-surface routing
+  table and the column-type-to-field-type mapping for this Avo version. Does not decide whether
+  Avo is relevant; the loader gates that.
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch
+metadata:
+  requires-gem: none — dispatcher; the target skill states its own gem
+---
+
+> **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.
+
+# Map a Rails change onto the Avo admin
+
+The Avo skills loader has already confirmed this app uses Avo and that the change at hand has an admin dimension. This skill answers the next two questions: **which admin surface** the change maps to, and **which skill owns** that surface.
+
+Do the Rails change first, then propose the admin delta and ask before writing any Avo file. Never own the Avo edit here — route it.
+
+## Routing table
+
+| Rails change | Avo surface to add | Skill to apply |
+| ------------ | ------------------ | -------------- |
+| New column | A `field` on the resource (infer `as:` from the column type) | `avo-fields` |
+| New model | Generate the Avo resource | `avo-resources` |
+| New enum / state column | A badge or select field **and** a filter — often also a state-transition action | `avo-fields` + `avo-filters` + `avo-actions` |
+| New capability (*"admins can approve X"*) | An action **and** the Pundit policy method that authorizes it | `avo-actions` + `avo-authorization` |
+| New association | An association field | `avo-associations` |
+| *"only show active records by default"* | A default scope on the resource | `avo-filters` |
+| *"let admins reorder these"* | `self.ordering` on the resource | `avo-record-reordering` |
+
+---
+
+## Column-type → field mapping
+
+When a new column becomes a field, infer the `as:` option from the migration column type:
+
+| Column type | Avo field `as:` |
+| ----------- | --------------- |
+| `string` | `:text` |
+| `text` | `:textarea` (or `:trix` / rich text for long-form content) |
+| `integer`, `decimal`, `float` | `:number` (use `:money` for currency amounts) |
+| `boolean` | `:boolean` |
+| `date` | `:date` |
+| `datetime`, `timestamp` | `:date_time` |
+| enum / fixed value set | `:select`, `:badge`, or `:status` |
+| `references` / `belongs_to` | `:belongs_to` |
+| `has_many` / `has_one` association | `:has_many` / `:has_one` |
+| `json`, `jsonb` | `:key_value` (or `:code` for freeform structured data) |
+| Active Storage attachment | `:file` (single) / `:files` (multiple) |
+
+These are defaults, not laws. Let the semantics of the column win — a `string` holding an email is better as a text field with an email pattern; a `text` column holding Markdown is better as rich text. When you propose the field in the confirm step, name the `as:` you'll use so the user can redirect it.
+
+---
+
+## Docs
+
+Whenever a delegated edit needs current API details, pull them from the Avo docs map so the authoring reflects the installed version rather than stale memory:
+
+**`https://docs.avohq.io/4.0/docs-map.md`** — an index of every Avo 4 docs page and its headings, with links. Fetch it, then follow the link to the specific page (fields, resources, actions, filters, associations, authorization) the vertical skill needs.
+
+---
+
+## Report
+
+When you're done, tell the user both halves plainly:
+
+- **The Rails change you made** — the migration/model/enum/association you wrote.
+- **The Avo change you proposed or made** — which admin surface, which field/filter/action/policy, and which vertical skill handled it. If the user declined the Avo change, say that the admin was left untouched so nothing is silently out of sync.
+
+Keep it to a few lines. The user should be able to see, at a glance, that the model and its admin surface still agree.