docs(api): align provider extension docs and contract test

Author: hanityx

CONTRIBUTING.md

@@ -60,22 +60,22 @@ For a deeper look at the backend layout and domain split, read [`docs/ARCHITECTU
 - TypeScript strict mode throughout
 - Zod for request validation (API)
 - React Query for data fetching (Web)
-- Web stays on React 18 while the Ink TUI currently tracks React 19
+- Web and the Ink TUI both target React 19
 - No hardcoded absolute paths — use `os.homedir()` / `path.resolve()` dynamically
 
 ### Safety Rules
 
 - **Never** delete local thread/session data without a token-verified flow
 - Keep backward compatibility for existing `/api/*` responses
 - Prefer incremental migration over large rewrites
-- Keep tracked docs and tracked scripts free of machine-specific paths and maintainer-only notes
+- Keep tracked docs and tracked scripts free of machine-specific paths and local-only notes
 
 ## Documentation
 
 Keep public docs focused on product behavior, public architecture, and reproducible setup. If your change touches tracked markdown:
 
-- No local paths, machine-specific traces, or internal codenames
-- No maintainer-only operating notes — those belong outside the tracked doc surface
+- No local paths, machine-specific traces, or non-public project labels
+- No local-only operating notes — those belong outside the tracked doc surface
 
 ## Reporting Issues
 

apps/api-ts/src/domains/providers/README.md

@@ -0,0 +1,82 @@
+# Provider Extension Guide
+
+This domain uses an in-repo, reviewed-source provider model. A provider is not
+loaded dynamically at runtime; adding one is a small code change with explicit
+registry, capability, and path-safety review.
+
+## Ownership
+
+- `adapters/`: provider-specific facts and optional probes.
+- `services/`: cross-provider engines for search, actions, transcripts, and
+  matrix data. Do not put provider-specific branches here unless the common
+  engine needs a new extension point.
+- `shared/file-roots.ts`: canonical provider root specs and scan root specs.
+- `shared/`: other provider-domain helpers for backup roots and fail-closed
+  path safety.
+- `capabilities.ts`: API-facing policy for which implemented providers are
+  searchable, transcript-readable, and cleanup-capable.
+- `registry.ts`: adapter registration and the `ProviderAdapter` contract.
+
+## Minimum Provider
+
+For a file-backed provider, add:
+
+1. `packages/shared-contracts/src/index.ts`
+   - Add the provider to `PROVIDER_REGISTRY` with its label and capabilities.
+2. `apps/api-ts/src/domains/providers/capabilities.ts`
+   - Add the id to `IMPLEMENTED_PROVIDER_IDS`.
+3. `apps/api-ts/src/domains/providers/registry.ts`
+   - Register it in `PROVIDER_ADAPTERS`.
+4. `apps/api-ts/src/domains/providers/shared/file-roots.ts`
+   - Add root specs and scan root specs.
+5. Provider tests or fixtures
+   - Add the smallest fixture or unit test that proves sessions are discovered
+     and parsed.
+
+Optional provider-specific files live under `adapters/<provider>/` only when
+they contain real provider-specific behavior, for example:
+
+- `roots.ts`
+- `title.ts`
+- `health.ts`
+- `transcript.ts`
+
+Do not create empty pass-through files just to match a folder template.
+
+This minimum path only proves file-backed session discovery. It does not prove
+full product support for DB-backed providers such as SQLite session stores.
+
+For a DB-backed provider, do not fake every session as the same database file
+path. Add the missing product contract first:
+
+- A stable session locator that includes the provider session id.
+- A transcript reader for the provider's storage shape.
+- API routing that can read transcripts by that locator.
+- UI selection/detail keys that do not collapse multiple sessions sharing one
+  backing database file.
+
+Until those pieces exist, a DB-backed provider can be treated only as a scan
+spike, not as a supported UI provider.
+
+## Guardrails
+
+- Keep provider-specific filesystem rules out of `services/`.
+- Keep shared pure utilities in `src/lib`; provider-domain helpers belong in
+  `domains/providers/shared`.
+- All destructive actions must flow through `services/actions`.
+- Do not add unsupported providers as hidden registry entries. If a
+  provider is not supported, leave it out of the registry.
+- Run `pnpm docs:provider-support` after changing capabilities.
+
+## Verification
+
+Run the nearest checks after adding a provider:
+
+```bash
+pnpm --filter @threadlens/shared-contracts test
+pnpm --filter @threadlens/api test -- src/domains/providers/provider-extension-contract.test.ts
+pnpm qa:provider
+```
+
+Use `provider-extension-contract.test.ts` as the first failure to read when a
+new provider is only partially wired.

apps/api-ts/src/domains/providers/probe.test.ts

@@ -12,7 +12,7 @@ describe("provider probe helpers", () => {
     expect(inferSessionId("/tmp/12345678-1234-1234-1234-1234567890ab.json")).toBe(
       "12345678-1234-1234-1234-1234567890ab",
     );
-    expect(inferSessionId("C:\\Users\\hwan\\.codex\\sessions\\win-session.jsonl")).toBe(
+    expect(inferSessionId("C:\\Users\\example\\.codex\\sessions\\win-session.jsonl")).toBe(
       "win-session",
     );
   });

apps/api-ts/src/domains/providers/provider-extension-contract.test.ts

@@ -0,0 +1,82 @@
+import {
+  getProviderCapability,
+  PROVIDER_IDS,
+} from "@threadlens/shared-contracts";
+import { describe, expect, it } from "vitest";
+import {
+  IMPLEMENTED_PROVIDER_IDS,
+  listProviderActionProviderIds,
+  listProviderIds,
+  listSearchableProviderIds,
+  listTranscriptReadableProviderIds,
+} from "./capabilities.js";
+import {
+  getProviderAdapter,
+  listProviderAdapters,
+  PROVIDER_ADAPTERS,
+} from "./registry.js";
+import { providerRootSpecs } from "./path-safety.js";
+
+describe("provider extension contract", () => {
+  it("keeps shared contracts, implemented ids, and adapters in lockstep", () => {
+    expect(IMPLEMENTED_PROVIDER_IDS).toEqual(PROVIDER_IDS);
+    expect(listProviderIds()).toEqual([...IMPLEMENTED_PROVIDER_IDS]);
+    expect(Object.keys(PROVIDER_ADAPTERS)).toEqual([...IMPLEMENTED_PROVIDER_IDS]);
+    expect(listProviderAdapters().map((adapter) => adapter.id)).toEqual([
+      ...IMPLEMENTED_PROVIDER_IDS,
+    ]);
+  });
+
+  it("wires every implemented provider to a labeled adapter and root specs", () => {
+    for (const provider of IMPLEMENTED_PROVIDER_IDS) {
+      const capability = getProviderCapability(provider);
+      const adapter = getProviderAdapter(provider);
+
+      expect(adapter, `missing adapter for ${provider}`).toBeDefined();
+      if (!adapter) continue;
+
+      expect(adapter.id).toBe(provider);
+      expect(adapter.label).toBe(capability.label);
+      expect(adapter.roots()).toEqual(providerRootSpecs(provider));
+      if (!adapter.scanSessions) {
+        expect(adapter.roots().length, `${provider} root specs`).toBeGreaterThan(0);
+      }
+      for (const spec of adapter.roots()) {
+        expect(spec.source, `${provider} root source`).toBeTruthy();
+        expect(spec.root, `${provider} root path`).toBeTruthy();
+        expect(Array.isArray(spec.exts), `${provider} root extensions`).toBe(true);
+      }
+    }
+  });
+
+  it("derives route policy lists from shared provider capabilities", () => {
+    const expectedSearchable = IMPLEMENTED_PROVIDER_IDS.filter((provider) => {
+      const capability = getProviderCapability(provider);
+      return (
+        capability.search_scope_visibility === "public" &&
+        capability.read_sessions &&
+        capability.analyze_context
+      );
+    });
+    const expectedTranscriptReadable = IMPLEMENTED_PROVIDER_IDS.filter(
+      (provider) => getProviderCapability(provider).read_transcript,
+    );
+    const expectedActionable = IMPLEMENTED_PROVIDER_IDS.filter((provider) => {
+      const capability = getProviderCapability(provider);
+      return capability.safe_cleanup || capability.hard_delete;
+    });
+
+    expect(listSearchableProviderIds()).toEqual(expectedSearchable);
+    expect(listTranscriptReadableProviderIds()).toEqual(expectedTranscriptReadable);
+    expect(listProviderActionProviderIds()).toEqual(expectedActionable);
+  });
+
+  it("keeps destructive action capabilities fail-closed", () => {
+    for (const provider of IMPLEMENTED_PROVIDER_IDS) {
+      const capability = getProviderCapability(provider);
+      if (capability.hard_delete) {
+        expect(capability.safe_cleanup, `${provider} hard_delete requires safe_cleanup`).toBe(true);
+      }
+    }
+  });
+});

apps/api-ts/src/domains/providers/services/search/row-search.test.ts

@@ -37,8 +37,8 @@ describe("searchConversationRows", () => {
   it("stops before loading later transcripts once metadata hits fill the result limit", async () => {
     const metadataRow = makeRow({
       display_title: "Unrelated title",
-      session_id: "rollout-2026-03-25T10-00-00-019d-obsidian-review",
-      file_path: "/tmp/obsidian-review.jsonl",
+      session_id: "rollout-2026-03-25T10-00-00-019d-project-notes-review",
+      file_path: "/tmp/project-notes-review.jsonl",
       mtime: "2026-03-25T10:05:00.000Z",
     });
     const transcriptRow = makeRow({
@@ -54,7 +54,7 @@ describe("searchConversationRows", () => {
           {
             idx: 0,
             role: "assistant",
-            text: "obsidian transcript fallback",
+            text: "project-notes transcript fallback",
             ts: "2026-03-25T10:00:00.000Z",
             source_type: "response_item.message",
           },
@@ -64,7 +64,7 @@ describe("searchConversationRows", () => {
 
     const result = await searchConversationRows(
       [metadataRow, transcriptRow],
-      "obsidian",
+      "project-notes",
       {
         limit: 1,
         transcriptLoader,
@@ -74,7 +74,7 @@ describe("searchConversationRows", () => {
     expect(result.results).toHaveLength(1);
     expect(result.results[0]).toMatchObject({
       match_kind: "title",
-      session_id: "obsidian-review",
+      session_id: "project-notes-review",
     });
     expect(transcriptLoader).not.toHaveBeenCalled();
   });

apps/api-ts/src/domains/providers/transcript.test.ts

@@ -19,7 +19,7 @@ afterEach(async () => {
 
 describe("buildSessionTranscript", () => {
   it("infers transcript session ids from Windows-style paths on POSIX runtimes", () => {
-    expect(inferSessionId("C:\\Users\\hwan\\.codex\\sessions\\win-transcript.jsonl")).toBe(
+    expect(inferSessionId("C:\\Users\\example\\.codex\\sessions\\win-transcript.jsonl")).toBe(
       "win-transcript",
     );
   });

apps/tui/src/cli.tsx

@@ -12,8 +12,8 @@ ${messages.cli.usageLabel}
 
 ${messages.cli.examplesLabel}
   threadlens-tui
-  threadlens-tui --query obsidian
-  threadlens-tui --query obsidian --results
+  threadlens-tui --query project-notes
+  threadlens-tui --query project-notes --results
   threadlens-tui --view sessions --provider codex
   threadlens-tui --view cleanup --filter risk
   threadlens-tui --locale ko

docs/ADDING_PROVIDER.md

@@ -5,7 +5,7 @@ session discovery, transcript parsing, search, diagnostics, archive, backup, and
 delete behavior, so new providers need both capability metadata and path-safety
 coverage.
 
-This guide describes the current internal extension path. It is not an external
+This guide describes the current in-repo extension path. It is not an external
 plugin API, and new provider code should stay in reviewed source until a separate
 security model exists.
 
@@ -44,12 +44,17 @@ folder under `apps/api-ts/src/domains/providers/`.
 
 Touch these files deliberately:
 
+- `packages/shared-contracts/src/index.ts` for the shared provider capability
+  source of truth
 - `apps/api-ts/src/domains/providers/registry.ts` for the explicit implemented
   adapter registration
 - `apps/api-ts/src/domains/providers/capabilities.ts` for route/search/report
   exposure policy
+- `apps/api-ts/src/domains/providers/shared/file-roots.ts` for canonical file
+  root specs and scan root specs
 - `apps/api-ts/src/domains/providers/adapters/<provider>/` for provider-specific
-  root discovery, title, transcript, or health evidence
+  root discovery, title, transcript, or health evidence when real
+  provider-specific behavior exists
 - `apps/api-ts/src/domains/providers/shared/` only for provider-neutral path/root
   helpers
 
@@ -74,22 +79,31 @@ export type ProviderAdapter = {
   label: string;
   roots(): ProviderRootSpec[];
   scanRoots?(): Promise<ProviderRootSpec[]>;
+  scanSessions?(): Promise<ProviderSessionCandidate[] | ProviderSessionRow[]>;
+  health?(): Promise<ProviderHealthEvidence>;
 };
 ```
 
 Do not duplicate capabilities in adapters. Capabilities must remain sourced from
 `getProviderCapability(adapter.id)`.
 
+Do not create empty `adapters/<provider>/transcript.ts`, `title.ts`, or
+`health.ts` files just to match a template. Optional adapter modules should
+exist only when they hold real provider-specific behavior.
+
 Providers that do not store sessions as standalone files should use a session
-locator model in later PRs instead of encoding provider-specific ids into fake
-file paths:
+locator model instead of encoding provider-specific ids into fake file paths:
 
 ```ts
 export type ProviderSessionLocator =
   | { kind: "file"; file_path: string }
   | { kind: "sqlite"; db_path: string; session_id: string };
 ```
 
+The locator type exists in the registry, but full DB-backed product support
+also needs transcript routing and UI selection keys that do not collapse
+multiple sessions sharing one backing database file.
+
 ## 3. Add Search and Transcript Support
 
 Most providers can use the existing JSON/JSONL transcript flow. Provider-neutral
@@ -158,6 +172,7 @@ At minimum, cover:
 
 Useful existing tests:
 
+- `apps/api-ts/src/domains/providers/provider-extension-contract.test.ts`
 - `apps/api-ts/src/domains/providers/path-safety.test.ts`
 - `apps/api-ts/src/domains/providers/parser-fixtures.test.ts`
 - `apps/api-ts/src/domains/providers/services/search/session-search.test.ts`
@@ -170,7 +185,7 @@ Useful existing tests:
 
 ## Adapter Direction
 
-The provider boundary is an internal provider adapter registry, not an external
+The provider boundary is an in-repo provider adapter registry, not an external
 plugin system.
 
 The adapter boundary starts with provider identity and root discovery. Keep
@@ -198,10 +213,7 @@ code unless a separate security model is designed.
 Before opening a provider PR:
 
 ```sh
-pnpm docs:provider-support
-pnpm --filter @threadlens/shared-contracts test
-pnpm --filter @threadlens/api test
-pnpm lint:deps
+pnpm qa:provider
 ```
 
 If provider UI copy changes are included, also run the relevant web or TUI tests.

docs/ARCHITECTURE.md

@@ -45,6 +45,7 @@ app/
       actions.ts
       matrix.ts
       search.ts
+      schemas.ts
       sessions.ts
       transcript.ts
     system/
@@ -57,10 +58,13 @@ app/
       forensics.ts
       open-folder.ts
       query.ts
+      schemas.ts
       state-actions.ts
       transcript.ts
+      types.ts
 domains/
   providers/
+    README.md
     adapters/
     services/
       actions/
@@ -71,6 +75,7 @@ domains/
     capabilities.ts
     constants.ts
     index.ts
+    provider-roots.ts
     registry.ts
     types.ts
   threads/
@@ -133,6 +138,16 @@ i18n/                localized message catalogs and locale loading
 - Provider services do not import provider-specific adapter modules directly; they go through the registry
 - Web, TUI, and desktop reuse the same API contracts
 
+## Provider Extension Model
+
+- `packages/shared-contracts/src/index.ts` is the shared provider capability source of truth
+- `domains/providers/capabilities.ts` narrows shared capabilities to api-ts implemented providers and route exposure
+- `domains/providers/registry.ts` registers reviewed-source adapters; ThreadLens does not load third-party provider code dynamically
+- `domains/providers/adapters/<provider>/` contains optional provider-specific behavior only when it is real behavior, not empty template files
+- `domains/providers/services/` contains cross-provider engines for search, actions, transcripts, and matrix data
+- `domains/providers/shared/` contains provider-domain root and path-safety helpers
+- `domains/providers/provider-extension-contract.test.ts` keeps shared ids, api implemented ids, adapters, roots, and route policy lists in lockstep
+
 ## Safety
 
 - Destructive actions use `dry-run -> confirm token -> execute`