@oevery/rsp 3.1.0-beta.5 → 3.1.1

package/README.md

@@ -4,387 +4,81 @@ English | [简体中文](./README.zh-CN.md)
 
 **A repository-native engineering workflow for humans and AI agents.**
 
-RSP helps turn unclear intent into shaped, implemented, reviewed, and verified software changes while keeping project knowledge durable and work recoverable. Its eleven composable Skills guide the engineering journey without introducing hidden workflow state or replacing the project's own files, tools, and authority.
-
-The workflow rests on a lightweight artifact foundation of **Rules, Specs, and Plans**.
+RSP turns unclear intent into shaped, implemented, reviewed, and verified software changes while keeping project knowledge durable and work recoverable. It uses ordinary repository files—Rules, Specs, and Plans—rather than hidden workflow state.
 
 ## What RSP helps you do
 
-- Shape ambiguous work into one executable Change or a small set of independent slices.
-- Resolve material design questions from repository evidence before implementation.
-- Route unexplained failures to diagnosis, ordinary evidenced edits to implementation, and only explicit or concrete-risk test-first work to TDD.
-- Review changes against explicit scope, address accepted findings, and rerun fresh verification.
-- Preserve stable facts, scoped instructions, lasting rationale, and completed history in their proper owners.
-- Prepare or reconcile release documentation for an explicit confirmed release operation; use a Release Change only when material coordination needs a persistent owner.
-
-## How the workflow fits together
+- Shape ambiguous work into an executable Change.
+- Resolve design questions from repository evidence before implementation.
+- Route diagnosis, implementation, TDD, review, and release work to explicit capabilities.
+- Preserve current facts, lasting rationale, scoped instructions, and completed history in the right owners.
+- Keep authority visible: RSP never infers permission to commit, publish, deploy, or approve work.
 
 ```text
-intent
-  → shape
-  → design when needed
-  → diagnose | TDD | implement
-  → review → address accepted findings
-  → release docs for an explicit confirmed operation
-  → durable review → archive
+intent → shape → design when needed → diagnose | TDD | implement
+       → review → durable review → archive
 ```
 
-RSP derives the next action from the selected Change, repository evidence, verification, and blockers. Each capability returns its result to the existing project or RSP owner. RSP does not infer permission to modify code, continue Git operations, commit, publish, deploy, or approve work.
-
-## Quick start
-
-```bash
-npx -y @oevery/rsp@3.1.0-beta.5 init
-npx -y @oevery/rsp@3.1.0-beta.5 doctor
-```
+## Five-minute start
 
-Recommended bootstrap flow:
+RSP 3.1 requires Node.js 22 or later. Use the current stable release:
 
 ```bash
-npx -y @oevery/rsp@3.1.0-beta.5 init --with-project-setup
+npx -y @oevery/rsp@latest init --with-project-setup
 # fill .rsp/changes/project-setup.md
 # fill .rsp/specs/design.md
-npx -y @oevery/rsp@3.1.0-beta.5 doctor
-```
-
-## Artifact foundation
-
-`Reliable Software Practice` is the product promise; `Rules, Specs, Plans` describes the lightweight artifact model that makes the workflow repository-native:
-
-- nearest `AGENTS.md` stores scoped project or module instructions.
-- `rsp-rules.md` is the minimal tool-agnostic fallback protocol.
-- `specs/` stores project-level source-of-truth docs.
-- `changes/` stores open work in a single-file format.
-- `focus.d/` mirrors current focused changes with empty marker files.
-- `archives/` stores completed work.
-
-```text
-.rsp/
-├── rsp-rules.md              # minimal fallback protocol
-├── specs/
-│   ├── 00-index.md           # auto-generated direct-child navigation
-│   ├── design.md
-│   ├── decisions/            # authoritative Decision Records by default; excluded from Specs indexes
-│   └── <domain>/
-│       ├── 00-index.md       # auto-generated direct-child navigation
-│       └── <spec>.md
-├── changes/
-│   ├── <name>.md
-│   └── <group>/
-│       ├── 00-brief.md
-│       └── <change>.md
-├── focus.d/
-│   └── <name>
-└── archives/
-    └── YYYY-MM-DD_<change>.md
-```
-
-## Concepts
-
-- `specs/` describes durable project facts and current agreed design.
-- Decision Records describe lasting rationale, alternatives, tradeoffs, and consequences for hard-to-reverse choices. They default to `.rsp/specs/decisions/` or use one configured external path.
-- `changes/` captures open work, including features, fixes, refactors, docs, ops, and research.
-- A change is always a single Markdown file with explicit sections for proposal, spec, design, tasks, verification, and blockers.
-- Keep each Change as a current-plan and final-evidence snapshot: choose the smallest decisive verification, retain new tests only when they add lasting value, and keep temporary probes and execution chronology out of persistent artifacts. Persistent prose names the real domain, system, user, or operator; it mentions AI or agents only when they are actual product participants or constraints.
-- An exact blocker line, `- requires \`<change-work-ref>\`: <reason>`, declares a dependency on another executable Change. Free-form blockers stay external; RSP never guesses edges from prose. Archived prerequisites resolve automatically.
-- Change names are either flat (`<change>`) or one direct grouped child (`<group>/<change>`). Recursive work directories are rejected.
-- A Change Group is optional and is the only composite work shape. Its non-executable, non-focusable logical identity `<group>/brief`, physically stored as `<group>/00-brief.md`, owns the shared goal, constraints, declared slices, completion conditions, durable outcomes, and blockers for at least two direct child Changes.
-- Create a group before its children. Every grouped Change must be declared by the brief, is focused and archived independently, and includes the brief in its context. With no focus, `status` uses Brief declaration order and current blockers to recommend the first executable slice. `status`, `check`, and `doctor` derive group health and completion without persisting another state; `rsp group close` archives only a completed brief. `rsp group create` never reuses an archived identity; `rsp group reopen <group> --reason <text>` explicitly restores one retained Brief snapshot as unfinished, unfocused continuation of that same Group.
-- A Group Brief blocker is inherited by its direct children as an external blocker in the derived execution plan; it does not create guessed dependency edges.
-- A Markdown file and directory cannot claim the same work identity.
-- `rsp status`, `rsp check`, and `rsp doctor` inspect the same complete work tree and dependency facts. `status` derives exact edges with their reasons, ready work, blockers, and stable waves without a graph file; `check` and `doctor` reject incomplete archive inspection, malformed or missing targets, self-dependencies, and cycles. The `changes/` root must exist as a real directory, and existing focus/archive roots and group prefixes must also be real directories. Unsupported directories, non-Markdown entries, symlinks, missing or unreadable current work, incomplete reads, and identity collisions are visible errors. `status` exits non-zero instead of hiding invalid work.
-- `rsp init`, `rsp update`, `rsp add spec`, and the generated Specs index builder apply the same no-follow managed-path checks. Archive discovery accepts only flat archive files or one real group directory; recursively organized Specs accept only real directories and regular files.
-- Final managed files—such as the project `AGENTS.md`, focus markers, fallback/config files, the generated Specs index, and placeholders—must also be regular files; RSP rejects static symlink targets before reading or writing them.
-- Completed changes move to `archives/`. Stable current facts belong in Specs; lasting rationale belongs in Decision Records; stable scoped operating instructions belong in nearest project-owned `AGENTS.md`.
-- When later evidence shows that the original acceptance was not actually met, `rsp reopen <work-ref> --reason <text>` restores the same executable WorkRef as focused open work and retains the selected archive as history. If its Group is closed, first use `rsp group reopen <group> --reason <text>`, then reopen only the incomplete child. Multiple matching Change or Group archives require an exact `--from .rsp/archives/...` path. Group reopen creates no focus and never reopens children or dependents. Use a new corrective Change for genuinely new scope or an independently delivered correction; reopening never rewrites Git or published history.
-- Do not promote task history, debugging notes, or one-off implementation context into Specs, Decision Records, or project instructions.
-- Managed progress questions report current evidence and do not implicitly pause an authorized run. Explicit pause confirms active work has stopped but preserves the focused WorkRef; only explicit release or `rsp unfocus` clears selection. Blocked or paused runs return a response-only continuation, and resume rereads authority, status, diff, blockers, and verification before requalifying Manage. RSP persists no paused or controller state.
-- Change `Spec` delta markers (`### ADDED`, `### MODIFIED`, `### REMOVED`) are planning aids only. `rsp archive` does not automatically promote them into Specs or Decision Records. Durable writeback remains an explicit semantic decision.
-- `rsp check` performs deterministic hygiene checks. It warns about unfinished template placeholders and unresolved clarification markers, but those warnings do not replace the semantic durable-update decision.
-
-## File ownership
-
-- `AGENTS.md`: only the `<!-- rsp:begin --> ... <!-- rsp:end -->` block is managed by RSP.
-- `.rsp/specs/**/00-index.md`: fully generated direct-child navigation for the root and populated Spec directories. Reconcile all local indexes with `rsp update`; `rsp add spec` refreshes only the affected directory chain.
-- `.rsp/specs/design.md`: created by `rsp init`, then owned by the project.
-- `.rsp/specs/decisions/`: the default authoritative Decision Record directory; configure `decisions.path` only when the Host Project already owns one external ADR directory.
-- `.rsp/rsp-rules.md`: generated minimal fallback protocol; use the `rsp` skill when available.
-- Keep project-wide boundaries in `.rsp/specs/design.md`; use the nearest `00-index.md` to discover cohesive reusable facts in the smallest domain Spec.
-- Treat every `00-index.md` as generated navigation, never as an editable current-fact or rationale owner. Each index lists only direct child Specs and populated child Spec directories; Decision Records are excluded.
-- Keep stable scoped workflow and validation instructions in the nearest project-owned `AGENTS.md`, outside the managed RSP block.
-
-## Decision Record path
-
-The default authoritative directory is `.rsp/specs/decisions/`. If the Host Project already owns ADRs elsewhere, configure exactly one project-relative external path:
-
-```yaml
-decisions:
-  path: docs/adr
-```
-
-The path cannot be absolute, escape the Host Project, or point at another `.rsp/` core location. `rsp init` and `rsp update` validate routing before managed writes and ensure the directory exists; `rsp show` and `rsp ready` refuse unsafe routing; `rsp doctor` validates directory readability and migration health. These commands never create a Decision Record. Switching to an external path does not migrate existing default records: `rsp doctor` reports inactive `.rsp/specs/decisions/*.md` files until they are moved or deliberately removed.
-
-## AGENTS integration
-
-Managed block example:
-
-```md
-<!-- rsp:begin -->
-## RSP Entry
-
-RSP tracks current work, stable specs, and archives under `.rsp/`.
-
-Read in order:
-1. Nearest `AGENTS.md` for project or module instructions.
-2. Root `CONTEXT-MAP.md` if present, then the relevant nearest `CONTEXT.md`.
-3. The `rsp` skill; if unavailable, read `.rsp/rsp-rules.md` as the fallback protocol.
-4. `.rsp/focus.d/`; for grouped work read the sibling Group Brief, then the explicitly selected focused Change.
-5. Only the relevant Specs and Decision Records under the configured authoritative path.
-
-If `.rsp/focus.d/` is empty and the user has not provided a concrete task, ask what to work on or suggest `npx -y @oevery/rsp create <name>` for tracked work.
-Do not treat `.rsp/specs/` or `.rsp/changes/` as replacements for nearest `AGENTS.md` or `CONTEXT.md`.
-<!-- rsp:end -->
-```
-
-`rsp init --agents-mode <mode>`:
-
-- `managed`: create `AGENTS.md` when needed and insert/update the managed block.
-- `print`: initialize normally and also print the resulting `AGENTS.md` content.
-
-## Skills
-
-RSP publishes eleven default host-neutral lifecycle Skills for on-demand loading, plus one explicitly installed project-level audit Skill:
-
-| Skill | Role |
-|---|---|
-| `rsp` | Derive the next action; guide setup, durable review, and archive decisions. |
-| `rsp-shape` | Shape one executable Change or justified shallow Group without implementation. |
-| `rsp-design` | Resolve one bounded domain, module/seam, or reversible-exploration question before or within tracked work. |
-| `rsp-implement` | Implement one selected ready Change with fresh verification. |
-| `rsp-diagnose` | Confirm a cause, or return a truthful unresolved diagnosis, before correction. |
-| `rsp-tdd` | Drive one clear behavior through RED, GREEN, and safe REFACTOR. |
-| `rsp-review` | Review a fixed code, document, or mixed comparison without mutation. |
-| `rsp-resolve-findings` | Dispose fixed findings, correct accepted ones, verify, and request re-review. |
-| `rsp-commit` | Create one authorized exact-scope local commit with a repository-consistent structured message. |
-| `rsp-release-docs` | Draft, audit, finalize, or reconcile evidence-based release surfaces. |
-| `rsp-manage` | Continue one explicitly requested or project-enabled eligible ready Change or shallow Group. |
-| `rsp-structural-audit` (optional) | Audit one bounded repository or subtree for evidence-backed structural risks without mutation. |
-
-Each lifecycle Skill returns to an existing project or RSP owner. Report-only Pre-Change Design and `rsp-structural-audit` may return one bounded result directly to the user without inventing an artifact owner. The suite adds no hidden workflow state or recursive Skill orchestration. No Skill infers commit, push, publication, deployment, approval, or human-acceptance authority.
-
-Response language is user/session-owned; artifact and commit-message language are durable project surfaces. Project `.rsp/config.yaml` never selects response language: response prose follows an explicit current request, user/host personal instructions, then conversation language. A project may set one durable `language.default` and independently override `language.artifacts` or `language.commit`. New authorized artifact prose follows an explicit artifact request, the configured effective artifact language, artifact-specific project instructions, then conversation language; existing artifacts keep their established language unless translation is explicitly authorized. Commit prose follows an explicit current commit-language instruction, configured effective commit language, repository commit authority, then clear recent non-merge history. Configuration changes never rewrite existing artifacts. CLI-generated scaffolds contain canonical structural tokens, neutral `<…>` placeholders, and verbatim user input instead of a locale catalog or silent English prose fallback; Core and discipline Skills fill their authorized natural-language content. Canonical RSP headings, paths, commands, identifiers, Conventional Commit types/scopes, trailers, and machine-consumed values remain unchanged; WorkRefs use the safe Unicode identity contract rather than the prose-language fallback chain.
-
-```yaml
-language:
-  default: en
-```
-
-`default` is required when the mapping is present and supplies both durable surfaces. Optional `artifacts` and `commit` override only their respective surfaces. `response` is intentionally unsupported because a shared repository must not constrain each collaborator's conversation language. Omit `language` entirely to leave both durable values unset. Plain status shows configured durable values, while status JSON always exposes `language.artifacts` and `language.commit` as a canonical language tag or `null`. Language configuration never grants staging, commit, push, or publication authority.
-
-Compose the suite from evidence: an explicit bounded question may enter report-only Pre-Change Design before Shape; otherwise Shape settles the executable owner and Tracked Design returns one material question to it. Core then chooses Diagnose, TDD, or Implement; Review stays report-only; Resolve Findings corrects accepted findings and requests re-review; Core performs the durable decision before archive. An explicit release operation with a confirmed identity or range may enter Release Docs without a Release Change; create one only for material decisions, coordination, recovery, blockers, or acceptance. Manage is optional: it accepts one selected ready Change or shallow Group that needs independent dispatch, long continuation, or recovery, while small or coupled work stays direct. Projects may keep explicit activation or let Core select eligible managed work automatically.
-
-### Managed automation policy
-
-Configure automatic selection and local closeout independently in `.rsp/config.yaml`:
-
-```yaml
-manage:
-  activation: auto
-  closeout: lifecycle
-```
-
-`activation` is `explicit` or `auto`. `auto` authorizes Core to select Manage for an eligible requested completion or continuation; it does not grant planning, product-mutation, lifecycle, Git, or external authority. `closeout` is one of:
-
-- `manual`: neither archive nor commit is automatic.
-- `lifecycle`: archive may follow durable review, but commit still needs separate authority.
-- `local`: lifecycle closeout plus separately justified recovery checkpoints; after lifecycle closeout, a qualified clean verified terminal non-small boundary routes once to `rsp-commit`, while terminal small work stays uncommitted.
-
-Change granularity follows one observable outcome and its shared acceptance, verification, review, archive, and rollback boundary; it does not prescribe Git commit count. Each `rsp-commit` invocation still creates exactly one local commit.
-
-New `rsp init` config templates use the shown `auto` plus `lifecycle` policy. If `manage` is absent, RSP instead resolves `activation: explicit` and `closeout: local` for compatibility with the previous explicitly requested Manage behavior. Plain `rsp status` and the top-level `manage` object in `rsp status --json` show the resolved values. Nearest scoped restrictions and host enforcement can narrow the configured ceiling. RSP intentionally has no `full` preset: push, tag, publication, deployment, approval, and human acceptance remain explicit and external.
-
-Humans should start with this README. Agents should follow the nearest `AGENTS.md`, prefer `skills/rsp/SKILL.md`, and use `.rsp/rsp-rules.md` only when the Skill is unavailable.
-
-When this README shows `rsp <command>`, it assumes the command is already available in your environment. For opt-in beta evaluation, pin the exact prerelease identity, such as `npx -y @oevery/rsp@3.1.0-beta.5 <command>`; stable users can keep using the unversioned package entrypoint for npm `latest`.
-
-Install the exact package's default lifecycle suite into the current project:
-
-```bash
-rsp skills install --dry-run
-rsp skills install
-```
-
-On a dual TTY, `rsp skills` opens the interactive manager: the default suite is selected and locked, while optional project Skills can be selected before one confirmed atomic install. For scripts, redirected terminals, and CI, use the deterministic discovery and install commands:
-
-```bash
-rsp skills list
-rsp skills list --json
-```
-
-The command preflights the eleven default package-owned targets, leaves unrelated `.agents/skills` entries (including optional Skills) untouched, and requires explicit `--force` before replacing a divergent selected directory. Install the optional project-level audit Skill by exact name:
-
-When upgrading an installation that still contains `rsp-address-review` or `rsp-codebase-audit`, their replacements are `rsp-resolve-findings` and `rsp-structural-audit`. The installer stops without mutation until `--force` explicitly authorizes transactional removal of the obsolete package-owned directory; `--dry-run --force` previews both removal and installation.
-
-```bash
-rsp skills install rsp-structural-audit --dry-run
-rsp skills install rsp-structural-audit
+npx -y @oevery/rsp@latest doctor
 ```
 
-Both forms install from the package that invoked `rsp`, so prerelease dogfooding can pin one exact npm identity:
+Then create and focus one tracked change:
 
 ```bash
-npx -y @oevery/rsp@3.1.0-beta.5 skills install --dry-run
-npx -y @oevery/rsp@3.1.0-beta.5 skills install
-```
-
-Exact prerelease identities avoid depending on a moving dist-tag. `rsp update` refreshes RSP-managed project files only; run `rsp skills install` separately to refresh the package-owned Skill suite.
-
-## Migrating from 2.x
-
-Version 3 uses `.rsp/rsp-rules.md` as the only runtime fallback path and removes project rules from the RSP model:
-
-See the [complete 3.0 migration guide](https://github.com/oevery/rsp/blob/v3.0.0/docs/migrations/3.0.md) for compatibility, recovery, and validation details.
-
-1. Upgrade the RSP CLI.
-2. Run `rsp update` to create the canonical fallback and remove the obsolete generated `.rsp/rules/rsp-rules.md`.
-3. If `.rsp/rules/` remains, move only stable scoped instructions from its residual entries into the nearest project-owned `AGENTS.md`, then remove the obsolete entries.
-4. Flatten any work path deeper than `.rsp/changes/<group>/<change>.md`, and resolve any `.rsp/changes/<name>.md` versus `.rsp/changes/<name>/` collision manually.
-5. Run `rsp doctor` and resolve every remaining migration issue.
-
-Repository maintainers can track external skill and workflow sources as offline review inputs. This tooling is intentionally excluded from the published package; see the [source-checkout maintainer guide](https://github.com/oevery/rsp/blob/main/docs/upstreams.md).
-
-## Work Model
-
-```text
-open → archived
+rsp create improve-login "Make login failures actionable"
+rsp focus improve-login
+rsp show --focused
 ```
 
-Directory roles are intentionally single-purpose:
-
-- `changes/`: open changes
-- `focus.d/`: currently focused changes
-- `archives/`: completed history
-
-Inside `open`, typical work includes:
-
-- `create`: create and scope a change.
-- `focus` / `unfocus`: decide which open change is currently foregrounded.
-- Edit the change file directly — fill sections, mark tasks, write design decisions.
-- Review whether durable updates are needed before archive.
-
-During implementation, keep the change file and the actual work in sync: complete `## Tasks` checkboxes as code lands, update `## Verify` with the checks actually run, and revise `## Design` if implementation discoveries change the plan.
-
-`archive` moves completed work into history. Archive never blocks — it warns but leaves the final decision to the agent or human.
-
-Agents should treat only entries in `focus.d/` as current work. Unfocused files in `changes/` are still open, but should not be treated as the current target unless the user explicitly asks for them or they are re-focused.
-
-Durable review makes two independent semantic choices: whether current facts or scoped instructions need an update, and whether lasting rationale needs a Decision Record. The RSP skill or a human reviewer owns both judgments.
-
-`rsp ready` and `rsp show` expose deterministic readiness and semantic-review signals without turning deterministic success into an archive action. Deterministic readiness comes from checkboxes, blockers, and scenarios; Core or a human still owns the durable-update decision and the advisory archive recommendation.
-
-`rsp ready --json` and `rsp show --json` include `durableReview.factDecisions`, `rationaleDecisions`, `factCandidateTargets`, and the one authoritative `decisionRecordsPath`. This is routing guidance only; RSP does not fabricate filenames or promote Change content automatically.
-
-## Recommended workflow
-
-New project:
+Follow the nearest `AGENTS.md`, edit the focused Change as work progresses, run fresh project checks, make the durable-update decision, and archive only after acceptance is satisfied.
 
-1. `npx -y @oevery/rsp@3.1.0-beta.5 init`
-2. Prefer `npx -y @oevery/rsp@3.1.0-beta.5 init --with-project-setup`, or run `rsp create project-setup` manually
-3. Fill `.rsp/specs/design.md`
-4. Use `rsp add spec <name>` only when a new durable project doc is needed
-5. Keep lasting rationale in the configured Decision Record directory and stable scoped operating instructions in the nearest project-owned `AGENTS.md`
-6. For tracked open work, start with `rsp create <name>`
-7. If you want an existing open change to become current work, use `rsp focus <name>`
-8. Use `rsp unfocus <name>` when you want to remove a change from the current focus set
-9. Edit the change file directly to implement the work and mark tasks complete
-10. Use the RSP skill or a human review to decide whether durable updates are needed
-11. After Core recommends archive, run `rsp archive <name>` before final Git delivery; inspect the complete resulting worktree and obtain Git authority separately
-12. If later evidence invalidates the original completion, run `rsp reopen <name> --reason <text>` and resolve the restored unfinished Task and Verify evidence under the same WorkRef
+[Read the full getting-started guide](./docs/site/en/getting-started.md).
 
-Existing project with a rich `AGENTS.md`:
-
-1. `npx -y @oevery/rsp@3.1.0-beta.5 init`
-2. Keep the managed block thin
-3. Keep project-wide boundaries and navigation in `.rsp/specs/design.md`, and route cohesive durable facts to the smallest domain Spec
-4. Use `rsp add spec <name>` only when another durable current-fact document is needed
-
-AI-assisted setup:
-
-1. `npx -y @oevery/rsp@3.1.0-beta.5 init --agents-mode print --with-project-setup`
-2. Keep the managed block as generated and adapt only the surrounding human-owned content if needed
-3. Have the AI review and fill `.rsp/changes/project-setup.md`
-4. Have the AI fill `.rsp/specs/design.md`
-5. Run `rsp doctor`
-
-## CLI
+## Artifact model
 
 ```text
-rsp init --agents-mode <mode>   Scaffold .rsp/ and ensure AGENTS.md contains the RSP entry block
-rsp init --with-project-setup   Also create .rsp/changes/project-setup.md
-rsp update                      Refresh managed project files, not packaged Skills
-rsp ui [--lang auto|en|zh-CN]   Open the read-only interactive dashboard
-rsp skills                      Open the interactive project Skill manager on a dual TTY
-rsp skills list [--json]        List bundled Skills and exact project installation status
-rsp skills install [name] [--dry-run] [--force]
-                                  Install the default eleven Skills or one exact optional Skill into .agents/skills
-rsp add spec <name>             Create .rsp/specs/<name>.md and rebuild specs index
-rsp create <name> [summary]     Create .rsp/changes/<name>.md; add --lite or --issue <url> [--issue-relation relates|closes]
-rsp group create <name> [goal] Create an unfocused .rsp/changes/<name>/00-brief.md
-rsp group close <name>         Archive a completed Group Brief after every child is archived
-rsp group reopen <name> --reason <text> [--from <archive-path>]
-                                  Restore the same Group Brief as unfinished, unfocused open work and retain history
-rsp focus <name>                Mark an open change as currently focused
-rsp unfocus <name>              Remove an open change from the current focus set
-rsp archive <name>              Archive to .rsp/archives/
-rsp archive --dry-run <name>    Deprecated compatibility route to rsp ready; never moves the change
-rsp reopen <name> --reason <text> [--from <archive-path>]
-                                  Restore the same WorkRef as focused open work and retain archive history
-rsp ready <name> [--json [--compact]] [--verbose]
-                                  Canonical read-only archive readiness projection
-rsp show <name|--focused> [--json [--compact]] [--verbose]
-                                  Show change context with readiness signals and context paths
-rsp history [--limit <n>] [--since <date>] [--until <date>] [--kind <kind>] [--group <group>] [--search <text>] [--json [--compact]]
-                                  List bounded archived Change summaries (default 20, maximum 100)
-rsp history <work-ref> [--json [--compact]]
-                                  Show bounded evidence detail for one exact archived Change
-rsp status [--focused|--blocked|--stale <days>] [--json [--compact]] [--verbose]
-                                  Show project status plus derived dependency plan with focus-aware filters
-rsp check [--focused] [--json [--compact]] [--verbose]
-                                  Validate change files and lightly lint template/scenario structure
-rsp doctor [--fix] [--json [--compact]] [--verbose]
-                                  Check setup health and common issues
+.rsp/
+├── rsp-rules.md       # minimal fallback protocol
+├── specs/             # durable current facts
+├── changes/           # open work
+├── focus.d/           # empty markers selecting current work
+└── archives/          # completed history
 ```
 
-Use `skills/rsp/SKILL.md` for operations. When the skill is unavailable, use `.rsp/rsp-rules.md` as the minimal fallback protocol.
-
-On a real interactive terminal, bare `rsp` opens the same read-only dashboard as `rsp ui`. CI, pipes, redirected streams, and `TERM=dumb` stay on static command output; use `rsp status` for a human snapshot or `rsp status --json` for automation. The dashboard never creates, focuses, or archives work.
+A Change is one Markdown file with canonical Proposal, Spec, Design, Tasks, Verify, and Blockers sections. Stable facts belong in Specs, lasting rationale in Decision Records, and scoped operating instructions in the nearest project-owned `AGENTS.md`.
 
-Dashboard keys: `Tab` cycles Changes/Groups/History, arrows or `j`/`k` move, `/` filters the active scope, `Enter` opens full-width detail, `r` refreshes the active scope, `?` shows help, and `q`, `Ctrl-C`, or top-level `Esc` exits. History is loaded only when first visited, uses the default bounded recent result, and loads one selected record's structured detail by its unique archive path only after `Enter`; use `rsp history` filters for older work. Set `RSP_UI_LANG=en|zh-CN` or pass `rsp ui --lang`; only dashboard-owned labels are localized. This UI setting does not localize CLI help, plain output, JSON, paths, commands, Skills, or existing artifacts. WorkRefs may use the safe Unicode identity contract, and new artifact prose follows the project language policy described above.
+## Documentation
 
-When there is no focused change, `rsp status` and `rsp show --focused --json` print `nextActions` instead of guessing which open change is current.
+- [Getting started](./docs/site/en/getting-started.md)
+- [Core concepts and artifact ownership](./docs/site/en/concepts.md)
+- [Daily workflow](./docs/site/en/guides/daily-workflow.md)
+- [Skills and managed work](./docs/site/en/guides/skills.md)
+- [Configuration reference](./docs/site/en/reference/configuration.md)
+- [CLI reference](./docs/site/en/reference/cli.md)
+- [3.0 migration guide](./docs/migrations/3.0.md) and [3.1 migration guide](./docs/migrations/3.1.md)
+- [Release notes](./docs/releases/3.1.1.md)
+- [Design philosophy](./docs/maintainers/design-philosophy.md) and [maintainer upstream research](./docs/maintainers/upstreams.md)
 
-Human-readable `rsp status` renders its execution guidance as a dependency forest: each parent requires its children, shared prerequisites are referenced instead of expanded repeatedly, and `Next action` names the currently executable Change or Changes.
+Run the documentation locally:
 
-`rsp status --json` returns the same dependency graph under `plan.nodes`, `plan.ready`, `plan.edges`, `plan.blocked`, and `plan.waves`. Nodes distinguish filter-selected Changes from prerequisite context, while filtered plans retain the transitive prerequisite closure needed to explain the result. JSON stays flat rather than nesting children because prerequisites may be shared by multiple Changes. Each edge reads as “`change` requires `requires`”. These are derived navigation facts, not execution authority or persisted workflow state.
-
-`rsp history` inspects authoritative archive files directly; no generated Archive Index is created or read. List results are ordered by archive date descending, WorkRef, then source path; inclusive date, exact kind, exact Group, and case-insensitive literal WorkRef/summary search filters are applied before the 1–100 record bound. Each record includes its project-relative archive path as a stable identity. `rsp history <work-ref>` returns bounded summary, scenario and checkbox counts, and bounded Tasks/Verify/Blockers evidence. It never returns raw Markdown; duplicate generations of one WorkRef fail with candidate archive paths instead of choosing implicitly. Unreadable, malformed, path-inconsistent, missing-root, or reserved executable Group Brief identities fail the complete query even when filters would exclude them. Archived Group Briefs are validated but are not list records. The command accepts at most one positional WorkRef. Diagnostics and ambiguous candidates are capped at 20 entries with total/returned/`hasMore` metadata, and human errors report how many entries were omitted. `status` archive trends and TUI History use the same validated inspection.
-
-Examples:
-
-```sh
-rsp history --since 2026-07-01 --kind fix --limit 10 --json
-rsp history --search migration --limit 10 --json
-rsp history cli-machine-output/add-bounded-history-query --json --compact
+```bash
+pnpm docs:dev
+pnpm docs:check
+pnpm docs:build
 ```
 
-The JSON-producing inspection commands `status`, `show`, `ready`, `check`, `doctor`, and `history` accept `--json --compact` for the same parsed value as `--json`, serialized on one LF-terminated line. `--compact` requires `--json`; other commands reject it before running command behavior.
-
-`rsp create --lite` is a shorter template for explicitly tracked small changes; simple current-session tasks should not create RSP changes unless tracking is intentionally needed.
-
-`rsp create <name> --issue <url>` attaches one validated external issue without network access and defaults to `relation: relates`; `--issue-relation closes` must be explicit and requires `--issue`. Issue options never update an existing Change: that invocation fails without changing the Change or focus. RSP stores only the canonical URL and relationship, never credentials, fetched title/body, or retrieval state. `status --json`, `show`, and `history` preserve valid relationships; immutable archives with older issue metadata remain readable but omit that opaque legacy projection. Shape may use available host access to retrieve real issue content, but failed access degrades to login retry, pasted source data, or a link-only draft rather than fabrication. Commit may add a closing keyword only for a terminal commit with completed acceptance and an owned `closes` relationship; otherwise it keeps a non-closing canonical URL reference.
+The site is only a presentation layer over the Markdown in this repository. It adds bilingual navigation, local search, and page outlines without introducing a content database or runtime service.
 
-`rsp doctor --fix` runs only safe deterministic repairs. Its `fixed` JSON entries report actual filesystem changes; a healthy project returns `fixed: []` and the human output says no safe fixes are needed.
+## Platform support
 
-## Platform-agnostic
+RSP is a tool-agnostic file convention and works with any assistant or editor that can read project files. Humans start here; agents follow the nearest `AGENTS.md`, load `skills/rsp/SKILL.md` when available, and use `.rsp/rsp-rules.md` only when the Skill is unavailable.
 
-`.rsp/` is a plain file convention. It works with Kilo Code, Cursor, Claude Code, Cline, GitHub Copilot, or any assistant that reads project files. RSP 3.1 requires Node.js 22+; users upgrading from 3.0 must update Node before installing.
+RSP is licensed under the [MIT License](./LICENSE).

package/README.zh-CN.md

@@ -2,372 +2,83 @@
 
 [English](./README.md) | 简体中文
 
-**面向人类与 AI Agent 的仓库原生工程工作流。**
+**面向人类与 AI 智能体的仓库原生工程工作流。**
 
-RSP 将模糊意图逐步转化为边界明确、经过实现、审查和验证的软件变更，同时让项目知识可以长期维护、让未完成工作可以可靠恢复。十一个可组合 Skills 共同覆盖工程旅程，但不引入隐藏 workflow state，也不取代项目自己的文件、工具和权限边界。
-
-这套工作流建立在轻量的 **Rules、Specs、Plans** artifact foundation 之上。
+RSP 把模糊意图转化为经过塑造、实现、审查和验证的软件变更，同时让项目知识可持久化、工作可恢复。它使用普通仓库文件——规则、规格和计划——而不是隐藏的工作流状态。
 
 ## RSP 帮助你完成什么
 
-- 将模糊工作塑造成一个可执行 Change，或一组彼此独立的小切片。
-- 在实现前，根据仓库证据解决关键设计问题。
-- 将原因不明的失败交给 diagnosis，将普通且证据充分的修改交给 implementation，仅将明确要求或具有具体风险的 test-first 工作交给 TDD。
-- 按明确范围审查变更、处理已接受的 findings，并重新运行 fresh verification。
-- 将稳定事实、作用域指令、长期理由和完成历史分别保存在正确的 owner 中。
-- 为显式且已确认的 release operation 准备或校准发布文档；只有重大协调需要持久 owner 时才使用 Release Change。
-
-## 工作流如何组合
+- 把模糊工作塑造成一个可执行 Change。
+- 在实现前根据仓库证据解决设计问题。
+- 把诊断、实现、TDD、审查和发布工作路由给明确的能力。
+- 把当前事实、长期理由、作用域指令和完成历史保存在正确的归属位置。
+- 保持权限可见：RSP 不会推断提交、发布、部署或批准权限。
 
 ```text
-意图
-  → Shape
-  → 按需 Design
-  → Diagnose | TDD | Implement
-  → Review → Address accepted findings
-  → 显式且确认后的 Release Docs
-  → Durable Review → Archive
+意图 → 塑造 → 必要时设计 → 诊断 | TDD | 实现
+     → 审查 → 持久化审查 → 归档
 ```
 
-RSP 根据 selected Change、仓库证据、验证结果和 blockers 推导下一步动作。每个能力都把结果返回已有的项目或 RSP owner。RSP 不会自行推断修改代码、继续 Git 操作、commit、publish、deploy 或 approve 的权限。
-
-## 快速开始
-
-```bash
-npx -y @oevery/rsp@3.1.0-beta.5 init
-npx -y @oevery/rsp@3.1.0-beta.5 doctor
-```
+## 五分钟入门
 
-推荐启动流程：
+RSP 3.1 需要 Node.js 22 或更高版本。使用当前稳定版本：
 
 ```bash
-npx -y @oevery/rsp@3.1.0-beta.5 init --with-project-setup
+npx -y @oevery/rsp@latest init --with-project-setup
 # 填写 .rsp/changes/project-setup.md
 # 填写 .rsp/specs/design.md
-npx -y @oevery/rsp@3.1.0-beta.5 doctor
-```
-
-## Artifact foundation
-
-`Reliable Software Practice` 表达产品承诺；`Rules、Specs、Plans` 描述让这套工作流保持仓库原生的轻量 artifact model：
-
-- nearest `AGENTS.md` 存放有作用域的项目或模块操作指令。
-- `rsp-rules.md` 是最小、tool-agnostic 的 fallback protocol。
-- `specs/` 存放项目级 source-of-truth 文档。
-- `changes/` 以单文件格式存放 open work。
-- `focus.d/` 用空标记文件镜像当前聚焦的 changes。
-- `archives/` 存放已完成工作。
-
-```text
-.rsp/
-├── rsp-rules.md              # 最小 fallback protocol
-├── specs/
-│   ├── 00-index.md           # 自动生成的直接子项导航
-│   ├── design.md
-│   ├── decisions/            # 默认的权威 Decision Records；不进入 Specs 索引
-│   └── <domain>/
-│       ├── 00-index.md       # 自动生成的直接子项导航
-│       └── <spec>.md
-├── changes/
-│   ├── <name>.md
-│   └── <group>/
-│       ├── 00-brief.md
-│       └── <change>.md
-├── focus.d/
-│   └── <name>
-└── archives/
-    └── YYYY-MM-DD_<change>.md
-```
-
-## 概念
-
-- `specs/` 描述长期稳定的项目事实和当前认可的设计。
-- Decision Records 描述难以逆转选择的长期理由、备选方案、取舍和后果；默认位于 `.rsp/specs/decisions/`，也可以配置唯一的外部权威路径。
-- `changes/` 描述 open work，包括 feature、fix、refactor、docs、ops 和 research。
-- 每个 change 始终是单个 Markdown 文件，并包含 proposal、spec、design、tasks、verification 与 blockers 等明确 section。
-- Change 保持为“当前计划与最终证据”的收敛快照：选择足以证明结果的最小验证，只保留具有长期价值的新测试，并让临时 probe 和执行流水留在持久产物之外。持久正文描述真实的领域、系统、用户或操作员；只有 AI 或 agent 确实是产品参与者或约束时才提及它们。
-- 精确 blocker 行 `- requires \`<change-work-ref>\`: <reason>` 表示依赖另一个可执行 Change。自由文本 blocker 保持为外部阻塞，RSP 不会从 prose 猜测依赖边；前置 Change 归档后依赖会自动解除。
-- Change 名称只能是扁平的 `<change>` 或一层直接子项 `<group>/<change>`；递归 work 目录会被拒绝。
-- Change Group 是可选且唯一的复合 work 形态。其不可执行、不可 focus 的逻辑身份 `<group>/brief` 在磁盘上存储为 `<group>/00-brief.md`，为至少两个直接子 Change 统一拥有目标、共享约束、slice 声明、整体完成条件、durable outcomes 和 blockers。
-- 必须先创建 Group 再创建子 Change。每个 grouped Change 都必须由 brief 声明，独立 focus、独立归档，并将 brief 纳入上下文。没有 focus 时，`status` 按 Brief 声明顺序和当前 blockers 推荐第一个可执行 slice。`status`、`check` 和 `doctor` 从文件事实推导 Group 健康度和完成度，不持久化额外状态；`rsp group close` 只归档已完成的 brief。已归档的 Group 身份不能重新打开。
-- Group Brief blocker 会作为外部 blocker 派生到其直接子 Change，但不会生成猜测的依赖边。
-- 同一个 work 身份不能同时由 Markdown 文件和目录占用。
-- `rsp status`、`rsp check` 和 `rsp doctor` 使用同一套完整 work-tree 与依赖事实检查。`status` 无需 graph 文件即可派生带原因的精确依赖边、ready work、blockers 和稳定 waves；`check` 与 `doctor` 会拒绝不完整的 archive inspection、格式错误或缺失的依赖目标、自依赖与循环。`changes/` 根目录必须存在且是真实目录，已有的 focus/archive 根目录和 group 前缀也必须是真实目录；非法目录、非 Markdown 条目、符号链接、缺失或不可读的当前 work、不完整读取和身份冲突都会成为可见错误。`status` 会返回非零状态，而不是隐藏非法 work。
-- `rsp init`、`rsp update`、`rsp add spec` 和生成索引使用相同的 no-follow managed-path 检查。archive discovery 只接受扁平 archive 文件或一层真实 group 目录；递归组织的 Specs 只接受真实目录和普通文件。
-- 项目 `AGENTS.md`、focus marker、fallback/config、生成索引和 placeholder 等最终 managed file 也必须是普通文件；RSP 会在读写前拒绝静态 symlink 目标。
-- 完成后的 change 会移动到 `archives/`。稳定当前事实写入 Specs；长期理由写入 Decision Records；稳定的作用域操作指令写入 nearest project-owned `AGENTS.md`。
-- 不要把任务历史、排障笔记或一次性实现上下文提升到 Specs、Decision Records 或项目指令。
-- Change `Spec` 中的 delta 标记仅为规划辅助。`rsp archive` 不会自动将它们提升到 Specs 或 Decision Records。
-- `rsp check` 会执行 deterministic 的卫生检查。它会对未完成的模板占位符和未解决的 clarification 标记发出 warning，但这些 warning 不会替代 durable update 的语义判断。
-
-## 文件所有权
-
-- `AGENTS.md`：只有 `<!-- rsp:begin --> ... <!-- rsp:end -->` 受管块由 RSP 维护。
-- `.rsp/specs/**/00-index.md`：为根目录及含内容的 Spec 目录生成直接子项导航。使用 `rsp update` 对齐全部本地索引；`rsp add spec` 只刷新受影响的目录链。
-- `.rsp/specs/design.md`：由 `rsp init` 创建，之后由项目维护。
-- `.rsp/specs/decisions/`：默认的权威 Decision Record 目录；只有 Host Project 已有外部 ADR 目录时才配置 `decisions.path`。
-- `.rsp/rsp-rules.md`：生成的最小 fallback protocol；可用时优先加载 `rsp` skill。
-- 将项目级边界放在 `.rsp/specs/design.md`；通过最近的 `00-index.md` 发现归属于最小领域 Spec 的成组、可复用事实。
-- 所有 `00-index.md` 都只是生成导航，不能作为可编辑的当前事实或理由 owner。每个索引只列直接子 Spec 与含内容的直接子目录，并排除 Decision Records。
-- 将稳定且有作用域的工作流、验证和本地运行指令放在 nearest project-owned `AGENTS.md` 的非受管区域。
-
-## Decision Record 路径
-
-默认权威目录是 `.rsp/specs/decisions/`。如果 Host Project 已在其他位置维护 ADR，只配置一个项目相对的外部路径：
-
-```yaml
-decisions:
-  path: docs/adr
-```
-
-该路径不能是绝对路径、不能逃逸 Host Project，也不能指向其他 `.rsp/` 核心位置。`rsp init` 和 `rsp update` 会在写入受管文件前校验路由并确保目录存在，`rsp show` 与 `rsp ready` 会拒绝不安全路由，`rsp doctor` 检查目录可读性和迁移健康；这些命令都不会创建 Decision Record。切换到外部路径不会自动迁移默认目录中的记录；在旧 `.rsp/specs/decisions/*.md` 被迁移或明确删除前，`rsp doctor` 会持续报告问题。
-
-## AGENTS 接入
-
-受管块示例：
-
-```md
-<!-- rsp:begin -->
-## RSP Entry
-
-RSP tracks current work, stable specs, and archives under `.rsp/`.
-
-Read in order:
-1. Nearest `AGENTS.md` for project or module instructions.
-2. Root `CONTEXT-MAP.md` if present, then the relevant nearest `CONTEXT.md`.
-3. The `rsp` skill; if unavailable, read `.rsp/rsp-rules.md` as the fallback protocol.
-4. `.rsp/focus.d/`; for grouped work read the sibling Group Brief, then the explicitly selected focused Change.
-5. Only the relevant Specs and Decision Records under the configured authoritative path.
-
-If `.rsp/focus.d/` is empty and the user has not provided a concrete task, ask what to work on or suggest `npx -y @oevery/rsp create <name>` for tracked work.
-Do not treat `.rsp/specs/` or `.rsp/changes/` as replacements for nearest `AGENTS.md` or `CONTEXT.md`.
-<!-- rsp:end -->
-```
-
-`rsp init --agents-mode <mode>`：
-
-- `managed`：在需要时创建 `AGENTS.md`，并插入或更新受管块。
-- `print`：正常初始化，并额外打印最终的 `AGENTS.md` 内容。
-
-## Skills
-
-RSP 发布十一个默认、宿主无关、按需加载的生命周期 Skills，以及一个需要显式安装的项目级审计 Skill：
-
-| Skill | 职责 |
-|---|---|
-| `rsp` | 派生下一动作，指导 setup、durable review 与 archive 判断。 |
-| `rsp-shape` | 在不实现的前提下塑造一个可执行 Change 或合理的 shallow Group。 |
-| `rsp-design` | 解决一个受跟踪的 domain、module/seam 或 reversible-exploration 问题。 |
-| `rsp-implement` | 实现一个 selected ready Change，并提供 fresh verification。 |
-| `rsp-diagnose` | 修正前确认原因，或如实返回 unresolved diagnosis。 |
-| `rsp-tdd` | 让一个清晰行为经过 RED、GREEN 与安全的 REFACTOR。 |
-| `rsp-review` | 对固定的 Code、Document 或 mixed comparison 做只读审查。 |
-| `rsp-resolve-findings` | 处置固定 findings，修正 accepted 项，验证并请求复审。 |
-| `rsp-commit` | 使用与仓库一致的结构化消息创建一个已授权、精确范围的本地提交。 |
-| `rsp-release-docs` | 起草、审计、定稿或校准基于证据的发布表面。 |
-| `rsp-manage` | 继续一个显式请求或项目启用且符合条件的 ready Change 或 shallow Group。 |
-| `rsp-structural-audit`（可选） | 只读审计一个有界仓库或子树，发现有证据支撑的结构风险。 |
-
-每个生命周期 Skill 都把结果返回现有项目或 RSP owner。只读的 Pre-Change Design 与 `rsp-structural-audit` 可以把一个有界结果直接返回用户，而不虚构 artifact owner。套件不引入隐藏 workflow state 或递归 Skill 编排。任何 Skill 都不会推断 commit、push、publication、deployment、approval 或 human-acceptance 权限。
-
-响应语言归用户和会话所有；产物与 commit message 语言才是项目持久表面。项目 `.rsp/config.yaml` 绝不选择响应语言：响应正文依次遵循当前明确请求、用户/宿主个人指令和会话语言。项目可以设置共享的 `language.default`，并通过 `language.artifacts` 或 `language.commit` 分别覆盖。新产物正文依次遵循明确产物语言、有效产物语言、项目产物指令和会话语言；已有产物除非明确授权翻译，否则保持现有语言。Commit 正文依次遵循当前明确的 commit 语言、有效 commit 语言、仓库 commit 规则和清晰的近期非 merge 历史。配置变化不会重写历史。CLI 生成的脚手架只包含 canonical 结构 token、中立的 `<…>` 占位符和用户原样输入，不维护 locale 字典，也不会静默回退为英文正文；Core 与 discipline Skills 再按授权语言填写自然语言内容。RSP 的 canonical headings、路径、命令、标识符、Conventional Commit type/scope、trailers 和机器消费值保持不变；WorkRef 遵循安全 Unicode 身份契约。
-
-```yaml
-language:
-  default: en
-```
-
-配置了 `language` mapping 时，`default` 必填并同时为产物和 commit 提供持久默认值；可选的 `artifacts` 与 `commit` 只覆盖对应表面。`response` 被明确禁止，因为共享仓库不应限制每位协作者的会话语言。完全省略 `language` 时，两项持久有效值都保持未设置。普通 status 显示持久语言值，status JSON 则始终把 `language.artifacts` 与 `language.commit` 投影为规范化语言标签或 `null`。语言配置不会授予 stage、commit、push 或 publication 权限。
-
-按证据组合套件：Shape 确定 owner；Design 返回一个关键问题；Core 在 Diagnose、TDD 与 Implement 之间选择；Review 保持只读；Resolve Findings 修正 accepted findings 并请求复审；Core 在 archive 前执行 durable decision。显式 release operation 在 identity 或 range 已确认时，可以不创建 Release Change 就进入 Release Docs；只有重大决策、协调、恢复、blocker 或 acceptance 需要持久 owner 时才创建。Manage 是可选能力：它接受一个 selected ready Change 或 shallow Group，并要求独立调度、长时 continuation 或恢复需求；小型或紧耦合工作保持直接执行。项目可以保持显式启用，也可以让 Core 自动选择符合条件的 managed work。
-
-### Managed automation policy
-
-在 `.rsp/config.yaml` 中分别配置自动选择与本地收尾：
-
-```yaml
-manage:
-  activation: auto
-  closeout: lifecycle
-```
-
-`activation` 可取 `explicit` 或 `auto`。`auto` 只授权 Core 为符合条件且已经请求完成或继续的工作选择 Manage；它不授予 planning、product mutation、lifecycle、Git 或外部权限。`closeout` 可取：
-
-- `manual`：archive 与 commit 都不会自动执行。
-- `lifecycle`：durable review 后可以 archive，但 commit 仍需要独立权限。
-- `local`：允许 lifecycle closeout 和有独立依据的 recovery checkpoint；lifecycle closeout 后，符合条件且 clean、已验证的非小型终态边界会调用一次 `rsp-commit`，小型终态仍不提交。
-
-Change 粒度由一个可观察结果及其共享的 acceptance、verification、review、archive 和 rollback 边界决定，不规定 Git commit 数量。每次 `rsp-commit` 调用仍只创建一个本地 commit。
-
-新的 `rsp init` config template 使用上面的 `auto` 加 `lifecycle` policy。如果省略 `manage`，RSP 则为兼容既有显式 Manage 行为解析为 `activation: explicit` 与 `closeout: local`。普通 `rsp status` 和 `rsp status --json` 顶层的 `manage` 对象都会显示解析后的值。nearest scoped restriction 与 host enforcement 可以缩小该配置上限。RSP 有意不提供 `full` preset：push、tag、publication、deployment、approval 与 human acceptance 始终保持显式且属于外部边界。
-
-人类应从本 README 开始；agent 应遵循 nearest `AGENTS.md`，优先加载 `skills/rsp/SKILL.md`，仅在 Skill 不可用时读取 `.rsp/rsp-rules.md`。
-
-如果文档中写的是 `rsp <command>`，默认前提是你的环境里已经能直接运行 `rsp`。进行 opt-in beta 评估时，应固定精确 prerelease 身份，例如 `npx -y @oevery/rsp@3.1.0-beta.5 <command>`；stable 用户仍可使用不带版本的入口获取 npm `latest`。
-
-将当前精确包内置的默认生命周期 Skill 套件安装到当前项目：
-
-```bash
-rsp skills install --dry-run
-rsp skills install
+npx -y @oevery/rsp@latest doctor
 ```
 
-在 dual TTY 中，`rsp skills` 会打开交互式管理器：默认套件保持选中并锁定，可在确认一次原子安装前选择可选的项目级 Skill。脚本、重定向终端和 CI 使用确定性的发现与安装命令：
+然后创建并聚焦一个受跟踪变更：
 
 ```bash
-rsp skills list
-rsp skills list --json
+rsp create improve-login "让登录失败信息可供用户采取行动"
+rsp focus improve-login
+rsp show --focused
 ```
 
-该命令会预检十一个默认 package-owned targets，保留无关的 `.agents/skills` 条目（包括可选 Skills），并且只有显式传入 `--force` 才会替换内容不同的已选目录。按精确名称安装可选的项目级审计 Skill：
-
-升级仍包含 `rsp-address-review` 或 `rsp-codebase-audit` 的安装时，其替代项分别是 `rsp-resolve-findings` 和 `rsp-structural-audit`。安装器会在变更前停止，直到 `--force` 显式授权事务性移除这个过时的 package-owned 目录；`--dry-run --force` 可同时预览移除与安装。
+遵循最近的 `AGENTS.md`，在工作推进时同步当前聚焦的 Change，运行最新的项目检查，判断是否需要持久化更新，并仅在满足验收条件后归档。
 
-```bash
-rsp skills install rsp-structural-audit --dry-run
-rsp skills install rsp-structural-audit
-```
+[阅读完整入门指南](./docs/site/zh-CN/getting-started.md)。
 
-两种形式都从调用 `rsp` 的同一个包安装，因此 beta 评估可以固定精确 npm 身份：
-
-```bash
-npx -y @oevery/rsp@3.1.0-beta.5 skills install --dry-run
-npx -y @oevery/rsp@3.1.0-beta.5 skills install
-```
-
-精确 prerelease 身份可以避免依赖持续移动的 dist-tag。`rsp update` 只刷新由 RSP 管理的项目文件；刷新 package-owned Skill 套件需要单独运行 `rsp skills install`。
-
-## 从 2.x 迁移
-
-版本 3 仅使用 `.rsp/rsp-rules.md` 作为运行时 fallback，并从 RSP 模型中移除了 project rules：
-
-完整的兼容性、恢复与验证说明见 [3.0 migration guide](https://github.com/oevery/rsp/blob/v3.0.0/docs/migrations/3.0.md)。
-
-1. 升级 RSP CLI。
-2. 运行 `rsp update`，生成 canonical fallback 并删除旧的 `.rsp/rules/rsp-rules.md` 生成文件。
-3. 如果 `.rsp/rules/` 仍然存在，只把残留内容中稳定且有作用域的指令迁入 nearest project-owned `AGENTS.md`，然后删除旧条目。
-4. 将深于 `.rsp/changes/<group>/<change>.md` 的 work path 扁平化，并手动解决 `.rsp/changes/<name>.md` 与 `.rsp/changes/<name>/` 的身份冲突。
-5. 运行 `rsp doctor`，处理所有剩余迁移问题。
-
-仓库维护者可以把外部 skill 和 workflow 来源作为离线评审输入进行跟踪。该工具有意不进入发布包；具体用法见[源码仓库维护指南](https://github.com/oevery/rsp/blob/main/docs/upstreams.md)。
-
-## 工作模型
+## 产物模型
 
 ```text
-open → archived
+.rsp/
+├── rsp-rules.md       # 最小后备协议
+├── specs/             # 持久化的当前事实
+├── changes/           # 未完成工作
+├── focus.d/           # 选择当前工作的空标记文件
+└── archives/          # 已完成历史
 ```
 
-各目录职责应保持单一且明确：
-
-- `changes/`：open changes
-- `focus.d/`：当前聚焦的 changes
-- `archives/`：完成后的历史
+一个 Change 是包含规范的 Proposal、Spec、Design、Tasks、Verify 和 Blockers 章节的单个 Markdown 文件。稳定事实属于 Specs，长期理由属于 Decision Records，稳定且有作用域的操作指令属于最近的项目自有 `AGENTS.md`。
 
-在 `open` 阶段，常见活动包括：
+## 文档
 
-- `create`：创建并界定一个 change。
-- `focus` / `unfocus`：调整当前聚焦的 open change。
-- 直接编辑 change 文件，填写 section、勾选 tasks、记录设计决策。
-- 在归档前判断是否需要 durable updates。
+- [开始使用](./docs/site/zh-CN/getting-started.md)
+- [核心概念与产物归属](./docs/site/zh-CN/concepts.md)
+- [日常工作流](./docs/site/zh-CN/guides/daily-workflow.md)
+- [Skills 与受管工作](./docs/site/zh-CN/guides/skills.md)
+- [配置参考](./docs/site/zh-CN/reference/configuration.md)
+- [CLI 参考](./docs/site/zh-CN/reference/cli.md)
+- [3.0 迁移指南](./docs/migrations/3.0.md)与 [3.1 迁移指南](./docs/migrations/3.1.md)
+- [发布说明](./docs/releases/3.1.1.md)
+- [设计哲学](./docs/maintainers/design-philosophy.md)与[维护者上游研究](./docs/maintainers/upstreams.md)
 
-实现过程中，应保持 change 文件与实际工作同步：代码完成后勾选对应的 `## Tasks`，在 `## Verify` 中记录实际运行的检查；如果实现发现设计不成立，应先更新 `## Design` 再继续。
+在本地运行文档：
 
-`archive` 会把已完成的工作归档到历史。`archive` 不会阻塞，只会给出 warning，最终判断留给 agent 或人工。
-
-agent 应只把 `focus.d/` 中列出的 change 视为当前工作。`changes/` 中未聚焦的文件仍然是 open，但除非用户明确要求或重新 `focus`，否则不应被当作当前目标。
-
-durable review 包含两个独立语义判断：是否更新当前事实或作用域指令，以及是否需要记录长期理由的 Decision Record；两者都由 RSP skill 或人工 reviewer 完成。
-
-`rsp ready` 和 `rsp show` 会暴露 deterministic readiness 与 semantic-review 信号，但不会把确定性通过直接变成 archive 动作。deterministic readiness 来自 checkbox、blocker 和 scenario；durable update 判断和 advisory archive 建议仍由 Core 或人工负责。
-
-`rsp ready --json` 和 `rsp show --json` 会提供 `durableReview.factDecisions`、`rationaleDecisions`、`factCandidateTargets` 和唯一的 `decisionRecordsPath`。这只是路由指导；RSP 不会虚构文件名或自动提升 Change 内容。
-
-## 推荐工作流
-
-新项目：
-
-1. `npx -y @oevery/rsp@3.1.0-beta.5 init`
-2. 优先使用 `npx -y @oevery/rsp@3.1.0-beta.5 init --with-project-setup`，或手动执行 `rsp create project-setup`
-3. 填写 `.rsp/specs/design.md`
-4. 仅在需要新的长期项目文档时使用 `rsp add spec <name>`
-5. 将长期理由写入配置的 Decision Record 目录，将稳定的作用域操作指令写入 nearest project-owned `AGENTS.md`
-6. 对需要跟踪的 open work，使用 `rsp create <name>` 开始
-7. 如果要让某个已有 open change 成为当前工作，使用 `rsp focus <name>`
-8. 如果要将某个 change 移出当前焦点集合，使用 `rsp unfocus <name>`
-9. 直接编辑 change 文件并完成实现、勾选 tasks
-10. 使用 RSP skill 或人工 review 判断是否需要 durable updates
-11. Core 建议 archive 后，在最终 Git 交付前运行 `rsp archive <name>`；重新检查完整工作树，并单独取得 Git 权限
-
-已有复杂 `AGENTS.md` 的项目：
-
-1. `npx -y @oevery/rsp@3.1.0-beta.5 init`
-2. 保持受管块尽量薄
-3. 将项目级边界与导航放在 `.rsp/specs/design.md`，把成组的长期事实放入最小领域 Spec
-4. 只有需要额外的 durable current-fact 文档时才使用 `rsp add spec <name>`
-
-AI 协助接入：
-
-1. `npx -y @oevery/rsp@3.1.0-beta.5 init --agents-mode print --with-project-setup`
-2. 保持受管块原样，只在需要时调整周围由人维护的内容
-3. 让 AI 审阅并填写 `.rsp/changes/project-setup.md`
-4. 让 AI 填写 `.rsp/specs/design.md`
-5. 运行 `rsp doctor`
-
-## CLI
-
-```text
-rsp init --agents-mode <mode>   搭建 .rsp/，并确保 AGENTS.md 含有 RSP 入口块
-rsp init --with-project-setup   同时创建 .rsp/changes/project-setup.md
-rsp update                      刷新受管项目文件，不更新 packaged Skills
-rsp ui [--lang auto|en|zh-CN]   打开只读交互式仪表盘
-rsp skills                      在 dual TTY 中打开交互式项目 Skill 管理器
-rsp skills list [--json]        列出内置 Skills 及其精确项目安装状态
-rsp skills install [name] [--dry-run] [--force]
-                                  将默认十一个 Skills 或一个精确可选 Skill 安装到 .agents/skills
-rsp add spec <name>             创建 .rsp/specs/<name>.md 并重建 specs 索引
-rsp create <name> [summary]     创建 .rsp/changes/<name>.md；可加 --lite 使用更短模板
-rsp group create <name> [goal] 创建不进入 focus 的 .rsp/changes/<name>/00-brief.md
-rsp group close <name>         所有子 Change 归档后关闭并归档 Group Brief
-rsp focus <name>                将一个 open change 标记为当前聚焦
-rsp unfocus <name>              将一个 open change 移出当前聚焦集合
-rsp archive <name>              归档到 .rsp/archives/
-rsp archive --dry-run <name>    已弃用的 rsp ready 兼容入口；不会移动 change
-rsp ready <name> [--json [--compact]] [--verbose]
-                                   canonical 只读归档就绪投影
-rsp show <name|--focused> [--json [--compact]] [--verbose]
-                                   显示 change 上下文，带就绪信号和上下文路径
-rsp history [--limit <n>] [--since <date>] [--until <date>] [--kind <kind>] [--group <group>] [--search <text>] [--json [--compact]]
-                                   列出有界的已归档 Change 摘要（默认 20，最大 100）
-rsp history <work-ref> [--json [--compact]]
-                                   显示一个精确已归档 Change 的有界证据详情
-rsp status [--focused|--blocked|--stale <days>] [--json [--compact]] [--verbose]
-                                   查看项目状态与派生依赖计划，并支持当前聚焦相关的轻量筛选
-rsp check [--focused] [--json [--compact]] [--verbose]
-                                   校验 change 文件，并对 template/scenario 结构做轻量 lint
-rsp doctor [--fix] [--json [--compact]] [--verbose]
-                                   检查接入健康和常见问题
+```bash
+pnpm docs:dev
+pnpm docs:check
+pnpm docs:build
 ```
 
-操作优先使用 `skills/rsp/SKILL.md`；skill 不可用时使用 `.rsp/rsp-rules.md` 作为最小 fallback protocol。
-
-在真实交互式终端中，裸 `rsp` 会打开与 `rsp ui` 相同的只读仪表盘。CI、管道、重定向流和 `TERM=dumb` 继续使用静态命令输出；人类快照使用 `rsp status`，自动化使用 `rsp status --json`。仪表盘不会创建、聚焦或归档工作。
-
-仪表盘快捷键：`Tab` 按 Changes/Groups/History 顺序切换，方向键或 `j`/`k` 移动，`/` 筛选当前 scope，`Enter` 打开全宽详情，`r` 刷新当前 scope，`?` 显示帮助，`q`、`Ctrl-C` 或顶层 `Esc` 退出。History 首次进入时才加载默认有界的近期结果，只有选中记录并按 `Enter` 后才按唯一 archive path 加载结构化详情；更早的记录使用 `rsp history` 过滤查询。可设置 `RSP_UI_LANG=en|zh-CN` 或传入 `rsp ui --lang`；只有仪表盘自有标签会本地化。该 UI 设置不会本地化 CLI help、纯文本输出、JSON、路径、命令、Skills 或已有产物。WorkRef 可使用安全 Unicode 身份契约，新产物正文则遵循上文的项目语言策略。
-
-当没有 focused change 时，`rsp status` 和 `rsp show --focused --json` 会输出 `nextActions`，但不会自动猜测哪个 open change 是当前工作。
-
-人类可读的 `rsp status` 会把执行指引渲染成依赖森林：父节点依赖其子节点，共享前置依赖以引用方式显示而不重复展开，`Next action` 直接指出当前可执行的 Change。
-
-`rsp status --json` 会在 `plan.nodes`、`plan.ready`、`plan.edges`、`plan.blocked` 和 `plan.waves` 中返回同一份依赖图。节点会区分过滤器选中的 Change 与仅用于解释的前置依赖上下文；过滤后的计划会保留解释结果所需的传递前置依赖闭包。由于同一个前置依赖可能被多个 Change 共享，JSON 保持扁平图结构而不嵌套 children。每条边都读作“`change` requires `requires`”。这些内容是派生的导航事实，不是执行授权或持久化 workflow state。
-
-`rsp history` 直接检查权威 archive 文件；系统不再生成或读取 Archive Index。列表按 archive date 降序、WorkRef、source path 排序，在 1–100 的结果上限前应用 inclusive date、精确 kind、精确 Group 以及 WorkRef/summary 的大小写不敏感字面搜索。详情只返回有界 summary、scenario/checkbox counts 与结构化 Tasks/Verify/Blockers evidence，不返回 raw Markdown；重复 WorkRef、不可读或格式错误的 archive 会 fail closed。`status` archive trend 与 TUI History 使用同一份已验证 inspection。
-
-产生 JSON 的 `status`、`show`、`ready`、`check`、`doctor` 和 `history` 都支持 `--json --compact`：内容与普通 `--json` 解析结果相同，但序列化为一行并以 LF 结尾。`--compact` 必须与 `--json` 同时使用，其他命令会在执行行为前拒绝它。
-
-`rsp create --lite` 是用于显式跟踪小 change 的短模板；简单的当前会话任务默认不应创建 RSP change，除非确实需要跟踪。
+网站只是本仓库 Markdown 的展示层。它提供双语导航、本地搜索和页面目录，不引入内容数据库或运行时服务。
 
-`rsp doctor --fix` 只执行安全 deterministic 修复。它的 JSON `fixed` 条目表示实际写入的文件系统变化；健康项目会返回 `fixed: []`，human 输出会说明无需安全修复。
+## 平台支持
 
-## 工具无关
+RSP 是与工具无关的文件约定，适用于任何能读取项目文件的助手或编辑器。人类从这里开始；AI 智能体遵循最近的 `AGENTS.md`，优先加载 `skills/rsp/SKILL.md`，仅在 Skill 不可用时使用 `.rsp/rsp-rules.md` 后备协议。
 
-`.rsp/` 是纯文件约定，适用于 Kilo Code、Cursor、Claude Code、Cline、GitHub Copilot 或任何能读取项目文件的 AI 助手。RSP 3.1 需要 Node.js 22+；从 3.0 升级时须先更新 Node.js 再安装。
+RSP 使用 [MIT 许可证](./LICENSE)。

package/dist/{chunk-3X2V6IEW.mjs → chunk-3Z4IO2TD.mjs}

@@ -5,7 +5,7 @@ import {
   inspectManagedDirectory,
   inspectManagedFileTree,
   resolveManagedDirectoryChain
-} from "./chunk-UVYEXKYS.mjs";
+} from "./chunk-WJXKLLIF.mjs";
 
 // src/commands/skills.ts
 import { randomUUID } from "crypto";

package/dist/{chunk-ZKZVWJQ7.mjs → chunk-MUNLLVVH.mjs}

@@ -29,7 +29,7 @@ import {
   resolveLanguagePolicy,
   resolveManagePolicy,
   toErrorMessage
-} from "./chunk-UVYEXKYS.mjs";
+} from "./chunk-WJXKLLIF.mjs";
 
 // src/status/inspect.ts
 import { readFile as readFile5, stat } from "fs/promises";

package/dist/{chunk-UVYEXKYS.mjs → chunk-WJXKLLIF.mjs}

@@ -651,8 +651,7 @@ function getChangeTemplateByKind(kind) {
     why: placeholder,
     scope: placeholder,
     nonGoals: placeholder,
-    specSection: `<!-- ${placeholder} -->
-### ${delta}
+    specSection: `### ${delta}
 - Requirement: ${placeholder}
   - ${placeholder}`,
     acceptanceSection: `#### Scenario: ${placeholder}

package/dist/cli.mjs

@@ -4,7 +4,7 @@ import {
   installPackagedSkills,
   printPackagedSkillInventory,
   printSkillInstallResult
-} from "./chunk-3X2V6IEW.mjs";
+} from "./chunk-3Z4IO2TD.mjs";
 import {
   ArchiveHistoryError,
   GROUP_BRIEF_FILENAME,
@@ -37,7 +37,7 @@ import {
   resolveWorkRef,
   selectArchiveHistoryRecord,
   selectArchivedGroupBrief
-} from "./chunk-ZKZVWJQ7.mjs";
+} from "./chunk-MUNLLVVH.mjs";
 import {
   ARCHIVES_DIR,
   CHANGES_DIR,
@@ -101,7 +101,7 @@ import {
   validateDecisionRecordsFilesystemPath,
   walkMarkdownFiles,
   writeManagedFile
-} from "./chunk-UVYEXKYS.mjs";
+} from "./chunk-WJXKLLIF.mjs";
 
 // src/cli.ts
 import { resolve } from "path";
@@ -3607,7 +3607,7 @@ async function runCli(rawArgs = process.argv.slice(2)) {
   if (shouldLaunchSkillsUi(rawArgs, terminalEnvironment)) {
     const { resolveUiLocale } = await import("./locale-HT44UIUP.mjs");
     const locale = resolveUiLocale("auto", process.env.RSP_UI_LANG, process.env.LC_ALL ?? process.env.LC_MESSAGES ?? process.env.LANG ?? new Intl.DateTimeFormat().resolvedOptions().locale);
-    const { runSkillsTui } = await import("./entry-BKEJDNOQ.mjs");
+    const { runSkillsTui } = await import("./entry-KAWA2AS4.mjs");
     const selection = await runSkillsTui(locale);
     if (selection.kind === "confirmed") {
       const result = await installPackagedSkills({ names: selection.names, force: selection.force });
@@ -3625,7 +3625,7 @@ async function runCli(rawArgs = process.argv.slice(2)) {
     } else {
       const { resolveUiLocale } = await import("./locale-HT44UIUP.mjs");
       const locale = resolveUiLocale(lang, process.env.RSP_UI_LANG, process.env.LC_ALL ?? process.env.LC_MESSAGES ?? process.env.LANG ?? new Intl.DateTimeFormat().resolvedOptions().locale);
-      const { runTui } = await import("./entry-ETZGIFKP.mjs");
+      const { runTui } = await import("./entry-IPHJBI53.mjs");
       const exitCode = await runTui(locale);
       if (exitCode !== 0)
         process.exitCode = exitCode;

package/dist/{entry-ETZGIFKP.mjs → entry-IPHJBI53.mjs}

@@ -7,14 +7,14 @@ import {
   projectDependencyForest,
   queryArchiveHistory,
   readArchiveHistoryDetail
-} from "./chunk-ZKZVWJQ7.mjs";
+} from "./chunk-MUNLLVVH.mjs";
 import {
   displayWidth,
   openTerminalSession,
   truncateDisplay,
   wrapDisplay
 } from "./chunk-JOMFFQRG.mjs";
-import "./chunk-UVYEXKYS.mjs";
+import "./chunk-WJXKLLIF.mjs";
 
 // src/tui/entry.tsx
 import process from "process";

package/dist/{entry-BKEJDNOQ.mjs → entry-KAWA2AS4.mjs}

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   inspectPackagedSkillInventory
-} from "./chunk-3X2V6IEW.mjs";
+} from "./chunk-3Z4IO2TD.mjs";
 import {
   openTerminalSession,
   truncateDisplay
 } from "./chunk-JOMFFQRG.mjs";
-import "./chunk-UVYEXKYS.mjs";
+import "./chunk-WJXKLLIF.mjs";
 
 // src/skills-tui/entry.tsx
 import process from "process";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oevery/rsp",
   "type": "module",
-  "version": "3.1.0-beta.5",
+  "version": "3.1.1",
   "description": "RSP (Reliable Software Practice), a repository-native engineering workflow for humans and AI agents",
   "author": "oevery",
   "license": "MIT",
@@ -37,13 +37,18 @@
   },
   "scripts": {
     "prepare": "pnpm run build",
-    "release:check": "pnpm run release:metadata-check && pnpm run build && pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run release:package-check",
+    "release:check": "pnpm run release:metadata-check && pnpm run docs:check && pnpm run docs:build && pnpm run build && pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run release:package-check",
     "release:candidate-check": "node scripts/release-candidate-check.mjs && pnpm run release:check",
     "release:metadata-check": "node scripts/release-metadata-check.mjs",
     "release:package-check": "node scripts/clean-install-check.mjs",
     "prepublishOnly": "pnpm run release:candidate-check",
     "build": "tsup",
     "dev": "tsup --watch",
+    "docs:build": "vitepress build docs",
+    "docs:check": "node scripts/docs-check.mjs",
+    "docs:deploy": "wrangler deploy",
+    "docs:dev": "vitepress dev docs",
+    "docs:preview": "vitepress preview docs",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "typecheck": "tsc --noEmit",
@@ -65,6 +70,8 @@
     "ink-testing-library": "4.0.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.10"
+    "vitepress": "^1.6.4",
+    "vitest": "^4.1.10",
+    "wrangler": "^4.114.0"
   }
 }

package/skills/rsp-commit/SKILL.md

@@ -37,7 +37,9 @@ Project every owned issue relationship as a non-closing `Issue: <canonical-url>`
 
 Stage only the explicit allowed paths. Re-read `git status --short`, inspect the complete cached path list and cached diff, and confirm they represent exactly one owner boundary with no sensitive material. If the cached boundary is wrong, stop and leave unrelated work untouched; do not repair it by broad staging, destructive reset, or history rewrite.
 
-Create one local commit with the prepared subject, optional body, and trailers. Do not push, tag, publish, amend, rebase, or force-push. Afterward observe `HEAD`, the complete committed message, committed paths, remaining worktree state, and remote refs when a remote-safety assertion is required. A commit command succeeding is insufficient if the observed message or paths differ from the prepared boundary.
+Transport a structured multiline message with actual line breaks or a safely prepared message file. Do not rely on ordinary quoted `\n` escape sequences as portable newlines; a host shell may pass those characters through literally.
+
+Create one local commit with the prepared subject, optional body, and trailers. Do not push, tag, publish, amend, rebase, or force-push. Afterward observe `HEAD`, the raw complete committed message, committed paths, remaining worktree state, and remote refs when required. A successful commit is still a post-commit mismatch when the observed message differs from the prepared message, including unintended literal `\n` sequences; report and stop without inferring amend or second-commit authority.
 
 ## Return the receipt