godotmaker-cli 0.2.0

package/GETTING_STARTED.zh-CN.md

@@ -0,0 +1,346 @@
+# godotmaker-cli 上手测试指南
+
+> English: [GETTING_STARTED.md](./GETTING_STARTED.md)  ·  参考手册：[README.zh-CN.md](./README.zh-CN.md)
+
+这份指南带你完成第一次端到端的测试会话。假设你以前没跑过这个工具。读完之后你会：
+
+1. 在不烧 agent token 的前提下验证你的环境装对了。
+2. 从一句话点子生成一个完整的 Godot 项目。
+3. 摸过所有失败 / 恢复 / 交互路径，真用的时候不会被吓到。
+
+如果你看到的跟这里写的不符，留下 `.godotmaker/` 目录和终端输出，提个 issue。
+
+---
+
+## 0. 环境准备
+
+| 工具 | 版本 | 验证方式 |
+|---|---|---|
+| Node.js | 22+ | `node --version` |
+| Claude Code CLI 或 Codex CLI | latest | `claude --version` 或 `codex --version` |
+| Godot | 4.x | `godot --version`（或者直接打开 GUI） |
+
+选中的 agent 二进制必须在 PATH 上**且**已认证。版本探测跑不通的话，安装对应的 agent CLI 然后重开 shell。
+
+CLI 会在 preflight 时把 GodotMaker framework（`/gm-scaffold`、
+`/gm-gdd`、`/gm-asset`、`/gm-build`、`/gm-verify`、`/gm-evaluate`、
+`/gm-fixgap`、`/gm-accept`、`/gm-finalize`）自动 publish 到项目里，
+版本由 `cliConfig.pinnedGodotmakerVersion` 决定（当前 `v0.5.0`）。
+
+### 安装或运行 CLI
+
+一次性运行用 `npx`；如果你会在多个项目目录里反复测试，可以全局安装：
+
+```bash
+npx godotmaker-cli --help
+# 或者
+npm install -g godotmaker-cli
+```
+
+后面的示例使用全局 `godotmaker-cli` 命令。如果你选择 `npx`，把它替换成
+`npx godotmaker-cli`。
+
+本地开发时，从 checkout 先构建，再按需要链接 workspace 包：
+
+```bash
+cd /path/to/GodotMakerApp
+npm install
+npm run build
+npm link -w godotmaker-cli     # 可选：把 `godotmaker-cli` 注册到系统 PATH
+godotmaker-cli --help
+```
+
+改 repo 代码前先确认测试 + 类型检查是绿的（在 repo root 跑这两条）：
+
+```bash
+npm test           # vitest，快，但**不**做类型检查
+npm run typecheck  # 两个 workspace 跑 tsc --noEmit，包括 test 文件
+```
+
+两条都应该干净退出。`npm test` 走 vitest + esbuild（不做类型检查），单独跑 typecheck 才能抓出 test fixture 的字段缺失和签名漂移。
+
+> 之后想拆掉本地开发链接？在同一个 repo root 跑 `npm unlink -w godotmaker-cli`。
+
+---
+
+## 1. 用 `--dry-run` 做冒烟测试（不烧 token）
+
+Dry-run 用本地 stub 走完完整 9 阶段 pipeline。它能证明你的安装接线正确，不花 agent credit。
+
+```bash
+mkdir test-pong && cd test-pong
+godotmaker-cli --dry-run --auto-start
+```
+
+你应该看到：
+
+- TUI 启动：header、9 行 pipeline 面板、session view、输入栏、footer。
+- header 区出现黄色 `DRY-RUN` 徽章。
+- 每行 stub 跑完依次变 ✓（总共 ≈1 秒）。
+- footer 变绿：`Pipeline complete. Press q or type /quit to exit.`
+
+应该出现的文件：
+
+```
+test-pong/
+├── project.godot              # stub 项目
+├── GDD.md                     # stub 设计文档
+└── .godotmaker/
+    ├── pipeline_state.json    # status: completed
+    ├── stage.jsonl            # 9 个事件，每阶段一个
+    ├── evaluation.json        # result: approve
+    └── final_report.json
+```
+
+按 `q` 或者输入 `/quit` 然后回车退出。
+
+**任何阶段在这里卡住，先停下来修，再继续。** Dry-run 失败说明接线本身坏了。
+
+### 顺手在 dry-run 输出上试 slash 命令
+
+再跑一次不带 `--auto-start` 的 dry-run，输入 `/start`，然后在按 `q` 之前：
+
+- 输入 `/help` 回车 —— 弹出 overlay 列出所有命令和快捷键。
+- 按任意键关闭。
+- 看 TUI 顶部的 Header —— 直接显示当前 iteration N/maxN、build try
+  N/maxN，以及最后一次评估的 verdict（dry-run 走 happy path 显示
+  `✓ approved`，绿色）；下方 PipelinePanel 显示当前 stage。这些信息
+  一直在屏，不需要打开 overlay。
+- 输入 `/peek` 回车 —— dry-run 下没有真正在跑的非交互 agent session 可以
+  尾巴查看，会看到黄色消息 `no active agent session to tail.`。在真实跑
+  的非交互态（build / verify 等）下，这条命令会打开一个 1 Hz 实时刷新
+  的 overlay，显示当前 state 的 stream-json + stderr；按任意键关闭。
+- 只输入 `/`（不带命令名）—— 输入栏下方弹出建议列表，包含所有 slash
+  命令。**Up / Down** 上下选择（环形），**Tab** 把高亮命令补全到输入栏，
+  **Enter** 直接补全并执行高亮命令（`/h` + Enter 直接跑 `/help`）。
+  匹配区分大小写 —— `/H` 不会匹配 `/help`。
+- 输入 `/foo` 回车 —— 建议列表自动隐藏（没匹配），黄色消息：
+  `unknown command: /foo — try /help`。
+- 输入任意字符 —— 消息消失。
+- 输入 `/quit` 回车 —— 任意状态都能退出（运行中按下会顺手 abort
+  当前选中 agent 子进程并把 resume 检查点写入 `pipeline_state.json`，
+  下次启动 `/start` 即可从中断处继续）。
+
+---
+
+## 2. 真实首次跑（一个已认证的 agent 账号，约 10–30 分钟）
+
+```bash
+mkdir my-pong && cd my-pong
+godotmaker-cli
+```
+
+TUI 会在 preflight 后进入 `idle`。输入 `/start` 才会开始；如果要无人值守运行，传 `--auto-start`。
+
+走完 9 个阶段。其中 3 个是交互的：TUI 会把终端交给选中的 agent 会话，那期间你看到的是该 agent 自己的 UI。
+
+### 2a. scaffold（交互）
+
+选中 agent 会问：
+- **游戏名** —— 比如 `Pong`
+- **视角** —— `2D` 或 `3D`
+
+`/gm-scaffold` 跑完后 选中 agent 退出，TUI 重新挂载。scaffold 行变 ✓。
+
+如果项目根目录没出现 `project.godot`，运行会停下。重新检查选中 agent 认证。
+
+### 2b. gdd（交互）
+
+选中 agent 做一段简短的设计访谈（机制、胜利条件、…）。简明回答即可。`GDD.md` 落到项目根目录。
+
+### 2c. asset（自动，约 30 秒 – 2 分钟）
+
+后台跑。session view 实时滚 `[tool] Bash`、`[tool] Read`、`[agent] ...` 这些行。不需要输入。
+
+### 2d. build（自动，最长的阶段）
+
+实际场景 / 脚本就在这里写出来。默认 idle-timeout 是 900 秒。这不是总墙钟超时，只会在选中 agent 连续这么久没有 stdout/stderr 输出时触发。看 session view 估进度；如果 5 分钟以上一动不动，可能卡住了。`Ctrl-C` 中断。
+
+### 2e. verify（自动）
+
+只读检查。pipeline 根据一个做过 freshness 检查的 `stage.jsonl` 事件路由：
+- pass → evaluate
+- fail → build（计入 `maxBuildAttempts`）
+
+### 2f. evaluate（自动）
+
+写出 `.godotmaker/evaluation.json`，包含二元
+`result: "approve" | "reject"` verdict + 分类 issue 数组。看 Header
+的 `eval` 单元格 —— approve 时显示绿色 `✓ approved`，reject 时显示
+黄色 `✗ Nc+Mm`（N/M 分别是 critical / major issue 数量）。
+
+路由：
+- `verdict === "approve"` → **accept**
+- `verdict === "reject"` 且达到最大 iteration → **accept**（agent escape：
+  `/gm-accept` 自己分流——要么放行，要么推荐别的 SKILL，参考 0509 测试报告）
+- 否则 → **fixgap**
+
+### 2g. fixgap（自动，仅在重试时进入）
+
+读最近的评估，把它作为指引喂给一个 build 风格的会话，然后回 verify。这就是 Generator-Evaluator 模式的一整圈。
+
+### 2h. accept（交互）
+
+选中 agent 把项目状态和评估展示给你，然后问决定：
+- `accept` → finalize → 完成
+- `fix` → 再来一圈 fixgap，用你写的反馈作引导
+- `done` → 在 accept 暂停 pipeline；**下次启动从这里恢复**
+
+### 2i. finalize（自动）
+
+`/gm-finalize` 写出 `final_report.json`，包含一致性检查和归档总结。Pipeline 完成；按 `q`。
+
+### 在 Godot 里打开结果
+
+```bash
+godot --path .
+# 或者：godot project.godot
+```
+
+应该能正常加载项目。如果加载就崩，说明 build 在技术上是对的但功能上有问题 —— 这是下次 iteration `/gm-fixgap` 的素材。想多跑几圈就把 `--max-iterations` 调高。
+
+---
+
+## 3. 测试 resume 路径
+
+Resume 是真实使用最常走的路径，验证一下：
+
+```bash
+# 在一个停在 accept（你选了 `done`）的项目里：
+godotmaker-cli
+```
+
+要确认：
+- TUI 重启；已经跑完的行从第 0 帧就显示 ✓。
+- header 显示正确的 `iter N/maxN`。
+- Header 的 `eval` 单元格立刻显示前一次的 verdict（不是 `--`）—— 这是 P1 修复：`restoreContext` 在 resume 时读 `evaluation.json`。
+
+然后测试破坏性路径：
+
+```bash
+godotmaker-cli --fresh
+```
+
+`.godotmaker/` 清空（state、stage 事件、evaluation、report）；你的 `GDD.md`、scenes、scripts 不动。Pipeline 从 scaffold 重启。
+
+---
+
+## 4. 测试交互 handoff 的失败模式
+
+值得戳一戳的边缘情况：
+
+### 4a. 交互阶段中 `Ctrl-C`
+在 `/gm-scaffold`（或 `/gm-gdd` / `/gm-accept`）里面按 `Ctrl-C`。
+被交接出去的 选中 agent 会话退出，控制权回到 cli，cli 的 unmount-cleanup
+钩子写入 resume 检查点后退出。下次启动 `/start` 即可从那个 state 恢复。
+
+### 4b. 自动阶段中 `Ctrl-C`
+`build` 或 `evaluate` 跑的时候按 `Ctrl-C`。Ink 卸载 cli，unmount-cleanup
+钩子 abort 在飞的选中 agent 子进程并把 paused 检查点写入 `pipeline_state.json`。
+下次启动 `/start` 即可从中断处恢复。**不退出只暂停**（cli 保持挂载、
+`/start` 立刻恢复）请改用 `/pause` 命令。
+
+### 4c. 跑到一半按 `q`
+Pipeline 还在跑的时候按 `q`，**没反应** —— `q` 是单键退出快捷键，但
+有意只在非 running 状态（`idle` / `paused` / `finished` / `failed`）
+生效；运行中这一下按键直接落到输入栏。运行中要退出请用 `Ctrl-C` 或
+`/quit`（两条都会 abort 选中 agent 并写检查点）；不退只暂停请用 `/pause`。
+footer 应该提示 `running… (/pause to pause, Ctrl-C to exit; /help for commands)`。
+
+### 4d. 崩溃恢复
+这个手动触发比较难，但如果某个 state 抛了意外错误，`run.tsx` 的 try/catch 兜住，`unmountForCrash()` 干净地拆掉 Ink（终端回到 cooked 模式），栈追踪打到 stderr。需要测的话只能手动注入一个 throw。
+
+---
+
+## 5. 配置
+
+### CLI flags（优先级：CLI > config.yaml > 默认值）
+
+```bash
+node ... --agent codex --max-iterations 5 --model gpt-5.5
+```
+
+用 `--agent claude-code` 或 `--agent codex` 可以只为本次启动选择
+agent runtime，不改项目配置或全局配置。选择优先级是：命令行参数、
+项目配置、CLI 全局配置，最后才是默认 `claude-code`。
+build / evaluate 的默认模型会根据 agent 变化：Claude Code 使用 `opus`，
+Codex 使用 `gpt-5.5`。
+
+### 项目级配置
+
+建 `.godotmaker/config.yaml`：
+
+```yaml
+agent: codex
+pipeline:
+  maxIterations: 5
+  maxBuildAttempts: 3
+  buildModel: gpt-5.5
+  evalModel: gpt-5.5
+```
+
+非交互 agent 会话的 idle-timeout 走全局配置 `~/.godotmaker/cli/config.yaml`
+里的 `idle_timeout_seconds`（默认 900），不在项目级 yaml 里——每个
+workspace 共用同一台机器的"选中 agent 卡住"定义。
+
+### 环境变量
+
+- `GMA_DRY_RUN=1` —— 跟 `--dry-run` 等价。CI 或一次性脚本里好用。
+
+---
+
+## 6. 提 bug 时该带什么
+
+```
+.godotmaker/pipeline_state.json
+.godotmaker/stage.jsonl
+.godotmaker/evaluation.json    # 如果存在
+.godotmaker/final_report.json  # 如果存在
+project.godot                   # 如果存在
+GDD.md                          # 如果存在
+```
+
+加上能往回滚的终端输出。TUI 是实时流的，事后只能靠这些文件 + 你记得卡在哪。
+
+---
+
+## 7. 速查
+
+```bash
+# 第一次，验证安装
+godotmaker-cli --dry-run --auto-start
+
+# 真实跑
+godotmaker-cli
+# 然后在 TUI 输入 /start
+
+# 暂停后恢复
+godotmaker-cli
+
+# 全炸了重头来
+godotmaker-cli --fresh
+
+# 多几次重试
+godotmaker-cli --max-iterations 5
+
+# TUI 里
+/start    # 启动（或 pause 后恢复）pipeline
+/pause    # 暂停正在跑的 pipeline（cli 保持挂载；/start 即可恢复）
+/refresh  # 重置 iteration / build 预算（idle / paused / finished / failed；running 中先 /pause）
+/help     # 命令列表
+/peek     # 实时尾巴查看当前 agent session（仅非交互态有效）
+/usage    # token / 花费 / 时长汇总（当前运行 + 项目累计）
+/quit     # 退出（任意状态）；运行中也会顺手 abort 选中 agent + 写 resume 检查点
+q         # 退出（仅在非 running 状态生效，且输入栏需为空）；走的是 /quit 同一条检查点路径
+Ctrl-C    # 退出（任意状态）；运行中按下会同时 abort 选中 agent + 写 resume 检查点
+Esc       # 清空输入栏
+```
+
+---
+
+## 接下来
+
+- 参考文档：[`README.zh-CN.md`](./README.zh-CN.md)
+- 设计 / 内部：[`../docs/design/cli-design.md`](../docs/design/cli-design.md)
+- Roadmap：[`../ROADMAP.md`](../ROADMAP.md)
+- 上游 skill 源码：[GodotMaker](https://github.com/RandallLiuXin/GodotMaker)

package/LICENSE

@@ -0,0 +1,48 @@
+GodotMakerApp CLI License
+
+Copyright (c) Randall Liu Xin.
+All rights reserved.
+
+GodotMakerApp CLI and its included runtime code are proprietary software.
+This license grants you a limited, non-exclusive, non-transferable right to
+install and use official copies of the software distributed by Randall Liu Xin
+or GodotMakerApp for creating, testing, and managing Godot game projects.
+
+You may not:
+
+- copy, redistribute, sublicense, sell, rent, lease, or host the software for
+  third-party use;
+- reverse engineer, decompile, disassemble, or attempt to derive the source
+  code, except where this restriction is not permitted by applicable law;
+- remove or bypass license, access-control, telemetry, or protection
+  mechanisms;
+- use the software, its workflow, or its runtime code to build or operate a
+  competing commercial game-generation, automation, or agent-platform product;
+- publish modified versions of the software or package it into another product
+  without prior written permission.
+
+Generated Output
+----------------
+
+GodotMakerApp CLI does not claim ownership of game projects, source code,
+assets, design documents, screenshots, reports, or other output generated in
+your target project. Subject to any third-party rights, provider terms, asset
+licenses, or model-service terms that may apply, those project outputs belong
+to you.
+
+Separate Components
+-------------------
+
+The upstream GodotMaker framework, third-party packages, Godot Engine, agent
+CLIs, model providers, and generated project dependencies are governed by their
+own licenses and terms. This license applies only to GodotMakerApp CLI and its
+included runtime code.
+
+No Warranty
+-----------
+
+The software is provided "as is", without warranty of any kind, express or
+implied, including but not limited to warranties of merchantability, fitness for
+a particular purpose, and non-infringement. In no event shall the copyright
+holder be liable for any claim, damages, or other liability arising from use of
+the software.

package/README.md

@@ -0,0 +1,240 @@
+# godotmaker-cli
+
+> 中文版：[README.zh-CN.md](./README.zh-CN.md)  ·  Hands-on testing guide: [GETTING_STARTED.md](./GETTING_STARTED.md) ([中文](./GETTING_STARTED.zh-CN.md))
+
+Pipeline driver for [GodotMaker](https://github.com/RandallLiuXin/GodotMaker) — an AI-assisted text-to-Godot game generator. This package ships an Ink TUI that orchestrates the upstream `/gm-*` skill chain across independent selected-agent sessions, so you can `cd` into an empty folder, run one command, and watch a Godot project build itself.
+
+> Proprietary. You may install and use official copies to create Godot game
+> projects. Redistribution, reverse engineering, and competing commercial
+> platform use are not permitted. Generated game projects and assets belong to
+> you; see [LICENSE](./LICENSE).
+
+---
+
+## Requirements
+
+| Tool | Version | Purpose |
+|---|---|---|
+| Node.js | 22+ | Runs the CLI (Ink 7 requires Node 22 or newer) |
+| [Claude Code CLI](https://docs.claude.com/en/docs/claude-code) or Codex CLI | latest | The selected agent binary must be on your PATH |
+| [Godot](https://godotengine.org/) | 4.x | Runs the generated project |
+
+The CLI auto-publishes the GodotMaker framework into each project during preflight; the framework version is pinned by `cliConfig.pinnedGodotmakerVersion` (currently `v0.5.0`).
+
+---
+
+## Install
+
+```bash
+npx godotmaker-cli
+# or install it globally
+npm install -g godotmaker-cli
+```
+
+For local development from a checkout:
+
+```bash
+npm install
+npm run build
+node cli/dist/run.js --help
+```
+
+The examples below use the global `godotmaker-cli` command. If you are
+using `npx`, replace it with `npx godotmaker-cli`.
+
+---
+
+## Quick start
+
+```bash
+mkdir my-pong-game && cd my-pong-game
+godotmaker-cli
+```
+
+The TUI launches in `idle` after preflight. Type `/start` to walk the
+9-stage pipeline; press **q** to exit after it finishes. Pass
+`--auto-start` when you want the run to begin immediately.
+
+```
+┌─ godotmaker-cli ───────────────────────────────────┐
+│ /home/user/my-pong-game                            │
+│ iter 1/3   build 1/3   eval --                     │
+├────────────────────────────────────────────────────┤
+│ ✓  scaffold     0:04                               │
+│ ✓  gdd          1:12                               │
+│ ✓  asset        0:38                               │
+│ ▶  build        0:21                               │
+│    verify       --                                 │
+│    evaluate     --                                 │
+│    fixgap       --                                 │
+│    accept       --                                 │
+│    finalize     --                                 │
+├─ session ──────────────────────────────────────────┤
+│ [tool] Bash                                        │
+│ [agent] Implementing Pong scene per PLAN.md...     │
+│ [tool] Write src/Ball.gd                           │
+└────────────────────────────────────────────────────┘
+running… (/pause to pause, Ctrl-C to exit; /help for commands)
+```
+
+### Interactive stages
+
+`scaffold`, `gdd`, and `accept` need user input (game name, design questions, accept / fix / done decision). When the pipeline reaches one, the TUI **suspends**, hands the terminal to a fresh selected-agent session, and **resumes** when that session exits — same pattern as `git commit` opening `$EDITOR`. There is a brief screen flicker; this is expected.
+
+### Lifecycle
+
+The cli launches into an `idle` state showing the preflight summary
+(framework version, selected agent probe, pipeline knobs). Type `/start` to
+begin. After a pause, `/start` resumes from the interrupted state.
+Pass `--auto-start` to skip the idle screen — implicitly enabled when
+stdin is not a TTY (CI, piped automation).
+
+### Hotkeys
+
+| Key | Effect |
+|---|---|
+| `q` | Quit when the input bar is empty AND the pipeline is not running (works in idle / paused / finished / failed) |
+| `Ctrl-C` | Exit. During a running pipeline, the cli's unmount-cleanup hook also aborts the active selected agent child and writes a resume checkpoint to `pipeline_state.json` so the next `godotmaker-cli` launch can `/start` from where you stopped. To pause WITHOUT exiting (cli stays mounted, you can `/start` immediately to resume), use the `/pause` slash command instead. |
+
+### Slash commands
+
+There is an always-on input bar at the bottom of the TUI. Type one of
+the following and press `Enter`:
+
+| Command | Effect |
+|---|---|
+| `/help` | Show all commands and hotkeys |
+| `/start` | Begin (or resume, after a pause) the pipeline |
+| `/pause` | Pause the running pipeline; the next `/start` resumes |
+| `/refresh` | Reset iteration / build budget for the current run; allowed in idle / paused / finished / failed (during a run, `/pause` first) |
+| `/peek` | Live tail (1 Hz) of the active non-interactive agent stream log |
+| `/usage` | Token / cost / time totals for this run + project lifetime |
+| `/quit` | Exit. During a run, also aborts the selected agent and writes a resume checkpoint (same path as Ctrl-C); next `godotmaker-cli` launch can `/start` to continue. |
+
+The current iteration / build try / last evaluation verdict are
+shown in the Header at the top of the TUI; there is no separate
+overlay for them. The eval cell shows `✓ approved` (green) on
+approve, `✗ Nc+Mm` (yellow, where N/M are critical/major issue
+counts) on reject, or `--` until `/gm-evaluate` runs.
+
+Any keystroke dismisses an open overlay. `Esc` clears the input buffer.
+Unknown input shows a transient message until the next keystroke.
+
+Typing `/` opens a live suggestion popup directly under the input bar
+listing every command whose name starts with what you've typed. **Up /
+Down** navigate (wrap-around), **Tab** completes the highlighted command
+into the buffer without executing, **Enter** auto-completes-and-runs the
+highlighted command (so `/h` + Enter runs `/help`). The match is
+case-sensitive — `/H` shows nothing, mirroring the parser. If the
+prefix has no matches the popup hides; pressing Enter then surfaces the
+usual `unknown command — try /help` message.
+
+`/peek` is only useful in non-interactive states (build / verify /
+asset / evaluate / fixgap / finalize) where the selected agent runs in non-interactive mode
+under the cli's control. In interactive states (scaffold / gdd /
+accept) the interactive agent has the terminal directly so the cli has nothing to
+peek into; the overlay shows "no active agent session to tail" if
+you invoke it then. The overlay refreshes once per second; press any
+key to dismiss.
+
+`/usage` shows three sections: **this run** (live token / output /
+duration / cost broken down per state), **project lifetime**
+(cumulative since the first run), and **recent runs** (the last 10
+completed runs as one row each). Tokens and dollar amounts come from
+the selected agent's stream or local session records. Cost is only
+shown when the selected agent reports it; otherwise it stays `--`.
+Persisted to `.godotmaker/usage.json` next to `pipeline_state.json`
+— copy that file along with the project to keep history when moving
+the project elsewhere. Interactive states (scaffold / gdd / accept)
+recover token usage best-effort from local session records and always
+contribute duration. The Header panel always shows the current-run
+total in shorthand; use `/usage` to drill in.
+
+---
+
+## Flags
+
+| Flag | Effect |
+|---|---|
+| `--agent <claude-code\|codex>` | Select the agent runtime for this launch, overriding project and CLI-global config |
+| `--max-iterations <n>` | Cap on Generator-Evaluator iterations (default `3`) |
+| `--model <name>` | Override agent model for build / evaluate (default depends on `--agent`) |
+| `--fresh` | Wipe saved state and start over |
+| `--dry-run` | Walk the pipeline without spawning an agent (writes stub artifacts; useful for CI / wiring checks) |
+| `-h`, `--help` | Show help and exit |
+
+Agent selection resolves in this order: `--agent`, per-project
+`.godotmaker/config.yaml`, `~/.godotmaker/cli/config.yaml`, then the
+default `claude-code`.
+
+Idle-timeout for spawned non-interactive agent sessions (default 900s = 15 min) is
+configured in `~/.godotmaker/cli/config.yaml` via `idle_timeout_seconds`,
+not as a CLI flag. The timer resets on every stdout/stderr chunk; only
+genuine silence triggers a kill.
+
+---
+
+## What the pipeline writes
+
+Everything lives under `.godotmaker/` inside your project:
+
+| File | Owner | Purpose |
+|---|---|---|
+| `pipeline_state.json` | Core | Resume checkpoint (current state, iteration, build attempts) |
+| `stage.jsonl` | upstream skills | One line per `/gm-*` completion; freshness-checked by Core |
+| `evaluation.json` | `/gm-evaluate` | Latest binary verdict + categorized issues; routes evaluate → accept / fixgap |
+| `final_report.json` | `/gm-finalize` | Summary at the end of a successful run |
+| `usage.json` | Core | Token / cost / time history surfaced by `/usage` (lifetime totals + last 10 runs) — see R-314 |
+| `config.yaml` | (optional, you) | Per-project flag defaults — see `loadConfig` in core |
+
+The Godot project itself (`project.godot`, `GDD.md`, `PLAN.md`, scenes, scripts, …) lives at the project root and is owned by the upstream skills. Core never writes to those.
+
+---
+
+## Resume vs fresh
+
+By default, re-running `godotmaker-cli` in the same directory **resumes** at the saved checkpoint:
+
+```bash
+godotmaker-cli           # picks up where the last run left off
+```
+
+To start over:
+
+```bash
+godotmaker-cli --fresh   # deletes pipeline_state.json + stage.jsonl + evaluation.json + final_report.json
+```
+
+User-authored files (`GDD.md`, `PLAN.md`, scenes, scripts) are never touched by `--fresh`.
+
+---
+
+## Dry-run mode
+
+`--dry-run` (or `GMA_DRY_RUN=1`) tells the CLI to walk the full state graph **without spawning an agent**. Stub handlers write the artifacts each `/gm-*` skill would have produced (`project.godot`, `GDD.md`, `evaluation.json`, `final_report.json`, plus `stage.jsonl` events) so the pipeline reaches `finalize`. Use it to:
+
+- verify your install (Node / paths / config) without burning tokens
+- pre-flight CI plumbing
+- demonstrate the TUI without an agent account
+
+Stubs always pick the happy path (`verify=pass`, `evaluate=approve`, `accept=accept`); to exercise fail / fixgap branches you need a real selected-agent session.
+
+---
+
+## Troubleshooting
+
+**Selected agent CLI not found on PATH** — Install the selected agent CLI and re-launch your terminal. Verify with `claude --version` or `codex --version`.
+
+**Pipeline halts at scaffold with no project.godot** — `/gm-scaffold` exited non-zero. Check that the upstream skills are installed and that the selected agent is authenticated.
+
+**Stale stage events being read after a crashed run** — Run with `--fresh` to clear `.godotmaker/stage.jsonl` and start over.
+
+**TUI looks broken / line wraps** — The TUI requires a real TTY. Piping output (`godotmaker-cli | tee log`) or running under a CI runner without a PTY is not currently supported.
+
+---
+
+## Links
+
+- Upstream framework: [GodotMaker](https://github.com/RandallLiuXin/GodotMaker)
+- Roadmap: [`ROADMAP.md`](https://github.com/RandallLiuXin/GodotMakerApp/blob/main/ROADMAP.md) (private)
+- Design notes: [`docs/design/cli-design.md`](https://github.com/RandallLiuXin/GodotMakerApp/blob/main/docs/design/cli-design.md) (private)