@erclx/aitk 0.8.0

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

@@ -0,0 +1,45 @@
+---
+name: toolkit-operator
+description: Front door to the toolkit in a target project. Orients on the toolkit's own docs and live `aitk` catalogs, then runs or routes any toolkit operation from a plain-language intent. Use when you want one entry point instead of picking a specific setup or sync skill, or when asked to "use the toolkit", "what can the toolkit do", "sync my standards", "install rules", or "help me set up this project". User-invoked only. Defers first-time scaffold to setup-init and seed drift to claude-seed-sync.
+disable-model-invocation: true
+---
+
+# Toolkit operator
+
+Front door to the toolkit. Orient first, then run the simplest operation that satisfies the intent or hand off to the owning skill. Never bypass `aitk` to edit managed files by hand.
+
+## Orient
+
+Run these from the target project root, in parallel, before acting:
+
+- `aitk docs list`: the index of toolkit reference docs
+- `aitk docs agents`: the CLI command catalog and invocation contract
+- `aitk docs target-projects`: the scaffold, add-a-domain, and sync lifecycle
+
+Load a domain doc with `aitk docs <topic>` only when the intent touches that domain. Read the live catalog for any domain you act on with `aitk <domain> list --json`. Never hardcode stack, rule, snippet, or standards names.
+
+## Route
+
+Map the stated intent to one lifecycle phase, then act:
+
+- First-time scaffold of a fresh project: hand off to `setup-init`
+- Governance rules for the project stack: hand off to `setup-gov`
+- Bootstrap the `index.md` system: hand off to `setup-indexes`
+- Seed or standards drift in `CLAUDE.md` or `.claude/` preambles: hand off to `claude-seed-sync`
+- Install one snippet, standard, or rule: run the domain `install` command
+- Sync one domain or every installed domain: run `aitk <domain> sync` or `aitk sync`
+- Browse what is available: run `aitk <domain> list`
+
+## Execute
+
+For operations this skill runs directly:
+
+- Read the catalog first with `aitk <domain> list --json`, then match against project context
+- Run the CLI with `AITK_NON_INTERACTIVE=1` so it skips prompts. The tool permission dialog is the confirmation gate.
+- Report the command run and what changed. Emit the full relative path for any file written.
+
+## Boundaries
+
+- Run `aitk`. Never reimplement its install or sync logic, and never edit managed files like rules, configs, or seeds by hand.
+- Hand off the deep flows. Do not duplicate `setup-init` detection or `claude-seed-sync` part-diffing inline.
+- Resolve names from catalogs at runtime. A hardcoded name is a bug.

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

@@ -0,0 +1,63 @@
+---
+name: toolkit-triage
+description: Triage open GitHub issues labeled `feedback` in the toolkit repo. List them, pick one, classify it as a direct fix or plan-worthy work, route to the right skill, and link the issue for close-out. Use when asked to "triage toolkit feedback", "work through the feedback issues", "process feedback issues", or "what feedback is open". Do NOT use to file new feedback (that is `toolkit-feedback`), or for general GitHub issue triage unrelated to toolkit feedback.
+---
+
+# Toolkit triage
+
+Consume the feedback queue that `aitk feedback --github` fills. Turn an open `feedback` issue into a scoped fix or a plan, then link the issue so merge closes it.
+
+Run from the toolkit repo root. This skill reads GitHub issues, not local `.claude/review/` files. Those are ephemeral session scratch. The durable, cross-project queue is GitHub.
+
+## Guards
+
+- If `gh` is not on PATH, stop: `❌ gh CLI not found. Install it to read feedback issues.`
+- If `gh auth status` fails, stop: `❌ gh is not authenticated. Run gh auth login.`
+- If no open `feedback` issues exist, stop: `✅ No open feedback issues.`
+
+## Step 1: list the queue
+
+Fetch open feedback issues:
+
+```bash
+gh issue list --label feedback --state open --json number,title,url --jq '.[] | "#\(.number)\t\(.title)\t\(.url)"'
+```
+
+Print each as a numbered line with its issue number, title, and URL. Do not open bodies yet. Ask which to triage, and accept "all" to work them in order.
+
+## Step 2: read and classify
+
+For each picked issue, read the body:
+
+```bash
+gh issue view <n> --json title,body,labels --jq '"\(.title)\n\n\(.body)"'
+```
+
+Classify against the toolkit's own surfaces. Score in this order and stop at the first match:
+
+1. **Direct fix.** One surface, one file, no architectural choice. A typo, a stale reference, a one-line rule or doc correction, a single wording fix. Route straight to the edit.
+2. **Plan-worthy.** Multiple files, a new skill or rule, a behavior change, or a cross-surface move. Route to `claude-feature`.
+3. **Needs clarification.** The observed and expected behavior conflict or the surface is unnamed. Comment on the issue asking for the missing detail, then skip it.
+
+State the class and the one-line reason per issue before routing. Do not batch unrelated fixes into one branch.
+
+## Step 3: route
+
+- Direct fix: rename the branch to a conventional name (invoke `git-branch`), make the edit, then open the PR with `git-pr`.
+- Plan-worthy: invoke `claude-feature` with the issue body as the feature description. Let it write the plan and stop. Hand the plan slug back to the user. Do not implement.
+- Needs clarification: `gh issue comment <n> --body "<one question>"`, then move on.
+
+Match one issue to one branch and one PR. A single feedback issue is a single unit of work.
+
+## Step 4: close-out
+
+Link every fix back to its issue so the queue drains on merge.
+
+- For a PR-backed fix, add a `Closes #<n>` line to the PR body so GitHub closes the issue on merge. When `git-pr` regenerates the body, keep that line.
+- For a fix that ships without a PR, close it directly: `gh issue close <n> --comment "Fixed in <commit or PR url>."`
+- For a plan-worthy route, leave the issue open. It closes when the resulting PR merges with its `Closes #<n>` line.
+
+## Notes
+
+- The `feedback` label is what `aitk feedback --github` and the `toolkit-feedback.yml` issue form both apply. An issue without it does not surface here by design.
+- This skill routes, it does not reimplement. `claude-feature` owns planning, `git-pr` owns the PR body, `git-branch` owns the branch name. Do not duplicate their logic.

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

@@ -0,0 +1,34 @@
+---
+name: youtube-transcripts
+description: Fetches a YouTube video transcript with metadata frontmatter into the current repo via `aitk transcripts`. Use when the user pastes a YouTube URL and asks to grab the transcript, pull captions, or save a transcript for context. Do NOT use for downloading the video file, summarizing a transcript that already exists, or non-YouTube links.
+---
+
+# YouTube transcripts
+
+Turn a pasted YouTube URL into a markdown file with YAML frontmatter and a cleaned prose body. The `aitk transcripts` command owns the fetch, VTT cleanup, and frontmatter. Do not reimplement that logic. See `.claude/context/transcripts.md` for the output format and field list.
+
+## Guards
+
+- If no URL is provided, stop: `❌ No URL. Paste a YouTube link to fetch.`
+- If the link is not a YouTube URL, stop: `❌ Not a YouTube URL. This skill fetches YouTube captions only.`
+
+## Prerequisite
+
+The command shells out to the `yt-dlp` binary. If a run fails with a `yt-dlp not found` message, tell the user to install it from `https://github.com/yt-dlp/yt-dlp` and stop. Do not attempt to install it.
+
+## Run
+
+From the project root, fetch the URL:
+
+```bash
+aitk transcripts <url>
+```
+
+- Pass `--keep-timestamps` when the user wants `[mm:ss]` markers per line instead of prose.
+- Pass `--out <dir>` to override the output directory. The default is `transcripts/` in the current directory.
+- The written file path prints to stdout. Surface it back to the user as a full relative path so it is clickable.
+
+## After the fetch
+
+- When the run reports `has_transcript: false`, tell the user the video has no auto-captions. The file still exists with frontmatter for later use.
+- Do not summarize or annotate the transcript unless the user asks. Fetching and reading are separate requests.

package/docs/agents.md

@@ -0,0 +1,371 @@
+---
+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)                                                  |
+| `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`)                             |
+| `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            |
+
+### 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`, `setup [dest]`                           |
+| `wiki`      | `init`                                                                 |
+| `design`    | `render`                                                               |
+| `slides`    | `render`, `list`                                                       |
+| `tasks`     | `archive`                                                              |
+
+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 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 needs `.claude/aitk.json`, which every install and sync
+writes. Without it, every difference reports as `drifted`.
+
+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. 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`, and denials from a run       |
+| `--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 and the turn ceiling 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.
+
+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.
+
+```bash
+aitk sandbox coverage --json
+```
+
+| Flag       | Effect                                            |
+| ---------- | ------------------------------------------------- |
+| `--json`   | Emit the coverage record on stdout                |
+| `--strict` | Exit 1 while any scenario declares no expectation |
+
+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.
+
+`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.
+
+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`.
+
+## 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                               |
+| `aitk gov list --json`          | Governance stacks and rule sets              |
+| `aitk claude seeds list --json` | Seed doc sources with content                |
+| `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 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.
+
+## 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