# README v2 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Rewrite `README.md` into an accurate, task-oriented English user guide for the current Pi Agent Board package, and correct the stale install command in `VERIFY.md`.

**Architecture:** This is a documentation-only change. `README.md` becomes the primary user-facing guide, organized around installation, first use, dashboard actions, reference behavior, configuration, safety, troubleshooting, and maintainer entry points. `VERIFY.md` receives one supporting-document correction so the linked verification path uses the scoped package name. Source code and `package.json` remain the behavior authority.

**Tech Stack:** Markdown, shell command examples, GitHub/Pi package links, existing Node.js verification scripts.

## Global Constraints

- Keep all user-facing documentation in English; discuss implementation progress in Chinese.
- Work only in `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-51-readme`; do not touch the main checkout.
- Use `package.json`, `src/index.ts`, `src/commands/*`, `src/ui/dashboard.ts`, `src/ui/pty-attach.ts`, `src/runtime/service.mjs`, and `src/core/*` as the source of truth.
- Do not advertise worktree isolation, plan-approval UI, provider-stall detection, or other planned/disabled behavior as shipped.
- State explicitly that worktree isolation is currently disabled and same-repository concurrent writes require user-managed isolation.
- Do not list internal child markers such as `AGENT_BOARD_CHILD`, `AGENT_BOARD_VIEW_ID`, or `AGENT_BOARD_HOSTED` as user settings.
- Do not advertise `AGENT_BOARD_ALLOW_PIPE_FALLBACK` as a normal ambient user toggle because the current service does not pass that ambient variable into the PTY runner configuration.
- Do not hard-code an unverified test count as a durable README claim; use CI and `npm run verify` as the authority.
- Do not modify runtime code, PRD/history documents, or the main checkout.
- Do not commit, push, open a PR, or merge without explicit user permission.

## File Map

- Modify: `README.md` — complete user-first guide and reference.
- Modify: `VERIFY.md` — one stale scoped-package install command.
- Create: `docs/superpowers/specs/2026-08-30-readme-v2-design.md` — approved design copied into the worktree.
- Create: `docs/superpowers/plans/2026-08-30-readme-v2.md` — this implementation plan.
- Inspect only: `package.json`, `src/index.ts`, `src/commands/agent-board.ts`, `src/commands/bg.ts`, `src/ui/dashboard.ts`, `src/ui/pty-attach.ts`, `src/runtime/service.mjs`, `src/core/rows.mjs`, `src/core/auto-state.mjs`, `src/core/launch-options.mjs`, `src/core/code-refs*.mjs`, `.github/workflows/ci.yml`, and `VERIFY.md`.

---

### Task 1: Rewrite README structure and first-use path

**Files:**
- Modify: `README.md`
- Inspect: `package.json`, `src/index.ts`, `src/commands/agent-board.ts`, `src/commands/bg.ts`, `src/ui/dashboard.ts`

**Interfaces:**
- Consumes: package identity and scripts from `package.json`; registered commands/flag from `src/index.ts` and `src/commands/*`; dashboard behavior from `src/ui/dashboard.ts`.
- Produces: an English README whose first-use path is Requirements → Install → Quick start → Entry points → Dashboard workflow.

- [ ] **Step 1: Replace the product introduction and requirements sections**

Write the opening around the current value proposition: a full-screen TUI for durable background Pi sessions, global cross-project visibility, dashboard triage, inline reply/evidence, and PTY/JSON fallback. Keep the existing banner, demo, package gallery, and npm links if they remain valid.

Add requirements for Pi, Node.js 20+, working Pi provider authentication, and PTY support for live attach/start-and-attach. State that provider authentication is a Pi prerequisite, not an Agent Board credential setup.

Use this package command exactly:

```bash
pi install npm:@zhuxixi/pi-agent-board
```

Do not use the unscoped `pi-agent-board` package name.

- [ ] **Step 2: Add installation alternatives and auth sanity check**

Keep three clearly separated paths:

```bash
# Published package
pi install npm:@zhuxixi/pi-agent-board

# Local package checkout
npm install
pi install "$(pwd)"

# Development auto-discovery
ln -s "$(pwd)" ~/.pi/agent/extensions/agent-board
```

Explain that `pi remove "$(pwd)"` applies to the local path installation, while the development symlink must be removed manually. Include the existing one-shot check and explain that it should end with an assistant `message_end`, then `agent_end`, and exit. Link `VERIFY.md` for the complete diagnostic sequence.

- [ ] **Step 3: Add Quick start and entry-point differences**

Add a five-step first-task flow:

1. Press `i` to enter INSERT mode.
2. Type a task.
3. Press `Enter` to open **Start session**.
4. Review cwd, model, thinking, and action.
5. Press `Enter` to launch.

Document `/agent-board`, `pi /agent-board`, `pi --agent-board`, and `/bg [prompt]`. State that `pi /agent-board` runs the standalone dashboard path and quitting it shuts down Pi; state that `--agent-board` cannot attach to a managed session and normal `/agent-board` is required for attach. Explain that `/bg` adopts the current interactive session and optionally queues a prompt.

- [ ] **Step 4: Verify the first-use section against source**

Check every command and behavior statement against `src/index.ts`, `src/commands/bg.ts`, `src/commands/agent-board.ts`, and the dashboard input handlers. Confirm that draft Enter opens the launch dialog, empty Enter attaches/resumes, and `i` is required before typing in Normal mode.

Run:

```bash
grep -nE '/agent-board|/bg|agent-board|INSERT|Start session|Enter|attach' README.md src/index.ts src/commands/*.ts src/ui/dashboard.ts
```

Expected: all advertised entry points and input transitions have matching source evidence and no unscoped install command appears in the new README.

---

### Task 2: Add dashboard, views, states, filters, and attach reference

**Files:**
- Modify: `README.md`
- Inspect: `src/ui/dashboard.ts`, `src/ui/pty-attach.ts`, `src/core/rows.mjs`, `src/core/types.mjs`, `src/runtime/service.mjs`, `src/ui/dashboard-evidence.mjs`

**Interfaces:**
- Consumes: dashboard modes/key handlers, row state/filter helpers, service fallback behavior, and PTY attach input handling.
- Produces: view-scoped reference sections that do not imply a key works in every dashboard mode.

- [ ] **Step 1: Document dashboard modes, launch dialog, and destructive actions**

Add Normal vs INSERT behavior, including `/` being literal in INSERT mode. Explain the launch dialog fields: cwd picker with favorites/browse and Tab completion, Pi-scoped model choices, supported thinking levels, and background versus start-and-attach. Mention persisted launch preferences and PTY-dependent start-and-attach fallback.

Document exact actions:

- `d` confirms Done for inactive sessions;
- manual completion is the default;
- `Ctrl+X` twice quickly archives/deletes a row;
- archive removes the row from the board but preserves the Pi session file;
- `X` removes inactive rows in the selected state;
- `m` enters batch selection with Space/a/u/d/Ctrl+X.

- [ ] **Step 2: Document view-specific shortcuts and capabilities**

Provide separate tables or subsections for Main list, Peek, Transcript, Evidence/Diagnostics, and PTY attach. Include:

- main-list navigation and actions;
- `Space` Peek;
- `r` reply only from Peek/Transcript/Evidence, not the main list; in Peek, it enters reply mode and the user presses Enter again after typing to send;
- `v` read-only transcript;
- `e` Evidence/Diagnostics and evidence-preserving diagnostic clear with `x`;
- attach with Enter/Right/`>`;
- PTY detach with `Left` when the child input is empty; edited input forwards the key, while a disconnected host can always be exited; `Ctrl+]` is passed through to the child Pi editor;
- attach scroll keys, mouse selection/copy, link opening, and optional middle-click paste.

State that pending Pi question/questionnaire tools require attach and cannot be answered with inline reply.

- [ ] **Step 3: Document states, grouping, unread, queue, and filters**

Document the exact display labels: Queued, Running, Needs answer, Needs instructions, Done, Failed, and Stopped. Explain semantic state versus process liveness, state/folder grouping, pinned-first stable creation ordering, unread indicators, busy follow-up FIFO queue, `qN`, and `queued:true`.

Document this filter syntax:

```text
s:running
review:ready
diag:stalled
evidence:error
queued:true
steer:awaiting-approval
```

Explain free-text AND matching over name, summary, and cwd, case-insensitive state aliases, and the limitation that `diag:stalled` consumes persisted diagnostics but does not represent a complete current provider-stall detector.

- [ ] **Step 4: Document evidence, code references, and persistence**

Explain Peek's summary/blocker/latest-output surface, transcript projection, Evidence/Diagnostics contents, durable artifacts, and locally extracted issue/PR badges. Mention optional per-root `providers.json` only as an extension point; do not invent an unverified schema.

Explain that busy replies are queued and drained when the session is ready. Explain the high-level store location `~/.pi/agent/agent-board/` and persistence through reload/restart/worker exit.

- [ ] **Step 5: Verify all advertised shortcuts and states**

Run:

```bash
grep -nE 'handle(List|Select|Peek|Session|Evidence)Key|renderHelp|renderPtyHelp|Ctrl|ctrl\+|review:ready|diag:stalled|evidence:error|queued:|steer:' src/ui/dashboard.ts src/core/rows.mjs
```

Compare every README shortcut/filter/state claim with the matching source handler. Remove any claim that only exists in PRD or planning documents.

---

### Task 3: Add configuration, safety, troubleshooting, and maintainer links

**Files:**
- Modify: `README.md`
- Inspect: `src/core/auto-state.mjs`, `src/core/title.mjs`, `runner/job-runner.mjs`, `runner/title-runner.mjs`, `src/runtime/service.mjs`, `src/ui/pty-attach.ts`, `src/core/pty-support.mjs`, `src/core/paths.mjs`, `.github/workflows/ci.yml`, `package.json`

**Interfaces:**
- Consumes: supported environment-variable reads, default values, PTY diagnosis behavior, package scripts, CI checks, and existing documentation links.
- Produces: a complete user-facing configuration table and explicit limitations/troubleshooting path.

- [ ] **Step 1: Replace the incomplete configuration table**

Document these supported user-facing settings with exact defaults and disable values: `AGENT_BOARD_ROOT`, `AGENT_BOARD_AUTO_STATE`, `AGENT_BOARD_AUTO_STATE_MODEL`, `AGENT_BOARD_AUTO_STATE_NO_DONE`, `AGENT_BOARD_SUMMARY_MODEL`, `AGENT_BOARD_TITLE_MODEL`, `AGENT_BOARD_TITLE_THINKING_LEVEL`, `AGENT_BOARD_CODE_REFS`, `AGENT_BOARD_DISABLE_PTY`, `AGENT_BOARD_FORCE_PTY`, `AGENT_BOARD_ATTACH_MOUSE`, `AGENT_BOARD_ENABLE_MOUSE_SCROLL`, `AGENT_BOARD_WHEEL_LINES`, `AGENT_BOARD_MAX_WARM_HOSTS`, `AGENT_BOARD_WARM_HOST_TTL_MS`, `AGENT_BOARD_ATTACH_NATIVE_PASTE`, `AGENT_BOARD_FORWARD_OSC52`, and `AGENT_BOARD_FORWARD_IMAGES`.

State the important default correctly: `AGENT_BOARD_AUTO_STATE_NO_DONE` unset means the user marks Done manually; `0`, `false`, `off`, or `no` restores automatic Done classification. Explain heuristic fallback for summary/title/state model failures where applicable.

Mention selected `AGENT_VIEW_*` names only as compatibility aliases and prefer `AGENT_BOARD_*` for new setup. Exclude internal child markers and do not present `AGENT_BOARD_ALLOW_PIPE_FALLBACK` as an ambient normal-user setting.

- [ ] **Step 2: Add safety, fallback, and troubleshooting sections**

Prominently state that worktree isolation is currently disabled and not automatically created. Same-repository concurrent sessions can run at the same time, so users must avoid overlapping writes or provide their own isolation.

Explain PTY versus JSON-runner fallback, the start-and-attach degradation, adopted external-session PTY requirement, Windows named-pipe/hidden-console capability, and `!` diagnostics. Add symptom-based troubleshooting for stuck Running/auth, `node-pty unavailable`, slow attach/reconnect, rejected inline reply, and same-repository conflicts.

- [ ] **Step 3: Simplify development, publishing, and further reading**

Keep maintainer sections concise:

```bash
npm install
npm run verify
```

Explain that verify runs typecheck, tests, coverage, and package dry-run. Keep publishing as verify, `npm version patch` (or minor/major), and `npm publish`. Link `VERIFY.md`, `PRD.md`, `PROGRESS.md`, and relevant deeper design material without embedding historical progress or a stale numeric test count.

- [ ] **Step 4: Validate configuration and limitation claims**

Run:

```bash
git grep -nE 'AGENT_BOARD_[A-Z0-9_]+' -- ':!README.md' ':!coverage/**' ':!node_modules/**'
grep -nE 'DEFAULT_|AUTO_STATE_NO_DONE|AGENT_BOARD_|node-pty|worktree|windows|verify' README.md package.json src/core/*.mjs src/runtime/*.mjs src/ui/*.ts runner/*.mjs .github/workflows/ci.yml
```

Expected: each public README variable has a source read and an accurate default; internal markers and unsupported worktree claims are absent.

---

### Task 4: Correct VERIFY.md and run documentation validation

**Files:**
- Modify: `VERIFY.md`
- Inspect: `README.md`, `VERIFY.md`, `package.json`, all README link targets

**Interfaces:**
- Consumes: the README's package/install path and the existing verification checklist.
- Produces: consistent scoped package installation instructions and validation evidence for the documentation change.

- [ ] **Step 1: Correct the stale published-package command**

Replace only this command in `VERIFY.md`:

```bash
pi install npm:pi-agent-board
```

with:

```bash
pi install npm:@zhuxixi/pi-agent-board
```

Do not change the verification procedure or historical notes beyond this scoped package correction.

- [ ] **Step 2: Check Markdown links and stale wording**

Run:

```bash
python - <<'PY'
from pathlib import Path
import re

for path in (Path("README.md"), Path("VERIFY.md")):
    text = path.read_text()
    for line_no, line in enumerate(text.splitlines(), 1):
        for target in re.findall(r"\]\(([^)]+)\)", line):
            if target.startswith(("http://", "https://", "#", "mailto:")):
                continue
            candidate = (path.parent / target.split("#", 1)[0]).resolve()
            if not candidate.exists():
                raise SystemExit(f"broken link: {path}:{line_no}: {target}")
print("relative Markdown links: OK")
PY

grep -RInE 'pi install npm:pi-agent-board|default: enabled|300\+ tests|r.*reply' README.md VERIFY.md || true
```

Expected: no broken relative links, no stale unscoped package command, no ambiguous auto-done wording, and no stale test-count claim.

- [ ] **Step 3: Run repository verification and inspect the final diff**

Run from the issue worktree:

```bash
npm run typecheck
npm test
npm run pack:dry
git diff --check
git diff --stat
git status --short
```

Expected: typecheck succeeds, the clean worktree baseline remains 416/416 tests with 0 failures, package dry-run succeeds, `git diff --check` is clean, and the diff contains only the approved spec/plan plus `README.md` and the one-line `VERIFY.md` correction.

Do not include the main checkout's untracked PTY tests in this evidence. Do not claim the main checkout is green while those unrelated tests remain failing.

- [ ] **Step 4: Prepare issue progress and handoff**

Record in the Issue #51 progress comment: the isolated worktree path, the documentation files changed, validation commands and results, any residual source-of-truth caveats, and the fact that no push/PR/merge was performed. Stop before pushing or opening a PR and request explicit user permission.