planr 1.4.0 → 1.5.1

package/docs/MCP_CONTRACT.md

@@ -42,10 +42,7 @@ Required groups:
 - artifact add, list, and show
 - event list and debug bundle preview
 - trace item, log add, and log read (including three-stage route observations)
-- built-in policy/binding catalog listing plus safe-pack/custom composition status
-- declarative registry verification with canonical evaluation/safe-binding gates, preview-first immutable import, and manifest-anchored integrity/signature/freshness-checked offline cache listing
-- policy preset preview/apply by path or built-in id with repository-only target validation and deterministic provenance lock
-- deterministic offline preset simulation plus explicit opt-in live-host execution with Planr-controlled challenge workspaces, strict task artifacts read and hashed by Planr, candidate/task outcome oracles, failed-live-attempt `unverified`/incomplete lifecycle semantics, production policy-capability checks, estimated arbitrary-process claims, optional Ed25519-verified run/suite/time/task/challenge-bound telemetry that alone can promote effective route and usage evidence to trusted/recommendation-eligible, observed process latency, transition/correction/violation counts, result hashes, and deterministic lifecycle thresholds
+- provider-neutral RoutingBundle v1 inspection, repository-safe preview/apply, and durable application evidence
 - review annotate, ingest, artifact, evidence, and close
 - item close, context create, and search
 
@@ -65,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` plus `.codex/agents/` roles
-- 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/MODEL_ROUTING.md

@@ -1,196 +1,39 @@
-# Model Routing
+# Model routing
 
-Declare which agent and model each kind of work should run on — once, in one file — and Planr hands the recommendation to whoever picks the work.
-
-The pattern this makes declarative: strongest model plans and judges, a cheap fast steerable model implements, token-hungry side work (browser verification, codebase analysis) goes to budget profiles. Without a registry that knowledge lives in CLAUDE.md prose, Codex agent TOMLs, and Cursor frontmatter — three dialects that drift. With a registry it travels inside every pick packet.
-
-Routing is **advisory by design**: Planr never calls model providers and never blocks a pick because a profile is unavailable. Your host (Codex, Claude Code, Cursor, any MCP client) stays the dispatch authority.
-
-Want the whole flow on a concrete project first? [Worked Example: Routing a Small Web App](EXAMPLE_WEBAPP.md) walks a frontend/backend todo app from pool declaration to the audit trail, with real outputs.
-
-## Quick Start
-
-One command writes a working starter registry — the cost-tiering defaults with a premium driver, a standard implementer, and a budget helper, commented so the tiers explain themselves:
-
-```bash
-planr agents init          # writes .planr/agents.toml; never overwrites without --force
-```
-
-Or declare `.planr/agents.toml` by hand:
+Planr Core treats routing as optional, advisory repository data. `.planr/agents.toml` declares opaque profiles and routes; Planr resolves them into pick packets but never calls a provider or claims that a requested model actually ran.
 
 ```toml
-[profiles.fable-driver]
-client = "cursor"
-model = "fable-5"
+[profiles.worker]
+client = "host-a"
+model = "model-id"
+agent_type = "repository-role"
 effort = "high"
-cost_tier = "premium"
-capabilities = ["orchestration", "review", "planning"]
-notes = "Planner/architect and judge. Verdicts stay on this tier."
-
-[profiles.gpt55-coder]
-client = "codex"
-model = "gpt-5.5"
-effort = "xhigh"
-cost_tier = "standard"
-capabilities = ["code", "steerable"]
-notes = "Primary implementer: strong, fast, cheap on subscription."
+skill = "planr-work"
 
 [[routes]]
 match = { work_type = "code" }
-profile = "gpt55-coder"
-fallbacks = ["fable-driver"]
-
-[[routes]]
-match = { work_type = "review" }
-profile = "fable-driver"
-
-[route_default]
-profile = "gpt55-coder"
-fallbacks = ["fable-driver"]
-```
-
-Validate and inspect:
-
-```bash
-planr agents check   # non-zero exit only on parse failure; warnings pass
-planr agents list    # resolved profiles, routes, and warnings
+profile = "worker"
 ```
 
-From then on, every pick carries the recommendation:
+Create a neutral scaffold or an explicit registry:
 
 ```bash
-planr pick --json
-```
-
-```json
-"routing": {
-  "profile": "gpt55-coder",
-  "client": "codex",
-  "model": "gpt-5.5",
-  "effort": "xhigh",
-  "cost_tier": "standard",
-  "fallbacks": ["fable-driver"],
-  "matched_selector": "work_type=code"
-}
+planr agents init
+planr agents init --profile worker=host-a/model-id@high#standard --route code=worker
+planr agents check
+planr agents list --json
 ```
 
-A driver session dispatches the right worker from the packet alone — and when the primary hits a rate limit, the fallback order is already in hand. No mid-run config edits.
-
-## The Registry File
-
-`.planr/agents.toml` has three parts:
-
-- `[profiles.<id>]` — a named agent setting. `client` (which host dispatches it: `codex`, `claude-code`, `cursor`, `generic-mcp`) and `model` are required; `effort`, `cost_tier` (`premium` | `standard` | `budget`), `capabilities`, and `notes` are optional. Model ids and aliases pass through verbatim — Planr does not validate them against provider catalogs, so new models need no Planr release.
-- `[[routes]]` — `match` selects work (`work_type = "code"` or `plan = "pln-1234abcd"`), `profile` names the primary, `fallbacks` the ordered alternatives.
-- `[route_default]` — catches everything no route matched.
-
-Resolution precedence per item: **per-item override > `work_type` route > `plan` route > default**. Within a level, the first declared route wins. If a chain's primary profile id is unknown, the first known fallback is promoted; a chain with no known profiles falls through to the next precedence level, so a typo never swallows lower routes. `matched_selector` in the output tells you which rule fired (`override`, `work_type=<v>`, `plan=<v>`, or `default`).
+Resolution order is per-item override, work type, plan, then default route. Unknown profiles fail open to the next applicable route. Host names, model ids, role selectors, effort values, and fallback behavior are opaque to Core.
 
-## Per-Item Overrides
+Workers may report observed routing with logs and route-audit evidence. Requested-only values never become effective proof; missing effective evidence remains explicitly unavailable.
 
-When one item needs a different setting than its policy route — a gnarly refactor that deserves the premium tier, a bulk doc pass that can run on budget — pin it:
+Host-specific model policies and generated repository roles are optional. The `planr-routing` workspace package compiles them into RoutingBundle v1, and Core safely previews and applies that bundle:
 
 ```bash
-planr item route <item-id>                    # resolved route + source: override or policy
-planr item route <item-id> --set fable-driver # pin; validates the profile id, emits route_overridden
-planr item route <item-id> --clear            # unpin; policy applies again, emits route_override_cleared
+planr-routing compile balanced --host codex-openai --output routing-bundle.json
+planr routing bundle preview routing-bundle.json
+planr routing bundle apply routing-bundle.json
 ```
 
-The pin beats every policy route and shows up in the pick packet with `"matched_selector": "override"`. Overrides are repair-friendly: `--set` rejects a profile id the registry does not declare (when the registry is missing or malformed it warns and stores anyway, so offline edits stay possible), and a pin whose profile is later deleted from the registry is never an error — policy routing takes over and `item route` prints a repair hint. Both mutations are recorded as graph events, so `planr event list --item <id>` shows who re-routed what, when.
-
-Tier the roles, not just the models: workers run safely on cheaper tiers because the pick packet bounds their scope, while review verdicts should stay on the strongest tier — `agents check` warns when review work routes to a `budget` profile. Background: [Cost Tiering](GOALS.md#cost-tiering).
-
-## Host-Native Rendering
-
-Routes only matter if the host actually dispatches the declared model, so `planr install codex|claude|cursor` closes the gap: when a registry is present, the provisioned subagent role files are rendered with pins taken from it instead of the shipped static defaults. The `work_type=code` route pins the worker role, the `work_type=review` route pins the reviewer role, and each render uses the host's exact vocabulary — Codex TOML gets `model` and `model_reasoning_effort` (with `developer_instructions` always present, since Codex silently ignores a role file without it), Claude frontmatter gets `model:` and `effort:`, Cursor frontmatter gets `model:` only.
-
-Two safety rules keep this predictable:
-
-- **Client matching**: a role file only pins profiles whose `client` matches the install target, scanning the route's fallback chain for the first match. A review route pointing at a Cursor profile never writes a Cursor model id into a Codex TOML — that role keeps its static default instead.
-- **Provision-once**: existing files are never overwritten. After editing the registry, re-render explicitly with `planr install <client> --force`. Rendered files start with a `# generated from .planr/agents.toml` header so you (and future audit tooling) can tell them from hand-maintained ones.
-
-Without a registry, installs write the static role files byte-identically to previous releases.
-
-## Prompt Routing
-
-`planr prompt routing [--client codex|claude|cursor|all]` prints a paste-ready block for the driver session: the prioritization table (every route, profile, and fallback in precedence order), per-host dispatch guidance including the traps that silently defeat pins (Codex requires `fork_turns: "none"` and a session restart after re-rendering; the `CLAUDE_CODE_SUBAGENT_MODEL` env var preempts Claude frontmatter; Cursor plan mode, admin policy, and Max Mode override silently), and process-dispatch snippets (`codex exec`, `pi`, `opencode run`) for hosts without role files, pre-filled from the `work_type=code` route. `--json` carries the same content structured.
-
-## Run Audit
-
-Every host has a silent override path — the `CLAUDE_CODE_SUBAGENT_MODEL` env var, Cursor plan/admin/Max-Mode policy, Codex full-history forks, org allowlists — so a pin alone is not proof. The audit loop closes this at two levels: workers report the profile they actually ran on via `planr log add`/`planr done --profile <id>` (or `PLANR_PROFILE`) for backward-compatible mismatch checks, and can attach a strict `--route-audit <observation.json>` that keeps requested, host-resolved, and effective model/effort/fork values separate. Every dimension carries enforcement confidence and a constrained evidence source; missing host evidence stays unavailable instead of inheriting the request.
-
-- `planr trace item <id>` (MCP: `planr_trace_item`) shows the declared route next to every run's actual client/profile and three-stage observation with a `mismatch` marker.
-- Runs also record the host they observably executed under (`observed_client`, detected from environment variables the hosts set themselves — no flags); a run whose host differs from the declared route's client emits an advisory `client_mismatch_observed` event, which catches exactly the deviation profile self-report cannot: a different host standing in for the declared client, even when the model matched.
-- `planr doctor` reports the registry state (absent, degraded with parse context, loaded with counts and warnings) and flags rendered role files that drifted from the current registry (`planr install <client> --force` re-renders).
-- `planr export`/`import` carry the registry with the package, preview-first; an existing registry at the destination is never silently overwritten.
-
-Everything here is advisory (ADR-001): mismatches never fail logging, reviews, or closes. No profile reported, no run recorded, or no registry means no comparison and no event.
-
-One legitimate mismatch source to know: a driver adding a live-verification log to a routed item runs on the driver profile by design, which emits a `route_mismatch_observed` event. The payload carries `log_kind`, so audit consumers can discount `verification` entries and alarm only on `completion` mismatches.
-
-For single-host pools (e.g. all-Cursor), declare the host's *exact* model slugs (`claude-opus-4-8-thinking-high`, not `opus`): dispatch APIs resolve slugs, not aliases, and a driver forced to map `fable-5` onto the nearest slug at dispatch time is a silent translation the audit cannot see.
-
-## Failure Behavior
-
-- **No registry file**: nothing changes. Pick packets simply have no `routing` key.
-- **Malformed registry**: `planr agents check` fails with the parser's line context; everything else (`pick`, `map`, `install`) keeps working with routing omitted — installs fall back to the static role files.
-- **Warnings** (unknown profile references, empty or duplicate selectors, budget-tier review routes, secret-like values) never block anything; `agents check` lists them and still exits zero.
-- Never put credentials in the registry — it holds configuration strings only, and secret-like values are flagged.
-
-## Use-Case Pools
-
-Work types are free-form, and that makes them the use-case dimension: beyond the built-in vocabulary (`code`, `fix`, `review`, `docs`, ...), any string you pass to `--work-type` routes. Combined with per-profile skill pairing, the registry becomes a small agent pool — each use case names who runs it, on what model, with which skill:
-
-```toml
-[profiles.designer]
-client = "claude-code"
-model = "opus"
-effort = "high"
-cost_tier = "premium"
-skill = "frontend-design"     # dispatch this profile *with* this skill
-
-[profiles.backender]
-client = "codex"
-model = "gpt-5.5"
-effort = "xhigh"
-cost_tier = "standard"
-skill = "planr-work"
-
-[[routes]]
-match = { work_type = "frontend" }
-profile = "designer"
-fallbacks = ["driver"]
-
-[[routes]]
-match = { work_type = "design" }
-profile = "designer"
-
-[[routes]]
-match = { work_type = "backend" }
-profile = "backender"
-fallbacks = ["driver"]
-```
-
-Create items with the use-case work type (`planr item create ... --work-type frontend`) — or retag existing ones with `planr item update <id> --work-type frontend`, which is how planning agents tag `map build` output against the declared routes (the planning skills read `agents list` and do this without user involvement) — and the pick packet carries the full pairing — `"profile": "designer"`, `"model": "opus"`, `"skill": "frontend-design"` — so the driver dispatches profile and skill together (`Use $frontend-design on item <id>` on the profile's client/model). Workers pull their slice of the pool with `planr pick --work-type frontend`. `skill` is passthrough vocabulary like model ids: Planr never validates it against installed skills, and profiles without one omit the key entirely. A profile that needs different skills for different use cases is simply two profiles.
-
-Declare the `client` you will actually dispatch on. A loop running inside one host dispatches that host's subagents — an in-Cursor driver that dispatches Cursor subagents with per-dispatch models is running `client = "cursor"` profiles in practice, even when the model matches. A `client = "codex"` profile is only honest when the driver really spawns a Codex process (`codex exec ...`). This matters for the audit: workers report the *profile id*, so a profile whose declared client differs from the real dispatch host passes the mismatch check on the model alone — the client deviation stays invisible.
-
-When do you actually need more than one client? Hosts with a full model catalog (Cursor) can serve an entire pool natively — an all-`cursor` registry with different models per profile is the normal case there. Cross-client profiles exist for two real situations: vendor-locked hosts (Claude Code dispatches only Anthropic models, Codex CLI only OpenAI models — a Claude-Code driver that wants a GPT implementer must process-dispatch via `codex exec`), and subscription economics (the same model can bill differently per host, so routing backend work through a flat-rate CLI subscription instead of the driver host's quota is a legitimate cost decision).
-
-## Host Matrix
-
-Where each host reads its model configuration from, and what silently defeats a pin there (state of July 2026):
-
-| Host | Native mechanism | Rendered by `planr install`? | Silent overrides / traps |
-| --- | --- | --- | --- |
-| Cursor | `.cursor/agents/*.md` frontmatter `model: <id>` (default `inherit`) | yes (`cursor`) | Team-admin model policy, plan availability, and Max-Mode-only models override without error; legacy request-based plans force Composer for subagents; subagent transcripts record no model field, so the actual model cannot be verified from artifacts after the fact — the dispatch parameters in the driver session are the only record |
-| Claude Code | `planr-worker.md`/`planr-reviewer.md` frontmatter `model:` + `effort:` | yes (`claude`) | `CLAUDE_CODE_SUBAGENT_MODEL` clamps frontmatter and per-invocation models with no signal ([#57718](https://github.com/anthropics/claude-code/issues/57718)); since v2.1.196 `inherit` behaves as unset; org `availableModels` allowlists fall back silently |
-| Codex CLI | `.codex/agents/*.toml` with `model` + `model_reasoning_effort` | yes (`codex`) | `fork_turns = "all"` intentionally drops the child's `agent_type`/`model` — use `fork_turns = "none"` or a partial fork; the role registry loads at session start ([#26408](https://github.com/openai/codex/issues/26408)), so re-renders need a restart |
-| opencode | `opencode.json` `agent.<name>.model = "provider/model-id"` or `.opencode/agents/*.md` frontmatter | no — use the `planr prompt routing` process snippet | Subagent inherits the primary model when unset; malformed `provider/model-id` strings (quoting, trailing newline) raise `ProviderModelNotFoundError` ([#5623](https://github.com/sst/opencode/issues/5623)) |
-| Pi | none by design — process-level dispatch (`pi --provider --model --thinking`) or the `pi-subagents` extension (`.pi/agents/*.md`) | no — use the `planr prompt routing` process snippet | Extension model-scope enforcement against `enabledModels` is opt-in; without it, pins are best-effort |
-
-For the hosts without rendered role files, `planr prompt routing` prints ready process-dispatch snippets pre-filled from the registry. Whatever the host does, the [run audit](#run-audit) catches silent overrides after the fact.
-
-## Command Summary
-
-The registry surface end to end: `planr agents init [--force]` scaffolds, `planr agents list|check` inspect and validate, `planr pick --json` carries the `routing` block, `planr item route [--set|--clear]` pins per item, the MCP tools (`planr_agents_list`, `planr_item_route`, `planr_item_route_set`, `planr_item_route_clear`) return identical JSON shapes, `planr install <client> [--force]` renders host role files from the registry, `planr prompt routing` prints the driver dispatch block, `planr log add`/`done --profile` (or `PLANR_PROFILE`) feed the run audit, `planr trace item` and `planr doctor` surface mismatches and drift, and `planr export`/`import` carry the registry preview-first.
+Bundle application is restricted to the repository. Planr never edits user configuration such as `~/.codex/config.toml`. See [Routing Bundles](ROUTING_BUNDLES.md).

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/ROUTING_BUNDLES.md

@@ -0,0 +1,32 @@
+# Routing bundles
+
+Planr Core is provider-neutral. It parses `.planr/agents.toml`, resolves routes into pick packets, records declared-versus-observed evidence, and safely previews or applies a strict RoutingBundle v1:
+
+```bash
+planr routing bundle inspect routing-bundle.json
+planr routing bundle preview routing-bundle.json
+planr routing bundle apply routing-bundle.json
+```
+
+Core accepts only allowlisted repository-local targets, verifies payload hashes, rejects absolute paths, traversal, symlinks, parent/child target collisions, conflicts, unsupported versions, and invalid payloads, and applies the validated set atomically. It never writes user configuration or files outside the repository.
+
+A signed bundle is accepted only with an independent trust anchor supplied to every inspect, preview, or apply call:
+
+```bash
+planr routing bundle inspect signed-bundle.json \
+  --trusted-signer planr-maintainers \
+  --trusted-public-key-file /absolute/path/to/maintainer.pub
+```
+
+The bundle contains the signer id and signature, not a self-trusted public key. Both trust flags are required together; unsigned bundles require neither. An unsigned bundle also cannot label its evidence `verified` or `recommended`.
+
+The `planr-routing` workspace package owns all volatile opinions: named policies, exact model ids, host bindings, generated role and skill files, capability probes, evaluation scenarios, signing, registry data, and the website catalog. A normal flow is:
+
+```bash
+planr-routing policy list
+planr-routing compile balanced --host codex-openai --output routing-bundle.json
+planr routing bundle preview routing-bundle.json
+planr routing bundle apply routing-bundle.json
+```
+
+The package emits the same provider-neutral bundle contract for Codex, Claude Code, Cursor, and mixed-host configurations. Offline evaluation remains experimental; a recommendation requires complete authenticated live-host evidence. Missing authentication or missing effective model, effort, role, or context-fork evidence cannot pass.

package/docs/SKILLS.md

@@ -2,7 +2,7 @@
 
 Planr ships agent-facing skill templates under `plugins/planr/skills/`.
 
-The repository ships an installable plugin under `plugins/planr` for Codex, Claude Code, and Cursor, so the skills can be installed as one package instead of copied by hand. Marketplace manifests at the repo root (`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`) point at that subdirectory — Codex silently ignores marketplaces whose plugin source is the repo root itself. The plugin only carries skills and agent roles; the `planr` CLI must be installed separately (`brew install instructa/tap/planr`).
+The repository ships an installable plugin under `plugins/planr` for Codex and Claude Code, while Cursor receives the same skills through `planr install cursor`. Marketplace manifests at the repo root (`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`) point at that subdirectory — Codex silently ignores marketplaces whose plugin source is the repo root itself. The shared package carries skills and Claude's independent workflow roles; optional model-specific host roles come only from a repository-local routing bundle, never from Planr Core or static fallbacks. The `planr` CLI must be installed separately (`brew install instructa/tap/planr`).
 
 ## Install As Plugin (preferred)
 
@@ -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,67 +170,46 @@ 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 install codex                            # provisions roles for an existing project (same for claude and cursor)
+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
 ```
 
-Codex needs these project-scoped files because its plugin system carries skills only; the Claude Code and Cursor plugins register the same roles automatically, so the provisioned `.claude/agents/` and `.cursor/agents/` copies only matter for standalone (non-plugin) installs. Existing role files are never overwritten.
+Optional project-scoped model-routing files are generated by `planr-routing` bundles. Core workflow skills remain host-neutral, and bundle application never overwrites conflicts or writes user configuration.
 
 Dispatches stay one line: `Use $planr-work on item <id>` and `Use $planr-review on item <id>`. The map and logs are the loop memory, so any iteration can resume from zero context.
 
 ## 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
 
@@ -235,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