planr 1.4.0 → 1.5.1

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/docs/fixtures/mcp-contract.json

@@ -20,12 +20,6 @@
     "planr_item_amend",
     "planr_item_replan",
     "planr_agents_list",
-    "planr_presets_list",
-    "planr_preset_evaluate",
-    "planr_preset_apply",
-    "planr_preset_registry_verify",
-    "planr_preset_registry_import",
-    "planr_preset_registry_list",
     "planr_policy_show",
     "planr_policy_check",
     "planr_policy_admit",
@@ -109,11 +103,9 @@
     "planr recover sweep",
     "planr agents list",
     "planr agents check",
-    "planr agents preset list",
-    "planr agents preset apply",
-    "planr agents preset registry verify",
-    "planr agents preset registry import",
-    "planr agents preset registry list",
+    "planr routing bundle inspect",
+    "planr routing bundle preview",
+    "planr routing bundle apply",
     "planr item route",
     "planr trace item",
     "planr serve --port"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Local-first planning and execution coordination for coding agents.",
   "license": "MIT",
   "repository": {
@@ -15,27 +15,38 @@
     "npm/bin/planr.js",
     "npm/native",
     "plugins",
-    "presets",
-    "evaluations",
-    "website",
     "README.md",
     "LICENSE.md",
     "docs"
   ],
   "scripts": {
-    "alchemy:check-runtime": "node scripts/check-alchemy-runtime.mjs",
     "build:native": "cargo build --release",
     "test": "cargo test",
     "pack:check": "npm pack --dry-run",
-    "deploy:test": "node scripts/cloudflare-test.mjs deploy",
-    "destroy:test": "node scripts/cloudflare-test.mjs destroy",
-    "site:build": "node scripts/build-site.mjs",
-    "site:check": "pnpm site:test && pnpm site:build",
-    "site:test": "node --test website/*.test.mjs",
-    "site:serve": "node website/serve.mjs"
-  },
-  "devDependencies": {
-    "alchemy": "0.93.7"
+    "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.4.0",
+  "version": "1.5.1",
   "author": {
     "name": "instructa"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "1.4.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."
     ]
   }
 }

package/plugins/planr/skills/planr-loop/SKILL.md

@@ -67,7 +67,7 @@ A worker subagent may take several items sequentially instead of being respawned
 
 Host wiring:
 
-- Codex: project agents in `.codex/agents/*.toml` preload the skill via `[[skills.config]]` (TOML templates in `agents/` next to this skill). Spawn explicitly: "spawn the planr_worker agent for item X". Keep `[agents] max_depth = 1`.
+- When a repository routing bundle supplies host roles, follow its generated routing skill exactly. Otherwise treat the profile in the pick packet as advisory and use the host's current dispatch contract. Never infer effective model or effort from a declaration alone.
 - Claude Code: subagents preload via the `skills:` frontmatter field. The Planr plugin registers `planr-worker` and `planr-reviewer` automatically from its `agents/` directory; standalone installs copy them to `.claude/agents/`. The reviewer subagent is read-only except for `planr review` commands.
 - Cursor: project subagents in `.cursor/agents/*.md` (Markdown templates in `agents/` next to this skill; `planr install cursor` provisions them). Dispatch explicitly: `/planr-worker implement item X`, `/planr-reviewer review item X`. Parallel dispatches are safe — the map's pick lease keeps one owner per item.
 - Single-agent hosts: run worker and checker as separate sequential dispatches with a fresh read of map state in between; never carry the worker's self-assessment into the review step. The mode is recorded automatically: `review close` derives `review_mode` (`single_agent`/`independent`) from worker identity.