avo 4.1.0 → 4.1.2

data/lib/avo/skills/avo-engine-internals/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: avo-engine-internals
+description: >-
+  The Rails-engine plumbing you touch when writing custom Ruby that runs inside Avo — engine path
+  helpers (`avo.` vs `main_app.`), `Avo::Current`, `Avo::ExecutionContext`, reserved model names
+  and route conflicts, `Avo::Services::EncryptionService`, and calling your app's helpers from
+  inside Avo. Use when the user wants to link from the admin back to their main app, fix
+  `undefined method 'posts_path'` inside Avo, access the current user / request / params / context
+  / tenant inside an Avo block, know which variables (`record`, `resource`, `view`,
+  `current_user`) a lambda gets or why `record` is nil, use an app view helper inside an Avo
+  field, fix a model named `resource` / `chart` / `search` / `home` that breaks the admin, keep a
+  reserved-name model while renaming its resource (`--model-class`), or encrypt a value to pass
+  through Avo params.
+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 Engine Internals
+
+Avo is a **Ruby on Rails engine** that runs isolated and side-by-side with the host app. The moment you write custom Ruby that executes *inside* Avo — a computed field, an action's `handle`, a controller override, a breadcrumb, a menu block, a card — you're on the engine's turf, and a handful of primitives govern how that code sees routes, request state, and app helpers. This skill owns those primitives:
+
+- **Path helpers** — `avo.` vs `main_app.` prefixes for isolated engine routing.
+- **`Avo::Current`** — per-request state (`user`, `params`, `request`, `context`, `view_context`, `locale`, `tenant`).
+- **`Avo::ExecutionContext`** — how your blocks receive `record` / `resource` / `view` / `current_user` and delegate to the view.
+- **Reserved model names** — names that collide with Avo's internal controllers/routes, and the escape hatches.
+- **`Avo::Services::EncryptionService`** — encrypt/decrypt values passed through params.
+
+These are cross-cutting: many other Avo features lean on them, but this is where they're documented. When another concern (a controller, a multitenant setup, a custom card) trips over one of these, it's this skill's territory. License: **Community** — none of this needs a paid gem.
+
+**Docs** — fetch on demand with WebFetch; prefer the raw `.md` (clean, no HTML):
+
+- Overview: https://docs.avohq.io/4.0/internals.md
+- Rails engines & path helpers: https://docs.avohq.io/4.0/rails-engines-paths.md
+- Avo ❤️ Rails & Hotwire (path helpers + using your helpers): https://docs.avohq.io/4.0/rails-and-hotwire.md
+- `Avo::Current`: https://docs.avohq.io/4.0/avo-current.md
+- `Avo::ExecutionContext`: https://docs.avohq.io/4.0/execution-context.md
+- Reserved model names & routes: https://docs.avohq.io/4.0/internal-model-names.md
+- `Avo::Services::EncryptionService`: https://docs.avohq.io/4.0/encryption-service.md
+- Docs map (find any other Avo page): https://docs.avohq.io/4.0/docs-map.md
+
+## When this applies
+
+Reach for this skill when a symptom or request points at the engine plumbing rather than a specific feature:
+
+| Symptom / request | Section |
+| --- | --- |
+| "Link from the admin back to my main app", `undefined method 'posts_path'` inside Avo, a link resolves to the wrong page | [Path helpers](#path-helpers-main_app-vs-avo) |
+| "Access the current user / request / params / context / tenant inside an Avo block", "set the tenant for this request" | [`Avo::Current`](#avocurrent) |
+| "What variables are available in this block?", "why is `record` nil in my lambda?", "use `record` / `resource` / `view` in a proc" | [`Avo::ExecutionContext`](#avoexecutioncontext) |
+| "Use my app's view helper (`link_to`, a custom formatter) inside an Avo field" | [`ExecutionContext`](#avoexecutioncontext) + [Using your app's helpers](#using-your-apps-helpers-inside-avo) |
+| Model named `resource` / `chart` / `search` / `home` / `attachment` breaks the admin, routing conflicts, `resources :resources` clash | [Reserved names](#reserved-names) |
+| "Encrypt a value to pass through Avo params", "decrypt what select-all sent" | [`EncryptionService`](#encryptionservice) |
+
+## Path helpers (`main_app` vs `avo`)
+
+Rails engines have **isolated routes**. Code running inside Avo resolves path helpers in Avo's route set by default, so a bare `posts_path` either raises `undefined method` or — worse, silently — resolves to a different route than you meant. Always prefix:
+
+```ruby
+# Avo's own routes (resources, tools, dashboards, media library, ...)
+avo.root_path
+avo.resources_users_path
+avo.resources_user_path(user)
+avo.resource_path(resource: UserResource, record: @user)
+
+# Your host application's routes
+main_app.root_path
+main_app.posts_path
+main_app.post_path(record)
+```
+
+This applies anywhere your code runs inside the engine: `Avo::ResourcesController` / `Avo::ToolsController` overrides, breadcrumbs configured in `config/initializers/avo.rb`, fields, actions, cards, custom tools, ejected partials.
+
+| You want to link to… | Prefix |
+| --- | --- |
+| Avo pages (resources, tools, dashboards) | `avo.` |
+| Your main application routes | `main_app.` |
+
+Inside an `ExecutionContext` block (fields, actions, most DSL lambdas) `main_app` and `avo` are already in scope as accessors — you can write `main_app.post_path(record)` directly without a receiver. See below.
+
+## `Avo::Current`
+
+`Avo::Current` is Avo's request-scoped state, built on [`ActiveSupport::CurrentAttributes`](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html). Avo populates it at the start of each request; read it from anywhere in your custom Ruby.
+
+| Attribute | What it is |
+| --- | --- |
+| `Avo::Current.user` | The authenticated user — whatever your `current_user_method` returns. |
+| `Avo::Current.params` | Equivalent to `request.params` (falls back to `{}` when there's no rack input). |
+| `Avo::Current.request` | The Rails `request` (an empty `ActionDispatch::Request` if none). |
+| `Avo::Current.context` | The `context` hash you configured in the initializer, evaluated in `Avo::ApplicationController`. |
+| `Avo::Current.view_context` | An `ActionView` context — call any helper/variable available in your partials, e.g. `Avo::Current.view_context.link_to "Avo", "https://avohq.io"`. |
+| `Avo::Current.locale` | The app locale for the request. |
+| `Avo::Current.tenant` / `Avo::Current.tenant_id` | **Writable.** Avo leaves these for you to set — assign the current tenant early (e.g. in an `Avo::ApplicationController` override) and read it back later in the request. |
+
+```ruby
+# Set the tenant for the current admin request (e.g. in a controller concern)
+Avo::Current.tenant = current_account
+Avo::Current.tenant_id = current_account.id
+
+# Read the current user anywhere in a resource/field/action
+Avo::Current.user
+```
+
+For a full multitenancy setup (scoping records, switching tenants, per-tenant menus) use the **avo-multitenancy** skill — `Avo::Current.tenant` is the primitive it builds on.
+
+## `Avo::ExecutionContext`
+
+Most Avo DSL blocks — computed fields, `visible`/`hide` lambdas, action `handle` context, dynamic options — don't run in a vacuum. Avo wraps them in an `Avo::ExecutionContext`: an object that holds request state and `instance_exec`s your block against it, so the right variables are simply *in scope*.
+
+```ruby
+field :full_name, as: :text do
+  "#{record.first_name} #{record.last_name}"   # `record` is provided by the ExecutionContext
+end
+```
+
+**Always in scope** (defaulted from `Avo::Current`): `context`, `current_user`, `params`, `request`, `view_context`, `locale`, `main_app`, `avo`.
+
+**Provided per-block**, depending on what's being evaluated: `record`, `resource`, `view`, and any other variable Avo (or you) passes in. This is why `record` exists in a field block but may be `nil` or absent in a block that isn't tied to a record — the variable is only there if that call site passed it.
+
+Two behaviors worth knowing:
+
+- **`delegate_missing_to :view_context`.** Any method the block calls that isn't a known accessor is forwarded to `view_context`. That means view helpers — `link_to`, `content_tag`, `image_tag`, and your app's own view helpers — are callable **directly** inside the block, no receiver needed.
+- **Only callables are executed.** `ExecutionContext` runs the target only if it `respond_to?(:call)`; a non-callable value (a plain string, symbol, boolean) is returned as-is. So `visible: false` and `visible: -> { view.show? }` both work — the lambda gets the context, the literal doesn't.
+
+You can drive it yourself when needed:
+
+```ruby
+Avo::ExecutionContext.new(
+  target: -> { "#{record.first_name} #{record.last_name}" },
+  record: User.first,
+  view: :index
+).handle
+```
+
+### `include:` — mix in modules
+
+Pass `include:` an array of modules to make their methods available inside the block:
+
+```ruby
+Avo::ExecutionContext.new(
+  target: -> { sanitize "<script>alert('be careful')</script>#{record.name}" },
+  record: record,
+  include: [ActionView::Helpers::SanitizeHelper]
+).handle
+```
+
+### Using your app's helpers inside Avo
+
+Three ways, from most to least direct:
+
+1. **View helpers, directly.** Because of `delegate_missing_to :view_context`, anything defined in `app/helpers` (or standard view helpers) is callable straight from an `ExecutionContext` block:
+
+   ```ruby
+   field :name, as: :text, format_using: -> { link_to value, main_app.post_path(record) }
+   ```
+
+2. **The `helpers` object.** Inside an `ExecutionContext` block, `helpers` returns an object with every module from `app/helpers` mixed in — handy when you want an explicit receiver:
+
+   ```ruby
+   # app/helpers/products_helper.rb defines `simple_name`
+   field :name, as: :text, format_using: -> { helpers.simple_name(value) }
+   ```
+
+3. **`view_context.controller`, from outside a block** (e.g. plain resource code or a controller). Include the helper module in the Avo controller, then reach it through the controller:
+
+   ```ruby
+   # app/controllers/avo/products_controller.rb
+   class Avo::ProductsController < Avo::ResourcesController
+     include ApplicationHelper
+   end
+
+   # app/avo/resources/product.rb
+   field :copyright, as: :text do
+     view_context.controller.render_copyright_info
+   end
+   ```
+
+   For controller overrides in general, see the **avo-controllers** skill.
+
+## Reserved names
+
+Avo dynamically maps models to internal controllers and routes, so a handful of model names **collide** with Avo's own controllers and will override built-in functionality or break routing. Avoid these model names:
+
+```
+action  appearance_settings  application  array  association  attachment
+base    base_application     chart        debug  home         media_library
+private resource             search
+```
+
+If you don't already have such a model, rename it (`user_resource` instead of `resource`, `advanced_search` instead of `search`, `graph` instead of `chart`).
+
+**Keep the model, rename the Avo resource** — when the model already exists and you can't rename it, generate the Avo resource under a different name but point it at the real model class:
+
+```sh
+bin/rails generate avo:resource user_resource --model-class resource
+```
+
+Generates `Avo::Resources::UserResource` and `Avo::UserResourcesController`, both backed by the existing `Resource` model — no collision.
+
+**Route helper clash with `resources :resources`.** A host-app route like `resources :resources` defines a `resources_path` helper that **overrides Avo's internal `resources_path`** and can break parts of the admin. Keep the URL, rename the helper:
+
+```ruby
+resources :resources, as: 'articles'   # URL stays /resources, helper becomes articles_path
+```
+
+## `EncryptionService`
+
+`Avo::Services::EncryptionService` encrypts and decrypts values so they can travel safely through params. Avo uses it internally (e.g. select-all serializes the query, encrypted, into the URL), and you can call it anywhere.
+
+```ruby
+# Strings
+token = Avo::Services::EncryptionService.encrypt(message: "Secret string", purpose: :demo)
+Avo::Services::EncryptionService.decrypt(message: token, purpose: :demo)
+# => "Secret string"
+
+# Objects — pass a serializer (Marshal handles ActiveRecord objects)
+token = Avo::Services::EncryptionService.encrypt(message: Course::Link.first, purpose: :demo, serializer: Marshal)
+Avo::Services::EncryptionService.decrypt(message: token, purpose: :demo, serializer: Marshal)
+```
+
+- `message:` (required) — the object to encrypt.
+- `purpose:` (required) — any symbol; it **must match** between `encrypt` and `decrypt` or verification fails.
+- Extra kwargs (e.g. `serializer:`) pass straight through to [`ActiveSupport::MessageEncryptor`](https://api.rubyonrails.org/classes/ActiveSupport/MessageEncryptor.html); use `serializer: Marshal` for non-string objects.
+- It derives the key from `Rails.application.secret_key_base`, so a `secret_key_base` must be defined — via `ENV["SECRET_KEY_BASE"]`, `Rails.application.credentials.secret_key_base`, or `Rails.application.secrets.secret_key_base`.
+
+## Gotchas
+
+- **Missing `avo.` / `main_app.` prefix is the #1 "extending Avo" footgun.** A bare path helper inside the engine raises `undefined method` — or, when both route sets define the same name, silently resolves to the *wrong* route with no error. Always prefix.
+- **Reserved model names collide with Avo's controllers.** A model named `resource`, `chart`, `search`, `home`, `attachment`, `association`, etc. overrides Avo's internal controllers/routes. Keep the model via `--model-class` (renaming only the Avo resource), and rename a conflicting `resources :resources` route helper with `as:`.
+- **`record` (or any per-block variable) only exists if the call site passed it.** `ExecutionContext` accessors like `context`/`current_user`/`request` default from `Avo::Current`, but `record`/`resource`/`view` are supplied per block. Referencing one where it wasn't passed gives `nil` (or `NameError`) — that's not a bug, it's the wrong block.
+- **`ExecutionContext` runs the target only if it `respond_to?(:call)`.** A non-callable value is returned untouched. If you expected your literal to be "evaluated," it wasn't — wrap it in a lambda.
+- **Delegation is to `view_context`, not `controller`.** Missing methods on an `ExecutionContext` go to `view_context`. To reach controller-level helpers you included in an Avo controller, go through `view_context.controller` explicitly.
+- **`EncryptionService` needs matching `purpose:` and a `secret_key_base`.** A mismatched `purpose:` between encrypt and decrypt fails verification; a missing `secret_key_base` raises. Use `serializer: Marshal` for anything that isn't a plain string.
+
+## Report
+
+When done, tell the user:
+
+- Which primitive you used and where (file + line): a path-helper prefix, an `Avo::Current` read/write, an `ExecutionContext` block, a reserved-name fix, or an `EncryptionService` call.
+- For path helpers: which prefix (`avo.` / `main_app.`) and why that route set.
+- For reserved names: the collision, and whether you renamed the model, used `--model-class`, and/or added `as:` to a route.
+- For `EncryptionService`: the `purpose:` used and whether a `serializer:` was needed — and remind them encrypt/decrypt must share both.
+- Any follow-up the user still owns: defining `secret_key_base`, wiring tenant scoping (**avo-multitenancy**), or a controller include (**avo-controllers**). Cross-link **avo-multitenancy**, **avo-controllers**, and **avo-custom-ui** when the work spills into their territory.

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

@@ -0,0 +1,219 @@
+---
+name: avo-fields
+description: Add or change fields in an Avo resource's `def fields` — pick the `as:` type, set options (required, default, help, visibility, formatting), and use computed and view-specific fields. Use when the user wants to add a field to an Avo resource, or — said without naming Avo — "add a status field to the Project model", "make the email field required", "show the user's avatar", "add a dropdown for order status", "the price should display as currency", "add a rich-text editor for the body", "hide the notes field on the index page", "add a star rating", "make the name column sortable", "show a badge for the order state", or "add a color picker / date picker / progress bar to a model". For belongs_to / has_many / has_one and other association fields, use the avo-associations skill instead.
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch
+metadata:
+  requires-gem: none — Community; some field types need companion gems (see Gotchas)
+---
+
+> **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 or change an Avo field
+
+In Avo (a Rails admin framework), the columns shown on a resource's Index, Show, New, and Edit pages are declared as **fields** inside the `def fields` method of `app/avo/resources/<model>.rb`. Almost every "add/change/hide a field on the X model" request lands in that one method.
+
+A field looks like:
+
+```ruby
+field :column_name, as: :field_type, **options
+```
+
+- `:column_name` — a database column **or** any method/attribute on the model.
+- `as: :field_type` — how it renders (`:text`, `:select`, `:boolean`, `:money`, …). Omit `as:` and it defaults to `:text`.
+- `**options` — label, visibility, formatting, validation cues, etc. (see [Key options](#key-options)).
+
+**Docs** (fetch on demand — do not rely on memory for exact option names):
+- Docs map / index: https://docs.avohq.io/4.0/docs-map.md
+- Declaring fields & view-specific methods: https://docs.avohq.io/4.0/fields.md
+- Common options (guide + full API): https://docs.avohq.io/4.0/field-options.md · https://docs.avohq.io/4.0/field-options-api.md
+- The ~38-type catalog (one page per type, with type-specific options): https://docs.avohq.io/4.0/fields/text.md — swap `text` for any type below. Fetch the specific type's page before using its niche options.
+- Layout DSL inside `def fields` (panels, tabs, sidebar, cards, columns): https://docs.avohq.io/4.0/fields-layout.md
+- Field discovery (auto-map columns/associations): https://docs.avohq.io/4.0/field-discovery.md
+- HTML attributes on a field: https://docs.avohq.io/4.0/html.md
+
+## When this applies
+
+Use this skill for anything **inside `def fields`** except associations:
+
+- Adding, removing, renaming, or reordering a field.
+- Changing a field's type (e.g. plain text → a `select` dropdown or a `badge`).
+- Setting options: required, default, help text, placeholder, disabled/readonly, sortable, visibility per view, formatting, copyable, etc.
+- Computed (block) fields that derive a value not stored in a column.
+- Arranging fields with the layout DSL (`panel`, `card`, `sidebar`, `tabs`/`tab`, `header`, column `width`).
+- Auto-generating fields with `discover_columns` / `discover_associations`.
+
+**Not this skill:**
+- `belongs_to`, `has_many`, `has_one`, `has_and_belongs_to_many` and other relationship fields → **avo-associations** skill.
+- Authoring a brand-new *custom field type* (a reusable component you invent) → **avo-custom-fields** skill. Note `rails g avo:field NAME` scaffolds a new custom type; it is **not** how you add a normal field — for that you just edit `def fields`.
+
+## Workflow
+
+1. **Find the resource file.** It's `app/avo/resources/<model>.rb` (singular, snake_case — e.g. the `Project` model → `app/avo/resources/project.rb`). If unsure, `Glob` `app/avo/resources/*.rb` or `Grep` for the model name. Read the file and locate `def fields` (or the view-specific methods below).
+
+2. **Confirm the backing attribute.** The first argument should match a real DB column or a model method. Check `db/schema.rb` (or the model) so you use the right column name and can pick a type that fits its data type. If the value isn't stored anywhere, it must be a [computed block field](#computed-block-fields).
+
+3. **Pick the field type** using the [decision table](#choosing-a-field-type). When in doubt, fetch that type's docs page.
+
+4. **Check for a gem gate.** A few types need a companion gem or ENV var and will error without it — see [Gotchas](#gotchas). If the user asks for one of those, tell them the gem to add.
+
+5. **Place the field** in the intended view(s). By default a field shows on all four views; use `def fields` for all views, or a view-specific method (below) when a view needs a different set. Respect existing ordering and formatting in the file.
+
+6. **Add options** — start minimal (`as:` + label if needed), then layer on only what the request asks for.
+
+7. **Report** what changed (see [Report](#report)). Don't run the app; if you want to sanity-check syntax, a `ruby -c` on the file is enough.
+
+### Which method to edit
+
+`def fields` is the catch-all used for every view when no more specific method exists. Override per view or per view-group only when a view genuinely needs a different set:
+
+| Method            | Applies to                        |
+| ----------------- | --------------------------------- |
+| `def fields`      | any view with no specific method  |
+| `def index_fields`| Index                             |
+| `def show_fields` | Show                              |
+| `def edit_fields` | Edit **and** Update               |
+| `def new_fields`  | New **and** Create                |
+| `def display_fields` | Index **and** Show             |
+| `def form_fields` | New, Create, Edit **and** Update  |
+
+Specific view methods beat view-group methods, which beat `fields`. Prefer a single `def fields` + per-field `hide_on:`/`only_on:` for small differences; reach for separate methods only when the field lists really diverge.
+
+## Choosing a field type
+
+Map the need to an `as:` type. All built-in types are **Community (free)**; the ⚠️ ones need a companion gem (see [Gotchas](#gotchas)).
+
+| The user wants…                                        | Use                          | Example |
+| ------------------------------------------------------ | ---------------------------- | ------- |
+| A short single-line string                             | `:text`                      | `field :title, as: :text` |
+| A long / multi-line string                             | `:textarea`                  | `field :body, as: :textarea` |
+| A number                                               | `:number`                    | `field :age, as: :number` |
+| A masked password input                                | `:password`                  | `field :password, as: :password` |
+| A yes/no checkbox                                      | `:boolean`                   | `field :active, as: :boolean` |
+| A hash of on/off toggles                               | `:boolean_group`             | `field :roles, as: :boolean_group, options: {admin: "Admin", editor: "Editor"}` |
+| A dropdown of fixed choices                            | `:select`                    | `field :type, as: :select, options: {Draft: :draft, Live: :live}` |
+| Multiple choices from a fixed set                      | `:select` (`multiple: true`) or `:checkbox_list` | `field :tags, as: :select, multiple: true, options: {...}` |
+| Radio buttons                                          | `:radio`                     | `field :plan, as: :radio, options: {...}` |
+| A country picker                                       | `:country`                   | `field :country, as: :country` |
+| A date                                                 | `:date`                      | `field :birthday, as: :date` |
+| A date **and** time                                    | `:date_time`                 | `field :published_at, as: :date_time` |
+| A time only                                            | `:time`                      | `field :opens_at, as: :time` |
+| A colored status pill (map value → color)              | `:badge`                     | `field :status, as: :badge, options: {success: "done", warning: "pending"}` |
+| A live status dot (loading/failed/success/neutral)     | `:status`                    | `field :state, as: :status, success_when: [:done], loading_when: [:running], failed_when: [:failed]` |
+| A tag input / list                                     | `:tags`                      | `field :skills, as: :tags` |
+| A star rating                                          | `:stars`                     | `field :rating, as: :stars` |
+| A progress bar (slider on forms)                       | `:progress_bar`              | `field :progress, as: :progress_bar` |
+| Editable flat JSON key/value pairs                     | `:key_value`                 | `field :meta, as: :key_value` |
+| Structured array data                                  | `:array`                     | `field :items, as: :array` |
+| A code editor (syntax-highlighted)                     | `:code`                      | `field :snippet, as: :code, language: "javascript"` |
+| The record id                                          | `:id`                        | `field :id, as: :id` |
+| A hidden form value                                    | `:hidden`                    | `field :token, as: :hidden` |
+| A section title between fields                         | `:heading`                   | `field :section, as: :heading` (layout, not a DB column) |
+| A hover preview icon on the Index row                  | `:preview`                   | `field :preview, as: :preview` |
+| A currency amount ⚠️                                    | `:money`                     | `field :price, as: :money, currencies: %w[USD EUR]` |
+| A rich-text WYSIWYG editor ⚠️ (recommended)            | `:rhino`                     | `field :body, as: :rhino` |
+| A GitHub-style Markdown editor ⚠️                       | `:markdown`                  | `field :body, as: :markdown` |
+| A simpler Markdown editor ⚠️                            | `:easy_mde`                  | `field :notes, as: :easy_mde` |
+| The Trix editor (ActionText)                           | `:trix`                      | `field :body, as: :trix` |
+| A single file upload (ActiveStorage)                   | `:file`                      | `field :cv, as: :file` |
+| Multiple file uploads                                  | `:files`                     | `field :docs, as: :files` |
+| An uploaded avatar image                               | `:avatar`                    | `field :photo, as: :avatar` |
+| A Gravatar from an email column                        | `:gravatar`                  | `field :email, as: :gravatar` |
+| An image from a stored URL                             | `:external_image`            | `field :logo, as: :external_image` |
+| A point on a map ⚠️                                      | `:location`                  | `field :coordinates, as: :location` |
+| A geographic area on a map ⚠️                            | `:area`                      | `field :zone, as: :area` |
+
+For anything relationship-shaped ("show the user's posts", "attach an author") use the **avo-associations** skill.
+
+## Key options
+
+Every field accepts these common options (full list + types at the field-options-api page). Pass a literal value or, unless noted, a lambda.
+
+- **`name`** — override the label (default is the humanized id). `field :is_available, as: :boolean, name: "Availability"`. For localized apps, translate via i18n instead of hardcoding.
+- **Visibility** — `hide_on:`, `show_on:`, `only_on:`, `except_on:` take `:index`, `:show`, `:new`, `:edit`, `:preview` plus shorthands `:forms` (new+edit), `:display` (index+show), and `:all` (only for `hide_on`/`show_on`). Example: `field :notes, as: :textarea, hide_on: [:index, :show]`.
+- **`visible:`** — a lambda for conditional display. It can see `context` and `resource`; the record is `resource.record`. On create the record is `nil`, so **use safe navigation**: `visible: -> { resource.record&.published? }`.
+- **`required:`** — adds an asterisk (cosmetic only; Avo adds it automatically when the model has a presence validator). Real enforcement is model validation.
+- **`disabled:`** vs **`readonly:`** — both render the input disabled on forms. `disabled:` **also ignores the value on save** (safe against DOM tampering). `readonly:` is UI-only — a user can re-enable it and submit; don't rely on it for protection.
+- **`default:`** — pre-fills the New form (and action modals): `default: -> { Time.current }`.
+- **`help:`** / **`label_help:`** — help text (HTML allowed) below the input (forms only) or below the label (every view).
+- **`placeholder:`** — placeholder for empty text-like inputs.
+- **`sortable:`** — makes the Index column sortable. `true` for real columns; a `-> { query.order(...) }` lambda (receives `query` and `direction`) for computed fields.
+- **`format_using:`** — reshape the displayed value. **Runs on form views too**, so branch on the view when the form should stay editable: `format_using: -> { view.form? ? value : value.upcase }`. View-scoped variants exist (`format_display_using`, `format_index_using`, `format_show_using`, `format_form_using`, …) — the most specific one wins, they don't chain.
+- **`update_using:`** — parse the raw form `value` before it's saved.
+- **`nullable:`** / **`null_values:`** — store empty input as `NULL` (optionally define which values count as null).
+- **`copyable:`** — clipboard icon on Show/Index. Copies the **displayed** (formatted) value.
+- **`link_to_record:`** — make the Index cell a link to the record. Only on `:id`, `:text`, `:gravatar`, and `belongs_to`.
+- **`for_attribute:`** — back the field with a different attribute than its id (lets you show one column two ways).
+- **`width:`** / **`stacked:`** — column width (`25/33/50/66/75/100`; any value <100 auto-stacks) and label-above-value layout.
+- **`html:`** — attach `style`/`classes`/`data` to the field's wrapper/label/input per view (e.g. right-align a number: `html: {index: {wrapper: {classes: "text-right"}}}`). See the html page.
+
+### Computed (block) fields
+
+When the value isn't a stored column, pass a block. Inside it you have `record`, `resource`, and `view`:
+
+```ruby
+field "Full name", as: :text do
+  "#{record.first_name} #{record.last_name}"
+end
+
+field "Has posts", as: :boolean do
+  record.posts.any?
+end
+```
+
+Block fields render **only on Index and Show** (they have no input) and **can't use `sortable: true`** (pass a sort lambda instead). Give them an explicit label string as the first argument.
+
+### Layout inside `def fields`
+
+The same method arranges fields. Use `panel`/`card` to group, `sidebar` (inside a panel) for compact fields, `tabs`/`tab` for tabbed sections, `header` to reposition the page chrome, and per-field `width:` for multi-column rows. This overlaps page-level layout — see the fields-layout docs page before building complex structures.
+
+```ruby
+def fields
+  field :id, as: :id
+  panel title: "Details" do
+    field :first_name, as: :text, width: 50
+    field :last_name,  as: :text, width: 50
+    sidebar do
+      field :active, as: :boolean, only_on: :show
+    end
+  end
+end
+```
+
+### Field discovery
+
+To auto-generate fields from the model instead of listing them, call `discover_columns` (columns, rich text, tags) and `discover_associations` (attachments, relationships). Scope with `only:`/`except:`, and pass any other keyword to forward it to every discovered field:
+
+```ruby
+def fields
+  discover_columns only: [:title, :body, :published_at]
+  discover_associations except: [:audit_logs]
+end
+```
+
+## Gotchas
+
+- **Gem-gated types break without their companion gem** (the field silently fails to render or raises). If the user asks for one, tell them to add the gem:
+  - `:rhino` → `gem "avo-rhino_field"`
+  - `:markdown` → `gem "marksmith"` + `gem "commonmarker"`
+  - `:money` → `gem "avo-money_field"` + `gem "money-rails", "~> 1.12"` (and `monetize :price_cents` on the model)
+  - `:location` / `:area` → `gem "mapkick-rb"` (**not** `mapkick`) + `MAPBOX_ACCESS_TOKEN` env var
+  - Reactive fields (`react_on:`) → `gem "avo-reactive_fields"`
+  - Some of these gems live on the `packager.dev` source — point the user to the Avo 4 upgrade guide's gems section.
+- **`tip_tap` is deprecated** — use `:rhino` for a WYSIWYG editor.
+- **`markdown` was renamed.** The old `markdown` field is now `easy_mde`; the new `markdown` is the Marksmith editor. Don't confuse them.
+- **`required:` and `readonly:` are cosmetic.** Enforce with model validations (`validates :x, presence: true`) and use `disabled:` when you need the value ignored on save.
+- **`format_using:` runs on form views too** — return the raw `value` when `view.form?` so the input stays editable, or use a `format_display_using:`/`format_*_using:` variant.
+- **Computed block fields** show only on Index/Show and can't be `sortable: true`.
+- **`visible:` lambdas see `resource.record == nil` on create** — always safe-navigate (`resource.record&.foo`).
+- **`select` takes exactly one of `options:`, `grouped_options:`, or `enum:`** — never combine them.
+- **Fields an external tool submits must still be declared** on the form views. If a resource tool renders the input, keep the field with `hide_on: :forms` so Avo can parse and save the value.
+- **`badge` vs `status`:** `badge` maps arbitrary values to colored pills (`options:`); `status` is a live indicator with `success_when:`/`loading_when:`/`failed_when:` arrays (everything else → neutral).
+
+## Report
+
+After editing, tell the user:
+
+- The file and method you changed (`app/avo/resources/<model>.rb` → `def fields`).
+- Each field added/changed: column, `as:` type, and any notable options.
+- Any gem or ENV var they must add for a gated type, and any model change needed (validation for `required`, `monetize` for money, an enum for an enum-backed select).
+- Which views the field now appears on, if you set visibility.