@erclx/aitk 0.38.0 → 0.40.0

package/docs/agents.md

@@ -1,535 +0,0 @@
----
-title: Agents
-description: CLI catalog and invocation rules for agents
-category: Agent surface
----
-
-# Agents
-
-CLI catalog and invocation rules for agents working in this repository.
-
-This doc is an index of what an agent can run and how to run it cleanly from a script. It does not cover domain behavior. Read `CLAUDE.md` for project behaviors and load the matching `.claude/skills/aitk-*` skill when working inside a domain.
-
-## Invocation rules
-
-See `CLAUDE.md` design principles. They apply to every command below.
-
-## Output shape
-
-Every CLI command renders into one of two framed shapes. Data goes to stdout. UI and logs go to stderr. Help output is the exception. It prints to stdout so it can be piped and grepped.
-
-### Data shape (lists, runs, errors)
-
-```plaintext
-┌
-│ aitk <domain>
-│
-├ Section
-│ ✓ item
-│ ✓ item
-└
-```
-
-Rules:
-
-- `┌` opens the frame on stderr
-- `│ aitk <domain>` is the command banner, one per invocation
-- `├ Section` headers introduce groups of items. `log_step` produces the blank `│` spacer before each.
-- `└` closes the frame on stderr, wired via `trap close_timeline EXIT`
-- Errors render as `│ ✗ message` inside the same frame. Never emit a lone error line without a frame.
-
-### Help shape
-
-```plaintext
-┌
-├ Usage: aitk <domain> [command]
-│
-│  Commands:
-│    ...
-└
-```
-
-Help skips the banner. The `Usage:` line sits directly on `├`. Help writes to stdout because `--help` is documentation, not runtime UI.
-
-### JSON and `--names` modes
-
-`--json` and `--names` keep stdout clean and machine-readable. The frame still renders on stderr (open, banner, close) so the stream discipline is consistent across modes. Consumers that only read stdout see pure data.
-
-## Command catalog
-
-Full help: `aitk <command> --help`.
-
-### Project-level
-
-| Command                  | Purpose                                                                                        |
-| ------------------------ | ---------------------------------------------------------------------------------------------- |
-| `aitk init [path]`       | Bootstrap a project with selected toolkit domains                                              |
-| `aitk sync [path]`       | Sync all installed domains in a target project                                                 |
-| `aitk sync --check`      | Report toolkit drift without writing (`--json`, `--exit-code`)                                 |
-| `aitk sandbox [cat:cmd]` | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads             |
-| `aitk sandbox reset`     | Reset sandbox to baseline                                                                      |
-| `aitk sandbox clean`     | Wipe the sandbox                                                                               |
-| `aitk sandbox check`     | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)          |
-| `aitk sandbox coverage`  | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)                 |
-| `aitk indexes regen`     | Regenerate `index.md` files from sibling frontmatter                                           |
-| `aitk docs [topic]`      | Emit toolkit reference docs (`list`, or a topic by name)                                       |
-| `aitk design render`     | Render `.claude/DESIGN.md` tokens to HTML and CSS                                              |
-| `aitk slides render`     | Render a `.claude/SLIDES.md` source into a PowerPoint deck                                     |
-| `aitk slides list`       | List the available slide layouts (`--json` for the catalog)                                    |
-| `aitk feedback`          | Write toolkit feedback from stdin to `.claude/review/`, or open a GitHub issue with `--github` |
-| `aitk transcripts <url>` | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                          |
-| `aitk tasks archive`     | Move a shipped task off the board, clear its ordering row, and regenerate the index            |
-| `aitk comments scan`     | Measure comment density by language and comment kind, with a trend recomputed from git         |
-| `aitk context audit`     | Report required sections, length, depth, bullet weight, cited paths, provenance, and drift     |
-| `aitk capture [source]`  | Render HTML capture sources to PNG, toolkit-only and absent from an installed package          |
-
-### Domain commands
-
-Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`.
-
-| Domain      | Subcommands                                                            |
-| ----------- | ---------------------------------------------------------------------- |
-| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore` |
-| `snippets`  | `list`, `install`, `sync`, `create`                                    |
-| `standards` | `list`, `install`, `sync`                                              |
-| `gov`       | `list`, `install`, `sync`, `build`                                     |
-| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `setup [dest]`            |
-| `wiki`      | `init`                                                                 |
-| `design`    | `render`                                                               |
-| `slides`    | `render`, `list`                                                       |
-| `tasks`     | `archive`                                                              |
-| `comments`  | `scan`                                                                 |
-| `context`   | `audit`                                                                |
-
-Common patterns:
-
-- `list --json` → machine-readable catalog on stdout.
-- `install <name> <path>` → install a specific entry into a target project.
-- `sync <path>` → reapply all installed entries in a target project.
-- `create [name]` → scaffold a new authoring entry in this repo.
-
-`aitk gov sync` updates only rules already present under `.claude/rules/` and
-never adds new ones. A rule the toolkit does not ship is left alone, which is
-how project-authored rules survive. It also removes a stale `.claude/GOV.md`
-from the retired build. Use `aitk gov install` to add rules.
-
-`aitk standards sync` matches by filename against `.claude/standards/` and
-regenerates that folder's `index.md` on every completed run. It is the one sync
-that refuses under `AITK_NON_INTERACTIVE=1` when drift exists, logging a warning
-and exiting 0 without writing, because standards are seeds a project edits. Run
-it interactively, or use the `claude-seed-sync` skill for a per-section audit
-that preserves customizations.
-
-`aitk snippets sync` behaves the same way against `.claude/snippets/`. It
-matches by path relative to that directory, so a snippet the toolkit no longer
-ships, or one authored directly in the target, is reported and skipped rather
-than deleted. It is not preset-aware, so a project that installed `essentials`
-does not grow new snippets on a sync. Use `aitk snippets install` to add them.
-
-`aitk gov install` and `aitk snippets install` require their first argument
-under `AITK_NON_INTERACTIVE=1`. Both used to fall back to an interactive picker
-that resolved to its first option headlessly, so `aitk gov install` with no
-stack installed whichever stack sorted first and `aitk snippets install` with no
-category installed every category. Each now reports the valid names on stderr
-and exits 1. Every documented agent path already passes the argument, including
-`aitk init`. The confirm-then-apply prompt after it still resolves to `Yes`
-headlessly, so a call that names its stack or category is unchanged.
-
-`aitk gov install` also refuses the toolkit root as a target, matching
-`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
-would have created and exiting 0. Nothing is staged, committed, or pushed
-headlessly. Run it interactively to reach the commit and pull request options.
-It also refuses a target whose working tree is dirty, so commit or stash first.
-
-`aitk sync --check` reports drift and writes nothing, so it needs no clean tree
-and is safe to run at any time. Each file is classified as `stale` when it still
-matches what the toolkit installed, `customized` when the project edited it,
-`stranded` when it sits at a path the toolkit no longer installs to, `orphaned`
-when the project authored it, or `drifted` when no stamp covers it. Use `--json`
-for the machine-readable report and `--exit-code` to fail a CI job. Orphaned
-files are excluded from that exit code, since a project-authored rule never
-converges. Attribution reads `.claude/aitk.json`, which every install and sync
-writes.
-
-A target installed before stamping shipped has no such file, and the report
-falls back to the toolkit's own git history. Installed content matching any
-version that history ever published proves the file is untouched, so it reports
-`stale` naming the commit it came from, and content matching no published
-version stays `drifted`. A toolkit reached outside a git clone, which is what a
-registry install is, cannot run that fallback and reports
-`historyUnavailable` alongside the unattributed files.
-
-Each domain carries its own toolkit anchor in that file, so syncing one domain
-never advances the revision another measures from, and each reports the upstream
-commits touching its own source path. The `covers` field names the domains a
-target has actually stamped, so a domain that was never stamped is legible
-rather than reading as a clean one.
-
-`aitk init` installs up to six core domains and reports each one independently. A
-domain that fails does not abort the run, so the command finishes the rest and
-exits 1 naming the failures. Passing any flag skips the confirmation prompt,
-which is what makes it scriptable. `--stack` defaults to `base`, and the default
-does not read as a passed flag, so a bare `aitk init` installs governance and
-still prompts. `--skip` takes `wiki`, `standards`, and `governance`, and warns
-without aborting on any other value.
-
-`aitk tooling inject` and `aitk tooling prune-gitignore` are the unguarded
-primitives beneath `sync`. They apply one stack with no scan and no prompt, and
-they deliberately skip the check that rejects `claude`, which is how `aitk
-claude` drives its own stack through them. Use `sync` unless you are scripting
-provisioning. Both frame their own output, so pass `--nested` when calling from
-inside an already-open frame.
-
-### Sandbox scenarios
-
-Scenarios live under `scripts/sandbox/`, one folder per category. `scripts/sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so both pickers filter it out. `files` in `package.json` excludes that tree, so an installed `aitk` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
-
-```bash
-SANDBOX_SCENARIO=sync aitk sandbox infra:tooling
-```
-
-Scenario categories: `infra:*` (domain flows), `git:*`, `scaffold:*`. `create` scenarios require interactive input and loop on empty input, so skip them in automated runs.
-
-### Scenario expectations
-
-`aitk sandbox check <category>:<command> [arm]` scores a provisioned sandbox against the arm's `expect.toml`, printing a verdict on stderr and, with `--json`, the same verdict as a record on stdout.
-
-```bash
-aitk sandbox check claude:docs drift --json
-```
-
-| Flag                | Effect                                                     |
-| ------------------- | ---------------------------------------------------------- |
-| `--envelope <file>` | Read `is_error`, `num_turns`, denials, and the reply text  |
-| `--writes <file>`   | Newline-delimited paths the session wrote, for write scope |
-| `--json`            | Emit the verdict record on stdout                          |
-| `--strict`          | Exit 1 on `unchecked` instead of 0                         |
-
-The verdict `state` is `pass`, `fail`, or `unchecked`. An arm with no `expect.toml` is `unchecked` and exits 0, so the harness stays usable while expectations roll out. A declaration that exists but asserts nothing is a failure, since an expectation file that asserts nothing passes every run.
-
-Omitting `--writes` or `--envelope` does not silently drop the assertion kinds that need them. Write scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. A verdict never reports `pass` with zero assertions.
-
-An envelope that parses but carries no `result` field skips the reply assertion the same way an absent file does. An envelope carrying an empty `result` fails it, since a run that returned no text is a finding rather than a gap in the input.
-
-Exit 0 means `pass` or `unchecked`. Exit 1 means `fail`, or a caller error: a malformed target, or a sandbox that was never provisioned. A missing sandbox reports as an error rather than a failed verdict, because failing every path assertion would read as a skill that did nothing. `--strict` moves `unchecked` to exit 1 for a caller that has finished arming its scenarios.
-
-### Scenario coverage
-
-`aitk sandbox coverage` reports which scenarios declare expectations and which only provision a state. It reads the fixture tree, so it needs no provisioned sandbox and runs nothing. Where that tree does not ship it exits 1 and prints no percentage, since a denominator nobody looked at is not a coverage result. A tree that is present and holds no scenarios is a real zero and still reports one.
-
-```bash
-aitk sandbox coverage --json
-```
-
-| Flag       | Effect                                                      |
-| ---------- | ----------------------------------------------------------- |
-| `--json`   | Emit the coverage record on stdout                          |
-| `--strict` | Exit 1 while any scenario declares no expectation           |
-| `--skills` | Add a per-skill asserted, should-be-asserted, exempt census |
-
-The record carries every scenario with the arms that declare, plus `totalScenarios`, `armedScenarios`, and `armedArms`. Scenarios and arms count separately, since several arms can share one scenario and dividing one by the other overstates the rollout.
-
-`--skills` answers what the scenario count cannot, which is whether anything can fail a given skill. It adds `skills`, `totalSkills`, `asserted`, `shouldBeAsserted`, `exempt`, `staleExemptions`, and `supersededExemptions` to the record, and keeps the scenario view rather than replacing it. The two denominators disagree on purpose: an armed scenario under `infra/` or `tooling/` exercises a CLI domain and pairs with no skill at all.
-
-A skill pairs to a scenario by filename, `<category>-<command>` first and bare `<command>` second, so `claude/setup-init.sh` reaches the `setup-init` skill. `should-be-asserted` is the default rather than a queue to drain, and which of those skills earns an arm is a project decision the census does not make. `exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
-
-`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.claude/.tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit. Stdout carries the same bytes it did before the record existed.
-
-## Docs
-
-`aitk docs` emits the toolkit's own reference docs so an agent in a target project can orient without the toolkit source checked out. The CLI resolves `docs/` and `.claude/context/` from its install root, and which of the two it finds depends on how the CLI was installed. A registry install carries `docs/` alone, since `.claude/` is not published. A clone or a linked worktree carries both.
-
-- `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.
-
-## Indexes
-
-`aitk indexes regen` rewrites `index.md` files from sibling frontmatter. With no positional paths, it walks the current directory. With paths, each resolves by walking up to the nearest indexed ancestor, bounded by `--root`. Duplicates dedupe. The whole-repo walk prunes `.git`, `node_modules`, and anything `.gitignore` covers via `git check-ignore`.
-
-A positional path is not filtered that way, because the walk-up resolves on the filesystem and never consults git. That is the only way to regenerate an index inside a gitignored folder, and it is how `.claude/tasks/` stays current.
-
-| Option          | Behavior                                                         |
-| --------------- | ---------------------------------------------------------------- |
-| `--dry-run`     | Report which indexes would change without writing                |
-| `--json`        | Emit a machine-readable record per index on stdout               |
-| `--root <path>` | Walk-up boundary when positional paths are passed (default: CWD) |
-| `--no-stage`    | Skip the auto `git add` on modified indexes                      |
-
-Exit codes: `0` clean, `1` frontmatter error or missing index, `2` drift found in `--dry-run`.
-
-When positional paths are passed inside a git repo, modified `index.md` files are staged so lint-staged and Claude `PostToolUse` hooks commit the regenerated catalog. Whole-repo walks never auto-stage, and neither does a path git ignores, since staging one always fails and the warning would fire on every edit.
-
-Skills can parse drift without branching on exit code:
-
-```bash
-aitk indexes regen --dry-run --json | jq '.results[] | select(.action == "would-write")'
-```
-
-For the system rationale, frontmatter contract, when to adopt, and bootstrap path, see `.claude/context/indexes.md`.
-
-## Tasks
-
-`aitk tasks archive` moves a shipped task from `.claude/tasks/` into `.claude/.tmp/task-archive/`, drops its row from `priority.md`, and regenerates the board index. The three run as one unit, so the attended and unattended callers cannot archive differently.
-
-Name the task by its filename stem, or by the pull request it carries:
-
-```bash
-aitk tasks archive v28.1-trigger-escalation
-aitk tasks archive --pull-request 673 --json
-```
-
-| Option               | Behavior                                                     |
-| -------------------- | ------------------------------------------------------------ |
-| `--pull-request <n>` | Select the task whose `Pull request:` line names this number |
-| `--json`             | Emit a machine-readable record on stdout                     |
-| `--root <path>`      | Board root, defaulting to the main worktree                  |
-
-Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, or `plan-unswept`.
-
-The board is shared scratch at the main worktree root, so `--root` defaults to the first entry of `git worktree list` rather than the working directory. A linked worktree archives against the same board every other session reads.
-
-Skills branch on the reason rather than on the exit code:
-
-```bash
-aitk tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .reason end'
-```
-
-For the board format, the `Pull request:` line, and the archive rules, see `.claude/standards/tasks.md`.
-
-## Capture
-
-`aitk capture [source]` renders HTML capture sources to PNG, which is how a committed documentation image regenerates from its committed source. The source defaults to `assets/`, where a directory expands to every `.html` directly inside it, so adding a capture means dropping a file beside the first one and running the same bare command.
-
-```bash
-aitk capture
-aitk capture assets/install.html
-aitk capture assets --out .claude/review/captures
-```
-
-`assets/` now holds two sources, so a bare `aitk capture` rebuilds both. `install.html` is hand-authored and its text came from a real run. `hero.html` is generated by `scripts/core/regen-hero.sh` from the CLI catalogs and must not be edited by hand, since `bun run check` regenerates it and fails on the difference. Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `aitk capture assets/hero.html` when the check reports the HTML changed.
-
-| Option             | Behavior                                          |
-| ------------------ | ------------------------------------------------- |
-| `--out <dir>`      | Write every PNG here instead of beside its source |
-| `--selector <sel>` | Element to capture (default: `.window`)           |
-
-Each source renders at `deviceScaleFactor` 2 with a transparent background, and the success line reports the pixel dimensions the element wrapped to. Size is reported and never asserted. The height of a terminal frame is whatever its text wrapped to at a fixed width, so pinning that number would harden an accident.
-
-What is asserted is the font. The command reads the first family the captured element declares and fails when the browser did not resolve it, because a fallback face rewraps the block and silently changes the output. Sources therefore name a real font rather than relying on `monospace`. A source that cannot render reports its own line and exits 1 without dropping the rest of the batch.
-
-The browser binary installs separately from the package. A fresh clone runs `bunx playwright install chromium` once, and a run that cannot launch one reports the engine's own remediation inside the frame and exits 1 rather than escaping as a stack trace.
-
-The command is toolkit-only. Its render module holds every browser reference in the toolkit and `files` in `package.json` excludes it, so an installed `aitk` carries the command, reports it as absent on one line, and exits 1. Every other command is unaffected, which is the reason the browser import sits behind a dynamic import rather than at a command's top level.
-
-## Comments
-
-`aitk comments scan [path]` reports comment density for a tree, split by language and by comment kind. It is the only command that parses the target's own source, so its scope stays deliberately narrow: TypeScript and bash, line-oriented, no AST.
-
-```bash
-aitk comments scan
-aitk comments scan src --json
-aitk comments scan --since v0.5.0
-```
-
-| Option               | Behavior                                                        |
-| -------------------- | --------------------------------------------------------------- |
-| `--json`             | Add a machine-readable record on stdout, keeping the frame      |
-| `--since <rev>`      | Report the trend from this revision instead of a snapshot alone |
-| `--languages <list>` | Comma-separated subset of `ts,sh` (default: both)               |
-
-A line counts as a comment when its first non-whitespace token opens one, which is what keeps a URL in a string literal from reading as a `//` comment without a parser. Density is `commentLines / lines`, reported and never graded. The command produces the number and a rule produces the judgment.
-
-Two exclusions are structural rather than tuning. Heredoc bodies are dropped from both the numerator and the denominator, because a scenario script carrying markdown inside one has `#` opening a heading rather than a comment, which inflated a measured 112 comment lines to 427. Fixture trees are pruned by path segment for the same reason. The line-1 shebang is not a comment, since every script has one and counting it puts a floor under density that reports the file count.
-
-`--since` recomputes each point from git via `ls-tree` and `cat-file --batch`, checking nothing out. No ledger is written or read. Six points spread evenly across the window by default, and the boundary revision is always included so the series keeps the reading it is measured against. This works only because density is a pure function of a tree. Which author or session wrote a comment is not recoverable from git and does not belong here.
-
-The degradation sweep reads its vocabulary from whichever rule publishes a `## Degradation vocabulary` heading, preferring `.claude/rules/` over `governance/rules/`, so one definition serves the toolkit and every target. Discovery anchors on the heading rather than a filename, because a renumbered rule would otherwise empty the vocabulary while the sweep still reported clean. With no such rule the sweep reports **skipped** rather than zero hits, since finding nothing and looking for nothing mean opposite things.
-
-`090-code-comments` is the rule that publishes the list, and it ships on the `base` stack. A project that installs or syncs governance for the first time after that rule landed gets a sweep that previously reported skipped, so hits appear where the command used to stay quiet. Edit the backticked terms in the installed copy to change what that project sweeps for. The sweep matches comment text, so a comment naming a term as an example is a hit, and a hit is a prompt to read the line rather than a verdict on it.
-
-## Context audit
-
-`aitk context audit [path]` reports the structural state of the folders following the index-plus-entry contract, meaning a generated `index.md` beside entries carrying frontmatter. It reads and reports. Fixing what it finds is separate work.
-
-```bash
-aitk context audit
-aitk context audit --json
-aitk context audit --citations-only
-aitk context audit --folder context,diagrams
-aitk context audit --folder docs
-```
-
-| Option             | Behavior                                                             |
-| ------------------ | -------------------------------------------------------------------- |
-| `--json`           | Add a machine-readable record on stdout, keeping the frame           |
-| `--folder <list>`  | Comma-separated folder names (default: the three below)              |
-| `--citations-only` | Run the gating citation check alone, printing nothing when it passes |
-
-Scope defaults to `context`, `diagrams`, and `wireframes`, and a folder the project does not carry is skipped rather than reported. A domain that outgrew one file and split into `<domain>/` is audited as its own folder, so a split entry measures at the same grain as a flat one.
-
-A name passed to `--folder` resolves under `.claude/` first and at the project root second, which is what puts `docs/` and any later corpus in reach of the same engine. The root base is reached only by a name the caller passes, so the default list still resolves under `.claude/` alone and a project holding a root `wireframes/` is not audited against a standard it never adopted. The scope line prints the resolved path, so a project carrying both spellings reads which one was taken. The JSON record carries the base per folder as `folders[].base`.
-
-A run where no requested name resolves refuses, whichever list it read. Naming the absent ones narrows to `--folder`, since a project carrying one of the three default folders is the ordinary case and a name it never asked for is not a typo. The JSON record carries those names as `unresolvedFolders`.
-
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved citation. Only the citation check sets a failing code. Required-section, length, depth, bullet weight, table, provenance, and index findings print and return `0`, because each is a judgment and failing a push on one would make the check something to route around.
-
-### What each check reports
-
-The required-section check reports what does not declare `## Overview` and `## Layout`, the two sections `.claude/standards/context.md` marks required. The list is held in code beside the numeric checkpoints rather than parsed out of the standard, so it fails on a defect rather than on a rewrite of the wording around it. A heading at any level counts, because a domain that split into a folder carries its overview in a sibling named `overview.md` where the section is the `#` title and an `##` beneath it would repeat the filename. Matching exactly is what keeps `## Layout catalog` from satisfying `Layout`.
-
-Which unit answers depends on the folder. Entries of the folder named under `.claude/` are one domain each, so each answers for itself and a finding names the entry. Entries of a folder a domain split into describe that one domain between them, so any sibling answers and a finding names the folder. Holding a split folder to the rule per file would report every child beside its `overview.md`, and rolling the named folder up would let one conforming entry stand in for every other domain sitting next to it.
-
-It reports rather than gates, the closer call because a missing section reads more like a fact than the other judgments. What settles it is that the standard sanctions omitting `## Layout` from a domain owning no paths in the repo, and no measure separates that from an entry that forgot it. A domain covering only external tools is that case, and it reports on every run. The JSON record carries the findings as `missingSections` and the list as `checkpoints.requiredSections`.
-
-Length and depth quote their checkpoints from `.claude/standards/context.md`: roughly 150 rendered lines for an entry, roughly 40 for a run no heading breaks. Depth measures the longest such run rather than everything under one `##`, skips fenced blocks so a markdown example does not read as three headings, and exempts a run whose lines are all list items at one indent averaging under 130 characters. The weight condition is what separates a scannable catalog of one-liners from a stack of paragraph-bullets, which reach the same count and read nothing alike.
-
-Both checks count rendered lines rather than source lines, wrapping each line at 80 columns and summing the heights. Entries here are authored one line per bullet, so a block of fifteen paragraph-bullets occupies fifteen source lines and renders past sixty, which source counting cannot see. Measuring one checkpoint in each unit would put an entry length beside a run length that mean different things. Their exclusions still differ: the file measure counts fenced blocks and frontmatter, while the run measure skips a fence so an example cannot break the run around it. A reference-heavy entry therefore ranks by its examples, which the length legend states on every run. Runs count blank lines, which the standard leaves open, so a hand reader who drops them lands a line or two lower. Both sections state the width on every run, since a number in rendered lines cannot be reproduced without it.
-
-The bullet check reports a top-level bullet past roughly 400 characters, which is where a bullet stops carrying a decision alone and starts carrying the incident that motivated it beside the decision. Continuation lines fold into the bullet they belong to, so a heavy bullet cannot fall under the checkpoint by wrapping across two source lines, while a nested item is left out because the parent's own text is what the checkpoint asks about. Findings group by entry and narrow to `.claude/context/` for the reasons the provenance ones do both. Unlike the peer-list threshold above it, this corpus has no gap behind the number: bullet weight decays smoothly from a median near 170, so the number is a judgment where that one was a measurement, and a bullet reading well past it means the number is wrong rather than the rule.
-
-The table check reports a catalog that grows a row per shipped thing, not a table count. A fixed comparison table never reflows, so its size costs nothing. A table qualifies at six or more body rows whose first column mostly carries a path, command, or link, which is what separates a catalog from a comparison without reading the prose.
-
-The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open. Fenced blocks are excluded, which keeps a pinned version in an install command from reading as a claim the entry makes. Frontmatter is excluded with them, since the content checks read the body alone, and that is what keeps a diagram entry's dated `verified` stamp a record of its last check rather than a marker to settle. Length is the exception, counting the whole file, so a reader applying the 150-rendered-line checkpoint against the body alone lands a few lines under what the tool reports.
-
-The provenance, bullet-weight, and required-section checks cover `.claude/context/` alone, while length, depth, and the table finding reach every audited folder. The rule is stated in `.claude/standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder, and what decides it is whether the remedy is actionable rather than what the check measures. Subdividing a run and splitting a file mean something in any entry, so length and depth generalize. Moving an incident out of a bullet and keeping the decision means nothing in a folder whose entries declare no decisions, which is why bullet weight narrows despite measuring a distance like the two that do not. Required sections narrow for a plainer reason: the names are the context standard's own, and neither sibling standard states a required section at all. The scoping key is the folder an entry was audited under, so `--folder` still reaches a folder the default list does not carry, and a domain split into `context/<sub-area>/` is governed as `context`. Every run states the reach, including a run where no audited folder is the governed one. The JSON record carries it as `checkpoints.provenanceFolder` and a per-folder `governsContent`.
-
-Index drift compares an index against its siblings in both directions. An entry the index does not link is invisible to a session choosing what to open, and a linked name resolving to nothing sends one to a path that opens nothing.
-
-### The citation gate
-
-The citation check resolves every path into an audited folder that appears anywhere in the repository, and it is the half wired into `bun run check`. A stale reference has a silent failure mode: the session opens nothing and carries on.
-
-Three exclusions keep it from firing on prose about paths. Fenced blocks are skipped in markdown, which covers a standard displaying a path as an example. Fixture and harness trees are skipped by location, covering sandbox scenarios that describe their own scratch tree, the eval harness naming its target project, and `*.test.ts`. A path into a folder the project does not carry is skipped, so a skill directing a reader to `.claude/wireframes/index.md` stays valid in a project that has wireframes and silent in one that does not.
-
-What remains is a sentence naming a hypothetical entry to show the shape of a name, which no syntax separates from a real reference. Append `<!-- audit-ignore-citations -->` to that source line. The marker suppresses citation checking for its own line only.
-
-The pattern spells the `.claude/` prefix, so a folder resolved at the project root is measured by every other check and contributes nothing here. Widening it to a bare `docs/x.md` would match prose that references nothing, which is a separate decision from where entries come from. A run whose folders all resolved at the root says the check is out of scope rather than reporting that zero paths resolved, and the same run under `--citations-only` refuses, because a gate exiting clean on a scope it could not build is the failure the gate exists to catch.
-
-## Runtime catalogs
-
-Use these to discover what's available instead of hardcoding names.
-
-| Command                          | Returns                                       |
-| -------------------------------- | --------------------------------------------- |
-| `aitk tooling list --json`       | Stacks, extends chain, dep and script counts  |
-| `aitk snippets list --json`      | Presets and categories with their slugs       |
-| `aitk standards list --json`     | Standards docs and the paths each governs     |
-| `aitk gov list --json`           | Governance stacks and rule sets               |
-| `aitk claude seeds list --json`  | Seed doc sources with content                 |
-| `aitk claude skills list --json` | Plugin skills, descriptions, requirement flag |
-| `aitk docs list --json`          | Consumer docs plus per-domain context         |
-
-Every catalog serializes through `JSON.stringify`, so a name carrying a quote
-emits valid JSON. `aitk tooling list` and `aitk snippets list` previously built
-their output with `printf` and no escaping.
-
-`aitk standards list` carries `appliesTo` per standard, the paths that standard's
-`## Scope` statement declares. It holds the backticked paths from the first
-sentence of the statement, the single entry `*` for a standard governing an
-attribute rather than a document type, and an empty array when the statement
-declares nothing a parser can read. A consumer mapping a file to its governing
-standards reads this rather than holding a table of its own, and reports an empty
-array rather than skipping the standard behind it.
-
-`aitk claude seeds list` reads the same plan `aitk claude init` applies, so the
-listing and the install cannot disagree. It now reports
-`.claude/context/index.md`, which `init` has always installed and the listing
-never named, and it emits the project-level `CLAUDE.md` last rather than first.
-
-`aitk claude skills list` reads `claude/skills/*/SKILL.md` and reports the folder
-name with the frontmatter description, sorted by name. Internal skills under
-`.claude/skills/` are excluded, since they never install into a target and a
-count spanning both overstates what ships. A skill whose frontmatter is missing
-or unparseable returns an empty description rather than failing the listing, so
-one malformed file cannot hide the rest of the catalog. `--names` emits skill
-names one per line.
-
-Each entry also carries `requirement`, whether the folder holds a sibling
-`REQUIREMENT.md`. Coverage of that file is selective by design, so a `false` is
-not a gap to close and the flag answers which skills carry one without a caller
-listing the directory itself. It says nothing about why, which is a judgment the
-toolkit records against its own corpus rather than in the catalog.
-
-## Non-interactive examples
-
-```bash
-# Create a new tooling stack
-AITK_NON_INTERACTIVE=1 aitk tooling create astro
-
-# Sync a stack into a target project
-AITK_NON_INTERACTIVE=1 aitk tooling sync astro /path/to/project
-
-# Install a governance stack (the stack argument is required headlessly)
-AITK_NON_INTERACTIVE=1 aitk gov install astro --add 260-shadcn /path/to/project
-
-# Update installed governance rules, dropping a retired .claude/GOV.md
-AITK_NON_INTERACTIVE=1 aitk gov sync /path/to/project
-
-# Concatenate installed rules into a paste payload
-AITK_NON_INTERACTIVE=1 aitk gov build /path/to/project
-
-# Sync a monorepo subtree, skipping the base layer the repo root already owns
-AITK_NON_INTERACTIVE=1 aitk tooling sync vite-react /path/to/repo/frontend --skip base
-
-# Verify a stack end-to-end in a throwaway scaffold
-aitk tooling verify vite-react
-
-# Apply one stack without scanning or prompting, for scripted provisioning
-aitk tooling inject base /path/to/project
-aitk tooling inject base /path/to/project --configs --seeds
-
-# Drop managed gitignore entries a manifest no longer declares
-# Prints the number removed on stdout, diagnostics on stderr
-aitk tooling prune-gitignore base /path/to/project
-
-# Install a snippet preset
-AITK_NON_INTERACTIVE=1 aitk snippets install essentials /path/to/project
-
-# Update snippets already installed, leaving project-authored ones alone
-AITK_NON_INTERACTIVE=1 aitk snippets sync /path/to/project
-
-# Report standards drift without applying it, which is what headless does here
-AITK_NON_INTERACTIVE=1 aitk standards sync /path/to/project
-
-# Copy every standard into a target, overwriting what is there
-AITK_NON_INTERACTIVE=1 aitk standards install /path/to/project
-
-# Bootstrap a project. Any flag suppresses the confirmation prompt
-AITK_NON_INTERACTIVE=1 aitk init --stack astro --skip wiki /path/to/project
-
-# Run every domain sync. The git workflow is refused headlessly, so nothing is pushed
-AITK_NON_INTERACTIVE=1 aitk sync /path/to/project
-
-# Scaffold .claude/wiki/ with a stub index. The target must already exist
-AITK_NON_INTERACTIVE=1 aitk wiki init /path/to/project
-
-# Run a sandbox scenario non-interactively
-SANDBOX_SCENARIO=sync aitk sandbox infra:tooling
-```
-
-## Related
-
-- `CLAUDE.md`: project behaviors and design principles
-- `.claude/skills/aitk-*`: domain-scoped guidance for editing work
-- `docs/index.md`: full docs directory