@cratis/pi 3.1.0 → 3.1.2

package/package/corpus/agents/orchestrator.md

@@ -115,7 +115,7 @@ When you receive a goal:
 - [ ] [security-reviewer] Security review of all changed files
 
 ### Phase 5 — Documentation (if applicable)
-- [ ] [write-documentation skill] Document <feature/concept>
+- [ ] [documentation] Document <feature/concept> in its authored source with cratis-documentation-writing (or cratis-engineering-docs-authoring) and cratis-technical-examples for code, when the repository's profiles install them; otherwise follow the repository's own documentation rules
 ```
 
 ---

package/package/corpus/prompts/write-documentation.prompt.md

@@ -1,21 +1,30 @@
 ---
 agent: agent
-description: "Write documentation following the Diátaxis framework."
+description: "Write reader-centered documentation using the Cratis documentation skills."
 ---
 
 # Write Documentation
 
-Write documentation for a feature, component, or concept. Invoke the **write-documentation** skill and follow `.cratis/ai/rules/documentation.md`.
+Write documentation for a feature, component, or concept. Follow
+`.cratis/ai/rules/documentation.md` and invoke **cratis-documentation-writing**.
+For a Cratis product page, also use **cratis-engineering-docs-authoring**;
+for samples or snippets, use **cratis-technical-examples**.
 
-## Confirm first
+## Determine the reader's job
 
-- **Subject**, **audience**, and the **Diátaxis type** — exactly one:
-  - **Tutorial** — guided lesson for newcomers
-  - **How-to guide** — recipe for a specific task
-  - **Reference** — exhaustive, terse technical description
-  - **Explanation** — concepts, trade-offs, architecture (the *why*)
-- The source files to document.
+From the request and neighboring authored pages, identify the reader, the
+question they have, the outcome they need, and the page's primary purpose:
+tutorial, how-to, explanation, or reference. Ask only when plausible choices
+would materially change the result; don't require an outline approval before
+ordinary drafting. Find the owning source before editing, never a synced copy.
 
-## Workflow
+## Write and verify
 
-Clarify type/audience/scope → propose an outline → write. Active voice, present tense, second person; lead with *why*; complete and correct code examples; Mermaid diagrams for non-trivial concepts; descriptive link text; relative links that resolve. Update `toc.yml` and run the documentation verification before considering it done. The skill carries the per-page detail; don't duplicate it here.
+Lead with the problem and payoff. Use active voice and show how the reader can
+recognize success. A tutorial can briefly explain an observed result without
+turning into a reference dump; link to deeper material. Verify framework APIs
+against first-party source at the applicable version, check the sample at its
+claimed scope, and run the owning repository's content and link gates. Add a
+new page to the owning product's `toc.yml`
+(a page missing from it silently drops out of the sidebar); otherwise update
+navigation only when the page's placement or route changes.

package/package/corpus/rules/documentation-structure-and-formatting.md

@@ -24,7 +24,7 @@ sidebar:
 ```
 
 - Product pages should declare `title` and `description`. The title becomes the page H1; the description feeds metadata and AI-facing exports.
-- Preserve existing frontmatter when editing unless the task deliberately changes it. The converter preserves only `title`, `description`, `sidebar`, and `tableOfContents`; it drops DocFX keys and other Starlight keys. Features such as `template`, `hero`, `banner`, `head`, `prev`, `next`, `slug`, and `draft` work only on site-level pages authored directly in the Documentation repository.
+- Preserve existing frontmatter when editing unless the task deliberately changes it. The converter preserves only `title`, `description`, `sidebar`, and `tableOfContents` from authored frontmatter; it drops DocFX keys and other Starlight keys. It generates `editUrl` separately from the owning product source path, so the page's edit action does not point to the synchronized copy. That link is the contribution path for a reader who is not set up locally: never hand-author `editUrl`, and after moving a page confirm its generated edit link still opens the file. Features such as `template`, `hero`, `banner`, `head`, `prev`, `next`, `slug`, and `draft` work only on site-level pages authored directly in the Documentation repository.
 - Product navigation comes from `toc.yml`, not Starlight autogeneration. `sidebar.badge` works, but `sidebar.order`, `sidebar.label`, and `sidebar.hidden` do not control product navigation.
 - A frontmatter-less page falls back to its first H1, but that loses the description and relies on converter inference. Do not add new pages that way.
 
@@ -50,7 +50,7 @@ sidebar:
 Use the least powerful format that communicates the idea:
 
 - Keep `.md` for headings, prose, links, GFM tables, fenced code, Mermaid/EventModeling diagrams, images, and Starlight aside directives.
-- Use `.mdx` only when the page needs imported Astro components, expressions, props, or named slots.
+- Use `.mdx` only when the page needs imported Astro components, expressions, props, or named slots. Every component costs machine readability: the Markdown mirror that assistants and "Copy Markdown" read keeps its imports and JSX. Spend that deliberately, where the component teaches better than plain Markdown.
 - Imports and JSX in `.md` fail silently: the import can render as visible prose and the component as an inert element. Permissive Markdown HTML allowlists can hide this mistake. A page using a component must be `.mdx`.
 - Do not rename a page to `.mdx` merely for a callout or diagram. Renames require checking `toc.yml`, inbound links, generated routes, and AI-facing Markdown output.
 - Do not add raw HTML, inline styling, scripts, or one-off visual components to decorate a product page. Reuse an established component or make an explicit reusable site change in the Documentation repository.

package/package/corpus/rules/documentation.md

@@ -12,9 +12,9 @@ Every page should answer: “If I were a developer encountering this concept for
 
 The site is built with [Astro Starlight](https://starlight.astro.build/). Documentation lives in the `Documentation/` folder of each product repository as [GitHub Flavored Markdown](https://github.github.com/gfm/); a converter synchronizes product `.md`/`.mdx` into the Starlight site, and all repositories are aggregated into one published site. Readers experience it as a single place — write for that whole, not for one repository in isolation. For the authoritative rendering contract, see [Documentation Structure and Formatting](./documentation-structure-and-formatting.md).
 
-## Every page is exactly one Diátaxis type
+## Give each page one primary reader purpose
 
-We organize documentation with the [Diátaxis framework](https://diataxis.fr/). Before writing, decide which of the four types a page is — and write *only* that type. Mixing types is the most common way docs fail: a tutorial padded with reference detail overwhelms the learner; a how-to interrupted by concept digressions stops being a quick recipe.
+Use [Diátaxis](https://diataxis.fr/) as a compass: decide whether the reader is primarily learning, solving a task, looking up a contract, or understanding a concept. Brief context that helps someone complete a tutorial or how-to is welcome. Move an exhaustive lookup or a long conceptual detour to its own linked page; do not split a coherent reader task merely to keep categories pure.
 
 | Type | The reader is… | Reads like | Rule |
 |---|---|---|---|
@@ -31,9 +31,9 @@ For a reader-centered writing workflow, use the **cratis-documentation-writing**
 
 Most readers decide whether to adopt Cratis in the first ten minutes. Protect that path.
 
-- **One canonical getting-started per product**, not a menu of competing quickstarts. Host variants are how-to guides linked *from* the canonical path — never rival front doors.
+- **One clear 'start here' entry per product**, not a menu of competing front doors. Let it direct readers to separate language or host procedures when those are genuinely different; do not force incompatible readers through one runnable recipe.
 - Drive to a **visible payoff fast** — something running the reader can see. State it up front: “By the end you'll have X running.”
-- **One threaded tutorial per product** builds a single realistic domain across chapters, each adding one concept. Open every chapter with what the reader will build or learn and close with a recap. The reader finishes with a working application, not a pile of snippets.
+- **Thread tutorials when the product warrants a multi-chapter journey.** Use one realistic domain across chapters, each adding one concept and visible result. A small tool may need only a short guided lesson; don't create filler chapters to satisfy a template.
 - **One cross-product capstone tutorial** builds a real full-stack feature using the relevant Cratis products together. This is the connective tissue between products — keep it current and runnable.
 
 ## Connect the products
@@ -54,18 +54,18 @@ The project's voice is **direct, practical, and opinionated**. Write like an exp
 - **Do not document the obvious.** If the API is self-explanatory, a complete code example is enough.
 - Use headings, lists, tables, and code blocks — dense paragraphs lose readers.
 - **Be honest about trade-offs.** A “when this is the wrong fit” section builds more trust than omitting the limits.
-- Focus on public APIs and behavior — never internal implementation or third-party libraries.
+- Focus on public APIs and behavior. Explain internals only where they clarify a supported boundary or failure mode; link to third-party documentation rather than retelling it.
 
 ## Diagrams
 
-- Use [Mermaid](https://mermaid-js.github.io/mermaid/#/) for every non-trivial concept — architecture, event and command flow, state transitions, projection and reactor pipelines. A concept page without a diagram is usually incomplete.
+- Use [Mermaid](https://mermaid-js.github.io/mermaid/#/) where a concept has structure that prose conveys poorly — architecture, event and command flow, state transitions, projection and reactor pipelines. Many strong pages carry their load in prose, real code, and real output instead; add a diagram because it explains something, not because the page type seems to require one.
 
 ## Code examples
 
 - Prefer `record` types for events, commands, and read models — match the codebase.
 - Use argument-free `[EventType]` for new events. A new generation or an explicit legacy identifier is valid only when documenting evolution of an existing stored-event contract.
-- Every example must be **complete and correct** — no pseudo-code, no `// ...` elisions that leave the reader guessing.
-- **Short illustrative snippets** may be purpose-built. **Longer or real samples must be embedded from compiled, tested source** when snippet tooling is available, so they cannot drift as APIs change. Never paste untested code, and never substitute a bare “see the repository” link for showing the code.
+- A standalone example must be **complete and correct** at its stated scope. Mark a partial excerpt as an excerpt, state its prerequisites, and never leave an essential step behind `// ...`. Do not offer an incomplete block as click-to-copy code.
+- **Short illustrative snippets** may be purpose-built after checking their framework APIs against source. Derive substantial or runnable examples from compiled, tested sample or spec code; extract or check displayed snippets with the owning repository's tooling so they do not drift. Never substitute a bare “see the repository” link for showing the code.
 - Where a feature spans products or languages, show both sides when both matter. Keep causal explanations sequential; use tabs only for alternatives.
 
 ## Links
@@ -73,15 +73,13 @@ The project's voice is **direct, practical, and opinionated**. Write like an exp
 - **Link text must describe the destination.** Write `[Event types](...)`, never `[see documentation](...)`, `[here](...)`, or `[click here](...)`. Non-descriptive link text is a defect.
 - Use relative links for internal product-source references. Verify every link resolves — broken links and links to non-existent folders fail review.
 
-## What every product's docs must have
+## Cover the reader's needs at the product's scale
 
-- A front-door **index** with a one-sentence definition and a “start here” link.
-- A **“Why <product>”** explanation page covering the problem it solves and when *not* to use it.
-- A canonical **getting started** with a visible payoff.
-- A **threaded tutorial**.
-- A **concepts/glossary** page and an **architecture diagram**.
-- A **troubleshooting/FAQ** page.
-- An **`llms.txt`** and **`llms-full.txt`** output so AI assistants can ground answers in the docs.
+- Every navigable product needs an **index** that defines it and points to a first useful outcome.
+- When a product has enough tutorials or how-to guides to warrant an index, list each by the **situation it solves**, with a one-line description (for example, "Dealing with concurrency" or "Multi-tenancy end to end"), not only by chapter number or API name. Don't add a landing page merely to satisfy this rule, or restructure navigation as a side effect of one page.
+- Document the **diagnostic surface**: the CLI commands, MCP tools, and observable state that tell a reader why the product behaves as it does. A capability with no documented way to inspect it becomes a support request, and an AI assistant helping the reader cannot use it.
+- Provide a **getting-started route**, exact reference, limitations, and recovery information where the product's complexity requires them. A small tool need not manufacture a multi-chapter tutorial, FAQ, glossary, or architecture diagram.
+- Connect related products with links instead of duplicating the same explanation. Share task-area and product indexes through the site's AI-facing exports where useful; don't require a separate full-text download per product or claim that an export alone proves answer quality.
 
 ## File rules
 

package/package/corpus/rules/editing-cratis-docs.md

@@ -43,10 +43,13 @@ From the owning repository:
 
 The local gate validates authored content without requiring every sibling product. The full site check synchronizes every available product and can expose unrelated sibling or optional-tool failures; diagnose and report those separately. Report which checks actually ran when local prose, Markdown, or external-link tools skip because their executables are absent.
 
+The published site builds when the Documentation repository's `main` changes and when a product repository dispatches `build-docs`. Product repositories such as Chronicle, Arc, and Components dispatch from a dedicated documentation workflow when `Documentation/**` changes on `main`, and also from their publish workflows. A merge is not proof the changed page is live: confirm that a site build containing it deployed before saying so. Because correcting a page is cheap, prefer a small accurate edit now over queuing a rewrite.
+
 Restart `npm run dev` after a build/check. The build re-sync can degrade a running dev server, producing 500s or missing table rendering. If a change still appears stale, clear `web/.astro` and `web/node_modules/.astro`, restart, and recheck before blaming the source.
 
 ## Add, move, rename, or delete a page
 
+- Adding a page inside the existing structure, with its `toc.yml` entry, is part of writing it. Adding a navigation bucket, reordering a product's navigation, or moving pages between products is a separate decision about the product's information architecture: make it when the request asks for it, not as a side effect of writing one page.
 - Product navigation comes from its `toc.yml`; site-level navigation comes from `astro.config.mjs`.
 - Product navigation buckets are defined per product in `PRODUCTS[].buckets`. Read the actual names and section lists before changing them.
 - Keep exactly one landing for a route. A sibling `<folder>.md[x]` collides with `<folder>/index.md[x]`; a legacy `.md` collision can move the directory index to `/overview/`, while other duplicate landing shapes can fail the build.

package/package/corpus/rules/pull-requests.md

@@ -13,7 +13,7 @@ PR descriptions serve two purposes: they help reviewers understand the change *n
 - Follow the repository's pull request template (`.github/pull_request_template.md`).
 - Focus on the **Added**, **Changed**, **Fixed**, **Removed**, **Security**, and **Deprecated** sections. Remove sections that are empty — don't leave blank headings.
 - Each bullet should be short, self-contained, and release-note ready.
-- **Write for users of the framework, not for internal developers.** Only include changes that have an impact on anyone using what we build — new APIs, changed behavior, fixed bugs, removed features. Do not list internal implementation details like storage changes, converter updates, gRPC contract internals, or spec additions. If a change is purely internal plumbing, it does not belong in the PR description.
+- **Write for users of the framework, not for internal developers.** Only include changes that have an impact on anyone using what we build — new APIs, changed behavior, fixed bugs, removed features. Do not list internal implementation details like storage changes, converter updates, gRPC contract internals, or spec additions. If a change is purely internal plumbing, it does not belong in the PR description. For a user-visible fix, a brief root cause and what now prevents a regression, stated as observable behavior rather than a list of specs, are user-facing and may be included: they tell the upgrader whether to trust the fix. Credit an external contributor by name or handle, unless they asked not to be named.
 - Add the associated issue reference at the end of a bullet when there is a real GitHub issue for the change (e.g. `(#351)`). Keep it a bare reference — **no closing keywords** (`Closes #351`, `Fixes #351`) anywhere in the body, because the published release notes are the PR description verbatim. If there is no associated issue, omit the reference entirely. Never use a placeholder like `(#issue)` or leave the example number `(#123)` literally, and never invent a random issue number. **Always verify the issue number read-only using the repository source — never guess or invent a number.** Comment on or close an issue when the user's request includes that effect; otherwise prepare a bounded post-merge disposition without performing it.
 - Include a summary only if there is a cohesive theme across the changes. If you find yourself restating individual bullets in slightly different words, the summary adds no value — remove it.
 - Never include Copilot prompt content in the PR description. Remove any "Original prompt" / coding agent transcript blocks before publishing.

package/package/corpus/rules/writing-cratis-docs.md

@@ -16,7 +16,7 @@ The Cratis docs must **take the reader on a tour, like a teacher** — the way [
 - **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 the limits.
 
-## One page equals one Diátaxis type
+## One primary purpose per page
 
 | Type | Reader is… | Reads like |
 |---|---|---|
@@ -25,7 +25,7 @@ The Cratis docs must **take the reader on a tour, like a teacher** — the way [
 | **Explanation** | trying to understand | a discussion — concepts, trade-offs, *why*, a diagram |
 | **Reference** | looking something up | a dictionary — exhaustive, terse, tables/signatures |
 
-Never mix types. A tutorial padded with reference detail overwhelms; a how-to interrupted by concept digressions stops being a recipe. Diátaxis type does not imply a universal navigation bucket; bucket names are product-specific.
+Use the page's primary reader need to guide its structure, not to ban a brief prerequisite or explanation. A tutorial padded with a reference dump overwhelms; a how-to interrupted by a long conceptual detour stops being a recipe. Link out when the other material deserves sustained attention. Diátaxis does not imply a universal navigation bucket; bucket names are product-specific.
 
 ## The tour-voice checklist
 
@@ -33,13 +33,14 @@ Apply this checklist to tutorials, getting-started pages, and explanations:
 
 1. **Open with a concrete scenario**, not a definition of the tool.
 2. **Name the friction first**, then the feature as its relief.
-3. **Use chronological verbs** such as 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** to the next concept.
-6. **Anticipate the reader's doubt** with a meaningful aside.
-7. **Show the result** — output, a resulting model, or another visible success signal.
-8. **Organize by workflow**, not alphabetically.
-9. **End each substantial section with the natural next step** when one exists.
+3. **Make the first snippet the convention path.** Show the shape that works without registration or wiring a convention already handles (no manual `.AutoMap()`, no hand-registered handlers). A first example that configures what a convention does teaches the reader to distrust the convention.
+4. **Use chronological verbs** such as define → append → project → query.
+5. **After every code block, explain the invisible**: what happens under the hood and why it matters. Verify that explanation against the setup the reader actually built; a backend without Chronicle appends no events, so "the command appended an event" would be false there.
+6. **Recap before pivoting** to the next concept.
+7. **Anticipate a likely mistake** near the example it affects. Use a caution aside where the risk would otherwise be missed, such as a convention that fails silently (proxy generation, service lifetimes, AutoMap): show the working shape and a verified recovery path, and name affected versions only when the product source establishes them.
+8. **Show the result** — output, a resulting model, or another visible success signal.
+9. **Organize by workflow**, not alphabetically.
+10. **End each substantial section with the natural next step** when one exists.
 
 Read a current, well-reviewed tutorial in the product or a closely related product before writing; do not assume one product's domain vocabulary fits every other product.
 
@@ -57,7 +58,7 @@ The exact Markdown/MDX boundary, aside semantics, component contracts, import pa
 
 - **Two voices per area:** the toured/educational layer and the terse, exhaustive reference. Narrative pages link *down* into the reference; the reference stays a dictionary.
 - **Connect at the seams** rather than re-explaining. Show how neighboring products meet in the user's workflow and link to the glossary for shared terms.
-- **Coming-from-X bridges** map new concepts to what the reader already knows without organizing the whole product around a competitor.
+- **Coming-from-X bridges** map new concepts to what the reader already knows without organizing the whole product around a competitor. Give each the same shape: the reader's current code, the Cratis equivalent beside it, then a short "what changed and why" list. Write one page per source technology. Keep the other technology's code accurate at a named version, or label it illustrative; state the trade-offs fairly and say when the reader's current approach remains the better fit.
 
 ## Before you call a page done
 

package/package/corpus/skills/cratis-documentation-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-documentation-writing
-description: Plan, write, and improve user-centered Cratis documentation with a clear reader journey and one Diátaxis purpose per page. Use for product docs, tutorials, how-to guides, reference, explanations, and documentation reviews. For executable examples use cratis-technical-examples; for release notes use cratis-release-notes. Do not invent APIs or publish content.
+description: Plan, write, and improve user-centered Cratis documentation with a clear reader journey and one primary Diátaxis purpose per page. Use for product docs, tutorials, how-to guides, reference, explanations, and documentation reviews. For executable examples use cratis-technical-examples; for release notes use cratis-release-notes. Do not invent APIs or publish content.
 license: MIT
 ---
 
@@ -8,9 +8,10 @@ license: MIT
 
 A developer arrives with a job to do, not with an interest in our repository
 structure. Start from that job: what did they try, what stopped them, and what
-would let them know they succeeded? Use [Diátaxis](https://diataxis.fr/) to give
-each page one primary purpose. This skill governs content and reader journeys;
-the owning repository governs page placement, navigation, and rendering.
+would let them know they succeeded? Use [Diátaxis](https://diataxis.fr/)
+as a compass for each page's primary purpose, not a purity test. This skill
+governs content and reader journeys; the owning repository governs page
+placement, navigation, and rendering.
 
 ## Classify before writing
 
@@ -28,9 +29,12 @@ Rules per type:
 - **Tutorial** — lead a newcomer through one realistic, threaded outcome.
   Each step has a visible result. Briefly explain the invisible effect of a
   step, then link to an explanation for deeper theory; do not interrupt the
-  lesson with a reference dump. Show the smallest configuration that runs
-  before presenting options; put host and configuration alternatives in linked
-  how-to guides.
+  lesson with a reference dump. Show the smallest *safe* configuration that
+  runs before presenting options: bind local services to loopback, label
+  development credentials as such, and put host and configuration
+  alternatives in linked how-to guides. Make the first snippet the convention
+  path, with no registration or wiring a convention already does, then name
+  what the framework did that the reader cannot see.
 - **How-to guide** — assume competence. State the goal, list prerequisites,
   give the steps, done. No teaching.
 - **Reference** — exhaustive within its declared scope and terse. For each
@@ -40,8 +44,9 @@ Rules per type:
 - **Explanation** — no steps. Discuss concepts, trade-offs, and design
   decisions. Diagrams are welcome here.
 
-If a reader needs both a lesson and a lookup, link two pages rather than
-mixing their jobs. Resolve routine audience or type choices from the request
+A brief prerequisite or explanation may serve the main journey. If a reader
+also needs an exhaustive lookup, link a reference page rather than burying it
+in the lesson. Resolve routine audience or type choices from the request
 and neighboring pages; ask only when the alternatives change the outcome.
 
 ## Work from the reader outward
@@ -52,13 +57,17 @@ and neighboring pages; ask only when the alternatives change the outcome.
 2. Write the question they came with and the success signal in one sentence.
    Draft a title and first paragraph that make the problem and payoff clear;
    avoid opening with an abstract product definition or an internal type name.
-3. Trace a short route from that page to one canonical getting-started journey,
-   targeted recipes, and exact reference. Offer task- and background-based
-   links without inventing competing quickstarts. A 'coming from X' bridge
-   should map familiar concepts to the new workflow, not replace it.
+3. Trace a short route from that page to one clear 'start here' entry,
+   targeted recipes, and exact reference. Give different languages or hosts
+   their own procedures when a shared path cannot be run as written. A
+   'coming from X' bridge should map familiar concepts to the new workflow,
+   not replace it.
 4. Draft in workflow order. For a tutorial, use one working domain throughout,
    show what to run and what appears, and recap before adding another concept.
    For a how-to, keep only what the specific task needs. Link out for details.
+   Many Cratis readers are adopting a paradigm (event sourcing, event
+   modeling, vertical slices), not only a tool: link the explanation from the
+   start route, but let the reader reach a first success before the theory.
 5. Read the rendered page as a newcomer: could they find it, begin without
    hidden prerequisites, recover from a common mistake, and recognize success?
    Then check claims, examples, accessibility, links, and the owning gates.
@@ -66,6 +75,14 @@ and neighboring pages; ask only when the alternatives change the outcome.
 Use support questions and user feedback as evidence: ask what they searched
 for, where they looked, and which step failed. Repair the entry link, wording,
 or example as appropriate; adding another FAQ entry alone may not fix discovery.
+The docs are also the answer surface for Prompter and Chronicle MCP, so treat
+a repeated question as a signal to investigate the page, its entry route, or
+the product behavior behind it. Reduce a report to the page and the
+sentence-level change the reader expected. Make an in-scope fix when the
+evidence supports one; otherwise report the gap and suggest an issue, opening
+one only when asked.
+[Cratis site specifics](references/cratis-site.md) lists the signals Prompter
+actually records.
 
 ## Writing style
 
@@ -88,7 +105,12 @@ explaining something to a capable developer, confident but never condescending.
   framework requirement from a house convention; avoid making a workaround the
   first example a newcomer copies.
 - State limitations, maturity, compatibility, and when the simpler approach
-  is preferable. Link to third-party docs instead of retelling them.
+  is preferable. Link to third-party docs instead of retelling them. Say that
+  an experimental or preview surface is experimental on its own first screen;
+  a sidebar link or published guide does not tell the reader.
+- Use a [Mermaid](https://mermaid-js.github.io/mermaid/#/) diagram where
+  architecture, a sequence, or state transitions are clearer drawn than
+  told. A diagram replaces topology prose; it does not decorate a page.
 - Vary sentence and paragraph rhythm; avoid templated openings and filler.
   A voice edit must never weaken a technical caveat or invent experience.
 - **American English only**: `color` not `colour`, `behavior` not `behaviour`,
@@ -102,6 +124,14 @@ reader journey in observed use cases and have the owning maintainer review
 structural changes. A style pass cannot establish technical correctness.
 Do not rewrite an entire corpus into one repeated template.
 
+An AI-drafted narrative is a first draft, not a finished page. Give the model
+the reader, the scenario, the terminology and the source evidence up front;
+then revise the result against that evidence and the
+**cratis-writing-voice-and-cadence** constructions before it ships. Tell the
+reviewer the narrative was AI-drafted (in the review request or commit
+message, not in a PR description's release-note sections) so they read it as
+prose, not only as a diff.
+
 For machine-readable delivery and retrieval checks, use
 **cratis-llm-friendly-documentation**; publishing `llms-full.txt` alone does
 not prove that an assistant can find the right page or cite it accurately.
@@ -114,17 +144,21 @@ Never transcribe an API from memory, hand-translate an unsupported client, or
 claim a pasted block is runnable when it requires unstated setup. Show the
 command and observable output for a substantial walkthrough.
 
-Keep the page-specific edit link aimed at the *authored* file, not a synced
-copy. Recheck examples against the supported version when that version changes.
-A review of docs is not complete just because the site builds: syntax and
-behavior are different checks.
+Edit the *authored* file, never a synced copy. The Cratis site derives each
+product page's edit link from that source path, so don't hand-author
+`editUrl` in product frontmatter. Recheck examples against the supported
+version when that version changes. A review of docs is not complete just
+because the site builds: syntax and behavior are different checks.
+
+A page is done for this change, not finished forever. Expect to revisit its
+wording, structure and examples as readers hit them.
 
-## Diagrams
+## Cratis platform specifics
 
-Use [Mermaid](https://mermaid-js.github.io/mermaid/#/) for architecture
-(`graph TD` / `graph LR`), sequence flows (`sequenceDiagram`), and state
-transitions (`stateDiagram-v2`). A diagram replaces a paragraph of topology
-prose; it does not decorate one.
+Read [Cratis site specifics](references/cratis-site.md) before writing a
+Cratis product page. It covers the teaching components (`YouWillLearn`,
+`Recap`, client tabs), maturity labeling, cross-product compatibility, the
+Prompter feedback signal, and who decides page structure.
 
 ## Contextual awareness
 
@@ -142,23 +176,24 @@ Jeremy Miller describes user-centered journeys, tutorial-to-reference links,
 source-checked snippets, and a quick edit/publish loop in his
 [OSS-community account](https://jeremydmiller.com/2026/07/08/things-that-have-worked-for-our-oss-community/)
 and [documentation essay](https://www.linkedin.com/pulse/effective-oss-documentation-jeremy-miller-bh1ac/).
-His account is experience, not evidence that a particular site generator or AI
-model causes better documentation. Borrow the reader and maintenance habits;
-do not copy Wolverine's information architecture onto a different product.
+His account is experience, not evidence that a site generator or AI model
+causes better documentation: borrow the habits, not Wolverine's structure.
 
 ## Completion checklist
 
 A page is done when:
 
-- The Diátaxis type is chosen deliberately and the page holds to that one
-  type, linking out to the other types instead of drifting into them.
+- The page has a deliberate primary purpose; short supporting context helps
+  the reader proceed, while substantial digressions link to their own pages.
 - The audience and their goal were identified before writing, and the first
   screen serves that goal. The first working path needs no unexplained setup
-  or up-front choice among configuration alternatives.
+  or up-front choice among configuration alternatives, and it is safe to run
+  on a developer machine as written.
 - Examples teach intended idioms and identify relevant traps without turning
   a tutorial into an exhaustive list of alternatives.
 - Examples are source-verified, complete at their stated scope, and show a
   checkable result; longer examples come from compiling sample or spec source.
+  Explanations of what happened match the backend the reader built.
 - The entry point, terminology, and next-step links fit the surrounding docs.
 - All internal links resolve; all external links are real.
 - Mermaid blocks are syntactically valid.

package/package/corpus/skills/cratis-documentation-writing/references/cratis-site.md

@@ -0,0 +1,82 @@
+# Cratis site specifics
+
+Facts about the Cratis documentation platform that change how a page should be
+written. They describe the site as of September 2026; confirm against the
+Documentation repository (`web/src/components`, `web/scripts/sync-content.mjs`,
+`web/variant-docs.yml`) before relying on a detail.
+
+## Teaching components
+
+Product pages that import components must be `.mdx`. Every component costs
+machine readability: the raw Markdown mirror behind "Copy Markdown" keeps its
+imports and JSX. Use one where it clearly teaches better than plain Markdown.
+
+| Need | Use |
+| --- | --- |
+| Open a tutorial with its outcomes | `import YouWillLearn from '@components/YouWillLearn.astro'`; optional `title`, list in the body |
+| Close a tutorial chapter | `import Recap from '@components/Recap.astro'`; optional `title` |
+| Ordered procedure | `import { Steps } from '@astrojs/starlight/components'` around an ordered list |
+| One example in every client language | `<ChronicleClientTabs snippet="…" />` or `<ArcBackendTabs snippet="…" />`, expanded at sync time from client-owned snippet files |
+| Two independently readable alternatives (C# and TypeScript) | `import FullStackTabs from '@components/FullStackTabs.astro'`, named `csharp` and `typescript` slots |
+
+- The client-tab macros take `snippet`, and optionally `syncKey` and a
+  `variants="java,kotlin"` subset. There is no `clients` property: a tab
+  appears for each client whose repository has that snippet file.
+- The site links each expanded tab to its exact snippet file in the owning
+  repository. Don't add those links by hand.
+- Arc's authoring check rejects `ArcBackendTabs` nested inside `Steps`.
+- `TopicHero` declares `title` (required), `icon` and `eyebrow`. Don't copy
+  props from a page that passes others; they are ignored.
+
+## Maturity
+
+The site has no single maturity convention. The sidebar badges some surfaces
+"Soon", some pages use a note aside, and the model-first layer (Studio,
+Screenplay, Stage, Scene, Prologue) is described as experimental in the
+site's AI-facing overview (`llms.txt`) but not on every product index. Check the owning product's current
+maturity and production guidance. If it is verified as experimental or
+preview, say so prominently on its index and getting-started page, for
+example in a `:::caution` aside, and state only the change and production
+limits the product source supports. Don't infer those limits from a
+site-wide label.
+
+## Cross-product compatibility
+
+There is no numbered compatibility matrix across the Chronicle kernel and its
+clients, Arc and Chronicle, or Components and Arc; the roadmap lists it as
+being hardened. `compatibility.mdx` describes baselines and dependency
+relationships, Components' supported Arc range is its `peerDependencies`, and
+Chronicle's `upgrading/major-versions.md` marks where kernel and clients must
+move together, and says "unknown" where it has not been established. Follow
+that practice: state the pairings you verified, and say when a pairing is
+unverified instead of implying it works or fails.
+
+## Prompter as a documentation signal
+
+Prompter, the Discord documentation assistant, stores anonymous rows per
+answer: surface, cited page URLs, answered or refused, confidence, and a
+thumbs-up/down verdict. It does not store question or answer text. Readers can
+report a missing or hard-to-find page through its `/issue` command, and an
+opted-in repository can notify a maintainer channel when it could not answer.
+Use refusals, low confidence and negative verdicts grouped by cited page to
+decide which pages to investigate. Don't claim individual questions or a
+reporting dashboard exist.
+
+## Bridges and comparisons
+
+Chronicle's `coming-from-crud`, Arc's `coming-from-mediatr-and-mvc` and
+Components' `coming-from-primereact` are product-owned. The site's .NET and
+JVM event-sourcing comparisons name the compared versions, link first-party
+sources, avoid ranking, and commit to a refresh interval. Keep that standard,
+and label another technology's code as illustrative unless it was compiled
+at a named version.
+
+## Structure and publishing
+
+- No repository has a path-specific `CODEOWNERS` entry for
+  `Documentation/**`; a few, such as Chronicle.Python and Chronicle.Wolverine,
+  have catch-all owners that include it. Check the owning repository rather
+  than assuming a documentation reviewer exists.
+- What is part of writing a page, what is a separate navigation decision,
+  and how a merged change reaches the site are in
+  [Editing Cratis Documentation](../../../rules/editing-cratis-docs.md).

package/package/corpus/skills/cratis-documentation-writing/verification.json

@@ -6,6 +6,7 @@
     { "kind": "skill-contains", "value": "## Classify before writing" },
     { "kind": "skill-contains", "value": "## Work from the reader outward" },
     { "kind": "skill-contains", "value": "cratis-technical-examples" },
-    { "kind": "skill-contains", "value": "## Completion checklist" }
+    { "kind": "skill-contains", "value": "## Completion checklist" },
+    { "kind": "skill-contains", "value": "(references/cratis-site.md)" }
   ]
 }

package/package/corpus/skills/cratis-engineering-docs-authoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-engineering-docs-authoring
-description: Draft accurate Cratis documentation content after the owning repository, page placement, document type, and authoritative product sources are known. Use for tutorials, how-to guides, explanations, and references; defer placement, existing-page discovery, and visual QA to their companion workflows.
+description: Draft accurate Cratis product or engineering documentation once the reader's goal, owning source, and product evidence are known. Use for tutorials, how-to guides, explanations, and references; use the owning repository's navigation and visual QA workflows for placement and rendering.
 license: LICENSE
 ---
 
@@ -37,9 +37,9 @@ different document types, audiences, or product choices remain plausible.
 - The subject is not Cratis product or engineering documentation: do not apply
   this skill.
 
-## Write one document type
+## Write to one primary reader need
 
-Do not mix Diátaxis types on one page:
+Use Diátaxis to choose the page's main job. Include brief context needed to make the task work; link out instead of embedding a different page's full lesson or lookup:
 
 | Type | Reader need | Shape |
 | --- | --- | --- |

package/package/corpus/skills/cratis-llm-friendly-documentation/SKILL.md

@@ -42,6 +42,17 @@ an entire product will fit a model's context window.
    do not recommend it as default prompt context. Measure bytes; label token
    counts as estimates for a named tokenizer or approximation, not universal
    limits. Split oversized sets instead of silently truncating them.
+6. Let an assistant that landed on a rendered page find that page's own
+   Markdown without going back through the index, at a stable URL. Inspect
+   whether that URL carries rendered prose or raw synchronized MDX, label a
+   raw mirror honestly, and propose a rendered export as a separate site
+   change rather than claiming the current mirror provides one.
+
+Cratis's own consumers are Prompter (the Discord documentation assistant),
+Chronicle MCP, and developers' coding agents. A page that shows every client
+language serves a human switching tabs, but it multiplies the code an
+assistant must read for a one-language question; measure that before
+splitting exports per language.
 
 Plain Markdown pages can expose their existing source mirror. For MDX-heavy
 pages, prefer a rendered representation that preserves all relevant variants;

package/package/corpus/skills/cratis-release-notes/SKILL.md

@@ -31,6 +31,15 @@ serialization/schema/data migrations, runtime and dependency compatibility,
 deploy ordering, deprecations/removals, and upgrade/rollback limits. Report
 'not verified' rather than guessing about a supported configuration.
 
+Cratis products move together at their seams: the Chronicle kernel and its
+clients, Arc and Chronicle, Components and Arc. When a change touches a
+seam, state the pairings you verified (for example, which kernel versions a
+client release was tested against) and say which pairings are unverified.
+There is no central compatibility matrix to defer to, so the release note may
+be the only place a reader learns it. Where a measurement drove the change,
+such as how many deployments hit a failure, give the number; never estimate
+one to add weight.
+
 ## Write for the right channel
 
 - **Exact-version release note (GitHub/PR):** start with changes requiring
@@ -38,12 +47,19 @@ deploy ordering, deprecations/removals, and upgrade/rollback limits. Report
   and the user's next action in plain language. Include an issue reference only
   when verified, and follow the owning repository's closing-keyword policy.
   Do not list internal refactors or specs that change nothing users observe.
+  For a user-visible fix, a sentence of root cause and of what now guards
+  against a regression, stated as observable behavior rather than a list of
+  specs, is user-facing: it tells the reader whether to trust the fix. Credit an external contributor by name or handle and say what
+  they did, unless they asked not to be named.
 - **Migration guide (durable product docs):** a compact *old behavior → new
   behavior → required action* table for each affected upgrade path, followed
   by source-verified before/after code or commands. Distinguish required
   migration from optional cleanup, name sequencing for schema/data changes,
   and explain escape hatches with their cost or expiry. If no action is needed,
-  state why and for whom, rather than implying it for everyone.
+  state why and for whom, rather than implying it for everyone. State the
+  table's scope and its known exclusions, so a reader who does not find their
+  API knows whether it was assessed. Do not infer backward compatibility for
+  APIs or configurations that were not assessed.
 - **Announcement or blog post:** explain the motivation and show a small
   realistic success, then link to the exact-version note and migration guide.
   It is not a second independent changelog. Do not claim personal experience

package/package/corpus/skills/cratis-technical-examples/SKILL.md

@@ -24,7 +24,10 @@ language-tab layout or documentation site implementation.
   snippet-equality check beside the sample and run it with the sample build in
   CI. Manual comparison alone is a one-time review, not a drift guard; name
   that limitation when automation is unavailable. Do not copy once and let
-  the page drift.
+  the page drift. Link each extracted block to its source file so a reader
+  can follow it to the fuller example; that link is navigation, not a
+  verification receipt. The Cratis site adds these links automatically to
+  client-language tabs, so don't add them by hand there.
 - **Multi-language client example:** keep one explanation; use the established
   client-owned snippet mechanism, compile each client against its own SDK, and
   offer only implementations that exist. Do not translate a C# call by guess.
@@ -65,6 +68,21 @@ language tabs. Never hand-edit a generated proxy or a synchronized docs copy.
 6. Record the source revision and verification scope in the change summary,
    not as a permanent receipt embedded in the page.
 
+## Know what the owning gate actually checks
+
+Look for a snippet validator before designing another checker. Arc and
+Chronicle's .NET repositories use `Documentation/validate-client-snippets.py`
+for supported **C#** fences in `Documentation/client-snippets/**`; Arc's
+validator has a `--self-test` that plants a failing snippet. Other client
+repositories own their own validators and toolchains. Check the validator's
+reported count and exclusions: unsupported markers or legacy snippets are not
+proved compilable just because the run passed. Run the owning validator for
+every changed client snippet, or name a missing toolchain and rely on its
+required CI gate. These checks **do not** compile ordinary Markdown/MDX fences
+elsewhere in product documentation. For those, verify against real source and
+a runnable sample/spec or an explicit snippet comparison; do not claim
+coverage from a site build or a validator that never scans the page.
+
 A simple process beats a large unmaintained examples gallery: give the reader
 one small success first, then link to a fuller sample when they need it. Update
 examples alongside public API changes and incoming reports of copy/paste failure.

package/package/profile-catalog.json

@@ -860,6 +860,7 @@
     {
       "id": "cratis/engineering/core",
       "availableTargets": [
+        "cratis-documentation-writing",
         "cratis-engineering-decision-record",
         "cratis-engineering-docs-authoring",
         "cratis-engineering-effect-boundaries",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [