planr 1.6.0 → 1.7.1

package/docs/CURSOR.md

@@ -1,114 +0,0 @@
-# Cursor Integration
-
-Cursor is a first-class Planr client. One command wires a project completely — MCP tools, the worker/reviewer subagents, and the full skill set:
-
-```bash
-planr install cursor
-```
-
-This writes only repository-local files (never global Cursor config):
-
-| Path | Purpose |
-| --- | --- |
-| `.cursor/mcp.json` | project-scoped stdio MCP server (`planr mcp`) with the 44 Planr tools |
-| `.cursor/agents/planr-worker.md` | worker subagent: implements exactly one picked item, then requests review and stops |
-| `.cursor/agents/planr-reviewer.md` | reviewer subagent: audits evidence and closes the review with a verdict |
-| `.cursor/skills/planr*/SKILL.md` | all ten Planr skills (`planr`, `planr-goal`, `planr-loop`, stage and capability skills) |
-
-Re-running the command refreshes `.cursor/mcp.json` but never overwrites edited agent or skill files. `planr project init "My Product" --client cursor` (or `--client all`) provisions the same subagent roles at init time. Verify with `planr doctor --client cursor`.
-
-## Skills And Agents Only (No MCP)
-
-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/`, `.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
-
-For user-level setup (all projects, no repo files), the dry-run prints a Cursor deeplink:
-
-```bash
-planr install cursor --dry-run
-```
-
-```text
-cursor://anysphere.cursor-deeplink/mcp/install?name=planr&config=eyJhcmdzIjpbIm1jcCJdLCJjb21tYW5kIjoicGxhbnIifQ==
-```
-
-Open the link (or paste it into a browser) and Cursor prompts to install the server. The embedded config is `{"command": "planr", "args": ["mcp"]}` with no `--db` path on purpose: Cursor starts the server in the workspace directory, so every project resolves its own `.planr/planr.sqlite`.
-
-## Plugin
-
-The repository carries a Cursor plugin manifest (`.cursor-plugin/plugin.json`) bundling the skills and both subagents. Marketplace listing is pending review; until it is listed:
-
-- `planr install cursor` (above) provides the identical component set per project, or
-- install the plugin locally: copy the repository to `~/.cursor/plugins/local/planr` and reload Cursor.
-
-## Multitasking With Cursor's Built-In Features
-
-Cursor's subagents, background execution, and parallel agents map directly onto Planr's maker/checker loop. The Planr map is the shared state, so concurrent Cursor agents coordinate through `planr pick` leases instead of stepping on each other.
-
-### Subagent dispatch (maker/checker)
-
-The installed subagents are dispatched from any Agent chat with `/name` or by mention:
-
-```text
-/planr-worker implement item <item-id>
-/planr-reviewer review item <item-id>
-```
-
-The worker preloads the `planr-work` protocol (implement one item, log evidence, request review, stop); the reviewer preloads `planr-review` (audit the diff, rerun logged commands, close with a verdict). Because each subagent runs in its own context window, the driving chat stays focused on `plan audit`, dispatch decisions, and synthesis — the same division of labor as Codex `/goal` and Claude Code (see [Long-Running Goals](GOALS.md)).
-
-Cost tiering: the worker file ships with `model: inherit`; edit its frontmatter to pin a cheaper Cursor model id when dispatch cost matters. Leave the reviewer on `inherit` — make workers cheap, not the verdict.
-
-### Parallel and background work
-
-- **Parallel subagents:** ask the driver to dispatch several workers at once ("implement items A, B, and C in parallel with planr-worker subagents"). Each worker calls `planr pick` (or is handed its item id); the map's single-owner lease guarantees no two agents hold the same item, and `planr recover sweep` reclaims work from any that die.
-- **Background subagents:** long items can run as background subagents; evidence logging doubles as the liveness heartbeat, so `planr pick stale` shows honestly stuck work.
-- **Cloud agents (`/in-cloud`):** cloud VMs do not share your local `.planr` database or local MCP config. Give cloud agents the CLI workflow instead (`planr prompt cli --client cursor`) and let them commit evidence through normal Planr CLI calls in their own checkout.
-
-### Parallel agents in worktrees
-
-Cursor's parallel agents run in separate git worktrees, and each worktree would otherwise get its own copy of `.planr/planr.sqlite` — forking the map. Keep one authoritative map by pointing every worktree at a shared absolute database path:
-
-```json
-{
-  "mcpServers": {
-    "planr": {"command": "planr", "args": ["--db", "/absolute/path/to/main-checkout/.planr/planr.sqlite", "mcp"]}
-  }
-}
-```
-
-`planr install cursor` already writes the absolute path of the current checkout, so worktrees created from an installed project inherit the right value — verify with `planr project show --json` from each worktree. One picked item per agent instance stays the rule (`plugins/planr/skills/planr-loop/SKILL.md`, Hard Rules).
-
-### Goal loops
-
-Cursor has no `/goal` primitive; the human (or an automation) is the re-dispatcher:
-
-```text
-Use $planr-goal: <your goal>
-Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract).
-```
-
-`$planr-loop` iterates inside the session, dispatching `/planr-worker` and `/planr-reviewer` per item. If the session ends before `planr plan audit <plan-id>` holds, send the same starter line in a fresh session — the map, the stored contract, and open reviews carry the run, not chat history.
-
-## HTTP And Review Feedback
-
-Planr V1 defaults to MCP stdio. Local HTTP/SSE is available through:
-
-```bash
-planr serve --port 7526
-```
-
-Cursor tasks can attach review feedback through either MCP stdio or the local HTTP API:
-
-```bash
-planr review annotate <item-id> --message "Cursor review note" --severity warning
-planr review ingest <item-id> --from .planr/tmp/cursor-review.json
-```
-
-Review ingestion does not auto-close or auto-approve work.

package/docs/EXAMPLE_WEBAPP.md

@@ -1,103 +0,0 @@
-# Worked Example: Routing a Small Web App
-
-This provider-neutral example routes a todo web app by work type. Planr Core treats every profile field as opaque data and does not select a host or model.
-
-## 1. Create the project and registry
-
-```bash
-planr project init "Todo Webapp"
-planr agents init
-```
-
-Edit the repository-local `.planr/agents.toml` with profiles owned by your team or routing package:
-
-```toml
-[profiles.frontend-worker]
-client = "your-host"
-model = "your-fast-model"
-effort = "medium"
-cost_tier = "budget"
-skill = "planr-work"
-
-[profiles.backend-worker]
-client = "your-host"
-model = "your-engineering-model"
-effort = "high"
-cost_tier = "standard"
-skill = "planr-work"
-
-[profiles.independent-reviewer]
-client = "your-host"
-model = "your-review-model"
-effort = "high"
-cost_tier = "premium"
-skill = "planr-review"
-
-[[routes]]
-match = { work_type = "frontend" }
-profile = "frontend-worker"
-
-[[routes]]
-match = { work_type = "backend" }
-profile = "backend-worker"
-
-[[routes]]
-match = { work_type = "review" }
-profile = "independent-reviewer"
-```
-
-Validate without contacting a provider:
-
-```bash
-planr agents check
-planr agents list
-```
-
-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 agents check
-planr agents list --json
-```
-
-## 2. Tag items by use case
-
-```bash
-planr item create "API: task CRUD endpoints" \
-  --description "GET/POST/PATCH/DELETE /api/tasks with sqlite store" \
-  --work-type backend
-
-planr item create "UI: task list and add form" \
-  --description "List view and optimistic add form" \
-  --work-type frontend
-```
-
-## 3. Pick and dispatch
-
-```bash
-planr pick --work-type backend --json
-```
-
-The pick packet contains the selected opaque profile, client, model, effort, skill, and selector. The host remains responsible for dispatching it; Planr never claims that the requested model actually ran.
-
-## 4. Close with evidence
-
-```bash
-planr done <item-id> \
-  --summary "CRUD endpoints implemented; 8 tests green" \
-  --files server/routes/tasks.ts \
-  --tests "vitest --run: 8 passed" \
-  --profile backend-worker
-```
-
-`--profile` records the run's claimed profile. For stronger evidence, attach a route observation that keeps requested, host-resolved, and effective values separate.
-
-## 5. Trace declared versus actual
-
-```bash
-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 [External Routing Declarations](ROUTING_BUNDLES.md).

package/docs/GOALS.md

@@ -1,175 +0,0 @@
-# Long-Running Goals
-
-Planr makes long-running, autonomous goal runs durable. A loop driver — Codex `/goal`, Claude Code `/goal` or `/loop`, an automation, or a human re-dispatching a skill — supplies continuation pressure: "do not stop until the goal holds." Planr supplies everything such a run loses between sessions: the plan, the task map, picks, evidence logs, review gates, approvals, and recovery.
-
-This is complementary, not competing. `/goal` stays the orchestrator; Planr is the state layer underneath it. Without a native loop primitive you lose only automatic re-prompting — never state, evidence, or recovery.
-
-## Division Of Labor
-
-| Concern | Owner |
-| --- | --- |
-| Continuation pressure, re-prompting, session autonomy | loop driver (`/goal`, automation, human) |
-| Scope, acceptance criteria, verification contract | Planr plan (`planr plan new/check`) |
-| Task state, dependencies, what is next | Planr map (`planr map`, `planr pick`) |
-| Stop condition that survives compaction | Planr context (`--tag goal-contract`) |
-| Proof the work happened and runs | Planr logs (`planr log`, `planr done`) |
-| Maker/checker separation | Planr reviews (`planr review`) + subagent roles |
-| Recovery after session loss or host switch | Planr map + stored contract, from zero chat context |
-
-## The Workflow
-
-### 1. Prep — `$planr-goal` (once, interactive)
-
-```text
-$planr-goal Add CSV export to the reports page, should work in the browser
-```
-
-The skill compiles the goal and stops — no implementation:
-
-- creates and checks a feature-scoped plan (`planr plan new` -> `plan check`; strict, empty sections fail),
-- builds the map and links execution order (`planr map build` is idempotent; `planr link add ... --type blocks`),
-- stores the goal contract durably in Planr:
-
-```bash
-planr context add "GOAL CONTRACT pl-csv-export: DONE when every in-scope map item is closed with log evidence, all reviews closed with verdict complete, no open approvals in scope, and a live browser verification log exists for the export flow. Iteration budget: 10." --tag goal-contract
-```
-
-- prints the exact starter command for your host.
-
-### 2. Execute — the loop driver runs `$planr-loop`
-
-```text
-/goal Use $planr-loop on plan pl-csv-export. The loop contract is stored in planr context (tag: goal-contract). Continue until the contract holds or the iteration budget is exhausted. You are operating autonomously: the user is not watching, so never end a turn on a plan, a question, or a promise — proceed until the contract holds or you are blocked on input only the user can provide.
-```
-
-The autonomy clause matters on long runs: deep into a session, frontier models occasionally end a turn with a statement of intent instead of the corresponding action, or pause to ask permission they already have. Stating the operating mode up front prevents both.
-
-Each iteration follows the `$planr-loop` protocol:
-
-```text
-1. planr plan audit <plan-id>   one-call contract verdict; holds -> exit
-2. $planr-work     pick exactly one ready item, implement, finish with planr done --review
-3. live verify     run the platform verification, log it with planr log add --kind verification --cmd
-4. $planr-review   independent audit; complete -> review close --close-target,
-                   findings -> fix items become the next ready items
-5. repeat
-```
-
-`plan audit` replaces the hand-rolled final audit: it checks `items_settled`, `reviews_complete`, `approvals_clear`, and `verification_logged` clause by clause with evidence, includes the stored goal contract, and answers `holds: true/false` in one command.
-
-The per-item path is three commands since v1.1.6:
-
-```bash
-planr pick --json --plan <plan-id>                           # flat work packet, leased only from the goal's plan
-planr done <item-id> --summary "..." --cmd "..." --review --next
-planr review close <review-id> --verdict complete --reviewer <id> --close-target
-```
-
-`--plan` keeps the lease inside the goal contract: when several plans share the board (a parallel feature, leftovers from an aborted prep run), a plan-scoped goal run never picks work outside its own plan. A pick that finds nothing in scope never widens silently: it reports `reason: "nothing_ready"` when nothing is ready at all, or `reason: "ready_items_excluded_by_filter"` with the excluded items, the cause per item, and the exact `repair` pick commands when ready work exists outside the filter.
-
-`done`/`close`/`review close` responses and the pick packet include a `remaining` snapshot (`counts` with explicit zeros for every status, `settled`, `total`), so the orchestrator evaluates the stop condition straight from the completion output — no extra `map status` round-trip. The same responses list what each settlement `unlocked`, so the loop sees its next work without re-reading the map. `--next` never hands a worker its own freshly created review, so maker and checker stay separate even in compact loops. The review verdict records `review_mode` (`single_agent` or `independent`) automatically from worker identity — no ceremony note needed. The contract's "all reviews closed" clause audits review items that exist; an item closed with plain `done` satisfies the contract without a review gate, so low-signal reviews can be skipped without blocking `plan audit`.
-
-### 3. Finish
-
-When the contract holds, the loop exits through `$planr-summary`: an evidence-backed account of what shipped, which commands proved it, and what (if anything) stayed blocked.
-
-## Recovery
-
-The defining property of a long-running goal: the session will die before the goal does. With Planr that costs nothing. Start a new session — same host or a different one — with the same starter line:
-
-```text
-/goal Use $planr-loop on plan pl-csv-export. The loop contract is stored in planr context (tag: goal-contract).
-```
-
-Iteration 1 reads the map and the stored contract: items already settled stay settled, open reviews stay open, the next ready item is picked. No chat history needed. `planr recover sweep` handles stale picks from interrupted workers.
-
-## Per-Host Setup
-
-### Codex with `/goal`
-
-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 agents check
-```
-
-Then:
-
-```text
-$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 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
-
-Same shape via the plugin (`/plugin install planr@planr`), which registers the `planr-worker` and `planr-reviewer` subagents automatically:
-
-```text
-/planr:planr-goal <your goal>
-/goal Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract).
-```
-
-`/loop` works for fixed-cadence runs instead of goal-conditioned ones. The registered worker subagent pins a cheaper model tier; see [Cost Tiering](#cost-tiering).
-
-### Cursor
-
-No `/goal` primitive, but full subagent support. Install once:
-
-```bash
-planr install cursor   # writes .cursor/mcp.json, .cursor/agents/planr-worker.md + planr-reviewer.md, and the skills
-```
-
-Then run the identical protocol with the human (or an automation) as the re-dispatcher:
-
-```text
-Use $planr-goal: <your goal>
-Use $planr-loop on plan <plan-id>. The loop contract is stored in planr context (tag: goal-contract).
-```
-
-`$planr-loop` iterates within the session under its own budget, dispatching `/planr-worker` and `/planr-reviewer` per item — the provisioned subagents preload the work and review protocols, so dispatches stay one line. If the session ends before the contract holds, dispatch the same line again — recovery is identical to the `/goal` case. Parallelism, background subagents, and worktree caveats: [Cursor](CURSOR.md).
-
-### Hosts without a loop primitive
-
-Identical protocol; the human (or a background agent) is the re-dispatcher, and worker/reviewer run as separate sequential dispatches when the host has no subagents.
-
-### Plain MCP clients
-
-Any MCP-capable agent uses the same flow over `planr mcp`. Every session starts with map state, so the loop is resumable by construction.
-
-## Cost Tiering
-
-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 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
-
-If you already run goal workflows with other tools, the concepts map directly:
-
-| Elsewhere | In Planr |
-| --- | --- |
-| Goal charter file (`goal.md`) | product/build plan (`planr plan new`, rich scope + verification) |
-| Board/state file (`state.yaml`) | the map (`planr map show`, authoritative item state) |
-| One active task | `planr pick` (single owner, heartbeat, stale recovery) |
-| Task receipts | `planr log` / `planr done` (files, commands, results) |
-| Goal oracle / completion proof | goal contract + live verification log |
-| Scout/Judge/Worker roles | worker/reviewer subagents + `$planr-status` for honest reads |
-| Final audit before done | `$planr-review` with `review close --verdict complete` |
-
-Using such tools for intake or visualization alongside Planr is fine — keep one rule: the Planr map stays the single source of truth for item status, links, picks, reviews, approvals, and completion.
-
-## Rules That Keep Goal Runs Honest
-
-- Never weaken a stored goal contract mid-run; scope changes go through `$planr-plan` and the user.
-- "Done" means the feature ran (live verification log), not that it compiles.
-- The maker never closes its own review; single-agent hosts record `review-mode` honestly.
-- Two iterations without map-state movement -> stop and report instead of grinding.
-- Destructive or out-of-repo side effects always go behind `planr approval request`.
-- Lessons that should outlive the iteration (a confirmed approach, a correction, a dead end) go into `planr context add "..." --tag lesson` — the next iteration or a fresh session recovers them with `planr context list --tag lesson`, not from chat history.
-
-See also: [Skills](SKILLS.md), [Operating Model](OPERATING_MODEL.md), [Task Graph Model](TASK_GRAPH_MODEL.md), [Codex](CODEX.md), [Claude Code](CLAUDE_CODE.md), [Cursor](CURSOR.md).

package/docs/HANDOFFS_AND_STORIES.md

@@ -1,121 +0,0 @@
-# Handoffs And Stories
-
-Planr separates live state from narrative memory.
-
-- Live state belongs in the map.
-- Completion proof belongs in logs.
-- Searchable decisions belong in contexts.
-- Long-form narrative belongs in story logs.
-
-## Handoff Logs
-
-Use `planr log add` whenever another agent, reviewer, or future session must know what happened:
-
-```bash
-planr log add --item <item-id> \
-  --summary "Implemented release dry-run checks" \
-  --files scripts/build-release.sh,docs/RELEASE.md \
-  --cmd "scripts/build-release.sh" \
-  --cmd "cargo test"
-```
-
-A useful handoff log names:
-
-- changed files;
-- commands run;
-- test results;
-- assumptions kept;
-- decisions made;
-- known remaining risk.
-
-Do not paste private source files, secrets, tokens, or full transcripts into logs.
-
-## Context Entries
-
-Use context for durable discoveries:
-
-```bash
-planr context add "Release dry-runs must not edit global agent configuration." --tag constraint
-planr context add "Use project-scoped MCP config for client examples." --tag decision
-```
-
-Prefer context when the fact may influence multiple future items.
-
-## Task Notes
-
-Use notes for local item discussion:
-
-```bash
-planr note add "Reviewer asked for an extra npm pack dry-run before closure." --item <item-id>
-```
-
-Prefer notes when the fact is not project-wide and should stay near one item.
-
-## Story Logs
-
-Use story logs only when map items, contexts, and logs are too thin to preserve the decision chain.
-
-Create a story log for:
-
-- a large architecture or ownership change;
-- a multi-round review/fix sequence;
-- a discovery that invalidates earlier assumptions;
-- a release or schema-upgrade path that future agents must understand;
-- interruption-prone work where the "why" matters as much as the status.
-
-Recommended location for repo-versioned product stories:
-
-```text
-.planr/stories/
-```
-
-Recommended location for private operator-only stories:
-
-```text
-~/.planr/<project>/stories/
-```
-
-Do not create `todo`, `in-progress`, or `finished` story folders. Status belongs to the map.
-
-## Story Template
-
-```markdown
-# <Story Title>
-
-Project: <project name>
-Related items: <item ids>
-Updated: <YYYY-MM-DD>
-
-## Problem
-
-## Current State
-
-## Key Discoveries
-
-## Decisions
-
-## Rejected Alternatives
-
-## Implementation Or Review History
-
-## Verification
-
-## Open Risks
-
-## Next Likely Steps
-```
-
-Keep the story focused on narrative. Do not duplicate the full map.
-
-## Recovery Order
-
-When resuming work:
-
-1. `git status --short`
-2. `planr map show --json`
-3. `planr trace item <item-id>`
-4. `planr log list --item <item-id>`
-5. `planr context list --item <item-id>`
-6. read a relevant story log only if the trace and logs do not explain why the work exists
-
-The story log may explain direction, but it must not override the map.

package/docs/HOOKS.md

@@ -1,34 +0,0 @@
-# Host Hooks
-
-`planr install codex|claude|cursor` wires Planr into the host's native hook system **by default** — skip it with `--no-hooks`. The hooks solve one problem: loop state must survive the moments context is created or destroyed. Every new session and every context compaction gets the map state injected automatically via `planr prime`, so recovery stops being discipline and becomes mechanism.
-
-## What gets installed
-
-| Host | File | Events | Runs |
-| --- | --- | --- | --- |
-| Cursor | `.cursor/hooks.json` | `sessionStart` | `planr prime --cursor-json` |
-| | | `subagentStop` | `.cursor/hooks/planr-evidence-guard.sh` |
-| Claude Code | `.claude/settings.json` | `SessionStart` (matcher `startup\|resume\|compact`) | `planr prime --hook-json` |
-| Codex CLI | `.codex/hooks.json` | `SessionStart` | `planr prime` |
-
-`planr prime` prints one compact, bounded state block (project, map counts, your held items with log status, the goal contract, registry presence, and the next command) — deterministic and read-only. `--hook-json` wraps it in the Claude Code SessionStart envelope (`hookSpecificOutput.additionalContext`); `--cursor-json` emits Cursor's `additional_context` shape.
-
-Only session-start events are wired, deliberately: they are the one place all three hosts inject hook output as context, and Claude's `compact` source plus post-compaction session starts cover the compaction case. Pre/post-compaction events (`preCompact`, `PreCompact`, `PostCompact`) cannot restore model context and are not used.
-
-The evidence guard is advisory and identity-scoped: a Cursor subagent that stops while *its own* pick (matched via `PLANR_WORKER_ID`/`PLANR_SESSION_ID`) has no completion log gets one follow-up message naming the item and the two ways out (`planr done ...` or `planr pick release ...`). Without an explicit worker identity it stays silent rather than steering the wrong agent toward foreign items. It never blocks.
-
-## Design rules
-
-- **Fail open, always.** Every hook command ends in `|| true` with a 10-second timeout; a missing, broken, or uninitialized planr never blocks a session. In a repo without a Planr database, `planr prime` exits silently and creates nothing.
-- **Additive merge, planr owns only its own entries.** Existing hook files keep every foreign entry; planr entries are reconciled on re-install (current ones untouched, outdated ones upgraded in place, entries under retired events removed) — so `planr install <client>` after an update also refreshes the hooks. A file planr cannot parse as a JSON object is left untouched with a note in the install output — add the snippet manually in that case.
-- **Default, not mandatory.** `--no-hooks` skips hook installation entirely; deleting the planr entries from the hook files removes the behavior with no other effect.
-
-## Codex trust model
-
-Codex requires reviewing hooks before they run: after installing, open `/hooks` in the Codex TUI once and trust the planr entries. Codex records trust against the hook definition's hash, so if a future planr version changes the hook commands, Codex will ask again — that is the host working as intended.
-
-## Removing hooks
-
-Delete the planr entries from `.cursor/hooks.json` / `.claude/settings.json` / `.codex/hooks.json` (and `.cursor/hooks/planr-evidence-guard.sh`). Nothing else depends on them.
-
-See also: [Model Routing](MODEL_ROUTING.md), [Goals](GOALS.md), [CLI Reference](CLI_REFERENCE.md).

package/docs/IMPORT.md

@@ -1,21 +0,0 @@
-# Planr Packages
-
-```bash
-planr project init "New Project"
-planr export --include-plans --include-logs --template-name "API backend slice" --tag api --out planr-package.json
-planr import planr-package.json --preview
-planr import planr-package.json --confirm
-```
-
-Planr packages are local-first JSON files created by `planr export`. They carry graph items, links, contexts, optional logs, optional plan file snapshots, and review artifacts.
-
-Imports are preview-first. Preview reports package metadata, create counts, and conflicting item ids before mutating the current project.
-
-Planr packages are local-first JSON. For encrypted sharing, review the JSON locally and encrypt the file with your team's standard tool, for example:
-
-```bash
-age -o planr-backup.json.age -r <recipient> planr-backup.json
-gpg -c planr-backup.json
-```
-
-Planr does not require a hosted share service for V1.1.