@gi4nks/ph 1.6.0 → 1.8.0

package/docs/evals/context-retrieval-golden.json

@@ -10,6 +10,14 @@
     { "id": "gemini-import", "project": "ph", "text": "Gemini history import reads session JSON, pairs human messages with the following model response, and supports dry run and duplicate filtering." },
     { "id": "remote-sync", "project": "ph", "text": "Remote sync pushes unsynced prompts and pulls newer records; sync hashes deduplicate matching prompt, response, tool, and arguments." },
     { "id": "analysis-memory", "project": "ph", "text": "Background analysis appends project memories and merges key insights and technical decisions into a single project summary." },
+    { "id": "shared-context", "project": "ph", "text": "getProjectContext and formatProjectContext are shared by ph context, chat, and MCP; semantic retrieval must stay project scoped." },
+    { "id": "wise-provider", "project": "ph", "text": "Wise provides OpenRouter and MLX-Serve providers in ph; provider and model configuration is shared across CLI and TUI." },
+    { "id": "homo-provider-boundary", "project": "homo", "text": "HOMO uses the shared Wise library to configure multiple AI providers behind the application's AI integration." },
+    { "id": "homo-genesis-context", "project": "homo", "text": "Chapter Genesis carries previous content fragments and book-level lore constraints into generated scenes." },
+    { "id": "picot-sqlite-build", "project": "picot", "text": "PicoT uses SQLite and Next.js; builds should use a SQLite timeout and isolated build data to avoid SQLITE_BUSY races." },
+    { "id": "picot-breadcrumb-context", "project": "picot", "text": "PicoT document preview preserves the originating library listing, search, and filters through breadcrumb navigation." },
+    { "id": "lens-harness-goal", "project": "lens", "text": "Lens integrates the harness goal loop with verified predicates, progress, recovery, and a run_command tool." },
+    { "id": "lens-wise-provider", "project": "lens", "text": "Lens WiseProvider supports OpenRouter and MLX-Serve using configured provider model IDs." },
     { "id": "unrelated-react", "project": "lens", "text": "React rendering uses reconciliation to compare virtual trees and update the browser DOM." },
     { "id": "unrelated-go", "project": "sonic", "text": "Go goroutines communicate using channels and are scheduled by the Go runtime." }
   ],
@@ -21,6 +29,14 @@
     { "query": "How are assistant replies and hidden reasoning handled in Claude imports?", "relevant": ["claude-import"] },
     { "query": "How does Gemini history import pair prompt and model output?", "relevant": ["gemini-import"] },
     { "query": "How does ph avoid duplicate records when synchronizing laptops?", "relevant": ["remote-sync"] },
-    { "query": "How do prompt analyses update the long term project knowledge?", "relevant": ["analysis-memory"] }
+    { "query": "How do prompt analyses update the long term project knowledge?", "relevant": ["analysis-memory"] },
+    { "query": "Which shared retrieval API do CLI, chat, and MCP use?", "relevant": ["shared-context"] },
+    { "query": "How are Wise models and providers configured in ph?", "relevant": ["wise-provider"] },
+    { "query": "How does HOMO pass earlier chapter context and lore into generation?", "relevant": ["homo-genesis-context"] },
+    { "query": "Which provider abstraction does HOMO use for AI backends?", "relevant": ["homo-provider-boundary"] },
+    { "query": "How should PicoT builds avoid SQLite locking conflicts?", "relevant": ["picot-sqlite-build"] },
+    { "query": "What state does PicoT preserve when navigating back from a document?", "relevant": ["picot-breadcrumb-context"] },
+    { "query": "How does Lens verify and recover an agent goal?", "relevant": ["lens-harness-goal"] },
+    { "query": "Which local and hosted AI providers are available to Lens?", "relevant": ["lens-wise-provider"] }
   ]
 }

package/docs/ph-architecture-review.html

@@ -0,0 +1,179 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>PH Architecture Review</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+  <style>
+    :root { color-scheme: light; --ink:#17212b; --muted:#52616d; --line:#d9e1e5; --paper:#f5f7f6; --teal:#087f74; --amber:#a85c05; --rose:#bd3e4b; }
+    body { background:var(--paper); color:var(--ink); font-family:Inter,ui-sans-serif,system-ui,-apple-system,sans-serif; }
+    h1,h2,h3,h4,.serif { font-family:Georgia,Cambria,"Times New Roman",serif; }
+    .module-box { border:1px solid #a8b8bf; border-radius:1rem; padding:1rem; background:#fff; box-shadow:0 10px 30px #162a3010; }
+    .diagram-arrow { color:#73848c; font-size:1.35rem; line-height:1; }
+    .seam-line { border-top:2px dashed var(--teal); position:relative; }
+    .seam-line:after { content:"SEAM"; position:absolute; right:0; top:-.78rem; padding:0 .45rem; background:white; color:var(--teal); font-size:.65rem; font-weight:800; letter-spacing:.12em; }
+    .mermaid { overflow-x:auto; background:#fff; padding:1.25rem; border:1px solid var(--line); border-radius:1rem; }
+    .evidence { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:.8rem; overflow-wrap:anywhere; }
+    .impact td,.impact th { padding:.55rem .65rem; border-bottom:1px solid var(--line); text-align:left; vertical-align:top; }
+    @media print { body { background:white; } .module-box,.mermaid { box-shadow:none; break-inside:avoid; } }
+  </style>
+</head>
+<body>
+  <main class="max-w-6xl mx-auto px-5 sm:px-8 py-10 sm:py-16">
+    <header class="border-b border-slate-300 pb-10">
+      <div class="flex flex-wrap gap-3 items-center text-sm text-slate-600">
+        <span class="rounded-full bg-slate-200 px-3 py-1 font-semibold">PH · PROMPT HISTORY</span>
+        <span>Architecture review</span><span>22 October 2026</span>
+        <span class="rounded-full bg-amber-100 text-amber-900 px-3 py-1 font-semibold">Working tree dirty</span>
+      </div>
+      <h1 class="serif text-5xl sm:text-6xl mt-8 leading-tight">A useful core under too many surfaces</h1>
+      <p class="mt-7 text-xl sm:text-2xl font-bold max-w-4xl">Strength: local capture, SQLite storage, and project-scoped retrieval form a coherent foundation with useful seams.</p>
+      <p class="mt-3 text-xl sm:text-2xl font-bold text-rose-800 max-w-4xl">Flaw: PH keeps adding command, transport, and knowledge workflows faster than it proves which ones users need.</p>
+      <div class="flex flex-wrap gap-3 mt-8 text-sm">
+        <span class="rounded-lg bg-slate-800 text-white px-3 py-2">Module</span>
+        <span class="rounded-lg border-2 border-dashed border-teal-700 text-teal-900 px-3 py-2">Seam</span>
+        <span class="rounded-lg border-2 border-dashed border-rose-600 text-rose-800 px-3 py-2">Leakage / unwired</span>
+        <span class="rounded-lg bg-teal-800 text-white px-3 py-2">Deep Module</span>
+      </div>
+      <p class="mt-6 max-w-4xl text-slate-600">This review describes the current working tree, including uncommitted operational-memory changes. It does not treat documentation or a passing test suite as proof of adoption.</p>
+    </header>
+
+    <section class="py-12 border-b border-slate-300">
+      <h2 class="serif text-3xl">Current Posture</h2>
+      <p class="mt-4 max-w-4xl text-slate-700">PH has a strong local-first data path and a meaningful retrieval boundary. Prompt capture remains useful without an LLM; semantic retrieval is optional; user approval gates curated memory writes. In this pass the MCP composition root was reduced to protocol setup, while memory and archive SQL moved behind repositories. The remaining concern is scope: a broad command set still exceeds what the operational workflow has validated.</p>
+      <div class="grid md:grid-cols-3 gap-4 mt-7">
+        <div class="module-box"><div class="text-3xl font-bold">97</div><div class="text-sm text-slate-600 mt-1">TypeScript / TSX source files</div></div>
+        <div class="module-box"><div class="text-3xl font-bold">17</div><div class="text-sm text-slate-600 mt-1">Test files; 94 tests passed in this checkout</div></div>
+        <div class="module-box"><div class="text-3xl font-bold">482 · 50 · 521 · 964</div><div class="text-sm text-slate-600 mt-1">Lines in CLI, MCP composition root, PhDB facade, and BrowseApp respectively</div></div>
+      </div>
+      <div class="mt-6 grid md:grid-cols-2 gap-5 text-sm">
+        <div class="rounded-xl border border-slate-300 bg-white p-5"><h3 class="font-bold text-teal-900">Rules the system respects</h3><ul class="list-disc pl-5 mt-3 space-y-1 text-slate-700"><li>SQLite is the source of truth; Ollama and generative providers are optional.</li><li>Project filters are applied inside semantic retrieval before limiting results.</li><li>Operational `prepare` is read-only; `close` asks for approval before promotion.</li><li>CLI and MCP share task-context retrieval and atomic memory promotion use cases.</li><li>Memory and archive repositories share the existing SQLite connection through the stable PhDB facade.</li></ul></div>
+        <div class="rounded-xl border border-rose-200 bg-rose-50 p-5"><h3 class="font-bold text-rose-900">Rules that are not yet proven</h3><ul class="list-disc pl-5 mt-3 space-y-1 text-slate-700"><li>The plan's three real tasks across different projects are not evidenced; it records one temporary-database usage check.</li><li>MCP-only tools still own some search and rendering decisions inside their grouped handler modules.</li><li>Feature breadth spans history capture, analysis, memory, TUI, MCP, import, archive, and remote sync.</li><li>Embedding-backed retrieval quality has not been evaluated in this pass.</li></ul></div>
+      </div>
+      <p class="mt-5 text-sm text-slate-600">Verification observed: <span class="font-semibold">npm test</span> passed (17 files, 94 tests), <span class="font-semibold">npm run lint</span>, <span class="font-semibold">npm run build</span>, and `npx tsc --noEmit` all passed. A separate embedding-backed retrieval evaluation was not run.</p>
+    </section>
+
+    <section class="py-12 border-b border-slate-300">
+      <h2 class="serif text-3xl">Runtime Map</h2>
+      <p class="mt-3 max-w-4xl text-slate-700">Solid teal marks high-leverage modules; dashed red marks broad adapters or duplicated routes where responsibilities leak across boundaries.</p>
+      <div class="mermaid mt-6">
+flowchart LR
+  User[User / agent] --> CLI[CLI dispatch and commands]
+  Hooks[CLI hooks and importers] --> Capture[Capture normalization]
+  CLI --> Capture
+  Capture --> DB[(SQLite / PhDB)]
+  CLI --> Retrieval[Project context retrieval]
+  MCP[MCP protocol composition] --> MCPTools[Grouped prompt, project, timeline handlers]
+  MCPTools --> Retrieval
+  Retrieval --> DB
+  Retrieval --> Embed[Embedding endpoint]
+  Retrieval --> Render[Shared context formatter]
+  Render --> CLI
+  Render --> MCPTools
+  CLI --> Close[Close proposal and approval]
+  Close --> Provider[Analysis provider]
+  Close --> DB
+  MCPTools --> DB
+  DB --> Vec[Semantic index]
+  CLI --> TUI[Ink browser]
+  TUI --> DB
+  CLI --> Remote[HTTP sync client]
+  Remote --> Server[HTTP sync server]
+  Server --> DB
+  classDef deep fill:#075e57,stroke:#064e48,color:#fff,stroke-width:2px;
+  classDef module fill:#e6f4f1,stroke:#0c8276,color:#153b38,stroke-width:1.5px;
+  classDef leak fill:#fff0f1,stroke:#c2414c,color:#762631,stroke-width:2px,stroke-dasharray:6 4;
+  classDef external fill:#f1f5f9,stroke:#64748b,color:#1e293b;
+  class Capture,Retrieval,Render,Vec deep;
+  class CLI,Close,TUI,DB,MCP,MCPTools module;
+  class Remote,Server leak;
+  class User,Hooks,Embed,Provider external;
+      </div>
+      <div class="grid md:grid-cols-3 gap-4 mt-5 text-sm">
+        <div class="module-box"><b>Capture Seam</b><p class="mt-2 text-slate-600">`src/capture/index.ts` normalizes direct logging, wrappers, and importers before persistence.</p></div>
+        <div class="module-box"><b>Retrieval Seam</b><p class="mt-2 text-slate-600">`src/knowledge/task-context.ts` shares bounded task retrieval across prepare and MCP; `src/context/index.ts` serves context and chat formatting.</p></div>
+        <div class="module-box border-rose-300"><b>Persistence Leakage</b><p class="mt-2 text-slate-600">The stable `PhDB` facade still exposes a broad prompt API; repository interfaces remain internal and SQLite-specific.</p></div>
+      </div>
+    </section>
+
+    <section class="py-12 border-b border-slate-300">
+      <h2 class="serif text-3xl">Candidates / Opportunities for Deepening</h2>
+      <p class="mt-3 text-slate-700 max-w-4xl">These are targeted reductions in real Leakage. They are not a proposal to replace the stack or split every file.</p>
+
+      <article class="mt-8 rounded-2xl border border-rose-200 bg-white p-6 sm:p-8">
+        <div class="flex flex-wrap justify-between gap-3"><h3 class="serif text-2xl">1. Contain product scope until real-use evidence exists</h3><div class="flex gap-2"><span class="rounded-full bg-teal-100 text-teal-900 px-3 py-1 text-sm font-bold">Implemented as a scope gate</span><span class="rounded-full bg-slate-800 text-white px-3 py-1 text-sm font-bold">P0</span></div></div>
+        <p class="evidence mt-4 text-slate-600">Evidence: `src/cli.ts:46-155` advertises a wide command set; `src/commands/` has 26 handlers; `README.md` describes capture, imports, analysis, memories, TUI, MCP, archive, and remote sync; `ROADMAP.md` now gates new user-facing work on three real tasks across projects.</p>
+        <h4 class="mt-5 font-bold">Problem</h4><p class="text-slate-700">PH now has several overlapping ways to retrieve project knowledge (`context`, `prepare`, chat injection, MCP knowledge checks) plus a separate curation flow. The tool's command count is growing while the core promise—capture useful history and find it again—has no adoption or success measure in the repo. This is product-scope Leakage: every surface needs help, docs, compatibility, and tests.</p>
+        <h4 class="mt-5 font-bold">Solution</h4><p class="text-slate-700">Keep the current commands available, state their distinct jobs, and defer new commands, transports, or knowledge workflows until the `prepare → work → close → promote` loop is used on three real tasks in different projects. The gate is now recorded in `ROADMAP.md`; no existing capability was removed.</p>
+        <div class="grid sm:grid-cols-2 gap-3 mt-5"><div class="module-box border-rose-300"><b>Before · surface area</b><div class="mt-3 flex flex-wrap gap-2 text-xs"><span class="bg-rose-50 p-2 rounded">context</span><span class="bg-rose-50 p-2 rounded">prepare</span><span class="bg-rose-50 p-2 rounded">chat context</span><span class="bg-rose-50 p-2 rounded">MCP check</span><span class="bg-rose-50 p-2 rounded">close</span><span class="bg-rose-50 p-2 rounded">save decision</span></div></div><div class="module-box border-teal-700"><b>After · gated growth</b><div class="mt-3 flex items-center gap-2 text-xs"><span class="bg-teal-50 p-2 rounded">capture</span><span class="diagram-arrow">→</span><span class="bg-teal-50 p-2 rounded">retrieve evidence</span><span class="diagram-arrow">→</span><span class="bg-teal-50 p-2 rounded">curate if useful</span></div><p class="mt-2 text-xs text-teal-900">No new surface until real-use gate.</p></div></div>
+        <div class="seam-line mt-8"></div><p class="mt-4 text-sm text-slate-700"><b>Seam:</b> a user-visible workflow contract that works through CLI and MCP without duplicating domain decisions. <b>Deep Module:</b> the smallest evidence-backed workflow PH can make dependable.</p>
+        <table class="impact w-full mt-4 text-sm"><tr><th>Leverage</th><th>Locality</th><th>Tests</th></tr><tr><td>Less maintenance per feature and clearer product promise.</td><td>Related user actions converge on fewer entry points.</td><td>Add outcome checks for retrieval usefulness and accepted promotions, not just command behavior.</td></tr></table>
+      </article>
+
+      <article class="mt-6 rounded-2xl border border-amber-200 bg-white p-6 sm:p-8">
+        <div class="flex flex-wrap justify-between gap-3"><h3 class="serif text-2xl">2. Give knowledge promotion one atomic persistence operation</h3><div class="flex gap-2"><span class="rounded-full bg-teal-100 text-teal-900 px-3 py-1 text-sm font-bold">Implemented</span><span class="rounded-full bg-slate-800 text-white px-3 py-1 text-sm font-bold">P1</span></div></div>
+        <p class="evidence mt-4 text-slate-600">Evidence: the previous implementation issued two writes per proposal. `PhDB.promoteMemories()` now delegates to the memory repository (`src/db/index.ts:473`); the shared provenance and promotion use case is `src/knowledge/promotion.ts`, used by CLI (`src/commands/close.ts:101`) and MCP (`src/mcp/tools/projects.ts:8,21`). A rollback test covers the transaction in `src/db/__tests__/phdb.test.ts`.</p>
+        <h4 class="mt-5 font-bold">Problem</h4><p class="text-slate-700">Before this review, staged approval did not guarantee atomic persistence. A failed summary update or later proposal could leave a partial result. The fix now places the approved batch in one SQLite transaction; this candidate is addressed in the current working tree.</p>
+        <h4 class="mt-5 font-bold">Solution</h4><p class="text-slate-700">The shared promotion operation accepts the approved proposal batch and writes memories plus aggregate summaries atomically. CLI and MCP use the same operation. Provider generation and interactive review stay outside the transaction; the Seam is the approved proposal batch.</p>
+        <div class="grid sm:grid-cols-2 gap-3 mt-5"><div class="module-box border-rose-300"><b>Before</b><div class="mt-3 flex items-center gap-2 text-xs"><span>insert memory</span><span class="diagram-arrow">→</span><span>update summary</span><span class="diagram-arrow">→</span><span>repeat</span></div><p class="mt-2 text-xs text-rose-800">Failure can leave partial state.</p></div><div class="module-box border-teal-700"><b>After</b><div class="mt-3 rounded-lg bg-teal-50 p-3 text-xs">Approved batch <span class="diagram-arrow">→</span> single DB transaction <span class="diagram-arrow">→</span> consistent memories + summaries</div></div></div>
+        <div class="seam-line mt-8"></div><p class="mt-4 text-sm text-slate-700"><b>Seam:</b> transport-independent promotion input. <b>Deep Module:</b> persistence owns consistency and exposes one operation with a simple result.</p>
+        <table class="impact w-full mt-4 text-sm"><tr><th>Leverage</th><th>Locality</th><th>Tests</th></tr><tr><td>Both CLI and MCP get the same all-or-nothing guarantee.</td><td>Memory and summary consistency live beside database writes.</td><td>Inject a failure midway and assert neither side changed.</td></tr></table>
+      </article>
+
+      <article class="mt-6 rounded-2xl border border-amber-200 bg-white p-6 sm:p-8">
+        <div class="flex flex-wrap justify-between gap-3"><h3 class="serif text-2xl">3. Thin the MCP composition root and share cross-transport work</h3><div class="flex gap-2"><span class="rounded-full bg-teal-100 text-teal-900 px-3 py-1 text-sm font-bold">Implemented; handlers remain adapters</span><span class="rounded-full bg-slate-800 text-white px-3 py-1 text-sm font-bold">P1</span></div></div>
+        <p class="evidence mt-4 text-slate-600">Evidence: `src/mcp/server.ts` is now 50 lines. Tool definitions live in `src/mcp/tools/definitions.ts`; prompt, project, and timeline handlers are grouped in `src/mcp/tools/`; formatting is isolated in `format.ts`. `src/knowledge/{task-context,promotion}.ts` centralize shared retrieval and persistence.</p>
+        <h4 class="mt-5 font-bold">Problem</h4><p class="text-slate-700">The original server mixed protocol registration, all handlers, retrieval policy, writes, and formatting. The composition root is now small and tool code is local by domain. Some MCP-only search, timeline, and output behavior remains in adapter modules, so the transport boundary is improved but not fully domain-neutral.</p>
+        <h4 class="mt-5 font-bold">Solution</h4><p class="text-slate-700">The composition root now owns MCP SDK registration, handler dispatch, and error envelopes. Shared task-context retrieval and memory promotion live under `src/knowledge/` and are called by CLI and MCP. Tool-specific protocols and renderers remain grouped under `src/mcp/tools/`; further extraction should wait for another consumer.</p>
+        <div class="grid sm:grid-cols-2 gap-3 mt-5"><div class="module-box border-rose-300"><b>Before</b><div class="mt-3 text-xs space-y-2"><div class="rounded bg-rose-50 p-2">MCP root owns tool declarations, queries, fallback, and formatting</div><div class="rounded bg-rose-50 p-2">MCP root validates sources and performs persistence</div></div></div><div class="module-box border-teal-700"><b>After</b><div class="mt-3 text-xs space-y-2"><div class="rounded bg-teal-50 p-2">MCP root → grouped tool handlers → shared task-context use case</div><div class="rounded bg-teal-50 p-2">CLI / MCP → shared promotion use case → PhDB facade</div></div></div></div>
+        <div class="seam-line mt-8"></div><p class="mt-4 text-sm text-slate-700"><b>Seam:</b> transport-neutral application operations. <b>Deep Module:</b> reusable project knowledge behavior with a compact input/output contract.</p>
+        <table class="impact w-full mt-4 text-sm"><tr><th>Leverage</th><th>Locality</th><th>Tests</th></tr><tr><td>New transports reuse product behavior instead of cloning it.</td><td>Protocol concerns stop interleaving with retrieval and writes.</td><td>Use-case tests avoid MCP protocol setup; adapter tests focus on schemas and errors.</td></tr></table>
+      </article>
+
+      <article class="mt-6 rounded-2xl border border-amber-200 bg-white p-6 sm:p-8">
+        <div class="flex flex-wrap justify-between gap-3"><h3 class="serif text-2xl">4. Split cohesive persistence behind the PhDB facade</h3><div class="flex gap-2"><span class="rounded-full bg-teal-100 text-teal-900 px-3 py-1 text-sm font-bold">Implemented for memory and archive</span><span class="rounded-full bg-slate-800 text-white px-3 py-1 text-sm font-bold">P2</span></div></div>
+        <p class="evidence mt-4 text-slate-600">Evidence: `src/db/index.ts` is now a 521-line public facade with prompt CRUD, FTS, migrations, and query forwarding. Memory and summary persistence moved to `src/db/memory-repository.ts`; archive persistence moved to `src/db/archive-repository.ts`; vectors remain in `src/db/semantic-index.ts`.</p>
+        <h4 class="mt-5 font-bold">Problem</h4><p class="text-slate-700">PhDB previously owned SQL for prompt CRUD, FTS, archives, memories, and summaries in one implementation. Memory and archive SQL now live in cohesive repositories over the same connection. The facade deliberately retains source compatibility; prompt CRUD and FTS remain one group.</p>
+        <h4 class="mt-5 font-bold">Solution</h4><p class="text-slate-700">The extraction keeps prompt CRUD/FTS in the facade and moves memory/summary and archive SQL behind internal repositories. All repositories share one SQLite connection; `PhDB` method names and return values stay stable. Avoid widening the repository abstraction until a second adapter needs it.</p>
+        <div class="grid sm:grid-cols-2 gap-3 mt-5"><div class="module-box border-rose-300"><b>Before</b><div class="mt-3 flex flex-wrap gap-2 text-xs"><span class="bg-rose-50 rounded p-2">PhDB: prompt</span><span class="bg-rose-50 rounded p-2">memory</span><span class="bg-rose-50 rounded p-2">summary</span><span class="bg-rose-50 rounded p-2">archive</span><span class="bg-rose-50 rounded p-2">migrations</span></div></div><div class="module-box border-teal-700"><b>After</b><div class="mt-3 flex items-center gap-2 text-xs"><span class="bg-teal-50 rounded p-2">PhDB prompt facade</span><span class="diagram-arrow">→</span><span class="border-2 border-dashed border-teal-700 rounded p-2">MemoryRepository<br>ArchiveRepository</span><span class="diagram-arrow">→</span><span class="bg-teal-50 rounded p-2">shared SQLite</span></div></div></div>
+        <div class="seam-line mt-8"></div><p class="mt-4 text-sm text-slate-700"><b>Seam:</b> existing PhDB-to-SQLite boundary, narrowed around use cases. <b>Deep Module:</b> a repository operation that hides SQL and guarantees its domain invariant.</p>
+        <table class="impact w-full mt-4 text-sm"><tr><th>Leverage</th><th>Locality</th><th>Tests</th></tr><tr><td>Changes to archive or memory behavior affect fewer consumers.</td><td>Each persistence concern owns its schema/query details.</td><td>Test repository invariants against temporary SQLite; use-case tests use a small contract.</td></tr></table>
+      </article>
+    </section>
+
+    <section class="py-12 border-b border-slate-300">
+      <h2 class="serif text-3xl">Top Recommendation</h2>
+      <div class="mt-5 rounded-2xl bg-slate-900 text-white p-6 sm:p-8">
+        <p class="text-teal-200 text-sm uppercase tracking-widest font-bold">First move · validate the operational workflow</p>
+        <h3 class="serif text-3xl mt-3">Do not add another memory feature yet</h3>
+        <p class="mt-4 max-w-4xl text-slate-200">Three structural actions are now in place: a product-scope gate, transport-neutral task-context and promotion operations with grouped MCP modules, and internal memory/archive repositories behind the unchanged PhDB API. Keep `prepare` as a read-only experiment. The remaining product test is three real tasks on different projects; record whether the brief prevented repeated work before adding more features.</p>
+        <p class="mt-4 max-w-4xl text-slate-200">Why this comes first: the biggest risk is not that PH lacks another abstraction. It is that summaries, memories, and tool-specific retrieval behavior drift while product value remains unmeasured. A transaction seam protects data now; a usage gate protects the project from building maintenance around an unproven loop.</p>
+      </div>
+    </section>
+
+    <section class="py-12 border-b border-slate-300">
+      <h2 class="serif text-3xl">Usage Modes</h2>
+      <div class="grid md:grid-cols-2 gap-4 mt-6">
+        <div class="module-box"><h3 class="font-bold">Capture and import history</h3><p class="mt-2 text-sm text-slate-600">Direct logging, wrappers, hooks, and importers normalize into prompt records.</p><p class="evidence mt-3">`src/capture/index.ts`, `src/importer/`, `src/commands/log.ts`, `hooks/`</p></div>
+        <div class="module-box"><h3 class="font-bold">Search local prompt history</h3><p class="mt-2 text-sm text-slate-600">SQLite FTS supports text search; sqlite-vec adds optional semantic search.</p><p class="evidence mt-3">`src/commands/search.ts`, `src/db/index.ts:246-345`, `src/db/semantic-index.ts`</p></div>
+        <div class="module-box"><h3 class="font-bold">Browse and curate records</h3><p class="mt-2 text-sm text-slate-600">The Ink interface filters, previews, edits metadata, exports, and reruns prompts.</p><p class="evidence mt-3">`src/ui/BrowseApp.tsx`, `src/ui/FilterPanel.tsx`, `src/ui/PreviewPane.tsx`</p></div>
+        <div class="module-box"><h3 class="font-bold">Expose history and project context to agents</h3><p class="mt-2 text-sm text-slate-600">MCP serves prompt queries and project knowledge; project tools call shared task-context retrieval and promotion use cases.</p><p class="evidence mt-3">`src/mcp/server.ts`, `src/mcp/tools/`, `src/knowledge/`</p></div>
+        <div class="module-box"><h3 class="font-bold">Prepare and promote operational knowledge</h3><p class="mt-2 text-sm text-slate-600">`prepare` retrieves a bounded brief; `close` proposes curated memory after provider analysis and user approval. Implemented in the current dirty tree; three-project real-use validation remains outstanding.</p><p class="evidence mt-3">`src/commands/prepare.ts`, `src/commands/close.ts`, `docs/specs/SPEC-016-operational-memory.md`</p></div>
+        <div class="module-box"><h3 class="font-bold">Synchronize with a remote PH server</h3><p class="mt-2 text-sm text-slate-600">An optional HTTP service supports prompt push/pull and memory lookups. It adds a second deployment and security surface.</p><p class="evidence mt-3">`src/server/index.ts`, `src/commands/remote.ts`</p></div>
+      </div>
+      <div class="mt-8 grid md:grid-cols-2 gap-4">
+        <div class="rounded-xl bg-teal-50 border border-teal-300 p-5"><h3 class="font-bold text-teal-950">Ready for...</h3><p class="mt-2 text-sm text-slate-700">Local prompt capture, search, browsing, and opt-in agent access to a user's own project history. The operational-memory commands are implemented and pass their current automated suite.</p></div>
+        <div class="rounded-xl bg-rose-50 border border-rose-300 p-5"><h3 class="font-bold text-rose-950">Still requires integration...</h3><p class="mt-2 text-sm text-slate-700">Evidence that the prepare/close loop improves real tasks; retrieval evaluation against the configured embedding model; and a coherent support boundary for the many transports and commands.</p></div>
+      </div>
+    </section>
+
+    <footer class="pt-8 text-sm text-slate-600 flex flex-wrap justify-between gap-3">
+      <span>PH Architecture Review · Based on the working tree at review time</span>
+      <span>Created: 2026-10-22 · Updated: 2026-10-22</span>
+    </footer>
+  </main>
+  <script>mermaid.initialize({startOnLoad:true,theme:'neutral',securityLevel:'strict'});</script>
+</body>
+</html>

package/docs/ph-manual.md

@@ -1,14 +1,14 @@
 # ph — Prompt History and Project Memory
 
-**Zero-friction capture, semantic search, project memory, and MCP-based knowledge retrieval for AI CLI tools.**
+**Capture AI CLI work, find it later, and retrieve project context when you need it.**
 
 ---
 
 ## 1. Overview
 
-ph is a transparent observability and knowledge layer for AI CLI tools (Claude Code, Codex CLI, Gemini CLI, OpenCode, etc.). It automatically records every prompt+response into a local SQLite database with full-text search, semantic vector search, LLM-based analysis, Git context snapshots, session grouping, and an interactive TUI browser.
+ph is a local history and project-context tool for AI CLI work. It records interactions through native hooks or by wrapping a tool, then helps you search history and retrieve project context from the terminal.
 
-**Core principle:** ph captures conversations without changing the normal tool workflow. Optional analysis turns captured history into project summaries and memories that can be searched locally or requested by an MCP client. Capture and full-text search work without an LLM provider; analysis, embeddings, and semantic search require the configured provider.
+**Core principle:** ph captures conversations without changing the normal tool workflow. Optional analysis enriches each captured interaction with searchable summary, insights, decisions, and classification. Analysis does not promote active project memories; `ph close` and MCP `save_decision` are the explicit promotion paths. Capture and full-text search work without an LLM provider; analysis, embeddings, and semantic search require the configured provider.
 
 ### Key Features
 
@@ -17,7 +17,7 @@ ph is a transparent observability and knowledge layer for AI CLI tools (Claude C
 - **LLM analysis** — role/tag/relevance classification, summary extraction, key insights, technical decisions
 - **Project memory** — per-project accumulated knowledge with deduped insights and decisions
 - **MCP server** — tools for agents to search memories, check project knowledge, get context
-- **Interactive TUI** — browse, filter, edit, star, re-run, export prompts
+- **Plain-text CLI** — the everyday interface is a small set of terminal commands
 - **Session grouping** — automatic conversation grouping with cohesion scoring
 - **Git context** — records branch, modified files, and diff at capture time
 - **Background analysis** — async LLM processing after each capture (optional)
@@ -45,7 +45,7 @@ npm link
 
 ```bash
 ph config set background-analysis true   # auto-analyze after each capture
-ph config set analyze-provider ollama     # ollama (default) or gemini
+ph config set analyze-provider ollama     # ollama (default), gemini, openrouter, or mlx-serve
 ph config set ollama-model llama3.1:latest
 ```
 
@@ -98,18 +98,41 @@ echo '{"tool":"claude","prompt":"hi","response":"hello"}' | ph log --stdin
 
 ---
 
-## 4. CLI Commands
+## 4. Everyday Commands
 
 | Command | Description |
 |---------|-------------|
-| `ph` (no args) | Open interactive TUI browser |
+| `ph` | Print the short usage guide |
+| `ph setup` | Connect installed Claude Code, Codex CLI, Gemini CLI, and OpenCode for automatic capture |
+| `ph <tool> [args...]` | Run an AI CLI tool and capture the interaction |
+| `ph search <query>` | Find earlier work in the current project (five matches by default) |
+| `ph show <id>` | Inspect the complete prompt, response, capture metadata, and analysis |
+| `ph show <id> --json` | Print the complete interaction as JSON |
+| `ph context "task"` | Retrieve project knowledge and related prompts |
+| `ph close` | Review the last three hours and approve useful project knowledge |
+
+`ph setup` is the recommended first step for everyday use. It detects installed supported tools (Claude Code, Codex CLI, Gemini CLI, and OpenCode), installs their native capture integrations, preserves existing settings, and reports whether each integration was installed or already configured. Pass tool names to choose explicitly. After setup, keep using your AI CLI normally; `ph search "query"` is the main command for retrieving earlier work. `ph <tool>` remains as a wrapper alternative.
+
+`ph search "query"` searches the project detected from the current directory and returns five matches by default, ordered by text relevance. Use `--limit <n>` to show more, or `--all` to search across every project. When no project can be detected, PH searches all saved work and labels that scope. Searches with no current-project matches explain how to broaden the search.
+
+`ph prepare "task"` remains as a compatibility alias for task-aware `ph context`.
+`ph browse` is a compatibility alias for a plain-text list of recent interactions.
+Use `ph help --all` for maintenance and integration commands, including `ph status` for recent capture and background-work state.
+
+## 4a. Advanced Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `ph` (no args) | Print the short everyday-use guide |
 | `ph <tool> [args...]` | Wrapper mode — run tool + capture |
-| `ph search [query]` | Full-text search prompts |
+| `ph search [query]` | Full-text search (current project, five matches by default) |
 | `ph search --semantic <query>` | Semantic (vector) search |
 | `ph search --archive` | Search archived prompts |
-| `ph search -i <query>` | Open results in interactive TUI |
 | `ph last [n]` | Show last N prompts |
-| `ph context [query]` | Get RAG context for current project |
+| `ph context [task]` | Retrieve task-aware project context; works without semantic embeddings |
+| `ph prepare "<task>"` | Compatibility alias for task-aware context retrieval |
+| `ph browse` | Compatibility alias for recent text results |
+| `ph close [--since 3h]` | Review recent work and propose knowledge for explicit approval |
 | `ph sessions` | Group prompts into work sessions |
 | `ph timeline <project>` | Full chronological project history |
 | `ph stats` | History statistics |
@@ -120,10 +143,11 @@ echo '{"tool":"claude","prompt":"hi","response":"hello"}' | ph log --stdin
 | `ph cleanup --retention` | Archive old/unqualified prompts per retention policy |
 | `ph cleanup-reusability` | Cleanup by reusability score |
 | `ph star <id>` | Toggle bookmark |
-| `ph export <id>` | Export prompt (txt/json/md) |
+| `ph export <id> [--format txt|json|md] [--archive]` | Export a complete interaction |
+| `ph status` | Show recent capture, analysis, and remote-push state without content |
 | `ph import gemini|claude|opencode|codex` | Import from AI CLI history |
 | `ph log --tool <name> ...` | Direct log (hook target) |
-| `ph embed-all` | Generate embeddings for all prompts |
+| `ph embed-all` | Generate embeddings for prompts without vectors |
 | `ph config get|set <key> <value>` | View/edit config |
 | `ph vacuum` | Compact SQLite database |
 | `ph memory-migrate` | Merge existing memories into project_summaries |
@@ -136,7 +160,6 @@ echo '{"tool":"claude","prompt":"hi","response":"hello"}' | ph log --stdin
 ### Search options
 
 ```
--i / --interactive    Open in TUI browser
 --tool <name>         Filter by tool
 --project <name>      Filter by project
 --language <lang>     Filter by language
@@ -147,11 +170,12 @@ echo '{"tool":"claude","prompt":"hi","response":"hello"}' | ph log --stdin
 --archive             Search archived prompts
 --since YYYY-MM-DD    Start date
 --until YYYY-MM-DD    End date
---limit <n>           Max results (default 50)
+--limit <n>           Max results (default 5)
+--all                 Search across all projects instead of the current project
 --top                 Quality >= 8
 --min-quality <n>     Min quality (0-10)
 --min-relevance <n>   Min relevance (0-10)
---full                Show full prompt text
+--full                Show full prompt and response text
 ```
 
 ### Context options
@@ -183,43 +207,13 @@ echo '{"tool":"claude","prompt":"hi","response":"hello"}' | ph log --stdin
 
 ---
 
-## 5. TUI Keybindings
-
-| Key | Action |
-|-----|--------|
-| `Up` / `Down`, `Page Up` / `Page Down` | Navigate list |
-| `Tab` | Switch pane (wide mode) |
-| `1`, `2`, `3` | Switch prompt/response/memory tab |
-| `y` | Copy to clipboard |
-| `s` | Toggle star |
-| `e` | Edit metadata |
-| `r` | Rerun prompt (edit before launch) |
-| `Shift+C` | Chat mode: launch tool with project context |
-| `x` | Delete entry |
-| `/` | Search |
-| `o` | Settings panel (toggle auto-analysis, view config) |
-| `f` | Filter panel (flat list, Enter toggle, letter jump) |
-| `c` | Clear all filters |
-| `q` / `Escape` | Quit / back |
-
-### TUI components
-
-- **SearchBar** — always visible spotlight bar at top
-- **FilterPanel** — flat scrollable list of filter options with counts `[N]`, toggle with Enter, jump by letter
-- **SettingsView** — config viewer/editor (auto-analysis toggle, ollama URL/model, filters)
-- **PreviewPane** — three tabs (prompt/response/memory). Memory tab shows project-level knowledge
-- **ListEntry** — role marker, analysis status, star, Q/R badges, optional summary line
-- **Footer** — context-sensitive hints (shows `C:chat` only when entry has project)
-
----
-
-## 6. Project Memory System
+## 5. Project Memory System
 
 ph maintains two levels of per-project knowledge:
 
-### 6a. `project_summaries` (curated, 1 row per project)
+### 5a. `project_summaries` (curated, 1 row per project)
 
-Accumulated knowledge with deduped insights and decisions. Updated on every analysis. Primary source for MCP tools.
+Accumulated, explicitly promoted knowledge with deduped insights and decisions. Updated by approved `close` proposals, MCP `save_decision`, and legacy migration; automatic analysis does not write here.
 
 ```bash
 # View accumulated project knowledge
@@ -229,9 +223,29 @@ ph context --project myproject
 # get_project_summary(project: "myproject")
 ```
 
-### 6b. `memories` (append-only timeline)
+### 5b. `memories` (append-only timeline)
+
+Legacy append-only project knowledge records retained for detailed audit. New automatic analysis results stay on their source interaction instead of creating memory rows.
+
+### Operational workflow: retrieve, work, review
+
+```bash
+# Read-only task context; project auto-detected from the current directory
+ph context "add Wise provider" --limit 5 --budget 3500
+
+# Inspect the selection without calling an LLM
+ph close --dry-run --since 3h
+
+# Generate knowledge proposals; approve, edit, skip, or quit each one
+ph close --since 3h
+ph close --from 1670 --to 1682 --project ph
+```
+
+`context` uses the task as a semantic retrieval query and prints source-linked prompt and memory excerpts. If Ollama embeddings are unavailable, it labels the fallback to recent project context. Retrieval never writes to SQLite. `prepare` remains an alias for compatibility. The character budget limits retrieved content; when the source list itself is larger than the budget, source IDs take precedence and the output can exceed the requested budget.
 
-Full chronological history of every analysis run. Preserved for detailed audit.
+`close` selects prompt/response pairs within one project, displays them before generation, and asks the configured analysis provider for durable proposals. It checks for a terminal before making that provider call. Each accepted proposal creates an append-only memory tied to its source prompt IDs; the approved batch and summary updates are committed in one SQLite transaction. A persistence failure rolls back the whole batch. Provider errors, malformed output, dry-run, skipping, and quitting do not promote unapproved knowledge.
+
+MCP `check_project_knowledge` uses the same retrieval and rendering boundary. MCP `save_decision` accepts optional `promptIds` and rejects missing or cross-project sources.
 
 ### Memory migration
 
@@ -243,7 +257,7 @@ ph memory-migrate   # one-time: merge all memories into project_summaries
 
 ---
 
-## 7. Retention & Archiving
+## 6. Retention & Archiving
 
 Configurable auto-archiving to keep the database lean:
 
@@ -266,9 +280,9 @@ ph search --archive
 
 ---
 
-## 8. Background Analysis
+## 7. Background Analysis
 
-When enabled, every `ph log` automatically spawns a detached child process that analyzes the new entry (role, tags, relevance, summary, key insights, technical decisions).
+When enabled, every `ph log` marks analysis pending and starts a detached child process that adds role, tags, relevance, summary, key insights, and technical decisions to the interaction. It does not create project memories or summaries. `ph status` shows pending, complete, or safe failure state. Remote push status is shown when configured.
 
 ```bash
 ph config set background-analysis true
@@ -283,9 +297,40 @@ ph config set ollama-model llama3.1:latest
 ph config set ollama-embed-model nomic-embed-text-v2-moe
 ```
 
+OpenRouter and MLX-Serve generation use `@gi4nks/wise`:
+
+```bash
+# OpenRouter: credentials stay in the environment; model IDs keep provider/model.
+export OPENROUTER_API_KEY="your_openrouter_api_key"
+ph models openrouter
+ph config set openrouter-api-key  # hidden prompt; or keep using the environment
+ph config set analyze-provider openrouter
+ph config set openrouter-model "provider/model-id"
+ph config show                    # provider settings with credentials redacted
+ph analyze
+
+# MLX-Serve on Parmenide: open this tunnel in a separate terminal.
+ssh -N -L 11234:127.0.0.1:11234 parmenide
+```
+
+```bash
+# In the terminal where you run ph:
+ph models mlx-serve
+ph config set analyze-provider mlx-serve
+ph config set mlx-serve-model "exact-model-id-from-server"
+ph analyze
+```
+
+MLX-Serve defaults to `http://127.0.0.1:11234/v1`. Override it with
+`MLX_SERVE_BASE_URL` or `ph config set mlx-serve-url <url>`. Set
+`MLX_SERVE_API_KEY` if the server requires auth; `GLB_OMLX_API_KEY` is also
+accepted for existing setups. Alternatively run `ph config set mlx-serve-api-key`
+to enter it without echoing it in the terminal. `ph config show` redacts
+credentials. `ph models mlx-serve` marks entries `[loaded]` or `[unloaded]`.
+
 ---
 
-## 9. MCP Server
+## 8. MCP Server
 
 ph exposes an MCP (Model Context Protocol) server over stdio for AI agents:
 
@@ -311,26 +356,30 @@ ph mcp
 
 ---
 
-## 10. HTTP Server & Remote Sync
+## 9. HTTP Server & Remote Sync
 
 Share prompt history across machines:
 
 ```bash
-# Start server
-ph server --port 3001 --host 0.0.0.0
-
-# From another machine
+# Configure the required server key, then start on loopback
+ph config set remote-api-key "$PH_REMOTE_API_KEY"
+ph server --port 3001
+
+# On the server, expose the listener only on a protected interface and put TLS
+# in front of it before using the endpoint across an untrusted network.
+# On each client, set the server URL and the same key:
+ph config set remote-api-key "$PH_REMOTE_API_KEY"
 ph config set remote-url http://server-ip:3001
-ph remote push      # send local unsynced prompts
-ph remote pull      # fetch remote prompts
+ph remote push      # resumable ID-based sync
+ph remote pull      # resumable ID-based sync
 ph remote status    # show sync state
 ```
 
-Every `ph log` auto-pushes to remote if configured (fire-and-forget, never blocks).
+The server requires a key before it starts, binds to `127.0.0.1` by default, and exposes only a status value at public `/health`. All data routes require Bearer authentication. Push and pull cursors are scoped to the remote target and the local database UUID. Push pages are split to stay below the 32 MiB request-body limit; interrupted pages can be retried safely. Bulk push waits at a live wrapper record and continues after the response is saved. `ph log` and both wrapper modes push after capture; requests time out after five seconds so an unavailable server cannot hang the command indefinitely. An invalid optional remote URL marks sync failed while the interaction remains saved locally and the wrapped CLI still runs. Current limitation: replacing the remote database behind the same URL is not detected, and last-push/pull status times are global across targets.
 
 ---
 
-## 11. Database
+## 10. Database
 
 **Location:** `~/.prompt_history.db` (configurable via `ph config set db-path`)
 
@@ -351,12 +400,12 @@ Every `ph log` auto-pushes to remote if configured (fire-and-forget, never block
 ph vacuum              # compact DB
 ph cleanup             # remove short/trivial/duplicate prompts
 ph cleanup --retention # archive per retention policy
-ph embed-all           # (re)generate all embeddings
+ph embed-all           # generate vectors for prompts without embeddings
 ```
 
 ---
 
-## 12. Filter Pipeline
+## 11. Filter Pipeline
 
 Before saving, ph filters out:
 
@@ -375,16 +424,20 @@ ph config set filter-min-relevance 3
 
 ---
 
-## 13. Configuration (`~/.ph_config.json`)
+## 12. Configuration (`~/.ph_config.json`)
 
 | Key | Default | Description |
 |-----|---------|-------------|
 | `dbPath` | `~/.prompt_history.db` | SQLite database path |
-| `analyzeProvider` | `ollama` | LLM provider: `ollama` or `gemini` |
+| `analyzeProvider` | `ollama` | LLM provider: `ollama`, `gemini`, `openrouter`, or `mlx-serve` |
 | `ollamaUrl` | `http://localhost:11434` | Ollama server URL |
 | `ollamaModel` | `llama3.1:latest` | Analysis model |
 | `ollamaEmbedModel` | `nomic-embed-text-v2-moe` | Embedding model |
 | `geminiApiKey` | — | Gemini API key |
+| `openrouterModel` | — | Exact OpenRouter model ID |
+| `openrouterUrl` | `https://openrouter.ai/api/v1` | OpenRouter-compatible API root |
+| `mlxServeModel` | — | Exact MLX-Serve model ID |
+| `mlxServeUrl` | `http://127.0.0.1:11234/v1` | MLX-Serve API root (Parmenide SSH tunnel by default) |
 | `backgroundAnalysis` | `false` | Auto-analyze after each capture |
 | `filterMinLength` | `15` | Min prompt length to keep |
 | `filterMinRelevance` | `3` | Min relevance to keep (0=disable) |
@@ -394,12 +447,16 @@ ph config set filter-min-relevance 3
 | `retentionMinRelevance` | `3` | Archive prompts below this relevance |
 | `remoteUrl` | — | Remote ph server URL (or `PH_REMOTE_URL` env) |
 | `remoteApiKey` | — | Remote server API key |
-| `remoteLastPush` | — | Timestamp of last successful push |
-| `remoteLastPull` | — | Timestamp of last successful pull |
+| `remoteLastPush` | — | Global timestamp of last successful push |
+| `remoteLastPull` | — | Global timestamp of last successful pull |
+
+Provider API credentials are environment-only: `OPENROUTER_API_KEY` and
+`MLX_SERVE_API_KEY` (`GLB_OMLX_API_KEY` is a fallback). They are not written to
+`~/.ph_config.json`.
 
 ---
 
-## 14. Architecture
+## 13. Architecture
 
 ```
 Hook/Import → ph log → prompts table (FTS5 indexed)
@@ -432,14 +489,13 @@ src/
   filter/             # Capture-time filter pipeline
   mcp/server.ts       # MCP stdio server
   server/index.ts     # HTTP REST server (zero deps)
-  ui/                 # React/Ink TUI, including extracted filter policy and panel
   importer/           # Gemini/Claude/OpenCode/Codex history importers
 hooks/                # Shell scripts and plugins for AI tools
 ```
 
 ---
 
-## 15. Importing Existing History
+## 14. Importing Existing History
 
 ```bash
 # Import from Claude Code
@@ -463,7 +519,7 @@ ph import codex
 
 ---
 
-## 16. Versioning and Releases
+## 15. Versioning and Releases
 
 Use Conventional Commits to describe changes: `feat:` requests a minor release,
 `fix:` requests a patch release, and `BREAKING CHANGE:` requests a major release.