@stackable-labs/mcp-app-extension 0.2.0 → 0.3.0

package/dist/server.js

@@ -0,0 +1,3985 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { IDENTITY_EVENTS, ACTIVITY_EVENTS, SURFACE_TARGETS, PERMISSIONS, CAPABILITY_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_ATTRIBUTES, tagToComponentName } from '@stackable-labs/sdk-extension-contracts';
+import { z } from 'zod';
+
+// src/server.ts
+
+// ../../sdk/extension/ai-docs/src/generated/template-content.ts
+var PATTERN_SECTIONS = [
+  {
+    path: "index.tsx",
+    title: "Entry Point",
+    code: `import { createExtension } from '@stackable-labs/sdk-extension-react'
+import { Header } from './surfaces/Header'
+import { Content } from './surfaces/Content'
+import { Footer } from './surfaces/Footer'
+
+const Extension = () => (
+  <>
+    <Header />
+    <Content />
+    <Footer />
+  </>
+)
+
+createExtension(() => <Extension />, { extensionId: '__EXTENSION_ID__' })`
+  },
+  {
+    path: "store.ts",
+    title: "Store-Based Navigation",
+    code: `import { createStore } from '@stackable-labs/sdk-extension-react'
+
+export type ViewState = { type: 'menu' }
+
+export interface AppState {
+  viewState: ViewState
+}
+
+export const appStore = createStore<AppState>({
+  viewState: { type: 'menu' },
+})`
+  },
+  {
+    path: "surfaces/Content.tsx",
+    title: "Content Surface with Loading State",
+    code: `import { ui, useStore, useContextData, Surface } from '@stackable-labs/sdk-extension-react'
+import { appStore } from '../store'
+
+export function Content() {
+  const viewState = useStore(appStore, (s) => s.viewState)
+  const { loading } = useContextData()
+
+  if (loading) {
+    return (
+      <Surface id="slot.content">
+        <ui.Stack direction="column" gap="2" className="animate-pulse">
+          <ui.Card className="h-24" />
+          <ui.Card className="h-32" />
+        </ui.Stack>
+      </Surface>
+    )
+  }
+
+  return (
+    <Surface id="slot.content">
+      {viewState.type === 'menu' && (
+        <ui.Menu>
+          {/* Add ui.MenuItem entries here */}
+        </ui.Menu>
+      )}
+    </Surface>
+  )
+}`
+  },
+  {
+    path: "surfaces/Footer.tsx",
+    title: "Surface Composition",
+    code: `import { ui, Surface } from '@stackable-labs/sdk-extension-react'
+
+export function Footer() {
+  return (
+    <>
+      <Surface id="slot.footer">
+        <ui.Text className="text-xs">Powered by My Extension</ui.Text>
+      </Surface>
+      <Surface id="slot.footer-links">
+        <ui.FooterLink href="https://example.com">My Extension</ui.FooterLink>
+      </Surface>
+    </>
+  )
+}`
+  },
+  {
+    path: "surfaces/Header.tsx",
+    title: "Simple Surface",
+    code: `import { ui, Surface } from '@stackable-labs/sdk-extension-react'
+
+export function Header() {
+  return (
+    <Surface id="slot.header">
+      <ui.Text>Header content goes here</ui.Text>
+    </Surface>
+  )
+}`
+  },
+  {
+    path: "lib/api.ts",
+    title: "API Wrapper (data.query + data.fetch)",
+    code: `/**
+ * API wrapper patterns \u2014 choose one based on your integration model.
+ *
+ * data.query  \u2192 host-mediated: the host handles the API call, extension sends
+ *               an action name + params, host returns data.
+ *               Permission: "data:query"
+ *
+ * data.fetch  \u2192 direct HTTP: the extension calls external APIs through the
+ *               platform proxy. Domains must be in allowedDomains in manifest.
+ *               Permission: "data:fetch"
+ *
+ * Usage in a surface:
+ *   const capabilities = useCapabilities()
+ *   const api = createApi(capabilities.data.query)
+ *   // or: const api = createFetchApi(capabilities.data.fetch)
+ */
+
+import type { ApiRequest, FetchRequestInit, FetchResponse } from '@stackable-labs/sdk-extension-contracts'
+
+type QueryFn = <T = unknown>(payload: ApiRequest) => Promise<T>
+type FetchFn = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>
+
+// \u2500\u2500 data.query wrapper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+export function createApi(query: QueryFn) {
+  return {
+    async getItems(): Promise<unknown[]> {
+      return query<unknown[]>({ action: 'getItems' })
+    },
+
+    async getItem(itemId: string): Promise<unknown> {
+      return query<unknown>({ action: 'getItem', itemId })
+    },
+  }
+}
+
+// \u2500\u2500 data.fetch wrapper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+const API_BASE_URL = import.meta.env.VITE_API_BASE_URL as string
+
+export function createFetchApi(fetch: FetchFn) {
+  return {
+    async getItems(): Promise<unknown[]> {
+      const result = await fetch(\`\${API_BASE_URL}/items\`, { method: 'GET' })
+      if (!result.ok) throw new Error(\`getItems failed: \${result.status}\`)
+      return result.data as unknown[]
+    },
+
+    async getItem(itemId: string): Promise<unknown> {
+      const result = await fetch(\`\${API_BASE_URL}/items/\${itemId}\`, { method: 'GET' })
+      if (!result.ok) throw new Error(\`getItem failed: \${result.status}\`)
+      return result.data as unknown
+    },
+  }
+}`
+  }
+];
+var RECIPE_SECTIONS = [
+  {
+    path: "store.ts",
+    title: "Current Store & View State",
+    code: `import { createStore } from '@stackable-labs/sdk-extension-react'
+
+export type ViewState = { type: 'menu' }
+
+export interface AppState {
+  viewState: ViewState
+}
+
+export const appStore = createStore<AppState>({
+  viewState: { type: 'menu' },
+})`
+  },
+  {
+    path: "surfaces/Content.tsx",
+    title: "Current Content Surface",
+    code: `import { ui, useStore, useContextData, Surface } from '@stackable-labs/sdk-extension-react'
+import { appStore } from '../store'
+
+export function Content() {
+  const viewState = useStore(appStore, (s) => s.viewState)
+  const { loading } = useContextData()
+
+  if (loading) {
+    return (
+      <Surface id="slot.content">
+        <ui.Stack direction="column" gap="2" className="animate-pulse">
+          <ui.Card className="h-24" />
+          <ui.Card className="h-32" />
+        </ui.Stack>
+      </Surface>
+    )
+  }
+
+  return (
+    <Surface id="slot.content">
+      {viewState.type === 'menu' && (
+        <ui.Menu>
+          {/* Add ui.MenuItem entries here */}
+        </ui.Menu>
+      )}
+    </Surface>
+  )
+}`
+  },
+  {
+    path: "lib/api.ts",
+    title: "Current API Wrapper",
+    code: `/**
+ * API wrapper patterns \u2014 choose one based on your integration model.
+ *
+ * data.query  \u2192 host-mediated: the host handles the API call, extension sends
+ *               an action name + params, host returns data.
+ *               Permission: "data:query"
+ *
+ * data.fetch  \u2192 direct HTTP: the extension calls external APIs through the
+ *               platform proxy. Domains must be in allowedDomains in manifest.
+ *               Permission: "data:fetch"
+ *
+ * Usage in a surface:
+ *   const capabilities = useCapabilities()
+ *   const api = createApi(capabilities.data.query)
+ *   // or: const api = createFetchApi(capabilities.data.fetch)
+ */
+
+import type { ApiRequest, FetchRequestInit, FetchResponse } from '@stackable-labs/sdk-extension-contracts'
+
+type QueryFn = <T = unknown>(payload: ApiRequest) => Promise<T>
+type FetchFn = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>
+
+// \u2500\u2500 data.query wrapper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+export function createApi(query: QueryFn) {
+  return {
+    async getItems(): Promise<unknown[]> {
+      return query<unknown[]>({ action: 'getItems' })
+    },
+
+    async getItem(itemId: string): Promise<unknown> {
+      return query<unknown>({ action: 'getItem', itemId })
+    },
+  }
+}
+
+// \u2500\u2500 data.fetch wrapper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+const API_BASE_URL = import.meta.env.VITE_API_BASE_URL as string
+
+export function createFetchApi(fetch: FetchFn) {
+  return {
+    async getItems(): Promise<unknown[]> {
+      const result = await fetch(\`\${API_BASE_URL}/items\`, { method: 'GET' })
+      if (!result.ok) throw new Error(\`getItems failed: \${result.status}\`)
+      return result.data as unknown[]
+    },
+
+    async getItem(itemId: string): Promise<unknown> {
+      const result = await fetch(\`\${API_BASE_URL}/items/\${itemId}\`, { method: 'GET' })
+      if (!result.ok) throw new Error(\`getItem failed: \${result.status}\`)
+      return result.data as unknown
+    },
+  }
+}`
+  }
+];
+var CORE_CONTENT = `# Extension SDK \u2014 Editorial Notes
+
+> This file is merged into the generated AI editor config files.
+> Keep it minimal \u2014 the generation script handles most content automatically.
+
+## Key Requirements
+
+### Fetching Data
+- No direct API calls using standard \`fetch\` allowed (blocked for security)
+- Any external API calls must be made using the \`data.fetch\` capability
+- Domain for any API call needs to be safelisted via \`allowedDomains\` in \`manifest.json\`
+
+## Troubleshooting
+
+### "Permission denied" errors
+- Verify the capability's permission is declared in \`manifest.json\`
+- Check that the permission string matches exactly (e.g., \`data:fetch\`, not \`data.fetch\`)
+
+### data.fetch returns network errors
+- Confirm the domain is in \`allowedDomains\` in \`manifest.json\`
+- Only exact hostnames are allowed \u2014 no wildcards, no paths
+- Check that the URL uses HTTPS
+
+### Surface not rendering
+- Confirm the \`<Surface id="...">\` matches a target in \`manifest.json\`
+- Confirm the surface component is imported and rendered in \`index.tsx\`
+- Check the browser console for errors
+
+### Context data is undefined
+- Ensure \`context:read\` permission is declared
+- Always check the \`loading\` flag before using context values
+- Context is only available when the host provides it (e.g., when viewing a ticket)
+
+## Best Practices
+
+### Performance
+- Keep bundle size under 500KB
+- Use \`useStore(store, selector)\` with narrow selectors to minimize re-renders
+- Avoid fetching data in multiple surfaces \u2014 fetch once and share via store
+
+### Code Organization
+- One file per surface in \`src/surfaces/\`
+- Shared state in \`src/store.ts\`
+- API wrappers in \`src/lib/\`
+- Feature components in \`src/components/\`
+`;
+
+// ../../sdk/extension/ai-docs/src/utils.ts
+var frontmatter = (meta) => {
+  const lines = ["---"];
+  for (const [key, value] of Object.entries(meta)) {
+    if (Array.isArray(value)) {
+      lines.push(`${key}: ${JSON.stringify(value)}`);
+    } else if (typeof value === "object" && value !== null) {
+      lines.push(`${key}:`);
+      for (const [subKey, subValue] of Object.entries(value)) {
+        lines.push(`  ${subKey}: ${JSON.stringify(subValue)}`);
+      }
+    } else {
+      lines.push(`${key}: ${JSON.stringify(value)}`);
+    }
+  }
+  lines.push("---");
+  return lines.join("\n");
+};
+var generateCoreReference = () => CORE_CONTENT;
+
+// ../../sdk/extension/ai-docs/src/generators/components.ts
+var generateComponents = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Available UI components with allowed attributes per tag",
+    globs: ["packages/extension/src/**/*.tsx"]
+  });
+  const componentLines = [];
+  for (const tag of UI_TAGS) {
+    const attrs = UI_TAG_ATTRIBUTES[tag];
+    const name = tagToComponentName(tag);
+    componentLines.push(`### \`<ui.${name}>\` (\`${tag}\`)`);
+    componentLines.push(`Allowed attributes: ${attrs.map((a2) => `\`${a2}\``).join(", ")}`);
+    componentLines.push("");
+  }
+  const iconList = ALLOWED_ICONS.map((icon) => `\`${icon}\``).join(", ");
+  return `${fm}
+
+# UI Components
+
+Access all components via the \`ui.*\` namespace:
+\`\`\`tsx
+import { ui } from '@stackable-labs/sdk-extension-react'
+\`\`\`
+
+**${UI_TAGS.length} available components** \u2014 only use the attributes listed below for each component.
+
+${componentLines.join("\n")}
+## Available Icons (${ALLOWED_ICONS.length})
+
+Use with \`<ui.Icon name="icon-name" />\`. Valid icon names:
+${iconList}
+`;
+};
+var generateIconReference = () => {
+  const iconList = ALLOWED_ICONS.map((icon) => `- \`${icon}\``).join("\n");
+  return `# Available Icons
+
+Use with \`<ui.Icon name="icon-name" />\`.
+
+${iconList}
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/snippets/hooks.ts
+var HOOK_SNIPPETS = {
+  "events:identity": `import { useIdentityEvent } from '@stackable-labs/sdk-extension-react'
+
+useIdentityEvent('login', (event) => {
+  console.log('User logged in:', event.data.state.user?.email)
+})
+useIdentityEvent('logout', () => {
+  console.log('User logged out')
+})`,
+  "events:messaging": `import { useMessagingEvent } from '@stackable-labs/sdk-extension-react'
+
+useMessagingEvent('postback:Buy Now', (event) => {
+  console.log('Postback:', event.data.actionName, event.data.conversationId)
+})`,
+  "events:activity": `import { useActivityEvent } from '@stackable-labs/sdk-extension-react'
+
+useActivityEvent('product_view', (event) => {
+  console.log('Activity:', event.eventName, event.data)
+})`,
+  "extend.identity": `import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
+
+useExtendIdentity((claims) => ({
+  external_id: \`custom_\${claims.external_id}\`,
+  loyalty_tier: 'gold',
+}))`
+};
+var HOOK_SNIPPETS_MEMOIZED = {
+  "events:messaging": `import { useCallback } from 'react'
+import { useMessagingEvent } from '@stackable-labs/sdk-extension-react'
+import type { MessagingEventHandler } from '@stackable-labs/sdk-extension-contracts'
+
+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'
+import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
+import type { ExtendIdentityHandler } from '@stackable-labs/sdk-extension-contracts'
+
+const handleExtend = useCallback<ExtendIdentityHandler>((claims) => ({
+  external_id: \`custom_\${claims.external_id}\`,
+  loyalty_tier: 'gold',
+}), [])
+useExtendIdentity(handleExtend)`
+};
+
+// ../../sdk/extension/ai-docs/src/generators/capabilities.ts
+var identityEventTypes = Object.values(IDENTITY_EVENTS).map((e) => `'${e}'`).join(" | ");
+var activityEventTypes = Object.values(ACTIVITY_EVENTS).map((e) => `'${e}'`).join(" | ");
+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",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Capabilities
+
+Access capabilities via the \`useCapabilities()\` hook:
+\`\`\`tsx
+const capabilities = useCapabilities()
+\`\`\`
+
+## data.query \u2014 Host-Mediated Requests
+The host handles the API call. Extension sends an action name + params, host returns data.
+- **Permission required:** \`data:query\`
+- **Usage:** \`capabilities.data.query<T>(payload: ApiRequest): Promise<T>\`
+- **ApiRequest shape:** \`{ action: string; [key: string]: unknown }\`
+- **When to use:** When the host application handles the API integration
+
+\`\`\`tsx
+const result = await capabilities.data.query<Customer>({
+  action: 'getCustomer',
+  customerId: '123',
+})
+\`\`\`
+
+## data.fetch \u2014 Direct HTTP from Sandbox
+Extension makes HTTP requests directly. Domain must be in \`allowedDomains\` in manifest.
+- **Permission required:** \`data:fetch\`
+- **Usage:** \`capabilities.data.fetch(url: string, init?: FetchRequestInit): Promise<FetchResponse>\`
+- **FetchRequestInit:** \`{ method?: 'GET'|'POST'|'PUT'|'PATCH'|'DELETE', headers?: Record<string,string>, body?: unknown }\`
+- **FetchResponse:** \`{ status: number, ok: boolean, data: unknown }\`
+- **When to use:** When the extension calls external APIs directly
+
+\`\`\`tsx
+const result = await capabilities.data.fetch('https://api.example.com/data', {
+  method: 'GET',
+  headers: { 'Authorization': 'Bearer token' },
+})
+if (!result.ok) throw new Error(\`Request failed: \${result.status}\`)
+const data = result.data as MyType
+\`\`\`
+
+## context.read \u2014 Read Host Context
+Read host-provided context (customer ID, email, etc.).
+- **Permission required:** \`context:read\`
+- **Usage:** \`capabilities.context.read(): Promise<ContextData>\`
+- **ContextData shape:** \`{ customerId?: string, customerEmail?: string, [key: string]: unknown }\`
+- **Convenience hook:** \`useContextData()\` returns \`ContextData & { loading: boolean }\`
+
+\`\`\`tsx
+// Preferred: use the hook
+const { loading, customerId, customerEmail } = useContextData()
+
+// Alternative: use the capability directly
+const context = await capabilities.context.read()
+\`\`\`
+
+## actions.toast \u2014 Show Toast Notifications
+Display a toast notification in the host UI.
+- **Permission required:** \`actions:toast\`
+- **Usage:** \`capabilities.actions.toast(payload: ToastPayload): Promise<void>\`
+- **ToastPayload:** \`{ message: string, type?: 'success'|'error'|'info'|'warning', duration?: number }\`
+
+\`\`\`tsx
+capabilities.actions.toast({ message: 'Saved!', type: 'success' })
+\`\`\`
+
+## actions.invoke \u2014 Invoke Host Actions
+Trigger host-defined actions (e.g., open a new conversation, set conversation tags/fields).
+- **Permission required:** \`actions:invoke\`
+- **Usage:** \`capabilities.actions.invoke<T>(action: string, payload?: Record<string, unknown>): Promise<T>\`
+- **Available actions:**
+  - \`'newConversation'\` \u2014 start a new Zendesk conversation (optionally with tags/fields)
+  - \`'setConversationTags'\` \u2014 set tags on the current/next conversation
+  - \`'setConversationFields'\` \u2014 set custom fields on the current/next conversation
+  - \`'open'\` / \`'close'\` / \`'show'\` / \`'hide'\` \u2014 control the Zendesk messenger widget
+
+\`\`\`tsx
+// 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'])
+
+// Standalone: set custom fields
+await capabilities.actions.invoke('setConversationFields', [
+  { id: 'order_status', value: 'shipped' },
+])
+\`\`\`
+
+**Zendesk constraints:** Tags max 20, auto-lowercased/sanitized. Fields require \`web_widget_conversation_ticket_metadata\` feature flag. Both \`conversationTags\` and \`conversationFields\` **replace** on each call (not additive).
+
+## events:identity \u2014 Identity Event Subscription
+Subscribe to real-time identity events (login, logout, refresh, expired) pushed from the host.
+- **Permission required:** \`events:identity\`
+- **Manifest events array:** Declare specific events to listen for (e.g. \`["identity:login", "identity:logout"]\`)
+- **Hook:** \`useIdentityEvent(eventType, handler)\`
+- **Event types:** \`${identityEventTypes}\`
+
+\`\`\`json
+{
+  "permissions": ["events:identity"],
+  "events": ["identity:login", "identity:logout"]
+}
+\`\`\`
+
+\`\`\`tsx
+${HOOK_SNIPPETS["events:identity"]}
+\`\`\`
+
+**Note:** Identity state is also available via \`context.read()\` \u2192 \`identity\` field (requires \`context:read\`, no separate permission needed).
+
+## events:messaging \u2014 Messaging Event Subscription
+Subscribe to messaging events (e.g. postback button clicks) pushed from the host widget.
+- **Permission required:** \`events:messaging\`
+- **Manifest events array:** Declare specific events to listen for (e.g. \`["messaging:postback:Buy Now"]\`) or \`"messaging:postback"\` for all postbacks (requires elevated marketplace review)
+- **Hook:** \`useMessagingEvent(eventType, handler)\` \u2014 \`MessagingEventHandler\` type exported for use with \`useCallback\`
+- **Event types:** \`'postback'\` (all postbacks) or \`'postback:<actionName>'\` (specific postback)
+- **Important:** Only \`postback\`-type buttons fire this event. The Zendesk bot builder's "Present options" creates \`reply\`-type buttons (no event). Use the Sunshine Conversations API with \`{ "type": "postback", "text": "Button Label", "payload": "..." }\` actions to create postback buttons.
+- **actionName caveat:** The \`actionName\` in the event is the button's display **text** (e.g. \`"Add to cart"\`), NOT the postback \`payload\` string. The payload is not exposed by the Zendesk Web Widget. Design manifest \`events\` entries to match button text: \`"messaging:postback:Add to cart"\`.
+
+\`\`\`json
+{
+  "permissions": ["events:messaging"],
+  "events": ["messaging:postback:Add to cart", "messaging:postback:Check order"]
+}
+\`\`\`
+
+\`\`\`tsx
+${HOOK_SNIPPETS["events:messaging"]}
+\`\`\`
+
+## events:activity \u2014 Activity Event Subscription
+Subscribe to host activity events (e.g. page views, clicks, purchases) pushed from the host application.
+- **Permission required:** \`events:activity\`
+- **Manifest events array:** Declare specific events to listen for (e.g. \`["activity:product_view", "activity:add_to_cart"]\`) \u2014 manifest uses fully-qualified strings
+- **Hook:** \`useActivityEvent(eventType, handler)\` \u2014 \`ActivityEventHandler\` type exported for use with \`useCallback\`
+- **Event types (domain-stripped):** \`${activityEventTypes} | '*'\`
+- **Well-known event names:**
+
+| Event | Example payload fields |
+|---|---|
+| \`page_view\` | \`{ url, title, referrer }\` |
+| \`click\` | \`{ elementId, elementText, url }\` |
+| \`product_view\` | \`{ productId, productName, price }\` |
+| \`add_to_cart\` | \`{ productId, quantity, price }\` |
+| \`purchase\` | \`{ orderId, total, currency, items }\` |
+| \`search\` | \`{ query, resultCount }\` |
+| \`form_submit\` | \`{ formId, formName, fields }\` |
+
+- \`'*'\` receives ALL activity events
+
+\`\`\`json
+{
+  "permissions": ["events:activity"],
+  "events": ["activity:product_view", "activity:add_to_cart"]
+}
+\`\`\`
+
+\`\`\`tsx
+${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 host 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 }\`
+
+\`\`\`json
+{
+  "permissions": ["extend:identity"]
+}
+\`\`\`
+
+\`\`\`tsx
+${HOOK_SNIPPETS["extend.identity"]}
+\`\`\`
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/snippets/examples.ts
+var EXAMPLE_SNIPPETS = {
+  // ── Structural topics ───────────────────────────────────────────────────────
+  bootstrap: `import { createExtension } from '@stackable-labs/sdk-extension-react'
+import { Header } from './surfaces/Header'
+import { Content } from './surfaces/Content'
+import { Footer } from './surfaces/Footer'
+
+const Extension = () => (
+  <>
+    <Header />
+    <Content />
+    <Footer />
+  </>
+)
+
+// NOTE: extensionId is optional \u2014 used when connected to a registered extension
+createExtension(() => <Extension />, { extensionId: 'my-extension' })`,
+  surfaces: `import { Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Header(): React.ReactElement {
+  return (
+    <Surface id="slot.header">
+      <ui.Stack direction="column" gap="2" className="p-3">
+        <ui.Text className="text-sm font-medium">Hello from slot.header</ui.Text>
+      </ui.Stack>
+    </Surface>
+  )
+}
+
+export function Content(): React.ReactElement {
+  return (
+    <Surface id="slot.content">
+      <ui.Stack direction="column" gap="3" className="p-4">
+        <ui.Heading level="3">Content Surface</ui.Heading>
+        <ui.Text>Rendered inside the host at slot.content.</ui.Text>
+      </ui.Stack>
+    </Surface>
+  )
+}`,
+  store: `import { createStore, useStore, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+// store.ts
+type ViewState = { type: 'list' } | { type: 'detail'; id: string }
+
+interface AppState {
+  viewState: ViewState
+}
+
+export const appStore = createStore<AppState>({
+  viewState: { type: 'list' },
+})
+
+// Content.tsx
+export function Content(): React.ReactElement {
+  const viewState = useStore(appStore, (s) => s.viewState)
+
+  const goToDetail = (id: string) => appStore.set({ viewState: { type: 'detail', id } })
+  const goBack = () => appStore.set({ viewState: { type: 'list' } })
+
+  return (
+    <Surface id="slot.content">
+      {viewState.type === 'list' && (
+        <ui.Button onClick={() => goToDetail('abc123')}>View Detail</ui.Button>
+      )}
+      {viewState.type === 'detail' && (
+        <ui.Stack direction="column" gap="2">
+          <ui.Text>Viewing: {viewState.id}</ui.Text>
+          <ui.Button onClick={goBack}>Back</ui.Button>
+        </ui.Stack>
+      )}
+    </Surface>
+  )
+}`,
+  loading: `import { useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Content(): React.ReactElement {
+  const { loading, customerId } = useContextData()
+
+  if (loading) {
+    return (
+      <Surface id="slot.content">
+        <ui.Skeleton />
+      </Surface>
+    )
+  }
+
+  if (!customerId) {
+    return (
+      <Surface id="slot.content">
+        <ui.Stack direction="column" gap="1" className="p-4 items-center">
+          <ui.Icon name="user" size="sm" />
+          <ui.Text className="text-xs text-muted-foreground">No customer selected</ui.Text>
+        </ui.Stack>
+      </Surface>
+    )
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Text className="text-sm">Customer: {customerId}</ui.Text>
+    </Surface>
+  )
+}`,
+  surfaceContext: `import { useSurfaceContext, Surface, ui } from '@stackable-labs/sdk-extension-react'
+import type { ContextData } from '@stackable-labs/sdk-extension-contracts'
+
+export function Header(): React.ReactElement {
+  // Lower-level hook \u2014 reads host-pushed context for this specific surface
+  const context = useSurfaceContext() as ContextData
+
+  return (
+    <Surface id="slot.header">
+      <ui.Text className="text-xs">{context.customerId ?? 'No customer'}</ui.Text>
+    </Surface>
+  )
+}`,
+  // ── Per-capability example snippets ─────────────────────────────────────────
+  "context.read": `import { useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Header(): React.ReactElement {
+  const { loading, customerId, customerEmail } = useContextData()
+
+  if (loading) {
+    return (
+      <Surface id="slot.header">
+        <ui.Text className="text-xs text-muted-foreground">Loading...</ui.Text>
+      </Surface>
+    )
+  }
+
+  return (
+    <Surface id="slot.header">
+      <ui.Stack direction="column" gap="1">
+        <ui.Text className="text-xs font-semibold">{customerEmail}</ui.Text>
+        <ui.Text className="text-xs text-muted-foreground">ID: {customerId}</ui.Text>
+      </ui.Stack>
+    </Surface>
+  )
+}`,
+  "data.query": `import { useCapabilities, Surface, ui } from '@stackable-labs/sdk-extension-react'
+import { useState } from 'react'
+import type { ApiRequest } from '@stackable-labs/sdk-extension-contracts'
+
+export function Content(): React.ReactElement {
+  const capabilities = useCapabilities()
+  const [data, setData] = useState<unknown>(null)
+
+  const handleQuery = async () => {
+    const payload: ApiRequest = {
+      action: 'getCustomer',
+      customerId: '123',
+    }
+    const result = await capabilities.data.query<{ name: string }>(payload)
+    setData(result)
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Button onClick={handleQuery}>Fetch Data</ui.Button>
+    </Surface>
+  )
+}`,
+  "data.fetch": `import { useCapabilities, Surface, ui } from '@stackable-labs/sdk-extension-react'
+import { useState } from 'react'
+import type { FetchResponse } from '@stackable-labs/sdk-extension-contracts'
+
+export function Content(): React.ReactElement {
+  const capabilities = useCapabilities()
+  const [data, setData] = useState<unknown>(null)
+
+  const handleGet = async () => {
+    const result: FetchResponse = await capabilities.data.fetch('https://api.myservice.com/orders')
+    if (result.ok) setData(result.data)
+  }
+
+  const handlePost = async () => {
+    const result: FetchResponse = await capabilities.data.fetch(
+      'https://api.myservice.com/orders',
+      { method: 'POST', body: { limit: 10 } }
+    )
+    if (result.ok) setData(result.data)
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Stack gap="2">
+        <ui.Button onClick={handleGet}>GET Orders</ui.Button>
+        <ui.Button onClick={handlePost}>POST Orders</ui.Button>
+      </ui.Stack>
+    </Surface>
+  )
+}`,
+  "actions.toast": `import { useCapabilities, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Content(): React.ReactElement {
+  const capabilities = useCapabilities()
+
+  const showToast = async () => {
+    await capabilities.actions.toast({ type: 'success', message: 'Done!' })
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Button onClick={showToast}>Show Toast</ui.Button>
+    </Surface>
+  )
+}`,
+  "actions.invoke": `import { useCapabilities, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Content(): React.ReactElement {
+  const capabilities = useCapabilities()
+
+  const newConversation = async () => {
+    await capabilities.actions.invoke('newConversation', {
+      tags: ['stackable', 'order-lookup'],
+      fields: [{ id: 'stackable_action', value: 'order_status' }],
+      metadata: { orderId: '12345' },
+    })
+  }
+
+  const setTags = async () => {
+    await capabilities.actions.invoke('setConversationTags', ['escalated', 'order-issue'])
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Stack gap="2">
+        <ui.Button onClick={newConversation}>New Conversation</ui.Button>
+        <ui.Button onClick={setTags}>Set Tags</ui.Button>
+      </ui.Stack>
+    </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.
+useExtendIdentity((claims) => ({
+  external_id: \`shopify_\${claims.external_id}\`,
+  loyalty_tier: 'gold',
+}))`,
+  // ── Per-event example 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>
+  )
+}`
+};
+
+// ../../sdk/extension/ai-docs/src/generators/hooks-and-api.ts
+var stripImports = (snippet) => snippet.split("\n").filter((line) => !line.startsWith("import ")).join("\n").trim();
+var identityEventTypes2 = Object.values(IDENTITY_EVENTS).map((e) => `'${e}'`).join(" | ");
+var activityEventTypes2 = Object.values(ACTIVITY_EVENTS).map((e) => `'${e}'`).join(" | ");
+var generateHooksAndApi = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Extension hooks and API reference: createExtension, Surface, useCapabilities, createStore",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Hooks & API Reference
+
+All imports from \`@stackable-labs/sdk-extension-react\`.
+
+## createExtension(factory, options?)
+Bootstrap the extension runtime. Call once in \`src/index.tsx\`.
+- \`factory: () => React.ReactElement\` \u2014 render function returning all surfaces
+- \`options?: { extensionId?: string }\` \u2014 extension identifier
+
+\`\`\`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
+const capabilities = useCapabilities()
+// capabilities.context.read()          \u2014 includes identity state in response
+// capabilities.data.query(payload)
+// 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)
+\`\`\`
+
+## useStore(store, selector?)
+Subscribe to a shared store. Re-renders when the selected state changes.
+\`\`\`tsx
+const viewState = useStore(appStore, (s) => s.viewState)
+\`\`\`
+
+## useContextData()
+Reads host-provided context. Returns \`{ loading, customerId, customerEmail, ... }\`.
+\`\`\`tsx
+const { loading, customerId, customerEmail } = useContextData()
+\`\`\`
+
+## useSurfaceContext()
+Returns host-provided context specific to the current surface slot.
+\`\`\`tsx
+const surfaceContext = useSurfaceContext()
+\`\`\`
+
+## useExtension()
+Returns extension-level context.
+\`\`\`tsx
+const { extensionId } = useExtension()
+\`\`\`
+
+## 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
+
+## useIdentityEvent(eventType, handler)
+Subscribe to identity events pushed from the host. Requires \`events:identity\` permission and matching entries in manifest \`events\` array.
+- \`eventType: ${identityEventTypes2}\`
+- \`handler: (event: IdentityEvent) => void\`
+- \`IdentityEvent: { eventName: IdentityEventType, data: { state: IdentityState, timestamp: string } }\`
+- \`IdentityState: { authenticated: boolean, user: UserIdentity | null, expiresAt?: string }\`
+
+\`\`\`tsx
+${stripImports(HOOK_SNIPPETS["events:identity"])}
+\`\`\`
+
+## useMessagingEvent(eventType, handler)
+Subscribe to messaging events (e.g. postback button clicks) pushed from the host widget. Requires \`events:messaging\` permission and matching entries in manifest \`events\` array.
+- \`eventType: 'postback' | 'postback:<actionName>'\`
+- \`handler: MessagingEventHandler\` \u2014 \`(event: MessagingEvent) => void\`
+- \`MessagingPostbackEvent: { eventName: 'postback', data: { actionName: string, conversationId: string, timestamp: string } }\`
+- \`'postback'\` receives ALL postback events (requires elevated marketplace review)
+- \`'postback:<actionName>'\` receives only events matching the specific actionName
+
+\`\`\`tsx
+${stripImports(HOOK_SNIPPETS["events:messaging"])}
+\`\`\`
+
+With \`useCallback\` (for memoized handlers):
+\`\`\`tsx
+${HOOK_SNIPPETS_MEMOIZED["events:messaging"]}
+\`\`\`
+
+## useActivityEvent(eventType, handler)
+Subscribe to host activity events. Requires \`events:activity\` permission and matching entries in manifest \`events\` array.
+- \`eventType: ${activityEventTypes2} | '*'\` (domain-stripped)
+- \`handler: ActivityEventHandler\` \u2014 \`(event: ActivityEvent) => void\`
+- \`ActivityEvent: { eventName: string, data: Record<string, unknown> }\`
+- \`'*'\` receives ALL activity events
+
+\`\`\`tsx
+${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\`
+
+\`\`\`tsx
+useEvent('activity', (event) => {
+  console.log('Activity:', event.data)
+})
+\`\`\`
+
+## useExtendIdentity(handler)
+Register a handler to enrich identity JWT claims before signing. Requires \`extend:identity\` 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"])}
+\`\`\`
+
+With \`useCallback\` (for memoized handlers):
+\`\`\`tsx
+${HOOK_SNIPPETS_MEMOIZED["extend.identity"]}
+\`\`\`
+
+## 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? }
+\`\`\`
+`;
+};
+var generatePermissions = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Permission strings, capability mapping, and target-permission conventions",
+    globs: ["packages/extension/public/manifest.json", "packages/extension/src/**/*.ts"]
+  });
+  const permissionList = PERMISSIONS.map((p) => `- \`${p}\``).join("\n");
+  const mappingLines = Object.entries(CAPABILITY_PERMISSION_MAP).map(([cap, perm]) => `| \`${cap}\` | \`${perm}\` |`).join("\n");
+  return `${fm}
+
+# Permissions
+
+Declare permissions in \`manifest.json\` before using the corresponding capability.
+
+## Available Permissions (${PERMISSIONS.length})
+
+${permissionList}
+
+## Capability \u2192 Permission Mapping
+
+| Capability | Required Permission |
+|-----------|-------------------|
+${mappingLines}
+
+## Target \u2192 Permission Conventions
+
+Common permission sets for each surface target:
+
+| Target | Typical Permissions |
+|--------|-------------------|
+| \`slot.header\` | \`context:read\` |
+| \`slot.content\` | \`context:read\`, \`data:query\`, \`actions:toast\`, \`actions:invoke\` |
+| \`slot.footer\` | (none) |
+| \`slot.footer-links\` | (none) |
+
+Only declare permissions your extension actually uses.
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/generators/suggestions.ts
+var generateSuggestions = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Contextual suggestion patterns for recommending next steps based on current extension code, capabilities, and surfaces",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Next Steps \u2014 Suggestion Patterns
+
+Use these patterns to analyze the current extension and suggest 2-3 specific, actionable next steps.
+Suggestions should reference actual data, components, and capabilities in the extension \u2014 never generic.
+
+## When to suggest
+
+- After making code changes (\`updateCode\`, \`updateManifest\`)
+- After adding a surface, capability, or component
+- Do NOT suggest after answering a question or explaining code
+
+## Suggestion format
+
+- **Label:** 2-5 word actionable verb phrase (e.g., "Show order total", "Add loading state")
+- **Prompt:** Specific enough that clicking it produces a useful result. Reference actual data or code in the extension (e.g., "Add the shipping address from the data.fetch response below the order total")
+
+## Pattern categories
+
+### Code-aware \u2014 analyze what's in the code vs. what's possible
+
+| Signal | Suggestion direction |
+|--------|---------------------|
+| Data fields fetched but not rendered | Suggest rendering unused fields (e.g., "Show order total", "Display customer email") |
+| Component rendered without styling refinement | Suggest layout improvements (e.g., "Add spacing to header", "Style the card layout") |
+| Surface exists but is sparse (few child components) | Suggest adding content (e.g., "Add status badge to header", "Include action buttons") |
+| No error/loading handling for async operations | Suggest robustness (e.g., "Add loading state", "Handle fetch errors") |
+| Hardcoded values that could come from context | Suggest dynamic data (e.g., "Use customer name from context") |
+
+### Capability-aware \u2014 suggest capabilities the extension doesn't use yet
+
+| Current state | Suggestion direction |
+|---------------|---------------------|
+| No capabilities wired | Suggest one relevant to the extension's apparent purpose |
+| Has \`data.fetch\` but no \`context.read\` | "Wire up customer context" |
+| Has \`data.query\` but no \`actions.toast\` | "Add success notifications" |
+| Uses \`context.read\` data but doesn't pass it to \`data.fetch\` | "Use context in API call" |
+| Has \`data.fetch\` but no error handling | "Handle API errors gracefully" |
+
+### Surface-aware \u2014 suggest additional UI surfaces
+
+| Current surfaces | Suggestion direction |
+|-----------------|---------------------|
+| Only \`content\` | "Add a header surface" or "Add footer actions" |
+| Only \`header\` | "Add a content surface" |
+| Has content but no \`footer-links\` | "Add quick action links" |
+| Has header + content but no footer | "Add footer with action buttons" |
+
+### Platform-aware \u2014 suggest based on extension target
+
+| Target platform | Suggestion direction |
+|----------------|---------------------|
+| Commerce (Shopify, BigCommerce) | Order data, product info, customer purchase history |
+| Support (Zendesk, Freshdesk) | Ticket context, conversation data, agent tools |
+| General | Configuration, settings, external API integrations |
+
+## Quality rules
+
+- Never suggest something already present in the code
+- Prefer suggestions that build on what the user just did (e.g., after adding a surface, suggest populating it)
+- Mix suggestion types: one "enhance what's there", one "add something new", one "improve quality" (loading/error states, styling)
+- Labels must be short enough to fit in a chip button (2-5 words)
+- Prompts should be one sentence that clearly describes the change
+
+## Examples by context
+
+| After this action | Label | Prompt |
+|---|---|---|
+| Added \`data.fetch\` to an orders API | "Show order total" | "Add the order total from the data.fetch response to the content surface" |
+| Added a header surface | "Add status badge" | "Add a status badge component to the header showing the current order status" |
+| Wired up \`context.read\` | "Use in API call" | "Pass the customerId from context.read as a parameter in the data.fetch call" |
+| Styled a component | "Add loading state" | "Add a loading skeleton that displays while the data.fetch call is in progress" |
+| Added \`data.query\` | "Show results in list" | "Render the query results as a list of cards in the content surface" |
+| Added a button | "Wire up action" | "Connect the button click to an actions.invoke call" |
+| Added error handling | "Add success toast" | "Show a success toast notification when the operation completes" |
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/generators/guardrails.ts
+var generateGuardrails = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "SDK constraints and rules that must always be followed",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts", "packages/extension/public/manifest.json"],
+    cursor: { alwaysApply: true }
+  });
+  return `${fm}
+
+# Guardrails
+
+These rules must always be followed when writing extension code.
+
+## Sandbox
+- Never access \`document\` or \`window.location\` directly \u2014 the extension runs in a sandboxed iframe
+- Never modify files in \`packages/preview/\` \u2014 the preview host is pre-configured
+
+## Components
+- Use the \`ui.*\` namespace for components (\`<ui.Card>\`, \`<ui.Button>\`) \u2014 don't import components directly
+- Only use the attributes listed in the component reference \u2014 the host rejects unknown attributes
+- Use \`<ui.ScrollArea>\` for content that may overflow
+
+## Manifest
+- Always declare permissions in \`manifest.json\` before using capabilities
+- Don't use \`data.fetch\` without adding the domain to \`allowedDomains\` in manifest
+- \`allowedDomains\` must be exact hostnames \u2014 no wildcards, no paths
+
+## Entry Point
+- Don't modify \`index.html\` \u2014 the extension entry point is always \`src/index.tsx\` via \`createExtension\`
+
+## State Management
+- Use discriminated unions for view state types, not string constants
+- Always handle loading states when using capabilities or context data
+
+## Performance
+- Keep bundle size under 500KB
+- Use the API wrapper pattern \u2014 don't call \`data.fetch\` inline in components
+- Use narrow selectors with \`useStore(store, selector)\` to minimize re-renders
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/generators/overview.ts
+var generateOverview = () => {
+  const fm = frontmatter({
+    root: true,
+    targets: ["*"],
+    description: "Stackable Labs Extension SDK overview, packages, and import conventions",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"],
+    cursor: { alwaysApply: true }
+  });
+  const baseBody = CORE_CONTENT.replace(/^#[^\n]*\n+(?:>[^\n]*\n+)?/, "");
+  return `${fm}
+
+# Stackable Labs Extension Development
+
+## SDK Packages
+This extension is built on the following npm packages. When generating code,
+read the installed source in node_modules to ensure type-accurate imports:
+- \`@stackable-labs/sdk-extension-react\` \u2014 hooks, createExtension, Surface, UI components
+- \`@stackable-labs/sdk-extension-contracts\` \u2014 TypeScript types, constants, manifest schema
+
+## Import Convention
+Components are accessed via the \`ui.*\` namespace:
+\`\`\`tsx
+import { ui, Surface, createExtension, useCapabilities } from '@stackable-labs/sdk-extension-react'
+// Usage: <ui.Card>, <ui.Button>, <ui.Text>, etc.
+// Do NOT import components directly (e.g., import { Card } will not work)
+\`\`\`
+
+## Project Structure
+\`\`\`
+packages/extension/
+  public/
+    manifest.json          # Extension manifest (targets, permissions, allowedDomains)
+  src/
+    index.tsx              # Entry point \u2014 createExtension bootstraps the runtime
+    store.ts               # Shared store for cross-surface state (createStore)
+    surfaces/              # One file per surface (Header.tsx, Content.tsx, Footer.tsx)
+    components/            # Feature components rendered within surfaces
+    lib/                   # API wrappers and utilities
+packages/preview/          # Local preview host \u2014 DO NOT MODIFY
+\`\`\`
+
+${baseBody}
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/generators/patterns.ts
+var generatePatterns = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Code patterns: store navigation, API wrapper, surface composition",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  const sections = PATTERN_SECTIONS.map(({ path, title, code }) => `## ${title}
+
+\`\`\`tsx
+// src/${path}
+${code}
+\`\`\``).join("\n\n");
+  const body = `# Code Patterns
+
+${sections}
+`;
+  return `${fm}
+
+${body}`;
+};
+
+// ../../sdk/extension/ai-docs/src/generators/recipes.ts
+var generateRecipes = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Reference code and recipes for common extension development tasks",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts", "packages/extension/public/manifest.json"]
+  });
+  const references = RECIPE_SECTIONS.map(({ path, title, code }) => `## Reference: ${title}
+
+\`\`\`tsx
+// src/${path}
+${code}
+\`\`\``).join("\n\n");
+  const body = `# Recipes
+
+${references}
+`;
+  return `${fm}
+
+${body}`;
+};
+var SURFACE_SNIPPETS = {
+  [SURFACE_TARGETS.HEADER]: `import { Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Header() {
+  return (
+    <Surface id="slot.header">
+      <ui.Text className="text-sm font-medium">Header content</ui.Text>
+    </Surface>
+  )
+}`,
+  [SURFACE_TARGETS.CONTENT]: `import { Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Content() {
+  return (
+    <Surface id="slot.content">
+      <ui.Card>
+        <ui.CardContent>
+          <ui.Text>Extension content</ui.Text>
+        </ui.CardContent>
+      </ui.Card>
+    </Surface>
+  )
+}`,
+  [SURFACE_TARGETS.FOOTER]: `import { Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Footer() {
+  return (
+    <Surface id="slot.footer">
+      <ui.Text className="text-xs">Powered by My Extension</ui.Text>
+    </Surface>
+  )
+}`,
+  [SURFACE_TARGETS.FOOTER_LINKS]: `import { Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function FooterLinks() {
+  return (
+    <Surface id="slot.footer-links">
+      <ui.FooterLink href="https://example.com">My Extension</ui.FooterLink>
+    </Surface>
+  )
+}`
+};
+
+// ../../sdk/extension/ai-docs/src/generators/surfaces.ts
+var generateSurfaces = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Surface types, lifecycle, and layout slots for Stackable extensions",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Surfaces
+
+Surfaces are the UI slots where your extension renders content inside the host application.
+Each surface maps to a specific layout position and is declared as a React component using
+the \`<Surface>\` wrapper from \`@stackable-labs/sdk-extension-react\`.
+
+## Surface Slots
+
+| Slot | Target String | Typical Use |
+|------|--------------|-------------|
+| Header | \`slot.header\` | Compact status bar, quick actions, summary info |
+| Content | \`slot.content\` | Main extension UI \u2014 forms, data display, workflows |
+| Footer | \`slot.footer\` | Actions, save buttons, contextual controls |
+| Footer Links | \`slot.footer-links\` | Navigation links, external references |
+
+## Declaring a Surface
+
+Each surface is a React component wrapped in \`<Surface>\`:
+
+\`\`\`tsx
+${SURFACE_SNIPPETS[SURFACE_TARGETS.CONTENT]}
+\`\`\`
+
+The \`id\` prop must match a target declared in your \`manifest.json\`:
+\`\`\`json
+{
+  "targets": ["slot.content"]
+}
+\`\`\`
+
+## Registering Surfaces
+
+Surfaces are composed in the entry point (\`src/index.tsx\`) via \`createExtension\`:
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS.bootstrap}
+\`\`\`
+
+\`createExtension\` bootstraps the extension runtime \u2014 it handles the sandboxed iframe
+communication, capability injection, and surface registration with the host.
+
+## Surface Lifecycle
+
+1. **Mount** \u2014 Host creates an iframe for the extension and loads the entry point
+2. **Register** \u2014 \`createExtension\` scans the rendered tree for \`<Surface>\` components
+3. **Render** \u2014 Each \`<Surface>\` renders its children into the matching host slot
+4. **Update** \u2014 Surfaces re-render when props, state, or context data changes
+5. **Unmount** \u2014 Host removes the extension iframe when no longer needed
+
+## Multi-Surface State
+
+Surfaces share state via \`createStore\` (see Store & Navigation). Each surface can read
+and write to the same store, enabling coordinated behavior across layout slots:
+
+\`\`\`tsx
+import { useStore } from '@stackable-labs/sdk-extension-react'
+import { appStore } from '../store'
+
+export const Header = () => {
+  const viewState = useStore(appStore, (s) => s.viewState)
+  return (
+    <Surface id="slot.header">
+      <ui.Text>Current view: {viewState.type}</ui.Text>
+    </Surface>
+  )
+}
+\`\`\`
+
+## Best Practices
+
+- **One surface per file** \u2014 keep surfaces in \`src/surfaces/\` with clear names (Header.tsx, Content.tsx)
+- **Minimal surface components** \u2014 surfaces should compose feature components from \`src/components/\`
+- **Always declare targets** \u2014 every \`<Surface id="...">\` must have a matching target in manifest.json
+- **Use ScrollArea** \u2014 wrap content surfaces in \`<ui.ScrollArea>\` for overflow handling
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/cli-commands.ts
+var DLX = "pnpm --config.dlx-cache-max-age=0 dlx";
+var CLI = {
+  /** Scaffold a new extension project */
+  create: (name = "<project-name>") => `${DLX} @stackable-labs/create-extension ${name}`,
+  /** Start dev servers with hot reload */
+  dev: `${DLX} @stackable-labs/cli-app-extension@latest dev`,
+  /** Deploy the extension */
+  deploy: `${DLX} @stackable-labs/cli-app-extension@latest deploy`,
+  /** Validate the extension for common errors */
+  validate: `${DLX} @stackable-labs/cli-app-extension@latest validate`,
+  /** Scaffold from an existing extension */
+  scaffold: `${DLX} @stackable-labs/cli-app-extension@latest scaffold`,
+  /** Update an existing extension */
+  update: `${DLX} @stackable-labs/cli-app-extension@latest update`
+};
+var TEMPLATE_FLAVORS = [
+  { name: "minimal", label: "Minimal", description: "Bare minimum \u2014 single surface, hello-world component" },
+  { name: "starter", label: "Starter", description: "Common patterns \u2014 store, api helpers, menu (default)" },
+  { name: "kitchen-sink", label: "Kitchen Sink", description: "Everything \u2014 every component, capability, surface, and hook" }
+];
+
+// ../../sdk/extension/ai-docs/src/generators/quick-start.ts
+var generateQuickStart = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Step-by-step guide to create, develop, and deploy your first Stackable extension",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Quick Start
+
+Create, develop, and deploy your first Stackable extension in minutes.
+
+## Prerequisites
+
+- **Node.js** 22 or later
+- **pnpm** (recommended) or npm
+
+## 1. Create a New Extension
+
+Scaffold a new extension project:
+
+\`\`\`bash
+${CLI.create("my-extension")}
+cd my-extension
+pnpm install
+\`\`\`
+
+This creates a project with:
+- A working extension with header, content, and footer surfaces
+- A local preview host for development
+- TypeScript configuration
+- A manifest with default permissions and targets
+
+## 2. Preview Your Extension
+
+Run the Stackable CLI dev server from your project directory:
+
+\`\`\`bash
+${CLI.dev}
+\`\`\`
+
+> **Note:** This uses \`pnpm dlx\` to run the Stackable CLI without installing it
+> globally. The \`--config.dlx-cache-max-age=0\` flag ensures you always get the
+> latest version.
+
+The dev command:
+1. Starts a local Vite dev server for your extension with hot reload
+2. Creates a public Cloudflare tunnel to your local server
+3. Displays a **query parameter** you can use to preview your extension
+
+### Testing against your host app
+
+The CLI outputs a query param like:
+
+\`\`\`
+?_stackable_dev=ext-123%3Ahttps%3A%2F%2Fabc.trycloudflare.com
+\`\`\`
+
+Copy this and **append it to your host application URL** to load your local extension
+instead of the production bundle. For example:
+
+\`\`\`
+https://your-app.com/dashboard?_stackable_dev=ext-123%3Ahttps%3A%2F%2Fabc.trycloudflare.com
+\`\`\`
+
+This override is **browser-session only** \u2014 no database changes, no shared state.
+Each developer gets isolated overrides. Changes you make locally appear immediately
+in the host app via hot reload.
+
+Use \`--no-tunnel\` if you only want to run the local Vite dev server without a tunnel.
+
+## 3. Explore the Project
+
+\`\`\`
+my-extension/
+  packages/
+    extension/
+      public/
+        manifest.json       # Targets, permissions, allowed domains
+      src/
+        index.tsx           # Entry point \u2014 createExtension bootstraps the runtime
+        store.ts            # Shared state across surfaces
+        surfaces/           # One component per surface slot
+          Header.tsx
+          Content.tsx
+          Footer.tsx
+        components/         # Feature components used by surfaces
+        lib/                # API wrappers and utilities
+    preview/                # Local preview host \u2014 DO NOT MODIFY
+\`\`\`
+
+## 4. Make Your First Change
+
+Open \`packages/extension/src/surfaces/Content.tsx\` and modify the content:
+
+\`\`\`tsx
+import { Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export const Content = () => (
+  <Surface id="slot.content">
+    <ui.Card>
+      <ui.CardContent>
+        <ui.Heading level={3}>Hello, Stackable!</ui.Heading>
+        <ui.Text>My first extension is working.</ui.Text>
+      </ui.CardContent>
+    </ui.Card>
+  </Surface>
+)
+\`\`\`
+
+Save the file \u2014 the preview updates automatically.
+
+## 5. Add a Capability
+
+To read host context data (customer info, etc.):
+
+1. Add the permission to \`manifest.json\`:
+\`\`\`json
+{
+  "permissions": ["context:read"]
+}
+\`\`\`
+
+2. Use it in a surface:
+\`\`\`tsx
+import { Surface, useContextData, ui } from '@stackable-labs/sdk-extension-react'
+
+export const Content = () => {
+  const { loading, customerId } = useContextData()
+
+  if (loading) {
+    return (
+      <Surface id="slot.content">
+        <ui.Skeleton />
+      </Surface>
+    )
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Card>
+        <ui.CardContent>
+          <ui.Text>Customer: {customerId}</ui.Text>
+        </ui.CardContent>
+      </ui.Card>
+    </Surface>
+  )
+}
+\`\`\`
+
+## 6. Validate & Deploy
+
+Before deploying, validate your extension:
+
+\`\`\`bash
+${CLI.validate}
+\`\`\`
+
+This checks manifest structure, permission usage, surface targets, and import patterns.
+
+When ready, deploy:
+
+\`\`\`bash
+${CLI.deploy}
+\`\`\`
+
+## Next Steps
+
+- **[Components](/docs/reference/components)** \u2014 browse the full UI component catalog
+- **[Capabilities](/docs/reference/capabilities)** \u2014 learn about data.query, data.fetch, and more
+- **[Surfaces](/docs/reference/surfaces)** \u2014 understand surface types and layout slots
+- **[Patterns](/docs/reference/patterns)** \u2014 see common extension code patterns
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/generators/cli-reference.ts
+var generateCliReference = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "CLI commands for creating, developing, and deploying Stackable extensions",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  const templateRows = TEMPLATE_FLAVORS.map((t) => `| \`${t.name}\` | ${t.description} |`).join("\n");
+  return `${fm}
+
+# CLI Reference
+
+The Stackable CLI provides commands to create, develop, validate, and deploy extensions.
+
+## create
+
+Scaffold a new extension project:
+
+\`\`\`bash
+${CLI.create()}
+\`\`\`
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| \`project-name\` | Directory name for the new project |
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| \`--template <flavor>\` | Template flavor (see below) |
+| \`--app-id <id>\` | Skip App selection |
+| \`--extension-port <port>\` | Extension dev server port (default: 6543) |
+| \`--preview-port <port>\` | Preview dev server port |
+| \`--skip-install\` | Skip package manager install |
+| \`--skip-git\` | Skip git initialization |
+
+**Template flavors:**
+
+| Flavor | Description |
+|--------|-------------|
+${templateRows}
+
+**Example:**
+\`\`\`bash
+${CLI.create("order-lookup")}
+cd order-lookup
+pnpm install
+\`\`\`
+
+## dev
+
+Start dev servers with a public tunnel for live preview:
+
+\`\`\`bash
+${CLI.dev}
+\`\`\`
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| \`--dir <path>\` | Project root (default: cwd) |
+| \`--extension-port <port>\` | Override extension port |
+| \`--preview-port <port>\` | Override preview port |
+| \`--no-tunnel\` | Skip tunnel, just run vite dev |
+
+**What it does:**
+1. Reads \`.env.stackable\` for cached App/Extension context (prompts if missing)
+2. Creates Cloudflare tunnels for the extension dev server
+3. Starts Vite dev servers with hot reload
+4. Displays a \`_stackable_dev\` query param to append to your host app URL
+
+### Host App Override
+
+The CLI outputs a query param like:
+
+\`\`\`
+?_stackable_dev=ext-123%3Ahttps%3A%2F%2Fabc.trycloudflare.com
+\`\`\`
+
+Append this to your deployed host app URL to load your local extension instead
+of the production bundle. The override is browser-session only \u2014 no DB changes,
+no shared state. Each developer gets isolated overrides.
+
+## validate
+
+Check your extension for common errors before deploying:
+
+\`\`\`bash
+${CLI.validate}
+\`\`\`
+
+**What it checks:**
+
+| Check | Description |
+|-------|-------------|
+| Manifest structure | Valid JSON, required fields present |
+| Permission usage | Capabilities used in code have matching permissions in manifest |
+| Surface targets | Each \`<Surface id="...">\` has a matching target in manifest |
+| Import validation | Uses \`ui.*\` namespace, no direct component imports |
+| Domain configuration | \`data.fetch\` calls match \`allowedDomains\` entries |
+| Sandbox compliance | No \`document\` or \`window.location\` access |
+
+**Exit codes:**
+- \`0\` \u2014 all checks pass
+- \`1\` \u2014 errors found (must fix before deploying)
+
+## deploy
+
+Package and deploy the extension:
+
+\`\`\`bash
+${CLI.deploy}
+\`\`\`
+
+**What it does:**
+1. Runs validation checks (same as validate)
+2. Builds the extension for production
+3. Packages the build output
+4. Uploads to the Stackable extension registry
+
+**Prerequisites:**
+- All validation checks must pass
+- You must be authenticated (follow the prompts if not)
+
+## scaffold
+
+Scaffold a local project from an existing extension:
+
+\`\`\`bash
+${CLI.scaffold} [extensionId]
+\`\`\`
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| \`--app-id <id>\` | App ID (auto-resolved from extensionId if omitted) |
+| \`--project-id <id>\` | Studio project ID (fetches files/manifest from Studio) |
+| \`--skip-install\` | Skip package manager install |
+| \`--skip-git\` | Skip git initialization |
+
+## update
+
+Update an existing extension:
+
+\`\`\`bash
+${CLI.update} [extensionId]
+\`\`\`
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| \`--app-id <id>\` | App ID (auto-resolved from extensionId if omitted) |
+| \`--name <name>\` | New extension name |
+| \`--targets <targets>\` | Comma-separated target slots |
+| \`--bundle-url <url>\` | New bundle URL |
+| \`--enabled <bool>\` | Enable/disable extension |
+| \`--dir <path>\` | Project root (default: cwd) |
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/generators/external-apis.ts
+var generateExternalApis = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Direct HTTP requests via data.fetch, allowedDomains configuration, and API wrapper patterns",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts", "packages/extension/public/manifest.json"]
+  });
+  return `${fm}
+
+# External APIs
+
+Extensions can make direct HTTP requests to external services using the \`data.fetch\`
+capability. All requests are proxied through the host for security \u2014 the extension
+never makes raw network calls from the sandbox.
+
+## Setup
+
+### 1. Add Permission
+
+Add \`data:fetch\` to your manifest permissions:
+
+\`\`\`json
+{
+  "permissions": ["data:fetch"]
+}
+\`\`\`
+
+### 2. Configure Allowed Domains
+
+Every domain your extension calls must be listed in \`allowedDomains\`:
+
+\`\`\`json
+{
+  "allowedDomains": ["api.example.com", "graphql.example.com"]
+}
+\`\`\`
+
+**Rules:**
+- Exact hostnames only \u2014 no wildcards, no paths, no protocols
+- The host rejects requests to unlisted domains
+- Add each subdomain separately (e.g., \`api.example.com\` and \`cdn.example.com\`)
+
+### 3. Make Requests
+
+Access \`data.fetch\` through the \`useCapabilities()\` hook:
+
+\`\`\`tsx
+const capabilities = useCapabilities()
+
+const result = await capabilities.data.fetch('https://api.example.com/data', {
+  method: 'GET',
+  headers: { 'Authorization': 'Bearer token' },
+})
+
+if (!result.ok) throw new Error(\`Request failed: \${result.status}\`)
+const data = result.data as MyType
+\`\`\`
+
+## API Signature
+
+\`\`\`tsx
+capabilities.data.fetch(url: string, init?: FetchRequestInit): Promise<FetchResponse>
+\`\`\`
+
+**FetchRequestInit:**
+| Field | Type | Default |
+|-------|------|---------|
+| \`method\` | \`'GET' \\| 'POST' \\| 'PUT' \\| 'PATCH' \\| 'DELETE'\` | \`'GET'\` |
+| \`headers\` | \`Record<string, string>\` | \`{}\` |
+| \`body\` | \`unknown\` | \u2014 |
+
+**FetchResponse:**
+| Field | Type | Description |
+|-------|------|-------------|
+| \`status\` | \`number\` | HTTP status code |
+| \`ok\` | \`boolean\` | \`true\` if status is 2xx |
+| \`data\` | \`unknown\` | Parsed response body |
+
+## API Wrapper Pattern
+
+Create a typed wrapper in \`src/lib/api.ts\` to keep components clean:
+
+\`\`\`tsx
+import type { Capabilities } from '@stackable-labs/sdk-extension-react'
+
+const BASE_URL = 'https://api.example.com'
+
+export async function fetchCustomer(
+  capabilities: Capabilities,
+  customerId: string
+): Promise<Customer> {
+  const result = await capabilities.data.fetch(
+    \`\${BASE_URL}/customers/\${customerId}\`
+  )
+  if (!result.ok) throw new Error(\`Failed to fetch customer: \${result.status}\`)
+  return result.data as Customer
+}
+
+export async function updateCustomer(
+  capabilities: Capabilities,
+  customerId: string,
+  data: Partial<Customer>
+): Promise<Customer> {
+  const result = await capabilities.data.fetch(
+    \`\${BASE_URL}/customers/\${customerId}\`,
+    {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: data,
+    }
+  )
+  if (!result.ok) throw new Error(\`Failed to update customer: \${result.status}\`)
+  return result.data as Customer
+}
+\`\`\`
+
+Then use it in components:
+
+\`\`\`tsx
+const capabilities = useCapabilities()
+const customer = await fetchCustomer(capabilities, customerId)
+\`\`\`
+
+## data.fetch vs data.query
+
+| | data.fetch | data.query |
+|--|-----------|-----------|
+| **Who handles the request** | Extension (via proxy) | Host application |
+| **Permission** | \`data:fetch\` | \`data:query\` |
+| **Domain config** | Required (\`allowedDomains\`) | Not needed |
+| **Use when** | Calling external APIs directly | Host provides the API integration |
+
+## Error Handling
+
+Always check \`result.ok\` before accessing \`result.data\`:
+
+\`\`\`tsx
+const result = await capabilities.data.fetch(url)
+if (!result.ok) {
+  capabilities.actions.toast({
+    message: 'Request failed. Please try again.',
+    type: 'error',
+  })
+  return
+}
+\`\`\`
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/generators/extension-studio.ts
+var generateExtensionStudio = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Extension Studio: in-browser builder with AI assistant, component palette, and live preview",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Extension Studio
+
+Extension Studio is an in-browser development environment for building Stackable
+extensions without local tooling. It runs inside the admin dashboard and provides
+a code editor, live preview, component palette, and an AI assistant \u2014 everything
+needed to create, iterate on, and deploy extensions from the browser.
+
+## Layout
+
+Studio is organized as a 3-pane workspace:
+
+| Pane | Position | Purpose |
+|------|----------|---------|
+| **Shelf** | Left (collapsible) | Component palette, surface picker, capability list |
+| **Stage** | Center | Code editor (CodeMirror) or live preview \u2014 toggle between modes |
+| **Sidekick** | Right (collapsible, resizable) | AI chat assistant for code generation and SDK guidance |
+
+## The Shelf
+
+The Shelf is a collapsible sidebar with three sections:
+
+### Components
+
+Browse all available \`ui.*\` components grouped by category (Layout, Text, Input,
+Feedback, Navigation, Composite). Click a component to insert it into your code \u2014
+in Code mode it inserts at the cursor, in Preview mode or with Shift+Click it uses
+AI-powered smart insertion to place the component in the correct location.
+
+### Surfaces
+
+Lists the surface targets available for your app (e.g., \`slot.header\`,
+\`slot.content\`, \`slot.footer\`). Surfaces already present in your code are
+filtered out. Clicking a surface adds it to your manifest and inserts a
+\`<Surface>\` block via AI smart insertion.
+
+### Capabilities
+
+The SDK capabilities your extension can use: \`data.query\`, \`data.fetch\`,
+\`context.read\`, \`actions.toast\`, \`actions.invoke\`, \`extend.identity\`,
+\`events:identity\`, \`events:messaging\`, and \`events:activity\`. Clicking a
+capability adds the permission to your manifest and AI-inserts the hook usage.
+
+## The Stage
+
+The center pane switches between two modes:
+
+- **Code mode** \u2014 a CodeMirror 6 editor with TypeScript/JSX syntax highlighting,
+  auto-save, and keyboard shortcuts (Cmd+S to save, Cmd+Z/Shift+Z for undo/redo,
+  Tab for indentation)
+- **Preview mode** \u2014 a live preview that renders your extension exactly as it
+  would appear in production, using the same Remote DOM pipeline as deployed
+  extensions
+
+Changes in Code mode recompile automatically via in-browser esbuild and update
+the preview. The toolbar shows the current status: Ready, Saving, Compiling,
+Thinking (AI), or Error.
+
+## The Sidekick
+
+The Sidekick is an AI chat assistant that understands the Stackable Extension SDK.
+It can:
+
+- **Write and modify code** \u2014 ask it to add features, fix bugs, or refactor
+- **Update the manifest** \u2014 it can add permissions, targets, and allowed domains
+- **Look up SDK reference** \u2014 it queries the full SDK documentation on demand
+- **Suggest next steps** \u2014 after making changes, it offers contextual suggestions
+  as clickable chips
+
+The Sidekick adapts multi-file SDK documentation to Studio's single-file context
+automatically \u2014 you don't need to worry about file structure when working in Studio.
+
+## Getting Started
+
+1. Navigate to the **Studio** section in the admin dashboard
+2. Select (or create) an App
+3. Create a new project \u2014 starts with a blank template
+4. Use the Shelf to add components, surfaces, and capabilities
+5. Chat with the Sidekick to build out your extension
+6. Toggle to Preview mode to see your extension rendered live
+
+## Exporting to a Local Project
+
+When your extension outgrows single-file editing or you want to use your own
+IDE and version control, export the Studio project to a local CLI project:
+
+\`\`\`bash
+${CLI.scaffold} --project-id <projectId>
+\`\`\`
+
+This scaffolds a full multi-file extension project from your Studio code,
+including surfaces split into separate files, a store, and a configured manifest.
+
+You can also download the project as a zip file from the export menu in the
+Studio toolbar.
+
+## Studio vs CLI
+
+| | Studio | CLI |
+|---|---|---|
+| **Best for** | Prototyping, learning, quick iterations | Production extensions, team workflows |
+| **Code structure** | Single file | Multi-file (surfaces/, components/, lib/) |
+| **Preview** | Built-in live preview | Local dev server + Cloudflare tunnel |
+| **AI assistance** | Sidekick chat + smart insertion | Your own AI editor (with SDK skills) |
+| **Version control** | Auto-saved to cloud | Git-based |
+| **Deployment** | Link to extension + deploy | CLI deploy command |
+
+Both workflows produce the same output \u2014 a Stackable extension that runs in the
+host application via the same Remote DOM pipeline. Start in Studio to prototype,
+then scaffold to CLI when you need the full development workflow.
+`;
+};
+var generateProjectStructure = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Extension project file structure, entry point, surfaces, store, and manifest",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts", "packages/extension/public/manifest.json"]
+  });
+  return `${fm}
+
+# Project Structure
+
+A Stackable extension project is a monorepo with two packages: the extension itself
+and a local preview host for development.
+
+## Directory Layout
+
+\`\`\`
+my-extension/
+  packages/
+    extension/                 # Your extension code
+      public/
+        manifest.json          # Extension manifest
+      src/
+        index.tsx              # Entry point
+        store.ts               # Shared state (createStore)
+        surfaces/              # Surface components
+          Header.tsx           # slot.header
+          Content.tsx          # slot.content
+          Footer.tsx           # slot.footer
+        components/            # Feature components
+        lib/                   # API wrappers, utilities
+    preview/                   # Local preview host \u2014 DO NOT MODIFY
+  package.json                 # Workspace root
+  tsconfig.json
+\`\`\`
+
+## Key Files
+
+### manifest.json
+
+The extension manifest declares what the extension needs from the host:
+
+\`\`\`json
+{
+  "name": "My Extension",
+  "version": "0.1.0",
+  "targets": ["slot.header", "slot.content", "slot.footer"],
+  "permissions": ["context:read", "data:fetch"],
+  "allowedDomains": ["api.example.com"]
+}
+\`\`\`
+
+| Field | Purpose |
+|-------|---------|
+| \`name\` | Display name shown to users |
+| \`version\` | Semver version string |
+| \`targets\` | Surface slots the extension renders into |
+| \`permissions\` | Capabilities the extension uses |
+| \`allowedDomains\` | Hostnames for data.fetch requests (exact match, no wildcards) |
+
+### index.tsx \u2014 Entry Point
+
+The entry point bootstraps the extension runtime:
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS.bootstrap}
+\`\`\`
+
+\`createExtension\` handles:
+- Sandboxed iframe communication with the host
+- Capability injection (makes \`useCapabilities()\` work)
+- Surface registration (maps \`<Surface id="...">\` to host layout slots)
+
+**Do not modify \`index.html\`** \u2014 the extension always bootstraps through \`createExtension\`.
+
+### store.ts \u2014 Shared State
+
+The store provides cross-surface state management:
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS.store}
+\`\`\`
+
+All surfaces import from the same store instance. Use \`useStore(appStore, selector)\`
+to read state with minimal re-renders.
+
+### Surface Files
+
+Each surface is a React component in \`src/surfaces/\`:
+
+\`\`\`tsx
+${SURFACE_SNIPPETS[SURFACE_TARGETS.CONTENT]}
+\`\`\`
+
+The \`id\` prop must match a target in \`manifest.json\`.
+
+### Preview Host
+
+The \`packages/preview/\` directory contains a local preview host that simulates
+the production environment. **Do not modify this directory** \u2014 it is pre-configured
+and managed by the SDK tooling.
+
+## Import Conventions
+
+All SDK imports come from two packages:
+
+\`\`\`tsx
+// Runtime: hooks, components, utilities
+import { ui, Surface, createExtension, useCapabilities, createStore, useStore, useContextData }
+  from '@stackable-labs/sdk-extension-react'
+
+// Types and constants (dev-time only)
+import type { ExtensionManifest } from '@stackable-labs/sdk-extension-contracts'
+\`\`\`
+
+Components use the \`ui.*\` namespace \u2014 do not import components directly.
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/generators/styling-and-theming.ts
+var generateStylingAndTheming = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Host theme passthrough, CSS constraints, and styling patterns for extensions",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Styling & Theming
+
+Extensions inherit the host application's theme automatically. The SDK component library
+(\`ui.*\` namespace) renders inside the host's styling context, so colors, fonts, and
+spacing match the host UI without any configuration.
+
+## Host Theme Inheritance
+
+The \`ui.*\` components automatically use the host's design tokens:
+- **Colors** \u2014 text, backgrounds, borders adapt to the host's color scheme
+- **Typography** \u2014 font family, sizes, and weights match the host
+- **Spacing** \u2014 padding and margins follow the host's spacing scale
+- **Dark mode** \u2014 components respond to the host's light/dark mode setting
+
+No CSS or theme configuration is needed in the extension.
+
+## The className Prop
+
+Most \`ui.*\` components accept a \`className\` prop for layout adjustments:
+
+\`\`\`tsx
+<ui.Card className="mt-4">
+  <ui.CardContent className="p-6">
+    <ui.Text className="text-center">Centered text</ui.Text>
+  </ui.CardContent>
+</ui.Card>
+\`\`\`
+
+**Use className for:**
+- Layout (margin, padding, flexbox, grid)
+- Positioning (relative, absolute)
+- Sizing (width, height, max-width)
+- Spacing between elements
+
+**Avoid overriding with className:**
+- Colors and backgrounds (breaks theme consistency)
+- Font families and sizes (breaks typography scale)
+- Border styles (use component variants instead)
+
+## Layout Components
+
+Use the built-in layout components instead of raw CSS:
+
+| Component | Purpose |
+|-----------|---------|
+| \`<ui.Stack>\` | Vertical layout with consistent spacing |
+| \`<ui.Inline>\` | Horizontal layout with consistent spacing |
+| \`<ui.Separator>\` | Visual divider between sections |
+| \`<ui.ScrollArea>\` | Scrollable container for overflow content |
+
+\`\`\`tsx
+<ui.Stack className="gap-4">
+  <ui.Heading level={3}>Section Title</ui.Heading>
+  <ui.Text>Section content</ui.Text>
+  <ui.Separator />
+  <ui.Inline className="gap-2">
+    <ui.Button variant="primary">Save</ui.Button>
+    <ui.Button variant="ghost">Cancel</ui.Button>
+  </ui.Inline>
+</ui.Stack>
+\`\`\`
+
+## Component Variants
+
+Use component props (not CSS) to control visual style:
+
+\`\`\`tsx
+// Buttons \u2014 variant controls appearance
+<ui.Button variant="primary">Primary action</ui.Button>
+<ui.Button variant="ghost">Secondary action</ui.Button>
+
+// Badges \u2014 variant + hue + tone for semantic colors
+<ui.Badge variant="default" hue="blue" tone="strong">Active</ui.Badge>
+<ui.Badge variant="default" hue="red" tone="subtle">Error</ui.Badge>
+
+// Text \u2014 tone for semantic meaning
+<ui.Text tone="subdued">Helper text</ui.Text>
+<ui.Text tone="critical">Error message</ui.Text>
+\`\`\`
+
+## CSS Constraints
+
+Extensions run in a sandboxed iframe. These constraints apply:
+
+- **No global CSS** \u2014 styles don't leak between extensions or into the host
+- **No \`document\` access** \u2014 cannot inject stylesheets or modify the DOM directly
+- **No \`window.location\`** \u2014 cannot read or modify the URL
+- **Component-only styling** \u2014 use \`className\` on \`ui.*\` components, not raw HTML elements
+- **Bundle size limit** \u2014 keep CSS dependencies minimal (under 500KB total bundle)
+
+## Responsive Design
+
+Extensions render in a constrained viewport (the host's sidebar or panel). Design for
+narrow widths:
+
+\`\`\`tsx
+// Use ScrollArea for content that may overflow
+<ui.ScrollArea className="h-[400px]">
+  <ui.Stack className="gap-3">
+    {items.map((item) => (
+      <ItemCard key={item.id} item={item} />
+    ))}
+  </ui.Stack>
+</ui.ScrollArea>
+\`\`\`
+
+- Assume a **narrow viewport** (~300-400px wide)
+- Use \`<ui.ScrollArea>\` for long lists or content
+- Avoid horizontal scrolling \u2014 stack elements vertically
+- Test at the minimum panel width the host supports
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/generators/store-and-navigation.ts
+var generateStoreAndNavigation = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Cross-surface state management with createStore and store-based navigation patterns",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Store & Navigation
+
+Extensions use \`createStore\` for cross-surface state management. The store is shared
+across all surfaces (header, content, footer), enabling coordinated UI updates from
+a single state source.
+
+## Creating a Store
+
+Define your store in \`src/store.ts\`:
+
+\`\`\`tsx
+import { createStore } from '@stackable-labs/sdk-extension-react'
+
+type ViewState = { type: 'list' } | { type: 'detail'; id: string }
+
+interface AppState {
+  viewState: ViewState
+}
+
+export const appStore = createStore<AppState>({
+  viewState: { type: 'list' },
+})
+\`\`\`
+
+## Reading State in Surfaces
+
+Use \`useStore\` with a selector to subscribe to specific slices of state:
+
+\`\`\`tsx
+import { useStore } from '@stackable-labs/sdk-extension-react'
+import { appStore } from '../store'
+
+export const Content = () => {
+  const viewState = useStore(appStore, (s) => s.viewState)
+
+  if (viewState.type === 'list') {
+    return <ListView onSelect={(id) => appStore.set({ viewState: { type: 'detail', id } })} />
+  }
+  return <DetailView id={viewState.id} onBack={() => appStore.set({ viewState: { type: 'list' } })} />
+}
+\`\`\`
+
+## Store-Based Navigation
+
+Use discriminated unions for view state instead of string constants or URL routing.
+The store replaces traditional routing \u2014 there are no URLs inside the sandbox.
+
+### View State Pattern
+
+\`\`\`tsx
+// Define all possible views as a discriminated union
+type ViewState =
+  | { type: 'list' }
+  | { type: 'detail'; id: string }
+  | { type: 'edit'; id: string }
+  | { type: 'create' }
+
+// TypeScript narrows the type based on the discriminant
+switch (viewState.type) {
+  case 'list':    return <ListView />
+  case 'detail':  return <DetailView id={viewState.id} />
+  case 'edit':    return <EditView id={viewState.id} />
+  case 'create':  return <CreateView />
+}
+\`\`\`
+
+### Cross-Surface Coordination
+
+The header can show context based on what the content surface displays:
+
+\`\`\`tsx
+// Header surface \u2014 shows back button when on detail view
+export const Header = () => {
+  const viewState = useStore(appStore, (s) => s.viewState)
+
+  return (
+    <Surface id="slot.header">
+      <ui.Inline>
+        {viewState.type !== 'list' && (
+          <ui.Button
+            variant="ghost"
+            onClick={() => appStore.set({ viewState: { type: 'list' } })}
+          >
+            Back
+          </ui.Button>
+        )}
+        <ui.Heading level={3}>
+          {viewState.type === 'list' ? 'All Items' : 'Item Detail'}
+        </ui.Heading>
+      </ui.Inline>
+    </Surface>
+  )
+}
+\`\`\`
+
+## Selector Performance
+
+Use narrow selectors to minimize re-renders. Each \`useStore\` call only
+triggers a re-render when its selected value changes:
+
+\`\`\`tsx
+// Good \u2014 component only re-renders when viewState changes
+const viewState = useStore(appStore, (s) => s.viewState)
+
+// Bad \u2014 component re-renders on ANY state change
+const state = useStore(appStore, (s) => s)
+\`\`\`
+
+## Best Practices
+
+- **One store per extension** \u2014 define in \`src/store.ts\`, import everywhere
+- **Discriminated unions for views** \u2014 TypeScript can narrow the type and catch missing cases
+- **Narrow selectors** \u2014 select only what the component needs
+- **Use \`appStore.set()\`** \u2014 update state directly via \`appStore.set({ viewState: ... })\` from any component
+- **No URL routing** \u2014 the extension runs in a sandboxed iframe with no URL bar
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/generators/cookbook-capabilities.ts
+var generateCookbookCapabilities = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Cookbook: data.query, data.fetch, context.read, actions.toast, actions.invoke capability examples",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Capability Examples
+
+Focused examples showing each SDK capability in a working Surface component.
+Each example is self-contained \u2014 copy it into a surface file and add the
+corresponding permission to your \`manifest.json\`.
+
+## context.read \u2014 Reading Host Context
+
+Read customer and session data provided by the host. The \`useContextData\`
+hook handles loading state automatically.
+
+**Permission:** \`context:read\`
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["context.read"]}
+\`\`\`
+
+## data.query \u2014 Host-Mediated Requests
+
+Send structured requests to the host application. The host handles the API
+call and returns the result \u2014 no \`allowedDomains\` needed.
+
+**Permission:** \`data:query\`
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["data.query"]}
+\`\`\`
+
+## data.fetch \u2014 Direct HTTP Requests
+
+Make HTTP requests directly from the extension sandbox. The domain must be
+listed in \`allowedDomains\` in your manifest.
+
+**Permission:** \`data:fetch\`
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["data.fetch"]}
+\`\`\`
+
+## actions.toast \u2014 Toast Notifications
+
+Display toast notifications in the host UI to provide feedback to users.
+
+**Permission:** \`actions:toast\`
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["actions.toast"]}
+\`\`\`
+
+## actions.invoke \u2014 Host Actions
+
+Trigger host-defined actions like starting conversations, setting tags, or
+updating custom fields.
+
+**Permission:** \`actions:invoke\`
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["actions.invoke"]}
+\`\`\`
+`;
+};
+var generateCookbookStructural = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Cookbook: extension bootstrap, surface declaration, store navigation, and loading patterns",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Structural Patterns
+
+Focused examples for the foundational patterns every extension uses: bootstrapping,
+surfaces, store-based navigation, and loading states.
+
+## Bootstrap \u2014 Entry Point
+
+Set up your extension entry point in \`src/index.tsx\`. The \`createExtension\` factory
+bootstraps the sandboxed runtime and registers all surfaces with the host.
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS.bootstrap}
+\`\`\`
+
+## Surfaces \u2014 Declaring UI Slots
+
+Each surface renders into a specific layout slot in the host application.
+The \`id\` prop must match a target declared in your \`manifest.json\`.
+
+### Header
+
+\`\`\`tsx
+${SURFACE_SNIPPETS[SURFACE_TARGETS.HEADER]}
+\`\`\`
+
+### Content
+
+\`\`\`tsx
+${SURFACE_SNIPPETS[SURFACE_TARGETS.CONTENT]}
+\`\`\`
+
+### Footer
+
+\`\`\`tsx
+${SURFACE_SNIPPETS[SURFACE_TARGETS.FOOTER]}
+\`\`\`
+
+### Footer Links
+
+\`\`\`tsx
+${SURFACE_SNIPPETS[SURFACE_TARGETS.FOOTER_LINKS]}
+\`\`\`
+
+## Store \u2014 Cross-Surface State & Navigation
+
+Extensions use \`createStore\` for shared state across surfaces. The store replaces
+traditional URL routing \u2014 there are no URLs inside the sandbox. Use discriminated
+unions for view state to get exhaustive type checking.
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS.store}
+\`\`\`
+
+## Loading States & Guards
+
+Handle loading states and missing context gracefully. Always show a skeleton
+while context loads, and guard against missing data before rendering.
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS.loading}
+\`\`\`
+
+## Surface Context
+
+Read host-pushed context for a specific surface using the lower-level
+\`useSurfaceContext\` hook.
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS.surfaceContext}
+\`\`\`
+`;
+};
+var identityEventTypes3 = Object.values(IDENTITY_EVENTS).map((e) => `\`${e}\``).join(", ");
+var activityEventTypes3 = Object.values(ACTIVITY_EVENTS).map((e) => `\`${e}\``).join(", ");
+var generateCookbookEvents = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Cookbook: identity, messaging, and activity event subscriptions + extend identity",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Events & Extensions
+
+Subscribe to real-time events pushed from the host 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:** ${identityEventTypes3}
+
+### Hook usage
+
+\`\`\`tsx
+${HOOK_SNIPPETS["events:identity"]}
+\`\`\`
+
+### Full component example
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["events:identity"]}
+\`\`\`
+
+## Messaging Events
+
+Subscribe to postback button clicks from the Zendesk messaging widget.
+The \`actionName\` is the button's display text, not a programmatic identifier.
+
+**Permission:** \`events:messaging\`
+
+### Hook usage
+
+\`\`\`tsx
+${HOOK_SNIPPETS["events:messaging"]}
+\`\`\`
+
+### Full component example
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["events:messaging"]}
+\`\`\`
+
+## Activity Events
+
+Subscribe to host activity events like page views, clicks, and purchases.
+Activity event names are domain-stripped \u2014 use \`useActivityEvent('product_view', ...)\`
+not \`'activity:product_view'\`.
+
+**Permission:** \`events:activity\`
+**Well-known events:** ${activityEventTypes3}
+
+### Hook usage
+
+\`\`\`tsx
+${HOOK_SNIPPETS["events:activity"]}
+\`\`\`
+
+### Full component example
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["events:activity"]}
+\`\`\`
+
+## Extend Identity
+
+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.
+
+**Permission:** \`extend:identity\`
+
+### Hook usage
+
+\`\`\`tsx
+${HOOK_SNIPPETS["extend.identity"]}
+\`\`\`
+
+### Full component example
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["extend.identity"]}
+\`\`\`
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/commands/add-surface.ts
+var generateAddSurfaceCommand = () => {
+  const fm = frontmatter({
+    description: "Add a new surface (UI slot) to this Stackable extension",
+    targets: ["*"]
+  });
+  return `${fm}
+
+# Add a New Surface
+
+Add a new surface to this extension. Follow these steps exactly:
+
+## 1. Determine the target slot
+Ask which target slot this surface is for. Valid targets:
+- \`slot.header\` \u2014 appears at the top of the extension area
+- \`slot.content\` \u2014 main content area
+- \`slot.footer\` \u2014 bottom of the extension area
+- \`slot.footer-links\` \u2014 footer link row
+
+## 2. Create the surface file
+Create a new file in \`packages/extension/src/surfaces/\` named after the slot
+(e.g., \`Header.tsx\`, \`Content.tsx\`, \`Footer.tsx\`).
+
+Use this template:
+\`\`\`tsx
+import { Surface, useCapabilities, useContextData } from '@stackable-labs/sdk-extension-react'
+import { ui } from '@stackable-labs/sdk-extension-react'
+
+export const [SurfaceName] = () => {
+  return (
+    <Surface id="[target]">
+      {/* Surface content here */}
+    </Surface>
+  )
+}
+\`\`\`
+
+If the surface needs state management, import and use the existing store from \`../store\`.
+
+## 3. Register the surface in index.tsx
+Import the new surface component and add it to the \`createExtension\` factory function
+alongside existing surfaces.
+
+## 4. Update manifest.json
+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.footer\` \u2192 (none)
+- \`slot.footer-links\` \u2192 (none)
+
+Only add permissions that aren't already declared.
+
+## 5. Verify
+- Confirm the surface renders by checking the import chain: index.tsx \u2192 Surface component \u2192 Surface id matches manifest target
+- Confirm manifest.json is valid JSON with no duplicate targets or permissions
+`;
+};
+
+// ../../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",
+    targets: ["*"]
+  });
+  return `${fm}
+
+# Add a Capability
+
+Wire up a new capability in this extension. Follow these steps exactly:
+
+## 1. Determine the capability
+Ask which capability to add. Valid capabilities:
+- \`data.query\` \u2014 host-mediated data requests (action name + params \u2192 host returns data)
+- \`data.fetch\` \u2014 direct HTTP requests from the sandbox (requires allowedDomains)
+- \`context.read\` \u2014 read host-provided context (customerId, customerEmail, 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
+- \`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)
+
+## 2. Add permission to manifest.json
+Add the corresponding permission to \`packages/extension/public/manifest.json\`:
+- \`data.query\` \u2192 \`"data:query"\`
+- \`data.fetch\` \u2192 \`"data:fetch"\`
+- \`context.read\` \u2192 \`"context:read"\`
+- \`actions.toast\` \u2192 \`"actions:toast"\`
+- \`actions.invoke\` \u2192 \`"actions:invoke"\`
+- \`extend:identity\` \u2192 \`"extend:identity"\`
+- \`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"]\`)
+
+Only add if not already declared.
+
+**Note:** Identity state is available via \`context.read()\` \u2192 \`identity\` field (requires \`context:read\`, no separate permission).
+
+## 3. If data.fetch \u2014 add allowedDomains
+Ask for the API domain(s) and add them to the \`allowedDomains\` array in manifest.json.
+
+## 4. If data.fetch \u2014 create API wrapper
+Create \`packages/extension/src/lib/api.ts\` with the API wrapper pattern:
+\`\`\`tsx
+type FetchFn = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>
+
+export function createApi(fetch: FetchFn) {
+  return {
+    async getData(): Promise<DataType> {
+      const result = await fetch('https://api.example.com/data', { method: 'GET' })
+      if (!result.ok) throw new Error(\`Request failed: \${result.status}\`)
+      return result.data as DataType
+    },
+  }
+}
+\`\`\`
+
+## 5. Use the capability in a surface
+
+### For data.*, context.*, and actions.* capabilities \u2014 use \`useCapabilities()\`:
+\`\`\`tsx
+import { useCapabilities } from '@stackable-labs/sdk-extension-react'
+
+const capabilities = useCapabilities()
+// data.query:    capabilities.data.query({ action: 'getItems', ... })
+// data.fetch:    const api = createApi(capabilities.data.fetch)
+// context.read:  capabilities.context.read()  (or use useContextData() hook)
+// actions.toast: capabilities.actions.toast({ message: 'Done!', type: 'success' })
+// 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.
+
+\`\`\`tsx
+// events:identity \u2014 use useIdentityEvent hook
+${HOOK_SNIPPETS["events:identity"]}
+\`\`\`
+
+\`\`\`tsx
+// events:messaging \u2014 use useMessagingEvent hook
+${HOOK_SNIPPETS["events:messaging"]}
+\`\`\`
+
+\`\`\`tsx
+// events:activity \u2014 use useActivityEvent hook
+${HOOK_SNIPPETS["events:activity"]}
+\`\`\`
+
+\`\`\`tsx
+// extend:identity \u2014 use useExtendIdentity hook
+${HOOK_SNIPPETS["extend.identity"]}
+\`\`\`
+
+## 6. Verify
+- Confirm the permission is in manifest.json
+- 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
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/commands/add-component.ts
+var generateAddComponentCommand = () => {
+  const fm = frontmatter({
+    description: "Add a UI component to this Stackable extension",
+    targets: ["*"]
+  });
+  return `${fm}
+
+# Add a UI Component
+
+Add a UI component to this extension. Follow these steps:
+
+## 1. Identify the component
+All UI components use the \`ui.*\` namespace from \`@stackable-labs/sdk-extension-react\`.
+
+**Available components by category:**
+- **Layout:** Card, CardContent, CardHeader, Stack, Inline, Separator, ScrollArea
+- **Text:** Text, Heading, Badge
+- **Input:** Button, Input, Textarea, Select, SelectOption, Checkbox, Switch, Label, RadioGroup, RadioGroupItem
+- **Feedback:** Skeleton, Tooltip, Progress, Alert
+- **Navigation:** Tabs, TabsList, TabsTrigger, TabsContent, Link, Menu, MenuItem
+- **Composite:** Collapsible, CollapsibleTrigger, CollapsibleContent, Avatar, Icon
+
+## 2. Place the component
+- Insert inside an existing \`<Surface>\` block \u2014 never outside a Surface
+- Place in a logical position within the existing UI structure
+- For compound components, include their required children:
+  - **Card** \u2192 CardContent (and optionally CardHeader)
+  - **Tabs** \u2192 TabsList + TabsTrigger(s) + TabsContent(s)
+  - **Select** \u2192 SelectOption(s)
+  - **Menu** \u2192 MenuItem(s)
+  - **Collapsible** \u2192 CollapsibleTrigger + CollapsibleContent
+  - **RadioGroup** \u2192 RadioGroupItem(s) + Label(s)
+
+## 3. Import
+Ensure \`ui\` is imported from \`@stackable-labs/sdk-extension-react\`. It usually already is.
+No additional imports needed \u2014 all components are accessed via \`ui.ComponentName\`.
+
+## 4. Constraints
+- Do not remove or change any existing code \u2014 only add the new component
+- Do not add components outside of a Surface
+- Do not use raw HTML elements \u2014 only \`ui.*\` components are allowed in the sandbox
+- Child-only tags (CardContent, CardHeader, SelectOption, TabsList, TabsTrigger, TabsContent,
+  RadioGroupItem, CollapsibleTrigger, CollapsibleContent, MenuItem) must be nested inside
+  their parent \u2014 never standalone
+`;
+};
+var generateValidateExtensionCommand = () => {
+  const fm = frontmatter({
+    description: "Validate this extension for common errors before deploying (manifest, permissions, surfaces, imports)",
+    targets: ["*"]
+  });
+  return `${fm}
+
+# Validate Extension
+
+Check this extension for common errors before deploying. Run through each check
+and report all issues found.
+
+## 1. Manifest validation
+Read \`packages/extension/public/manifest.json\` and verify:
+- [ ] Valid JSON
+- [ ] \`name\` is a non-empty string
+- [ ] \`version\` follows semver (e.g., "1.0.0")
+- [ ] \`targets\` is a non-empty array of valid target strings (slot.header, slot.content, slot.footer, slot.footer-links)
+- [ ] \`permissions\` contains only valid permission strings (${PERMISSIONS.join(", ")})
+- [ ] \`allowedDomains\` is an array (can be empty if data:fetch is not used)
+- [ ] If \`data:fetch\` permission is declared, \`allowedDomains\` is not empty
+
+## 2. Permission-to-usage matching
+Scan all \`.tsx\` files in \`packages/extension/src/\` for capability usage:
+- \`capabilities.data.query\` or \`data.query\` \u2192 needs \`data:query\` permission
+- \`capabilities.data.fetch\` or \`data.fetch\` \u2192 needs \`data:fetch\` permission
+- \`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
+- \`useIdentityEvent\` \u2192 needs \`events:identity\` permission (also check manifest \`events\` array has matching entries)
+- \`useMessagingEvent\` \u2192 needs \`events:messaging\` permission (also check manifest \`events\` array has matching entries)
+- \`useActivityEvent\` \u2192 needs \`events:activity\` permission (also check manifest \`events\` array has matching entries)
+
+Report:
+- **Missing permissions:** capabilities used in code but not declared in manifest
+- **Unused permissions:** permissions declared in manifest but not used in code
+
+## 3. Surface-to-target matching
+- Each \`.tsx\` file with a \`<Surface id="...">\` should have a matching target in manifest.json
+- Each target in manifest.json should have a corresponding Surface component
+
+## 4. Import validation
+Verify that:
+- [ ] UI components are imported via \`ui.*\` namespace from \`@stackable-labs/sdk-extension-react\`
+- [ ] No direct imports of \`document\`, \`window.location\`, or other browser globals
+- [ ] No modifications to \`packages/preview/\` directory
+- [ ] Entry point is \`src/index.tsx\` using \`createExtension\`
+
+## 5. Summary
+Print a summary: total issues found, categorized by severity (error vs warning).
+Errors must be fixed before deploying. Warnings are recommendations.
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/skills.ts
+var SKILLS = [
+  // ── Knowledge skills ──────────────────────────────────────────
+  {
+    id: "overview",
+    description: "Stackable Labs Extension SDK overview, packages, import conventions, and project structure. Use when starting a new extension, asking about the SDK, or needing architectural context.",
+    type: "knowledge",
+    content: () => generateOverview(),
+    references: {
+      "core.md": () => generateCoreReference()
+    }
+  },
+  {
+    id: "components",
+    description: "UI component catalog with allowed attributes per tag and available icon names. Use when building extension UI, looking up component attributes, or asking about available components.",
+    type: "knowledge",
+    content: () => generateComponents(),
+    references: {
+      "icons.md": () => generateIconReference()
+    }
+  },
+  {
+    id: "capabilities",
+    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke. Use when wiring up host-mediated APIs or direct HTTP requests.",
+    type: "knowledge",
+    content: () => generateCapabilities()
+  },
+  {
+    id: "permissions",
+    description: "Permission strings, capability-to-permission mapping, and target conventions. Use when configuring manifest.json or debugging permission errors.",
+    type: "knowledge",
+    content: () => generatePermissions()
+  },
+  {
+    id: "hooks-api",
+    description: "Extension hooks and API reference: createExtension, Surface, useCapabilities, createStore, useContextData. Use when writing extension runtime code.",
+    type: "knowledge",
+    content: () => generateHooksAndApi()
+  },
+  {
+    id: "guardrails",
+    description: "SDK constraints and rules that must always be followed: sandbox restrictions, component usage, manifest requirements, entry point rules. Use as a checklist when writing or reviewing extension code.",
+    type: "knowledge",
+    scopes: ["studio", "registry"],
+    content: () => generateGuardrails()
+  },
+  {
+    id: "patterns",
+    description: "Code patterns extracted from the reference extension: entry point, store navigation, surface composition, API wrapper. Use when implementing common extension patterns.",
+    type: "knowledge",
+    content: () => generatePatterns()
+  },
+  {
+    id: "recipes",
+    description: "Reference code examples from the template extension source. Use when looking for working examples of store management, content surfaces, or API wrappers.",
+    type: "knowledge",
+    content: () => generateRecipes()
+  },
+  {
+    id: "suggestions",
+    description: "Contextual suggestion patterns for recommending next steps based on current extension code, capabilities, and surfaces. Use when deciding what to suggest after making changes.",
+    type: "knowledge",
+    scopes: ["studio"],
+    content: () => generateSuggestions()
+  },
+  // ── Dual-use knowledge skills (studio + docs) ────────────────
+  {
+    id: "surfaces",
+    description: "Surface types, lifecycle, layout slots, and multi-surface composition. Use when adding or configuring surfaces in an extension.",
+    type: "knowledge",
+    content: () => generateSurfaces()
+  },
+  {
+    id: "external-apis",
+    description: "Direct HTTP requests via data.fetch, allowedDomains configuration, and API wrapper patterns. Use when connecting an extension to external APIs.",
+    type: "knowledge",
+    content: () => generateExternalApis()
+  },
+  {
+    id: "store-and-navigation",
+    description: "Cross-surface state management with createStore, useStore selectors, and store-based navigation patterns. Use when managing shared state or view navigation.",
+    type: "knowledge",
+    content: () => generateStoreAndNavigation()
+  },
+  {
+    id: "styling-and-theming",
+    description: "Host theme inheritance, className usage, layout components, and CSS constraints. Use when styling extension UI or working with the host theme.",
+    type: "knowledge",
+    content: () => generateStylingAndTheming()
+  },
+  // ── Docs-only knowledge skills ──────────────────────────────
+  {
+    id: "quick-start",
+    description: "Step-by-step guide to create, develop, and deploy your first Stackable extension.",
+    type: "action",
+    scopes: ["docs"],
+    content: () => generateQuickStart()
+  },
+  {
+    id: "project-structure",
+    description: "Extension project file structure, entry point, surfaces, store, and manifest configuration.",
+    type: "knowledge",
+    scopes: ["docs"],
+    content: () => generateProjectStructure()
+  },
+  {
+    id: "cli-reference",
+    description: "CLI commands for creating, developing, validating, and deploying Stackable extensions.",
+    type: "knowledge",
+    scopes: ["docs"],
+    content: () => generateCliReference()
+  },
+  {
+    id: "extension-studio",
+    description: "Extension Studio: in-browser builder with AI assistant, component palette, and live preview. Use when learning about Studio or comparing Studio vs CLI workflows.",
+    type: "knowledge",
+    scopes: ["docs"],
+    content: () => generateExtensionStudio()
+  },
+  // ── Cookbook skills (docs-only) ────────────────────────────────
+  {
+    id: "cookbook-structural",
+    description: "Cookbook: extension bootstrap, surface declaration, store navigation, and loading patterns.",
+    type: "knowledge",
+    scopes: ["docs"],
+    content: () => generateCookbookStructural()
+  },
+  {
+    id: "cookbook-capabilities",
+    description: "Cookbook: data.query, data.fetch, context.read, actions.toast, actions.invoke capability examples.",
+    type: "knowledge",
+    scopes: ["docs"],
+    content: () => generateCookbookCapabilities()
+  },
+  {
+    id: "cookbook-events",
+    description: "Cookbook: identity, messaging, and activity event subscriptions + extend identity.",
+    type: "knowledge",
+    scopes: ["docs"],
+    content: () => generateCookbookEvents()
+  },
+  // ── Action skills ─────────────────────────────────────────────
+  {
+    id: "add-surface",
+    description: "Add a new surface (UI slot) to this Stackable extension. Use when the user wants to add a header, content, footer, or footer-links surface.",
+    type: "action",
+    content: () => generateAddSurfaceCommand()
+  },
+  {
+    id: "add-capability",
+    description: "Wire up a new capability (data.fetch, data.query, context.read, actions.toast, actions.invoke) in this extension. Use when adding a new host-mediated API.",
+    type: "action",
+    content: () => generateAddCapabilityCommand()
+  },
+  {
+    id: "add-component",
+    description: "Add a UI component (ui.Card, ui.Button, ui.Tabs, etc.) to this extension. Use when the user wants to add a visual element.",
+    type: "action",
+    content: () => generateAddComponentCommand()
+  },
+  {
+    id: "validate",
+    description: "Validate this extension for common errors before deploying: manifest, permissions, surfaces, imports. Use before publishing or when debugging issues.",
+    type: "action",
+    content: () => generateValidateExtensionCommand()
+  }
+];
+
+// ../../../node_modules/.pnpm/ultramatter@0.0.4/node_modules/ultramatter/dist/index.js
+function b(t) {
+  let e = 0, r = "default", i = [];
+  for (let n = 0; n < t.length; n++) {
+    if (t[n] === "-") if (e === 0) if (r === "default" && n == 0 || r === "open" && t[n - 1] === `
+`) e = 1;
+    else continue;
+    else e++;
+    else e = 0;
+    e === 3 && (r = r === "default" ? "open" : "closed", i.push(n + 1));
+  }
+  switch (r) {
+    case "default":
+      return ["", t];
+    case "open":
+      return ["", t];
+    case "closed":
+      return [t.slice(i[0], i[1] - 3).trim(), t.slice(i[1]).trimStart()];
+  }
+}
+var h = (t) => t.slice(0, t.length - t.trimStart().length);
+var a = (t) => {
+  let e = h(t);
+  return t.split(`
+`).map((r) => r.slice(e.length)).join(`
+`);
+};
+var E = (t) => {
+  if (t[0] === '"' || t[0] === "'") {
+    let e = t[0];
+    if (t[t.length - 1] === e) return t.slice(1, -1);
+  }
+  return t;
+};
+var d = (t) => t === "true" || t === "false" ? t === "true" : Number.isNaN(Number(t)) ? E(t) : Number(t);
+var o = (t) => {
+  let e = /(^[^\:\s]+):(?!\/)\n?([\s\S]*?(?=^\S)|[\s\S]*$)/gm, r = /[\:\-\[\]\|\#]/gm, i = /#.*$/gm, n = h(t);
+  if (!r.test(t)) return n.length > 1 ? a(t) : d(t.trim());
+  n.length <= 1 && (t = t.trimStart());
+  let f, l = {};
+  for (; f = e.exec(t); ) {
+    let [m, c, g] = f;
+    if (h(g).length > 1) {
+      let u = a(g);
+      l[c] = o(u);
+    } else l[c] = o(g);
+  }
+  if (Object.keys(l).length > 0) return l;
+  let s = t.trim().replace(i, "").trim();
+  return s.startsWith("-") ? s.split(/^\-/gm).filter((c) => c).map((c) => o(c.trimEnd())) : s.startsWith("[") ? (s = s.slice(1, -1), s.split(",").map((m) => d(m.trim()))) : s.startsWith("|") ? a(s.replace("|", "").replace(`
+`, "")) : d(s.trim());
+};
+function R(t) {
+  let [e, r] = b(t);
+  return e ? { frontmatter: o(e), content: r } : { content: r };
+}
+
+// ../../sdk/extension/ai-docs/src/skill-loader.ts
+var listSkills = (scope) => SKILLS.filter((s) => !s.scopes || s.scopes.includes(scope));
+var getSkillBody = (skill) => {
+  const raw = skill.content();
+  const { content } = R(raw);
+  return content.trim();
+};
+var getSkillMetadata = (skill) => ({ id: skill.id, description: skill.description });
+var lookupSkill = (skills, id) => {
+  const skill = skills.find((s) => s.id === id);
+  if (!skill) {
+    return null;
+  }
+  return getSkillBody(skill);
+};
+var findRelevantSkills = (skills, query) => {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (terms.length === 0) {
+    return [];
+  }
+  return skills.filter((skill) => {
+    const text = `${skill.id} ${skill.description}`.toLowerCase();
+    return terms.some((term) => text.includes(term));
+  });
+};
+
+// ../../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": `
+const capabilities = useCapabilities()
+const ctx = await capabilities.context.read()
+`,
+  "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'
+import { Header } from './surfaces/Header'
+import { Content } from './surfaces/Content'
+import { Footer } from './surfaces/Footer'
+
+const Extension = () => (
+  <>
+    <Header />
+    <Content />
+    <Footer />
+  </>
+)
+
+// NOTE: extensionId is optional \u2014 used when connected to a registered extension
+createExtension(() => <Extension />, { extensionId: 'my-extension' })`,
+  "surfaces": `import { Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Header() {
+  return (
+    <Surface id="slot.header">
+      <ui.Stack direction="column" gap="2" className="p-3">
+        <ui.Text className="text-sm font-medium">Hello from slot.header</ui.Text>
+      </ui.Stack>
+    </Surface>
+  )
+}
+
+export function Content() {
+  return (
+    <Surface id="slot.content">
+      <ui.Stack direction="column" gap="3" className="p-4">
+        <ui.Heading level="3">Content Surface</ui.Heading>
+        <ui.Text>Rendered inside the host at slot.content.</ui.Text>
+      </ui.Stack>
+    </Surface>
+  )
+}`,
+  "store": `import { createStore, useStore, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+// store.ts
+
+export const appStore = createStore({
+  viewState: { type: 'list' },
+})
+
+// Content.tsx
+export function Content() {
+  const viewState = useStore(appStore, (s) => s.viewState)
+
+  const goToDetail = (id) => appStore.set({ viewState: { type: 'detail', id } })
+  const goBack = () => appStore.set({ viewState: { type: 'list' } })
+
+  return (
+    <Surface id="slot.content">
+      {viewState.type === 'list' && (
+        <ui.Button onClick={() => goToDetail('abc123')}>View Detail</ui.Button>
+      )}
+      {viewState.type === 'detail' && (
+        <ui.Stack direction="column" gap="2">
+          <ui.Text>Viewing: {viewState.id}</ui.Text>
+          <ui.Button onClick={goBack}>Back</ui.Button>
+        </ui.Stack>
+      )}
+    </Surface>
+  )
+}`,
+  "loading": `import { useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Content() {
+  const { loading, customerId } = useContextData()
+
+  if (loading) {
+    return (
+      <Surface id="slot.content">
+        <ui.Skeleton />
+      </Surface>
+    )
+  }
+
+  if (!customerId) {
+    return (
+      <Surface id="slot.content">
+        <ui.Stack direction="column" gap="1" className="p-4 items-center">
+          <ui.Icon name="user" size="sm" />
+          <ui.Text className="text-xs text-muted-foreground">No customer selected</ui.Text>
+        </ui.Stack>
+      </Surface>
+    )
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Text className="text-sm">Customer: {customerId}</ui.Text>
+    </Surface>
+  )
+}`,
+  "surfaceContext": `import { useSurfaceContext, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Header() {
+  // Lower-level hook \u2014 reads host-pushed context for this specific surface
+  const context = useSurfaceContext()
+
+  return (
+    <Surface id="slot.header">
+      <ui.Text className="text-xs">{context.customerId ?? 'No customer'}</ui.Text>
+    </Surface>
+  )
+}`,
+  "context.read": `import { useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Header() {
+  const { loading, customerId, customerEmail } = useContextData()
+
+  if (loading) {
+    return (
+      <Surface id="slot.header">
+        <ui.Text className="text-xs text-muted-foreground">Loading...</ui.Text>
+      </Surface>
+    )
+  }
+
+  return (
+    <Surface id="slot.header">
+      <ui.Stack direction="column" gap="1">
+        <ui.Text className="text-xs font-semibold">{customerEmail}</ui.Text>
+        <ui.Text className="text-xs text-muted-foreground">ID: {customerId}</ui.Text>
+      </ui.Stack>
+    </Surface>
+  )
+}`,
+  "data.query": `import { useCapabilities, Surface, ui } from '@stackable-labs/sdk-extension-react'
+import { useState } from 'react'
+
+export function Content() {
+  const capabilities = useCapabilities()
+  const [data, setData] = useState(null)
+
+  const handleQuery = async () => {
+    const payload = {
+      action: 'getCustomer',
+      customerId: '123',
+    }
+    const result = await capabilities.data.query(payload)
+    setData(result)
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Button onClick={handleQuery}>Fetch Data</ui.Button>
+    </Surface>
+  )
+}`,
+  "data.fetch": `import { useCapabilities, Surface, ui } from '@stackable-labs/sdk-extension-react'
+import { useState } from 'react'
+
+export function Content() {
+  const capabilities = useCapabilities()
+  const [data, setData] = useState(null)
+
+  const handleGet = async () => {
+    const result = await capabilities.data.fetch('https://api.myservice.com/orders')
+    if (result.ok) setData(result.data)
+  }
+
+  const handlePost = async () => {
+    const result = await capabilities.data.fetch(
+      'https://api.myservice.com/orders',
+      { method: 'POST', body: { limit: 10 } }
+    )
+    if (result.ok) setData(result.data)
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Stack gap="2">
+        <ui.Button onClick={handleGet}>GET Orders</ui.Button>
+        <ui.Button onClick={handlePost}>POST Orders</ui.Button>
+      </ui.Stack>
+    </Surface>
+  )
+}`,
+  "actions.toast": `import { useCapabilities, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Content() {
+  const capabilities = useCapabilities()
+
+  const showToast = async () => {
+    await capabilities.actions.toast({ type: 'success', message: 'Done!' })
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Button onClick={showToast}>Show Toast</ui.Button>
+    </Surface>
+  )
+}`,
+  "actions.invoke": `import { useCapabilities, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+export function Content() {
+  const capabilities = useCapabilities()
+
+  const newConversation = async () => {
+    await capabilities.actions.invoke('newConversation', {
+      tags: ['stackable', 'order-lookup'],
+      fields: [{ id: 'stackable_action', value: 'order_status' }],
+      metadata: { orderId: '12345' },
+    })
+  }
+
+  const setTags = async () => {
+    await capabilities.actions.invoke('setConversationTags', ['escalated', 'order-issue'])
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Stack gap="2">
+        <ui.Button onClick={newConversation}>New Conversation</ui.Button>
+        <ui.Button onClick={setTags}>Set Tags</ui.Button>
+      </ui.Stack>
+    </Surface>
+  )
+}`,
+  "extend.identity": `import { useExtendIdentity } 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'
+
+export function Header() {
+  const [user, setUser] = useState(null)
+
+  useIdentityEvent('login', (event) => {
+    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 { useState } from 'react'
+
+export function Content() {
+  const [lastPostback, setLastPostback] = useState(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 { useState } from 'react'
+
+export function Content() {
+  const [lastEvent, setLastEvent] = useState(null)
+
+  useActivityEvent('page_view', (event) => {
+    setLastEvent(event.data.url)
+  })
+
+  return (
+    <Surface id="slot.content">
+      <ui.Text className="text-xs">{lastEvent ?? 'No activity yet'}</ui.Text>
+    </Surface>
+  )
+}`
+};
+
+// ../../sdk/extension/ai-docs/src/generated/capability-snippets-jsx.ts
+var CAPABILITY_SNIPPETS2 = {
+  "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": `const capabilities = useCapabilities()
+const ctx = await capabilities.context.read()`,
+  "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": `import { useIdentityEvent } from '@stackable-labs/sdk-extension-react'
+
+useIdentityEvent('login', (event) => {
+  console.log('User logged in:', event.data.state.user?.email)
+})
+useIdentityEvent('logout', () => {
+  console.log('User logged out')
+})`,
+  "events:messaging": `import { useMessagingEvent } from '@stackable-labs/sdk-extension-react'
+
+useMessagingEvent('postback:Buy Now', (event) => {
+  console.log('Postback:', event.data.actionName, event.data.conversationId)
+})`,
+  "events:activity": `import { useActivityEvent } from '@stackable-labs/sdk-extension-react'
+
+useActivityEvent('product_view', (event) => {
+  console.log('Activity:', event.eventName, event.data)
+})`,
+  "extend.identity": `import { useExtendIdentity } from '@stackable-labs/sdk-extension-react'
+
+useExtendIdentity((claims) => ({
+  external_id: \`custom_\${claims.external_id}\`,
+  loyalty_tier: 'gold',
+}))`
+};
+var EVENT_SNIPPETS2 = {
+  "events:identity": `import { useIdentityEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'
+import { useState } from 'react'
+
+export function Header() {
+  const [user, setUser] = useState(null)
+
+  useIdentityEvent('login', (event) => {
+    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 { useState } from 'react'
+
+export function Content() {
+  const [lastPostback, setLastPostback] = useState(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 { useState } from 'react'
+
+export function Content() {
+  const [lastEvent, setLastEvent] = useState(null)
+
+  useActivityEvent('page_view', (event) => {
+    setLastEvent(event.data.url)
+  })
+
+  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'
+
+// 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/index.ts
+var pair = (tsx, jsx) => Object.fromEntries(Object.entries(tsx).map(([k, v]) => [k, { tsx: v, jsx: jsx[k] ?? v }]));
+pair(EXAMPLE_SNIPPETS, EXAMPLE_SNIPPETS2);
+pair(CAPABILITY_SNIPPETS, CAPABILITY_SNIPPETS2);
+pair(EVENT_SNIPPETS, EVENT_SNIPPETS2);
+
+// ../../lib/contracts/src/permissions.ts
+var SUPER_ROLE = {
+  ADMIN: "org:super_admin"
+};
+var ORG_ROLE = {
+  ADMIN: "org:admin",
+  OWNER: "org:owner"};
+var EDITOR_ROLES = [
+  SUPER_ROLE.ADMIN,
+  ORG_ROLE.ADMIN,
+  ORG_ROLE.OWNER
+];
+[
+  ...Object.values(SUPER_ROLE),
+  ...Object.values(EDITOR_ROLES)
+];
+
+// ../../lib/utils-services/src/auth/index.ts
+var STANDALONE_CLIENT = {
+  MCP: "@stackable-labs/mcp-app-extension"
+};
+
+// package.json
+var package_default = {
+  version: "0.0.0"};
+
+// src/server.ts
+var MCP_CLIENT_NAME = STANDALONE_CLIENT.MCP;
+var DEFAULT_ADMIN_API_URL = "https://api-use1.stackablelabs.io/admin";
+var textContent = (text) => ({ content: [{ type: "text", text }] });
+var errorContent = (text) => ({ content: [{ type: "text", text }], isError: true });
+var createMcpServer = (options = {}) => {
+  const server = new McpServer({
+    name: "stackable-extension-dev",
+    version: package_default.version
+  });
+  const getAuthToken = async () => {
+    if (options.authContext?.token) {
+      return options.authContext.token;
+    }
+    const { readFile } = await import('fs/promises');
+    const { join } = await import('path');
+    const { homedir } = await import('os');
+    const authFile = join(homedir(), ".stackable", "auth.json");
+    let state;
+    try {
+      const content = await readFile(authFile, "utf8");
+      state = JSON.parse(content);
+    } catch {
+      throw new Error("Not authenticated. Run 'stackable-app-extension auth login' first.");
+    }
+    const [, payload] = state.token.split(".");
+    if (payload) {
+      try {
+        const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        if (decoded.exp && Date.now() >= decoded.exp * 1e3) {
+          throw new Error("Session expired. Run 'stackable-app-extension auth login' to re-authenticate.");
+        }
+      } catch (err) {
+        if (err instanceof Error && err.message.includes("expired")) {
+          throw err;
+        }
+      }
+    }
+    return state.token;
+  };
+  const authHeaders = (token) => ({
+    authorization: `Bearer ${token}`,
+    "content-type": "application/json",
+    "x-client-name": MCP_CLIENT_NAME
+  });
+  const callApi = async (path) => {
+    const token = await getAuthToken();
+    const baseUrl = process.env.ADMIN_API_BASE_URL ?? DEFAULT_ADMIN_API_URL;
+    const res = await fetch(`${baseUrl}${path}`, { headers: authHeaders(token) });
+    if (!res.ok) {
+      return errorContent(`API error: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json();
+    return textContent(JSON.stringify(data, null, 2));
+  };
+  const withAuth = async (fn) => {
+    try {
+      return await fn();
+    } catch (err) {
+      return errorContent(err.message);
+    }
+  };
+  const registrySkills = listSkills("registry");
+  for (const skill of registrySkills) {
+    server.registerResource(
+      skill.id,
+      `sdk://${skill.id}`,
+      { description: skill.description, mimeType: "text/markdown" },
+      async (uri) => ({
+        contents: [{ uri: uri.href, text: getSkillBody(skill), mimeType: "text/markdown" }]
+      })
+    );
+  }
+  server.registerTool("list_skills", {
+    description: "List all available SDK skills with descriptions"
+  }, async () => textContent(JSON.stringify(registrySkills.map(getSkillMetadata), null, 2)));
+  server.registerTool("lookup_skill", {
+    description: "Look up a specific SDK skill by ID or search by keyword. Returns full skill content for ID lookup, or matching skill metadata for keyword search.",
+    inputSchema: { id: z.string().optional().describe('Exact skill ID (e.g. "capabilities", "patterns")'), query: z.string().optional().describe("Search keywords to find relevant skills") }
+  }, async ({ id, query }) => {
+    if (id) {
+      const body = lookupSkill(registrySkills, id);
+      if (!body) {
+        return errorContent(`No skill found with ID "${id}". Use list_skills to see available IDs.`);
+      }
+      return textContent(body);
+    }
+    if (query) {
+      const matches = findRelevantSkills(registrySkills, query);
+      if (matches.length === 0) {
+        return errorContent(`No skills matched "${query}". Use list_skills to see available skills.`);
+      }
+      return textContent(JSON.stringify(matches.map(getSkillMetadata), null, 2));
+    }
+    return errorContent('Provide either "id" or "query" parameter.');
+  });
+  server.registerTool("validate_manifest", {
+    description: "Validate an extension manifest.json. Checks required fields, valid permissions, targets, and allowedDomains consistency with permissions.",
+    inputSchema: { manifestContent: z.string().describe("The full manifest.json content as a string") }
+  }, async ({ manifestContent }) => {
+    const errors = [];
+    let manifest;
+    try {
+      manifest = JSON.parse(manifestContent);
+    } catch {
+      return errorContent("Invalid JSON: could not parse manifest content.");
+    }
+    if (!manifest.name || typeof manifest.name !== "string") {
+      errors.push('Missing or invalid "name" field (must be a non-empty string).');
+    }
+    if (!manifest.version || typeof manifest.version !== "string") {
+      errors.push('Missing or invalid "version" field (must be a non-empty string).');
+    }
+    if (!Array.isArray(manifest.targets) || manifest.targets.length === 0) {
+      errors.push('Missing or empty "targets" array. At least one surface target is required.');
+    }
+    if (!Array.isArray(manifest.permissions)) {
+      errors.push('Missing "permissions" array.');
+    } else {
+      const validPermissions = new Set(PERMISSIONS);
+      for (const perm of manifest.permissions) {
+        if (!validPermissions.has(perm)) {
+          errors.push(`Invalid permission "${perm}". Valid permissions: ${PERMISSIONS.join(", ")}`);
+        }
+      }
+    }
+    if (!Array.isArray(manifest.allowedDomains)) {
+      errors.push('Missing "allowedDomains" array. Use an empty array if no external API calls are needed.');
+    }
+    const permissions = manifest.permissions ?? [];
+    if (permissions.includes("data:fetch") && Array.isArray(manifest.allowedDomains) && manifest.allowedDomains.length === 0) {
+      errors.push('"data:fetch" permission declared but "allowedDomains" is empty. Add the domains your extension needs to fetch from.');
+    }
+    if (errors.length === 0) {
+      return textContent("Manifest is valid.");
+    }
+    return errorContent(`Manifest validation failed:
+${errors.map((e) => `- ${e}`).join("\n")}`);
+  });
+  server.registerTool("validate_permissions", {
+    description: "Static analysis: match declared manifest permissions against actual capability and event hook usage in source files. Detects unused permissions and missing permissions.",
+    inputSchema: {
+      manifestContent: z.string().describe("The full manifest.json content as a string"),
+      sourceFiles: z.record(z.string(), z.string()).describe("Map of filename \u2192 source content for all extension source files")
+    }
+  }, async ({ manifestContent, sourceFiles }) => {
+    let manifest;
+    try {
+      manifest = JSON.parse(manifestContent);
+    } catch {
+      return errorContent("Invalid JSON: could not parse manifest content.");
+    }
+    const declaredPermissions = new Set(manifest.permissions ?? []);
+    const usedPermissions = /* @__PURE__ */ new Set();
+    const allSource = Object.values(sourceFiles).join("\n");
+    for (const [capability, permission] of Object.entries(CAPABILITY_PERMISSION_MAP)) {
+      if (allSource.includes(capability)) {
+        usedPermissions.add(permission);
+      }
+    }
+    const eventHookMap = {
+      useIdentityEvent: "events:identity",
+      useMessagingEvent: "events:messaging",
+      useActivityEvent: "events:activity"
+    };
+    for (const [hook, permission] of Object.entries(eventHookMap)) {
+      if (allSource.includes(hook)) {
+        usedPermissions.add(permission);
+      }
+    }
+    const issues = [];
+    for (const perm of declaredPermissions) {
+      if (!usedPermissions.has(perm)) {
+        issues.push(`Unused permission "${perm}" \u2014 declared in manifest but no matching capability/hook usage found in source.`);
+      }
+    }
+    for (const perm of usedPermissions) {
+      if (!declaredPermissions.has(perm)) {
+        issues.push(`Missing permission "${perm}" \u2014 capability/hook used in source but not declared in manifest.`);
+      }
+    }
+    if (issues.length === 0) {
+      return textContent("Permissions are consistent with source code usage.");
+    }
+    return textContent(`Permission analysis:
+${issues.map((i) => `- ${i}`).join("\n")}`);
+  });
+  server.registerTool("list_apps", {
+    description: "List available apps for development with IDs, names, and targets. Requires CLI auth."
+  }, async () => withAuth(() => callApi("/app-extension")));
+  server.registerTool("list_extensions", {
+    description: "List extensions under an app with status, version, and bundle URL. Requires CLI auth.",
+    inputSchema: { appId: z.string().describe("App ID") }
+  }, async ({ appId }) => withAuth(() => callApi(`/app-extension/${appId}/extensions`)));
+  server.registerTool("get_extension", {
+    description: "Get extension detail including manifest, permissions, and targets. Requires CLI auth.",
+    inputSchema: { appId: z.string().describe("App ID"), extensionId: z.string().describe("Extension ID") }
+  }, async ({ appId, extensionId }) => withAuth(() => callApi(`/app-extension/${appId}/extensions/${extensionId}`)));
+  server.registerTool("list_instances", {
+    description: "List instances under an app. Requires CLI auth.",
+    inputSchema: { appId: z.string().describe("App ID") }
+  }, async ({ appId }) => withAuth(() => callApi(`/app-extension/${appId}/instances`)));
+  return server;
+};
+
+export { createMcpServer };