better-design 0.7.6 → 0.8.0

package/dist/index.js

@@ -284,7 +284,7 @@ var init_constants = __esm({
     RULE_END = "<!-- better-design:end -->";
     RULE_BODY = `## Better Design
 
-Always use the Better Design MCP tools for any frontend, UI, UX, interaction, flow, form, navigation, dialog, error, onboarding, component, or styling work, without me having to explicitly ask. Load visual guidance with \`get-ui-principle\`, load flow/behavior guidance with \`get-ux-principle\`, and self-review against \`get-review-rules\` after. Use \`create-design-system\` to generate the user's own brand (the default for building an app), or \`find-design\` / \`get-design-system-docs\` to install an existing catalog system.`;
+Always use the Better Design MCP tools for any frontend, UI, UX, interaction, flow, form, navigation, dialog, error, onboarding, component, or styling work, without me having to explicitly ask. Load visual guidance with \`get-ui-principle\`, load flow/behavior guidance with \`get-ux-principle\`, and self-review against \`get-review-rules\` after. Use \`create-design-system\` to generate the user's own brand (the default for building an app), or \`find-design-system\` / \`get-design-system-docs\` to install an existing catalog system.`;
     RULE_BLOCK = `${RULE_START}
 ${RULE_BODY}
 ${RULE_END}`;
@@ -559,7 +559,7 @@ var init_rule_writer = __esm({
 
 // src/setup/args.ts
 function parseArgs(argv2) {
-  const args = { help: false };
+  const args = { help: false, autoKey: false };
   for (const arg of argv2) {
     switch (arg) {
       case "--global":
@@ -568,6 +568,14 @@ function parseArgs(argv2) {
       case "--project":
         args.scope = "project";
         break;
+      // `setup` is the implicit command; tolerate it appearing in argv.
+      case "setup":
+        break;
+      // Non-interactive: skip prompts, auto-mint a key.
+      case "-y":
+      case "--yes":
+        args.autoKey = true;
+        break;
       case "--help":
       case "-h":
         args.help = true;
@@ -580,20 +588,25 @@ var HELP_TEXT;
 var init_args = __esm({
   "src/setup/args.ts"() {
     "use strict";
-    HELP_TEXT = `better-design-mcp setup: configure Better Design in your AI clients
+    HELP_TEXT = `better-design: connect Better Design to your AI coding tools
 
 Usage:
-  npx better-design-mcp setup [options]
+  npx better-design          Set up Better Design (auto-creates a key, no signup)
+  npx better-design setup     Same as the bare command, with options below
 
 Options:
+  -y, --yes   Non-interactive: skip all prompts and auto-create a key
   --global    Install at user/global scope (default)
   --project   Install at project scope (current directory)
   --help, -h  Show this help
 
-The installer detects your clients and prompts for the rest. Set your API key
-via the BETTER_DESIGN_API_KEY env var or the interactive prompt.
+No API key? You don't need one up front. The installer creates a free key for
+you automatically (no account required) so you can start using Better Design
+right away. Create an account later to keep your key and lift the free limit.
 
-Get an API key at https://better-design.com/mcp`;
+Already have a key? Set BETTER_DESIGN_API_KEY and it will be used instead.
+
+Manage your account or keys at https://better-design.com/mcp`;
   }
 });
 
@@ -612,11 +625,40 @@ var init_prompts = __esm({
   }
 });
 
+// src/setup/provision.ts
+async function provisionApiKey() {
+  const res = await fetch(`${API_URL}/api/api-keys/provision`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (!res.ok) {
+    const body2 = await res.json().catch(() => ({}));
+    throw new Error(
+      body2.message ?? `Could not create a key automatically (HTTP ${res.status}). Create one at ${DASHBOARD_URL}`
+    );
+  }
+  const body = await res.json();
+  if (!body.key) {
+    throw new Error(`Provisioning endpoint returned no key. Create one at ${DASHBOARD_URL}`);
+  }
+  return { key: body.key, claimUrl: body.claimUrl ?? "" };
+}
+var API_URL;
+var init_provision = __esm({
+  "src/setup/provision.ts"() {
+    "use strict";
+    init_constants();
+    API_URL = process.env.API_URL ?? "https://better-design.com";
+  }
+});
+
 // src/setup/index.ts
 var setup_exports = {};
 __export(setup_exports, {
   runSetup: () => runSetup
 });
+import { spawn } from "child_process";
 async function runSetup(argv2) {
   const args = parseArgs(argv2);
   if (args.help) {
@@ -625,7 +667,7 @@ async function runSetup(argv2) {
   }
   const interactive = Boolean(process.stdin.isTTY);
   clack.intro("Better Design setup");
-  const apiKey = await getApiKey(interactive);
+  const apiKey = await getApiKey(interactive, args.autoKey);
   const clients = await pickClients(interactive);
   if (clients.length === 0) {
     clack.outro("No clients selected. Run again and select at least one client.");
@@ -644,13 +686,55 @@ async function runSetup(argv2) {
   const ruleResults = rulePlan.files.map((f) => writeRule(f));
   printSummary(results, ruleResults, rulePlan.manual);
 }
-async function getApiKey(interactive) {
+async function getApiKey(interactive, autoKey) {
   const fromEnv = process.env.BETTER_DESIGN_API_KEY;
   if (fromEnv) return fromEnv.trim();
-  if (!interactive) {
-    clack.cancel(`No API key. Set BETTER_DESIGN_API_KEY. Get one at ${DASHBOARD_URL}`);
-    process.exit(1);
+  if (!interactive || autoKey) {
+    return provisionFlow();
   }
+  const choice = ensure(
+    await clack.select({
+      message: "No API key found. How do you want to connect?",
+      options: [
+        { value: "browser", label: "Sign in / create an account", hint: "opens browser, unlimited, recommended" },
+        { value: "generate", label: "Create a free key now", hint: "no account" }
+      ],
+      initialValue: "browser"
+    })
+  );
+  if (choice === "browser") return browserFlow();
+  return provisionFlow();
+}
+async function provisionFlow() {
+  const spinner = clack.spinner();
+  spinner.start("Creating a free Better Design key");
+  try {
+    const { key, claimUrl } = await provisionApiKey();
+    spinner.stop("Created a free Better Design key (no account needed)");
+    if (claimUrl) {
+      clack.note(
+        `You're on the free tier with a limited number of queries.
+Create an account to keep this key and go unlimited:
+${claimUrl}`,
+        "Heads up"
+      );
+    }
+    return key;
+  } catch (error) {
+    spinner.stop("Couldn't create a key automatically");
+    throw error instanceof Error ? error : new Error(String(error));
+  }
+}
+async function browserFlow() {
+  openUrl(DASHBOARD_URL);
+  clack.note(
+    `Opened ${DASHBOARD_URL} in your browser.
+Sign in, copy your API key, then paste it here.`,
+    "Sign in"
+  );
+  return pasteFlow();
+}
+async function pasteFlow() {
   const key = ensure(
     await clack.password({
       message: `Paste your Better Design API key (get one at ${DASHBOARD_URL})`,
@@ -659,6 +743,13 @@ async function getApiKey(interactive) {
   );
   return key.trim();
 }
+function openUrl(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
+  } catch {
+  }
+}
 async function pickClients(interactive) {
   const detected = detectInstalled();
   if (!interactive) return detected;
@@ -757,6 +848,7 @@ var init_setup = __esm({
     init_args();
     init_prompts();
     init_constants();
+    init_provision();
   }
 });
 
@@ -769,12 +861,12 @@ var init_instructions = __esm({
 
 Use these tools for ANY frontend, UI, component, or styling work, without being asked.
 
-Tools (exact names): find-design, get-design-system-docs, preview-design-system (SHOW in-chat), create-design-system, check-design-system-status (poll after create), get-ui-principle, get-ux-principle, get-review-rules, resolve-icon-library, search-icons, install-icons, detect-icon-library.
+Tools (exact names): find-design-system, get-design-system-docs, preview-design-system (SHOW in-chat), create-design-system, get-design-system-status (poll after create), get-ui-principle, get-ux-principle, get-review-rules, find-icon-library, find-icons, install-icons, detect-icon-library.
 
 ## Build an app (even if the user never says "design" or "brand")
 On any "build/make me <app>" request, create the user's BRAND design system FIRST, then build with it:
 1. create-design-system({ prompt }) \u2014 derive the prompt from the app (name, domain, vibe) -> a custom brand (tokens + components). Share the project URL so the user watches it build.
-2. check-design-system-status({ projectId }) \u2014 poll; it SHOWS the generated brand inline.
+2. get-design-system-status({ projectId }) \u2014 poll; it SHOWS the generated brand inline.
 3. Build the app with that brand. Brand first, not raw UI.
 
 ## Building / modifying UI
@@ -784,7 +876,7 @@ On any "build/make me <app>" request, create the user's BRAND design system FIRS
 4. get-review-rules after; fix every critical/serious issue before presenting.
 
 ## Only if the user explicitly names an existing catalog DS
-Default is create-design-system (above). Just to install a named catalog system: find-design(query) -> get-design-system-docs({ designSystemId }) -> run BOTH bash lines (installs globals.css + components into components/ui/; use only their tokens). Icons: detect-icon-library / resolve-icon-library -> search-icons -> install-icons. Never runtime @iconify/react.
+Default is create-design-system (above). Just to install a named catalog system: find-design-system(query) -> get-design-system-docs({ designSystemId }) -> run BOTH bash lines (installs globals.css + components into components/ui/; use only their tokens). Icons: detect-icon-library / find-icon-library -> find-icons -> install-icons. Never runtime @iconify/react.
 `.trim();
   }
 });
@@ -902,21 +994,20 @@ Emitting a single standalone \`.html\` file as "the app" when you could run the
     PREVIEW_OUTPUT_SCHEMA = z.object({
       status: z.string().describe("completed | error | pending | generating | selected"),
       name: z.string().describe("Display name of the design system or project."),
-      viewUrl: z.string().optional().describe("Better Design page for this system/project."),
+      viewUrl: z.string().optional().describe("Owner-facing Better Design page (the human 'Open' link). May require login."),
+      previewUrl: z.string().optional().describe("Public, cookieless showcase URL to embed in an iframe (sandboxed hosts can't carry the user's session). Falls back to viewUrl."),
       shotUrl: z.string().optional().describe("Real screenshot of the showcase page, for hosts that can't iframe it."),
       installCommand: z.string().optional().describe("shadcn install command, when complete."),
       step: z.string().optional().describe("Current generation step, while generating."),
       tokensCss: z.string().describe("CSS custom-property stylesheet for the system's tokens.")
     });
     SEARCH_TOOLS = /* @__PURE__ */ new Set([
-      "find-design",
-      "resolve-design-system",
-      // deprecated alias of find-design [BD-152]
+      "find-design-system",
       "get-ui-principle",
       "get-ux-principle",
       "get-review-rules",
-      "resolve-icon-library",
-      "search-icons",
+      "find-icon-library",
+      "find-icons",
       "create-design-system"
     ]);
   }
@@ -1356,11 +1447,9 @@ var init_icon_installer = __esm({
 // ../shared/src/mcp/tools/icon-tools.ts
 import { z as z3 } from "zod";
 function registerIconTools({ server, provider, tracked, track }) {
-  server.registerTool(
-    "resolve-icon-library",
-    {
-      title: "Resolve Icon Library",
-      description: `Search for icon libraries matching a design style or personality using semantic search.
+  const iconLibraryConfig = {
+    title: "Find Icon Library",
+    description: `Search for icon libraries matching a design style or personality using semantic search.
 
 Use this to find an icon library that matches your design system's personality:
 - Style traits (minimal, bold, rounded, sharp, outlined, filled)
@@ -1371,156 +1460,154 @@ Examples:
 - "minimal clean professional" \u2192 Iconoir, Feather Icons
 - "friendly rounded warm" \u2192 Phosphor, MingCute
 - "bold technical enterprise" \u2192 Tabler, Carbon`,
-      inputSchema: z3.object({
-        query: z3.string().describe("Style description or personality traits to match.")
-      }),
-      annotations: { readOnlyHint: true }
-    },
-    async ({ query }) => {
-      const start = Date.now();
-      try {
-        const results = await provider.searchIconLibraries(query, 5);
-        const topResults = results.map((result) => ({ id: result.id, score: result.matchScore }));
-        if (results.length === 0) {
-          return trackSearch(
-            track,
-            "resolve-icon-library",
-            { query, topResults },
-            start,
-            { content: [{ type: "text", text: "No icon libraries found matching your query." }] }
-          );
-        }
-        const formatted = results.map((r) => {
-          const lines = [
-            `**ID:** ${r.id}`,
-            `**Name:** ${r.name}`,
-            `**Prefix:** ${r.prefix}`,
-            `**Style:** ${r.tags.join(", ")}`
-          ];
-          if (r.variants?.length) {
-            lines.push(`**Variants:** ${r.variants.join(", ")}`);
-            lines.push(`**Default Variant:** ${r.defaultVariant || r.variants[0]}`);
-          }
-          lines.push(`**Match Score:** ${r.matchScore}%`);
-          return lines.join("\n");
-        }).join("\n\n----------\n\n");
+    inputSchema: z3.object({
+      query: z3.string().describe("Style description or personality traits to match.")
+    }),
+    annotations: { readOnlyHint: true }
+  };
+  const makeIconLibraryHandler = (toolName) => async ({ query }) => {
+    const start = Date.now();
+    try {
+      const results = await provider.searchIconLibraries(query, 5);
+      const topResults = results.map((result) => ({ id: result.id, score: result.matchScore }));
+      if (results.length === 0) {
         return trackSearch(
           track,
-          "resolve-icon-library",
+          toolName,
           { query, topResults },
           start,
-          {
-            content: [{
-              type: "text",
-              text: `# Matching Icon Libraries
+          { content: [{ type: "text", text: "No icon libraries found matching your query." }] }
+        );
+      }
+      const formatted = results.map((r) => {
+        const lines = [
+          `**ID:** ${r.id}`,
+          `**Name:** ${r.name}`,
+          `**Prefix:** ${r.prefix}`,
+          `**Style:** ${r.tags.join(", ")}`
+        ];
+        if (r.variants?.length) {
+          lines.push(`**Variants:** ${r.variants.join(", ")}`);
+          lines.push(`**Default Variant:** ${r.defaultVariant || r.variants[0]}`);
+        }
+        lines.push(`**Match Score:** ${r.matchScore}%`);
+        return lines.join("\n");
+      }).join("\n\n----------\n\n");
+      return trackSearch(
+        track,
+        toolName,
+        { query, topResults },
+        start,
+        {
+          content: [{
+            type: "text",
+            text: `# Matching Icon Libraries
 
 Use the prefix with Iconify: \`<Icon icon="prefix:icon-name" />\`
 
 ---
 
 ${formatted}`
-            }]
-          }
-        );
-      } catch (error) {
-        return trackSearch(
-          track,
-          "resolve-icon-library",
-          { query, topResults: [] },
-          start,
-          { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : "Unknown error"}` }] },
-          true,
-          error instanceof Error ? error.message : String(error)
-        );
-      }
+          }]
+        }
+      );
+    } catch (error) {
+      return trackSearch(
+        track,
+        toolName,
+        { query, topResults: [] },
+        start,
+        { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : "Unknown error"}` }] },
+        true,
+        error instanceof Error ? error.message : String(error)
+      );
     }
-  );
-  server.registerTool(
-    "search-icons",
-    {
-      title: "Search Icons",
-      description: `Search for specific icons within an icon library.
+  };
+  server.registerTool("find-icon-library", iconLibraryConfig, makeIconLibraryHandler("find-icon-library"));
+  const iconSearchConfig = {
+    title: "Find Icons",
+    description: `Search for specific icons within an icon library.
 
-Use this after resolve-icon-library to find specific icons by name/concept.
+Use this after find-icon-library to find specific icons by name/concept.
 
 **Query with a single canonical noun** ("inbox", "calendar", "paperclip"), not a multi-word phrase. The underlying index keyword-matches, so "home" beats "home house dwelling". Multi-word queries still work (they fall back to a per-keyword union) but a single noun gives the best ranking. Search once per concept; you don't need to retry with synonyms.
 
 Examples:
-- search-icons({ query: "home", libraryId: "phosphor" })
-- search-icons({ query: "settings", libraryId: "tabler" })
+- find-icons({ query: "home", libraryId: "phosphor" })
+- find-icons({ query: "settings", libraryId: "tabler" })
 
 Returns icons formatted for use with Iconify React. If you pass a variant, Better Design will try standard Iconify naming first, such as \`home-bold\`, then fall back to alternate naming and the bare icon name.`,
-      inputSchema: z3.object({
-        query: z3.string().describe("What icon you need (e.g., 'home', 'settings', 'user')"),
-        libraryId: z3.string().describe("The icon library ID from resolve-icon-library"),
-        variant: z3.string().optional().describe("Optional variant style (e.g., 'bold', 'outline', 'duotone').")
-      }),
-      annotations: { readOnlyHint: true }
-    },
-    async ({ query, libraryId, variant }) => {
-      const start = Date.now();
-      try {
-        const library = await provider.getIconLibraryById(libraryId);
-        if (!library) {
-          return trackSearch(
-            track,
-            "search-icons",
-            { query, topResults: [] },
-            start,
-            { content: [{ type: "text", text: `Icon library '${libraryId}' not found.` }] }
-          );
-        }
-        const icons = await provider.searchIconsInLibrary(query, library, variant, 15);
-        const topResults = icons.map((icon2) => ({ id: icon2 }));
-        if (icons.length === 0) {
-          return trackSearch(
-            track,
-            "search-icons",
-            { query, topResults },
-            start,
-            { content: [{ type: "text", text: `No icons found in ${library.name}.` }] }
-          );
-        }
-        const lines = [
-          `# Icons from ${library.name}`,
-          "",
-          '**Next step:** call `install-icons` with these names to scaffold them as SSR-clean React component files in the user\'s repo. Avoid the runtime `<Icon icon="..." />` import, it requires a CDN fetch on every page load.',
-          "",
-          "```ts",
-          `install-icons({ libraryId: "${library.id}", names: [${icons.slice(0, 3).map((i) => `"${stripPrefix(i)}"`).join(", ")}${icons.length > 3 ? ", ..." : ""}] })`,
-          "```",
-          "",
-          "Found icons:",
-          "",
-          ...icons.map((icon2) => `- \`${icon2}\``)
-        ];
+    inputSchema: z3.object({
+      query: z3.string().describe("What icon you need (e.g., 'home', 'settings', 'user')"),
+      libraryId: z3.string().describe("The icon library ID from find-icon-library"),
+      variant: z3.string().optional().describe("Optional variant style (e.g., 'bold', 'outline', 'duotone').")
+    }),
+    annotations: { readOnlyHint: true }
+  };
+  const makeIconSearchHandler = (toolName) => async ({ query, libraryId, variant }) => {
+    const start = Date.now();
+    try {
+      const library = await provider.getIconLibraryById(libraryId);
+      if (!library) {
         return trackSearch(
           track,
-          "search-icons",
-          { query, topResults },
+          toolName,
+          { query, topResults: [] },
           start,
-          { content: [{ type: "text", text: lines.join("\n") }] }
+          { content: [{ type: "text", text: `Icon library '${libraryId}' not found.` }] }
         );
-      } catch (error) {
+      }
+      const icons = await provider.searchIconsInLibrary(query, library, variant, 15);
+      const topResults = icons.map((icon2) => ({ id: icon2 }));
+      if (icons.length === 0) {
         return trackSearch(
           track,
-          "search-icons",
-          { query, topResults: [] },
+          toolName,
+          { query, topResults },
           start,
-          { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : "Unknown error"}` }] },
-          true,
-          error instanceof Error ? error.message : String(error)
+          { content: [{ type: "text", text: `No icons found in ${library.name}.` }] }
         );
       }
+      const lines = [
+        `# Icons from ${library.name}`,
+        "",
+        '**Next step:** call `install-icons` with these names to scaffold them as SSR-clean React component files in the user\'s repo. Avoid the runtime `<Icon icon="..." />` import, it requires a CDN fetch on every page load.',
+        "",
+        "```ts",
+        `install-icons({ libraryId: "${library.id}", names: [${icons.slice(0, 3).map((i) => `"${stripPrefix(i)}"`).join(", ")}${icons.length > 3 ? ", ..." : ""}] })`,
+        "```",
+        "",
+        "Found icons:",
+        "",
+        ...icons.map((icon2) => `- \`${icon2}\``)
+      ];
+      return trackSearch(
+        track,
+        toolName,
+        { query, topResults },
+        start,
+        { content: [{ type: "text", text: lines.join("\n") }] }
+      );
+    } catch (error) {
+      return trackSearch(
+        track,
+        toolName,
+        { query, topResults: [] },
+        start,
+        { content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : "Unknown error"}` }] },
+        true,
+        error instanceof Error ? error.message : String(error)
+      );
     }
-  );
+  };
+  server.registerTool("find-icons", iconSearchConfig, makeIconSearchHandler("find-icons"));
   server.registerTool(
     "install-icons",
     {
       title: "Install Icons as React Components",
       description: `Scaffold SVG icons as React component files (.tsx) into the user's repo.
 
-Call this after \`search-icons\` to materialise the chosen icons as owned, SSR-clean component files, with no runtime CDN fetch from \`api.iconify.design\` and no first-paint flash.
+Call this after \`find-icons\` to materialise the chosen icons as owned, SSR-clean component files, with no runtime CDN fetch from \`api.iconify.design\` and no first-paint flash.
 
 The tool fetches each SVG from the public Iconify API, inlines its viewBox + body into a small \`<Name>Icon\` React component, and returns a list of \`<file path="...">\`-tagged blocks for the agent to write to disk. A barrel \`index.ts\` is also returned.
 
@@ -1532,7 +1619,7 @@ import { HomeIcon } from "@/components/icons";
 
 If \`components/icons/index.ts\` already exists in the project, MERGE the new exports into it rather than overwriting.`,
       inputSchema: z3.object({
-        libraryId: z3.string().describe("Icon library ID from resolve-icon-library (e.g. 'tabler', 'phosphor')."),
+        libraryId: z3.string().describe("Icon library ID from find-icon-library (e.g. 'tabler', 'phosphor')."),
         names: z3.array(z3.string()).min(1).describe("Icon names to install. May be bare (e.g. 'home') or prefixed (e.g. 'tabler:home')."),
         targetDir: z3.string().optional().describe("Directory inside the project to write into. Defaults to 'components/icons'."),
         format: z3.enum(["tsx", "svg"]).optional().describe("Output format. 'tsx' (default) generates React components; 'svg' generates raw .svg files."),
@@ -1552,7 +1639,7 @@ If \`components/icons/index.ts\` already exists in the project, MERGE the new ex
           const dir = dirResult.dir;
           const library = await provider.getIconLibraryById(libraryId);
           if (!library) {
-            return { content: [{ type: "text", text: `Icon library '${libraryId}' not found. Call resolve-icon-library first.` }] };
+            return { content: [{ type: "text", text: `Icon library '${libraryId}' not found. Call find-icon-library first.` }] };
           }
           const outFormat = format ?? "tsx";
           const prefix = library.prefix;
@@ -1734,11 +1821,11 @@ If \`components/icons/index.ts\` already exists in the project, MERGE the new ex
 
 Reads <targetDir>/.library.json (default targetDir: "components/icons") if it exists and returns the locked library + installed icon list.
 
-Call this BEFORE resolve-icon-library / install-icons. If a library is already locked, use it for any new icon work. Do NOT switch libraries mid-project.
+Call this BEFORE find-icon-library / install-icons. If a library is already locked, use it for any new icon work. Do NOT switch libraries mid-project.
 
 Returns either:
 - The locked library info + installed icon list, with a hint to call install-icons using that libraryId, OR
-- A "no library detected" response, prompting the agent to call resolve-icon-library normally.`,
+- A "no library detected" response, prompting the agent to call find-icon-library normally.`,
       inputSchema: z3.object({
         manifestContent: z3.string().optional().describe("Contents of the project's components/icons/.library.json file, if it exists. The agent should attempt to read this file from disk and pass it here. If the file doesn't exist or can't be read, omit this field.")
       }),
@@ -1746,7 +1833,7 @@ Returns either:
     },
     async ({ manifestContent }) => tracked("detect-icon-library", { hasManifest: Boolean(manifestContent) }, async () => {
       if (!manifestContent || !manifestContent.trim()) {
-        return { content: [{ type: "text", text: "No `.library.json` manifest found. Proceed by calling `resolve-icon-library` to pick a library, then `install-icons` to scaffold icons. The library you pick will be locked for subsequent installs." }] };
+        return { content: [{ type: "text", text: "No `.library.json` manifest found. Proceed by calling `find-icon-library` to pick a library, then `install-icons` to scaffold icons. The library you pick will be locked for subsequent installs." }] };
       }
       try {
         const parsed = JSON.parse(manifestContent);
@@ -1764,7 +1851,7 @@ Returns either:
       } catch (err) {
         return { content: [{ type: "text", text: `Failed to parse .library.json: ${err instanceof Error ? err.message : "unknown error"}
 
-Proceed by calling \`resolve-icon-library\` to pick a library.` }] };
+Proceed by calling \`find-icon-library\` to pick a library.` }] };
       }
     })
   );
@@ -2094,29 +2181,38 @@ function componentRadiusCss(files) {
   if (card) rules.push(`.bd-card, .ds-card { border-radius: ${card}; }`);
   return rules.join("\n");
 }
+function decodeArbitrary(raw) {
+  const value = raw.replace(/(?<!\\)_/g, " ").replace(/\\_/g, "_").trim();
+  return value && !/[<>{};]/.test(value) ? value : null;
+}
+function restingValue(scope, cssProp, utilPrefixes) {
+  for (const prefix of utilPrefixes) {
+    const m = scope.match(new RegExp(`(?<![\\w:.\\-])${prefix}-\\[([^\\]]+)\\]`));
+    if (m) {
+      const v = decodeArbitrary(m[1]);
+      if (v) return v;
+    }
+  }
+  const pm = scope.match(new RegExp(`(?<!:)\\[${cssProp}:([^\\]]+)\\]`));
+  return pm ? decodeArbitrary(pm[1]) : null;
+}
+function variantBody(content, name) {
+  const vi = content.search(/variant\s*:\s*\{/);
+  const hay = vi !== -1 ? content.slice(vi) : content;
+  const m = hay.match(
+    new RegExp(`[\\s{,]${name}\\s*:\\s*([\\s\\S]*?)(?:\\n\\s*[A-Za-z_][\\w-]*\\s*:|\\n\\s*\\},)`)
+  );
+  return m ? m[1] : null;
+}
 function componentDepthCss(files) {
   const btn = files.find((f) => f.path && /(^|\/)button\.(tsx|jsx)$/.test(f.path));
   if (!btn?.content) return "";
   const content = btn.content;
-  let scope = content;
-  const variantIdx = content.search(/variant\s*:\s*\{/);
-  if (variantIdx !== -1) {
-    const after = content.slice(variantIdx);
-    const dm = after.match(
-      /default\s*:\s*([\s\S]*?)(?:\n\s*(?:secondary|destructive|outline|ghost|link|subtle|success|warning|info|danger)\s*:|\n\s*\},)/
-    );
-    if (dm) scope = dm[1];
-  }
-  const arbitrary = (prefix) => {
-    const m = scope.match(new RegExp(`${prefix}-\\[([^\\]]+)\\]`));
-    if (!m) return null;
-    const value = m[1].replace(/(?<!\\)_/g, " ").replace(/\\_/g, "_").trim();
-    return value && !/[<>{};]/.test(value) ? value : null;
-  };
-  const rules = [];
-  const shadow = /(?:^|\s|"|')shadow-none(?=\s|"|'|$)/.test(scope) ? "none" : arbitrary("shadow");
-  const background = arbitrary("bg");
+  const scope = variantBody(content, "primary") ?? variantBody(content, "default") ?? content;
+  const shadow = /(?:^|\s|"|')shadow-none(?=\s|"|'|$)/.test(scope) ? "none" : restingValue(scope, "box-shadow", ["shadow"]);
+  const background = restingValue(scope, "background", ["bg"]) ?? restingValue(scope, "background-image", []);
   const sel = ".bd-btn-primary, .bd-view, .ds-btn-primary";
+  const rules = [];
   if (shadow) rules.push(`${sel} { box-shadow: ${shadow}; }`);
   if (background) rules.push(`${sel} { background: ${background}; }`);
   return rules.join("\n");
@@ -2138,14 +2234,14 @@ function buildDsComponentCss(files) {
   const card = contentOf(/(^|\/)card\.(tsx|jsx)$/);
   if (card) {
     covered.add("card");
-    const shadow = /shadow-none(?=[\s"'])/.test(card) ? "none" : arbitrary(card, /shadow-\[([^\]]+)\]/);
+    const shadow = /shadow-none(?=[\s"'])/.test(card) ? "none" : restingValue(card, "box-shadow", ["shadow"]);
     if (shadow) rules.push(`.ds-card { box-shadow: ${shadow}; }`);
   }
   const sw = contentOf(/(^|\/)switch\.(tsx|jsx)$/);
   if (sw) {
     covered.add("switch");
-    const bg = arbitrary(sw, /data-\[state=checked\]:bg-\[([^\]]+)\]/);
-    const shadow = arbitrary(sw, /data-\[state=checked\]:shadow-\[([^\]]+)\]/);
+    const bg = arbitrary(sw, /data-\[state=checked\]:bg-\[([^\]]+)\]/) ?? arbitrary(sw, /data-\[state=checked\]:\[background(?:-image)?:([^\]]+)\]/);
+    const shadow = arbitrary(sw, /data-\[state=checked\]:shadow-\[([^\]]+)\]/) ?? arbitrary(sw, /data-\[state=checked\]:\[box-shadow:([^\]]+)\]/);
     if (bg) rules.push(`.ds-switch-track.on { background: ${bg}; }`);
     if (shadow) rules.push(`.ds-switch-track.on { box-shadow: ${shadow}; }`);
   }
@@ -2278,7 +2374,11 @@ var init_preview_html = __esm({
    preview use the system's font everywhere; headings opt into --font-serif. [BD-120] */
 html, body { margin: 0; padding: 0; background: transparent; font-family: var(--font-sans, ui-sans-serif, system-ui, sans-serif); color: var(--foreground, oklch(0.2 0 0)); }
 ${PREVIEW_BASE_CSS}
-.bd-card-shell { background: var(--background, oklch(1 0 0)); border-radius: 16px; overflow: hidden; box-shadow: 0 1px 3px oklch(0 0 0 / 0.08), 0 8px 24px oklch(0 0 0 / 0.06); }
+/* Square + flush: no radius, no shadow. The host (claude.ai bubble / ChatGPT
+   widget frame) already provides the card chrome, so an inner rounded+shadowed
+   shell read as an awkward card-in-a-card and clipped the screenshot corners.
+   overflow:hidden stays to contain children. [BD-136] */
+.bd-card-shell { background: var(--background, oklch(1 0 0)); overflow: hidden; }
 .bd-app { padding: 16px; }
 .bd-cta-row { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 12px 16px; background: var(--card, var(--background, oklch(1 0 0))); border-top: 1px solid var(--border, oklch(0.92 0 0)); }
 .bd-cta-name { font-weight: 600; font-size: 14px; color: var(--foreground, oklch(0.2 0 0)); font-family: var(--font-serif, var(--font-sans, ui-sans-serif)); }
@@ -2300,21 +2400,11 @@ ${PREVIEW_BASE_CSS}
 /* .bd-row carries margin:12px 0 from the base CSS; reset it inside the sampler so the
    8px column gap is the only spacing (else label<->row reads ~20px, too loose). */
 .bd-sampler .bd-row { margin: 0; }
-/* Generating state: a clearly-loading skeleton, NOT a token-rendered mock \u2014 the
-   DS tokens aren't ready yet, so a full vignette would render in flat fallback
-   colors and read as a broken finished system. Theme-neutral on purpose. */
+/* Error state: a static, theme-neutral note (errorBody). No DS tokens are
+   loaded, so it falls back to a light ramp on the white fallback card. */
 .bd-skel-app { padding: 16px; display: flex; flex-direction: column; gap: 12px; font-family: ui-sans-serif, system-ui, sans-serif; }
 .bd-skel-name { font-weight: 600; font-size: 14px; color: var(--muted-foreground, oklch(0.45 0 0)); }
 .bd-skel-row { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
-.bd-skel-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 10px; }
-/* Skeleton color tracks the (host or DS) surface tokens, NOT prefers-color-
-   scheme: while generating tokensCss is empty so these fall back to a light
-   ramp on the white fallback card; if the host applies a dark theme the bars
-   follow --muted/--border instead of fighting it. */
-.bd-skel { background: var(--muted, oklch(0.92 0 0)); border-radius: 8px; position: relative; overflow: hidden; }
-.bd-skel::after { content: ""; position: absolute; inset: 0; transform: translateX(-100%); background: linear-gradient(90deg, oklch(1 0 0 / 0), oklch(1 0 0 / 0.28), oklch(1 0 0 / 0)); animation: bd-shimmer 1.4s ease-in-out infinite; }
-@keyframes bd-shimmer { 100% { transform: translateX(100%); } }
-@media (prefers-reduced-motion: reduce) { .bd-skel::after { animation: none; } }
 .bd-skel-card { border: 1px solid var(--border, oklch(0.9 0 0)); border-radius: 14px; padding: 16px 18px; display: flex; flex-direction: column; gap: 10px; }
 /* No DS font is loaded while generating, so keep the footer name neutral sans
    too \u2014 otherwise a host-injected serif that doesn't load in the sandbox falls
@@ -2511,31 +2601,6 @@ ${DS_KIT_CSS}
     return '<div class="bd-show ds' + (full ? " bd-fs" : "") + '">' + wrapped + '</div>';
   }
 
-  // Loading skeleton shown while the system is still generating: its tokens
-  // aren't ready, so a token-rendered vignette would paint in flat fallback
-  // colors and look like a finished-but-broken DS. Theme-neutral shimmer instead.
-  function skeletonBody(out) {
-    var nm = esc(out.name || "Design system");
-    return '<div class="bd-skel-app">' +
-      '<div class="bd-skel-row"><span class="bd-skel-name">' + nm + '</span><span class="bd-skel-name" style="font-weight:400;opacity:0.7">Generating' + (out.step ? ": " + esc(out.step) : "...") + '</span></div>' +
-      '<div class="bd-skel-card">' +
-        '<div class="bd-skel" style="height:18px;width:60%"></div>' +
-        '<div class="bd-skel" style="height:11px;width:90%"></div>' +
-        '<div class="bd-skel" style="height:11px;width:75%"></div>' +
-        '<div class="bd-skel-row" style="margin-top:6px;justify-content:flex-start;gap:10px">' +
-          '<div class="bd-skel" style="height:34px;width:104px"></div>' +
-          '<div class="bd-skel" style="height:34px;width:104px"></div>' +
-        '</div>' +
-      '</div>' +
-      '<div class="bd-skel-grid">' +
-        '<div class="bd-skel" style="height:62px"></div>' +
-        '<div class="bd-skel" style="height:62px"></div>' +
-        '<div class="bd-skel" style="height:62px"></div>' +
-      '</div>' +
-      '<div class="bd-skel" style="height:44px"></div>' +
-    '</div>';
-  }
-
   // Generation failed: a static (non-shimmer) note. A shimmering "loading"
   // skeleton would falsely read as still-in-progress, and the token vignette
   // can't render (no tokens). The CTA below links to the project page to retry.
@@ -2656,16 +2721,20 @@ ${DS_KIT_CSS}
   // our own: both hosts render a native close button in fullscreen (ChatGPT's
   // top bar, claude.ai's native header), so our own Back bar was redundant and
   // visually broken (misaligned, disliked chevron). [BD-136]
-  function iframeBody(out, view, full) {
+  // embed = the PUBLIC, cookieless URL we iframe (the sandbox carries no
+  // session cookie, so an owner-scoped page would 404 inside it). open = the
+  // owner-facing page for the human "Open" link (they have the cookie). [BD-164]
+  function iframeBody(out, embed, open, full) {
     var nm = esc(out.name || "Design system");
-    var frame = '<iframe class="bd-frame" src="' + esc(embedUrl(view)) + '" title="' + nm + ' showcase" referrerpolicy="no-referrer-when-downgrade"></iframe>';
+    var frame = '<iframe class="bd-frame" src="' + esc(embedUrl(embed)) + '" title="' + nm + ' showcase" referrerpolicy="no-referrer-when-downgrade"></iframe>';
     if (full) {
       return '<div class="bd-frame-wrap bd-fs">' + frame + '</div>';
     }
+    var openHref = open || embed;
     return '<div class="bd-frame-wrap">' + frame +
       '<div class="bd-frame-foot"><span class="bd-cta-name">' + nm + '</span><span class="bd-cta-actions">' +
         (canFullscreen() ? '<button class="bd-expand" data-bd-fullscreen type="button">Fullscreen' + ICON_EXPAND + '</button>' : "") +
-        '<a class="bd-cta" data-bd-open href="' + esc(view) + '" target="_blank" rel="noopener">Open' + ICON_EXTERNAL + '</a>' +
+        '<a class="bd-cta" data-bd-open href="' + esc(openHref) + '" target="_blank" rel="noopener">Open' + ICON_EXTERNAL + '</a>' +
       '</span></div>' +
     '</div>';
   }
@@ -2707,6 +2776,12 @@ ${DS_KIT_CSS}
     var img = root.querySelector("[data-bd-shot]");
     if (!img) return;
     img.addEventListener("error", function () { shotFailed = true; if (lastOut) render(lastOut); });
+    // The screenshot loads async; its real height only exists after it decodes.
+    // claude.ai reads the widget's documentElement height from the DOM, so re-pin
+    // the iframe height once the image has dimensions (a cached image may already
+    // be complete before this runs). [BD-136]
+    img.addEventListener("load", scheduleResize);
+    if (img.complete && img.naturalHeight) scheduleResize();
   }
 
   function render(out) {
@@ -2716,6 +2791,10 @@ ${DS_KIT_CSS}
     syncHostFonts();
     // Only an http(s) URL is usable; reject any other scheme up front.
     var view = safeUrl(out.viewUrl);
+    // The iframe must load a PUBLIC, cookieless URL (the sandbox has no session
+    // cookie). previewUrl points at /preview/<fragmentId>; fall back to view if
+    // the host didn't supply one (e.g. catalog DSes, whose view is public). [BD-164]
+    var embed = safeUrl(out.previewUrl) || view;
     var isError = out.status === "error";
     var generating = out.status && out.status !== "completed" && !isError;
     var completed = !isError && !generating;
@@ -2723,10 +2802,18 @@ ${DS_KIT_CSS}
     // render if there's no shotUrl or the image failed to load.
     var useShot = !shotFailed && !!safeUrl(out.shotUrl);
 
+    // ChatGPT's fullscreen "Open in <app>" button defaults to the iframe's
+    // current path, which is now the PUBLIC /preview page. Repoint it at the
+    // owner's editable /projects/<id> (they have the session cookie on the web,
+    // so it loads for them) so fullscreen Open still reaches their project. [BD-164]
+    if (completed && view && window.openai && window.openai.setOpenInAppUrl) {
+      try { window.openai.setOpenInAppUrl({ href: view }); } catch (e) {}
+    }
+
     // Fullscreen: ChatGPT iframes the real page; claude.ai shows the full
     // screenshot (scrollable) or the token showcase. [BD-136]
     if (displayMode === "fullscreen" && completed) {
-      if (canIframe() && view) { root.innerHTML = iframeBody(out, view, true); return; }
+      if (canIframe() && embed) { root.innerHTML = iframeBody(out, embed, view, true); return; }
       if (useShot) { root.innerHTML = '<div class="bd-card-shell bd-fs">' + shotBody(out, true) + footHtml(out) + '</div>'; wireShotFallback(); }
       else { root.innerHTML = showcaseBody(out, true); wireShowcase(); }
       return;
@@ -2735,8 +2822,8 @@ ${DS_KIT_CSS}
     // Inline completed: ChatGPT = real-page iframe; claude.ai = real screenshot
     // (capped) or token showcase, + a footer (Fullscreen + Open). [BD-136]
     if (completed) {
-      if (canIframe() && view) {
-        root.innerHTML = '<div class="bd-card-shell">' + iframeBody(out, view, false) + '</div>';
+      if (canIframe() && embed) {
+        root.innerHTML = '<div class="bd-card-shell">' + iframeBody(out, embed, view, false) + '</div>';
         return;
       }
       var body = useShot ? shotBody(out, false) : showcaseBody(out, false);
@@ -2745,8 +2832,11 @@ ${DS_KIT_CSS}
       return;
     }
 
-    // Generating / error / no-url: skeleton or static note + optional open link.
-    var hero = isError ? errorBody(out) : generating ? skeletonBody(out) : errorBody(out);
+    // Generating: render nothing \u2014 no fake skeleton. The widget stays empty
+    // until the system is completed (or errors). [BD-164]
+    if (generating) { root.innerHTML = ""; return; }
+    // Error / no-url: static note + optional open link.
+    var hero = errorBody(out);
     var cta = view
       ? '<div class="bd-cta-row"><span class="bd-cta-name">' + esc(out.name || "Design system") + '</span>' +
           '<a class="bd-cta" data-bd-open href="' + esc(view) + '" target="_blank" rel="noopener">Open' + ICON_EXTERNAL + '</a></div>'
@@ -2754,9 +2844,56 @@ ${DS_KIT_CSS}
     root.innerHTML = '<div class="bd-card-shell">' + hero + cta + "</div>";
   }
 
-  // Auto-resize is handled by the MCP Apps client (setupSizeChangedNotifications:
-  // ResizeObserver on documentElement + body -> ui/notifications/size-changed),
-  // mirroring ext-apps' App. The widget doesn't manage sizing itself. [BD-150]
+  // \u2500\u2500 Sizing \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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  // The MCP Apps client emits ui/notifications/size-changed (ResizeObserver on
+  // documentElement + body); ChatGPT honors that and auto-sizes its widget.
+  // claude.ai web does NOT honor size-changed \u2014 it reads the widget's
+  // documentElement height straight from the DOM and pins the iframe to whatever
+  // inline height the document carries. With no explicit height the iframe stays
+  // at 0 (verified live: a single size-changed{0,0} then the iframe sits at 0px;
+  // claude-ai-mcp#69). So on the DOM-reading hosts we set
+  // document.documentElement.style.height ourselves, AFTER content + the async
+  // screenshot have real height. [BD-136]
+  var lastAppliedH = 0;
+  function measureCardHeight() {
+    var card = root.firstElementChild; // .bd-card-shell / fullscreen shell
+    return Math.ceil(Math.max(
+      (card && card.scrollHeight) || 0,
+      root.scrollHeight || 0,
+      document.body ? document.body.scrollHeight : 0,
+    ));
+  }
+  function applyClaudeHeight() {
+    // ChatGPT (window.openai) auto-sizes via its own bridge \u2014 never fight it.
+    if (window.openai) return;
+    var de = document.documentElement;
+    // Fullscreen content is position:fixed (out of flow), so its scrollHeight is
+    // meaningless \u2014 clear the pin and let the host own the viewport.
+    if (displayMode === "fullscreen") { de.style.height = ""; lastAppliedH = 0; return; }
+    var h = measureCardHeight();
+    if (h > 0 && Math.abs(h - lastAppliedH) > 1) {
+      lastAppliedH = h;
+      de.style.height = h + "px";
+    }
+  }
+  // Measure across two frames (layout settle + image decode) so we never pin a
+  // pre-render / pre-image height that claude.ai would latch onto.
+  function scheduleResize() {
+    if (typeof requestAnimationFrame !== "function") { applyClaudeHeight(); return; }
+    requestAnimationFrame(function () { applyClaudeHeight(); requestAnimationFrame(applyClaudeHeight); });
+  }
+  // Re-pin on every render swap (#bd-root mutations) and on any late layout growth
+  // (fonts, reflow). The screenshot's own load event is wired in wireShotFallback.
+  try {
+    if (typeof MutationObserver === "function") {
+      new MutationObserver(scheduleResize).observe(root, { childList: true, subtree: true });
+    }
+  } catch (e) {}
+  try {
+    if (typeof ResizeObserver === "function") {
+      new ResizeObserver(scheduleResize).observe(root);
+    }
+  } catch (e) {}
 
   // The widget runs in a sandboxed iframe (claude.ai); a bare <a target=_blank>
   // cannot open a tab or navigate the top frame, so the CTA looks dead. Route the
@@ -2917,7 +3054,7 @@ function registerDesignSystemTools({
   const searchInputSchema = z4.object({
     query: z4.string().describe("Natural language query describing the type of UI you're building.")
   });
-  const searchDescription = (deprecated) => `${deprecated ? "DEPRECATED alias of find-design \u2014 prefer find-design. " : ""}Search the Better Design catalog for an EXISTING design system via semantic search, and return its ID.
+  const searchDescription = () => `Search the Better Design catalog for an EXISTING design system via semantic search, and return its ID.
 
 For building an app, generate the user's OWN brand with create-design-system instead. Use this only to browse or inspect catalog systems (the user names one, or wants to preview before installing).
 
@@ -2988,24 +3125,14 @@ ${formatted}`
     }
   };
   server.registerTool(
-    "find-design",
+    "find-design-system",
     {
       title: "Find Design System",
-      description: searchDescription(false),
-      inputSchema: searchInputSchema,
-      annotations: { readOnlyHint: true }
-    },
-    makeSearchHandler("find-design")
-  );
-  server.registerTool(
-    "resolve-design-system",
-    {
-      title: "Resolve Design System (deprecated alias of find-design)",
-      description: searchDescription(true),
+      description: searchDescription(),
       inputSchema: searchInputSchema,
       annotations: { readOnlyHint: true }
     },
-    makeSearchHandler("resolve-design-system")
+    makeSearchHandler("find-design-system")
   );
   server.registerTool(
     "get-design-system-docs",
@@ -3013,7 +3140,7 @@ ${formatted}`
       title: "Get Design System Documentation",
       description: `Scaffolds a design system into the user's project.
 
-You must call 'find-design' first to obtain the design system ID.
+You must call 'find-design-system' first to obtain the design system ID.
 
 **Default behavior (recommended): install the full design system.**
 Call with only a designSystemId and this tool returns ONE shadcn command that
@@ -3025,7 +3152,7 @@ Pass 'component' only when the user explicitly asks to inspect or customise a
 specific component's source code. In that mode the tool returns the requested
 components, a scoped install command, and their source code.`,
       inputSchema: z4.object({
-        designSystemId: z4.string().describe("The design system ID from find-design"),
+        designSystemId: z4.string().describe("The design system ID from find-design-system"),
         component: z4.union([z4.string(), z4.array(z4.string())]).optional().describe('Optional. Only pass this when the user asks to inspect specific component source code. Examples: "button", ["button", "card"]. Omit to scaffold the entire design system.')
       }),
       outputSchema: PREVIEW_OUTPUT_SCHEMA,
@@ -3167,17 +3294,17 @@ components, a scoped install command, and their source code.`,
       title: "Create a New Design System",
       description: `Generate a brand new design system tailored to the user's product, and return a single shadcn install command that lands the entire set of components + tokens (globals.css) into the user's Next.js project.
 
-**Use this PROACTIVELY on any "build/make me <app>" request \u2014 even when the user never mentions design or branding.** A design system IS the app's brand/visual identity, so creating one first is the right first step for building an app: derive the \`prompt\` from the app (its name, domain, and vibe), generate the brand, show it with \`check-design-system-status\`, then build the app with that brand. Also use it when the user explicitly wants a **custom** design system instead of installing an existing one via 'get-design-system-docs'.
+**Use this PROACTIVELY on any "build/make me <app>" request \u2014 even when the user never mentions design or branding.** A design system IS the app's brand/visual identity, so creating one first is the right first step for building an app: derive the \`prompt\` from the app (its name, domain, and vibe), generate the brand, show it with \`get-design-system-status\`, then build the app with that brand. Also use it when the user explicitly wants a **custom** design system instead of installing an existing one via 'get-design-system-docs'.
 
 How it works:
 1. Sends the user's prompt to Better Design's generation pipeline (same flow the web chat input uses) and returns IMMEDIATELY with the project id + project URL.
 2. Generation runs in the background and typically takes 1-3 minutes.
-3. Call \`check-design-system-status\` with the returned project id (wait ~60 seconds first) to get the live preview URL and the final \`npx shadcn add <registry-url>\` install command once it completes.
+3. Call \`get-design-system-status\` with the returned project id (wait ~60 seconds first) to get the live preview URL and the final \`npx shadcn add <registry-url>\` install command once it completes.
 
 Share the project URL with the user right away so they can watch the generation live.`,
       inputSchema: z4.object({
         prompt: z4.string().min(1).max(1e4).describe("Describe the design system the user wants. E.g. 'A warm, minimal design system for a personal finance app, soft pastels, rounded corners' or 'A brutalist developer tool aesthetic with sharp edges and monospace type'."),
-        baseDesignSystemId: z4.string().optional().describe("Optional. Pass a design system ID from `find-design` to bias generation toward an existing aesthetic (e.g. apply a theme tweak on top of Linear). Leave empty for a fully custom DS.")
+        baseDesignSystemId: z4.string().optional().describe("Optional. Pass a design system ID from `find-design-system` to bias generation toward an existing aesthetic (e.g. apply a theme tweak on top of Linear). Leave empty for a fully custom DS.")
       }),
       annotations: {
         readOnlyHint: false,
@@ -3223,126 +3350,128 @@ Share the project URL with the user right away so they can watch the generation
         ...authContext ? [`Saved to your Better Design account. Watch it generate live:`] : [`Watch it generate live:`],
         projectUrl,
         "",
-        `Generation takes 1-3 minutes. Share the project link with the user now, wait ~60 seconds, then call \`check-design-system-status\` with the project id to get the live preview URL and the final install command.`,
+        `Generation takes 1-3 minutes. Share the project link with the user now, wait ~60 seconds, then call \`get-design-system-status\` with the project id to get the live preview URL and the final install command.`,
         inlineBuildMd(projectId)
       ];
       return { content: [{ type: "text", text: lines.join("\n") }] };
     })
   );
-  server.registerTool(
-    "check-design-system-status",
-    {
-      title: "Check Design System Generation Status",
-      description: `Check on a design system generation started with 'create-design-system'. Returns progress while generating, and the live preview URL + the \`npx shadcn add\` install command once complete. Generation typically takes 1-3 minutes; poll every ~30 seconds until it reports ready.`,
-      inputSchema: z4.object({
-        projectId: z4.string().min(1).describe("The project id returned by create-design-system.")
-      }),
-      outputSchema: PREVIEW_OUTPUT_SCHEMA,
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        openWorldHint: false
-      },
-      _meta: {
-        ui: { resourceUri: DS_PREVIEW_WIDGET_URI },
-        "ui/resourceUri": DS_PREVIEW_WIDGET_URI,
-        "openai/outputTemplate": DS_PREVIEW_WIDGET_URI,
-        "openai/toolInvocation/invoking": "Checking your design system...",
-        "openai/toolInvocation/invoked": "Design system status ready"
-      }
-    },
-    async ({ projectId }) => tracked("check-design-system-status", {}, async () => {
-      const headers = {};
-      if (authContext) {
-        const bearer2 = authContext.kind === "api-key" ? authContext.apiKey : authContext.accessToken;
-        headers.Authorization = `Bearer ${bearer2}`;
-      }
-      const statusUrl = `${APP_BASE_URL}/api/projects/${projectId}`;
-      let project;
-      try {
-        const res = await fetch(statusUrl, { headers });
-        if (!res.ok) {
-          return { content: [{ type: "text", text: `Could not read project ${projectId} (HTTP ${res.status}). Check the id, or view it at ${APP_BASE_URL}/projects/${projectId}.` }] };
-        }
-        project = await res.json();
-      } catch (err) {
-        return { content: [{ type: "text", text: `Network error calling ${statusUrl}: ${err instanceof Error ? err.message : String(err)}` }] };
+  const runDesignSystemStatus = async (projectId) => {
+    const headers = {};
+    if (authContext) {
+      const bearer2 = authContext.kind === "api-key" ? authContext.apiKey : authContext.accessToken;
+      headers.Authorization = `Bearer ${bearer2}`;
+    }
+    const statusUrl = `${APP_BASE_URL}/api/projects/${projectId}`;
+    let project;
+    try {
+      const res = await fetch(statusUrl, { headers });
+      if (!res.ok) {
+        return { content: [{ type: "text", text: `Could not read project ${projectId} (HTTP ${res.status}). Check the id, or view it at ${APP_BASE_URL}/projects/${projectId}.` }] };
       }
-      const projectUrl = `${APP_BASE_URL}/projects/${projectId}`;
-      if (project.designSystemStatus === "COMPLETED") {
-        const registryUrl = `${APP_BASE_URL}/api/projects/${projectId}/registry/all.json`;
-        let body = `\`\`\`bash
+      project = await res.json();
+    } catch (err) {
+      return { content: [{ type: "text", text: `Network error calling ${statusUrl}: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+    const projectUrl = `${APP_BASE_URL}/projects/${projectId}`;
+    if (project.designSystemStatus === "COMPLETED") {
+      const registryUrl = `${APP_BASE_URL}/api/projects/${projectId}/registry/all.json`;
+      let body = `\`\`\`bash
 npx shadcn@latest add ${registryUrl}
 \`\`\``;
-        let tokensCss = "";
-        let dsName = `Project ${projectId.slice(0, 8)}`;
-        try {
-          const res = await fetch(registryUrl);
-          if (res.ok) {
-            const json = await res.json();
-            if (json.meta?.installInstructions) body = json.meta.installInstructions;
-            tokensCss = tokensCssFromRegistry(json);
-            if (project.name) dsName = project.name;
-            else if (json.name) dsName = json.name;
-          }
-        } catch {
+      let tokensCss = "";
+      let dsName = `Project ${projectId.slice(0, 8)}`;
+      try {
+        const res = await fetch(registryUrl);
+        if (res.ok) {
+          const json = await res.json();
+          if (json.meta?.installInstructions) body = json.meta.installInstructions;
+          tokensCss = tokensCssFromRegistry(json);
+          if (project.name) dsName = project.name;
+          else if (json.name) dsName = json.name;
         }
-        const lines = [
-          `# Design system ready`,
-          "",
-          ...authContext ? [`Saved to your Better Design account. View, preview, and re-grab the install command anytime here:`] : [`View and preview your design system anytime here:`],
-          projectUrl,
-          "",
-          `Project id: \`${projectId}\``,
-          "",
-          `To install it into a local project (Cursor, Claude Code, a checked-out repo):`,
-          "",
-          REQUIREMENTS_MD,
-          body,
-          ANTI_MOCKUP_MD,
-          inlineBuildMd(projectId),
-          "",
-          `In a real codebase, run the install above; do NOT hand-build an HTML/React copy of the components. The preview widget already shows it, and ${projectUrl} has the full showcase.`
-        ];
-        return {
-          content: [{ type: "text", text: lines.join("\n") }],
-          structuredContent: {
-            status: "completed",
-            name: dsName,
-            viewUrl: projectUrl,
-            installCommand: `npx shadcn@latest add ${registryUrl}`,
-            tokensCss
-          }
-        };
-      }
-      if (project.designSystemStatus === "ERROR") {
-        return {
-          content: [{ type: "text", text: `Generation failed for project ${projectId}. Last step: ${project.currentStep ?? "(none)"}. The user can retry from ${projectUrl}.` }],
-          structuredContent: { status: "error", name: `Project ${projectId.slice(0, 8)}`, viewUrl: projectUrl, tokensCss: "" }
-        };
+      } catch {
       }
-      const step = project.currentStep ? project.currentStep.replace(/^[a-z]+:/, "") : void 0;
-      const stepNote = step ? ` Current step: ${step}.` : "";
+      const lines = [
+        `# Design system ready`,
+        "",
+        ...authContext ? [`Saved to your Better Design account. View, preview, and re-grab the install command anytime here:`] : [`View and preview your design system anytime here:`],
+        projectUrl,
+        "",
+        `Project id: \`${projectId}\``,
+        "",
+        `To install it into a local project (Cursor, Claude Code, a checked-out repo):`,
+        "",
+        REQUIREMENTS_MD,
+        body,
+        ANTI_MOCKUP_MD,
+        inlineBuildMd(projectId),
+        "",
+        `In a real codebase, run the install above; do NOT hand-build an HTML/React copy of the components. The preview widget already shows it, and ${projectUrl} has the full showcase.`
+      ];
+      const previewUrl = project.previewFragmentId ? `${APP_BASE_URL}/preview/${project.previewFragmentId}` : projectUrl;
+      const shotUrl = project.previewFragmentId ? `${APP_BASE_URL}/api/og/preview?fragment=${project.previewFragmentId}` : void 0;
       return {
-        content: [{ type: "text", text: `Still generating (status: ${project.designSystemStatus ?? "PENDING"}).${stepNote}
-Check again in ~30 seconds. Watch it live on the project page: ${projectUrl}` }],
+        content: [{ type: "text", text: lines.join("\n") }],
         structuredContent: {
-          status: (project.designSystemStatus ?? "PENDING").toLowerCase(),
-          name: `Project ${projectId.slice(0, 8)}`,
+          status: "completed",
+          name: dsName,
           viewUrl: projectUrl,
-          step,
-          tokensCss: ""
+          previewUrl,
+          ...shotUrl ? { shotUrl } : {},
+          installCommand: `npx shadcn@latest add ${registryUrl}`,
+          tokensCss
         }
       };
-    })
+    }
+    if (project.designSystemStatus === "ERROR") {
+      return {
+        content: [{ type: "text", text: `Generation failed for project ${projectId}. Last step: ${project.currentStep ?? "(none)"}. The user can retry from ${projectUrl}.` }],
+        structuredContent: { status: "error", name: `Project ${projectId.slice(0, 8)}`, viewUrl: projectUrl, tokensCss: "" }
+      };
+    }
+    const step = project.currentStep ? project.currentStep.replace(/^[a-z]+:/, "") : void 0;
+    const stepNote = step ? ` Current step: ${step}.` : "";
+    return {
+      content: [{ type: "text", text: `Still generating (status: ${project.designSystemStatus ?? "PENDING"}).${stepNote}
+Check again in ~30 seconds. Watch it live on the project page: ${projectUrl}` }],
+      structuredContent: {
+        status: (project.designSystemStatus ?? "PENDING").toLowerCase(),
+        name: `Project ${projectId.slice(0, 8)}`,
+        viewUrl: projectUrl,
+        step,
+        tokensCss: ""
+      }
+    };
+  };
+  const statusConfig = {
+    title: "Get Design System Generation Status",
+    description: `Check on a design system generation started with 'create-design-system'. Returns progress while generating, and the live preview URL + the \`npx shadcn add\` install command once complete. Generation typically takes 1-3 minutes; poll every ~30 seconds until it reports ready.`,
+    inputSchema: z4.object({
+      projectId: z4.string().min(1).describe("The project id returned by create-design-system.")
+    }),
+    outputSchema: PREVIEW_OUTPUT_SCHEMA,
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    _meta: {
+      ui: { resourceUri: DS_PREVIEW_WIDGET_URI },
+      "ui/resourceUri": DS_PREVIEW_WIDGET_URI,
+      "openai/outputTemplate": DS_PREVIEW_WIDGET_URI,
+      "openai/toolInvocation/invoking": "Checking your design system...",
+      "openai/toolInvocation/invoked": "Design system status ready"
+    }
+  };
+  server.registerTool(
+    "get-design-system-status",
+    statusConfig,
+    ({ projectId }) => tracked("get-design-system-status", {}, () => runDesignSystemStatus(projectId))
   );
   server.registerTool(
     "preview-design-system",
     {
       title: "Preview a Design System",
-      description: `Show the user a visual preview of a design system from the catalog (use the id from 'find-design'). Returns a token-true HTML preview: palette, typography, buttons, card, input, badge, plus a link to the full live showcase. Use this when the user wants to SEE a design system before installing it.`,
+      description: `Show the user a visual preview of a design system from the catalog (use the id from 'find-design-system'). Returns a token-true HTML preview: palette, typography, buttons, card, input, badge, plus a link to the full live showcase. Use this when the user wants to SEE a design system before installing it.`,
       inputSchema: z4.object({
-        designSystemId: z4.string().min(1).describe("Design system id from find-design, e.g. 'linear', 'editorial-warm'.")
+        designSystemId: z4.string().min(1).describe("Design system id from find-design-system, e.g. 'linear', 'editorial-warm'.")
       }),
       outputSchema: PREVIEW_OUTPUT_SCHEMA,
       annotations: {
@@ -3362,7 +3491,7 @@ Check again in ~30 seconds. Watch it live on the project page: ${projectUrl}` }]
       const ds = await provider.getDesignSystemById(designSystemId);
       if (!ds) {
         return {
-          content: [{ type: "text", text: `Design system "${designSystemId}" not found. Call find-design first to get a valid id.` }],
+          content: [{ type: "text", text: `Design system "${designSystemId}" not found. Call find-design-system first to get a valid id.` }],
           structuredContent: { status: "error", name: designSystemId, tokensCss: "" }
         };
       }
@@ -3403,12 +3532,12 @@ Check again in ~30 seconds. Watch it live on the project page: ${projectUrl}` }]
       title: "Get a Design System as HTML/CSS",
       description: `Export a design system as plain, framework-free HTML + CSS for building an app INLINE (ChatGPT canvas / Claude artifact) where npm and a Tailwind build are unavailable. Returns the system's real design tokens (globals.css) plus a token-driven component CSS kit (button, input, card, badge, alert, etc.) and an example to riff on.
 
-Works for BOTH a catalog system (pass \`designSystemId\` from find-design) AND a custom system you just generated (pass \`projectId\` from create-design-system / check-design-system-status).
+Works for BOTH a catalog system (pass \`designSystemId\` from find-design-system) AND a custom system you just generated (pass \`projectId\` from create-design-system / get-design-system-status).
 
 ${BUILD_TARGET_RULE}`,
       inputSchema: z4.object({
-        designSystemId: z4.string().min(1).optional().describe("Catalog design system id from find-design, e.g. 'linear', 'editorial-warm'. Pass this OR projectId."),
-        projectId: z4.string().min(1).optional().describe("Project id from create-design-system / check-design-system-status, for a custom generated DS. Pass this OR designSystemId.")
+        designSystemId: z4.string().min(1).optional().describe("Catalog design system id from find-design-system, e.g. 'linear', 'editorial-warm'. Pass this OR projectId."),
+        projectId: z4.string().min(1).optional().describe("Project id from create-design-system / get-design-system-status, for a custom generated DS. Pass this OR designSystemId.")
       }),
       annotations: {
         readOnlyHint: true,
@@ -3431,17 +3560,31 @@ ${BUILD_TARGET_RULE}`,
       }
       if (!designSystemId) {
         return {
-          content: [{ type: "text", text: "Pass either a catalog designSystemId (from find-design) or a projectId (from create-design-system)." }]
+          content: [{ type: "text", text: "Pass either a catalog designSystemId (from find-design-system) or a projectId (from create-design-system)." }]
         };
       }
       const ds = await provider.getDesignSystemById(designSystemId);
       if (!ds) {
         return {
-          content: [{ type: "text", text: `Design system "${designSystemId}" not found. Call find-design first to get a valid id, or pass a projectId for a generated system.` }]
+          content: [{ type: "text", text: `Design system "${designSystemId}" not found. Call find-design-system first to get a valid id, or pass a projectId for a generated system.` }]
         };
       }
-      const { tokensCss, files } = await fetchCatalog(designSystemId);
       const viewUrl = `${APP_BASE_URL}/design-systems/${designSystemId}`;
+      const host = codingHostName(server);
+      const steer = host ? `> \u26A0\uFE0F **You appear to be in ${host}, a coding environment with a filesystem.** Build this as real React components: call \`get-design-system-docs\` and run the shadcn install instead of shipping a standalone HTML file. The kit below is only for inline chat canvases (ChatGPT / Claude artifacts) that cannot run a build.
+
+` : "";
+      if (ds.metadata.html) {
+        const intro = `Framework-free HTML/CSS version of **${ds.metadata.title}**. One self-contained document: every component rendered with the exact compiled CSS inline, no JS, no build. Render it directly in a ChatGPT canvas / Claude artifact, or lift the markup + \`<style>\` you need. Full live showcase: ${viewUrl}
+
+`;
+        const longestRun = Math.max(0, ...[...ds.metadata.html.matchAll(/`+/g)].map((m) => m[0].length));
+        const fence2 = "`".repeat(Math.max(3, longestRun + 1));
+        return { content: [{ type: "text", text: `${steer}${intro}${fence2}html
+${ds.metadata.html}
+${fence2}` }] };
+      }
+      const { tokensCss, files } = await fetchCatalog(designSystemId);
       if (!tokensCss) {
         return {
           content: [{ type: "text", text: `Could not load tokens for "${designSystemId}". The full live showcase is at ${viewUrl}.` }]
@@ -3449,10 +3592,6 @@ ${BUILD_TARGET_RULE}`,
       }
       const componentKit = buildDsComponentCss(files);
       const text = buildDsHtmlKit({ name: ds.metadata.title, tokensCss, viewUrl, componentKit });
-      const host = codingHostName(server);
-      const steer = host ? `> \u26A0\uFE0F **You appear to be in ${host}, a coding environment with a filesystem.** Build this as real React components: call \`get-design-system-docs\` and run the shadcn install instead of shipping a standalone HTML file. The kit below is only for inline chat canvases (ChatGPT / Claude artifacts) that cannot run a build.
-
-` : "";
       return { content: [{ type: "text", text: steer + text }] };
     })
   );
@@ -3598,9 +3737,12 @@ __export(api_client_exports, {
 import { createHash as createHash2 } from "crypto";
 async function request(path4) {
   if (!API_KEY) {
-    throw new ApiError(401, "BETTER_DESIGN_API_KEY is not set. Get one at https://better-design.com/mcp");
+    throw new ApiError(
+      401,
+      "BETTER_DESIGN_API_KEY is not set. Run `npx better-design` to create a free key (no account needed), or get one at https://better-design.com/mcp"
+    );
   }
-  const res = await fetch(`${API_URL}/api${path4}`, {
+  const res = await fetch(`${API_URL2}/api${path4}`, {
     headers: {
       Authorization: `Bearer ${API_KEY}`,
       "Content-Type": "application/json"
@@ -3661,7 +3803,7 @@ async function getReviewRules(category = "all") {
   return request(`/v1/review-rules${params}`);
 }
 function postAlert(body) {
-  fetch(`${API_URL}/api/internal/alert`, {
+  fetch(`${API_URL2}/api/internal/alert`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body),
@@ -3693,11 +3835,11 @@ function trackMcpInstalled(opts) {
     mcpVersion: process.env.npm_package_version
   });
 }
-var API_URL, API_KEY, API_KEY_HASH, ApiError;
+var API_URL2, API_KEY, API_KEY_HASH, ApiError;
 var init_api_client = __esm({
   "src/lib/api-client.ts"() {
     "use strict";
-    API_URL = process.env.API_URL ?? "https://better-design.com";
+    API_URL2 = process.env.API_URL ?? "https://better-design.com";
     API_KEY = process.env.BETTER_DESIGN_API_KEY;
     API_KEY_HASH = API_KEY ? createHash2("sha256").update(API_KEY).digest("hex") : void 0;
     ApiError = class extends Error {
@@ -3784,9 +3926,9 @@ var init_http_data_provider = __esm({
 // src/index.ts
 var argv = process.argv.slice(2);
 var command = argv[0];
-if (command === "setup" || !command) {
+if (!command || command.startsWith("-") || command === "setup") {
   const { runSetup: runSetup2 } = await Promise.resolve().then(() => (init_setup(), setup_exports));
-  runSetup2(argv.slice(1)).catch((error) => {
+  runSetup2(argv).catch((error) => {
     console.error(error);
     process.exit(1);
   });