avo 4.1.0 → 4.1.2

data/lib/avo/skills/avo-branding-appearance/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: avo-branding-appearance
+description: Brand and theme an Avo admin panel — logos, favicon, color scheme, neutral/accent palettes, chart colors, per-user theme persistence, deep CSS re-skinning, and menu/action icons — starting from the no-build `config.appearance` path in `config/initializers/avo.rb`. Use when the user wants to "brand the admin with our logo and colors", "make the admin match our brand", "add our company logo", "add a favicon", "make the admin default to / support dark mode", "let users switch themes" or "lock the theme", "remember each user's theme", "change the accent/primary color" or "make the buttons blue", "change the sidebar/navbar background", "give the admin a coastal/rose/sunset theme", "our admin looks too generic", "change the dashboard chart colors", or "use a custom icon for this menu item" — whether or not they name Avo.
+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 Branding & Appearance
+
+Make the Avo admin look like your product — logos, favicon, color scheme, brand colors, chart colors, and the deeper CSS chrome (navbar, sidebar, tables). Avo gives you a ladder: start with a few lines of Ruby in `config/initializers/avo.rb` (`config.appearance = { … }`, **no build step**), and only drop to CSS or ejected views when the Ruby layer can't express what you want. **Almost every branding request is satisfied by `config.appearance` alone** — reach for CSS last.
+
+Files you'll touch, from shallowest to deepest:
+
+- `config/initializers/avo.rb` → `config.appearance = { … }` — logos, favicon, scheme, palettes, picker/lock, persistence, chart colors. **The default answer.**
+- `app/assets/stylesheets/avo-overrides.css` — no-build CSS-variable re-skin (eject with `rails g avo:eject --partial :avo_overrides_css`). Served as-is.
+- `app/views/avo/partials/_head.html.erb` — inline `<style>` for component variables (eject with `rails g avo:eject --partial :head`).
+- `app/assets/svgs/` — your own SVG icons for menu items / actions.
+- A JSONB column + `load_settings`/`save_settings` procs — only when persisting each user's theme to the database.
+
+## Docs
+
+Authoritative docs — fetch on demand, verify option names against them (and the app's installed Avo source) before writing; don't inline whole pages:
+
+- Docs map (discover pages): https://docs.avohq.io/4.0/docs-map.md
+- Theming overview (the ladder): https://docs.avohq.io/4.0/theming.md
+- Appearance guide: https://docs.avohq.io/4.0/appearance.md — API reference (every option, defaults, CSS variables): https://docs.avohq.io/4.0/appearance-api.md
+- Icons (Tabler / Heroicons / your own SVGs): https://docs.avohq.io/4.0/icons.md
+- Branding → Appearance (Avo 3 `config.branding` was renamed to `config.appearance` in Avo 4): https://docs.avohq.io/4.0/branding.md
+
+## When this applies
+
+**Explicit (Avo named):** "set `config.appearance`", "change Avo's logo / logomark / favicon", "set the Avo accent/neutral palette", "lock the Avo theme", "restrict the appearance picker", "persist Avo appearance to the database", "override Avo CSS variables", "eject the `:head` partial", "set an icon on this Avo menu item".
+
+**Implicit (product-shaped, no mention of Avo):** "brand the admin with our logo and colors", "make the admin match our brand", "add our company logo / a favicon", "the admin should default to dark mode" / "support dark mode", "let users switch themes" / "lock it so they can't", "remember each user's theme across devices", "change the accent/primary color" / "make the buttons blue", "change the sidebar/navbar background color", "give the admin a coastal / rose / 80s-sunset theme", "our admin looks too generic", "change the dashboard chart colors", "use a custom icon for this menu item".
+
+## Workflow
+
+Read `config/initializers/avo.rb` first. If a `config.appearance = { … }` hash already exists, **merge** new keys into it rather than adding a second block. Work top-down through this ladder and stop at the shallowest layer that does the job.
+
+### 1. Brand assets — logo, logomark, favicon, placeholder
+
+Asset paths resolve through the Rails asset pipeline (e.g. `app/assets/images/my_company/logo.png` → `"my_company/logo.png"`). Each has an optional `*_dark` variant used in dark mode; omit the dark variant and the light file is used in both schemes.
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.appearance = {
+    logo: "my_company/logo.png",              # main navbar logo
+    logo_dark: "my_company/logo-dark.png",    # dark-mode variant (optional)
+    logomark: "my_company/logomark.png",      # compact square mark for collapsed navbar
+    logomark_dark: "my_company/logomark-dark.png",
+    favicon: "my_company/favicon.ico",
+    favicon_dark: "my_company/favicon-dark.ico",
+    placeholder: "my_company/placeholder.svg" # fallback for records with no cover image
+  }
+end
+```
+
+**The top navbar is dark in BOTH light and dark mode** — `logo` always sits on a dark surface, so pick a file that reads on dark. `logo_dark` only swaps when the whole UI is in dark mode, not to fix contrast on the navbar.
+
+### 2. Color scheme — light / dark / auto
+
+```ruby
+config.appearance = {
+  scheme: :auto # :auto (follow system, default) | :light | :dark
+}
+```
+
+Unless locked (step 4), users can flip the scheme from the navbar switcher. "Default to dark mode" → `scheme: :dark`. "Force dark, no toggle" → `scheme: :dark` + `lock: [:scheme]`.
+
+### 3. Brand colors — neutral & accent palettes
+
+Two palettes drive the whole UI. **Neutral** = surfaces, borders, chrome. **Accent** = interactive emphasis: primary buttons, links, focus rings, selected rows. "Make the buttons blue" / "change the primary color" → set `accent`.
+
+**Built-in presets (fastest):**
+
+```ruby
+config.appearance = {
+  neutral: :slate,  # :slate :stone :gray :zinc :neutral :taupe :mauve :mist :olive  (or :brand)
+  accent: :blue     # :red :orange :amber :yellow :lime :green :emerald :teal :cyan :sky
+                    # :blue :indigo :violet :purple :fuchsia :pink :rose  (or :brand)
+}
+```
+
+`neutral:` and `accent:` **must be Symbols** — a String or Hash raises `ArgumentError`.
+
+**Custom brand colors** — define your own palette, then select it with the `:brand` preset:
+
+```ruby
+config.appearance = {
+  # Neutral needs all 12 shades; the same scale is used in both light and dark mode.
+  neutral: :brand,
+  neutral_colors: {
+    25 => "oklch(98.5% 0.005 60)", 50  => "oklch(97% 0.008 60)", 100 => "oklch(93% 0.012 60)",
+    200 => "oklch(86% 0.015 60)",  300 => "oklch(76% 0.015 60)", 400 => "oklch(63% 0.014 60)",
+    500 => "oklch(53% 0.013 60)",  600 => "oklch(48% 0.012 60)", 700 => "oklch(43% 0.011 60)",
+    800 => "oklch(39% 0.010 60)",  900 => "oklch(28% 0.008 60)", 950 => "oklch(20% 0.005 60)"
+  },
+
+  # Accent needs exactly three tokens.
+  accent: :brand,
+  accent_colors: {
+    color:      "oklch(55% 0.2 280)", # main accent: button bg, link color
+    content:    "oklch(45% 0.2 280)", # hover surfaces, soft variants
+    foreground: "oklch(99% 0 0)"      # text/icons rendered on top of the accent
+  }
+}
+```
+
+Palette values accept any CSS color string (`oklch()`, `#hex`, `rgb()`, `hsl()`, `var()`). `neutral_colors` and `accent_colors` are independent — set either, both, or neither. Defining the colors only creates the palette; you still need `neutral: :brand` / `accent: :brand` (or `"brand"` listed in `neutrals:`/`accents:`) to actually select it. If the user gives you only one brand color, set `accent_colors` and leave the neutral as a preset like `:slate`.
+
+### 4. Picker exposure — restrict, lock, and switcher layout
+
+By default the navbar picker lets users change scheme, neutral, and accent. Trim the options, lock some down, or change the layout:
+
+```ruby
+config.appearance = {
+  scheme: :light, neutral: :slate, accent: :blue,
+
+  neutrals: %w[brand slate stone olive],   # subset shown in the picker (Strings, no colon)
+  accents:  %w[brand blue indigo violet],
+
+  lock: [:scheme],           # any subset of [:scheme, :neutral, :accent] — hides that switcher, forces the value
+  picker_layout: :inline     # :inline (default; collapses to dropdown on small screens) | :dropdown
+}
+```
+
+A value **not** in `lock:` is a default the user can still override. Lock all three to fully pin the theme.
+
+### 5. Persist each user's picks
+
+By default picks live in a **cookie** (per browser, zero setup). For cross-device persistence, switch to the database and supply both blocks; you need a JSON/JSONB column on the model backing `current_user`.
+
+```ruby
+# db/migrate/..._add_avo_preferences_to_users.rb
+class AddAvoPreferencesToUsers < ActiveRecord::Migration[8.0]
+  def change
+    add_column :users, :avo_preferences, :jsonb, default: {}
+  end
+end
+```
+
+```ruby
+config.appearance = {
+  persistence: :database, # :cookie (default) | :database
+  load_settings: -> {
+    current_user&.avo_preferences&.dig("appearance")&.symbolize_keys || {}
+  },
+  save_settings: -> {
+    next unless current_user
+
+    current_user.update!(
+      avo_preferences: current_user.avo_preferences.to_h.deep_merge(
+        "appearance" => settings.stringify_keys
+      )
+    )
+  }
+}
+```
+
+Both blocks run in Avo's execution context with `current_user` (plus `params`, `request`, `view_context`, `main_app`). `load_settings` returns a Hash with any subset of `:color_scheme`, `:neutral`, `:accent`; missing keys fall back to defaults. `save_settings` receives a `settings` local that is a **partial** Hash — only the keys the user just changed — so always `deep_merge` into existing preferences, never overwrite the whole blob.
+
+### 6. Chart colors
+
+Recolor dashboard charts. Values are forwarded straight to Chart.js, so they **must be hex** (not `oklch`/`rgb`):
+
+```ruby
+config.appearance = {
+  chart_colors: ["#0B8AE2", "#34C683", "#FFBE4F", "#FF7676", "#2AB1EE"]
+}
+```
+
+### 7. Deep re-skin — CSS variables (only when `config.appearance` can't reach it)
+
+Navbar background, sidebar surfaces, table row hover/selected, focus ring, and motion speeds aren't routed through Ruby — they're CSS custom properties. Avo's whole look is variable-driven, so overriding a handful re-skins everything with **no build step**. Put light-mode values on `:root`, dark-mode overrides on `.dark`.
+
+Preferred surface — eject `avo-overrides.css` (loaded after Avo's stylesheet, so it wins the cascade):
+
+```bash
+rails g avo:eject --partial :avo_overrides_css
+```
+
+```css
+/* app/assets/stylesheets/avo-overrides.css */
+:root {
+  --color-accent: var(--color-fuchsia-500);
+  --color-navbar-background: #1e3a5f;
+  --color-sidebar-background: #f5f7fa;
+  --color-table-row-hover: #eef4fb;
+  --radius-card: 1.5rem;
+}
+.dark {
+  --color-accent: var(--color-fuchsia-400);
+  --color-navbar-background: #0b1a2b;
+  --color-sidebar-background: #11161c;
+}
+```
+
+The navbar and sidebar expose **scoped** palette contracts on the `.top-navbar` and `.avo-sidebar` selectors (e.g. `--top-navbar-content`, `--sidebar-link-active-background`) so you can recolor them without leaking into popovers or the main content. If you'd rather keep the `<style>` next to the rest of the head, eject `:head` instead and append a `<style>` block there:
+
+```bash
+bin/rails generate avo:eject --partial :head
+```
+
+The full variable list (navbar, sidebar, table, focus ring, motion) with defaults lives in the CSS variables section of `appearance-api.md` — fetch it before writing component-level overrides. For named-theme requests ("coastal", "rose", "80s sunset"), work in `avo-overrides.css` with matching `:root` and `.dark` values.
+
+### 8. Icons (menu items, actions)
+
+Anywhere Avo takes an `icon:`, pass a path string. **Prefer Tabler in v4** (`tabler/outline/<name>` or `tabler/filled/<name>`); Heroicons (`heroicons/outline/<name>`, also `solid`/`mini`/`micro`) are legacy-supported. Your own SVGs go in `app/assets/svgs/` and are referenced by filename.
+
+```ruby
+# a menu item in config.main_menu
+link "Reports", path: "/reports", icon: "tabler/outline/chart-bar"
+# your own file at app/assets/svgs/my-icons/rocket.svg
+dashboard :sales, icon: "my-icons/rocket.svg"
+```
+
+For **populating menu/resource icons at scale** (migrations, whole-sidebar passes), that's the **avo-navigation-search** skill — defer to it rather than hand-picking here. Avo's own `avo/*` icons are a **private API** — don't rely on them.
+
+## Key options (`config.appearance`)
+
+| Option | Does | Type / values |
+| --- | --- | --- |
+| `logo` / `logo_dark` | Main navbar logo (+ dark variant) | String path; default `"avo/logo.png"` |
+| `logomark` / `logomark_dark` | Compact mark for collapsed navbar | String path |
+| `favicon` / `favicon_dark` | Browser favicon (+ dark variant) | String path |
+| `placeholder` | Fallback image for record with no cover | String path |
+| `scheme` | Default color mode | `:auto` (default) `:light` `:dark` |
+| `neutral` / `accent` | Palette presets | **Symbol** only (or `:brand`) |
+| `neutral_colors` | Custom 12-shade neutral | Hash of all 12 shades (`25`…`950`) |
+| `accent_colors` | Custom accent | Hash of `:color`, `:content`, `:foreground` |
+| `neutrals` / `accents` | Restrict picker options | Array of **Strings** (no colon) |
+| `lock` | Force values, hide switchers | Array subset of `[:scheme, :neutral, :accent]` |
+| `picker_layout` | Navbar switcher layout | `:inline` (default) `:dropdown` |
+| `persistence` | Where picks are stored | `:cookie` (default) `:database` |
+| `load_settings` / `save_settings` | DB persistence blocks | Proc; needs a JSON/JSONB column |
+| `chart_colors` | Dashboard chart palette | Array of **hex** Strings |
+
+CSS-only knobs (navbar/sidebar/table/focus/motion variables) are not in this hash — see step 7 and `appearance-api.md`.
+
+## Gotchas
+
+- **`neutral:` / `accent:` must be Symbols.** A String or Hash raises `ArgumentError`. Custom colors go through `neutral_colors:` / `accent_colors:`, and you must also set `neutral: :brand` / `accent: :brand` (or list `"brand"` in `neutrals:`/`accents:`) to select the custom palette.
+- **`neutral_colors` needs all 12 shades; `accent_colors` needs all 3 tokens.** A missing or `nil` value raises `ArgumentError`.
+- **The navbar is dark in both modes.** The `logo` must read on a dark surface. `logo_dark` is for whole-UI dark mode, not navbar contrast.
+- **`chart_colors` must be hex.** They're passed straight to Chart.js — `oklch()`/`rgb()` won't work there (even though the palettes accept them).
+- **`avo-overrides.css` is served as-is, NOT through the Tailwind build.** Only put plain CSS + variable overrides there — no `@apply`, no arbitrary values. Tailwind directives for your *own* custom UI belong in `app/assets/stylesheets/avo/` (which IS built). See the avo-custom-ui skill.
+- **DB persistence needs a JSONB column and BOTH blocks**, and `save_settings` gets a **partial** `settings` Hash (only the changed keys) — `deep_merge`, never overwrite the whole preferences blob.
+- **`config.branding` was renamed to `config.appearance` in Avo 4.** On a v3 app you may find `config.branding = { … }` — migrate it into `config.appearance`.
+- **Avo's `avo/*` icons are a private API.** Use `tabler/*` (preferred), `heroicons/*` (legacy), or your own SVGs in `app/assets/svgs/`.
+- **Verify before writing.** Option names drift between versions — check the docs URLs above or the installed Avo source rather than trusting memory.
+
+## Cross-links
+
+- **avo-admin-config** — other global `Avo.configure` knobs beyond appearance.
+- **avo-navigation-search** — populating menu/resource icons and menu structure at scale.
+- **avo-custom-ui** — deeper CSS/Tailwind for your own tools/fields, and ejecting views for full markup control.
+
+## Report
+
+When done, tell the user:
+
+- Which file(s) you edited (full paths) and, for CSS/eject work, which generator command(s) to run (`rails g avo:eject --partial :avo_overrides_css` / `:head`, or the migration).
+- Which `config.appearance` keys you set and why (assets, scheme, palettes, picker/lock, persistence, chart colors).
+- Which layer of the ladder you used and why you didn't go deeper (Ruby vs `avo-overrides.css` vs ejected `:head`).
+- Anything the user must still do: add the asset files under `app/assets/`, run the migration for DB persistence, or restart the server so initializer changes take effect.
+- For custom palettes, remind them the same scale applies in both light and dark mode, and confirm the `:brand` preset is selected.

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

@@ -0,0 +1,236 @@
+---
+name: avo-controllers
+description: Override the per-resource CRUD controller hooks Avo generates (redirect paths, flash messages, custom responses, save/destroy behavior) and safely extend Avo's private ApplicationController. Use when the user wants to redirect somewhere else after creating/updating/deleting in the admin, change the "successfully created/updated" flash message, soft-delete or archive instead of destroying, swap `@record.save!` for a service object, run code before every admin request, set a `Current` attribute or tenant per admin request, override `fill_record`, or fix `ActionDispatch::MissingController`. Covers `Avo::CoursesController < Avo::ResourcesController`, the `avo:controller` generator, `after_create_path`/`after_update_path`/`after_destroy_path`, `*_success_message`/`*_fail_message`, `create_/update_/destroy_success_action`/`*_fail_action`, `save_record_action`/`destroy_record_action`, and extending `Avo::ApplicationController` with a concern in `to_prepare`.
+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 Resource Controllers
+
+Avo generates a Rails controller alongside every resource so each one plugs into Rails' REST architecture. Each generated controller inherits from `Avo::ResourcesController`, which inherits from `Avo::BaseController` — and that base is where every CRUD action (`index`, `show`, `new`, `create`, `edit`, `update`, `destroy`) lives:
+
+```ruby
+# app/controllers/avo/courses_controller.rb
+class Avo::CoursesController < Avo::ResourcesController
+end
+```
+
+Most of the time you never touch this file — resource-level config on `app/avo/resources/<name>.rb` does the job. Reach for the controller when you need **granular per-action control**: where the user lands after a save, what the flash says, how the response is rendered, or how the record is actually persisted or removed. You do that by overriding **hook methods** in the generated controller, the same way Devise lets you override `after_sign_in_path_for`. For app-wide behavior that isn't tied to one resource (a `Current` attribute, a tenant, a `before_action` on every admin request), you extend `Avo::ApplicationController` instead — but **never by copying it** (see below).
+
+## Docs
+
+Authoritative docs — fetch on demand rather than guessing, and verify every method 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
+- Controllers guide: https://docs.avohq.io/4.0/controllers.md — API reference (each hook + its default): https://docs.avohq.io/4.0/controllers-api.md
+- Extending `Avo::ApplicationController`: https://docs.avohq.io/4.0/avo-application-controller.md
+
+## When this applies
+
+**Explicit (Avo named):** "override the `Courses` controller", "override `after_create_path`/`after_update_path`/`after_destroy_path`", "change `create_success_message`", "override `save_record_action` / `destroy_record_action`", "generate a controller with `avo:controller`", "set `config.resource_parent_controller`", "extend `Avo::ApplicationController`", "override `fill_record`".
+
+**Implicit (Rails/product-shaped, no mention of Avo):** "redirect somewhere else after saving/creating/deleting in the admin", "send the user to the dashboard after they create a record", "change the 'successfully created' message", "soft-delete instead of destroying in the admin", "archive instead of delete", "run a service object when I save instead of `save!`", "run code before every admin request", "set a `Current` attribute on each admin request", "set the tenant / add multitenancy in the admin", "customize what happens after I save a record", "I get `ActionDispatch::MissingController` when I open a resource".
+
+## Workflow
+
+### 1. Know which lever to pull
+
+Before opening a controller, check whether a **resource-level option** already covers it — it's less code and survives upgrades better:
+
+- Just want to land on <Index /> or <Edit /> after a save? Set [`self.after_create_path`](https://docs.avohq.io/4.0/resources-api.md) / `self.after_update_path` (`:show` | `:edit` | `:index`) on the resource — no controller needed. (There is **no** resource-level `after_destroy_path`; use the controller hook for that.)
+- Need a computed path, a different flash, a custom render, or different persistence? Override the controller hook (steps below).
+- Behavior that should apply to **every** resource/request, not one? Extend `Avo::ApplicationController` (see "Extending `Avo::ApplicationController`").
+
+### 2. Make sure the controller exists
+
+Every resource **must** have a paired controller at `app/controllers/avo/<name>s_controller.rb`, or opening it raises `ActionDispatch::MissingController`. The resource generator creates it for you; if it's missing (deleted, or the resource was hand-written), generate one:
+
+```bash
+bin/rails generate avo:controller course     # → app/controllers/avo/courses_controller.rb
+bin/rails generate avo:controller galaxy/planet   # namespaced → Avo::Galaxy::PlanetsController
+```
+
+The last name segment is pluralized (`course` → `Avo::CoursesController`). To make generated controllers inherit from a shared base (e.g. one that adds authentication), pass `--parent-controller` or set it once in the initializer:
+
+```bash
+bin/rails g avo:controller city --parent-controller Avo::BaseResourcesController
+```
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.resource_parent_controller = "Avo::BaseResourcesController" # default: "Avo::ResourcesController"
+end
+```
+
+### 3. Override the hook(s) you need
+
+Add the method(s) to the generated controller. Each hook has a documented default; calling `super` runs it. **Guard your override with `super`** whenever the default handles a flow you want to keep (this is the #1 source of breakage — see Gotchas).
+
+## Hooks
+
+Every write action (`create`, `update`, `destroy`) exposes the same three flavors, plus two persistence methods shared by create/update and destroy. All are overridden in the generated resource controller.
+
+### Redirect path — where the user lands
+
+`after_create_path`, `after_update_path`, `after_destroy_path` return the path used after a successful action.
+
+```ruby
+class Avo::CoursesController < Avo::ResourcesController
+  def after_create_path
+    "/avo/resources/users"
+  end
+end
+```
+
+Defaults you may be dropping:
+
+- **`after_create_path`** — when the record was created **through an association**, redirects back to the parent record's page; otherwise honors the resource's `self.after_create_path`, falling back to the new record's <Show /> (or <Edit /> when `config.resource_default_view` is `:edit`). Return `super` when `params[:via_relation_class]` and `params[:via_record_id]` are present to keep the parent redirect.
+- **`after_update_path`** — returns `params[:return_to]`, then `params[:referrer]`, before honoring `self.after_update_path` and the <Show />/<Edit /> fallback. Return `super` when `params[:return_to]` is present so "send the user back where they came from" keeps working.
+- **`after_destroy_path`** — returns `params[:referrer]` when present, otherwise the resource's <Index />.
+
+```ruby
+def after_update_path
+  return super if params[:return_to].present?
+
+  "/avo/resources/courses"
+end
+```
+
+### Flash message — what the user reads
+
+Override `*_success_message` / `*_fail_message` (one per outcome) to change the flash text:
+
+```ruby
+class Avo::CoursesController < Avo::ResourcesController
+  def create_success_message
+    "Course saved. Off you go! 🚀"
+  end
+
+  def destroy_fail_message
+    "This course could not be removed."
+  end
+end
+```
+
+The six: `create_success_message`, `create_fail_message`, `update_success_message`, `update_fail_message`, `destroy_success_message`, `destroy_fail_message`. Defaults are i18n-backed (e.g. `"#{@resource.name} #{t("avo.was_successfully_created")}."`); `destroy_fail_message` defaults to the record's joined validation errors, or `t("avo.failed")` when there are none.
+
+### Custom response — full control over the render
+
+When path + message aren't enough (different format, extra headers, a completely different render), override the `*_action` methods. These are **Turbo-stream aware** and their defaults drive real UI flows, so fall back to `super` for the cases you aren't customizing:
+
+```ruby
+class Avo::CoursesController < Avo::ResourcesController
+  def create_success_action
+    return super if params[:via_belongs_to_resource_class].present?
+
+    respond_to do |format|
+      format.html { redirect_to "/dashboard", flash: {success: create_success_message} }
+    end
+  end
+end
+```
+
+Defaults that carry Turbo behavior:
+
+- **`create_success_action`** — when a record is created through a `belongs_to` modal (`params[:via_belongs_to_resource_class]` present), renders Turbo Streams that close the modal and select the new record in the field; otherwise redirects to `after_create_path` with the success flash. Keep the `super` guard or the "Create new record" flow inside `belongs_to` fields breaks.
+- **`destroy_success_action`** — when the delete happens inside a Turbo Frame (`params[:turbo_frame]`, e.g. an association list) it reloads that frame via Turbo Streams; otherwise flashes and redirects to `after_destroy_path`. Keep the `super` guard or deleting from association lists breaks.
+- **`create_fail_action` / `update_fail_action`** — flash the fail message and re-render `:new` / `:edit` with `:unprocessable_content` status (`:unprocessable_entity` on Rails < 7.1), plus a `turbo_stream` format.
+- **`destroy_fail_action`** — flashes and renders a `turbo_stream` alert without leaving the page.
+
+### Persistence — how the record is saved or destroyed
+
+Avo saves with `@record.save!` and removes with `@record.destroy!`. Override `save_record_action` / `destroy_record_action` for soft deletes, archiving, a service object, or extra bookkeeping:
+
+```ruby
+class Avo::CoursesController < Avo::ResourcesController
+  def destroy_record_action
+    @record.archive!          # soft-delete instead of destroying
+  end
+
+  def save_record_action
+    CourseSaver.new(@record).call   # service object instead of save!
+  end
+end
+```
+
+**Errors raised inside these methods are caught, logged, and added to the record's errors** (`errors.add(:base, ...)`) — which automatically triggers the matching `*_fail_action` and `*_fail_message`. So you don't rescue in here yourself; raising *is* how you signal failure, and the record's validation errors surface in the fail flash.
+
+## Extending `Avo::ApplicationController`
+
+For behavior that isn't tied to one resource — setting a `Current` attribute, selecting a tenant, a `before_action` on every admin request — you want `Avo::ApplicationController`, not a resource controller.
+
+**Do NOT copy Avo's `application_controller.rb` into your app.** Avo's `ApplicationController` (and the `BaseApplicationController` it inherits) is a **private API**: methods, before/after actions, and helpers change between versions **without a changelog or upgrade-guide entry**, and a copied file silently drifts and breaks on the next upgrade. Use a concern merged in at boot instead.
+
+**Add** behavior — `include` the concern, use an `included` block:
+
+```ruby
+# app/controllers/concerns/multitenancy.rb
+module Multitenancy
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :set_tenant
+    # or, to run BEFORE all of Avo's own before_actions:
+    prepend_before_action :set_tenant
+  end
+
+  def set_tenant
+    # your logic here
+  end
+end
+
+# config/initializers/avo.rb
+Rails.configuration.to_prepare do
+  Avo::ApplicationController.include Multitenancy
+end
+```
+
+**Override** an existing method (e.g. `fill_record`) — `prepend` the concern and use a `prepended` block so it wins in the ancestor chain, calling `super` to keep Avo's behavior:
+
+```ruby
+# app/controllers/concerns/application_controller_overrides.rb
+module ApplicationControllerOverrides
+  extend ActiveSupport::Concern
+
+  prepended do
+    before_action :some_hook
+  end
+
+  def fill_record
+    # your logic here
+    super
+  end
+end
+
+# config/initializers/avo.rb
+Rails.configuration.to_prepare do
+  Avo::ApplicationController.prepend ApplicationControllerOverrides
+end
+```
+
+Rules of thumb: **`include` + `included`** to add; **`prepend` + `prepended`** to override an existing method; **`prepend_before_action`** to run *before* Avo's own filters (set a tenant/account early); always wrap it in `Rails.configuration.to_prepare` so it re-applies on every code reload.
+
+## Gotchas
+
+- **Guard overrides with `super` — the defaults do more than redirect.** `after_create_path` handles the via-association parent redirect (`params[:via_relation_class]`/`via_record_id`), `after_update_path` honors `return_to`/`referrer`, `create_success_action` drives the `belongs_to`-modal Turbo flow (`via_belongs_to_resource_class`), and `destroy_success_action` reloads the Turbo Frame for association-list deletes (`params[:turbo_frame]`). Drop the `super` branch and you break that flow. Pattern: `return super if params[:x].present?`, then your custom behavior.
+- **Never copy `Avo::ApplicationController` wholesale.** It's a private API that changes without changelog and breaks on upgrade. Use a concern + `Rails.configuration.to_prepare` (`include`/`included` to add, `prepend`/`prepended` to override, `prepend_before_action` to run first).
+- **Raising is how you fail in persistence hooks.** Errors from `save_record_action` / `destroy_record_action` are caught and added to `@record.errors[:base]` → the fail action + message fire automatically. Don't swallow the exception; let it raise (or `errors.add` yourself) to signal failure. A foreign-key constraint on delete surfaces this way instead of 500-ing.
+- **Prefer the resource option when one exists.** For a plain "land on index/edit after save", `self.after_create_path` / `self.after_update_path` on the resource beats a controller override. There's no resource-level `after_destroy_path` — that one's controller-only.
+- **Missing controller → `ActionDispatch::MissingController`.** Every resource needs its controller; generate it with `bin/rails g avo:controller <name>`. Use `--parent-controller` (or `config.resource_parent_controller`) to inherit from a shared base.
+- **Verify before writing.** Method names and defaults drift between versions — check the docs URLs above or the app's installed Avo source (`Avo::BaseController`, `Avo::BaseApplicationController`) rather than trusting memory.
+
+**Related skills:** setting the tenant per request → **avo-multitenancy**; `Avo::Current` and other engine internals → **avo-engine-internals**; authenticating admin requests / `config.authenticate_with` → **avo-authentication**; resource-level `self.after_create_path` and friends → **avo-resources**.
+
+## Report
+
+When done, tell the user:
+
+- Which controller file(s) you created or edited (full paths) and any generator command(s) run.
+- Which hook(s) you overrode and what each now does — and, for any hook whose default carried a Turbo/association/`return_to` flow, confirm you kept the `super` guard (or explicitly note you dropped it and why).
+- For persistence overrides (`save_record_action`/`destroy_record_action`): what now persists/removes the record, and that failures still surface through the normal fail action/message.
+- For `Avo::ApplicationController` work: the concern file, whether you used `include`/`prepend`, and that it's wired in `Rails.configuration.to_prepare`.
+- Anything still needed: run pending migrations, generate a missing controller, add the `archived_at`/soft-delete column, or reach for a related skill (multitenancy, authentication).