@inneranimalmedia/agentsam-sdk 2.0.0 → 2.2.0

package/README.md

@@ -1,7 +1,8 @@
 # AgentSam SDK
 
-Portable SDK modules and CLI kits for creating local projects, inspecting repositories,
-indexing selected code, integrating identity, and maintaining dependencies.
+A deterministic-first application and agent toolkit: reusable repository, knowledge, integrity,
+security, identity, scaffolding, and delivery capabilities with optional AgentSam/LLM composition.
+CLI/TUI surfaces make those same primitives easy to use without making a model part of the implementation.
 
 **npm:** `@inneranimalmedia/agentsam-sdk` · **Source:** [GitHub](https://github.com/SamPrimeaux/agentsam-sdk)
 
@@ -24,19 +25,23 @@ or use local scaffolding/indexing.
 ## Create a local application
 
 ```sh
-agentsam init --name my-agent --yes
+agentsam create my-agent --preset fullstack
 cd my-agent
 npm install
 npm run smoke
-npm run dev
+agentsam dev
 ```
 
-This creates a Git repository, local SQLite database, environment templates, a Node API,
-and terminal commands. Local setup does not require an IAM account, cloud credentials,
-or a tunnel. `npm run status`, `npm run tui`, and `npm run pty` inspect or operate the
-generated project. A configured host/provider is required when selecting cloud operations.
+Presets are deterministic configuration bundles, not model prompts. Available starting presets are
+`fullstack`, `cms`, `prototype`, and `data`; they select an existing scaffold lane plus explicit feature
+and capability IDs. They do not silently provision cloud resources. The older
+`agentsam init --name my-agent --yes` scaffold entry point remains available for compatibility.
 
-Without a global install, use `npx @inneranimalmedia/agentsam-sdk init --name my-agent --yes`.
+The generated project contains a Git repository, local SQLite database, environment templates, a Node
+API, and terminal commands. Local setup does not require an IAM account, cloud credentials, a model, or
+a tunnel. Use `agentsam add <feature>` to record an explicit feature selection and its capability set.
+
+Without a global install, use `npx @inneranimalmedia/agentsam-sdk create my-agent --preset fullstack`.
 
 ## Index an existing repository
 
@@ -57,16 +62,23 @@ The JavaScript/TypeScript parser records syntactic relationships, not a fully re
 semantic call graph. Model/dimension changes create a distinct embedding profile.
 Python-backed snapshots capture repository composition and Git churn.
 
-## Available kits
+## Capability discovery and available kits
+
+The canonical machine-readable capability registry is available through `agentsam capabilities --json`
+and `@inneranimalmedia/agentsam-sdk/capabilities`. `agentsam inspect --json` runs the canonical
+read-only `repository.snapshot` composition primitive. See [Capabilities and presets](docs/CAPABILITIES.md).
 
 | Capability | Entry point | Guide |
 | --- | --- | --- |
+| Capability registry + presets | `agentsam capabilities`, `/capabilities`, `/presets` | [Capabilities](docs/CAPABILITIES.md) |
+| Canonical repository snapshot | `agentsam inspect --json`; `/repository` | [Capabilities](docs/CAPABILITIES.md) |
 | Git context and bridge client | `agentsam context --json`; `/git-context`, `/bridge-client` | [Portable context](docs/PORTABLE_CONTEXT.md) |
 | Identity contracts and adapters | `/identity`; `agentsam identity init` | [Identity](packages/identity/README.md) |
 | Repository knowledge | `agentsam index`, `search`, `repo`; `/knowledge` | [Knowledge](docs/portable-knowledge.md) |
 | File integrity | `agentsam merkle`; `/merkle` | [Merkle](docs/MERKLE.md) |
 | Dependency health and repair | `agentsam security`; `/security` | [Security](docs/SECURITY.md) |
 | Mini prototypes | `agentsam mini`; `/mini` | [Mini](docs/MINI.md) |
+| Recon bounded-worker packets | `agentsam recon pack\|validate` | [Recon](docs/RECON.md) |
 | Local containers | `agentsam dockerize`; `/dockerize` | [Dockerize](docs/DOCKERIZE.md) |
 | Background indexing service | Docker `knowledge_service`; `/knowledge-service-client` | [Knowledge service](docs/knowledge-service.md) |
 | Local status, DB, terminal UI | `agentsam status`, `db`, `tui`, `start-local` | [Terminal UI](docs/CLI_SHELL.md) |
@@ -92,11 +104,12 @@ authorizes its caller. Other local tooling uses Node APIs.
 
 ## Host integration and ownership
 
-The root `AgentSam` helper supplies routing/session primitives. Full model orchestration,
-tool execution policy, provider credentials, user authorization, and production storage
-belong to the consuming host application. The npm package alone does not provide a hosted
-autonomous agent platform. The old `scaffoldProject()` export is deprecated; use the local
-CLI scaffold command.
+Deterministic SDK capabilities remain useful without a model. The root `AgentSam` helper supplies an
+optional routing/session wrapper, while model orchestration, tool execution policy, provider credentials,
+actor/account authorization, workflow durability, approvals, jobs, and production application records
+belong to the consuming host application. Git/repository identity never proves actor authority, and the SDK
+does not create a second platform tools database. The old `scaffoldProject()` export is deprecated; use
+`agentsam create` or the local scaffold commands.
 
 This repository owns portable code once. Applications import it and provide adapters;
 they do not mirror SDK trees. [Ownership protocol](protocol/README.md).

package/docs/CAPABILITIES.md

@@ -0,0 +1,93 @@
+# Deterministic capabilities and product presets
+
+AgentSam SDK treats useful mechanics as deterministic capabilities first. Model/agent orchestration is an optional consumer of those capabilities, not a prerequisite for using them.
+
+## Contract
+
+A capability has a stable ID, kind, runtime, side-effect class, CLI/library entry point where applicable, and explicit model requirement. The canonical data SSOT is `protocol/capabilities/manifest.json`; `src/capabilities/manifest.js` is only its runtime reader. Presets follow the same rule through `protocol/presets/catalog.json`.
+
+```js
+import { getCapabilityManifest, repositorySnapshot } from '@inneranimalmedia/agentsam-sdk/capabilities';
+import { getPresetCatalog } from '@inneranimalmedia/agentsam-sdk/presets';
+```
+
+Raw machine-readable data is also shipped through the `/capability-manifest` and `/preset-catalog` package subpaths.
+
+```sh
+agentsam capabilities
+agentsam capabilities repository.snapshot --json
+```
+
+This registry is intended to drive CLI/TUI discovery, AgentSam/MCP tool selection, docs, verification, and workflow capability resolution. It is deliberately not a second hosted tools database.
+
+## repository.snapshot
+
+`repository.snapshot` is the first canonical composition primitive. It performs one read-only evidence collection pass over the current checkout and combines existing SDK mechanics:
+
+- Git resource identity and revision
+- Python repository intelligence
+- Merkle root and tree statistics
+- package/manifests
+- local knowledge/index generation when configured
+- last trusted local deployment receipt when available
+- a content hash over the collected evidence
+
+It does **not** call an LLM, mutate source, index the repository, provision cloud resources, or invent platform account/workspace authority.
+
+```sh
+agentsam inspect --json
+```
+
+```js
+import { repositorySnapshot } from '@inneranimalmedia/agentsam-sdk/repository';
+const snapshot = await repositorySnapshot({ cwd: process.cwd() });
+```
+
+The timestamp is not included in the content hash, so unchanged evidence produces the same `content_hash` and `snapshot_id`.
+
+## Optional AgentSam/LLM composition
+
+`repository.audit` is intentionally a different kind of manifest entry: an `agent_primitive`, not a deterministic evidence collector. It accepts a certified `repository.snapshot`, builds a bounded read-only evidence packet, and requires the caller to inject a `reasoner(packet)` function. The SDK does not choose a provider or model.
+
+```js
+import { createCapabilityAdapter, runRepositoryAudit } from '@inneranimalmedia/agentsam-sdk/agent';
+
+const audit = await runRepositoryAudit({
+  snapshot,
+  reasoner: async packet => myModelAnalyze(packet),
+});
+```
+
+The audit validator rejects mutation-oriented output keys such as jobs, executions, commits, deployments, mutations, and patches. A host Workflow may later turn validated findings/routes into plans or proposed jobs; that durable process remains outside the SDK.
+
+`createCapabilityAdapter()` converts the same canonical manifest into a small executable tool surface. Built-in `repository.snapshot` is available without a model; `repository.audit` becomes available only when a reasoner is supplied; other capability handlers can be injected explicitly by a host. This is the intended search-and-execute boundary rather than exposing every SDK command to every agent turn.
+
+## Product UX and power-user UX
+
+Product entry points are intentionally small:
+
+```sh
+agentsam create myapp --preset fullstack
+agentsam add knowledge
+agentsam dev
+agentsam inspect
+agentsam deploy
+```
+
+Power-user primitives remain available:
+
+```sh
+agentsam repo snapshot
+agentsam index ...
+agentsam search ...
+agentsam merkle ...
+agentsam recon ...
+agentsam security ...
+agentsam deploy-receipt ...
+```
+
+Presets select a coherent starting configuration; they do not silently provision remote services. `agentsam add` records an explicit feature selection in `.agentsam/features.json`; feature-specific commands continue to own real mutations until an additive handler can satisfy the complete feature contract safely.
+
+## Ownership boundary
+
+The SDK owns portable deterministic implementations and contracts. A host platform owns actor authorization, account ownership, workflow durability, approvals, job materialization, provider credentials, and application records. Portable repository capabilities must never infer actor authority from Git, workspace, or tenant labels.

package/docs/DEPLOY_RECEIPTS.md

@@ -0,0 +1,83 @@
+# Deployment receipts and checkpoints
+
+Agent Sam's Merkle tree answers a source identity question: **what exact file tree exists right now?**
+
+The deploy-receipt lifecycle adds a second question: **what changed since the last state we trusted?**
+
+The runtime checkpoint belongs under `.agentsam/deploy-merkle/` by default and is deliberately excluded from the captured source tree. It is cache/checkpoint state, not application source. Committing it would make deployment bookkeeping mutate Git and feed back into the next hash.
+
+## CLI
+
+```sh
+agentsam deploy-receipt capture . --project my-app --json
+# run any deployment provider here
+agentsam deploy-receipt success . --deployment-id dep_123 --worker-version worker_v1 --json
+```
+
+If deployment fails:
+
+```sh
+agentsam deploy-receipt failure . --deployment-id dep_123 --json
+```
+
+A successful finalize promotes `latest.snapshot.json` and `latest.receipt.json`. A failed finalize writes failure history but does **not** advance the trusted baseline.
+
+An external durable snapshot (R2, S3, GCS, artifact store, etc.) can be restored before capture and supplied explicitly:
+
+```sh
+agentsam deploy-receipt capture . \
+  --baseline /tmp/last-success.snapshot.json \
+  --baseline-source r2 \
+  --project my-app \
+  --json
+```
+
+Provider storage stays an adapter. The Merkle tree, diff, receipt contract, local checkpoint state, Git metadata, dirty-tree observation, and success/failure promotion semantics live in the SDK.
+
+## Programmatic API
+
+```js
+import {
+  captureDeployReceipt,
+  finalizeDeployReceipt,
+} from '@inneranimalmedia/agentsam-sdk/deploy-receipt';
+
+const capture = await captureDeployReceipt({
+  root: process.cwd(),
+  project: 'my-app',
+  baselineSnapshot: restoredSnapshotPath,
+  baselineSource: 'r2',
+});
+
+try {
+  const deployment = await deploy();
+  const completed = await finalizeDeployReceipt({
+    root: process.cwd(),
+    status: 'success',
+    deploymentId: deployment.id,
+    workerVersionId: deployment.versionId,
+  });
+  await persistSnapshotAndReceipt(completed);
+} catch (error) {
+  await finalizeDeployReceipt({
+    root: process.cwd(),
+    status: 'failed',
+  });
+  throw error;
+}
+```
+
+The same primitive is exported as `captureCheckpoint()` / `promoteCheckpoint()` for long-running agent work. That enables a loop to checkpoint a trusted tree, execute a batch, inspect the exact Merkle delta, run verification, and only promote the new checkpoint when the batch is accepted.
+
+## Receipt shape
+
+A capture includes compact metadata such as:
+
+- Git SHA, branch, repository remote, and dirty-tree state
+- current Merkle root and previous trusted root
+- added / modified / removed counts
+- exact changed paths (capped for receipt size)
+- file / directory / byte statistics
+- baseline provenance
+
+Full file trees remain Merkle snapshots. Deployment ledgers should store the compact receipt metadata rather than the complete manifest.

package/docs/RECON.md

@@ -0,0 +1,165 @@
+# Recon: bounded-worker harness (aka "MiniCodeScout")
+
+A cheap or local model (Ollama/Qwen-class, a mini-tier hosted model, whatever's
+cheapest that week) can be useful as a **reconnaissance subagent** — but only once
+the evidence handed to it is already disambiguated. Live investigation on the
+`feat/workflow-runtime-v2` worktree found the actual failure mode wasn't missing
+ceilings, it was mixed-signal evidence: a flat `rg 'workspace_id'` sweep conflates
+a JS member access (`authUser?.workspace_id`), an object key (`workspace_id: ctx.workspaceId`),
+and a SQL template literal (`` `AND workspace_id = ?` ``) into one undifferentiated
+hit list. That's why a Qwen-class mini guessed — not because it lacked a schema.
+
+**Current status:** the mini-worker step is benched for this sprint (decision:
+`workflows-v2:ollama-benched`; follow-up tracked as backlog P3). Deterministic
+search alone (`rg` and `ast-grep`, both installed on the primary dev machine) is
+already answering the questions that matter, faster and for free. This kit ships
+as reusable infra ahead of need — it isn't on the critical path for Workflows v2,
+and nothing here should be read as "go delegate to Ollama now." `ast-grep` stays
+recon-only: no `sgconfig.yml`, no `--fix`/`--update-all`/`--interactive` on target
+files until well after v2 lands — those are what turn it from search into a write
+action.
+
+## Where recon actually starts
+
+Recon is the last two stages of a longer pipeline, not the whole thing:
+
+```text
+lexical search (rg)         "where is this text?"          — do this first, always
+        |
+structural search (ast-grep)
+        |                   "where is this shape, and which kind?"
+        v
+   raw hits: {path, line, kind?}
+        |
+        v
+agentsam_sdk.repository.recon.from_matches(...)
+        |                   groups by file, windows context lines,
+        |                   chunks into packets of <=5 files each
+        v
+   ReconTaskPacket(s)   (protocol/recon/task-packet.schema.json)
+        |
+        v
+     mini worker          (only if/when actually delegated -- never given rg)
+        |
+        v
+   ReconFindingReport   (protocol/recon/finding-report.schema.json)
+        |
+        v
+agentsam_sdk.repository.recon.validate_report(...)
+        |
+        v
+     capable agent         (verifies, edits, git, tests, PR)
+```
+
+Hand-picked slices still work too — `build_task_packet()` takes an explicit slice
+list directly when you already know exactly which 5 files matter and don't have a
+raw hit list to chunk.
+
+## Rules the worker operates under
+
+- **One question, not a subsystem audit.** "Does this file still read
+  `workspace_id`?" — not "audit the workflow runtime."
+- **≤5 file slices per packet, supplied — never discovered.** The worker doesn't
+  run its own `rg`/`ast-grep`/`find`/`ls`; the controller already ran search and
+  chunked the results before the worker ever sees anything. "Do not give Qwen rg."
+- **≤2 follow-up reads**, each still inside the packet's ceilings.
+- **Read-only diagnostics only**, and only ones the controller pre-approved
+  (`allowed_diagnostics` in the packet) — `git status`/`diff`/`log`/`show`, a
+  syntax check, a single named test. Never `git add|commit|reset|push`, never a
+  migration, never a full build or deploy, never `ast-grep --fix`/`sg --update-all`
+  on the target files.
+- **No branch ownership.** The worker's only output is a `ReconFindingReport`. It
+  never calls `write_file` against the repository.
+- **Never guess.** If the supplied slices don't answer the question, the worker
+  returns `status: "needs_context"` with `reason` and `missing` — not a
+  fabricated finding. `validate_report` rejects any `answered` report that cites
+  a file outside the packet's slices, so a worker can't paper over a gap with
+  invented evidence either.
+- **A slice's `kind` (when present) is a controller-verified structural label,
+  not a hint the worker should second-guess.** `sql_string` and `member` are not
+  the same finding even when the literal text matches.
+
+## Where each half lives
+
+| Half | Module | Notes |
+| --- | --- | --- |
+| rg adapter | `agentsam_sdk.repository.recon.from_ripgrep` | Parses `rg --json` NDJSON into hits. No `kind` — lexical only. Runs no search itself. |
+| ast-grep adapter | `agentsam_sdk.repository.recon.from_ast_grep` | Parses `sg`/`ast-grep --json=compact` array output into hits, tagged with a caller-supplied `kind` (one invocation = one shape). Runs no search itself. |
+| Chunker | `agentsam_sdk.repository.recon.from_matches` | Takes hits from either adapter (or hand-built), groups by file, windows context lines, chunks anything over 5 files into multiple packets. |
+| Controller (hand-picked packets) | `agentsam_sdk.repository.recon.build_task_packet` | For when you already know the exact ≤5 files/lines — no hit list to chunk. |
+| Validator (gate reports) | `agentsam_sdk.repository.recon.validate_report` | Structural check + the "never guess" rule + citation check (findings can't reference files the worker was never given). Raises `ReportError`; callers must discard, not patch, a rejected report. |
+| Contracts | `protocol/recon/task-packet.schema.json`, `protocol/recon/finding-report.schema.json` | Provider-neutral; usable from the CLI, the MCP surface, or a Worker. |
+| CLI | `agentsam recon pack \| validate` (Node, thin passthrough) or `python -m agentsam_sdk.repository.recon pack \| validate` | Hand-picked slices only. Same `ToolInput`/`ToolResult` contract as every other `agentsam_sdk` tool on the Python side — read-only by default, gets a receipt. |
+
+This kit intentionally stops at the report. Model orchestration — which model
+answers a packet, retries, cost routing, whether delegation happens at all — is
+host policy, same as the rest of the SDK's "host integration and ownership"
+boundary in the root README. A future `bounded-mutation` contract (a worker
+allowed to perform one specific, proven-safe transform, e.g. "rename import path
+A → B") is a separate, narrower protocol, not an extension of recon's read-only
+contract. `ast-grep` structural classification (splitting hits by node kind) is a
+separate layer with its own hard rule — recon only, never `sgconfig.yml`/`--fix`
+on target files — and `from_ast_grep()`/`from_matches()` carry its `kind` labels
+through into packets without needing a schema change.
+
+## Example
+
+`from_ripgrep()` and `from_ast_grep()` parse the two tools' real output shapes directly
+-- no hand-rolled JSON parsing needed. `from_ast_grep()` takes a `kind` label because one
+`sg`/`ast-grep` invocation is one pattern or rule, i.e. one structural shape; `from_ripgrep()`
+never sets `kind` since lexical hits carry no structural classification on their own.
+
+```python
+import subprocess
+from agentsam_sdk.repository import recon
+
+def run(*args):
+    return subprocess.run(args, capture_output=True, text=True).stdout
+
+matches = []
+matches += recon.from_ast_grep(
+    run("sg", "-p", "$X.workspace_id", "-l", "js", "--json=compact",
+        "backend/workflows", "backend/http/workflows"),
+    kind="member",
+)
+matches += recon.from_ast_grep(
+    run("sg", "-p", "$X.workspaceId", "-l", "js", "--json=compact",
+        "backend/workflows", "backend/http/workflows"),
+    kind="member_camel",
+)
+matches += recon.from_ast_grep(
+    run("sg", "scan", "--inline-rules",
+        "id: sql-ws\nlanguage: JavaScript\nrule:\n  kind: template_string\n  regex: workspace_id",
+        "backend/workflows", "backend/http/workflows", "--json=compact"),
+    kind="sql_string",
+)
+
+packets = recon.from_matches(
+    ".",
+    question="Does this file still depend on removed workspace-scoped columns?",
+    matches=matches,
+    task_id_prefix="workflow-v2-runtime-audit",
+)
+# classified hits across N files -> packets of <=5 files each, ready to hand to a
+# capable model for direct classification, or to a delegated worker later. Files
+# with more than one kind in their hit set come back with slice.kind omitted --
+# genuinely mixed evidence is a real signal, not something to flatten.
+```
+
+Also usable from the shell directly for hand-picked slices, no Python needed:
+
+```sh
+agentsam recon pack --repo-root . --question "..." \
+  --slice backend/workflows/repository.js:1-180 --out /tmp/packet.json
+agentsam recon validate --packet /tmp/packet.json --report /tmp/report.json
+```
+
+`agentsam recon` is a thin passthrough to the same Python module (`python -m
+agentsam_sdk.repository.recon`), for hand-picked slices only -- `from_matches`,
+`from_ripgrep`, and `from_ast_grep` are Python-only since raw hit shapes vary by tool
+and don't have a stable CLI surface yet.
+
+See [`REPOSITORY_INTELLIGENCE.md`](REPOSITORY_INTELLIGENCE.md) for the git-level
+evidence layer (hotspots/churn) that can help decide *which* files to search in
+the first place, and [`protocol/README.md`](../protocol/README.md) (rule 6) for
+the read-only, no-hardcoded-identity law this module follows.

package/docs/RELEASES.md

@@ -1,11 +1,12 @@
 # `@inneranimalmedia/agentsam-sdk` release receipts
 
-**2.0.0 is prepared, not yet published.** See [stable release instructions](sdk-2.0-release.md).
-Add its publication receipt only after npm confirms success; this preparation does not
-publish the private identity workspace or create a `v2.0.0` release tag.
+**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.
 
 | npm version | Published (UTC) | IAM git SHA (40) | Notes |
 |-------------|-----------------|------------------|-------|
+| 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. |
 | 2.0.0-alpha.identity.4 | 2026-08-22 | `df064114eb7f8888f163e4a07dfddf19035b7169` | IAM auth portal sync: signup→`/api/auth/signup`, `company-branding.js`, preview stubs. SDK git `d7498ca`. |
 | 2.0.0-alpha.identity.3 | 2026-08-22 | `559bc37267f76790136004f5fa94a2bb3cd6a721` | `company` table + `GET/PATCH /api/company` branding SSOT. |

package/docs/portable-knowledge.md

@@ -12,7 +12,7 @@ agentsam search "snapshot integrity"
 agentsam index show
 ```
 
-Bare `agentsam init` detects an existing Git repository and offers a setup wizard. `agentsam init --name new-project` retains the scaffold workflow. Setup creates `.agentsam/knowledge.json` exclusively and preserves existing source/configuration. The config's `repository_id` is generated once; workspace identity is explicit, never inferred from a Git owner. Commit this non-secret config to share identity across checkouts. Use a distinct repository ID when cloning it for another customer.
+Bare `agentsam init` detects an existing Git repository and offers a setup wizard. `agentsam init --name new-project` retains the scaffold workflow. Setup creates `.agentsam/knowledge.json` exclusively and preserves existing source/configuration. The config's `repository_id` is generated once and is the portable knowledge identity. New configs do not require or create a workspace identifier. Legacy configs that already contain `workspace_id` remain readable and retain their previous cache/generation namespace for compatibility. Commit this non-secret config to share identity across checkouts. Use a distinct repository ID when the same source must represent a different repository corpus.
 
 Scope entries are literal relative files/directories, comma-separated on the CLI, not glob expressions. Supported AST languages are JS/JSX/TS/TSX including `.mjs`, `.cjs`, `.mts`, `.cts`; Markdown/MDX, SQL and JSON are bounded text chunks, not AST parsers. Imports, re-exports and call expressions are syntactic observations marked `resolved: false`, not a type-resolved cross-file call graph. Syntax errors abort publication.
 
@@ -36,7 +36,7 @@ Limits count unique uncached inputs and content characters, not total billable a
 ## Incremental and history guarantees
 
 - Structural parse cache keys include source content, language, parser version and chunking policy.
-- Vector keys include workspace/repository namespace, model, revision, dimensions, parameters, input-format version and actual chunk content. Paths/commit IDs are retrieval metadata, so a pure move reuses vectors.
+- Vector keys include the repository namespace, model, revision, dimensions, parameters, input-format version and actual chunk content. Legacy configs with `workspace_id` preserve their prior workspace-qualified namespace so existing cached vectors remain readable. Paths/commit IDs are retrieval metadata, so a pure move reuses vectors.
 - Scope expansion rechecks the complete selected inventory. Named scopes have separate active generations. Different customers/repositories do not share caches.
 - An unchanged run performs zero embedding requests. An edit embeds only changed chunks; changing the profile creates a separate embedding space.
 - A run stages completed cache work, rechecks source hashes, then atomically publishes a generation with compare-and-swap protection. Provider failure, invalid dimensions, concurrent publication or mid-run source edits leave the previous active generation intact.
@@ -59,14 +59,14 @@ This wraps the existing bundled Python repository-intelligence module (Python 3.
 ## Backend Postgres / Supabase
 
 ```sh
-agentsam init . --yes --include backend/feature --target production --workspace customer-workspace
+agentsam init . --yes --include backend/feature --target production
 # Supply AGENTSAM_DATABASE_URL through a secret manager.
 agentsam index setup-store
 agentsam index plan
 agentsam index run
 ```
 
-Production selects the storage destination; execution still runs from this checkout. Review [`postgres.sql`](../src/knowledge/stores/postgres.sql) before `setup-store`, which explicitly applies it to the configured database. Init/plan/search never migrate a database. Use a dedicated backend connection with TLS appropriate to your environment. The private `agentsam_knowledge` schema is not intended for browser access or Supabase's exposed REST schemas; tenant authorization belongs in the host. Workspace-qualified IDs provide isolation in queries, not authentication.
+Production selects the storage destination; execution still runs from this checkout. Review [`postgres.sql`](../src/knowledge/stores/postgres.sql) before `setup-store`, which explicitly applies it to the configured database. Init/plan/search never migrate a database. Use a dedicated backend connection with TLS appropriate to your environment. The private `agentsam_knowledge` schema is not intended for browser access or Supabase's exposed REST schemas; account/tenant authorization belongs in the host. Repository ID plus named scope isolates portable knowledge generations; it is resource identity, not actor authentication.
 
 SQLite stores cache entries plus immutable generation/observation payloads locally under `.agentsam/knowledge/`, excluded from Git. Postgres stores the same versioned facts in JSONB and embeddings in native pgvector, with exact cosine ranking restricted to the selected generation's vector keys. This first slice uses exact search, not an ANN index; large indexes need per-profile partitions/indexes and benchmarks. The unconstrained vector column permits multiple dimensional profiles, but queries never mix them. Retention/garbage collection is intentionally absent so initial history is preserved; configure a retention policy before large production backfills.
 

package/docs/sdk-2.0-release.md

@@ -1,6 +1,6 @@
 # AgentSam SDK 2.0.0 release
 
-Status: prepared for manual npm publication; no publish is performed by branch cleanup.
+Status: published to npm as `@inneranimalmedia/agentsam-sdk@2.0.0`; npm `latest` points to 2.0.0.
 
 ## Product boundaries
 
@@ -32,8 +32,8 @@ automatic retention, multi-user authorization and production routing remain host
 
 ## Changes from 1.9 and the identity alphas
 
-- The npm `latest` tag was 1.9.0 at preparation; the alpha tag was
-  2.0.0-alpha.identity.12. Version 2.0.0 was not present in the registry.
+- npm `latest` advanced from 1.9.0 to 2.0.0. The alpha tag remains
+  2.0.0-alpha.identity.12 for the final identity prerelease line.
 - Node 22.5+ is required. Python 3.10+ is required for Python repository intelligence;
   Docker is required only when actually building/running containers.
 - In an existing repository, `agentsam init` configures repository knowledge. Use
@@ -43,36 +43,34 @@ automatic retention, multi-user authorization and production routing remain host
 - Knowledge and Docker features from PRs #20 and #21 are integrated in main.
 - Publication runs the installed-tarball consumer proof, Python tests, and dependency scan
   in addition to the existing SDK, identity, bootstrap and package checks.
-- The legacy alpha workflow refuses stable versions. Stable npm publication stays manual.
+- The legacy alpha workflow refuses stable versions. Stable npm publication remains manual.
 
-## Publish from the clean main checkout
+## Publication receipt
 
-```sh
-cd /Users/samprimeaux/agentsam-sdk
-git status --short
-git pull --ff-only
-npm ci
-bash scripts/npm-publish-preflight.sh
-npm publish --tag latest --access public
+Version 2.0.0 was published on 2026-09-03 at `2026-09-03T02:21:44.857Z` from SDK git SHA
+`ed629869e701809d2bf4c61bd56d05d8d8d1e183`. npm recorded this integrity value:
+
+```text
+sha512-lXnBp8GR1iduKWxxHSRHSd9Q1fjTUZvX1UecwtS8xdDxMdZRd2BSHtDygm0OMNYchrtUP1nR6g0t3MqZTkE5HA==
 ```
 
-The `prepublishOnly` hook runs `npm run verify:release` before upload. This runs the SDK and
-identity suites, package/bootstrap checks, installed-tarball fixtures, Python tests and a
-complete dependency scan. The tests do not call embedding providers or production databases.
-If npm requests login or a one-time code, complete that in your terminal. Do not publish
-with `--workspaces`: identity and shell-kit workspaces remain private.
+The `prepublishOnly` hook ran `npm run verify:release` before upload. That verification ran
+the SDK and identity suites, package/bootstrap checks, installed-tarball fixtures, Python
+tests and the complete dependency scan. The private identity and shell-kit workspaces were
+not published separately.
 
-After a successful publish, verify the registry and record the receipt:
+Verify the live registry state with:
 
 ```sh
-npm view @inneranimalmedia/agentsam-sdk@2.0.0 version dist.integrity
+npm view @inneranimalmedia/agentsam-sdk@2.0.0 version gitHead dist.integrity
 npm view @inneranimalmedia/agentsam-sdk dist-tags --json
 npm install -g @inneranimalmedia/agentsam-sdk@2.0.0
 agentsam --version
 ```
 
-Record the actual publication date and SDK commit in `docs/RELEASES.md`; only then create
-the `v2.0.0` release tag. A published npm name/version cannot be overwritten.
+The publication receipt is recorded in `docs/RELEASES.md`. Git tag `v2.0.0` identifies the
+exact npm `gitHead`. A published npm name/version cannot be overwritten; subsequent package
+changes require a new version.
 
 ## Branch consolidation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Portable AgentSam SDK and CLI kits for local scaffolding, repository intelligence, incremental indexing, identity adapters, and verified dependency maintenance.",
   "type": "module",
   "main": "./src/index.js",
@@ -12,8 +12,15 @@
     "./dockerize": "./src/lib/dockerize.js",
     "./mini": "./src/lib/mini/index.js",
     "./merkle": "./src/lib/merkle/index.js",
+    "./deploy-receipt": "./src/lib/deploy-receipt/index.js",
     "./knowledge": "./src/knowledge/index.js",
     "./knowledge-service-client": "./src/knowledge/service/client.js",
+    "./capabilities": "./src/capabilities/index.js",
+    "./capability-manifest": "./protocol/capabilities/manifest.json",
+    "./repository": "./src/repository/index.js",
+    "./agent": "./src/agent/index.js",
+    "./presets": "./src/presets/index.js",
+    "./preset-catalog": "./protocol/presets/catalog.json",
     "./identity": "./packages/identity/src/index.js",
     "./identity/providers": "./packages/identity/src/providers/index.js",
     "./identity/providers/google": "./packages/identity/src/providers/google/index.js",

package/packages/identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk-identity",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "private": true,
   "type": "module",
   "description": "Identity module for @inneranimalmedia/agentsam-sdk (workspace — publish via root SDK)",

package/packages/identity/src/frontend/auth-portal/README.md

@@ -11,7 +11,7 @@ Pages copied **verbatim** from IAM `static/pages/auth/*` — reorganize only.
 | Colors | `:root { --auth-bg, ... }` | theme tokens — **no JS changes** |
 | OAuth labels | button text | HTML only |
 
-Phase 5 (`agentsam init identity` — copy portal + inject brand tokens) is not in the CLI yet. Today: edit HTML/CSS directly or use `portal.brand` at `createIdentityClient` init for programmatic apps; preview with `agentsam identity preview`.
+The CLI can now scaffold the reusable identity app surfaces directly with `agentsam identity init --name <project> --brand "App Name"`. This copies the portal, Worker adapter, and migrations into a standalone app layout. Use `portal.brand` at `createIdentityClient` init for programmatic configuration, or `agentsam identity preview` for the local preview server.
 
 ## Source map
 

package/packages/identity/src/index.js

@@ -17,6 +17,7 @@ import {
   listIdentityProviders,
   GoogleProvider,
   GithubProvider,
+  IamProvider,
   GcpProvider,
   EmailProvider,
 } from './providers/index.js';
@@ -34,6 +35,7 @@ export {
   listIdentityProviders,
   GoogleProvider,
   GithubProvider,
+  IamProvider,
   GcpProvider,
   EmailProvider,
 };