@calibrate-ds/cli 0.1.24 → 0.1.26

package/dist/mcp/tools/action-tools.js

@@ -42,136 +42,143 @@ async function saveLock(workspaceRoot, lock) {
 export const actionTools = {
     name: "action",
     register(server, getContext) {
-        server.tool("run_scan", "Scan the Figma design file and update the local snapshot. Equivalent to running 'ptb scan' in the terminal. Requires FIGMA_ACCESS_TOKEN to be set in the environment.", async () => {
-            // Load config independently — no snapshot required (this tool creates the snapshot).
-            let config;
-            try {
-                const cwd = await resolveCwd();
-                config = await loadConfig(cwd);
-            }
-            catch (e) {
-                return { content: [{ type: "text", text: e.message }] };
-            }
-            // Check token first so the error points at the real problem.
-            const tokenEnv = config.designTool.accessTokenEnv;
-            const token = process.env[tokenEnv];
-            if (!token) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: `${tokenEnv} is not set in the MCP server environment.\n\nThe MCP server is a separate process from your terminal — it does not inherit your shell exports.\n\nFix options:\n  1. Add to ~/.zshrc or ~/.bashrc: export ${tokenEnv}=your_token\n     Then launch your IDE from the terminal (not the dock): e.g. 'cursor .' or 'code .'\n  2. Mac only (dock-launched IDEs): run in terminal: launchctl setenv ${tokenEnv} your_token\n     Then fully quit and relaunch your IDE.\n     NOTE: If you already ran launchctl setenv, the MCP server may have started before the token was set. Fully quitting and relaunching your IDE is required — the running server cannot see tokens set after it started.\n  3. Alternatively, run 'ptb scan' directly in your terminal where the token is already exported.`,
-                        }],
-                };
-            }
-            try {
-                const fileKey = config.designTool.fileKey;
-                const adapter = getDesignToolAdapter(config.designTool.provider);
-                const model = await adapter.scanDesignFile({ fileKey, accessToken: token });
-                // Mirror the full enrichment pipeline from scan.ts so MCP scans
-                // produce the same snapshot as CLI scans (tokens, icons, bitmaps, thumbnails).
-                const tokenResolution = await resolveTokenSource(config, token);
-                if (tokenResolution.tokens.length > 0) {
-                    model.tokens = tokenResolution.tokens;
+        server.tool("run", `Execute a PTB pipeline stage. Use this to scan Figma, generate code, or maintain the local design system state.
+
+PIPELINE ORDER — run stages in this sequence after first setup:
+  1. scan     → fetch Figma snapshot, enrich tokens/icons/thumbnails, auto-exports context
+  2. tokens   → regenerate CSS design token files from snapshot
+  3. generate → scaffold typed React component shells (accepts optional name param)
+  4. context  → re-export context files + update ptb.lock without re-scanning Figma
+  5. prune    → remove generated folders for components deleted from Figma
+
+WHEN TO USE EACH:
+  scan     — Figma file has changed or this is the first run. Requires FIGMA_ACCESS_TOKEN (or configured env var) in env.
+  tokens   — After scan, or whenever token values changed in Figma.
+  generate — After scan, or to scaffold a specific new component (use name param).
+  context  — After implementing components to refresh ptb.lock hashes; or after scan if you skipped it.
+  prune    — Components were deleted in Figma and their folders should be removed from the repo.`, {
+            stage: z.enum(["scan", "generate", "tokens", "context", "prune"])
+                .describe("Pipeline stage to execute"),
+            name: z.string().optional().default(".")
+                .describe("For stage:'generate' only — component name or '.' for all. Ignored by other stages."),
+        }, async ({ stage, name = "." }) => {
+            if (stage === "scan") {
+                let config;
+                try {
+                    const cwd = await resolveCwd();
+                    config = await loadConfig(cwd);
                 }
-                await enrichIconsWithSvg(model, fileKey, token, adapter);
-                await enrichBitmapAssets(model, fileKey, token, config);
-                await enrichComponentThumbnails(model, fileKey, token, config, adapter);
-                await saveSnapshot(model, config);
-                invalidateCache();
-                const manifest = await loadManifest(config).catch(() => ({ components: {} }));
-                await exportAllComponentContexts(model, config, manifest);
-                return { content: [{ type: "text", text: `Scan complete. ${model.components.length} components, ${model.tokens?.length ?? 0} token collections.` }] };
-            }
-            catch (e) {
-                return { content: [{ type: "text", text: `Scan failed: ${e.message}` }] };
-            }
-        });
-        server.tool("generate_components", "Regenerate typed React component shells from the latest snapshot. Equivalent to 'ptb generate-components'. Pass a component name or '.' for all.", { name: z.string().default(".").describe("Component name or '.' for all") }, async ({ name }) => {
-            let ctx;
-            try {
-                ctx = await getContext();
-            }
-            catch (e) {
-                return { content: [{ type: "text", text: e.message }] };
-            }
-            try {
-                const { snapshot, config } = ctx;
-                const targets = name === "." || name === "*"
-                    ? snapshot.components
-                    : snapshot.components.filter(c => c.name.toLowerCase() === name.toLowerCase() || toSlug(c.name) === toSlug(name));
-                if (targets.length === 0) {
-                    return { content: [{ type: "text", text: `No component found matching '${name}'.` }] };
+                catch (e) {
+                    return { content: [{ type: "text", text: e.message }] };
                 }
-                const generator = getGenerator(config.framework.name || "react");
-                const report = await generator.writeComponents(snapshot, config);
-                await syncManifestWithReport(config, report);
-                // Update Symbol Bridge
-                await updateBridge(targets, config);
-                const totalFiles = report.createdFiles.length + report.skippedFiles.length;
-                const lines = [
-                    `Generated ${report.createdFiles.length} new files, skipped ${report.skippedFiles.length} (already exist). Total: ${totalFiles} files across ${targets.length} components.`,
-                    ``,
-                    `These are scaffold shells — prop signatures and CSS stubs, not full implementations.`,
-                    `After you implement each component, run stamp_component to record it:`,
-                    `  • One component:  stamp_component { name: "ComponentName" }`,
-                    `  • All at once:    stamp_component { name: "." }`,
-                    ``,
-                    `Until stamped, coverage_summary will show them as unstamped and ptb status --fail-on-stale will flag them.`,
-                ];
-                return { content: [{ type: "text", text: lines.join("\n") }] };
-            }
-            catch (e) {
-                return { content: [{ type: "text", text: `Generation failed: ${e.message}` }] };
-            }
-        });
-        server.tool("generate_tokens", "Regenerate CSS design token files from the latest snapshot. Equivalent to 'ptb generate-tokens'.", async () => {
-            let ctx;
-            try {
-                ctx = await getContext();
-            }
-            catch (e) {
-                return { content: [{ type: "text", text: e.message }] };
-            }
-            try {
-                const { snapshot, config } = ctx;
-                if (!snapshot.tokens?.length) {
-                    return { content: [{ type: "text", text: "No token collections in snapshot. Run run_scan first." }] };
+                const tokenEnv = config.designTool.accessTokenEnv;
+                const token = process.env[tokenEnv];
+                if (!token) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `${tokenEnv} is not set in the MCP server environment.\n\nThe MCP server is a separate process from your terminal — it does not inherit your shell exports.\n\nFix options:\n  1. Add to ~/.zshrc or ~/.bashrc: export ${tokenEnv}=your_token\n     Then launch your IDE from the terminal (not the dock): e.g. 'cursor .' or 'code .'\n  2. Mac only (dock-launched IDEs): run in terminal: launchctl setenv ${tokenEnv} your_token\n     Then fully quit and relaunch your IDE.\n     NOTE: If you already ran launchctl setenv, the MCP server may have started before the token was set. Fully quitting and relaunching your IDE is required — the running server cannot see tokens set after it started.\n  3. Alternatively, run 'ptb scan' directly in your terminal where the token is already exported.`,
+                            }],
+                    };
+                }
+                try {
+                    const fileKey = config.designTool.fileKey;
+                    const adapter = getDesignToolAdapter(config.designTool.provider);
+                    const model = await adapter.scanDesignFile({ fileKey, accessToken: token });
+                    const tokenResolution = await resolveTokenSource(config, token);
+                    if (tokenResolution.tokens.length > 0)
+                        model.tokens = tokenResolution.tokens;
+                    await enrichIconsWithSvg(model, fileKey, token, adapter);
+                    await enrichBitmapAssets(model, fileKey, token, config);
+                    await enrichComponentThumbnails(model, fileKey, token, config, adapter);
+                    await saveSnapshot(model, config);
+                    invalidateCache();
+                    const manifest = await loadManifest(config).catch(() => ({ components: {} }));
+                    await exportAllComponentContexts(model, config, manifest);
+                    return { content: [{ type: "text", text: `Scan complete. ${model.components.length} components, ${model.tokens?.length ?? 0} token collections.` }] };
+                }
+                catch (e) {
+                    return { content: [{ type: "text", text: `Scan failed: ${e.message}` }] };
                 }
-                const generator = getGenerator(config.framework.name || "react");
-                const report = await generator.writeTokens(snapshot, config);
-                const totalTokenFiles = report.createdFiles.length + report.skippedFiles.length;
-                return { content: [{ type: "text", text: `Generated ${report.createdFiles.length} new token files, skipped ${report.skippedFiles.length} (already exist). Total: ${totalTokenFiles} token files on disk.` }] };
-            }
-            catch (e) {
-                return { content: [{ type: "text", text: `Token generation failed: ${e.message}` }] };
-            }
-        });
-        server.tool("export_context", "Export component context files to .ptb/context/ and update ptb.lock. Equivalent to 'ptb export context'. Run after a scan to make context available to AI tools.", async () => {
-            let ctx;
-            try {
-                ctx = await getContext();
             }
-            catch (e) {
-                return { content: [{ type: "text", text: e.message }] };
+            if (stage === "generate") {
+                let ctx;
+                try {
+                    ctx = await getContext();
+                }
+                catch (e) {
+                    return { content: [{ type: "text", text: e.message }] };
+                }
+                try {
+                    const { snapshot, config } = ctx;
+                    const targets = name === "." || name === "*"
+                        ? snapshot.components
+                        : snapshot.components.filter(c => c.name.toLowerCase() === name.toLowerCase() || toSlug(c.name) === toSlug(name));
+                    if (targets.length === 0) {
+                        return { content: [{ type: "text", text: `No component found matching '${name}'.` }] };
+                    }
+                    const generator = getGenerator(config.framework.name || "react");
+                    const report = await generator.writeComponents(snapshot, config);
+                    await syncManifestWithReport(config, report);
+                    await updateBridge(targets, config);
+                    const totalFiles = report.createdFiles.length + report.skippedFiles.length;
+                    const lines = [
+                        `Generated ${report.createdFiles.length} new files, skipped ${report.skippedFiles.length} (already exist). Total: ${totalFiles} files across ${targets.length} components.`,
+                        ``,
+                        `These are scaffold shells — prop signatures and CSS stubs, not full implementations.`,
+                        `After you implement each component, call submit_work to record it as done:`,
+                        `  • submit_work({ name: "ComponentName", folder: "src/components/..." })`,
+                        `  • Bulk stamp (CLI only): ptb stamp component .`,
+                        ``,
+                        `Until stamped, get_status will show them as not-stamped and ptb status --fail-on-stale will flag them.`,
+                    ];
+                    return { content: [{ type: "text", text: lines.join("\n") }] };
+                }
+                catch (e) {
+                    return { content: [{ type: "text", text: `Generation failed: ${e.message}` }] };
+                }
             }
-            try {
-                const { snapshot, config } = ctx;
-                const manifest = await loadManifest(config).catch(() => ({ components: {} }));
-                const paths = await exportAllComponentContexts(snapshot, config, manifest);
-                return { content: [{ type: "text", text: `Exported ${paths.length} context files to .ptb/context/.` }] };
+            if (stage === "tokens") {
+                let ctx;
+                try {
+                    ctx = await getContext();
+                }
+                catch (e) {
+                    return { content: [{ type: "text", text: e.message }] };
+                }
+                try {
+                    const { snapshot, config } = ctx;
+                    if (!snapshot.tokens?.length) {
+                        return { content: [{ type: "text", text: "No token collections in snapshot. Run run({ stage:'scan' }) first." }] };
+                    }
+                    const generator = getGenerator(config.framework.name || "react");
+                    const report = await generator.writeTokens(snapshot, config);
+                    const totalTokenFiles = report.createdFiles.length + report.skippedFiles.length;
+                    return { content: [{ type: "text", text: `Generated ${report.createdFiles.length} new token files, skipped ${report.skippedFiles.length} (already exist). Total: ${totalTokenFiles} token files on disk.` }] };
+                }
+                catch (e) {
+                    return { content: [{ type: "text", text: `Token generation failed: ${e.message}` }] };
+                }
             }
-            catch (e) {
-                return { content: [{ type: "text", text: `Export failed: ${e.message}` }] };
+            if (stage === "context") {
+                let ctx;
+                try {
+                    ctx = await getContext();
+                }
+                catch (e) {
+                    return { content: [{ type: "text", text: e.message }] };
+                }
+                try {
+                    const { snapshot, config } = ctx;
+                    const manifest = await loadManifest(config).catch(() => ({ components: {} }));
+                    const paths = await exportAllComponentContexts(snapshot, config, manifest);
+                    return { content: [{ type: "text", text: `Exported ${paths.length} context files to .ptb/context/.` }] };
+                }
+                catch (e) {
+                    return { content: [{ type: "text", text: `Export failed: ${e.message}` }] };
+                }
             }
-        });
-        server.tool("stamp_component", `Mark a component as implemented against the current design. Equivalent to 'ptb stamp component <name>'. Use '.' to stamp all components.
-
-Optionally pass folder + artifacts to register the component's files in manifest.json — this is required for the ptb dev playground to pick up the component automatically. If ptb dev is running, the playground will hot-reload as soon as the manifest is updated.`, {
-            name: z.string().describe("Component name or '.' for all"),
-            message: z.string().optional().describe("Optional note about what was implemented"),
-            folder: z.string().optional().describe("Relative path from packageRoot to the component folder, e.g. 'src/components/web/btn-web'. Required for playground auto-registration."),
-            artifacts: z.array(z.string()).optional().describe("List of artifact paths relative to packageRoot, e.g. ['src/components/web/btn-web/BtnWeb.tsx', ...]. Defaults to [folder] if omitted."),
-        }, async ({ name, message, folder, artifacts }) => {
+            // stage === "prune"
             let ctx;
             try {
                 ctx = await getContext();
@@ -180,61 +187,19 @@ Optionally pass folder + artifacts to register the component's files in manifest
                 return { content: [{ type: "text", text: e.message }] };
             }
             try {
-                const lock = await loadLock(ctx.workspaceRoot);
-                if (!lock) {
-                    return { content: [{ type: "text", text: "No ptb.lock found. Run export_context first." }] };
-                }
-                const identity = getGitIdentity();
-                const now = new Date().toISOString();
-                const stamped = [];
-                const entries = name === "." || name === "*"
-                    ? Object.entries(lock.components)
-                    : Object.entries(lock.components).filter(([slug, e]) => slug === toSlug(name) || e.displayName.toLowerCase() === name.toLowerCase());
-                if (entries.length === 0) {
-                    return { content: [{ type: "text", text: `No component found in ptb.lock matching '${name}'.` }] };
-                }
-                for (const [slug, entry] of entries) {
-                    // Build stampedContract from the live snapshot so diff is
-                    // scan-timing-independent (same logic as CLI stampInLock).
-                    const modelComponent = ctx.snapshot.components.find(c => c.name.toLowerCase() === entry.displayName.toLowerCase() ||
-                        c.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") === slug);
-                    const stampedContract = modelComponent ? {
-                        ...(modelComponent.variantAxes ? { variantAxes: modelComponent.variantAxes } : {}),
-                        ...(modelComponent.properties ? { properties: modelComponent.properties } : {}),
-                        ...(modelComponent.tokenBindings ? { tokenBindings: modelComponent.tokenBindings } : {}),
-                        ...(modelComponent.styleMetadata ? { styleMetadata: modelComponent.styleMetadata } : {}),
-                        ...(modelComponent.layout ? { layout: modelComponent.layout } : {}),
-                    } : undefined;
-                    lock.components[slug] = {
-                        ...entry,
-                        stampedHash: entry.designHash,
-                        stampedAt: now,
-                        stampedBy: identity,
-                        workStatus: "stamped",
-                        ...(message ? { stampedMessage: message } : {}),
-                        ...(stampedContract ? { stampedContract } : {}),
-                    };
-                    stamped.push(entry.displayName);
-                }
-                await saveLock(ctx.workspaceRoot, lock);
-                // If the caller provided file paths, register them in manifest.json.
-                // This triggers the ptb dev playground watcher so the component appears
-                // in the playground without a manual `ptb dev` restart.
-                const manifestNotes = [];
-                if (folder && entries.length === 1) {
-                    const [, entry] = entries[0];
-                    const comp = ctx.snapshot.components.find((c) => c.name === entry.displayName);
-                    if (comp) {
-                        const resolvedArtifacts = artifacts ?? [folder];
-                        await updateComponentArtifacts(ctx.config, comp.id, comp.name, folder, resolvedArtifacts, ctx.config.framework?.name ?? "react");
-                        manifestNotes.push(`Registered in manifest.json → folder: ${folder}`);
-                    }
+                const result = await pruneStaleComponents(ctx.config, ctx.snapshot);
+                if (result.found === 0) {
+                    return { content: [{ type: "text", text: "No stale artifacts to prune." }] };
                 }
-                const detail = manifestNotes.length > 0 ? `\n${manifestNotes.join("\n")}` : "";
-                return { content: [{ type: "text", text: `Stamped ${stamped.length} component(s): ${stamped.join(", ")}${detail}` }] };
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ found: result.found, deleted: result.deleted, skipped: result.skipped, errors: result.errors }, null, 2),
+                        }],
+                };
             }
             catch (e) {
-                return { content: [{ type: "text", text: `Stamp failed: ${e.message}` }] };
+                return { content: [{ type: "text", text: `Prune failed: ${e.message}` }] };
             }
         });
         server.tool("assign_component", "Assign a component to a developer. Stores assignment metadata (priority, due date, notes, acceptance criteria) in ptb.lock.", {
@@ -301,7 +266,7 @@ TOKEN AUTHORITY — what to trust, what to verify:
 DIVISION OF LABOR WITH FIGMA MCP (composite workflow — most accurate):
   PTB  → token names, dependency graph, variant axes, state/content contracts (read contextFile)
   Figma → exact hex values, spacing, visual arrangement (get_variable_defs, get_screenshot)
-  Map: Figma hex  →  get_token_by_value(hex)  →  --ptb-* cssVar name → emit both together
+  Map: Figma hex  →  get_token(hex)  →  --ptb-* cssVar name → emit both together
 
 TYPICAL WORKFLOW:
 1. Call start_work("<name>") — read blockedBy and tokenConflicts first
@@ -433,18 +398,24 @@ TYPICAL WORKFLOW:
                 return { content: [{ type: "text", text: `start_work failed: ${e.message}` }] };
             }
         });
-        server.tool("submit_work", `Submit completed implementation work for a component.
+        server.tool("submit_work", `Submit completed implementation work for a component. Use after writing all component files.
 
-Stamps the component (records the current design hash as implemented) and transitions
-its work lifecycle. Use after writing all component files.
+Stamps the component (records the current design hash + design contract snapshot) and
+transitions its work lifecycle. This is the canonical "I'm done" signal — always call
+this after implement_component and writing the code.
 
 transitionTo options:
 - "stamped" (default): stamps immediately — for solo work or when you're the reviewer
-- "in_review": marks as ready for review without stamping — for teams where a reviewer stamps later`, {
+- "in_review": marks as ready for review without stamping — for teams where a reviewer stamps later
+
+folder + artifacts: register the component's files in manifest.json so the ptb dev
+playground picks it up automatically (hot-reloads on save if ptb dev is running).`, {
             name: z.string().describe("Component name to submit"),
-            transitionTo: z.enum(["stamped", "in_review"]).optional().describe("Target status after submitting. Default: 'stamped'"),
+            transitionTo: z.enum(["stamped", "in_review"]).optional().describe("Target status. Default: 'stamped'"),
             message: z.string().optional().describe("Optional implementation note"),
-        }, async ({ name, transitionTo = "stamped", message }) => {
+            folder: z.string().optional().describe("Relative path from packageRoot to the component folder, e.g. 'src/components/web/btn-web'. Required for playground auto-registration."),
+            artifacts: z.array(z.string()).optional().describe("Artifact paths relative to packageRoot, e.g. ['src/components/web/btn-web/BtnWeb.tsx']. Defaults to [folder] if omitted."),
+        }, async ({ name, transitionTo = "stamped", message, folder, artifacts }) => {
             let ctx;
             try {
                 ctx = await getContext();
@@ -455,7 +426,7 @@ transitionTo options:
             try {
                 const lock = await loadLock(ctx.workspaceRoot);
                 if (!lock) {
-                    return { content: [{ type: "text", text: "No ptb.lock found. Run export_context first." }] };
+                    return { content: [{ type: "text", text: "No ptb.lock found. Run run({ stage:'context' }) first." }] };
                 }
                 const entries = Object.entries(lock.components).filter(([slug, e]) => slug === toSlug(name) || e.displayName.toLowerCase() === name.toLowerCase());
                 if (entries.length === 0) {
@@ -465,6 +436,15 @@ transitionTo options:
                 const now = new Date().toISOString();
                 for (const [slug, entry] of entries) {
                     if (transitionTo === "stamped") {
+                        const modelComponent = ctx.snapshot.components.find(c => c.name.toLowerCase() === entry.displayName.toLowerCase() ||
+                            c.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") === slug);
+                        const stampedContract = modelComponent ? {
+                            ...(modelComponent.variantAxes ? { variantAxes: modelComponent.variantAxes } : {}),
+                            ...(modelComponent.properties ? { properties: modelComponent.properties } : {}),
+                            ...(modelComponent.tokenBindings ? { tokenBindings: modelComponent.tokenBindings } : {}),
+                            ...(modelComponent.styleMetadata ? { styleMetadata: modelComponent.styleMetadata } : {}),
+                            ...(modelComponent.layout ? { layout: modelComponent.layout } : {}),
+                        } : undefined;
                         lock.components[slug] = {
                             ...entry,
                             stampedHash: entry.designHash,
@@ -472,6 +452,7 @@ transitionTo options:
                             stampedBy: identity,
                             workStatus: "stamped",
                             ...(message ? { stampedMessage: message } : {}),
+                            ...(stampedContract ? { stampedContract } : {}),
                         };
                     }
                     else {
@@ -483,11 +464,20 @@ transitionTo options:
                     }
                 }
                 await saveLock(ctx.workspaceRoot, lock);
+                // Register artifact paths in manifest.json for playground hot-reload
+                const manifestNotes = [];
+                if (folder && transitionTo === "stamped" && entries.length === 1) {
+                    const [, entry] = entries[0];
+                    const comp = ctx.snapshot.components.find(c => c.name === entry.displayName);
+                    if (comp) {
+                        await updateComponentArtifacts(ctx.config, comp.id, comp.name, folder, artifacts ?? [folder], ctx.config.framework?.name ?? "react");
+                        manifestNotes.push(`Registered in manifest.json → folder: ${folder}`);
+                    }
+                }
                 const names = entries.map(([, e]) => e.displayName).join(", ");
-                const action = transitionTo === "stamped"
-                    ? `Stamped and marked as done`
-                    : `Submitted for review (not yet stamped)`;
-                return { content: [{ type: "text", text: `${action}: ${names}` }] };
+                const action = transitionTo === "stamped" ? `Stamped and marked as done` : `Submitted for review (not yet stamped)`;
+                const detail = manifestNotes.length > 0 ? `\n${manifestNotes.join("\n")}` : "";
+                return { content: [{ type: "text", text: `${action}: ${names}${detail}` }] };
             }
             catch (e) {
                 return { content: [{ type: "text", text: `submit_work failed: ${e.message}` }] };
@@ -509,8 +499,7 @@ TOKEN AUTHORITY — what to trust, what to verify:
 
 WORKFLOW — follow this exactly:
 1. Check unbuiltDependencies. If any exist, call implement_component for each one in buildOrder first.
-   - autoGeneratedIcons are handled by ptb automatically — do NOT call stamp_component for them,
-     they are not tracked in ptb.lock.
+   - autoGeneratedIcons are handled by ptb automatically — they are not tracked in ptb.lock.
 2. For each component in buildOrder (dependencies first, then the requested component):
    a. Read contextFile for the full implementation brief (promptText, renderTree, variantDiffs).
    b. Write the required files: <Name>.tsx, <Name>.types.ts, <Name>.module.css, index.ts
@@ -518,8 +507,8 @@ WORKFLOW — follow this exactly:
       - Populate story args from contentSourceMap (username, title, etc.) using the base values
         shown in the Content Contracts section of promptText.
       - Include at least one populated story so the playground/Storybook preview matches the design.
-   d. After writing ALL files, call stamp_component with the folder path so the playground updates.
-3. Never skip stamp_component — it is what marks the component as done and keeps ptb.lock in sync.
+   d. After writing ALL files, call submit_work with the folder path so the playground updates.
+3. Never skip submit_work — it records stampedContract and keeps ptb.lock in sync.
 
 If a dependency also has its own unbuilt dependencies, implement_component will surface those
 recursively when you call it for that dependency.`, { name: z.string().describe("Component name to implement, e.g. 'SearchBar' or 'BtnWeb'") }, async ({ name }) => {
@@ -552,7 +541,7 @@ recursively when you call it for that dependency.`, { name: z.string().describe(
                 depIds.delete(comp.id);
                 const depComponents = ctx.snapshot.components.filter((c) => depIds.has(c.id));
                 // Icons are auto-generated deterministically by ptb — they are NOT tracked
-                // in ptb.lock (writeLockFile skips them), so calling stamp_component on them
+                // in ptb.lock (writeLockFile skips them), so calling submit_work on them
                 // will always fail with "not found". Split them out so the agent never tries.
                 const iconDeps = depComponents.filter((c) => isIconComponent(c.name));
                 const nonIconDeps = depComponents.filter((c) => !isIconComponent(c.name));
@@ -639,30 +628,6 @@ recursively when you call it for that dependency.`, { name: z.string().describe(
                 return { content: [{ type: "text", text: `implement_component failed: ${e.message}` }] };
             }
         });
-        server.tool("run_prune", "Remove stale generated component folders that are no longer in the design system (present in manifest but deleted from Figma). Also cleans up ptb.lock entries. Equivalent to 'ptb prune'.", async () => {
-            let ctx;
-            try {
-                ctx = await getContext();
-            }
-            catch (e) {
-                return { content: [{ type: "text", text: e.message }] };
-            }
-            try {
-                const result = await pruneStaleComponents(ctx.config, ctx.snapshot);
-                if (result.found === 0) {
-                    return { content: [{ type: "text", text: "No stale artifacts to prune." }] };
-                }
-                return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({ found: result.found, deleted: result.deleted, skipped: result.skipped, errors: result.errors }, null, 2),
-                        }],
-                };
-            }
-            catch (e) {
-                return { content: [{ type: "text", text: `run_prune failed: ${e.message}` }] };
-            }
-        });
         server.tool("document_component", "Generate MDX docs and/or Storybook stories for a component. Pass '.' to document all. The docs tool is read from ptb.config.json (docs.tool). Equivalent to 'ptb document component <name>'.", {
             name: z.string().describe("Component name or '.' for all"),
             format: z.enum(["mdx", "stories", "both"]).optional().describe("Output format. Default: mdx"),
@@ -726,7 +691,7 @@ recursively when you call it for that dependency.`, { name: z.string().describe(
                         const componentFile = path.join(baseOutputDir, `${codeName}.${ext}`);
                         const componentExists = await fs.access(componentFile).then(() => true).catch(() => false);
                         if (!componentExists) {
-                            skipped.push(`${codeName}.stories.tsx (${codeName}.${ext} not found — run generate_components first)`);
+                            skipped.push(`${codeName}.stories.tsx (${codeName}.${ext} not found — run run({ stage:'generate' }) first)`);
                             continue;
                         }
                         const storiesContent = generateComponentStories(context, codeName, fileKey);