@bstage-sdk/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,2800 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_TRANSLATION_TIER,
+  LOGIN_PATH,
+  TRANSLATION_CDN_BASE_KEY,
+  TRANSLATION_CDN_BUCKET_PREFIX,
+  TRANSLATION_CDN_ORIGIN,
+  TRANSLATION_LANGUAGES,
+  bstageDevPlugin,
+  createViteConfig,
+  describePhase,
+  resolvePhase,
+  resolveProjectTarget
+} from "./chunk-S6HGR2U3.js";
+
+// src/index.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname3, join as join7 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { Command } from "commander";
+
+// src/commands/build.ts
+import { resolve, join, relative } from "path";
+import { readFile, access, readdir, rename, mkdir, rm } from "fs/promises";
+import { build as viteBuild, loadEnv } from "vite";
+import pc from "picocolors";
+import { getSlotsByTargetV2, isSlotIdV2, slotIdToDirName } from "@bstage-sdk/core";
+
+// src/vite/metaPlugin.ts
+function createMetaPlugin() {
+  let meta2 = null;
+  const plugin = {
+    name: "bstage-meta-extract",
+    enforce: "pre",
+    transform(code, id) {
+      if (meta2) return null;
+      if (!/\.[cm]?[tj]sx?$/.test(id)) return null;
+      if (!code.includes("createTemplate") && !code.includes("createWebComponent")) return null;
+      const extracted = extractMeta(code);
+      if (extracted) meta2 = extracted;
+      return null;
+    }
+  };
+  return { plugin, getMeta: () => meta2 };
+}
+function extractMeta(code) {
+  let framework;
+  if (code.includes("'@bstage-sdk/react'") || code.includes('"@bstage-sdk/react"')) {
+    framework = "react";
+  } else if (code.includes("'@bstage-sdk/vue'") || code.includes('"@bstage-sdk/vue"')) {
+    framework = "vue";
+  } else if (code.includes("'@bstage-sdk/svelte'") || code.includes('"@bstage-sdk/svelte"')) {
+    framework = "svelte";
+  }
+  const attempts = [
+    { fnName: "createTemplate", argIndex: 1 },
+    { fnName: "createWebComponent", argIndex: 2 }
+  ];
+  for (const { fnName, argIndex } of attempts) {
+    const idx = code.indexOf(fnName + "(");
+    if (idx === -1) continue;
+    const objStr = findNthObjectArg(code, idx + fnName.length, argIndex);
+    if (!objStr) continue;
+    const name = extractStringProp(objStr, "name");
+    if (!name) continue;
+    const slot = extractStringProp(objStr, "slot");
+    const type = extractStringProp(objStr, "type");
+    const explicitFramework = extractStringProp(objStr, "framework");
+    return {
+      name,
+      elementName: name,
+      ...slot && { slot },
+      ...type && { type },
+      framework: explicitFramework ?? framework
+    };
+  }
+  return null;
+}
+function findNthObjectArg(code, parenPos, n) {
+  let i = parenPos;
+  while (i < code.length && code[i] !== "(") i++;
+  i++;
+  let argCount = 0;
+  let depth = 0;
+  while (i < code.length && argCount < n) {
+    const ch = code[i];
+    if (ch === "(" || ch === "[" || ch === "{") depth++;
+    else if (ch === ")" || ch === "]" || ch === "}") depth--;
+    else if (ch === "," && depth === 0) argCount++;
+    if (ch === "'" || ch === '"' || ch === "`") {
+      i = skipString(code, i);
+    }
+    i++;
+  }
+  while (i < code.length && /\s/.test(code[i])) i++;
+  if (i >= code.length || code[i] !== "{") return null;
+  let braceDepth = 0;
+  const start = i;
+  while (i < code.length) {
+    const ch = code[i];
+    if (ch === "'" || ch === '"' || ch === "`") {
+      i = skipString(code, i);
+    } else if (ch === "{") {
+      braceDepth++;
+    } else if (ch === "}") {
+      braceDepth--;
+      if (braceDepth === 0) return code.slice(start, i + 1);
+    }
+    i++;
+  }
+  return null;
+}
+function skipString(code, i) {
+  const quote = code[i];
+  i++;
+  while (i < code.length && code[i] !== quote) {
+    if (code[i] === "\\") i++;
+    i++;
+  }
+  return i;
+}
+function extractStringProp(objStr, key) {
+  const regex = new RegExp(`(?:^|[,{\\s])\\s*${key}\\s*:\\s*['"\`]([^'"\`]+)['"\`]`);
+  return objStr.match(regex)?.[1];
+}
+
+// src/vite/registerPlugin.ts
+function createRegisterPlugin() {
+  return {
+    name: "bstage-auto-register",
+    enforce: "post",
+    config() {
+      return {
+        optimizeDeps: {
+          include: ["react-dom/client"]
+        }
+      };
+    },
+    transform(code, id) {
+      if (!id.endsWith("template.tsx") && !id.endsWith("template.ts")) return null;
+      if (!code.includes("createTemplate")) return null;
+      const injection = `
+import { __bstage_registry__ as __reg__, registerTemplate as __registerTemplate__ } from '@bstage-sdk/react';
+__reg__.forEach(__registerTemplate__);
+`;
+      return {
+        code: code + injection,
+        map: null
+      };
+    }
+  };
+}
+
+// src/build/credentialCheck.ts
+var CLIENT_MARKER = "X-BSTAGE-APP-ID";
+var APP_ID_PREFIX = "bsa_";
+var APP_SECRET_PREFIX = "bsp_";
+var CREDENTIAL_ENV_VARS = [
+  "VITE_BSTAGE_APP_ID",
+  "VITE_BSTAGE_APP_SECRET",
+  "VITE_BSTAGE_TENANT_ID"
+];
+function usesBstageClient(bundle) {
+  return bundle.includes(CLIENT_MARKER);
+}
+function isPlaceholderValue(value) {
+  const upper = value.toUpperCase();
+  return ["YOUR", "EXAMPLE", "PLACEHOLDER", "XXX"].some((hint) => upper.includes(hint));
+}
+function collectReferencedVars(sources) {
+  const referenced = /* @__PURE__ */ new Set();
+  for (const source of sources) {
+    for (const varName of CREDENTIAL_ENV_VARS) {
+      if (source.includes(`import.meta.env.${varName}`)) referenced.add(varName);
+    }
+  }
+  return referenced;
+}
+function checkCredentials(env2, referenced) {
+  const issues = [];
+  for (const varName of CREDENTIAL_ENV_VARS) {
+    if (!referenced.has(varName)) continue;
+    const value = env2[varName]?.trim();
+    if (!value) {
+      issues.push({
+        level: "error",
+        varName,
+        message: "\uAC12\uC774 \uC5C6\uC2B5\uB2C8\uB2E4 \u2014 \uBC88\uB4E4\uC5D0 undefined\uAC00 \uBC15\uD600 \uBC30\uD3EC \uD6C4 401\uC774 \uB0A9\uB2C8\uB2E4."
+      });
+      continue;
+    }
+    if (isPlaceholderValue(value)) {
+      issues.push({
+        level: "error",
+        varName,
+        message: "\uC790\uB9AC\uD45C\uC2DC\uC790\uAC00 \uADF8\uB300\uB85C\uC785\uB2C8\uB2E4 \u2014 \uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09\uBC1B\uC740 \uAC12\uC73C\uB85C \uBC14\uAFB8\uC138\uC694."
+      });
+    }
+  }
+  const appId = referenced.has("VITE_BSTAGE_APP_ID") ? env2.VITE_BSTAGE_APP_ID?.trim() : void 0;
+  const appSecret = referenced.has("VITE_BSTAGE_APP_SECRET") ? env2.VITE_BSTAGE_APP_SECRET?.trim() : void 0;
+  const appIdUsable = !!appId && !isPlaceholderValue(appId);
+  const appSecretUsable = !!appSecret && !isPlaceholderValue(appSecret);
+  const swapped = appIdUsable && appId.startsWith(APP_SECRET_PREFIX) || appSecretUsable && appSecret.startsWith(APP_ID_PREFIX);
+  if (swapped) {
+    issues.push({
+      level: "error",
+      varName: "VITE_BSTAGE_APP_ID",
+      message: `APP_ID\uC640 APP_SECRET\uC774 \uC11C\uB85C \uBC14\uB010 \uAC83 \uAC19\uC2B5\uB2C8\uB2E4 \u2014 APP_ID\uB294 "${APP_ID_PREFIX}", APP_SECRET\uC740 "${APP_SECRET_PREFIX}"\uB85C \uC2DC\uC791\uD574\uC57C \uD569\uB2C8\uB2E4.`
+    });
+    return issues;
+  }
+  if (appIdUsable && !appId.startsWith(APP_ID_PREFIX)) {
+    issues.push({
+      level: "warn",
+      varName: "VITE_BSTAGE_APP_ID",
+      message: `"${APP_ID_PREFIX}"\uB85C \uC2DC\uC791\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 \uD30C\uD2B8\uB108 \uCF58\uC194 \uBC1C\uAE09 \uAC12\uC774 \uB9DE\uB294\uC9C0 \uD655\uC778\uD558\uC138\uC694.`
+    });
+  }
+  if (appSecretUsable && !appSecret.startsWith(APP_SECRET_PREFIX)) {
+    issues.push({
+      level: "warn",
+      varName: "VITE_BSTAGE_APP_SECRET",
+      message: `"${APP_SECRET_PREFIX}"\uB85C \uC2DC\uC791\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 \uD30C\uD2B8\uB108 \uCF58\uC194 \uBC1C\uAE09 \uAC12\uC774 \uB9DE\uB294\uC9C0 \uD655\uC778\uD558\uC138\uC694.`
+    });
+  }
+  return issues;
+}
+
+// src/commands/build.ts
+var ELEMENT_NAME_RE = /^[a-z][a-z0-9-]*-[a-z0-9-]*$/;
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var IGNORE_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", ".git"]);
+var PAGES_ROOT = "src/pages";
+var SLOTS_ROOT = "src/slots";
+var LEGACY_ROOT = "src/templates";
+var TEMPLATE_FILE = "template.tsx";
+var DIST_DIR = "dist";
+var STAGING_DIR = ".staging";
+function entryLabel(entry) {
+  if (entry.kind === "page") return entry.segments.length > 0 ? `/${entry.segments.join("/")}` : "/";
+  return [SLOTS_ROOT, ...entry.segments].join("/");
+}
+async function discoverEntries(cwd) {
+  const roots = [
+    ["page", PAGES_ROOT],
+    ["slot", SLOTS_ROOT]
+  ];
+  const results = [];
+  async function walk(kind, dir, segments) {
+    let dirents;
+    try {
+      dirents = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const d of dirents) {
+      if (IGNORE_DIRS.has(d.name) || d.name.startsWith(".")) continue;
+      const fullPath = resolve(dir, d.name);
+      if (d.isDirectory()) {
+        await walk(kind, fullPath, [...segments, d.name]);
+      } else if (d.name === TEMPLATE_FILE) {
+        results.push({ kind, entry: relative(cwd, fullPath), segments });
+      }
+    }
+  }
+  for (const [kind, root] of roots) {
+    await walk(kind, resolve(cwd, root), []);
+  }
+  return results.sort((a, b) => a.entry.localeCompare(b.entry));
+}
+var BuildRuleError = class extends Error {
+};
+var DYNAMIC_SEGMENT_RE = /^\[.*\]$/;
+function resolveOutputName(entry, slot) {
+  const label = entryLabel(entry);
+  if (entry.kind === "page") {
+    if (slot) {
+      throw new BuildRuleError(
+        `${label}: \uD398\uC774\uC9C0(${PAGES_ROOT}/)\uC5D0\uB294 slot \uC635\uC158\uC744 \uC4F8 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.
+  \uBC30\uD3EC \uACBD\uB85C\uB294 ${PAGES_ROOT}/ \uC544\uB798 \uD3F4\uB354 \uAD6C\uC870\uAC00 \uC815\uD569\uB2C8\uB2E4.
+  \uC704\uC82F\uC73C\uB85C \uB9CC\uB4E4 \uC0DD\uAC01\uC774\uC5C8\uB2E4\uBA74 \uC774 \uD3F4\uB354\uB97C ${SLOTS_ROOT}/ \uC544\uB798\uB85C \uC62E\uAE30\uC138\uC694.`
+      );
+    }
+    const dynamic = entry.segments.find((s) => DYNAMIC_SEGMENT_RE.test(s));
+    if (dynamic) {
+      throw new BuildRuleError(
+        `${label}: \uB3D9\uC801 \uACBD\uB85C("${dynamic}")\uB294 \uC544\uC9C1 \uC9C0\uC6D0\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.
+  \uACE0\uC815 \uACBD\uB85C \uD3F4\uB354\uB85C \uBC14\uAFD4\uC8FC\uC138\uC694.`
+      );
+    }
+    return entry.segments.join("/");
+  }
+  if (!slot) {
+    throw new BuildRuleError(
+      `${label}: \uC704\uC82F(${SLOTS_ROOT}/)\uC5D0\uB294 slot \uC635\uC158\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.
+  createTemplate(Component, { name: '...', slot: 'user.contents-home.curation:after' })
+  \uD3F4\uB354 \uC774\uB984\uC740 \uBC30\uCE58\uC5D0 \uC4F0\uC774\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 \uC5B4\uB290 \uC790\uB9AC\uC5D0 \uBD99\uC744\uC9C0\uB294 slot \uC635\uC158\uB9CC \uC815\uD569\uB2C8\uB2E4.`
+    );
+  }
+  if (!isSlotIdV2(slot)) {
+    throw new BuildRuleError(
+      `${label}: \uCE74\uD0C8\uB85C\uADF8\uC5D0 \uC5C6\uB294 \uC2AC\uB86F id "${slot}"\uC785\uB2C8\uB2E4.
+  \uC4F8 \uC218 \uC788\uB294 \uC790\uB9AC:
+${formatSlotSuggestions(slot)}`
+    );
+  }
+  return slotIdToDirName(slot);
+}
+function formatSlotSuggestions(slot) {
+  const all = [...getSlotsByTargetV2("user"), ...getSlotsByTargetV2("admin")].map((s) => s.id);
+  const prefix = slot.split(".").slice(0, 2).join(".");
+  const near = all.filter((id) => id.startsWith(`${prefix}.`));
+  const shown = near.length > 0 ? near : all;
+  const lines = shown.slice(0, 12).map((id) => `    - ${id}`);
+  if (shown.length > lines.length) lines.push(`    ... \uC804\uCCB4 \uBAA9\uB85D\uC740 SLOT_CATALOG_V2 \uCC38\uC870`);
+  return lines.join("\n");
+}
+var SOURCE_EXT_RE = /\.(?:[cm]?[jt]sx?)$/;
+async function readProjectSources(cwd) {
+  const sources = [];
+  async function walk(dir) {
+    let dirents;
+    try {
+      dirents = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const d of dirents) {
+      if (IGNORE_DIRS.has(d.name)) continue;
+      const fullPath = resolve(dir, d.name);
+      if (d.isDirectory()) {
+        await walk(fullPath);
+      } else if (SOURCE_EXT_RE.test(d.name) && !d.name.endsWith(".d.ts")) {
+        try {
+          sources.push(await readFile(fullPath, "utf-8"));
+        } catch {
+        }
+      }
+    }
+  }
+  await walk(cwd);
+  return sources;
+}
+async function buildEntry(ctx, entryInfo) {
+  const { cwd } = ctx;
+  const { entry } = entryInfo;
+  const label = entryLabel(entryInfo);
+  console.log(`
+Building template: ${label}`);
+  const { plugin: metaPlugin, getMeta } = createMetaPlugin();
+  const outDir = join(DIST_DIR, STAGING_DIR);
+  const viteConfig2 = createViteConfig({ entry, outDir });
+  await viteBuild({
+    ...viteConfig2,
+    configFile: false,
+    root: cwd,
+    logLevel: "info",
+    plugins: [...viteConfig2.plugins ?? [], metaPlugin, createRegisterPlugin()]
+  });
+  const bundlePath = join(cwd, outDir, "template.js");
+  let bundleSize = 0;
+  let usesClient = false;
+  try {
+    const bundle = await readFile(bundlePath);
+    bundleSize = bundle.length;
+    usesClient = usesBstageClient(bundle);
+  } catch {
+    console.warn("Warning: Could not read the built bundle.");
+  }
+  const bundleMeta = getMeta();
+  const name = bundleMeta?.name;
+  if (!name) {
+    console.error(`Error: Could not determine template metadata (name) for "${label}".`);
+    console.error("Ensure createTemplate() is called at module level with name.");
+    process.exit(1);
+  }
+  if (!ELEMENT_NAME_RE.test(name)) {
+    console.error(
+      `Error: \uC798\uBABB\uB41C name "${name}". Custom Element \uC2A4\uD399\uC0C1 \uC18C\uBB38\uC790\uB85C \uC2DC\uC791\uD558\uACE0 \uD558\uC774\uD508\uC744 1\uAC1C \uC774\uC0C1 \uD3EC\uD568\uD574\uC57C \uD558\uBA70, \uC18C\uBB38\uC790\xB7\uC22B\uC790\xB7\uD558\uC774\uD508\uB9CC \uC0AC\uC6A9\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4. \uC608: "bmf-hello"`
+    );
+    process.exit(1);
+  }
+  const elementName = bundleMeta?.elementName ?? name;
+  let outputName;
+  try {
+    outputName = resolveOutputName(entryInfo, bundleMeta?.slot);
+  } catch (e) {
+    if (!(e instanceof BuildRuleError)) throw e;
+    console.error(`
+${pc.red("Error")} ${e.message}`);
+    process.exit(1);
+  }
+  const previousOwner = ctx.takenOutputs.get(outputName);
+  if (previousOwner !== void 0) {
+    console.error(
+      `
+${pc.red("Error")} ${label}: \uC0B0\uCD9C\uBB3C \uC704\uCE58 "${join(DIST_DIR, outputName)}"\uAC00 ${previousOwner}\uC640 \uACB9\uCE69\uB2C8\uB2E4.
+  \uB450 \uD15C\uD50C\uB9BF\uC774 \uAC19\uC740 \uC790\uB9AC\uB85C \uB098\uAC08 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.`
+    );
+    process.exit(1);
+  }
+  ctx.takenOutputs.set(outputName, label);
+  const elementNameOwner = ctx.takenElementNames.get(elementName);
+  if (elementNameOwner !== void 0) {
+    console.error(
+      `
+${pc.red("Error")} ${label}: name "${elementName}"\uC744 ${elementNameOwner}\uAC00 \uC774\uBBF8 \uC501\uB2C8\uB2E4.
+  Custom Element \uD0DC\uADF8\uBA85\uC740 \uD15C\uD50C\uB9BF\uB9C8\uB2E4 \uB2EC\uB77C\uC57C \uD569\uB2C8\uB2E4.`
+    );
+    process.exit(1);
+  }
+  ctx.takenElementNames.set(elementName, label);
+  const finalDir = outputName ? join(cwd, DIST_DIR, outputName) : join(cwd, DIST_DIR);
+  await mkdir(finalDir, { recursive: true });
+  await rename(join(cwd, outDir, "template.js"), join(finalDir, "template.js"));
+  console.log(`  ${relative(cwd, finalDir)}/template.js  (${formatSize(bundleSize)})`);
+  return { usesClient };
+}
+function printCredentialReport(env2, referenced) {
+  const issues = checkCredentials(env2, referenced);
+  if (issues.length === 0) return;
+  const hasError = issues.some((i) => i.level === "error");
+  console.log("");
+  console.log(
+    hasError ? pc.red(pc.bold("\u2717 \uC778\uC99D \uAC12 \uC810\uAC80 \u2014 \uC774\uB300\uB85C \uBC30\uD3EC\uD558\uBA74 API \uD638\uCD9C\uC774 \uC2E4\uD328\uD569\uB2C8\uB2E4.")) : pc.yellow(pc.bold("\u26A0 \uC778\uC99D \uAC12 \uC810\uAC80"))
+  );
+  for (const i of issues) {
+    const mark = i.level === "error" ? pc.red("\u2717") : pc.yellow("\u26A0");
+    console.log(`  ${mark} ${i.varName}  ${i.message}`);
+  }
+  console.log(
+    pc.dim(
+      '\n  .env \uAC12\uC740 \uBE4C\uB4DC \uC2DC\uC810\uC5D0 \uBC88\uB4E4\uB85C \uC778\uB77C\uC778\uB429\uB2C8\uB2E4 \u2014 \uAC12\uC744 \uACE0\uCE5C \uB4A4 \uB2E4\uC2DC \uBE4C\uB4DC\uD574\uC57C \uBC18\uC601\uB429\uB2C8\uB2E4.\n  \uBC30\uD3EC\uD560 \uD658\uACBD\uC5D0\uC11C \uBC1C\uAE09\uD55C \uD0A4\uC778\uC9C0\uB3C4 \uD655\uC778\uD558\uC138\uC694(\uD0A4 \uD3EC\uB9F7\uB9CC\uC73C\uB85C\uB294 SDK\uAC00 \uAD6C\uBD84\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4).\n  \uBC30\uD3EC \uC804 \uC810\uAC80 \uBAA9\uB85D: SDK \uBB38\uC11C\uC758 GETTING_STARTED.md \u2014 "9. \uBC30\uD3EC"'
+    )
+  );
+  console.log("");
+}
+async function buildCommand() {
+  const cwd = process.cwd();
+  const entries = await discoverEntries(cwd);
+  if (entries.length === 0) {
+    console.error(
+      `Error: ${PAGES_ROOT}/ \xB7 ${SLOTS_ROOT}/ \uC544\uB798\uC5D0\uC11C ${TEMPLATE_FILE}\uC744 \uCC3E\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4.`
+    );
+    if (await exists(join(cwd, LEGACY_ROOT))) {
+      console.error(
+        `
+  ${LEGACY_ROOT}/ \uC774 \uB0A8\uC544 \uC788\uC2B5\uB2C8\uB2E4. \uBE4C\uB4DC \uC0B0\uCD9C\uBB3C \uACBD\uB85C \uADDC\uCE59\uC774 \uBC14\uB00C\uBA74\uC11C
+  \uD398\uC774\uC9C0\uB294 ${PAGES_ROOT}/, \uC704\uC82F\uC740 ${SLOTS_ROOT}/ \uC544\uB798\uB85C \uC62E\uACA8\uC57C \uD569\uB2C8\uB2E4.
+  \uC9C4\uB2E8: npx @bstage-sdk/cli@latest doctor
+  \uBCC0\uD658: \uC5D0\uC774\uC804\uD2B8\uC5D0\uAC8C "bstage \uB9C8\uC774\uADF8\uB808\uC774\uC158" \uC694\uCCAD (bstage-migrate \uC2A4\uD0AC)`
+      );
+    }
+    process.exit(1);
+  }
+  await rm(join(cwd, DIST_DIR), { recursive: true, force: true });
+  const ctx = {
+    cwd,
+    takenOutputs: /* @__PURE__ */ new Map(),
+    takenElementNames: /* @__PURE__ */ new Map()
+  };
+  console.log(
+    `Found ${entries.length} template${entries.length > 1 ? "s" : ""}: ${entries.map(entryLabel).join(", ")}`
+  );
+  const results = [];
+  for (const entry of entries) {
+    results.push(await buildEntry(ctx, entry));
+  }
+  await rm(join(cwd, DIST_DIR, STAGING_DIR), { recursive: true, force: true });
+  console.log(`
+Build complete.`);
+  if (results.some((r) => r.usesClient)) {
+    const referenced = collectReferencedVars(await readProjectSources(cwd));
+    printCredentialReport(loadEnv("production", cwd, "VITE_"), referenced);
+  }
+}
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  const kb = bytes / 1024;
+  if (kb < 1024) return `${kb.toFixed(1)} KB`;
+  const mb = kb / 1024;
+  return `${mb.toFixed(2)} MB`;
+}
+
+// src/commands/dev.ts
+import { createServer as createViteServer, searchForWorkspaceRoot } from "vite";
+import react from "@vitejs/plugin-react";
+async function devCommand(options) {
+  const port = parseInt(options.port, 10);
+  const root = process.cwd();
+  let resolved;
+  try {
+    resolved = resolvePhase(options.phase, root);
+  } catch (err) {
+    console.error(`[bstage] ${err.message}`);
+    process.exit(1);
+  }
+  const phase = resolved.phase;
+  console.log(describePhase(resolved));
+  const plugins = [react(), bstageDevPlugin({ phase }), createRegisterPlugin()];
+  let vite;
+  try {
+    vite = await createViteServer({
+      root,
+      configFile: false,
+      plugins,
+      server: {
+        port,
+        strictPort: true,
+        // 프로젝트 루트 밖 파일은 내보내지 않는다. 워크스페이스 루트를 함께 허용하는 것은
+        // 모노레포·pnpm 스토어에서 의존 패키지 실제 경로가 루트 위에 있기 때문이다.
+        //
+        // 허용 경로를 넓혀야 한다면(로컬 링크 개발 등) 스캐폴드의 `npm run dev`를 쓴다.
+        // 그쪽은 소비자의 `vite.config.ts`를 타므로 `server.fs.allow`를 직접 넣을 수 있다.
+        fs: { strict: true, allow: [root, searchForWorkspaceRoot(root)] }
+      }
+    });
+  } catch (err) {
+    console.error(`[bstage] ${err.message}`);
+    process.exit(1);
+  }
+  await vite.listen();
+  vite.printUrls();
+  const resolvedPort = vite.config.server.port ?? port;
+  console.log(`  Login:  http://localhost:${resolvedPort}${LOGIN_PATH}
+`);
+}
+
+// src/commands/init.ts
+import * as p from "@clack/prompts";
+import pc2 from "picocolors";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { execSync } from "child_process";
+import { resolve as resolve2, join as join2 } from "path";
+
+// src/templates/agentsMdRegion.ts
+var AGENTS_MANAGED_VERSION = 10;
+var START_MARKER = `<!-- BSTAGE:MANAGED:START v=${AGENTS_MANAGED_VERSION} \u2014 SDK\uAC00 \uAD00\uB9AC\uD558\uB294 \uC601\uC5ED\uC785\uB2C8\uB2E4. \`bstage skills install\` / \`bstage migrate\`\uAC00 \uC7AC\uC0DD\uC131\uD558\uBBC0\uB85C \uC9C1\uC811 \uD3B8\uC9D1\uD558\uC9C0 \uB9C8\uC138\uC694(\uAC31\uC2E0 \uC2DC \uB36E\uC5B4\uC4F0\uC785\uB2C8\uB2E4). \uD504\uB85C\uC81D\uD2B8 \uACE0\uC720 \uADDC\uCE59\uC740 \uC544\uB798 \uC790\uC720 \uC601\uC5ED\uC5D0 \uC801\uC73C\uC138\uC694. -->`;
+var END_MARKER = `<!-- BSTAGE:MANAGED:END -->`;
+var START_RE = /<!--\s*BSTAGE:MANAGED:START(?:\s+v=(\d+))?[\s\S]*?-->/;
+var END_RE = /<!--\s*BSTAGE:MANAGED:END[\s\S]*?-->/;
+var FREE_REGION_NOTE = `<!-- \uC544\uB798\uB294 \uD504\uB85C\uC81D\uD2B8 \uC790\uC720 \uC601\uC5ED\uC785\uB2C8\uB2E4. SDK \uB9C8\uC774\uADF8\uB808\uC774\uC158\uC774 \uBCF4\uC874\uD569\uB2C8\uB2E4. \uC774 \uD504\uB85C\uC81D\uD2B8\uB9CC\uC758 \uADDC\uCE59\xB7\uCEE8\uD14D\uC2A4\uD2B8\uB97C \uC5EC\uAE30\uC5D0 \uC801\uC73C\uC138\uC694. -->`;
+function wrapManaged(body) {
+  return `${START_MARKER}
+${body}
+${END_MARKER}`;
+}
+function freeRegionScaffold() {
+  return `${FREE_REGION_NOTE}
+
+## \uD504\uB85C\uC81D\uD2B8 \uADDC\uCE59
+
+<!-- \uC774 \uD504\uB85C\uC81D\uD2B8\uB9CC\uC758 \uADDC\uCE59\xB7\uCEE8\uD14D\uC2A4\uD2B8\uB97C \uC5EC\uAE30\uC5D0 \uC791\uC131\uD558\uC138\uC694. -->
+`;
+}
+function readManagedVersion(content) {
+  const m = START_RE.exec(content);
+  if (!m) return null;
+  return m[1] ? parseInt(m[1], 10) : 0;
+}
+function agentsMdStatus(content) {
+  const v = readManagedVersion(content);
+  if (v === null) return "legacy";
+  return v < AGENTS_MANAGED_VERSION ? "stale" : "ok";
+}
+function swapManagedBlock(existing, newWrappedBlock) {
+  const s = START_RE.exec(existing);
+  const e = END_RE.exec(existing);
+  if (!s || !e) return null;
+  const startIdx = s.index;
+  const endIdx = e.index + e[0].length;
+  if (endIdx <= startIdx) return null;
+  return existing.slice(0, startIdx) + newWrappedBlock + existing.slice(endIdx);
+}
+function parseAgentsIdentity(content) {
+  const space = /\*\*Space\*\*:\s*([A-Za-z0-9-]+)/.exec(content)?.[1];
+  const projectName = /\*\*레포\*\*:\s*`([^`]+)`/.exec(content)?.[1];
+  return { space, projectName };
+}
+
+// src/templates/designGuide.ts
+function meta(target) {
+  if (target === "admin") {
+    return {
+      pkg: "@bstage-sdk/design/admin",
+      prefix: "admin",
+      colorExample: "color.text.primary",
+      cssVarExample: "text/primary",
+      textStyleExample: "16/title/med",
+      shadowExample: "default-large",
+      themeNote: "\uC5B4\uB4DC\uBBFC\uC740 **\uB77C\uC774\uD2B8 \uC804\uC6A9**(\uB2E4\uD06C\uBAA8\uB4DC \uC5C6\uC74C)."
+    };
+  }
+  return {
+    pkg: "@bstage-sdk/design/user",
+    prefix: "user",
+    colorExample: "color.text.secondary",
+    cssVarExample: "text/secondary",
+    textStyleExample: "16/title/semibold",
+    shadowExample: "default-large",
+    themeNote: "\uC0C9 \uD1A0\uD070\uC740 \uB77C\uC774\uD2B8/\uB2E4\uD06C \uC790\uB3D9 \uB300\uC751 \u2014 \uD50C\uB7AB\uD3FC \uD14C\uB9C8\uB97C \uB530\uB77C \uAC12\uC774 \uBC14\uB010\uB2E4."
+  };
+}
+function designRulesBrief(target) {
+  const m = meta(target);
+  return `## \uB514\uC790\uC778 (bstage \uB514\uC790\uC778 \uD1A0\uD070)
+
+UI\uC758 \uC0C9\xB7\uD0C0\uC774\uD3EC\xB7\uADF8\uB9BC\uC790\uB294 **\uBC18\uB4DC\uC2DC \`${m.pkg}\`\uC758 \uD1A0\uD070\uB9CC** \uC0AC\uC6A9\uD55C\uB2E4. hex/rgb \uD558\uB4DC\uCF54\uB529 \uAE08\uC9C0.
+
+- **\uC0C9**: \`${m.colorExample}\`(\uC911\uCCA9 \uD2B8\uB9AC) \uB610\uB294 \`cssVar('${m.cssVarExample}')\` \u2192 \`var(--${m.prefix}-...)\`. \uCE74\uD14C\uACE0\uB9AC: bg / text / border / icon / surface / overlay / service
+- **\uD0C0\uC774\uD3EC**: \`textStyle('${m.textStyleExample}')\` \u2192 \uC778\uB77C\uC778 \uC2A4\uD0C0\uC77C\uC5D0 spread
+- **\uADF8\uB9BC\uC790**: \`shadow['${m.shadowExample}']\`
+- **\uC778\uD130\uB799\uC158**(hover/press): overlay \uD1A0\uD070 \u2014 \`color.overlay['hover-a']\` / \`color.overlay['press-a']\`
+- **\uAC04\uACA9\xB7\uB77C\uC6B4\uB4DC**: \uC804\uC6A9 \uD1A0\uD070 \uC5C6\uC74C \u2014 \uC77C\uAD00\uB41C \uC2A4\uCF00\uC77C(4\uC758 \uBC30\uC218 \uAD8C\uC7A5)\xB7\uC77C\uAD00\uB41C radius. \uC784\uC758\uAC12 \uB0A8\uBC1C \uAE08\uC9C0
+- **\uD14C\uB9C8**: ${m.themeNote}
+- \uAC12\uC740 \uD50C\uB7AB\uD3FC\uC774 \uB7F0\uD0C0\uC784\uC5D0 \`:root\`\uB85C \uC8FC\uC785\uD558\uACE0 \uB85C\uCEEC\uC740 \`bstage dev\`\uAC00 fallback \uC8FC\uC785 \u2192 \uAC1C\uBC1C \uC911\uC5D0\uB3C4 \uC2E4\uC81C \uD1A4\uC73C\uB85C \uBCF4\uC778\uB2E4. \uC815\uD655\uD55C \uD1A0\uD070 \uD0A4\uB294 \`node_modules/${m.pkg.split("/").slice(0, 2).join("/")}/dist/${m.prefix}/index.d.ts\` \uCC38\uC870
+
+\uC790\uC138\uD55C \uC0AC\uC6A9\uBC95\uC740 SDK \uBB38\uC11C \`DESIGN_TOKENS.md\`(\`bstage docs\`)\uC640 \`bstage-template\` \uC2A4\uD0AC \uCC38\uACE0.`;
+}
+function designGuideSection(target) {
+  const m = meta(target);
+  const pkgRoot = m.pkg.split("/").slice(0, 2).join("/");
+  return `UI \uC2A4\uD0C0\uC77C\uC740 \uC784\uC758 \uAC12 \uB300\uC2E0 **bstage \uB514\uC790\uC778 \uD1A0\uD070**\uB9CC \uC4F4\uB2E4. \uAC12\uC740 \uD50C\uB7AB\uD3FC\uC774 \uB7F0\uD0C0\uC784\uC5D0 \`:root\`\uB85C \uC8FC\uC785\uD558\uACE0, \uB85C\uCEEC \`bstage dev\`\uB294 fallback\uC744 \uC8FC\uC785\uD558\uBBC0\uB85C \uAC1C\uBC1C \uC911\uC5D0\uB3C4 \uC2E4\uC81C \uD1A4\uC73C\uB85C \uBCF4\uC778\uB2E4. **hex/rgb \uD558\uB4DC\uCF54\uB529 \uAE08\uC9C0.**
+
+\`\`\`tsx
+import { color, shadow, cssVar, textStyle } from '${m.pkg}'
+
+<div
+  style={{
+    background: color.bg.base,
+    color: ${m.colorExample},            // = 'var(--${m.prefix}-mode-text-...)'
+    boxShadow: shadow['${m.shadowExample}'],
+    ...textStyle('${m.textStyleExample}'), // fontSize/lineHeight/fontWeight/letterSpacing
+  }}
+/>
+\`\`\`
+
+- **\uC0C9**: \`color.<category>.<name>\` \uC911\uCCA9 \uD2B8\uB9AC, \uB610\uB294 \uD0C0\uC785 \uC548\uC804 \`cssVar('${m.cssVarExample}')\`. \uCE74\uD14C\uACE0\uB9AC: bg / text / border / icon / surface / overlay / service
+- **\uD0C0\uC774\uD3EC**: \`textStyle('{size}/{role}/{weight}')\` \u2192 \uC778\uB77C\uC778 \uC2A4\uD0C0\uC77C \uAC1D\uCCB4(spread). \uC815\uD655\uD55C \uD0A4\uB294 \uD0C0\uC785 \uD655\uC778
+- **\uADF8\uB9BC\uC790**: \`shadow['<name>']\`
+- **\uC778\uD130\uB799\uC158**: hover/press\uB294 overlay \uD1A0\uD070\uC744 \uC704\uC5D0 \uC5B9\uB294\uB2E4 \u2014 \`color.overlay['hover-a']\`, \`color.overlay['press-a']\`
+- **\uAC04\uACA9\xB7\uB77C\uC6B4\uB4DC**: \uC804\uC6A9 \uD1A0\uD070 \uC5C6\uC74C \u2014 \uC77C\uAD00\uB41C \uC2A4\uCF00\uC77C(4\uC758 \uBC30\uC218)\xB7\uC77C\uAD00\uB41C radius\uB97C \uC4F0\uACE0 \uC784\uC758\uAC12\uC744 \uB0A8\uBC1C\uD558\uC9C0 \uC54A\uB294\uB2E4
+- **\uD14C\uB9C8**: ${m.themeNote}
+- **\uC815\uD655\uD55C \uD1A0\uD070 \uBAA9\uB85D(SSOT)**: \`node_modules/${pkgRoot}/dist/${m.prefix}/index.d.ts\`. \uC0AC\uC6A9 \uAC00\uC774\uB4DC\uB294 SDK \uBB38\uC11C \`DESIGN_TOKENS.md\`(\`bstage docs\`). \uAE30\uC5B5\uC5D0 \uC758\uC874\uD574 \uD1A0\uD070\uBA85\uC744 \uCD94\uCE21\uD558\uC9C0 \uC54A\uB294\uB2E4`;
+}
+
+// src/templates/agentsMd.ts
+function agentsManagedBody({
+  space,
+  projectName,
+  target = "user"
+}) {
+  const structureBlock = `src/
+  main.tsx                  \u2014 App \uB9C8\uC6B4\uD2B8\uB9CC (\uC218\uC815 \uBD88\uD544\uC694)
+  App.tsx                   \u2014 import.meta.glob \uAE30\uBC18 \uAC1C\uBC1C\uC6A9 \uBAA9\uB85D\xB7\uB77C\uC6B0\uD305 (\uC218\uC815 \uBD88\uD544\uC694)
+  shared/
+    client.ts               \u2014 BstageClient \uC778\uC2A4\uD134\uC2A4 (API \uD0A4\uB294 .env\uC5D0\uC11C \uC8FC\uC785). \uC720\uC800\uB2E8 API\uB9CC \uC9C0\uC6D0
+  pages/
+    {\uACBD\uB85C}/
+      template.tsx          \u2014 \uD398\uC774\uC9C0 (\uD3F4\uB354 \uAD6C\uC870\uAC00 \uACE7 \uBC30\uD3EC \uACBD\uB85C)
+  slots/
+    {\uC544\uBB34 \uC774\uB984}/
+      template.tsx          \u2014 \uC704\uC82F (createTemplate\uC758 slot \uC635\uC158\uC774 \uC790\uB9AC\uB97C \uC815\uD568)
+.env                        \u2014 VITE_BSTAGE_PHASE + API \uD0A4 (\uCEE4\uBC0B \uC548 \uB428, .gitignore)
+.env.example                \u2014 \uC704 \uD56D\uBAA9 placeholder (\uCEE4\uBC0B\uB428 \u2014 \uBCF5\uC0AC\uD574\uC11C .env \uC0DD\uC131)
+vite.config.ts              \u2014 Vite + bstageDevPlugin (phase\uB294 .env\uC5D0\uC11C \uC77D\uC74C)`;
+  const envSection = `\`.env\`(\uCEE4\uBC0B \uC548 \uB428)\uB294 phase\uC640 API \uD0A4\uB97C, \`.env.example\`(\uCEE4\uBC0B\uB428)\uC740 \uADF8 placeholder\uB97C \uB2F4\uB294\uB2E4. \`client.ts\`\uB294 \`import.meta.env.VITE_BSTAGE_APP_*\`\uB97C, \`vite.config.ts\`\uB294 \`.env\`\uC758 phase\uB97C \uCC38\uC870\uD55C\uB2E4.
+
+\`\`\`
+VITE_BSTAGE_PHASE=dev   # dev | qa | real | sandbox
+\`\`\``;
+  const commandsSection = `- \`npm run dev\` \u2014 \uAC1C\uBC1C \uC11C\uBC84 \uC2E4\uD589 (\uC778\uC99D \uD504\uB85D\uC2DC \uD3EC\uD568)
+- \uB85C\uADF8\uC778 \uD398\uC774\uC9C0: http://localhost:5173/__bstage__/login`;
+  const apiForbidBullet = `- \uACBD\uB85C\xB7\uC751\uB2F5 \uBAA8\uC591\uC744 \uCD94\uCE21\uD574 \uD638\uCD9C\uD558\uC9C0 \uC54A\uB294\uB2E4 \u2014 SDK\uB294 API \uACBD\uB85C \uBAA9\uB85D\uC744 \uB4E4\uACE0 \uC788\uC9C0 \uC54A\uB2E4(\uC790\uB3D9\uC644\uC131 \uC5C6\uC74C). \uCD9C\uCC98\uB294 \uAC8C\uC774\uD2B8\uC6E8\uC774 API Reference Doc\uC774\uACE0, \uC751\uB2F5 \uD0C0\uC785\uC740 \`client.get<T>(...)\`\uCC98\uB7FC \uC81C\uB124\uB9AD\uC73C\uB85C \uBA85\uC2DC\uD55C\uB2E4.
+- \uC5B4\uB4DC\uBBFC\uC6A9 API\uB97C \uCD94\uCE21\uD574 \uD638\uCD9C\uD558\uC9C0 \uC54A\uB294\uB2E4 \u2014 BstageClient\uB294 **\uC720\uC800\uB2E8 API\uB9CC \uC9C0\uC6D0**\uD55C\uB2E4. \uC5B4\uB4DC\uBBFC API\uAC00 \uD544\uC694\uD558\uBA74 \uACBD\uB85C\uB97C \uC784\uC758\uB85C \uB9CC\uB4E4\uC9C0 \uB9D0\uACE0 **\uBC18\uB4DC\uC2DC \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uBA3C\uC800 \uD655\uC778**\uD55C\uB2E4.`;
+  return `# AGENTS.md
+
+## \uD504\uB85C\uC81D\uD2B8 \uAC1C\uC694
+
+b.stage \uC11C\uB4DC\uD30C\uD2F0 \uD15C\uD50C\uB9BF \uD504\uB85C\uC81D\uD2B8. React \uCEF4\uD3EC\uB10C\uD2B8\uB97C \uC791\uC131\uD558\uBA74 SDK\uAC00 Web Component\uB85C \uBE4C\uB4DC\uD558\uACE0, \uBE4C\uB4DC \uC0B0\uCD9C\uBB3C\uC774 b.stage \uD50C\uB7AB\uD3FC\uC5D0\uC11C \uB85C\uB4DC\uB418\uC5B4 \uC2E4\uD589\uB41C\uB2E4.
+
+- **Space**: ${space}
+- **\uB808\uD3EC**: \`${projectName}\`
+
+## SDK \uBB38\uC11C
+
+SDK\uC758 API, hooks, \uC2AC\uB86F \uC2DC\uC2A4\uD15C, \uBE4C\uB4DC \uD30C\uC774\uD504\uB77C\uC778 \uB4F1 **SDK\uC640 \uAD00\uB828\uB41C \uBAA8\uB4E0 \uB0B4\uC6A9**\uC740 \uC124\uCE58\uB41C \uD328\uD0A4\uC9C0\uC758 \uBB38\uC11C\uB97C \uCC38\uC870\uD55C\uB2E4. \uC774 \uBB38\uC11C\uB4E4\uC774 \uD56D\uC0C1 \uCD5C\uC2E0\uC774\uBA70 \uC678\uBD80 \uAC80\uC0C9 \uACB0\uACFC\uBCF4\uB2E4 \uC2E0\uB8B0\uD560 \uC218 \uC788\uB2E4.
+
+\`\`\`
+node_modules/@bstage-sdk/core/docs/
+  \u251C\u2500\u2500 GETTING_STARTED.md   \u2014 \uBE60\uB978 \uC2DC\uC791 \uAC00\uC774\uB4DC
+  \u251C\u2500\u2500 API_REFERENCE.md     \u2014 createTemplate, hooks, BstageClient, PlatformBridge API
+  \u251C\u2500\u2500 I18N.md              \u2014 \uB2E4\uAD6D\uC5B4 \uD6C5 + bstage i18n pull (\uBC88\uC5ED \uCF54\uB4DC\uC820) \uC6CC\uD06C\uD50C\uB85C
+  \u251C\u2500\u2500 DESIGN_TOKENS.md     \u2014 \uB514\uC790\uC778 \uD1A0\uD070 (\uC0C9\xB7\uD0C0\uC774\uD3EC\xB7\uADF8\uB9BC\uC790) \uC0AC\uC6A9 \uAC00\uC774\uB4DC
+  \u251C\u2500\u2500 SLOT_PROTOCOL.md     \u2014 \uC2AC\uB86F \uC2DC\uC2A4\uD15C v1 \uD504\uB85C\uD1A0\uCF5C (3-part \uD0A4\xB7context \uB2E8\uBC29\uD5A5)
+  \u251C\u2500\u2500 SLOT_CATALOG.md      \u2014 \uC2AC\uB86F \uBAA9\uB85D, \uC774\uBCA4\uD2B8 \uC778\uD130\uD398\uC774\uC2A4, resourceId \uC758\uBBF8
+  \u251C\u2500\u2500 SLOT_SYSTEM.md       \u2014 \uC2AC\uB86F \uC2DC\uC2A4\uD15C \uC124\uACC4, \uB7F0\uD0C0\uC784 \uD750\uB984
+  \u251C\u2500\u2500 BUILD_SYSTEM.md      \u2014 \uBE4C\uB4DC \uD30C\uC774\uD504\uB77C\uC778, \uC0B0\uCD9C\uBB3C \uACBD\uB85C \uADDC\uCE59
+  \u251C\u2500\u2500 DEV_SERVER.md        \u2014 \uB85C\uCEEC \uAC1C\uBC1C \uC11C\uBC84, \uC778\uC99D \uD504\uB85D\uC2DC
+  \u251C\u2500\u2500 MIGRATION.md         \u2014 \uBC84\uC804 \uC0AC\uC774 \uB9C8\uC774\uADF8\uB808\uC774\uC158 \uAC00\uC774\uB4DC (bstage doctor \uC5F0\uACC4)
+  \u2514\u2500\u2500 SDK_ARCHITECTURE.md  \u2014 \uD328\uD0A4\uC9C0 \uAD6C\uC870, \uC124\uACC4 \uACB0\uC815
+\`\`\`
+
+\uBB38\uC11C \uBAA9\uB85D\uC740 \`npx bstage docs\`\uB85C\uB3C4 \uBCFC \uC218 \uC788\uB2E4. \uD0C0\uC785 \uC815\uC758(.d.ts)\uC640 \uB7F0\uD0C0\uC784 \uC18C\uC2A4(.js)\uB294 \`node_modules/@bstage-sdk/react/dist/\`, \`node_modules/@bstage-sdk/core/dist/\`\uC5D0\uC11C \uC9C1\uC811 \uD655\uC778\uD560 \uC218 \uC788\uB2E4.
+
+## \uD504\uB85C\uC81D\uD2B8 \uAD6C\uC870
+
+\`\`\`
+${structureBlock}
+\`\`\`
+
+## \uD15C\uD50C\uB9BF \uAC1C\uBC1C \uADDC\uCE59
+
+### \uC0C8 \uD15C\uD50C\uB9BF \uCD94\uAC00
+
+\uD398\uC774\uC9C0\uB0D0 \uC704\uC82F\uC774\uB0D0\uC5D0 \uB530\uB77C \uB450\uB294 \uACF3\uC774 \uB2E4\uB974\uB2E4. \uD30C\uC77C\uBA85\uC740 \uBC18\uB4DC\uC2DC \`template.tsx\`\uC5EC\uC57C \uD558\uBA70, \`src/pages/\`\xB7\`src/slots/\` \uBC16\uC5D0 \uB450\uBA74 \uBE4C\uB4DC\uAC00 \uC778\uC2DD\uD558\uC9C0 \uC54A\uB294\uB2E4.
+
+- **\uD398\uC774\uC9C0** \u2014 \`src/pages/{\uACBD\uB85C}/template.tsx\`. **\uD3F4\uB354 \uAD6C\uC870\uAC00 \uACE7 \uBC30\uD3EC \uACBD\uB85C**\uB2E4(\`src/pages/settings/custom/\` \u2192 \`/settings/custom\`). \uB3D9\uC801 \uACBD\uB85C(\`[id]\`)\uB294 \uC544\uC9C1 \uC9C0\uC6D0\uD558\uC9C0 \uC54A\uB294\uB2E4.
+- **\uC704\uC82F** \u2014 \`src/slots/{\uC544\uBB34 \uC774\uB984}/template.tsx\` + \`createTemplate\`\uC5D0 \`slot\` \uC635\uC158. \uD3F4\uB354 \uC774\uB984\uC740 \uBC30\uCE58\uC5D0 \uC4F0\uC774\uC9C0 \uC54A\uACE0, \uC5B4\uB290 \uC790\uB9AC\uC5D0 \uBD99\uC744\uC9C0\uB294 \`slot\`\uB9CC \uC815\uD55C\uB2E4.
+
+\`name\`\uC740 Custom Element \uD0DC\uADF8\uB85C \uADF8\uB300\uB85C \uC0AC\uC6A9\uB41C\uB2E4. Custom Element \uC2A4\uD399\uC0C1 **\uC18C\uBB38\uC790\uB85C \uC2DC\uC791 + \uD558\uC774\uD508 1\uAC1C \uC774\uC0C1 + \uC18C\uBB38\uC790\xB7\uC22B\uC790\xB7\uD558\uC774\uD508\uB9CC** \uD5C8\uC6A9. \uC704\uBC18 \uC2DC \uB7F0\uD0C0\uC784\xB7\uBE4C\uB4DC\uAC00 \uAC70\uBD80\uD55C\uB2E4.
+
+\`\`\`
+src/pages/welcome/template.tsx              \u2192 /welcome
+src/pages/settings/custom/template.tsx      \u2192 /settings/custom
+src/slots/curation-banner/template.tsx      \u2192 slot \uC635\uC158\uC774 \uC790\uB9AC\uB97C \uC815\uD568
+\`\`\`
+
+### template.tsx \uD544\uC218 \uAD6C\uC870
+
+\`\`\`tsx
+import { createTemplate } from '@bstage-sdk/react'
+
+// \uCEF4\uD3EC\uB10C\uD2B8\uB294 \uBC18\uB4DC\uC2DC export default
+export default function MyWidget() {
+  return <div>...</div>
+}
+
+// createTemplate \uD638\uCD9C \uD544\uC218 \u2014 \uBE4C\uB4DC \uD30C\uC774\uD504\uB77C\uC778\uC774 \uC774 \uD638\uCD9C\uC744 \uD30C\uC2F1\uD558\uC5EC \uBA54\uD0C0\uB370\uC774\uD130 \uCD94\uCD9C
+createTemplate(MyWidget, {
+  name: '${space}-my-widget',   // \uD3F4\uB354\uBA85\uACFC \uB3D9\uC77C\uD574\uC57C \uD568. \uD558\uC774\uD508 \uD544\uC218.
+})
+\`\`\`
+
+- \`name\`\uC740 \uD544\uC218 \u2014 \uD15C\uD50C\uB9BF \uD3F4\uB354\uBA85\uACFC \uC77C\uCE58, \uD558\uC774\uD508 \uD3EC\uD568
+- \uCEF4\uD3EC\uB10C\uD2B8 \uD568\uC218\uBA85\uC740 \uC790\uC720\uC774\uB098 \`export default\` \uD544\uC218
+- \`type\` \uB4F1 \uC120\uD0DD \uD544\uB4DC \uCD94\uAC00 \uAC00\uB2A5
+
+${designRulesBrief(target)}
+
+## \uD658\uACBD \uC124\uC815
+
+${envSection}
+
+## \uBA85\uB839\uC5B4
+
+${commandsSection}
+
+## SDK \uC5C5\uB370\uC774\uD2B8 / \uB9C8\uC774\uADF8\uB808\uC774\uC158
+
+\uC774 \uD504\uB85C\uC81D\uD2B8\uB294 \uC0DD\uC131 \uC2DC\uC810\uC758 SDK \uBC84\uC804\uC744 \`package.json\`\uC5D0 \uACE0\uC815\uD55C\uB2E4. SDK\uAC00 \uC5C5\uB370\uC774\uD2B8\uB3FC\uB3C4 \uC790\uB3D9\uC73C\uB85C \uB530\uB77C\uC624\uC9C0 \uC54A\uC73C\uBBC0\uB85C, \uCD5C\uC2E0\uC73C\uB85C \uC62C\uB9AC\uB824\uBA74:
+
+- \`npx @bstage-sdk/cli@latest doctor\` \u2014 \uBC84\uC804 \uB4DC\uB9AC\uD504\uD2B8\xB7\uB204\uB77D \uD30C\uC77C\xB7\uC801\uC6A9 \uAC00\uB2A5\uD55C \uB9C8\uC774\uADF8\uB808\uC774\uC158 \uD56D\uBAA9\uC744 \uC9C4\uB2E8\uD55C\uB2E4(\uD30C\uC77C \uC218\uC815 \uC5C6\uC74C, \`--json\` \uC9C0\uC6D0).
+- \uC2E4\uC81C \uC801\uC6A9\uC740 \`bstage-migrate\` \uC2A4\uD0AC\uC5D0\uAC8C \uB9E1\uAE34\uB2E4 \u2014 Claude Code\uC5D0\uC11C "bstage \uCD5C\uC2E0 \uBC84\uC804\uC73C\uB85C \uB9C8\uC774\uADF8\uB808\uC774\uC158 \uD574\uC918"\uB77C\uACE0 \uC694\uCCAD\uD558\uBA74, doctor \uACB0\uACFC\uC640 SDK\uC758 \`MIGRATION.md\`\uB97C \uC77D\uACE0 \uC774 \uD504\uB85C\uC81D\uD2B8\uC5D0 \uB9DE\uCDB0 \uBCC0\uD658\uD55C\uB2E4(\uC0AC\uC6A9\uC790 \uCF54\uB4DC\uB294 \uB36E\uC5B4\uC4F0\uC9C0 \uC54A\uACE0 reconcile).
+
+\uB9C8\uC774\uADF8\uB808\uC774\uC158 \uC808\uCC28\uC758 \uB2E8\uC77C \uC18C\uC2A4\uB294 SDK\uC758 \`node_modules/@bstage-sdk/core/docs/MIGRATION.md\`\uB2E4.
+
+\uC774 \uD504\uB85C\uC81D\uD2B8\uC758 \`.claude/skills/\`\uC5D0\uB294 \uC5D0\uC774\uC804\uD2B8\uC6A9 \uC2A4\uD0AC(\`bstage-template\` \uC791\uC131 \uAC00\uC774\uB4DC, \`bstage-migrate\` \uB9C8\uC774\uADF8\uB808\uC774\uC158)\uC774 \uB4E4\uC5B4 \uC788\uB2E4. SDK \uBC84\uC804\uC5C5 \uD6C4 \`npx @bstage-sdk/cli@latest skills install\`\uB85C \uCD5C\uC2E0 \uC2A4\uD0AC\uC744 \uB3D9\uAE30\uD654\uD560 \uC218 \uC788\uC73C\uBA70, \uC774\uB54C **\uC774 AGENTS.md\uC758 SDK \uAD00\uB9AC \uC601\uC5ED(\uB9C8\uCEE4\uB85C \uAC10\uC2FC \uBD80\uBD84)\uB3C4 \uD568\uAED8 \uCD5C\uC2E0\uD654**\uB41C\uB2E4. \uD504\uB85C\uC81D\uD2B8 \uACE0\uC720 \uADDC\uCE59\uC740 \uAD00\uB9AC \uC601\uC5ED \uC544\uB798 **\uC790\uC720 \uC601\uC5ED**\uC5D0 \uC801\uC73C\uBA74 \uAC31\uC2E0 \uC2DC \uBCF4\uC874\uB41C\uB2E4.
+
+## \uBE4C\uB4DC & \uBC30\uD3EC
+
+- \uBC30\uD3EC\uB294 \uAD00\uB9AC\uB3C4\uAD6C\uAC00 \uC774 \uB808\uD3EC\uC758 GitHub Actions \uC6CC\uD06C\uD50C\uB85C\uC6B0\uB97C \uD2B8\uB9AC\uAC70\uD558\uC5EC \uC218\uD589\uD55C\uB2E4.
+- \uB85C\uCEEC\uC5D0\uC11C \uC0B0\uCD9C\uBB3C \uD655\uC778\uC774 \uD544\uC694\uD558\uBA74 \`npx bstage build\`\uB85C \`dist/\` \uB97C \uC0DD\uC131\uD560 \uC218 \uC788\uB2E4.
+
+## \uAE08\uC9C0 \uC0AC\uD56D
+
+- \`src/main.tsx\`\xB7\`src/App.tsx\`\uB97C \uC218\uC815\uD558\uC9C0 \uC54A\uB294\uB2E4 \u2014 \uAC1C\uBC1C\uC6A9 \uC9C4\uC785\uC810\xB7\uBAA9\uB85D \uD654\uBA74\uC73C\uB85C SDK\uAC00 \uAD00\uB9AC
+- \`customElements.define()\`\uC744 \uC9C1\uC811 \uD638\uCD9C\uD558\uC9C0 \uC54A\uB294\uB2E4 \u2014 \`createTemplate()\`\uC774 \uC790\uB3D9 \uCC98\uB9AC
+- Shadow DOM\uC744 \uC9C1\uC811 \uC870\uC791\uD558\uC9C0 \uC54A\uB294\uB2E4 (\`attachShadow\`, \`shadowRoot\` \uB4F1) \u2014 SDK\uAC00 \uAD00\uB9AC
+- \`createTemplate()\` \uD638\uCD9C\uC758 \uC778\uC790 \uAD6C\uC870\uB97C \uC784\uC758\uB85C \uBCC0\uACBD\uD558\uC9C0 \uC54A\uB294\uB2E4 \u2014 \uBE4C\uB4DC \uD30C\uC774\uD504\uB77C\uC778\uC774 \uD30C\uC2F1\uC5D0 \uC2E4\uD328\uD560 \uC218 \uC788\uB2E4
+- \`@bstage-sdk/core\`\uB97C \uC9C1\uC811 import\uD558\uC5EC \`createWebComponent()\`\uB97C \uD638\uCD9C\uD558\uC9C0 \uC54A\uB294\uB2E4 \u2014 \`@bstage-sdk/react\`\uC758 API\uB9CC \uC0AC\uC6A9
+- \uC804\uC5ED CSS \uD30C\uC77C(\`<link>\`, \uC678\uBD80 \uC2A4\uD0C0\uC77C\uC2DC\uD2B8)\uC744 \uC0AC\uC6A9\uD558\uC9C0 \uC54A\uB294\uB2E4 \u2014 Shadow DOM \uB0B4\uBD80\uC5D0 \uC801\uC6A9\uB418\uC9C0 \uC54A\uB294\uB2E4.
+- **\`import './style.css'\`\uB85C \uC2A4\uD0C0\uC77C\uC744 \uB123\uC9C0 \uC54A\uB294\uB2E4 \u2014 \uBC30\uD3EC \uC0B0\uCD9C\uBB3C\uC5D0\uC11C \uC0AC\uB77C\uC9C4\uB2E4.** \uB85C\uCEEC \uAC1C\uBC1C \uD654\uBA74\uC5D0\uC11C\uB294 \uC801\uC6A9\uB418\uC5B4 \uB208\uCE58\uCC44\uAE30 \uC5B4\uB835\uB2E4. CSS \uD30C\uC77C\uC744 \uC4F0\uB824\uBA74 \`import css from './style.css?inline'\`\uC73C\uB85C \uBB38\uC790\uC5F4\uC744 \uAC00\uC838\uC640 \`createTemplate(..., { styles: css })\`\uC5D0 \uB118\uAE30\uAC70\uB098 \uCEF4\uD3EC\uB10C\uD2B8 \uC548 \`<style>{css}</style>\`\uB85C \uB80C\uB354\uD55C\uB2E4. inline \`style={{}}\`\uB3C4 \uB41C\uB2E4
+- UI \uC0C9\xB7\uD0C0\uC774\uD3EC\xB7\uADF8\uB9BC\uC790\uB97C hex/rgb\uB85C \uD558\uB4DC\uCF54\uB529\uD558\uC9C0 \uC54A\uB294\uB2E4 \u2014 \uC704 '\uB514\uC790\uC778' \uC139\uC158\uC758 \uB514\uC790\uC778 \uD1A0\uD070\uC744 \uC0AC\uC6A9
+- \uC571\uD0A4(APP-ID \`bsa_\u2026\`\xB7Secret \`bsp_\u2026\`, \uC5B4\uB4DC\uBBFC \uAC8C\uC774\uD2B8\uC6E8\uC774 \`bsm_\u2026\`)\uB97C \uC18C\uC2A4 \uCF54\uB4DC\uC5D0 \uB9AC\uD130\uB7F4\uB85C \uB123\uC9C0 \uC54A\uB294\uB2E4 \u2014 \uC778\uC99D \uAC12\uC740 \`.env\`(\uCEE4\uBC0B \uC548 \uB428)\uC5D0\uC11C \`import.meta.env.VITE_BSTAGE_*\`\uB85C\uB9CC \uC8FC\uC785\uD55C\uB2E4. pre-commit \uD6C5\uC774 \uCEE4\uBC0B \uC804 \uAC80\uCD9C\xB7\uCC28\uB2E8\uD558\uBA70 \`--no-verify\`\uB85C \uC6B0\uD68C\uD558\uC9C0 \uC54A\uB294\uB2E4
+${apiForbidBullet}
+`;
+}
+function renderManagedBlock(opts) {
+  return wrapManaged(agentsManagedBody(opts));
+}
+function agentsMd(opts) {
+  return `${renderManagedBlock(opts)}
+
+${freeRegionScaffold()}`;
+}
+
+// src/templates/claudeMd.ts
+function claudeMd() {
+  return `# CLAUDE.md
+
+\uC774 \uD504\uB85C\uC81D\uD2B8\uC758 \uADDC\uCE59\uACFC \uCEE8\uD14D\uC2A4\uD2B8\uB294 [AGENTS.md](./AGENTS.md)\uB97C \uCC38\uACE0\uD558\uC138\uC694.
+`;
+}
+
+// src/templates/env.ts
+function env({ phase, appId, appSecret, tenantId }) {
+  return `VITE_BSTAGE_PHASE=${phase}
+
+# \uC778\uC99D \uC815\uBCF4(\uC120\uD0DD) \u2014 BstageClient\uB85C API\uB97C \uD638\uCD9C\uD560 \uB54C\uB9CC \uD544\uC694\uD569\uB2C8\uB2E4.
+# API \uC5C6\uC774 UI\uB9CC \uB80C\uB354\uD558\uB294 \uD15C\uD50C\uB9BF\uC740 \uAC12\uC744 \uCC44\uC6B0\uC9C0 \uC54A\uC544\uB3C4 \uB429\uB2C8\uB2E4.
+# .env\uB294 \uCEE4\uBC0B\uB418\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4(.gitignore). \uAC12\uC740 b.stage \uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09.
+VITE_BSTAGE_APP_ID=${appId}
+VITE_BSTAGE_APP_SECRET=${appSecret}
+VITE_BSTAGE_TENANT_ID=${tenantId}
+
+# CF Access \uC790\uACA9\uC99D\uBA85 \u2014 dev\xB7qa phase\uB85C \uAC1C\uBC1C\uD560 \uB54C\uB9CC \uD544\uC694\uD569\uB2C8\uB2E4.
+# dev\xB7qa\uB294 \uC0AC\uB0B4 \uC804\uC6A9 \uD658\uACBD\uC774\uB77C Cloudflare Access \uAC8C\uC774\uD2B8 \uB4A4\uC5D0 \uC788\uACE0, \uAC12\uC774 \uC5C6\uC73C\uBA74
+# \uB85C\uADF8\uC778\xB7API \uD504\uB85D\uC2DC\uAC00 302\uB85C \uB9C9\uD799\uB2C8\uB2E4. \uC0AC\uB0B4\uC5D0\uC11C \uC4F4\uB2E4\uBA74 CF Access \uC11C\uBE44\uC2A4 \uD1A0\uD070\uC744 \uBC1C\uAE09\uBC1B\uC544 \uCC44\uC6B0\uC138\uC694.
+# sandbox\xB7real\uC740 \uAC8C\uC774\uD2B8\uAC00 \uC5C6\uC5B4 \uC124\uC815\uC774 \uD544\uC694 \uC5C6\uC2B5\uB2C8\uB2E4.
+VITE_CF_ACCESS_CLIENT_ID=
+VITE_CF_ACCESS_CLIENT_SECRET=
+
+# \uC0AC\uB0B4 \uC804\uC6A9 phase\uC758 \uD638\uC2A4\uD2B8 \u2014 dev\xB7qa phase\uB85C \uAC1C\uBC1C\uD560 \uB54C\uB9CC \uD544\uC694\uD569\uB2C8\uB2E4.
+# \uC774 \uD638\uC2A4\uD2B8\uB4E4\uC740 \uC0AC\uB0B4 \uD658\uACBD\uC774\uB77C SDK\uC5D0 \uB4E4\uC5B4 \uC788\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4. \uAC12\uC774 \uC5C6\uC73C\uBA74 dev \uC11C\uBC84\uAC00
+# \uB728\uC9C0 \uC54A\uACE0 \uC5B4\uB5A4 \uAC12\uC774 \uBE44\uC5C8\uB294\uC9C0 \uC54C\uB824\uC90D\uB2C8\uB2E4. \uAC12\uC740 \uC0AC\uB0B4 \uBB38\uC11C\uB97C \uCC38\uACE0\uD558\uC138\uC694.
+# sandbox\xB7real\uC740 \uD638\uC2A4\uD2B8\uAC00 SDK\uC5D0 \uC788\uC5B4 \uC124\uC815\uC774 \uD544\uC694 \uC5C6\uC2B5\uB2C8\uB2E4.
+VITE_BSTAGE_GATEWAY_HOST=
+VITE_BSTAGE_AUTH_HOST=
+`;
+}
+
+// src/templates/packageJson.ts
+function packageJson({
+  projectName,
+  target = "user",
+  sdkVersions
+}) {
+  const dependencies = {
+    "@bstage-sdk/cli": sdkVersions.cli,
+    "@bstage-sdk/core": sdkVersions.core,
+    "@bstage-sdk/design": sdkVersions.design,
+    "@bstage-sdk/react": sdkVersions.react,
+    react: "^19.2.0",
+    "react-dom": "^19.2.0"
+  };
+  const devDependencies = {
+    "@eslint/js": "^9.39.0",
+    // tsconfig.node.json이 `types: ['node']`를 선언하고 vite.config.ts가 `process.cwd()`를 쓴다.
+    // 이게 없으면 `npm run typecheck`(tsc -b)가 TS2688로 깨진다.
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^5.2.0",
+    eslint: "^9.39.0",
+    "eslint-plugin-react-hooks": "^7.0.0",
+    "eslint-plugin-react-refresh": "^0.4.0",
+    globals: "^16.0.0",
+    husky: "^9.1.7",
+    typescript: "~5.9.0",
+    "typescript-eslint": "^8.0.0",
+    vite: "^7.0.0"
+  };
+  return JSON.stringify(
+    {
+      name: projectName,
+      private: true,
+      version: "0.0.0",
+      type: "module",
+      bstage: { target },
+      scripts: {
+        dev: "vite dev",
+        build: "bstage build",
+        // `bstage build`는 tsc를 타지 않는다 — 타입 게이트는 이 스크립트가 유일하다.
+        // solution-style tsconfig(files: [])라 `tsc --noEmit`은 아무것도 검사하지 않으므로 `-b`를 쓴다.
+        typecheck: "tsc -b",
+        lint: "eslint .",
+        // install 시 husky가 .husky/ 훅(pre-commit 시크릿 가드)을 활성화한다.
+        prepare: "husky"
+      },
+      dependencies,
+      devDependencies
+    },
+    null,
+    2
+  );
+}
+
+// src/templates/readme.ts
+function readme({ projectName, packageManager }) {
+  const runCmd = packageManager === "pnpm" ? "pnpm" : "npm run";
+  return `# ${projectName}
+
+b.stage \uC11C\uB4DC\uD30C\uD2F0 \uD15C\uD50C\uB9BF \uD504\uB85C\uC81D\uD2B8
+
+## \uC2DC\uC791\uD558\uAE30
+
+\`\`\`bash
+${runCmd} dev
+\`\`\`
+
+\uAC1C\uBC1C \uC11C\uBC84\uAC00 \uC2E4\uD589\uB418\uBA74 http://localhost:5173 \uC5D0\uC11C \uD15C\uD50C\uB9BF \uBAA9\uB85D\uC744 \uD655\uC778\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4.
+
+## \uD15C\uD50C\uB9BF \uCD94\uAC00
+
+\uD398\uC774\uC9C0\uB0D0 \uC704\uC82F\uC774\uB0D0\uC5D0 \uB530\uB77C \uB450\uB294 \uACF3\uC774 \uB2E4\uB985\uB2C8\uB2E4. \uD30C\uC77C\uBA85\uC740 \uBC18\uB4DC\uC2DC \`template.tsx\`\uC5EC\uC57C \uD569\uB2C8\uB2E4.
+
+- **\uD398\uC774\uC9C0** \u2014 \`src/pages/{\uACBD\uB85C}/template.tsx\`. \uD3F4\uB354 \uAD6C\uC870\uAC00 \uACE7 \uBC30\uD3EC \uACBD\uB85C\uAC00 \uB429\uB2C8\uB2E4.
+- **\uC704\uC82F** \u2014 \`src/slots/{\uC544\uBB34 \uC774\uB984}/template.tsx\`. \uC5B4\uB290 \uC790\uB9AC\uC5D0 \uBD99\uC744\uC9C0\uB294 \`createTemplate\`\uC758 \`slot\` \uC635\uC158\uC774 \uC815\uD569\uB2C8\uB2E4.
+
+\`name\`\uC740 Custom Element \uD0DC\uADF8\uB85C \uADF8\uB300\uB85C \uC0AC\uC6A9\uB418\uBBC0\uB85C **\uC18C\uBB38\uC790\uB85C \uC2DC\uC791\uD558\uACE0 \uD558\uC774\uD508\uC744 1\uAC1C \uC774\uC0C1 \uD3EC\uD568**\uD574\uC57C \uD569\uB2C8\uB2E4. \uC608: \`my-widget\`, \`bmf-hello\`.
+
+\`\`\`
+src/pages/my-page/template.tsx        \u2192 /my-page
+src/slots/my-widget/template.tsx      \u2192 slot \uC635\uC158\uC774 \uC790\uB9AC\uB97C \uC815\uD568
+\`\`\`
+
+\`\`\`tsx
+import { createTemplate } from '@bstage-sdk/react'
+
+export default function MyWidget() {
+  return <div>Hello!</div>
+}
+
+createTemplate(MyWidget, {
+  name: 'my-widget',
+})
+\`\`\`
+
+## \uD658\uACBD \uC124\uC815
+
+\`.env\` \uD30C\uC77C\uC5D0\uC11C API \uD658\uACBD\uC744 \uBCC0\uACBD\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4.
+
+\`\`\`
+VITE_BSTAGE_PHASE=dev   # dev | qa | real | sandbox
+\`\`\`
+
+API \uD0A4(APP-ID/Secret)\uB294 \`.env\`\uC5D0\uC11C \uC124\uC815\uD569\uB2C8\uB2E4. \`.env\`\uB294 \uCEE4\uBC0B\uB418\uC9C0 \uC54A\uC73C\uB2C8, clone \uD6C4 \`.env.example\`\uC744 \`.env\`\uB85C \uBCF5\uC0AC\uD574 \uAC12\uC744 \uCC44\uC6B0\uC138\uC694.
+
+> **\uBCF4\uC548**: \uC571\uD0A4 \uAC12\uC744 \uC18C\uC2A4 \uCF54\uB4DC(\uC608: \`client.ts\`)\uC5D0 \uC9C1\uC811 \uB123\uC9C0 \uB9C8\uC138\uC694 \u2014 \uBC18\uB4DC\uC2DC \`.env\`\uB85C\uB9CC \uC8FC\uC785\uD569\uB2C8\uB2E4. \`bstage init\`\uC774 \uC124\uCE58\uD55C pre-commit \uD6C5\uC774 \uCEE4\uBC0B \uC804 \uD0A4 \uB9AC\uD130\uB7F4\uC744 \uCC28\uB2E8\uD558\uBA70, \`--no-verify\`\uB85C \uC6B0\uD68C\uD558\uC9C0 \uB9C8\uC138\uC694.
+
+## SDK \uC5C5\uB370\uC774\uD2B8
+
+\uC774 \uD504\uB85C\uC81D\uD2B8\uB294 \uC0DD\uC131 \uC2DC\uC810\uC758 SDK \uBC84\uC804\uC5D0 \uACE0\uC815\uB429\uB2C8\uB2E4. \uCD5C\uC2E0\uC73C\uB85C \uC62C\uB9AC\uB824\uBA74 \`npx @bstage-sdk/cli@latest doctor\`\uB85C \uC9C4\uB2E8\uD55C \uB4A4, Claude Code\uC5D0 "bstage \uCD5C\uC2E0 \uBC84\uC804\uC73C\uB85C \uB9C8\uC774\uADF8\uB808\uC774\uC158 \uD574\uC918"\uB77C\uACE0 \uC694\uCCAD\uD558\uBA74 \`bstage-migrate\` \uC2A4\uD0AC\uC774 \uCC98\uB9AC\uD569\uB2C8\uB2E4.
+
+## \uBC30\uD3EC
+
+\uBC30\uD3EC\uB294 \uAD00\uB9AC\uB3C4\uAD6C\uC5D0\uC11C \uC774 \uB808\uD3EC\uC758 GitHub Actions \uC6CC\uD06C\uD50C\uB85C\uC6B0\uB97C \uD2B8\uB9AC\uAC70\uD574 \uC9C4\uD589\uB429\uB2C8\uB2E4. \uAC1C\uBC1C\uC790\uB294 \uCF54\uB4DC \uC791\uC131\xB7push\uC5D0 \uC9D1\uC911\uD558\uBA74 \uB418\uACE0, \uBC30\uD3EC \uD2B8\uB9AC\uAC70\uB294 \uAD00\uB9AC\uB3C4\uAD6C\uC5D0\uC11C \uC218\uD589\uD569\uB2C8\uB2E4.
+`;
+}
+
+// src/templates/tsconfig.ts
+function tsconfig() {
+  return JSON.stringify(
+    {
+      files: [],
+      references: [{ path: "./tsconfig.app.json" }, { path: "./tsconfig.node.json" }]
+    },
+    null,
+    2
+  );
+}
+function tsconfigApp() {
+  return JSON.stringify(
+    {
+      compilerOptions: {
+        tsBuildInfoFile: "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+        target: "ES2022",
+        useDefineForClassFields: true,
+        lib: ["ES2022", "DOM", "DOM.Iterable"],
+        module: "ESNext",
+        types: ["vite/client"],
+        skipLibCheck: true,
+        moduleResolution: "bundler",
+        allowImportingTsExtensions: true,
+        verbatimModuleSyntax: true,
+        moduleDetection: "force",
+        noEmit: true,
+        jsx: "react-jsx",
+        strict: true,
+        noUnusedLocals: true,
+        noUnusedParameters: true,
+        erasableSyntaxOnly: true,
+        noFallthroughCasesInSwitch: true,
+        noUncheckedSideEffectImports: true
+      },
+      include: ["src"]
+    },
+    null,
+    2
+  );
+}
+function tsconfigNode() {
+  return JSON.stringify(
+    {
+      compilerOptions: {
+        tsBuildInfoFile: "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+        target: "ES2023",
+        lib: ["ES2023"],
+        module: "ESNext",
+        types: ["node"],
+        skipLibCheck: true,
+        moduleResolution: "bundler",
+        allowImportingTsExtensions: true,
+        verbatimModuleSyntax: true,
+        moduleDetection: "force",
+        noEmit: true,
+        strict: true,
+        noUnusedLocals: true,
+        noUnusedParameters: true,
+        erasableSyntaxOnly: true,
+        noFallthroughCasesInSwitch: true,
+        noUncheckedSideEffectImports: true
+      },
+      include: ["vite.config.ts"]
+    },
+    null,
+    2
+  );
+}
+
+// src/templates/viteConfig.ts
+function viteConfig() {
+  return `import { defineConfig, loadEnv } from 'vite'
+import react from '@vitejs/plugin-react'
+import { bstageDevPlugin } from '@bstage-sdk/cli/vite'
+
+// https://vite.dev/config/
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), '')
+
+  return {
+    plugins: [react(), bstageDevPlugin({ phase: env.VITE_BSTAGE_PHASE })],
+  }
+})
+`;
+}
+
+// src/templates/indexHtml.ts
+function indexHtml() {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Dev</title>
+  <style>body { margin: 0; }</style>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+</html>
+`;
+}
+
+// src/templates/pnpmWorkspace.ts
+function pnpmWorkspace() {
+  return `# pnpm 9\uB294 \uC774 \uD30C\uC77C\uC774 \uC788\uC73C\uBA74 workspace \uB8E8\uD2B8\uB85C \uBCF4\uACE0, packages\uAC00 \uC5C6\uC73C\uBA74 install\uC774 \uC8FD\uB294\uB2E4.
+# \uB2E8\uC77C \uD504\uB85C\uC81D\uD2B8\uC774\uBBC0\uB85C \uB8E8\uD2B8\uB9CC \uC120\uC5B8\uD55C\uB2E4.
+packages:
+  - '.'
+
+# pnpm\uC740 \uC758\uC874\uC131 build script\uB97C \uAE30\uBCF8 \uCC28\uB2E8\uD558\uACE0, \uCC28\uB2E8 \uC2DC install\uC774 \uC5D0\uB7EC\uB85C \uB05D\uB09C\uB2E4.
+# \uC544\uB798\uC5D0\uC11C \uD5C8\uC6A9\uD560 \uD328\uD0A4\uC9C0\uB97C \uBA85\uC2DC\uD55C\uB2E4. \uC0C8 \uD328\uD0A4\uC9C0\uAC00 \uD544\uC694\uD574\uC9C0\uBA74 \`pnpm approve-builds\`\uAC00
+# \uC774 \uD30C\uC77C\uC5D0 \uD56D\uBAA9\uC744 \uCD94\uAC00\uD574 \uC900\uB2E4(\uAC12\uC744 true\uB85C \uBC14\uAFD4\uC57C \uC801\uC6A9\uB41C\uB2E4).
+allowBuilds:
+  # vite\uAC00 \uC4F0\uB294 \uBC88\uB4E4\uB7EC. postinstall\uC774 \uD50C\uB7AB\uD3FC \uBC14\uC774\uB108\uB9AC\uB97C \uB193\uB294\uB2E4.
+  esbuild: true
+`;
+}
+
+// src/templates/gitignore.ts
+function gitignore() {
+  return `# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# \uD658\uACBD\uBCC0\uC218 (\uC778\uC99D \uC815\uBCF4 \uD3EC\uD568 \u2014 \uCEE4\uBC0B \uAE08\uC9C0). .env.example\uB9CC \uCEE4\uBC0B\uD55C\uB2E4.
+# .env\uB9CC \uBB34\uC2DC\uD55C\uB2E4 \u2014 .env.local\uC740 \uC704 *.local\uC774 \uCC98\uB9AC\uD558\uACE0, .env.development \uB4F1 Vite \uBAA8\uB4DC
+# \uD30C\uC77C\uC740 \uBB34\uC2DC\uD558\uC9C0 \uC54A\uB294\uB2E4.
+.env
+
+# bstage \uB85C\uCEEC \uCE90\uC2DC (\uBC88\uC5ED \uB4F1 \u2014 bstage i18n pull\uB85C \uC7AC\uC0DD\uC131)
+.bstage
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+`;
+}
+
+// src/templates/huskyPreCommit.ts
+function huskyPreCommit() {
+  return `node .husky/check-secrets.mjs
+`;
+}
+
+// src/templates/checkSecretsScript.ts
+function checkSecretsScript() {
+  return `/* eslint-disable */
+// bstage \uC2DC\uD06C\uB9BF \uAC00\uB4DC \u2014 SDK\uAC00 \uAD00\uB9AC\uD558\uB294 \uD30C\uC77C\uC785\uB2C8\uB2E4. \uC9C1\uC811 \uD3B8\uC9D1\uD558\uC9C0 \uB9C8\uC138\uC694(bstage skills install\uC774 \uAC31\uC2E0).
+// \uC2A4\uD14C\uC774\uC9C0\uB41C \uBCC0\uACBD\uC5D0\uC11C \uC571\uD0A4(bsa_/bsm_/bsp_)\xB7GitHub PAT \uB9AC\uD130\uB7F4\uC744 \uAC80\uCD9C\uD574 \uCEE4\uBC0B\uC744 \uCC28\uB2E8\uD55C\uB2E4.
+import { execFileSync } from 'node:child_process'
+import { basename } from 'node:path'
+
+const LF = String.fromCharCode(10)
+const NUL = String.fromCharCode(0)
+const PATTERNS = [
+  { label: '\uC571\uD0A4', re: /bs[amp]_[A-Za-z0-9]{16,}/g },
+  { label: 'GitHub PAT', re: /ghp_[A-Za-z0-9]{36}/g },
+  { label: 'GitHub PAT', re: /github_pat_[A-Za-z0-9_]{82}/g },
+]
+const HINTS = ['YOUR', 'EXAMPLE', 'PLACEHOLDER', 'XXXX']
+
+function isPlaceholder(token, line) {
+  const upper = line.toUpperCase()
+  if (HINTS.some((h) => upper.includes(h))) return true
+  const body = token.slice(token.indexOf('_') + 1)
+  return body.length > 0 && body.split('').every((c) => c === body[0])
+}
+function mask(token) {
+  const us = token.indexOf('_')
+  const prefix = us >= 0 ? token.slice(0, us + 1) : token.slice(0, 4)
+  return prefix + '****'
+}
+function git(args) {
+  return execFileSync('git', args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] })
+}
+
+let out
+try {
+  out = git(['-c', 'core.quotepath=false', 'diff', '--cached', '--name-only', '--diff-filter=ACM'])
+} catch {
+  process.exit(0)
+}
+const files = out
+  .split(LF)
+  .map((s) => s.trim())
+  .filter(Boolean)
+const findings = []
+
+for (const f of files) {
+  const base = basename(f)
+  if (base === '.env' || base.endsWith('.local')) {
+    findings.push({ file: f, line: 0, label: '.env \uD30C\uC77C', masked: base })
+  }
+}
+for (const f of files) {
+  if (basename(f) === '.env.example') continue
+  let content
+  try {
+    content = git(['show', ':' + f])
+  } catch {
+    continue
+  }
+  if (content.includes(NUL)) continue
+  const lines = content.split(LF)
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    for (const p of PATTERNS) {
+      p.re.lastIndex = 0
+      let m
+      while ((m = p.re.exec(line)) !== null) {
+        const token = m[0]
+        if (p.label === '\uC571\uD0A4' && isPlaceholder(token, line)) continue
+        findings.push({ file: f, line: i + 1, label: p.label, masked: mask(token) })
+      }
+    }
+  }
+}
+
+if (findings.length === 0) process.exit(0)
+
+console.error('')
+console.error('\u2717 \uCEE4\uBC0B \uCC28\uB2E8: \uC2A4\uD14C\uC774\uC9C0\uB41C \uBCC0\uACBD\uC5D0 \uD0A4/\uC2DC\uD06C\uB9BF \uB9AC\uD130\uB7F4\uC774 \uC788\uC2B5\uB2C8\uB2E4.')
+for (const x of findings) {
+  if (x.line === 0) {
+    console.error('  ' + x.file + ' \u2014 .env\uB958 \uD30C\uC77C\uC740 \uCEE4\uBC0B\uD558\uC9C0 \uB9C8\uC138\uC694 (git add -f\uB85C \uAC15\uC81C\uB428?)')
+  } else {
+    console.error('  ' + x.file + ':' + x.line + ' \u2014 ' + x.label + ' \uB9AC\uD130\uB7F4 (' + x.masked + ')')
+  }
+}
+console.error('')
+console.error('  \uC778\uC99D \uAC12\uC740 .env(\uCEE4\uBC0B \uC548 \uB428) + import.meta.env\uB85C \uC8FC\uC785\uD558\uC138\uC694. \uB178\uCD9C\uB41C \uD0A4\uB294 \uD3D0\uAE30\xB7\uC7AC\uBC1C\uAE09\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.')
+console.error('')
+process.exit(1)
+`;
+}
+
+// src/templates/eslintConfig.ts
+function eslintConfig() {
+  return `import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  // .husky\uB294 SDK\uAC00 \uC0DD\uC131\xB7\uAC31\uC2E0\uD558\uB294 \uB3C4\uAD6C \uC2A4\uD06C\uB9BD\uD2B8\uB77C \uD504\uB85C\uC81D\uD2B8 \uC18C\uC2A4\uAC00 \uC544\uB2C8\uB2E4.
+  // \uBE7C\uB450\uC9C0 \uC54A\uC73C\uBA74 check-secrets.mjs\uC758 \uD30C\uC77C \uC0C1\uB2E8 eslint-disable\uC774 "\uBD88\uD544\uC694\uD55C directive" \uACBD\uACE0\uB85C \uC7A1\uD78C\uB2E4.
+  globalIgnores(['dist', '.husky']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])
+`;
+}
+
+// src/templates/migrateSkillMd.ts
+function migrateSkillMd() {
+  return `---
+name: bstage-migrate
+description: bstage SDK \uBC84\uC804 \uB9C8\uC774\uADF8\uB808\uC774\uC158\uC744 \uC218\uD589\uD55C\uB2E4. SDK\uAC00 \uC5C5\uB370\uC774\uD2B8\uB418\uC5B4 \uC624\uB798\uB41C \uD504\uB85C\uC81D\uD2B8\uB97C \uCD5C\uC2E0\uC73C\uB85C \uC62C\uB9AC\uAC70\uB098, "bstage \uC5C5\uB370\uC774\uD2B8", "SDK \uB9C8\uC774\uADF8\uB808\uC774\uC158", "\uCD5C\uC2E0 SDK\uB85C \uC62C\uB824\uC918" \uAC19\uC740 \uC694\uCCAD\uC744 \uBC1B\uC744 \uB54C \uC0AC\uC6A9\uD55C\uB2E4.
+---
+
+# \uC5ED\uD560
+
+\uC774 \uD504\uB85C\uC81D\uD2B8\uC758 bstage SDK\uB97C \uCD5C\uC2E0 \uBC84\uC804\uC73C\uB85C \uB9C8\uC774\uADF8\uB808\uC774\uC158\uD55C\uB2E4. \uAC10\uC9C0\uB294 \`bstage doctor\`(\uACB0\uC815\uB860)\uAC00, \uBCC0\uD658 \uC808\uCC28\uB294 SDK\uAC00 \uB3D9\uBD09\uD55C \`MIGRATION.md\`\uAC00 \uC815\uC758\uD55C\uB2E4. \uB108\uB294 \uC774 \uB458\uC744 \uC77D\uACE0 **\uC774 \uD504\uB85C\uC81D\uD2B8\uC5D0 \uB9DE\uCDB0** \uC801\uC6A9\uD55C\uB2E4.
+
+\uD575\uC2EC \uC6D0\uCE59:
+
+1. **\uCD94\uCE21 \uAE08\uC9C0 \u2014 \uD56D\uC0C1 \uC2E4\uC81C \uC18C\uC2A4\uB85C \uAC80\uC99D\uD55C\uB2E4.** \uBAA8\uB4E0 \uD310\uB2E8\uC740 \uAE30\uC5B5\xB7\uAC00\uC815\uC774 \uC544\uB2C8\uB77C **\uC9C1\uC811 \uC77D\uC5B4 \uD655\uC778\uD55C \uC0AC\uC2E4**\uC5D0 \uADFC\uAC70\uD574\uC57C \uD55C\uB2E4. \uBCC0\uACBD \uC804\uC5D0 (a) \uC124\uCE58\uB41C \uD328\uD0A4\uC9C0(\`node_modules/@bstage-sdk/*\`\uC758 \`MIGRATION.md\`\xB7\`dist/*.d.ts\` \uD0C0\uC785 \uC120\uC5B8)\uC640 (b) **\uC774 \uD504\uB85C\uC81D\uD2B8\uC758 \uC2E4\uC81C \uC18C\uC2A4 \uCF54\uB4DC**\uB97C \uC9C1\uC811 \uC77D\uC5B4 \uD655\uC778\uD55C\uB2E4. SDK API\xB7\uB3D9\uC791\uC744 \uAE30\uC5B5\uC73C\uB85C \uB2E8\uC815\uD558\uC9C0 \uC54A\uB294\uB2E4.
+2. **\uC0AC\uC6A9\uC790\uAC00 \uC791\uC131/\uC218\uC815\uD55C \uCF54\uB4DC\uB97C \uD568\uBD80\uB85C \uB36E\uC5B4\uC4F0\uC9C0 \uC54A\uB294\uB2E4.** \uCD94\uAC00\uB294 \uC548\uC804\uD558\uAC8C, \uCDA9\uB3CC\xB7\uC7AC\uAD6C\uC131\uC740 \uD655\uC778\uD55C\uB2E4.
+
+\uD655\uC778\uC774 \uC548 \uB418\uBA74 **\uCD94\uCE21\uD574\uC11C \uC801\uC6A9\uD558\uC9C0 \uB9D0\uACE0 \uBA48\uCD98\uB2E4.** \uB2E8, \uC0AC\uC6A9\uC790\uC5D0\uAC8C "\uCF54\uB4DC\uB97C \uD655\uC778\uD574 \uB2EC\uB77C"\uACE0 \uB5A0\uB118\uAE30\uC9C0 \uC54A\uB294\uB2E4 \u2014 \uC0AC\uC6A9\uC790\uB294 \uAC1C\uBC1C\uC790\uAC00 \uC544\uB2D0 \uC218 \uC788\uC5B4 \uC9C1\uC811 \uAC80\uC99D\uC774 \uC5B4\uB835\uB2E4. **\uAC80\uC99D\uC740 \uB108(\uC5D0\uC774\uC804\uD2B8)\uC758 \uCC45\uC784**\uC774\uB2E4(\uD30C\uC77C\xB7\uC124\uCE58\uB41C \uD328\uD0A4\uC9C0\uB97C \uC77D\uC5B4 \uC2A4\uC2A4\uB85C \uD655\uC778). \uC0AC\uC6A9\uC790\uC5D0\uAC90 \uCF54\uB4DC\uB85C \uD655\uC778 \uAC00\uB2A5\uD55C *\uC0AC\uC2E4*\uC774 \uC544\uB2C8\uB77C **\uC81C\uD488\xB7\uC120\uD638 *\uACB0\uC815*** \uB9CC, \uAD6C\uCCB4\uC801 \uC120\uD0DD\uC9C0\uB85C \uBB3B\uB294\uB2E4.
+
+# \uAD8C\uC704 \uC788\uB294 \uCD9C\uCC98 (\uBA3C\uC800 \uC77D\uAE30)
+
+- \`MIGRATION.md\` \u2014 \uBC84\uC804\uBCC4 \uB9C8\uC774\uADF8\uB808\uC774\uC158 \uD56D\uBAA9\xB7\uC808\uCC28(\uB2E8\uC77C \uC18C\uC2A4). \uBC84\uC804 \uBC94\uD504+\uC124\uCE58 \uD6C4 \`node_modules/@bstage-sdk/cli/dist/MIGRATION.md\`(\uB610\uB294 core docs)\uC5D0\uC11C \uC77D\uB294\uB2E4.
+- \`bstage doctor\` \u2014 \uD604\uC7AC \uB4DC\uB9AC\uD504\uD2B8 \uC9C4\uB2E8(\uACB0\uC815\uB860). \`npx @bstage-sdk/cli@latest doctor\`.
+- \uBB38\uC11C \uBAA9\uB85D: \`npx bstage docs\`
+
+# \uC808\uCC28
+
+## 1. \uC9C4\uB2E8 (doctor)
+
+\`\`\`bash
+npx @bstage-sdk/cli@latest doctor --json
+\`\`\`
+
+\uCD9C\uB825\uC5D0\uC11C \uC138 \uAC00\uC9C0\uB97C \uC5BB\uB294\uB2E4.
+
+- \`versions\` \u2014 \uB4A4\uCC98\uC9C4 \uD328\uD0A4\uC9C0\uC640 latest \uBC84\uC804
+- \`files\` \u2014 \uB204\uB77D\uB41C \uBCF4\uC77C\uB7EC\uD50C\uB808\uC774\uD2B8 \uD30C\uC77C
+- \`recommendedDeps\` \u2014 \uAD8C\uC7A5 \uC758\uC874\uC131\uC758 \uC120\uC5B8 \uC0C1\uD0DC(\`declared: false\`\uBA74 \uBBF8\uC120\uC5B8). **\uBC84\uC804 \uB300\uC870\uB85C\uB294 \uC548 \uC7A1\uD788\uB294 \uCD95**\uC774\uBBC0\uB85C \`migrations\`\uAC00 \uBE44\uC5B4 \uC788\uC5B4\uB3C4 \uB530\uB85C \uD655\uC778\uD55C\uB2E4
+- \`migrations\` \u2014 \uC801\uC6A9 \uAC00\uB2A5\uD55C \uB9C8\uC774\uADF8\uB808\uC774\uC158 \uD56D\uBAA9. \uAC01 \uD56D\uBAA9\uC740 \`label\`(\uD5E4\uB354 \uD45C\uAE30, \uC608: \`cli 0.43.0\` \uB610\uB294 \`core 0.32.0 \xB7 react 0.32.0\`) \xB7 \`requirements\`(\uC62C\uB824\uC57C \uD560 \uD328\uD0A4\uC9C0\xB7\uCD5C\uC18C \uBC84\uC804 \uC30D) \xB7 \`items\`(\uD56D\uBAA9 \uC81C\uBAA9)\uB97C \uAC00\uC9C4\uB2E4. \uD5E4\uB354\uC758 \uD328\uD0A4\uC9C0\uB97C \uADF8 \uBC84\uC804 \uC774\uC0C1\uC73C\uB85C \uC62C\uB9B0\uB2E4
+
+\`isBstageProject\`\uAC00 false\uBA74 bstage \uD504\uB85C\uC81D\uD2B8\uAC00 \uC544\uB2C8\uBBC0\uB85C \uC911\uB2E8\uD55C\uB2E4. \uB808\uC9C0\uC2A4\uD2B8\uB9AC \uC870\uD68C\uC5D0 \uC2E4\uD328\uD574 \`latestChecked\`\uAC00 false\uBA74 \uBC84\uC804 \uBE44\uAD50\uB97C \uBCF4\uB958\uD55C\uB2E4(\uBCF4\uC77C\uB7EC\uD50C\uB808\uC774\uD2B8\xB7\uD56D\uBAA9\uC740 \uACC4\uC18D \uC9C4\uD589 \uAC00\uB2A5).
+
+## 2. \uACC4\uD68D \uC81C\uC2DC (\uC2B9\uC778 \uC804 \uBA48\uCDA4)
+
+doctor \uACB0\uACFC\uB97C \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uC694\uC57D\uD558\uACE0, **\uBB34\uC5C7\uC744 \uD560\uC9C0** \uACC4\uD68D\uC744 \uC81C\uC2DC\uD55C \uB4A4 \uC2B9\uC778\uC744 \uBC1B\uB294\uB2E4. \uC774\uB54C \uC0AC\uC6A9\uC790\uAC00 \uB9AC\uBDF0\uD558\uB294 \uAC83\uC740 MIGRATION.md \uC6D0\uBB38\uC774 \uC544\uB2C8\uB77C **\uC774 \uD504\uB85C\uC81D\uD2B8\uC5D0 \uB9DE\uCD98 \uC791\uC5C5 \uACC4\uD68D**\uC774\uB2E4.
+
+- \uBC84\uC804 \uBC94\uD504 \uBAA9\uB85D(\uD604\uC7AC \u2192 \uBAA9\uD45C)
+- \uCD94\uAC00\uD560 \uBCF4\uC77C\uB7EC\uD50C\uB808\uC774\uD2B8 \uD30C\uC77C
+- \uC801\uC6A9\uD560 \uB9C8\uC774\uADF8\uB808\uC774\uC158 \uD56D\uBAA9, \uAC01 \uD56D\uBAA9\uC758 \`\uC790\uB3D9\`/\`\uD310\uB2E8\` \uAD6C\uBD84
+- \uD310\uB2E8\uC774 \uD544\uC694\uD55C \uC9C0\uC810(\uC608: \uCEE4\uC2A4\uD140 \uCF54\uB4DC \uAD50\uCCB4)\uC740 \uBBF8\uB9AC \uC9DA\uC5B4 \uB454\uB2E4
+
+## 3. \uC801\uC6A9
+
+### 3a. \uBC84\uC804 \uBC94\uD504 + \uC124\uCE58 (\uC790\uB3D9)
+
+\`package.json\`\uC774 \uC758\uC874\uD558\uB294 \`@bstage-sdk/*\` \uD328\uD0A4\uC9C0\uB97C \uBAA8\uB450 latest\uB85C \uC62C\uB9B0\uB2E4 \u2014 \uBCF4\uD1B5 \`cli\`/\`core\`/\`react\`/\`design\`\uC774\uB2E4. \uBC84\uC804 \uD45C\uAE30 \uC2A4\uD0C0\uC77C(\uCE90\uB7FF vs \uC815\uD655\uD55C \uBC84\uC804)\uC740 \uD504\uB85C\uC81D\uD2B8 \uAE30\uC874 \uCEE8\uBCA4\uC158\uC744 \uB530\uB978\uB2E4. \`react\`/\`vite\` \uB4F1 \uC0AC\uC6A9\uC790\uAC00 \uAD00\uB9AC\uD558\uB294 \uC758\uC874\uC131\uC740 **\uC784\uC758\uB85C \uC62C\uB9AC\uAC70\uB098 \uB0B4\uB9AC\uC9C0 \uC54A\uB294\uB2E4**(\uC608: \uD504\uB85C\uC81D\uD2B8\uAC00 \uC774\uBBF8 \uB354 \uB192\uC740 vite\uB97C \uC4F0\uBA74 init \uAE30\uBCF8\uAC12\uC73C\uB85C \uB2E4\uC6B4\uADF8\uB808\uC774\uB4DC \uAE08\uC9C0). \uADF8 \uD6C4 \uC124\uCE58\uD55C\uB2E4(\uD504\uB85C\uC81D\uD2B8\uC758 \uD328\uD0A4\uC9C0 \uB9E4\uB2C8\uC800).
+
+> **install\uC774 bstage\uC640 \uBB34\uAD00\uD55C peer \uCDA9\uB3CC\uB85C \uC2E4\uD328**\uD558\uBA74(\uC608: \uB2E4\uB978 SDK\uAC00 \uC61B react\uB97C \uC694\uAD6C) \uD504\uB85C\uC81D\uD2B8 \uACE0\uC720 \uC81C\uC57D\uC774\uB2E4. \uAC15\uC81C \uBCC0\uACBD\uD558\uC9C0 \uB9D0\uACE0 \`--legacy-peer-deps\`(npm) \uB4F1 \uADF8 \uD504\uB85C\uC81D\uD2B8\uC758 \uAE30\uC874 \uC124\uCE58 \uBC29\uC2DD\uC73C\uB85C \uC7AC\uC2DC\uB3C4\uD558\uAC70\uB098, \uD310\uB2E8\uC774 \uD544\uC694\uD558\uBA74 \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uBCF4\uACE0\uD55C\uB2E4.
+
+> \uC774 \uB2E8\uACC4 \uC9C1\uD6C4 \`node_modules/@bstage-sdk/cli/dist/MIGRATION.md\`\uAC00 \uC0DD\uAE34\uB2E4. \uC774\uD6C4 \uB2E8\uACC4\uB294 \uC774 \uD30C\uC77C\uC758 \uD574\uB2F9 \uBC84\uC804 \uC139\uC158\uC744 \uC815\uB3C5\uD558\uACE0 \uB530\uB978\uB2E4.
+
+doctor\uC758 \`recommendedDeps\`\uC5D0 \`declared: false\`\uAC00 \uC788\uC73C\uBA74 **\uC0AC\uC6A9\uC790\uC5D0\uAC8C \uBB3B\uACE0** \uD568\uAED8 \uCD94\uAC00\uD55C\uB2E4. \uC774\uAC74 \uBC84\uC804 \uBC94\uD504\uB85C \uC800\uC808\uB85C \uB4E4\uC5B4\uC624\uC9C0 \uC54A\uB294\uB2E4 \u2014 \uC608: \`@bstage-sdk/design\`(\uB514\uC790\uC778 \uD1A0\uD070)\uC774 \uC5C6\uC73C\uBA74 AGENTS.md\xB7\`bstage-template\` \uC2A4\uD0AC\uC740 \uD1A0\uD070\uC744 \uC4F0\uB77C\uACE0 \uC548\uB0B4\uD558\uB294\uB370 \uC815\uC791 import\uAC00 \uC2E4\uD328\uD55C\uB2E4. \uC774\uBBF8 \uCD5C\uC2E0 \uBC84\uC804\uC778 \uD504\uB85C\uC81D\uD2B8\uC5D0\uC11C\uB294 \`migrations\`\uAC00 \uBE44\uC5B4 \uC774 \uCD95\uB9CC \uB0A8\uC73C\uBBC0\uB85C, \uB9C8\uC774\uADF8\uB808\uC774\uC158\uD560 \uAC8C \uC5C6\uB2E4\uACE0 \uD310\uB2E8\uD558\uACE0 \uB118\uC5B4\uAC00\uC9C0 \uC54A\uB294\uB2E4.
+
+### 3b. init \uAE30\uBCF8 \uD30C\uC77C \uCC28\uC774 (\uD310\uB2E8 \u2014 \uAC15\uC694 \uAE08\uC9C0)
+
+doctor\uC758 "init \uAE30\uBCF8 \uD30C\uC77C" \uD56D\uBAA9\uC740 **\uB204\uB77D\uC774 \uC544\uB2C8\uB77C init \uAE30\uBCF8 \uAD6C\uC131\uACFC\uC758 \uCC28\uC774**\uB2E4. \uCD94\uAC00\uD558\uAE30 \uC804\uC5D0 **\uD504\uB85C\uC81D\uD2B8\uAC00 \uAC19\uC740 \uBAA9\uC801\uC744 \uB2E4\uB974\uAC8C \uB2EC\uC131\uD588\uB294\uC9C0** \uBA3C\uC800 \uD655\uC778\uD558\uACE0, \uD544\uC694\uD560 \uB54C\uB9CC \uCD94\uAC00\uD55C\uB2E4.
+
+- \`src/vite-env.d.ts\` \u2014 \`tsconfig\`\uC758 \`types:["vite/client"]\`\uB85C \uC774\uBBF8 \uCC98\uB9AC \uC911\uC774\uBA74 \uBD88\uD544\uC694.
+- \`eslint.config.js\` \u2014 eslint\uB97C \uC4F0\uC9C0 \uC54A\uB294 \uD504\uB85C\uC81D\uD2B8(\uC608: prettier/\uD0C0 \uB9B0\uD130\uB9CC)\uC5D4 \uCD94\uAC00\uD558\uC9C0 \uC54A\uB294\uB2E4.
+- \`tsconfig.app.json\` / \`tsconfig.node.json\` \u2014 \uB2E8\uC77C \`tsconfig.json\`\uC774 \uC798 \uB3D9\uC791\uD558\uBA74 \uAD73\uC774 \uCABC\uAC1C\uC9C0 \uC54A\uB294\uB2E4. \uBD84\uB9AC\uD560 \uACBD\uC6B0 \uC0AC\uC6A9\uC790 \uC124\uC815(\uACBD\uB85C \uBCC4\uCE6D \uB4F1)\uC744 \uBCF4\uC874\uD55C\uB2E4.
+
+\uD310\uB2E8\uC774 \uC11C\uC9C0 \uC54A\uC73C\uBA74 \uCD94\uAC00\uD558\uC9C0 \uB9D0\uACE0 \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uD655\uC778\uD55C\uB2E4.
+
+### 3c. \uB9C8\uC774\uADF8\uB808\uC774\uC158 \uD56D\uBAA9 (\uD56D\uBAA9\uBCC4\uB85C \uC790\uB3D9/\uD310\uB2E8 \uBD84\uB9AC)
+
+\`MIGRATION.md\`\uC5D0\uC11C \uC801\uC6A9 \uB300\uC0C1 \uBC84\uC804 \uC139\uC158\uC744 \uC77D\uACE0, \uAC01 \uD56D\uBAA9\uC758 **\uC801\uC6A9** \uC808\uCC28\uB97C \uB530\uB978\uB2E4.
+
+- \`\uC790\uB3D9\` \uB2E8\uACC4\uB294 \uADF8\uB300\uB85C \uC218\uD589\uD55C\uB2E4.
+- \`\uD310\uB2E8\` \uB2E8\uACC4\uB294 **\uC2E4\uC81C \uD504\uB85C\uC81D\uD2B8 \uCF54\uB4DC\uB97C \uC77D\uACE0** \uC801\uC6A9\uD55C\uB2E4. \uC608: \uCEE4\uC2A4\uD140 i18n \uD5EC\uD37C\uAC00 \uC788\uC73C\uBA74 \uC6A9\uB3C4(\uC790\uCCB4 \uBB38\uAD6C vs \uD50C\uB7AB\uD3FC \uBB38\uAD6C)\uB97C \uBD84\uB958\uD574 \`useMessages\`/\`useBstageTranslations\`\uB85C \uC774\uC804\uD55C\uB2E4. \uC560\uB9E4\uD558\uBA74 \uC77C\uAD04 \uCE58\uD658\uD558\uC9C0 \uB9D0\uACE0 \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uBB3B\uB294\uB2E4.
+- \`\uC120\uD0DD\` \uD56D\uBAA9\uC740 \uC774 \uD504\uB85C\uC81D\uD2B8\uC5D0 \uD544\uC694\uD55C\uC9C0 \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uD655\uC778\uD55C \uB4A4 \uC9C4\uD589\uD55C\uB2E4.
+
+### 3c-1. \uD15C\uD50C\uB9BF \uB514\uB809\uD1A0\uB9AC \uAD6C\uC870 (\uD310\uB2E8 \u2014 \uC0AC\uC6A9\uC790\uB9CC \uB2F5\uD560 \uC218 \uC788\uB294 \uAC83)
+
+doctor\uC758 \`layout.legacyPresent\`\uAC00 \`true\`\uBA74 \`src/templates/\`\uAC00 \uB0A8\uC544 \uC788\uB294 \uC61B \uAD6C\uC870\uB2E4. \uD398\uC774\uC9C0\uB294 \`src/pages/{\uACBD\uB85C}/\`, \uC704\uC82F\uC740 \`src/slots/{\uC544\uBB34 \uC774\uB984}/\`\uC73C\uB85C \uC62E\uACA8\uC57C \uD558\uACE0, \uC548 \uC62E\uAE30\uBA74 \`bstage build\`\uAC00 \uC5D4\uD2B8\uB9AC\uB97C \uCC3E\uC9C0 \uBABB\uD574 \uBA48\uCD98\uB2E4.
+
+**\uC5EC\uAE30\uC11C\uB9CC\uC740 \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uBB3C\uC5B4\uC57C \uD55C\uB2E4.** \uC774 \uC2A4\uD0AC\uC758 \uC6D0\uCE59\uC740 "\uC0AC\uC2E4\uC740 \uC5D0\uC774\uC804\uD2B8\uAC00 \uAC80\uC99D\uD558\uACE0, \uC0AC\uC6A9\uC790\uC5D0\uAC90 \uACB0\uC815\uB9CC \uBB3B\uB294\uB2E4"\uC774\uC9C0\uB9CC, \uC774 \uD56D\uBAA9\uC740 **\uC0AC\uC2E4 \uC790\uCCB4\uAC00 \uD504\uB85C\uC81D\uD2B8 \uC18C\uC2A4\uC5D0 \uC5C6\uB2E4**:
+
+- \uD3F4\uB354 \uC774\uB984\uC740 \uC9C0\uAE08\uAE4C\uC9C0 \uC544\uBB34 \uC758\uBBF8\uAC00 \uC5C6\uC5C8\uB2E4 \u2014 \uBE4C\uB4DC\uAC00 \uC784\uC2DC \uB77C\uBCA8\uB85C\uB9CC \uC4F0\uACE0 \uBC84\uB838\uB2E4. \uADF8\uB798\uC11C \`src/templates/home/\`\uC774 \uC2E4\uC81C\uB85C\uB294 \`/landing\`\uC5D0 \uBC30\uD3EC\uB3FC \uC788\uC744 \uC218 \uC788\uB2E4.
+- \uC2AC\uB86F \uBC30\uCE58\uB294 \uCF54\uB4DC\uC5D0 \uC120\uC5B8\uD558\uC9C0 \uC54A\uC558\uB2E4(\uC124\uACC4\uC0C1 \uAD00\uB9AC\uB3C4\uAD6C \uBAAB\uC774\uC5C8\uB2E4). \uADF8\uB798\uC11C \uD398\uC774\uC9C0\uC778\uC9C0 \uC704\uC82F\uC778\uC9C0\uB3C4 \uC18C\uC2A4\uB85C\uB294 \uAC08\uB9AC\uC9C0 \uC54A\uB294\uB2E4.
+- \uC5B4\uB4DC\uBBFC \uC804\uC6A9 \`type: 'fullPage' | 'sharedNav'\`\uB294 \uB808\uC774\uC544\uC6C3 \uAD6C\uBD84\uC774\uB77C \uC774 \uD310\uB2E8\uC5D0 \uC4F8 \uC218 \uC5C6\uB2E4.
+
+\uC2E4\uC81C \uB9E4\uD551\uC740 \uAD00\uB9AC\uB3C4\uAD6C(bstage portal)\uC5D0\uB9CC \uC788\uB2E4. \`layout.legacyTemplates\`\uC758 \uD3F4\uB354\uB97C \uD558\uB098\uC529 \uC9DA\uC5B4 \uBB3B\uB294\uB2E4.
+
+- \uBA3C\uC800 **\uC18C\uC2A4\uB97C \uC77D\uACE0 \uCD94\uC815\uC548\uC744 \uB9CC\uB4E4\uC5B4 \uC81C\uC2DC\uD55C\uB2E4.** \uC804\uCCB4 \uD654\uBA74\uC744 \uADF8\uB9AC\uB294\uC9C0 \uC791\uC740 \uC870\uAC01\uC778\uC9C0, \uCEF4\uD3EC\uB10C\uD2B8 \uC774\uB984\uC774 \uBB34\uC5C7\uC778\uC9C0\uB294 \uB124\uAC00 \uC77D\uC5B4\uC11C \uC54C \uC218 \uC788\uB2E4. \uC0AC\uC6A9\uC790\uAC00 \uBC31\uC9C0\uC5D0\uC11C \uB2F5\uD558\uAC8C \uB450\uC9C0 \uC54A\uB294\uB2E4.
+- \uC704\uC82F\uC774\uB77C\uACE0 \uB2F5\uD558\uBA74 **\uC790\uB9AC \uBAA9\uB85D\uC744 \uC120\uD0DD\uC9C0\uB85C \uC81C\uC2DC\uD55C\uB2E4.** \uCE74\uD0C8\uB85C\uADF8\uB294 SDK\uAC00 \uB4E4\uACE0 \uC788\uC73C\uBBC0\uB85C \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uCC3E\uC544\uC624\uB77C\uACE0 \uD558\uC9C0 \uC54A\uB294\uB2E4 \u2014 \`node_modules/@bstage-sdk/core\`\uC758 \`SLOT_CATALOG_V2\`(\uB610\uB294 \`SLOT_CATALOG_V2.md\`)\uB97C \uC77D\uC5B4 \`description\`\uACFC \uD568\uAED8 \uBCF4\uC5EC\uC900\uB2E4.
+- \uD398\uC774\uC9C0\uB77C\uACE0 \uB2F5\uD558\uBA74 **\uAD00\uB9AC\uB3C4\uAD6C\uC5D0 \uB4F1\uB85D\uB41C \uACBD\uB85C**\uB97C \uBB3B\uB294\uB2E4. \uC774\uAC83\uB9CC\uC740 \uC0AC\uC6A9\uC790\uAC00 \uAD00\uB9AC\uB3C4\uAD6C\uB97C \uBD10\uC57C \uD55C\uB2E4 \u2014 \uB300\uC2E0 "\uAD00\uB9AC\uB3C4\uAD6C\uC5D0\uC11C \uC774 \uCEE4\uC2A4\uD140 \uD398\uC774\uC9C0\uC758 \uACBD\uB85C\uB97C \uD655\uC778\uD574 \uC8FC\uC138\uC694"\uCC98\uB7FC \uC5B4\uB514\uB97C \uBCF4\uBA74 \uB418\uB294\uC9C0\uAE4C\uC9C0 \uC54C\uB824\uC900\uB2E4.
+- \uD655\uC778\uC774 \uC548 \uB418\uBA74 \uCD94\uCE21\uD574\uC11C \uC62E\uAE30\uC9C0 \uB9D0\uACE0 \uBA48\uCD98\uB2E4. \uACBD\uB85C\uAC00 \uD2C0\uB9AC\uBA74 \uBC30\uD3EC \uD6C4 \uD654\uBA74\uC774 \uC548 \uB728\uB294\uB370, \uC6D0\uC778\uC744 \uCC3E\uAE30 \uC5B4\uB835\uB2E4.
+
+\uC62E\uAE34 \uB4A4\uC5D0\uB294 \uAC1C\uBC1C\uC6A9 \uC9C4\uC785\uC810\uC758 \`import.meta.glob\`(\uC720\uC800 \uD504\uB85C\uC81D\uD2B8\uB294 \`src/App.tsx\`, \uC5B4\uB4DC\uBBFC\uC740 \`src/main.tsx\`)\uACFC \`route-preview.json\`\xB7\`config-preview.json\` \uAC12\uC744 \uD568\uAED8 \uACE0\uCE5C\uB2E4(MIGRATION.md\uC758 \uD574\uB2F9 \uD56D\uBAA9 \uCC38\uC870). \uB9C8\uC9C0\uB9C9\uC5D0 \`npx bstage build\`\uB97C \uB3CC\uB824 \uC0B0\uCD9C\uBB3C\uC774 \uC758\uB3C4\uD55C \uACBD\uB85C\uB85C \uB098\uC624\uB294\uC9C0 \uD655\uC778\uD558\uACE0, \uADF8 \uBAA9\uB85D\uC744 \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uBCF4\uC5EC\uC900\uB2E4.
+
+> \uAD00\uB9AC\uB3C4\uAD6C\uAC00 \uD604\uC7AC \uB9E4\uD551\uC744 \uC870\uD68C\uD558\uB294 API\uB97C \uC5F4\uBA74 \uC774 \uBB3C\uC74C\uC740 \uC790\uB3D9 \uC870\uD68C\uB85C \uB300\uCCB4\uD560 \uC218 \uC788\uB2E4. \uADF8\uB54C\uAE4C\uC9C0\uB294 \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uBB3B\uB294 \uAC8C \uC720\uC77C\uD55C \uBC29\uBC95\uC774\uB2E4.
+
+### 3d. AGENTS.md \uAD00\uB9AC \uC601\uC5ED \uB3D9\uAE30\uD654
+
+\`AGENTS.md\`\uB294 **SDK \uAD00\uB9AC \uC601\uC5ED**(\uB9C8\uCEE4 \`BSTAGE:MANAGED:START\`~\`END\`\uB85C \uAC10\uC2FC SDK \uC800\uC791 \uBCF4\uC77C\uB7EC\uD50C\uB808\uC774\uD2B8)\uACFC **\uC790\uC720 \uC601\uC5ED**(\uB9C8\uCEE4 \uBC14\uAE65, \uD504\uB85C\uC81D\uD2B8 \uACE0\uC720 \uADDC\uCE59)\uC73C\uB85C \uB098\uB25C\uB2E4. doctor\uC758 \`agentsMd.status\`\uB85C \uBD84\uAE30\uD55C\uB2E4.
+
+- \`ok\` \u2014 \uD560 \uC77C \uC5C6\uC74C.
+- \`stale\` (\uB9C8\uCEE4\uB294 \uC788\uACE0 \uBC84\uC804\uB9CC \uB0AE\uC74C) \u2014 **\uC790\uB3D9**. \`bstage skills install\`\uC744 \uC2E4\uD589\uD558\uBA74 \uAD00\uB9AC \uC601\uC5ED\uB9CC \uCD5C\uC2E0\uC73C\uB85C \uCE58\uD658\uB418\uACE0 \uC790\uC720 \uC601\uC5ED\uC740 \uBCF4\uC874\uB41C\uB2E4. \uB05D.
+- \`legacy\` (\uB9C8\uCEE4 \uC5C6\uC74C \u2014 \uC61B \uD504\uB85C\uC81D\uD2B8) \u2014 **\uD310\uB2E8**. SDK \uB0B4\uC6A9\uACFC \uC0AC\uC6A9\uC790 \uB0B4\uC6A9\uC774 \uD55C \uB369\uC5B4\uB9AC\uB77C 1\uD68C reconcile\uC774 \uD544\uC694\uD558\uB2E4. **\uACBD\uACC4\uB294 \uB124(\uC5D0\uC774\uC804\uD2B8)\uAC00 \uBA3C\uC800 \uBD84\uB958\uD574 \uC81C\uC548\uD558\uACE0, \uC0AC\uC6A9\uC790\uC5D0\uAC90 \uD655\uC778\uB9CC \uBC1B\uB294\uB2E4** \u2014 \uC0AC\uC6A9\uC790\uC5D0\uAC8C "\uC5B4\uB514\uAE4C\uC9C0\uAC00 \uD504\uB85C\uC81D\uD2B8 \uCD94\uAC00\uBD84\uC774\uB0D0"\uB97C \uBC31\uC9C0\uC5D0\uC11C \uBB3B\uC9C0 \uC54A\uB294\uB2E4(\uC0AC\uC6A9\uC790\uB294 AGENTS.md \uAD6C\uC870\uB97C \uBAA8\uB97C \uC218 \uC788\uACE0, \uBD84\uB958\uB294 \uB124 \uCC45\uC784\uC774\uB2E4).
+  1. doctor \`--json\`\uC758 \`agentsMd.managedBlock\`\uC774 \uC801\uC6A9\uD560 **\uCD5C\uC2E0 SDK \uAD00\uB9AC \uC601\uC5ED(\uB9C8\uCEE4 \uD3EC\uD568)**\uC774\uB2E4. \uC774\uAC78 \uB808\uD37C\uB7F0\uC2A4\uB85C \uC0BC\uC544, \uC61B AGENTS.md\uC758 \uAC01 \uAD6C\uAC04\uC774 **SDK \uBCF4\uC77C\uB7EC\uD50C\uB808\uC774\uD2B8**(\uD504\uB85C\uC81D\uD2B8 \uAC1C\uC694\xB7SDK \uBB38\uC11C \uBAA9\uB85D\xB7\uD504\uB85C\uC81D\uD2B8 \uAD6C\uC870\xB7\uD15C\uD50C\uB9BF \uC791\uC131 \uADDC\uCE59\xB7\uAE08\uC9C0 \uC0AC\uD56D\xB7\uC61B \`client.get('/api/...')\` \uC608\uC2DC\uB098 \uC5D4\uB4DC\uD3EC\uC778\uD2B8 \uBAA9\uB85D \uB4F1 \u2014 managedBlock\uC774 \uB300\uCCB4\uD558\uB294 \uAC83)\uC778\uC9C0, **\uD504\uB85C\uC81D\uD2B8 \uACE0\uC720 \uB0B4\uC6A9**(\uC774 \uB808\uD3EC\uB9CC\uC758 \uADDC\uCE59\xB7\uB3C4\uBA54\uC778 \uBA54\uBAA8 \uB4F1)\uC778\uC9C0 \uBD84\uB958\uD55C\uB2E4.
+  2. \uBD84\uB958 \uACB0\uACFC\uB85C "\uB9E8 \uC704 = managedBlock, \uADF8 \uC544\uB798 \uC790\uC720 \uC601\uC5ED = \uD504\uB85C\uC81D\uD2B8 \uACE0\uC720 \uB0B4\uC6A9\uB9CC" \uAD6C\uC870\uC758 \uC7AC\uC791\uC131\uC548\uC744 \uB9CC\uB4E0\uB2E4. SDK \uBCF4\uC77C\uB7EC\uD50C\uB808\uC774\uD2B8\uB294 managedBlock\uC774 \uB300\uC2E0\uD558\uBBC0\uB85C **\uC790\uC720 \uC601\uC5ED\uC5D0 \uC911\uBCF5 \uBCF4\uC874\uD558\uC9C0 \uC54A\uB294\uB2E4** \u2014 \uD2B9\uD788 \uC61B \`/api/\` \uACBD\uB85C \uBAA9\uB85D\uC774 \uB0A8\uC73C\uBA74 \uC7AC\uBC1C \uC6D0\uC778\uC774 \uB41C\uB2E4.
+  3. \uC790\uC720 \uC601\uC5ED\uC73C\uB85C \uBCF4\uC874\uD558\uB824\uB294 \uD56D\uBAA9(=\uB124\uAC00 "\uD504\uB85C\uC81D\uD2B8 \uACE0\uC720"\uB85C \uBD84\uB958\uD55C \uAC83)\uC744 \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uC81C\uC2DC\uD558\uACE0 **\uACBD\uACC4\uB97C \uD655\uC778\uBC1B\uB294\uB2E4**: "\uC774 \uBD80\uBD84\uB4E4\uC744 \uD504\uB85C\uC81D\uD2B8 \uACE0\uC720 \uB0B4\uC6A9\uC73C\uB85C \uBCF4\uACE0 \uBCF4\uC874\uD558\uB824\uB294\uB370 \uB9DE\uB098\uC694? SDK \uC601\uC5ED\uC73C\uB85C \uBE7C\uB3C4 \uB418\uB294 \uAC8C \uC11E\uC5EC \uC788\uAC70\uB098, \uBE60\uC9C4 \uAC8C \uC788\uB098\uC694?" (\uC774\uAC74 "\uCF54\uB4DC\uAC00 \uB9DE\uB0D0"\uB294 \uAC80\uC99D\uC774 \uC544\uB2C8\uB77C "\uC774\uAC8C \uB108\uD76C\uAC00 \uCD94\uAC00\uD55C \uAC70\uB0D0"\uB294 \uC18C\uC720 \uD655\uC778\uC774\uB77C \uC0AC\uC6A9\uC790\uAC00 \uB2F5\uD560 \uC218 \uC788\uB2E4.) \uC560\uB9E4\uD55C \uAD6C\uAC04\uC740 \uC784\uC758\uB85C \uC9C0\uC6B0\uC9C0 \uB9D0\uACE0 \uC790\uC720 \uC601\uC5ED\uC5D0 \uB0A8\uACA8 \uD6C4\uBCF4\uB85C \uC81C\uC2DC\uD55C\uB2E4.
+  4. \uD655\uC778\xB7\uC870\uC815 \uD6C4 \uC7AC\uC791\uC131\uD558\uACE0, \uCD5C\uC885 diff\uB97C \uBCF4\uC5EC\uC900\uB2E4.
+
+## 4. \uAC80\uC99D
+
+- \uC124\uCE58\uAC00 \uB05D\uB0AC\uB294\uC9C0 \uD655\uC778\uD558\uACE0, \uD504\uB85C\uC81D\uD2B8\uC758 \uD0C0\uC785\uCCB4\uD06C\xB7\uB9B0\uD2B8\xB7\uBE4C\uB4DC\uB97C \uB3CC\uB824 \uAE68\uC9C4 \uACF3\uC774 \uC5C6\uB294\uC9C0 \uBCF8\uB2E4.
+- \`npx @bstage-sdk/cli@latest doctor\`\uB97C \uB2E4\uC2DC \uB3CC\uB824 \uBC84\uC804\uC774 \uCD5C\uC2E0\uC73C\uB85C \uC815\uB9AC\uB410\uB294\uC9C0 \uD655\uC778\uD55C\uB2E4(init \uAE30\uBCF8 \uD30C\uC77C \uCC28\uC774\uB294 \uC758\uB3C4\uC801\uC73C\uB85C \uB0A8\uAE38 \uC218 \uC788\uB2E4).
+- \uB0A8\uC740 \`\uD310\uB2E8\` \uD56D\uBAA9(\uC608: \uB3C4\uC785\uC744 \uBCF4\uB958\uD55C \uC120\uD0DD \uAE30\uB2A5)\uC774 \uC788\uC73C\uBA74 \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uBCF4\uACE0\uD55C\uB2E4.
+
+# \uD558\uC9C0 \uB9D0 \uAC83
+
+- **\uAE30\uC5B5\xB7\uAC00\uC815\uC73C\uB85C \uC801\uC6A9\uD558\uAE30** \u2014 \uC124\uCE58\uB41C \uD328\uD0A4\uC9C0(\`MIGRATION.md\`\xB7\uD0C0\uC785 \uC120\uC5B8)\uC640 \uD504\uB85C\uC81D\uD2B8 \uC2E4\uC81C \uCF54\uB4DC\uB85C \uD655\uC778\uD558\uC9C0 \uC54A\uACE0 \uBCC0\uD658\uD558\uAE30
+- **\uC0AC\uC6A9\uC790\uC5D0\uAC8C \uCF54\uB4DC \uAC80\uC99D\uC744 \uB5A0\uB118\uAE30\uAE30** \u2014 "\uC774 \uCF54\uB4DC \uB9DE\uB098\uC694?"\uCC98\uB7FC \uC0AC\uC6A9\uC790\uAC00 \uC9C1\uC811 \uD655\uC778\uD574\uC57C \uB2F5\uD560 \uC218 \uC788\uB294 \uC9C8\uBB38\uD558\uAE30 (\uC0AC\uC6A9\uC790\uB294 \uAC1C\uBC1C\uC790\uAC00 \uC544\uB2D0 \uC218 \uC788\uB2E4 \u2014 \uAC80\uC99D\uC740 \uB124 \uBAAB)
+- \uC0AC\uC6A9\uC790 \uCF54\uB4DC\uB97C \uD1B5\uC9F8\uB85C \uB36E\uC5B4\uC4F0\uAE30 (\uD2B9\uD788 \`src/pages/**\`\xB7\`src/slots/**\`, \uCEE4\uC2A4\uD140 \`shared\`/\`api\` \uB4F1)
+- \uD15C\uD50C\uB9BF\uC774 \uD398\uC774\uC9C0\uC778\uC9C0 \uC704\uC82F\uC778\uC9C0, \uD398\uC774\uC9C0\uBA74 \uC5B4\uB290 \uACBD\uB85C\uC778\uC9C0\uB97C **\uCD94\uCE21\uD574\uC11C** \uC62E\uAE30\uAE30 (\uAD00\uB9AC\uB3C4\uAD6C\uC5D0\uB9CC \uC788\uB294 \uC815\uBCF4\uB2E4)
+- \uD55C \uBC88\uC5D0 \uBAA8\uB4E0 \uBCC0\uACBD\uC744 \uC801\uC6A9\uD558\uACE0 \uAC80\uC99D\uC744 \uAC74\uB108\uB6F0\uAE30
+- \`\uD310\uB2E8\` \uD56D\uBAA9\uC744 \uC0AC\uC6A9\uC790 \uD655\uC778 \uC5C6\uC774 \uCD94\uCE21\uC73C\uB85C \uBCC0\uD658\uD558\uAE30
+- \`.bstage/i18n/**/*.json\` \uAC19\uC740 \uC7AC\uC0DD\uC131 \uAC00\uB2A5\uD55C \uCE90\uC2DC\uB97C \uC190\uC73C\uB85C \uD3B8\uC9D1\uD558\uAE30 (\`bstage i18n pull\`\uB85C \uC0DD\uC131)
+`;
+}
+
+// src/templates/templateSkillMd.ts
+function templateSkillMd(target = "user") {
+  return `---
+name: bstage-template
+description: b.stage \uC11C\uB4DC\uD30C\uD2F0 \uD15C\uD50C\uB9BF\uC744 \uC791\uC131\xB7\uC218\uC815\uD55C\uB2E4. \uC0C8 \uD15C\uD50C\uB9BF\uC744 \uB9CC\uB4E4\uAC70\uB098, createTemplate\xB7\uC2AC\uB86F\xB7\uD50C\uB7AB\uD3FC \uC774\uBCA4\uD2B8\xB7\uB2E4\uAD6D\uC5B4\xB7API \uD638\uCD9C\uC744 \uB2E4\uB8E8\uAC70\uB098, "\uD15C\uD50C\uB9BF \uCD94\uAC00/\uAC1C\uBC1C", "bstage \uC704\uC82F \uB9CC\uB4E4\uC5B4\uC918" \uAC19\uC740 \uC694\uCCAD\uC744 \uBC1B\uC744 \uB54C \uC0AC\uC6A9\uD55C\uB2E4.
+---
+
+# \uC5ED\uD560
+
+\uC774 \uD504\uB85C\uC81D\uD2B8\uC5D0\uC11C b.stage \uD15C\uD50C\uB9BF\uC744 \uC791\uC131\uD55C\uB2E4. \uC791\uC131\uD55C React \uCEF4\uD3EC\uB10C\uD2B8\uB294 SDK\uAC00 Web Component\uB85C \uBE4C\uB4DC\uD574 \uD50C\uB7AB\uD3FC\uC5D0 \uB9C8\uC6B4\uD2B8\uD55C\uB2E4. \uC774 \uC2A4\uD0AC\uC740 **\uBAA9\uD45C\uC9C0\uD5A5 \uC808\uCC28 + \uD568\uC815**\uB9CC \uB2F4\uB294\uB2E4. \uC815\uD655\uD55C \uC2DC\uADF8\uB2C8\uCC98\uB294 \uD56D\uC0C1 \uC124\uCE58\uB41C docs/\uD0C0\uC785\uC744 SSOT\uB85C \uBCF8\uB2E4.
+
+# \uAD8C\uC704 \uC788\uB294 \uCD9C\uCC98 (\uBA3C\uC800 \uC77D\uAE30)
+
+\uCD94\uCE21\uD558\uC9C0 \uB9D0\uACE0 \uC124\uCE58\uB41C \uD328\uD0A4\uC9C0\uB97C \uBCF8\uB2E4. \uC678\uBD80 \uAC80\uC0C9\uBCF4\uB2E4 \uC2E0\uB8B0\uD560 \uC218 \uC788\uB2E4.
+
+- \`node_modules/@bstage-sdk/core/docs/\` \u2014 GETTING_STARTED, API_REFERENCE, SLOT_*, I18N, BUILD_SYSTEM, DEV_SERVER, DESIGN_TOKENS, SDK_ARCHITECTURE
+- \uD0C0\uC785: \`node_modules/@bstage-sdk/react/dist/*.d.ts\`, \`node_modules/@bstage-sdk/core/dist/*.d.ts\`
+- \uD504\uB85C\uC81D\uD2B8 \uADDC\uCE59: \uB808\uD3EC \uB8E8\uD2B8\uC758 \`AGENTS.md\`
+- \uBB38\uC11C \uBAA9\uB85D: \`npx bstage docs\`
+
+# \uC808\uCC28
+
+## 1. \uC0C8 \uD15C\uD50C\uB9BF \uCD94\uAC00
+
+\uD398\uC774\uC9C0\uB294 \`src/pages/{\uACBD\uB85C}/template.tsx\`(\uD3F4\uB354 \uAD6C\uC870\uAC00 \uACE7 \uBC30\uD3EC \uACBD\uB85C), \uC704\uC82F\uC740 \`src/slots/{\uC544\uBB34 \uC774\uB984}/template.tsx\` + \`slot\` \uC635\uC158\uC73C\uB85C \uB9CC\uB4E0\uB2E4. \uD30C\uC77C\uBA85\uC740 \uBC18\uB4DC\uC2DC \`template.tsx\`(\uB77C\uC6B0\uD305\xB7\uBE4C\uB4DC\uAC00 \uC774 \uCEE8\uBCA4\uC158\uC73C\uB85C \uBC1C\uACAC). \`name\`\uC740 Custom Element \uD0DC\uADF8\uB85C \uADF8\uB300\uB85C \uC4F0\uC774\uBBC0\uB85C **\uC18C\uBB38\uC790 \uC2DC\uC791 + \uD558\uC774\uD508 1\uAC1C \uC774\uC0C1 + \uC18C\uBB38\uC790\xB7\uC22B\uC790\xB7\uD558\uC774\uD508\uB9CC**.
+
+\`\`\`tsx
+import { createTemplate } from '@bstage-sdk/react'
+
+export default function MyWidget() {
+  return <div>...</div>
+}
+
+createTemplate(MyWidget, { name: 'my-widget' }) // \uD3F4\uB354\uBA85\uACFC \uB3D9\uC77C, \uD558\uC774\uD508 \uD544\uC218
+\`\`\`
+
+## 2. \uAE30\uB2A5\uBCC4 \uD6C5 (\uC2DC\uADF8\uB2C8\uCC98\uB294 API_REFERENCE.md / .d.ts \uD655\uC778)
+
+- **\uD50C\uB7AB\uD3FC \uB124\uBE44\uAC8C\uC774\uC158**: \`useNavigation()\` \u2014 \`navigate\`/\`goBack\`/\`openExternal\`
+- **\uD50C\uB7AB\uD3FC \uC774\uBCA4\uD2B8**: \`useBstageContext()\`\uC758 \`bridge\`\uB85C \`emit\`(\uD15C\uD50C\uB9BF\u2192\uD50C\uB7AB\uD3FC), \uAD6C\uB3C5\uC740 \`usePlatformEvent()\`(\uD50C\uB7AB\uD3FC\u2192\uD15C\uD50C\uB9BF)
+- **API \uD638\uCD9C**: \`shared/client.ts\`\uC758 \`client\` \uC778\uC2A4\uD134\uC2A4\uB97C import\uD574 \uC9C1\uC811 \uD638\uCD9C(\`client.get<T>(...)\`). \`BstageClient\`\uB294 \uC778\uC99D fetch\xB7\uAC8C\uC774\uD2B8\uC6E8\uC774 base URL\uC744 \uC2A4\uC2A4\uB85C \uD574\uC11D\uD558\uBBC0\uB85C \uBCC4\uB3C4 \uBC30\uC120\uC774 \uD544\uC694 \uC5C6\uB2E4. **\uACBD\uB85C\xB7\uC751\uB2F5 \uBAA8\uC591\uC740 SDK\uAC00 \uB4E4\uACE0 \uC788\uC9C0 \uC54A\uB2E4** \u2014 \uAC8C\uC774\uD2B8\uC6E8\uC774 API Reference Doc\uC774 \uCD9C\uCC98\uC774\uACE0, \uC751\uB2F5 \uD0C0\uC785\uC740 \uC81C\uB124\uB9AD\uC73C\uB85C \uBA85\uC2DC\uD55C\uB2E4(\uC0DD\uB7B5\uD558\uBA74 \`unknown\`). **\uC720\uC800\uB2E8 API\uB9CC \uC9C0\uC6D0.** **\uC5B4\uB4DC\uBBFC\uC6A9 API\uB294 \uBBF8\uC9C0\uC6D0 \u2014 \uD544\uC694\uD558\uBA74 \uACBD\uB85C\uB97C \uCD94\uCE21\uD558\uC9C0 \uB9D0\uACE0 \uBC18\uB4DC\uC2DC \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uBA3C\uC800 \uD655\uC778\uD560 \uAC83.**
+- **\uC2AC\uB86F context**: \`useSlotContext<Id>()\` \u2014 \uD638\uC2A4\uD2B8\uAC00 \uB9C8\uC6B4\uD2B8 \uC2DC 1\uD68C \uC804\uB2EC\uD558\uB294 read-only \uAC12
+- **\uB2E4\uAD6D\uC5B4**: \uB85C\uCF00\uC77C \uD6C5(\`useLocale\`/\`useMessages\`/\`useBstageTranslations\`)\uC740 **\uBC18\uB4DC\uC2DC \`<BstageLocaleProvider>\` \uD558\uC704\uC5D0\uC11C** \uD638\uCD9C\uD55C\uB2E4(\uBC16\uC774\uBA74 throw). \uC720\uC800 \uD15C\uD50C\uB9BF\uC740 \`<BstageLocaleProvider>\`(target \uC0DD\uB7B5), \uC5B4\uB4DC\uBBFC\uC740 \`<BstageLocaleProvider target="admin">\`. \uC790\uCCB4 \uBB38\uAD6C\uB294 \`useMessages\`(\uC900\uBE44 \uBD88\uD544\uC694). \uD50C\uB7AB\uD3FC \uACF5\uC6A9 \uBB38\uAD6C\uB97C \uC4F0\uB824\uBA74 **\uBA3C\uC800 \`bstage i18n pull\`\uC744 \uC2E4\uD589**\uD574 \uBC88\uC5ED \uD0A4\xB7\uD0C0\uC785\xB7\uB85C\uCEEC \uCE90\uC2DC(\`.bstage/i18n\`)\uB97C \uB9CC\uB4E0 \uB4A4 \`useBstageTranslations\`\uB97C \uC4F4\uB2E4 \u2014 \uC548 \uD558\uBA74 \uB85C\uCEEC dev\uC5D0\uC11C \uBC88\uC5ED\uC774 \uC548 \uB728\uACE0 \uD0A4\uB3C4 \uC54C \uC218 \uC5C6\uB2E4. **\uC720\uC800 \uC2AC\uB86F \uD15C\uD50C\uB9BF\uC740 \`--target user\`(\uAE30\uBCF8, Bxxxxx), \uC5B4\uB4DC\uBBFC \uC2AC\uB86F \uD15C\uD50C\uB9BF\uC740 \`--target admin\`(Axxxxx)** \u2014 Provider \`target\`\uACFC \uAC19\uC740 \uCD95. \uD604\uC7AC \uC5B8\uC5B4\uB9CC \uD544\uC694\uD558\uBA74 \`useLocale\`. \uC0C1\uC138 \uC6CC\uD06C\uD50C\uB85C\uB294 I18N.md
+- **\uB2E4\uAD6D\uC5B4 \uBB38\uAD6C \uBC30\uBD84 (\uC791\uC5C5 \uC804 \uACB0\uC815)**: "\uB2E4\uAD6D\uC5B4 \uCC98\uB9AC\uD574\uC918" \uB958 \uC694\uCCAD\uC744 \uBC1B\uC73C\uBA74 \uC804\uBD80 \`useMessages\`\uB85C \uB9CC\uB4E4\uC9C0 \uB9D0\uACE0, **\uD50C\uB7AB\uD3FC \uD0A4 \uB300\uC870\uBD80\uD130** \uD55C\uB2E4 \u2014 \`bstage i18n pull\` \uC2E4\uD589 \u2192 \uC0DD\uC131\uB41C \`src/bstage-i18n.ts\`\uC5D0\uC11C \uB300\uC0C1 \uBB38\uAD6C\uC758 \uC6D0\uBB38 \uAC80\uC0C9 \u2192 \uB9E4\uCE6D\uB418\uB294 \uD0A4\uAC00 \uC788\uC73C\uBA74 \uACF5\uC6A9 \uD0A4(\`useBstageTranslations\`), \uC5C6\uB294 \uBB38\uAD6C\uB9CC \`useMessages\`\uC5D0 \uCD94\uAC00. \uC800\uC7A5\xB7\uCDE8\uC18C\xB7\uC801\uC6A9\uD558\uAE30 \uAC19\uC740 \uACF5\uC6A9 UI \uB77C\uBCA8\uC740 \uB300\uBD80\uBD84 \uD50C\uB7AB\uD3FC \uD0A4\uAC00 \uC774\uBBF8 \uC788\uB2E4. \uACF5\uC6A9 \uD0A4\uAC00 \uC788\uB294 \uBB38\uAD6C\uB97C \`useMessages\`\uC5D0 \uBCF5\uC0AC\uD574 \uB36E\uC5B4\uC4F0\uBA74 \uD50C\uB7AB\uD3FC \uBC88\uC5ED \uC218\uC815\uC774 \uD15C\uD50C\uB9BF\uC5D0 \uBC18\uC601\uB418\uC9C0 \uC54A\uB294\uB2E4(\uD63C\uC6A9 \uD328\uD134\uC740 I18N.md).
+
+## 3. \uB514\uC790\uC778 \uD1A0\uD070 (\uC0C9\xB7\uD0C0\uC774\uD3EC\xB7\uADF8\uB9BC\uC790)
+
+${designGuideSection(target)}
+
+## 4. \uB85C\uCEEC \uC2E4\uD589 / \uBE4C\uB4DC
+
+- \`npm run dev\` \u2014 \uC778\uC99D \uD504\uB85D\uC2DC \uD3EC\uD568 \uAC1C\uBC1C \uC11C\uBC84. \uB85C\uADF8\uC778: http://localhost:5173/__bstage__/login
+- \uC0B0\uCD9C\uBB3C \uD655\uC778: \`npx bstage build\` \u2192 \uD398\uC774\uC9C0\uB294 \`dist/{\uACBD\uB85C}/template.js\`, \uC704\uC82F\uC740 \`dist/{\uC2AC\uB86F id}/template.js\` (\uBC30\uD3EC\uB294 \uAD00\uB9AC\uB3C4\uAD6C\uAC00 \uD2B8\uB9AC\uAC70)
+
+# \uD568\uC815 (SDK \uC124\uACC4 \uC81C\uC57D \u2014 \uC5B4\uAE30\uBA74 \uB7F0\uD0C0\uC784\xB7\uBE4C\uB4DC\uAC00 \uAE68\uC9D0)
+
+- **CSS\uB294 Shadow DOM \uC548\uC73C\uB85C \uB123\uC5B4\uC57C \uD55C\uB2E4**: \uD15C\uD50C\uB9BF\uC740 Shadow DOM\uC5D0 \uB9C8\uC6B4\uD2B8\uB41C\uB2E4. **\`import './style.css'\`\uB294 \uBC30\uD3EC \uC0B0\uCD9C\uBB3C\uC5D0\uC11C \uC870\uC6A9\uD788 \uC0AC\uB77C\uC9C4\uB2E4** \u2014 \uB85C\uCEEC \uAC1C\uBC1C \uD654\uBA74\uC5D0\uC11C\uB294 \uC801\uC6A9\uB418\uBBC0\uB85C "\uB85C\uCEEC\uC5D0\uC120 \uB418\uB294\uB370 \uBC30\uD3EC\uD558\uBA74 \uC2A4\uD0C0\uC77C\uC774 \uC5C6\uB2E4"\uB85C \uB098\uD0C0\uB09C\uB2E4. \uC4F8 \uC218 \uC788\uB294 \uAC74 \uB458\uBFD0\uC774\uB2E4: \u2460 \`createTemplate\`\uC758 \`styles\` \uC635\uC158(\`import css from './x.css?inline'\`) \u2461 \uCEF4\uD3EC\uB10C\uD2B8 \uC548 \`<style>{cssText}</style>\`. inline \`style={{}}\`\uB3C4 \uBB3C\uB860 \uB41C\uB2E4. \uC804\uC5ED CSS(\`<link>\`)\uB294 \uAE08\uC9C0.
+- **IIFE \uB2E8\uC77C \uBC88\uB4E4**: \uBC88\uB4E4\uC740 \uD56D\uC0C1 \uB2E8\uC77C IIFE. \uCF54\uB4DC \uC2A4\uD50C\uB9BF\xB7\uB3D9\uC801 \`import()\` \uBD88\uAC00.
+- **\`__bstage_fetch__\` \uACC4\uC57D**: \uD50C\uB7AB\uD3FC\uC774 \uC778\uC99D fetch\uB97C \uC804\uC5ED\uC73C\uB85C \uC8FC\uC785\uD55C\uB2E4. \`BstageClient\`\uAC00 \uC774\uB97C \uC6B0\uC120 \uC0AC\uC6A9\uD558\uBBC0\uB85C, fetch \uACBD\uB85C\uB97C \uC6B0\uD68C\uD558\uC9C0 \uB9D0 \uAC83.
+- **\`slot.context\`\uB294 \uB2E8\uBC29\uD5A5\xB7read-only**: \uD638\uC2A4\uD2B8\u2192\uC704\uC82F 1\uD68C \uC804\uB2EC. \uC704\uC82F\uC774 \uB418\uB3CC\uB824 \uC4F0\uC9C0 \uC54A\uB294\uB2E4.
+- **\`createTemplate()\` \uD638\uCD9C \uD615\uD0DC \uC720\uC9C0**: \uBE4C\uB4DC \uD30C\uC774\uD504\uB77C\uC778\uC774 \uC18C\uC2A4\uC5D0\uC11C \`createTemplate(\` \uD638\uCD9C\uC744 \uD30C\uC2F1\uD574 \uBA54\uD0C0\uB370\uC774\uD130\uB97C \uBF51\uB294\uB2E4. \uC778\uC790 \uAD6C\uC870\uB97C \uC784\uC758 \uBCC0\uD615\uD558\uBA74 \uD30C\uC2F1 \uC2E4\uD328.
+
+# \uD558\uC9C0 \uB9D0 \uAC83
+
+- \`src/main.tsx\`\xB7\`src/App.tsx\` \uC218\uC815 (\uAC1C\uBC1C\uC6A9 \uC9C4\uC785\uC810\xB7\uBAA9\uB85D \uD654\uBA74, SDK\uAC00 \uAD00\uB9AC)
+- \`customElements.define()\` / \`attachShadow\` \uC9C1\uC811 \uD638\uCD9C (createTemplate\uC774 \uCC98\uB9AC)
+- \`@bstage-sdk/core\`\uC758 \`createWebComponent()\` \uC9C1\uC811 \uC0AC\uC6A9 \u2014 react \uD328\uD0A4\uC9C0 API\uB9CC
+- UI \uC0C9\xB7\uD0C0\uC774\uD3EC\xB7\uADF8\uB9BC\uC790\uB97C hex/rgb\uB85C \uD558\uB4DC\uCF54\uB529 \u2014 \uB514\uC790\uC778 \uD1A0\uD070(\uC704 3\uBC88) \uC0AC\uC6A9
+- \uC2DC\uADF8\uB2C8\uCC98\uB97C \uAE30\uC5B5\uC5D0 \uC758\uC874\uD574 \uCD94\uCE21 \u2014 \uC704 docs/.d.ts\uC5D0\uC11C \uD655\uC778
+`;
+}
+
+// src/templates/skills.ts
+var BSTAGE_SKILLS = [
+  { name: "bstage-migrate", content: migrateSkillMd },
+  { name: "bstage-template", content: templateSkillMd }
+];
+
+// src/templates/src/mainTsx.ts
+function mainTsx() {
+  return `import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)
+`;
+}
+
+// src/templates/src/appTsx.ts
+function appTsx({ hasApiKey }) {
+  const apiKeyGuide = hasApiKey ? "" : `
+            <li><code>src/shared/client.ts</code>\uC5D0 API \uD0A4\uB97C \uC124\uC815\uD558\uBA74 b.stage API\uB97C \uC0AC\uC6A9\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4.</li>
+            <li>API \uD0A4\uAC00 \uD5C8\uC6A9\uB41C \uD658\uACBD\uC5D0 \uB9DE\uCDB0 <code>.env</code>\uC758 <code>VITE_BSTAGE_PHASE</code>\uB97C \uC124\uC815\uD574\uC57C \uD569\uB2C8\uB2E4.</li>`;
+  return `import { useState, useEffect, type ComponentType } from 'react'
+
+/* import.meta.glob\uC73C\uB85C \uBAA8\uB4E0 \uD15C\uD50C\uB9BF\uC744 \uC790\uB3D9 \uAC10\uC9C0 */
+/* \uD398\uC774\uC9C0\uB294 \uC911\uCCA9 \uD3F4\uB354\uAC00 \uADF8\uB300\uB85C \uBC30\uD3EC \uACBD\uB85C\uAC00 \uB418\uBBC0\uB85C \`**\`\uB85C \uD6D1\uB294\uB2E4. */
+const modules = import.meta.glob<{ default?: ComponentType; [key: string]: unknown }>([
+  './pages/**/template.tsx',
+  './slots/**/template.tsx',
+])
+
+/**
+ * glob \uACBD\uB85C\uC5D0\uC11C \uBBF8\uB9AC\uBCF4\uAE30 \uC8FC\uC18C\uB97C \uBF51\uB294\uB2E4.
+ * ./pages/settings/custom/template.tsx \u2192 pages/settings/custom
+ * ./slots/curation-banner/template.tsx \u2192 slots/curation-banner
+ *
+ * src/ \uC544\uB798 \uACBD\uB85C\uB97C \uADF8\uB300\uB85C \uC4F0\uB294 \uC774\uC720: \uD398\uC774\uC9C0\uC640 \uC704\uC82F\uC774 \uAC19\uC740 \uC774\uB984\uC744 \uC368\uB3C4 \uACB9\uCE58\uC9C0 \uC54A\uACE0,
+ * \uBAA9\uB85D \uD654\uBA74(/)\uACFC\uB3C4 \uBD80\uB52A\uD788\uC9C0 \uC54A\uB294\uB2E4.
+ */
+function parseName(path: string): string {
+  const match = path.match(/\\.\\/((?:pages|slots)(?:\\/.+)?)\\/template\\.tsx$/)
+  return match?.[1] ?? path
+}
+
+const templateEntries = Object.entries(modules)
+  .map(([path, loader]) => ({ name: parseName(path), loader }))
+  .sort((a, b) => a.name.localeCompare(b.name))
+
+/** \uD15C\uD50C\uB9BF \uBAA9\uB85D + \uC2DC\uC791 \uC548\uB0B4 */
+function TemplatePicker() {
+  return (
+    <div style={{ maxWidth: 520, margin: '60px auto', padding: '0 24px', fontFamily: 'system-ui, sans-serif' }}>
+      <h1 style={{ fontSize: 24, marginBottom: 24 }}>b.stage Templates</h1>
+
+      <section style={{ marginBottom: 28 }}>
+        <h2 style={{ fontSize: 15, fontWeight: 600, marginBottom: 8 }}>\uD15C\uD50C\uB9BF \uBAA9\uB85D</h2>
+        <ul style={{ listStyle: 'none', padding: 0, display: 'flex', flexDirection: 'column', gap: 8 }}>
+          {templateEntries.map(({ name }) => (
+            <li key={name}>
+              <a
+                href={\`/\${name}\`}
+                style={{
+                  display: 'block',
+                  padding: '12px 16px',
+                  border: '1px solid #e2e2e2',
+                  borderRadius: 8,
+                  textDecoration: 'none',
+                  color: '#111',
+                  fontWeight: 500,
+                  transition: 'background 0.15s',
+                }}
+                onMouseEnter={(e) => (e.currentTarget.style.background = '#f5f5f5')}
+                onMouseLeave={(e) => (e.currentTarget.style.background = 'transparent')}
+              >
+                {name}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </section>
+
+      <section style={{ marginBottom: 28 }}>
+        <h2 style={{ fontSize: 15, fontWeight: 600, marginBottom: 8 }}>\uC2DC\uC791\uD558\uAE30</h2>
+        <ol style={{ margin: 0, paddingLeft: 20, display: 'flex', flexDirection: 'column', gap: 6, color: '#444', fontSize: 14 }}>
+          <li>\uC704 \uD15C\uD50C\uB9BF\uC744 \uD074\uB9AD\uD558\uC5EC \uB80C\uB354\uB9C1 \uACB0\uACFC\uB97C \uD655\uC778\uD558\uC138\uC694.</li>
+          <li>\uD398\uC774\uC9C0\uB294 <code>src/pages/{'{\uACBD\uB85C}'}/template.tsx</code> \u2014 \uD3F4\uB354 \uAD6C\uC870\uAC00 \uACE7 \uBC30\uD3EC \uACBD\uB85C\uC785\uB2C8\uB2E4.</li>
+          <li>\uC704\uC82F\uC740 <code>src/slots/{'{\uC544\uBB34\uC774\uB984}'}/template.tsx</code> \u2014 \uC790\uB9AC\uB294 <code>slot</code> \uC635\uC158\uC774 \uC815\uD569\uB2C8\uB2E4.</li>${apiKeyGuide}
+        </ol>
+      </section>
+
+      <p style={{ fontSize: 13, color: '#999' }}>
+        \uC778\uC99D\uC774 \uD544\uC694\uD55C API\uB97C \uD14C\uC2A4\uD2B8\uD558\uB824\uBA74{' '}
+        <a href="/__bstage__/login" style={{ color: '#999' }}>\uB85C\uADF8\uC778</a>
+        \uD558\uC138\uC694.
+      </p>
+    </div>
+  )
+}
+
+export default function App() {
+  const [Component, setComponent] = useState<ComponentType | null>(null)
+  const pathname = location.pathname.replace(/^\\//, '')
+
+  useEffect(() => {
+    if (!pathname) return
+    const entry = templateEntries.find((e) => e.name === pathname)
+    if (!entry) return
+    entry.loader().then((mod) => {
+      /* createTemplate\uC740 default export \uB610\uB294 \uCCAB \uBC88\uC9F8 export\uB41C \uCEF4\uD3EC\uB10C\uD2B8 */
+      const Comp = mod.default ?? (Object.values(mod).find((v) => typeof v === 'function') as ComponentType)
+      if (Comp) setComponent(() => Comp)
+    })
+  }, [pathname])
+
+  if (!pathname) return <TemplatePicker />
+  if (!Component) return <p style={{ padding: 24 }}>Loading...</p>
+  return <Component />
+}
+`;
+}
+
+// src/templates/src/indexCss.ts
+function indexCss() {
+  return `body {
+  margin: 0;
+  min-width: 320px;
+  min-height: 100vh;
+  font-family: system-ui, sans-serif;
+  line-height: 1.5;
+  color: #333;
+  background-color: #fff;
+}
+`;
+}
+
+// src/templates/src/viteEnvDts.ts
+function viteEnvDts() {
+  return `/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_BSTAGE_PHASE: string
+  readonly VITE_BSTAGE_APP_ID: string
+  readonly VITE_BSTAGE_APP_SECRET: string
+  readonly VITE_BSTAGE_TENANT_ID: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+`;
+}
+
+// src/templates/src/clientTs.ts
+function clientTs() {
+  return `import { BstageClient } from '@bstage-sdk/core'
+
+// \uC778\uC99D \uC815\uBCF4\uB294 .env(\uCEE4\uBC0B\uB418\uC9C0 \uC54A\uC74C)\uC5D0\uC11C \uC8FC\uC785\uB429\uB2C8\uB2E4.
+// clone \uD6C4 .env.example\uC744 .env\uB85C \uBCF5\uC0AC\uD574 \uAC12\uC744 \uCC44\uC6B0\uC138\uC694.
+export const client = new BstageClient({
+  appId: import.meta.env.VITE_BSTAGE_APP_ID,
+  appSecret: import.meta.env.VITE_BSTAGE_APP_SECRET,
+  tenantId: import.meta.env.VITE_BSTAGE_TENANT_ID,
+})
+`;
+}
+
+// src/templates/src/templateTsx.ts
+function templateTsx({ name }) {
+  const componentName = name.charAt(0).toUpperCase() + name.slice(1).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  return `import { createTemplate } from '@bstage-sdk/react'
+// import { useNavigation, useBstageContext } from '@bstage-sdk/react'
+// import { client } from '../../shared/client'
+// CSS \uD30C\uC77C\uC744 \uC4F0\uB824\uBA74 ?inline\uC73C\uB85C \uBB38\uC790\uC5F4\uC744 \uAC00\uC838\uC640 \uC544\uB798 styles\uC5D0 \uB118\uAE34\uB2E4.
+// \uBD80\uC218\uD6A8\uACFC import(\`import './x.css'\`)\uB294 \uBC30\uD3EC \uC0B0\uCD9C\uBB3C\uC5D0\uC11C \uC0AC\uB77C\uC9C4\uB2E4.
+// import css from '../../index.css?inline'
+
+export default function ${componentName}Template() {
+  // \u2500\u2500 \uD50C\uB7AB\uD3FC \uB124\uBE44\uAC8C\uC774\uC158 \u2500\u2500
+  // const { navigate, goBack, openExternal } = useNavigation()
+  // navigate('/profile', { userId: '123' })
+
+  // \u2500\u2500 PlatformBridge \uC9C1\uC811 \uC811\uADFC \u2500\u2500
+  // const { bridge } = useBstageContext()
+  // bridge.emit('toast', { message: '\uC800\uC7A5 \uC644\uB8CC', variant: 'success' })
+
+  // \u2500\u2500 API \uD638\uCD9C (shared/client.ts\uC758 \uC778\uC2A4\uD134\uC2A4\uB97C \uC9C1\uC811 import\uD574 \uC0AC\uC6A9) \u2500\u2500
+  // useEffect(() => {
+  //   client.get('/content/v1/boards').then(res => console.log(res.data))
+  // }, [])
+
+  return (
+    <div style={{ padding: 24, fontFamily: 'system-ui, sans-serif' }}>
+      <h1>Hello, ${name}!</h1>
+    </div>
+  )
+}
+
+createTemplate(${componentName}Template, {
+  name: '${name}',
+  // styles: css,   // Shadow DOM\uC5D0 \uC8FC\uC785 (\uC704 ?inline import\uC640 \uD568\uAED8 \uC0AC\uC6A9)
+})
+`;
+}
+
+// src/templates/slotsReadme.ts
+function slotsReadme() {
+  return `# src/slots
+
+\uD50C\uB7AB\uD3FC \uD654\uBA74 \uC0AC\uC774\uC5D0 \uB07C\uC6CC \uB123\uB294 **\uC704\uC82F**\uC744 \uB450\uB294 \uACF3\uC785\uB2C8\uB2E4.
+\uD398\uC774\uC9C0 \uC804\uCCB4\uB97C \uADF8\uB9AC\uB294 \uD15C\uD50C\uB9BF\uC740 \`src/pages/\`\uC5D0 \uB461\uB2C8\uB2E4.
+
+## \uC704\uC82F \uCD94\uAC00\uD558\uAE30
+
+\uD3F4\uB354\uB97C \uB9CC\uB4E4\uACE0 \uADF8 \uC548\uC5D0 \`template.tsx\`\uB97C \uB461\uB2C8\uB2E4.
+
+\`\`\`
+src/slots/
+  curation-banner/
+    template.tsx
+\`\`\`
+
+\`\`\`tsx
+import { createTemplate } from '@bstage-sdk/react'
+
+export default function CurationBanner() {
+  return <div>\uBC30\uB108</div>
+}
+
+createTemplate(CurationBanner, {
+  name: 'bmf-curation-banner',
+  slot: 'user.contents-home.curation:after',
+})
+\`\`\`
+
+## \uD3F4\uB354 \uC774\uB984\uC740 \uC790\uC720\uC785\uB2C8\uB2E4
+
+\uC5B4\uB290 \uC790\uB9AC\uC5D0 \uBD99\uC744\uC9C0\uB294 **\`slot\` \uC635\uC158\uB9CC** \uC815\uD569\uB2C8\uB2E4. \uD3F4\uB354 \uC774\uB984\uC740 \uC0AC\uB78C\uC774 \uC54C\uC544\uBCF4\uAE30 \uC26C\uC6B0\uBA74 \uB429\uB2C8\uB2E4.
+\uBE4C\uB4DC \uC0B0\uCD9C\uBB3C\uC740 \uC2AC\uB86F id\uB97C \uB530\uB77C \`dist/user.contents-home.curation--after/template.js\`\uB85C \uB098\uAC11\uB2C8\uB2E4
+(\uCF5C\uB860\uC740 Windows\uC5D0\uC11C \uD3F4\uB354 \uC774\uB984\uC5D0 \uC4F8 \uC218 \uC5C6\uC5B4 \`--\`\uB85C \uBC14\uB01D\uB2C8\uB2E4).
+
+\`src/pages/\`\uC640 \uB2EC\uB9AC \uD3F4\uB354 \uAD6C\uC870\uB294 \uBC30\uD3EC \uC704\uCE58\uC5D0 \uC601\uD5A5\uC744 \uC8FC\uC9C0 \uC54A\uC73C\uBBC0\uB85C, \uC6D0\uD558\uB294 \uB9CC\uD07C \uC911\uCCA9\uD574\uB3C4 \uB429\uB2C8\uB2E4.
+
+## \uC4F8 \uC218 \uC788\uB294 \uC790\uB9AC \uBAA9\uB85D
+
+\`slot\`\uC5D0 \uB123\uC744 \uC218 \uC788\uB294 \uAC12\uC740 \uD3B8\uC9D1\uAE30 \uC790\uB3D9\uC644\uC131\uC73C\uB85C \uD655\uC778\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4.
+\uC804\uCCB4 \uBAA9\uB85D\uACFC \uAC01 \uC790\uB9AC\uAC00 \uB118\uACA8\uC8FC\uB294 context\uB294 SDK \uBB38\uC11C\uB97C \uBCF4\uC138\uC694.
+
+\`\`\`bash
+npx bstage docs   # SLOT_CATALOG_V2.md
+\`\`\`
+
+\uC624\uD0C0\uAC00 \uC788\uC73C\uBA74 \`bstage build\`\uAC00 \uD6C4\uBCF4\uC640 \uD568\uAED8 \uB9C9\uC544\uC90D\uB2C8\uB2E4.
+`;
+}
+
+// src/commands/init.ts
+var PHASES = ["dev", "qa", "real", "sandbox"];
+var TARGETS = ["user", "admin"];
+async function initCommand(options) {
+  p.intro(`${pc2.cyan(pc2.bold("bstage init"))} ${pc2.dim("\u2014 b.stage Template Project Setup")}`);
+  let space;
+  let templateName;
+  let packageManager;
+  let phase;
+  let target;
+  let appId = "";
+  let appSecret = "";
+  let tenantId = "";
+  if (options.yes) {
+    const targetOpt = options.target ?? "user";
+    if (!TARGETS.includes(targetOpt)) {
+      p.log.error(`--target \uAC12\uC740 ${TARGETS.join(" | ")} \uC911 \uD558\uB098\uC5EC\uC57C \uD569\uB2C8\uB2E4.`);
+      p.outro(pc2.red("\uC911\uB2E8\uB418\uC5C8\uC2B5\uB2C8\uB2E4."));
+      process.exit(1);
+    }
+    target = targetOpt;
+    if (!options.space) {
+      p.log.error("--yes \uBAA8\uB4DC\uC5D0\uC11C\uB294 --space\uAC00 \uD544\uC218\uC785\uB2C8\uB2E4.");
+      p.outro(pc2.red("\uC911\uB2E8\uB418\uC5C8\uC2B5\uB2C8\uB2E4."));
+      process.exit(1);
+    }
+    const slugPattern = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+    if (!slugPattern.test(options.space)) {
+      p.log.error(
+        `${pc2.red("--space")} \uAC12\uC740 \uC601\uBB38\uC790\uB85C \uC2DC\uC791\uD574\uC57C \uD558\uBA70, \uC601\uBB38, \uC22B\uC790, \uD558\uC774\uD508\uB9CC \uC0AC\uC6A9\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4.`
+      );
+      p.outro(pc2.red("\uC911\uB2E8\uB418\uC5C8\uC2B5\uB2C8\uB2E4."));
+      process.exit(1);
+    }
+    space = options.space;
+    const templateOpt = resolveTemplateName(space, options.template);
+    if (!ELEMENT_NAME_RE2.test(templateOpt)) {
+      p.log.error(
+        `${pc2.red("--template")} \uAC12\uC740 Custom Element \uC2A4\uD399\uC744 \uB530\uB77C\uC57C \uD569\uB2C8\uB2E4: \uC18C\uBB38\uC790 \uC2DC\uC791, \uD558\uC774\uD508 1\uAC1C \uC774\uC0C1, \uC18C\uBB38\uC790\xB7\uC22B\uC790\xB7\uD558\uC774\uD508\uB9CC.`
+      );
+      p.outro(pc2.red("\uC911\uB2E8\uB418\uC5C8\uC2B5\uB2C8\uB2E4."));
+      process.exit(1);
+    }
+    templateName = templateOpt;
+    packageManager = options.pm ?? "npm";
+    const phaseOpt = options.phase ?? "sandbox";
+    if (!PHASES.includes(phaseOpt)) {
+      p.log.error(`--phase \uAC12\uC740 ${PHASES.join(" | ")} \uC911 \uD558\uB098\uC5EC\uC57C \uD569\uB2C8\uB2E4.`);
+      p.outro(pc2.red("\uC911\uB2E8\uB418\uC5C8\uC2B5\uB2C8\uB2E4."));
+      process.exit(1);
+    }
+    phase = phaseOpt;
+  } else {
+    target = await p.select({
+      message: "\uCCAB \uBC88\uC9F8 \uD15C\uD50C\uB9BF\uC740 \uC5B4\uB290 \uD50C\uB7AB\uD3FC\uC6A9\uC778\uAC00\uC694? (\uB808\uD3EC\uC5D0 \uB450 \uC885\uB958\uB97C \uC11E\uC744 \uC218 \uC788\uC2B5\uB2C8\uB2E4)",
+      options: [
+        { value: "user", label: "user (b.stage \uC720\uC800 \uD50C\uB7AB\uD3FC)" },
+        { value: "admin", label: "admin (b.stage \uC5B4\uB4DC\uBBFC \uD50C\uB7AB\uD3FC)" }
+      ],
+      initialValue: options.target === "admin" ? "admin" : "user"
+    });
+    if (p.isCancel(target)) return cancelled();
+    space = await p.text({
+      message: "\uD15C\uD50C\uB9BF\uC744 \uC801\uC6A9\uD560 Space ID\uB97C \uC785\uB825\uD574 \uC8FC\uC138\uC694.",
+      validate: validateSlug("Space ID\uB294 \uD544\uC218\uC785\uB2C8\uB2E4.")
+    });
+    if (p.isCancel(space)) return cancelled();
+    phase = await p.select({
+      message: "\uD15C\uD50C\uB9BF\uC744 \uBC30\uD3EC\uD560 \uD658\uACBD\uC744 \uC120\uD0DD\uD574 \uC8FC\uC138\uC694.",
+      options: [
+        { value: "sandbox", label: "sandbox", hint: "\uAE30\uBCF8" },
+        { value: "real", label: "real" },
+        { value: "dev", label: "dev", hint: "\uC0AC\uB0B4 \uC804\uC6A9 \u2014 .env\uC5D0 \uD638\uC2A4\uD2B8\xB7CF Access \uC790\uACA9\uC99D\uBA85 \uD544\uC694" },
+        { value: "qa", label: "qa", hint: "\uC0AC\uB0B4 \uC804\uC6A9 \u2014 .env\uC5D0 \uD638\uC2A4\uD2B8\xB7CF Access \uC790\uACA9\uC99D\uBA85 \uD544\uC694" }
+      ],
+      initialValue: "sandbox"
+    });
+    if (p.isCancel(phase)) return cancelled();
+    templateName = await p.text({
+      message: `\uCCAB \uBC88\uC9F8 \uD15C\uD50C\uB9BF \uC774\uB984\uC744 \uC785\uB825\uD574 \uC8FC\uC138\uC694. ${pc2.dim(`(\uC608: ${space}-hello \u2014 \uD558\uC774\uD508 \uD544\uC218)`)}`,
+      placeholder: resolveTemplateName(space, void 0),
+      validate: validateElementName
+    });
+    if (p.isCancel(templateName)) return cancelled();
+    packageManager = await p.select({
+      message: "\uC0AC\uC6A9\uD560 \uD328\uD0A4\uC9C0 \uB9E4\uB2C8\uC800\uB97C \uC120\uD0DD\uD574 \uC8FC\uC138\uC694.",
+      options: [
+        { value: "npm", label: "npm" },
+        { value: "pnpm", label: "pnpm" }
+      ],
+      initialValue: "npm"
+    });
+    if (p.isCancel(packageManager)) return cancelled();
+    const configureAuth = await p.confirm({
+      message: "b.stage \uD30C\uD2B8\uB108\uC2A4\uC5D0\uC11C \uBC1C\uAE09\uBC1B\uC740 API \uD0A4\uAC00 \uC788\uC73C\uC2E0\uAC00\uC694? (\uC5C6\uC5B4\uB3C4 \uC2DC\uC791\uD560 \uC218 \uC788\uC5B4\uC694)",
+      initialValue: false
+    });
+    if (p.isCancel(configureAuth)) return cancelled();
+    if (configureAuth) {
+      p.log.info(pc2.dim("API \uC778\uC99D \uC124\uC815 (\uC120\uD0DD)"));
+      appId = await p.text({
+        message: "\uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09\uBC1B\uC740 APP-ID\uB97C \uC785\uB825\uD574 \uC8FC\uC138\uC694."
+      }) ?? "";
+      if (p.isCancel(appId)) return cancelled();
+      appSecret = await p.text({
+        message: "\uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09\uBC1B\uC740 Secret \uAC12\uC744 \uC785\uB825\uD574 \uC8FC\uC138\uC694."
+      }) ?? "";
+      if (p.isCancel(appSecret)) return cancelled();
+      warnIfCredentialsSwapped(appId, appSecret);
+      tenantId = space;
+    }
+  }
+  const projectName = `${space}-custom-templates-${phase}`;
+  const projectDir = resolve2(process.cwd(), projectName);
+  if (existsSync(projectDir)) {
+    p.log.error(
+      `${pc2.red(projectDir)} \uB514\uB809\uD1A0\uB9AC\uAC00 \uC774\uBBF8 \uC874\uC7AC\uD569\uB2C8\uB2E4. \uD574\uB2F9 \uB514\uB809\uD1A0\uB9AC\uB97C \uC815\uB9AC\uD55C \uB4A4 \uB2E4\uC2DC \uC2E4\uD589\uD574 \uC8FC\uC138\uC694.`
+    );
+    p.outro(pc2.red("\uC911\uB2E8\uB418\uC5C8\uC2B5\uB2C8\uB2E4."));
+    process.exit(1);
+  }
+  const s = p.spinner();
+  s.start("SDK \uCD5C\uC2E0 \uBC84\uC804 \uC870\uD68C \uC911...");
+  let sdkVersions;
+  try {
+    const [cli, core, react2, design] = await Promise.all([
+      fetchLatestVersion("@bstage-sdk/cli"),
+      fetchLatestVersion("@bstage-sdk/core"),
+      fetchLatestVersion("@bstage-sdk/react"),
+      fetchLatestVersion("@bstage-sdk/design")
+    ]);
+    sdkVersions = { cli, core, react: react2, design };
+    s.stop(`SDK \uBC84\uC804 \uD655\uC815 \u2014 cli@${cli}, core@${core}, react@${react2}, design@${design}`);
+  } catch (err) {
+    s.stop(pc2.red("SDK \uCD5C\uC2E0 \uBC84\uC804 \uC870\uD68C \uC2E4\uD328"));
+    p.log.error(
+      (err instanceof Error ? err.message : String(err)) + `
+  ${pc2.dim("\uB124\uD2B8\uC6CC\uD06C \uC5F0\uACB0\uACFC registry.npmjs.org \uC811\uADFC\uC774 \uAC00\uB2A5\uD55C\uC9C0 \uD655\uC778\uD574 \uC8FC\uC138\uC694.")}`
+    );
+    p.outro(pc2.red("\uC911\uB2E8\uB418\uC5C8\uC2B5\uB2C8\uB2E4."));
+    process.exit(1);
+  }
+  s.start("\uD504\uB85C\uC81D\uD2B8 \uD30C\uC77C \uC0DD\uC131 \uC911...");
+  const dirs = [
+    "",
+    "src",
+    ".husky",
+    "src/shared",
+    `src/pages/${templateName}`,
+    "src/slots",
+    ...BSTAGE_SKILLS.map((s2) => `.claude/skills/${s2.name}`)
+  ];
+  for (const dir of dirs) {
+    mkdirSync(join2(projectDir, dir), { recursive: true });
+  }
+  const envFiles = [
+    // .env(실제 값)는 커밋되지 않음(.gitignore). .env.example은 커밋되어 팀원 세팅 안내.
+    [
+      ".env",
+      env({
+        phase,
+        appId: appId || "YOUR_APP_ID",
+        appSecret: appSecret || "YOUR_APP_SECRET",
+        tenantId: tenantId || "YOUR_TENANT_ID"
+      })
+    ],
+    [
+      ".env.example",
+      env({
+        phase,
+        appId: "YOUR_APP_ID",
+        appSecret: "YOUR_APP_SECRET",
+        tenantId: "YOUR_TENANT_ID"
+      })
+    ]
+  ];
+  const files = [
+    ["AGENTS.md", agentsMd({ space, projectName, target })],
+    ["CLAUDE.md", claudeMd()],
+    ["README.md", readme({ projectName, packageManager })],
+    ["package.json", packageJson({ projectName, target, sdkVersions })],
+    ["tsconfig.json", tsconfig()],
+    ["tsconfig.app.json", tsconfigApp()],
+    ["tsconfig.node.json", tsconfigNode()],
+    ["vite.config.ts", viteConfig()],
+    ...envFiles,
+    ["index.html", indexHtml()],
+    // pnpm은 의존성 build script를 막고 그걸 에러로 낸다 → 허용 목록이 없으면 install이 실패한다.
+    ...packageManager === "pnpm" ? [["pnpm-workspace.yaml", pnpmWorkspace()]] : [],
+    [".gitignore", gitignore()],
+    [".husky/pre-commit", huskyPreCommit()],
+    [".husky/check-secrets.mjs", checkSecretsScript()],
+    ["eslint.config.js", eslintConfig()],
+    ["src/main.tsx", mainTsx()],
+    // 화면은 App.tsx가 갖는다 — main.tsx에 컴포넌트를 두면 export 없는 파일이 되어 lint가 막는다.
+    ["src/App.tsx", appTsx({ hasApiKey: !!appId })],
+    ["src/index.css", indexCss()],
+    ["src/vite-env.d.ts", viteEnvDts()],
+    ["src/shared/client.ts", clientTs()],
+    [`src/pages/${templateName}/template.tsx`, templateTsx({ name: templateName })],
+    // 빈 디렉토리는 git이 추적하지 않아 커밋하면 src/slots가 사라진다. 안내를 겸해 README를 둔다.
+    ["src/slots/README.md", slotsReadme()],
+    ...BSTAGE_SKILLS.map(
+      (s2) => [`.claude/skills/${s2.name}/SKILL.md`, s2.content(target)]
+    )
+  ];
+  for (const [filePath, content] of files) {
+    writeFileSync(join2(projectDir, filePath), content, "utf-8");
+  }
+  s.stop("\uD504\uB85C\uC81D\uD2B8 \uD30C\uC77C \uC0DD\uC131 \uC644\uB8CC");
+  s.start("Git \uCD08\uAE30\uD654 \uC911...");
+  try {
+    execSync("git init", { cwd: projectDir, stdio: "ignore" });
+    execSync("git add -A", { cwd: projectDir, stdio: "ignore" });
+    execSync('git commit -m "init: bstage \uD15C\uD50C\uB9BF \uD504\uB85C\uC81D\uD2B8 \uCD08\uAE30\uD654"', {
+      cwd: projectDir,
+      stdio: "ignore"
+    });
+    s.stop("Git \uCD08\uAE30\uD654 \uC644\uB8CC");
+  } catch {
+    s.stop(pc2.yellow("Git \uCD08\uAE30\uD654 \uAC74\uB108\uB700 (git\uC774 \uC124\uCE58\uB418\uC9C0 \uC54A\uC558\uC744 \uC218 \uC788\uC2B5\uB2C8\uB2E4)"));
+  }
+  s.start(`\uC758\uC874\uC131 \uC124\uCE58 \uC911... (${packageManager} install)`);
+  try {
+    const installCmd = packageManager === "pnpm" ? "pnpm install" : "npm install";
+    execSync(installCmd, { cwd: projectDir, stdio: "ignore", env: { ...process.env } });
+    s.stop("\uC758\uC874\uC131 \uC124\uCE58 \uC644\uB8CC");
+  } catch {
+    s.stop(pc2.yellow("\uC758\uC874\uC131 \uC124\uCE58 \uC2E4\uD328 \u2014 \uC9C1\uC811 \uC124\uCE58\uD574 \uC8FC\uC138\uC694"));
+  }
+  const runCmd = packageManager === "pnpm" ? "pnpm dev" : "npm run dev";
+  const label = target === "admin" ? "\uC5B4\uB4DC\uBBFC \uD15C\uD50C\uB9BF \uD504\uB85C\uC81D\uD2B8" : "\uD504\uB85C\uC81D\uD2B8";
+  p.outro(`${pc2.green(`${label}\uAC00 \uC0DD\uC131\uB418\uC5C8\uC2B5\uB2C8\uB2E4!`)}
+
+  \uB2E4\uC74C \uB2E8\uACC4:
+  ${pc2.cyan(`cd ${projectName}`)}
+  ${pc2.cyan(runCmd)}
+  ${pc2.dim("# \uBE0C\uB77C\uC6B0\uC800: http://localhost:5173")}`);
+}
+async function fetchLatestVersion(packageName) {
+  const res = await fetch(`https://registry.npmjs.org/${packageName}`, {
+    headers: { Accept: "application/json" }
+  });
+  if (!res.ok) {
+    throw new Error(`${packageName} \uB808\uC9C0\uC2A4\uD2B8\uB9AC \uC870\uD68C \uC2E4\uD328 (HTTP ${res.status})`);
+  }
+  const data = await res.json();
+  const latest = data["dist-tags"]?.latest;
+  if (!latest) {
+    throw new Error(`${packageName}\uC758 latest \uBC84\uC804\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4`);
+  }
+  return latest;
+}
+function validateSlug(requiredMessage) {
+  return (v) => {
+    if (!v?.trim()) return requiredMessage;
+    if (!/^[a-zA-Z][a-zA-Z0-9-]*$/.test(v.trim()))
+      return "\uC601\uBB38\uC790\uB85C \uC2DC\uC791\uD574\uC57C \uD558\uBA70, \uC601\uBB38, \uC22B\uC790, \uD558\uC774\uD508\uB9CC \uC0AC\uC6A9\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4.";
+  };
+}
+var ELEMENT_NAME_RE2 = /^[a-z][a-z0-9-]*-[a-z0-9-]*$/;
+function resolveTemplateName(space, option) {
+  return option ?? `${space.toLowerCase()}-hello`;
+}
+function validateElementName(v) {
+  if (!v?.trim()) return "\uD15C\uD50C\uB9BF \uC774\uB984\uC740 \uD544\uC218\uC785\uB2C8\uB2E4.";
+  if (!ELEMENT_NAME_RE2.test(v.trim())) {
+    return "Custom Element \uC2A4\uD399: \uC18C\uBB38\uC790 \uC2DC\uC791 + \uD558\uC774\uD508 1\uAC1C \uC774\uC0C1 + \uC18C\uBB38\uC790/\uC22B\uC790/\uD558\uC774\uD508\uB9CC.";
+  }
+}
+var APP_ID_PREFIX2 = "bsa_";
+var APP_SECRET_PREFIX2 = "bsp_";
+function warnIfCredentialsSwapped(appId, appSecret) {
+  if (!appId.startsWith(APP_SECRET_PREFIX2) && !appSecret.startsWith(APP_ID_PREFIX2)) return;
+  p.log.warn(
+    `APP-ID\uC640 Secret\uC774 \uC11C\uB85C \uBC14\uB010 \uAC83 \uAC19\uC2B5\uB2C8\uB2E4.
+  APP-ID\uB294 "${APP_ID_PREFIX2}", Secret\uC740 "${APP_SECRET_PREFIX2}"\uB85C \uC2DC\uC791\uD569\uB2C8\uB2E4.
+  \uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09\uBC1B\uC740 \uAC12\uC744 \uB2E4\uC2DC \uD655\uC778\uD574 \uC8FC\uC138\uC694.`
+  );
+}
+function cancelled() {
+  p.outro(pc2.red("\uCDE8\uC18C\uB418\uC5C8\uC2B5\uB2C8\uB2E4."));
+  process.exit(0);
+}
+
+// src/commands/i18n.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname, join as join3, resolve as resolve3 } from "path";
+import pc3 from "picocolors";
+function latestKey(phase, tier, target) {
+  const segments = tier === DEFAULT_TRANSLATION_TIER ? [TRANSLATION_CDN_BASE_KEY, phase, target] : [TRANSLATION_CDN_BASE_KEY, phase, target, tier];
+  return [...segments, "latest.json"].join("/");
+}
+function cacheStamp(now) {
+  const pad = (n) => String(n).padStart(2, "0");
+  const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${pad(now.getHours())}`;
+  const min = now.getMinutes();
+  const floored = min - min % 5;
+  return `${date}-${pad(floored)}`;
+}
+async function fetchJson(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return await res.json();
+}
+function escapeJsdoc(value) {
+  return value.replace(/\*\//g, "*\\/").replace(/\r?\n/g, " ").trim();
+}
+function generateTypeModule(dict, meta2) {
+  const keys = Object.keys(dict).sort();
+  const registry = keys.map((k) => `    /** ${escapeJsdoc(dict[k])} */
+    ${JSON.stringify(k)}: true`).join("\n");
+  const consts = keys.map((k) => `  /** ${escapeJsdoc(dict[k])} */
+  ${JSON.stringify(k)}: ${JSON.stringify(k)},`).join("\n");
+  return `// AUTO-GENERATED by \`bstage i18n pull\` \u2014 \uC9C1\uC811 \uC218\uC815\uD558\uC9C0 \uB9C8\uC138\uC694.
+// version: ${meta2.version} (ref=${meta2.ref}, \uD0A4 ${keys.length}\uAC1C)
+/* eslint-disable */
+
+declare module '@bstage-sdk/core' {
+  interface TranslationKeyRegistry {
+${registry}
+  }
+}
+
+/** \uD50C\uB7AB\uD3FC \uBC88\uC5ED \uD0A4 \u2192 \uCF54\uB4DC. \uD638\uBC84\uB85C \uC6D0\uBB38 \uD655\uC778, \uCF54\uB4DC \uB0B4 \uC6D0\uBB38 \uAC80\uC0C9\uC5D0 \uC0AC\uC6A9\uD55C\uB2E4. */
+export const bstageTranslationKeys = {
+${consts}
+} as const
+`;
+}
+async function i18nPullCommand(options) {
+  const root = process.cwd();
+  const tier = options.tier || DEFAULT_TRANSLATION_TIER;
+  const target = options.target || "user";
+  const latestUrl = `${TRANSLATION_CDN_ORIGIN}/${latestKey(options.phase, tier, target)}?date=${cacheStamp(/* @__PURE__ */ new Date())}`;
+  console.log(pc3.cyan(`[bstage] \uBC88\uC5ED pull: ${options.phase}/${target} (tier=${tier})`));
+  let latest;
+  try {
+    latest = await fetchJson(latestUrl);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(pc3.red(`[bstage] latest.json \uC870\uD68C \uC2E4\uD328: ${msg}
+  ${latestUrl}`));
+    process.exit(1);
+  }
+  const versionBase = `${TRANSLATION_CDN_ORIGIN}/${latest.cdnPath.replace(TRANSLATION_CDN_BUCKET_PREFIX, "")}`;
+  console.log(pc3.dim(`  version: ${latest.version}`));
+  const cacheDir = join3(root, ".bstage", "i18n", target);
+  mkdirSync2(cacheDir, { recursive: true });
+  let refDict = null;
+  const fetched = [];
+  for (const locale of TRANSLATION_LANGUAGES) {
+    try {
+      const dict = await fetchJson(`${versionBase}/${locale}/translation.json`);
+      writeFileSync2(join3(cacheDir, `${locale}.json`), JSON.stringify(dict, null, 2));
+      fetched.push(locale);
+      if (locale === options.ref) refDict = dict;
+      console.log(pc3.green(`  \u2713 ${locale} (${Object.keys(dict).length})`));
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(pc3.yellow(`  - ${locale}: ${msg} \u2014 \uAC74\uB108\uB700`));
+    }
+  }
+  if (fetched.length === 0) {
+    console.error(pc3.red("[bstage] \uBC1B\uC740 \uBC88\uC5ED\uC774 \uC5C6\uC2B5\uB2C8\uB2E4."));
+    process.exit(1);
+  }
+  if (!refDict) {
+    console.warn(
+      pc3.yellow(`[bstage] ref \uB85C\uCF00\uC77C(${options.ref}) \uC0AC\uC804\uC774 \uC5C6\uC5B4 \uD0C0\uC785 \uC0DD\uC131\uC744 \uAC74\uB108\uB701\uB2C8\uB2E4.`)
+    );
+    return;
+  }
+  const outPath = resolve3(root, options.out);
+  mkdirSync2(dirname(outPath), { recursive: true });
+  writeFileSync2(outPath, generateTypeModule(refDict, { version: latest.version, ref: options.ref }));
+  console.log(pc3.green(`[bstage] \uD0C0\uC785 \uC0DD\uC131: ${options.out} (${Object.keys(refDict).length} \uD0A4)`));
+  console.log(
+    pc3.dim(
+      `  \uCE90\uC2DC: .bstage/i18n/${target}/*.json \u2014 \uD0C0\uC785 \uC0DD\uC131 \uC785\uB825 + \uC6D0\uBB38 \uAC80\uC0C9\uC6A9(\uB7F0\uD0C0\uC784\uC740 CDN\uC5D0\uC11C \uC9C1\uC811 \uBC1B\uB294\uB2E4)`
+    )
+  );
+  console.log(pc3.dim("  \uC0DD\uC131 \uD30C\uC77C\uC744 \uD55C \uBC88 import\uD558\uBA74 useBstageTranslations().t() \uD0A4\uAC00 \uC881\uD600\uC9D1\uB2C8\uB2E4."));
+}
+
+// src/commands/doctor.ts
+import { existsSync as existsSync3 } from "fs";
+import { readFile as readFile2, readdir as readdir2 } from "fs/promises";
+import { dirname as dirname2, join as join5 } from "path";
+import { fileURLToPath } from "url";
+import pc5 from "picocolors";
+
+// src/commands/skills.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync, writeFileSync as writeFileSync3 } from "fs";
+import { join as join4 } from "path";
+import pc4 from "picocolors";
+async function skillsInstallCommand(options) {
+  const root = process.cwd();
+  const baseDir = options.dir || ".claude/skills";
+  const target = resolveProjectTarget(root);
+  console.log(pc4.cyan(`[bstage] \uC2A4\uD0AC \uC124\uCE58: ${baseDir}/`) + pc4.dim(` (\uB514\uC790\uC778 \uD0C0\uAE43: ${target})`));
+  console.log(
+    pc4.dim(
+      "  SDK\uAC00 \uC18C\uC720\uD558\uB294 \uC790\uC0B0\uC785\uB2C8\uB2E4. \uAC19\uC740 \uC774\uB984\uC758 \uAE30\uC874 SKILL.md\uB294 \uB36E\uC5B4\uC4F0\uC5EC \uCD5C\uC2E0\uC73C\uB85C \uB3D9\uAE30\uD654\uB429\uB2C8\uB2E4."
+    )
+  );
+  for (const skill of BSTAGE_SKILLS) {
+    const dir = join4(root, baseDir, skill.name);
+    mkdirSync3(dir, { recursive: true });
+    const file = join4(dir, "SKILL.md");
+    const action = existsSync2(file) ? "\uAC31\uC2E0" : "\uC0DD\uC131";
+    writeFileSync3(file, skill.content(target), "utf-8");
+    console.log(pc4.green(`  \u2713 ${skill.name} (${action})`));
+  }
+  console.log(
+    pc4.dim(
+      `  ${BSTAGE_SKILLS.length}\uAC1C \uC2A4\uD0AC \uC124\uCE58 \uC644\uB8CC. Claude Code\uAC00 ${baseDir}/ \uC758 \uC2A4\uD0AC\uC744 \uC790\uB3D9 \uC778\uC2DD\uD569\uB2C8\uB2E4.`
+    )
+  );
+  syncAgentsMd(root, target);
+  installGuardHook(root);
+}
+function syncAgentsMd(root, target) {
+  const file = join4(root, "AGENTS.md");
+  if (!existsSync2(file)) {
+    console.log(pc4.dim("  \xB7 AGENTS.md \uC5C6\uC74C \u2014 `bstage init` \uB610\uB294 \uB9C8\uC774\uADF8\uB808\uC774\uC158\uC73C\uB85C \uC0DD\uC131\uD558\uC138\uC694."));
+    return;
+  }
+  const content = readFileSync(file, "utf-8");
+  const status = agentsMdStatus(content);
+  if (status === "legacy") {
+    console.log(
+      pc4.yellow("  ! AGENTS.md\uAC00 \uB808\uAC70\uC2DC \uD3EC\uB9F7\uC785\uB2C8\uB2E4(\uAD00\uB9AC \uC601\uC5ED \uB9C8\uCEE4 \uC5C6\uC74C).") + pc4.dim(" `bstage-migrate` \uC2A4\uD0AC\uB85C reconcile\uD558\uC138\uC694 \u2014 skills install\uC740 \uAC74\uB4DC\uB9AC\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.")
+    );
+    return;
+  }
+  const parsed = parseAgentsIdentity(content);
+  const projectName = parsed.projectName ?? readPkgName(root) ?? "custom-templates";
+  const space = parsed.space ?? projectName.split("-custom-templates-")[0] ?? projectName;
+  const swapped = swapManagedBlock(content, renderManagedBlock({ space, projectName, target }));
+  if (swapped === null) {
+    console.log(pc4.dim("  \xB7 AGENTS.md \uAD00\uB9AC \uC601\uC5ED\uC744 \uCC3E\uC9C0 \uBABB\uD574 \uAC74\uB108\uB701\uB2C8\uB2E4."));
+    return;
+  }
+  if (swapped === content) {
+    console.log(pc4.green("  \u2713 AGENTS.md (\uAD00\uB9AC \uC601\uC5ED \uCD5C\uC2E0)"));
+    return;
+  }
+  writeFileSync3(file, swapped, "utf-8");
+  console.log(pc4.green("  \u2713 AGENTS.md (\uAD00\uB9AC \uC601\uC5ED \uAC31\uC2E0, \uC790\uC720 \uC601\uC5ED \uBCF4\uC874)"));
+}
+function installGuardHook(root) {
+  const pkgPath = join4(root, "package.json");
+  if (!existsSync2(pkgPath)) {
+    console.log(pc4.dim("  \xB7 package.json \uC5C6\uC74C \u2014 pre-commit \uAC00\uB4DC \uC124\uCE58\uB97C \uAC74\uB108\uB701\uB2C8\uB2E4."));
+    return;
+  }
+  let pkgChanged = false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    pkg.devDependencies ?? (pkg.devDependencies = {});
+    pkg.scripts ?? (pkg.scripts = {});
+    if (!pkg.devDependencies.husky) {
+      pkg.devDependencies.husky = "^9.1.7";
+      pkgChanged = true;
+    }
+    if (!pkg.scripts.prepare) {
+      pkg.scripts.prepare = "husky";
+      pkgChanged = true;
+    } else if (!pkg.scripts.prepare.includes("husky")) {
+      pkg.scripts.prepare = `${pkg.scripts.prepare} && husky`;
+      pkgChanged = true;
+    }
+    if (pkgChanged) {
+      writeFileSync3(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+    }
+  } catch {
+    console.log(pc4.yellow("  ! package.json \uD30C\uC2F1 \uC2E4\uD328 \u2014 pre-commit \uAC00\uB4DC \uC124\uCE58\uB97C \uAC74\uB108\uB701\uB2C8\uB2E4."));
+    return;
+  }
+  const huskyDir = join4(root, ".husky");
+  mkdirSync3(huskyDir, { recursive: true });
+  const scriptFile = join4(huskyDir, "check-secrets.mjs");
+  const scriptExisted = existsSync2(scriptFile);
+  writeFileSync3(scriptFile, checkSecretsScript(), "utf-8");
+  console.log(pc4.green(`  \u2713 .husky/check-secrets.mjs (${scriptExisted ? "\uAC31\uC2E0" : "\uC0DD\uC131"})`));
+  const hookFile = join4(huskyDir, "pre-commit");
+  const body = huskyPreCommit();
+  if (!existsSync2(hookFile)) {
+    writeFileSync3(hookFile, body, "utf-8");
+    console.log(pc4.green("  \u2713 .husky/pre-commit (\uC0DD\uC131)"));
+  } else {
+    const cur = readFileSync(hookFile, "utf-8");
+    if (cur.includes("check-secrets.mjs")) {
+      console.log(pc4.green("  \u2713 .husky/pre-commit (\uAC00\uB4DC \uC874\uC7AC)"));
+    } else {
+      const sep = cur.endsWith("\n") ? "" : "\n";
+      writeFileSync3(hookFile, cur + sep + body, "utf-8");
+      console.log(pc4.green("  \u2713 .husky/pre-commit (\uAC00\uB4DC \uB77C\uC778 \uCD94\uAC00)"));
+    }
+  }
+  if (pkgChanged) {
+    console.log(
+      pc4.dim("  \xB7 husky\uB97C package.json\uC5D0 \uCD94\uAC00\uD588\uC2B5\uB2C8\uB2E4 \u2014 install \uD6C4 pre-commit \uD6C5\uC774 \uD65C\uC131\uD654\uB429\uB2C8\uB2E4.")
+    );
+  }
+}
+function readPkgName(root) {
+  try {
+    return JSON.parse(readFileSync(join4(root, "package.json"), "utf-8")).name ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// src/commands/doctor.ts
+var SDK_PACKAGES = [
+  "@bstage-sdk/cli",
+  "@bstage-sdk/core",
+  "@bstage-sdk/react",
+  "@bstage-sdk/design"
+];
+var RECOMMENDED_DEPS = [
+  {
+    pkg: "@bstage-sdk/design",
+    note: "bstage \uB514\uC790\uC778 \uD1A0\uD070 (\uC0C9\xB7\uD0C0\uC774\uD3EC\xB7\uADF8\uB9BC\uC790)",
+    why: "\uC5C6\uC73C\uBA74 \uC5D0\uC774\uC804\uD2B8\uAC00 hex/rgb\uB97C \uD558\uB4DC\uCF54\uB529\uD574 \uD50C\uB7AB\uD3FC \uD14C\uB9C8\xB7\uB2E4\uD06C\uBAA8\uB4DC\uC640 \uC5B4\uAE0B\uB09C\uB2E4"
+  },
+  {
+    pkg: "@types/node",
+    note: 'vite.config.ts \uD0C0\uC785 (tsconfig.node.json\uC774 `types: ["node"]` \uC120\uC5B8)',
+    why: "\uC5C6\uC73C\uBA74 `npm run typecheck`(tsc -b)\uAC00 TS2688\uB85C \uAE68\uC9C4\uB2E4 \u2014 vite.config.ts\uAC00 process.cwd()\uB97C \uC4F4\uB2E4"
+  }
+];
+var EXPECTED_SCRIPTS = [
+  {
+    name: "typecheck",
+    command: "tsc -b",
+    why: "`bstage build`\uB294 tsc\uB97C \uD0C0\uC9C0 \uC54A\uC544, \uC774 \uC2A4\uD06C\uB9BD\uD2B8\uAC00 \uC5C6\uC73C\uBA74 \uC5C6\uB294 \uBC88\uC5ED \uD0A4\xB7\uD0C0\uC785 \uC624\uB958\uAC00 \uC870\uC6A9\uD788 \uD1B5\uACFC\uD55C\uB2E4"
+  }
+];
+var EXPECTED_FILES = [
+  { path: "tsconfig.app.json", note: "tsconfig \uBD84\uB9AC (app)" },
+  { path: "tsconfig.node.json", note: "tsconfig \uBD84\uB9AC (node)" },
+  { path: "eslint.config.js", note: "ESLint flat config" },
+  { path: "src/vite-env.d.ts", note: "Vite client \uD0C0\uC785" },
+  { path: "src/App.tsx", note: "dev \uD654\uBA74 \uBD84\uB9AC (\uC5C6\uC73C\uBA74 lint \uC2E4\uD328)" }
+];
+async function doctorCommand(options) {
+  const root = process.cwd();
+  const report = await diagnose(root);
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  printReport(report);
+  await autoSyncSkills(report);
+}
+async function autoSyncSkills(report) {
+  if (!report.isBstageProject) return;
+  if (!report.skills.some((s) => s.status !== "ok")) return;
+  await skillsInstallCommand({ dir: ".claude/skills" });
+}
+async function diagnose(root) {
+  let pkgJson = null;
+  try {
+    pkgJson = JSON.parse(await readFile2(join5(root, "package.json"), "utf-8"));
+  } catch {
+  }
+  const deps = {
+    ...pkgJson?.dependencies,
+    ...pkgJson?.devDependencies,
+    ...pkgJson?.peerDependencies,
+    ...pkgJson?.optionalDependencies
+  };
+  const isBstageProject = SDK_PACKAGES.some((p2) => p2 in deps);
+  const installed = /* @__PURE__ */ new Map();
+  for (const pkg of SDK_PACKAGES) {
+    installed.set(pkg, await readInstalledVersion(root, pkg) ?? cleanRange(deps[pkg]));
+  }
+  const relevantPackages = SDK_PACKAGES.filter((pkg) => installed.get(pkg) !== null || pkg in deps);
+  const latest = /* @__PURE__ */ new Map();
+  let latestChecked = false;
+  if (isBstageProject) {
+    latestChecked = true;
+    await Promise.all(
+      relevantPackages.map(async (pkg) => {
+        latest.set(pkg, await fetchLatestVersion2(pkg).catch(() => null));
+      })
+    );
+  }
+  const versions = relevantPackages.map((pkg) => {
+    const inst = installed.get(pkg) ?? null;
+    const lat = latest.get(pkg) ?? null;
+    return {
+      pkg,
+      installed: inst,
+      latest: lat,
+      outdated: !!inst && !!lat && compareSemver(inst, lat) < 0
+    };
+  });
+  const files = EXPECTED_FILES.map((f) => ({
+    path: f.path,
+    note: f.note,
+    present: existsSync3(join5(root, f.path))
+  }));
+  const isPnpmProject = existsSync3(join5(root, "pnpm-lock.yaml"));
+  let pnpmWorkspace2 = {
+    relevant: false,
+    allowBuildsDeclared: false,
+    packagesDeclared: false,
+    filePresent: false
+  };
+  if (isPnpmProject) {
+    let yaml = null;
+    try {
+      yaml = await readFile2(join5(root, "pnpm-workspace.yaml"), "utf-8");
+    } catch {
+    }
+    pnpmWorkspace2 = {
+      relevant: true,
+      filePresent: yaml !== null,
+      allowBuildsDeclared: yaml !== null && /^allowBuilds:/m.test(yaml),
+      packagesDeclared: yaml !== null && /^packages:/m.test(yaml)
+    };
+  }
+  const scripts = EXPECTED_SCRIPTS.map((sc) => ({
+    ...sc,
+    expected: sc.command,
+    actual: pkgJson?.scripts?.[sc.name] ?? null
+  }));
+  const recommendedDeps = RECOMMENDED_DEPS.map((d) => ({
+    ...d,
+    declared: d.pkg in deps
+  }));
+  const resolveCache = /* @__PURE__ */ new Map();
+  const migrations = await readApplicableMigrations(async (pkg) => {
+    const cached = resolveCache.get(pkg);
+    if (cached) return cached;
+    const version = installed.get(pkg) ?? await readInstalledVersion(root, pkg) ?? cleanRange(deps[pkg]);
+    const resolved = { version, relevant: version !== null || pkg in deps };
+    resolveCache.set(pkg, resolved);
+    return resolved;
+  });
+  const agentsMd2 = await diagnoseAgentsMd(root, pkgJson?.name ?? null);
+  const skills2 = await diagnoseSkills(root);
+  return {
+    project: pkgJson?.name ?? null,
+    isBstageProject,
+    versions,
+    files,
+    layout: await diagnoseLayout(root),
+    pnpmWorkspace: pnpmWorkspace2,
+    scripts,
+    recommendedDeps,
+    migrations,
+    agentsMd: agentsMd2,
+    skills: skills2,
+    latestChecked
+  };
+}
+async function diagnoseLayout(root) {
+  const legacyRoot = join5(root, "src", "templates");
+  let legacyTemplates = [];
+  let legacyPresent = false;
+  try {
+    const dirents = await readdir2(legacyRoot, { withFileTypes: true });
+    legacyPresent = true;
+    legacyTemplates = dirents.filter((d) => d.isDirectory() && !d.name.startsWith(".")).map((d) => d.name).sort();
+  } catch {
+  }
+  return {
+    legacyPresent,
+    legacyTemplates,
+    pagesPresent: existsSync3(join5(root, "src", "pages")),
+    slotsPresent: existsSync3(join5(root, "src", "slots"))
+  };
+}
+async function diagnoseSkills(root) {
+  const target = resolveProjectTarget(root);
+  return Promise.all(
+    BSTAGE_SKILLS.map(async (skill) => {
+      let installed;
+      try {
+        installed = await readFile2(join5(root, ".claude", "skills", skill.name, "SKILL.md"), "utf-8");
+      } catch {
+        return { name: skill.name, status: "missing" };
+      }
+      return { name: skill.name, status: installed === skill.content(target) ? "ok" : "stale" };
+    })
+  );
+}
+async function diagnoseAgentsMd(root, pkgName) {
+  let content;
+  try {
+    content = await readFile2(join5(root, "AGENTS.md"), "utf-8");
+  } catch {
+    return { status: "missing", managedBlock: null };
+  }
+  const status = agentsMdStatus(content);
+  if (status === "ok") return { status, managedBlock: null };
+  const parsed = parseAgentsIdentity(content);
+  const projectName = parsed.projectName ?? pkgName ?? "custom-templates";
+  const space = parsed.space ?? projectName.split("-custom-templates-")[0] ?? projectName;
+  const target = resolveProjectTarget(root);
+  return { status, managedBlock: renderManagedBlock({ space, projectName, target }) };
+}
+async function readInstalledVersion(root, pkg) {
+  try {
+    const raw = await readFile2(join5(root, "node_modules", pkg, "package.json"), "utf-8");
+    const parsed = JSON.parse(raw);
+    return parsed.version ?? null;
+  } catch {
+    return null;
+  }
+}
+async function fetchLatestVersion2(packageName) {
+  const res = await fetch(`https://registry.npmjs.org/${packageName}`, {
+    headers: { Accept: "application/json" }
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const data = await res.json();
+  const latest = data["dist-tags"]?.latest;
+  if (!latest) throw new Error("latest \uC5C6\uC74C");
+  return latest;
+}
+async function readApplicableMigrations(resolve4) {
+  const md = await readBundledMigrationDoc();
+  if (md === null) return [];
+  return selectApplicableMigrations(parseMigrationDoc(md), resolve4);
+}
+function parseMigrationDoc(md) {
+  const lines = md.split("\n");
+  const sectionRe = /^##\s+(?:→\s*)?(.+?)\s*$/;
+  const itemRe = /^###\s+(.+?)\s*$/;
+  const entries = [];
+  let current = null;
+  for (const line of lines) {
+    const sec = sectionRe.exec(line);
+    if (sec) {
+      const requirements = parseMigrationRequirements(sec[1]);
+      current = requirements.length > 0 ? { label: sec[1].trim(), requirements, items: [] } : null;
+      if (current) entries.push(current);
+      continue;
+    }
+    if (current) {
+      const item = itemRe.exec(line);
+      if (item) {
+        current.items.push(item[1].replace(/\s*[—–-]\s*`.*$/, "").trim());
+      }
+    }
+  }
+  return entries;
+}
+async function selectApplicableMigrations(entries, resolve4) {
+  const applicable = [];
+  for (const e of entries) {
+    let applies = false;
+    for (const req of e.requirements) {
+      const { version, relevant } = await resolve4(req.pkg);
+      if (!relevant) continue;
+      if (version === null || compareSemver(version, req.version) < 0) {
+        applies = true;
+        break;
+      }
+    }
+    if (applies) applicable.push(e);
+  }
+  return applicable;
+}
+function parseMigrationRequirements(text2) {
+  const reqs = [];
+  const re = /(?:([a-z][a-z-]*)\s+)?(\d+\.\d+\.\d+)/g;
+  let m;
+  while ((m = re.exec(text2)) !== null) {
+    reqs.push({ pkg: normalizeMigrationPkg(m[1]), version: m[2] });
+  }
+  return reqs;
+}
+function normalizeMigrationPkg(short) {
+  if (!short) return "@bstage-sdk/core";
+  return short.startsWith("@") ? short : `@bstage-sdk/${short}`;
+}
+async function readBundledMigrationDoc() {
+  const here = dirname2(fileURLToPath(import.meta.url));
+  const candidates = [
+    join5(here, "MIGRATION.md"),
+    // 배포물: dist/ 옆 (cli/dist/MIGRATION.md)
+    join5(here, "..", "..", "..", "docs", "MIGRATION.md"),
+    // dev(dist): cli/dist → repo/docs
+    join5(here, "..", "..", "..", "..", "docs", "MIGRATION.md")
+    // dev(src): cli/src/commands → repo/docs
+  ];
+  for (const path of candidates) {
+    try {
+      return await readFile2(path, "utf-8");
+    } catch {
+    }
+  }
+  return null;
+}
+function cleanRange(spec) {
+  if (!spec) return null;
+  const m = /(\d+\.\d+\.\d+)/.exec(spec);
+  return m ? m[1] : null;
+}
+function compareSemver(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10));
+  const pb = b.split(".").map((n) => parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+function printReport(r) {
+  console.log("");
+  console.log(`${pc5.cyan(pc5.bold("bstage doctor"))} ${pc5.dim(`\u2014 ${r.project ?? "(\uC774\uB984 \uC5C6\uC74C)"}`)}`);
+  console.log("");
+  if (!r.isBstageProject) {
+    console.log(pc5.yellow("\uC774 \uB514\uB809\uD1A0\uB9AC\uB294 bstage \uD15C\uD50C\uB9BF \uD504\uB85C\uC81D\uD2B8\uAC00 \uC544\uB2CC \uAC83 \uAC19\uC2B5\uB2C8\uB2E4."));
+    console.log(pc5.dim("  package.json\uC5D0 @bstage-sdk/* \uC758\uC874\uC131\uC774 \uC5C6\uC2B5\uB2C8\uB2E4."));
+    return;
+  }
+  console.log(pc5.bold("\u{1F4E6} SDK \uBC84\uC804"));
+  if (!r.latestChecked) {
+    console.log(pc5.dim("  \uB808\uC9C0\uC2A4\uD2B8\uB9AC \uC870\uD68C\uB97C \uAC74\uB108\uB6F0\uC5B4 \uC124\uCE58 \uBC84\uC804\uB9CC \uD45C\uC2DC\uD569\uB2C8\uB2E4."));
+  }
+  const nameWidth = Math.max(12, ...r.versions.map((v) => v.pkg.replace("@bstage-sdk/", "").length));
+  for (const v of r.versions) {
+    const name = v.pkg.replace("@bstage-sdk/", "").padEnd(nameWidth);
+    const inst = v.installed ?? "?";
+    if (v.latest && v.installed) {
+      const arrow = v.outdated ? pc5.yellow(`\u2192  ${v.latest}  (\uB4A4\uCC98\uC9D0)`) : pc5.green("(\uCD5C\uC2E0)");
+      console.log(`  ${name} ${inst.padEnd(8)} ${arrow}`);
+    } else {
+      console.log(`  ${name} ${inst}`);
+    }
+  }
+  console.log("");
+  console.log(pc5.bold("\u{1F4C1} init \uAE30\uBCF8 \uD30C\uC77C (\uCC38\uACE0)"));
+  const absent = r.files.filter((f) => !f.present);
+  if (absent.length === 0) {
+    console.log(pc5.green("  \u2713 init \uAE30\uBCF8 \uAD6C\uC131\uACFC \uB3D9\uC77C"));
+  } else {
+    console.log(pc5.dim("  init \uAE30\uBCF8\uAC12\uACFC\uC758 \uCC28\uC774\uC77C \uBFD0 \u2014 \uD504\uB85C\uC81D\uD2B8\uAC00 \uB2E4\uB974\uAC8C \uCC98\uB9AC \uC911\uC774\uBA74 \uBB34\uC2DC\uD558\uC138\uC694."));
+    for (const f of r.files) {
+      if (f.present) console.log(`  ${pc5.green("\u2713")} ${f.path}`);
+      else console.log(`  ${pc5.dim("\xB7")} ${f.path.padEnd(20)} ${pc5.dim(`\uC5C6\uC74C (${f.note})`)}`);
+    }
+  }
+  console.log("");
+  console.log(pc5.bold("\u{1F5C2}  \uD15C\uD50C\uB9BF \uB514\uB809\uD1A0\uB9AC"));
+  if (r.layout.legacyPresent) {
+    console.log(`  ${pc5.yellow("\u2192")} ${pc5.yellow("src/templates/ \uAC00 \uB0A8\uC544 \uC788\uC2B5\uB2C8\uB2E4 (\uC61B \uAD6C\uC870)")}`);
+    console.log(pc5.dim("      \uBE4C\uB4DC \uC0B0\uCD9C\uBB3C \uACBD\uB85C\uAC00 \uD3F4\uB354 \uAD6C\uC870\uB97C \uB530\uB77C\uAC00\uB3C4\uB85D \uBC14\uB00C\uC5C8\uC2B5\uB2C8\uB2E4."));
+    console.log(pc5.dim("      \uD398\uC774\uC9C0 \u2192 src/pages/{\uACBD\uB85C}/  \xB7  \uC704\uC82F \u2192 src/slots/{\uC544\uBB34\uC774\uB984}/"));
+    if (r.layout.legacyTemplates.length > 0) {
+      console.log(pc5.dim(`      \uC62E\uACA8\uC57C \uD560 \uD15C\uD50C\uB9BF: ${r.layout.legacyTemplates.join(", ")}`));
+    }
+    console.log(pc5.dim('      \uBCC0\uD658: \uC5D0\uC774\uC804\uD2B8\uC5D0\uAC8C "bstage \uB9C8\uC774\uADF8\uB808\uC774\uC158" \uC694\uCCAD'));
+  } else if (!r.layout.pagesPresent && !r.layout.slotsPresent) {
+    console.log(`  ${pc5.dim("\xB7")} src/pages/ \xB7 src/slots/ \uB458 \uB2E4 \uC5C6\uC74C`);
+  } else {
+    console.log(pc5.green("  \u2713 src/pages/ \xB7 src/slots/ \uAD6C\uC870"));
+  }
+  console.log("");
+  if (r.pnpmWorkspace.relevant) {
+    console.log(pc5.bold("\u{1F4E6} pnpm workspace \uC124\uC815"));
+    if (r.pnpmWorkspace.allowBuildsDeclared) {
+      console.log(pc5.green("  \u2713 pnpm-workspace.yaml\uC5D0 allowBuilds \uC120\uC5B8\uB428"));
+    } else {
+      console.log(`  ${pc5.yellow("\u2192")} ${pc5.yellow("pnpm-workspace.yaml\uC5D0 allowBuilds \uC5C6\uC74C")}`);
+      console.log(
+        pc5.dim("      pnpm\uC740 \uC758\uC874\uC131 build script\uB97C \uAE30\uBCF8 \uCC28\uB2E8\uD558\uACE0, pnpm 11\uC740 \uADF8\uAC83\uC744 \uC5D0\uB7EC\uB85C \uB0B8\uB2E4")
+      );
+      console.log(
+        pc5.dim("      \u2192 `pnpm install`\uC774 ERR_PNPM_IGNORED_BUILDS\uB85C \uC2E4\uD328\uD558\uACE0 `pnpm dev`\uB3C4 \uC8FD\uB294\uB2E4")
+      );
+      console.log(pc5.dim("      \uCD94\uAC00: pnpm-workspace.yaml\uC5D0 `allowBuilds:` + `esbuild: true`"));
+      console.log(pc5.dim("      \uB610\uB294 `pnpm approve-builds`\uB85C \uB300\uD654\uC2DD \uC120\uD0DD"));
+    }
+    if (r.pnpmWorkspace.filePresent && !r.pnpmWorkspace.packagesDeclared) {
+      console.log(`  ${pc5.yellow("\u2192")} ${pc5.yellow("pnpm-workspace.yaml\uC5D0 packages \uC5C6\uC74C")}`);
+      console.log(
+        pc5.dim("      pnpm 9\uB294 \uC774 \uD30C\uC77C\uC774 \uC788\uC73C\uBA74 workspace \uB8E8\uD2B8\uB85C \uBCF4\uACE0 packages\uB97C \uC694\uAD6C\uD55C\uB2E4")
+      );
+      console.log(pc5.dim("      \u2192 pnpm 9\uC5D0\uC11C `ERROR packages field missing or empty`\uB85C \uC8FD\uB294\uB2E4"));
+      console.log(pc5.dim("      \uCD94\uAC00: pnpm-workspace.yaml \uB9E8 \uC704\uC5D0 `packages:` + `- '.'`"));
+    } else if (r.pnpmWorkspace.packagesDeclared) {
+      console.log(pc5.green("  \u2713 pnpm-workspace.yaml\uC5D0 packages \uC120\uC5B8\uB428"));
+    }
+    console.log("");
+  }
+  console.log(pc5.bold("\u{1F6E0}  package.json \uC2A4\uD06C\uB9BD\uD2B8"));
+  const scriptIssues = r.scripts.filter((sc) => sc.actual !== sc.expected);
+  if (scriptIssues.length === 0) {
+    console.log(pc5.green("  \u2713 init \uAE30\uBCF8 \uAD6C\uC131\uACFC \uB3D9\uC77C"));
+  } else {
+    for (const sc of r.scripts) {
+      if (sc.actual === sc.expected) {
+        console.log(`  ${pc5.green("\u2713")} ${sc.name}`);
+        continue;
+      }
+      if (sc.actual === null) {
+        console.log(`  ${pc5.yellow("\u2192")} ${sc.name} ${pc5.yellow("\uC5C6\uC74C")}`);
+      } else {
+        console.log(
+          `  ${pc5.yellow("\u2192")} ${sc.name} ${pc5.yellow("\uB2E4\uB984")} ${pc5.dim(`\u2014 \uD604\uC7AC \`${sc.actual}\``)}`
+        );
+        if (sc.actual.includes("--noEmit") && !sc.actual.includes("-p ")) {
+          console.log(
+            pc5.dim(
+              "      \uC8FC\uC758: solution-style tsconfig\uC5D0\uC11C `tsc --noEmit`\uC740 \uC544\uBB34 \uD30C\uC77C\uB3C4 \uAC80\uC0AC\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4."
+            )
+          );
+        }
+      }
+      console.log(pc5.dim(`      ${sc.why}`));
+      console.log(pc5.dim(`      \uAD8C\uC7A5: "${sc.name}": "${sc.expected}"`));
+    }
+  }
+  console.log("");
+  console.log(pc5.bold("\u{1F9F1} \uAD8C\uC7A5 \uC758\uC874\uC131"));
+  if (r.recommendedDeps.every((d) => d.declared)) {
+    console.log(pc5.green("  \u2713 \uBAA8\uB450 \uC120\uC5B8\uB428"));
+  } else {
+    for (const d of r.recommendedDeps) {
+      if (d.declared) {
+        console.log(`  ${pc5.green("\u2713")} ${d.pkg}`);
+        continue;
+      }
+      console.log(`  ${pc5.yellow("\u2192")} ${d.pkg} ${pc5.yellow("\uBBF8\uC120\uC5B8")} ${pc5.dim(`\u2014 ${d.note}`)}`);
+      console.log(pc5.dim(`      ${d.why}`));
+      console.log(pc5.dim(`      \uCD94\uAC00: npm i ${d.pkg} (\uD504\uB85C\uC81D\uD2B8 \uD328\uD0A4\uC9C0 \uB9E4\uB2C8\uC800\uB85C)`));
+    }
+  }
+  console.log("");
+  console.log(pc5.bold("\u{1F4D6} \uC801\uC6A9 \uAC00\uB2A5\uD55C \uB9C8\uC774\uADF8\uB808\uC774\uC158"));
+  if (r.migrations.length === 0) {
+    console.log(pc5.dim("  \uD574\uB2F9 \uD56D\uBAA9 \uC5C6\uC74C."));
+  } else {
+    for (const m of r.migrations) {
+      console.log(`  ${pc5.cyan(`\u2192 ${m.label}`)}`);
+      for (const item of m.items) console.log(`    \u2022 ${item}`);
+    }
+  }
+  console.log("");
+  console.log(pc5.bold("\u{1F4DD} AGENTS.md"));
+  switch (r.agentsMd.status) {
+    case "ok":
+      console.log(pc5.green("  \u2713 \uAD00\uB9AC \uC601\uC5ED \uCD5C\uC2E0"));
+      break;
+    case "missing":
+      console.log(pc5.dim("  \xB7 \uD30C\uC77C \uC5C6\uC74C \u2014 bstage \uD504\uB85C\uC81D\uD2B8\uB77C\uBA74 init/\uB9C8\uC774\uADF8\uB808\uC774\uC158\uC73C\uB85C \uC0DD\uC131\uD558\uC138\uC694."));
+      break;
+    case "stale":
+      console.log(
+        pc5.yellow("  \u2192 \uAD00\uB9AC \uC601\uC5ED\uC774 \uC624\uB798\uB428") + pc5.dim(" \u2014 `bstage skills install`\uB85C \uAC31\uC2E0(\uC790\uC720 \uC601\uC5ED\uC740 \uBCF4\uC874).")
+      );
+      break;
+    case "legacy":
+      console.log(
+        pc5.yellow("  \u2192 \uB808\uAC70\uC2DC \uD3EC\uB9F7(\uAD00\uB9AC \uC601\uC5ED \uB9C8\uCEE4 \uC5C6\uC74C)") + pc5.dim(
+          " \u2014 `bstage skills install`\uB85C \uC2A4\uD0AC\uC744 \uBA3C\uC800 \uC124\uCE58\uD55C \uB4A4, `bstage-migrate` \uC2A4\uD0AC\uB85C reconcile(SDK \uC601\uC5ED \uAD50\uCCB4 + \uC0AC\uC6A9\uC790 \uB0B4\uC6A9 \uBCF4\uC874)."
+        )
+      );
+      break;
+  }
+  console.log("");
+  console.log(pc5.bold("\u{1F9E9} \uC5D0\uC774\uC804\uD2B8 \uC2A4\uD0AC (.claude/skills/)"));
+  const skillsNeedWork = r.skills.filter((s) => s.status !== "ok");
+  if (skillsNeedWork.length === 0) {
+    console.log(pc5.green("  \u2713 \uBAA8\uB4E0 \uC2A4\uD0AC \uCD5C\uC2E0"));
+  } else {
+    for (const s of r.skills) {
+      if (s.status === "ok") console.log(`  ${pc5.green("\u2713")} ${s.name}`);
+      else if (s.status === "missing")
+        console.log(`  ${pc5.yellow("\u2192")} ${s.name.padEnd(16)} ${pc5.yellow("\uBBF8\uC124\uCE58")}`);
+      else console.log(`  ${pc5.yellow("\u2192")} ${s.name.padEnd(16)} ${pc5.yellow("\uAD6C\uBC84\uC804/\uC218\uC815\uB428")}`);
+    }
+    console.log(
+      pc5.dim(
+        "  \uC544\uB798\uC5D0\uC11C \uC790\uB3D9 \uB3D9\uAE30\uD654\uD569\uB2C8\uB2E4 \u2014 bstage-* \uC2A4\uD0AC\uB9CC \uB36E\uC5B4\uC4F0\uBA70, \uADF8 \uC678 \uC0AC\uC6A9\uC790 \uC2A4\uD0AC\uC740 \uAC74\uB4DC\uB9AC\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4."
+      )
+    );
+  }
+  console.log("");
+  const agentsNeedsWork = r.agentsMd.status === "legacy" || r.agentsMd.status === "stale";
+  const hasWork = r.versions.some((v) => v.outdated) || r.migrations.length > 0 || agentsNeedsWork;
+  if (hasWork) {
+    console.log(
+      pc5.dim(
+        "\uB2E4\uC74C \uB2E8\uACC4: \uB9C8\uC774\uADF8\uB808\uC774\uC158 \uC2A4\uD0AC\uC744 \uC2E4\uD589\uD574 \uC704 \uD56D\uBAA9\uC744 \uD504\uB85C\uC81D\uD2B8\uC5D0 \uB9DE\uCDB0 \uC801\uC6A9\uD558\uC138\uC694.\n  \uC0C1\uC138 \uAC00\uC774\uB4DC: SDK \uBB38\uC11C\uC758 MIGRATION.md (\uC704 \uD56D\uBAA9\uBCC4 \uC801\uC6A9 \uC808\uCC28)"
+      )
+    );
+  } else {
+    console.log(pc5.green("\u2713 \uCD5C\uC2E0 \uC0C1\uD0DC\uC785\uB2C8\uB2E4. \uB9C8\uC774\uADF8\uB808\uC774\uC158\uC774 \uD544\uC694 \uC5C6\uC2B5\uB2C8\uB2E4."));
+    if (absent.length > 0) {
+      console.log(pc5.dim("  (\uC704 init \uAE30\uBCF8 \uD30C\uC77C \uCC28\uC774\uB294 \uC120\uD0DD \uC0AC\uD56D\uC785\uB2C8\uB2E4.)"));
+    }
+    if (r.recommendedDeps.some((d) => !d.declared)) {
+      console.log(pc5.dim("  (\uC704 \uAD8C\uC7A5 \uC758\uC874\uC131\uC740 \uBC84\uC804\uACFC \uBB34\uAD00\uD569\uB2C8\uB2E4 \u2014 \uC4F8 \uAC70\uBA74 \uB530\uB85C \uCD94\uAC00\uD558\uC138\uC694.)"));
+    }
+  }
+  console.log("");
+}
+
+// src/commands/docs.ts
+import { existsSync as existsSync4, readdirSync } from "fs";
+import { join as join6 } from "path";
+import pc6 from "picocolors";
+var DOC_ORDER = [
+  ["GETTING_STARTED.md", "\uBE60\uB978 \uC2DC\uC791 \uAC00\uC774\uB4DC"],
+  ["API_REFERENCE.md", "createTemplate, hooks, BstageClient, PlatformBridge API"],
+  ["I18N.md", "\uB2E4\uAD6D\uC5B4 \uD6C5 + bstage i18n pull (\uBC88\uC5ED \uCF54\uB4DC\uC820) \uC6CC\uD06C\uD50C\uB85C"],
+  ["DESIGN_TOKENS.md", "\uB514\uC790\uC778 \uD1A0\uD070 (\uC0C9\xB7\uD0C0\uC774\uD3EC\xB7\uADF8\uB9BC\uC790) \uC0AC\uC6A9 \uAC00\uC774\uB4DC (user/admin)"],
+  ["SLOT_PROTOCOL.md", "\uC2AC\uB86F \uC2DC\uC2A4\uD15C v1 \uD504\uB85C\uD1A0\uCF5C (3-part \uD0A4\xB7context \uB2E8\uBC29\uD5A5)"],
+  ["SLOT_CATALOG_V2.md", "v2 \uC2AC\uB86F \uCE74\uD0C8\uB85C\uADF8 (\uD0A4\xB7anchor\xB7context \uACC4\uC57D)"],
+  ["SLOT_CATALOG.md", "\uC2AC\uB86F \uBAA9\uB85D, \uC774\uBCA4\uD2B8 \uC778\uD130\uD398\uC774\uC2A4, resourceId \uC758\uBBF8"],
+  ["SLOT_SYSTEM.md", "\uC2AC\uB86F \uC2DC\uC2A4\uD15C \uC124\uACC4, \uB7F0\uD0C0\uC784 \uD750\uB984"],
+  ["BUILD_SYSTEM.md", "\uBE4C\uB4DC \uD30C\uC774\uD504\uB77C\uC778, \uC0B0\uCD9C\uBB3C \uACBD\uB85C \uADDC\uCE59"],
+  ["DEV_SERVER.md", "\uB85C\uCEEC \uAC1C\uBC1C \uC11C\uBC84, \uC778\uC99D \uD504\uB85D\uC2DC"],
+  ["INIT.md", "bstage init \uBA85\uB839 \uC0C1\uC138"],
+  ["MIGRATION.md", "\uBC84\uC804 \uC0AC\uC774 \uB9C8\uC774\uADF8\uB808\uC774\uC158 \uAC00\uC774\uB4DC (bstage doctor \uC5F0\uACC4)"],
+  ["SDK_ARCHITECTURE.md", "\uD328\uD0A4\uC9C0 \uAD6C\uC870, \uC124\uACC4 \uACB0\uC815"]
+];
+async function docsCommand() {
+  const docsDir = join6(process.cwd(), "node_modules", "@bstage-sdk", "core", "docs");
+  if (!existsSync4(docsDir)) {
+    console.log(pc6.yellow("SDK \uBB38\uC11C\uB97C \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4."));
+    console.log(pc6.dim("  @bstage-sdk/core\uAC00 \uC124\uCE58\uB418\uC5B4 \uC788\uB294\uC9C0 \uD655\uC778\uD558\uC138\uC694 (npm install \uD6C4 \uC7AC\uC2DC\uB3C4)."));
+    return;
+  }
+  const present = new Set(readdirSync(docsDir).filter((f) => f.endsWith(".md")));
+  const ordered = DOC_ORDER.filter(([f]) => present.has(f));
+  const known = new Set(DOC_ORDER.map(([f]) => f));
+  const extras = [...present].filter((f) => !known.has(f)).sort();
+  console.log("");
+  console.log(pc6.bold("bstage SDK \uBB38\uC11C"));
+  console.log(pc6.dim(`  ${docsDir}`));
+  console.log("");
+  for (const [file, desc] of ordered) {
+    console.log(`  ${pc6.cyan(file.padEnd(22))} ${pc6.dim(desc)}`);
+  }
+  for (const file of extras) {
+    console.log(`  ${pc6.cyan(file.padEnd(22))}`);
+  }
+  console.log("");
+  console.log(
+    pc6.dim("\uD30C\uC77C\uC744 \uC5F4\uC5B4 \uC0C1\uC138 \uB0B4\uC6A9\uC744 \uD655\uC778\uD558\uC138\uC694. \uCEE4\uB9E8\uB4DC \uB3C4\uC6C0\uB9D0\uC740 `bstage <command> --help`.")
+  );
+  console.log("");
+}
+
+// src/index.ts
+function readVersion() {
+  try {
+    const here = dirname3(fileURLToPath2(import.meta.url));
+    return JSON.parse(readFileSync2(join7(here, "..", "package.json"), "utf-8")).version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+var program = new Command().name("bstage").description("b.stage \uC11C\uB4DC\uD30C\uD2F0 \uD15C\uD50C\uB9BF SDK CLI \u2014 \uD15C\uD50C\uB9BF \uAC1C\uBC1C\xB7\uBE4C\uB4DC\xB7\uB85C\uCEEC \uC11C\uBC84\xB7\uB9C8\uC774\uADF8\uB808\uC774\uC158").version(readVersion(), "-v, --version", "\uBC84\uC804 \uCD9C\uB825");
+program.command("init").description("\uC0C8 bstage \uD15C\uD50C\uB9BF \uD504\uB85C\uC81D\uD2B8 \uC0DD\uC131").option("-y, --yes", "\uAE30\uBCF8\uAC12\uC73C\uB85C \uBE44\uC778\uD130\uB799\uD2F0\uBE0C \uC2E4\uD589").option("--space <space>", "Space \uC774\uB984").option("--target <target>", "\uC2A4\uCE90\uD3F4\uB4DC \uB300\uC0C1 (user, admin)", "user").option("--template <template>", "\uCCAB \uBC88\uC9F8 \uD15C\uD50C\uB9BF \uC774\uB984 (\uAE30\uBCF8: {space}-hello)").option("--phase <phase>", "\uBC30\uD3EC \uD658\uACBD (dev, qa, real, sandbox)", "sandbox").option("--pm <pm>", "\uD328\uD0A4\uC9C0 \uB9E4\uB2C8\uC800 (npm, pnpm)", "npm").action(initCommand);
+program.command("build").description("\uD15C\uD50C\uB9BF\uC744 IIFE \uBC88\uB4E4\uB85C \uBE4C\uB4DC (\uD398\uC774\uC9C0\uB294 \uACBD\uB85C\uBCC4, \uC704\uC82F\uC740 \uC2AC\uB86F\uBCC4 \uB514\uB809\uD1A0\uB9AC)").action(buildCommand);
+program.command("docs").description("\uC124\uCE58\uB41C SDK \uBB38\uC11C \uBAA9\uB85D\xB7\uACBD\uB85C \uCD9C\uB825").action(docsCommand);
+program.command("doctor").description("SDK \uBC84\uC804\xB7\uBCF4\uC77C\uB7EC\uD50C\uB808\uC774\uD2B8 \uB4DC\uB9AC\uD504\uD2B8 \uC9C4\uB2E8 (\uAC10\uC9C0\uB9CC, \uD30C\uC77C \uC218\uC815 \uC5C6\uC74C)").option("--json", "\uAD6C\uC870\uD654 \uCD9C\uB825 (\uC2A4\uD0AC\xB7CI\uC6A9)").action(doctorCommand);
+program.command("dev").description("\uC778\uC99D \uD504\uB85D\uC2DC \uD3EC\uD568 \uB85C\uCEEC \uAC1C\uBC1C \uC11C\uBC84 \uC2E4\uD589").option("-p, --port <port>", "Dev server port", "5173").option(
+  "--phase <phase>",
+  "Target phase (dev, qa, real, sandbox). \uC0DD\uB7B5 \uC2DC .env\uC758 VITE_BSTAGE_PHASE, \uADF8\uAC83\uB3C4 \uC5C6\uC73C\uBA74 sandbox"
+).action(devCommand);
+var skills = program.command("skills").description("\uC5D0\uC774\uC804\uD2B8\uC6A9 \uC2A4\uD0AC \uC720\uD2F8");
+skills.command("install").description("\uC5D0\uC774\uC804\uD2B8\uC6A9 \uC2A4\uD0AC\uC744 .claude/skills/\uC5D0 \uC124\uCE58\xB7\uB3D9\uAE30\uD654 (\uAE30\uC874 \uD504\uB85C\uC81D\uD2B8\uC6A9)").option("--dir <dir>", "\uC124\uCE58 \uC704\uCE58", ".claude/skills").action(skillsInstallCommand);
+var i18n = program.command("i18n").description("\uB2E4\uAD6D\uC5B4(\uBC88\uC5ED) \uC720\uD2F8");
+i18n.command("pull").description("\uD50C\uB7AB\uD3FC \uBC88\uC5ED \uC0AC\uC804\uC744 CDN\uC5D0\uC11C \uBC1B\uC544 \uD0C0\uC785 \uC0DD\uC131 + \uB85C\uCEEC \uCE90\uC2DC").option("--phase <phase>", "\uB300\uC0C1 phase (real, qa, dev)", "real").option("--target <target>", "\uBC88\uC5ED \uC2DC\uC2A4\uD15C (user, admin)", "user").option("--tier <tier>", "\uBC88\uC5ED tier (inhouse, mnetplus, hiand)", "inhouse").option("--ref <locale>", "\uD0C0\uC785 \uC6D0\uBB38 \uAE30\uC900 \uB85C\uCF00\uC77C", "ko").option("--out <file>", "\uC0DD\uC131 \uD0C0\uC785 \uD30C\uC77C \uACBD\uB85C", "src/bstage-i18n.ts").action(i18nPullCommand);
+program.addHelpText(
+  "after",
+  `
+\uC608\uC2DC:
+  $ bstage init                  \uC0C8 \uD15C\uD50C\uB9BF \uD504\uB85C\uC81D\uD2B8 \uC0DD\uC131
+  $ bstage dev                   \uB85C\uCEEC \uAC1C\uBC1C \uC11C\uBC84 (\uC778\uC99D \uD504\uB85D\uC2DC)
+  $ bstage build                 IIFE \uBC88\uB4E4 \uBE4C\uB4DC (dist/{\uACBD\uB85C} \xB7 dist/{\uC2AC\uB86F})
+  $ bstage doctor                SDK \uBC84\uC804\xB7\uB4DC\uB9AC\uD504\uD2B8 \uC9C4\uB2E8
+  $ bstage skills install        \uC5D0\uC774\uC804\uD2B8 \uC2A4\uD0AC \uC124\uCE58/\uB3D9\uAE30\uD654
+  $ bstage i18n pull             \uD50C\uB7AB\uD3FC \uBC88\uC5ED \uBC1B\uAE30 + \uD0C0\uC785 \uC0DD\uC131
+
+\uBB38\uC11C:
+  $ bstage docs                  \uC124\uCE58\uB41C SDK \uBB38\uC11C \uBAA9\uB85D\xB7\uACBD\uB85C
+  \uCEE4\uB9E8\uB4DC\uBCC4 \uC0C1\uC138\uB294 \`bstage <command> --help\``
+);
+program.parse();