planr 1.6.0 → 1.7.1

package/docs/SKILLS.md

@@ -1,261 +0,0 @@
-# Planr Skills
-
-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 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)
-
-Codex:
-
-```bash
-codex plugin marketplace add instructa/planr
-# then install "planr" from the plugin directory picker, or:
-codex plugin add planr@planr
-```
-
-Claude Code:
-
-```text
-/plugin marketplace add instructa/planr
-/plugin install planr@planr
-```
-
-Skills are namespaced in Claude Code: `/planr:planr`, `/planr:planr-loop`. The plugin also registers the `planr-worker` and `planr-reviewer` subagents from the plugin's `agents/` directory.
-
-Cursor: pending marketplace review; `planr install cursor` provides the identical component set today — it writes the skills to `.cursor/skills/`, the subagents to `.cursor/agents/`, and the MCP config in one command (see below and [Cursor](CURSOR.md)).
-
-opencode: no plugin yet; use `planr mcp` as an MCP server (below). A JS plugin wrapping the CLI as custom tools is a possible follow-up.
-
-## Included Skills
-
-Entry points (what users invoke):
-
-- `planr`: master router. One entry point for any request; reads live map state and dispatches to the right skill. Users do not need to remember skill names.
-- `planr-goal`: goal prep compiler for long-running runs. Turns a broad goal into a checked plan, a linked map, and a durable goal contract (`planr context --tag goal-contract`), then prints the starter command for the host's loop driver (Codex/Claude Code `/goal`, or manual re-dispatch). Prep only — see [Long-Running Goals](GOALS.md).
-- `planr-loop`: autonomous closing loop. Drives one feature to verified completion — work, live verification, independent review, fix items — until the map is clean or the iteration budget runs out. Ships subagent templates under `plugins/planr/skills/planr-loop/agents/`.
-
-Capability skills (dispatched by the loop's live-verification step):
-
-- `planr-verify-web`: proves a web feature runs in a browser. Discovers the host's existing browser capability (browser skill, browser MCP, `npx playwright`, HTTP checks as last resort), records the choice as a `capability` context, and logs replayable evidence. Ships no browser tooling itself.
-
-Stage skills (what the router and loop dispatch to; also directly invocable):
-
-- `planr-task-graph`: active task graph coordination with plans, parent gates, map items, picks, runtime state, approvals, logs, reviews, handoffs, stories, and recovery.
-- `planr-plan`: product and build planning.
-- `planr-work`: one picked item to evidence-backed completion.
-- `planr-review`: findings-first review gates.
-- `planr-status`: honest read-only status.
-- `planr-summary`: evidence-backed summaries.
-
-## Cheat Sheet
-
-Default usage needs one public entry point:
-
-```text
-$planr        any request -> routed to the right stage skill from live map state
-```
-
-`$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
-$planr-plan        idea -> product plan -> build plan
-$planr-task-graph  build plan -> map -> dependencies -> critical lane
-$planr-work        pick one ready item -> implement -> log evidence -> request review
-$planr-review      audit evidence -> complete or create fix work
-$planr-work        pick generated fix work when review finds issues
-$planr-status      report honest state, blockers, and next ready work
-$planr-summary     summarize completed scope with evidence
-```
-
-Example first prompt for a Habit Tracker:
-
-```text
-Use $planr.
-
-Create a production-ready Habit Tracker web app plan. Include habits, daily check-ins,
-streaks, weekly overview, local-first persistence, tests, privacy, and release readiness.
-Create the product plan, split an MVP build plan, check it, then build the Planr map.
-Do not implement yet. End with the build plan id, critical lane, and first ready items.
-```
-
-Example autonomous feature loop (two separate prompts):
-
-```text
-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
-overview rendering real check-in data in the browser. Iteration budget: 10.
-```
-
-Example single implementation step (human-in-the-loop):
-
-```text
-Use $planr-work.
-
-Pick exactly one ready Habit Tracker item. Implement only that item, keep Planr runtime
-state current, log changed files and real verification commands, then request review.
-Do not close the item until review is complete.
-```
-
-## Two Journeys: New Project vs. Existing Project
-
-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
-
-Initialize once per repository, then hand the idea to the router:
-
-```bash
-planr project init "Habit Tracker" --client all
-```
-
-```text
-Use $planr.
-
-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. 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
-
-Never re-run `project init`; the project and map already exist. Every new scope — a feature like an auth system, a refactor, a non-trivial fix — gets its own feature-scoped plan on the same map:
-
-```text
-Use $planr.
-
-Add an auth system (email+password, sessions, protected routes) to this app.
-Create a feature plan for it, record what existing code it builds on, split a
-narrow build slice, check it, and extend the map with linked items. Do not implement yet.
-```
-
-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: a plan-bound `$planr-loop` for autonomous work, or `$planr-work` / `$planr-review` for human-in-the-loop.
-
-Or autonomous in two prompts:
-
-```text
-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
-complete, and a live verification log shows login and a protected route working
-in the browser. Iteration budget: 10.
-```
-
-Rules that hold in both journeys:
-
-- No map items without a checked build plan — even a small fix gets a minimal slice (`plan new` -> `plan split` with a tiny scope). This keeps closure evidence and reviews attached to a contract.
-- Plans accumulate: `planr plan list` shows the project's history of scopes; the map stays the single live source of item status.
-- Status, review, and summary requests (`$planr-status`, `$planr-review`, `$planr-summary`) work the same at any point in either journey.
-
-## Loop Roles
-
-`planr-loop` keeps maker and checker separate. Hosts with subagents get dedicated roles that are prompted with skills, not hand-written prompts.
-
-The CLI provisions the role files automatically — no manual copying:
-
-```bash
-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 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
-
-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
-```
-
-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
-
-Install the Claude Code plugin for all ten workflow skills and its plugin worker/reviewer agents, then install the project integration:
-
-```text
-/plugin marketplace add instructa/planr
-/plugin install planr@planr
-```
-
-```bash
-planr project init "Example Product" --client claude
-planr install claude
-planr doctor --client claude
-```
-
-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
-
-One command wires everything — MCP, the skills, and the subagent roles:
-
-```bash
-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`, 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
-
-Any MCP-capable coding agent can run:
-
-```bash
-planr mcp
-```
-
-Use these commands for setup text without editing global config:
-
-```bash
-planr prompt mcp --client all
-planr prompt cli --client all
-planr prompt http --client all
-```
-
-## What The Skills Do
-
-The skills are client-neutral and use only Planr-owned commands:
-
-```bash
-planr project show --json
-planr plan new "App idea"
-planr map build --from <plan-id>
-planr pick --json
-planr done <item-id> --summary "..." --files a --files b --cmd "..." --review --next
-planr review close <review-id> --verdict complete --close-target
-planr approval list --open
-```
-
-The granular commands (`log add`, `review request`, `close`, `pick heartbeat`) remain available; `done` chains them with identical evidence.
-
-See also:
-
-- [Operating Model](OPERATING_MODEL.md)
-- [Task Graph Model](TASK_GRAPH_MODEL.md)
-- [Handoffs And Stories](HANDOFFS_AND_STORIES.md)

package/docs/TASK_GRAPH_MODEL.md

@@ -1,272 +0,0 @@
-# Planr Task Graph Model
-
-Planr's map is a local dependency-aware graph for coding-agent work. It exists so agents can coordinate without relying on ad hoc chat history.
-
-## Core Objects
-
-- Project: repository-level Planr workspace.
-- Plan: Markdown product or build package.
-- Item: one unit of live work in the map.
-- Link: relationship between items.
-- Pick: atomic claim of a ready item by one worker session.
-- Log: durable proof of implementation, verification, review, or handoff.
-- Review: an item that blocks target closure until it is closed.
-- Context: searchable discovery or decision.
-- Recovery: explicit preview/apply operation for stale, timed-out, or retryable work.
-
-## State Authority
-
-The SQLite database is authoritative for:
-
-- item status;
-- links and readiness;
-- picks and ownership;
-- reviews and closure gates;
-- contexts and logs;
-- artifacts and events as they become public product surfaces.
-
-Markdown plans are authoritative for scope and acceptance criteria. They do not override map state.
-
-## Item Readiness
-
-Readiness is derived from state and links:
-
-- an item may become ready when its blocking upstream items are closed;
-- picked items are owned by one worker session;
-- requesting a review moves a picked or running item to `in_review` (ownership kept) so the wait state is visible instead of masquerading as active work;
-- closed items can unlock downstream items;
-- open review items block target closure;
-- cancelled items should not silently unlock unrelated work.
-
-The status lifecycle for work items is `pending -> ready -> picked -> running -> in_review -> closed` (with `blocked`, `failed`, `cancelled`, and `closed_partial` as branch states). `in_review` items still accept evidence logs and heartbeats from their owner, are excluded from new picks, and close either through `review close --verdict complete --close-target` or an explicit `planr close` after the review completes. Findings keep the target `in_review`: the follow-up review gates the same target until the chain settles.
-
-Use:
-
-```bash
-planr map show --json
-planr map lane --critical
-planr map pressure
-```
-
-## Links
-
-Create explicit order:
-
-```bash
-planr item create "Design API" --description "Define endpoints and data ownership."
-planr item create "Implement API" --description "Build endpoints after design is closed."
-planr link add <design-item> <implementation-item> --type blocks
-```
-
-Use `blocks` for hard ordering. Use softer link types only when the product contract for that type is documented and tested.
-
-Structured output always keeps that canonical `blocks` kind. Human rendering adds
-current satisfaction state without mutating it: an upstream `closed` or
-`closed_partial` item renders as dim `blocks✓` in the compact tree and neutral `then`
-in the human-only diagram. Open, failed, and cancelled upstream items still render as
-red `blocks`; cancellation does not satisfy readiness.
-
-## Picking
-
-Picking is the concurrency boundary:
-
-```bash
-planr pick --json
-```
-
-One ready item should be picked by one worker. The pick output is one flat work packet — item, links, logs, runtime, recovery, conditions, recall context, and a `remaining` progress snapshot, each fact exactly once; empty collections are omitted. Picked work records `worker_id`, `pick_token`, `picked_at`, and `last_heartbeat_at`. Worker identity is stable per client, host, and user, so heartbeats keep working across the many short-lived processes of an agent session. Agents should export `PLANR_WORKER_ID` (an explicit identity such as `maker-1` or `checker-1`) for the whole session, so picks, logs, and heartbeats attribute to the agent instead of `client:host:user`. Parallel workers on the same machine must set `PLANR_WORKER_ID` (or `PLANR_SESSION_ID`) to distinct values. Evidence written via `log add` or `done` by the owner refreshes the heartbeat automatically; the explicit runtime commands cover long silent stretches:
-
-```bash
-planr pick heartbeat [item-id]
-planr pick progress <item-id> --percent 42 --note "running focused tests"
-planr pick pause <item-id> --note "waiting for review input"
-planr pick resume <item-id>
-```
-
-If two workers race, the database must allow only one winner. If the owner disappears, inspect stale claims and reset intentionally:
-
-```bash
-planr pick stale --older-than-seconds 900
-planr pick stale --older-than-seconds 900 --release
-planr recover sweep --older-than-seconds 900
-planr recover sweep --older-than-seconds 900 --apply
-planr pick release <item-id> --force
-```
-
-Use forced release only when the operator intentionally transfers ownership. Use `recover sweep --apply` for the broader recovery path that also requeues timed-out picked work and retryable failed work.
-
-## Approvals
-
-Approvals are explicit human gates on an item:
-
-```bash
-planr approval request <item-id> --reason "needs release approval"
-planr approval deny <item-id> --by "qa" --comment "missing evidence"
-planr approval approve <item-id> --by "qa" --comment "evidence accepted"
-planr approval list --open
-```
-
-An item with `requested` or `denied` approval status cannot close. `map preview --close <item-id>` reports whether approval blocks closure before the mutation is attempted.
-
-## Reviews And Fix Chains
-
-Request review after evidence exists:
-
-```bash
-planr review request <item-id>
-```
-
-A clean review can close:
-
-```bash
-planr review close <review-id> --verdict complete
-```
-
-Findings create follow-up work:
-
-```bash
-planr review close <review-id> \
-  --verdict not-complete \
-  --findings "specific actionable finding"
-```
-
-The target item may close only when required review items are closed.
-
-Every `review close` records a derived `review_mode`: the closing reviewer identity is compared against the target item's lease holder and recorded as `single_agent` (same identity), `independent` (different identity), or `unattributed` (no recorded maker). The mode lands in the close response, review log, artifact, and event — independence is proven by recorded identity, not declared by a note. `unattributed` should be rare: `done` adopts a never-picked ready item (the lease is written retroactively under the current worker), so every completion path records a maker. When it does appear, the close output explains that the target carried no lease.
-
-## Evidence
-
-Logs make closure auditable:
-
-```bash
-planr log add --item <item-id> \
-  --summary "Implemented parser hardening" \
-  --files src/parser.rs,tests/parser.rs \
-  --cmd "cargo test parser"
-```
-
-Use multiple `--cmd` or `--tests` values when more than one verification command matters. `--cmd` records what was executed; `--tests` records test commands/results specifically — both are evidence fields, not gates.
-
-Live verification evidence (browser runs, smoke tests against a running app) uses `--kind verification`:
-
-```bash
-planr log add --item <item-id> --kind verification \
-  --summary "Verified upload flow in browser: video plays after publish" \
-  --cmd "agent-browser snapshot http://localhost:3000/watch/1"
-```
-
-`plan audit` checks for verification logs when a goal contract exists. Log persistent evidence, not transient states: a failure that you immediately fix belongs in the final log's narrative, not as a standalone failure log.
-
-Settling commands (`done`, `close`, `review close`) report what they `unlocked` — every item that became ready because of that settlement — plus the item's `post_condition` and an evidence hint when downstream work depends on an item closed without `--cmd`/`--tests`.
-
-## Graph Inspection
-
-Coding agents use the compact default tree or `map show --json`. They must not
-invoke the diagram renderer. The boxed workflow diagram is exclusively for a
-person scanning the graph shape and current state:
-
-```bash
-planr map show
-planr map show --view diagram
-planr map show --plan <plan-id> --view diagram
-planr map show --plan <plan-id> --view diagram --full
-```
-
-The default diagram keeps every box to at most two content lines in
-`ICON ITEM-ID → TITLE` form. It still labels readiness-blocking routes, joins,
-disconnected components, and cycles. Active dependencies use `blocks`; satisfied
-dependencies use neutral `then`. Add `--full` for the previous verbose node
-layout with status words, complete wrapped titles, critical items, downstream
-pressure, and active workers. It is only a human renderer: coding agents do not
-invoke it, the SQLite map
-remains authoritative, the default `map show` view stays `tree`, and `--json`
-returns the same projection regardless of diagram detail.
-
-Human map states are colorized automatically on an interactive terminal while
-retaining their symbols and words. `--no-color`, `NO_COLOR`, `TERM=dumb`, pipes,
-and JSON stay plain.
-
-For a person to observe an agent live, use a second terminal:
-
-```bash
-# terminal A: agent/worker continues to pick, log, review, and close work
-# terminal B:
-planr map watch --plan <plan-id>
-planr map watch --plan <plan-id> --until-settled
-planr map watch --plan <plan-id> --full
-```
-
-`map watch` is human-only; coding agents must not invoke it. Watch defaults to
-the condensed diagram, polls once per second, and redraws only
-after a canonical graph change. `--full`, `--view tree`, `--interval-ms`, and
-`--no-clear` are available for detailed, compact-tree, or append-only
-observation. It records no graph events. Agents use `map show --json` or the
-local `/v1/events/stream` SSE endpoint instead.
-Machine consumers should use JSON snapshots or the local
-`/v1/events/stream` SSE endpoint.
-
-Use critical lane for ordering risk:
-
-```bash
-planr map lane --critical
-```
-
-Use pressure for bottlenecks:
-
-```bash
-planr map pressure
-```
-
-Use trace for handoff:
-
-```bash
-planr trace item <item-id>
-```
-
-The trace should be enough for a new agent to recover the current item, linked logs, and linked blockers.
-
-Use status, lookahead, and close preview before sequencing or closure:
-
-```bash
-planr map status
-planr map lookahead <item-id>
-planr map preview --close <item-id>
-```
-
-These commands expose readiness, downstream unlocks, closure blockers, approval requirements, open reviews, and manual conditions before mutating graph state.
-
-## Review Evidence
-
-Review evidence is item-scoped proof, not a dump of the whole repository:
-
-```bash
-planr review evidence <item-id>
-planr review evidence <item-id> --pr-url https://example.invalid/pr/123
-```
-
-Planr reports Git branch, commit, dirty state, files named by item logs/artifacts, unrelated dirty files, and optional PR URL context. It does not inline source file content by default.
-
-## Packages
-
-Packages preserve reusable graph context outside the live database:
-
-```bash
-planr export --include-plans --include-logs --template-name "Release checklist" --tag release --out planr-package.json
-planr import planr-package.json --preview
-planr import planr-package.json --confirm
-```
-
-Package import is preview-first and confirmed explicitly. Imported packages restore items, links, contexts, logs, plan file snapshots, and review artifacts into the current map.
-
-## Graph Adaptation
-
-Planr supports graph adaptation without relying on chat-only replanning:
-
-- use `item breakdown` for decomposition;
-- use `item insert --preview` before rewiring linked work and `--confirm` to apply;
-- use `item amend` for future-work context;
-- use `item replan --preview` before replacing pending child work and `--confirm` to apply;
-- use `link add` and `link remove` for dependency changes;
-- use `map preview --close`, `map unlocks`, `map lookahead`, and `map status` before closing or sequencing work;
-- use `item cancel --preview` before cancellation;
-- use `trace item` and logs for recovery.

package/docs/TESTING.md

@@ -1,87 +0,0 @@
-# Testing
-
-Planr has two test layers plus a release-grade V1.1 verification ladder.
-
-## In-Repo Tests
-
-```bash
-cargo fmt --check
-cargo clippy --all-targets -- -D warnings
-cargo test
-```
-
-Focused V1.1 checks should be run when their surfaces change:
-
-```bash
-cargo test recovery_sweep -- --nocapture
-cargo test local_review_workspace -- --nocapture
-cargo test review_evidence -- --nocapture
-cargo test template_export_import -- --nocapture
-```
-
-## Consumer E2E Project
-
-The standalone consumer suite is a maintainer-local project that is not part of this repository. On maintainer machines it lives at:
-
-```bash
-~/projects/planr-test
-```
-
-Contributors without that project should rely on the in-repo suite (`cargo test`), which covers the same CLI, MCP, and HTTP surfaces.
-
-Run against the local native binary:
-
-```bash
-cd ~/projects/planr
-cargo build --release
-cd ~/projects/planr-test
-npm test
-```
-
-Run through the npm package wrapper:
-
-```bash
-cd ~/projects/planr
-npm link
-cd ~/projects/planr-test
-npm link planr
-npm run test:npm-planr
-```
-
-The consumer suite exercises every public command group and subcommand, MCP stdio, local HTTP/SSE, import/export, review gates, install helpers, and generated plan files.
-
-## V1.1 Release Verification
-
-Before calling V1.1 complete, run the full in-repo and consumer ladder:
-
-```bash
-cargo fmt --check
-cargo test
-cargo clippy --all-targets -- -D warnings
-scripts/build-release.sh
-(cd dist && shasum -a 256 -c SHA256SUMS)
-(cd dist/planr-1.0.0 && shasum -a 256 -c SHA256SUMS)
-npm pack --dry-run
-```
-
-Installer changes also require:
-
-```bash
-/Users/kregenrek/.agents/skills/shellck/scripts/run_shellck.sh scripts/install.sh
-PREFIX="$(mktemp -d)" PLANR_DOWNLOAD=1 PLANR_RELEASE_BASE_URL="file://$PWD/dist" scripts/install.sh
-```
-
-Live behavior must be proved with:
-
-- a fresh consumer project at `~/projects/planr-test`;
-- MCP stdio contract checks against `docs/fixtures/mcp-contract.json`;
-- localhost HTTP/SSE checks and the browser review workspace at `/review`;
-- recovery sweep checks for stale, timed-out, and retryable work;
-- Git/PR review evidence checks that do not inline source content;
-- package export/import checks for templates, logs, plan files, and review artifacts;
-- prompt output checks for CLI, MCP, and HTTP setup text;
-- a forbidden-reference scrub across public repo files.
-
-## Contract Fixtures
-
-`docs/fixtures/mcp-contract.json` is checked by the Rust E2E suite against live MCP stdio responses, install dry-runs, and the CLI reference. Update the fixture and `docs/MCP_CONTRACT.md` together when adding or removing MCP tools, resources, prompts, or install snippets.

package/docs/TROUBLESHOOTING.md

@@ -1,30 +0,0 @@
-# Troubleshooting
-
-## No Ready Items
-
-```bash
-planr map show --json
-planr map pressure
-planr trace item <item-id>
-```
-
-## MCP Client Cannot See Tools
-
-```bash
-planr doctor --client all
-planr install codex --dry-run
-planr install claude --dry-run
-planr install cursor --dry-run
-```
-
-## A Planr Command Appears To Hang
-
-Planr bounds every database wait: `busy_timeout` is 5 seconds, and no command loops indefinitely — SQLite contention resolves or errors within that bound (a parallel first-pick storm is regression-tested). If a command still appears hung inside an agent-host tool call, the wait is almost certainly outside Planr: host tool harnesses that stop draining the child's stdout block the process on a full pipe, which looks exactly like a hang and works on retry. Kill and re-run the command; if it reproduces outside the host harness (plain terminal), capture a stack (`lldb -p <pid>` then `bt all`) and file it with the output — that would be a Planr bug we want.
-
-## Database Or Import Issues
-
-```bash
-planr project show --json
-planr import /path/to/repo --json
-planr export --include-plans --include-logs --out planr-debug.json
-```