@erclx/aitk 0.10.0 → 0.12.0

package/README.md

@@ -1,5 +1,9 @@
 # aitk
 
+[![npm version](https://img.shields.io/npm/v/@erclx/aitk)](https://www.npmjs.com/package/@erclx/aitk)
+[![CI status](https://img.shields.io/github/actions/workflow/status/erclx/aitk/verify.yml?branch=main)](https://github.com/erclx/aitk/actions/workflows/verify.yml)
+[![License MIT](https://img.shields.io/npm/l/@erclx/aitk)](LICENSE)
+
 One source for your repos' AI conventions. Install once, sync everywhere.
 
 ![Adding the aitk marketplace and installing the plugin in Claude Code](assets/install.png)
@@ -39,7 +43,7 @@ Two limits worth knowing before you install. Claude Code is the only agent runti
 
 Each domain has a canonical source in this repo and a thin install or sync CLI on your side. The links run to internal narrative, written for someone maintaining the toolkit rather than installing it, so skip them on a first pass.
 
-- [Claude Code plugin](.claude/context/claude-plugin.md): skills for planning, review, docs sync, and the git ship chain
+- [Claude Code plugin](.claude/context/claude-plugin/index.md): skills for planning, review, docs sync, and the git ship chain
 - [Governance rules](.claude/context/governance.md): Cursor rules and stacks, installable per project
 - [Standards](.claude/context/standards.md): shared authoring conventions, synced to projects
 - [Snippets](.claude/context/snippets.md): reusable prompts for Claude and Gemini chat

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-diagram/SKILL.md

@@ -55,6 +55,7 @@ One file per kind at `.claude/diagrams/<kind>.md`. Write only the files Step 2 s
 title: <what the entry answers, sentence case>
 description: <the question it settles and the signal that drives it>
 category: <the kind, matching the standard>
+verified: 'TODO: never verified'
 ---
 
 # <Same as title>
@@ -71,8 +72,12 @@ category: <the kind, matching the standard>
 <one to three explanation paragraphs>
 ````
 
+Write `verified` as the literal `TODO: never verified` here, quoted so the colon parses. Step 6 replaces it once a render has been read back, so a SHA written beside the diagram would assert a check that has not run yet. The placeholder is what keeps a render-less project conforming, since Step 5 sends a failed render past Step 6 and nothing stamps the entry. Carry an existing entry's current value across untouched when this pass is rewriting one, and let Step 6 replace that instead.
+
 When sources came from a code scan rather than planning prose, lead the explanation with `Source: code.` and add `Fidelity is lower than prose-driven diagrams. Verify against the project's intent.`
 
+The code paths the explanation cites are what the `claude-docs` sweep watches for staleness, so cite paths that exist and spell them exactly.
+
 Quote node labels containing spaces or special characters with double quotes (`A["Web shell"]`). Avoid parentheses inside labels, they break some renderers. Use `<br/>` for line breaks inside labels.
 
 Run the banned-character scan in `.claude/standards/prose.md` against the whole file, including inside mermaid `subgraph` labels and node text, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it. A colon also works as a replacement inside a label. The pedagogical voice the diagram standard asks for is a yield on voice alone and buys no exemption from these bans.
@@ -123,6 +128,20 @@ Fix the source and re-render. Stop after two correction passes on an entry.
 
 When a defect survives, keep the entry and name the defect in the chat output. A diagram whose author states the flaw is recoverable. A wrong diagram reported as verified is not.
 
+### Stamp the marker
+
+Stamp every entry that passed. Set `verified` to the short SHA of `HEAD` and today's ISO date, and delete any `stale` key the `claude-docs` sweep left on it:
+
+```bash
+git rev-parse --short HEAD
+```
+
+The result is one line, `<sha> <date>`, as in `73e9a3f8 2026-08-02`.
+
+Stamp nothing else. An entry Step 2 left alone was never re-checked, an entry whose defect survived is known wrong, and an entry whose render was skipped was never seen. All three keep the marker they already carry, and Step 7 names the last two. The field means a render was read back and judged correct, so stamping any of these spends the only signal a reader has on a diagram nobody confirmed.
+
+A migration pass stamps on the same rule. Conversion writes entries, Step 5 renders them, and this step reads them back, so the marker records the commit the split was checked against rather than the commit the flat file was written at.
+
 ## Step 7: chat output
 
 ```plaintext

package/claude/skills/claude-docs/SKILL.md

@@ -9,11 +9,11 @@ description: Updates `.claude/` planning docs to reflect decisions made during t
 
 - If no `.claude/` directory exists, stop: `❌ No .claude/ directory found. Run aitk claude init to set up the workflow.`
 
-The bail on a session that changed nothing lives at the end of Step 2, because it needs the diff to decide.
+The skip for a session that changed nothing lives at the end of Step 2, because it needs the diff to decide. It drops the doc rewrite alone. The diff-driven sweeps in Steps 4 and 5 still run.
 
 ## Diff baseline
 
-Steps 2, 4, and 7 share one diff on the usable path. An unusable baseline splits them, per the rule below. Resolve the base ref once and reuse it:
+Steps 2, 4, 5, and 7 share one diff on the usable path. An unusable baseline splits them, per the rule below. Resolve the base ref once and reuse it:
 
 ```bash
 git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
@@ -32,9 +32,9 @@ An unusable baseline costs only the committed half. `git diff <base> HEAD` is em
 
 **Step 2 recovers the committed half.** Read `git log -p -1`, widening to `git log -p -<n>` when the session spans several commits, and read the candidate task files against the working tree. That yields names and content both, which is what lets Step 2 decide on behavior rather than on filenames. A fresh `git init` on `main` with no remote is the ordinary shape of a scaffolded project, so this path carries the evidence rather than covering an edge case.
 
-**Steps 4 and 7 keep the scoped set.** Run them on the working tree and untracked files alone, and skip only when that set comes out empty, each reporting the warning its own step names.
+**Steps 4, 5, and 7 keep the scoped set.** Run them on the working tree and untracked files alone, and skip only when that set comes out empty, each reporting the warning its own step names.
 
-Never substitute the whole tree for a missing baseline, and do not reuse Step 2's commit read in these two for consistency. On a fresh `git init` project the last commit is the scaffold commit, so `git log -p -1` is the whole tree by another route. Step 2 tolerates that because it only reads, and it matches conservatively against outcomes already on the board. These two write, so the same set stubs a wireframe for every uncovered surface in the repository and rewrites every context entry that tree touches.
+Never substitute the whole tree for a missing baseline, and do not reuse Step 2's commit read in these three for consistency. On a fresh `git init` project the last commit is the scaffold commit, so `git log -p -1` is the whole tree by another route. Step 2 tolerates that because it only reads, and it matches conservatively against outcomes already on the board. These three write, so the same set stubs a wireframe for every uncovered surface in the repository, stubs a diagram for every source signal the scaffold introduced, and rewrites every context entry that tree touches.
 
 Widening what a step reads is safe. Widening what a step writes is not.
 
@@ -70,7 +70,17 @@ Keep the match conservative:
 - Match on the behavior an outcome describes, not on filenames or commit subjects. The path match above only narrowed which task files to open.
 - Leave an outcome `[ ]` when the diff is ambiguous. An unmarked shipped outcome costs one manual edit, while a wrongly marked one hides work that never happened.
 
-Stop here when the session shows no divergence **and** the diff matches no queued outcome: `✅ No doc updates needed. Session matched the original plan.` Both conditions have to hold. Shipping a queued task exactly as planned is the ordinary case and it reads as no divergence, so a session-only bail would stop the skill before it reaches the marking step.
+Skip Step 3 when the session shows no divergence **and** the diff matches no queued outcome, reporting `✅ No doc updates needed. Session matched the original plan.` Both conditions have to hold. Shipping a queued task exactly as planned is the ordinary case and it reads as no divergence, so a session-only skip would drop the marking step with it.
+
+Then run Steps 4 through 8. Step 3 is the only one this skips, because it is the only one driven by the session rather than by the diff or the board. A project with an empty task board making a mechanical change satisfies both conditions above, and stopping here would put an uncovered surface and an uncovered diagram kind out of reach in every such project.
+
+Three of the steps that follow write, so each earns the reach separately:
+
+- Steps 4 and 5 stub against the diff. These are why the skip is not a stop. A session that changed no docs is exactly when an uncovered surface or diagram kind goes unnoticed.
+- Step 7 rewrites context entries against the diff. The Diff baseline section above already groups it with Steps 4 and 5 as a scoped-set step, so a quiet session is no different from any other for it.
+- Step 8 reads the board rather than the session. Its board-wide scan exists to clear a plan an earlier run stranded, and a run that stops at Step 2 can never reach one.
+
+This changes which steps the skill reaches. It does not widen what any of them reads. Steps 4, 5, and 7 still take the same scoped set the Diff baseline section defines, and that section's rule is about the input a write is handed rather than about which writes run.
 
 ## Step 3: update
 
@@ -127,13 +137,59 @@ Output one line per finding:
 
 If the sweep finds nothing, skip silently.
 
-## Step 5: flag diagram staleness
+## Step 5: diagram staleness sweep
+
+Skip this step silently when `.claude/diagrams/` does not exist at `pwd` or holds no entry. An entry is any `*.md` other than `index.md`, so a folder carrying the catalog alone is an empty set. A project that has never run `claude-diagram` is not told on every ship that it has holes. When the baseline is unusable, scope the sweep to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the diagram sweep.`
+
+This step writes frontmatter and never content. Mermaid bodies and explanation paragraphs are off limits to it. A change that removes a module does not carry the new correct shape of the picture, so rewriting a diagram from it produces a confident wrong diagram, which is worse than the stale one it replaced. The author redraws by running `claude-diagram`.
+
+Follow `.claude/standards/diagrams.md` for the marker fields this step writes, or `${CLAUDE_SKILL_DIR}/../../standards/diagrams.md` when the project does not have it.
+
+Both findings key on something literally entering or leaving the tree. Anything looser fires on ordinary feature work and rebuilds the ignored warning this sweep replaced.
+
+**Contradicted entries.** For each entry, collect the backticked code paths its explanation cites. When a cited path is in the diff as a delete or a rename and no longer exists in the tree, append a `stale` key to that entry's frontmatter naming the path:
+
+```yaml
+stale: 'src/gov/install.ts no longer exists'
+```
+
+Append that key alone. Never edit `verified`, `title`, `description`, or `category`, and never touch the body. When the entry already carries `stale`, extend the existing line rather than adding a second key.
+
+**Uncovered kinds.** The standard fixes one source signal per kind. Stub a kind when the diff adds its signal file and no entry covers that kind. The trigger is the signal appearing, never a file under it changing, so a branch editing a component folder that `components.md` already covers produces nothing here.
 
-If `.claude/DIAGRAMS.md` exists at `pwd` and this session edited any source `claude-diagram` reads (planning docs, deploy or infrastructure config, top-level component folders), surface a one-line warning:
+| Signal added by the diff                                                                                           | Kind stubbed when absent |
+| ------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| `.claude/REQUIREMENTS.md`                                                                                          | `system-context.md`      |
+| `.claude/ARCHITECTURE.md`                                                                                          | `components.md`          |
+| A deploy or infrastructure config (`Dockerfile`, `.github/workflows/*`, `vercel.json`, `fly.toml`, `compose.yaml`) | `deployment.md`          |
 
-`⚠ DIAGRAMS.md may be stale. Run /claude-diagram`
+Leave `request-flow.md` and `data-pipeline.md` out. Neither has a source signal a diff can point at, so a rule covering them would guess at when they went stale.
 
-Do not regenerate inline. The author decides when to re-run the diagram skill. Skip the step silently when `.claude/DIAGRAMS.md` does not exist.
+Write the stub at `.claude/diagrams/<kind>.md`:
+
+```markdown
+---
+title: <Kind as title case>
+description: 'TODO: name the question this entry settles.'
+category: <the category the standard fixes for this kind>
+verified: 'TODO: never verified'
+---
+
+# <Kind as title case>
+
+TODO: draw this. `<signal path>` entered the tree with no entry covering this kind.
+
+Run `/claude-diagram <kind>` to replace the stub.
+```
+
+No mermaid fence. An empty stub is visible debt that reaches review through the branch diff, while a generated diagram nobody rendered is invisible debt that reads as verified. A fence here invites the next session to fill it in without a render.
+
+Output one line per finding:
+
+- `⚠ Diagram stale: .claude/diagrams/<kind>.md cites <path>, which left the tree`
+- `📝 Stubbed: .claude/diagrams/<kind>.md`
+
+If the sweep finds nothing, skip silently. An ordinary change that adds no signal and deletes no cited path produces no output at all.
 
 ## Step 6: flag CLAUDE.md drift
 
@@ -202,3 +258,5 @@ Output one line per file updated:
 If no files were updated and nothing was swept, output:
 
 `✅ No changes needed.`
+
+Suppress that line when Step 2 already reported no doc updates. It closes the run on its own, and emitting both leaves a quiet session reporting success twice for one outcome.

package/claude/skills/create-standard/SKILL.md

@@ -7,7 +7,7 @@ description: Creates a new standard file in `standards/` (toolkit repo) or `.cla
 
 Read these files in parallel:
 
-- `${CLAUDE_SKILL_DIR}/references/standard.md`: the meta-standard for a standard's shape, frontmatter, and structure
+- `.claude/standards/standard.md` from the project root: the meta-standard for a standard's shape, frontmatter, and structure
 - `.claude/standards/prose.md` from the project root: prose conventions for all generated text
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.

package/claude/skills/toolkit-cli/SKILL.md

@@ -35,4 +35,4 @@ What each `aitk` sync or install command does to existing files in a target proj
 
 ## Source of truth
 
-- Full semantics live in the toolkit's `.claude/context/tooling.md`, `standards.md`, and `claude-plugin.md`. This skill is the target-session summary. When they disagree, the context docs win.
+- Full semantics live in the toolkit's `.claude/context/tooling.md`, `standards.md`, and `claude-plugin/`. This skill is the target-session summary. When they disagree, the context docs win.

package/docs/agents.md

@@ -136,6 +136,16 @@ headlessly, so a call that names its stack or category is unchanged.
 `aitk snippets install`. Both resolve the target before anything else, so a path
 that does not exist fails rather than being scaffolded.
 
+`aitk gov regen` is the one governance verb that runs against the toolkit root,
+because the `.claude/rules/` it writes there is produced output rather than an
+operator's working copy. It reads the stack recorded in `internal/governance.toml`,
+installs it alongside anything under `internal/rules/`, and clears the
+destination first so a rule the record stopped naming disappears. It takes
+`--root <path>` and defaults to the toolkit root, prints nothing on success, and
+reports the reason on stderr with exit 1 when the record names a stack or rule
+that does not resolve. `scripts/core/regen-claude-copies.sh` calls it, and the
+Consumed copies stage of `bun run check` asserts the result is committed.
+
 `aitk sync` runs every installed domain sync, then offers to commit the result
 and open a pull request. Under `AITK_NON_INTERACTIVE=1` it applies the domain
 syncs and then refuses the git workflow, reporting the branch and commit it
@@ -229,6 +239,8 @@ The record carries every scenario with the arms that declare, plus `totalScenari
 - `aitk docs list [--json]` lists the downstream catalog: the consumer-facing `docs/` surface plus per-domain narrative from `.claude/context/` when that root is present. Toolkit-internal context entries (`ci`, `development`, `extensions`, `sandbox`) are dropped. From a registry install the context section is absent rather than empty.
 - `aitk docs <topic>` prints one doc to stdout, resolved by exact name from `docs/` first, then `.claude/context/`. Any doc the install carries is reachable by name, including the toolkit-internal topics the list omits.
 
+A domain too large for one file splits into `<domain>/` with a generated `index.md`, and both verbs name it by the folder. `aitk docs <domain>` prints that index, which is the catalog routing to the sub-area files, and the listing describes it from the index's `subtitle` where a sibling file supplies `description`. A sibling file wins over a folder of the same name. A folder carrying no `index.md` is absent from both, since a catalog is what makes the sub-areas reachable.
+
 Data prints to stdout and the frame to stderr, so `aitk docs <topic> > out.md` captures clean markdown. With no topic and no verb, `aitk docs` runs `list`. An unknown topic names the available topics on stderr and exits 1.
 
 Only a `---` block opening on the first line counts as frontmatter, so a document body carrying horizontal rules emits whole.

package/docs/ai-workflow.md

@@ -20,12 +20,13 @@ Project docs live in `.claude/` at the project root.
 ├── ARCHITECTURE.md  ← technical design decisions
 ├── DESIGN.md        ← visual intent and token decisions (UI projects)
 ├── WIREFRAMES.md    ← ASCII wireframes: layout, UI copy, and interaction rules (UI projects)
+├── diagrams/        ← one Mermaid entry per diagram kind with a generated index.md
 ├── tasks/           ← one file per task with a generated index.md, gitignored local scratch
 ├── context/         ← per-domain narrative loaded on demand via index.md
 └── rules/           ← path-scoped governance rules, written by aitk gov install
 ```
 
-Three tiers of context load with different cost: always-loaded (root `CLAUDE.md`, `.claude/REQUIREMENTS.md`, `.claude/ARCHITECTURE.md`), path-scoped lazy (`.claude/rules/<scope>.md` with `paths:` glob), and on-demand lookup (`.claude/context/<domain>.md` discovered via `.claude/context/index.md`). See [the context model](../.claude/context/context-model.md) for the full picture.
+Three tiers of context load with different cost: always-loaded (root `CLAUDE.md`, `.claude/REQUIREMENTS.md`, `.claude/ARCHITECTURE.md`), path-scoped lazy (`.claude/rules/<scope>.md` with `paths:` glob), and on-demand lookup (`.claude/context/<domain>.md`, or `.claude/context/<domain>/` once a domain outgrows one file, discovered via `.claude/context/index.md`). See [the context model](../.claude/context/context-model.md) for the full picture.
 
 Run `aitk init` to seed the `.claude/` directory, a root `CLAUDE.md` file, and `.claude/rules/` in one pass. `aitk init` chains claude init and governance install. Claude Code auto-loads every file in `.claude/rules/` at session start, applying always-on rules unconditionally and path-scoped rules to files matching their `paths:` glob.
 

package/docs/operating-model.md

@@ -103,4 +103,4 @@ port-collision detail.
 
 - [Claude Code and git worktrees](../wiki/claude-worktrees.md) for the isolation and fan-out mechanics
 - [Claude Code subagents](../wiki/claude-subagents.md) for in-session parallelism without worktrees
-- `.claude/context/claude-plugin.md` for how the skills in the loop are categorized
+- `.claude/context/claude-plugin/skills.md` for how the skills in the loop are categorized

package/docs/target-projects.md

@@ -57,7 +57,7 @@ Scaffold installs tooling and seeds. It does not fill the planning docs or the d
 
 1. Fill `.claude/REQUIREMENTS.md` and `.claude/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write.
 2. For a UI project, invoke `aitk:claude-design-propose` to draft `.claude/DESIGN.md` from the requirements and a `## Personality` section. Skip for non-UI projects.
-3. Optionally invoke `aitk:claude-diagram` to draft entries under `.claude/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds. A machine without a renderer still gets the diagrams and is told which check was skipped.
+3. Optionally invoke `aitk:claude-diagram` to draft entries under `.claude/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds. A machine without a renderer still gets the diagrams and is told which check was skipped. Each entry records the commit and date it was last verified against, and `aitk:claude-docs` maintains that record on every ship: it annotates an entry whose cited code path left the tree and stubs a kind whose source signal arrived uncovered. The sweep writes frontmatter only, so a diagram's picture and prose change when you redraw them and at no other time.
 4. Start the feature loop. See [AI workflow](ai-workflow.md) for the per-feature sequence.
 
 ### Stack decision
@@ -179,5 +179,5 @@ Sync also refuses a target whose working tree is dirty, so commit or stash befor
 
 - [agents](agents.md): CLI flags, exit codes, and JSON output shapes
 - [AI workflow](ai-workflow.md): feature-development loop inside a toolkit-managed project
-- [tooling](../.claude/context/tooling.md), [governance](../.claude/context/governance.md), [claude plugin](../.claude/context/claude-plugin.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards.md): per-domain mechanics
+- [tooling](../.claude/context/tooling.md), [governance](../.claude/context/governance.md), [claude plugin](../.claude/context/claude-plugin/index.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards.md): per-domain mechanics
 - [sandbox](../.claude/context/sandbox.md): scenario catalog for verifying domain flows

package/docs/visual-design-workflow.md

@@ -130,7 +130,7 @@ Zero or one yes: tier 0. Two or three: tier 1. Four: tier 2. Resist over-tiering
 
 - [Stitch](../wiki/stitch.md): Gemini-powered design product with the MCP server that anchors tier 1
 - [Claude Design](../wiki/claude-design.md): first-party hosted design product and handoff bundle
-- `.claude/context/claude-plugin.md`: how to decide between workflow and domain-knowledge skills
+- `.claude/context/claude-plugin/skills.md`: how to decide between workflow and domain-knowledge skills
 - [Visual wireframes](../wiki/visual-wireframes.md): Excalidraw research and setup for the tier 1 wireframe companion
 - [Community skills and plugins](../wiki/community-skills.md): catalog of frontend design skills and integrations
 - [Community MCP servers](../wiki/community-mcp-servers.md): catalog of MCPs referenced across all tiers

package/governance/rules/claude/580-readme.md

@@ -8,4 +8,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/readme.md` for structure, required and optional sections, heading hierarchy, and what to link out rather than inline. It is the single source.
+- Follow `.claude/standards/readme.md` for voice, structure, required and optional sections, heading hierarchy, badge classes, per-project-type content, and what to link out rather than inline. It is the single source.

package/governance/rules/claude/591-standard-authoring.md

@@ -0,0 +1,13 @@
+---
+description: Enforce shape, scope, and success criterion for authoring convention files
+paths:
+  - '.claude/standards/**/*.md'
+  - 'standards/**/*.md'
+---
+
+# Standard authoring standards
+
+## Authority
+
+- Follow `.claude/standards/standard.md` for a standard's frontmatter, shape, scope, and success criterion. It is the single source.
+- Read it before writing or editing a standard. Do not work the shape from memory.

package/governance/stacks/base.toml

@@ -1,2 +1,2 @@
 extends = ""
-rules = ["000-constitution", "010-testing", "020-concurrency", "030-error-handling", "040-performance", "050-logging", "060-naming", "070-planning", "080-config-comments", "500-prose", "510-context", "520-wireframes", "530-requirements", "540-architecture", "550-design", "555-tasks", "560-diagrams", "570-skill", "580-readme", "590-rule-authoring"]
+rules = ["000-constitution", "010-testing", "020-concurrency", "030-error-handling", "040-performance", "050-logging", "060-naming", "070-planning", "080-config-comments", "500-prose", "510-context", "520-wireframes", "530-requirements", "540-architecture", "550-design", "555-tasks", "560-diagrams", "570-skill", "580-readme", "590-rule-authoring", "591-standard-authoring"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-claude-copies.sh

@@ -23,4 +23,13 @@ mirror_dir "$PROJECT_ROOT/snippets" "$PROJECT_ROOT/.claude/snippets" -name "*.md
 
 # `internal/` is the surface the plugin does not symlink. Mirrored on its own so
 # toolkit sessions read it at a `.claude/` path like every other consumed copy.
-mirror_dir "$PROJECT_ROOT/internal" "$PROJECT_ROOT/.claude/internal" -name "*.md"
+# `internal/rules/` is excluded because it lands in `.claude/rules/` below, and
+# mirroring it here too would publish each rule at a second inert path. The
+# exclusion is anchored to that one folder, since an unanchored `*/rules/*` would
+# also drop a later `internal/standards/rules/` and report nothing for it.
+mirror_dir "$PROJECT_ROOT/internal" "$PROJECT_ROOT/.claude/internal" -name "*.md" -not -path "$PROJECT_ROOT/internal/rules/*"
+
+# `.claude/rules/` is a subset rather than a mirror, so it resolves through the
+# stack machinery instead of a fourth `mirror_dir` call. The record naming the
+# subset is `internal/governance.toml`.
+bun "$PROJECT_ROOT/src/cli.ts" gov regen --root "$PROJECT_ROOT"

package/scripts/core/verify.sh

@@ -132,7 +132,7 @@ main() {
 
   log_step "Consumed copies"
   run_check "bash $PROJECT_ROOT/scripts/core/regen-claude-copies.sh" "Consumed-copy regen failed"
-  assert_no_drift ".claude/standards .claude/snippets .claude/internal" "Consumed copies drifted. Run bun run check and commit .claude/standards, .claude/snippets, and .claude/internal."
+  assert_no_drift ".claude/standards .claude/snippets .claude/internal .claude/rules" "Consumed copies drifted. Run bun run check and commit .claude/standards, .claude/snippets, .claude/internal, and .claude/rules."
   log_info "Consumed copies clean"
 
   log_step "Skill references"

package/scripts/docs/list.sh

@@ -38,8 +38,33 @@ is_internal_topic() {
   esac
 }
 
+# Emits `name<TAB>description<TAB>target` per context entry, sorted so a domain
+# split into a folder lands in its alphabetical place rather than after every
+# file. Matches listTopics in src/docs/read.ts, which sorts both together.
+collect_context() {
+  local file name description
+  {
+    while IFS= read -r file; do
+      name=$(basename "$file" .md)
+      [ "$name" = "index" ] && continue
+      is_internal_topic "$name" && continue
+      description=$(read_frontmatter_field "$file" "description")
+      printf '%s\t%s\t%s\n' "$name" "$description" ".claude/context/$name.md"
+    done < <(find "$CONTEXT_DIR" -maxdepth 1 -type f -name "*.md")
+
+    # A split domain is named by its folder and described by its generated
+    # index, which carries subtitle where a sibling file carries description
+    while IFS= read -r file; do
+      name=$(basename "$(dirname "$file")")
+      is_internal_topic "$name" && continue
+      description=$(read_frontmatter_field "$file" "subtitle")
+      printf '%s\t%s\t%s\n' "$name" "$description" ".claude/context/$name/index.md"
+    done < <(find "$CONTEXT_DIR" -mindepth 2 -maxdepth 2 -type f -name "index.md")
+  } | sort
+}
+
 list_text() {
-  local file name description category
+  local file name description category target
   log_step "Docs"
   while IFS= read -r file; do
     name=$(basename "$file" .md)
@@ -53,13 +78,9 @@ list_text() {
   # Absent in a registry install, which ships docs/ without .claude/
   if [ -d "$CONTEXT_DIR" ]; then
     log_step "Domain context"
-    while IFS= read -r file; do
-      name=$(basename "$file" .md)
-      [ "$name" = "index" ] && continue
-      is_internal_topic "$name" && continue
-      description=$(read_frontmatter_field "$file" "description")
+    while IFS=$'\t' read -r name description target; do
       log_info "$name : $description"
-    done < <(find "$CONTEXT_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+    done < <(collect_context)
   fi
 }
 
@@ -76,7 +97,7 @@ emit_json_entry() {
 }
 
 list_json() {
-  local file name description category
+  local file name description category target
   JSON_FIRST=1
   printf '['
   while IFS= read -r file; do
@@ -89,13 +110,9 @@ list_json() {
   done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
 
   if [ -d "$CONTEXT_DIR" ]; then
-    while IFS= read -r file; do
-      name=$(basename "$file" .md)
-      [ "$name" = "index" ] && continue
-      is_internal_topic "$name" && continue
-      description=$(read_frontmatter_field "$file" "description")
-      emit_json_entry "$name" "$description" "" ".claude/context/$(basename "$file")"
-    done < <(find "$CONTEXT_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+    while IFS=$'\t' read -r name description target; do
+      emit_json_entry "$name" "$description" "" "$target"
+    done < <(collect_context)
   fi
   printf ']'
 }

package/src/commands/gov.ts

@@ -5,6 +5,7 @@ import type { Command } from 'commander'
 import { registerPassThroughVerbs } from '@/commands/pass-through'
 import { PROJECT_ROOT } from '@/exec'
 import { createGovAdapter } from '@/gov/adapter'
+import { regenConsumedRules } from '@/gov/consumed'
 import { hasStandards, installRules, lookupRules } from '@/gov/install'
 import { buildRulesPayload, listRuleFiles } from '@/gov/payload'
 import {
@@ -39,6 +40,10 @@ interface InstallOptions {
   readonly add?: string
 }
 
+interface RegenOptions {
+  readonly root?: string
+}
+
 export function register(program: Command): void {
   const gov = program
     .command('gov')
@@ -95,9 +100,44 @@ export function register(program: Command): void {
       process.exitCode = await runBuild(target)
     })
 
+  gov
+    .command('regen')
+    .description("Rebuild a repository's own .claude/rules/ from its record")
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository root to regenerate', PROJECT_ROOT)
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads internal/governance.toml and installs the stack it names, plus',
+        'any rules under internal/rules/. Unlike install and sync, this runs',
+        'against the toolkit root, whose .claude/rules/ is produced output.',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RegenOptions) => {
+      process.exitCode = await runRegen(opts)
+    })
+
   registerPassThroughVerbs(gov, 'gov', PASS_THROUGH_VERBS)
 }
 
+/**
+ * Silent on success so the consumed-copy stage that calls it stays as quiet as
+ * the three `mirror_dir` lines it sits beside. The installed set is readable on
+ * disk, so printing it would only add noise to every `bun run check`.
+ */
+async function runRegen(opts: RegenOptions): Promise<number> {
+  const result = await regenConsumedRules(resolve(opts.root ?? PROJECT_ROOT))
+
+  if (!result.ok) {
+    process.stderr.write(`Consumed-rules regen failed: ${result.reason}\n`)
+    return 1
+  }
+
+  return 0
+}
+
 /**
  * Renders the target-relative path the prompt quotes, keeping the argument the
  * caller typed rather than the absolute path it resolves to.

package/src/docs/read.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { basename, join } from 'node:path'
+import { basename, dirname, join } from 'node:path'
 import { stripFrontmatter } from '@/frontmatter'
 
 const INDEX_TOPIC = 'index'
@@ -16,14 +16,25 @@ export interface ResolvedTopic {
   readonly rel: string
 }
 
+/**
+ * A domain too large for one file splits into `<domain>/` with a generated
+ * `index.md`, so a topic names either a sibling file or such a folder. Both
+ * spellings resolve to the same name a caller types.
+ */
 export function resolveTopic(
   root: string,
   topic: string,
 ): ResolvedTopic | undefined {
   for (const dir of ROOTS) {
-    const rel = join(dir, `${topic}.md`)
-    const path = join(root, rel)
-    if (existsSync(path)) return { path, rel }
+    const candidates = [
+      join(dir, `${topic}.md`),
+      join(dir, topic, `${INDEX_TOPIC}.md`),
+    ]
+
+    for (const rel of candidates) {
+      const path = join(root, rel)
+      if (existsSync(path)) return { path, rel }
+    }
   }
 
   return undefined
@@ -41,14 +52,21 @@ export function listTopics(root: string): string[] {
     const cwd = join(root, dir)
     if (!existsSync(cwd)) continue
 
-    const names = [
+    const files = [
       ...new Bun.Glob('*.md').scanSync({ cwd, onlyFiles: true, dot: true }),
     ]
       .map((name) => basename(name, '.md'))
       .filter((name) => name !== INDEX_TOPIC)
-      .sort()
 
-    topics.push(...names)
+    const folders = [
+      ...new Bun.Glob(`*/${INDEX_TOPIC}.md`).scanSync({
+        cwd,
+        onlyFiles: true,
+        dot: true,
+      }),
+    ].map((name) => dirname(name))
+
+    topics.push(...[...files, ...folders].sort())
   }
 
   return topics

package/src/gov/consumed.ts

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import {
+  installRules,
+  installedRulesDir,
+  lookupRules,
+  type RuleSource,
+  ruleSubdir,
+} from '@/gov/install'
+import { mergeExtraRules, resolveRules } from '@/gov/stacks'
+
+export const RECORD_REL = join('internal', 'governance.toml')
+
+const INTERNAL_RULES_REL = join('internal', 'rules')
+
+/** The stack a repository installs into its own `.claude/rules/`. */
+export interface ConsumedRecord {
+  readonly stack: string
+  readonly add: readonly string[]
+}
+
+export type ConsumedResult =
+  | { readonly ok: true; readonly installed: readonly string[] }
+  | { readonly ok: false; readonly reason: string }
+
+export function consumedRecordPath(root: string): string {
+  return join(root, RECORD_REL)
+}
+
+export function internalRulesDir(root: string): string {
+  return join(root, INTERNAL_RULES_REL)
+}
+
+/**
+ * Reads the record naming the consumed stack. A file with no `stack` reads the
+ * same as no file at all, since neither tells the producer what to install and
+ * the caller's message covers both.
+ */
+export function readConsumedRecord(root: string): ConsumedRecord | undefined {
+  const path = consumedRecordPath(root)
+  if (!existsSync(path)) return undefined
+
+  const parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+    string,
+    unknown
+  >
+  const stack = typeof parsed.stack === 'string' ? parsed.stack : ''
+  if (stack === '') return undefined
+
+  return {
+    stack,
+    add: Array.isArray(parsed.add)
+      ? parsed.add.filter(
+          (rule): rule is string => typeof rule === 'string' && rule !== '',
+        )
+      : [],
+  }
+}
+
+/**
+ * Lists rules authored under `internal/rules/`. These govern toolkit authoring
+ * against paths only this repository has, so they install into the consumed
+ * copy without ever entering `governance/rules/`, which ships to targets.
+ */
+export function listInternalRules(root: string): RuleSource[] {
+  const dir = internalRulesDir(root)
+  if (!existsSync(dir)) return []
+
+  return [...new Bun.Glob('**/*.md').scanSync({ cwd: dir, onlyFiles: true })]
+    .sort()
+    .map((rel) => {
+      const src = join(dir, rel)
+      return { rule: basename(rel, '.md'), src, subdir: ruleSubdir(src, dir) }
+    })
+}
+
+/**
+ * Rebuilds a repository's own `.claude/rules/` from its record. Unlike
+ * `gov install` and `gov sync`, this runs against the toolkit root on purpose:
+ * those two refuse it because a target's rules are the operator's to edit,
+ * while this destination is produced output that happens to live beside its
+ * source.
+ */
+export async function regenConsumedRules(
+  root: string,
+): Promise<ConsumedResult> {
+  const record = readConsumedRecord(root)
+  if (record === undefined) {
+    return { ok: false, reason: `No stack recorded at ${RECORD_REL}` }
+  }
+
+  const resolution = resolveRules(root, record.stack)
+  if (!resolution.ok) {
+    return { ok: false, reason: `Stack not found: ${resolution.missingStack}` }
+  }
+
+  const { found, missing } = lookupRules(
+    root,
+    mergeExtraRules(resolution.rules, record.add.join(',')),
+  )
+  if (missing.length > 0) {
+    return { ok: false, reason: `No source for: ${missing.join(', ')}` }
+  }
+
+  const internal = listInternalRules(root)
+  const stackRules = new Set(found.map((entry) => entry.rule))
+  const shadowed = internal
+    .filter((entry) => stackRules.has(entry.rule))
+    .map((entry) => entry.rule)
+  if (shadowed.length > 0) {
+    return {
+      ok: false,
+      reason: `Internal rules shadow stack rules: ${shadowed.join(', ')}`,
+    }
+  }
+
+  // Clearing first is what makes a rule the record stopped naming disappear.
+  // Copying over the destination would leave it behind as an unsourced file,
+  // which is the state this producer exists to end.
+  await rm(installedRulesDir(root), { recursive: true, force: true })
+
+  const installed = [
+    ...(await installRules(found, root)),
+    ...(await installRules(internal, root)),
+  ]
+
+  return { ok: true, installed: installed.sort() }
+}

package/src/indexes/render.ts

@@ -161,21 +161,41 @@ function renderIndex(
       }
     })
   } else {
-    for (const entry of entries) {
-      out += formatEntry(entry)
-    }
+    /**
+     * Flat mode sorts sub-catalogs among the files rather than after them. A
+     * folder and a file are both one domain to a reader scanning the catalog,
+     * so a trailing folder reads as absent from the alphabetical run it belongs
+     * in. Grouped mode keeps its own heading below, where a category is the
+     * organizing key and alphabetical position carries no meaning.
+     */
+    const lines = [
+      ...entries.map((entry) => ({
+        key: entry.name,
+        text: formatEntry(entry),
+      })),
+      ...subCatalogs.map((catalog) => ({
+        key: catalog.name,
+        text: formatSubCatalog(catalog),
+      })),
+    ].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+
+    for (const line of lines) out += line.text
   }
 
-  if (subCatalogs.length > 0) {
-    if (hasCategories) out += '\n## Sub-catalogs\n\n'
+  if (hasCategories && subCatalogs.length > 0) {
+    out += '\n## Sub-catalogs\n\n'
     for (const catalog of subCatalogs) {
-      out += `- [${catalog.title}](${catalog.name}/${INDEX_FILE}): ${catalog.subtitle}\n`
+      out += formatSubCatalog(catalog)
     }
   }
 
   return out
 }
 
+function formatSubCatalog(catalog: SubCatalog): string {
+  return `- [${catalog.title}](${catalog.name}/${INDEX_FILE}): ${catalog.subtitle}\n`
+}
+
 function formatEntry(entry: IndexEntry): string {
   return `- [${entry.title}](${entry.name}): ${entry.description}\n`
 }

package/standards/context.md

@@ -90,6 +90,8 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Past roughly 150 lines, check two things before adding more: whether the entry still covers a single domain, and whether it has filled with content `ls` or `--help` reproduces. Fix whichever is true rather than trimming to hit a number.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
 - Split into a folder (`.claude/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
+- Keep a split domain's `index.md` generated. The catalog body is rewritten on every regen, so the domain's own overview and layout belong in a sibling file rather than in it, and the `subtitle` is what names the file to start with.
+- Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and turns a one-line edit into a whole-file rewrite that conflicts with any sibling branch. This is what forced the split above.
 
 ## Examples
 

package/standards/diagrams.md

@@ -24,8 +24,14 @@ An entry that fails these is non-conforming regardless of whether it satisfies e
 - `title` (required): sentence case, names what the entry answers (`System context`, `Request flow`), not what it draws.
 - `description` (required): one line on which question the entry settles and which source signal drives it.
 - `category` (required): the diagram kind, one of the five in Entry kinds. It is the grouping field `aitk indexes regen` renders headings from.
+- `verified` (required): the short commit SHA an entry was last checked against and the ISO date of that check, separated by a space (`73e9a3f8 2026-08-02`). A stub nobody has drawn yet carries the literal `TODO: never verified` instead, which is the one other accepted value.
+- `stale` (optional): one line naming what changed under the entry since that check. Absent on an entry nothing has flagged.
 
-All three feed `.claude/diagrams/index.md` when regenerated. The catalog sorts categories alphabetically rather than in narrative order, so an entry cannot rely on its position to introduce another. Each entry names its own starting point, and the catalog's subtitle routes a first-time reader to the system context entry.
+The first three feed `.claude/diagrams/index.md` when regenerated. The catalog sorts categories alphabetically rather than in narrative order, so an entry cannot rely on its position to introduce another. Each entry names its own starting point, and the catalog's subtitle routes a first-time reader to the system context entry.
+
+The marker fields reach the catalog through neither route. `aitk indexes regen` reads `title`, `description`, and `category` and ignores every other key, so a marker changes no generated file. A reader picks it up by opening the entry, which is where it sits above the diagram and where anyone deciding whether to trust the picture is already standing.
+
+Two writers share the marker and neither touches the other's field. A pass that renders an entry and reads the picture back sets `verified` and clears `stale`. The `claude-docs` sweep appends `stale` and never edits `verified`. Keeping them separate is what lets a reader tell a diagram nobody has checked since the code moved from one that was checked and found correct.
 
 ## Entry kinds
 
@@ -72,7 +78,7 @@ A second entry for one kind takes a suffixed name (`request-flow-admin.md`) and
 
 - One to three short paragraphs below each diagram. Plain English and pedagogical.
 - Lead with what the diagram shows. Follow with why this shape was chosen and what alternative was rejected, when the choice was non-obvious.
-- Reference one or two specific code paths the reader can open. Do not enumerate every file.
+- Reference one or two specific code paths the reader can open. Do not enumerate every file. Backticked paths here are also the set the `claude-docs` sweep watches, so a path cited in this section is one a later session gets told about when it leaves the tree.
 - Do not duplicate prose across entries. An entry that restates its neighbor has taken the neighbor's job.
 - The audience is mixed, so vocabulary runs as a gradient across the set. `System context` assumes no knowledge of the repository. `Deployment` may assume the reader has read the others.
 
@@ -101,5 +107,7 @@ Reference the context entry by path when a reader needs the mechanism. The diagr
 - When the system changes, update the entries whose source signal changed and leave the rest alone. Rewriting the folder wholesale reproduces the defect the per-kind split exists to end.
 - A diagram showing a defunct host or library is worse than no diagram. Audit the affected entry in the same PR.
 - `System context` has no named source signal beyond `.claude/REQUIREMENTS.md`, so nothing tells a session it went stale. Re-read it when the boundary or the set of external dependencies moves.
+- The `claude-docs` sweep watches two things and writes frontmatter only. It appends `stale` when a path an entry cites leaves the tree, and it stubs a kind when a diff adds the source signal that kind is drawn from. Diagram bodies and explanation paragraphs are off limits to it, because a change that removes a module does not carry the new correct shape of the picture.
+- That watch samples thinly. It sees the one or two paths an entry happened to cite and nothing else, so a change elsewhere leaves the entry looking current. `verified` is what covers the gap, and an entry whose date sits far behind the branch is due a read whether or not anything flagged it.
 - Mermaid blocks are inside fenced code, so the prose-standards hook ignores them. The explanation paragraphs around them are still prose. Follow `standards/prose.md`.
 - The punctuation bans still apply to node and subgraph labels, and nothing checks them there. An em dash in a label passes every gate the repository has, so read the labels before shipping the entry.

package/standards/index.md

@@ -16,6 +16,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Requirements reference](requirements.md): Shape and content rules for .claude/REQUIREMENTS.md
 - [Governance rule reference](rule.md): Rule frontmatter, body shape, and voice for .claude/rules files
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
+- [Standard reference](standard.md): Shape and content rules for authoring a standard
 - [Tasks reference](tasks.md): Folder layout, filename convention, and content rules for .claude/tasks/
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, commits, and tags
 - [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/readme.md

@@ -36,6 +36,23 @@ Scoped to the README at a repository root. A nested README documenting a folder,
 - Do not include detailed contribution guidelines. Reference `CONTRIBUTING.md`.
 - Do not include extensive troubleshooting guides. Use a wiki or separate documentation.
 
+### Badges
+
+A badge earns its place by carrying a fact the reader cannot get from the page they are already on. Three classes pass that test.
+
+- Package version, which reports what the registry actually published rather than what the working tree claims
+- Build or CI status, which reports whether the checks are currently passing
+- License, which passes because a README rendered on a registry page has no host sidebar stating it
+
+Stars, forks, download counts, language chips, and "made with" badges fail. The first three restate what a repository host already renders above the README, and the rest decorate.
+
+- Cap the block at four. A fifth costs more scanning than any badge repays.
+- Give each badge alt text naming what it reports rather than the service that renders it. Write `npm version`, not `shields.io`.
+- Link each badge to the page a doubting reader would check next, which is the registry listing for a version badge and the run history for a status badge. A red badge with no route to the failing run reports a problem and withholds the only thing the reader wants.
+- Pin a status badge to the branch whose health it claims to report, and confirm the workflow actually runs on that branch. A workflow triggered by pull requests alone never runs on the default branch, so an unpinned badge reports whichever branch ran last and a pinned one reports nothing at all. Fix the trigger, or drop the badge under the rule below.
+- Verify a badge by the value it renders, not by its status code. A badge service answers 200 for a query it cannot satisfy, so a blank badge and a working one look identical to a status check.
+- Zero badges is a correct answer. A private project with no registry presence and no CI has nothing that passes the test, and an empty block beats a padded one.
+
 ## Content
 
 - Open public-facing READMEs with universal problems any reader recognizes, not repo-specific artifact names. Save artifact names for feature or "What is inside" sections.
@@ -44,6 +61,10 @@ Scoped to the README at a repository root. A nested README documenting a folder,
 - For libraries/tools: include API quickstart
 - For applications/products: include usage instructions and configuration options
 - For CLI tools: include command examples with flags
+- For agent-facing repositories: name the file an agent loads first and the command that lists what the project exposes
+- For marketplace-distributed plugins: give the install command for every channel the project publishes to
+
+A project is often several of these at once. Cover every type that applies rather than picking the closest one. A repository that ships a CLI, distributes a plugin, and holds agent conventions owes its reader all three.
 
 ## Examples
 

package/{claude/skills/create-standard/references → standards}/standard.md

@@ -1,33 +1,52 @@
 ---
 title: Standard reference
 description: Shape and content rules for authoring a standard
-consumers: create-standard
 ---
 
 # Standard reference
 
+Applies to each authored standard in the folder. Skip for `index.md`, which is generated rather than authored.
+
 ## Overview
 
-A standard is a target-facing authoring convention for one document type. It installs into a project under `.claude/standards/` and is consumed by skills and developers alike. One standard governs one doc type. Split unrelated conventions into separate files.
+A standard is a target-facing authoring convention for one document type. It installs into a project under `.claude/standards/` and is consumed by skills and developers alike. This file governs itself, so every rule below applies to it.
+
+## What a working standard looks like
+
+A standard answers these questions. Each can be answered wrong, which is what makes them a test rather than a preamble.
+
+- Which single document type does this govern, and where does that document live?
+- Can an author who has seen no example produce a conforming document from this file alone?
+- Does every rule state a shape the document must have, rather than a fact about the repository that happens to store it?
+- What does a conforming document achieve, stated so a reviewer can call one non-conforming without appealing to taste?
+
+A standard failing these questions is non-conforming even when it satisfies every shape rule below.
+
+## Scope
+
+- Govern one document type per standard. Split unrelated conventions into separate files.
+- Name no path, filename, or folder outside the document type the standard governs. A standard reaches projects whose layout is their own, so a path borrowed from the authoring repository is wrong in a target and nothing reports it.
+- State the rule, never the mechanism enforcing it. Hooks, scripts, checks, and skill catalogs are facts about one repository. Name the condition the document must meet and let the enforcing surface name its own case.
+- Invent inline examples rather than citing a real file elsewhere in the project. A cited file moves or is deleted and the standard goes stale in silence.
 
 ## Frontmatter
 
-- Start the file with a frontmatter block carrying `title` and `description`.
-- `title`: names the doc type in sentence case, suffixed `reference` (`Commit reference`, `Branch reference`).
+- Start the file with a frontmatter block carrying at least `title` and `description`. A consuming surface may require more.
+- `title`: names the doc type in sentence case, suffixed `reference` (`Commit reference`, `Branch reference`)
 - `description`: one line naming what the standard covers. It becomes the index link label on install.
 
 ## Structure
 
-- Use sentence case for every heading.
+- Use sentence case for every heading
 - Flat `##` rule groups for a single-topic standard. Group `##` headers by concern for a multi-topic one.
 - When one `##` section covers more than one sub-concern, split its bullets into `###` subgroups, one subgroup per sub-concern. A flat bullet list under an `##` covers a single sub-concern. Roughly seven bullets is a signal to split, not a hard cap.
-- Order groups from the most-used rule down to the edge case.
+- Order groups from the most-used rule down to the edge case
 
 ## Rules
 
-- Write rules as imperative bullets: one rule per bullet, one concern per group.
-- State the forbidden shape rather than enumerating allowed options, so a rule survives new categories.
-- Cut any rule that resists a crisp one-line phrasing.
+- Write rules as imperative bullets: one rule per bullet, one concern per group
+- State the forbidden shape rather than enumerating allowed options, so a rule survives new categories
+- Cut any rule that resists a crisp one-line phrasing
 - Do not pad with filler prose. Every line earns its place as a usable reference entry.
 
 ## Success criterion
@@ -47,6 +66,6 @@ A standard is a target-facing authoring convention for one document type. It ins
 ## Examples
 
 - Include examples only where a rule is non-obvious. A self-evident rule needs none.
-- When shown, label them `### Correct` and `### Incorrect` with an inline `# reason` on each entry.
+- When shown, label them `### Correct` and `### Incorrect` with an inline `# reason` on each entry
 - Keep to two or three entries. Show the pattern, not a catalog.
 - Keep each entry a short one-liner or command. Do not write multi-line correct and incorrect function blocks.

package/standards/bundled/standard.md

@@ -1,52 +0,0 @@
----
-title: Standard reference
-description: Shape and content rules for authoring a standard
-consumers: create-standard
----
-
-# Standard reference
-
-## Overview
-
-A standard is a target-facing authoring convention for one document type. It installs into a project under `.claude/standards/` and is consumed by skills and developers alike. One standard governs one doc type. Split unrelated conventions into separate files.
-
-## Frontmatter
-
-- Start the file with a frontmatter block carrying `title` and `description`.
-- `title`: names the doc type in sentence case, suffixed `reference` (`Commit reference`, `Branch reference`).
-- `description`: one line naming what the standard covers. It becomes the index link label on install.
-
-## Structure
-
-- Use sentence case for every heading.
-- Flat `##` rule groups for a single-topic standard. Group `##` headers by concern for a multi-topic one.
-- When one `##` section covers more than one sub-concern, split its bullets into `###` subgroups, one subgroup per sub-concern. A flat bullet list under an `##` covers a single sub-concern. Roughly seven bullets is a signal to split, not a hard cap.
-- Order groups from the most-used rule down to the edge case.
-
-## Rules
-
-- Write rules as imperative bullets: one rule per bullet, one concern per group.
-- State the forbidden shape rather than enumerating allowed options, so a rule survives new categories.
-- Cut any rule that resists a crisp one-line phrasing.
-- Do not pad with filler prose. Every line earns its place as a usable reference entry.
-
-## Success criterion
-
-- State what a conforming artifact achieves, not only what shape it takes. A standard that specifies structure exhaustively and success nowhere cannot be argued against, only edited on taste.
-- Write the criterion as a small set of questions the artifact must answer, or a task a reader must be able to complete from it. Keep it checkable by a person in one sitting.
-- Place it near the top, above the shape rules it governs. The shape rules are the means and the criterion is the test.
-- Say that an artifact failing the criterion is non-conforming even when it satisfies every shape rule. Without that line the criterion reads as advice.
-- Add a criterion to an existing standard when that standard is next exercised, not in a sweep. A criterion written without a failure to point at is the taste-based edit this section exists to prevent, so a standard with no criterion yet is a known gap rather than a violation.
-
-## Changing a standard
-
-- Change a standard on a failure, not on a finding. A finding is that the docs say X or a paper suggests Y. A failure is a conforming artifact that satisfied every shape rule and still missed the success criterion.
-- Park findings wherever the project tracks pending work, or in the standard's own backlog section when it tracks none. They are hypotheses to test, not instructions to apply.
-- Cite the failing artifact in the change that fixes it, so the next reader can tell which rules were paid for by evidence.
-
-## Examples
-
-- Include examples only where a rule is non-obvious. A self-evident rule needs none.
-- When shown, label them `### Correct` and `### Incorrect` with an inline `# reason` on each entry.
-- Keep to two or three entries. Show the pattern, not a catalog.
-- Keep each entry a short one-liner or command. Do not write multi-line correct and incorrect function blocks.