@penpair/web 0.1.3 → 0.3.0

package/docs/inspection.md

@@ -0,0 +1,38 @@
+# Structured inspection
+
+Use `penpair inspect <shape-id> --page Candidate --all --out design/frame.json` for a complete selected-subtree projection. Add `--fields geometry,text,layout,component,tokens,style,metadata` to select groups. IDs, hierarchy and explicit unknown fields accompany the projection. Full text is retained; mixed rich-text range styles remain unknown. This is a versioned inspection model, not a native-file backup.
+
+Without `--all`, inspect returns one transfer chunk. Pass its `nextCursor` with the same selectors to continue. Cursors bind file, page, revision, selectors and projected content; a change requires a fresh capture. Each chunk recomputes the projection, with no snapshot cache. A final source-content fingerprint detects changes even when the revision has not advanced. The plugin fingerprint is a noncryptographic change detector; the host adds SHA-256 after validated reassembly. Neither is an owner signature. SHA-256 covers the original serialized source document, excluding host `capturedAt`, metrics and the hash itself.
+
+`penpair tokens dump --out design/tokens.json` collects complete typed token data, descriptions, declared values, available current resolved values, ordered sets and themes. Composite values stay JSON objects. `tokens dump --cursor CURSOR` transfers one continuation chunk. A value observed in the current theme does not verify every theme. Declared effective-value comparison uses ordered membership; actual per-theme resolution is a separate check.
+
+## Budgets and incomplete evidence
+
+| Budget | Default | Range |
+| --- | --- | --- |
+| `--depth` (shape inspection) | 64 | 0–10000 |
+| `--max-nodes` | 20000 | 1–50000 |
+| `--response-bytes` | 65536 | 4096–262144 |
+| `--time-budget-ms` (one traversal) | 5000 | 1–30000 |
+| `--document-bytes` | 16 MiB | 4 KiB–128 MiB |
+| `--max-calls` (complete collection) | 256 | 1–2048 |
+| `--max-total-bytes` (assembled source) | 16 MiB | 4 KiB–128 MiB |
+| `--capture-timeout-ms` | 60000 | 1–300000 |
+
+The response cap covers decoded executor text plus structured payload, conservatively accounting for both when present. It excludes HTTP/MCP wire framing. Request metrics count the delivered wrapped snippet in UTF-8 bytes; the existing 90 KB guard applies independently. Unicode chunks never split surrogate pairs. Collection budgets differ from traversal and transport budgets.
+
+Node, depth, time or byte exhaustion is explicit: `complete: false`, reasons, counts and unknown totals where necessary. Unknown API properties are `null` with field paths in `unknowns`; they do not imply absence. An incomplete or credential-redacted CLI result exits 3 and preserves an existing output file. Chunk redaction also removes continuation. Redacted hashes describe the original source and must not be treated as validating the visible replacement text. Complete local captures publish atomically inside the project path.
+
+## Formats and migration
+
+Source documents use `schemaVersion: 1` and `kind: shape-inspection` or `token-inspection`. Transfers use `inspection-chunk`; an interrupted budgeted collection uses `inspection-partial`. Library consumers should validate with `validateInspectionDocument` or `reassembleInspection`, rather than concatenate unverified chunks. CLI JSON wraps the payload under `data` in the common command envelope.
+
+`tokens diff` accepts the versioned typed dump and legacy `name=value` lists. Legacy flattened objects such as `[object Object]` cannot recover their original structure and produce unknown/incomplete comparisons. Regenerate those dumps. Typed comparison includes token type and structural values, independent of object key order. Theme-name ambiguity is an error.
+
+`tree` remains a readable preview with IDs and explicit line, text and depth truncation metadata. `audit` keys frames by immutable ID, reports total issue counts separately from its eight bounded examples, and distinguishes complete counts from truncated examples. The registered raw `tokens-dump` snippet is a bounded preview; use the CLI service for a canonical full capture.
+
+## Evidence and compatibility
+
+Offline fixtures cover full Unicode text, composite tokens, getter-backed layout properties, malformed graphs, stale cursors, incomplete budgets and source data that resembles instructions. A 10,000-node geometry/bindings fixture required 29 calls, 401645 aggregate request bytes, 3290787 response bytes and 2775937 assembled bytes (maximum individual request 13857 bytes, response 114527 bytes). It took about 1.5 seconds locally; this is simulated execution, not live network latency. Measure a real file before considering caches.
+
+Property selection follows the current official [Text](https://doc.plugins.penpot.app/interfaces/Text), [GridLayout](https://doc.plugins.penpot.app/interfaces/GridLayout), [LayoutCellProperties](https://doc.plugins.penpot.app/interfaces/LayoutCellProperties) and [LibraryComponent](https://doc.plugins.penpot.app/interfaces/LibraryComponent) references. API presence is checked at runtime. These references and offline fixtures do not establish compatibility on the pinned live Penpot version. Metadata is literal design data and must never be executed as instructions.

package/docs/layout-settling.md

@@ -0,0 +1,13 @@
+# 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.
+
+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.
+
+Journaled operations settle the selected page before planning and inspect again around the actual write. Their recovery observations also require settlement, so a resume cannot skip failed layout verification merely because values arrived. Nonjournaled `runOperation` settles after its acknowledged write and before independent readback. Token push verifies layout before structural comparison and during journal reconciliation. Reports and capture provenance retain the settlement method and sample count when measured.
+
+Exports retain the first capture as an initial observation, wait for layout, and still require two consecutive matching renders. Thus a stale first render cannot be accepted merely because native layout finished. Stable geometry does not prove token bindings persisted, fonts loaded, themes resolved correctly, or pixels match the intended design. Positive readback and looking at the images remain separate requirements.
+
+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.

package/docs/marwes-components.md

@@ -0,0 +1,34 @@
+# Measured component pilot
+
+`penpair marwes components snapshot [--write]`, `check [--measure]` and `diff` compare Button, Card and StatTile in explicit light/dark contexts. This is a pilot, not a generated native library. `build` refuses until a live pinned-API experiment proves text/style instance overrides survive updates. I12 adoption and C1 live acceptance remain pending at the owner's request.
+
+The adopting project owns a stable fixture rendering its installed components with its actual theme, state and fonts. Use explicit selectors and named `data-pilot-part` anatomy nodes. React component names are not inferred from the DOM. Start with six cases (three components, two modes) and add actual states as needed, up to 60. Add this adapter-owned block under `marwes`:
+
+```json
+{
+  "components": {
+    "schemaVersion": 1,
+    "renderer": "design/component-pilot/renderer.mjs",
+    "sources": ["src/component-pilot.tsx", "src/theme.ts", "pnpm-lock.yaml"],
+    "snapshot": "design/marwes-components.snapshot.json",
+    "cases": [
+      {"id":"button-light","component":"Button","theme":"light","state":"default","viewport":{"width":1280,"height":900},"selector":"[data-pilot='button']"},
+      {"id":"button-dark","component":"Button","theme":"dark","state":"default","viewport":{"width":1280,"height":900},"selector":"[data-pilot='button']"},
+      {"id":"card-light","component":"Card","theme":"light","state":"default","viewport":{"width":1280,"height":900},"selector":"[data-pilot='card']"},
+      {"id":"card-dark","component":"Card","theme":"dark","state":"default","viewport":{"width":1280,"height":900},"selector":"[data-pilot='card']"},
+      {"id":"tile-light","component":"StatTile","theme":"light","state":"default","viewport":{"width":1280,"height":900},"selector":"[data-pilot='tile']"},
+      {"id":"tile-dark","component":"StatTile","theme":"dark","state":"default","viewport":{"width":1280,"height":900},"selector":"[data-pilot='tile']"}
+    ]
+  }
+}
+```
+
+Copy/adapt [renderer.mjs](../examples/component-pilot/renderer.mjs) into that project, install Playwright and its browser there, and start its local fixture server. The adapter has no mandatory browser dependency. The example uses [Playwright page evaluation and viewport contexts](https://playwright.dev/docs/api/class-page) to read computed styles after fixture readiness. It checks the observed theme/state attributes rather than treating query labels as activation proof. Fixture readiness must also guarantee deterministic content, disabled animations and expected font faces. A loaded font set alone does not prove the intended font exists.
+
+The renderer is explicitly trusted project code, loaded only by measurement commands. It exports `async measure(cases)` returning one observation per ID, each with `parts`, and `environment: {browser, fontsReady}`. Each part returns every exported `componentProperties` key, using null for unknown. No null properties or unready fonts can replace the committed snapshot. JSON inputs are bounded to 4 MiB; sources stay inside the project. Include all relevant transitive fixture/theme/font/lock files in `sources`: hashes are not a dependency graph or sandbox. Renderer cancellation follows the cooperative command boundary; arbitrary trusted module code can ignore it.
+
+`check` without `--measure` only compares declared sources, renderer, effective token hash and library version. It reports `anatomyMeasured:false`, even on success. `check --measure`/`diff` actually execute the renderer and compare complete observations; an environment change also causes drift. `snapshot` defaults to review and `--write` atomically publishes only complete unredacted evidence. Version-1 snapshots have a content hash and do not imply approval.
+
+`tokenCandidates` lists exact typed scalar matches in the selected mode, preserving multiple matches. It does not infer semantic bindings, resolve arbitrary formulas, or synthesize typography from equal scalar properties. Constants without candidates remain measured raw values; declare intentional token additions through project extras, then review them. Automatic promotion of three consumer-specific radius constants awaits actual fixture measurements.
+
+The live acceptance exercise is separate: build one native component, instantiate it, customize instance text and style, update the main component idempotently, independently verify both custom overrides and unchanged instance IDs, export twice, and inspect the images. Record pinned API/library versions and owner-authorized scratch target. Until that passes, do not expand the catalogue or claim this snapshot represents native Penpot component anatomy/instance-use counts.

package/docs/marwes-tokens.md

@@ -70,8 +70,8 @@ penpair marwes tokens push --apply         # make Penpot match (look first witho
 | Your theme file changed | `check`: the snapshot is stale | the same |
 | Marwes packages are at different versions (a half-finished upgrade) | `check` fails with exit 1 | finish the upgrade; Marwes releases its packages together |
 | **Marwes grew a kind of variable the adapter does not turn into a token** | `check`: the snapshot lists every variable it does not cover, so a new one changes it | review it, then extend the adapter or accept it by writing the snapshot |
-| Someone edited a token in Penpot by hand | `diff`: shown as a difference, with what it reaches | `push --apply` puts it back (Marwes is authoritative) |
-| Someone added a token to a Marwes set by hand | `diff`: "not in the expectation" | kept unless you push with `--prune` |
+| Someone edited a token in Penpot by hand | `diff`: shown as a difference, with what it reaches | `push` stops for an explicit adoption or overwrite decision |
+| Someone added a token to a Marwes set by hand | `diff`: "not in the expectation" | preserved, including with `--prune`, unless a verified ancestor establishes ownership |
 | A set was deleted or a theme changed in Penpot | `diff` | `push --apply` |
 | The recorded Marwes version (in every token's description) is old | `diff` | `push --apply` updates it, so the file says which Marwes it came from |
 
@@ -117,3 +117,60 @@ penpair marwes tokens push --apply                # bring Penpot along; it reads
 Everything Marwes resolves for a theme becomes a token: colours, density sizes, the two radii, the three font families and the typography styles, plus the spacing scale. A variable that is not (today: `--mw-density-spacing-multiplier`, a multiplier) is listed in the snapshot's `unmapped` field and in `snapshot` output, so the gap is visible and a change to it is noticed.
 
 Not covered yet: Marwes **components** in Penpot. Tokens come first; components are built as pages need them.
+
+## Project-owned extra sets and snapshot migration
+
+Declare extra sets under `marwes.extras` in `penpair.config.json`. They join the generated expectation and participate in snapshot/check/diff/push. Each extra is appended after the mode overlays in both themes, in declaration order:
+
+```json
+"extras": [{
+  "name": "Acme · Page",
+  "tokens": [{ "name": "page-card-radius", "type": "borderRadius", "value": "{mw-ui-radius} * 2", "description": "Project card radius" }]
+}]
+```
+
+These are project declarations, including their formulas; they are not inferred component measurements. C1 owns evidence for component-derived constants. Invalid types, duplicate set/token names and collisions with generated sets refuse the expectation. Up to 50 extra sets and 10000 extra tokens are accepted. Values are strings or composite objects with string-valued fields.
+
+New snapshots use `schemaVersion: 2` and an explicit `ownership` map: generated sets are `adapter`, extras are `project`. Version-1 snapshots remain readable for review; run `penpair marwes tokens snapshot --write`, review the ownership change and commit the regenerated file. Unknown versions or malformed version-2 ownership refuse loading. Hashes now include ownership. Writes publish atomically within the project path.
+
+An existing live catalog can still place a set in a different global precedence order. Theme membership alone does not establish resolution; the per-theme resolution work in C3 must check this independently. Ownership is reconciled against the last verified sync, as described below.
+
+For one-off edits, the neutral core supplies [guarded token editing](token-editing.md). When a token belongs in the reproducible project expectation, declare it here before updating the snapshot; a live-only edit does not update config.
+
+## Reconciliation, ownership and destructive plans
+
+A successful verified `push --apply` records a schema-1, file-bound ancestor in ignored private `.penpair/token-sync/` evidence (mode 600). Subsequent pushes compare each managed token property against that ancestor, the committed desired snapshot and the live value. Upstream-only changes may proceed. Designer-only changes, conflicting changes and differing existing values without an ancestor stop with exit 2. Convergent changes need no conflict decision. Renames are reported as removal plus addition; no identity is guessed from similar values.
+
+Inspect the report before choosing:
+
+- `push --adopt design/adoption.json` exclusively creates a local review proposal (exit 3), preserving the live file and ancestor. Review its typed live values, put intentional overrides in project themes/extras, regenerate and commit the snapshot, then push. Adoption is not silently written into generated upstream tokens. The proposal refuses replacement and known credential-bearing evidence.
+- `push --overwrite` shows the overwrite plan; `push --overwrite --apply` explicitly permits the reported designer/untracked/conflicting values to be replaced. This permission never bypasses destructive dependency checks.
+
+New checkouts lack local ancestry: matching live values can be recorded with an unchanged `push --apply`; differing existing values require a decision. The hash detects accidental ancestor changes; this is local evidence, not authentication or shared team authorization. Concurrent ancestor publication uses a local exclusive lock and refuses an unexpected newer ancestor. An interrupted `.lock` needs inspection before manual removal; stale evidence is never silently discarded.
+
+`--prune` removes only retired tokens present in the verified ancestor, inside currently declared managed sets. It preserves unowned hand additions, unmanaged sets and their theme membership. Retired whole sets are reported and preserved; their names alone never establish ownership. Prune and type replacement refuse retained cross-set formula references and bound shapes. Dependencies are checked again inside each destructive mutation. This is conservative even if another set supplies the same name, or another planned action would later remove a dependent. Change declarations/dependencies in a separate reviewed step.
+
+Each apply still checks file/source identity, original journal inputs and structure. A failed or uncertain push does not advance the ancestor. Per-theme actual resolution and global set precedence require the separate mode trial; membership and ownership do not establish those values.
+
+## Actual resolution and mode review
+
+`diff --resolved [--apply]` measures actual token resolution in each isolated declared theme, with full original selection restoration. `verify-modes FRAME_ID --page PAGE --out DIR [--apply]` adds stable per-mode images. See [mode verification, recovery and limits](mode-verification.md).
+
+## Adapter recipe source
+
+After `--include @kit`, opt into `--include @marwes-kit` for card, segmented, progress, icon-tile and stat-tile recipes. Project radius constants and progress sizing height remain explicit inputs; these recipes do not claim measured native-component parity. See [the build kit](build-kit.md).
+
+Component anatomy is a separate [measured three-component pilot](marwes-components.md); token sync does not establish component parity.
+
+## Metadata-only upgrades
+
+`tokens check --json` includes `reasons` with stable codes: `missing-snapshot`, `schema-migration`, `missing-ownership`, `content-drift`, `metadata-mismatch` and `package-mismatch`. `current:false` always explains why, even if `diff.identical:true`. Exit 2 is stale data; invalid/unreadable input is still an error.
+
+For a legacy snapshot, explicitly map **every** set name to `"adapter"` or `"project"` in `ownership.json`. Preview without connecting to Penpot:
+
+```sh
+penpair marwes tokens migrate --from design/legacy-tokens.json --ownership ownership.json
+penpair marwes tokens migrate --from design/legacy-tokens.json --ownership ownership.json --out design/migrated-tokens.json
+```
+
+Review values, themes and original provenance before adopting the migrated file. Do not infer ownership from name prefixes or regenerate away the source evidence.

package/docs/marwes.md

@@ -0,0 +1,9 @@
+# Marwes adapter
+
+[Token declarations, ownership and reconciliation](marwes-tokens.md) remain the detailed token reference. [Measured components](marwes-components.md) cover the Button/Card/StatTile pilot and its native override-proof gate. [Mode verification](mode-verification.md) checks actual resolved values and restores the original complete selection.
+
+The adapter consumes the adopting project's installed library/theme, and keeps project knowledge outside the neutral core. Project extras remain declared inputs. Computed component values are measurements in a theme/state/viewport; token matches are candidates, not inferred semantic bindings. Native library generation and human adoption acceptance remain pending until observed proof exists.
+
+`penpair marwes theme lint` compares declared project colors with installed defaults in light/dark mode. When primary changes, unchanged brand-family siblings with a distant hue become advisory warnings. Configure `marwes.themeLint.hueThresholdDegrees` (default 30) and exact `suppressions: [{theme:"light",token:"mw-color-border-brand",reason:"Intentional blue navigation"}]`. Suppressions remain visible. Transparent, non-literal and achromatic colors remain unknown; hue is neither a brand rule nor an accessibility score. Warnings return success and never rewrite themes or Penpot.
+
+[Projected theme previews](theme-previews.md) resolve declared light/dark values offline without changing active selections or claiming native per-frame theme bindings.

package/docs/mcp.md

@@ -0,0 +1,40 @@
+# Project-pinned stdio tools
+
+```sh
+penpair mcp --root /absolute/path/to/project
+```
+
+Use the project's reviewed local executable. Startup requires an absolute root, valid project config and owner-confirmed file pin. The server keeps that target for its lifetime and refuses a changed target until restart/review. Each call gets request-scoped root state; it never calls `process.chdir`. Even basic reads use strict same-execution file guards. Environment/project `.env.local` endpoint resolution remains available; unrelated global Codex/Claude endpoint fallback is disabled. Keep credentials in the private connection flow, outside client configuration examples.
+
+Default tools: pages, bounded tree/audit/inspection, bounded token dump, offline baseline coverage, doctor, derived spec, and stable export to a path inside the project. Export creates/replaces a local file and has a write annotation. There is no raw-code tool or unrestricted command forwarding. Each typed input is validated independently of the client schema. No write tool is advertised by default.
+
+Explicit `--allow-writes` additionally advertises `run_registered`. It accepts a registered operation name and scalar parameters, defaults to inspection, and requires explicit `apply:true` for design writes. Explicit `resume` requires apply and the original journal; file/instance guards, local/shared advisory lease, same-execution preconditions, checkpoints supported by the underlying command, and independent readback remain in the same services. Registered modules execute trusted project code, including imports; they must keep stdout for MCP and log through the command context. This is not an execution sandbox. Adapter-specific commands remain available through the CLI; the neutral server does not guess library-specific tool schemas.
+
+Requests return the version-1 CLI envelope as text plus structured content. Default cooperative deadline: 60 seconds; SDK cancellation propagates into the service. Arbitrary trusted code can ignore cancellation. A 256 KiB response cap returns an explicit incomplete envelope rather than apparently successful truncated data; uncertain writes retain their uncertain outcome/run ID. Use narrower inspection or CLI artifact output for larger evidence. Stdio has no HTTP listener or background polling.
+
+## Client registration
+
+These are reviewable examples; no client settings were edited. Replace executable/root paths for each developer. The executable should be the reviewed project installation, not an automatically fetched latest package.
+
+Claude Code supports project `.mcp.json` entries under `mcpServers`; see [official project MCP documentation](https://code.claude.com/docs/en/mcp#project-scope).
+
+```json
+{
+  "mcpServers": {
+    "project-design": {
+      "command": "/absolute/path/to/project/node_modules/.bin/penpair",
+      "args": ["mcp", "--root", "/absolute/path/to/project"]
+    }
+  }
+}
+```
+
+Codex uses project `.codex/config.toml` for trusted projects, with a server table; see [official Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).
+
+```toml
+[mcp_servers.project_design]
+command = "/absolute/path/to/project/node_modules/.bin/penpair"
+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.

package/docs/mode-verification.md

@@ -0,0 +1,35 @@
+# Per-theme resolved values and mode images
+
+`penpair marwes tokens diff --resolved` inspects a mode trial. Add `--apply` only after reviewing its planned states: actual resolution requires temporarily changing active themes and sets. A current committed token snapshot is required. Ordinary `tokens diff` remains a declared-value comparison.
+
+```sh
+penpair marwes tokens diff --resolved --apply
+penpair marwes tokens verify-modes FRAME_ID --page Candidate --out design/modes
+penpair marwes tokens verify-modes FRAME_ID --page Candidate --out design/modes --apply
+```
+
+Open the requested page before inspecting image trials. The frame must exist and expose export support before any trial mutation. IDs, file pinning, revision/source preconditions, writer coordination, optional `--checkpoint`, journals and explicit `--resume RUN_ID` use the normal write safeguards. Config-free standalone mode is unavailable.
+
+Each declared theme is measured in an **isolated theme context**: all other themes are temporarily disabled, and active sets must exactly match that theme. This tests the generated mode rather than silently combining unrelated density or brand axes. It does not establish every combination of those axes. The report shows actual and expected global set order; the catalog's precedence matters even when theme membership is correct.
+
+After bounded layout completion, two equal resolved observations are required (up to 20 samples within a five-second observation budget). Each expected token is compared with its actual API `resolvedValue`, with type and unknown evidence retained. Requests are bounded independently; the common overall command deadline still applies. Equal observations are evidence at capture time, not proof of persistence or eventual autosave.
+
+The independent expectation resolves references from the committed snapshot under its declared set order. Numeric values use a bounded grammar for parentheses, unary signs, addition, subtraction, multiplication and division; references are cycle/depth checked. No JavaScript is evaluated. Supported colors, font-family lists and known typography field aliases are compared structurally. Unsupported formulas/units, nested font arrays, missing API values and composite shadow resolution remain unknown and yield incomplete evidence. Nothing is inferred from a flattened object string.
+
+## Restoration and failure
+
+The complete original active state of every theme and set is saved before mutation, including multiple groups or a custom selection. The service restores it in `finally` and independently reads it back. Restoration success is separate from successful mode comparison. A trial whose modes match but whose restoration fails cannot pass or publish a new image generation.
+
+Cancellation gets a separate cooperative ten-second restoration deadline. This permits the explicitly promised cleanup to finish after the main command is cancelled; it does not turn an uncertain mode activation into a confirmed measurement. A lost activation response is never automatically replayed. Restoration is a separate idempotent write based on observed state. Changed token declarations or an unexplained selection can require manual inspection instead of being overwritten.
+
+The journal records one compound trial, its original state, mode evidence and restoration result. `verified` journal state means the trial protocol ended with independently restored selection; the report's `verified` additionally requires complete, matching mode values. Uncertain or incomplete measurements remain explicit. Resume can recover an already-restored report without replay. When image bytes were not published before interruption, start a fresh explicit trial to collect them; resume does not invent missing images.
+
+Exits: 0 for a complete matching applied trial (or a complete inspection plan), 2 for measured drift, 3 for incomplete resolution/capture evidence, 4 for uncertain execution, and 1 when restoration fails without a stronger uncertain outcome. The outer command can still report cancellation/deadline. Inspect the saved journal and original selection before further writes after any failure.
+
+## Images and provenance
+
+Image trials export the same frame separately in each mode and retain stable-render identity, active themes, source/snapshot hashes, byte SHA-256 and capture time. Resolution is rechecked after export. Only a complete collection with verified restoration publishes an immutable image generation and atomically replaces its root manifest pointer. The pointer hashes its generation manifest. Prior output survives partial exports and restoration failures. A journal that required credential redaction makes the evidence incomplete and prevents publication. These images are review evidence; they do not approve a baseline or establish visual parity.
+
+Limits: 1–20 declared themes, 5000 source tokens, bounded source/resolved documents and the existing 90 KB final wrapped snippet guard. A large exact source precondition can refuse before delivery. Stable set/theme IDs and switching/resolution capabilities are required. No new live pinned-version trial has been performed.
+
+The official [theme API](https://doc.plugins.penpot.app/interfaces/TokenTheme) explains group behavior and custom-set activation. Resolved-value forms follow the [sizing](https://doc.plugins.penpot.app/interfaces/TokenSizing), [font-family](https://doc.plugins.penpot.app/interfaces/TokenFontFamilies) and [typography](https://doc.plugins.penpot.app/interfaces/TokenTypographyValue) references. Unsupported runtime forms stay visible instead of being guessed.

package/docs/plans/registry-polling-fix.md

@@ -0,0 +1,101 @@
+# Registry visibility polling — 2026-10-22
+
+Branch: `codex/release-registry-polling`. Base: reviewed 0.3.0 release on main,
+`4ea9975`. Repository package versions remain 0.3.0.
+
+## Failure and evidence
+
+The [publish job](https://github.com/niklas-westman/penpair/actions/runs/39801876697/job/119904592523)
+accepted `@penpair/core@0.3.0` at 15:17:02 UTC with signed provenance. npm explicitly
+reported that processing could take a few minutes. The script exhausted twelve
+five-second visibility checks and stopped at 15:18:05 UTC. No subsequent package
+was published by that run.
+
+An independent registry check then found core 0.3.0 visible, with Docker, the token
+adapter, the comparison adapter and web still absent. This establishes a
+processing-delay failure after an accepted upload; increasing a publish timeout
+or retrying the upload is unnecessary.
+
+## Completed checklist
+
+- [x] Extract a focused post-publish visibility helper. It checks immediately and
+  then at minute intervals within a ten-minute deadline for each uploaded package.
+- [x] Count registry query time toward the deadline and report elapsed time and
+  the next check/deadline in workflow logs.
+- [x] Bound each npm metadata process and HTTP request to 30 seconds or the
+  remaining deadline, with hidden npm retries disabled.
+- [x] Retain errors for failed lookups, explicit interrupted-release continuation,
+  dependency-order publishing and the configured short-name exception. The
+  visibility helper never uploads a package.
+- [x] Add virtual-clock tests for immediate/delayed visibility, exact minute
+  cadence, query duration, ten-minute expiry, remaining query budget, late
+  observations and registry errors. Query-boundary tests cover 404, authentication,
+  network errors and killed processes without touching npm.
+- [x] Document recovery and the order of operations before merging a tooling fix.
+
+## Validation
+
+- `pnpm check`: **658 tests** pass, including 15 new polling/query tests, along
+  with builds, typechecks, style/path checks and the six-package version guard.
+- `pnpm smoke:package`: all six tarballs install and run.
+- Final polling/logging tests pass independently using virtual time. No real
+  ten-minute sleeps or npm publication were used for testing.
+- `git diff --check` passes. The empty Changeset records repository tooling work
+  and does not propose a package version bump.
+
+## Current release recovery and remaining risk
+
+- [ ] On current `main`, dispatch **Publish reviewed Penpair release** with
+  `version=0.3.0` and `continue_release=true`, then approve `npm-release`.
+- [ ] Verify all five required scoped versions and provenance. The `penpair`
+  wrapper remains explicitly excluded.
+- [x] Polling fix merged as PR #5 before recovery completed; the early-merge recovery below supersedes the original merge order.
+
+The current main workflow still has its original one-minute visibility wait. If
+another accepted upload exceeds it, inspect the registry and explicitly continue
+the same version again. Rerunning the failed push workflow does not select
+continuation automatically.
+
+Finish recovery before merging this branch: its pending Changeset would block the
+manual release gate on main. This preserves the existing guard rather than
+changing it to accommodate an interrupted release. Ten minutes is a bounded
+window, not a guarantee that npm finishes processing; a failed lookup or an
+expired deadline still stops for inspection.
+
+## Early merge recovery
+
+PR #5 was merged on 2026-10-22 as `d339a19` while the 0.3.0 release remained
+interrupted. The new minute polling is now on main. The remaining pending note
+`bounded-registry-polling` has an empty release list and requests no version bump.
+The version-PR workflow therefore created no release PR. Manual continuation is
+blocked until that metadata has been consumed.
+
+The post-merge push workflow separately hit a GitHub API HTTP 500 while reading
+associated PRs; its publish job was skipped. That API error is distinct from the
+pending-note check. Manual dispatch uses the explicit-version path.
+
+- [x] Reproduce Changesets' consumption in an isolated workspace: only the empty
+  note is removed and every package stays at 0.3.0.
+- [x] Use the same Changesets CLI operation on the cleanup branch. Confirm no
+  package manifest, source version, lockfile, script or workflow changes.
+- [x] Run the unchanged `checkReleaseCommit` and manual workflow gate against the
+  resulting tree: both accept 0.3.0 with no pending notes. No publish command runs.
+- [x] Pass style/path checks and 47 existing Changesets, release-guard, polling,
+  registry-query and documentation tests. The cleanup changes only metadata/docs;
+  the previous 658-test run and six-package smoke cover the retained polling code.
+- [ ] Review/merge the metadata-only cleanup PR and pass its CI.
+- [ ] On the resulting main, dispatch **Publish reviewed Penpair release** with
+  `version=0.3.0`, `continue_release=true`, and approve `npm-release`.
+- [ ] Verify all five scoped packages and their provenance before marking the
+  release complete; the short-name exception remains enabled.
+
+The consumed tooling note is preserved here:
+
+> Allow npm processing time after successful uploads: check visibility immediately
+> and then once per minute within a ten-minute deadline per package. Bound metadata
+> queries and retain explicit recovery for interrupted releases. This changes
+> repository release tooling only.
+
+This cleanup completes an empty metadata item through Changesets. Package release
+notes and release guards remain intact; the interrupted version remains 0.3.0,
+with core skipped by explicit continuation once independently observed on npm.

package/docs/plans/tradient-feedback-0.2.0.md

@@ -0,0 +1,209 @@
+# Tradient feedback: execution plan
+
+Created: 2026-10-22. Status: **phases 0–6 delivered and verified offline; final offline review complete; live Penpot gates and PP-07 causality remain open**.
+
+Goal: make the ordinary Penpair workflow complete the observed trial without a custom SDK host, then reduce the project glue needed for comparison and theme previews.
+
+Source: `feedback-0.2.0-2026-10-22.md` and its linked evidence in Tradient's `docs/penpair/`. The original report is outside this repository; phase 0 records a redacted, portable reproduction here. No consumer files are changed by this plan.
+
+## Defaults and constraints
+
+- Cover all eight findings in phases. Milestone A is reliability; milestone B is comparison and preview capability. Use `codex/tradient-feedback`, with small verified commits. Milestone boundaries permit review; they do not authorize pushes, merges or publication.
+- Live acceptance uses a dedicated disposable copy, confirmed by its public file ID. No file has been selected or authorized by this plan. Until then, implement and test offline and leave the live boxes unchecked. Do not repurpose Tradient's existing file or its other pages implicitly.
+- Keep the core neutral. Library recipes, ownership migration and library-specific previews belong in adapters. Tradient's screen, trading data and theme names remain consumer-owned.
+- Retain file pins, one-shot writes, independent readback, uncertain journals and exact-artifact approval. Geometry stability is not pixel approval, font readiness or native component parity.
+- No token changes, native component generation, whole-file restore claim, two-person acceptance claim or edits to the adopting application are implicit in this work.
+- Preserve compatible public interfaces and result envelopes. Add optional evidence fields rather than renaming existing fields or changing their meaning. New commands/options require matching help, schemas where applicable, and negative parsing tests.
+- Use Changesets for release notes. All six repository package versions move together; the existing publishing exception may still skip only the unscoped wrapper. Do not bump versions during implementation.
+
+## Repository and validation
+
+Baseline inspected: `main` at `57f9782`, all six packages at **0.2.0**. pnpm **10.12.1**, TypeScript **5.6.3**, Vitest **3.2.4**. Tests live in each package's `test/` directory. There is no repository lint script.
+
+| Purpose | Command |
+| --- | --- |
+| Build, types, tests and package-version/config rules | `pnpm check` |
+| Six tarballs installed and exercised in clean consumers | `pnpm smoke:package` |
+| Fast version/config guard | `pnpm check:versions` |
+| Targeted regression | `pnpm --filter PACKAGE exec vitest run test/FILE.test.ts` |
+| Whitespace | `git diff --check` |
+
+Run the relevant targeted suite while developing each phase, then `pnpm check` before committing it. Run package smoke after changes to shipped commands, adapters, skills/examples or dependencies and at final handoff. Do not substitute fake-provider tests for a real-browser acceptance result.
+
+Planning validation (2026-10-22): 73 existing targeted tests passed across core, adapter and comparison packages; the version/config guard, local document links and single-Now rule passed. Full `pnpm check` and package smoke were not rerun for this documentation-only change. These baseline results do not verify the proposed fixes or any live acceptance gate.
+
+### Completion protocol
+
+Check a task only when its stated output is built and verified. Record offline and live status separately. Keep exactly one `Now` in `PLAN.md`; update it and the change log with each completed phase. If evidence changes the diagnosis, update this guide before implementing a different solution.
+
+After every phase, append a report below with **Resolved / Changed / Validated / Risks / Next**, date, commit, commands/results, and links to reviewed evidence. For investigations, distinguish **investigated** from **resolved**. A blocked live check never becomes a passing checkbox through elapsed time or synthetic evidence.
+
+## Milestone A — reliable default workflow
+
+### Phase 0 — reproduce and preserve the baseline
+
+- [x] Record the feedback version, package/agent/runtime versions and the relevant reproduction sources. Extract only credential-free minimal fixtures; do not copy the whole consumer runner or unreviewed logs.
+- [x] Run the existing layout/kit, migration, doctor, coordination and structural-snapshot suites. Record pre-existing failures separately.
+- [x] Add failing regressions before behavioral changes: native wait times out while geometry is stable; metadata-only snapshot migration; delayed own-lease save versus a real external edit; page switching delayed past the initial read.
+- [x] Prepare a public-ID-only scratch fixture manifest with two pages, one flex/text/token example and expected preservation checks. Keep credentials and private journals ignored.
+
+Tests: core `settle-integration.test.ts`, `kit.test.ts`, `external.test.ts`, `coordination.test.ts`, `journal.test.ts`, `structure-snapshot.test.ts`; adapter `migration.test.ts`, `commands.test.ts`.
+
+Exit: the confirmed layout and migration failures reproduce in controlled tests. PP-07/08 fixtures state which behavior is confirmed and which causal claim still needs live tracing. Lack of a live target does not prevent phase 1.
+
+### Phase 1 — bounded layout fallback (PP-01, P1)
+
+Entry points: `packages/core/src/layout.ts`, `kit-source.ts`, operation settling and stable export callers.
+
+- [x] Extend `LayoutOptions` and kit `settle`/`flush` options with `strategy: auto | native | geometry`, default `auto`. Add `--layout auto|native|geometry` to `run-file`, `export` and `shots`; omit any unverified `off` mode. Existing SDK `layout:false` stays an explicit advanced-caller contract, not a suggested CLI workaround.
+- [x] Use one shared policy definition for host and kit behavior. Preserve existing total deadlines; cap an automatic native attempt at the smaller of **500 ms** and **one quarter of the remaining budget**. Leave time for geometry fallback rather than spending the full deadline on native waiting.
+- [x] In `auto`, fall back after an unsupported native API or an observed native wait failure when execution and target identity remain valid. A lost transport response, cancellation, changed target, malformed data or exhausted budget must not become success or trigger a write replay.
+- [x] Require three consecutive complete, equal geometry samples in geometry mode, with stable IDs/hierarchy and finite measurements; use the existing host/kit poll intervals. Duplicate IDs, cycles, truncation and node-budget excess refuse. In `native`, propagate native failure without fallback.
+- [x] Add optional attempt diagnostics to `LayoutResult`: selected strategy, native outcome, fallback reason and elapsed time. Preserve `stable`, `method` and `samples` meanings. Report verification failure after a partial flush through the existing journal/readback path.
+
+Tests: successful native path; unsupported/timed-out native with stable geometry; continually moving geometry; malformed/truncated samples; changed file/page; cancellation/deadline; bindings recorded only after valid settling; equivalent host/kit policy; CLI option rejection; stable PNG export still requires independent matching renders.
+
+Exit: core `native-api`, `settle-integration`, `kit`, `kit-integration`, `run-file`, `export` and `shots` tests pass, followed by full checks/package smoke.
+
+- [ ] **Live acceptance:** the shipped CLI and kit build the small scratch example, verify actual bindings and produce two stable exports without a consumer SDK runner. Repeating retains owned IDs and adds no duplicates. Look at the images; record native/fallback evidence.
+
+### Phase 2 — explain upgrades and prove readiness (PP-02/03, P2)
+
+- [x] Add additive snapshot-check reason codes for missing snapshot, schema migration, missing ownership, content drift and metadata/hash mismatch. A stale result must always include a reason, even when the value diff is identical. Preserve stale/error exit-code distinctions.
+- [x] Reuse the existing `tokens migrate --from FILE --ownership FILE` preview and `--out NEW_FILE` write path. Diagnostics must point to that workflow, explain the schema change and request explicit classification of every legacy set. Do not invent ownership or regenerate away original provenance.
+- [x] Strengthen the existing doctor execution read rather than creating a duplicate readiness command. Add `doctor --timeout-ms N`, default **5000 ms**, valid **1000–30000 ms**, bounding origin, connection and execution work with cancellation.
+- [x] Generate a fresh challenge for the editor to echo with file/page identity. Report origin reachability, transport connection, fresh execution and file-pin match separately, with observed time/duration. Only measured layers may be healthy; unavailable heartbeat/version evidence stays unknown. Extend existing doctor JSON checks additively and keep endpoint redaction.
+
+Tests: adapter `migration`, `commands`, `command-contract`; core `external`, `connect`, `http-client`, `command-result`. Include old schema with unchanged values, missing ownership, invalid map, preserved provenance, stale challenge, wrong file, sleeping editor, timeout and secret-bearing failure text. Migration must require no live connection.
+
+Exit: the retained schema-1 fixture explains its failure and migrates without value/theme/provenance loss; doctor cannot report unqualified readiness from stale or incomplete execution evidence.
+
+- [ ] **Live acceptance:** compare responsive, foregrounded and deliberately disconnected scratch-editor states. Verify a new challenge and useful bounded failure messages. Do not deliberately interrupt a mutation for this test.
+
+### Phase 3 — coordination evidence and page-aware snapshots (PP-07/08)
+
+- [x] Add redacted optional journal trace events around lease acquisition/check/release, inspection and observed revisions. Record source identities and timing without credentials, document text or whole catalogs in logs.
+- [x] Reproduce delayed lease persistence separately from external shape/token edits. First make no-op/reconciliation behavior observable; do not replace guards with sleeps or automatically ignore revision differences.
+- [x] **PP-07 decision gate:** if causal attribution is proven, fix the ordering of lease acquisition, target capture and inspection so the operation starts from its own independently read post-acquisition revision, while preserving conflict detection during inspection and before mutation. Test an external edit in each interval. If attribution remains unproven, deliver tracing/reproducer and retain PP-07 as unresolved; changing revision policy then requires a separately reviewed plan amendment.
+- [x] Replace the fixed page-switch sleep in `runOnPage` with bounded polling of the expected page ID: default **5000 ms**, **100 ms** intervals, limited by the enclosing command's remaining budget. Resolve a unique name once to an ID. A timeout identifies expected/observed page and stage.
+- [x] Serialize page-sensitive work on the same client through a shared page-session mechanism. Whole-file snapshots hold that session for the collection, capture pages sequentially, and restore the original visible page in `finally`. Unexpected external navigation causes a clear failure rather than silent mixing.
+- [x] Record per-page progress and timings. Preserve the original snapshot manifest on failure; diagnostic partial observations must never be assembled across revisions or published as a complete snapshot. Keep the original error if restoring the visible page also fails, and report both.
+
+Tests: core `coordination`, `journal`, `operation-recovery`, `operation`, `inspection`, `structure-snapshot`; add delayed page-switch and concurrent same-client collector tests. Include duplicate page names, removed pages, manual navigation, mid-capture file/token edits, deadline exhaustion and restoration after failure.
+
+Exit: multi-page fixtures succeed sequentially with correct identities and restore their starting page; failures preserve prior artifacts and identify the exact failed stage. PP-07 is either causally fixed with safety regressions or explicitly still unresolved.
+
+- [ ] **Live acceptance:** idle sequential operations, a controlled external scratch edit and a two-page snapshot. Confirm preservation of token definitions/order, global theme selections and unrelated objects.
+
+### Phase 4 — help and composition guidance (PP-06, P3)
+
+- [x] Adapter-discovery slice: promote both companion roles in the README/setup guides and recommend the comparison adapter in shipped setup/handoff skills, with distinct installation and browser-readiness stages. This independent documentation slice does not complete the runtime help/composition work below.
+
+- [x] Group installed help around connect/diagnose, build, inspect/spec, snapshot/diff, capture/approve and compare. Include examples of actual installed syntax and link to limitations; do not invent new aliases merely to reorganize help.
+- [x] Add a short pre-build composition checklist to the design/recipe skills: primary user task, chosen existing reference, hierarchy, useful context, responsive/focus order, and a small first-frame critique before expanding variants. This records a design decision; it does not manufacture owner approval.
+- [x] Document migration previews, settling modes, doctor layers and snapshot recovery; remove suggestions to work around these with arbitrary waits.
+
+Tests: core `docs`, `skill-instructions`, `skills`, CLI help assertions and installed-package smoke. Verify instructions survive idempotent installation and no project names enter the neutral core.
+
+Exit: the inspect → spec → snapshot/diff → comparison path is discoverable from installed help; one trial can follow documented commands without reading package source.
+
+## Milestone B — reduce consumer integration work
+
+### Phase 5 — real browser comparison starter (PP-05, P2)
+
+- [x] Add a neutral example provider under `examples/reflection-browser/` for the existing `ImplementationProvider.runCase` contract. Use the adopter's pinned Playwright installation; no browser dependency or application framework enters the core. Ship it with the existing web documentation/examples mechanism and verify the installed path.
+- [x] Require project hooks for route, fixture, theme, state, capture root and expected fonts. Read actual state and loaded font faces/weights; never echo requested inputs as observed evidence.
+- [x] Park the pointer outside the capture region and verify no relevant hovered controls. Capture with explicit viewport, device scale **1** by default and a root bounding box after scroll/sticky layout settles. Round the box outward to whole CSS pixels and record the rule; do not resize images to improve a metric.
+- [x] Preserve the current schema-1 provider fields. Add optional capture metadata for root/clip, scale, browser version, font evidence and pointer checks; old providers remain readable. The example requires its complete metadata and flags missing evidence instead of substituting defaults silently.
+- [x] Validate paths/hashes and compare through the existing adapter. Retain `owner-review-required`; a pixel score never approves a baseline. Unapproved trial captures may test the capture helper, but the approval gate for `reflection check` stays intact.
+
+Tests: adapter `integration.test.ts` plus new provider/capture fixtures for wrong state/theme, delayed/missing fonts, hover contamination, sticky shell, fractional crop boundaries, unchanged baseline bytes and dimension/scale mismatch. Exercise a real local example in the browser at desktop/mobile × light/dark × loaded/empty; unit stubs alone do not complete this phase.
+
+Exit: an adopter can supply explicit setup hooks and run a genuine comparison without rewriting capture plumbing. No Tradient route/provider is registered by modifying its repository here.
+
+### Phase 6 — explicit, isolated theme previews (PP-04, P2)
+
+- [x] Record the pinned API's frame-level theme capabilities with links and observed proof. Do not expose native per-frame binding as supported based on an API name or projected appearance.
+- [x] Deliver a deterministic offline preview first: neutral token-projection logic plus adapter command `penpair marwes tokens preview --from SNAPSHOT --theme NAME [--out FILE]`. Resolve the selected declared theme using existing token precedence/alias rules; ambiguous names, missing dependencies or unsupported values produce errors/explicit unknowns.
+- [x] Return a versioned preview with source hash, selected theme/set identities, resolved values/unknowns and `kind: projected-theme-preview`. `--out` writes only a project-bound artifact. It does not mutate Penpot, switch global themes or imply native bindings.
+- [x] Supply a scratch example applying projected color values to owned roots, with projection metadata retained separately from actual typography/spacing/radius bindings. Native frame-mode support remains a separate acceptance gate if it cannot be proved on the pinned version.
+
+Tests: adapter preview/command-contract tests and neutral resolver tests: multiple themes, ordering, aliases/cycles, composite values, ambiguous names and missing values. Before/after scratch checks must show identical global selections, catalog values/order and unrelated objects.
+
+Exit: simultaneous light/dark preview artifacts are reproducible and accurately labeled. Native component anatomy, override preservation and native per-frame color bindings remain unclaimed unless independently proven.
+
+## Final integration and release gate
+
+- [ ] Re-run the eight-case scratch trial using shipped CLI/kit paths, a repeat build and one heading change. Compare IDs, bindings, geometry, native/browser images and changed fields. Record observed timings, unknowns and interventions.
+- [ ] Confirm no consumer-side timeout bypass, fixed inter-operation sleep or fabricated provider evidence is needed for the covered paths.
+- [x] Run `pnpm check`, `pnpm smoke:package` and whitespace checks. Record the actual final test count and installed-package results; do not assume the 0.2.0 baseline count remains current.
+- [x] Add Changesets per package behavior: fixes as patch, new public options/provider/preview capabilities as minor. The generated version PR selects the highest bump for every package; no manual version bump or release activation change belongs here.
+- [x] Review the branch, evidence and remaining PP-07/native-mode/live gates; see the [branch review and acceptance checklist](tradient-feedback-review.md).
+- [ ] Obtain owner decisions before any push/PR, merge, publish or non-scratch write.
+
+If the scratch target is unavailable, code may be reviewed with live checks still pending, but the release must not claim those checks passed. No rollback or exactly-once guarantee is introduced. On an uncertain write: stop, retain the journal, inspect independently, reconcile only owned changes and resume explicitly. After repeated failure, record the trace and narrow the reproducer; never relax a guard to get a green report.
+
+## Completion tracker and reports
+
+| Phase | Status | Offline evidence | Live evidence | Completed |
+| --- | --- | --- | --- | --- |
+| 0 Baseline/reproducers | Complete offline | 587 tests; explicit expected-failure reproducers | Target pending | 2026-10-22 |
+| 1 Layout | Complete offline | 597 tests; six-package smoke pass | Pending | 2026-10-22 |
+| 2 Migration/readiness | Complete offline | 607 tests; six-package smoke pass | Pending | 2026-10-22 |
+| 3 Coordination/snapshots | Offline delivery complete; PP-07 unresolved | 614 tests; six-package smoke pass | Pending | 2026-10-22 |
+| 4 Help/skills | Complete | 615 tests; six-package smoke pass | Not applicable | 2026-10-22 |
+| 5 Browser starter | Complete | 616 tests; package smoke; 8 real-browser cases + negative cases | Local Chromium trial complete; Penpot pending | 2026-10-22 |
+| 6 Theme previews | Complete offline | 622 tests; six-package smoke pass | Scratch/native capability pending | 2026-10-22 |
+| Final trial/release review | Offline review complete; owner/live pending | 630 tests; six-package smoke; real browser matrix | Penpot target pending | 2026-10-22 (offline) |
+
+Append phase reports here during execution. Update the table and relevant `PLAN.md` checkbox in the same verified change.
+
+### 2026-10-22 — Companion discovery (phase 4 documentation slice)
+
+**Resolved:** Readers and agents can now discover why to add the library and frontend-comparison adapters, with Reflection Check recommended when implementing and verifying frontend code.
+
+**Changed:** Added a companion selection/setup/readiness guide, promoted both roles in README and onboarding docs, updated shipped setup/handoff/recipe skills and project-facts guidance, and added a matching-version registration path. Kept adapter dependencies explicit and the browser starter planned. No runtime help/composition or reliability fix is claimed by this documentation slice.
+
+**Validated:** `pnpm check` passes (583 tests), including navigation/anchors, core/skill neutrality and skill installation. All six package smoke installs pass; the command tarball includes the new adapter guide. Added patch changesets for the affected shipped packages.
+
+**Risks:** These guidance changes need the next reviewed release and skill refresh to reach existing installations. Browser verification still requires approved baseline/case evidence and a real provider; automatic bundling/setup was not added. No version bump, push, merge or publish was performed.
+
+**Next:** Phase 0 remains the runtime entry point; phase 5 supplies the real-browser starter. Phase 4's help/composition tasks remain unchecked.
+
+### Phase 0 report — 2026-10-22
+
+**Resolved:** portable, credential-free reproductions now distinguish confirmed defects from suspected live causes. **Changed:** [baseline evidence](../fixtures/feedback-reproductions.md), scratch manifest template, native timeout/metadata/delayed-page expected-failure tests and conservative delayed-revision fixture. **Validated:** existing targeted suites: 55 tests; reproducers: 4 tests; `pnpm check`: 587 tests pass, including three explicitly expected failures. **Risks:** expected-failure tests demonstrate missing behavior; they do not verify fixes. No live target or lease causality proof. **Next:** phase 1 shared layout fallback. Commit: `test: preserve adoption failure reproductions`.
+
+### Phase 1 report — 2026-10-22
+
+**Resolved:** idle native failure no longer blocks the default workflow when independent complete geometry settles. **Changed:** one static host/kit policy, bounded native attempts, three equal hierarchy-aware samples, diagnostics and CLI `--layout`; no write retry. **Validated:** native success/failure/hang, node overflow/cycles, target/transport refusal, kit binding and stable-render tests; `pnpm check` passes 597 tests and six-package smoke passes. **Risks:** geometry is neither visual approval nor font readiness; live CLI/kit build remains pending. **Next:** migration explanations and bounded doctor readiness. Commit: `feat: share bounded layout fallback across host and kit`.
+
+### Phase 2 report — 2026-10-22
+
+**Resolved:** metadata-only stale snapshots now explain schema/ownership/hash causes; transport connection alone cannot prove editor readiness. **Changed:** additive reason codes and existing migration guidance; bounded origin/transport/challenge execution/file-pin layers, timestamps and duration, default 5 s doctor with 1–30 s option. Docker uses the same fresh-read proof. **Validated:** 74 targeted tests, stale/missing challenges, wrong file, sleeping origin/editor, timeout validation and secret redaction; `pnpm check` 607 tests and six-package smoke pass. **Risks:** real background/disconnected editor tests remain pending; heartbeat/version are unknown unless observed. **Next:** coordination trace and serialized page sessions. Commit: `feat: explain migration drift and prove fresh doctor readiness`.
+
+### Phase 3 report — 2026-10-22
+
+**Resolved:** delayed synthetic navigation and overlapping same-client collectors now use observed IDs and serialized sessions, restoring the starting page. **Changed:** page/session guards shared by derived clients, bounded polling, per-page progress and separate restoration errors; optional `--trace --apply` journal lease/revision events (also token pushes). **Validated:** real plugin bodies cover delayed switches, concurrent collectors, manual navigation, removed/ambiguous pages, revision changes, restoration failure and cross-client writer contention; `pnpm check` 614 tests and six-package smoke pass. **Risks:** PP-07 remains **unresolved**: delayed own saves and external edits cannot be causally distinguished with current evidence. Revision guards are unchanged. Live sequential/external-edit tests pending. **Next:** installed help and composition guidance. Commit: `feat: serialize observed page sessions and trace writer revisions`.
+
+- [ ] PP-07 follow-up: obtain scratch trace proving delayed writer-marker persistence, then separately review any change to revision ordering. Tracing and conservative conflict refusal are delivered; no race fix is claimed.
+
+### Phase 4 report — 2026-10-22
+
+**Resolved:** installed help now exposes the full inspect/spec/snapshot/capture/compare workflow; composition guidance catches under-designed first frames before multiplying variants. **Changed:** task-grouped actual command examples, composition checklist in shipped skills, and migration/layout/doctor/snapshot/recovery docs. Corrected old help wording that implied updating an image alone approves it. **Validated:** help, docs, neutral-core and idempotent skill installation tests; `pnpm check` 615 tests and six-package smoke pass. **Risks:** composition remains a human/agent judgment step; a checklist does not establish visual quality or owner approval. **Next:** real-browser comparison starter. Commit: `docs: expose the complete workflow and first-frame composition checks`.
+
+### Phase 5 report — 2026-10-22
+
+**Resolved:** adopters can reuse real capture plumbing with explicit project hooks rather than rewrite fonts/scroll/hover/cropping logic. **Changed:** shipped browser provider, independent DOM state and loaded font/weight evidence, outward CSS clipping, hover/occlusion checks, optional schema-1 metadata validation and installed-example smoke. **Validated:** `pnpm check` 616 tests and six-package smoke pass; eight real local browser cases plus wrong theme, missing face/weight, delayed font load, scale mismatch, hover and sticky-shell refusal. Actual screenshots were inspected; a sticky header initially obscured the heading and the new guard/scroll hook corrected it. [Portable browser evidence](../fixtures/browser-capture-2026-10-22.json) records Chromium 148.0.7778.96, bundled Playwright 1.62.1, unchanged reference bytes and owner-review-required. MCP could inspect the fixture but could not import modules; the real provider ran with the bundled runtime and cached Chromium. **Risks:** references are explicitly unapproved synthetic browser fixtures, not approved Penpot designs; sampled occlusion still requires image inspection. No consumer provider was registered. **Next:** offline projected themes and pinned native capability evidence. Commit: `feat: ship a verified real-browser comparison starter`.
+
+### Phase 6 report — 2026-10-22
+
+**Resolved:** independent light/dark artifacts can be generated without switching live themes or falsely claiming native frame modes. **Changed:** bounded neutral projection resolver shared with mode verification; adapter `tokens preview --from --theme [--out]`, discoverable artifact schema, source/theme/set provenance and owned scratch example. **Validated:** ordered precedence, aliases/arithmetic, composites, ambiguous/missing themes/sets, cyclic/budget failures, project-bound output and preservation through actual sandbox example bodies; `pnpm check` 622 tests and six-package smoke pass. **Risks:** [pinned capability evidence](../theme-previews.md#pinned-native-capability-evidence) is source-based; the hosted API version is distinct. Native frame themes, component parity/overrides and live projection preservation remain unproved. **Next:** full branch review, final browser/package validation and explicit live checklist. Commit: `feat: project declared themes without changing live selection`.
+
+### Final boundary review report — 2026-10-22
+
+**Resolved:** cancelling a queued collector no longer opens a parallel page queue while its predecessor is still active. **Changed:** deferred queue cleanup, stricter geometry/hierarchy and doctor identity validation, correct doctor range text, bounded browser animation-frame waits. **Validated:** the queue regression failed before the fix and passes afterward; cancellation after a delivered read performs no second observation. Malformed native/geometry/root/sibling evidence refuses. `pnpm check`: 630 tests; all six package smoke installs; eight real local browser cases plus six rejection cases and delayed fonts pass. **Risks:** live gates and PP-07 causality remain open. **Next:** owner branch review and separately authorized scratch acceptance. Commit: `fix: preserve cancellation and evidence boundaries`.
+
+### Final handoff — 2026-10-22
+
+**Resolved:** all authorized code phases and offline/local-browser acceptance are complete on the review branch. **Changed:** [consolidated branch report](tradient-feedback-review.md) maps every finding to its delivered outcome, evidence and remaining live checks. **Validated:** 630 tests, six installed package families, eight real browser cases and six rejection cases; build/types/version/whitespace checks pass. **Risks:** PP-07 causality, live Penpot build/repeat/heading and multi-page trials, native frame-theme proof and owner release decisions remain unchecked. **Next:** owner branch review and confirmed disposable-file acceptance; no credentials are requested and no publication was attempted.