@inneranimalmedia/agentsam-sdk 2.6.10 → 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

@@ -0,0 +1,140 @@
+# Dual Analytics Product Architecture
+
+## Non-negotiable boundary
+
+Commerce analytics and AgentSam runtime analytics are both first-class products.
+
+Do not collapse ecommerce into AgentSam telemetry merely because AgentSam can
+measure AI cost or execute ecommerce work.
+
+```text
+                    @inneranimalmedia/analytics-ui
+                   /                                                /                                @inneranimalmedia/commerce-analytics    @inneranimalmedia/agentsam-analytics
+        |                                         |
+revenue/orders/products/customers          runs/tools/models/GOAP
+conversion/COGS/cohorts/AOV                waits/retries/cost/scores
+store health + AI attribution              runtime health + priors
+```
+
+## Commerce stays commerce-owned
+
+Examples:
+
+- gross revenue
+- orders
+- average order value
+- units sold
+- product mix
+- conversion funnel
+- customer cohorts
+- repeat customer rate
+- pending/refunded share
+- estimated COGS
+- gross margin
+- commerce infrastructure health
+- AgentSam AI spend attributable to commerce operations
+
+An order is not an AgentSam event.
+A customer is not a model run.
+Revenue is not a generic reward signal.
+
+## AgentSam runtime analytics stays runtime-owned
+
+Examples:
+
+- run/tool/model events
+- GOAP transitions
+- verification gates
+- test results
+- duration
+- active model time
+- queue wait
+- external wait
+- retries
+- token usage
+- provider/model cost
+- failure origin
+- artifact references
+- versioned score families
+
+## Correlation, not collapse
+
+The domains may correlate through stable identifiers such as:
+
+- account_id
+- tenant_id
+- run_id
+- receipt_id
+- source_id
+- dimensions.order_id
+- dimensions.product_id
+- dimensions.customer_id
+- dimensions.campaign_id
+
+This enables useful cross-domain questions:
+
+- AI cost per fulfilled order
+- image-generation cost per sellable product
+- merchandising automation cost vs gross margin
+- support-agent cost per resolved commerce incident
+- test/deploy cost per storefront release
+
+## Storage/read path
+
+```text
+meaningful AgentSam operation
+        |
+        v
+emitAnalyticsFact()
+        |
+        +--> agentsam_analytics (D1 hot fact authority)
+        |
+        +--> AGENTSAM_ACTIVITY -> Basin -> Iceberg/Parquet
+```
+
+Commerce continues to use commerce-owned operational and aggregate sources.
+
+UI reads stable read models, never raw tables directly.
+
+## Visual grammar
+
+Ember Supply remains the donor:
+
+- light application shell
+- dark analytical cards
+- compact KPI row
+- dense tables
+- range selector
+- status indicators
+- sparklines
+- time-series charts
+- health/incident views
+
+AgentSam surfaces:
+- Overview
+- Usage & Cost
+- Performance
+- Health
+- Scores
+
+Commerce surfaces stay intact and can grow:
+- Overview
+- Finance
+- Health
+- Merch
+- Products
+- Customers
+- Fulfillment
+- Marketing
+- AI Cost Attribution
+
+## Instrumentation law
+
+Do not instrument every helper.
+
+Instrument meaningful boundaries that consume:
+time, tokens, paid APIs, compute, I/O, network, queue capacity, storage,
+external quota, or durable state mutation.
+
+Raw facts are evidence.
+Scores are recomputable interpretations.

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
 
@@ -260,7 +260,7 @@ forces a package change, the seam is wrong.
 
 | Field | Value |
 |---|---|
-| Worktree | `/Users/samprimeaux/agent-worktrees/content-studio-audit` |
+| Worktree | `worktree://content-studio-audit` |
 | Branch | `audit/agentsam-content-studio-transplant-20260927` |
 | Base head | `28ef451` (transplant on main) |
 | Brand audit | `/tmp/agentsam-brand-authority-audit.json` |

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/engineering/go-portability/01-product-project-deployment-authority.md

@@ -0,0 +1,69 @@
+# AgentSam Go Product / Project / Deployment Authority
+
+## Product
+
+`@inneranimalmedia/agentsam-go-worker` is a distributable AgentSam product.
+
+The portable package owns source code and the generic Cloudflare Worker +
+Container configuration.
+
+It does not own a customer's Cloudflare account, domain, or mutable project
+state.
+
+## Project instance
+
+Mutable AgentSam Go state belongs to the caller repository:
+
+`<project>/.agentsam/go/`
+
+This rule applies equally to maintainers and third-party users.
+
+Product source must not become state authority merely because it was discovered
+from the SDK repository.
+
+## Deployment
+
+A deployment belongs to the Cloudflare account selected by the current user.
+
+The published portable config:
+
+`apps/agentsam-go-worker/wrangler.jsonc`
+
+must not contain InnerAnimalMedia's production hostname.
+
+InnerAnimalMedia production deployment is a separate explicit maintainer path:
+
+`apps/agentsam-go-worker/wrangler.inneranimalmedia.jsonc`
+
+That file is intentionally excluded from the npm package `files` contract.
+
+## Invariants
+
+- `runtime.inneranimalmedia.com` is Sam's deployment, not the AgentSam Go product.
+- self-host mode uses `wrangler.jsonc`
+- official release mode uses `wrangler.inneranimalmedia.jsonc`
+- self-host state belongs to the caller project
+- maintainer state follows the same caller-project rule
+- no live deployment is performed by portability tests
+
+
+## Receipt location
+
+Interactive `agentsam go` asks the operator where run receipts/state should live.
+
+Supported choices:
+
+- project-local
+- central `~/.agentsam/receipts/<project>`
+- custom directory
+
+Non-interactive callers may use:
+
+`--receipt-root <path>`
+
+Distribution verification remains offline by default. Ambient Cloudflare
+credentials do not enable remote/container verification. Explicit opt-in is:
+
+`AGENTSAM_VERIFY_GO_CLOUDFLARE=1`
+
+Dry-run and skip-deploy lanes must never execute Docker.

package/docs/engineering/provider-internal-renames/01-lane-initialization.md

@@ -0,0 +1,20 @@
+# Stage 01 — Lane Initialization
+
+## Change
+
+Created a clean worktree from `origin/main` for the Work Suite
+graduation and provider-internal rename pass.
+
+## Reason
+
+The ordinary SDK checkout may contain unrelated work. Mechanical
+provider renames need an isolated ancestry so later functional work
+has a trustworthy base.
+
+## Acceptance
+
+- clean dedicated worktree
+- dedicated feature branch
+- rename policy documented before code mutation
+- auth/provider authority explicitly documented
+- no production/runtime provider contracts changed