@cratis/pi 3.1.1 → 3.2.0

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` 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. 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

@@ -58,7 +58,7 @@ The project's voice is **direct, practical, and opinionated**. Write like an exp
 
 ## 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
 
@@ -76,6 +76,8 @@ The project's voice is **direct, practical, and opinionated**. Write like an exp
 ## Cover the reader's needs at the product's scale
 
 - 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.
 

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

@@ -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

@@ -29,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
@@ -62,6 +65,9 @@ and neighboring pages; ask only when the alternatives change the outcome.
 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.
@@ -69,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
 
@@ -91,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`,
@@ -105,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.
@@ -119,16 +146,19 @@ command and observable output for a substantial walkthrough.
 
 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.
+`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
 
@@ -146,9 +176,8 @@ 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
 
@@ -158,11 +187,13 @@ A page is done when:
   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-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.

package/package.json

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