planr 1.5.0 → 1.5.1

package/README.md

@@ -4,6 +4,10 @@
 
 Planr is a local-first planning and execution coordination tool for coding agents. It combines reviewable Markdown plans with a dependency-aware work map so Codex, Claude Code, Cursor, generic MCP clients, and human operators can drive the same work safely — from idea to verified completion.
 
+[**View the Demo →**](https://x.com/kevinkern/status/2066957434564808884?s=20)
+
+[**Documentation →**](https://planr.so/docs)
+
 ```text
 idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> close
 ```
@@ -40,7 +44,7 @@ Or with the release installer:
 curl -fsSL https://raw.githubusercontent.com/instructa/planr/main/scripts/install.sh | sh
 ```
 
-Then initialize a project (also provisions the worker/reviewer subagent roles for your client):
+Then initialize a project. When selected, Claude Code and Cursor also receive standalone project worker/reviewer roles; Codex workflow skills come from its plugin:
 
 ```bash
 planr project init "My Product" --client all
@@ -86,7 +90,7 @@ One command installs everything the plugin would carry:
 
 ```bash
 planr install cursor            # writes .cursor/mcp.json, .cursor/agents/, and .cursor/skills/
-planr install cursor --no-mcp   # skills and subagents only, no MCP config
+planr install cursor --no-mcp   # project skills, subagents, and hooks; no MCP config
 ```
 
 The dry-run also prints a one-click `cursor://` deeplink for user-level MCP install. Marketplace listing is pending review. Multitasking with Cursor subagents: [Cursor guide](docs/CURSOR.md).
@@ -108,7 +112,7 @@ planr prompt cli
 
 ## Tell Your Agent
 
-Two skills drive everything. `$planr` routes any request to the right stage skill from live map state; `$planr-loop` drives one feature through work, live verification, and independent review until the map is clean.
+Remember one public entry point: `$planr`. It routes the request from live Planr state, including planning-only work and autonomous-goal preparation. Stage skills are advanced surfaces selected by the router.
 
 Start a new product from an idea:
 
@@ -119,10 +123,13 @@ Create a production-ready Habit Tracker web app plan. Create the product plan,
 split an MVP build plan, check it, then build the Planr map. Do not implement yet.
 ```
 
-Ship one feature autonomously until verified:
+For a long autonomous run, prepare outside the driver first. The preparation result prints a real plan id; Codex or Claude Code then starts only the plan-bound loop driver:
 
 ```text
-Use $planr-loop.
+Use $planr to prepare an autonomous goal for the weekly overview feature.
+
+/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr
+context (tag: goal-contract).
 
 Goal: ship the weekly overview feature. DONE when every in-scope map item is closed
 with log evidence, all reviews are closed complete, and a live verification log shows

package/docs/CLAUDE_CODE.md

@@ -38,7 +38,7 @@ planr install claude
 planr doctor --client claude
 ```
 
-Dry-run prints both project-scope `.mcp.json` content and the user-scope CLI form. The non-dry command writes only this repository's `.mcp.json`.
+Dry-run prints both project-scope `.mcp.json` content and the optional user-scope CLI form. The non-dry command writes this repository's `.mcp.json`, standalone worker/reviewer roles, and additive fail-open session hooks. Workflow skills and plugin agents come from the Claude Code plugin. Use `--no-mcp` to omit `.mcp.json`, or `--no-hooks` to omit hook reconciliation.
 
 Claude Code should treat Planr map state as authoritative and use Markdown plans as context.
 
@@ -49,4 +49,4 @@ planr review ingest <item-id> --from .planr/tmp/claude-review.json
 planr review artifact <review-item-id>
 ```
 
-Planr does not install shell hooks or edit global Claude Code configuration. The review item remains open until `planr review close` records the final verdict.
+Planr does not edit global Claude Code configuration. Project hooks live in `.claude/settings.json`, preserve foreign entries, and can be omitted with `--no-hooks`. The review item remains open until `planr review close` records the final verdict.

package/docs/CURSOR.md

@@ -19,13 +19,13 @@ Re-running the command refreshes `.cursor/mcp.json` but never overwrites edited
 
 ## Skills And Agents Only (No MCP)
 
-The skills are CLI-first — they drive the `planr` binary directly through the terminal — so MCP is optional. For a plugin-style install that writes only the subagents and skills:
+The skills are CLI-first — they drive the `planr` binary directly through the terminal — so MCP is optional. To install project subagents, skills, and the default hooks without MCP:
 
 ```bash
 planr install cursor --no-mcp
 ```
 
-This writes `.cursor/agents/` and `.cursor/skills/` and nothing else: no `.cursor/mcp.json`, no deeplink. Everything below (subagent dispatch, parallel work, goal loops) works identically in this mode because the skills call `planr pick`, `planr done`, `planr review ...` as shell commands. `--no-mcp --dry-run` lists the files that would be written. The flag works for `claude` and `codex` too (roles only; their skills ship via each host's plugin system).
+This writes `.cursor/agents/`, `.cursor/skills/`, and the default project hooks, but no `.cursor/mcp.json` or deeplink. Add `--no-hooks` when hooks must also be skipped. Everything below works in this mode because the skills call the Planr CLI directly. `--no-mcp --dry-run` lists the roles and skills and states whether the non-dry run would reconcile hooks. For Claude Code the flag writes standalone project roles and hooks but no project skills; for Codex it writes hooks only. Their workflow skills come from their respective plugins.
 
 ## One-Click MCP Install
 

package/docs/INSTALL.md

@@ -72,9 +72,9 @@ planr prompt cli --client codex
 planr prompt http
 ```
 
-`planr install claude` writes a project `.mcp.json` plus static workflow roles. `planr install cursor` writes `.cursor/mcp.json`, static workflow roles, and Planr skills, then prints a user-level MCP deeplink. `planr install codex` writes only the project MCP snippet. Optional model pins and generated host roles come from a repository-local routing bundle. Dry-runs print exact paths first; no command touches global user configuration.
+`planr install codex` writes a project MCP snippet and project hooks; its workflow skills come from the Codex plugin, and it writes no project roles or skills. `planr install claude` writes project `.mcp.json`, standalone worker/reviewer roles, and hooks; workflow skills come from the Claude Code plugin. `planr install cursor` writes project MCP, roles, all ten skills, and hooks, then prints an optional user-level MCP deeplink. Optional model pins come from a repository-local routing bundle. Dry-runs print the complete repository artifact and hook-reconciliation paths without writing them; no command silently edits global user configuration.
 
-Skills-and-agents-only setups (no MCP) use `--no-mcp`: `planr install cursor --no-mcp` writes the subagents and skills but no MCP config — the skills drive the `planr` CLI directly, so nothing is lost except MCP tool access.
+`--no-mcp` skips only the project MCP artifact. Codex then reconciles hooks only; Claude Code writes standalone project roles and hooks but no project skills; Cursor writes project roles, skills, and hooks. Add `--no-hooks` to skip hooks as well. The Codex and Claude Code plugins remain the owners of their workflow skills.
 
 Runtime surfaces:
 
@@ -87,7 +87,7 @@ Open `http://127.0.0.1:7526/review` after `planr serve` for the local browser re
 
 ## Agent Skills And Plugin
 
-The repository ships a plugin under `plugins/planr` for Codex and Claude Code that bundles Planr workflow skills; Claude Code additionally registers static workflow roles. Cursor receives the same skills and static roles through `planr install cursor`. Model-specific role files are optional routing-bundle artifacts. The CLI above must be installed separately. See [Skills](SKILLS.md).
+The repository ships a plugin under `plugins/planr` for Codex and Claude Code that bundles all ten workflow skills; Claude Code additionally registers plugin worker/reviewer agents. The Codex plugin does not register project agents. Cursor receives the ten skills and both project agents through `planr install cursor` (or its plugin manifest). Model-specific role files are optional routing-bundle artifacts. The CLI above must be installed separately. See [Skills](SKILLS.md).
 
 ## From Source
 

package/docs/MCP_CONTRACT.md

@@ -62,12 +62,12 @@ HTTP mirrors the same rule: `GET /v1/reviews/:id/artifact` is read-only; `POST /
 
 ## Install Contract
 
-`planr install <client> --dry-run` prints project-scoped configuration for Codex, Claude Code, and Cursor. Non-dry install writes only repository-local files:
+`planr install <client> --dry-run` prints the complete client-owned MCP, role, skill, and hook-reconciliation paths for Codex, Claude Code, and Cursor without writing them. Non-dry install writes only repository-local files, with this ownership contract:
 
-- Codex: `.planr/integrations/codex-mcp.toml`; optional `.codex/agents/` roles are routing-bundle artifacts
-- Claude Code: `.mcp.json` plus `.claude/agents/` roles
-- Cursor: `.cursor/mcp.json` plus `.cursor/agents/` roles and `.cursor/skills/` skill copies
+- Codex: the CLI writes `.planr/integrations/codex-mcp.toml` and `.codex/hooks.json`; the plugin owns all ten workflow skills; neither path writes Planr project roles or project skills
+- Claude Code: the CLI writes `.mcp.json`, standalone `.claude/agents/` roles, and `.claude/settings.json` hooks, but no project skills; the plugin owns all ten workflow skills and its plugin agents
+- Cursor: the CLI writes `.cursor/mcp.json`, both `.cursor/agents/` roles, all ten `.cursor/skills/` skill copies, and `.cursor/hooks.json`
 
 The Cursor dry-run additionally prints a `cursor://anysphere.cursor-deeplink/mcp/install` link whose embedded config (`planr mcp`, no `--db`) is safe at user scope because each workspace resolves its own database. Planr does not edit global client configuration without a separate explicit operator action; the deeplink requires the operator to click it and confirm inside Cursor.
 
-`planr install <client> --no-mcp` is the plugin-style variant: it writes the subagent roles (and, for Cursor, the skills) but no MCP configuration at all, for setups that use skills and agents over the CLI only.
+`--no-mcp` skips only the project MCP artifact: Codex reconciles hooks only; Claude Code writes standalone roles and hooks but no project skills; Cursor writes roles, all ten skills, and hooks. `--no-hooks` is the independent hook opt-out and can be combined with `--no-mcp`.

package/docs/RELEASE.md

@@ -25,7 +25,7 @@ The script enforces, in order:
 1. branch is `main`, worktree is clean, `CHANGELOG.md` already has a committed `## [x.y.z]` section, and the tag does not exist;
 2. the version is written into all four manifests plus `Cargo.lock`;
 3. gates: `cargo test` (includes the manifest drift guard in `tests/e2e.rs`), `npm pack --dry-run`, and `scripts/security-local.sh` (betterleaks + trivy leak gate);
-4. one mechanical commit `release x.y.z: <summary>`, tag `vx.y.z`, and a single push of branch plus tag.
+4. one mechanical commit `release x.y.z: <summary>`, an annotated `vx.y.z` tag carrying that summary, and a single push of branch plus tag.
 
 Two independent gates back the script:
 

package/docs/SKILLS.md

@@ -50,14 +50,14 @@ Stage skills (what the router and loop dispatch to; also directly invocable):
 
 ## Cheat Sheet
 
-Default usage needs two skills:
+Default usage needs one public entry point:
 
 ```text
 $planr        any request -> routed to the right stage skill from live map state
-$planr-loop   one feature -> loop work/verify/review/fix until done or budget exhausted
-$planr-goal   broad goal -> plan + map + durable contract + starter for /goal or manual loops
 ```
 
+`$planr-goal` and `$planr-loop` are advanced stage surfaces selected by the router. A long-running goal is always prepared first; only the resulting real plan id is passed to the loop driver.
+
 The stage order the router follows for a new app:
 
 ```text
@@ -81,10 +81,13 @@ Create the product plan, split an MVP build plan, check it, then build the Planr
 Do not implement yet. End with the build plan id, critical lane, and first ready items.
 ```
 
-Example autonomous feature loop:
+Example autonomous feature loop (two separate prompts):
 
 ```text
-Use $planr-loop.
+Use $planr to prepare an autonomous goal for the weekly overview feature.
+
+/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr
+context (tag: goal-contract).
 
 Goal: ship the weekly overview feature. DONE when every in-scope map item is closed with
 log evidence, all reviews are closed complete, and a live verification log shows the
@@ -103,7 +106,7 @@ Do not close the item until review is complete.
 
 ## Two Journeys: New Project vs. Existing Project
 
-Both journeys use the same entry point (`$planr` or `$planr-loop`). What differs is the state the router finds, and what kind of plan the work gets.
+Both journeys use the same public entry point (`$planr`). What differs is the state the router finds, and what kind of plan the work gets.
 
 ### Journey 1 — start a project from an idea
 
@@ -120,7 +123,7 @@ Create a production-ready Habit Tracker web app plan. Create the product plan,
 split an MVP build plan, check it, then build the Planr map. Do not implement yet.
 ```
 
-The router runs the full stage order: product plan -> build plan -> map -> work. From there, `$planr-loop` or `$planr-work` executes against the map.
+The router runs the full stage order: product plan -> build plan -> map. From there it can select `$planr-work`, or prepare a plan-bound `$planr-loop` run.
 
 ### Journey 2 — mid-project: add a feature, refactor, or fix
 
@@ -138,12 +141,15 @@ What the router does with that, and why:
 
 1. `$planr-plan` creates a new plan scoped to the feature (`planr plan new "Auth system" ...`), not a new project. Refine notes capture constraints from the existing codebase; the build plan's "existing leverage" field records what is reused instead of rebuilt.
 2. `$planr-task-graph` extends the existing map: new items, plus `blocks` links to anything already on the map that must land first.
-3. Execution is identical to journey 1: `$planr-loop` for autonomous, `$planr-work` / `$planr-review` for human-in-the-loop.
+3. Execution is identical to journey 1: a plan-bound `$planr-loop` for autonomous work, or `$planr-work` / `$planr-review` for human-in-the-loop.
 
-Or autonomous in one prompt:
+Or autonomous in two prompts:
 
 ```text
-Use $planr-loop.
+Use $planr to prepare an autonomous goal for the auth system.
+
+/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr
+context (tag: goal-contract).
 
 Goal: ship an auth system (email+password, sessions, protected routes).
 DONE when every auth map item is closed with log evidence, all reviews are closed
@@ -164,8 +170,8 @@ Rules that hold in both journeys:
 The CLI provisions the role files automatically — no manual copying:
 
 ```bash
-planr project init "My Product" --client all   # writes .codex/agents/*.toml, .claude/agents/*.md, and .cursor/agents/*.md
-planr agents init                              # generates canonical native Codex roles in an existing project
+planr project init "My Product" --client all   # writes standalone Claude and Cursor roles; Codex has no project roles
+planr agents init                              # writes the provider-neutral .planr/agents.toml registry; it does not generate Codex roles
 planr install claude                           # provisions Claude's independent roles
 planr install cursor                           # provisions Cursor's independent roles and skills
 ```
@@ -176,57 +182,34 @@ Dispatches stay one line: `Use $planr-work on item <id>` and `Use $planr-review
 
 ## Install For Codex
 
-Copy the Planr skills into Codex's local skill directory:
-
-```bash
-mkdir -p ~/.codex/skills
-cp -R plugins/planr/skills/* ~/.codex/skills/
-```
-
-If Planr was installed from an npm package that includes `skills/`, copy from the package location instead:
-
-```bash
-PLANR_PKG="$(npm root -g)/planr"
-mkdir -p ~/.codex/skills
-cp -R "$PLANR_PKG"/plugins/planr/skills/* ~/.codex/skills/
-```
-
-Do not present `npx planr` as the primary install path until the npm artifact ships platform-native Planr binaries. Today the normal user path is the GitHub Release installer; npm is a development and consumer-test wrapper.
-
-Then run Codex from a repository where `planr` is installed and initialized:
+Install the Codex plugin for all ten workflow skills, then initialize and install the project integration:
 
 ```bash
+codex plugin marketplace add instructa/planr
+codex plugin add planr@planr
 planr project init "Example Product" --client codex
+planr install codex
 planr doctor --client codex
 ```
 
-Codex can also use Planr through MCP:
-
-```bash
-planr install codex --dry-run
-planr prompt mcp --client codex
-```
+The CLI writes the project MCP snippet and hooks. It does not copy project skills or agents; those skills are plugin-owned, and Codex has no Planr project-agent contract. `--no-mcp` leaves hooks only, while `--no-mcp --no-hooks` writes neither integration artifact.
 
 ## Install For Claude Code
 
-Claude Code loads project skills from `.claude/skills/`:
+Install the Claude Code plugin for all ten workflow skills and its plugin worker/reviewer agents, then install the project integration:
 
-```bash
-mkdir -p .claude/skills .claude/agents
-cp -R plugins/planr/skills/* .claude/skills/
-cp plugins/planr/agents/*.md .claude/agents/
+```text
+/plugin marketplace add instructa/planr
+/plugin install planr@planr
 ```
 
-Then add MCP and the Planr workflow prompt to project instructions when needed:
-
 ```bash
 planr project init "Example Product" --client claude
-planr install claude --dry-run
-planr prompt mcp --client claude
-planr prompt cli --client claude
+planr install claude
+planr doctor --client claude
 ```
 
-`planr install claude` writes a project-scoped `.mcp.json` when not run as a dry-run.
+The CLI writes project-scoped `.mcp.json`, standalone project worker/reviewer roles, and hooks. It does not copy project skills. `--no-mcp` retains the standalone roles and hooks; add `--no-hooks` to omit hooks.
 
 ## Install For Cursor
 
@@ -237,7 +220,7 @@ planr project init "Example Product" --client cursor
 planr install cursor
 ```
 
-`planr install cursor` writes `.cursor/mcp.json`, copies the ten skills to `.cursor/skills/`, provisions `.cursor/agents/planr-worker.md` and `planr-reviewer.md`, and prints a one-click deeplink for user-level MCP install. Prefer skills and agents without MCP? `planr install cursor --no-mcp` writes only the subagents and skills — the skills are CLI-first, so the whole workflow runs through the `planr` binary. Invoke skills with `/planr` or `/planr-loop` in Agent chat, and dispatch subagents with `/planr-worker` and `/planr-reviewer`. Use `planr serve --port 7526` and `planr prompt http --client cursor` if a Cursor workflow should inspect the local HTTP/review workspace. Subagent multitasking and worktree guidance: [Cursor](CURSOR.md).
+`planr install cursor` writes `.cursor/mcp.json`, copies the ten skills to `.cursor/skills/`, provisions `.cursor/agents/planr-worker.md` and `planr-reviewer.md`, reconciles hooks, and prints a one-click deeplink for user-level MCP install. `planr install cursor --no-mcp` retains the agents, skills, and hooks while omitting MCP; add `--no-hooks` to omit hooks. Invoke the public router with `/planr` in Agent chat, and dispatch subagents with `/planr-worker` and `/planr-reviewer`. Use `planr serve --port 7526` and `planr prompt http --client cursor` if a Cursor workflow should inspect the local HTTP/review workspace. Subagent multitasking and worktree guidance: [Cursor](CURSOR.md).
 
 ## MCP-Only Clients
 

package/docs/documentation/CONTRACT.md

@@ -0,0 +1,164 @@
+# Planr Documentation Contract
+
+Status: approved implementation contract for the Planr documentation site
+Last audited: 2026-07-17
+Scope owner: `apps/docs` (site and English product documentation)
+
+This contract turns the current product, runtime, and repository documentation into one maintainable public documentation system. It is intentionally separate from the product specification package: `docs/planr-spec/` remains the product source of truth, while the site explains the released product to users and contributors.
+
+## Source hierarchy
+
+When sources disagree, authors must use this order and disclose the disagreement instead of silently choosing convenient copy:
+
+1. **Product intent and invariants:** `AGENTS.md` and `docs/planr-spec/`, especially `PRODUCT_SPEC.md`, `TECH_ARCHITECTURE.md`, and `API_AND_DATA_MODEL.md`.
+2. **Released executable behavior:** compiled `planr --help` output, `src/cli.rs`, `src/app/mcp.rs`, `src/app/http.rs`, `src/model.rs`, and the tested fixture `docs/fixtures/mcp-contract.json`. Runtime sources decide whether a command, option, schema, endpoint, state, or error exists in the current release.
+3. **Distribution contract:** `Cargo.toml`, `package.json`, `pnpm-workspace.yaml`, release workflows, installers, and release tests. These decide supported versions, artifacts, operating systems, and install commands.
+4. **Existing explanatory material:** `README.md`, `docs/*.md`, `plugins/planr/skills/`, examples, and routing-package docs. These are migration inputs, not independent sources of truth.
+5. **External references:** official upstream documentation and inspected local projects may influence structure and implementation, but never define Planr behavior.
+
+If product intent is ahead of runtime, the public page must label the behavior as planned or omit it from executable instructions. If runtime is ahead of an older specification sentence, the public page documents the tested runtime and the discrepancy is added to the conflict register below.
+
+## Canonical terminology
+
+Use these terms exactly. Prefer the lowercase form in prose unless it starts a sentence.
+
+| Term | Public definition | Do not substitute |
+| --- | --- | --- |
+| Planr | The local-first planning and execution coordination product. | project manager, cloud orchestrator |
+| project | One repository or multi-root workspace tracked by Planr. | workspace when referring to the stored object |
+| product plan | A Markdown specification package that captures product intent. | PRD when the broader package is meant |
+| build plan | A focused Markdown implementation contract for a buildable slice. | task list |
+| map | The authoritative live dependency graph. | board, checklist |
+| item | A node in the map with status, work type, ownership, and evidence. | ticket, task when referring to the stored object |
+| link | A directed relation between items, normally `blocks`. | dependency edge in introductory prose |
+| pick | An atomic lease of one ready item to one worker. | assignment, claim unless explaining the concept |
+| worker | The identity holding the active pick. | agent when ownership specifically matters |
+| log | Durable evidence or progress attached to an item. | transcript |
+| verification log | A log with kind `verification` that records a live oracle. | test result alone |
+| review | A graph gate that checks evidence and can create fix/follow-up work. | approval; approvals are a separate human gate |
+| approval | An explicit requested/approved/denied human decision on an item. | review |
+| context | A durable discovery, decision, constraint, or goal contract. | memory |
+| artifact | Item-linked or project evidence such as a report, screenshot, or review file. | attachment when referring to the stored object |
+| recovery sweep | A preview/apply operation for stale, timed-out, and retryable work. | automatic retry loop |
+| package | A reusable export/import bundle of graph and optional Planr artifacts. | backup unless that is the user's intent |
+| routing bundle | A provider-neutral, validated set of repository-local routing artifacts. | model config |
+| goal contract | Durable Planr context defining the completion oracle and stop condition. | prompt-only instruction |
+
+The canonical lifecycle is always:
+
+```text
+idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> recovery/package -> close
+```
+
+## Selected documentation stack
+
+The docs worker must create `apps/docs` in the existing pnpm workspace and pin direct dependencies exactly. The lockfile remains the transitive dependency authority.
+
+| Component | Selected version | Rationale and evidence |
+| --- | --- | --- |
+| Fumadocs Core | `16.11.5` | npm `latest` on 2026-07-17; supplies source loading and built-in Orama search. Its peers accept Next.js `16.x` and React `^19.2.0`. |
+| Fumadocs UI | `16.11.5` | npm `latest` on 2026-07-17; supplies accessible layouts and docs components. Its peer contract requires Core exactly `16.11.5`, Next.js `16.x`, and React `^19.2.0`. |
+| Fumadocs MDX | `15.2.0` | npm `latest` on 2026-07-17; its major version is independent from Core/UI. Its peers accept Core `^16.7.0`, Next.js `^15.3.0 || ^16.0.0`, and React `^19.2.0`. |
+| Next.js | `16.2.10` | Current stable Next.js 16 line required by the official Fumadocs Next.js guide. |
+| React and React DOM | `19.2.7` | npm `latest` on 2026-07-17; satisfies the selected Fumadocs packages' `^19.2.0` peer requirement and Next.js 16's React 19 range. |
+| Tailwind CSS | `4.x`, exact patch chosen at scaffold time | Fumadocs UI supports Tailwind 4 only; record the resolved exact patch in `apps/docs/package.json`. |
+| Node.js | `>=22` for the docs workspace | Official Fumadocs quickstart requires Node 22. This does not change the published Planr CLI npm wrapper's Node 18 runtime contract. |
+| Package manager | repository-pinned pnpm `11.5.3` | Avoids a second package manager and keeps workspace scripts reproducible. |
+
+Evidence captured from official upstream sources:
+
+- Fumadocs quickstart and Node requirement: <https://www.fumadocs.dev/docs>
+- Fumadocs manual Next.js setup: <https://www.fumadocs.dev/docs/manual-installation/next>
+- Fumadocs UI themes and Tailwind 4 contract: <https://www.fumadocs.dev/docs/ui/theme>
+- Fumadocs layout API: <https://www.fumadocs.dev/docs/ui/layouts/docs>
+- Fumadocs deployment constraints: <https://www.fumadocs.dev/docs/deploying>
+- Alchemy v2 Cloudflare setup: <https://alchemy.run/cloudflare/setup/>
+- Alchemy v2 frontend resources: <https://alchemy.run/cloudflare/frontend/frontends/>
+- Alchemy v2 domains and DNS: <https://alchemy.run/cloudflare/networking/domains/>
+- Stable package versions and peer ranges were replayed from the npm registry with `npm view <package>@latest version peerDependencies --json` on the audit date. The selected Core/UI/MDX/Next.js set satisfies every declared peer range.
+
+Do not use `latest`, caret, tilde, or wildcard ranges for direct docs dependencies. A later upgrade is an explicit, reviewed dependency change with build, search, and browser verification.
+
+## Architecture decisions
+
+### DOC-ADR-001: One first-class workspace app
+
+Create one English documentation application at `apps/docs`. It owns the public landing page, guides, reference, search, metadata, and deployment. Existing `docs/*.md` files remain source/reference material during migration; once a topic has a canonical site page, the old file becomes either a concise pointer or a checked redirect source, not a second maintained copy.
+
+### DOC-ADR-002: Next.js App Router with local MDX
+
+Use Next.js 16 App Router, Fumadocs MDX, and content under `apps/docs/content/docs`. This is the most direct officially documented Fumadocs path and gives Planr a conservative deployment surface. Use `source.config.ts`, a generated `.source` directory, `fumadocs-core/source`, the Fumadocs root provider, and the standard docs catch-all route.
+
+Rejected for this scope:
+
+- TanStack Start: AgentRig proves it is viable, but it adds routing/build decisions that Planr does not otherwise own and is not needed for a documentation-only app.
+- A bespoke Rust-rendered site or the `planr-routing/website` static implementation: neither supplies the requested polished docs authoring/search system.
+
+### DOC-ADR-003: Deploy with Alchemy and OpenNext on Cloudflare Workers
+
+Use an Alchemy v2 Effect stack and OpenNext as the committed deployment owner. `Cloudflare.Website.StaticSite` runs the OpenNext build, uploads its prebuilt Worker with `bundle: false`, and serves the generated assets. Bind `docs.planr.so` only when the Alchemy stage is `prod`; development and preview stages use generated URLs. The Cloudflare zone must already exist in the authenticated account. Local credentials live in the Alchemy profile, shared state uses `Cloudflare.state()`, and CI verifies the OpenNext Worker artifact without deploying it.
+
+### DOC-ADR-004: Use Fumadocs primitives before copying components
+
+Adopt `DocsLayout`, page tree navigation, breadcrumbs, table of contents, built-in search, MDX components, theme support, and metadata APIs. Customize with documented props, slots, stable ids/data attributes, and Planr design tokens. Do not fork layout components on day one; Fumadocs explicitly warns that copied components stop receiving upstream UI updates.
+
+### DOC-ADR-005: Navigation is explicit and task-first
+
+Use directory `meta.json` files to make the navigation order deliberate. The first paths are evaluation, installation, quickstart, and a complete lifecycle tutorial. Concepts explain the mental model; guides solve tasks; reference mirrors executable surfaces; contributor and operations pages explain maintenance.
+
+### DOC-ADR-006: Reference is generated or mechanically checked
+
+The CLI and MCP inventories must be derived from compiled help and the tested MCP fixture/schema. Hand-authored explanations can enrich them, but CI must fail when a public command/tool/resource/prompt lacks a target page. HTTP routes must be extracted or checked against `src/app/http.rs`. JSON examples must be replayed by tests or fixtures.
+
+### DOC-ADR-007: AgentRig is structural inspiration, not a template dependency
+
+The requested path `~/projects/agentrig-mono/agentrig/apps/docs` no longer exists. The active inspected reference is `~/projects/agentrig-mono/agentrig-public/apps/docs`.
+
+Adopted patterns:
+
+- an `apps/docs` workspace boundary;
+- local MDX collections plus `meta.json` page trees;
+- an overview with audience-specific cards and quick paths;
+- compact installation, integration, guide, contribution, and reference sections;
+- a shared layout options module, source loader, MDX component registry, search endpoint, explicit 404/error UI, and theme control.
+
+Rejected patterns:
+
+- direct dependencies set to `latest`;
+- product-specific TanStack/Alchemy infrastructure;
+- manually curated CLI pages without a drift check;
+- copying AgentRig wording, branding, images, or product taxonomy.
+
+## Conflict and gap register
+
+These findings are explicit inputs to implementation and content review.
+
+| ID | Finding | Resolution in the site |
+| --- | --- | --- |
+| GAP-001 | `docs/CLI_REFERENCE.md` says it is generated from help but omits current commands including `project delete`, `plan list`, `map export/import`, `item show/cancel`, `link remove`, `log show/list`, `review request/list/show`, `note`, and `scrub`. | Replace the list with generated/mechanically checked reference data; retain editorial detail around it. |
+| GAP-002 | `docs/planr-spec/PRODUCT_SPEC.md` still calls Rust and the HTTP server open decisions, but the repository ships a Rust binary and `planr serve`. | Document current released behavior; update product specs only in a separately scoped product-spec change. |
+| GAP-003 | `docs/ARCHITECTURE.md` describes one crate and one deployable while the root Cargo workspace includes the independent `planr-routing` member/package. | The architecture page must describe Planr Core and optional `planr-routing` ownership separately. |
+| GAP-004 | README leads with Homebrew, while `docs/INSTALL.md` calls GitHub Releases/repo installer canonical and Homebrew preferred day-to-day. | Say “Homebrew recommended on macOS”; GitHub Releases are the canonical artifact source; npm is the cross-package-manager native-binary path. |
+| GAP-005 | The CLI npm wrapper supports Node 18, while latest Fumadocs requires Node 22. | Keep separate requirement callouts: Planr CLI Node 18; docs contributors Node 22. |
+| GAP-006 | Product personas mention Gemini CLI and generic clients, but install helpers exist only for Codex, Claude Code, and Cursor. | Give the three supported clients first-class setup pages; route Gemini/opencode/other tools through clearly labeled generic CLI or stdio MCP instructions. Do not imply a native installer. |
+| GAP-007 | `planr install` uses the subcommand `claude`, while product prose often says “Claude Code”. | Use “Claude Code” in headings and `planr install claude` in commands. |
+| GAP-008 | Product specs mention optional HTTP/SSE and “streamable HTTP” in client expectations, but the implemented MCP transport is stdio; `planr serve` is a separate localhost HTTP/SSE API and review UI. | Keep MCP transport and local HTTP API separate. Do not advertise streamable-HTTP MCP support unless implemented and tested. |
+| GAP-009 | Existing flat Markdown pages overlap heavily across README, install, skills, operating model, and client guides. | Assign one canonical site page per concept/task; other pages link to it instead of restating the procedure. |
+| GAP-010 | The initial repository had no website package, search index, redirect policy, link checker, freshness owner, or browser accessibility gate. | Implemented in `apps/docs`: Fumadocs search, executable redirects, maintenance drift checks, governance ownership, and production-browser axe evidence. |
+| GAP-011 | The requested AgentRig path is stale. | Use `agentrig-public/apps/docs` only as recorded prior art; never make it a build dependency. |
+| GAP-012 | Windows native assets are not in the public install contract. | Installation clearly labels macOS/Linux native support and WSL/source alternatives; no unsupported Windows-native promise. |
+| GAP-013 | `opencode` appears in README but is not a first-class install target. | Include it only as an example on the generic CLI/MCP page, with no plugin or installer guarantee. |
+| GAP-014 | The optional `planr-routing` package has its own CLI, catalog, policies, bindings, and website artifacts outside the core CLI reference. | Give routing its own concept/guide/reference pages and label the package optional. |
+
+## Explicit exclusions
+
+- No localization in the initial release; English is canonical. The content structure must remain localization-ready.
+- No hosted account, analytics, feedback database, or cloud search service.
+- No OpenAPI rendering until Planr exposes a maintained OpenAPI document.
+- No documentation for unimplemented cloud sync, team dashboard, native Windows artifact, Gemini installer, or streamable-HTTP MCP transport.
+- No automatic execution of destructive examples. Preview-first examples are mandatory for delete, cancellation, replan, recovery apply, scrub, and import.
+- No copying of AgentRig assets, copy, or branding.
+
+## Definition of maintained documentation
+
+A public surface is documented only when it has a target route in `COVERAGE.md`, a canonical owner, a tested example or schema source where applicable, and a link from the page tree. A page is release-ready only when it has a title, description, audience/purpose, prerequisites, safe runnable examples, expected outcomes, failure/recovery guidance, and next steps.

package/docs/documentation/COVERAGE.md

@@ -0,0 +1,91 @@
+# Documentation Coverage Matrix
+
+This is the canonical inventory that maps shipped public surfaces to repository owners and published routes. Every `/docs` target in this file must resolve to a current MDX page; `pnpm docs:verify-maintenance` enforces that rule. Retired aliases belong only in `apps/docs/redirects.mjs`, never in this current-route matrix.
+
+## Published route inventory
+
+The site currently owns 59 MDX routes. Next.js also emits the landing page and framework support routes during the production build.
+
+| Section | Published routes |
+| --- | --- |
+| Documentation | `/docs` |
+| Getting started | `/docs/getting-started`, `/docs/getting-started/why-planr`, `/docs/getting-started/installation`, `/docs/getting-started/quickstart`, `/docs/getting-started/full-lifecycle`, `/docs/getting-started/choose-your-interface` |
+| For Agents | `/docs/agents`, `/docs/agents/quickstart`, `/docs/agents/prompt-recipes`, `/docs/agents/skills` |
+| Integrations | `/docs/integrations`, `/docs/integrations/codex`, `/docs/integrations/claude-code`, `/docs/integrations/cursor`, `/docs/integrations/generic-mcp`, `/docs/integrations/cli-only` |
+| Concepts | `/docs/concepts`, `/docs/concepts/local-first-model`, `/docs/concepts/plans-and-map`, `/docs/concepts/graph-and-readiness`, `/docs/concepts/picks-and-leases`, `/docs/concepts/evidence-and-context`, `/docs/concepts/reviews-and-approvals`, `/docs/concepts/recovery-packages-and-closure` |
+| Guides | `/docs/guides`, `/docs/guides/daily-worker-loop`, `/docs/guides/parallel-coordination`, `/docs/guides/handoff-and-resume`, `/docs/guides/review-and-fix-loops`, `/docs/guides/recover-interrupted-work`, `/docs/guides/packages-and-reuse`, `/docs/guides/recipes` |
+| Reference | `/docs/reference`, `/docs/reference/cli`, `/docs/reference/cli-generated`, `/docs/reference/mcp`, `/docs/reference/mcp-schemas-generated`, `/docs/reference/http-api`, `/docs/reference/configuration-and-storage`, `/docs/reference/data-and-status`, `/docs/reference/outputs-and-errors`, `/docs/reference/support-matrix`, `/docs/reference/maintenance` |
+| Contributing | `/docs/contributing`, `/docs/contributing/repository-setup`, `/docs/contributing/architecture`, `/docs/contributing/docs-authoring`, `/docs/contributing/testing`, `/docs/contributing/security-and-privacy` |
+| Operations | `/docs/operations`, `/docs/operations/release`, `/docs/operations/versioning-and-migrations`, `/docs/operations/docs-deployment`, `/docs/operations/health-and-diagnostics`, `/docs/operations/rollback`, `/docs/operations/documentation-governance` |
+| Help | `/docs/troubleshooting`, `/docs/faq` |
+
+## Product journeys and concepts
+
+| Surface | Canonical owner | Published route(s) |
+| --- | --- | --- |
+| Promise, users, non-goals | `docs/planr-spec/PRODUCT_SPEC.md` | `/docs/getting-started/why-planr` |
+| Install, first success, full lifecycle | manifests, installers, `src/cli.rs`, E2E tests | `/docs/getting-started/installation`, `/docs/getting-started/quickstart`, `/docs/getting-started/full-lifecycle` |
+| Agent setup, public routing, and prompt recipes | typed client/prompt contracts and installed Planr skills | `/docs/agents`, `/docs/agents/quickstart`, `/docs/agents/prompt-recipes`, `/docs/agents/skills` |
+| Local-first authority and boundaries | product/data specs, `src/storage/` | `/docs/concepts/local-first-model` |
+| Product plans, build plans, maps | `src/planpack.rs`, `src/app/commands.rs` | `/docs/concepts/plans-and-map` |
+| Items, links, statuses, readiness | `src/model.rs`, `src/app/repository/item.rs`, `src/app/lease.rs` | `/docs/concepts/graph-and-readiness` |
+| Picks, leases, concurrency, progress | `src/app/lease.rs`, `src/app/flow.rs` | `/docs/concepts/picks-and-leases`, `/docs/guides/parallel-coordination` |
+| Logs, contexts, artifacts, live evidence | `src/app/application.rs`, `src/app/inspection.rs` | `/docs/concepts/evidence-and-context` |
+| Reviews, approvals, fix chains | `src/app/review.rs`, `src/app/flow.rs`, `src/app/application.rs` | `/docs/concepts/reviews-and-approvals`, `/docs/guides/review-and-fix-loops` |
+| Recovery, conditions, packages, closure | `src/app/recovery.rs`, `src/app/packages.rs`, `src/app/flow.rs` | `/docs/concepts/recovery-packages-and-closure`, `/docs/guides/recover-interrupted-work`, `/docs/guides/packages-and-reuse` |
+| Worker loop, handoff, recipes | application flow and lease owners | `/docs/guides/daily-worker-loop`, `/docs/guides/handoff-and-resume`, `/docs/guides/recipes` |
+
+## CLI, MCP, HTTP, and data contracts
+
+The executable and schema sources decide exact inventory. Editorial pages explain usage; generated pages carry exhaustive command and schema detail.
+
+| Surface | Canonical owner | Published route(s) |
+| --- | --- | --- |
+| CLI invocation and automation rules | `src/cli.rs`, compiled help | `/docs/reference/cli` |
+| Every CLI group and subcommand | compiled recursive help, reference generator | `/docs/reference/cli-generated` |
+| MCP transport, resources, prompts, results | `src/app/mcp.rs`, `src/integrations.rs`, fixture | `/docs/reference/mcp` |
+| Every MCP tool input schema | live MCP discovery, schema generator | `/docs/reference/mcp-schemas-generated` |
+| Local HTTP/SSE and review routes | `src/app/http.rs` | `/docs/reference/http-api` |
+| Environment, installers, storage, repository files | CLI/install/storage owners | `/docs/reference/configuration-and-storage` |
+| DTOs, IDs, statuses, links, SQLite tables, packages | `src/model.rs`, `src/storage/schema.rs` | `/docs/reference/data-and-status` |
+| JSON output, error codes, exit/recovery behavior | application and surface adapters | `/docs/reference/outputs-and-errors` |
+| Platforms, clients, transports | manifests, release and integration owners | `/docs/reference/support-matrix` |
+| Reference generation and synchronization | generator/check scripts and CI | `/docs/reference/maintenance` |
+
+## Installation, clients, and safety
+
+| Surface | Canonical owner | Published route(s) |
+| --- | --- | --- |
+| Homebrew, install script, npm, source build | release manifests, `scripts/install.sh`, npm wrapper | `/docs/getting-started/installation` |
+| Interface selection and client differences | integration descriptors and installers | `/docs/getting-started/choose-your-interface`, `/docs/integrations` |
+| Agent-led setup and autonomous handoff | typed onboarding prompts and Planr goal/loop contracts | `/docs/agents/quickstart`, `/docs/agents/prompt-recipes` |
+| Codex | Codex manifest, generated role/install assets | `/docs/integrations/codex` |
+| Claude Code | Claude manifest, generated role/install assets | `/docs/integrations/claude-code` |
+| Cursor | Cursor manifest, role/skill/install assets | `/docs/integrations/cursor` |
+| Generic stdio MCP | MCP server and fixture | `/docs/integrations/generic-mcp` |
+| CLI-only and non-first-class hosts | prompt output and CLI | `/docs/integrations/cli-only` |
+| Privacy, secret handling, localhost boundary | safety spec, `src/app/http.rs`, scrub behavior | `/docs/contributing/security-and-privacy` |
+| User diagnosis and common questions | doctor/debug behavior and E2E tests | `/docs/troubleshooting`, `/docs/faq` |
+
+## Contributor and operations coverage
+
+| Surface | Canonical owner | Published route(s) |
+| --- | --- | --- |
+| Repository setup and worktree safety | manifests and `AGENTS.md` | `/docs/contributing/repository-setup` |
+| Code and docs architecture ownership | `docs/ARCHITECTURE.md`, compiled source, docs contract | `/docs/contributing/architecture` |
+| MDX, components, navigation, preview | `apps/docs` source and component contract | `/docs/contributing/docs-authoring` |
+| Rust, docs, semantic, browser, accessibility gates | tests, scripts, CI workflows | `/docs/contributing/testing` |
+| Product release and publication | `scripts/release.sh`, release workflow, `docs/RELEASE.md` | `/docs/operations/release` |
+| Version synchronization and SQLite upgrades | release script, manifests, `src/storage/schema.rs` | `/docs/operations/versioning-and-migrations` |
+| Alchemy/OpenNext docs build and Cloudflare deployment | `apps/docs/alchemy.run.ts`, Next/OpenNext config, environment contract | `/docs/operations/docs-deployment` |
+| Runtime diagnosis | docs scripts, source loader, deployment config | `/docs/operations/health-and-diagnostics` |
+| Docs and product rollback boundaries | immutable deployment contract, schema owner, release policy | `/docs/operations/rollback` |
+| Ownership, freshness, redirects, coverage | this matrix, docs contract, IA, redirect inventory, CI | `/docs/operations/documentation-governance` |
+
+## Audit completion checklist
+
+- [x] All 59 current MDX routes are explicitly inventoried.
+- [x] Every public product, CLI, MCP, HTTP, data, client, contributor, and operations surface has a current target and canonical source owner.
+- [x] Generated CLI and MCP inventories are separated from editorial guidance and mechanically checked.
+- [x] Retired aliases are isolated in `apps/docs/redirects.mjs` and resolve to a current route.
+- [x] `pnpm docs:verify-maintenance` fails for missing coverage routes, missing anchors, undeclared pages, invalid redirects, dependency drift, or release-tag drift.

package/docs/documentation/INFORMATION_ARCHITECTURE.md

@@ -0,0 +1,147 @@
+# Documentation Information Architecture
+
+This file records the implemented route and navigation contract. Routes are public interfaces: rename one only after adding a tested legacy alias to `apps/docs/redirects.mjs`.
+
+## Audiences and required journeys
+
+| Audience | Required path | Success signal |
+| --- | --- | --- |
+| evaluator | `/` -> `/docs` -> `/docs/getting-started/why-planr` | Understands the local-first map and evidence model. |
+| first-time user | `/docs/getting-started/installation` -> `/docs/getting-started/quickstart` | Installs, initializes, inspects, and diagnoses Planr. |
+| agent-led user | `/docs/agents/quickstart` -> `/docs/agents/prompt-recipes` | Completes safe setup, starts with `$planr`, and keeps autonomous execution plan-bound. |
+| lifecycle user | `/docs/getting-started/full-lifecycle` | Completes plan, map, work, evidence, and review. |
+| worker/operator | `/docs/guides/daily-worker-loop` -> `/docs/guides/parallel-coordination` | Picks without collisions and records durable evidence. |
+| reviewer | `/docs/concepts/reviews-and-approvals` -> `/docs/guides/review-and-fix-loops` | Closes a complete gate or creates a bounded fix chain. |
+| client integrator | `/docs/integrations` -> one client page | Connects through a supported CLI or stdio MCP path. |
+| API toolsmith | `/docs/reference/mcp` or `/docs/reference/http-api` | Uses the current schema and transport boundary. |
+| contributor | `/docs/contributing` -> setup/architecture/testing | Places and verifies a change without tribal knowledge. |
+| maintainer | `/docs/operations` | Can release, deploy, diagnose, roll back, and review freshness. |
+
+## Implemented route tree
+
+The 59 MDX files below are the current page tree and must agree with every `meta.json` file and `COVERAGE.md`.
+
+```text
+/docs
+├── getting-started
+│   ├── why-planr
+│   ├── installation
+│   ├── quickstart
+│   ├── full-lifecycle
+│   └── choose-your-interface
+├── agents (For Agents)
+│   ├── quickstart
+│   ├── prompt-recipes
+│   └── skills
+├── integrations
+│   ├── codex
+│   ├── claude-code
+│   ├── cursor
+│   ├── generic-mcp
+│   └── cli-only
+├── concepts
+│   ├── local-first-model
+│   ├── plans-and-map
+│   ├── graph-and-readiness
+│   ├── picks-and-leases
+│   ├── evidence-and-context
+│   ├── reviews-and-approvals
+│   └── recovery-packages-and-closure
+├── guides
+│   ├── daily-worker-loop
+│   ├── parallel-coordination
+│   ├── handoff-and-resume
+│   ├── review-and-fix-loops
+│   ├── recover-interrupted-work
+│   ├── packages-and-reuse
+│   └── recipes
+├── reference
+│   ├── cli
+│   ├── cli-generated
+│   ├── mcp
+│   ├── mcp-schemas-generated
+│   ├── http-api
+│   ├── configuration-and-storage
+│   ├── data-and-status
+│   ├── outputs-and-errors
+│   ├── support-matrix
+│   └── maintenance
+├── contributing
+│   ├── repository-setup
+│   ├── architecture
+│   ├── docs-authoring
+│   ├── testing
+│   └── security-and-privacy
+├── operations
+│   ├── release
+│   ├── versioning-and-migrations
+│   ├── docs-deployment
+│   ├── health-and-diagnostics
+│   ├── rollback
+│   └── documentation-governance
+├── troubleshooting
+└── faq
+```
+
+Each named section also has its own index route. The application additionally owns `/`, `/api/search`, the custom not-found page, metadata routes, and static assets; those are application routes rather than MDX navigation nodes.
+
+## Navigation and page contracts
+
+- Root and section `meta.json` files explicitly order every page.
+- Guides state prerequisites, outcome, failure recovery, and next action.
+- Reference pages name their generated or compiled source.
+- The For Agents section owns the shared setup and prompt journey; integration pages own client-specific technical detail and render the same typed recipe rather than copying it.
+- Getting Started remains the manual, CLI-first journey.
+- Search indexes the same Fumadocs source tree used by navigation.
+- English is canonical for this release.
+
+## Redirect policy
+
+`apps/docs/redirects.mjs` is the one executable inventory of retired public site aliases. `apps/docs/next.config.mjs` returns that inventory from Next.js `redirects()`, so production serves permanent redirects. The maintenance verifier enforces unique sources, current destinations, absence of alias/source collisions, and documentation of both sides here.
+
+The inventory covers these retired route families:
+
+| Retired alias | Current destination |
+| --- | --- |
+| `/docs/concepts/mental-model` | `/docs/concepts/local-first-model` |
+| `/docs/concepts/plans` | `/docs/concepts/plans-and-map` |
+| `/docs/concepts/map-items-and-links` | `/docs/concepts/graph-and-readiness` |
+| `/docs/concepts/statuses-and-readiness` | `/docs/concepts/graph-and-readiness` |
+| `/docs/concepts/logs-and-artifacts` | `/docs/concepts/evidence-and-context` |
+| `/docs/concepts/evidence-and-reviews` | `/docs/concepts/reviews-and-approvals` |
+| `/docs/concepts/approvals` | `/docs/concepts/reviews-and-approvals` |
+| `/docs/concepts/context-and-recall` | `/docs/concepts/evidence-and-context` |
+| `/docs/concepts/recovery-and-packages` | `/docs/concepts/recovery-packages-and-closure` |
+| `/docs/concepts/routing-and-policy` | `/docs/reference/configuration-and-storage` |
+| `/docs/guides/new-product` | `/docs/getting-started/full-lifecycle` |
+| `/docs/guides/existing-project-work` | `/docs/guides/recipes` |
+| `/docs/guides/autonomous-goals` | `/docs/getting-started/full-lifecycle` |
+| `/docs/guides/multi-agent-coordination` | `/docs/guides/parallel-coordination` |
+| `/docs/guides/review-and-fix-loop` | `/docs/guides/review-and-fix-loops` |
+| `/docs/guides/interruptions-and-recovery` | `/docs/guides/recover-interrupted-work` |
+| `/docs/guides/import-export-and-templates` | `/docs/guides/packages-and-reuse` |
+| `/docs/guides/local-review-workspace` | `/docs/guides/recipes` |
+| `/docs/guides/host-hooks` | `/docs/integrations` |
+| `/docs/guides/model-routing` | `/docs/reference/configuration-and-storage` |
+| `/docs/reference/cli/index` | `/docs/reference/cli` |
+| `/docs/reference/cli/project-and-plans` | `/docs/reference/cli-generated` |
+| `/docs/reference/cli/map-items-and-links` | `/docs/reference/cli-generated` |
+| `/docs/reference/cli/picks-logs-and-close` | `/docs/reference/cli-generated` |
+| `/docs/reference/cli/reviews-and-approvals` | `/docs/reference/cli-generated` |
+| `/docs/reference/cli/context-search-and-recovery` | `/docs/reference/cli-generated` |
+| `/docs/reference/cli/agents-routing-and-policy` | `/docs/reference/cli-generated` |
+| `/docs/reference/cli/install-prompt-and-server` | `/docs/reference/cli-generated` |
+| `/docs/reference/cli/artifacts-events-and-packages` | `/docs/reference/cli-generated` |
+| `/docs/reference/mcp/tools` | `/docs/reference/mcp-schemas-generated` |
+| `/docs/reference/mcp/resources` | `/docs/reference/mcp` |
+| `/docs/reference/mcp/prompts` | `/docs/reference/mcp` |
+| `/docs/reference/configuration-and-environment` | `/docs/reference/configuration-and-storage` |
+| `/docs/reference/storage-and-generated-files` | `/docs/reference/configuration-and-storage` |
+| `/docs/reference/data-model-and-statuses` | `/docs/reference/data-and-status` |
+| `/docs/reference/json-and-errors` | `/docs/reference/outputs-and-errors` |
+| `/docs/reference/routing-bundles` | `/docs/reference/configuration-and-storage` |
+| `/docs/reference/platform-support` | `/docs/reference/support-matrix` |
+
+Repository files such as `docs/INSTALL.md` are not former website URLs. They remain GitHub-readable source material and must link to the current site rather than pretending a Next.js redirect can intercept a repository path.
+
+To retire another route: add exactly one alias, choose the closest current outcome page, update this table, repair internal links, run the maintenance and browser gates, and retain the redirect while supported inbound links may exist. Never redirect an unknown path to a generic landing page merely to hide a 404.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Local-first planning and execution coordination for coding agents.",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,30 @@
     "build:native": "cargo build --release",
     "test": "cargo test",
     "pack:check": "npm pack --dry-run",
-    "routing": "cargo run --manifest-path planr-routing/Cargo.toml --"
+    "routing": "cargo run --manifest-path planr-routing/Cargo.toml --",
+    "docs:dev": "pnpm --filter @planr/docs dev",
+    "docs:alchemy:dev": "pnpm --filter @planr/docs alchemy:dev",
+    "docs:build": "pnpm --filter @planr/docs build",
+    "docs:start": "pnpm --filter @planr/docs start",
+    "docs:deploy": "pnpm --filter @planr/docs run deploy",
+    "docs:destroy": "pnpm --filter @planr/docs run destroy",
+    "docs:content": "pnpm --filter @planr/docs content",
+    "docs:typecheck": "pnpm --filter @planr/docs typecheck",
+    "docs:lint": "pnpm --filter @planr/docs lint",
+    "docs:verify-shell": "pnpm --filter @planr/docs verify:shell",
+    "docs:verify-onboarding": "cargo build --bin planr && pnpm --filter @planr/docs verify:onboarding && pnpm --filter @planr/docs verify:agent-recipes",
+    "docs:verify-agent-recipes": "cargo build --bin planr && pnpm --filter @planr/docs verify:agent-recipes",
+    "docs:verify-agent-markdown": "pnpm docs:build && pnpm --filter @planr/docs verify:agent-markdown",
+    "docs:verify-agent-journey": "pnpm --filter @planr/docs verify:agent-journey",
+    "docs:verify-agent-landing": "pnpm --filter @planr/docs verify:agent-landing",
+    "docs:verify-concepts": "cargo build --bin planr && pnpm --filter @planr/docs verify:concepts",
+    "docs:verify-maintenance": "pnpm --filter @planr/docs verify:maintenance",
+    "docs:verify-deployment": "pnpm --filter @planr/docs verify:deployment",
+    "docs:verify-release": "pnpm --filter @planr/docs verify:release",
+    "docs:verify-release-live": "pnpm --filter @planr/docs verify:release-live",
+    "docs:verify-clean-install": "pnpm --filter @planr/docs verify:clean-install",
+    "docs:reference:generate": "cargo build --bin planr && pnpm --filter @planr/docs reference:generate",
+    "docs:verify-reference": "cargo build --bin planr && pnpm --filter @planr/docs reference:check && pnpm --filter @planr/docs verify:reference"
   },
   "engines": {
     "node": ">=18"

package/plugins/planr/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "planr",
   "description": "Skill-driven planning and execution loop for coding agents: one planr entry point, an autonomous planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "author": {
     "name": "instructa"
   },

package/plugins/planr/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Skill-driven planning and execution loop for coding agents: one $planr entry point, an autonomous $planr-loop, and evidence-backed task graph skills powered by the planr CLI.",
   "author": {
     "name": "instructa",
@@ -19,7 +19,7 @@
     "category": "Productivity",
     "defaultPrompt": [
       "Use $planr to plan a production-ready app from my idea.",
-      "Use $planr-loop to ship one feature with verification until done."
+      "Use $planr to prepare my next feature and tell me the verified next step."
     ]
   }
 }