@aperant/framework 0.7.0 → 0.7.3

package/dist/plugin/skills/apt-update/SKILL.md

@@ -15,7 +15,7 @@ execution_modes:
   - auto
   - step
 allowed-tools: "Bash, Read, Write"
-argument-hint: "apt:update"
+argument-hint: "apt:update [--from-source]"
 gates: []
 ---
 
@@ -42,35 +42,101 @@ The cache file is at `~/.cache/aperant/apt-update-check.json`. It contains `runt
 
 ## 1. Read current state
 
+<!-- TODO(followup): support PATH-only / npx-only kernel installs. The
+     hardcoded `.aperant/deps/...` path below fails users who don't have a
+     project-local kernel directory. Tracked as a separate task. -->
 ```bash
 node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs check-version . --json
 ```
 
-Parse the JSON. Capture:
+Parse the JSON. From 0.6.7 the envelope merges the SessionStart worker's cache (when fresh — written within the last hour to `~/.cache/aperant/apt-update-check.json`). Capture:
+
 - `framework.installed_version` — what's currently on disk
-- `framework.latest_version` — what's in the source / published
+- `framework.latest_version` — what npm reports as the latest published version (MAY BE `null` when the worker cache is stale / missing / wrong schema)
 - `runtimes[]` — list of installed runtime ids + per-runtime `stale_files` count
 - `stale_files_total` — drift tally across runtimes
+- `update_available` — true when worker cache is fresh AND `installed_version < latest_version`
+- `dev_install_ahead` — true when local kernel is ahead of published (typical local dev)
+- `not_published` — true when npm returned 404 (package not yet on registry)
+- `lookup_error` — non-null when npm view failed for any non-404 reason (timeout, ENETDOWN, etc.)
+
+The envelope is **single-shape** — every field above is always present. When the worker cache is stale or missing, `latest_version` is `null`, the four booleans are `false`, `stale_files_total` falls back to a local-only count, and `lookup_error` is `null`. Your parser doesn't need to branch on cache freshness.
 
 If `runtimes[]` is empty, tell the user they haven't installed Aperant into any runtime yet and suggest `apt-tools init . --claude` (or their preferred runtime). Stop.
 
+## 1.5. Bump the local kernel from npm when newer is available
+
+The Aperant kernel lives at `.aperant/deps/node_modules/@aperant/framework/`. `apt-tools init` re-installs runtime files at THE LOCAL KERNEL'S VERSION — so a stale kernel means `/apt:update` re-stamps manifests at the OLD version even when npm has a newer release. Bump the kernel BEFORE invoking init.
+
+First, resolve `latest_version` when the envelope had `null` (stale cache).
+
+**Timeout enforcement (ID-04):** The `npm view` call must complete within 10 s — never block the user longer than the SessionStart worker would. Use npm's `--fetch-timeout` flag as the primary mechanism (universally portable across all npm versions); it sets the HTTP fetch timeout in milliseconds:
+
+```bash
+npm view @aperant/framework version --fetch-timeout=10000 --fetch-retries=0 --json --silent 2>/dev/null || true
+```
+
+On Linux/macOS with GNU coreutils installed, you MAY additionally wrap with a hard shell-level timer: `timeout 10 npm view ...` (Linux) or `gtimeout 10 npm view ...` (macOS via `brew install coreutils`). Shell-level wrapping is optional — `--fetch-timeout=10000` alone is sufficient because it is universal. Do NOT rely solely on the shell `timeout` command without the npm flag, as it is not available on all systems.
+
+If npm exits non-zero or times out, surface a one-line warning (`⚠ npm view failed — using local kernel`) and proceed; the local kernel still works for the runtime refresh, just at the older version.
+
+**Security (SEC-001):** Before interpolating `latest_version` into any shell command, verify it matches the semver pattern `^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$`. If it does not match, treat it as missing and fall back to the explicit version pinning path (proceed with the local kernel version, surface `⚠ latest_version invalid — using local kernel`). This protects against a poisoned cache entry reaching a shell command.
+
+When `installed_version < latest_version`, bump:
+
+```bash
+npm install --prefix .aperant/deps @aperant/framework@<latest_version> --no-save --no-package-lock --no-audit --no-fund
+```
+
+On `npm 404` (`E404` in stderr) treat it as `not_published` and skip the kernel bump (proceed to step 3). On any other npm failure, surface the npm stderr verbatim and STOP — do NOT proceed to init with a half-installed kernel.
+
+## 1.6. Self-host case — bump from local workspace (FRAMEWORK-BUG-017)
+
+When the user invokes `/apt:update --from-source` OR the route envelope's `update_check.reason` mentions `workspace source ahead of installed kernel`, the source of truth is the local `packages/framework/` workspace — NOT npm. This is the Aperant-contributor self-host case: a same-PR framework fix bumps the workspace `packages/framework/package.json:version` but the kernel under `.aperant/deps/node_modules/@aperant/framework/` still reflects the previous version. Step 1.5's `npm view` would fetch the published version (still the OLD one), so we must skip it.
+
+The reliable bump mechanism mirrors what `runKernelInstall` does today — `pnpm pack` produces a versioned tarball, then `npm install --prefix` consumes it. Symlinking is fragile across re-installs and `pnpm install --filter` doesn't relocate the published artifact into `.aperant/deps`.
+
+Walk up from the project root looking for a sibling `packages/framework/package.json`. When found AND its `name === "@aperant/framework"`:
+
+```bash
+# 1. Pack the workspace source into a versioned tarball.
+cd <workspace-root>
+pnpm --filter @aperant/framework pack --pack-destination /tmp
+
+# 2. Install the tarball into the project's kernel root.
+cd <project-root>
+npm install --prefix .aperant/deps /tmp/aperant-framework-<version>.tgz --no-save --no-package-lock --no-audit --no-fund
+```
+
+Replace `<version>` with the workspace `package.json:version` you just read. The tarball name follows npm's `pack` convention (`@aperant/framework@X.Y.Z` → `aperant-framework-X.Y.Z.tgz`).
+
+If `--from-source` was passed but no `packages/framework/package.json` is found anywhere above the project root, surface a one-line error (`⚠ --from-source: no workspace package.json found — falling back to npm`) and proceed with the standard step 1.5 npm path.
+
+Then proceed to step 3 to re-install the runtime files at the new kernel version. Skip step 4 (cache clear) — the cache is keyed on `latest_version` from npm, and a `--from-source` bump never wrote to it, so there's nothing to invalidate.
+
 ## 2. Classify the update scenario
 
-Pick ONE of three scenarios based on what you just parsed:
+Pick ONE of three scenarios based on what you parsed in step 1:
 
-- **A. Version bump available** — `installed_version !== latest_version` (regardless of drift). Users see this most often.
-- **B. Drift only** — `installed_version === latest_version` but `stale_files_total > 0`. User hand-edited an installed file or something was partially overwritten.
-- **C. Nothing to do** — `installed_version === latest_version` AND `stale_files_total === 0`. Still re-run init to refresh the update-check cache, but tell the user plainly that no changes were applied.
+- **A. Version bump available** — `installed_version !== latest_version` (regardless of drift). Users see this most often. Step 1.5 bumped the kernel; step 3 re-stamps manifests at the new version.
+- **B. Drift only** — `installed_version === latest_version` but `stale_files_total > 0`. User hand-edited an installed file or something was partially overwritten. Step 1.5 was a no-op; step 3 still needs `--force-runtimes` to re-stamp.
+- **C. Nothing to do** — `installed_version === latest_version` AND `stale_files_total === 0`. Still re-run init with `--force-runtimes` to refresh manifests + cache, but tell the user plainly that no version change happened.
 
 ## 3. Re-install the currently-installed runtimes
 
-Build the flags list from the runtime ids (e.g. `--claude --codex`) and run:
+Build the flags list from the runtime ids (e.g. `--claude --codex`) and pass `--force-runtimes` so init bypasses the `upgrade_noop` short-circuit (Bug 2 fix, 0.6.7) and re-stamps every manifest:
+
+```bash
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs init . --claude --force-runtimes
+```
+
+Example with multiple runtimes installed:
 
 ```bash
-node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs init . <flags>
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs init . --claude --codex --force-runtimes
 ```
 
-**Do NOT add `--yes`, `--solo`, `--team`, or any other Class A flag.** This command is meant to refresh runtime files only — adding `--yes` triggers a config schema migration that can silently flip `share.visibility` to `solo` and re-write `.gitignore`, which is exactly the 0.6.0/0.6.1 dogfood bug. If `init` returns a `requires_input` envelope (schema drift), surface it to the user verbatim and stop; let them decide team vs solo with the explicit flag. From 0.6.4 onward `--yes` infers visibility from existing git tracking, but the skill must still not add it — keep this command scoped to runtime refresh.
+**Do NOT add `--yes`, `--solo`, `--team`, or any other Class A flag.** This command is meant to refresh runtime files only — adding `--yes` triggers a config schema migration that can silently flip `share.visibility` to `solo` and re-write `.gitignore`, which is exactly the 0.6.0/0.6.1 dogfood bug. `--force-runtimes` is the ONLY new flag this skill adds. If `init` returns a `requires_input` envelope (schema drift), surface it to the user verbatim and stop; let them decide team vs solo with the explicit flag. From 0.6.4 onward `--yes` infers visibility from existing git tracking, but the skill must still not add it — keep this command scoped to runtime refresh.
 
 Parse the init JSON. Capture for each runtime:
 - `install_root` (shortened to the basename, e.g. `.claude`)
@@ -164,5 +230,6 @@ Runtime files were still refreshed; `/apt` will still work from PATH if `apt-too
 - **Worker hasn't run yet**: the cache file is missing. That's fine — run check-version directly (step 1 is robust to a missing cache). Proceed normally.
 - **Re-install fails (non-zero exit from init)**: surface the JSON `error` field verbatim in a single line, then stop. Do NOT delete the cache file — the chip should remain visible so the user sees the failure persists.
 - **Kernel install fails but runtime install succeeds**: see Scenario D above. Do not treat this as a total failure; the user's skills still work via PATH fallback.
+- **CLAUDE.md / AGENTS.md foreign rows (exit 2, `instruction-file.foreign-rows`)** — 0.7.0+ — init now refuses to silently clobber custom rows in the `<!-- APT:framework-* -->` block. If `init` exits 2 with `code: instruction-file.foreign-rows`, the `foreignRowIds[]` field lists the rows the generator did NOT produce. Two paths: (a) remove the foreign rows from CLAUDE.md / AGENTS.md by hand and re-run init, or (b) re-run with `--force-overwrite-catalog` to regenerate anyway. Unattended upgrade flows should detect this code and surface it to the operator — silent bypass is a regression.
 
 </edge_cases>

package/dist/plugin/skills/apt-verify/SKILL.md

@@ -19,6 +19,9 @@ argument-hint: "apt:verify [--fast | --cross-verify]"
 gates: 
   - consistency-check
   - all-subtasks-complete
+config_keys:
+  - verification.evidence_capture
+  - verification.max_iterations
 ---
 <objective>
 Verify that the implementation matches the spec, all tests pass, code quality checks succeed, and sign off on the build.

package/dist/plugin/skills/apt-verify-proof/SKILL.md

@@ -17,6 +17,9 @@ execution_modes:
 allowed-tools: "Bash, Read, Write, Edit, Grep, Glob, Task"
 argument-hint: "apt:verify-proof [--multi-model | --video]"
 gates: []
+config_keys:
+  - verification.open_report
+  - verification.report_formats
 ---
 
 # Proof Verification
@@ -86,8 +89,10 @@ For multi-model verification details:
 
 ## Config
 
-Settings in `.aperant/config.json` control behavior (run `/apt:setup` to configure):
-- `verification.evidence_capture` — capture screenshots + terminal output (default: true)
-- `verification.open_report` — open HTML in browser when done (default: true)
-- `multi_model.enabled` — run multi-model verification (default: false)
-- `multi_model.gemini.model` — Gemini preset: default/thorough/fast
+Settings live in the MERGED Aperant config (shared `.aperant/config.json` + per-device `.aperant/config.local.json`; local wins). Run `/apt:setup` to configure. Read via `apt-tools config read .` or the framework's `loadMergedProjectConfig()` — NEVER raw `JSON.parse(readFileSync('.aperant/config.json'))`, which misses per-device overrides.
+
+- `verification.evidence_capture` — shared. capture screenshots + terminal output (default: true)
+- `verification.open_report` — **per-device (config.local.json)** per AUDIT-001. open HTML in browser when done (default: true)
+- `multi_model.enabled` — shared. run multi-model verification (default: false)
+- `multi_model.cross_verification.tools` — **per-device (config.local.json)** per AUDIT-001. which CLIs to cross-verify with.
+- `multi_model.gemini.model` — shared. Gemini preset: default/thorough/fast

package/dist/plugin/skills/apt-watch-ci/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: apt:watch-ci
+description: "Post-ship CI watcher — polls PR checks, auto-fixes red, pushes, reschedules"
+apt-skill-version: {{APT_VERSION}}
+stage: ship
+intent: x-watch-ci
+when_to_use: "A PR has been shipped and CI is running. Use to watch its checks on a recurring tick, auto-fix red checks from first red, push fixes, and reschedule until green / merged / closed / 5 attempts / 4h wall."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: require-existing
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
+argument-hint: "apt:watch-ci [--pr N | --tick --pr N | --stop --pr N | --resume --pr N]"
+gates: []
+config_keys:
+  - ci_watch.after_ship
+  - ci_watch.auto_merge_on_green
+---
+
+# /apt:watch-ci — Post-ship CI Watcher
+
+You are a **post-ship CI watcher**. After a PR has been opened by `/apt:ship`, you watch its checks on a recurring tick, auto-fix red checks from the first red, push the fix, and reschedule yourself until the PR is green / merged / closed, or you hit the 5-attempt / 4h wall budget.
+
+This skill is **one-tick-per-invocation** (D-01). It MUST NOT enter a polling loop. The recurring beat is delivered externally — by Claude Code's `CronCreate` on cron-capable hosts, by Pi's `pi-schedule-prompt` on Pi, or by the user re-invoking `/apt:watch-ci --tick --pr N` on non-cron hosts. Each invocation does at most one of: poll + classify + maybe-fix + push + reschedule, then exits.
+
+The locked decisions backing every section are in `.aperant/context/notes/framework-post-ship-ci-watcher.md` (D-01..D-08).
+
+---
+
+## Your environment
+
+- **Working directory:** the task's worktree (or the project root if this is a non-worktree task).
+- **State files:** `.aperant/ci-watches/{pr}.json` (per-PR state, D-04); `.aperant/ci-watches/{pr}.lock` (per-PR atomic lock, D-05). Both ephemeral — they are NOT committed.
+- **Events:** every tick appends a `ci-watch.tick` event to `.aperant/events/{today}.jsonl`; `start` appends `ci-watch.armed`; the fix-and-push path appends `ci-watch.fix-pushed`; terminal actions append `ci-watch.stopped` with a `reason`.
+- **CLI surface:** `apt-tools ci-watch start|stop|status|tick --pr N`. The skill body shells out to those subcommands — DO NOT re-implement the classifier in your prompt; the cmd already does it.
+
+---
+
+## §1. Resolve mode
+
+Parse the flags:
+- No flag → "start a watch for the active task's PR" (resolve PR number from `.aperant/state.json` active task's `pr_url` field).
+- `--tick --pr N` → run one tick for PR N. This is the cron payload's invocation form.
+- `--stop --pr N` → tear down the watch.
+- `--resume --pr N` → clear the `paused: true` flag and return to normal tick.
+
+If no PR can be resolved (no active task, no `pr_url`), print an error and exit — there is nothing to watch.
+
+---
+
+## §2. Lock acquire
+
+For everything except `status`, the imperative work happens inside `apt-tools ci-watch tick`, which acquires the per-PR lock itself. If `tick` returns exit code 2 with `{status:"busy", reason:"lock-held"}`, another invocation is already running for this PR. Print:
+
+```
+Watcher already running for PR {N} (held by sessionId={x}, pid={y}); exiting.
+```
+
+…and exit. Do NOT block, retry, or kill the holder.
+
+---
+
+## §3. One-tick semantics (the heart of D-01)
+
+For the `--tick` mode, execute exactly the following sequence — once — inside this single skill invocation:
+
+1. **Poll.** Call `gh pr checks <N> --json name,bucket,state,conclusion,detailsUrl` and `gh pr view <N> --json state,reviewDecision`. Combine both JSON outputs into a single file shaped `{checks: <pr-checks-json>, prMetadata: <pr-view-json>}` (for example with `jq -s '{checks: .[0], prMetadata: .[1]}'`) and save it as `{captured.json}` (any path under the worktree is fine). On any `gh` failure, omit the file and let the cmd's `tick` route to `infra-backoff` (it surfaces the same action when no payload is available).
+2. **Classify + state update.** Call `apt-tools ci-watch tick {worktree} --pr {N} --payload-file {captured.json}`. The cmd reads `{captured.json}` from disk and runs the classifier — it does NOT shell out to `gh` itself (that boundary stays with the orchestrator skill; see commands/ci-watch.mjs:15). The cmd internally:
+   - acquires the per-PR lock (BUSY → exit 2 → step §2);
+   - reads the per-PR state file;
+   - runs the stop-matrix classifier (`packages/framework/src/cli/ci-watch/stop-matrix.mjs`);
+   - applies the action's state mutation (attempts++, last_status fingerprint, paused, etc.);
+   - releases the lock;
+   - returns `{status, action, attempts_used, next_tick_at, reason}`.
+3. **Branch on `action`** — see §4 (terminal), §5 (fix), §6 (non-counting), §7 (pause/resume).
+4. **Reschedule (next tick).** On Claude Code: refresh the `CronCreate` entry's next-fire timestamp (CronCreate is idempotent on the same payload). On Pi: do the equivalent via `pi-schedule-prompt`. On other hosts: print `Next tick: run /apt:watch-ci --tick --pr {N} when you return.` Do NOT register a cron on a non-cron host — the framework would be lying.
+5. **Emit event.** `apt-tools event append . --type ci-watch.tick --data '{...}'` with the cmd's envelope as the data payload. Non-fatal if it fails.
+
+---
+
+## §4. Terminal branches (green / merged / closed / *-cap / identical-log)
+
+When `action ∈ {green, merged, closed, attempts-cap, wall-cap, identical-log}`:
+
+- **green** — print "CI green for PR {N}." If `ci_watch.auto_merge_on_green` is `true` in `.aperant/config.json`, run `gh pr merge {N} --auto --squash` then suggest `/apt:close-task`.
+  - **DO NOT pass `--delete-branch`** to `gh pr merge` from this auto-merge path — ever, unconditionally. The watcher's cwd is the task worktree, where `gh`'s `--delete-branch` post-merge cleanup tries to `git switch <base>` and fails because `<base>` is checked out in the primary worktree. The remote merge has already succeeded by then; local branch + worktree cleanup is `/apt:close-task`'s job via `apt-tools task close-merged` → `computeWorktreeCleanup` (see FRAMEWORK-BUG-019).
+
+  Else print the exact D-08 text:
+
+  ```
+  ✅ CI green — merge in browser or run /apt:close-task post-merge
+  ```
+
+- **merged** / **closed** — print a one-line summary. No PR comment needed.
+
+- **attempts-cap** / **wall-cap** / **identical-log** — these are bail conditions. Leave a PR comment via `gh pr comment {N} --body "<summary>"` describing why the watcher stopped (attempt count, deadline, fingerprint). The user comes back to find a structured note in the PR.
+
+In all terminal cases:
+- Stop the host scheduler (`CronDelete` on Claude Code, `pi schedule remove` on Pi, no-op elsewhere).
+- The cmd already deleted the state file when it returned `status: 'stopped'`. Do NOT re-delete it.
+- Emit `ci-watch.stopped` event with the matching `reason`.
+
+---
+
+## §5. Fix-and-push (D-02 — the auto-fix path)
+
+When `action === 'fix'` (or `diverged-rebased`/`diverged-bailed`):
+
+1. **Fetch the failed-check log.** From the gh payload, find the failed check's `detailsUrl` and call `gh run view {runId} --log` to capture the log into a temp file.
+2. **Shell out to the host CLI** to fix it. The watcher does NOT inline a custom fix prompt; it hands the worktree + failed-log to the same CLI binary that's running this skill (detected by `apt-tools host-detect`). Pseudocode:
+
+   ```bash
+   <host-cli-bin> --print "Fix this CI failure for PR {N}. The failed-run log is at {log_path}. Use the worktree at {worktree}. Land + push a commit with the fix." \
+     --cwd {worktree}
+   ```
+
+   The fix-CLI is responsible for the actual edits + verification + commit + push. This is a clean shell-out boundary — the watcher trusts the fix-CLI to land a commit (or to bail with a non-zero exit code, which the watcher treats as "no progress made this tick").
+3. **Did the fix change anything?** Run `git -C {worktree} status --porcelain`. If empty, the fixer made no changes → the next tick's classifier will see the same failure log and emit `identical-log`. Do NOT push.
+4. **Push.** `git -C {worktree} push origin {branch}`. On push failure, the next tick will route through `infra-backoff`.
+5. **Emit event.** `apt-tools event append . --type ci-watch.fix-pushed --data '{pr, attempts, commit_sha}'`.
+6. **Reschedule** per §3 step 4.
+
+For `diverged-rebased`: the cmd already returned the verb; the orchestrator runs `git -C {worktree} fetch && git rebase origin/{base}` BEFORE the fix step. On conflict the action becomes `diverged-bailed` and the watcher exits with a PR comment summarizing the conflict.
+
+---
+
+## §6. Non-counting branches (flake-skip / infra-backoff)
+
+When `action === 'flake-skip'` or `'infra-backoff'`:
+
+- **flake-skip:** Skip the fix path entirely. Reschedule at the normal interval. No PR comment.
+- **infra-backoff:** Same skip — but the next tick interval is doubled by the cmd (it wrote `next_tick_interval_ms *= 2` to state). The cron host re-invocation reads it. After one retry, if the same infra signal persists, post a PR comment marking the failure as `infra-incident`; do NOT keep doubling forever.
+
+---
+
+## §7. --stop / --resume flags
+
+- `--stop --pr N` — releases scheduler handle (`CronDelete` on CC, `pi schedule remove` on Pi, no-op elsewhere), deletes state file, emits `ci-watch.stopped` event with `reason:"user-stop"`. Idempotent — calling `--stop` on a PR with no active watch is fine.
+- `--resume --pr N` — only valid when state has `paused: true` (set by `reviewer-pause`). Clears the flag, returns to normal tick. Error envelope if no paused state for the PR.
+
+When the classifier returns `reviewer-pause`, the state's `paused: true` is set by the cmd, but the scheduler is NOT removed — the cron payload keeps firing, and each tick the cmd checks `paused` and exits early with action `reviewer-pause`. Cheaper than re-registering on `--resume`.
+
+---
+
+## §8. Single-execution-mode contract
+
+Reiterating because this is the most easily-broken invariant:
+
+- One tick = one invocation. **Do not** wrap the §3 sequence in a `while`/`until` loop.
+- **Do not** sleep + re-invoke yourself inside a single session.
+- The recurring beat is delivered by host cron OR by the user re-invoking the skill manually. The watcher's value comes from the host scheduler — it does not impersonate one.
+
+If you find yourself wanting to add "and then wait 5 minutes and run again," STOP. The skill is finished after one tick. Exit.
+
+---
+
+## Notes for the orchestrator
+
+- All gh CLI calls run with the host's existing auth. The watcher introduces no new secret material (per task `dimensions_covered.token-encryption.crossed: false`).
+- `auto_merge_on_green` is snapshotted from `.aperant/config.json` at `start` time (state file's `auto_merge_on_green` field). Changing the config mid-watch does NOT retroactively affect armed watches — re-run `start` to pick up the new value.
+- The fix-CLI shell-out is the cleanest abstraction we have for portability. It's NOT a sub-agent. On Claude Code that means another `claude` invocation; on Codex/Gemini/OpenCode/Pi, the equivalent binary. Detection lives in `apt-tools host-detect`'s `cli` field.

package/dist/plugin/skills/apt-zoom-out/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: apt:zoom-out
+description: "Orient yourself in an unfamiliar area of the codebase — load CONTEXT.md, map modules + callers, output a one-page orientation"
+apt-skill-version: {{APT_VERSION}}
+stage: plan
+intent: investigate
+when_to_use: "The user is dropped into a part of the codebase they don't know and wants a one-page architectural orientation before planning or editing. Natural-language triggers: 'give me a broader picture of X', 'I'm lost in this area', 'explain how this fits'."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: none
+default_track: STANDARD
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Grep, Glob"
+argument-hint: "apt:zoom-out [area-name]"
+gates: []
+---
+
+# Zoom-Out — One-page Architectural Orientation
+
+Tiny skill. High signal. The user named an area; you produce a one-page
+orientation so they (or a future agent) can plan or edit without
+re-learning the codebase from scratch.
+
+**Pocock adoption note.** This skill descends from Matt Pocock's `zoom-out`
+discipline. Aperant's router is dynamic and LLM-driven, so unlike Pocock's
+upstream this skill is **router-invocable** (no `disable-model-invocation:
+true` flag). The work-intent — "give me a broader picture of X" — is
+genuine and the router resolves natural-language triggers without forcing
+the user to remember the verb name.
+
+## When to Use
+
+- Dropped into a new module / package / area of the monorepo
+- About to plan a feature that crosses an unfamiliar boundary
+- The codebase has CONTEXT.md (Pocock glossary) and you want to load it
+  alongside the structural map
+
+## When Not to Use
+
+- The area is one you know well — `/apt:plan` already does targeted
+  investigation
+- You need to lock decisions (use `/apt:discuss` with the
+  `appendices/grill-discipline.md` posture loader instead)
+- The user wants to refactor proactively — that's `/apt:improve`
+
+## Process
+
+### 1. Parse the area name
+
+Extract the area from `$ARGUMENTS`. The area is a noun phrase, not a
+file path: e.g., `"chat session lifecycle"`, `"sparring engine"`,
+`"feature registry"`. If the argument is a file path, narrow the
+orientation to the file's enclosing module.
+
+### 2. Load CONTEXT.md (if present)
+
+If `CONTEXT.md` exists at the project root, read it and pre-load any
+term-blocks whose `Term` matches keywords in the area name (or whose
+`Aliases to avoid` field hints at the area). Carry these terms forward
+into the orientation report so the reader sees the vocabulary the
+codebase actually uses.
+
+If `CONTEXT.md` does not exist, skip silently — orientation still works,
+just without the glossary anchor.
+
+### 3. Map modules and callers
+
+Run Glob + Grep to identify:
+
+- **Entry points** — files in the area that other modules import (high
+  fan-in: many `import`-ers).
+- **State owners** — files that declare the area's persistent
+  state (Zustand stores, Convex queries, libSQL tables).
+- **External boundaries** — files that touch external systems (HTTP,
+  IPC, native modules, child processes).
+- **Known fragile areas** — search for `// TODO`, `// FIXME`, `// HACK`
+  comments + any recent commits touching the area (last 30 days).
+
+### 4. Emit the one-page orientation
+
+Output to stdout (no file written — this is a read-only orientation):
+
+```markdown
+# Orientation: {area name}
+
+## Purpose
+{One paragraph: what does this area exist to do?}
+
+## Entry points
+- `{path}` — {one-line role}
+- `{path}` — {one-line role}
+
+## State owners
+- `{path}` — {one-line: what state, what scope}
+
+## External boundaries
+- `{path}` — {one-line: which external system, what direction}
+
+## Known fragile areas
+- `{path}:{line}` — `// TODO` / `// FIXME` summary + age
+- {recent-commit-shortlog one-liner if relevant}
+
+## Glossary (from CONTEXT.md)
+- **{Term}** — definition + aliases-to-avoid
+- {…}
+
+## Pointers for the next agent
+- {one-line: where to start reading}
+- {one-line: which test file to read first}
+- {one-line: which CONTEXT.md term resolves the most ambiguity}
+```
+
+The orientation MUST fit on one screen. If it doesn't, you've gone too
+deep — re-scope the area name and try again.
+
+## Output contract
+
+- **Read-only.** This skill never writes files. It is a context-loader,
+  not a planner.
+- **Stops at orientation.** Do NOT pivot into `/apt:plan` automatically.
+  The user invokes `/apt:plan` (or `/apt:improve`) as a follow-up if the
+  orientation surfaces a planning opportunity.
+- **No grill posture.** This skill does NOT load
+  `apt-discuss/appendices/grill-discipline.md` — orientation is
+  descriptive, not normative. Locking decisions is `apt:discuss`'s job.