layered-resource-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 83a0686237527aabd89c6fa83f98c8a2bbab1a02deff48528e8e5baed7f8b874
+  data.tar.gz: 744e768aff2d5c624c9a243ccfbc9d92cf80de3a559fec9c320c89d51e7e197e
+SHA512:
+  metadata.gz: ebe053f334e9ad89c835add54f1c60bf5c8c863cb175ec42932e7d9cf0809eef73d65646a96505da64cd9062207dc722eb672d4662cad612ca70259eecac9c60
+  data.tar.gz: a148f47dc69bbd3fb799bd1b8b49d2b4bf90dbc3854e2c75fec7dd88dd5c8efcb8e99ec7af434d6c2b76370d2243ca3eb9f7d512113aeba3ae46effe8bc76194

data/.claude/skills/layered-resource-rails/SKILL.md

@@ -0,0 +1,449 @@
+---
+name: layered-resource-rails
+description: Installs, configures, and builds with the layered-resource-rails gem - a Rails 8+ engine providing convention-over-configuration CRUD scaffolding with search, sort, and pagination. Use when adding layered-resource-rails to a Rails app, defining resource classes, mounting `layered_resources` routes, ejecting views or controllers, or troubleshooting setup.
+license: Apache-2.0
+compatibility: Requires Ruby on Rails >= 8.0, layered-ui-rails ~> 0.9, ransack ~> 4.0, pagy ~> 43.2
+metadata:
+  author: layered.ai
+  version: "1.0"
+  source: https://github.com/layered-ai-public/layered-resource-rails
+---
+
+# layered-resource-rails
+
+A Rails 8+ engine that scaffolds CRUD UIs from a single resource class and a single route. Built on top of [layered-ui-rails](https://github.com/layered-ai-public/layered-ui-rails), Ransack, and Pagy.
+
+## Installation
+
+```bash
+bundle add layered-resource-rails
+```
+
+The gem depends on `layered-ui-rails` for its UI. If the host app hasn't installed it yet, run its install generator first:
+
+```bash
+bin/rails generate layered:ui:install
+```
+
+## Quick start
+
+The fastest path is the scaffold generator. It invokes Rails' built-in `model` generator, writes a resource class, and appends a route:
+
+```bash
+rails g layered:resource:scaffold post title:string body:text
+```
+
+This produces:
+
+- `db/migrate/<timestamp>_create_posts.rb` and `app/models/post.rb` (via `rails g model`)
+- `app/layered_resources/post_resource.rb` with `columns` and `fields` derived from the attributes
+- `layered_resources :posts` appended to `config/routes.rb`
+
+Useful flags:
+
+- `--skip-model` - the model already exists
+- `--actions index show` - emits `only: [:index, :show]`
+- `--except destroy` - emits `except: [:destroy]`
+- `--controller` - also eject a controller and wire it into the route
+- `--views` - also eject the templates upfront
+
+Views are intentionally not generated by default - the gem's defaults render until ejected.
+
+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`. It writes `app/layered_resources/post_resource.rb` and appends `layered_resources :posts` to `config/routes.rb`. Pass `--skip-route` to skip the route line.
+
+## What you get
+
+For `layered_resources :posts` with all actions enabled:
+
+| Route                   | Action  |
+|-------------------------|---------|
+| `GET /posts`            | index   |
+| `GET /posts/:id`        | show    |
+| `GET /posts/new`        | new     |
+| `POST /posts`           | create  |
+| `GET /posts/:id/edit`   | edit    |
+| `PATCH /posts/:id`      | update  |
+| `DELETE /posts/:id`     | destroy |
+
+The index table's primary column links to each record's **edit** page automatically (or its show page for read-only resources that have `:show` but not `:edit`).
+
+The default `show` view is intentionally a blank canvas - the gem does not auto-render an attribute list (generated detail pages are low-value and always need customizing). Since the index links titles to edit, `:show` is only worth keeping if you'll build a real detail view (eject it with `rails g layered:resource:views` and fill in the template). Otherwise advise `except: [:show]` to drop the route.
+
+`@page_title` is set automatically per action: pluralized model name on index, `"New <Model>"` on new, the record's primary column value on show, and `"Edit <record label>"` on edit. The layered-ui-rails layout reads it for `<title>`.
+
+## Resource DSL
+
+Resource classes live in `app/layered_resources/` and inherit from `Layered::Resource::Base`:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  columns [
+    { attribute: :title, primary: true },
+    { attribute: :status },
+    { attribute: :created_at, label: "Published" }
+  ]
+
+  fields [
+    { attribute: :title },
+    { attribute: :body, as: :text },
+    { attribute: :status }
+  ]
+
+  search_fields [:title, :body]
+  default_sort attribute: :created_at, direction: :desc
+  per_page 25
+end
+```
+
+| Method | Purpose |
+|---|---|
+| `model Post` | The ActiveRecord class this resource manages |
+| `columns [...]` | Index table columns. Each entry is `{ attribute:, label:, primary:, link:, render: }` |
+| `fields [...]` | Form fields for new/edit. Omit to disable CRUD forms |
+| `search_fields [...]` | Ransack attributes the index search box matches against. Association-walking entries like `:user_name` (for `belongs_to :user` + `users.name`) join into the association |
+| `search_placeholder "..."` | Replaces the search box placeholder. Default derives from `search_fields` via `human_attribute_name`, so `activerecord.attributes.<model>.<attr>` i18n renames flow through (association walks resolve each half against its own model) |
+| `filters :a, :b, c: {...}` | Structured filter controls on the index — an "Add filter" popover plus removable tags. Control + Ransack predicate inferred per column; trailing hash overrides per attribute. See [Filters](#filters) |
+| `label_attribute :title` | Attribute a record is labelled by (page titles, row action menus, another resource's picker). Defaults to the `primary:` column, else the first. Falls back through `name`/`title`/`label`/`email`, then the model's own `to_s`, then `"Post #12"` |
+| `default_sort attribute:, direction:` | Default sort order for the index |
+| `per_page n` | Pagination size (default 15) |
+| `root_breadcrumb "Home", "/"` | Static first crumb in the breadcrumb trail (e.g. back to the host app's dashboard). Without it, top-level resources render no trail; nested routes prepend it to the derived parent trail |
+
+### Column options
+
+- `as: :type` - pins the cell to a column partial instead of the type-inferred default. Built in: `:text`, `:datetime`, `:badge`, `:boolean`; an unrecognised type raises `ArgumentError` at render time rather than rendering an empty cell. See [Column rendering](#column-rendering)
+- `primary: true` - marks the cell that links to the record's edit (or show) page (defaults to first column)
+- `label: "Custom"` - overrides the humanised attribute name
+- `sortable:` - whether the header renders a sort link. **Defaults to `false` for any attribute that isn't a real DB column** (virtual attributes, delegated association values), because a Ransack sort link on one 500s when clicked. Pass `sortable: true` to opt back in - you then own the associated model's `ransackable_attributes` (see [Associations](#associations))
+- `link: :route_key` - wraps the column's rendered value in a link to a nested route (e.g. `:users_posts`); composes with `as:` (pair with `as: :badge` for a badge link)
+- `render: ->(record) { ... }` - custom cell renderer. The proc is a plain Ruby closure invoked with `.call` (not `instance_exec`), so `self` inside it is the lexical scope where you wrote it - the resource class body, which has no view helpers. **To use a view helper (`l_ui_format_datetime`, `link_to`, `tag.*`, etc.), take the view context as a second arg:** `render: ->(record, view) { view.l_ui_format_datetime(record.created_at) }`. Arity `>= 2` (or variadic/optional, e.g. `->(record, view = nil)`) trips the view-injection branch; an arity-1 proc that calls a view helper raises `NoMethodError ... for class YourResource`. Before reaching for a proc at all: the **default renderer already strftime-formats datetime columns** (and dispatches `as:` partials), so a plain `{ attribute: :created_at, label: "Created" }` renders the timestamp readably with no proc needed.
+
+### Column rendering
+
+Cells render through a partial picked by `as:`, or inferred from the model's column type (`boolean` → `:boolean`, `date`/`datetime`/`time`/`timestamp` → `:datetime`, everything else including virtual attributes → `:text`). A `render:` proc bypasses partials entirely. Lookup order is per-resource (`app/views/layered/<resource>/columns/_<type>.html.erb`) → host-wide (`app/views/layered/resource/columns/_<type>.html.erb`) → gem built-in, so an ejected partial overrides the default for one resource or the whole app.
+
+Partial locals are `record`, `value` (`record.public_send(attribute)`), and `options` — **`options` is the column hash itself**. That's the extension point: any extra key on a column is readable by its partial, which is how the per-type options work.
+
+| `as:` | Options it reads |
+|---|---|
+| `:text` | — (strftime-formats a value that responds to `strftime`) |
+| `:datetime` | `format:` (strftime string, default `"%-d %b %Y %H:%M"`); nil-safe |
+| `:boolean` | `true_label:` (default `"✓"`), `false_label:` (default `"✗"`) |
+| `:badge` | `variants:`, `rounded:` |
+
+Since `:datetime` and `:boolean` are already the defaults for their column types, `as:` mostly earns its place for `:badge`, or to pass `format:` / `true_label:`.
+
+`variants:` maps the cell's value to a layered-ui badge modifier, defaulting to `:default` (grey) for any value not listed — including `nil`:
+
+```ruby
+{ attribute: :lock_status, label: "Status", as: :badge,
+  variants: { Locked: :danger, Active: :success } }
+```
+
+Keys are matched as `value.to_s.to_sym`, so they must match the rendered string exactly: a `lock_status` returning `"Locked"` needs the key `Locked:`, and `:locked` silently falls through to grey. Variant names are layered-ui's badge modifiers — see that skill's `references/CSS.md`. Pair with `rounded: true` for a count pill (see [Counts of nested resources](#counts-of-nested-resources)). A badge column is usually backed by a **model method**, not a DB column, so it's non-sortable by default (see `sortable:` above).
+
+```bash
+rails g layered:resource:column badge            # eject the built-in host-wide
+rails g layered:resource:column badge users      # eject for one resource only
+rails g layered:resource:column priority_badge   # scaffold a new as: type
+```
+
+A scaffolded partial ships with the locals contract in a comment, ready to fill in.
+
+### Field types
+
+Field `as:` follows Rails' `form_with` field helpers - `:text`, `:checkbox`, `:date`, `:datetime`, `:select`, etc. A field is automatically marked required if its model has an unconditional presence validator on that attribute.
+
+**Record pickers.** A field naming a `belongs_to`'s foreign key (`user_id`) infers `as: :combobox, multiple: false` - a type-ahead token select over the associated records. Default options are `klass.all` labelled by the first present of `name`/`title`/`label`/`email` (else `"User #12"`), resolved per request via a callable. It posts the plain foreign key, so the write path is unchanged. Required comes from the association's `optional:` (via `belongs_to_required_by_default`), not from a presence validator on the column - `belongs_to` validates the *association*, and with an `if:` Rails attaches for its own reasons. Polymorphic associations are skipped (no single class to fill the picker). `as:` opts out; `collection:` keeps the control and replaces the options - use it to scope, order, or label by a specific resource (`-> { User.editors.map { |u| [UserResource.record_label(u), u.id] } }`), since the default does *not* consult the associated model's own resource (a model can have several). Other combobox options (`multiple:`, `url:`, `min_chars:`, `create:`/`create_name:`, `reorder:`, `text:`) pass through to `l_ui_combobox`. Requires layered-ui-rails ~> 0.25, which is where the `:combobox` field type landed.
+
+### Filters
+
+`filters` declares structured index controls complementing the single free-text `search_fields` box. The UI: an **Add filter** button opens a popover listing the declared filters; picking one adds it as an unset **tag** at the end of the row (the `f[]` param tracks added tags and their order for as long as they're shown) with its controls popover already open, ready to take a value; pressing the tag's label reopens the popover, and its ✕ removes it. Short single-choice filters apply instantly via links; ranges/text/multi-selects/comboboxes apply via a small GET form. Every filter is a Ransack predicate in the URL, so filters compose with search, sort, and pagination — the search form and each filter form round-trip the other `q` params (and `f[]` entries) as hidden fields (no JavaScript; the one-shot `fo` param marks which tag's popover renders open).
+
+```ruby
+filters :status,          # enum     -> multi-select of its values  (status_in)
+        :featured,        # boolean  -> Yes / No                     (featured_eq)
+        :created_at,      # date     -> from / to range              (created_at_gteq / _lteq)
+        :comments_count,  # integer  -> number range                 (comments_count_gteq / _lteq)
+        :user             # belongs_to -> multi-select               (user_id_in)
+```
+
+Inference by column type: `enum`/`belongs_to` -> multi-select (`_in`; `multiple: false` gives a single-choice `_eq`); `boolean` -> Yes/No (`_eq`); `date`/`datetime` -> date range (`_gteq`+`_lteq`); numeric -> number range; `string`/`text` -> "contains" (`_cont`), or a multi-select when a `collection:` or `url:` is given. A `belongs_to` filter keys on the **foreign key** (`user_id`) so it never joins — no association-walk setup needed; its default options are `klass.all` labelled by the first present of `name`/`title`/`label`/`email`.
+
+**Long option lists switch control.** A select-type filter renders as the plain list (multi-select: checkboxes + Apply; single-choice: instant-apply links) up to `Layered::Resource.filter_combobox_threshold` options (10), and as a type-ahead **combobox** past it — a checkbox list of every user is no way to pick one. A single-choice combobox posts a scalar (no `[]`), so `_eq` gets the value rather than an array. The count is taken per request, after a `collection:` callable resolves, so the control follows the data; the decision lives in `layered_filter_control` (the view helper), not in `resolved_filters`, for exactly that reason. Declaring `as:` pins the control and opts out: `as: :select` keeps the list however long, `as: :combobox` uses the combobox however short.
+
+**Remote options.** `url:` fetches the options from an endpoint as the user types instead of rendering a collection — such a filter is always a combobox (nothing to render or count). Give it as a callable (`-> { user_options_path }`) so it resolves per request in the view, where route helpers exist. The endpoint is an ordinary host-app action including `Layered::Ui::ComboboxOptions` and returning `l_ui_combobox_options(scope, label:, search:)` — the gem never routes it, so it's authorised however any index is. Since the browser has no collection to look a label up in, an active remote filter's values are labelled server-side from the records (same `name`/`title`/`label`/`email` fallbacks), so the tag reads "User: Alice" not "User: 12"; a `url:` over a plain column has no records and its values label themselves. `min_chars:` and `text:` pass through too; the write-side options (`create:`, `create_name:`, `reorder:`) deliberately don't — a filter picks among values that already exist.
+
+**The blank a combobox posts.** `l_ui_combobox` emits a leading blank hidden input so clearing every token submits an empty collection rather than omitting the key. Ransack prunes blanks from an `_in` array itself, and `layered_filter_query_params` prunes them too — an array left with nothing becomes an explicit `""`, the same shape the Clear link writes, so the tag reads as inactive *and* a `default:` doesn't immediately re-apply.
+
+Override per attribute with a trailing hash: `as:` (force control type: `:select`, `:combobox`, `:boolean`, `:string`, `:range`, `:date_range`), `collection:` (select options — array, `[label, value]` pairs, or a callable resolved per request, returning either form or records), `multiple:` (defaults to true for select-types; false gives single-choice `_eq`), `url:`/`min_chars:`/`text:` (remote options; `Layered::Resource::Base::COMBOBOX_FILTER_OPTIONS`), `label:`, `pinned:` (tag always shown — never in the add menu, no remove ✕; Clear resets the value but the tag stays), `default:` (value applied when the request has no state for the filter — scalar, `{ from:, to: }` for ranges, array for `multiple:`, or a callable). The add-filter button only renders while unpinned filters remain. Clearing a defaulted filter writes an explicit blank (`q[status_eq]=`) so the default doesn't re-apply. Filtered attributes are added to the resource's Ransack allowlist; un-shown/un-searched/un-filtered attributes stay un-queryable and stray `q[...]` params are ignored, not raised.
+
+**The predicate set is closed.** Each control type maps to a fixed predicate (`:select`/`:combobox` → `_in`/`_eq`, `:boolean` → `_eq`, `:string` → `_cont`, ranges → `_gteq`+`_lteq`) and there is no `predicate:` option, so predicates Ransack can otherwise express (`_not_null`, `_matches`) aren't reachable through the DSL. In particular a **"is this set / unset" filter on a nullable timestamp** (a `locked_at`-style column) has no inferred control: `as: :boolean` emits `locked_at_eq=true`, which casts against a datetime column and matches nothing. Back the flag with a real boolean column the write path maintains, or eject the filter partials and emit the predicate yourself. Filtered attributes *are* allowlisted, so `q[locked_at_not_null]=1` works hand-typed in the URL — it just has no UI control.
+
+The bar renders inside the index Turbo frame between search box and table, built from `l_ui_popover` and the `_filters`/`_filter_control` partials — eject with `rails g layered:resource:views` to customise.
+
+## Route DSL
+
+Mount in `config/routes.rb`:
+
+```ruby
+layered_resources :posts                                       # all CRUD actions
+layered_resources :posts, only: [:index]                       # read-only
+layered_resources :posts, except: [:destroy]                   # everything but delete
+layered_resources :posts, controller: "posts"                  # use a custom controller
+layered_resources :posts, resource: "Admin::PostResource"      # explicit resource class
+layered_resources :posts, namespace: "Admin"                   # derives Admin::PostResource and Admin::ResourcesController
+```
+
+Incoherent `only:` combos raise at boot time - e.g. `:new` without `:create`, or `:edit` without `:update`.
+
+### Nested routes
+
+```ruby
+layered_resources :users
+
+# Either form produces /users/:user_id/posts with Rails-standard helper
+# names (user_posts_path, new_user_post_path, edit_user_post_path, …):
+resources :users, only: [] do
+  layered_resources :posts
+end
+# …or, equivalently…
+scope "users/:user_id" do
+  layered_resources :posts
+end
+```
+
+Helper names follow the standard Rails nested-resources convention, so `polymorphic_path([@user, :posts])`, `link_to "Edit", [@user, @post]`, `url_for([@user, @post, :comments])` etc. all resolve. The `link:` column option uses the same name (`link: :user_posts`, `link: :user_post_comments`).
+
+**Never add `as:` to a surrounding `scope`.** `layered_resources` composes its own helper names from the path segments (`scope path: "manage"` → `manage_posts_path`, `new_manage_post_path`, …), so `as:` is unnecessary. A value matching the path is absorbed silently; a disagreeing one (`as: "admin"`) is ignored with a boot-time warning.
+
+Resolve the parent in `scope`:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  def self.scope(controller)
+    if controller.params[:user_id].present?
+      User.find(controller.params[:user_id]).posts
+    else
+      Post.all
+    end
+  end
+end
+```
+
+## Override points
+
+Override these class methods on the resource (not the controller) to change behaviour:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  # Restrict the base scope (e.g. tenant isolation)
+  def self.scope(controller)
+    controller.current_team.posts
+  end
+
+  # Customise how new records are instantiated
+  def self.build_record(controller)
+    scope(controller).build(author: controller.current_user)
+  end
+
+  # Customise the redirect target after create/update/destroy
+  def self.after_save_path(controller, record)
+    controller.main_app.post_path(record)
+  end
+end
+```
+
+Note: when `current_user` (or whichever accessor a hand-rolled `scope` reads) is `nil`, return `model.none` rather than `model.all` - otherwise unauthenticated requests see the full table. The `owned_by` shorthand below raises loudly instead, surfacing missing auth wiring.
+
+## Ownership shorthand
+
+`owned_by` collapses the two most common scope/build_record overrides into one declaration:
+
+```ruby
+class QuoteResource < Layered::Resource::Base
+  model Quote
+
+  owned_by :user                            # default via :current_user
+  # owned_by :account, via: :current_account
+end
+```
+
+It rewires `scope(controller) = model.where(association => controller.public_send(via))` and assigns the owner in `build_record`. Pure data filter - it does not enforce per-action authorisation.
+
+When `via` returns nil, `owned_by` raises `Layered::Resource::MissingOwnerError` so a missing `before_action :authenticate_user!` surfaces immediately instead of every page silently 404ing. Pass `allow_nil: true` to opt into public-with-scope behaviour (returns `model.none` and assigns nil on create):
+
+```ruby
+owned_by :user, allow_nil: true
+```
+
+When combined with `use_pundit`, the nil-owner check is skipped — Pundit's policy gate (`policy.create?`) is the authoritative auth check.
+
+## Authorisation (Pundit)
+
+The gem ships first-class Pundit support as opt-in. Add `use_pundit` to a resource:
+
+```ruby
+class PostResource < Layered::Resource::Base
+  model Post
+
+  use_pundit
+end
+```
+
+When enabled:
+
+- `scope(controller)` defaults to the controller's `policy_scope(model)` helper, so apps that override `pundit_user` (e.g. `current_account`) get the same identity used by `authorize`.
+- The controller calls `authorize(@record)` after loading a member record (show/edit/update/destroy and any custom member action).
+- The `New`/`Edit`/`Delete` actions in the default views (inline buttons on show, a per-row actions popover menu on index, in a column pinned to the right edge via `l_ui_table`'s `floating_actions:`) hide for users whose policy denies the action - the views call a `resource_can?(action, record = nil)` helper that ANDs the route-exposure flag with `policy(record).<action>?`.
+
+`owned_by` composes with `use_pundit`: Pundit's `Policy::Scope#resolve` wins for the read filter; `owned_by` still drives owner assignment on create. Stack both when needed.
+
+For CanCan, plain POROs, or bespoke policies, override `scope` directly (and add `before_action :authorize_*` callbacks in an ejected controller). `use_pundit` is just a convenience for the Pundit case.
+
+In ejected views, prefer `resource_can?(:update, @record)` over the raw `@resource_can_update` ivar when you want per-record policy gating; the ivar still works for route-exposure-only checks.
+
+## Inheritance / variants
+
+Subclasses inherit `model`, `columns`, `fields`, `search_fields`, `search_placeholder`, `label_attribute`, `default_sort`, `per_page`, and `root_breadcrumb`. Override only what differs:
+
+```ruby
+# app/layered_resources/admin/post_resource.rb
+class Admin::PostResource < PostResource
+  columns [
+    { attribute: :title, primary: true },
+    { attribute: :author_name, label: "Author" },
+    { attribute: :pinned }
+  ]
+end
+```
+
+```ruby
+# config/routes.rb
+layered_resources :posts
+namespace :admin do
+  layered_resources :posts, resource: "Admin::PostResource"
+end
+```
+
+## Index introduction
+
+Drop a partial at `app/views/layered/<resource>/_introduction.html.erb` to render content above the search area on that resource's index page. The partial is rendered when present and skipped otherwise — no DSL, no configuration. It uses the same per-resource view path as ejected templates and column overrides.
+
+## Ejection
+
+Take over presentation or controller logic without giving up the rest:
+
+```bash
+rails g layered:resource:views posts        # copies index/show/new/edit ERB into app/views/layered/posts/
+rails g layered:resource:controller posts   # generates a controller subclass for custom actions
+```
+
+The controller's `_prefixes` is overridden so `app/views/layered/<plural>/` overrides win automatically - no extra wiring. Delete any individual ejected template to fall back to the gem default.
+
+To outgrow the gem entirely: drop the inheritance, write a plain Rails controller, swap `layered_resources :posts` for `resources :posts` in routes.
+
+## Authentication
+
+`Layered::Resource::ResourcesController` inherits from the host app's `ApplicationController`, so any `before_action` declared there (e.g. Devise's `authenticate_user!`) already protects every layered resource request - no extra configuration needed.
+
+### 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
+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.
+
+## Flash messages (i18n)
+
+Flash strings live under `layered.resource.flash.*` in `config/locales/en.yml`:
+
+| Key | Trigger |
+|---|---|
+| `created` / `updated` / `deleted` | Successful create/update/destroy |
+| `not_deleted` | `record.destroy` returned false |
+| `dependent_records` | `destroy` rescued `ActiveRecord::InvalidForeignKey` or `ActiveRecord::DeleteRestrictionError` |
+
+Override per-locale in the host app's `config/locales/<lang>.yml`. The `%{model}` interpolation is the humanised model name.
+
+`destroy` rescues FK and restrict-dependent violations and redirects to the index with the `dependent_records` flash instead of returning a 500.
+
+## Show is intentionally minimal
+
+The default show view renders the primary column as a heading with `Edit` and `Delete` buttons - nothing else. It does not iterate over `columns` (those are designed for index table cells, with no per-user gating, and would leak everything declared for the index). For a real detail page, eject with `rails g layered:resource:views <name>` and edit the show template directly against `@record`.
+
+## Associations
+
+Resources are independent - each model gets its own resource class. To surface association data on an index, expose a method on the model and reference it as a virtual column attribute:
+
+```ruby
+class Post < ApplicationRecord
+  belongs_to :user
+  delegate :name, to: :user, prefix: true, allow_nil: true # post.user_name
+end
+```
+
+```ruby
+columns [
+  { attribute: :title, primary: true },
+  { attribute: :user_name, label: "Author" }
+]
+```
+
+### Counts of nested resources
+
+To show how many children a record has, back the count with a **Rails counter cache**, not a virtual `record.children.size` column. A virtual size column issues a `COUNT` query per row (an N+1 on the index) and can't be sorted or searched; a counter-cache column reads off the parent row in the index's single query and sorts via `q[s]=<count> asc` like any other attribute.
+
+Add `counter_cache: true` to the child's `belongs_to` and a backing integer column on the parent, then point the column at that real attribute. **Render the count as a rounded badge** so it reads as a count rather than a value:
+
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :post, counter_cache: true    # maintains posts.comments_count
+end
+# add_column :posts, :comments_count, :integer, default: 0, null: false
+```
+
+```ruby
+columns [
+  { attribute: :title, primary: true },
+  { attribute: :comments_count, label: "Comments", as: :badge, rounded: true, link: :post_comments }
+]
+```
+
+`as: :badge, rounded: true` gives the rounded count pill; `link:` (optional) makes it link to the children's nested index. If the parent doesn't already carry a counter-cache column, add the migration and `counter_cache: true` rather than reaching for `.size`.
+
+To make an association searchable, add a Ransack-walk-shaped entry to `search_fields` - e.g. `search_fields [:title, :user_name]` resolves `:user_name` against `belongs_to :user` + `users.name` and joins into the association. The gem scopes the Ransack allowlists per resource: it only responds when the resource class is the auth object (on both the parent and the associated model), so host-app Ransack config is preserved. A walked search field is also *sortable* (`q[s]=user_name asc` orders by `users.name`) because Ransack derives its sort allowlist from the search allowlist. Cross-model sort/filter on associations *not* declared in `search_fields` remains off; to opt in, define `ransackable_associations` on the parent model yourself and allowlist the attributes on the child model - the gem detects the host-defined override and unions with it. The search box placeholder labels a walk as "<association> <attribute>" via each model's `human_attribute_name` - translate `activerecord.attributes.<model>.<attr>` to rename a half, or set `search_placeholder` on the resource to replace the whole string.
+
+## Common issues
+
+- **`NoMethodError: undefined method 'l_ui_table'`** - the host app hasn't installed `layered-ui-rails`. Run `bin/rails generate layered:ui:install`.
+- **Search/sort returns empty** - the attribute isn't in `search_fields`, or Ransack's `ransackable_attributes` on the model excludes it. The resource patches Ransack only when itself is the auth object; verify nothing in the host app removes the attribute unconditionally.
+- **`only:` validation error at boot** - `:new` requires `:create`, `:edit` requires `:update`. Adjust the action list.
+- **Ejected view not picked up** - the controller looks under `app/views/layered/<plural_name>/`, where `<plural_name>` is the symbol passed to `layered_resources` (ignoring Rails namespaces). The generator mirrors this; if you've moved files manually, match that path.
+
+## Further reference
+
+- README: https://github.com/layered-ai-public/layered-resource-rails
+- Live demo: https://layered-resource-rails.layered.ai
+- Underlying UI gem: https://github.com/layered-ai-public/layered-ui-rails

data/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+This file provides guidance to AI agents when working with code in this repository.
+
+A Rails 8+ engine providing CRUD scaffolding. Consumer apps declare a `Layered::Resource::Base` subclass in `app/layered_resources/` and a `layered_resources :name` route. README is the user-facing API reference.
+
+## Commands
+
+```bash
+bundle exec rake test                                              # full suite
+bundle exec rake test TEST=test/integration/layered_resource_crud_test.rb
+cd test/dummy && bin/dev                                           # manual exploration
+```
+
+## Architecture
+
+Three load-bearing pieces:
+
+- **`Layered::Resource::Base`** (`lib/layered/resource/base.rb`) - DSL (`model`, `columns`, `fields`, `search_fields`, `default_sort`, `per_page`) plus override points (`scope`, `build_record`, `after_save_path`). `inherited_attribute` walks the ancestor chain manually because class ivars aren't Ruby-inherited - this enables resource subclassing. `configure_ransack` patches `ransackable_attributes`/`ransackable_associations` on the model but **only responds when called with the resource class as `auth_object`**; other callers fall through to the original methods, preserving host-app config.
+
+- **`Layered::Resource::Routing`** (`lib/layered/resource/routing.rb`) - the `layered_resources` route DSL plus a process-wide `Concurrent::Map` registry. Each route bakes a `_layered_resource_route_key` default into `path_parameters` so the controller can look up the right resource. Parses surrounding `scope` paths at registration time for nested-route support. Raises early on incoherent `only:` combos (e.g. `:new` without `:create`) - keep those guards in sync if adding actions.
+
+- **`Layered::Resource::ResourcesController`** (`app/controllers/layered/resource/resources_controller.rb`) - inherits from the **host app's** `ApplicationController`, so its `before_action`s (e.g. Devise) apply automatically. `load_layered_resource` reads the route key, looks up the resource, and sets the `@can_*` action flags. `_prefixes` is overridden so `app/views/layered/<name>/` overrides win - this is what makes `rails g layered:resource:views` ejection work.
+
+Engine (`lib/layered/resource/engine.rb`) autoloads `app/layered_resources`, mixes `Routing` into `Mapper`, includes `Pagy::Method`, and prepends the engine view path.
+
+## Notes
+
+- Tests in `test/integration/` run against `test/dummy/` (a real Rails app with `Post` and `User` models, plus `PostResource` and `UserResource`). Integration tests are the contract for controller/routing/DSL changes.
+- `attribute_required?` treats a field as required only when the presence validator is unconditional - don't tighten without considering conditional-validation forms.
+- `concurrent-ruby` is depended on solely for the routing registry's `Concurrent::Map`.
+
+## Conventions
+
+- Titles: capitalise first word only (e.g. "This title")
+- Document new DSL surface in three places: the README (user-facing API reference), an integration test under `test/integration/` exercising it against the dummy app, and `.claude/skills/layered-resource-rails/SKILL.md`. When a new DSL option needs a runnable example, wire it into the dummy app to show it working.

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-08-30
+
+Initial release.
+
+### Resource DSL
+
+- `Layered::Resource::Base` DSL: `model`, `columns`, `fields`, `search_fields`, `default_sort`, `per_page`.
+- `label_attribute :title` — the attribute a record is labelled by wherever the gem names one (the `show`/`edit` page titles, a row's actions menu, and its options in another resource's picker). Defaults to the primary column. A record whose labelling attribute is blank falls back through `name`/`title`/`label`/`email`, then the model's own `to_s` when it defines one, then `"Post #12"`.
+- Resource inheritance for namespaced variants (e.g. `Admin::PostResource`), with `inherited_attribute` walking the ancestor chain so subclasses pick up their parent's declarations.
+- Escape hatches: `scope`, `build_record`, and `after_save_path`.
+
+### Routing and controllers
+
+- `layered_resources` route helper with full CRUD, plus `only:`/`except:` to restrict actions. Incoherent combinations (`:new` without `:create`) raise at route-definition time rather than 404ing later.
+- `layered_resources :foo, namespace: "Foo::Bar"` derives the resource class as `Foo::Bar::FooResource` and routes to `Foo::Bar::ResourcesController` when one is defined — the supported path for mounting resources inside an engine.
+- `Layered::Resource::Controller` concern. An engine can define its own `<Namespace>::ResourcesController` inheriting from its own `ApplicationController` and `include Layered::Resource::Controller`, keeping auth/authorize `before_action`s wired correctly.
+- Auth inherited from the host app's `ApplicationController`, so its `before_action`s (Devise and friends) apply with no extra configuration.
+- `owned_by` scopes a resource to its owner, and raises `Layered::Resource::MissingOwnerError` when `via` returns nil so auth misconfiguration surfaces loudly instead of silently 404ing every request. Pass `allow_nil: true` to opt into public-with-scope behaviour. (No-op under `use_pundit`, where Pundit handles the policy gate.)
+- `destroy` rescues `ActiveRecord::InvalidForeignKey` and `ActiveRecord::DeleteRestrictionError`, redirecting to the index with a flash rather than raising a 500.
+
+### Index: search, sort, filters, pagination
+
+- Index search, sort, and pagination via Ransack and Pagy.
+- `filters :status, :created_at, user: { multiple: true }` — structured index filters rendered as an "Add filter" popover plus removable chips. Picking a filter adds an unset chip to the end of the row; its popover holds the controls, its ✕ removes it. Control and Ransack predicate are inferred from the column type (enum/`belongs_to` → multi-select via `_in`, with `multiple: false` for single-choice `_eq`; boolean → Yes/No; date/datetime → date range; numeric → number range; string → contains), and are overridable per attribute with `as:`/`collection:`/`multiple:`/`label:`/`pinned:`/`default:`. Pinned filters render as always-shown chips (no ✕, never in the add menu — which disappears entirely once every filter is pinned); a default applies when the request carries no state for the filter, and clearing writes an explicit blank so it does not re-apply. Filters, search, and sort round-trip each other as hidden fields, so they compose in the URL with no JavaScript.
+- A select-type filter with more than `Layered::Resource.filter_combobox_threshold` (10) options renders as a type-ahead combobox rather than a checkbox list (or, single-choice, a menu of instant-apply links), so a `belongs_to` filter over a large table stays usable. The count is taken per request, after a `collection:` callable resolves, so the control follows the data; declaring `as: :select` or `as: :combobox` pins it either way.
+- Filters accept `url:` (plus `min_chars:` and `text:`), fetching their options from an endpoint as the user types rather than rendering a collection up front. Such a filter is always a combobox. Give `url:` as a callable so it resolves per request in the view (`-> { user_options_path }`); the endpoint is an ordinary host-app action including `Layered::Ui::ComboboxOptions`, so it is authorised however any index is. An active remote filter's values are labelled server-side from the records, so its tag reads "User: Alice" rather than "User: 12".
+
+### Forms
+
+- Record pickers: a field naming a `belongs_to`'s foreign key (`user_id`) renders as a single-select combobox over the associated records — a type-ahead input whose selection becomes a removable token — rather than as the raw number the column holds. Options default to `klass.all`, labelled the way a `belongs_to` filter's are and resolved per request; the picker posts the plain foreign key, so the write path is unchanged. `as:` opts out, `collection:` replaces the options, and every other combobox option passes through to `l_ui_combobox`. Polymorphic associations are skipped, having no single class to fill a picker.
+- A field on a `belongs_to`'s foreign key takes its required flag from the association's `optional:` rather than from a presence validator on the column, since `belongs_to` validates the presence of the *association* under an `if:` that ActiveRecord attaches for its own reasons.
+- A field's `permit:` is strong-parameters configuration read by `permitted_params`, and is dropped before the field reaches the form layer. The form helper passes any key it does not recognise through to the field's input, where a stray `permit` would render as an HTML attribute on a `select` or text input — and raise outright on a `combobox`, whose helper takes named options only.
+
+### Generators and i18n
+
+- `layered:resource:scaffold`, `layered:resource`, `layered:resource:views`, `layered:resource:controller`, and `layered:resource:column` generators, plus `layered:resource:install_agent_skill` for the bundled agent skill.
+- Flash messages are i18n-backed (`config/locales/en.yml`, key `layered.resource.flash.*`), overridable per-locale in the host app.
+
+### Requirements
+
+- Rails ~> 8.0, Ruby >= 3.3, and layered-ui-rails ~> 0.25 (>= 0.25.1, which is where the popover overflow fix the filter comboboxes depend on landed).

data/CLA.md

@@ -0,0 +1,10 @@
+# Contributor License Agreement
+
+This agreement allows LAYERED AI LIMITED (UK company number: 17056830) to
+use your contributions in both open source and commercial offerings.
+
+- You retain copyright
+- You grant LAYERED AI LIMITED a perpetual, worldwide license to use,
+  modify, sublicense, and distribute your contribution
+
+This agreement does not restrict your own use of the contribution.