git:20260825.36a5f1a to git:20260825.5ae3d56

2 added, 8 removed. Audit A to A.

# DOX — .pi/skills

Files in this directory. One row per file. Non-source area (migrated from `docs/file-index-skills-misc.md`; source of truth now here). See change: migrate-file-index-to-agents-tree.

+ **Deliberately undocumented:** `openspec-*/` (except `openspec-shared/`) and `.pi/prompts/opsx-*.md` are vendored by the openspec CLI and gitignored via `.pi/.gitignore`. `kb dox lint` walks the filesystem, not git, so it reports them `missing` — that finding is expected. Do NOT add rows; they describe files absent from a fresh clone and drift on every openspec upgrade.

| File | Purpose |

|------|---------|

| `ci-troubleshoot/references/common-failures.md` | Detailed CI failure catalog: repo-lint tests (`no-raw-node-import`, `no-direct-process-kill`,… → see `ci-troubleshoot/references/common-failures.md.AGENTS.md` |

| `ci-troubleshoot/references/release-pipeline.md` | `publish.yml` gated 7-job graph, input semantics, literal diagnostics, recovery, post-release checks. → see `ci-troubleshoot/references/release-pipeline.md.AGENTS.md` |

| `ci-troubleshoot/references/workflow-taxonomy.md` | Current 10 workflow files: 8 entry workflows, 2 reusable workflows, triggers, purposes, release boundaries. → see `ci-troubleshoot/references/workflow-taxonomy.md.AGENTS.md` |

| `ci-troubleshoot/scripts/list-recent-runs.ts` | Wrap `gh run list`. Flags `--failed`, `--workflow <name>`, `-L <n>`. Ensures `gh` installed + authenticated. Filters tabular output to failure rows when `--failed`. Cross-platform (`shell:false`). |

| `ci-troubleshoot/scripts/retrigger-failed.ts` | Re-run failed jobs of a GitHub Actions run. `<run-id>` defaults to latest failed run (`findLatestFailedRun`). → see `ci-troubleshoot/scripts/retrigger-failed.ts.AGENTS.md` |

| `ci-troubleshoot/scripts/show-failed-run.ts` | Show failed steps + log tails. `<run-id>` defaults to latest failed run. Flag `--full` switches `gh run view --log` (full) over `--log-failed` (default). Prints run summary then failed-step logs. |

| `ci-troubleshoot/SKILL.md` | Diagnose GitHub Actions failures: 10 workflows, verified helpers, release gates, diagnostics, recovery. → see `ci-troubleshoot/SKILL.md.AGENTS.md` |

| `code-quality/SKILL.md` | code-quality skill. Biome analyze→fix→test. changed-files (goal-loop) + whole-repo (cleanup) modes. → see `code-quality/SKILL.md.AGENTS.md` |

| `debug-dashboard/references/isolated-verification.md` | Isolated UI/worktree verification. Live :8000 runs MAIN-repo code; `npm run build` leaks to `packages/client/dist`. Temp HOME + non-8000 ports + `PI_DASHBOARD_NO_MDNS=1`. Mockup-serve + worktree-harness recipe. |

| `debug-dashboard/references/known-issues.md` | Known-issue catalogue distilled from `docs/faq.md`: server won't start (Electron Node bin fallback… + new-session spawn_register_timeout (pi-crash vs overload split) → see `debug-dashboard/references/known-issues.md.AGENTS.md` |

| `debug-dashboard/references/log-locations.md` | Persistent file map. `~/.pi/dashboard/`: `server.log` (append, timestamped banners, grep recipes),… → see `debug-dashboard/references/log-locations.md.AGENTS.md` |

| `debug-dashboard/references/test-failure-triage.md` | Vitest failure triage. Golden rule tee→grep (`npm test 2>&1 | tee /tmp/pi-test.log`), standard greps,… → see `debug-dashboard/references/test-failure-triage.md.AGENTS.md` |

| `debug-dashboard/references/ui-debug.md` | Pointer to `browser` skill for UI/visual debugging. Symptom routing table:… → see `debug-dashboard/references/ui-debug.md.AGENTS.md` |

| `debug-dashboard/scripts/health-probe.ts` | Probe `GET /api/health`. Reads port from `~/.pi/dashboard/config.json` (default 8000). → see `debug-dashboard/scripts/health-probe.ts.AGENTS.md` |

| `debug-dashboard/scripts/list-sessions.ts` | List pi sessions via `GET /api/sessions`. Default: active only (filters `status !== 'ended'`). → see `debug-dashboard/scripts/list-sessions.ts.AGENTS.md` |

| `debug-dashboard/scripts/run-tests-triage.ts` | Runs `npm test` (or scoped variant), tees output to `${tmpdir}/pi-test.log`, prints FAIL-marker summary. → see `debug-dashboard/scripts/run-tests-triage.ts.AGENTS.md` |

| `debug-dashboard/scripts/tail-server-log.ts` | Tail `~/.pi/dashboard/server.log`. Default: last 50 lines of current run (since last `=== [ts] ===` banner). → see `debug-dashboard/scripts/tail-server-log.ts.AGENTS.md` |

| `debug-dashboard/SKILL.md` | System-level debugging for running dashboard. Three layers: server alive (`health-probe.ts`,… → see `debug-dashboard/SKILL.md.AGENTS.md` |

| `edit-flow/SKILL.md` | Skill: create/edit pi-flows flows + agents via `flow_agents` + `flow_write`. → see `edit-flow/SKILL.md.AGENTS.md` |

| `frontend-mockup-loop-dashboard/SKILL.md` | Skill. Dashboard adapter over frontend-mockup-loop. Binds 7-step loop to `packages/client` sources, theme-system tokens (4 themes), isolated-verification, `openspec/changes/<name>/mockups/`. |

| `implement/references/code-discipline.md` | Reference: expands AGENTS.md "Code Instructions" 5 rules with worked examples. → see `implement/references/code-discipline.md.AGENTS.md` |

| `implement/references/rebuild-matrix.md` | Reference: full 3-component rebuild matrix. Per-component recipes — extension `npm run… → see `implement/references/rebuild-matrix.md.AGENTS.md` |

| `implement/scripts/check-mode.ts` | Print dashboard mode ("dev"/"production") via `GET /api/health`. → see `implement/scripts/check-mode.ts.AGENTS.md` |

| `implement/scripts/full-rebuild.ts` | Deploy checked-out dev version to local running instance. → see `implement/scripts/full-rebuild.ts.AGENTS.md` |

| `implement/scripts/parse-findings.ts` | Pure parsing helpers for CodeRabbit `--agent` NDJSON. Exports `parseFindings(stdout)` → `Finding[]` (filters… → see `implement/scripts/parse-findings.ts.AGENTS.md` |

| `implement/scripts/restart-server.ts` | Restart server via `POST /api/restart`. Flags: none (keep mode), `--dev` (body `{"dev":true}`), `--prod`… → see `implement/scripts/restart-server.ts.AGENTS.md` |

| `implement/scripts/review-changes.ts` | Implementation-phase advisory CodeRabbit review gate. Default `-t uncommitted`; passthrough passthrough flags… → see `implement/scripts/review-changes.ts.AGENTS.md` |

| `implement/SKILL.md` | Skill: disciplined implementation. Pairs code-discipline rules (TDD, simplicity, surgical) with 3-component… → see `implement/SKILL.md.AGENTS.md` |

| `manage-flows/SKILL.md` | Stub: only `disable-model-invocation: true` frontmatter; body moved to `edit-flow/SKILL.md`. → see `manage-flows/SKILL.md.AGENTS.md` |

| `nano-banana-imagegen/references/` | Prompting guide, example prompts |

| `nano-banana-imagegen/references/headers-and-heroes.md` | Prompt library for header/hero images. Categories: blog/article headers (tech blog, business case study,… → see `nano-banana-imagegen/references/headers-and-heroes.md.AGENTS.md` |

| `nano-banana-imagegen/references/icons-and-logos.md` | Prompt library for icons + logos. Categories: app icons (meditation, fitness, notes, weather —… → see `nano-banana-imagegen/references/icons-and-logos.md.AGENTS.md` |

| `nano-banana-imagegen/references/illustrations.md` | Prompt library for illustrations. Categories: editorial (concept, explainer), character (mascot, professional… → see `nano-banana-imagegen/references/illustrations.md.AGENTS.md` |

| `nano-banana-imagegen/references/photography-and-editing.md` | Prompt library: photorealistic generation (product, food, portrait, landscape, architecture) + `npx… → see `nano-banana-imagegen/references/photography-and-editing.md.AGENTS.md` |

| `nano-banana-imagegen/references/prompting-guide.md` | Prompting guide for Gemini image gen. Layered structure… → see `nano-banana-imagegen/references/prompting-guide.md.AGENTS.md` |

| `nano-banana-imagegen/SKILL.md` | Skill: AI image generation/editing via Google Gemini (nano-banana CLI) |

- | `openspec-apply-change/SKILL.md` | Implement tasks from OpenSpec change. `openspec instructions apply` → contextFiles + progress; loop until done/blocked. Pause on ambiguity/errors, don't guess; checkbox per task; done → suggest archive. |

- | `openspec-archive-change/SKILL.md` | Archive completed change. Never auto-select — AskUserQuestion always. Warn + confirm on incomplete artifacts/tasks. Assess delta-spec sync, offer sync via openspec-sync-specs. `mv` changeRoot → `archive/YYYY-MM-DD-<name>`. |

- | `openspec-continue-change/SKILL.md` | Create next artifact — ONE per invocation. `openspec status` → first `ready` artifact; `openspec instructions <artifact-id>` → template/context/rules. Read dependencies first; no skip/out-of-order; context/rules never copied into file. |

- | `openspec-explore/SKILL.md` | Explore mode — thinking partner, NOT implementer. No fixed workflow; curious, visual, grounded in codebase. NEVER write code/features; MAY create proposal/design/spec artifacts to capture thinking. Offer capture, don't auto-capture. |

- | `openspec-ff-change/SKILL.md` | Fast-forward artifact creation: ALL apply-required artifacts in one pass. `openspec new change <name>` then loop `ready` artifacts via `openspec instructions` until `applyRequires` done. Ask only if critically unclear; verify each file written. |

- | `openspec-new-change/SKILL.md` | Start new change: ask what to build if unclear, derive kebab-case name. `openspec new change "<name>"`, default schema unless `--schema` requested. Show first-artifact template then STOP — no artifact creation, wait for user. |

| `openspec-shared/scripts/effective-status.sh` | Bash wrapper around `openspec status --change <name> --json`; applies same R1/R2/R3 promotion as dashboard so… → see `openspec-shared/scripts/effective-status.sh.AGENTS.md` |

- | `openspec-sync-specs/SKILL.md` | Sync delta specs → main specs, agent-driven. Apply ADDED/MODIFIED/REMOVED/RENAMED sections from delta spec to `openspec/specs/<capability>/spec.md`; intelligent partial merge — preserve untouched content. Idempotent. No auto-select change. |

- | `openspec-verify-change/SKILL.md` | Verify implementation vs artifacts pre-archive: Completeness (tasks/req coverage), Correctness (req/scenario mapping), Coherence (design adherence). Issues graded CRITICAL/WARNING/SUGGESTION with file:line fixes; graceful degradation on missing artifacts. |

| `plan-proposal/SKILL.md` | Develop-side planning orchestrator. Chains artifact-gen (openspec-new/-ff/-continue) → doubt-driven-review on proposal.md/design.md (ARTIFACT+CONTRACT only, cross-model offer) → scenario-design → category-routed fold of `automated` manifest scenarios into vanilla `tasks.md` checkboxes (harness-exemplar pointer + Triple; no custom token). Main-session-only (refuses subagent: nested reviewer + ask_user gate). Stops at worktree boundary; hands to ship-it. See change: add-openspec-pipeline-orchestrators. |

| `release-cut/SKILL.md` | Cuts new release: promotes `## [Unreleased]` in CHANGELOG → dated section, bumps every workspace… → see `release-cut/SKILL.md.AGENTS.md` |

| `release-revoke/SKILL.md` | `release-revoke` skill. Reverts a release: deletes GitHub Release, removes git tag (local + origin), `npm… → see `release-revoke/SKILL.md.AGENTS.md` |

| `run-dashboard-e2e-local-changes/SKILL.md` | Skill. Run Playwright E2E vs `docker/` harness reflecting LOCAL changes. `docker compose -f docker/compose.yml build` FIRST (test-up.sh omits `--build`). Seed env `PI_E2E_SEED=1`. |

| `ship-change/SKILL.md` | End-to-end "land it" pipeline after openspec-apply. Base branch `develop`, worktree `.worktrees/os-<change>`… Step 1 defer rule now manifest-aware: `test-plan.md` present → defer only `manual-only` rows (via `deferDecision` in ship-it/scripts/manifest.ts); absent → legacy keyword defer verbatim. Step 10 teardown-before-worktree-removal ordering contract with ship-it. Step 10.5 opt-in (`RUN_FAQ_MINE=1`) non-blocking FAQ harvest: runs `faq-mine --docs skip --memory failures` on parent `develop` after merge, docs-only commit separate from feature PR. → see `ship-change/SKILL.md.AGENTS.md`. See change: add-openspec-pipeline-orchestrators |

| `ship-it/scripts/manifest.ts` | Pure ship-it/ship-change manifest helpers (unit-tested). `parseManifest(text)` → `{id,level,disposition}[]` from test-plan.md tables (tolerant of malformed/no-disposition). `classifyTaskDisposition(task,map)`. `deferDecision(tasks,manifestText\|null)` → defer/stop (manifest: only manual-only defers; no manifest: legacy keyword). `filesystemRealityCheck(scenarios,exists)` → automated satisfied only if test file exists. See change: add-openspec-pipeline-orchestrators. |

| `ship-it/scripts/no-weakening.ts` | Pure `assertNoWeakening(diff)` → `{ok,reasons}`. Parses unified test-file diff; rejects added `.only`/skip, net assertion deletion (expect() removed>added), strong→permissive matcher swap; allows genuine value-change fix. Enforced each ship-it red-test fix cycle. See change: add-openspec-pipeline-orchestrators. |

| `ship-it/SKILL.md` | Worktree-side implementation orchestrator (headless-capable). Idempotent: gates `automated` scenarios on filesystem-reality (test file exists + harness-green), not the tasks.md checkbox. Owns red-test fix loop (never re-invokes apply on checked task; progress-bound; no-weakening guardrail via scripts/no-weakening.ts). Harness via docker/test-up.sh, port from `.pi-test-harness.json` `dashboardPort` (never `:18000`), trap always-teardown. Step 4.4 deterministic enforcers (`check-conventions.mjs --base origin/develop`, `dox-byte-gate.mjs`, `i18n-lint --strict`, `i18n-parity`) run before any model call; failure routes to the fix loop and 4.5 does not run. Step 4.5 local review checkpoint: unconditional (no triviality escape), `@review` REQUIRED and spawned as an isolated `Agent` subagent (never inline self-review, never CodeRabbit CLI), fed `git diff origin/develop...HEAD` + proposal + task text, bounded by `REVIEW_TIMEOUT_MS` and a hard 2-round cap via scripts/review-gate.ts. Drives ship-change inline, manifest-aware defer, teardown before worktree removal. Escape hatch → SHIP_IT_BLOCKED.md, exit non-zero. See change: add-openspec-pipeline-orchestrators, wire-local-review-gate. |

| `ship-it/scripts/review-gate.ts` | Pure step-4.5 review decisions (unit-tested); skill owns the I/O. `REVIEW_TIMEOUT_MS=300_000`, `MAX_REVIEW_ROUNDS=2`. `resolveReviewer({roles,interactive})` → `@review` REQUIRED, never falls back to the session default (that model is the author ⇒ self-review); unconfigured = hard fail naming `update_roles`, `prompt:true` only when interactive (not persisted — accepting it removes the hard fail). `classifyFindings` → only `issue(blocking)` blocks. `reviewRoundDecision({round,blockingFindings,timedOut,unsatisfiable})` → `review\|proceed\|escape`; HARD 2-round cap, not step 4's no-progress bound (a model emits a fresh finding each round, so every cycle looks like progress); timeout and unsatisfiable escape regardless of round; every escape carries a `reason` for SHIP_IT_BLOCKED.md. See change: wire-local-review-gate. |

| `ship-it/vitest.config.ts` | Vitest project for the skill's decision helpers (`ship-it/scripts/__tests__/**/*.test.ts`, node, forks). Registered in root `vitest.config.ts`. Before it, nothing under `.pi/skills/` was collected by any project, so `manifest.ts` and `no-weakening.ts` shipped untested despite gating real ship decisions. See change: wire-local-review-gate. |

| `switch-extension-source/scripts/switch-source.ts` | Toggle script. Commands: status \| local <pkg> [--overlay] \| npm <pkg>. <pkg> = monorepo dir or npm name. → see `switch-extension-source/scripts/switch-source.ts.AGENTS.md` |

| `switch-extension-source/SKILL.md` | Skill. Switch monorepo extension/skill package between published npm source and local working-tree source. → see `switch-extension-source/SKILL.md.AGENTS.md` |

| `theme-system/SKILL.md` | CSS custom properties theme architecture for 4 themes (studio default, earth, athlete, gradient) switched via… → see `theme-system/SKILL.md.AGENTS.md` |