@inneranimalmedia/agentsam-sdk 2.4.1 → 2.5.0

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,34 @@
 # `@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.5.0 is the current release candidate on `main`; it is not published yet.**
+The npm `latest` dist-tag is **2.4.1**. The private identity workspace continues to
+ship through root SDK exports and is not published separately.
+
+Release-candidate base: `236afa84b553fb0d0109abe41939488945c4fc74`. The final tagged
+publish commit will be recorded here after release. Publishing remains manual and
+`prepublishOnly` runs `npm run verify:release`.
+
+## 2.5.0 candidate 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.5.0 | _(pending)_ | _(tag at publish)_ | Release candidate; full verification required immediately before publish. |
+| 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.

package/docs/SDK_WORKER.md

@@ -0,0 +1,86 @@
+# `agentsam-sdk` Cloudflare application
+
+The SDK repository root owns package/tooling concerns. Each deployable product under `apps/` owns its own runtime. For Local Studio, the production Cloudflare application is owned by `apps/local-studio/backend/`.
+
+```text
+agentsam-sdk/
+├─ package.json
+├─ package-lock.json
+├─ packages/...
+└─ apps/local-studio/
+   ├─ package.json
+   ├─ package-lock.json
+   ├─ frontend/package.json
+   ├─ backend/
+   │  ├─ package.json
+   │  ├─ wrangler.jsonc
+   │  ├─ worker/
+   │  │  └─ index.js        checked-in Worker authority
+   │  └─ server/            Nitro routes/runtime modules
+   └─ shared/agentsam/package.json
+```
+
+`backend/worker/index.js` is the stable Cloudflare entrypoint and imports the generated Nitro handler from `../../.output/server/index.mjs`. `backend/wrangler.jsonc` therefore points to `worker/index.js`; assets remain generated under `../.output/public`.
+
+```text
+main             = worker/index.js
+assets.directory = ../.output/public
+```
+
+Run installs from `apps/local-studio/` with its committed lockfile:
+
+```sh
+npm ci
+npm run build
+npm run cf:verify-output
+npm run cf:dry-run
+```
+
+Production uses only `https://agentsam.inneranimalmedia.com`; `workers_dev` is disabled. The SDK root has no production `worker/` or `wrangler.jsonc`.
+
+## Binding contract
+
+```text
+agentsam-sdk
+├─ DB                  -> inneranimalmedia-business
+├─ WEBSITE_ASSETS      -> agentsam-os-blueprint-content
+├─ AGENTSAM_WAI        -> Workers AI provider
+├─ EXECOS              -> execos service binding
+├─ PTY_SERVICE         -> iam-vpc VPC service
+├─ IAM_ORIGIN          -> https://inneranimalmedia.com
+├─ IAM_CLIENT_ID       -> public OAuth client id
+├─ IAM_CLIENT_SECRET   -> secret
+├─ AGENTSAM_SDK_KEY    -> secret
+└─ AGENTSAM_BRIDGE_KEY -> secret
+```
+
+Hosted model credentials are secrets: `XAI_API_KEY`, `OPENAI_API_KEY`, and `GEMINI_API_KEY`. Grok model inference is the `XAI_API_KEY` provider lane and is independent from the pre-wired Grok gate viewer identity/session system.
+
+`AGENTSAM_WORKER_ROLE` is not part of the SDK contract. `IAM_OAUTH_ISSUER` and `AGENTSAM_SDK_TOKEN` are SDK 2.5 migration-read aliases only; new configuration uses `IAM_ORIGIN` and `AGENTSAM_SDK_KEY`.
+
+## Ollama
+
+Ollama is local compute with two ways to reach it:
+
+```text
+CLI on developer machine
+  -> http://127.0.0.1:11434
+
+agentsam-sdk Worker
+  -> EXECOS service binding
+  -> explicit target=local + neutral cwd (`/`)
+  -> existing local execution/tunnel fabric
+  -> http://127.0.0.1:11434
+```
+
+There is no production `OLLAMA_BASE_URL` and no public Ollama hostname. `PTY_SERVICE` remains the lower-level VPC/PTY health lane; model execution goes through ExecOS rather than bypassing the dispatcher. Ollama commands are filesystem-independent, so the ExecOS cwd defaults to portable `/`; `OLLAMA_LOCAL_CWD` can override it when needed. Default local models are `qwen2.5-coder` for chat/code and `mxbai-embed-large` for embeddings.
+
+## Merkle persistence
+
+Semantic deployment snapshots use the logical `WEBSITE_ASSETS` binding and the provider-neutral `agentsam_fs_merkle_snapshots/` namespace. D1 indexes the snapshot row in `agentsam_fs_merkle_snapshots`; R2 stores the full document. Customer/generated Workers keep the same logical binding and may point it at their own selected storage.
+
+```text
+root_hash      = content identity
+policy_hash    = capture-scope identity
+metadata_root  = semantic/index identity
+```

package/docs/SECURITY.md

@@ -1,23 +1,33 @@
-# Dependency health and repair
+# Security scan and evidence-backed repair
 
-AgentSam checks npm dependency graphs against known OSV advisories, reads dependency warnings from install/build/deploy logs, and prepares verified repairs. A passing report means no findings in the supported checks; it is not proof that application code is secure.
+AgentSam combines dependency security evidence with a deterministic execution trust-boundary analysis. `agentsam security scan` checks the npm dependency graph against OSV **and** derives browser/server/shared execution facts from the repository's AST + Merkle semantic index.
+
+The core security rule is execution authority, not folder naming:
+
+> Code executed on hardware controlled by the user is untrusted client code. Code executed on hardware controlled by the application operator is the trusted server boundary.
+
+Anything sent to a browser can be read or modified. Client validation is useful UX, but authentication, authorization, ownership, prices, permissions, resource identity, and other security/correctness invariants must be re-verified by server-owned code. Secrets must never enter the browser dependency graph or public environment.
+
+A clean scan means no findings in the checks AgentSam could completely evaluate. It is **not** a proof that an application is secure, and the local AST analyzer currently covers JavaScript/TypeScript-family source. Hosted/custom repository knowledge providers may supply richer structural evidence for additional languages.
 
 ## Commands
 
 ~~~bash
 agentsam security scan --path .
 agentsam security check --path . --log /tmp/deploy.log --json
-agentsam security run --path . -- npm run build
+agentsam security run --path . --json -- npm run build
 agentsam security repair --path . --log /tmp/deploy.log --json
 agentsam security repair --path . --apply --verify verify --json
 ~~~
 
-The alias is "agentsam sca". Offline scanning lists dependency inventory but **always exits 2**, because no vulnerability lookup was performed. Use "node src/security/cli.mjs" inside this repository before dependencies are installed.
+The alias is `agentsam sca`. Offline scanning still performs the deterministic AST/Merkle trust-boundary analysis, but dependency vulnerability coverage is incomplete without OSV and therefore the overall command exits 2.
 
-The run command executes the exact argument vector after "--", without a shell, captures up to 8 MiB, and checks the resulting logs and lockfile. It preserves a failed command as a failed result. Logs are captured rather than streamed; receipts contain categories and line numbers, never raw log lines. Use it around an existing deployment command to make warnings visible, or around the build before deployment. It does not roll back a deployment already performed by that command.
+The `run` command executes the exact argument vector after `--`, without a shell, captures up to 8 MiB, and checks the resulting logs, dependency graph, and source trust boundary. It preserves a failed command as a failed result. Logs are captured rather than streamed; receipts contain categories and line numbers, never raw log lines. It does not roll back a deployment already performed by that command.
 
 ## What is checked
 
+### Dependencies and logs
+
 - Exact npm package-lock / shrinkwrap versions 1, 2 and 3, including nested dependencies, aliases, and workspaces. npm-shrinkwrap takes precedence.
 - Lockfile consistency with root/workspace manifest declarations and missing direct lock entries.
 - Full paginated OSV advisories, including IDs, aliases, severity evidence, and package-specific fixed releases. Withdrawn advisories are excluded.
@@ -25,41 +35,68 @@ The run command executes the exact argument vector after "--", without a shell,
 - Engine mismatches, peer conflicts, package-manager configuration warnings, audit summaries, and unclassified warnings.
 - Experimental runtime and pip/npm update notices are explicitly informational.
 
-An old audit summary can be resolved by a complete fresh scan. A deprecated-package log warning is resolved when the package is absent or its version changed and the new lock entry is not deprecated. Engine/peer/configuration/unclassified warnings stay actionable until reviewed at their source.
+### Execution trust boundary
 
-## Coverage and exit codes
+AgentSam's semantic Merkle pass records, for indexed JS/TS files:
 
-- **0:** complete and clean, already clean, or verified repair candidate.
-- **1:** unresolved findings, failed wrapped command, or manual action needed.
-- **2:** incomplete lookup/coverage, offline inventory, invalid input, or failed repair execution.
+- content hash and metadata root;
+- inferred/declared `execution_domain` (`browser`, `server`, `shared`, `test`, `tooling`, `framework`, `unknown`);
+- AST imports plus resolved local import edges;
+- names of `process.env` / `import.meta.env` accesses, never their values;
+- parser coverage/errors.
+
+The deterministic analyzer then follows the browser-reachable graph and reports contradictions such as:
+
+- browser code importing server-owned modules;
+- browser-reachable code importing Node/server-only runtime dependencies;
+- browser code reading private server environment names;
+- public environment names that look secret-bearing (`VITE_*`, `NEXT_PUBLIC_*`, etc. do **not** make a secret safe);
+- shared code depending on server environment state.
+
+Findings carry source/target hashes and the semantic `metadata_root`, so a repair can be tied to exact evidence rather than a prose guess. The same analyzer is embedded in `repository.snapshot`, so `agentsam inspect` and `agentsam security scan` do not maintain competing architecture models.
 
-The npm graph adapter does not pretend to parse pnpm, Yarn or Bun formats. Those managers produce an explicit incomplete result. Missing lockfiles, unresolved ranges, external file/Git dependencies, and mismatched workspace manifests also make coverage incomplete. A package.json-only scan cannot prove transitive coverage.
+Framework adapters are not guessed away. Exceptional layouts can declare deterministic `agentsam.classify` rules in the nearest package manifest. For example, a server-only DB module physically located in a frontend workspace can declare `execution_domain: "server"`; a generated router/server-function bridge can declare `framework`. Tests and known build-tool config files are separately classified instead of being mistaken for shipped browser roots.
 
-The scanner includes development and optional dependencies present in the lockfile. It queries OSV for each unique registry package name/version with four concurrent requests, a two-minute overall deadline, per-request timeouts, bounded response bodies, transient-status retries, and pagination-loop detection. Names and versions go to OSV; project source and log contents do not. No local credentials are sent to OSV. Unknown severities remain actionable and raw CVSS vectors are retained rather than guessed.
+## Mechanical repair contract
 
-## Repair contract
+Every trust-boundary finding has a deterministic repair action such as:
 
-Repair produces a plan by default. Applying requires an online complete scan, a clean Git repository root, and an existing npm verification script (verify, otherwise test, or explicit --verify SCRIPT). Automated repair currently requires macOS/Linux; Windows can scan and triage.
+- `move-server-call-behind-api-boundary`
+- `move-server-dependency-out-of-browser-graph`
+- `move-secret-to-server-runtime`
+- `split-shared-contract-from-server-implementation`
 
-The command creates a new agentsam/security-* branch and worktree under the system temporary directory, leaving the source checkout untouched. It:
+`agentsam security repair` includes these in its plan with the exact evidence refs. They are deliberately `automatic: false` today. Moving an application boundary can change behavior, so AgentSam does not blindly rewrite architecture and claim success.
+
+The reliable automatic-repair target is an isolated-worktree workflow: capture the Merkle/metadata baseline, apply a bounded recipe, rebuild/retest, create a fresh semantic snapshot, prove the contradiction disappeared without introducing new ones, and return a before/after receipt. Dependency repair already uses this isolated verified pattern; source-boundary repair will only become automatic when a recipe can satisfy the same proof standard.
+
+## Dependency repair
+
+Dependency repair produces a plan by default. Applying requires an online complete dependency scan, a clean Git repository root, and an existing npm verification script (`verify`, otherwise `test`, or explicit `--verify SCRIPT`). Automated dependency repair currently requires macOS/Linux; Windows can scan and triage.
+
+The command creates a new `agentsam/security-*` branch and worktree under the system temporary directory, leaving the source checkout untouched. It:
 
 1. Runs npm audit fix with package-lock-only, ignore-scripts, force=false and legacy-peer-deps=false.
 2. For deprecated dependencies, also runs npm update within existing declared ranges, with scripts disabled and no manifest saving.
 3. Rejects changes outside the selected lockfile and major-version changes at existing dependency paths.
 4. Runs a fresh npm ci with install scripts disabled, then the configured verification script.
-5. Rescans OSV and triages the original plus new install/verification logs.
+5. Rescans OSV, logs, and the AST/Merkle trust boundary.
 6. Returns a structured receipt with branch, worktree, step exit codes, before/after reports, and verified status.
 
-A verified candidate remains available for review/commit. Failed or unresolved candidates are retained for inspection and never marked fixed. Native packages needing lifecycle builds may fail verification; that remains visible rather than silently enabling install scripts. The existing verification script runs as trusted project code.
+A verified candidate remains available for review/commit. Failed or unresolved candidates are retained for inspection and never marked fixed. The command never force-pushes, publishes, deploys, executes instructions copied from logs/advisories, or treats an advisory's fixed version as proof of application compatibility.
 
-The command never uses force, edits dependency declarations, selects a major upgrade, suppresses warnings, executes instructions copied from logs/advisories, publishes, or deploys. Fixed versions listed by an advisory are evidence, not a promise they are compatible with your application. Breaking upgrades, package replacements, engine changes, and peer-range design decisions remain explicit follow-up work.
+## Coverage and exit codes
 
-## Installed automation in this repository
+- **0:** complete and clean, already clean, or verified repair candidate.
+- **1:** complete scan with unresolved findings, failed wrapped command, or manual action needed.
+- **2:** incomplete lookup/coverage, offline dependency inventory, invalid input, or failed repair execution.
 
-CI and the alpha publication workflow wrap npm installation with the dependency-health gate. The root prepublish hook also performs an online security scan after verification.
+The npm adapter does not pretend to parse pnpm, Yarn or Bun lock formats. Missing lockfiles, unresolved/external dependencies, and mismatched workspace manifests remain explicitly incomplete. An app workspace that links packages outside its own root can still receive a complete trust-boundary result while its dependency section reports that external package coverage must be scanned at the owning repository root.
+
+## Installed automation in this repository
 
-The dependency-maintenance workflow runs weekly and can be dispatched manually. It prepares and verifies a repair, then opens a PR when a verified lockfile change exists. It does not auto-merge or publish. It explicitly dispatches CI for its generated branch because GitHub-token-created PRs do not trigger another workflow automatically. An existing repair PR prevents duplicates. If repository settings block PR creation, the verified branch and compare URL remain in the failed run receipt for follow-up. Unresolved or incomplete runs fail visibly and upload a JSON receipt. GitHub repository settings must permit Actions to create pull requests.
+CI and publication workflows use the same `agentsam security` implementation. The root `prepublishOnly` hook runs `npm run verify:release`, which includes the online security scan. The dependency-maintenance workflow can prepare verified lockfile repairs but does not auto-merge, publish, or deploy.
 
-Other projects opt in by wrapping their existing build/install commands or calling the exported @inneranimalmedia/agentsam-sdk/security API. This SDK does not silently monitor unrelated deployments.
+Other projects can use the CLI or the exported `@inneranimalmedia/agentsam-sdk/security` API. Repository inspection also carries bounded trust-boundary analysis through `repository.snapshot`; observability/index evidence is not injected wholesale into model context.
 
 References: [OSV query API](https://google.github.io/osv.dev/post-v1-query/), [npm audit](https://docs.npmjs.com/cli/v11/commands/npm-audit/), [npm update](https://docs.npmjs.com/cli/v11/commands/npm-update/).