planr 1.5.0 → 1.5.2

package/README.md

@@ -4,6 +4,10 @@
 
 Planr is a local-first planning and execution coordination tool for coding agents. It combines reviewable Markdown plans with a dependency-aware work map so Codex, Claude Code, Cursor, generic MCP clients, and human operators can drive the same work safely — from idea to verified completion.
 
+[**View the Demo →**](https://x.com/kevinkern/status/2066957434564808884?s=20)
+
+[**Documentation →**](https://planr.so/docs)
+
 ```text
 idea -> product plan -> build plan -> map -> pick -> log -> review/evidence -> close
 ```
@@ -40,7 +44,7 @@ Or with the release installer:
 curl -fsSL https://raw.githubusercontent.com/instructa/planr/main/scripts/install.sh | sh
 ```
 
-Then initialize a project (also provisions the worker/reviewer subagent roles for your client):
+Then initialize a project. When selected, Claude Code and Cursor also receive standalone project worker/reviewer roles; Codex workflow skills come from its plugin:
 
 ```bash
 planr project init "My Product" --client all
@@ -50,7 +54,7 @@ Manual downloads, from-source builds, and client wiring details: [Install Guide]
 
 ## Install The Plugin (Skills)
 
-The plugin under `plugins/planr` carries the ten Planr workflow skills. Optional model-routing roles come from repository-local routing bundles. The `planr` CLI (above) is required separately.
+The plugin under `plugins/planr` carries the ten Planr workflow skills. Optional model-routing declarations live in repository-local files such as `.planr/agents.toml` and `.planr/policy.toml`; external tools may manage those files, but Planr does not install or invoke a routing engine. The `planr` CLI (above) is required separately.
 
 <a id="install-plugin-codex"></a>
 <details>
@@ -86,7 +90,7 @@ One command installs everything the plugin would carry:
 
 ```bash
 planr install cursor            # writes .cursor/mcp.json, .cursor/agents/, and .cursor/skills/
-planr install cursor --no-mcp   # skills and subagents only, no MCP config
+planr install cursor --no-mcp   # project skills, subagents, and hooks; no MCP config
 ```
 
 The dry-run also prints a one-click `cursor://` deeplink for user-level MCP install. Marketplace listing is pending review. Multitasking with Cursor subagents: [Cursor guide](docs/CURSOR.md).
@@ -108,7 +112,7 @@ planr prompt cli
 
 ## Tell Your Agent
 
-Two skills drive everything. `$planr` routes any request to the right stage skill from live map state; `$planr-loop` drives one feature through work, live verification, and independent review until the map is clean.
+Remember one public entry point: `$planr`. It routes ordinary planning and status work from live Planr state. For long autonomous runs, use the explicit two-step workflow: `$planr-goal` prepares durable state, then `$planr-loop` executes the resulting plan.
 
 Start a new product from an idea:
 
@@ -119,10 +123,13 @@ Create a production-ready Habit Tracker web app plan. Create the product plan,
 split an MVP build plan, check it, then build the Planr map. Do not implement yet.
 ```
 
-Ship one feature autonomously until verified:
+For a long autonomous run, prepare outside the driver first. The preparation result prints a real plan id; Codex or Claude Code then starts only the plan-bound loop driver:
 
 ```text
-Use $planr-loop.
+Use $planr-goal 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
@@ -133,7 +140,7 @@ Mid-project work (a new feature, refactor, or fix on an existing project) works
 
 ## What's new
 
-- **1.5.0 — Optional routing policies:** Planr Core stays provider-neutral while the independently buildable `planr-routing` package owns model policies and host bindings for Codex, Claude Code, Cursor, and mixed-host setups. Start with [Routing Bundles](docs/ROUTING_BUNDLES.md), the [`planr-routing` guide](planr-routing/docs/MODEL_ROUTING_POLICY.md), and the [1.5.0 release notes](https://github.com/instructa/planr/releases/tag/v1.5.0).
+- **1.5.2 — Standalone core, optional Switchloom:** Planr consumes provider-neutral repository declarations and route evidence only; it works without any routing files, and requested-only routing metadata is not execution proof. Optional model-routing lifecycle is external, with [Switchloom v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1) verified as the repository-local handoff outside Planr. Start with [Model Routing](docs/MODEL_ROUTING.md), [Switchloom](https://switchloom.ai), the [Switchloom repository](https://github.com/instructa/switchloom), its tagged [setup quickstart](https://github.com/instructa/switchloom/blob/v0.2.1/README.md#setup-from-the-website) and [lifecycle docs](https://github.com/instructa/switchloom/blob/v0.2.1/docs/preset-composition.md#repository-lifecycle-commands), and the [Changelog](CHANGELOG.md).
 - **1.4.0 — Verified presets:** Added policy-driven composition, evaluation, signed registry evidence, and the public catalog. See the [1.4.0 release notes](https://github.com/instructa/planr/releases/tag/v1.4.0).
 - **1.3.0 — Native host hooks:** Added automatic session-state injection and loop recovery for supported hosts. See the [Hooks guide](docs/HOOKS.md) and [1.3.0 release notes](https://github.com/instructa/planr/releases/tag/v1.3.0).
 

package/docs/ARCHITECTURE.md

@@ -6,7 +6,7 @@ Planr V1 is a single Rust binary with explicit module ownership. The crate stays
 
 - `src/`: the Rust CLI (module ownership below).
 - `tests/e2e.rs`: real CLI, MCP, HTTP, import, review-gate, run-log, and concurrent-pick tests.
-- `plugins/planr/`: the installable plugin payload — all ten skills, independent Claude/Cursor worker and reviewer role assets, and the per-host plugin manifests. Native Codex role TOMLs are generated from the selected binding instead of shipped here.
+- `plugins/planr/`: the installable plugin payload — all ten skills, independent Claude/Cursor worker and reviewer role assets, and the per-host plugin manifests. Planr does not ship model-pinned Codex roles.
 - `.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json`: marketplace manifests pointing Codex and Claude Code at `plugins/planr`.
 - `docs/`: user and contributor guides; `docs/planr-spec/` is the production specification package for Planr V1.
 - `examples/real-world-flow.md`: executable real-world operator flow.
@@ -43,12 +43,10 @@ Planr V1 is a single Rust binary with explicit module ownership. The crate stays
 - `src/usage_policy.rs`: provider-neutral Usage Policy v1 core. Owns strict `.planr/policy.toml` parsing, policy and task-contract vocabulary, materiality classification, budget/concurrency validation, and the pure five-way transition resolver; it contains no provider ids, host dispatch, or execution-permission behavior.
 - `src/execution_policy.rs`: execution admission core. Owns per-role filesystem, network, tool/MCP, structured command, environment, hook, secret, and approval grants; permission-diff previews; bounded task-contract admission; fail-closed command grammar; and isolated write-scope concurrency. It never selects models or mutates graph state. `src/app/policy.rs` binds that pure decision to the current SQLite lease owner and pick token, and only treats an admission from that exact lease generation as authoritative.
 - `src/route_audit.rs`: provider-neutral run-observation contract. Owns strict requested/resolved/effective route stages, model/effort/fork enforcement confidence, transition provenance, policy/binding versions, and per-dimension metering confidence. It rejects requested-only values in the effective stage rather than inferring host execution.
-- `src/routing_bundle.rs`: provider-neutral RoutingBundle v1 contract and repository transaction boundary. Owns validation, hashes, signatures, allowlisted paths, conflict and symlink rejection, atomic apply, rollback, and application receipts.
-- `planr-routing/`: independently buildable workspace package that owns model policies, host bindings, generated host artifacts, probes, evaluation, signing, registry data, and catalog publication.
 - `src/app/agents.rs`: routing application boundary. Owns the `agents` and `item route` command handlers, the shared `*_value` JSON shapes reused by MCP, per-item route facts assembly, and registry-aware role content selection for installs.
 - `src/app/agents_init.rs`: registry bootstrap boundary. Owns `planr agents init` — the static cost-tiering scaffold and, per the agent-pool plan, the flag-spec builder and interactive wizard.
 - `src/integrations.rs`: agent-client integration descriptor boundary. Owns Codex, Claude Code, Cursor, MCP install metadata, MCP tool schemas, MCP resources, and MCP text response wrapping.
-- `src/rolefiles.rs`: static host workflow roles and Cursor skill payloads. It does not select or pin models; generated routing artifacts belong to `planr-routing` bundles.
+- `src/rolefiles.rs`: static host workflow roles and Cursor skill payloads. It does not select or pin models; externally generated routing artifacts stay outside Planr ownership.
 - `src/util.rs`: small CLI-boundary utilities. Owns ids, timestamps, path helpers, output formatting, and safe file writes.
 
 ## Boundary Rules

package/docs/CLAUDE_CODE.md

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

package/docs/CLI_REFERENCE.md

@@ -67,9 +67,6 @@ planr agents init [--force]
 planr agents init --profile|--skill|--route|--default-route|--interactive
 planr agents list [--json]
 planr agents check
-planr routing bundle inspect <bundle.json>
-planr routing bundle preview <bundle.json>
-planr routing bundle apply <bundle.json>
 planr doctor [--client codex|claude|cursor|all]
 planr install codex|claude|cursor [--dry-run] [--no-mcp] [--force] [--no-hooks]
 planr prompt cli|mcp|http [--client codex|claude|cursor|all]
@@ -141,8 +138,6 @@ With `--json`, responses follow one convention so agents never guess where data
 
 `policy show` and `policy check` inspect the provider-neutral Usage Policy v1 file (`.planr/policy.toml`). A missing policy is an explicit successful state that preserves existing advisory routing; a malformed or unsafe policy fails `check` with parser/field diagnostics and leaves enforcement unavailable. Usage Policy v1 fixes delegation depth at one and keeps retry, availability fallback, quality escalation, quota downgrade, and safety stop as distinct transition contracts. Its separate `execution` section declares bounded per-role filesystem, network, tool/MCP, structured command, environment, hook, secret-reference, and approval grants. `policy admit <request.json>` requires the picked item's current `item_id` and `pick_token`, authorizes the current worker as lease owner, evaluates a bounded task contract before delegation, previews any permission addition, records the decision and lease generation, rejects unclassified commands and destructive or out-of-scope work, permits overlapping readers, and admits concurrent writers only for disjoint scopes isolated in distinct worktrees. Released or recovered leases never inherit historical admitted scopes. MCP `planr_policy_show`, `planr_policy_check`, and `planr_policy_admit`, plus HTTP `POST /v1/policy/admit`, call the same admission service and return the same decision shape.
 
-`routing bundle inspect|preview|apply` is Planr Core's only policy-package boundary. It accepts RoutingBundle v1, validates payload hashes, restricts targets to allowlisted repository-local paths, rejects traversal, symlinks, parent/child collisions, conflicts, and unsupported versions, and applies the validated set atomically. Signed bundles require both `--trusted-signer` and an external `--trusted-public-key-file`; a key embedded beside the content is never trusted. It never edits user configuration. Named policies, model ids, host bindings, evaluation, signing, and catalog operations are provided by the optional `planr-routing` package. See [Routing Bundles](ROUTING_BUNDLES.md).
-
 `agents init` writes a provider-neutral `.planr/agents.toml` scaffold or compiles explicit profile and route flags. `agents list` and `agents check` inspect it, while pick packets carry the resolved opaque profile, host, model, effort, tier, skill, route chain, and matched selector. Full guide: [Model Routing](MODEL_ROUTING.md).
 
 `log add` and `done` accept `--profile <id>` — the registry profile the run actually executed on (`PLANR_PROFILE` env is the fallback, so rendered role files can export it). They also accept `--route-audit <observation.json>` for the strict three-stage observation contract. A route audit records each stage's model, effort, and context-fork value with enforcement state (`verified`, `requested_only`, `estimated`, or `unavailable`), an evidence-source enum, typed transition plus reason, policy/binding ids and versions, and wall-time/tool/token/credit values with independent confidence. It is stored in run metadata, projected into its durable log and trace, and emits local route-stage/transition events. The profile remains backward compatible: when it differs from the item's declared route, Planr emits advisory `route_mismatch_observed`. Runs without commands/tests record neither a run nor a route observation. MCP `planr_log_add` and HTTP item log accept the same optional `route_observation` object.

package/docs/CODEX.md

@@ -22,15 +22,13 @@ $planr-goal <your goal>
 
 The stop condition lives in Planr (`--tag goal-contract`), so a dead session resumes with the same starter line from zero chat context.
 
-Optionally compile and apply a repository-local Codex routing bundle before starting the driver:
+Optionally prepare repository-local routing declarations before starting the driver. Planr reads `.planr/agents.toml` and `.planr/policy.toml`; external tools such as [Switchloom v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1) own any generated roles, application, or uninstall lifecycle:
 
 ```bash
-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
+planr agents check
 ```
 
-The bundle generates repository-local roles and a routing skill. Follow that generated skill exactly, restart after role changes, and confirm child metadata reports the expected model, effort, role path, and context-fork behavior. Full workflow: [Long-Running Goals](GOALS.md).
+Follow any externally generated repository role instructions outside Planr, restart after role changes when your host requires it, and confirm child metadata reports the expected model, effort, role path, and context-fork behavior. Full workflow: [Long-Running Goals](GOALS.md).
 
 ## MCP
 

package/docs/CURSOR.md

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

package/docs/EXAMPLE_WEBAPP.md

@@ -53,12 +53,11 @@ planr agents check
 planr agents list
 ```
 
-Alternatively, an external policy package can compile a strict RoutingBundle v1. Preview and apply it through the generic Core boundary:
+Alternatively, an external routing tool such as [Switchloom v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1) can manage repository-local declarations and host roles outside Planr. After that external lifecycle step, Planr still sees only provider-neutral declarations:
 
 ```bash
-planr routing bundle inspect routing-bundle.json
-planr routing bundle preview routing-bundle.json
-planr routing bundle apply routing-bundle.json
+planr agents check
+planr agents list --json
 ```
 
 ## 2. Tag items by use case
@@ -101,4 +100,4 @@ planr trace item <item-id>
 
 A mismatch is recorded as advisory evidence instead of silently rewritten. Missing effective-host evidence stays unavailable and is never inferred from the registry.
 
-One-off exceptions use `planr item route <id> --set <profile>`; `--clear` restores policy resolution. See [Model Routing](MODEL_ROUTING.md) and [Routing Bundles](ROUTING_BUNDLES.md).
+One-off exceptions use `planr item route <id> --set <profile>`; `--clear` restores policy resolution. See [Model Routing](MODEL_ROUTING.md) and [External Routing Declarations](ROUTING_BUNDLES.md).

package/docs/GOALS.md

@@ -87,15 +87,13 @@ Iteration 1 reads the map and the stored contract: items already settled stay se
 
 ### Codex with `/goal`
 
-Install the plugin, initialize the repository, and optionally apply a repository routing bundle:
+Install the plugin and initialize the repository. Optional routing declarations are repository-local and may be edited directly or managed by an external tool such as [Switchloom v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1) before the run:
 
 ```bash
 codex plugin marketplace add instructa/planr
 codex plugin add planr@planr
 planr project init "My Product"
-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
+planr agents check
 ```
 
 Then:
@@ -105,7 +103,7 @@ $planr-goal <your goal>          # prep: plan, map, contract, starter command
 /goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract).
 ```
 
-When a routing bundle is applied, the `/goal` PM follows its generated repository skill and roles. The bundle owner decides exact models, effort, role names, and fork policy; Planr only carries the resulting opaque route in pick packets. Codex Automations use the same starter line.
+When repository routing declarations exist, the `/goal` PM treats them as advisory dispatch input. The external routing owner decides exact models, effort, role names, fallback policy, and lifecycle; Planr only carries the resulting opaque route in pick packets and records observed evidence when workers provide it. Codex Automations use the same starter line.
 
 ### Claude Code
 
@@ -147,7 +145,7 @@ Any MCP-capable agent uses the same flow over `planr mcp`. Every session starts
 
 A goal run has distinct roles with different intelligence needs. Planr represents those decisions as opaque profiles and routes; it does not choose providers, models, effort levels, fallback chains, or host-native role names.
 
-An optional routing-policy package can map planning, exploration, implementation, mechanical work, and independent review onto different cost or quality tiers. If a routing bundle generated repository roles, follow its generated instructions and verify effective child metadata because declarations alone are not proof. The official package and its host-specific caveats live under [`planr-routing`](../planr-routing/docs/MODEL_ROUTING_POLICY.md); the Core contract is documented in [Model Routing](MODEL_ROUTING.md).
+An optional external routing tool can map planning, exploration, implementation, mechanical work, and independent review onto different cost or quality tiers. If [Switchloom v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1) or another repository-local process writes routing declarations or host roles, follow that tool's generated instructions outside Planr and verify effective child metadata because declarations alone are not proof. The Core contract is documented in [Model Routing](MODEL_ROUTING.md).
 
 ## Coming From Other Goal Tools
 

package/docs/INSTALL.md

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

package/docs/MCP_CONTRACT.md

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

package/docs/MODEL_ROUTING.md

@@ -28,12 +28,6 @@ Resolution order is per-item override, work type, plan, then default route. Unkn
 
 Workers may report observed routing with logs and route-audit evidence. Requested-only values never become effective proof; missing effective evidence remains explicitly unavailable.
 
-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:
+Host-specific model policies, generated repository roles, and uninstall/application lifecycle are external to Planr. [Switchloom](https://switchloom.ai) [v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1) can manage repository-local routing artifacts from its [repository](https://github.com/instructa/switchloom), [setup quickstart](https://github.com/instructa/switchloom/blob/v0.2.1/README.md#setup-from-the-website), and [repository lifecycle docs](https://github.com/instructa/switchloom/blob/v0.2.1/docs/preset-composition.md#repository-lifecycle-commands), but Planr does not install, invoke, compile, apply, or uninstall Switchloom output. After an external tool or operator changes `.planr/agents.toml` or `.planr/policy.toml`, run `planr agents check` and capture observed route evidence through `planr log add` or `planr done`.
 
-```bash
-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
-```
-
-Bundle application is restricted to the repository. Planr never edits user configuration such as `~/.codex/config.toml`. See [Routing Bundles](ROUTING_BUNDLES.md).
+The hard boundary is provider-neutral: Planr consumes declarations and evidence; hosts and external routing tools decide whether any requested model, effort, role, or fallback actually ran. See [External Routing Declarations](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

@@ -1,32 +1,15 @@
-# Routing bundles
+# External routing declarations
 
-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:
+Planr Core is provider-neutral. It parses `.planr/agents.toml`, resolves routes into pick packets, records declared-versus-observed evidence, and checks `.planr/policy.toml`. It does not own a bundle format, catalog, compiler, signer, installer, or uninstaller.
 
-```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:
+The current boundary is repository-local declaration plus evidence:
 
 ```bash
-planr routing bundle inspect signed-bundle.json \
-  --trusted-signer planr-maintainers \
-  --trusted-public-key-file /absolute/path/to/maintainer.pub
+planr agents init
+planr agents check
+planr agents list --json
 ```
 
-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
-```
+External tools, including Switchloom v0.2.1, may create, update, apply, or uninstall repository-local routing artifacts. Those lifecycle operations happen outside Planr. Planr only consumes the resulting provider-neutral declarations and the route observations workers attach to logs.
 
-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.
+Because declarations are advisory, requested model values never become proof by themselves. Strong evidence keeps requested, host-resolved, and effective execution separate in route observations, with `unavailable` used when the host cannot prove what ran.

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 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`).
+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 from repository-local routing declarations managed outside Planr, 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-goal 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-goal 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,69 +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 agents init                              # generates canonical native Codex roles in an existing project
+planr project init "My Product" --client all   # writes standalone Claude and Cursor roles; Codex has no project roles
+planr agents init                              # writes the provider-neutral .planr/agents.toml registry; it does not generate Codex roles
 planr install claude                           # provisions Claude's independent roles
 planr install cursor                           # provisions Cursor's independent roles and skills
 ```
 
-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.
+Optional project-scoped model-routing files are repository-local declarations. They may be edited directly or managed by an external tool such as [Switchloom v0.2.1](https://github.com/instructa/switchloom/releases/tag/v0.2.1); Core workflow skills remain host-neutral, and Planr does not install, invoke, apply, or uninstall external routing artifacts.
 
 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
 
@@ -237,7 +220,7 @@ planr project init "Example Product" --client cursor
 planr install cursor
 ```
 
-`planr install cursor` writes `.cursor/mcp.json`, copies the ten skills to `.cursor/skills/`, provisions `.cursor/agents/planr-worker.md` and `planr-reviewer.md`, and prints a one-click deeplink for user-level MCP install. Prefer skills and agents without MCP? `planr install cursor --no-mcp` writes only the subagents and skills — the skills are CLI-first, so the whole workflow runs through the `planr` binary. Invoke skills with `/planr` or `/planr-loop` in Agent chat, and dispatch subagents with `/planr-worker` and `/planr-reviewer`. Use `planr serve --port 7526` and `planr prompt http --client cursor` if a Cursor workflow should inspect the local HTTP/review workspace. Subagent multitasking and worktree guidance: [Cursor](CURSOR.md).
+`planr install cursor` writes `.cursor/mcp.json`, copies the ten skills to `.cursor/skills/`, provisions `.cursor/agents/planr-worker.md` and `planr-reviewer.md`, reconciles hooks, and prints a one-click deeplink for user-level MCP install. `planr install cursor --no-mcp` retains the agents, skills, and hooks while omitting MCP; add `--no-hooks` to omit hooks. Invoke the public router with `/planr` in Agent chat, and dispatch subagents with `/planr-worker` and `/planr-reviewer`. Use `planr serve --port 7526` and `planr prompt http --client cursor` if a Cursor workflow should inspect the local HTTP/review workspace. Subagent multitasking and worktree guidance: [Cursor](CURSOR.md).
 
 ## MCP-Only Clients