git:20260829.2825840 to git:20260831.ff0698b

# DOX — docs

Files in this directory. One row per file. Topic docs + repo-root config (root config files have no directory owner; catalogued here). Supersedes deleted `docs/file-index*.md` splits. See change: migrate-file-index-to-agents-tree.

| File | Purpose |

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

| `CONTRIBUTING.md` | (repo root) Human-facing contribution guide. Spec-first 5-phase pipeline (EXPLORE→PLAN→BUILD→SHIP→CI). 6 Mermaid diagrams + PNGs, cross-ref docs/pipeline-map/. |

| `architecture-notes/worker-offload-roadmap.md` | Worker offload roadmap. Main-loop CPU + sync-fs work → worker_threads. → see `architecture-notes/worker-offload-roadmap.md.AGENTS.md` |

| `biome.json` | (repo root) Biome 2.5.1 config. formatter off. vcs defaultBranch develop. → see `biome.json.AGENTS.md` |

| `chat-display-preferences.md` | `DisplayPrefs` gate chat chrome (thinking, tool cards, results, separators, stats bars). → see `chat-display-preferences.md.AGENTS.md` |

| `code-quality.md` | Biome ratchet. Rules graduate one-way off→warn→error; cleanup lands first, severity flip second. → see `code-quality.md.AGENTS.md` |

| `context-mode-roi-report.md` | ROI analysis. context-mode MCP plugin vs kb extension. Verdict: trim not drop. → see `context-mode-roi-report.md.AGENTS.md` |

| `context-mode-roi-report.pdf` | Rendered PDF of context-mode-roi-report.md. 13 pages. Built via document-converter facade (DOCX) + LibreOffice (DOCX→PDF). |

| `doctor-skill.md` | Modular doctor diagnostic skill. Router + 7 capability modules + _lib. → see `doctor-skill.md.AGENTS.md` |

| `electron-bootstrap-flow.md` | Electron startup state machine. `app.whenReady()` → dashboard window. → see `electron-bootstrap-flow.md.AGENTS.md` |

| `electron-build-methods.md` | 3 Electron build paths: local native (`npm run electron:build`), Docker cross-compile (--windows/--linux), CI publish.yml (tag push). Per-platform artifact/signing/node-pty matrix. |

| `electron-immutable-bundle.md` | Invariant: Electron bundle read-only at runtime. No post-install `npm install`. pi/openspec/tsx ship as deps under `<resourcesPath>/server/node_modules/`. electron-updater whole-app replacement. |

| `electron-session.md` | Implementation session log. 21 phases. Branding/icons, packaging (NSIS/AppImage), `__dirname`/tsx saga, dead… → see `electron-session.md.AGENTS.md` |

| `embedding-chat-view.md` | Subpath export `@blackbelt-technology/pi-dashboard-web/chat-embed` mounts live chat in sibling workspace. → see `embedding-chat-view.md.AGENTS.md` |

| `examples/c4-example.md` | C4-model diagram example. Mermaid fenced blocks: `C4Context`, `C4Container`. → see `examples/c4-example.md.AGENTS.md` |

| `faq.md` | Recurring how-to + troubleshooting questions. Caveman style. Cross-refs README.md + docs/. Auto-naming entry: starved vs waiting, budget, stop persistence. See change: fix-auto-naming-reasoning-model. → see `faq.md.AGENTS.md` Gains “Why do the OpenSpec buttons do nothing?” → per-state fixes. See change: add-openspec-init-affordances. |

| `grammar-checker.md` | User + dev feature doc. LLM grammar + spelling + style check for composer + OpenSpec Explore/New Change dialogs. Opt-in (default OFF). Config namespace `plugins.grammar.*`; enable + pick model in Settings → Plugins. Suggestion kinds: spelling, grammar, punctuation, style. Correction views: redline (default, with mode toggle) + list. API: /api/grammar/health (client config), /api/grammar/check (POST, error codes 409/400/502/504). Client: `useGrammarCheck` debounces keystroke + auto-check (skips streaming/min-chars/commands). Server: LLM backend via model runtime; provider creds server-side; offset-safe apply (keyed by text span). Prompt injection guard + robustness fallback. Plugin-contained `packages/grammar-plugin/`. Mounts in composer + OpenSpec dialogs via `ComposerPanelSlot`. Links docs/grammar-model-guidance.md for model benchmarks (recommended: openai/gpt-4.1-nano). Known: opt-in, ~2s latency floor, code-fence quirk on weak models. |

| `grammar-model-guidance.md` | Recommended LLM models for composer grammar check + latency/quality/cost tradeoffs. OpenRouter competition finals. LLM-only backend (LanguageTool removed). Model picked in Settings → Plugins → "Grammar & Spelling". Weak/reasoning models identified + avoided. Linked from GrammarSettings. See change: grammar-llm-only-with-explore, align-grammar-settings-design. |

| `install-invoice-bot-extension.md` | Install `@blackbelt-technology/invoicebot` (local `../pi-invoice-bot`) as global pi extension. → see `install-invoice-bot-extension.md.AGENTS.md` |

| `installation-windows.md` | Windows 10/11 install guide. 2 paths: Electron Setup.exe NSIS (per-user, bundled Node) + tarball/npm (advanced). Runtime layout `%USERPROFILE%\.pi-dashboard\` + `%USERPROFILE%\.pi\`. |

| `kb-read-discipline.md` | Trust verdicts on `kb_search` agents hits (FRESH/STALE/MOVED/GONE/UNVERIFIED, cap 8, ack sidecar v2) + search guard arm B (fire 3, off/warn/block, KB_GUARD_MODE, kb_guard_pause). Code: verdict.ts, guard.ts. |

| `knip-baseline.json` | (repo root) Knip dead-code baseline. Per-class debt counts, measured 2026-08-13. Debt ceiling, not target. → see `knip-baseline.json.AGENTS.md` |

| `knip.json` | (repo root) Knip 6.32.2 whole-graph dead-code config. 38 workspaces. → see `knip.json.AGENTS.md` |

| `migration/from-pi-model-proxy.md` | Migration guide `@blackbelt-technology/pi-model-proxy` → dashboard built-in proxy. → see `migration/from-pi-model-proxy.md.AGENTS.md` |

| `migration/slot-pill-actions-to-folder-menu.md` | Plugin-author migration guide. `SlotPill.actions?: ReactNode` removed; replace with `useFolderMenuItem` + `useFolderMenuRefresher`. See change: move-slot-actions-to-menu. → see `migration/slot-pill-actions-to-folder-menu.md.AGENTS.md` |

| `perf-ws-broadcast-load.md` | WS broadcast load harness. Measures head-of-line blocking on single browser WS. `createDrainingWs` timing-aware fake socket drives real gateway. Test-only, regression-gated. |

| `plan/electron-app.md` | Comprehensive Electron desktop-app plan. Bundle dashboard standalone macOS/Linux/Windows, zero prereqs,… → see `plan/electron-app.md.AGENTS.md` |

| `playwright.config.ts` | (repo root) Playwright config. testDir `tests/e2e`, `use.baseURL` imports `BASE_URL` from lifecycle.ts,… → see `playwright.config.ts.AGENTS.md` |

| `playwright.electron.config.ts` | (repo root) Playwright config for Electron-E2E suite. testDir `tests/e2e-electron`, testMatch… → see `playwright.electron.config.ts.AGENTS.md` |

| `plugin-claim-gates.md` | `predicate` vs `shouldRender` contract for plugin claims. See change: auto-hide-empty-session-subcards. |

| `plugin-intent-protocol.md` | Server-driven plugin UI. Plugins emit JSON intent trees; clients render via local primitive registry. → see `plugin-intent-protocol.md.AGENTS.md` |

| `plugin-ui-primitives.md` | Plugins access dashboard React primitives via runtime registry. `useUiPrimitive(key)` lookup. Keys `UI_PRIMITIVE_KEYS`. Shell → plugin flow, complements slot system. Documents `ui:thinking-level-selector`. Documents `UiModelSelectorProps.placeholder?`. Documents shell-bound wrapper registrations (`lib/plugins/shell-primitives.tsx`). See change: upgrade-model-selector-primitives. |

| `pnpm-workspace.yaml` | (repo root) pnpm workspace + config source of truth (package.json `pnpm.*` ignored when this exists). → see `pnpm-workspace.yaml.AGENTS.md` |

| `publishing-plugins.md` | Publish new plugin package to npm. Lockstep versioning (`sync-versions.js`). First publish seeds 0.0.1 via one-shot manual publish + revert; OIDC Trusted Publisher after. |

| `release-process.md` | Cut release how-to. Promote CHANGELOG `[Unreleased]` → versioned, bump + tag; CI publishes npm + Electron + GitHub Release. Conventional Commits enforced by review only. |

| `research/auto-trigger-plan-proposal.md` | Research dossier. Auto-trigger `plan-proposal` on `proposal.md` draft. Explore-mode, no change / no impl. → see `research/auto-trigger-plan-proposal.md.AGENTS.md` |

| `research/bridge-transport-and-identity.md` | Research dossier. Explore-mode, no change / no impl. P2P vs WebSocket for bridge↔server. Verdict: pain = name→endpoint indirection + absent peer identity, not transport; fix = HOME-derived rendezvous + platform transport (UDS POSIX / TCP+token Windows) + paired-device remote. → see `research/bridge-transport-and-identity.md.AGENTS.md` |

| `research/browser-provider-registry.md` | Research artifact. Explore-mode, no change / no impl. Verdict: named-browsers registry, NOT Chrome extension; extension tiers = provider rows. Notifications premise refuted — Web Push already designed (`isUnreadTrigger` @ `event-status-extraction.ts:201`); only extension seam = air-gapped WS notifier. Panerelay live-broken on host (`GLOBAL_DEFAULT=yes`, `READY=no`, 3 stale `BROWSER_ID`s, 0 chrome procs), NOT CDP, false success. Multi-profile = identity gap not capability; 3 real profiles ↔ 3 IDs. `debugger` CANNOT be `optional_permissions` (kills runtime T1→T2). No-native-host: long-lived server → plain WS to `ws://localhost:8000`. Registry grep in shared+server = EMPTY (never built); build first vs bundled agent-browser + Panerelay, zero extension code; T1/T2 independent, recommend TWO extensions. Fork whole browser EVALUATED, REJECTED: fork buys distribution-as-browser not capability; ChatGPT Atlas (OpenAI, macOS-only Chromium) died `2026-08-09` after ~10 months, Win/iOS/Android never shipped; Electron pinned `32.3.3` → Chromium 128, 533 days behind `electron@43.4.1` → Chromium 150, E32 EOL no backports (#529); `brave-core` = patch set not Chromium copy (permanent rebase); own browser in embryo — CDP on `9222` (`--debug-cdp`, `resolve-cdp-activation.ts`, `main.ts:31`), `WebContentsView` tab + `session.fromPartition()` = named multi-profile free; fork does NOT buy logged-in sessions; upgrade surface small (no `remote`, no native runtime deps). §13 hard rule quoted verbatim. 8 open spikes (debugger.attach vs host permissions UNVERIFIED). → see `research/browser-provider-registry.md.AGENTS.md` |

| `research/context-injection-ab-test.md` | A/B non-inferiority experiment: pi context injections. Harness `scripts/ab-context/`. → see `research/context-injection-ab-test.md.AGENTS.md` |

| `research/grammar-backend-architecture.md` | Architecture decision record. Composer "writing" backend: LanguageTool (Java, ~25 ms, offline, deterministic, i18n en/hu, XML/Java custom rules, n-gram data) vs LLM (haiku, ~2–4 s) vs hybrid. Status: OPEN — undecided. → see `research/grammar-backend-architecture.md.AGENTS.md` |

| `research/headroom-pi-integration.md` | Research dossier. Maps Headroom (local context-compression layer, shrinks tool outputs/logs/RAG before LLM,… → see `research/headroom-pi-integration.md.AGENTS.md` |

| `research/hermes-memory-pressure-kb-archive.md` | Research dossier. Decrease pi-hermes-memory pressure + keep most-relevant entries via a kb-indexed cold… → see `research/hermes-memory-pressure-kb-archive.md.AGENTS.md` |

| `research/kb-search-retrieval-quality-investigation.md` | Research dossier. Diagnose `kb_search` "sometimes similar, but unrelevant records" — feeds openspec… → see `research/kb-search-retrieval-quality-investigation.md.AGENTS.md` |

| `research/lora-dataset-from-pi-logs.md` | Research doc. Turns repo pi session JSONL logs into SFT dataset for LoRA adaptation of ~1T-param base model;… → see `research/lora-dataset-from-pi-logs.md.AGENTS.md` |

| `research/mobile-app-bubblewrap-vs-capacitor.md` | Research artifact. Explore-mode, no change / no impl. Ship pi-dashboard as mobile app: Google **Bubblewrap**… → see `research/mobile-app-bubblewrap-vs-capacitor.md.AGENTS.md` |

| `research/neutral-shell-deploy-and-pairing-durability.md` | Research artifact. Explore-mode, no change / no impl. Test shell at pi-dashboard.dev/app/: no release needed — site deploy independent of npm/Electron; stale `site/package-lock.json` blocks `Deploy Site`. Secure-context rule by design (D4); keyring `urls[]` go stale → misleading identity error; tailscale serve header check measured, no loopback bypass; stable https via reserved zrok name or tailnet HTTPS + MagicDNS `publicBaseUrls`. → see `research/neutral-shell-deploy-and-pairing-durability.md.AGENTS.md` |

| `research/omp-agent-parallel-support.md` | Research dossier. Explore-mode, no change / no impl. Parallel pi+omp agents, per-session selectable, both visible. VERDICT: CONDITIONAL GO — spikes 1+2 EXECUTED 2026-08-29; loader + core API GREEN verified live. Spike 2 IMPROVED risk: storage claim CORRECTED — sessions JSONL pi-identical layout (`<sessions>/<mangled-cwd>/<ISO>_<id>.jsonl`; id 16-hex vs UUID), SQLite scope = settings/auth/models/history ONLY; version skew REFUTED (dist/src in sync 18.0.11, `omp --version` `13.14.2` display quirk = `config.yml` `lastChangelogVersion`); RPC RESOLVED (omp 42-case set vs pi `RpcCommand` 36; keeper dispatches `prompt` only → XS); runtime-undefined members CONFIRMED unconditional both modes (in bundle, NOT exposed on ExtensionAPI; workaround `set_session_name` RPC command). NEW FINDING H: omp honors `PI_CONFIG_DIR` (injected by dashboard) → cross-flavor env contamination; per-flavor env scrub REQUIRED = gap #7 S–M + residual risk. Last red: session RECORD schema (needs ONE authenticated turn). Fork NOT reusable — blind sed rebrand, 2 ahead / 1193 behind, DELETES pi support. omp = `@oh-my-pi/pi-coding-agent` Bun-runtime (`bin omp`), env `PI_*` retained + `OMP_*` added, home `~/.omp/agent`. Bridge runtime-agnostic (9/9 type-only); loader accepts `export default function activate(pi)` via `omp -e` raw TS. `getSessionName`/`setSessionName`/`unregisterProvider` DECLARED in types, UNDEFINED runtime → 22 call sites need shims (3 unguarded: `session-sync.ts:160/230`, `bridge.ts:2012`); `.d.ts` NOT oracle. `pi.on` permissive 19/19; lifecycle ×3 identical through `agent_end`, `agent_settled` absent → synthesis VIABLE (trap `18.0.11`→native WRONG, fix = flavor-derived). MCP hang: `omp --print` rc=124, 0 bytes, `OMP_MCP_TIMEOUT_MS` ignored; clean `HOME=/tmp/omp-home` works; preflight MUST bound startup. Credentials do NOT carry over; `--session-dir` overridable. Gaps: 147 stray `.pi/*` literals (L, dominant), session RECORD schema (last red), bin+bun resolution + BUN PREFLIGHT (M), env isolation NEW (#7 S–M). Options: B `AgentFlavor` descriptor RECOMMENDED, A fork REJECTED, C SPI DEFERRED. → see `research/omp-agent-parallel-support.md.AGENTS.md` |

| `research/oh-my-pi-feature-adaptation.md` | Research artifact. omp (oh-my-pi, pi-mono fork) → pi-dashboard feature adaptation. → see `research/oh-my-pi-feature-adaptation.md.AGENTS.md` |

| `research/reverse-spec-from-code-session.md` | Method playbook. HOW `reverse-spec-from-code` skill + 102-spec backfill built in one pi session. → see `research/reverse-spec-from-code-session.md.AGENTS.md` |

| `research/reverse-spec-from-code.md` | Research artifact. `reverse-spec-from-code` skill prompt tuning + generator-model-loss experiment. → see `research/reverse-spec-from-code.md.AGENTS.md` |

| `research/session-derived-taste-learning.md` | Research dossier. Taste-learning vs CommandCode. Verdict: DO NOT BUILD. → see `research/session-derived-taste-learning.md.AGENTS.md` |

| `research/session-guideline-fast-vs-research-ab.md` | A/B test — @fast vs @research model for SessionGuideline subagent. N=1 input session 019f8680. → see `research/session-guideline-fast-vs-research-ab.md.AGENTS.md` |

| `research/site-3d-background-field.md` | Research record. Ribbon candidate vs fleet. Extruded ribbons read 3D; lean+Z-stagger sells depth; shared scene, no stacked canvases; opacity capped 0.58/0.42. A11y trap + session-hazard lessons. |

| `research/sub1b-stt-diarization-benchmark.md` | Sub-1B open-source STT+diarization benchmark. 4 engines: MOSS-Transcribe-Diarize 0.9B Q5_K GGUF ~1x RT local… → see `research/sub1b-stt-diarization-benchmark.md.AGENTS.md` |

| `research/test-suite-performance.md` | Research dossier. WHY `npm test` takes 12 min: 728.81s wall / 1456 files, 3547 worker-s ÷ 8 workers (`maxWorkers: "50%"`) → ~443s floor = too much work + poor packing. 4 bottlenecks: mutation-harness 238.0s critical path (33% wall); 50% cores idle (client threads+100% = 124.2s vs 178.0s); jsdom env 743.98s vs 169.25s tests; `maxWorkers: 1` projects serial AFTER pool. Levers A–G, A+B+D → ~3–4 min. RESEARCH ONLY. → see `research/test-suite-performance.md.AGENTS.md` |

| `research/t3code-feature-adaptation.md` | Research artifact. t3code (multi-provider web GUI wrapping Codex/Claude/Cursor/OpenCode) → pi-dashboard… → see `research/t3code-feature-adaptation.md.AGENTS.md` |

| `research/understand-anything-integration.md` | Research dossier. Adapt Egonex-AI/Understand-Anything (MIT; turns any codebase/docs into interactive… → see `research/understand-anything-integration.md.AGENTS.md` |

| `research/user-browser-in-editor-view.md` | Explore-mode research record. `user_browser` tool: agent drives browser, page renders in dashboard editor… → see `research/user-browser-in-editor-view.md.AGENTS.md` |

| `service-bootstrap.md` | 3 starters (Electron/Bridge/Standalone) × 2 surfaces (GUI/shell). Tool resolution (pi, openspec, node, tsx, bridge). `DASHBOARD_STARTER` env, `launchSource` on `/api/health`. |

| `skills-as-subagents.md` | Skill↔subagent bridge analysis. Wrap skill via thin `.pi/agents/<Name>.md` (model role, `inherit_context`,… → see `skills-as-subagents.md.AGENTS.md` |

| `slash-command.md` | Bridge routes typed `/foo` chat text to pi handlers. `parseSendPrompt` + `bridge.ts::sessionPrompt` 11-step order. Extension command dispatch fix (`pi.dispatchCommand`, RPC keeper). |

| `ui-contract.md` | (repo root) Cross-screen design control plane. Single source of truth for visual consistency. References design tokens only, never redefines, forbids raw hex/px. Token authority `packages/client/src/index.css`. Two themes ship: `:root` (dark, default) + `[data-theme="light"]` (32-token override). Theme-system skill "4 themes" claim stale — no such selectors. Prefer `--severity-{error,warning,success,info,neutral}-{bg,fg,border}`, `--status-*`, `--warn-*`; new surfaces use severity, not raw `--accent-*`. Carries spacing scale, type scale (floor: below `text-[11px]` non-essential), radius, elevation (`--elevation-rim` inset signature), component invariants, motion, WCAG 2.2 AA invariants. Debt, do-not-copy: `SessionCard.tsx` off-token `border-blue-500/30`; `BranchSwitchDialog.tsx` missing `role`/`aria-modal`/labelled title. Created by frontend-mockup-loop skill CONTRACT step. See change: share-session-archives. |

| `vitest.config.ts` | (repo root) Root Vitest config. `defineConfig`. Vitest 4 dropped `vitest.workspace.ts`. Projects live under `test.projects`. New `tests` project. Points at `tests/vitest.config.ts`. Collects `tests/e2e/helpers/__tests__/` only. Playwright specs excluded. Need docker harness + browser. Run via `npm run test:e2e`. Added for pure helper. Used only by opt-in specs (`PI_SYNTH_AGENT_TICKS=1`). No CI job executed it. See issue #549. → see `vitest.config.ts.AGENTS.md` |