claude-pro-minmax 1.1.0 → 1.2.1

package/README.ko.md

@@ -3,6 +3,7 @@
 <!-- Badges -->
 [![npm version](https://img.shields.io/npm/v/claude-pro-minmax.svg)](https://www.npmjs.com/package/claude-pro-minmax)
 [![npm downloads](https://img.shields.io/npm/dm/claude-pro-minmax.svg)](https://www.npmjs.com/package/claude-pro-minmax)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
 ![Claude Code](https://img.shields.io/badge/Claude_Code-Compatible-purple.svg)
 ![Pro Plan](https://img.shields.io/badge/Pro_Plan-Optimized-green.svg)
@@ -27,91 +28,138 @@ CPMM은 모델 라우팅, 출력 제어, 로컬 안전장치로 리셋 전까지
 
 ## 🛠 설치 (Installation)
 
-### 1. 빠른 설치 (권장)
+### 1. 설치 (권장)
 ```bash
-npm install -g claude-pro-minmax
-cpmm install
+npm install -g claude-pro-minmax@latest
+cpmm setup
+cpmm doctor
 ```
 
-대안 (전역 설치 없이 1회 실행):
+### 2. 업데이트
 ```bash
-npx claude-pro-minmax@latest install
+npm install -g claude-pro-minmax@latest
+cpmm setup
 ```
 
-### 2. 의존성 설정 (필수/선택)
+### 3. 트러블슈팅 (빠른 복구)
 ```bash
-cpmm setup --check
-# 누락된 의존성 자동 복구 (비대화형)
-cpmm setup --fix --yes
+# 누락된 의존성 재설치
+cpmm setup
+
+# 상태 확인만
+cpmm doctor
 ```
 
-- `required`: `claude`, `jq`
-- `optional`: `mgrep`, `tmux`
+의존성 정책:
+- `required`: `jq`, `mgrep`, `tmux`
+- `optional` (확인만): `claude` (사전 설치 가정)
+- 자동 설치 지원: `npm` (mgrep), `brew` (macOS), Linux 패키지 매니저 `apt-get`, `dnf`, `pacman`, `apk`
+- macOS에서 Homebrew가 없으면 설치 명령을 안내합니다
+
+### 4. 커스텀 & 업데이트 정책
+
+- `cpmm setup`은 누락된 의존성을 설치한 뒤, CPMM 설정(설정 파일 복사, 언어 선택, Perplexity 설정)까지 진행합니다.
+- `cpmm doctor`는 수정 없이 의존성 상태만 확인합니다.
+- 재실행 시 CPMM 관리 파일은 최신 버전으로 교체되고, 사용자 데이터는 보존됩니다.
+
+```text
+~/.claude/*            ← Global Baseline (CPMM 관리)
+  ├── agents/            🔄 업데이트 시 교체됨
+  ├── commands/          🔄 업데이트 시 교체됨
+  ├── contexts/          🔄 업데이트 시 교체됨
+  ├── scripts/           🔄 업데이트 시 교체됨
+  ├── skills/cli-wrappers/ 🔄 업데이트 시 교체됨
+  ├── rules/*.md         🔄 업데이트 시 교체됨
+  ├── settings.json      🔄 업데이트 시 교체됨
+  ├── settings.local.json  ✋ 사용자 소유 — 보존됨
+  ├── skills/learned/      ✋ 사용자 소유 — 보존됨
+  ├── sessions/            ✋ 사용자 소유 — 보존됨
+  ├── plans/               ✋ 사용자 소유 — 보존됨
+  ├── projects/            ✋ 사용자 소유 — 보존됨
+  └── rules/language.md    ✋ 사용자 소유 — 보존됨
+
+<project>/.claude/*    ← Project-Specific (사용자/팀 커스텀)
+  ├── CLAUDE.md          프로젝트별 지침
+  ├── commands/          프로젝트 전용 슬래시 명령어
+  ├── skills/            프로젝트 전용 스킬
+  ├── rules/             프로젝트 전용 규칙
+  └── settings.json      프로젝트 전용 권한/훅/MCP 비활성화
+```
+
+> **핵심 규칙 2가지:**
+> 1. 글로벌 커스텀은 `settings.local.json`에만 — `settings.json`은 업데이트 시 덮어쓰기됩니다.
+> 2. 커스텀 명령어/규칙은 프로젝트 `.claude/`에 — 글로벌 `commands/`는 CPMM이 관리합니다.
+
+프로젝트 초기화 팁:
+- `claude` 실행 전에 `project-templates/`를 참고해 프로젝트를 초기화하세요. (설치기는 `project-templates`를 `~/.claude`로 복사하지 않습니다.)
+
+### 5. 고급 (선택)
+<details>
+<summary>Perplexity, 언어, 수동 설치 보기</summary>
+
+**Perplexity/언어 설정 (필수 아님):**
+- Perplexity는 `/dplan`의 웹 리서치에 사용됩니다. 설정하지 않아도 `/dplan`은 Sequential Thinking + Context7으로 동작하며, 나머지 모든 기능은 Perplexity와 무관합니다.
+- 최초 인터랙티브 설치 시 `cpmm setup`이 출력 언어와 Perplexity API 키를 묻습니다.
+- 영어(기본): 파일이 필요 없습니다. `~/.claude/rules/language.md`가 있으면 삭제하세요.
+- 비영어: `~/.claude/rules/language.md`를 만들어 원하는 언어를 지정하세요.
+- Perplexity를 수동으로 설정하려면 `~/.claude.json`의 `mcpServers`에 아래를 추가하세요:
+
+```json
+"perplexity": {
+  "command": "npx",
+  "args": ["-y", "@perplexity-ai/mcp-server"],
+  "env": {
+    "PERPLEXITY_API_KEY": "YOUR_API_KEY_HERE"
+  }
+}
+```
 
-### 3. 수동 의존성 설치 (고급)
+**수동 의존성 설치:**
 ```bash
-# 필수
-npm install -g @anthropic-ai/claude-code
+# jq
 brew install jq                 # macOS
-sudo apt-get install jq         # Linux
+sudo apt-get install -y jq      # Ubuntu/Debian
+sudo dnf install -y jq          # Fedora/RHEL
+sudo pacman -S --noconfirm jq   # Arch
+sudo apk add jq                 # Alpine
 
-# 선택
+# mgrep
 npm install -g @mixedbread/mgrep
 mgrep install-claude-code
+
+# tmux
 brew install tmux               # macOS
-sudo apt-get install tmux       # Linux
+sudo apt-get install -y tmux    # Ubuntu/Debian
+sudo dnf install -y tmux        # Fedora/RHEL
+sudo pacman -S --noconfirm tmux # Arch
+sudo apk add tmux               # Alpine
 ```
 
-### 4. 소스에서 수동 설치
+**소스에서 수동 설치:**
 ```bash
 git clone https://github.com/move-hoon/claude-pro-minmax.git
 cd claude-pro-minmax
-node bin/cpmm.js install
+node bin/cpmm.js setup
 # 고급/디버그 경로 (동일한 내부 설치기):
 # bash install.sh
 ```
 
-### 5. 설치 후 설정 (선택 사항)
-**Fresh Install을 인터랙티브로 실행할 때 `cpmm install`이 Perplexity API 키와 출력 언어를 묻습니다.**
-설치 시 언어를 건너뛰었다면 수동으로 설정할 수 있습니다:
-- **비영어:** `~/.claude/rules/language.md`를 생성하여 원하는 언어 지정
-- **영어 (기본값):** 파일 불필요. `~/.claude/rules/language.md`가 있으면 삭제
-
-Perplexity를 설치 시 건너뛰었다면 나중에 수동으로 설정할 수 있습니다:
-1. `~/.claude.json` 파일을 엽니다.
-2. `mcpServers` 객체 안에 다음 내용을 추가하세요:
-   ```json
-   "perplexity": {
-     "command": "npx",
-     "args": ["-y", "@perplexity-ai/mcp-server"],
-     "env": {
-       "PERPLEXITY_API_KEY": "YOUR_API_KEY_HERE"
-     }
-   }
-   ```
-
-> **함께 포함된 MCP 서버 (기본 활성화):**
-> - **Sequential Thinking**: 복잡한 로직 처리를 위한 강력한 추론 도구
-> - **Context7**: 고급 문서 조회 및 컨텍스트 관리 도구
-
-> **Note:** 최초 `cpmm install`(또는 `npx claude-pro-minmax@latest install`) 시 기존 `~/.claude`를 `~/.claude.pre-cpmm`으로 백업합니다. 이후 `cpmm install` 재실행은 CPMM 관리 파일만 업데이트하며, 사용자 설정(`language.md`, `settings.local.json`, `skills/learned/`, `plans/` 등)은 보존됩니다. (`cpmm install`은 내부적으로 `install.sh`를 호출합니다.)
-
-### 6. 프로젝트 초기화
-> **Tip:** `claude` 실행 전, 이 저장소의 `project-templates/`를 참고해 프로젝트를 초기화하세요. (설치기는 `project-templates`를 `~/.claude`로 복사하지 않습니다.)
-
-### 7. 설치 확인
-```bash
-cpmm setup --check
-cpmm doctor
-# 또는 (전역 설치 없이 1회 실행)
-npx claude-pro-minmax@latest setup --check
-npx claude-pro-minmax@latest doctor
-```
+</details>
 
 ---
 
 ## 🚀 빠른 시작 (Quick Start)
 
+### ⚡ 첫 60초 (FTUE)
+
+```bash
+claude
+> /plan 이 저장소를 분석하고 작은 개선 1개에 대한 3단계 실행 계획을 제안해줘.
+> /do 1단계만 최소 변경으로 안전하게 구현해줘.
+> /review .
+> /session-save ftue-first-pass
+```
+
 ### 🤖 에이전트 워크플로우
 
 CPMM은 계층적 모델 라우팅을 제공합니다: `/plan`은 @planner (Sonnet 4.6) → @builder (Haiku 4.5) 체인으로 복잡한 작업을 처리하고, `/do`는 현재 세션 모델에서 직접 실행하여 속도를 높입니다.
@@ -250,10 +298,16 @@ claude-pro-minmax
 ├── .claude.json                # 글로벌 MCP 설정 (User Scope)
 ├── .claudeignore               # Claude 컨텍스트 제외 규칙
 ├── .gitignore                  # Git ignore 규칙
-├── install.sh                  # 핵심 설치 스크립트 (`cpmm install`이 내부 호출)
+├── CONTRIBUTING.md             # 기여 가이드
+├── install.sh                  # 핵심 설치 스크립트 (`cpmm setup`이 내부 호출)
 ├── LICENSE                     # MIT 라이선스
 ├── README.md                   # 영문 문서
 ├── README.ko.md                # 국문 문서
+├── package.json                # npm 패키지 매니페스트
+├── bin/                        # CPMM CLI 엔트리포인트
+│   ├── cpmm.js                 # `cpmm` 실행 진입점
+├── lib/                        # CPMM CLI 코어 구현
+│   └── cli.js                  # setup/doctor 명령 로직
 ├── .claude/
 │   ├── CLAUDE.md               # 핵심 지침 (모든 세션에 로드됨)
 │   ├── settings.json           # 프로젝트 설정 (권한, 훅, 환경변수)
@@ -399,7 +453,7 @@ A: 네, 하지만 이러한 최적화가 필요하지 않을 수 있습니다. M
 <details>
 <summary><strong>Q: 기존 Claude Code 설정과 충돌하나요?</strong></summary>
 
-A: 최초 `cpmm install`(또는 `npx claude-pro-minmax@latest install`) 시 기존 `~/.claude`를 `~/.claude.pre-cpmm`으로 백업합니다. 이후 재설치는 CPMM 관리 파일만 덮어쓰고, 언어 설정·로컬 설정·학습된 패턴·세션 기록은 보존됩니다. Perplexity API 설정 및 언어 선택은 최초 설치 시에만 실행됩니다.
+A: 최초 `cpmm setup` 시 기존 `~/.claude`를 `~/.claude.pre-cpmm`으로 백업합니다. 재실행 시 CPMM 관리 경로는 재생성되고, 사용자 소유 경로(언어 설정, 로컬 설정, 학습 패턴, 세션)는 보존됩니다. 정확한 경계는 설치 섹션의 2-Layer 구조를 참고하세요.
 </details>
 
 <details>
@@ -417,7 +471,22 @@ A: API 가격(컴퓨팅 비용 반영)을 보면 Opus 4.6 ($5/MTok input)은 Son
 <details>
 <summary><strong>Q: /do 실행 중 실패하면 어떻게 되나요?</strong></summary>
 
-A: CPMM은 **원자적 롤백**을 사용합니다. `/do` 실행 전 `git stash push`로 스냅샷을 저장합니다. 2회 재시도 후 실패하면 `git stash pop`이 작업 트리를 실행 전 상태로 복원합니다. dirty state를 방지하고 수동 정리에 소비될 2-4 메시지를 절약합니다.
+A: CPMM은 `scripts/snapshot.sh`를 통한 **best-effort 원자적 롤백**을 사용합니다.
+
+- `/do` 실행 전 `snapshot.sh push`로 라벨된 stash 스냅샷을 시도합니다.
+- 실패 시 `snapshot.sh pop`이 복구를 시도하며, 아래 상태 중 하나를 반환합니다:
+
+| 상태 | 의미 |
+| --- | --- |
+| `RESTORED` | CPMM 라벨 stash를 정상 pop하여 복구 완료 |
+| `RESTORE_FAILED` | `git stash pop` 실패 (예: 충돌) |
+| `CHECKOUT_CLEAN` | CPMM stash가 없어 fallback `git checkout .` 성공 |
+| `CLEAN_FAILED` | fallback 정리도 실패 |
+
+롤백 후에도 완전히 깨끗하지 않다면:
+1. `git status` 확인
+2. `git stash list` 확인
+3. 충돌 해결/새 untracked 파일 수동 정리 후 재시도
 
 - 비용: 0 (git stash는 로컬 작업)
 - 제한: 기존(tracked) 파일만 추적. 새로 생성된 파일은 수동 제거 필요.

package/README.md

@@ -3,6 +3,7 @@
 <!-- Badges -->
 [![npm version](https://img.shields.io/npm/v/claude-pro-minmax.svg)](https://www.npmjs.com/package/claude-pro-minmax)
 [![npm downloads](https://img.shields.io/npm/dm/claude-pro-minmax.svg)](https://www.npmjs.com/package/claude-pro-minmax)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
 ![Claude Code](https://img.shields.io/badge/Claude_Code-Compatible-purple.svg)
 ![Pro Plan](https://img.shields.io/badge/Pro_Plan-Optimized-green.svg)
@@ -27,91 +28,138 @@ CPMM helps Pro users complete more verified tasks before reset through model rou
 
 ## 🛠 Installation
 
-### 1. Quick Start (Recommended)
+### 1. Install (Recommended)
 ```bash
-npm install -g claude-pro-minmax
-cpmm install
+npm install -g claude-pro-minmax@latest
+cpmm setup
+cpmm doctor
 ```
 
-Alternative (no global install):
+### 2. Update
 ```bash
-npx claude-pro-minmax@latest install
+npm install -g claude-pro-minmax@latest
+cpmm setup
 ```
 
-### 2. Dependency Setup (Required/Optional)
+### 3. Troubleshooting (Quick)
 ```bash
-cpmm setup --check
-# auto-fix missing dependencies (non-interactive)
-cpmm setup --fix --yes
+# re-run setup to install any missing deps
+cpmm setup
+
+# check status only
+cpmm doctor
 ```
 
-- `required`: `claude`, `jq`
-- `optional`: `mgrep`, `tmux`
+Dependency policy:
+- `required`: `jq`, `mgrep`, `tmux`
+- `optional` (check only): `claude` (assumed pre-installed)
+- auto-install supports `npm` (mgrep), `brew` (macOS), and Linux package managers `apt-get`, `dnf`, `pacman`, `apk`
+- on macOS without Homebrew, setup prints the Homebrew install command
+
+### 4. Customization & Update Policy
+
+- `cpmm setup` installs missing dependencies, then configures CPMM (copies config files, language selection, Perplexity setup).
+- `cpmm doctor` checks dependency status without modifying anything.
+- Re-running `cpmm setup` replaces CPMM-managed files with the latest version while preserving user data.
+
+```text
+~/.claude/*            ← Global Baseline (CPMM-managed)
+  ├── agents/            🔄 Replaced on update
+  ├── commands/          🔄 Replaced on update
+  ├── contexts/          🔄 Replaced on update
+  ├── scripts/           🔄 Replaced on update
+  ├── skills/cli-wrappers/ 🔄 Replaced on update
+  ├── rules/*.md         🔄 Replaced on update
+  ├── settings.json      🔄 Replaced on update
+  ├── settings.local.json  ✋ User-owned — preserved
+  ├── skills/learned/      ✋ User-owned — preserved
+  ├── sessions/            ✋ User-owned — preserved
+  ├── plans/               ✋ User-owned — preserved
+  ├── projects/            ✋ User-owned — preserved
+  └── rules/language.md    ✋ User-owned — preserved
+
+<project>/.claude/*    ← Project-Specific (user/team customization)
+  ├── CLAUDE.md          Project-specific instructions
+  ├── commands/          Project-specific slash commands
+  ├── skills/            Project-specific skills
+  ├── rules/             Project-specific rules
+  └── settings.json      Project-specific permissions/hooks/MCP disable
+```
+
+> **Two key rules:**
+> 1. Global customization goes in `settings.local.json` only — `settings.json` is overwritten on update.
+> 2. Custom commands/rules go in project `.claude/` — global `commands/` is managed by CPMM.
+
+Project initialization tip:
+- Before running `claude`, initialize your project with templates in `project-templates/` (not copied into `~/.claude`).
+
+### 5. Advanced (Optional)
+<details>
+<summary>Perplexity, language, manual install</summary>
+
+**Perplexity/Language setup (not required):**
+- Perplexity is used for web research in `/dplan`. Without it, `/dplan` still works via Sequential Thinking + Context7. All other features are unrelated to Perplexity.
+- On fresh interactive installs, `cpmm setup` asks for output language and Perplexity API key.
+- English (default): no file needed; remove `~/.claude/rules/language.md` if it exists.
+- Non-English: create `~/.claude/rules/language.md` with your preferred language.
+- To configure Perplexity manually, add this under `mcpServers` in `~/.claude.json`:
+
+```json
+"perplexity": {
+  "command": "npx",
+  "args": ["-y", "@perplexity-ai/mcp-server"],
+  "env": {
+    "PERPLEXITY_API_KEY": "YOUR_API_KEY_HERE"
+  }
+}
+```
 
-### 3. Manual Dependency Setup (Advanced)
+**Manual dependency setup:**
 ```bash
-# required
-npm install -g @anthropic-ai/claude-code
+# jq
 brew install jq                 # macOS
-sudo apt-get install jq         # Linux
+sudo apt-get install -y jq      # Ubuntu/Debian
+sudo dnf install -y jq          # Fedora/RHEL
+sudo pacman -S --noconfirm jq   # Arch
+sudo apk add jq                 # Alpine
 
-# optional
+# mgrep
 npm install -g @mixedbread/mgrep
 mgrep install-claude-code
+
+# tmux
 brew install tmux               # macOS
-sudo apt-get install tmux       # Linux
+sudo apt-get install -y tmux    # Ubuntu/Debian
+sudo dnf install -y tmux        # Fedora/RHEL
+sudo pacman -S --noconfirm tmux # Arch
+sudo apk add tmux               # Alpine
 ```
 
-### 4. Manual Install From Source
+**Manual install from source:**
 ```bash
 git clone https://github.com/move-hoon/claude-pro-minmax.git
 cd claude-pro-minmax
-node bin/cpmm.js install
+node bin/cpmm.js setup
 # advanced/debug path (same underlying installer):
 # bash install.sh
 ```
 
-### 5. Post-Install Configuration (Optional)
-**On fresh interactive installs, `cpmm install` asks for your Perplexity API Key and output language.**
-If you skipped language selection, you can configure it manually:
-- **Non-English:** Create `~/.claude/rules/language.md` with your preferred language
-- **English (default):** No file needed. Remove `~/.claude/rules/language.md` if it exists
-
-If you skipped Perplexity setup during installation, you can set it up manually:
-1. Open `~/.claude.json`.
-2. Add the following to the `mcpServers` object:
-   ```json
-   "perplexity": {
-     "command": "npx",
-     "args": ["-y", "@perplexity-ai/mcp-server"],
-     "env": {
-       "PERPLEXITY_API_KEY": "YOUR_API_KEY_HERE"
-     }
-   }
-   ```
-
-> **Other included MCP servers (Enabled by default):**
-> - **Sequential Thinking**: Powerful reasoning tool for complex logic.
-> - **Context7**: Advanced documentation fetching and context management.
-
-> **Note:** On first `cpmm install` (or `npx claude-pro-minmax@latest install`), CPMM backs up your existing `~/.claude` to `~/.claude.pre-cpmm`. Re-running install via `cpmm install` updates CPMM-managed files in-place while preserving your settings (`language.md`, `settings.local.json`, `skills/learned/`, `plans/`, etc.). (`cpmm install` invokes `install.sh` internally.)
-
-### 6. Project Initialization
-> **Tip:** Before running `claude`, initialize your project by referencing templates in this repository's `project-templates/` directory. (The installer does not copy `project-templates` into `~/.claude`.)
-
-### 7. Verify Installation
-```bash
-cpmm setup --check
-cpmm doctor
-# or (no global install)
-npx claude-pro-minmax@latest setup --check
-npx claude-pro-minmax@latest doctor
-```
+</details>
 
 ---
 
 ## 🚀 Quick Start
 
+### ⚡ First 60 Seconds (FTUE)
+
+```bash
+claude
+> /plan Analyze this repository and propose a 3-step implementation plan for one small improvement.
+> /do Implement step 1 only, with minimal and safe changes.
+> /review .
+> /session-save ftue-first-pass
+```
+
 ### 🤖 Agent Workflow
 
 CPMM provides layered model routing: `/plan` chains @planner (Sonnet 4.6) → @builder (Haiku 4.5) for complex tasks, while `/do` executes directly in the current session model for speed.
@@ -250,10 +298,16 @@ claude-pro-minmax
 ├── .claude.json                # Global MCP Settings (User Scope)
 ├── .claudeignore               # Files excluded from Claude's context
 ├── .gitignore                  # Git ignore rules
-├── install.sh                  # Core installer (invoked by `cpmm install`)
+├── CONTRIBUTING.md             # Contribution guide
+├── install.sh                  # Core installer (invoked by `cpmm setup`)
 ├── LICENSE                     # MIT License
 ├── README.md                   # English Documentation
 ├── README.ko.md                # Korean Documentation
+├── package.json                # npm package manifest
+├── bin/                        # CPMM CLI entrypoints
+│   ├── cpmm.js                 # `cpmm` executable entry
+├── lib/                        # CPMM CLI core implementation
+│   └── cli.js                  # setup/doctor command logic
 ├── .claude/
 │   ├── CLAUDE.md               # Core Instructions (Loaded in all sessions)
 │   ├── settings.json           # Project Settings (Permissions, hooks, env vars)
@@ -399,7 +453,7 @@ This configuration is specifically designed for the Pro Plan's 5-hour rolling re
 <details>
 <summary><strong>Q: Does it conflict with existing Claude Code settings?</strong></summary>
 
-A: On first `cpmm install` (or `npx claude-pro-minmax@latest install`), CPMM backs up your existing `~/.claude` to `~/.claude.pre-cpmm`. Subsequent installs update CPMM-managed files in-place — your language settings, local config, learned patterns, and session history are preserved. Perplexity API setup and language selection only run on fresh install.
+A: On first `cpmm setup`, CPMM backs up your existing `~/.claude` to `~/.claude.pre-cpmm`. Re-running `cpmm setup` recreates CPMM-managed paths and preserves user-owned paths (language settings, local config, learned patterns, sessions). See the 2-Layer structure in the install section for exact boundaries.
 </details>
 
 <details>
@@ -417,7 +471,22 @@ A: API pricing (reflecting compute cost), Opus 4.6 ($5/MTok input) is much more
 <details>
 <summary><strong>Q: What happens when /do fails mid-execution?</strong></summary>
 
-A: CPMM uses **Atomic Rollback**. Before `/do` executes, `git stash push` saves a snapshot. If execution fails after 2 retries, `git stash pop` restores the working tree to its pre-execution state. This prevents dirty state and saves 2-4 messages that would otherwise be spent on manual cleanup.
+A: CPMM uses **best-effort atomic rollback** via `scripts/snapshot.sh`.
+
+- Before `/do`, `snapshot.sh push` attempts a labeled stash snapshot.
+- On failure, `snapshot.sh pop` attempts restore and returns one of these statuses:
+
+| Status | Meaning |
+| --- | --- |
+| `RESTORED` | Labeled CPMM stash was popped successfully. |
+| `RESTORE_FAILED` | `git stash pop` failed (for example: conflicts). |
+| `CHECKOUT_CLEAN` | No CPMM stash found; fallback `git checkout .` succeeded. |
+| `CLEAN_FAILED` | Fallback cleanup also failed. |
+
+If rollback did not fully restore clean state:
+1. Run `git status`.
+2. Run `git stash list`.
+3. Resolve conflicts / remove new untracked files manually, then retry.
 
 - Cost: Zero (git stash is a local operation)
 - Limitation: Only tracks existing (tracked) files. Newly created files require manual removal.