@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/docs/plans/UNIVERSAL-INGEST-MACHINE-FIRST-2026-09-24.md

@@ -0,0 +1,215 @@
+---
+name: Universal ingest stack
+overview: Strengthen agentsam-sdk in place—machine-first world state for every app/world, native decision primitives, distributable apps, mini kept as the tiny lane. Proof is real apps and harvested sites, not new demos. Branch hygiene complete on clean main.
+todos:
+  - id: branch-audit
+    content: "DONE 2026-09-24: audited + deleted completed local/remote branches and worktrees; only main remains"
+    status: completed
+  - id: machine-intel-docs
+    content: "Batch A — Land protocol/docs Machine Intelligence scaffold (ladder, primitives, confidence≠risk, receipts, MINI/APP/WORLD)"
+    status: pending
+  - id: decision-primitives
+    content: "Batch A — Native predicate/choice/score/distribution + confidence policy + decision receipts (AgentSam-owned, not TypeSafe)"
+    status: pending
+  - id: world-state
+    content: "Batch B — Converge snapshot+Merkle+AST+brand+harvest into world-state; agentsam inspect for arbitrary paths + every apps/*"
+    status: pending
+  - id: app-maturity
+    content: "Batch B — Calculated maturity + provenance/hashes/capabilities/relationships/verify/next for every apps/*"
+    status: pending
+  - id: verify-strengthen
+    content: "Batch B — Strengthen verify-package/source-boundaries, app contract tests, registry receipts (imperfect = observable)"
+    status: pending
+  - id: ingest-on-worlds
+    content: "Batch C — Universal ingest/extract/sensitive/catalog feeding world-state; fixtures = harvested sites + real apps"
+    status: pending
+  - id: app-distribute
+    content: "Batch D — Graduate curated apps toward npm install / agentsam app add (runtime/scaffold only; exclude donor junk)"
+    status: pending
+  - id: mini-keep-tiny
+    content: "Batch D — Keep mini as instant zero-dep utility lane; demote from architectural poster framing in docs/help"
+    status: pending
+  - id: disk-clutter
+    content: "Optional hygiene — review leftover /Users/samprimeaux/agent-worktrees/* dirs (not linked worktrees; some 50–254MB clones)"
+    status: pending
+isProject: false
+---
+
+# Machine-first AgentSam — strengthen worlds in place
+
+## Intent (locked)
+
+**Audit and strengthen the current system. Do not redesign the repo around package purity.**
+
+Home: [`/Users/samprimeaux/agentsam-sdk`](/Users/samprimeaux/agentsam-sdk) @ clean `main` (`c017da3` Brand Intelligence).
+
+Preserve ownership:
+
+| Layer | Role |
+|-------|------|
+| `apps/*` | Product authoring SSOT — real worlds at uneven maturity |
+| `packages/*` | Reusable / packageable capability surfaces |
+| `protocol/*` | Portable contracts + evidence |
+| `src/*` | AgentSam runtime / CLI machinery |
+| `mini` | Intentionally tiny utility lane — **not** the architectural proof |
+
+**Proof already exists:** `local-studio`, `cad-creator`, `client-cms-editor`, `ecommerce-cms-agentsam`, seven harvested sites. Imperfection is maturity state, not exclusion:
+
+```text
+harvested → scaffolded → wired → verified → releasable → production
+```
+
+## Product scales
+
+```text
+MINI  — tiny local artifact, instant preview, seconds
+APP   — complete packaged product (npm install / agentsam app add), minutes
+WORLD — arbitrary repo → deterministic world state → progressive normalize
+```
+
+---
+
+## Branch audit — COMPLETE (2026-09-24)
+
+Repo now: **local `main` only**, synced to `origin/main` @ `c017da3`. No linked git worktrees besides the primary checkout.
+
+### Deleted (fully on main — tip == merge-base / 0 ahead)
+
+| Branch | Local | Remote | Notes |
+|--------|:-----:|:------:|-------|
+| `chore/package-release-system-20260923` | deleted | deleted | ancestor |
+| `feat/cad-project-tools-20260922` | deleted | deleted | + worktree removed |
+| `feat/feature-capability-snapshots-20260924` | deleted | deleted | ancestor |
+| `fix/local-studio-cms-resolution-and-route-map-20260924` | deleted | deleted | ancestor |
+| `integrate/identity-oauth-finish-20260924` | deleted | n/a | + worktree removed |
+| `integrate/unified-tool-provider-event-contracts-20260924` | deleted | deleted | + worktree removed |
+| `feat/unified-tool-provider-event-contracts-20260923` | n/a | deleted | cherry-`+` completeful commit superseded on main |
+| `feat/agentsam-queue-control-20260923` | n/a | deleted | 0 ahead / 33 behind |
+| `feat/goap-planner-backend` | n/a | deleted | 0 ahead / 112 behind |
+| `rescue/ecommerce-cms-untracked-20260919` | n/a | deleted | 0 ahead / 125 behind |
+
+### Errors-v1 claim — verified, then deleted
+
+| Branch | Ahead by SHA | Verdict |
+|--------|-------------:|---------|
+| `feat/errors-v1-runtime-contract` | 44 | Remotes already gone. Knowledge/Gemini/error adapter files **byte-identical to main** (reconcile via `976506d` / PR #53). Only `test/error-diagnostics.test.mjs` differed; **main is newer**. No unique work to cherry-pick. |
+| `integrate/errors-v1-main` | 40 | Same story; overlaps feat line. Deleted local tip. |
+
+### Remaining git branches
+
+**None** (besides `main` / `origin/main`).
+
+### Leftover disk (not git branches — optional hygiene)
+
+Under `/Users/samprimeaux/agent-worktrees/` (not registered with `git worktree list`):
+
+| Dir | Approx | Note |
+|-----|--------|------|
+| `agentsam-lab` | clone on `main` | separate checkout |
+| `agentsam-sdk` | clone **892 behind** origin/main | stale duplicate — safe delete candidate |
+| `auth-scoped-terminal-lanes` | ~55M | no `.git`; contains `AgentSamRemix` |
+| `cad-release` | empty | leftover shell |
+| `gemini-env` | ~53M | contains `inneranimalmedia` tree |
+| `mcp-account-owned-code-retrieve` | ~254M | MCP server tree |
+| `mcp-search-execute-stabilization` | ~254M | MCP server tree |
+| `memory-v2-contract` | ~2.3M | MCP server tree |
+
+These are **disk clutter**, not unfinished SDK feature branches. Clean when ready; not blocking Batch A–D.
+
+---
+
+## Logical batches of work left (on main)
+
+No branch merge queue. All remaining work is **new implementation on clean main**, grouped as:
+
+### Batch A — Machine Intelligence foundation
+**Todos:** `machine-intel-docs`, `decision-primitives`
+
+- `docs/MACHINE_INTELLIGENCE.md` + protocol schemas for predicate / choice / score / distribution + decision receipts
+- Shared AgentSam-owned primitives + confidence policy (confidence ≠ risk; abstention; hierarchical degrade)
+- Cross-link Brand Intelligence + ingestion as consumers of the same ladder
+- Framing: LLM is one handler inside AgentSam
+
+### Batch B — World-state + every app observable
+**Todos:** `world-state`, `app-maturity`, `verify-strengthen`
+
+- Converge Merkle / `repository.snapshot` / AST / brand / harvest / manifests into one **world-state** envelope
+- `agentsam inspect` works for arbitrary paths **and** every `apps/*`
+- Calculated maturity + provenance + hashes + capabilities + relationships + verify receipts + next actions
+- Strengthen `verify-package.mjs`, `verify-source-boundaries.mjs`, app contract tests, registry receipts
+- Prefer calculated facts over hand labels; imperfect apps stay included
+
+**Current app surface (proof targets, not toys):**
+
+| App | Manifest signal |
+|-----|-----------------|
+| `cad-creator` | `agentsam.app.json` + `.agentsam/app.json` |
+| `client-cms-editor` | same |
+| `ecommerce-cms-agentsam` | same |
+| `local-studio` | same |
+| `church-site` … `shinshu-site` (7 harvested) | `.agentsam/app.json` (theme-refinery) |
+| `theme-gallery-preview`, `frontend`, `_incoming` | maturity TBD via calculated gates |
+
+### Batch C — Ingest feeds world-state
+**Todos:** `ingest-on-worlds`
+
+- Paste / path / stdin → detect → extract → catalog → world-state
+- Sensitive candidates: confidence ≠ risk; redact before preview/model
+- Safe localhost gallery / Brand Packet = **projections** of world-state
+- Fixtures = harvested sites + real app slices (not mini, not toy repos)
+
+### Batch D — APP distribution + mini lane clarity
+**Todos:** `app-distribute`, `mini-keep-tiny`
+
+- Graduate curated apps toward `npm install @inneranimalmedia/<app>` / `agentsam app add`
+- Ship runtime/build/scaffold; exclude donor/reference junk
+- Keep mini as scaffold/preview/zero-dep utilities; demote from poster-child docs/help
+
+### Optional — Disk hygiene
+**Todo:** `disk-clutter`
+
+- Review/remove stale `agent-worktrees/*` clones (especially `agentsam-sdk` @ 892 behind)
+
+---
+
+## Architecture (unchanged)
+
+```mermaid
+flowchart TB
+  repo[Repository_or_App] --> scan[Deterministic_scanner]
+  scan --> files[files_hashes_MIME]
+  scan --> code[AST_routes_APIs]
+  scan --> assets[images_GLB_fonts_URLs]
+  files --> world[WORLD_STATE]
+  code --> world
+  assets --> world
+  world --> classify[Decision_primitives]
+  classify --> route[Confidence_policy_routing]
+  route --> next[Progression_next_actions]
+  world --> brand[brand.scan_consumer]
+  world --> preview[Local_gallery_optional]
+  world --> llm[LLM_only_on_ambiguity]
+```
+
+## Explicit non-goals
+
+- Repo redesign for package purity
+- New toy/demo apps as architectural proof
+- Requiring finished status before inclusion
+- TypeSafe/Jev dependency or product vocabulary
+- Mini as showcase
+- Auto-fetch remotes / auto-delete orphans / execute imported HTML
+- Jump every path to Level-4 LLM
+
+## Acceptance
+
+Without a model, AgentSam can:
+
+1. List every `apps/*` with calculated maturity + provenance + verify status
+2. `agentsam inspect` a harvested site and a serious app → world-state
+3. Answer what/where/contents/capabilities/reusable/missing/verified/next from receipts
+4. Expose decision primitives + a confidence-policy receipt on ≥1 classification path
+5. Keep `agentsam mini` working as the tiny lane
+6. Docs state machine-first ladder + MINI/APP/WORLD
+
+Suggested next execution: **Batch A** (docs + decision primitives), then **Batch B** against real apps.

package/docs/plugins.md

@@ -8,8 +8,8 @@ The first reusable connection is `@agentsam-mcp`:
 
 - `provider_key`: `cloudflare`
 - OAuth authority: Cloudflare OAuth (`c0704bd7a7aab7216b362603e1985499`)
-- token storage: the consuming Worker’s `agentsam_cloudflare_connections`,
-  encrypted with that Worker’s `VAULT_MASTER_KEY`
+- token storage: the consuming Worker’s `user_oauth_tokens`
+  (`provider=cloudflare`), sealed with that Worker’s `VAULT_MASTER_KEY`
 - tool keys: `agentsam-mcp.docs`, `agentsam-mcp.search`, and
   `agentsam-mcp.execute`
 

package/docs/product/AGENTSAM_PRODUCT_EXPERIENCE_STANDARD.md

@@ -0,0 +1,280 @@
+# AgentSam Product Experience Standard
+
+**Status:** Internal product law  
+**Applies to:** AgentSam SDK · Local Studio · packaged AgentSam apps · runtime surfaces · developer tooling  
+**Product:** `@inneranimalmedia/agentsam-sdk`  
+**Machinery:** SAM — **Systematic Autonomous Machinery**
+
+> **Complex underneath. Effortless above.**
+
+## Product posture
+
+AgentSam is a professional software platform, not a prototype dashboard, chatbot wrapper, or collection of demos. The UI communicates maturity through **clarity, speed, consistency, depth, and restraint**.
+
+A user should feel that the system is capable without being forced to look at all of the machinery that makes it capable.
+
+## Progressive discovery
+
+> **Reveal a capability when context makes it useful; do not advertise the entire machinery permanently.**
+
+This applies to terminals, runtimes, languages, forwarding, LSP, databases, cloud providers, CMS, CAD, machine inspection, identity, install/setup, and AgentSam itself.
+
+If only one healthy runtime exists, do not show a runtime picker. If a repository requires Go, surface Go when the user runs or inspects that repository. Context creates discovery.
+
+## Local Studio is a real desktop work application
+
+Local Studio is not a PWA pretending to be desktop software, a hosted website hidden behind a native wrapper, a bootstrap/status page users must escape before doing work, or a chatbot with tools bolted on.
+
+Expected launch path:
+
+```text
+Launch AgentSam Local Studio.app
+        ↓
+bundled Local Studio application
+        ↓
+restore last workspace/session
+        ↓
+local runtime becomes available quietly
+        ↓
+account/cloud/provider state hydrates without blocking local work
+```
+
+The shipped `.app` must boot directly into the real application interface. A thin **Open Studio UI / Stay on this shell** runtime-status page is a development or recovery fallback, not a shippable default.
+
+## Local-first contract
+
+Local functionality remains useful without authentication or network availability: files, local projects, SQLite, PTY/terminal, agentsamd, repository inspection, local language tooling, and installed local CAD/modeling integrations.
+
+Authentication enhances the product. It does not gate the user's computer.
+
+## Visual identity
+
+The default visual language is **quiet, dark, precise, desktop-native, and content-first**.
+
+Prefer near-black neutral work surfaces, restrained borders, compact chrome, crisp typography, careful spacing, small precise active states, limited iconography, contextual panels that disappear when closed, and motion that communicates state changes.
+
+Avoid particle effects as ordinary product chrome, glowing dashboard cards, pulsing status indicators, decorative telemetry, giant capability dashboards, nested cards without purpose, permanent status rails, and "AI is thinking" theater.
+
+Motion should be experienced as smoothness, not watched as entertainment.
+
+## Canonical layout modes
+
+### Focused work
+
+```text
+project/history rail | main work/chat | contextual editor/browser/details
+```
+
+### Code / file work
+
+```text
+project/history rail | editor/work surface | file tree/workspace/context
+```
+
+### Full workbench
+
+```text
+minimal nav | primary surface | optional contextual secondary pane
+```
+
+The active task owns the screen. Secondary panes support it.
+
+A user should move naturally among recent work, projects, Git worktrees, local folders, attached runtimes, containers, and future remote workspaces without needing to understand the transport underneath.
+
+## The work surface defines the experience
+
+Browsing should feel like a browser; coding like an editor; data work like a database editor; CMS work like a CMS; CAD work like CAD; terminal work like a terminal.
+
+AgentSam intelligence is contextual infrastructure, not permanent visual chrome.
+
+> Every capability should feel native to the surface where it is used.
+
+## Tabs, split panes, browser, and annotation
+
+Tabs are first-class desktop primitives. State should preserve and restore per workspace, split panes should feel like one application, and contextual panels should disappear completely when closed.
+
+The in-app browser is a serious work primitive, not an iframe preview.
+
+Annotation is a signature AgentSam interaction. A user should be able to select a real DOM element, code range, file, database object, CMS section, CAD object, browser region, artifact, runtime, or job and open a minimal contextual composer against that structured selection.
+
+AgentSam should know **what was selected**, not merely where the user clicked.
+
+## Terminal and runtime model
+
+Do not create separate terminal architectures for each language.
+
+```text
+terminal_instance   → where compute lives
+terminal_connection → how AgentSam reaches it
+terminal_session    → interactive PTY
+terminal_job        → detached/background work
+```
+
+Capabilities hang off the target:
+
+```text
+pty
+exec
+filesystem
+ports
+forwarding
+jobs
+lsp
+docker
+node
+python
+go
+rust
+freecad
+openscad
+blender
+```
+
+"Go service", "Rust task", "Python worker", and "Node dev server" are process profiles, not new PTY technologies.
+
+Forwarding should be first-class but mostly invisible. If a process exposes a port, Local Studio can offer **Open preview** and resolve forwarding underneath.
+
+## Databases
+
+AgentSam's own `.agentsam/data/agentsam.sqlite` is application state, not a claim that Local Studio supports only one SQLite database.
+
+User-owned SQLite is first-class: create/open arbitrary databases, attach/detach, CRUD, scoped SQL, duplicate/backup, rename/delete with confirmation, and offline operation.
+
+## Identity and storage authority
+
+Local Studio ships the AgentSam identity **UI and client contract** inside the app. The official connected AgentSam distribution does not create a second canonical account database on the device.
+
+```text
+packaged AgentSam auth UI
+        ↓
+identity_bridge
+        ↓
+configured identity service / Worker
+        ↓
+main account database
+```
+
+The installed app receives a native bearer session from the same identity service and keeps that credential in the platform secure store. The main database remains authoritative for account, user, session, grant, billing, membership, provider-connection, and other shared/cloud state.
+
+Device-local SQLite has a different authority:
+
+```text
+main DB        = account/shared/cloud truth
+local SQLite   = device/workspace/cache/offline-outbox/runtime truth
+secure store   = secret/credential truth
+```
+
+Do not dual-write canonical server records into SQLite. A local cached server record must be explicitly cache/sync state and disposable. Offline mutations to server-owned resources use an idempotent outbox and are committed through the Worker when connectivity returns.
+
+The portable identity package still supports an explicit standalone SQLite identity adapter for independent/offline products. That is a deployment choice, not the default authority of the official connected AgentSam download.
+
+Platform secure storage is a contract, not a macOS assumption: macOS uses Keychain; Windows uses Credential Manager; Linux uses the platform secret service; iOS and Android use their native secure-storage adapters.
+
+## External desktop escape hatches
+
+Useful actions include Open in Cursor, default app, Terminal, iTerm2, Reveal in Finder, Open on GitHub, and Save as.
+
+These are convenience paths. They do not replace Local Studio's own editor, PTY, browser, files, database, or runtime system.
+
+## Donor extraction and dependency direction
+
+InnerAnimalMedia is a donor and proving ground. It is not a runtime dependency of Local Studio.
+
+```text
+                  agentsam-sdk
+                      │
+          reusable packages/contracts
+                      │
+        ┌─────────────┼─────────────┐
+        ▼             ▼             ▼
+   Local Studio  InnerAnimalMedia  customer apps
+```
+
+Never make Local Studio import portable runtime/UI truth from the InnerAnimalMedia repository.
+
+Salvage proven UI, adapters, contracts, browser/editor/file behaviors, OAuth work, CMS mechanics, runtime patterns, and interaction components; remove InnerAnimalMedia-specific tenancy, branding, URLs, customer IDs, bindings, and deployment policy; land reusable ownership once in AgentSam SDK; let InnerAnimalMedia consume it through explicit adapters.
+
+Portability test:
+
+> Could a developer clone only `agentsam-sdk`, build/install Local Studio, and get the core experience without an `inneranimalmedia` checkout?
+
+For portable functionality, the answer must be yes.
+
+## Authority and registry discipline
+
+Do not flatten product, app, package, service, feature, capability, operation, tool, runtime, and install state into one registry.
+
+Preserve:
+
+```text
+APP
+apps/*/agentsam.app.json
+
+PACKAGE / SERVICE
+agentsam.package.json / package metadata
+
+FEATURE
+agentsam.feature.json
+
+CAPABILITY
+protocol/capabilities/manifest.json
+
+OPERATION
+protocol/sam/* + defineSamOperation()
+
+TOOL
+platform / MCP bounded registry
+
+RUNTIME
+agentsam.runtime.v1 + terminal_* state
+
+INSTALL
+.agentsam state + receipts
+```
+
+The official platform product inventory remains `agentsam_products` and its platform relationships.
+
+Any source-controlled `registry/products/*` layer is a **thin relationship/index seed**: product IDs, authority paths, host/mount relationships, service relationships, and platform linkage. It must not copy versions, commands, capability lists, runtime facts, or other fields already owned elsewhere.
+
+## Product quality bar
+
+Local Studio should feel deliberate, quiet, responsive, high-confidence, contextual, predictable, and deeply capable.
+
+Never gimmicky, demo-first, fake, capability-theater, or overloaded with status chrome.
+
+Infrastructure earns its value by making visible work reliable.
+
+## Acceptance rules
+
+1. **Real over fake** — no fake green states or pretend integrations.
+2. **Context over dashboards** — surface capabilities where they matter.
+3. **Local-first** — local work does not wait on account/cloud availability.
+4. **Progressive discovery** — advanced controls appear when useful.
+5. **One coherent product** — browser, files, editor, terminal, database, CMS, CAD, Work, and AgentSam share interaction language.
+6. **No permanent noise** — closed panels disappear.
+7. **Native platform behavior** — tabs/splits where appropriate, native file dialogs, OS secure storage, external-open actions, and platform-appropriate local capabilities.
+8. **Capability truth** — UI affordances derive from real runtime/provider capability.
+9. **Smoothness is functional** — animation reduces friction.
+10. **AgentSam remains contextual** — intelligence supports the work instead of competing with it.
+
+## Design test
+
+Before adding a permanent control, panel, badge, dashboard, runtime selector, or status surface, ask:
+
+```text
+Does the user need this visible right now?
+Can context reveal it later?
+Can the system infer this safely?
+Is it useful to the task, or merely proof that our backend exists?
+Would a mature professional application expose this continuously?
+```
+
+If the answer points toward hiding it, hide it.
+
+## North star
+
+> **A serious desktop work environment where browser, files, code, terminal, data, CMS, CAD, runtimes, cloud resources, and AgentSam intelligence behave as if they were designed together from the beginning.**
+
+AgentSam makes complex infrastructure feel simple without pretending the infrastructure is simple.
+
+That is the brand.

package/docs/product/LOCAL_STUDIO_DESKTOP_EXPERIENCE.md

@@ -0,0 +1,139 @@
+# Local Studio Desktop Experience Contract
+
+**Status:** Product acceptance contract  
+**App:** `local-studio`  
+**Desktop shell:** `packages/agentsam-desktop-shell`  
+**Canonical UI:** `apps/local-studio`
+**Identity package:** `packages/identity`
+
+The downloadable Local Studio app must look like Local Studio because it **is** Local Studio.
+
+## Launch contract
+
+Production:
+
+```text
+AgentSam Local Studio.app
+        ↓
+Tauri window
+        ↓
+bundled apps/local-studio desktop SPA
+        ↓
+real AgentSam shell / workspace
+```
+
+Not acceptable as a shipped default:
+
+```text
+bootstrap/status shell
+→ "Open Studio UI"
+→ hosted website
+```
+
+The packager must fail closed if the real desktop SPA is missing. It must never silently substitute a recovery page into a release artifact.
+
+Native capability startup (`agentsamd`, filesystem bridges, database bridges) happens in the background and must not cover the work surface with a diagnostic boot screen.
+
+## Packaged identity UI, shared account authority
+
+Local Studio packages the real AgentSam login/signup/reset UI inside the application. Displaying that UI does not require redirecting to a website.
+
+For the official connected AgentSam distribution, authentication writes to the configured identity service and main database:
+
+```text
+Local Studio / future mobile app
+        ↓
+bundled auth portal
+        ↓
+identity_bridge
+        ↓
+Worker identity API
+        ↓
+main account database
+```
+
+The Worker creates/resolves the canonical user and `auth_sessions` row. Native clients request the same session as a bearer credential rather than relying on a browser cookie. The credential is stored in the platform secure store and `/api/auth/me` validates it against the main database.
+
+There is no desktop-only account table and no duplicate canonical user/session authority.
+
+## Three storage authorities
+
+```text
+MAIN SERVICE / DB
+  accounts, users, auth sessions, OAuth grants, provider connections,
+  billing, memberships, shared/project/cloud records
+
+LOCAL SQLITE
+  installation/device metadata, workspace state, local projects, caches,
+  runtime/job state, sync cursors, offline outbox, user-opened SQLite DBs
+
+OS SECURE STORE
+  account session credential, device credentials, encryption keys,
+  machine-private provider secrets where policy allows
+```
+
+SQLite must not become a shadow copy of the main account database. Cached remote records are explicitly non-authoritative and disposable. Offline server-owned mutations are queued with idempotency keys and committed through the Worker.
+
+The portable identity package may use its SQLite identity adapter only when an installation explicitly selects standalone mode.
+
+## Platform contract
+
+The product contract is broader than macOS:
+
+- **macOS:** Tauri desktop, `agentsamd`, bundled JS bridge runtime, Keychain, POSIX shells.
+- **Windows:** Tauri desktop, `agentsamd`, bundled JS bridge runtime, Credential Manager, `pwsh` → Windows PowerShell → `cmd.exe`.
+- **Linux:** Tauri desktop, `agentsamd`, bundled JS bridge runtime, platform secret service, POSIX shells.
+- **iOS:** same UI/service/storage contracts through mobile-native adapters; no executable Node/`agentsamd` sidecar assumption.
+- **Android:** same UI/service/storage contracts through mobile-native adapters; no executable Node/`agentsamd` sidecar assumption.
+
+Desktop sidecars are an implementation of local-machine capabilities, not part of the cross-platform protocol. Mobile can connect to remote/local AgentSam runtimes where appropriate while keeping account identity and device state contracts unchanged.
+
+## Provider OAuth
+
+Provider grants are separate from the AgentSam account session. Google, Cloudflare, GitHub, GCP, and later providers use their own consent/connection lanes. A system browser may be required for a provider's OAuth consent, but the AgentSam login UI itself remains packaged in the app.
+
+Provider tokens never belong in callback URLs beyond the minimum standard authorization material, and confidential client secrets never belong in downloadable clients.
+
+## Session restoration
+
+```text
+secure store has AgentSam session credential?
+  no  → signed-out cloud/account state; local work remains available
+  yes → /api/auth/me with Bearer credential
+           valid   → canonical account restored from main DB
+           invalid → clear stale credential / signed out
+```
+
+Browser cookies are not required for desktop/mobile session restoration.
+
+## Failure behavior
+
+If a provider, remote account service, or network connection fails, Local Studio remains usable locally.
+
+Ordinary local workflows must never be replaced by a full-screen authentication or infrastructure error.
+
+## Release acceptance
+
+Before shipping a desktop artifact:
+
+- build the Local Studio desktop SPA;
+- copy the packaged auth portal into that SPA;
+- verify the auth portal is AgentSam/host branded rather than donor branded;
+- sync the SPA into the Tauri desktop shell;
+- fail the build if the real SPA is missing or hydrate-only;
+- verify the old `Open Studio UI` / `Stay on this shell` copy is absent;
+- verify native startup work is non-blocking;
+- run the full identity package tests;
+- run Local Studio auth/type/build gates;
+- run Rust checks;
+- verify the packaged identity runtime/migrations are present;
+- build and mount the disk image;
+- launch the app copied from the disk image;
+- verify local signup/login/session restoration without a hosted redirect;
+- verify local files, SQLite, PTY, and `agentsamd` still work signed out.
+
+## Product rule
+
+> **The downloadable Local Studio app is self-contained AgentSam product software.**
+
+Company deployments, customer hosts, and external identity providers are adapters around that product. They are not its intrinsic authority.

package/docs/product/README.md

@@ -0,0 +1,8 @@
+# AgentSam Product Standards
+
+These documents define product-facing laws above implementation-specific architecture.
+
+- [AgentSam Product Experience Standard](./AGENTSAM_PRODUCT_EXPERIENCE_STANDARD.md) — brand posture, visual/interaction language, progressive discovery, Local Studio quality bar, runtime UX, donor extraction, and authority discipline.
+- [Local Studio Desktop Experience Contract](./LOCAL_STUDIO_DESKTOP_EXPERIENCE.md) — launch behavior, bundled UI, desktop OAuth/Keychain behavior, handoff security, and release acceptance.
+
+Architecture contracts remain authoritative for their own namespaces, including `docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md` and `docs/architecture/SAM_KERNEL.md`.