layered-resource-rails 0.1.0

data/README.md

@@ -0,0 +1,912 @@
+# layered-resource-rails
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Website](https://img.shields.io/badge/Website-layered.ai-purple)](https://www.layered.ai/)
+[![Demo](https://img.shields.io/badge/Demo-layered--resource--rails.layered.ai-purple)](https://layered-resource-rails.layered.ai/)
+[![GitHub](https://img.shields.io/badge/GitHub-layered--resource--rails-black)](https://github.com/layered-ai-public/layered-resource-rails)
+[![Discord](https://img.shields.io/badge/Discord-join-5865F2)](https://discord.gg/aCGqz9Bx)
+[![YouTube](https://img.shields.io/badge/YouTube-subscribe-FF0000)](https://www.youtube.com/@UseLayeredAi)
+[![X](https://img.shields.io/badge/X-follow-000000)](https://x.com/UseLayeredAi)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-follow-0A66C2)](https://www.linkedin.com/company/uselayeredai/)
+
+An open source, Rails 8+ engine that provides convention-over-configuration CRUD scaffolding. Define a resource class and a single route, and you get index, show, new/create, edit/update, and destroy actions with search and pagination. Built on top of [layered-ui-rails](https://github.com/layered-ai-public/layered-ui-rails), Ransack, and Pagy.
+
+## Why use it
+
+Most Rails apps need an admin area, an internal dashboard, or a "list and edit some records" screen long before they need anything bespoke. `layered-resource-rails` gets you there in a few lines, then stays out of your way as your needs grow:
+
+- **Skip the boilerplate.** Declare your columns, fields, and search - get index, show, forms, search, sort, and pagination for free. No scaffold to maintain, no half-finished admin gem to fight.
+- **Looks right out of the box.** Tables, forms, and pagination come pre-styled via [layered-ui-rails](https://github.com/layered-ai-public/layered-ui-rails) with WCAG 2.2 AA compliance and dark mode included.
+- **Override only what you need.** Swap a single view partial, subclass the controller for a custom scope or redirect, or generate plain ERB to take full control - without rewriting the rest.
+- **Eject cleanly if you outgrow it.** Generate a standard Rails controller and views, drop the gem, and you're left with idiomatic Rails. No lock-in, no hidden coupling.
+
+## Agent skill
+
+An [agent skill](https://agentskills.io) is included so AI coding agents can work with `layered-resource-rails` in your project. Once installed, the agent can handle the full setup - just ask it to add `layered-resource-rails` to your app and it will install the gem, scaffold resources, and wire up routes.
+
+**Project install** - scoped to a single repo, available to all contributors:
+
+```bash
+bin/rails generate layered:resource:install_agent_skill
+```
+
+**Global install** - available across all your projects:
+
+```bash
+./install-skill.sh
+```
+
+Or install remotely without cloning the repo:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/layered-ai-public/layered-resource-rails/main/install-skill.sh | sh
+```
+
+## Requirements
+
+- Ruby on Rails >= 8.0
+- [layered-ui-rails](https://github.com/layered-ai-public/layered-ui-rails) ~> 0.25 (>= 0.25.1)
+- Ransack ~> 4.0
+- Pagy ~> 43.2
+
+## Getting started
+
+Add to your Gemfile and install:
+
+```bash
+bundle add layered-resource-rails
+```
+
+`layered-resource-rails` depends on `layered-ui-rails` for its UI. If you haven't already set it up, run its install generator:
+
+```bash
+bin/rails generate layered:ui:install
+```
+
+## Quick start
+
+The fastest path: scaffold the model, migration, resource, and route in one shot.
+
+```
+rails g layered:resource:scaffold post title:string body:text
+```
+
+This invokes Rails' built-in `model` generator (so you get the migration and model), writes `app/layered_resources/post_resource.rb` with `columns` and `fields` derived from the attributes, and appends `layered_resources :posts` to `config/routes.rb`. Views are intentionally not generated - the gem's defaults render until you eject them with `rails g layered:resource:views posts`.
+
+Pass `--skip-model` if the model already exists. Restrict which CRUD actions get routed with `--actions index show` (emits `only:`) or `--except destroy` (emits `except:`). Pass `--controller` to also eject a controller and wire it into the route, or `--views` to eject the templates upfront.
+
+If the model already exists and you just want the resource class plus its route, use `rails g layered:resource post title:string body:text` instead. It writes `app/layered_resources/post_resource.rb` and appends `layered_resources :posts` - pass `--skip-route` to skip the route line.
+
+The rest of this section walks through what the generator produces.
+
+### 1. Define a resource
+
+Create a file at `app/layered_resources/post_resource.rb`:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  columns [
+    { attribute: :title, primary: true },
+    { attribute: :status },
+    { attribute: :created_at, label: "Published" }
+  ]
+
+  search_fields [:title]
+
+  default_sort attribute: :created_at, direction: :desc
+
+  fields [
+    { attribute: :title },
+    { attribute: :body, as: :text },
+    { attribute: :status }
+  ]
+end
+```
+
+### 2. Add the route
+
+In `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  layered_resources :posts
+end
+```
+
+That's it. You now have a full CRUD interface with search and pagination for `Post`.
+
+### What you get
+
+| Route                   | Action  | Description      |
+|-------------------------|---------|------------------|
+| `GET /posts`            | index   | Paginated table  |
+| `GET /posts/:id`        | show    | Post detail page |
+| `GET /posts/new`        | new     | New post form    |
+| `POST /posts`           | create  | Create post      |
+| `GET /posts/:id/edit`   | edit    | Edit post form   |
+| `PATCH /posts/:id`      | update  | Update post      |
+| `DELETE /posts/:id`     | destroy | Delete post      |
+
+The index table's primary column (`primary: true`, or the first column) links to each record's edit page - or, for read-only resources without an edit action, to its show page.
+
+Row actions (`Edit`/`Delete`) live in a popover menu in the table's last column. That column is pinned to the right-hand edge of the table's scroll container, so the actions menu stays reachable when a wide table scrolls horizontally.
+
+Each action also sets `@page_title` for use by the layout's `<title>` tag - `"Posts"` on index, `"New Post"` on new, the record's primary column value on show, and `"Edit <record label>"` on edit. Override after `super` in a custom action if you need something different.
+
+## Options
+
+**Read-only (no forms):** omit `fields` and restrict routes:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  columns [
+    { attribute: :title, primary: true },
+    { attribute: :created_at, label: "Published" }
+  ]
+end
+```
+
+```ruby
+layered_resources :posts, only: [:index]
+```
+
+**Restrict actions** with `only:` or `except:`:
+
+```ruby
+layered_resources :posts, only: [:index, :show, :edit, :update]
+layered_resources :posts, except: [:destroy]
+```
+
+The default `show` view is intentionally a blank canvas - the gem doesn't auto-render an attribute list, since generated detail pages tend to be low-value and always need customizing. The index links each record's title to its **edit** page, not its show page, so `show` is only worth keeping if you're going to build a real detail view (eject it with `rails g layered:resource:views` and fill in the template). If you're not, pass `except: [:show]` to drop the route.
+
+**Root breadcrumb:** top-level resources render no breadcrumb trail by default. Declare a static first crumb — typically a link back to the host app's dashboard:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  root_breadcrumb "Home", "/"
+end
+```
+
+Nested routes prepend it to the derived parent trail (e.g. Home / Users / Alice). Pass `nil` as the path to render unlinked text.
+
+**Record label:** a record is labelled by its **primary column** (the one marked `primary: true`, else the first) wherever the gem has to name it: the `show` and `edit` page titles, a row's actions menu, and its options in another resource's picker. Declare `label_attribute` when that column isn't the record's name — a `primary:` column rendered by a `render:` proc, say:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  columns [
+    { attribute: :headline, primary: true, render: ->(record, view) { view.tag.strong(record.headline) } },
+    { attribute: :created_at }
+  ]
+
+  label_attribute :title
+end
+```
+
+When the attribute has no value, the label falls back to the first of `name`/`title`/`label`/`email` that does, then to the model's own `to_s` if it defines one, and finally to `"Post #12"` — never a bare `#<Post:0x...>`.
+
+**Custom scope (e.g. tenant isolation):**
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  # ...columns, fields, etc.
+
+  def self.scope(controller)
+    controller.current_team.posts
+  end
+end
+```
+
+## Ownership
+
+For the common case where every record belongs to the signed-in user (or
+tenant), use the `owned_by` shorthand:
+
+```ruby
+class QuoteResource < Layered::Resource::Base
+  model Quote
+
+  owned_by :user                          # via :current_user (default)
+  # owned_by :account, via: :current_account
+end
+```
+
+`owned_by` is purely behavioural - it expands to:
+
+1. `scope(controller)` returns `Quote.where(user: controller.current_user)`,
+   so the index, show, edit, etc. only see records the user owns.
+2. `build_record(controller)` assigns the owner on new records, so `create`
+   stamps `user_id` automatically.
+3. When `controller.current_user` is `nil`, `owned_by` raises
+   `Layered::Resource::MissingOwnerError` so a missing `authenticate_user!`
+   surfaces immediately instead of every page silently 404ing. Pass
+   `allow_nil: true` for genuinely public-with-scope behaviour (returns
+   `Quote.none` and assigns nil on create). With `use_pundit`, the policy
+   gate (`policy.create?`) decides — `owned_by` lets nil through.
+
+`owned_by` is a fact about the data, not a gate on what users can do. For
+per-action authorisation ("can this user edit *this* record?") use
+`use_pundit` or override `scope` yourself.
+
+## Authorisation
+
+`scope(controller)` is the universal seam - any read filter (Pundit,
+CanCan, a plain PORO) goes there. The gem also ships first-class Pundit
+support via opt-in:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  use_pundit
+end
+```
+
+When enabled:
+
+- `scope(controller)` defaults to the controller's `policy_scope(model)` helper -
+  the index reads through `Policy::Scope#resolve`. This routes through
+  Pundit's `pundit_user`, so apps that authorize as `current_account` (or
+  any other identity) get the same context here as in `authorize` calls.
+- Every action that loads or builds a record (`new`, `create`, `show`,
+  `edit`, `update`, `destroy`, plus any custom member action declared in
+  a `layered_resources` block) calls `authorize(@record)` automatically.
+  Pundit raises `Pundit::NotAuthorizedError` on denial; handle it in
+  your `ApplicationController` as you would for any Pundit-backed app.
+- Action buttons hide automatically: the `New` link on the index, the
+  `Edit`/`Delete` items in the index row's actions popover, and the
+  `Edit`/`Delete` buttons on the show page check
+  `policy(record).new?/update?/destroy?` so users only see actions they
+  can perform.
+
+> **`verify_authorized` / `verify_policy_scoped`**: if your
+> `ApplicationController` runs Pundit's `after_action :verify_authorized`
+> (or `:verify_policy_scoped`) globally, layered resources that don't opt
+> into `use_pundit` will raise `AuthorizationNotPerformed` because the
+> controller never calls `authorize` for them. Either skip those checks
+> for the layered controller (`skip_after_action :verify_authorized,
+> if: -> { is_a?(Layered::Resource::ResourcesController) }`) or scope the
+> hardening to the controllers you actually want it on.
+
+`owned_by` composes with `use_pundit`: Pundit owns the read filter
+(`Policy::Scope` wins over the owner-where), and `owned_by` still drives
+owner assignment on `create`. Stack them when the policy needs to express
+more than ownership:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  use_pundit
+  owned_by :user
+end
+```
+
+CanCan, plain POROs, and bespoke policies are still supported - just
+override `scope` (and add per-action `before_action :authorize_*` callbacks
+in an ejected controller). Use `use_pundit` when Pundit is the right fit
+and you want the integration without writing it.
+
+### Writing policies
+
+Two conventions worth knowing:
+
+- **Compare ids, not associations.** Inside policy methods write
+  `record.user_id == user.id` rather than `record.user == user`. The id
+  comparison avoids loading the association and works on unsaved records.
+- **The policy queried matches the route, not the model being mutated.**
+  For a custom member action declared on `layered_resources :questions`
+  (e.g. `POST /questions/:id/submit_answer`), `@record` is a `Question`
+  and the gem calls `QuestionPolicy#submit_answer?` — even if the action
+  ultimately creates an `Answer`. Put the predicate on the policy for the
+  resource the route lives on.
+
+### Per-record gating in custom views
+
+Inside ejected views, the `resource_can?(action, record = nil)` helper
+returns `true` only when both the route exposes the action and (when
+Pundit is enabled) the policy permits it for the given record. Use it
+wherever you'd previously read `@resource_can_*`:
+
+```erb
+<% if resource_can?(:update, @record) %>
+  <%= link_to "Edit", edit_post_path(@record) %>
+<% end %>
+```
+
+The raw `@resource_can_*` ivars remain available for route-only checks
+(no per-record policy lookup).
+
+## Associations
+
+Resources are independent - each model gets its own resource class. To surface association data on an index, add a virtual column whose `attribute:` is a method on the model. For `Post belongs_to :user`, expose `user.name` by delegating on the model:
+
+```ruby
+class Post < ApplicationRecord
+  belongs_to :user
+  delegate :name, to: :user, prefix: true, allow_nil: true # post.user_name
+end
+```
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  columns [
+    { attribute: :title, primary: true },
+    { attribute: :user_name, label: "Author" },
+    { attribute: :created_at, label: "Published" }
+  ]
+end
+```
+
+### Searching across associations
+
+`search_fields` accepts association-walking entries in Ransack's `<association>_<attribute>` form. An entry that isn't a column on the resource's own model but matches an association plus a column on the associated model (e.g. `:user_name` for `belongs_to :user` and `users.name`) makes the index search box join into the association:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  search_fields [:title, :body, :user_name] # user_name searches users.name
+end
+```
+
+The Ransack allowlists are scoped to the resource: the association and the associated model's attribute are only ransackable when this resource is the one searching, so nothing else gains access to the associated model and any host-app Ransack config is preserved.
+
+A walked search field is also sortable — `q[s]=user_name asc` orders the index by `users.name` — because Ransack derives its sort allowlist from the search allowlist. Associations not declared in `search_fields` stay unsearchable and unsortable.
+
+### Search placeholder
+
+The index search box's placeholder is derived from `search_fields` via `human_attribute_name`, so attribute renames declared in the standard Rails i18n location flow through automatically. Given `search_fields [:title, :user_sid]`:
+
+```yaml
+# config/locales/en.yml
+en:
+  activerecord:
+    attributes:
+      user:
+        sid: Identifier
+```
+
+produces "Search by title, user identifier". Association walks are labelled `<association> <attribute>`, each half resolved against its own model's human names (so translating `post.user` changes the "user" half too).
+
+To replace the derived text wholesale, declare `search_placeholder`:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  search_fields [:title, :body, :user_sid]
+
+  search_placeholder "Search by title, body or author identifier"
+end
+```
+
+### Nested routes
+
+To scope posts to a user (`/users/:user_id/posts`), nest the route inside a Rails `resources :users do` block or an explicit `scope "users/:user_id"`. Either form produces the standard Rails nested-resources helper names (`user_posts_path`, `user_post_path`, `new_user_post_path`, …) — `polymorphic_path([@user, :posts])` and `link_to "Edit", [@user, @post]` resolve to them with no extra wiring:
+
+```ruby
+# config/routes.rb
+layered_resources :users
+
+resources :users, only: [] do
+  layered_resources :posts
+end
+# …or, equivalently…
+scope "users/:user_id" do
+  layered_resources :posts
+end
+```
+
+> **Don't add `as:` to a surrounding `scope`.** `layered_resources` derives its own helper names from the path segments (`scope path: "manage"` → `manage_posts_path`, `new_manage_post_path`, …), so an `as:` is unnecessary — and a value that disagrees with the path is ignored with a warning.
+
+Resolve the parent in the resource's `scope`:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  # ...columns, fields, etc.
+
+  def self.scope(controller)
+    if controller.params[:user_id].present?
+      User.find(controller.params[:user_id]).posts
+    else
+      Post.all
+    end
+  end
+end
+```
+
+### Linking columns to a nested index
+
+A column on the parent can link to its children's index using `link:` with the nested route's key:
+
+```ruby
+class UserResource < Layered::Resource::Base
+  model User
+
+  columns [
+    { attribute: :name, primary: true },
+    { attribute: :email },
+    { attribute: :posts_count, label: "Posts", as: :badge, rounded: true, link: :user_posts }
+  ]
+end
+```
+
+The `posts_count` cell on each user row links to `/users/:id/posts`. `link:` wraps the column's normal rendering in a link, so it composes with `as:` — pair it with `as: :badge` if you want a badge link.
+
+**Use a counter cache for child counts, not a virtual `child.size` column.** Render the count as a rounded badge (`as: :badge, rounded: true`) so it reads as a count, not a value. Point the column at a real counter-cache attribute and add `counter_cache: true` to the child's `belongs_to`:
+
+```ruby
+class Post < ApplicationRecord
+  belongs_to :user, counter_cache: true   # maintains users.posts_count
+end
+```
+
+```ruby
+# add_column :users, :posts_count, :integer, default: 0, null: false
+```
+
+A counter-cache column reads straight off the parent row, so the index renders in one query. A virtual column backed by `user.posts.size` issues a `COUNT` per row (an N+1) and can't be sorted or searched. Once `posts_count` is a real column it sorts via `q[s]=posts_count asc` like any other.
+
+## Filters
+
+Where `search_fields` gives a single free-text box, `filters` adds structured controls for narrowing the index by specific attributes. The UI follows the "add filter" pattern: an **Add filter** button opens a popover listing the declared filters; picking one adds it as a **tag** with its controls popover already open, ready to take a value; pressing the tag's label reopens the popover, and its ✕ removes it. Booleans and short single-choice selects apply instantly on click; multi-selects, comboboxes, ranges, and text filters have an Apply button.
+
+Under the hood every filter is a Ransack predicate in the query string, so filters compose with search, sort, and pagination — all coexist in the URL and survive each other's submits (the search form and each filter form round-trip the other params as hidden fields; no JavaScript involved). The lightweight `f[]` param records which tags were added and in what order — new tags join the end of the row (after any pinned ones) and stay put when set; a tag's ✕ removes its entry.
+
+Declare `filters` with a list of attributes. The control and predicate are inferred from each column:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  filters :status,         # enum column     -> multi-select of its values        (status_in)
+          :featured,       # boolean column  -> Yes / No                           (featured_eq)
+          :created_at,     # date/datetime   -> from / to date range               (created_at_gteq / _lteq)
+          :comments_count, # integer/decimal -> from / to number range             (comments_count_gteq / _lteq)
+          :user            # belongs_to      -> multi-select of associated records (user_id_in)
+end
+```
+
+| Column type | Control | Ransack predicate |
+| --- | --- | --- |
+| `enum` | multi-select of the enum's values | `_in` (or `_eq` with `multiple: false`) |
+| `boolean` | Yes / No | `_eq` |
+| `date` / `datetime` | from–to date range | `_gteq` + `_lteq` |
+| `integer` / `decimal` / `float` | from–to number range | `_gteq` + `_lteq` |
+| `belongs_to` | multi-select of associated records | `<foreign_key>_in` (or `_eq`) |
+| `string` / `text` | text "contains" (multi-select if a `collection:` is given) | `_cont` (or `_in` / `_eq`) |
+
+Select-type filters default to **multi-select**: filtering via the `_in` predicate. Pass `multiple: false` for a single-choice select via `_eq`.
+
+A `belongs_to` filter keys on the **foreign-key column** (`user_id`), so it never joins — no association-walk setup is needed, unlike `search_fields`. By default its options are `klass.all`, labelled by the first present of `name`/`title`/`label`/`email`; pass a `collection:` to scope, order, or label differently. As with search, every filtered attribute is added to the resource's Ransack allowlist; attributes that are neither shown, searched, nor filtered stay un-queryable and any `q[...]` referencing them is silently ignored rather than raising.
+
+### Long option lists
+
+How a select-type filter renders depends on how many options it turns out to have — a checkbox list of every user is no way to pick one:
+
+| Options | Multi-select | Single-choice |
+| --- | --- | --- |
+| up to 10 | checkbox list, Apply button | list of links, applying instantly on click |
+| more than 10 | [combobox](https://github.com/layered-ai-public/layered-ui-rails) — type-ahead, selections become removable tokens | single-select combobox, Apply button |
+
+The count is taken per request (a `collection:` callable resolves first), so a filter follows its data rather than a guess made when the resource was written. The threshold is global:
+
+```ruby
+# config/initializers/layered_resource.rb
+Layered::Resource.filter_combobox_threshold = 25
+```
+
+Declaring `as:` pins the control and opts out of the switch entirely — `as: :select` keeps the plain list however long it gets, `as: :combobox` uses the combobox however short:
+
+```ruby
+filters status: { as: :combobox },   # always the type-ahead
+        user:   { as: :select }      # always the checkbox list
+```
+
+### Remote filter options
+
+Past a few thousand records, rendering the options at all is the problem. Point a filter at an endpoint with `url:` and its options are fetched as the user types instead — the filter is then always a combobox, since there is no collection to render or count:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  filters user: { url: -> { user_options_path }, min_chars: 2 }
+end
+```
+
+Give `url:` as a callable so it resolves per request in the view, where route helpers are available. The endpoint is an ordinary action in your app — the gem never routes it — so it's authorised however any index is:
+
+```ruby
+class UserOptionsController < ApplicationController
+  include Layered::Ui::ComboboxOptions
+
+  def index
+    render json: l_ui_combobox_options(policy_scope(User), label: :name, search: [:name, :email])
+  end
+end
+```
+
+A remote combobox has no collection in the browser to look a label up in, so an active filter's current values are labelled server-side from the records themselves (the same `name`/`title`/`label`/`email` fallbacks) — the tag reads "User: Alice", not "User: 12". A `url:` on a plain column has no records to read, so its values label themselves.
+
+> **Label lookups are not scoped.** Whatever scoping the `url:` endpoint applies covers the options it *serves*; it does not cover the labels. Current values arrive in the query string, and the gem labels them with an unscoped `klass.where(id: ...)` — so hand-editing `?q[user_id_in][]=` to an id outside the endpoint's scope still renders that record's label in the tag and the combobox token. This is the same position a `belongs_to` filter's default `klass.all` options take, and it discloses one label at a time; treat it as a reason not to rely on a filter's option scoping to keep an association's names or e-mail addresses private.
+
+`min_chars:` and `text:` pass through to `l_ui_combobox` alongside `url:`. The write-side combobox options (`create:`, `create_name:`, `reorder:`) don't: a filter picks among values that already exist.
+
+### Overriding the inference
+
+Pass an options hash per attribute to override what's inferred:
+
+```ruby
+filters :created_at,
+        status: { collection: %w[draft live] },       # override the select options
+        user:   { multiple: false,                    # single-choice (user_id_eq) instead of multi
+                  collection: -> { User.active } },   # scope the options per request
+        title:  { as: :string, label: "Headline" }    # force a "contains" text filter
+```
+
+Recognised keys:
+
+- `as:` — force a control type (`:select`, `:combobox`, `:boolean`, `:string`, `:range`, `:date_range`). Naming `:select` or `:combobox` also pins the control against the [option-count switch](#long-option-lists).
+- `collection:` — options for a select: an array of values, an array of `[label, value]` pairs, or a callable resolved per request (returning either form, or records). A `collection:` on a plain string column promotes it to a select.
+- `multiple:` — `true` (the default for select-type filters) filters via the `_in` predicate; `false` gives a single-choice `_eq`.
+- `url:`, `min_chars:`, `text:` — [remote options](#remote-filter-options), fetched from an endpoint as the user types.
+- `label:` — override the filter's name (defaults to `human_attribute_name`, so i18n flows through).
+- `pinned:` — always show the tag. Pinned tags never appear in the add-filter menu and have no remove ✕ (their popover's Clear resets the value; the tag stays).
+- `default:` — value applied when the request carries none of the filter's params: a scalar, `{ from:, to: }` for ranges, an array for `multiple:`, or a callable resolved per request (e.g. `-> { { from: 7.days.ago.to_date } }`).
+
+### Pinned tags and defaults
+
+```ruby
+filters :created_at,
+        status: { pinned: true, default: Post.statuses[:published] },
+        user:   { pinned: true }
+```
+
+Pinned filters render as tags from the start, so the common ones are one click away instead of two; the **Add filter** button only renders while there are unpinned filters left to add (pin everything and it disappears). A `default:` applies whenever the request carries no state for that filter — the tag shows it as active and every link and form round-trips it explicitly from then on. Clearing a defaulted filter writes an explicit blank (`q[status_eq]=`) rather than dropping the param, so the default doesn't immediately re-apply.
+
+The filter bar renders inside the index's Turbo frame between the search box and the table; eject the views (`rails g layered:resource:views`) to customise placement — the bar is the `_filters` partial, and each control is `_filter_control`.
+
+## Column rendering
+
+Each column on the index table is rendered through a partial. By default the gem picks one based on the model's column type (`text` for strings, `datetime` for timestamps, etc.), but you can pin a column to a specific renderer with `as:`:
+
+```ruby
+columns [
+  { attribute: :title, primary: true },
+  { attribute: :status, as: :badge, variants: { published: :success, draft: :warning } },
+  { attribute: :priority, as: :badge, rounded: true },
+  { attribute: :created_at, as: :datetime, format: "%Y-%m-%d" },
+  { attribute: :pinned, as: :boolean, true_label: "Yes", false_label: "No" }
+]
+```
+
+The built-in column types are `:text`, `:datetime`, `:badge`, and `:boolean`. Lookup order is per-resource → host-wide → gem default, so any partial you place at `app/views/layered/<resource>/columns/_<type>.html.erb` overrides the gem's built-in for that resource only, and one at `app/views/layered/resource/columns/_<type>.html.erb` overrides it host-wide.
+
+Use the column generator to eject a built-in or scaffold a new one:
+
+```bash
+rails g layered:resource:column badge              # eject the built-in host-wide
+rails g layered:resource:column badge posts        # eject scoped to PostResource
+rails g layered:resource:column priority_badge     # scaffold a brand-new type
+```
+
+A custom partial receives `record`, `value`, and `options` (the column hash) as locals - read keys like `:variants` or `:format` straight off `options`.
+
+### Sortable headers
+
+A column header renders a sort link only when the attribute is sortable. This defaults to `true` for real DB columns and `false` for anything else - virtual attributes and delegated association values - because Ransack can't sort those without the associated model allowlisting the underlying field, and the sort link would 500 when clicked. Set `sortable: true` on the column to opt back in; you're then responsible for that model's `ransackable_attributes` (see [Associations](#associations)).
+
+```ruby
+columns [
+  { attribute: :title, primary: true },
+  { attribute: :user_name, label: "Author", sortable: true }
+]
+```
+
+## Index introduction
+
+To render an introduction above the search area on a resource's index page, drop a partial at `app/views/layered/<resource>/_introduction.html.erb`. It's rendered when present and skipped otherwise — no DSL or configuration needed.
+
+```erb
+<%# app/views/layered/posts/_introduction.html.erb %>
+<div class="l-ui-mt-4">
+  <p>Browse the latest posts. Use search and sort to find what you're looking for.</p>
+</div>
+```
+
+The partial sits inside the resource's view directory, so it follows the same per-resource override path as ejected views and column partials.
+
+## Record pickers
+
+A field naming a `belongs_to`'s **foreign key** is a record picker, so it renders as a single-select [combobox](https://github.com/layered-ai-public/layered-ui-rails) - a type-ahead input whose selection becomes a removable token - over the associated records, rather than as the number the column happens to hold:
+
+```ruby
+fields [
+  { attribute: :title },
+  { attribute: :user_id, label: "Author" }   # belongs_to :user -> author picker
+]
+```
+
+The default options are `klass.all`, labelled the same way a `belongs_to` filter's are (the first present of `name`/`title`/`label`/`email`, else `"User #12"`), and resolved per request rather than once at boot. The picker posts the plain foreign key (`post[user_id]`), so nothing else in the write path changes.
+
+Two things follow from the association rather than the column:
+
+- **Required.** A `belongs_to` validates the presence of the *association*, not of the foreign key, so the picker's required flag comes from the association's own `optional:` (resolved as ActiveRecord resolves it, via `belongs_to_required_by_default`) instead of from a presence validator on the column.
+- **Polymorphic associations are skipped.** There is no single class whose records could fill the picker, so the field falls back to its column type.
+
+Override with `as:` to opt out of the control entirely, or `collection:` to keep it and replace the options - to scope them, order them, or label them by a particular resource:
+
+```ruby
+fields [
+  { attribute: :user_id, as: :select, collection: -> { User.pluck(:name, :id) } },  # plain <select>
+  { attribute: :editor_id, collection: -> { User.editors.map { |u| [UserResource.record_label(u), u.id] } } }
+]
+```
+
+Note that the default labelling deliberately does **not** consult the associated model's own resource for its `label_attribute`: a model can have several resources (a plain one and an admin variant, say), so there is no single resource to ask. Name one in a `collection:` when you want its labelling.
+
+Every other combobox option - `multiple:`, `url:`, `min_chars:`, `create:`/`create_name:`, `reorder:`, `text:` - passes straight through to `l_ui_combobox`.
+
+## Strong parameters for nested or array fields
+
+By default each entry in `fields` is permitted as a scalar. To allow an array (e.g. `has_many_attached`) or a nested hash (e.g. `accepts_nested_attributes_for`), set `permit:` on the field:
+
+```ruby
+fields [
+  { attribute: :title },
+  { attribute: :documents, as: :file, permit: [] },                  # array of files
+  { attribute: :address_attributes, permit: [:street, :city, :zip] } # nested hash
+]
+```
+
+`permit: []` produces `params.permit(documents: [])`; `permit: [:street, :city]` produces `params.permit(address_attributes: [:street, :city])`.
+
+## Custom member and collection routes
+
+To add non-CRUD actions (e.g. `POST /posts/:id/approve`, `POST /posts/bulk_archive`), pass a block to `layered_resources` with the same `member`/`collection` DSL Rails' `resources` uses. A block requires `controller:` because the action implementation has to live somewhere - generate a controller subclass with `rails g layered:resource:controller posts` and point the route at it:
+
+```ruby
+layered_resources :posts, controller: "posts" do
+  member do
+    post :approve
+  end
+
+  collection do
+    get :bulk_archive
+    post :bulk_destroy
+  end
+end
+```
+
+```ruby
+class PostsController < Layered::Resource::ResourcesController
+  def approve
+    @record.update!(approved: true)
+    redirect_to layered_member_path(@record), notice: "Post approved"
+  end
+
+  def bulk_archive
+    # render a confirmation page, run the archive, etc.
+  end
+end
+```
+
+Inside the controller, `@resource` is the resource class and the standard Rails `before_action`s from `ApplicationController` (e.g. `authenticate_user!`) still apply.
+
+**Auto-loaded `@record` (member actions only).** Custom member actions get `@record` set from `params[:id]` via `@resource.scope(self).find` before the action runs. This does not extend to collection actions — those have no `:id` and `@record` stays `nil`, so do any lookups yourself. Opt a member action out of the auto-load with `skip_before_action :load_layered_member_record, only: [:foo]` if it shouldn't 404 on a missing record (or shouldn't pay for the lookup).
+
+Path helpers available inside actions:
+
+- `layered_collection_path` — index path for the current resource. Raises if `:index` isn't routed.
+- `layered_member_path(record)` — show/update/destroy path for the current resource. Raises if no member route is registered.
+- `layered_routes.<helper>_path(...)` — any registered route, with parent params filled in from the current request.
+
+## Variants via inheritance
+
+For variants that warrant their own URL - typically a separate admin area - declare a subclass and register it on its own route. The subclass inherits `model`, `columns`, `fields`, `search_fields`, `search_placeholder`, `default_sort`, `per_page`, and `root_breadcrumb` from the parent and overrides only what differs:
+
+```ruby
+# app/layered_resources/admin/post_resource.rb
+class Admin::PostResource < PostResource
+  columns [
+    { attribute: :title, primary: true },
+    { attribute: :status },
+    { attribute: :author_name, label: "Author" },
+    { attribute: :created_at, label: "Published" }
+  ]
+
+  fields [
+    { attribute: :title },
+    { attribute: :body, as: :text },
+    { attribute: :status },
+    { attribute: :pinned, as: :checkbox }
+  ]
+end
+```
+
+```ruby
+# config/routes.rb
+layered_resources :posts
+namespace :admin do
+  layered_resources :posts, resource: "Admin::PostResource"
+end
+```
+
+`search_fields` and `model` aren't redeclared - they're inherited from `PostResource`.
+
+## Authentication
+
+`Layered::Resource::ResourcesController` inherits from your app's `ApplicationController`, so any `before_action` you've declared there (e.g. Devise's `authenticate_user!`) already protects every layered resource request.
+
+### Engines: route to your engine's `ApplicationController`
+
+For an engine with its own `ApplicationController` (running its own `authorize`/`authenticate` chain), define a sibling controller and include the gem's concern:
+
+```ruby
+# app/controllers/layered/assistant/resources_controller.rb
+class Layered::Assistant::ResourcesController < Layered::Assistant::ApplicationController
+  include Layered::Resource::Controller
+end
+```
+
+Then pass `namespace:` so `layered_resources` derives both the resource class and the controller from one option:
+
+```ruby
+# config/routes.rb (or your engine's routes)
+scope path: "/assistant", module: "layered/assistant" do
+  layered_resources :skills, namespace: "Layered::Assistant"
+end
+```
+
+This resolves to `resource: "Layered::Assistant::SkillResource"` and routes to `Layered::Assistant::ResourcesController` automatically — no per-route `resource:`/`controller:` plumbing.
+
+`namespace:` is explicit-only. Avoid wrapping in a `namespace :foo` block: Rails composes URL helpers differently inside one (e.g. `foo_new_post_path` instead of `new_foo_post_path`), and the gem-shipped views call the latter form. Use `scope path:`/`module:` as above to get the path/module without the `:as` prefix.
+
+## Flash messages
+
+Flash strings come from i18n. The gem ships English defaults under `layered.resource.flash.*`:
+
+| Key | Trigger |
+|---|---|
+| `created` | `create` succeeded |
+| `updated` | `update` succeeded |
+| `deleted` | `destroy` succeeded |
+| `not_deleted` | `record.destroy` returned false |
+| `dependent_records` | `destroy` rescued `ActiveRecord::InvalidForeignKey` or `ActiveRecord::DeleteRestrictionError` (the gem catches these so dependent-record violations redirect with a flash instead of 500ing) |
+
+Override per-locale by adding the same keys in your host app's `config/locales/<lang>.yml`:
+
+```yaml
+en:
+  layered:
+    resource:
+      flash:
+        created: "%{model} added successfully"
+        dependent_records: "Can't delete %{model} — it still has linked records."
+```
+
+The `%{model}` interpolation is `model.model_name.human`, so it picks up any `activerecord.models.<key>` translations you've already defined.
+
+## Show is intentionally minimal
+
+The default show view is a heading with `Edit` and `Delete` buttons - it
+doesn't iterate over `columns` because columns are designed for table cells
+and have no per-user gating. If a column is configured for the index it
+would otherwise leak in full on show. When you want a real detail page,
+eject views with `rails g layered:resource:views <name>` and write the show
+template against `@record` directly.
+
+## Escape hatching
+
+The gem is designed so you can start fully managed and progressively take over control if you outgrow the defaults.
+
+**Override the scope or redirect target** directly in the resource class:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  # ...columns, fields, etc.
+
+  def self.scope(controller)
+    controller.current_team.posts
+  end
+
+  def self.build_record(controller)
+    scope(controller).build(author: controller.current_user)
+  end
+
+  def self.after_save_path(controller, record)
+    controller.main_app.post_path(record)
+  end
+end
+```
+
+**Eject views** when you need full control over presentation:
+
+```
+rails g layered:resource:views posts
+```
+
+This copies the gem's actual `index`, `show`, `new`, and `edit` templates into `app/views/layered/posts/` - fully populated, working ERB you can edit immediately. Delete any of them to fall back to the gem default; keep the rest to override only what you need.
+
+**Override the controller.** Use the generator to create one in the right place:
+
+```
+rails g layered:resource:controller posts
+```
+
+This gives you a controller that inherits from the base - override any of the standard CRUD actions and call `super` when you only want to tweak behaviour.
+
+If you outgrow the gem entirely, drop the inheritance and write a plain Rails controller:
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    @posts = Post.all
+  end
+
+  # ...
+end
+```
+
+```ruby
+# swap the route
+resources :posts
+```
+
+## Documentation
+
+A live demo of the dummy app is deployed at **[https://layered-resource-rails.layered.ai](https://layered-resource-rails.layered.ai)**.
+
+You can also run it locally to explore:
+
+```bash
+git clone https://github.com/layered-ai-public/layered-resource-rails.git
+cd layered-resource-rails
+bundle install
+cd test/dummy && bin/rails db:setup && bin/dev
+```
+
+### Deploying the dummy app
+
+The dummy app can be deployed with [Kamal](https://kamal-deploy.org). Set the required environment variables and deploy from `test/dummy`:
+
+```bash
+cd test/dummy
+export KAMAL_DEPLOY_IP=<server-ip>
+export KAMAL_DEPLOY_DOMAIN=<domain>
+export KAMAL_SSH_KEY=<path-to-ssh-key>
+kamal deploy
+```
+
+`KAMAL_DEPLOY_DOMAIN` defaults to `layered-resource-rails.layered.ai`. `SECRET_KEY_BASE` is read from `test/dummy/.kamal/secrets`, which is gitignored - create it locally before the first deploy.
+
+## Contributing
+
+This project is still in its early days. We welcome issues, feedback, and ideas - they genuinely help shape the direction of the project. That said, we're holding off on accepting pull requests for now to stay focused on getting the foundations right. Thank you for your patience and interest. See [CLA.md](CLA.md) for the full policy.
+
+## License
+
+Released under the [Apache 2.0 License](LICENSE).
+
+Copyright 2026 LAYERED AI LIMITED (UK company number: 17056830). See [NOTICE](NOTICE) for attribution details.
+
+## Trademarks
+
+The source code is fully open, but the layered.ai name, logo, and brand assets are trademarks of LAYERED AI LIMITED. The Apache 2.0 license does not grant rights to use the layered.ai branding. Forks and redistributions must use a distinct name. See [TRADEMARK.md](TRADEMARK.md) for the full policy.