fix: correct tool shapes, installer hang, and the half-built non-Stitch source paths

AGENTS.md

@@ -4,7 +4,7 @@ Guidance for Claude Code, Cursor, Copilot, Codex CLI, and other AI agents workin
 
 ## What this repo is
 
-A collection of Claude Code **skills** — 35 packaged instructions and scripts that extend AI agents with Stitch-specific capabilities: text-to-UI generation, design iteration (edit, variants, design systems), design token extraction, and multi-framework conversion. Think of it as a Stitch co-pilot that wraps 13 of the 15 Stitch MCP tools and knows the footguns so you don't have to learn them the hard way.
+A collection of Claude Code **skills** — 36 packaged instructions and scripts that extend AI agents with Stitch-specific capabilities: text-to-UI generation, design iteration (edit, variants, design systems), design token extraction, and multi-framework conversion. Think of it as a Stitch co-pilot that wraps all 15 Stitch MCP tools and knows the footguns so you don't have to learn them the hard way.
 
 ## Skill structure
 
@@ -15,7 +15,7 @@ skills/{skill-name}/
 ├── SKILL.md              ← Required: activation instructions and workflow
 ├── examples/             ← Required: worked examples (gold-standard reference)
 ├── resources/            ← Optional: templates, checklists, mapping tables
-├── scripts/              ← Optional: bash scripts (fetch-stitch.sh, encode-image.sh, etc.)
+├── scripts/              ← Optional: bash scripts (fetch-stitch.sh, init_stitch_skill.py, etc.)
 └── references/           ← Optional: style guides, contracts
 ```
 
@@ -88,7 +88,7 @@ For Stitch-based UI generation, load **`stitch-orchestrator`** or invoke the **`
 | Layer | Count | Purpose |
 |-------|-------|---------|
 | **Brain** (`stitch-ui-*`, `stitch-ideate`) | 5 | Design intelligence — ideation agent, specs, prompts, variants, UED guide |
-| **Hands** (`stitch-mcp-*`) | 13 | MCP wrappers — one per Stitch API tool, handles ID format rules |
+| **Hands** (`stitch-mcp-*`) | 15 | MCP wrappers — one per Stitch API tool, handles ID format rules |
 | **Conversion** | 7+ | Stitch HTML → framework components (Next.js, Svelte, React, HTML, RN, SwiftUI, shadcn) |
 | **Quality** | 3 | Design tokens, accessibility audit, animations |
 
@@ -98,7 +98,7 @@ Skills marked `allowed-tools: ["stitch*:*"]` require the **Stitch MCP Server** c
 
 Setup guide: https://stitch.withgoogle.com/docs/mcp/setup
 
-13 of the 15 Stitch MCP tools wrapped: `create_project`, `get_project`, `delete_project`, `list_projects`, `generate_screen_from_text`, `edit_screens`, `generate_variants`, `list_screens`, `get_screen`, `create_design_system`, `update_design_system`, `list_design_systems`, `apply_design_system`
+All 15 Stitch MCP tools wrapped: `create_project`, `get_project`, `delete_project`, `list_projects`, `generate_screen_from_text`, `edit_screens`, `generate_variants`, `list_screens`, `get_screen`, `create_design_system`, `update_design_system`, `list_design_systems`, `apply_design_system`, `upload_design_md`, `create_design_system_from_design_md`
 
 Without MCP: the orchestrator falls back to prompt-only mode (generates ready-to-copy Stitch prompts instead of running the full workflow — still useful, just slower).
 
@@ -113,6 +113,8 @@ Without MCP: the orchestrator falls back to prompt-only mode (generates ready-to
 | `stitch-mcp-edit-screens` | Edit existing screens with text prompts (iteration) |
 | `stitch-mcp-generate-variants` | Generate design alternatives with creativity controls |
 | `stitch-mcp-create-design-system` | Create reusable Stitch Design Systems |
+| `stitch-mcp-upload-design-md` | Upload a DESIGN.md into a project (pairs with the next row) |
+| `stitch-mcp-create-design-system-from-design-md` | Turn an uploaded DESIGN.md into a design system |
 | `stitch-mcp-apply-design-system` | Apply design systems to screens |
 | `stitch-mcp-get-screen` | Retrieve screen HTML + screenshot by ID |
 | `stitch-design-system` | Extract design tokens → CSS + Tailwind files |
@@ -131,7 +133,7 @@ Without MCP: the orchestrator falls back to prompt-only mode (generates ready-to
 
 See [`docs/`](docs/) for:
 - `skills-index.md` — complete skills table with descriptions and layers
-- `mcp-schemas/` — JSON Schema for the 13 Stitch MCP tools this repo wraps
+- `mcp-schemas/` — JSON Schema for all 15 Stitch MCP tools
 - `color-prompt-guide.md` — 8 ready-to-use color palette prompts for Stitch
 - `tailwind-reference.md` — Tailwind utility class reference for conversions
 - `mcp-naming-convention.md` — MCP tool name → skill name mapping

README.md

@@ -152,7 +152,9 @@ Without stitch-kit, your agent sends Stitch a half-baked prompt, gets confused b
 
 ## Ship to any framework
 
-**Works on any HTML, not just Stitch output.** Each conversion skill takes a Stitch screen, a local HTML file, or a URL — point it at a template you bought, a page you already built, or something a different tool generated, and you get the same production components with dark mode, design tokens, TypeScript, and ARIA. Only the Stitch route needs an API key.
+**Works on any HTML, not just Stitch output.** Each conversion skill takes a Stitch screen, a local HTML file, or a URL — point it at a template you bought, a page you already built, or something a different tool generated. Only the Stitch route needs an API key.
+
+Every target gets dark mode and design tokens. The rest depends on where you're shipping: TypeScript and ARIA on the web targets, Swift and native accessibility APIs on SwiftUI, plain semantic HTML with no build step on the HTML target.
 
 Pick your target:
 

agents/stitch-kit.md

@@ -14,6 +14,7 @@ You are a Stitch design-to-code specialist. You handle the full pipeline from UI
 - Edit existing screens with text prompts (edit_screens) — iterate without regenerating
 - Generate design variants with configurable creativity and aspect controls (generate_variants)
 - Create, update, list, and apply Stitch Design Systems for cross-screen consistency
+- Turn a DESIGN.md into a Stitch Design System (upload_design_md, then create_design_system_from_design_md — always both)
 - Convert Stitch HTML to Next.js 15 App Router, Svelte 5, Vite+React, HTML5, React Native/Expo, or SwiftUI
 - Extract design tokens → CSS custom properties (light + dark mode)
 - Build multi-page sites iteratively with the stitch-loop baton pattern
@@ -69,9 +70,11 @@ Stitch uses inconsistent ID formats across tools. Use the `stitch-mcp-*` wrapper
 | `edit_screens` | Numeric | Numeric array | — |
 | `generate_variants` | Numeric | Numeric array | — |
 | `create_design_system` | Numeric (optional) | — | Returns Asset `name` |
+| `upload_design_md` | Numeric | — | Body is base64; `base64 -i` on macOS |
+| `create_design_system_from_design_md` | Numeric | Screen **instance** id + full `sourceScreen` path | Instance id is not the source screen id |
 | `update_design_system` | — | — | Asset `name` required |
 | `list_design_systems` | Numeric (optional) | — | Returns Asset names |
-| `apply_design_system` | Numeric | Numeric array | `assetId` required |
+| `apply_design_system` | Numeric | Screen **instances** (`{id, sourceScreen}`), not bare ids | `assetId` bare numeric, no `assets/` prefix |
 
 ## Framework selection guide
 

bin/stitch-kit.mjs

@@ -55,12 +55,27 @@ function logErr(msg) { console.error(`  ✗ ${msg}`); }
 
 /**
  * Prompt the user for input via stdin.
+ *
+ * Resolves to an empty string whenever there's nobody to answer — no TTY, or
+ * stdin hits EOF. Callers treat empty as "skipped", which is what we want in
+ * CI, Docker, and `npx ... < /dev/null`: carry on with the rest of the install
+ * rather than hanging.
+ *
  * @param {string} question - The question to display
- * @returns {Promise<string>} The user's input (trimmed)
+ * @returns {Promise<string>} The user's input (trimmed), or '' if unanswerable
  */
 function prompt(question) {
+  // Non-interactive stdin: readline would wait forever for input that can't
+  // arrive. Skip straight to the default instead.
+  if (!process.stdin.isTTY) return Promise.resolve('');
+
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
+    // `close` fires on EOF (ctrl-D, or a pipe closing). Without this the
+    // question callback never runs, the promise never settles, and node exits
+    // mid-install with "Detected unsettled top-level await" — an install that
+    // silently did nothing.
+    rl.on('close', () => resolve(''));
     rl.question(question, (answer) => {
       rl.close();
       resolve(answer.trim());

docs/mcp-schemas/README.md

@@ -1,6 +1,6 @@
 # Stitch MCP API Schemas
 
-Formal JSON Schema definitions for the 13 Stitch MCP tools this repo wraps.
+Formal JSON Schema definitions for the 15 Stitch MCP tools this repo wraps.
 
 Each file documents the full `arguments` (input) and `outputSchema` (output) for one tool.
 
@@ -34,7 +34,9 @@ Each file documents the full `arguments` (input) and `outputSchema` (output) for
 | `create_design_system.json` | `create_design_system` | Create a reusable design system. Optional numeric `projectId`. |
 | `update_design_system.json` | `update_design_system` | Update an existing design system. Requires asset `name`. |
 | `list_design_systems.json` | `list_design_systems` | List available design systems. Optional numeric `projectId`. |
-| `apply_design_system.json` | `apply_design_system` | Apply a design system to screens. **Numeric IDs** + `assetId`. |
+| `apply_design_system.json` | `apply_design_system` | Apply a design system to screens. Screen **instances** (`{id, sourceScreen}`) + bare `assetId`. |
+| `upload_design_md.json` | `upload_design_md` | Upload a DESIGN.md into a project. Numeric `projectId`, base64 body. |
+| `create_design_system_from_design_md.json` | `create_design_system_from_design_md` | Turn an uploaded DESIGN.md into a design system. Numeric `projectId` + screen instance. |
 
 ---
 
@@ -154,8 +156,10 @@ Useful for: targeted HTML extraction, component-level conversion, design audits.
 | `list_screens` | `projects/NUMERIC` | — | — |
 | `get_screen` | **NUMERIC only** | **NUMERIC only** | — |
 | `create_design_system` | **NUMERIC** (optional) | — | Returns Asset `name` |
-| `update_design_system` | — | — | Asset `name` required |
+| `update_design_system` | — | — | Asset `name` (prefixed) required |
 | `list_design_systems` | **NUMERIC** (optional) | — | Returns Asset names |
-| `apply_design_system` | **NUMERIC only** | **NUMERIC array** | `assetId` required |
+| `apply_design_system` | **NUMERIC only** | Screen **instances** (`{id, sourceScreen}`) | `assetId` bare numeric, no prefix |
+| `upload_design_md` | **NUMERIC only** | — | Body is base64 |
+| `create_design_system_from_design_md` | **NUMERIC only** | Screen **instance** (`{id, sourceScreen}`) | — |
 
 See `../mcp-naming-convention.md` for the full breakdown.

docs/mcp-schemas/apply_design_system.json

@@ -1,24 +1,30 @@
 {
   "name": "apply_design_system",
-  "description": "Applies a Stitch Design System to one or more existing screens, updating their visual theme.\n\n**Input Requirements (CRITICAL):**\n1. **`projectId` (string - MANDATORY):** Numeric ID only.\n2. **`selectedScreenIds` (array - MANDATORY):** Numeric screen IDs.\n3. **`assetId` (string - MANDATORY):** Design system asset identifier.\n",
+  "description": "Applies a Stitch Design System to one or more existing screens, updating their visual theme.\n\n**Input Requirements (CRITICAL):**\n1. **`projectId` (string - MANDATORY):** Numeric ID only, no `projects/` prefix.\n2. **`selectedScreenInstances` (array of objects - MANDATORY):** Screen INSTANCES, each `{id, sourceScreen}`. NOT an array of bare screen ids. `id` is the screen instance id (from get_project's screenInstances), NOT the source screen id; `sourceScreen` is the full `projects/{p}/screens/{s}` path.\n3. **`assetId` (string - MANDATORY):** Bare numeric asset id, WITHOUT the `assets/` prefix.\n",
   "arguments": {
     "type": "object",
     "properties": {
       "projectId": {
         "description": "Required. Numeric project ID only — do NOT include 'projects/' prefix.",
         "type": "string"
       },
-      "selectedScreenIds": {
-        "description": "Required. Array of numeric screen IDs to apply the design system to.",
-        "type": "array",
-        "items": { "type": "string" }
-      },
       "assetId": {
-        "description": "Required. The design system asset identifier from list or create operations.",
+        "description": "Required. The asset id of the design system to apply, can be fetched from `list_design_systems`. Example: '15996705518239280238', without the `assets/` prefix.",
         "type": "string"
+      },
+      "selectedScreenInstances": {
+        "description": "Required. The screen instances to edit, which is available in the Project info, fetched by `get_project`. NOT bare screen ids.",
+        "type": "array",
+        "items": {
+          "$ref": "#/$defs/SelectedScreenInstance"
+        }
       }
     },
-    "required": ["projectId", "selectedScreenIds", "assetId"],
+    "required": [
+      "projectId",
+      "selectedScreenInstances",
+      "assetId"
+    ],
     "description": "Request message for ApplyDesignSystem."
   },
   "outputSchema": {
@@ -28,9 +34,33 @@
         "description": "Array of output components with updated screen data.",
         "type": "array"
       },
-      "projectId": { "type": "string" },
-      "sessionId": { "type": "string" }
+      "projectId": {
+        "type": "string"
+      },
+      "sessionId": {
+        "type": "string"
+      }
     },
     "description": "Response message for ApplyDesignSystem."
+  },
+  "$defs": {
+    "SelectedScreenInstance": {
+      "type": "object",
+      "description": "A screen instance to be edited by the agent, selected by the user.",
+      "properties": {
+        "id": {
+          "description": "Required. The id of the screen instance, NOT the source screen id. Available in screenInstances from `get_project`.",
+          "type": "string"
+        },
+        "sourceScreen": {
+          "description": "Required. The resource name of the source screen. Format: projects/{project}/screens/{screen}",
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "sourceScreen"
+      ]
+    }
   }
 }

docs/mcp-schemas/create_design_system.json

@@ -28,14 +28,6 @@
           "theme": {
             "$ref": "#/$defs/DesignTheme",
             "description": "Required. Visual theme configuration."
-          },
-          "designTokens": {
-            "description": "Optional. CSS custom properties or token definitions.",
-            "type": "string"
-          },
-          "styleGuidelines": {
-            "description": "Optional. Natural-language design rules.",
-            "type": "string"
           }
         },
         "required": [
@@ -71,20 +63,6 @@
             "description": "Primary color (hex).",
             "type": "string"
           },
-          "backgroundLight": {
-            "description": "Light mode background (hex).",
-            "type": "string"
-          },
-          "backgroundDark": {
-            "description": "Dark mode background (hex).",
-            "type": "string"
-          },
-          "preset": {
-            "type": "string"
-          },
-          "description": {
-            "type": "string"
-          },
           "colorVariant": {
             "enum": [
               "COLOR_VARIANT_UNSPECIFIED",
@@ -319,15 +297,6 @@
             ],
             "type": "string"
           },
-          "namedColors": {
-            "type": "object",
-            "description": "Semantic color map (40+ tokens like primary, on_primary, surface, etc.)"
-          },
-          "spacingScale": {
-            "format": "int32",
-            "type": "integer",
-            "description": "0=minimal, 1=compact, 2=normal, 3=spacious"
-          },
           "designMd": {
             "type": "string",
             "description": "Auto-generated markdown design system document"
@@ -360,6 +329,13 @@
             "description": "Optional. Map of typography level name (e.g. \"h1\", \"body\") to Typography token overrides."
           }
         },
+        "required": [
+          "colorMode",
+          "headlineFont",
+          "bodyFont",
+          "roundness",
+          "customColor"
+        ],
         "type": "object"
       },
       "Typography": {

docs/mcp-schemas/create_design_system_from_design_md.json

@@ -24,25 +24,31 @@
         ]
       }
     },
-    "required": ["projectId", "selectedScreenInstance"],
-    "description": "Request message for CreateDesignSystemFromDesignMd."
-  },
-  "$defs": {
-    "SelectedScreenInstance": {
-      "type": "object",
-      "description": "A screen instance to be edited by the agent, selected by the user.",
-      "properties": {
-        "id": {
-          "description": "Required. The id of the screen instance, NOT the source screen id. This is available in the screen instances in the Project info, fetched by `get_project`.",
-          "type": "string"
+    "$defs": {
+      "SelectedScreenInstance": {
+        "type": "object",
+        "description": "A screen instance to be edited by the agent, selected by the user.",
+        "properties": {
+          "id": {
+            "description": "Required. The id of the screen instance, NOT the source screen id. This is available in the screen instances in the Project info, fetched by `get_project`.",
+            "type": "string"
+          },
+          "sourceScreen": {
+            "description": "Required. The source screen of the screen instance. The resource name of the source screen. Format: projects/{project}/screens/{screen}",
+            "type": "string"
+          }
         },
-        "sourceScreen": {
-          "description": "Required. The source screen of the screen instance. The resource name of the source screen. Format: projects/{project}/screens/{screen}",
-          "type": "string"
-        }
-      },
-      "required": ["id", "sourceScreen"]
-    }
+        "required": [
+          "id",
+          "sourceScreen"
+        ]
+      }
+    },
+    "required": [
+      "projectId",
+      "selectedScreenInstance"
+    ],
+    "description": "Request message for CreateDesignSystemFromDesignMd."
   },
   "outputSchema": {
     "type": "object",

docs/mcp-schemas/generate_screen_from_text.json

@@ -32,6 +32,10 @@
       "prompt": {
         "description": "Required. The text prompt describing the screen to generate.",
         "type": "string"
+      },
+      "designSystem": {
+        "description": "Optional. The design system id to use for generating the new screen, should always be configured for design consistency. Takes the `assets/` prefix. Example: 'assets/15996705518239280238'.",
+        "type": "string"
       }
     },
     "required": ["projectId", "prompt"],