AGENTS.md@docs git:20260928.8d19223A

Immutable. This exact content never changes and is served at /api/v1/blob/9edcccc3cc402f0e.

# 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` |
| `architecture.md` | Full architecture reference. 3 components: bridge extension, Node server, React client. → see `architecture.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` |
| `chat-gateway.agent.md` | Pull-only condensed map/companion for `chat-gateway.md`. Setup, boundaries, team controls, config keys. → see `chat-gateway.md` |
| `chat-gateway.md` | Operator setup guide for `@blackbelt-technology/pi-dashboard-chat-gateway-plugin`. → see `chat-gateway.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/. → see `faq.md.AGENTS.md` |
| `features.md` | Full feature catalog. 562 capabilities. Derived from README.md + openspec/specs/. Categorized by surface. Source for end-user subset → docs/user-features.md. |
| `heap-limits.md` | V8 heap reference. Config keys `sessionHeap` (`maxOldSpaceMb` 512, `initialOldSpaceMb`, `maxSemiSpaceMb`) +… → see `heap-limits.md.AGENTS.md` |
| `grammar-checker.md` | User + dev feature doc. LLM grammar + spelling + style check for composer + OpenSpec Explore/New Change… → see `grammar-checker.md.AGENTS.md` |
| `grammar-model-guidance.md` | Recommended LLM models for composer grammar check + latency/quality/cost tradeoffs. → see `grammar-model-guidance.md.AGENTS.md` |
| `gmail-plugin.md` | Map Gmail setup, sign-in, leases, levels, tools, routes, storage, tests, security. See change: add-gmail-plugin. |
| `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… → see `kb-read-discipline.md.AGENTS.md` |
| `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/slot-pill-actions-to-folder-menu.md` | Plugin-author migration guide. `SlotPill.actions?: ReactNode` removed; replace with `useFolderMenuItem` +… → 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; slot-claims invalidation store. See change: auto-hide-empty-session-subcards, add-blackhole-session-pipeline. |
| `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-seams.md` | Plugin authoring guide. 3 seams: `ctx.credentials` store (`~/.pi/agent/plugin-credentials.json` 0600, namespace=manifest id, caps 64 KiB/256 keys/2 MiB); `ctx.oauth.startFlow({key,loginFlow,persist})` served by `/api/provider-auth/flow/:flowId` + `createLoopbackCallback`; bridge→server request lane (`requestPluginServer`/`registerPiRequestHandler`, 256 KiB, 15 s). Trust boundary + fixture gate (`PI_DASHBOARD_FIXTURE_PLUGINS=1`). See change: expose-plugin-credential-and-oauth-seams. |
| `plugin-ui-primitives.md` | Plugins access dashboard React primitives via runtime registry. `useUiPrimitive(key)` lookup. → see `plugin-ui-primitives.md.AGENTS.md` |
| `pnpm-workspace.yaml` | (repo root) pnpm workspace + config source of truth (package.json `pnpm.*` ignored when this exists). → see `pnpm-workspace.yaml.AGENTS.md` |
| `vendored-relay-refresh.md` | Operator page for the vendored Playwright relay: per-file provenance kinds, the non-reorderable fetch →… → see `vendored-relay-refresh.md.AGENTS.md` |
| `vitest.workers.ts` | (repo root) Single source of truth for the vitest parallel worker target: exports `PARALLEL_MAX_WORKERS =… → see `vitest.workers.ts.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/agent0-self-evolving-loop-adaptation.md` | Research artifact. Explore-mode, no change / no impl. Agent0 (arXiv 2511.16043) → pi-dashboard. → see `research/agent0-self-evolving-loop-adaptation.md.AGENTS.md` |
| `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. → see `research/bridge-transport-and-identity.md.AGENTS.md` |
| `research/browser-probe-and-ship-traps.md` | Research dossier. Method half of 2026-08-26/27 marketing-site session: headless-browser probes verify… → see `research/browser-probe-and-ship-traps.md.AGENTS.md` |
| `research/browser-provider-registry.md` | Research artifact. Explore-mode, no change / no impl. Verdict: named-browsers registry, NOT Chrome extension;… → see `research/browser-provider-registry.md.AGENTS.md` |
| `research/browser-relay-playwright-extension.md` | Research artifact. Explore-mode, no impl. Verdict: reuse MS Playwright Extension… → see `research/browser-relay-playwright-extension.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/gae-geometry-native-autoencoder-skill.md` | Research dossier + skill plan. TencentARC GAE (Geometry-Native Autoencoder, arXiv 2609.24981) → proposed `gae-world-gen` skill. Plan only, no impl. → see `research/gae-geometry-native-autoencoder-skill.md.AGENTS.md` |
| `research/grammar-backend-architecture.md` | Architecture decision record. Composer "writing" backend: LanguageTool (Java, ~25 ms, offline, deterministic,… → 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/marketing-site-static-rewrite.md` | Implementation record. `site/` dropped Astro 5 + Tailwind + Preact + MDX for one hand-written static page. → see `research/marketing-site-static-rewrite.md.AGENTS.md` |
| `research/ming-image-design-skill.md` | Research dossier. Local-runnable Ming image/design model → pi `ming-design` skill; web + slides consumers. → see `research/ming-image-design-skill.md.AGENTS.md` |
| `research/mira-scene-deck3d.md` | Research artifact. Explore-mode, no change / no impl. Mira-Scene (arXiv 2609.23796) single-image→3D scene for deck3d… → see `research/mira-scene-deck3d.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… → see `research/neutral-shell-deploy-and-pairing-durability.md.AGENTS.md` |
| `research/oci-cwd-delegation.md` | Research dossier. Explore-mode, no change / no impl. OCI image from CWD (crane/oras/umoci/buildah,… → see `research/oci-cwd-delegation.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… → 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/querymt-agent-backend.md` | Research dossier. Explore-mode, no change / no impl. Can query.mt (`qmtcode`) replace pi under dashboard?… → see `research/querymt-agent-backend.md.AGENTS.md` |
| `research/ovis-omni-embedding-kb-eval.md` | Research dossier. Local feasibility of `ATH-MaaS/Ovis-Omni-Embedding-3B` (omni embedding, not chat) + 3-question kb retrieval eval plan. → see `research/ovis-omni-embedding-kb-eval.md.AGENTS.md` |
| `research/qwen-audio-and-omni-models.md` | Research dossier. Qwen cloud audio/omni landscape + measured transcription test. → see `research/qwen-audio-and-omni-models.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… → 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/typesafe-system-one-decision-points.md` | Research dossier. Explore-mode, no change / no impl. TypeSafe `jev` (System One) `Choice`/`Score`/`Noul`… → see `research/typesafe-system-one-decision-points.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/unified-context-manager-exploration.md` | Research artifact. Explore-mode, no change / no impl. Status: exploration in progress; supersedes… → see `research/unified-context-manager-exploration.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` |
| `research/webgl-field-and-glass-bands.md` | Implementation record. pi-dashboard.dev visual system: `site/field.js` WebGL slab field + `site/index.html`… → see `research/webgl-field-and-glass-bands.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… → see `slash-command.md.AGENTS.md` |
| `system-one.md` | Shared decision registry. `@blackbelt-technology/pi-system-one` library (`predict` over `choice`/`score`/`noul`; config `~/.pi/agent/system-one.json`; `allowOffMachine` egress switch) + `@blackbelt-technology/pi-dashboard-system-one-plugin` (settings section "Decision models (System 1)", `/api/system-one/*`, managed Von/Laya). See change: add-system-one-registry. |
| `ui-contract.md` | (repo root) Cross-screen design control plane. Single source of truth for visual consistency. → see `ui-contract.md.AGENTS.md` |
| `untrusted-plugin-ui-gap.md` | Read-only gap analysis. Untrusted plugin UI via descriptor protocol (`extension-ui-system`) vs React path. 53% claims blocked (`react-only` slots). Rec: descriptors + sandboxed-iframe escape hatch. |
| `user-features.md` | End-user feature subset. Curated from docs/features.md. Communicable to end users. Excludes internal plumbing, CI/QA, packaging, refactors. |
| `vitest.config.ts` | (repo root) Root Vitest config. `defineConfig`. Vitest 4 dropped `vitest.workspace.ts`. → see `vitest.config.ts.AGENTS.md` |