avo 4.1.0 → 4.1.2

data/lib/avo/skills/avo-index-views/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: avo-index-views
+description: Control how records render on an Avo resource's Index screen — table styling, grid cards, map markers, and which view types are available. Use when the user wants to change how a list of records looks or behaves on the index. Avo phrasings ("enable grid view", "set default_view_type", "configure row_options", "add a map view", "restrict view_types") and Rails-shaped ones without naming Avo ("show these products as image cards", "put the stores on a map", "highlight failed orders in red", "gray out archived rows", "let users toggle between list and grid", "make grid the default", "add a data attribute / Stimulus controller to each row", "move the row action buttons to the left", "run an action on all matching records not just this page"). Not for authoring brand-new custom view types (that's plugin work — see avo-custom-ui).
+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 Index Views
+
+Everything here configures the **Index** screen of an Avo resource — the page that lists all records. You change it by setting **class attributes on the resource file** at `app/avo/resources/<model>.rb`, e.g. `class Avo::Resources::Product < Avo::BaseResource`. A few settings (global row-control defaults, the app-wide default view type) live in `config/initializers/avo.rb` inside `Avo.configure do |config|`.
+
+Avo ships three built-in index view types: **table** (default), **grid**, and **map**. A resource can offer several and let users switch between them; the current pick is persisted in the URL as `?view_type=`.
+
+**Docs** (fetch on demand — read the page before implementing that piece). Start from the docs map `https://docs.avohq.io/4.0/docs-map.md`, then:
+- Overview + choosing/restricting view types: `https://docs.avohq.io/4.0/views.md`
+- Table styling: `https://docs.avohq.io/4.0/table-view.md`, API `https://docs.avohq.io/4.0/table-view-api.md`
+- Grid cards: `https://docs.avohq.io/4.0/grid-view.md`
+- Map markers: `https://docs.avohq.io/4.0/map-view.md`
+- Select-all across pages: `https://docs.avohq.io/4.0/select-all.md`
+- Custom view types (plugin authoring, out of scope here): `https://docs.avohq.io/4.0/custom-view-types.md`
+
+Published under `https://docs.avohq.io/4.0/<page>.html`. Fetch with WebFetch if the local checkout isn't present.
+
+## When this applies
+
+Use this skill when the request is about the **appearance or behavior of the index list**, not the fields on it. Signals:
+
+- "Show X as cards / a gallery / a grid" → **grid view**.
+- "Put X on a map", geospatial data, latitude/longitude, stores/cities/locations → **map view**.
+- "Highlight / color / gray out / dim rows", per-row `class`/`data`/`title`, "add a Stimulus controller to each row" → **table `row_options`**.
+- "Move the action buttons", "controls are hidden behind columns", "reveal buttons on hover" → **row controls placement**.
+- "Let users switch between list and grid", "make grid/map the default", "only allow the table view" → **view types**.
+- "Run an action on every matching record, not just this page" → **select-all** (cross-links to `avo-actions`).
+
+**Not this skill:** inventing a brand-new view type (timeline, calendar, kanban) is plugin authoring — a ViewComponent inheriting `Avo::ViewTypes::BaseViewTypeComponent` registered from an engine. Mention it briefly and point to the **avo-custom-ui** skill and `https://docs.avohq.io/4.0/custom-view-types.md`. This skill only *enables and configures* built-in (or already-registered) view types.
+
+**License:** everything here is Community — no paid add-on required.
+
+## Workflow
+
+1. **Find the resource file.** Glob `app/avo/resources/*.rb` (and `**/*.rb` for namespaced ones). The class is `Avo::Resources::<Model>`. If the user named a model, match it; otherwise ask or infer from context.
+2. **Identify which knob.** Map the request to one of the sections below (table / grid / map / view types / select-all).
+3. **Read the resource** before editing so you preserve `def fields`, existing class attributes, and `self.includes`.
+4. **Read the relevant doc page** (see Docs above) to confirm option names and defaults before writing DSL — the surface is small but exact.
+5. **Apply the change** as a class attribute near the top of the class body (after `self.title` / `self.includes` if present, before `def fields`).
+6. **Keep `view_types` and `default_view_type` in sync** whenever you add a view — see Gotchas.
+7. **Report** what you changed and any follow-ups (gems, env vars, Tailwind classes, preloading).
+
+## View types
+
+### Choosing which view types are available
+
+Two independent attributes:
+
+- `self.default_view_type` — which view opens first. Defaults to `:table`. Also settable app-wide via `config.default_view_type` in the initializer.
+- `self.view_types` — which views appear in the switcher (restricts the set). When only one is available, the switcher is hidden.
+
+Adding `grid_view` or `map_view` config automatically adds that type to the switcher — you only need `view_types` to **restrict** or **reorder**.
+
+```ruby
+# app/avo/resources/city.rb
+class Avo::Resources::City < Avo::BaseResource
+  self.default_view_type = :grid          # opens in grid
+  self.view_types = [:table, :grid]       # switcher order follows this array
+end
+```
+
+Restrict to a single view (no switcher shown):
+
+```ruby
+self.view_types = :table
+```
+
+Decide per request with a block — has `current_user`, `params`, `record`, `resource` via `Avo::ExecutionContext`:
+
+```ruby
+self.view_types = -> do
+  current_user.admin? ? [:table, :grid] : :table
+end
+```
+
+`default_view_type` accepts a block too. "Make grid the default for everything" → set `config.default_view_type = :grid` in the initializer instead of per-resource.
+
+### Table view
+
+Default; needs no config. Two independent customizations: **row controls** (where the show/edit/delete/action buttons sit) and **`row_options`** (HTML attributes on each `<tr>`).
+
+**Row controls** — move or float the per-row buttons. Per resource:
+
+```ruby
+class Avo::Resources::User < Avo::BaseResource
+  self.row_controls_config = {
+    placement: :left,       # :right (default), :left, or :both
+    float: true,            # sticky to the row end with a gradient fade
+    show_on_hover: true     # hidden until the row is hovered
+  }
+end
+```
+
+Global default for all resources goes in the initializer:
+
+```ruby
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.resource_row_controls_config = { placement: :left, float: true, show_on_hover: true }
+end
+```
+
+`row_controls_config` merges over the global config, so set only the keys you change. `float` and `show_on_hover` are designed for `placement: :right`; other placements are allowed but may look off.
+
+**`row_options`** — declaratively set `<tr>` attributes per record. This is how you highlight/gray-out/tag rows or attach a Stimulus controller, without overriding the row component.
+
+```ruby
+# app/avo/resources/order.rb
+class Avo::Resources::Order < Avo::BaseResource
+  self.includes = [:customer]           # preload anything the blocks touch
+  self.table_view = {
+    row_options: {
+      class: -> {
+        case record.status
+        when "failed"  then "bg-red-50 dark:bg-red-950/30"
+        when "shipped" then "bg-emerald-50 dark:bg-emerald-950/30"
+        else ""
+        end
+      },
+      data: { controller: "highlightable", test_id: -> { "order-#{record.id}" } },
+      title: -> { "Order ##{record.id} — #{record.status}" }
+    }
+  }
+end
+```
+
+Each value is static or a `-> {}` block (the whole hash can also be one block). Blocks run **once per row, per render** through `Avo::ExecutionContext` with `record`, `resource`, `view` (`:index` on the main index, `:has_many` inside an association panel), plus `current_user`, `params`, view helpers. The same config also applies to `has_many` association tables listing this resource. Return `nil`/`false` to omit an attribute.
+
+Supported keys:
+- `class` — String, Symbol, Array, or `{ "cls" => bool }` hash (like Rails' `class_names`). Appended after Avo's classes, so they win at equal specificity.
+- `data` — hash of `data-*`, deep-merged with Avo's; `data-controller`/`data-action` are token-concatenated (yours added alongside Avo's, never replacing).
+- `style` — inline CSS string.
+- Other passthrough HTML attributes (`title`, `aria-label`, …).
+
+Common recipes:
+- **Gray out archived rows:** `class: -> { "opacity-60 italic" if record.archived? }`
+- **Colored left border by priority:** `style: -> { "border-left: 4px solid #{record.priority_color};" }`
+- **Theme-aware background via Avo's tokens:** `style: "background-color: var(--color-secondary);"`
+
+### Grid view
+
+Card layout for image-heavy resources. Enable by setting `self.grid_view` with a `card` block returning `cover_url`, `title`, `body`, and optional `badge`. The `card` block runs once per record through `Avo::ExecutionContext`.
+
+```ruby
+# app/avo/resources/product.rb
+class Avo::Resources::Product < Avo::BaseResource
+  self.default_view_type = :grid    # optional: open in grid
+  self.grid_view = {
+    card: -> do
+      {
+        cover_url: record.image.attached? ? main_app.url_for(record.image.variant(resize_to_fill: [300, 300])) : nil,
+        title: record.title,
+        body: simple_format(record.description),
+        badge: {
+          label: record.new? ? "New" : "Updated",
+          color: record.new? ? "green" : "orange",   # base or semantic color; unknown → neutral
+          style: record.new? ? "solid" : "subtle",   # subtle (default) | solid
+          title: "Availability",                       # tooltip
+          icon: "tabler/outline/trending-up"
+        }
+      }
+    end
+  }
+end
+```
+
+- `cover_url` — String; `nil` falls back to a placeholder image.
+- `title` — String.
+- `body` — String; HTML-safe strings render as HTML (use `simple_format`, `truncate`, etc.).
+- `badge` — optional hash: `label`, `color` (base colors like `red`/`blue`/`emerald`, or semantic `success`/`danger`/`warning`/`info`/`neutral`), `style` (`subtle`/`solid`), `title` (tooltip), `icon` (path like `"tabler/outline/…"` or `"heroicons/outline/…"`). Skipped entirely when both `label` and `icon` are blank.
+
+Restyle card wrappers with an `html:` block keyed by section → view → `wrapper` → `classes`:
+
+```ruby
+self.grid_view = {
+  card: -> { { cover_url: ..., title: record.name, body: record.excerpt } },
+  html: -> do
+    {
+      title: { index: { wrapper: { classes: "bg-blue-50 dark:bg-blue-900 rounded-md p-2" } } },
+      cover: { index: { wrapper: { classes: "rounded-lg overflow-hidden" } } }
+    }
+  end
+}
+```
+
+Grid has **no per-card HTML-attribute API** — `row_options` is table-only. `html:` styles the card sections, not the card container.
+
+### Map view
+
+Plot records with geospatial data on a Mapbox map. Enable with `self.map_view`.
+
+```ruby
+# app/avo/resources/city.rb
+class Avo::Resources::City < Avo::BaseResource
+  self.map_view = {
+    mapkick_options: { controls: true },
+    record_marker: -> {
+      {
+        latitude: record.coordinates.first,
+        longitude: record.coordinates.last,
+        tooltip: record.name
+      }
+    },
+    map: { position: :left },      # :left | :right | :top | :bottom — table takes the other side
+    table: { visible: true }       # show the index table alongside the map
+  }
+end
+```
+
+Options:
+- `mapkick_options` — forwarded to the [mapkick gem](https://github.com/ankane/mapkick). Avo sets a default `style` and always controls `height` (any `height` you pass is overwritten).
+- `record_marker` — Proc evaluated per record; must return a hash with `latitude` and `longitude` (optionally `tooltip`, `label`, `color`). Markers missing lat/long are skipped. Default reads `record.coordinates.first`/`.last`. Use this block to source coordinates from anywhere (API, cache), not just the DB.
+- `map` — `{ position: … }` places the map; the table takes the remaining side (`:left`/`:right` side-by-side, `:top`/`:bottom` stacked).
+- `table` — `{ visible: true|false }`; default renders no adjacent table.
+- `extra_markers` — Proc returning an array of marker hashes for points not backed by records.
+
+**Requirements** (report these): add the **`mapkick-rb`** gem (NOT `mapkick`) to the `Gemfile`, and set a valid `MAPBOX_ACCESS_TOKEN` env var from a [Mapbox](https://account.mapbox.com/auth/signup/) account.
+
+Make it the default with `self.default_view_type = :map`.
+
+### Select all across pages
+
+Not a view type — a table affordance. Checking the header "Select all" checkbox and confirming "select all matching" lets an action run on **every record the current query matches**, across all pages, not just the visible page. Avo serializes (and encrypts) the whole query — filters, sorting, scopes — and reconstructs it inside the action.
+
+It works out of the box on the table view; nothing to enable on the resource. The action itself is where the selection is consumed — cross-link the **avo-actions** skill for writing/handling the action. If serialization fails, Avo silently disables select-all rather than crashing (see the `normalizes` gotcha below).
+
+## Gotchas
+
+- **`view_types` / `default_view_type` must stay in sync with what's registered.** Requesting a view type not in the available list raises an error; rendering one that was never configured raises `Avo::ViewTypeComponentNotFoundError`. If you set `default_view_type = :grid`, make sure grid is actually configured (or in `view_types`).
+- **`row_options` values must be `String`/`Symbol`/`Integer`** (or `nil`/`false` to omit). A raw boolean like `record.archived?` raises `ArgumentError` — call `.to_s`: `data: { archived: -> { record.archived?.to_s } }`. `class:` additionally accepts Array and the `{class => bool}` hash form.
+- **Denied `<tr>` attributes** (raise `ArgumentError`, or in production fall back to defaults + log): `id`, `role`, `aria-selected`, any `on*` handler (`onclick`, …), `tabindex`, `contenteditable`, `draggable`. Use `data: { action: "..." }` (Stimulus) instead of `on*`. Reserved `data-*` keys Avo owns (silently ignored): `index`, `component_name`, `resource_name`, `record_id`, `resource_id`, `visit_path`, `reorder_target`.
+- **Custom Tailwind classes need the compiler to see them.** With Avo's [Tailwind CSS integration](https://docs.avohq.io/4.0/tailwindcss-integration.md), classes written **literally** inside blocks are scanned from `app/avo` and compiled. **Dynamically-built class names** (`"role-#{record.slug}"`, string concatenation) are invisible — register them with Tailwind v4's `@source inline(...)` in an Avo stylesheet. Without the integration (precompiled bundle only), no new utilities are generated at all — only classes already in Avo's bundle work.
+- **`row_options` blocks run per row, per render.** Preload every association they touch via `self.includes`, or you get an N+1 across every row. Keep blocks cheap.
+- **Dark mode is your responsibility** for user classes — pair `dark:` variants (`bg-blue-50 dark:bg-blue-950/40`) or use Avo's semantic CSS variables via `style:`. For custom backgrounds, use semitransparent values or explicit `hover:` variants so Avo's row hover/selection overlay still shows through.
+- **Map markers need `latitude` + `longitude`.** Records whose `record_marker` returns a hash missing either are silently dropped from the map.
+- **Select-all serialization can break on a model `normalizes` proc.** `normalizes :status, with: ->(s) { s }` combined with a filter on that attribute raises `TypeError: no _dump_data is defined for class Proc`, which auto-disables select-all. For apps created before Rails 7.1, set `config.active_record.marshalling_format_version = 7.1` in `config/application.rb`.
+- **Authoring a brand-new custom view type is out of scope.** Timeline/calendar/kanban views are plugin work (ViewComponent + engine registration). Point the user to the **avo-custom-ui** skill and `https://docs.avohq.io/4.0/custom-view-types.md`; here only enable built-in/registered types.
+
+## Report
+
+Tell the user:
+- Which resource file(s) and attribute(s) you changed (`self.table_view`, `self.grid_view`, `self.map_view`, `self.view_types`, `self.default_view_type`, `self.row_controls_config`, or the initializer).
+- Any external requirements: the `mapkick-rb` gem + `MAPBOX_ACCESS_TOKEN` for maps; the Tailwind integration and/or `@source inline(...)` for custom/dynamic classes; `self.includes` additions to avoid N+1.
+- If you set a `default_view_type`, confirm the matching view is configured/available so the switcher stays consistent.
+- For select-all or custom-view-type requests, note the cross-linked skill (**avo-actions**, **avo-custom-ui**) that carries the rest of the work.

data/lib/avo/skills/avo-media-library/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: avo-media-library
+description: Turn on and manage Avo's Media Library — a central browser/manager for every uploaded asset, plus an asset picker inside the trix, rhino, and markdown rich-text editors — configured in config/initializers/avo.rb. Use when the user wants to "let users upload and manage images", "have one place to view and manage all our assets/uploads", "add an image or asset gallery to the admin", "insert/pick an existing image in the rich-text editor while writing content", "reuse uploaded images across records", "a digital asset manager for the admin", or "browse all the files I've uploaded" — and when they want to turn the Media Library on or off, hide or conditionally show its sidebar item, re-add it to a customized menu, or disable the gallery picker on a markdown field. Disabled by default and gated behind `defined?(Avo::MediaLibrary)`; Community license; currently in Alpha (breaking changes expected).
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch
+metadata:
+  requires-gem: none — Community (Alpha)
+---
+
+> **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.
+
+# Enable and manage the Avo Media Library
+
+The Media Library is a central place to browse and manage every asset uploaded to an Avo admin, and it doubles as an asset picker inside Avo's three rich-text editors (`trix`, `rhino`, `markdown`) — a button in each editor opens a modal, and the selected asset is injected into the content. It is **not a separate gem**: it ships inside Avo, gated behind `defined?(Avo::MediaLibrary)`, and is **disabled by default**. All configuration lives in `config/initializers/avo.rb`.
+
+**License:** Community (free). **Status:** Alpha — future releases may contain breaking changes, so tell the user this and point them at the upgrade guide when they adopt it.
+
+**Docs** (fetch on demand — do not rely on memory for exact option names or defaults):
+- Docs map / index: https://docs.avohq.io/4.0/docs-map.md
+- Media Library guide: https://docs.avohq.io/4.0/media-library.md
+- Rich-text fields it plugs into: https://docs.avohq.io/4.0/fields/trix.md · https://docs.avohq.io/4.0/fields/rhino.md · https://docs.avohq.io/4.0/fields/markdown.md
+- Menu editor (for re-adding the item): https://docs.avohq.io/4.0/menu-editor.md
+- Blocks / `Avo::Current` in config lambdas: https://docs.avohq.io/4.0/execution-context.md
+
+## When this applies
+
+Reach for this skill when the goal is either of the Media Library's two jobs:
+
+1. **A central asset manager** — one screen to browse and manage all uploaded assets ("a gallery in the admin", "a digital asset manager", "see every file we've uploaded", "reuse images across records").
+2. **An asset picker in the editors** — inserting or reusing an existing image while writing rich-text content in a `trix`, `rhino`, or `markdown` field.
+
+Also use it for the on/off and visibility controls: enabling/disabling the whole feature, hiding or conditionally showing its sidebar item, re-adding it after the menu is customized, and toggling the picker off on a single markdown field.
+
+**Not this skill:**
+- Adding or configuring the rich-text field itself (which editor, its options) → **avo-fields**.
+- Re-ordering the sidebar, sections/groups, or the global search palette → **avo-navigation-search**.
+- Logos, colors, theming, menu/action icons → **avo-branding-appearance**.
+
+## Enable it
+
+The feature is off until you flip the killswitch. Always wrap the config in `if defined?(Avo::MediaLibrary)` so the initializer stays safe if the constant isn't loaded.
+
+```ruby
+# config/initializers/avo.rb
+if defined?(Avo::MediaLibrary)
+  Avo::MediaLibrary.configure do |config|
+    config.enabled = true
+  end
+end
+```
+
+`config.enabled` is the killswitch for the entire feature. While it's `false` (the default) the Media Library is unavailable to everyone: the sidebar item is hidden, all its routes are blocked, and the Media Library button is hidden in every editor. Note the block is `Avo::MediaLibrary.configure` (a separate object) — **not** the main `Avo.configure` block.
+
+## Workflow
+
+1. **Find the initializer.** It's `config/initializers/avo.rb`. `Grep` it for `Avo::MediaLibrary` to see whether a `configure` block already exists; add to it rather than creating a second one.
+
+2. **Turn it on** with the `Enable it` snippet above. This is the only step needed for "let users upload/manage assets" or "add an asset gallery". Mention the Alpha status.
+
+3. **Control the sidebar item (optional).** By default an enabled Media Library adds a sidebar item.
+   - Hide it outright with a Boolean:
+     ```ruby
+     if defined?(Avo::MediaLibrary)
+       Avo::MediaLibrary.configure do |config|
+         config.visible = false
+       end
+     end
+     ```
+   - Or show it conditionally with a block. The block runs through Avo's execution context, so it has access to `Avo::Current` (e.g. the current user):
+     ```ruby
+     if defined?(Avo::MediaLibrary)
+       Avo::MediaLibrary.configure do |config|
+         config.visible = -> { Avo::Current.user.is_developer? }
+       end
+     end
+     ```
+   `visible` only affects the menu item; it does not disable the feature. (When `enabled` is `false`, `visible` is moot — the killswitch already hides everything.)
+
+4. **Re-add it to a customized menu (if needed).** If the app defines a custom `config.main_menu` (see **avo-navigation-search**), the Media Library item does **not** appear automatically. Add it back as a `link_to` (or `link`) pointing at `avo.media_library_index_path`, inside the normal `Avo.configure` block:
+   ```ruby
+   # config/initializers/avo.rb
+   Avo.configure do |config|
+     config.main_menu = lambda {
+       link_to "Media Library", avo.media_library_index_path
+       # ...the rest of the custom menu
+     }
+   end
+   ```
+
+5. **Use it with the editors.** Once enabled, every `trix`, `rhino`, and `markdown` field automatically gets a Media Library button in its toolbar — no per-field opt-in. Just declare the field as usual (this is **avo-fields** territory):
+   ```ruby
+   field :body, as: :trix
+   field :body, as: :rhino
+   field :body, as: :markdown
+   ```
+
+6. **Disable the picker on a single markdown field (optional).** The `markdown` field accepts a `media_library` option (defaults to `true`). Set it to `false` to hide the gallery button on that one field while the Media Library stays enabled everywhere else:
+   ```ruby
+   field :body, as: :markdown, media_library: false
+   ```
+   This is **markdown-only** — `trix` and `rhino` have no per-field toggle. To remove the picker from those, the only lever is the global killswitch.
+
+7. **Report** what you changed (see below). No need to run the app; a `ruby -c` on the initializer is enough to sanity-check syntax.
+
+## Gotchas
+
+- **Alpha feature.** It's still in alpha and future releases may include breaking changes. Say so, and tell the user to watch the upgrade guide. Don't present it as stable.
+- **Always guard with `if defined?(Avo::MediaLibrary)`.** The docs wrap every `Avo::MediaLibrary.configure` call this way. Without the guard, an environment where the constant isn't present would raise on boot.
+- **`config.enabled` is an all-or-nothing killswitch.** Flipping it off hides the menu item, blocks the routes, *and* hides the editor icons — for everyone. There is no per-user or per-resource enable; use `config.visible` (a block) if you only want to gate who *sees the menu item*.
+- **`enabled` and `visible` are different levers.** `enabled` = whole feature on/off. `visible` = just the sidebar item (Boolean or block). Hiding the item with `visible = false` does not disable uploads or the editor picker.
+- **A customized menu drops the item.** If `config.main_menu` is defined, the Media Library sidebar item won't appear on its own — re-add it manually with `link_to "Media Library", avo.media_library_index_path`.
+- **`media_library: false` is markdown-only.** `trix` and `rhino` don't support per-field toggling; the killswitch is the only way to remove their buttons.
+- **It's `Avo::MediaLibrary.configure`, not `Avo.configure`.** The enable/visible settings live on their own configuration object. Only the menu `link_to` goes inside the main `Avo.configure` block.
+
+## Report
+
+After editing, tell the user:
+
+- The file you changed (`config/initializers/avo.rb`) and which block (`Avo::MediaLibrary.configure` and/or `Avo.configure`).
+- What you set: `config.enabled`, `config.visible` (Boolean or block), any `link_to` menu item, and any `media_library: false` on a markdown field.
+- That the feature is **Community-licensed** but in **Alpha**, so breaking changes are possible — watch the upgrade guide.
+- Whether the sidebar item will show, and for whom (if you used a `visible` block).
+- If they customized their menu: remind them the item only appears because you re-added the `link_to`.

data/lib/avo/skills/avo-menu-icons/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: avo-menu-icons
+description: >-
+  Choose semantically correct Tabler icons for Avo menu items and resources, and apply them. Use
+  when the user wants icons in the sidebar, an icon on a resource or dashboard, to populate
+  missing icons across the admin, or is migrating from Avo 3. Ships the icon list and the concept-
+  to-icon matching strategy. Applying an icon to a resource (`self.icon`) is Community and covered
+  here; placing one inside the initializer menu DSL needs the avo-menu add-on, whose own skill
+  covers that.
+allowed-tools: Read, Edit, Glob, Bash
+metadata:
+  requires-gem: none — icon selection and resource icons are Community; the initializer menu DSL needs avo-menu, which ships its own skill
+---
+
+> **These instructions ship inside the `avo` gem this app has locked, so they describe the version you are actually running.** Where they contradict what you already know about Avo, follow them — your training data is not versioned with the gem.
+
+# Add Icons to Avo Menu Items
+
+> **This skill picks the icon; `avo-menu` places it in the menu DSL.** Choosing a semantically right Tabler name, and setting `self.icon` on a resource, are Community and covered here. Writing that icon into `config.main_menu` is the `avo-menu` add-on, whose skill ships inside that gem.
+>
+> Re-run the Avo skills loader to check for `avo-menu` before routing to Approach A.
+
+Before doing anything, list the icon names available to this app. `<AVO_GEM_PATH>` is the path the Avo skills loader printed — this skill lives inside that gem, so build the path from it rather than from the app's working directory:
+
+```bash
+ruby <AVO_GEM_PATH>/lib/avo/skills/avo-menu-icons/scripts/list_icons.rb
+```
+
+That prints two lines, `outline: …` and `filled: …`, read straight from the installed `avo-icons` gem — no network call, so the names are exactly what this app can render. Pass `outline` or `filled` to get one style, or `--count` for just the totals.
+
+To use an icon, prefix the name with `tabler/outline/` or `tabler/filled/` — e.g. `icon: "tabler/outline/users"`. Only use names the command printed.
+
+---
+
+## Choosing an icon
+
+For each item without an icon, find the best-matching name from the outline list. Prefer outline icons; only use filled when it clearly fits better.
+
+**Matching strategy — try in order:**
+
+1. **Exact match** — the item name or a keyword from it appears verbatim in the list (e.g. `users` section → find `users`).
+2. **Semantic match** — the concept maps to a well-known icon. Common hints:
+
+   | Concept                    | Try these names                               |
+   | -------------------------- | --------------------------------------------- |
+   | Users / People / Members   | `users`, `user`, `user-circle`                |
+   | Posts / Articles / Blog    | `article`, `news`, `writing`                  |
+   | Orders / Purchases         | `shopping-cart`, `receipt`, `cash-register`   |
+   | Products / Items / Catalog | `package`, `box`, `tag`                       |
+   | Settings / Config          | `settings`, `adjustments`, `sliders`          |
+   | Reports / Analytics        | `chart-bar`, `chart-line`, `report-analytics` |
+   | Dashboard / Overview       | `layout-dashboard`, `dashboard`, `home`       |
+   | Comments / Reviews         | `message`, `message-circle`, `star`           |
+   | Teams / Organizations      | `users-group`, `building`, `hierarchy`        |
+   | Roles / Permissions        | `shield-lock`, `lock`, `key`                  |
+   | Media / Files / Uploads    | `photo`, `file`, `paperclip`                  |
+   | Tags / Labels / Categories | `tag`, `tags`, `bookmark`                     |
+   | Email / Notifications      | `mail`, `bell`, `send`                        |
+   | Calendar / Events          | `calendar`, `calendar-event`, `clock`         |
+   | Invoices / Billing         | `receipt`, `credit-card`, `currency-dollar`   |
+   | Geography / Locations      | `map-pin`, `map`, `globe`                     |
+   | Tools / Utilities          | `tool`, `tools`, `hammer`                     |
+   | External links             | `external-link`, `link`                       |
+   | Sign out / Logout          | `logout`, `door-exit`                         |
+   | Profile / Account          | `user-circle`, `id-badge`                     |
+
+3. **No match** — if nothing fits well, skip the item. Never force a generic placeholder.
+
+Always verify the chosen name exists in the icons list before using it.
+
+---
+
+## Determine the approach
+
+There are two ways to add icons in Avo. Identify which one to use:
+
+### Approach A — Initializer menu DSL
+
+Use this when `config/initializers/avo.rb` contains a `config.main_menu` or `config.profile_menu` block. Icons are added inline to the DSL calls inside those blocks. The menu DSL requires the `avo-menu` paid add-on — if it's not installed, use Approach B instead.
+
+### Approach B — Resource files
+
+Use this when the initializer has **no** `config.main_menu` / `config.profile_menu` block, meaning Avo auto-generates the sidebar from the registered resources. Icons are added via `self.icon` inside each resource class.
+
+**Decision rule:**
+
+1. If the user explicitly says which approach they want, use that.
+2. Otherwise, read `config/initializers/avo.rb`:
+   - If it contains `config.main_menu` or `config.profile_menu` → use **Approach A**.
+   - If neither block is present → use **Approach B**.
+
+---
+
+## Approach A — icons in the initializer menu DSL
+
+The `config.main_menu` / `config.profile_menu` DSL is the `avo-menu` add-on. Pick the icon name with the section above, then read the **avo-menu** skill — re-run the Avo skills loader and open the path it prints — for where `icon:` goes on each DSL call. If the loader reports `avo-menu` missing from `Gemfile.lock`, this app cannot use Approach A; use Approach B.
+
+## Approach B — Add icons in resource files
+
+### Step 1: Find all resource files
+
+Use Glob to find all Avo resource files, typically at `app/avo/resources/**/*.rb` or `app/avo/resources/*.rb`.
+
+### Step 2: Identify resources without icons
+
+Read each resource file. Check whether the class body already contains `self.icon`. Collect every resource that is missing it.
+
+The resource name is the class name without the `Resource` suffix (e.g. `Avo::Resources::UserResource` → `User`).
+
+### Step 3: Choose icons
+
+Apply the matching strategy from **Choosing an icon** above, using the resource name as the concept to match.
+
+### Step 4: Apply the changes
+
+For each matched resource, add `self.icon = "tabler/outline/{name}"` inside the class body, immediately after the class declaration line (or after any existing `self.model_class` / `self.label` declarations if present):
+
+```ruby
+class Avo::Resources::UserResource < Avo::BaseResource
+  self.icon = "tabler/outline/users"
+  # ... rest of resource
+end
+```
+
+- Preserve exact indentation and all existing content.
+- Do not add `self.icon` if one already exists.
+- One edit per file.
+
+### Step 5: Report
+
+Tell the user:
+
+- Total icons added
+- For each resource that got an icon: resource name → icon chosen, with a one-word reason
+- Any resources skipped because no good match was found

data/lib/avo/skills/avo-menu-icons/scripts/list_icons.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Lists every Tabler icon name Avo can render, grouped by style.
+#
+# The icons ship inside the `avo-icons` gem, which is a hard dependency of `avo`,
+# so this reads them off disk — no network call, no GitHub rate limit, and no
+# cache file. That matters here: this script lives inside an installed gem, and
+# gem directories are frequently read-only, so writing a cache next to it would
+# fail on exactly the machines it needs to work on.
+#
+# Usage:
+#   ruby list_icons.rb            # both styles
+#   ruby list_icons.rb outline    # one style
+#   ruby list_icons.rb --count    # just the totals
+
+require "rubygems"
+
+STYLES = %w[outline filled].freeze
+
+def icons_root
+  spec = Gem::Specification.find_all_by_name("avo-icons").max_by(&:version)
+  abort "avo-icons gem not found. It is a dependency of avo — run `bundle install`." if spec.nil?
+
+  root = File.join(spec.gem_dir, "lib", "assets", "svgs", "tabler")
+  abort "avo-icons #{spec.version} has no tabler icons at #{root}" unless Dir.exist?(root)
+
+  root
+end
+
+def names_for(root, style)
+  Dir.glob(File.join(root, style, "*.svg")).map { |p| File.basename(p, ".svg") }.sort
+end
+
+args = ARGV.dup
+count_only = args.delete("--count")
+styles = args.empty? ? STYLES : (args & STYLES)
+abort "unknown style. Valid styles: #{STYLES.join(", ")}" if styles.empty?
+
+root = icons_root
+
+styles.each do |style|
+  names = names_for(root, style)
+  if count_only
+    puts "#{style}: #{names.size}"
+  else
+    puts "#{style}: #{names.join(", ")}"
+  end
+end