AGENTS.md@docs git:20260924.dabf946A

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

# 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. Gains "Access-Grant Prompts and YOLO" — per-connection capability + `X-Pi-Grant-Channel`, host-gate `enforce` precondition, HELD/DEFERRED planes, registry flood controls, ancestor ladder, YOLO, env vars, REST. See change: add-access-grant-dialog. → 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`. Setup, boundaries, team controls, audit trail, config. See change: add-chat-gateway, add-chat-gateway-team-controls. → see `chat-gateway.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. Gains "Doctrine not injected / first-contact nudge keeps firing?" → extension-not-loaded, missing doctrine key, legacy `AGENTS.md`, malformed config, `write` flag. See change: inject-dox-doctrine-and-describe. Gains "How do I connect Claude Code / Cursor to the dashboard MCP?" → token mint, snippet, tunnel reachability, shell history warning, legacy vs streaming capability, shutdown DELETE 405. See change: mcp-legacy-clients-and-token-issuance. Gains "Why is a subagent or tool card stuck `running` after the session ended?" → orphan heal on `onEnded`, open-work derivation, synthesized `tool_execution_end` / `subagent_failed`, cold hydration parity. See change: heal-orphaned-tool-cards-on-session-end. Gains "Why does my session die whenever it spawns subagents?" → event loop stall root cause, admission control gate, `maxConcurrentSubagents` knob, saturation fallback to 1, terminal errored refusal card, scope boundary. See change: bound-subagent-fanout-under-host-pressure. Gains "Plugin pages 403 `network_not_allowed` after upgrade?" → auth-off tunnel + plugin/provider-auth API routes now guarded, app shell unaffected, remedy enable auth or add trusted network (Settings ▸ Servers). See change: add-universal-network-guard. |
| `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`) + `serverHeap` (`maxOldSpaceMb` 1536, replaced hardcoded 8192). Floor 64 MB; invalid → `loadConfig` default, never throws; no `0` sentinel. DISTINCT from `memoryLimits` (event store). Transport argv, not `NODE_OPTIONS` (allow-list rejects `--initial-old-space-size`; env leaks to every Node grandchild; tmux panes never see spawn env). Per-mechanism: headless/wt argv, tmux/wsl-tmux `-e NODE_OPTIONS`, last-resort fallback logged `[heap]` + `/api/health` `sessionHeapFallback`, forbidden on headless. Strip gated on `PI_DASHBOARD_HEAP_FLAG` marker. Effect boundary: session = next spawn (reload counts), server = cold start only. `heap_size_limit` carries ~192 MB V8 overhead. Telemetry fields + the two non-comparable percentage bases (84% vs crash point, ~69% vs `heapSizeLimit`). Subagent coupling formula `maxOldSpaceMb/(n+1)`. See change: bound-session-heap-and-gc-telemetry. |
| `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/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; 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-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` |
| `vendored-relay-refresh.md` | Operator page for the vendored Playwright relay: per-file provenance kinds, the non-reorderable fetch → verify-in-memory → copy → patch → rehash order, upstream-never-from-disk, Apache-2.0 §4(b)/§4(d), the three guards, never hand-edit `relay/vendor/`. See change: fix-browser-plugin-vendor-specifier-resolution. |
| `vitest.workers.ts` | (repo root) Single source of truth for the vitest parallel worker target: exports `PARALLEL_MAX_WORKERS = "50%"`. Imported by RELATIVE path from every parallel `vitest.config.ts` (27 at adoption) — no `package.json` dependency edge. Deliberately serial projects (7, `maxWorkers: 1`) do not import it. Guard: `scripts/__tests__/vitest-workers.test.mjs`. See change: make-test-suite-deterministic. |
| `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. Verdict: RL-on-weights NO; text-policy evolution loop YES — curriculum agent + `scripts/ab-context/` executor/judge + agent-proposed arms; `ab-test-plain-language-rule` = one manual iteration. → 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. 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-probe-and-ship-traps.md` | Research dossier. Method half of 2026-08-26/27 marketing-site session: headless-browser probes verify static-site visual/UI claims; ship traps cost time. → 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; 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/browser-relay-playwright-extension.md` | Research artifact. Explore-mode, no impl. Verdict: reuse MS Playwright Extension (`mmlmfjhmonkocbjadbfplnigmagldckm`) + own relay; `agent-browser connect` unchanged; zero new `browser_*` tools. → 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/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/marketing-site-static-rewrite.md` | Implementation record. `site/` dropped Astro 5 + Tailwind + Preact + MDX for one hand-written static page. Shipped 2026-08-27, live https://pi-dashboard.dev. → see `research/marketing-site-static-rewrite.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/oci-cwd-delegation.md` | Research dossier. Explore-mode, no change / no impl. OCI image from CWD (crane/oras/umoci/buildah, daemon-free) → remote "mount" = overlay (Linux) or extract+mtree (portable) → changes back as one layer with whiteouts. Verdict: layer-as-checkpoint fine, layer-as-build anti-pattern; 4-layer split L0 deps/L1 HEAD/L2 dirty/L3 ignored-wanted + lease model; fork checkpoint (OCI/kopia) vs live-sync (Mutagen). 5 open questions. → 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 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/qwen-audio-and-omni-models.md` | Research dossier. Qwen cloud audio/omni landscape + measured transcription test. Qwen3.8-Omni-Flash EXISTS (2026-09-18; "stops at 3.5" WRONG). Token Plan (`sk-sp-`) vs Model Studio PAYG (`sk-ws-`) = disjoint products, non-interchangeable keys, 14 vs 170 ids, omni only PAYG. pi input union `("text" or "image")[]` closed → no audio. MEASURED: `qwen3.8-omni-flash` 9.4x realtime, ~$0.019/hr, better prose than Soniox BUT silent truncation 210s/300s, normal `finish_reason`, −15% words. Verdict: ASR = timing spine, translate text only → drove `add-srt-translation-pass`, `pi-translate-srt`. 4 open questions. → 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 (`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/typesafe-system-one-decision-points.md` | Research dossier. Explore-mode, no change / no impl. TypeSafe `jev` (System One) `Choice`/`Score`/`Noul` calibrated decisions → pi-dashboard. Verdict: replace agent-prose snap judgments — skill/subagent selection (cookbook `skill_suggestion`), `autofix` safe-fix gate, `distill-hermes-memory-into-skills` route classifier (PILOT 1), supervised tool-approval risk score, flows `typesafe-decision` step. Web design: `runL4` + anti-slop source-observable Nouls ✓ (PILOT 2); L1/L2 deterministic; render-observable stays vision. Unknowns: pricing, residency, no image input. → 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 `openspec/changes/consolidate-retrieval-planes` (SUPERSEDED; umbrella `openspec/changes/unify-context-manager` drafted). Goal: ONE unified context-manager pi extension + ONE dashboard plugin replacing pi-hermes-memory + pi-blackhole + context-mode + kb-extension. Primary target = MODEL CONFUSION (3 session-search tools, 3 prompt injections), RAM/disk = bonus. Decisions: big-bang fork of hermes+blackhole (MIT); context-mode (Elastic-2.0) clean-room sandbox exec only, no code port; drop `ctx_fetch_and_index` → pi-web-access sole ingestion, manager taps `tool_result` → `web` scope; old tool names aliased 1 release + deactivated via `pi.setActiveTools`; keep 2 distillation pipelines; explicit agent-authored triggers. Inventory 2026-09-24: hermes 0.9.9 MIT ~17.0k LOC 186 MB store; blackhole 0.5.6 MIT ~32.7k LOC 2.7 MB; context-mode 1.0.169 Elastic-2.0 compiled, 16 MCP procs 616 MB RSS. Session JSONL re-read 4×, distillation 4 pipelines, 4 store formats; ~12k LOC droppable → fork ≈30k LOC. Memory files write-only (`MEMORY.md` 272 KB 263 entries not injected; 461 writes vs 66 reads). External: "Delivery, not storage" (arXiv 2607.20972), Proactive Memory Agent (2607.08716), Retrieval vs Utilization (2603.02473), Letta filesystem 74.0% LoCoMo. Delivery channels A–E from pi 0.87.1 types. Spike 1: compaction prerequisite MET (pi 0.87.0 `turn_end` boundary). Spike 2: trigger replay — naive median 117 fires/session, strict median 2 precision ~25–35%; df filter ~60× volume cut. Storage model RESOLVED (one-file-per-lesson md+frontmatter canonical, kb-indexed, node:sqlite stats). Retrospective lesson miner design (session-distiller → LLM stages, existing subagent cap). System-1 tier (Jev/Von/Laya, `POST /v1/systemone`, LLM fallback). Spike 3 bake-off identical-harness (LLM AUC 0.951, Von 0.425, Laya 0.616; neither pre-filters — recall≥0.9 keeps 45–50/50; Laya ~2.3× faster, 1-q ~55 ms runtime gate). §17 method studies — 50-window set, then rebuilt 78-window set (fault 32, correction 17, decision 14, routine 16; reference 25/78 lessons): decomposition lifts Von 0.43→0.71 zero-shot; structure+domain checkpoint lifts Laya 0.62→0.71; generic unanchored `score` worse than random (0.41–0.44) — anchored observable levels rescue it (Von 0.42→0.71) but never beat best noul per backend; Von one anchored score ≈50 ms ties 11 atomic nouls (0.707 vs 0.701, ≈470 ms) = ~9× cheaper; Laya-td best System-1 = abstract noul 0.785 (CI 0.67–0.88); LLM probability 0.945 ≥ anchored level 0.921, hard level cut loses ranking; LR aggregation still overfits n=78/25 positives; prefilter unchanged (best System-1 keeps 55–57/78 at recall 0.9 vs LLM 34/78; CIs wide); design D11 = atomic nouls over structured state, never one abstract judgement, `score` selectable per step with anchored observable levels mandatory, `noul` default. §18 labeling beyond window judgement — 8 sources (hindsight utility, contrastive, weak supervision, query/click-through, knowledge-type, sequence mining, proposition+graph, git/CI); spike 4 kb_search click-through 501 sessions/123 calls (grep_fallback 54% vs click 15%, ~60 labelled pairs) → kb eval fixtures + gap report; spike 1 hindsight replay: judged lesson-ness + recurrence = independent axes (kappa 0.01–0.05; recurrence count AUC 0.748 vs LLM 0.472); spike 3 weak supervision + System-1 as LF voters FAIL (no positive LF; label model 0.576 vs LLM 0.935); knowledge-type census episode 41%/none 32%/lesson 16%/fact 8%/rationale 3%/procedure 0; D10 knowledge_type routes destination, D6 click/miss labels feed kb eval; prior art `packages/kb/eval/mine-golden-sets.mjs` already mines those golden sets. §19 memory/KB beyond storage+triage — 9 areas: AGENTS.md eval 2602.11988 no general task-success gain +20%+ cost; SkillsBench 2602.12670 SWE +4.5 pp 16/84 negative, self-generated no benefit; VibeMemBench 2609.23570 verified experience +1.1–4.5 pp, 4 memory systems 11/12 pairings fail memory-off; code-anchored staleness Temporal Validity 2608.20685 36–38% superseded + limpet/TMF fingerprints → lesson anchors[] + kb FRESH/STALE; Zep/Graphiti bi-temporal + Mem0 supersede-on-write; ACE 2510.04618 +10.6% delta-only updates; Anthropic Contextual Retrieval −49%/−67%; Aider repo-map pull-only; Letta 2504.13171 sleep-time; MINJA/AgentPoison/OWASP ASI06 poisoning controls; LongMemEval 2410.10813 abstention. Spike A deterministic contextual BM25 mixed within noise NOT adopted (P@1 md-intent baseline 0.151 / C1 0.164 / C2 0.137; src-intent 0.048 / 0.038 / 0.067); spike B memory eval design Tier R offline + Tier O outcome (501 sessions, 6% cross-session refs, 4% memory calls, 11–16/90 recurring faults); Tier R v0 measured (§19, /tmp/tierr deleted): 502 JSONLs → recurring_fault 50 / user_flagged 23 / explicit_ref 2 / negative 30, valid 33/50 + 21/23 + 2/2 + 11/30 ~34% noise; helpful any shipped retriever 30/56 54% (session_search newest-first 19/56, bm25 17/56, kb_search 15/56 upper-bound leakage, memory_search 4/56 7%); no abstention, 30/30 negatives non-empty; ceiling ~54% vs delivery ≈ fraction (recall tools 4% sessions); D9 = tool results indexed + hybrid ranking + Tier R baseline numbers; D4 lifecycle frontmatter anchors[]/supersedes/valid_from/valid_to/trust + staleness, D5 abstention score floor + “injection must be earned”, tasks.md §2 eval gates block 1.6 cutover. Umbrella change drafted `openspec/changes/unify-context-manager` (skip_specs, phases 1–6). §19 ontology ablation (/tmp/onto deleted): deterministic regex entities (path/file/cmd/pkg/env/err/sym) on 856 hermes memories → 760 89% ≥1 entity avg 5.1; Tier R rebuilt 56 valid positives, hit@5 V0 body BM25 19/56 34% full / 2/56 4% as-of, V1 + entity FTS field 17/56, V2 overlap 17/56, V3 rare-entity 17/56 → entities do NOT help ranking or firing precision; keep deterministic entities for anchors/staleness, observed-event triggers, dedupe keys, supersession keys, graph joins; closed relation set with consumers `kb:about`/`kb:fixes`/`kb:supersedes`/`kb:decidedIn`/`kb:replacedBy`, source deterministic, lesson files only; LLM open-ontology not now (only via `add-kb-semantic-annotation-plane` for docs, lessons gated on Tier R gain); D4 ontology block reuses kb §9.4 shape (`type kb:Lesson`, `kb.relations[]`, `source deterministic`) + annotation-plane design §7 coordination note; `kb:fixes` untested. → 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` glass bands. Shipped 2026-08-26/27. → 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 order. Step 9 = ONE in-process call `pi.sendUserMessage({expandPromptTemplates:true,deliverAs})`, gate running pi >= 0.84.2; every session kind. Paths B/C/D retired; server tombstone for `dispatch_extension_command`. Keeper sidecar unchanged (durable pi-stdin owner). See change: retire-slash-dispatch-via-expand-prompt-templates. |
| `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. |
| `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`. 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` |