@penpair/web 0.3.7 → 0.4.1

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/docs/layout-settling.md

@@ -1,6 +1,6 @@
 # Bounded layout settling
 
-Normal operation writes, PNG exports, baselines, shots and token push verification now use `waitForStableLayout`. A supported shape/global native wait is preferred. Older APIs fall back to geometry samples, requiring two consecutive equal observations of the target subtree. Missing targets, changed file/page identity, malformed geometry, more than 10,000 sampled nodes, native failure and expired budgets cannot establish stability.
+Normal operation writes, PNG exports, baselines, shots and token push verification now use `waitForStableLayout`. A supported shape/global native wait is preferred. Older APIs fall back to geometry samples, requiring three consecutive equal observations of the target subtree. Missing targets, changed file/page identity, malformed sampled geometry and expired budgets cannot establish stability. Native failure falls back to geometry in `auto` mode; `native` mode still requires a successful native wait.
 
 The default layout budget is 30 seconds, with 200 ms fallback intervals. A run is also limited to 1,000 samples. Each layout observation forwards its remaining request budget through guards to the MCP SDK and disables suspension retries; a read timeout does not silently restart the budget. Custom clients must honor the optional `ToolCallOptions.timeoutMs` contract. A late native response is rejected even if it claims completion. The overall CLI `--timeout-ms` remains a separate bound on the complete command.
 
@@ -11,3 +11,19 @@ Exports retain the first capture as an initial observation, wait for layout, and
 The previous unconditional ten-second operation sleep is replaced by bounded evidence. Library callers can retain an explicitly measured `settleMs` minimum from 0 to 30 seconds for an additional asynchronous contract such as binding persistence. It is a delay, not verification. A missing binding still fails independent readback and may be reconciled through the journal once it arrives. Page switching retains its existing short navigation delay. No new live timing or compatibility claim is made.
 
 Library options may select a target and budget through `layout`, or explicitly set `layout: false` when the caller supplies its own settlement evidence. CLI design commands do not expose that opt-out. Multi-step mutations remain nontransactional: a post-write layout failure can leave completed work applied; inspect the run and explicitly resume after resolving it. The later build kit should reuse these primitives rather than introduce another fixed-sleep convention.
+
+## Scope and node budgets
+
+`run-file`, `run`, `archive`, token edit writers, `export` and `shots` accept:
+
+```sh
+penpair run-file design/build.js --inspect design/inspect.js --readback design/readback.js \
+  --page Candidate --layout-root BOARD_ID --layout-root OTHER_BOARD_ID \
+  --layout-max-nodes 20000 --apply
+```
+
+Each repeatable `--layout-root` identifies an existing shape on the operation's page. Roots must be distinct, nonoverlapping subtrees. Missing roots refuse rather than falling back to the page. The same roots are observed before planning, after writing and during recovery. New shape IDs cannot be selected before creation; select their existing parent or use the page default. Without explicit roots the current page is sampled; exports retain their existing shape scope. Library callers use `layout.shapeIds` (or the existing singular `shapeId`) and `layout.maxNodes`.
+
+`--layout-max-nodes` is an integer from 1 to 100,000, shared across the selected subtrees; the default remains 10,000. When the traversal exceeds it, the observer retains a bounded depth-first prefix. A successful native wait or three equal bounded samples can continue the operation with `method: "partial"` and `truncated: true`. This establishes stability only for the sample, not for unsampled shapes. Invalid geometry, cycles or duplicate IDs encountered in the sample still refuse. Use explicit roots for complete evidence on a large page. Partial evidence never replaces positive independent write readback or visual export inspection.
+
+Reports and journal observations, visible through `penpair runs RUN_ID`, record `rootIds`, `nodeCount` (the sampled count), `maxNodes` and `truncated`. The sample count is a lower bound on subtree size when truncated. Journal input hashes retain the chosen scope and budget, so changing either requires a new run. The build kit's `pp.settle(root, {maxNodes})` shares this policy and evidence; it also accepts an array of root shapes.

package/docs/mcp.md

@@ -55,3 +55,5 @@ args = ["mcp", "--root", "/absolute/path/to/project"]
 ```
 
 Restart/reconnect after reviewed target or tool-capability changes. Keep the actual Penpot editor visible. SDK in-memory tests establish discovery, typed input refusal, explicit write opt-in, root isolation and target-change refusal; actual agent/editor compatibility remains a pending I12 trial.
+
+For explicit tab activation, heartbeat diagnostics and the limits of background operation, see [recovering a suspended Penpot tab](browser-sessions.md). The CLI `wake` action is separate from the read-only doctor tool.

package/docs/run-file.md

@@ -69,3 +69,5 @@ The common verifier requires matching nonempty expected/actual objects. Empty `p
 Final wrapped UTF-8 snippets obey the existing 90 KB guard, including helpers, guards, parameters and the captured inspection passed to apply. Every phase compiles offline before connecting; an oversized runtime inspection can still make apply refuse before delivery. Each input file is bounded independently, and at most 20 distinct include paths and 100 parameters are accepted. Reports identify the ordered source text hashes actually prepared. No implicit imports, glob expansion or transpilation occurs.
 
 Writes reuse pinned file guards, revisions, writer coordination, positive independent verification and redacted journals. Optional `--checkpoint`, `--force-lock` and explicit `--apply --resume RUN_ID` follow normal recovery rules. Source/parameter changes refuse resume; a final state already independently verified is not written again. Partial unexplained state requires inspection; there is no rollback or enforced idempotency sandbox. A redacted journal cannot be presented as complete verification or automatically resumed.
+
+On a large page, scope layout settling to the existing boards touched by the write with repeatable `--layout-root SHAPE_ID`. `--layout-max-nodes N` sets the shared sample budget (1–100,000; default 10,000). The roots must exist before the write and remain present through readback. Reports and `penpair runs RUN_ID` retain the roots and sampled node count. Budget overflow continues with explicitly partial layout evidence; independent readback is still required. See [layout settling](layout-settling.md) for scope and partial-sample limits.

package/docs/troubleshooting.md

@@ -11,7 +11,7 @@ Generated from the core error remedy inventory. Regenerate with `pnpm docs:gener
 | `incomplete-output` | Required output is missing, truncated or unstable. Narrow the scope or resolve the capture problem before accepting it as complete. |
 | `mcp-unavailable` | Start the Penpot instance and check the MCP URL. Run `penpair probe` to see what answers. |
 | `plugin-disconnected` | In the open Penpot file choose File, MCP Server, Connect, and keep that tab visible, then run the command again. |
-| `plugin-suspended` | The browser put the Penpot tab to sleep. Bring it to the foreground and keep it visible while a command runs. A suspended-tab error does not mean nothing was written: read the page before running a write again. |
+| `plugin-suspended` | The browser put the Penpot tab to sleep. Bring it to the foreground, or use penpair wake --debug-port PORT with a dedicated debugging browser, then run penpair doctor. Waking is temporary recovery. A suspended-tab error does not mean nothing was written: read the page and reconcile the run before explicitly replaying a write. |
 | `snippet-too-large` | Split the snippet. Penpot's proxy refuses request bodies of about 110 KB, so snippets stay under 90 KB. |
 | `stale-inspection` | The file, revision, query or inspected content changed. Discard the old cursor/chunks and start a fresh capture. |
 | `tool-failed` | Penpot's tool reported a failure; the message above says what. |

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."
+}