cafe_car 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f2ee78455723f808d6f02bbcad83ac86cd5f4fcf8c05203bd3afc602afe1d4f
-  data.tar.gz: '09447696c9bd504e776cc1cc493025ff99ceb467276ca916eb660165bfdf42cc'
+  metadata.gz: 8782de0874fe886849232cebef1d036e0cc43680e758a5bfdc2a0b027e26b06c
+  data.tar.gz: 346735b4f4568e3c28a751e8dde44d5e85fa0b5d907c2ce95e0e004ff4277e1e
 SHA512:
-  metadata.gz: b39a51b42de3e8ffa3440e3d714eab15415592e30077187ddabf970826f64ef210d7f4f3e6a61ef28de43e0c8715dbaba35367700d1f2537fad3817c16b347ee
-  data.tar.gz: 30792c4c93baf653babd0f2bb64dc0790875faa41db6ef7d5dcf93e69238c146752930794a2672f68eee83c15facfb537b200825750b370d2199e79dc627cc2e
+  metadata.gz: 84003696580e71078eced5706bf2a4d33858de2aee2a2b8ac3c2764838f53226d6fa5c1b6015a9bec4ec5f8049ef7cbd3188db462ad6500f29e79c6ff5b9778a
+  data.tar.gz: 4ec99470b492701f531e2977d0fd88cc2f33fa3b4b35327b25a3b5b11f233b75fb91a5b2fdad3ff72a5398975c130cc8b6ffca4db5e159ebc6cfdbcd8c8c036b

data/.claude-plugin/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://www.schemastore.org/claude-code-marketplace.json",
+  "name": "cafe-car",
+  "description": "CafeCar — a composable view extension for Rails",
+  "owner": {
+    "name": "Jeff Peterson",
+    "email": "jeff@yak.sh"
+  },
+  "plugins": [
+    {
+      "name": "cafe-car",
+      "source": "./",
+      "strict": false,
+      "description": "The CafeCar Agent Skill: point a controller at a model and the Pundit policy drives the whole UI — index, show, new, edit, filtering, sorting, CSV export, and Turbo-morph live updates. Teaches agents to extend CafeCar's defaults instead of hand-rolling admin views.",
+      "author": {
+        "name": "Jeff Peterson"
+      },
+      "license": "MIT",
+      "homepage": "https://github.com/craft-concept/cafe_car",
+      "skills": ["./skills/cafe_car"]
+    }
+  ]
+}

data/README.md

@@ -4,38 +4,76 @@
   CafeCar
 </h1>
 
+<p><em>🚋 Recline in the cafe car while Rails renders your views for you.</em></p>
+
 [![CI](https://img.shields.io/github/actions/workflow/status/craft-concept/cafe_car/ci.yml?branch=main&label=CI)](https://github.com/craft-concept/cafe_car/actions/workflows/ci.yml)
 [![Gem Version](https://img.shields.io/gem/v/cafe_car)](https://rubygems.org/gems/cafe_car)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/licenses/MIT)
 
-> 🚀 **[Live demo →](https://cafe-car-demo-production.up.railway.app)** — click straight
-> into a real auto-generated admin (clients, invoices, articles, users, notes). No signup;
-> the data resets periodically.
+> 🚀 **[Live demo →](https://cafe-car-demo.up.railway.app)** — click straight
+> into a real admin, rendered from plain models (clients, invoices, articles, users, notes).
+> No signup; the data resets periodically.
 
 <p align="center">
-  <a href="https://cafe-car-demo-production.up.railway.app/admin/invoices">
+  <a href="https://cafe-car-demo.up.railway.app/admin/invoices">
     <img src="https://raw.githubusercontent.com/craft-concept/cafe_car/main/docs/images/admin-invoices-index.png"
-         alt="CafeCar's auto-generated admin: an invoices index with sortable columns, currency formatting, association links, sender avatars, and pagination — all rendered straight from the model with no view code."
+         alt="A CafeCar admin rendered straight from the model: an invoices index with sortable columns, currency formatting, association links, sender avatars, and pagination — no view code."
          width="900">
   </a>
 </p>
 <p align="center">
   <em>A complete admin index — sortable columns, formatted values, association links, and
-  pagination — auto-generated from a model with one line of controller code.
-  <a href="https://cafe-car-demo-production.up.railway.app">Try the live demo →</a></em>
+  pagination — rendered from a model with one line of controller code.
+  <a href="https://cafe-car-demo.up.railway.app">Try the live demo →</a></em>
 </p>
 
-CafeCar is a Rails engine that extends the MVC "view" layer to provide automatic
-CRUD UI generation with sensible defaults. Its philosophy is rooted in the idea
-that Rails should render _something_ that represents the CRUD operations of your
-models by default. These defaults can then be expanded or overridden on either
-an application-wide or model-specific basis.
+Your model already knows its columns, types, and associations — a full
+description of a resource. Rails still makes you hand-write a controller, seven
+actions, and a folder of view templates before any of it renders in a browser.
+CafeCar closes that gap. It's a composable view extension for Rails — an
+extension of the view and controller layer that renders index, show, new, and
+edit straight from the model, with Pundit authorization, filtering, and Hotwire,
+from one line of controller code. It's how Rails ought to work out of the box:
+render something for your models by default, then get out of the way. Every
+default is a starting point — override any view, presenter, or policy with
+ordinary Rails when the default is wrong.
+
+**Perfect for**: Rails developers who need a working admin this week — not a
+second framework to learn and configure.
+
+## Try it in 60 seconds
+
+```bash
+# 1. Install the gem and run the installer
+bundle add cafe_car
+bin/rails generate cafe_car:install
+```
+
+```ruby
+# 2. Point a controller at a model (add `resources :products` to your routes)
+class ProductsController < ApplicationController
+  cafe_car
+end
+```
+
+```ruby
+# 3. Say who can do what — and which fields are editable
+class ProductPolicy < ApplicationPolicy
+  def index?  = user.present?
+  def update? = user.admin?
+
+  def permitted_attributes = %i[name price description]
+end
+```
 
-**Perfect for**: Admin panels, internal tools, and rapid prototyping.
+Visit `/products`: index, show, new, and edit, all generated from the model.
+When a default is wrong, override that one piece — see
+[Getting Started](#getting-started).
 
 ## Table of Contents
 
 - [How CafeCar compares](#how-cafecar-compares)
+- [How CafeCar relates to ViewComponent & Phlex](#how-cafecar-relates-to-viewcomponent--phlex)
 - [Features](#features)
 - [Prerequisites](#prerequisites)
 - [Installation](#installation)
@@ -55,6 +93,7 @@ an application-wide or model-specific basis.
   - [Policy Generator](#policy-generator)
   - [Notes Generator](#notes-generator)
   - [Sessions Generator](#sessions-generator)
+- [Using CafeCar with AI coding agents](#using-cafecar-with-ai-coding-agents)
 - [Configuration](#configuration)
 - [Testing](#testing)
 - [Contributing](#contributing)
@@ -82,10 +121,27 @@ Reach for one of them when its model matches how you want to work:
 Reach for CafeCar when you want a Rails-native, convention-over-configuration
 admin that you extend with ordinary Rails code.
 
+## How CafeCar relates to ViewComponent & Phlex
+
+ViewComponent and Phlex answer "what's the unit of reuse for the UI I write?"
+CafeCar answers a different question: "why hand-write the CRUD index, show, and
+form views at all?" They sit at different layers, so they compose rather than
+compete.
+
+CafeCar renders index, show, new, and edit straight from the model — the
+boilerplate you'd otherwise write once per resource and maintain forever. Keep
+your ViewComponent or Phlex components for the screens you customize, and drop
+them into a CafeCar view or presenter like any other partial. CafeCar covers the
+boilerplate screens; your component library covers the parts worth building by hand.
+
+Plain partials work the same way. Pick whichever view primitive you like —
+CafeCar is the convention layer above it, deleting the boilerplate views so you
+write only the ones that earn their keep.
+
 ## Features
 
-- 🚀 **Auto-generated CRUD interfaces** - One line of code generates complete
-  index, show, new, edit views
+- 🚀 **Index, show, new, edit from the model** - One line of controller code
+  renders all four, straight from your model
 - 🎨 **Component-based UI system** - Flexible, composable components for
   building interfaces
 - 🔐 **Built-in authorization** - Pundit integration for attribute-level
@@ -95,11 +151,19 @@ admin that you extend with ordinary Rails code.
   association filters
 - 🔎 **Keyword search** - Turnkey search box on every index, matching across a
   model's text columns with zero per-model setup
+- 📈 **Chart view** - A third index view (beside grid/table) that buckets records
+  over any date column and plots the count, or a sum/average of a numeric column,
+  as dependency-free inline SVG
+- 📊 **Dashboard** - An opt-in overview page composing metric tiles and charts;
+  you write one view to turn it on, off by default
 - ⬇️ **CSV export** - One-click "Download CSV" of the current filtered, sorted
   view on any index
+- ☑️ **Bulk actions** - Select rows and act on many at once (delete ships built
+  in); every selected record is authorized against your policy on its own
 - 📄 **Pagination & sorting** - Kaminari integration with sortable columns
 - ⚡ **Hotwire ready** - Turbo Streams support out of the box
-- 📝 **Intelligent forms** - Auto-generated forms with smart field detection
+- 📝 **Intelligent forms** - Forms rendered from your schema, with smart field
+  detection
 
 ## Prerequisites
 
@@ -223,6 +287,8 @@ end
 - **Callbacks**: Lifecycle hooks for `render`, `update`, `create`, `destroy`
 - **Responders**: JSON, HTML, and Turbo Stream responses
 
+[See it live →](https://cafe-car-demo.up.railway.app/admin/clients) — the clients index from that one line.
+
 **Limiting actions:**
 
 ```ruby
@@ -280,7 +346,7 @@ end
 **Key methods:**
 
 - `permitted_attributes` - Attributes that can be edited via forms
-- `displayable_attributes` - Attributes shown in views (auto-detected from
+- `attributes.displayable` - Attributes shown in views (auto-detected from
   columns + associations)
 - `displayable_associations` - Associations that can be displayed
 - `filtered_attribute?(attr)` - Check if attribute should be hidden (uses Rails
@@ -419,15 +485,15 @@ end
 CafeCar provides an enhanced form builder with smart field detection.
 
 <p align="center">
-  <a href="https://cafe-car-demo-production.up.railway.app/admin/invoices/new">
+  <a href="https://cafe-car-demo.up.railway.app/admin/invoices/new">
     <img src="https://raw.githubusercontent.com/craft-concept/cafe_car/main/docs/images/admin-invoice-form.png"
-         alt="CafeCar's auto-generated new-invoice form with a client association select, typed inputs, and nested has_many line items (add/remove rows)."
+         alt="A CafeCar new-invoice form rendered from the model, with a client association select, typed inputs, and nested has_many line items (add/remove rows)."
          width="760">
   </a>
 </p>
 <p align="center">
-  <em>An auto-generated form with a typed date field, an association select, and nested
-  <code>has_many</code> line items — add and remove rows inline.</em>
+  <em>A form rendered from the model, with a typed date field, an association select, and
+  nested <code>has_many</code> line items — add and remove rows inline.</em>
 </p>
 
 **Basic forms:**
@@ -470,7 +536,17 @@ The form builder automatically detects field types:
 <%= f.association :category %>
 ```
 
-Automatically creates a select dropdown with all categories.
+[See it live →](https://cafe-car-demo.up.railway.app/admin/invoices/new) — add and remove nested line items on a new invoice.
+
+Creates a select dropdown for the association. The select is **searchable**: it's
+enhanced with [Tom Select](https://tom-select.js.org) (vendored — no CDN, no
+bundler) for keystroke typeahead. To keep large associations from rendering
+thousands of `<option>`s, the initial list is capped at
+`CafeCar.max_collection_options` (default 100); the typeahead then queries a JSON
+`options` endpoint (`GET /categories/options?q=…`) so records **past the cap stay
+reachable**. That endpoint is authorized through the model's policy scope, so the
+search never returns rows the user can't see. Enhancement is progressive — if
+JavaScript is disabled or fails, the field stays a working plain select.
 
 ### Filtering & Sorting
 
@@ -482,14 +558,78 @@ CafeCar provides advanced filtering with minimal configuration.
 /products?name=Widget&price.min=10&price.max=50&created_at=2024-01-01..2024-12-31
 ```
 
-**Filter operators:**
+**Filter operators** — a bare column key filters that column; a `.operator`
+suffix compares it:
+
+- **Equals**: `status=active` (or `status.eq=active`)
+- **Greater / less than**: `price.gt=10`, `price.lt=50`
+- **At least / at most**: `price.min=10`, `price.max=50` (aliases: `price.gte`, `price.lte`)
+- **Range**: `created_at=2024-01-01..2024-12-31` (`...` for an exclusive end)
+- **Arrays (IN)**: `tags=red,blue,green`
+
+Combine them freely — `?price.min=10&price.max=50` reads as `price BETWEEN 10 AND 50`.
+
+[See it live →](https://cafe-car-demo.up.railway.app/admin/users) — sort, filter, and search a real index.
+
+**The filter panel:**
+
+Every index also renders those filters as a form — a sticky card of controls
+beside the table, with no configuration. CafeCar reads the model policy's
+`permitted_filters` (which defaults to the displayable columns and associations)
+and renders one **typed control per attribute**, matched to the column type:
+
+- **string / text** — a "contains" box (substring match, the `~` operator)
+- **integer / decimal / float / date / datetime** — a min/max pair (the range)
+- **enum** — a select of the enum's own values (blank = Any)
+- **boolean** — a tri-state select (Any / true / false)
+- **belongs_to / has_many** — a searchable **multi-select** of the associated
+  records (the same Tom Select typeahead as the edit form), matching any of the
+  records you pick
+
+The keyword-search box shares the card, and the whole panel submits as one GET
+form — a submission just rewrites the query string above, with the active sort
+and view riding along as hidden fields. Attachments, rich text, polymorphic
+targets, and password columns render no control (there's nothing to filter on).
+
+Named model scopes opt in separately through `permitted_scopes` and render as
+checkbox toggles:
+
+```ruby
+class ArticlePolicy < ApplicationPolicy
+  def permitted_filters = %i[title author published_at]  # narrow the panel
+  def permitted_scopes  = %i[published draft]            # ?published=true
+end
+```
+
+The policy is the source of truth: change `permitted_filters` to change which
+controls appear, and a URL filter for an attribute that isn't on the list is
+dropped before it reaches the query. Control labels read from your locale
+(`helpers.filter`, plus each model's attribute names), and you replace any
+control by dropping a `_<type>_filter.html.haml` partial in the view directory.
+
+**Filter through an association:**
+
+Add a dot-path to `permitted_filters` and the panel filters by the far model's
+attribute:
+
+```ruby
+class InvoicePolicy < ApplicationPolicy
+  # own columns, plus a client's status and its owner
+  def permitted_filters = %i[status client.status client.owner_id]
+end
+```
+
+Each hop is the association name; the terminal is the far column, its enum, or a
+belongs_to — `client.owner_id` and `client.owner` mean the same thing. The
+control is typed by that terminal, so a nested belongs_to renders the same
+searchable multi-select and a nested enum the same enum select as a top-level
+one, and it composes with the other filters, search, and sort, round-tripping
+into the URL like any other.
 
-- **Range queries**: `created_at=2024..2025-01-01`
-- **Comparisons**: `price.min=10`, `price.max=50`
-- **Greater than**: `price.gt=10` or `price=>10`
-- **Less than**: `price.lt=50` or `price=<50`
-- **Equals**: `status=active` or `status.eq=active`
-- **Arrays**: `tags=red,blue,green`
+That one list is both the panel's source and the query whitelist: an undeclared
+path is dropped before any join, even when it names a real column further out.
+`?client.owner.email=` filters nothing unless `client.owner.email` is on
+`permitted_filters` — the same gate as an unpermitted top-level column.
 
 **Sorting:**
 
@@ -544,6 +684,41 @@ and logs a warning. Raise the limit in an initializer if your tables are larger:
 CafeCar.csv_export_row_limit = 50_000
 ```
 
+**Chart view:**
+
+Every index offers a third view beside grid and table. The **Chart** toggle
+buckets records over a date column and plots them as a bar chart:
+
+```
+/articles?view=chart&chart_x=published_at&chart_by=month
+/invoices?view=chart&chart_x=issued_on&chart_y=sum:total
+```
+
+Pick the x-axis from any of the model's displayable date/datetime columns
+(`chart_x`) and the bucket size from `day`, `week`, or `month` (`chart_by`,
+default `month`) using the form above the chart — it defaults to `created_at`
+and month, so the chart renders with zero configuration. Only date columns the
+policy exposes are offered, and the selected column is validated against that
+allowlist, so the parameter is never used as a raw column name.
+
+By default the bars measure the record count per bucket. `chart_y` switches that
+to an aggregate of a numeric column: `count` (the default), `sum:<column>`, or
+`avg:<column>` — for example `chart_y=sum:total`. The chartable columns are the
+model's policy-permitted numeric attributes (integer, decimal, or float), the
+same policy-is-source-of-truth pattern as the x-axis dates. A `chart_y` selector
+renders above the chart only when the model has at least one such column;
+otherwise you get the count chart with no selector. An unknown or non-permitted
+`chart_y` is validated against the allowlist and falls back to `count`, so the
+value never reaches SQL raw. Sum and average aggregate through a portable
+ActiveRecord calculation that runs on both SQLite and Postgres.
+
+The chart aggregates the **same** collection the table shows: the active filters
+narrow it and `policy_scope` still applies, so it never plots rows the current
+user can't see. Aggregation is a single database `GROUP BY` (a portable Arel date
+truncation — `date_trunc` on Postgres, `strftime` on SQLite), and the result is
+dependency-free inline SVG — no JavaScript, CSP-safe. A model with no date column
+shows a short "no date columns to chart" message instead.
+
 **In models:**
 
 ```ruby
@@ -625,6 +800,159 @@ In views:
 <% end %>
 ```
 
+### Bulk Actions
+
+Every index table carries a checkbox per row and a "select all" checkbox in the
+header. Pick some rows, choose an action from the bar, and CafeCar applies it to
+the selection. **Delete** ships built in.
+
+Each selected record is authorized on its own: the candidate set is first
+narrowed to the policy scope, then every row is checked against the action's
+policy predicate (`destroy?` for delete). Rows the current user isn't allowed to
+touch are skipped — a batch never bulk-bypasses a per-record denial.
+
+**The policy is the source of truth.** A policy declares the actions its index
+offers with `permitted_bulk_actions`, and the bar renders exactly that list:
+
+```ruby
+class ArticlePolicy < ApplicationPolicy
+  def permitted_bulk_actions = %i[publish destroy]
+
+  def publish? = user.editor?   # per-record authorization for the batch
+  def destroy? = !object.published?
+end
+```
+
+A custom action "just works" from three conventional pieces — no registration:
+
+1. list its name in `permitted_bulk_actions` (the policy),
+2. a **model bang method** for the behavior (`Article#publish!`),
+3. a **policy predicate** for authorization (`publish?`).
+
+`batch` derives both from the name — it calls `record.publish!` on each row the
+policy answers `publish?` for. Button labels and styles come from your locale
+(`en.destroy: Delete`; `bulk_actions.styles.destroy: danger`), and you override
+the whole bar for a resource by dropping an `_bulk_actions.html.haml` partial in
+its view directory.
+
+[See it live →](https://cafe-car-demo.up.railway.app/admin/users) — select rows and delete the selection.
+
+### Member Actions
+
+A **member action** runs one custom operation on a single record — a button on
+the show page and on each index row, no row selection. It's the same three
+conventional pieces as a bulk action, declared with `permitted_member_actions`:
+
+```ruby
+class ArticlePolicy < ApplicationPolicy
+  def permitted_member_actions = %i[publish]
+
+  def publish? = !object.published?   # authorizes the record, and shows/hides the button
+end
+
+class Article < ApplicationRecord
+  def publish! = update!(published_at: Time.current)
+end
+```
+
+The name resolves by convention — no registration: `publish?` authorizes and
+`Article#publish!` runs. CafeCar renders a **Publish** button on the show page's
+Actions card and on the record's index row, each a POST to
+`/articles/:id/actions/publish`. A record whose `publish?` answers false renders
+disabled with a tooltip instead of a link, so the one predicate gates both the
+display and the request — a forged POST is re-authorized and refused, and the
+bang method never runs.
+
+The action replies with a redirect that Turbo morphs in place, so the row
+reflows without a full page reload. The button's label and style come from your
+locale (`en.publish`; `actions.styles.publish: primary`), never a hardcoded
+string.
+
+Override the forwarding by defining a `publish` controller method — it takes
+over after authorization and owns the response. Override the buttons by dropping
+an `_actions.html.haml` (show) or `_controls.html.haml` (index) partial in the
+resource's view directory.
+
+[See it live →](https://cafe-car-demo.up.railway.app/admin/articles) — publish an article from its show page or index row.
+
+### Collection Actions
+
+A **collection action** runs one action over a whole set at once, from a single
+toolbar button — no row selection. It's the same three conventional pieces as a
+bulk action, declared with `permitted_collection_actions`:
+
+```ruby
+class ArticlePolicy < ApplicationPolicy
+  def permitted_collection_actions = %i[publish_all]
+
+  def publish_all? = user.editor?   # authorizes against the model class
+end
+
+class Article < ApplicationRecord
+  def self.publish_all! = unpublished.update_all(published_at: Time.current)
+end
+```
+
+The button runs over the **currently-viewed, filtered set** — not the whole
+table. It carries the active filters and search from the URL, so the action hits
+exactly the records the index is showing. Filter `?author_id=7`, and **Publish
+all** publishes that author's articles and nothing else. The button's label shows
+the reach as a count — **Publish all 21** — from your locale
+(`helpers.collection_action`, a `one`/`other` hash you can reword).
+
+Names resolve like member/bulk actions: `publish_all?` authorizes, then
+`Article.publish_all!` runs within the filtered scope. Override the forwarding by
+defining a `publish_all` controller method (scope its own query), and override
+the toolbar by dropping an `_index_actions.html.haml` partial in the view directory.
+
+### Dashboard
+
+CafeCar can render a single **dashboard** overview — an at-a-glance page that
+composes your data into metric tiles and charts. It's **opt-in the CafeCar way:
+you write one view.** Its existence turns the dashboard on; delete it and there's
+no dashboard at all (a direct hit 404s, no nav link), so a CRUD-only app never
+inherits a blank page.
+
+Write `app/views/cafe_car/dashboard/show.html.haml`:
+
+```haml
+- title "Dashboard"
+
+= Page title: "Dashboard" do |page|
+  = page.Body do
+    .Dashboard
+      = metrics User
+      = metric("Signups today") { User.where(created_at: Date.current.all_day).count }
+      = chart "New users", model: User, x: :created_at, by: :month
+```
+
+Three helpers compose the page:
+
+- **`metric("Label") { … }`** — a tile showing a label over the number your block
+  returns.
+- **`metrics(Model)`** — the tiles a **policy** declares. `Model`'s policy lists
+  the scopes to surface in `permitted_metrics` (`:all` = the whole relation), and
+  CafeCar renders a count tile for each — the same policy-is-source-of-truth rule
+  as bulk actions.
+- **`chart "Title", model:, x:, by:`** — the same dependency-free inline-SVG bar
+  chart as the index [Chart view](#advanced-usage), bucketing `model`'s records
+  over the `x` date column at `by` granularity (`:day`/`:week`/`:month`, default
+  `:month`). The `x` column is validated against the model's date-column allowlist
+  and truncated with portable Arel, so it's never interpolated as raw SQL.
+
+```ruby
+class UserPolicy < ApplicationPolicy
+  def permitted_metrics = %i[all active]   # total, then User.active.count
+end
+```
+
+Tiles render in a responsive grid at `dashboard_path` (no JavaScript, CSP-safe).
+Because the dashboard is a plain view, you can drop in headings, your own
+partials, or any markup between tiles. Once the template exists, a **Dashboard**
+link appears at the top of the sidebar nav — no template, no link.
+
+[See it live →](https://cafe-car-demo.up.railway.app/admin/dashboard) — metric tiles and a chart on one page.
+
 ### Current Context
 
 Access current request context anywhere:
@@ -760,8 +1088,66 @@ $ rails generate cafe_car:sessions
 Creates the `sessions` table migration. The `CafeCar::Session` model and
 `SessionPolicy` already ship with the engine.
 
+## Using CafeCar with AI coding agents
+
+CafeCar ships an [Agent Skill](skills/cafe_car/SKILL.md) — the mental model (the policy
+declares, the UI renders) plus ten reference pages, written for coding agents. Install it
+into your app:
+
+```bash
+$ rails generate cafe_car:agents
+```
+
+This copies the skill to `.claude/skills/cafe_car/` (Claude Code) and
+`.agents/skills/cafe_car/` (Codex, Copilot, and other agents), and adds a marker-delimited
+pointer block to your `AGENTS.md` so agents read the skill before hand-rolling admin UI.
+Safe to re-run: only the marked block is replaced; the rest of your `AGENTS.md` is never
+touched.
+
+Two more ways to put CafeCar docs in front of an agent:
+
+```bash
+$ npx skills add craft-concept/cafe_car   # install the skill in any skills-aware tool
+```
+
+Or point an MCP-capable agent at
+[gitmcp.io/craft-concept/cafe_car](https://gitmcp.io/craft-concept/cafe_car) for live
+CafeCar docs with zero setup.
+
 ## Configuration
 
+### Theme
+
+CafeCar ships three bundled themes, each a set of CSS custom properties with a
+built-in `prefers-color-scheme: dark` variant. Pick one with `CafeCar.theme`:
+
+```ruby
+# config/initializers/cafe_car.rb
+CafeCar.theme = :cool
+```
+
+| Theme    | Look                                                      |
+| -------- | --------------------------------------------------------- |
+| `:warm`  | Warm neutrals on off-white — the default.                 |
+| `:cool`  | Cool blue-grey on a crisp light background.               |
+| `:cool2` | The `cool` palette with translucent cards and darker dark mode. |
+
+The selected theme is injected as a `<link>` into every CafeCar page's `<head>`,
+so it takes effect without recompiling assets. It defaults to `:warm` (the theme
+the engine has always shipped); an unknown value raises `ArgumentError`.
+
+### Association select size
+
+`f.association` selects render at most `CafeCar.max_collection_options` options
+(default 100) to keep a large association from loading its whole target table into
+every form. Records past the cap stay reachable through the searchable select's
+typeahead feed (see [Forms](#forms)). Raise or lower the cap globally:
+
+```ruby
+# config/initializers/cafe_car.rb
+CafeCar.max_collection_options = 250
+```
+
 ### Custom Form Builder
 
 ```ruby
@@ -827,6 +1213,8 @@ development setup, how to run the tests (`bundle exec rake`), and PR expectation
 By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md). To report a
 security issue, see [SECURITY.md](SECURITY.md).
 
+If CafeCar saved you an afternoon, a star helps other Rails developers find it.
+
 ## License
 
 The gem is available as open source under the terms of the

data/Rakefile

@@ -19,6 +19,6 @@ end
 
 task default: %i[rubocop test brakeman]
 
-# Holdco backlog machinery (tasks:new, tasks:index, tasks:claim, tasks:done, rake task).
-# Loads every .rake under lib/tasks/ so the gem's own tasks and holdco_tasks both run.
+# Load the gem's own rake tasks under lib/tasks/ (the backlog now lives on the
+# holdco-tasks board — see `bin/operate tasks`).
 Dir.glob(File.expand_path("lib/tasks/*.rake", __dir__)).sort.each { |f| load f }

data/app/assets/stylesheets/cafe_car/chart.css

@@ -0,0 +1,41 @@
+@layer component {
+  .ChartControls {
+    display: flex;
+    gap: var(--half-gap);
+    align-items: center;
+    margin-block-end: var(--gap);
+  }
+
+  /* Fill the column at the SVG's fixed landscape viewBox ratio (see
+     ChartBuilder::WIDTH/HEIGHT). `height: auto` lets the height track that ratio,
+     so the chart stays a steady ~3.5:1 landscape at any bucket count instead of
+     rendering tall-and-narrow (few buckets) or flat (many). max-height keeps it
+     from getting oversized on very wide screens; the SVG's preserveAspectRatio
+     letterboxes cleanly if the cap trims the ratio. */
+  .Chart {
+    display: block;
+    width: 100%;
+    height: auto;
+    max-height: 360px;
+    color: var(--accent);
+    overflow: visible;
+  }
+
+  .Chart-bar rect {
+    transition: opacity var(--duration);
+  }
+
+  .Chart-bar:hover rect {
+    opacity: 0.8;
+  }
+
+  .Chart-value {
+    fill: var(--dim);
+    font-size: 11px;
+  }
+
+  .Chart-label {
+    fill: var(--dim);
+    font-size: 11px;
+  }
+}