@penpair/core 0.2.0 → 0.3.1

package/skills/penpair-handoff/references/comparison-companion.md

@@ -0,0 +1,16 @@
+# Frontend comparison companion
+
+Recommend `@penpair/reflection-check` when a task moves from a design into frontend implementation and visual verification. It connects approved design cases to a real project browser provider; that provider handles route, theme, state, fixtures, fonts, screenshot capture and comparison.
+
+1. Inspect the project's installed command/core versions and `adapters` configuration. Offer the companion at the same reviewed version, using the project's package manager and dependency location. Merge its config entry while preserving other adapters. Do not install a second command package.
+2. Follow the [companion setup guide](https://github.com/niklas-westman/penpair/blob/main/docs/adapters.md#check-the-frontend-against-the-design). The project needs a pinned file, approved baseline provenance and explicit viewport/theme/state/fixture/font cases. Existing human approval cannot be invented or carried over to changed artifacts.
+3. Prepare an explicit case-to-setup mapping and a trusted project module exporting `async runCase(test)`. The module must perform actual browser setup, readback, capture and comparison using the project's tools. A stub or copied input labels cannot establish browser verification.
+4. Run `penpair reflection plan --map FILE`, then `penpair reflection check --map FILE --provider FILE` once ready. Inspect the images and report pending cases, measured drift and unknowns. Preserve the baseline bytes.
+5. Report separate readiness stages: installed, registered, references approved, cases mapped, provider configured, browser verified and owner reviewed. Missing stages are explicit pending work. Never describe installing the adapter as supplying a browser or a complete frontend integration.
+
+The package reference defines the current provider evidence contract. For a
+design-only task, defer implementation setup until that work is in scope. Use
+`penpair-verify` when installed for the real browser comparison and repair loop.
+The final comparison verdict still requires owner review.
+
+The command package ships a real-browser starter at `node_modules/@penpair/web/examples/reflection-browser/`. Supply project-owned setup and independent state hooks; read its README for font, scroll/sticky, pointer and crop requirements. Keep browsers pinned in the adopting project.

package/skills/penpair-handoff/references/handoff-flow.md

@@ -1,5 +1,7 @@
 # Evidence and review
 
+For frontend checks, first follow [the recommended comparison companion](comparison-companion.md). Report adapter installation separately from complete browser/provider evidence.
+
 Use `spec --page PAGE --frame ID` for live evidence or `spec --from INSPECTION --map MAP --out FILE` for an offline handoff. `spec check` regenerates against the supplied inspection/map and detects manual edits or changed provenance. Offline success establishes freshness against those inputs, not the current live file or an unchanged PNG.
 
 A schema-1 map declares exact `libraryId`, `componentId`, identifier `codeComponent`, literal scalar `props` and `textProps` pointing at exact descendant text node IDs. Familiar names and equal scalar values are insufficient for automatic semantic mapping. Missing references remain unknown. A single captured viewport/state cannot establish responsive behavior, application transitions, focus order, keyboard support or accessible roles.

package/skills/penpair-recipes/SKILL.md

@@ -1,16 +1,28 @@
 ---
 name: penpair-recipes
-description: Build or update a Penpot page through reviewed penpair recipes, active tokens and an idempotent script, then verify the resulting objects and export.
+description: Build a Penpot screen or create loading, empty or error variants from an approved frame using the existing library and tokens. Use for design construction and state variants in Penpot; frontend implementation belongs to penpair-handoff.
 ---
 
 # Page recipes
 
 Use the existing project library and declared tokens as inputs. Work within the owner's authorized design scope; retain unresolved choices for review.
 
+
+Before building a page, record a short composition decision: the primary user task, one chosen existing reference, visual hierarchy and useful context, responsive behavior and focus order. Build one small representative frame first; critique its hierarchy, density and missing context before expanding themes/states/devices. This is a design decision and critique, not owner approval.
+
+For a substantial state variant or screen family, read
+[visual-checkpoint.md](references/visual-checkpoint.md) and create a project-owned
+evidence record. Carry the approved image/inspection, preserved regions and
+intentional deviations into the plan. Keep expansion pending until the first
+candidate has actual comparison evidence and its blocking findings are resolved.
+Do not infer critique from a passing mechanical audit.
+
 1. **Target.** Read the project's design facts and `penpair doctor --json`. Confirm the pinned file and exact page/frame IDs. Done when the connected target matches the authorized target and required APIs are observed.
 2. **Vocabulary.** Inspect the actual token catalog, theme selection and existing components. Select explicit token names/types and component IDs. Done when every recipe input resolves or is listed as an explicit missing dependency. Equal computed values alone establish candidate matches.
 3. **Preview.** Read [build-flow.md](references/build-flow.md) for file declarations, helper order and partial-root ownership. Prepare an idempotent operation with positive independent readback. Run inspection first. Done when source preconditions and the exact changed objects are reviewable.
 4. **Build.** Apply within the existing authorization, set values/fonts before bindings and await helper flush. On uncertainty, retain the run ID and inspect actual state before explicit recovery. Done when independent geometry, text and binding evidence matches the intended output.
 5. **Judge.** Export until stable, inspect the image twice, and audit the complete relevant scope. Done when visual findings and unknowns are reported separately from mechanical verification. Name frames with the project's page/state/device convention.
 
+When frontend implementation follows, recommend the comparison companion described in the [adapter guide](https://github.com/niklas-westman/penpair/blob/main/docs/adapters.md#check-the-frontend-against-the-design) and the installed handoff skill. Retain intended viewport/theme/state/fixture information so the project can map approved designs to actual browser cases. A rendered design is not yet a verified implementation.
+
 Report **Changed**, **Validated**, **Risks**, with exact object/artifact IDs and any owner decisions still needed. The kit smoke test is scratch work requiring its own authorized target. Native library expansion stays gated on demonstrated instance-override preservation.

package/skills/penpair-recipes/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Penpair Recipes"
+  short_description: "Build screens and approved-design variants"
+  default_prompt: "Use $penpair-recipes to create a state variant from the approved Penpot frame and critique one representative candidate."
+policy:
+  allow_implicit_invocation: true

package/skills/penpair-recipes/assets/visual-checkpoint.md

@@ -0,0 +1,48 @@
+# Visual evidence checkpoint
+
+Copy into the project's review folder and replace every pending field with actual
+evidence or a reason it remains unknown. This is an unfilled template, not proof
+of an inspection, comparison or approval.
+
+- Work / case ID: pending
+- Mode: design variant / frontend comparison (select one)
+- Current status: pending
+- Next action and responsible person/agent: pending
+
+## Source and intended change
+
+- Authorized scope and user task: pending
+- Source image path and complete inspection path: pending
+- File / page / frame IDs and captured revision: pending
+- Approval record / exact approved case and reference hash, or missing approval: pending
+- Source image actually inspected; observed hierarchy/density: pending
+- Existing component identities and relevant token evidence: pending
+
+| Region | Preserve or change | Evidence / reason for deviation |
+| --- | --- | --- |
+| pending | pending | pending |
+
+## Representative result
+
+- Candidate frame / implementation route: pending
+- Viewport, theme, state, fixture and expected fonts: pending
+- Stable candidate image and independent readback: pending
+- Source/candidate comparison view and regions inspected: pending
+- Provider/setup/version and observed browser state (frontend only): pending
+- Comparison result / drift / screenshot hash (frontend only): pending
+- Mechanical audits and their limits: pending
+
+| Location | User impact | Observed evidence | Fix / explicit decision | Rerun case and result |
+| --- | --- | --- | --- | --- |
+| pending | pending | pending | pending | pending |
+
+## Decision and continuation
+
+- [ ] Source and candidate evidence exist and were inspected.
+- [ ] Preserved regions and intentional deviations were compared.
+- [ ] Blocking findings are resolved; remaining unknowns are explicit.
+- Expansion readiness: pending (with reason)
+- Behavior/accessibility checks: not assessed
+- Owner approval: pending; record exact words/artifact only if actually supplied
+- Attempts / tooling effort / revised approach if blocked: pending
+- Next case or action, with exact artifact paths: pending

package/skills/penpair-recipes/references/visual-checkpoint.md

@@ -0,0 +1,37 @@
+# Comparative evidence checkpoint
+
+For a new screen family or a substantial variant of an approved design, copy the
+[checkpoint template](../assets/visual-checkpoint.md) into the project's review
+folder before building. Use the project's existing report format if it retains
+the same evidence. The copy is project-owned; never keep completed records inside
+an installed skill folder, where `skills install --force` may refresh templates.
+
+Record one representative case first. Link the actual approved image and complete
+inspection with file/page/frame identity, revision, approval/case identity and
+relevant component/token evidence. State which regions keep their layout,
+hierarchy, density, type scale and native instances, and which intentionally
+change. A sentence naming a reference does not establish that its image was seen.
+If the task has no approved reference, record that limitation and the chosen
+design direction; do not manufacture provenance or turn a draft into a baseline.
+
+Before expanding devices/themes/states, export the candidate until stable, look
+at source and candidate and record the consequential findings. Use a side-by-side
+view at comparable scale; compare preserved regions separately from intentionally
+changed content. Whole-page pixel equality is inappropriate for different data
+states. A clean token/overflow audit and a generated screenshot do not establish
+visual critique. Recomposition is allowed within the task's scope when its reason
+and deviations are explicit; owner acceptance stays separate.
+
+Expansion is ready only when the representative candidate has real source and
+candidate evidence, a recorded critique and resolved blocking findings. Missing
+images, unobserved instance behavior or failed readback remain pending. If
+repeated failures or substantial tooling work prevent this result, report the
+current evidence, effort and revised approach before adding a renderer or a larger
+case matrix. Preserve source/library objects and stop ambiguous write retries.
+
+For frontend work, carry the case record through handoff and browser comparison:
+retain the route, viewport, theme, state, fixture, fonts, setup/provider identity,
+baseline hash, observed screenshot and rerun result. Use `penpair-verify` when
+installed. Design-to-design critique does not satisfy frontend verification, and
+browser comparison does not approve a new design. Another agent should be able to
+continue from the record's next action without guessing which artifact was judged.

package/skills/penpair-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: penpair-setup
-description: Set up penpair in a project and connect it to a Penpot, on the web (the default) or in Docker on this computer. Use when a project has no penpair.config.json, when `penpair doctor` reports a failure, when the user asks to install, start, connect, repair or move their Penpot connection, or when an agent is told "set up penpair". Do not use for editing a Penpot file (penpair-design) or deciding how a screen looks (design-judgment).
+description: Install Penpair or connect and repair a project's Penpot setup, including a failing doctor check, suspended plugin or missing configuration. Use for connection and setup work; use penpair-design to edit designs and design-judgment to choose their composition.
 metadata:
   version: "0.1.0"
   scope: setup and connection
@@ -14,11 +14,15 @@ Two ways to run Penpot, one way to connect. **Web** (design.penpot.app, or a tea
 
 ## The key never passes through you
 
+For an existing installation, use its local command and reviewed version
+(`pnpm exec penpair` in pnpm projects) in place of the first-use `npx` examples
+below. Preserve its chosen command package and current profile.
+
 The MCP key is the person's password to their Penpot. Keep it out of chat, logs, commands and commits. The person pastes it themselves into a prompt that hides it (`penpair connect`), or pipes it from their clipboard (`pbpaste | npx @penpair/web connect`). Your shell cannot answer a hidden prompt, so hand that one step to the person with the exact words below.
 
 ## Steps
 
-1. **Look.** If `penpair.config.json` exists, run `npx @penpair/web doctor --json` and read its versioned envelope: `data.ok`, then `data.checks`. Done when you can name the first failing check, or say all pass. If all pass, stop here and say so.
+1. **Look.** If `penpair.config.json` exists, run `npx @penpair/web doctor --json` and read its versioned envelope: `data.ok`, then `data.checks`. Done when you can name the first failing check, or say all pass. If all pass, skip connection repair and check the companion recommendations in step 7 before reporting setup complete.
 2. **Choose where Penpot runs.** Recommend web. Choose Docker when the person asks for offline work, data that stays on this computer, or a disposable instance. Ask once, in one sentence, and take the answer. Done when the choice is stated. The decision table and what is checked: [references/web-or-docker.md](references/web-or-docker.md).
 3. **Initialise.**
    - Web: `npx @penpair/web init --external https://design.penpot.app --gitignore` (a team's own Penpot: its address instead).
@@ -39,7 +43,9 @@ The MCP key is the person's password to their Penpot. Keep it out of chat, logs,
    | editor and plugin: not connected or suspended | The tab is asleep or the plugin is not connected. Do step 4.4 again; keep the tab in front. |
    | key file: git would commit it | Add `.env.local` to `.gitignore`; `penpair connect` does it. |
 
-6. **Install the rules.** Run `npx @penpair/web skills install`, add the printed rows to the project's agent guide, then fill in `.skills/penpair-design/references/project-facts.md` with the person (the Penpot file, token sets, naming, who approves). Done when that file has no `<...>` placeholders left.
+6. **Install the rules.** Use the installed local command when available (`pnpm exec penpair` in pnpm projects). Preview `penpair skills install --agents AGENTS.md --dry-run`, then apply the reviewed update to the selected instruction file. Preserve project customizations and fill in the installed `penpair-design/references/project-facts.md` (file pin, token sets, naming, who approves); use the destination printed by the installer. Run `penpair skills check --json` for Codex discovery/routing diagnostics, selecting `--only` for intentional partial installs. A passing file check does not prove a session loaded or correctly applied a skill. Done when required project facts and diagnostics are ready, or their missing evidence is reported explicitly.
+
+7. **Recommend companions for the task.** Read the [adapter guide](https://github.com/niklas-westman/penpair/blob/main/docs/adapters.md). A library adapter brings the project's chosen component-library tokens and recipes into the workflow. When frontend implementation/comparison is in scope, recommend `@penpair/reflection-check`, installed at the same version as the command/core and merged into the existing `adapters` list. State the remaining requirements: approved baselines, explicit case mappings and a real browser provider. Record those as pending until configured and exercised; connection-ready does not mean comparison-ready. Design-only projects can defer comparison setup.
 
 ## Moving between web and Docker
 

package/skills/penpair-setup/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Penpair Setup"
+  short_description: "Connect or repair a Penpot project"
+  default_prompt: "Use $penpair-setup to diagnose this project's Penpot connection and report the remaining setup steps."
+policy:
+  allow_implicit_invocation: true

package/skills/penpair-verify/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: penpair-verify
+description: Verify a frontend against an approved Penpot design using Penpair Reflection Check. Use to check visual parity, investigate design mismatches or recheck an implementation after fixes with real browser screenshots and observed application state.
+---
+
+# Frontend verification
+
+Compare the real implementation with the exact approved design case. Use the
+project's configured browser provider and component library. A captured design,
+an installed adapter and a passing build each establish different facts.
+
+Continue the project's existing comparative checkpoint, or create a project-owned
+case report outside installed skill folders. Retain source/candidate identities,
+preserved and changed regions, actual image paths, observed setup, consequential
+findings and the next action. If `penpair-recipes` is installed, its
+`references/visual-checkpoint.md` and template supply the common format.
+
+1. **Establish readiness.** Inspect the installed command and adapter versions,
+   the project's existing verification scripts, approved reference and explicit
+   case mapping. Use the local command (`pnpm exec penpair` in pnpm projects).
+   Report installed, registered, references approved, cases mapped, provider
+   configured, browser verified and owner reviewed separately. Keep unavailable
+   stages pending; do not invent approval or replace an unimplemented setup.
+2. **Plan the case.** Run `penpair reflection plan --map FILE`. Confirm the
+   reference identity/hash and intended route, viewport, theme, state, fixture and
+   fonts. Start with one representative case before expanding the matrix. For
+   browser evidence requirements, read [browser-evidence.md](references/browser-evidence.md).
+3. **Run the real browser.** Start or reuse the authorized local application and
+   run `penpair reflection check --map FILE --provider FILE`. The project module
+   must activate and independently observe the requested application state.
+   Exit 0 means complete evidence within thresholds; 2 means measured drift;
+   3 means incomplete evidence. An execution error establishes no comparison.
+4. **Inspect and repair.** Look at the approved image and actual browser image;
+   inspect a diff image when the checker produces one. Record consequential
+   findings as location, impact, evidence, proposed fix and rerun case. Fix
+   implementation mismatches within scope, then recapture affected cases. Do
+   not overwrite approved references, change case intent or loosen thresholds
+   merely to pass. A design change goes back through design review and approval.
+5. **Checkpoint and report.** If repeated failures or substantial tooling work
+   prevent a representative visual result, report the evidence and revised
+   approach before expanding tools or cases. Retain case IDs, image paths,
+   findings and the next action so another agent can continue. Report **Changed**,
+   **Validated**, **Risks**, separating comparison, visual critique, accessibility
+   checks and owner approval. A low pixel ratio does not establish any of the last
+   three.
+
+For a new implementation or missing component mapping, use `penpair-handoff` when
+installed. For Penpot changes, use `penpair-design` when installed and retain the
+project's write protocol. Reading a skill never authorizes an extra live write.

package/skills/penpair-verify/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Penpair Verify"
+  short_description: "Compare browser UI with approved designs"
+  default_prompt: "Use $penpair-verify to compare this running frontend with its approved design, inspect the images and recheck scoped fixes."
+policy:
+  allow_implicit_invocation: true

package/skills/penpair-verify/references/browser-evidence.md

@@ -0,0 +1,33 @@
+# Real browser evidence
+
+The optional `@penpair/reflection-check` adapter connects approved design cases to
+a trusted project module exporting `async runCase(test)`. Match its version to
+the installed command/core and preserve existing adapter entries. Read the
+[adapter guide](https://github.com/niklas-westman/penpair/blob/main/docs/adapters.md#check-the-frontend-against-the-design)
+for installation and the current provider contract.
+
+The command package ships `examples/reflection-browser/`: for a web installation,
+start at `node_modules/@penpair/web/examples/reflection-browser/README.md`. The
+starter supplies browser capture and pixel comparison plumbing. Project hooks
+still own the actual route, state setup, fixture, theme observation, capture root
+and expected fonts. The standalone Reflection application is optional; a pinned
+browser dependency and working provider are still required in the project.
+
+Before claiming a comparison, retain the case ID, approved reference/hash, setup
+name, provider identity/version and actual browser observation. Check viewport,
+theme, state, fixture, loaded fonts, PNG dimensions and scale. Missing state
+hooks, placeholder routes or echoed test inputs leave verification pending.
+Inspect pointer/hover, scroll/sticky behavior, occlusion and capture-root bounds
+when they can explain a mismatch. Do not hide them by changing the reference.
+
+Use the project's existing verification command or pass its explicit mapping and
+provider to the installed `penpair reflection` command. Providers execute trusted
+project code, not sandboxed data. Preserve approved baseline bytes before and
+after running them. Browser state and screenshots must be independently observed;
+an adapter accepts an evidence contract but cannot attest that a provider is
+honest.
+
+Keep the result and screenshots in a project-owned report. Distinguish measured
+drift, a visual finding, behavior/accessibility checks and owner acceptance.
+Design-to-design state variants need a source/candidate critique, not an
+implementation parity score against intentionally different content.

package/dist/cli.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/cli.js

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-import { runCli } from "./cli-main.js";
-process.exitCode = await runCli(process.argv.slice(2));

package/dist/docker/lifecycle.d.ts

@@ -1,96 +0,0 @@
-import { type InstanceConfig } from "../instance/config.js";
-import { type Check, type DoctorCheck, type DoctorOptions } from "../instance/connection.js";
-import type { Runner } from "../instance/runner.js";
-export interface Context {
-    root: string;
-    config: InstanceConfig;
-    runner: Runner;
-    log?: (message: string) => void;
-    sleep?: (milliseconds: number) => Promise<void>;
-    fetch?: typeof fetch;
-    now?: () => Date;
-}
-/** `docker compose` arguments for this instance: its own project name, compose file and secrets. */
-export declare function composeArgs(c: Context, ...rest: string[]): string[];
-/** The frontend answers a few seconds before the backend does (502 until then); /readyz is 200 only when the backend is ready. */
-export declare const readyUrl: (config: InstanceConfig) => string;
-export declare function waitForHttp(c: Context, url: string, timeoutMs?: number, stepMs?: number): Promise<boolean>;
-export declare function up(c: Context): Promise<{
-    url: string;
-    ready: boolean;
-}>;
-/** Stops and removes the containers. Volumes are never removed: the design data stays. */
-export declare function down(c: Context): Promise<void>;
-export interface ServiceState {
-    service: string;
-    state: string;
-    health: string;
-}
-export declare function parseComposePs(output: string): ServiceState[];
-export declare function status(c: Context): Promise<{
-    services: ServiceState[];
-    frontendReachable: boolean;
-    backendReady: boolean;
-    url: string;
-}>;
-export interface Counts {
-    files: number;
-    profiles: number;
-    teams: number;
-    storageObjects: number;
-    fileRevisions: {
-        id: string;
-        name: string;
-        revn: number;
-    }[];
-}
-export interface BackupManifest {
-    instance: string;
-    penpotVersion: string;
-    createdAt: string;
-    label?: string;
-    files: {
-        db: {
-            name: string;
-            sha256: string;
-            bytes: number;
-        };
-        assets: {
-            name: string;
-            sha256: string;
-            bytes: number;
-        };
-    };
-    counts: Counts;
-    note: string;
-}
-/**
- * A backup of the whole instance: a Postgres dump and a tarball of the asset volume, with checksums and the counts
- * that `backup verify` later checks a restore against. It holds account data (password hashes): never commit it.
- */
-export declare function backup(c: Context, label?: string): Promise<{
-    directory: string;
-    manifest: BackupManifest;
-}>;
-/** Proves a backup can be restored without touching the instance: restores the dump into a throwaway Postgres and compares. */
-export declare function verifyBackup(c: Context, directory: string): Promise<{
-    ok: boolean;
-    checks: Check[];
-}>;
-export interface RestoreOptions {
-    /** Restoring replaces the instance's data; it only runs when this is true. */
-    yes: boolean;
-    /** Skip the safety backup of the current data. */
-    skipSafetyBackup?: boolean;
-}
-/**
- * Replaces the instance's database and assets with a backup. A backup of the current data is taken first unless told
- * not to, the checksums are checked before anything is touched, and the counts are compared afterwards.
- */
-export declare function restore(c: Context, directory: string, options: RestoreOptions): Promise<{
-    ok: boolean;
-    checks: Check[];
-    safetyBackup?: string;
-}>;
-/** What is up, what is not, and what to do about it. */
-export declare function doctor(c: Context, options?: DoctorOptions): Promise<DoctorCheck[]>;