From eb6f466ab822487aa2edec743dbe88b74c9d6a86 Mon Sep 17 00:00:00 2001
From: mhenrixon <mikael@mhenrixon.com>
Date: Fri, 3 Jul 2026 15:53:26 +0200
Subject: [PATCH] docs(dogfood): rewrite the docs-kit docs site to cover the
 whole gem
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The dogfood site had drifted badly behind the gem (epic #8 shipped Markdown
islands, the API-docs kit, the .md twin, llms.txt, search, MCP, --sync, and
more — none of it documented). Rewrite + extend so the site documents AND
demonstrates every capability, each page dogfooding the gem.

Registry + nav (app/models/doc.rb)
- Regrouped into 5 headings: Getting started / Authoring / Reference /
  AI & tooling / Deploy. nav_registries stays the canonical nav path.

New pages
- Markdown authoring (/docs/markdown) — the `md` island, the single-quoted
  heredoc convention, the GFM vocabulary rendered LIVE, how it flows into the
  .md twin.
- API reference (/docs/api) — renders a live DocsUI::Endpoint + FieldTable +
  ErrorTable + RequestExample (4 client tabs) + JsonResponse, plus the
  api_base_url/api_auth_header/api_clients config.
- AI & agents (/docs/ai) — the .md twin, the Markdown masthead action,
  /llms.txt + /llms-full.txt, the built-in MCP server, and the AGENTS.md +
  write-docs-page skill the generator scaffolds.
- Search (/docs/search) — server-rendered search + the ⌘K palette, the
  search_/search_path/search_shortcuts config, progressive enhancement.

Rewrites
- Configuration — the "All options" table is now COMPLETE (28/28 knobs with
  defaults, was 13), grouped by concern; notes version_badge accepts a String
  or callable; nav_registries canonical, c.nav the escape hatch.
- Overview — current "What you get" covering the whole surface, each feature
  linking to its page.
- Installation — documents the --sync additive upgrade path.
- Styling & CSS — adds c.code_theme / code_theme_dark / dark_themes (the
  light/dark Rouge highlight mechanism), corrected to describe the now-graceful
  theme-name degradation (not the old NameError crash).
- Authoring — expanded building-blocks section links to the dedicated pages.

Every page dogfoods the kit (md islands, DocsUI::Section/Code, live component
renders) and renders 200; the .md twin, /llms.txt, /llms-full.txt, and search
all render clean. Gem suite stays green (538 examples).

Refs #8

Claude-Session: https://claude.ai/code/session_01FPQb6z3YwcKRMbvoJhdxnX
---
 docs/app/models/doc.rb                     |  31 +-
 docs/app/views/docs/pages/ai.rb            | 335 +++++++++++++++++++
 docs/app/views/docs/pages/api.rb           | 353 +++++++++++++++++++++
 docs/app/views/docs/pages/authoring.rb     | 127 ++++----
 docs/app/views/docs/pages/configuration.rb | 324 ++++++++++++++-----
 docs/app/views/docs/pages/installation.rb  | 101 +++++-
 docs/app/views/docs/pages/markdown.rb      | 308 ++++++++++++++++++
 docs/app/views/docs/pages/overview.rb      | 173 +++++-----
 docs/app/views/docs/pages/search.rb        | 347 ++++++++++++++++++++
 docs/app/views/docs/pages/styling.rb       | 271 +++++++++++-----
 docs/config/initializers/docs_kit.rb       |   6 +-
 11 files changed, 2054 insertions(+), 322 deletions(-)
 create mode 100644 docs/app/views/docs/pages/ai.rb
 create mode 100644 docs/app/views/docs/pages/api.rb
 create mode 100644 docs/app/views/docs/pages/markdown.rb
 create mode 100644 docs/app/views/docs/pages/search.rb

diff --git a/docs/app/models/doc.rb b/docs/app/models/doc.rb
index 93b1fa7..a9f18ab 100644
--- a/docs/app/models/doc.rb
+++ b/docs/app/models/doc.rb
@@ -13,13 +13,26 @@ class Doc
   path_prefix    "/docs"
   view_namespace "Views::Docs::Pages"
 
-  page "Overview",        group: "Getting started"
-  page "Installation",    group: "Getting started"
-  page "Configuration",   group: "Getting started"
-  page "Authoring pages", group: "Getting started", slug: "authoring", view: "Authoring"
-  page "Styling & CSS",   group: "Getting started", slug: "styling", view: "Styling"
-  page "Components",      group: "Reference"
-  page "Code languages",  group: "Reference", slug: "languages", view: "Languages"
-  page "On this page",    group: "Reference"
-  page "Deploy",          group: "Reference"
+  # Getting started
+  page "Overview",      group: "Getting started"
+  page "Installation",  group: "Getting started"
+  page "Configuration", group: "Getting started"
+  page "Styling & CSS", group: "Getting started", slug: "styling", view: "Styling"
+
+  # Authoring
+  page "Authoring pages",    group: "Authoring", slug: "authoring", view: "Authoring"
+  page "Markdown authoring", group: "Authoring", slug: "markdown", view: "Markdown"
+  page "Code languages",     group: "Authoring", slug: "languages", view: "Languages"
+  page "API reference",      group: "Authoring", slug: "api", view: "Api"
+
+  # Reference
+  page "Components",   group: "Reference"
+  page "On this page", group: "Reference"
+
+  # AI & tooling
+  page "AI & agents", group: "AI & tooling", slug: "ai", view: "Ai"
+  page "Search",      group: "AI & tooling"
+
+  # Deploy
+  page "Deploy", group: "Deploy"
 end
diff --git a/docs/app/views/docs/pages/ai.rb b/docs/app/views/docs/pages/ai.rb
new file mode 100644
index 0000000..292b4bc
--- /dev/null
+++ b/docs/app/views/docs/pages/ai.rb
@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+module Views
+  module Docs
+    module Pages
+      # Everything that makes a docs-kit site machine-readable: the automatic
+      # `.md` twin per page (+ the "Markdown" masthead action), /llms.txt and
+      # /llms-full.txt, and the built-in read-only MCP server. All derived from
+      # the SAME render the HTML pages use — the author writes nothing extra.
+      class Ai < DocsUI::Page
+        title "AI & agents"
+        eyebrow "AI & tooling"
+
+        def lead = "Every page is machine-readable for free — a Markdown twin, an llms.txt index, and a read-only MCP endpoint, all built from the same render your readers see."
+
+        def content
+          overview_section
+          md_twin_section
+          markdown_action_section
+          llms_section
+          mcp_section
+          agents_section
+        end
+
+        private
+
+        def overview_section
+          DocsUI::Section("Machine-readable, for free",
+                          description: "Four surfaces, one render — the .md twin, llms.txt, llms-full.txt, and MCP all read from the page you already wrote.") do
+            md <<~'MD'
+              docs-kit derives its agent-facing surfaces from the **same render**
+              the HTML pages use — so they never drift and you author nothing
+              extra:
+
+              - **The `.md` twin** — every page has a GFM Markdown copy at
+                `GET /docs/x.md`, converted post-render from the page's own HTML.
+                This page's twin is [/docs/ai.md](/docs/ai.md).
+              - **The "Markdown" action** — the masthead button that copies (or
+                opens) the current page's twin.
+              - **[/llms.txt](/llms.txt) + [/llms-full.txt](/llms-full.txt)** — the
+                llmstxt.org index and the full-text concatenation, built straight
+                from the registry.
+              - **The MCP endpoint** — an optional read-only `POST /mcp` server
+                exposing `list_pages` / `get_page` / `search_docs`.
+
+              None of it is a second source of truth. The `.md` twin is a
+              conversion of the rendered `#docs-content`; llms.txt is the registry;
+              MCP reads the same twins and the same [search](/docs/search) index.
+            MD
+          end
+        end
+
+        def md_twin_section
+          DocsUI::Section("The .md twin",
+                          description: "GET /docs/x.md returns faithful Markdown of exactly what /docs/x shows.") do
+            md <<~'MD'
+              A controller that includes `DocsKit::Controller` gets the twin
+              automatically: `render_page(view)` serves the page's GFM Markdown
+              instead of HTML when the request format is `.md` (or `.text` as an
+              alias). Same page class, same render, `text/markdown` body — you
+              write nothing extra.
+            MD
+
+            DocsUI::Code(<<~RUBY, filename: "app/controllers/docs_controller.rb")
+              class DocsController < ApplicationController
+                include DocsKit::Controller
+
+                def show
+                  render_page(Views::Docs::Pages.const_get(params[:page].classify).new)
+                end
+              end
+            RUBY
+
+            md <<~'MD'
+              The conversion is `DocsKit::MarkdownExport`: it renders the page to
+              HTML, extracts the `#docs-content` subtree that `DocsUI::Shell`
+              stamps, strips `[data-md-skip]` / `<script>` / `<style>`, and walks
+              the remaining DOM to GFM. Because it runs **after** the render,
+              authoring style is irrelevant — Phlex components, `md` islands, and
+              raw tags in `prose` all convert identically. A page with no
+              `#docs-content` region yields an empty body (`200` with `""`), never
+              a 404, and the HTML route is untouched.
+            MD
+
+            DocsUI::Callout(:note) do
+              plain "The host must route the "
+              code { ".md" }
+              plain "/"
+              code { ".text" }
+              plain " format (a format-aware or catch-all route). "
+              code { ".text" }
+              plain " is accepted only so hosts whose routes permit the built-in "
+              code { ":text" }
+              plain " format still get the twin."
+            end
+
+            md <<~'MD'
+              The page chrome never leaks into the twin: `DocsUI::Page` stamps
+              `data-md-skip` on its top nav (the "← Home" link and the "Markdown"
+              action), so the export drops it. Anything you want kept out of the
+              `.md` can opt out the same way — wrap it in
+              `data: { md_skip: true }`.
+            MD
+
+            render DocsUI::PropTable.new(
+              [
+                [ "GET /docs/x.md", "route", "—", "The page's GFM twin (.text is an alias)." ],
+                [ "DocsKit::Controller#render_page", "method", "—", "Serves the twin on a .md/.text request, HTML otherwise." ],
+                [ "DocsKit::MarkdownExport.new(view).to_md", "class", "—", "The HTML→GFM converter over #docs-content." ],
+                [ "data: { md_skip: true }", "attribute", "—", "Opt any wrapper out of the exported Markdown." ]
+              ],
+              headers: [ "Surface", "Kind", "Default", "Description" ]
+            )
+          end
+        end
+
+        def markdown_action_section
+          DocsUI::Section("The \"Markdown\" masthead action",
+                          description: "The button at the top of this page — copy the page as Markdown, or open the raw twin with JS off.") do
+            md <<~'MD'
+              `DocsUI::MarkdownAction` renders the small "Markdown" button in the
+              masthead (a clipboard icon + label), pointing at the current page's
+              `.md` twin. `DocsUI::Page` renders it automatically when
+              `DocsKit.configuration.page_markdown_action` is true (the default) —
+              look at the top-right of this page.
+
+              With **JS off** it simply opens the raw Markdown — a working
+              fallback, never a dead end. With **JS on**, the one `docs-nav`
+              Stimulus controller upgrades the click: it fetches the same `.md`
+              URL with `Accept: text/markdown`, writes the body to the clipboard,
+              and flashes the label to "Copied!" for 1500ms. Any failure (no
+              clipboard API on an insecure context, a non-ok fetch) falls back to
+              normal navigation to the raw `.md`.
+            MD
+
+            DocsUI::Code(<<~RUBY)
+              # Rendered for you by DocsUI::Page; the href is request.path + ".md":
+              render DocsUI::MarkdownAction.new(request.path)
+            RUBY
+
+            md <<~'MD'
+              The href is built from the request path and is idempotent about the
+              query string: `/x → /x.md`, `/x?q=1 → /x.md?q=1`, and an existing
+              `/x.md` is left as-is. The affordance lives inside the page's
+              `data-md-skip` nav, so it never appears in the exported twin.
+            MD
+
+            DocsUI::Callout(:tip) do
+              plain "Hide the button site-wide with "
+              code { "c.page_markdown_action = false" }
+              plain " — the "
+              code { ".md" }
+              plain " route itself keeps serving the twin regardless; the knob only controls the UI."
+            end
+
+            render DocsUI::PropTable.new(
+              [
+                [ "DocsUI::MarkdownAction.new(path)", "String", "request.path", "The page whose .md twin the button targets." ],
+                [ "docs-nav#copyMarkdown", "action", "—", "Fetches + copies the twin; falls back to opening it." ],
+                [ "c.page_markdown_action", "Boolean", "true", "Show the masthead button (the .md route ignores this)." ]
+              ],
+              headers: [ "Surface", "Type", "Default", "Description" ]
+            )
+          end
+        end
+
+        def llms_section
+          DocsUI::Section("/llms.txt and /llms-full.txt",
+                          description: "The llmstxt.org index and full-text dump — built straight from the registry, zero authoring.") do
+            md <<~'MD'
+              docs-kit's engine ships **no routes** — it is glue-only, so a site
+              keeps full control over path, auth, and omission. The install
+              generator draws the two llms routes for you:
+            MD
+
+            DocsUI::Code(<<~RUBY, filename: "config/routes.rb")
+              get "/llms.txt"      => "docs_kit/llms#index", as: :llms
+              get "/llms-full.txt" => "docs_kit/llms#full",  as: :llms_full
+            RUBY
+
+            md <<~'MD'
+              **[/llms.txt](/llms.txt)** is the llmstxt.org index, built by
+              `DocsKit::LlmsText.index`:
+
+              - an `# {brand}` H1 (`c.brand`, default `"Docs"` — always present),
+              - a `> {tagline}` blockquote (`c.tagline`) right under it — this site
+                sets it to the shell's one-line summary; nil or empty omits the line,
+              - one `## {group}` section per nav group, a tight bullet list of each
+                authored page's absolute `.md` link, in registry order,
+              - a trailing `## MCP` block *only when the MCP endpoint is live*.
+
+              **[/llms-full.txt](/llms-full.txt)** concatenates every authored
+              page's Markdown twin — each as `# {title}` + its rendered Markdown,
+              separated by a `---` rule.
+
+              Both include **only pages with a resolvable `view_class`** — an
+              unwritten registry entry is excluded from the links and the
+              concatenation, so neither ever references a page that doesn't exist
+              yet. Links are absolutized against `request.base_url`, so agent
+              tooling fetches a portable URL.
+            MD
+
+            DocsUI::Callout(:note) do
+              plain "Both endpoints are HTTP-cached: they revalidate on the rendered body plus "
+              code { "DocsKit::VERSION" }
+              plain " as the etag salt, so any registry, config, or page change busts the cache while an unchanged site serves a "
+              code { "304 Not Modified" }
+              plain "."
+            end
+
+            render DocsUI::PropTable.new(
+              [
+                [ "c.brand", "String", '"Docs"', "The # H1 of the index (always emitted)." ],
+                [ "c.tagline", "String, nil", "nil", "The > blockquote under the H1; nil/empty omits it." ],
+                [ "c.nav_registries", "Hash", "{}", "Registries → the ## group sections and their .md links." ],
+                [ "DocsKit::LlmsText.index / .full", "class", "—", "The pure builders the LlmsController threads request.base_url into." ]
+              ],
+              headers: [ "Surface", "Type", "Default", "Description" ]
+            )
+          end
+        end
+
+        def mcp_section
+          DocsUI::Section("The read-only MCP server",
+                          description: "POST /mcp — list_pages / get_page / search_docs over JSON-RPC, gated on the optional mcp gem.") do
+            md <<~'MD'
+              docs-kit ships a built-in **read-only** MCP server so an agent can
+              connect over the protocol instead of scraping. It exposes three
+              tools over `POST /mcp` (JSON-RPC), all reading the same registry,
+              `.md` twins, and [search](/docs/search) index the docs render from:
+
+              - **`list_pages`** — every authored page as `{slug, title, group, url}`,
+              - **`get_page`** — one page's GFM twin by slug (unknown slugs return
+                the list of valid ones, so an agent self-corrects),
+              - **`search_docs`** — ranked full-text search returning
+                `{page_title, section_title, url, snippet}`.
+            MD
+
+            DocsUI::Callout(:warning) do
+              plain "The endpoint is live only when BOTH the optional "
+              code { "mcp" }
+              plain " gem is loadable AND "
+              code { "c.mcp" }
+              plain " is true (the default). Off in either case → the controller 404s and the site is byte-identical to before the feature. A fresh site has "
+              code { "c.mcp = true" }
+              plain " but no live endpoint until you add the gem and uncomment the routes."
+            end
+
+            md <<~'MD'
+              Enabling it is two steps. Add the gem:
+            MD
+
+            DocsUI::Code(<<~RUBY, filename: "Gemfile")
+              gem "mcp" # optional — powers the built-in POST /mcp server
+            RUBY
+
+            md <<~'MD'
+              …then uncomment the routes the install generator drew for you
+              (commented out, because the gem is optional). `POST` speaks
+              JSON-RPC; `GET`/`DELETE` return `405` — the server is stateless and
+              read-only, so there is no SSE session to open or terminate:
+            MD
+
+            DocsUI::Code(<<~RUBY, filename: "config/routes.rb")
+              match "/mcp" => "docs_kit/mcp#method_not_allowed", via: %i[get delete]
+              post  "/mcp" => "docs_kit/mcp#create"
+            RUBY
+
+            md <<~'MD'
+              The controller delegates the whole protocol to the official MCP SDK:
+              `DocsKit::McpServer.build` constructs the `MCP::Server` (named from
+              `c.brand`, versioned from `DocsKit::VERSION`) and registers the three
+              tools; `server.handle_json(request.body.read)` parses, dispatches,
+              and serializes the JSON-RPC response. All three tools' logic lives in
+              `DocsKit::McpTools` as pure plain-Ruby functions with zero gem and
+              zero JSON-RPC dependency — so the whole consumption story is
+              unit-testable without booting Rails or the SDK.
+
+              Once live, `/llms.txt` grows its trailing `## MCP` block advertising
+              the endpoint, so an agent reading the index discovers it can also
+              connect over the protocol.
+            MD
+
+            render DocsUI::PropTable.new(
+              [
+                [ "c.mcp", "Boolean", "true", "Toggle; the endpoint needs this AND the mcp gem present." ],
+                [ "c.mcp_enabled?", "method", "—", "!!c.mcp && the gem loadable — the gate the controller + llms.txt read." ],
+                [ "POST /mcp", "route", "—", "JSON-RPC; GET/DELETE 405 (stateless, read-only)." ],
+                [ "list_pages / get_page / search_docs", "tools", "—", "The three read-only tools, over DocsKit::McpTools." ]
+              ],
+              headers: [ "Surface", "Type", "Default", "Description" ]
+            )
+          end
+        end
+
+        def agents_section
+          DocsUI::Section("AGENTS.md + the write-docs-page skill",
+                          description: "The install generator scaffolds an authoring contract every agent can read.") do
+            md <<~'MD'
+              So an agent (or a teammate) can *author* pages the docs-kit way, the
+              install generator scaffolds two files into the consuming site:
+
+              - **`AGENTS.md`** at the repo root — the cross-tool authoring
+                contract. The generator owns a delimited block inside it (between
+                `<!-- BEGIN docs-kit -->` / `<!-- END docs-kit -->`), so a re-run
+                updates only that block and leaves the rest of your `AGENTS.md`
+                alone. A fresh site gets the whole file.
+              - **`.claude/skills/write-docs-page/SKILL.md`** — a Claude Code skill
+                that scaffolds with `rails g docs_kit:page`, writes Markdown-first
+                `#content`, and runs the verification gates. Written unless the site
+                already has one.
+
+              Both point at the same recipe: one `DocsUI::Section` per part of the
+              page (Sections own structure and the TOC — never a Markdown `##`),
+              prose via a single-quoted `md <<~'MD'` heredoc, and reference
+              material via `DocsUI::PropTable` / `DocsUI::FieldTable` /
+              `DocsUI::RequestExample`. See [Authoring pages](/docs/authoring) for
+              the same contract written for humans.
+            MD
+
+            DocsUI::Callout(:tip) do
+              plain "The skill's recipe is exactly what the "
+              code { "docs_kit:page" }
+              plain " generator produces — see "
+              a(href: "/docs/authoring") { "Authoring pages" }
+              plain " and "
+              a(href: "/docs/components") { "Components" }
+              plain " for the full kit."
+            end
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/docs/app/views/docs/pages/api.rb b/docs/app/views/docs/pages/api.rb
new file mode 100644
index 0000000..2542668
--- /dev/null
+++ b/docs/app/views/docs/pages/api.rb
@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+module Views
+  module Docs
+    module Pages
+      # How to build an API-reference page from the kit: an Endpoint line, a
+      # FieldTable / ErrorTable, one RequestExample that fans out to every client
+      # tab, and a JsonResponse — driven by three config knobs, shown live.
+      class Api < DocsUI::Page
+        title "API reference"
+        eyebrow "Authoring"
+
+        def lead = "Declare an endpoint once — method, path, fields, one request — and the kit renders the badge, the tables, and a code tab per client. Base URL, auth, and the client set are config."
+
+        def content
+          overview_section
+          endpoint_section
+          field_error_section
+          request_example_section
+          config_section
+          clients_section
+          live_section
+        end
+
+        private
+
+        def overview_section
+          DocsUI::Section("The API-reference kit",
+                          description: "Six components compose a full endpoint reference — no hand-rolled badges or per-language heredocs.") do
+            md <<~'MD'
+              An API-reference page is the same page you'd write for anything else
+              — a Phlex class of `DocsUI::Section`s (see [Authoring
+              pages](/docs/authoring)). What's different is the vocabulary you
+              reach for inside `#content`:
+
+              - `DocsUI::Endpoint` — a verb badge + monospace path, inline;
+              - `DocsUI::FieldTable` / `DocsUI::ErrorTable` — schema-driven tables;
+              - `DocsUI::RequestExample` — one request declaration → one code tab
+                per client;
+              - `DocsUI::JsonResponse` — a Ruby Hash rendered as pretty JSON.
+
+              Three config knobs — `api_base_url`, `api_auth_header`,
+              `api_clients` — feed every `RequestExample`, so a snippet is
+              authored once and points at the right host with the right auth. The
+              [Components](/docs/components) reference lists every arg; this page
+              walks the workflow.
+            MD
+          end
+        end
+
+        def endpoint_section
+          DocsUI::Section("Endpoint — the method + path line",
+                          description: "A colour-coded verb badge and a monospace path, rendered inline.") do
+            md <<~'MD'
+              `DocsUI::Endpoint.new(method, path)` renders an HTTP method badge
+              coloured per verb — `GET` success, `POST` primary, `PUT`/`PATCH`
+              warning, `DELETE` error, anything else neutral — followed by the
+              path in a `<code>`. It renders **inline** (no wrapper), on purpose:
+              drop it straight into a `Section`'s `description:`.
+            MD
+
+            DocsUI::Code(<<~RUBY)
+              DocsUI::Section("List customers",
+                description: DocsUI::Endpoint.new(:get, "/v1/customers")) do
+                # fields, request example, response…
+              end
+            RUBY
+
+            prose { p { "The badge live, for each verb:" } }
+            div(class: "flex flex-wrap gap-4 not-prose") do
+              render DocsUI::Endpoint.new(:get, "/v1/customers")
+              render DocsUI::Endpoint.new(:post, "/v1/customers")
+              render DocsUI::Endpoint.new(:patch, "/v1/customers/:id")
+              render DocsUI::Endpoint.new(:delete, "/v1/customers/:id")
+            end
+
+            DocsUI::Callout(:note) do
+              plain "The verb → badge map is a frozen Hash of "
+              strong { "literal" }
+              plain " class strings so Tailwind's Ruby scan generates each colour — never interpolate them. The path is Phlex-escaped, and an unknown verb (e.g. "
+              code { ":trace" }
+              plain ") degrades to a neutral badge rather than raising."
+            end
+          end
+        end
+
+        def field_error_section
+          DocsUI::Section("FieldTable & ErrorTable — the schemas",
+                          description: "Keyword-schema presets over DocsUI::Table for request fields and endpoint errors.") do
+            md <<~'MD'
+              `DocsUI::FieldTable` takes an Array of field Hashes and renders
+              **Name / Type / Required / Description**. `name` is auto
+              code-styled, `required:` defaults to `false` (a `✓` when true, the
+              canonical `—` when not), and the description cell follows
+              `DocsUI::Table`'s convention — a plain `String` is escaped text,
+              `[:code, "x"]` is inline code, `[:md, "…"]` is inline Markdown.
+            MD
+
+            DocsUI::Code(<<~RUBY)
+              render DocsUI::FieldTable.new([
+                { name: "email", type: "string", required: true,
+                  description: "The customer's email address." },
+                { name: "metadata", type: "object",
+                  description: [:md, "Up to 50 keys, e.g. `plan: pro`."] }
+              ])
+            RUBY
+
+            md <<~'MD'
+              `DocsUI::ErrorTable` renders **Scenario / Status / Type** — plus a
+              **Param** column, but only when at least one error names a `param:`.
+              An endpoint whose errors are all param-free renders a clean
+              three-column table; when the column IS shown, a param-free row gets
+              the em-dash. `type` and `param` are auto code-styled.
+            MD
+
+            DocsUI::Code(<<~RUBY)
+              render DocsUI::ErrorTable.new([
+                { scenario: "Missing or invalid API key", status: "401",
+                  type: "authentication_error" },
+                { scenario: "Email already taken", status: "422",
+                  type: "validation_error", param: "email" }
+              ])
+            RUBY
+
+            DocsUI::Callout(:tip) do
+              plain "The "
+              code { "—" }
+              plain " placeholder is the kit's ONE canonical \"no value\" glyph (an em-dash, never an ASCII hyphen) — both tables share it, so a page never types a stray "
+              code { "-" }
+              plain "."
+            end
+          end
+        end
+
+        def request_example_section
+          DocsUI::Section("RequestExample — one declaration, every client",
+                          description: "Declare method/path/body once; get a syntax-highlighted tab per configured client.") do
+            md <<~'MD'
+              `DocsUI::RequestExample` is the payoff. Declare the request once and
+              it renders one code tab per configured client — `curl`,
+              `javascript`, `ruby`, `python` by default — wrapped in a
+              `DocsUI::Example`, so the reader's sticky global language choice
+              persists across every endpoint on the site.
+            MD
+
+            DocsUI::Code(<<~RUBY)
+              render DocsUI::RequestExample.new(
+                method: :post,
+                path: "/v1/customers",
+                body: { email: "ada@example.com", name: "Ada Lovelace" }
+              )
+            RUBY
+
+            md <<~'MD'
+              Under the hood each tab is fed a `DocsKit::ApiRequest` — an immutable
+              value object carrying `method`/`path`/`url`/`query`/`headers`/`body`
+              with display helpers (`#http_method`, `#body?`,
+              `#pretty_body_json`, `#url_with_query`). Every shipped template
+              guards its payload lines on `#body?`, so a body-less GET emits no
+              dangling `-d` / `json=` / `request.body =` line.
+            MD
+
+            render DocsUI::PropTable.new(
+              [
+                [ "method: / path:", "Symbol/String, String", "—", "The verb and path; path is appended to c.api_base_url." ],
+                [ "body:", "Hash, String, nil", "nil", "Payload — deep-stringified into each snippet. Omit for a GET." ],
+                [ "query:", "Hash", "{}", "Query params, URL-encoded onto every snippet's URL." ],
+                [ "headers:", "Hash", "{}", "Extra headers, merged over the config auth header (explicit wins)." ],
+                [ "clients:", "Array<Symbol>, nil", "all configured", "Filter AND order the tabs, e.g. %i[curl ruby]." ]
+              ]
+            )
+
+            DocsUI::Callout(:warning) do
+              plain "A "
+              strong { "lone" }
+              plain " client renders no tabs — "
+              code { "DocsUI::Example" }
+              plain " needs at least two. When demoing one custom client, pair it (e.g. "
+              code { "clients: %i[cli curl]" }
+              plain "). An unknown token in "
+              code { "clients:" }
+              plain " is silently skipped — a typo yields fewer tabs, never a raise."
+            end
+          end
+        end
+
+        def config_section
+          DocsUI::Section("Configure the base URL & auth",
+                          description: "Two knobs point every snippet at your real host with a real auth line.") do
+            md <<~'MD'
+              `RequestExample` reads three config knobs. Set them once in the
+              initializer (see [Configuration](/docs/configuration)) and every
+              endpoint inherits them.
+
+              - `c.api_base_url` — prefixed onto every `path:`. Defaults to the
+                neutral `https://api.example.com`.
+              - `c.api_auth_header` — an example `Authorization` line merged into
+                every snippet. Defaults to `nil` → no auth line (clean snippets
+                for a no-auth API). It's split on the first colon into a
+                `{ name => value }` header, merged **under** any explicit
+                `headers:` you pass (so your explicit header wins).
+              - `c.api_clients` — override or extend the tab set (next section).
+            MD
+
+            DocsUI::Code(<<~RUBY, filename: "config/initializers/docs_kit.rb")
+              DocsKit.configure do |c|
+                c.api_base_url    = "https://api.acme.com"
+                c.api_auth_header = "Authorization: Bearer sk_live_..."
+              end
+            RUBY
+
+            render DocsUI::PropTable.new(
+              [
+                [ "c.api_base_url", "String", '"https://api.example.com"', "Host prefixed onto every RequestExample path." ],
+                [ "c.api_auth_header", "String, nil", "nil", "Example Authorization line merged into every snippet." ],
+                [ "c.api_clients", "Hash", "{}", "Overrides/extensions merged over the four defaults (writer only)." ]
+              ]
+            )
+          end
+        end
+
+        def clients_section
+          DocsUI::Section("Custom clients — SDK-flavored tabs",
+                          description: "Replace a default tab with an SDK snippet, or append your own (a cli tab).") do
+            md <<~'MD'
+              The gem ships **generic HTTP** snippets because it can't know your
+              SDK. A `DocsKit::ApiClient` describes one tab — a `label`, a Rouge
+              `lexer`, an optional `filename` (a String or a `(request) -> String`
+              proc), and a `template`: a `(DocsKit::ApiRequest) -> String`
+              callable that renders the snippet.
+
+              Set `c.api_clients` to a `{ token => ApiClient }` Hash. It merges
+              **over** the four defaults (`curl`, `javascript`, `ruby`,
+              `python`): reusing a default token **replaces** that tab with an
+              SDK-flavored one; a new token **appends** a tab. Hash merge preserves
+              order — reused tokens keep their slot, new ones append in
+              declaration order.
+            MD
+
+            DocsUI::Code(<<~'RUBY', filename: "config/initializers/docs_kit.rb")
+              DocsKit.configure do |c|
+                c.api_clients = {
+                  # Replace the generic Ruby tab with the SDK flavour:
+                  ruby: DocsKit::ApiClient.new(
+                    label: "Ruby", lexer: :ruby, filename: "acme.rb",
+                    template: ->(req) { %(Acme.#{req.http_method.downcase}("#{req.path}")) }
+                  ),
+                  # Append a brand-new CLI tab:
+                  cli: DocsKit::ApiClient.new(
+                    label: "Acme CLI", lexer: :shell, filename: "cli.sh",
+                    template: ->(req) { "acme #{req.http_method.downcase} #{req.path}" }
+                  )
+                }
+              end
+            RUBY
+
+            DocsUI::Callout(:note) do
+              plain "Read the effective map via "
+              code { "DocsKit.configuration.api_clients" }
+              plain " (which merges over the defaults), never the raw ivar. Because it merges, setting one "
+              code { "cli:" }
+              plain " client yields FIVE tabs, not one. Config can't "
+              strong { "remove" }
+              plain " a default tab — use "
+              code { "RequestExample" }
+              plain "'s "
+              code { "clients:" }
+              plain " to select a subset."
+            end
+          end
+        end
+
+        def live_section
+          DocsUI::Section("A full endpoint, live",
+                          description: DocsUI::Endpoint.new(:post, "/v1/customers")) do
+            md <<~'MD'
+              Everything above, composed — an `Endpoint` description, a
+              `FieldTable`, an `ErrorTable`, a `RequestExample` (four real client
+              tabs, on THIS site's config), and a `JsonResponse`. This is the real
+              kit rendering, not a screenshot:
+            MD
+
+            render DocsUI::FieldTable.new(
+              [
+                { name: "email", type: "string", required: true, description: "The customer's email address." },
+                { name: "name", type: "string", description: "The customer's full name." },
+                { name: "metadata", type: "object", description: [ :md, "Up to 50 key/value pairs, e.g. `plan: pro`." ] }
+              ]
+            )
+
+            render DocsUI::ErrorTable.new(
+              [
+                { scenario: "Missing or invalid API key", status: "401", type: "authentication_error" },
+                { scenario: "Email already registered", status: "422", type: "validation_error", param: "email" }
+              ]
+            )
+
+            prose { p { "Try it — one declaration renders every client tab:" } }
+            render DocsUI::RequestExample.new(
+              method: :post,
+              path: "/v1/customers",
+              body: { email: "ada@example.com", name: "Ada Lovelace", metadata: { plan: "pro" } }
+            )
+
+            prose { p { "A successful response:" } }
+            render DocsUI::JsonResponse.new(
+              {
+                id: "cus_1a2b3c",
+                object: "customer",
+                email: "ada@example.com",
+                name: "Ada Lovelace",
+                metadata: { plan: "pro" },
+                created: 1_720_000_000
+              }
+            )
+
+            prose { p { "The calls that produced the block above:" } }
+            DocsUI::Code(<<~RUBY)
+              DocsUI::Section("Create a customer",
+                description: DocsUI::Endpoint.new(:post, "/v1/customers")) do
+                render DocsUI::FieldTable.new([
+                  { name: "email", type: "string", required: true,
+                    description: "The customer's email address." }
+                ])
+                render DocsUI::ErrorTable.new([
+                  { scenario: "Email already registered", status: "422",
+                    type: "validation_error", param: "email" }
+                ])
+                render DocsUI::RequestExample.new(
+                  method: :post, path: "/v1/customers",
+                  body: { email: "ada@example.com", name: "Ada Lovelace" }
+                )
+                render DocsUI::JsonResponse.new(
+                  { id: "cus_1a2b3c", object: "customer", email: "ada@example.com" }
+                )
+              end
+            RUBY
+
+            DocsUI::Callout(:tip) do
+              plain "See the "
+              a(href: "/docs/components") { "Components" }
+              plain " reference for every arg of every kit component, and "
+              a(href: "/docs/markdown") { "Markdown authoring" }
+              plain " for the "
+              code { "md" }
+              plain " prose used throughout this page."
+            end
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/docs/app/views/docs/pages/authoring.rb b/docs/app/views/docs/pages/authoring.rb
index 0489c84..1be8beb 100644
--- a/docs/app/views/docs/pages/authoring.rb
+++ b/docs/app/views/docs/pages/authoring.rb
@@ -3,11 +3,12 @@
 module Views
   module Docs
     module Pages
-      # How to write a documentation page: a Phlex class, a registry entry, and
-      # the DocsUI building blocks, plus the automatic "On this page" TOC.
+      # How to write a documentation page: a Phlex class, a registry entry, the
+      # DocsUI building blocks (with pointers to their dedicated pages), and the
+      # automatic "On this page" TOC.
       class Authoring < DocsUI::Page
         title "Authoring pages"
-        eyebrow "Getting started"
+        eyebrow "Authoring"
 
         def lead = "One command scaffolds a page — the class and its registry line. Then write content; the shell, masthead, and TOC come free."
 
@@ -80,23 +81,15 @@ def content
               end
             RUBY
 
-            prose do
-              p do
-                code { "title" }
-                plain " names the page, "
-                code { "eyebrow" }
-                plain " groups it above the title, and "
-                code { "lead" }
-                plain " is the summary sentence under it. Everything you render lives in "
-                code { "content" }
-                plain "."
-              end
-              p do
-                plain "The shell (topbar, sidebar, theme switcher), the page masthead, and the "
-                strong { "On this page" }
-                plain " TOC are added automatically — you only write the body."
-              end
-            end
+            md <<~'MD'
+              `title` names the page, `eyebrow` groups it above the title, and
+              `lead` is the summary sentence under it. Everything you render lives
+              in `content`.
+
+              The shell (topbar, sidebar, theme switcher), the page masthead, and
+              the **On this page** TOC are added automatically — you only write the
+              body.
+            MD
           end
         end
 
@@ -136,53 +129,59 @@ class Doc
 
         def building_blocks_section
           DocsUI::Section("The building blocks",
-                          description: "The DocsUI kit you compose inside #content.") do
-            render DocsUI::PropTable.new(
+                          description: "The DocsUI kit you compose inside #content — and where each one is documented in full.") do
+            md <<~'MD'
+              Inside `#content` you reach for a small kit. The everyday four —
+              a `DocsUI::Section` wrapper, `md` for Markdown prose, `DocsUI::Code`
+              for a highlighted block, and `DocsUI::Callout` for an aside —
+              carry most pages. The rest are specialised; each has its own
+              reference page rather than being re-explained here.
+            MD
+
+            render DocsUI::Table.new(
+              [ "Block", "Use for", "Full reference" ],
               [
-                [ "DocsUI::Section(title)", "an anchored subsection with a heading (+ optional description)" ],
-                [ "md(source)", "a block of GFM Markdown, styled like Prose" ],
-                [ "prose { … }", "hand-authored prose (p/ul/code) in a reading-rhythm wrapper" ],
-                [ "DocsUI::Code(source)", "a syntax-highlighted code block" ],
-                [ "example { |ex| … }", "multi-language tabbed code" ],
-                [ "DocsUI::Callout(level)", "note / tip / warning boxes" ]
-              ],
-              headers: [ "Helper", "Use for" ]
+                [ [ :code, "DocsUI::Section(title)" ], "an anchored subsection with a heading (+ optional description:)", [ :md, "[Components](/docs/components)" ] ],
+                [ [ :code, "md(source)" ], "a block of GFM Markdown — the everyday prose helper", [ :md, "[Markdown authoring](/docs/markdown)" ] ],
+                [ [ :code, "prose { … }" ], "hand-authored prose (p/ul/code) in a reading-rhythm wrapper", [ :md, "[Components](/docs/components)" ] ],
+                [ [ :code, "DocsUI::Code(source)" ], "a Rouge-highlighted code block", [ :md, "[Code languages](/docs/languages)" ] ],
+                [ [ :code, "example { |ex| … }" ], "multi-language tabbed code", [ :md, "[Code languages](/docs/languages)" ] ],
+                [ [ :code, "DocsUI::Callout(level)" ], "note / tip / warning boxes", [ :md, "[Components](/docs/components)" ] ],
+                [ [ :code, "DocsUI::Table / PropTable" ], "reference tables — headers + rows, or the args preset", [ :md, "[Components](/docs/components)" ] ],
+                [ [ :code, "DocsUI::Endpoint / RequestExample" ], "the API-reference kit — a method+path line, client tabs, a fields table", [ :md, "[API reference](/docs/api)" ] ]
+              ]
             )
 
-            prose do
-              p do
-                plain "The primary argument is always positional — "
-                code { "Section(\"Title\")" }
-                plain ", "
-                code { "Code(source)" }
-                plain ", "
-                code { "Header(\"Title\")" }
-                plain " — with modifiers as keywords ("
-                code { "description:" }
-                plain ", "
-                code { "eyebrow:" }
-                plain ")."
-              end
-              p do
-                plain "For the wrappers that take no argument, use the lowercase page helpers "
-                code { "prose" }
-                plain " / "
-                code { "example" }
-                plain " (and "
-                code { "md" }
-                plain " for Markdown). A lowercase method takes a block without parens, so "
-                code { "prose do … end" }
-                plain " just works. The kit forms "
-                code { "DocsUI::Prose()" }
-                plain " / "
-                code { "DocsUI::Example()" }
-                plain " stay valid — they only need the empty "
-                code { "()" }
-                plain " because a bare "
-                code { "DocsUI::Prose do" }
-                plain " parses as a constant reference (a SyntaxError)."
-              end
-            end
+            md <<~'MD'
+              The primary argument is always positional —
+              `Section("Title")`, `Code(source)`, `Header("Title")` — with
+              modifiers as keywords (`description:`, `eyebrow:`).
+
+              For the wrappers that take no argument, use the lowercase page
+              helpers `prose` / `example` (and `md` for Markdown). A lowercase
+              method takes a block without parens, so `prose do … end` just works.
+              The kit forms `DocsUI::Prose()` / `DocsUI::Example()` stay valid —
+              they only need the empty `()` because a bare `DocsUI::Prose do`
+              parses as a constant reference (a SyntaxError).
+            MD
+
+            markdown_island_callout
+          end
+        end
+
+        def markdown_island_callout
+          DocsUI::Callout(:tip) do
+            plain "Prose is a "
+            strong { "Markdown island" }
+            plain ": "
+            code { "md <<~'MD'" }
+            plain " parses GFM with commonmarker and emits native Phlex nodes — tables, fenced code (routed through "
+            code { "DocsUI::Code" }
+            plain "), links, all Phlex-escaped. Use a single-quoted heredoc so "
+            code { "\#{...}" }
+            plain " stays literal author text. See "
+            a(href: "/docs/markdown") { "Markdown authoring" }
+            plain " for the full vocabulary."
           end
         end
 
diff --git a/docs/app/views/docs/pages/configuration.rb b/docs/app/views/docs/pages/configuration.rb
index 205ba2b..597e52b 100644
--- a/docs/app/views/docs/pages/configuration.rb
+++ b/docs/app/views/docs/pages/configuration.rb
@@ -3,17 +3,22 @@
 module Views
   module Docs
     module Pages
+      # The canonical knob reference: DocsKit.configure, the complete options
+      # table grouped by concern, and the two nav paths (registries vs. lambda).
       class Configuration < DocsUI::Page
         title "Configuration"
         eyebrow "Getting started"
 
-        def lead = "One initializer drives the shared chrome — brand, themes, and sidebar nav differ per site; the shell does not."
+        def lead = "One initializer drives the shared chrome. Everything that differs between two sites — brand, themes, nav, search, API examples — is config; the Shell, Sidebar, and ThemeSwitcher are identical everywhere."
 
         def content
           configure_section
-          all_options_section
-          sidebar_nav_section
-          themes_section
+          brand_themes_section
+          nav_section
+          code_section
+          search_section
+          api_section
+          ai_section
         end
 
         private
@@ -22,128 +27,305 @@ def configure_section
           DocsUI::Section("DocsKit.configure", description: "Set it once; the shared chrome reads it everywhere.") do
             prose do
               p do
-                plain "Everything that differs between sites lives here — "
-                code { "brand" }
-                plain ", "
-                code { "themes" }
-                plain ", the sidebar "
-                code { "nav" }
-                plain ". The Shell, Sidebar, and ThemeSwitcher are identical across every site that uses docs-kit; only this config changes."
+                plain "Call "
+                code { "DocsKit.configure" }
+                plain " with a block and set "
+                code { "c.<knob>" }
+                plain " on the yielded "
+                code { "DocsKit::Configuration" }
+                plain " singleton. Read any value back with "
+                code { "DocsKit.configuration" }
+                plain ". Every knob has a sensible default, so a brand-new site works with an empty block."
               end
               p do
                 plain "Configure inside "
                 code { "config.to_prepare" }
-                plain " so the block re-runs on every code reload and the "
-                code { "nav" }
-                plain " callable always sees the current Doc registry in development."
+                plain " so the block re-runs on every code reload — that keeps the derived nav pointing at the current registry in development."
               end
             end
             DocsUI::Code(<<~RUBY, filename: "config/initializers/docs_kit.rb")
               Rails.application.config.to_prepare do
                 DocsKit.configure do |c|
-                  c.brand           = "Acme Docs"
-                  c.title_suffix    = "Acme"                      # "Installation · Acme"
-                  c.themes          = %w[dark light dracula night]
-                  c.default_theme   = "dark"
-                  c.code_theme      = "Rouge::Themes::Monokai"
-                  c.version_badge   = -> { "v\#{Acme::VERSION}" }
-                  c.on_page_default = :panel                      # :panel | :toggle | :sidebar | false
+                  c.brand          = "Acme Docs"
+                  c.tagline        = "Everything the Acme API can do."
+                  c.themes         = %w[dark light dracula night]
+                  c.default_theme  = "dark"
+                  c.version_badge  = -> { "v\#{Acme::VERSION}" }
 
-                  c.nav = lambda do
-                    docs = Doc.all.group_by(&:group).transform_values do |items|
-                      items.map { |d| DocsKit::NavItem.new(href: "/docs/\#{d.slug}", label: d.title) }
-                    end
-                    { "Docs" => docs }
-                  end
+                  c.nav_registries = { "Docs" => Doc, "API" => ApiDoc }
                 end
               end
             RUBY
           end
         end
 
-        def all_options_section
-          DocsUI::Section("All options", description: "Every setting on the config object, with its default.") do
+        def brand_themes_section
+          DocsUI::Section("Brand & themes", description: "Identity, the topbar, the <title>, and the theme switcher.") do
+            prose do
+              p do
+                plain "The one required-ish knob is "
+                code { "brand" }
+                plain " — it names the topbar and sidebar header, and is the fallback for both "
+                code { "title_suffix" }
+                plain " and "
+                code { "nav_storage_key" }
+                plain ", so setting it alone gets you sensible page titles and per-site localStorage namespacing."
+              end
+              p do
+                plain "The theme list is the contract with your CSS: the values in "
+                code { "themes" }
+                plain " MUST match the daisyUI "
+                code { %(@plugin "daisyui" { themes: ... }) }
+                plain " block in your Tailwind entry. A theme offered here that the build never generated is a dead switcher entry. See the "
+                a(href: "/docs/styling") { "Styling & CSS" }
+                plain " page for wiring that up."
+              end
+            end
             render DocsUI::PropTable.new(
               [
-                [ "brand", "String", '"Docs"', "Topbar + sidebar heading." ],
-                [ "title_suffix", "String", "= brand", %(Appended to <title> ("Installation · brand").) ],
+                [ "brand", "String", '"Docs"', "Topbar + sidebar heading. Fallback for title_suffix and nav_storage_key." ],
+                [ "tagline", "String, nil", "nil", "One-line summary; rendered as the llms.txt blockquote. AI-index only — the chrome never shows it." ],
+                [ "brand_href", "String", '"/"', "Where the topbar brand link points (e.g. \"/docs\" for a subpath site)." ],
+                [ "title_suffix", "String", "= brand", %(Appended to the page <title> ("Installation · Acme"). Writer only; reader falls back to brand.) ],
                 [ "themes", "Array", "%w[dark light]", "ThemeSwitcher options; must match the daisyUI @plugin themes: block." ],
-                [ "default_theme", "String", "= themes.first", "data-theme applied on first paint." ],
-                [ "nav", "callable", "-> {}", %(Returns the sidebar nav Hash { "Heading" => { "Subgroup" => [items] } }; items respond to #href, #label, optional #icon.) ],
-                [ "version_badge", "callable", "nil", %(Returns a short badge string for the sidebar header, e.g. -> { "v1.2.3" }.) ],
+                [ "default_theme", "String", "= themes.first", "The data-theme applied on first paint. Writer only; reader falls back to themes.first." ],
+                [ "version_badge", "String or callable", "nil", "Short badge string for the sidebar header. A callable is invoked; a plain String is used as-is; nil = no badge." ],
                 [ "stylesheets", "Array", "%w[application]", "Stylesheet logical names linked in <head>, in order." ],
-                [ "code_theme", "String", '"Rouge::Themes::Monokai"', "Rouge theme class for inline highlight CSS." ],
                 [ "default_group_icon", "String", '"file-text"', "lucide icon for a nav group with no explicit icon." ],
-                [ "nav_storage_key", "String", "= brand slug", "Namespaces localStorage keys so two sites on one origin don't collide." ],
-                [ "on_page_default", ":panel | :toggle | :sidebar | false", ":panel", "Default auto-TOC placement." ],
-                [ "code_lexer_aliases", "Hash", "{}", %(Friendly-name→Rouge lexer aliases, merged over built-ins ({ curl: "console" }).) ],
-                [ "code_lexer_fallback", "String", '"plaintext"', "Lexer when a language can't be resolved." ],
-                [ "code_language_labels", "Hash", "{}", %(Human labels for Example language tabs, merged over built-ins ({ elixir: "Elixir" }).) ]
+                [ "icon_library", "String, nil", '"lucide"', "The RailsIcons library the chrome renders its own icons from. nil defers to the host default." ],
+                [ "nav_storage_key", "String", "= brand slug", "Namespaces the sidebar localStorage (collapse state) so two sites on one origin don't collide. Writer only." ],
+                [ "page_markdown_action", "Boolean", "true", "Show the \"Markdown\" masthead action (a link to the .md twin). false hides it; the .md route still works." ],
+                [ "on_page_default", ":panel | :toggle | :sidebar | false", ":panel", "Default auto-TOC placement when a page doesn't set its own on_page:." ]
               ]
             )
+            DocsUI::Callout(:note) do
+              plain "The version badge accepts a "
+              strong { "String OR a callable" }
+              plain " — "
+              code { %(c.version_badge = "v1.2") }
+              plain " and "
+              code { %(c.version_badge = -> { "v\#{Acme::VERSION}" }) }
+              plain " both render. A lambda is handy when the version lives in a constant that loads after the initializer."
+            end
           end
         end
 
-        def sidebar_nav_section
-          DocsUI::Section("The sidebar nav", description: "A callable that maps your registry into the shared sidebar shape.") do
+        def nav_section
+          DocsUI::Section("The sidebar nav", description: "Registries are the canonical path; a nav lambda is the escape hatch.") do
+            prose do
+              p do
+                plain "The common case is "
+                code { "nav_registries" }
+                plain " — an ordered "
+                code { '{ "Heading" => registry_class }' }
+                plain " map. Each registry answers "
+                code { ".nav_items" }
+                plain " (a "
+                code { "DocsKit::Registry" }
+                plain " method returning "
+                code { "{ group => [NavItem] }" }
+                plain "), and the whole sidebar derives from it with zero site nav code. A heading whose registry has no authored pages is dropped, so no empty group renders."
+              end
+            end
+            DocsUI::Code(<<~RUBY, filename: "config/initializers/docs_kit.rb")
+              c.nav_registries = { "Docs" => Doc, "API" => ApiDoc }
+            RUBY
             prose do
               p do
-                plain "Set "
-                code { "c.nav" }
-                plain " to a callable returning a two-level Hash: "
+                plain "Reach for the explicit "
+                code { "nav" }
+                plain " lambda only for bespoke nav — interleaving multiple registries, or hand-built subgroups. It must return an ordered "
                 code { '{ "Heading" => { "Subgroup" => [items] } }' }
-                plain ". Each item must respond to "
+                plain " Hash where each item responds to "
                 code { "#href" }
-                plain " and "
+                plain ", "
                 code { "#label" }
-                plain ", and may respond to "
+                plain ", and optional "
                 code { "#icon" }
-                plain " (a lucide name)."
-              end
-              p do
-                plain "Wrap your own registry rows in "
-                code { "DocsKit::NavItem" }
-                plain " so the sidebar stays registry-agnostic — it never touches your models directly."
+                plain "."
               end
             end
             DocsUI::Code(<<~RUBY)
               c.nav = lambda do
                 grouped = Doc.all.group_by(&:group).transform_values do |docs|
-                  docs.map do |doc|
-                    DocsKit::NavItem.new(href: "/docs/\#{doc.slug}", label: doc.title)
-                  end
+                  docs.map { |d| DocsKit::NavItem.new(href: "/docs/\#{d.slug}", label: d.title) }
                 end
-
                 {
                   "Getting started" => { "Basics" => grouped.fetch("basics", []) },
                   "Reference"       => { "API" => grouped.fetch("api", []) }
                 }
               end
             RUBY
+            render DocsUI::PropTable.new(
+              [
+                [ "nav_registries", "Hash", "{}", %({ "Heading" => registry_class }; each registry answers .nav_items. The canonical, zero-code nav path.) ],
+                [ "nav", "callable", "-> {}", "Explicit nav lambda; wins over nav_registries when assigned. For bespoke interleaved nav only." ]
+              ]
+            )
+            DocsUI::Callout(:warning) do
+              plain "Assigning "
+              code { "nav" }
+              plain " to "
+              strong { "any" }
+              plain " value — even "
+              code { "-> { {} }" }
+              plain " — marks it explicit and stops derivation from "
+              code { "nav_registries" }
+              plain ". If you set an empty nav lambda while relying on registries, you get an empty sidebar. Leave "
+              code { "nav" }
+              plain " unset unless you truly need the escape hatch."
+            end
           end
         end
 
-        def themes_section
-          DocsUI::Section("Themes", description: "The theme list is the contract between config and CSS.") do
+        def code_section
+          DocsUI::Section("Code highlighting", description: "The Rouge themes and the lexer/label maps DocsUI::Code and Example read.") do
             prose do
               p do
-                plain "The values in "
-                code { "c.themes" }
-                plain " must match the daisyUI "
-                code { "@plugin \"daisyui\" { themes: ... }" }
-                plain " block in your Tailwind entry. The first entry is the default unless you set "
-                code { "c.default_theme" }
-                plain " explicitly."
+                plain "Syntax highlighting is inline Rouge CSS. "
+                code { "code_theme" }
+                plain " is the base (light) theme, emitted un-scoped so it applies everywhere. Set "
+                code { "code_theme_dark" }
+                plain " and docs-kit additionally emits that theme's CSS scoped under each shipped "
+                strong { "dark" }
+                plain " theme — CSS-only, no JS, no flash. Which themes count as dark comes from "
+                code { "dark_themes" }
+                plain " (defaults to the 13 built-in daisyUI dark themes), intersected with your "
+                code { "themes" }
+                plain "."
+              end
+              p do
+                plain "The lexer and label maps are merged "
+                strong { "over" }
+                plain " the built-ins, so you only add or override. Any of Rouge's ~200 languages already works by its own name — see the "
+                a(href: "/docs/languages") { "Code languages" }
+                plain " page."
+              end
+            end
+            render DocsUI::PropTable.new(
+              [
+                [ "code_theme", "String or Class", '"Rouge::Themes::Monokai"', "The base (light) Rouge theme for inline highlight CSS. An unresolvable name degrades to the default." ],
+                [ "code_theme_dark", "String, Class, nil", "nil", "Optional second Rouge theme, scoped under each shipped dark theme. nil = single-theme behavior." ],
+                [ "dark_themes", "Array", "13 built-in dark themes", "Which theme names are treated as dark for code_theme_dark scoping. Override for custom dark themes." ],
+                [ "code_lexer_aliases", "Hash", "{}", %(Friendly-name → Rouge lexer aliases, merged over built-ins ({ dockerfile: "docker" }).) ],
+                [ "code_lexer_fallback", "String", '"plaintext"', "The lexer used when a language can't be resolved (no highlighting, never raises)." ],
+                [ "code_language_labels", "Hash", "{}", %(Human labels for Example language tabs, merged over built-ins ({ elixir: "Elixir" }).) ]
+              ]
+            )
+          end
+        end
+
+        def search_section
+          DocsUI::Section("Search", description: "The topbar search form and the ⌘K command palette.") do
+            prose do
+              p do
+                plain "Search is on by default. The Shell renders the affordance when "
+                code { "search" }
+                plain " is true "
+                strong { "and" }
+                plain " "
+                code { "search_path" }
+                plain " is non-blank (the gate is "
+                code { "#search_enabled?" }
+                plain "). Blank the path to disable the form without touching the toggle. The keyboard shortcuts that open the palette are configurable — "
+                code { "mod" }
+                plain " is the platform modifier (⌘ on mac, Ctrl elsewhere), so one entry works on every OS."
               end
               p do
                 plain "See the "
-                a(href: "/docs/styling") { "Styling" }
-                plain " page for wiring up the daisyUI plugin and the Rouge highlight CSS."
+                a(href: "/docs/search") { "Search" }
+                plain " page for how the index is built and served."
               end
             end
-            DocsUI::Callout(:warning) do
-              "A theme listed in c.themes but not enabled in the CSS @plugin themes: block won't apply — the ThemeSwitcher shows it, but daisyUI has no tokens for it. Keep the two lists in sync."
+            render DocsUI::PropTable.new(
+              [
+                [ "search", "Boolean", "true", "Whether the topbar renders the search form + palette markup." ],
+                [ "search_path", "String", '"/docs/search"', "Where the form submits (GET ?q=) and the palette fetches .json. Blank to disable." ],
+                [ "search_shortcuts", "Array", "%w[/ mod+k]", "Keyboard shortcuts that open the palette. Writer only; read the parsed form via #search_shortcuts." ]
+              ]
+            )
+          end
+        end
+
+        def api_section
+          DocsUI::Section("API examples", description: "The base URL, auth line, and client tabs DocsUI::RequestExample renders.") do
+            prose do
+              p do
+                plain "The API-docs kit turns one request declaration into a tab per client. "
+                code { "api_base_url" }
+                plain " is prefixed onto each snippet's path; "
+                code { "api_auth_header" }
+                plain " is an optional example auth line merged into every snippet. "
+                code { "api_clients" }
+                plain " overrides or extends the four shipped defaults ("
+                code { "curl" }
+                plain ", "
+                code { "javascript" }
+                plain ", "
+                code { "ruby" }
+                plain ", "
+                code { "python" }
+                plain ") — reusing a token replaces that client, a new token appends a tab."
+              end
+              p do
+                plain "The "
+                a(href: "/docs/api") { "API reference" }
+                plain " page shows the kit rendered live."
+              end
             end
+            DocsUI::Code(<<~RUBY, filename: "config/initializers/docs_kit.rb")
+              c.api_base_url   = "https://api.acme.com"
+              c.api_auth_header = "Authorization: Bearer sk_live_..."
+              c.api_clients = {
+                cli: DocsKit::ApiClient.new(
+                  label: "CLI", lexer: :shell,
+                  template: ->(req) { "acme \#{req.http_method.downcase} \#{req.path}" }
+                )
+              }
+            RUBY
+            render DocsUI::PropTable.new(
+              [
+                [ "api_base_url", "String", '"https://api.example.com"', "Prefixed onto each RequestExample path so snippets point at a real host." ],
+                [ "api_auth_header", "String, nil", "nil", "Example Authorization header line merged into every snippet. nil = no auth line." ],
+                [ "api_clients", "Hash", "4 shipped defaults", "{ token => DocsKit::ApiClient } merged over curl/javascript/ruby/python. Writer only; read the merged map via #api_clients." ]
+              ]
+            )
+          end
+        end
+
+        def ai_section
+          DocsUI::Section("AI & tooling", description: "The built-in MCP endpoint.") do
+            prose do
+              p do
+                plain "docs-kit ships an optional read-only MCP endpoint ("
+                code { "POST /mcp" }
+                plain ", JSON-RPC exposing "
+                code { "list_pages" }
+                plain " / "
+                code { "get_page" }
+                plain " / "
+                code { "search_docs" }
+                plain " over the docs registry). "
+                code { "mcp" }
+                plain " is true by default, but the endpoint only turns on when the optional "
+                code { "mcp" }
+                plain " gem is "
+                strong { "also" }
+                plain " loadable and the host draws the route — gate on "
+                code { "#mcp_enabled?" }
+                plain ", not the raw toggle."
+              end
+              p do
+                plain "See the "
+                a(href: "/docs/ai") { "AI & agents" }
+                plain " page for llms.txt, the .md twins, and the MCP server."
+              end
+            end
+            render DocsUI::PropTable.new(
+              [
+                [ "mcp", "Boolean", "true", "Whether the built-in MCP endpoint is active. Actually gated by #mcp_enabled? (toggle AND the mcp gem loadable)." ]
+              ]
+            )
           end
         end
       end
diff --git a/docs/app/views/docs/pages/installation.rb b/docs/app/views/docs/pages/installation.rb
index b909d39..137497f 100644
--- a/docs/app/views/docs/pages/installation.rb
+++ b/docs/app/views/docs/pages/installation.rb
@@ -3,15 +3,18 @@
 module Views
   module Docs
     module Pages
+      # How to install docs-kit: scaffold a new site, add it to an existing app,
+      # and re-run the generator with --sync to pull new wiring on upgrade.
       class Installation < DocsUI::Page
         title "Installation"
         eyebrow "Getting started"
 
-        def lead = "Scaffold a new docs site in one command, or add docs-kit to an existing Rails app."
+        def lead = "Scaffold a new docs site in one command, add docs-kit to an existing Rails app, or re-run the generator with --sync to upgrade."
 
         def content
           new_site_section
           existing_app_section
+          upgrade_section
           requirements_section
           verify_section
         end
@@ -46,9 +49,11 @@ def new_site_section
         end
 
         def existing_app_section
-          DocsUI::Section("Add to an existing Rails app") do
+          DocsUI::Section("Add to an existing Rails app",
+                          description: "Four steps: the gems, the generator, the icons, the CSS.") do
             existing_app_gemfile
             existing_app_generator
+            existing_app_manifest
             existing_app_icons
             existing_app_css
           end
@@ -72,13 +77,42 @@ def existing_app_generator
             rails g docs_kit:install
           SHELL
           md <<~'MD'
-            It creates the initializers (phlex, rails_icons, docs_kit), includes
-            `DocsKit::Controller`, a `Doc` registry with a sample page, the
-            Bun/Tailwind CSS build (`bin/build-css`), and registers the Stimulus
-            controller. It is idempotent — safe to re-run.
+            It is fully idempotent — safe on a fresh app AND a years-old site, so
+            re-running it is the sanctioned [upgrade path](#upgrade-an-existing-site).
+            File creations skip what already exists; the config initializer is
+            never clobbered; routes are skipped even when the site wrote them in
+            its own style.
           MD
         end
 
+        def existing_app_manifest
+          md "The generator wires the following into your app:"
+          render DocsUI::PropTable.new(
+            [
+              [ "config/initializers/docs_kit.rb", "The site config — brand, themes, nav. Skipped if present (never clobbered)." ],
+              [ "config/initializers/phlex.rb", "Phlex autoload namespaces (Views::, Components::)." ],
+              [ "config/initializers/rails_icons.rb", "The rails_icons config for the lucide chrome icons." ],
+              [ "app/models/doc.rb", "The Doc registry, seeded with a sample page." ],
+              [ "app/views/docs/pages/installation.rb", "A sample page to prove the render path." ],
+              [ "routes", "docs/:doc(.:format), the search / llms.txt / llms-full.txt routes, and a commented MCP route." ],
+              [ "bin/build-css + application.tailwind.css", "The Bun/Tailwind CSS build, carrying the theme @plugin block." ],
+              [ "controllers/index.js", "Registers the docs-nav Stimulus controller (eager-loaded)." ],
+              [ "AGENTS.md + .claude skill", "The AI-authoring contract and a write-docs-page Claude Code skill." ],
+              [ ".rubocop.yml", "docs-kit's shipped cops, merged into an existing config." ]
+            ],
+            headers: [ "What", "Why" ]
+          )
+          DocsUI::Callout(:note) do
+            plain "The generator also injects "
+            code { "include DocsKit::Controller" }
+            plain " into your "
+            code { "ApplicationController" }
+            plain " — that is what provides the "
+            code { "#render_page" }
+            plain " helper the docs controller calls."
+          end
+        end
+
         def existing_app_icons
           md "**3. Sync the icons.**"
           DocsUI::Code(<<~SHELL, lexer: :shell)
@@ -91,6 +125,61 @@ def existing_app_css
           DocsUI::Code(<<~SHELL, lexer: :shell)
             bun install && bun run build:css
           SHELL
+          md <<~'MD'
+            Then set your brand, themes, and nav in
+            `config/initializers/docs_kit.rb` — see
+            [Configuration](/docs/configuration) for every knob — and write your
+            first page (see [Authoring pages](/docs/authoring)).
+          MD
+        end
+
+        def upgrade_section
+          DocsUI::Section("Upgrade an existing site",
+                          id: "upgrade-an-existing-site",
+                          description: "rails g docs_kit:install --sync pulls new wiring without touching your content.") do
+            md <<~'MD'
+              docs-kit ships new wiring over time — new routes, a new Stimulus
+              registration, updated AGENTS.md guidance, RuboCop cops. To pull
+              those into an existing site, re-run the generator with `--sync`.
+              This is the **sanctioned upgrade path**.
+            MD
+            DocsUI::Code(<<~SHELL, lexer: :shell)
+              rails g docs_kit:install --sync
+            SHELL
+            md <<~'MD'
+              `--sync` is *additive*. It runs ONLY the idempotent wiring steps and
+              scaffolds no content:
+
+              - **Runs** the routes, the initializer hint, the importmap/Stimulus
+                registration, the AGENTS.md block, and the `.rubocop.yml` cops.
+              - **Skips** everything you own — the `Doc` registry, your pages, and
+                the `application.tailwind.css` build. Those already exist and are
+                yours to edit, so a sync never touches them.
+            MD
+            upgrade_drift
+            DocsUI::Callout(:tip) do
+              plain "After a sync: run "
+              code { "bun run build:css" }
+              plain " to pick up any new emitted classes, then "
+              code { "bundle exec rspec" }
+              plain " to confirm the site still boots and renders."
+            end
+          end
+        end
+
+        def upgrade_drift
+          md <<~'MD'
+            A sync also prints a **drift report** — manual cleanup it detects but
+            won't do for you, because it can't safely automate a delete. It warns,
+            never deletes, and never fails the run. The two items it looks for:
+          MD
+          render DocsUI::PropTable.new(
+            [
+              [ "A hand-rolled render_page", "app/controllers/application_controller.rb defines its own #render_page — DocsKit::Controller already provides it, so the copy shadows the gem's. Delete it." ],
+              [ "A dead IconHelper", "app/helpers/icon_helper.rb is dead code — docs-kit renders icons via rails_icons (DocsUI::Icon). Delete it." ]
+            ],
+            headers: [ "Drift", "What to do" ]
+          )
         end
 
         def requirements_section
diff --git a/docs/app/views/docs/pages/markdown.rb b/docs/app/views/docs/pages/markdown.rb
new file mode 100644
index 0000000..bd4d993
--- /dev/null
+++ b/docs/app/views/docs/pages/markdown.rb
@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+module Views
+  module Docs
+    module Pages
+      # The `md` island: the everyday prose path. Write GFM as a single-quoted
+      # heredoc; it renders as Prose-identical typography, delegates fences to
+      # Rouge, and flows into the page's .md twin.
+      class Markdown < DocsUI::Page
+        title "Markdown authoring"
+        eyebrow "Authoring"
+
+        def lead = "Write prose as Markdown with the md helper — GFM in, Prose-identical typography out, and every fence highlighted by Rouge."
+
+        def content
+          md_helper_section
+          heredoc_section
+          gfm_section
+          inline_section
+          escaping_section
+          twin_section
+          args_section
+        end
+
+        private
+
+        def md_helper_section
+          DocsUI::Section("The md helper",
+                          description: "The everyday authoring entry point — a block of GFM, styled like Prose.") do
+            md <<~'MD'
+              `md` is the prose path you reach for on almost every page. Hand it a
+              heredoc of GFM Markdown and it renders a `DocsUI::Markdown` island —
+              a block styled with the **exact** typography of a hand-authored
+              [Prose](/docs/components) block, so `md` prose and `prose do … end`
+              read identically.
+            MD
+
+            DocsUI::Code(<<~'RUBY')
+              md <<~'MD'
+                Write **prose** as Markdown — `inline code`, [links](/docs/overview),
+                lists, and tables all styled like Prose.
+              MD
+            RUBY
+
+            md <<~'MD'
+              This whole page is written with `md`. Under the hood the helper is
+              `render DocsUI::Markdown.new(source)` — a lowercase method so the
+              heredoc lands without the parens-with-blocks Ruby trap. It lives on
+              `DocsUI::Page` (via the `PageHelpers` mixin) alongside `prose` and
+              `example`; it is not a global, so a bare Phlex component would need
+              to include `DocsUI::PageHelpers` to get it.
+            MD
+
+            DocsUI::Callout(:tip) do
+              plain "Markdown is prose-only. Document structure — the section headings that feed the "
+              a(href: "/docs/on-this-page") { "On this page" }
+              plain " TOC — stays with "
+              code { "DocsUI::Section" }
+              plain ", not with an island heading."
+            end
+          end
+        end
+
+        def heredoc_section
+          DocsUI::Section("Always single-quote the heredoc",
+                          description: "A single-quoted heredoc passes interpolation and backslashes through as literal author text.") do
+            md <<~'MD'
+              Use a **single-quoted** heredoc — `<<~'MD'` — for every `md` block.
+              With single quotes Ruby does no interpolation, so `#{...}` and
+              backslashes reach the parser as the literal characters you typed.
+              That matters constantly in docs prose, where you *write about*
+              interpolation and escapes rather than perform them.
+            MD
+
+            DocsUI::Code(<<~'RUBY')
+              # Good — single-quoted: the reader sees the literal text.
+              md <<~'MD'
+                Write `#{user.name}` to interpolate, and `\d+` for a digit.
+              MD
+
+              # Trap — double-quoted: Ruby evaluates #{user.name} before Phlex
+              # ever sees it, and eats the backslash in \d.
+              md <<~MD
+                Write `#{user.name}` ...
+              MD
+            RUBY
+
+            md <<~'MD'
+              Even a double-quoted heredoc is still *safe* — Phlex escapes all
+              author free text, so nothing injects markup (see
+              [Escaping](#escaping-raw-html) below). But it will silently *change
+              your words*: `#{user.name}` becomes whatever that expression
+              evaluates to, and `\d` loses its backslash. Single-quoting is the
+              intended convention precisely so the prose you wrote is the prose the
+              reader gets.
+            MD
+          end
+        end
+
+        def gfm_section
+          DocsUI::Section("The GFM you can write",
+                          description: "Headings, lists, tables, fenced code, links, blockquotes — parsed by commonmarker.") do
+            md <<~'MD'
+              Islands parse **GitHub-Flavored Markdown** with commonmarker (v2 /
+              comrak). The full everyday vocabulary is here:
+
+              ## Headings, emphasis, lists
+
+              A `#` heading renders as an `<h3>`; `##` and anything deeper collapse
+              to `<h4>` — demoted so an island heading never collides with the page
+              masthead or a `DocsUI::Section` heading. Hierarchy inside an island is
+              intentionally flat.
+
+              Inline you get **strong**, *emphasis*, ~~strikethrough~~, and
+              `inline code`. Lists come tight or loose, bullet or ordered, nested:
+
+              - a bullet item,
+              - another, with a nested list:
+                1. first ordered step,
+                2. second ordered step.
+
+              ## Tables
+
+              A GFM pipe table renders as the kit's daisyUI table — a `not-prose`
+              overflow wrapper around a `table table-sm table-zebra`. The first row
+              is the header, the rest the body:
+
+              | Syntax        | Renders as        |
+              | ------------- | ----------------- |
+              | `**bold**`    | strong            |
+              | `~~gone~~`    | strikethrough     |
+              | `` `code` ``  | inline code       |
+
+              ## Fenced code → Rouge
+
+              A fenced ` ```lang ` block routes through
+              [`DocsUI::Code`](/docs/components), so it is Rouge-highlighted exactly
+              like a hand-written Code block — same wrapper, same token spans, same
+              configured [language aliases](/docs/languages):
+
+              ```ruby
+              class Doc
+                extend DocsKit::Registry
+                page "Overview", group: "Getting started"
+              end
+              ```
+
+              No fence language — or an unknown one — falls back to plaintext and
+              never raises.
+
+              ## Links, blockquotes, rules
+
+              [Links](/docs/authoring) are ordinary `[text](url)`. A `>` line is a
+              blockquote:
+
+              > Prose written as Markdown, styled with the reading rhythm.
+
+              And a line of three dashes is a thematic break — the horizontal rule
+              just below this paragraph:
+
+              ---
+
+              Everything above the rule was one `md` island.
+            MD
+
+            DocsUI::Callout(:note) do
+              plain "A soft line break (a single newline inside a paragraph) becomes a single space, not a "
+              code { "<br>" }
+              plain ". Only a hard break — two trailing spaces or a trailing backslash — becomes a "
+              code { "<br>" }
+              plain "."
+            end
+          end
+        end
+
+        def inline_section
+          DocsUI::Section("Inline markdown in a table cell",
+                          description: "Markdown.inline renders inline children with no Prose wrapper — for a [:md, …] cell.") do
+            md <<~'MD'
+              `DocsUI::Markdown.inline(source)` is the inline sibling: **no** Prose
+              wrapper div, and a single top-level paragraph is unwrapped so its
+              inline children — strong, em, code, a link — sit directly in the
+              surrounding element. It exists for the `[:md, "…"]` cell form of
+              [`DocsUI::Table` / `PropTable` / `FieldTable`](/docs/components),
+              where the `<td>` is already the container and a block paragraph would
+              be wrong.
+            MD
+
+            DocsUI::Table(
+              [ "name", "description" ],
+              [
+                [ [ :code, "events" ], [ :md, "Event types, e.g. `payment_link.paid`." ] ],
+                [ [ :code, "amount" ], [ :md, "Amount in the **smallest** currency unit." ] ]
+              ]
+            )
+
+            prose { p { "The description cells above are inline markdown — the call that produced the table:" } }
+
+            DocsUI::Code(<<~'RUBY')
+              DocsUI::Table(
+                [ "name", "description" ],
+                [
+                  [ [ :code, "events" ], [ :md, "Event types, e.g. `payment_link.paid`." ] ],
+                  [ [ :code, "amount" ], [ :md, "Amount in the **smallest** currency unit." ] ]
+                ]
+              )
+            RUBY
+
+            md <<~'MD'
+              Adjacent top-level blocks get a joining space when unwrapped, so two
+              paragraphs never fuse (`"one"` + `"two"` → `"one two"`, not
+              `"onetwo"`). You rarely call `.inline` directly — the `[:md, …]` cell
+              form invokes it for you.
+            MD
+          end
+        end
+
+        def escaping_section
+          DocsUI::Section("Escaping & raw HTML",
+                          id: "escaping-raw-html",
+                          description: "Author free text is Phlex-escaped; raw HTML tags are dropped entirely.") do
+            md <<~'MD'
+              Because the island *walks the commonmarker AST and emits native Phlex
+              nodes* — it never `raw`s commonmarker's HTML string — all author free
+              text is Phlex-escaped. There is no `html_safe` on prose (Critical Rule
+              7 holds), and `<`, `>`, `&` inside inline `` `code` `` are safe.
+
+              Raw HTML is dropped: `html_block` and `html_inline` AST nodes are
+              skipped entirely, so author Markdown can never inject a live
+              `<script>` or `<div onclick>` tag. There is no config to re-enable it.
+            MD
+
+            DocsUI::Callout(:warning) do
+              plain "Only the tags are dropped, not the text between them. The body of "
+              code { "<script>alert(1)</script>" }
+              plain " survives as a separate commonmarker text node — inert, Phlex-escaped prose that reads as the literal words "
+              code { "alert(1)" }
+              plain ". Never executable, but not erased either."
+            end
+
+            md <<~'MD'
+              Input is also normalized at the boundary: the initializer does
+              `source.to_s.encode(Encoding::UTF_8)`, so a `nil` source renders an
+              empty wrapper (never raises) and a US-ASCII heredoc parses fine.
+            MD
+          end
+        end
+
+        def twin_section
+          DocsUI::Section("Markdown flows into the .md twin",
+                          description: "Every page has a raw-Markdown twin; the masthead links it.") do
+            md <<~'MD'
+              Every docs page has a `.md` twin — the same page served as raw
+              Markdown at its path plus `.md`. The **Markdown** button in this
+              page's masthead points at it. With JavaScript off, the link simply
+              opens the raw Markdown (a working no-JS fallback); with JS on, the one
+              [`docs-nav`](/docs/ai) controller intercepts the click, fetches the
+              `.md`, copies it to your clipboard, and prevents the navigation.
+            MD
+
+            DocsUI::Code(<<~'RUBY')
+              # DocsUI::Page renders this automatically when
+              # DocsKit.configuration.page_markdown_action is true (the default).
+              render DocsUI::MarkdownAction.new(request.path)
+            RUBY
+
+            md <<~'MD'
+              The affordance is a new target + action on the single `docs-nav`
+              controller — the one-controller rule holds. The `.md` twin *content*
+              itself is produced by `DocsKit::Controller#render_page` →
+              `DocsKit::MarkdownExport`, not by this button. Disable the button
+              site-wide with `c.page_markdown_action = false`.
+            MD
+
+            DocsUI::Callout(:note) do
+              plain "The twin href is idempotent and query-preserving: "
+              code { "/docs/markdown" }
+              plain " → "
+              code { "/docs/markdown.md" }
+              plain ", "
+              code { "/x?a=1" }
+              plain " → "
+              code { "/x.md?a=1" }
+              plain ", and a path already ending in "
+              code { ".md" }
+              plain " is left untouched."
+            end
+          end
+        end
+
+        def args_section
+          DocsUI::Section("DocsUI::Markdown args",
+                          description: "The component behind the md helper.") do
+            render DocsUI::PropTable.new(
+              [
+                [ "source", "String, nil", "—", "The GFM to render. nil/non-UTF-8 is normalized (never raises)." ],
+                [ "inline:", "Boolean", "false", "No Prose wrapper; unwrap a lone top-level paragraph (for a [:md, …] cell)." ],
+                [ "md(source)", "page helper", "—", "render DocsUI::Markdown.new(source) — the everyday path." ],
+                [ ".inline(source)", "class method", "—", "== new(source, inline: true); used by [:md, …] table cells." ]
+              ],
+              headers: [ "Arg", "Type", "Default", "Description" ]
+            )
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/docs/app/views/docs/pages/overview.rb b/docs/app/views/docs/pages/overview.rb
index 589613a..4a7be69 100644
--- a/docs/app/views/docs/pages/overview.rb
+++ b/docs/app/views/docs/pages/overview.rb
@@ -3,7 +3,8 @@
 module Views
   module Docs
     module Pages
-      # The introduction page: what docs-kit is and the mental model behind it.
+      # The introduction page: what docs-kit is, the mental model behind it, and
+      # a scannable tour of the whole surface — each feature linking to its page.
       class Overview < DocsUI::Page
         title "Overview"
         eyebrow "Getting started"
@@ -21,51 +22,34 @@ def content
 
         def what_is_section
           DocsUI::Section("What is docs-kit", description: "A gem, not a template.") do
-            prose do
-              p do
-                strong { "docs-kit" }
-                plain " is a Ruby gem that gives you the shared chrome for a Rails "
-                plain "documentation site: the topbar, the responsive sidebar, the theme "
-                plain "switcher, the content column, an automatic "
-                plain %("On this page" TOC, and syntax-highlighted code blocks.)
-              end
-              p do
-                plain "It's built on "
-                code { "phlex-rails" }
-                plain " and "
-                code { "daisyUI" }
-                plain ". You write page bodies as Phlex components — docs-kit renders everything around them."
-              end
-            end
+            md <<~'MD'
+              **docs-kit** is a Ruby gem that gives you the shared chrome for a
+              Rails documentation site: the topbar, the responsive sidebar, the
+              theme switcher, the content column, an automatic "On this page" TOC,
+              and syntax-highlighted code blocks.
+
+              It's built on [`phlex-rails`](https://www.phlex.fun) and
+              [`daisyUI`](https://daisyui.com). You write page bodies as Phlex
+              components — docs-kit renders everything around them.
+            MD
           end
         end
 
         def mental_model_section
           DocsUI::Section("The mental model", description: "Configure the chrome; don't re-author it.") do
-            prose do
-              p do
-                plain "The chrome — "
-                code { "Shell" }
-                plain ", "
-                code { "Sidebar" }
-                plain ", "
-                code { "Page" }
-                plain " — is byte-identical across every site that uses docs-kit. The only thing "
-                plain "that differs is "
-                code { "DocsKit.configure" }
-                plain "."
-              end
-              p do
-                plain "That's the whole point: two sites built with docs-kit look and behave "
-                plain "consistently for free, because they share the same components. You change "
-                plain "the brand, the themes, and the nav — never the layout code."
-              end
-            end
+            md <<~'MD'
+              The chrome — `Shell`, `Sidebar`, `Page` — is byte-identical across
+              every site that uses docs-kit. The only thing that differs is
+              `DocsKit.configure`. Two sites look and behave consistently for free,
+              because they share the same components. You change the brand, the
+              themes, and the nav — never the layout code.
+            MD
 
             DocsUI::Code(<<~RUBY, filename: "config/initializers/docs_kit.rb")
               DocsKit.configure do |c|
-                c.brand  = "My Project"     # only this differs per site
-                c.themes = %w[dark light]   # the chrome itself is identical
+                c.brand          = "My Project"          # only this differs per site
+                c.themes         = %w[dark light]        # the chrome itself is identical
+                c.nav_registries = { "Docs" => Doc }     # sidebar derives from the registry
               end
             RUBY
 
@@ -77,60 +61,75 @@ def mental_model_section
         end
 
         def what_you_get_section
-          DocsUI::Section("What you get", description: "Everything below ships in the box.") do
-            prose do
-              ul do
-                li do
-                  strong { "Shared shell + responsive sidebar" }
-                  plain " — the same layout and navigation on every screen size."
-                end
-                li do
-                  strong { "A theme switcher" }
-                  plain " with sticky themes remembered in "
-                  code { "localStorage" }
-                  plain "."
-                end
-                li do
-                  strong { "Syntax highlighting for ~200 languages" }
-                  plain " via Rouge — no allowlist."
-                end
-                li do
-                  strong { "Multi-language code examples" }
-                  plain " with a sticky, global language choice."
-                end
-                li do
-                  plain "An automatic "
-                  strong { %("On this page" TOC) }
-                  plain " with three placement options."
-                end
-                li do
-                  strong { "A one-command generator" }
-                  plain " — "
-                  code { "docs-kit new" }
-                  plain " scaffolds a site."
-                end
-                li do
-                  strong { "A single reusable deploy workflow" }
-                  plain " — Kamal + GHCR."
-                end
-              end
-            end
+          DocsUI::Section("What you get", description: "The whole surface, in the box — each row links to its page.") do
+            md <<~'MD'
+              #### The chrome
+
+              - **Shared shell + responsive sidebar + theme switcher** — the same
+                topbar, nav, and layout on every screen size, remembered in
+                `localStorage`. See [Components](/docs/components).
+              - **A theme switcher** whose list is your `c.themes` — it must match
+                the daisyUI `@plugin` block in your Tailwind entry. See
+                [Styling & CSS](/docs/styling).
+              - **Syntax highlighting for ~200 languages** via Rouge, with a
+                light + dark theme pair emitted as inline CSS — no allowlist, no
+                flash. See [Code languages](/docs/languages).
+
+              #### Authoring
+
+              - **Markdown islands** — drop `md <<~'MD' … MD` anywhere in a page
+                and get GFM (tables, lists, inline code, links) styled with the
+                reading rhythm. See [Markdown authoring](/docs/markdown).
+              - **The component kit** — `Section`, `Code`, `Example`, `Callout`,
+                `Table`/`PropTable`, plus the **API-docs kit**
+                (`Endpoint`, `RequestExample`, `JsonResponse`) that turns one
+                request declaration into every client tab. See
+                [Components](/docs/components) and the [API reference](/docs/api).
+              - **A one-command page generator** — `rails g docs_kit:page "Title"`
+                writes the Phlex class AND its one-line Registry v2 entry, both
+                derived from the title. See [Authoring pages](/docs/authoring).
+
+              #### For machines
+
+              - **An automatic `.md` twin** — every page answers at `/docs/x.md`
+                with its Markdown source, and the masthead "Markdown" action
+                becomes copy-to-clipboard.
+              - **`/llms.txt` + `/llms-full.txt`** — an [llmstxt.org](https://llmstxt.org)
+                index and a full concatenation, served from the registry with zero
+                authoring.
+              - **Server-rendered search + a ⌘K palette** — a working
+                `GET /docs/search` form the `docs-nav` controller enhances into a
+                fuzzy palette. See [Search](/docs/search).
+              - **An optional read-only MCP server** — `POST /mcp` exposing
+                `list_pages` / `get_page` / `search_docs` over the registry when
+                the `mcp` gem is present. See [AI & agents](/docs/ai).
+              - **AGENTS.md scaffolding** — the install generator writes an
+                `AGENTS.md` authoring contract plus a Claude Code
+                `write-docs-page` skill, so agents author pages the right way.
+
+              #### Toolchain
+
+              - **Shipped RuboCop cops** — `DocsKit/RenderComponentPreferred`
+                (steer to the kit helper form) and
+                `DocsKit/EscapedInterpolationInHeredoc` (kill the `\#{…}` escape
+                tax in Markdown heredocs). See [Configuration](/docs/configuration).
+              - **An idempotent install** — `docs_kit:install` is safe to re-run,
+                and `--sync` runs only the additive wiring to upgrade an existing
+                site without touching your pages. See [Installation](/docs/installation).
+              - **`docs-kit new` + a single reusable deploy workflow** — scaffold a
+                whole site, then ship it with Kamal + GHCR. See [Deploy](/docs/deploy).
+            MD
           end
         end
 
         def next_steps_section
           DocsUI::Section("Next steps") do
-            prose do
-              p do
-                plain "Start with "
-                strong { "Installation" }
-                plain " to add the gem and render your first page. Then read "
-                strong { "Configuration" }
-                plain " to set your brand, themes, and nav, and "
-                strong { "Authoring" }
-                plain " to learn the DocsUI kit — the building blocks for every page body."
-              end
-            end
+            md <<~'MD'
+              Start with [Installation](/docs/installation) to add the gem and
+              render your first page. Then read [Configuration](/docs/configuration)
+              to set your brand, themes, and nav, and [Authoring pages](/docs/authoring)
+              to learn the DocsUI kit — the building blocks for every page body.
+            MD
           end
         end
       end
diff --git a/docs/app/views/docs/pages/search.rb b/docs/app/views/docs/pages/search.rb
new file mode 100644
index 0000000..c1b02ad
--- /dev/null
+++ b/docs/app/views/docs/pages/search.rb
@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module Views
+  module Docs
+    module Pages
+      # Server-rendered docs search + the ⌘K palette: a JS-off GET form, an
+      # in-memory index built from the pages' Markdown twins, and the .json
+      # endpoint the palette fetches. Renders the real SearchBox/SearchResults.
+      class Search < DocsUI::Page
+        title "Search"
+        eyebrow "AI & tooling"
+
+        def lead = "One index, two front-ends: a plain GET form that works with JavaScript off, and a ⌘K palette that enhances it. Both read the same twins that feed /llms-full.txt, so search can never drift from the pages."
+
+        def content
+          overview_section
+          progressive_section
+          index_section
+          endpoint_section
+          searchbox_section
+          config_section
+        end
+
+        private
+
+        def overview_section
+          DocsUI::Section("How search fits together",
+                          description: "Zero authoring, no external service, no build step — the pages ARE the index.") do
+            md <<~'MD'
+              docs-kit search has three moving parts and no second registry:
+
+              - **`DocsKit::SearchIndex`** — an in-memory index built per request
+                from each page's Markdown twin (the same twins
+                [/llms-full.txt](/docs/ai) serves), split on its `## ` headings
+                into searchable sections.
+              - **`DocsKit::SearchController`** — one gem controller answering
+                **both** formats off that index: HTML for the JS-off results page,
+                JSON for the palette.
+              - **`DocsUI::SearchBox`** — the topbar form the `docs-nav` controller
+                enhances into a keyboard palette.
+
+              Everything is driven by `DocsKit.configuration` — `search`,
+              `search_path`, and `search_shortcuts` — so a site tunes it without
+              touching a component.
+            MD
+
+            DocsUI::Callout(:note) do
+              plain "The route is "
+              strong { "not" }
+              plain " added by the engine — the install generator draws "
+              code { "get \"/docs/search\" => \"docs_kit/search#index\"" }
+              plain " so a site can remount search elsewhere via "
+              code { "config.search_path" }
+              plain "."
+            end
+          end
+        end
+
+        def progressive_section
+          DocsUI::Section("Works with JavaScript off",
+                          description: "The GET form is the whole search UX; the palette is a pure enhancement over the same controller.") do
+            md <<~'MD'
+              The topbar affordance is a real `GET` form pointed at
+              `config.search_path`. Press **Enter** and the browser lands on the
+              server-rendered results page — no JavaScript required. `docs-nav`
+              enhances that same form into a debounced palette; if JS never loads
+              (or dies mid-typing) the form still submits normally.
+
+              The results page IS `DocsUI::SearchResults` wrapped in
+              `DocsUI::Shell` — a full working page, not a JSON blob. It echoes the
+              query, groups hits by page (best-scoring page first), links each hit
+              to its section anchor, and shows a pre-highlighted snippet.
+            MD
+
+            prose { p { "The JS-off results body, rendered live for a query that hits this very page:" } }
+            render DocsUI::SearchResults.new(
+              query: "search index",
+              hits: DocsKit::SearchIndex.new(
+                [
+                  [
+                    "Search", "/docs/search",
+                    "The docs search index is built from each page's Markdown twin.\n\n" \
+                    "## The search index\nDocsKit::SearchIndex splits a twin on its headings into sections."
+                  ]
+                ]
+              ).search("search index")
+            )
+
+            prose { p { "The call that produced the block above (the controller does this for you):" } }
+            DocsUI::Code(<<~RUBY)
+              render DocsUI::SearchResults.new(
+                query: params[:q],
+                hits:  index.search(params[:q])
+              )
+            RUBY
+
+            DocsUI::Callout(:tip) do
+              plain "A blank query prompts the reader; a query with "
+              strong { "no" }
+              plain " hits renders guidance (“Try fewer or more general words”) instead of an empty list. A page-intro hit (no section) is labeled "
+              code { "Overview" }
+              plain "."
+            end
+          end
+        end
+
+        def index_section
+          DocsUI::Section("The in-memory index",
+                          description: "DocsKit::SearchIndex over the registry — pure Ruby, unit-testable with no Rails.") do
+            md <<~'MD'
+              The controller renders each registry page through
+              `DocsKit::MarkdownExport` and hands `SearchIndex` a list of triples —
+              `[page_title, page_href, markdown]`. The index splits every twin on
+              its `## ` (level-2 ATX) headings into one entry per section, plus a
+              **page-intro** entry for the text before the first heading.
+            MD
+
+            DocsUI::Code(<<~RUBY)
+              index = DocsKit::SearchIndex.new(
+                [["Overview", "/docs/overview", overview_markdown_twin],
+                 ["Search",   "/docs/search",   search_markdown_twin]]
+              )
+              index.search("theme switcher") # => [DocsKit::SearchHit, ...]
+            RUBY
+
+            md <<~'MD'
+              **Scoring** is weighted AND-token ranking: every whitespace-split
+              query token must match somewhere in an entry, and each token scores
+              the heaviest field it hit — title beats heading beats body
+              (`100 > 10 > 1`). The entry's score is the per-token sum, so a section
+              matching more tokens in heavier fields floats up. Matching is plain
+              case-insensitive `String#include?` (so `gen` matches `Generators`) —
+              no fuzzy matching, no stemming, by design. Results cap at 20.
+
+              The page **title** is a searchable field only on the page-intro entry
+              — never on every section — so a pure title match surfaces once rather
+              than flooding the results with every section of that page.
+            MD
+
+            render DocsUI::PropTable.new(
+              [
+                [ "SearchIndex.new(triples)", "Array", "[]", "[[page_title, page_href, markdown], …] — the twins." ],
+                [ "#search(query)", "String", "—", "Array<SearchHit>, best first, capped at 20. Blank → []." ],
+                [ "#entries", "—", "—", "The indexed Entry list (one per section + page intro)." ],
+                [ "TITLE/HEADING/BODY_WEIGHT", "Integer", "100 / 10 / 1", "Field weights a token scores against." ],
+                [ "MAX_RESULTS", "Integer", "20", "Hard cap on returned hits." ]
+              ],
+              headers: [ "API", "Type", "Default", "Description" ]
+            )
+
+            md <<~'MD'
+              Each hit is a `DocsKit::SearchHit` — an immutable value object with
+              `page_title`, `section_title` (nil for a page-intro hit), `href`
+              (the `page_href#anchor`), a pre-highlighted HTML-safe `snippet`, and
+              a `score`. Its `#label` reads `"Page → Section"` (or just the page
+              title), and `#as_json` is the `{ label, href, snippet }` shape the
+              palette fetches (score is dropped — rank only matters server-side).
+
+              The snippet is a `~80`-char window centered on the first match with
+              the query terms wrapped in `<mark>`; everything else is HTML-escaped
+              **first**, so a source angle bracket can never inject markup. That's
+              why `SearchResults` can render it via `raw(safe(…))` — it's trusted
+              gem-produced markup, the same idiom `DocsUI::Code` uses.
+            MD
+
+            DocsUI::Callout(:warning) do
+              plain "The section anchor is recomputed as "
+              code { "page_href#slug" }
+              plain " using the SAME "
+              code { "slugify" }
+              plain " rule "
+              code { "DocsUI::Section" }
+              plain " stamps on its "
+              code { "<section id>" }
+              plain ". Section splitting is code-fence aware, but a "
+              code { "## " }
+              plain " with no space ("
+              code { "##Nospace" }
+              plain ") is not treated as a heading."
+            end
+          end
+        end
+
+        def endpoint_section
+          DocsUI::Section("One endpoint, HTML + JSON",
+                          description: "DocsKit::SearchController answers both formats off the same lazily-built index.") do
+            md <<~'MD'
+              The host draws the route (the engine adds none); the controller reads
+              `params[:q]` and responds by format:
+
+              - **HTML** — the JS-off path: `DocsUI::SearchResults` inside
+                `DocsUI::Shell`, rendered `layout: false` (the Shell IS the whole
+                document).
+              - **JSON** — the enhancement path: `{ query, results: [...] }`, where
+                each result is a `SearchHit#as_json`. The palette fetches this
+                debounced as you type.
+
+              The palette hits the `.json` variant of the same path:
+            MD
+
+            DocsUI::Code(<<~JSON, filename: "GET /docs/search.json?q=theme", lexer: :json)
+              {
+                "query": "theme",
+                "results": [
+                  {
+                    "label": "Components → ThemeSwitcher",
+                    "href": "/docs/components#themeswitcher",
+                    "snippet": "…the <mark>theme</mark> dropdown in the topbar…"
+                  }
+                ]
+              }
+            JSON
+
+            md <<~'MD'
+              The index is rebuilt on **every** request (no caching) — fine for a
+              tens-of-pages site, but `O(pages × markdown render)` per query.
+              Because it renders through the controller's own view context, url
+              helpers and CSRF resolve, and hrefs are absolutized against
+              `request.base_url` — exactly as the [/llms-full.txt](/docs/ai)
+              endpoint renders each twin.
+            MD
+
+            DocsUI::Callout(:note) do
+              plain "The controller reads config via "
+              code { "#docs_config" }
+              plain ", never "
+              code { "#config" }
+              plain " — shadowing "
+              code { "ActionController::Base#config" }
+              plain " would break "
+              code { "csrf_meta_tags" }
+              plain " when the Shell renders."
+            end
+          end
+        end
+
+        def searchbox_section
+          DocsUI::Section("The topbar SearchBox & ⌘K palette",
+                          description: "The GET form docs-nav enhances — one <kbd> hint per configured shortcut, bound from JSON.") do
+            md <<~'MD'
+              `DocsUI::SearchBox` is the affordance in the topbar — `DocsUI::Shell`
+              renders it whenever `DocsKit.configuration.search_enabled?`. It's a
+              plain `GET` form to `config.search_path` with a `q` input, plus the
+              hooks `docs-nav` needs to turn it into a palette:
+
+              - one `<kbd>` badge per `config.search_shortcuts`, labeled by the
+                parsed `DocsKit::Shortcut#label` (`/`, `Ctrl K`, …),
+              - the parsed shortcut list emitted as JSON on the scope
+                (`data-docs-nav-shortcuts-value`), so the visible badges and the
+                key bindings share ONE source and can't drift,
+              - an empty, hidden results dropdown `docs-nav` fills as you type.
+            MD
+
+            prose { p { "The real component (it's the same one in this site's topbar):" } }
+            render DocsUI::SearchBox.new
+
+            prose { p { "Render it yourself with:" } }
+            DocsUI::Code(<<~RUBY)
+              render DocsUI::SearchBox.new
+              # Shell renders it automatically when config.search_enabled?
+            RUBY
+
+            md <<~'MD'
+              Shortcuts are platform-agnostic strings. `mod` is the **platform
+              modifier** — ⌘ on mac, Ctrl elsewhere — kept abstract server-side and
+              resolved in the browser by `docs-nav`, which swaps only the badge
+              label (never the binding). Modifier aliases: `mod`,
+              `ctrl`/`control`, `shift`, `alt`/`option`, `cmd`/`command`/`meta`.
+            MD
+
+            render DocsUI::PropTable.new(
+              [
+                [ "mod+k", "Ctrl K", "Platform command chord — ⌘K on mac, Ctrl K elsewhere." ],
+                [ "/", "/", "A bare key — shown exactly as authored." ],
+                [ "s", "s", "A bare single char — not uppercased." ],
+                [ "ctrl+shift+f", "Ctrl Shift F", "An explicit physical chord (no platform abstraction)." ]
+              ],
+              headers: [ "Shortcut string", "<kbd> label", "Meaning" ]
+            )
+
+            DocsUI::Callout(:tip) do
+              plain "A modifier-only or empty string ("
+              code { "mod+" }
+              plain ", "
+              code { "\"\"" }
+              plain ", "
+              code { "nil" }
+              plain ") is unparseable — "
+              code { "Shortcut.parse_list" }
+              plain " silently drops it. With "
+              code { "search_shortcuts" }
+              plain " empty the form still works; it just renders no "
+              code { "<kbd>" }
+              plain " badges."
+            end
+          end
+        end
+
+        def config_section
+          DocsUI::Section("Configuration",
+                          description: "Three knobs — the affordance, where it submits, and the shortcuts.") do
+            DocsUI::Code(<<~RUBY, filename: "config/initializers/docs_kit.rb")
+              DocsKit.configure do |c|
+                c.search           = true            # toggle the affordance (default true)
+                c.search_path      = "/docs/search"  # where the form GETs; palette fetches .json here
+                c.search_shortcuts = %w[/ mod+k]     # chord strings (default ["/", "mod+k"])
+              end
+            RUBY
+
+            render DocsUI::PropTable.new(
+              [
+                [ "c.search", "Boolean", "true", "Toggles the topbar affordance + palette markup site-wide." ],
+                [ "c.search_path", "String", '"/docs/search"', "Where the form GETs and the base the palette fetches .json from." ],
+                [ "c.search_shortcuts", "Array<String>", '["/", "mod+k"]', "Chord strings that open the palette." ],
+                [ "config.search_enabled?", "Boolean", "—", "search == true AND a non-blank search_path." ],
+                [ "config.search_shortcuts", "Array<Shortcut>", "—", "The PARSED list (reader maps to Shortcut, drops unparseable)." ]
+              ],
+              headers: [ "Knob / reader", "Type", "Default", "Description" ]
+            )
+
+            md <<~'MD'
+              `search_shortcuts` is asymmetric by design: you set raw **strings**,
+              but `config.search_shortcuts` reads them back as parsed
+              `DocsKit::Shortcut` objects (dropping anything unparseable) — read the
+              parsed reader, never `@search_shortcuts`.
+
+              Blanking `search_path` disables the affordance even with
+              `search == true`: `search_enabled?` is false because there'd be
+              nothing to submit to. That lets a site kill search without touching
+              `c.search`.
+            MD
+
+            DocsUI::Callout(:note) do
+              plain "See "
+              a(href: "/docs/configuration") { "Configuration" }
+              plain " for the full config surface, "
+              a(href: "/docs/ai") { "AI & agents" }
+              plain " for the twins search reads, and "
+              a(href: "/docs/components") { "Components" }
+              plain " for SearchBox / SearchResults alongside the rest of the kit."
+            end
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/docs/app/views/docs/pages/styling.rb b/docs/app/views/docs/pages/styling.rb
index 3d9f532..ff4e204 100644
--- a/docs/app/views/docs/pages/styling.rb
+++ b/docs/app/views/docs/pages/styling.rb
@@ -3,126 +3,231 @@
 module Views
   module Docs
     module Pages
+      # How each site builds its own Tailwind + daisyUI stylesheet, keeps the
+      # theme list in sync with the CSS, and drives the light/dark code-highlight
+      # theme — all config, no per-site CSS surgery.
       class Styling < DocsUI::Page
         title "Styling & CSS"
         eyebrow "Getting started"
 
-        def lead = "Each site builds its own Tailwind + daisyUI stylesheet so the chrome is themed to match."
+        def lead = "Each site builds its own Tailwind + daisyUI stylesheet so the chrome is themed to match — and code blocks restyle light↔dark with the switcher, CSS-only."
 
         def content
-          DocsUI::Section("The canonical build", description: "docs-kit ships no compiled CSS — you build it.") do
-            prose do
-              p do
-                plain "docs-kit ships "
-                strong { "no compiled CSS" }
-                plain ". Each site builds its own with the Tailwind CLI (run via Bun), so the "
-                code { "@source" }
-                plain " globs can see "
-                strong { "both" }
-                plain " your app "
-                strong { "and" }
-                plain " the gem's Phlex components. Without the gem in scope, every class the shared chrome uses would be tree-shaken away."
-              end
-              p do
-                plain "The bundled "
-                code { "bin/build-css" }
-                plain " resolves the docs-kit gem path and adds it as an extra "
-                code { "@source" }
-                plain ", so you never hand-write the gem's location."
-              end
-            end
+          canonical_build_section
+          entry_point_section
+          adding_a_theme_section
+          code_theme_section
+          custom_styles_section
+        end
+
+        private
+
+        def canonical_build_section
+          DocsUI::Section("The canonical build",
+                          description: "docs-kit ships no compiled CSS — you build it.") do
+            md <<~'MD'
+              docs-kit ships **no compiled CSS**. Each site builds its own with
+              the Tailwind CLI (run via Bun), so the `@source` globs can see
+              **both** your app **and** the gem's Phlex components. Without the
+              gem in scope, every class the shared chrome uses would be
+              tree-shaken away.
+
+              The bundled `bin/build-css` resolves the docs-kit (and daisyUI) gem
+              paths and adds them as extra `@source` entries, so you never
+              hand-write a gem's install location.
+            MD
+
             DocsUI::Code(<<~SHELL, lexer: :shell)
               bun run build:css     # one-shot, for deploys
               bun run watch:css     # rebuild on change, for development
             SHELL
           end
+        end
+
+        def entry_point_section
+          DocsUI::Section("application.tailwind.css",
+                          description: "Your Tailwind entry point wires up daisyUI, the themes, and the sources.") do
+            md <<~'MD'
+              The `themes:` list here **must match** `c.themes` in your
+              initializer — the CSS build ships exactly those themes and the
+              `ThemeSwitcher` offers exactly those names. A theme in one list but
+              not the other is either a dead switcher entry or an unreachable
+              build. This is the single most important invariant on this page.
+            MD
 
-          DocsUI::Section("application.tailwind.css", description: "Your Tailwind entry point wires up daisyUI and the sources.") do
-            prose do
-              p do
-                plain "The "
-                code { "themes:" }
-                plain " list here "
-                strong { "must match" }
-                plain " "
-                code { "c.themes" }
-                plain " in your initializer — the CSS build ships those themes and the ThemeSwitcher offers them."
-              end
-            end
             DocsUI::Code(<<~CSS, filename: "app/assets/stylesheets/application.tailwind.css", lexer: :css)
               @import "tailwindcss";
 
+              /* daisyUI — the theme list MUST match DocsKit.configuration.themes. */
               @plugin "daisyui" {
-                themes: dark --default, light, synthwave;
+                themes: dark --default, light --prefersdark, synthwave, retro,
+                  cyberpunk, dracula, night, nord, sunset;
               }
 
-              /* Your app's templates + components */
-              @source "../../../app/views/**/*.rb";
+              /* Your app's views + components + the gem's Phlex chrome.
+                 bin/build-css resolves the gem paths, so you never hard-code them. */
+              @source "../../../app/views/**/*.{rb,erb,haml,html,slim}";
               @source "../../../app/components/**/*.rb";
-
-              /* The docs-kit gem's Phlex chrome (bin/build-css injects this path) */
-              @source "../../../../<docs-kit gem>/lib/**/*.rb";
+              @import "./tailwind.sources.css";  /* gem @source lines, generated */
             CSS
-          end
 
-          DocsUI::Section("Adding a theme") do
-            prose do
-              p { "Themes come from daisyUI. To add one:" }
-              ol do
-                li do
-                  plain "Add it to the "
-                  code { "@plugin \"daisyui\" { themes: ... }" }
-                  plain " block in "
-                  code { "application.tailwind.css" }
-                  plain "."
-                end
-                li do
-                  plain "Add the same name to "
-                  code { "c.themes" }
-                  plain " in "
-                  code { "config/initializers/docs_kit.rb" }
-                  plain "."
-                end
-                li do
-                  plain "Rebuild the CSS ("
-                  code { "bun run build:css" }
-                  plain ")."
-                end
-              end
-            end
+            md <<~'MD'
+              The `--default` modifier picks the theme applied on first paint and
+              `--prefersdark` the one used when the OS asks for a dark scheme.
+              That block above is this very site's — its nine themes are the nine
+              in `c.themes`.
+            MD
+
             DocsUI::Callout(:warning) do
               plain "Interpolated Tailwind class names get tree-shaken. Always write "
               strong { "literal" }
-              plain " class strings in components — e.g. "
+              plain " class strings — e.g. "
               code { 'class: "badge badge-primary"' }
               plain ", never "
               code { 'class: "badge badge-\#{color}"' }
-              plain ". The scanner can't see the built name, so the style never ships."
+              plain ". The scanner can't see the built name, so the style never ships. New render-time classes (like the Drawer) need an "
+              code { "@source inline(...)" }
+              plain " line."
             end
           end
+        end
+
+        def adding_a_theme_section
+          DocsUI::Section("Adding a theme",
+                          description: "Two edits and a rebuild — CSS block, config, done.") do
+            md <<~'MD'
+              Themes come from daisyUI. To add one, keep the two lists in step:
+
+              1. Add the name to the `@plugin "daisyui" { themes: ... }` block in
+                 `application.tailwind.css`.
+              2. Add the same name to `c.themes` in
+                 `config/initializers/docs_kit.rb`.
+              3. Rebuild the CSS (`bun run build:css`).
+
+              First entry in `c.themes` is the page default; override with
+              `c.default_theme`. See [Configuration](/docs/configuration) for the
+              full theme surface.
+            MD
+
+            DocsUI::Code(<<~RUBY, filename: "config/initializers/docs_kit.rb")
+              DocsKit.configure do |c|
+                c.themes = %w[dark light synthwave retro cyberpunk dracula night nord sunset]
+              end
+            RUBY
+          end
+        end
+
+        def code_theme_section
+          DocsUI::Section("Code highlighting: one light theme, one dark",
+                          description: "Rouge highlights code; two config knobs make it follow the switcher.") do
+            md <<~'MD'
+              `DocsUI::Code` highlights with [Rouge](/docs/languages) and injects
+              its **own** inline theme CSS — no separate stylesheet asset. Which
+              theme that CSS uses is config:
+
+              - `c.code_theme` — the **base** Rouge theme, emitted **un-scoped**
+                so it applies under every daisyUI theme. Default
+                `Rouge::Themes::Monokai`.
+              - `c.code_theme_dark` — an **optional** second Rouge theme. When
+                set, `Code` additionally emits that theme's CSS scoped under
+                `[data-theme=X] .code-highlight` for each shipped dark theme.
+                daisyUI's more-specific `[data-theme]` selector wins, so code
+                blocks restyle when the switcher lands on a dark theme.
+                **CSS-only — no JS, no flash.** Default `nil` (single-theme,
+                byte-for-byte backwards compatible).
+              - `c.dark_themes` — which theme names count as dark for that
+                scoping. Defaults to the built-in daisyUI dark themes and is
+                intersected with `c.themes` at render time, so only **shipped**
+                dark themes emit CSS. A custom/branded dark theme must be listed
+                here or its code CSS won't scope — docs-kit can't inspect the
+                compiled daisyUI CSS to detect darkness.
+            MD
 
-          DocsUI::Section("Custom styles") do
-            prose do
-              p do
-                plain "Add your own CSS below the imports in "
-                code { "application.tailwind.css" }
-                plain " — plain rules, "
-                code { "@apply" }
-                plain ", or "
-                code { "@layer" }
-                plain " all work."
+            md <<~'MD'
+              **This site sets both.** Its initializer picks a light base and a
+              dark override, so every code block on the page you're reading
+              restyles as you flip the theme switcher between a light theme
+              (`light`, `retro`, `cyberpunk`, `nord`) and a dark one:
+            MD
+
+            DocsUI::Code(<<~RUBY, filename: "config/initializers/docs_kit.rb")
+              DocsKit.configure do |c|
+                c.code_theme      = "Rouge::Themes::Github"  # light themes
+                c.code_theme_dark = "Rouge::Themes::Monokai" # dark themes
+                # c.dark_themes defaults to daisyUI's dark set; override only
+                # for a custom dark theme the built-in list doesn't know.
               end
-              p do
-                plain "To pull in additional stylesheets (loaded after the built one), list them via "
-                code { "c.stylesheets" }
-                plain " in your initializer."
+            RUBY
+
+            md <<~'MD'
+              Try it: switch the theme in the topbar and watch this next block
+              change palette. It's the same highlighter, two scoped stylesheets.
+            MD
+
+            DocsUI::Code(<<~RUBY, filename: "app/models/doc.rb")
+              class Doc
+                extend DocsKit::Registry
+
+                path_prefix    "/docs"
+                view_namespace "Views::Docs::Pages"
+
+                page "Overview",       group: "Getting started"
+                page "Styling & CSS",  group: "Getting started"
               end
+            RUBY
+
+            md <<~'MD'
+              For this site, the shipped dark themes (the intersection of
+              `c.dark_themes` and `c.themes`) are **dark, synthwave, dracula,
+              night, sunset** — those five each get a `[data-theme=…]`-scoped
+              Monokai block; the four light themes fall through to the un-scoped
+              GitHub base.
+            MD
+
+            render DocsUI::PropTable.new(
+              [
+                [ "c.code_theme", "String or Class", "Rouge::Themes::Monokai", "Base (light) Rouge theme, emitted un-scoped." ],
+                [ "c.code_theme_dark", "String, Class, nil", "nil", "Optional dark override, scoped per shipped dark theme. nil = single-theme." ],
+                [ "c.dark_themes", "Array<String>", "daisyUI dark set", "Which theme names count as dark; intersected with c.themes at render." ]
+              ]
+            )
+
+            DocsUI::Callout(:note) do
+              plain "A String theme name is resolved to its Rouge constant. A typo'd or "
+              plain "unloaded name "
+              strong { "degrades gracefully" }
+              plain " — the base theme falls back to the default and a bad "
+              code { "code_theme_dark" }
+              plain " simply emits no dark CSS, so a mistake never crashes a code block."
             end
+          end
+        end
+
+        def custom_styles_section
+          DocsUI::Section("Custom styles",
+                          description: "Plain CSS, @apply, @layer, or extra stylesheets.") do
+            md <<~'MD'
+              Add your own CSS below the imports in `application.tailwind.css` —
+              plain rules, `@apply`, or `@layer` all work.
+
+              To pull in additional, separately-built stylesheets (linked after
+              the Tailwind build), list their logical names via `c.stylesheets`
+              in your initializer. Default is `%w[application]` — the Bun/Tailwind
+              build.
+            MD
+
             DocsUI::Code(<<~RUBY, filename: "config/initializers/docs_kit.rb")
               DocsKit.configure do |c|
-                c.stylesheets = %w[custom announcements]
+                c.stylesheets = %w[application announcements]
               end
             RUBY
+
+            md <<~'MD'
+              Next: see [Languages](/docs/languages) for the Rouge lexer surface,
+              [Components](/docs/components) for the kit `Code` and `Example`
+              render live, and [Configuration](/docs/configuration) for every
+              config knob in one place.
+            MD
           end
         end
       end
diff --git a/docs/config/initializers/docs_kit.rb b/docs/config/initializers/docs_kit.rb
index 9786961..8dc4c5c 100644
--- a/docs/config/initializers/docs_kit.rb
+++ b/docs/config/initializers/docs_kit.rb
@@ -28,8 +28,10 @@
 
     # The sidebar nav derives from the registry — one heading → one registry.
     # Each registry's authored pages become NavItems automatically (an unwritten
-    # page is skipped, so no dead links). For bespoke nav (interleaved
-    # registries, custom subgroups) set a `c.nav` lambda instead; it wins.
+    # page is skipped, so no dead links); the page `group:` values render as the
+    # collapsible sub-groups (Getting started / Authoring / Reference / AI &
+    # tooling / Deploy). For bespoke nav (interleaved registries) set a `c.nav`
+    # lambda instead; it wins.
     c.nav_registries = { "Docs" => Doc }
   end
 end