@erclx/aitk 0.38.0 → 0.40.0

package/docs/agents/install-and-sync.md

@@ -0,0 +1,109 @@
+---
+title: Install and sync
+description: What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
+---
+
+# Install and sync
+
+The behavior notes behind the verbs listed in `commands.md`. Each one records what the verb writes, what it refuses, and what it deliberately leaves alone.
+
+## Domain sync
+
+`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.
+
+## Install guards
+
+`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.
+
+## Governance regen
+
+`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.
+
+## Whole-project sync
+
+`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.
+
+## Drift reporting
+
+`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.
+
+## Bootstrap
+
+`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.
+
+## Unguarded tooling primitives
+
+`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.

package/docs/agents/output-shape.md

@@ -0,0 +1,45 @@
+---
+title: Output shape
+description: The two framed shapes every command renders into, and how JSON and --names modes keep stdout clean
+---
+
+# 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.

package/docs/agents/overview.md

@@ -0,0 +1,26 @@
+---
+title: Overview
+description: What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
+---
+
+# Overview
+
+CLI catalog and invocation rules for agents working in this repository.
+
+This folder 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 in this folder.
+
+## Where to start
+
+- `output-shape.md`: the stream contract every command renders into, which is what a caller parsing stdout depends on
+- `commands.md`: the full command catalog, project-level and per-domain
+- `scripting.md`: the runtime catalogs that replace hardcoded names, plus headless invocation examples
+
+## Related
+
+- `CLAUDE.md`: project behaviors and design principles
+- `.claude/skills/aitk-*`: domain-scoped guidance for editing work
+- `docs/index.md`: full docs directory

package/docs/agents/sandbox.md

@@ -0,0 +1,65 @@
+---
+title: Sandbox
+description: Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
+---
+
+# Sandbox
+
+`aitk sandbox` provisions isolated project states, scores a provisioned one against a declared expectation, and reports which scenarios declare an expectation at all.
+
+## 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.
+
+### The skills census
+
+`--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.

package/docs/agents/scripting.md

@@ -0,0 +1,115 @@
+---
+title: Scripting
+description: The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
+---
+
+# Scripting
+
+What a skill or script reads to discover names at runtime, and how each domain is invoked with no TTY.
+
+## 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         |
+
+### Catalog fields
+
+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.
+
+### The skills catalog
+
+`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`. Every skill is meant to carry one, so a `false` is a gap to
+close rather than a recorded exemption, and the flag answers which skills are
+missing theirs without a caller listing the directory itself. Nothing gates the
+rule yet, which is why the flag is worth reading against the shipped corpus after
+a merge.
+
+## 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
+```

package/docs/agents/tasks.md

@@ -0,0 +1,33 @@
+---
+title: Tasks
+description: Selecting a shipped task by stem or pull request, the refusal reasons, and why the board root defaults to the main worktree
+---
+
+# 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`.

package/docs/index.md

@@ -9,7 +9,6 @@ One-line reference for each doc in this folder.
 
 ## Agent surface
 
-- [Agents](agents.md): CLI catalog and invocation rules for agents
 - [AI workflow](ai-workflow.md): Overarching AI workflow across domains
 - [Target projects](target-projects.md): Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
 
@@ -18,3 +17,7 @@ One-line reference for each doc in this folder.
 - [Operating model](operating-model.md): Orchestrator and worker roles for building across parallel sessions
 - [Visual design workflow](visual-design-workflow.md): Tiered guide for design and wireframe authoring with Claude Code
 - [Zshrc aliases for Claude Code](zshrc-aliases.md): Shell aliases that shorten common Claude Code invocations
+
+## Sub-catalogs
+
+- [Agents](agents/index.md): CLI catalog and invocation rules for agents, split by command domain. Start with overview.

package/docs/target-projects.md

@@ -8,7 +8,7 @@ category: Agent surface
 
 How a project outside this repo consumes the toolkit across its lifecycle. Three phases: scaffold once, add a domain later when a new need appears, and sync when the upstream toolkit moves.
 
-This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](agents.md). For per-domain mechanics, see each `.claude/context/<domain>.md`.
+This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](agents/index.md). For per-domain mechanics, see each `.claude/context/<domain>.md`.
 
 ## Getting the skills
 
@@ -179,7 +179,7 @@ Sync also refuses a target whose working tree is dirty, so commit or stash befor
 
 ## Related
 
-- [agents](agents.md): CLI flags, exit codes, and JSON output shapes
+- [agents](agents/index.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/index.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards.md): per-domain mechanics
 - [sandbox](../.claude/context/sandbox/index.md): scenario catalog for verifying domain flows

package/package.json

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

package/scripts/docs/list.sh

@@ -38,6 +38,35 @@ is_internal_topic() {
   esac
 }
 
+# Emits `name<TAB>description<TAB>category<TAB>target` per target-facing doc,
+# sorted so a domain split into a folder lands in its alphabetical place rather
+# than after every file. A folder declares its category on its own index, since
+# the allowlist is what separates a target-facing doc from a workflow one and a
+# split domain is not exempt from it.
+collect_docs() {
+  local file name description category
+  {
+    while IFS= read -r file; do
+      name=$(basename "$file" .md)
+      [ "$name" = "index" ] && continue
+      category=$(read_frontmatter_field "$file" "category")
+      is_target_facing "$category" || continue
+      description=$(read_frontmatter_field "$file" "description")
+      printf '%s\t%s\t%s\t%s\n' "$name" "$description" "$category" "docs/$name.md"
+    done < <(find "$DOCS_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")")
+      category=$(read_frontmatter_field "$file" "category")
+      is_target_facing "$category" || continue
+      description=$(read_frontmatter_field "$file" "subtitle")
+      printf '%s\t%s\t%s\t%s\n' "$name" "$description" "$category" "docs/$name/index.md"
+    done < <(find "$DOCS_DIR" -mindepth 2 -maxdepth 2 -type f -name "index.md")
+  } | sort
+}
+
 # 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.
@@ -64,16 +93,11 @@ collect_context() {
 }
 
 list_text() {
-  local file name description category target
+  local name description category target
   log_step "Docs"
-  while IFS= read -r file; do
-    name=$(basename "$file" .md)
-    [ "$name" = "index" ] && continue
-    category=$(read_frontmatter_field "$file" "category")
-    is_target_facing "$category" || continue
-    description=$(read_frontmatter_field "$file" "description")
+  while IFS=$'\t' read -r name description category target; do
     log_info "$name : $description"
-  done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+  done < <(collect_docs)
 
   # Absent in a registry install, which ships docs/ without .claude/
   if [ -d "$CONTEXT_DIR" ]; then
@@ -97,17 +121,12 @@ emit_json_entry() {
 }
 
 list_json() {
-  local file name description category target
+  local name description category target
   JSON_FIRST=1
   printf '['
-  while IFS= read -r file; do
-    name=$(basename "$file" .md)
-    [ "$name" = "index" ] && continue
-    category=$(read_frontmatter_field "$file" "category")
-    is_target_facing "$category" || continue
-    description=$(read_frontmatter_field "$file" "description")
-    emit_json_entry "$name" "$description" "$category" "docs/$(basename "$file")"
-  done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+  while IFS=$'\t' read -r name description category target; do
+    emit_json_entry "$name" "$description" "$category" "$target"
+  done < <(collect_docs)
 
   if [ -d "$CONTEXT_DIR" ]; then
     while IFS=$'\t' read -r name description target; do

package/scripts/manage-sandbox.sh

@@ -296,6 +296,10 @@ inject_changed_skills() {
   [ -z "$combined" ] && return
 
   while IFS= read -r skill_path; do
+    # The diff against main lists a deleted skill alongside a changed one, and
+    # there is nothing left to inject for a name this branch removed.
+    [ -f "$PROJECT_ROOT/$skill_path" ] || continue
+
     local skill_name
     skill_name=$(basename "$(dirname "$skill_path")")
     local target_dir="$SANDBOX/.claude/skills/$skill_name"

package/src/commands/sandbox.ts

@@ -389,7 +389,7 @@ function runCheck(
 
   // The report always renders on stderr. `--json` adds the machine copy on
   // stdout rather than replacing the frame, per the stream contract in
-  // `docs/agents.md`, so one invocation serves a human and a caller at once.
+  // `docs/agents/output-shape.md`, so one invocation serves a human and a caller at once.
   reportVerdict(verdict)
   if (options.json === true)
     process.stdout.write(`${JSON.stringify(verdict)}\n`)

package/src/sandbox/census.ts

@@ -70,7 +70,7 @@ export function listSkills(root: string): string[] {
  * Maps a scenario to the skill it drives, trying two spellings in order.
  *
  * `<category>-<command>` is the rule `.claude/context/sandbox/coverage.md` states, and it
- * alone pairs 29 of 55 skills. The bare `<command>` fallback is what reaches the
+ * alone pairs 29 of 54 skills. The bare `<command>` fallback is what reaches the
  * rest: `claude/setup-init.sh` drives the `setup-init` skill, not a
  * `claude-setup-init` that does not exist. Stating one spelling and shipping two
  * is what let the audit report a paired skill as unpaired.

package/src/ui.ts

@@ -31,7 +31,7 @@ export function logRemove(message: string): void {
 }
 
 /**
- * Renders the `✗` shape `docs/agents.md` specifies for a failure inside an
+ * Renders the `✗` shape `docs/agents/output-shape.md` specifies for a failure inside an
  * open frame. It does not exit, so the caller closes the frame and returns an
  * exit code rather than terminating mid-write.
  */

package/standards/bundled/snippets.md

@@ -1,7 +1,7 @@
 ---
 title: Snippet reference
 description: Snippet reference and authoring conventions
-consumers: create-standard
+consumers: create-snippet
 ---
 
 # Snippet reference

package/standards/skill.md

@@ -11,7 +11,7 @@ Skills give Claude Code domain-specific constraints and rules inline, so it can
 
 ## Scope
 
-Governs a skill folder under `skills/` as one artifact: `SKILL.md`, its optional sibling `REQUIREMENT.md`, and the bundled reference, script, and asset folders beside them.
+Governs a skill folder under `skills/` as one artifact: `SKILL.md`, its sibling `REQUIREMENT.md`, and the bundled reference, script, and asset folders beside them.
 
 Does not govern:
 
@@ -68,14 +68,14 @@ allowed-tools: <tools required>
 
 ## Structure
 
-- Skill is a folder named in kebab-case containing `SKILL.md` (required), `REQUIREMENT.md` (optional), `scripts/` (optional), `references/` (optional), `assets/` (optional)
+- Skill is a folder named in kebab-case containing `SKILL.md` (required), `REQUIREMENT.md` (required), `scripts/` (optional), `references/` (optional), `assets/` (optional)
 - `SKILL.md` must start with YAML frontmatter between `---` delimiters
 - No `README.md` inside the skill folder
 - No spaces, capitals, or underscores in folder or skill name
 
 ## Requirement
 
-`REQUIREMENT.md` states what a skill is for, so a proposed change can be argued against something. This standard governs shape across the corpus and the requirement governs scope for one skill. Claude Code loads `SKILL.md` as the entry and ignores the sibling, so the file costs a target session nothing.
+`REQUIREMENT.md` states what a skill is for, so a proposed change can be argued against something and the corpus can be read to decide whether a skill should exist at all. This standard governs shape across the corpus and the requirement governs scope and behavior for one skill. Claude Code loads `SKILL.md` as the entry and ignores the sibling, so the file costs a target session nothing.
 
 The file serves a second purpose beside the argument. A skill body is procedural by design, so what the skill is for sits spread across its steps rather than stated in one place. The requirement is the compressed statement a reader gets before opening the body, and that purpose holds whether or not the skill's scope is contested.
 
@@ -83,7 +83,7 @@ Read it before editing the skill. When a change closes no gap the requirement st
 
 Write the gaps from what the skill is for, then compare the body against them. Deriving the requirement from the body is circular, because a requirement reverse-engineered from an overfitted skill records the overfitting as the requirement. That failure costs more under the orientation purpose than under the argument one, since a file summarizing the body misinforms whoever reads it in place of the body rather than merely failing to gate a change.
 
-A skill earns one when a reader cannot recover what the skill is for from the body alone. Apply the test to a skill nobody in the session has read before: read the body once, then state both the failures the skill exists to prevent and the nearest thing it deliberately does not do. A body answering both is its own specification and needs no sibling, and a body leaving either open earns one. Length is a weak proxy for that, since a short skill with a contested boundary earns one and a long skill doing one plain thing may not.
+Every skill carries one. Coverage was selective while the file existed only to disambiguate a contested boundary, and a file present for some skills and absent for others cannot be scanned, because an absence reads as a gap rather than as a verdict. A skill whose scope nobody contests still owes the statement, since the reader deciding whether a skill should exist reads the corpus rather than one entry. A new skill is created with the sibling beside it rather than acquiring one in a later sweep.
 
 ### What a working requirement looks like
 

package/claude/skills/claude-design-propose/SKILL.md

@@ -1,15 +0,0 @@
----
-name: claude-design-propose
-description: Retired. `claude-design-extract` absorbed this skill and now takes the greenfield path itself. Invoke `aitk:claude-design-extract` instead.
-disable-model-invocation: true
----
-
-# Design propose
-
-Retired. `claude-design-extract` absorbed the greenfield path, picks it from what the project has, and its description carries every trigger this skill used to route on.
-
-Invoke `aitk:claude-design-extract` instead. It reads `.claude/REQUIREMENTS.md` for the `## Personality` paragraph and `.claude/ARCHITECTURE.md` for platform signals when the project has no UI code, which is what this skill did.
-
-This body exists so a project that installed the plugin before the merge keeps resolving the old name for one sync cycle. It ships in `0.18.0` and is removed in `0.19.0`.
-
-`scripts/sandbox/claude/design-propose.sh` goes at the same time, but its fixture does not. That scenario is the only greenfield coverage the survivor has, so `0.19.0` folds it into `scripts/sandbox/claude/design-extract.sh` as a second arm rather than deleting it. Removing the file outright drops the greenfield path from the catalog.