@penpair/web 0.2.0 → 0.3.1

package/README.md

@@ -4,6 +4,15 @@
 
 Inspect structure and tokens, compose reviewed recipes, capture references and hand design evidence to the implementation. Penpot holds the design; Git holds declarations, snapshots and review records.
 
+**Design in Penpot → hand off to frontend code → check the implementation.** Add the companion adapters for the parts of that workflow your project uses:
+
+| Companion | When to add it | What it helps with |
+| --- | --- | --- |
+| [Marwes UI adapter](docs/adapters.md#bring-your-component-library-into-penpot) | Your application uses Marwes UI | Bring library/project tokens into Penpot, detect drift and compose library-aware recipes |
+| [Reflection Check adapter](docs/adapters.md#check-the-frontend-against-the-design) | You implement a frontend from Penpot and want repeatable visual checks | Connect approved design cases to real browser captures and comparison evidence |
+
+**Reflection Check is the recommended companion for design-to-frontend verification.** Install it explicitly alongside your command package. It needs approved references and a project browser provider; the [adapter guide](docs/adapters.md) shows installation, registration and readiness steps.
+
 ## Choose your path
 
 | You want to… | Start here |
@@ -12,6 +21,7 @@ Inspect structure and tokens, compose reviewed recipes, capture references and h
 | Let an agent guide setup | [Setup guide skill](skills/penpair-setup-guide/SKILL.md) |
 | Join a shared file | [Team guide](docs/team.md) |
 | Build and review a page | [Design workflow](docs/design-workflow.md) |
+| Choose adapters or check the frontend | [Companion adapters](docs/adapters.md) |
 | Resolve a failure | [Troubleshooting](docs/troubleshooting.md) |
 | Extend the framework | [Guide and reference map](docs/guide.md) |
 
@@ -30,20 +40,25 @@ pnpm exec penpair skills install --dry-run
 
 Confirm the owner-authorized file ID, then follow the [skill installation preview](docs/skill-installation.md). Each teammate uses their own key. Prefer a team/web Penpot; [Docker is an alternative](packages/core/skills/penpair-setup/references/web-or-docker.md).
 
-This improvement branch is **unreleased**. Registry installs do not establish that these changes are present: review the branch or use the complete packed-package trial in the [trial runbook](docs/trials.md). Live/human checks remain explicitly pending.
+Use the installed version's `--help` to confirm available commands. For an unreleased source trial, install the complete matching package set described in the [trial runbook](docs/trials.md). Live/human acceptance gates remain explicit.
 
 ## Packages and workflows
 
-Install one command package: `@penpair/web`, or `@penpair/docker` for a local instance. Both use the neutral `@penpair/core` library. `penpair` is the short-name wrapper. Optional adapters are [`@penpair/marwes-ui`](docs/marwes.md) and [`@penpair/reflection-check`](packages/reflection-check/README.md). Every package is released together at one version; publishing belongs to the owner.
+Install one command package: `@penpair/web`, or `@penpair/docker` for a local instance. Both use the neutral `@penpair/core` library. Add the [companion adapters](docs/adapters.md) your workflow needs. Keep their versions aligned with the command package. The unscoped `penpair` wrapper currently has a publishing exception; use the scoped command package. Every repository package is versioned together; publishing belongs to the owner.
 
 | Shipped skill | Use |
 | --- | --- |
 | [penpair-setup](packages/core/skills/penpair-setup/SKILL.md) | Connect or repair project setup |
 | [penpair-design](packages/core/skills/penpair-design/SKILL.md) | Inspect and operate on a design file |
 | [penpair-recipes](packages/core/skills/penpair-recipes/SKILL.md) | Compose a page with reviewed recipes |
-| [penpair-handoff](packages/core/skills/penpair-handoff/SKILL.md) | Implement from design evidence and compare |
+| [penpair-handoff](packages/core/skills/penpair-handoff/SKILL.md) | Map components and implement from design evidence |
+| [penpair-verify](packages/core/skills/penpair-verify/SKILL.md) | Compare the real frontend, inspect images and recheck fixes |
 | [design-judgment](packages/core/skills/design-judgment/SKILL.md) | Assess page structure and hierarchy |
 
+Check a consumer's Codex installation with `pnpm exec penpair skills check --json`.
+[Discovery diagnostics and behavior trials](docs/skill-validation.md) explain what
+that establishes and how to verify actual skill use.
+
 [Cookbook](docs/cookbook.md) · [MCP tools](docs/mcp.md) · [Format contracts](docs/formats.md) · [Compatibility](docs/compatibility.md) · [Recovery](docs/recovery.md) · [Living checklist](docs/improvements.md)
 
 See [CONTRIBUTING](CONTRIBUTING.md), [SECURITY](SECURITY.md), [release steps](docs/releasing.md), [CHANGELOG](CHANGELOG.md) and the [MIT licence](LICENSE). Comparison metrics supply evidence for review; they do not approve a design.

package/docs/adapters.md

@@ -0,0 +1,90 @@
+# Companion adapters
+
+Penpair connects the design workflow to the libraries and implementation tools a project already uses. Choose the command package for your Penpot connection, then add companions for your intended workflow.
+
+| Your workflow | Recommendation | Required project inputs |
+| --- | --- | --- |
+| Inspect, build and export Penpot designs | One of `@penpair/web` or `@penpair/docker` | A configured connection and pinned design file |
+| Use Marwes UI in the frontend and Penpot | Add `@penpair/marwes-ui` | Installed library, project theme and reviewed token declarations |
+| Implement frontend code and compare it with Penpot | Add `@penpair/reflection-check` | Approved design baselines, explicit cases and a real browser provider |
+
+Adapters are installed and registered explicitly. Both companions can be used together; a comparison workflow does not require the library adapter. Keep the command package, its resolved core and directly installed adapters at the same reviewed version. Do not install both command packages.
+
+## Bring your component library into Penpot
+
+`@penpair/marwes-ui` connects the installed Marwes library and project theme to token snapshots, ownership-aware drift checks and reviewed token operations. It also provides compositional recipes and a measured-component pilot. Native component generation remains gated on actual override-preservation proof.
+
+Use it when your application uses Marwes UI. Follow the [adapter overview](marwes.md), [token configuration](marwes-tokens.md) and [build-kit guide](build-kit.md). Other libraries need their own adapters or explicit project declarations; the core contains no library defaults.
+
+## Check the frontend against the design
+
+**Recommend `@penpair/reflection-check` whenever frontend implementation and visual verification are part of the task.** It connects an approved Penpot design case to the corresponding running application case:
+
+1. Inspect the design and create a [handoff](handoff.md).
+2. Capture and review [baseline cases](coverage.md), including viewport, theme, state, fixture and fonts.
+3. Implement the frontend using the project's actual components and behavior.
+4. Map each approved design case to explicit application setup.
+5. Run a project provider to open that state, read it back, capture the browser and compare the image.
+6. Review the screenshots and differences; record human approval separately.
+
+The adapter checks that the returned evidence identifies the requested case and expected state, references the correct unchanged baseline, and has matching PNG dimensions/scale and font evidence. A complete result within the configured difference threshold is technical evidence, not visual approval or an accessibility assessment.
+
+The provider is project code with an `async runCase(test)` export. It supplies actual route/theme/state/fixture setup, browser readback, screenshot capture and image comparison through the project's pinned tools. It can integrate the project's existing Reflection/browser checker. The adapter itself does not install a browser or execute a particular Reflection engine automatically.
+
+### Install and register
+
+First check your installed command version:
+
+```sh
+pnpm exec penpair --version
+```
+
+For example, a project whose command/core are **0.3.0** installs this matching
+companion. Use the actual installed version when it differs:
+
+```sh
+pnpm add -D -E @penpair/reflection-check@0.3.0
+```
+
+Use the version printed above when it differs. In a pnpm workspace, use the existing dependency location (`-w` when installing at the workspace root). Upgrade directly installed Penpair packages together rather than mixing releases.
+
+Append the adapter to the existing `adapters` array in `penpair.config.json`, preserving other fields and already configured adapters:
+
+```json
+{
+  "adapters": ["@penpair/reflection-check"]
+}
+```
+
+That JSON is a fragment to merge, not a replacement project config. The library companion is installed the same way at the matching version and registered as `@penpair/marwes-ui`; only register packages you have installed.
+
+### Progress from installed to working
+
+- [ ] **Installed and registered:** the matching adapter dependency and config entry exist. `penpair --help` can identify configured extensions without executing them.
+- [ ] **References ready:** configured file pin and baseline frames have current exact approved provenance and explicit case metadata.
+- [ ] **Mapping ready:** `design/implementation-cases.json` maps each baseline case ID to its project setup name.
+- [ ] **Provider ready:** `design/reflection-provider.mjs` exports `runCase` and uses actual browser/checker work; requested inputs are not copied into observed results.
+- [ ] **Verified in the browser:** the plan has no pending cases, the provider executes the intended cases and the owner looks at the resulting images.
+
+```sh
+pnpm exec penpair reflection plan --map design/implementation-cases.json
+pnpm exec penpair reflection check --map design/implementation-cases.json --provider design/reflection-provider.mjs
+```
+
+Use the [package reference](https://github.com/niklas-westman/penpair/blob/main/packages/reflection-check/README.md) for mapping/provider examples. Exit **0** means complete evidence within threshold, **2** means measured drift and **3** means missing/incomplete evidence. An install, a passing setup check or a stub provider is not a completed frontend comparison.
+
+The browser-provider starter ships with the command package; supply real project
+hooks or report integration as pending. The shipped
+[penpair-verify skill](../packages/core/skills/penpair-verify/SKILL.md) guides
+comparison, image inspection, implementation fixes and recapture. For simple
+legacy route/viewport checks, the existing generated `reflection-cases.json` and
+`visualSmoke` configuration remain available; richer cases require explicit setup
+and readback.
+
+## Why explicit companions?
+
+The design-only workflow can start with one command package. Frontend projects should be guided toward the comparison companion during setup and handoff. Keeping installation explicit lets each project choose its browser/checker and supply meaningful setup instead of treating an added dependency as a finished integration.
+
+The shipped setup/handoff skills should recommend the appropriate companion, preserve existing adapter configuration and report readiness at each stage. They must keep missing references or provider work visible and never invent owner approval.
+
+Use the shipped [real-browser provider starter](../examples/reflection-browser/README.md) to supply capture plumbing while keeping route/theme/state/fixture hooks project-owned. It includes measured font, pointer, scroll and crop evidence; a browser dependency is not added to the core.

package/docs/build-kit.md

@@ -24,8 +24,8 @@ The last two examples require the token adapter configured in the adopting proje
 | `inst(parent, path, name, textOverrides, library?)` | Exact unique component match; validates named text overrides and never removes/reorders instance children. Defaults to the local library. |
 | `style(shape, options)` | Queues requested styling only; an isolated color update preserves existing spacing and bindings. |
 | `fill`, `fillV` | Sets layout-child horizontal/vertical fill sizing. |
-| `settle(root, options)` | Native completion where available, otherwise bounded equal geometry. Time/node/malformed evidence cannot report stable. |
-| `flush({root, timeoutMs})` | Waits for layout, applies queued values/styles, then awaits queued bindings, then settles again. Active token-context changes refuse. |
+| `settle(root, options)` | `strategy: auto | native | geometry`, default auto. Auto caps native at min(500 ms, remaining/4), then requires three complete equal geometry/hierarchy samples. Time/node/malformed evidence cannot report stable. |
+| `flush({root, timeoutMs, strategy})` | Waits for layout, applies queued values/styles, then awaits queued bindings, then settles again. Active token-context changes refuse. |
 
 Always `await pp.flush()` before independent readback/export. There are no fixed 1.2/2.5-second styling sleeps. Layout completion does not prove font download, token persistence or pixels; keep positive readback and stable exports. Queues are local to one execution, not a recovery log. Partial errors are not transactions; the enclosing reviewed operation must own and reconcile its roots. Bindings remain subject to the runtime's supported token properties; A4 owns the broader compatibility whitelist.
 
@@ -55,3 +55,5 @@ These are compositional starting points. They are not generated native component
 A verified trial saves a private PNG preview under `.penpair/probes/`, with byte hash and capture identity. Look at the preview as the write protocol requires. `visualApproval: false` remains explicit. Redacted/incomplete evidence cannot publish a preview; an existing differing preview is preserved. No new live pinned-version trial has been performed in this branch.
 
 Current references: [flex layout](https://doc.plugins.penpot.app/interfaces/FlexLayout), [font application](https://doc.plugins.penpot.app/interfaces/Font), [component instantiation](https://doc.plugins.penpot.app/interfaces/LibraryComponent), [spacing properties](https://doc.plugins.penpot.app/types/TokenSpacingProps) and [sizing properties](https://doc.plugins.penpot.app/types/TokenSizingProps). Runtime capability and independent evidence remain required.
+
+Host operations retain a 30 s total layout deadline; kit settle/flush default to 10 s. `native` reports failure without fallback; `geometry` skips native waiting. Diagnostics include the chosen strategy, native outcome, fallback reason and elapsed time. Neither transport loss, cancellation, changed target nor malformed/truncated data becomes a successful fallback. `run-file`, `export` and `shots` accept `--layout auto|native|geometry`. The default is suitable for ordinary builds; there is no CLI off mode.

package/docs/conventions/README.md

@@ -0,0 +1,63 @@
+# Code conventions
+
+Start with the row matching the change. Copy the relevant pattern, then use the
+nearest production module's domain vocabulary. The examples compile and run in
+`pnpm conventions:check`; production code never imports them.
+
+The [completion report](completion-2026-10-22.md) records the initial rollout,
+resolved problems, verification and limits.
+
+| Work | Read | Checked example |
+| --- | --- | --- |
+| Choose a package, folder or module boundary | [Structure](structure.md) | [Comparison adapter](../../packages/reflection-check/src/index.ts) |
+| Write a helper, contract or test | [TypeScript](typescript.md) | [Frame label](templates/frame-label.ts), [tests](templates/conventions.test.ts) |
+| Add an adapter command | [TypeScript](typescript.md), [structure](structure.md) | [Offline command](templates/adapter-command.ts) |
+| Generate code for the Penpot sandbox | [Plugin code](plugin-code.md) | [Read-only snippet](templates/frame-inspection.ts) |
+| Change release or workspace scripts | [Structure](structure.md), [releasing](../releasing.md) | Existing sibling in `scripts/` |
+
+```sh
+pnpm format             # Format supported source/configuration files
+pnpm lint:fix           # Apply safe lint fixes
+pnpm check:style        # Check formatting, focused lint rules and code directory names
+pnpm conventions:check # Typecheck and execute these examples
+pnpm check              # Style, build, typecheck, examples, tests and version consistency
+pnpm smoke:package      # Verify the packaged installation shapes
+```
+
+`biome.json` is the formatting authority: two spaces, LF, a 100-column target,
+double quotes, semicolons, expanded object/array layouts and parenthesized arrow
+parameters. Braces and one variable per declaration keep control flow readable.
+Use the editor's Biome extension with the repository's pinned version if desired;
+`.editorconfig` supplies the basic whitespace settings in other editors.
+
+Biome checks filenames; `check-code-paths.mjs` checks directories containing code
+under `packages/`, `scripts/`, `examples/` and this folder, including new untracked
+files. Both run in CI through `pnpm check`. Human/agent review still checks whether
+names describe intent and whether responsibilities should be split. A formatter
+cannot judge those decisions.
+
+Vertical spacing is also an author/review responsibility: Biome keeps intentional
+blank lines, but does not add separation between declarations or logical steps.
+Follow [TypeScript spacing guidance](typescript.md) even when `check:style` passes.
+
+The [repository skill](../../.agents/skills/penpair-code-conventions/SKILL.md)
+applies this workflow to implementation and refactoring work. It develops Penpair
+itself; the separately shipped `packages/core/skills/` teach consumers how to use
+Penpair with their designs.
+
+## Coverage and exceptions
+
+- Generated `dist/`, dependencies, ignored local artifacts and data fixtures are
+  outside formatting. Keep captured evidence unchanged.
+- `docs/trials/` and `docs/upstream/` preserve external evidence.
+- Raw plugin bodies in `examples/hello-card/`, `examples/theme-preview/` and
+  `examples/trials/` may contain a top-level `return`, which Biome's module parser
+  rejects. Their existing sandbox tests compile them as async function bodies.
+  Follow [plugin code](plugin-code.md) when editing them.
+- JavaScript inside template strings is string data to Biome. Format that source
+  deliberately and test the generated snippet. Do not run blind whitespace
+  rewriting over strings, serialized snapshots or embedded protocols.
+
+Add new file-type examples when an actual feature needs a pattern. Keep them
+minimal and executable; do not introduce a framework or dependency just for a
+template.

package/docs/conventions/completion-2026-10-22.md

@@ -0,0 +1,73 @@
+# Readability conventions completion — 2026-10-22
+
+Branch: `codex/tradient-feedback`. All repository package versions remain 0.2.0.
+
+## Completed checklist and what each update resolves
+
+- [x] **Readable formatting baseline.** Pin Biome 2.6.2, use two-space indentation
+  and expanded layouts, add braces and separate variable declarations. This
+  removes compressed source layouts and makes subsequent diffs consistent. The
+  mechanical baseline is its own commit, `b1a9445`, for review.
+- [x] **Maintained conventions.** Add task-based guidance for naming, package
+  ownership, module extraction, TypeScript, tests and sandbox code. This gives new
+  work a concrete placement and implementation pattern instead of relying on
+  memory or copying unrelated frontend conventions.
+- [x] **Checked examples.** Typecheck actual core contracts and run helper,
+  sandbox-generation and path-rule tests. This catches stale examples and proves
+  that the generated plugin body compiles and behaves as documented.
+- [x] **Agent discovery.** Link the conventions and repository-local
+  `penpair-code-conventions` skill from `AGENTS.md`, with contributor routing from
+  `CONTRIBUTING.md`. This makes readable names and early responsibility extraction
+  part of the implementation workflow.
+- [x] **Continuous enforcement.** Include Biome, directory naming and example
+  validation in `pnpm check`, which existing CI already runs. The CI job name stays
+  stable for branch protection. These checks prevent automatic style/path drift;
+  review still judges the meaning of names and module boundaries.
+- [x] **Comparison adapter extraction.** Replace the dense entrypoint with focused
+  public contracts, planning, capture validation, provider validation, PNG I/O,
+  orchestration and command modules. Public imports, report fields, approval gates
+  and command behavior remain compatible. Shared test fixtures and capture tests
+  also have focused files.
+- [x] **Installed contract verification.** Extend package smoke testing to import
+  the packed adapter's public functions/default export and typecheck its public
+  contracts. This catches missing extracted files or broken declaration exports.
+
+## Validation
+
+- `pnpm check` passes: **640 package tests plus 3 convention tests**, style/path
+  checks, builds, typechecks and the six-package version guard.
+- `pnpm smoke:package` passes for all **six tarballs**, including the new runtime
+  export and declaration checks.
+- The comparison package's tests/helpers also pass a separate strict TypeScript
+  check. Skill YAML metadata, UI metadata and local convention/skill links resolve.
+- Before the manual extraction, an AST comparison across 199 changed
+  JavaScript/TypeScript files found no differences beyond formatting, equivalent
+  control-flow blocks and separate declarations. The initial formatted baseline
+  passed all 630 pre-existing tests.
+- `git diff --check` passes. A patch Changeset records the delivered refactor and
+  documentation. No version bump, push, publication or live Penpot write occurred.
+
+## Limits
+
+Biome cannot determine whether a name expresses the right domain meaning or when
+responsibilities deserve separate modules; the skill and review cover those
+decisions. Raw async plugin bodies, JavaScript inside strings, generated artifacts
+and captured fixtures retain the handling described in the [conventions index](README.md).
+This update does not constitute new live Penpot or browser acceptance. The
+[existing pending acceptance](../plans/tradient-feedback-review.md#remaining-acceptance)
+stays open.
+
+## Vertical spacing correction
+
+- [x] Separate declarations and individual steps in the component pilot module.
+- [x] Clarify that Biome retains author-supplied blank lines but does not insert
+  the separation required by the conventions.
+
+Resolved: `packages/marwes-ui/src/components.ts` passed Biome while remaining
+visually dense. The file now has blank lines between its contracts, functions,
+guards and work steps. The diff contains only added blank lines, and Biome keeps
+them. `pnpm check:style` and all three existing component tests pass. No behavior
+changed; the full suite was not rerun for this whitespace-only follow-up.
+
+Automatic vertical-spacing enforcement remains outside the current Biome checks;
+the conventions and code review require it explicitly.

package/docs/conventions/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -0,0 +1 @@
+{"version":"3.2.4","results":[[":templates/conventions.test.ts",{"duration":3.757374000000027,"failed":false}]]}

package/docs/conventions/plugin-code.md

@@ -0,0 +1,23 @@
+# Penpot plugin source
+
+Node-side TypeScript and the Penpot editor sandbox are different environments.
+The sandbox has `penpot` and explicit injected values such as `CFG`; it cannot
+import Node filesystem modules or reach local project paths. Keep Node I/O outside
+the generated source. Use the neutral kit/snippet APIs and actual upstream names.
+
+Raw plugin files are async function bodies and may return at the top level.
+`*.ts` generators are ordinary Node modules and are formatted by Biome; their
+template string contents need deliberate formatting. Prefer readable multiline
+source with descriptive names and braces. Preserve string values and parameter
+serialization when editing whitespace.
+
+The [frame inspection example](templates/frame-inspection.ts) shows a small
+read-only generator. Its tests compile the generated body and execute it against
+a sandbox stub. This catches syntax and behavior errors that formatting the
+outer TypeScript module cannot catch.
+
+For writes, follow [the write protocol](../../packages/core/skills/penpair-design/references/write-protocol.md):
+inspect, pin a snapshot, perform one idempotent write, independently read back,
+then export and look. Preserve file/page guards, bounded layout settling and the
+under-90-KB transport limit. A syntax test does not prove live Penpot behavior.
+Tests may stub read-only sandbox objects; live acceptance remains separate.

package/docs/conventions/structure.md

@@ -0,0 +1,48 @@
+# Folder and module structure
+
+Place code with the responsibility that owns it. The dependency direction is
+command packages/adapters → core; the core never imports an adapter or names a
+consumer project or component library.
+
+| Location | Owns |
+| --- | --- |
+| `packages/core/src/` | Neutral engine, validation, transport and public extension contracts |
+| `packages/web/`, `packages/docker/`, `packages/penpair/` | Command distribution and profile-specific lifecycle |
+| `packages/<adapter>/src/` | Library/tool knowledge and its adapter commands |
+| `packages/<package>/test/` | That package's behavior and integration contracts |
+| `scripts/` and `scripts/lib/` | Workspace/release tooling and reusable script helpers |
+| `examples/<feature>/` | Consumer-facing workflows and explicit sample project knowledge |
+| `packages/core/skills/` | Shipped consumer workflows |
+| `.agents/skills/` | Skills for developing this repository |
+| `docs/conventions/templates/` | Checked examples, never runtime dependencies |
+
+Use kebab-case for new code directories and filenames. Prefer a domain name such
+as `capture-validation.ts` over `helpers.ts`, `utils.ts` or `manager.ts`. Add a
+feature folder when several related files form one cohesive area; keep small
+features as siblings rather than adding a directory around every file. Preserve
+tool-required names such as `AGENTS.md`, `SKILL.md` and `README.md`.
+
+## Split as soon as a responsibility stands on its own
+
+Extract a responsibility when it has its own inputs/outputs, invariants or useful
+tests. Do this in the change that introduces it. Typical splits are public types,
+argument parsing/provider loading, pure planning, evidence validation and image
+I/O. Keep a package's public `index.ts` focused on exports and adapter wiring.
+Preserve public imports when moving implementations.
+
+The comparison adapter demonstrates this shape: `case-plan.ts` plans approved
+cases, `evidence-validation.ts` validates observed state, `capture-validation.ts`
+checks browser geometry, `png-evidence.ts` reads bounded images, `run-cases.ts`
+orchestrates evidence collection, and `command.ts` handles CLI/provider loading.
+
+Do not split tightly coupled steps solely to make files short. Avoid one-line
+forwarders and a forest of generic folders. Repeated domain code, mixed I/O and
+validation, a long boolean condition, or unrelated reasons for a file to change
+are stronger signals than a line count. Around 200 lines in a module or 40 lines
+in a function is a review prompt, not an automatic failure or a reason to hide
+complexity in another large helper.
+
+Before extracting, identify the public contract and the tests that protect it.
+After extracting, read the orchestration from top to bottom: names should explain
+the workflow without opening every helper. Keep shared types below implementations
+in the dependency direction and avoid circular imports or unnecessary barrels.

package/docs/conventions/templates/adapter-command.ts

@@ -0,0 +1,28 @@
+import type { AdapterCommand, AdapterContext } from "../../../packages/core/src/adapters.js";
+
+async function runExampleStatus(
+  context: AdapterContext,
+  commandArguments: string[],
+): Promise<number> {
+  if (commandArguments.length > 0) {
+    throw new Error("Usage: example-status");
+  }
+
+  const report = {
+    configured: Boolean(context.config.file),
+  };
+  context.output?.result(report);
+  context.log(JSON.stringify(report));
+
+  return report.configured ? 0 : 3;
+}
+
+// Register in an adapter's defineAdapter({ commands: [...] }) when adopting this pattern.
+export const exampleStatusCommand: AdapterCommand = {
+  name: "example-status",
+  summary: "Report offline file-pin readiness",
+  usage: [
+    "penpair example-status",
+  ],
+  run: runExampleStatus,
+};

package/docs/conventions/templates/conventions.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { compiles } from "../../../packages/core/src/snippet.js";
+import { findInvalidCodeDirectories } from "../../../scripts/check-code-paths.mjs";
+import { formatFrameLabel } from "./frame-label.js";
+import { createFrameInspection } from "./frame-inspection.js";
+
+describe("convention examples", () => {
+  it("normalizes names and refuses incomplete labels", () => {
+    expect(
+      formatFrameLabel({
+        pageName: " Dashboard ",
+        frameName: " Empty ",
+      }),
+    ).toBe("Dashboard / Empty");
+    expect(() =>
+      formatFrameLabel({
+        pageName: " ",
+        frameName: "Empty",
+      }),
+    ).toThrow("requires");
+  });
+
+  it("compiles and executes the generated read-only sandbox body", async () => {
+    const inspection = createFrameInspection("Empty");
+    expect(compiles(inspection.code)).toBeUndefined();
+    const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+    const executeInspection = new AsyncFunction("penpot", inspection.code);
+    const frame = {
+      id: "frame-1",
+      type: "board",
+      name: "Empty",
+    };
+
+    expect(
+      await executeInspection({
+        currentPage: {
+          children: [
+            frame,
+          ],
+        },
+      }),
+    ).toEqual({
+      ok: true,
+      frameId: "frame-1",
+      frameName: "Empty",
+    });
+    expect(
+      await executeInspection({
+        currentPage: {
+          children: [
+            frame,
+            frame,
+          ],
+        },
+      }),
+    ).toMatchObject({
+      ok: false,
+    });
+  });
+
+  it("checks new code folders while leaving data paths outside the code rule", () => {
+    expect(
+      findInvalidCodeDirectories([
+        "packages/core/src/capture-validation.ts",
+        "examples/browser-capture/provider.mjs",
+        "docs/conventions/templates/frame-label.ts",
+        "docs/trials/ImportedEvidence/report.json",
+      ]),
+    ).toEqual([]);
+    expect(
+      findInvalidCodeDirectories([
+        "packages/core/src/captureHelpers/geometry.ts",
+        "packages/core/src/captureHelpers/fonts.ts",
+        "examples/BrowserCapture/provider.mjs",
+      ]),
+    ).toEqual([
+      "examples/BrowserCapture",
+      "packages/core/src/captureHelpers",
+    ]);
+  });
+});

package/docs/conventions/templates/frame-inspection.ts

@@ -0,0 +1,27 @@
+import { snippet, type Snippet } from "../../../packages/core/src/snippet.js";
+
+export function createFrameInspection(frameName: string): Snippet {
+  if (!frameName.trim()) {
+    throw new Error("Frame name is required");
+  }
+
+  return snippet(
+    "example-frame-inspection",
+    `
+const matchingFrames = penpot.currentPage.children.filter((shape) => {
+  return shape.type === "board" && shape.name === CFG.frameName;
+});
+
+if (matchingFrames.length !== 1) {
+  return { ok: false, message: "Expected one uniquely named frame" };
+}
+
+const frame = matchingFrames[0];
+return { ok: true, frameId: frame.id, frameName: frame.name };
+`,
+    {
+      frameName,
+    },
+    "read",
+  );
+}

package/docs/conventions/templates/frame-label.ts

@@ -0,0 +1,15 @@
+export interface FrameLabel {
+  pageName: string;
+  frameName: string;
+}
+
+export function formatFrameLabel(label: FrameLabel): string {
+  const pageName = label.pageName.trim();
+  const frameName = label.frameName.trim();
+
+  if (!pageName || !frameName) {
+    throw new Error("A frame label requires a page name and a frame name");
+  }
+
+  return `${pageName} / ${frameName}`;
+}

package/docs/conventions/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "declaration": false,
+    "allowJs": true,
+    "checkJs": true
+  },
+  "include": [
+    "templates/**/*.ts",
+    "vitest.config.ts"
+  ]
+}

package/docs/conventions/typescript.md

@@ -0,0 +1,59 @@
+# TypeScript and naming
+
+Use `pnpm format` and `pnpm check:style`; do not hand-align code against Biome.
+Separate top-level declarations and distinct steps inside a function with blank
+lines. Use braces for every branch and loop, and declare one variable at a time.
+Prefer early exits that leave the main path easy to follow.
+
+Biome preserves these blank lines but does not insert them between declarations
+or logical steps. Add them while writing/reviewing code, before running the
+formatter. A passing style check alone does not prove that vertical spacing follows
+this convention. Separate each top-level declaration (including interfaces and
+type aliases), and separate input preparation, guard clauses, work and returns
+inside a function. Keep a documentation comment attached to its declaration.
+
+## Names carry intent
+
+- Files and folders: `capture-validation.ts`, `page-session/`. Keep conventional
+  `index.ts`, `*.test.ts`, `*.config.ts` and tool-required filenames.
+- Values and functions: `captureMetadata`, `baselineImage`, `implementationCase`,
+  `validateCaptureMetadata`. Use a verb for an action and a noun for a value.
+- Types: `ImplementationCase`, `BrowserCaptureMetadata`. Prefer interfaces for
+  object contracts and unions for finite alternatives.
+- Booleans: `fontsReady`, `hasCurrentApproval`, `isComplete`.
+- Units and encodings: `timeoutMs`, `maxSnippetBytes`, `screenshotHash`,
+  `imageWidth`. Make conversions visible where they happen.
+- Avoid one-letter domain names (`c`, `m`, `r`, `b`) and unexplained abbreviations
+  (`cfg`, `sub`, `rest`) when the full name makes the next line understandable.
+  Familiar small mathematical coordinates (`x`, `y`) remain appropriate.
+- Preserve public field names, CLI flags and external API spelling. Improve a
+  local binding without renaming a persisted schema or an upstream property.
+
+Use `const` unless reassignment is needed. Export named functions and types;
+adapter definitions retain the default export required by their loader. Give
+exported functions explicit return types. Use `unknown` with validation at input
+boundaries rather than `any` or a cast that pretends an external value was checked.
+
+## Functions and errors
+
+A function should name one operation at one level of detail. Extract a named
+predicate when a condition combines independently meaningful rules; retain the
+short-circuit checks that protect access to malformed input. Extract filesystem
+work from pure validation when each can be tested independently.
+
+Throw errors with actionable domain context. Catch them where a caller can choose
+recovery, report a failed case or return a command exit code. Preserve existing
+error classifications, redaction and cancellation behavior during a refactor.
+Comment on non-obvious reasons; use names to explain routine steps.
+
+## Tests
+
+Use the package's Vitest runner and its existing `test/` layout. Test observable
+contracts: accepted evidence, rejected malformed/stale evidence, partial progress,
+and filesystem boundaries. Keep fixtures local and deterministic. For a refactor,
+keep a public-entrypoint integration test and add regression cases for the rules
+being extracted. Avoid tests that only search for an implementation's wording.
+
+Production TypeScript uses ESM imports with `.js` for local modules. Match the
+existing NodeNext configuration. Documentation templates import actual core types
+so API changes invalidate stale examples during `pnpm check`.

package/docs/conventions/vitest.config.ts

@@ -0,0 +1,11 @@
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  root: fileURLToPath(new URL("./", import.meta.url)),
+  test: {
+    include: [
+      "templates/**/*.test.ts",
+    ],
+  },
+});

package/docs/design-workflow.md

@@ -6,6 +6,8 @@
 4. Present the exact artifact to the owner. [Approval records](approvals.md) retain supplied words and capture hashes; a comparison percentage never supplies approval.
 5. Capture [baselines and case coverage](coverage.md). A changed reference requires matching approval or an explicitly labeled waiver; unsupported cases remain pending.
 6. Generate a [structured handoff](handoff.md) with explicit component mappings. Implement behavior, responsive rules and accessibility from an actual application contract rather than inferred appearance.
-7. Capture the actual implementation case with stable fonts/data. Inspect comparison evidence and images, resolve drift, and report changed behavior, validation and remaining risks.
+7. Use the recommended [Reflection Check companion](adapters.md#check-the-frontend-against-the-design) and a real project browser provider to capture the actual implementation case with stable fonts/data. Inspect comparison evidence and images, resolve drift, and report changed behavior, validation and remaining risks. Missing provider/setup work remains pending.
 
 [Structural snapshots](snapshots.md) make design review diffable. [Archives and restore trials](backup.md) establish recovery independently. The current branch has offline fixtures and repeatable [human trial instructions](trials.md); it has not completed those real trials.
+
+Before expanding variants, choose the primary task and an existing reference, establish hierarchy/context and responsive/focus order, then critique one small first frame. Use `inspect → spec → snapshot/diff → capture/approve → comparison` from installed `penpair --help`. Exact owner words approve only the captured artifact; first-frame critique does not grant approval. Layout strategy and fresh doctor evidence are described in [build kit](build-kit.md) and [recovery](recovery.md).