@cratis/pi 3.1.0 → 3.1.1

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

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,7 +54,7 @@ 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
 
@@ -64,8 +64,8 @@ The project's voice is **direct, practical, and opinionated**. Write like an exp
 
 - 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,11 @@ 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.
+- 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/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
 

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
 
@@ -40,8 +41,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,10 +54,11 @@ 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.
@@ -114,8 +117,9 @@ 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.
+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.
 
@@ -150,8 +154,8 @@ do not copy Wolverine's information architecture onto a different product.
 
 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.

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-technical-examples/SKILL.md

@@ -65,6 +65,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.1",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [