@erclx/aitk 0.38.0 → 0.40.0

package/claude/skills/systematic-debugging/REQUIREMENT.md

@@ -0,0 +1,41 @@
+---
+name: systematic-debugging
+description: Why a fix is blocked until investigation completes, and what the three-attempt stop is measuring
+---
+
+# Systematic debugging requirement
+
+## Gap
+
+Without this skill, a session handed a failure proposes a fix from the first plausible reading of the error, and the fix is judged by whether the symptom moved. A symptom that moves is the normal result of changing something near it, so the session reports success and the cause is still there.
+
+The compounding failures come next. Several changes go in at once, so a pass says nothing about which one mattered. A fix that fails gets another fix stacked on top of it rather than a new hypothesis, and the code accumulates changes nobody can trace to a reason. A bad value gets corrected where it was observed rather than where it was produced, which moves the failure downstream instead of removing it.
+
+Two failures are about stopping rather than about fixing. A session that never counts its attempts keeps fixing through the pattern where each fix reveals a problem elsewhere, which is architectural and cannot be reached from inside the loop. And a session that concludes an issue is environmental usually has an incomplete investigation rather than an environmental issue, because that conclusion is available at any point and is never contradicted by evidence.
+
+## Must
+
+- Complete the investigation before any fix is proposed, reading the failure in full and reproducing it
+- Trace a bad value back to where it was produced and fix there
+- Compare the broken code against working code in the same codebase before hypothesizing
+- State one hypothesis and change one variable to test it
+- Write the failing test before the fix, so the fix is judged against a reproduction rather than against the symptom
+- Stop after three failed attempts and hand the architectural question to the user
+
+## Must not
+
+- Stack a second fix on a failed one rather than forming a new hypothesis
+- Bundle a refactor or an unrelated improvement into the fix
+- Accept an environmental or timing conclusion before the investigation is exhausted
+- Claim an understanding it does not have
+
+## Guards
+
+- An incomplete investigation blocks the fix proposal, which is the skill's one refusal and the reason it exists
+- Three failed attempts stop the loop, since the pattern is evidence about the design rather than about the bug
+
+## Out of scope
+
+- A typo fix and a cause already agreed on, where the phases cost more than they return
+- Reviewing a change for defects it has not yet exhibited: `claude-review`
+- Deciding whether the architecture should change, which the three-attempt stop hands to the user rather than answering

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

@@ -0,0 +1,37 @@
+---
+name: toolkit-cli
+description: Why the overwrite contract is stated before a sync runs, and why the skill reads rather than executes
+---
+
+# Toolkit cli requirement
+
+## Gap
+
+Without this skill, a session runs an `aitk` sync and finds out afterward what it did. The command names give nothing away. `install` and `sync` differ per domain, some surfaces overwrite unconditionally, some merge, some are written once and never touched again, and none of that is visible from the command line the user typed.
+
+The damage lands on the files a project owns. A golden config carrying local edits is replaced without a warning anyone saw, and a standards install overwrites every standard in a project that only needed the two it had drifted on. The user learns which category a file was in by losing the edit.
+
+The inverse failure is quieter. A session that assumes a sync will pick up a change edits a seed and waits for an update that never comes, because the seed is copy-once and no sync command writes it again. Both failures are one missing fact available before the command runs.
+
+## Must
+
+- State per surface and per command whether an existing file is overwritten, merged, written once, or left alone
+- Warn about a destructive run before it happens, naming the surface that will be lost
+- Name the section-preserving path for a standard or seed the project has customized
+- Defer to the toolkit's own context docs when they and this summary disagree, since the summary is a copy and they are the source
+
+## Must not
+
+- Run any `aitk` command. The skill is read before acting.
+- Restate the full semantics. It is a target-session summary and the detail lives with its owner.
+
+## Guards
+
+- A surface or command the contract does not cover routes to the context docs rather than to an inference from a similar row
+
+## Out of scope
+
+- Executing the sync, which the user runs or `toolkit-operator` routes
+- Reconciling a customized seed section by section: `claude-seed-sync`
+- Relocating a project's folders into the layout a newer version expects: `migration-standards`
+- Deciding which stack, rule, or standard a project should install, which the setup skills resolve from live catalogs

package/claude/skills/toolkit-feedback/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: toolkit-feedback
+description: Why a toolkit defect is reported from session context alone, and what shipping through the CLI replaces
+---
+
+# Toolkit feedback requirement
+
+## Gap
+
+Without this skill, a toolkit defect noticed inside a target project dies with the session. The user is told to mention it in the toolkit repository later, which means retyping a report they no longer have the context to write, so the defect is either reported badly or not at all.
+
+The report itself fails two ways. A block printed in chat needs a copy-paste into another repository, and a step that manual is skipped under any time pressure. A report that names no surface cannot be routed, because the toolkit acts on a plugin skill, a snippet, a CLI command, and a seed through different paths, and the difference is not recoverable from the symptom.
+
+The last failure is the session's own effort. Asked to report, a session starts diagnosing instead, searching the toolkit and reading its surfaces to find the cause. That spends the context the report was meant to capture cheaply, and it produces a diagnosis from a project that cannot see the toolkit's current source.
+
+## Must
+
+- Build the report from what the session already holds
+- Name the surface and its type, since the toolkit routes on that rather than on the symptom
+- Write the stated fallback for a field the session cannot fill, so an empty field reads as absent rather than as unreported
+- Ship through the CLI so the report lands without a copy-paste, and print the returned path on its own line
+- Offer the durable route for a report worth keeping across sessions and machines
+- Fall back to printing the block when the CLI is absent, so the report still exists
+
+## Must not
+
+- Probe the project, list files, grep, or read toolkit surfaces to enrich the report
+- Guess the surface type when the session is ambiguous. Ask one line.
+- Diagnose or fix, which needs the toolkit's source rather than the target's
+
+## Guards
+
+- Nothing in session context pointing at a toolkit issue stops, since a report assembled from nothing wastes the triage it reaches
+
+## Out of scope
+
+- Fixing the defect, which happens in the toolkit repository against its own source
+- Draining the queue this fills: `toolkit-triage`
+- Filing an issue against the current project: `git-issue`
+- Complaints about tooling the toolkit does not own

package/claude/skills/toolkit-operator/REQUIREMENT.md

@@ -0,0 +1,39 @@
+---
+name: toolkit-operator
+description: Why the toolkit has one front door, what orienting on live catalogs prevents, and where it hands off
+---
+
+# Toolkit operator requirement
+
+## Gap
+
+Without this skill, using the toolkit means knowing which skill to pick, and the user who most needs it is the one who cannot. A plain-language intent has no obvious owner among a dozen setup and sync skills, so the session guesses a command instead of resolving one, and a wrong guess installs into a project rather than reporting a mismatch.
+
+Two failures come from acting on memory. A session that names a stack, rule, or snippet from what it remembers rather than from the live catalog runs against an entry that has been renamed or removed. And a session that edits a managed file by hand produces a change the next sync overwrites, which reads as the toolkit undoing work rather than as the edit having been made in the wrong place.
+
+The last failure is duplication. A front door that answers everything itself reimplements first-time detection and seed diffing inline, badly, beside the skills that already do both. The value of a router is that it stops at the handoff.
+
+## Must
+
+- Orient on the toolkit's own docs and the live catalogs before acting
+- Map the stated intent to one lifecycle phase, then either run the simplest command that satisfies it or hand off
+- Resolve every stack, rule, snippet, and standard name from a catalog at runtime
+- Run the CLI non-interactively and report the command run, what changed, and the full path of anything written
+
+## Must not
+
+- Edit a managed file by hand instead of running the CLI that owns it
+- Reimplement a flow another skill owns
+- Hardcode a catalog name
+- Auto-trigger. It is a door the user opens, and a router that fires on its own routes requests nobody made.
+
+## Guards
+
+- An intent matching a deep flow hands off rather than running a shallow version of it, since a partial scaffold is harder to recover from than none
+
+## Out of scope
+
+- First-time scaffold of a fresh project: `setup-init`
+- Seed and preamble drift in installed files: `claude-seed-sync`
+- Governance rule install and index bootstrap: `setup-gov` and `setup-indexes`
+- What a given sync overwrites once it runs: `toolkit-cli`

package/claude/skills/toolkit-triage/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: toolkit-triage
+description: Why the feedback queue is read from GitHub rather than local scratch, and why triage routes instead of implementing
+---
+
+# Toolkit triage requirement
+
+## Gap
+
+Without this skill, the feedback queue fills and nothing drains it. Reports arrive from projects the toolkit never sees, and a queue nobody reads on a schedule is the same as no queue. The local review folder looks like the right place to read, and it is the wrong one, because that content is per-machine session scratch that any cleanup removes.
+
+Triage fails three ways once it starts. Unrelated issues get batched into one branch, so review has to judge several unconnected changes at once and can approve none of them cleanly. An issue needing a plan gets implemented inline from a paragraph of description, which skips the step where scope is argued. And an issue whose report contradicts itself gets a guess rather than a question, so the fix addresses a defect nobody confirmed.
+
+The queue also fails to drain even when the work ships. A fix merged with no link back leaves its issue open, and the next triage re-reads work already done.
+
+## Must
+
+- Read the durable queue rather than local session scratch
+- Classify each issue in a fixed order and stop at the first match, stating the class and its one-line reason before routing
+- Route to the skills that own planning, branch naming, and the pull request body rather than restating them
+- Keep one issue to one branch and one pull request
+- Link a fix to its issue so merge closes it, and preserve that link when the body is regenerated
+- Ask on the issue when the report is unreadable, then move on rather than blocking the batch
+
+## Must not
+
+- Batch unrelated fixes into one branch
+- Implement a plan-worthy issue, which stops at the plan handed back to the user
+- Close an issue whose pull request has yet to merge
+
+## Guards
+
+- The `gh` CLI absent or unauthenticated stops, since the queue is unreachable
+- An empty queue reports nothing open rather than widening the label to find work
+
+## Out of scope
+
+- Filing new feedback: `toolkit-feedback`
+- Writing the plan a plan-worthy issue needs: `claude-feature`
+- Triage of issues carrying any other label, which surface here by design only under the feedback label

package/claude/skills/youtube-transcripts/REQUIREMENT.md

@@ -0,0 +1,38 @@
+---
+name: youtube-transcripts
+description: Why the transcript fetch stays in the CLI, and why fetching stops short of reading
+---
+
+# Youtube transcripts requirement
+
+## Gap
+
+Without this skill, a pasted video link turns into captions printed in chat, which persist nowhere and cannot be cited by a later session. The file is the point. A transcript saved with its metadata is context the repository holds, and a transcript in a message is context that ends with the turn.
+
+A session that fetches on its own gets the shape wrong. Raw captions carry timing cues and duplicated lines, and a file written without frontmatter has no title, no source URL, and no way to tell which video it came from. Reimplementing the cleanup also duplicates logic the CLI already owns, so the two drift and the drift shows up as inconsistent files rather than as an error.
+
+Two smaller failures follow the fetch. A video with no captions produces a file that looks empty rather than one reported as having none, so the user reads it as a failed fetch. And a session that summarizes what it fetched answers a question nobody asked, spending context on a reading the user may not want yet.
+
+## Must
+
+- Run the CLI, which owns the fetch, the caption cleanup, and the frontmatter
+- Surface the written path as a full relative path so the terminal makes it clickable
+- Report a video with no captions as a fact about the video, since the file still exists and carries its metadata
+- Name the missing external binary and stop, leaving the install to the user
+
+## Must not
+
+- Reimplement the fetch or the cleanup
+- Summarize or annotate the transcript unasked, which is a separate request against the file
+- Install the external binary the command shells out to
+
+## Guards
+
+- No URL stops, since there is nothing to fetch
+- A link that is not a YouTube URL stops rather than attempting a generic fetch the command cannot do
+
+## Out of scope
+
+- Downloading the video or its audio
+- Summarizing a transcript already on disk, which is a read of that file
+- Choosing where transcripts live, which the command defaults and a flag overrides

package/docs/agents/capture.md

@@ -0,0 +1,31 @@
+---
+title: Capture
+description: Rendering committed HTML sources to PNG, what the command asserts about fonts, and why it is toolkit-only
+---
+
+# 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`)           |
+
+## What the command asserts
+
+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.

package/docs/agents/commands.md

@@ -0,0 +1,57 @@
+---
+title: Command catalog
+description: Every project-level command and every domain subcommand, plus the shape each domain exposes
+---
+
+# Command catalog
+
+Full help: `aitk <command> --help`. Behavior notes for the install and sync verbs live in `install-and-sync.md`.
+
+## 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.

package/docs/agents/comments.md

@@ -0,0 +1,32 @@
+---
+title: Comments
+description: Comment density by language and kind, the two structural exclusions, and how the degradation sweep finds its vocabulary
+---
+
+# 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.
+
+## Degradation sweep
+
+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.

package/docs/agents/context-audit-checks.md

@@ -0,0 +1,40 @@
+---
+title: Context audit checks
+description: What each non-gating check reports, the unit each checkpoint is measured in, and which folders each check reaches
+---
+
+# Context audit checks
+
+What each finding from `aitk context audit` means. The command surface, its flags, and the one gating check are in `context-audit.md`.
+
+## Required sections
+
+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
+
+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.
+
+## Bullet weight and tables
+
+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.
+
+## Provenance
+
+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.
+
+## Which folders each check reaches
+
+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
+
+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.

package/docs/agents/context-audit.md

@@ -0,0 +1,44 @@
+---
+title: Context audit
+description: Running the audit, its flags and folder scope, the exit codes, and the citation gate that is the only failing one
+---
+
+# 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. What each finding means is in `context-audit-checks.md`.
+
+```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 |
+
+## Folder scope
+
+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
+
+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.
+
+## 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.

package/docs/agents/docs.md

@@ -0,0 +1,17 @@
+---
+title: Docs
+description: How aitk docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
+---
+
+# 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.

package/docs/agents/index.md

@@ -0,0 +1,23 @@
+---
+title: Agents
+subtitle: CLI catalog and invocation rules for agents, split by command domain. Start with overview.
+category: Agent surface
+---
+
+# Agents
+
+CLI catalog and invocation rules for agents, split by command domain. Start with overview.
+
+- [Capture](capture.md): Rendering committed HTML sources to PNG, what the command asserts about fonts, and why it is toolkit-only
+- [Command catalog](commands.md): Every project-level command and every domain subcommand, plus the shape each domain exposes
+- [Comments](comments.md): Comment density by language and kind, the two structural exclusions, and how the degradation sweep finds its vocabulary
+- [Context audit checks](context-audit-checks.md): What each non-gating check reports, the unit each checkpoint is measured in, and which folders each check reaches
+- [Context audit](context-audit.md): Running the audit, its flags and folder scope, the exit codes, and the citation gate that is the only failing one
+- [Docs](docs.md): How aitk docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
+- [Indexes](indexes.md): Flags, exit codes, and JSON shape for aitk indexes regen, plus when it auto-stages what it rewrote
+- [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
+- [Output shape](output-shape.md): The two framed shapes every command renders into, and how JSON and --names modes keep stdout clean
+- [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
+- [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
+- [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
+- [Tasks](tasks.md): Selecting a shipped task by stem or pull request, the refusal reasons, and why the board root defaults to the main worktree

package/docs/agents/indexes.md

@@ -0,0 +1,29 @@
+---
+title: Indexes
+description: Flags, exit codes, and JSON shape for aitk indexes regen, plus when it auto-stages what it rewrote
+---
+
+# 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`.