sdtk-design-kit 0.2.1 → 0.3.1

package/src/commands/handoff.js

@@ -1,60 +1,60 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
 const { parseFlags } = require("../lib/args");
 const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths");
-const { inferDomainProfile } = require("../lib/domain-profile");
-const { ValidationError } = require("../lib/errors");
-
-const HANDOFF_FLAG_DEFS = {
-  help: { type: "boolean" },
-  "project-path": { type: "string" },
-  force: { type: "boolean" },
-};
-
-const REQUIRED_WIREFRAMES = ["LANDING.md", "ONBOARDING.md", "DASHBOARD.md"];
-
-function cmdHandoffHelp() {
-  console.log(`SDTK-DESIGN Handoff
-
-Usage:
-  sdtk-design handoff [--project-path <path>] [--force]
-
-Example:
-  sdtk-design handoff
-
-Reads:
-  docs/design/DESIGN_BRIEF.md
-  docs/design/SCREEN_MAP.md
-  docs/design/wireframes/LANDING.md
-  docs/design/wireframes/ONBOARDING.md
-  docs/design/wireframes/DASHBOARD.md
-  docs/design/DESIGN_SYSTEM.md
-
-Creates:
-  docs/design/DESIGN_HANDOFF.md
-
-Safety:
-  Local files only.
-  Existing DESIGN_HANDOFF.md is not overwritten unless --force is explicit.
-  No .sdtk/atlas creation or mutation.
-  No SDTK-WIKI output mutation.
-  No network call, Pro entitlement, or production app code generation.`);
-  return 0;
-}
-
+const { inferDomainProfile } = require("../lib/domain-profile");
+const { ValidationError } = require("../lib/errors");
+
+const HANDOFF_FLAG_DEFS = {
+  help: { type: "boolean" },
+  "project-path": { type: "string" },
+  force: { type: "boolean" },
+};
+
+const REQUIRED_WIREFRAMES = ["LANDING.md", "ONBOARDING.md", "DASHBOARD.md"];
+
+function cmdHandoffHelp() {
+  console.log(`SDTK-DESIGN Handoff
+
+Usage:
+  sdtk-design handoff [--project-path <path>] [--force]
+
+Example:
+  sdtk-design handoff
+
+Reads:
+  docs/design/DESIGN_BRIEF.md
+  docs/design/SCREEN_MAP.md
+  docs/design/wireframes/LANDING.md
+  docs/design/wireframes/ONBOARDING.md
+  docs/design/wireframes/DASHBOARD.md
+  docs/design/DESIGN_SYSTEM.md
+
+Creates:
+  docs/design/DESIGN_HANDOFF.md
+
+Safety:
+  Local files only.
+  Existing DESIGN_HANDOFF.md is not overwritten unless --force is explicit.
+  No .sdtk/atlas creation or mutation.
+  No SDTK-WIKI output mutation.
+  No network call, Pro entitlement, or production app code generation.`);
+  return 0;
+}
+
 function requiredArtifacts(paths) {
-  return [
-    { label: "Design brief", relativePath: "docs/design/DESIGN_BRIEF.md", filePath: paths.designBriefPath },
-    { label: "Screen map", relativePath: "docs/design/SCREEN_MAP.md", filePath: paths.screenMapPath },
-    { label: "Design system", relativePath: "docs/design/DESIGN_SYSTEM.md", filePath: paths.designSystemPath },
-    ...REQUIRED_WIREFRAMES.map((fileName) => ({
-      label: `${fileName.replace(".md", "")} wireframe`,
-      relativePath: `docs/design/wireframes/${fileName}`,
-      filePath: path.join(paths.wireframesPath, fileName),
-    })),
-  ];
+  return [
+    { label: "Design brief", relativePath: "docs/design/DESIGN_BRIEF.md", filePath: paths.designBriefPath },
+    { label: "Screen map", relativePath: "docs/design/SCREEN_MAP.md", filePath: paths.screenMapPath },
+    { label: "Design system", relativePath: "docs/design/DESIGN_SYSTEM.md", filePath: paths.designSystemPath },
+    ...REQUIRED_WIREFRAMES.map((fileName) => ({
+      label: `${fileName.replace(".md", "")} wireframe`,
+      relativePath: `docs/design/wireframes/${fileName}`,
+      filePath: path.join(paths.wireframesPath, fileName),
+    })),
+  ];
 }
 
 function readJsonSafe(filePath) {
@@ -130,140 +130,140 @@ function normalizeScreenRole(screen) {
   if (token.includes("configurator") || token.includes("mode-b")) return "mode-b-configurator";
   return screen.screenId || "screen";
 }
-
+
 function handoffContent({ hasPrototype = false, prototypeRefs = [], profile = inferDomainProfile() } = {}) {
   const prototypeReference = hasPrototype
     ? "`docs/design/prototype/index.html` is available as the static visual preview reference."
     : "Run `sdtk-design prototype` to create `docs/design/prototype/index.html` before implementation if visual preview evidence is needed.";
-  const setupKey = profile.storageKeys[0];
-  const itemKey = profile.storageKeys[1];
-
-  return [
-    "# Design Handoff",
-    "",
-    "## Readiness Verdict",
-    "",
-    "- Verdict: READY_FOR_SDTK_CODE",
-    "- Rationale: Required Phase A design artifacts exist and provide enough screen, component, state, and design-system context for implementation planning.",
-    "",
-    "## Source Artifacts",
-    "",
-    "- `docs/design/DESIGN_BRIEF.md`",
-    "- `docs/design/SCREEN_MAP.md`",
-    "- `docs/design/wireframes/LANDING.md`",
-    "- `docs/design/wireframes/ONBOARDING.md`",
-    "- `docs/design/wireframes/DASHBOARD.md`",
-    "- `docs/design/DESIGN_SYSTEM.md`",
-    hasPrototype ? "- `docs/design/prototype/index.html`" : "- `docs/design/prototype/index.html` (optional, not present at handoff time)",
-    "",
-    "## Screen-To-Component Mapping",
-    "",
-    "| Screen | Design artifact | Component direction |",
-    "|---|---|---|",
-    "| Landing | `docs/design/wireframes/LANDING.md` | Header, hero copy, primary CTA, workflow preview, benefit bullets |",
-    "| Onboarding | `docs/design/wireframes/ONBOARDING.md` | Progress indicator, setup form, segmented sample-data control, inline validation, continue CTA |",
-    `| Dashboard | \`docs/design/wireframes/DASHBOARD.md\` | Summary counters, ${profile.collectionSurface}, status treatment, quick-add action, empty-state panel, recoverable error alert |`,
-    "",
-    "## Screen-To-User-Story Mapping",
-    "",
-    "| Screen | User story | Acceptance signal |",
-    "|---|---|---|",
-    `| Landing | As ${profile.targetUser}, I want to understand the ${profile.productName} promise so I can decide whether to start. | Primary CTA is visible and routes to onboarding. |`,
-    `| Onboarding | As a new user, I want a short setup path so I can create my first ${profile.itemSingular} without heavy configuration. | Required fields are clear, validation is inline, and entered values are preserved on error. |`,
-    `| Dashboard | As ${profile.targetUser}, I want to see active ${profile.itemPlural} and next actions so I can choose what to do next. | ${profile.itemPlural.charAt(0).toUpperCase() + profile.itemPlural.slice(1)}, next actions, context, and status are scannable with empty and error states. |`,
-    "",
-    "## Design Decisions",
-    "",
-    "- Keep the MVP to three core screens: Landing, Onboarding, and Dashboard.",
-    "- Optimize for repeated action and scan speed over decorative presentation.",
-    "- Use a restrained operational design system with stable controls, clear form states, and accessible status language.",
-    "- Preserve `docs/design` as the human-facing design output boundary.",
-    "",
-    "## Implementation Notes For SDTK-CODE",
-    "",
-    "- Treat the markdown artifacts as planning input, not generated production code.",
-    "- Implement screens in this order: Landing, Onboarding, Dashboard.",
-    "- Keep user data capture minimal until the first useful workflow is complete.",
-    "- Preserve empty, success, and error states from the screen map and wireframes.",
-    "- Apply typography, color, spacing, button, card, form, tone, and accessibility rules from `DESIGN_SYSTEM.md`.",
-    "",
-    "## Suggested Data Model",
-    "",
-    "Workspace fields:",
-    "",
-    "- `id`: local identifier.",
-    `- \`name\`: ${profile.setupLabel.toLowerCase()} name.`,
-    "- `createdAt`: ISO timestamp.",
-    "",
-    `${profile.modelName} fields:`,
-    "",
-    "- `id`: local identifier.",
-    `- \`name\`: ${profile.itemSingular} name or label.`,
-    "- `status`: workflow status.",
-    "- `nextAction`: next action or due context.",
-    "- `note`: latest context note or summary.",
-    "- `createdAt`: ISO timestamp.",
-    "- `updatedAt`: ISO timestamp.",
-    "",
-    "## Domain Vocabulary / Status Taxonomy",
-    "",
-    `- ${profile.itemLabel}: the primary record the MVP helps the user create and track.`,
-    "- Next action: the next planned step needed to keep the workflow moving.",
-    "- Note: short context needed before the next action.",
-    `- ${profile.collectionSurface.charAt(0).toUpperCase() + profile.collectionSurface.slice(1)}: the grouped view for active ${profile.itemPlural}.`,
-    `- Status taxonomy: ${profile.statusTaxonomy.join(", ")}.`,
-    "",
-    "## Interaction Flow",
-    "",
-    "1. Landing -> user chooses the primary CTA.",
-    `2. Onboarding -> user enters ${profile.setupLabel.toLowerCase()} name and continues.`,
-    `3. Dashboard -> user sees empty state, ${profile.itemSingular} form, and status counters.`,
-    `4. ${profile.itemAction} -> validate required fields, append ${profile.itemSingular}, update list/counts, and show the saved note/next action.`,
-    `5. Refresh -> restore ${profile.setupLabel.toLowerCase()} and ${profile.itemPlural} from local persistence before rendering dashboard state.`,
-    "",
-    "## Persistence Guidance",
-    "",
-    "- For a frontend-only MVP, use browser `localStorage` or equivalent local persistence.",
-    `- Suggested keys: \`${setupKey}\` and \`${itemKey}\`.`,
-    "- Store arrays/objects as JSON and tolerate parse failures by falling back to empty state.",
-    "- Do not introduce backend, API, auth, database, or network persistence unless a later SDTK-CODE task explicitly adds it.",
-    "",
-    "## Visual Implementation Contract",
-    "",
-    "- Implement the selected visual preset from `DESIGN_SYSTEM.md` before adding extra decoration.",
-    `- Preserve landing hero hierarchy, onboarding form clarity, dashboard metric density, ${profile.collectionSurface}, status treatment, and empty state.`,
-    "- Keep responsive behavior explicit: grids collapse at mobile width and controls remain at least 44px tall.",
-    "- Pair every status color with text; do not rely on color alone.",
-    "- Avoid shipping a gray wireframe look when the prototype/design system provides finished tokens.",
-    "",
+  const setupKey = profile.storageKeys[0];
+  const itemKey = profile.storageKeys[1];
+
+  return [
+    "# Design Handoff",
+    "",
+    "## Readiness Verdict",
+    "",
+    "- Verdict: READY_FOR_SDTK_CODE",
+    "- Rationale: Required Phase A design artifacts exist and provide enough screen, component, state, and design-system context for implementation planning.",
+    "",
+    "## Source Artifacts",
+    "",
+    "- `docs/design/DESIGN_BRIEF.md`",
+    "- `docs/design/SCREEN_MAP.md`",
+    "- `docs/design/wireframes/LANDING.md`",
+    "- `docs/design/wireframes/ONBOARDING.md`",
+    "- `docs/design/wireframes/DASHBOARD.md`",
+    "- `docs/design/DESIGN_SYSTEM.md`",
+    hasPrototype ? "- `docs/design/prototype/index.html`" : "- `docs/design/prototype/index.html` (optional, not present at handoff time)",
+    "",
+    "## Screen-To-Component Mapping",
+    "",
+    "| Screen | Design artifact | Component direction |",
+    "|---|---|---|",
+    "| Landing | `docs/design/wireframes/LANDING.md` | Header, hero copy, primary CTA, workflow preview, benefit bullets |",
+    "| Onboarding | `docs/design/wireframes/ONBOARDING.md` | Progress indicator, setup form, segmented sample-data control, inline validation, continue CTA |",
+    `| Dashboard | \`docs/design/wireframes/DASHBOARD.md\` | Summary counters, ${profile.collectionSurface}, status treatment, quick-add action, empty-state panel, recoverable error alert |`,
+    "",
+    "## Screen-To-User-Story Mapping",
+    "",
+    "| Screen | User story | Acceptance signal |",
+    "|---|---|---|",
+    `| Landing | As ${profile.targetUser}, I want to understand the ${profile.productName} promise so I can decide whether to start. | Primary CTA is visible and routes to onboarding. |`,
+    `| Onboarding | As a new user, I want a short setup path so I can create my first ${profile.itemSingular} without heavy configuration. | Required fields are clear, validation is inline, and entered values are preserved on error. |`,
+    `| Dashboard | As ${profile.targetUser}, I want to see active ${profile.itemPlural} and next actions so I can choose what to do next. | ${profile.itemPlural.charAt(0).toUpperCase() + profile.itemPlural.slice(1)}, next actions, context, and status are scannable with empty and error states. |`,
+    "",
+    "## Design Decisions",
+    "",
+    "- Keep the MVP to three core screens: Landing, Onboarding, and Dashboard.",
+    "- Optimize for repeated action and scan speed over decorative presentation.",
+    "- Use a restrained operational design system with stable controls, clear form states, and accessible status language.",
+    "- Preserve `docs/design` as the human-facing design output boundary.",
+    "",
+    "## Implementation Notes For SDTK-CODE",
+    "",
+    "- Treat the markdown artifacts as planning input, not generated production code.",
+    "- Implement screens in this order: Landing, Onboarding, Dashboard.",
+    "- Keep user data capture minimal until the first useful workflow is complete.",
+    "- Preserve empty, success, and error states from the screen map and wireframes.",
+    "- Apply typography, color, spacing, button, card, form, tone, and accessibility rules from `DESIGN_SYSTEM.md`.",
+    "",
+    "## Suggested Data Model",
+    "",
+    "Workspace fields:",
+    "",
+    "- `id`: local identifier.",
+    `- \`name\`: ${profile.setupLabel.toLowerCase()} name.`,
+    "- `createdAt`: ISO timestamp.",
+    "",
+    `${profile.modelName} fields:`,
+    "",
+    "- `id`: local identifier.",
+    `- \`name\`: ${profile.itemSingular} name or label.`,
+    "- `status`: workflow status.",
+    "- `nextAction`: next action or due context.",
+    "- `note`: latest context note or summary.",
+    "- `createdAt`: ISO timestamp.",
+    "- `updatedAt`: ISO timestamp.",
+    "",
+    "## Domain Vocabulary / Status Taxonomy",
+    "",
+    `- ${profile.itemLabel}: the primary record the MVP helps the user create and track.`,
+    "- Next action: the next planned step needed to keep the workflow moving.",
+    "- Note: short context needed before the next action.",
+    `- ${profile.collectionSurface.charAt(0).toUpperCase() + profile.collectionSurface.slice(1)}: the grouped view for active ${profile.itemPlural}.`,
+    `- Status taxonomy: ${profile.statusTaxonomy.join(", ")}.`,
+    "",
+    "## Interaction Flow",
+    "",
+    "1. Landing -> user chooses the primary CTA.",
+    `2. Onboarding -> user enters ${profile.setupLabel.toLowerCase()} name and continues.`,
+    `3. Dashboard -> user sees empty state, ${profile.itemSingular} form, and status counters.`,
+    `4. ${profile.itemAction} -> validate required fields, append ${profile.itemSingular}, update list/counts, and show the saved note/next action.`,
+    `5. Refresh -> restore ${profile.setupLabel.toLowerCase()} and ${profile.itemPlural} from local persistence before rendering dashboard state.`,
+    "",
+    "## Persistence Guidance",
+    "",
+    "- For a frontend-only MVP, use browser `localStorage` or equivalent local persistence.",
+    `- Suggested keys: \`${setupKey}\` and \`${itemKey}\`.`,
+    "- Store arrays/objects as JSON and tolerate parse failures by falling back to empty state.",
+    "- Do not introduce backend, API, auth, database, or network persistence unless a later SDTK-CODE task explicitly adds it.",
+    "",
+    "## Visual Implementation Contract",
+    "",
+    "- Implement the selected visual preset from `DESIGN_SYSTEM.md` before adding extra decoration.",
+    `- Preserve landing hero hierarchy, onboarding form clarity, dashboard metric density, ${profile.collectionSurface}, status treatment, and empty state.`,
+    "- Keep responsive behavior explicit: grids collapse at mobile width and controls remain at least 44px tall.",
+    "- Pair every status color with text; do not rely on color alone.",
+    "- Avoid shipping a gray wireframe look when the prototype/design system provides finished tokens.",
+    "",
     "## Prototype Reference",
     "",
     `- ${prototypeReference}`,
     ...(prototypeRefs.length > 0 ? prototypeRefs.map((ref) => `- \`${ref}\``) : []),
     "- Treat the prototype as visual direction only, not production application code.",
-    "",
-    "## SDTK-CODE Build Notes",
-    "",
-    "- A static frontend implementation may use `app/index.html`, `app/styles.css`, and `app/app.js` when no framework is required.",
-    "- Keep runtime dependencies optional; this handoff does not require a framework, server, or package install.",
-    `- Add verification for local rendering, ${profile.itemAction.toLowerCase()} behavior, persistence after refresh, and mobile-width layout.`,
-    "- SDTK-CODE owns implementation planning, code changes, tests, and ship readiness.",
-    "",
-    "## Acceptance Criteria",
-    "",
-    "- Landing renders the product promise, workflow preview, and a single dominant primary CTA.",
-    "- Onboarding captures only required setup data and keeps validation inline.",
-    `- Dashboard shows active ${profile.itemPlural}, next action, status, empty state, and recoverable error state.`,
-    "- Components follow the design system tokens and accessibility baseline.",
-    "- No production app code, network integration, Pro entitlement, `.sdtk/atlas`, or SDTK-WIKI mutation is implied by this handoff.",
-    "",
-    "## Non-Goals",
-    "",
-    "- Figma, Lovable, v0, or full app-builder replacement behavior.",
-    `- ${profile.nonGoals}`,
-    "- Package publish or deployment.",
-    "",
-  ].join("\n");
+    "",
+    "## SDTK-CODE Build Notes",
+    "",
+    "- A static frontend implementation may use `app/index.html`, `app/styles.css`, and `app/app.js` when no framework is required.",
+    "- Keep runtime dependencies optional; this handoff does not require a framework, server, or package install.",
+    `- Add verification for local rendering, ${profile.itemAction.toLowerCase()} behavior, persistence after refresh, and mobile-width layout.`,
+    "- SDTK-CODE owns implementation planning, code changes, tests, and ship readiness.",
+    "",
+    "## Acceptance Criteria",
+    "",
+    "- Landing renders the product promise, workflow preview, and a single dominant primary CTA.",
+    "- Onboarding captures only required setup data and keeps validation inline.",
+    `- Dashboard shows active ${profile.itemPlural}, next action, status, empty state, and recoverable error state.`,
+    "- Components follow the design system tokens and accessibility baseline.",
+    "- No production app code, network integration, Pro entitlement, `.sdtk/atlas`, or SDTK-WIKI mutation is implied by this handoff.",
+    "",
+    "## Non-Goals",
+    "",
+    "- Figma, Lovable, v0, or full app-builder replacement behavior.",
+    `- ${profile.nonGoals}`,
+    "- Package publish or deployment.",
+    "",
+  ].join("\n");
 }
 
 function highFidelityHandoffAppendix({ paths, statePayload, hasPrototype }) {
@@ -325,27 +325,27 @@ function highFidelityHandoffAppendix({ paths, statePayload, hasPrototype }) {
     "",
   ].join("\n");
 }
-
+
 function runDesignHandoff({ projectPath, force = false }) {
-  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
-  if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
-    throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}. No project files were changed.`);
-  }
-
-  const paths = describeDesignPaths(resolvedProjectPath);
-  const missing = requiredArtifacts(paths).filter((artifact) => !fs.existsSync(artifact.filePath));
-  if (missing.length > 0) {
-    const missingList = missing.map((artifact) => artifact.relativePath).join(", ");
-    throw new ValidationError(`Missing required design artifacts: ${missingList}. Run the previous SDTK-DESIGN commands first. No project files were changed.`);
-  }
-  if (fs.existsSync(paths.designHandoffPath) && !force) {
-    throw new ValidationError("docs/design/DESIGN_HANDOFF.md already exists. Re-run with --force to replace this managed handoff.");
-  }
-
-  const briefContent = fs.readFileSync(paths.designBriefPath, "utf-8");
-  const screenMapContent = fs.readFileSync(paths.screenMapPath, "utf-8");
-  const designSystemContent = fs.readFileSync(paths.designSystemPath, "utf-8");
-  const wireframeContents = REQUIRED_WIREFRAMES.map((fileName) => fs.readFileSync(path.join(paths.wireframesPath, fileName), "utf-8"));
+  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
+  if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
+    throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}. No project files were changed.`);
+  }
+
+  const paths = describeDesignPaths(resolvedProjectPath);
+  const missing = requiredArtifacts(paths).filter((artifact) => !fs.existsSync(artifact.filePath));
+  if (missing.length > 0) {
+    const missingList = missing.map((artifact) => artifact.relativePath).join(", ");
+    throw new ValidationError(`Missing required design artifacts: ${missingList}. Run the previous SDTK-DESIGN commands first. No project files were changed.`);
+  }
+  if (fs.existsSync(paths.designHandoffPath) && !force) {
+    throw new ValidationError("docs/design/DESIGN_HANDOFF.md already exists. Re-run with --force to replace this managed handoff.");
+  }
+
+  const briefContent = fs.readFileSync(paths.designBriefPath, "utf-8");
+  const screenMapContent = fs.readFileSync(paths.screenMapPath, "utf-8");
+  const designSystemContent = fs.readFileSync(paths.designSystemPath, "utf-8");
+  const wireframeContents = REQUIRED_WIREFRAMES.map((fileName) => fs.readFileSync(path.join(paths.wireframesPath, fileName), "utf-8"));
   const profile = inferDomainProfile({ briefContent, screenMapContent, designSystemContent, wireframeContents });
   const statePayload = readInputContractState(paths);
   const highFidelityReady =
@@ -375,28 +375,28 @@ function runDesignHandoff({ projectPath, force = false }) {
     forced: Boolean(force),
   };
 }
-
-function cmdHandoff(args) {
-  const { flags } = parseFlags(args || [], HANDOFF_FLAG_DEFS);
-  if (flags.help) return cmdHandoffHelp();
-
-  const result = runDesignHandoff({
-    projectPath: flags["project-path"],
-    force: Boolean(flags.force),
-  });
-
+
+function cmdHandoff(args) {
+  const { flags } = parseFlags(args || [], HANDOFF_FLAG_DEFS);
+  if (flags.help) return cmdHandoffHelp();
+
+  const result = runDesignHandoff({
+    projectPath: flags["project-path"],
+    force: Boolean(flags.force),
+  });
+
   console.log(`[design] Wrote ${result.relativeDesignHandoffPath}: ${result.projectPath}`);
   console.log(`[design] Verdict: READY_FOR_SDTK_CODE`);
   console.log(`[design] High-fidelity contract: ${result.highFidelityReady ? "enabled" : "not enabled"}`);
   console.log(`[design] Overwrite: ${result.forced ? "enabled by --force" : "not needed"}`);
-  console.log("[design] No .sdtk/atlas, SDTK-WIKI output, source files, network, or app code was modified.");
-  return 0;
-}
-
-module.exports = {
-  cmdHandoff,
-  cmdHandoffHelp,
-  handoffContent,
-  requiredArtifacts,
-  runDesignHandoff,
-};
+  console.log("[design] No .sdtk/atlas, SDTK-WIKI output, source files, network, or app code was modified.");
+  return 0;
+}
+
+module.exports = {
+  cmdHandoff,
+  cmdHandoffHelp,
+  handoffContent,
+  requiredArtifacts,
+  runDesignHandoff,
+};

package/src/commands/help.js

@@ -13,18 +13,21 @@ Usage:
   sdtk-design screens
   sdtk-design wireframe --screen landing
   sdtk-design system --style minimal-saas
-  sdtk-design prototype --style premium-dashboard
+  sdtk-design prototype
   sdtk-design review --artifact docs/design/prototype/index.html
   sdtk-design handoff
   sdtk-design status
+  sdtk-design update --check-only
 
 Examples:
   sdtk-design start --idea "I want to build a lightweight CRM for solo consultants to track leads." --style premium-dashboard
   sdtk-design start --from-spec . --reference-dir ./docs/design/reference-export --profile b2b-commerce
-  sdtk-design prototype --style premium-dashboard
+  sdtk-design prototype
   sdtk-design review --artifact docs/design/prototype/index.html
   sdtk-design handoff
   sdtk-design status
+  sdtk-design update --check-only
+  npm install -g sdtk-design-kit@<version>
 
 Visual style presets:
   minimal-saas, premium-dashboard, bold-founder, warm-editorial
@@ -53,11 +56,12 @@ Command status:
   screens               Available.
   wireframe             Available.
   system                Available.
-  prototype             Available static HTML/CSS preview.
+  prototype             Available SPEC-driven prototype manifest launcher.
   handoff               Available.
   review                Available for local markdown and static HTML artifacts.
   start                 Available beginner facade.
   status                Available.
+  update                Available package-only updater; no project/design files are mutated in R1.
 
 Deferred:
   URL/browser/screenshot/vision review is not implemented in Foundation Beta.

package/src/commands/init.js

@@ -17,6 +17,13 @@ const INIT_FLAG_DEFS = {
   "no-state": { type: "boolean" },
 };
 
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+const DESIGN_PROTOTYPE_SKILL_SOURCE = path.join(PACKAGE_ROOT, "skills", "design-prototype");
+const DESIGN_PROTOTYPE_SKILL_TARGETS = [
+  path.join(".claude", "skills", "design-prototype"),
+  path.join(".agents", "skills", "design-prototype"),
+];
+
 function toPosix(value) {
   return String(value || "").replace(/\\/g, "/");
 }
@@ -113,6 +120,51 @@ function writeManagedFile(filePath, content, projectPath, force, result) {
   result.created.push(toPosix(path.relative(projectPath, filePath)));
 }
 
+function listSkillFiles(sourceDir) {
+  const results = [];
+  const stack = [sourceDir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const absolutePath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(absolutePath);
+        continue;
+      }
+      if (entry.isFile()) {
+        results.push(absolutePath);
+      }
+    }
+  }
+  return results.sort();
+}
+
+function installDesignPrototypeSkill(projectPath, force, result) {
+  if (!fs.existsSync(DESIGN_PROTOTYPE_SKILL_SOURCE) || !fs.statSync(DESIGN_PROTOTYPE_SKILL_SOURCE).isDirectory()) {
+    throw new ValidationError(`Bundled design-prototype skill is missing: ${DESIGN_PROTOTYPE_SKILL_SOURCE}. No project files were changed.`);
+  }
+
+  for (const relativeTargetDir of DESIGN_PROTOTYPE_SKILL_TARGETS) {
+    const targetDir = path.join(projectPath, relativeTargetDir);
+    assertProjectLocalPath(targetDir, projectPath, "skill directory");
+    fs.mkdirSync(targetDir, { recursive: true });
+    result.created.push(toPosix(relativeTargetDir) + "/");
+
+    for (const sourceFile of listSkillFiles(DESIGN_PROTOTYPE_SKILL_SOURCE)) {
+      const relativeFile = path.relative(DESIGN_PROTOTYPE_SKILL_SOURCE, sourceFile);
+      const targetFile = path.join(targetDir, relativeFile);
+      assertProjectLocalPath(targetFile, projectPath, "skill file");
+      if (fs.existsSync(targetFile) && !force) {
+        result.skipped.push(toPosix(path.relative(projectPath, targetFile)));
+        continue;
+      }
+      fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+      fs.copyFileSync(sourceFile, targetFile);
+      result.created.push(toPosix(path.relative(projectPath, targetFile)));
+    }
+  }
+}
+
 function runDesignInit({ projectPath, force = false, state = true }) {
   const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
   if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
@@ -131,6 +183,7 @@ function runDesignInit({ projectPath, force = false, state = true }) {
   ensureDirectory(paths.wireframesPath, resolvedProjectPath, result);
   ensureDirectory(paths.reviewsPath, resolvedProjectPath, result);
   writeManagedFile(paths.designReadmePath, designReadmeContent(), resolvedProjectPath, force, result);
+  installDesignPrototypeSkill(resolvedProjectPath, force, result);
 
   if (state) {
     ensureDirectory(paths.designStatePath, resolvedProjectPath, result);