openplanr 3.3.0 → 3.5.0

package/lib/host-packages/openai/openplanr/skills/design/references/design-system.md

@@ -54,11 +54,11 @@ while authoring:
 - at most two families and three weights each; one variable file can cover a
   family's weights.
 
-Snapshot with the bundled helper, run from the skill directory (see
+Snapshot with the design CLI, run from the project directory (see
 [utilities.md](utilities.md)):
 
 ```sh
-node scripts/design.mjs fonts fetch --family "Inter:400,600" --family "Source Serif 4:400" --dest <design>/source/assets/fonts
+openplanr design fonts fetch --family "Inter:400,600" --family "Source Serif 4:400" --dest <design>/source/assets/fonts
 ```
 
 It is the one command to ask approval for. A host that allowlists network access by

package/lib/host-packages/openai/openplanr/skills/design/references/generation.md

@@ -34,12 +34,12 @@ incidental array positions or rendered CSS selectors.
 
 Author real screen content with useful labels, plausible data and complete states.
 Make the primary journey navigable and meaningful controls functional. Use local
-HTML/CSS/JavaScript and assets supported by the bundled utility; do not require a
+HTML/CSS/JavaScript and assets supported by the design utilities; do not require a
 build server, package installation, remote modules or a development environment to
 open the studio. Third-party assets retain their license/attribution where needed.
 Use classic browser scripts with local event handlers. If adapting an existing
-module-based component, compile its local preview before packaging; the portable
-utility does not install dependencies or compile modules. Use local image `src`
+module-based component, compile its local preview before packaging; the design
+utilities do not install dependencies or compile modules. Use local image `src`
 with responsive CSS. Forms validate and run local handlers; omit navigation
 actions and targets. Cross-screen actions can use `data-design-navigate` with the
 stable target screen ID.

package/lib/host-packages/openai/openplanr/skills/design/references/hosted-canvas.md

@@ -14,6 +14,8 @@ there. Hosts without one use the local studio unchanged.
 - Use the local studio when the user asks for it, asks for an encrypted company
   review or share link, or the canvas cannot be created or published. Name the
   reason when it is a failure, keep any work already written and continue locally.
+  The local studio needs a ready runtime; without one, end at the matching stop in
+  [utilities.md](utilities.md).
 - Before creating the canvas, say in one line that the design is published to
   the host's service and stays private to the user until they share it.
 
@@ -57,6 +59,7 @@ Name each screen's board file in the screen inventory. This path writes no
 specification and board sources are Plan's inputs.
 
 Return the direction, the canvas link, the specification and board-source paths,
-and the verification status. Review happens in the canvas's own comments; apply
-revisions with the Design type's revising steps and keep the specification in
-step. OpenPlanr Studio cannot open a hosted canvas yet, so do not offer it.
+and the verification status. Review happens in the canvas's own comments: read
+them with the host's artifact comments tool, apply revisions with the Design
+type's revising steps, and keep the specification in step. OpenPlanr Studio
+cannot open a hosted canvas yet, so do not offer it.

package/lib/host-packages/openai/openplanr/skills/design/references/review.md

@@ -9,10 +9,10 @@ a remix; keep their origin distinct and do not invent board votes.
 For "this button" or "this screen", read the live local viewer context:
 
 ```sh
-node scripts/design.mjs view-context <design-document.json> --json
+openplanr design view-context <design-document.json> --json
 ```
 
-The utility reads `.design/view-context.json` beside the document and rejects a
+The command reads `.design/view-context.json` beside the document and rejects a
 revision that differs from the current render. Ignore context whose `updatedAt`
 is older than the user's request; pass `--request-time <ISO-timestamp>` to have
 the reader enforce that check. Missing, invalid or stale context returns
@@ -85,7 +85,7 @@ decision. Read project-local shared feedback alongside the ordinary pin ledger.
 
 Creating a share or publishing an update requires an explicit user request.
 Rendering a local revision does not update the remote review. After the user asks
-to publish, use the studio's Publish update action or the bundled utility; verify
+to publish, use the studio's Publish update action or `openplanr artifact publish`; verify
 the returned published revision. The URL stays stable and recipients choose when
 to load a new revision. Earlier pins remain stale until deliberately addressed.
 
@@ -96,9 +96,9 @@ specifications, project files, URLs, logs, or ordinary command output.
 
 ## Agent-friendly review exports
 
-Use **Export reviews** in the Review sidebar, or the bundled feedback export
-utility, for Markdown or JSON grouped by original revision, screen, direction and
-responsive frame. Preserve reviewer IDs, exact quotations, replies and timestamps.
+Use **Export reviews** in the Review sidebar, or
+`openplanr artifact feedback --action export`, for Markdown or JSON grouped by
+original revision, screen, direction and responsive frame. Preserve reviewer IDs, exact quotations, replies and timestamps.
 Read the completeness flag; wait for older pages or retry when disconnected before
 treating an export as the full review history. Unsaved text in a composer is a draft,
 not submitted feedback.

package/lib/host-packages/openai/openplanr/skills/design/references/team-review.md

@@ -101,10 +101,9 @@ has been rendered and checked.
 
 ## Prepare and refine the handoff
 
-When requested, run `openplanr artifact handoff <design-document.json>` or the bundled
-`node scripts/design.mjs handoff <design-document.json>` utility. Both prepare a
-factual draft from the recorded review; neither calls an AI model or starts Plan.
-Read the utility's `--help` for the installed edit and approval interface.
+When requested, run `openplanr artifact handoff <design-document.json>`. It
+prepares a factual draft from the recorded review; it does not call an AI model or
+start Plan. Read its `--help` for the installed edit and approval interface.
 
 Refine the draft in this active host session. Preserve comment quotations,
 authorship, source revision and references. Separate accepted changes from

package/lib/host-packages/openai/openplanr/skills/design/references/utilities.md

@@ -1,24 +1,71 @@
-# Bundled design utilities
+# Design utilities
 
-Run the linked design helper from the skill entrypoint relative to the skill's
-directory. It contains deterministic operations and all required assets. It needs
-Node.js 22.13 or later, with no global CLI or provider credentials. Only `fonts fetch`
-downloads anything, and only when run; nothing is fetched when a design opens.
-Use `--help` to inspect the installed command interface before writing documents
-or invoking operations; the installed contract is authoritative.
+Design operations run in the `openplanr` CLI. They are deterministic, need Node.js
+22.13 or later and no provider credentials. Only `fonts fetch` downloads anything,
+and only when run; nothing is fetched when a design opens. Use `--help` on a
+command to inspect the installed interface before writing documents or invoking
+operations; the installed contract is authoritative.
+
+## Check the design runtime
+
+Run this once, before consultation, and check whether the host's artifact tool
+offers a design quickstart or a Design artifact type:
 
 ```sh
-node scripts/design.mjs inspect <design-document.json> --json
-node scripts/design.mjs validate <design-document.json> --json
-node scripts/design.mjs render <design-document.json> --json
-node scripts/design.mjs open <design-document.json> --view canvas --no-open --json
-node scripts/design.mjs feedback <design-document.json> --action inspect --json
-node scripts/design.mjs view-context <design-document.json> --json
-node scripts/design.mjs studio <design-document.json> --action status --json
-node scripts/design.mjs studio <design-document.json> --action stop --json
-node scripts/design.mjs fonts fetch --family "<Name>:<weights>" [--family ...] --dest <design>/source/assets/fonts --json
+openplanr design capabilities --json
 ```
 
+These skills need design contract 1. Treat a successful
+`openplanr design capabilities --json` as proof the runtime is ready. Never locate
+or import the OpenPlanr workflow package, inspect `node_modules`, or call internal
+runtime modules. Use the `openplanr` on `PATH`; never search for another one or
+for bundled design scripts. A failed probe means the matching stop below.
+
+| Probe result | Runtime | Next action |
+|---|---|---|
+| `ok: true` and `supported.min` ≤ 1 ≤ `supported.max` | Ready | Use the commands below. |
+| `openplanr` not found | Stop 1: no CLI | `npm install -g openplanr` |
+| `unknown command 'design'`, `E_DESIGN_RUNTIME_UNSUPPORTED`, or a `supported` range without 1 | Stop 2: CLI too old | `npm install -g openplanr@latest` |
+| `ok: false` with `E_DESIGN_RUNTIME_MISSING` and `pipeline: null` | Stop 3: CLI without its workflow package | `npm install -g openplanr`, run without `--omit=optional` |
+
+A design on the hosted canvas needs no CLI. At a stop, consultation and
+authoring still happen: author `design-document.json`, its sources and
+`design-spec.md`, mark them **unverified**, and say that no studio was rendered or
+checked. End with every next action that applies, each one the user can run: the
+stop's command, and the host action below. On Claude Code without a Design
+artifact type, that is the command and the canvas actions. Then ask the user to
+run the skill again.
+
+| Host | Notes |
+|---|---|
+| Claude Code | Design builds on the hosted canvas when the artifact tool offers a Design type. When it does not, also name the canvas actions: sign in with `/login` on a claude.ai Pro, Max, Ultra, Team or Enterprise plan; or, when artifacts are turned off, re-enable them in `/config`. An API key or gateway token means no claude.ai login: name `/login` with a claude.ai plan, or the CLI. On Bedrock, Google Cloud or Foundry, or in an organisation with CMEK, HIPAA or Zero Data Retention, the canvas is unavailable and the CLI is the path. |
+| Codex | The stop's command. `openplanr setup` installs the workflow package beside the skills, but `PATH` can resolve a different `openplanr`; `which openplanr` shows the one that runs. Codex's default `workspace-write` sandbox stops the studio: `design open` fails with `listen EPERM`. Tell the user to run `openplanr design open <design-document.json>` in their own terminal, or to restart Codex with `-c sandbox_workspace_write.network_access=true -c 'sandbox_workspace_write.writable_roots=["<absolute path of ~/.planr>"]'` (use `PLANR_HOME` instead when it is set). That setting also lets commands reach the network. |
+| Cursor | The stop's command. `openplanr setup` installs the workflow package beside the skills, but `PATH` can resolve a different `openplanr`; `which openplanr` shows the one that runs. |
+| ChatGPT | Without a local shell, take stop 1: deliver the unverified sources and specification, and name `npm install -g openplanr` for a coding agent with a shell. |
+
+## Commands
+
+Run these from the project directory. Paths resolve against it.
+
+```sh
+openplanr design inspect <design-document.json> --json
+openplanr design validate <design-document.json> --json
+openplanr design render <design-document.json> --json
+openplanr design open <design-document.json> --view canvas --no-open --json
+openplanr design view-context <design-document.json> --json
+openplanr design verify <design-document.json> --report <browser-report.json> --json
+openplanr design export <design-document.json> --view canvas --format html --output <path> --json
+openplanr design studio status <design-document.json> --json
+openplanr design studio stop <design-document.json> --json
+openplanr design fonts fetch --family "<Name>:<weights>" [--family ...] --dest <design>/source/assets/fonts --json
+openplanr artifact feedback <design-document.json> --action inspect --json
+```
+
+`render` reads the specification at the path in [handoff.md](handoff.md), so write
+`design-spec.md` before the first render. The CLI prints `<path>` in place of
+absolute paths, so an `ENOENT` names no file: check that `design-spec.md` and
+every source the document names exist before suspecting the CLI.
+
 `fonts fetch` snapshots at most two OFL or Apache families, three weights each, as
 Latin `woff2` files with their license files and a local `fonts.css`. It needs network
 access; ask the user to approve that one command. A host that allowlists domains needs
@@ -28,9 +75,9 @@ access; ask the user to approve that one command. A host that allowlists domains
 [design-system.md](design-system.md) for the fallback.
 
 Use `--view prototype` or `--view walkthrough` to select the initial presentation.
-When an `openplanr` CLI is available, prefer its public `openplanr artifact` route for
-opening the document; otherwise use this bundled script. Both compose the same
-design and artifact runtime, preserving feedback and view behavior.
+`design open` keeps the studio running until it is stopped, so run it in the
+background. `openplanr artifact open <design-document.json>` opens the same studio,
+preserving feedback and view behavior.
 
 `view-context` returns validated live viewer data, or `{ viewContext: null, reason }`
 when unavailable or stale. Use `--request-time <ISO-timestamp>` to reject context
@@ -49,12 +96,12 @@ Opening a completed design reuses its healthy local service and returns a short
 Studio; a service hosting several designs offers a selection page. Keep the
 returned URL instead of constructing one from export paths.
 
-Use `studio --action status` to find the healthy service for this design. Its
+Use `design studio status` to find the healthy service for this design. Its
 `status: running` reports service availability; `browserStatus` reports observed
 preview loading separately, and `verification` reports actual saved checks.
 Startup alone does not mean a design is ready or verified.
 
-Use `studio --action stop` to authenticate the exact owned live instance and drain
+Use `design studio stop` to authenticate the exact owned live instance and drain
 pending saves; it does not signal a process by PID. `status: stopping` means
 shutdown was accepted. Run status again to confirm it stopped. Feedback, ratings
 and arrangement remain in their canonical stores and survive reopening.
@@ -63,7 +110,7 @@ A healthy service with different settings, an older runtime, or an unvalidated
 session must be stopped before reopening. When its launcher record is missing,
 stop can recover the sole authenticated owner for this design. If several owned
 services remain, inspect status and choose one explicitly with
-`studio <design-document.json> --action stop --instance-id <id>`. An instance from
+`openplanr design studio stop <design-document.json> --instance-id <id>`. An instance from
 another project or state directory is rejected. Hosted shares continue independently.
 
 ## Import downloaded feedback
@@ -71,7 +118,7 @@ another project or state directory is rejected. Hosted shares continue independe
 Explicitly reconcile downloaded feedback with the canonical local ledger:
 
 ```sh
-node scripts/design.mjs feedback <design-document.json> --action import --input <downloaded-review.json> --revision <current-render-revision> --json
+openplanr artifact feedback <design-document.json> --action import --input <downloaded-review.json> --revision <current-render-revision> --json
 ```
 
 Read `feedback --action inspect` first and pass its current `revision` internally;
@@ -108,12 +155,11 @@ The design remains accessible when the local machine is offline. Owner authority
 saves automatically in a protected user-level file outside the project; recovery
 export is optional. Only copy the reviewer token through the explicit Share controls.
 
-The bundled utility supports `share`, `publish`, and `sync` with the same design
-document argument. `share` creates or retries a review, `publish` sends an explicitly
-requested new revision to the existing URL, and `sync` retrieves authenticated
-feedback. Run `--help` for access-management and recovery options. The public CLI
-equivalents are `openplanr artifact share`, `openplanr artifact publish`, and
-`openplanr artifact sync`. No global CLI is required for the bundled helper.
+Sharing runs in the `openplanr` CLI, which holds the owner keys:
+`openplanr artifact share`, `publish`, `sync`, `status`, `manage`, `feedback` and
+`handoff`, and the studio's Share dialog. `share` creates or retries a review,
+`publish` sends an explicitly requested new revision to the existing URL, and
+`sync` retrieves authenticated feedback.
 
 Retention is until the owner revokes or deletes the review, while the service is
 maintained. The owner can pause comments and rotate access tokens. Rotation blocks
@@ -123,9 +169,9 @@ saved operation and use its retry path. Report service unavailability explicitly
 
 ## Team review and handoff
 
-`openplanr artifact handoff <design-document.json>` and the bundled
-`node scripts/design.mjs handoff <design-document.json>` prepare or refresh a
-factual review handoff. Use `--json` for structured results and consult `--help`
+`openplanr artifact handoff <design-document.json>` prepares or refreshes a
+factual review handoff, and `openplanr design handoff <design-document.json>`
+inspects it. Use `--json` for structured results and consult `--help`
 for inspection, update and approval actions. Follow [team-review.md](team-review.md)
 for active-agent refinement and owner approval. These deterministic operations do
 not call a provider, publish a design or start Plan/Ship.

package/lib/host-packages/openai/openplanr/skills/design-loop/SKILL.md

@@ -9,6 +9,16 @@ license: MIT
 Help the user choose and refine a direction through a real comparison board.
 Generate three alternatives by default; honor an explicit requested count.
 
+Before consultation, run `openplanr design capabilities --json` and read the probe
+and host tables in [utilities.md](references/utilities.md). Treat a successful
+`openplanr design capabilities --json` as proof the runtime is ready. Never locate
+or import the OpenPlanr workflow package, inspect `node_modules`, or call internal
+runtime modules. The comparison board has no hosted canvas, so the host's artifact
+tool does not replace it. At a stop, still consult and author the shared document,
+every direction's sources and the specification, mark them **unverified** and
+awaiting a board, and end with the stop's next action. On Claude Code, also offer
+`/planr:design` to develop one direction on the hosted canvas.
+
 1. Read [discovery.md](references/discovery.md) and
    [design-system.md](references/design-system.md). Inspect the brief, existing
    product, assets, reference screens, design document and previous preferences.
@@ -25,11 +35,9 @@ Generate three alternatives by default; honor an explicit requested count.
    sibling `review-context.json` before rendering. Ground its welcome purpose and
    up to three consequential review questions in the supplied brief and the
    directions' actual tradeoffs, without implying a winner or inventing requirements.
-3. Build the comparison from those sources using
-   [utilities.md](references/utilities.md) and
-   [scripts/design.mjs](scripts/design.mjs), or the public `openplanr artifact` route
-   when the CLI is present. All variants use the same screen identities and frame
-   coverage. Show failures explicitly without inventing results or discarding
+3. Build the comparison from those sources with the `openplanr design` commands
+   in [utilities.md](references/utilities.md). All variants use the same screen
+   identities and frame coverage. Show failures explicitly without inventing results or discarding
    completed variants. Canvas, Prototype and Walkthrough share one document and
    can be switched without regenerating content.
 4. Inspect rendered screenshots and exercise each available direction's primary
@@ -50,8 +58,8 @@ Generate three alternatives by default; honor an explicit requested count.
    Selection does not start Plan or Ship or authorize creating
    or sending a review link or deployment.
 
-The bundled utilities perform deterministic work only. No provider credentials,
-semantic command subprocess, runtime downloads or global CLI are required.
+The `openplanr design` commands perform deterministic work only. They need no
+provider credentials, semantic command subprocess or runtime downloads.
 
 For company reviews and implementation handoff, follow
 [team-review.md](references/team-review.md). Keep review guidance outside product

package/lib/host-packages/openai/openplanr/skills/design-loop/openplanr.skill.json

@@ -121,17 +121,6 @@
         "cursor"
       ]
     },
-    {
-      "path": "scripts/design.mjs",
-      "kind": "script",
-      "executable": true,
-      "hosts": [
-        "claude-code",
-        "codex",
-        "chatgpt",
-        "cursor"
-      ]
-    },
     {
       "path": "schemas/design-document.schema.json",
       "kind": "schema",

package/lib/host-packages/openai/openplanr/skills/design-loop/references/design-system.md

@@ -54,11 +54,11 @@ while authoring:
 - at most two families and three weights each; one variable file can cover a
   family's weights.
 
-Snapshot with the bundled helper, run from the skill directory (see
+Snapshot with the design CLI, run from the project directory (see
 [utilities.md](utilities.md)):
 
 ```sh
-node scripts/design.mjs fonts fetch --family "Inter:400,600" --family "Source Serif 4:400" --dest <design>/source/assets/fonts
+openplanr design fonts fetch --family "Inter:400,600" --family "Source Serif 4:400" --dest <design>/source/assets/fonts
 ```
 
 It is the one command to ask approval for. A host that allowlists network access by

package/lib/host-packages/openai/openplanr/skills/design-loop/references/generation.md

@@ -34,12 +34,12 @@ incidental array positions or rendered CSS selectors.
 
 Author real screen content with useful labels, plausible data and complete states.
 Make the primary journey navigable and meaningful controls functional. Use local
-HTML/CSS/JavaScript and assets supported by the bundled utility; do not require a
+HTML/CSS/JavaScript and assets supported by the design utilities; do not require a
 build server, package installation, remote modules or a development environment to
 open the studio. Third-party assets retain their license/attribution where needed.
 Use classic browser scripts with local event handlers. If adapting an existing
-module-based component, compile its local preview before packaging; the portable
-utility does not install dependencies or compile modules. Use local image `src`
+module-based component, compile its local preview before packaging; the design
+utilities do not install dependencies or compile modules. Use local image `src`
 with responsive CSS. Forms validate and run local handlers; omit navigation
 actions and targets. Cross-screen actions can use `data-design-navigate` with the
 stable target screen ID.

package/lib/host-packages/openai/openplanr/skills/design-loop/references/review.md

@@ -9,10 +9,10 @@ a remix; keep their origin distinct and do not invent board votes.
 For "this button" or "this screen", read the live local viewer context:
 
 ```sh
-node scripts/design.mjs view-context <design-document.json> --json
+openplanr design view-context <design-document.json> --json
 ```
 
-The utility reads `.design/view-context.json` beside the document and rejects a
+The command reads `.design/view-context.json` beside the document and rejects a
 revision that differs from the current render. Ignore context whose `updatedAt`
 is older than the user's request; pass `--request-time <ISO-timestamp>` to have
 the reader enforce that check. Missing, invalid or stale context returns
@@ -85,7 +85,7 @@ decision. Read project-local shared feedback alongside the ordinary pin ledger.
 
 Creating a share or publishing an update requires an explicit user request.
 Rendering a local revision does not update the remote review. After the user asks
-to publish, use the studio's Publish update action or the bundled utility; verify
+to publish, use the studio's Publish update action or `openplanr artifact publish`; verify
 the returned published revision. The URL stays stable and recipients choose when
 to load a new revision. Earlier pins remain stale until deliberately addressed.
 
@@ -96,9 +96,9 @@ specifications, project files, URLs, logs, or ordinary command output.
 
 ## Agent-friendly review exports
 
-Use **Export reviews** in the Review sidebar, or the bundled feedback export
-utility, for Markdown or JSON grouped by original revision, screen, direction and
-responsive frame. Preserve reviewer IDs, exact quotations, replies and timestamps.
+Use **Export reviews** in the Review sidebar, or
+`openplanr artifact feedback --action export`, for Markdown or JSON grouped by
+original revision, screen, direction and responsive frame. Preserve reviewer IDs, exact quotations, replies and timestamps.
 Read the completeness flag; wait for older pages or retry when disconnected before
 treating an export as the full review history. Unsaved text in a composer is a draft,
 not submitted feedback.

package/lib/host-packages/openai/openplanr/skills/design-loop/references/team-review.md

@@ -101,10 +101,9 @@ has been rendered and checked.
 
 ## Prepare and refine the handoff
 
-When requested, run `openplanr artifact handoff <design-document.json>` or the bundled
-`node scripts/design.mjs handoff <design-document.json>` utility. Both prepare a
-factual draft from the recorded review; neither calls an AI model or starts Plan.
-Read the utility's `--help` for the installed edit and approval interface.
+When requested, run `openplanr artifact handoff <design-document.json>`. It
+prepares a factual draft from the recorded review; it does not call an AI model or
+start Plan. Read its `--help` for the installed edit and approval interface.
 
 Refine the draft in this active host session. Preserve comment quotations,
 authorship, source revision and references. Separate accepted changes from

package/lib/host-packages/openai/openplanr/skills/design-loop/references/utilities.md

@@ -1,24 +1,71 @@
-# Bundled design utilities
+# Design utilities
 
-Run the linked design helper from the skill entrypoint relative to the skill's
-directory. It contains deterministic operations and all required assets. It needs
-Node.js 22.13 or later, with no global CLI or provider credentials. Only `fonts fetch`
-downloads anything, and only when run; nothing is fetched when a design opens.
-Use `--help` to inspect the installed command interface before writing documents
-or invoking operations; the installed contract is authoritative.
+Design operations run in the `openplanr` CLI. They are deterministic, need Node.js
+22.13 or later and no provider credentials. Only `fonts fetch` downloads anything,
+and only when run; nothing is fetched when a design opens. Use `--help` on a
+command to inspect the installed interface before writing documents or invoking
+operations; the installed contract is authoritative.
+
+## Check the design runtime
+
+Run this once, before consultation, and check whether the host's artifact tool
+offers a design quickstart or a Design artifact type:
 
 ```sh
-node scripts/design.mjs inspect <design-document.json> --json
-node scripts/design.mjs validate <design-document.json> --json
-node scripts/design.mjs render <design-document.json> --json
-node scripts/design.mjs open <design-document.json> --view canvas --no-open --json
-node scripts/design.mjs feedback <design-document.json> --action inspect --json
-node scripts/design.mjs view-context <design-document.json> --json
-node scripts/design.mjs studio <design-document.json> --action status --json
-node scripts/design.mjs studio <design-document.json> --action stop --json
-node scripts/design.mjs fonts fetch --family "<Name>:<weights>" [--family ...] --dest <design>/source/assets/fonts --json
+openplanr design capabilities --json
 ```
 
+These skills need design contract 1. Treat a successful
+`openplanr design capabilities --json` as proof the runtime is ready. Never locate
+or import the OpenPlanr workflow package, inspect `node_modules`, or call internal
+runtime modules. Use the `openplanr` on `PATH`; never search for another one or
+for bundled design scripts. A failed probe means the matching stop below.
+
+| Probe result | Runtime | Next action |
+|---|---|---|
+| `ok: true` and `supported.min` ≤ 1 ≤ `supported.max` | Ready | Use the commands below. |
+| `openplanr` not found | Stop 1: no CLI | `npm install -g openplanr` |
+| `unknown command 'design'`, `E_DESIGN_RUNTIME_UNSUPPORTED`, or a `supported` range without 1 | Stop 2: CLI too old | `npm install -g openplanr@latest` |
+| `ok: false` with `E_DESIGN_RUNTIME_MISSING` and `pipeline: null` | Stop 3: CLI without its workflow package | `npm install -g openplanr`, run without `--omit=optional` |
+
+A design on the hosted canvas needs no CLI. At a stop, consultation and
+authoring still happen: author `design-document.json`, its sources and
+`design-spec.md`, mark them **unverified**, and say that no studio was rendered or
+checked. End with every next action that applies, each one the user can run: the
+stop's command, and the host action below. On Claude Code without a Design
+artifact type, that is the command and the canvas actions. Then ask the user to
+run the skill again.
+
+| Host | Notes |
+|---|---|
+| Claude Code | Design builds on the hosted canvas when the artifact tool offers a Design type. When it does not, also name the canvas actions: sign in with `/login` on a claude.ai Pro, Max, Ultra, Team or Enterprise plan; or, when artifacts are turned off, re-enable them in `/config`. An API key or gateway token means no claude.ai login: name `/login` with a claude.ai plan, or the CLI. On Bedrock, Google Cloud or Foundry, or in an organisation with CMEK, HIPAA or Zero Data Retention, the canvas is unavailable and the CLI is the path. |
+| Codex | The stop's command. `openplanr setup` installs the workflow package beside the skills, but `PATH` can resolve a different `openplanr`; `which openplanr` shows the one that runs. Codex's default `workspace-write` sandbox stops the studio: `design open` fails with `listen EPERM`. Tell the user to run `openplanr design open <design-document.json>` in their own terminal, or to restart Codex with `-c sandbox_workspace_write.network_access=true -c 'sandbox_workspace_write.writable_roots=["<absolute path of ~/.planr>"]'` (use `PLANR_HOME` instead when it is set). That setting also lets commands reach the network. |
+| Cursor | The stop's command. `openplanr setup` installs the workflow package beside the skills, but `PATH` can resolve a different `openplanr`; `which openplanr` shows the one that runs. |
+| ChatGPT | Without a local shell, take stop 1: deliver the unverified sources and specification, and name `npm install -g openplanr` for a coding agent with a shell. |
+
+## Commands
+
+Run these from the project directory. Paths resolve against it.
+
+```sh
+openplanr design inspect <design-document.json> --json
+openplanr design validate <design-document.json> --json
+openplanr design render <design-document.json> --json
+openplanr design open <design-document.json> --view canvas --no-open --json
+openplanr design view-context <design-document.json> --json
+openplanr design verify <design-document.json> --report <browser-report.json> --json
+openplanr design export <design-document.json> --view canvas --format html --output <path> --json
+openplanr design studio status <design-document.json> --json
+openplanr design studio stop <design-document.json> --json
+openplanr design fonts fetch --family "<Name>:<weights>" [--family ...] --dest <design>/source/assets/fonts --json
+openplanr artifact feedback <design-document.json> --action inspect --json
+```
+
+`render` reads the specification at the path in [handoff.md](handoff.md), so write
+`design-spec.md` before the first render. The CLI prints `<path>` in place of
+absolute paths, so an `ENOENT` names no file: check that `design-spec.md` and
+every source the document names exist before suspecting the CLI.
+
 `fonts fetch` snapshots at most two OFL or Apache families, three weights each, as
 Latin `woff2` files with their license files and a local `fonts.css`. It needs network
 access; ask the user to approve that one command. A host that allowlists domains needs
@@ -28,9 +75,9 @@ access; ask the user to approve that one command. A host that allowlists domains
 [design-system.md](design-system.md) for the fallback.
 
 Use `--view prototype` or `--view walkthrough` to select the initial presentation.
-When an `openplanr` CLI is available, prefer its public `openplanr artifact` route for
-opening the document; otherwise use this bundled script. Both compose the same
-design and artifact runtime, preserving feedback and view behavior.
+`design open` keeps the studio running until it is stopped, so run it in the
+background. `openplanr artifact open <design-document.json>` opens the same studio,
+preserving feedback and view behavior.
 
 `view-context` returns validated live viewer data, or `{ viewContext: null, reason }`
 when unavailable or stale. Use `--request-time <ISO-timestamp>` to reject context
@@ -49,12 +96,12 @@ Opening a completed design reuses its healthy local service and returns a short
 Studio; a service hosting several designs offers a selection page. Keep the
 returned URL instead of constructing one from export paths.
 
-Use `studio --action status` to find the healthy service for this design. Its
+Use `design studio status` to find the healthy service for this design. Its
 `status: running` reports service availability; `browserStatus` reports observed
 preview loading separately, and `verification` reports actual saved checks.
 Startup alone does not mean a design is ready or verified.
 
-Use `studio --action stop` to authenticate the exact owned live instance and drain
+Use `design studio stop` to authenticate the exact owned live instance and drain
 pending saves; it does not signal a process by PID. `status: stopping` means
 shutdown was accepted. Run status again to confirm it stopped. Feedback, ratings
 and arrangement remain in their canonical stores and survive reopening.
@@ -63,7 +110,7 @@ A healthy service with different settings, an older runtime, or an unvalidated
 session must be stopped before reopening. When its launcher record is missing,
 stop can recover the sole authenticated owner for this design. If several owned
 services remain, inspect status and choose one explicitly with
-`studio <design-document.json> --action stop --instance-id <id>`. An instance from
+`openplanr design studio stop <design-document.json> --instance-id <id>`. An instance from
 another project or state directory is rejected. Hosted shares continue independently.
 
 ## Import downloaded feedback
@@ -71,7 +118,7 @@ another project or state directory is rejected. Hosted shares continue independe
 Explicitly reconcile downloaded feedback with the canonical local ledger:
 
 ```sh
-node scripts/design.mjs feedback <design-document.json> --action import --input <downloaded-review.json> --revision <current-render-revision> --json
+openplanr artifact feedback <design-document.json> --action import --input <downloaded-review.json> --revision <current-render-revision> --json
 ```
 
 Read `feedback --action inspect` first and pass its current `revision` internally;
@@ -108,12 +155,11 @@ The design remains accessible when the local machine is offline. Owner authority
 saves automatically in a protected user-level file outside the project; recovery
 export is optional. Only copy the reviewer token through the explicit Share controls.
 
-The bundled utility supports `share`, `publish`, and `sync` with the same design
-document argument. `share` creates or retries a review, `publish` sends an explicitly
-requested new revision to the existing URL, and `sync` retrieves authenticated
-feedback. Run `--help` for access-management and recovery options. The public CLI
-equivalents are `openplanr artifact share`, `openplanr artifact publish`, and
-`openplanr artifact sync`. No global CLI is required for the bundled helper.
+Sharing runs in the `openplanr` CLI, which holds the owner keys:
+`openplanr artifact share`, `publish`, `sync`, `status`, `manage`, `feedback` and
+`handoff`, and the studio's Share dialog. `share` creates or retries a review,
+`publish` sends an explicitly requested new revision to the existing URL, and
+`sync` retrieves authenticated feedback.
 
 Retention is until the owner revokes or deletes the review, while the service is
 maintained. The owner can pause comments and rotate access tokens. Rotation blocks
@@ -123,9 +169,9 @@ saved operation and use its retry path. Report service unavailability explicitly
 
 ## Team review and handoff
 
-`openplanr artifact handoff <design-document.json>` and the bundled
-`node scripts/design.mjs handoff <design-document.json>` prepare or refresh a
-factual review handoff. Use `--json` for structured results and consult `--help`
+`openplanr artifact handoff <design-document.json>` prepares or refreshes a
+factual review handoff, and `openplanr design handoff <design-document.json>`
+inspects it. Use `--json` for structured results and consult `--help`
 for inspection, update and approval actions. Follow [team-review.md](team-review.md)
 for active-agent refinement and owner approval. These deterministic operations do
 not call a provider, publish a design or start Plan/Ship.