@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.8

package/AGENTSAM.md

@@ -8,6 +8,35 @@ conventional client variable for that machinery, never a human identity. Prefer
 “AgentSam executes through SAM…” over anthropomorphic phrasing. Architecture SSOT:
 `docs/architecture/SAM_KERNEL.md`.
 
+## AgentSam system model: deterministic machinery + LLM augmentation
+
+AgentSam is deliberately **not** “an LLM with tools.” It is a layered system:
+
+- **Old-school AgentSam / SAM** owns deterministic perception and execution: repository discovery, manifests, Git/Merkle evidence, AST/indexes, capability probes, provider/runtime discovery, schemas/migrations, routing constraints, typed operations, receipts, and verification.
+- **LLM AgentSam** augments that machinery where language-model reasoning is valuable: interpreting intent, resolving ambiguity, planning across valid options, composing/translating content or code, explaining evidence, and proposing transformations.
+- Deterministic evidence is authoritative when it can answer a question reliably. Do not ask an LLM to rediscover or guess facts that SAM can inspect, derive, or prove.
+- LLM output never overrides authorization, runtime capability evidence, manifests, migrations, provider state, product contracts, or verification receipts.
+- Core product workflows should remain inspectable and recoverable without hidden model reasoning. Emit typed/versioned receipts and explicit state transitions instead of treating a transcript as system state.
+- A model may recommend an action; trusted machinery decides whether the action is available, authorized, correctly scoped, and verifiably complete.
+
+This division is a product requirement: **LLMs supercharge AgentSam; they do not become the source of truth that holds AgentSam together.**
+
+## Portability, resale, and repurposability law
+
+AgentSam machinery is only reusable when an unrelated user can install or instantiate it without inheriting the operator's machine, identity, credentials, infrastructure, or monorepo.
+
+- A reusable package, app, template, or pipeline must not require Sam/operator-specific usernames, device names, absolute paths, domains, account IDs, database IDs, repository names, credentials, customer content, or private infrastructure assumptions.
+- Customer differences belong primarily in manifests, portable schema/data, company/brand rows, themes, provider grants, capability configuration, and content — **not source-code forks**.
+- Product apps under `apps/` are independently extractable. Advertised CLI/app capabilities must work from the published/packed artifact outside this monorepo; repo-local `file:` escape dependencies are not a valid release mechanism.
+- If the SDK advertises a datastore, provider, runtime, or backend as supported, the corresponding contract and implementation must ship together. Do not mark placeholders or “follow-up” adapters as supported production paths.
+- Generic packages stay generic. Product/customer seeds, deployment bindings, brand values, and app-specific migrations belong with the consuming app or installation.
+- Authorization and resource visibility are always principal/installation scoped. **No authorized resource must never fall back to a platform-owner resource.**
+- Product readiness is proven, not asserted. Use current manifests, machine inspection, clean-room packaging/install tests, migrations, doctors, and receipts. If a product cannot pass its declared contract, mark it non-graduated/unavailable rather than advertising readiness.
+- Extend existing authorities and adapters instead of creating parallel copies of Identity, Database Studio, Settings, themes, registries, or runtime state.
+
+Product graduation and resale enforcement are defined in
+[`docs/PRODUCT_LIFECYCLE.md`](docs/PRODUCT_LIFECYCLE.md).
+
 ## Execution
 
 - Infer routine implementation details when repository evidence makes the answer clear; do not block on unnecessary questions.

package/README.md

@@ -114,6 +114,43 @@ 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.
 
+## Native Machine engine
+
+AgentSam's deterministic Rust perception engine is also published independently
+on crates.io. A clean machine does not need this repository checked out:
+
+```sh
+cargo install agentsam-machine-cli
+agentsam-machine --help
+agentsam-machine inspect . --json
+```
+
+The Cargo package is named `agentsam-machine-cli`; the installed executable is
+`agentsam-machine`. Standalone Cargo installs normally place it in `~/.cargo/bin`.
+
+The AgentSam npm CLI also owns one user-level Machine runtime shared by every
+repository on that computer:
+
+```sh
+agentsam machine status
+agentsam machine install
+agentsam machine update
+agentsam machine doctor
+```
+
+Managed versions live under `~/.agentsam/runtimes/machine/versions/<version>/`
+with `current.json` selecting the active version. AgentSam resolves this managed
+runtime before environment overrides, PATH binaries, or contributor source-tree
+fallbacks. Projects keep their own evidence/state under `<repo>/.agentsam/`; they
+do not install or choose a Machine executable.
+
+The crates.io distribution is self-contained: the published CLI resolves the
+published `agentsam-machine-core` crate by version. Deleting a local AgentSam SDK
+checkout does not affect a registry installation. Install/update are explicit and
+do not run just because a user enters a repository. Precompiled npm-native
+platform binaries remain a separate future distribution lane; the current managed
+installer uses Cargo and therefore requires a Rust/Cargo toolchain.
+
 ## Capability discovery and available kits
 
 The canonical machine-readable capability registry is available through `agentsam capabilities --json`

package/apps/README.md

@@ -2,6 +2,11 @@
 
 `apps/` is the development/authoring source of truth for runnable AgentSam product surfaces. Product apps are independently extractable and are intentionally **not** members of the SDK root npm workspace graph.
 
+**Lifecycle SSOT (validate → machine → prove → graduate → install):** [`docs/PRODUCT_LIFECYCLE.md`](../docs/PRODUCT_LIFECYCLE.md).  
+Use that doc for product map, graduation gates, scaffold vocabulary, old-school SAM + LLM layering, and how Identity/Desktop/Database lanes must stay extractable for resale.
+
+**Global agent/runtime law:** [`AGENTSAM.md`](../AGENTSAM.md). Product apps may specialize behavior through app-owned manifests/data, but they must not weaken the portability, principal-isolation, deterministic-evidence, or receipt-backed completion rules.
+
 ## Product app law
 
 Every deployable product app follows the same ownership boundary:

package/apps/cad-creator/README.md

@@ -462,7 +462,7 @@ If you want, I can also **put this directly into `SamPrimeaux/AgentSamCadCreatio
 CAD Creator is packaged independently from the core SDK as:
 
 ```text
-@inneranimalmedia/agentsam-sdk-cad-creator
+@inneranimalmedia/agentsam-cad-creator
 ```
 
 The package deliberately contains both:
@@ -477,13 +477,13 @@ It deliberately does **not** publish `reference/`, donor ZIPs/snapshots, `node_m
 Once published:
 
 ```bash
-npx @inneranimalmedia/agentsam-sdk-cad-creator
+npx @inneranimalmedia/agentsam-cad-creator
 ```
 
 or after installing it:
 
 ```bash
-npm install @inneranimalmedia/agentsam-sdk-cad-creator
+npm install @inneranimalmedia/agentsam-cad-creator
 npx agentsam-cad-creator --port 3000
 ```
 
@@ -500,7 +500,7 @@ The normal Design Studio shell loads first. The MuJoCo/robotics workspace remain
 ### Materialize an editable project
 
 ```bash
-npx @inneranimalmedia/agentsam-sdk-cad-creator scaffold ./my-cad-app
+npx @inneranimalmedia/agentsam-cad-creator scaffold ./my-cad-app
 cd ./my-cad-app
 npm install
 npm run dev

package/apps/cad-creator/shared/cad/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-cad-shared",
-  "version": "0.0.0",
+  "version": "2.6.7",
   "private": true,
   "type": "module",
   "exports": {

package/apps/client-cms-editor/AGENTS.md

@@ -1,12 +1,17 @@
 # Client CMS Editor workspace law
 
+- Product authority is the installable npm package `@inneranimalmedia/client-cms-editor`, not registry rows and not host-app vite aliases.
+- Donor behavioral authority: `studio-cms-editor` + `reference/harvest/plans/CMS-EDITOR-HARVEST.md`. Encode requirements in `acceptance/cms-parity.v1.json`.
 - This app is an independent workspace root. Keep one active lockfile at `apps/client-cms-editor/package-lock.json`.
 - Do not add its frontend/backend/shared packages to the SDK root workspace list.
-- Product-neutral AgentSam contracts/UI live in `packages/agentsam-contracts` and `packages/agentsam-workbench`.
-- Do not import from `apps/local-studio` or `apps/cad-creator`.
-- `shared/cms` owns pure CMS editor/publication/config contracts only; no React and no vendor runtime SDKs.
-- `backend/` is the portable host API/routing/preview bridge. Do not duplicate the canonical Inner Animal Media CMS server domain here.
-- Public CMS runtime must remain smaller than the authoring app. Do not ship Monaco, terminal, browser automation, auth-admin, or the whole AgentSam workbench to anonymous visitors.
-- `SESSION_CACHE` is never auth/session authority. `MY_CONTAINER` is never identity authority.
-- CMS AgentSam context must be explicit. Never scrape editor/site state silently.
+- Do not import from sibling host apps for runtime authority.
+- `shared/cms` owns pure CMS editor/publication/adapter/config contracts only; no React and no vendor runtime SDKs.
+- Persistence adapters implement `CmsEditorAdapter` (`shared/cms/src/adapter.ts`). Never treat localStorage as an authority or scaffold persistence choice.
+- `backend/` is a portable host bridge. Consumer `/api/cms/*` routes are one implementation of the adapter contract — not the product architecture.
+- Do not invent product resources (Worker binding labels, fixed account/database IDs, or deployment hostnames) inside this package.
+- Public CMS runtime must remain smaller than the authoring app. Do not ship Monaco, terminal, browser automation, auth-admin, or a full agent workbench to anonymous visitors.
+- Session caches and containers are never auth/identity authority.
+- CMS agent context must be explicit. Never scrape editor/site state silently.
 - Prefer structured/versioned section data for publication. Arbitrary executable editor HTML is not a public-content authority.
+- Heuristic is a stock starter pack (`starter-packs/heuristic`), not fake demo mode. Fake write short-circuits are forbidden.
+- Before calling a release good: `npm run verify:cms` must pass, then a fresh empty-folder install of the packed/published tarball must boot the editor.

package/apps/client-cms-editor/README.md

@@ -1,72 +1,100 @@
-# AgentSam Client CMS Editor
+# AgentSam Client CMS
 
-Authoring/control application for AgentSam CMS. This directory is a self-contained npm workspace root inside the SDK repository and is intentionally **not** part of the SDK root workspace graph.
+Reusable, white-label **website + CMS application kit** published as `@inneranimalmedia/client-cms-editor`.
 
-It was imported from `SamPrimeaux/inneranimalmedia` at the exact revision recorded in `IMPORT_PROVENANCE.json`. The donor browser editor is preserved, then normalized into explicit frontend/backend/shared package boundaries.
+A developer can scaffold a customer website, run it completely locally, browse the public pages and CMS, customize or import a theme, edit and publish through real local persistence, then connect identity/cloud/deployment providers without replacing the CMS or content model.
+
+**Authority order:** donor behavior → this npm package → adapters under the UX → registry receipts last.  
+See [`ALPHA.md`](./ALPHA.md) and [`acceptance/cms-parity.v1.json`](./acceptance/cms-parity.v1.json).
 
 ```text
-apps/client-cms-editor/
-├─ package.json
-├─ package-lock.json
-├─ frontend/                 CMS authoring UI + shared AgentSam workbench adapter
-│  ├─ package.json
-│  └─ src/
-├─ backend/                  host-neutral CMS API/routing/preview client bridge
-│  ├─ package.json
-│  └─ src/
-├─ shared/
-│  └─ cms/                   pure CMS editor/publication/binding/context contracts
-│     ├─ package.json
-│     └─ src/
-└─ reference/                immutable donor docs/lock/config for comparison only
+scaffold
+  ↓
+customer project
+  ├── public multi-page site (header / pages / footer)
+  └── protected CMS (pages · sections · blocks · media · theme · draft/preview/publish)
+        ↓
+same CmsEditorAdapter authority
 ```
 
-## Product boundary
-
-CMS Studio is the authenticated authoring/control product. It is **not** the public website runtime.
+## First-run (local before cloud)
 
-```text
-CMS Studio
-  ├─ pages / sections / themes / assets
-  ├─ AgentSam through @inneranimalmedia/agentsam-workbench
-  ├─ preview
-  └─ publish
-       ↓
-publication snapshot
-  ├─ D1 metadata
-  └─ WEBSITE_ASSETS (R2 content/media/theme artifacts)
-       ↓
-small public CMS runtime
-       ↓
-<public-host>/*
+```bash
+npx agentsam-cms create my-site --starter heuristic   # or blank | import --theme ./old-theme.zip
+cd my-site
+npx agentsam-cms dev
 ```
 
-The visitor-facing runtime should ship its normal frontend JavaScript through the normal static deployment bundle. R2 is for CMS-managed content/media and generated artifacts, not a replacement for the application bundle.
+Then browse:
+
+| URL | Surface |
+|-----|---------|
+| `http://localhost:4317/` | Published public home |
+| `http://localhost:4317/about` | Published interior page |
+| `http://localhost:4317/cms` | Protected CMS (local-dev principal by default) |
+
+No GitHub / Cloudflare / Supabase account is required to inspect or use the local product.
+
+### Starters
+
+| Starter | Meaning |
+|---------|---------|
+| **Heuristic** | Built-in multipage starter pack |
+| **Blank** | Empty durable site shell |
+| **IASF** | Stock Inner Animal Storefront (`--starter iasf`) |
+| **Import existing theme** | Directory or `.zip` → safe intake → ThemePack → `installStarterPack` |
 
-## Shared AgentSam rule
+Imported themes are normalized into the **same** `CmsStarterPack` contract Heuristic uses. The editor never parses ZIP/Liquid itself — import/refinery tooling does.
 
-CMS must not invent its own chat/browser/terminal/auth stack. `frontend/src/CmsAgentSurface.tsx` is a thin CMS adapter around `@inneranimalmedia/agentsam-workbench`; the host supplies an `AgentWorkbenchAdapter`, authenticated `AgentPrincipal`, and explicit CMS context. No fake AgentSam endpoint is provided by this app.
+## Architecture
 
-Identity remains outside the workbench. IAM establishes `accountId` / `authUserId`, application authorization resolves CMS access, and only then may optional browser/container execution be created.
+```text
+CmsEditor / public renderer
+        ↓
+CmsEditorAdapter
+
+LOCAL     →  ./sqlite-adapter  (Node / node:sqlite)
+CLOUD     →  D1 + R2 adapter
+OTHER     →  HTTP / custom
+```
+
+- Browser CMS UI does **not** import `node:sqlite`.
+- `./sqlite-adapter`, `./import`, and `./local` are Node/local-runtime surfaces.
+- Root package `engines` stay cross-runtime (`node >= 20`); only `./sqlite-adapter` documents the `node:sqlite` requirement.
 
-## Cloud binding contract
+## Auth boundary
 
-`shared/cms/src/cloudflare-bindings.ts` defines the capability-driven names. `DB` and `WEBSITE_ASSETS` are the CMS cloud baseline. `SESSION_CACHE` is cache-only and cannot be identity/session authority. `MY_CONTAINER` and `MYBROWSER` are optional execution capabilities and cannot establish identity.
+`/cms` is protected through a portable `CmsAuthHost` contract. Local scaffolds use an explicit local-development principal. Stock sign-in options for OAuth / CMS prebuild:
 
-## Canonical CMS backend
+- **Cloudflare** — `createStockCmsAuthHost('cloudflare')`
+- **Google** — `createStockCmsAuthHost('google')`
+- **Inner Animal Media** — `createStockCmsAuthHost('inneranimalmedia')`
+- **ChatGPT** — `createStockCmsAuthHost('chatgpt')` (Apps SDK hosted headers)
 
-This app's `backend/` is currently the portable API/routing/preview bridge that talks to `/api/cms/*`. The full canonical CMS domain still lives in the Inner Animal Media platform under `src/core/agentsam/cms/` at the donor revision. Do not copy that 166-file domain into this app and create a second authority. Its next extraction target is a product-neutral `packages/agentsam-cms/` family.
+Consumers wire OAuth/OIDC/their identity service without rebuilding route protection.
 
-## Development
+## Persistence
 
-From this directory:
+| Adapter | Role |
+|---------|------|
+| SQLite | desktop/offline authority via `./sqlite-adapter` |
+| D1 + R2 | cloud authority from **proven** OAuth resources |
+| HTTP / custom | consumer backend |
+| localStorage | UI chrome cache only — never scaffolded as authority |
+
+## Development / gates
 
 ```bash
+cd apps/client-cms-editor
 npm ci
-npm run typecheck
-npm test
 npm run build
-npm run dev
+npm run verify:cms
+# package + memory + sqlite durability + theme import + browser isolation + pack/bin
 ```
 
-Standalone dev requires explicit site context, for example `/?site=my-site`. In a real authenticated host, mount `CmsEditor` with the resolved site/project identity.
+Release (`private:false` required):
+
+```bash
+npm run verify:cms-release
+npm publish --tag alpha --access public
+```

package/apps/client-cms-editor/agentsam.app.json

@@ -2,28 +2,37 @@
   "schema": "agentsam.app.v1",
   "id": "client-cms-editor",
   "product_id": "cms",
-  "name": "AgentSam CMS Editor",
+  "name": "AgentSam Website + CMS Kit",
   "kind": "app",
   "package": "@inneranimalmedia/client-cms-editor",
-  "version": "0.1.0",
+  "version": "0.1.0-alpha.0",
+  "description": "Reusable white-label website + CMS kit: multipage public site, protected authoring dashboard, local SQLite, Heuristic/Blank/Import Theme starters, pluggable auth and deployment adapters.",
   "entrypoints": {
     "frontend": "./frontend",
     "backend": "./backend",
-    "cli": "./bin/agentsam-cms.mjs"
+    "cli": "./bin/agentsam-cms.js",
+    "public_renderer": "./local/public-renderer.ts",
+    "import_refinery": "./import/index.ts"
   },
   "capabilities": [
     "cms",
     "media",
     "templates",
-    "admin_content"
+    "admin_content",
+    "theme_import",
+    "local_storefront",
+    "auth_boundary"
   ],
   "provides": [
     "cms.editor",
+    "cms.public_renderer",
     "cms.templates",
     "cms.media.library",
+    "cms.theme_import",
     "workspace.panel"
   ],
   "surfaces": [
+    "public-site",
     "store",
     "theme-editor",
     "cms-editor",
@@ -31,23 +40,31 @@
     "media-library",
     "agentsam"
   ],
+  "starters": [
+    "heuristic",
+    "blank",
+    "import-existing-theme"
+  ],
   "runtime": {
     "local_preview": "ready",
     "source_scaffold": "ready",
-    "cloudflare": "ready",
+    "local_sqlite": "ready",
+    "theme_import": "ready",
+    "cloudflare": "adapter-ready",
     "github": "source-ready",
     "browser": true,
     "local": true
   },
   "commands": {
-    "preview": "agentsam-cms",
+    "create": "agentsam-cms create <directory> --starter heuristic|blank|import",
+    "dev": "agentsam-cms dev",
+    "import_theme": "agentsam-cms import-theme <source> --out <dir>",
     "doctor": "agentsam-cms doctor",
-    "scaffold": "agentsam-cms scaffold <directory>",
     "info": "agentsam-cms info"
   },
-  "bin": "bin/agentsam-cms.mjs",
+  "bin": "bin/agentsam-cms.js",
   "install": {
-    "command": "agentsam app scaffold client-cms-editor",
+    "command": "agentsam-cms create",
     "selector": "client-cms-editor",
     "paths": [
       "/install/cms",

package/apps/client-cms-editor/backend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inneranimalmedia/agentsam-cms-backend",
-  "version": "0.1.0",
-  "private": true,
+  "version": "2.6.7",
+  "description": "Internal CMS backend bridge (bundled into @inneranimalmedia/client-cms-editor \u2014 not published separately).",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,9 +14,26 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@inneranimalmedia/agentsam-cms-shared": "0.1.0"
+    "@inneranimalmedia/agentsam-cms-shared": "2.6.7"
   },
   "devDependencies": {
     "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamPrimeaux/agentsam-sdk.git",
+    "directory": "apps/client-cms-editor/backend"
+  },
+  "files": [
+    "src"
+  ],
+  "agentsam": {
+    "releaseIgnore": [
+      "worker",
+      "wrangler.jsonc"
+    ]
   }
 }