@byh3071/vhk 1.3.0 → 1.3.1

package/README.md

@@ -1,57 +1,90 @@
 ---
 id: vhk-readme
-date: 2026-05-24
-tags: [vhk, cli, readme, v1.0.0, ga]
+date: 2026-05-28
+tags: [vhk, cli, readme, v1.3.0, ga]
 ---
 
 # 🔧 VHK — Vibe Harness Kit
 
-> 🎉 **v1.0.0 GA** — 바이브코더의 올인원 CLI. 공개 API 안정성 보장.
+> 🎉 **v1.3.0** — 바이브코더의 올인원 CLI. 컨텍스트 + 자율 하네스.
 >
-> AI 코딩 에이전트를 부리는 사람을 위한 **한국어 풀사이클 CLI** (v1.0.0)
+> AI 코딩 에이전트를 부리는 사람을 위한 **한국어 풀사이클 CLI**.
 >
 > 🍽️ **VHK는 VHK로 부트스트랩됨** — 이 레포의 `docs/`, `CLAUDE.md`, `.cursorrules`도 `vhk init`이 만들었습니다.
 
 명령어를 외우지 않아도 됩니다. `vhk`만 치면 메뉴가 나오고, 한국어로 말해도 알아듣습니다.
 
-## 설치
+## 3분 안에 시작하기 (Getting Started)
+
+### 1. 설치
 
 ```bash
 npm install -g @byh3071/vhk
+vhk --version
 ```
 
+> Node.js ≥ 20 필요. `npx @byh3071/vhk` 로 1회성 실행도 가능.
+
+### 2. 첫 프로젝트 — `vhk start` (마법사)
+
 ```bash
-# 한 번만 쓸 때
-npx @byh3071/vhk
+mkdir my-app && cd my-app
+vhk start
 ```
 
-로컬 개발 중:
+`vhk start` 한 번이면 **git init → 문서 생성 → MCP 등록 → 컨텍스트 파일** 까지 자동으로 끝납니다.
 
-```powershell
-cd vhk-cli
-pnpm install
-pnpm build
-pnpm link --global
-vhk --version
+기획이 막 떠올랐다면 검증부터:
+
+```bash
+vhk gate          # 퀵 5문항 — GO / 다듬기 / 다른 아이디어
 ```
 
-## 빠른 시작
+### 3. v1.3 핵심 기능 한눈에
 
-```bash
-vhk
+| 기능 | 한 줄 요약 | 진입 명령 |
+|------|-----------|-----------|
+| 🎯 **Goals 체계** | 단계별 미션 + 게이트 스크립트로 AI가 목표를 스스로 추적 | `vhk goal init` |
+| ▶️ **자율 루프** | `goal next → 작업 → goal check → goal done`. FAIL 3회면 자동 블로커 | `vhk goal next` |
+| 🚧 **HARD_STOP 안전장치** | 블로커 3건 누적 → `.vhk/HARD_STOP` 트립와이어. `vhk resume --confirm` 만 해제 | `vhk blocker "<증상>"` |
+| 🔌 **MCP 24 tool** | Cursor·Claude Desktop 등에서 vhk를 채팅으로 호출 | `vhk mcp-init` |
+| 📋 **컨텍스트 영속화** | `.vhk/context.md` + `memory.json` + `brief.md` 로 세션 간 맥락 유지 | `vhk context` |
+
+### 4. 권장 일일 사이클
+
+```text
+세션 시작 :  vhk context          # AI에 줄 프로젝트 맥락 갱신
+            vhk goal next         # 오늘 작업할 미션 자동 선택
+
+   개발 ...
+
+세션 종료 :  vhk goal check        # 게이트 스크립트로 통과 검증
+            vhk goal done         # 통과 시 status: DONE 으로 전이
+            vhk save              # add → commit → push 한 번에
+            vhk recap             # docs/log/ 에 오늘 기록
 ```
 
-인자 없이 실행하면 **「뭘 도와드릴까요?」** 메뉴가 열립니다.
+### 5. 자연어로도 됩니다
 
 ```bash
-# 자연어로도 가능
 vhk 프로젝트 만들고 싶어
 vhk 기획 끝났고 바로 시작
 vhk 오늘 한 일 정리
 vhk 저장해줘
-vhk 변경사항 보여줘
+vhk 다음 목표
+vhk 블로커 "API 호출 실패"
+```
+
+---
+
+## 빠른 시작 (인터랙티브 메뉴)
+
+```bash
+vhk
 ```
 
+인자 없이 실행하면 **「뭘 도와드릴까요?」** 메뉴가 열립니다.
+
 ## 워크플로우 (권장 순서)
 
 ```text
@@ -265,7 +298,7 @@ vhk ref open 1          # 1번 레퍼런스를 브라우저로 열기
 
 | 기능 | 설명 |
 |------|------|
-| **MCP 서버** | `vhk mcp` — 8개 도구(save/undo/status/diff/ship/doctor/check/recap)를 stdio로 노출. Cursor 등 MCP 클라이언트에서 자연어로 호출 |
+| **MCP 서버** | `vhk mcp` — stdio MCP 서버 첫 도입 (v0.6.0 당시 8개 도구 — save/undo/status/diff/ship/doctor/check/recap). 현재 v1.3 기준 **24개** 로 확장 — 위 "Cursor와 MCP로 연동하기" 섹션 참조 |
 | **mcp-init** | `vhk mcp-init` — Cursor `.cursor/mcp.json` 자동 생성. 재시작 한 번으로 연동 완료 |
 | **자연어 라우팅 확장** | `vhk mcp설정` → `vhk mcp-init` 별칭 |
 | **보안** | MCP save 도구의 shell injection 차단 — 모든 git 호출에 `execFileSync` 사용 |

package/dist/{chunk-3HGOQLRT.js → chunk-6S3JYYZ3.js}

@@ -551,7 +551,11 @@ var ko = {
     package: "package.json:",
     noPackage: "package.json \uC5C6\uC74C",
     detached: "(detached HEAD)",
-    unknownBranch: "(\uC54C \uC218 \uC5C6\uC74C)"
+    unknownBranch: "(\uC54C \uC218 \uC5C6\uC74C)",
+    nextWithChangesMessage: "\uBCC0\uACBD\uC0AC\uD56D\uC774 \uC788\uC5B4\uC694. \uCEE4\uBC0B\xB7\uD478\uC2DC\uB97C \uC9C4\uD589\uD558\uC138\uC694.",
+    nextWithChangesCursor: "\uC800\uC7A5\uD574\uC918",
+    nextCleanMessage: "\uD074\uB9B0 \uC0C1\uD0DC! \uB2E4\uC74C \uBBF8\uC158\uC73C\uB85C \uB118\uC5B4\uAC00\uC138\uC694.",
+    nextCleanCursor: "\uB2E4\uC74C \uBAA9\uD45C \uC54C\uB824\uC918"
   },
   save: {
     title: "\uC800\uC7A5\uD558\uAE30",
@@ -573,7 +577,11 @@ var ko = {
     pushFailed: "push \uC2E4\uD328 (\uB85C\uCEEC \uCEE4\uBC0B\uC740 \uC644\uB8CC\uB428)",
     commitOkPushFailed: "\uB85C\uCEEC \uCEE4\uBC0B\uC740 \uB410\uC9C0\uB9CC \uC6D0\uACA9 push\uC5D0 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4. git push\uB97C \uC9C1\uC811 \uD655\uC778\uD558\uC138\uC694.",
     done: (n) => `${n}\uAC1C \uD30C\uC77C \uC800\uC7A5 \uC644\uB8CC!`,
-    doneLocalOnly: (n) => `${n}\uAC1C \uD30C\uC77C \uB85C\uCEEC \uC800\uC7A5\uB428 (push\uB294 \uC2E4\uD328)`
+    doneLocalOnly: (n) => `${n}\uAC1C \uD30C\uC77C \uB85C\uCEEC \uC800\uC7A5\uB428 (push\uB294 \uC2E4\uD328)`,
+    nextOkMessage: "\uC800\uC7A5 \uC644\uB8CC! \uC624\uB298 \uC791\uC5C5\uC744 \uC815\uB9AC\uD574\uB450\uBA74 \uC88B\uC544\uC694.",
+    nextOkCursor: "\uC624\uB298 \uD55C \uC77C \uC815\uB9AC\uD574\uC918",
+    nextPushFailMessage: "\uCEE4\uBC0B\uC740 \uB410\uC9C0\uB9CC push \uC2E4\uD328. \uC6D0\uACA9\uC744 \uD655\uC778\uD558\uC138\uC694.",
+    nextPushFailCursor: "\uC65C push \uC2E4\uD328\uC778\uC9C0 \uC54C\uB824\uC918"
   },
   undo: {
     title: "\uB418\uB3CC\uB9AC\uAE30",
@@ -590,7 +598,9 @@ var ko = {
     stagedHint: "\uBCC0\uACBD\uC0AC\uD56D\uC740 \uC2A4\uD14C\uC774\uC9D5 \uC601\uC5ED\uC5D0 \uB0A8\uC544 \uC788\uC5B4\uC694.",
     rootCommit: "\uCCAB \uCEE4\uBC0B\uB9CC \uC788\uC5B4\uC11C \uB354 \uB418\uB3CC\uB9B4 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
     forcePushHint: "\uC6D0\uACA9\uACFC \uB9DE\uCD94\uB824\uBA74: git push --force-with-lease (\uD63C\uC790 \uC791\uC5C5\uD55C \uBE0C\uB79C\uCE58\uC5D0\uC11C\uB9CC, \uD300\uACFC \uD569\uC758 \uD6C4)",
-    failed: "\uB418\uB3CC\uB9AC\uAE30 \uC2E4\uD328"
+    failed: "\uB418\uB3CC\uB9AC\uAE30 \uC2E4\uD328",
+    nextMessage: "\uBCC0\uACBD\uC0AC\uD56D\uC774 \uC2A4\uD14C\uC774\uC9D5 \uC601\uC5ED\uC5D0 \uB0A8\uC558\uC5B4\uC694. \uBA54\uC2DC\uC9C0 \uACE0\uCCD0\uC11C \uB2E4\uC2DC \uC800\uC7A5\uD558\uC138\uC694.",
+    nextCursor: "\uCEE4\uBC0B \uBA54\uC2DC\uC9C0 \uBC14\uAFD4\uC11C \uC800\uC7A5\uD574\uC918"
   },
   diff: {
     title: "\uBCC0\uACBD\uC0AC\uD56D \uD655\uC778",
@@ -799,7 +809,9 @@ var ko = {
   },
   mcp: {
     initTitle: "Cursor MCP \uC5F0\uB3D9 \uC124\uC815",
-    serverStarted: "VHK MCP \uC11C\uBC84 \uC2DC\uC791\uB428"
+    serverStarted: "VHK MCP \uC11C\uBC84 \uC2DC\uC791\uB428",
+    nextMessage: "Cursor / Claude Desktop \uC744 \uC7AC\uC2DC\uC791\uD55C \uB4A4 \uCC44\uD305\uC5D0\uC11C vhk \uB3C4\uAD6C\uB97C \uD638\uCD9C\uD558\uC138\uC694.",
+    nextCursor: "\uD504\uB85C\uC81D\uD2B8 \uC0C1\uD0DC \uC54C\uB824\uC918"
   },
   deploy: {
     title: "\uBC30\uD3EC\uD558\uAE30",
@@ -836,7 +848,11 @@ var ko = {
     selectTarget: "\uC5B4\uB5A4 \uD328\uD0A4\uC9C0 \uB9E4\uB2C8\uC800\uB85C \uC804\uD658\uD560\uAE4C\uC694?"
   },
   update: {
-    title: "VHK CLI \uC5C5\uB370\uC774\uD2B8"
+    title: "VHK CLI \uC5C5\uB370\uC774\uD2B8",
+    nextOkMessage: "\uC5C5\uB370\uC774\uD2B8 \uC644\uB8CC! \uC0C8 \uBC84\uC804 \uD655\uC778\uD558\uC138\uC694.",
+    nextOkCursor: "vhk \uBC84\uC804 \uC54C\uB824\uC918",
+    nextFailMessage: "\uC5C5\uB370\uC774\uD2B8 \uC2E4\uD328. \uD658\uACBD \uC810\uAC80\uBD80\uD130 \uD574\uBCF4\uC138\uC694.",
+    nextFailCursor: "vhk doctor \uC2E4\uD589\uD574\uC918"
   },
   context: {
     title: "\uD504\uB85C\uC81D\uD2B8 \uCEE8\uD14D\uC2A4\uD2B8 \uC0DD\uC131",
@@ -1300,11 +1316,33 @@ async function audit(autoFix = false) {
   });
 }
 
+// src/lib/version.ts
+import { existsSync as existsSync5 } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+function getVhkVersion() {
+  const dir = dirname(fileURLToPath(import.meta.url));
+  for (const pkgPath of [
+    join(dir, "../../package.json"),
+    join(dir, "../package.json")
+  ]) {
+    try {
+      if (existsSync5(pkgPath)) {
+        const pkg = readJsonFile(pkgPath);
+        if (pkg.version) return pkg.version;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return "0.0.0";
+}
+
 // src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync3, appendFileSync as appendFileSync2 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync4, writeFileSync as writeFileSync3, appendFileSync as appendFileSync2 } from "fs";
 
 // src/lib/scan-secrets.ts
 import fs3 from "fs";
@@ -1590,7 +1628,7 @@ function filterSevereFindings(findings) {
 }
 
 // src/mcp/server.ts
-var SERVER_VERSION = "1.3.0";
+var SERVER_VERSION = getVhkVersion();
 function isGitRepo() {
   return safeExecFile("git", ["rev-parse", "--is-inside-work-tree"]).ok;
 }
@@ -1697,7 +1735,7 @@ ${preview}${more}
   });
   server.registerTool("status", { description: "\uD504\uB85C\uC81D\uD2B8 \uC0C1\uD0DC \uB300\uC2DC\uBCF4\uB4DC (\uBE0C\uB79C\uCE58/\uBCC0\uACBD\uC0AC\uD56D/\uCD5C\uADFC \uCEE4\uBC0B)" }, async () => {
     const lines = [];
-    if (existsSync5("package.json")) {
+    if (existsSync6("package.json")) {
       try {
         const pkg = readJsonFile("package.json");
         lines.push(`\u{1F4E6} \uD504\uB85C\uC81D\uD2B8: ${pkg.name ?? "(\uC774\uB984 \uC5C6\uC74C)"} v${pkg.version ?? "?"}`);
@@ -1782,7 +1820,7 @@ ${preview}${more}
     checks.push(build.ok ? "\u2705 \uBE4C\uB4DC \uC131\uACF5" : "\u274C \uBE4C\uB4DC \uC2E4\uD328");
     const test = safeExecFile("pnpm", ["test", "--run"]);
     checks.push(test.ok ? "\u2705 \uD14C\uC2A4\uD2B8 \uD1B5\uACFC" : "\u274C \uD14C\uC2A4\uD2B8 \uC2E4\uD328");
-    if (existsSync5("package.json")) {
+    if (existsSync6("package.json")) {
       try {
         const pkg = readJsonFile("package.json");
         checks.push(`\u{1F4E6} \uBC84\uC804: ${pkg.version}`);
@@ -1820,11 +1858,11 @@ ${preview}${more}
     const recommended = ["CLAUDE.md", ".cursorrules", "docs/PRD.md", "docs/ARCHITECTURE.md"];
     const lines = ["\u{1F50D} \uD504\uB85C\uC81D\uD2B8 \uC810\uAC80", "", "\uD544\uC218:"];
     required.forEach((f) => {
-      lines.push(`  ${existsSync5(f) ? "\u2705" : "\u274C"} ${f}`);
+      lines.push(`  ${existsSync6(f) ? "\u2705" : "\u274C"} ${f}`);
     });
     lines.push("", "\uAD8C\uC7A5 (VHK \uD558\uB124\uC2A4):");
     recommended.forEach((f) => {
-      lines.push(`  ${existsSync5(f) ? "\u2705" : "\u26A0\uFE0F"} ${f}`);
+      lines.push(`  ${existsSync6(f) ? "\u2705" : "\u26A0\uFE0F"} ${f}`);
     });
     return { content: [{ type: "text", text: lines.join("\n") }] };
   });
@@ -1858,7 +1896,7 @@ ${log.out}` }] };
       description: ".env \u2192 .env.example \uB3D9\uAE30\uD654 + .gitignore\uC5D0 .env \uC790\uB3D9 \uCD94\uAC00"
     },
     async () => {
-      if (!existsSync5(".env")) {
+      if (!existsSync6(".env")) {
         return { content: [{ type: "text", text: "\u26A0\uFE0F  .env \uD30C\uC77C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4. \uBA3C\uC800 .env\uB97C \uB9CC\uB4E4\uC5B4\uC8FC\uC138\uC694." }] };
       }
       const keys = parseEnvKeys(readFileSync4(".env", "utf-8"));
@@ -1868,7 +1906,7 @@ ${log.out}` }] };
       const exampleContent = keys.map((k) => `${k}=`).join("\n") + "\n";
       writeFileSync3(".env.example", exampleContent, "utf-8");
       const gitignoreLines = [];
-      if (existsSync5(".gitignore")) {
+      if (existsSync6(".gitignore")) {
         const content = readFileSync4(".gitignore", "utf-8");
         if (!content.split("\n").some((l) => l.trim() === ".env")) {
           appendFileSync2(".gitignore", "\n.env\n");
@@ -1889,11 +1927,11 @@ ${log.out}` }] };
       description: "\uD544\uC218 \uD658\uACBD\uBCC0\uC218 \uB204\uB77D \uAC80\uC0AC (.env.example \uAE30\uC900)"
     },
     async () => {
-      if (!existsSync5(".env.example")) {
+      if (!existsSync6(".env.example")) {
         return { content: [{ type: "text", text: "\u26A0\uFE0F  .env.example\uC774 \uC5C6\uC2B5\uB2C8\uB2E4. \uBA3C\uC800 env \uB3C4\uAD6C\uB97C \uC2E4\uD589\uD558\uC138\uC694." }] };
       }
       const requiredKeys = parseEnvKeys(readFileSync4(".env.example", "utf-8"));
-      const currentKeys = existsSync5(".env") ? parseEnvKeys(readFileSync4(".env", "utf-8")) : [];
+      const currentKeys = existsSync6(".env") ? parseEnvKeys(readFileSync4(".env", "utf-8")) : [];
       const missing = requiredKeys.filter((k) => !currentKeys.includes(k));
       const extra = currentKeys.filter((k) => !requiredKeys.includes(k));
       const lines = [`\u{1F4CB} \uD544\uC218 \uD658\uACBD\uBCC0\uC218: ${requiredKeys.length}\uAC1C`];
@@ -2007,7 +2045,7 @@ ${cliStatus}
       description: "\uD604\uC7AC \uBC84\uC804 + bump \uD6C4\uBCF4 \uD45C\uC2DC (MCP \uBAA8\uB4DC: \uC2E4\uC81C npm publish \uBBF8\uC218\uD589 \u2014 `vhk publish` \uC548\uB0B4)"
     },
     async () => {
-      if (!existsSync5("package.json")) {
+      if (!existsSync6("package.json")) {
         return { content: [{ type: "text", text: "\u274C package.json \uC5C6\uC74C." }] };
       }
       try {
@@ -2035,7 +2073,7 @@ ${cliStatus}
       description: "\uD328\uD0A4\uC9C0 \uB9E4\uB2C8\uC800 \uAC10\uC9C0 + \uC804\uD658 \uD6C4\uBCF4 \uAC00\uC6A9\uC131 (MCP \uBAA8\uB4DC: \uC2E4\uC81C \uC804\uD658 \uBBF8\uC218\uD589 \u2014 `vhk migrate <target>` \uC548\uB0B4)"
     },
     async () => {
-      const current = existsSync5("pnpm-lock.yaml") ? "pnpm" : existsSync5("yarn.lock") ? "yarn" : existsSync5("package-lock.json") ? "npm" : null;
+      const current = existsSync6("pnpm-lock.yaml") ? "pnpm" : existsSync6("yarn.lock") ? "yarn" : existsSync6("package-lock.json") ? "npm" : null;
       const candidates = ["npm", "yarn", "pnpm"].filter((pm) => pm !== current);
       const lines = [`\uD604\uC7AC PM: ${current ?? "\uAC10\uC9C0 \uBD88\uAC00 (lock \uD30C\uC77C \uC5C6\uC74C)"}`];
       for (const pm of candidates) {
@@ -2112,5 +2150,6 @@ export {
   envCheck,
   publish,
   audit,
+  getVhkVersion,
   startMcpServer
 };

package/dist/index.js

@@ -8,6 +8,7 @@ import {
   envCheck,
   filterSevereFindings,
   filterTrackedPaths,
+  getVhkVersion,
   ko,
   printNextStep,
   printSecurityWarnings,
@@ -17,7 +18,7 @@ import {
   scanProjectForSecrets,
   startMcpServer,
   t
-} from "./chunk-3HGOQLRT.js";
+} from "./chunk-6S3JYYZ3.js";
 
 // src/index.ts
 import { Command, Help } from "commander";
@@ -2052,9 +2053,18 @@ ${ko.goal.initTitle}
     });
   }
 }
+function findGateScript(id) {
+  const mjs = join2(SCRIPTS_DIR, `check-goal-${id}.mjs`);
+  if (existsSync2(mjs)) return mjs;
+  const sh = join2(SCRIPTS_DIR, `check-goal-${id}.sh`);
+  if (existsSync2(sh)) return sh;
+  return null;
+}
 function runGate(scriptPath) {
-  const r = safeExecFile("bash", [scriptPath]);
-  return { ok: r.ok, out: r.out, err: r.ok ? "" : r.err };
+  const isMjs = scriptPath.endsWith(".mjs");
+  const runner = isMjs ? "node" : "bash";
+  const r = safeExecFile(runner, [scriptPath]);
+  return { ok: r.ok, out: r.out, err: r.ok ? "" : r.err, runner };
 }
 async function goalCheck(opts) {
   console.log(chalk6.bold(`
@@ -2069,15 +2079,17 @@ ${ko.goal.checkTitle}
     process.exitCode = 1;
     return;
   }
-  const scriptPath = join2(SCRIPTS_DIR, `check-goal-${id}.sh`);
-  if (!existsSync2(scriptPath)) {
-    console.log(chalk6.red(`  \u274C \uAC8C\uC774\uD2B8 \uC2A4\uD06C\uB9BD\uD2B8 \uC5C6\uC74C: ${scriptPath}`));
+  const scriptPath = findGateScript(id);
+  if (!scriptPath) {
+    console.log(
+      chalk6.red(`  \u274C \uAC8C\uC774\uD2B8 \uC2A4\uD06C\uB9BD\uD2B8 \uC5C6\uC74C: scripts/check-goal-${id}.{mjs,sh}`)
+    );
     process.exitCode = 1;
     return;
   }
-  console.log(chalk6.dim(`  \u25B6 bash ${scriptPath}
-`));
   const gate2 = runGate(scriptPath);
+  console.log(chalk6.dim(`  \u25B6 ${gate2.runner} ${scriptPath}
+`));
   if (gate2.out) console.log(gate2.out);
   if (gate2.ok) {
     console.log(chalk6.green(`
@@ -2108,15 +2120,19 @@ ${ko.goal.doneTitle}
     process.exitCode = 1;
     return;
   }
-  const scriptPath = join2(SCRIPTS_DIR, `check-goal-${id}.sh`);
-  if (!existsSync2(scriptPath)) {
-    console.log(chalk6.red(`  \u274C \uAC8C\uC774\uD2B8 \uC2A4\uD06C\uB9BD\uD2B8 \uC5C6\uC74C \u2014 done \uCC98\uB9AC \uAC70\uBD80: ${scriptPath}`));
+  const scriptPath = findGateScript(id);
+  if (!scriptPath) {
+    console.log(
+      chalk6.red(
+        `  \u274C \uAC8C\uC774\uD2B8 \uC2A4\uD06C\uB9BD\uD2B8 \uC5C6\uC74C \u2014 done \uCC98\uB9AC \uAC70\uBD80: scripts/check-goal-${id}.{mjs,sh}`
+      )
+    );
     process.exitCode = 1;
     return;
   }
-  console.log(chalk6.dim(`  \u25B6 \uAC8C\uC774\uD2B8 \uAC80\uC99D: bash ${scriptPath}
-`));
   const gate2 = runGate(scriptPath);
+  console.log(chalk6.dim(`  \u25B6 \uAC8C\uC774\uD2B8 \uAC80\uC99D: ${gate2.runner} ${scriptPath}
+`));
   if (gate2.out) console.log(gate2.out);
   if (!gate2.ok) {
     console.log(
@@ -2298,7 +2314,7 @@ function checkCommand(name, command, hint) {
   const version = result.out.split("\n")[0];
   return { name, command, version, ok: true, hint };
 }
-function getVhkVersion() {
+function getVhkVersion2() {
   const dir = path10.dirname(fileURLToPath(import.meta.url));
   const candidates = [
     path10.join(dir, "../package.json"),
@@ -2352,7 +2368,7 @@ ${ko.doctor.title}
     }
   }
   console.log("");
-  const vhkVersion = getVhkVersion();
+  const vhkVersion = getVhkVersion2();
   if (vhkVersion) {
     console.log(chalk9.green("  \u2705 VHK") + chalk9.dim(` \u2014 v${vhkVersion}`));
   } else {
@@ -2709,9 +2725,19 @@ async function save() {
     if (process.exitCode !== 1) {
       console.log(chalk11.green(`
 \u2705 ${t("save.done", lines.length)}`));
+      printNextStep({
+        message: t("save.nextOkMessage"),
+        command: "vhk recap",
+        cursorHint: t("save.nextOkCursor")
+      });
     } else {
       console.log(chalk11.green(`
 \u2705 ${t("save.doneLocalOnly", lines.length)}`));
+      printNextStep({
+        message: t("save.nextPushFailMessage"),
+        command: "vhk doctor",
+        cursorHint: t("save.nextPushFailCursor")
+      });
     }
   } catch (err) {
     spinner.fail(t("save.failed"));
@@ -2831,6 +2857,11 @@ ${t("undo.recentHeader")}`));
       console.log(chalk12.yellow(`
 \u{1F4A1} ${t("undo.forcePushHint")}`));
     }
+    printNextStep({
+      message: t("undo.nextMessage"),
+      command: "vhk save",
+      cursorHint: t("undo.nextCursor")
+    });
   } catch (err) {
     console.log(chalk12.red(`\u274C ${t("undo.failed")}`));
     const msg = err instanceof Error ? err.message : String(err);
@@ -2954,7 +2985,20 @@ async function status() {
   } else {
     console.log(chalk13.dim(`\u{1F4E6} ${t("status.noPackage")}`));
   }
-  console.log("");
+  const hasChanges = counts.staged + counts.unstaged + counts.untracked > 0;
+  if (hasChanges) {
+    printNextStep({
+      message: t("status.nextWithChangesMessage"),
+      command: "vhk save",
+      cursorHint: t("status.nextWithChangesCursor")
+    });
+  } else {
+    printNextStep({
+      message: t("status.nextCleanMessage"),
+      command: "vhk goal next",
+      cursorHint: t("status.nextCleanCursor")
+    });
+  }
 }
 
 // src/commands/diff.ts
@@ -3114,10 +3158,11 @@ async function mcpInit() {
   console.log(chalk15.green("\n\u2705 Cursor MCP \uC124\uC815 \uC644\uB8CC!"));
   console.log(chalk15.cyan("\u{1F4C1} \uC0DD\uC131\uB41C \uD30C\uC77C:"));
   console.log(`   ${configPath}`);
-  console.log(chalk15.cyan("\n\u{1F504} \uB2E4\uC74C \uB2E8\uACC4:"));
-  console.log("   1. Cursor\uB97C \uC7AC\uC2DC\uC791\uD558\uC138\uC694");
-  console.log("   2. Cursor \uCC44\uD305\uC5D0\uC11C vhk \uB3C4\uAD6C\uB97C \uC0AC\uC6A9\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4");
-  console.log(chalk15.gray('\n\u{1F4A1} \uC608: "\uD504\uB85C\uC81D\uD2B8 \uC0C1\uD0DC \uC54C\uB824\uC918" \u2192 Cursor\uAC00 vhk status \uD638\uCD9C'));
+  printNextStep({
+    message: t("mcp.nextMessage"),
+    command: "vhk mcp",
+    cursorHint: t("mcp.nextCursor")
+  });
 }
 
 // src/commands/design.ts
@@ -3696,11 +3741,21 @@ async function update() {
     console.log(chalk21.green.bold(`
 \u{1F389} VHK CLI v${latest} \uC5C5\uB370\uC774\uD2B8 \uC644\uB8CC!`));
     console.log(chalk21.gray("   \uBCC0\uACBD \uC0AC\uD56D\uC740 GitHub Releases\uB97C \uD655\uC778\uD558\uC138\uC694."));
+    printNextStep({
+      message: t("update.nextOkMessage"),
+      command: "vhk --version",
+      cursorHint: t("update.nextOkCursor")
+    });
   } else {
     updateSpinner.fail("\uC5C5\uB370\uC774\uD2B8 \uC2E4\uD328");
     console.log(chalk21.red(upd.err.slice(0, 300)));
     console.log(chalk21.yellow("\n\uC218\uB3D9\uC73C\uB85C \uC5C5\uB370\uC774\uD2B8\uD558\uC138\uC694:"));
     console.log(chalk21.gray(`   npm update -g ${PACKAGE}`));
+    printNextStep({
+      message: t("update.nextFailMessage"),
+      command: "vhk doctor",
+      cursorHint: t("update.nextFailCursor")
+    });
   }
 }
 
@@ -4410,28 +4465,6 @@ async function runNaturalLanguageRoute(input) {
   await dispatchNlpRoute(route, input);
 }
 
-// src/lib/version.ts
-import { existsSync as existsSync15 } from "fs";
-import { dirname as dirname3, join as join8 } from "path";
-import { fileURLToPath as fileURLToPath4 } from "url";
-function getVhkVersion2() {
-  const dir = dirname3(fileURLToPath4(import.meta.url));
-  for (const pkgPath of [
-    join8(dir, "../../package.json"),
-    join8(dir, "../package.json")
-  ]) {
-    try {
-      if (existsSync15(pkgPath)) {
-        const pkg = readJsonFile(pkgPath);
-        if (pkg.version) return pkg.version;
-      }
-    } catch {
-      continue;
-    }
-  }
-  return "0.0.0";
-}
-
 // src/commands/agent.ts
 import chalk27 from "chalk";
 function activeGoalId() {
@@ -4545,7 +4578,7 @@ var KO_ALIASES = {
   learn: "\uAD50\uD6C8",
   resume: "\uC7AC\uAC1C"
 };
-program.name("vhk").description("VHK \u2014 \uBC14\uC774\uBE0C\uCF54\uB529 \uD504\uB85C\uC81D\uD2B8 \uCF54\uCE58 (\uD55C\uAD6D\uC5B4\uB85C \uC548\uB0B4\uD569\uB2C8\uB2E4)").version(getVhkVersion2());
+program.name("vhk").description("VHK \u2014 \uBC14\uC774\uBE0C\uCF54\uB529 \uD504\uB85C\uC81D\uD2B8 \uCF54\uCE58 (\uD55C\uAD6D\uC5B4\uB85C \uC548\uB0B4\uD569\uB2C8\uB2E4)").version(getVhkVersion());
 program.configureHelp({
   formatHelp(cmd, helper) {
     if (cmd.parent) {
@@ -4591,10 +4624,10 @@ program.command("status").alias("\uC0C1\uD0DC").description("\uD504\uB85C\uC81D\
   await status();
 });
 program.command("diff").alias("\uBCC0\uACBD").alias("\uCC28\uC774").description("Git \uBCC0\uACBD\uC0AC\uD56D \uD55C\uAD6D\uC5B4 \uC694\uC57D (staged / unstaged / \uC0C8 \uD30C\uC77C)").action(diff);
-program.command("mcp").description("MCP \uC11C\uBC84 \uC2DC\uC791 (Cursor \uB4F1 MCP \uD074\uB77C\uC774\uC5B8\uD2B8\uC6A9)").action(async () => {
+program.command("mcp").description("MCP \uC11C\uBC84 \uC2DC\uC791 (24 tool stdio \u2014 Cursor\xB7Claude Desktop \uB4F1)").action(async () => {
   await startMcpServer();
 });
-program.command("mcp-init").alias("mcp\uC124\uC815").description("Cursor MCP \uC5F0\uB3D9 \uC124\uC815 \uC790\uB3D9 \uC0DD\uC131 (.cursor/mcp.json)").action(async () => {
+program.command("mcp-init").alias("mcp\uC124\uC815").description("Cursor\xB7Claude Desktop MCP \uC5F0\uB3D9 \uC124\uC815 \uC790\uB3D9 \uC0DD\uC131 (.cursor/mcp.json)").action(async () => {
   await mcpInit();
 });
 program.command("deploy").alias("\uBC30\uD3EC").description("\uD504\uB85C\uB355\uC158 \uBC30\uD3EC (Vercel/Netlify/Cloudflare \uC790\uB3D9 \uAC10\uC9C0)").action(async () => {

package/dist/mcp/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   startMcpServer
-} from "../chunk-3HGOQLRT.js";
+} from "../chunk-6S3JYYZ3.js";
 
 // src/mcp/index.ts
 startMcpServer().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byh3071/vhk",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Vibe Harness Kit — 바이브코딩 풀사이클 CLI",
   "bin": {
     "vhk": "dist/index.js",