@stackable-labs/mcp-app-extension 0.23.0 → 1.0.0

package/dist/server.js

@@ -1,8 +1,12 @@
-import { STANDALONE_CLIENT, MCP_AUTH_FILE, getToken, STANDALONE_CLIENT_AUTH_FILE } from './chunk-HOOVB46Z.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, PERMISSIONS, CAPABILITY_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_ATTRIBUTES, tagToComponentName } from '@stackable-labs/sdk-extension-contracts';
+import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, PERMISSIONS, CAPABILITY_PERMISSION_MAP, EVENT_HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_ATTRIBUTES, tagToComponentName } from '@stackable-labs/sdk-extension-contracts';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
 import { z } from 'zod';
 
+// src/server.ts
+
 // ../../sdk/extension/ai-docs/src/generated/template-content.ts
 var PATTERN_SECTIONS = [
   {
@@ -530,6 +534,8 @@ const result = await capabilities.data.fetch('https://api.example.com/orders', {
 - For optional secret fields, the entire header is omitted if the value is not configured
 - Declare secret fields in your \`manifest.json\` \`settingsSchema\` with \`"secret": true\`
 
+> See [Instance Settings](./instance-settings) for the full schema-declaration + storage-mode story, including which field types accept \`secret: true\`.
+
 ## context.read \u2014 Read Host Context
 Read host-provided context (customer ID, email, extension settings, etc.).
 - **Permission required:** \`context:read\`
@@ -1148,6 +1154,202 @@ const context = await capabilities.context.read()
 \`\`\`
 `;
 };
+
+// ../../sdk/extension/ai-docs/src/generators/instance-settings.ts
+var SECRET_ALLOWED = ["text", "textarea", "email"];
+var generateInstanceSettings = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Instance Settings: declaring per-Instance configuration in your extension manifest, the install-time admin form, and reading both regular and secure values from extension code.",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts", "packages/extension/public/manifest.json"]
+  });
+  return `${fm}
+
+# Instance Settings
+
+Instance Settings are the per-Instance configuration values your extension needs in
+order to do its job \u2014 API keys, account identifiers, environment toggles, feature
+flags. You declare them once in your extension's \`manifest.json\`; whoever installs
+your extension fills them in from the admin dashboard at install time; your code
+reads the values at runtime.
+
+There are two flavors:
+
+- **Regular** values live in plaintext and are readable from your extension code.
+  Use them for non-sensitive configuration the UI needs to branch on.
+- **Secure** values are encrypted at rest and **never** leave the server. Use them
+  for credentials. Your code references them as a placeholder; the proxy
+  substitutes the real value server-side when it makes the outbound request.
+
+## 1. Declare your settings in \`manifest.json\`
+
+Add a \`settingsSchema\` array to \`packages/extension/public/manifest.json\`. Each
+entry describes one input on the install-time admin form:
+
+\`\`\`json
+{
+  "name": "My Extension",
+  "version": "1.0.0",
+  "targets": ["slot.content"],
+  "permissions": ["context:read", "data:fetch"],
+  "allowedDomains": ["api.example.com"],
+  "settingsSchema": [
+    {
+      "identifier": "apiKey",
+      "label": "API Key",
+      "type": "text",
+      "secret": true,
+      "required": true,
+      "description": "Your account API key. Stored encrypted; injected server-side into outbound request headers."
+    },
+    {
+      "identifier": "environmentType",
+      "label": "Environment",
+      "type": "select",
+      "options": [
+        { "label": "Production", "value": "prod" },
+        { "label": "Sandbox", "value": "sandbox" }
+      ]
+    }
+  ]
+}
+\`\`\`
+
+That's the entire authoring step. The next time someone installs (or re-syncs)
+your extension, the admin dashboard renders a form from this schema on the
+Instance settings page. Regular fields show inline values; secret fields show a
+masked input that accepts a value once and displays \`\u2022\u2022\u2022\u2022\` after save (the
+cleartext value is never returned by the API).
+
+### Field types
+
+| Type | Renders as | Accepts \`secret: true\` |
+|------|------------|--------------------------|
+| \`text\` | Single-line text input | Yes |
+| \`textarea\` | Multi-line text input | Yes |
+| \`email\` | Email input with format validation | Yes |
+| \`number\` | Numeric input (\`min\` / \`max\` / \`step\`) | No |
+| \`select\` | Dropdown (use \`allowMultiple\` for multi-select) | No |
+| \`radio\` | Radio button group | No |
+| \`toggle\` | On/off switch | No |
+| \`tags\` | Tag list / multi-string entry | No |
+
+The \`secret: true\` flag is only valid on \`${SECRET_ALLOWED.join("`, `")}\` types.
+
+All fields share these optional properties: \`required\`, \`placeholder\`,
+\`description\` (help text shown below the input), and \`dependsOn\` (conditional
+visibility \u2014 show this field only when another field has a matching value).
+
+## 2. The install-time admin form
+
+When someone installs your extension into one of their Instances, the admin
+dashboard reads your \`settingsSchema\` and generates a form. Each field becomes
+an input; \`required\` fields block save; \`description\` text becomes inline help;
+\`dependsOn\` rules show or hide fields based on other field values.
+
+Each Instance gets its own copy of these values, so the same extension can run
+side-by-side on multiple Instances with completely different credentials and
+configuration. The installer can edit values later from the same Instance
+settings page \u2014 your code always sees the current values.
+
+## 3. Read regular values: \`useSettings()\` (or \`useContextData()\`)
+
+Regular (non-secret) values are exposed to your extension code via the
+\`useSettings()\` hook, keyed by each field's \`identifier\`. This requires the
+\`context:read\` permission.
+
+\`\`\`tsx
+import { Surface, ui, useSettings } from '@stackable-labs/sdk-extension-react'
+
+export const Content = () => {
+  const settings = useSettings()
+  const environmentType = (settings.environmentType as string) || 'prod'
+
+  return (
+    <Surface id="slot.content">
+      <ui.Card>
+        <ui.CardContent>
+          <ui.Text>Looking up orders\u2026</ui.Text>
+          {environmentType === 'sandbox' && (
+            <ui.Text className="text-xs opacity-50">Sandbox Mode</ui.Text>
+          )}
+        </ui.CardContent>
+      </ui.Card>
+    </Surface>
+  )
+}
+\`\`\`
+
+If you need settings alongside other context data (customer, locale, etc.), they
+also come back from \`useContextData()\`:
+
+\`\`\`tsx
+import { useContextData } from '@stackable-labs/sdk-extension-react'
+
+const { loading, settings, customerId } = useContextData()
+\`\`\`
+
+> **Note:** Secret fields are **never** present in \`useSettings()\` or on
+> \`ctx.settings\`. Reading \`settings.apiKey\` for a \`secret: true\` field returns
+> \`undefined\`, even when a value is configured. If you find yourself reaching
+> for a secret value in extension code, you almost certainly want the
+> \`data.fetch\` placeholder pattern below instead.
+
+## 4. Use secure values: \`{{settings.<identifier>}}\` in \`data.fetch\`
+
+Secure values are decrypted only by the proxy Lambda that handles \`data.fetch\` \u2014
+at substitution time, per-request, then discarded. Your code references them as
+template placeholders in **header values**:
+
+\`\`\`tsx
+import { useCapabilities, useSettings } from '@stackable-labs/sdk-extension-react'
+
+const capabilities = useCapabilities()
+const settings = useSettings()
+const environmentType = (settings.environmentType as string) || 'prod'
+
+const result = await capabilities.data.fetch('https://api.example.com/orders', {
+  method: 'GET',
+  headers: {
+    // environmentType is a regular value \u2014 interpolate it normally
+    'X-Environment': environmentType,
+    // apiKey is secret \u2014 the proxy substitutes it server-side; the cleartext
+    // value never enters this code path
+    'X-Api-Key': '{{settings.apiKey}}',
+  },
+})
+if (!result.ok) throw new Error(\`Request failed: \${result.status}\`)
+\`\`\`
+
+Placeholders are only resolved in **header values** \u2014 not URLs, not header
+names, not the request body. For \`required: true\` secret fields the proxy
+returns \`400\` when the value is not configured; for optional secret fields
+the entire header is omitted.
+
+## Regular vs secure at a glance
+
+| | Regular | Secure (\`secret: true\`) |
+|--|---------|--------------------------|
+| **Stored** | Plaintext | Encrypted with a per-Instance derived key |
+| **Readable from extension code?** | Yes \u2014 \`useSettings().<identifier>\` | **Never** \u2014 secrets are not serialized to the browser or sandbox |
+| **How to use the value** | Read at render time and use freely | Reference as a \`{{settings.<identifier>}}\` placeholder in \`data.fetch\` headers \u2014 the proxy substitutes server-side |
+| **Returned by admin API after save?** | Yes (the value is shown back in the form) | No (the form shows \`\u2022\u2022\u2022\u2022\`; the cleartext value is unrecoverable) |
+
+## When in doubt, mark it \`secret: true\`
+
+The cost is negligible \u2014 one encryption per write, one decryption per outbound
+request. The blast radius of an accidental log line, screenshot, or sandbox
+exfiltration drops to zero. Secrets on one Instance also can't be used to
+decrypt secrets on any other Instance, even when both Instances run the same
+extension \u2014 encryption keys are derived per-Instance.
+
+If a value is sensitive at all (API keys, OAuth tokens, signing secrets, webhook
+shared secrets, personal access tokens), declare the field \`secret: true\` and
+reach for it via the \`data.fetch\` placeholder pattern. Save \`useSettings()\` for
+the values your UI legitimately needs to branch on.
+`;
+};
 var generatePermissions = () => {
   const fm = frontmatter({
     root: false,
@@ -1538,28 +1740,42 @@ export const Header = () => {
 - **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}`,
+  create: (name = "<extension-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 the extension (future) */
   deploy: `${DLX} @stackable-labs/cli-app-extension@latest deploy`,
-  /** Validate the extension for common errors */
+  /** Validate the extension for common errors (coming soon) */
   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`
+  update: `${DLX} @stackable-labs/cli-app-extension@latest update`,
+  /** Manage CLI authentication (browser-based OAuth) */
+  auth: {
+    login: `${DLX} @stackable-labs/cli-app-extension@latest auth login`,
+    logout: `${DLX} @stackable-labs/cli-app-extension@latest auth logout`,
+    status: `${DLX} @stackable-labs/cli-app-extension@latest auth status`
+  },
+  /** AI editor configuration tools (Skills + MCP) */
+  ai: {
+    /** Download AI editor config files (Stackable Skills) into your project */
+    scaffold: `${DLX} @stackable-labs/cli-app-extension@latest ai scaffold`,
+    /** Add Stackable MCP server config to your project */
+    mcp: `${DLX} @stackable-labs/cli-app-extension@latest ai mcp`
+  }
 };
-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" }
-];
+var TEMPLATE_FLAVOR_META = {
+  minimal: { label: "Minimal", description: "Bare minimum \u2014 single surface, hello-world component" },
+  starter: { label: "Starter", description: "Common patterns \u2014 store, api helpers, menu (default)" },
+  "kitchen-sink": { label: "Kitchen Sink", description: "Everything \u2014 every component, capability, surface, and hook" }
+};
+var TEMPLATE_FLAVOR_DETAILS = TEMPLATE_FLAVORS.map(
+  (name) => ({ name, ...TEMPLATE_FLAVOR_META[name] })
+);
 
 // ../../sdk/extension/ai-docs/src/generators/quick-start.ts
 var generateQuickStart = () => {
@@ -1575,6 +1791,21 @@ var generateQuickStart = () => {
 
 Create, develop, and deploy your first Stackable extension in minutes.
 
+## Choosing your path
+
+Stackable supports two authoring paths. Both produce the same kind of extension and ship to the same marketplace.
+
+| | AI Extension Studio | CLI (this guide) |
+|---|---|---|
+| **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 | Skills, MCP server, and Claude Code plugin (see [AI-Accelerated Development](/docs/reference/ai-accelerated-development)) |
+| **Version control** | Auto-saved to cloud | Git-based |
+| **Deployment** | Link to extension + deploy | CLI deploy command |
+
+Both produce the same output \u2014 a Stackable extension that runs in the host application via the same Remote DOM pipeline. **This guide covers the [CLI](/docs/reference/cli-reference) path.** For Studio, see [AI Extension Studio](/docs/reference/extension-studio).
+
 ## Prerequisites
 
 - **Node.js** 22 or later
@@ -1713,21 +1944,11 @@ export const Content = () => {
 }
 \`\`\`
 
-## 6. Validate & Deploy
+## 6. Submit for review
 
-Before deploying, validate your extension:
+When your extension is ready, open it in the [Stackable admin dashboard](https://admin.stackablelabs.com), fill in the marketplace listing (icon, screenshots, description, tagline, support links), and submit for review. Most reviews complete within a few business days.
 
-\`\`\`bash
-${CLI.validate}
-\`\`\`
-
-This checks manifest structure, permission usage, surface targets, and import patterns.
-
-When ready, deploy:
-
-\`\`\`bash
-${CLI.deploy}
-\`\`\`
+> *CLI \`validate\` and \`deploy\` commands are on the roadmap (see [CLI Reference](/docs/reference/cli-reference#validate-coming-soon)). Today, manifests are validated server-side during submission and via the \`validate_manifest\` MCP tool.*
 
 ## Next Steps
 
@@ -1746,7 +1967,7 @@ var generateCliReference = () => {
     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");
+  const templateRows = TEMPLATE_FLAVOR_DETAILS.map((t) => `| \`${t.name}\` | ${t.description} |`).join("\n");
   return `${fm}
 
 # CLI Reference
@@ -1765,7 +1986,7 @@ ${CLI.create()}
 
 | Argument | Description |
 |----------|-------------|
-| \`project-name\` | Directory name for the new project |
+| \`extension-name\` | Name for your extension (saved as the manifest's \`name\`; kebab-cased to derive the directory and extension ID) |
 
 **Options:**
 
@@ -1826,9 +2047,11 @@ 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
+## validate *(coming soon)*
 
-Check your extension for common errors before deploying:
+> *NOTE: manifests are validated server-side during the marketplace submission flow, in the AI Studio, or can be validated using the \`validate_manifest\` MCP tool \u2014 see [AI-Accelerated Development](/docs/reference/ai-accelerated-development#live-mcp-server).*
+
+When shipped, the \`validate\` command will check your extension for common errors locally before submission:
 
 \`\`\`bash
 ${CLI.validate}
@@ -1849,23 +2072,21 @@ ${CLI.validate}
 - \`0\` \u2014 all checks pass
 - \`1\` \u2014 errors found (must fix before deploying)
 
-## deploy
+## deploy *(future)*
+
+> *This command is on the roadmap. Currently build, deployment and hosting are the responsibility of the extension developer with your hosted Bundle URL being updated via the admin dashboard or via CLI.*
 
-Package and deploy the extension:
+When shipped, the \`deploy\` command will package and ship your extension straight from the terminal:
 
 \`\`\`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)
+**Planned behavior:**
+1. Run validation checks (same as \`validate\`)
+2. Build the extension for production
+3. Package the build output
+4. Upload to the Stackable extension registry
 
 ## scaffold
 
@@ -1902,6 +2123,62 @@ ${CLI.update} [extensionId]
 | \`--bundle-url <url>\` | New bundle URL |
 | \`--enabled <bool>\` | Enable/disable extension |
 | \`--dir <path>\` | Project root (default: cwd) |
+
+## auth
+
+Manage CLI authentication. Subcommands open a browser-based OAuth flow against the Stackable platform and store the resulting credentials locally.
+
+**Subcommands:**
+
+| Subcommand | Description |
+|------------|-------------|
+| \`login\` | Authenticate with Stackable via browser-based OAuth |
+| \`logout\` | Clear stored CLI credentials |
+| \`status\` | Show current authentication status (signed-in user, org, token expiry) |
+
+**Examples:**
+
+\`\`\`bash
+# First-time setup
+${CLI.auth.login}
+
+# Check who's signed in
+${CLI.auth.status}
+
+# Sign out
+${CLI.auth.logout}
+\`\`\`
+
+## ai
+
+Manage AI editor configuration in your Extension project. Subcommands write Stackable's [AI tooling](/docs/reference/ai-accelerated-development) (Skills + MCP server config) into your project.
+
+**Subcommands:**
+
+| Subcommand | Description |
+|------------|-------------|
+| \`scaffold\` | Download Stackable Skills into your project's \`.claude/\`, \`.cursor/\`, \`.windsurf/\`, etc. |
+| \`mcp\` | Add Stackable MCP server config to your project so any MCP-compatible AI client can connect |
+
+**Options:**
+
+| Flag | Description | Applies to |
+|------|-------------|------------|
+| \`--version <version>\` | AI docs version (semver or \`latest\`, default: \`latest\`) | both |
+| \`--dir <path>\` | Project root directory (default: cwd) | \`mcp\` only |
+
+**Examples:**
+
+\`\`\`bash
+# Add the latest Stackable Skills to your project
+${CLI.ai.scaffold}
+
+# Pin a specific version
+${CLI.ai.scaffold} --version 0.2.0
+
+# Configure your project to talk to the Stackable MCP server
+${CLI.ai.mcp}
+\`\`\`
 `;
 };
 
@@ -2060,29 +2337,29 @@ var generateExtensionStudio = () => {
   const fm = frontmatter({
     root: false,
     targets: ["*"],
-    description: "Extension Studio: in-browser builder with AI assistant, component palette, and live preview",
+    description: "AI 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
+# AI Extension Studio
 
-Extension Studio is an in-browser development environment for building Stackable
+Stackable's AI 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:
+"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 |
+| **Stage** | Center | Code editor or live preview \u2014 toggle between modes |
 | **Sidekick** | Right (collapsible, resizable) | AI chat assistant for code generation and SDK guidance |
 
-## The Shelf
+## The "Shelf"
 
 The Shelf is a collapsible sidebar with three sections:
 
@@ -2107,7 +2384,7 @@ The SDK capabilities your extension can use: \`data.query\`, \`data.fetch\`,
 \`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 "Stage"
 
 The center pane switches between two modes:
 
@@ -2122,7 +2399,7 @@ 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"
 
 The Sidekick is an AI chat assistant that understands the Stackable Extension SDK.
 It can:
@@ -2162,18 +2439,114 @@ Studio toolbar.
 
 ## Studio vs CLI
 
-| | Studio | CLI |
+Comparing approaches? See [Choosing your path](/docs/guides/quick-start#choosing-your-path) in the Quick Start guide for the full Studio vs CLI comparison.
+
+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.
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/generators/ai-accelerated-development.ts
+var generateAIAcceleratedDevelopment = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "AI-Accelerated Development: AI Extension Studio, Agent Skills, the live MCP server, and the Claude Code plugin \u2014 and how to choose between them.",
+    globs: ["*"]
+  });
+  return `${fm}
+
+# AI-Accelerated Development
+
+Stackable's AI-native messaging experience platform makes building extensions really simple - and incredibly fast. Four complementary surfaces (Studio, Agent Skills, MCP Server, and Claude Code Plugin) take you from possibility to production in minutes.
+
+| Surface | Best for | Install |
 |---|---|---|
-| **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 |
+| **AI Extension Studio** | First extensions, prototyping, in-browser builds | Open the admin dashboard |
+| **Agent Skills** | Any AI coding assistant | \`pnpm dlx skills add stackable-labs/skills\` (auto-bundled in scaffolds) |
+| **Live MCP Server** | AI clients that speak MCP | Add to your client's MCP config |
+| **Claude Code Plugin** | Claude Code users (bundles Skills + MCP) | \`/plugin marketplace add stackable-labs/claude-plugins\` |
+
+---
+
+## AI Extension Studio
+
+AI Extension Studio is more than just another AI App builder ([Lovable](https://lovable.dev), [v0](https://v0.dev), [Bolt](https://bolt.new), [Replit](https://replit.com), etc.). It's an in-browser companion trained specifically to conceptualize and build experiences for the Stackable framework that are secure, look great, and are **production ready in minutes!**
+
+The 3-pane workspace (component palette, live preview, agentic chat) takes you from idea to shipped code in moments. The agentic chat ("Sidekick") writes and modifies code, updates your manifest, looks up SDK reference on demand, and suggests next steps as you work. No installs, no Node version to manage, no tunnel \u2014 open the admin dashboard and you're building.
+
+**Best for:** first extensions, prototyping, non-developers, and quick experiments.
+
+**When to move to the CLI:** Studio produces a simple single-file project. When you need multi-file structure, custom dependencies, your own build pipeline, or git-based version control, you can transition seamlessly. Either download your Studio project as a ZIP from the export menu, or pull it directly via the CLI. Either path produces a fully-structured local project ready for production build and deployment.
+
+For full Studio details, see [AI Extension Studio](/docs/reference/extension-studio).
+
+## AI Agentic Skills
+
+[Agent Skills](https://agentskills.io) is an open standard for publishing machine-readable knowledge that AI coding assistants can pull on demand instead of crawling your docs. Stackable publishes the core SDK concepts (surfaces, capabilities, components, hooks, patterns, recipes, and more) as Agent Skills, so any compatible assistant has just-in-time access to exactly the surface area it needs.
+
+### How to install
+
+- **Bundled automatically when you scaffold** \u2014 \`@stackable-labs/cli-app-extension create\` writes the Stackable Skills into your project's \`.claude/\`, \`.cursor/\`, \`.windsurf/\`, and equivalent directories. No extra setup.
+- **Standalone install** \u2014 for an existing project, or to update to the latest skills, run:
+  \`\`\`bash
+  pnpm dlx skills add stackable-labs/skills
+  \`\`\`
+  This is powered by [Vercel's open \`skills\` CLI](https://github.com/vercel-labs/skills).
+
+### Compatible assistants
+
+Agent Skills work with any tool that supports the format \u2014 Claude Code, Cursor, Windsurf, Codex, VS Code (with MCP-aware extensions), Continue, Zed, and 40+ others listed on agentskills.io. Stackable's Claude Code plugin (below) bundles + auto-updates these skills for Claude Code users.
+
+## Live MCP Server
+
+The Stackable platform exposes a hosted MCP (Model Context Protocol) server that any compatible AI client can connect to for live access to your account's apps, extensions, and platform metadata.
+
+**Endpoint:** \`https://api-use1.stackablelabs.io/mcp/app-extension\`
+
+### Available tools (snapshot)
+
+| Tool | What it does |
+|---|---|
+| \`list_apps\` | List apps in your account |
+| \`list_extensions\` | List extensions for a given app |
+| \`list_instances\` | List deployed instances of an extension |
+| \`list_skills\` | List available SDK skills |
+| \`lookup_skill\` | Fetch a specific SDK skill's content on demand |
+| \`get_extension\` | Fetch full details for a single extension |
+| \`validate_manifest\` | Validate an extension manifest against the platform |
+| \`validate_permissions\` | Validate manifest permissions |
+
+### Compatible clients
+
+[Claude Desktop](https://claude.ai/download), [VS Code](https://code.visualstudio.com), [Cursor](https://cursor.com), [Codex](https://developers.openai.com/codex), [Antigravity](https://antigravity.google), [Windsurf](https://windsurf.com), and any other MCP-compatible AI tool. Each client has its own way to register MCP servers \u2014 see your client's docs for the exact config syntax.
+
+Authentication uses standard OAuth2 \u2014 your client will prompt you to sign in on first use.
+
+## Claude Code Plugin
+
+For Claude Code users, the Stackable Claude Code plugin bundles the Skills and pre-configures the MCP server in one install.
+
+**Install:**
+\`\`\`bash
+# Add marketplace
+/plugin marketplace add stackable-labs/claude-plugins
+
+# Install plugin
+/plugin install stackable-extension-dev@stackable-claude-plugins
+\`\`\`
+
+**What it includes:**
+- Latest Stackable Agent Skills (auto-updated)
+- The Stackable MCP server pre-configured
+- Slash commands and workflows tailored for extension development
+
+After install, Claude Code can scaffold, validate, and inspect your Stackable extensions directly from your editor without any extra config.
 
-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.
+## Choosing your tools
+
+- **Just starting?** Open [AI Extension Studio](/docs/reference/extension-studio) in the admin dashboard. No installs, no decisions \u2014 get started on your first extension right in the browser.
+- **Want more control, or preparing for release?** Use the [CLI](/docs/guides/quick-start) for a full local TypeScript project: multi-file structure, your own dependencies, git-based version control, and your own build pipeline.
+- **Building from scratch with your own AI workflow?** Wire up your editor with [Agent Skills](#ai-agentic-skills), the [Live MCP Server](#live-mcp-server), or both \u2014 or use the [Claude Code Plugin](#claude-code-plugin) for Claude Code users, which auto-bundles Skills and pre-configures the MCP server in one install.
 `;
 };
 var generateProjectStructure = () => {
@@ -3012,12 +3385,23 @@ var generateValidateExtensionCommand = () => {
     description: "Validate this extension for common errors before deploying (manifest, permissions, surfaces, imports)",
     targets: ["*"]
   });
+  const eventHookBullets = Object.keys(EVENT_HOOK_PERMISSION_MAP).map((hook) => `- \`${hook}\` \u2192 needs \`${EVENT_HOOK_PERMISSION_MAP[hook]}\` permission (also check manifest \`events\` array has matching entries)`).join("\n");
   return `${fm}
 
 # Validate Extension
 
 Check this extension for common errors before deploying. Run through each check
-and report all issues found.
+and ensure no issues found before you submit.
+
+> **Tip \u2014 let the platform validate for you.** The hosted Stackable MCP server
+> exposes a \`validate_manifest\` tool that runs the same server-side checks the
+> marketplace submission flow uses. If your AI client is connected to the
+> Stackable MCP server (see [AI-Accelerated Development](/docs/reference/ai-accelerated-development#live-mcp-server)),
+> just ask it to validate \`packages/extension/public/manifest.json\` for you \u2014
+> it returns structured errors and warnings without you having to walk the
+> checklist below by hand. The manual steps remain useful for code-level checks
+> the manifest validator can't see (permission usage, surface wiring, sandbox
+> compliance).
 
 ## 1. Manifest validation
 Read \`packages/extension/public/manifest.json\` and verify:
@@ -3037,9 +3421,7 @@ Scan all \`.tsx\` files in \`packages/extension/src/\` for capability usage:
 - \`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)
+${eventHookBullets}
 
 Report:
 - **Missing permissions:** capabilities used in code but not declared in manifest
@@ -3059,6 +3441,202 @@ Verify that:
 ## 5. Summary
 Print a summary: total issues found, categorized by severity (error vs warning).
 Errors must be fixed before deploying. Warnings are recommendations.
+
+## Next: deploy
+
+Once validation passes, build the production bundle, host it, and register the
+Bundle URL with Stackable. See the [Deploy guide](/docs/guides/deploy).
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/commands/deploy-extension.ts
+var generateDeployExtensionCommand = () => {
+  const fm = frontmatter({
+    description: "Build, host, and register the production Bundle URL for this Stackable extension",
+    targets: ["*"]
+  });
+  return `${fm}
+
+# Deploy
+
+Stackable hosts the marketplace, the proxy, and the runtime \u2014 but **you host
+your extension's bundle/runtime**. Deployment is three steps: build for production,
+upload to a host of your choice, then point your extension's **Bundle URL** at
+the result.
+
+## 1. Build the production bundle
+
+From the project root:
+
+\`\`\`bash
+pnpm build
+\`\`\`
+
+This runs Vite in production mode and writes the static bundle to
+\`packages/extension/dist/\` \u2014 a small set of JS/CSS files plus your
+\`manifest.json\`. That's the artifact you ship.
+
+> **Tip:** Validate the build before you upload it. Run through the
+> [Validate guide](/docs/guides/validate) (or ask your AI client to call the
+> \`validate_manifest\` MCP tool) so manifest typos and missing permissions are
+> caught before they reach the marketplace.
+
+## 2. Upload to a hosting provider
+
+Stackable doesn't care where the bundle lives \u2014 only that it's served over
+HTTPS with permissive CORS so the host runtime can fetch it. Anything that
+serves static files works. The most common options:
+
+| Provider | Notes |
+|----------|-------|
+| **Netlify** | Drop \`packages/extension/dist/\` into a site, or wire up Git auto-deploys. CORS is already permissive. |
+| **Vercel** | Same idea \u2014 link the repo and let Vercel build/deploy on push. Set the build output to \`packages/extension/dist\`. |
+| **Cloudflare Pages** | Connect the repo, set the output directory, deploys land on the edge globally. |
+| **AWS S3 + CloudFront** | Sync \`dist/\` to an S3 bucket, front it with a CloudFront distribution. Make sure the CloudFront response headers include \`Access-Control-Allow-Origin: *\` (or your host origin). |
+| **Your own CDN / object storage** | Anything that returns \`200 OK\` with the right \`Content-Type\` and CORS headers will work. |
+
+Whichever you pick, the only requirements are:
+
+- Bundle is reachable over **HTTPS**
+- CORS allows the host application's origin (most providers do this by default; S3+CloudFront is the one that usually needs explicit configuration)
+- The URL is **stable** \u2014 every Instance running your extension fetches from this URL on load
+
+> **Need help with setup or deployment?** Reach out at [developers@stackablelabs.com](mailto:developers@stackablelabs.com) or open an issue / discussion on [GitHub](https://github.com/stackable-labs).
+
+## 3. Register your Bundle URL with Stackable
+
+Once your extension bundle is deployed/live, tell Stackable where to find it. You have two options:
+
+- **Admin dashboard** \u2014 open your extension at [admin.stackablelabs.com](https://admin.stackablelabs.com), edit the **Bundle URL** field, and save. Existing Instances pick up the new bundle the next time they load.
+- **CLI** \u2014 from the project directory:
+
+  \`\`\`bash
+  ${CLI.update} --bundle-url https://your-host.example.com/manifest.json
+  \`\`\`
+
+  Or, with an explicit extension ID (handy for CI/CD):
+
+  \`\`\`bash
+  ${CLI.update} ext_xxx --bundle-url https://your-host.example.com/manifest.json
+  \`\`\`
+
+Point the URL at your bundle's \`manifest.json\` \u2014 that's the entrypoint the
+runtime fetches first; everything else is loaded relative to it.
+
+## 4. Roll out and iterate
+
+That's the entire deploy loop. Subsequent updates follow the same path: bump
+\`version\` in \`manifest.json\`, run \`pnpm build\`, re-upload, and (only if the
+URL changed) re-register. Most teams wire steps 1\u20133 into a single CI/CD job
+that runs on every merge to \`main\`.
+
+## Next: list it on the Marketplace
+
+Deploying makes your extension **runnable** at a stable URL. To make it
+**installable** by other organizations, you also need to fill in the
+marketplace listing (icon, screenshots, description, visibility) and submit
+for review. See [Marketplace Listing](/docs/reference/marketplace-listing).
+`;
+};
+
+// ../../sdk/extension/ai-docs/src/commands/marketplace-listing.ts
+var generateMarketplaceListing = () => {
+  const fm = frontmatter({
+    description: "Fill in your marketplace listing, choose visibility, and submit your Stackable extension for review and approval",
+    targets: ["*"]
+  });
+  return `${fm}
+
+# Listing & Submission
+
+Once your extension is built, hosted, and registered with a Bundle URL (see
+[Deploy](/docs/guides/deploy)), the last step is to make it discoverable and
+installable. That happens entirely in the [admin dashboard](https://admin.stackablelabs.com)
+\u2014 you fill in your marketplace listing, pick a visibility mode, and submit for
+review.
+
+## 1. Fill in the listing fields
+
+Open your extension in the admin dashboard and complete the **Listing** tab.
+Every field below is part of the marketplace metadata that prospective
+installers see when browsing or evaluating your extension.
+
+| Field | Required | What it's for |
+|-------|----------|---------------|
+| **Icon** | Yes | Square image rendered on browse cards and the detail page. Square aspect ratio, transparent background recommended. |
+| **Short description** | Yes | One-line summary used on browse cards and search results. Keep it under ~120 characters. |
+| **Long description** | Yes | Markdown body for the extension detail page. Cover what the extension does, the problem it solves, and any setup requirements. Screenshots and links allowed. |
+| **Screenshots** | Recommended | Image gallery shown on the detail page. Pick views that demonstrate the extension actually working in a host application. |
+| **Categories** | Yes | One or more curated categories from the platform taxonomy (e.g., commerce, support, analytics). Drives marketplace browse filters. |
+| **Tags** | Optional | Freeform searchable tags. Used for keyword search across the marketplace. |
+| **Publisher** | Auto | Pulled from your organization profile \u2014 the org name shown as the listing's publisher. Update your org profile in the dashboard if this needs to change. |
+
+> **Tip:** The icon and screenshots are what make a listing feel real. A
+> placeholder icon and no screenshots is the single biggest reason listings
+> get a "needs more info" review response.
+
+## 2. Choose a visibility mode
+
+Every listing has a **visibility** setting that controls who can install it:
+
+| Visibility | Who can find and install it |
+|------------|------------------------------|
+| **Public** | Anyone browsing the marketplace. Goes through full marketplace review. Best for extensions you want available to everyone. |
+| **Protected** | Only organizations you explicitly add to the **allowed orgs** list. The listing is hidden from public browse; people you've allowed see it in their marketplace as if it were public. Best for private/internal extensions, paid customers, or staged rollouts. |
+
+Visibility can be changed later from the same Listing tab. Switching from
+**Protected** \u2192 **Public** triggers a fresh marketplace review.
+
+## 3. Submit for review
+
+Click **Submit for review**. The platform runs a two-stage review:
+
+### Stage 1 \u2014 Automated Bundle scan
+
+Runs immediately on submit. The platform fetches your bundle from the
+registered Bundle URL and runs deterministic checks:
+
+- Bundle reachable, valid \`manifest.json\`, sane bundle size
+- Declared permissions match observed capability usage
+- Declared targets match the surfaces your code actually registers
+- Declared \`allowedDomains\` match the endpoints \`data.fetch\` actually hits
+- No use of forbidden browser globals (\`document\`, \`window.location\`, etc.)
+
+Findings come back categorized as **error**, **warning**, or **info**. Errors
+must be fixed before the listing can move forward. Warnings don't block
+submission but factor into the review.
+
+### Stage 2 \u2014 Advanced review + Stackable approval
+
+If Stage 1 passes, the platform runs an advanced review of your bundle \u2014
+framework analysis, permission surface, network behavior, and any
+security-relevant findings get scored and assessed against your listing
+content. From there, Stackable will either:
+
+- **Approve** \u2014 your listing moves to **Published** and becomes installable.
+- **Request changes** \u2014 you'll see structured feedback on the listing page. Address it, re-deploy if needed, and resubmit.
+
+Most reviews complete within a few business days. You'll get an email when
+the status changes; the listing's review status is also visible in the admin
+dashboard at all times.
+
+## Review status lifecycle
+
+| Status | Meaning |
+|--------|---------|
+| **Draft** | Listing is being edited; not submitted. |
+| **Pending review** | Submitted; waiting on Stage 1 + Stage 2 + Stackable approval. |
+| **Rejected** | Stackable requested changes. Address the feedback and resubmit. |
+| **Published** | Live in the marketplace. Installable per your visibility setting. |
+| **Suspended** | Pulled from the marketplace by Stackable (security issue, ToS violation, etc.). Contact support. |
+
+## After publishing
+
+Re-deploys to the same Bundle URL don't require re-submission \u2014 your existing
+Instances pick up the new bundle automatically. **Listing edits** (description,
+screenshots, categories, visibility) and **major version bumps** do go through
+review again. Patch updates that don't change permissions, targets, or
+\`allowedDomains\` typically clear review quickly.
 `;
 };
 
@@ -3152,6 +3730,12 @@ var SKILLS = [
     type: "knowledge",
     content: () => generateStylingAndTheming()
   },
+  {
+    id: "instance-settings",
+    description: "Instance Settings: declaring settingsSchema in your extension manifest, the install-time admin form, and reading regular values via useSettings() vs secure values via {{settings.x}} placeholders in data.fetch. Use when adding per-Instance configuration to an extension.",
+    type: "knowledge",
+    content: () => generateInstanceSettings()
+  },
   // ── Docs-only knowledge skills ──────────────────────────────
   {
     id: "quick-start",
@@ -3181,6 +3765,13 @@ var SKILLS = [
     scopes: ["docs"],
     content: () => generateExtensionStudio()
   },
+  {
+    id: "ai-accelerated-development",
+    description: "AI-Accelerated Development: AI Extension Studio, Agent Skills, the live MCP server, and the Claude Code plugin \u2014 and how to choose between them.",
+    type: "knowledge",
+    scopes: ["docs"],
+    content: () => generateAIAcceleratedDevelopment()
+  },
   // ── Cookbook skills (docs-only) ────────────────────────────────
   {
     id: "cookbook-structural",
@@ -3203,6 +3794,13 @@ var SKILLS = [
     scopes: ["docs"],
     content: () => generateCookbookEvents()
   },
+  {
+    id: "marketplace-listing",
+    description: "Marketplace listing reference: the listing fields (icon, screenshots, description, categories), Public vs Protected visibility, and the two-stage review process (bundle scan + security review + approval). Use when publishing a deployed extension to the marketplace.",
+    type: "knowledge",
+    scopes: ["docs"],
+    content: () => generateMarketplaceListing()
+  },
   // ── Action skills ─────────────────────────────────────────────
   {
     id: "add-surface",
@@ -3227,6 +3825,15 @@ var SKILLS = [
     description: "Validate this extension for common errors before deploying: manifest, permissions, surfaces, imports. Use before publishing or when debugging issues.",
     type: "action",
     content: () => generateValidateExtensionCommand()
+  },
+  {
+    id: "deploy",
+    description: "Build the production bundle, host it on Netlify / Vercel / Cloudflare Pages / S3+CloudFront, and register your Bundle URL with Stackable via the admin dashboard or CLI. Use when shipping an extension after validation passes.",
+    type: "action",
+    // TODO: T3 #24 — remove `scopes: ['docs']` once `cli deploy` is implemented so Studio's
+    // AI assistant in the future should be able invoke the deploy flow (not just describe it).
+    scopes: ["docs"],
+    content: () => generateDeployExtensionCommand()
   }
 ];
 
@@ -3828,6 +4435,64 @@ pair(EXAMPLE_SNIPPETS, EXAMPLE_SNIPPETS2);
 pair(CAPABILITY_SNIPPETS, CAPABILITY_SNIPPETS2);
 pair(EVENT_SNIPPETS, EVENT_SNIPPETS2);
 
+// ../../lib/contracts/src/custom.ts
+var CUSTOM_ROLE = {
+  SUPER_ADMIN: "super_admin"
+};
+new Set(Object.values(CUSTOM_ROLE));
+
+// ../../lib/utils-auth/src/constants.ts
+var STANDALONE_CLIENT_DATA = {
+  CLI: { name: "@stackable-labs/cli-app-extension", authFile: "cli-auth.json" },
+  MCP: { name: "@stackable-labs/mcp-app-extension", authFile: "mcp-auth.json" }
+};
+var STANDALONE_CLIENT = Object.fromEntries(
+  Object.entries(STANDALONE_CLIENT_DATA).map(([k, v]) => [k, v.name])
+);
+var STANDALONE_CLIENT_AUTH_FILE = Object.fromEntries(
+  Object.entries(STANDALONE_CLIENT_DATA).map(([k, v]) => [k, v.authFile])
+);
+Object.values(STANDALONE_CLIENT);
+
+// ../../lib/utils-auth/src/index.ts
+var AUTH_DIR = join(homedir(), ".stackable");
+join(AUTH_DIR, STANDALONE_CLIENT_AUTH_FILE.CLI);
+var MCP_AUTH_FILE = join(AUTH_DIR, STANDALONE_CLIENT_AUTH_FILE.MCP);
+var resolveAuthFile = (filename) => join(AUTH_DIR, filename ?? STANDALONE_CLIENT_AUTH_FILE.CLI);
+var readAuthState = async (filename) => {
+  try {
+    const content = await readFile(resolveAuthFile(filename), "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+};
+var decodeJwtPayload = (token) => {
+  try {
+    const [, payload] = token.split(".");
+    if (!payload) {
+      return null;
+    }
+    const json = Buffer.from(payload, "base64url").toString("utf8");
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+};
+var getToken = async (filename) => {
+  const state = await readAuthState(filename);
+  if (!state) {
+    throw new Error("Not authenticated. Run `stackable-app-extension auth login` first.");
+  }
+  const payload = decodeJwtPayload(state.token);
+  if (payload?.exp && typeof payload.exp === "number") {
+    if (Date.now() >= payload.exp * 1e3) {
+      throw new Error("Session expired. Run `stackable-app-extension auth login` to re-authenticate.");
+    }
+  }
+  return state.token;
+};
+
 // package.json
 var package_default = {
   version: "0.0.0"};
@@ -3851,9 +4516,13 @@ var createMcpServer = (options = {}) => {
       return await getToken(STANDALONE_CLIENT_AUTH_FILE.MCP);
     } catch {
     }
-    const { performOAuthFlow } = await import('./auth-DWIWIJNN.js');
+    if (!options.performOAuthFlow) {
+      throw new Error(
+        "No auth token available. Provide authContext (server) or performOAuthFlow (CLI)."
+      );
+    }
     const MCP_API_BASE_URL = process.env.MCP_API_BASE_URL ?? DEFAULT_MCP_API_BASE_URL;
-    return performOAuthFlow(`${MCP_API_BASE_URL}/.well-known/oauth-authorization-server`);
+    return options.performOAuthFlow(`${MCP_API_BASE_URL}/.well-known/oauth-authorization-server`);
   };
   const authHeaders = (token) => ({
     authorization: `Bearer ${token}`,
@@ -3990,12 +4659,7 @@ ${errors.map((e) => `- ${e}`).join("\n")}`);
         usedPermissions.add(permission);
       }
     }
-    const eventHookMap = {
-      useIdentityEvent: "events:identity",
-      useMessagingEvent: "events:messaging",
-      useActivityEvent: "events:activity"
-    };
-    for (const [hook, permission] of Object.entries(eventHookMap)) {
+    for (const [hook, permission] of Object.entries(EVENT_HOOK_PERMISSION_MAP)) {
       if (allSource.includes(hook)) {
         usedPermissions.add(permission);
       }