@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/docs/CONTEXT.md

@@ -0,0 +1,170 @@
+# Agent Sam context contracts
+
+Agent Sam treats context as a bounded evidence pack, not as a place to dump every available index, tool, file, or prior message.
+
+## Project rules
+
+Generated projects include a committed `.agentsamrules` file. It is the repository-level instruction surface, similar in spirit to `.cursorrules`.
+
+```text
+repo/
+├── .agentsam/config.json   portable project identity/defaults
+├── .agentsamrules          committed project instructions
+└── .agentsam/cli.json      machine/user preferences; gitignored
+```
+
+`loadProjectRules()` searches upward from the active cwd, hashes the source, and bounds loaded content before it can enter system context. The portable default ceiling is 24,000 characters; a host may choose a lower ceiling through its context budget.
+
+`.agentsamrules` is for durable repository instructions and conventions. It is not a place for secrets, account IDs, active runs, task state, model history, terminal sessions, or Merkle roots.
+
+## Result policy
+
+Every result-producing capability should have a result policy. Absence of a custom policy means the bounded SDK default:
+
+```json
+{
+  "max_items": 8,
+  "max_chars": 24000,
+  "detail": "excerpt"
+}
+```
+
+A caller may request less. Asking for more items, more characters, or a higher detail class requires the explicit `higher-detail` operation.
+
+Progressive detail is ordered as:
+
+```text
+metadata
+  ↓
+card
+  ↓
+excerpt
+  ↓
+range
+  ↓
+full
+```
+
+`normalizeResultPolicy()` enforces the ceiling. Built-in SDK tool cards inherit the bounded default rather than silently behaving as unlimited.
+
+## Context budget
+
+`createContextBudget()` derives per-class ceilings from the selected model's context window. The default operating ratios are:
+
+```text
+target active input    60%
+emergency hard line    85%
+```
+
+The remaining window is deliberate headroom for additional retrieval, tool iterations, reasoning, user input, and output.
+
+A budget owns separate ceilings for:
+
+```text
+system / project rules
+tool schemas
+retrieved evidence
+single file reads
+cumulative file reads per turn
+tool results
+```
+
+For example:
+
+```js
+import { createContextBudget } from '@inneranimalmedia/agentsam-sdk/context';
+
+const budget = createContextBudget({
+  windowTokens: 250_000,
+});
+```
+
+The resulting budget tracks both tokens and deterministic character ceilings.
+
+## Context items
+
+Portable context evidence uses the following shape:
+
+```ts
+interface ContextItem {
+  ref: string;
+  kind: 'file' | 'symbol' | 'memory' | 'tool_result' | 'repo' | 'artifact';
+  chars: number;
+  hash?: string;
+  priority: number;
+  content?: string;
+}
+```
+
+`resolveContext()` sorts candidate evidence by priority, applies kind-specific and cumulative limits, and returns only the selected items.
+
+`resolveProjectContext()` does the same while automatically loading `.agentsamrules` within the system-context ceiling.
+
+Every resolved pack includes a receipt:
+
+```json
+{
+  "chars": 18422,
+  "evidence_chars": 17769,
+  "system_chars": 653,
+  "estimated_tokens": 4606,
+  "sources_considered": 73,
+  "sources_included": 6,
+  "sources_deferred": 67,
+  "deferred_refs": []
+}
+```
+
+The existing knowledge `ContextPack` now uses the same receipt vocabulary for retrieval hits.
+
+### Consumed tool results
+
+`compactConsumedToolResult()` defaults to 4,000 characters for evidence that has already had its high-fidelity pass. It preserves the item ref/hash/priority so later turns can expand the source again instead of replaying the original dump.
+
+## Index law
+
+> An index is a retrieval substrate, never prompt content.
+
+The active prompt should receive a compact repository/index status plus selected evidence references. It should not receive an entire repository tree, symbol graph, embedding set, tool catalog, or hundreds of search results.
+
+Prefer evidence in this order whenever possible:
+
+```text
+exact structural evidence
+        ↓
+bounded lexical/search evidence
+        ↓
+semantic retrieval
+        ↓
+explicit larger range/full object only when required
+```
+
+## Tool discovery
+
+`searchToolCards()` supports cards-first discovery. It accepts a host/tool catalog and returns compact cards without full input schemas:
+
+```json
+{
+  "tool": "code.retrieve",
+  "summary": "Find symbols, callers, and semantic code matches.",
+  "risk": "read",
+  "required": ["query"],
+  "result_class": "bounded_evidence"
+}
+```
+
+A host can hydrate the selected tool's full schema only after selection. This keeps the portable contract compatible with small local catalogs and large hosted catalogs without injecting all schemas at turn zero.
+
+## Subagent handoff law
+
+A child agent should return a compact work receipt rather than its entire prompt/tool history:
+
+```text
+conclusion
+evidence refs
+changed files
+commands/tests
+uncertainty
+```
+
+The parent can expand an evidence ref when needed.

package/docs/LOCAL_OLLAMA.md

@@ -0,0 +1,58 @@
+# Local Ollama development kit
+
+AgentSam supports Ollama as an **opt-in local development runtime**. Ollama stays on the developer's machine; the `agentsam-sdk` Cloudflare Worker does not receive an Ollama binding and does not run an Ollama model at the edge.
+
+Canonical local defaults:
+
+```text
+OLLAMA_BASE_URL=http://127.0.0.1:11434
+OLLAMA_MODEL=qwen2.5-coder
+OLLAMA_EMBED_MODEL=mxbai-embed-large
+```
+
+## Setup
+
+```sh
+agentsam ollama setup
+```
+
+That writes the three values into the current project's `.env` and, when `.agentsam/config.json` exists, records only portable `models.local` metadata (provider + environment variable names). Machine URLs and chosen model values stay in `.env` / `.agentsam/cli.json`, not the committed project manifest. It does **not** silently install software or download models.
+
+Explicit opt-ins are available:
+
+```sh
+agentsam ollama setup --install
+agentsam ollama setup --start
+agentsam ollama setup --pull
+agentsam ollama setup --install --start --pull
+```
+
+Automatic installation uses Homebrew on macOS/Linux when available, or `winget` on Windows. Hosts without a supported local package manager receive a clear manual-install message instead of running an opaque remote install script.
+
+Model management:
+
+```sh
+agentsam ollama status
+agentsam ollama list
+agentsam ollama pull
+agentsam ollama pull qwen2.5-coder
+```
+
+`ollama pull` with no model pulls the configured chat and embedding models.
+
+## Local tunnel boundary
+
+For a remote AgentSam session, use the existing **user-hosted terminal tunnel** to execute `agentsam ollama ...` on the user's machine. The local CLI then reaches `127.0.0.1:11434` from that machine.
+
+```text
+remote agent
+    │
+    │ existing terminal tunnel
+    ▼
+local AgentSam CLI
+    │
+    └── http://127.0.0.1:11434
+         local Ollama process
+```
+
+This avoids exposing Ollama's HTTP API to the public internet and avoids pretending that a Cloudflare Worker can reach the developer's loopback interface. A deliberately configured HTTP tunnel can still be supplied with `--base-url`, but it is not the default product path.

package/docs/MERKLE.md

@@ -1,16 +1,16 @@
-# Merkle CLI and terminal explorer
+# Merkle CLI and interactive explorer
 
 ```bash
 agentsam merkle root .
 agentsam merkle root . --include dist
-agentsam merkle snapshot . --out .agentsam/merkle.json
+agentsam merkle snapshot . --semantic --out .agentsam/merkle.json
 agentsam merkle verify .agentsam/merkle.json
-agentsam merkle diff ./copy-a ./copy-b --tui
+agentsam merkle diff ./copy-a ./copy-b --interactive
 agentsam merkle inspect .
-agentsam tui merkle .
+agentsam merkle explore .
 ```
 
-The commands work on ordinary folders, including a mini prototype. Git, cloud accounts, databases, and containers are not required. Only `snapshot` writes files. There is no synchronization/restore command or background watcher in this version.
+The commands work on ordinary folders. Git, cloud accounts, databases, and containers are not required. Only `snapshot` writes files. There is no synchronization/restore command or background watcher in this version.
 
 ## Commands
 
@@ -21,50 +21,50 @@ The commands work on ordinary folders, including a mini prototype. Git, cloud ac
 | `verify <snapshot>` | Rescans the recorded root and reports unchanged, modified, added, and removed files/links. |
 | `diff <a> <b>` | Compares directories, snapshots, or one of each. No files are copied. |
 | `inspect [path]` | Prints the full tree/hash breakdown; also accepts a snapshot. |
-| `tui [path]` | Opens the keyboard-driven explorer. Alias: `agentsam tui merkle [path]`. |
+| `explore [path]` | Opens the keyboard-driven terminal explorer. |
 
-`--tui` also works with root, inspect, verify, and diff. Up/down or j/k select an entry; Enter/right expands a directory; left collapses it. `c` filters changes, `r` rescans, and q/Esc/Ctrl+C exits. The UI uses real scan counts, honors `NO_COLOR`, adapts to terminal resize, wraps the selected hash on narrow screens, and restores the cursor and terminal mode on exit. `r` does not update a saved baseline. Failed rescans remain visible and exit as an error.
+`--semantic` works with root, snapshot, and directory inspection. It adds deterministic `agentsam-filemeta` package/system/category/layer metadata plus JavaScript/TypeScript AST symbols/imports while leaving the v1 content root unchanged. Semantic snapshots validate both roots when reloaded.
 
-With piped output or `TERM=dumb`, the TUI prints once and exits. `--json` always bypasses interactive mode. Root JSON contains `rootPath`, `rootHash`, `stats`, and `policy`; verify/diff JSON contains `equal`, roots, counts, and the changed entries. Inspect/snapshot output contains the full manifest (snapshot adds `output`).
+`--interactive` works with root, inspect, verify, and diff. Up/down or j/k select an entry; Enter/right expands a directory; left collapses it. `c` filters changes, `r` rescans, and q/Esc/Ctrl+C exits. The explorer uses real scan counts, honors `NO_COLOR`, adapts to terminal resize, wraps the selected hash on narrow screens, and restores cursor/terminal mode on exit. `r` does not update a saved baseline.
+
+With piped output or `TERM=dumb`, the explorer prints once and exits. `--json` always bypasses interactive mode. Root JSON contains `rootPath`, `rootHash`, `policyHash`, `stats`, and `policy`; with `--semantic` it also contains `metadataRoot`, `classifier`, and `semanticStats`; verify/diff JSON contains `equal`, roots, counts, and changed entries.
 
 Exit codes: **0** success/match, **1** differences, **2** invalid input/scan error, **130** interrupted non-interactive scan. Interactive quit after a completed comparison retains its match/difference exit code.
 
 ## Comparing machines and preserving baselines
 
-Copy a manifest to another machine, then explicitly select that machine's checkout:
-
 ```bash
-agentsam merkle verify ./baseline.json --root ./local-copy --tui
+agentsam merkle verify ./baseline.json --root ./local-copy --interactive
 ```
 
-Verification uses the saved include/exclude policy. Roots are independent of absolute paths, timestamps, permissions, and creation order. Matching roots mean the **included relative names, file bytes, and literal symlink targets** match, subject to SHA-256 collision resistance. Empty directories are omitted. Line endings, Unicode filename normalization, and symlink target spelling are not normalized.
+Verification uses the saved include/exclude policy. Content roots are independent of absolute paths, timestamps, permissions, and creation order. Permission `mode` may still be recorded as metadata and, when semantic enrichment is enabled, contributes to the separate metadata root.
 
-Snapshots are baselines, not signatures or attestations of who created them. Protect a trusted baseline separately. For a consistent scan, avoid editing the directory while hashing it; detectable changes/read errors fail the scan, but this is not an atomic filesystem snapshot.
+Snapshots are baselines, not signatures or attestations. Protect a trusted baseline separately. Avoid editing a directory while hashing it; detectable changes/read errors fail the scan, but this is not an atomic filesystem snapshot.
 
-Existing snapshot files are not overwritten without `--force`. Snapshot output is excluded from its own tree. The manifest records a custom output exclusion when necessary. Save multiple historical snapshots under `.agentsam/merkle/`, which is ignored by default:
+Existing snapshot files are not overwritten without `--force`. Snapshot output is excluded from its own tree. Save historical snapshots under `.agentsam/merkle/`, which is ignored by default:
 
 ```bash
 agentsam merkle snapshot . --out .agentsam/merkle/before.json
 agentsam merkle snapshot . --out .agentsam/merkle/after.json
-agentsam merkle diff .agentsam/merkle/before.json .agentsam/merkle/after.json --tui
+agentsam merkle diff .agentsam/merkle/before.json .agentsam/merkle/after.json --interactive
 ```
 
 ## Ignore rules
 
 Default ignored names: `.git`, `node_modules`, `dist`, `.DS_Store`. Default ignored root subtrees/files: `.agentsam/cache`, `.agentsam/merkle`, `.agentsam/merkle.json`.
 
-`--include dist` disables that default rule. Repeat `--include` for additional default rules. `--exclude generated` ignores that name at any depth; `--exclude assets/cache` ignores that exact relative subtree. Rules are literal paths, not globs or `.gitignore` patterns. Explicit exclusions take precedence. Comparing snapshots with different policies is refused; a directory compared with a snapshot uses the snapshot's policy.
+`--include dist` disables that default rule. Repeat `--include` for additional default rules. `--exclude generated` ignores that name at any depth; `--exclude assets/cache` ignores that exact relative subtree. Rules are literal paths, not globs or `.gitignore` patterns. Explicit exclusions take precedence.
 
-The scanner hashes symlink target strings without following them. Special files (sockets, pipes, devices), unrepresentable filenames, unreadable files, and directory depths over 256 produce errors instead of silently weakening the tree.
+The scanner hashes symlink target strings without following them. Special files, unrepresentable filenames, unreadable files, and directory depths over 256 produce errors instead of silently weakening the tree.
 
 ## Reusable Node library
 
 ```js
-import { buildMerkleTree, saveSnapshot, readSnapshot, diffTrees } from '@inneranimalmedia/agentsam-sdk/merkle';
+import { buildMerkleTree, readSnapshot, diffTrees } from '@inneranimalmedia/agentsam-sdk/merkle';
 
 const baseline = await readSnapshot('./baseline.json');
 const current = await buildMerkleTree('./checkout', { policy: baseline.policy });
 const comparison = diffTrees(baseline, current);
 ```
 
-The library is local filesystem tooling. It adds no Worker bindings, user/workspace identity, network calls, or package dependencies. The interoperable hash format is specified in [MERKLE_V1](../protocol/MERKLE_V1.md).
+The library is local filesystem tooling. It adds no Worker bindings, user/workspace identity, or network calls. The interoperable content hash format is specified in [MERKLE_V1](../protocol/MERKLE_V1.md), and semantic identity in [FILEMETA_V1](../protocol/FILEMETA_V1.md).

package/docs/PORTABLE_CONTEXT.md

@@ -44,13 +44,14 @@ For trusted operator/service calls, configure one secret:
 export AGENTSAM_BRIDGE_KEY='...'
 ```
 
-Optional base URL overrides:
+Canonical IAM/platform origin:
 
 ```bash
-export AGENTSAM_BASE_URL='https://agentsam.example.com'
-# AGENTSAM_CORE_URL and IAM_CORE_URL are also supported.
+export IAM_ORIGIN='https://agentsam.example.com'
 ```
 
+`AGENTSAM_BASE_URL`, `AGENTSAM_CORE_URL`, and `IAM_CORE_URL` remain compatibility-only read fallbacks during the migration window.
+
 Programmatic API:
 
 ```js

package/docs/PROJECT_CONFIG.md

@@ -0,0 +1,72 @@
+# `.agentsam/config.json` — portable project manifest
+
+`.agentsam/config.json` is the small committed handshake that tells Agent Sam what project it is operating in and which portable defaults apply. It is **not** a runtime journal.
+
+Current schema:
+
+```json
+{
+  "schema_version": 2,
+  "project": {
+    "name": "agentsam-sdk"
+  },
+  "repository": {
+    "id": "github:samprimeaux/agentsam-sdk",
+    "remote": "origin"
+  },
+  "product": {
+    "preset": null,
+    "features": [],
+    "capabilities": []
+  },
+  "defaults": {
+    "mode": "agent",
+    "profile": "default",
+    "runtime": "local",
+    "model": "auto",
+    "deploy_target": null
+  },
+  "merkle": {
+    "enabled": true,
+    "semantic": true,
+    "persistence": "auto"
+  },
+  "rules": {
+    "file": ".agentsamrules"
+  },
+  "knowledge": {
+    "config": ".agentsam/knowledge.json"
+  },
+  "local": {
+    "database": ".agentsam/data/agentsam.sqlite",
+    "schema": "db/schema.sql"
+  },
+  "sdk": {
+    "created_with": "2.5.0"
+  }
+}
+```
+
+## Ownership boundaries
+
+```text
+.agentsam/config.json       committed portable project identity + defaults
+.agentsamrules             committed repository instructions; bounded when loaded
+.agentsam/knowledge.json    repository index / retrieval configuration
+.agentsam/cli.json          local user's terminal/runtime/model preference; gitignored
+D1 / runtime stores         runs, plans, tasks, executions, model history, subagents
+Merkle snapshot store       filesystem evidence and snapshot lineage
+Git                         source-control authority
+```
+
+Do **not** add account/user/tenant/workspace identity, current run IDs, active task state, PTY/session/connection IDs, current Merkle roots, provider credentials, deployment receipts, model history, or subagent execution records to the project manifest.
+
+`repository.id` is the portable repository authority for Agent Sam surfaces. Existing `knowledge.json.repository_id` remains readable during migration, but when both files exist the IDs must agree. Git remote discovery is fallback/adoption evidence rather than a second persistent identity.
+
+For a repository already hosted on a known Git provider, IDs use the portable form such as `github:owner/repo`. Repositories without a provider identity receive a durable `local:<uuid>` ID.
+
+Project defaults are intentionally different from machine preferences. A project can say `defaults.model = "auto"`; a developer can independently prefer an Ollama model on one laptop in `.agentsam/cli.json` without changing the repository contract.
+
+## Project instructions
+
+Generated projects include `.agentsamrules` as the human-editable repository instruction surface. The manifest only points to it; the instructions themselves stay outside JSON so teams can maintain them like other repository documentation. Runtime loaders hash and bound the file before it enters context.

package/docs/RELEASES.md

@@ -1,10 +1,43 @@
 # `@inneranimalmedia/agentsam-sdk` release receipts
 
-**2.1.0 is published on npm and is the `latest` dist-tag.** The private identity workspace
-continues to ship through the root SDK exports and is not published separately.
+**2.6.0 is the current release candidate on `main`; it is not published yet.**
+The npm `latest` dist-tag is **2.5.0**. The private identity workspace continues to
+ship through root SDK exports and is not published separately.
+
+Release-candidate base: `2643c164b0a745d0772f1aa9808c03bbe3873c94`. The final tagged publish commit will be recorded
+here after release. Publishing remains manual and `prepublishOnly` runs
+`npm run verify:release`.
+
+## 2.6.0 candidate highlights
+
+- Interactive AgentSam now has persistent machine-local account/session identity with explicit `login`, `logout`, `whoami`, and `resume` flows.
+- `/models` and model-selection UX bind to the canonical model inventory v2 contract instead of maintaining a second CLI catalog.
+- Provider credentials and account BYOK resolution are scoped, source-aware, and reusable across interactive, deploy, and tunnel flows without storing secrets in project state.
+- Runtime receipts now model account-owned runs, provider usage, approvals, and terminal jobs with stable lineage and no tenant/workspace/user ownership aliases.
+- Cloudflare diagnostics, context economics, repository evidence, and security/indexing contracts accumulated after 2.5.0 are included in the same verified release lineage.
+
+## 2.5.0 highlights
+
+- `agentsam` is the interactive product entrypoint; renderer selection is internal, and live thinking/activity scenes now run automatically around real Agent Sam work.
+- Portable project authority is `.agentsam/config.json` + `.agentsamrules`; local CLI preferences remain non-authoritative.
+- Public SDK seams include `/context`, `/tools`, `/indexing`, `/repository`, `/knowledge`, and `/skills`.
+- Context resolution is bounded by independent budgets and result policies; consumed tool results compact to evidence-preserving receipts.
+- Tool discovery is cards-first rather than full-schema catalog injection.
+- `RepositoryKnowledgeProvider` keeps local, hosted, and custom repository-intelligence implementations behind one contract.
+- Portable skills now include `agentsam-jr-dev`, `agentsam-app-fundamentals` (`quick-bytes`), and `agentsam-progression-guard` (`no-regress`), with deeper references loaded on demand and CLI discovery through `agentsam skills`.
+- Local model inventory/Ollama support remains preference-only and does not become a second routing authority.
+- Merkle/repository evidence, knowledge receipts, and project identity share the same portable repository identity.
+- `agentsam security scan` now combines OSV/dependency evidence with Merkle-bound AST execution trust-boundary contradictions; `agentsam inspect` exposes the same bounded analysis and mechanical repair actions.
 
 | npm version | Published (UTC) | IAM git SHA (40) | Notes |
 |-------------|-----------------|------------------|-------|
+| 2.6.0 | _(pending)_ | _(tag at publish)_ | Release candidate; interactive model/session SSOT and account-scoped runtime receipts. |
+| 2.5.0 | 2026-09-11T21:27:11.516Z | `da28623dc4808025b77605ed09aa16217b1db607` | Published package; registry `gitHead` receipt. |
+| 2.4.1 | 2026-09-11T05:45:03.622Z | `a256ababededd904da555e7898bc8afd753737d2` | Latest published package before 2.5.0. |
+| 2.4.0 | 2026-09-11T05:29:02.811Z | `81c8659977953bed53c2adb0a341ce7382be4794` | Published 2.4 line. |
+| 2.3.0 | 2026-09-11T05:09:40.046Z | `b517a720fb9b90f35c26f9ef87a84abd60d7ee01` | Published 2.3 line. |
+| 2.2.1 | 2026-09-11T04:08:18.238Z | `fefb587312df4fd4e177e839c5374c9621e7463d` | Published 2.2 patch. |
+| 2.2.0 | 2026-09-11T02:48:47.291Z | `06539ba3d3c2238b08201192dbec33d0e8df4b8a` | Published 2.2 line. |
 | 2.1.0 | 2026-09-09 (UTC, approx) | `a2570afdf1ae99542565fa3937abd7dbf95d121f` | Recon bounded-worker protocol: `protocol/recon/*` schemas, `python/agentsam_sdk/repository/recon` (packet/validate + `from_ripgrep`/`from_ast_grep` adapters), `agentsam recon pack\|validate` CLI (#27, #28). SDK-native change — no corresponding IAM platform-repo mirror SHA. |
 | 2.0.0 | 2026-09-03T02:21:44.857Z | `ed629869e701809d2bf4c61bd56d05d8d8d1e183` | Stable SDK 2.0.0; npm `latest`; identity bundled through root exports; release verification and dependency scan passed before publish. |
 | 2.0.0-alpha.identity.5 | _(pending npm)_ | `df064114eb7f8888f163e4a07dfddf19035b7169` | Password reset service, `registerFinalizeInboundOAuth`, IAM live proof. |

package/docs/REPOSITORY_INTELLIGENCE.md

@@ -10,7 +10,7 @@ python -m agentsam_sdk.repository.intelligence --repo-root ..
 python -m agentsam_sdk.repository.intelligence --repo-root .. --json
 ```
 
-The snapshot is deterministic evidence suitable for CLI/TUI presentation or downstream agent reasoning. Scores are relative within a snapshot, not quality grades:
+The snapshot is deterministic evidence suitable for CLI/terminal UI presentation or downstream agent reasoning. Scores are relative within a snapshot, not quality grades:
 
 - **density** — code/file concentration
 - **activity** — recent changed lines and commit touches

package/docs/REPOSITORY_KNOWLEDGE.md

@@ -0,0 +1,114 @@
+# Repository knowledge provider contract
+
+The SDK does not define the InnerAnimal production code index as the universal implementation.
+
+The npm package defines the portable capability contract. A host chooses how to satisfy it.
+
+```text
+Agent Sam repository understanding
+              │
+      ┌───────┼────────┐
+      │       │        │
+      ▼       ▼        ▼
+   Local    Hosted   Existing
+    SDK     AgentSam   system
+      │       │        │
+ lightweight  full    Sourcegraph /
+ local slice platform  Qdrant /
+                     custom service
+```
+
+## Provider surface
+
+A `RepositoryKnowledgeProvider` supplies:
+
+```text
+status()
+refresh()
+findSymbol()
+graph()
+retrieve()
+snapshot()
+```
+
+The SDK intentionally does not prescribe D1 tables, pgvector schemas, parser processes, queues, or embedding providers behind those calls.
+
+```js
+import {
+  createRepositoryKnowledgeClient,
+  describeRepositoryKnowledgeProvider,
+} from '@inneranimalmedia/agentsam-sdk/indexing';
+```
+
+A provider should describe actual capabilities rather than relying on stale prose metadata:
+
+```js
+describeRepositoryKnowledgeProvider({
+  provider: 'inneranimal-platform',
+  structure: 'tree-sitter',
+  lexical: true,
+  semantic: true,
+  graph: true,
+  history: true,
+  evidence: 'merkle',
+});
+```
+
+## User-facing concepts
+
+The terminal/UI should normally present only:
+
+```text
+Code map   where things are and how they connect
+Search     exact/lexical search + optional semantic search
+History    generations, Git evidence, and Merkle checkpoints
+```
+
+Parser technology, dimensions, vector tables, queue topology, generation internals, and storage adapters belong under advanced/debug surfaces.
+
+## Local SDK implementation
+
+The current SDK contains a portable/local knowledge slice with deterministic repository intelligence, lightweight JS/TS structural parsing, bounded chunks, local SQLite, optional Postgres/pgvector, optional embeddings, generations, and Merkle evidence.
+
+That is useful as a standalone implementation. It is not presented as the architecture of every Agent Sam host.
+
+## InnerAnimal production implementation
+
+The InnerAnimal platform is a separate host implementation with a broader code-intelligence pipeline: repository/index generations, a dedicated Tree-sitter parsing service, D1 structural nodes/edges, structural-first graph retrieval, semantic projections, and bounded hydration.
+
+That implementation should plug into the provider contract rather than be copied into npm.
+
+The same rule applies to the platform's logical RAG lanes (`code`, `schema`, `memory`, `docs`, `media`, `archive`), generic knowledge ingestion pipeline, and memory/experience systems. Those are specialized host infrastructure behind portable Agent Sam capability contracts.
+
+## Existing/custom systems
+
+A customer does not need to reproduce Agent Sam's internal storage model. They can implement the provider surface around their own system.
+
+Examples:
+
+```text
+Sourcegraph
+Elasticsearch
+Postgres / pgvector
+Qdrant
+Weaviate
+custom Tree-sitter service
+homegrown RAG / graph service
+```
+
+The common contract lets Agent Sam ask for status, refresh, symbols, graph evidence, retrieval, and snapshots while the implementation remains the customer's authority.
+
+## Evidence lineage
+
+Provider results should carry stable evidence references when possible:
+
+```text
+repository_id
+index generation
+Merkle snapshot_id / root hash
+Git revision
+path + span
+provider receipt
+```
+
+That lets context packs select evidence without copying the entire underlying index into the prompt.