@penpair/web 0.3.7 → 0.4.0

package/docs/adapters.md

@@ -27,7 +27,7 @@ Use it when your application uses Marwes UI. Follow the [adapter overview](marwe
 5. Run a project provider to open that state, read it back, capture the browser and compare the image.
 6. Review the screenshots and differences; record human approval separately.
 
-The adapter checks that the returned evidence identifies the requested case and expected state, references the correct unchanged baseline, and has matching PNG dimensions/scale and font evidence. A complete result within the configured difference threshold is technical evidence, not visual approval or an accessibility assessment.
+The adapter checks that the returned evidence identifies the requested case and expected state, references the correct unchanged baseline, and has matching image dimensions/scale (PNG or static lossless WebP) and font evidence. A complete result within the configured difference threshold is technical evidence, not visual approval or an accessibility assessment.
 
 The provider is project code with an `async runCase(test)` export. It supplies actual route/theme/state/fixture setup, browser readback, screenshot capture and image comparison through the project's pinned tools. It can integrate the project's existing Reflection/browser checker. The adapter itself does not install a browser or execute a particular Reflection engine automatically.
 

package/docs/approvals.md

@@ -8,7 +8,7 @@ penpair approve --page Dashboard --frame FRAME_ID --write \
 # Include --case CONFIGURED_BASELINE_ID for a rich theme/state/fixture case.
 ```
 
-Preview captures stable evidence and records nothing. Recording captures again and appends a schema-1 owner-words record to `design/approvals.json`, with file/page/frame IDs, revision, scale, actual theme/render context, optional declared case, PNG SHA-256, date, identity, exact note and record hash. The immutable PNG lives under `design/approvals/SHA256.png`. A local exclusive append lock prevents lost records; a stale lock requires inspection. The file is atomically replaced after image bytes exist. Prior records are retained.
+Preview captures stable evidence and records nothing. Recording captures again and appends a schema-1 owner-words record to `design/approvals.json`, with file/page/frame IDs, revision, scale, actual theme/render context, optional declared case, encoded-image SHA-256, date, identity, exact note and record hash. The immutable image lives under `design/approvals/SHA256.webp` or the preserved PNG form `design/approvals/SHA256.png`. A local exclusive append lock prevents lost records; a stale lock requires inspection. The file is atomically replaced after image bytes exist. Prior records are retained.
 
 The command records supplied words; it cannot authenticate a person or establish consent. An agent needs the owner's actual approval for the exact reviewed artifact and must never invent words or run this as a routine automatic success step. No approvals were recorded by this implementation task. Content hashes detect changes, not identity. An empty note/identity, unstable capture, mismatched case, altered approved bytes or credential redaction refuses publication.
 
@@ -16,4 +16,35 @@ The command records supplied words; it cannot authenticate a person or establish
 
 An exceptional `--apply --update --force-reason 'EXPLICIT_REASON'` may save a reference without a matching owner record. Its provenance says `forced-reference`; the reason persists. Rich case coverage and the implementation-case adapter refuse to count that waiver as owner-approved evidence. A waived reference is useful for an experiment, but cannot silently satisfy the design acceptance gate. Empty reasons and reasons without apply/update refuse.
 
-The latest revision is a conservative invalidation boundary: an unrelated design edit may require fresh approval even if pixels stay equal. A PNG alone does not approve structure, behavior or accessibility. Approval records remain local/project artifacts until reviewed; no publish, client configuration or consumer-repository edit occurs automatically.
+The latest revision is a conservative invalidation boundary: an unrelated design edit may require fresh approval even if pixels stay equal. An image alone does not approve structure, behavior or accessibility. Approval records remain local/project artifacts until reviewed; no publish, client configuration or consumer-repository edit occurs automatically.
+
+## Image format and migration
+
+New image approvals default to static lossless WebP. `approve --format png` or
+`approve --format webp` selects an exact encoding. For `approve --case CASE_ID`
+without explicit `--format`, the baseline resolver preserves an existing
+reference's actual format; otherwise it uses `baselines.format`, then WebP.
+An approval without `--case` uses explicit `--format` or WebP. Review the actual
+encoded candidate before supplying owner words; equal decoded pixels do not make
+PNG and WebP byte approvals interchangeable.
+
+Changing `baselines.format` or supplying `baselines --format webp` alone does not
+convert an existing PNG reference. Preview migration explicitly:
+
+```sh
+penpair baselines --format webp --migrate-format
+penpair approve --page Dashboard --frame FRAME_ID --case CASE_ID --format webp
+```
+
+After inspecting the new-format artifact and obtaining the owner's actual words,
+record it using the same approval command with `--write --by OWNER --note
+EXACT_OWNER_WORDS`. Then apply the migration:
+
+```sh
+penpair baselines --format webp --migrate-format --apply --update
+```
+
+The CLI requires `--format` with `--migrate-format`; applying requires `--update`.
+Normal exact-image/case approval rules still apply. Prior PNG approval records
+and generations stay intact; migration publishes a new immutable generation.
+Public `export` and `shots` output remain PNG and are independent of this choice.

package/docs/artifacts.md

@@ -1,13 +1,33 @@
 # Capture and approval provenance
 
-Baseline manifests use schema 2. `capturedRevision` identifies the coherent capture run, while each frame has separate `captured` and `approved` records. Those records identify the file, page and frame by immutable ID, revision, PNG hash, scale, active theme names, capture time, penpair version, reported Penpot API version and browser user agent when available. A missing environment value is recorded as unknown; the record does not establish that fonts loaded correctly or identify every rendering dependency.
+Baseline manifests use schema 2. `capturedRevision` identifies the coherent capture run, while each frame has separate `captured` and `approved` records. Those records identify the file, page and frame by immutable ID, revision, encoded-image hash, scale, active theme names, capture time, penpair version, reported Penpot API version and browser user agent when available. A missing environment value is recorded as unknown; the record does not establish that fonts loaded correctly or identify every rendering dependency.
 
-An unchanged reference retains its original approval record. A changed image recaptured without `--update` retains its approved bytes, path, revision and hash, while `captured` describes the new candidate. Legacy images without trustworthy provenance are marked `legacy`; a current revision is never invented for them. Changing a baseline still requires the owner's `--apply --update`. Schema 2 does not claim a separate human review record; that is tracked in D2.
+An unchanged reference retains its original approval record. A changed image recaptured without `--update` retains its approved bytes, path, revision and hash, while `captured` describes the new candidate. Legacy images without trustworthy provenance are marked `legacy`; a current revision is never invented for them. Changing a baseline still requires the owner's `--apply --update`. Exact owner words are retained separately in [approval records](approvals.md); manifest provenance alone cannot manufacture consent.
 
 All configured frames must be present and stable. File/page/revision evidence is checked inside exports and across consecutive exports; the complete frame listing is checked again after capture. Intervening changes, failures or cancellation do not publish a new complete manifest. There is no partial-publication mode.
 
-PNG captures live in immutable `captures/<capture-id>/<baseline-id>.png` generations instead of replacing `<baseline-id>.png`. Read approved image paths from manifest frame `file` fields. Generated Reflection cases already use those paths. `penpair-baselines.json` is the authoritative commit point and is published last with a same-directory atomic rename. Its `casesFile` points to the exact immutable case file for that generation. The root `reflection-cases.json` remains a convenience for existing config imports; when reading it together with a manifest, require matching `captureId`, or follow `casesFile` from the manifest. Independent root files cannot be replaced as one filesystem transaction.
+Baseline captures live in immutable `captures/<capture-id>/<baseline-id>.webp` or `.png` generations. New references default to static lossless WebP; existing PNG references keep PNG during ordinary captures and updates. Historical `<baseline-id>.png` files are not renamed or converted implicitly. Read approved image paths from manifest frame `file` fields. Generated Reflection cases already use those paths. `penpair-baselines.json` is the authoritative commit point and is published last with a same-directory atomic rename. Its `casesFile` points to the exact immutable case file for that generation. The root `reflection-cases.json` remains a convenience for existing config imports; when reading it together with a manifest, require matching `captureId`, or follow `casesFile` from the manifest. Independent root files cannot be replaced as one filesystem transaction.
 
 A process interrupted during output may leave an unreferenced capture generation. Previous manifest references remain usable; inspect before cleaning generations. Staging directories are removed on handled errors. This is filesystem publication safety, not a power-loss-proof multi-file transaction or a remote backup.
 
 Standalone PNG export and full-file archive candidates also stage complete bytes before publication. Archives use exclusive creation and never replace an existing file. PNG exports atomically replace the requested output only after a stable result. The export report includes target provenance. Archive restore verification remains a separate scratch import/readback task.
+
+## Baseline encoding and explicit migration
+
+Always follow the manifest's exact `file` path and encoded-byte hash; do not
+construct a `.png` or `.webp` path from the baseline ID. PNG and WebP with identical
+pixels have different approval identities. An existing reference keeps its
+actual encoding even when `baselines.format` or `--format` selects another
+format. New references choose explicit `--format`, then config, then WebP.
+
+An explicit `--format webp --migrate-format` previews migration. Publishing it
+also requires `--apply --update` and the normal matching exact new-format approval
+(or explicit waiver rules). Earlier immutable generations and owner records
+remain unchanged. See [approval migration](approvals.md#image-format-and-migration).
+
+WebP conversion is lossless and independently verifies decoded RGBA bytes,
+dimensions and ICC preservation. Animation, unsupported bit depth, excessive
+size or pixel/metadata mismatch refuses conversion and preserves the previous
+manifest. Public PNG exports, shot generations and pinned release-source PNG
+renders retain their existing format; baseline defaults do not redefine those
+artifacts.

package/docs/coverage.md

@@ -20,9 +20,9 @@ A baseline frame may declare an explicit viewport, theme label, UI state, fixtur
 
 `theme`, `state` and `fixture` are declared design intent. A label alone does not prove actual theme activation, application state or data loading. Optional `activeThemeIds` asserts the complete exact active native theme-ID set at capture; omit it for a manually styled frame and retain that uncertainty. Baseline capture remains read-only toward the Penpot document: it never switches themes. Use the separate [mode trial](mode-verification.md) for temporary theme switching.
 
-Frame geometry must match the declared CSS viewport within less than 0.01 CSS px per axis, allowing floating-point noise from Penpot transforms and auto sizing. Baseline capture, case approval and offline coverage use the same tolerance. Exported PNG dimensions must still exactly equal the declared viewport multiplied by the observed export scale and rounded to whole pixels; the geometry tolerance never applies to PNG dimensions. A failed viewport/theme assertion marks `case-mismatch`, exits incomplete and preserves the previous generation. New provenance retains raw, unrounded design dimensions, active native theme IDs where available, API/tool version, renderer description and capture time. Font names are declarations; loaded font versions remain unobserved.
+Frame geometry must match the declared CSS viewport within less than 0.01 CSS px per axis, allowing floating-point noise from Penpot transforms and auto sizing. Baseline capture, case approval and offline coverage use the same tolerance. Encoded image dimensions (PNG or static lossless WebP) must still exactly equal the declared viewport multiplied by the observed export scale and rounded to whole pixels; the geometry tolerance never applies to image dimensions. A failed viewport/theme assertion marks `case-mismatch`, exits incomplete and preserves the previous generation. New provenance retains raw, unrounded design dimensions, active native theme IDs where available, API/tool version, renderer description and capture time. Font names are declarations; loaded font versions remain unobserved.
 
-Case metadata is part of approval identity. Changing a fixture/state/theme/viewport declaration requires `--apply --update` even if the PNG bytes happen to match. Moving a matching image to a different file/page/frame identity also requires review. Recapture preserves the original approval until that explicit update. Metadata is pinned before asynchronous capture.
+Case metadata is part of approval identity. Changing a fixture/state/theme/viewport declaration requires `--apply --update` even if the image bytes happen to match. Moving a matching image to a different file/page/frame identity also requires review. Recapture preserves the original approval until that explicit update. Metadata is pinned before asynchronous capture.
 
 ## Required matrix
 
@@ -30,7 +30,7 @@ Add `baselines.coverage.required` as an explicit list of route/viewport/theme/st
 
 See [an example matrix](../examples/coverage-matrix.json) spanning desktop/mobile, light/dark and an empty state. Only request combinations the product intends to support; no matrix is inferred from frame sizes or names.
 
-`penpair baselines coverage --json` runs offline. It loads the version-2 manifest, checks the configured file pin, validates project-bound artifact paths, independently hashes approved PNG bytes and reports:
+`penpair baselines coverage --json` runs offline. It loads the version-2 manifest, checks the configured file pin, validates project-bound artifact paths, independently hashes approved PNG or static lossless WebP bytes and reports:
 
 - `missing-case`: no configured frame for the required tuple.
 - `missing-capture`: a frame is configured but has no approved capture.
@@ -41,7 +41,7 @@ See [an example matrix](../examples/coverage-matrix.json) spanning desktop/mobil
 
 `designCasesComplete` means all requested design slots have matching approved intent. `browserVerification: not-run` and `accessibility: not-assessed` remain separate, even when every design slot is complete. Unknown font loading, absent activation assertions and missing renderer metadata are listed. The offline report exits 3 for gaps; it never connects to Penpot or loads project extensions.
 
-Ordinary `baselines` can publish a coherent capture of its configured frames while the broader required matrix still has gaps; that command returns incomplete when configured requirements remain uncovered. The manifest distinguishes capture completeness from matrix coverage. An incomplete capture itself still publishes nothing. Manifest reads are bounded to 16 MiB and each approved PNG check to 64 MiB; exceeding those bounds cannot produce covered evidence.
+Ordinary `baselines` can publish a coherent capture of its configured frames while the broader required matrix still has gaps; that command returns incomplete when configured requirements remain uncovered. The manifest distinguishes capture completeness from matrix coverage. An incomplete capture itself still publishes nothing. Manifest reads are bounded to 16 MiB and each approved image check to 64 MiB; exceeding those bounds cannot produce covered evidence.
 
 ## Browser integration
 
@@ -62,3 +62,19 @@ Baseline entries require `frame` or `frameId`, or both. `frameId` is a unique bo
 When both are supplied, a different current board name reports `renamed` and the entry is never captured under its stale name. Review the rename and update the expected name before retrying. ID-only entries follow the ID and report its current name. Page searches stop with an explicit error if the 10,000-shape budget truncates the listing.
 
 `approve --case CASE_ID --page PAGE --frame ID` compares `--frame` directly with a configured `frameId`; name-only cases retain the unique-name check. Nested frames use the same exact frame-ID capture identity for approval matching. The baseline manifest continues to record `frameId`; Reflection case format is unchanged.
+
+## Image encoding
+
+New baseline references default to static lossless WebP. Existing PNG references
+and approvals retain their exact original bytes, paths and hashes during normal
+capture/update. Neither `baselines.format` nor `--format` alone migrates an
+existing reference. Use explicit `--format webp --migrate-format` for a preview;
+application also requires `--apply --update` and matching exact new-format image
+approval. A PNG approval does not cover equivalent WebP pixels. See
+[approval and migration](approvals.md#image-format-and-migration).
+
+WebP conversion preserves exact dimensions, decoded RGBA pixels including RGB
+under transparency, and the source ICC profile. Unsupported animated/16-bit
+input or failed conversion verification leaves the prior generation intact.
+The conversion budget is 64 megapixels; geometry tolerance never relaxes image
+pixel-size or pixel-identity checks.

package/docs/design-releases.md

@@ -0,0 +1,162 @@
+# Design releases
+
+A design release freezes a reviewed design handoff for an explicit product SemVer,
+independent of the Penpair package version. It joins
+[journey maps](journey-maps.md), [integration maps](integration-maps.md), exact
+design cases and immutable evidence so a later implementation agent can identify
+what was reviewed. This is a design release, separate from publishing Penpair's
+npm packages or accepting a frontend implementation.
+
+## Local commands
+
+Create the plan from actual source inspection, using your own product SemVer.
+These paths illustrate project-owned inputs. A release accepts at most 100
+selected source screens. Use the local project command, such as
+`pnpm exec penpair`, when installed as a dependency.
+
+```sh
+# Save a planned release, then inspect the remote assembly preview.
+penpair design-release plan --from design/releases/1.0.0/plan.json \
+  --out design/releases/1.0.0/release.json
+penpair design-release assemble --from design/releases/1.0.0/release.json
+
+# After reviewing the preview and authorizing the assembly write:
+penpair design-release assemble --from design/releases/1.0.0/release.json --apply
+```
+
+Next, perform the guided native copy and record actual source/target identities
+in `receipts.json`. Verification reads the live frames and saves evidence;
+finalization below is a preview and records no owner approval.
+
+```sh
+penpair design-release verify --from design/releases/1.0.0/release.json \
+  --receipts design/releases/1.0.0/receipts.json
+penpair design-release finalize --from design/releases/1.0.0/release.json
+penpair design-release check --from design/releases/1.0.0/release.json --live
+penpair design-release context --from design/releases/1.0.0/release.json --draft
+```
+
+Only apply finalization after the owner supplies actual words for the exact
+verified candidate, as described below. After finalization, omit `--draft` to
+request approved context. Missing required proof keeps verification/finalization
+incomplete; these commands do not bypass the native support limits.
+
+## Prepare and assemble
+
+Use the `design-release` command family to plan, assemble, verify, finalize,
+check and produce context. Use the installed command's help for current argument
+names. Planning exposes required inputs and unresolved work. Assembly records
+identities and hashes; it does not invent source observations or owner approval.
+Each selected source needs its complete `inspection` reference (project-relative
+`path` and exact `sha256`). Pin a stable source PNG through its `render` reference
+before verification; a draft without this reference cannot pass fidelity. A
+source using tokens also needs a complete pinned token-inspection `dependencies`
+reference. Required dependency changes invalidate the pinned source evidence.
+
+Include the parent and every linked detail-map contract in the release's
+`contracts` list, each with its independent exact review. A reviewed parent link
+is not approval of the child graph. See [linked detail maps](integration-maps.md#linked-detail-maps).
+
+Keep the release page in the same pinned Penpot file, named `release/<version>`.
+Assembly creates the owned overview/map sections and reports `awaiting-copy`.
+Copy source design frames natively using a reviewed, guided copy/paste operation
+by a person or an authorized AI using existing browser tools. Assembly does not
+perform an unsupported cross-page clone.
+Preserve visual fidelity, native components, token bindings, text and layout;
+do not recreate frames from screenshots or normalize their dimensions. A source
+using auto height must retain it. Floating-point geometry noise is not a reason
+to change source sizing.
+
+The live sequence is read-only inspection, pinned snapshot, one idempotent write,
+independent readback and stable exports that are looked at. Snippets stay under
+90 KB. If a write response is uncertain, inspect what exists before retrying.
+Keep unmanaged content intact; a page name alone cannot authorize replacement.
+Do not copy via a lossy or structurally incomplete fallback when native fidelity
+cannot be established: report the missing proof.
+
+## Supported native verification limits
+
+Native verification is deliberately narrower than native copy/paste. Selecting a
+screen for this workflow does not establish that its content can be verified.
+The current verifier blocks these cases:
+
+- **All component instances, copies, main instances and component roots.** The
+  inspection cannot establish complete override state. Retaining links during a
+  copy is required, but it does not prove override fidelity.
+- **Groups without an explicit `maskedGroup` observation.** An absent mask flag
+  is unknown, not proof that the group is unmasked.
+- **Unknown text range/style observations**, including unobserved mixed-range
+  state, and any other unknown or missing required inspection field.
+- **Paths/vector shapes whose actual path content was not observed.** A path
+  type or matching raster export cannot establish the native path data.
+- Unsupported shape content, incomplete hierarchy, unobservable interactions or
+  missing pinned source render/dependency evidence.
+
+A selected screen containing one of these cases remains blocked with a reason;
+it cannot be finalized by waiving the finding or accepting equal pixels. Retain
+its native structure and source evidence, then obtain the missing observation or
+extend and validate inspection support before retrying. Do not detach components,
+flatten groups, remove styles or substitute raster images to bypass the gate.
+Simple screens whose required fields are fully observed can be assessed, but
+that is not a claim of complete support for every native Penpot feature.
+
+## Verify the package
+
+Supply a project-owned receipt list with explicit `sourceId` and
+`targetFrameId` values to `verify --receipts FILE`. Check release frame identities
+against the selected sources and retain immutable inspection/export evidence
+with exact paths and hashes. Compare source and release frames independently,
+including component/token identity and sizing
+behavior, and inspect stable exports. A current rendering cannot rewrite the
+bytes of an already recorded artifact. Native release objects remain mutable,
+including changes inherited through shared components and tokens. A later change
+is drift and needs a new reviewed generation, not a silent refresh of finalized
+evidence.
+
+New baseline evidence uses lossless WebP. Existing PNG baselines and image
+approvals remain valid in their original format. Conversion must be a deliberate
+migration with new evidence and review; never change approved bytes in place.
+Penpot can supply PNG during export, so conversion must retain exact dimensions
+and pixels. Quality 100 alone does not establish lossless encoding.
+
+The release needs matching exact-artifact review records and no unresolved
+blocking findings. Preserve the distinction between:
+
+- Map review: the owner's supplied words bind an exact contract hash.
+- Design image approval: the existing exact case/image approval protocol.
+- Technical verification: independently observed structure and image evidence.
+- Implementation acceptance: actual application behavior, browser evidence and
+  owner review, assessed separately after implementation.
+
+## Finalize and continue
+
+The release record progresses from `planned` through `awaiting-copy` and
+`verified` to `final`. Finalization records the reviewed release identity and
+immutable evidence. It must not promote missing evidence, waivers or inferred owner approval into a
+successful design gate. Finalized means the design package is ready to guide
+implementation; it does not mean the application has been built or checked.
+
+Finalization previews by default. Only use `finalize --apply --by OWNER --note
+EXACT_WORDS` after the owner has supplied those words for the exact candidate.
+Keep journal/run identity when reconciling interrupted remote work.
+
+Run checks again before using the package later. Missing or modified artifacts,
+changed map/source hashes and changed release evidence must remain visible as
+drift or incomplete evidence. A saved-source check does not contact Penpot;
+live freshness requires an explicit fresh observation. Context must identify
+its verification scope and any truncation. Release context includes actual frozen
+`mapContexts`, exact release-page `mapTargets`, independently pending implementation
+status and next actions. Linked detail navigation targets the release's own child
+boards; each child contract retains its separate review requirement.
+Its `proposedBaselines` is a configuration fragment with the release page, WebP
+format, baseline root and explicit target `frameId` entries. Review and merge it
+into the existing `baselines` block; context does not rewrite project config or
+approve the new target image identities.
+
+Use `penpair-handoff` with the approved integration context, then `penpair-verify`
+for the actual frontend. Keep those later implementation results separately;
+never rewrite the finalized design to match an implementation failure.
+
+The [reset-password example](../examples/design-release-maps/README.md) is an
+unapproved fixture showing decisions and gaps. It is not a finalized release or
+proof of a live Penpot copy.

package/docs/guide.md

@@ -10,6 +10,7 @@ consumer evidence.
 | Path | Documents |
 | --- | --- |
 | First run / shared file | [Choose an installation route](installation.md), [manual installation](getting-started.md), [team](team.md), [validation](validation.md) |
+| Intent / release | [Journey maps](journey-maps.md), [integration maps](integration-maps.md), [design releases](design-releases.md) |
 | Build / handoff | [Cookbook](cookbook.md), [workflow](design-workflow.md), [kit](build-kit.md), [file scripts](run-file.md), [handoff](handoff.md) |
 | Evidence | [Inspection](inspection.md), [advisory audits](audits.md), [snapshots](snapshots.md), [approvals](approvals.md), [coverage](coverage.md), [artifacts](artifacts.md) |
 | Integration | [Companion adapters](adapters.md), [MCP](mcp.md), [formats](formats.md), [extension trust](extensions-trust.md), [credentials](credentials.md), [token adapter](marwes.md) |
@@ -95,6 +96,7 @@ For registered writes, supply an explicit `verify({ inspect, apply, readback })`
 "baselines": {
   "page": "Candidate",
   "root": "tests/baselines",
+  "format": "webp",
   "threshold": 0.05,
   "frames": [
     { "frame": "F / candidates", "id": "candidates-desktop", "route": "candidates" },
@@ -107,8 +109,23 @@ For registered writes, supply an explicit `verify({ inspect, apply, readback })`
 - Each entry requires `frame` or `frameId` (or both). `frameId` is a board UUID, unique across entries, resolved anywhere on the configured page. Frames inside boards, such as release frames inside section boards, need `frameId`. Name-only entries still match top-level frames only.
 - With both fields, `frame` is an expected name: a changed name reports `renamed` and captures nothing for that entry. Review and update the expected name before retrying. ID-only entries use the board's current name in reports. A truncated page search (10,000 shapes) stops the capture instead of using a partial listing.
 - For example: `{ "frameId": "10216397-acdf-805e-8008-d69b71f841d4", "frame": "Login / Empty", "id": "login-empty", "route": "login" }`.
-- `id` names the image (`<id>.png`) and the check. `route` is the route in your app this frame is the design of; a frame without a route is exported but gets no check.
-- Without `--apply` the command only looks and reports each frame as `new`, `same`, `changed`, `unstable` (the export never settled) or `missing`/`renamed`. `--apply` writes new images, `penpair-baselines.json` (file, revision, sizes, hashes) and `reflection-cases.json`. A `changed` image is replaced only with `--apply --update`: that is the act of approving the new design, and the owner's call. The exit code is 2 when a design differs from its image, 3 when a frame is missing, renamed or unstable.
+- `id` names the image (`<id>.webp` for a new default reference; existing PNG references retain `.png`) and the check. `route` is the route in your app this frame is the design of; a frame without a route is exported but gets no check.
+- Without `--apply` the command only looks and reports each frame as `new`, `same`, `changed`, `unstable` (the export never settled) or `missing`/`renamed`. `--apply` writes new images, `penpair-baselines.json` (file, revision, sizes, hashes) and `reflection-cases.json`. A `changed` image is replaced only with `--apply --update` and matching exact-artifact owner approval (or an explicitly recorded waiver); see [approval records](approvals.md). The exit code is 2 when a design differs from its image, 3 when a frame is missing, renamed or unstable.
+
+New references default to static lossless WebP. `baselines.format` accepts
+`"webp"` or `"png"`; a command's `--format` overrides that choice for new
+references. Existing approved images keep their original encoding during ordinary
+captures and updates, even when config or `--format` selects another format.
+Approved byte hashes are never silently converted.
+
+To preview an explicit migration, run `penpair baselines --format webp
+--migrate-format`. After reviewing and recording matching new-format approval,
+apply it with `penpair baselines --format webp --migrate-format --apply --update`.
+`--migrate-format` requires explicit `--format`, and applying it requires
+`--update`. Use `approve --format webp` (plus the intended `--case`, when present)
+to review/record the same encoding; PNG approval cannot approve WebP bytes.
+See [approval and migration details](approvals.md#image-format-and-migration).
+Public `export` and `shots` remain PNG.
 
 The generated `reflection-cases.json` holds, per route, the viewports (the image's exact size) and the `visualSmoke` cases (review-only, `strict: false`). A Reflection config uses it like this; only the route's own expectations are written by hand:
 
@@ -169,6 +186,6 @@ Use `inspect <shape-id> --page <name> --all` for bounded structured evidence wit
 
 ## State, theme and responsive coverage
 
-Add explicit `frames[].case` metadata and a required matrix under `baselines.coverage`. Case geometry allows less than 0.01 CSS px of Penpot floating-point noise per axis; exported PNG dimensions remain exact at the capture scale, and raw geometry stays in provenance. `baselines coverage --json` validates approved images offline and exposes missing/unsupported slots. Rich cases remain pending browser setup mappings; see [coverage semantics and approval](coverage.md).
+Add explicit `frames[].case` metadata and a required matrix under `baselines.coverage`. Case geometry allows less than 0.01 CSS px of Penpot floating-point noise per axis; encoded image dimensions (PNG or lossless WebP) remain exact at the capture scale, and raw geometry stays in provenance. `baselines coverage --json` validates approved images offline and exposes missing/unsupported slots. Rich cases remain pending browser setup mappings; see [coverage semantics and approval](coverage.md).
 
 For project-specific agent tools, use the [explicit-root stdio server and client examples](mcp.md). It exposes typed guarded services and defaults to omitting design-write tools.

package/docs/handoff.md

@@ -29,6 +29,6 @@ An optional schema-1 component map names exact source identities:
 
 Names and equal pixels do not establish a mapping. There are no guessed library IDs in shipped maps: the adapter's native component catalogue awaits C1 proof. Static scalar props are owner-declared hints; text props resolve only explicit descendants of that instance. Missing text IDs stay unknown. No inferred click handlers, state transitions, keyboard behavior, accessibility roles, focus order or responsive layout claims are emitted. The current recorded state does not describe every breakpoint or theme.
 
-`spec check` regenerates from the supplied structured capture and map, detecting manual edits, source/revision changes and mapping changes (exit 2). It does not contact Penpot or establish current live freshness. A PNG export manifest alone cannot prove structural/text freshness; use a new structured inspection rather than treating an unchanged image as proof. Live human handoff/adoption acceptance remains pending under I12; native mapping generation remains gated under C1. JSON output uses the shared command envelope.
+`spec check` regenerates from the supplied structured capture and map, detecting manual edits, source/revision changes and mapping changes (exit 2). It does not contact Penpot or establish current live freshness. An image export manifest alone cannot prove structural/text freshness; use a new structured inspection rather than treating an unchanged image as proof. Live human handoff/adoption acceptance remains pending under I12; native mapping generation remains gated under C1. JSON output uses the shared command envelope.
 
 Owner review can be retained as an [exact-artifact approval record](approvals.md). Changed baseline references require matching supplied owner words or an explicitly labeled waiver; a comparison metric does not supply approval.

package/docs/integration-maps.md

@@ -0,0 +1,171 @@
+# Integration maps
+
+An integration map links a reviewed user journey to the screens, routes,
+components, state, data and verification work needed to implement it. It gives
+agents a shared project record of what the solution must present and what the
+current implementation actually presents.
+
+Start with the [journey map](journey-maps.md) and complete [design evidence](handoff.md).
+Inspect existing code before proposing new modules. Reuse project architecture;
+a visual frame does not justify inventing a backend or component framework.
+
+## Local commands
+
+```sh
+penpair integration-map check --from design/integrations/reset-password/map.json
+penpair integration-map render --from design/integrations/reset-password/map.json --out design/integrations/reset-password/rendered
+penpair integration-map context --from design/integrations/reset-password/map.json --out design/integrations/reset-password/context.json
+```
+
+Use the local project command when installed as a dependency. Add `--live` to a
+check only when an explicit fresh Penpot observation is needed; ordinary saved
+input validation does not establish current live freshness.
+
+## Record the gaps before building
+
+Use stable requirements and connect each to relevant design cases, proposed or
+existing code responsibilities, data contracts and verification evidence. Mark
+claims `observed`, `proposed`, `owner-decision` or `unknown`. Distinguish visible
+screen state from inferred behavior, and application intent from observed code.
+Keep unresolved component identity, API behavior and accessibility semantics
+explicit.
+
+| Requirement | Design observation | Implementation observation | Finding and next action |
+| --- | --- | --- | --- |
+| `reset-error-retry` | Illustrative design has a retryable error with the address retained | Hypothetical implementation clears the address after a failed request | Blocking: the person must retype their address. Preserve the value and verify the failed-request/retry path; this example is not observed project evidence. |
+
+Compare both directions: intended requirements without implementation, and
+implemented behavior without an agreed rationale. Link concrete source/evidence
+rather than reporting that a diagram or passing build proves completeness.
+
+## Contract, drawings and edits
+
+A schema-1 `integration-map` contract uses the same sources, nodes, edges,
+requirements and findings as a journey contract. Its `journey` reference binds the
+project-relative path and exact SHA-256 of its journey map. Component mapping
+still requires exact source identities as described in [handoff](handoff.md);
+familiar labels are insufficient.
+
+The `integration-map` command family checks a contract, renders derived diagrams,
+publishes managed native objects, imports native edits as a reviewable proposal,
+accepts a proposal, records supplied owner review and emits bounded context.
+Read installed help for exact arguments. Do not equate `accept` of an edit
+proposal with owner `approve`, image approval or implementation acceptance.
+
+Canonical JSON is authoritative. Mermaid, drawing plans and native Penpot boards
+are derived views tied to its hash. A managed Penpot edit must become a proposal
+against that hash; inspect the changes before accepting them. Unmanaged shapes
+and ambiguous identities are not automatic contract edits. Publishing and
+updating native drawings follow the full Penpot write protocol.
+
+Semantic native import writes both the canonical proposal and a bound adjacent
+`<proposal>.native.json` observation. Preserve both. Native acceptance rechecks
+the live observation read-only before changing the canonical contract and saved
+baseline; afterward republish explicitly to update native contract metadata.
+A purely local semantic proposal without native observation can be accepted
+offline. If canonical acceptance succeeded but saving the projection failed,
+reconcile with the same proposal rather than blindly publishing again.
+
+Geometry-only edits use a separate `map-presentation-proposal`. Acceptance checks
+the exact canonical hash, saved baseline and current observed projection, captures
+fresh stable evidence and adopts presentation without changing canonical bytes.
+Renew native visual review: old review does not automatically cover new render
+evidence. Future publication preserves accepted node positions and sizes.
+Unsupported style/ownership changes and unmanaged objects remain conflicts.
+
+Use clear typography, short labels and a neutral diagram theme. The diagram's
+font defaults to Inter; an explicit presentation override belongs to the map.
+Diagram presentation must not modify the application's tokens or theme.
+
+## Readable titles and descriptions
+
+Existing contracts remain supported. Optional map `summary` and `description`
+add a short introduction and detailed context. A node's existing `label` remains
+its title; optional `summary`, `description` and `icon` supply a one-line purpose,
+longer explanation and semantic icon. Keep labels specific and concise instead
+of repeating “proposed” or “unknown”; the origin badge supplies that distinction.
+Descriptions still need to explain which evidence supports a claim and which
+questions remain unresolved.
+
+Native cards use compact titles, summaries, icons and connector ports. Full
+original text and long descriptions remain in managed notes below the flow and
+in generated Markdown/context; they must not disappear when card text is shortened.
+Descriptions and icons belong to canonical intent: edits need proposal review and
+renewed approval. Use one fixed icon key: `screen`, `action`, `decision`, `data`,
+`service`, `code`, `check` or `link`. Icons use native vector paths, with no external
+image URLs or asset downloads.
+
+## Linked detail maps
+
+Decompose oversized maps explicitly; Penpair does not automatically partition a
+contract. Give each detail map its own canonical contract, native publication
+and owner review. In the parent, a `kind: "detail-link"` node references exactly
+one `sourceId`: that source must have `kind: "contract"`, a project-relative
+`path`, the raw file-byte `sha256`, and exact `fileId`, `pageId` and `frameId` of
+the published detail board in the same pinned file. This source byte hash is
+distinct from the canonical hash used by a journey reference.
+
+The linked child must have the same map kind as the parent. The link covers at
+least one parent requirement through `requirementIds`, and the child retains
+all those requirement IDs. Generated Markdown links to the contract; the native
+card uses a `NavigateTo` interaction to its declared board. Missing/stale source
+bytes or incompatible child requirements prevent readiness.
+
+Parent context identifies the child handoff and its independent review rather
+than inlining the child graph. Later agents must read that child contract too.
+Include every parent and linked detail contract in the design release with its
+own exact review. Publishing or approving the parent does not publish or approve
+its detail maps.
+
+## Implementation context
+
+A context result should identify the exact map and journey, review/freshness,
+open findings, requirements and linked source evidence. Bounded or truncated
+context must say so; missing evidence remains pending. Freshness against supplied
+saved files does not assert live Penpot freshness or functional correctness.
+
+Later agents should:
+
+1. Read the current map context and linked sources before implementing.
+2. Surface stale inputs and blocking findings before relying on approval.
+3. Implement within the reviewed scope; propose changes to intent separately.
+4. Attach actual route/state, browser and behavior evidence to the project record.
+5. Reconcile findings and seek implementation acceptance independently.
+
+Use [Reflection Check](adapters.md#check-the-frontend-against-the-design) for actual
+browser comparisons. It supplies visual evidence; behavior and accessibility
+need their own checks. A low pixel difference does not approve architecture or
+prove a working recovery flow.
+
+## Design readiness and implementation readiness
+
+A [design release](design-releases.md) can finalize a reviewed, internally
+consistent design package while implementation is still `not-assessed`. That
+separation is intentional: agents need stable approved design context before
+they build. Never mark implementation accepted because a map was approved.
+
+See the [worked reset-password example](../examples/design-release-maps/README.md)
+for a proposed journey and integration map with visible unknowns.
+
+Every local requirement must appear in a node or edge's `requirementIds`, and an
+integration map retains all requirement IDs from its linked journey. Omitted
+coverage prevents readiness and design finalization; drafts can still be checked
+and rendered. Drawing plans explicitly become incomplete above a 16,384 px axis
+or 64 KiB serialized plan budget. Split the map instead of publishing clipped
+content.
+
+## Publication recovery
+
+After an uncertain write, inspect the actual target and retained run first. Resume
+the original journal explicitly, keeping the original contract, sources and
+target flags (including whether `--board-id` was omitted):
+
+```sh
+penpair integration-map publish --from design/integrations/reset-password/map.json \
+  --page-id PAGE_ID --apply --resume RUN_ID
+```
+
+Use the original `--board-id` and `--projection` options if they were supplied.
+Resume independently reconciles readback and exports; it does not blindly repeat
+the write. Changed input or code signatures must refuse reuse. Inspect again and
+start a new explicitly authorized run when needed; do not bypass those guards.

package/docs/journey-maps.md

@@ -0,0 +1,139 @@
+# Journey maps
+
+A journey map records what a person is trying to accomplish, which states they
+encounter, and the decisions still needed before implementation. It is a
+project-owned contract that later agents can read without recovering earlier
+chats. Use an [integration map](integration-maps.md) to connect the journey to
+application structure, and a [design release](design-releases.md) to freeze a
+reviewed design handoff.
+
+## Local commands
+
+```sh
+penpair journey-map check --from design/journeys/reset-password/map.json
+penpair journey-map render --from design/journeys/reset-password/map.json --out design/journeys/reset-password/rendered
+penpair journey-map context --from design/journeys/reset-password/map.json --out design/journeys/reset-password/context.json
+```
+
+Use your project's local command, such as `pnpm exec penpair`, when installed as
+an application dependency. Rendering with `--out` writes local derived artifacts;
+it does not publish into Penpot. Context is intended for reviewed inputs; drafts
+must be explicit and cannot imply readiness.
+
+## Start from observed intent
+
+Inspect the actual frames and existing application before drafting. Record the
+user goal, entry points, successful outcome, alternate paths and recovery. Use
+stable requirement and node IDs so a finding can refer to the same requirement
+through review and implementation. A frame establishes visible design facts;
+it does not establish what a button does, how an API behaves or how keyboard
+focus moves.
+
+Every node, edge and requirement declares its origin:
+
+| Origin | Meaning |
+| --- | --- |
+| `observed` | Directly supported by the referenced design, code or evidence |
+| `proposed` | An AI or designer recommendation awaiting a decision |
+| `owner-decision` | A decision actually supplied by the owner |
+| `unknown` | Missing information; retain it as a question |
+
+An origin is provenance, not approval. In particular, an `owner-decision` label
+cannot replace a review record binding the owner's actual words to the exact
+contract hash. Do not turn guesses into observations or invent approval notes.
+
+## Keep the flow readable
+
+Use short, specific node titles (`label`), optional one-line `summary` and longer
+`description` text for evidence, decisions and unknowns. The map itself also
+accepts optional `summary` and `description`. Origin badges distinguish observed
+facts from proposals without repeating that status in every title. Optional
+semantic `icon` values use fixed native vectors. Full notes remain available
+below the flow and in Markdown/context; legacy contracts need no new fields.
+See [titles and descriptions](integration-maps.md#readable-titles-and-descriptions).
+These optional fields are part of reviewed canonical intent, so changing them
+needs renewed approval.
+
+## Contract and review
+
+The schema-1 JSON contract contains `kind: "journey-map"`, `id`, `title`, `goal`,
+`sources`, `nodes`, `edges`, `requirements` and `findings`. Sources retain their
+SHA-256 and available path/file/page/frame/revision identity. Nodes and edges
+carry readable labels and stable IDs; requirement links connect them to the
+intended outcomes. Open blocking findings keep readiness pending. Resolving a
+finding requires an explicit resolution, rather than deleting its history.
+
+The `journey-map` command family supports checking, rendering, publishing,
+importing managed edits as proposals, accepting proposals, recording supplied
+approval, and producing bounded context. Consult the installed command's help
+for arguments. Checking and rendering locally do not approve or publish a map.
+Native publication is a Penpot write and needs the normal inspection, pinned
+snapshot, one idempotent write, independent readback and inspected stable export.
+Check the exported typeface against the canvas: a font available to the editor
+can still be unavailable to its exporter. Correct font metadata and identical
+consecutive exports do not prove font fidelity. Visible font substitution needs
+correction before visual approval.
+
+The contract is authoritative; Mermaid and native Penpot objects are derived
+views. Managed native edits become a proposal against the exact prior contract
+hash. Review the diff and accept it explicitly before regenerating dependent
+views. A changed label or connector must not silently rewrite accepted intent.
+An old proposal cannot overwrite a newer contract.
+
+Owner review is a separate `artifact-review` record containing the artifact
+identity, exact hash, supplied words, identity, date and record hash. Review is
+not authenticated identity. Changed contracts or source hashes need fresh review;
+matching saved inputs do not prove the live file is unchanged.
+
+## Review gates
+
+1. **Intent ready:** the goal, success/recovery paths, evidence and unknowns are
+   explicit. Blocking questions are answered or remain visibly blocking.
+2. **Contract reviewed:** the owner reviewed the exact map and supporting
+   decisions. Technical checks and a neat diagram do not supply acceptance.
+3. **Handoff ready:** the integration map references this exact journey hash,
+   required design cases exist, and outstanding implementation work is explicit.
+
+## Reset-password example
+
+The [worked example](../examples/design-release-maps/README.md) describes an
+illustrative reset flow. An observed confirmation frame is distinct from a
+proposed submission transition and an unknown expiry policy. The example is
+unapproved and contains no fabricated inspection or owner evidence.
+
+Keep loading, empty, error and success states proportionate to the feature.
+Capture keyboard entry, focus movement, error announcements and responsive
+behavior as explicit requirements or unknowns. The map does not establish that
+any of these behaviors has been implemented or tested.
+
+Contracts are bounded to 16 MiB, 1,000 nodes and 2,000 edges. Context has a
+128 KiB limit and reports omissions explicitly. Source paths remain inside the
+project. Labels and descriptions are escaped literal data in generated views.
+
+Every local requirement must be connected through node/edge `requirementIds`.
+A readable graph with unmapped requirements remains incomplete for readiness.
+Drawing plans also refuse complete native publication above a 16,384 px axis or
+64 KiB serialized plan size; split large maps into reviewable parts. Semantic
+native imports retain a bound adjacent `.native.json` observation and require
+fresh live readback during acceptance. Pure geometry changes instead produce a
+presentation proposal, preserve canonical intent and require fresh visual review.
+
+For explicit decomposition, use [linked detail maps](integration-maps.md#linked-detail-maps).
+Journey details remain journey contracts, with independent publication and review;
+parent approval does not cover a child map automatically.
+
+## Publication recovery
+
+After an uncertain write, inspect the actual target and retained run first. Resume
+the original journal explicitly, keeping the original contract, sources and
+target flags (including whether `--board-id` was omitted):
+
+```sh
+penpair journey-map publish --from design/journeys/reset-password/map.json \
+  --page-id PAGE_ID --apply --resume RUN_ID
+```
+
+Use the original `--board-id` and `--projection` options if they were supplied.
+Resume independently reconciles readback and exports; it does not blindly repeat
+the write. Changed input or code signatures must refuse reuse. Inspect again and
+start a new explicitly authorized run when needed; do not bypass those guards.

package/examples/design-release-maps/README.md

@@ -0,0 +1,72 @@
+# Reviewed-map workflow example
+
+These contracts describe a **synthetic, unapproved** reset-password feature.
+They are valid draft inputs, not a real Penpot inspection, code audit, owner
+review or finalized design release. `sample-source.md` is their only observed
+source. Proposed application architecture and unknown policy stay labeled.
+
+From the repository root:
+
+```sh
+pnpm build
+node packages/web/dist/cli.js journey-map render --from examples/design-release-maps/journey.json
+node packages/web/dist/cli.js integration-map render --from examples/design-release-maps/integration.json
+```
+
+Use the installed CLI entrypoint when working from a packaged installation.
+Rendering is offline and establishes neither owner approval nor live fidelity.
+Checks/context should retain the open blockers and missing reviews; this fixture
+is intentionally not ready for implementation or release finalization.
+
+## Read the map
+
+```mermaid
+flowchart LR
+    Entry["Enter email"]
+    Confirm["Check your email"]
+    Error["Retry request"]
+    Entry -->|"Success"| Confirm
+    Entry -->|"Failure"| Error
+    Error -->|"Retry"| Entry
+```
+
+Each JSON node uses a concise `label` as its title, a one-line `summary`, a
+longer `description` for evidence and decisions, and a fixed semantic `icon`.
+Native cards show the compact title/summary with origin badges; detailed notes
+retain the full explanation below the flow. The short labels above do not
+change provenance: entry/confirmation are observations of the synthetic text,
+while success, failure and retry behavior remain proposals. Policy and actual
+code/browser evidence remain unknown.
+
+This short illustration explains the intended flow; the JSON contract remains
+authoritative. Generate full Mermaid/native drawing plans from it rather than
+editing this illustration as if it updated the contract. A native drawing is
+editable, but managed semantic changes must be imported as proposals, reviewed,
+accepted against their base hash and approved again.
+
+| Requirement | Intended result | Hypothetical mismatch | Next action |
+| --- | --- | --- | --- |
+| `reset-error-retry` | Keep the address after a failed request and allow retry | An implementation clears it and makes the person retype it | Confirm the proposed behavior, then test a real failed request and retry. This row is not observed project evidence. |
+
+## Three review gates
+
+1. **Intent ready:** inspect real source frames; decide request, disclosure,
+   expiry, recovery, loading and focus behavior. Do not convert unknown policy
+   into an inferred security rule.
+2. **Design package reviewed:** replace synthetic sources with actual inspection
+   paths/hashes, review the exact journey/integration maps, assemble target
+   native frames in `release/<product-version>`, verify fidelity, then obtain
+   the actual owner words for the exact release candidate. Source image
+   approval does not approve new target frame identities.
+3. **Implementation accepted:** implement against that stable context, observe
+   actual route/state/fixture behavior, compare browser images, test recovery
+   and accessibility, and review the results. Finalized design alone cannot
+   satisfy this gate.
+
+No release plan with invented file IDs, frame IDs, transfer receipts or owner
+words is included. Create a plan only after inspecting the actual pinned file
+and selecting sources. The [release guide](../../docs/design-releases.md)
+describes the native copy, immutable evidence and later drift checks.
+
+New baselines default to static lossless WebP. Preserve existing approved PNG
+bytes; format migration is explicit and requires normal exact-byte review.

package/examples/design-release-maps/integration.json

@@ -0,0 +1,181 @@
+{
+  "schemaVersion": 1,
+  "kind": "integration-map",
+  "id": "reset-password-integration",
+  "title": "Reset implementation",
+  "goal": "Connect the proposed reset flow to implementation responsibilities without inventing existing code.",
+  "sources": [
+    {
+      "id": "sample-brief",
+      "kind": "other",
+      "path": "examples/design-release-maps/sample-source.md",
+      "sha256": "ab97f0a30f066e9a9f2689d1624608ea91287751cbc6a613542c0e97de187a96"
+    }
+  ],
+  "journey": {
+    "path": "examples/design-release-maps/journey.json",
+    "sha256": "956fbe3e9d4eb3519d714912ec89bfaedd2a8c2b8882d06dc5ee9c4c279439a9"
+  },
+  "nodes": [
+    {
+      "id": "reset-route",
+      "label": "Reset route",
+      "kind": "route",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-entry"
+      ],
+      "summary": "Open /reset-password to begin the flow.",
+      "description": "Proposed route responsibility: enter the reset flow using the existing application router. The route and surrounding navigation have not been inspected. Reuse the actual project structure rather than treating this illustrative path as an approved architecture decision.",
+      "icon": "code"
+    },
+    {
+      "id": "reset-form",
+      "label": "Reset form",
+      "kind": "component",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-entry",
+        "reset-error-retry"
+      ],
+      "summary": "Collect an address and retain it on retry.",
+      "description": "Proposed form responsibility: collect the address, follow agreed validation and preserve input during recoverable failure. Inspect existing components before choosing an implementation. Form semantics and behavior need explicit review and real browser evidence.",
+      "icon": "screen"
+    },
+    {
+      "id": "reset-mutation",
+      "label": "Reset service",
+      "kind": "data",
+      "origin": "unknown",
+      "requirementIds": [
+        "reset-request",
+        "reset-expiry"
+      ],
+      "summary": "Agree the request and response contract.",
+      "description": "The endpoint, request payload, validation, response policy and expiry behavior are unknown. Obtain the actual project API and product decisions before implementation. This node does not claim that a service exists or prescribe a new backend.",
+      "icon": "service"
+    },
+    {
+      "id": "reset-feedback",
+      "label": "Request feedback",
+      "kind": "state",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-error-retry",
+        "reset-confirmation",
+        "reset-focus"
+      ],
+      "summary": "Show confirmation or a recoverable error.",
+      "description": "Proposed feedback responsibility: present the agreed confirmation state after an accepted request and useful recovery after failure. Define focus and announcements with the actual application. The synthetic source does not establish these transitions or their accessibility.",
+      "icon": "decision"
+    },
+    {
+      "id": "browser-case",
+      "label": "Verify recovery",
+      "kind": "verification",
+      "origin": "unknown",
+      "requirementIds": [
+        "reset-error-retry",
+        "reset-confirmation",
+        "reset-focus",
+        "reset-expiry"
+      ],
+      "summary": "Check retry, focus, and announcements.",
+      "description": "Verification is pending. Map approved design cases to actual route/state/fixture setup, then observe failed submission, retained input, retry and confirmation in the real browser. Assess keyboard and screen-reader behavior separately from visual comparison. No provider or result is supplied here.",
+      "icon": "check"
+    }
+  ],
+  "edges": [
+    {
+      "id": "route-form",
+      "from": "reset-route",
+      "to": "reset-form",
+      "label": "Compose",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-entry"
+      ]
+    },
+    {
+      "id": "form-request",
+      "from": "reset-form",
+      "to": "reset-mutation",
+      "label": "Submit",
+      "origin": "unknown",
+      "requirementIds": [
+        "reset-request"
+      ]
+    },
+    {
+      "id": "request-feedback",
+      "from": "reset-mutation",
+      "to": "reset-feedback",
+      "label": "Handle result",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-error-retry"
+      ]
+    },
+    {
+      "id": "feedback-evidence",
+      "from": "reset-feedback",
+      "to": "browser-case",
+      "label": "Verify behavior",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-error-retry"
+      ]
+    }
+  ],
+  "requirements": [
+    {
+      "id": "reset-entry",
+      "text": "Proposed: map the entry screen to the project route and existing form conventions after inspecting code.",
+      "origin": "proposed"
+    },
+    {
+      "id": "reset-request",
+      "text": "Unknown: endpoint, validation and response policy require the actual project contract.",
+      "origin": "unknown"
+    },
+    {
+      "id": "reset-error-retry",
+      "text": "Proposed: retain the entered address on failure; verify retry and accessible feedback in the real browser.",
+      "origin": "proposed"
+    },
+    {
+      "id": "reset-confirmation",
+      "text": "Proposed: render confirmation only after the agreed response; final request policy remains unknown.",
+      "origin": "proposed"
+    },
+    {
+      "id": "reset-expiry",
+      "text": "Unknown: expiry/repeated request behavior must follow the agreed product/security contract.",
+      "origin": "unknown"
+    },
+    {
+      "id": "reset-focus",
+      "text": "Proposed: implement and verify keyboard focus and announced error recovery.",
+      "origin": "proposed"
+    }
+  ],
+  "findings": [
+    {
+      "id": "code-not-inspected",
+      "message": "No application code, route or component identity has been inspected for this synthetic example.",
+      "severity": "blocking",
+      "status": "open"
+    },
+    {
+      "id": "provider-pending",
+      "message": "No approved design cases, actual provider or browser evidence are supplied.",
+      "severity": "blocking",
+      "status": "open"
+    }
+  ],
+  "presentation": {
+    "fontFamily": "Inter"
+  },
+  "summary": "Connect the reset flow to application responsibilities.",
+  "description": "This unapproved integration proposal links the synthetic journey to a route, form, service contract, feedback states and verification work. No application code, API or browser behavior has been inspected. Every proposed responsibility needs project evidence and review before implementation."
+}

package/examples/design-release-maps/journey.json

@@ -0,0 +1,187 @@
+{
+  "schemaVersion": 1,
+  "kind": "journey-map",
+  "id": "reset-password-journey",
+  "title": "Reset password",
+  "goal": "Request password-reset instructions and understand the next step.",
+  "sources": [
+    {
+      "id": "sample-brief",
+      "kind": "other",
+      "path": "examples/design-release-maps/sample-source.md",
+      "sha256": "ab97f0a30f066e9a9f2689d1624608ea91287751cbc6a613542c0e97de187a96"
+    }
+  ],
+  "nodes": [
+    {
+      "id": "address-entry",
+      "label": "Enter email",
+      "kind": "screen",
+      "origin": "observed",
+      "sourceIds": [
+        "sample-brief"
+      ],
+      "requirementIds": [
+        "reset-entry"
+      ],
+      "summary": "Provide an address for reset instructions.",
+      "description": "The synthetic brief includes an address-entry screen. No Penpot frame or application has been inspected. Field validation, submission behavior and the final wording still require project evidence or review.",
+      "icon": "screen"
+    },
+    {
+      "id": "confirmation",
+      "label": "Check your email",
+      "kind": "screen",
+      "origin": "observed",
+      "sourceIds": [
+        "sample-brief"
+      ],
+      "requirementIds": [
+        "reset-confirmation"
+      ],
+      "summary": "Explain the next step after the request.",
+      "description": "The synthetic brief includes a confirmation screen. Its success transition and response messaging are proposed, not observed. Confirm the actual request and account-disclosure policy before implementing this state.",
+      "icon": "screen"
+    },
+    {
+      "id": "recoverable-error",
+      "label": "Retry request",
+      "kind": "state",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-error-retry"
+      ],
+      "summary": "Keep the address and offer a retry.",
+      "description": "Proposed recovery preserves the entered address after a failed request, explains the failure and allows another attempt. No inspected design or implementation establishes this behavior yet. Review it, then verify a real failure and retry.",
+      "icon": "action"
+    },
+    {
+      "id": "expiry-policy",
+      "label": "Request policy",
+      "kind": "decision",
+      "origin": "unknown",
+      "requirementIds": [
+        "reset-expiry"
+      ],
+      "summary": "Decide expiry and repeat-request behavior.",
+      "description": "The source provides no expiry, repeat-request or disclosure policy. Obtain the actual product and service contract before deciding what the interface should say or do. This is an unresolved requirement, not an inferred security rule.",
+      "icon": "decision"
+    },
+    {
+      "id": "focus-recovery",
+      "label": "Accessible recovery",
+      "kind": "behavior",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-focus"
+      ],
+      "summary": "Announce errors and guide keyboard focus.",
+      "description": "Proposed accessible recovery should explain failures to screen-reader users and support keyboard correction and retry. Exact focus destinations, announcement behavior and implementation checks remain to be defined and tested.",
+      "icon": "check"
+    }
+  ],
+  "edges": [
+    {
+      "id": "request-success",
+      "from": "address-entry",
+      "to": "confirmation",
+      "label": "Success",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-confirmation"
+      ]
+    },
+    {
+      "id": "request-failure",
+      "from": "address-entry",
+      "to": "recoverable-error",
+      "label": "Failure",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-error-retry"
+      ]
+    },
+    {
+      "id": "retry",
+      "from": "recoverable-error",
+      "to": "address-entry",
+      "label": "Retry",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-error-retry"
+      ]
+    },
+    {
+      "id": "expiry-decision",
+      "from": "address-entry",
+      "to": "expiry-policy",
+      "label": "Resolve policy",
+      "origin": "unknown",
+      "requirementIds": [
+        "reset-expiry"
+      ]
+    },
+    {
+      "id": "focus-requirement",
+      "from": "recoverable-error",
+      "to": "focus-recovery",
+      "label": "Accessible feedback",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-focus"
+      ]
+    }
+  ],
+  "requirements": [
+    {
+      "id": "reset-entry",
+      "text": "The synthetic source includes an address-entry screen.",
+      "origin": "observed",
+      "sourceIds": [
+        "sample-brief"
+      ]
+    },
+    {
+      "id": "reset-confirmation",
+      "text": "The synthetic source includes a confirmation screen; its actual transition is proposed.",
+      "origin": "observed",
+      "sourceIds": [
+        "sample-brief"
+      ]
+    },
+    {
+      "id": "reset-error-retry",
+      "text": "Proposed: preserve the entered address after a failed request and allow retry.",
+      "origin": "proposed"
+    },
+    {
+      "id": "reset-expiry",
+      "text": "Unknown: expiry policy and treatment of repeated requests require a product/security decision.",
+      "origin": "unknown"
+    },
+    {
+      "id": "reset-focus",
+      "text": "Proposed: focus and announced errors must support keyboard and screen-reader recovery.",
+      "origin": "proposed"
+    }
+  ],
+  "findings": [
+    {
+      "id": "decide-request-contract",
+      "message": "No actual API contract or account-disclosure policy has been supplied.",
+      "severity": "blocking",
+      "status": "open"
+    },
+    {
+      "id": "design-error-state",
+      "message": "Recovery and accessible error presentation are proposals; no inspected frame supports them.",
+      "severity": "warning",
+      "status": "open"
+    }
+  ],
+  "presentation": {
+    "fontFamily": "Inter"
+  },
+  "summary": "Request reset instructions and recover from failure.",
+  "description": "This unapproved planning fixture is grounded only in the synthetic brief. It illustrates the proposed reset flow without claiming inspected Penpot frames, actual application behavior or owner agreement. Request policy, recovery and accessibility behavior remain explicit decisions and verification work."
+}

package/examples/design-release-maps/sample-source.md

@@ -0,0 +1,8 @@
+# Synthetic reset-password source
+
+This is illustrative fixture text, not a Penpot inspection or approved product
+requirement. It supplies reproducible local source bytes for the map examples.
+
+The sample includes an address-entry screen and a confirmation screen.
+The intended user goal is to request password-reset instructions.
+No API, expiry policy, error recovery or focus behavior is established here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/web",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "The penpair command for Penpot on the web (design.penpot.app or your team's own): guided setup, a safe write protocol, skills for AI agents. Includes everything in @penpair/core.",
   "license": "MIT",
   "repository": {
@@ -48,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@penpair/core": "0.3.7"
+    "@penpair/core": "0.4.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",