@seanyao/roll 2026.520.1 → 2026.521.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## v2026.521.2
+
+### Fixed
+
+- **`roll setup` 不再在 macOS 后台活动列表里留下 ghost「bash」条目** — 改由 `roll init` 和 `roll loop on` 按需安装 `[loop]`
+- **`roll setup` 现在能正确显示哪些步骤真的装了** — 之前装好的 skills 和 peer 状态目录会被误标成"跳过" `[loop]`
+- **`roll loop status --days 7` 不再吞掉天数参数** — 之前永远只显示默认 3 天，dashboard 底部那条 "more" 提示也改成能直接复制跑通 `[loop]`
+- **loop 每轮起手不再刷一堆"找不到文件"报错** — 修了内部脚本里的旧路径，并让 agent 在 zsh 下不再被未匹配的通配符卡住 `[loop]`
+
+## v2026.521.1
+
+### Added
+
+- **dashboard cycle 行现在标出模型和按公开单价算的成本** — 跨账号 / 跨项目可以横向对比和加总，不再被订阅折扣藏掉真实开销 `[loop]`
+
+### Improved
+
+- **`roll setup` 重跑能看出"已是最新"还是"刷新了 X 项"** — 每步上报 changed / unchanged / failed，强制覆盖用 `~` 标出 `[loop]`
+- **`roll-peer` 评审第一轮要先独立判断** — 不再被评审方预设结论带跑，跨 agent 才真的是二次判断 `[loop]`
+
+### Fixed
+
+- **`roll init` 默认不再打"Project ready"假提示** — 老项目进引导分支时不再骗你说已就绪 `[legacy-onboard]`
+
 ## v2026.520.1
 
 ### Added

package/bin/roll

@@ -4,7 +4,7 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2026.520.1"
+VERSION="2026.521.2"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -572,53 +572,161 @@ _ensure_tmux() {
   return 0
 }
 
+# FIX-075: snapshot the content of watched directories so cmd_setup can detect
+# whether a step actually changed any file. Uses `cksum` (mtime-independent) so
+# a re-copy with identical content is recognised as a no-op even when the inner
+# helper rewrites the file. Watch is a colon-separated list of directories;
+# missing dirs are skipped silently.
+# FIX-079: also track symlinks (`_link_skills` only creates symlinks) and
+# directories (`_peer_ensure_state_dir` only creates dirs). Without these, a
+# step that did real work but produced no regular file would falsely render
+# as ↷ on a brand-new install.
+_setup_snapshot() {
+  local watch="$1"
+  local -a dirs
+  IFS=':' read -r -a dirs <<<"$watch"
+  local d
+  {
+    for d in "${dirs[@]}"; do
+      [[ -d "$d" ]] || continue
+      find "$d" -type f -print0 2>/dev/null | xargs -0 cksum 2>/dev/null
+      while IFS= read -r l; do
+        printf 'L %s -> %s\n' "$l" "$(readlink "$l")"
+      done < <(find "$d" -type l 2>/dev/null)
+      find "$d" -type d -print 2>/dev/null
+    done
+  } | sort
+}
+
+# FIX-075: run a setup step and report changed/unchanged/failed via the global
+# _ROLL_SETUP_STATE. Caller passes the watch dir(s) plus the command + args.
+# stdout/stderr of the inner command are suppressed (same as the previous
+# pattern in cmd_setup) to keep the v2 UI render the only user-visible output.
+_run_setup_step() {
+  local watch="$1"; shift
+  local before after
+  before=$(_setup_snapshot "$watch")
+  if "$@" >/dev/null 2>&1; then
+    after=$(_setup_snapshot "$watch")
+    if [[ "$before" == "$after" ]]; then
+      _ROLL_SETUP_STATE="unchanged"
+    else
+      _ROLL_SETUP_STATE="changed"
+    fi
+  else
+    _ROLL_SETUP_STATE="failed"
+  fi
+}
+
 cmd_setup() {
   local force=false
-  local demo=false
   while [[ $# -gt 0 ]]; do
     case "$1" in
       --force|-f) force=true; shift ;;
-      --demo)     demo=true;  shift ;;
       *) err "Unknown argument: $1  未知参数: $1"; exit 1 ;;
     esac
   done
 
-  if [[ "${ROLL_UI:-v2}" == "v2" ]] || [[ "$demo" == "true" ]]; then
-    python3 "${ROLL_PKG_DIR}/lib/roll-setup.py" --demo
-    if [[ "$demo" == "true" ]]; then return; fi
-  fi
+  # Capture per-step outcomes for the v2 UI render at the end.
+  local steps_buf=()
+  _record() { steps_buf+=("$1|$2"); }
+
+  # Map snapshot-detected state to v2 UI marker. -f rewrites "changed" to
+  # "forced" so the user can tell a forced reinstall apart from a fresh
+  # install — both produce diff'd files, only -f was explicitly requested.
+  _state_to_marker() {
+    local s="$1"
+    case "$s" in
+      changed)   [[ "$force" == "true" ]] && echo forced || echo ok ;;
+      unchanged) echo skip ;;
+      failed)    echo fail ;;
+      *)         echo fail ;;
+    esac
+  }
 
-  info "Setting up Roll on this machine...  正在初始化 Roll..."
-  echo ""
+  local _ai_dirs="$HOME/.claude:$HOME/.gemini:$HOME/.kimi:$HOME/.codex:$HOME/.cursor:$HOME/.trae:$HOME/.config/opencode:$HOME/.openclaw:$HOME/.pi:$HOME/.deepseek"
 
-  _install_local "$force"
-  echo ""
-  info "Syncing to AI tools...  正在同步到 AI 工具..."
-  _sync_conventions "$force"
-  echo ""
-  _sync_skills "$force"
+  _run_setup_step "$ROLL_HOME" _install_local "$force"
+  _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Install templates & conventions to ~/.roll"
 
-  echo ""
-  info "Setting up peer review state...  正在初始化 peer review 状态..."
-  _peer_ensure_state_dir
-  ok "Peer state directory ready.  Peer 状态目录已就绪。"
+  _run_setup_step "$_ai_dirs" _sync_conventions "$force"
+  _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Sync conventions to AI tools"
 
-  echo ""
-  info "Ensuring tmux is installed (required for visible loop runs)...  正在确认 tmux 已安装..."
-  _ensure_tmux
+  _run_setup_step "$_ai_dirs" _sync_skills "$force"
+  _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Install skills to ~/.claude"
 
-  if [[ "$(uname)" == "Darwin" ]]; then
-    echo ""
-    info "Installing launchd plists...  正在安装 LaunchAgents..."
-    _install_launchd_plists "$(pwd -P)"
+  _run_setup_step "$ROLL_HOME/.peer-state" _peer_ensure_state_dir
+  _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Initialize peer-review state directory"
+
+  if command -v tmux >/dev/null 2>&1; then
+    _record skip "Ensure tmux is installed (already present)"
+  else
+    if _ensure_tmux >/dev/null 2>&1 && command -v tmux >/dev/null 2>&1; then
+      _record ok "Ensure tmux is installed"
+    else
+      _record fail "Ensure tmux is installed"
+    fi
   fi
 
-  echo ""
-  ok "Setup complete.  初始化完成。"
+  # FIX-078: launchd plist 安装从 setup 里拿掉——plist 是 per-project 资源，
+  # setup 是全局安装阶段，不应该给 cwd 留 disabled 的占位。需要时 cmd_init /
+  # _loop_on 各自会调 _install_launchd_plists。
 
-  echo ""
-  info "Next: run ${BOLD}roll init${NC} inside a project to initialize it.  下一步：在项目目录运行 roll init"
-  info "Optional gates: run ${BOLD}roll doctor${NC} inside a repo to see which PR review extras are still off.  可选闸门：在仓库内运行 roll doctor 查看 PR 评审两档开关状态"
+  _emit_setup_v2_ui "${steps_buf[@]}"
+}
+
+# FIX-073: Render the cmd_setup v2 UI from per-step outcomes captured above.
+# FIX-075: footer composition depends on how many steps actually changed —
+#   all unchanged → "no changes"; some forced (~) → "re-installed (forced)";
+#   any failed → "Setup incomplete"; otherwise → "X items refreshed".
+_emit_setup_v2_ui() {
+  local color_flag=""
+  if [[ -n "${NO_COLOR:-}" ]] || ! [ -t 1 ]; then
+    color_flag="--no-color"
+  fi
+
+  python3 - "$@" <<'PY' \
+    | python3 "${ROLL_PKG_DIR}/lib/roll-setup.py" $color_flag
+import json, sys
+entries = sys.argv[1:]
+steps = []
+for i, entry in enumerate(entries, start=1):
+    status, _sep, label = entry.partition("|")
+    steps.append({"num": i, "label": label, "status": status})
+
+n_failed   = sum(1 for s in steps if s["status"] == "fail")
+n_forced   = sum(1 for s in steps if s["status"] == "forced")
+n_changed  = sum(1 for s in steps if s["status"] == "ok")
+
+if n_failed:
+    footer_status = "fail"
+    label = "Setup incomplete"
+    hint = None
+elif n_forced:
+    footer_status = "ok"
+    label = f"Setup re-installed (forced — {n_forced} item{'s' if n_forced != 1 else ''})"
+    hint = "run roll init inside a project"
+elif n_changed == 0:
+    footer_status = "ok"
+    label = "Setup complete (no changes)"
+    hint = "everything already up to date"
+else:
+    footer_status = "ok"
+    label = f"Setup complete ({n_changed} item{'s' if n_changed != 1 else ''} refreshed)"
+    hint = "run roll init inside a project"
+
+payload = {
+    "header_label": "SETUP",
+    "subtitle":     "初始化",
+    "steps":        steps,
+    "footer": {
+        "status": footer_status,
+        "label":  label,
+        "hint":   hint,
+    },
+}
+print(json.dumps(payload))
+PY
 }
 
 # ─── PR pipeline hint ────────────────────────────────────────────────────────
@@ -917,21 +1025,20 @@ _merge_claude_to_project() {
 # Existing AGENTS.md: re-merges global conventions (section-level, non-destructive)
 # ═══════════════════════════════════════════════════════════════════════════════
 cmd_init() {
-  # US-VIEW-008: parse --demo before any side effects so the v2 renderer can
-  # run standalone (no templates, no project mutation).
-  local demo=false
-  local args=()
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --demo) demo=true; shift ;;
-      *)      args+=("$1"); shift ;;
-    esac
-  done
-  set -- "${args[@]:-}"
+  # US-ONBOARD-009: --apply consumes onboard-plan.yaml produced by $roll-onboard
+  if [[ "${1:-}" == "--apply" ]]; then
+    if [[ ! -d "$ROLL_TEMPLATES" ]]; then
+      err "No templates found. Run 'roll setup' first.  未找到模板，请先运行 'roll setup'。"
+      exit 1
+    fi
+    shift
+    _init_apply "$@"
+    return $?
+  fi
 
-  if [[ "${ROLL_UI:-v2}" == "v2" ]] || [[ "$demo" == "true" ]]; then
-    python3 "${ROLL_PKG_DIR}/lib/roll-init.py" --demo
-    if [[ "$demo" == "true" ]]; then return; fi
+  if [[ "${1:-}" == -* ]]; then
+    err "Unknown flag: $1  未知参数: $1"
+    exit 1
   fi
 
   if [[ ! -d "$ROLL_TEMPLATES" ]]; then
@@ -939,13 +1046,6 @@ cmd_init() {
     exit 1
   fi
 
-  # US-ONBOARD-009: --apply consumes onboard-plan.yaml produced by $roll-onboard
-  if [[ "${1:-}" == "--apply" ]]; then
-    shift
-    _init_apply "$@"
-    return $?
-  fi
-
   local project_dir
   project_dir="$(pwd)"
   local has_agents=false
@@ -953,7 +1053,6 @@ cmd_init() {
 
   if [[ -f "$project_dir/AGENTS.md" ]]; then
     has_agents=true
-    info "Re-merging global conventions...  正在重新合并全局约定..."
   else
     # US-ONBOARD-006: legacy project detection — guide user through $roll-onboard
     # instead of blindly scaffolding files into an existing codebase.
@@ -963,25 +1062,90 @@ cmd_init() {
     fi
   fi
 
-  _merge_global_to_project "$project_dir"
-  _merge_claude_to_project "$project_dir"
-  _write_backlog "$project_dir/.roll/backlog.md"
-  _ensure_features_dir "$project_dir/.roll/features"
-  _write_features_md "$project_dir/.roll/features.md"
-  print_merge_summary
+  # FIX-073: Suppress per-step echoes — outcomes are captured into
+  # _ROLL_MERGE_SUMMARY and rendered through the v2 UI below.
+  {
+    _merge_global_to_project "$project_dir"
+    _merge_claude_to_project "$project_dir"
+    _write_backlog "$project_dir/.roll/backlog.md"
+    _ensure_features_dir "$project_dir/.roll/features"
+    _write_features_md "$project_dir/.roll/features.md"
+  } >/dev/null
 
-  echo ""
-  info "Syncing conventions to AI tools...  正在同步约定到 AI 工具..."
-  _sync_conventions
-  echo ""
+  local sync_status="ok"
+  if ! _sync_conventions >/dev/null 2>&1; then
+    sync_status="fail"
+  fi
 
-  _install_launchd_plists "$project_dir"
+  _install_launchd_plists "$project_dir" >/dev/null 2>&1 || true
 
+  _emit_init_v2_ui "$project_dir" "$has_agents" "$sync_status"
+}
+
+# FIX-073: Build a real-data JSON payload from _ROLL_MERGE_SUMMARY and pipe it
+# to lib/roll-init.py for v2 UI rendering. Replaces the previous demo-only
+# render path.
+_emit_init_v2_ui() {
+  local project_dir="$1"
+  local has_agents="$2"
+  local sync_status="${3:-ok}"
+
+  local header_label="INIT" subtitle="项目初始化" footer_label="Initialized"
   if [[ "$has_agents" == "true" ]]; then
-    ok "Done.  完成。"
-  else
-    ok "Initialized.  已初始化。"
+    header_label="REINIT"
+    subtitle="重新合并约定"
+    footer_label="Re-merged"
   fi
+
+  local color_flag=""
+  if [[ -n "${NO_COLOR:-}" ]] || ! [ -t 1 ]; then
+    color_flag="--no-color"
+  fi
+
+  python3 - "$project_dir" "$header_label" "$subtitle" "$footer_label" "$sync_status" "${_ROLL_MERGE_SUMMARY[@]}" <<'PY' \
+    | python3 "${ROLL_PKG_DIR}/lib/roll-init.py" $color_flag
+import json, sys
+project_dir, header_label, subtitle, footer_label, sync_status, *summary = sys.argv[1:]
+STATUS = {"created":"ok","merged":"ok","unchanged":"skip","overwritten":"ok","kept":"skip"}
+OP = {"created":"+","merged":"~","unchanged":"·","overwritten":"~","kept":"·"}
+by_file = {}
+for entry in summary:
+    action, _sep, fname = entry.partition("|")
+    if fname:
+        by_file[fname] = action
+
+def step(num, label, fname):
+    act = by_file.get(fname)
+    if not act:
+        return {"num": num, "label": label, "status": "skip",
+                "note": "not modified"}
+    return {"num": num, "label": label, "status": STATUS.get(act, "ok"),
+            "files": [[OP.get(act, "·"), fname]]}
+
+steps = [
+    {"num": 1, "label": "Detect project type", "status": "ok"},
+    step(2, "Create AGENTS.md",           "AGENTS.md"),
+    step(3, "Create .roll/backlog.md",    ".roll/backlog.md"),
+    step(4, "Create .roll/features/",     ".roll/features/"),
+    step(5, "Merge existing CLAUDE.md",   ".claude/CLAUDE.md"),
+    {"num": 6, "label": "Link skills to AI clients", "status": sync_status},
+]
+footer_status = "fail" if any(s["status"] == "fail" for s in steps) else "ok"
+payload = {
+    "header_label": header_label,
+    "subtitle":     subtitle,
+    "project_path": project_dir,
+    "steps":        steps,
+    "footer":       {"status": footer_status,
+                     "label": footer_label if footer_status == "ok" else "Init incomplete"},
+    "next": [
+        ["Edit .roll/backlog.md",   "open the backlog and add your first US"],
+        ["Run roll loop now",       "execute one cycle manually to test the flow"],
+        ["Enable loop scheduling",  "roll loop on  — let it run hourly"],
+    ],
+}
+print(json.dumps(payload))
+PY
 }
 
 # US-ONBOARD-006: Legacy detection
@@ -2219,9 +2383,6 @@ cmd_peer() {
   local context_file=""
   local yolo=false
   local subcmd=""
-  # US-VIEW-009: parse --demo before any side effects so the v2 renderer can
-  # run standalone (no peer state, no tmux session, no agent call).
-  local demo=false
 
   while [[ $# -gt 0 ]]; do
     case "$1" in
@@ -2231,7 +2392,6 @@ cmd_peer() {
       --tag) tag="$2"; shift 2 ;;
       --context) context_file="$2"; shift 2 ;;
       --yes|--yolo) yolo=true; shift ;;
-      --demo) demo=true; shift ;;
       status) subcmd="status"; shift ;;
       reset) subcmd="reset"; shift; break ;;
       help|--help|-h) subcmd="help"; shift ;;
@@ -2239,13 +2399,6 @@ cmd_peer() {
     esac
   done
 
-  # US-VIEW-009: ROLL_UI=v2 (default) + --demo routes to the redesigned Python view.
-  # Set ROLL_UI=v1 to fall back to the legacy bash implementation.
-  if [[ "$demo" == "true" ]] && { [[ "${ROLL_UI:-v2}" == "v2" ]] || [[ "$demo" == "true" ]]; }; then
-    python3 "${ROLL_PKG_DIR}/lib/roll-peer.py" --demo
-    return
-  fi
-
   case "$subcmd" in
     status) cmd_peer_status; return ;;
     reset) cmd_peer_reset "$@"; return ;;
@@ -3787,7 +3940,7 @@ cmd_loop() {
     off)     _loop_off ;;
     now)     _loop_now ;;
     test)    _loop_test ;;
-    status)  _loop_status ;;
+    status)  _loop_status "$@" ;;
     monitor) _loop_monitor "${1:-3}" ;;
     runs)    _loop_runs "$@" ;;
     events)  _loop_event_log "${1:-20}" ;;

package/lib/loop-fmt.py

@@ -116,10 +116,15 @@ class LoopFmt:
         self.pending_ci      = False
         self.pending_story   = False
         self.spinner         = Spinner()
-        # Track the most recent usage / model seen on assistant turns so
-        # the result event handler can emit a 'usage' event even when
-        # result.usage is missing.
-        self._last_usage     = None
+        # Accumulate token usage across all assistant turns in the cycle so
+        # the trailing result event can emit a 'usage' event carrying the
+        # cumulative totals (result.usage only carries the last turn's).
+        self._usage_totals   = {
+            "input_tokens":          0,
+            "output_tokens":         0,
+            "cache_creation_tokens": 0,
+            "cache_read_tokens":     0,
+        }
         self._last_model     = None
 
     def _extract_cycle_num(self, text):
@@ -161,10 +166,14 @@ class LoopFmt:
 
     def _handle_assistant(self, ev):
         msg = ev.get("message", {})
-        # Remember the latest usage / model so the trailing result event
-        # can emit a 'usage' event even if result.usage is empty.
-        if msg.get("usage"):
-            self._last_usage = msg["usage"]
+        # Sum token usage across turns; result.usage only carries the last
+        # turn so accumulating here is the only way to get cumulative totals.
+        u = msg.get("usage") or {}
+        if u:
+            self._usage_totals["input_tokens"]          += int(u.get("input_tokens") or 0)
+            self._usage_totals["output_tokens"]         += int(u.get("output_tokens") or 0)
+            self._usage_totals["cache_creation_tokens"] += int(u.get("cache_creation_input_tokens") or 0)
+            self._usage_totals["cache_read_tokens"]     += int(u.get("cache_read_input_tokens") or 0)
         if msg.get("model"):
             self._last_model = msg["model"]
         for blk in msg.get("content", []):
@@ -341,18 +350,17 @@ class LoopFmt:
         shared  = os.environ.get("LOOP_SHARED_ROOT") or os.path.expanduser("~/.shared/roll")
         if not (slug and cycle):
             return
-        # Pull usage off the result event itself if present, otherwise off
-        # the most recent assistant turn we observed.
-        usage = (result_ev.get("usage") or self._last_usage or {})
+        # Use the cumulative totals accumulated across all assistant turns;
+        # result.usage is per-turn (last only) so it would under-count badly.
         model = result_ev.get("model") or self._last_model or ""
         payload = {
-            "model": model,
-            "input_tokens":            int(usage.get("input_tokens") or 0),
-            "output_tokens":           int(usage.get("output_tokens") or 0),
-            "cache_creation_tokens":   int(usage.get("cache_creation_input_tokens") or 0),
-            "cache_read_tokens":       int(usage.get("cache_read_input_tokens") or 0),
-            "cost_reported_usd":       float(cost_usd or 0),
-            "duration_ms":             int(dur_ms or 0),
+            "model":                 model,
+            "input_tokens":          self._usage_totals["input_tokens"],
+            "output_tokens":         self._usage_totals["output_tokens"],
+            "cache_creation_tokens": self._usage_totals["cache_creation_tokens"],
+            "cache_read_tokens":     self._usage_totals["cache_read_tokens"],
+            "cost_reported_usd":     float(cost_usd or 0),
+            "duration_ms":           int(dur_ms or 0),
         }
         evfile = os.path.join(shared, "loop", f"events-{slug}.ndjson")
         line = json.dumps({

package/lib/roll-backlog.py

@@ -211,51 +211,14 @@ def render(path: str) -> None:
 
 def main() -> None:
     args = sys.argv[1:]
-    demo = "--demo" in args
     no_color = "--no-color" in args or not sys.stdout.isatty() or os.getenv("NO_COLOR")
     rr.USE_COLOR = not no_color
 
     backlog = ".roll/backlog.md"
-    if not demo and not os.path.isfile(backlog):
+    if not os.path.isfile(backlog):
         print(f"Error: {backlog} not found — run 'roll init' first", file=sys.stderr)
         sys.exit(1)
-
-    if demo:
-        _write_demo(backlog)
-        try:
-            render(backlog)
-        finally:
-            os.unlink(backlog)
-    else:
-        render(backlog)
-
-
-def _write_demo(path: str) -> None:
-    with open(path, "w") as f:
-        f.write("""# Project Backlog
-
-## 🐛 Bug Fixes
-| ID | Description | Status |
-|----|-------------|--------|
-| FIX-042 | Fix outer runner tmux kill matching wrong session | 🔨 In Progress |
-| FIX-043 | Handle stale state in loop now command | 📋 Todo |
-
-## Epic: Autonomous Evolution
-### Feature: autonomous-evolution
-| Story | Description | Status |
-|-------|-------------|--------|
-| [US-AUTO-042](.roll/features/autonomous-evolution/autonomous-evolution.md) | Loop cost telemetry — write model and token data per cycle | 📋 Todo |
-
-## ♻️ Refactor
-| ID | Description | Status |
-|----|-------------|--------|
-| REFACTOR-010 | Simplify CI test parallelism strategy | 🔒 Blocked [waiting on CI infra] |
-
-## 💡 Ideas
-| ID | Description | Status |
-|----|-------------|--------|
-| IDEA-025 | Dashboard cost from list-price tokens | ⏸ Deferred [design pending] |
-""")
+    render(backlog)
 
 
 if __name__ == "__main__":

package/lib/roll-help.py

@@ -7,7 +7,7 @@ Compact wordmark + grouped commands (AUTONOMY / PROJECT / MACHINE) + examples.
 Usage:
   python3 lib/roll-help.py              # live
   python3 lib/roll-help.py --no-color
-  python3 lib/roll-help.py --demo       # same as live, no fixture needed
+  python3 lib/roll-help.py              # static layout, no fixture needed
 """
 
 from __future__ import annotations
@@ -142,7 +142,6 @@ def render(version: str) -> None:
 # ════════════════════════════════════════════════════════════════════════════
 def main() -> None:
     ap = argparse.ArgumentParser(add_help=False)
-    ap.add_argument("--demo",     action="store_true")
     ap.add_argument("--no-color", dest="no_color", action="store_true")
     ap.add_argument("--en",       action="store_true")
     ap.add_argument("--zh",       action="store_true")

package/lib/roll-home.py

@@ -10,7 +10,7 @@ Usage:
   python3 lib/roll-home.py              # live data
   python3 lib/roll-home.py --no-color
   python3 lib/roll-home.py --en | --zh  # collapse bilingual rows
-  python3 lib/roll-home.py --demo       # render with fixture data
+  ROLL_RENDER_FIXTURE=1 python3 lib/roll-home.py   # render with fixture data (test only)
 """
 
 from __future__ import annotations
@@ -262,9 +262,9 @@ def _ac_completion(feature_link: str) -> Tuple[int, int]:
     return (done, total)
 
 # ════════════════════════════════════════════════════════════════════════════
-# Demo fixture
+# Fixture data (test-only; opt in via ROLL_RENDER_FIXTURE=1)
 # ════════════════════════════════════════════════════════════════════════════
-def _demo_data() -> Dict[str, Any]:
+def _fixture_data() -> Dict[str, Any]:
     return dict(
         project_name="myapp", version="2026.518.3",
         agent="claude", git_branch="main", git_status="✓",
@@ -455,7 +455,6 @@ def render(d: Dict[str, Any]) -> None:
 # ════════════════════════════════════════════════════════════════════════════
 def main() -> None:
     ap = argparse.ArgumentParser(add_help=False)
-    ap.add_argument("--demo",     action="store_true")
     ap.add_argument("--no-color", dest="no_color", action="store_true")
     ap.add_argument("--en",       action="store_true")
     ap.add_argument("--zh",       action="store_true")
@@ -464,8 +463,8 @@ def main() -> None:
     if args.no_color or os.environ.get("NO_COLOR") or not sys.stdout.isatty():
         roll_render.USE_COLOR = False
 
-    if args.demo:
-        d = _demo_data()
+    if os.environ.get("ROLL_RENDER_FIXTURE"):
+        d = _fixture_data()
     else:
         slug    = _project_slug()
         config  = _load_config()