@cratis/pi 3.0.0 → 3.1.1

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/profiles.md

@@ -138,7 +138,14 @@ per surface so only the relevant one loads:
 | `cratis-screenplay-ui-composition` | `layout`, templates, `form`, `contribute`, `ui profile`, `theme`, `$strings`, `file` |
 | `cratis-screenplay-captures-and-reactions` | The Change Data Capture Language, `reaction`, `trigger` |
 | `cratis-screenplay-specifications` | Given/when/then and the reference execution |
-| `cratis-screenplay-model-authoring` | The compiler, the CLI, diagnostics, and the parsed-versus-admitted boundary |
+| `cratis-screenplay-model-authoring` | Typed MCP authoring, model navigation/refactoring, compiler diagnostics, and source-versus-executable readiness |
+
+The profile also selects the corpus-owned Screenplay MCP declaration from
+`mcp-servers.json`. The Cratis CLI hosts the server as `cratis screenplay mcp`
+and registers a scoped entry for supported clients without replacing their other
+servers. Inspect install/status results for adapter support or configuration
+conflicts. The conventional model root is `.cratis/screenplay/`; project-owned
+configuration can choose another root.
 
 ## How to Use Profiles
 

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