@cratis/pi 7.1.4 → 7.2.0

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

@@ -25,6 +25,16 @@ imports and JSX. Use one where it clearly teaches better than plain Markdown.
 - 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`.
+  Tabs can't sit inside `Steps` anywhere, so write a backend procedure as
+  numbered H2 steps and keep `Steps` for shared, untabbed procedures such as
+  the React screen.
+- Site-owned MDX under `web/src/content/docs/` can use `<ArcBackendTabs>` and
+  `<ChronicleClientTabs>` without an import. The site expands them from the
+  same manifest and client-owned snippets as product pages, including in the
+  Copy Markdown mirror; check the mirror to confirm the macro expanded.
+- The variant-docs audit (`web/variant-docs.yml`) also covers site-owned
+  pages. Every site page is audited or explicitly excluded with a reason, and
+  direct single-language backend fences are ratcheted.
 - `TopicHero` declares `title` (required), `icon` and `eyebrow`. Don't copy
   props from a page that passes others; they are ignored.
 
@@ -40,6 +50,10 @@ 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.
 
+Label a preview variant on the first screen of every page that shows it, not
+only on its own getting-started page. An unsupported-variant snippet is one
+sentence with its tracking issue; the surrounding prose doesn't repeat it.
+
 ## Cross-product compatibility
 
 There is no numbered compatibility matrix across the Chronicle kernel and its

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

@@ -7,6 +7,10 @@
     { "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": "(references/cratis-site.md)" }
+    { "kind": "skill-contains", "value": "(references/cratis-site.md)" },
+    { "kind": "skill-contains", "value": "\"how the backends differ\" table" },
+    { "kind": "skill-contains", "value": "keep backend limitations in one table on the series index" },
+    { "kind": "skill-contains", "value": "single-language claims" },
+    { "kind": "skill-contains", "value": "the variant-docs audit" }
   ]
 }

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

@@ -2,6 +2,8 @@
 name: cratis-engineering-docs-authoring
 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
+cratis-hint-paths:
+  - "**/Documentation/**/*.{md,mdx}"
 ---
 
 # Cratis documentation authoring

package/package/corpus/skills/cratis-specifications-csharp/SKILL.md

@@ -2,6 +2,8 @@
 name: cratis-specifications-csharp
 description: Write C# specifications with Cratis.Specifications using the Establish/Because/should_ pattern and the for_/when_/and_ folder hierarchy. Use when adding or restructuring C# specs in any Cratis repository, choosing between an isolated unit spec and an in-process scenario spec, or building reusable given/ contexts. Do not use for TypeScript or React specs, and do not use it to decide what a command, projection, or reactor should do.
 license: MIT
+cratis-hint-paths:
+  - "**/for_*/**/*.cs"
 ---
 
 # Cratis C# specifications

package/package/corpus/skills/cratis-specifications-typescript/SKILL.md

@@ -2,6 +2,9 @@
 name: cratis-specifications-typescript
 description: Write TypeScript specifications in the Cratis BDD style using the given() helper, reusable context classes, Sinon stubbing, and the Chai .should fluent interface. Use when adding or restructuring TypeScript specifications, building a given/ context class, or laying out a for_/when_ specification folder. Do not use for C# specifications, and do not use it to decide what the code under specification should do.
 license: MIT
+cratis-hint-paths:
+  - "**/for_*/**/*.ts"
+  - "**/for_*/**/*.tsx"
 ---
 
 # Cratis TypeScript specifications

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

@@ -2,6 +2,8 @@
 name: cratis-technical-examples
 description: Design and verify developer-facing code samples, tutorial projects, and documentation snippets against real Cratis APIs. Use when adding or reviewing a runnable example, multi-client snippet, sample app, command/output pair, or migration before/after code. Do not invent API shapes or treat rendering as a compilation check.
 license: MIT
+cratis-hint-paths:
+  - "**/Samples/**/*.{cs,ts,tsx}"
 ---
 
 # Technical examples readers can trust
@@ -31,6 +33,11 @@ language-tab layout or documentation site implementation.
 - **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.
+  Use the same domain type names in every tab; if the prose has to explain
+  which name each tab uses, fix the snippets instead. State each backend's id
+  and command-response wire type (for example `Guid` versus `string`) and keep
+  one id type per concept across every page of a series. Shared frontend code
+  that depends on those types must be backend-neutral or tabbed per backend.
 - **Sample application:** one realistic domain, explicit prerequisites and
   package versions, a documented run command, a reproducible state to start
   from, and a visible result. Keep it minimal enough for a new reader to finish.
@@ -83,6 +90,14 @@ 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 compiling tab is not a working tab. For each backend, confirm that the
+artifact is discovered and registered, that proxy generation emits the file
+and types the page names, and that any runtime behavior the page claims (live
+updates, constraint rejection) was observed against a real kernel and sink. If
+a tab's code compiles but fails at runtime, don't publish it with a workaround
+in the prose after it. Put working code in the tab and reference the tracking
+issue in a code comment.
+
 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/corpus/skills/cratis-technical-examples/verification.json

@@ -6,6 +6,9 @@
     { "kind": "skill-contains", "value": "## Choose the right source" },
     { "kind": "skill-contains", "value": "**Multi-language client example:**" },
     { "kind": "skill-contains", "value": "## Build the example as a reader would" },
-    { "kind": "skill-contains", "value": "## Stop conditions" }
+    { "kind": "skill-contains", "value": "## Stop conditions" },
+    { "kind": "skill-contains", "value": "A compiling tab is not a working tab." },
+    { "kind": "skill-contains", "value": "one id type per concept across every page of a series" },
+    { "kind": "skill-contains", "value": "Use the same domain type names in every tab" }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.1.4",
+  "version": "7.2.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [
@@ -41,6 +41,7 @@
       "./src/index.ts",
       "./package/corpus/harnesses/pi/extensions/cratis-hooks/index.ts",
       "./package/corpus/harnesses/pi/extensions/cratis-mcp/index.ts",
+      "./package/corpus/harnesses/pi/extensions/cratis-path-guidance/index.ts",
       "./package/corpus/harnesses/pi/extensions/subagent/index.ts"
     ]
   }

package/src/index.ts

@@ -88,6 +88,16 @@ function ruleMatchesConfiguration(path: string, content: string, configuration:
         (needsDocumentation && selectedProfiles.includes('cratis/documentation'));
 }
 
+/**
+ * A rule scoped by `applyTo` to particular files is delivered by the packaged `cratis-path-guidance`
+ * extension when such a file is touched, so it stays out of the system prompt. Only rules that apply to
+ * every file, or declare no scope, belong there.
+ */
+function isUniversalRule(content: string): boolean {
+    const applyTo = (frontmatterValue(content, 'applyTo') ?? '').split(',').map(glob => glob.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    return applyTo.length === 0 || applyTo.some(glob => ['**', '**/*', '*'].includes(glob));
+}
+
 function rules(cwd: string): string {
     const root = join(corpusRoot, 'rules');
     const configurationPath = join(cwd, '.cratis', 'ai.json');
@@ -99,6 +109,7 @@ function rules(cwd: string): string {
         .sort()
         .map(entry => ({ path: join(root, entry), content: readFileSync(join(root, entry), 'utf8') }))
         .filter(rule => !configuration || ruleMatchesConfiguration(rule.path, rule.content, configuration))
+        .filter(rule => isUniversalRule(rule.content))
         .map(rule => rule.content)
         .join('\n\n');
 }