@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/docs/MERKLE.md

@@ -68,3 +68,7 @@ const comparison = diffTrees(baseline, current);
 ```
 
 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).
+
+## AutoRAG use
+
+AutoRAG consumes this package's content root and optional semantic metadata root as source evidence. During a code plan it compares those roots with the previous generation, reports changed paths, and reuses unchanged parsed chunks/vectors where their content identity still matches. Merkle is deterministic filesystem evidence; it is not a dependency graph, an AST graph, a vector index, or a replacement for Git history.

package/docs/PROJECT_CONFIG.md

@@ -57,10 +57,13 @@ Current schema:
 D1 / runtime stores         runs, plans, tasks, executions, model history, subagents
 Merkle snapshot store       filesystem evidence and snapshot lineage
 Git                         source-control authority
+knowledge generations       indexed evidence history; never mutable project config
 ```
 
 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.
 
+AutoRAG manages the existing `.agentsam/knowledge.json` authority. It may add a portable repository/project key and explicit lane/profile settings there; it does not create per-lane, retrieval, backend, or credential config files. `workspace_id` is legacy read compatibility only, not universal knowledge authority.
+
 `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.

package/docs/REPOSITORY_KNOWLEDGE.md

@@ -72,6 +72,8 @@ The current SDK contains a portable/local knowledge slice with deterministic rep
 
 That is useful as a standalone implementation. It is not presented as the architecture of every Agent Sam host.
 
+`@inneranimalmedia/agentsam-sdk/autorag` is the higher-level façade over that same engine. It performs discovery, recommends bounded source scopes, manages the existing knowledge config, selects explicit provider/backend lanes, and runs probes. It never becomes a second indexing runtime. The lower-level engine remains available through `@inneranimalmedia/agentsam-sdk/knowledge`.
+
 ## 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.

package/docs/THEME_REFINERY.md

@@ -0,0 +1,120 @@
+# Theme Refinery — Archaeology → Product Graph
+
+**Law:** discover ≠ promote · install ≠ activate · automation ≠ authority  
+**SSOT for registry:** live `inneranimalmedia-business` D1 (`agentsam_products` + `asset_relationships` + evidence/artifacts)  
+**SSOT for packages:** `agentsam-sdk` workspaces (`@inneranimalmedia/heuristic-theme`, `@inneranimalmedia/theme-*`)
+
+Python owns deterministic harvest/normalize/preview/QA. AgentSam owns interpretation. **Every meaningful product unit must reconcile into D1** — filesystem-only runs are incomplete.
+
+## Pipeline states
+
+```
+old scattered website
+        ↓ discover + fingerprint          → evidence snapshot (website/repository)
+        ↓ make portable                   → work/theme-harvest/<slug>/
+        ↓ make previewable                → preview/ + agentsam_artifacts
+        ↓ classify + document             → agentsam_products UPSERT (prototype)
+        ↓ normalize structure             → apps/<slug> (scaffolded)
+        ↓ map reusable features           → feature.v1 + asset_relationships
+        ↓ visual/product refinement       → AgentSam (preserve design, replace plumbing)
+        ↓ QA + screenshots + receipts     → quality_reports + evidence
+        ↓ promote                         → production (human authority)
+apps/<sellable-theme>  +  @inneranimalmedia/theme-<slug>
+```
+
+## Product unit kinds (`agentsam_products.kind`)
+
+| Kind | Use when |
+|------|----------|
+| `app` | Sellable site/APP (`insurance-site`) |
+| `theme` | Visual/design product or stock shell (`heuristic-theme`) |
+| `sdk-package` | npm boundary (`@inneranimalmedia/theme-insurance-site`) |
+| `section` / `block` | Reusable CMS pieces (also may write `cms_component_templates`) |
+| `ui-component` | Header/nav shells extracted for reuse |
+| `integration` | Provider adapters (Resend, Square, …) |
+| `service` | Worker/backend service |
+| `script` / `solution` / `collection` / `product` / `product-line` | As classified |
+
+**Status ladder:** `prototype` → `scaffolded` → `wired` → `production` (→ `deprecated`)
+
+UPSERT by stable `slug`. Never delete/recreate to refresh metadata.
+
+## D1 reconciliation (required)
+
+### 1. `agentsam_products` — canonical identity
+
+- Resolve `repository_id` from live `code_repositories` (never invent IDs).
+- Set `canonical_path` (e.g. `apps/insurance-site`, `packages/theme-insurance-site`).
+- Rely on existing triggers for `defined_in` → `code_repository`.
+- Provenance in `metadata` only (no secrets). See `protocol/theme-refinery/product-metadata.schema.json`.
+
+### 2. `asset_relationships` — topology
+
+Idempotent UPSERT on `(source_type, source_id, target_type, target_id, relationship_type)`.
+
+Preferred verbs already in use: `defined_in`, `depends_on`, `consumed_by`, `builds_shell_for`, `integrates_with`, `packaged_as`, `runtime_for`, `exposes_tool`, `provides_workflow`, `sourced_from`, …
+
+Example:
+
+```
+insurance-site --sourced_from--> (evidence / donor path hash)
+insurance-site --packaged_as--> @inneranimalmedia/theme-insurance-site
+insurance-site --depends_on--> theme.storefront.shell / cms contracts
+```
+
+### 3. `agentsam_evidence_snapshots` — point-in-time proof
+
+Fingerprint, intake, pre/post visual, link scans.  
+Product row = durable summary; snapshot = detailed evidence.
+
+### 4. `agentsam_artifacts` — durable previews/docs
+
+Screenshots, preview bundles, help exports. Link via relationships (`has_preview`, `documented_by` — extend vocabulary intentionally).
+
+### 5. `agentsam_quality_reports` — only when a real report artifact exists
+
+### 6. `cms_themes` vs product identity
+
+Style tokens → `cms_themes`. Sellable APP → `agentsam_products`. Link; do not substitute.
+
+### 7. `cms_component_templates`
+
+Only for extracted reusable sections/blocks — not whole sites.
+
+### 8. Discovery inputs (merge automatically)
+
+- `~/company-map/machine/projects.json` + `git-roots.json`
+- `~/IAM-Library/01_Template_Candidates`
+- live D1 `apps` (historical inventory — discovery/backfill only)
+- existing `agentsam_products` + `code_repositories`
+- explicit donor roots
+
+`apps` / `client_apps` are **not** the new SSOT. Backfill into `agentsam_products`.
+
+## CLI surface (target)
+
+```
+agentsam theme harvest <path>     # archaeology packet + evidence + product UPSERT (prototype)
+agentsam theme preview <slug>     # gallery-ready artifacts
+agentsam theme normalize <slug>   # proposed plan (scaffolded/wired)
+agentsam theme promote <slug>     # human-gated → production
+agentsam themes                   # status table from D1 + filesystem
+```
+
+## Reconciliation receipt
+
+Every run emits `ThemeRefineryReconciliationReceipt` (`protocol/theme-refinery/reconciliation-receipt.schema.json`):
+
+discovered / matched / registered / updated / unchanged products · repositories resolved · relationships · evidence · artifacts · quality reports · CMS themes/templates · tools/workflows linked · duplicates · promotions · failures.
+
+**Run incomplete if only files were written.**
+
+## Packages (current)
+
+| Package | Role |
+|---------|------|
+| `@inneranimalmedia/heuristic-theme` | Stock CMS `theme.storefront.shell` |
+| `@inneranimalmedia/theme-<slug>` | Installable gallery theme contracts |
+| `apps/theme-gallery-preview` | Proving surface / historical mounts — not the package SSOT |
+
+Preserve design, replace plumbing: old auth/email/uploads/CMS → current feature vocabulary.

package/docs/architecture/AGENTSAM_DISTRIBUTION_OWNERSHIP.md

@@ -0,0 +1,176 @@
+# AgentSam Distribution, Ownership, and Telemetry Boundaries
+
+## Principle
+
+One AgentSam ecosystem does not mean one giant package, one credential domain, one runtime, or one analytics signal.
+
+Keep these authorities distinct:
+
+- SDK/CLI — umbrella entry point, protocols, orchestration, discovery.
+- Products — things users independently install/open, such as Local Studio and CAD Creator.
+- Services — independently deployed backends such as agentsam-go-worker.
+- Machine runtime — one agentsamd installation per user machine where required.
+- InnerAnimalMedia infrastructure — InnerAnimalMedia-owned Cloudflare, D1/R2, Workers, ExecOS, MCP, Tail, VMs.
+- Customer/self-host infrastructure — resources owned by the customer's explicitly connected account.
+
+## Normal user vs self-host vs official release
+
+### Normal user
+
+    @inneranimalmedia/agentsam-sdk
+              │
+              ▼
+          AgentSam CLI
+          Local Studio
+              │
+       ┌──────┴─────────┐
+       ▼                ▼
+    agentsamd      official hosted
+    user machine       services
+
+Normal users do not need service source trees or InnerAnimalMedia infrastructure credentials.
+
+### Advanced self-host
+
+    installed @inneranimalmedia/agentsam-go-worker
+                    │
+                    ▼
+            Wrangler identity
+                    │
+                    ▼
+        explicit USER Cloudflare account
+                    │
+                    ▼
+             user's Worker/Container
+                    │
+                    ▼
+             local AgentSam registry
+
+A self-host operation never writes inneranimalmedia-business.
+
+### InnerAnimalMedia official release
+
+    clean maintainer source
+             │
+             ▼
+      explicit InnerAnimalMedia release guard
+             │
+             ▼
+      explicit InnerAnimalMedia CF account
+             │
+             ▼
+    official Worker/Container
+             │
+        healthy proof
+             │
+             ▼
+    inneranimalmedia-business
+    agentsam_products
+    asset_relationships
+
+The official registry path is not imported as the default meaning of deploy.
+
+## Cloudflare identity boundary
+
+Wrangler is the deploy authority. AgentSam uses wrangler whoami --json, requires an authenticated account, requires explicit selection when multiple accounts are available, binds the chosen account into the child process, and records only non-secret account metadata in receipts.
+
+Distributed packages never include InnerAnimalMedia Cloudflare credentials.
+
+## Repository/package boundary
+
+@inneranimalmedia/agentsam-sdk remains the umbrella package. Deployable or independently installable products/services can be their own packages.
+
+The Go service is:
+
+    @inneranimalmedia/agentsam-go-worker
+
+The SDK discovers that package instead of assuming:
+
+    <sdk install>/apps/agentsam-go-worker
+
+This lets a normal SDK tarball remain focused while preserving a single AgentSam user experience.
+
+## Local state boundary
+
+Installed packages are source artifacts, not mutable user state.
+
+Use:
+
+    <caller>/.agentsam/
+
+for build/deploy receipts, local product projections, and transient proof artifacts.
+
+Do not write runtime state into:
+
+    node_modules/@inneranimalmedia/...
+
+## Product/runtime boundary
+
+User-facing products should declare runtime requirements rather than bundle complete daemons.
+
+    Local Studio ──┐
+    CAD Creator ───┼──► one agentsamd ─► capability inventory
+    Ecommerce ─────┘
+
+Hosted services such as agentsam-go-worker remain services. agentsamd remains the user-machine execution runtime.
+
+## Distribution analytics: keep funnel stages separate
+
+Do not turn package installation into hidden database access.
+
+Measure distinct signals:
+
+    DISCOVERY
+      npm aggregate downloads
+      docs/site interest
+          ↓
+    ACTIVATION
+      AgentSam first run
+      Local Studio opened
+      agentsamd booted
+          ↓
+    ADOPTION
+      products/apps enabled
+      repositories registered
+          ↓
+    VALUE
+      successful runs
+      packages/deployments verified
+          ↓
+    RETENTION
+      returning active installations/accounts/projects
+          ↓
+    INFRA HEALTH
+      Workers
+      Go runtime
+      ExecOS
+      agentsamd
+      MCP
+
+Npm download counts are distribution metrics, not unique-user counts.
+
+Do not add a postinstall phone-home path. First-run/product telemetry should be disclosed/configurable and constrained to product facts. Do not collect home directories, working paths, repository names, git remotes, hostnames, usernames, command contents, credentials, or environment variables as activation telemetry.
+
+If an anonymous installation identifier is used, generate a random local UUID; never derive it from hardware identifiers.
+
+## Telemetry authorities
+
+Use separate authorities:
+
+- npm/registry data — aggregate package distribution.
+- AgentSam analytics ingestion service — validated activation/adoption/value events.
+- inneranimalmedia-tail — InnerAnimalMedia runtime/Worker observability where Cloudflare Tail is the appropriate primitive.
+
+Do not make inneranimalmedia-tail the install counter. Treat it as a registered infrastructure primitive in SAM's topology and assign it runtime-observability responsibilities deliberately.
+
+A future analytics ingestion path can normalize events from CLI, Local Studio, agentsamd, hosted services, npm metric collectors, and Tail into aggregate analytics without granting distributed clients direct D1 access.
+
+## Scale objective
+
+The purpose is not to collapse dozens of repositories and Workers into one monolith.
+
+The objective is to give every asset a known identity, capabilities, dependencies, health state, deployment receipt, ownership boundary, and protocol relationship so SAM can operate a large software estate systematically.
+
+Protect this rule:
+
+One authority per concept; multiple implementations/adapters where appropriate.

package/docs/architecture/AGENTSAM_GO_RUNTIME.md

@@ -0,0 +1,282 @@
+# AgentSam Go Runtime
+
+## Purpose
+
+Go is AgentSam's native deterministic machinery layer. It is reused by two different ownership surfaces:
+
+- agentsam-go-worker — an independently deployed hosted/self-host service.
+- agentsamd — the user-machine runtime that products can share.
+
+Those are not the same product. They should reuse protocol-compatible native core code without sharing deployment authority.
+
+The TypeScript/protocol layer remains canonical contract authority.
+
+## Current hosted-service topology
+
+    AgentSam / SAM
+          |
+          v
+    canonical runtime protocol
+          |
+          v
+    Cloudflare Worker
+          |
+          v
+      Go Container
+
+The Worker owns edge routing and deploy-time identity. The container owns native Go execution.
+
+Normal AgentSam users consume the official hosted service where appropriate. They do not need to deploy this Worker just to use AgentSam.
+
+## User-machine topology
+
+    Local Studio ──┐
+    CAD Creator ───┼──► agentsamd
+    Ecommerce ─────┘       |
+                           ├─ filesystem
+                           ├─ watcher
+                           ├─ Merkle
+                           ├─ jobs
+                           ├─ PTY/process
+                           └─ activity
+
+Products declare runtime capabilities. They do not each clone a complete daemon.
+
+## Contract authority
+
+TypeScript/protocol remains canonical. Go implements shared contracts.
+
+Consequences:
+
+- no Go-only public ErrorEnvelope,
+- no Go-only activity vocabulary,
+- no Go-only planning semantics,
+- no browser contract moves into Go,
+- shared behavior is judged by conformance fixtures.
+
+Rust/Tauri remains responsible for desktop-shell concerns such as folder selection, keychain, application lifecycle, updater, deep links, and launching/supervising agentsamd.
+
+## Current Go service capabilities
+
+The deployed service currently owns:
+
+- health/build identity,
+- runtime inventory,
+- capability inventory,
+- deterministic SHA-256,
+- deterministic static inspection,
+- canonical AgentSam ErrorEnvelope-compatible request failures.
+
+The Worker exposes edge health separately so operators can distinguish edge availability from native-container health.
+
+## Source and build identity
+
+Source identity must remain truthful across development and distribution.
+
+Maintainer checkout:
+
+    git:<commit-sha>
+
+Published service artifact:
+
+    npm:@inneranimalmedia/agentsam-go-worker@<version>
+
+Fallback only when neither authority is available:
+
+    tree:<deterministic-source-digest>
+
+The build receipt also records the deterministic source-tree digest.
+
+The local/native build proof requires:
+
+- go test ./...,
+- go vet ./...,
+- native binary build,
+- SHA-256 binary digest,
+- native process boot,
+- source identity match,
+- health/runtime/capabilities/hash/inspect probes,
+- canonical malformed-request ErrorEnvelope,
+- graceful shutdown.
+
+The Linux verification container receives the same intended source identity and must be linux/amd64 and nonroot.
+
+The live deployment is not accepted merely because Wrangler returned success. External edge and native health must report the intended source identity.
+
+## Distribution boundary
+
+The Go service is packaged independently:
+
+    @inneranimalmedia/agentsam-go-worker
+
+The SDK does not assume its own npm tarball contains apps/agentsam-go-worker.
+
+Installed-package discovery resolves the service package through Node package resolution. User state belongs under the caller's .agentsam directory; the package under node_modules remains source-only.
+
+## Cloudflare account authority
+
+Before any self-host or official live deployment AgentSam asks Wrangler for identity:
+
+    wrangler whoami --json
+
+The deploy path fails closed when authentication is missing, when no account is available, or when multiple accounts exist without an explicit selection.
+
+The chosen account is observable and bound into the Wrangler process with CLOUDFLARE_ACCOUNT_ID.
+
+No distributed package contains an InnerAnimalMedia production credential.
+
+## Self-host lifecycle
+
+Self-host is an advanced opt-in path:
+
+    agentsam go --cloudflare agentsam-go-worker \
+      --account <user-cloudflare-account-id> \
+      --yes
+
+The sequence is:
+
+    installed or development service source
+       |
+       v
+    source identity
+       |
+       v
+    Go tests + vet
+       |
+       v
+    native binary + digest
+       |
+       v
+    native boot/probes/shutdown
+       |
+       v
+    linux/amd64 nonroot container
+       |
+       v
+    container boot/probes/shutdown
+       |
+       v
+    explicit USER Cloudflare account
+       |
+       v
+    Wrangler deploy
+       |
+       v
+    Cloudflare deployment/version identity
+       |
+       v
+    external edge + native probes
+       |
+       v
+    deployment receipt
+       |
+       v
+    local AgentSam registry
+
+Self-host never mutates inneranimalmedia-business.
+
+## InnerAnimalMedia official-release lifecycle
+
+InnerAnimalMedia product registration is a separate authority:
+
+    AGENTSAM_INNERANIMALMEDIA_OFFICIAL_RELEASE=1 \
+      agentsam go --cloudflare agentsam-go-worker \
+      --official-release \
+      --account <iam-account-id> \
+      --yes
+
+Requirements:
+
+- maintainer/development source,
+- explicit InnerAnimalMedia release guard,
+- explicit InnerAnimalMedia Cloudflare account,
+- healthy live probes,
+- deployment/version identity,
+- only then remote agentsam_products and asset_relationships projection.
+
+The InnerAnimalMedia D1 adapter lives in official-registry.js specifically so generic self-host deployment does not import InnerAnimalMedia registration as a default side effect.
+
+## Dry run
+
+Dry run is:
+
+    agentsam go --cloudflare agentsam-go-worker \
+      --dry-run \
+      --account <cloudflare-account-id>
+
+It still performs Go build/probes, Linux container build/probes, Wrangler identity/account resolution, and Wrangler deploy --dry-run.
+
+It does not create a live deployment and does not mutate InnerAnimalMedia D1.
+
+Skip-deploy is a different explicit local-only mode and cannot be used as deployment proof.
+
+## Errors and recovery
+
+Go preserves native evidence when present, but public failures classify through AgentSam's canonical ErrorEnvelope.
+
+Recovery remains centralized in AgentSam. ErrorEnvelope feeds planRecovery / agentsam.recovery.v1 semantics used by other runtimes. Go does not own an independent retry brain.
+
+Unsafe writes with unknown side effects must reconcile before retry. Provider/model fallback follows shared semantic-compatibility rules.
+
+## Activity
+
+Native operations feed agentsam.activity.v1; Go does not create a separate event vocabulary.
+
+Near-term events include runtime.started, filesystem.read, filesystem.write, watcher.resync, merkle.updated, job.started, job.completed, and runtime.degraded. Studio Activity / Computational Hyperspace and the CLI in-flight TUI consume the same stream.
+
+## Graduation toward agentsamd
+
+The reusable native core should progressively own:
+
+    runtime/
+      workspace/
+      filesystem/
+      watch/
+      hash/
+      merkle/
+      jobs/
+      runtimeinfo/
+      health/
+
+Executables/adapters reuse that core:
+
+    cmd/server
+    cmd/agentsamd
+
+The same core can support Cloudflare Container, local daemon, and remote daemon execution. Deployment/auth/ownership adapters remain target-specific.
+
+## Conformance
+
+Where TypeScript and Go implement the same protocol, use the same fixtures.
+
+First conformance targets:
+
+- runtime response shape,
+- SHA-256 result,
+- ErrorEnvelope classification for invalid input,
+- path containment,
+- version conflict semantics.
+
+Then:
+
+- file-watch events,
+- Merkle roots/deltas,
+- workspace filesystem behavior,
+- cancellable job behavior.
+
+A language-specific reinterpretation of a canonical contract is a failure.
+
+## Next native capabilities
+
+After the deployed service seed remains boring and repeatable, graduate capabilities in this order:
+
+1. workspace filesystem behind workspace-fs.v1,
+2. native filesystem watcher,
+3. SHA/Merkle branch updates,
+4. runtime capability/health state,
+5. cancellable durable jobs,
+6. PTY coordination where it belongs.
+
+A* remains TypeScript-canonical until real workload measurements justify a native planner.
+
+See AGENTSAM_DISTRIBUTION_OWNERSHIP.md for package, credential, registry, and telemetry ownership boundaries.