@seanyao/roll 4.630.1 → 4.702.2

package/guide/en/feedback.md

@@ -0,0 +1,31 @@
+# Feedback And Issue Capture
+
+Roll keeps two feedback paths deliberately separate:
+
+- Use `roll idea "<one sentence>"` when the input should become a local Roll backlog card.
+- Use `gh issue create` when the input belongs in GitHub Issues for a public repo or cross-project tracker.
+
+## Local Roll Backlog
+
+```bash
+roll idea "Safari login fails after the session cookie expires"
+roll idea "Add dark mode to the story report archive"
+```
+
+`roll idea` classifies the note, assigns the next ID, infers the epic, mints
+the card folder, appends the backlog row, and refreshes the index. It is the
+normal project-owner entry for turning quick feedback into tracked Roll work.
+
+## GitHub Issues
+
+For public bug reports or external collaboration, call GitHub directly:
+
+```bash
+gh issue create \
+  --repo owner/repo \
+  --title "Login fails on Safari" \
+  --body "Repro: 1. ... 2. ..."
+```
+
+Use labels such as `bug`, `idea`, `enhancement`, `FIX`, or `US` if your project
+board routes issues into Roll backlog work.

package/guide/en/getting-started.md

@@ -0,0 +1,103 @@
+# Roll — Getting Started
+
+This path gets one Roll-managed project from install to acceptance evidence in
+about five minutes. Run it in a git repository.
+
+## 1. Install
+
+```bash
+curl -fsSL https://seanyao.github.io/roll/install | bash
+# or
+npm install -g @seanyao/roll
+```
+
+Roll needs Node.js 22 or newer and at least one supported local AI agent.
+
+## 2. Initialize The Project
+
+```bash
+cd your-project
+roll setup
+roll init
+```
+
+`roll init` diagnoses the directory before it writes anything. Empty projects use
+the fresh scaffold path; existing codebases route to `$roll-onboard`; PRD/docs-only
+projects point to design as a new-project path; partial or old Roll layouts print
+repair/migration guidance without changing files.
+
+## 3. Go from Requirements to a Backlog
+
+If you have requirement docs (a PRD, sketches, notes) but no source yet, `roll
+init` classifies that as a PRD-only new project and points you toward design.
+`roll status` and `roll doctor` still show the design nudge after a Roll scaffold
+exists with an empty backlog.
+
+To start an interactive design session right away:
+
+```bash
+roll design --from-file docs/PRD.md
+```
+
+Use the exact `roll design --from-file ...` command printed by `roll init` when
+it detects a PRD. Without a file, `roll design` still launches the same
+`roll-design` skill in your AI agent. You talk through the domain model, the
+agent writes INVEST stories into `.roll/backlog.md`, and detailed design notes
+get a self-contained `design-review.html` Design Review Page — then `roll loop`
+takes over.
+
+You can also run `$roll-design` directly inside your agent if you prefer.
+
+If you already have a story in mind and just want to add it fast, skip to step 4.
+
+## 4. Add One Backlog Item
+
+Add a small story card with one sentence:
+
+```bash
+roll idea "Add a health check endpoint"
+```
+
+`roll idea` auto-classifies, assigns an id, infers the epic, and creates the
+card folder — you get both the backlog row and the story folder in one step.
+
+Then edit `.roll/features/<epic>/<ID>/spec.md` so the ACs describe what
+"done" means.
+
+Keep the first story tiny: one visible behavior, one clear test path.
+
+## 5. Start The Loop
+
+```bash
+roll loop on
+roll loop status
+```
+
+`roll loop status` is the normal snapshot view. If a cycle is running and you
+want the live view, start with the read-only watch command:
+
+```bash
+roll loop watch
+```
+
+Use `roll loop watch --events` for compact event debugging and
+`roll loop watch --raw-events` only when you need raw audit JSON. All watch
+modes are read-only; Ctrl-C stops only the view.
+
+For an immediate local cycle instead of waiting for the schedule:
+
+```bash
+roll loop now
+```
+
+## 6. Render Acceptance Evidence
+
+After the story lands and the backlog row is `✅ Done`, render the offline
+acceptance report:
+
+```bash
+roll attest US-DEMO-001
+```
+
+The report is written into that story folder under `.roll/features/`. Each AC
+should have a verdict and evidence link before a release.

package/guide/en/installation.md

@@ -0,0 +1,86 @@
+# Roll — Installation & Updates
+
+## Install
+
+### curl (recommended)
+
+```bash
+curl -fsSL https://seanyao.github.io/roll/install | bash
+```
+
+No prerequisites beyond bash 3.2+, curl, and tar — all preinstalled on macOS and Linux.
+
+To pin a specific version:
+
+```bash
+curl -fsSL https://seanyao.github.io/roll/install | ROLL_VERSION=v3.610.1 bash
+```
+
+### npm
+
+```bash
+npm install -g @seanyao/roll
+```
+
+Requires Node.js 16+.
+
+After installation via either method, run setup to sync conventions and skills into your AI tools:
+
+```bash
+roll setup
+```
+
+## Verify
+
+```bash
+roll --version   # print installed version
+roll status      # show resolved paths and convention state
+```
+
+## Update
+
+```bash
+roll update
+```
+
+Roll detects how it was installed and acts accordingly:
+
+| Install mode | What `roll update` does |
+|---|---|
+| curl (default) | Re-downloads the latest tarball, extracts atomically, then `roll sync` |
+| npm | `npm update -g @seanyao/roll`, then `roll sync` |
+| git clone (contributors) | `git pull` in the package directory, then `roll sync` |
+
+## Automatic Version Nudge
+
+After each `roll` command, a background check queries the GitHub releases API
+(at most once per 24 h, cached at `~/.roll/.update-check`). If a newer version
+is available, a one-line nudge appears at the end of the next command's output.
+The check is fire-and-forget — it never delays your command.
+
+## Uninstall
+
+### curl
+
+```bash
+rm -rf ~/.local/share/roll ~/.local/bin/roll
+```
+
+### npm
+
+```bash
+npm uninstall -g @seanyao/roll
+```
+
+Remove state files afterward if you no longer need them:
+
+```bash
+rm -rf ~/.roll ~/.shared/roll
+```
+
+## See Also
+
+- [overview.md](overview.md) — what roll is
+- [project-setup.md](project-setup.md) — `roll init` for a new project
+- [configuration.md](configuration.md) — environment variables
+- [SECURITY.md](../../SECURITY.md) — curl|bash trust boundary and version pinning

package/guide/en/legacy-onboarding.md

@@ -0,0 +1,195 @@
+# Existing Codebase Onboarding
+
+> Adopt Roll on an existing codebase without breaking your team's current workflow.
+
+This page keeps the `legacy-onboarding.md` path for link stability. The visible
+workflow name is **Existing Codebase Onboarding**.
+
+If you have a real project that's been alive for a while — code, tests, history, conventions, the works — and you want to start using Roll on it, this is your path.
+
+## Three modes of adoption
+
+| Mode | Use when | Trade-off |
+|------|----------|-----------|
+| **Seed** | You're starting a brand-new project | Lowest friction; specs/backlog from day 1 |
+| **Graft** (this page) | You have a live existing codebase that keeps evolving | Zero intrusion on existing code; Roll layered on top |
+| **Replant** | You want a clean rewrite, debt cleared | Higher effort; you reverse-engineer specs first |
+
+This page covers **graft**. For seed vs. replant, see [adoption patterns](https://github.com/seanyao/roll-meta) (maintainer-only repo, public summary in the README).
+
+## What graft does
+
+- **Reads** your project to understand type, domains, and key modules
+- **Asks** you 9 questions in ≤ 3 minutes
+- **Generates** a `.roll/` directory alongside your existing code (no source files touched)
+- **Syncs** Roll conventions to whichever AI tools you use
+- Leaves you with a project that has BOTH its original workflow AND Roll's project-management capabilities
+
+The graft is **fully reversible**: run `roll setup offboard` and Roll undoes exactly what it added (see [How to exit](#how-to-exit) below).
+
+## Step by step
+
+### 1. Install Roll
+
+```bash
+curl -fsSL https://seanyao.github.io/roll/install | bash
+```
+
+Or via npm:
+
+```bash
+npm install -g @seanyao/roll@latest
+```
+
+Then:
+
+```bash
+roll setup
+```
+
+### 2. Run `roll init` in your project
+
+```bash
+cd your-project
+roll init
+```
+
+Roll detects this as an existing codebase without Roll (source/manifests exist, but no current Roll markers). It will print something like:
+
+```
+Detected: existing codebase without Roll
+Recommended path: agentic-onboard
+Facts:
+  - manifests: package.json
+  - source dirs: src
+  - test dirs: tests
+  - source files: 47
+  - Roll markers: none
+  - facts hash: sha256:...
+Next: $roll-onboard
+Agent status: available: claude, codex
+Run `$roll-onboard` with an available agent, review the artifacts, then run `roll init --apply`.
+No files changed.
+```
+
+### 3. Run `$roll-onboard` in your AI agent
+
+Open the agent of your choice (Claude Code, Codex CLI, Cursor, etc.) and run:
+
+```
+$roll-onboard
+```
+
+The skill will:
+1. Walk your repository and tell you what it sees
+2. Confirm the inferred project type, domains, key modules (group 1: 3 questions)
+3. Ask which `.roll/` artifacts to generate and which existing docs to include (group 2: 3 questions)
+4. Ask about `.gitignore`, AI tool sync, and loop activation (group 3: 3 questions)
+5. Write exactly two structured artifacts: `.roll/init-diagnosis.yaml` and `.roll/onboard-plan.yaml`
+
+Total time: under 3 minutes.
+
+### 4. Apply the plan
+
+Back in your terminal, review `.roll/init-diagnosis.yaml` and `.roll/onboard-plan.yaml`, then run:
+
+```bash
+roll init --apply
+```
+
+This validates the paired diagnosis/plan artifacts before writing anything. It rejects unsupported schema versions, stale facts hashes, non-idempotent file operations, path traversal, and shell-command keys.
+
+After validation, Roll prints an apply review checkpoint. The table lists every
+planned operation with action, target path, merge/create mode, and whether owner
+content is preserved. In an interactive terminal, Roll waits for confirmation
+before writing any reviewed mutation.
+
+For non-interactive automation, use the explicit review acknowledgement after you have reviewed the artifacts:
+
+```bash
+roll init --apply --auto
+```
+
+After validation passes, Roll:
+- Creates `.roll/` subdirectories per your scope choices
+- Generates a starter `.roll/backlog.md` if you said yes
+- Includes (not regenerates) the existing docs you flagged
+- Adds `.roll/` to `.gitignore` if you said yes
+- Syncs Roll conventions to the AI tools you picked
+
+Done. Run `roll next` to continue with the next action.
+
+### 5. (Optional) Turn on autonomous loop
+
+If you said "yes" to Q9, `roll loop on` activates the autonomous executor on a cron schedule. It picks up `📋 Todo` items from `BACKLOG.md` and runs `$roll-build` / `$roll-fix` on them.
+
+## The graft boundary
+
+Roll only touches **its own** files inside your project:
+
+| Touched by Roll | Not touched by Roll |
+|-----------------|---------------------|
+| `.roll/` (all contents) | `src/`, `lib/`, `tests/`, etc. — your code |
+| `AGENTS.md` (created if missing; section-merged if exists) | `README.md` |
+| `.gitignore` (only if you said yes to Q7) | `package.json`, `pyproject.toml`, etc. |
+
+If you've already got a `CONTRIBUTING.md` or a `.github/` workflow, Roll won't reach into them. If you want Roll's workflow integrated with yours, that's a manual step you do later.
+
+`$roll-onboard` itself has a stricter boundary than `roll init --apply`: the agent may only write `.roll/init-diagnosis.yaml` and `.roll/onboard-plan.yaml`. The apply command owns `AGENTS.md`, `.gitignore`, backlog, features, docs, and offboard changesets.
+
+## How to exit
+
+`roll init --apply` records every Roll-owned file, directory, merged marker block, and `.gitignore` line it adds into `.roll/onboard-changeset.yaml`. Re-running the same plan keeps that metadata and deduplicates entries instead of losing the original offboard record. If apply fails midway, inspect the changeset and run `roll setup offboard --confirm` after review to reverse Roll-owned artifacts.
+
+Existing `AGENTS.md` files are preserved. Roll appends its managed sections between stable `<!-- roll:onboard:start -->` / `<!-- roll:onboard:end -->` markers so offboard can strip only those sections later.
+
+**Preview what will be undone (default):**
+
+```bash
+cd your-project
+roll setup offboard
+```
+
+This is a dry-run — no files are removed. The output lists every artefact the changeset recorded and the `.gitignore` lines that will be reverted.
+
+**Apply the rollback:**
+
+```bash
+roll setup offboard --confirm
+```
+
+Files and directories that Roll did not create are left untouched. Marker-wrapped Roll sections are removed from existing owner files without deleting the file. Lines you added to `.gitignore` yourself are preserved. The changeset file itself is removed at the end of a successful apply.
+
+Safety:
+
+- If `.roll/onboard-changeset.yaml` is missing (e.g. you ran an earlier Roll version that didn't track it, or the project was never onboarded with `roll init --apply`), `roll setup offboard` refuses and prints the manual `rm` commands instead. It will never guess.
+- If the changeset names paths that resolve outside the current project (cross-project contamination), `roll setup offboard` refuses and tells you to run it in the right directory.
+
+**Full uninstall (machine-wide):**
+
+```bash
+roll setup offboard --confirm
+npm uninstall -g @seanyao/roll
+```
+
+Your project is now exactly as it was before adoption.
+
+## FAQ
+
+**Q: What if I don't have an AI agent installed?**
+You need at least one. Install Claude Code, Codex CLI, or Cursor — they're free to install (the AI calls cost tokens via your account).
+
+**Q: What if I already have a `BACKLOG.md` from another tool?**
+Roll detects this as a pre-2.0 Roll project (not an existing-codebase onboard target) and tells you to run `npx @seanyao/roll@2 migrate`. If the file came from a totally different tool, rename it first (`mv BACKLOG.md old-backlog.md`) then run `roll init`.
+
+**Q: Roll-onboard infers my project type wrong — what do I do?**
+Tell the skill in chat. Group 1 questions exist specifically so you can correct misidentification. The skill writes the corrected understanding into the plan; bash trusts the plan.
+
+**Q: Can I edit `.roll/onboard-plan.yaml` manually?**
+Yes, but keep it paired with `.roll/init-diagnosis.yaml`. `roll init --apply` requires matching `factsHash` values, recomputes the current facts hash, allows no shell-command keys, and only accepts the two idempotent `file_operations` entries rooted inside the project. Plans older than 24 hours, stale against the current project, or generated by older `$roll-onboard` contracts should be regenerated.
+
+Manual edits still pass through the same review checkpoint; without interactive
+confirmation or explicit `--auto`, no files are changed.
+
+**Q: My team uses GitHub Issues / Jira / Linear — does Roll replace them?**
+No. Roll's `BACKLOG.md` is for AI-driven autonomous execution. Your team's external tracker stays where it is. Some teams use Roll only for new stories that are AI-loop-executable and keep human-only work in their existing tracker.

package/guide/en/loop-data-layout.md

@@ -0,0 +1,256 @@
+# Loop Data Layout (Phase 2.0)
+
+Starting with Phase 2.0, a project's own loop runtime data lives **inside the
+project** at `<project>/.roll/loop/`, not under your home directory. Only the
+machine-level binding files (launchd runners, attach scripts) stay in
+`~/.shared/roll/loop/`.
+
+从 Phase 2.0 起，项目自己的 loop 运行时数据搬进了**项目目录** `<project>/.roll/loop/`，
+不再放在家目录下。只有机器级的绑定文件（launchd runner、attach 脚本）留在
+`~/.shared/roll/loop/`。
+
+This means: move the project, the state moves with it. Delete the project, the
+state goes too. `git status` and your IDE can see the loop's control and data
+files alongside your code.
+
+也就是说：项目挪走，状态跟着走；项目删掉，状态也一起没了。`git status` 和你的
+IDE 能在代码旁边看到 loop 的控制与数据文件。
+
+---
+
+## What lives in `<project>/.roll/loop/`
+
+What lives in `<project>/.roll/loop/`:
+
+`<project>/.roll/loop/` 里放什么：
+
+| File | Plane | Content |
+|------|-------|---------|
+| `state-<slug>.yaml` | control | Current/last run: status, story, agent, run_id |
+| `ALERT-<slug>.md` | control | Accumulated alerts (failures, TCR violations) |
+| `PAUSE-<slug>` | control | Pause marker (created by `roll loop pause`) |
+| `mute-<slug>` | control | Per-project auto-attach mute marker |
+| `.LOCK-<slug>` | control | Single-runner lock for this project |
+| `heartbeat` | control | Liveness timestamp for the running cycle |
+| `runs.jsonl` | data | Append-only run history (one JSON line per cycle) |
+| `events.ndjson` | data | Per-cycle event stream (phase_start/phase_end, …) |
+| `cron.log` | data | Legacy aggregate cycle log (see deprecation note below) |
+
+The control plane (what the outer runner touches before spawning tmux) and the
+data plane (what the inner cycle script writes) ship independently, but both now
+resolve to the same project-local directory.
+
+控制平面（outer runner 在 spawn tmux 之前接触的）和数据平面（inner cycle 脚本写
+入的）各自独立演进，但现在都解析到同一个项目本地目录。
+
+---
+
+## Dream cron logs
+
+`roll-.dream` (the nightly code-health scan) also writes its cron stdout capture
+project-local:
+
+| Service | Path |
+|---------|------|
+| dream | `<project>/.roll/dream/cron.log` |
+
+Previously this lived in `~/.shared/roll/dream/cron-<slug>.log`.
+Moving it project-local means it is naturally garbage-collected when
+the project is deleted, and concurrent projects never interleave.
+
+`roll-.dream`（每晚代码健康扫描）的 cron stdout 捕获日志也改为项目本地：
+
+| 服务 | 路径 |
+|------|------|
+| dream | `<project>/.roll/dream/cron.log` |
+
+以前放在 `~/.shared/roll/dream/cron-<slug>.log`。项目本地后，删项目即
+清日志，并发项目也不会互相穿插。
+
+---
+
+## What is left in `~/.shared/roll/loop/`
+
+What is left in `~/.shared/roll/loop/`:
+
+`~/.shared/roll/loop/` 现在只剩：
+
+| File | Why it stays |
+|------|--------------|
+| `run-<slug>.sh` / `run-<slug>-inner.sh` | launchd `WorkingDirectory` / `ProgramArguments` bind to absolute home paths |
+| `attach-<slug>.command` | LaunchServices double-click target; must be a stable home path |
+| `worktrees/` | machine-scoped scratch, not project-intrinsic |
+| `changelog-audit*` | machine-level audit log |
+| `archived/` | `roll loop gc` parking lot for retired slugs |
+
+`~/.shared/roll/mute` (the global mute switch shared across all projects and all
+autonomous activity) also stays in home — it is intentionally machine-wide.
+
+`~/.shared/roll/mute`（所有项目、所有自动化活动共享的全局静音开关）也留在家目录 ——
+它本来就是机器级的。
+
+---
+
+## Cross-project dashboard
+
+`roll loop runs --all` no longer reads one machine-wide `runs.jsonl`. Instead it:
+
+`roll loop runs --all` 不再读单个机器级的 `runs.jsonl`，而是：
+
+1. Enumerates installed slugs from launchd plists.
+2. Resolves each slug to its project path, reads that project's
+   `.roll/loop/runs.jsonl`.
+3. Merges every project's rows with `jq` and sorts by timestamp.
+
+1. 从 launchd plist 枚举已安装的 slug。
+2. 把每个 slug 解析到它的项目路径，读该项目的 `.roll/loop/runs.jsonl`。
+3. 用 `jq` 把所有项目的行归并，按时间排序。
+
+So you still get a machine-wide overview, computed live from per-project files —
+no central file to drift out of sync.
+
+所以你照样能看到机器级总览，只是改为从各项目文件实时聚合 —— 没有会失同步的中心文件。
+
+The optional cache hook `ROLL_LOOP_RUNS_CACHE_TTL` (default `0` = no cache) is
+reserved for future use; aggregation is live today.
+
+可选的缓存钩子 `ROLL_LOOP_RUNS_CACHE_TTL`（默认 `0` = 不缓存）为未来预留；目前是
+实时聚合。
+
+---
+
+## Automatic migration (7-day dual-path window)
+
+If you upgrade an existing project, **you do not need to do anything**. The
+outer runner migrates legacy files automatically on the next cycle.
+
+如果你升级一个既有项目，**无需任何手动操作**。outer runner 会在下一个 cycle 自动
+迁移老文件。
+
+**How it works:**
+
+**工作原理：**
+
+1. Before reading any control state, the runner calls
+   `the legacy-path migration helper <slug>`. It copies `state-<slug>.yaml`,
+   `ALERT-<slug>.md`, `PAUSE-<slug>`, and `mute-<slug>` from
+   `~/.shared/roll/loop/` into `<project>/.roll/loop/`, then renames each legacy
+   file to `<name>.migrated-<timestamp>`.
+2. `runs.jsonl` is migrated by `the legacy-runs migration helper`: the machine-wide
+   file is split by each row's `project` slug into the matching project's
+   `.roll/loop/runs.jsonl`, then renamed `runs.jsonl.migrated-<timestamp>`. Rows
+   whose slug cannot be resolved are left behind so no history is lost.
+3. Migration is **idempotent** — the `.migrated-*` rename makes a re-run a
+   no-op, and an existing newer target is never overwritten.
+
+1. 读任何控制状态之前，runner 调用 `the legacy-path migration helper <slug>`，把
+   `state-<slug>.yaml`、`ALERT-<slug>.md`、`PAUSE-<slug>`、`mute-<slug>` 从
+   `~/.shared/roll/loop/` 复制进 `<project>/.roll/loop/`，再把每个老文件改名为
+   `<name>.migrated-<时间戳>`。
+2. `runs.jsonl` 由 `the legacy-runs migration helper` 迁移：机器级文件按每行的 `project`
+   slug 拆分进对应项目的 `.roll/loop/runs.jsonl`，再改名
+   `runs.jsonl.migrated-<时间戳>`。无法解析 slug 的行会留在原处，不丢历史。
+3. 迁移**幂等** —— `.migrated-*` 改名让重跑变成 no-op，已存在的更新目标永不被覆盖。
+
+**During the 7-day window**, reads of control-plane files use dual-path lookup
+(`the control-state path resolver`): the project-local path is preferred, falling back
+to the legacy home path. After the window, a separate FIX removes the fallback.
+
+**在 7 天窗口期内**，控制平面文件的读取走双路查找（`the control-state path resolver`）：
+优先项目本地路径，回退到家目录老路径。窗口结束后由单独的 FIX 移除回退。
+
+The `.migrated-*` and `runs.jsonl.migrated-*` artifacts are reaped by
+`roll loop gc` after they age out (see below), so home never accumulates debris.
+
+`.migrated-*` 和 `runs.jsonl.migrated-*` 残骸到期后由 `roll loop gc` 回收（见下），
+家目录不会堆积。
+
+---
+
+## `roll loop gc` — garbage collection
+
+`roll loop gc` retires slugs whose project directory no longer exists, and
+sweeps migration/backup debris.
+
+`roll loop gc` 退役那些项目目录已不存在的 slug，并清扫迁移/备份残骸。
+
+```bash
+roll loop gc                  # GC orphan slugs + debris (default: keep 30 days)
+roll loop gc --dry-run        # Preview what would be removed — touches nothing
+roll loop gc --keep-days 14   # Override retention for this run
+```
+
+**What it cleans:**
+
+**它清什么：**
+
+- Orphan slugs — `run-<slug>.sh` / `-inner.sh` / `attach-*.command` are moved to
+  `~/.shared/roll/loop/archived/<slug>-<timestamp>/`; the launchd plist is
+  booted out first.
+- `runs.jsonl.tmp.*` write-interrupted leftovers.
+- `backup-before-merge-*.tgz` older than 5 days.
+- `*.migrated-<ts>` markers older than 7 days.
+
+- 孤儿 slug —— `run-<slug>.sh` / `-inner.sh` / `attach-*.command` 移到
+  `~/.shared/roll/loop/archived/<slug>-<时间戳>/`，先 bootout launchd plist。
+- `runs.jsonl.tmp.*` 写中断残留。
+- 5 天前的 `backup-before-merge-*.tgz`。
+- 7 天前的 `*.migrated-<时间戳>` 标记。
+
+**Retention precedence** (highest first):
+
+**保留期优先级**（从高到低）：
+
+1. `ROLL_LOOP_GC_RETENTION_DAYS` environment variable.
+2. `loop_gc.retention_days` in `.roll/local.yaml`.
+3. Default: 30 days.
+
+1. 环境变量 `ROLL_LOOP_GC_RETENTION_DAYS`。
+2. `.roll/local.yaml` 里的 `loop_gc.retention_days`。
+3. 默认 30 天。
+
+`--dry-run` lists the full plan without executing — safe to run anytime.
+
+`--dry-run` 列出完整计划但不执行 —— 随时可放心运行。
+
+---
+
+## Troubleshooting
+
+**Where did my ALERT go?**
+
+**我的 ALERT 跑到哪去了？**
+
+It is now at `<project>/.roll/loop/ALERT-<slug>.md`. Run `roll loop alert` from
+inside the project, or open the file directly.
+
+现在在 `<project>/.roll/loop/ALERT-<slug>.md`。在项目里跑 `roll loop alert`，或直
+接打开文件。
+
+**How do I migrate manually?**
+
+**怎么手动迁移？**
+
+You normally never need to — the next cycle does it. To force it without waiting,
+run `roll loop now` (or `roll loop test`) once; the runner migrates before
+reading state.
+
+正常你永远不需要 —— 下一个 cycle 会做。要不等就触发，跑一次 `roll loop now`（或
+`roll loop test`）；runner 在读状态前会先迁移。
+
+**How do I roll back?**
+
+**怎么回滚？**
+
+The legacy files are preserved as `<name>.migrated-<timestamp>` for 7 days. To
+revert a single file, rename it back (drop the `.migrated-<ts>` suffix) and
+remove the project-local copy. After 7 days `roll loop gc` reaps the markers, so
+roll back within the window.
+
+老文件以 `<name>.migrated-<时间戳>` 形式保留 7 天。要回退某个文件，把它改名回去
+（去掉 `.migrated-<时间戳>` 后缀）并删掉项目本地副本。7 天后 `roll loop gc` 会
+回收这些标记，所以请在窗口期内回滚。
+
+See also: [roll loop](loop.md) · [Migration 2.0](migration-2.0.md) · [FAQ](faq.md)
+
+另见：[roll loop](loop.md) · [Migration 2.0](migration-2.0.md) · [FAQ](faq.md)