@inneranimalmedia/agentsam-sdk 2.6.11 → 2.6.12

package/docs/adr/ADR-0003-product-portfolio-and-package-taxonomy.md

@@ -0,0 +1,146 @@
+# ADR: AgentSam Product Portfolio and Package Taxonomy
+
+**Status:** Accepted
+**Decision type:** Product / architecture / packaging
+**Applies to:** `agentsam-sdk`, public packages, Local Studio, packaged apps, plugins, hosted runtimes, themes, adapters
+
+## Context
+
+`agentsam-sdk` contains many public npm packages and several apps. That does not mean every package should become a standalone product or commercial offer.
+
+Without an explicit taxonomy, package names can accidentally become product names, infrastructure can be marketed as a feature, provider adapters can become false product boundaries, and closely related capabilities can fragment into weak offers.
+
+## Decision
+
+AgentSam uses four portfolio layers:
+
+1. **Offers / products** - user-recognizable solutions with a clear problem, workflow, outcome, and commercial reason to exist.
+2. **Domain engines / product packages** - reusable deterministic capabilities that power one or more offers.
+3. **Shared primitives / infrastructure** - contracts, errors, vault, hooks, work graph, scoring, queueing, navigation, shell, and similar machinery.
+4. **Adapters / themes / providers** - provider-specific integrations and reusable presentation packages that remain subordinate to the product experience.
+
+A package is not automatically a product.
+
+A product may compose multiple packages.
+
+A package may support multiple products.
+
+## Offer criteria
+
+A standalone AgentSam offer should have:
+
+- a recognizable user problem;
+- a coherent end-to-end workflow;
+- an outcome a user would intentionally seek;
+- a defined data/authority boundary;
+- graceful behavior when evidence is incomplete;
+- a product surface appropriate to its host;
+- acceptance cases that prove more than component existence;
+- a plausible acquisition, packaging, or monetization path.
+
+If those conditions are not met, the capability remains a package or supporting subsystem.
+
+## Product portfolio
+
+The current aspirational portfolio is:
+
+```text
+AgentSam Platform / SDK
+  |
+  +-- AgentSam Local Studio
+  +-- AgentSam Work
+  +-- AgentSam Brand
+  +-- AgentSam Campaign
+  +-- AgentSam Content Studio
+  +-- AgentSam Database Studio
+  +-- AgentSam Browser
+  +-- AgentSam Analytics
+  +-- AgentSam Knowledge
+  +-- AgentSam Merch
+  +-- AgentSam CAD Studio
+  +-- AgentSam Commerce Studio
+  +-- AgentSam Site Studio
+  +-- AgentSam Developer Studio
+  +-- AgentSam Hosted Runtime
+```
+
+These offers are allowed to share primitives while keeping their product identity distinct.
+
+## Package taxonomy
+
+Examples of **domain/product packages**:
+
+- `@inneranimalmedia/agentsam-brand`
+- `@inneranimalmedia/agentsam-campaign`
+- `@inneranimalmedia/agentsam-content`
+- `@inneranimalmedia/agentsam-content-studio`
+- `@inneranimalmedia/agentsam-database-editor`
+- `@inneranimalmedia/agentsam-analytics`
+- `@inneranimalmedia/agentsam-knowledge`
+- `@inneranimalmedia/agentsam-merch`
+- `@inneranimalmedia/agentsam-work`
+- `@inneranimalmedia/agentsam-abs`
+- `@inneranimalmedia/agentsam-browser-surface`
+- `@inneranimalmedia/agentsam-ide`
+
+Examples of **shared primitives**:
+
+- `@inneranimalmedia/agentsam-contracts`
+- `@inneranimalmedia/agentsam-errors`
+- `@inneranimalmedia/agentsam-hooks`
+- `@inneranimalmedia/agentsam-goap`
+- `@inneranimalmedia/agentsam-queue-control`
+- `@inneranimalmedia/agentsam-repository`
+- `@inneranimalmedia/agentsam-scoring`
+- `@inneranimalmedia/agentsam-vault`
+- `@inneranimalmedia/agentsam-workbench`
+- `@inneranimalmedia/agentsam-work-graph`
+- `@inneranimalmedia/agentsam-settings`
+- `@inneranimalmedia/agentsam-shell-kit`
+- `@inneranimalmedia/agentsam-nav`
+- `@inneranimalmedia/agentsam-assets-core`
+
+Examples of **adapters/providers**:
+
+- `@inneranimalmedia/agentsam-cloudflare-images`
+- `@inneranimalmedia/agentsam-provider-completeful`
+- `@inneranimalmedia/agentsam-connector-cloudflare`
+- future commerce, analytics, identity, storage, model, and deployment adapters.
+
+Examples of **themes/prebuilds**:
+
+- `theme-cypress`
+- `theme-ember`
+- `theme-forge`
+- `theme-grove`
+- `theme-harbor`
+- `theme-heuristic`
+- `theme-iasf`
+- `theme-resolve`
+- `theme-scenes`
+- `theme-summit`
+- `theme-violet`
+
+These are sellable assets or ingredients, but they are not separate AgentSam domain authorities.
+
+## Consequences
+
+- Product naming is based on user value, not package internals.
+- Provider names remain implementation details unless the user explicitly chooses that provider.
+- Shared primitives should become stronger, not get duplicated inside each offer.
+- New packages require an explicit placement in the taxonomy.
+- PRDs are created for offers; ADRs govern cross-offer authority and composition.
+
+## Rejected alternatives
+
+### Every npm package is a product
+
+Rejected because it creates weak, confusing offers and exposes implementation structure as product strategy.
+
+### One giant AgentSam application owns everything
+
+Rejected because it collapses clear domain authorities and makes portability, plugins, distribution, and independent evolution harder.
+
+### Provider-specific products by default
+
+Rejected because AgentSam should remain provider-neutral and user-recognizable at the product layer.

package/docs/adr/ADR-0004-product-composition-and-provider-neutrality.md

@@ -0,0 +1,56 @@
+# ADR: AgentSam Product Composition and Provider Neutrality
+
+**Status:** Accepted
+**Decision type:** Architecture / product boundary
+**Applies to:** all AgentSam offers, packages, adapters, plugins, hosted and desktop surfaces
+
+## Decision
+
+AgentSam products compose through stable domain contracts and shared primitives. Provider-specific systems remain adapters underneath user-recognizable product operations.
+
+The canonical direction is:
+
+```text
+user goal
+   |
+   v
+AgentSam product
+   |
+   v
+domain contract / capability
+   |
+   +-- provider adapter A
+   +-- provider adapter B
+   +-- local implementation
+   +-- hosted implementation
+```
+
+A product must not become synonymous with one provider when the underlying user problem is provider-independent.
+
+## Rules
+
+1. Product names describe user value, not infrastructure.
+2. Packages expose portable contracts before host-specific glue.
+3. Provider credentials remain scoped to the adapter that needs them.
+4. Raw provider capabilities are not automatically exposed as public AgentSam tools.
+5. Hosted and local implementations should share domain semantics where practical.
+6. Apps may compose packages but must not silently fork their contracts.
+7. External writes require explicit authorization, bounded scopes, and receipts where practical.
+8. A provider outage should degrade the affected capability, not redefine the product.
+
+## Examples
+
+Campaign may consume commerce data, but does not become Shopify, Completeful, or another commerce provider.
+
+Content may deliver through Cloudflare Images or another image service, but Content remains the user-facing domain.
+
+Database Studio may connect to SQLite, D1, Postgres, or Supabase while preserving a provider-neutral database workflow.
+
+Browser may use multiple model providers while preserving one Browse/Build product surface.
+
+## Consequences
+
+- New provider integrations should be implemented as adapters/connectors.
+- PRDs must describe the user workflow independently of one provider.
+- Public plugin surfaces should expose product verbs rather than raw provider APIs.
+- Tests should include provider substitution or missing-provider behavior where relevant.

package/docs/adr/ADR-0005-offer-graduation-standard.md

@@ -0,0 +1,66 @@
+# ADR: AgentSam Offer Graduation Standard
+
+**Status:** Accepted
+**Decision type:** Product quality / release governance
+**Applies to:** any AgentSam package or app proposed as a real-world product, plugin, paid feature, or standalone offer
+
+## Context
+
+AgentSam has many strong components. A component becomes commercially meaningful only when it solves an end-to-end user problem reliably.
+
+## Decision
+
+An AgentSam capability graduates into a real offer only after it satisfies the following gates.
+
+## Gate 1 - Clear user problem
+
+The offer has a defined user, painful job, expected outcome, and explicit non-goals.
+
+## Gate 2 - Complete workflow
+
+The user can reach the promised outcome without stitching together undocumented package internals.
+
+## Gate 3 - Authority and evidence
+
+The offer knows which data it owns, which data it consumes, which facts are observed, and which outputs are inferred or proposed.
+
+## Gate 4 - Portability
+
+The core domain capability is reusable across appropriate hosts and is not unnecessarily tied to one customer's app, provider, or deployment.
+
+## Gate 5 - Trust
+
+Authentication, authorization, approvals, secret handling, error behavior, and write boundaries are explicit.
+
+## Gate 6 - Quality
+
+The offer has direct, indirect, sparse-context, rich-context, negative, failure, and out-of-scope acceptance cases.
+
+## Gate 7 - Product experience
+
+The offer has coherent naming, onboarding, defaults, empty states, progress, failure recovery, accessibility, and responsive behavior appropriate to its host.
+
+## Gate 8 - Operations
+
+The offer has versioning, health, telemetry, logs, receipts where needed, upgrade behavior, and support/debugging paths.
+
+## Gate 9 - Distribution
+
+The offer has a defined delivery form such as npm package, desktop app, hosted app, plugin, template, runtime, or service.
+
+## Gate 10 - Commercial value
+
+There is a plausible reason a user or organization would adopt or pay for the outcome rather than merely admire the technology.
+
+## Status vocabulary
+
+- **Primitive** - internal/reusable machinery.
+- **Experimental** - useful capability under active product discovery.
+- **Alpha** - end-to-end workflow exists, still changing materially.
+- **Beta** - stable enough for external users with known limitations.
+- **v1** - coherent supported offer meeting its acceptance criteria.
+- **Deprecated** - being removed or replaced.
+
+## Consequence
+
+Package publication alone does not equal product graduation.

package/docs/adr/README.md

@@ -0,0 +1,25 @@
+# Architecture Decision Records
+
+Use ADRs for durable architecture, trust-boundary, authority, portability, and product-boundary decisions.
+
+## Convention
+
+- File names: `ADR-NNNN-short-decision-name.md`
+- Status values: `Proposed`, `Accepted`, `Superseded`, `Deprecated`
+- Prefer one coherent decision per ADR.
+- Record context, the decision, consequences, invariants, and rejected alternatives.
+- Do not rewrite accepted history to reflect a new decision. Add a new ADR and mark the old one superseded.
+- Cross-repo decisions should use the same ADR number and title where practical.
+- Numbering may therefore have gaps in a repo when an earlier ADR primarily lives in another AgentSam repo.
+
+## Current ADRs
+
+- `ADR-0002-brand-campaign-plugin-boundaries.md` — Brand/Campaign ownership, composition, data authority, and public MCP boundary.
+
+ADRs describe **why the system is shaped this way**. Product behavior and acceptance criteria belong in PRDs.
+
+## Portfolio ADRs
+
+- `ADR-0003-product-portfolio-and-package-taxonomy.md`
+- `ADR-0004-product-composition-and-provider-neutrality.md`
+- `ADR-0005-offer-graduation-standard.md`

package/docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md

@@ -122,7 +122,7 @@ apps/<app-id>/
 | `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.
+Same APP installed into Ember Supply, Companions CPAs, InnerAnimalMedia, or a customer localhost keeps the same `APP.id`. `.agentsam/` describes **this** installation.
 
 ## Physical shape
 

package/docs/architecture/DUAL_ANALYTICS_PRODUCT.md

@@ -98,7 +98,7 @@ UI reads stable read models, never raw tables directly.
 
 ## Visual grammar
 
-Fuel & Free Time remains the donor:
+Ember Supply remains the donor:
 
 - light application shell
 - dark analytical cards

package/docs/content-studio/HOST_MOUNT_CHECKLIST.md

@@ -7,7 +7,7 @@ are Path B / host-app work — do **not** fork packages per host.
 
 Each host supplies a `ContentRuntime` via `createContentRuntime({...})`:
 
-| Seam | Local Studio | IAM dashboard | Fuel & Free Time (customer) |
+| Seam | Local Studio | IAM dashboard | Ember Supply (customer) |
 |---|---|---|---|
 | `account` / `actor` | desktop session | IAM auth session | customer tenant session |
 | `providers` / capability adapters | local + optional CF | R2 / Images / Drive / Stream | customer-scoped providers |

package/docs/content-studio/REVISION_GATE_2026-09-27.md

@@ -3,7 +3,7 @@
 **Acceptance sentence (every package):**
 
 > Could this exact capability be consumed tomorrow by Local Studio, IAM,
-> Fuel & Free Time, and an unknown customer app without modifying the package?
+> Ember Supply, and an unknown customer app without modifying the package?
 
 If the answer is no because of branding, routes, credentials, storage, RAG,
 or a hardcoded provider — it is not finished.
@@ -237,12 +237,12 @@ Scan output must produce **actionable proposals** (package-readiness scores, tok
 
 ## Severity / product context
 
-Paying customer galleries (e.g. Fuel & Free Time) underperform vs the donor
+Paying customer galleries (e.g. Ember Supply) underperform vs the donor
 gallery that already includes R2, Google Drive, Cloudflare Images, tagging,
 editing, multi-size variants, and inspect. The same portable gallery must
 serve **at least three hosts without forks**:
 
-1. Fuel & Free Time (customer)
+1. Ember Supply (customer)
 2. Inner Animal Media platform dashboard
 3. AgentSam Local Studio
 

package/docs/contracts/google-cloud-oauth-setup.md

@@ -128,7 +128,7 @@ APIs & Services → OAuth consent screen:
   - `profile`
   - For Cloud resource discovery later: add Cloud Platform scopes only when Connections needs them (`https://www.googleapis.com/auth/cloud-platform` is powerful — prefer incremental scopes)
 
-Publishing status: **Testing** while iterating; add test users (you, Connor).
+Publishing status: **Testing** while iterating; add test users (you, Operator).
 
 ### 3. Create OAuth client
 

package/docs/local-studio/WORKMODE_DONOR_NOTES.md

@@ -7,7 +7,7 @@ AgentSam Workmode ( agent reading this-- we will clone/repackage the build menti
 Calm vibecode bench: persistent trails, helper chats, in-app browser, Monaco, xterm CLI, projects/artifacts, model picker, and GitHub / Cloudflare ship.
 
 Repo: SamPrimeaux/AgentSam-Grok-Workmode
-Account ID: ede6590ac0d2fb7daf155b35653457b2
+Account ID: demo-commerce-account
 Canonical D1: inneranimalmedia-business (cf87b717-d4e2-4cf8-bab0-a81268e32d49)
 Product domain: https://simple.inneranimalmedia.com
 UI Worker: agentsam-grok-workmode → https://agentsam-grok-workmode.meauxbility.workers.dev
@@ -55,7 +55,7 @@ Docs: agentsam-sdk
 Deploy / bind Cloudflare Worker + D1
 Account + database (SSOT)
 Binding	Value
-Account ID	ede6590ac0d2fb7daf155b35653457b2
+Account ID	demo-commerce-account
 Account	Inner Animal Media Cloudflare account
 D1 name	inneranimalmedia-business
 D1 UUID	cf87b717-d4e2-4cf8-bab0-a81268e32d49
@@ -73,7 +73,7 @@ Auth for Wrangler (never commit tokens)
 npx wrangler login
 
 # or export a scoped API token in your shell only
-export CLOUDFLARE_ACCOUNT_ID="ede6590ac0d2fb7daf155b35653457b2"
+export CLOUDFLARE_ACCOUNT_ID="demo-commerce-account"
 export CLOUDFLARE_API_TOKEN="<token-with-workers+d1>"
 On the IAM Mac desk, prefer the monorepo env wrappers instead of pasting tokens into chat:
 

package/docs/plans/ASTRA-BRIEF-2026-09-18.md

@@ -57,7 +57,7 @@ and `origin/main` before acting.
    detection genuinely fails. Both `wizards/cms.js` and
    `wizards/worker-api.js` now call this instead of a raw `text()` prompt
    asking the user to hand-paste an ID that `agentsam cloudflare` already
-   knows. Verified live: resolves to `ede6590ac0d2fb7daf155b35653457b2`
+   knows. Verified live: resolves to `demo-commerce-account`
    ("Info@inneranimals.com's Account") with zero prompts.
 3. **`src/lib/scaffold/templates/worker-api/index.js` +
    `templates/cms/index.js` + `templates/wrangler-dev/...`** (3 templates

package/docs/plans/LOCAL-STUDIO-REAL-APP-CONTRACT-ADDENDUM-2026-09-27.md

@@ -221,7 +221,7 @@ There is no fourth category: “looks finished but doesn’t do anything.”
 
 Surfaces currently represented (must eventually be REAL or withheld): AgentSam/chat, Library, Sites/CMS, CAD, Database, Projects, Settings (Account, Agents, Customize, Brand & Design, Git & PRs, Codebase, Browser & Network, Themes, Storage, Keys & Secrets, Plan & Usage, Notifications, Docs), terminal/runtime controls.
 
-Themes cards (AgentSam Graphite, Fuel N Free, Shinshu, …) must become discovered/installed theme projections — not permanent hard-coded gallery fakes. Healthy badges and Local account must derive from real checks/identity.
+Themes cards (AgentSam Graphite, Ember Supply, Shinshu, …) must become discovered/installed theme projections — not permanent hard-coded gallery fakes. Healthy badges and Local account must derive from real checks/identity.
 
 ### Library vs Sites → Media
 
@@ -324,7 +324,7 @@ Do **not** hand-patch the generated file. Do **regenerate** via normal `npm run
 
 #### 8. FnF migration
 
-Keep Fuel & Free Time migration **separate** until Local Studio acceptance for this slice passes. Then migrate FnF onto the same Content Studio package/runtime — do not recreate.
+Keep Ember Supply migration **separate** until Local Studio acceptance for this slice passes. Then migrate FnF onto the same Content Studio package/runtime — do not recreate.
 
 ### Minimum acceptance test (this media feature)
 

package/docs/plans/MACHINE-FIRST-APPS-TUI-2026-09-24.md

@@ -132,7 +132,7 @@ Calculated maturity gates (facts, not labels):
 - `verify-package` / `verify-source-boundaries`: keep; add app-level contract checks invoked by `agentsam app doctor` and maturity.
 - Imperfect apps stay listed; failures become receipts on the catalog row.
 
-**Acceptance B:** `agentsam inspect apps/cad-creator` and `agentsam inspect apps/church-site` both emit world-state; `agentsam app list --json` shows maturity for every `apps/*`.
+**Acceptance B:** `agentsam inspect apps/cad-creator` and `agentsam inspect apps/cypress` both emit world-state; `agentsam app list --json` shows maturity for every `apps/*`.
 
 ---
 

package/docs/plans/NEXT-AGENT-HANDOFF.md

@@ -79,7 +79,7 @@ Hard rules (unchanged):
 - Never return secrets to the browser.  
 - Never silently swap providers (no XAI→OpenAI).  
 - Selection stays `{ provider, model_id }`.  
-- Sam’s machine `env.d` ≠ Connor’s Studio options.
+- Sam’s machine `env.d` ≠ Operator’s Studio options.
 
 Worker already has vault routes + `GET /api/llm/inventory` provenance.  
 TanStack `/api/llm/inventory` + `/api/chat` currently use **platform** via
@@ -139,7 +139,7 @@ hint / paste-collapse / shimmer if still open — extend, don’t rebuild.
 | Project SQLite storage / no default DOs | Done (PR #51) |
 | `agentsam help all` | Works on main |
 | Cursor machine discovery | Done on this branch |
-| Static Studio Grok-only menu | Replaced on this branch |
+| Static Studio requires the configured Grok provider menu | Replaced on this branch |
 | `agentsam app` manifests | Done on this branch |
 | npm publish / surprise deploy | Forbidden without Sam |