@penpair/web 0.1.3 → 0.3.0

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

@@ -0,0 +1,83 @@
+# Adoption feedback branch review
+
+Date: 2026-10-22. Branch: `codex/tradient-feedback`. Base: `57f9782`.
+
+Code phases 0–6 are implemented and verified. The branch is ready for owner review. Live Penpot acceptance remains pending; the lease/save race is investigated rather than claimed fixed. The owner has authorized pushing this branch and opening its feature PR. No version bump, merge or publication was performed. All six repository versions remain 0.2.0.
+
+## What each update resolves
+
+| Finding | Delivered result | Verification and limit |
+| --- | --- | --- |
+| PP-01: native layout timeout blocks default build | Shared bounded auto/native/geometry policy for SDK and kit; CLI selection; three complete matching geometry/hierarchy samples | Native success/failure/hang, transport/cancellation/malformed/target refusal and independent matching exports tested; real Penpot build pending |
+| PP-02: unexplained metadata-only token drift | Stable reason codes and explicit existing ownership migration guidance | Legacy values unchanged while schema/hash differs reproduces and explains staleness; migration preserves provenance |
+| PP-03: readiness is unclear | Bounded origin, transport, fresh execution challenge, file/page identity and file-pin evidence | Sleeping origin/editor, stale/malformed challenge, wrong pin and redaction tested; real editor state trials pending |
+| PP-04: simultaneous theme preview needs custom glue | Offline versioned projection, shared ordered alias resolver, adapter command and owned-root example | Precedence, composites, unknowns and sandbox preservation tested; native frame themes remain unproved |
+| PP-05: real comparison provider is missing | Packaged browser starter with project hooks, actual state/fonts, pointer, occlusion and crop evidence | Eight real local Chromium cases, delayed fonts and six rejection cases; unapproved synthetic references do not establish Penpot parity |
+| PP-06: workflow/companions are hard to discover | Companion setup guide, grouped installed help and first-frame composition checklist | Help, docs, core neutrality and idempotent installed skills tested; composition still requires judgment |
+| PP-07: suspected self-save revision conflict | Optional redacted lease/inspection/revision traces and conservative reproducer | **Unresolved causality.** Own delayed persistence and external edits still conflict; no revision guard was relaxed |
+| PP-08: multi-page snapshots fail | Observed page-ID polling, serialized sessions, per-page progress and starting-page restoration | Delayed/concurrent collectors, manual navigation, source edits and restoration failures tested; real multi-page trial pending |
+
+The final review also reproduced and fixed cancellation allowing a third collector to bypass an active session. Queue order now survives cancellation. Layout and doctor reject malformed evidence, and browser frame sampling has a deadline.
+
+## Repository readability follow-up
+
+Biome 2.6.2 supplies a separately committed formatting baseline (`b1a9445`).
+[Conventions and executable examples](../conventions/README.md), an `AGENTS.md`
+reference and the repository-local coding skill now guide naming and module
+boundaries. `pnpm check` also enforces formatting, focused lint rules, kebab-case
+code paths and checked templates. The comparison adapter is split into focused
+modules with its existing public entrypoint intact. The
+[completion checklist/report](../conventions/completion-2026-10-22.md) explains
+what each change resolves and the remaining formatter/review limits.
+
+## Validation
+
+- `pnpm check`: **643 tests** pass (core 498, Docker 28, token adapter 99, comparison adapter 15, convention examples 3), style/path checks, build/typecheck and six-package version guard pass.
+- `pnpm smoke:package`: all **six tarballs** install and run in clean consumers. Installed help, skills, adapter documentation and browser starter are verified, including the comparison adapter's preserved runtime exports and public TypeScript declarations.
+- Real browser trial: bundled Playwright **1.62.1**, cached Chromium **148.0.7778.96**; desktop/mobile × light/dark × loaded/empty. Missing/wrong font face/weight, wrong theme, scale mismatch, hover contamination and sticky occlusion refuse; delayed font loading succeeds. Baseline bytes remain unchanged and verdict stays `owner-review-required`.
+- Actual captures were visually inspected. That inspection found a sticky header hiding the heading; an occlusion guard and explicit project scroll hook corrected it. [Portable evidence](../fixtures/browser-capture-2026-10-22.json) records the cases without machine paths or credentials.
+- `git diff --check` passes. Changesets cover fixes and new public capabilities; repository versions are unchanged.
+
+## Commits
+
+| Step | Commit |
+| --- | --- |
+| Baseline/reproductions | `cc65514` |
+| Bounded layout | `2c60ac5` |
+| Migration/readiness | `b985dc2` |
+| Coordination/snapshots | `b51ad30` |
+| Help/composition | `81f20d3` |
+| Browser starter | `79e8c8e` |
+| Projected themes | `415b291` |
+| Final boundary fixes | `5bcc687` |
+
+## Remaining acceptance
+
+- [x] Owner authorizes pushing the branch and opening its feature PR (2026-10-22).
+- [ ] Owner reviews the branch before merge or release work.
+- [ ] Owner confirms a disposable Penpot copy by public file ID; populate the [scratch manifest](../fixtures/feedback-scratch.template.json). No credentials belong in it.
+- [ ] Run shipped CLI/kit build, repeat it and change one heading across the eight cases; independently compare IDs, bindings, geometry and two inspected exports.
+- [ ] Verify fresh doctor reads with responsive/background/disconnected scratch editor states.
+- [ ] Capture idle/no-op and controlled external-edit traces; establish PP-07 causality before reviewing a revision-order change.
+- [ ] Run a two-page snapshot with restoration and projected-color preservation checks for global selections, catalog/order and unrelated objects.
+- [ ] Prove any native frame-theme or component override capability separately; projected appearance is insufficient.
+- [ ] After owner review and acceptance decisions, prepare the release through Changesets and existing protected publication workflow.
+
+The [living execution guide](tradient-feedback-0.2.0.md) contains the per-phase Resolved / Changed / Validated / Risks / Next reports. Pending live items remain unchecked; this branch does not claim rollback, exactly-once writes, native component parity or human visual approval.
+
+## Release readiness check — 2026-10-22
+
+- [x] Working branch is based on remote main (`57f9782`) verified during the readiness check.
+- [x] Pending Changesets plan **0.3.0 for all six packages** without changing versions on this feature branch.
+- [x] GitHub has both release activation variables set to `true`, and `CHANGESETS_PR_TOKEN` is present. Both release workflows are active; recent version-PR workflow runs succeeded.
+- [x] `npm-release` allows the `main` branch and requires the owner as reviewer, with self-review allowed.
+- [x] The temporary `PENPAIR_RELEASE_EXCLUDE_PENPAIR=true` exception remains enabled: all six repository versions advance together, while the five scoped packages must publish and verify.
+- [x] Remove trailing whitespace from the added font license without changing its text, and replace stale hardcoded versions in the release guide. Branch whitespace checks and current style checks pass.
+- [ ] Push/open the feature PR and pass its remote CI before merging.
+- [ ] Review/merge the generated **Release Penpair** version PR, approve the environment and verify the five required registry versions/provenance.
+
+The code is ready for a feature PR with the live acceptance limits above visible.
+Its merge does not publish: it creates/updates the version PR. Publication runs
+after that separate PR is merged and the environment is approved. The recent
+publish workflows were skipped; this check verifies repository configuration,
+not a completed npm OIDC publication or npm account publisher permissions.

package/docs/pr-improvements.md

@@ -0,0 +1,57 @@
+# PR draft
+
+Target: `main` ← `codex/penpair-improvements`
+
+Title: **Add guarded design workflows and reviewed whole-family releases**
+
+## Description
+
+Penpot operations now pin the target file, stop ambiguous write retries, require
+positive readback evidence and record recovery progress. Structured inspection,
+token ownership/reconciliation, explicit design cases, approvals, snapshots and
+implementation handoffs make design-to-code work reproducible and reviewable.
+
+The branch also adds project MCP tools, reusable build recipes, focused agent
+skills, private credential references, advisory audits and clearer documentation.
+The neutral core and one-way package dependency rules remain enforced.
+
+Releases now use Changesets to collect notes into one **Release Penpair** PR. All
+six packages receive the same bump, including unchanged packages. Merging that
+reviewed version PR can trigger the existing guarded whole-family publisher using
+npm OIDC. Feature merges only collect notes. The owner-approved temporary
+`PENPAIR_RELEASE_EXCLUDE_PENPAIR=true` repository variable can omit only the
+blocked short-name wrapper from publishing, with explicit logs/summary and all
+other packages still required. All six repository versions continue together. A separate GitHub PR token is needed
+for automatic version-PR checks. Both automation paths remain disabled until
+owner activation; no package version is changed by this PR. The pending note
+proposes 0.2.0 in the separate generated version PR.
+
+## Validation
+
+- `pnpm check`: build, typecheck, 583 tests and lockstep/config checks.
+- `pnpm smoke:package`: all six tarballs install and run in clean consumers.
+- Real Changesets CLI tests verify unchanged-package bumps, highest-level
+  selection, changelogs, note consumption and exact workspace dependencies.
+- A disposable full version-wrapper rehearsal moves every package, changelog and
+  the source constant to 0.2.0; this branch remains at 0.1.3.
+- All three workflows pass actionlint 1.7.12 and parsed permission/gate checks.
+- Gate tests cover ordinary pushes, exact merged version PRs, manual confirmation,
+  pending notes, malformed auth evidence and workflow permission separation.
+- Detached-checkout regression runs the exact CI Changesets command against the
+  base SHA and verifies consumed-note version PRs through their dedicated path.
+  Version-PR creation also supports a main-only manual trigger.
+
+## Open acceptance and activation
+
+- Hosted export/import restore proof (G3), two-person live trials (I12), and
+  real component measurement/override proof (C1) remain unchecked by request.
+  Native component generation remains gated.
+- Configure GitHub main/environment protection, the PR token and trusted
+  publishers for every npm package before enabling release automation. Verify
+  the previously refused short name and any unpublished package bootstrap.
+- npm publication is sequential; partial failures require explicit recovery.
+- No remote policy, live Penpot mutation, consumer edit, upstream message,
+  release, tag or deployment was performed.
+
+Review details: [branch review](branch-review.md), [living checklist and
+reports](improvements.md), [release activation](releasing.md#one-time-owner-activation).

package/docs/recovery.md

@@ -0,0 +1,33 @@
+# Recovering interrupted writes
+
+CLI archive, registered write operations and adapter token pushes record their plans in `.penpair/runs/<run-id>.json` before applying a step. The directory is ignored by Git before evidence is written; records use mode 0600. Evidence can contain design content, so keep the directory private. Endpoint credentials are redacted, including known bare keys. A journal whose evidence needed redaction cannot automatically resume.
+
+Inspect a failure locally:
+
+```sh
+penpair runs
+penpair runs <run-id>
+```
+
+These commands work offline, even when project configuration is broken. Resume the original command with its original inputs and explicit apply:
+
+```sh
+penpair archive --page Drafts --name Archive --keep Live --parts Parts --apply --resume <run-id>
+penpair run <write-name> --param name=value --apply --resume <run-id>
+```
+
+Adapter token push also accepts `--apply --resume <run-id>`. It uses the saved original actions and the current committed snapshot. Keep the same engine, operation implementation, snapshot, parameters, prune and checkpoint choices. Changed inputs or source signatures are refused. The direct library runner opts in through `OperationOptions.journal`; unjournaled library calls do not gain recovery automatically.
+
+Resume checks file identity and independently reads actual state. Verified steps are checked again. Token batches rebuild residual work, including partial additions and replacements, rather than blindly replaying previous writes. Third values, changed protected shape structure, or ambiguous identity stop recovery. An archive with a partially created parent whose ownership cannot be established stops for inspection. Custom operations may supply an explicit reconciliation function; otherwise only unchanged inputs or independently verified final state permit recovery.
+
+Add `--checkpoint` to request a run-keyed named Penpot version before operation steps. That flag requires a supported API and independently verified checkpoint; an unavailable checkpoint stops the run. Keep the flag when resuming. A checkpoint is a recovery aid, and is neither a transaction nor proof that a separate backup can be restored. See [backup guidance](backup.md).
+
+A response lost after a mutation leaves the step uncertain, even if the file changed successfully. Completed batches remain applied. There is no automatic rollback over human edits. This release's recovery tests use simulated Penpot execution and HTTP transport faults; live recovery on a scratch file remains to be checked. Journaled CLI writers also use local locks and shared advisory markers; see [team coordination](team.md).
+
+## Coordination evidence
+
+Use `--trace --apply` on journaled core writes or `marwes tokens push` to retain bounded lease/revision events in the private run journal. Inspect with `penpair runs RUN_ID`. Events contain identity, stage and time; they omit document text, token values and endpoint credentials. A revision change remains a conflict even if delayed marker persistence is suspected. Tracing does not establish causality or permit automatic retries.
+
+## Fresh doctor evidence
+
+`penpair doctor --json --timeout-ms 5000` uses a total origin/connection/execution budget (1000–30000 ms). It reports origin reachability, connected transport, a fresh random editor challenge with file/page IDs, and file-pin matching separately. Observation times/durations are measured; heartbeat and unobserved API versions stay unknown. A reachable origin or a connected transport alone is insufficient. Reconnect/foreground an unresponsive editor and obtain a fresh read before starting another operation.

package/docs/releasing.md

@@ -1,44 +1,154 @@
 # Releasing
 
-All packages in this repository are released **together, at one version, even a package that did not change**: `@penpair/core`, `@penpair/web`, `@penpair/docker`, `@penpair/marwes-ui`, `penpair`, and anything added under `packages/` later. The root of the repository is a private workspace and is never published. The rule is enforced, not remembered:
+All packages in this repository are released **together, at one version, even a package that did not change**: `@penpair/core`, `@penpair/web`, `@penpair/docker`, `@penpair/marwes-ui`, `@penpair/reflection-check`, `penpair`, and anything added under `packages/` later. The root of the repository is a private workspace and is never published. The rule is enforced, not remembered:
 
 | Guard | What it stops |
 | --- | --- |
 | `pnpm check` (and CI) runs `scripts/check-versions.mjs` | Any package at a different version, a version that differs from `packages/core/src/version.ts`, a private package, an internal dependency that is not `workspace:*`, a package without the publish guard |
-| `pnpm bump patch\|minor\|major\|x.y.z` | Drift starting at all: it sets every package and `version.ts` in one step |
+| `pnpm version-packages` | One Changesets fixed group versions every package, synchronizes `version.ts` and refreshes the lockfile |
+| `pnpm check:versions` | Missing, duplicate, ignored or separately grouped release packages, including packages added later |
 | `prepublishOnly` in every package | `pnpm publish` inside one package: it refuses unless `pnpm release` started it, and checks the versions again |
 | `pnpm release` | A half release: it checks, publishes the whole set in dependency order, looks each one up on npm, and reports anything missing |
 
 Publishing cannot be undone: a version, once published, cannot be replaced. Check first, publish once.
 
-## One time
-
-1. The npm organisation `penpair` exists (npmjs.com, Add organization, free for public packages).
-2. `npm whoami` prints your user name. If it answers `401`, run `npm login`.
+## Normal release: review a version PR
+
+1. Add `pnpm changeset` to each package/script change, select an affected package
+   and patch/minor/major, and describe the user-visible change. Commit the note
+   with the feature. Documentation-only changes need no note; a script change
+   with no release impact can use `pnpm changeset --empty`.
+2. Merge the feature PR. Once enabled, `.github/workflows/version-pr.yml` creates
+   or updates one **Release Penpair** PR from `changeset-release/main`.
+3. Review the generated package changelogs and shared version. The highest bump
+   requested across pending notes applies to **every** member of the fixed group,
+   including unchanged packages. `pnpm version-packages` runs Changesets, updates
+   the CLI source constant, refreshes the lockfile and checks consistency. It
+   never publishes. Never run it on a feature branch. Feature-PR release-note
+   checks use the exact PR base SHA, so detached CI checkouts need no local main
+   branch. Version PRs instead verify the increased shared version and consumed
+   notes through the dedicated release verifier.
+4. Merge the version PR after CI passes. `.github/workflows/release.yml` checks
+   the GitHub API for that exact merged, same-repository release PR and verifies
+   a higher committed version with no pending notes. Ordinary main pushes skip
+   publishing. The protected `npm-release` environment may require an additional
+   owner approval, depending on its configured protection.
+5. The existing `pnpm release` entrypoint reruns checks and all package smoke
+   installs, publishes packed tarballs in dependency order with npm OIDC and
+   provenance, and verifies every required registry version (all six by default). A moved main branch stops
+   the job instead of publishing a different commit. Do not merge another main
+   change until a release finishes; use manual recovery if it has moved.
+
+Automation is opt-in through the activation switches below. Merging a feature PR
+creates or updates the version PR; publishing starts only after that reviewed
+version PR is merged and any environment approval is granted. Pending Changesets
+determine the next shared version. Package versions remain unchanged on feature
+branches until the separate version PR is generated and reviewed.
+
+## One-time owner activation
+
+- [ ] Review and merge the release implementation; do not enable automation on
+  an unreviewed branch. Confirm GitHub's current action/runtime requirements.
+- [ ] Protect `main`: require the CI job and owner approval, dismiss stale
+  approvals, restrict bypasses, and disable automatic merging of release PRs.
+  Prefer squash/merge commits; the automatic gate requires GitHub's recorded
+  merge SHA to equal the exact main push (ambiguous rebase history fails closed).
+- [ ] Add repository secret `CHANGESETS_PR_TOKEN`: a fine-grained GitHub token
+  limited to this repository with Contents and Pull requests read/write, or a
+  managed GitHub App token with the same rights. No npm permission is needed.
+  Use a bot identity and restrict writes to `changeset-release/main` where your
+  GitHub plan supports it. The token lets generated PR checks run automatically;
+  do not give it branch-protection bypass. Never put it in repository files.
+- [ ] Set `PENPAIR_RELEASE_AUTOMATION_ENABLED=true` to enable version PR creation.
+  After this workflow is on main, open **Actions → Release version PR → Run
+  workflow**, choose `main`, and run it to create the first version PR without
+  another commit. The manual trigger still requires the activation variable and
+  main branch. Inspect the generated PR and confirm its CI checks actually run.
+- [ ] Create/protect environment `npm-release`, restrict deployments to main and
+  configure required reviewers if retaining a second approval before publish.
+- [ ] Configure the exact GitHub repository, `release.yml` workflow and
+  `npm-release` environment as npm trusted publisher for **every** package.
+  Node >=22.14.0/npm >=11.5.1 and supported hosted runners are required; the
+  workflow uses Node 24 and checks npm before publishing.
+- [ ] Verify publishing/bootstrap permissions for every package, especially the
+  previously refused short name `penpair` and the new comparison adapter. A
+  missing or blocked required package stops publishing. The owner-approved
+  temporary `PENPAIR_RELEASE_EXCLUDE_PENPAIR=true` exception may omit only
+  the short-name wrapper; every other package remains required.
+- [ ] Set `PENPAIR_TRUSTED_RELEASE_ENABLED=true` only when all required packages
+  are provisioned (five while the explicit short-name exception is enabled). Merge the reviewed version PR to release. Inspect registry versions
+  and provenance for all packages afterward.
+
+No npm token is needed for this path. The PR token authorizes GitHub changes;
+short-lived OIDC authorizes npm publishing. The versioning job has no OIDC
+permission; the publishing job has no repository write token. No workflow creates
+or pushes tags or GitHub releases automatically.
+
+## Temporary exception for the short name
+
+While npm cannot accept `penpair`, set this **repository Actions variable**:
+
+```text
+PENPAIR_RELEASE_EXCLUDE_PENPAIR=true
+```
 
-## Each release
+This is the only configurable publishing exclusion. The same shared version and
+Changesets fixed group still cover **all six** packages. Both automatic and manual
+CI releases publish and verify the other five, skip registry access/publication
+for `penpair`, and display the exception in logs and the GitHub step summary.
+A successful run means all five required packages are verified; it does not claim
+the full six-package family is published. Any other missing package still fails.
+The exception is rejected if a required package starts depending on the wrapper.
+
+The variable defaults to `false`/unset. Values other than `true`, `false` or empty
+fail before release work. This variable does not enable automation or publishing.
+Keep the two activation switches disabled until owner setup is complete. While
+the exception is enabled, leave only `penpair`'s npm trusted publisher pending.
+The `npm-release` environment does not need its own copy of this variable.
+
+Once the name is available, configure its trusted publisher and set the repository
+variable to `false` or remove it. For the latest reviewed version whose other five
+packages already exist on npm, use manual dispatch with that exact version and
+`continue_release=true`; the unchanged recovery guard publishes only the missing
+wrapper. If nothing at the current version has been published, release normally.
+The first run without the exception refuses a partial family unless continuation
+is explicit. Historical skipped versions are not automatically backfilled.
+
+Local owner-led releases can use the same environment variable. The older local
+`--except penpair` option below still deliberately returns INCOMPLETE/exit 3; it
+is separate from the configured CI exception, which succeeds once its five
+required packages are independently verified.
+
+## Local owner-led recovery
+
+`pnpm bump patch|minor|major|x.y.z` remains a deliberate emergency tool, never
+combined with Changesets versioning for the same release. Normal versions are
+owned by the generated version PR. Do not hand-edit package versions. The root
+workspace version is private and is excluded.
+
+For a reviewed, committed, clean and pushed main release, local `npm login`/OTP
+publishing remains available:
 
 ```bash
-pnpm bump patch              # or minor, major, or an exact x.y.z: every package and version.ts move together
-# add a section to CHANGELOG.md
-pnpm check                   # typecheck, tests, build and the version check
-git commit -am "Release 0.1.3" && git push
-
-pnpm release                 # dry run: checks everything, prints the plan, publishes nothing
-pnpm release --publish       # the real thing; npm asks for your one-time code (or add --otp <code>)
+pnpm release                          # dry run; publishes nothing
+pnpm release --publish --confirm-version X.Y.Z
 ```
 
-`pnpm release` refuses unless all of this is true, and tells you which part is not:
-
-- every package has the same version, and the source version matches;
-- you are on `main`, the working tree is clean, and `main` equals `origin/main`, so what is published is what is on GitHub;
-- npm has none of the packages at this version (or it is an interrupted release, below);
-- `pnpm check` and `pnpm smoke:package` pass (the smoke test packs every package, installs the tarballs in empty projects and runs them).
-
-Then it publishes in dependency order (the core, then the packages that depend on it), waits until npm shows each one, and finally looks up all of them. If any is missing it says `INCOMPLETE` and exits with 3.
+The manual GitHub **Publish reviewed Penpair release** dispatch also remains:
+enter the exact version already on main. It rejects mismatches or pending notes;
+set `continue_release` only after inspecting an interrupted release. The dispatch
+still passes through the protected environment and all unchanged release guards.
 
 ## If a release stops half way
 
+After a successful upload, npm may still be processing the version. The release
+checks registry visibility immediately and then once per minute within a
+ten-minute deadline **for each uploaded package**, printing progress while it
+waits. Each metadata query has a 30-second maximum (or the remaining deadline,
+whichever is smaller), with npm's internal retries disabled. Query time counts
+toward the deadline. A registry error still stops the release; only an actual
+not-found result waits for propagation. The visibility wait never republishes.
+
 A publish can fail after some packages are out (a network error, a wrong one-time code, a name npm refuses). The version is then on npm for some packages and not for others, which must not stay that way. Fix the cause and run:
 
 ```bash
@@ -47,6 +157,26 @@ pnpm release --publish --continue    # publishes only what is missing at this ve
 
 Without `--continue`, `pnpm release` refuses to run while only some packages are at the version, so a partial release cannot be forgotten.
 
+For GitHub recovery, run **Publish reviewed Penpair release** on `main`, enter
+the exact interrupted version and set `continue_release=true`. Approve
+`npm-release` when requested. This checks the registry again, skips versions
+already present and publishes only missing required packages. Inspect the final
+package/provenance verification before counting the release complete.
+
+Finish an interrupted release before merging unrelated changes or a tooling fix
+with new pending Changesets. The manual release gate requires a reviewed version
+with no pending notes; merging another feature can prevent continuation until
+that release state is reconciled. Do not discard pending package-release notes
+or weaken guards to force recovery through.
+
+An empty, tooling-only Changeset contains no package release entries. Changesets
+can consume that metadata without changing versions. If such a note blocks an
+interrupted release, handle it in a reviewed metadata-only cleanup, preserve its
+summary in the completion report and verify unchanged package/source versions
+plus the existing manual gate. This does not apply to notes requesting a package
+release. The [0.3.0 early-merge recovery](plans/registry-polling-fix.md#early-merge-recovery)
+records the concrete case and checks.
+
 ## A package npm will not accept yet
 
 `penpair` (the short name) is refused by npm while its name is blocked as too close to another package. To release the rest and keep the rule visible, leave it out explicitly:
@@ -64,6 +194,7 @@ npm view @penpair/core version
 npm view @penpair/web version
 npm view @penpair/docker version
 npm view @penpair/marwes-ui version
+npm view @penpair/reflection-check version
 ```
 
 Then, in an empty folder, run `npx @penpair/web --version`, `npx @penpair/web setup --help` and `npx @penpair/docker --version` (and, once the short name is published, the same with `npx penpair`). Tag the release if you want one: `git tag v<version> && git push origin v<version>`.
@@ -75,3 +206,22 @@ The core ships `dist`, `skills`, `LICENSE` and a short `README.md`. The web pack
 ## After publishing
 
 Update the version in `PLAN.md` and add the change log line. A problem found in a published version is answered with a new version of **all** packages, never by changing a published one.
+
+## Authentication and limits
+
+See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) and
+[provenance requirements](https://docs.npmjs.com/generating-provenance-statements/).
+Publishing validates the workflow context and rejects long-lived npm token
+fallback, packs with pnpm to rewrite `workspace:*` to exact versions, and publishes
+single tarballs with npm and provenance. These local checks are operational guards;
+npm authenticates the actual identity against owner-managed publisher settings.
+
+npm cannot atomically publish multiple packages. A network/permission failure can
+leave some published and others missing; the release reports failure and requires
+explicit continuation at the same version. A rerun never silently resumes.
+
+GitHub branch/environment protection and npm settings must be checked remotely
+before activation. Tests use the real Changesets CLI in disposable workspaces and
+fake GitHub/OIDC evidence; they do not establish account permissions or a live
+publishing result. Owner activation, pushes, merges, version bumps and publishing
+remain separate actions.

package/docs/run-file.md

@@ -0,0 +1,71 @@
+# Running reviewed plugin bodies from files
+
+`run-file` sends explicitly selected JavaScript bodies to the Penpot plugin. It does not import those files or unrelated project extensions into the Node process. Files must be `.js` or `.mjs` bodies for an async function, not host modules. Paths resolve inside the configured project, including real symlink targets. Config-free standalone execution is unavailable.
+
+```sh
+penpair run-file design/read.js --page Candidate --param id=SHAPE_ID \
+  --include design/helpers.js --include design/project-helpers.js
+```
+
+Each file that runs read-only at top level starts with `// penpair: read`. This includes helper preludes and inspection/readback phases. Helpers are concatenated in caller order before the phase body, after the page guard. Parameters are literal strings available as `CFG`; duplicate or malformed keys refuse. `CFG.page` is owned by `--page`, and `CFG.inspection` is reserved for writes.
+
+A read declaration is a trusted contract, never a JavaScript sandbox. Review includes too. A helper may define functions used by a later write phase, while its top-level inclusion must itself remain read-only. Read executions disable automatic suspension retries and require an explicit `ok: true` result.
+
+## Reviewed writes
+
+To preserve the write protocol, a write file needs both leading declarations:
+
+```js
+// penpair: write
+// penpair: idempotent
+```
+
+It also requires explicit read-only `--inspect` and `--readback` files. The command runs only inspection by default:
+
+```sh
+penpair run-file design/rename.js --inspect design/rename-inspect.js \
+  --readback design/rename-readback.js --page Candidate \
+  --param id=SHAPE_ID --param name=ReviewedName
+```
+
+Review that inspection, then add `--apply`. Undeclared or unverified raw writes refuse even when `--apply` is supplied. This is stricter than a raw executor: acknowledging arbitrary code is insufficient to claim an independently verified design change. For a custom code-defined verifier use a registered snippet operation.
+
+A small example follows. Inspection captures the original target:
+
+```js
+// penpair: read
+const shape = penpot.currentPage.getShapeById(CFG.id);
+if (!shape) throw new Error("Target missing");
+return { ok: true, id: shape.id, beforeName: shape.name, desiredName: CFG.name };
+```
+
+The write uses that independent observation, tolerates its already-completed state and refuses a third state:
+
+```js
+// penpair: write
+// penpair: idempotent
+const shape = penpot.currentPage.getShapeById(CFG.id);
+if (!shape || shape.id !== CFG.inspection.id) throw new Error("Target changed");
+if (shape.name !== CFG.inspection.beforeName && shape.name !== CFG.name) throw new Error("Source changed");
+shape.name = CFG.name;
+return { ok: true };
+```
+
+Readback reads the real target from scratch:
+
+```js
+// penpair: read
+const shape = penpot.currentPage.getShapeById(CFG.id);
+return { ok: true, verification: {
+  expected: { id: CFG.id, name: CFG.name },
+  actual: shape ? { id: shape.id, name: shape.name } : { missing: true }
+} };
+```
+
+The common verifier requires matching nonempty expected/actual objects. Empty `problems: []` cannot pass. The code's author still owns the meaningful postconditions, read-only declarations and idempotency. Export affected frames and look at them twice as the write protocol requires; structural verification does not approve pixels.
+
+## Identity, budgets and recovery
+
+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.

package/docs/shots.md

@@ -0,0 +1,15 @@
+# Named exports and ad-hoc shots
+
+```sh
+penpair export --name "Dashboard / Desktop" --page Dashboard dashboard.png
+penpair export <shape-id> dashboard.png --page Dashboard
+penpair shots --page Dashboard --prefix "Dashboard /" --out design/shots
+```
+
+Names match exactly on the selected page, including nested shapes. Zero matches or multiple matches fail; ambiguity reports candidate IDs instead of silently choosing one. Names shared by multiple pages are also refused for name-based page selection. Use an ID when the shape name is ambiguous. The name search visits at most 10,000 nodes and refuses incomplete lookup. A lookup's file/page/revision must still match the stable export before bytes can be published.
+
+`shots` selects top-level frames with an optional prefix. It reuses the stable PNG exporter and the capture identity checks. It supports up to 100 selected frames per run; narrow the prefix for larger pages. Empty or unstable selections exit 3 and publish no new manifest. Intervening edits or export failure preserve the previous complete manifest. `--out` is project-relative and cannot escape through a symlink. With no config, built-in capture supports explicit `--standalone`.
+
+The output contains immutable `captures/<run-id>/shot-0001.png` images and a `penpair-shots.json` manifest, published after every capture succeeds. Each entry records the original name, target IDs, revision, PNG dimensions/hash and available render environment. No baseline approval is created. Old generations remain usable; review references before cleaning them. Interrupted local publication can leave an unreferenced generation, as described in [artifact publication](artifacts.md).
+
+Use `--json` for the shared command envelope. Unknown option errors suggest a nearby spelling when one is plausible, but never reinterpret or execute the suggestion. Named exports keep the existing scale option, and `shots` accepts it too. Stable bytes and geometry are technical capture evidence; review the resulting images before judging visual correctness.

package/docs/skill-installation.md

@@ -0,0 +1,16 @@
+# Install skills and integrate project instructions
+
+```sh
+penpair skills install --agents AGENTS.md --dry-run
+penpair skills install --agents AGENTS.md
+```
+
+The preview lists planned files/links, shows the resolved instruction path and prints the owned-block diff. Dry-run writes nothing, including skill copies and links. Add `--json` for the versioned report. Skill paths reuse the project's existing real skill folder; `--to` selects another project-relative folder. Generated links are relative to the selected instruction file, with spaces and special characters encoded.
+
+Without `--agents`, exactly one existing AGENTS.md or CLAUDE.md is selected. If neither exists, installation prints rows and leaves instruction creation to an explicit destination. If both exist, it edits neither and exits 3 with `instructions.status: choice-required`; choose `--agents` explicitly. Skills may still have been installed. `setup --agents <path>` passes that destination to the same installer. Setup without a destination follows the same existing-file policy and reports when instruction integration still needs a choice.
+
+The installer appends a skills section when needed or replaces only the contents between `<!-- penpair:skills:start -->` and `<!-- penpair:skills:end -->`. Existing text outside the owned region, including line endings, is preserved. Duplicate, reversed or unmatched markers stop installation before any skill files are written. An instruction file edited after planning is preserved; retry after reviewing its current contents. A repeat run with identical content is a no-op. Existing file permissions are retained.
+
+Local outputs must remain inside the project after resolving existing symlinks. An instruction link escaping the project or a dangling link is refused. The resolved destination is shown so a project wrapper or shared in-project target is visible. These operations do not edit global agent configuration. Entry-point/output checks do not sandbox arbitrary extensions.
+
+Skill files modified by the project are kept unless `--force` is explicit. Project facts remain project-owned even with force, and rename migration preserves the prior facts. All writes are planned before execution, published as complete files, and instructions are written after skill copies/links. This is not a multi-file transaction: a filesystem failure or a concurrent owner edit can leave skill installation partly applied while preserving the instruction file. Review the report and rerun; unchanged files are skipped.

package/docs/snapshots.md

@@ -0,0 +1,20 @@
+# Structural snapshots for review
+
+```sh
+penpair snapshot
+penpair snapshot --write --out design/snapshots/current
+penpair snapshot diff design/snapshots/before --from design/snapshots/current
+penpair snapshot diff design/snapshots/before --from design/snapshots/current --out design/changes.md
+```
+
+Default mode captures for inspection and writes nothing. `--write` publishes schema-1, page-split structure and token JSON. Every page starts at the actual page root, so loose text/groups outside boards are retained. A reserved structured-inspection selector `@page-root` supports this scope. Page names must be unique for the editor's name-based selection API; ambiguity refuses rather than selecting a similarly named page.
+
+The snapshot records file/page/node identities, hierarchy/order, geometry, full text, layout, styles, token bindings, component source IDs/overrides and explicit unknown fields, plus the typed token/theme catalog. All pages and tokens must share the same file/revision, with an independent listing afterward. Changed source, incomplete transfer or credential redaction refuses publication. Capturing can switch the current editor page; no design objects are changed, and the original visible page is restored in a bounded `finally` step. Same-client collections are serialized; page changes require observed IDs rather than a fixed delay. External navigation fails clearly. If capture and restoration both fail, both errors and per-page progress are retained. The previous published manifest stays intact.
+
+Review budgets: 100 pages, 50,000 total nodes, 8 MiB per page/token artifact, 128 MiB total, five-minute collection budget checked between bounded captures. Individual captures retain I8 call/time/transfer limits. Source fields that the plugin API cannot observe remain explicit unknowns; a complete traversal does not make those fields known.
+
+Artifacts use deterministic key/node/page order, with hierarchy indices retained. Volatile capture times and transport metrics are omitted. Identical source produces identical files. Immutable `generations/HASH/` artifacts are written first and a hash-checked `snapshot.json` pointer is published last. A local exclusive publication lock refuses competing writers. An older revision or another file cannot replace the canonical pointer. Prior generations remain available; deleting them is an owner action.
+
+Offline `snapshot diff` validates all manifest/artifact hashes and identities, then reports added/removed pages/nodes and changed text, bindings, layout, geometry, styles, metadata and token catalogs. Foreign file IDs are not comparable. Large diffs show an explicit truncated result with an exact total change count (exit 3); full bounded comparisons with changes exit 2, unchanged exit 0. Markdown keeps design-supplied names/text inside literal untrusted-data fences. The command does not post comments or contact a forge.
+
+These artifacts are **review evidence**, not full-fidelity backups. They do not embed external library assets, font/image bytes, collaboration history or every native feature. Keep the [archive/hosted restore workflow](backup.md) for disaster recovery; structural diffs cannot establish a successful restore. Native component override proof and live hosted round trips remain pending.

package/docs/status.md

@@ -0,0 +1,7 @@
+# Project status and file opening
+
+`penpair status --json` reports deployment reachability, configured file pin, actual connected identity/revision/pages, observed API capabilities, skill installation differences and baseline coverage for web or local profiles. Unknown/missing evidence remains visible and produces incomplete status; a reachable web page alone cannot make the project healthy. It does not run a write probe, install skills, activate themes or approve images.
+
+By default configured adapters are listed as uninspected. `status --adapters` explicitly loads trusted configured modules and their optional `defineAdapter({status: async context => lines})` hooks. Each line has `id`, `label`, `state` (`ok`, `warning`, `failed`, `unknown`) and `detail`. The token adapter contributes declaration freshness, explicitly separate from a live token comparison. Third-party hooks execute project code and should use the context output contract. Status never implies sandboxed imports or complete native/browser acceptance.
+
+`penpair open --print` returns the public URL derived from the configured origin and encoded owner-confirmed file ID. `penpair open` invokes the platform browser opener for that same URL. No MCP key enters it. If the deployment needs extra team context, use the owner's full editor link and confirm the ID in doctor. Browser launch success cannot prove that a login/file page rendered; inspect it normally. Tests use a stub opener, not a real browser session.

package/docs/team.md

@@ -0,0 +1,17 @@
+# Working on a shared design
+
+Run `penpair onboard` (or `--json`) in the project for a checklist generated from its configured origin and pinned file. It works offline and does not load adapters. The owner invites each colleague's own account to the shared file. Each person creates their own MCP key, runs `penpair connect`, opens the pinned file and connects the MCP plugin. Share configuration and the file pin through Git; keep personal keys and `.penpair/` recovery evidence private.
+
+A direct file link is included when the pin is known. If Penpot needs team context, use the owner's complete editor link and confirm the file ID with doctor. A Docker `localhost` origin is only reachable on that computer; colleagues need a shared deployment. Onboarding does not grant access or provision accounts.
+
+## Coordinating writes
+
+Journaled CLI archive/registered operations and adapter token pushes acquire an exclusive local file for this checkout and, when supported, a shared `penpair/writer` marker on the Penpot file. The marker contains a random ownership token, run ID, operation, username and times. Another active writer refuses the operation. Read-only inspection stays available. Independent readback confirms ownership after acquisition; every step checks it again. The marker expires after 15 minutes and a longer run stops before its next step. There is no background renewal.
+
+Agree on a write window and keep the editor awake. A human can still edit. Penpot's [shared plugin-data API](https://doc.plugins.penpot.app/interfaces/File) supplies separate reads/writes rather than an atomic compare-and-swap, so this is advisory across machines. It cannot prevent two simultaneous acquisitions or act as a distributed mutex. The local lock protects this checkout, not other clones or computers. When shared methods are absent, the command warns and uses only the local lock.
+
+A crashed local process can leave a lock behind. Inspect its run with `penpair runs <run-id>`, check the file, and coordinate with the named writer before explicitly adding `--force-lock --apply` to the original command. A still-running local process cannot be forced out. The override can replace a foreign shared marker or abandoned local lock; it is not a safe way to interrupt someone. Simultaneous forced takeovers have no exclusion guarantee. Malformed shared marker data requires manual inspection; force does not silently discard it.
+
+Revisions are checked inside each journaled operation mutation. Archive also rechecks candidate IDs and geometry. Adapter pushes compare the CLI's source snapshot before planning and recheck the just-inspected token state inside each mutation. These guards detect stale input but do not make a multi-step build transactional. Known self-writes, including checkpoint and marker creation, occur before subsequent revision observations. Custom snippet authors must verify their own relevant content preconditions as well.
+
+Direct library calls that omit journal options, native checkpoint helpers invoked separately, and the explicitly destructive scratch deep probe do not acquire the journal's writer lease. Coordinate those manually. No live two-editor trial has been run for this change. See [recovery](recovery.md) after an uncertain write; do not automatically roll back intervening work.

package/docs/theme-previews.md

@@ -0,0 +1,18 @@
+# Isolated projected theme previews
+
+```sh
+penpair marwes tokens preview --from design/tokens.json --theme Light
+penpair marwes tokens preview --from design/tokens.json --theme Mode/Dark --out design/dark-preview.json
+```
+
+This is an **offline projection** of declared values. The adapter reads the retained snapshot without importing the installed application theme or connecting to Penpot. Output is schema 1, `kind: projected-theme-preview`, with a hash of the source artifact, its declared snapshot hash, selected theme/set identities and catalog order, resolved values, explicit unknowns, `complete` and `nativeBindings:false`. Missing native IDs remain null; names are not invented IDs.
+
+Later sets in catalog order win, regardless of the theme membership list order. Aliases, numeric expressions and structured values use the same neutral resolver as adapter mode verification. Missing sets/ambiguous names refuse; missing aliases, cycles, unsupported units/types or budget excess remain unknown (exit 3). A complete projection exits 0. Output paths stay within the project, refuse overwrites and cannot replace the source. Projection does not validate color meaning, layout, fonts or native component anatomy.
+
+See the [owned scratch example](../examples/theme-preview/README.md) for two independent color previews. Projected fills carry separate provenance and are not native color bindings. Existing typography/spacing/radius bindings require their own independent readback.
+
+## Pinned native capability evidence
+
+Inspected on 2026-10-22 against repository-pinned **Penpot 2.18.3**. The [pinned token implementation](https://github.com/penpot/penpot/blob/2.18.3/frontend/src/app/plugins/tokens.cljs) activates themes/sets in the file token library. The [pinned shape implementation](https://github.com/penpot/penpot/blob/2.18.3/frontend/src/app/plugins/shape.cljs) exposes token application by token and property. The [official Theme reference](https://doc.plugins.penpot.app/interfaces/TokenTheme) describes active set membership and grouped activation. These contracts do not establish an independently selected theme per frame. This is source-based evidence, not a live runtime capability proof.
+
+The adoption report observed hosted API 2.18.4, which is distinct from the pinned Docker runtime. No frame-level theme setter has been verified on either runtime here. Native per-frame color binding, native component parity and override preservation therefore remain unclaimed. A future live capability trial must inspect the actual API, change only owned scratch roots and prove unchanged global selections/catalog/order and unrelated objects. A method name or projected appearance is insufficient.