@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md

@@ -0,0 +1,188 @@
+# AgentSam Application Contract
+
+**Status:** binding for portable product apps  
+**Schema:** `protocol/apps/agentsam.app.v1.schema.json`  
+**CLI:** `agentsam app validate` · `agentsam app list` · `agentsam app inspect <id>`
+
+## Artifact taxonomy
+
+| Type | Meaning | Canonical manifest |
+|------|---------|-------------------|
+| **APP** | Something a user can install/run/use as a product | `agentsam.app.json` |
+| **PACKAGE** | Reusable code/capability | `agentsam.package.json` (or package metadata) |
+| **SERVICE** | Runtime infrastructure/backend | `agentsam.package.json` with `type: "service"` (or `agentsam.service.json`) |
+| **HOST** | Something that mounts/composes apps | host / install state under `.agentsam/` |
+| **THEME** | Appearance/content kit, not an app | theme package / theme-site scaffold |
+
+A folder under `apps/` is **not** an APP merely because of its path. The AgentSam APP contract (`agentsam.app.json`) makes it one.
+
+Example: `apps/agentsam-go-worker` correctly uses `agentsam.package.json` (`type: "service"`) and must **not** be forced into APP semantics because it is deployable.
+
+Theme packages and static theme-site scaffolds likewise stay outside APP semantics.
+
+## Target tree (conceptual)
+
+```
+apps/
+  cad-creator/
+  client-cms-editor/
+  ecommerce-cms/
+  local-studio/
+
+packages/
+  database-editor/
+  settings/
+  identity/
+  planner/
+  cms-sections/
+  themes/
+
+services/
+  go-runtime/
+  render-runtime/
+```
+
+## Identity namespaces (must not collapse)
+
+| Namespace | Example | Role |
+|-----------|---------|------|
+| `APP.id` | `cad-creator` | Canonical product identity — immutable kebab-case |
+| `HOST.id` / origin | host-install projection | Where this APP instance is served; belongs to installation state, not portable APP identity |
+| npm package | `@inneranimalmedia/agentsam-cad-creator` | Distribute/install code |
+| CLI command | `agentsam-cad-creator` / `agentsam cad` | Launch surface |
+| Cloudflare Worker | `agentsam-cad-creator` | Host deployment name |
+| desktop bundle | `com.inneranimalmedia.agentsam.cadcreator` | OS identity |
+| route | `/cad` | URL mount |
+| service | `cad-render-service` | Infrastructure |
+| `PRODUCT.id` | `cms` | Platform product registry |
+| `MOUNT.id` | `cms-studio` | Host mount slot |
+| remote identity/account issuer | optional host/provider adapter configuration | External account authority for an installation — **not** intrinsic APP identity |
+
+Portable APP law: an installable APP must not hardcode a donor/company hostname, remote issuer, tenant, confidential OAuth client, or customer deployment as a prerequisite for its local product experience. Those facts belong to `agentsam.host-install.v1` state or an explicitly installed provider/identity adapter.
+
+Those names **may** differ. What must not happen:
+
+```js
+const APP = "agentsam-cad-creator"; // Worker name ≠ APP identity
+```
+
+```js
+// Forbidden: collapsing HOST and PLATFORM into alias env vars
+const origin = env.AGENTSAM_STUDIO_ORIGIN || env.AGENTSAM_LOCAL_STUDIO_ORIGIN || env.IAM_OAUTH_ISSUER;
+```
+
+Relate namespaces explicitly:
+
+```json
+{
+  "schema": "agentsam.host-install.v1",
+  "app_id": "local-studio",
+  "config": {
+    "hosts": [
+      { "host_id": "studio-public", "origin": "https://studio.example.com", "role": "production" }
+    ],
+    "identity": { "portable_default": "local" }
+  }
+}
+```
+
+```json
+{
+  "id": "client-cms-editor",
+  "product_id": "cms",
+  "name": "AgentSam CMS",
+  "package": "@inneranimalmedia/client-cms-editor"
+}
+```
+
+```json
+{
+  "schema": "agentsam.host-install.v1",
+  "app_id": "client-cms-editor",
+  "config": {},
+  "mounts": []
+}
+```
+
+## Manifest authority
+
+```
+apps/<app-id>/
+├── agentsam.app.json    ← ONE canonical product definition
+├── package.json
+├── frontend/
+├── backend/
+├── bin/
+└── .agentsam/           ← host / install / project state (not a second product def)
+    └── app.json         ← references app_id; does not redefine identity
+```
+
+| File | Role |
+|------|------|
+| `agentsam.app.json` | Package/product definition — sole APP identity authority |
+| `.agentsam/` | Host/user/project **installation** state for this checkout or customer |
+
+Same APP installed into Fuel & Free Time, Companions CPAs, InnerAnimalMedia, or a customer localhost keeps the same `APP.id`. `.agentsam/` describes **this** installation.
+
+## Physical shape
+
+```
+apps/<app-id>/
+├── agentsam.app.json
+├── package.json
+├── frontend/     # portable presentation/UI
+├── backend/      # application-owned server/runtime
+├── bin/          # launch/install/dev CLI
+├── scripts/
+├── test/
+└── README.md
+```
+
+Not every directory is required for every runtime. Directory **meaning** must not change.
+
+## Runtime identity loading
+
+```js
+import appManifest from "../../agentsam.app.json";
+
+export const APP = Object.freeze(appManifest);
+// APP.id === "cad-creator"
+```
+
+Forbidden:
+
+- `const APP = "..."` (string used as product identity)
+- Duplicated app definitions (root manifest + `.agentsam/app.json` both defining the product)
+- Treating Worker name, npm package name, or route slug as `APP.id`
+
+## AGENTSAM APPLICATION CONTRACT (rules)
+
+APP represents a portable user-facing AgentSam application.
+
+Every APP MUST:
+
+1. Own exactly one canonical `agentsam.app.json`.
+2. Have one immutable kebab-case `APP.id`.
+3. Load runtime APP identity from that manifest.
+4. Keep package, service, Worker, host, route, and desktop identities separate from `APP.id`.
+5. Use explicit `app_id` / `product_id` / `service_id` / `package_id` relationships rather than aliases.
+6. Follow the standard `frontend` / `backend` / `bin` layout.
+7. Declare capabilities and entrypoints in its manifest.
+8. Be runnable independently.
+9. Be discoverable/composable by an AgentSam host.
+10. Pass `agentsam app validate`.
+
+## Resulting composition model
+
+```
+npm / install / package
+          ↓
+      AgentSam APP
+          ↓
+ ┌────────┼─────────┐
+ ▼        ▼         ▼
+standalone Local   another
+app        Studio  APP / host
+```
+
+Goal is **not** one identifier everywhere. Goal is **one canonical identifier per namespace**, with explicit relationships between namespaces.

package/docs/architecture/AGENTSAM_RUNTIME_PROTOCOL.md

@@ -0,0 +1,171 @@
+# AgentSam Runtime Protocol
+
+> Standing law: **`agentsam.runtime.v1` is the portable execution contract. `agentsamd` and ExecOS are supported runtime implementations/adapters; neither is a transport.**
+
+## Architectural law
+
+**`agentsam.runtime.v1` is the execution authority. `agentsamd` is the stock portable machine daemon for independent installs; ExecOS is a proven managed/platform runtime and dispatcher used by InnerAnimalMedia. Runtime implementations sit behind the same connection/protocol model, and transports stay separate from them.**
+
+Physical D1 tables stay `terminal_*` for this generation. Domain nouns in code are `RuntimeInstance`, `RuntimeConnection`, `RuntimeAdapter`, `RuntimeCapabilities`.
+
+| Noun | Role |
+|---|---|
+| **agentsamd** | Lives with execution: exec, PTY, fs, processes, git, tools, capabilities, attach |
+| **Native helper** (this sprint) | Privileged companion under unprivileged Go: keychain, mounts, devices |
+| **ExecOS / EXECOS Worker** (`env.EXECOS` / `EXECOS_IAM`) | Supported managed/platform runtime + cloud→machine dispatch used by InnerAnimalMedia. Historical rows may use `runtime_adapter=execos_legacy`; that compatibility id does **not** imply a retirement decision. |
+| **PTY_SERVICE** | VPC/PTY health lane — not the daemon |
+| **agentsam-go-worker** | Optional hosted Go service (same Go core). **Not** the Studio control plane |
+| **Local Studio Worker** | Stock app host: auth, D1 SSOT, bindings, runtime APIs |
+
+### Four permanent concepts (never conflate)
+
+```text
+INSTANCE   what computer/execution environment is this?
+ADAPTER    what speaks agentsam.runtime.v1 there?
+TRANSPORT  how do we reach that adapter?
+AUTH       how is this connection authenticated?
+```
+
+Examples:
+
+| | Mac | GCP VM | CF Sandbox |
+|---|---|---|---|
+| provider | local | google_cloud | cloudflare |
+| substrate | host | vm | sandbox |
+| lifecycle | persistent | persistent | ephemeral |
+| provider_product | (host) | compute_engine | sandbox |
+| protocol | agentsam.runtime.v1 | same | same |
+| runtime_adapter | agentsamd or ExecOS | agentsamd or ExecOS | cloudflare_sandbox |
+| transport | cloudflare_tunnel / direct_https | cloudflare_tunnel / vpc_service | service_binding |
+| auth_mode | connection_token | connection_token / platform_bridge | service_binding |
+
+**Forbidden:** `transport IN ('execos','container')` — those were adapter/substrate smuggled into transport.
+
+### ExecOS support status
+
+ExecOS is **supported working machinery**, not presumed deprecated. Current InnerAnimalMedia production/runtime paths still use it for governed dispatch, enrolled-device execution, bridge authentication, terminal/session routing, and `user_hosted_tunnel` flows.
+
+`execos_legacy` exists because earlier rows encoded `execos` as a transport and needed a compatibility mapping into the newer four-axis model. The word `legacy` in that identifier is migration vocabulary; it is **not** authorization to delete, disable, or silently replace ExecOS.
+
+The portability goal is additive:
+
+```text
+agentsam.runtime.v1
+        ├── agentsamd              stock portable/local runtime
+        ├── ExecOS                 supported managed/platform runtime
+        ├── cloudflare_sandbox     sandbox adapter
+        └── future adapters
+```
+
+Where implementations overlap, converge on protocol semantics and acceptance tests. A future deprecation is a separate, evidence-backed product decision.
+
+---
+
+## Runtime Registry (D1 spine — preserve)
+
+```text
+ACCOUNT
+│
+├── agentsam_api_credentials     AAK / BRK
+├── cloud_provider_connections   optional provisioning authority (widen providers)
+│
+└── terminal_instances           WHAT EXISTS
+       ├── provider, substrate, provider_product, lifecycle
+       ├── platform / arch / capabilities_json
+       ▼
+    terminal_connections         HOW AGENTSAM TALKS TO IT
+       ├── protocol = agentsam.runtime.v1
+       ├── runtime_adapter = agentsamd | execos_legacy (ExecOS compatibility id) | …
+       ├── transport = direct_https | cloudflare_tunnel | vpc_service | …
+       ├── auth_mode
+       ├── terminal_connection_credentials
+       ├── terminal_enrollment_tokens
+       ├── terminal_sessions          interactive PTY
+       ├── terminal_jobs              noninteractive (runtime_run_id)
+       └── terminal_port_forwards
+```
+
+**Do not** introduce parallel `runtime_instances` / `runtime_connections` tables this generation.
+
+### Authority ladder (keep)
+
+```text
+AAK / BRK  →  enrollment token  →  connection credential  →  session attach token
+```
+
+### Rebuild now (bounded)
+
+1. **`terminal_instances`** — drop `kind`↔provider CHECK; drop `compute_provider`; add substrate / provider_product / lifecycle / hw_model; normalize arch `x64`→`x86_64`.
+2. **`terminal_connections`** — replace transport=`execos|container` with `protocol` + `runtime_adapter` + real `transport`; fold `transport_provider` into `transport`; add `endpoint_ref`; stop growing provider-specific columns (keep queried CF indexes for now, prefer `provider_metadata_json`).
+3. **`terminal_jobs`** — `execos_run_id` → `runtime_run_id` (all live values null).
+4. **`cloud_provider_connections`** — widen `provider`; remove policy CHECK forcing GCP `provider_connection_id`.
+
+### Do not rebuild unless needed
+
+`terminal_connection_credentials`, `terminal_enrollment_tokens`, `terminal_sessions` (optionally rename `auth_token_hash`→`attach_token_hash` while empty), `terminal_port_forwards`, `agentsam_api_credentials`.
+
+---
+
+## Installation grades (this sprint)
+
+| Grade | What |
+|---|---|
+| **Full daemon** | Go `agentsamd` + enroll + LaunchAgent/systemd |
+| **Native helper** | Rust/Zig privileged helper with daemon |
+| **Provider adapter** | CF Sandbox etc. (`runtime_adapter=cloudflare_sandbox`) |
+
+```bash
+agentsam setup runtime
+# plan → create instance → create connection → mint enrollment → agentsamd enroll
+```
+
+---
+
+## Protocol surface
+
+```text
+identity / capabilities / health
+exec / spawn / signal / terminate
+pty.create|attach|resize|detach
+fs.read|write|list|watch
+ports.list|expose
+system.inspect
+```
+
+---
+
+## Migration priority
+
+1. Freeze vocabulary (this doc + `packages/runtime-protocol`).
+2. Rebuild `terminal_instances` (local_device→host).
+3. Normalize historical `transport=execos` records into **adapter + real transport** fields. Existing `runtime_adapter=execos_legacy` is a compatibility identifier for ExecOS-backed connections, not a support/deprecation state.
+4. Stock independent/local installs may default to `runtime_adapter=agentsamd`; managed/platform installs may continue to use ExecOS. Both remain valid registered runtimes.
+5. `execos_run_id` → protocol-neutral `runtime_run_id` where that column still encodes implementation detail.
+6. Widen `cloud_provider_connections`.
+7. Heartbeats fill `capabilities_json`, `provider_product`, and lifecycle facts from the selected runtime.
+8. `agentsam setup runtime` writes records from GOAP plans without assuming one runtime implementation.
+9. Prove overlapping ExecOS / agentsamd operations against the same `agentsam.runtime.v1` semantics instead of removing one merely because the other exists.
+10. Any future narrowing or retirement of ExecOS requires an explicit product decision, inventory of production callers, proven replacement parity, migration plan, acceptance tests, and approval.
+
+---
+
+## Rejected
+
+- Parallel `runtime_*` physical tables beside `terminal_*` this generation
+- `transport = execos` or `container`
+- kind↔provider coupling (VM=Google only, etc.)
+- Soft dual-write forever
+- Casting agentsam-go-worker as the EXECOS/control plane
+- Stock dependence on `load-agent-env.sh`
+
+---
+
+## Success criteria
+
+- User123 can install Studio → `setup runtime` → enroll the stock `agentsamd` runtime (+ native helper where needed) → attach without InnerAnimalMedia infrastructure.
+- Existing InnerAnimalMedia ExecOS connections remain supported and functional while sharing protocol-neutral registry/session concepts.
+- Same protocol semantics can be implemented across Mac / GCP VM / Docker / CF Container; Sandbox remains an adapter.
+- Transport can change without renaming the instance or changing runtime/session semantics.
+- D1 spine stays `terminal_*`; vocabulary remains instance + adapter + transport + auth.
+- The historical string `execos_legacy` is treated as compatibility vocabulary only. **Do not infer support lifecycle from the identifier.**
+- Duplication between ExecOS and agentsamd is resolved by shared contracts/tests and explicit routing, not by deleting proven machinery without parity.

package/docs/architecture/LOCAL_STUDIO_CLOUDFLARE_OAUTH.md

@@ -14,12 +14,20 @@
 Browser GET on connections **start** → 302 to Cloudflare.  
 `fetch` + `Accept: application/json` → `{ authorize_url }`.
 
-## D1
+## D1 tables (Cloudflare connect / approve)
 
-- `identity_oauth_states` — identity PKCE (migration `0013_identity_oauth_states.sql`)
-- `agentsam_cloudflare_oauth_state` — MCP connector PKCE
+| Table | Role |
+|---|---|
+| `oauth_state_nonces` | Short-lived PKCE state for connector `/api/connections/cloudflare/*` |
+| `identity_oauth_states` | Short-lived PKCE for identity “Sign in with Cloudflare” |
+| `user_oauth_tokens` | **SSOT** durable grant: sealed access/refresh, scopes, `account_identifier` (= CF account id), `is_active` |
+| `agentsam_cloudflare_connections` | **Legacy** — migrated/superseded into `user_oauth_tokens`; do not write new rows |
+| `agentsam_cloudflare_oauth_state` | Legacy MCP connector PKCE (prefer `oauth_state_nonces`) |
+
+Vault seals token material; D1 never stores raw refresh/access plaintext in the durable grant row when vault is configured.
+
+Resource discovery (their D1/R2/Workers) uses the sealed token from `user_oauth_tokens` — never the platform `env.DB` binding.
 
-## IAM AS redirect (required)
 
 Register on client `iam_agentsam_sdk_web`:
 

package/docs/architecture/R2_SLUG_NAMESPACE.md

@@ -0,0 +1,20 @@
+# AgentSam R2 layout — slug-keyed customer namespaces (not account_id)
+#
+# Path identity = brand.slug (UNIQUE in D1). account_id lives inside manifest.json
+# as ownership data for auth checks — never as a directory segment.
+#
+# {slug}/
+#   brand/identity.json
+#   brand/assets/{asset_key}/{version}/   ← brand_asset / brand_asset_variant
+#   site/public/…  site/draft/…
+#   frontend/dist/
+#   backend/
+#   manifest.json                         ← account_id, oauth defaults, included_apps
+#
+# Platform chrome (not a customer):
+#   _platform/shared/…
+#
+# Product surface for non-git customers:
+#   agentsam scaffold new <slug>
+#     → provisions R2 prefix + Worker + D1 rows from an npm-packaged app scaffold
+#     → customers never see the monorepo

package/docs/architecture/WORK_PRODUCT_EXTRACTION.md

@@ -0,0 +1,97 @@
+# AgentSam Work product extraction
+
+## Product boundary
+
+AgentSam Work is a **private monorepo workspace package**, not a separately
+published product package. It is reusable UI/runtime contract code consumed by
+Local Studio and can later be composed into other AgentSam apps.
+
+```
+packages/agentsam-work
+  contracts       normalized Work view/runtime models
+  frontend        shell, mini navigation, right rail, surfaces
+  client          transport adapter
+  fixtures        production-shaped localhost data
+
+apps/local-studio
+  frontend        route composition + LocalStudio WorkHost
+  backend/server/work
+                  authenticated provider/storage adapters
+```
+
+The package is intentionally parallel to `@inneranimalmedia/agentsam-settings`:
+presentation/contracts are reusable; Local Studio remains the first host and
+owns backend authority.
+
+## Donor material
+
+The current InnerAnimalMedia dashboard remains a donor, not a dependency.
+
+The extraction studied:
+
+- `CollaborateWorkShell.tsx`
+- `CollaboratePageRail.tsx`
+- `collaborateRailNav.ts`
+- `shellNav.ts`
+- `LaunchDeskPage.tsx`
+- `CollaborateTasksPanel.tsx`
+- `MailPage.tsx`
+- `api/tickets.ts`
+- `api/projects.ts`
+- calendar/mail/Gmail OAuth backend modules
+
+The useful product grammar is retained:
+
+- one Work mini navigation family;
+- optional narrow right utility rail;
+- Calendar/Tickets/Mail as one Work workbench;
+- ticket `surface` separates engineering/platform tickets from Collaborate
+  tickets without duplicating the ticket runtime;
+- Artifacts and Projects share the same Work chrome;
+- Projects keep their card-grid information architecture;
+- project detail keeps its main AgentSam composer plus the quick-stats and
+  project-context rail.
+
+Dashboard-specific route prefixes, workspace navigation infrastructure, and
+host-specific CSS are not imported into the package.
+
+## Flat route contract
+
+```
+/collaborate
+/collaborate?seg=tickets
+/mail
+/artifacts
+/artifacts/tickets
+/artifacts/tickets/:ticketId
+/projects
+/projects/:projectId
+```
+
+`seg=tasks` may remain a compatibility alias at a host boundary, but reusable
+links emit `seg=tickets`.
+
+## Theme contract
+
+The default theme intentionally follows the simple Google Workspace/Cloud
+visual grammar visible in the donor Work pages: bright canvas, subtle blue
+selection, compact rows, restrained borders, little shadow, and rounded
+controls.
+
+It is not hard-coded as brand authority. Work surfaces consume semantic
+`--agentsam-work-*` CSS variables. `applyWorkThemeTokens()` lets Local
+Studio project a Settings → Themes selection into the Work package without
+making Work import Settings.
+
+## Backend extraction order
+
+1. Keep all routes on the production-shaped fixture host until the UI shell is
+   approved.
+2. Implement read-only Local Studio adapters for projects, artifacts, tickets,
+   calendar, and mail.
+3. Switch Local Studio from `createFixtureWorkHost` to the HTTP host.
+4. Add mutations (ticket CRUD, calendar CRUD, mail actions/compose) behind the
+   same adapters.
+5. Normalize Gmail OAuth return paths to flat `/mail`.
+6. Only then evaluate database migrations; do not reshape live D1 just to
+   satisfy the frontend scaffold.

package/docs/brand/AGENT_SAM_ICON_GRAMMAR.md

@@ -0,0 +1,70 @@
+# AgentSam icon & motion grammar
+
+Family system for product marks and UI glyphs. Static identity stays quiet and architectural; runtime motion (Computational Hyperspace) is spectral and dimensional — not the icon itself.
+
+## Brand hierarchy
+
+```text
+AgentSam                         master brand
+├── Local Studio                 product identity
+├── CAD Creator                  product identity
+├── Ecommerce                    product identity
+├── CLI                          surface identity
+└── future apps
+```
+
+Related without sharing the exact same icon. One recognizable **master silhouette** (abstract SAM core / aperture / dimensional mark — readable at 16–24 px). Each product adds a single cue:
+
+| Product | Cue on master geometry |
+|---|---|
+| Local Studio | workspace / portal |
+| CAD Creator | dimensional plane / cube |
+| Ecommerce | modular product-card |
+
+## Icon grammar
+
+| Attribute | Rule |
+|---|---|
+| Base | graphite / near-black dimensional surface |
+| Accent | spectral blue → violet; amber only for special active states |
+| Geometry | rounded, slightly architectural |
+| Detail | one dominant shape, max 2–3 secondary forms |
+| Text | never in the app icon |
+| Lighting | restrained edge/highlight — not glossy clip-art |
+| Small sizes | simplify rather than shrink detail |
+| Status icons | separate semantic system from product logos |
+| Motion | slow depth/parallax; no bouncing/spinning clutter |
+
+## Asset drop paths (desktop shell)
+
+| Asset | Path |
+|---|---|
+| App / Dock / tray PNG (prefer **1024×1024**) | `packages/agentsam-desktop-shell/icons/<app_id>/icon.png` |
+| Vector mark | `packages/agentsam-desktop-shell/icons/<app_id>/*.svg` |
+| Manifest | `packages/agentsam-desktop-shell/manifests/<app_id>.json` → `icon_set`, `icon_mark_svg` |
+
+Build: `cd packages/agentsam-desktop-shell && npm run build:brand -- local-studio`  
+Optional: `AGENTSAM_ICON_URL=https://…/logo.png` overrides local files.
+
+`build-brand.mjs` must honor `icon_mark_svg` when `icon.png` is missing (rasterize → `src-tauri/icons/`).
+
+## UI glyphs (not product logos)
+
+One semantic layer — design system picks the glyph family:
+
+```jsx
+<Icon name="workspace" />
+<Icon name="terminal" />
+<Icon name="activity" />
+<Icon name="repository" />
+<Icon name="warning" />
+```
+
+Do not mix Heroicons / Lucide / random SVGs / macOS symbols as the AgentSam brand identity. Platform-native symbols OK only for OS chrome.
+
+## Identity vs motion
+
+- **Static identity:** quiet / recognizable / architectural  
+- **Runtime motion:** spectral / dimensional / computational (Hyperspace)
+
+See also: `docs/plans/LOCAL-STUDIO-GRADUATION-2026-09-26.md`.

package/docs/content-studio/HOST_MOUNT_CHECKLIST.md

@@ -0,0 +1,71 @@
+# Host mount checklist — Content Studio (Path A / Commit 6)
+
+Portable packages are ready for host adapters. Full OAuth / production mounts
+are Path B / host-app work — do **not** fork packages per host.
+
+## Shared mount contract
+
+Each host supplies a `ContentRuntime` via `createContentRuntime({...})`:
+
+| Seam | Local Studio | IAM dashboard | Fuel & Free Time (customer) |
+|---|---|---|---|
+| `account` / `actor` | desktop session | IAM auth session | customer tenant session |
+| `providers` / capability adapters | local + optional CF | R2 / Images / Drive / Stream | customer-scoped providers |
+| `brandResolver` | project BrandPack projection | org BrandPack projection | customer BrandPack projection |
+| `knowledge` | local / injected | host Vectorize/AutoRAG/pgvector | customer knowledge adapter |
+| `localHost` | Tauri / agentsamd bridge | usually `unavailable` | usually `unavailable` |
+| `routes` / `permissions` | desktop RouteMap | IAM RouteMap | customer RouteMap |
+| UI | `<ContentStudio runtime={rt} />` | same | same |
+
+## Do
+
+1. Build runtime in the **host** app (not inside `agentsam-content-studio`).
+2. Derive UI tabs/actions from `await runtime.capabilities()`.
+3. Keep BrandPack authority in `agentsam-brand` / `brand.pack.json`.
+4. Use `inferBrandAssociation` only as proposals + ScoreCard evidence.
+5. Use `@inneranimalmedia/agentsam-cloudflare-images` for CF Images HTTP.
+
+## Don't
+
+- Import Tauri / raw `fs` / agentsamd into reusable UI packages.
+- Hardcode R2 / Images / Drive / Vectorize tabs in Content Studio.
+- Embed real customer BrandPack fixtures in generic packages.
+- Seed fictional `DEMO_BRAND_PROJECTIONS` into production `/content` runtimes.
+- Run IAM `deploy:full` from this SDK repo for content-studio work.
+
+## Local Studio mount (wired)
+
+- Route: `/content` → `ContentStudioPage` mounts `<ContentStudio runtime={…} />`
+- Runtime factory: `apps/local-studio/frontend/src/lib/content/createLocalStudioContentRuntime.ts`
+- **Identity:** resolved from `useCurrentUserState()` / Auth session — fail closed when missing.
+  No `acct_local_studio` / `local-studio-user` production defaults.
+- **Brand:** empty `ContentBrandResolver` projections until host injects BrandPack (Path B).
+  Fictional demos live only in `demoBrandProjections.ts` (tests/examples).
+- **LocalContentHost (desktop):** native Rust Tauri `local_content_bridge` —
+  `rfd` pickers, opaque `localref_*` / `localdir_*`, granted roots, browse in place,
+  copy only on `import_to_library`. **Does not require** monorepo Node or global Node.
+- **LocalContentHost (browser/dev):** File System Access API when available; else
+  explicit browser-import (`import_bytes`, 32 MiB) via Node `/api/content/local/bridge`.
+- Knowledge / BrandSimilarity: noop adapters (no Vectorize hardcode)
+- agentsamd: probed via Tauri `ensure_agentsamd` / health; FS ops are native Rust until
+  agentsamd ships native `/v1/fs` (documented migration target)
+
+## Packaged-app contract
+
+| Requirement | Status |
+|---|---|
+| Works from `/Applications` without repo checkout | Native Rust FS — yes |
+| No global Node for content FS | Desktop native — yes; Node bridge is browser/dev only |
+| Native Open File / Open Folder | `rfd` via `pick_files` / `pick_directory` |
+| Selected file not copied until import | Yes — `import_to_library` is separate |
+| Opaque refs only to UI/models | Yes — absolute paths stay in Rust/grant store |
+
+## Remaining for true 3-host E2E (Path B)
+
+- agentsamd native `/v1/fs` + watch (migration from native Rust bridge)
+- IAM dashboard route + OAuth-scoped providers
+- F&F admin mount with customer account scope
+- Production BrandPack projection into Local Studio `brandResolver`
+- Harvest Go pipeline → SiteGraph / TokenGraph → package-readiness ScoreCards
+- Brand package migration onto shared CF Images transport (content already uses it)
+- Beta / outcome calibration receipts for accept/reject (does not mutate evidence)