planr 1.5.0 → 1.5.2

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/`, and examples. 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 declaration | Provider-neutral repository data in `.planr/agents.toml` or `.planr/policy.toml`. | 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 an external routing-catalog static implementation: neither supplies the requested polished docs authoring/search system.
+
+### DOC-ADR-003: Deploy direct static assets with Alchemy on Cloudflare
+
+Use an Alchemy v2 Effect stack as the committed deployment owner. Next.js exports every human and agent-readable route, Fumadocs search runs from a build-time Orama database in the browser, and `Cloudflare.Website.StaticSite` serves normal pages and files directly. A tiny edge worker is limited to exact legacy aliases and machine-readable Markdown, search, and LLM paths; it redirects, fixes content types, or delegates immediately to the asset binding. Bind `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 complete static artifact and Wrangler configuration without deploying it. This avoids making public documentation availability depend on a paid application Worker CPU allowance.
+
+### 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 | Resolved on 2026-07-18: `docs/ARCHITECTURE.md` now describes Planr as one Rust binary plus wrappers/docs, with provider-neutral routing declarations owned in Core and external routing lifecycle outside Planr. | Keep architecture ownership aligned with current runtime modules and do not reintroduce routing-package ownership wording. |
+| 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 | Resolved on 2026-07-18: Planr no longer documents a routing package CLI, catalog, compiler, bundle, or application lifecycle as current product surface. | Document only provider-neutral declarations, policy checks, pick-packet routing, and route evidence; external tools such as Switchloom remain outside Planr execution. |
+
+## 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 static docs build and Cloudflare deployment | `apps/docs/alchemy.run.ts`, Next static export, 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/worker.mjs` consumes that inventory and returns permanent redirects while preserving query strings; Alchemy derives the exact worker-first paths from the same inventory. 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/docs/fixtures/mcp-contract.json

@@ -103,9 +103,6 @@
     "planr recover sweep",
     "planr agents list",
     "planr agents check",
-    "planr routing bundle inspect",
-    "planr routing bundle preview",
-    "planr routing bundle apply",
     "planr item route",
     "planr trace item",
     "planr serve --port"

package/docs/release-candidates/planr-v1.5.2.md

@@ -0,0 +1,164 @@
+# Planr v1.5.2 Release Candidate Evidence
+
+Candidate produced on 2026-07-20 in an isolated local workspace:
+
+- Workspace: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2`
+- Source clone: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/release-candidate-src`
+- Local bare remote: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/local-origin.git`
+- Config-proof rerun source clone: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/release-candidate-src`
+- Config-proof rerun local bare remote: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/local-origin.git`
+- Config-proof hash snapshots: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence`
+- Public side effects: none. The candidate clone's `origin` points to the local bare remote, and the public `origin` check from this repository returned no `v1.5.2` tag.
+
+## Identity
+
+- Upstream release-scope base commit: `f7763c6197ddf8cdd93227b9aa320f2b168a0523`
+- Clean pre-release source commit: `9390af541ca51755e585bf3c1a652717997daeca`
+- Clean pre-release source tree: `2569374e6321a88b812cc706257bbda086101437`
+- Release commit: `678038db4536723867fc96b0cd0af703fda43ef1`
+- Release tree: `80324b8afef14d7d7bd97950eb8352cd9c667e6a`
+- Annotated tag object: `12c78b7a870552361b11c5de768a6c5da7c8f115`
+- Tag target: `678038db4536723867fc96b0cd0af703fda43ef1`
+- Config-proof rerun release commit: `0d6bab060793fd52a5e144b9862c1fbc77d10ec3`
+- Config-proof rerun release tree: `80324b8afef14d7d7bd97950eb8352cd9c667e6a`
+- Config-proof rerun annotated tag object: `78c6c99afbca24803d58abb7d9a507cafde40741`
+- Config-proof rerun tag target: `0d6bab060793fd52a5e144b9862c1fbc77d10ec3`
+
+## Version Checks
+
+Both runtime entry points reported `planr 1.5.2`:
+
+- `target/release/planr --version`
+- `node npm/bin/planr.js --version`
+
+All release manifests carried `1.5.2`:
+
+- `Cargo.toml`
+- `package.json`
+- `plugins/planr/.codex-plugin/plugin.json`
+- `plugins/planr/.claude-plugin/plugin.json`
+- `.cursor-plugin/plugin.json`
+
+## Artifact Digests
+
+- Native binary `target/release/planr`: `e91917be04e84f97c5d515e673f829c33b21f5128dae87ce836e3721ece50473`
+- npm tarball `planr-1.5.2.tgz`: `33df443e6ec20d6d44fcf05469efe56eb75b192c826467c33d47d44672297a34`
+- Native archive `dist/planr-darwin-arm64.tar.gz`: `6fdaf803073d99bdb02522100e50094fb277409d52fc3a0c33e9d8bd6707d8ac`
+- Archive checksum file `dist/SHA256SUMS`: `6347103b757e5045aef9a83a311ae2bcc43de5b6e9ada8a9efa2d52b84e3359b`
+- Payload checksum file `dist/planr-1.5.2/SHA256SUMS`: `d8ac952c247706bb328e1539583b87e55f9e2b211b89c134aab08357d0cc665c`
+- Config-proof rerun native binary `target/release/planr`: `00c1b3b46f66563dfe4c909e2ecb75dc448e72bfe75b6cb7d56d86c6539b5d6c`
+- Config-proof rerun npm tarball `planr-1.5.2.tgz`: `33df443e6ec20d6d44fcf05469efe56eb75b192c826467c33d47d44672297a34`
+- Config-proof rerun native archive `dist/planr-darwin-arm64.tar.gz`: `dbba6abece2cc37d1b7e038094b8b7483ce79e5c770f8ed64048c84446d17681`
+- Config-proof rerun archive checksum file `dist/SHA256SUMS`: `1d77872f58c8ef8877cbed11b16ab0ea30524a6b2a9565f5190dfd059d69416c`
+- Config-proof rerun payload checksum file `dist/planr-1.5.2/SHA256SUMS`: `ce2adbe238c9fe27838c11f3a89195d9eb8b262411c86d3a8b02304ee14eaec6`
+
+`dist/SHA256SUMS` records:
+
+```text
+6fdaf803073d99bdb02522100e50094fb277409d52fc3a0c33e9d8bd6707d8ac  planr-darwin-arm64.tar.gz
+```
+
+`dist/planr-1.5.2/SHA256SUMS` records:
+
+```text
+e91917be04e84f97c5d515e673f829c33b21f5128dae87ce836e3721ece50473  planr
+a1e27e1cfb3d9d540dfe05f5d1212ee98be97b1f48e203d48209e31243383ba3  README.md
+61a9b281d04d62cdea4bef57d5e0b702c191b3219456409ac5ed651569228a30  LICENSE.md
+```
+
+## Gates Run
+
+- `scripts/release.sh 1.5.2 'standalone Planr core with optional Switchloom handoff'`
+  - `cargo test`: 71 unit tests, 67 e2e tests, and 3 routing ownership tests passed.
+  - `npm pack --dry-run`: reported `planr@1.5.2`, 65 files, shasum `a3903ce5658be6f6140321232885f86f6515ae70`.
+  - `scripts/security-local.sh`: betterleaks found no leaks; Trivy reported 0 vulnerabilities for `Cargo.lock` and `pnpm-lock.yaml`.
+  - Pushed `main` and `v1.5.2` only to `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/local-origin.git`.
+- `scripts/build-release.sh`: built `dist/planr-darwin-arm64.tar.gz`.
+- `npm pack`: created `planr-1.5.2.tgz` locally; no npm publish was run.
+- Config-proof rerun:
+  - `scripts/release.sh 1.5.2 'standalone Planr core with optional Switchloom handoff'`: 71 unit tests, 67 e2e tests, and 3 routing ownership tests passed; betterleaks found no leaks; Trivy reported 0 vulnerabilities; pushed only to `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/local-origin.git`.
+  - `scripts/build-release.sh`: built `dist/planr-darwin-arm64.tar.gz`.
+  - `npm pack`: created `planr-1.5.2.tgz` locally; no npm publish was run.
+  - `target/release/planr --version` and `node npm/bin/planr.js --version`: both reported `planr 1.5.2`.
+- `git tag -l v1.5.2`: returned no local tag in `/Users/kregenrek/projects/planr`.
+- `git ls-remote --heads --tags origin 'v1.5.2'`: returned no public remote ref.
+- Candidate clone artifact inventory: no Switchloom files, no legacy routing-owner directories, and no routing manifests were present.
+
+## User Config Hash Proof
+
+No release command targeted user/global host config files. The config-proof rerun captured hashes immediately before and after each release-owned run, stored without file contents:
+
+- `scripts/release.sh`
+  - Before: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-before-release-sh.txt`
+  - After: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-after-release-sh.txt`
+  - Equality proof: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-release-sh-equality.txt` records `config hashes unchanged across scripts/release.sh`.
+- `scripts/build-release.sh`
+  - Before: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-before-build-release.txt`
+  - After: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-after-build-release.txt`
+  - Equality proof: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-build-release-equality.txt` records `config hashes unchanged across scripts/build-release.sh`.
+- `npm pack`
+  - Before: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-before-npm-pack.txt`
+  - After: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-after-npm-pack.txt`
+  - Equality proof: `/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/config-proof/evidence/config-npm-pack-equality.txt` records `config hashes unchanged across npm pack`.
+
+Every before/after snapshot contains the same hashes:
+
+- `/Users/kregenrek/.codex/config.toml`: `82224997e7d4d5147f892a8aa12f7f5f04e77c38267da6ba1274a9267b23f040`
+- `/Users/kregenrek/.claude/settings.json`: `99a0eb17993d0dd0c952df03bec38d284fd119a9b0ed928f3201b1792224049f`
+- `/Users/kregenrek/.claude.json`: `a5f901ce3b38943ed2591333b4cb6dbab0cab101f8d02ea348fc476021f55afb`
+- `/Users/kregenrek/.cursor/mcp.json`: `cf7217adfcb48b532dfdbced62ca68eab4c60996ef38d510a8efb3d286ce5baf`
+
+## Switchloom v0.2.1 Optional Dogfood Evidence
+
+Fresh non-replay dogfood ran on 2026-07-20 with the release-candidate Planr v1.5.2 binary and exact public Switchloom v0.2.1 bytes. The durable local audit receipt is:
+
+- Receipt: `/private/tmp/planr-switchloom-cross-product-QEvWps/oracle-receipt.json`
+- Receipt SHA-256: `c01f4b980977a15028f7a82cc6fc237aa50fb4b35310871ba3ad245ec1c699ee`
+- Mode/result: `live`, `ok=true`
+- Fresh root: `/private/tmp/planr-switchloom-cross-product-QEvWps`
+
+Replayable command:
+
+```bash
+PLANR_WORKER_ID=switchloom_optional_dogfood PLANR_BIN=/Users/kregenrek/projects/planr-dogfood/release-v1.5.2/release-candidate-src/target/release/planr SWITCHLOOM_TARBALL=/private/tmp/switchloom-public-0.2.1.MN008L/switchloom-0.2.1.tgz PLANR_ORACLE_TEMP_PARENT=/private/tmp node scripts/verify-switchloom-cross-product.mjs
+```
+
+Public Switchloom package identity:
+
+- Package: `switchloom@0.2.1`
+- Tarball: `/private/tmp/switchloom-public-0.2.1.MN008L/switchloom-0.2.1.tgz`
+- npm SHA-1 shasum: `e813283f54d0d64b5fd4835e17687aaaf3b0a6cb`
+- SHA-512 integrity: `sha512-vUKHxYXHt7Sx7MkYQz5MRZ0Ll544iHoadHGCgvJPUYkpUzQWtzjt1o3xhyeQwExCA6tuLQ5vZnLPz+fO5uMiXg==`
+- Local SHA-256: `028176063ce20b4981aa4e13199b25169b2f8296f648eeeec9291e6955e7549a`
+
+Host routing evidence from the receipt:
+
+- Codex CLI: `codex-cli 0.144.5`
+- Maker role/model/effort: `model_routing_terra_high`, `gpt-5.6-terra`, `high`
+- Reviewer role/model/effort: `model_routing_sol_high`, `gpt-5.6-sol`, `high`
+- `fork_turns_all_used`: `false`
+- Public Codex JSONL: `/private/tmp/planr-switchloom-cross-product-QEvWps/codex-live.jsonl`
+- Parent rollout: `/Users/kregenrek/.codex/sessions/2026/07/20/rollout-2026-07-20T20-05-19-019f80b4-2e89-7470-a432-6937ddcbc7ac.jsonl`
+- Maker rollout: `/Users/kregenrek/.codex/sessions/2026/07/20/rollout-2026-07-20T20-05-50-019f80b4-a7d3-73d1-bf34-9762ad7d9474.jsonl`
+- Reviewer rollout: `/Users/kregenrek/.codex/sessions/2026/07/20/rollout-2026-07-20T20-06-37-019f80b5-5d7f-7441-97f3-c743d97e0a8c.jsonl`
+
+Fresh Planr audit and uninstall evidence:
+
+- Fresh oracle plan: `pln-773f1d88`
+- Fresh oracle item: `i-build-first-slice-5c85`
+- Audit result: holds with clauses `items_settled`, `reviews_complete`, `approvals_clear`, and `verification_logged`.
+- Post-uninstall result: Switchloom uninstall removed only managed files and unrouted Planr still worked; the script reran the Planr audit after uninstall and required `holds=true`.
+- Requested-only routing metadata was rejected as effective proof: `/private/tmp/planr-switchloom-cross-product-QEvWps/requested-only-route-audit.json`.
+
+Protected configuration and source inventory proof:
+
+- `/Users/kregenrek/.codex/config.toml`: `82224997e7d4d5147f892a8aa12f7f5f04e77c38267da6ba1274a9267b23f040`
+- `/Users/kregenrek/.claude/settings.json`: `99a0eb17993d0dd0c952df03bec38d284fd119a9b0ed928f3201b1792224049f`
+- `/Users/kregenrek/.claude.json`: `a5f901ce3b38943ed2591333b4cb6dbab0cab101f8d02ea348fc476021f55afb`
+- `/Users/kregenrek/.cursor/mcp.json`: `cf7217adfcb48b532dfdbced62ca68eab4c60996ef38d510a8efb3d286ce5baf`
+- Switchloom source root: `/Users/kregenrek/projects/model-routing`
+- Switchloom source HEAD: `191f6aac91ff0f73fcae68ab269eb2d89c9e76e9`
+- Switchloom source status SHA-256: `2ca939e3e14ba8971210e93152120323641d21b0ac465b02a85335860b01758c`
+- Switchloom tracked files SHA-256: `0292bca86e80e9c63d5848984cab229b17df6e1162f1b0d8ec577474a9ac3591`
+
+This section records paths, digests, roles, and verification outcomes only. It does not copy rollout contents, prompts, responses, credentials, or user configuration contents into the repository.