@stackable-labs/mcp-app-extension 1.22.0 → 1.23.0

package/dist/index.js

@@ -465,11 +465,19 @@ ${iconList}
 var HOOK_SNIPPETS = {
   "events:identity": `import { useIdentityEvent } from '@stackable-labs/sdk-extension-react'
 
+// manifest events: ["identity:login", "identity:logout", "identity:refresh"]
 useIdentityEvent('login', (event) => {
-  console.log('User logged in:', event.data.state.user?.email)
+  // event.data.state.user.metadata is populated with any enrichment from sibling
+  // extensions with identity:extend (declared in their manifest.identityClaims)
+  console.log('User logged in:', event.data.state.user?.email, event.data.state.user?.metadata)
 })
 useIdentityEvent('logout', () => {
   console.log('User logged out')
+})
+// identity:refresh fires after any extension calls capabilities.identity.extend({...}).
+// Listen here to react to post-login enrichment (verification, tier upgrades, etc.).
+useIdentityEvent('refresh', (event) => {
+  console.log('Identity refreshed \u2014 metadata:', event.data.state.user?.metadata)
 })`,
   "events:messaging": `import { useMessagingEvent } from '@stackable-labs/sdk-extension-react'
 
@@ -481,11 +489,23 @@ useMessagingEvent('postback:Buy Now', (event) => {
 useActivityEvent('product_view', (event) => {
   console.log('Activity:', event.eventName, event.data)
 })`,
-  "extend.identity": `import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
-
+  "identity.extend": `import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
+
+// manifest.json:
+//   {
+//     "permissions": ["identity:extend"],
+//     "identityClaims": ["loyalty_tier", "verified", "verified_by", "verified_at"]
+//   }
+// Standard JWT claims (external_id, email, name) are exempt from declaration.
+// Custom claims must be in manifest.identityClaims or they're dropped with a warn.
+//
+// Fires ONCE at initial login \u2014 return what's known synchronously. For post-login
+// async updates (e.g., after verification completes via a webhook or polling),
+// use capabilities.identity.extend(patch) \u2014 see the 'identity.extend' capability.
 useExtendIdentity((claims) => ({
-  external_id: \`custom_\${claims.external_id}\`,
-  loyalty_tier: 'gold',
+  external_id: \`custom_\${claims.external_id}\`,   // standard claim override (exempt)
+  loyalty_tier: 'bronze',                           // custom \u2014 sync, known at login
+  verified: false,                                  // custom \u2014 default; updated async post-verification
 }))`
 };
 var HOOK_SNIPPETS_MEMOIZED = {
@@ -497,13 +517,19 @@ const handlePostback = useCallback<MessagingEventHandler>((event) => {
   console.log('Postback:', event.data.actionName, event.data.conversationId)
 }, [])
 useMessagingEvent('postback:Buy Now', handlePostback)`,
-  "extend.identity": `import { useCallback } from 'react'
+  "identity.extend": `import { useCallback } from 'react'
 import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
 import type { ExtendIdentityHandler } from '@stackable-labs/sdk-extension-contracts'
 
+// manifest.json:
+//   {
+//     "permissions": ["identity:extend"],
+//     "identityClaims": ["loyalty_tier", "verified", "verified_by", "verified_at"]
+//   }
 const handleExtend = useCallback<ExtendIdentityHandler>((claims) => ({
-  external_id: \`custom_\${claims.external_id}\`,
-  loyalty_tier: 'gold',
+  external_id: \`custom_\${claims.external_id}\`,   // standard claim override (exempt)
+  loyalty_tier: 'bronze',                           // custom \u2014 sync, known at login
+  verified: false,                                  // custom \u2014 default; updated async post-verification
 }), [])
 useExtendIdentity(handleExtend)`
 };
@@ -515,7 +541,7 @@ var generateCapabilities = () => {
   const fm = frontmatter({
     root: false,
     targets: ["*"],
-    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke, extend:identity, events:identity, events:messaging, events:activity",
+    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke, identity.extend, events:identity, events:messaging, events:activity",
     globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
   });
   return `${fm}
@@ -722,22 +748,89 @@ ${HOOK_SNIPPETS["events:activity"]}
 
 **Generic alternative:** \`useEvent('activity:product_view', handler)\` \u2014 a cross-domain hook that accepts fully-qualified event types. Domain wildcard (e.g., \`'activity'\`) receives all events in that domain.
 
-## extend:identity \u2014 Identity Claim Enrichment
-Enrich identity JWT claims before signing. The framework sends base claims to your extension, and you return additional claims to merge into the token.
-- **Permission required:** \`extend:identity\`
-- **Hook:** \`useExtendIdentity(handler)\` \u2014 \`ExtendIdentityHandler\` type exported for use with \`useCallback\`
-- **Handler signature:** \`(claims: IdentityBaseClaims) => Record<string, unknown> | Promise<Record<string, unknown>>\`
-- **IdentityBaseClaims:** \`{ external_id: string, email?: string, name?: string, [key: string]: unknown }\`
+## identity.extend \u2014 Identity Claim Enrichment
+Enrich identity JWT claims and \`identityState.user.metadata\` so the current user's signed token AND any sibling extension can react to them. Two complementary APIs:
+
+1. **\`useExtendIdentity(handler)\`** \u2014 synchronous hook that fires ONCE at initial login.
+2. **\`capabilities.identity.extend(patch)\`** \u2014 imperative call that fires at any time after login (post-verification, post-checkout, any user-triggered async flow). Re-signs the JWT, updates \`user.metadata\`, and broadcasts \`identity:refresh\`.
+
+Both share the **\`identity:extend\`** permission and the **\`manifest.identityClaims\`** declaration gate.
+
+### Manifest contract
 
 \`\`\`json
 {
-  "permissions": ["extend:identity"]
+  "permissions": ["identity:extend"],
+  "identityClaims": ["loyalty_tier", "verified", "verified_by", "verified_at"]
 }
 \`\`\`
 
+- **Standard JWT claims (\`external_id\`, \`email\`, \`name\`) are exempt** \u2014 they're part of the signing contract and may be overridden without declaration.
+- **Custom keys MUST be declared in \`identityClaims\`** or the host filter drops them with a \`console.warn\`.
+- **Reserved JWT/Zendesk keys** (\`iss\`, \`sub\`, \`aud\`, \`exp\`, \`nbf\`, \`iat\`, \`jti\`, \`scope\`, \`email_verified\`, \`user_fields\`) **cannot** appear in \`identityClaims\` \u2014 the Lambda sanitizer always wins on collision.
+- **Key format:** \`/^[a-z_][a-z0-9_]{0,63}$/\` (lowercase identifier, \u226464 chars).
+- **Maximum 20 entries.**
+
+### Initial-login enrichment (handler-style)
+
+- **Hook:** \`useExtendIdentity(handler)\` \u2014 \`ExtendIdentityHandler\` type exported for use with \`useCallback\`
+- **Handler signature:** \`(claims: IdentityBaseClaims) => Record<string, unknown> | Promise<Record<string, unknown>>\`
+- **IdentityBaseClaims:** \`{ external_id: string, email?: string, name?: string, [key: string]: unknown }\`
+
 \`\`\`tsx
-${HOOK_SNIPPETS["extend.identity"]}
+${HOOK_SNIPPETS["identity.extend"]}
 \`\`\`
+
+### Async post-login push (imperative)
+
+\`\`\`tsx
+const capabilities = useCapabilities()
+
+// Anytime after login \u2014 webhook callback, user action, async verification, etc.
+await capabilities.identity.extend({
+  verified: true,
+  verified_by: 'xyzProvider',
+  verified_at: new Date().toISOString(),
+})
+// \u2192 host filters against manifest.identityClaims
+// \u2192 user.metadata updated
+// \u2192 JWT re-signed, pushed to Zendesk loginUser
+// \u2192 identity:refresh broadcast to all extensions with events:identity
+\`\`\`
+
+Per-extension calls are serialized to prevent concurrent Zendesk \`loginUser\` callbacks from orphaning each other (empirically verified in the loginUser re-auth spike).
+
+### Consuming enriched state from another extension
+
+Any extension with \`events:identity\` permission can react to enrichment updates. Same minimal pattern as the \`events:identity\` section above \u2014 \`'login'\` covers the initial enriched state, \`'refresh'\` covers post-login pushes:
+
+\`\`\`tsx
+${HOOK_SNIPPETS["events:identity"]}
+\`\`\`
+
+For a snapshot read instead of event-driven reaction (auto re-renders when context changes):
+
+\`\`\`tsx
+const { identity } = useContextData()
+const verified = Boolean(identity?.user?.metadata?.verified)
+\`\`\`
+
+### Install-time enforcement
+
+Two enabled extensions on the same instance **MUST NOT** declare overlapping \`identityClaims\` keys. The runtime merge is order-dependent (\`Object.assign\` across per-extension contributions), so one extension's value would silently overwrite the other's. The marketplace install API blocks the install with a 409 conflict, surfacing the specific overlapping key + conflicting extension name in the admin install dialog. Coordinate keys with downstream extensions or namespace them (e.g. \`<vendor>_loyalty_tier\`).
+
+### Bundle-scan findings at upload
+
+The publisher-side bundle scan validates your declaration at submission time:
+
+| Finding | Severity | Triggers when |
+| --- | --- | --- |
+| \`identityClaims_missing\` | warning | \`identity:extend\` declared, \`identityClaims\` empty (custom claims would be dropped) |
+| \`identityClaims_no_permission\` | warning | \`identityClaims\` declared, \`identity:extend\` permission missing |
+| \`identityClaims_invalid_key\` | error | Key fails the format regex |
+| \`identityClaims_reserved_key\` | error | Collides with a reserved JWT / Zendesk claim |
+| \`identityClaims_standard_key\` | warning | Redundant \u2014 standard claims (\`external_id\`, \`email\`, \`name\`) are exempt |
+| \`identityClaims_too_many\` | error | More than 20 entries |
 `;
 };
 
@@ -975,35 +1068,94 @@ export function Content(): React.ReactElement {
     </Surface>
   )
 }`,
-  "extend.identity": `import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
-import type { ExtendIdentityHandler } from '@stackable-labs/sdk-extension-contracts'
+  "identity.extend": `import { useCapabilities, useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+import type { ContextData } from '@stackable-labs/sdk-extension-contracts'
 
-// Enrich identity JWT claims before signing.
-// The host sends base claims (external_id, email, name),
-// and your handler returns additional claims to merge.
-useExtendIdentity((claims) => ({
-  external_id: \`shopify_\${claims.external_id}\`,
-  loyalty_tier: 'gold',
-}))`,
+// manifest.json:
+//   {
+//     "permissions": ["identity:extend"],
+//     "identityClaims": ["verified", "verified_by", "verified_at"]
+//   }
+//
+// PUSH side \u2014 capabilities.identity.extend(patch) sends new claims to the host
+// AFTER initial login. The host filters the patch against manifest.identityClaims,
+// merges into user.metadata, re-signs the JWT, and broadcasts identity:refresh.
+//
+// CONSUMER side \u2014 useContextData() already re-renders on every host-pushed
+// context update (login/logout/refresh/expired). For pure rendering, read the
+// enriched value directly from ctx.identity.user.metadata \u2014 no event listener
+// needed. Use useIdentityEvent only when you need a SIDE EFFECT (analytics,
+// cache invalidation, etc.) on a specific event.
+//
+// Standard JWT claims (external_id, email, name) are exempt from declaration.
+// Undeclared custom keys are dropped client-side with a console.warn.
+export function Content(): React.ReactElement {
+  const capabilities = useCapabilities()
+  const ctx = useContextData() as ContextData & { loading: boolean }
+
+  // Push: trigger after async verification (webhook, polling, user action)
+  const runVerification = async () => {
+    await new Promise(r => setTimeout(r, 1000))   // simulated async work
+    await capabilities.identity.extend({
+      verified: true,
+      verified_by: 'xyzProvider',
+      verified_at: new Date().toISOString(),
+    })
+  }
+
+  // Consume: read directly from ctx \u2014 re-renders automatically on identity:refresh.
+  const verified = Boolean(ctx.identity?.user?.metadata?.verified)
+
+  return (
+    <Surface id="slot.content">
+      <ui.Stack direction="column" gap="2" className="p-3">
+        <ui.Button onClick={runVerification}>Verify</ui.Button>
+        <ui.Text>Status: {verified ? 'verified' : 'unverified'}</ui.Text>
+      </ui.Stack>
+    </Surface>
+  )
+}`,
   // ── Per-event example snippets ─────────────────────────────────────────────
-  "events:identity": `import { useIdentityEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'
+  "events:identity": `import { Surface, ui, useContextData, useIdentityEvent } from '@stackable-labs/sdk-extension-react'
 import type { IdentityEvent } from '@stackable-labs/sdk-extension-contracts'
-import { useState } from 'react'
 
+// useIdentityEvent \u2014 for SIDE EFFECTS on identity lifecycle events.
+// If you just want to RENDER based on identity state (e.g. show the current
+// user's email), use useContextData() \u2014 it re-renders reactively on every
+// host-pushed identity change. Use useIdentityEvent only when you need to
+// RUN imperative code on a specific event: analytics beacons, cookie writes,
+// downstream system notifications, cache invalidation, etc.
+//
+// manifest.json:
+//   {
+//     "permissions": ["context:read", "events:identity"],
+//     "events": ["identity:login", "identity:logout"]
+//   }
 export function Header(): React.ReactElement {
-  const [user, setUser] = useState<string | null>(null)
+  const ctx = useContextData()
 
+  // Side effect: persist a "last login" hint to localStorage on every login.
+  // Replace with your real-world side effect \u2014 analytics beacon, cookie write,
+  // downstream system notification, etc.
   useIdentityEvent('login', (event: IdentityEvent) => {
-    setUser(event.data.state.user?.email ?? null)
+    localStorage.setItem('last-login', JSON.stringify({
+      userId: event.data.state.user?.id,
+      timestamp: new Date().toISOString(),
+    }))
   })
 
+  // Clear the hint on logout / session expiry.
   useIdentityEvent('logout', () => {
-    setUser(null)
+    localStorage.removeItem('last-login')
   })
 
+  // Rendering: read directly from ctx \u2014 DON'T mirror identity into local
+  // useState via the event listener; useContextData is already reactive.
+  const email = ctx?.identity?.user?.email ?? null
+
   return (
     <Surface id="slot.header">
-      <ui.Text className="text-xs">{user ?? 'Not logged in'}</ui.Text>
+      <ui.Text className="text-xs">{email ?? 'Not logged in'}</ui.Text>
     </Surface>
   )
 }`,
@@ -1082,7 +1234,7 @@ const capabilities = useCapabilities()
 // capabilities.data.fetch(url, init?)
 // capabilities.actions.toast(payload)
 // capabilities.actions.invoke(action, payload?) \u2014 actions: newConversation, setConversationTags, setConversationFields, open, close, show, hide
-// capabilities.extend.identity(payload) \u2014 enrich identity claims (prefer useExtendIdentity hook)
+// capabilities.identity.extend(patch) \u2014 push enrichment claims to user.metadata + JWT custom_claims (imperative; for handler-style at login, use useExtendIdentity hook). Each patch key MUST be declared in manifest.identityClaims or the host filter drops it.
 \`\`\`
 
 ## useStore(store, selector?)
@@ -1180,17 +1332,17 @@ useEvent('activity', (event) => {
 \`\`\`
 
 ## useExtendIdentity(handler)
-Register a handler to enrich identity JWT claims before signing. Requires \`extend:identity\` permission.
+Register a handler to enrich identity JWT claims before signing. Requires \`identity:extend\` permission.
 - \`handler: ExtendIdentityHandler\` \u2014 \`(claims: IdentityBaseClaims) => Record<string, unknown> | Promise<Record<string, unknown>>\`
 - \`IdentityBaseClaims: { external_id: string, email?: string, name?: string, [key: string]: unknown }\`
 
 \`\`\`tsx
-${stripImports(HOOK_SNIPPETS["extend.identity"])}
+${stripImports(HOOK_SNIPPETS["identity.extend"])}
 \`\`\`
 
 With \`useCallback\` (for memoized handlers):
 \`\`\`tsx
-${HOOK_SNIPPETS_MEMOIZED["extend.identity"]}
+${HOOK_SNIPPETS_MEMOIZED["identity.extend"]}
 \`\`\`
 
 ## Identity via context.read()
@@ -2506,7 +2658,7 @@ filtered out. Clicking a surface adds it to your manifest and inserts a
 ### Capabilities
 
 The SDK capabilities your extension can use: \`data.query\`, \`data.fetch\`,
-\`context.read\`, \`actions.toast\`, \`actions.invoke\`, \`extend.identity\`,
+\`context.read\`, \`actions.toast\`, \`actions.invoke\`, \`identity.extend\`,
 \`events:identity\`, \`events:messaging\`, and \`events:activity\`. Clicking a
 capability adds the permission to your manifest and AI-inserts the hook usage.
 
@@ -3554,30 +3706,13 @@ var generateCookbookEvents = () => {
   });
   return `${fm}
 
-# Events & Extensions
-
-Subscribe to real-time events pushed from the host via the framework, and extend identity claims.
-Each event type has a dedicated hook \u2014 never use \`capabilities.events.*\` directly.
-
-## Identity Events
-
-Subscribe to login, logout, refresh, and expired events. Useful for tracking
-agent authentication state in your extension.
-
-**Permission:** \`events:identity\`
-**Event types:** ${identityEventTypes2}
-
-### Hook usage
-
-\`\`\`tsx
-${HOOK_SNIPPETS["events:identity"]}
-\`\`\`
-
-### Full component example
+# Events & Identity
 
-\`\`\`tsx
-${EXAMPLE_SNIPPETS["events:identity"]}
-\`\`\`
+Subscribe to real-time events pushed from the host via the framework, and enrich identity
+claims. Each event type has a dedicated hook (\`useIdentityEvent\` / \`useMessagingEvent\` /
+\`useActivityEvent\`) \u2014 never use \`capabilities.events.*\` directly. Identity enrichment
+supports both a login-time hook (\`useExtendIdentity\`) and an imperative post-login API
+(\`capabilities.identity.extend\`).
 
 ## Messaging Events
 
@@ -3619,24 +3754,54 @@ ${HOOK_SNIPPETS["events:activity"]}
 ${EXAMPLE_SNIPPETS["events:activity"]}
 \`\`\`
 
-## Extend Identity
+## Identity Events
 
-Enrich identity JWT claims before signing. The host sends base claims
-(\`external_id\`, \`email\`, \`name\`) and your handler returns additional
-claims to merge into the token.
+Subscribe to login, logout, refresh, and expired events. Useful for tracking
+agent authentication state and reacting to identity enrichment pushed from sibling
+extensions (via \`capabilities.identity.extend\` \u2014 see *Extend Identity* below).
 
-**Permission:** \`extend:identity\`
+**Permission:** \`events:identity\`
+**Event types:** ${identityEventTypes2}
 
 ### Hook usage
 
 \`\`\`tsx
-${HOOK_SNIPPETS["extend.identity"]}
+${HOOK_SNIPPETS["events:identity"]}
 \`\`\`
 
 ### Full component example
 
 \`\`\`tsx
-${EXAMPLE_SNIPPETS["extend.identity"]}
+${EXAMPLE_SNIPPETS["events:identity"]}
+\`\`\`
+
+## Extend Identity
+
+Enrich identity JWT claims and \`user.metadata\` so the signed token AND any sibling
+extension with \`events:identity\` can react. Two complementary paths:
+
+- **\`useExtendIdentity(handler)\`** \u2014 synchronous hook, fires ONCE at initial login. Use
+  for known-at-login enrichment.
+- **\`capabilities.identity.extend(patch)\`** \u2014 imperative call, fires post-login (after
+  async verification, webhook callbacks, user-triggered flows). Re-signs the JWT and
+  broadcasts \`identity:refresh\` to all extensions with \`events:identity\`.
+
+Both paths share the **\`identity:extend\`** permission and the **\`manifest.identityClaims\`**
+declaration gate. Standard JWT claims (\`external_id\`, \`email\`, \`name\`) are exempt;
+custom keys must be declared or they're dropped by the host filter with a \`console.warn\`.
+
+**Permission:** \`identity:extend\`
+
+### Login-time hook (useExtendIdentity)
+
+\`\`\`tsx
+${HOOK_SNIPPETS["identity.extend"]}
+\`\`\`
+
+### Imperative post-login (capabilities.identity.extend)
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["identity.extend"]}
 \`\`\`
 `;
 };
@@ -3700,10 +3865,148 @@ Only add permissions that aren't already declared.
 `;
 };
 
+// ../../sdk/extension/ai-docs/src/snippets/capabilities.ts
+var EXTEND_IDENTITY_HOOK_EXAMPLE = `// Enrich identity JWT claims before signing.
+// The host sends base claims (external_id, email, name); your handler returns
+// additional claims to merge. Returned keys are filtered against manifest.identityClaims:
+//   - Standard JWT claims (external_id, email, name) are exempt \u2014 always allowed
+//   - Custom claims must be declared in manifest.identityClaims
+//   - Undeclared keys are dropped with a console.warn
+// Merged claims land in BOTH identityState.user.metadata (for sibling extensions)
+// AND the signed JWT's custom_claims (for downstream JWT consumers).
+// Pattern: name the handler with useCallback<ExtendIdentityHandler> for stable
+// reference + clean separation; pass the named const to useExtendIdentity.
+//
+// useExtendIdentity fires ONCE at initial login \u2014 return what's known synchronously.
+// For post-login async updates (e.g., after verification completes via a webhook
+// or polling), use capabilities.identity.extend(patch) \u2014 see the 'identity.extend'
+// capability for the imperative path.
+
+${HOOK_SNIPPETS_MEMOIZED["identity.extend"]}`;
+var CAPABILITY_SNIPPETS = {
+  "data.query": `
+const capabilities = useCapabilities()
+const result = await capabilities.data.query({ path: '/your-endpoint', method: 'GET' })
+`,
+  "data.fetch": `
+const capabilities = useCapabilities()
+const response = await capabilities.data.fetch('https://api.example.com/endpoint')
+`,
+  "context.read": `
+// Read host context + extension settings
+const { customerId, settings } = useContextData()
+
+// Or use the convenience hook for settings only
+const settings = useSettings()
+`,
+  "actions.toast": `
+const capabilities = useCapabilities()
+capabilities.actions.toast({ type: 'success', message: 'Done!' })
+`,
+  "actions.invoke": `
+const capabilities = useCapabilities()
+
+// New conversation with tags and fields
+await capabilities.actions.invoke('newConversation', {
+  tags: ['stackable', 'order-lookup'],
+  fields: [{ id: 'stackable_action', value: 'order_status' }],
+  metadata: { orderId: '12345' },
+})
+
+// Standalone: set tags on current/next conversation
+await capabilities.actions.invoke('setConversationTags', ['escalated', 'order-issue'])
+`,
+  "events:identity": HOOK_SNIPPETS["events:identity"],
+  "events:messaging": HOOK_SNIPPETS["events:messaging"],
+  "events:activity": HOOK_SNIPPETS["events:activity"],
+  "identity.extend": `${EXTEND_IDENTITY_HOOK_EXAMPLE}
+
+// \u2500\u2500 For post-login async push (e.g., after async verification completes): \u2500\u2500\u2500\u2500\u2500
+const capabilities = useCapabilities()
+await capabilities.identity.extend({ verified: true })
+
+// Consumer side \u2014 same or sibling extension reacts via identity:refresh
+useIdentityEvent('refresh', (event) => {
+  console.log('verified =>', event.data.state.user?.metadata?.verified)
+})
+`
+};
+var EVENT_SNIPPETS = {
+  "events:identity": `import { useIdentityEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'
+import type { IdentityEvent } from '@stackable-labs/sdk-extension-contracts'
+import { useState } from 'react'
+
+// manifest events: ["identity:login", "identity:logout", "identity:refresh"]
+//
+// 'login' and 'refresh' both deliver the full IdentityState, including
+// state.user.metadata \u2014 populated by sibling extensions with identity:extend
+// (declared in their manifest.identityClaims). Subscribe to BOTH to cover the
+// initial login AND any post-login push via capabilities.identity.extend().
+export function Header(): React.ReactElement {
+  const [user, setUser] = useState<string | null>(null)
+  const [verified, setVerified] = useState(false)
+
+  useIdentityEvent('login', (event: IdentityEvent) => {
+    setUser(event.data.state.user?.email ?? null)
+    setVerified(Boolean(event.data.state.user?.metadata?.verified))
+  })
+
+  useIdentityEvent('refresh', (event: IdentityEvent) => {
+    setVerified(Boolean(event.data.state.user?.metadata?.verified))
+  })
+
+  useIdentityEvent('logout', () => {
+    setUser(null)
+    setVerified(false)
+  })
+
+  return (
+    <Surface id="slot.header">
+      <ui.Text className="text-xs">{user ?? 'Not logged in'} {verified && '\u2713'}</ui.Text>
+    </Surface>
+  )
+}`,
+  "events:messaging": `import { useMessagingEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'
+import type { MessagingEventHandler } from '@stackable-labs/sdk-extension-contracts'
+import { useState } from 'react'
+
+export function Content(): React.ReactElement {
+  const [lastPostback, setLastPostback] = useState<string | null>(null)
+
+  useMessagingEvent('postback', (event) => {
+    setLastPostback(event.data.actionName)
+  })
+
+  return (
+    <Surface id="slot.content">
+      <ui.Text className="text-xs">{lastPostback ?? 'No postbacks yet'}</ui.Text>
+    </Surface>
+  )
+}`,
+  "events:activity": `import { useActivityEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'
+import type { ActivityEventHandler } from '@stackable-labs/sdk-extension-contracts'
+import { useState } from 'react'
+
+export function Content(): React.ReactElement {
+  const [lastEvent, setLastEvent] = useState<string | null>(null)
+
+  useActivityEvent('page_view', (event) => {
+    setLastEvent(event.data.url as string)
+  })
+
+  return (
+    <Surface id="slot.content">
+      <ui.Text className="text-xs">{lastEvent ?? 'No activity yet'}</ui.Text>
+    </Surface>
+  )
+}`,
+  "identity.extend": EXTEND_IDENTITY_HOOK_EXAMPLE
+};
+
 // ../../sdk/extension/ai-docs/src/commands/add-capability.ts
 var generateAddCapabilityCommand = () => {
   const fm = frontmatter({
-    description: "Wire up a new capability (data.fetch, data.query, context.read, actions.toast, actions.invoke, extend:identity, events:identity, events:messaging, events:activity) in this extension",
+    description: "Wire up a new capability (data.fetch, data.query, context.read, actions.toast, actions.invoke, identity.extend, events:identity, events:messaging, events:activity) in this extension",
     targets: ["*"]
   });
   return `${fm}
@@ -3719,7 +4022,7 @@ Ask which capability to add. Valid capabilities:
 - \`context.read\` \u2014 read host-provided context (customerId, customerEmail, messaging.conversationId, etc.)
 - \`actions.toast\` \u2014 show toast notifications (success, error, info, warning)
 - \`actions.invoke\` \u2014 invoke host actions (e.g., open new conversation)
-- \`extend:identity\` \u2014 enrich identity JWT claims before signing
+- \`identity.extend\` \u2014 enrich identity JWT claims before signing
 - \`events:identity\` \u2014 subscribe to identity events (login, logout, refresh, expired)
 - \`events:messaging\` \u2014 subscribe to messaging events (postback button clicks)
 - \`events:activity\` \u2014 subscribe to activity events (page views, clicks, purchases)
@@ -3731,7 +4034,7 @@ Add the corresponding permission to \`packages/extension/public/manifest.json\`:
 - \`context.read\` \u2192 \`"context:read"\`
 - \`actions.toast\` \u2192 \`"actions:toast"\`
 - \`actions.invoke\` \u2192 \`"actions:invoke"\`
-- \`extend:identity\` \u2192 \`"extend:identity"\`
+- \`identity.extend\` \u2192 \`"identity:extend"\`
 - \`events:identity\` \u2192 \`"events:identity"\` (also add entries to \`events\` array, e.g. \`["identity:login", "identity:logout"]\`)
 - \`events:messaging\` \u2192 \`"events:messaging"\` (also add entries to \`events\` array, e.g. \`["messaging:postback:Buy Now"]\`)
 - \`events:activity\` \u2192 \`"events:activity"\` (also add entries to \`events\` array, e.g. \`["activity:product_view"]\`)
@@ -3773,8 +4076,14 @@ const capabilities = useCapabilities()
 // actions.invoke: capabilities.actions.invoke('newConversation', { tags: ['order'], fields: [{ id: 'field_id', value: 'val' }] })
 \`\`\`
 
-### For events and extend \u2014 ALWAYS use dedicated hooks (INSTEAD of useCapabilities direct):
-**IMPORTANT:** Event and extend capabilities have their own React hooks. Never use \`capabilities.events.*\` or \`capabilities.extend.*\` \u2014 those do not exist.
+### Special handling (events + identity.extend):
+
+#### For events \u2014 ALWAYS use dedicated hooks (INSTEAD of useCapabilities direct):
+Events are subscribed via \`useIdentityEvent\` / \`useMessagingEvent\` / \`useActivityEvent\` \u2014 never use \`capabilities.events.*\` directly (events are not part of the \`capabilities\` object).
+
+#### For identity.extend \u2014 choose the CORRECT option:
+- **\`useExtendIdentity(handler)\`** \u2014 synchronous hook, fires only once at initial login. ALWAYS use for known-at-login enrichment.
+- **\`capabilities.identity.extend(patch)\`** \u2014 imperative call via \`useCapabilities()\`, fires post-login (after async verification, webhook callbacks, user-triggered flows). Re-signs the JWT and broadcasts \`identity:refresh\`.
 
 \`\`\`tsx
 // events:identity \u2014 use useIdentityEvent hook
@@ -3792,8 +4101,8 @@ ${HOOK_SNIPPETS["events:activity"]}
 \`\`\`
 
 \`\`\`tsx
-// extend:identity \u2014 use useExtendIdentity hook
-${HOOK_SNIPPETS["extend.identity"]}
+// identity.extend \u2014 login-time useExtendIdentity hook OR post-login imperative capabilities.identity.extend
+${CAPABILITY_SNIPPETS["identity.extend"]}
 \`\`\`
 
 ## 6. Verify
@@ -3801,7 +4110,7 @@ ${HOOK_SNIPPETS["extend.identity"]}
 - If data.fetch, confirm the domain is in allowedDomains
 - For data/context/actions: confirm accessed via \`useCapabilities()\` hook
 - For events: confirm using \`useIdentityEvent\`, \`useMessagingEvent\`, or \`useActivityEvent\` hooks
-- For extend: confirm using \`useExtendIdentity\` hook
+- For identity.extend: confirm using \`useExtendIdentity\` hook (login-time) and/or \`capabilities.identity.extend(patch)\` (imperative post-login)
 `;
 };
 
@@ -3892,12 +4201,13 @@ Scan all \`.tsx\` files in \`packages/extension/src/\` for capability usage:
 - \`capabilities.context.read\` or \`useContextData\` \u2192 needs \`context:read\` permission
 - \`capabilities.actions.toast\` \u2192 needs \`actions:toast\` permission
 - \`capabilities.actions.invoke\` \u2192 needs \`actions:invoke\` permission
-- \`useExtendIdentity\` \u2192 needs \`extend:identity\` permission
+- \`useExtendIdentity\` or \`capabilities.identity.extend\` \u2192 needs \`identity:extend\` permission AND every custom key returned by the handler / passed to \`extend(patch)\` MUST be declared in \`manifest.identityClaims\` (standard JWT claims \`external_id\` / \`email\` / \`name\` are exempt). Undeclared keys are dropped by the host filter with a \`console.warn\`.
 ${eventHookBullets}
 
 Report:
 - **Missing permissions:** capabilities used in code but not declared in manifest
 - **Unused permissions:** permissions declared in manifest but not used in code
+- **Undeclared identityClaims:** keys returned from \`useExtendIdentity\` or passed to \`capabilities.identity.extend\` that are not in \`manifest.identityClaims\` (excluding the standard-claim exemption list)
 
 ## 3. Surface-to-target matching
 - Each \`.tsx\` file with a \`<Surface id="...">\` should have a matching target in manifest.json
@@ -4398,114 +4708,6 @@ var findRelevantSkills = (skills, query) => {
   });
 };
 
-// ../../sdk/extension/ai-docs/src/snippets/capabilities.ts
-var CAPABILITY_SNIPPETS = {
-  "data.query": `
-const capabilities = useCapabilities()
-const result = await capabilities.data.query({ path: '/your-endpoint', method: 'GET' })
-`,
-  "data.fetch": `
-const capabilities = useCapabilities()
-const response = await capabilities.data.fetch('https://api.example.com/endpoint')
-`,
-  "context.read": `
-// Read host context + extension settings
-const { customerId, settings } = useContextData()
-
-// Or use the convenience hook for settings only
-const settings = useSettings()
-`,
-  "actions.toast": `
-const capabilities = useCapabilities()
-capabilities.actions.toast({ type: 'success', message: 'Done!' })
-`,
-  "actions.invoke": `
-const capabilities = useCapabilities()
-
-// New conversation with tags and fields
-await capabilities.actions.invoke('newConversation', {
-  tags: ['stackable', 'order-lookup'],
-  fields: [{ id: 'stackable_action', value: 'order_status' }],
-  metadata: { orderId: '12345' },
-})
-
-// Standalone: set tags on current/next conversation
-await capabilities.actions.invoke('setConversationTags', ['escalated', 'order-issue'])
-`,
-  "events:identity": HOOK_SNIPPETS["events:identity"],
-  "events:messaging": HOOK_SNIPPETS["events:messaging"],
-  "events:activity": HOOK_SNIPPETS["events:activity"],
-  "extend.identity": HOOK_SNIPPETS["extend.identity"]
-};
-var EVENT_SNIPPETS = {
-  "events:identity": `import { useIdentityEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'
-import type { IdentityEvent } from '@stackable-labs/sdk-extension-contracts'
-import { useState } from 'react'
-
-export function Header(): React.ReactElement {
-  const [user, setUser] = useState<string | null>(null)
-
-  useIdentityEvent('login', (event: IdentityEvent) => {
-    setUser(event.data.state.user?.email ?? null)
-  })
-
-  useIdentityEvent('logout', () => {
-    setUser(null)
-  })
-
-  return (
-    <Surface id="slot.header">
-      <ui.Text className="text-xs">{user ?? 'Not logged in'}</ui.Text>
-    </Surface>
-  )
-}`,
-  "events:messaging": `import { useMessagingEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'
-import type { MessagingEventHandler } from '@stackable-labs/sdk-extension-contracts'
-import { useState } from 'react'
-
-export function Content(): React.ReactElement {
-  const [lastPostback, setLastPostback] = useState<string | null>(null)
-
-  useMessagingEvent('postback', (event) => {
-    setLastPostback(event.data.actionName)
-  })
-
-  return (
-    <Surface id="slot.content">
-      <ui.Text className="text-xs">{lastPostback ?? 'No postbacks yet'}</ui.Text>
-    </Surface>
-  )
-}`,
-  "events:activity": `import { useActivityEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'
-import type { ActivityEventHandler } from '@stackable-labs/sdk-extension-contracts'
-import { useState } from 'react'
-
-export function Content(): React.ReactElement {
-  const [lastEvent, setLastEvent] = useState<string | null>(null)
-
-  useActivityEvent('page_view', (event) => {
-    setLastEvent(event.data.url as string)
-  })
-
-  return (
-    <Surface id="slot.content">
-      <ui.Text className="text-xs">{lastEvent ?? 'No activity yet'}</ui.Text>
-    </Surface>
-  )
-}`,
-  "extend.identity": `import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
-import type { ExtendIdentityHandler } from '@stackable-labs/sdk-extension-contracts'
-
-// Enrich identity JWT claims before signing.
-// The host sends base claims (external_id, email, name),
-// and your handler returns additional claims to merge.
-// Use ExtendIdentityHandler type with useCallback for memoized handlers.
-useExtendIdentity((claims) => ({
-  external_id: \`shopify_\${claims.external_id}\`,
-  loyalty_tier: 'gold',
-}))`
-};
-
 // ../../sdk/extension/ai-docs/src/generated/example-snippets-jsx.ts
 var EXAMPLE_SNIPPETS2 = {
   "bootstrap": `import { createExtension } from '@stackable-labs/sdk-extension-react'
@@ -4730,32 +4932,91 @@ export function Content() {
     </Surface>
   )
 }`,
-  "extend.identity": `import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
+  "identity.extend": `import { useCapabilities, useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
 
-// Enrich identity JWT claims before signing.
-// The host sends base claims (external_id, email, name),
-// and your handler returns additional claims to merge.
-useExtendIdentity((claims) => ({
-  external_id: \`shopify_\${claims.external_id}\`,
-  loyalty_tier: 'gold',
-}))`,
-  "events:identity": `import { useIdentityEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'
-import { useState } from 'react'
+// manifest.json:
+//   {
+//     "permissions": ["identity:extend"],
+//     "identityClaims": ["verified", "verified_by", "verified_at"]
+//   }
+//
+// PUSH side \u2014 capabilities.identity.extend(patch) sends new claims to the host
+// AFTER initial login. The host filters the patch against manifest.identityClaims,
+// merges into user.metadata, re-signs the JWT, and broadcasts identity:refresh.
+//
+// CONSUMER side \u2014 useContextData() already re-renders on every host-pushed
+// context update (login/logout/refresh/expired). For pure rendering, read the
+// enriched value directly from ctx.identity.user.metadata \u2014 no event listener
+// needed. Use useIdentityEvent only when you need a SIDE EFFECT (analytics,
+// cache invalidation, etc.) on a specific event.
+//
+// Standard JWT claims (external_id, email, name) are exempt from declaration.
+// Undeclared custom keys are dropped client-side with a console.warn.
+export function Content() {
+  const capabilities = useCapabilities()
+  const ctx = useContextData()
+
+  // Push: trigger after async verification (webhook, polling, user action)
+  const runVerification = async () => {
+    await new Promise(r => setTimeout(r, 1000))   // simulated async work
+    await capabilities.identity.extend({
+      verified: true,
+      verified_by: 'xyzProvider',
+      verified_at: new Date().toISOString(),
+    })
+  }
 
+  // Consume: read directly from ctx \u2014 re-renders automatically on identity:refresh.
+  const verified = Boolean(ctx.identity?.user?.metadata?.verified)
+
+  return (
+    <Surface id="slot.content">
+      <ui.Stack direction="column" gap="2" className="p-3">
+        <ui.Button onClick={runVerification}>Verify</ui.Button>
+        <ui.Text>Status: {verified ? 'verified' : 'unverified'}</ui.Text>
+      </ui.Stack>
+    </Surface>
+  )
+}`,
+  "events:identity": `import { Surface, ui, useContextData, useIdentityEvent } from '@stackable-labs/sdk-extension-react'
+
+// useIdentityEvent \u2014 for SIDE EFFECTS on identity lifecycle events.
+// If you just want to RENDER based on identity state (e.g. show the current
+// user's email), use useContextData() \u2014 it re-renders reactively on every
+// host-pushed identity change. Use useIdentityEvent only when you need to
+// RUN imperative code on a specific event: analytics beacons, cookie writes,
+// downstream system notifications, cache invalidation, etc.
+//
+// manifest.json:
+//   {
+//     "permissions": ["context:read", "events:identity"],
+//     "events": ["identity:login", "identity:logout"]
+//   }
 export function Header() {
-  const [user, setUser] = useState(null)
+  const ctx = useContextData()
 
+  // Side effect: persist a "last login" hint to localStorage on every login.
+  // Replace with your real-world side effect \u2014 analytics beacon, cookie write,
+  // downstream system notification, etc.
   useIdentityEvent('login', (event) => {
-    setUser(event.data.state.user?.email ?? null)
+    localStorage.setItem('last-login', JSON.stringify({
+      userId: event.data.state.user?.id,
+      timestamp: new Date().toISOString(),
+    }))
   })
 
+  // Clear the hint on logout / session expiry.
   useIdentityEvent('logout', () => {
-    setUser(null)
+    localStorage.removeItem('last-login')
   })
 
+  // Rendering: read directly from ctx \u2014 DON'T mirror identity into local
+  // useState via the event listener; useContextData is already reactive.
+  const email = ctx?.identity?.user?.email ?? null
+
   return (
     <Surface id="slot.header">
-      <ui.Text className="text-xs">{user ?? 'Not logged in'}</ui.Text>
+      <ui.Text className="text-xs">{email ?? 'Not logged in'}</ui.Text>
     </Surface>
   )
 }`,
@@ -4819,11 +5080,19 @@ await capabilities.actions.invoke('newConversation', {
 await capabilities.actions.invoke('setConversationTags', ['escalated', 'order-issue'])`,
   "events:identity": `import { useIdentityEvent } from '@stackable-labs/sdk-extension-react'
 
+// manifest events: ["identity:login", "identity:logout", "identity:refresh"]
 useIdentityEvent('login', (event) => {
-  console.log('User logged in:', event.data.state.user?.email)
+  // event.data.state.user.metadata is populated with any enrichment from sibling
+  // extensions with identity:extend (declared in their manifest.identityClaims)
+  console.log('User logged in:', event.data.state.user?.email, event.data.state.user?.metadata)
 })
 useIdentityEvent('logout', () => {
   console.log('User logged out')
+})
+// identity:refresh fires after any extension calls capabilities.identity.extend({...}).
+// Listen here to react to post-login enrichment (verification, tier upgrades, etc.).
+useIdentityEvent('refresh', (event) => {
+  console.log('Identity refreshed \u2014 metadata:', event.data.state.user?.metadata)
 })`,
   "events:messaging": `import { useMessagingEvent } from '@stackable-labs/sdk-extension-react'
 
@@ -4835,31 +5104,77 @@ useMessagingEvent('postback:Buy Now', (event) => {
 useActivityEvent('product_view', (event) => {
   console.log('Activity:', event.eventName, event.data)
 })`,
-  "extend.identity": `import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
+  "identity.extend": `// Enrich identity JWT claims before signing.
+// The host sends base claims (external_id, email, name); your handler returns
+// additional claims to merge. Returned keys are filtered against manifest.identityClaims:
+//   - Standard JWT claims (external_id, email, name) are exempt \u2014 always allowed
+//   - Custom claims must be declared in manifest.identityClaims
+//   - Undeclared keys are dropped with a console.warn
+// Merged claims land in BOTH identityState.user.metadata (for sibling extensions)
+// AND the signed JWT's custom_claims (for downstream JWT consumers).
+// Pattern: name the handler with useCallback<ExtendIdentityHandler> for stable
+// reference + clean separation; pass the named const to useExtendIdentity.
+//
+// useExtendIdentity fires ONCE at initial login \u2014 return what's known synchronously.
+// For post-login async updates (e.g., after verification completes via a webhook
+// or polling), use capabilities.identity.extend(patch) \u2014 see the 'identity.extend'
+// capability for the imperative path.
 
-useExtendIdentity((claims) => ({
-  external_id: \`custom_\${claims.external_id}\`,
-  loyalty_tier: 'gold',
-}))`
+import { useCallback } from 'react'
+import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
+
+// manifest.json:
+//   {
+//     "permissions": ["identity:extend"],
+//     "identityClaims": ["loyalty_tier", "verified", "verified_by", "verified_at"]
+//   }
+const handleExtend = useCallback((claims) => ({
+  external_id: \`custom_\${claims.external_id}\`,   // standard claim override (exempt)
+  loyalty_tier: 'bronze',                           // custom \u2014 sync, known at login
+  verified: false,                                  // custom \u2014 default; updated async post-verification
+}), [])
+useExtendIdentity(handleExtend)
+
+// \u2500\u2500 For post-login async push (e.g., after async verification completes): \u2500\u2500\u2500\u2500\u2500
+const capabilities = useCapabilities()
+await capabilities.identity.extend({ verified: true })
+
+// Consumer side \u2014 same or sibling extension reacts via identity:refresh
+useIdentityEvent('refresh', (event) => {
+  console.log('verified =>', event.data.state.user?.metadata?.verified)
+})`
 };
 var EVENT_SNIPPETS2 = {
   "events:identity": `import { useIdentityEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'
 import { useState } from 'react'
 
+// manifest events: ["identity:login", "identity:logout", "identity:refresh"]
+//
+// 'login' and 'refresh' both deliver the full IdentityState, including
+// state.user.metadata \u2014 populated by sibling extensions with identity:extend
+// (declared in their manifest.identityClaims). Subscribe to BOTH to cover the
+// initial login AND any post-login push via capabilities.identity.extend().
 export function Header() {
   const [user, setUser] = useState(null)
+  const [verified, setVerified] = useState(false)
 
   useIdentityEvent('login', (event) => {
     setUser(event.data.state.user?.email ?? null)
+    setVerified(Boolean(event.data.state.user?.metadata?.verified))
+  })
+
+  useIdentityEvent('refresh', (event) => {
+    setVerified(Boolean(event.data.state.user?.metadata?.verified))
   })
 
   useIdentityEvent('logout', () => {
     setUser(null)
+    setVerified(false)
   })
 
   return (
     <Surface id="slot.header">
-      <ui.Text className="text-xs">{user ?? 'Not logged in'}</ui.Text>
+      <ui.Text className="text-xs">{user ?? 'Not logged in'} {verified && '\u2713'}</ui.Text>
     </Surface>
   )
 }`,
@@ -4895,16 +5210,36 @@ export function Content() {
     </Surface>
   )
 }`,
-  "extend.identity": `import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
+  "identity.extend": `// Enrich identity JWT claims before signing.
+// The host sends base claims (external_id, email, name); your handler returns
+// additional claims to merge. Returned keys are filtered against manifest.identityClaims:
+//   - Standard JWT claims (external_id, email, name) are exempt \u2014 always allowed
+//   - Custom claims must be declared in manifest.identityClaims
+//   - Undeclared keys are dropped with a console.warn
+// Merged claims land in BOTH identityState.user.metadata (for sibling extensions)
+// AND the signed JWT's custom_claims (for downstream JWT consumers).
+// Pattern: name the handler with useCallback<ExtendIdentityHandler> for stable
+// reference + clean separation; pass the named const to useExtendIdentity.
+//
+// useExtendIdentity fires ONCE at initial login \u2014 return what's known synchronously.
+// For post-login async updates (e.g., after verification completes via a webhook
+// or polling), use capabilities.identity.extend(patch) \u2014 see the 'identity.extend'
+// capability for the imperative path.
 
-// Enrich identity JWT claims before signing.
-// The host sends base claims (external_id, email, name),
-// and your handler returns additional claims to merge.
-// Use ExtendIdentityHandler type with useCallback for memoized handlers.
-useExtendIdentity((claims) => ({
-  external_id: \`shopify_\${claims.external_id}\`,
-  loyalty_tier: 'gold',
-}))`
+import { useCallback } from 'react'
+import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
+
+// manifest.json:
+//   {
+//     "permissions": ["identity:extend"],
+//     "identityClaims": ["loyalty_tier", "verified", "verified_by", "verified_at"]
+//   }
+const handleExtend = useCallback((claims) => ({
+  external_id: \`custom_\${claims.external_id}\`,   // standard claim override (exempt)
+  loyalty_tier: 'bronze',                           // custom \u2014 sync, known at login
+  verified: false,                                  // custom \u2014 default; updated async post-verification
+}), [])
+useExtendIdentity(handleExtend)`
 };
 
 // ../../sdk/extension/ai-docs/src/index.ts