@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/scripts/phase1-gather.py

@@ -0,0 +1,1298 @@
+#!/usr/bin/env python3
+"""
+Phase 1 Data Gathering Script
+Replaces the LLM subagent with deterministic Python calls.
+Expected runtime: ~5-15 seconds (vs ~20 minutes with subagent).
+
+Usage:
+    python3 phase1-gather.py \
+        --file-key "ps4xrJzhn7WNbfkZs895Bi" \
+        --node-id "9047:349" \
+        --artifact-path "path/to/ComponentName/" \
+        --component-name "AvatarPassengers" \
+        [--figma-token TOKEN] \
+        [--mcp-token TOKEN] \
+        [--mcp-url "http://127.0.0.1:3845/mcp"]
+
+Exit 0 = success (prints JSON summary to stdout)
+Exit 1 = failure (prints JSON error to stdout)
+"""
+
+import argparse
+import concurrent.futures
+import http.client
+import json
+import os
+import re
+import ssl
+import subprocess
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+
+# ─── Globals ─────────────────────────────────────────────────────────────────
+MCP_MODE = None       # "remote" or "local"
+MCP_URL = None        # local MCP URL (http://127.0.0.1:3845/mcp)
+MCP_TOKEN = None      # OAuth token for remote MCP
+SESSION_ID = None     # local MCP session ID
+FIGMA_TOKEN = None
+FILE_KEY = None
+NODE_ID = None
+COMPONENT_NAME = None
+ARTIFACT_PATH = None
+
+SUBLAYER_CAP = 20     # max sublayers to fetch for get_design_context
+
+
+def log(msg):
+    """Log to stderr so stdout stays clean for JSON output."""
+    print(f"[phase1] {msg}", file=sys.stderr)
+
+
+def halt(gate, reason, completed_gates, artifacts, user_action=""):
+    """Print HALT JSON and exit 1."""
+    print(json.dumps({
+        "status": "HALT",
+        "phase": "phase-1",
+        "gate": gate,
+        "reason": reason,
+        "completed_gates": completed_gates,
+        "artifacts_created": artifacts,
+        "user_action_required": user_action,
+    }, indent=2))
+    sys.exit(1)
+
+
+# ─── HTTP Helpers ────────────────────────────────────────────────────────────
+
+def figma_get(endpoint):
+    """GET from Figma REST API. Returns parsed JSON."""
+    url = f"https://api.figma.com/v1/{endpoint}"
+    req = Request(url, headers={"X-Figma-Token": FIGMA_TOKEN})
+    with urlopen(req, timeout=30) as resp:
+        return json.loads(resp.read().decode())
+
+
+def download_file(url, dest):
+    """Download a URL to a local file path. Returns True on success."""
+    try:
+        req = Request(url)
+        with urlopen(req, timeout=60) as resp:
+            Path(dest).parent.mkdir(parents=True, exist_ok=True)
+            with open(dest, "wb") as f:
+                f.write(resp.read())
+        return True
+    except (URLError, HTTPError) as exc:
+        log(f"Download failed ({dest}): {exc}")
+        return False
+
+
+# ─── MCP Token Resolution ────────────────────────────────────────────────────
+
+def get_mcp_token(cli_token=None):
+    """Resolve MCP OAuth token: CLI arg > Keychain FIGMA_MCP_TOKEN > Claude Code credentials."""
+    if cli_token:
+        return cli_token
+    # Keychain: dedicated entry
+    try:
+        token = subprocess.check_output(
+            ["security", "find-generic-password", "-a", os.environ["USER"],
+             "-s", "FIGMA_MCP_TOKEN", "-w"],
+            stderr=subprocess.DEVNULL,
+        ).decode().strip()
+        if token:
+            log("MCP token from Keychain: FIGMA_MCP_TOKEN")
+            return token
+    except (subprocess.CalledProcessError, KeyError):
+        pass
+    # Keychain: extract from Claude Code credentials
+    try:
+        raw = subprocess.check_output(
+            ["security", "find-generic-password", "-s", "Claude Code-credentials",
+             "-a", os.environ["USER"], "-w"],
+            stderr=subprocess.DEVNULL,
+        ).decode()
+        match = re.search(
+            r'"figma-remote\|[^"]+":\{[^}]*"accessToken":"([^"]+)"', raw
+        )
+        if match:
+            log("MCP token extracted from Claude Code credentials")
+            return match.group(1)
+    except (subprocess.CalledProcessError, KeyError):
+        pass
+    return None
+
+
+def _try_refresh_mcp_token():
+    """Attempt to refresh MCP token using stored refresh_token and fetch-mcp-token.py."""
+    global MCP_TOKEN
+    script = Path(__file__).parent.parent.parent / "figma-setup" / "scripts" / "fetch-mcp-token.py"
+    if not script.exists():
+        # Try relative to repo root
+        script = Path(__file__).resolve()
+        for _ in range(10):
+            script = script.parent
+            candidate = script / ".instructions" / "figma" / "figma-setup" / "scripts" / "fetch-mcp-token.py"
+            if candidate.exists():
+                script = candidate
+                break
+        else:
+            return False
+    try:
+        result = subprocess.run(
+            [sys.executable, str(script), "--verify", "--save-keychain", "--quiet"],
+            capture_output=True, text=True, timeout=30,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            MCP_TOKEN = result.stdout.strip()
+            log("MCP token auto-refreshed via fetch-mcp-token.py")
+            return True
+        else:
+            log(f"MCP token refresh failed (exit {result.returncode})")
+    except Exception as exc:
+        log(f"MCP token refresh error: {exc}")
+    return False
+
+
+# ─── MCP Helpers ─────────────────────────────────────────────────────────────
+
+def _parse_sse_json(raw):
+    """Parse JSON from SSE response. Handles multiline data payloads."""
+    # Find the "data: " prefix
+    data_start = raw.find("\ndata: ")
+    if data_start == -1:
+        data_start = raw.find("data: ")
+    if data_start == -1:
+        return None
+
+    json_str = raw[raw.index("data: ", data_start) + 6:].strip()
+    try:
+        return json.loads(json_str)
+    except json.JSONDecodeError:
+        # JSON may have trailing SSE noise — find balanced braces
+        depth = 0
+        end = 0
+        for i, ch in enumerate(json_str):
+            if ch == "{":
+                depth += 1
+            elif ch == "}":
+                depth -= 1
+                if depth == 0:
+                    end = i + 1
+                    break
+        if end > 0:
+            try:
+                return json.loads(json_str[:end])
+            except json.JSONDecodeError:
+                pass
+    return None
+
+
+def _mcp_post_local(body_dict):
+    """POST to local MCP (HTTP, session-based)."""
+    parsed = urlparse(MCP_URL)
+    conn = http.client.HTTPConnection(parsed.hostname, parsed.port, timeout=120)
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+    }
+    if SESSION_ID:
+        headers["mcp-session-id"] = SESSION_ID
+
+    conn.request("POST", parsed.path, body=json.dumps(body_dict), headers=headers)
+    resp = conn.getresponse()
+    session = resp.getheader("mcp-session-id")
+    raw = resp.read().decode()
+    conn.close()
+
+    result_json = _parse_sse_json(raw)
+    return result_json, session
+
+
+def _mcp_post_remote(body_dict):
+    """POST to remote MCP (HTTPS, Bearer auth, stateless)."""
+    conn = http.client.HTTPSConnection("mcp.figma.com", timeout=120)
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+        "Authorization": f"Bearer {MCP_TOKEN}",
+    }
+
+    conn.request("POST", "/mcp", body=json.dumps(body_dict), headers=headers)
+    resp = conn.getresponse()
+    raw = resp.read().decode()
+    conn.close()
+
+    if resp.status != 200:
+        raise RuntimeError(f"Remote MCP HTTP {resp.status}: {raw[:200]}")
+
+    result_json = _parse_sse_json(raw)
+    return result_json, None
+
+
+def _mcp_post(body_dict):
+    """Route to remote or local MCP based on MCP_MODE."""
+    if MCP_MODE == "remote":
+        return _mcp_post_remote(body_dict)
+    else:
+        return _mcp_post_local(body_dict)
+
+
+def mcp_init():
+    """Initialize MCP connection. Tries remote first, falls back to local."""
+    global MCP_MODE, MCP_TOKEN, SESSION_ID
+
+    init_body = {
+        "jsonrpc": "2.0",
+        "method": "initialize",
+        "params": {
+            "capabilities": {},
+            "clientInfo": {"name": "phase1-gather", "version": "1.0.0"},
+            "protocolVersion": "2025-03-26",
+        },
+        "id": 1,
+    }
+
+    # Try remote first
+    if MCP_TOKEN:
+        try:
+            log("MCP: trying remote (mcp.figma.com)...")
+            result, _ = _mcp_post_remote(init_body)
+            if result:
+                MCP_MODE = "remote"
+                log("MCP: remote connected")
+                return
+        except Exception as exc:
+            log(f"MCP: remote failed ({exc}), attempting token refresh...")
+            # Try auto-refresh before falling back to local
+            if _try_refresh_mcp_token():
+                try:
+                    result, _ = _mcp_post_remote(init_body)
+                    if result:
+                        MCP_MODE = "remote"
+                        log("MCP: remote connected (after token refresh)")
+                        return
+                except Exception as exc2:
+                    log(f"MCP: remote still failed after refresh ({exc2}), trying local...")
+
+    # Fall back to local
+    try:
+        log(f"MCP: trying local ({MCP_URL})...")
+        result, session = _mcp_post_local(init_body)
+        if session:
+            SESSION_ID = session
+            MCP_MODE = "local"
+            log(f"MCP: local connected (session: {SESSION_ID[:12]}...)")
+            return
+    except Exception as exc:
+        raise RuntimeError(f"MCP init failed — remote and local both unavailable. Local error: {exc}")
+
+    raise RuntimeError("MCP init failed — no session from local, no response from remote")
+
+
+_MCP_CALL_ID = 10  # auto-increment per call
+
+
+def mcp_call(tool_name, arguments):
+    """Call an MCP tool. Returns the text content from the result."""
+    global _MCP_CALL_ID
+    _MCP_CALL_ID += 1
+
+    # Remote MCP requires fileKey in every call
+    if MCP_MODE == "remote" and "fileKey" not in arguments:
+        arguments = {**arguments, "fileKey": FILE_KEY}
+
+    body = {
+        "jsonrpc": "2.0",
+        "method": "tools/call",
+        "params": {"name": tool_name, "arguments": arguments},
+        "id": _MCP_CALL_ID,
+    }
+    result_json, _ = _mcp_post(body)
+    if not result_json:
+        raise RuntimeError(f"MCP {tool_name}: empty response")
+    if "error" in result_json:
+        raise RuntimeError(f"MCP {tool_name}: {result_json['error']}")
+
+    # Extract text from content array
+    content_items = (result_json.get("result") or {}).get("content", [])
+    texts = [item.get("text", "") for item in content_items if item.get("type") == "text"]
+    return "\n".join(texts)
+
+
+# ─── Batch 1: Parallel Fetchers ─────────────────────────────────────────────
+
+def fetch_screenshot_url():
+    """Figma REST -> screenshot image URL."""
+    log("REST: fetching screenshot URL...")
+    data = figma_get(f"images/{FILE_KEY}?ids={NODE_ID}&format=png&scale=2")
+    url = (data.get("images") or {}).get(NODE_ID)
+    if not url:
+        raise RuntimeError("No screenshot URL returned from images API")
+    log("REST: screenshot URL obtained")
+    return url
+
+
+def fetch_node_data():
+    """Figma REST -> full node document (for component properties + variants)."""
+    log("REST: fetching node data...")
+    data = figma_get(f"files/{FILE_KEY}/nodes?ids={NODE_ID}")
+    node = (data.get("nodes") or {}).get(NODE_ID, {}).get("document")
+    if not node:
+        raise RuntimeError("No document in nodes response")
+    log(f"REST: node type={node.get('type')}")
+    return node
+
+
+def fetch_metadata():
+    log("MCP: get_metadata...")
+    text = mcp_call("get_metadata", {
+        "nodeId": NODE_ID,
+        "clientLanguages": "swift",
+        "clientFrameworks": "swiftui",
+    })
+    log(f"MCP: metadata {len(text)} chars")
+    return text
+
+
+def _is_too_large_response(text):
+    """Check if MCP returned XML metadata instead of code (design too large)."""
+    return "too large" in text.lower() and "<frame" in text[:300]
+
+
+def _parse_sublayer_ids(text):
+    """Extract sublayer node IDs from the XML metadata response."""
+    # Match <symbol id="X:Y" ...> or <frame id="X:Y" ...> (children only)
+    ids = re.findall(r'<(?:symbol|frame)\s+id="([^"]+)"', text)
+    # Skip the root frame (first match is the container itself)
+    root_match = re.search(r'<frame\s+id="([^"]+)"', text)
+    root_id = root_match.group(1) if root_match else None
+    return [nid for nid in ids if nid != root_id]
+
+
+def _build_design_context_args(node_id, assets_dir=None):
+    """Build arguments for get_design_context. Skips dirForAssetWrites on remote."""
+    args = {
+        "nodeId": node_id,
+        "clientLanguages": "swift",
+        "clientFrameworks": "swiftui",
+        # Disable Code Connect in design context — when Code Connect is enabled,
+        # the returned snippets override the original Tailwind reference code we
+        # need for layout/style extraction. We fetch Code Connect separately
+        # via get_code_connect_map.
+        "disableCodeConnect": True,
+    }
+    if assets_dir and MCP_MODE == "local":
+        args["dirForAssetWrites"] = assets_dir
+    return args
+
+
+def _fetch_sublayer_context(node_id, assets_dir, depth=0):
+    """Fetch design context for a single sublayer. Recurses if also too large."""
+    if depth > 3:
+        log(f"  sublayer {node_id}: max recursion depth, returning raw")
+        return {"nodeId": node_id, "error": "max_recursion_depth"}
+
+    text = mcp_call("get_design_context", _build_design_context_args(node_id, assets_dir))
+
+    if _is_too_large_response(text):
+        log(f"  sublayer {node_id}: also too large, splitting further (depth={depth+1})")
+        child_ids = _parse_sublayer_ids(text)
+        if not child_ids:
+            return {"nodeId": node_id, "response": text}
+        child_responses = {}
+        for cid in child_ids:
+            child_responses[cid] = _fetch_sublayer_context(cid, assets_dir, depth + 1)
+        return {"nodeId": node_id, "sublayers": True, "responses": child_responses}
+
+    log(f"  sublayer {node_id}: {len(text)} chars")
+    return {"nodeId": node_id, "response": text}
+
+
+def _fetch_sublayers_parallel(sublayer_ids, assets_dir, max_workers=10):
+    """Fetch all sublayer design contexts in parallel using a thread pool."""
+    results = {}
+    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as pool:
+        future_to_sid = {
+            pool.submit(_fetch_sublayer_context, sid, assets_dir): sid
+            for sid in sublayer_ids
+        }
+        for future in concurrent.futures.as_completed(future_to_sid):
+            sid = future_to_sid[future]
+            try:
+                results[sid] = future.result()
+            except Exception as e:
+                log(f"  sublayer {sid}: ERROR {e}")
+                results[sid] = {"nodeId": sid, "error": str(e)}
+    return results
+
+
+def fetch_design_context():
+    assets_dir = str((Path(ARTIFACT_PATH) / "pass1" / "assets").resolve())
+    Path(assets_dir).mkdir(parents=True, exist_ok=True)
+
+    log("MCP: get_design_context...")
+    text = mcp_call("get_design_context", _build_design_context_args(NODE_ID, assets_dir))
+    log(f"MCP: design_context {len(text)} chars")
+
+    if _is_too_large_response(text):
+        sublayer_ids = _parse_sublayer_ids(text)
+
+        # Cap check: if too many sublayers, defer to manual resolution
+        if len(sublayer_ids) > SUBLAYER_CAP:
+            log(f"MCP: {len(sublayer_ids)} sublayers exceeds cap ({SUBLAYER_CAP}) — deferring")
+            return {
+                "__deferred": True,
+                "__sublayer_count": len(sublayer_ids),
+                "__sublayer_ids": sublayer_ids,
+                "__metadata_xml": text,
+                "__cap": SUBLAYER_CAP,
+            }
+
+        log(f"MCP: design too large — fetching {len(sublayer_ids)} sublayers in parallel")
+        if sublayer_ids:
+            sublayer_responses = _fetch_sublayers_parallel(sublayer_ids, assets_dir)
+            total = sum(
+                len(r.get("response", "")) for r in sublayer_responses.values()
+                if isinstance(r, dict) and "response" in r
+            )
+            log(f"MCP: sublayer design_context total {total} chars across {len(sublayer_ids)} sublayers")
+            return {
+                "__sublayers": True,
+                "__sublayer_ids": sublayer_ids,
+                "__metadata_xml": text,
+                "__responses": sublayer_responses,
+            }
+
+    return text
+
+
+def fetch_variable_defs():
+    log("MCP: get_variable_defs...")
+    text = mcp_call("get_variable_defs", {
+        "nodeId": NODE_ID,
+        "clientLanguages": "swift",
+        "clientFrameworks": "swiftui",
+    })
+    log(f"MCP: variable_defs {len(text)} chars")
+    return text
+
+
+def fetch_code_connect_map():
+    log("MCP: get_code_connect_map...")
+    # Filter by SwiftUI label — without this, MCP returns all platforms
+    # (e.g. Compose) and we get Android snippets instead of iOS ones.
+    text = mcp_call("get_code_connect_map", {
+        "nodeId": NODE_ID,
+        "codeConnectLabel": "SwiftUI",
+    })
+    log(f"MCP: code_connect_map {len(text)} chars")
+    return text
+
+
+# ─── Batch 2: Downloads & Post-Processing ───────────────────────────────────
+
+def download_screenshot(screenshot_url):
+    dest = str(Path(ARTIFACT_PATH) / "pass1" / "screenshot.png")
+    log("Downloading screenshot PNG...")
+    if not download_file(screenshot_url, dest):
+        raise RuntimeError("Screenshot PNG download failed")
+    log("Screenshot saved")
+    return dest
+
+
+def download_variant_screenshots(node_data):
+    """Batch-download variant screenshots. Returns list of variant info dicts."""
+    if node_data.get("type") != "COMPONENT_SET":
+        log("Not COMPONENT_SET -- skipping variants")
+        return []
+
+    children = [c for c in node_data.get("children", []) if c.get("type") == "COMPONENT"]
+    if not children:
+        log("No COMPONENT children found")
+        return []
+
+    log(f"Found {len(children)} variants -- batch fetching image URLs...")
+
+    # Single batch API call for all variant IDs
+    all_ids = ",".join(c["id"] for c in children)
+    data = figma_get(f"images/{FILE_KEY}?ids={all_ids}&format=png&scale=2")
+    image_urls = data.get("images") or {}
+
+    screenshots_dir = Path(ARTIFACT_PATH) / "pass1" / "screenshots"
+    screenshots_dir.mkdir(parents=True, exist_ok=True)
+
+    # Build download list
+    downloads = []
+    for child in children:
+        url = image_urls.get(child["id"])
+        if not url:
+            continue
+        name = child.get("name", child["id"])
+        # Single-property: "State=Success" -> "Success"
+        # Multi-property: "Size=Large, Loyalty Type=Classic" -> "Size=Large_LoyaltyType=Classic"
+        parts = [p.strip() for p in name.split(",")]
+        if len(parts) == 1 and "=" in parts[0]:
+            safe = parts[0].split("=", 1)[1].strip()
+        else:
+            # "Size=Large, Loyalty Type=Classic Plus" -> "Size=Large_LoyaltyType=Classic_Plus"
+            formatted = []
+            for p in parts:
+                if "=" in p:
+                    k, v = p.split("=", 1)
+                    k = k.strip().replace(" ", "")       # remove spaces in key
+                    v = v.strip().replace(" ", "_")       # spaces -> underscores in value
+                    formatted.append(f"{k}={v}")
+                else:
+                    formatted.append(p.replace(" ", ""))
+            safe = "_".join(formatted)
+        safe = re.sub(r"[/\\:]", "_", safe)
+        downloads.append({
+            "id": child["id"],
+            "name": name,
+            "safe_name": safe,
+            "file": f"{safe}.png",
+            "url": url,
+            "dest": str(screenshots_dir / f"{safe}.png"),
+        })
+
+    # Parallel download
+    results = []
+    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as pool:
+        futs = {pool.submit(download_file, d["url"], d["dest"]): d for d in downloads}
+        for fut in concurrent.futures.as_completed(futs):
+            info = futs[fut]
+            if fut.result():
+                results.append(info)
+                log(f"  variant: {info['safe_name']}")
+
+    # Write variants.md
+    results.sort(key=lambda x: x["name"])
+    lines = [
+        "# Variant Screenshots\n",
+        "| Variant | Node ID | File |",
+        "|---------|---------|------|",
+    ]
+    for r in results:
+        lines.append(f"| {r['name']} | {r['id']} | {r['file']} |")
+    lines += ["", "## Usage", "- Confluence documentation", "- Snapshot testing reference", ""]
+    (screenshots_dir / "variants.md").write_text("\n".join(lines))
+
+    log(f"Downloaded {len(results)}/{len(downloads)} variant screenshots")
+    return results
+
+
+def sanitize_svgs():
+    """Remove Xcode-incompatible attributes from downloaded SVGs."""
+    assets_dir = Path(ARTIFACT_PATH) / "pass1" / "assets"
+    if not assets_dir.exists():
+        return 0
+
+    count = 0
+    for svg in assets_dir.glob("*.svg"):
+        content = svg.read_text()
+        original = content
+        content = re.sub(r' width="100%"', "", content)
+        content = re.sub(r' height="100%"', "", content)
+        content = re.sub(r' preserveAspectRatio="none"', "", content)
+        content = re.sub(r' style="display: block;"', "", content)
+        content = re.sub(r' overflow="visible"', "", content)
+        content = re.sub(r"var\(--fill-0, ([^)]*)\)", r"\1", content)
+        content = re.sub(r"var\(--stroke-0, ([^)]*)\)", r"\1", content)
+        if content != original:
+            svg.write_text(content)
+            count += 1
+    if count:
+        log(f"Sanitized {count} SVGs")
+    return count
+
+
+# ─── File Writers ────────────────────────────────────────────────────────────
+
+def save_mcp_text(filename, text, try_json=True):
+    """Write MCP text output to a file in pass1/."""
+    dest = Path(ARTIFACT_PATH) / "pass1" / filename
+    if try_json:
+        try:
+            parsed = json.loads(text)
+            dest.write_text(json.dumps(parsed, indent=2, ensure_ascii=False) + "\n")
+            return
+        except (json.JSONDecodeError, TypeError):
+            pass
+    dest.write_text(text)
+
+
+def write_design_context_deferred(data):
+    """Write deferred artifact when sublayer count exceeds cap."""
+    pass1 = Path(ARTIFACT_PATH) / "pass1"
+
+    # Write design_context_response.json with metadata XML only
+    envelope = {
+        "rootNodeId": NODE_ID,
+        "source": MCP_MODE,
+        "deferred": True,
+        "sublayers": True,
+        "sublayerCount": data["__sublayer_count"],
+        "cap": data["__cap"],
+        "sublayerNodeIds": data["__sublayer_ids"],
+        "metadataXml": data["__metadata_xml"],
+        "responses": {},
+    }
+    (pass1 / "design_context_response.json").write_text(
+        json.dumps(envelope, indent=2, ensure_ascii=False) + "\n"
+    )
+
+    # Write design_context_deferred.json — resolution instructions
+    cmd_template = (
+        f"python3 .instructions/figma/figma-to-swiftui/scripts/phase1-gather.py "
+        f"--fetch-deferred "
+        f"--file-key {FILE_KEY} "
+        f"--node-id {NODE_ID} "
+        f"--artifact-path {ARTIFACT_PATH} "
+        f"--component-name {COMPONENT_NAME} "
+        f"--sublayer-ids \"{{comma_separated_ids}}\""
+    )
+    deferred = {
+        "status": "deferred",
+        "reason": "sublayer_count_exceeds_cap",
+        "sublayerCount": data["__sublayer_count"],
+        "cap": data["__cap"],
+        "sublayerIds": data["__sublayer_ids"],
+        "fileKey": FILE_KEY,
+        "rootNodeId": NODE_ID,
+        "instruction": (
+            "Design context has too many sublayers to fetch automatically. "
+            "Use --fetch-deferred mode with selected sublayer IDs to resolve."
+        ),
+        "commandTemplate": cmd_template,
+    }
+    (pass1 / "design_context_deferred.json").write_text(
+        json.dumps(deferred, indent=2, ensure_ascii=False) + "\n"
+    )
+    log(f"design_context_deferred.json written ({data['__sublayer_count']} sublayers)")
+
+
+def write_design_context_file(data):
+    """Save design context -- handles normal text, sublayer dict, and deferred."""
+    dest = Path(ARTIFACT_PATH) / "pass1" / "design_context_response.json"
+
+    # Deferred case: sublayer count exceeded cap
+    if isinstance(data, dict) and data.get("__deferred"):
+        write_design_context_deferred(data)
+        return
+
+    # Sublayer case: data is a dict with __sublayers=True
+    if isinstance(data, dict) and data.get("__sublayers"):
+        sublayer_ids = data["__sublayer_ids"]
+        responses = {}
+        for sid, resp in data["__responses"].items():
+            if isinstance(resp, dict) and "response" in resp:
+                responses[sid] = resp["response"]
+            else:
+                responses[sid] = resp  # nested sublayer or error
+        envelope = {
+            "rootNodeId": NODE_ID,
+            "source": MCP_MODE,
+            "sublayers": True,
+            "sublayerNodeIds": sublayer_ids,
+            "responses": responses,
+        }
+        dest.write_text(json.dumps(envelope, indent=2, ensure_ascii=False) + "\n")
+        return
+
+    # Normal case: data is a text string
+    text = data
+    try:
+        parsed = json.loads(text)
+        dest.write_text(json.dumps(parsed, indent=2, ensure_ascii=False) + "\n")
+    except (json.JSONDecodeError, TypeError):
+        envelope = {
+            "rootNodeId": NODE_ID,
+            "source": MCP_MODE,
+            "sublayers": False,
+            "response": text,
+        }
+        dest.write_text(json.dumps(envelope, indent=2, ensure_ascii=False) + "\n")
+
+
+def write_design_context_assets():
+    """List downloaded assets in design_context_assets.txt."""
+    dest = Path(ARTIFACT_PATH) / "pass1" / "design_context_assets.txt"
+    assets_dir = Path(ARTIFACT_PATH) / "pass1" / "assets"
+    files = sorted(assets_dir.glob("*")) if assets_dir.exists() else []
+    files = [f for f in files if f.is_file()]
+
+    if files:
+        lines = [
+            "# Asset References from Design Context",
+            f"# {len(files)} assets downloaded by MCP",
+            "",
+        ]
+        for f in files:
+            lines.append(f"{f.name} | local:{f}")
+    else:
+        lines = [
+            "# Asset References from Design Context",
+            "# No assets referenced in design context response.",
+        ]
+    dest.write_text("\n".join(lines) + "\n")
+    return len(files)
+
+
+def write_screenshot_response():
+    dest = Path(ARTIFACT_PATH) / "pass1" / "screenshot_response.md"
+    today = datetime.now().strftime("%Y-%m-%d")
+    dest.write_text(
+        f"# Screenshot Response\n\n"
+        f"## Screenshot File\n"
+        f"- File: screenshot.png\n"
+        f"- Node ID: {NODE_ID}\n"
+        f"- Source: local\n"
+        f"- Scale: 2x\n"
+        f"- Timestamp: {today}\n"
+    )
+
+
+def generate_component_properties(node_data):
+    """Build component_properties.json from the REST API node document."""
+    node_type = node_data.get("type", "UNKNOWN")
+    is_component = node_type in ("COMPONENT", "COMPONENT_SET")
+    prop_defs = node_data.get("componentPropertyDefinitions") or {}
+
+    variants_list = []
+    boolean_props = []
+    text_slots = []
+    nested_comps = []
+    cc_mappings = {}
+
+    for key, defn in prop_defs.items():
+        ptype = defn.get("type")
+        # Display name: "Text#6893:1" -> "Text",  "\u21aa Left Icon#13152:11" -> "\u21aa Left Icon"
+        display = key.split("#")[0]
+        clean = display.lstrip("\u21aa ").strip()
+
+        if ptype == "VARIANT":
+            values = defn.get("variantOptions", [])
+            variants_list.append({"property": display, "values": values, "type": "VARIANT"})
+            if values:
+                pairs = ", ".join(
+                    f'"{v}": .{v.lower().replace(" ", "")}' for v in values
+                )
+                cc_mappings[key] = f'@FigmaEnum("{display}", mapping: [{pairs}])'
+
+        elif ptype == "BOOLEAN":
+            boolean_props.append({
+                "property": clean,
+                "default": defn.get("defaultValue", False),
+                "figmaKey": key,
+            })
+            cc_mappings[key] = f'@FigmaBoolean("{clean}")'
+
+        elif ptype == "TEXT":
+            text_slots.append({
+                "name": clean,
+                "defaultValue": defn.get("defaultValue", ""),
+                "figmaKey": key,
+            })
+            cc_mappings[key] = f'@FigmaString("{clean}")'
+
+        elif ptype == "INSTANCE_SWAP":
+            nested_comps.append({
+                "name": clean,
+                "nodeId": defn.get("defaultValue", ""),
+                "figmaKey": key,
+                "type": "INSTANCE_SWAP",
+            })
+            cc_mappings[key] = f'@FigmaInstance("{display}")'
+
+    result = {
+        "componentName": COMPONENT_NAME,
+        "nodeId": NODE_ID,
+        "nodeType": node_type,
+        "isComponent": is_component,
+        "componentPropertyDefinitions": prop_defs,
+        "variants": variants_list,
+        "booleanProperties": boolean_props,
+        "textSlots": text_slots,
+        "nestedComponents": nested_comps,
+        "codeConnectStrategy": {
+            "isComponent": is_component,
+            "hasPropertyDefinitions": bool(prop_defs),
+            "mappings": cc_mappings,
+        },
+    }
+    dest = Path(ARTIFACT_PATH) / "pass1" / "component_properties.json"
+    dest.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n")
+    log("component_properties.json written")
+    return result
+
+
+def write_component_summary(comp_props, node_data):
+    """Condensed summary (~100 lines) for downstream phases."""
+    prop_defs = comp_props.get("componentPropertyDefinitions") or {}
+    properties = []
+    for key, defn in prop_defs.items():
+        ptype = defn.get("type")
+        name = key.split("#")[0].lstrip("\u21aa ").strip()
+        prop = {"name": name, "type": ptype, "figmaKey": key, "default": defn.get("defaultValue")}
+        if ptype == "VARIANT":
+            prop["values"] = defn.get("variantOptions", [])
+        properties.append(prop)
+
+    children = node_data.get("children", [])
+    variant_count = len([c for c in children if c.get("type") == "COMPONENT"])
+    bbox = node_data.get("absoluteBoundingBox") or {}
+
+    assets_dir = Path(ARTIFACT_PATH) / "pass1" / "assets"
+    svgs = sorted(assets_dir.glob("*.svg")) if assets_dir.exists() else []
+    screenshots_dir = Path(ARTIFACT_PATH) / "pass1" / "screenshots"
+    pngs = sorted(screenshots_dir.glob("*.png")) if screenshots_dir.exists() else []
+
+    ntype = node_data.get("type", "UNKNOWN")
+    layer_line = (
+        f"{ntype} > COMPONENT({variant_count} variants)"
+        if variant_count
+        else ntype
+    )
+
+    summary = {
+        "componentName": COMPONENT_NAME,
+        "nodeId": NODE_ID,
+        "fileKey": FILE_KEY,
+        "nodeType": ntype,
+        "variantCount": variant_count,
+        "dimensions": {"width": bbox.get("width", 0), "height": bbox.get("height", 0)},
+        "properties": properties,
+        "layerSummary": [layer_line],
+        "variableBindingCount": 0,
+        "variableBindingSummary": [],
+        "assets": {
+            "svgCount": len(svgs),
+            "screenshotCount": len(pngs),
+            "fileList": [s.name for s in svgs],
+        },
+        "hasExistingCodeConnect": False,
+    }
+
+    dest = Path(ARTIFACT_PATH) / "pass1" / "component_summary.json"
+    dest.write_text(json.dumps(summary, indent=2, ensure_ascii=False) + "\n")
+    log("component_summary.json written")
+    return summary
+
+
+def write_index(variant_results, asset_count):
+    today = datetime.now().strftime("%Y-%m-%d")
+    screenshots_dir = Path(ARTIFACT_PATH) / "pass1" / "screenshots"
+    var_count = len(list(screenshots_dir.glob("*.png"))) if screenshots_dir.exists() else 0
+    assets_dir = Path(ARTIFACT_PATH) / "pass1" / "assets"
+    svg_count = len(list(assets_dir.glob("*.svg"))) if assets_dir.exists() else 0
+
+    content = f"""# Pass 1 -- Data Gathering Output
+
+Component: {COMPONENT_NAME}
+Node ID: {NODE_ID}
+File Key: {FILE_KEY}
+Gathered: {today}
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `pass1/screenshot.png` | Component screenshot (2x scale) |
+| `pass1/screenshot_response.md` | Screenshot metadata |
+| `pass1/screenshots/` | Variant screenshots ({var_count} variants) |
+| `pass1/screenshots/variants.md` | Variant screenshot index |
+| `pass1/metadata_response.xml` | Layer hierarchy (XML) |
+| `pass1/design_context_response.json` | Generated code + structure |
+| `pass1/design_context_assets.txt` | Asset download URLs ({svg_count} vectors) |
+| `pass1/assets/` | Downloaded SVG assets (sanitized for Xcode) |
+| `pass1/variable_defs_response.json` | Design tokens / variables |
+| `pass1/component_properties.json` | Variant properties, booleans, text slots, Code Connect strategy |
+| `pass1/code_connect_map_response.json` | Existing Code Connect mappings |
+| `pass1/component_summary.json` | **Condensed summary -- read this FIRST** |
+
+## Read Instructions
+
+**All downstream phases: read `component_summary.json` FIRST.** It contains a condensed view of the component's properties, structure, and assets in ~100 lines. Only read raw artifacts (design_context_response.json, etc.) if you need detail the summary does not provide.
+
+- Phase 2A (Testing Identifiers): `component_summary.json`, then `design_context_response.json` if needed, `component_properties.json`
+- Phase 2B (Localization): `component_summary.json`, then `design_context_response.json` if needed, `component_properties.json`
+- Phase 2C (Accessibility): `component_summary.json`, then `screenshot_response.md`, `design_context_response.json` if needed
+- Phase 2D (Analytics): `component_summary.json`, then `design_context_response.json` if needed
+- Phase 3 sub-phases: `component_summary.json` FIRST, then phase-specific raw artifacts as needed
+- Phase 4 sub-phases: `component_summary.json` for cross-reference, pass3/ analysis files as primary input
+"""
+    (Path(ARTIFACT_PATH) / "pass1" / "_index.md").write_text(content)
+    log("_index.md written")
+
+
+def update_implementation_history(variant_count, svg_count):
+    hist = Path(ARTIFACT_PATH) / "IMPLEMENTATION_HISTORY.md"
+    if not hist.exists():
+        log("WARNING: IMPLEMENTATION_HISTORY.md not found -- skipping update")
+        return
+
+    text = hist.read_text()
+
+    phase1_block = f"""
+## Phase 1 Data
+- Screenshot: pass1/screenshot_response.md
+- Screenshot PNG: pass1/screenshot.png
+- Metadata: pass1/metadata_response.xml
+- Design Context: pass1/design_context_response.json
+- Design Assets: pass1/design_context_assets.txt
+- Variable Defs: pass1/variable_defs_response.json
+- Component Properties: pass1/component_properties.json (for Code Connect)
+- Code Connect: pass1/code_connect_map_response.json
+- Assets: pass1/assets/ (SVGs sanitized)
+- Variant Screenshots: pass1/screenshots/ ({variant_count} variants)
+- Component Summary: pass1/component_summary.json
+"""
+
+    if "## Phase 1 Data" in text:
+        text = re.sub(r"\n## Phase 1 Data.*?(?=\n## |\Z)", "", text, flags=re.DOTALL)
+
+    text = text.rstrip() + "\n" + phase1_block
+    hist.write_text(text)
+    log("IMPLEMENTATION_HISTORY.md updated")
+
+
+# ─── Deferred Resolution ─────────────────────────────────────────────────────
+
+def fetch_deferred(sublayer_ids):
+    """Fetch design context for selected sublayer IDs and merge into standard format."""
+    t0 = time.time()
+    log(f"Deferred resolution: fetching {len(sublayer_ids)} sublayers...")
+
+    pass1 = Path(ARTIFACT_PATH) / "pass1"
+    assets_dir = str((pass1 / "assets").resolve())
+    Path(assets_dir).mkdir(parents=True, exist_ok=True)
+
+    # Read existing deferred JSON to get all sublayer IDs
+    deferred_path = pass1 / "design_context_deferred.json"
+    if deferred_path.exists():
+        deferred = json.loads(deferred_path.read_text())
+        all_sublayer_ids = deferred.get("sublayerIds", [])
+    else:
+        all_sublayer_ids = sublayer_ids
+
+    # Fetch each sublayer in parallel (reuses existing infrastructure)
+    sublayer_responses = _fetch_sublayers_parallel(sublayer_ids, assets_dir)
+
+    # Build responses dict (text only, same format as normal sublayer path)
+    responses = {}
+    for sid, resp in sublayer_responses.items():
+        if isinstance(resp, dict) and "response" in resp:
+            responses[sid] = resp["response"]
+        elif isinstance(resp, dict) and "error" in resp:
+            responses[sid] = f"<!-- Error: {resp['error']} -->"
+            log(f"  WARNING: sublayer {sid} had error: {resp['error']}")
+        else:
+            responses[sid] = str(resp)
+
+    # Build merged design_context_response.json — same format as non-deferred
+    envelope = {
+        "rootNodeId": NODE_ID,
+        "source": MCP_MODE,
+        "sublayers": True,
+        "representativeSelection": True,
+        "sublayerNodeIds": all_sublayer_ids,
+        "selectedNodeIds": sublayer_ids,
+        "responses": responses,
+        # Flat concatenated response for Phase 2 NORMALIZE_DESIGN_CONTEXT compatibility
+        "response": "\n\n".join(
+            f"// --- Sublayer: {sid} ---\n{text}"
+            for sid, text in responses.items()
+            if not text.startswith("<!-- Error")
+        ),
+    }
+
+    dest = pass1 / "design_context_response.json"
+    dest.write_text(json.dumps(envelope, indent=2, ensure_ascii=False) + "\n")
+    log(f"design_context_response.json written ({len(responses)} sublayers, {len(envelope['response'])} chars)")
+
+    # Update component_summary.json
+    summary_path = pass1 / "component_summary.json"
+    if summary_path.exists():
+        summary = json.loads(summary_path.read_text())
+        summary["designContextStatus"] = "representative"
+        summary["selectedSublayerCount"] = len(sublayer_ids)
+        summary_path.write_text(json.dumps(summary, indent=2, ensure_ascii=False) + "\n")
+        log("component_summary.json updated with designContextStatus")
+
+    # Sanitize any new SVGs
+    sanitize_svgs()
+
+    # Update asset list
+    write_design_context_assets()
+
+    duration = time.time() - t0
+    log(f"=== DEFERRED COMPLETE in {duration:.1f}s (MCP: {MCP_MODE}) ===")
+
+    result = {
+        "status": "COMPLETE",
+        "phase": "phase-1-deferred",
+        "mcpMode": MCP_MODE,
+        "sublayersFetched": len(sublayer_ids),
+        "sublayersSucceeded": len([v for v in responses.values() if not v.startswith("<!-- Error")]),
+        "responseChars": len(envelope["response"]),
+        "duration_seconds": round(duration, 1),
+    }
+    print(json.dumps(result, indent=2))
+    sys.exit(0)
+
+
+# ─── Main ────────────────────────────────────────────────────────────────────
+
+def main():
+    global MCP_URL, MCP_TOKEN, FIGMA_TOKEN, FILE_KEY, NODE_ID, COMPONENT_NAME, ARTIFACT_PATH
+
+    parser = argparse.ArgumentParser(description="Phase 1 -- Data Gathering")
+    parser.add_argument("--file-key", required=True)
+    parser.add_argument("--node-id", required=True, help="colon-separated, e.g. 6893:6879")
+    parser.add_argument("--artifact-path", required=True)
+    parser.add_argument("--component-name", required=True)
+    parser.add_argument("--figma-token", help="REST API token (falls back to macOS Keychain)")
+    parser.add_argument("--mcp-token", help="MCP OAuth token (falls back to Keychain/Claude Code creds)")
+    parser.add_argument("--mcp-url", default="http://127.0.0.1:3845/mcp")
+    parser.add_argument("--fetch-deferred", action="store_true",
+                        help="Deferred resolution mode: fetch design context for selected sublayer IDs")
+    parser.add_argument("--sublayer-ids", help="Comma-separated sublayer node IDs (requires --fetch-deferred)")
+    args = parser.parse_args()
+
+    FILE_KEY = args.file_key
+    NODE_ID = args.node_id
+    COMPONENT_NAME = args.component_name
+    ARTIFACT_PATH = args.artifact_path
+    MCP_URL = args.mcp_url
+
+    # ─── Deferred Resolution Mode ───
+    if args.fetch_deferred:
+        if not args.sublayer_ids:
+            halt("PRE_CHECK", "--fetch-deferred requires --sublayer-ids", [], [],
+                 "Pass comma-separated sublayer node IDs: --sublayer-ids 'id1,id2,id3'")
+        sublayer_ids = [sid.strip() for sid in args.sublayer_ids.split(",") if sid.strip()]
+        if not sublayer_ids:
+            halt("PRE_CHECK", "No valid sublayer IDs provided", [], [],
+                 "Pass comma-separated sublayer node IDs: --sublayer-ids 'id1,id2,id3'")
+        # Need MCP token for fetching
+        MCP_TOKEN = get_mcp_token(args.mcp_token)
+        try:
+            mcp_init()
+        except Exception as exc:
+            halt("PRE_CHECK", f"MCP init failed: {exc}", [], [],
+                 "Ensure Figma Desktop is running or run /figma-setup for remote MCP")
+        fetch_deferred(sublayer_ids)
+        return  # fetch_deferred calls sys.exit(0)
+
+    # Resolve Figma REST API token
+    FIGMA_TOKEN = args.figma_token
+    if not FIGMA_TOKEN:
+        try:
+            FIGMA_TOKEN = subprocess.check_output(
+                ["security", "find-generic-password", "-a", os.environ["USER"],
+                 "-s", "FIGMA_ACCESS_TOKEN", "-w"],
+                stderr=subprocess.DEVNULL,
+            ).decode().strip()
+        except (subprocess.CalledProcessError, KeyError):
+            halt("PRE_CHECK", "FIGMA_ACCESS_TOKEN not found", [], [],
+                 "Pass --figma-token or: security add-generic-password -a $USER -s FIGMA_ACCESS_TOKEN -w <token>")
+
+    # Resolve MCP OAuth token (for remote MCP)
+    MCP_TOKEN = get_mcp_token(args.mcp_token)
+
+    t0 = time.time()
+    log(f"Phase 1: {COMPONENT_NAME}  node={NODE_ID}  file={FILE_KEY}")
+
+    # Ensure directories
+    pass1 = Path(ARTIFACT_PATH) / "pass1"
+    pass1.mkdir(parents=True, exist_ok=True)
+    (pass1 / "assets").mkdir(exist_ok=True)
+    (pass1 / "screenshots").mkdir(exist_ok=True)
+
+    gates = ["PRE_CHECK"]
+    artifacts = []
+
+    # -- MCP Init (remote first, local fallback) --
+    try:
+        mcp_init()
+    except Exception as exc:
+        halt("PRE_CHECK", f"MCP init failed: {exc}", [], [],
+             "Ensure Figma Desktop is running or run /figma-setup for remote MCP")
+
+    # -- Batch 1: parallel data fetching --
+    log("=== Batch 1: parallel data fetching ===")
+    b1 = {}
+    b1_err = {}
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=6) as pool:
+        jobs = {
+            pool.submit(fetch_screenshot_url): "screenshot_url",
+            pool.submit(fetch_node_data): "node_data",
+            pool.submit(fetch_metadata): "metadata",
+            pool.submit(fetch_design_context): "design_context",
+            pool.submit(fetch_variable_defs): "variable_defs",
+            pool.submit(fetch_code_connect_map): "code_connect_map",
+        }
+        for fut in concurrent.futures.as_completed(jobs):
+            key = jobs[fut]
+            try:
+                b1[key] = fut.result()
+            except Exception as exc:
+                b1_err[key] = str(exc)
+                log(f"  ERROR {key}: {exc}")
+
+    # Critical checks
+    if "screenshot_url" in b1_err:
+        halt("SCREENSHOT", b1_err["screenshot_url"], gates, artifacts,
+             "Check FIGMA_ACCESS_TOKEN and node ID")
+    if "node_data" in b1_err:
+        halt("COMPONENT_PROPERTIES", b1_err["node_data"], gates, artifacts,
+             "Check FIGMA_ACCESS_TOKEN and node ID")
+
+    # -- Batch 2: downloads + processing --
+    log("=== Batch 2: downloads & processing ===")
+
+    # Screenshot
+    try:
+        download_screenshot(b1["screenshot_url"])
+        gates.append("SCREENSHOT")
+        artifacts.append("pass1/screenshot.png")
+    except Exception as exc:
+        halt("SCREENSHOT", str(exc), gates, artifacts)
+
+    write_screenshot_response()
+    artifacts.append("pass1/screenshot_response.md")
+
+    # Variant screenshots
+    node_data = b1["node_data"]
+    try:
+        variant_results = download_variant_screenshots(node_data)
+        gates.append("VARIANT_SCREENSHOTS")
+        if variant_results:
+            artifacts.extend(["pass1/screenshots/", "pass1/screenshots/variants.md"])
+    except Exception as exc:
+        log(f"WARNING: variant screenshots failed: {exc}")
+        variant_results = []
+        gates.append("VARIANT_SCREENSHOTS")
+
+    # Metadata
+    if "metadata" in b1:
+        save_mcp_text("metadata_response.xml", b1["metadata"], try_json=False)
+        gates.append("METADATA")
+        artifacts.append("pass1/metadata_response.xml")
+    elif "metadata" in b1_err:
+        (pass1 / "metadata_response.xml").write_text(f"<!-- Error: {b1_err['metadata']} -->\n")
+        gates.append("METADATA")
+        artifacts.append("pass1/metadata_response.xml")
+
+    # Design context
+    design_context_deferred = False
+    if "design_context" in b1:
+        dc_data = b1["design_context"]
+        write_design_context_file(dc_data)
+        gates.append("DESIGN_CONTEXT")
+        artifacts.append("pass1/design_context_response.json")
+        if isinstance(dc_data, dict) and dc_data.get("__deferred"):
+            design_context_deferred = True
+            artifacts.append("pass1/design_context_deferred.json")
+    elif "design_context" in b1_err:
+        halt("DESIGN_CONTEXT", b1_err["design_context"], gates, artifacts,
+             "Check Figma connection and node ID")
+
+    # Sanitize SVGs
+    sanitize_svgs()
+    gates.append("SANITIZE_SVGS")
+
+    # Asset list
+    asset_count = write_design_context_assets()
+    artifacts.append("pass1/design_context_assets.txt")
+
+    # Variable defs
+    if "variable_defs" in b1:
+        save_mcp_text("variable_defs_response.json", b1["variable_defs"])
+    else:
+        # REST API fallback (requires Enterprise plan — may 403)
+        log("MCP variable_defs failed — trying REST API fallback...")
+        try:
+            rest_vars = figma_get(f"files/{FILE_KEY}/variables/local")
+            (pass1 / "variable_defs_response.json").write_text(
+                json.dumps(rest_vars, indent=2, ensure_ascii=False) + "\n"
+            )
+            log("REST API variable_defs fallback succeeded")
+        except HTTPError as exc:
+            if exc.code == 403:
+                log("REST API variable_defs: 403 (requires Enterprise plan) — skipping")
+            else:
+                log(f"REST API variable_defs fallback failed: {exc}")
+            (pass1 / "variable_defs_response.json").write_text(json.dumps({
+                "error": "variable_defs_unavailable",
+                "source": "none",
+                "note": "Variable definitions could not be retrieved. MCP unavailable, REST API returned 403 (Enterprise plan required).",
+            }, indent=2) + "\n")
+        except Exception as exc:
+            log(f"REST API variable_defs fallback failed: {exc}")
+            (pass1 / "variable_defs_response.json").write_text(json.dumps({
+                "error": "variable_defs_unavailable",
+                "source": "none",
+                "note": f"Variable definitions could not be retrieved via MCP or REST API: {exc}",
+            }, indent=2) + "\n")
+    gates.append("VARIABLE_DEFS")
+    artifacts.append("pass1/variable_defs_response.json")
+
+    # Component properties
+    comp_props = generate_component_properties(node_data)
+    gates.append("COMPONENT_PROPERTIES")
+    artifacts.append("pass1/component_properties.json")
+
+    # Code connect map
+    if "code_connect_map" in b1:
+        save_mcp_text("code_connect_map_response.json", b1["code_connect_map"])
+    else:
+        (pass1 / "code_connect_map_response.json").write_text("{}\n")
+    gates.append("CODE_CONNECT_MAP")
+    artifacts.append("pass1/code_connect_map_response.json")
+
+    # -- Finalize --
+    log("=== Finalize ===")
+
+    write_component_summary(comp_props, node_data)
+    artifacts.append("pass1/component_summary.json")
+
+    write_index(variant_results, asset_count)
+    artifacts.append("pass1/_index.md")
+
+    update_implementation_history(
+        len(variant_results),
+        len(list((pass1 / "assets").glob("*.svg"))) if (pass1 / "assets").exists() else 0,
+    )
+
+    gates.append("FINALIZE")
+    duration = time.time() - t0
+
+    # -- Success --
+    status = "COMPLETE_WITH_DEFERRED" if design_context_deferred else "COMPLETE"
+    log(f"=== {status} in {duration:.1f}s (MCP: {MCP_MODE}) ===")
+    summary = {
+        "status": status,
+        "phase": "phase-1",
+        "mcpMode": MCP_MODE,
+        "gates_passed": gates,
+        "artifacts_created": artifacts,
+        "duration_seconds": round(duration, 1),
+    }
+    if design_context_deferred:
+        summary["deferred"] = {
+            "artifact": "pass1/design_context_deferred.json",
+            "reason": "sublayer_count_exceeds_cap",
+        }
+    print(json.dumps(summary, indent=2))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()