cafe_car 0.2.1 → 0.3.0

data/lib/cafe_car/policy.rb

@@ -13,30 +13,100 @@ module CafeCar::Policy
   end
 
   def title_attribute
-    @title_attribute ||= displayable_attributes.first
+    @title_attribute ||= attributes.displayable.first
   end
 
-  def logo_attribute
-    model.info.fields.listable.attachments.first&.method
+  # The bulk actions offered on this model's index table — the policy is the source
+  # of truth. Each name maps to a policy predicate (`name?`, authorized per record
+  # in Controller#batch) and a model bang method (`name!`, applied to each). Ships
+  # with `:destroy`; a host lists its own (e.g. `%i[publish destroy]`) by overriding
+  # this, with no registration anywhere else. Return `[]` to offer none.
+  def permitted_bulk_actions = %i[destroy]
+
+  # The custom actions offered on a single record — rendered on the show page's
+  # Actions card and on each index row. Same derivation as
+  # #permitted_bulk_actions: the `name?` predicate authorizes and the record's
+  # `name!` bang method runs (see Controller#member_action). Empty by default;
+  # a host lists its own (e.g. `%i[publish]`) with no registration anywhere else.
+  def permitted_member_actions = []
+
+  # The custom actions offered on the whole collection — rendered in the index
+  # toolbar. The `name?` predicate authorizes (asked of the model class, not a
+  # record) and `name!` runs on the policy scope, which ActiveRecord delegates
+  # to a class method (see Controller#collection_action). Empty by default.
+  def permitted_collection_actions = []
+
+  # The metrics the dashboard renders for this model by default — the same
+  # policy-is-source-of-truth pattern as #permitted_bulk_actions. Each name is a
+  # model scope (`:all` = the whole relation) whose row count becomes a tile; the
+  # `metrics` view helper reads this list. Empty by default (opt in per model).
+  def permitted_metrics = []
+
+  # The attributes (columns and associations) a user may filter an index by —
+  # the same policy-is-source-of-truth pattern: the filter UI enumerates this
+  # list, and Controller::Filtering drops URL filter keys that aren't on it.
+  # Defaults to `attributes.displayable` (Rails' parameter filter already strips
+  # password/token columns); a host overrides this to narrow or widen the list.
+  def permitted_filters = attributes.displayable
+
+  # The named model scopes invokable as URL filter params — `?published=true`
+  # calls the `published` scope. Empty by default (opt in per model): a scope
+  # key reaches `QueryBuilder#scope!`, which can invoke any public class method
+  # with a URL-supplied argument, so a host lists the safe ones explicitly.
+  def permitted_scopes = []
+
+  # Is `attribute` filterable? Compares the attribute's canonical form against the
+  # policy's #permitted_filters, canonicalized the same way — so a foreign key and
+  # its association match (`client_id` ≡ `:client`), and a nested dot-path
+  # (`client.status`) is honored only when its FULL path is permitted. The lone
+  # implicit exception is a permitted association's `.id` set-membership control
+  # (see #set_membership?), which needs no separate declaration.
+  def permitted_filter?(attribute)
+    path = canonical_filter(attribute.to_s)
+    permitted_filter_paths.include?(path) || set_membership?(path)
   end
 
-  def listable_attributes
-    model.info.fields.listable.map(&:method)
+  # The permitted filters as canonical dot-paths (foreign keys resolved to their
+  # associations) — the gate's whitelist, memoized. A nested filter is permitted
+  # iff its canonical path is a member, exactly like a top-level one.
+  def permitted_filter_paths
+    @permitted_filter_paths ||= permitted_filters.map { canonical_filter(_1.to_s) }
   end
 
-  def displayable_attributes
-    permitted_attribute_keys
-      .union(model.columns.map(&:name).map(&:to_sym))
-      .map    { association_for_attribute(_1) || _1 }
-      .reject { filtered_attribute? _1 } - %i[id]
+  # `<assoc>.id` is the association-membership control (`?line_items.id[]=`): pick
+  # associated records by id. It's sanctioned whenever the association itself is a
+  # permitted filter, so the has_many `_has_many_filter` control needs no separate
+  # `.id` declaration — the same rule that let it through before nested paths.
+  def set_membership?(path)
+    parent, _, leaf = path.to_s.rpartition(".")
+    leaf == "id" && permitted_filter_paths.include?(parent)
   end
 
-  def permitted_fields
-    @permitted_fields ||= permitted_attribute_keys.map { info _1 }
+  # Canonical form of a (possibly dotted) filter key: each association hop keeps
+  # its association name and the terminal foreign key resolves to its association
+  # (`client.owner_id` → `client.owner`), so a declaration and the param a control
+  # posts compare equal regardless of which form the host wrote. Walks segment by
+  # segment through the associated models; a segment that isn't a real association
+  # (a bad hop, or the terminal attribute) passes through untouched, so an
+  # undeclared path simply fails the membership check — it never reaches SQL.
+  def canonical_filter(key, klass = model)
+    head, dot, rest = key.to_s.partition(".")
+    return (info_for(klass, head).reflection&.name || head).to_s if dot.empty?
+
+    ref = klass.reflect_on_association(head) or return key.to_s
+    "#{head}.#{canonical_filter(rest, ref.klass)}"
+  end
+
+  def info_for(klass, method) = CafeCar[:FieldInfo].new(model: klass, method:)
+
+  def permitted_scope?(name) = permitted_scopes.include?(name.to_sym)
+
+  def logo_attribute
+    model.info.fields.listable.attachments.first&.method
   end
 
-  def editable_attributes
-    permitted_fields.map(&:input_key) - permitted_fields.flat_map(&:abrogated_keys)
+  def permitted_fields
+    @permitted_fields ||= permitted_attribute_keys.map { info _1 }
   end
 
   def displayable_associations
@@ -68,7 +138,7 @@ module CafeCar::Policy
   end
 
   def displayable_attribute?(attribute)
-    displayable_attributes.include?(attribute.to_sym)
+    attributes.displayable.include?(attribute.to_sym)
   end
 
   def association_for_attribute(attribute)

data/lib/cafe_car/query_builder.rb

@@ -24,6 +24,14 @@ module CafeCar
       end
     end
 
+    # Word-form comparison operators for URL filters — `price.min=10` parses to
+    # `{ "price" => { "min" => "10" } }`, and each word maps to an Arel predicate.
+    # `min`/`max` read friendlier than `gte`/`lte` and are the documented spelling.
+    OPS = {
+      "eq"  => "==", "gt"  => ">",  "lt"  => "<",
+      "gte" => ">=", "lte" => "<=", "min" => ">=", "max" => "<="
+    }.freeze
+
     attr_reader :scope
 
     def initialize(scope)
@@ -67,6 +75,11 @@ module CafeCar
         parse_range(key, value)
       in Array | Op
         value.map { parse_value(key, _1) }
+      # An enum key ("archived") passes through untouched — ActiveRecord casts it
+      # to the stored value itself; coercing by column type would `to_i` an
+      # integer-backed enum's key to 0, the wrong bucket.
+      in String if enum?(key)
+        value
       in "true" then true
       in "false" then false
       in String
@@ -95,6 +108,8 @@ module CafeCar
 
     def column(name)       = @scope.columns_hash[name.to_s]
     def reflection(name)   = @scope.reflect_on_association(name)
+    def info(name)         = CafeCar[:ModelInfo].find(@scope.model).field(chomp(name))
+    def enum?(name)        = info(name).enum?
     def association?(name) = reflection(name).present?
     def attribute?(name)   = column(name).present?
     def scope?(name)       = name.intern.in? @scope.local_methods
@@ -126,10 +141,17 @@ module CafeCar
         @scope.where!(arel(key).matches_regexp(value.source, !value.casefold?))
       in _, Op
         @scope.where!(parse(key, value).arel(arel(key)))
+      in _, Hash if operators?(value)
+        value.each { |word, rhs| attribute!(key, Op.new(OPS[word.to_s], rhs)) }
       else @scope.where!(key => parse(key, value))
       end
     end
 
+    # A filter value like `{ "min" => 10, "max" => 50 }` — every key a known
+    # comparison operator — desugars to `>= 10 AND <= 50` rather than an
+    # equality against the literal hash.
+    def operators?(value) = value.any? && value.keys.all? { OPS.key?(_1.to_s) }
+
     def association!(name, value, ...)
       update! do
         case value

data/lib/cafe_car/routing.rb

@@ -6,12 +6,36 @@ module CafeCar
       @concerns[:batchable] || begin
         concern :batchable do
           collection do
-            patch :update_all
+            post :batch
           end
         end
       end
 
-      super(*, **, concerns: [ :batchable, *concerns ], &)
+      # JSON typeahead feed for searchable association selects (Tom Select).
+      # `GET /<resources>/options?q=` returns policy-scoped [{value, text}] pairs,
+      # letting an association field reach records past `max_collection_options`.
+      @concerns[:searchable] || begin
+        concern :searchable do
+          collection do
+            get :options
+          end
+        end
+      end
+
+      # Policy-declared custom actions (Policy#permitted_member_actions /
+      # #permitted_collection_actions) route through one generic endpoint each —
+      # the action name is a URL param, so a host never enumerates them here.
+      # POST /<resources>/:id/actions/:member_action → Controller#member_action
+      # POST /<resources>/actions/:collection_action → Controller#collection_action
+      # The policy whitelists which names resolve; anything else is a 404.
+      @concerns[:actionable] || begin
+        concern :actionable do
+          member     { post "actions/:member_action",     action: :member_action,     as: :member_action }
+          collection { post "actions/:collection_action", action: :collection_action, as: :collection_action }
+        end
+      end
+
+      super(*, **, concerns: [ :batchable, :searchable, :actionable, *concerns ], &)
     end
   end
 end

data/lib/cafe_car/table/builder.rb

@@ -35,7 +35,7 @@ module CafeCar::Table
 
     def timestamp_attribute = %w[updated_at created_at].find { has? _1 }
 
-    def remaining_attributes = policy.listable_attributes - @shown_attributes.keys
+    def remaining_attributes = policy.attributes.listable - @shown_attributes.keys
 
     def remaining(except: [])
       capture do

data/lib/cafe_car/table/foot_builder.rb

@@ -8,6 +8,7 @@ module CafeCar::Table
     def cell!           = (@count += 1; nil)
     def cell(...)       = (super; cell!)
     def controls(...)   = cell!
+    def select(...)     = (cell! if @template.bulk_actions?)
 
     def to_html = ""
   end

data/lib/cafe_car/table/head_builder.rb

@@ -21,6 +21,12 @@ module CafeCar::Table
 
     def controls(*, **) = cell(:controls, :controls, *, label: nil, **)
 
+    def select(*, **)
+      return unless @template.bulk_actions?
+      check_all = @template.tag.input(type: :checkbox, data: { bulk_select_all: true }, "aria-label": "Select all")
+      cell(:select, :select, *, label: check_all, **)
+    end
+
     def to_html = ui.Head(:sticky) { capture(self, &@block) }
   end
 end

data/lib/cafe_car/table/row_builder.rb

@@ -32,6 +32,13 @@ module CafeCar::Table
       ui.Cell(:shrink, :shy, :controls, *args) { present(@object).controls(*args, **options) }
     end
 
+    def select(*args)
+      return unless @template.bulk_actions?
+      ui.Cell(:select, *args) do
+        @template.check_box_tag("ids[]", @object.id, false, id: nil, "aria-label": "Select this row")
+      end
+    end
+
     def to_html
       ui.Row { safe_join [ capture(self, &@block), @template.turbo_stream_from(@object) ] }
     end

data/lib/cafe_car/version.rb

@@ -1,3 +1,3 @@
 module CafeCar
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/cafe_car.rb

@@ -3,12 +3,10 @@ require "cafe_car/core_ext"
 require "cafe_car/version"
 require "cafe_car/engine"
 require "cafe_car/resolver"
-require "cafe_car/auto_resolver"
 require "cafe_car/proc_helpers"
 
 module CafeCar
   include Resolver
-  extend AutoResolver
   extend ProcHelpers
 
   class MissingAttributeError < StandardError
@@ -27,6 +25,38 @@ module CafeCar
   # of exporting a large table; truncated exports signal `X-CafeCar-Truncated`.
   mattr_accessor :csv_export_row_limit, default: 10_000
 
+  # Upper bound on an index page's `?per=`. Clamps oversized requests so a caller
+  # can't force the whole table into memory with `?per=1000000` (a DoS footgun);
+  # the effective per-page is silently capped, not rejected.
+  mattr_accessor :max_per_page, default: 200
+
+  # Upper bound on the number of `<option>`s an association select loads. Bounds
+  # the memory/latency cost of rendering a `belongs_to`/`has_many` field on every
+  # form and filter sidebar; without it a 10k-row association loads the whole
+  # table into memory each request. (A searchable/remote select is the fix for
+  # associations larger than this — a separate follow-up.)
+  mattr_accessor :max_collection_options, default: 100
+
+  # Bundled themes selectable via `CafeCar.theme`. Each lives at
+  # `app/assets/stylesheets/cafe_car/themes/<name>.css` as a set of CSS custom
+  # properties layered over `themes/defaults.css`, with its own dark-mode block.
+  THEMES = %i[warm cool cool2].freeze
+
+  # The active bundled theme, injected as a <link> into every CafeCar page's
+  # <head> (see `CafeCar::Helpers#theme_stylesheet_tag`). Defaults to `:warm` —
+  # the theme the engine has always shipped — so an unset host renders unchanged.
+  # Assigning a value outside THEMES raises rather than rendering unstyled.
+  mattr_reader :theme, default: :warm
+
+  def self.theme=(name)
+    name = name&.to_sym
+    unless THEMES.include?(name)
+      raise ArgumentError,
+        "unknown CafeCar theme #{name.inspect} (valid: #{THEMES.map(&:inspect).join(", ")})"
+    end
+    @@theme = name
+  end
+
   # The host's user model, resolved lazily so the constant need not exist at
   # boot. Used by CafeCar::Session for authentication.
   def self.user_class = user_class_name.to_s.constantize

data/lib/generators/cafe_car/agents/USAGE

@@ -0,0 +1,13 @@
+Description:
+    Installs CafeCar's agent docs into the host app so coding agents reach for
+    CafeCar instead of hand-rolling admin UI.
+
+    Copies the CafeCar Agent 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 AGENTS.md (created if missing).
+
+    Safe to re-run: the skill copies are overwritten and only the marked
+    block in AGENTS.md is replaced — your own content is never touched.
+
+Example:
+    bin/rails generate cafe_car:agents

data/lib/generators/cafe_car/agents/agents_generator.rb

@@ -0,0 +1,49 @@
+class CafeCar::AgentsGenerator < Rails::Generators::Base
+  source_root File.expand_path("../../../..", __dir__)
+
+  BLOCK = <<~MD.freeze
+    <!-- cafe_car:start -->
+    This app uses the **cafe_car** gem. Before hand-rolling any admin / back-office / index / CRUD
+    UI, read `.claude/skills/cafe_car/SKILL.md` — point a controller at a model and the Pundit policy
+    drives the whole UI (filtering, sorting, turbo-streams, CSV) for free.
+    <!-- cafe_car:end -->
+  MD
+
+  MARKED_BLOCK = /^<!-- cafe_car:start -->.*?<!-- cafe_car:end -->/m
+
+  def copy_skill
+    directory "skills/cafe_car", ".claude/skills/cafe_car", force: true
+    directory "skills/cafe_car", ".agents/skills/cafe_car", force: true
+  end
+
+  def update_agents_md
+    if agents_md&.match?(MARKED_BLOCK)
+      gsub_file "AGENTS.md", MARKED_BLOCK, BLOCK.chomp
+    elsif agents_md
+      append_to_file "AGENTS.md", "\n#{BLOCK}"
+    else
+      create_file "AGENTS.md", BLOCK
+    end
+  end
+
+  def post_install
+    say <<~MSG
+
+      CafeCar agent docs installed:
+        .claude/skills/cafe_car/   Claude Code skill
+        .agents/skills/cafe_car/   mirror for Codex, Copilot, and other agents
+        AGENTS.md                  pointer block (re-runs replace only the marked block)
+
+      Optional, for your team:
+        npx skills add craft-concept/cafe_car      # install the skill in any skills-aware tool
+        https://gitmcp.io/craft-concept/cafe_car   # live CafeCar docs over MCP, zero setup
+    MSG
+  end
+
+  private
+
+  def agents_md
+    path = File.join(destination_root, "AGENTS.md")
+    File.read(path) if File.exist?(path)
+  end
+end

data/lib/generators/cafe_car/resource/resource_generator.rb

@@ -25,7 +25,18 @@ class CafeCar::ResourceGenerator < Rails::Generators::NamedBase
   # generator's `field:type:index` form. Forwarding them lets the policy list
   # real permitted attributes instead of falling back to model introspection,
   # which can't see a model that isn't a loaded constant yet mid-run.
-  def field_names = attributes.map { _1.to_s.split(":").first }
+  #
+  # A `:references`/`belongs_to` field must be permitted by its foreign key
+  # (`invoice_id`), not the bare association (`invoice`) — that's the column
+  # strong-params actually receives. Polymorphic refs need `_id` + `_type`
+  # (mirrors notes_generator's hardcoded `notable_id notable_type`).
+  def field_names
+    attributes.flat_map do |attr|
+      next attr.name unless attr.reference?
+
+      [ "#{attr.name}_id", ("#{attr.name}_type" if attr.polymorphic?) ].compact
+    end
+  end
 
   def assign_controller_names!(...)
     if options[:model_name].blank?

data/lib/tasks/demo.rake

@@ -0,0 +1,9 @@
+namespace :demo do
+  desc "Effect-level smoke check against the live demo (DEMO_URL to override the host)"
+  task :smoke do
+    script = File.expand_path("../../bin/demo-smoke", __dir__)
+    # Deliberately standalone + on-demand — NOT part of the `default` (CI) task:
+    # coupling repo CI to the external demo's uptime would make CI flaky.
+    exit(1) unless system(RbConfig.ruby, script)
+  end
+end

data/llms.txt

@@ -0,0 +1,25 @@
+# CafeCar
+
+> CafeCar is a composable view extension for Rails. Point a controller at a model and the Pundit policy drives complete index, show, new, and edit pages — keyword search, URL-based filtering and sorting, pagination, CSV export, bulk actions, and Turbo-morph live updates included. Every default can be overridden with ordinary Rails views and partials; there is no config DSL.
+
+Key conventions: the policy is the source of truth (what's visible, editable, and permitted); customization goes policy → presenter → partial override → controller, cheapest first; UI copy lives in locales; styles live in component CSS.
+
+## Docs
+
+- [README](https://github.com/craft-concept/cafe_car/blob/main/README.md): installation, getting started, and the full feature reference
+- [Agent Skill](https://github.com/craft-concept/cafe_car/blob/main/skills/cafe_car/SKILL.md): the mental model and customization ladder, written for coding agents
+- [Controllers](https://github.com/craft-concept/cafe_car/blob/main/skills/cafe_car/references/controllers.md): the `cafe_car` macro, scope, callbacks, custom actions
+- [Policies](https://github.com/craft-concept/cafe_car/blob/main/skills/cafe_car/references/policies.md): Pundit policies as the source of truth — permissions, scopes, permitted attributes
+- [Presenters](https://github.com/craft-concept/cafe_car/blob/main/skills/cafe_car/references/presenters.md): per-attribute rendering with `show ... as:`
+- [Views](https://github.com/craft-concept/cafe_car/blob/main/skills/cafe_car/references/views.md): the partial-override ladder, per-resource and app-wide
+- [Forms](https://github.com/craft-concept/cafe_car/blob/main/skills/cafe_car/references/forms.md): automatic forms from permitted attributes
+- [Filtering](https://github.com/craft-concept/cafe_car/blob/main/skills/cafe_car/references/filtering.md): URL query params for search, ranges, comparisons, sorting
+- [Components](https://github.com/craft-concept/cafe_car/blob/main/skills/cafe_car/references/components.md): the UI component set and component-scoped styling
+- [Turbo](https://github.com/craft-concept/cafe_car/blob/main/skills/cafe_car/references/turbo.md): Turbo Stream responses and live morph updates
+- [Locales](https://github.com/craft-concept/cafe_car/blob/main/skills/cafe_car/references/locales.md): all UI copy via i18n
+- [Navigation](https://github.com/craft-concept/cafe_car/blob/main/skills/cafe_car/references/navigation.md): menus and layout
+- [CHANGELOG](https://github.com/craft-concept/cafe_car/blob/main/CHANGELOG.md): what changed in each release
+
+## Optional
+
+- [Live demo](https://cafe-car-demo-production.up.railway.app): a clickable CafeCar app, no signup

data/skills/cafe_car/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: cafe_car
+description: >-
+  Use when building admin, back-office, index, or CRUD UI in a Rails app that has the
+  cafe_car gem: point a controller at a model (the `cafe_car` macro) and the Pundit
+  policy drives complete index/show/new/edit pages — filtering, sorting, keyword search,
+  pagination, CSV export, bulk actions, and Turbo-morph live updates included. Do not
+  hand-roll admin controllers or views in these apps; extend CafeCar's defaults.
+when_to_use: >-
+  Any task touching list/detail/form UI for an ActiveRecord model in an app with
+  cafe_car in the Gemfile: adding an admin section, changing visible columns or fields,
+  restricting access, filtering or sorting an index, adding buttons to cards or rows,
+  bulk actions, dashboards, theming, or live-updating records across clients.
+---
+
+# CafeCar
+
+CafeCar is a composable view extension for Rails. It renders index, show, new, and
+edit straight from the model at runtime — you delete view files instead of writing
+them. One controller line gives you the whole CRUD surface; you then override only
+the pieces that need to differ.
+
+**Never hand-roll an admin page in a CafeCar app.** A hand-written index loses
+Turbo-morph updates, the standard query params, policy-driven columns, association
+links, bulk actions, and CSV export — all of which the default views carry for free.
+
+## The mental model: the policy declares, the UI renders
+
+The Pundit policy is the source of truth. It declares who may do what
+(`index?`, `update?`, …), which rows are visible (`Scope#resolve`), which fields are
+editable (`permitted_attributes`), which bulk actions exist
+(`permitted_bulk_actions`), and which dashboard metrics show (`permitted_metrics`).
+The default views render exactly what the policy declares.
+
+So the customization ladder, cheapest first:
+
+1. **Policy** — change what's permitted/visible. Most "change the UI" tasks end here.
+2. **Presenter** — change how a value renders (`show :total, as: :currency`).
+3. **Partial override** — drop a same-named view file to replace one piece, for one
+   resource or app-wide.
+4. **Controller** — override `scope`, add callbacks, or replace an action.
+
+Configuration is views and partials, not config DSLs. Copy lives in locales, not
+templates. Styles live in component CSS, not global stylesheets.
+
+## Point a controller at a model
+
+```ruby
+# config/routes.rb
+namespace :admin do
+  resources :products      # also auto-adds POST batch + GET options collection routes
+end
+
+# app/controllers/admin/products_controller.rb
+module Admin
+  class ProductsController < ApplicationController
+    cafe_car
+  end
+end
+
+# app/policies/product_policy.rb
+class ProductPolicy < ApplicationPolicy
+  def index?   = user.present?
+  def show?    = index?
+  def create?  = user.admin?
+  def update?  = user.admin?
+  def destroy? = update?
+
+  def permitted_attributes = %i[name price description category_id]
+
+  class Scope < Scope
+    def resolve = scope.all
+  end
+end
+```
+
+That's the whole feature. `/admin/products` now serves index (table/grid/chart
+views), show, new, edit, JSON, and CSV. Generators scaffold these files:
+`bin/rails g cafe_car:resource admin/products name:string price:decimal` (model +
+migration + route + controller + policy), or `cafe_car:controller` /
+`cafe_car:policy` individually. First-time setup in a bare app:
+`bin/rails g cafe_car:install`.
+
+Every ActiveRecord model also gets `.query(params)`, `.sorted(*keys)`, and `.info`
+automatically — no opt-in, no include.
+
+## Recipes
+
+| How do I… | See |
+|---|---|
+| Add an admin section for a model | above; [controllers](references/controllers.md) |
+| Change which columns/fields show or are editable | [policies](references/policies.md) |
+| Restrict which rows a user sees | [policies](references/policies.md) — `Scope#resolve` |
+| Narrow one controller's collection (`def scope = super.published`) | [controllers](references/controllers.md) |
+| Add a bulk action (Publish button on the index) | [policies](references/policies.md) — bulk actions |
+| Filter/sort/search an index via URL params | [filtering](references/filtering.md) |
+| Add buttons or fields to grid cards / table rows | [views](references/views.md) |
+| Override one view for one resource vs app-wide | [views](references/views.md) |
+| Change how a value renders (currency, links, previews) | [presenters](references/presenters.md) |
+| Customize a form field or input type | [forms](references/forms.md) |
+| Add a sidebar link | add an `index` route — [navigation](references/navigation.md) |
+| Add a dashboard with metric tiles and charts | [navigation](references/navigation.md) — dashboard |
+| Re-theme, style a component, add a component | [components](references/components.md) |
+| Make edits sync live across clients | [turbo](references/turbo.md) — `broadcasts_refreshes` |
+| Change labels, hints, flashes, button styles | [locales](references/locales.md) |
+| Link to a related object | [presenters](references/presenters.md) — `href_for`, `link` |
+
+## Reference pages
+
+- [controllers.md](references/controllers.md) — the `cafe_car` macro, the scope
+  pipeline, callbacks, batch/options endpoints
+- [policies.md](references/policies.md) — the source of truth: predicates, scopes,
+  attributes, bulk actions, metrics
+- [presenters.md](references/presenters.md) — how values render; `show` macros
+- [forms.md](references/forms.md) — the form builder, type inference, nested records
+- [filtering.md](references/filtering.md) — the dot-query URL grammar, sort, search,
+  CSV, chart view
+- [views.md](references/views.md) — the partial override system (the crux)
+- [components.md](references/components.md) — the UI component system, CSS, theming
+- [navigation.md](references/navigation.md) — route-driven sidebar; the dashboard
+- [turbo.md](references/turbo.md) — Turbo-morph refreshes and cross-client sync
+- [locales.md](references/locales.md) — all UI copy and where its keys live
+
+## Ground truth
+
+These pages teach conventions, not a frozen API. When in doubt, read the shipped
+defaults — they are the best examples of idiomatic CafeCar and always current:
+
+```sh
+cd "$(bundle show cafe_car)"
+ls app/views/application/            # overridable shared partials
+ls app/views/cafe_car/application/   # action templates + turbo_stream responses
+cat lib/cafe_car/controller.rb       # the macro and the scope pipeline
+cat lib/cafe_car/policy.rb           # everything a policy can declare
+```