@seanyao/roll 3.626.2 → 3.628.1

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## Unreleased
 
+## v3.628.1 — 2026-06-28
+
+### 上手引导
+
+- **`roll init` 给出的 PRD 下一步现在能直接运行**：`roll design --from-file <path>` 会校验输入文件并把 PRD/brief 绑定到 `$roll-design`，不再落到 usage。(#1065) `[legacy-onboard]`
+
+## v3.627.1 — 2026-06-27
+
+### 上手引导
+
+- **新拆的卡会带验收契约**：`roll design` 现在把预期证据和评分重点写进 story，交付和评审看同一份标准。(US-SKILL-030) `[skill-ecosystem]`
+  <!-- evidence: .roll/features/skill-ecosystem/US-SKILL-030/2026-06-27T02-11-16/US-SKILL-030-report.html -->
+- **`roll init` 会先分清项目类型**：PRD、空项目、已有代码库、partial Roll、旧布局和已就绪项目都会走不同下一步。(US-INIT-004, US-INIT-005, US-INIT-006a, US-INIT-009) `[legacy-onboard]`
+  <!-- evidence: .roll/features/init-onboard/US-INIT-004/latest/US-INIT-004-report.html -->
+  <!-- evidence: .roll/features/init-onboard/US-INIT-005/latest/US-INIT-005-report.html -->
+  <!-- evidence: .roll/features/init-onboard/US-INIT-006a/latest/US-INIT-006a-report.html -->
+- **已有代码库先诊断再应用**：`roll init` 先产诊断和计划，确认后再 `roll init --apply`，不会一上来改你的仓库。(US-INIT-006b, US-INIT-006c, US-INIT-006d) `[legacy-onboard]`
+  <!-- evidence: .roll/features/init-onboard/US-INIT-006b/latest/US-INIT-006b-report.html -->
+  <!-- evidence: .roll/features/init-onboard/US-INIT-006c/latest/US-INIT-006c-report.html -->
+  <!-- evidence: .roll/features/init-onboard/US-INIT-006d/latest/US-INIT-006d-report.html -->
+- **`roll init --apply` 可以放心重跑和退出**：重复执行会复用变更账本，`roll offboard` 只移除 Roll 管理的内容。(US-INIT-006e, US-INIT-006f) `[legacy-onboard]`
+  <!-- evidence: .roll/features/init-onboard/US-INIT-006e/latest/US-INIT-006e-report.html -->
+  <!-- evidence: .roll/features/init-onboard/US-INIT-006f/latest/US-INIT-006f-report.html -->
+- **`roll next` 成了上手流程的继续按钮**：init、onboard、repair、migrate、design 和下一张 Todo 都会收束到一个显然下一步。(US-INIT-007) `[legacy-onboard]`
+  <!-- evidence: .roll/features/init-onboard/US-INIT-007/latest/US-INIT-007-report.html -->
+- **文档、CLI help 和站点图现在讲同一条路**：README、指南、skill contract 和 `$roll-onboard` 图都改成“已有代码库”视角。(US-INIT-008) `[legacy-onboard]`
+  <!-- evidence: .roll/features/init-onboard/US-INIT-008/latest/US-INIT-008-report.html -->
+
+### 稳定性
+
+- **验收截图不再能伪造现场**：CLI 用 Terminal.app，站点图用真实浏览器窗口；无 GUI 或无权限时诚实跳过。(US-INIT-003d, US-INIT-008) `[acceptance-evidence]`
+  <!-- evidence: .roll/features/init-onboard/US-INIT-003d/latest/US-INIT-003d-report.html -->
+  <!-- evidence: .roll/features/init-onboard/US-INIT-008/latest/US-INIT-008-report.html -->
+
 ## v3.626.2 — 2026-06-26
 
 ### 自动化流水线

package/README.md

@@ -33,12 +33,26 @@ Requirements: Node.js ≥ 22. Roll is a self-contained TypeScript CLI — no run
 ```bash
 cd your-project
 roll init           # set up Roll here (interactive confirmation)
+roll next           # continue with design, apply, repair, migrate, loop, or status
 roll loop on        # let AI work through the backlog (optional)
 ```
 
-`roll init` detects legacy code and routes you to `$roll-onboard` when appropriate.
-For a fresh project, it prints a project-type summary and asks for confirmation
-before creating files; pass `--auto` to skip the prompt in scripts and CI.
+`roll init` first diagnoses the current directory. Complete Roll projects get
+`Already initialized` and `Next: roll status`; partial Roll projects get
+`roll init --repair`, while pre-2.0 layouts get migration guidance without writing files. Existing codebases route to
+`$roll-onboard`. PRD/docs-only workspaces are treated as new projects: Roll writes
+`.roll/brief.md` from the detected document and points to
+`roll design --from-file <detected-doc>`.
+Empty directories ask what you are building in an interactive terminal; in scripts
+and CI, plain `roll init` is read-only and `roll init --auto` writes a placeholder
+brief before pointing to `roll design`.
+For existing-codebase grafts, `roll init --apply` validates the generated
+artifacts, prints a review checkpoint with every planned file operation, and
+waits for owner confirmation before writing. Automation must use
+`roll init --apply --auto` after that review.
+After any init path, `roll next` is the continuation button: it reads the same
+brief, onboard plan, backlog, and Roll markers, then prints one best next
+command instead of a menu.
 First time through? Start with [Getting started](guide/en/getting-started.md).
 
 ## Quick start for new projects
@@ -73,15 +87,16 @@ with `roll loop resume` when ready.
 | `roll loop alert [list\|ack\|resolve\|log]` | View / clear loop alerts |
 | `roll status` | Verdict-first truth summary read from the ONE snapshot — LOOP · CYCLE · RELEASE · STORY, with the STORY line's attest-coverage % (`done ≡ merged ∧ attested`) — then convention/AI-client sync health |
 | `roll pulse [--json]` | Today's delivery pulse: cycles in window, merged count, attested count, plus an ASCII sparkline from the story spectrum. Bilingual EN/中. `--json` for machine-readable output |
-| `roll doctor [skills]` | Environment + install diagnosis (agents, skill catalog, plists, launchd lanes) |
+| `roll doctor [skills\|--tools]` | Environment + install diagnosis; `roll doctor --tools` shows focused tool and screenshot readiness, including Terminal.app Screen Recording |
 | `roll daemon <start\|stop\|status>` | Opt-in read-only observability daemon for the live console; defaults to `127.0.0.1:7077`, records `.roll/loop/daemon.pid`, and is never auto-started by the loop |
 | `roll tune [reset]` | Suggest-only self-tuning from loop trends — read-only, never auto-applies |
 | **Cards & evidence** | |
 | `roll idea "<one-sentence description>"` | Capture a card: auto-classify, number, lint, infer epic, mint the full story folder — the one user entry for adding cards |
 | `roll story new <ID> --title <t> [--epic <e>] [--no-index]` | The one minting entry agents/skills use: card folder + backlog row + index refresh (`--no-index` for batches) |
 | **Project · per repo** | |
-| `roll init` | Set up Roll in this project (agent-driven onboarding for legacy code) |
-| `roll design [--agent <name>]` | Launch `$roll-design` interactively to turn requirements into a domain model + INVEST backlog |
+| `roll init` | Diagnose this directory and route to fresh scaffold, PRD/design handoff, existing-codebase onboard, repair, migration, or `roll status` |
+| `roll next` | Continue the init/onboard journey with one best next command: design, apply, repair, migrate, loop, or status |
+| `roll design [--from-file <path>] [--agent <name>]` | Launch `$roll-design` interactively; `--from-file` binds a PRD/brief as the design input |
 | `roll offboard` | Remove Roll from this project |
 | `roll test [--where] [--reset]` | Run the test suite (routes through the isolation adapter; unknown types fail loud) |
 | `roll daemon <start\|stop\|status>` | Manage the read-only observability daemon (OPT-IN only; never auto-started) |