@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

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
+
+Fuel & Free Time 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/architecture/HOOKS-MODELS-SELF-HOSTING-PLAN.md

@@ -0,0 +1,199 @@
+# Hooks, model inventory, and self-hosting plan
+
+Status: active implementation plan (2026-10-02)
+
+## Decisions
+
+### Hooks are one runtime concept
+
+AgentSam has one lifecycle event catalog, one output merge algorithm, and one
+receipt format. It has multiple **authoring sources**, not multiple kinds of
+hook:
+
+| Source | Authored in | Dashboard/CLI behavior | Durable definition row |
+|---|---|---|---|
+| `code` | SDK registration | visible, read-only | no |
+| `config` | `agentsam.hooks.json` or `.agentsam/hooks.json` | visible, file-owned | no |
+| `stored` | CLI/API/dashboard | visible and mutable | `agentsam_hook` |
+| `system` | AgentSam runtime | visible, read-only | only when a host intentionally materializes it |
+
+React hooks (`useAgentHooks`, `useHookList`) are UI implementation details and
+must never be called lifecycle hooks in product copy.
+
+Dispatch order is priority, then hook key. Source does not create a second
+semantics path. A source badge answers where to edit a definition. Execution
+receipts from all sources go to the same `agentsam_hook_execution` projection.
+
+### Portable ownership is owner + optional scope
+
+The portable hook schema deliberately has no `tenant_id`, `workspace_id`,
+`user_id`, `person_uuid`, or installation-specific foreign keys.
+
+- `owner_id` is an opaque host/account/local owner key.
+- `scope_type` is `global`, `account`, `repository`, `project`, or `session`.
+- `scope_ref` contains the corresponding opaque id/path when needed.
+- `agent_run_id`, `session_id`, and `conversation_id` are the common execution
+  correlations.
+- Rare correlations (plan, todo, workflow run, command run, route) belong in
+  `correlation_json`, not a permanently sparse column set.
+- `workflow_id` is a soft reference on the definition. The hook pack remains
+  installable without a workflow table family.
+- Handler credentials are references resolved by the host. They are never
+  values in `handler_config_json`.
+
+The canonical fresh-install SQL is
+`migrations/runtime/0005_agentsam_hooks.sql`. The standalone hooks package
+ships a generated byte-identical copy plus `schema/manifest.json`.
+
+Existing hosted tables with required `user_id` or tenant/workspace columns are
+**not** silently rebuilt. The hosted owner must inspect references and run an
+explicit copy/verify/swap migration. Portable initialization is idempotent and
+will not guess that `user_id` equals an account owner.
+
+### The existing model surfaces keep their jobs
+
+No new per-model-per-user table is introduced.
+
+| Existing surface | Authority |
+|---|---|
+| `src/models/catalog.js` / hosted `agentsam_model_catalog` | curated provider-qualified reference capabilities; never credential availability |
+| `agentsam_model_pricing` | global/versioned reference pricing |
+| `agentsam_plugins` with `plugin_kind='ai'` | one installation per account/environment/provider/credential reference; health and last good credential-scoped model snapshot |
+| `user_secrets` / machine vault | provider secret material; never model metadata |
+| `agentsam_api_credentials` | authentication to AgentSam itself; never provider keys |
+| `agentsam_model_eval_observations` | eval evidence; not a portable customer model catalog |
+
+A successful provider probe writes a compact
+`agentsam.provider-model-snapshot.v1` object into the AI plugin row's
+`metadata_json.model_snapshot`. It contains sorted model ids, count, hash, and
+fetch time. `recordAiPluginModelDiscovery` writes it through the existing
+plugin registry and health-check log. A failed probe updates health evidence
+but preserves the last good snapshot. Secret values and hashes of secret values
+are never included.
+
+The provider API remains the availability authority at use time. A snapshot is
+stale-while-revalidate evidence for UI convenience, not an authorization gate.
+Reference catalog enrichment is never an availability claim. Unknown models
+continue to work with unknown/reference capabilities where the adapter can use
+them.
+
+Provider/model identity is the pair `(provider, provider_model_id)`. The SDK's
+`model_key` already encodes that pair (`openai:gpt-…`, `cursor:…`). Hosted SQL
+must use `UNIQUE(provider, model_key)` (or a provider-qualified `model_key`),
+not global `UNIQUE(model_key)`. Provider ids should match SDK canonical ids:
+`openai`, `anthropic`, `gemini`, `xai`, `cursor`, `cloudflare`, and `ollama`.
+Display names are not ids.
+
+## Product and CLI experience
+
+`agentsam hooks` and `/hooks` are the factual control surface:
+
+- `status` — source counts, project config, and stored registry health.
+- `list` — merged dispatch order with source, handler, state, and priority.
+- `executions` — recent value-free receipts and redacted failures.
+- `validate` — portable config validation.
+- `init` — idempotently creates `.agentsam/hooks.json`.
+- `enable` / `disable` — toggles stored definitions only.
+
+The dashboard should consume the same status/list/execution projection. It must
+not maintain a second event list or merge algorithm. Code rows are read-only;
+config rows link to their source file; stored rows expose full editing. A future
+priority/disable override for code hooks must be an explicit overlay keyed by
+`(owner_id, source_kind, hook_key)`, not a copied code definition.
+
+The model picker follows a similar provenance rule:
+
+1. show models discovered for the selected plugin/credential installation;
+2. enrich from the global catalog when a provider-qualified match exists;
+3. label every limit/capability as provider, reference, or unknown;
+4. keep pinned/default visibility in the AI plugin's `config_json`;
+5. never write discovered ids into the global catalog.
+
+## Dogfooding matrix
+
+| Runtime point | Hook event | Current owner |
+|---|---|---|
+| interactive shell open/close | `session_start`, `session_end` | CLI shell |
+| submitted/transformed input | `user_prompt_submitted`, `user_prompt_transformed` | provider-neutral runner |
+| paid inference boundaries | `pre_model_use`, `post_model_use` | provider adapter |
+| capability side effects | `pre_tool_use`, `post_tool_use`, `post_tool_use_failure` | capability adapter |
+| provider/tool failures | `error_occurred` | provider/capability adapters |
+| autonomous continuation | `agent_stop` | runner with bounded continuation count |
+| delegated work | `subagent_start`, `subagent_stop` | delegated-agent adapter |
+
+The interactive CLI loads code, project config, and active stored hooks into the
+same runtime. `session_start.modified_config` may override the session's model,
+reasoning, service tier, and compaction preference; arbitrary process or path
+configuration is not applied. Session context is injected through normal
+context items. Every invocation uses the same receipt observer and local
+execution table.
+
+`session_end` remains best effort. Handlers must be idempotent, and durable
+cleanup must eventually be backed by an idle-session sweeper rather than an
+assumption that a process always exits normally.
+
+## Delivery sequence
+
+### Phase 1 — portable core (implemented in this change)
+
+- Canonical portable hook tables and schema-pack manifest.
+- Generic injected-SQL hook store for SQLite/D1-shaped adapters.
+- Stored/config/code source merging.
+- CLI `/hooks` discovery and value-free execution history.
+- Actual shell/runner dogfooding, including session and transformed-prompt
+  events.
+- Compact AI plugin model snapshot contract and existing-plugin persistence API with last-good preservation.
+
+### Phase 2 — hosted compatibility migration
+
+1. Inventory every FK/view/query referencing hosted `agentsam_hook` and
+   `agentsam_hook_execution`.
+2. Create `_v2` tables from the portable columns plus host-required indexes.
+3. Map `owner_id` from the hosted account authority; do not infer it from a
+   tenant/workspace label.
+4. Move legacy handler fields into `handler_config_json` and legacy correlation
+   fields into `correlation_json`.
+5. Validate row counts, active definitions, orphan references, JSON validity,
+   and sampled execution history.
+6. Swap in one transaction where supported; retain a rollback table until
+   production verification completes.
+7. Add the dashboard API only after ownership checks are enforced by the host.
+
+### Phase 3 — shared dashboard projection
+
+- Expose merged definitions and receipts through an injected HookRegistry API.
+- Add source badges, event filters, dry-run input, and last-failure state.
+- Add stored-hook create/edit with handler-specific forms.
+- Add explicit code-hook overrides without copying handler definitions.
+- Reuse the protocol conformance fixtures in UI/API integration tests.
+
+### Phase 4 — model snapshot persistence
+
+- Apply `createAiPluginProbePatch` in the hosted provider probe transaction.
+- Compare `models_hash`; avoid writes when the snapshot is unchanged.
+- Refresh stale snapshots in the background and through `agentsam models
+  --refresh` without blocking startup.
+- Keep last good ids on auth/network failures and expose health separately.
+- Add retention only to probe history, not the last good plugin snapshot.
+
+### Phase 5 — lifecycle reliability
+
+- Add stale-session sweep and idempotent cleanup jobs.
+- Add execution retention/compaction policy.
+- Add local↔remote receipt sync by immutable execution id where explicitly
+  enabled; never sync secrets or full prompt/tool values.
+- Run JSON conformance fixtures in JavaScript, Python, Go, and Rust CI.
+
+## Acceptance checks
+
+- Fresh SQLite and D1-shaped installs produce the same hook tables.
+- No portable hook query requires tenant/workspace/user tables.
+- A prompt value or tool result value cannot be found in a hook receipt row.
+- Config and stored hooks execute in one deterministic priority order.
+- The CLI lists every active source that can affect a turn.
+- A provider probe with 1,000 model ids produces one AI plugin metadata update,
+  not 1,000 catalog rows.
+- Failed model refreshes preserve the last successful model id list.
+- A catalog miss never blocks a provider-verified model solely because the
+  reference package is older.
+- Provider and AgentSam credentials remain separate authorities.

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

@@ -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/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

package/docs/engineering/provider-internal-renames/01a-runtime-environment-contract.md

@@ -0,0 +1,115 @@
+        # Runtime Environment Contract
+
+        Schema: `agentsam.runtime-environment-contract.v1`
+
+        Status: **APPROVED / PROTECTED**
+
+        ## Meaning of "safe"
+
+        These runtime bindings are known-good parts of the existing
+        AgentSam / Local Studio environment contract.
+
+        "Safe" means:
+
+        - preserve the binding name
+        - preserve its existing environment value
+        - preserve Variable vs Secret classification
+        - allow existing Production / Previews / Base wiring to continue
+        - do not reinterpret the name during internal provider refactors
+
+        It does **not** mean secret values are public.
+
+        Secret values must remain encrypted and must never be written into
+        this repository, logs, frontend state, query parameters, generated
+        documentation, test snapshots, or Git diffs.
+
+        ## Approved runtime variables
+
+        - `CLOUDFLARE_ACCOUNT_ID`
+- `GITHUB_APP_ID`
+- `GITHUB_CLIENT_ID`
+- `GOOGLE_CLIENT_ID`
+- `GOOGLE_DESKTOP_CLIENT_ID`
+- `IAM_CLIENT_ID`
+- `IAM_OAUTH_ISSUER`
+
+        ## Approved runtime secrets
+
+        - `AGENTSAM_API_KEY`
+- `AGENTSAM_BRIDGE_KEY`
+- `CLOUDFLARE_API_TOKEN`
+- `CLOUDFLARE_BREAK_GLASS_ADMIN_TOKEN`
+- `CLOUDFLARE_OAUTH_CLIENT_ID`
+- `CURSOR_API_KEY`
+- `GEMINI_API_KEY`
+- `GITHUB_APP_PRIVATE_KEY`
+- `GITHUB_CLIENT_SECRET`
+- `GITHUB_WEBHOOK_SECRET`
+- `GOOGLE_CLIENT_SECRET`
+- `GOOGLE_DESKTOP_CLIENT_SECRET`
+- `IAM_CLIENT_SECRET`
+- `OPENAI_API_KEY`
+- `VAULT_MASTER_KEY`
+
+        ## Refactor protection
+
+        Internal provider abbreviations are implementation-path vocabulary:
+
+        - `cfoa`
+        - `gclioa`
+        - `goaude`
+        - `gdrv`
+
+        They MUST NOT cause environment variables such as:
+
+        - `CLOUDFLARE_ACCOUNT_ID`
+        - `CLOUDFLARE_API_TOKEN`
+        - `CLOUDFLARE_OAUTH_CLIENT_ID`
+        - `GOOGLE_CLIENT_ID`
+        - `GOOGLE_CLIENT_SECRET`
+        - `GOOGLE_DESKTOP_CLIENT_ID`
+        - `GOOGLE_DESKTOP_CLIENT_SECRET`
+
+        to be renamed.
+
+        Environment-variable names are runtime contracts, not implementation
+        filenames.
+
+        ## Existing `.env` / deployment behavior
+
+        Preserve the working runtime environment pattern.
+
+        This lane does not require moving, deleting, rotating, renaming, or
+        changing the values of these bindings.
+
+        Environment-specific values remain managed by their existing runtime
+        environment / secret-management authority.
+
+        ## OAuth boundary
+
+        Provider implementation-file cleanup does not redesign authentication.
+
+        Existing Google, Google Desktop, Cloudflare, IAM, GitHub, AgentSam,
+        bridge, Vault, and model-provider credentials retain their current
+        runtime authority.
+
+        Portable UI packages must consume server/native capability adapters.
+        They must not ingest these secrets directly.
+
+        ## Environments
+
+        Approved contract scopes:
+
+        - Production
+        - Previews
+        - Base
+
+        A later deployment hardening pass may intentionally vary whether a
+        particular credential is populated in each environment, but that is
+        separate from this mechanical rename lane.
+
+        ## Values
+
+        Actual runtime values are intentionally omitted from this document.
+
+        The repository records the contract, not the credentials.

package/docs/engineering/provider-internal-renames/02-cfoa.md

@@ -0,0 +1,57 @@
+        # Stage 02 — Cloudflare OAuth Internal Directory
+
+        ## Change
+
+        Renamed:
+
+        `packages/connectors/cloudflare/`
+        → `packages/connectors/cfoa/`
+
+        `cfoa` means **Cloudflare OAuth**.
+
+        ## Scope
+
+        This stage changes implementation filesystem naming only.
+
+        It does **not** rename:
+
+        - runtime provider ID `cloudflare`
+        - Cloudflare OAuth routes
+        - Cloudflare API URLs
+        - environment variables
+        - D1/R2 scope strings
+        - D1/R2 provider IDs
+        - persisted connection/provider values
+        - public package names
+
+        ## Rewritten tracked references
+
+        - `apps/agentsamd/agentsam.package.json`
+- `apps/local-studio/backend/worker/cloudflare-code-mode.js`
+- `apps/local-studio/backend/worker/connections-registry.js`
+- `apps/local-studio/backend/worker/database-service.js`
+- `apps/local-studio/backend/worker/index.js`
+- `apps/local-studio/backend/worker/plugin-registry.js`
+- `apps/local-studio/package-lock.json`
+- `docs/SOURCE_ARCHITECTURE.md`
+- `docs/engineering/provider-internal-renames/README.md`
+- `package-lock.json`
+- `package.json`
+- `packages/agentsam-knowledge/src/backends/index.js`
+- `packages/connectors/cfoa/package.json`
+- `packages/identity/src/oauth/credentials.js`
+- `scripts/verify-package.mjs`
+- `src/commands/cloudflare-login.js`
+- `src/commands/cloudflare.js`
+- `src/commands/connections.js`
+- `src/lib/deploy/local-studio.js`
+- `src/lib/whoami-capabilities.js`
+- `src/mcp/cloudflare-bundles.js`
+- `test/cloudflare-connector.test.mjs`
+- `test/local-studio-deploy.test.mjs`
+
+        ## Architecture
+
+        Cloudflare authentication remains a host/provider authority.
+        Portable Work/content UI packages consume capability-bearing
+        adapters and must not own OAuth tokens themselves.

package/docs/engineering/provider-internal-renames/03-gclioa.md

@@ -0,0 +1,32 @@
+        # Stage 03 — Google CLI OAuth Internal Filename
+
+        ## Change
+
+        Renamed:
+
+        `apps/local-studio/backend/worker/google-cli-cloud.js`
+        → `apps/local-studio/backend/worker/gclioa.js`
+
+        `gclioa` means **Google CLI OAuth**.
+
+        ## Important boundary
+
+        This stage intentionally does not globally replace the string
+        `google-cli-cloud`.
+
+        Any external OAuth route, callback identifier, protocol value,
+        persisted value, or API contract retains its existing name.
+
+        Only the implementation filename and module references were
+        mechanically revised.
+
+        ## Tracked files rewritten
+
+        - `apps/local-studio/backend/worker/index.js`
+- `docs/engineering/provider-internal-renames/README.md`
+
+        ## Auth authority
+
+        This remains the existing Google CLI/cloud OAuth lane. No new
+        credential store, identity system, or frontend token transport
+        is introduced.

package/docs/engineering/provider-internal-renames/04-goaude.md

@@ -0,0 +1,50 @@
+        # Stage 04 — Google Desktop OAuth Exchange Internals
+
+        ## Change
+
+        Renamed the two implementation files representing the desktop
+        Google OAuth/native handoff lane:
+
+        `apps/local-studio/backend/worker/google-desktop-exchange.js`
+        → `apps/local-studio/backend/worker/goaude.js`
+
+        `packages/identity/src/oauth/google-desktop-exchange.js`
+        → `packages/identity/src/oauth/goaude.js`
+
+        `goaude` is the compact internal name for the Google OAuth
+        desktop/dashboard exchange implementation.
+
+        ## Preserved behavior
+
+        The existing desktop PKCE/native OAuth architecture remains
+        unchanged.
+
+        This stage does not rename or redesign:
+
+        - OAuth callback URLs
+        - native deep-link protocols
+        - PKCE semantics
+        - native handoff records
+        - IAM session semantics
+        - Google provider identity
+        - browser-to-native exchange behavior
+
+        ## Tracked references revised
+
+        - `apps/local-studio/backend/worker/goaude.js`
+- `apps/local-studio/backend/worker/index.js`
+- `apps/local-studio/scripts/google-desktop-exchange.test.mjs`
+- `apps/local-studio/scripts/smoke-desktop-auth.mjs`
+- `docs/engineering/provider-internal-renames/README.md`
+- `package.json`
+- `packages/identity/src/index.js`
+- `packages/identity/src/oauth/README.md`
+- `packages/identity/src/server/worker-router.js`
+- `packages/identity/tests/google-desktop-identity-login.test.mjs`
+- `packages/identity/tests/oauth-presets-accounts-ssot.test.mjs`
+
+        ## SDK law
+
+        Installed Local Studio remains independently usable. Desktop
+        Google OAuth must continue through its existing native/PKCE
+        authority rather than depending on a hosted-only Work UI flow.