@ductape/mcp 0.1.48 → 0.1.50

package/dist/index.js

@@ -1192,9 +1192,63 @@ const docsInputSchema = z.object({
     topic: z.string().describe('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'),
+        'notifications, resilience, features, events, logs, frontend, frontend-analytics, client, react, vue'),
 });
 const DOCS = {
+    frontend: `
+DUCTAPE FRONTEND SDK GUIDE
+
+Choose one integration package:
+  React 17+  — npm install @ductape/react
+               Provider and hooks built on @ductape/client.
+               Continue with ductape_docs({ topic: "react" }).
+  Vue 3+     — npm install @ductape/vue
+               Plugin and composables built on @ductape/client.
+               Continue with ductape_docs({ topic: "vue" }).
+  Other UI   — npm install @ductape/client
+  frameworks   Use directly with Svelte, Angular, vanilla JavaScript, or a custom adapter.
+               Continue with ductape_docs({ topic: "client" }).
+
+Do not install @ductape/client separately when using @ductape/react or @ductape/vue unless the
+application also needs direct access to a client API not exposed by the framework package. Both
+framework packages wrap @ductape/client and expose the underlying client through useDuctape().
+
+SHARED APPLICATION LIFECYCLE
+  1. Create one client at the application root using a browser-safe publishableKey, proxy baseUrl,
+     default product tag, and environment slug.
+  2. Connect the real-time client only in the browser. In React use DuctapeProvider autoConnect or
+     connect() after mount; in Vue use createDuctape({ autoConnect: true }) or connect() in onMounted.
+  3. Authenticate the player with the sessions API and retain the returned session token according
+     to the application's security policy. Refresh it before expiry (the React/Vue packages provide
+     useSessionAutoRefresh) and revoke it on logout.
+  4. Pass the session value when connecting a broker that requires player-scoped authorization.
+  5. Subscribe through the framework hook/composable or the client service. Always unsubscribe on
+     component teardown; the framework integrations do this automatically for declarative hooks.
+  6. The underlying client reconnects its WebSocket and restores active subscriptions. Observe
+     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.
+  - A Ductape player session and the real-time transport connection are separate: authenticate or
+    refresh the session, then use that session when opening player-scoped broker resources.
+  - For SSR, create/connect the real-time client only on the browser side.
+
+MIGRATING A CUSTOM WRAPPER
+  - Keep @ductape/client when the wrapper implements application-specific projection or state logic.
+  - For React, move root connection ownership to DuctapeProvider, replace imperative subscriptions
+    with useBroker/useBrokerSubscription, and keep projection reduction in an application hook.
+  - For Vue, move root ownership to createDuctape(), replace imperative subscriptions with
+    useBroker/useBrokerSubscription, and keep projection reduction in an application composable.
+  - Verify session handoff, initial loading state, error state, reconnect UI, subscription cleanup,
+    and duplicate-event behavior with a live end-to-end run before removing the old wrapper.
+`.trim(),
     transactions: `
 DUCTAPE DATABASE TRANSACTIONS
 
@@ -1924,6 +1978,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" })
 
@@ -2011,6 +2066,16 @@ 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
+  Preserve the original full token on every user-context database, Event, Feature, notification,
+  storage, graph, vector, action, and other runtime operation that accepts session. Do not replace
+  it with the session tag, user ID, decoded claims, or refresh token. Durable user-initiated work
+  should retain the initiating token; intentional system/background work should be sessionless.
+
+  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: `
 DUCTAPE CACHES
@@ -2173,6 +2238,222 @@ 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
+`.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: `
 DUCTAPE FEATURES
@@ -2858,9 +3139,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:
@@ -2961,13 +3248,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 }
@@ -3037,7 +3326,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
@@ -3206,7 +3498,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
@@ -3549,7 +3844,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, client, react, vue',
+                'notifications, resilience, features, events, logs, frontend, frontend-analytics, client, react, vue',
             inputSchema: docsInputSchema,
         }, docsHandler);
         server.registerTool('ductape_cli', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.1.48",
+  "version": "0.1.50",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "test": "node scripts/check-frontend-analytics-guidance.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },

package/scripts/check-frontend-analytics-guidance.mjs

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const source = readFileSync(resolve(here, '../src/index.ts'), 'utf8');
+
+const checks = [
+  ['dedicated docs topic', /'frontend-analytics': `/],
+  ['anonymous analytics without an invented session', /Before login:[\s\S]*do not invent a session/i],
+  ['identify after authentication', /After login\/registration:[\s\S]*identify\(fullSessionToken\)/i],
+  ['identify after refresh', /After refresh:[\s\S]*identify\(newSessionToken\)/i],
+  ['clear identity on logout and account switching', /LOGOUT \/ ACCOUNT SWITCHING[\s\S]*clearSession\(\)/],
+  ['SPA route pageviews', /location\.pathname[\s\S]*analytics\.pageview/],
+  ['pageviews and custom events', /CUSTOM EVENTS[\s\S]*PAGE VIEWS/],
+  ['analytics is non-authoritative', /Analytics is never an authoritative order/],
+  ['tokens excluded from properties', /session\/refresh tokens in event[\s\S]*properties/],
+  ['hidden multiplayer state warning', /HIDDEN AND SENSITIVE DATA/],
+  ['masking review before auto-capture', /AUTO-CAPTURE — OPT IN ONLY AFTER A PRIVACY AUDIT/],
+  ['visitor ID is not authentication', /visitor ID is anonymous analytics identity, not authentication/i],
+  ['trace correlation', /traceId\s*= correlation/],
+  ['dashboard troubleshooting covers both tracks', /Investigate both tracks before blaming the SDK/],
+  ['installed exports take precedence', /Installed package types and exports determine what can be called now/],
+];
+
+for (const [name, pattern] of checks) {
+  assert.match(source, pattern, `Missing frontend analytics guidance: ${name}`);
+}
+
+assert.doesNotMatch(
+  source,
+  /analytics\.identify\(\{\s*userId/,
+  'MCP guidance must not use the obsolete identify({ userId, traits }) signature',
+);
+
+console.log(`frontend analytics guidance: ${checks.length + 1} acceptance checks passed`);

package/src/index.ts

@@ -1242,11 +1242,66 @@ 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',
+    'notifications, resilience, features, events, logs, frontend, frontend-analytics, client, react, vue',
   ),
 });
 
 const DOCS: Record<string, string> = {
+  frontend: `
+DUCTAPE FRONTEND SDK GUIDE
+
+Choose one integration package:
+  React 17+  — npm install @ductape/react
+               Provider and hooks built on @ductape/client.
+               Continue with ductape_docs({ topic: "react" }).
+  Vue 3+     — npm install @ductape/vue
+               Plugin and composables built on @ductape/client.
+               Continue with ductape_docs({ topic: "vue" }).
+  Other UI   — npm install @ductape/client
+  frameworks   Use directly with Svelte, Angular, vanilla JavaScript, or a custom adapter.
+               Continue with ductape_docs({ topic: "client" }).
+
+Do not install @ductape/client separately when using @ductape/react or @ductape/vue unless the
+application also needs direct access to a client API not exposed by the framework package. Both
+framework packages wrap @ductape/client and expose the underlying client through useDuctape().
+
+SHARED APPLICATION LIFECYCLE
+  1. Create one client at the application root using a browser-safe publishableKey, proxy baseUrl,
+     default product tag, and environment slug.
+  2. Connect the real-time client only in the browser. In React use DuctapeProvider autoConnect or
+     connect() after mount; in Vue use createDuctape({ autoConnect: true }) or connect() in onMounted.
+  3. Authenticate the player with the sessions API and retain the returned session token according
+     to the application's security policy. Refresh it before expiry (the React/Vue packages provide
+     useSessionAutoRefresh) and revoke it on logout.
+  4. Pass the session value when connecting a broker that requires player-scoped authorization.
+  5. Subscribe through the framework hook/composable or the client service. Always unsubscribe on
+     component teardown; the framework integrations do this automatically for declarative hooks.
+  6. The underlying client reconnects its WebSocket and restores active subscriptions. Observe
+     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.
+  - A Ductape player session and the real-time transport connection are separate: authenticate or
+    refresh the session, then use that session when opening player-scoped broker resources.
+  - For SSR, create/connect the real-time client only on the browser side.
+
+MIGRATING A CUSTOM WRAPPER
+  - Keep @ductape/client when the wrapper implements application-specific projection or state logic.
+  - For React, move root connection ownership to DuctapeProvider, replace imperative subscriptions
+    with useBroker/useBrokerSubscription, and keep projection reduction in an application hook.
+  - For Vue, move root ownership to createDuctape(), replace imperative subscriptions with
+    useBroker/useBrokerSubscription, and keep projection reduction in an application composable.
+  - Verify session handoff, initial loading state, error state, reconnect UI, subscription cleanup,
+    and duplicate-event behavior with a live end-to-end run before removing the old wrapper.
+`.trim(),
+
   transactions: `
 DUCTAPE DATABASE TRANSACTIONS
 
@@ -1991,6 +2046,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" })
 
@@ -2079,6 +2135,16 @@ 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
+  Preserve the original full token on every user-context database, Event, Feature, notification,
+  storage, graph, vector, action, and other runtime operation that accepts session. Do not replace
+  it with the session tag, user ID, decoded claims, or refresh token. Durable user-initiated work
+  should retain the initiating token; intentional system/background work should be sessionless.
+
+  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: `
@@ -2246,6 +2312,223 @@ Input template references: $Input{field} → maps declared input to the probe's
 Provider status: available | unavailable
 `.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: `
 DUCTAPE FEATURES
 
@@ -2933,9 +3216,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:
@@ -3037,13 +3326,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 }
@@ -3113,7 +3404,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
@@ -3283,7 +3577,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
@@ -3682,7 +3979,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, client, react, vue',
+          'notifications, resilience, features, events, logs, frontend, frontend-analytics, client, react, vue',
         inputSchema: docsInputSchema,
       },
       docsHandler,