@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/AGENTSAM.md

@@ -2,6 +2,12 @@
 
 This file defines stable behavior for AgentSam agents using the portable SDK. It is not account state, project state, a run log, or a replacement for repository-specific `.agentsamrules`.
 
+**Naming:** AgentSam is the product. **SAM** means **Systematic Autonomous Machinery** — the typed
+operation/execution spine (`sam.invoke`, modules, receipts). In docs and code, `sam` is the
+conventional client variable for that machinery, never a human identity. Prefer “SAM resolves…” /
+“AgentSam executes through SAM…” over anthropomorphic phrasing. Architecture SSOT:
+`docs/architecture/SAM_KERNEL.md`.
+
 ## Execution
 
 - Infer routine implementation details when repository evidence makes the answer clear; do not block on unnecessary questions.
@@ -70,6 +76,17 @@ This file defines stable behavior for AgentSam agents using the portable SDK. It
 See [Storage architecture](docs/architecture/STORAGE.md) for enforcement and
 the current compatibility boundary.
 
+## Application contract (APP identity)
+
+Portable product apps follow [`docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md`](docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md).
+
+- **APP** = installable product (`agentsam.app.json`, immutable kebab-case `APP.id`).
+- **Not** an APP merely because it is under `apps/`, deployable, or an npm package.
+- Runtime identity: `import APP from "./agentsam.app.json"` — never `const APP = "agentsam-…"`.
+- `.agentsam/app.json` is host/install state (`app_id`), not a second product definition.
+- Package, Worker, route, desktop, and service names are separate namespaces with explicit pointers.
+- Gate: `agentsam app validate` / `npm run guard:apps`.
+
 ## Model and run policy
 
 - Model, reasoning effort, service tier, budget, and permissions are runtime configuration, not hidden prompt instructions.

package/README.md

@@ -5,6 +5,21 @@ security, identity, scaffolding, and delivery capabilities with optional AgentSa
 The interactive CLI can run the same bounded capabilities through an explicitly selected model while
 keeping model choice, reasoning effort, processing tier, credentials, approvals, context, and cost inspectable.
 
+**SAM** = **Systematic Autonomous Machinery** — the execution spine under AgentSam (not a person).
+The conventional client variable is `sam`:
+
+```js
+import { AgentSamClient } from '@inneranimalmedia/agentsam-sdk';
+
+const sam = new AgentSamClient();
+const repo = await sam.invoke('repository.inspect', { root: '.' });
+// or: await sam.repository.inspect({ root: '.' });
+console.log(repo.data.summary, repo.receipt.id);
+```
+
+See [SAM Kernel](docs/architecture/SAM_KERNEL.md) for `invoke` / `describe` / `discover`,
+operation IDs, and the universal `SamResult` envelope.
+
 **npm:** `@inneranimalmedia/agentsam-sdk` · **Source:** [GitHub](https://github.com/SamPrimeaux/agentsam-sdk)
 
 Node 22.5+ is required. Docker is optional for container commands. Python 3.10+ is required
@@ -25,7 +40,7 @@ an npm-bootstrap script; standalone SEA binaries are planned, not shipped yet):
 ```sh
 curl -fsSL https://agentsam.inneranimalmedia.com/install | bash
 # a specific version, channel, or bundled app launcher:
-curl -fsSL https://agentsam.inneranimalmedia.com/install | bash -s -- --version 2.6.2
+curl -fsSL https://agentsam.inneranimalmedia.com/install | bash -s -- --version 2.6.3
 curl -fsSL https://agentsam.inneranimalmedia.com/install | bash -s -- --channel beta
 curl -fsSL https://agentsam.inneranimalmedia.com/install | bash -s -- --app cad
 ```
@@ -61,19 +76,24 @@ Without a global install, use `npx @inneranimalmedia/agentsam-sdk create my-agen
 
 ## MCP setup
 
-Cloudflare's API MCP server uses `https://mcp.cloudflare.com/mcp`. Add that URL
-to the agent client you use, then complete its Cloudflare OAuth flow. For Codex:
+Register MCP servers into `~/.agentsam/mcp/` and sync IDE adapters:
 
 ```sh
-codex mcp add cloudflare-api --url https://mcp.cloudflare.com/mcp
-codex mcp login cloudflare-api
+agentsam mcp add inneranimalmedia --client cursor
+agentsam mcp add cloudflare-api --client cursor
+agentsam mcp list --bundles          # Cloudflare portal bundles + pack scopes
+agentsam mcp scopes cloudflare-bindings
+agentsam mcp doctor cloudflare-api
 ```
 
-`agentsam mcp add cloudflare-api --url https://mcp.cloudflare.com/mcp` is not
-currently an AgentSam CLI command. The repo's `.agentsam/config.json` is a
-portable project manifest, not an MCP client configuration; it cannot register
-this server for every agent tool on clone. Keep OAuth tokens in each client's
-credential store rather than committing them to the repository.
+Cloudflare MCP portals (bindings, builds, browser, …) are **server bundles**, not
+OAuth clients. AgentSam Cloudflare OAuth stays pack-scoped (`agentsam` pack includes
+`mcp-portals.read` / `mcp-portals.write`). Never request the full ~315-scope catalog
+at connect time — upgrade with `agentsam cloudflare permissions authorize --packs …`.
+
+Portal-hosted OAuth (Cloudflare’s own consent on `*.mcp.cloudflare.com`) is separate
+from AgentSam’s CF connection token. Keep tokens in each client’s credential store;
+do not commit them.
 
 ## Index an existing repository
 
@@ -111,6 +131,7 @@ read-only `repository.snapshot` composition primitive. See [Capabilities and pre
 | File integrity | `agentsam merkle`; `/merkle` | [Merkle](docs/MERKLE.md) |
 | Security, trust-boundary scan, and repair | `agentsam security`; `/security` | [Security](docs/SECURITY.md) |
 | Mini prototypes | `agentsam mini`; `/mini` | [Mini](docs/MINI.md) |
+| Machine Intelligence (MINI/APP/WORLD ladder) | world-state / maturity (in progress) | [Machine Intelligence](docs/MACHINE_INTELLIGENCE.md) · [Tomorrow briefing](docs/plans/TOMORROW-MACHINE-FIRST-BRIEFING.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) |

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

@@ -0,0 +1,12 @@
+# Client CMS Editor workspace law
+
+- 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.
+- Prefer structured/versioned section data for publication. Arbitrary executable editor HTML is not a public-content authority.

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

@@ -0,0 +1,8 @@
+{
+  "source_repository": "SamPrimeaux/inneranimalmedia",
+  "source_path": "packages/client-cms-editor",
+  "source_commit": "5957af19dfb67e1551d0174b72141dd65acc4972",
+  "source_ref": "origin/main",
+  "imported_as": "apps/client-cms-editor",
+  "note": "Imported as real files, then normalized into an independent npm workspace root. Canonical platform CMS server/domain code remains in inneranimalmedia src/core/agentsam/cms until a dedicated agentsam-cms package extraction."
+}

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

@@ -0,0 +1,72 @@
+# AgentSam Client CMS Editor
+
+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.
+
+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.
+
+```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
+```
+
+## Product boundary
+
+CMS Studio is the authenticated authoring/control product. It is **not** the public website runtime.
+
+```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>/*
+```
+
+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.
+
+## Shared AgentSam rule
+
+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.
+
+Identity remains outside the workbench. IAM establishes `accountId` / `authUserId`, application authorization resolves CMS access, and only then may optional browser/container execution be created.
+
+## Cloud binding contract
+
+`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.
+
+## Canonical CMS backend
+
+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.
+
+## Development
+
+From this directory:
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm run build
+npm run dev
+```
+
+Standalone dev requires explicit site context, for example `/?site=my-site`. In a real authenticated host, mount `CmsEditor` with the resolved site/project identity.

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

@@ -0,0 +1,57 @@
+{
+  "schema": "agentsam.app.v1",
+  "id": "client-cms-editor",
+  "product_id": "cms",
+  "name": "AgentSam CMS Editor",
+  "kind": "app",
+  "package": "@inneranimalmedia/client-cms-editor",
+  "version": "0.1.0",
+  "entrypoints": {
+    "frontend": "./frontend",
+    "backend": "./backend",
+    "cli": "./bin/agentsam-cms.mjs"
+  },
+  "capabilities": [
+    "cms",
+    "media",
+    "templates",
+    "admin_content"
+  ],
+  "provides": [
+    "cms.editor",
+    "cms.templates",
+    "cms.media.library",
+    "workspace.panel"
+  ],
+  "surfaces": [
+    "store",
+    "theme-editor",
+    "cms-editor",
+    "templates",
+    "media-library",
+    "agentsam"
+  ],
+  "runtime": {
+    "local_preview": "ready",
+    "source_scaffold": "ready",
+    "cloudflare": "ready",
+    "github": "source-ready",
+    "browser": true,
+    "local": true
+  },
+  "commands": {
+    "preview": "agentsam-cms",
+    "doctor": "agentsam-cms doctor",
+    "scaffold": "agentsam-cms scaffold <directory>",
+    "info": "agentsam-cms info"
+  },
+  "bin": "bin/agentsam-cms.mjs",
+  "install": {
+    "command": "agentsam app scaffold client-cms-editor",
+    "selector": "client-cms-editor",
+    "paths": [
+      "/install/cms",
+      "/install/client-cms-editor"
+    ]
+  }
+}

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

@@ -0,0 +1,5 @@
+# CMS backend bridge
+
+This workspace package is the portable CMS client/backend boundary: HTTP API calls, model mapping, routing, preview messages and storefront URL helpers. It does not own the platform CMS server implementation or identity authority.
+
+The current platform implementation remains `inneranimalmedia/src/core/agentsam/cms/` until it is extracted into reusable `agentsam-cms-*` packages.

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

@@ -0,0 +1,22 @@
+{
+  "name": "@inneranimalmedia/agentsam-cms-backend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./api": "./src/api/client.ts",
+    "./model": "./src/model.ts",
+    "./preview": "./src/preview/bridge.ts",
+    "./routing": "./src/routing/index.js"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@inneranimalmedia/agentsam-cms-shared": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/apps/client-cms-editor/backend/src/api/client.ts

@@ -0,0 +1,200 @@
+import { mapCmsEditorBlock, mapCmsEditorBootstrap, mapCmsEditorPage, mapCmsEditorSection } from '../model';
+import type { CmsEditorBlock, CmsEditorPage, CmsEditorSection } from '@inneranimalmedia/agentsam-cms-shared';
+import { buildDemoCmsBootstrap } from '../demo-bootstrap';
+
+type Json = Record<string, any>;
+type ApiInit = Omit<RequestInit, 'body'> & { body?: any };
+
+function useDemoBootstrap(projectSlug?: string) {
+  const slug = String(projectSlug || '').trim().toLowerCase();
+  if (slug === 'demo' || slug === 'scaffold' || slug === 'preview' || slug === '') return true;
+  if (typeof window !== 'undefined') {
+    const host = window.location.hostname;
+    if (host === 'localhost' || host === '127.0.0.1') return true;
+    const params = new URLSearchParams(window.location.search);
+    if (params.get('demo') === '1' || params.get('preview') === '1') return true;
+  }
+  return false;
+}
+
+/** Offline first-run: never hit Worker APIs (avoids "Not Found" toasts). */
+function demoOk<T extends Json = Json>(payload: T = {} as T): Promise<T> {
+  return Promise.resolve(payload);
+}
+
+async function api<T extends Json = Json>(path: string, init: ApiInit = {}): Promise<T> {
+  if (useDemoBootstrap()) {
+    return demoOk<T>({} as T);
+  }
+  const headers = new Headers(init.headers);
+  let body = init.body;
+  if (body != null && !(body instanceof FormData) && typeof body !== 'string') {
+    headers.set('Content-Type', 'application/json');
+    body = JSON.stringify(body);
+  }
+  const response = await fetch(path, { ...init, body, headers, credentials: 'include', cache: 'no-store' });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const message = payload?.message || payload?.error || response.statusText || 'Request failed';
+    throw Object.assign(new Error(String(message)), { status: response.status, payload });
+  }
+  return payload as T;
+}
+
+export async function getCmsEditorBootstrap(projectSlug: string, focusPageId?: string | null) {
+  if (useDemoBootstrap(projectSlug)) {
+    return mapCmsEditorBootstrap(buildDemoCmsBootstrap(projectSlug || 'demo'), projectSlug || 'demo');
+  }
+  try {
+    const params = new URLSearchParams({ project_slug: projectSlug, site: projectSlug });
+    if (focusPageId) params.set('page_id', focusPageId);
+    return mapCmsEditorBootstrap(await api<Json>(`/api/cms/bootstrap?${params}`), projectSlug);
+  } catch (error) {
+    // Local first-run: fall back to the real editor shell with demo content.
+    if (typeof window !== 'undefined' && (location.hostname === 'localhost' || location.hostname === '127.0.0.1')) {
+      return mapCmsEditorBootstrap(buildDemoCmsBootstrap(projectSlug || 'demo'), projectSlug || 'demo');
+    }
+    throw error;
+  }
+}
+
+export async function getCmsEditorPagePreview(pageId: string, mode: 'draft' | 'published' = 'draft') {
+  if (useDemoBootstrap()) {
+    return demoOk({ id: pageId, preview: mode, html: null, _demo: true });
+  }
+  return api<Json>(`/api/cms/pages/${encodeURIComponent(pageId)}?preview=${encodeURIComponent(mode)}`);
+}
+
+export const saveCmsEditorSection = (sectionId: string, fields: Record<string, any>, css?: Record<string, any>) =>
+  api(`/api/cms/sections/${encodeURIComponent(sectionId)}`, { method: 'PUT', body: { section_data: { ...fields, ...(css && Object.keys(css).length ? { css_override: css } : {}) } } });
+export const renameCmsEditorSection = (sectionId: string, sectionName: string) => api(`/api/cms/sections/${encodeURIComponent(sectionId)}`, { method: 'PUT', body: { section_name: sectionName } });
+export const reorderCmsEditorSections = (pageId: string, sections: CmsEditorSection[]) => api('/api/cms/sections/reorder', { method: 'POST', body: { page_id: pageId, order: sections.map((section, index) => ({ id: section.id, sort_order: (index + 1) * 10 })) } });
+export const setCmsEditorSectionVisibility = (sectionId: string, visible: boolean) => api(`/api/cms/sections/${encodeURIComponent(sectionId)}/visibility`, { method: 'POST', body: { is_visible: visible ? 1 : 0 } });
+export async function createCmsEditorSection(pageId: string, name: string, fields: Record<string, any>, sortOrder: number) {
+  if (useDemoBootstrap()) {
+    return mapCmsEditorSection({
+      id: `sec_local_${Date.now()}`,
+      section_name: name,
+      section_type: name.toLowerCase().replace(/\s+/g, '-'),
+      section_data: fields,
+      is_visible: 1,
+      sort_order: sortOrder,
+    });
+  }
+  const result = await api<Json>('/api/cms/sections', { method: 'POST', body: { page_id: pageId, section_type: name.toLowerCase().replace(/\s+/g, '-'), section_name: name, section_data: fields, sort_order: sortOrder } });
+  return mapCmsEditorSection(result.section || { id: result.id, section_name: name, section_type: name, section_data: fields, is_visible: 1 });
+}
+
+export async function listCmsEditorBlocks(sectionId: string) {
+  if (useDemoBootstrap()) return [];
+  const result = await api<Json>(`/api/cms/blocks?section_id=${encodeURIComponent(sectionId)}`);
+  return (result.blocks || result.components || []).map((row: Json) => mapCmsEditorBlock(row, sectionId));
+}
+export async function createCmsEditorBlock(sectionId: string, type: string, data: Record<string, any>, sortOrder = 10) {
+  const blockType = String(type || 'text').trim() || 'text';
+  if (useDemoBootstrap()) {
+    return mapCmsEditorBlock({
+      id: `blk_local_${Date.now()}`,
+      section_id: sectionId,
+      type: blockType,
+      block_type: blockType,
+      data,
+      sort_order: sortOrder,
+      is_visible: 1,
+    }, sectionId);
+  }
+  const result = await api<Json>('/api/cms/blocks', {
+    method: 'POST',
+    body: {
+      section_id: sectionId,
+      type: blockType,
+      block_type: blockType,
+      component_type: blockType,
+      data,
+      sort_order: sortOrder,
+    },
+  });
+  return mapCmsEditorBlock(result.block || result.component || { id: result.id, section_id: sectionId, type: blockType, data }, sectionId);
+}
+export const saveCmsEditorBlock = (block: CmsEditorBlock) => api(`/api/cms/blocks/${encodeURIComponent(block.id)}`, { method: 'PUT', body: { block_data: block.data, block_type: block.type, type: block.type, component_type: block.type } });
+export const setCmsEditorBlockVisibility = (blockId: string, visible: boolean) => api(`/api/cms/blocks/${encodeURIComponent(blockId)}/visibility`, { method: 'POST', body: { is_visible: visible ? 1 : 0 } });
+export const reorderCmsEditorBlocks = (blocks: CmsEditorBlock[]) => api('/api/cms/blocks/reorder', { method: 'POST', body: { order: blocks.map((block, index) => ({ id: block.id, sort_order: (index + 1) * 10 })) } });
+
+export async function createCmsEditorPage(projectSlug: string, input: { title: string; slug: string; type: string }) {
+  const slug = input.slug.replace(/^\/+/, '') || 'untitled';
+  if (useDemoBootstrap(projectSlug)) {
+    return mapCmsEditorPage({
+      id: `page_local_${Date.now()}`,
+      title: input.title || 'Untitled',
+      slug,
+      route_path: `/${slug}`,
+      page_type: input.type,
+      status: 'draft',
+    });
+  }
+  const result = await api<Json>('/api/cms/pages', { method: 'POST', body: { project_id: projectSlug, title: input.title || 'Untitled', slug, route_path: `/${slug}`, page_type: input.type, status: 'draft', content: '' } });
+  return mapCmsEditorPage({ ...result, id: result.id, title: input.title, slug, route_path: result.route_path || `/${slug}`, page_type: input.type, status: 'draft' });
+}
+export const saveCmsEditorPageMeta = (page: CmsEditorPage) => {
+  if (useDemoBootstrap()) return demoOk({ ok: true, id: page.id });
+  const route = page.slug.startsWith('/') ? page.slug : `/${String(page.slug || '').replace(/^\/+/, '')}`;
+  const normalizedRoute = route.length > 1 ? route.replace(/\/+$/, '') : route || '/';
+  const slug = normalizedRoute === '/' ? 'home' : normalizedRoute.replace(/^\/+/, '') || 'untitled';
+  return api(`/api/cms/pages/${encodeURIComponent(page.id)}`, {
+    method: 'PUT',
+    body: {
+      title: page.title,
+      route_path: normalizedRoute,
+      slug,
+      page_type: page.type,
+      seo_title: page.metaTitle,
+      meta_description: page.metaDescription,
+    },
+  });
+};
+export const publishCmsEditorPage = (pageId: string) => api(`/api/cms/pages/${encodeURIComponent(pageId)}/publish`, { method: 'POST', body: {} });
+export const saveCmsEditorThemeVars = (projectSlug: string, vars: Record<string, string>) => api('/api/cms/theme-vars', { method: 'PATCH', body: { project_slug: projectSlug, vars } });
+
+export async function getCmsEditorAssets() {
+  if (useDemoBootstrap()) return [];
+  const result = await api<Json>('/api/cms/assets');
+  return (result.assets || []).map((asset: Json, index: number) => ({ id: asset.id || index, name: asset.original_filename || asset.filename || asset.label || 'Asset', type: String(asset.mime_type || '').startsWith('video/') ? 'Video' : String(asset.mime_type || '').includes('font') ? 'Font' : String(asset.mime_type || '').includes('pdf') ? 'Document' : 'Image', size: asset.content_size_bytes ? `${(Number(asset.content_size_bytes) / 1e6).toFixed(1)} MB` : '—', color: ['#5346db', '#d2e9df', '#ebc59d', '#25302b', '#705cf0', '#e6e0d3'][index % 6], previewUrl: asset.thumbnail_url || asset.cdn_url || asset.public_url || null }));
+}
+export async function getCmsEditorTemplates() {
+  if (useDemoBootstrap()) {
+    return [
+      { id: 'tpl_baseline_landing', name: 'Landing page', type: 'page', category: 'Marketing', slug: 'landing', previewImageUrl: null, hasHtml: false },
+      { id: 'tpl_baseline_hero', name: 'Editorial hero', type: 'section', category: 'Portfolio', slug: 'hero', previewImageUrl: null, hasHtml: false },
+      { id: 'tpl_baseline_footer', name: 'Utility footer', type: 'section', category: 'Agency', slug: 'footer', previewImageUrl: null, hasHtml: false },
+    ];
+  }
+  const result = await api<Json>('/api/cms/templates');
+  return (result.templates || []).map((row: Json) => ({
+    id: String(row.id || ''),
+    name: String(row.template_name || row.iam_label || row.slug || 'Template'),
+    type: String(row.template_type || 'section'),
+    category: String(row.category || 'General'),
+    slug: row.slug ? String(row.slug) : null,
+    previewImageUrl: row.preview_image_url ? String(row.preview_image_url) : null,
+    hasHtml: Boolean(row.source_html_r2_key),
+  })).filter((row: { id: string }) => row.id);
+}
+
+export async function applyCmsEditorTemplate(templateId: string, input: { pageId?: string | null; projectSlug?: string | null } = {}) {
+  if (useDemoBootstrap(input.projectSlug || undefined)) {
+    return demoOk({ ok: true, template_id: templateId, page_id: input.pageId, _demo: true });
+  }
+  return api<Json>(`/api/cms/templates/${encodeURIComponent(templateId)}/apply`, {
+    method: 'POST',
+    body: {
+      page_id: input.pageId || undefined,
+      project_slug: input.projectSlug || undefined,
+    },
+  });
+}
+export async function getCmsEditorContacts() {
+  if (useDemoBootstrap()) return [];
+  const result = await api<Json>('/api/user/contacts');
+  return (result.contacts || []).map((row: Json, index: number) => ({ id:index,name:String(row.name||row.display_name||row.email||'Contact'),email:String(row.email||''),source:String(row.source||'Contact form'),date:String(row.updated_at||row.created_at||'Recently'),tag:Array.isArray(row.tags)?row.tags[0]||'Lead':row.tag||'Lead' }));
+}
+export const activateCmsEditorTheme = (themeSlug: string, accent?: string) => api('/api/cms/themes/activate', { method: 'POST', body: { slug: themeSlug, accent } });

package/apps/client-cms-editor/backend/src/demo-bootstrap.ts

@@ -0,0 +1,145 @@
+/**
+ * Offline first-run CMS site for localhost preview — feeds the real CmsEditor shell.
+ * Not a separate “scaffold UI”. Migrations/API stay authoritative in production.
+ */
+
+export function buildDemoCmsBootstrap(projectSlug = 'demo') {
+  const pageId = 'page_home';
+  const heroId = 'sec_hero';
+  const gridId = 'sec_products';
+  const footerId = 'sec_footer';
+  const textBlockId = 'blk_join';
+
+  return {
+    tenant: {
+      name: 'Heuristic Theme',
+      domain: 'demo.localhost',
+      primary_color: '#1e6a6f',
+    },
+    public_domain: 'demo.localhost',
+    workspace_label: 'Heuristic Theme',
+    home_page: { id: pageId },
+    protocol_version: 1,
+    active_theme: {
+      css_vars: {
+        '--brand-primary': '#1e6a6f',
+        '--brand-secondary': '#123f42',
+        '--brand-accent': '#cfef5b',
+        '--color-bg': '#f5f2ea',
+        '--color-surface': '#ffffff',
+        '--color-text': '#101014',
+        '--color-text-muted': '#73737f',
+        '--font-heading': 'Inter',
+        '--font-body': 'Inter',
+      },
+    },
+    pages: [
+      {
+        id: pageId,
+        title: 'Home page',
+        slug: '/',
+        route_path: '/',
+        page_type: 'Home',
+        status: 'draft',
+        seo_title: 'Heuristic Theme',
+        meta_description: 'Stock CMS theme preview for AgentSam scaffolding.',
+      },
+    ],
+    sections_by_page: {
+      [pageId]: [
+        {
+          id: heroId,
+          section_name: 'Editorial hero',
+          section_type: 'hero',
+          is_visible: 1,
+          sort_order: 10,
+          section_data: {
+            headline: 'My Store',
+            subline: 'Stock heuristic-theme · first-run CMS surface',
+            cta_text: 'Shop collection',
+            eyebrow: 'Heuristic Theme',
+            bg_color: '#101014',
+          },
+        },
+        {
+          id: gridId,
+          section_name: 'Product grid',
+          section_type: 'product-grid',
+          is_visible: 1,
+          sort_order: 20,
+          section_data: {
+            title: 'Featured',
+            columns: 2,
+          },
+        },
+        {
+          id: footerId,
+          section_name: 'Footer',
+          section_type: 'footer',
+          is_visible: 1,
+          sort_order: 30,
+          section_data: {
+            zone: 'FOOTER',
+            bg_color: '#F3F0E8',
+          },
+        },
+      ],
+    },
+    blocks_by_section: {
+      [heroId]: [],
+      [gridId]: [
+        {
+          id: 'blk_card_1',
+          section_id: gridId,
+          block_type: 'product-card',
+          is_visible: 1,
+          sort_order: 10,
+          block_data: { title: 'Classic tee', price: '$19.99' },
+        },
+        {
+          id: 'blk_card_2',
+          section_id: gridId,
+          block_type: 'product-card',
+          is_visible: 1,
+          sort_order: 20,
+          block_data: { title: 'Soft tee', price: '$19.99' },
+        },
+      ],
+      [footerId]: [
+        {
+          id: textBlockId,
+          section_id: footerId,
+          block_type: 'text',
+          is_visible: 1,
+          sort_order: 10,
+          block_data: {
+            text: 'Join our email list',
+            typography_preset: 'Heading 4',
+            width: 'fit',
+            max_width: 'normal',
+            align: 'left',
+          },
+        },
+      ],
+    },
+    component_templates: [
+      { id: 'tpl_baseline_landing', template_name: 'Landing page', template_type: 'page', category: 'Marketing' },
+      { id: 'tpl_baseline_hero', template_name: 'Editorial hero', template_type: 'section', category: 'Portfolio' },
+      { id: 'tpl_baseline_footer', template_name: 'Utility footer', template_type: 'section', category: 'Agency' },
+    ],
+    schemas: {
+      protocol_version: 1,
+      sections: [
+        { key: 'hero', type: 'hero', version: 1, label: 'Editorial hero' },
+        { key: 'product-grid', type: 'product-grid', version: 1, label: 'Product grid' },
+        { key: 'footer', type: 'footer', version: 1, label: 'Footer' },
+      ],
+      blocks: [
+        { key: 'text', type: 'text', version: 1, label: 'Text' },
+        { key: 'product-card', type: 'product-card', version: 1, label: 'Product card' },
+      ],
+    },
+    _demo: true,
+    _project_slug: projectSlug,
+  };
+}

package/apps/client-cms-editor/backend/src/index.ts

@@ -0,0 +1,6 @@
+export * from './api/client';
+export * from '@inneranimalmedia/agentsam-cms-shared';
+export * from './model';
+export * from './preview/bridge';
+export * from './preview/urls';
+export * from './storefront';