@penpair/web 0.3.1 → 0.3.3

package/README.md

@@ -1,64 +1,103 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/niklas-westman/penpair/main/docs/assets/logo.png" alt="Penpair: a pen nib between blue code brackets" width="120" height="120">
+</p>
+
 # penpair
 
-**Design together. Build together.** Connect people and agents to the same Penpot design, with pinned targets, recoverable writes and independent readback.
+**Design together. Build together.**
 
-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.
+Penpair helps people and AI coding assistants work on the same Penpot design, then carry that design into frontend code. Your assistant can inspect a real file, build a page in reviewed steps and check the result. You stay in control of what changes and what gets approved.
 
-**Design in Penpot → hand off to frontend code → check the implementation.** Add the companion adapters for the parts of that workflow your project uses:
+**Design in Penpot → build in your app → compare the result.**
 
-| 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 |
+[Install](#install) · [First task](#try-your-first-task) · [Companions](#add-your-companions) · [Contribute](#contribute) · [Documentation](#documentation)
 
-**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.
+[![M8ven Score](https://m8ven.ai/badge/mcp/niklas-westman-penpair-637i3e?v=4c3a3cf6e76f527306a6b8d2974a4cdb)](https://m8ven.ai/mcp/niklas-westman-penpair-637i3e?s=readme)
 
-## Choose your path
+## What it does
 
-| You want to… | Start here |
+Penpot holds the design. Penpair adds project configuration, reusable operations and skills: written instructions that teach your assistant how to work with that design.
+
+| From an idea to a checked page | What Penpair helps with |
 | --- | --- |
-| Set up your first project | [Getting started](docs/getting-started.md) |
-| 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) |
+| **Understand the design** | Read pages, inspect components and tokens, audit spacing and export frames. |
+| **Work on it together** | Pin the intended file, inspect before writing, take snapshots and independently read changes back. |
+| **Build the frontend** | Hand design references and component mappings to the coding assistant. |
+| **Check the implementation** | Add Reflection Check to compare approved references with real browser captures. |
 
-## Quick start
+Use your existing frontend stack. Library-specific knowledge lives in optional adapters; the core stays independent of any component library.
 
-Use Node 22 or newer, your project folder and a visible Penpot editor. Enter the personal MCP address only in the private connection prompt.
+## Install
 
-```sh
-pnpm add -D @penpair/web
-pnpm exec penpair init --external https://design.penpot.app --gitignore
-pnpm exec penpair connect
-pnpm exec penpair connect --pin-file
-pnpm exec penpair doctor --json
-pnpm exec penpair skills install --dry-run
+Choose how you want to get started. Both routes set up the same project and agent skills.
+
+| Route | Best for | Start here |
+| --- | --- | --- |
+| **Set it up with your assistant — recommended** | You want guidance, help with browser steps and checks along the way. | [Guided installation](https://github.com/niklas-westman/penpair/blob/main/docs/installation.md#recommended-set-it-up-with-your-assistant) |
+| **Install it yourself** | You prefer to run each command and review the configuration yourself. | [Manual installation](https://github.com/niklas-westman/penpair/blob/main/docs/getting-started.md) |
+
+For the recommended route, open your application's project in your coding assistant and paste:
+
+```text
+Read https://raw.githubusercontent.com/niklas-westman/penpair/main/packages/core/skills/penpair-setup/SKILL.md
+and follow its recommended assisted route to set up Penpair in this project.
+Keep my MCP key out of chat and check with me before changing a design file.
 ```
 
-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).
+You need **Node.js 22 or newer**, a project folder and a Penpot account. Your assistant helps check the prerequisites; you handle your personal key and browser. No clone of this repository is needed. Prefer a terminal wizard? The [installation guide](https://github.com/niklas-westman/penpair/blob/main/docs/installation.md#prefer-a-terminal-wizard) covers that too.
 
-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.
+## Try your first task
 
-## Packages and workflows
+Start with a read-only request to your assistant:
 
-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.
+> Read the installed penpair-design skill. Inspect the pinned design file, summarize its pages and tokens, and suggest one small improvement. Do not change the file yet.
 
-| 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) | 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 |
+Then choose a scratch page and agree on a small design task. The workflow is: inspect, snapshot, write once, independently read back, export and look at the result. The [design workflow](https://github.com/niklas-westman/penpair/blob/main/docs/design-workflow.md) explains the review points and recovery steps.
+
+The installed skills cover **setup → design → recipes → handoff → verification**, with `design-judgment` for visual hierarchy. Ask the assistant to name the skill it uses. For frontend work, `penpair-handoff` carries design evidence into implementation; `penpair-verify` guides browser comparison, image review, fixes and recapture. [Check skill discovery and behavior](https://github.com/niklas-westman/penpair/blob/main/docs/skill-validation.md).
+
+## Add your companions
+
+| Package | Add it when | What it contributes |
+| --- | --- | --- |
+| **`@penpair/marwes-ui`** | Your application uses Marwes UI | Bring library and project tokens into Penpot, detect drift and compose library-aware recipes. |
+| **`@penpair/reflection-check`** | You build a frontend from the design | Map approved design cases to real browser captures and comparison evidence. **Recommended for design-to-code work.** |
 
-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.
+Install companions at the **same version** as your command package, then register them in `penpair.config.json`. Both can work together; Reflection Check can also be used without Marwes. Follow [installation and registration](https://github.com/niklas-westman/penpair/blob/main/docs/adapters.md).
 
-[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)
+**Penpair manages the design workflow. Marwes connects the component library. Reflection Check connects implementation evidence.** The comparison adapter does not bundle a browser or a Reflection engine: your project supplies a browser/checker provider. Start with the [real-browser example](https://github.com/niklas-westman/penpair/blob/main/examples/reflection-browser/README.md). Installing the adapter alone does not complete verification, and a passing comparison does not replace visual review or human approval.
 
-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.
+## Know the boundaries
+
+- Penpair uses Penpot's MCP and plugin APIs. The editor must stay open and visible; this is an interactive workflow.
+- A healthy connection does not authorize design changes. Review the target and intended work before writing.
+- Keep backups and prove a restore on scratch before relying on them. See [backup and restore](https://github.com/niklas-westman/penpair/blob/main/docs/backup.md).
+- Penpair is early software. Check [compatibility](https://github.com/niklas-westman/penpair/blob/main/docs/compatibility.md) for tested environments and remaining gaps. The installed command's `--help` is the reference for its available options.
+
+Use the scoped command packages above. The unscoped `penpair` wrapper currently has a publishing exception. `@penpair/core` is the underlying library and ships transitively; it has no command of its own.
+
+## Contribute
+
+Found a rough edge? [Open an issue](https://github.com/niklas-westman/penpair/issues) with what you tried, what you expected, your versions and a redacted reproduction. Documentation fixes, reproducible bug reports and focused pull requests are welcome. Report vulnerabilities through [SECURITY](https://github.com/niklas-westman/penpair/blob/main/SECURITY.md).
+
+To develop Penpair itself, fork and clone this repository, then:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm check
+```
+
+Use the pnpm version declared in `package.json`. Read [CONTRIBUTING](https://github.com/niklas-westman/penpair/blob/main/CONTRIBUTING.md) for choosing a package, conventions, release notes and package smoke checks. A live Penpot connection is not required for the standard automated checks.
+
+## Documentation
+
+| You want to… | Read |
+| --- | --- |
+| Set up by hand or join a team | [Choose an installation route](https://github.com/niklas-westman/penpair/blob/main/docs/installation.md) · [Team setup](https://github.com/niklas-westman/penpair/blob/main/docs/team.md) |
+| Work on a design and build from it | [Design workflow](https://github.com/niklas-westman/penpair/blob/main/docs/design-workflow.md) · [Handoff](https://github.com/niklas-westman/penpair/blob/main/docs/handoff.md) |
+| Connect a library or browser checker | [Companion adapters](https://github.com/niklas-westman/penpair/blob/main/docs/adapters.md) |
+| Find commands, recipes or extension points | [Guide](https://github.com/niklas-westman/penpair/blob/main/docs/guide.md) · [Cookbook](https://github.com/niklas-westman/penpair/blob/main/docs/cookbook.md) · [MCP tools](https://github.com/niklas-westman/penpair/blob/main/docs/mcp.md) |
+| Diagnose or recover a failure | [Troubleshooting](https://github.com/niklas-westman/penpair/blob/main/docs/troubleshooting.md) · [Recovery](https://github.com/niklas-westman/penpair/blob/main/docs/recovery.md) |
+| Validate a source build or prepare a release | [Validation](https://github.com/niklas-westman/penpair/blob/main/docs/validation.md) · [Releasing](https://github.com/niklas-westman/penpair/blob/main/docs/releasing.md) |
+
+[Changelog](https://github.com/niklas-westman/penpair/blob/main/CHANGELOG.md) · [MIT licence](https://github.com/niklas-westman/penpair/blob/main/LICENSE)

package/docs/backup.md

@@ -49,6 +49,11 @@ Set `restoreVerified` to true only after the owner completes the scratch compari
 
 ## Current verification limits
 
-The bounded exporter, target/revision guards, refusal to overwrite, error/budget handling and reminder behavior are tested with fake clients and local files. The first live archive export/import round trip on hosted Penpot 2.18.4 remains outstanding. Structural snapshots (D3) will provide review evidence and remain distinct from archives. G3 stays open until its required live restore evidence is recorded.
+The bounded exporter, target/revision guards, refusal to overwrite, error/budget
+handling and reminder behavior are tested with fake clients and local files.
+Those checks do not establish archive restoration on a live hosted instance;
+record the required export/import and visual comparison before relying on that
+recovery path. Structural snapshots provide review evidence and remain distinct
+from archives.
 
 [Structural snapshots and diffs](snapshots.md) provide bounded review evidence alongside archives; they cannot replace an export/import restore trial.

package/docs/conventions/README.md

@@ -4,9 +4,6 @@ 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) |
@@ -49,7 +46,8 @@ Penpair with their designs.
 
 - Generated `dist/`, dependencies, ignored local artifacts and data fixtures are
   outside formatting. Keep captured evidence unchanged.
-- `docs/trials/` and `docs/upstream/` preserve external evidence.
+- Internal completion reports, trial evidence and upstream drafts belong in
+  git-ignored `.working-docs/`; maintained guides must work without those files.
 - 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.

package/docs/design-workflow.md

@@ -8,6 +8,9 @@
 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. 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.
+[Structural snapshots](snapshots.md) make design review diffable. [Archives and
+restore trials](backup.md) establish recovery independently. Use the
+[validation guide](validation.md) for source-package and scratch checks; automated
+fixtures do not establish live behavior or human acceptance.
 
 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).

package/docs/getting-started.md

@@ -1,8 +1,8 @@
-# Getting started
+# Manual installation
 
-Draft. Written for someone who has not used a terminal much. The steps marked **(not tried yet)** come from Penpot's help pages, not from a run; the first person to follow this guide on a clean machine should mark what differs.
+Run each step yourself, at your own pace. Prefer your assistant to guide you? [Choose the recommended route](installation.md#recommended-set-it-up-with-your-assistant). Both routes produce the same setup.
 
-**Easiest:** let your AI assistant (Claude Code, Codex or GitHub Copilot) walk you through it with the [setup guide skill](https://github.com/niklas-westman/penpair/blob/main/skills/penpair-setup-guide/SKILL.md). This page is the same path by hand.
+Browser menu labels below marked **(not tried yet)** still need a fresh live check; use [compatibility](compatibility.md) for the recorded environment checks.
 
 The normal way is to use Penpot on the web (or your team's own Penpot) and connect the AI assistant to it. Nothing runs on your computer except penpair. If you want your own copy of Penpot on your computer instead, see "Alternative: run Penpot on your own computer" at the end.
 
@@ -25,13 +25,23 @@ That is all. The assistant looks first, changes things in one go, and checks its
 ## If you set it up
 You need: a Mac or Linux computer, **Node.js** (22 or newer), a terminal, and an account on a Penpot (use design.penpot.app or your team's own address).
 
-**The quick way:** in your project's folder run `npx @penpair/web setup`. It asks where your Penpot is (press Enter for the web), does steps 1 to 5 below, and says in plain words what it is waiting for. Run it again if you stop halfway. The rest of this section is what it does, one step at a time, for when you want to do it by hand or something needs fixing.
+### 0. Install the command package
+
+In your application's folder (not a clone of Penpair):
+
+```sh
+pnpm add -D @penpair/web
+```
+
+Using npm? Run `npm install --save-dev @penpair/web`, then use `npx penpair` in place of `pnpm exec penpair` below. In a pnpm workspace, add `-w` when installing at its root. Start with a `package.json`; in an empty trial folder, create one with `npm init -y` first.
+
+For Docker, install `@penpair/docker` instead and follow the [local Penpot steps](#alternative-run-penpot-on-your-own-computer). Install only one command package.
 
 ### 1. Connect your project to that Penpot
 In the folder of your project:
 
 ```
-npx @penpair/web init --external https://design.penpot.app --gitignore
+pnpm exec penpair init --external https://design.penpot.app --gitignore
 ```
 
 `init` writes a small settings file (`penpair.config.json`, commit it) and keeps your private files out of git for you.
@@ -40,15 +50,17 @@ npx @penpair/web init --external https://design.penpot.app --gitignore
 Open the Penpot address, create an account and log in. Create a project and a design file for this work.
 
 ### 3. Connect the assistant (once)
-1. In Penpot open **Account, Integrations, MCP Server** and switch it on (not tried yet). Copy the address it shows; it contains your personal key, so treat it like a password. The key belongs to you, not to the team; each person who uses the assistant makes their own.
-2. In your project folder run `npx @penpair/web connect` and paste the address when asked. Nothing is shown as you paste. It saves the address in `.env.local` (readable only by you, and added to `.gitignore`) and refuses an address that belongs to a different Penpot. (By hand instead: put the line `PENPAIR_MCP_URL=<the address>` in `.env.local` and keep that file out of git.)
-3. Open your design file in Penpot, choose **File, MCP Server, Connect**, and keep that tab visible.
 
-After connecting, run `npx @penpair/web connect --pin-file` and check the displayed file name and ID. This records the intended file in `penpair.config.json`; commit it for teammates. A different open file now blocks writes and file-specific exports. Basic reads warn. If doctor reports a file mismatch, open the expected file and reconnect its plugin.
+1. In Penpot open **Account, Integrations, MCP Server** and switch it on (not tried yet). Copy the address it shows; it contains your personal key, so treat it like a password. Each teammate uses their own key.
+2. Open the intended design file, choose **File, MCP Server, Connect**, and keep that tab visible.
+3. In your project's terminal run `pnpm exec penpair connect` and paste the address into the hidden prompt. It saves the address in private, git-ignored `.env.local` and refuses an address for a different Penpot. Never paste the address into chat. [Private file and Keychain references](credentials.md) are also supported.
+4. When asked to pin the file, check its displayed name and ID before accepting. If you skipped the prompt, verify the correct file is open before running `pnpm exec penpair connect --pin-file`; that flag accepts the pin without another confirmation.
+
+The pin is saved in `penpair.config.json`; commit it for teammates. A different open file blocks writes and file-specific exports. Basic reads warn. If doctor reports a mismatch, open the expected file and reconnect its plugin.
 
 ### 4. Check that it works
 ```
-npx @penpair/web doctor
+pnpm exec penpair doctor
 ```
 Every line should say `ok`. If one says `FAIL`, the line under it says what to do. The usual ones:
 
@@ -56,17 +68,29 @@ Every line should say `ok`. If one says `FAIL`, the line under it says what to d
 | --- | --- |
 | penpot: not answering | Check the address in the config and your internet connection |
 | editor and plugin: the MCP address points at another instance | The address in `.env.local` belongs to a different Penpot. Copy the one from this Penpot |
-| editor and plugin: not connected | Do step 3.3 again and keep the tab visible |
+| editor and plugin: not connected | Reconnect the plugin in step 3.2 and keep the tab visible |
 
-Then try: `npx @penpair/web pages` lists the pages in the open file.
+Then try: `pnpm exec penpair pages` lists the pages in the open file.
 
-If you want to know what your Penpot offers before you start, `npx @penpair/web probe` lists its tools and limits. If `execute_code` is missing from that list, penpair cannot work with it. The hosted service, checked 2026-10-20 on Penpot 2.18.4, offers the same four tools and the same limits as a local Penpot (see `compatibility.md`).
+If you want to know what your Penpot offers before you start, `pnpm exec penpair probe` lists its tools and limits. If `execute_code` is missing from that list, penpair cannot work with it. The hosted service, checked 2026-10-20 on Penpot 2.18.4, offers the same four tools and the same limits as a local Penpot (see `compatibility.md`).
 
 ### 5. Give the assistant its rules (once)
 ```
-npx @penpair/web skills install
+pnpm exec penpair skills install --agents AGENTS.md --dry-run
+pnpm exec penpair skills install --agents AGENTS.md
+pnpm exec penpair skills check --agents AGENTS.md --json
 ```
-This copies the rules the assistant follows (how to work safely in Penpot, and how to judge a screen) into `.skills/` and makes them visible to Codex and Claude Code. It prints a line for each to add to your `AGENTS.md`. Then fill in `.skills/penpair-design/references/project-facts.md` (your file, never replaced): the Penpot file, the token sets, the names you use, who approves.
+Review the preview before applying it. This copies the rules the assistant follows into the project's skill folder, creates discovery links and adds task routing to `AGENTS.md`. Use `CLAUDE.md` instead if that is your instruction file. Existing project text outside the owned section is preserved. The final command checks discovery and routing; observe actual skill use separately.
+
+Then fill in `penpair-design/references/project-facts.md` in the skill folder printed by the installer (your file, never replaced): the Penpot file, the token sets, the names you use, who approves. See [skill installation](skill-installation.md) for destination choices and existing setups.
+
+### 6. Finish and choose companions
+
+Commit your dependency and lockfile, `penpair.config.json`, Git ignore rules and reviewed skill/instruction files. Keep `.env.local` and private connection files out of Git.
+
+Choose [companion adapters](adapters.md): add Marwes UI when your app uses it, and the recommended Reflection Check adapter for frontend comparison. Keep versions aligned. Installation and registration do not replace approved references or a real browser provider.
+
+You are connection-ready when `doctor` is healthy, `pages` names the intended file and skill discovery checks pass. Observe actual skill use in your assistant separately; comparison readiness is a further step. Try the [read-only first task](../README.md#try-your-first-task).
 
 ### Every day
 Before moving into frontend implementation, choose the [companion adapters](adapters.md): use the library adapter for library-aware tokens/recipes and the recommended Reflection Check adapter for comparing the running frontend with approved designs. Installation and registration are the first steps; browser setup/provider evidence is a separate readiness stage.
@@ -76,7 +100,7 @@ Open the file in Penpot, choose **File, MCP Server, Connect**, keep the tab visi
 ### Your safety net
 See the [hosted backup and scratch-restore guide](backup.md). `penpair backup file <new.penpot>` can try a bounded file export; it never replaces an existing archive and does not claim restore proof. Larger/failing exports use the manual UI route. Optional backup-note reminders are disabled unless configured.
 
-`up`, `down`, Docker `status`, instance `backup` and instance `restore` belong to the Docker alternative; `backup file` is the separate hosted-file export candidate described above. Your safety net is Penpot's own version history and the `.penpot` export in the File menu. Whether a `.penpot` export restores everything (components, token sets, themes) is not proven yet; see the [plan](https://github.com/niklas-westman/penpair/blob/main/PLAN.md).
+`up`, `down`, Docker `status`, instance `backup` and instance `restore` belong to the Docker alternative; `backup file` is the separate hosted-file export candidate described above. Your safety net is Penpot's own version history and the `.penpot` export in the File menu. Whether an archive restores all required components, token sets and themes must be established with the [scratch restore checklist](backup.md#prove-the-restore-on-scratch).
 
 ## What it will not do
 It needs the Penpot tab open and visible while the assistant works, so it cannot run on its own overnight. It changes one Penpot at a time and only the page you have open.
@@ -102,10 +126,6 @@ npx penpair up
 
 Every day: `npx penpair up` (if Docker was restarted) and `npx penpair down` to stop; your designs stay. Back up before big changes with `npx penpair backup`, and prove a backup works with `npx penpair backup verify <the folder it printed>`. The backup contains account data, so never put it in git.
 
-## Still to make easier (see the [plan](https://github.com/niklas-westman/penpair/blob/main/PLAN.md))
-- A short illustrated version with a screenshot of each browser step.
-- A shared Penpot for a team, so designers need no setup.
-
 ## Rotate or move a personal key
 
 Follow [private credential storage and rotation](credentials.md). Use the provider UI and a private file/Keychain update, or the legacy hidden `connect --replace` prompt. Reconnect the intended editor and confirm the public file pin with doctor. The assistant should never receive either key value.

package/docs/guide.md

@@ -1,15 +1,18 @@
 # Guide
 
-Choose a workflow below, starting with [companion adapters](adapters.md) when connecting a component library or verifying frontend code. Use the [review guide](branch-review.md) for the original improvement delivery; live checks are identified separately.
+Choose a workflow below, starting with [companion adapters](adapters.md) when
+connecting a component library or verifying frontend code. The
+[validation guide](validation.md) distinguishes automated, scratch and actual
+consumer evidence.
 
 ## Documentation map
 
 | Path | Documents |
 | --- | --- |
-| First run / shared file | [Getting started](getting-started.md), [team](team.md), [trial runbook](trials.md) |
+| First run / shared file | [Choose an installation route](installation.md), [manual installation](getting-started.md), [team](team.md), [validation](validation.md) |
 | Build / handoff | [Cookbook](cookbook.md), [workflow](design-workflow.md), [kit](build-kit.md), [file scripts](run-file.md), [handoff](handoff.md) |
 | Evidence | [Inspection](inspection.md), [advisory audits](audits.md), [snapshots](snapshots.md), [approvals](approvals.md), [coverage](coverage.md), [artifacts](artifacts.md) |
-| Integration | [Companion adapters](adapters.md), [MCP](mcp.md), [formats](formats.md), [extension trust](extensions-trust.md), [credentials](credentials.md), [token adapter](marwes.md), [upstream draft](upstream/marwes-requests.md) |
+| Integration | [Companion adapters](adapters.md), [MCP](mcp.md), [formats](formats.md), [extension trust](extensions-trust.md), [credentials](credentials.md), [token adapter](marwes.md) |
 | Repair / operations | [Status/open](status.md), [troubleshooting](troubleshooting.md), [recovery](recovery.md), [backup](backup.md), [compatibility](compatibility.md), [releasing](releasing.md) |
 
 ## Extension points
@@ -21,11 +24,12 @@ Choose a workflow below, starting with [companion adapters](adapters.md) when co
 | Verification provider | what "matches the design" means | `penpair baselines` (images and Reflection cases, below), a page-verify gate |
 | Skill pack | rules the agent follows | the Penpot skill, design judgment |
 
-## Live documentation checks still pending
+## Verification limits
 
-- Follow the first-run guide on a clean machine with real participants.
-- Capture owner-reviewed screenshots of actual browser steps and a hosted large-file run.
-- Record the [human trial findings](trials.md) rather than treating offline fixtures as usability evidence.
+Offline fixtures do not establish first-run usability, hosted large-file behavior
+or multi-person coordination. Validate those in the actual target environment and
+retain observed results separately from unknowns; see [validation](validation.md)
+and the [compatibility matrix](compatibility.md).
 
 ## Configuration checks and standalone inspection
 

package/docs/installation.md

@@ -0,0 +1,67 @@
+# Choose your installation route
+
+Two ways to get the same Penpair setup. Choose who drives the steps; you can switch routes without starting over.
+
+| Route | Who does what | Choose it when |
+| --- | --- | --- |
+| **Set it up with your assistant — recommended** | Your assistant checks the project, explains and runs permitted commands, then verifies progress. You handle the browser, private key and approvals. | You want help getting connected and choosing companions. |
+| **Install it yourself** | You run each command, connect Penpot and review the installed instructions. Your assistant can help explain an individual step. | You want direct control over every setup step. |
+
+## Recommended: set it up with your assistant
+
+Open the project that will use Penpair in your coding assistant. Paste:
+
+```text
+Read https://raw.githubusercontent.com/niklas-westman/penpair/main/packages/core/skills/penpair-setup/SKILL.md
+and follow its recommended assisted route to set up Penpair in this project.
+Keep my MCP key out of chat and check with me before changing a design file.
+```
+
+The [setup skill](https://github.com/niklas-westman/penpair/blob/main/packages/core/skills/penpair-setup/SKILL.md) works before Penpair is installed. If your assistant cannot open the URL, give it that file's contents, or use the manual route. Linking a skill asks the assistant to read it; it does not install it globally.
+
+Your assistant will:
+
+1. Check Node.js 22+, your project folder and package manager. Help create a small trial project if needed.
+2. Recommend web Penpot, or use Docker when you choose it.
+3. Install one command package and preserve any existing project setup.
+4. Walk you through connecting the visible editor and entering your key privately.
+5. Confirm the intended file pin, run connection checks and preview/install the agent skills.
+6. Recommend Marwes UI if your app uses it and Reflection Check for frontend verification, with missing integration work stated clearly.
+
+You still operate the browser and paste the key into your own hidden terminal prompt. A healthy setup does not authorize design changes. A first design trial is optional and needs an agreed scratch target.
+
+## Install it yourself
+
+Follow [manual installation](getting-started.md). It includes dependency installation, configuration, browser connection, file pinning, diagnostics, agent instructions and companion choices.
+
+Tell your assistant “manual installation; give me the steps, do not run them” if you want help without handing over execution. It should explain the current step and wait for your result. You can switch to assisted setup later; it should inspect progress and continue rather than initialize everything again.
+
+## Prefer a terminal wizard?
+
+This is another way to drive setup yourself. In your project folder, after creating a `package.json` if needed:
+
+```sh
+pnpm add -D @penpair/web
+pnpm exec penpair setup --web --agents AGENTS.md
+pnpm exec penpair doctor
+pnpm exec penpair pages
+pnpm exec penpair skills check --agents AGENTS.md --json
+```
+
+Use your team's Penpot with `setup --web --external https://your-penpot.example --agents AGENTS.md`. For npm, install with `npm install --save-dev @penpair/web` and use `npx penpair`. At a pnpm workspace root, add `-w` to the install. Select `CLAUDE.md` instead if that is your instruction file. The wizard installs skills; use the manual route when you want a dry-run preview before applying those files.
+
+Review the displayed file name and ID when the wizard offers to pin it. If you skip pinning, verify the open file before `pnpm exec penpair connect --pin-file`; that flag accepts without another prompt. Fill in the installed `penpair-design/references/project-facts.md` and choose [companions](adapters.md) afterward. The wizard does not complete browser comparison integration.
+
+For local Penpot, install `@penpair/docker` **instead of** `@penpair/web` and use `setup --docker --agents AGENTS.md`. Docker Desktop must be running. Web/Docker is a hosting choice, independent of assisted/manual installation.
+
+## Same finish line
+
+Whichever route you choose, check:
+
+- `doctor` reports a healthy connection and intended file pin.
+- `pages` lists the intended file's pages.
+- Skills and routing are installed in the chosen instruction file, with project facts filled in or missing facts recorded.
+- Personal credentials remain private; teammates each connect with their own key.
+- Companion installation is recorded separately from approved references, browser-provider setup and completed visual checks.
+
+See [skill installation](skill-installation.md), [troubleshooting](troubleshooting.md) and the [first task](../README.md#try-your-first-task) for what comes next.

package/docs/marwes-components.md

@@ -1,6 +1,6 @@
 # Measured component pilot
 
-`penpair marwes components snapshot [--write]`, `check [--measure]` and `diff` compare Button, Card and StatTile in explicit light/dark contexts. This is a pilot, not a generated native library. `build` refuses until a live pinned-API experiment proves text/style instance overrides survive updates. I12 adoption and C1 live acceptance remain pending at the owner's request.
+`penpair marwes components snapshot [--write]`, `check [--measure]` and `diff` compare Button, Card and StatTile in explicit light/dark contexts. This is a pilot, not a generated native library. `build` refuses until a live pinned-API experiment proves text/style instance overrides survive updates. Measurement snapshots alone do not establish that native behavior.
 
 The adopting project owns a stable fixture rendering its installed components with its actual theme, state and fonts. Use explicit selectors and named `data-pilot-part` anatomy nodes. React component names are not inferred from the DOM. Start with six cases (three components, two modes) and add actual states as needed, up to 60. Add this adapter-owned block under `marwes`:
 

package/docs/releasing.md

@@ -174,8 +174,8 @@ 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.
+release. Retain the reviewed cleanup rationale and unchanged-version checks with
+the release's own evidence; never relax the existing release guards.
 
 ## A package npm will not accept yet
 
@@ -205,7 +205,11 @@ 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.
+Record registry versions, provenance and any explicit publishing exception in
+the release evidence. Keep temporary release/recovery notes in `.working-docs/`
+and lasting operational guidance in this document. 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
 

package/docs/skill-installation.md

@@ -1,5 +1,35 @@
 # Install skills and integrate project instructions
 
+## One skill pack, three hosts
+
+There is one canonical installation skill, **penpair-setup**, for first setup,
+assisted/manual routes and connection repair. The old `penpair-setup-guide` URL is
+only a redirect. The other five skills own design operations, recipes, judgment,
+frontend handoff and frontend verification; install does not create host-specific
+versions of their instructions.
+
+The installer stores one physical copy, normally in `.skills`, and creates
+relative discovery links. It reuses an existing real skill folder, including
+`.github/skills`, instead of creating a second copy.
+
+| Host | Discovery path used by Penpair | Explicit use when available |
+| --- | --- | --- |
+| Codex | `.agents/skills/<name>/SKILL.md` | Mention `$penpair-setup` or select the skill in the host. |
+| Claude Code | `.claude/skills/<name>/SKILL.md` | `/penpair-setup` |
+| GitHub Copilot | `.agents/skills/<name>/SKILL.md`; Copilot also supports `.claude/skills` and `.github/skills` | Ask it to read the installed skill by name/path. |
+
+All six entrypoints use shared `name`/`description` YAML metadata, task-specific
+triggers and ordinary Markdown. Codex's optional `agents/openai.yaml` adds UI
+metadata; it is not required by Claude or Copilot. Host selection still depends
+on the request, host version/settings and available tools.
+
+Choose an instruction destination the host actually loads. The examples below
+use `AGENTS.md`. For Claude, use `--agents CLAUDE.md`, or maintain an explicit
+reference from the project's existing Claude instructions to shared guidance.
+Copilot projects can select `--agents .github/copilot-instructions.md` for native
+repository instructions. Running install for a second instruction file reuses
+the same skills; it does not make another pack.
+
 ```sh
 penpair skills install --agents AGENTS.md --dry-run
 penpair skills install --agents AGENTS.md
@@ -17,8 +47,18 @@ selected skills when `--only` is used. Installation does not guarantee that a
 particular model will select or correctly apply a skill, and selecting a skill
 grants no additional write permission.
 
-Run `penpair skills check --json` for read-only Codex discovery/routing diagnostics
-after a reviewed installation. Use repeated `--only NAME` for a partial install
+Run host-specific read-only discovery/routing diagnostics after a reviewed installation:
+
+```sh
+penpair skills check --agent codex --agents AGENTS.md --json
+penpair skills check --agent claude --agents CLAUDE.md --json
+penpair skills check --agent copilot --agents .github/copilot-instructions.md --json
+```
+
+Check only hosts/instruction files you have configured. Without `--agent`, Codex
+remains the default. Claude defaults to `CLAUDE.md`; Codex and Copilot default to
+`AGENTS.md` when `--agents` is omitted. These checks verify files and routes, not
+whether the host loaded them. Use repeated `--only NAME` for a partial install
 and `--agents PATH` for its selected instruction destination. See
 [skill validation](skill-validation.md) for results, limits and realistic model
 invocation trials. Filesystem readiness does not prove correct agent behavior.
@@ -35,3 +75,19 @@ an update does not appear. See [official skill documentation](https://developers
 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.
+
+
+## Refresh an old setup without duplicates
+
+Preview `penpair skills install --agents <your-instruction-file> --dry-run --json`.
+Review `kept` files and `legacy` folders, migrate needed custom guidance into the
+canonical skill or project instructions, then remove obsolete folders/links only
+after that review. The installer reports old `penpair-setup-guide` copies in all
+supported project folders and never deletes them. `skills check` stays incomplete
+while those old setup folders remain. Project facts remain protected even with
+`--force`; avoid force when you have not reviewed the kept changes.
+
+See the official [Codex](https://developers.openai.com/codex/skills/),
+[Claude Code](https://code.claude.com/docs/en/skills) and
+[Copilot](https://docs.github.com/en/copilot/concepts/customizations/agent-skills)
+documentation for host discovery and invocation details.