openplanr 1.25.2 → 2.0.0

package/dist/templates/rules/shared/implementation-guidance.md.hbs

@@ -0,0 +1,44 @@
+## OpenPlanr context
+
+- Start with the request and relevant code, tests, configuration, documentation,
+  ADRs, and project rules.
+- When an exact Planr task is supplied, read the complete task first, then its
+  complete parent story, enclosing spec, matching Gherkin sidecar when present,
+  and declared `dependsOn` output contracts. Treat Create/Modify as the expected
+  change surface and structured Preserve entries as unchanged paths.
+- Load `input/tech/stack.md` when present. Resolve each `ActiveStackFiles` entry
+  from the active OpenPlanr skill's bundled references, then the project stack
+  directory; the project file wins on collision.
+- Load the applicable `design-spec.md` for UI work and `output/db/schema.json`
+  for persistence work.
+- When no task is supplied, use the strongest relevant artifacts under
+  `{{agilePath}}/`. Missing or stale planning state does not block a clear
+  implementation request.
+- Ask only when an unresolved choice materially changes product behavior,
+  scope, architecture, or risk. Prefer the host's native structured question
+  surface; otherwise ask one concise question.
+- Keep PLAN and SHIP as separate user-invoked workflows. PLAN prepares context;
+  SHIP implements it. Never auto-chain them. This is a workflow boundary, not
+  a prerequisite for useful work within the selected workflow.
+
+## Implementation guidance
+
+1. Implement the coherent requested outcome, including directly required
+   companion files.
+2. Match the repository's architecture, conventions, and ownership boundaries.
+3. Verify in proportion to risk and acceptance behavior. Fix relevant failures
+   directly.
+4. When a command or check fails, inspect the actual error and use it to choose
+   the next useful step. If progress is not possible, report the failing command,
+   concise error context, and the next useful action.
+5. Report `Outcome`, `Task`, `Changed`, `Checks`, and `Issues`; write `none`
+   when no material issue remains.
+
+## Planning artifact map
+
+- Specs: `{{agilePath}}/specs/`
+- Tasks and quick work: `{{agilePath}}/tasks/`, `{{agilePath}}/quick/`
+- Stories, features, and epics: `{{agilePath}}/stories/`,
+  `{{agilePath}}/features/`, `{{agilePath}}/epics/`
+- Backlog and architecture decisions: `{{agilePath}}/backlog/`,
+  `{{agilePath}}/adrs/`

package/dist/templates/spec/spec-shaped.md.hbs

@@ -3,7 +3,8 @@ id: "{{id}}"
 title: "{{title}}"
 slug: "{{slug}}"
 schemaVersion: "{{schemaVersion}}"
-status: "shaping"
+specificationContract: "{{specificationContract}}"
+status: "shaped"
 priority: "{{priority}}"
 {{#if milestone}}milestone: "{{milestone}}"{{/if}}
 {{#if po}}po: "{{po}}"{{/if}}
@@ -26,6 +27,25 @@ tech_dependencies: []
 
 {{context}}
 
+## Audience
+
+**Primary:** {{audience.primary}}
+
+**Affected:**
+{{#each audience.affected}}
+- {{this}}
+{{/each}}
+
+## Outcome & Measurement
+
+**Statement:** {{outcome.statement}}
+
+**Measure:** {{outcome.measure}}
+
+**Target:** {{outcome.target}}
+
+**Timeframe:** {{outcome.timeframe}}
+
 ## Functional Requirements
 
 {{#if functionalRequirements.length}}
@@ -38,39 +58,64 @@ tech_dependencies: []
 
 ## Business Rules
 
-{{#if businessRules}}
-{{businessRules}}
+{{#if businessRules.length}}
+{{#each businessRules}}
+- {{this}}
+{{/each}}
 {{else}}
 _None specified._
 {{/if}}
 
-## User Flows
+## Constraints
+
+{{#each constraints}}
+- {{this}}
+{{/each}}
+
+## Evidence Expectations
+
+{{#each evidenceExpectations}}
+- {{this}}
+{{/each}}
+
+## Failure Modes
 
-_To be detailed by the PO. Sketch the primary happy path(s) here before running `planr spec decompose {{id}}`._
+{{#each failureModes}}
+- {{this}}
+{{/each}}
 
-**Flow 1 — [Flow Name]:**
-1. User lands on ...
-2. User performs ...
-3. System responds with ...
+## Rollback
 
-## Out of Scope
+{{rollback}}
 
-{{#if outOfScope.length}}
-{{#each outOfScope}}
+## Scope Boundaries
+
+### In Scope
+
+{{#each scope.inScope}}
+- {{this}}
+{{/each}}
+
+### Out of Scope
+
+{{#each scope.outOfScope}}
 - {{this}}
 {{/each}}
-{{else}}
-_Nothing explicitly out of scope yet._
-{{/if}}
 
 ## Acceptance Criteria
 
-{{#if acceptanceCriteria.length}}
 {{#each acceptanceCriteria}}
 - [ ] {{this}}
 {{/each}}
+
+## Declared Risk Specialists
+
+{{#if declaredSpecialists.length}}
+{{#each declaredSpecialists}}
+- {{this}}
+{{/each}}
 {{else}}
-- [ ] Given ..., when ..., then ...
+_No risk specialist was explicitly declared; deterministic classification still applies before review._
 {{/if}}
 
 ## Notes for Decomposition
@@ -78,12 +123,11 @@ _Nothing explicitly out of scope yet._
 {{#if decompositionNotes}}
 {{decompositionNotes}}
 {{else}}
-_Optional hints to guide `planr spec decompose`. Not business requirements._
+_Optional hints for the host-native `planr-plan` skill. Not business requirements._
 {{/if}}
 
 ---
 
-> **Pipeline handoff:** Once decomposed and reviewed, run from Claude Code:
-> `/planr-pipeline:plan {{slug}}`
->
-> _This spec was authored via `planr spec shape {{id}}` on {{date}}. Run `planr spec decompose {{id}}` to generate User Stories + Tasks._
+> Shaped as `{{specificationContract}}` on {{date}}. Continue with
+> Invoke `$planr:plan {{id}}` in Codex/ChatGPT or `/planr:plan {{id}}` in Claude Code.
+> when implementation tasks are needed.

package/dist/templates/spec/spec.md.hbs

@@ -19,6 +19,23 @@ tech_dependencies: []
 
 _Describe the problem this feature solves and the expected outcome. 2-5 sentences. Focus on the user need; avoid implementation details._
 
+## Audience
+
+**Primary:** _Who makes or receives the core decision?_
+
+**Affected:**
+- _List every materially affected user or stakeholder._
+
+## Outcome & Measurement
+
+**Statement:** _State the user or business outcome._
+
+**Measure:** _Name the observable metric or evidence._
+
+**Target:** _Set the pass threshold._
+
+**Timeframe:** _Set the measurement window._
+
 ## Functional Requirements
 
 _Use action verbs. One bullet = one observable behavior._
@@ -32,18 +49,31 @@ _Constraints, validations, and logic that govern the feature._
 
 - ...
 
-## User Flows
+## Constraints
 
-**Flow 1 — [Flow Name]:**
-1. User lands on ...
-2. User performs ...
-3. System responds with ...
+- _State technical, legal, operational, time, or budget boundaries._
 
-## Out of Scope
+## Evidence Expectations
 
-_Explicitly list what this feature does NOT include._
+- _Name the evidence required to accept each material outcome._
 
-- ...
+## Failure Modes
+
+- _Describe a credible failure and how it will be detected._
+
+## Rollback
+
+_Describe the safe reversal or compensating action and its trigger._
+
+## Scope Boundaries
+
+### In Scope
+
+- _List the exact capability included._
+
+### Out of Scope
+
+- _List the exact capability excluded._
 
 ## Acceptance Criteria
 
@@ -52,9 +82,14 @@ _Observable, testable outcomes._
 - [ ] Given ..., when ..., then ...
 - [ ] Given ..., when ..., then ...
 
+## Declared Risk Specialists
+
+_Optional explicit declarations: security, performance, migration, api-contract,
+or data-integrity. Deterministic classification still runs before review._
+
 ## Notes for Decomposition
 
-_Optional hints to guide `planr spec decompose`. Not business requirements._
+_Optional hints for the host-native `planr-plan` skill. Not business requirements._
 
 - Suggested US split: ...
 - Special attention: ...
@@ -62,17 +97,5 @@ _Optional hints to guide `planr spec decompose`. Not business requirements._
 
 ---
 
-> **Next steps:**
->
-> In Claude Code with the `planr-pipeline` plugin:
-> ```
-> /planr-pipeline:plan {{slug}}     # decompose + human review
-> /planr-pipeline:ship {{slug}}     # full DEV phase
-> ```
->
-> Bare CLI:
-> ```
-> planr spec decompose {{id}}           # AI-driven
-> ```
->
-> Schema: `https://openplanr.dev/docs/reference/spec-schema`
+> **Continue:** Complete this specification directly or use
+> Run `planr spec shape {{id}}`, then invoke `$planr:plan {{id}}` in Codex/ChatGPT or `/planr:plan {{id}}` in Claude Code.

package/dist/templates/spec/story.md.hbs

@@ -7,16 +7,21 @@ schemaVersion: "{{schemaVersion}}"
 status: "{{status}}"
 created: "{{date}}"
 updated: "{{date}}"
+acceptanceCriteria:{{#unless acceptanceCriteria.length}} []{{/unless}}
+{{#each acceptanceCriteria}}
+  - id: "{{id}}"
+    statement: {{{json statement}}}
+{{/each}}
 ---
 
 # {{id}} — {{title}}
 
 > **Spec:** {{specId}}
-> **Note:** This US-NNN ID is **scoped to the parent spec** ({{specId}}), not project-globally unique.
+> **Note:** This User Story ID is project-global; `specId` records its parent.
 
 ## User Story
 
-**As a** {{roleAction}},
+**As** {{roleAction}},
 **so that** {{benefit}}.
 
 ## Scope
@@ -27,7 +32,7 @@ updated: "{{date}}"
 
 {{#if acceptanceCriteria.length}}
 {{#each acceptanceCriteria}}
-- [ ] {{this}}
+- [ ] **{{id}}** — {{statement}}
 {{/each}}
 {{else}}
 - [ ] Given ..., when ..., then ...
@@ -38,7 +43,13 @@ updated: "{{date}}"
 
 | Task | File | Agent | Description |
 |------|------|-------|-------------|
-| _none yet_ | _tasks/T-NNN-{slug}.md_ | _frontend-agent / backend-agent_ | _Generated by `planr spec decompose`_ |
+{{#if tasks.length}}
+{{#each tasks}}
+| {{id}} | `../tasks/{{filename}}` | `{{agent}}` | {{title}} |
+{{/each}}
+{{else}}
+| _None_ | _None_ | _None_ | _No implementation tasks have been created._ |
+{{/if}}
 
 ## Dependencies
 

package/dist/templates/spec/task.md.hbs

@@ -10,6 +10,48 @@ agent: "{{agent}}"
 status: "{{status}}"
 created: "{{date}}"
 updated: "{{date}}"
+rationale: "{{rationale}}"
+{{#if dependsOn.length}}
+dependsOn:
+{{#each dependsOn}}
+  - "{{this}}"
+{{/each}}
+{{else}}
+dependsOn: []
+{{/if}}
+{{#if reviewRisks.length}}
+reviewRisks:
+{{#each reviewRisks}}
+  - "{{this}}"
+{{/each}}
+{{else}}
+reviewRisks: []
+{{/if}}
+{{#if browserSurfaces.length}}
+browserSurfaces:
+{{#each browserSurfaces}}
+  - "{{this}}"
+{{/each}}
+{{else}}
+browserSurfaces: []
+{{/if}}
+{{#if acceptanceRefs.length}}
+acceptanceRefs:
+{{#each acceptanceRefs}}
+  - "{{this}}"
+{{/each}}
+{{else}}
+acceptanceRefs: []
+{{/if}}
+{{#if filesPreserve.length}}
+preserve:
+{{#each filesPreserve}}
+  - repositoryKey: project
+    path: "{{this}}"
+{{/each}}
+{{else}}
+preserve: []
+{{/if}}
 ---
 
 # {{id}} — {{title}}
@@ -17,8 +59,8 @@ updated: "{{date}}"
 > **User Story:** {{storyId}}
 > **Spec:** {{specId}}
 > **Type:** {{type}}
-> **Agent:** `{{agent}}` (matches `planr-pipeline` subagent name; free-form for other tools)
-> **Note:** T-NNN ID is **scoped to the parent spec** ({{specId}}), not project-globally unique.
+> **Agent:** `{{agent}}` (Protocol v1.7 pairing for `{{type}}`)
+> **Note:** This Task ID is project-global; `storyId` and `specId` record its parents.
 
 ## Objective
 
@@ -33,7 +75,7 @@ updated: "{{date}}"
 - `{{this}}` — _purpose_
 {{/each}}
 {{else}}
-- `path/to/new-file.ext` — _purpose_
+_None._
 {{/if}}
 
 ### Modify
@@ -43,7 +85,7 @@ updated: "{{date}}"
 - `{{this}}` — _what to change_
 {{/each}}
 {{else}}
-- `path/to/existing-file.ext` — _what to change_
+_None._
 {{/if}}
 
 ### Preserve (do not touch)
@@ -53,7 +95,7 @@ updated: "{{date}}"
 - `{{this}}` — _why_
 {{/each}}
 {{else}}
-- `path/to/protected-file.ext` — _why_
+_None._
 {{/if}}
 
 ## Technical Spec
@@ -87,6 +129,12 @@ updated: "{{date}}"
 - **Edge cases to cover:** _list_
 {{/if}}
 
+### Acceptance coverage
+
+{{#each acceptanceCriteria}}
+- **{{id}}** — {{statement}}
+{{/each}}
+
 ## Definition of Done
 
 - [ ] All files listed under "Create" exist and compile

package/dist/utils/constants.d.ts

@@ -52,7 +52,7 @@ export declare const VALID_STATUSES: Partial<Record<ArtifactType, readonly strin
  *
  * - pending             — SPEC created, body not yet written
  * - shaping             — SPEC body authored (manually or via `planr spec shape`)
- * - decomposing         — `planr spec decompose` is running (AI generating US + tasks)
+ * - decomposing         — the active host agent is authoring user stories and tasks
  * - decomposed          — US + Task files written, awaiting human review
  * - ready-for-pipeline  — `planr spec promote` validated; ready for planr-pipeline
  * - in-pipeline         — planr-pipeline `/plan` or `/ship` is running

package/dist/utils/constants.js

@@ -63,7 +63,7 @@ export const VALID_STATUSES = {
  *
  * - pending             — SPEC created, body not yet written
  * - shaping             — SPEC body authored (manually or via `planr spec shape`)
- * - decomposing         — `planr spec decompose` is running (AI generating US + tasks)
+ * - decomposing         — the active host agent is authoring user stories and tasks
  * - decomposed          — US + Task files written, awaiting human review
  * - ready-for-pipeline  — `planr spec promote` validated; ready for planr-pipeline
  * - in-pipeline         — planr-pipeline `/plan` or `/ship` is running

package/dist/utils/logger.d.ts

@@ -1,11 +1,8 @@
-import type { AIUsage } from '../ai/types.js';
 export interface Spinner {
     update(msg: string): void;
     stop(): void;
     succeed(msg: string): void;
 }
-/** Format token usage for display. Returns empty string if no usage data. */
-export declare function formatUsage(usage?: AIUsage | null): string;
 export declare function createSpinner(message: string): Spinner;
 export declare function setVerbose(enabled: boolean): void;
 export declare function isVerbose(): boolean;

package/dist/utils/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAe9C,MAAM,WAAW,OAAO;IACtB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,IAAI,IAAI,CAAC;IACb,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,MAAM,CAG1D;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CA2BtD;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEjD;AAED,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED,eAAO,MAAM,MAAM;cACP,MAAM;iBAGH,MAAM;cAGT,MAAM;eAGL,MAAM;iBAGJ,MAAM;aAGV,MAAM;eAGJ,MAAM,WAAW,OAAO,EAAE;CAStC,CAAC;AAQF,eAAO,MAAM,OAAO;IAClB,qCAAqC;eAC1B,MAAM;IAGjB,uCAAuC;;IAIvC,wCAAwC;;IAIxC,oCAAoC;kBACtB,MAAM;IAGpB,iDAAiD;oBACjC,MAAM,SAAS,MAAM;IAIrC,kCAAkC;iBACrB,MAAM;IAInB,kCAAkC;oBAClB,MAAM,QAAQ,MAAM;IAIpC,sDAAsD;yBACjC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE;IAKvD,6CAA6C;qBAC5B,MAAM,EAAE,UAAU,MAAM,EAAE;IAK3C,sDAAsD;+BAC3B,MAAM;IAIjC,4BAA4B;yBACP,MAAM,yBAAoB;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAgBnF,CAAC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,OAAO;IACtB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,IAAI,IAAI,CAAC;IACb,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CA2BtD;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEjD;AAED,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED,eAAO,MAAM,MAAM;cACP,MAAM;iBAGH,MAAM;cAGT,MAAM;eAGL,MAAM;iBAGJ,MAAM;aAGV,MAAM;eAGJ,MAAM,WAAW,OAAO,EAAE;CAStC,CAAC;AAQF,eAAO,MAAM,OAAO;IAClB,qCAAqC;eAC1B,MAAM;IAGjB,uCAAuC;;IAIvC,wCAAwC;;IAIxC,oCAAoC;kBACtB,MAAM;IAGpB,iDAAiD;oBACjC,MAAM,SAAS,MAAM;IAIrC,kCAAkC;iBACrB,MAAM;IAInB,kCAAkC;oBAClB,MAAM,QAAQ,MAAM;IAIpC,sDAAsD;yBACjC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE;IAKvD,6CAA6C;qBAC5B,MAAM,EAAE,UAAU,MAAM,EAAE;IAK3C,sDAAsD;+BAC3B,MAAM;IAIjC,4BAA4B;yBACP,MAAM,yBAAoB;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAgBnF,CAAC"}

package/dist/utils/logger.js

@@ -9,12 +9,6 @@ const out = (...args) => console.log(...args);
 const outErr = (...args) => console.error(...args);
 let verboseEnabled = false;
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-/** Format token usage for display. Returns empty string if no usage data. */
-export function formatUsage(usage) {
-    if (!usage)
-        return '';
-    return ` (${usage.inputTokens.toLocaleString()} in → ${usage.outputTokens.toLocaleString()} out tokens)`;
-}
 export function createSpinner(message) {
     let frameIndex = 0;
     let currentMsg = message;

package/dist/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/docs/ARTIFACT_REVIEW.md

@@ -0,0 +1,110 @@
+# Artifact review and private sharing
+
+`planr artifact` turns a project-local HTML file into a loopback-only review
+session with comments, pins, threads, and Approve or Request changes decisions.
+JavaScript inside the artifact remains interactive in an opaque-origin,
+network-blocked sandbox.
+
+Generic artifacts open in `document` presentation by default: the complete
+artifact is the edge-to-edge page with a compact floating comments rail. The
+prior zoomable artboard is still available as `canvas` presentation and remains
+the default for design boards and multi-variant workflows.
+
+## Local review
+
+```bash
+planr artifact ./artifact.html
+planr artifact open /absolute/path/to/artifact.html --theme auto
+planr artifact open ./artifact.html --presentation canvas
+planr artifact export <session-id> --format markdown --output review.md
+```
+
+The bundler packages local CSS, scripts, modules, images, SVG, fonts, `srcset`,
+and CSS `url()` references. With no `--root`, the artifact's own directory is
+the dependency root, so absolute files from Downloads or another project work
+without extra flags. It also vendors safe public HTTPS dependency graphs (such
+as Google Fonts, CDN stylesheets, scripts, images, and fonts) into the immutable
+artifact before review or sharing. Forms, traversal, symlink escapes, unsafe or
+unavailable remote assets, and unresolved dependencies remain rejected. Use
+`--no-open --json` for remote or SSH sessions, then forward the printed loopback
+port explicitly.
+
+`--presentation auto|document|canvas` is available on `open` and `share`.
+`auto` resolves one generic artifact to `document`; explicit overrides win.
+Document feedback starts closed and opens as an overlay without resizing the
+artifact. JSON output includes the resolved presentation.
+
+The complete local HTML/CSS/JavaScript graph is bundled into immutable bytes
+before review or sharing. The viewer does not fetch the original project after
+sharing. It loads those bytes through an invisible Blob iframe with
+`sandbox="allow-scripts"`; it never injects artifact HTML into OpenPlanr or
+executes it under the `share.openplanr.dev` origin. A bounded authenticated
+layout bridge provides natural outer-page scrolling and full-document pins.
+
+This is private artifact review, not standalone website hosting. Publishing a
+top-level website would require a separate isolated artifact origin and is not
+part of this command.
+
+## Private links
+
+```bash
+planr artifact share ./artifact.html --secret-output ./room.private.json
+planr artifact share ./artifact.html --presentation document --secret-output ./room.private.json
+planr artifact share ./artifact.html --snapshot --short --ttl 7d --yes
+```
+
+By default, sharing creates one stable encrypted live review room. The normal
+review URL lets anyone with the link view and comment. A distinct owner-verdict
+URL plus the matching private P-256 signer can approve or request changes. The
+management URL can only pause/reopen comments or delete the room. The required
+`--secret-output` path is reserved exclusively, then an exact recovery bundle
+containing all three URLs and the owner signer is made durable at mode 0600
+before the first room request. A lost response is retried once with the same
+prepared room identity, ciphertext, and capabilities, so it cannot create a
+duplicate or rotate the recovery URLs. A validated no-effect rejection revokes
+the bundle; an ambiguous outcome preserves it and returns a bounded, path-free
+recovery error. New feedback synchronizes to other open review tabs immediately.
+The artifact itself remains immutable and the service never receives the
+private signer.
+
+Use `--snapshot` for the immutable sharing model. Artifacts whose encoded
+fragments are 8,000 characters or less use
+`https://share.openplanr.dev/#v1.<payload>`. The browser fragment is not sent in
+the HTTP request, so the host receives no artifact content. Fragment links are
+encoded, not encrypted: anyone who receives the URL can read the review.
+
+Larger artifacts require an explicit encrypted short-link upload. OpenPlanr
+compresses the envelope, encrypts it with AES-256-GCM, uploads ciphertext, and
+puts the key only after `#k=` in the URL. The service sees request metadata and
+ciphertext, never plaintext or the key. Links are immutable and expire after
+1, 7, or 30 days. Save the one-time deletion token when it is displayed.
+
+## Return and import feedback
+
+Live-room feedback stays in its encrypted room until expiry or deletion. Import
+the room URL at any point to merge its latest full feedback state locally. For
+snapshot sharing, a reviewer still returns a new immutable review URL. Import
+one or more room or snapshot URLs non-destructively:
+
+```bash
+planr artifact import "<review-url>" "<second-review-url>"
+```
+
+Changed-artifact feedback is rejected with `E_ARTIFACT_STALE_REVIEW`. To retain
+it for audit, rerun with `--allow-stale`, inspect the digest and feedback-count
+preview, and confirm. Automation must use `--allow-stale --yes`.
+
+Generic review state is stored in `.planr/artifacts/<artifact-id>/` inside a
+valid project and under `~/.planr/artifacts/` elsewhere. Design-board reviews
+continue to merge into the adjacent `feedback.json` contract.
+
+## Minimal installs, offline use, and self-hosting
+
+A planning-only installation returns `E_PIPELINE_NOT_INSTALLED`; install the
+full distribution with `npm install -g openplanr@latest`. Local review and
+export work offline after installation. Creating or opening a remote review
+link requires network access.
+
+The shell assets and Protocol v1.1 schemas are shipped by `planr-pipeline`.
+Self-hosters may deploy the static viewer and Worker implementation from
+`openplanr/openplanr-web`, then set `OPENPLANR_SHARE_BASE` to their HTTPS origin.