@byh3071/vhk 1.3.0 → 1.4.0

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.4.0, ga]
 ---
 
 # 🔧 VHK — Vibe Harness Kit
 
-> 🎉 **v1.0.0 GA** — 바이브코더의 올인원 CLI. 공개 API 안정성 보장.
+> 🎉 **v1.4.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
@@ -82,11 +115,13 @@ vhk 기획 끝났고 바로 시작
 | `vhk gate` | `검증`, `아이디어` | 아이디어 검증 (퀵 5문항 / 풀 13문항 / 스킵) |
 | `vhk init` | `시작`, `만들기` | 프로젝트 초기화 + 하네스 생성 |
 | `vhk recap` | `정리`, `오늘` | Git 변경 → `docs/log/` 세션 로그 |
-| `vhk sync` | `규칙`, `맞추기` | RULES.md → `.cursorrules` + CLAUDE.md |
+| `vhk sync` | `규칙`, `맞추기` | RULES.md → `.cursorrules` + CLAUDE.md + `.windsurfrules` |
 | `vhk check` | `점검`, `린트` | RULES.md 규칙 위반 검사 |
 | `vhk secure` | `보안` | 시크릿·키 유출 스캔 (`scan` / `스캔` 동일). **CRITICAL/HIGH 발견 시 exit code 1** (CI용) |
 | `vhk ship` | `출하` | 배포 체크리스트 + 회고 + 빌드 로그 |
 | `vhk doctor` | `환경`, `진단` | Node / npm / pnpm / Git 환경 점검 |
+| `vhk cloud push` | `클라우드`, `올리기` | `.vhk/` 를 GitHub secret gist 로 백업 (gh CLI 인증 사용) |
+| `vhk cloud pull` | `내리기` | gist 에서 `.vhk/` 복원 (`vhk cloud pull <gistId>` 또는 cloud.json) |
 | `vhk save` | `저장`, `커밋` | git add · commit · push 한 번에 |
 | `vhk undo` | `되돌리기`, `취소` | 최근 커밋 soft reset (변경은 staged 유지) |
 | `vhk diff` | `변경`, `차이` | staged / unstaged / 새 파일 요약 (줄 수 합계는 tracked·HEAD 기준) |
@@ -265,7 +300,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` 사용 |
@@ -307,8 +342,26 @@ vhk ref open 1          # 1번 레퍼런스를 브라우저로 열기
 - `docs/PRD.md`, `docs/ARCHITECTURE.md`
 - `docs/adr/`, `docs/log/`, `docs/troubleshooting/`
 - `COMMANDS.md`, `BACKLOG.md` (프로젝트 유형에 따라)
+- `.vhk/README.md` + `.vhk/context.md` (유형별 씨앗 — 규격: [`docs/spec.md`](docs/spec.md))
+- `.vhk/.gitignore` + `.vhkignore` (로컬 전용·클라우드 제외 규칙)
+- 루트 `.gitignore` (`.env`·`node_modules`·`dist` 보호 — 기존 파일은 보존하고 누락분만 추가)
 - `package.json` scripts: `save`, `check`, `scan`, `recap`, `ship`, `doctor` → `vhk` 호출
 
+## 클라우드 백업 (vhk cloud)
+
+`.vhk/` 프로젝트 맥락을 GitHub **secret gist** 로 백업·복원합니다. 컴퓨터를 바꿔도
+규칙·맥락이 따라옵니다. 규격은 [`docs/spec.md`](docs/spec.md) 참조.
+
+```bash
+vhk cloud push          # .vhk/ → secret gist 백업 (gist id 는 .vhk/cloud.json 에 저장)
+vhk cloud pull          # cloud.json 의 gist 에서 복원
+vhk cloud pull <gistId> # 새 환경에서 gist id 로 직접 복원
+```
+
+- **인증:** `gh` CLI 사용 (`gh auth login`, gist 권한). 코드·설정에 토큰을 저장하지 않습니다.
+- **프라이버시:** gist 는 secret(비공개). 개인 메모(`memory.json`)·참고링크(`refs.json`)·
+  `HARD_STOP` 은 기본 제외됩니다. 추가 제외는 루트 `.vhkignore` 에 한 줄씩 적으세요.
+
 ## 자연어 예시
 
 | 말하면 | 실행 |

package/dist/{chunk-3HGOQLRT.js → chunk-3DV7AEN4.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",
@@ -686,7 +696,9 @@ var ko = {
     gitHintCommand: 'git init && git add . && git commit -m "feat: \uD504\uB85C\uC81D\uD2B8 \uC2DC\uC791"',
     startDev: "\uC774\uC81C \uAC1C\uBC1C\uD574 \uBCF4\uC138\uC694! \u{1F680}",
     commandsMdDone: "\u{1F4CB} COMMANDS.md \uC0DD\uC131",
-    scriptsDone: "\u{1F4E6} package.json scripts \uCD94\uAC00"
+    scriptsDone: "\u{1F4E6} package.json scripts \uCD94\uAC00",
+    gitignoreCreated: "\u{1F512} .gitignore \uC0DD\uC131 (.env\xB7node_modules\xB7dist \uC81C\uC678)",
+    gitignoreUpdated: "\u{1F512} .gitignore \uBCF4\uAC15 (\uB204\uB77D \uD56D\uBAA9 \uCD94\uAC00)"
   },
   recap: {
     title: "\u{1F4DD} \uC624\uB298 \uD55C \uC77C \uC815\uB9AC",
@@ -742,8 +754,22 @@ var ko = {
     noRules: "\u26A0\uFE0F RULES.md \uD30C\uC77C\uC774 \uC5C6\uC5B4\uC694.",
     cursorrulesDone: "\u2705 .cursorrules \uB9DE\uCDA4 \uC644\uB8CC",
     claudeDone: "\u2705 CLAUDE.md \uB9DE\uCDA4 \uC644\uB8CC",
+    windsurfDone: "\u2705 .windsurfrules \uB9DE\uCDA4 \uC644\uB8CC",
     done: "\u{1F504} \uB9DE\uCD94\uAE30 \uC644\uB8CC!"
   },
+  cloud: {
+    pushTitle: "\u2601\uFE0F .vhk \uD074\uB77C\uC6B0\uB4DC \uBC31\uC5C5 (gist \uC62C\uB9AC\uAE30)",
+    pullTitle: "\u2601\uFE0F .vhk \uD074\uB77C\uC6B0\uB4DC \uBCF5\uC6D0 (gist \uB0B4\uB9AC\uAE30)",
+    noGh: "gh CLI \uAC00 \uC124\uCE58\uB418\uC5B4 \uC788\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.",
+    noAuth: "gh \uC778\uC99D\uC774 \uD544\uC694\uD569\uB2C8\uB2E4 (gist \uAD8C\uD55C).",
+    noVhkDir: ".vhk/ \uD3F4\uB354\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4. vhk init \uB610\uB294 vhk context \uB97C \uBA3C\uC800 \uC2E4\uD589\uD558\uC138\uC694.",
+    nothingToSync: "\uBC31\uC5C5\uD560 \uD30C\uC77C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4 (.vhkignore \uB85C \uBAA8\uB450 \uC81C\uC678\uB428).",
+    noGistId: "\uBCF5\uC6D0\uD560 gist id \uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.",
+    pushDone: "\u2705 \uD074\uB77C\uC6B0\uB4DC \uBC31\uC5C5 \uC644\uB8CC",
+    pullDone: "\u2705 \uD074\uB77C\uC6B0\uB4DC \uBCF5\uC6D0 \uC644\uB8CC",
+    pushFail: "\u274C \uBC31\uC5C5 \uC2E4\uD328",
+    pullFail: "\u274C \uBCF5\uC6D0 \uC2E4\uD328"
+  },
   ship: {
     title: "\u{1F680} \uBC30\uD3EC \uCCB4\uD06C\uB9AC\uC2A4\uD2B8",
     checklist: "\u{1F4CB} \uBC30\uD3EC \uC804 \uCCB4\uD06C\uB9AC\uC2A4\uD2B8",
@@ -799,7 +825,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 +864,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 +1332,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 +1644,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 +1751,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 +1836,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 +1874,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 +1912,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 +1922,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 +1943,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 +2061,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 +2089,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) {
@@ -2096,9 +2150,11 @@ async function startMcpServer() {
 }
 
 export {
+  __toESM,
   ko,
   t,
   printNextStep,
+  require_ignore,
   printSecurityWarnings,
   filterTrackedPaths,
   readJsonFile,
@@ -2112,5 +2168,6 @@ export {
   envCheck,
   publish,
   audit,
+  getVhkVersion,
   startMcpServer
 };

package/dist/index.js

@@ -2,22 +2,25 @@
 import {
   MAX_SCAN_FILE_BYTES,
   MAX_SECRET_FINDINGS,
+  __toESM,
   audit,
   deploy,
   env,
   envCheck,
   filterSevereFindings,
   filterTrackedPaths,
+  getVhkVersion,
   ko,
   printNextStep,
   printSecurityWarnings,
   publish,
   readJsonFile,
+  require_ignore,
   safeExecFile,
   scanProjectForSecrets,
   startMcpServer,
   t
-} from "./chunk-3HGOQLRT.js";
+} from "./chunk-3DV7AEN4.js";
 
 // src/index.ts
 import { Command, Help } from "commander";
@@ -39,6 +42,19 @@ function matchesKeywords(text, command) {
   return keywords.some((kw) => text.includes(kw.toLowerCase()));
 }
 var RULES = [
+  // 영문 `vhk cloud push|pull [id]` 은 commander 가 직접 처리(가로채기 금지) — 한국어 표현만 매칭.
+  {
+    command: "cloud-pull",
+    explanation: "\uD074\uB77C\uC6B0\uB4DC\uC5D0\uC11C .vhk \uBCF5\uC6D0 (vhk cloud pull)",
+    confidence: "high",
+    test: (t2) => (/(클라우드|gist)\s*(에서)?\s*(복원|내려받?|내리|받아)/.test(t2) || /(\.?vhk\s*)?(복원해|복구해|복원\s*하|복구\s*하)/.test(t2)) && !/백업|올려|올리/.test(t2)
+  },
+  {
+    command: "cloud-push",
+    explanation: ".vhk \uB97C \uD074\uB77C\uC6B0\uB4DC\uC5D0 \uBC31\uC5C5 (vhk cloud push)",
+    confidence: "high",
+    test: (t2) => (/(클라우드|gist)\s*(에)?\s*(백업|올려|올리)/.test(t2) || /(\.?vhk\s*)?백업\s*해|(\.?vhk\s*)?백업하/.test(t2)) && !/복원|내려|내리|복구/.test(t2)
+  },
   {
     command: "start",
     explanation: "\uB178\uC158\uC5D0\uC11C \uAC00\uC838\uC640 \uC0C8 \uD504\uB85C\uC81D\uD2B8 \uC2DC\uC791 \uB9C8\uBC95\uC0AC (vhk start --from-notion)",
@@ -176,7 +192,7 @@ var RULES = [
     command: "save",
     explanation: "Git\uC5D0 \uC800\uC7A5 (vhk \uC800\uC7A5)",
     confidence: "high",
-    test: (t2) => (matchesKeywords(t2, "save") || /깃허브|github/.test(t2)) && !/정리|recap|되돌|취소|rollback|reset|리셋|롤백|원래대로/.test(t2)
+    test: (t2) => (matchesKeywords(t2, "save") || /깃허브|github/.test(t2)) && !/정리|recap|되돌|취소|rollback|reset|리셋|롤백|원래대로|클라우드|cloud|gist/.test(t2)
   },
   {
     command: "recap",
@@ -351,6 +367,8 @@ var KNOWN_COMMAND_TOKENS = /* @__PURE__ */ new Set([
   "\uAE30\uC5B5",
   "brief",
   "\uBE0C\uB9AC\uD551",
+  "cloud",
+  "\uD074\uB77C\uC6B0\uB4DC",
   "goal",
   "\uBAA9\uD45C",
   "blocker",
@@ -382,7 +400,7 @@ function detectNaturalLanguageInput(argv) {
 }
 
 // src/lib/nlp-run.ts
-import chalk26 from "chalk";
+import chalk27 from "chalk";
 import inquirer11 from "inquirer";
 
 // src/commands/gate.ts
@@ -737,6 +755,70 @@ function COMMANDS_MD_TEMPLATE() {
   ].join("\n");
 }
 
+// src/templates/vhk-dir.ts
+function VHK_README_TEMPLATE() {
+  return [
+    "# `.vhk/` \u2014 VHK runtime state",
+    "",
+    "\uC774 \uB514\uB809\uD1A0\uB9AC\uB294 VHK\uAC00 \uD504\uB85C\uC81D\uD2B8\uBCC4 \uC0C1\uD0DC\uB97C \uC800\uC7A5\uD558\uB294 \uACF3\uC785\uB2C8\uB2E4.",
+    "\uC804\uCCB4 \uADDC\uACA9\uC740 `docs/spec.md` (spec_version 1.0) \uCC38\uC870.",
+    "",
+    "## \uD2B8\uB798\uD0B9 \uC815\uCC45",
+    "",
+    "| \uD30C\uC77C | \uD2B8\uB798\uD0B9 | \uC6A9\uB3C4 |",
+    "| --- | --- | --- |",
+    "| `README.md` | \u2705 | \uBCF8 \uC548\uB0B4 |",
+    "| `context.md` | \u2705 | \uD504\uB85C\uC81D\uD2B8 \uB9E5\uB77D (`vhk context` \uB85C \uAC31\uC2E0) |",
+    "| `brief.md` | \u2705 | \uC0C1\uD0DC \uC694\uC57D \uBE0C\uB9AC\uD551 (`vhk brief`) |",
+    "| `memory.json` | \u274C \uB85C\uCEEC \uC804\uC6A9 | \uC758\uC0AC\uACB0\uC815 \uBA54\uBAA8 (`vhk memory add`) |",
+    "| `refs.json` | \u274C \uB85C\uCEEC \uC804\uC6A9 | \uCC38\uACE0 URL (`vhk ref add`) |",
+    "| `HARD_STOP` | \u274C \uB85C\uCEEC \uC804\uC6A9 | \uC874\uC7AC\uD558\uBA74 \uBAA8\uB4E0 \uC790\uB3D9\uD654 \uC989\uC2DC \uC911\uB2E8 |",
+    "",
+    "> `memory.json`\xB7`refs.json` \uC740 \uAC1C\uC778 \uBA54\uBAA8 \uB178\uCD9C \uBC29\uC9C0\uB97C \uC704\uD574 `.gitignore` \uC5D0 \uB4F1\uB85D\uB429\uB2C8\uB2E4.",
+    "> `HARD_STOP` \uD574\uC81C\uB294 `vhk resume --confirm` \uC73C\uB85C\uB9CC \uAC00\uB2A5\uD569\uB2C8\uB2E4.",
+    ""
+  ].join("\n");
+}
+function VHK_GITIGNORE_TEMPLATE() {
+  return [
+    "# VHK \uB85C\uCEEC \uC804\uC6A9 \u2014 \uAC1C\uC778 \uBA54\uBAA8/\uCC38\uACE0\uB9C1\uD06C/\uC548\uC804\uC2E0\uD638 (docs/spec.md \uD2B8\uB798\uD0B9 \uC815\uCC45)",
+    "memory.json",
+    "refs.json",
+    "HARD_STOP",
+    ""
+  ].join("\n");
+}
+function VHK_IGNORE_TEMPLATE() {
+  return [
+    "# vhk cloud push \uBC31\uC5C5\uC5D0\uC11C \uC81C\uC678\uD560 .vhk/ \uD30C\uC77C (\uD55C \uC904\uC5D0 \uD558\uB098)",
+    "# \uAE30\uBCF8 \uC81C\uC678(\uC790\uB3D9): memory.json, refs.json, HARD_STOP, cloud.json, .gitignore",
+    "# \uC608) \uC544\uB798 \uC8FC\uC11D\uC744 \uD480\uBA74 brief.md \uB3C4 \uBC31\uC5C5\uC5D0\uC11C \uC81C\uC678\uB429\uB2C8\uB2E4.",
+    "# brief.md",
+    ""
+  ].join("\n");
+}
+function VHK_CONTEXT_SEED(name, type, stack) {
+  const stackList = stack.map((s) => "- " + s).join("\n");
+  return [
+    "# " + name + " \u2014 \uD504\uB85C\uC81D\uD2B8 \uB9E5\uB77D",
+    "",
+    "> \u26A1 \uC774 \uD30C\uC77C\uC740 vhk init \uC774 \uC0DD\uC131\uD55C \uC528\uC557\uC785\uB2C8\uB2E4. `vhk context` \uB85C \uAC31\uC2E0\uD558\uC138\uC694.",
+    "",
+    "## \uD504\uB85C\uC81D\uD2B8 \uC720\uD615",
+    "- " + type,
+    "",
+    "## \uAE30\uC220 \uC2A4\uD0DD",
+    stackList,
+    "",
+    "## \uC8FC\uC694 \uACB0\uC815\uC0AC\uD56D",
+    "- (\uC544\uC9C1 \uC5C6\uC74C \u2014 `vhk memory add` \uB85C \uAE30\uB85D)",
+    "",
+    "## \uB2E4\uC74C \uB2E8\uACC4",
+    "- docs/PRD.md \uC791\uC131",
+    ""
+  ].join("\n");
+}
+
 // src/utils/logger.ts
 import chalk2 from "chalk";
 var log = {
@@ -994,7 +1076,7 @@ ${ko.init.recommendedStack} ${stack.join(" + ")}
     }
   }
   const cwd = process.cwd();
-  const files = generateFiles(answers.name, answers.description, stack, prdContent);
+  const files = generateFiles(answers.name, answers.description, stack, prdContent, answers.type);
   log.step(ko.init.filesGenerating);
   for (const [filePath, content] of Object.entries(files)) {
     const fullPath = path2.join(cwd, filePath);
@@ -1039,7 +1121,7 @@ ${ko.init.nextSteps}`));
     alternative: "VS Code/Cursor\uC5D0\uC11C \uD3F4\uB354\uB97C \uC5F4\uC5B4\uB3C4 \uB429\uB2C8\uB2E4"
   });
 }
-function generateFiles(name, description, stack, prdContent = {}) {
+function generateFiles(name, description, stack, prdContent = {}, type = "") {
   const stackStr = stack.join(" + ");
   const prd = {
     tagline: description,
@@ -1064,7 +1146,12 @@ function generateFiles(name, description, stack, prdContent = {}) {
 ## v1.1 \uD6C4\uBCF4
 
 - 
-`
+`,
+    // .vhk/ 씨앗 — 규격: docs/spec.md (spec_version 1.0)
+    ".vhk/README.md": VHK_README_TEMPLATE(),
+    ".vhk/context.md": VHK_CONTEXT_SEED(name, type || "unknown", stack),
+    ".vhk/.gitignore": VHK_GITIGNORE_TEMPLATE(),
+    ".vhkignore": VHK_IGNORE_TEMPLATE()
   };
 }
 var VHK_PACKAGE_SCRIPTS = {
@@ -1075,6 +1162,32 @@ var VHK_PACKAGE_SCRIPTS = {
   ship: "vhk ship",
   doctor: "vhk doctor"
 };
+var ROOT_GITIGNORE_ENTRIES = [
+  ".env",
+  ".env.local",
+  ".env.*.local",
+  "node_modules/",
+  "dist/",
+  "*.tsbuildinfo",
+  ".DS_Store"
+];
+function ensureRootGitignore(projectDir) {
+  const gitignorePath = path2.join(projectDir, ".gitignore");
+  if (!fs2.existsSync(gitignorePath)) {
+    fs2.writeFileSync(gitignorePath, ROOT_GITIGNORE_ENTRIES.join("\n") + "\n", "utf-8");
+    return "created";
+  }
+  const content = fs2.readFileSync(gitignorePath, "utf-8");
+  const existing = new Set(content.split("\n").map((l) => l.trim()));
+  const missing = ROOT_GITIGNORE_ENTRIES.filter((e) => !existing.has(e));
+  if (missing.length === 0) return "unchanged";
+  const prefix = content.endsWith("\n") ? "" : "\n";
+  fs2.appendFileSync(gitignorePath, `${prefix}
+# vhk init
+${missing.join("\n")}
+`, "utf-8");
+  return "updated";
+}
 function enhancePackageScripts(projectDir) {
   const pkgPath = path2.join(projectDir, "package.json");
   if (!fs2.existsSync(pkgPath)) return false;
@@ -1105,6 +1218,12 @@ async function writeInitExtras(projectDir) {
   if (enhancePackageScripts(projectDir)) {
     log.success(ko.init.scriptsDone);
   }
+  const gitignoreResult = ensureRootGitignore(projectDir);
+  if (gitignoreResult === "created") {
+    log.success(ko.init.gitignoreCreated);
+  } else if (gitignoreResult === "updated") {
+    log.success(ko.init.gitignoreUpdated);
+  }
 }
 
 // src/commands/recap.ts
@@ -1578,6 +1697,27 @@ function toCursorrules(sections, projectName) {
   }
   return lines.join("\n");
 }
+function toWindsurfrules(sections, projectName) {
+  const codingSections = sections.filter(
+    (s) => CURSORRULES_KEYS.some((k) => s.title.includes(k))
+  );
+  const lines = [
+    `# ${projectName} \u2014 Windsurf Rules`,
+    "",
+    "> \uCF54\uB529/\uB514\uC790\uC778 \uC804\uC6A9. \uAE30\uB85D/\uC6B4\uC601 \u2192 CLAUDE.md \uCC38\uC870.",
+    "> \u26A1 \uC774 \uD30C\uC77C\uC740 RULES.md\uC5D0\uC11C \uC790\uB3D9 \uC0DD\uC131\uB428 (vhk sync). \uC9C1\uC811 \uC218\uC815 \uAE08\uC9C0.",
+    "",
+    "## \uD544\uC218 \uCC38\uC870",
+    "- docs/PRD.md \xB7 docs/ARCHITECTURE.md \xB7 CLAUDE.md \xB7 RULES.md",
+    ""
+  ];
+  for (const section of codingSections) {
+    lines.push(`## ${section.title}`);
+    lines.push(section.content);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
 function toClaudeMd(sections, existing) {
   const recordSections = sections.filter(
     (s) => CLAUDE_MD_KEYS.some((k) => s.title.includes(k))
@@ -1637,9 +1777,12 @@ ${ko.sync.title}
 - **\uB9C8\uC9C0\uB9C9 \uC5C5\uB370\uC774\uD2B8:** ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}`;
   fs5.writeFileSync(claudePath, toClaudeMd(sections, existingClaude), "utf-8");
   console.log(chalk5.green(`  ${ko.sync.claudeDone}`));
+  const windsurfPath = path6.join(cwd, ".windsurfrules");
+  fs5.writeFileSync(windsurfPath, toWindsurfrules(sections, projectName), "utf-8");
+  console.log(chalk5.green(`  ${ko.sync.windsurfDone}`));
   console.log(chalk5.bold.green(`
 ${ko.sync.done}`));
-  console.log(chalk5.dim("  RULES.md (\uC6D0\uBCF8) \u2192 .cursorrules + CLAUDE.md (\uC790\uB3D9 \uC0DD\uC131)"));
+  console.log(chalk5.dim("  RULES.md (\uC6D0\uBCF8) \u2192 .cursorrules + CLAUDE.md + .windsurfrules (\uC790\uB3D9 \uC0DD\uC131)"));
   console.log(chalk5.dim("  \uADDC\uCE59 \uBCC0\uACBD\uC740 \uD56D\uC0C1 RULES.md\uC5D0\uC11C\uB9CC \uD558\uC138\uC694."));
   printNextStep({
     message: "\uADDC\uCE59 \uB3D9\uAE30\uD654 \uC644\uB8CC! \uC774\uC81C Cursor\uAC00 \uC0C8 \uADDC\uCE59\uC744 \uB530\uB985\uB2C8\uB2E4.",
@@ -2052,9 +2195,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 +2221,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 +2262,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 +2456,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 +2510,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 +2867,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 +2999,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 +3127,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 +3300,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 +3883,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")
+    });
   }
 }
 
@@ -4306,6 +4503,211 @@ ${ko.start.allDone}
   });
 }
 
+// src/commands/cloud.ts
+import fs13 from "fs";
+import path14 from "path";
+import chalk26 from "chalk";
+
+// src/lib/vhk-cloud.ts
+var import_ignore = __toESM(require_ignore(), 1);
+import fs12 from "fs";
+import path13 from "path";
+var DEFAULT_CLOUD_EXCLUDES = [
+  "memory.json",
+  // 개인 의사결정 메모
+  "refs.json",
+  // 개인 참고링크
+  "HARD_STOP",
+  // 로컬 안전 신호
+  "cloud.json",
+  // gist 포인터 (백업 대상 아님)
+  ".gitignore"
+  // .vhk/ 내부 gitignore
+];
+var VHK_DIR2 = ".vhk";
+var CLOUD_CONFIG_FILE = "cloud.json";
+function loadVhkignore(rootDir) {
+  const ig = (0, import_ignore.default)();
+  ig.add(DEFAULT_CLOUD_EXCLUDES);
+  const ignorePath = path13.join(rootDir, ".vhkignore");
+  if (fs12.existsSync(ignorePath)) {
+    ig.add(fs12.readFileSync(ignorePath, "utf-8"));
+  }
+  return ig;
+}
+function collectVhkFiles(rootDir, ig = loadVhkignore(rootDir)) {
+  const vhkDir = path13.join(rootDir, VHK_DIR2);
+  let entries;
+  try {
+    entries = fs12.readdirSync(vhkDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.filter((e) => e.isFile()).map((e) => e.name).filter((name) => !ig.ignores(name)).sort();
+}
+function readCloudConfig(rootDir) {
+  const p = path13.join(rootDir, VHK_DIR2, CLOUD_CONFIG_FILE);
+  if (!fs12.existsSync(p)) return null;
+  try {
+    const parsed = JSON.parse(fs12.readFileSync(p, "utf-8"));
+    if (parsed && typeof parsed.gistId === "string" && parsed.gistId) {
+      return { gistId: parsed.gistId };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function writeCloudConfig(rootDir, config) {
+  const vhkDir = path13.join(rootDir, VHK_DIR2);
+  fs12.mkdirSync(vhkDir, { recursive: true });
+  const p = path13.join(vhkDir, CLOUD_CONFIG_FILE);
+  fs12.writeFileSync(p, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+// src/commands/cloud.ts
+function ensureGhReady() {
+  const ver = safeExecFile("gh", ["--version"]);
+  if (!ver.ok) {
+    console.log(chalk26.red(`  ${ko.cloud.noGh}`));
+    console.log(chalk26.dim("  \uC124\uCE58: https://cli.github.com/  (\uC124\uCE58 \uD6C4 `gh auth login`)"));
+    return false;
+  }
+  const auth = safeExecFile("gh", ["auth", "status"]);
+  if (!auth.ok) {
+    console.log(chalk26.red(`  ${ko.cloud.noAuth}`));
+    console.log(chalk26.dim("  \uC2E4\uD589: gh auth login  (gist \uAD8C\uD55C \uD544\uC694)"));
+    return false;
+  }
+  return true;
+}
+function parseGistId(output) {
+  const match = output.match(/gist\.github\.com\/(?:[^/]+\/)?([0-9a-f]+)/i);
+  if (match) return match[1];
+  const trimmed = output.trim();
+  if (/^[0-9a-f]{8,}$/i.test(trimmed)) return trimmed;
+  return null;
+}
+async function cloudPush() {
+  console.log(chalk26.bold(`
+${ko.cloud.pushTitle}
+`));
+  const cwd = process.cwd();
+  if (!fs13.existsSync(path14.join(cwd, VHK_DIR2))) {
+    console.log(chalk26.yellow(`  ${ko.cloud.noVhkDir}`));
+    return;
+  }
+  const files = collectVhkFiles(cwd);
+  if (files.length === 0) {
+    console.log(chalk26.yellow(`  ${ko.cloud.nothingToSync}`));
+    return;
+  }
+  if (!ensureGhReady()) {
+    process.exitCode = 1;
+    return;
+  }
+  const filePaths = files.map((f) => path14.join(cwd, VHK_DIR2, f));
+  console.log(chalk26.dim(`  \u{1F4E6} \uBC31\uC5C5 \uB300\uC0C1 ${files.length}\uAC1C: ${files.join(", ")}
+`));
+  const existing = readCloudConfig(cwd);
+  const desc = `vhk .vhk backup \u2014 ${path14.basename(cwd)}`;
+  if (existing) {
+    const gistFiles = listGistFiles(existing.gistId);
+    for (let i = 0; i < files.length; i++) {
+      const name = files[i];
+      const src = filePaths[i];
+      const args = gistFiles.includes(name) ? ["gist", "edit", existing.gistId, "-f", name, src] : ["gist", "edit", existing.gistId, "-a", src];
+      const res2 = safeExecFile("gh", args);
+      if (!res2.ok) {
+        console.log(chalk26.red(`  ${ko.cloud.pushFail}: ${name}`));
+        console.log(chalk26.dim(`    ${res2.err}`));
+        process.exitCode = 1;
+        return;
+      }
+    }
+    console.log(chalk26.green.bold(`  ${ko.cloud.pushDone}`));
+    console.log(chalk26.dim(`  gist: ${existing.gistId} (\uAC31\uC2E0)`));
+    printPushNext();
+    return;
+  }
+  const res = safeExecFile("gh", ["gist", "create", "--desc", desc, ...filePaths]);
+  if (!res.ok) {
+    console.log(chalk26.red(`  ${ko.cloud.pushFail}`));
+    console.log(chalk26.dim(`    ${res.err || res.out}`));
+    process.exitCode = 1;
+    return;
+  }
+  const gistId = parseGistId(res.out);
+  if (!gistId) {
+    console.log(chalk26.red(`  ${ko.cloud.pushFail} \u2014 gist id \uD30C\uC2F1 \uC2E4\uD328`));
+    console.log(chalk26.dim(`    \uCD9C\uB825: ${res.out}`));
+    process.exitCode = 1;
+    return;
+  }
+  writeCloudConfig(cwd, { gistId });
+  console.log(chalk26.green.bold(`  ${ko.cloud.pushDone}`));
+  console.log(chalk26.dim(`  gist: ${gistId} (\uC2E0\uADDC, secret) \u2192 .vhk/cloud.json \uC800\uC7A5`));
+  printPushNext();
+}
+async function cloudPull(gistIdArg) {
+  console.log(chalk26.bold(`
+${ko.cloud.pullTitle}
+`));
+  const cwd = process.cwd();
+  const gistId = gistIdArg || readCloudConfig(cwd)?.gistId;
+  if (!gistId) {
+    console.log(chalk26.yellow(`  ${ko.cloud.noGistId}`));
+    console.log(chalk26.dim("  \uC0AC\uC6A9\uBC95: vhk cloud pull <gistId>  (\uB610\uB294 cloud.json \uC774 \uC788\uB294 \uACF3\uC5D0\uC11C \uC2E4\uD589)"));
+    return;
+  }
+  if (!ensureGhReady()) {
+    process.exitCode = 1;
+    return;
+  }
+  const names = listGistFiles(gistId);
+  if (names.length === 0) {
+    console.log(chalk26.red(`  ${ko.cloud.pullFail} \u2014 gist \uBE44\uC5C8\uAC70\uB098 \uC811\uADFC \uBD88\uAC00: ${gistId}`));
+    process.exitCode = 1;
+    return;
+  }
+  const vhkDir = path14.join(cwd, VHK_DIR2);
+  fs13.mkdirSync(vhkDir, { recursive: true });
+  let restored = 0;
+  for (const name of names) {
+    const res = safeExecFile("gh", ["gist", "view", gistId, "-f", name, "--raw"]);
+    if (!res.ok) {
+      console.log(chalk26.red(`  ${ko.cloud.pullFail}: ${name}`));
+      console.log(chalk26.dim(`    ${res.err}`));
+      continue;
+    }
+    fs13.writeFileSync(path14.join(vhkDir, name), ensureTrailingNewline(res.out), "utf-8");
+    restored++;
+  }
+  writeCloudConfig(cwd, { gistId });
+  console.log(chalk26.green.bold(`  ${ko.cloud.pullDone}`));
+  console.log(chalk26.dim(`  ${restored}\uAC1C \uD30C\uC77C \uBCF5\uC6D0 (gist: ${gistId})`));
+  printNextStep({
+    message: "\uD074\uB77C\uC6B0\uB4DC\uC5D0\uC11C .vhk/ \uBCF5\uC6D0 \uC644\uB8CC!",
+    command: "vhk \uB9E5\uB77D",
+    cursorHint: "\uD504\uB85C\uC81D\uD2B8 \uB9E5\uB77D \uBCF4\uC5EC\uC918"
+  });
+}
+function listGistFiles(gistId) {
+  const res = safeExecFile("gh", ["gist", "view", gistId, "--files"]);
+  if (!res.ok) return [];
+  return res.out.split("\n").map((l) => l.trim()).filter(Boolean);
+}
+function ensureTrailingNewline(s) {
+  return s.endsWith("\n") ? s : s + "\n";
+}
+function printPushNext() {
+  printNextStep({
+    message: "\uD074\uB77C\uC6B0\uB4DC \uBC31\uC5C5 \uC644\uB8CC! \uB2E4\uB978 \uD658\uACBD\uC5D0\uC11C vhk cloud pull \uB85C \uBCF5\uC6D0\uD558\uC138\uC694.",
+    command: "vhk cloud pull",
+    cursorHint: "\uB2E4\uB978 \uCEF4\uD4E8\uD130\uC5D0\uC11C .vhk \uBCF5\uC6D0\uD574\uC918"
+  });
+}
+
 // src/lib/nlp-run.ts
 async function dispatchNlpRoute(route, input) {
   switch (route.command) {
@@ -4374,6 +4776,10 @@ async function dispatchNlpRoute(route, input) {
       return memoryList();
     case "brief":
       return brief();
+    case "cloud-push":
+      return cloudPush();
+    case "cloud-pull":
+      return cloudPull();
     case "goal": {
       const sub = route.args?.[0];
       if (sub === "next") return goalNext();
@@ -4386,14 +4792,14 @@ async function dispatchNlpRoute(route, input) {
 async function runNaturalLanguageRoute(input) {
   const route = routeNaturalLanguage(input);
   if (!route) {
-    console.log(chalk26.yellow(`
+    console.log(chalk27.yellow(`
   \u2753 "${input}" \u2014 ${ko.nlp.notMatched}
 `));
     return;
   }
   console.log("");
-  console.log(chalk26.cyan(`  \u{1F4AC} "${input}"`));
-  console.log(chalk26.cyan(`  \u2192 ${route.explanation}`));
+  console.log(chalk27.cyan(`  \u{1F4AC} "${input}"`));
+  console.log(chalk27.cyan(`  \u2192 ${route.explanation}`));
   if (route.confidence === "low") {
     const { confirm } = await inquirer11.prompt([{
       type: "confirm",
@@ -4402,7 +4808,7 @@ async function runNaturalLanguageRoute(input) {
       default: true
     }]);
     if (!confirm) {
-      console.log(chalk26.dim(`  ${ko.nlp.menuHint}`));
+      console.log(chalk27.dim(`  ${ko.nlp.menuHint}`));
       return;
     }
   }
@@ -4410,100 +4816,78 @@ 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";
+import chalk28 from "chalk";
 function activeGoalId() {
   const goals = listGoals("goals");
   const id = selectActiveId(goals);
   return id ?? void 0;
 }
 async function blocker(description) {
-  console.log(chalk27.bold(`
+  console.log(chalk28.bold(`
 ${ko.agent.blockerTitle}
 `));
   if (!description || !description.trim()) {
-    console.log(chalk27.red("  \u274C \uBE14\uB85C\uCEE4 \uC124\uBA85\uC744 \uC785\uB825\uD574 \uC8FC\uC138\uC694."));
-    console.log(chalk27.dim('  \uC608: vhk blocker "tsc \uC5D0\uB7EC \u2014 simple-git \uD0C0\uC785 \uD638\uD658"'));
+    console.log(chalk28.red("  \u274C \uBE14\uB85C\uCEE4 \uC124\uBA85\uC744 \uC785\uB825\uD574 \uC8FC\uC138\uC694."));
+    console.log(chalk28.dim('  \uC608: vhk blocker "tsc \uC5D0\uB7EC \u2014 simple-git \uD0C0\uC785 \uD638\uD658"'));
     process.exitCode = 1;
     return;
   }
   const goalId = activeGoalId();
   const r = appendBlocker(description, goalId);
-  console.log(chalk27.green(`  \u2705 blocker \uAE30\uB85D (\uD604\uC7AC \uD65C\uC131 ${r.count}\uAC74)`));
+  console.log(chalk28.green(`  \u2705 blocker \uAE30\uB85D (\uD604\uC7AC \uD65C\uC131 ${r.count}\uAC74)`));
   if (r.hardStopTripped) {
-    console.log(chalk27.red.bold("  \u{1F6D1} HARD_STOP \uC790\uB3D9 \uC0DD\uC131 \u2014 \uBAA8\uB4E0 \uC790\uB3D9\uD654 \uC911\uB2E8."));
-    console.log(chalk27.yellow("     \uC0AC\uB78C \uAC80\uD1A0 \uD6C4 `vhk resume --confirm` \uC73C\uB85C\uB9CC \uD574\uC81C."));
+    console.log(chalk28.red.bold("  \u{1F6D1} HARD_STOP \uC790\uB3D9 \uC0DD\uC131 \u2014 \uBAA8\uB4E0 \uC790\uB3D9\uD654 \uC911\uB2E8."));
+    console.log(chalk28.yellow("     \uC0AC\uB78C \uAC80\uD1A0 \uD6C4 `vhk resume --confirm` \uC73C\uB85C\uB9CC \uD574\uC81C."));
     process.exitCode = 2;
   }
 }
 async function learn(lesson) {
-  console.log(chalk27.bold(`
+  console.log(chalk28.bold(`
 ${ko.agent.learnTitle}
 `));
   if (!lesson || !lesson.trim()) {
-    console.log(chalk27.red("  \u274C \uAD50\uD6C8 \uB0B4\uC6A9\uC744 \uC785\uB825\uD574 \uC8FC\uC138\uC694."));
-    console.log(chalk27.dim('  \uC608: vhk learn "PowerShell \uC5D0\uC11C\uB294 ; \uC0AC\uC6A9 (&& \uBBF8\uC9C0\uC6D0)"'));
+    console.log(chalk28.red("  \u274C \uAD50\uD6C8 \uB0B4\uC6A9\uC744 \uC785\uB825\uD574 \uC8FC\uC138\uC694."));
+    console.log(chalk28.dim('  \uC608: vhk learn "PowerShell \uC5D0\uC11C\uB294 ; \uC0AC\uC6A9 (&& \uBBF8\uC9C0\uC6D0)"'));
     process.exitCode = 1;
     return;
   }
   const goalId = activeGoalId();
   appendLearning(lesson, goalId);
-  console.log(chalk27.green("  \u2705 learnings.md append."));
+  console.log(chalk28.green("  \u2705 learnings.md append."));
   console.log(
-    chalk27.dim("  \uACB0\uC815\uC0AC\uD56D(decision)\uC740 `vhk memory add` \uB85C \uBCC4\uB3C4 \uAE30\uB85D \u2014 SoT \uBD84\uB9AC.")
+    chalk28.dim("  \uACB0\uC815\uC0AC\uD56D(decision)\uC740 `vhk memory add` \uB85C \uBCC4\uB3C4 \uAE30\uB85D \u2014 SoT \uBD84\uB9AC.")
   );
 }
 async function resume(opts = {}) {
-  console.log(chalk27.bold(`
+  console.log(chalk28.bold(`
 ${ko.agent.resumeTitle}
 `));
   if (!isHardStopActive()) {
-    console.log(chalk27.dim("  HARD_STOP \uD65C\uC131 \uC544\uB2D8 \u2014 \uD560 \uC77C \uC5C6\uC74C."));
+    console.log(chalk28.dim("  HARD_STOP \uD65C\uC131 \uC544\uB2D8 \u2014 \uD560 \uC77C \uC5C6\uC74C."));
     return;
   }
   const reason = readHardStopReason();
   if (reason) {
-    console.log(chalk27.yellow("  \u{1F4CB} HARD_STOP \uC0AC\uC720:"));
-    console.log(chalk27.dim(`     ${reason.split("\n").join("\n     ")}`));
+    console.log(chalk28.yellow("  \u{1F4CB} HARD_STOP \uC0AC\uC720:"));
+    console.log(chalk28.dim(`     ${reason.split("\n").join("\n     ")}`));
     console.log("");
   }
   if (!opts.confirm) {
     console.log(
-      chalk27.red(
+      chalk28.red(
         "  \u274C --confirm \uD50C\uB798\uADF8 \uC5C6\uC774\uB294 \uD574\uC81C\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4 (\uC790\uB3D9 \uD638\uCD9C \uAE08\uC9C0)."
       )
     );
-    console.log(chalk27.yellow("     \uC0AC\uC720\uB97C \uD655\uC778\uD55C \uD6C4 \uB2E4\uC2DC: vhk resume --confirm"));
+    console.log(chalk28.yellow("     \uC0AC\uC720\uB97C \uD655\uC778\uD55C \uD6C4 \uB2E4\uC2DC: vhk resume --confirm"));
     process.exitCode = 1;
     return;
   }
   const removed = clearHardStop();
   if (removed) {
-    console.log(chalk27.green("  \u2705 HARD_STOP \uD574\uC81C. \uC790\uB3D9\uD654 \uC7AC\uAC1C \uAC00\uB2A5."));
+    console.log(chalk28.green("  \u2705 HARD_STOP \uD574\uC81C. \uC790\uB3D9\uD654 \uC7AC\uAC1C \uAC00\uB2A5."));
   } else {
-    console.log(chalk27.dim("  \uD30C\uC77C\uC774 \uC774\uBBF8 \uC5C6\uC74C \u2014 no-op."));
+    console.log(chalk28.dim("  \uD30C\uC77C\uC774 \uC774\uBBF8 \uC5C6\uC74C \u2014 no-op."));
   }
 }
 
@@ -4545,7 +4929,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) {
@@ -4579,6 +4963,15 @@ program.command("check").alias("\uC810\uAC80").alias("\uB9B0\uD2B8").option("--g
 });
 var secureCmd = program.command("secure").alias("\uBCF4\uC548").description("\uBCF4\uC548 \uB3C4\uAD6C \uBAA8\uC74C \u2014 scan: \uC2DC\uD06C\uB9BF\xB7\uD0A4 \uC720\uCD9C \uAC80\uC0AC").action(secure);
 secureCmd.command("scan").alias("\uC2A4\uCE94").description("\uC2DC\uD06C\uB9BF/\uD0A4 \uC720\uCD9C \uC2A4\uCE94").action(secure);
+var cloudCmd = program.command("cloud").alias("\uD074\uB77C\uC6B0\uB4DC").description(".vhk/ \uD074\uB77C\uC6B0\uB4DC \uBC31\uC5C5\xB7\uBCF5\uC6D0 (GitHub gist) \u2014 push: \uC62C\uB9AC\uAE30, pull: \uB0B4\uB9AC\uAE30").action(() => {
+  cloudCmd.help();
+});
+cloudCmd.command("push").alias("\uC62C\uB9AC\uAE30").description(".vhk/ \uB97C secret gist \uB85C \uBC31\uC5C5").action(async () => {
+  await cloudPush();
+});
+cloudCmd.command("pull").alias("\uB0B4\uB9AC\uAE30").argument("[gistId]", "\uBCF5\uC6D0\uD560 gist id (\uC0DD\uB7B5 \uC2DC .vhk/cloud.json \uC0AC\uC6A9)").description("gist \uC5D0\uC11C .vhk/ \uBCF5\uC6D0").action(async (gistId) => {
+  await cloudPull(gistId);
+});
 program.command("ship").alias("\uCD9C\uD558").description("\uBC30\uD3EC \uCCB4\uD06C\uB9AC\uC2A4\uD2B8 + \uD68C\uACE0 + \uBE4C\uB4DC \uB85C\uADF8 \uC0DD\uC131").action(ship);
 program.command("doctor").alias("\uD658\uACBD").alias("\uC9C4\uB2E8").description("\uAC1C\uBC1C \uD658\uACBD \uC810\uAC80 \u2014 Node/Git/npm \uC0C1\uD0DC \uD655\uC778").action(doctor);
 program.command("save").alias("\uC800\uC7A5").description("\uBCC0\uACBD\uC0AC\uD56D \uC800\uC7A5 (git add \u2192 commit \u2192 push)").action(async () => {
@@ -4591,10 +4984,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-3DV7AEN4.js";
 
 // src/mcp/index.ts
 startMcpServer().catch((err) => {

package/package.json

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