diff --git a/.ai/rules/documentation-structure-and-formatting.md b/.ai/rules/documentation-structure-and-formatting.md
new file mode 100644
index 0000000..87753fe
--- /dev/null
+++ b/.ai/rules/documentation-structure-and-formatting.md
@@ -0,0 +1,86 @@
+---
+applyTo: "**/Documentation/**/*.{md,mdx}"
+paths:
+  - "**/Documentation/**/*.md"
+  - "**/Documentation/**/*.mdx"
+---
+
+# Documentation Structure & Formatting (so a page fits the site)
+
+The mechanical conventions a page must follow to slot into the Astro Starlight site correctly. (For *what* to write — the tour voice — see [Writing Cratis Documentation](./writing-cratis-docs.md). For *where* a page lives — see [Editing Cratis Documentation](./editing-cratis-docs.md).) Product `.md` is run through `web/scripts/sync-content.mjs` before it reaches Starlight; this is what that converter expects and does.
+
+## Frontmatter
+
+```yaml
+---
+title: Append an event          # required-ish; becomes the page H1
+description: One sentence …      # strongly recommended; SEO/meta + AI export
+sidebar:                         # optional: order / label / badge
+  order: 2
+  badge: { text: New, variant: tip }
+---
+```
+
+- The converter **keeps** `title`, `description`, `sidebar`; it **drops** DocFX keys (`uid`, `applyTo`, `storybook`, …). For product `.md` with no frontmatter, it derives a `title` from the first H1.
+- **Starlight renders `title` as the page H1 — so do NOT put an H1 in the body.** Start the body at `##` (H2). A leading body H1 is stripped, but don't rely on that; structure from H2.
+
+## Headings
+
+- **No body H1** (the title is the H1).
+- **The "On this page" ToC shows H2 only** (`tableOfContents: { min:2, max:2 }`). Structure each page as a flat list of `##` sections — sub-points go under them as `###`/prose, not as ToC entries.
+- Use sentence case in headings; no trailing punctuation.
+
+## File & folder layout
+
+- Every folder has a **`toc.yml`** (navigation) and an **`index.md`** (landing). A folder whose landing is `overview.md` (no `index.md`) **404s on the bare URL** — give it an `index.md` or link to a specific page.
+- A `toc.yml` entry pointing to a **missing page is dropped** from the sidebar (the sync prints "N broken toc entries dropped" — keep it 0).
+- `toc.yml` sections are regrouped into Diátaxis **buckets** (Get started / Guides / Understand / Reference) via `PRODUCTS[].buckets` in `sync-content.mjs`. Sections named **"Getting started…"** auto-get a *Quickstart* badge; **"Tutorial"** gets a *Tutorial* badge.
+
+## Callouts / asides
+
+Write DocFX alerts in product `.md` (converted automatically) **or** Starlight directives directly:
+
+| DocFX | Becomes |
+|---|---|
+| `> [!NOTE]` / `> [!IMPORTANT]` | `:::note` |
+| `> [!TIP]` | `:::tip` |
+| `> [!WARNING]` | `:::caution` |
+| `> [!CAUTION]` | `:::danger` |
+
+```
+:::note
+Body of the callout.
+:::
+```
+
+In `.mdx` you may also use `<Aside type="tip">…</Aside>` (import from `@astrojs/starlight/components`).
+
+## Code blocks
+
+- **Always tag the language** for highlighting: ` ```csharp `, ` ```tsx `, ` ```bash `, ` ```yaml `, etc. DocFX-era custom fences (`env`, `pdl`, `ebnf`, `pql`, `gitignore`, `flow`) are aliased to plain text so they don't warn — but use a real language where one exists.
+- **No spurious common leading indentation** — if a snippet is lifted from inside a method, dedent it to column 0 (the whole block shifted right reads as "indented"). Keep only the code's own internal indentation.
+- Where a feature spans the stack, show **both sides** with `<FullStackTabs>` (synced C# ↔ generated TS) rather than backend-only.
+- `[!INCLUDE [x](./x.md)]` is inlined; `[Snippet source](…)` links stay as-is.
+
+## Tables, images, links, diagrams
+
+- **Tables** are GitHub-Flavored Markdown (`| … |` with a `| --- |` separator row, blank line before). They render as real tables (the site tints the header). A table that shows as raw `|` pipes means GFM isn't applying — check the Documentation repo's site-rendering rule.
+- **Images** use relative paths next to the page; they're click-to-zoom automatically. Give meaningful alt text.
+- **Links:** product `.md` may use `./foo.md`; links to a `.mdx` page must be **extension-less** (`./foo`); site-level `.mdx` uses clean root-relative URLs (`/arc/…`). Cross-product links are root-relative. **Link text must describe the destination** — never `[here]` / `[see documentation]` (the gate fails on these).
+- **Diagrams:** ` ```mermaid ` fences for any non-trivial concept (pre-rendered to SVG at build).
+
+## `.mdx` specifics
+
+- Frontmatter `title` + `description`, **no body H1**, then imports:
+  ```mdx
+  import { Steps, Tabs, TabItem, Aside } from '@astrojs/starlight/components';
+  import { FullStackTabs, TopicHero, SimpleCard, StackDiagram } from '@components';
+  ```
+- Valid `<TabItem>` icons include `apple`, `linux`, `seti:c-sharp`, `seti:react`.
+- The splash front door uses `template: splash` in frontmatter.
+
+## File hygiene
+
+- **End every file with a single trailing newline.**
+- Don't use shell commands to modify a doc after writing it.
+- Verify before done: `cd Documentation/web && npm run check` must end **0 error(s)** and **0 broken** links.
diff --git a/.ai/rules/editing-cratis-docs.md b/.ai/rules/editing-cratis-docs.md
new file mode 100644
index 0000000..8935f8c
--- /dev/null
+++ b/.ai/rules/editing-cratis-docs.md
@@ -0,0 +1,54 @@
+---
+applyTo: "**/Documentation/**/*.{md,mdx}"
+paths:
+  - "**/Documentation/**/*.md"
+  - "**/Documentation/**/*.mdx"
+---
+
+# Editing Cratis Documentation (the content is split across repos)
+
+Cratis documentation is **not** one folder. The content lives in **each product's own repo** under that repo's `Documentation/` folder, and a single published site (in the **`Documentation` repo**, at `Documentation/web/`) aggregates them all at build time. Know where a page actually lives before you edit it, or you'll edit a generated copy that gets overwritten.
+
+## Where each page actually lives
+
+| Page | Source of truth |
+|---|---|
+| `/chronicle/**` | `Chronicle/Documentation/**` |
+| `/arc/**` | `Arc/Documentation/**` (the `ApplicationModel` repo, cloned as `Arc`) |
+| `/components/**` | `Components/Documentation/**` |
+| `/cli/**`, `/fundamentals/**`, `/contributing/**` | the matching repo's `Documentation/` |
+| Site-level pages (`/`, `/why-cratis`, `/cratis-stack`, `/glossary`, `/comparisons/**`, …) | `Documentation/web/src/content/docs/*.{md,mdx}` (authored directly in the site) |
+
+**Map a URL to a file:** `/chronicle/concepts/event-source/` → `Chronicle/Documentation/concepts/event-source.md`. The site reads each product repo as a **sibling clone** (`<parent>/{Documentation,Chronicle,Arc,Components,Fundamentals,cli,.github}`), all on the same branch.
+
+## The one rule that prevents wasted work
+
+**NEVER edit `Documentation/web/src/content/docs/{chronicle,arc,components,cli,fundamentals,contributing}/`.** Those are **generated and git-ignored** — `web/scripts/sync-content.mjs` regenerates them from the product repos on every build. Edit the **product-repo source** and re-sync. (Site-level pages directly under `web/src/content/docs/` *are* hand-authored — only the per-product subfolders are generated.)
+
+## The loop
+
+1. **Edit** the source `.md`/`.mdx` in the owning product repo (or the site-level page in `web/src/content/docs/`).
+2. **Sync + preview:** from `Documentation/web`, `npm run dev` (runs the sync, serves http://localhost:4321). The sync also runs automatically in `predev`/`prebuild`.
+3. **Verify:** `npm run check` — the full gate. It MUST end **0 error(s)** and **0 broken** links (≈187 advisory style warnings are expected and fine). Run it after every change.
+4. Commit the change in the **product repo** (content) — the site repo only changes if you touched site-level pages, nav buckets, or the build.
+
+## Adding or moving a page
+
+- Create the file in the product repo's `Documentation/`, add a `toc.yml` entry, and add that entry's `name` to the right Diátaxis **bucket** in `web/scripts/sync-content.mjs` (`PRODUCTS[].buckets`). Site-level pages are wired in `astro.config.mjs` instead.
+- Buckets are the Diátaxis order: **Get started** (tutorials) → **Guides** (how-to) → **Understand** (explanation) → **Reference**. Keep every product on this shape.
+
+## Links (the rules differ by file type)
+
+- **Product `.md`** goes through the converter — `[x](./foo.md)` is fine (it strips `.md`).
+- **Intra-doc links to a `.mdx` page must be EXTENSION-LESS** (`./validation`, not `./validation.mdx`) — slugify strips the dot and breaks `.mdx`.
+- **Site-level `.mdx`** does NOT go through the converter — use clean root-relative URLs (`/arc/...`), never `.md`.
+- Cross-product links are root-relative: `/chronicle/...`. Sections whose landing is `overview.md` (no `index.md`) 404 on the bare URL — link to a specific page.
+
+## Hard gotchas (these will bite you)
+
+- **A long-running `npm run dev` degrades** (every page 500s / tables stop rendering) — and **running `npm run check`/`build` while dev is live** corrupts it (the build re-syncs content the dev server is watching). Fix: **restart `npm run dev`** (kill `lsof -ti tcp:4321`). Re-verify a fresh dev server before trusting any "X doesn't render".
+- **The Astro content cache (`.astro/`, `node_modules/.astro`) silently serves a PARTIAL prior render** between iterations. If a change "didn't take" or a build looks half-done, `rm -rf .astro node_modules/.astro` and rebuild.
+- **Code examples are copied verbatim by readers** — verify every framework API against real source before writing it. See [Writing Correct Code Examples](./writing-correct-examples.md).
+- Match the **tour voice** (teach, don't dump) and the right **Diátaxis** type — see [Writing Cratis Documentation](./writing-cratis-docs.md).
+
+→ Site build and rendering internals live in the Documentation repo.
diff --git a/.ai/rules/writing-correct-examples.md b/.ai/rules/writing-correct-examples.md
new file mode 100644
index 0000000..cbd0690
--- /dev/null
+++ b/.ai/rules/writing-correct-examples.md
@@ -0,0 +1,35 @@
+---
+applyTo: "**/Documentation/**/*.{md,mdx}"
+paths:
+  - "**/Documentation/**/*.md"
+  - "**/Documentation/**/*.mdx"
+---
+
+# Writing Correct Code Examples (Technical Docs)
+
+Documentation code examples are **copied verbatim** by evaluators. A snippet that uses an API that doesn't exist is worse than no snippet — it breaks on first paste and loses trust. An audit of these docs found **~12 fabricated-API bugs** that had passed review and shipped. The discipline below is how you avoid adding the thirteenth.
+
+## The rule: verify every framework API against real source — before you write it
+
+For each framework type, attribute, method, prop, hook, or import in an example, confirm it exists and has that exact shape in **source**, not in another doc page (the docs themselves had the bugs):
+
+- **C# / backend** — grep real usage in **Studio** (`/Volumes/sourcecode/repos/cratis/Studio/Source`, `*.cs`) and the product `Source/` trees (`Arc/Source`, `Chronicle/Source`). For extension methods, find the `public static … (this <Type> …)` signature and note **which type it extends**.
+- **React / Components** — the authoritative prop names are in the compiled type defs: `Components/Source/dist/esm/**/*.d.ts`. Real usage: Studio `*.tsx`.
+- **Invented *domain* names are fine** (event/concept/command names like `AuthorRegistered`, `BookId`). Only **framework APIs** must be real. Never invent a framework interface, attribute, prop, method, or import path.
+
+## Complete and correct
+
+- No pseudo-code, no `// ...` elisions that leave the reader guessing, no props/members that don't exist.
+- A snippet a reader pastes should compile (modulo the invented domain types they'd supply).
+
+## Verified gotchas (the real APIs — these are the ones docs kept getting wrong)
+
+- Commands/queries are **model-bound**: a `[Command]` record with `Handle()` **on the record**, and `[ReadModel]` records with **static** query methods. The marker/handler interfaces `ICommand`, `ICommandHandler<T>`, `IQuery<T>`, `IQueryHandler<T,R>` **do not exist** — never use them.
+- Bootstrap: `ArcApplication.CreateBuilder(args)` (not `ArcApplicationBuilder.CreateBuilder`). `builder.AddCratisArc()` on the builder (`WebApplicationBuilder`/`IHostBuilder`); `app.UseCratisArc()` on the built app and it takes **no args** (the listen URL comes from `ArcOptions.Hosting.ApplicationUrl`).
+- Read the current user inside `Handle()` by injecting **`IHttpContextAccessor`** and reading `HttpContext?.User` (`ClaimsPrincipal`). There is no `CommandContext.User` and no `IUserAccessor` Arc type. In-`Handle` guards return `Result<ValidationResult, T>` + `ValidationResult.Error(...)` — there is no `CommandResult.Forbidden`/`Unauthorized` to return.
+- Components: `DataPage` uses the **compound** `DataPage.Columns` / `DataPage.MenuItems`; the detail prop is **`detailsComponent`** (lowercase) — `detailsTitle`/`initialSizes` are **not** props. Import `DataTableForObservableQuery` from `@cratis/components/DataTables` (the root barrel only re-exports namespaces); `DataPage`/`MenuItem` from `@cratis/components/DataPage`. Required props like `emptyMessage`/`title` must be present.
+- Chronicle model-bound projections use property attributes **`[SetFrom<T>]`** / **`[SetValue<T>]`** (and `[FromEvent<T>]` AutoMap) — **not** `static On(event)` methods (that shape doesn't exist). Retrieve a read model with `eventStore.ReadModels.GetInstanceById<T>(id)`. Integration assertion is `ShouldHaveAppendedEvent<TEvent>(seq, eventSourceId, validator)` (**3 args**).
+
+## Auditing at scale
+
+Re-run a snippet-correctness audit periodically — it keeps finding bugs (the list above came from three rounds). Delegate the cross-checking to subagents that compare each snippet to source and report only confirmed discrepancies; **verify each finding against source yourself before fixing**. Consider adopting an automated example tester (**Doc Detective**, **Squidler** — from awesome-docs) that actually runs the snippets, so correctness is enforced by CI rather than by hand. The principle, from jvns's "write good examples by starting with real code": derive examples from working source, don't compose them from memory.
diff --git a/.ai/rules/writing-cratis-docs.md b/.ai/rules/writing-cratis-docs.md
new file mode 100644
index 0000000..8e63b4d
--- /dev/null
+++ b/.ai/rules/writing-cratis-docs.md
@@ -0,0 +1,75 @@
+---
+applyTo: "**/Documentation/**/*.{md,mdx}"
+paths:
+  - "**/Documentation/**/*.md"
+  - "**/Documentation/**/*.mdx"
+---
+
+# Writing Cratis Documentation — tour voice + Starlight authoring
+
+The Cratis docs must **take the reader on a tour, like a teacher** — the way [Marten](https://martendb.io), [Wolverine](https://wolverinefx.net), and [aspire.dev](https://aspire.dev) docs do — **not** state facts like a reference dump. This is the project's strongest qualitative bar and it's been flagged repeatedly. The differentiator of those docs is **pedagogical structure**, not looks. Match it.
+
+## The bar
+
+- **Pain → relief.** Open by naming the friction the reader feels, then reveal the feature as the relief. (Aspire's "without vs. with".)
+- **Why before how.** A reader who understands the reasoning handles edge cases the docs don't cover.
+- **Active voice, present tense, second person.** "You append the event," not "the event is appended."
+- **Be honest about limits.** A "when this is the wrong fit" section builds more trust than omitting it.
+
+## One page = one Diátaxis type (it also picks the nav bucket)
+
+| Type | Reader is… | Reads like | Nav bucket |
+|---|---|---|---|
+| **Tutorial** | learning by doing | a guided lesson — each step a visible result | Get started |
+| **How-to** | solving a specific problem | a recipe — assume competence, no teaching | Guides |
+| **Explanation** | trying to understand | a discussion — concepts, trade-offs, *why*, a diagram | Understand |
+| **Reference** | looking something up | a dictionary — exhaustive, terse, tables/signatures | Reference |
+
+Never mix types. A tutorial padded with reference detail overwhelms; a how-to interrupted by concept digressions stops being a recipe.
+
+## The tour-voice checklist (apply to tutorials, getting-started, and explanations)
+
+1. **Open with a concrete scenario** ("a book shows up — let's record that"), not a definition of the tool.
+2. **Name the friction first**, then the feature as its relief.
+3. **"Let's…" with chronological verbs** (define → append → project → query).
+4. **After every code block, explain the invisible** — what happens under the hood and why it matters.
+5. **Recap before pivoting** ("this works well for X… however…").
+6. **Anticipate the reader's doubt** with an inline aside ("in a real app you'd…").
+7. **Show the result** — the output, the resulting read model/JSON — so success is visible.
+8. **Organize by workflow**, not alphabetically (especially CLI/command docs).
+9. **End every section with a forward link** to the natural next step.
+
+`Chronicle/Documentation/tutorial/*` is the reference voice — read it before writing.
+
+## Achieve the tour voice with Starlight's authoring tools
+
+Author rich pages as **`.mdx`** (the converter keeps `.mdx`): frontmatter `title` + `description`, **no body H1**, then import what you need:
+
+```mdx
+import { Steps, Tabs, TabItem, Aside } from '@astrojs/starlight/components';
+import { FullStackTabs, TopicHero, SimpleCard, StackDiagram, YouWillLearn, Recap } from '@components';
+```
+
+- **`<Steps>`** — procedures where each step produces a visible result (checklist point 1, 3).
+- **`<Tabs>` / `<TabItem>`** — alternatives (OS, console-vs-web, C#-vs-fluent). Valid icons include `apple`, `linux`, `seti:c-sharp`, `seti:react`.
+- **`<Aside>`** — anticipate doubt / call out a gotcha (checklist point 6).
+- **`<FullStackTabs>`** — synced C# ↔ generated-TypeScript tabs. **This is the differentiator** (full-stack type safety) — use it wherever a feature spans the stack; show both sides, not just the backend.
+- **`<TopicHero>` + `<SimpleCard>`** — the per-product Overview landings (pain→relief framing + a card grid).
+- **`<StackDiagram>`, `<YouWillLearn>`, `<Recap>`** — the stack picture, a chapter's learning goals, and the closing recap (checklist points 1 and 5).
+- **A Mermaid diagram for every non-trivial concept** — architecture, event/command flow, state transitions. A concept page without a diagram is usually incomplete. (The Documentation site pre-renders them to SVG at build time.)
+
+## Two voices, and connect the products
+
+- **Two voices per area:** the toured/educational layer (tutorial, getting-started, "Understanding…") **and** the terse, exhaustive reference. The narrative pages **link *down*** into the reference; the reference stays a dictionary.
+- **Connect at the seams** rather than re-explaining: a command (Arc) appends events (Chronicle); a query reads a projection (Chronicle) rendered by a component (Components). Link to the **glossary** for shared terms instead of redefining them.
+- **Coming-from-X bridges** map new concepts to what the reader knows (MediatR, MVC, EF/CRUD, Marten/other event stores).
+
+## Before you call a page done
+
+- Every framework API in a code example is **verified against real source** — see [Writing Correct Code Examples](./writing-correct-examples.md). Readers paste snippets verbatim.
+- `npm run check` is green (0 errors · 0 broken links); the page sits in the right nav bucket.
+- For a visual page, screenshot it in light **and** dark — see the `qa-cratis-docs` skill.
+
+**Study the masters (cloned locally):** `~/src/repos/aspire.dev` (Starlight — great CLI docs + tour writing), `~/src/repos/marten`, `~/src/repos/wolverine`. Mine their *patterns*; never copy their text.
+
+→ The mechanical format a page must follow (frontmatter, headings, asides, code fences, file layout): [Documentation Structure & Formatting](./documentation-structure-and-formatting.md). The edit→sync→verify loop and where pages live: [Editing Cratis Documentation](./editing-cratis-docs.md). Site build internals live in the Documentation repo.
diff --git a/.ai/skills/add-cratis-docs-page/SKILL.md b/.ai/skills/add-cratis-docs-page/SKILL.md
new file mode 100644
index 0000000..85ffef4
--- /dev/null
+++ b/.ai/skills/add-cratis-docs-page/SKILL.md
@@ -0,0 +1,43 @@
+---
+name: add-cratis-docs-page
+description: Use this skill when creating a NEW Cratis documentation page under `Documentation/**` in a product or contributing repo — a new tutorial chapter, how-to/guide, explanation/concept page, reference page, or scenario/recipe. Handles where the file goes (which product repo), wiring it into the sidebar nav (toc.yml + Diátaxis bucket), and verifying it renders. Trigger when someone asks to add/create/write a new docs page, document a new feature, add a guide/tutorial/recipe/concept to the docs, or add a new section to a product's documentation.
+---
+
+# Adding a new Cratis documentation page
+
+> Scope this skill to new source files under `Documentation/**` in the product or contributing repo. Site-level pages in `Documentation/web` are owned by the Documentation repo.
+
+The site builds its navigation from each product's `toc.yml`, regrouped into Diátaxis buckets. A new page must be created in the right repo AND wired into the nav, or it builds but is unreachable.
+
+## 1. Decide the type and the home
+
+- **Which product?** Put the file in that product's repo: `Chronicle/Documentation/`, `Arc/Documentation/`, `Components/Documentation/`, `cli/Documentation/`, `Fundamentals/Documentation/`. A cross-product / site-level page belongs in the Documentation repo's `web/src/content/docs/`, not in this product repo.
+- **Which Diátaxis type?** It decides the bucket and the voice — write *only* that type:
+  - **Tutorial** (Get started) — learning by doing, steps with visible results.
+  - **How-to / Guide** (Guides) — a recipe for a specific task; assume competence.
+  - **Explanation / Concept** (Understand) — the *why*, trade-offs, a diagram.
+  - **Reference** — exhaustive, terse, tables/signatures.
+
+## 2. Create the file
+
+- Author in the **tour voice** (open with a scenario, name the friction, narrate the code, show the result, forward-link at the end). The Chronicle tutorial (`Chronicle/Documentation/tutorial/*`) is the reference voice.
+- **Format it to fit the site** — frontmatter (`title` + `description`, **no body H1**), H2-only structure, `:::note` asides, language-tagged code fences, GFM tables. The full spec is the **`documentation-structure-and-formatting`** rule.
+- **`.mdx`** unlocks `<Steps>`, `<Tabs>`, `<Aside>` (from `@astrojs/starlight/components`) and the shared `@components` (`FullStackTabs`, `TopicHero`, `SimpleCard`, `StackDiagram`).
+- Add a **Mermaid diagram** for any non-trivial concept (they're pre-rendered to SVG at build time).
+- Verify every framework API in code examples against real source (the `writing-correct-examples` rule).
+
+## 3. Wire it into the nav
+
+- **Product page:** add the entry to that repo's `Documentation/toc.yml`, then add the entry's `name` to the correct bucket's `sections` in `Documentation/web/scripts/sync-content.mjs` (`PRODUCTS[].buckets`). Buckets order: **Get started → Guides → Understand → Reference**.
+- **Site-level page:** use the Documentation repo copy of this skill; site-level pages are wired in `astro.config.mjs` there.
+- **Links:** to a `.mdx` page use an **extension-less** link; `.md` keeps the extension; cross-product links are root-relative (`/chronicle/...`).
+
+## 4. Verify
+
+```bash
+cd Documentation/web && npm run check
+```
+
+Must end **0 error(s)** and **0 broken** links, and your page must appear in the nav (the converter drops `toc.yml` entries whose slug doesn't match a built page — check the sync output for "broken toc entries dropped"). Preview at http://localhost:4321 (`npm run dev`); screenshot it with the `qa-cratis-docs` skill. Commit in the owning product repo (+ the site repo if you touched buckets/`astro.config`).
+
+→ To edit an existing page instead, use `edit-cratis-docs`. The content craft — tour voice + how to use Starlight's authoring tools (`<Steps>`, `<Tabs>`, `<FullStackTabs>`, diagrams) — is the **`writing-cratis-docs`** rule. Read it before writing.
diff --git a/.ai/skills/edit-cratis-docs/SKILL.md b/.ai/skills/edit-cratis-docs/SKILL.md
new file mode 100644
index 0000000..12321f0
--- /dev/null
+++ b/.ai/skills/edit-cratis-docs/SKILL.md
@@ -0,0 +1,50 @@
+---
+name: edit-cratis-docs
+description: Use this skill when changing, fixing, or improving Cratis documentation whose source file is under `Documentation/**` in a product or contributing repo. The content is split across repos (each product owns its docs in its own `Documentation/` folder; the `Documentation` repo aggregates them), so this skill finds the real source file, edits it, syncs, and verifies. Trigger whenever someone asks to edit/update/fix/reword a docs page, fix a broken link, correct a code example, update a guide or tutorial or reference page, or says a docs page is wrong/outdated — for Chronicle, Arc, Components, CLI, Fundamentals, or the contributing docs.
+---
+
+# Editing a Cratis documentation page
+
+> Scope this skill to source files under `Documentation/**` in the product or contributing repo. Site-level pages in `Documentation/web` are owned by the Documentation repo.
+
+Cratis docs content lives in **each product's own repo** under that repo's `Documentation/` folder; the published site (in the `Documentation` repo at `Documentation/web/`) aggregates them. Editing the wrong copy wastes the work — the per-product folders under `web/src/content/docs/` are **generated and overwritten**.
+
+## 1. Find the source of truth
+
+Map the page URL to its owning repo:
+
+| URL | Source file |
+|---|---|
+| `/chronicle/**` | `Chronicle/Documentation/**` |
+| `/arc/**` | `Arc/Documentation/**` (the `ApplicationModel` repo, cloned as `Arc`) |
+| `/components/**` | `Components/Documentation/**` |
+| `/cli/**`, `/fundamentals/**`, `/contributing/**` | the matching repo's `Documentation/` |
+| `/`, `/why-cratis`, `/cratis-stack`, `/glossary`, `/comparisons/**`, `/adopting-cratis`, … | Site-level pages: use the Documentation repo; source lives in `Documentation/web/src/content/docs/*.{md,mdx}`. |
+
+Example: `/chronicle/concepts/event-source/` → `Chronicle/Documentation/concepts/event-source.md`. If unsure, `grep -rl "<a distinctive sentence>" */Documentation Documentation/web/src/content/docs/*.md*`.
+
+**Never edit `Documentation/web/src/content/docs/{chronicle,arc,components,cli,fundamentals,contributing}/`** — generated and git-ignored.
+
+## 2. Edit the source
+
+- Match the page's **Diátaxis type** (tutorial / how-to / explanation / reference) and the **tour voice** (teach, don't dump) — see the **`writing-cratis-docs`** rule (the tour-voice checklist + Starlight authoring tools). Don't mix types.
+- **Verify every framework API in a code example against real source** before writing it — readers paste them verbatim. (See the `writing-correct-examples` rule; grep Studio `*.cs`/`*.tsx` and the product `Source/` trees.)
+- Link rules: product `.md` may use `./foo.md`; links to a `.mdx` page must be **extension-less** (`./foo`); site-level `.mdx` uses clean root-relative URLs (`/arc/...`).
+
+## 3. Sync, preview, verify
+
+```bash
+cd Documentation/web
+npm run dev      # serves http://localhost:4321 (re-syncs the product repos)
+npm run check    # the gate: build + lint + link-check
+```
+
+`npm run check` MUST end **0 error(s)** and **0 broken** links (≈187 advisory style warnings are expected). Fix anything it flags. **Restart `npm run dev` after running the gate** — the gate's re-sync degrades a live dev server.
+
+For visual changes, screenshot the page in light and dark and read the result — use the `qa-cratis-docs` skill.
+
+## 4. Commit
+
+Commit the change in the **product repo** that owns the page (the site repo only changes if you touched a site-level page, the nav buckets in `sync-content.mjs`, or the build). Keep commits to one logical unit; don't push without explicit approval.
+
+→ Site build and rendering internals live in the Documentation repo. To create a *new* page (not edit an existing one), use the `add-cratis-docs-page` skill.
diff --git a/.ai/skills/qa-cratis-docs/SKILL.md b/.ai/skills/qa-cratis-docs/SKILL.md
new file mode 100644
index 0000000..b6ee6dc
--- /dev/null
+++ b/.ai/skills/qa-cratis-docs/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: qa-cratis-docs
+description: Use this skill to visually QA rendered docs site pages after changes to source files under `Documentation/**` — screenshot pages headless in light AND dark, evaluate how they look against the aspire.dev bar, check diagrams/tables/code blocks render, and diagnose layout-shift ("flicker"/"twitch"/"pop") bugs. Trigger when someone asks to screenshot the docs, check how a docs page looks, review the docs visually, verify a diagram or table renders, compare the docs to aspire.dev, or investigate a flicker/jump/layout-shift on the docs site.
+---
+
+# Visual & layout QA for the docs site
+
+> Scope this skill to visual checks for product or contributing docs whose source lives under `Documentation/**`. Site-level pages in `Documentation/web` are owned by the Documentation repo.
+
+`shot-scraper`/Playwright aren't dependencies, but Chrome is. Use the committed `Documentation/web/scripts/screenshot.mjs` (drives system Chrome over CDP) — it captures **light or dark**, full-page, with client-side rendering settled.
+
+## Capture
+
+```bash
+cd Documentation/web && npm run dev        # serve at http://localhost:4321 (keep it running)
+node scripts/screenshot.mjs http://localhost:4321/chronicle/concepts/event-source/ /tmp/es-dark.png dark
+node scripts/screenshot.mjs http://localhost:4321/chronicle/concepts/event-source/ /tmp/es-light.png light
+```
+
+Then **Read the PNG** to evaluate it. Crop/zoom with the `sharp` already in `node_modules` (PIL/ImageMagick aren't installed):
+
+```bash
+node -e "require('sharp')('/tmp/es-dark.png').extract({left:300,top:600,width:900,height:500}).resize({width:1400}).toFile('/tmp/crop.png')"
+```
+
+Build the page list from `web/src/generated/topics.json` + the site-level slugs. **The bar is aspire.dev** (`~/src/repos/aspire.dev/src/frontend`) — study its `site.css`/`mermaid.css` for the depth cues (gradient glows, framed diagrams, lifted cards) that `cratis.css` is built from.
+
+## What to check on each page
+
+- **Diagrams** themed and correctly sized in both themes (pre-rendered SVG — should be present immediately, no pop).
+- **Tables** render as real tables (not raw `|` pipes — that's the GFM/MDX bug).
+- **Code blocks** not over-indented (no spurious leading whitespace in the source snippet) and lifted off the page.
+- **Hero / cards** have depth (glow, lift), inline code is a brand-tinted chip.
+- Light AND dark both read cleanly.
+
+## Diagnosing a flicker / twitch / layout-shift
+
+The cause is almost always one of: **font swap** (fixed — `font-display: optional` + preload in `Head.astro`), **client-side rendering settling**, or **Mermaid** (fixed — build-time pre-render). To measure:
+
+- Inject a buffered `layout-shift` PerformanceObserver via CDP `Page.addScriptToEvaluateOnNewDocument` and sample `document.documentElement` height every ~16ms after navigate; print the timeline.
+- Use a **fresh `--user-data-dir`** for a cold (uncached) load; reuse it for a warm load. Many shifts only show cold.
+- For scroll-restoration flashes: scroll down, `Page.reload`, sample `window.scrollY` — if it lands short, content above is rendering late.
+- Run all CDP scripts **serially** — they collide on the debug port.
+
+## Caveats
+
+- **Restart `npm run dev` after running `npm run check`** — the gate's re-sync degrades a live dev server (pages 500, tables vanish). A degraded dev server makes screenshots lie; restart and re-verify before trusting a "broken" result.
+- The Astro dev toolbar appears mid-page in full-page captures — it's a dev-only overlay, not a real element.
+- `prefers-color-scheme` emulation can trigger astro-mermaid's theme observer on any client-rendered fallback diagram; pre-rendered diagrams are unaffected.
+
+→ Rendering internals live in the Documentation repo.
diff --git a/.claude/rules/documentation-structure-and-formatting.md b/.claude/rules/documentation-structure-and-formatting.md
new file mode 120000
index 0000000..403ade9
--- /dev/null
+++ b/.claude/rules/documentation-structure-and-formatting.md
@@ -0,0 +1 @@
+../../.ai/rules/documentation-structure-and-formatting.md
\ No newline at end of file
diff --git a/.claude/rules/editing-cratis-docs.md b/.claude/rules/editing-cratis-docs.md
new file mode 120000
index 0000000..e2f7b51
--- /dev/null
+++ b/.claude/rules/editing-cratis-docs.md
@@ -0,0 +1 @@
+../../.ai/rules/editing-cratis-docs.md
\ No newline at end of file
diff --git a/.claude/rules/writing-correct-examples.md b/.claude/rules/writing-correct-examples.md
new file mode 120000
index 0000000..98570f7
--- /dev/null
+++ b/.claude/rules/writing-correct-examples.md
@@ -0,0 +1 @@
+../../.ai/rules/writing-correct-examples.md
\ No newline at end of file
diff --git a/.claude/rules/writing-cratis-docs.md b/.claude/rules/writing-cratis-docs.md
new file mode 120000
index 0000000..5f4ddab
--- /dev/null
+++ b/.claude/rules/writing-cratis-docs.md
@@ -0,0 +1 @@
+../../.ai/rules/writing-cratis-docs.md
\ No newline at end of file
diff --git a/.github/instructions/documentation-structure-and-formatting.instructions.md b/.github/instructions/documentation-structure-and-formatting.instructions.md
new file mode 120000
index 0000000..403ade9
--- /dev/null
+++ b/.github/instructions/documentation-structure-and-formatting.instructions.md
@@ -0,0 +1 @@
+../../.ai/rules/documentation-structure-and-formatting.md
\ No newline at end of file
diff --git a/.github/instructions/editing-cratis-docs.instructions.md b/.github/instructions/editing-cratis-docs.instructions.md
new file mode 120000
index 0000000..e2f7b51
--- /dev/null
+++ b/.github/instructions/editing-cratis-docs.instructions.md
@@ -0,0 +1 @@
+../../.ai/rules/editing-cratis-docs.md
\ No newline at end of file
diff --git a/.github/instructions/specs-no-api-docs.instructions.md b/.github/instructions/specs-no-api-docs.instructions.md
deleted file mode 100644
index 7cfff2a..0000000
--- a/.github/instructions/specs-no-api-docs.instructions.md
+++ /dev/null
@@ -1 +0,0 @@
-../../.ai/rules/specs-no-api-docs.md
\ No newline at end of file
diff --git a/.github/instructions/writing-correct-examples.instructions.md b/.github/instructions/writing-correct-examples.instructions.md
new file mode 120000
index 0000000..98570f7
--- /dev/null
+++ b/.github/instructions/writing-correct-examples.instructions.md
@@ -0,0 +1 @@
+../../.ai/rules/writing-correct-examples.md
\ No newline at end of file
diff --git a/.github/instructions/writing-cratis-docs.instructions.md b/.github/instructions/writing-cratis-docs.instructions.md
new file mode 120000
index 0000000..5f4ddab
--- /dev/null
+++ b/.github/instructions/writing-cratis-docs.instructions.md
@@ -0,0 +1 @@
+../../.ai/rules/writing-cratis-docs.md
\ No newline at end of file
diff --git a/.github/skills b/.github/skills
new file mode 120000
index 0000000..6838a11
--- /dev/null
+++ b/.github/skills
@@ -0,0 +1 @@
+../.ai/skills
\ No newline at end of file
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index b502d83..0fe1b96 100644
--- a/.github/workflows/documentation.yml
+++ b/.github/workflows/documentation.yml
@@ -1,6 +1,12 @@
 name: Trigger documentation build
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 on:
+  workflow_dispatch:
+
   push:
     branches: ["main"]
     paths:
@@ -8,8 +14,6 @@ on:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 jobs:
   trigger:
@@ -19,6 +23,5 @@ jobs:
         uses: peter-evans/repository-dispatch@v3
         with:
           token: ${{ secrets.PAT_DOCUMENTATION }}
-          repository: cratis/documentation
+          repository: Cratis/Documentation
           event-type: build-docs
-
diff --git a/Documentation/CommandForm/calendar-field.md b/Documentation/CommandForm/calendar-field.md
index 9749515..e95d980 100644
--- a/Documentation/CommandForm/calendar-field.md
+++ b/Documentation/CommandForm/calendar-field.md
@@ -5,10 +5,10 @@
 ## Usage
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { CalendarField } from '@cratis/components/CommandForm';
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <CalendarField<MyCommand>
         value={c => c.startDate}
         placeholder="Select a date"
diff --git a/Documentation/CommandForm/checkbox-field.md b/Documentation/CommandForm/checkbox-field.md
index e51950c..2e481d4 100644
--- a/Documentation/CommandForm/checkbox-field.md
+++ b/Documentation/CommandForm/checkbox-field.md
@@ -5,10 +5,10 @@
 ## Usage
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { CheckboxField } from '@cratis/components/CommandForm';
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <CheckboxField<MyCommand> value={c => c.isActive} label="Active" />
     <CheckboxField<MyCommand> value={c => c.newsletter} label="Send me newsletter updates" />
 </CommandDialog>
diff --git a/Documentation/CommandForm/chips-field.md b/Documentation/CommandForm/chips-field.md
index b127a89..c3de794 100644
--- a/Documentation/CommandForm/chips-field.md
+++ b/Documentation/CommandForm/chips-field.md
@@ -5,10 +5,10 @@
 ## Usage
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { ChipsField } from '@cratis/components/CommandForm';
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <ChipsField<MyCommand>
         value={c => c.tags}
         placeholder="Add tags and press Enter"
diff --git a/Documentation/CommandForm/color-picker-field.md b/Documentation/CommandForm/color-picker-field.md
index c46defb..fff8958 100644
--- a/Documentation/CommandForm/color-picker-field.md
+++ b/Documentation/CommandForm/color-picker-field.md
@@ -5,10 +5,10 @@
 ## Usage
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { ColorPickerField } from '@cratis/components/CommandForm';
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <ColorPickerField<MyCommand>
         value={c => c.primaryColor}
         title="Primary color"
@@ -22,7 +22,7 @@ import { ColorPickerField } from '@cratis/components/CommandForm';
 |------|------|---------|-------------|
 | `value` | `(instance: TCommand) => unknown` | - | **Required.** Accessor function that returns the bound property from the command instance. Pass the command type as the generic parameter for full type safety. |
 | `inline` | `boolean` | `false` | Renders the picker inline instead of using an overlay. |
-| `defaultColor` | `string` | `ff0000` | Fallback color shown by PrimeReact when the bound value is empty. |
+| `defaultColor` | `string` | `000000` | Fallback color used when the bound value is empty. |
 
 ## Behavior
 
diff --git a/Documentation/CommandForm/dropdown-field.md b/Documentation/CommandForm/dropdown-field.md
index 187c34b..811ed6e 100644
--- a/Documentation/CommandForm/dropdown-field.md
+++ b/Documentation/CommandForm/dropdown-field.md
@@ -5,7 +5,7 @@
 ## Usage
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { DropdownField } from '@cratis/components/CommandForm';
 
 const statusOptions = [
@@ -13,7 +13,7 @@ const statusOptions = [
     { label: 'Inactive', value: 'inactive' },
 ];
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <DropdownField<MyCommand>
         value={c => c.status}
         options={statusOptions}
diff --git a/Documentation/CommandForm/index.md b/Documentation/CommandForm/index.md
index 8173fad..b1de9d0 100644
--- a/Documentation/CommandForm/index.md
+++ b/Documentation/CommandForm/index.md
@@ -39,10 +39,10 @@ The `value` prop accepts a function of the form `(instance: TCommand) => unknown
 CommandForm fields are used as children of `CommandDialog`:
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { InputTextField, NumberField, CheckboxField } from '@cratis/components/CommandForm';
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <InputTextField<MyCommand> value={c => c.title} />
     <NumberField<MyCommand> value={c => c.quantity} />
     <CheckboxField<MyCommand> value={c => c.active} label="Active" />
diff --git a/Documentation/CommandForm/input-text-field.md b/Documentation/CommandForm/input-text-field.md
index 9c2c8aa..ca42e1c 100644
--- a/Documentation/CommandForm/input-text-field.md
+++ b/Documentation/CommandForm/input-text-field.md
@@ -5,10 +5,10 @@
 ## Usage
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { InputTextField } from '@cratis/components/CommandForm';
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <InputTextField<MyCommand> value={c => c.username} placeholder="Enter username" />
     <InputTextField<MyCommand> value={c => c.email} type="email" placeholder="Enter email" />
     <InputTextField<MyCommand> value={c => c.password} type="password" />
diff --git a/Documentation/CommandForm/multi-select-field.md b/Documentation/CommandForm/multi-select-field.md
index a614cb8..283aa48 100644
--- a/Documentation/CommandForm/multi-select-field.md
+++ b/Documentation/CommandForm/multi-select-field.md
@@ -5,7 +5,7 @@
 ## Usage
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { MultiSelectField } from '@cratis/components/CommandForm';
 
 const categoryOptions = [
@@ -14,7 +14,7 @@ const categoryOptions = [
     { id: 'engineering', label: 'Engineering' },
 ];
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <MultiSelectField<MyCommand>
         value={c => c.categories}
         options={categoryOptions}
diff --git a/Documentation/CommandForm/number-field.md b/Documentation/CommandForm/number-field.md
index 55f7d98..ae89a9e 100644
--- a/Documentation/CommandForm/number-field.md
+++ b/Documentation/CommandForm/number-field.md
@@ -5,10 +5,10 @@
 ## Usage
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { NumberField } from '@cratis/components/CommandForm';
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <NumberField<MyCommand> value={c => c.quantity} min={1} max={100} />
     <NumberField<MyCommand> value={c => c.price} min={0} step={0.01} placeholder="0.00" />
 </CommandDialog>
diff --git a/Documentation/CommandForm/radio-button-field.md b/Documentation/CommandForm/radio-button-field.md
index 8957e8f..f28ce5b 100644
--- a/Documentation/CommandForm/radio-button-field.md
+++ b/Documentation/CommandForm/radio-button-field.md
@@ -5,10 +5,10 @@
 ## Usage
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { RadioButtonField } from '@cratis/components/CommandForm';
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <RadioButtonField<MyCommand> value={c => c.size} buttonValue="small" label="Small" />
     <RadioButtonField<MyCommand> value={c => c.size} buttonValue="medium" label="Medium" />
     <RadioButtonField<MyCommand> value={c => c.size} buttonValue="large" label="Large" />
diff --git a/Documentation/CommandForm/radio-group-field.md b/Documentation/CommandForm/radio-group-field.md
index 0a07200..06a3bf0 100644
--- a/Documentation/CommandForm/radio-group-field.md
+++ b/Documentation/CommandForm/radio-group-field.md
@@ -5,7 +5,7 @@
 ## Usage
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { RadioGroupField } from '@cratis/components/CommandForm';
 
 const sizeOptions = [
@@ -14,7 +14,7 @@ const sizeOptions = [
     { id: 'large', label: 'Large' },
 ];
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <RadioGroupField<MyCommand>
         value={c => c.size}
         options={sizeOptions}
diff --git a/Documentation/CommandForm/slider-field.md b/Documentation/CommandForm/slider-field.md
index da9f5b4..0dd8fad 100644
--- a/Documentation/CommandForm/slider-field.md
+++ b/Documentation/CommandForm/slider-field.md
@@ -5,10 +5,10 @@
 ## Usage
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { SliderField } from '@cratis/components/CommandForm';
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <SliderField<MyCommand> value={c => c.volume} min={0} max={100} step={5} />
     <SliderField<MyCommand> value={c => c.experience} min={0} max={50} />
 </CommandDialog>
diff --git a/Documentation/CommandForm/text-area-field.md b/Documentation/CommandForm/text-area-field.md
index 785f1d8..7676094 100644
--- a/Documentation/CommandForm/text-area-field.md
+++ b/Documentation/CommandForm/text-area-field.md
@@ -5,10 +5,10 @@
 ## Usage
 
 ```tsx
-import { CommandDialog } from '@cratis/components';
+import { CommandDialog } from '@cratis/components/CommandDialog';
 import { TextAreaField } from '@cratis/components/CommandForm';
 
-<CommandDialog command={MyCommand} visible={visible} onHide={() => setVisible(false)}>
+<CommandDialog command={MyCommand} visible={visible} onCancel={() => setVisible(false)}>
     <TextAreaField<MyCommand> value={c => c.description} placeholder="Enter a description" rows={4} />
     <TextAreaField<MyCommand> value={c => c.notes} rows={3} />
 </CommandDialog>
diff --git a/Documentation/Common/error-boundary.md b/Documentation/Common/error-boundary.md
index 64d59f6..f92ba23 100644
--- a/Documentation/Common/error-boundary.md
+++ b/Documentation/Common/error-boundary.md
@@ -12,12 +12,11 @@ ErrorBoundary catches JavaScript errors in component trees and displays a fallba
 - Displays user-friendly error message
 - Prevents application crash
 - Can be nested at different levels
-- Optional custom fallback UI
 
 ## Basic Usage
 
 ```typescript
-import { ErrorBoundary } from '@cratis/components';
+import { ErrorBoundary } from '@cratis/components/Common';
 
 function App() {
     return (
@@ -28,26 +27,9 @@ function App() {
 }
 ```
 
-## With Custom Fallback
-
-```typescript
-const CustomError = ({ error }) => (
-    <div className="error-container">
-        <h2>Oops! Something went wrong.</h2>
-        <p>{error.message}</p>
-        <button onClick={() => window.location.reload()}>Reload</button>
-    </div>
-);
-
-<ErrorBoundary fallback={CustomError}>
-    <MyComponent />
-</ErrorBoundary>
-```
-
 ## Props
 
 - `children`: Components to protect with error boundary
-- `fallback`: Custom error display component (optional)
 
 ## Error Information
 
@@ -100,42 +82,13 @@ function Dashboard() {
 ```typescript
 function DataTable() {
     return (
-        <ErrorBoundary fallback={TableError}>
+        <ErrorBoundary>
             <ComplexTable data={data} />
         </ErrorBoundary>
     );
 }
 ```
 
-## Advanced Example
-
-```typescript
-const ErrorFallback = ({ error, errorInfo, reset }) => (
-    <div className="error-boundary-fallback">
-        <div className="error-icon">
-            <i className="pi pi-exclamation-triangle" />
-        </div>
-        
-        <h2>Something went wrong</h2>
-        
-        <details className="error-details">
-            <summary>Error Details</summary>
-            <pre>{error.message}</pre>
-            <pre>{errorInfo.componentStack}</pre>
-        </details>
-        
-        <div className="error-actions">
-            <button onClick={reset}>Try Again</button>
-            <button onClick={() => window.location.href = '/'}>Go Home</button>
-        </div>
-    </div>
-);
-
-<ErrorBoundary fallback={ErrorFallback}>
-    <App />
-</ErrorBoundary>
-```
-
 ## Error Logging
 
 Integrate with logging services:
@@ -173,37 +126,18 @@ function RetryErrorBoundary({ children }) {
         setRetryCount(count => count + 1);
     };
     
+    // Bump `retryCount` to remount the boundary and re-render its children.
     return (
-        <ErrorBoundary 
-            key={retryCount}
-            fallback={({ error }) => (
-                <div>
-                    <p>Error: {error.message}</p>
-                    <button onClick={handleRetry}>Retry</button>
-                </div>
-            )}
-        >
-            {children}
-        </ErrorBoundary>
+        <div>
+            <button onClick={handleRetry}>Retry</button>
+            <ErrorBoundary key={retryCount}>
+                {children}
+            </ErrorBoundary>
+        </div>
     );
 }
 ```
 
-### Fallback Content
-
-```typescript
-<ErrorBoundary 
-    fallback={() => (
-        <div className="fallback-content">
-            <h3>This section is temporarily unavailable</h3>
-            <p>Please try refreshing the page or check back later.</p>
-        </div>
-    )}
->
-    <OptionalFeature />
-</ErrorBoundary>
-```
-
 ## What Errors Are Caught
 
 ErrorBoundary catches:
diff --git a/Documentation/Common/form-element.md b/Documentation/Common/form-element.md
index 37c46bc..789bc37 100644
--- a/Documentation/Common/form-element.md
+++ b/Documentation/Common/form-element.md
@@ -22,7 +22,7 @@ FormElement is a structural primitive — it lays out an icon addon and a child
 ## Basic Usage
 
 ```tsx
-import { FormElement } from '@cratis/components';
+import { FormElement } from '@cratis/components/Common';
 import { InputText } from 'primereact/inputtext';
 
 function MyForm() {
diff --git a/Documentation/Common/icon.md b/Documentation/Common/icon.md
index d2e1ccd..5699c0b 100644
--- a/Documentation/Common/icon.md
+++ b/Documentation/Common/icon.md
@@ -50,15 +50,15 @@ function MyToolbar() {
     return (
         <Toolbar>
             {/* String — existing usage unchanged */}
-            <ToolbarButton icon='pi pi-arrow-up-left' tooltip='Select' />
+            <ToolbarButton icon='pi pi-arrow-up-left' title='Select' />
 
             {/* ReactNode — third-party icon component */}
-            <ToolbarButton icon={<FaPencil />} tooltip='Draw' />
+            <ToolbarButton icon={<FaPencil />} title='Draw' />
 
             {/* ReactNode — fan-out trigger */}
             <ToolbarFanOutItem icon={<FaShapes />} tooltip='Shapes'>
-                <ToolbarButton icon='pi pi-stop' tooltip='Rectangle' />
-                <ToolbarButton icon='pi pi-circle' tooltip='Circle' />
+                <ToolbarButton icon='pi pi-stop' title='Rectangle' />
+                <ToolbarButton icon='pi pi-circle' title='Circle' />
             </ToolbarFanOutItem>
         </Toolbar>
     );
diff --git a/Documentation/Common/page.md b/Documentation/Common/page.md
index 5a88d98..a0faeee 100644
--- a/Documentation/Common/page.md
+++ b/Documentation/Common/page.md
@@ -17,7 +17,7 @@ The Page component provides a consistent layout structure with a title and conte
 ## Basic Usage
 
 ```typescript
-import { Page } from '@cratis/components';
+import { Page } from '@cratis/components/Common';
 
 function MyPage() {
     return (
diff --git a/Documentation/DataPage/details-panel.md b/Documentation/DataPage/details-panel.md
index 8b15d29..89d2f85 100644
--- a/Documentation/DataPage/details-panel.md
+++ b/Documentation/DataPage/details-panel.md
@@ -6,7 +6,7 @@ The details panel displays detailed information about the selected row in a resi
 
 ## Enabling Details Panel
 
-Provide a `DetailsComponent` prop to enable the details panel:
+Provide a `detailsComponent` prop to enable the details panel:
 
 ```typescript
 const ProductDetails = ({ item }) => (
@@ -26,8 +26,7 @@ const ProductDetails = ({ item }) => (
     title="Products"
     query={ProductsQuery}
     emptyMessage="No products"
-    DetailsComponent={ProductDetails}
-    detailsTitle="Product Details"
+    detailsComponent={ProductDetails}
 >
     {/* MenuItems and Columns */}
 </DataPage>
@@ -102,31 +101,14 @@ const OrderDetails = ({ item }) => {
 
 ## Panel Layout
 
-Control the initial size split between the table and details:
+Wire the details component into the page:
 
 ```typescript
 <DataPage
     title="Orders"
     query={OrdersQuery}
     emptyMessage="No orders"
-    DetailsComponent={OrderDetails}
-    detailsTitle="Order Details"
-    initialSizes={[60, 40]}  // Table: 60%, Details: 40%
->
-    {/* ... */}
-</DataPage>
-```
-
-## Custom Details Title
-
-Set a custom title for the details panel:
-
-```typescript
-<DataPage
-    DetailsComponent={ProductDetails}
-    detailsTitle="Product Information"
-    // Or use a function for dynamic titles
-    detailsTitle={(item) => `Product: ${item.name}`}
+    detailsComponent={OrderDetails}
 >
     {/* ... */}
 </DataPage>
@@ -174,32 +156,6 @@ The details panel is resizable by default using Allotment. Users can drag the di
 
 To disable resizing, you would need to wrap the DataPage or use custom layout.
 
-### Remember Size
-
-Store the user's preferred size:
-
-```typescript
-const [sizes, setSizes] = useState([60, 40]);
-
-useEffect(() => {
-    const saved = localStorage.getItem('dataPanelSizes');
-    if (saved) {
-        setSizes(JSON.parse(saved));
-    }
-}, []);
-
-const handleSizeChange = (newSizes) => {
-    setSizes(newSizes);
-    localStorage.setItem('dataPanelSizes', JSON.stringify(newSizes));
-};
-
-<DataPage
-    initialSizes={sizes}
-    // Note: You may need to handle this through Allotment's onChange
-    // ... other props
-/>
-```
-
 ## No Selection State
 
 When no row is selected, the details panel is hidden automatically.
diff --git a/Documentation/DataPage/index.md b/Documentation/DataPage/index.md
index 2820020..44f48bd 100644
--- a/Documentation/DataPage/index.md
+++ b/Documentation/DataPage/index.md
@@ -17,42 +17,68 @@ DataPage combines a page header, data table, menu bar, and optional detail view
 
 ## Basic Usage
 
-```typescript
-import { DataPage, MenuItem, MenuItems, Columns } from '@cratis/components';
+Declare the columns and menu actions with the compound `DataPage.Columns` and `DataPage.MenuItems` children, imported alongside `DataPage` from `@cratis/components/DataPage`:
+
+```tsx
+import { DataPage, MenuItem } from '@cratis/components/DataPage';
 import { Column } from 'primereact/column';
-import { MyQuery } from './queries';
+import { FaPlus, FaPencil } from 'react-icons/fa';
+import { AllAuthors } from './queries';   // generated query proxy
 
-function MyDataPage() {
+function Authors() {
     return (
         <DataPage
-            title="My Data"
-            query={MyQuery}
-            emptyMessage="No data found"
-        >
-            <MenuItems>
-                <MenuItem 
-                    label="Create" 
-                    icon="pi pi-plus"
-                    command={() => handleCreate()}
-                />
-                <MenuItem 
-                    label="Edit" 
-                    icon="pi pi-pencil"
-                    disableOnUnselected={true}
-                    command={() => handleEdit()}
-                />
-            </MenuItems>
-            
-            <Columns>
-                <Column field="name" header="Name" />
-                <Column field="description" header="Description" />
-                <Column field="createdAt" header="Created" />
-            </Columns>
+            title="Authors"
+            query={AllAuthors}
+            emptyMessage="No authors found">
+            <DataPage.MenuItems>
+                <MenuItem label="Add" icon={FaPlus} command={() => handleAdd()} />
+                <MenuItem label="Edit" icon={FaPencil} disableOnUnselected command={() => handleEdit()} />
+            </DataPage.MenuItems>
+            <DataPage.Columns>
+                <Column field="name" header="Name" sortable />
+                <Column field="id" header="Id" />
+            </DataPage.Columns>
         </DataPage>
     );
 }
 ```
 
+`disableOnUnselected` greys the menu item out until a row is selected — wire your edit and remove actions to it so they only fire on a selection.
+
+## List-and-detail with a details panel
+
+Pass a `detailsComponent` and `DataPage` adds a resizable split: the table on the left, your component on the right, shown only when a row is selected. The component receives the selected row as `item` (the `IDetailsComponentProps<T>` contract):
+
+```tsx
+import { DataPage } from '@cratis/components/DataPage';
+import { Column } from 'primereact/column';
+import { AllAuthorsWithBooks } from './queries';
+
+const AuthorDetails = ({ item }) => (
+    <div className="p-4">
+        <h2>{item.name}</h2>
+        <ul>{item.books.map(b => <li key={String(b.id)}>{b.title}</li>)}</ul>
+    </div>
+);
+
+function Authors() {
+    return (
+        <DataPage
+            title="Authors"
+            query={AllAuthorsWithBooks}
+            emptyMessage="No authors yet"
+            detailsComponent={AuthorDetails}>
+            <DataPage.Columns>
+                <Column field="name" header="Name" sortable />
+            </DataPage.Columns>
+        </DataPage>
+    );
+}
+```
+
+Selection is managed for you; to drive it yourself, pass `selection` and `onSelectionChange`.
+
 ## Props
 
 ### Required Props
diff --git a/Documentation/DataPage/menu-items.md b/Documentation/DataPage/menu-items.md
index 9887b2b..59b4be3 100644
--- a/Documentation/DataPage/menu-items.md
+++ b/Documentation/DataPage/menu-items.md
@@ -6,17 +6,21 @@ The `MenuItems` component defines the action menu for a DataPage.
 
 ## Basic Usage
 
-```typescript
+```tsx
+import { DataPage, MenuItem } from '@cratis/components/DataPage';
+import { Column } from 'primereact/column';
+import { FaPlus, FaPencil, FaTrash } from 'react-icons/fa';
+
 <DataPage title="Products" query={ProductsQuery} emptyMessage="No products">
-    <MenuItems>
-        <MenuItem label="Create Product" icon="pi pi-plus" command={handleCreate} />
-        <MenuItem label="Edit" icon="pi pi-pencil" disableOnUnselected command={handleEdit} />
-        <MenuItem label="Delete" icon="pi pi-trash" disableOnUnselected command={handleDelete} />
-    </MenuItems>
-    
-    <Columns>
+    <DataPage.MenuItems>
+        <MenuItem label="Create Product" icon={FaPlus} command={handleCreate} />
+        <MenuItem label="Edit" icon={FaPencil} disableOnUnselected command={handleEdit} />
+        <MenuItem label="Delete" icon={FaTrash} disableOnUnselected command={handleDelete} />
+    </DataPage.MenuItems>
+
+    <DataPage.Columns>
         {/* ... columns */}
-    </Columns>
+    </DataPage.Columns>
 </DataPage>
 ```
 
@@ -29,7 +33,7 @@ The `MenuItems` component defines the action menu for a DataPage.
 
 ### Optional Props
 
-- `icon`: Icon component or CSS class
+- `icon`: Icon **component type** (e.g. a `react-icons` icon like `FaPlus`) — DataPage renders it as `<Icon />`, so pass the component reference, not a CSS-class string or a JSX element
 - `disableOnUnselected`: Disable when no row is selected (default: false)
 - All PrimeReact MenuItem props are supported
 
@@ -37,65 +41,66 @@ The `MenuItems` component defines the action menu for a DataPage.
 
 Use `disableOnUnselected` to disable actions that require a selection:
 
-```typescript
-<MenuItems>
+```tsx
+import { FaPlus, FaPencil, FaTrash, FaArchive } from 'react-icons/fa';
+
+<DataPage.MenuItems>
     {/* Always enabled */}
-    <MenuItem 
-        label="Create New" 
-        icon="pi pi-plus"
+    <MenuItem
+        label="Create New"
+        icon={FaPlus}
         command={() => setShowCreateDialog(true)}
     />
-    
+
     {/* Disabled when no selection */}
-    <MenuItem 
-        label="Edit Selected" 
-        icon="pi pi-pencil"
+    <MenuItem
+        label="Edit Selected"
+        icon={FaPencil}
         disableOnUnselected={true}
         command={() => setShowEditDialog(true)}
     />
-    
-    <MenuItem 
-        label="Delete Selected" 
-        icon="pi pi-trash"
+
+    <MenuItem
+        label="Delete Selected"
+        icon={FaTrash}
         disableOnUnselected={true}
         command={() => handleDelete()}
     />
-    
+
     {/* Conditional actions */}
-    <MenuItem 
-        label="Archive" 
-        icon="pi pi-archive"
+    <MenuItem
+        label="Archive"
+        icon={FaArchive}
         disableOnUnselected={true}
         command={() => handleArchive()}
     />
-</MenuItems>
+</DataPage.MenuItems>
 ```
 
 ## Icons
 
-### PrimeReact Icons
-
-```typescript
-<MenuItem label="Save" icon="pi pi-save" command={handleSave} />
-<MenuItem label="Download" icon="pi pi-download" command={handleDownload} />
-<MenuItem label="Upload" icon="pi pi-upload" command={handleUpload} />
-```
-
-### React Icons
+The `icon` prop takes a **component type** — DataPage renders it internally as `<Icon />`. Pass the
+component reference (for example, an icon from [`react-icons`](https://react-icons.github.io/react-icons/)),
+not a string CSS class and not an already-rendered JSX element.
 
-```typescript
-import { FaPlus, FaEdit, FaTrash } from 'react-icons/fa';
+```tsx
+import { FaSave, FaDownload, FaUpload } from 'react-icons/fa';
 
-<MenuItem label="Create" icon={<FaPlus />} command={handleCreate} />
-<MenuItem label="Edit" icon={<FaEdit />} command={handleEdit} />
-<MenuItem label="Delete" icon={<FaTrash />} command={handleDelete} />
+<MenuItem label="Save" icon={FaSave} command={handleSave} />
+<MenuItem label="Download" icon={FaDownload} command={handleDownload} />
+<MenuItem label="Upload" icon={FaUpload} command={handleUpload} />
 ```
 
+:::caution
+Don't pass `icon="pi pi-save"` (a PrimeIcons CSS class) or `icon={<FaSave />}` (a JSX element).
+DataPage instantiates the icon itself, so the prop must be the component type: `icon={FaSave}`.
+:::
+
 ## Accessing Selected Item
 
 The selected item is available through the DataPage context:
 
-```typescript
+```tsx
 const handleEdit = () => {
     // Access selected item from parent component state
     if (selectedItem) {
@@ -109,40 +114,44 @@ const handleEdit = () => {
 
 Use PrimeReact MenuItem features for separators:
 
-```typescript
-<MenuItems>
-    <MenuItem label="New" icon="pi pi-plus" command={handleNew} />
+```tsx
+import { FaPlus, FaPencil, FaTrash, FaFileExport } from 'react-icons/fa';
+
+<DataPage.MenuItems>
+    <MenuItem label="New" icon={FaPlus} command={handleNew} />
     <MenuItem separator />
-    <MenuItem label="Edit" icon="pi pi-pencil" disableOnUnselected command={handleEdit} />
-    <MenuItem label="Delete" icon="pi pi-trash" disableOnUnselected command={handleDelete} />
+    <MenuItem label="Edit" icon={FaPencil} disableOnUnselected command={handleEdit} />
+    <MenuItem label="Delete" icon={FaTrash} disableOnUnselected command={handleDelete} />
     <MenuItem separator />
-    <MenuItem label="Export" icon="pi pi-file-export" command={handleExport} />
-</MenuItems>
+    <MenuItem label="Export" icon={FaFileExport} command={handleExport} />
+</DataPage.MenuItems>
 ```
 
 ## Dropdown Menus
 
 Create nested menu structures:
 
-```typescript
-<MenuItems>
-    <MenuItem label="File" icon="pi pi-file">
-        <MenuItem label="New" icon="pi pi-plus" command={handleNew} />
-        <MenuItem label="Open" icon="pi pi-folder-open" command={handleOpen} />
+```tsx
+import { FaFile, FaPlus, FaFolderOpen, FaPencil, FaCopy, FaClipboard } from 'react-icons/fa';
+
+<DataPage.MenuItems>
+    <MenuItem label="File" icon={FaFile}>
+        <MenuItem label="New" icon={FaPlus} command={handleNew} />
+        <MenuItem label="Open" icon={FaFolderOpen} command={handleOpen} />
     </MenuItem>
-    
-    <MenuItem label="Edit" icon="pi pi-pencil">
-        <MenuItem label="Copy" icon="pi pi-copy" command={handleCopy} />
-        <MenuItem label="Paste" icon="pi pi-clipboard" command={handlePaste} />
+
+    <MenuItem label="Edit" icon={FaPencil}>
+        <MenuItem label="Copy" icon={FaCopy} command={handleCopy} />
+        <MenuItem label="Paste" icon={FaClipboard} command={handlePaste} />
     </MenuItem>
-</MenuItems>
+</DataPage.MenuItems>
 ```
 
 ## Action Handlers
 
 ### Simple Actions
 
-```typescript
+```tsx
 const handleCreate = () => {
     setShowCreateDialog(true);
 };
@@ -150,10 +159,10 @@ const handleCreate = () => {
 
 ### Actions with Selected Item
 
-```typescript
+```tsx
 const handleEdit = () => {
     if (!selectedItem) return;
-    
+
     setEditItem(selectedItem);
     setShowEditDialog(true);
 };
@@ -161,10 +170,10 @@ const handleEdit = () => {
 
 ### Confirmation Dialogs
 
-```typescript
+```tsx
 const handleDelete = () => {
     if (!selectedItem) return;
-    
+
     setDeleteItem(selectedItem);
     setShowConfirmDialog(true);
 };
@@ -172,10 +181,10 @@ const handleDelete = () => {
 
 ### Async Actions
 
-```typescript
+```tsx
 const handleArchive = async () => {
     if (!selectedItem) return;
-    
+
     try {
         await archiveItem(selectedItem.id);
         // Refresh data
diff --git a/Documentation/DataTables/data-table-for-observable-query.md b/Documentation/DataTables/data-table-for-observable-query.md
index 44b95d0..fd7fb11 100644
--- a/Documentation/DataTables/data-table-for-observable-query.md
+++ b/Documentation/DataTables/data-table-for-observable-query.md
@@ -18,7 +18,7 @@ DataTableForObservableQuery displays data from observable queries that automatic
 ## Basic Usage
 
 ```typescript
-import { DataTableForObservableQuery } from '@cratis/components';
+import { DataTableForObservableQuery } from '@cratis/components/DataTables';
 import { Column } from 'primereact/column';
 import { MyObservableQuery } from './queries';
 
diff --git a/Documentation/DataTables/data-table-for-query.md b/Documentation/DataTables/data-table-for-query.md
index b8c8211..bb5a9a1 100644
--- a/Documentation/DataTables/data-table-for-query.md
+++ b/Documentation/DataTables/data-table-for-query.md
@@ -18,7 +18,7 @@ DataTableForQuery provides a data table specifically designed for `IQueryFor` qu
 ## Basic Usage
 
 ```typescript
-import { DataTableForQuery } from '@cratis/components';
+import { DataTableForQuery } from '@cratis/components/DataTables';
 import { Column } from 'primereact/column';
 import { MyQuery } from './queries';
 
diff --git a/Documentation/Dialogs/busy-indicator-dialog.md b/Documentation/Dialogs/busy-indicator-dialog.md
index 93e74c6..a97050e 100644
--- a/Documentation/Dialogs/busy-indicator-dialog.md
+++ b/Documentation/Dialogs/busy-indicator-dialog.md
@@ -13,42 +13,58 @@ BusyIndicatorDialog displays a loading indicator while performing asynchronous o
 - Non-dismissible (no close button)
 - Centered layout
 
+## Host-rendered
+
+`BusyIndicatorDialog` is rendered by the dialog host, not instantiated directly. Register it once with `DialogComponents`, then show and hide it with the `useBusyIndicator` hook. The host threads the `title` and `message` from your request into the rendered modal.
+
 ## Basic Usage
 
+Register the dialog component near the root of your app:
+
 ```typescript
-import { BusyIndicatorDialog } from '@cratis/components';
+import { BusyIndicatorDialog } from '@cratis/components/Dialogs';
+import { DialogComponents } from '@cratis/arc.react/dialogs';
+
+export const App = () => (
+    <DialogComponents busyIndicator={BusyIndicatorDialog}>
+        <YourApp />
+    </DialogComponents>
+);
+```
+
+Show the indicator around a long-running operation and close it when done:
+
+```typescript
+import { useBusyIndicator } from '@cratis/arc.react/dialogs';
 
 function MyComponent() {
-    const [processing, setProcessing] = useState(false);
+    const [showBusy, closeBusy] = useBusyIndicator(
+        'Processing',
+        'Please wait while we process your request...'
+    );
 
     const handleAsyncOperation = async () => {
-        setProcessing(true);
+        showBusy();
         try {
             await performOperation();
         } finally {
-            setProcessing(false);
+            closeBusy();
         }
     };
 
-    return (
-        <>
-            <button onClick={handleAsyncOperation}>Start Operation</button>
-            {processing && (
-                <BusyIndicatorDialog
-                    title="Processing"
-                    message="Please wait while we process your request..."
-                />
-            )}
-        </>
-    );
+    return <button onClick={handleAsyncOperation}>Start Operation</button>;
 }
 ```
 
-## Props
+## Request
+
+The `BusyIndicatorDialogRequest` the host threads into the dialog carries:
 
 - `title`: Dialog header text
 - `message`: Message to display below the spinner
 
+`useBusyIndicator(title?, message?)` returns `[showBusy, closeBusy]` — call `showBusy()` to display the indicator and `closeBusy()` to dismiss it.
+
 ## Use Cases
 
 - File uploads
diff --git a/Documentation/Dialogs/confirmation-dialog.md b/Documentation/Dialogs/confirmation-dialog.md
index f1421d9..88bbb09 100644
--- a/Documentation/Dialogs/confirmation-dialog.md
+++ b/Documentation/Dialogs/confirmation-dialog.md
@@ -8,95 +8,113 @@ ConfirmationDialog prompts users to confirm or cancel an action.
 
 ## Key Features
 
-- Confirm and cancel buttons
-- Custom labels and icons
-- Callback handlers
+- Built-in confirm and cancel buttons
+- Configurable button set (`DialogButtons`)
+- Host-rendered — triggered with a hook, awaited as a `Promise<DialogResult>`
 - Modal behavior
 
+## Host-rendered
+
+`ConfirmationDialog` is rendered by the dialog host, not instantiated directly. Register it once with `DialogComponents`, then trigger it from anywhere with the `useConfirmationDialog` hook. The request carries the `title`, `message`, and `buttons` — there are no per-instance label/icon/callback props.
+
 ## Basic Usage
 
+Register the dialog component near the root of your app:
+
 ```typescript
-import { ConfirmationDialog } from '@cratis/components';
+import { ConfirmationDialog } from '@cratis/components/Dialogs';
+import { DialogComponents } from '@cratis/arc.react/dialogs';
+
+export const App = () => (
+    <DialogComponents confirmation={ConfirmationDialog}>
+        <YourApp />
+    </DialogComponents>
+);
+```
 
-function MyComponent() {
-    const [showConfirm, setShowConfirm] = useState(false);
+Trigger it from a component and await the result:
 
-    const handleDelete = () => {
-        setShowConfirm(true);
-    };
+```typescript
+import { useConfirmationDialog, DialogButtons, DialogResult } from '@cratis/arc.react/dialogs';
 
-    const handleConfirm = () => {
-        // Perform the action
-        deleteItem();
-        setShowConfirm(false);
+function MyComponent() {
+    const [showConfirm] = useConfirmationDialog(
+        'Confirm Delete',
+        'Are you sure you want to delete this item?',
+        DialogButtons.YesNo
+    );
+
+    const handleDelete = async () => {
+        const result = await showConfirm();
+        if (result === DialogResult.Yes) {
+            deleteItem();
+        }
     };
 
-    return (
-        <>
-            <button onClick={handleDelete}>Delete</button>
-            {showConfirm && (
-                <ConfirmationDialog
-                    title="Confirm Delete"
-                    message="Are you sure you want to delete this item?"
-                    confirmLabel="Delete"
-                    cancelLabel="Cancel"
-                    onConfirm={handleConfirm}
-                    onCancel={() => setShowConfirm(false)}
-                />
-            )}
-        </>
-    );
+    return <button onClick={handleDelete}>Delete</button>;
 }
 ```
 
-## Props
+## Request
+
+The `ConfirmationDialogRequest` the host threads into the dialog carries:
 
 - `title`: Dialog header text
 - `message`: Confirmation message
-- `confirmLabel`: Text for confirm button (default: "Yes")
-- `cancelLabel`: Text for cancel button (default: "No")
-- `confirmIcon`: Icon for confirm button
-- `cancelIcon`: Icon for cancel button
-- `onConfirm`: Callback when confirmed
-- `onCancel`: Callback when cancelled
+- `buttons`: A `DialogButtons` value (`Ok`, `OkCancel`, `YesNo`, or `YesNoCancel`)
+
+`useConfirmationDialog(title?, message?, buttons?)` returns `[showConfirm]`, where `showConfirm()` returns a `Promise<DialogResult>` resolving to the button the user picked.
 
 ## Examples
 
-### Delete Confirmation
+### Delete confirmation
 
 ```typescript
-<ConfirmationDialog
-    title="Delete Item"
-    message="This action cannot be undone. Are you sure?"
-    confirmLabel="Delete"
-    cancelLabel="Keep"
-    onConfirm={handleDelete}
-    onCancel={handleCancel}
-/>
+const [showConfirm] = useConfirmationDialog(
+    'Delete Item',
+    'This action cannot be undone. Are you sure?',
+    DialogButtons.YesNo
+);
+
+const onDelete = async () => {
+    if (await showConfirm() === DialogResult.Yes) {
+        deleteItem();
+    }
+};
 ```
 
-### Save Changes
+### Save changes
 
 ```typescript
-<ConfirmationDialog
-    title="Unsaved Changes"
-    message="You have unsaved changes. Do you want to save them?"
-    confirmLabel="Save"
-    cancelLabel="Discard"
-    onConfirm={handleSave}
-    onCancel={handleDiscard}
-/>
+const [showConfirm] = useConfirmationDialog(
+    'Unsaved Changes',
+    'You have unsaved changes. Do you want to save them?',
+    DialogButtons.YesNoCancel
+);
+
+const onLeave = async () => {
+    const result = await showConfirm();
+    if (result === DialogResult.Yes) {
+        await save();
+    } else if (result === DialogResult.No) {
+        discard();
+    }
+    // DialogResult.Cancelled keeps the user on the page
+};
 ```
 
-### Proceed with Action
+### Proceed with action
 
 ```typescript
-<ConfirmationDialog
-    title="Confirm Action"
-    message="This will affect all users. Continue?"
-    confirmLabel="Continue"
-    cancelLabel="Cancel"
-    onConfirm={handleProceed}
-    onCancel={handleCancel}
-/>
+const [showConfirm] = useConfirmationDialog(
+    'Confirm Action',
+    'This will affect all users. Continue?',
+    DialogButtons.OkCancel
+);
+
+const onProceed = async () => {
+    if (await showConfirm() === DialogResult.Ok) {
+        proceed();
+    }
+};
 ```
diff --git a/Documentation/Dropdown/index.md b/Documentation/Dropdown/index.md
index cc080e6..a50f24c 100644
--- a/Documentation/Dropdown/index.md
+++ b/Documentation/Dropdown/index.md
@@ -17,7 +17,7 @@ Dropdown provides a select component that correctly appears above dialogs and ot
 ## Quick Start
 
 ```typescript
-import { Dropdown } from '@cratis/components';
+import { Dropdown } from '@cratis/components/Dropdown';
 
 function MyForm() {
     const [selectedCity, setSelectedCity] = useState(null);
@@ -233,7 +233,7 @@ Integrate with form validation:
 ## Complete Form Example
 
 ```typescript
-import { Dropdown } from '@cratis/components';
+import { Dropdown } from '@cratis/components/Dropdown';
 import { useState } from 'react';
 
 interface FormData {
diff --git a/Documentation/Filter/index.md b/Documentation/Filter/index.md
index 26f9d16..a8251b9 100644
--- a/Documentation/Filter/index.md
+++ b/Documentation/Filter/index.md
@@ -257,7 +257,7 @@ The hook re-syncs state when the `filters` array reference changes — existing
 | `values` | `FilterValue[]` | ✓ | Raw data values used to compute the histogram |
 | `min` | `number` | ✓ | Lower bound of the full range |
 | `max` | `number` | ✓ | Upper bound of the full range |
-| `buckets` | `number` | ✓ | Number of histogram bars |
+| `buckets` | `number` | | Number of histogram bars (default `20`) |
 | `selectedRange` | `[number, number] \| null` | ✓ | Currently selected range, or `null` for none |
 | `onChange` | `(range: [number, number] \| null) => void` | ✓ | Called when the range changes |
 
@@ -270,8 +270,10 @@ import { FilterPanel, FilterEditor, useFilterState } from '@cratis/components/Fi
 import type { FilterDefinition } from '@cratis/components/Filter';
 ```
 
-It is also re-exported from the package root:
+From the package root, the module is available under the `Filter` namespace:
 
 ```tsx
-import { FilterPanel, FilterEditor, useFilterState } from '@cratis/components';
+import { Filter } from '@cratis/components';
+
+// Use as Filter.FilterPanel, Filter.FilterEditor, Filter.useFilterState
 ```
diff --git a/Documentation/ObjectContentEditor/index.md b/Documentation/ObjectContentEditor/index.md
index 13902c4..3d7bd4e 100644
--- a/Documentation/ObjectContentEditor/index.md
+++ b/Documentation/ObjectContentEditor/index.md
@@ -20,7 +20,7 @@ ObjectContentEditor provides a structured view of JSON objects with breadcrumb n
 ## Quick Start
 
 ```typescript
-import { ObjectContentEditor } from '@cratis/components';
+import { ObjectContentEditor } from '@cratis/components/ObjectContentEditor';
 import { JsonSchema } from '@cratis/components/types';
 
 function MyObjectViewer() {
@@ -105,7 +105,7 @@ Validation errors are displayed inline beneath each field using PrimeReact's `p-
 ### Edit Mode Example
 
 ```typescript
-import { ObjectContentEditor } from '@cratis/components';
+import { ObjectContentEditor } from '@cratis/components/ObjectContentEditor';
 import { useState } from 'react';
 
 function EditableProduct() {
@@ -194,7 +194,7 @@ Click back arrow or breadcrumb
 ## Complete Example
 
 ```typescript
-import { ObjectContentEditor } from '@cratis/components';
+import { ObjectContentEditor } from '@cratis/components/ObjectContentEditor';
 
 function ProductViewer() {
     const product = {
diff --git a/Documentation/ObjectNavigationalBar/index.md b/Documentation/ObjectNavigationalBar/index.md
index cde075a..6d2d834 100644
--- a/Documentation/ObjectNavigationalBar/index.md
+++ b/Documentation/ObjectNavigationalBar/index.md
@@ -18,7 +18,7 @@ ObjectNavigationalBar displays the current navigation path and allows users to j
 ## Quick Start
 
 ```typescript
-import { ObjectNavigationalBar } from '@cratis/components';
+import { ObjectNavigationalBar } from '@cratis/components/ObjectNavigationalBar';
 
 function MyNavigator() {
     const [path, setPath] = useState<string[]>(['profile', 'address']);
@@ -106,7 +106,7 @@ city (index: 3)  ← current location
 ## Complete Example
 
 ```typescript
-import { ObjectNavigationalBar } from '@cratis/components';
+import { ObjectNavigationalBar } from '@cratis/components/ObjectNavigationalBar';
 import { useState } from 'react';
 
 interface DataNode {
diff --git a/Documentation/PivotViewer/configuration.md b/Documentation/PivotViewer/configuration.md
index 1fc02b0..a908566 100644
--- a/Documentation/PivotViewer/configuration.md
+++ b/Documentation/PivotViewer/configuration.md
@@ -6,15 +6,15 @@
 
 - `data`: Array of items to display
 - `dimensions`: Array of dimension configurations for grouping
-- `filters`: Array of filter configurations
 - `cardRenderer`: Function to render card view for an item
-- `detailRenderer`: Function to render detail view for an item
-- `getItemId`: Function to extract unique ID from an item
 
 ### Optional Props
 
+- `filters`: Array of filter configurations
+- `detailRenderer`: Function to render detail view for an item
+- `getItemId`: Function to extract unique ID from an item
 - `defaultDimensionKey`: Initial dimension to group by
-- `searchFields`: Array of field names to include in text search
+- `searchFields`: Array of accessor functions returning the values to include in text search
 - `className`: CSS class for the container
 - `emptyContent`: React node to show when no data matches filters
 - `isLoading`: Show loading state
@@ -31,14 +31,14 @@
     cardRenderer={renderCard}
     detailRenderer={renderDetails}
     getItemId={(item) => item.id}
-    searchFields={['title', 'description', 'assignee']}
+    searchFields={[item => item.title, item => item.description, item => item.assignee]}
     className="my-pivot-viewer"
     emptyContent={<div>No items match your filters</div>}
     isLoading={isLoadingData}
     colors={{
-        primary: '#4CAF50',
-        background: '#1a1a1a',
-        surface: '#2d2d2d'
+        primaryColor: '#4CAF50',
+        surfaceGround: '#1a1a1a',
+        surfaceCard: '#2d2d2d'
     }}
 />
 ```
@@ -49,11 +49,11 @@ Customize the color scheme:
 
 ```typescript
 const customColors = {
-    primary: '#0066cc',        // Primary accent color
-    background: '#ffffff',     // Main background
-    surface: '#f5f5f5',       // Card backgrounds
-    text: '#333333',          // Text color
-    border: '#e0e0e0'         // Border color
+    primaryColor: '#0066cc',     // Primary accent color
+    surfaceGround: '#ffffff',    // Main background
+    surfaceCard: '#f5f5f5',      // Card backgrounds
+    textColor: '#333333',        // Text color
+    surfaceBorder: '#e0e0e0'     // Border color
 };
 
 <PivotViewer
@@ -103,11 +103,11 @@ Customize the message when filters return no results:
 
 ## Search Configuration
 
-Specify which fields should be searchable:
+Specify which fields should be searchable by passing accessor functions:
 
 ```typescript
 <PivotViewer
-    searchFields={['title', 'description', 'tags', 'author']}
+    searchFields={[item => item.title, item => item.description, item => item.tags, item => item.author]}
     // ... other props
 />
 ```
diff --git a/Documentation/PivotViewer/dimensions-and-filters.md b/Documentation/PivotViewer/dimensions-and-filters.md
index 093b8bc..9c83a35 100644
--- a/Documentation/PivotViewer/dimensions-and-filters.md
+++ b/Documentation/PivotViewer/dimensions-and-filters.md
@@ -10,7 +10,7 @@ Dimensions define how items can be grouped.
 {
     key: string;           // Unique identifier
     label: string;         // Display name
-    accessor: (item) => value;  // Function to extract grouping value
+    getValue: (item) => value;  // Function to extract grouping value
 }
 ```
 
@@ -21,22 +21,22 @@ const dimensions = [
     {
         key: 'status',
         label: 'Status',
-        accessor: (item) => item.status
+        getValue: (item) => item.status
     },
     {
         key: 'priority',
         label: 'Priority',
-        accessor: (item) => item.priority
+        getValue: (item) => item.priority
     },
     {
         key: 'assignee',
         label: 'Assigned To',
-        accessor: (item) => item.assignedTo
+        getValue: (item) => item.assignedTo
     },
     {
         key: 'date',
         label: 'Created Date',
-        accessor: (item) => {
+        getValue: (item) => {
             const date = new Date(item.createdAt);
             return `${date.getFullYear()}-${date.getMonth() + 1}`;
         }
@@ -60,8 +60,8 @@ Filters allow users to narrow down the dataset.
 {
     key: 'category',
     label: 'Category',
-    type: 'categorical',
-    accessor: (item) => item.category
+    type: 'string',
+    getValue: (item) => item.category
 }
 ```
 
@@ -71,10 +71,9 @@ Filters allow users to narrow down the dataset.
 {
     key: 'price',
     label: 'Price',
-    type: 'range',
-    accessor: (item) => item.price,
-    min: 0,
-    max: 1000
+    type: 'number',
+    getValue: (item) => item.price,
+    buckets: 20
 }
 ```
 
@@ -86,8 +85,8 @@ For properties that return arrays:
 {
     key: 'tags',
     label: 'Tags',
-    type: 'categorical',
-    accessor: (item) => item.tags  // Returns array of strings
+    type: 'string',
+    getValue: (item) => item.tags  // Returns array of strings
 }
 ```
 
@@ -109,17 +108,17 @@ const dimensions = [
     {
         key: 'status',
         label: 'Status',
-        accessor: (item: Task) => item.status
+        getValue: (item: Task) => item.status
     },
     {
         key: 'assignee',
         label: 'Assignee',
-        accessor: (item: Task) => item.assignee
+        getValue: (item: Task) => item.assignee
     },
     {
         key: 'priority-level',
         label: 'Priority Level',
-        accessor: (item: Task) => {
+        getValue: (item: Task) => {
             if (item.priority >= 8) return 'High';
             if (item.priority >= 5) return 'Medium';
             return 'Low';
@@ -131,36 +130,34 @@ const filters = [
     {
         key: 'status',
         label: 'Status',
-        type: 'categorical',
-        accessor: (item: Task) => item.status
+        type: 'string',
+        getValue: (item: Task) => item.status
     },
     {
         key: 'priority',
         label: 'Priority',
-        type: 'range',
-        accessor: (item: Task) => item.priority,
-        min: 0,
-        max: 10
+        type: 'number',
+        getValue: (item: Task) => item.priority,
+        buckets: 10
     },
     {
         key: 'estimatedHours',
         label: 'Estimated Hours',
-        type: 'range',
-        accessor: (item: Task) => item.estimatedHours,
-        min: 0,
-        max: 40
+        type: 'number',
+        getValue: (item: Task) => item.estimatedHours,
+        buckets: 20
     },
     {
         key: 'tags',
         label: 'Tags',
-        type: 'categorical',
-        accessor: (item: Task) => item.tags
+        type: 'string',
+        getValue: (item: Task) => item.tags
     },
     {
         key: 'assignee',
         label: 'Assigned To',
-        type: 'categorical',
-        accessor: (item: Task) => item.assignee
+        type: 'string',
+        getValue: (item: Task) => item.assignee
     }
 ];
 ```
@@ -173,7 +170,7 @@ Create dimensions based on computed values:
 {
     key: 'age-group',
     label: 'Age Group',
-    accessor: (item) => {
+    getValue: (item) => {
         const age = item.age;
         if (age < 18) return 'Under 18';
         if (age < 35) return '18-34';
@@ -189,12 +186,12 @@ Create dimensions based on computed values:
 {
     key: 'year',
     label: 'Year',
-    accessor: (item) => new Date(item.createdAt).getFullYear()
+    getValue: (item) => new Date(item.createdAt).getFullYear()
 },
 {
     key: 'month',
     label: 'Month',
-    accessor: (item) => {
+    getValue: (item) => {
         const date = new Date(item.createdAt);
         return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
     }
@@ -202,7 +199,7 @@ Create dimensions based on computed values:
 {
     key: 'quarter',
     label: 'Quarter',
-    accessor: (item) => {
+    getValue: (item) => {
         const date = new Date(item.createdAt);
         const quarter = Math.floor(date.getMonth() / 3) + 1;
         return `Q${quarter} ${date.getFullYear()}`;
diff --git a/Documentation/PivotViewer/index.md b/Documentation/PivotViewer/index.md
index e43e89d..ffabb21 100644
--- a/Documentation/PivotViewer/index.md
+++ b/Documentation/PivotViewer/index.md
@@ -20,7 +20,7 @@ PivotViewer enables users to explore and analyze collections of data items throu
 ## Quick Start
 
 ```typescript
-import { PivotViewer } from '@cratis/components';
+import { PivotViewer } from '@cratis/components/PivotViewer';
 
 interface Product {
     id: string;
@@ -31,11 +31,11 @@ interface Product {
 
 function ProductViewer() {
     const dimensions = [
-        { key: 'category', label: 'Category', accessor: (item: Product) => item.category }
+        { key: 'category', label: 'Category', getValue: (item: Product) => item.category }
     ];
 
     const filters = [
-        { key: 'category', label: 'Category', type: 'categorical', accessor: (item: Product) => item.category }
+        { key: 'category', label: 'Category', type: 'string', getValue: (item: Product) => item.category }
     ];
 
     return (
@@ -44,10 +44,10 @@ function ProductViewer() {
             dimensions={dimensions}
             filters={filters}
             defaultDimensionKey="category"
-            cardRenderer={(item) => <ProductCard product={item} />}
+            cardRenderer={(item) => ({ title: item.name, labels: ['Category'], values: [item.category] })}
             detailRenderer={(item) => <ProductDetails product={item} />}
             getItemId={(item) => item.id}
-            searchFields={['name', 'category']}
+            searchFields={[item => item.name, item => item.category]}
         />
     );
 }
diff --git a/Documentation/PivotViewer/performance.md b/Documentation/PivotViewer/performance.md
index 20e8724..f1e542a 100644
--- a/Documentation/PivotViewer/performance.md
+++ b/Documentation/PivotViewer/performance.md
@@ -58,7 +58,7 @@ Keep dimension and filter accessors simple:
 ```typescript
 {
     key: 'status',
-    accessor: (item) => item.status
+    getValue: (item) => item.status
 }
 ```
 
@@ -67,7 +67,7 @@ Keep dimension and filter accessors simple:
 ```typescript
 {
     key: 'status',
-    accessor: (item) => {
+    getValue: (item) => {
         // Complex computation on every filter
         return expensiveCalculation(item.data, item.metadata, item.relationships);
     }
@@ -76,18 +76,19 @@ Keep dimension and filter accessors simple:
 
 ### Memoize Renderers
 
-Use React.memo for card and detail renderers:
+The `cardRenderer` returns lightweight structured data (`{ title, labels?, values? }`), so keep it cheap. For the heavier `detailRenderer`, wrap the component in `React.memo`:
 
 ```typescript
-const TaskCard = React.memo(({ item }: { item: Task }) => (
-    <div className="task-card">
+const TaskDetails = React.memo(({ item }: { item: Task }) => (
+    <div className="task-details">
         <h4>{item.title}</h4>
         <p>{item.description}</p>
     </div>
 ));
 
 <PivotViewer
-    cardRenderer={(item) => <TaskCard item={item} />}
+    cardRenderer={(item) => ({ title: item.title, values: [item.description] })}
+    detailRenderer={(item) => <TaskDetails item={item} />}
     // ...
 />
 ```
@@ -134,7 +135,7 @@ Avoid creating new objects in render:
 
 ```typescript
 <PivotViewer
-    dimensions={[{ key: 'status', label: 'Status', accessor: i => i.status }]}
+    dimensions={[{ key: 'status', label: 'Status', getValue: i => i.status }]}
     // ... creates new array on every render
 />
 ```
@@ -143,7 +144,7 @@ Avoid creating new objects in render:
 
 ```typescript
 const dimensions = useMemo(() => [
-    { key: 'status', label: 'Status', accessor: i => i.status }
+    { key: 'status', label: 'Status', getValue: i => i.status }
 ], []);
 
 <PivotViewer dimensions={dimensions} />
diff --git a/Documentation/PivotViewer/renderers.md b/Documentation/PivotViewer/renderers.md
index 69c47df..929e992 100644
--- a/Documentation/PivotViewer/renderers.md
+++ b/Documentation/PivotViewer/renderers.md
@@ -2,55 +2,31 @@
 
 ## Card Renderer
 
-The card renderer determines how each item appears in the collection view.
+The card renderer determines how each item appears in the collection view. It returns structured text data — `{ title, labels?, values? }` — and `PivotViewer` lays it out into the card. The `labels` and `values` arrays are paired positionally.
 
 ### Basic Card
 
 ```typescript
-const cardRenderer = (item: Product) => (
-    <div className="product-card">
-        <img src={item.imageUrl} alt={item.name} />
-        <h3>{item.name}</h3>
-        <p className="price">${item.price}</p>
-    </div>
-);
+const cardRenderer = (item: Product) => ({
+    title: item.name,
+    labels: ['Price'],
+    values: [`$${item.price}`]
+});
 ```
 
 ### Rich Card Example
 
 ```typescript
-const taskCardRenderer = (item: Task) => (
-    <div className="task-card">
-        <div className="task-header">
-            <span className={`priority priority-${item.priority}`}>
-                P{item.priority}
-            </span>
-            <span className={`status status-${item.status}`}>
-                {item.status}
-            </span>
-        </div>
-        
-        <h4 className="task-title">{item.title}</h4>
-        
-        <div className="task-meta">
-            <div className="assignee">
-                <img src={item.assigneeAvatar} alt={item.assignee} className="avatar" />
-                <span>{item.assignee}</span>
-            </div>
-            
-            <div className="tags">
-                {item.tags.map(tag => (
-                    <span key={tag} className="tag">{tag}</span>
-                ))}
-            </div>
-        </div>
-        
-        <div className="task-footer">
-            <span className="estimate">{item.estimatedHours}h</span>
-            <span className="due-date">{formatDate(item.dueDate)}</span>
-        </div>
-    </div>
-);
+const taskCardRenderer = (item: Task) => ({
+    title: item.title,
+    labels: ['Priority', 'Status', 'Assignee', 'Estimate'],
+    values: [
+        `P${item.priority}`,
+        item.status,
+        item.assignee,
+        `${item.estimatedHours}h`
+    ]
+});
 ```
 
 ## Detail Renderer
@@ -201,28 +177,26 @@ const interactiveDetailRenderer = (item: Task) => {
 
 ## Conditional Rendering
 
-Adapt cards based on item properties:
+Adapt the structured card data based on item properties:
 
 ```typescript
 const adaptiveCardRenderer = (item: Task) => {
     const isOverdue = new Date(item.dueDate) < new Date();
     const isHighPriority = item.priority >= 8;
-    
-    return (
-        <div className={`task-card ${isOverdue ? 'overdue' : ''} ${isHighPriority ? 'high-priority' : ''}`}>
-            {isOverdue && (
-                <div className="overdue-badge">Overdue</div>
-            )}
-            
-            {isHighPriority && (
-                <div className="urgent-indicator">!</div>
-            )}
-            
-            <h4>{item.title}</h4>
-            
-            {/* ... rest of card ... */}
-        </div>
-    );
+
+    const labels: string[] = ['Status'];
+    const values: string[] = [item.status];
+
+    if (isOverdue) {
+        labels.push('Flag');
+        values.push('Overdue');
+    }
+    if (isHighPriority) {
+        labels.push('Priority');
+        values.push('High');
+    }
+
+    return { title: item.title, labels, values };
 };
 ```
 
diff --git a/Documentation/SchemaEditor/editing.md b/Documentation/SchemaEditor/editing.md
index f876934..1e59956 100644
--- a/Documentation/SchemaEditor/editing.md
+++ b/Documentation/SchemaEditor/editing.md
@@ -189,7 +189,7 @@ Disable editing to display schema structure without allowing changes:
 <SchemaEditor
     schema={schema}
     onChange={setSchema}
-    readOnly={true}
+    canEdit={false}
 />
 ```
 
diff --git a/Documentation/SchemaEditor/index.md b/Documentation/SchemaEditor/index.md
index 28203d8..8e1e1d8 100644
--- a/Documentation/SchemaEditor/index.md
+++ b/Documentation/SchemaEditor/index.md
@@ -20,7 +20,7 @@ SchemaEditor allows users to define data structures by adding properties, specif
 ## Quick Start
 
 ```typescript
-import { SchemaEditor } from '@cratis/components';
+import { SchemaEditor } from '@cratis/components/SchemaEditor';
 import { JsonSchema } from '@cratis/components/types';
 
 function MySchemaEditor() {
diff --git a/Documentation/Styling/mixing-paths.md b/Documentation/Styling/mixing-paths.md
index 887c24c..b8e998c 100644
--- a/Documentation/Styling/mixing-paths.md
+++ b/Documentation/Styling/mixing-paths.md
@@ -9,7 +9,8 @@ Keep the PrimeReact theme as your global baseline and opt one specific component
 ```tsx
 import 'primereact/resources/themes/lara-dark-blue/theme.css';
 import '@cratis/components/styles';
-import { CratisComponentsProvider, Dialog } from '@cratis/components';
+import { CratisComponentsProvider } from '@cratis/components';
+import { Dialog } from '@cratis/components/Dialogs';
 
 const brandDialogPt = {
     root:    { className: 'rounded-3xl bg-violet-900 text-violet-50' },
diff --git a/Documentation/TimeMachine/configuration.md b/Documentation/TimeMachine/configuration.md
index 18408f9..2e281fb 100644
--- a/Documentation/TimeMachine/configuration.md
+++ b/Documentation/TimeMachine/configuration.md
@@ -4,7 +4,7 @@
 
 ### Required Props
 
-- `versions`: Array of version objects containing timestamp, readModel, and events
+- `versions`: Array of version objects containing id, timestamp, label, content, and events
 
 ### Optional Props
 
@@ -18,12 +18,15 @@ Each version in the `versions` array should have:
 
 ```typescript
 {
+    id: string;                // Unique identifier for this version
     timestamp: Date;           // When this version was created
-    readModel: object;         // The state of the read model at this time
+    label: string;             // Display label for the version
+    content: React.ReactNode;  // Rendered content shown for this version
     events?: Array<{           // Events that led to this version
+        sequenceNumber: number; // Sequence number of the event
         type: string;          // Event type name
-        timestamp: Date;       // When the event occurred
-        data: object;          // Event payload
+        occurred: Date;        // When the event occurred
+        content: Record<string, unknown>; // Event payload
     }>;
 }
 ```
@@ -33,19 +36,16 @@ Each version in the `versions` array should have:
 ```typescript
 const versions = [
     {
+        id: 'v1',
         timestamp: new Date('2024-01-01T10:00:00'),
-        readModel: {
-            id: 'product-1',
-            name: 'Product A',
-            price: 99.99,
-            status: 'draft',
-            category: 'Electronics'
-        },
+        label: 'Created',
+        content: <div>Product A — $99.99 — draft</div>,
         events: [
             {
+                sequenceNumber: 0,
                 type: 'ProductCreated',
-                timestamp: new Date('2024-01-01T10:00:00'),
-                data: {
+                occurred: new Date('2024-01-01T10:00:00'),
+                content: {
                     name: 'Product A',
                     category: 'Electronics'
                 }
@@ -53,19 +53,16 @@ const versions = [
         ]
     },
     {
+        id: 'v2',
         timestamp: new Date('2024-01-05T14:30:00'),
-        readModel: {
-            id: 'product-1',
-            name: 'Product A',
-            price: 89.99,  // Changed
-            status: 'draft',
-            category: 'Electronics'
-        },
+        label: 'Price updated',
+        content: <div>Product A — $89.99 — draft</div>,
         events: [
             {
+                sequenceNumber: 1,
                 type: 'PriceUpdated',
-                timestamp: new Date('2024-01-05T14:30:00'),
-                data: {
+                occurred: new Date('2024-01-05T14:30:00'),
+                content: {
                     oldPrice: 99.99,
                     newPrice: 89.99
                 }
@@ -73,19 +70,16 @@ const versions = [
         ]
     },
     {
+        id: 'v3',
         timestamp: new Date('2024-01-10T09:15:00'),
-        readModel: {
-            id: 'product-1',
-            name: 'Product A',
-            price: 89.99,
-            status: 'active',  // Changed
-            category: 'Electronics'
-        },
+        label: 'Published',
+        content: <div>Product A — $89.99 — active</div>,
         events: [
             {
+                sequenceNumber: 2,
                 type: 'ProductPublished',
-                timestamp: new Date('2024-01-10T09:15:00'),
-                data: {
+                occurred: new Date('2024-01-10T09:15:00'),
+                content: {
                     status: 'active'
                 }
             }
diff --git a/Documentation/TimeMachine/index.md b/Documentation/TimeMachine/index.md
index 0a6556e..a28864c 100644
--- a/Documentation/TimeMachine/index.md
+++ b/Documentation/TimeMachine/index.md
@@ -20,24 +20,31 @@ TimeMachine allows users to navigate through different versions of data, viewing
 ## Quick Start
 
 ```typescript
-import { TimeMachine } from '@cratis/components';
+import { TimeMachine } from '@cratis/components/TimeMachine';
 
 interface Version {
+    id: string;
     timestamp: Date;
-    readModel: object;
-    events: Array<{
+    label: string;
+    content: React.ReactNode;
+    events?: Array<{
+        sequenceNumber: number;
         type: string;
-        timestamp: Date;
-        data: object;
+        occurred: Date;
+        content: Record<string, unknown>;
     }>;
 }
 
 function MyTimeMachine() {
     const versions: Version[] = [
         {
+            id: 'v1',
             timestamp: new Date('2024-01-01'),
-            readModel: { name: 'Initial', status: 'draft' },
-            events: [{ type: 'Created', timestamp: new Date('2024-01-01'), data: {} }]
+            label: 'Initial',
+            content: <div>Name: Initial — Status: draft</div>,
+            events: [
+                { sequenceNumber: 0, type: 'Created', occurred: new Date('2024-01-01'), content: {} }
+            ]
         }
     ];
 
diff --git a/Documentation/Toolbar/basic-usage.md b/Documentation/Toolbar/basic-usage.md
index 22f48ec..96e0387 100644
--- a/Documentation/Toolbar/basic-usage.md
+++ b/Documentation/Toolbar/basic-usage.md
@@ -3,7 +3,7 @@
 Place `ToolbarButton` elements inside a `Toolbar`:
 
 ```tsx
-import { Toolbar, ToolbarButton } from '@cratis/components';
+import { Toolbar, ToolbarButton } from '@cratis/components/Toolbar';
 
 function MyToolbar() {
     return (
@@ -19,7 +19,7 @@ function MyToolbar() {
 `ToolbarButton` supports either an icon, text, or both. For text-first controls such as zoom indicators, provide the `text` prop:
 
 ```tsx
-import { Toolbar, ToolbarButton, ToolbarSeparator } from '@cratis/components';
+import { Toolbar, ToolbarButton, ToolbarSeparator } from '@cratis/components/Toolbar';
 
 function ZoomToolbar() {
     const [zoom, setZoom] = useState(120);
@@ -52,4 +52,4 @@ import { FaPencil } from 'react-icons/fa6';
 </Toolbar>
 ```
 
-See [Icon](../../Common/icon.md) for the shared `Icon` type and `IconDisplay` component.
+See [Icon](../Common/icon.md) for the shared `Icon` type and `IconDisplay` component.
diff --git a/Documentation/Toolbar/fan-out.md b/Documentation/Toolbar/fan-out.md
index e0b8b0c..1375c7f 100644
--- a/Documentation/Toolbar/fan-out.md
+++ b/Documentation/Toolbar/fan-out.md
@@ -46,4 +46,4 @@ import { FaShapes } from 'react-icons/fa6';
 </ToolbarFanOutItem>
 ```
 
-See [Icon](../../Common/icon.md) for the shared `Icon` type and `IconDisplay` component.
+See [Icon](../Common/icon.md) for the shared `Icon` type and `IconDisplay` component.
diff --git a/Documentation/Toolbar/folder.md b/Documentation/Toolbar/folder.md
index cc70c8d..107dd47 100644
--- a/Documentation/Toolbar/folder.md
+++ b/Documentation/Toolbar/folder.md
@@ -54,7 +54,7 @@ import { FaFolder } from 'react-icons/fa6';
 </ToolbarFolder>
 ```
 
-See [Icon](../../Common/icon.md) for the shared `Icon` type and `IconDisplay` component.
+See [Icon](../Common/icon.md) for the shared `Icon` type and `IconDisplay` component.
 
 ## List Mode
 
diff --git a/Documentation/Toolbar/sections.md b/Documentation/Toolbar/sections.md
index 8c4fe7c..303f9e3 100644
--- a/Documentation/Toolbar/sections.md
+++ b/Documentation/Toolbar/sections.md
@@ -3,7 +3,7 @@
 `ToolbarSeparator` renders a thin visual divider between groups of buttons. Unlike `ToolbarSection`, it has no behavioral logic — it simply draws a line perpendicular to the toolbar orientation. In a horizontal toolbar the separator is a vertical rule; in a vertical toolbar it is a horizontal rule.
 
 ```tsx
-import { Toolbar, ToolbarButton, ToolbarSeparator } from '@cratis/components';
+import { Toolbar, ToolbarButton, ToolbarSeparator } from '@cratis/components/Toolbar';
 
 function ZoomToolbar() {
     return (
diff --git a/Documentation/Toolbar/slots.md b/Documentation/Toolbar/slots.md
index 05d1531..3997bb4 100644
--- a/Documentation/Toolbar/slots.md
+++ b/Documentation/Toolbar/slots.md
@@ -7,7 +7,7 @@ The slot system lets any component in the React tree inject toolbar items into a
 Wrap the relevant part of the tree in a `ToolbarSlotProvider`, give a `ToolbarGroup` a `slotName`, and use `ToolbarSlot` anywhere inside the provider to inject items:
 
 ```tsx
-import { ToolbarSlotProvider, ToolbarSlot } from '@cratis/components';
+import { ToolbarSlotProvider, ToolbarSlot } from '@cratis/components/Toolbar';
 
 export const MyCanvas = () => (
     <ToolbarSlotProvider>
@@ -131,7 +131,7 @@ Any number of independent components can register into the same slot. They are r
 If you need to read slot items directly (for example when building a custom slot host), call `useToolbarSlot`:
 
 ```tsx
-import { useToolbarSlot } from '@cratis/components';
+import { useToolbarSlot } from '@cratis/components/Toolbar';
 
 const MyCustomHost = ({ slotName }: { slotName: string }) => {
     const slotItems = useToolbarSlot(slotName);
diff --git a/Documentation/Toolbar/toolbar-layout.md b/Documentation/Toolbar/toolbar-layout.md
index 161f02f..ff902dc 100644
--- a/Documentation/Toolbar/toolbar-layout.md
+++ b/Documentation/Toolbar/toolbar-layout.md
@@ -18,7 +18,7 @@ The key capability: any component in the React tree can inject a complete toolba
 Wrap the toolbar and the contributing components in a `ToolbarSlotProvider`. Give `ToolbarLayout` a `name` prop that external components match in their `ToolbarSlot`:
 
 ```tsx
-import { ToolbarSlotProvider, ToolbarSlot } from '@cratis/components';
+import { ToolbarSlotProvider, ToolbarSlot } from '@cratis/components/Toolbar';
 
 export const AppShell = () => (
     <ToolbarSlotProvider>
diff --git a/Documentation/building-a-form.md b/Documentation/building-a-form.md
new file mode 100644
index 0000000..875d3d1
--- /dev/null
+++ b/Documentation/building-a-form.md
@@ -0,0 +1,64 @@
+---
+title: "Recipe: Building a form"
+description: Execute a command from a typed form using CommandDialog and CommandForm fields, with validation handled for you.
+sidebar:
+  order: 3
+---
+
+**Goal:** collect input and run an Arc command — with the confirm button disabled while it executes, validation wired up, and no manual fetch.
+
+## Use CommandDialog
+
+`CommandDialog` takes your generated command constructor, instantiates it, renders the fields you supply plus the OK/Cancel footer, and executes on confirm:
+
+```tsx
+import { CommandDialog } from '@cratis/components/CommandDialog';
+import { InputTextField, TextAreaField } from '@cratis/components/CommandForm';
+import { DialogProps, DialogResult } from '@cratis/arc.react/dialogs';
+import { RegisterAuthor } from './RegisterAuthor';   // generated proxy
+
+export const AddAuthor = ({ closeDialog }: DialogProps) => (
+    <CommandDialog<RegisterAuthor>
+        command={RegisterAuthor}
+        title="Add author"
+        okLabel="Add"
+        validateOn="blur"
+        onConfirm={() => closeDialog(DialogResult.Ok)}>
+        <InputTextField<RegisterAuthor> value={i => i.name} title="Name" placeholder="Jane Austen" />
+        <TextAreaField<RegisterAuthor> value={i => i.bio} title="Bio" />
+    </CommandDialog>
+);
+```
+
+The `value={i => i.name}` accessor is **typed against the command** — rename `Name` in C#, rebuild, and this line stops compiling until you fix it.
+
+## Show the dialog
+
+Open it from a button and await the result with `useDialog`:
+
+```tsx
+import { useDialog } from '@cratis/arc.react/dialogs';
+import { DialogResult } from '@cratis/arc.react/dialogs';
+
+const [AddAuthorDialog, showAddAuthor] = useDialog(AddAuthor);
+
+// in your component
+<>
+    <button onClick={async () => {
+        const [result] = await showAddAuthor();
+        if (result === DialogResult.Ok) { /* command executed successfully */ }
+    }}>Add author</button>
+    <AddAuthorDialog />
+</>
+```
+
+## Tips
+
+- **Injected (non-input) values** — set required values like a parent id via `initialValues`, not `onBeforeExecute`. Values set in `onBeforeExecute` run too late to affect validity, so the confirm button would stay disabled. Use `onBeforeExecute` only for generated values (like a new `Guid`) that don't gate validity.
+- **Multi-step forms** — reach for `StepperCommandDialog` when one command needs to be gathered across several stages.
+- Don't import `Dialog` from `primereact/dialog` directly — use the Cratis wrappers so execution, validation timing, and footers stay consistent.
+
+## Next
+
+- [Displaying data](/components/displaying-data/) — render the results.
+- The full field set and dialog options are in the Components reference and Storybook.
diff --git a/Documentation/choosing-a-component.md b/Documentation/choosing-a-component.md
new file mode 100644
index 0000000..366cb7f
--- /dev/null
+++ b/Documentation/choosing-a-component.md
@@ -0,0 +1,46 @@
+---
+title: Choosing a component
+description: A decision guide for the overlapping Components — CommandDialog vs StepperCommandDialog, DataPage vs DataTables, and Dialog vs CommandDialog.
+---
+
+Several Components solve similar-looking problems, and it's not always obvious which one to reach for.
+This page is the decision guide: pick by what you're building, then follow the link to the recipe or
+reference.
+
+## Collecting input
+
+The question is whether confirming the form **runs a command**, and whether it's one step or several.
+
+| You want to… | Use | Why |
+| --- | --- | --- |
+| Collect a few fields and run one command | [`CommandDialog`](./CommandDialog/index.md) | Instantiates, validates, and executes the command; handles the footer and button states. The default. |
+| Run a command, but gather input across **named steps** | [`StepperCommandDialog`](./StepperCommandDialog/index.md) | A wizard over a single command — validate per step, navigate back and forth, execute at the end. |
+| Embed command fields **in a page**, not a dialog | [`CommandForm`](./CommandForm/index.md) | The same typed fields `CommandDialog` uses, without the dialog chrome. |
+| Collect data and return it **without** running a command | [`Dialog`](./Dialogs/index.md) | A confirmation or data-entry dialog that hands values back to the caller. No command involved. |
+
+Rule of thumb: **if confirming the dialog executes a generated command, it's a `CommandDialog`** (or its
+stepper variant). If it just gathers values and returns them, it's a `Dialog`. Never reach for
+PrimeReact's raw `Dialog` — these wrappers handle validation timing, loading state, and footers
+consistently.
+
+## Displaying data
+
+Both render a query or observable query; the question is whether you want a **whole page** or a **table
+to drop into one**.
+
+| You want to… | Use | Why |
+| --- | --- | --- |
+| A full screen: a list, a toolbar of actions, detail panels | [`DataPage`](./DataPage/index.md) | A resizable page composition with toolbar and detail areas wired to the query. |
+| Just a grid inside a layout you already have | [`DataTables`](./DataTables/index.md) | The table wrappers — paging, sorting, and selection over a query — without the page scaffolding. |
+
+If you're building a list-screen-with-actions from scratch, start with the
+[list screen recipe](./list-screen-with-actions.md), which composes `DataPage` with `CommandDialog`
+actions.
+
+## Putting it together
+
+A typical CRUD screen combines these: a `DataPage` lists the rows, a toolbar button opens a
+`CommandDialog` to add one, and selecting a row opens another `CommandDialog` to edit it. That whole
+screen is the [list screen with actions](./list-screen-with-actions.md) recipe.
+
+Still deciding how to style any of this? See [Styling](./Styling/index.md).
diff --git a/Documentation/coming-from-primereact.md b/Documentation/coming-from-primereact.md
new file mode 100644
index 0000000..9e06cee
--- /dev/null
+++ b/Documentation/coming-from-primereact.md
@@ -0,0 +1,127 @@
+---
+title: PrimeReact and Components
+description: You already know PrimeReact. Here's how forms and tables map onto Cratis Components — concept by concept, side by side — and what changes.
+---
+
+Cratis Components isn't a different component kit — it's built **on** PrimeReact. Your theme, your `Column`, your `Button`, your icons all still apply. What changes is the *wiring*: instead of keeping form state and query subscriptions in the screen, you point a component at an Arc-generated proxy and let the component own that integration. This page maps familiar PrimeReact code onto its Components equivalent.
+
+## The one-paragraph version
+
+In a PrimeReact app, the screen often owns request creation, loading state, dialog footer actions, field binding, API calls, and live updates. Components centralizes that wiring around generated command and query proxies — so a form or a table is declarative, and it's type-checked against the C# it came from. You keep PrimeReact while reducing screen-specific integration code.
+
+## A command form
+
+You have a dialog with a field and a save button. By hand, that's local state, a loading flag, a fetch, and footer buttons:
+
+```tsx
+// PrimeReact, local state
+const [name, setName] = useState('');
+const [saving, setSaving] = useState(false);
+
+const save = async () => {
+    setSaving(true);
+    await fetch('/api/authors/register', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name }),
+    });
+    setSaving(false);
+};
+
+<Dialog header="Add author" visible={visible} onHide={hide} footer={
+    <>
+        <Button label="Cancel" onClick={hide} />
+        <Button label="Add" loading={saving} onClick={save} />
+    </>
+}>
+    <InputText value={name} onChange={e => setName(e.target.value)} />
+</Dialog>
+```
+
+With Components, the command *is* the form — instantiation, the footer, the executing state, and validation are handled:
+
+```tsx
+// Components
+<CommandDialog<RegisterAuthor> command={RegisterAuthor} title="Add author" okLabel="Add">
+    <InputTextField<RegisterAuthor> value={i => i.name} title="Name" />
+</CommandDialog>
+```
+
+`i => i.name` is typed against the generated `RegisterAuthor` — rename the property in C#, rebuild, and this line stops compiling.
+
+## A data table
+
+With plain PrimeReact, a table typically fetches on mount, holds rows in state, and — if you want live data — subscribes to updates:
+
+```tsx
+// PrimeReact, local state
+const [authors, setAuthors] = useState([]);
+
+useEffect(() => {
+    fetch('/api/authors').then(r => r.json()).then(setAuthors);
+    // ...and a subscription if you want it to stay current
+}, []);
+
+<DataTable value={authors}>
+    <Column field="name" header="Name" sortable />
+</DataTable>
+```
+
+With Components, you hand the table the query proxy; it subscribes and re-renders as the read model changes:
+
+```tsx
+// Components
+<DataTableForObservableQuery query={AllAuthors} emptyMessage="No authors yet">
+    <Column field="name" header="Name" sortable />
+</DataTableForObservableQuery>
+```
+
+The `Column` is the same PrimeReact component you already use. Only the data binding changed — and it stays live with no subscription code.
+
+## A list-and-detail page
+
+The "table left, details right, toolbar on top" layout has several moving parts: split panes, selection state, and a detail panel that appears only when a row is picked. `DataPage` is that layout as one component:
+
+```tsx
+// Components
+<DataPage title="Authors" query={AllAuthorsWithBooks} detailsComponent={AuthorDetails}>
+    <DataPage.MenuItems>
+        <MenuItem label="Add author" icon="pi pi-plus" command={() => showAddAuthor()} />
+        <MenuItem label="Edit" icon="pi pi-pencil" disableOnUnselected command={openEdit} />
+    </DataPage.MenuItems>
+    <DataPage.Columns>
+        <Column field="name" header="Name" sortable />
+    </DataPage.Columns>
+</DataPage>
+```
+
+Selection, the resizable split, and disabling menu items until a row is selected all come built in.
+
+## How the pieces map
+
+| You know (PrimeReact) | In Components |
+|---|---|
+| `Dialog` + footer `Button`s + a fetch | `CommandDialog command={...}` |
+| `InputText` + `useState` + manual validation | `InputTextField value={i => i.field}` — typed to the command |
+| `DataTable value={...}` + `useEffect` fetch | `DataTableForObservableQuery query={...}` (live) or `DataTableForQuery` |
+| Split panes + selection + detail wiring | `DataPage` with `detailsComponent` |
+| A multi-step wizard you build yourself | `StepperCommandDialog` |
+| A PrimeReact theme | the same theme, plus `--cratis-*` tokens for repainting |
+
+## What stays the same
+
+- It's still PrimeReact underneath. `Column`, `Button`, icons, and your chosen theme all work as you know them.
+- You keep using plain PrimeReact for purely presentational widgets that aren't tied to a command or query — the two coexist happily on the same screen.
+- Your styling knowledge carries over; Components renders PrimeReact in unstyled mode and reads colors and spacing from tokens you control. See [Styling](/components/styling/).
+
+## What changes (and why it's less code)
+
+- **Forms bind to commands, not to local state.** No `useState` per field, no loading flag, no hand-written validation — the command carries its own rules, and the proxy runs them on both sides.
+- **Tables bind to queries, not to fetched arrays.** An observable query keeps the table current with no subscription code and no "refresh after save."
+- **The binding is type-checked.** Field accessors and column fields line up with the generated types, so a backend change that breaks the screen is a compile error, not a runtime surprise.
+
+## Where to go next
+
+- [Getting started](/components/getting-started/) — install Components and mount the provider.
+- [Build the library screen](/components/tutorial/) — the same ideas built up one screen at a time.
+- [Why Components](/components/why-components/) — the case for the library, and when plain PrimeReact is the better choice.
diff --git a/Documentation/displaying-data.md b/Documentation/displaying-data.md
new file mode 100644
index 0000000..a29eeff
--- /dev/null
+++ b/Documentation/displaying-data.md
@@ -0,0 +1,56 @@
+---
+title: "Recipe: Displaying data"
+description: Render query results in a data table that updates live, and build list-and-detail screens with DataPage.
+sidebar:
+  order: 4
+---
+
+**Goal:** show the results of an Arc query in a table — and have it update on its own when the underlying read model changes.
+
+## A live table from an observable query
+
+If your query is observable, `DataTableForObservableQuery` subscribes for you and re-renders as new data arrives — no polling, no manual subscription:
+
+```tsx
+import { DataTableForObservableQuery } from '@cratis/components/DataTables';
+import { Column } from 'primereact/column';
+import { AllAuthors } from './Author';   // generated observable query proxy
+
+export const Authors = () => (
+    <DataTableForObservableQuery query={AllAuthors} emptyMessage="No authors yet">
+        <Column field="name" header="Name" sortable />
+        <Column field="id" header="Id" />
+    </DataTableForObservableQuery>
+);
+```
+
+For a one-shot (non-live) query, use `DataTableForQuery` the same way.
+
+## Prefer the hook when you need the data, not a table
+
+When you want the values themselves (to filter, summarize, or render custom markup), call `.use()` on the proxy:
+
+```tsx
+const [authors] = AllAuthors.use();
+const count = authors.data.length;
+```
+
+## List-and-detail with DataPage
+
+For the common "table on the left, details on the right" screen, `DataPage` gives you the layout, selection, and a resizable detail panel out of the box:
+
+```tsx
+import { DataPage } from '@cratis/components/DataPage';
+```
+
+See the DataPage reference for menu items, the details panel, and selection wiring.
+
+## Tips
+
+- **Eventual consistency** — the read model behind your query updates shortly after a command appends its event. An observable table reflects that automatically the moment the projection catches up. See [Read Models](/chronicle/read-models/).
+- Keep read models **specialized per screen** — a table query and a detail query can read different, purpose-built read models rather than one shared model.
+
+## Next
+
+- [Building a form](/components/building-a-form/) — the write side.
+- [Build a full-stack feature](/build-a-full-app/) — the table and the form together against one Arc slice.
diff --git a/Documentation/getting-started.mdx b/Documentation/getting-started.mdx
new file mode 100644
index 0000000..421e863
--- /dev/null
+++ b/Documentation/getting-started.mdx
@@ -0,0 +1,102 @@
+---
+title: Getting started
+description: Install Components, mount the provider, and render your first type-safe command form — a few declarative lines instead of a few files of glue.
+sidebar:
+  order: 2
+---
+
+import { Steps, Aside } from '@astrojs/starlight/components';
+
+You've built an Arc backend — a `RegisterAuthor` command, an `AllAuthors` query — and `dotnet build` has generated the typed proxies for both. Now you need a screen: a form to add an author, a table that lists them and refreshes itself when one's added.
+
+You can build that straight on PrimeReact — instantiate the command, track its executing state, disable the button while it runs, render OK/Cancel, bind every field, call the query, subscribe to its observable, re-render on change. `@cratis/components` centralizes that integration around your generated proxies, so the same screen is a few declarative lines. Let's wire it up.
+
+## Prerequisites
+
+- **A React app** — a Vite + React frontend (the `dotnet new cratis` template scaffolds one).
+- **An Arc frontend that reaches your backend through generated proxies** — the [Arc frontend get-started](/arc/frontend/getting-started/) sets that up. Components renders forms and tables *on top* of those proxies. If you scaffolded with `dotnet new cratis`, the package is already installed and you're here to understand the pieces.
+
+## Install and wire it up
+
+<Steps>
+
+1. **Install the package and its PrimeReact peers.**
+
+   ```bash title="Install Components"
+   npm install @cratis/components primereact primeicons
+   ```
+
+   A few components pull extra peers only when you use them — `pixi.js` for `PivotViewer`, `framer-motion` for animated panels, `allotment` for `DataPage`. Skip them until you reach for those.
+
+2. **Import the styles once**, at your app's entry point:
+
+   ```typescript title="main.tsx"
+   import '@cratis/components/styles';
+   ```
+
+   This ships the pre-compiled utility styles and the `--cratis-*` [token layer](/components/styling/) the components read their colors and spacing from. It works with any bundler.
+
+3. **Mount the provider** around your app:
+
+   ```tsx title="App.tsx"
+   import '@cratis/components/styles';
+   import { CratisComponentsProvider } from '@cratis/components';
+
+   export const App = () => (
+       <CratisComponentsProvider>
+           <YourApp />
+       </CratisComponentsProvider>
+   );
+   ```
+
+</Steps>
+
+## What the provider sets up
+
+That one wrapper does more than it looks. Components renders PrimeReact in **unstyled mode** with a pass-through preset, configures locale, ripple, and overlay z-index, and routes every component's look through the `--cratis-*` tokens you just imported. The upshot: everything below it renders structurally right away, and it takes its visual identity from tokens you control — not from styles baked into the library.
+
+```mermaid
+flowchart LR
+    Proxy["generated proxy<br/>RegisterAuthor · AllAuthors"] --> C["Components<br/>CommandDialog · DataTable"]
+    C --> PR["PrimeReact (unstyled)"]
+    Tokens["--cratis-* tokens"] -.->|theming| PR
+```
+
+The components sit between your typed proxies and PrimeReact: they speak commands and queries on one side, render PrimeReact on the other, and take their styling from tokens.
+
+## See the payoff
+
+Here's the add-author form — the whole thing. `CommandDialog` takes your generated command, renders the fields and the confirm/cancel buttons, and disables confirm while it executes:
+
+```tsx title="AddAuthor.tsx"
+import { CommandDialog } from '@cratis/components/CommandDialog';
+import { InputTextField } from '@cratis/components/CommandForm';
+import { RegisterAuthor } from './Authors/RegisterAuthor';   // generated proxy
+
+export const AddAuthor = () => (
+    <CommandDialog<RegisterAuthor> command={RegisterAuthor} title="Add author" okLabel="Add">
+        <InputTextField<RegisterAuthor> value={i => i.name} title="Name" />
+    </CommandDialog>
+);
+```
+
+No `isExecuting` flag, no button wiring, no duplicate validation logic — and because `RegisterAuthor` is generated from your C#, `i => i.name` is type-checked against the real command. Rename the property in C#, rebuild, and this line stops compiling until you fix it.
+
+## Choose how it looks
+
+The components render structurally the moment the provider is mounted; their *look* is a separate, deliberate choice. Pick one setup on the [Styling](/components/styling/) page:
+
+- a ready-made PrimeReact theme,
+- a theme repainted with a custom `--cratis-*` palette, or
+- fully unstyled, with your own pass-through preset.
+
+## Recap
+
+You installed `@cratis/components`, imported its styles, and wrapped your app in `CratisComponentsProvider` — and with that one provider in place, a typed command form is a handful of lines instead of a handful of files. Everything else in the library works the same way: declare it, point it at a proxy, done.
+
+## Where to go next
+
+- **[Building a form](/components/building-a-form/)** — `CommandDialog`, field types, validation, and multi-step wizards.
+- **[Displaying data](/components/displaying-data/)** — live data tables that re-render when the read model changes.
+- **[Choosing a component](/components/choosing-a-component/)** — a decision guide from "what's on the screen" to the right component.
+- **[Build a full-stack feature](/build-a-full-app/)** — see Components consume a real Arc slice end to end.
diff --git a/Documentation/index.md b/Documentation/index.md
deleted file mode 100644
index 64bd709..0000000
--- a/Documentation/index.md
+++ /dev/null
@@ -1,138 +0,0 @@
-# Cratis Components
-
-The Cratis Components library provides a comprehensive set of reusable React components built on top of PrimeReact, designed specifically for building data-driven applications with the Cratis Arc framework.
-
-## Overview
-
-This library includes specialized components for:
-
-- **Command Handling**: Dialog and form components for executing commands
-- **Data Display**: Advanced data tables and pages for queries and observable queries
-- **Data Visualization**: Pivot viewers, time machines, and schema editors
-- **Common UI Elements**: Pages, dialogs, and form elements
-- **Navigation**: Object navigational bars and content editors
-
-## Key Features
-
-- Built with TypeScript for type safety
-- Integrates seamlessly with Cratis Arc framework
-- Uses PrimeReact components for consistent UI/UX
-- Supports both queries and observable queries
-- Three supported [styling options](Styling/index.md) — use a PrimeReact theme, apply your own palette, or run fully unstyled
-- Full PrimeReact `pt` (pass-through) forwarding on every wrapper for per-slot styling
-- Comprehensive Storybook documentation
-- Accessibility-focused design
-
-## Getting Started
-
-### Install
-
-Install `@cratis/components` along with the required PrimeReact peer dependencies:
-
-```bash
-npm install @cratis/components primereact primeicons
-# or
-yarn add @cratis/components primereact primeicons
-```
-
-The optional peers (`pixi.js` for `PivotViewer`, `framer-motion` for animated panels, `allotment` for `DataPage` resizable layout) are only required when you use the corresponding component.
-
-### Importing Styles
-
-The library ships pre-compiled utility styles that must be imported once in your application entry point (e.g. `main.tsx`):
-
-```typescript
-import '@cratis/components/styles';
-```
-
-This is required because the components use Tailwind utility classes that are compiled into the package at build time, and because it ships the [`--cratis-*` token layer](Styling/cratis-tokens.md) every Cratis-scoped surface reads from. The import works with any bundler (Vite, webpack, Rollup) regardless of whether your application uses Tailwind.
-
-If you bring your own Tailwind setup and want only the token layer, import `@cratis/components/tokens` instead.
-
-### Wire the Provider
-
-Mount [`CratisComponentsProvider`](Common/cratis-components-provider.md) at the root of your tree to configure PrimeReact's global settings — `unstyled`, `pt`, `ptOptions`, locale, ripple, overlay z-index, and the rest:
-
-```tsx
-import '@cratis/components/styles';
-import { CratisComponentsProvider } from '@cratis/components';
-
-export const App = () => (
-    <CratisComponentsProvider>
-        <YourApp />
-    </CratisComponentsProvider>
-);
-```
-
-### Choose how styling works
-
-The components render structurally as soon as the provider is mounted. To give them a visual identity, choose the setup that matches how much control you need:
-
-- [**Use a PrimeReact theme**](Styling/themed.md) — load a theme stylesheet and tweak with CSS or `className` as needed.
-- [**Use a custom palette on top of a PrimeReact theme**](Styling/custom-palette.md) — keep the theme's structure and repaint with CSS variables on `:root`.
-- [**Use fully unstyled mode**](Styling/unstyled.md) — disable PrimeReact's base styles and provide the visuals through a `pt` preset in CSS or Tailwind.
-
-See the [Styling overview](Styling/index.md) for the full mental model.
-
-### Importing Components
-
-All components are exported from the main package and can be imported as needed:
-
-```typescript
-import { CommandDialog, DataPage, PivotViewer } from '@cratis/components';
-```
-
-For tree-shaking-friendly subpath imports:
-
-```typescript
-import { Dialog } from '@cratis/components/Dialogs';
-import { DataPage } from '@cratis/components/DataPage';
-import { InputTextField } from '@cratis/components/CommandForm/fields';
-```
-
-## Component Categories
-
-### Command Components
-
-Components for handling command execution and user interactions — `CommandDialog`, `StepperCommandDialog`, `CommandStepper`, and the full `CommandForm/fields` set (text, number, dropdown, date, checkbox, radio, slider, multiselect, chips, color picker).
-
-### Data Components
-
-Components for displaying and interacting with data from queries — `DataPage`, `DataTableForQuery`, `DataTableForObservableQuery`.
-
-### Common Components
-
-Reusable UI elements for building consistent layouts — [`CratisComponentsProvider`](Common/cratis-components-provider.md), `Page`, `FormElement`, `Icon`, `Tooltip`, `ErrorBoundary`.
-
-### Specialized Components
-
-Advanced components for specific use cases — `PivotViewer`, `TimeMachine`, `SchemaEditor`, `ObjectContentEditor`, `ObjectNavigationalBar`.
-
-## Styling
-
-Styling is designed to stay out of the way: choose the setup that matches how much control you want, and the other layers stay invisible. See the dedicated [Styling section](Styling/index.md) for:
-
-- [Getting Started](Styling/getting-started.md) — the one-line setup every option shares
-- [Use a PrimeReact theme](Styling/themed.md)
-- [Use a custom palette on top of a PrimeReact theme](Styling/custom-palette.md)
-- [Use fully unstyled mode](Styling/unstyled.md)
-- [Cratis token reference](Styling/cratis-tokens.md)
-- [Pass-through (pt) cheat sheet](Styling/pass-through.md)
-- [Combining styling setups](Styling/mixing-paths.md)
-
-## Upgrading from an earlier release
-
-See the [Migration guide](migration.md) for the required install changes (PrimeReact and PrimeIcons are now peer dependencies), the visual differences to be aware of, and a tour of the new optional capabilities (Cratis Components Provider, `--cratis-*` tokens, full `pt` forwarding).
-
-## Development
-
-The components are built using:
-
-- Vite for development and bundling
-- Vitest for testing
-- Storybook for component documentation (`yarn dev` from `Source/`)
-- yarn for package management
-
-## Documentation
-
-Each component includes comprehensive documentation and examples in Storybook. See the individual component pages for detailed usage instructions, props documentation, and live examples.
diff --git a/Documentation/index.mdx b/Documentation/index.mdx
new file mode 100644
index 0000000..9817101
--- /dev/null
+++ b/Documentation/index.mdx
@@ -0,0 +1,62 @@
+---
+title: Components
+description: The React component library for Cratis — command dialogs, forms, and data tables that consume Arc's generated proxies.
+---
+
+import { CardGrid } from '@astrojs/starlight/components';
+import SimpleCard from '@components/SimpleCard.astro';
+import TopicHero from '@components/TopicHero.astro';
+
+<TopicHero icon="laptop" eyebrow="Components" title="React components wired to your proxies">
+Command dialogs, forms, and data tables that consume [Arc's](/arc/) generated proxies. Built on PrimeReact, fully typed, and styled the way you choose. [Get started →](/components/getting-started/) · [Why Components? →](/components/why-components/)
+</TopicHero>
+
+## Start here
+
+<CardGrid>
+  <SimpleCard title="Getting started" icon="rocket" link="/components/getting-started/">
+    Install the package, mount the provider, and render your first proxy-driven screen.
+  </SimpleCard>
+  <SimpleCard title="Why Components" icon="approve-check" link="/components/why-components/">
+    What the library adds when PrimeReact meets generated Arc proxies.
+  </SimpleCard>
+  <SimpleCard title="Styling" icon="seti:folder" link="/components/styling/">
+    Three paths — a PrimeReact theme, your own palette, or fully unstyled with a `pt` preset.
+  </SimpleCard>
+</CardGrid>
+
+## Recipes
+
+<CardGrid>
+  <SimpleCard title="Build a form" icon="open-book" link="/components/building-a-form/">
+    Collect input and execute a command with `CommandDialog` and the `CommandForm` fields.
+  </SimpleCard>
+  <SimpleCard title="Display data" icon="seti:db" link="/components/displaying-data/">
+    Render a query or observable query with `DataPage` and the data-table wrappers.
+  </SimpleCard>
+  <SimpleCard title="Multi-step form" icon="list-format" link="/components/multi-step-form/">
+    Gather information across named stages with `StepperCommandDialog`.
+  </SimpleCard>
+  <SimpleCard title="A list screen with actions" icon="puzzle" link="/components/list-screen-with-actions/">
+    A full screen: list rows, add and edit through dialogs, and react to selection.
+  </SimpleCard>
+</CardGrid>
+
+## Key components
+
+<CardGrid>
+  <SimpleCard title="CommandDialog" icon="seti:react" link="/components/commanddialog/">
+    Instantiates, validates, and executes a generated command, with the footer handled for you.
+  </SimpleCard>
+  <SimpleCard title="DataPage" icon="laptop" link="/components/datapage/">
+    A resizable page that lists query data with toolbar actions and detail panels.
+  </SimpleCard>
+  <SimpleCard title="CommandForm fields" icon="approve-check" link="/components/commandform/">
+    Typed input fields bound to command properties — text, number, dropdown, date, and more.
+  </SimpleCard>
+  <SimpleCard title="Dialogs" icon="open-book" link="/components/dialogs/">
+    Data-collection dialogs that return values without executing a command.
+  </SimpleCard>
+</CardGrid>
+
+Components renders [Arc's](/arc/) proxies over [Chronicle](/chronicle/) read models — see [Why developers choose Cratis](/why-cratis/) for the full stack.
diff --git a/Documentation/list-screen-with-actions.md b/Documentation/list-screen-with-actions.md
new file mode 100644
index 0000000..7f83e07
--- /dev/null
+++ b/Documentation/list-screen-with-actions.md
@@ -0,0 +1,58 @@
+---
+title: "Recipe: A list screen with actions"
+description: Combine a live table with command dialogs to build the everyday "list things, add/edit/remove them" screen.
+sidebar:
+  order: 6
+---
+
+**Goal:** the most common screen in any app — a table of things with a toolbar to add, and per-row actions to edit or remove. This recipe wires [displaying data](/components/displaying-data/) and [running commands](/components/building-a-form/) together.
+
+## The shape
+
+- A **live table** reads an observable query, so it reflects changes the instant a command lands.
+- A **toolbar button** opens an "add" `CommandDialog`.
+- **Row actions** open edit/remove command dialogs for the selected item.
+
+```tsx
+import { DataPage, MenuItem } from '@cratis/components/DataPage';
+import { Column } from 'primereact/column';
+import { useDialog } from '@cratis/arc.react/dialogs';
+import { AllAuthors } from './Author';        // observable query proxy
+import { AddAuthor } from './AddAuthor';       // CommandDialog from the form recipe
+
+export const Authors = () => {
+    const [AddAuthorDialog, showAddAuthor] = useDialog(AddAuthor);
+
+    return (
+        <>
+            <DataPage
+                title="Authors"
+                query={AllAuthors}
+                emptyMessage="No authors yet">
+                <DataPage.MenuItems>
+                    <MenuItem label="Add author" icon="pi pi-plus" command={() => showAddAuthor()} />
+                </DataPage.MenuItems>
+                <DataPage.Columns>
+                    <Column field="name" header="Name" sortable />
+                </DataPage.Columns>
+            </DataPage>
+            <AddAuthorDialog />
+        </>
+    );
+};
+```
+
+## Why it stays simple
+
+You never write the glue between the write and the read: the "add" command appends an event, the projection updates the read model, and the observable table re-renders — automatically. There's no "refresh the list after saving" code because there's nothing to refresh.
+
+## Tips
+
+- **Edit and remove are just more commands.** Model them as commands (`RenameAuthor`, `RemoveAuthor`) and open them in dialogs the same way; the table updates itself.
+- **Keep the table's read model specialized.** The list query and a detail query can read different, purpose-built read models — don't force one model to serve every screen.
+- For a plain table without the detail panel, use [`DataTableForObservableQuery`](/components/displaying-data/) directly.
+
+## Next
+
+- [Building a form](/components/building-a-form/) and [Displaying data](/components/displaying-data/) — the two halves in detail.
+- [Build a full-stack feature](/build-a-full-app/) — the backend slice this screen sits on.
diff --git a/Documentation/migration.md b/Documentation/migration.md
index b543bb8..b45e3ce 100644
--- a/Documentation/migration.md
+++ b/Documentation/migration.md
@@ -254,18 +254,21 @@ See [Pass-through cheat sheet](Styling/pass-through.md) for every wrapper's avai
 If you only use a few components, prefer subpath imports so unused parts of the package tree-shake out:
 
 ```ts
-// Before — pulls in everything
-import { Dialog, DataPage, InputTextField } from '@cratis/components';
+// Before — the package root re-exports every component as a namespace,
+// so importing from it pulls the whole package into your bundle
+import { Dialogs, DataPage, CommandForm } from '@cratis/components';
+
+// used as Dialogs.Dialog, DataPage.DataPage, CommandForm.InputTextField
 ```
 
 ```ts
-// After — tree-shaking-friendly
+// After — per-component subpaths let the bundler drop everything you don't use
 import { Dialog } from '@cratis/components/Dialogs';
 import { DataPage } from '@cratis/components/DataPage';
-import { InputTextField } from '@cratis/components/CommandForm/fields';
+import { InputTextField } from '@cratis/components/CommandForm';
 ```
 
-The root import (`@cratis/components`) still works and is fine when you use most of the package.
+The root import is convenient when you use most of the package, but it defeats tree-shaking — reach for the subpaths in code that pulls in only a handful of components.
 
 ## New optional capabilities
 
diff --git a/Documentation/multi-step-form.md b/Documentation/multi-step-form.md
new file mode 100644
index 0000000..6f06470
--- /dev/null
+++ b/Documentation/multi-step-form.md
@@ -0,0 +1,46 @@
+---
+title: "Recipe: Multi-step form"
+description: Gather a command's input across several named steps with StepperCommandDialog.
+sidebar:
+  order: 5
+---
+
+**Goal:** one command needs more input than fits comfortably on a single screen. Split it into a wizard — named steps the user moves through — that still executes a single command at the end.
+
+## Use StepperCommandDialog
+
+`StepperCommandDialog` is `CommandDialog` with stages. You group fields into `StepperPanel`s; it handles next/back navigation, per-step validation, and runs the command when the last step is confirmed:
+
+```tsx
+import { StepperCommandDialog } from '@cratis/components/CommandDialog';
+import { StepperPanel } from 'primereact/stepperpanel';
+import { InputTextField, DropdownField } from '@cratis/components/CommandForm';
+import { RegisterMember } from './RegisterMember';   // generated proxy
+
+export const RegisterMemberWizard = () => (
+    <StepperCommandDialog<RegisterMember> command={RegisterMember} title="Register member">
+        <StepperPanel header="Details">
+            <InputTextField<RegisterMember> value={i => i.name} title="Name" />
+            <InputTextField<RegisterMember> value={i => i.email} title="Email" />
+        </StepperPanel>
+        <StepperPanel header="Membership">
+            <DropdownField<RegisterMember> value={i => i.tier} title="Tier" options={tierOptions} />
+        </StepperPanel>
+    </StepperCommandDialog>
+);
+```
+
+## Notes
+
+- **One command, many steps.** Every field across every panel maps to the *same* command — the wizard is just how you collect it. The command still validates and executes once.
+- **Per-step validation.** The user can't advance past a step whose required fields are invalid; use `validateOnInit` if you need a step validated as soon as it's shown.
+- **Required values that aren't inputs** still go through `initialValues` (not `onBeforeExecute`), same as a single-step dialog — see [Building a form](/components/building-a-form/).
+
+## When to use a wizard vs. a plain dialog
+
+Reach for a wizard when the input is genuinely staged or long enough that one screen would overwhelm. For three or four fields, a single [CommandDialog](/components/building-a-form/) is friendlier — don't add steps for their own sake.
+
+## Next
+
+- [Building a form](/components/building-a-form/) — the single-step version and the field set.
+- The full stepper options are in the Components reference and Storybook.
diff --git a/Documentation/storybook.md b/Documentation/storybook.md
deleted file mode 100644
index da26a17..0000000
--- a/Documentation/storybook.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-storybook:
-  path: /Source
----
diff --git a/Documentation/storybook.mdx b/Documentation/storybook.mdx
new file mode 100644
index 0000000..2c09ee6
--- /dev/null
+++ b/Documentation/storybook.mdx
@@ -0,0 +1,13 @@
+---
+title: Storybook
+description: Browse every Cratis component live — props, states, and variations — in an interactive Storybook.
+---
+import StorybookEmbed from '@components/StorybookEmbed.astro';
+
+Every Cratis component ships with **stories** — live, interactive examples you can poke at.
+Toggle props, switch between states, and read the rendered output without writing a line of
+setup. It's the fastest way to see what a component does before you reach for it.
+
+Browse the full catalog below, or use the controls panel to drive each component's props.
+
+<StorybookEmbed />
diff --git a/Documentation/toc.yml b/Documentation/toc.yml
index 8e927e3..6b23e4b 100644
--- a/Documentation/toc.yml
+++ b/Documentation/toc.yml
@@ -1,240 +1,60 @@
 - name: Overview
   href: index.md
-- name: Storybook
-  href: storybook.md
-  items:
-    - name: CommandDialog
-      items:
-        - name: Default
-          href: storybook.md?story=commanddialog-commanddialog--default
-      href: storybook.md?story=commanddialog-commanddialog--default
-    - name: PrimeReact Fields
-      items:
-        - name: All Fields
-          href: storybook.md?story=commandform-primereact-fields--all-fields
-        - name: Input Text Field Example
-          href: storybook.md?story=commandform-primereact-fields--input-text-field-example
-        - name: Number Field Example
-          href: storybook.md?story=commandform-primereact-fields--number-field-example
-        - name: Text Area Field Example
-          href: storybook.md?story=commandform-primereact-fields--text-area-field-example
-        - name: Dropdown Field Example
-          href: storybook.md?story=commandform-primereact-fields--dropdown-field-example
-        - name: Slider Field Example
-          href: storybook.md?story=commandform-primereact-fields--slider-field-example
-        - name: Checkbox Field Example
-          href: storybook.md?story=commandform-primereact-fields--checkbox-field-example
-      href: storybook.md?story=commandform-primereact-fields--all-fields
-    - name: Common
-      items:
-        - name: ErrorBoundary
-          href: storybook.md?story=common-errorboundary--default
-          items:
-            - name: Default
-              href: storybook.md?story=common-errorboundary--default
-            - name: With Error
-              href: storybook.md?story=common-errorboundary--with-error
-        - name: FormElement
-          href: storybook.md?story=common-formelement--default
-          items:
-            - name: Default
-              href: storybook.md?story=common-formelement--default
-            - name: With Email Icon
-              href: storybook.md?story=common-formelement--with-email-icon
-            - name: With Search Icon
-              href: storybook.md?story=common-formelement--with-search-icon
-        - name: Page
-          href: storybook.md?story=common-page--default
-          items:
-            - name: Default
-              href: storybook.md?story=common-page--default
-            - name: With Panel
-              href: storybook.md?story=common-page--with-panel
-      href: storybook.md?story=common-errorboundary--default
-    - name: DataPage
-      items:
-        - name: Default
-          href: storybook.md?story=datapage-datapage--default
-        - name: Without Details
-          href: storybook.md?story=datapage-datapage--without-details
-      href: storybook.md?story=datapage-datapage--default
-    - name: DataTables
-      items:
-        - name: DataTableForObservableQuery
-          href: storybook.md?story=datatables-datatableforobservablequery--default
-          items:
-            - name: Default
-              href: storybook.md?story=datatables-datatableforobservablequery--default
-            - name: With Selection
-              href: storybook.md?story=datatables-datatableforobservablequery--with-selection
-        - name: DataTableForQuery
-          href: storybook.md?story=datatables-datatableforquery--default
-          items:
-            - name: Default
-              href: storybook.md?story=datatables-datatableforquery--default
-            - name: With Selection
-              href: storybook.md?story=datatables-datatableforquery--with-selection
-      href: storybook.md?story=datatables-datatableforobservablequery--default
-    - name: Dialogs
-      items:
-        - name: BusyIndicatorDialog
-          href: storybook.md?story=dialogs-busyindicatordialog--default
-          items:
-            - name: Default
-              href: storybook.md?story=dialogs-busyindicatordialog--default
-        - name: ConfirmationDialog
-          href: storybook.md?story=dialogs-confirmationdialog--default
-          items:
-            - name: Default
-              href: storybook.md?story=dialogs-confirmationdialog--default
-      href: storybook.md?story=dialogs-busyindicatordialog--default
-    - name: Components
-      items:
-        - name: ObjectContentEditor
-          href: storybook.md?story=components-objectcontenteditor--default
-          items:
-            - name: Default
-              href: storybook.md?story=components-objectcontenteditor--default
-            - name: With Timestamp
-              href: storybook.md?story=components-objectcontenteditor--with-timestamp
-            - name: Simple Object
-              href: storybook.md?story=components-objectcontenteditor--simple-object
-            - name: With Array
-              href: storybook.md?story=components-objectcontenteditor--with-array
-        - name: ObjectNavigationalBar
-          href: storybook.md?story=components-objectnavigationalbar--interactive
-          items:
-            - name: Interactive
-              href: storybook.md?story=components-objectnavigationalbar--interactive
-            - name: At Root
-              href: storybook.md?story=components-objectnavigationalbar--at-root
-            - name: Single Level
-              href: storybook.md?story=components-objectnavigationalbar--single-level
-            - name: Deep Path
-              href: storybook.md?story=components-objectnavigationalbar--deep-path
-        - name: SchemaEditor
-          href: storybook.md?story=components-schemaeditor--interactive
-          items:
-            - name: Interactive
-              href: storybook.md?story=components-schemaeditor--interactive
-            - name: View Mode
-              href: storybook.md?story=components-schemaeditor--view-mode
-            - name: Edit Mode
-              href: storybook.md?story=components-schemaeditor--edit-mode
-            - name: Read Only
-              href: storybook.md?story=components-schemaeditor--read-only
-            - name: Empty Schema
-              href: storybook.md?story=components-schemaeditor--empty-schema
-            - name: Simple Schema
-              href: storybook.md?story=components-schemaeditor--simple-schema
-      href: storybook.md?story=components-objectcontenteditor--default
-    - name: Filter
-      items:
-        - name: FilterPanel
-          href: storybook.md?story=filter-filterpanel--single-select-filter
-          items:
-            - name: Single-select string filter
-              href: storybook.md?story=filter-filterpanel--single-select-filter
-            - name: Multi-select string filter
-              href: storybook.md?story=filter-filterpanel--multi-select-filter
-            - name: Numeric range filter (histogram)
-              href: storybook.md?story=filter-filterpanel--numeric-range-filter
-            - name: Custom filter editor
-              href: storybook.md?story=filter-filterpanel--custom-editor
-            - name: Mixed filter types
-              href: storybook.md?story=filter-filterpanel--mixed-filters
-      href: storybook.md?story=filter-filterpanel--single-select-filter
-    - name: PivotViewer
-      items:
-        - name: Default
-          href: storybook.md?story=pivotviewer-pivotviewer--default
-      href: storybook.md?story=pivotviewer-pivotviewer--default
-    - name: TimeMachine
-      items:
-        - name: EventsView
-          href: storybook.md?story=timemachine-eventsview--default
-          items:
-            - name: Default
-              href: storybook.md?story=timemachine-eventsview--default
-            - name: Single Event
-              href: storybook.md?story=timemachine-eventsview--single-event
-            - name: Empty Events
-              href: storybook.md?story=timemachine-eventsview--empty-events
-        - name: Properties
-          href: storybook.md?story=timemachine-properties--default
-          items:
-            - name: Default
-              href: storybook.md?story=timemachine-properties--default
-            - name: Left Aligned
-              href: storybook.md?story=timemachine-properties--left-aligned
-            - name: Right Aligned
-              href: storybook.md?story=timemachine-properties--right-aligned
-            - name: With Null Values
-              href: storybook.md?story=timemachine-properties--with-null-values
-        - name: ReadModelView
-          href: storybook.md?story=timemachine-readmodelview--default
-          items:
-            - name: Default
-              href: storybook.md?story=timemachine-readmodelview--default
-            - name: Single Version
-              href: storybook.md?story=timemachine-readmodelview--single-version
-        - name: TimeMachine
-          href: storybook.md?story=timemachine-timemachine--default
-          items:
-            - name: Default
-              href: storybook.md?story=timemachine-timemachine--default
-            - name: Start At Latest Version
-              href: storybook.md?story=timemachine-timemachine--start-at-latest-version
-            - name: High Scroll Sensitivity
-              href: storybook.md?story=timemachine-timemachine--high-scroll-sensitivity
-      href: storybook.md?story=timemachine-eventsview--default
+- name: Why Components
+  href: why-components.md
+- name: PrimeReact and Components
+  href: coming-from-primereact.md
+- name: Getting started
+  href: getting-started.mdx
+- name: Tutorial
+  href: tutorial/toc.yml
+- name: Choosing a component
+  href: choosing-a-component.md
 - name: Styling
   href: Styling/toc.yml
-- name: Migration guide
+- name: Storybook
+  href: storybook.mdx
+- name: Building a form
+  href: building-a-form.md
+- name: Displaying data
+  href: displaying-data.md
+- name: Multi-step form
+  href: multi-step-form.md
+- name: A list screen with actions
+  href: list-screen-with-actions.md
+- name: CommandDialog
+  href: CommandDialog/toc.yml
+- name: CommandForm
+  href: CommandForm/toc.yml
+- name: CommandStepper
+  href: CommandStepper/toc.yml
+- name: StepperCommandDialog
+  href: StepperCommandDialog/toc.yml
+- name: DataPage
+  href: DataPage/toc.yml
+- name: DataTables
+  href: DataTables/toc.yml
+- name: Dialogs
+  href: Dialogs/toc.yml
+- name: Filter
+  href: Filter/toc.yml
+- name: Dropdown
+  href: Dropdown/index.md
+- name: Toolbar
+  href: Toolbar/toc.yml
+- name: ObjectNavigationalBar
+  href: ObjectNavigationalBar/index.md
+- name: ObjectContentEditor
+  href: ObjectContentEditor/index.md
+- name: PivotViewer
+  href: PivotViewer/toc.yml
+- name: SchemaEditor
+  href: SchemaEditor/toc.yml
+- name: TimeMachine
+  href: TimeMachine/toc.yml
+- name: Common
+  href: Common/toc.yml
+- name: Types
+  href: Types/toc.yml
+- name: Migration
   href: migration.md
-- name: Components
-  items:
-    - name: Command Components
-      items:
-        - name: CommandDialog
-          href: CommandDialog/toc.yml
-        - name: CommandStepper
-          href: CommandStepper/toc.yml
-        - name: StepperCommandDialog
-          href: StepperCommandDialog/toc.yml
-        - name: CommandForm Field Types
-          href: CommandForm/toc.yml
-    - name: Data Components
-      items:
-        - name: DataPage
-          href: DataPage/toc.yml
-        - name: DataTables
-          href: DataTables/toc.yml
-    - name: Common Components
-      items:
-        - name: Common
-          href: Common/toc.yml
-        - name: Dialogs
-          href: Dialogs/toc.yml
-        - name: Dropdown
-          href: Dropdown/index.md
-        - name: FilterPanel
-          href: Filter/toc.yml
-        - name: Toolbar
-          href: Toolbar/toc.yml
-    - name: Specialized Components
-      items:
-        - name: PivotViewer
-          href: PivotViewer/toc.yml
-        - name: TimeMachine
-          href: TimeMachine/toc.yml
-        - name: SchemaEditor
-          href: SchemaEditor/toc.yml
-        - name: ObjectContentEditor
-          href: ObjectContentEditor/index.md
-        - name: ObjectNavigationalBar
-          href: ObjectNavigationalBar/index.md
-    - name: Types
-      items:
-        - name: Types
-          href: Types/toc.yml
diff --git a/Documentation/tutorial/act-on-it.mdx b/Documentation/tutorial/act-on-it.mdx
new file mode 100644
index 0000000..906012a
--- /dev/null
+++ b/Documentation/tutorial/act-on-it.mdx
@@ -0,0 +1,90 @@
+---
+title: "2. Act on the list"
+description: Add, rename, and remove authors with typed command dialogs — and watch the live table update itself the moment a command lands.
+---
+
+import { Steps, Aside } from '@astrojs/starlight/components';
+
+The table lists authors; now a librarian needs to *change* the list. Every change is an Arc command — `RegisterAuthor`, `RenameAuthor`, `RemoveAuthor` — and Components turns each one into a form-with-a-button without you binding a single field. Let's start with adding.
+
+## Add an author
+
+<Steps>
+
+1. **Build the dialog from the command.** `CommandDialog` takes the generated command, renders the fields you list plus the OK/Cancel footer, validates, and executes on confirm. The field accessor `i => i.name` is typed against `RegisterAuthor`:
+
+   ```tsx title="AddAuthor.tsx"
+   import { CommandDialog } from '@cratis/components/CommandDialog';
+   import { InputTextField } from '@cratis/components/CommandForm';
+   import { DialogProps, DialogResult } from '@cratis/arc.react/dialogs';
+   import { RegisterAuthor } from './Authors/RegisterAuthor';   // generated proxy
+
+   export const AddAuthor = ({ closeDialog }: DialogProps) => (
+       <CommandDialog<RegisterAuthor>
+           command={RegisterAuthor}
+           title="Add author"
+           okLabel="Add"
+           onConfirm={() => closeDialog(DialogResult.Ok)}>
+           <InputTextField<RegisterAuthor> value={i => i.name} title="Name" placeholder="Jane Austen" />
+       </CommandDialog>
+   );
+   ```
+
+2. **Open it from the screen.** `useDialog` gives you a wrapper element to render and a function to show it. Drop a toolbar button next to the table from chapter 1:
+
+   ```tsx title="Authors.tsx"
+   import { Button } from 'primereact/button';
+   import { useDialog } from '@cratis/arc.react/dialogs';
+   import { AddAuthor } from './AddAuthor';
+
+   export const Authors = () => {
+       const [AddAuthorDialog, showAddAuthor] = useDialog(AddAuthor);
+       return (
+           <Page title="Authors" panel>
+               <Button label="Add author" icon="pi pi-plus" onClick={() => showAddAuthor()} />
+               <DataTableForObservableQuery query={AllAuthors} emptyMessage="No authors yet">
+                   <Column field="name" header="Name" sortable />
+               </DataTableForObservableQuery>
+               <AddAuthorDialog />
+           </Page>
+       );
+   };
+   ```
+
+</Steps>
+
+## The payoff: it updates itself
+
+Run it and add an author. The new row appears in the table **immediately** — and you wrote nothing to make that happen. There's no "reload the list after saving," because there's nothing to reload: the command appended an event, the projection updated the read model, and the observable table you built in chapter 1 re-rendered on its own. The write side and the read side meet at the read model, and the screen just follows.
+
+<Aside type="tip" title="Validation flows through">
+The rules you put on the command in the backend (a non-empty name, a unique name) are extracted into the generated proxy. `CommandDialog` runs them, disables **Add** until the form is valid, and shows the server's rejection message against the field without duplicate frontend validation code.
+</Aside>
+
+## Rename and remove are just more commands
+
+Editing isn't a different mechanism — it's another command. `RenameAuthor` opens the same way, but it needs to know *which* author. Pass the selected author's id (and current name) as `initialValues`, so the command is valid from the start:
+
+```tsx title="RenameAuthor.tsx"
+<CommandDialog<RenameAuthor>
+    command={RenameAuthor}
+    title="Rename author"
+    okLabel="Save"
+    initialValues={{ id: author.id, name: author.name }}>
+    <InputTextField<RenameAuthor> value={i => i.name} title="Name" />
+</CommandDialog>
+```
+
+<Aside type="note" title="initialValues, not onBeforeExecute">
+The author's `id` must be present for the command to be valid, so it goes in `initialValues`. Values you compute at execution time and that don't gate validity (a generated `Guid`, say) can go in `onBeforeExecute` — but a required id set there arrives too late, and the confirm button would never enable.
+</Aside>
+
+Removing is a `RemoveAuthor` command with nothing but the id — often a confirm dialog rather than a form. The table updates itself after every one of these, the same way it did for adding.
+
+## What you built
+
+- An **Add author** dialog generated from the `RegisterAuthor` command, opened with `useDialog`,
+- a table that **updates live** the moment the command lands — no refresh code,
+- and the pattern for rename and remove: model the change as a command, open it in a dialog, let the list follow.
+
+These actions hang off a toolbar button, but a real list screen lets you *select* a row and act on it — and often shows that row's details beside the list. That's exactly what `DataPage` is for. [Let's build the list-and-detail screen →](./list-and-detail)
diff --git a/Documentation/tutorial/index.md b/Documentation/tutorial/index.md
new file mode 100644
index 0000000..67f6509
--- /dev/null
+++ b/Documentation/tutorial/index.md
@@ -0,0 +1,64 @@
+---
+title: "Tutorial: Build the library screen"
+description: Build the front end for the library app one screen at a time — a live table, command-driven actions, and a list-and-detail layout — using Components on top of your Arc proxies.
+---
+
+In the [Arc tutorial](/arc/tutorial/) you built a library backend: a `RegisterAuthor` command, an `AllAuthors` query, books that belong to authors. Now we'll build the screen a librarian actually uses — and we'll do it the Cratis way, where the UI rides directly on the generated proxies and updates itself.
+
+Here's the thing to hold onto as we go: **you won't write the wiring between the screen and the backend.** No `fetch`, no loading flags, no "refresh the list after saving," no hand-bound form fields. Components already knows how to render a command as a form and a query as a live table — so each screen is a few declarative lines, type-checked against the C# it came from. We'll build it up in three short chapters, stopping at each step to see what just happened.
+
+Here's the slice your screens plug into, as an **[event model](/event-modeling/)** (read left to right). **Components builds the two `ui` blocks** — the dialog that issues the `RegisterAuthor` command and the live table that reads the `Author` read model; the `cmd`, `evt`, and `rmo` in between are the backend you built in the [Arc tutorial](/arc/tutorial/):
+
+```mermaid
+eventmodeling
+
+tf 01 ui  Authors.AddAuthorDialog
+tf 02 cmd Authors.RegisterAuthor { id: uuid, name: string }
+tf 03 evt Authors.AuthorRegistered { name: string }
+tf 04 rmo Authors.Author ->> 03
+tf 05 ui  Authors.AuthorsTable ->> 04
+```
+
+You won't wire those `ui` blocks directly to the backend. Concretely, each generated proxy maps to one Components widget — a query becomes a live table, a command becomes a dialog:
+
+```mermaid
+flowchart LR
+    subgraph Backend["Arc proxies (generated)"]
+        Q["AllAuthors · AllAuthorsWithBooks"]
+        C["RegisterAuthor · RenameAuthor"]
+    end
+    Q -->|live| T["DataTable / DataPage"]
+    C -->|CommandDialog| D["dialogs + forms"]
+    T --> S["the library screen"]
+    D --> S
+```
+
+So the event model tells you *what* each screen does, and this tells you *how* it's built: each screen is a few declarative lines, type-checked against the C# it came from.
+
+## What you'll build
+
+A working library admin screen where a librarian can:
+
+- **see every author in a live table** that updates the instant one is added — no refresh,
+- **add, rename, and remove** authors through typed command dialogs,
+- and **select an author to see their books** in a resizable detail panel beside the list.
+
+## What you'll learn
+
+- How a **live data table** binds to an observable query and re-renders itself.
+- How `CommandDialog` and `useDialog` turn a command into a form-with-a-button, validation included.
+- How `DataPage` gives you a **list-and-detail** layout — selection, columns, menu actions, and a detail panel — out of the box.
+- Why you point each screen at a **purpose-built read model** rather than one shared model.
+
+## What you'll need
+
+- An Arc backend with the library slices from the [Arc tutorial](/arc/tutorial/) — at minimum `AllAuthors` and `RegisterAuthor`, and (for the last chapter) `AllAuthorsWithBooks`.
+- Components installed and the provider mounted — the [Get started](/components/getting-started/) page does this in three steps. Come back when `CratisComponentsProvider` wraps your app.
+
+## The tour
+
+1. **[List the authors](./list-it)** — a live table from the `AllAuthors` query.
+2. **[Act on the list](./act-on-it)** — add, rename, and remove with command dialogs, driven by selection.
+3. **[List and detail](./list-and-detail)** — swap the plain table for a `DataPage` and show each author's books.
+
+By the end you'll have a real screen, and the pattern for every other one in your app. Ready? [Let's put the authors on screen →](./list-it)
diff --git a/Documentation/tutorial/list-and-detail.mdx b/Documentation/tutorial/list-and-detail.mdx
new file mode 100644
index 0000000..d34d3dd
--- /dev/null
+++ b/Documentation/tutorial/list-and-detail.mdx
@@ -0,0 +1,86 @@
+---
+title: "3. List and detail"
+description: Swap the plain table for DataPage to get selection, menu actions, and a resizable detail panel that shows the selected author's books — then look back at the screen you built.
+---
+
+import { Steps, Aside } from '@astrojs/starlight/components';
+
+Our screen lists authors and acts on them, but the actions hang off a lone button, and there's nowhere to *see* an author — their books, in particular. The everyday shape for this is a table on the left, details on the right, with a toolbar that knows whether a row is selected. That layout has enough moving pieces to deserve a component; `DataPage` hands it to you whole.
+
+We'll point it at `AllAuthorsWithBooks` — the read model from the [Arc tutorial](/arc/tutorial/books-and-relationships/) where each author already carries their books — so the detail panel has something to show.
+
+<Steps>
+
+1. **Describe the detail panel.** It's an ordinary component that receives the selected `item`. Because each `AuthorWithBooks` carries its `books`, listing them is a `map` — no second query:
+
+   ```tsx title="AuthorDetails.tsx"
+   export const AuthorDetails = ({ item }) => (
+       <div className="p-4">
+           <h2>{item.name}</h2>
+           <h3>Books</h3>
+           <ul>
+               {item.books.map(book => <li key={String(book.id)}>{book.title}</li>)}
+           </ul>
+       </div>
+   );
+   ```
+
+2. **Assemble the page.** `DataPage` takes the query, the columns, the menu actions, and the detail component. Selection, the resizable split, and hiding the panel when nothing is selected all come built in:
+
+   ```tsx title="Authors.tsx"
+   import { DataPage, MenuItem } from '@cratis/components/DataPage';
+   import { Column } from 'primereact/column';
+   import { useDialog } from '@cratis/arc.react/dialogs';
+   import { AllAuthorsWithBooks } from './Authors/AuthorWithBooks';   // generated proxy
+   import { AddAuthor } from './AddAuthor';
+   import { AuthorDetails } from './AuthorDetails';
+
+   export const Authors = () => {
+       const [AddAuthorDialog, showAddAuthor] = useDialog(AddAuthor);
+       return (
+           <>
+               <DataPage
+                   title="Authors"
+                   query={AllAuthorsWithBooks}
+                   emptyMessage="No authors yet"
+                   detailsComponent={AuthorDetails}>
+                   <DataPage.MenuItems>
+                       <MenuItem label="Add author" icon="pi pi-plus" command={() => showAddAuthor()} />
+                       <MenuItem label="Edit" icon="pi pi-pencil" disableOnUnselected command={() => {/* open RenameAuthor */}} />
+                   </DataPage.MenuItems>
+                   <DataPage.Columns>
+                       <Column field="name" header="Name" sortable />
+                   </DataPage.Columns>
+               </DataPage>
+               <AddAuthorDialog />
+           </>
+       );
+   };
+   ```
+
+</Steps>
+
+Select an author and their books appear on the right. Drag the divider to resize. The **Edit** item is disabled until a row is selected — `disableOnUnselected` wires that to selection for you.
+
+<Aside type="tip" title="One read model per screen">
+The detail panel reads `books` straight off the row because `AllAuthorsWithBooks` was *built for this screen* — author plus books, in one shape. Resist the urge to make one giant read model serve every view. A list query, a detail query, and a dashboard query can each read their own purpose-built model; they're cheap to add and they never fight each other. See [Read Models](/chronicle/read-models/).
+</Aside>
+
+## Look back at what you built
+
+Three chapters ago we had a generated query and no screen. Now we have a real library back office:
+
+- **Chapter 1** — a live table from `AllAuthors`, bound to an observable query with no fetch or subscription code.
+- **Chapter 2** — add, rename, and remove through `CommandDialog` + `useDialog`, with the table updating itself the instant a command lands.
+- **Chapter 3** — a `DataPage` list-and-detail layout: selection, menu actions, and a resizable panel showing each author's books.
+
+The pattern under all of it is the same one Components exists to give you: **point a component at a generated proxy, and the wiring is already done.** A query becomes a live table; a command becomes a validated form; a read model becomes a detail panel — and every one of them stays type-checked against the C# it came from.
+
+## Where to go next
+
+- **[Building a form](/components/building-a-form/)** and **[Displaying data](/components/displaying-data/)** — the two halves in full, including every field type and table option.
+- **[A list screen with actions](/components/list-screen-with-actions/)** — the same screen as a quick recipe to copy.
+- **[Choosing a component](/components/choosing-a-component/)** — a decision guide from "what's on the screen" to the right component.
+- **[Build a full-stack feature](/build-a-full-app/)** — the backend and this front end, assembled end to end.
+
+You've built a screen, and you have the pattern for every other one. That's Components doing its job — go build the rest of your app.
diff --git a/Documentation/tutorial/list-it.mdx b/Documentation/tutorial/list-it.mdx
new file mode 100644
index 0000000..a14daea
--- /dev/null
+++ b/Documentation/tutorial/list-it.mdx
@@ -0,0 +1,51 @@
+---
+title: "1. List the authors"
+description: Put the library's authors on screen with a data table that binds to the AllAuthors query and updates itself when the read model changes.
+---
+
+import { Steps, Aside } from '@astrojs/starlight/components';
+
+A library screen starts with a list. We have an `AllAuthors` query from the backend, generated into a typed proxy — so the first job is to get its results onto the screen in a table. And because that query is **observable**, the table will stay current on its own.
+
+<Steps>
+
+1. **Render the table.** `DataTableForObservableQuery` takes the query proxy, subscribes to it, and renders each result as a row. You describe the columns with PrimeReact's `Column` — `field` matches a property on the read model, typed against the generated `Author`:
+
+   ```tsx title="Authors.tsx"
+   import { Page } from '@cratis/components/Common';
+   import { DataTableForObservableQuery } from '@cratis/components/DataTables';
+   import { Column } from 'primereact/column';
+   import { AllAuthors } from './Authors/Author';   // generated observable query proxy
+
+   export const Authors = () => (
+       <Page title="Authors" panel>
+           <DataTableForObservableQuery query={AllAuthors} emptyMessage="No authors yet">
+               <Column field="name" header="Name" sortable />
+           </DataTableForObservableQuery>
+       </Page>
+   );
+   ```
+
+</Steps>
+
+That's the whole screen. The `Page` wrapper gives you the titled, panelled chrome the rest of the app uses; the table does the rest.
+
+## What you didn't write
+
+Notice everything that's *absent*. There's no `fetch`, no `useEffect`, no loading flag, no `useState` holding the rows, and — the part that matters most — **no subscription code**. `DataTableForObservableQuery` opened the observable for you. The moment something else in the app registers a new author, the backend pushes the new read-model value down, and this table re-renders with the extra row. You'll see that happen for real in the next chapter, when we add the form.
+
+<Aside type="note" title="Live, because the query is observable">
+The liveness comes from the query being observable on the C# side (it returns `collection.Observe()`). If you only need the data once — to summarize or render custom markup — use `DataTableForQuery` instead, or call `AllAuthors.use()` to get the values directly. Same proxy, different consumption.
+</Aside>
+
+## Type safety reaches the column
+
+`field="name"` is a string, but it isn't a guess — it lines up with the `name` property on the generated `Author` read model. If you'd rather not hand-type field names at all, the [Displaying data](/components/displaying-data/) guide shows the typed `Columns` helpers. Either way, the table can't drift from the backend: change the read model in C#, rebuild, and the mismatch shows up.
+
+## What you built
+
+- A library screen that lists every author in a table,
+- bound to the `AllAuthors` query with **no subscription or fetch code**,
+- that will update itself the instant the data behind it changes.
+
+A read-only list isn't a back office, though — a librarian needs to *add* authors. Next we'll give the screen a command. [Let's act on the list →](./act-on-it)
diff --git a/Documentation/tutorial/toc.yml b/Documentation/tutorial/toc.yml
new file mode 100644
index 0000000..b3d853c
--- /dev/null
+++ b/Documentation/tutorial/toc.yml
@@ -0,0 +1,8 @@
+- name: Overview
+  href: index.md
+- name: 1. List the authors
+  href: list-it.mdx
+- name: 2. Act on the list
+  href: act-on-it.mdx
+- name: 3. List and detail
+  href: list-and-detail.mdx
diff --git a/Documentation/why-components.md b/Documentation/why-components.md
new file mode 100644
index 0000000..5bce692
--- /dev/null
+++ b/Documentation/why-components.md
@@ -0,0 +1,35 @@
+---
+title: Why Components
+description: What the Cratis Components library is for, and why it exists on top of PrimeReact.
+sidebar:
+  order: 1
+---
+
+You can build your UI straight on PrimeReact (or any component kit) and keep each form and table connected to your [Arc](/arc/) backend with screen-local state and effects — instantiate the command, manage loading and error state, render the footer buttons, bind each field, call the query, handle the observable subscription. Components centralizes that wiring.
+
+It's a set of React components built on **PrimeReact** that know how to talk to **Arc's generated proxies**. The result: a command form or a live data table is a few declarative lines instead of a few files of glue.
+
+## What it removes
+
+| Without Components | With Components |
+|---|---|
+| Instantiate a command, track `isExecuting`, disable the button, render OK/Cancel | `<CommandDialog command={...}>` does all of it |
+| Bind each input to command state and validate locally | `<InputTextField value={i => i.name} />` — typed to the command |
+| Fetch a query, subscribe to the observable, re-render on change | `<DataTableForObservableQuery>` / `query.use()` |
+| Hand-roll list pages with detail panels | `<DataPage>` |
+
+## What you get
+
+- **Command components** — `CommandDialog`, `StepperCommandDialog`, and the full `CommandForm` field set (text, number, dropdown, date, checkbox, slider, …), all typed against your generated command.
+- **Data components** — `DataTableForQuery`, `DataTableForObservableQuery`, and `DataPage` for list-and-detail screens.
+- **Building blocks** — dialogs, toolbars, navigation, and specialized editors (`PivotViewer`, `TimeMachine`, `SchemaEditor`).
+- **Theming that stays out of the way** — use a PrimeReact theme, repaint with a custom palette, or go fully unstyled. See [Styling](/components/styling/).
+
+## When to use it
+
+Use Components when you're building a Cratis app and want the UI to track the backend with minimal ceremony. If you only need one-off presentational widgets unrelated to commands/queries, plain PrimeReact is fine — and the two coexist happily.
+
+## Next
+
+- [Getting started](/components/getting-started/) — install, wire the provider, render your first form and table.
+- [Build a full-stack feature](/build-a-full-app/) — see Components consume a real Arc slice end to end.
diff --git a/README.md b/README.md
index 8de6bef..f85d488 100644
--- a/README.md
+++ b/README.md
@@ -12,3 +12,13 @@
 ## Description
 
 A collection of React components designed to work seamlessly with the constructs found in the Arc universe. These components provide a rich set of UI elements for building modern applications, including command dialogs, data tables, schema editors, and more.
+
+## Support
+
+Cratis is an open community, and we are glad to help users, teams evaluating the stack, and contributors.
+
+| Channel | Details |
+|---|---|
+| Discord | Join the community on [Discord](https://discord.gg/kt4AMpV8WV) for questions and discussions |
+| GitHub Issues | [Report bugs or request features](https://github.com/Cratis/Components/issues) |
+| Documentation | Read the docs at [cratis.io](https://cratis.io) |