@ductape/mcp 0.1.49 → 0.1.51

package/src/index.ts

@@ -943,7 +943,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     "storage.create", "storage.update"
 
   When to use this tool:
-  - Before calling ductape_execute to create or update any asset — use this to discover required fields
+  - Before constructing an administrative asset file for ductape_cli or Workbench — use this to discover required fields
   - To enumerate valid enum values (e.g. which DatabaseTypes or AuthTypes are accepted)
   - To understand nested object shapes without reading SDK docs
 `;
@@ -998,6 +998,11 @@ const payloadGenerateInputSchema = z.object({
     'Include a session placeholder inside the generated input object. ' +
     'The placeholder is named "<session_tag_token>" to indicate it expects the runtime JWT, not the tag name.'
   ),
+  execution_context: z.enum(['user', 'delegated', 'system']).optional().default('user').describe(
+    'Actor intent for this runtime operation. "user" means an active request initiated by the authenticated user; ' +
+    '"delegated" means work acting on behalf of a user with a short-lived delegated identity or application-owned ' +
+    'immutable actor context; "system" means intentionally unattributed background work. This drives session warnings.'
+  ),
   include_cache: z.boolean().optional().default(true).describe(
     'Include the cache tag inside the generated input object so the caller knows which cache to reference for this query.'
   ),
@@ -1091,6 +1096,53 @@ function buildSdkInvocationArgs(payload: Record<string, unknown>): Record<string
   };
 }
 
+function operationAcceptsSession(operationFamily: string, method: string): boolean {
+  const family = operationFamily.toLowerCase();
+  const sessionFamilies = new Set([
+    'action', 'features', 'feature', 'database', 'graph', 'vector', 'storage',
+    'notification', 'messaging', 'broker', 'events', 'event', 'quota', 'fallback',
+  ]);
+  if (!sessionFamilies.has(family)) return false;
+  return !['consume', 'status', 'check', 'fetch', 'list'].includes(method.toLowerCase());
+}
+
+function addSessionAwarenessMetadata(
+  generated: any,
+  args: z.infer<typeof payloadGenerateInputSchema>,
+): any {
+  const acceptsSession = operationAcceptsSession(args.operation_family, args.method);
+  const executionContext = args.execution_context ?? 'user';
+  const payloadHasSession = Boolean(generated?.payload?.session || generated?.payload?.input?.session);
+  const sessionRequested = args.include_session !== false;
+  const warnings: string[] = [];
+
+  if (acceptsSession && executionContext !== 'system' && (!sessionRequested || !payloadHasSession)) {
+    warnings.push(
+      `Session attribution is missing for a ${executionContext}-context operation. ` +
+      'Pass the original full session token for immediate user work, or an approved delegated identity/immutable actor context for delayed work.',
+    );
+  }
+  if (executionContext === 'system' && payloadHasSession) {
+    warnings.push(
+      'This operation is marked system-context but contains a session placeholder. Remove it unless the work is actually user/delegated.',
+    );
+  }
+
+  generated.meta = {
+    ...(generated?.meta ?? {}),
+    session_awareness: {
+      accepts_session: acceptsSession,
+      execution_context: executionContext,
+      appears_user_context: executionContext === 'user',
+      session_requested: sessionRequested,
+      session_present_in_payload: payloadHasSession,
+      intentionally_system_context: executionContext === 'system',
+      warnings,
+    },
+  };
+  return generated;
+}
+
 function buildTypeScriptSnippet(
   payload: Record<string, unknown>,
   operationFamily: string,
@@ -1242,7 +1294,7 @@ const docsInputSchema = z.object({
     'Feature topic to look up. Supported: ' +
     'transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
     'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-    'notifications, resilience, features, events, logs, frontend, client, react, vue',
+    'notifications, resilience, features, events, logs, frontend, frontend-analytics, client, react, vue',
   ),
 });
 
@@ -1280,6 +1332,11 @@ SHARED APPLICATION LIFECYCLE
      connectionState to render disconnected/reconnecting UI; do not create duplicate subscriptions.
   7. Disconnect resource sessions and the root client when the owning application scope is torn down.
 
+PRODUCT ANALYTICS
+  Frontend product analytics complements backend session propagation; neither replaces the other.
+  Continue with ductape_docs({ topic: "frontend-analytics" }) for identity lifecycle, pageviews,
+  custom events, privacy masking, hidden-state safety, trace correlation, and package-version checks.
+
 AUTHENTICATION AND SECURITY
   - Use publishableKey in browser applications. Never ship workspace private keys or privileged
     access keys in frontend bundles.
@@ -1457,33 +1514,9 @@ DUCTAPE DATABASE MIGRATIONS
 
 Migrations are versioned SQL/NoSQL schema change scripts managed per database component.
 
-Create a migration:
-  ductape_execute("databases.migration.create", [{
-    product: "my-product",
-    database: "core-db",
-    data: {
-      name: "add users table",
-      tag: "001-add-users",
-      value: {
-        up:   ["CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT NOT NULL UNIQUE)"],
-        down: ["DROP TABLE users"],
-      },
-    },
-  }])
-
-Run migrations (applies all pending):
-  ductape_execute("databases.migration.run", [migrations, { env: "prd" }])
-
-Rollback:
-  ductape_execute("databases.migration.rollback", [migrations, 1])  // roll back 1
+Create migrations through the project migration files and ductape_cli, never ductape_execute.
 
-Check status:
-  ductape_execute("databases.migration.status", [migrations])
-
-History:
-  ductape_execute("databases.migration.history", [])
-
-Via CLI:
+Use the access-key administrative CLI for running, rolling back, and inspecting migrations:
   ductape_cli("db migrate")              // run pending
   ductape_cli("db migrate rollback")     // roll back last
   ductape_cli("db migrate rollback -n 3")
@@ -1494,25 +1527,13 @@ MongoDB: migrations run as raw Mongo shell commands in the up/down arrays.
   indexes: `
 DUCTAPE DATABASE INDEXES
 
-Create an index:
-  ductape_execute("databases.schema.createIndex", [
-    "collection_name",
-    ["field1", "field2"],           // simple array of field names
-    { unique: true, name: "idx_email_unique" }   // options (optional)
-  ])
-
-  // Ordered index:
-  ductape_execute("databases.schema.createIndex", [
-    "orders",
-    [{ field: "createdAt", order: "DESC" }, { field: "userId", order: "ASC" }],
-    { name: "idx_orders_date_user" }
-  ])
-
-Drop an index:
-  ductape_execute("databases.schema.dropIndex", ["collection_name", "index_name"])
+Create or update indexes through migration files and ductape_cli("db migrate"), not the
+publishable-key runtime proxy. Example definitions may use ["field1", "field2"] with
+{ unique: true, name: "idx_email_unique" }, or ordered fields such as
+[{ field: "createdAt", order: "DESC" }, { field: "userId", order: "ASC" }].
 
-List indexes on a collection:
-  ductape_execute("databases.schema.indexes", ["collection_name"])
+Drop and inspect indexes through migration/CLI tooling or the database administration surface,
+not ductape_execute.
 
 Performance guidance:
   - Index fields used in WHERE clauses, JOIN conditions, and ORDER BY.
@@ -1558,18 +1579,7 @@ DUCTAPE DATABASE ACTIONS
 A database action is a saved query or mutation (SQL string or NoSQL command) stored
 on the Ductape product and executed by tag at runtime.
 
-Create an action (admin):
-  ductape_execute("databases.action.create", [{
-    product: "my-product",
-    database: "core-db",
-    data: {
-      tag: "get-active-users",
-      name: "Get active users",
-      description: "Returns all users with status=active",
-      type: "sql",                    // "sql" or "nosql"
-      query: "SELECT * FROM users WHERE status = :status",
-    },
-  }])
+Create/update actions in Workbench (administrative access), never through ductape_execute.
 
 Dispatch an action at runtime:
   → CALL ductape_generate_payload FIRST to get the canonical input shape.
@@ -1584,10 +1594,9 @@ Dispatch an action at runtime:
 List actions for a database:
   ductape_execute("databases.action.list", ["database_tag"])
 
-Fetch / update / delete:
+Fetch:
   ductape_execute("databases.action.fetch",  ["action_tag"])
-  ductape_execute("databases.action.update", ["my-product", "action_tag", { query: "..." }])
-  ductape_execute("databases.action.delete", ["action_tag"])
+Update/delete are administrative and must be performed in Workbench.
 
 Actions are the preferred way to encapsulate complex or reused queries — they can be
 scheduled, dispatched with retries, and audited via logs.
@@ -1851,16 +1860,8 @@ DUCTAPE SECRETS
 Secrets are workspace-level encrypted key-value pairs. They are referenced in resource configs,
 connection URLs, and any string field using the $Secret{KEY_NAME} syntax.
 
-Create (admin — ductape_cli or ductape_execute):
-  ductape_execute("secrets.create", [{
-    key: "STRIPE_API_KEY",
-    value: "sk_live_...",          // plaintext — encrypted AES-256-GCM client-side before send
-    description: "Stripe live key",
-    token_type: "api",             // "api" | "password" | "certificate"
-    scope: ["my-product"],         // which products can read this secret
-    envs: ["prd"],                 // which env slugs can read this secret
-    expires_at: 1800000000,        // optional epoch ms
-  }])
+Create/update secrets with ductape_cli or Workbench (administrative access), never ductape_execute.
+Definition fields include key, value, description, token_type, scope, envs, and expires_at.
   The server never receives the plaintext value. Encryption uses the workspace private key.
 
 Fetch / resolve:
@@ -1875,10 +1876,7 @@ $Secret{} reference syntax:
   - The in-memory cache stores the encrypted form only; decryption happens on each cache hit.
   - Cache TTL: 5 minutes. Clear with: secrets.clearCache()
 
-Lifecycle:
-  ductape_execute("secrets.revoke", ["KEY"])   → disables without deleting (recoverable)
-  ductape_execute("secrets.delete", ["KEY"])   → permanent deletion (irreversible)
-  ductape_execute("secrets.update", ["KEY", { value: "new_value", expires_at: ... }])
+Lifecycle mutations (revoke/delete/update) are administrative: use ductape_cli or Workbench.
 
 List all secrets (keys only — values are not returned in list):
   ductape_execute("secrets.list", [])
@@ -1929,9 +1927,7 @@ Import from a file:
   ductape_cli("apps import <file.json> -t postman|openapi")
   Supports Postman v2.1 collection and OpenAPI 3.0 spec.
 
-Manage environments (base URLs per stage):
-  ductape_execute("app.environments.create", [app_tag, { slug, env_name, base_url }])
-  ductape_execute("app.environments.list",   [app_tag])
+Manage environments (base URLs per stage) in Workbench; this currently has no CLI command.
 
 Discover apps in a product and their actions (ALWAYS do this before writing any ctx.api.run call):
   Step 1 — list apps connected to the product:
@@ -1948,16 +1944,8 @@ Discover apps in a product and their actions (ALWAYS do this before writing any
            app resources (not for runtime input — use actions.fetch or ductape_generate_payload for that)
   NEVER assume action input field names. Always fetch the action definition first.
 
-Manage actions (individual API endpoints):
-  ductape_execute("actions.create", [app_tag, {
-    tag, name, resource: "/users/{id}", method: "GET"|"POST"|"PUT"|"PATCH"|"DELETE",
-    body?: { fieldName: { type, required? } },
-    params?: { id: { type: "string" } },
-    query?: { filter: { type: "string" } },
-    headers?: { Authorization: { type: "string" } },
-    response?: { status_code: 200, success: true, body: { ... }, response_format: "json" },
-  }])
-  ductape_execute("actions.update", [app_tag, action_tag, data])
+Manage actions (individual API endpoints) in Workbench or import an OpenAPI/Postman file.
+Creation/update are administrative and must never use ductape_execute.
   ductape_execute("actions.list",   [app_tag])
   ductape_execute("actions.fetch",  [app_tag, action_tag])
 
@@ -1978,16 +1966,14 @@ Run an action at runtime:
 
 Auth schemes (how the app authenticates outbound requests):
   Setup types: header | bearer | basic | oauth2 | apikey
-  ductape_execute("auths.create", [app_tag, { tag, name, setup_type, expiry, period, action_tag? }])
+  Configure auth in Workbench (administrative).
   ductape_execute("auths.list",   [app_tag])
 
 Webhooks (inbound events from the external service):
-  ductape_execute("webhooks.create", [app_tag, { tag, name, description, envs: [{ slug, registration_url?, method? }] }])
-  ductape_execute("webhooks.events.create", [app_tag, { tag, name, selector, description, sample }])
+  Configure webhooks and webhook events in Workbench (administrative).
 
 Variables (per-env mutable values) and Constants (fixed values):
-  ductape_execute("app.variables.create", [app_tag, { key, value, env_slug }])
-  ductape_execute("app.constants.create", [app_tag, { key, value }])
+  Configure variables and constants in Workbench (administrative).
 
 Connecting an app to a product (after creation):
   NOTE: All product.* module methods require the access key and CANNOT use ductape_execute.
@@ -1995,14 +1981,13 @@ Connecting an app to a product (after creation):
 
   FULL FLOW to make an app callable from a product:
   1. Create the app:     ductape_cli("apps create --name \\"Service Name\\" --description \\"...\\"")
-  2. Add environments:   ductape_execute("app.environments.create", [app_tag, { slug: "prd", env_name: "Production", base_url: "https://api.example.com" }])
-  3. Configure auth:     ductape_execute("auths.create", [app_tag, { tag, name, setup_type: "apikey"|"bearer"|"basic"|"oauth2", expiry, period }])
-  4. Define actions:     ductape_execute("actions.create", [app_tag, { tag, name, resource, method, body?, params?, query?, headers?, response? }])
+  2. Add environments:   Workbench
+  3. Configure auth:     Workbench
+  4. Define actions:     Workbench
                          OR import: ductape_cli("apps import <file.json> -t postman|openapi")
   5. Connect to product: Requires the product_id (from ductape_cli("products get --tag <tag> --json")).
                          There is no CLI command for this step — the SDK product.apps.add method requires
-                         an access key which only the backend can provide. Use ductape_execute via an
-                         admin-authenticated context, or connect via the Workbench UI.
+                         an access key which only the backend can provide. Connect via Workbench.
   6. Verify:             ductape_cli("products get --tag <product_tag> --json") → check apps[] contains the app
                          ductape_execute("actions.list", [app_tag]) → verify actions are registered
 `.trim(),
@@ -2041,6 +2026,7 @@ Resource registration (all via ductape_cli or ductape_execute — see per-topic
   caches    → ductape_docs({ topic: "caches" })
   notifications → ductape_docs({ topic: "notifications" })
   sessions  → ductape_docs({ topic: "sessions" })
+  frontend analytics → ductape_docs({ topic: "frontend-analytics" })
   resilience → ductape_docs({ topic: "resilience" })
   features  → ductape_docs({ topic: "features" })
 
@@ -2078,8 +2064,8 @@ IMPORTANT — selector must be "$Session{fieldName}" format:
   CORRECT:   selector: "$Session{playerId}"
   INCORRECT: selector: "playerId"   ← WILL FAIL with "Selector should be in the format $Session{...}{key}"
 
-Example (game product — player identity in JWT):
-  ductape_execute("sessions.create", [product_tag, {
+Example definition (configure via declarative apply or Workbench, not ductape_execute):
+  {
     tag: "player-session",
     name: "Player Session",
     expiry: 24,
@@ -2091,7 +2077,7 @@ Example (game product — player identity in JWT):
       role:      "player",
       accountId: "acct_xyz",
     },
-  }])
+  }
 
 Runtime — create a session (sign a JWT):
   → CALL ductape_generate_payload FIRST (operation_family="session", method="start", targets={tag})
@@ -2129,6 +2115,39 @@ Analytics:
 
 Token format: "session_tag:jwt_token" — pass this format verbatim wherever session is expected.
 JWT is signed with the product private key (not a symmetric shared secret).
+
+SESSION PROPAGATION
+  Extract the original full "session_tag:jwt" token once at the HTTP/transport boundary and retain
+  it separately from verified/decoded claims. Claims are authorization data; they are not a token.
+  Store a request ActorContext in a NestJS request-scoped provider or AsyncLocalStorage:
+    type ActorContext =
+      | { kind: "user"; session: string; actorId: string }
+      | { kind: "delegated"; delegatedIdentity: string; actorId: string; initiatedAt: string }
+      | { kind: "system"; reason: string };
+  Pass ActorContext explicitly through service boundaries. At each immediate Ductape runtime call,
+  pass actor.kind === "user" ? actor.session : the SDK-approved delegated identity. Put only
+  non-secret actor metadata (actorId, kind, initiatedAt, correlationId) in Event envelopes.
+  Feature execution should receive the same explicit actor classification. Never log, serialize
+  into business payloads, or attach the raw session/refresh token to traces or error messages.
+
+  SECURITY BOUNDARY FOR DURABLE WORK
+  The current SDK accepts a session string on dispatch, but it does not expose an immutable
+  attribution snapshot API, an expired-token attribution contract, or a general delegated-session
+  issuer. Therefore do NOT persist reusable JWTs indefinitely or assume an expired initiating token
+  will remain valid when delayed work executes. Pass the full token only for immediate work within
+  its validity window. For delayed/recurring work, classify execution as system-context, or use an
+  application-owned immutable actor-context envelope plus a short-lived delegated identity issued
+  by an explicitly approved auth design. Until the SDK provides that design, actor metadata is for
+  audit/correlation and must not be treated as authorization.
+
+  Distinguish contexts deliberately:
+    user      — active request; original valid full token is required when the operation accepts it
+    delegated — delayed/on-behalf-of work; approved short-lived credential + immutable actor metadata
+    system    — scheduler/maintenance with no user authority; omit session and record a reason
+
+  Backend propagation attributes component activity to an actor, but it does not record frontend
+  pageviews, navigation, UI intent, funnels, or client failures. Continue immediately with
+  ductape_docs({ topic: "frontend-analytics" }); both layers are required for a complete picture.
 `.trim(),
 
   caches: `
@@ -2136,14 +2155,12 @@ DUCTAPE CACHES
 
 Caches are product-level Redis (or in-memory) stores for temporary key-value data with optional TTL.
 
-Registration (admin — ductape_cli or SDK):
+Registration (admin — ductape_cli):
   ductape_cli("resources caches create -f cache.json")
   File: { name, tag, description?, expiry: <milliseconds> }
   No type or envs — Ductape manages the store infrastructure.
   expiry is in MILLISECONDS: 3600000 = 1 hour, 86400000 = 1 day, 604800000 = 1 week.
 
-  SDK: ductape_execute("caches.create", [product_tag, { name, tag, description?, expiry: 3600000 }])
-
 Operations:
   caches.set   [{ product, cache, key, value: string, expiry?: string (ISO 8601), env }]
     expiry is an ABSOLUTE TIMESTAMP (not a duration).
@@ -2192,20 +2209,20 @@ DUCTAPE NOTIFICATIONS
 
 Notifications send messages across multiple channels: email, SMS, push, or HTTP callback.
 
-Create a notification (admin — ductape_execute):
-  ductape_execute("notifications.create", [product_tag, {
+Create a notification through declarative apply or Workbench (administrative), using:
+  {
     tag: "welcome-email",
     name: "Welcome Email",
     type: "email",   // optional hint; actual channels configured per env
-  }])
+  }
 
-Create a message template:
-  ductape_execute("notifications.messages.create", [product_tag, {
+Create a message template through declarative apply or Workbench:
+  {
     tag: "welcome-email:default",       // format: "notification_tag:message_tag"
     notification: "welcome-email",
     subject: { template: "Welcome, {{name}}!", data: { name: "" } },
     body:    { template: "Hi {{name}}, thanks for signing up.", data: { name: "" } },
-  }])
+  }
 
 Send at runtime (one channel at a time):
   → CALL ductape_generate_payload FIRST (operation_family="notification", method="email.send")
@@ -2244,8 +2261,15 @@ DUCTAPE RESILIENCE
 Resilience covers three mechanisms: quotas (rate-limited provider pools), fallbacks (automatic
 provider switching), and healthchecks (continuous probe monitoring with failure actions).
 
+CONFIGURATION BOUNDARY
+  Quotas, fallbacks, and health checks are administrative product configuration. Configure them in
+  Workbench (or a future access-key administrative tool explicitly documented for the asset).
+  Never route administrative create/update methods through ductape_execute: its publishable-key
+  runtime proxy will fail.
+
 QUOTAS — rate-limited multi-provider pools:
-  ductape_execute("quotas.create", [product_tag, {
+  Workbench definition shape:
+  {
     tag: "sms-quota",
     name: "SMS Provider Pool",
     input: { to: { type: "string", required: true }, message: { type: "string" } },
@@ -2259,7 +2283,7 @@ QUOTAS — rate-limited multi-provider pools:
         input: { "body:to": "$Input{to}", "body:body": "$Input{message}" },
         output: {} },
     ],
-  }])
+  }
   Providers are tried in order until quota is not exhausted.
   quotas.run      [{ product, env, tag, input }]  ← CALL ductape_generate_payload FIRST
   quotas.dispatch [{ product, env, tag, input, schedule? }]
@@ -2267,12 +2291,13 @@ QUOTAS — rate-limited multi-provider pools:
 FALLBACKS — automatic provider switching on failure:
   Same schema as quotas but options are ordered: primary first, then fallback(s).
   Primary is used first; on failure, the next provider is tried automatically.
-  ductape_execute("fallback.create", [product_tag, { tag, name, input: { ... }, options: [...] }])
+  Configure in Workbench: { tag, name, input: { ... }, options: [...] }
   fallback.run      [{ product, env, tag, input }]  ← CALL ductape_generate_payload FIRST
   fallback.dispatch [{ product, env, tag, input, schedule? }]
 
 HEALTHCHECKS — continuous probe with failure notifications:
-  ductape_execute("health.create", [product_tag, {
+  Workbench definition shape:
+  {
     tag: "payment-health",
     name: "Payment Service Health",
     probe: { type: "app", app: "stripe-app", event: "ping" },
@@ -2284,7 +2309,7 @@ HEALTHCHECKS — continuous probe with failure notifications:
         channels: { email: { recipients: ["ops@example.com"] } } }],
       webhooks: [{ url: "https://hooks.example.com/alert", method: "POST" }],
     },
-  }])
+  }
   health.run    [{ product, env, tag }]   → triggers an immediate probe
   health.check  [{ product, env, tag }]   → same as run
   health.status [{ product, env, tag }]   → current health status
@@ -2294,6 +2319,240 @@ Failure actions: notification channels, HTTP webhooks, and/or message broker emi
   be configured simultaneously on the same healthcheck.
 Input template references: $Input{field} → maps declared input to the probe's action input.
 Provider status: available | unavailable
+
+DECISION MATRIX
+  Rate/capacity allocation across providers       → quota
+  Equivalent provider after operational failure   → fallback
+  Detect failure before routing provider traffic  → health check
+  Transient failure of one operation              → bounded retry + idempotency policy
+  Multi-step business recovery/compensation       → Feature
+  Database atomicity                              → database transaction, not Feature rollback
+  Scheduled single operation                      → that component's dispatch
+  Scheduled multi-step process                    → Feature dispatch
+
+COMBINING MECHANISMS
+  A health check may keep an unhealthy provider out of a fallback/quota pool; the pool controls
+  provider selection; each operation may use bounded retries and an idempotency key; a Feature
+  coordinates business steps and compensation around those resilient operations. Do not stack them
+  reflexively: each layer needs a distinct failure it owns, bounded retry budgets, and observable
+  terminal behavior. Database transactions remain the atomicity boundary for related DB writes.
+`.trim(),
+
+  'frontend-analytics': `
+DUCTAPE FRONTEND PRODUCT ANALYTICS AND SESSION ACTIVITY
+
+Frontend analytics and backend session attribution are complementary; neither replaces the other.
+
+BACKEND OPERATION ATTRIBUTION
+  Pass the original full Ductape session token to every user-initiated database, Event, Feature,
+  notification, storage, graph, vector, action, and other runtime operation that accepts session.
+  This attributes server work to the authenticated actor. Durable work should retain the initiating
+  session; intentional system/background work should remain sessionless.
+
+FRONTEND PRODUCT ANALYTICS
+  Use the browser Analytics service for anonymous visits, authenticated page views, navigation,
+  UI interactions, funnels, client errors, realtime state, and product-surface engagement.
+
+  IMPORTANT:
+  Passing session to backend component calls does not replace frontend analytics.
+  Calling analytics.identify(sessionToken) and tracking frontend events does not replace backend
+  session propagation. A complete activity picture requires both.
+
+VERSION AND DOCUMENTATION PRECEDENCE
+  1. Installed package types and exports determine what can be called now.
+  2. Version-matched package documentation explains intended usage.
+  3. Current docs/docs/Frontend describes the latest supported design.
+  4. If they disagree, report the mismatch; never fabricate compatibility.
+
+  Inspect package.json plus package exports/type declarations before recommending framework hooks.
+  The current repository exports useAnalytics from @ductape/react and @ductape/vue. Their installed
+  hook/composable exposes track, pageview, identify, visitorId, enableAutoCapture, and flush.
+  clearSession and disableAutoCapture are available on client.analytics but are not currently
+  returned by those framework wrappers. Use useDuctape().client.analytics for those calls, or
+  recommend a package version that exports them; do not generate a hook method that does not exist.
+
+CLIENT API — IDENTIFY AFTER AUTHENTICATION
+  ductape.analytics.identify(sessionToken);
+
+  sessionToken is the complete value returned by Ductape, in "player-session:jwt" format.
+  It is NOT a player ID, session tag, session ID, decoded claims, or refresh token.
+  identify links subsequent frontend analytics to the authenticated Ductape session and lets
+  supported analytics correlate anonymous pre-login activity with authenticated activity.
+
+LOGOUT / ACCOUNT SWITCHING
+  await ductape.analytics.flush();
+  ductape.analytics.clearSession();
+
+  Clear analytics identity when logout or revocation succeeds, refresh fails irrecoverably, local
+  authentication is removed, or a different user is about to authenticate in the same browser.
+  Removing only the application token can leave later anonymous/next-user events associated with
+  the previous analytics identity. Flush is best-effort; browser shutdown does not guarantee it.
+
+CUSTOM EVENTS
+  await ductape.analytics.track({
+    event: 'order_submitted',
+    traceId,
+    properties: { matchId, orderType },
+  });
+
+  IAnalyticsTrackOptions:
+    event: string
+    properties?: Record<string, unknown>
+    session?: string
+    product?: string
+    env?: string
+    traceId?: string
+    context?: { url?, path?, referrer?, locale?, screen?: { width, height } }
+
+  identify establishes the default analytics session. An individual event may explicitly provide
+  session. Normally use product/env from client configuration. traceId correlates frontend intent
+  with backend logs, Events, Features, and order processing.
+
+PAGE VIEWS
+  await ductape.analytics.pageview({
+    path: location.pathname,
+    title: document.title,
+    properties: { matchId, screen: 'governance' },
+  });
+
+  IAnalyticsPageviewOptions:
+    path?: string
+    title?: string
+    session?: string
+    product?: string
+    env?: string
+    properties?: Record<string, unknown>
+
+AUTO-CAPTURE — OPT IN ONLY AFTER A PRIVACY AUDIT
+  const stopAutoCapture = ductape.analytics.enableAutoCapture({
+    session: () => authSession?.token,
+    clicks: false,
+    pageviews: true,
+    maskTextSelectors: [
+      '[data-private]',
+      '[data-secret]',
+      '[data-player-message]',
+      '[data-intelligence-report]',
+    ],
+  });
+  stopAutoCapture(); // or ductape.analytics.disableAutoCapture()
+
+  Mark sensitive UI with data-private/data-secret attributes. Text masking may not mask attributes,
+  IDs, URLs, element names, custom properties, console errors, or network errors. Inspect actual
+  payloads before production. For hidden-information products, begin with reviewed automatic
+  pageviews, clicks disabled, and preferred custom named events.
+
+VISITOR ID
+  const visitorId = ductape.analytics.getVisitorId();
+  A visitor ID is anonymous analytics identity, not authentication or authorization.
+
+FRONTEND SESSION LIFECYCLE
+  Before login:
+    - Track anonymous pageviews/onboarding; do not invent a session.
+  After login/registration:
+    - Store the session securely, identify(fullSessionToken), track success, start authenticated
+      pageviews, and pass the same token to user-context realtime/component operations.
+  After refresh:
+    - Replace the old token, identify(newSessionToken), update realtime connections/subscriptions,
+      and use the refreshed token for future backend operations.
+  Logout:
+    - Optionally track logout_initiated, flush, revoke, disconnect realtime, clearSession, then
+      remove local authentication.
+  Refresh failure/revocation:
+    - Disconnect user-context clients, clearSession, clear local auth, navigate to authentication,
+      and track only anonymous events afterward.
+
+REACT ROUTE TRACKING (verify installed exports first)
+  import { useAnalytics, useDuctape } from '@ductape/react';
+  import { useEffect } from 'react';
+  import { useLocation } from 'react-router-dom';
+
+  function ProductAnalytics({ sessionToken }: { sessionToken?: string }) {
+    const analytics = useAnalytics();
+    const { client } = useDuctape();
+    const location = useLocation();
+    useEffect(() => {
+      if (sessionToken) analytics.identify(sessionToken);
+      else client.analytics.clearSession();
+    }, [analytics, client, sessionToken]);
+    useEffect(() => {
+      void analytics.pageview({ path: location.pathname, title: document.title });
+    }, [analytics, location.pathname]);
+    return null;
+  }
+
+SAFE EVENT TAXONOMY
+  Define stable names centrally; do not invent variants throughout components.
+  Authentication:
+    registration_started, registration_completed, registration_failed,
+    login_started, login_completed, login_failed, session_refreshed,
+    session_refresh_failed, logout_completed
+  Match:
+    match_list_viewed, match_creation_started, match_created, match_joined, lobby_viewed,
+    player_marked_ready, match_preparation_started, world_loaded, match_reconnected,
+    match_completed, endgame_viewed
+  Orders:
+    order_form_opened, order_previewed, order_submission_started, order_submitted,
+    order_submission_failed, order_cancelled, boundary_result_viewed
+  Realtime:
+    realtime_connect_started, realtime_connected, realtime_disconnected,
+    realtime_reconnect_attempted, realtime_subscription_failed, projection_refresh_failed,
+    client_error
+  Funnels:
+    tutorial_started, tutorial_step_completed, tutorial_abandoned, first_match_created,
+    first_order_submitted, first_boundary_viewed, first_match_completed
+
+  Safe properties include matchId, orderType, screen, tick, result, and errorCategory.
+
+HIDDEN AND SENSITIVE DATA — NEVER SEND TO ANALYTICS
+  Do not track exact hidden formations, operative/handler identities, secret operation payloads,
+  false-report truth markers, undiscovered evasion details, invisible treaties, canonical hidden
+  map state, private messages, passwords, authorization headers, session/refresh tokens in event
+  properties, or full errors/records that may contain secrets. Analytics must observe usage, not
+  become a hidden-state side channel.
+
+CORRELATION
+  Frontend: create traceId = crypto.randomUUID(), track intent with traceId, and send traceId with
+  the actual request. Backend logs the same traceId and propagates session to Ductape operations.
+  Track completion with the same traceId.
+
+  traceId       = correlation
+  session       = actor attribution
+  idempotencyKey = duplicate prevention
+  matchId/orderId = domain identity
+  These values are not interchangeable.
+
+OWNERSHIP BOUNDARIES
+  Analytics is never an authoritative order, authorization proof, or gameplay source of truth.
+  Analytics failure must not block or alter gameplay. The server verifies sessions independently;
+  authoritative database and Event streams remain the source of truth. Prefer non-blocking
+  analytics except explicit best-effort flushes at safe lifecycle transitions.
+
+FRONTEND PROJECT AUDIT
+  Inspect installed @ductape/client/react/vue versions and actual exports; client/provider setup;
+  identify after login and refresh; clearSession on logout/account switch; SPA pageviews; auto-
+  capture and masking; taxonomy consistency; sensitive custom properties; and shared trace IDs.
+  Report capability as Present/Missing/Partial/Not applicable with concrete findings.
+
+WHEN “SESSION ACTIVITY IS MISSING FROM THE DASHBOARD”
+  Investigate both tracks before blaming the SDK.
+  Backend: start/verify format, correct env, session on database/Event/Feature/notification/etc.,
+  and intentional background sessionlessness.
+  Frontend: identify after login/refresh, clearSession on logout, pageviews/custom events, flush,
+  correct publishable key/product/env, installed API compatibility, browser failures, and privacy
+  controls that may suppress events.
+
+PAYLOAD RECIPES
+  Anonymous:
+    await ductape.analytics.pageview({ path: window.location.pathname, title: document.title });
+  Authenticated:
+    ductape.analytics.identify(playerSessionToken);
+    await ductape.analytics.track({
+      event: 'match_created', session: playerSessionToken, traceId, properties: { matchId },
+    });
+  Logout:
+    await ductape.analytics.flush();
+    ductape.analytics.clearSession();
 `.trim(),
 
   features: `
@@ -2358,9 +2617,11 @@ STEP 4 — PRESENT the plan and get approval BEFORE writing any code or creating
   Wait for confirmation before writing code or calling any create tool.
 
 STEP 5 — CREATE missing components (only with user approval)
-  Use ductape_execute for any missing databases, apps, database actions, notification events, etc.
-  For a missing database action:
-    ductape_execute("databases.action.create", [product_tag, db_tag, { tag, name, type, query }])
+  Administrative assets must never be created through ductape_execute. Use ductape_cli for products,
+  apps, supported resources, broker topics, cloud connections, secrets, and declarative apply flows.
+  App actions, auths, Features, quotas, fallbacks, health checks, and other assets for which the CLI
+  has no command must be configured in Workbench. Do not generate an impossible publishable-key
+  create/update call. For a missing database action, configure it in Workbench, then verify it exists.
   For a missing child feature, recursively apply this same workflow.
   Tell the user what you are about to create before each tool call.
 
@@ -2484,7 +2745,11 @@ When you call features.define({ handler }), the handler runs TWICE:
 
   Invoke internal application business logic (your own NestJS/backend service code):
     → produce a broker event (ctx.messaging.produce or ductape.events.produce)
-    → consume it in your NestJS service with events.consume in onModuleInit
+    → follow ductape_docs({ topic: "events" }) and use the canonical NestJS decorator:
+      @Events.Consumer({ event: "broker-tag:topic-tag" })
+      async handle(message: MessageShape) { /* injected-service business logic; throw to nack */ }
+    → DuctapeModule auto-registers the decorated consumer; no manual onModuleInit is needed
+    → events.consume() remains a supported lower-level alternative for plain TypeScript/Node.js
     → your service method runs with full access to DI, DB transactions, etc.
     Do NOT create an App Action just to call your own service over HTTP.
 
@@ -2983,9 +3248,15 @@ SESSIONS SERVICE
   const { token } = await ductape.sessions.refresh({ refreshToken: '...' });
 
 ANALYTICS SERVICE
-  ductape.analytics.pageview({ page: '/dashboard' });
-  ductape.analytics.track('button_click', { button: 'sign-up' });
-  ductape.analytics.identify({ userId: 'u_123', traits: { plan: 'pro' } });
+  ductape.analytics.identify('player-session:eyJ...'); // full Ductape session token
+  await ductape.analytics.pageview({ path: '/dashboard', title: document.title });
+  await ductape.analytics.track({
+    event: 'button_clicked',
+    properties: { button: 'sign-up' },
+  });
+  await ductape.analytics.flush();
+  ductape.analytics.clearSession(); // logout/account switch
+  See ductape_docs({ topic: "frontend-analytics" }) before enabling auto-capture.
 
 FRAMEWORK-SPECIFIC PACKAGES
   For React and Vue projects, use the dedicated packages instead of managing the client manually:
@@ -3087,13 +3358,15 @@ AGENT HOOKS
   useAgentSignal(hookOptions?)               → { mutate, isLoading, error }
 
 BROKER HOOKS
-  useBroker(broker, options?)
+  useBroker()
     → { isConnected, isConnecting, error, connect, disconnect }
+    connect({ broker, session?, product?, env? }) forwards the complete options object to
+    @ductape/client. Pass session for player-scoped authorization.
   useBrokerPublish(hookOptions?)
     → { mutate({ topic, message, headers?, key? }), isLoading, error, data }
   useBrokerSubscription(subscribeOptions, hookOptions?)
     → { data: BrokerMessage[], isSubscribed, error, unsubscribe, resubscribe }
-    subscribeOptions: { topic, group? }
+    subscribeOptions: { broker?, topic, group?, session?, product?, env? }
 
 GRAPH HOOKS
   useGraph(graphTag)  → { isConnected, isConnecting, error, connect, disconnect }
@@ -3163,7 +3436,10 @@ ACTIONS HOOKS
   useActionRun(hookOptions?) → { mutate, isLoading, error, data }
 
 ANALYTICS HOOK
-  useAnalytics() → { pageview, track, identify }
+  useAnalytics() → { pageview, track, identify, visitorId, enableAutoCapture, flush }
+  The currently installed hook does NOT return clearSession or disableAutoCapture.
+  Use useDuctape().client.analytics.clearSession()/disableAutoCapture(), or verify a newer installed
+  package export before generating those hook calls. See ductape_docs({ topic: "frontend-analytics" }).
 
 hookOptions pattern (applies to all hooks):
   enabled?    boolean — false skips auto-fetch/subscribe
@@ -3333,7 +3609,10 @@ ACTIONS COMPOSABLES
   useActionRun(composableOptions?) → { mutate, isLoading, error, data }
 
 ANALYTICS COMPOSABLE
-  useAnalytics() → { pageview, track, identify }
+  useAnalytics() → { pageview, track, identify, visitorId, enableAutoCapture, flush }
+  The currently installed composable does NOT return clearSession or disableAutoCapture.
+  Use useDuctape().client.analytics.clearSession()/disableAutoCapture(), or verify a newer installed
+  package export before generating those composable calls. See ductape_docs({ topic: "frontend-analytics" }).
 
 composableOptions pattern (applies to all composables):
   enabled?    boolean — false skips auto-fetch/subscribe
@@ -3542,6 +3821,25 @@ async function main() {
 
   const executeHandler = async (args: { publishable_key?: string; module: SDKModule; method: string; params: unknown[] }) => {
     try {
+      const runtimeMutationMethods: Partial<Record<SDKModule, Set<string>>> = {
+        databases: new Set(['insert', 'update', 'delete', 'upsert']),
+        graph: new Set(['insert', 'update', 'delete']),
+        vector: new Set(['insert', 'upsert', 'upsertOne', 'delete']),
+        sessions: new Set(['revoke']),
+      };
+      const isRuntimeDataMutation = runtimeMutationMethods[args.module]?.has(args.method) === true;
+      const isAdministrativeMutation =
+        (/^migration\./.test(args.method) ||
+          /^schema\.(create|drop|add|remove|update)/.test(args.method) ||
+          /(^|\.)(create|update|delete|configure|add|remove|revoke)$/.test(args.method)) &&
+        !isRuntimeDataMutation;
+      if (isAdministrativeMutation) {
+        throw new Error(
+          `Administrative operation "${args.module}.${args.method}" is blocked in ductape_execute. ` +
+          'Use ductape_cli when that resource is supported by the CLI; otherwise configure it in Workbench. ' +
+          'The runtime proxy uses a publishable key and cannot administer platform assets.',
+        );
+      }
       const key = args.publishable_key || process.env.DUCTAPE_PUBLISHABLE_KEY;
       if (!key) {
         throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
@@ -3592,7 +3890,10 @@ async function main() {
       if (!key) {
         throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
       }
-      const result = await generateExecutablePayload({ ...args, publishable_key: key });
+      const result = addSessionAwarenessMetadata(
+        await generateExecutablePayload({ ...args, publishable_key: key }),
+        args,
+      );
 
       let text = JSON.stringify(result ?? null, null, 2);
 
@@ -3624,7 +3925,10 @@ async function main() {
         throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
       }
       ensureSupportedSnippetOperation(args.operation_family, args.method);
-      const generated = await generateExecutablePayload({ ...args, publishable_key: key });
+      const generated = addSessionAwarenessMetadata(
+        await generateExecutablePayload({ ...args, publishable_key: key }),
+        args,
+      );
       const payload = (generated as any)?.payload ?? {};
       const snippet = buildSnippet(args.language, payload, args.operation_family, args.method);
       return {
@@ -3732,7 +4036,7 @@ async function main() {
           'index strategy, operation types) that should be confirmed with the user first.\n\n' +
           'Available topics: transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
           'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-          'notifications, resilience, features, events, logs, frontend, client, react, vue',
+          'notifications, resilience, features, events, logs, frontend, frontend-analytics, client, react, vue',
         inputSchema: docsInputSchema,
       },
       docsHandler,
@@ -3808,7 +4112,7 @@ async function main() {
           '    Step 2 — check if the database component already exists:\n' +
           '      ductape_cli("resources databases list <product_tag> --json")\n' +
           '      If a component already uses the same Atlas cluster, do NOT re-import — instead update it:\n' +
-          '        ductape_execute("databases.updateDatabase", [product_tag, db_tag, { envs: [...updated envs...] }])\n' +
+          '        use ductape_cli resource update when supported; otherwise update it in Workbench\n' +
           '      Add or change the dbName in the env\'s connection_url to switch databases on the same cluster.\n' +
           '    Step 3 — import (only if no existing component uses this cluster):\n' +
           '      Use import-persist-all with one entry per product env. Required fields per entry:\n' +