avo 4.1.0 → 4.1.2

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

@@ -0,0 +1,179 @@
+---
+name: avo-update
+description: Update an app's Avo gems and apply every upgrade-guide step for the versions crossed — record the current versions, run `bin/rails avo:update`, diff `Gemfile.lock` to see the real jump, then work the upgrade guide section by section from oldest to newest, writing a deletable log as you go. Use when the user wants to update or upgrade Avo, bump the Avo gems, get on the latest Avo, apply the Avo upgrade guide, catch up an admin panel that's several versions behind, find out what breaks if they upgrade, or fix an admin that broke after an Avo bump. Also covers the Avo 3 → Avo 4 major upgrade.
+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 Update
+
+Updating Avo is two jobs, and skipping the second is how admins break: **bump the gems**, then **apply the upgrade guide for every version you crossed**. Avo publishes breaking changes as discrete sections in an upgrade page — an app jumping 4.0.4 → 4.0.12 may have several to apply, in order, and add-on gems (`avo-kanban`, `avo-dynamic_filters`, …) get their own sections. `bin/rails avo:update` only does the first job; nothing applies the guide for you.
+
+The whole run is: **record versions → update → diff the lock → apply the crossed sections oldest-first → log it → boot the app back up**.
+
+**Docs** — fetch on demand with WebFetch; prefer the raw `.md` (clean, no HTML):
+
+- Upgrade guide, Avo 4.x (the section list you work through): https://docs.avohq.io/4.0/upgrade.md
+- Avo 3 → Avo 4 major upgrade (a different, much bigger job): https://docs.avohq.io/4.0/avo-3-avo-4-upgrade.md
+- Avo 3.x upgrade guide (for jumps still inside 3.x): https://docs.avohq.io/3.0/upgrade.md
+- Docs map (find any page a guide section links to): https://docs.avohq.io/4.0/docs-map.md
+
+Release notes for versions the guide doesn't mention: https://github.com/avo-hq/avo/releases. Per-gem latest versions: https://avohq.io/gems.
+
+## When this applies
+
+**Explicit (Avo named):** "upgrade Avo", "update the Avo gems", "run `avo:update`", "bump avo to the latest", "apply the Avo upgrade guide", "we're on Avo 4.0.4, get us current", "upgrade from Avo 3 to Avo 4", "what breaks if I upgrade Avo?", "the admin broke after I bumped Avo".
+
+**Implicit (no mention of Avo):** "update the admin panel gems", "we're several versions behind on the admin", "get the backoffice onto the latest release", "`bundle update avo` broke the admin", "the admin panel stopped rendering after last week's bundle update".
+
+**Not this skill:** first-time install, gem-server token, mounting, license key → **avo-setup**. A broken admin with no recent version change → **avo-troubleshoot**. Locale casing after an upgrade → apply the guide section here, then **avo-i18n** for the wider i18n picture.
+
+## Workflow
+
+### 1. Get a safe starting point
+
+Non-negotiable before touching the lockfile — the whole method depends on `git diff` telling the truth:
+
+```bash
+git status --porcelain          # must be empty; if not, stop and ask
+git checkout -b avo-update
+```
+
+Run the test suite now to capture a baseline. **If it's already red, stop and tell the user** — otherwise you can't tell your changes from theirs.
+
+### 2. Record the current versions
+
+This is the "before" half of the jump. Read every Avo gem, not just core — add-ons have their own upgrade sections and their own version lines:
+
+```bash
+grep -E "^ {4}avo(-[a-z_]+)? \(" Gemfile.lock
+```
+
+Write these down in the log file (step 6) **before** running the update — after the bundle they're gone unless you kept them.
+
+Also note the Gemfile constraints, which cap what the update can do:
+
+```bash
+grep -n "avo" Gemfile
+```
+
+### 3. Run the update
+
+```bash
+bin/rails avo:update      # or: bundle exec rails avo:update
+```
+
+The task resolves Avo core plus every registered Avo plugin to its real gem name and runs `bundle update --conservative <those gems>` — `--conservative` so it doesn't drag unrelated shared dependencies along. Read its output: it echoes the exact `bundle update` command it ran.
+
+If the task isn't available (older Avo, or the app won't boot), fall back to naming the gems yourself:
+
+```bash
+bundle update --conservative avo avo-dashboards avo-menu   # …every avo* gem in the lock
+```
+
+### 4. Diff the lock to find the real jump
+
+```bash
+git diff Gemfile.lock | grep -E "^[-+] {4}avo"
+```
+
+Now you have `before → after` per gem. **This is the input to everything downstream** — a `4.0.4 → 4.0.12` jump means every guide section between those two applies, and the same is true separately for each add-on.
+
+If a gem didn't move as far as expected, the Gemfile constraint from step 2 is capping it (see Gotchas). Fix the constraint and re-run rather than assuming there was nothing to update.
+
+### 5. Apply the crossed guide sections, oldest first
+
+Fetch the upgrade guide for the major version you're on (4.x → `upgrade.md`; a jump still inside 3.x → the 3.0 page; **3.x → 4.x → stop and use the Avo 3 → Avo 4 guide instead**, that's a much bigger, chapter-by-chapter job with its own procedure).
+
+Guide sections are headed by version (`## Upgrade to 3.22.0`, `## Upgrade from 3.16.2 to 3.16.3`) or by the change itself when a version only shipped one. Some are per-add-on (`## Upgrade to avo-kanban 0.1.18`). A version section may hold **several named changes**, each with its own "Action required" note — work them all, not just the first. A `## Unreleased — …` section at the very top describes changes that have landed on `main` but aren't in a released gem yet; skip it unless the app tracks Avo from git. Newest is at the top — **read up, then apply down.**
+
+For each section between your before and after versions:
+
+1. **Inventory first.** Grep for the API the section touches *before* changing anything. Most sections won't apply to a given app.
+2. Mark it **APPLIES / NOT USED / NEEDS REVIEW** in the log. Never apply a change for an API the app doesn't use.
+3. If it applies, make the edit, then boot the app and re-run the tests.
+4. Commit per section, with the version in the message.
+
+Sections often link a deeper page (i18n, appearance, actions) — fetch and follow it rather than guessing the new API.
+
+Watch for **silent behavior changes**: a section that changes a *default* rather than an API name passes every test and still changes what users see. Flag each one to the user explicitly instead of just ticking it off.
+
+If a version in your range has no guide section, check the GitHub releases for it — the guide only documents changes that need action, so silence is usually (but not always) fine.
+
+### 6. Keep a log as you go
+
+Write it incrementally, not at the end — if the run stops halfway, the log is the handoff. Put it at the repo root as `avo-update-<from>-to-<to>.md`:
+
+```markdown
+# Avo update log — 4.0.4 → 4.0.12
+
+Scratch notes from an assisted Avo update on 2026-07-24. Not part of the app —
+**safe to delete once the upgrade is reviewed and merged.**
+
+## Versions
+
+| Gem          | Before  | After   |
+| ------------ | ------- | ------- |
+| avo          | 4.0.4   | 4.0.12  |
+| avo-kanban   | 0.1.17  | 0.1.18  |
+
+## Guide sections
+
+| Section                                    | Status      | What changed |
+| ------------------------------------------ | ----------- | ------------ |
+| Resource and field translations verbatim    | APPLIED     | Capitalized 14 entries in `config/locales/avo.pt-BR.yml` |
+| avo-kanban 0.1.18                           | NOT USED    | App has no kanban boards |
+| …                                           | NEEDS REVIEW | … |
+
+## Manual verification needed
+
+- Things the tests can't catch — icons, avatars/covers, custom CSS on renamed
+  variables, anything visual.
+```
+
+The "safe to delete" line goes in the log itself — the user will find this file later and needs to know it isn't app code.
+
+### 7. Start the app back up
+
+Check the project's own instructions for how — in this order: `AGENTS.md`, `CLAUDE.md`, `.claude/CLAUDE.md`, `README.md`, `Procfile.dev` / `bin/dev`. If the project documents a dev-server command, run it (restarting it if you stopped it in step 1) and confirm the admin boots.
+
+**If no command is documented, don't guess** — say so and ask. A wrong `rails s` in a Procfile/overmind project just fights the real process.
+
+## Key commands
+
+| Command | Does |
+| --- | --- |
+| `grep -E "^ {4}avo(-[a-z_]+)? \(" Gemfile.lock` | Current version of every Avo gem — run **before** updating |
+| `bin/rails avo:update` | `bundle update --conservative` across Avo core + every registered plugin |
+| `git diff Gemfile.lock \| grep -E "^[-+] {4}avo"` | The actual before → after jump per gem |
+| `bundle update --conservative avo …` | Manual fallback when the rake task isn't available |
+| `bundle outdated \| grep avo` | What's available above the current Gemfile constraints |
+| `rake avo:build-assets` | Recompile assets — only for GitHub-sourced installs (**avo-setup**) |
+
+## Gotchas
+
+- **`avo:update` is bounded by the Gemfile.** It runs `bundle update`, so a pin like `gem "avo", "~> 4.0.4"` or `"= 4.0.4"` caps the jump — the task reports success and nothing moves. Check the constraint in step 2, and loosen it deliberately (with the user) rather than silently.
+- **The rake task doesn't fail on a failed bundle.** It shells out with `system` and ignores the exit status, so a `403 Forbidden` on `packager.dev` or a resolution conflict prints an error while the task still exits 0. **Read the output and confirm with the lock diff** — never trust the exit code alone.
+- **It only updates plugins that are actually loaded.** The gem list comes from the registered plugin manager, so an Avo gem in an optional/skipped bundler group won't be updated. Cross-check the lock diff against the full gem list from step 2.
+- **Paid gems need the gem-server token to update, same as to install.** In a sandboxed or restricted-egress environment a correct token still 403s because `packager.dev` is blocked. See **avo-setup**.
+- **The update alone is not the upgrade.** Bumping the gems and skipping the guide is the single most common way an admin breaks after an "upgrade" — and the breakage often surfaces days later, in a view nobody opened.
+- **Apply sections oldest → newest.** They're written as a chain; applying 4.0.12's change before 4.0.7's can leave you editing code the earlier section was about to rename.
+- **Silent default flips pass tests.** Sections that change a default (authorization strictness, confirmation modals, expanded filters) break nothing visible in CI and change runtime behavior. Call these out individually.
+- **Add-on gems version independently.** `avo-kanban 0.1.17 → 0.1.18` has its own section even when Avo core barely moved. Work the lock diff, not just the core version.
+- **Assets after upgrade.** A GitHub-sourced install ships no precompiled assets — re-run `rake avo:build-assets` or the admin renders unstyled (**avo-setup**).
+- **Don't invent a migration.** If a version's change isn't in the guide or the release notes, stop and ask rather than guessing at the new API.
+
+## Report
+
+When done, tell the user:
+
+- The **jump per gem** (`avo 4.0.4 → 4.0.12`, plus each add-on), taken from the lock diff.
+- **Which guide sections applied**, which were skipped as not-used, and which need their judgement — and the files you edited for each.
+- Any **silent behavior change** you crossed, named explicitly, since tests won't surface it.
+- **Test status**: baseline vs. now, and whether the app boots.
+- **Where the log is** and that it's safe to delete after review.
+- Whether the app was **restarted** and how — or that no start command was documented, so you didn't guess.
+- Follow-ups: anything needing manual visual checks (icons, avatars/covers, custom CSS), plus **avo-troubleshoot** if something's still broken and **avo-setup** if a paid gem wouldn't bundle.

data/lib/avo/skills/bin/avo-skills-resolve

@@ -0,0 +1,242 @@
+#!/usr/bin/env bash
+#
+# Avo skills loader — resolves the skills that ship inside this app's locked Avo
+# gems, proves each resolved gem is the version the lock names, and prints the
+# combined index.
+#
+# Gemfile.lock is the inventory and the version oracle. `bundle show` is only one
+# path resolver among several: it exits non-zero on an unrelated Ruby-version
+# mismatch, and `gem which` happily returns a stale gem from another version, so
+# neither is trusted without the version assertion below.
+#
+# Exit 0 prints verified absolute paths and index content on stdout. Any failure
+# exits non-zero with a stable token on stderr. There is no soft-failure mode:
+# the caller must stop rather than fall back on prior knowledge of Avo.
+#
+# Usage: avo-skills-resolve
+
+set -uo pipefail
+
+
+fail() { printf 'avo-skills: error %s: %s\n' "$1" "$2" >&2; exit 1; }
+warn() { printf 'avo-skills: warning %s: %s\n' "$1" "$2" >&2; }
+
+# --- 1. Locate Gemfile.lock -------------------------------------------------
+
+find_lock() {
+  local dir="$PWD"
+  while [ "$dir" != "/" ]; do
+    [ -f "$dir/Gemfile.lock" ] && { printf '%s\n' "$dir/Gemfile.lock"; return 0; }
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+LOCK="$(find_lock)" || fail not_an_app \
+  "no Gemfile.lock found in $PWD or any parent directory. This does not look like a Ruby app; do not guess an Avo version."
+APP_ROOT="$(dirname "$LOCK")"
+
+# --- 2. Parse the lock ------------------------------------------------------
+#
+# Top-level specs are indented exactly four spaces; their dependencies get six,
+# so the anchored pattern below never mistakes a dependency for an installed gem.
+# The section (GEM/PATH/GIT) is carried through because a path- or git-sourced
+# gem legitimately has no version to assert against.
+
+LOCK_ENTRIES="$(awk '
+  /^(GEM|PATH|GIT)$/            { section = $1; next }
+  /^[A-Z]/                      { section = "" ; next }
+  section == ""                 { next }
+  /^    [^ ]+ \([^)]+\)$/ {
+    name = $1
+    gsub(/[()]/, "", $2)
+    print name "|" $2 "|" section
+  }
+' "$LOCK")"
+
+avo_line="$(printf '%s\n' "$LOCK_ENTRIES" | grep -m1 '^avo|' || true)"
+[ -n "$avo_line" ] && [ -z "${avo_line##avo|*}" ] || fail avo_not_locked \
+  "the avo gem is not in $LOCK. This app does not use Avo, or its bundle is not installed."
+
+# --- 3. Validate every parsed name and version (never trust the lock) -------
+
+valid_name()    { [[ "$1" =~ ^[a-z0-9_]+(-[a-z0-9_]+)*$ ]]; }
+valid_version() { [[ "$1" =~ ^[0-9]+(\.[0-9a-zA-Z]+)*$ ]]; }
+
+AVO_GEMS=""
+while IFS='|' read -r name version section; do
+  [ -z "$name" ] && continue
+  case "$name" in avo|avo-*) ;; *) continue ;; esac
+  valid_name "$name" || fail malformed_lock \
+    "gem name '$name' in $LOCK is not a valid gem name. Refusing to build a path from it."
+  valid_version "$version" || fail malformed_lock \
+    "version '$version' for gem '$name' in $LOCK is not a valid version string."
+  AVO_GEMS+="$name|$version|$section"$'\n'
+done <<< "$LOCK_ENTRIES"
+
+lock_version_of() { printf '%s\n' "$AVO_GEMS" | awk -F'|' -v n="$1" '$1 == n { print $2; exit }'; }
+lock_section_of() { printf '%s\n' "$AVO_GEMS" | awk -F'|' -v n="$1" '$1 == n { print $3; exit }'; }
+
+# --- 4. Resolve a gem's path ------------------------------------------------
+#
+# Bundler subprocess stderr is discarded rather than inherited: bundler prints
+# configuration on some error paths, and this app's bundle may carry a private
+# gem-server credential that must never reach an agent transcript.
+
+resolve_path() {
+  local gem="$1" version="$2" candidate
+
+  # BUNDLE_GEMFILE wins over the working directory, so an agent invoked from
+  # inside any `bundle exec` context would otherwise resolve that outer bundle's
+  # Avo instead of this app's. Clear bundler's ambient state and resolve from the
+  # app root. (The version assertion below would catch the mismatch, but failing
+  # loudly on a question we can simply answer correctly is worse.)
+  candidate="$(cd "$APP_ROOT" && env -u BUNDLE_GEMFILE -u BUNDLE_BIN_PATH -u RUBYOPT bundle show "$gem" 2>/dev/null)"
+  if [ -n "$candidate" ] && [ -d "$candidate" ]; then
+    printf '%s\n' "$candidate"; return 0
+  fi
+
+  # `gempath` (plural) rather than `gemdir`: a bundle installed under a
+  # different Ruby or a custom GEM_HOME still shows up here.
+  # Same reason as above: bundler's RUBYOPT shim makes `gem env` report the
+  # active bundle's paths rather than the machine's real gem homes.
+  local gempaths
+  gempaths="$(env -u BUNDLE_GEMFILE -u BUNDLE_BIN_PATH -u RUBYOPT gem env gempath 2>/dev/null)"
+  if [ -n "$gempaths" ]; then
+    local IFS=:
+    for dir in $gempaths; do
+      [ -d "$dir/gems/$gem-$version" ] && { printf '%s\n' "$dir/gems/$gem-$version"; return 0; }
+    done
+  fi
+
+  candidate="$(find "$APP_ROOT/vendor/bundle" -maxdepth 4 -type d -name "$gem-$version" 2>/dev/null | head -1)"
+  if [ -n "$candidate" ] && [ -d "$candidate" ]; then
+    printf '%s\n' "$candidate"; return 0
+  fi
+
+  return 1
+}
+
+# Core keeps VERSION at lib/avo/version.rb; a feature gem keeps it at
+# lib/avo/<gem name minus the avo- prefix>/version.rb.
+version_file_for() {
+  local gem="$1" path="$2"
+  if [ "$gem" = "avo" ]; then
+    printf '%s\n' "$path/lib/avo/version.rb"
+  else
+    printf '%s\n' "$path/lib/avo/${gem#avo-}/version.rb"
+  fi
+}
+
+# Both quote styles are in use across the gem family — avo-audit_logging
+# declares VERSION with single quotes — so matching only double quotes would
+# fail the version assertion on a gem that is perfectly fine.
+installed_version_of() {
+  local file="$1"
+  [ -f "$file" ] || return 1
+  sed -n "s/.*VERSION *= *['\"]\([^'\"]*\)['\"].*/\1/p" "$file" | head -1
+}
+
+# Resolves, asserts, and echoes the gem's path. A path- or git-sourced gem is a
+# working tree, so its version legitimately differs from the lock — report the
+# source instead of failing.
+resolve_and_verify() {
+  local gem="$1" strict="$2" path locked installed section
+  locked="$(lock_version_of "$gem")"
+  section="$(lock_section_of "$gem")"
+
+  path="$(resolve_path "$gem" "$locked")" || {
+    [ "$strict" = "strict" ] && fail gem_not_on_disk \
+      "$gem $locked is in $LOCK but no matching gem is installed on disk. Run 'bundle install'. If the app pins a Ruby version this shell is not running, switch to it first — the gems live under that Ruby. Do not guess a path."
+    return 1
+  }
+
+  if [ "$section" != "GEM" ]; then
+    printf '%s\n' "$path"; return 0
+  fi
+
+  installed="$(installed_version_of "$(version_file_for "$gem" "$path")")" || {
+    [ "$strict" = "strict" ] && fail version_mismatch \
+      "cannot read a VERSION constant for $gem at $path. Refusing to use an unverified path."
+    return 1
+  }
+
+  if [ "$installed" != "$locked" ]; then
+    [ "$strict" = "strict" ] && fail version_mismatch \
+      "$LOCK says $gem $locked but the gem resolved at $path is $installed. Refusing to load skills that do not match this app's locked version."
+    return 1
+  fi
+
+  printf '%s\n' "$path"
+}
+
+# --- 5. Resolve avo itself, then read its package map -----------------------
+
+# `fail` inside a command substitution exits only that subshell, so the caller
+# must propagate the status — otherwise a hard failure would print its error and
+# then carry on resolving, which is the one thing this script must never do.
+AVO_PATH="$(resolve_and_verify avo strict)" || exit 1
+AVO_VERSION="$(lock_version_of avo)"
+AVO_SECTION="$(lock_section_of avo)"
+SKILLS_ROOT="$AVO_PATH/lib/avo/skills"
+PACKAGE_MAP="$SKILLS_ROOT/package-map.md"
+
+# Reachable because the deprecated avo-hq/skills channel hands the pointer to
+# everyone, including apps whose Avo predates gem-shipped skills. No minimum
+# version is named: this file is copied into the app and cannot be updated when
+# a release number turns out differently than planned.
+[ -f "$SKILLS_ROOT/index.md" ] || fail skills_not_shipped \
+  "avo $AVO_VERSION does not ship agent skills. Run 'bin/rails avo:update' to get a version that does, then re-run 'rails g avo:skills'. Until then use the documentation at https://docs.avohq.io — do not answer from prior knowledge of Avo."
+
+# The map is the trust boundary as well as the miss-path lookup: 'avo-' on
+# rubygems.org is an unreserved namespace, and loaded skill text becomes
+# instructions, so a gem name alone never earns that authority.
+allowlisted() {
+  [ -f "$PACKAGE_MAP" ] || return 1
+  grep -qE "^\| \`$1\` \|" "$PACKAGE_MAP"
+}
+
+# --- 6. Emit ----------------------------------------------------------------
+
+printf '# Avo skills for this app\n\n'
+printf 'avo %s' "$AVO_VERSION"
+[ "$AVO_SECTION" != "GEM" ] && printf ' (%s source — working tree, version not asserted)' "$(printf '%s' "$AVO_SECTION" | tr 'A-Z' 'a-z')"
+printf '\n%s\n\n' "$SKILLS_ROOT"
+
+cat "$SKILLS_ROOT/index.md"
+printf '\n' 
+
+printf '\n## Installed packages with their own skills\n\n'
+found_pkg=0
+while IFS='|' read -r name version section; do
+  [ -z "$name" ] || [ "$name" = "avo" ] && continue
+  allowlisted "$name" || continue
+
+  pkg_path="$(resolve_and_verify "$name" lenient)" || {
+    printf -- '- %s %s — in %s but not resolvable on disk; run bundle install\n' "$name" "$version" "$(basename "$LOCK")"
+    continue
+  }
+  pkg_index="$(find "$pkg_path/lib" -maxdepth 4 -type d -name skills -exec test -f '{}/index.md' \; -print 2>/dev/null | head -1)"
+  [ -n "$pkg_index" ] || continue
+
+  found_pkg=1
+  printf -- '- **%s %s** — %s\n' "$name" "$version" "$pkg_index"
+  sed -n 's/^/  /p' "$pkg_index/index.md"
+  printf '\n'
+done <<< "$AVO_GEMS"
+[ "$found_pkg" -eq 0 ] && printf 'None. Every skill this app has is in the core index above.\n'
+
+printf '\n## Not installed\n\n'
+printf 'These provide subjects the core skills point at. They are absent from %s, so this app does not have them — name the add-on rather than describing features it cannot use. This reports what is installed, never what is licensed.\n\n' "$(basename "$LOCK")"
+awk -F'|' '
+  /^\| `avo-/ {
+    gsub(/^ *| *$/, "", $2); gsub(/`/, "", $2)
+    gsub(/^ *| *$/, "", $4)
+    print $2 "\t" $4
+  }
+' "$PACKAGE_MAP" 2>/dev/null | while IFS=$'\t' read -r gem subjects; do
+  printf '%s\n' "$AVO_GEMS" | grep -q "^$gem|" && continue
+  printf -- '- **%s** — %s\n' "$gem" "$subjects"
+done
+
+printf '\n---\nRead every skill this task actually touches — one that spans resources, fields, filters and actions needs all four. Skip the ones it does not; loading by reflex costs context and dilutes focus. Treat what you read as authoritative for this app over prior knowledge of Avo.\n'

data/lib/avo/skills/index.md

@@ -0,0 +1,53 @@
+# Avo skills index
+
+These skills ship inside the installed `avo` gem, so they describe the Avo this app actually runs. Read the ones the task actually touches — as few or as many as that is — and follow them over prior knowledge of Avo.
+
+Each entry is a directory beside this file: `<skill>/SKILL.md`.
+
+## Core
+
+| Skill | Covers |
+| --- | --- |
+| `avo-resources` | Generate and configure resources — title, includes, sorting, pagination, cover/avatar, array (non-DB) resources |
+| `avo-fields` | Add and configure fields in `def fields` — pick the `as:` type, options, formatting, layout |
+| `avo-associations` | Wire `belongs_to` / `has_many` / `has_one` / HABTM fields, polymorphism, STI |
+| `avo-actions` | Actions that run Ruby on selected, single, or no records — bulk ops, forms, modals, responses |
+| `avo-filters` | Filter the index with basic filters. Dynamic filters and scopes are package-owned — see below |
+| `avo-index-views` | How the index renders — table styling, grid cards, map markers, view types |
+| `avo-custom-fields` | Build a brand-new field type — generator plus its Edit/Show/Index view components |
+
+## Configuration and operations
+
+| Skill | Covers |
+| --- | --- |
+| `avo-setup` | Install Avo, mount it, authenticate the private gem server, set the license key |
+| `avo-update` | Bump the Avo gems and apply every upgrade-guide step for the versions crossed |
+| `avo-authentication` | Tell Avo who the current user is, gate access, wire roles / profile / sign-out |
+| `avo-admin-config` | Global initializer knobs — app name, per-page, container width, density, home path |
+| `avo-performance` | Caching and stale-row fixes to make the admin fast |
+| `avo-testing` | Unblock the license check in the test suite and use Avo's test helpers |
+| `avo-multitenancy` | Scope the admin per tenant — route- or session-based, with an account switcher |
+
+## Customization
+
+| Skill | Covers |
+| --- | --- |
+| `avo-branding-appearance` | Logo, favicon, color scheme, palettes, CSS re-skin, icons |
+| `avo-menu-icons` | Pick the right Tabler icon and apply it to resources. The menu DSL is `avo-menu`'s own skill |
+| `avo-navigation-search` | Per-resource search, breadcrumbs, keyboard shortcuts, the auto-generated sidebar |
+| `avo-custom-ui` | Custom pages, embedded panels, dynamic/nested forms, ejected views, Stimulus, Tailwind |
+| `avo-i18n` | Translate and localize the admin — labels, locale switching, RTL |
+| `avo-controllers` | Override per-resource CRUD controller hooks and safely extend Avo's ApplicationController |
+| `avo-engine-internals` | `main_app`/`avo` helpers, `Avo::Current`, `ExecutionContext`, reserved names |
+| `avo-media-library` | Central asset browser and a picker inside rich-text editors |
+
+## Cross-cutting
+
+| Skill | Covers |
+| --- | --- |
+| `avo-aware` | Map a Rails change onto the admin surface it affects, and route the edit — the loader decides when this applies |
+| `avo-troubleshoot` | Diagnose a broken or misbehaving Avo app, organized by symptom |
+
+## Package-owned skills
+
+Features that live in their own gem ship their own skill. The loader lists the ones this app has installed and names the ones it does not, so nothing here points at a path that is absent. See `package-map.md` for the full map of gem to subject.

data/lib/avo/skills/package-map.md

@@ -0,0 +1,30 @@
+# Package map
+
+Every Avo gem that owns skills or is referenced by a core skill's pointer block.
+
+This file does two jobs for the skills loader:
+
+1. **Allowlist.** The loader reads a gem's skills index only when that gem is listed here. The `avo-` prefix on rubygems.org is unreserved, and loaded skill text becomes instructions the agent follows, so a gem name alone never grants that authority.
+2. **Miss-path map.** When a task's subject belongs to a gem this app does not have, the loader names the gem and what it provides instead of pointing at a path that is not there.
+
+The loader reports what is **installed**, never what is **licensed** — license state needs a runtime call the loader cannot make. A gem listed here and present in `Gemfile.lock` is treated as available.
+
+## Ships its own skills
+
+| Gem | Skill | Subjects | More |
+| --- | --- | --- | --- |
+| `avo-advanced_search` | `avo-advanced-search` | Cmd+K global search across resources; searchable association pickers | https://avohq.io/addons/global-search |
+| `avo-api` | `avo-rest-api` | JSON REST API over every resource, token auth, per-token permission matrix | https://avohq.io/addons/api |
+| `avo-audit_logging` | `avo-audit-logging` | Who changed and viewed what — timeline, diffs, revert | https://avohq.io/pricing |
+| `avo-authorization` | `avo-authorization` | Pundit policies for resources, actions, associations, files | https://avohq.io/addons/authorization |
+| `avo-collaboration` | `avo-collaboration` | Comments, reactions, automatic change-log on a record | https://avohq.io/addons/collaboration |
+| `avo-custom_controls` | `avo-custom-controls` | Take over the show/edit/index/row button bars | https://avohq.io/addons/custom-controls |
+| `avo-dashboards` | `avo-dashboards-cards` | Dashboards and the six card types — metrics, charts, tables, lists | https://avohq.io/addons/dashboards |
+| `avo-dynamic_filters` | `avo-dynamic-filters` | Filter the index by any column from a filter bar, Ransack authorization | https://avohq.io/addons/dynamic-filters |
+| `avo-forms` | `avo-forms-and-pages` | Model-agnostic forms and sidebar page hierarchies | https://avohq.io/addons/forms |
+| `avo-http_resource` | `avo-http-resource` | Back a resource with an external HTTP API instead of Active Record | https://avohq.io/addons/http-resource |
+| `avo-kanban` | `avo-kanban` | Database-backed drag-and-drop boards across resources | https://avohq.io/addons/kanban |
+| `avo-menu` | `avo-menu` | The sidebar menu editor DSL — sections, groups, links, dashboards, visibility, sub-items, profile and header menus | https://avohq.io/addons/menu-editor |
+| `avo-notifications` | `avo-notifications` | In-app notifications — bell dropdown, levels, action buttons, realtime | https://avohq.io/addons/notifications |
+| `avo-record_reordering` | `avo-record-reordering` | Persistent up/down and drag-and-drop record ordering | https://avohq.io/addons/record-reordering |
+| `avo-scopes` | `avo-scopes` | Scope tabs on the index — default view, counts, per-scope columns | https://avohq.io/addons/scopes |

data/lib/avo/version.rb

@@ -1,3 +1,3 @@
 module Avo
-  VERSION = "4.1.0" unless const_defined?(:VERSION)
+  VERSION = "4.1.2" unless const_defined?(:VERSION)
 end

data/lib/avo.rb

@@ -19,6 +19,10 @@ loader.inflector.inflect(
   "railtie_dsl" => "RailtieDSL"
 )
 loader.ignore("#{__dir__}/generators")
+# Shipped agent skills. Markdown alone is invisible to Zeitwerk, but a skill that
+# bundles a script makes its hyphenated directory eligible, and Zeitwerk then
+# raises trying to constantize e.g. `avo-menu-icons`.
+loader.ignore("#{__dir__}/avo/skills")
 loader.ignore("#{__dir__}/avo/engine_dsl.rb")
 loader.ignore("#{__dir__}/avo/plugin_dsl.rb")
 loader.ignore("#{__dir__}/avo/railtie_dsl.rb")