@bstage-sdk/ai-toolkit 0.6.0 → 0.6.2

package/dist/index.cjs

@@ -31,6 +31,7 @@ __export(index_exports, {
   designGuideSection: () => designGuideSection,
   designMeta: () => meta,
   designRulesBrief: () => designRulesBrief,
+  extractManagedBlock: () => extractManagedBlock,
   freeRegionScaffold: () => freeRegionScaffold,
   parseAgentsIdentity: () => parseAgentsIdentity,
   planInstall: () => planInstall,
@@ -48,7 +49,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.ts
-var VERSION = "0.6.0";
+var VERSION = "0.6.2";
 
 // src/skills/deploy.ts
 function deploySkillMd() {
@@ -738,6 +739,7 @@ ${designGuideSection(target)}
 - **\`__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.
+- **\uD398\uC774\uC9C0 \uD3F4\uB354 \`user\`\xB7\`admin\`\uC740 \uC608\uC57D\uC774\uB2E4**: \uC774 \uB808\uD3EC\uC5D0 liquid \uD15C\uD50C\uB9BF(\`public/{user|admin}/{\uC774\uB984}/template.liquid\`)\uC774 \uD568\uAED8 \uC788\uC73C\uBA74 \`src/pages/user/\u2026\`\xB7\`src/pages/admin/\u2026\` \uC740 \uB9CC\uB4E4 \uC218 \uC5C6\uB2E4(\uB300\uC18C\uBB38\uC790 \uBB34\uC2DC). \uD398\uC774\uC9C0 \uC0B0\uCD9C\uBB3C\uC774 \`dist/{\uD3F4\uB354 \uACBD\uB85C}/\` \uB85C \uB098\uAC00 liquid \uC790\uB9AC\uC640 \uAC19\uC740 \uD2B8\uB9AC\uC5D0 \uB193\uC774\uACE0, \uD55C \uB514\uB809\uD130\uB9AC\uC5D0 \uB450 \uC885\uB958\uAC00 \uB193\uC774\uBA74 \uD3EC\uD138\uC774 sdk\uB85C\uB9CC \uD310\uC815\uD574 liquid\uAC00 \uC870\uC6A9\uD788 \uC0AC\uB77C\uC9C4\uB2E4. \`bstage build\` \uC640 \uD3EC\uD138 \uBE4C\uB4DC\uAC00 \uC885\uB8CC \uCF54\uB4DC 2\uB85C \uB9C9\uB294\uB2E4. \uC704\uC82F(\`src/slots\`)\uC740 \uC2AC\uB86F id\uB85C \uB098\uAC00\uBBC0\uB85C \uD574\uB2F9 \uC5C6\uB2E4. liquid \uD15C\uD50C\uB9BF\uC774 \uC5C6\uB294 \uB808\uD3EC\uC5D0\uC11C\uB294 \uC81C\uC57D\uC774 \uC5C6\uC9C0\uB9CC, \uB098\uC911\uC5D0 \uCD94\uAC00\uD558\uBA74 \uADF8\uB54C \uB9C9\uD788\uBBC0\uB85C \uCC98\uC74C\uBD80\uD130 \uB2E4\uB978 \uC774\uB984\uC744 \uC4F4\uB2E4.
 
 # \uD558\uC9C0 \uB9D0 \uAC83
 
@@ -745,6 +747,7 @@ ${designGuideSection(target)}
 - \`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
+- liquid \uD15C\uD50C\uB9BF\uC774 \uD568\uAED8 \uC788\uB294 \uB808\uD3EC\uC5D0\uC11C \`src/pages/user\`\xB7\`src/pages/admin\` \uB9CC\uB4E4\uAE30 \u2014 liquid \uC0B0\uCD9C\uBB3C \uC790\uB9AC\uC640 \uACB9\uCE5C\uB2E4(\uC704 \uD568\uC815)
 - \uC2DC\uADF8\uB2C8\uCC98\uB97C \uAE30\uC5B5\uC5D0 \uC758\uC874\uD574 \uCD94\uCE21 \u2014 \uC704 docs/.d.ts\uC5D0\uC11C \uD655\uC778
 `;
 }
@@ -834,6 +837,12 @@ function agentsMdStatus(content) {
   if (v === null) return "legacy";
   return v < AGENTS_MANAGED_VERSION ? "stale" : "ok";
 }
+function extractManagedBlock(content) {
+  const s = findMarker(content, START_TOKEN);
+  const e = findMarker(content, END_TOKEN);
+  if (!s || !e || e.end <= s.start) return null;
+  return content.slice(s.start, e.end);
+}
 function swapManagedBlock(existing, newWrappedBlock) {
   const s = findMarker(existing, START_TOKEN);
   const e = findMarker(existing, END_TOKEN);
@@ -1195,6 +1204,8 @@ var CLAUDE_FILE = "CLAUDE.md";
 var LEGACY_NOTE = "\uAD00\uB9AC \uC601\uC5ED \uB9C8\uCEE4 \uC5C6\uC74C \u2014 bstage-migrate \uC2A4\uD0AC\uB85C reconcile";
 var HAND_EDIT_NOTE = "\uBC84\uC804\uC740 \uAC19\uC740\uB370 \uBCF8\uBB38\uC774 \uB2E4\uB985\uB2C8\uB2E4(\uC190\uC218\uC815) \u2014 SDK \uBCF8\uBB38\uC73C\uB85C \uB418\uB3CC\uB9AC\uACE0 \uAE30\uC874 \uBCF8\uBB38\uC740 SKILL.md.bak \uC73C\uB85C \uB0A8\uAE41\uB2C8\uB2E4. \uD504\uB85C\uC81D\uD2B8 \uACE0\uC720 \uADDC\uCE59\uC740 AGENTS.md \uC790\uC720 \uC601\uC5ED\uC5D0 \uC801\uC73C\uC138\uC694.";
 var NEWER_NOTE = "\uC124\uCE58\uBCF8\uC774 \uC774 toolkit\uBCF4\uB2E4 \uC0C8 \uBC84\uC804\uC785\uB2C8\uB2E4 \u2014 \uC774 CLI\uAC00 \uC624\uB798\uB3FC \uC61B \uBCF8\uBB38\uC73C\uB85C \uB418\uB3CC\uB9BD\uB2C8\uB2E4(\uD558\uD5A5). \uCD5C\uC2E0 CLI(npx @bstage-sdk/cli@latest ai update)\uB85C \uB2E4\uC2DC \uC2E4\uD589\uD558\uC138\uC694.";
+var KIND_DRIFT_NOTE = "\uAD00\uB9AC \uC601\uC5ED \uBC84\uC804\uC740 \uCD5C\uC2E0\uC778\uB370 \uBCF8\uBB38\uC774 \uC774 \uD504\uB85C\uC81D\uD2B8 \uC885\uB958\uC758 \uAC83\uACFC \uB2E4\uB985\uB2C8\uB2E4(\uC885\uB958\uAC00 \uBC14\uB00C\uC5C8\uAC70\uB098 \uAD00\uB9AC \uC601\uC5ED\uC744 \uC190\uC73C\uB85C \uACE0\uCE68) \u2014 \uD604\uC7AC \uC885\uB958\uC758 \uBCF8\uBB38\uC73C\uB85C \uAC31\uC2E0\uD569\uB2C8\uB2E4. \uC790\uC720 \uC601\uC5ED\uC740 \uBCF4\uC874\uB429\uB2C8\uB2E4.";
+var AGENTS_NEWER_NOTE = "AGENTS.md \uAD00\uB9AC \uC601\uC5ED\uC774 \uC774 toolkit\uBCF4\uB2E4 \uC0C8 \uBC84\uC804\uC785\uB2C8\uB2E4 \u2014 \uC774 CLI\uAC00 \uC624\uB798\uB3FC \uC61B \uBCF8\uBB38\uC73C\uB85C \uB418\uB3CC\uB9BD\uB2C8\uB2E4(\uD558\uD5A5). \uCD5C\uC2E0 CLI(npx @bstage-sdk/cli@latest ai update)\uB85C \uB2E4\uC2DC \uC2E4\uD589\uD558\uC138\uC694.";
 function planInstall(input) {
   const actions = [...planSkills(input), planAgentsMd(input), planClaudeMd(input.existing.claudeMd)];
   return [...actions].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
@@ -1247,7 +1258,6 @@ function planAgentsMd(input) {
   if (status === "legacy") {
     return { path: AGENTS_FILE, content: null, reason: "legacy", note: LEGACY_NOTE };
   }
-  if (status === "ok") return { path: AGENTS_FILE, content: null, reason: "keep" };
   const identity = parseAgentsIdentity(current);
   const block = renderManagedBlock({
     space: sanitizeIdentity(identity.space) ?? space,
@@ -1255,10 +1265,23 @@ function planAgentsMd(input) {
     target,
     kind
   });
+  if (status === "ok" && extractManagedBlock(current) === block) {
+    return { path: AGENTS_FILE, content: null, reason: "keep" };
+  }
   const swapped = swapManagedBlock(current, block);
   if (swapped === null) {
     return { path: AGENTS_FILE, content: null, reason: "legacy", note: LEGACY_NOTE };
   }
+  if (status === "ok") {
+    const fileVersion = readManagedVersion(current);
+    const newer = fileVersion !== null && fileVersion > AGENTS_MANAGED_VERSION;
+    return {
+      path: AGENTS_FILE,
+      content: swapped,
+      reason: "update",
+      note: newer ? AGENTS_NEWER_NOTE : KIND_DRIFT_NOTE
+    };
+  }
   return { path: AGENTS_FILE, content: swapped, reason: "update" };
 }
 function planClaudeMd(current) {
@@ -1278,6 +1301,7 @@ function planClaudeMd(current) {
   designGuideSection,
   designMeta,
   designRulesBrief,
+  extractManagedBlock,
   freeRegionScaffold,
   parseAgentsIdentity,
   planInstall,

package/dist/index.d.cts

@@ -111,6 +111,12 @@ type AgentsMdStatus = 'missing' | 'legacy' | 'stale' | 'ok';
 declare function readManagedVersion(content: string): number | null;
 /** AGENTS.md 내용으로 갱신 상태를 판정한다. */
 declare function agentsMdStatus(content: string): Exclude<AgentsMdStatus, 'missing'>;
+/**
+ * 기존 파일의 관리 영역(마커 포함, START~END)을 그대로 돌려준다. 마커가 없거나 순서가 어긋나면 null.
+ * `renderManagedBlock` 결과와 문자열로 비교해 "버전은 같은데 본문이 다른" 상태(레포 종류가 바뀐 뒤의
+ * 옛 kind 본문, 관리 영역 안 손수정)를 잡는 데 쓴다 — 버전 마커만 보면 이 둘은 `ok`로 보인다.
+ */
+declare function extractManagedBlock(content: string): string | null;
 /**
  * 기존 파일의 관리 영역(START~END)을 새 블록으로 치환한다. START/END 바깥(자유 영역 등)은
  * 그대로 보존한다. 마커가 없으면(레거시) null을 반환 — 호출부가 reconcile 경로로 분기한다.
@@ -223,4 +229,4 @@ declare function designRulesBrief(target: DesignTarget): string;
  */
 declare function designGuideSection(target: DesignTarget): string;
 
-export { AGENTS_MANAGED_VERSION, type ActionReason, type AgentsMdStatus, BSTAGE_SKILLS, type BstageSkill, type DesignTarget, type InstallAction, type InstallInput, type ProjectKind, type SkillContext, VERSION, agentsManagedBody, agentsMd, agentsMdStatus, claudeMd, compareVersions, designGuideSection, meta as designMeta, designRulesBrief, freeRegionScaffold, parseAgentsIdentity, planInstall, readManagedVersion, readSkillStamp, renderManagedBlock, sanitizeIdentity, skillFilePath, skillStamp, skillsFor, swapManagedBlock, withStamp, wrapManaged };
+export { AGENTS_MANAGED_VERSION, type ActionReason, type AgentsMdStatus, BSTAGE_SKILLS, type BstageSkill, type DesignTarget, type InstallAction, type InstallInput, type ProjectKind, type SkillContext, VERSION, agentsManagedBody, agentsMd, agentsMdStatus, claudeMd, compareVersions, designGuideSection, meta as designMeta, designRulesBrief, extractManagedBlock, freeRegionScaffold, parseAgentsIdentity, planInstall, readManagedVersion, readSkillStamp, renderManagedBlock, sanitizeIdentity, skillFilePath, skillStamp, skillsFor, swapManagedBlock, withStamp, wrapManaged };

package/dist/index.d.ts

@@ -111,6 +111,12 @@ type AgentsMdStatus = 'missing' | 'legacy' | 'stale' | 'ok';
 declare function readManagedVersion(content: string): number | null;
 /** AGENTS.md 내용으로 갱신 상태를 판정한다. */
 declare function agentsMdStatus(content: string): Exclude<AgentsMdStatus, 'missing'>;
+/**
+ * 기존 파일의 관리 영역(마커 포함, START~END)을 그대로 돌려준다. 마커가 없거나 순서가 어긋나면 null.
+ * `renderManagedBlock` 결과와 문자열로 비교해 "버전은 같은데 본문이 다른" 상태(레포 종류가 바뀐 뒤의
+ * 옛 kind 본문, 관리 영역 안 손수정)를 잡는 데 쓴다 — 버전 마커만 보면 이 둘은 `ok`로 보인다.
+ */
+declare function extractManagedBlock(content: string): string | null;
 /**
  * 기존 파일의 관리 영역(START~END)을 새 블록으로 치환한다. START/END 바깥(자유 영역 등)은
  * 그대로 보존한다. 마커가 없으면(레거시) null을 반환 — 호출부가 reconcile 경로로 분기한다.
@@ -223,4 +229,4 @@ declare function designRulesBrief(target: DesignTarget): string;
  */
 declare function designGuideSection(target: DesignTarget): string;
 
-export { AGENTS_MANAGED_VERSION, type ActionReason, type AgentsMdStatus, BSTAGE_SKILLS, type BstageSkill, type DesignTarget, type InstallAction, type InstallInput, type ProjectKind, type SkillContext, VERSION, agentsManagedBody, agentsMd, agentsMdStatus, claudeMd, compareVersions, designGuideSection, meta as designMeta, designRulesBrief, freeRegionScaffold, parseAgentsIdentity, planInstall, readManagedVersion, readSkillStamp, renderManagedBlock, sanitizeIdentity, skillFilePath, skillStamp, skillsFor, swapManagedBlock, withStamp, wrapManaged };
+export { AGENTS_MANAGED_VERSION, type ActionReason, type AgentsMdStatus, BSTAGE_SKILLS, type BstageSkill, type DesignTarget, type InstallAction, type InstallInput, type ProjectKind, type SkillContext, VERSION, agentsManagedBody, agentsMd, agentsMdStatus, claudeMd, compareVersions, designGuideSection, meta as designMeta, designRulesBrief, extractManagedBlock, freeRegionScaffold, parseAgentsIdentity, planInstall, readManagedVersion, readSkillStamp, renderManagedBlock, sanitizeIdentity, skillFilePath, skillStamp, skillsFor, swapManagedBlock, withStamp, wrapManaged };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.6.0";
+var VERSION = "0.6.2";
 
 // src/skills/deploy.ts
 function deploySkillMd() {
@@ -689,6 +689,7 @@ ${designGuideSection(target)}
 - **\`__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.
+- **\uD398\uC774\uC9C0 \uD3F4\uB354 \`user\`\xB7\`admin\`\uC740 \uC608\uC57D\uC774\uB2E4**: \uC774 \uB808\uD3EC\uC5D0 liquid \uD15C\uD50C\uB9BF(\`public/{user|admin}/{\uC774\uB984}/template.liquid\`)\uC774 \uD568\uAED8 \uC788\uC73C\uBA74 \`src/pages/user/\u2026\`\xB7\`src/pages/admin/\u2026\` \uC740 \uB9CC\uB4E4 \uC218 \uC5C6\uB2E4(\uB300\uC18C\uBB38\uC790 \uBB34\uC2DC). \uD398\uC774\uC9C0 \uC0B0\uCD9C\uBB3C\uC774 \`dist/{\uD3F4\uB354 \uACBD\uB85C}/\` \uB85C \uB098\uAC00 liquid \uC790\uB9AC\uC640 \uAC19\uC740 \uD2B8\uB9AC\uC5D0 \uB193\uC774\uACE0, \uD55C \uB514\uB809\uD130\uB9AC\uC5D0 \uB450 \uC885\uB958\uAC00 \uB193\uC774\uBA74 \uD3EC\uD138\uC774 sdk\uB85C\uB9CC \uD310\uC815\uD574 liquid\uAC00 \uC870\uC6A9\uD788 \uC0AC\uB77C\uC9C4\uB2E4. \`bstage build\` \uC640 \uD3EC\uD138 \uBE4C\uB4DC\uAC00 \uC885\uB8CC \uCF54\uB4DC 2\uB85C \uB9C9\uB294\uB2E4. \uC704\uC82F(\`src/slots\`)\uC740 \uC2AC\uB86F id\uB85C \uB098\uAC00\uBBC0\uB85C \uD574\uB2F9 \uC5C6\uB2E4. liquid \uD15C\uD50C\uB9BF\uC774 \uC5C6\uB294 \uB808\uD3EC\uC5D0\uC11C\uB294 \uC81C\uC57D\uC774 \uC5C6\uC9C0\uB9CC, \uB098\uC911\uC5D0 \uCD94\uAC00\uD558\uBA74 \uADF8\uB54C \uB9C9\uD788\uBBC0\uB85C \uCC98\uC74C\uBD80\uD130 \uB2E4\uB978 \uC774\uB984\uC744 \uC4F4\uB2E4.
 
 # \uD558\uC9C0 \uB9D0 \uAC83
 
@@ -696,6 +697,7 @@ ${designGuideSection(target)}
 - \`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
+- liquid \uD15C\uD50C\uB9BF\uC774 \uD568\uAED8 \uC788\uB294 \uB808\uD3EC\uC5D0\uC11C \`src/pages/user\`\xB7\`src/pages/admin\` \uB9CC\uB4E4\uAE30 \u2014 liquid \uC0B0\uCD9C\uBB3C \uC790\uB9AC\uC640 \uACB9\uCE5C\uB2E4(\uC704 \uD568\uC815)
 - \uC2DC\uADF8\uB2C8\uCC98\uB97C \uAE30\uC5B5\uC5D0 \uC758\uC874\uD574 \uCD94\uCE21 \u2014 \uC704 docs/.d.ts\uC5D0\uC11C \uD655\uC778
 `;
 }
@@ -785,6 +787,12 @@ function agentsMdStatus(content) {
   if (v === null) return "legacy";
   return v < AGENTS_MANAGED_VERSION ? "stale" : "ok";
 }
+function extractManagedBlock(content) {
+  const s = findMarker(content, START_TOKEN);
+  const e = findMarker(content, END_TOKEN);
+  if (!s || !e || e.end <= s.start) return null;
+  return content.slice(s.start, e.end);
+}
 function swapManagedBlock(existing, newWrappedBlock) {
   const s = findMarker(existing, START_TOKEN);
   const e = findMarker(existing, END_TOKEN);
@@ -1146,6 +1154,8 @@ var CLAUDE_FILE = "CLAUDE.md";
 var LEGACY_NOTE = "\uAD00\uB9AC \uC601\uC5ED \uB9C8\uCEE4 \uC5C6\uC74C \u2014 bstage-migrate \uC2A4\uD0AC\uB85C reconcile";
 var HAND_EDIT_NOTE = "\uBC84\uC804\uC740 \uAC19\uC740\uB370 \uBCF8\uBB38\uC774 \uB2E4\uB985\uB2C8\uB2E4(\uC190\uC218\uC815) \u2014 SDK \uBCF8\uBB38\uC73C\uB85C \uB418\uB3CC\uB9AC\uACE0 \uAE30\uC874 \uBCF8\uBB38\uC740 SKILL.md.bak \uC73C\uB85C \uB0A8\uAE41\uB2C8\uB2E4. \uD504\uB85C\uC81D\uD2B8 \uACE0\uC720 \uADDC\uCE59\uC740 AGENTS.md \uC790\uC720 \uC601\uC5ED\uC5D0 \uC801\uC73C\uC138\uC694.";
 var NEWER_NOTE = "\uC124\uCE58\uBCF8\uC774 \uC774 toolkit\uBCF4\uB2E4 \uC0C8 \uBC84\uC804\uC785\uB2C8\uB2E4 \u2014 \uC774 CLI\uAC00 \uC624\uB798\uB3FC \uC61B \uBCF8\uBB38\uC73C\uB85C \uB418\uB3CC\uB9BD\uB2C8\uB2E4(\uD558\uD5A5). \uCD5C\uC2E0 CLI(npx @bstage-sdk/cli@latest ai update)\uB85C \uB2E4\uC2DC \uC2E4\uD589\uD558\uC138\uC694.";
+var KIND_DRIFT_NOTE = "\uAD00\uB9AC \uC601\uC5ED \uBC84\uC804\uC740 \uCD5C\uC2E0\uC778\uB370 \uBCF8\uBB38\uC774 \uC774 \uD504\uB85C\uC81D\uD2B8 \uC885\uB958\uC758 \uAC83\uACFC \uB2E4\uB985\uB2C8\uB2E4(\uC885\uB958\uAC00 \uBC14\uB00C\uC5C8\uAC70\uB098 \uAD00\uB9AC \uC601\uC5ED\uC744 \uC190\uC73C\uB85C \uACE0\uCE68) \u2014 \uD604\uC7AC \uC885\uB958\uC758 \uBCF8\uBB38\uC73C\uB85C \uAC31\uC2E0\uD569\uB2C8\uB2E4. \uC790\uC720 \uC601\uC5ED\uC740 \uBCF4\uC874\uB429\uB2C8\uB2E4.";
+var AGENTS_NEWER_NOTE = "AGENTS.md \uAD00\uB9AC \uC601\uC5ED\uC774 \uC774 toolkit\uBCF4\uB2E4 \uC0C8 \uBC84\uC804\uC785\uB2C8\uB2E4 \u2014 \uC774 CLI\uAC00 \uC624\uB798\uB3FC \uC61B \uBCF8\uBB38\uC73C\uB85C \uB418\uB3CC\uB9BD\uB2C8\uB2E4(\uD558\uD5A5). \uCD5C\uC2E0 CLI(npx @bstage-sdk/cli@latest ai update)\uB85C \uB2E4\uC2DC \uC2E4\uD589\uD558\uC138\uC694.";
 function planInstall(input) {
   const actions = [...planSkills(input), planAgentsMd(input), planClaudeMd(input.existing.claudeMd)];
   return [...actions].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
@@ -1198,7 +1208,6 @@ function planAgentsMd(input) {
   if (status === "legacy") {
     return { path: AGENTS_FILE, content: null, reason: "legacy", note: LEGACY_NOTE };
   }
-  if (status === "ok") return { path: AGENTS_FILE, content: null, reason: "keep" };
   const identity = parseAgentsIdentity(current);
   const block = renderManagedBlock({
     space: sanitizeIdentity(identity.space) ?? space,
@@ -1206,10 +1215,23 @@ function planAgentsMd(input) {
     target,
     kind
   });
+  if (status === "ok" && extractManagedBlock(current) === block) {
+    return { path: AGENTS_FILE, content: null, reason: "keep" };
+  }
   const swapped = swapManagedBlock(current, block);
   if (swapped === null) {
     return { path: AGENTS_FILE, content: null, reason: "legacy", note: LEGACY_NOTE };
   }
+  if (status === "ok") {
+    const fileVersion = readManagedVersion(current);
+    const newer = fileVersion !== null && fileVersion > AGENTS_MANAGED_VERSION;
+    return {
+      path: AGENTS_FILE,
+      content: swapped,
+      reason: "update",
+      note: newer ? AGENTS_NEWER_NOTE : KIND_DRIFT_NOTE
+    };
+  }
   return { path: AGENTS_FILE, content: swapped, reason: "update" };
 }
 function planClaudeMd(current) {
@@ -1228,6 +1250,7 @@ export {
   designGuideSection,
   meta as designMeta,
   designRulesBrief,
+  extractManagedBlock,
   freeRegionScaffold,
   parseAgentsIdentity,
   planInstall,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bstage-sdk/ai-toolkit",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "bstage SDK ai-toolkit — 에이전트용 스킬·AGENTS.md 콘텐츠(cli가 소비)",
   "type": "module",
   "publishConfig": {
@@ -34,7 +34,7 @@
     "@types/node": "^25.5.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
-    "@bstage-sdk/design": "0.6.0"
+    "@bstage-sdk/design": "0.6.2"
   },
   "license": "MIT",
   "scripts": {