@cratis/pi 2.21.3 → 2.23.0

package/package/corpus/agents/backend-developer.md

@@ -7,11 +7,12 @@ description: >
   and reactors — all in strict compliance with the vertical slice architecture.
 model: claude-sonnet-4-5
 tools:
-  - githubRepo
-  - codeSearch
-  - usages
-  - rename
-  - terminalLastCommand
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Edit
+  - Write
 ---
 
 # Backend Developer

package/package/corpus/agents/code-reviewer.md

@@ -6,11 +6,11 @@ description: >
   TypeScript conventions, and vertical slice correctness before merge.
 model: claude-sonnet-4-5
 tools:
-  - githubRepo
-  - codeSearch
-  - usages
-  - rename
-  - terminalLastCommand
+  - Read
+  - Grep
+  - Glob
+  - Bash
+readonly: true
 ---
 
 # Code Reviewer
@@ -110,7 +110,7 @@ When checking unused code, references, or naming, use semantic navigation if the
 
 ## TypeScript Styling checklist
 
-- [ ] No hard-coded hex/rgb values — PrimeReact CSS variables used
+- [ ] No hard-coded hex/rgb values — `--cratis-*` tokens used
 - [ ] CSS co-located with component (`.css` file in same folder)
 - [ ] No `!important` unless absolutely required and justified with a comment
 
@@ -128,7 +128,7 @@ When checking unused code, references, or naming, use semantic navigation if the
 - [ ] README.md exists for complex component folders
 - [ ] `CommandDialog` from `@cratis/components/CommandDialog` used for command-based dialogs
 - [ ] `Dialog` from `@cratis/components/Dialogs` used for data-only dialogs
-- [ ] Never imports `Dialog` directly from `primereact/dialog`
+- [ ] Never uses a vendor or hand-rolled modal — `CommandDialog` / `Dialog` from Cratis Components
 - [ ] No monolithic components — decomposed into smaller, focused sub-components
 
 ---

package/package/corpus/agents/coordinator.md

@@ -10,10 +10,11 @@ description: >
   and review).
 model: claude-sonnet-4-5
 tools:
-  - githubRepo
-  - codeSearch
-  - usages
-  - terminalLastCommand
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Agent
 ---
 
 # Coordinator

package/package/corpus/agents/frontend-developer.md

@@ -6,11 +6,12 @@ description: >
   proxies, following the project's component and styling conventions.
 model: claude-sonnet-4-5
 tools:
-  - githubRepo
-  - codeSearch
-  - usages
-  - rename
-  - terminalLastCommand
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Edit
+  - Write
 ---
 
 # Frontend Developer
@@ -64,7 +65,7 @@ Confirm that the TypeScript proxies exist in the slice folder before writing any
 - Place `.tsx` files in the **same folder** as the corresponding `.cs` file.
 - Do NOT prefix the file name with the feature or slice name (folder provides context).
 - Each component has its own `.css` file for static styles.
-- Use PrimeReact CSS variables for all colors, backgrounds, and borders — never hard-code hex values. The default stack is Cratis Components on PrimeReact theming — not Tailwind.
+- Use the `--cratis-*` design tokens for all colors, backgrounds, and borders — never hard-code hex values. The default stack is Cratis Components 4 (Components-owned markup and tokens; no PrimeReact) — not Tailwind.
 - Use `const` over `let`.
 - Use full descriptive names (never abbreviations like `e`, `idx`, `prev`).
 - **Move non-trivial state out of the render function** into a `withViewModel` view model (or a tested state module) — see `react.md`. Extract as soon as a component has 3+ `useState`, a state-syncing `useEffect`, or derived values. A view model is a plain class with no React hooks, constructible in a spec.
@@ -90,28 +91,22 @@ const handleSubmit = async () => {
 ## Query usage pattern (with paging)
 
 ```tsx
-const pageSize = 10;
-
-export const Listing = () => {
-    const [allProjectsResult, , setPage] = AllProjects.useWithPaging(pageSize);
-
-    return (
-        <DataTable
-            lazy paginator
-            value={allProjectsResult.data}
-            rows={pageSize}
-            totalRecords={allProjectsResult.paging.totalItems}
-            alwaysShowPaginator={false}
-            first={allProjectsResult.paging.page * pageSize}
-            onPage={event => setPage(event.page ?? 0)}
-            scrollable scrollHeight="flex"
-            emptyMessage="No items found.">
-            <Column field="name" header="Name" />
-        </DataTable>
-    );
-};
+import { DataTableForQuery, Column } from '@cratis/components/DataTables';
+import { AllProjects } from './AllProjects';
+
+// The table subscribes to the query itself and pages server-side (20 rows a page);
+// do not fetch rows and pass an items array.
+export const Listing = () => (
+    <DataTableForQuery query={AllProjects} emptyMessage="No items found.">
+        <Column field="name" header="Name" />
+    </DataTableForQuery>
+);
 ```
 
+For caller-controlled paging outside a table, use the proxy hook directly —
+`const [result, , , setPage] = AllProjects.useWithPaging(pageSize)`; `result.data` and
+`result.paging` (`page`, `size`, `totalItems`, `totalPages`) drive your own layout.
+
 ---
 
 ## Dialog patterns
@@ -133,7 +128,7 @@ export const AddProject = ({ closeDialog }: DialogProps) => {
             title="Add Project"
             okLabel="Add"
             cancelLabel="Cancel"
-            onConfirm={() => closeDialog(DialogResult.Ok)}
+            onSuccess={() => closeDialog(DialogResult.Ok)}
             onCancel={() => closeDialog(DialogResult.Cancelled)}
         >
             <InputTextField<RegisterProject>
@@ -157,7 +152,7 @@ Use this for dialogs that collect data and return it without executing a command
 import { useState } from 'react';
 import { DialogProps, DialogResult } from '@cratis/arc.react/dialogs';
 import { Dialog } from '@cratis/components/Dialogs';
-import { InputText } from 'primereact/inputtext';
+import { TextInput } from '@cratis/components/Common';
 
 export const AddProject = ({ closeDialog }: DialogProps<{ name: string }>) => {
     const [name, setName] = useState('');
@@ -173,18 +168,18 @@ export const AddProject = ({ closeDialog }: DialogProps<{ name: string }>) => {
             onConfirm={() => closeDialog(DialogResult.Ok, { name })}
             onCancel={() => closeDialog(DialogResult.Cancelled)}
         >
-            <InputText
+            <TextInput
                 value={name}
-                onChange={event => setName(event.target.value)}
+                onChange={value => setName(value)}
                 placeholder="Enter a name"
-                autoFocus
+                aria-label="Project name"
             />
         </Dialog>
     );
 };
 ```
 
-> **Never** import `Dialog` from `primereact/dialog` directly.
+> **Never** use a vendor or hand-rolled modal — dialogs are Components-owned.
 
 ---
 
@@ -195,20 +190,19 @@ import { Page } from '@cratis/components/Common';
 import { AddProject } from './Registration/AddProject';
 import { Listing } from './Listing/Listing';
 import { DialogResult, useDialog } from '@cratis/arc.react/dialogs';
-import { Button } from 'primereact/button';
-import * as mdIcons from 'react-icons/md';
+import { Button } from '@cratis/components/Common';
+import { MdAdd } from 'react-icons/md';
 
 export const Projects = () => {
     const [AddProjectDialog, showAddProjectDialog] = useDialog(AddProject);
 
     // For a query-backed list page, prefer `DataPage` with `<DataPage.MenuItems>`
-    // (it owns the action bar). PrimeReact 11 removed the standalone `Menubar`;
-    // for a custom toolbar, compose `Button`s (content is children in v11).
+    // (it owns the action bar). For a custom action row, compose Components `Button`s
+    // (`variant`: solid | outline | ghost | link; `tone`: neutral | accent | positive | caution | critical).
     return (
         <Page title="Projects">
-            <Button variant="text" onClick={() => showAddProjectDialog()}>
-                <mdIcons.MdAdd />
-                <span>Add Project</span>
+            <Button variant="ghost" icon={<MdAdd aria-hidden="true" />} onClick={() => showAddProjectDialog()}>
+                Add Project
             </Button>
             <Listing />
             <AddProjectDialog />
@@ -238,7 +232,7 @@ Before handing back:
 - [ ] `npx tsc -b` passes with zero errors
 - [ ] Components are in the correct slice folder
 - [ ] If the app has a localization convention, user-visible text is routed through it (product policy — not a Cratis rule)
-- [ ] No hard-coded hex/rgb color values — PrimeReact CSS variables used throughout
+- [ ] No hard-coded hex/rgb color values — `--cratis-*` tokens used throughout
 - [ ] All variable/parameter names are fully descriptive (no abbreviations)
 - [ ] No `any` types — `unknown` with type guards where needed
 - [ ] Composition page updated to include the new component

package/package/corpus/agents/orchestrator.md

@@ -10,10 +10,11 @@ description: >
   large refactors, or any goal that spans more than one concern.
 model: claude-sonnet-4-5
 tools:
-  - githubRepo
-  - codeSearch
-  - usages
-  - terminalLastCommand
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Agent
 ---
 
 # Orchestrator

package/package/corpus/agents/performance-reviewer.md

@@ -6,10 +6,11 @@ description: >
   React render overhead, and Chronicle anti-patterns before merge.
 model: claude-sonnet-4-5
 tools:
-  - githubRepo
-  - codeSearch
-  - usages
-  - terminalLastCommand
+  - Read
+  - Grep
+  - Glob
+  - Bash
+readonly: true
 ---
 
 # Performance Reviewer

package/package/corpus/agents/planner.md

@@ -7,10 +7,11 @@ description: >
   the work is considered done.
 model: claude-sonnet-4-5
 tools:
-  - githubRepo
-  - codeSearch
-  - usages
-  - terminalLastCommand
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Agent
 ---
 
 # Vertical Slice Planner

package/package/corpus/agents/repository-investigation-reviewer.md

@@ -7,8 +7,9 @@ description: >
 model: claude-opus-5
 tools:
   - Read
-  - Glob
   - Grep
+  - Glob
+readonly: true
 ---
 
 # Repository Investigation Reviewer

package/package/corpus/agents/repository-investigator.md

@@ -7,9 +7,10 @@ description: >
 model: claude-opus-5
 tools:
   - Read
-  - Glob
   - Grep
+  - Glob
   - Bash
+readonly: true
 ---
 
 # Repository Investigator

package/package/corpus/agents/security-reviewer.md

@@ -7,10 +7,11 @@ description: >
   attack surface.
 model: claude-sonnet-4-5
 tools:
-  - githubRepo
-  - codeSearch
-  - usages
-  - terminalLastCommand
+  - Read
+  - Grep
+  - Glob
+  - Bash
+readonly: true
 ---
 
 # Security Reviewer

package/package/corpus/agents/slice-implementer.md

@@ -5,7 +5,13 @@ description: >
   in when_*/ folders, and the React surface (page and/or command dialog). Use for new slices and for
   non-trivial slice changes spanning backend and frontend.
 model: claude-opus-4-8
-tools: [githubRepo, codeSearch, usages, rename, terminalLastCommand]
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Edit
+  - Write
 ---
 
 # Slice Implementer
@@ -52,7 +58,7 @@ Proxies now exist. Build React components from the generated proxies (`react.md`
 - Events: no arguments on `[EventType]`, non-nullable, past tense, `<summary>`, never carry the event-source id.
 - `[OnceOnly]` on non-idempotent reactor side effects; reactors return side-effect events or use `ICommandPipeline` (never `IEventLog`).
 - Specs `#if DEBUG`, command aliased, per-test unique values.
-- Frontend via `withViewModel` + Arc proxy hooks + Cratis Components; never edit generated proxies; never import `Dialog` from `primereact/dialog`.
+- Frontend via `withViewModel` + Arc proxy hooks + Cratis Components; never edit generated proxies; never use a vendor or hand-rolled modal (dialogs come from `@cratis/components/CommandDialog` and `/Dialogs`).
 
 ## Output
 

package/package/corpus/agents/spec-writer.md

@@ -6,10 +6,12 @@ description: >
   comprehensive behavior coverage following the project's BDD conventions.
 model: claude-sonnet-4-5
 tools:
-  - githubRepo
-  - codeSearch
-  - usages
-  - terminalLastCommand
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Edit
+  - Write
 ---
 
 # Spec Writer

package/package/corpus/harnesses/pi/extensions/subagent/agents.ts

@@ -23,6 +23,13 @@ export interface AgentConfig {
 	name: string;
 	description: string;
 	tools?: string[];
+	/**
+	 * Set when the agent declared a non-empty `tools` list of which nothing maps to a Pi tool. Such an
+	 * agent must not launch: dropping the whole list would hand a deliberately restricted agent (a
+	 * read-only reviewer) Pi's full default toolset. Mirrors Claude Code, which refuses to launch a
+	 * subagent whose `tools` list resolves to no tool.
+	 */
+	toolsError?: string;
 	model?: string;
 	systemPrompt: string;
 	source: "package" | "user" | "project";
@@ -70,22 +77,59 @@ const TOOL_NAME_MAP: Record<string, string | null> = {
 	websearch: null,
 };
 
+/**
+ * The outcome of normalizing a frontmatter `tools` value.
+ *
+ * `tools` is the de-duplicated Pi allowlist, or `undefined` when the agent declared no tools at
+ * all (it then inherits Pi's full default toolset, exactly like an omitted `tools:` in Claude Code).
+ * `unresolved` lists every declared name that is neither a Pi built-in nor a known orchestration
+ * tool, so a caller can tell "nothing declared" apart from "declared, but nothing resolved".
+ */
+export interface NormalizedTools {
+	tools?: string[];
+	unresolved: string[];
+}
+
 /**
  * Normalize a frontmatter `tools` value to a de-duplicated list of Pi tool names.
  * Accepts both YAML spellings in use (`tools: [Read, Bash]` and `tools: Read, Bash`).
- * Returns `undefined` when nothing maps, so the subagent inherits Pi's full default
- * toolset rather than being launched with an empty allowlist.
  */
-export function normalizeTools(value: unknown): string[] | undefined {
+export function normalizeToolsDetailed(value: unknown): NormalizedTools {
 	const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
-	const mapped = raw
+	const declared = raw
 		.filter((t): t is string => typeof t === "string")
-		.map((t) => t.trim().toLowerCase())
-		.filter(Boolean)
+		.map((t) => t.trim())
+		.filter(Boolean);
+	const mapped = declared
+		.map((t) => t.toLowerCase())
 		.map((t) => (t in TOOL_NAME_MAP ? TOOL_NAME_MAP[t] : null))
 		.filter((t): t is string => typeof t === "string");
+	const unresolved = declared.filter((t) => !(t.toLowerCase() in TOOL_NAME_MAP));
 	const deduped = Array.from(new Set(mapped));
-	return deduped.length > 0 ? deduped : undefined;
+	return { tools: deduped.length > 0 ? deduped : undefined, unresolved };
+}
+
+/**
+ * Normalize a frontmatter `tools` value to a de-duplicated list of Pi tool names, or `undefined`
+ * when nothing maps. Prefer {@link normalizeToolsDetailed} where the difference between an omitted
+ * list and an unresolvable one matters — it always does when the result gates a launch.
+ */
+export function normalizeTools(value: unknown): string[] | undefined {
+	return normalizeToolsDetailed(value).tools;
+}
+
+/**
+ * The launch error for an agent whose declared tools resolve to nothing, or `undefined` when the
+ * agent either declared no tools or at least one of them resolved.
+ */
+export function toolsErrorFor(name: string, value: unknown): string | undefined {
+	const { tools, unresolved } = normalizeToolsDetailed(value);
+	if (tools !== undefined || unresolved.length === 0) return undefined;
+	return (
+		`Agent "${name}" declares tools that resolve to no Pi tool: ${unresolved.join(", ")}. ` +
+		`It would launch with every tool instead of the restriction it declares, so it is not launched. ` +
+		`Declare Pi-resolvable names (Read, Write, Edit, Bash, Grep, Glob, ls) in its frontmatter.`
+	);
 }
 
 function loadAgentsFromDir(dir: string, source: "package" | "user" | "project"): AgentConfig[] {
@@ -119,6 +163,7 @@ function loadAgentsFromDir(dir: string, source: "package" | "user" | "project"):
 			name: frontmatter.name,
 			description: frontmatter.description,
 			tools: normalizeTools(frontmatter.tools),
+			toolsError: toolsErrorFor(frontmatter.name, frontmatter.tools),
 			model: typeof frontmatter.model === "string" ? frontmatter.model.trim() : undefined,
 			systemPrompt: body,
 			source,

package/package/corpus/harnesses/pi/extensions/subagent/index.ts

@@ -96,6 +96,20 @@ async function runSingleAgent(
 		};
 	}
 
+	// A restricted agent whose restriction cannot be expressed in Pi is not launched at all: launching it
+	// with the full toolset would be the opposite of what its author declared (see AgentConfig.toolsError).
+	if (agent.toolsError) {
+		return {
+			agent: agentName,
+			agentSource: agent.source,
+			task,
+			exitCode: 1,
+			finalText: "",
+			stderr: agent.toolsError,
+			step,
+		};
+	}
+
 	// An agent that pins no model inherits the dispatching session's model + thinking level.
 	const model = agent.model ?? dispatch.model;
 	const args: string[] = ["--mode", "json", "-p", "--no-session"];

package/package/corpus/hooks/README.md

@@ -13,24 +13,27 @@ Three layers:
 | Quality gate | `Stop` | `scripts/cratis-quality-gate.sh` | one build/test run, only when relevant files changed | exits **2** — the turn does not end |
 
 The Claude Code wiring that fires them is tracked here, in
-[`settings.template.json`](./settings.template.json). Claude reads `.claude/settings.json`, which is
-per-machine and gitignored, so activate the hooks by copying the template once:
+[`settings.template.json`](./settings.template.json). Claude reads `.claude/settings.json`. In a
+repository set up with `cratis ai install`, that file is a **symlink** to this template and follows
+every `cratis ai update`; there is nothing to copy. Where the corpus is present without the CLI,
+activate the hooks by copying the template once:
 
 ```bash
 cp .cratis/ai/hooks/settings.template.json .claude/settings.json
 ```
 
-If you already have a `.claude/settings.json`, merge the template's `hooks` block into it rather
-than overwriting — the rest of that file is yours. Re-copy after the template changes; the copy is
-not a symlink, so it does not update itself. **Edit the template, never the copy**: `.cratis/ai/` is the
-source of truth (see the [corpus README](../README.md)), and
-`scripts/validate-ai-setup.sh` checks the template against the script names this page documents.
+If you already have a `.claude/settings.json` of your own, merge the template's `hooks` block into it
+rather than overwriting — the rest of that file is yours — and re-copy after the template changes.
+**Edit the template, never the copy or the managed file**: `.cratis/ai/` is the source of truth (see the
+[corpus README](../README.md)), and `cratis ai status` reports a hand-edited managed file as drift.
 
 The markdown files in this folder (`agent-stop.md`, `pre-commit.md`) remain *lifecycle guidance* —
 they describe what a hook should do for tools that have no wiring yet.
 
-> Hooks are the one surface with no folder adapter: Claude reads `.claude/settings.json`,
-> Copilot would read `.github/hooks/*.json`. Only the Claude wiring exists today.
+> Hooks are the one surface with no folder adapter: Claude Code reads `.claude/settings.json`;
+> the Pi harness bridges the same three scripts to its own events through the `cratis-hooks`
+> extension under `../harnesses/pi/extensions/`; Copilot would read `.github/hooks/*.json`, and no
+> Copilot wiring ships yet.
 
 ## What is enforced
 
@@ -83,13 +86,16 @@ the managed gates running unchanged.
 `general.md` and the steps in [`agent-stop.md`](./agent-stop.md) — Debug build, specs, Release
 build (with `-p:CratisProxiesOutputPath=` per `general.md`, so the proxy generator does not
 re-run and touch already-correct generated files), frontend lint / compile / compile-specs /
-test, and `validate-ai-setup.sh` for corpus changes.
+test.
 
-## The corpus validator
+## The package drift guards
 
-`scripts/validate-ai-setup.sh` sits outside the three layers: it validates `.cratis/ai/` itself, and both
-the `Stop` gate and the `ai-corpus` CI job run it. Structural, adapter and Codex checks are
-**fatal**; the content drift guards **warn**.
+Three scripts sit outside the three layers and are not bound to a hook event: run
+`scripts/validate-package-subpaths.sh` directly and it chains `validate-type-references.sh` and
+`validate-package-imports.sh` over the same roots. They check the corpus text against the packages a
+repository actually has installed, so they are meaningful only where `node_modules` or a NuGet cache
+exists. The corpus's own structure, catalog and adapters are verified in the `Cratis/AI` repository
+before anything is published; a consuming repository checks its installed copy with `cratis ai status`.
 
 ### Package subpath existence — `scripts/validate-package-subpaths.sh` (warn)
 
@@ -113,11 +119,9 @@ and the `ai-corpus` CI job checks out the tree and installs nothing — so faili
 permanent no-op in CI while turning repos red locally for their own dependency pin. The warning
 names the file, the line and the installed version, and leaves the judgement to a human.
 
-> **What this repository is.** `Cratis/AI` is a corpus of markdown, JSON and a little
-> JavaScript — it has no `Source/`, no `.slnx`, no `package.json` and no C# or TypeScript
-> project of its own. Every `.cs` / `.ts` / `Source/**` reference below describes what the
-> hooks do in a **consuming** repository. Here they are silent, which is the designed
-> behavior, not a broken setup.
+> Every `.cs` / `.ts` / `Source/**` reference below describes what the hooks do in a repository
+> that has such a project. Where there is none — a documentation or corpus-only repository — the
+> hooks are silent, which is the designed behavior, not a broken setup.
 
 **Silent when it cannot judge.** No `jq`, no `node_modules`, a package this repository does not
 depend on, or a package published without an `exports` map: skipped without a word. "Not installed"
@@ -137,8 +141,7 @@ specifiers, nothing else.
 
 Run it standalone, optionally over other roots, and add `CRATIS_HOOKS_SUBPATH_REPORT=1` to see every
 reference and how it resolved rather than only the failures. It invokes Tier 3 before its own gates
-and Tier 2 after its own work, over the same roots, so the single call site in
-`validate-ai-setup.sh` gets all three.
+and Tier 2 after its own work, over the same roots, so one call gets all three.
 
 ### Named import existence — `scripts/validate-package-imports.sh` (warn)
 
@@ -247,7 +250,7 @@ phrases and the guard stays quiet.
 **Silent when it cannot judge.** No `Directory.Packages.props`, no local NuGet cache, or a cache
 holding none of the pinned versions: skipped without a word. It needs no `jq` and no `node_modules`,
 which is why Tier 1 invokes it *above* its own gates rather than beside the Tier 2 call — a backend-
-only repository must still get this check. It adds about 1.4 s to `validate-ai-setup.sh`.
+only repository must still get this check. It adds about 1.4 s to the chained run.
 
 **The allowlist — `scripts/type-references-allowlist.txt`.** Thirteen entries, each with a written
 justification: ASP.NET Core and BCL attributes that live in ref packs (which ship no XML docs at
@@ -288,15 +291,15 @@ gate script find it — `workingDirectoryFrom: ["*.slnx", "*.sln", "**/*.slnx",
 `dotnet build` in whichever directory holds the repository's own solution, preferring one at the
 root because the globs are tried in order. The frontend gates discover `package.json` the same way.
 The same shipped file therefore activates in an application repository, activates in a framework
-repository, and stays quiet in a corpus-only repository like this one, which has no project at all.
+repository, and stays quiet in a repository that has no project at all.
 
 **Overriding it, in order of increasing force.** Set `workingDirectory` on a gate to pin one of
 several candidate projects; drop a `quality-gates.json` of your own in place of the shipped one; or
 point `CRATIS_HOOKS_GATES` at a file anywhere. None of them requires forking the script.
 
 **Profile note.** The C# patterns are application-profile and scoped to `Source/**/*.cs`, which is
-the application source root [`../rules/general.md`](../rules/general.md) documents — not a path in
-this repository, which has no C# at all. A framework-profile repository (Arc, Chronicle,
+the application source root [`../rules/general.md`](../rules/general.md) documents. A
+framework-profile repository (Arc, Chronicle,
 Fundamentals, Components — see [`../rules/framework.md`](../rules/framework.md)) has no vertical
 slices and should disable them in its `cratis-patterns.local.json`; a repository whose application
 source root is not `Source/` re-scopes the `paths` globs there too.
@@ -350,8 +353,7 @@ Each is an explicit, auditable opt-out — none of them is a default.
 The scripts read hook JSON on stdin, so they are directly testable:
 
 The pattern pass and the gate both read the repository they are pointed at, so testing them means
-pointing them at a repository that *has* the thing under test. This corpus has no C# and no
-project, so run those two against a consuming checkout (or a scratch tree), and expect silence here.
+pointing them at a repository that *has* the thing under test; where it is absent, expect silence.
 
 ```bash
 # Pattern pass — expect exit 0, and JSON on stdout only when something matched.

package/package/corpus/hooks/agent-stop.md

@@ -10,11 +10,7 @@ When the agent finishes a session, verify the work against **fresh signals** bef
 
 ## Pick the path for this repository
 
-- **AI corpus repo** — the changes are only under `.cratis/ai/`, `.github/`, or `.claude/` and there is no .NET solution or frontend to build (e.g. this `cratis/AI` repo). Run the AI-setup validator instead of a code build:
-  ```
-  .cratis/ai/hooks/scripts/validate-ai-setup.sh
-  ```
-  Stop only when it passes (symlinks/adapters healthy, frontmatter present, no broken cross-links). Skip the application gates below.
+- **No .NET solution or frontend** — a documentation or corpus-only repository. Run that repository's own documentation and corpus checks instead of a code build, and `cratis ai status` when the change touched the installed AI corpus or its adapters (a hand-edited managed file is reported as drift). Skip the application gates below.
 
 - **Application repo** — there is a .NET solution and/or a frontend. Run the application gates below.
 

package/package/corpus/hooks/scripts/cratis-patterns.json

@@ -78,7 +78,7 @@
             "pattern": "from[[:space:]]+['\"]primereact/dialog['\"]",
             "paths": ["**/*.ts", "**/*.tsx"],
             "exclude_paths": ["**/node_modules/**", "**/dist/**", "**/wwwroot/**", "**/obj/**", "**/bin/**"],
-            "message": "Never import `Dialog` from `primereact/dialog` — use `CommandDialog` / `Dialog` from `@cratis/components`."
+            "message": "Cratis Components 4 has no PrimeReact underneath — a `primereact/dialog` import is a leftover from Components 3. Use `CommandDialog` from `@cratis/components/CommandDialog` or `Dialog` from `@cratis/components/Dialogs`."
         }
     ]
 }

package/package/corpus/hooks/scripts/validate-package-subpaths.sh

@@ -113,8 +113,7 @@ done
 
 # Tier 2 over the same roots: a subpath that resolves says nothing about the *names* imported
 # through it. Kept in its own script — a different question, a different corpus extraction and a
-# different report variable — and invoked from here so the single call site in validate-ai-setup.sh
-# gets both. Tested with -f, not -x, and run through `bash`: a checkout that lost the exec bit must
+# different report variable — and invoked from here so one call to this script gets both. Tested with -f, not -x, and run through `bash`: a checkout that lost the exec bit must
 # not silently drop the guard.
 imports="$(dirname "${BASH_SOURCE[0]}")/validate-package-imports.sh"
 if [[ -f "$imports" ]]; then bash "$imports" "$@" || true; fi