openplanr 1.25.3 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 2.0.0
+### Major Changes
+
+- 622ce31: Move semantic planning and implementation into the active coding agent. This is a
+  breaking CLI change: `planr plan`, `planr spec decompose`, and the model-backed
+  pipeline, estimate, refine, revise, and evidence command roots are retired. The
+  CLI no longer accepts AI-provider configuration or calls model providers.
+  
+  Use the installed Plan, Spec, Ship, and review skills for semantic work, with the
+  current repository context and the host's own models and tools. Existing manual
+  artifact CRUD, document readers, integration commands, rendering, local studios,
+  dashboard, setup, and diagnostics remain available. Existing `planr`,
+  `openplanr`, and `opr` binary names still use the same parser.
+
+### Minor Changes
+
+- 622ce31: Add the portable company-workspace contracts and CLI workflow for public-client
+  sign-in, scoped publication previews, resumable synchronization, review handoffs,
+  typed change proposals, conflict detection, and explicit local application. Keep
+  repository files authoritative and require the hosted service to enforce every
+  organization, project, and artifact permission server-side.
+- 622ce31: Consolidate the portable OpenPlanr product into one reproducible monorepo with
+  explicit package ownership, generated host adapters, preserved compatibility
+  lineages, and isolated packed-package verification. Keep the CLI and pipeline
+  self-contained for consumers without sibling repositories or private workspace
+  dependencies.
+- 622ce31: Add permanent encrypted design reviews with separately entered access tokens,
+  explicit revision publishing, private local owner custody, and synchronized
+  revision-bound feedback. Fix Notes dismissal and unavailable sharing controls.
+- 622ce31: Restore professional Design, Design Loop and Design Review workflows with
+  adaptive consultation, portable host-native skills, and a shared authored design
+  document. Render canvas, interactive prototype and walkthrough views in one
+  review studio with durable feedback, scoped revision recovery, responsive
+  previews and offline exports. Use a standard 1440 × 1024 desktop frame, compact
+  independently collapsible navigation and review rails, and an encrypted company
+  review Share flow. Add an unbounded persisted camera, direct artboard movement,
+  trackpad/Space/middle-button panning, cursor-centered zoom and per-view positions.
+  Keep implementation guidance in compact markers and an external Notes accordion
+  so product artboards remain development-ready interfaces. Open design documents
+  through `planr artifact` and preserve the authored design specification in the
+  separate Plan handoff.
+  
+  Stabilize the mobile shell around keyboard and browser-chrome changes. Use
+  readable touch-sized fields, accessible action targets and a bounded welcome
+  dialog without altering authored product screens or restricting browser zoom.
+- 622ce31: Render sequence diagrams as readable time-ordered conversations with participant
+  headers, lifelines, phases, distinct message rows, annotations, and emphasis.
+  Detect overlapping rendered labels, support sequence Mermaid and Excalidraw
+  round trips, and open verified diagram manifests in the native Diagram
+  studio after rendering. Use one SVG camera with outline/search, fit controls,
+  compact persisted comments, and verified drawing and agent review exports;
+  avoid fixed document frames and nested scrolling.
+- 622ce31: Shorten unified-plugin invocations to `planr:<verb>` across Codex and Claude
+  Code while preserving canonical `planr-*` skill identities and Cursor rules.
+  Migrate managed local installations from the former `openplanr` plugin
+  namespace after the replacement package is installed.
+- 622ce31: Complete the design studio's team review flow with reviewer orientation, adjustable panels, thumbnails, organized feedback, revision comparison, canvas navigation, and a read-only implementation inspector. Add revision-bound owner dispositions and explicit review handoff drafts and approvals. Preserve existing design documents and shared URLs, and package the same deterministic tools for standalone skills and hosted reviews.
+  
+  Bound live previews on touch devices, load the opening screen first, and release older previews while preserving review drafts. Navigation waits for an authenticated destination frame before revealing it; failed previews can be retried. Desktop canvases retain their existing loading behavior.
+
+### Patch Changes
+
+- 6dbc8b8: Use the branded OpenPlanr company API by default so hosted customers can sign in and publish without copying an infrastructure URL. Keep `--api-url` as an optional development and self-hosted override.
+- 528ff85: Make the local planning console easier to operate on real projects: stage dependency graphs by delivery order, contain board scrolling within each status column, present readable inspector metadata with route feedback, and turn sprint records into delivery workspaces that include scope, blockers, and current Operate context.
+- 622ce31: Update the bundled dashboard to React Router 7.18.3, closing the current
+  production security advisories while preserving the existing routing contract.
+- 746e568: Turn completed local Operate reviews into a structured, read-only operating
+  console with distinct decision, action, lens, evidence, outcome, history, and
+  recovery views. Keep the board report available as the durable audit record.
+
 ## 1.25.3
 
 ### Patch Changes

package/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to the OpenPlanr CLI
+
+The `openplanr` package is developed in the
+[OpenPlanr monorepo](https://github.com/openplanr/OpenPlanr). Follow the
+[root contribution guide](https://github.com/openplanr/OpenPlanr/blob/main/CONTRIBUTING.md)
+and [Code of Conduct](https://github.com/openplanr/OpenPlanr/blob/main/CODE_OF_CONDUCT.md).
+
+Clone the full repository and run these commands from its root:
+
+```bash
+npm ci
+npm run generate
+npm run build
+npm run test:focused
+```
+
+Do not treat an installed npm package as a standalone development checkout.
+CLI command registration lives under `packages/cli/src/cli/`; services and
+package tests live under `packages/cli/src/services/` and `packages/cli/tests/`.
+Canonical Protocol, domain, and skill sources live in their owning workspaces.
+Edit those sources before regenerating their compatibility projections.
+
+For a CLI change, run the relevant focused checks, then package tests and lint:
+
+```bash
+npm run test --workspace=openplanr
+npm run lint --workspace=openplanr
+```
+
+The root guide describes command-catalog regeneration, full workspace checks,
+and isolated packed-package verification. Submit a focused pull request with the
+behavior change, regression coverage, and any limitations. Report vulnerabilities
+using the [security policy](https://github.com/openplanr/OpenPlanr/blob/main/SECURITY.md).

package/README.md

@@ -4,27 +4,28 @@
 
 ### Dedicated planning CLI and cross-runtime workflow control plane
 
-**Plan continuously. Operate from evidence. Route feature delivery anywhere.**
+**Plan continuously. Route feature delivery anywhere.**
 Certified first for **Claude Code**, **Cursor**, and **Codex** through Protocol
-v1.0 artifacts plus additive v1.1–v1.4 runtime and operating contracts.
+v1.0 artifacts plus additive runtime contracts.
 
 [![npm version](https://img.shields.io/npm/v/openplanr.svg?style=flat-square&color=cb3837&logo=npm)](https://www.npmjs.com/package/openplanr)
 [![node](https://img.shields.io/node/v/openplanr.svg?style=flat-square&color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/openplanr.svg?style=flat-square&color=blue)](https://github.com/openplanr/OpenPlanr/blob/main/LICENSE)
-[![protocol](https://img.shields.io/badge/protocol-v1.4.0-7c3aed?style=flat-square)](https://github.com/openplanr/planr-pipeline/tree/main/docs/protocol)
-[![runtimes](https://img.shields.io/badge/runtimes-Claude%20Code%20%7C%20Cursor%20%7C%20Codex-f97316?style=flat-square)](https://github.com/openplanr/planr-pipeline/blob/main/docs/compatibility-matrix.md)
+[![protocol](https://img.shields.io/badge/protocol-v1.7.0-7c3aed?style=flat-square)](https://github.com/openplanr/OpenPlanr/tree/main/packages/pipeline/docs/protocol)
+[![runtimes](https://img.shields.io/badge/runtimes-Claude%20Code%20%7C%20Cursor%20%7C%20Codex-f97316?style=flat-square)](https://github.com/openplanr/OpenPlanr/blob/main/packages/pipeline/docs/compatibility-matrix.md)
 
-**[Website](https://openplanr.dev)** · **[Setup guide](docs/CROSS_RUNTIME_SETUP.md)** · **[Operating Board](docs/OPERATING_BOARD.md)** · **[Artifact review](docs/ARTIFACT_REVIEW.md)** · **[Compatibility matrix](https://github.com/openplanr/planr-pipeline/blob/main/docs/compatibility-matrix.md)** · **[Protocol spec](https://github.com/openplanr/planr-pipeline/tree/main/docs/protocol)** · **[CLI reference](docs/CLI.md)**
+**[Website](https://openplanr.dev)** · **[Setup guide](docs/CROSS_RUNTIME_SETUP.md)** · **[Artifact review](docs/ARTIFACT_REVIEW.md)** · **[Compatibility matrix](https://github.com/openplanr/OpenPlanr/blob/main/packages/pipeline/docs/compatibility-matrix.md)** · **[Protocol spec](https://github.com/openplanr/OpenPlanr/tree/main/packages/pipeline/docs/protocol)** · **[CLI reference](docs/CLI.md)**
 
 </div>
 
 ---
 
-OpenPlanr is the standalone planning and project-management CLI. It owns epics,
-features, stories, tasks, specs, sprints, backlog, reports, integrations, and
-artifact lifecycle. `planr-pipeline` is a separate complete PO → Design → Review
-→ DEV → QA workflow with its own feature-local planning phase. The overlap is
-intentional; shared artifacts and provenance make the producer explicit.
+OpenPlanr is the public planning and project-management CLI package. It owns
+epics, features, stories, tasks, specs, sprints, backlog, reports,
+integrations, and artifact lifecycle. The public `planr-pipeline` package owns
+the PO → Design → Review → DEV → QA workflow. Their package boundaries remain
+independent, while their sources and shared contracts now live in the same
+OpenPlanr workspace.
 
 ```bash
 curl -fsSL https://openplanr.dev/install.sh | sh
@@ -34,9 +35,10 @@ cd my-project
 planr setup
 planr doctor
 planr init
-planr pipeline plan auth
 ```
 
+Create a spec locally, then invoke the `planr:plan` skill in your coding host.
+
 No global install is also supported: `npx openplanr@latest setup`. Planning-only
 installations use `--minimal`; the full pipeline is the default.
 
@@ -47,12 +49,9 @@ installations use `--minimal`; the full pipeline is the default.
 AI coding agents are powerful but lack structured planning context. Without a clear plan, they generate code that drifts from requirements, churn on the same problem across sessions, and can't be audited. OpenPlanr fixes this with four properties:
 
 1. **Markdown artifacts in your repo** — plans live next to your code, version-controlled, gittable, gradable. No external SaaS, no DB.
-2. **One contract, every runtime** — Claude Code, Cursor, and Codex consume the same v1.0 planning artifacts while locks and provenance use additive v1.1 contracts and the agent-native Operating Board uses Protocol v1.4.
+2. **One contract, every runtime** — Claude Code, Cursor, and Codex consume the same planning artifacts while locks and provenance retain explicit additive contracts.
 3. **Three planning postures** — agile, quick task, or spec-driven planning, independent from the pipeline's feature-local PO phase.
 4. **Safe runtime migration** — setup previews exact changes, preserves hand-written content, records ownership, backs up exact bytes, and supports rollback.
-5. **Evidence-to-decision operations** — `planr operate` produces cited,
-   reviewable DEV, OWNER, and AGENT routes while preserving human authority and
-   the PLAN→SHIP gate.
 
 ---
 
@@ -64,7 +63,7 @@ AI coding agents are powerful but lack structured planning context. Without a cl
 | **Quick task** | Solo dev, one-off chores, no ceremony | `.planr/quick/QT-NNN-*.md` (a single checklist file) |
 | **Spec-driven** | Handing a feature to an AI agent factory | `.planr/specs/SPEC-NNN-{slug}/{stories,tasks,design}/` |
 
-Pick one per project, mix per task. The spec-driven posture is the bridge to the [planr-pipeline](https://github.com/openplanr/planr-pipeline) — same artifact contract, no conversion adapter.
+Pick one per project, mix per task. The spec-driven posture is the bridge to the [planr-pipeline](https://github.com/openplanr/OpenPlanr/tree/main/packages/pipeline) — same artifact contract, no conversion adapter.
 
 ---
 
@@ -75,11 +74,11 @@ remains project initialization; it is no longer overloaded with user installatio
 
 | Runtime | What gets installed | How the workflow activates |
 |---|---|---|
-| **Claude Code** | Official `openplanr@openplanr` and `planr-pipeline@openplanr` marketplace plugins at compatible versions | Native plugin skills/commands and the packaged headless router |
+| **Claude Code** | Official `planr@openplanr` unified marketplace plugin | Native `/planr:*` skills and packaged role agents |
 | **Cursor** | Portable project rules plus nine generated role files using relative paths | Composer handoff with sequential fallback |
 | **Codex** | User-scope skills; `AGENTS.md` contains only project policy and artifact pointers | Skills, native subagents when available, sequential fallback otherwise |
 
-Same artifacts (`.planr/specs/SPEC-NNN-{slug}/`). Same `.pipeline-shipped` proof markers. Cross-runtime spec portability works out of the box. See the [compatibility matrix](https://github.com/openplanr/planr-pipeline/blob/main/docs/compatibility-matrix.md) for per-capability parity.
+Same artifacts (`.planr/specs/SPEC-NNN-{slug}/`). Same `.pipeline-shipped` proof markers. Cross-runtime spec portability works out of the box. See the [compatibility matrix](https://github.com/openplanr/OpenPlanr/blob/main/packages/pipeline/docs/compatibility-matrix.md) for per-capability parity.
 
 ---
 
@@ -102,20 +101,70 @@ Claude Code is selected, confirmed setup also refreshes the official
 OpenPlanr marketplace and installs or updates its compatible plugins. Restart
 Claude Code when setup reports that runtime packages changed.
 
+### Run an Operate cycle with Codex
+
+Full Codex setup installs one globally owned, digest-verified bundle containing
+every canonical `planr-*` skill in the Protocol registry. The Operate set is
+`planr-operate` plus the seven
+`planr-{ceo,cto,cpo,cmo,coo,challenger,chair}-review` executors. Setup
+copies every manifest-owned asset in each skill tree; `planr doctor --strict
+--json` checks the installed files and their declared CLI requirements.
+
+Invoke `$planr-operate` directly for a local seven-lens review. It infers a
+current-snapshot periodic review when the request is clear, asks one native
+question only when a consequential choice is genuinely ambiguous, and returns a
+concise board report with decisions, actions, risks, coverage, and issues.
+
+The note checker is optional editing help. It reports bounded structural
+diagnostics, but a missing or imperfect lens does not discard the useful review
+or create a workflow gate:
+
+```bash
+planr operate validate-note <note.md> --profile advisor|challenger|chair|board-report --contract-version 2.0.0 --json
+```
+
+Use `--contract-version auto` (the default) to detect current v2 notes and
+historical v1 Markdown notes by declaration or structure.
+
+The durable Operate runtime is a separate stateful interface. Discover its exact
+registered domain identity before starting a durable Cycle; a domain version is
+not the Protocol version and is never guessed:
+
+```bash
+planr operate domains --json
+```
+
+Issued durable assignments use the packet workflow below. The returned
+`resultPath` is the file to author; no base64 or private runtime-store reads are
+required.
+
+```bash
+planr operate assignment prepare <assignmentId> --actor <agentId> --runtime codex --json
+planr operate assignment validate <packetId> --content-file <resultPath> --json
+planr operate assignment submit <packetId> --content-file <resultPath> --json
+```
+
+If setup, domain discovery, or a packet command fails, run
+`planr doctor --strict --json`. Re-run `planr setup` to repair only known owned
+skill bytes; modified or unknown files are preserved and reported as conflicts.
+Use `planr upgrade status`, then the explicit `planr upgrade apply` command when
+doctor reports an incompatible installed CLI. See the
+[setup and troubleshooting guide](docs/CROSS_RUNTIME_SETUP.md)
+and [CLI reference](docs/CLI.md#planr-operate).
+
 ### Initialise a project
 
 ```bash
 cd my-project
 planr init
-# Interactive: pick AI provider, pick coding agent, generate rules → done
+# Creates deterministic project-local planning storage
 ```
 
 Non-interactive variants:
 
 ```bash
-planr init --yes                       # accept all defaults (AI on, all rules)
-planr init --no-ai --yes               # skip AI provider setup
-planr init --no-pipeline-rules --yes   # agile rules only (skip pipeline workflow)
+planr init --name "My project"          # create deterministic project storage
+planr setup --dry-run                  # preview host adapter installation
 ```
 
 ### Pick a posture and start
@@ -127,8 +176,7 @@ planr epic create
 planr feature create --epic EPIC-001
 planr story create --feature FEAT-001
 planr task create --feature FEAT-001
-# Or one-shot:
-planr plan --epic EPIC-001
+# Use the planr:plan host skill when semantic decomposition is needed.
 ```
 
 **Quick task:**
@@ -142,90 +190,64 @@ planr quick create "add OAuth login"
 ```bash
 planr spec create "Auth flow" --slug auth
 planr spec shape SPEC-001              # 4 questions, no $EDITOR
-planr pipeline plan auth
-# Human review is mandatory before the separate SHIP invocation:
-planr pipeline ship auth
+planr spec promote SPEC-001            # validate and print the host handoff
 ```
 
+In Claude Code invoke `/planr:plan`; in Codex invoke `$planr:plan`. After
+reviewing the plan, invoke the matching `planr:ship` skill explicitly.
+
 ### Review and privately share any HTML artifact
 
 ```bash
 planr artifact ./artifact.html
 # Add pins, threads, and an Approve or Request changes decision.
 
-planr artifact share ./artifact.html --no-open # live encrypted room (default)
+planr artifact share ./artifact.html --secret-output ./room.private.json --no-open # live encrypted room (default)
 planr artifact share ./artifact.html --snapshot # explicit immutable snapshot
 planr artifact open ./artifact.html --presentation canvas # optional spatial view
 planr artifact import "<returned-review-url>"
 ```
 
 Generic artifacts render edge-to-edge in the headless document presentation;
-design boards retain the zoomable canvas. Complete local HTML/CSS/JavaScript is
+design boards retain the zoomable canvas. Authored `design-document.json` files
+open the Design studio through `planr artifact open design-document.json`, with
+Canvas, Prototype and Walkthrough views of the same source, responsive frames,
+variant selection and persistent pinned feedback. The design skills also bundle
+the same local utilities for installations without a global CLI. Browser
+readiness and visual verification are reported separately; a design without
+browser evidence remains unverified. Complete local HTML/CSS/JavaScript is
 bundled into an opaque-origin sandbox, so private review is not standalone site
 hosting.
 
 Sharing is explicit. A new generic share creates one stable encrypted live room:
-anyone with its review URL can comment, while the creator receives a separate
-private manage URL to pause comments, set the final verdict, or delete the
-room. Immutable fragments and encrypted short links remain available with
-`--snapshot`; the service stores ciphertext only.
+anyone with its review URL can comment. Owner decisions require a distinct
+owner-verdict URL plus the matching private P-256 signer in the mode-0600
+`--secret-output` file. A third management URL can pause/reopen comments or
+delete the room, but cannot set a verdict. Before any room request, the CLI
+prepares one room identity and durably writes its exact three URLs plus owner
+signer to the private recovery file. A lost response retries that same prepared
+creation once without rotating secrets or creating a second room. A definite
+rejection revokes the file; an ambiguous outcome preserves it and reports a
+bounded recovery error. Immutable fragments and encrypted short links remain
+available with `--snapshot`; the service never receives the private signer.
 See the [artifact review and privacy guide](docs/ARTIFACT_REVIEW.md).
 
-### Run an operating cycle
-
-```bash
-planr operate inspect     # no initialization or credentials required
-planr operate demo        # deterministic, credential-free, no project writes
-$planr-operate            # Codex: initialize if needed, research, advise, synthesize
-# /planr-pipeline:operate # Claude Code equivalent
-planr operate report --lens cto
-planr operate drafts list
-```
-
-Operating Board governs direction; it never deploys, publishes, spends,
-contacts customers, or invokes SHIP. The selected runtime researches the
-workspace and runs CEO, CTO, CPO, CMO, COO, and Chair agents; OpenPlanr validates
-their citations and creates only reversible, unapproved proposal drafts.
-Planning-only installations retain `operate --help`, `inspect`, and `demo`;
-commands that require Protocol v1.4 return `E_PIPELINE_NOT_INSTALLED` with the
-full-install recovery command. See the
-[Operating Board guide](docs/OPERATING_BOARD.md).
-
 ---
 
 ## Commands
 
-### Operating Board
-
-| Command | Description |
-|---|---|
-| `planr operate inspect` | Inspect workspace, runtime, evidence, and package readiness without initialization |
-| `planr operate demo` | Produce a real cited brief from sanitized deterministic fixtures |
-| `planr operate` | Expose the agent-native initialize/research/advisor/Chair/report workflow |
-| `planr operate context show\|refresh\|review` | Inspect or refresh cited research-first context |
-| `planr operate run` | Start or resume one runtime-bound cycle and stop at reviewable |
-| `planr operate review` / `brief` / `status` | Review the concise brief and canonical lifecycle state |
-| `planr operate report [cycle]` | Print CEO, CTO, CPO, CMO, COO, and Chair output as Markdown or strict JSON with exact planning conversion commands |
-| `planr operate drafts list\|show\|approve\|discard` | Govern canonical Quick Task, Spec, Epic, decision, and agent proposal drafts |
-| `planr operate findings accept <id>` | Record governance without applying a route |
-| `planr operate routes apply <id>` | Apply one confirmed, digest-bound local route; Pipeline-PO DEV routes may return `awaiting-plan` and an exact native PLAN command |
-| `planr operate decisions decide <id>` | Record an owner decision |
-| `planr operate gaps answer <id>` | Supply missing evidence or charter context |
-| `planr operate gaps verify <id> --evidence-ref <id>` | Verify an answered gap against explicit evidence before closing it |
-| `planr operate run --review-only` | Reconcile verified shipment proofs and due outcome observations without evidence collection or model calls |
-| `planr operate cache status` / `purge` | Inspect or purge machine-local evidence |
-| `planr operate integrity status` / `enable` | Inspect integrity or enable externally keyed signed checkpoints |
-
 ### Spec-driven mode
 
-Third planning posture — designed for handing features to AI coding agents. Specs decompose into User Stories and Tasks with explicit file Create / Modify / Preserve lists, `Type: UI | Tech`, agent assignment, and DoD with build / test commands. Schema matches [OpenPlanr Protocol v1.0.0](https://github.com/openplanr/planr-pipeline/tree/main/docs/protocol); canonical JSON Schemas for this cleanup cycle live in `openplanr/planr-pipeline` under `schemas/v1.0.0/`.
+Third planning posture for handing reviewed features to coding hosts. Specs contain
+User Stories and Tasks with explicit Create / Modify / Preserve lists, `Type: UI |
+Tech`, ownership, and build/test completion criteria. Canonical schemas live in
+[`packages/protocol`](https://github.com/openplanr/OpenPlanr/tree/main/packages/protocol).
 
 | Command | Description |
 |---|---|
 | `planr spec init` | Activate spec-driven mode (creates `.planr/specs/`) |
 | `planr spec create "Auth flow"` | Create a self-contained `SPEC-NNN-{slug}/` directory |
 | `planr spec shape <id>` | Interactive 4-question authoring (Context, Functional Reqs, Business Rules, Acceptance) |
-| `planr spec decompose <id>` | AI-driven decomposition into US + Tasks |
 | `planr spec sync [<id>]` | Validate integrity (orphans, missing `specId`, schema drift); auto-fixes safe issues |
 | `planr spec list` | List all specs with status + decomposition counts |
 | `planr spec show <id>` | Print a spec + its US/Task tree |
@@ -241,19 +263,17 @@ Third planning posture — designed for handing features to AI coding agents. Sp
 | `planr epic create` | Create a new epic (supports `--file <path>` for PRDs) |
 | `planr feature create --epic <ID>` | Create features from an epic |
 | `planr story create --feature <ID>` | Create user stories from a feature |
-| `planr story create --epic <ID>` | Batch-generate stories for all features under an epic |
-| `planr task create --story <ID>` | AI task list from one story |
-| `planr task create --feature <ID>` | AI task list from all stories under a feature |
-| `planr plan` | Full automated flow: Epic → Features → Stories → Tasks |
+| `planr task create --story <ID>` | Create a task from flags or deterministic JSON for one story |
+| `planr task create --feature <ID>` | Create a task from flags or deterministic JSON for one feature |
 | `planr epic list` / `planr feature list` / `planr story list` / `planr task list` | List artifacts |
 
 ### Quick tasks & templates
 
 | Command | Description |
 |---|---|
-| `planr quick create "description"` | AI-generated standalone task list |
+| `planr quick create "description"` | Create a standalone task list |
 | `planr quick create --file spec.md` | Task list from a PRD or spec file |
-| `planr quick promote <ID> --story US-001` | Move into agile hierarchy |
+| `planr quick show <ID>` / `planr quick update <ID>` | Inspect or update a quick task |
 | `planr template list` | List built-in and custom templates |
 | `planr template use rest-endpoint --title "User API"` | Generate tasks from a template |
 | `planr template save TASK-001 --name my-pattern` | Save existing tasks as template |
@@ -265,18 +285,14 @@ Built-in templates: `rest-endpoint`, `react-component`, `database-migration`, `a
 | Command | Description |
 |---|---|
 | `planr backlog add "desc" --priority high --tag bug` | Capture a backlog item |
-| `planr backlog list` / `prioritize` / `promote <id>` / `close <id>` | Manage backlog |
-| `planr sprint create --name "Sprint 1" --duration 2w` | Create a time-boxed sprint |
-| `planr sprint add TASK-001 QT-001` | Assign tasks (or `--auto` for AI) |
-| `planr sprint status` / `list` / `close` / `history` | Track sprint progress + velocity |
+| `planr backlog list` / `show <id>` / `update <id>` | Inspect or update backlog items |
+| `planr sprint create "Sprint 1" --duration 2w` | Create a time-boxed sprint |
+| `planr sprint list` / `show <id>` / `update <id>` | Inspect or update sprints |
 
 ### Planning tools
 
 | Command | Description |
 |---|---|
-| `planr estimate <ID>` | AI effort estimation (story points, hours, complexity) |
-| `planr refine <ID>` | AI-powered review and prose polish |
-| `planr revise <ID>` | AI-driven *alignment* of planning artifacts with codebase (with diff preview) |
 | `planr search <query>` | Full-text search across all artifacts |
 | `planr sync` | Validate and fix cross-references |
 | `planr status [scope]` | Whole-project delivery report — status + GitHub/Linear cross-ref + outstanding work (`--md` / `--json` / `--github` / `--linear`) |
@@ -290,7 +306,9 @@ Built-in templates: `rest-endpoint`, `react-component`, `database-migration`, `a
 | `planr rules generate --target all --scope all` | Everything for every runtime |
 | `planr rules generate --dry-run` | Preview without writing |
 
-`--scope agile` (default) writes the agile workflow rules. `--scope pipeline` writes the rule files that drive the [planr-pipeline](https://github.com/openplanr/planr-pipeline) two-phase spec-driven flow on the chosen runtime. `--scope all` produces both. `planr init` auto-runs `--scope all` by default — opt out with `planr init --no-pipeline-rules`.
+`--scope agile` writes agile workflow rules. `--scope pipeline` writes the
+project policy for the [planr-pipeline](https://github.com/openplanr/OpenPlanr/tree/main/packages/pipeline)
+two-phase flow. `--scope all` produces both.
 
 ### Integrations
 
@@ -322,10 +340,9 @@ Output: Markdown + HTML written to `.planr/reports/`. `--push slack` posts via w
 | `planr setup` | Detect and install runtime adapters with preview, backup, and locking |
 | `planr runtime detect/list/install/update/remove/rollback/doctor` | Manage adapter lifecycle |
 | `planr doctor [--strict] [--fix] [--json]` | Unified ecosystem health checks |
-| `planr pipeline <action>` | Route PLAN, Design, SHIP, status, dashboard, sync, or doctor |
 | `planr init` | Initialise project (creates `.planr/`, generates rules for all runtimes by default) |
 | `planr config show` | Display current configuration + spec-driven readiness |
-| `planr config set-provider` / `set-key` / `set-model` / `set-agent` | Manage AI provider settings |
+| `planr config set-agent` / `set-upgrade-policy` | Manage deterministic host and upgrade preferences |
 | `planr checklist show/toggle/reset` | Agile development checklist |
 
 See [docs/CLI.md](docs/CLI.md) for the full reference with every flag.
@@ -362,25 +379,6 @@ my-project/
 
 ---
 
-## Architecture decision: `planr revise`
-
-Most planning tools let plans drift from the codebase. `planr revise` actively rewrites planning artifacts so they match reality, with a four-layer safety pipeline:
-
-1. **Clean-tree gate** — git working tree must be clean (`--allow-dirty` to override)
-2. **Agent decision** — zod-validated `revise` / `skip` / `flag` per artifact
-3. **Evidence verification** — agent must cite typed, verifiable evidence (file existence, grep matches, sibling artifacts); unverifiable citations are dropped
-4. **Diff preview + confirmation** — per-artifact `[a]pply / [s]kip / [e]dit / [d]iff / [q]uit`; writes are atomic with sidecar backups
-
-```bash
-planr revise EPIC-003 --cascade           # interactive
-planr revise --all --dry-run              # preview every revision
-planr revise EPIC-003 --cascade --dry-run --audit ./revise.json   # CI mode
-```
-
-Full design: [.planr/EPIC-REVISE-COMMAND.md](.planr/EPIC-REVISE-COMMAND.md).
-
----
-
 ## Configuration
 
 `.planr/config.json` is created by `planr init`:
@@ -407,38 +405,43 @@ Full design: [.planr/EPIC-REVISE-COMMAND.md](.planr/EPIC-REVISE-COMMAND.md).
 
 ## Ecosystem
 
-OpenPlanr is one of four components:
+The source ecosystem is consolidated under the OpenPlanr npm workspace:
 
-| Component | Role | Repo |
-|---|---|---|
-| **`planr` CLI** | Authoring surface — generates `.planr/` artifacts and runtime rule files | this repo |
-| **`planr-pipeline`** | Portable PO → Design → Review → DEV → QA engine with nine canonical roles and runtime adapters | [openplanr/planr-pipeline](https://github.com/openplanr/planr-pipeline) |
-| **`openplanr` skill** | Routing playbook — teaches Claude when to use which surface | [openplanr/skills](https://github.com/openplanr/skills) |
-| **`openplanr/marketplace`** | Distribution — Claude Code plugin registry | [openplanr/marketplace](https://github.com/openplanr/marketplace) |
+| Workspace path | Role |
+|---|---|
+| `packages/cli` | Public `openplanr` authoring and setup package |
+| `packages/pipeline` | Public feature-delivery engine and compatibility projections |
+| `skills/` and `agents/` | Canonical workflow and role sources |
+| `packages/protocol` | Schemas, registries, and public contracts |
+| `adapters/` | Generated Claude Code, Codex, and Cursor projections |
+| `.claude-plugin/` | Generated workspace marketplace metadata |
 
-planr CLI is the only piece you need to install for Cursor and Codex. Add the marketplace + pipeline plugin for the full Claude Code experience.
+`openplanr-web` remains an independently deployed external repository. Package
+publication and hosted deployment are separate from local workspace
+development.
 
 ---
 
 ## Development
 
 ```bash
-git clone https://github.com/openplanr/OpenPlanr.git
-cd OpenPlanr
-npm install
-
-# Run from source
-npx tsx src/cli/index.ts init
-
-# Build / test / lint
+cd /path/to/OpenPlanr
+npm ci
+npm run generate
 npm run build
-npm test
-npx biome check src/ tests/
+npm run test:focused
+npm run lint
 
-# Link globally for development
-npm install -g .
+# Optional: expose the local public binaries on PATH
+npm link --workspace=planr-pipeline
+npm link --workspace=openplanr
 ```
 
+Use Node 20 or 22; no specific Node version manager is required. Run workspace
+commands from the repository root so npm uses the single root lockfile. See the
+root README for link detection, Codex adapter refresh, and a first-project
+walkthrough.
+
 ---
 
 ## Contributing
@@ -456,3 +459,23 @@ Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
 
 [MIT](LICENSE)
+
+### Design review handoffs
+
+`planr artifact handoff <design-document.json>` prepares a deterministic review
+handoff beside the design specification. Refine the proposed text in the active
+Claude/Codex session, then review and approve it in the attached studio. This
+command never invokes Plan, Ship, or publication. Approved handoffs are bound to
+the exact design and feedback snapshot; subsequent changes require a new review.
+
+Verified diagram manifests open the native Diagram studio:
+
+```sh
+planr artifact diagrams/application-flow/application-flow.manifest.json
+```
+
+The drawing uses one SVG canvas with an outline, search, pan, pointer-centered
+zoom, Fit, Fit width, and presentation mode. Comments stay attached to diagram
+coordinates. Export offers the verified drawing/source files and a JSON review
+handoff containing timestamps, source identity, scene dimensions, and pins.
+The diagram studio is local; existing hosted design boards are unchanged.

package/dist/cli/commands/artifact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/artifact.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwYzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwD9D"}
+{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/artifact.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkmBzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+F9D"}