avo 4.1.0 → 4.1.2

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

@@ -0,0 +1,273 @@
+---
+name: avo-resources
+description: Generate an Avo CRUD resource from a Rails model and configure resource-level behavior in `app/avo/resources/<name>.rb` plus its controller. Use when the user wants to generate an Avo resource, add a model to the admin panel, expose a table in the admin, set a resource's title/description/icon/cover/avatar or discreet info, fix ActionDispatch::MissingController, avoid N+1 with includes, tune sort/pagination/index query, build an array (non-DB) resource, or map multiple resources to one model.
+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 Resources
+
+An Avo **resource** turns one Rails model into a full CRUD admin interface — index, show, new, edit, delete — configured from a single Ruby file at `app/avo/resources/<name>.rb`. Think of it as the admin-side counterpart to the model: the model defines the data, the resource defines how Avo displays and manages it. Every resource is a class like `Avo::Resources::Post < Avo::BaseResource`, and **each resource must be paired with a controller** at `app/controllers/avo/<name>s_controller.rb` (e.g. `Avo::PostsController < Avo::ResourcesController`). The generator creates both for you. Resource-level options are class attributes (`self.title`, `self.includes`, …) declared at the top of the file; the fields themselves go in `def fields`, and associations are just fields too — those two are documented in the sibling **avo-fields** and **avo-associations** skills, not here.
+
+## 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
+- Resources guide: https://docs.avohq.io/4.0/resources.md — API reference: https://docs.avohq.io/4.0/resources-api.md
+- Cover & avatar: https://docs.avohq.io/4.0/cover-and-avatar.md
+- Discreet information: https://docs.avohq.io/4.0/discreet-information.md
+- Array resource: https://docs.avohq.io/4.0/array-resource.md
+- Custom errors / validation display: https://docs.avohq.io/4.0/custom-errors.md
+
+## When this applies
+
+**Explicit (Avo named):** "generate/create an Avo resource", "add a resource for `Order`", "configure the `Post` resource", "set the resource title/description/icon", "add a cover photo / avatar to the resource", "make an array resource", "register two resources for one model", "STI resource".
+
+**Implicit (Rails-shaped, no mention of Avo):** "add the `Invoice` model to the admin", "expose the `orders` table in the admin panel", "show these records in Avo but they don't come from a table", "the admin is showing the wrong resource for `User`", "I get `ActionDispatch::MissingController` when I open a resource", "the index is doing N+1 queries", "sort the admin list by `position`", "let admins look up records by slug instead of id", "the admin count query is too slow on a huge table".
+
+## Workflow
+
+### 1. Generate the resource (and its controller)
+
+For an existing model, generate the resource directly. **This also auto-generates the paired controller** — the resource generator invokes `avo:controller` for you:
+
+```bash
+bin/rails generate avo:resource post
+```
+
+That writes `app/avo/resources/post.rb` and `app/controllers/avo/posts_controller.rb`. If the model already has columns and associations, matching `field` lines are filled in automatically.
+
+Other generation modes:
+
+```bash
+# One resource + controller for every ActiveRecord model in the app
+bin/rails generate avo:resource --model-class post   # secondary resource on the Post model → sets self.model_class = "Post"
+bin/rails generate avo:all_resources                 # scans app/models, skips abstract/PORO/form objects
+bin/rails generate avo:resource Galaxy::Planet       # namespaced → app/avo/resources/galaxy/planet.rb + Avo::Galaxy::PlanetsController
+bin/rails generate avo:resource Movie --array        # in-memory (non-AR) resource, see step 6
+```
+
+When you scaffold the model itself, the Avo resource **and** controller are generated alongside the standard Rails files:
+
+```bash
+bin/rails generate model car make:string mileage:integer          # also creates Avo::Resources::Car + Avo::CarsController
+bin/rails generate model car make:string mileage:integer --skip-avo-resource  # opt out
+```
+
+**MissingController gotcha:** every resource needs its controller. If the controller file is missing (deleted, or the resource was hand-written), opening the resource raises `ActionDispatch::MissingController`. Generate the missing one:
+
+```bash
+bin/rails generate avo:controller post
+```
+
+To make generated controllers inherit from a shared base (e.g. one that adds authentication), pass `--parent-controller` on either generator, or set it once in the initializer:
+
+```bash
+bin/rails g avo:resource city --parent-controller Avo::BaseResourcesController
+```
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.resource_parent_controller = "Avo::BaseResourcesController" # default: "Avo::ResourcesController"
+end
+```
+
+### 2. Fill in fields and associations
+
+The generated file has a `def fields` block. Adding, ordering, and configuring fields — and association fields like `belongs_to`/`has_many` — is the job of the **avo-fields** and **avo-associations** skills. Don't re-derive that here; a minimal resource looks like:
+
+```ruby
+# app/avo/resources/post.rb
+class Avo::Resources::Post < Avo::BaseResource
+  self.includes = []
+
+  def fields
+    field :id, as: :id
+    field :name, as: :text
+    field :body, as: :textarea
+    field :user, as: :belongs_to   # ← see avo-associations
+  end
+end
+```
+
+### 3. Set the record's display identity
+
+Avo guesses a record's display name from `name`, `title`, then `label`, falling back to `id`. Override with `self.title` (a Symbol pointing at an attribute/getter, or a block with `record`/`resource`):
+
+```ruby
+class Avo::Resources::Comment < Avo::BaseResource
+  self.title = :slug
+  # or a computed block:
+  self.title = -> { ActionView::Base.full_sanitizer.sanitize(record.body).truncate(30) }
+end
+```
+
+Add a message under the resource name with `self.description`, the sidebar icon with `self.icon`, and an image with `self.avatar` (small, on show/forms) or `self.cover` (banner):
+
+```ruby
+class Avo::Resources::User < Avo::BaseResource
+  self.description = "These are the users of the app."
+  self.icon = "tabler/outline/user"
+  self.avatar = { source: :avatar, visible_on: [:show, :forms] }
+  self.cover  = { source: :cover_photo, size: :md, visible_on: [:show] }
+end
+```
+
+- `self.description` is rendered as **raw HTML** — never feed it user-editable data (stored-XSS risk). A block gets `record`, `resource`, `view`, `current_user`, `params`.
+- `self.cover`/`self.avatar` were named `cover_photo`/`profile_photo` in Avo 3. A **Symbol** `source:` renders nothing for unpersisted (new) records — use a block if you want a placeholder on `new`/`index`.
+
+Surface small metadata (timestamps, id, a badge/link) next to the title without spending a field, via `self.discreet_information`:
+
+```ruby
+class Avo::Resources::Post < Avo::BaseResource
+  self.discreet_information = [
+    :timestamps,
+    { as: :badge, text: -> { record.published_at ? "Published" : "Draft" } }
+  ]
+end
+```
+
+### 4. Tune index performance and behavior
+
+Eager-load associations and attachments to kill N+1 on the index:
+
+```ruby
+class Avo::Resources::Post < Avo::BaseResource
+  self.includes = [:user, :tags]        # associations, Index view
+  self.attachments = [:cover_photo]     # Active Storage attachments, Index view
+  # self.single_includes / self.single_attachments do the same on Show/Edit only
+end
+```
+
+Control the default sort, drop a model `default_scope` on index, or teach Avo to find records by something other than `id`:
+
+```ruby
+class Avo::Resources::Task < Avo::BaseResource
+  self.default_sort_column = :position
+  self.default_sort_direction = :asc            # :asc | :desc (default :desc)
+  self.index_query = -> { query.unscoped }      # receives `query`, returns modified query
+end
+
+class Avo::Resources::Post < Avo::BaseResource
+  # For slug/custom to_param lookups. `id` is an Array in batch contexts (bulk actions) → return a collection there.
+  self.find_record_method = -> {
+    id.to_i == 0 ? query.find_by!(slug: id) : query.find(id)
+  }
+end
+```
+
+FriendlyId is detected automatically (no `find_record_method` needed); prefixed_ids and hashid-rails work out of the box. On huge tables, skip the count with `self.pagination = { type: :countless }`.
+
+### 5. Control the save flow and error display
+
+```ruby
+class Avo::Resources::Comment < Avo::BaseResource
+  self.confirm_on_save = true          # ask before persisting
+  self.after_create_path = :index      # :show (default) | :edit | :index
+  self.after_update_path = :edit
+  # self.devise_password_optional = true  # Devise: allow updating a user without a password
+end
+```
+
+Validation and errors need **no Avo config** — Avo runs your model's validations on every write. Anything you add via `errors.add` stops the action and shows the message:
+
+- `errors.add(:age, "must be over 18.")` → inline under the `age` field.
+- `errors.add(:base, "…")` (or an error whose attribute has no field on the form) → alert banner at the top.
+- Non-validation exceptions during save/destroy (FK constraint on delete, `after_save` failure) are caught, added as a `:base` alert, and shown gracefully instead of 500-ing. Developers additionally see the backtrace (gated on `Avo::Current.user_is_developer?`).
+
+### 6. Array (non-database) resources
+
+For structured data that isn't backed by a table, generate with `--array`. The class extends `Avo::Resources::ArrayResource` and returns data from `records` (array of hashes, AR objects, an `ActiveRecord::Relation`, or `StoreModel` instances):
+
+```ruby
+# app/avo/resources/movie.rb
+class Avo::Resources::Movie < Avo::Resources::ArrayResource
+  def records
+    [
+      { id: 1, name: "The Shawshank Redemption", release_date: "1994-09-23" },
+      { id: 2, name: "The Godfather", release_date: "1972-03-24" }
+    ]
+  end
+
+  def fields
+    field :id, as: :id
+    field :name, as: :text
+    field :release_date, as: :date
+  end
+end
+```
+
+Array resources are **Beta**: sorting is not supported, and the array is rebuilt on every request (cache inside `records` if it gets heavy). For external-API-backed data, prefer an [HTTP Resource](https://docs.avohq.io/4.0/http-resource.md).
+
+### 7. Sidebar, shortcuts, external links, and multiple resources per model
+
+```ruby
+class Avo::Resources::TeamMembership < Avo::BaseResource
+  self.visible_on_sidebar = false      # hide from the auto-generated menu (not the menu editor)
+  self.hotkey = "g m"                  # keyboard shortcut to the Index view
+  self.external_link = -> { main_app.team_membership_path(record) }  # button to a public page
+end
+```
+
+When **two resources map to the same model**, Avo picks one alphabetically wherever it needs a default (associations, links) — often the wrong one. Pin the default with `model_resource_mapping`, and point specific associations elsewhere with `use_resource` (an avo-associations concern):
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.model_resource_mapping = { "User": "Avo::Resources::User" }
+end
+```
+
+For STI, send index clicks to the child record with `self.link_to_child_resource = true` on the parent resource; set `self.model_class` on any resource whose model can't be inferred from the class name.
+
+## Key options
+
+| Option | Does | Tiny example |
+| --- | --- | --- |
+| `self.title` | Record display name | `self.title = :name` |
+| `self.description` | Message under the name (raw HTML!) | `self.description = "App users."` |
+| `self.icon` | Sidebar icon | `self.icon = "tabler/outline/user"` |
+| `self.avatar` / `self.cover` | Small photo / banner | `self.cover = { source: :cover_photo, size: :md }` |
+| `self.discreet_information` | Metadata by the title | `self.discreet_information = :timestamps` |
+| `self.model_class` | Model when not inferable / secondary resource | `self.model_class = "Delayed::Job"` |
+| `self.includes` / `self.attachments` | Eager-load on Index (N+1) | `self.includes = [:user, :tags]` |
+| `self.default_sort_column` / `_direction` | Index sort | `self.default_sort_column = :position` |
+| `self.index_query` | Base Index query (drop default_scope) | `self.index_query = -> { query.unscoped }` |
+| `self.find_record_method` | Lookup by slug/custom id | `-> { query.find_by!(slug: id) }` |
+| `self.pagination` | Skip count on big tables | `self.pagination = { type: :countless }` |
+| `self.confirm_on_save` | Confirm dialog before save | `self.confirm_on_save = true` |
+| `self.after_create_path` / `_update_path` | Post-save redirect | `self.after_create_path = :index` |
+| `self.visible_on_sidebar` / `self.hotkey` | Menu presence / shortcut | `self.visible_on_sidebar = false` |
+| `self.external_link` | Button to a public URL | `-> { main_app.post_path(record) }` |
+| `self.link_to_child_resource` | STI: jump to child on click | `self.link_to_child_resource = true` |
+| `config.buttons_on_form_footers` | Save/Back in form footer (initializer, global) | `config.buttons_on_form_footers = true` |
+
+Search (`self.search`), grid/map view types, record reordering, and i18n live on their own docs pages — reach for the docs map when a request touches those.
+
+## Gotchas
+
+- **Every resource needs a controller.** A missing controller → `ActionDispatch::MissingController` on open. Generate it with `bin/rails g avo:controller <name>`. The resource generator does this automatically; hand-written resources don't.
+- **`self.description` is raw HTML.** Never interpolate user-editable content into it — stored XSS. Same care with `title:` in discreet-information tooltips (sanitize HTML there).
+- **Cover/avatar renamed in Avo 4.** It's `self.cover` / `self.avatar` now, not `cover_photo` / `profile_photo`. A Symbol `source:` shows nothing for unpersisted records — use a block for a placeholder.
+- **Two resources, one model → wrong one wins.** Avo resolves the default alphabetically. Set `config.model_resource_mapping` and/or `use_resource:` on associations.
+- **Secondary / namespaced / oddly-named resources need `self.model_class`** (or the matching namespace) or Avo can't infer the model. Namespaced resources whose namespace matches the model's namespace infer automatically.
+- **Array resources are Beta:** no sorting, and `records` re-runs every request. Cache inside `records` for large sets, or move to an HTTP Resource.
+- **`find_record_method` in batch contexts:** `id` arrives as an Array for bulk actions — return a collection (`query.where(...)`) in that branch, not a single record.
+- **`visible_on_sidebar` only affects the auto-generated menu.** If the app uses the menu editor, control visibility in its `visible` block instead.
+- **Don't re-invent fields/associations here.** Field DSL is the avo-fields skill; `belongs_to`/`has_many`/`use_resource` is avo-associations.
+- **Verify before writing.** Option names drift between versions — check the docs URLs above or the app's installed Avo source rather than trusting memory.
+
+## Report
+
+When done, tell the user:
+
+- Which resource file(s) and controller file(s) you created or edited (full paths), and the generator command(s) run.
+- The model each resource maps to, and any `self.model_class` / `model_resource_mapping` you set to disambiguate.
+- The resource-level options you configured (title, includes, sort, pagination, etc.) and why.
+- Anything still needed for the resource to work: run pending migrations, generate a missing controller, define fields (avo-fields) or associations (avo-associations), or add a policy if authorization is enabled.
+- Note when a resource is an array/Beta resource or has multiple resources per model, so the user knows the limitations.

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

@@ -0,0 +1,288 @@
+---
+name: avo-setup
+description: Install Avo, mount it in `config/routes.rb`, authenticate the private gem server, and set the license key. Use when the user wants to install Avo, add an admin panel to a Rails app, mount the admin at a path/scope/nested path/subdomain (e.g. `/backoffice`, `admin.myapp.com`), add paid Avo add-on gems (`avo-dashboards`, `avo-dynamic_filters`, `avo-kanban`, …), fix a `403 Forbidden` pulling a private or paid Avo gem, can't bundle the paid gem, set the gem-server token on Heroku/Hatchbox/GitHub Actions/Docker/Kamal, deploy the admin when the gem won't install, add or wire a license key, fix an admin that says unlicensed or shows a license-timeout badge, or append custom routes inside the Avo engine.
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch
+metadata:
+  requires-gem: none — this skill installs `avo` plus any paid add-on gems
+---
+
+> **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 Setup
+
+Getting Avo into a Rails app is four moving parts: **install** the right gems, **authenticate** the private gem server if any are paid, **mount** the engine in `config/routes.rb`, and **license** it for production. Avo ships as a family of gems — the `avo` Community gem is free on rubygems.org; each paid feature is its own add-on gem (`avo-dashboards`, `avo-dynamic_filters`, `avo-kanban`, …) served from Avo's private server at [`packager.dev`](https://packager.dev) and needs a Gem Server Token to bundle. One `mount_avo` call in the routes file mounts Avo and every engine it registers, so a subdomain, a scope, or a nested path is a routing detail on that single call. This skill covers install → gem-server auth → mount → license, plus appending your own routes inside the engine. What each per-app knob in `config/initializers/avo.rb` does (`app_name`, `per_page`, `container_width`, …) belongs to the **avo-admin-config** skill; gating who can reach the admin by wrapping `mount_avo` in `authenticate :user do…end` is **avo-authentication**; deep license/gem-auth failure diagnosis is **avo-troubleshoot**.
+
+## 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
+- Installation: https://docs.avohq.io/4.0/installation.md
+- Routing / mounting: https://docs.avohq.io/4.0/routing.md
+- Gem server authentication: https://docs.avohq.io/4.0/gem-server-authentication.md
+- Licensing: https://docs.avohq.io/4.0/licensing.md
+- License troubleshooting: https://docs.avohq.io/4.0/license-troubleshooting.md
+
+## When this applies
+
+**Explicit (Avo named):** "install Avo", "add the Avo gem", "add an Avo add-on gem (`avo-dashboards`, `avo-kanban`, …)", "mount Avo at `/admin`", "put Avo on a subdomain", "set the Avo license key", "add my Gem Server Token", "`BUNDLE_PACKAGER__DEV`", "append a route inside the Avo engine".
+
+**Implicit (Rails-shaped, no mention of Avo):** "add an admin panel to my Rails app", "mount the admin at `/backoffice`", "put the admin on `admin.myapp.com`", "the admin should live under `/uk/admin`", "`403 Forbidden` pulling a private gem", "can't bundle the paid gem", "the paid gem won't install on Heroku/Kamal", "set up the gem token in CI/Docker", "deploy the admin and the gem is missing", "the admin says it's unlicensed", "there's a license-timeout badge in the admin", "I want an extra route in the admin's router".
+
+## Workflow
+
+### 1. Check requirements first
+
+Avo needs, in the target app:
+
+- Rails **>= 6.1**, Ruby **>= 3.1**.
+- `config.api_only` **= false** (an API-only app has no views/session/flash for Avo to render — see the docs map's api-only guide).
+- `propshaft` **or** `sprockets` in the Gemfile.
+- A `secret_key_base` (from `ENV["SECRET_KEY_BASE"]`, credentials, or secrets).
+- **Zeitwerk** autoloading (`config.load_defaults 6.1`+). An app upgraded from Rails 5 must switch off the classic autoloader.
+
+If any are missing, fix that before installing — otherwise the install "succeeds" but the admin won't boot.
+
+### 2. Pick the gems and add them to the Gemfile
+
+The `avo` Community gem is free and comes from rubygems.org. It covers resources, most fields, sorting, filtering, actions, associations, appearance, and i18n — about 70% of Avo. Each advanced feature is its own paid **add-on gem** from the private server, so a license only pulls in what it includes.
+
+Community only — nothing private, no token needed:
+
+```ruby
+# Gemfile
+gem "avo", ">= 4.0.0"
+```
+
+Paid add-ons — declare the gems included in the license inside a `source` block pointing at the private server:
+
+```ruby
+# Gemfile
+gem "avo", ">= 4.0.0"
+
+source "https://packager.dev/avo-hq/" do
+  # the add-ons on the license, e.g.
+  gem "avo-dashboards", ">= 4.0.0"
+  gem "avo-menu", ">= 4.0.0"
+  gem "avo-dynamic_filters", ">= 4.0.0"
+  gem "avo-authorization", ">= 4.0.0"
+end
+```
+
+Other add-on gems (`avo-advanced_search`, `avo-record_reordering`, `avo-kanban`, `avo-collaboration`, `avo-forms`, `avo-nested`, …) go in the same block. All paid gems come from `packager.dev` and need the token from step 3 to `bundle install`.
+
+To ship the app to environments **without** the paid gems, move them to an optional group and bundle without it:
+
+```ruby
+# Gemfile
+gem "avo"
+
+group :avo, optional: true do
+  source "https://packager.dev/avo-hq/" do
+    gem "avo-dashboards", "~> 4.0"
+  end
+end
+```
+
+```bash
+RAILS_GROUPS=avo BUNDLE_WITH=avo bundle install
+```
+
+### 3. Authenticate the private gem server (paid add-ons only)
+
+The token is the **Gem Server Token** from https://avohq.io/dashboard. It authenticates bundler to `packager.dev`. Skip this step entirely for Community.
+
+**Local machine** — store it in bundler's global config (bundler picks it up automatically, no Gemfile change):
+
+```bash
+bundle config set --global https://packager.dev/avo-hq/ xxx
+```
+
+**Servers & CI** — expose it as the `BUNDLE_PACKAGER__DEV` environment variable (bundler maps this env var to the `packager.dev` source):
+
+```bash
+export BUNDLE_PACKAGER__DEV=xxx
+# or one-shot:
+BUNDLE_PACKAGER__DEV=xxx bundle install
+```
+
+Per host:
+
+- **Heroku:** `heroku config:set BUNDLE_PACKAGER__DEV=xxx`
+- **Hatchbox:** add `BUNDLE_PACKAGER__DEV` in the app's Environment tab.
+- **GitHub Actions:** add a repo secret named `BUNDLE_PACKAGER__DEV`, then surface it in the workflow with `env: { BUNDLE_PACKAGER__DEV: ${{ secrets.BUNDLE_PACKAGER__DEV }} }`.
+- **Docker:** `ARG BUNDLE_PACKAGER__DEV` + `ENV BUNDLE_PACKAGER__DEV=$BUNDLE_PACKAGER__DEV` before `bundle install`, then `docker build --build-arg BUNDLE_PACKAGER__DEV=$BUNDLE_PACKAGER__DEV`.
+- **Kamal:** list `BUNDLE_PACKAGER__DEV` under `builder.secrets` in `deploy.yml`, put the value in `.kamal/secrets`, and in the Dockerfile run `RUN --mount=type=secret,id=BUNDLE_PACKAGER__DEV BUNDLE_PACKAGER__DEV=$(cat /run/secrets/BUNDLE_PACKAGER__DEV) bundle install`.
+
+Then `bundle install`.
+
+### 4. Run the install generator
+
+```bash
+bin/rails generate avo:install
+```
+
+This generates `config/initializers/avo.rb`, adds `mount_avo` to `config/routes.rb` (mounting under `/avo` by default), and — if a `User` (or `Account`) model exists — generates a first resource. Fastest path for a brand-new setup is the one-command app template, which runs every install step:
+
+```bash
+bin/rails app:template LOCATION='https://avohq.io/app-template'
+```
+
+**Installing from GitHub** (not rubygems) means precompiled assets aren't shipped — you must compile them yourself and hook that into deploys:
+
+```bash
+rake avo:build-assets
+```
+
+```ruby
+# Rakefile — run avo:build-assets whenever assets are precompiled
+Rake::Task["assets:precompile"].enhance do
+  Rake::Task["avo:build-assets"].execute
+end
+```
+
+(If your deploy has no `assets:precompile` step, enhance a step you do run, e.g. `db:migrate`.)
+
+### 5. Mount it where you want
+
+`mount_avo` forwards options straight to Rails' `mount`, and its `at:` defaults to `config.root_path`. Pick the shape:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount_avo                          # default: config.root_path (/avo)
+  mount_avo at: "backoffice"         # → /backoffice
+end
+```
+
+Under a scope (e.g. localization):
+
+```ruby
+scope ":locale" do
+  mount_avo
+end
+```
+
+(A `:locale` scope also needs `config.default_url_options` set — see the routing docs.)
+
+On a subdomain — `admin.myapp.com`:
+
+```ruby
+constraints subdomain: "admin" do
+  mount_avo at: "/"
+end
+```
+
+Under a **nested path** — `/uk/admin` — three things have to line up:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  scope :uk do
+    scope :admin do
+      get "dashboard", to: "avo/tools#dashboard"  # custom tools FIRST
+    end
+    mount_avo   # engine mounted LAST, after custom-tool routes
+  end
+end
+```
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.root_path = "/admin"            # ONLY the last segment — not "/uk/admin"
+  config.home_path = "/uk/admin/dashboard"  # other paths use the FULL path
+end
+```
+
+Served under a `map` prefix in `config.ru` — tell Avo the prefix so it builds correct URLs:
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.prefix_path = "/internal"
+end
+```
+
+To restrict who can reach the admin, wrap `mount_avo` in `authenticate :user do…end` — that's the **avo-authentication** skill, not this one.
+
+### 6. Add the license key (production)
+
+Community needs no key. For paid add-ons, drop the key into the initializer (an env var keeps it out of source control):
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.license_key = ENV["AVO_LICENSE_KEY"]
+end
+```
+
+A license authorizes **one app, one production URL** (`Rails.env.production?`). Non-production environments — development, staging, test, QA — need no extra license. To hide the "license request timed out" badge, set `config.display_license_request_timeout_error = false`.
+
+Verify at the **status page**: `https://yourapp.com/<mount-path>/avo_private/status` (e.g. `.../avo/avo_private/status` or `.../admin/avo_private/status`). It shows whether the license authenticated and what the checking server returned; the key is masked unless you set `config.exclude_from_status = []`. The viewing user must be an Avo admin. Deep failure diagnosis (unlicensed after deploy, timeouts, test-suite blocking the check host) is the **avo-troubleshoot** skill.
+
+### 7. (Optional) Append your own routes inside the engine
+
+Add custom controllers/actions to Avo's own router — open the engine's routes after `mount_avo`:
+
+```ruby
+# config/routes.rb
+if defined? ::Avo
+  Avo::Engine.routes.draw do
+    put "switch_accounts/:id", to: "switch_accounts#update", as: :switch_account
+
+    scope :resources do
+      get "courses/cities", to: "courses#cities"   # extra route on a resource controller
+    end
+  end
+end
+```
+
+```ruby
+# app/controllers/avo/switch_accounts_controller.rb
+class Avo::SwitchAccountsController < Avo::ApplicationController
+  def update
+    session[:tenant_id] = params[:id]
+    redirect_back fallback_location: root_path
+  end
+end
+```
+
+## Key options
+
+| Option / call | Does | Tiny example |
+| --- | --- | --- |
+| `mount_avo` | Mount Avo + all engines in `routes.rb` | `mount_avo at: "backoffice"` |
+| `at:` | Mount path (forwards to Rails `mount`) | `mount_avo at: "admin"` |
+| `config.root_path` | Avo's root path — **last segment only** when nested | `config.root_path = "/admin"` |
+| `config.prefix_path` | Prefix when served under a `config.ru` `map` block | `config.prefix_path = "/internal"` |
+| `source "https://packager.dev/avo-hq/"` | Gemfile block that scopes paid gems to the private server | wrap `gem "avo-dashboards"` |
+| `BUNDLE_PACKAGER__DEV` | Gem-server token env var bundler uses for `packager.dev` | `export BUNDLE_PACKAGER__DEV=xxx` |
+| `bundle config set --global …` | Store the token locally without touching the Gemfile | `… https://packager.dev/avo-hq/ xxx` |
+| `config.license_key` | Production license key | `config.license_key = ENV["AVO_LICENSE_KEY"]` |
+| `config.display_license_request_timeout_error` | Hide the license-timeout badge | `= false` |
+| `config.exclude_from_status` | Reveal masked fields on the status page | `config.exclude_from_status = []` |
+| `rake avo:build-assets` | Compile assets (required for GitHub installs) | hook into `assets:precompile` |
+| `Avo::Engine.routes.draw` | Append custom routes inside Avo's router | see step 7 |
+
+## Gotchas
+
+- **`.env` does NOT work for the gem-server token.** Bundler doesn't load `.env` files, so a `BUNDLE_PACKAGER__DEV` line there is ignored and `bundle install` fails with `403 Forbidden`. Use a real exported env var or the host's secrets mechanism (or `bundle config` locally).
+- **`403 Forbidden` in a sandboxed/cloud env is usually the network, not the token.** In the Claude Code cloud environment, Cursor background agents, or any setup with restricted egress, a correctly-set token still 403s because a network allowlist is blocking `packager.dev`. Add `packager.dev` to the allowed hosts and re-run `bundle install` — don't churn on the token.
+- **Nested mount = two easy mistakes.** For `/uk/admin`: `config.root_path` must be **only the last segment** (`/admin`, never `/uk/admin`), and `mount_avo` must be the **last** thing in the scope, after any custom-tool routes — otherwise the engine swallows them.
+- **`api_only` must be `false`.** An API-only app has no session/flash/views; Avo can't render. Flip it (or follow the api-only guide) before installing.
+- **GitHub installs don't ship assets.** Install from GitHub and you must `rake avo:build-assets` yourself and hook it into `assets:precompile`, or the admin renders unstyled/broken in production.
+- **One license per production URL.** A key authorizes a single app on a single production URL; staging/dev/test don't consume licenses. A second production URL needs its own license.
+- **Add-on gems must sit inside the `packager.dev` `source` block** — that's where the private gems resolve from; `avo` itself stays outside it (rubygems.org).
+- **Verify before writing.** Option and path names drift between versions — check 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 paths): `Gemfile`, `config/routes.rb`, `config/initializers/avo.rb`, and any Rakefile/CI/Dockerfile edits — plus the generator command(s) run.
+- The **gems** installed (`avo` alone vs which paid add-on gems) and, for paid, **where** the gem-server token lives (bundler config, host env var, CI secret) — never echo the token value itself.
+- The **mount** shape and resulting URL (path / scope / subdomain / nested), and any `root_path` / `prefix_path` you set to match it.
+- Whether the **license key** is wired (and via which env var), and the **status-page URL** to confirm it in production.
+- Any custom engine routes you appended.
+- Next steps: run `bundle install`, generate a first resource (**avo-resources**), gate access to the admin (**avo-authentication**) and set up authorization, tune per-app behavior in the initializer (**avo-admin-config**), and — if the gem won't bundle or the license won't validate — hand off to **avo-troubleshoot**.