@stackable-labs/mcp-app-extension 1.30.0 → 2.0.1

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, MESSAGING_ACTION_EXAMPLES, PERMISSIONS, CAPABILITY_PERMISSION_MAP, EVENT_HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_CATEGORIES, UI_TAG_ATTRIBUTES, tagToComponentName, MESSAGING_SEND_EXAMPLES } from '@stackable-labs/sdk-extension-contracts';
+import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, MESSAGING_ACTION_EXAMPLES, PERMISSIONS, CAPABILITY_PERMISSION_MAP, HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_CATEGORIES, UI_TAG_ATTRIBUTES, tagToComponentName, EVENT_HOOK_PERMISSION_MAP, MESSAGING_SEND_EXAMPLES } from '@stackable-labs/sdk-extension-contracts';
 import { validatePatternFormat } from '@stackable-labs/lib-contracts';
 import fs4, { readFile, mkdir, writeFile, constants } from 'fs/promises';
 import path, { join } from 'path';
@@ -348,6 +348,11 @@ var CORE_CONTENT = `# Extension SDK \u2014 Editorial Notes
 - Always check the \`loading\` flag before using context values
 - Context is only available when the host provides it (e.g., when viewing a ticket)
 
+### \`messaging.send\` resolves to null without throwing
+- The host silently handles \`no_conversation\` / \`reauth_required\` / \`forbidden\` \u2014 \`send()\` returns null and \`error\` stays unset on these codes
+- These are operational/admin concerns (no active conversation, instance disconnected from messaging, permission revoked) \u2014 surfaced to admins via dashboard remediation UI, not user-actionable from the extension
+- Actionable codes (\`invalid_message\`, \`rate_limited\`, \`upstream_error\`) DO populate \`error\` and throw \u2014 handle in UI
+
 ## Best Practices
 
 ### Performance
@@ -506,7 +511,12 @@ useExtendIdentity((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
-}))`
+}))`,
+  "messaging.send": `import { useMessaging } from '@stackable-labs/sdk-extension-react'
+
+// manifest.json: { "permissions": ["messaging:send"] }
+const [send, { enabled, loading, error }] = useMessaging()
+await send({ kind: 'text', body: 'Hello from the extension' })`
 };
 var HOOK_SNIPPETS_MEMOIZED = {
   "events:messaging": `import { useCallback } from 'react'
@@ -836,7 +846,7 @@ The publisher-side bundle scan validates your declaration at submission time:
 
 Post a message into the **active conversation** bound to the current Instance. The host attributes each message to the extension via the per-Instance author label set by the admin (see "Author label" below). Two complementary APIs:
 
-1. **\`useMessaging()\`** \u2014 React hook returning tuple \`[send, { loading, error, data }]\` \u2014 lets callers rename \`send\` per-instance when used multiple times in one component. Preferred for UI components; narrows the error surface to actionable codes only.
+1. **\`useMessaging()\`** \u2014 React hook returning tuple \`[send, { enabled, loading, error, data }]\` \u2014 lets callers rename \`send\` per-instance when used multiple times in one component. Preferred for UI components; narrows the error surface to actionable codes only. Use \`enabled\` to pre-empt the silent \`no_conversation\` case **without** declaring \`context:read\`.
 2. **\`messagingSendCapability(payload)\`** / **\`capabilities.messaging.send(payload)\`** \u2014 imperative; useful outside React render. Exposes the full wire-level error taxonomy.
 
 ### Manifest contract
@@ -879,14 +889,9 @@ Four kinds:
 ### Hook usage
 
 \`\`\`tsx
-import { useMessaging, useContextData } from '@stackable-labs/sdk-extension-react'
+import { useMessaging } from '@stackable-labs/sdk-extension-react'
 
-const { messaging } = useContextData()
-const [send, { loading, error }] = useMessaging()
-
-// Proactive gate: skip the call when there's no conversation \u2014 avoids the
-// host-handled no_conversation log + null return.
-const canSend = !!messaging?.conversationId
+const [send, { enabled, loading, error }] = useMessaging()
 
 const onApprove = async () => {
   try {
@@ -900,11 +905,15 @@ const onApprove = async () => {
   }
 }
 
-if (error === 'rate_limited') {
-  // Render a "slow down" notice
-}
+return (
+  <button disabled={!enabled || loading} onClick={onApprove}>
+    {error === 'rate_limited' ? 'Slow down\u2026' : 'Approve'}
+  </button>
+)
 \`\`\`
 
+The \`enabled\` flag is a permission-free, host-pushed signal \u2014 \`true\` whenever an active conversation exists. Wiring buttons to \`disabled={!enabled || loading}\` pre-empts the silent \`no_conversation\` case without forcing the extension to declare \`context:read\`. If the extension already has \`context:read\` for other reasons, \`useContextData().messaging?.conversationId\` is an equivalent gate.
+
 ### Imperative usage
 
 \`\`\`tsx
@@ -929,7 +938,7 @@ The wire taxonomy has 6 codes. The hook (\`useMessaging\`) narrows them into two
 
 | Code | What the framework does |
 | --- | --- |
-| \`no_conversation\` | \`console.info\` \u2014 pre-empt via \`useContextData().messaging?.conversationId\` |
+| \`no_conversation\` | \`console.info\` \u2014 pre-empt via the \`enabled\` flag from \`useMessaging()\` (no permission needed) |
 | \`reauth_required\` | \`console.warn\` \u2014 admin sees a "Reconnect" CTA in the dashboard (server flips \`messagingDisconnected: true\`) |
 | \`forbidden\` | \`console.warn\` \u2014 should not reach in production with correct manifest |
 
@@ -947,7 +956,7 @@ Three gates fire in series, surfacing the same \`forbidden\` error if any blocks
 
 \`reply\` and \`postback\` action clicks fire on extensions with the \`events:messaging\` permission via \`useMessagingEvent\` \u2014 see the \`events:messaging\` section above.
 
-> **Note:** the postback \`payload\` field is currently not surfaced by the Web Widget (only the button text \`actionName\`). Until that gap is closed, design action labels to be self-describing or pair sends with a follow-up \`data.query\` lookup.
+> **Note:** the postback \`payload\` field is currently not surfaced by the Web Widget (only the button text \`actionName\`). Until that gap is closed, design action labels to be self-describing or pair sends with a follow-up \`data.fetch\` lookup.
 `;
 };
 
@@ -1310,16 +1319,12 @@ export function Content(): React.ReactElement {
     </Surface>
   )
 }`,
-  "messaging.send": `import { useMessaging, useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+  "messaging.send": `import { useMessaging, Surface, ui } from '@stackable-labs/sdk-extension-react'
 
 // Requires 'messaging:send' permission. send() throws on actionable errors
 // (state.error holds the typed code); resolves to null on host-handled cases.
 export function Content(): React.ReactElement {
-  const { messaging } = useContextData()
-  const [send, { loading, error }] = useMessaging()
-  // Proactive gate: skip the call when there's no conversation \u2014 avoids the
-  // host-handled no_conversation log + null return.
-  const canSend = !!messaging?.conversationId
+  const [send, { enabled, loading, error }] = useMessaging()
 
   const onSayHello = async () => {
     try {
@@ -1339,7 +1344,7 @@ export function Content(): React.ReactElement {
   return (
     <Surface id="slot.content">
       <ui.Stack direction="column" gap="2" className="p-3">
-        <ui.Button onClick={onSayHello} disabled={loading || !canSend}>Say hello</ui.Button>
+        <ui.Button onClick={onSayHello} disabled={!enabled || loading}>Say hello</ui.Button>
         {(error === 'rate_limited') && <ui.Alert variant="warning">Slow down \u2014 sent too many.</ui.Alert>}
         {(error === 'upstream_error') && <ui.Alert variant="error">Send failed \u2014 please try again.</ui.Alert>}
         {(error === 'invalid_message') && <ui.Alert variant="error">Send failed \u2014 message format invalid.</ui.Alert>}
@@ -1375,10 +1380,6 @@ Bootstrap the extension runtime. Call once in \`src/index.tsx\`.
 ${EXAMPLE_SNIPPETS.bootstrap}
 \`\`\`
 
-## Surface component
-Wraps content for a target slot. The \`id\` must match a target in \`manifest.json\`.
-- \`<Surface id="slot.content">...</Surface>\`
-
 ## useCapabilities()
 Returns the capabilities object for calling host-mediated APIs.
 \`\`\`tsx
@@ -1389,7 +1390,7 @@ const capabilities = useCapabilities()
 // capabilities.actions.toast(payload)
 // capabilities.actions.invoke(action, payload?) \u2014 actions: newConversation, setConversationTags, setConversationFields, open, close, show, hide
 // 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.
-// capabilities.messaging.send(payload) \u2014 post a message into the active conversation bound to this Instance. Requires messaging:send permission. Author label is admin-set per-Instance (instance.config.settings.messagingDisplayName) with extension.manifest.name fallback. For React state ([send, { loading, error, data }]), prefer the useMessaging hook.
+// capabilities.messaging.send(payload) \u2014 post a message into the active conversation bound to this Instance. Prefer the useMessaging hook instead. Requires messaging:send permission. Author label is admin-set per-Instance (instance.config.settings.messagingDisplayName) with extension.manifest.name fallback.
 \`\`\`
 
 ## useStore(store, selector?)
@@ -1398,6 +1399,17 @@ Subscribe to a shared store. Re-renders when the selected state changes.
 const viewState = useStore(appStore, (s) => s.viewState)
 \`\`\`
 
+## createStore(initialState)
+Create a shared store for cross-surface state coordination.
+\`\`\`tsx
+const appStore = createStore<AppState>({ viewState: { type: 'menu' } })
+\`\`\`
+
+**Store\\<T\\> interface**
+- \`get(): T\` \u2014 read current state
+- \`set(partial: Partial<T>): void\` \u2014 merge partial state update
+- \`subscribe(listener: (state: T) => void): () => void\` \u2014 subscribe, returns unsubscribe fn
+
 ## useContextData()
 Reads host-provided context including extension settings. Returns \`{ loading, customerId, customerEmail, messaging, settings, ... }\`. \`messaging.conversationId\` is the active Messaging conversation ID (or \`null\` until one exists).
 \`\`\`tsx
@@ -1424,26 +1436,48 @@ Returns extension-level context.
 const { extensionId } = useExtension()
 \`\`\`
 
-## createStore(initialState)
-Create a shared store for cross-surface state coordination.
+## useEvent(eventType, handler)
+Generic cross-domain event hook (should not be used unless absolutely required). Subscribe to any event using fully-qualified event types.
+- \`eventType: EventType\` \u2014 fully-qualified (e.g., \`'activity:product_view'\`, \`'identity:login'\`, \`'messaging:postback'\`)
+- Domain wildcard (e.g., \`'activity'\`) receives all events in that domain
+- \`handler: (event: BaseEvent) => void\`
+
 \`\`\`tsx
-const appStore = createStore<AppState>({ viewState: { type: 'menu' } })
+useEvent('activity', (event) => {
+  console.log('Activity:', event.data)
+})
 \`\`\`
 
-### Store\\<T\\> interface
-- \`get(): T\` \u2014 read current state
-- \`set(partial: Partial<T>): void\` \u2014 merge partial state update
-- \`subscribe(listener: (state: T) => void): () => void\` \u2014 subscribe, returns unsubscribe fn
+## useMessaging()
+Send messages into the active conversation bound to this Instance. Wraps the \`messaging.send\` capability with React state, tracking \`enabled\` / \`loading\` / \`error\` / \`data\`. Returns a tuple \`[send, state]\` so callers can rename \`send\` when the hook is used multiple times in one component. Requires \`messaging:send\` permission. The author label rendered above outbound messages is set per-Instance by the admin (Instance settings \`messagingDisplayName\`); falls back to \`extension.manifest.name\` when blank.
 
-## useIdentityEvent(eventType, handler)
-Subscribe to identity events pushed from the host via the framework. Requires \`events:identity\` permission and matching entries in manifest \`events\` array.
-- \`eventType: ${identityEventTypes}\`
-- \`handler: (event: IdentityEvent) => void\`
-- \`IdentityEvent: { eventName: IdentityEventType, data: { state: IdentityState, timestamp: string } }\`
-- \`IdentityState: { authenticated: boolean, user: UserIdentity | null, expiresAt?: string }\`
+- **Returns:** \`readonly [send, { enabled, loading, error, data }]\`
+- **\`send(payload: SendMessagePayload): Promise<SendMessageResponse | null>\`** \u2014 returns the response on success; throws on **actionable** errors; resolves to \`null\` on host-handled errors (SDK logs a breadcrumb, host surfaces remediation)
+- **\`enabled: boolean\`** \u2014 advisory; \`true\` when an active conversation exists. Permission-free (no \`context:read\` needed). Wire to button \`disabled\` to pre-empt the silent \`no_conversation\` case. Starts \`false\`; flips reactively via host-pushed availability events.
+- **\`loading: boolean\`** \u2014 true while a call is in flight (matches \`useContextData\`'s \`loading\` for SDK-wide consistency)
+- **\`data: SendMessageResponse | null\`** \u2014 \`{ messageId, receivedAt }\` from last successful send
+- **\`error: SendMessageActionableErrorCode | null\`** \u2014 one of \`invalid_message\` / \`rate_limited\` / \`upstream_error\` after a failed send. Host-handled codes (\`no_conversation\` / \`reauth_required\` / \`forbidden\`) never surface here.
+
+Payload is discriminated by \`kind\`: \`'text'\` / \`'image'\` / \`'file'\` / \`'carousel'\`. See the \`messaging.send\` capability section for the full payload table + action types.
 
 \`\`\`tsx
-${stripImports(HOOK_SNIPPETS["events:identity"])}
+import { useMessaging } from '@stackable-labs/sdk-extension-react'
+
+const [send, { enabled, loading, error }] = useMessaging()
+
+const onApprove = async () => {
+  try {
+    await send({ kind: 'text', body: 'Approved \u2713' })
+  } catch {
+    // error holds the typed SendMessageActionableErrorCode
+  }
+}
+
+return (
+  <button disabled={!enabled || loading} onClick={onApprove}>
+    Approve
+  </button>
+)
 \`\`\`
 
 ## useMessagingEvent(eventType, handler)
@@ -1474,16 +1508,15 @@ Subscribe to activity events pushed from the host via the framework. Requires \`
 ${stripImports(HOOK_SNIPPETS["events:activity"])}
 \`\`\`
 
-## useEvent(eventType, handler)
-Generic cross-domain event hook (should not be used unless absolutely required). Subscribe to any event using fully-qualified event types.
-- \`eventType: EventType\` \u2014 fully-qualified (e.g., \`'activity:product_view'\`, \`'identity:login'\`, \`'messaging:postback'\`)
-- Domain wildcard (e.g., \`'activity'\`) receives all events in that domain
-- \`handler: (event: BaseEvent) => void\`
+## useIdentityEvent(eventType, handler)
+Subscribe to identity events pushed from the host via the framework. Requires \`events:identity\` permission and matching entries in manifest \`events\` array.
+- \`eventType: ${identityEventTypes}\`
+- \`handler: (event: IdentityEvent) => void\`
+- \`IdentityEvent: { eventName: IdentityEventType, data: { state: IdentityState, timestamp: string } }\`
+- \`IdentityState: { authenticated: boolean, user: UserIdentity | null, expiresAt?: string }\`
 
 \`\`\`tsx
-useEvent('activity', (event) => {
-  console.log('Activity:', event.data)
-})
+${stripImports(HOOK_SNIPPETS["events:identity"])}
 \`\`\`
 
 ## useExtendIdentity(handler)
@@ -1500,41 +1533,12 @@ With \`useCallback\` (for memoized handlers):
 ${HOOK_SNIPPETS_MEMOIZED["identity.extend"]}
 \`\`\`
 
-## Identity via context.read()
+**Identity via context.read()**
 Identity state is available in the \`context.read()\` response as an \`identity\` field. Requires \`context:read\` permission (no separate identity permission needed).
 \`\`\`tsx
 const context = await capabilities.context.read()
 // context.identity \u2014 { authenticated, user, expiresAt? }
 \`\`\`
-
-## useMessaging()
-Send messages into the active conversation bound to this Instance. Wraps the \`messaging.send\` capability with React state, tracking \`loading\` / \`error\` / \`data\`. Returns a tuple \`[send, state]\` so callers can rename \`send\` when the hook is used multiple times in one component. Requires \`messaging:send\` permission. The author label rendered above outbound messages is set per-Instance by the admin (Instance settings \`messagingDisplayName\`); falls back to \`extension.manifest.name\` when blank.
-
-- **Returns:** \`readonly [send, { loading, error, data }]\`
-- **\`send(payload: SendMessagePayload): Promise<SendMessageResponse | null>\`** \u2014 returns the response on success; throws on **actionable** errors; resolves to \`null\` on host-handled errors (SDK logs a breadcrumb, host surfaces remediation)
-- **\`loading: boolean\`** \u2014 true while a call is in flight (matches \`useContextData\`'s \`loading\` for SDK-wide consistency)
-- **\`data: SendMessageResponse | null\`** \u2014 \`{ messageId, receivedAt }\` from last successful send
-- **\`error: SendMessageActionableErrorCode | null\`** \u2014 one of \`invalid_message\` / \`rate_limited\` / \`upstream_error\` after a failed send. Host-handled codes (\`no_conversation\` / \`reauth_required\` / \`forbidden\`) never surface here.
-
-Payload is discriminated by \`kind\`: \`'text'\` / \`'image'\` / \`'file'\` / \`'carousel'\`. See the \`messaging.send\` capability section for the full payload table + action types.
-
-\`\`\`tsx
-import { useMessaging, useContextData } from '@stackable-labs/sdk-extension-react'
-
-const { messaging } = useContextData()
-const [send, { loading, error }] = useMessaging()
-
-// Proactive gate: skip the call when there's no conversation
-const canSend = !!messaging?.conversationId
-
-const onApprove = async () => {
-  try {
-    await send({ kind: 'text', body: 'Approved \u2713' })
-  } catch {
-    // error holds the typed SendMessageActionableErrorCode
-  }
-}
-\`\`\`
 `;
 };
 
@@ -4160,7 +4164,7 @@ alongside existing surfaces.
 Add the target to the \`targets\` array in \`packages/extension/public/manifest.json\`.
 Also add any required permissions based on the target-permission mapping:
 - \`slot.header\` \u2192 \`context:read\`
-- \`slot.content\` \u2192 \`context:read\`, \`data:query\`, \`actions:toast\`, \`actions:invoke\`
+- \`slot.content\` \u2192 \`context:read\`, \`data:query\`, \`actions:toast\`, \`actions:invoke\`, \`messaging:send\`
 - \`slot.footer\` \u2192 (none)
 - \`slot.footer-links\` \u2192 (none)
 
@@ -4237,13 +4241,7 @@ useIdentityEvent('refresh', (event) => {
   console.log('verified =>', event.data.state.user?.metadata?.verified)
 })
 `,
-  "messaging.send": `
-// Send a message into the active conversation bound to this Instance.
-// Requires the 'messaging:send' permission. The author label rendered above
-// outbound messages is set per-Instance by the admin (Instance settings
-// messagingDisplayName); falls back to extension.manifest.name when blank.
-const [send, { loading, error }] = useMessaging()
-const result = await send({ kind: 'text', body: 'Hello from the extension' })
+  "messaging.send": `${HOOK_SNIPPETS["messaging.send"]}
 
 // Actionable errors throw + populate state.error: 'invalid_message' (bad payload),
 // 'rate_limited' (slow down), 'upstream_error' (transient \u2014 retry). Branch in
@@ -4251,7 +4249,8 @@ const result = await send({ kind: 'text', body: 'Hello from the extension' })
 // Host-handled cases ('no_conversation' / 'reauth_required' / 'forbidden')
 // resolve to null without throwing; the SDK logs a breadcrumb and the host
 // surfaces remediation to admins (e.g. dashboard Reconnect UI). Extensions
-// can pre-empt 'no_conversation' via useContextData().messaging?.conversationId.
+// can pre-empt 'no_conversation' via the 'enabled' flag from useMessaging()
+// (permission-free) \u2014 wire to button disabled={!enabled || loading}.
 if (error === 'rate_limited') { /* show "slow down" UI */ }
 `
 };
@@ -4330,7 +4329,7 @@ export function Content(): React.ReactElement {
 // ../../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, identity.extend, 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, messaging.send, identity.extend, events:identity, events:messaging, events:activity) in this extension",
     targets: ["*"]
   });
   return `${fm}
@@ -4346,6 +4345,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)
+- \`messaging.send\` \u2014 send messages into the active conversation bound to this Instance (text/image/file/carousel + reply/link/postback actions)
 - \`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)
@@ -4358,6 +4358,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"\`
+- \`messaging.send\` \u2192 \`"messaging:send"\`
 - \`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"]\`)
@@ -4400,12 +4401,15 @@ const capabilities = useCapabilities()
 // actions.invoke: capabilities.actions.invoke('newConversation', { tags: ['order'], fields: [{ id: 'field_id', value: 'val' }] })
 \`\`\`
 
-### Special handling (events + identity.extend):
+### Special handling (events + identity.extend + messaging.send):
 
 #### 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:
+#### For messaging.send \u2014 ALWAYS use the \`useMessaging\` hook:
+\`useMessaging\` returns a \`[send, { enabled, loading, error }]\` tuple. The \`send\` function is the imperative call wrapped with React state + typed errors. ALWAYS use the hook \u2014 do NOT call \`capabilities.messaging.send(...)\` directly from \`useCapabilities()\`. The hook is the canonical pattern: state management (\`enabled\`/\`loading\`) + typed errors (\`error\`) + correct payload shape (\`{ kind, body }\` with the \`kind\` discriminator). Wire send buttons to \`disabled={!enabled || loading}\` \u2014 the \`enabled\` flag pre-empts the silent \`no_conversation\` case without declaring \`context:read\`. See the snippet below for the full error-handling surface (actionable codes vs. host-handled codes).
+
+#### 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\`.
 
@@ -4424,6 +4428,11 @@ ${HOOK_SNIPPETS["events:messaging"]}
 ${HOOK_SNIPPETS["events:activity"]}
 \`\`\`
 
+\`\`\`tsx
+// messaging.send \u2014 use useMessaging hook (returns [send, { enabled, loading, error }] tuple)
+${HOOK_SNIPPETS["messaging.send"]}
+\`\`\`
+
 \`\`\`tsx
 // identity.extend \u2014 login-time useExtendIdentity hook OR post-login imperative capabilities.identity.extend
 ${CAPABILITY_SNIPPETS["identity.extend"]}
@@ -4435,6 +4444,7 @@ ${CAPABILITY_SNIPPETS["identity.extend"]}
 - For data/context/actions: confirm accessed via \`useCapabilities()\` hook
 - For events: confirm using \`useIdentityEvent\`, \`useMessagingEvent\`, or \`useActivityEvent\` hooks
 - For identity.extend: confirm using \`useExtendIdentity\` hook (login-time) and/or \`capabilities.identity.extend(patch)\` (imperative post-login)
+- For messaging.send: confirm using \`useMessaging\` hook
 `;
 };
 
@@ -5383,16 +5393,12 @@ export function Content() {
     </Surface>
   )
 }`,
-  "messaging.send": `import { useMessaging, useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+  "messaging.send": `import { useMessaging, Surface, ui } from '@stackable-labs/sdk-extension-react'
 
 // Requires 'messaging:send' permission. send() throws on actionable errors
 // (state.error holds the typed code); resolves to null on host-handled cases.
 export function Content() {
-  const { messaging } = useContextData()
-  const [send, { loading, error }] = useMessaging()
-  // Proactive gate: skip the call when there's no conversation \u2014 avoids the
-  // host-handled no_conversation log + null return.
-  const canSend = !!messaging?.conversationId
+  const [send, { enabled, loading, error }] = useMessaging()
 
   const onSayHello = async () => {
     try {
@@ -5412,7 +5418,7 @@ export function Content() {
   return (
     <Surface id="slot.content">
       <ui.Stack direction="column" gap="2" className="p-3">
-        <ui.Button onClick={onSayHello} disabled={loading || !canSend}>Say hello</ui.Button>
+        <ui.Button onClick={onSayHello} disabled={!enabled || loading}>Say hello</ui.Button>
         {(error === 'rate_limited') && <ui.Alert variant="warning">Slow down \u2014 sent too many.</ui.Alert>}
         {(error === 'upstream_error') && <ui.Alert variant="error">Send failed \u2014 please try again.</ui.Alert>}
         {(error === 'invalid_message') && <ui.Alert variant="error">Send failed \u2014 message format invalid.</ui.Alert>}
@@ -5511,12 +5517,11 @@ await capabilities.identity.extend({ verified: true })
 useIdentityEvent('refresh', (event) => {
   console.log('verified =>', event.data.state.user?.metadata?.verified)
 })`,
-  "messaging.send": `// Send a message into the active conversation bound to this Instance.
-// Requires the 'messaging:send' permission. The author label rendered above
-// outbound messages is set per-Instance by the admin (Instance settings
-// messagingDisplayName); falls back to extension.manifest.name when blank.
-const [send, { loading, error }] = useMessaging()
-const result = await send({ kind: 'text', body: 'Hello from the extension' })
+  "messaging.send": `import { useMessaging } from '@stackable-labs/sdk-extension-react'
+
+// manifest.json: { "permissions": ["messaging:send"] }
+const [send, { enabled, loading, error }] = useMessaging()
+await send({ kind: 'text', body: 'Hello from the extension' })
 
 // Actionable errors throw + populate state.error: 'invalid_message' (bad payload),
 // 'rate_limited' (slow down), 'upstream_error' (transient \u2014 retry). Branch in
@@ -5524,7 +5529,8 @@ const result = await send({ kind: 'text', body: 'Hello from the extension' })
 // Host-handled cases ('no_conversation' / 'reauth_required' / 'forbidden')
 // resolve to null without throwing; the SDK logs a breadcrumb and the host
 // surfaces remediation to admins (e.g. dashboard Reconnect UI). Extensions
-// can pre-empt 'no_conversation' via useContextData().messaging?.conversationId.
+// can pre-empt 'no_conversation' via the 'enabled' flag from useMessaging()
+// (permission-free) \u2014 wire to button disabled={!enabled || loading}.
 if (error === 'rate_limited') { /* show "slow down" UI */ }`
 };
 var EVENT_SNIPPETS2 = {
@@ -5901,7 +5907,7 @@ ${errors.map((e) => `- ${e}`).join("\n")}`);
         usedPermissions.add(permission);
       }
     }
-    for (const [hook, permission] of Object.entries(EVENT_HOOK_PERMISSION_MAP)) {
+    for (const [hook, permission] of Object.entries(HOOK_PERMISSION_MAP)) {
       if (allSource.includes(hook)) {
         usedPermissions.add(permission);
       }

package/dist/server.js

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, MESSAGING_ACTION_EXAMPLES, PERMISSIONS, CAPABILITY_PERMISSION_MAP, EVENT_HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_CATEGORIES, UI_TAG_ATTRIBUTES, tagToComponentName, MESSAGING_SEND_EXAMPLES } from '@stackable-labs/sdk-extension-contracts';
+import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, MESSAGING_ACTION_EXAMPLES, PERMISSIONS, CAPABILITY_PERMISSION_MAP, HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_CATEGORIES, UI_TAG_ATTRIBUTES, tagToComponentName, EVENT_HOOK_PERMISSION_MAP, MESSAGING_SEND_EXAMPLES } from '@stackable-labs/sdk-extension-contracts';
 import { validatePatternFormat } from '@stackable-labs/lib-contracts';
 import { readFile } from 'fs/promises';
 import { join } from 'path';
@@ -341,6 +341,11 @@ var CORE_CONTENT = `# Extension SDK \u2014 Editorial Notes
 - Always check the \`loading\` flag before using context values
 - Context is only available when the host provides it (e.g., when viewing a ticket)
 
+### \`messaging.send\` resolves to null without throwing
+- The host silently handles \`no_conversation\` / \`reauth_required\` / \`forbidden\` \u2014 \`send()\` returns null and \`error\` stays unset on these codes
+- These are operational/admin concerns (no active conversation, instance disconnected from messaging, permission revoked) \u2014 surfaced to admins via dashboard remediation UI, not user-actionable from the extension
+- Actionable codes (\`invalid_message\`, \`rate_limited\`, \`upstream_error\`) DO populate \`error\` and throw \u2014 handle in UI
+
 ## Best Practices
 
 ### Performance
@@ -499,7 +504,12 @@ useExtendIdentity((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
-}))`
+}))`,
+  "messaging.send": `import { useMessaging } from '@stackable-labs/sdk-extension-react'
+
+// manifest.json: { "permissions": ["messaging:send"] }
+const [send, { enabled, loading, error }] = useMessaging()
+await send({ kind: 'text', body: 'Hello from the extension' })`
 };
 var HOOK_SNIPPETS_MEMOIZED = {
   "events:messaging": `import { useCallback } from 'react'
@@ -829,7 +839,7 @@ The publisher-side bundle scan validates your declaration at submission time:
 
 Post a message into the **active conversation** bound to the current Instance. The host attributes each message to the extension via the per-Instance author label set by the admin (see "Author label" below). Two complementary APIs:
 
-1. **\`useMessaging()\`** \u2014 React hook returning tuple \`[send, { loading, error, data }]\` \u2014 lets callers rename \`send\` per-instance when used multiple times in one component. Preferred for UI components; narrows the error surface to actionable codes only.
+1. **\`useMessaging()\`** \u2014 React hook returning tuple \`[send, { enabled, loading, error, data }]\` \u2014 lets callers rename \`send\` per-instance when used multiple times in one component. Preferred for UI components; narrows the error surface to actionable codes only. Use \`enabled\` to pre-empt the silent \`no_conversation\` case **without** declaring \`context:read\`.
 2. **\`messagingSendCapability(payload)\`** / **\`capabilities.messaging.send(payload)\`** \u2014 imperative; useful outside React render. Exposes the full wire-level error taxonomy.
 
 ### Manifest contract
@@ -872,14 +882,9 @@ Four kinds:
 ### Hook usage
 
 \`\`\`tsx
-import { useMessaging, useContextData } from '@stackable-labs/sdk-extension-react'
+import { useMessaging } from '@stackable-labs/sdk-extension-react'
 
-const { messaging } = useContextData()
-const [send, { loading, error }] = useMessaging()
-
-// Proactive gate: skip the call when there's no conversation \u2014 avoids the
-// host-handled no_conversation log + null return.
-const canSend = !!messaging?.conversationId
+const [send, { enabled, loading, error }] = useMessaging()
 
 const onApprove = async () => {
   try {
@@ -893,11 +898,15 @@ const onApprove = async () => {
   }
 }
 
-if (error === 'rate_limited') {
-  // Render a "slow down" notice
-}
+return (
+  <button disabled={!enabled || loading} onClick={onApprove}>
+    {error === 'rate_limited' ? 'Slow down\u2026' : 'Approve'}
+  </button>
+)
 \`\`\`
 
+The \`enabled\` flag is a permission-free, host-pushed signal \u2014 \`true\` whenever an active conversation exists. Wiring buttons to \`disabled={!enabled || loading}\` pre-empts the silent \`no_conversation\` case without forcing the extension to declare \`context:read\`. If the extension already has \`context:read\` for other reasons, \`useContextData().messaging?.conversationId\` is an equivalent gate.
+
 ### Imperative usage
 
 \`\`\`tsx
@@ -922,7 +931,7 @@ The wire taxonomy has 6 codes. The hook (\`useMessaging\`) narrows them into two
 
 | Code | What the framework does |
 | --- | --- |
-| \`no_conversation\` | \`console.info\` \u2014 pre-empt via \`useContextData().messaging?.conversationId\` |
+| \`no_conversation\` | \`console.info\` \u2014 pre-empt via the \`enabled\` flag from \`useMessaging()\` (no permission needed) |
 | \`reauth_required\` | \`console.warn\` \u2014 admin sees a "Reconnect" CTA in the dashboard (server flips \`messagingDisconnected: true\`) |
 | \`forbidden\` | \`console.warn\` \u2014 should not reach in production with correct manifest |
 
@@ -940,7 +949,7 @@ Three gates fire in series, surfacing the same \`forbidden\` error if any blocks
 
 \`reply\` and \`postback\` action clicks fire on extensions with the \`events:messaging\` permission via \`useMessagingEvent\` \u2014 see the \`events:messaging\` section above.
 
-> **Note:** the postback \`payload\` field is currently not surfaced by the Web Widget (only the button text \`actionName\`). Until that gap is closed, design action labels to be self-describing or pair sends with a follow-up \`data.query\` lookup.
+> **Note:** the postback \`payload\` field is currently not surfaced by the Web Widget (only the button text \`actionName\`). Until that gap is closed, design action labels to be self-describing or pair sends with a follow-up \`data.fetch\` lookup.
 `;
 };
 
@@ -1303,16 +1312,12 @@ export function Content(): React.ReactElement {
     </Surface>
   )
 }`,
-  "messaging.send": `import { useMessaging, useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+  "messaging.send": `import { useMessaging, Surface, ui } from '@stackable-labs/sdk-extension-react'
 
 // Requires 'messaging:send' permission. send() throws on actionable errors
 // (state.error holds the typed code); resolves to null on host-handled cases.
 export function Content(): React.ReactElement {
-  const { messaging } = useContextData()
-  const [send, { loading, error }] = useMessaging()
-  // Proactive gate: skip the call when there's no conversation \u2014 avoids the
-  // host-handled no_conversation log + null return.
-  const canSend = !!messaging?.conversationId
+  const [send, { enabled, loading, error }] = useMessaging()
 
   const onSayHello = async () => {
     try {
@@ -1332,7 +1337,7 @@ export function Content(): React.ReactElement {
   return (
     <Surface id="slot.content">
       <ui.Stack direction="column" gap="2" className="p-3">
-        <ui.Button onClick={onSayHello} disabled={loading || !canSend}>Say hello</ui.Button>
+        <ui.Button onClick={onSayHello} disabled={!enabled || loading}>Say hello</ui.Button>
         {(error === 'rate_limited') && <ui.Alert variant="warning">Slow down \u2014 sent too many.</ui.Alert>}
         {(error === 'upstream_error') && <ui.Alert variant="error">Send failed \u2014 please try again.</ui.Alert>}
         {(error === 'invalid_message') && <ui.Alert variant="error">Send failed \u2014 message format invalid.</ui.Alert>}
@@ -1368,10 +1373,6 @@ Bootstrap the extension runtime. Call once in \`src/index.tsx\`.
 ${EXAMPLE_SNIPPETS.bootstrap}
 \`\`\`
 
-## Surface component
-Wraps content for a target slot. The \`id\` must match a target in \`manifest.json\`.
-- \`<Surface id="slot.content">...</Surface>\`
-
 ## useCapabilities()
 Returns the capabilities object for calling host-mediated APIs.
 \`\`\`tsx
@@ -1382,7 +1383,7 @@ const capabilities = useCapabilities()
 // capabilities.actions.toast(payload)
 // capabilities.actions.invoke(action, payload?) \u2014 actions: newConversation, setConversationTags, setConversationFields, open, close, show, hide
 // 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.
-// capabilities.messaging.send(payload) \u2014 post a message into the active conversation bound to this Instance. Requires messaging:send permission. Author label is admin-set per-Instance (instance.config.settings.messagingDisplayName) with extension.manifest.name fallback. For React state ([send, { loading, error, data }]), prefer the useMessaging hook.
+// capabilities.messaging.send(payload) \u2014 post a message into the active conversation bound to this Instance. Prefer the useMessaging hook instead. Requires messaging:send permission. Author label is admin-set per-Instance (instance.config.settings.messagingDisplayName) with extension.manifest.name fallback.
 \`\`\`
 
 ## useStore(store, selector?)
@@ -1391,6 +1392,17 @@ Subscribe to a shared store. Re-renders when the selected state changes.
 const viewState = useStore(appStore, (s) => s.viewState)
 \`\`\`
 
+## createStore(initialState)
+Create a shared store for cross-surface state coordination.
+\`\`\`tsx
+const appStore = createStore<AppState>({ viewState: { type: 'menu' } })
+\`\`\`
+
+**Store\\<T\\> interface**
+- \`get(): T\` \u2014 read current state
+- \`set(partial: Partial<T>): void\` \u2014 merge partial state update
+- \`subscribe(listener: (state: T) => void): () => void\` \u2014 subscribe, returns unsubscribe fn
+
 ## useContextData()
 Reads host-provided context including extension settings. Returns \`{ loading, customerId, customerEmail, messaging, settings, ... }\`. \`messaging.conversationId\` is the active Messaging conversation ID (or \`null\` until one exists).
 \`\`\`tsx
@@ -1417,26 +1429,48 @@ Returns extension-level context.
 const { extensionId } = useExtension()
 \`\`\`
 
-## createStore(initialState)
-Create a shared store for cross-surface state coordination.
+## useEvent(eventType, handler)
+Generic cross-domain event hook (should not be used unless absolutely required). Subscribe to any event using fully-qualified event types.
+- \`eventType: EventType\` \u2014 fully-qualified (e.g., \`'activity:product_view'\`, \`'identity:login'\`, \`'messaging:postback'\`)
+- Domain wildcard (e.g., \`'activity'\`) receives all events in that domain
+- \`handler: (event: BaseEvent) => void\`
+
 \`\`\`tsx
-const appStore = createStore<AppState>({ viewState: { type: 'menu' } })
+useEvent('activity', (event) => {
+  console.log('Activity:', event.data)
+})
 \`\`\`
 
-### Store\\<T\\> interface
-- \`get(): T\` \u2014 read current state
-- \`set(partial: Partial<T>): void\` \u2014 merge partial state update
-- \`subscribe(listener: (state: T) => void): () => void\` \u2014 subscribe, returns unsubscribe fn
+## useMessaging()
+Send messages into the active conversation bound to this Instance. Wraps the \`messaging.send\` capability with React state, tracking \`enabled\` / \`loading\` / \`error\` / \`data\`. Returns a tuple \`[send, state]\` so callers can rename \`send\` when the hook is used multiple times in one component. Requires \`messaging:send\` permission. The author label rendered above outbound messages is set per-Instance by the admin (Instance settings \`messagingDisplayName\`); falls back to \`extension.manifest.name\` when blank.
 
-## useIdentityEvent(eventType, handler)
-Subscribe to identity events pushed from the host via the framework. Requires \`events:identity\` permission and matching entries in manifest \`events\` array.
-- \`eventType: ${identityEventTypes}\`
-- \`handler: (event: IdentityEvent) => void\`
-- \`IdentityEvent: { eventName: IdentityEventType, data: { state: IdentityState, timestamp: string } }\`
-- \`IdentityState: { authenticated: boolean, user: UserIdentity | null, expiresAt?: string }\`
+- **Returns:** \`readonly [send, { enabled, loading, error, data }]\`
+- **\`send(payload: SendMessagePayload): Promise<SendMessageResponse | null>\`** \u2014 returns the response on success; throws on **actionable** errors; resolves to \`null\` on host-handled errors (SDK logs a breadcrumb, host surfaces remediation)
+- **\`enabled: boolean\`** \u2014 advisory; \`true\` when an active conversation exists. Permission-free (no \`context:read\` needed). Wire to button \`disabled\` to pre-empt the silent \`no_conversation\` case. Starts \`false\`; flips reactively via host-pushed availability events.
+- **\`loading: boolean\`** \u2014 true while a call is in flight (matches \`useContextData\`'s \`loading\` for SDK-wide consistency)
+- **\`data: SendMessageResponse | null\`** \u2014 \`{ messageId, receivedAt }\` from last successful send
+- **\`error: SendMessageActionableErrorCode | null\`** \u2014 one of \`invalid_message\` / \`rate_limited\` / \`upstream_error\` after a failed send. Host-handled codes (\`no_conversation\` / \`reauth_required\` / \`forbidden\`) never surface here.
+
+Payload is discriminated by \`kind\`: \`'text'\` / \`'image'\` / \`'file'\` / \`'carousel'\`. See the \`messaging.send\` capability section for the full payload table + action types.
 
 \`\`\`tsx
-${stripImports(HOOK_SNIPPETS["events:identity"])}
+import { useMessaging } from '@stackable-labs/sdk-extension-react'
+
+const [send, { enabled, loading, error }] = useMessaging()
+
+const onApprove = async () => {
+  try {
+    await send({ kind: 'text', body: 'Approved \u2713' })
+  } catch {
+    // error holds the typed SendMessageActionableErrorCode
+  }
+}
+
+return (
+  <button disabled={!enabled || loading} onClick={onApprove}>
+    Approve
+  </button>
+)
 \`\`\`
 
 ## useMessagingEvent(eventType, handler)
@@ -1467,16 +1501,15 @@ Subscribe to activity events pushed from the host via the framework. Requires \`
 ${stripImports(HOOK_SNIPPETS["events:activity"])}
 \`\`\`
 
-## useEvent(eventType, handler)
-Generic cross-domain event hook (should not be used unless absolutely required). Subscribe to any event using fully-qualified event types.
-- \`eventType: EventType\` \u2014 fully-qualified (e.g., \`'activity:product_view'\`, \`'identity:login'\`, \`'messaging:postback'\`)
-- Domain wildcard (e.g., \`'activity'\`) receives all events in that domain
-- \`handler: (event: BaseEvent) => void\`
+## useIdentityEvent(eventType, handler)
+Subscribe to identity events pushed from the host via the framework. Requires \`events:identity\` permission and matching entries in manifest \`events\` array.
+- \`eventType: ${identityEventTypes}\`
+- \`handler: (event: IdentityEvent) => void\`
+- \`IdentityEvent: { eventName: IdentityEventType, data: { state: IdentityState, timestamp: string } }\`
+- \`IdentityState: { authenticated: boolean, user: UserIdentity | null, expiresAt?: string }\`
 
 \`\`\`tsx
-useEvent('activity', (event) => {
-  console.log('Activity:', event.data)
-})
+${stripImports(HOOK_SNIPPETS["events:identity"])}
 \`\`\`
 
 ## useExtendIdentity(handler)
@@ -1493,41 +1526,12 @@ With \`useCallback\` (for memoized handlers):
 ${HOOK_SNIPPETS_MEMOIZED["identity.extend"]}
 \`\`\`
 
-## Identity via context.read()
+**Identity via context.read()**
 Identity state is available in the \`context.read()\` response as an \`identity\` field. Requires \`context:read\` permission (no separate identity permission needed).
 \`\`\`tsx
 const context = await capabilities.context.read()
 // context.identity \u2014 { authenticated, user, expiresAt? }
 \`\`\`
-
-## useMessaging()
-Send messages into the active conversation bound to this Instance. Wraps the \`messaging.send\` capability with React state, tracking \`loading\` / \`error\` / \`data\`. Returns a tuple \`[send, state]\` so callers can rename \`send\` when the hook is used multiple times in one component. Requires \`messaging:send\` permission. The author label rendered above outbound messages is set per-Instance by the admin (Instance settings \`messagingDisplayName\`); falls back to \`extension.manifest.name\` when blank.
-
-- **Returns:** \`readonly [send, { loading, error, data }]\`
-- **\`send(payload: SendMessagePayload): Promise<SendMessageResponse | null>\`** \u2014 returns the response on success; throws on **actionable** errors; resolves to \`null\` on host-handled errors (SDK logs a breadcrumb, host surfaces remediation)
-- **\`loading: boolean\`** \u2014 true while a call is in flight (matches \`useContextData\`'s \`loading\` for SDK-wide consistency)
-- **\`data: SendMessageResponse | null\`** \u2014 \`{ messageId, receivedAt }\` from last successful send
-- **\`error: SendMessageActionableErrorCode | null\`** \u2014 one of \`invalid_message\` / \`rate_limited\` / \`upstream_error\` after a failed send. Host-handled codes (\`no_conversation\` / \`reauth_required\` / \`forbidden\`) never surface here.
-
-Payload is discriminated by \`kind\`: \`'text'\` / \`'image'\` / \`'file'\` / \`'carousel'\`. See the \`messaging.send\` capability section for the full payload table + action types.
-
-\`\`\`tsx
-import { useMessaging, useContextData } from '@stackable-labs/sdk-extension-react'
-
-const { messaging } = useContextData()
-const [send, { loading, error }] = useMessaging()
-
-// Proactive gate: skip the call when there's no conversation
-const canSend = !!messaging?.conversationId
-
-const onApprove = async () => {
-  try {
-    await send({ kind: 'text', body: 'Approved \u2713' })
-  } catch {
-    // error holds the typed SendMessageActionableErrorCode
-  }
-}
-\`\`\`
 `;
 };
 
@@ -4153,7 +4157,7 @@ alongside existing surfaces.
 Add the target to the \`targets\` array in \`packages/extension/public/manifest.json\`.
 Also add any required permissions based on the target-permission mapping:
 - \`slot.header\` \u2192 \`context:read\`
-- \`slot.content\` \u2192 \`context:read\`, \`data:query\`, \`actions:toast\`, \`actions:invoke\`
+- \`slot.content\` \u2192 \`context:read\`, \`data:query\`, \`actions:toast\`, \`actions:invoke\`, \`messaging:send\`
 - \`slot.footer\` \u2192 (none)
 - \`slot.footer-links\` \u2192 (none)
 
@@ -4230,13 +4234,7 @@ useIdentityEvent('refresh', (event) => {
   console.log('verified =>', event.data.state.user?.metadata?.verified)
 })
 `,
-  "messaging.send": `
-// Send a message into the active conversation bound to this Instance.
-// Requires the 'messaging:send' permission. The author label rendered above
-// outbound messages is set per-Instance by the admin (Instance settings
-// messagingDisplayName); falls back to extension.manifest.name when blank.
-const [send, { loading, error }] = useMessaging()
-const result = await send({ kind: 'text', body: 'Hello from the extension' })
+  "messaging.send": `${HOOK_SNIPPETS["messaging.send"]}
 
 // Actionable errors throw + populate state.error: 'invalid_message' (bad payload),
 // 'rate_limited' (slow down), 'upstream_error' (transient \u2014 retry). Branch in
@@ -4244,7 +4242,8 @@ const result = await send({ kind: 'text', body: 'Hello from the extension' })
 // Host-handled cases ('no_conversation' / 'reauth_required' / 'forbidden')
 // resolve to null without throwing; the SDK logs a breadcrumb and the host
 // surfaces remediation to admins (e.g. dashboard Reconnect UI). Extensions
-// can pre-empt 'no_conversation' via useContextData().messaging?.conversationId.
+// can pre-empt 'no_conversation' via the 'enabled' flag from useMessaging()
+// (permission-free) \u2014 wire to button disabled={!enabled || loading}.
 if (error === 'rate_limited') { /* show "slow down" UI */ }
 `
 };
@@ -4323,7 +4322,7 @@ export function Content(): React.ReactElement {
 // ../../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, identity.extend, 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, messaging.send, identity.extend, events:identity, events:messaging, events:activity) in this extension",
     targets: ["*"]
   });
   return `${fm}
@@ -4339,6 +4338,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)
+- \`messaging.send\` \u2014 send messages into the active conversation bound to this Instance (text/image/file/carousel + reply/link/postback actions)
 - \`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)
@@ -4351,6 +4351,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"\`
+- \`messaging.send\` \u2192 \`"messaging:send"\`
 - \`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"]\`)
@@ -4393,12 +4394,15 @@ const capabilities = useCapabilities()
 // actions.invoke: capabilities.actions.invoke('newConversation', { tags: ['order'], fields: [{ id: 'field_id', value: 'val' }] })
 \`\`\`
 
-### Special handling (events + identity.extend):
+### Special handling (events + identity.extend + messaging.send):
 
 #### 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:
+#### For messaging.send \u2014 ALWAYS use the \`useMessaging\` hook:
+\`useMessaging\` returns a \`[send, { enabled, loading, error }]\` tuple. The \`send\` function is the imperative call wrapped with React state + typed errors. ALWAYS use the hook \u2014 do NOT call \`capabilities.messaging.send(...)\` directly from \`useCapabilities()\`. The hook is the canonical pattern: state management (\`enabled\`/\`loading\`) + typed errors (\`error\`) + correct payload shape (\`{ kind, body }\` with the \`kind\` discriminator). Wire send buttons to \`disabled={!enabled || loading}\` \u2014 the \`enabled\` flag pre-empts the silent \`no_conversation\` case without declaring \`context:read\`. See the snippet below for the full error-handling surface (actionable codes vs. host-handled codes).
+
+#### 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\`.
 
@@ -4417,6 +4421,11 @@ ${HOOK_SNIPPETS["events:messaging"]}
 ${HOOK_SNIPPETS["events:activity"]}
 \`\`\`
 
+\`\`\`tsx
+// messaging.send \u2014 use useMessaging hook (returns [send, { enabled, loading, error }] tuple)
+${HOOK_SNIPPETS["messaging.send"]}
+\`\`\`
+
 \`\`\`tsx
 // identity.extend \u2014 login-time useExtendIdentity hook OR post-login imperative capabilities.identity.extend
 ${CAPABILITY_SNIPPETS["identity.extend"]}
@@ -4428,6 +4437,7 @@ ${CAPABILITY_SNIPPETS["identity.extend"]}
 - For data/context/actions: confirm accessed via \`useCapabilities()\` hook
 - For events: confirm using \`useIdentityEvent\`, \`useMessagingEvent\`, or \`useActivityEvent\` hooks
 - For identity.extend: confirm using \`useExtendIdentity\` hook (login-time) and/or \`capabilities.identity.extend(patch)\` (imperative post-login)
+- For messaging.send: confirm using \`useMessaging\` hook
 `;
 };
 
@@ -5376,16 +5386,12 @@ export function Content() {
     </Surface>
   )
 }`,
-  "messaging.send": `import { useMessaging, useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+  "messaging.send": `import { useMessaging, Surface, ui } from '@stackable-labs/sdk-extension-react'
 
 // Requires 'messaging:send' permission. send() throws on actionable errors
 // (state.error holds the typed code); resolves to null on host-handled cases.
 export function Content() {
-  const { messaging } = useContextData()
-  const [send, { loading, error }] = useMessaging()
-  // Proactive gate: skip the call when there's no conversation \u2014 avoids the
-  // host-handled no_conversation log + null return.
-  const canSend = !!messaging?.conversationId
+  const [send, { enabled, loading, error }] = useMessaging()
 
   const onSayHello = async () => {
     try {
@@ -5405,7 +5411,7 @@ export function Content() {
   return (
     <Surface id="slot.content">
       <ui.Stack direction="column" gap="2" className="p-3">
-        <ui.Button onClick={onSayHello} disabled={loading || !canSend}>Say hello</ui.Button>
+        <ui.Button onClick={onSayHello} disabled={!enabled || loading}>Say hello</ui.Button>
         {(error === 'rate_limited') && <ui.Alert variant="warning">Slow down \u2014 sent too many.</ui.Alert>}
         {(error === 'upstream_error') && <ui.Alert variant="error">Send failed \u2014 please try again.</ui.Alert>}
         {(error === 'invalid_message') && <ui.Alert variant="error">Send failed \u2014 message format invalid.</ui.Alert>}
@@ -5504,12 +5510,11 @@ await capabilities.identity.extend({ verified: true })
 useIdentityEvent('refresh', (event) => {
   console.log('verified =>', event.data.state.user?.metadata?.verified)
 })`,
-  "messaging.send": `// Send a message into the active conversation bound to this Instance.
-// Requires the 'messaging:send' permission. The author label rendered above
-// outbound messages is set per-Instance by the admin (Instance settings
-// messagingDisplayName); falls back to extension.manifest.name when blank.
-const [send, { loading, error }] = useMessaging()
-const result = await send({ kind: 'text', body: 'Hello from the extension' })
+  "messaging.send": `import { useMessaging } from '@stackable-labs/sdk-extension-react'
+
+// manifest.json: { "permissions": ["messaging:send"] }
+const [send, { enabled, loading, error }] = useMessaging()
+await send({ kind: 'text', body: 'Hello from the extension' })
 
 // Actionable errors throw + populate state.error: 'invalid_message' (bad payload),
 // 'rate_limited' (slow down), 'upstream_error' (transient \u2014 retry). Branch in
@@ -5517,7 +5522,8 @@ const result = await send({ kind: 'text', body: 'Hello from the extension' })
 // Host-handled cases ('no_conversation' / 'reauth_required' / 'forbidden')
 // resolve to null without throwing; the SDK logs a breadcrumb and the host
 // surfaces remediation to admins (e.g. dashboard Reconnect UI). Extensions
-// can pre-empt 'no_conversation' via useContextData().messaging?.conversationId.
+// can pre-empt 'no_conversation' via the 'enabled' flag from useMessaging()
+// (permission-free) \u2014 wire to button disabled={!enabled || loading}.
 if (error === 'rate_limited') { /* show "slow down" UI */ }`
 };
 var EVENT_SNIPPETS2 = {
@@ -5850,7 +5856,7 @@ ${errors.map((e) => `- ${e}`).join("\n")}`);
         usedPermissions.add(permission);
       }
     }
-    for (const [hook, permission] of Object.entries(EVENT_HOOK_PERMISSION_MAP)) {
+    for (const [hook, permission] of Object.entries(HOOK_PERMISSION_MAP)) {
       if (allSource.includes(hook)) {
         usedPermissions.add(permission);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackable-labs/mcp-app-extension",
-  "version": "1.30.0",
+  "version": "2.0.1",
   "type": "module",
   "bin": {
     "mcp-app-extension": "./dist/index.js"