@penpair/core 0.1.0 → 0.1.1

package/dist/instance/init.js

@@ -1,72 +1,32 @@
-import { createServer } from "node:net";
-import { mkdir, writeFile } from "node:fs/promises";
+import { writeFile } from "node:fs/promises";
 import path from "node:path";
-import { configFileName, instancePaths, isExternal, loadConfig, testedPenpotVersion, validateConfig, validateProjectConfig, ConfigError } from "./config.js";
-import { generateSecrets, renderEnv, writeSecretFile } from "../docker/secrets.js";
-import { renderCompose } from "../docker/template.js";
-import { ensureGitignoreEntry, ensureKeyFileIgnored } from "./gitignore.js";
-export async function isPortFree(port, host = "127.0.0.1") {
-    return new Promise((resolve) => {
-        const server = createServer();
-        server.once("error", () => resolve(false));
-        server.once("listening", () => server.close(() => resolve(true)));
-        server.listen(port, host);
-    });
-}
-export async function firstFreePort(from, avoid = [], free = isPortFree) {
-    for (let port = from; port < from + 200; port++)
-        if (!avoid.includes(port) && (await free(port)))
-            return port;
-    throw new Error(`no free port from ${from}`);
-}
-function defaultInstanceName(root) {
+import { requireLocalProfile } from "../local-profile.js";
+import { configFileName, ConfigError, isExternal, loadConfig, validateProjectConfig } from "./config.js";
+import { ensureKeyFileIgnored } from "./gitignore.js";
+/** A short, valid instance name from the folder's name; "design" when nothing usable is left. */
+export function defaultInstanceName(root) {
     const name = path.basename(path.resolve(root)).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^[^a-z]+/, "").slice(0, 31);
     return name.length > 0 ? name : "design";
 }
-const ensureGitignore = (root, entry) => ensureGitignoreEntry(root, entry, { directory: true, comment: "penpair: generated compose file, secrets and backups" });
 /**
- * Sets an instance up in a project: config (committed), then the generated compose file and secrets (in a git-ignored
- * directory). Running it again rewrites the compose file from the config; existing secrets are never replaced.
+ * Sets a project up. For Penpot on the web (`external`) it writes only the config, here. For Penpot on this computer it hands over to
+ * the local profile a package provides (`@penpair/docker`), which writes the config, the compose file and the secrets.
  */
-export async function init(root, options = {}) {
-    let config;
-    let createdConfig = false;
+export async function init(root, options = {}, deps = {}) {
+    let existing;
     try {
-        config = await loadConfig(root);
+        existing = await loadConfig(root);
     }
     catch (error) {
         if (!(error instanceof ConfigError) || !/No penpair\.config\.json/.test(error.message))
             throw error;
-        if (options.external) {
-            config = validateProjectConfig({ instance: options.instance ?? defaultInstanceName(root), profile: { type: "external", origin: options.external } });
-            await writeFile(path.join(root, configFileName), `${JSON.stringify(config, null, 2)}\n`);
-            return { config, createdConfig: true, createdSecrets: false, files: [], gitignoreAdded: options.gitignore ? await ensureKeyFileIgnored(root) : false };
-        }
-        const free = options.isFree ?? isPortFree;
-        const frontend = options.port ?? (await firstFreePort(9001, [], free));
-        const mail = options.mailPort ?? (await firstFreePort(1080, [frontend], free));
-        config = validateConfig({
-            instance: options.instance ?? defaultInstanceName(root),
-            penpotVersion: options.penpotVersion ?? testedPenpotVersion,
-            ports: { frontend, mail },
-            directory: options.directory ?? ".penpair",
-            ...(options.composeProject ? { composeProject: options.composeProject } : {}),
-        });
-        await writeFile(path.join(root, configFileName), `${JSON.stringify(config, null, 2)}\n`);
-        createdConfig = true;
     }
-    if (isExternal(config))
-        return { config, createdConfig, createdSecrets: false, files: [], gitignoreAdded: options.gitignore ? await ensureKeyFileIgnored(root) : false };
-    const paths = instancePaths(root, config);
-    await mkdir(paths.directory, { recursive: true });
-    await writeFile(paths.compose, renderCompose(config));
-    const files = [paths.compose];
-    const createdSecrets = await writeSecretFile(paths.env, renderEnv(config, generateSecrets()));
-    files.push(paths.env);
-    let gitignoreAdded = false;
-    if (options.gitignore) {
-        const directoryAdded = await ensureGitignore(root, config.directory);
-        gitignoreAdded = (await ensureKeyFileIgnored(root)) || directoryAdded;
+    if (existing && isExternal(existing))
+        return { config: existing, createdConfig: false, createdSecrets: false, files: [], gitignoreAdded: options.gitignore ? await ensureKeyFileIgnored(root) : false };
+    if (!existing && options.external) {
+        const config = validateProjectConfig({ instance: options.instance ?? defaultInstanceName(root), profile: { type: "external", origin: options.external } });
+        await writeFile(path.join(root, configFileName), `${JSON.stringify(config, null, 2)}\n`);
+        return { config, createdConfig: true, createdSecrets: false, files: [], gitignoreAdded: options.gitignore ? await ensureKeyFileIgnored(root) : false };
     }
-    return { config, createdConfig, createdSecrets, files, gitignoreAdded };
+    return requireLocalProfile(deps.local).init(root, options);
 }

package/dist/instance/setup.d.ts

@@ -1,5 +1,6 @@
 import { type ProjectConfig } from "./config.js";
 import { type ConnectIo, type ConnectResult, type WaitOptions } from "./connect.js";
+import { type LocalProfile } from "../local-profile.js";
 import type { Runner } from "./runner.js";
 export declare const hostedOrigin = "https://design.penpot.app";
 export type SetupWhere = {
@@ -23,6 +24,8 @@ export interface SetupOptions {
     /** Install the assistant's rules at the end without asking. */
     installSkills?: () => Promise<void>;
     runner: Runner;
+    /** A way to run Penpot on this computer, from a package that provides one; only used when that is chosen. */
+    local?: LocalProfile;
     log?: (message: string) => void;
 }
 export interface SetupResult {

package/dist/instance/setup.js

@@ -1,12 +1,12 @@
 import { ConfigError, isExternal, loadConfig, requireLocal } from "./config.js";
 import { connectProject, penpotAddress } from "./connect.js";
 import { init } from "./init.js";
-import { up } from "../docker/lifecycle.js";
+import { requireLocalProfile } from "../local-profile.js";
 export const hostedOrigin = "https://design.penpot.app";
-async function chooseWhere(io) {
+async function chooseWhere(io, hasLocal) {
     io.say("Where is your Penpot?");
     io.say("  1  On the web: design.penpot.app (free account) or your team's own Penpot. Nothing to install. (recommended)");
-    io.say("  2  On this computer, in Docker. Works offline; needs Docker Desktop and a 2 GB download.");
+    io.say(hasLocal ? "  2  On this computer, in Docker. Works offline; needs Docker Desktop and a 2 GB download." : "  2  On this computer, in Docker. Needs the @penpair/docker package, which this install does not include.");
     const answer = (await io.ask("Press Enter for 1, or type 2: ", "1")).trim();
     if (answer === "2")
         return { type: "docker" };
@@ -29,18 +29,17 @@ export async function setup(root, io, options) {
             throw error;
     }
     if (!config) {
-        const where = options.where ?? (await chooseWhere(io));
-        const made = await init(root, { gitignore: true, instance: options.instance, port: options.port, ...(where.type === "web" ? { external: where.origin } : {}) });
+        const where = options.where ?? (await chooseWhere(io, Boolean(options.local)));
+        const made = await init(root, { gitignore: true, instance: options.instance, port: options.port, ...(where.type === "web" ? { external: where.origin } : {}) }, { local: options.local });
         config = made.config;
         io.say(`Wrote penpair.config.json (${where.type === "web" ? `Penpot at ${where.origin}` : "Penpot on this computer"}). Commit that file; it holds no secrets.`);
     }
     if (!isExternal(config)) {
+        const local = requireLocalProfile(options.local);
+        await local.preflight(options.runner);
         const c = { root, config: requireLocal(config), runner: options.runner, log: options.log ?? (() => undefined) };
-        const docker = await options.runner.run("docker", ["version", "--format", "{{.Server.Version}}"]);
-        if (docker.code !== 0)
-            throw new ConfigError("Docker is not running. Start Docker Desktop, wait until it says it is running, then run `penpair setup` again.");
         io.say("Starting Penpot. The first time it downloads about 2 GB and can take several minutes.");
-        const started = await up(c);
+        const started = await local.up(c);
         if (!started.ready)
             throw new ConfigError(`Penpot started but ${started.url} does not answer yet. Wait a minute and run \`penpair setup\` again.`);
         io.say("Penpot is running. Create your account on its start page (no email confirmation is needed), then create a design file.");

package/dist/local-profile.d.ts

@@ -0,0 +1,95 @@
+import { type InstanceConfig } from "./instance/config.js";
+import type { InitOptions, InitResult } from "./instance/init.js";
+import type { Check, DoctorCheck, DoctorOptions } from "./instance/connection.js";
+import type { Runner } from "./instance/runner.js";
+/**
+ * Another package can add a way to run Penpot on this computer (`@penpair/docker` does). It depends on this one, never the other way
+ * round: it starts the command line with its implementation of `LocalProfile`, and this file is the whole contract. Without one, the
+ * commands that run Penpot locally say where they come from.
+ */
+/** What an action on a local instance needs to know about the project. Injectable so it can be tested without the real thing. */
+export interface LocalContext {
+    root: string;
+    config: InstanceConfig;
+    runner: Runner;
+    log?: (message: string) => void;
+    sleep?: (milliseconds: number) => Promise<void>;
+    fetch?: typeof fetch;
+    now?: () => Date;
+}
+export interface ServiceState {
+    service: string;
+    state: string;
+    health: 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;
+}
+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;
+}
+export interface LocalProfile {
+    /** Throws a plain-language ConfigError when what the instance runs on is not available (for example, Docker is not running). */
+    preflight(runner: Runner): Promise<void>;
+    /** Writes the config when missing, the compose file and the secrets (never replaced). */
+    init(root: string, options: InitOptions): Promise<InitResult>;
+    up(c: LocalContext): Promise<{
+        url: string;
+        ready: boolean;
+    }>;
+    down(c: LocalContext): Promise<void>;
+    status(c: LocalContext): Promise<{
+        services: ServiceState[];
+        frontendReachable: boolean;
+        backendReady: boolean;
+        url: string;
+    }>;
+    doctor(c: LocalContext, options?: DoctorOptions): Promise<DoctorCheck[]>;
+    backup(c: LocalContext, label?: string): Promise<{
+        directory: string;
+        manifest: BackupManifest;
+    }>;
+    verifyBackup(c: LocalContext, directory: string): Promise<{
+        ok: boolean;
+        checks: Check[];
+    }>;
+    restore(c: LocalContext, directory: string, options: RestoreOptions): Promise<{
+        ok: boolean;
+        checks: Check[];
+        safetyBackup?: string;
+    }>;
+}
+/** The commands that run Penpot on this computer exist only when a package provides a profile for them. */
+export declare const needsLocalProfile = "Running Penpot on this computer is not part of this install. It comes with `@penpair/docker`: install it with `npm i -D @penpair/docker` and run `npx penpair \u2026` (or, once, `npx @penpair/docker <command>`). Penpot on the web needs nothing extra.";
+export declare function requireLocalProfile(local: LocalProfile | undefined): LocalProfile;

package/dist/local-profile.js

@@ -0,0 +1,8 @@
+import { ConfigError } from "./instance/config.js";
+/** The commands that run Penpot on this computer exist only when a package provides a profile for them. */
+export const needsLocalProfile = "Running Penpot on this computer is not part of this install. It comes with `@penpair/docker`: install it with `npm i -D @penpair/docker` and run `npx penpair …` (or, once, `npx @penpair/docker <command>`). Penpot on the web needs nothing extra.";
+export function requireLocalProfile(local) {
+    if (!local)
+        throw new ConfigError(needsLocalProfile);
+    return local;
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** Kept in its own file so that the command line and the library entry can both read it without importing each other. Equals package.json (a test checks). */
+export declare const version = "0.1.1";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** Kept in its own file so that the command line and the library entry can both read it without importing each other. Equals package.json (a test checks). */
+export const version = "0.1.1";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@penpair/core",
-  "version": "0.1.0",
-  "description": "Design together. Build together. Connect AI agents and people to a Penpot design file, safely: setup, a safe write protocol, snippets, skills, and an optional Docker Penpot per project.",
+  "version": "0.1.1",
+  "description": "Design together. Build together. The library and engine behind penpair: connect AI agents and people to a Penpot design file, safely. Install @penpair/web or @penpair/docker for the command.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,16 +23,11 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
-    "./cli": "./dist/cli.js",
     "./package.json": "./package.json"
   },
-  "bin": {
-    "penpair": "dist/cli.js"
-  },
   "files": [
     "dist",
     "skills",
-    "docs",
     "LICENSE",
     "README.md"
   ],

package/skills/penpair-setup/SKILL.md

@@ -10,36 +10,36 @@ compatibility: Node 22 and a terminal; a Penpot account on the web, or Docker De
 
 # penpair-setup
 
-Two ways to run Penpot, one way to connect. **Web** (design.penpot.app, or a team's own Penpot) is the default: nothing to install. **Docker** puts a private Penpot on this computer: offline, own data, throwaway per project. Both end the same way: the person's personal key in `.env.local` as `PENPAIR_MCP_URL`, the Penpot file open in a visible browser tab with its plugin connected, and `penpair doctor` all `ok`.
+Two ways to run Penpot, one way to connect. **Web** (design.penpot.app, or a team's own Penpot) is the default: the package `@penpair/web`, nothing else to install. **Docker** (the package `@penpair/docker`, which includes everything in `@penpair/web`) puts a private Penpot on this computer: offline, own data, throwaway per project. Both end the same way: the person's personal key in `.env.local` as `PENPAIR_MCP_URL`, the Penpot file open in a visible browser tab with its plugin connected, and `penpair doctor` all `ok`.
 
 ## The key never passes through you
 
-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 connect`). Your shell cannot answer a hidden prompt, so hand that one step to the person with the exact words below.
+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 doctor --json` and read it: `ok`, then each check. 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 it: `ok`, then each check. Done when you can name the first failing check, or say all pass. If all pass, stop here and say so.
 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 init --external https://design.penpot.app --gitignore` (a team's own Penpot: its address instead).
-   - Docker: `npx penpair init --gitignore`, then `npx penpair up` (the first start downloads about 2 GB; Docker Desktop must be running). Done when `up` says Penpot is up.
-   - The one-command alternative for a person at a terminal is `npx penpair setup` (add `--web` or `--docker` to skip the question).
+   - Web: `npx @penpair/web init --external https://design.penpot.app --gitignore` (a team's own Penpot: its address instead).
+   - Docker: `npm i -D @penpair/docker` (the same command as `@penpair/web` with the Docker commands added; install it instead of `@penpair/web`, not beside it), then `npx penpair init --gitignore` and `npx penpair up` (the first start downloads about 2 GB; Docker Desktop must be running). Done when `up` says Penpot is up. For a person at a terminal, `npx @penpair/docker setup --docker` does it in one go.
+   - The one-command alternative for a person at a terminal is `npx @penpair/web setup` (add `--web` or `--docker` to skip the question).
 4. **Hand the browser steps to the person**, in these words, adapted to the choice:
    1. Open Penpot (the address `init` or `up` printed), log in or create an account, create a design file.
    2. Account, Integrations, MCP Server: switch it on and copy the address.
-   3. In your own terminal, in this folder, run `npx penpair connect` and paste the address (nothing is shown as you paste).
+   3. In your own terminal, in this folder, run `npx @penpair/web connect` and paste the address (nothing is shown as you paste).
    4. In the design file: File, then MCP Server, then Connect. Keep that tab in front while we work.
-5. **Verify.** Run `npx penpair doctor --json` after the person says they are done. Done when `ok` is true and the check named `editor and plugin` says it is connected. A failing check carries a `remedy`; say it in plain words and let the person act. Common ones:
+5. **Verify.** Run `npx @penpair/web doctor --json` after the person says they are done. Done when `ok` is true and the check named `editor and plugin` says it is connected. A failing check carries a `remedy`; say it in plain words and let the person act. Common ones:
 
    | Check says | Meaning and fix |
    | --- | --- |
    | docker: not answering | Docker Desktop is not running. Start it, wait until it says running. |
-   | containers / backend not ready | Run `npx penpair up`; wait ten seconds; check again. |
-   | editor and plugin: points at another instance | The key in `.env.local` belongs to a different Penpot. Run `npx penpair connect --replace` and paste this Penpot's key. |
+   | containers / backend not ready | Docker projects only: run `npx penpair up`; wait ten seconds; check again. |
+   | editor and plugin: points at another instance | The key in `.env.local` belongs to a different Penpot. Run `npx @penpair/web connect --replace` and paste this Penpot's key. |
    | 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 skills install`, add the printed rows to the project's agent guide, then fill in `.skills/penpot-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.** Run `npx @penpair/web skills install`, add the printed rows to the project's agent guide, then fill in `.skills/penpot-design/references/project-facts.md` with the person (the Penpot file, token sets, naming, who approves). Done when that file has no `<...>` placeholders left.
 
 ## Moving between web and Docker
 

package/skills/penpair-setup/references/web-or-docker.md

@@ -13,14 +13,14 @@ penpair works the same against both. The only difference is who runs Penpot. Eve
 
 | | Web (the default) | Docker on this computer |
 | --- | --- | --- |
-| Install | Nothing. An account on design.penpot.app or your team's Penpot | Docker Desktop, a 2 GB download on first start |
+| Install | Nothing extra (`@penpair/core` is the web variant). An account on design.penpot.app or your team's Penpot | `@penpair/docker` as well, Docker Desktop, a 2 GB download on first start |
 | Start | Open the Penpot address | `penpair up` (Docker must be running) |
 | Sharing with a team | An invite; Penpot's accounts decide who edits | One person's computer; others need the address and an account there |
 | Where the design lives | On the Penpot service; it survives your laptop | In Docker volumes on this computer; back them up |
 | Backup | Penpot's version history and the `.penpot` export in the File menu | `penpair backup`, `backup verify`, `restore` (proven on a scratch instance) |
 | Offline | No | Yes |
 | Data stays on your machine | No | Yes |
-| Setup command | `penpair setup --web` | `penpair setup --docker` |
+| Setup command | `npx @penpair/web setup --web` | `npm i -D @penpair/core @penpair/docker`, then `npx penpair setup --docker` |
 | Ports and containers | None | One instance per project, its own ports and volumes |
 
 Pick **web** unless you need offline work, your data on your own machine, or an instance you can throw away. Teams that run their own Penpot use the web path with their own address: `penpair init --external https://penpot.example.org`.

package/docs/compatibility.md

@@ -1,29 +0,0 @@
-# Compatibility
-
-What has been checked, where, and what differs. Update it whenever a Penpot is probed. "Not run" means not run, not that it fails.
-
-| | Local Docker, Penpot 2.18.3 | Hosted, design.penpot.app, Penpot 2.18.4 (free account) |
-| --- | --- | --- |
-| Tools offered | `execute_code`, `high_level_overview`, `penpot_api_info`, `export_shape` | the same four |
-| Request body | 90 KB accepted, 110 KB refused | the same |
-| Response size | 3 MB returned | 1 MB returned (larger not tried) |
-| Plugin API: tokens, `uploadMediaData`, `createBoard`, `openPage`, file export | present | present |
-| `currentFile.export` | fails ("No matching clause") | not tried |
-| Deep check (`probe --deep --write`): flex layout, text, token set and binding, components and swap, clone, PNG export, clean-up | all steps pass, nothing left behind (run on a fresh instance's empty file) | all steps pass, nothing left behind (run twice) |
-| `pages`, `tree`, `audit`, `tokens dump`, `export` (waits for a stable render), `archive` with `--apply`, a project snippet that writes (`run seed-demo`) | all in use | all verified on seeded sample content |
-| `doctor` (external profile) | ok | ok |
-| `init`, `up`, `doctor` for a Penpot penpair starts (a fresh instance on its own port, then the owner's account, key and plugin connection) | ok: 16 seconds to answer with the images cached; `doctor` all ok | not applicable |
-
-## Differences found
-- **A new token set starts inactive, with no themes in the file.** Seen on both the hosted Penpot and a fresh local instance. (An earlier note that local sets start active was wrong or applied to a file with themes.)
-- **A token binding is recorded after the call, not during it.** On the hosted Penpot it appeared after about half a second to a few seconds; reading it straight away shows nothing. Code that checks a binding has to wait for it.
-- **Applying the same token again removes the binding** (seen on the hosted Penpot, as in the local notes).
-- **A library component's name is split into a path and a name.** Naming the shapes "Demo / button" and creating the component gives a component whose path is "Demo" and whose name is "button"; setting the component's name to the full text afterwards makes the main shape "Demo / Demo / button". Create the component and leave its name.
-- **Exporting a small board took about 3 to 4 seconds on the hosted Penpot and about 7 seconds on the local one.** The first export after a change can be stale; `export` takes two until they match.
-- **Versions differ by one patch release** (2.18.3 local, 2.18.4 hosted). Nothing in the checks depended on it. Pin the version that was tested, and run the deep check before moving it.
-
-## Not checked
-- The hosted Penpot on a large file, with real design content and a shared library.
-- Paid plans, and whether the free plan keeps the remote MCP.
-- Two people in the same hosted file while an agent writes.
-- Penpot's own version history as a backup for an external project.

package/docs/getting-started.md

@@ -1,97 +0,0 @@
-# Getting started
-
-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.
-
-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.
-
-There are two roles. You may be both.
-
-- **The designer** works in Penpot in the browser (go to "If you are the designer").
-- **The person who sets it up** connects the AI assistant to that Penpot (go to "If you set it up").
-
-## If you are the designer
-You need a link to your team's Penpot and an account.
-
-1. Open the link and log in.
-2. Open the design file you will work on.
-3. Choose **File, MCP Server, Connect** (not tried yet). A small window may appear; leave it open.
-4. Keep this browser tab **visible** while the assistant works. If the browser puts the tab to sleep, the assistant stops and says the tab is suspended. Bring the tab to the front and it carries on.
-5. Tell the assistant which page to work on. It works on the page you have open.
-
-That is all. The assistant looks first, changes things in one go, and checks its own work; you review the result in Penpot as usual.
-
-## If you set it up
-You need: a Mac or Linux computer, **Node.js** (the current LTS version), a terminal, and an account on a Penpot (the hosted one at design.penpot.app is free to start; use your team's address if it runs its own).
-
-**The quick way:** in your project's folder run `npx penpair 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.
-
-### 1. Connect your project to that Penpot
-In the folder of your project:
-
-```
-npx 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.
-
-### 2. Make your account and a file (once)
-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 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.
-
-### 4. Check that it works
-```
-npx penpair doctor
-```
-Every line should say `ok`. If one says `FAIL`, the line under it says what to do. The usual ones:
-
-| It says | What to do |
-| --- | --- |
-| 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 |
-
-Then try: `npx penpair pages` lists the pages in the open file.
-
-If you want to know what your Penpot offers before you start, `npx 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 skills install
-```
-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/penpot-design/references/project-facts.md` (your file, never replaced): the Penpot file, the token sets, the names you use, who approves.
-
-### Every day
-Open the file in Penpot, choose **File, MCP Server, Connect**, keep the tab visible, and start working with the assistant.
-
-### Your safety net
-`up`, `down`, `status`, `backup` and `restore` belong to the Docker alternative and do not apply here. 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).
-
-## 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.
-
-## Alternative: run Penpot on your own computer
-Choose this when you want to work offline, keep the data on your machine, or have one Penpot per project that you can throw away. It needs **Docker Desktop** running in addition to Node.js. The first start downloads about 2 GB.
-
-```
-npx penpair init --gitignore
-npx penpair up
-```
-
-`init` also writes a hidden folder `.penpair/` with the Penpot settings and secret keys. When `up` says "Penpot is up at http://127.0.0.1:9001" (your port may differ; use `--port 9002` with `init` if one is taken), open that address and create an account (no email confirmation is needed). Then do steps 3 to 5 above in that Penpot. `npx penpair doctor` also checks Docker, the secrets file and the containers:
-
-| It says | What to do |
-| --- | --- |
-| docker: not answering | Start Docker Desktop and wait until it says it is running |
-| containers: not running | Run `npx penpair up` |
-| backend: not ready yet | Wait ten seconds and run `doctor` again |
-
-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))
-- One guided command (`penpair setup`) that does the steps above, waits for each browser step and says what it sees. It will ask "Penpot on the web, or on this computer?" and default to the web.
-- A short illustrated version with a screenshot of each browser step.
-- A shared Penpot for a team, so designers need no setup.

package/docs/guide.md

@@ -1,93 +0,0 @@
-# Guide (skeleton)
-
-The contract an adopting project works through. It grows with the code; each section ends in a checklist like Reflection's provider guide.
-
-## Extension points
-| Point | A project supplies | First implementations |
-| --- | --- | --- |
-| Connection profile | endpoint, Penpot version, where the token comes from | local Docker, shared self-hosted, hosted |
-| Library adapter | where tokens and components come from | Marwes |
-| Snippet registry | named plugin snippets with inputs and a size check | tree, audit, tokens, archive |
-| 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 |
-
-## Sections to write
-- Starting from an empty machine
-- Instances (written, below): one per project, ports, volumes, secrets, backup and restore
-- The write protocol
-- Writing a snippet
-- Writing a library adapter
-- What breaks when Penpot is upgraded
-
-## Instances
-One Penpot per project, configured in `penpair.config.json` (no secrets, commit it):
-
-```json
-{ "instance": "my-app", "penpotVersion": "2.18.3", "ports": { "frontend": 9002, "mail": 1081 }, "directory": ".penpair" }
-```
-
-| Command | What it does |
-| --- | --- |
-| `penpair setup [--web \| --docker]` | The guided path: where is Penpot, config, start it if it is Docker, take the key (hidden), wait for the editor, read the file, install the skills |
-| `penpair connect [--replace]` | Only the key and the wait for the editor; accepts a pipe (`pbpaste \| penpair connect`) |
-| `penpair init [--instance <name>] [--port 9002] [--gitignore]` | Writes the config if missing, the compose file, and a secrets file (owner-only) that is never replaced |
-| `penpair up` / `down` / `status` | Start (waits until the backend answers), stop (the data volumes stay), look |
-| `penpair doctor [--json]` | Docker, secrets, containers, frontend, backend, then the editor and plugin through the MCP, and that `.env.local` is kept out of git (a web project checks only the address, the editor and the key file) |
-| `penpair backup` | A Postgres dump and a tarball of the assets, with checksums and counts, in `.penpair/backups/` |
-| `penpair backup verify <dir>` | Restores the dump into a throwaway database and compares counts, revisions and asset files |
-| `penpair restore <dir> --yes` | Replaces the instance's data; a safety backup of the current data comes first; the counts are compared afterwards |
-
-Things to know:
-- Two instances never collide: the compose project is `penpair-<instance>`, so containers and volumes have their own names. `composeProject` in the config adopts an instance that was started earlier under another name.
-- Keep `.penpair/` out of git. Backups hold account data (password hashes).
-- The database password must not change while the database volume exists; the secrets file is never regenerated.
-- The frontend answers a few seconds before the backend; `up` and `doctor` look at `/readyz`.
-- `doctor` compares the MCP key's port with the instance's, because a key for another instance silently drives the wrong file.
-- Penpot's accounts come from the first registration in the browser; the MCP key is made in Account, Integrations, MCP Server and goes in `.env.local` as `PENPAIR_MCP_URL`.
-
-## Baselines for a check
-
-`penpair baselines` hands a page's design to a check that compares the implementation against images. It reads the `baselines` block of `penpair.config.json`:
-
-```json
-"baselines": {
-  "page": "Candidate",
-  "root": "tests/baselines",
-  "threshold": 0.05,
-  "frames": [
-    { "frame": "F / candidates", "id": "candidates-desktop", "route": "candidates" },
-    { "frame": "F / my work", "id": "my-work" }
-  ]
-}
-```
-
-- `frame` is the exact name of a top-level frame on the page; two frames with the same name is an error, so the reference is never ambiguous.
-- `id` names the image (`<id>.png`) and the check. `route` is the route in your app this frame is the design of; a frame without a route is exported but gets no check.
-- Without `--apply` the command only looks and reports each frame as `new`, `same`, `changed`, `unstable` (the export never settled) or `missing`. `--apply` writes new images, `penpair-baselines.json` (file, revision, sizes, hashes) and `reflection-cases.json`. A `changed` image is replaced only with `--apply --update`: that is the act of approving the new design, and the owner's call. The exit code is 2 when a design differs from its image, 1 when a frame is missing or unstable.
-
-The generated `reflection-cases.json` holds, per route, the viewports (the image's exact size) and the `visualSmoke` cases (review-only, `strict: false`). A Reflection config uses it like this; only the route's own expectations are written by hand:
-
-```ts
-import { defineReflection } from 'reflection-check';
-import cases from './tests/baselines/reflection-cases.json' with { type: 'json' };
-
-export default defineReflection({
-  project: 'my-app',
-  run: { defaultMode: 'smoke', ciMode: 'smoke' },
-  contracts: {
-    browser: {
-      enabled: true,
-      blocking: true,
-      baseUrl: 'http://127.0.0.1:5173',
-      routes: [
-        { id: 'candidates', name: 'Candidates', path: '/candidates', viewports: cases.routes.candidates.viewports, expects: [{ screenshot: 'final' }] },
-      ],
-      visualSmoke: cases.visualSmoke as never,
-    },
-  },
-});
-```
-
-`baselineRoot` in the generated cases is relative to the Reflection config's folder, so keep the two in the same project root. The same images work with any other image comparison; the Reflection cases are one output of the manifest.
-
-The percentage a comparison reports is not a verdict: a correct implementation differs from a Penpot render by about 1 to 2% on text alone, so read the diff image.

package/docs/releasing.md

@@ -1,45 +0,0 @@
-# Releasing
-
-Two packages are published from this repository, always with the same version: `@penpair/core` (the library, the command, the skills; `packages/core`) and `penpair` (the short name for the command; `packages/penpair`). The root of the repository is a private workspace and is never published.
-
-Publishing cannot be undone: a version, once published, cannot be replaced. Check first, publish once.
-
-## One time
-
-1. An npm organisation named `penpair` must exist (npmjs.com, Add organization, free for public packages). `@penpair/core` cannot be published without it.
-2. `npm whoami` must print your user name. If it answers `401`, run `npm login`.
-3. If npm asks for a one-time code, add `--otp=<code>` to each publish.
-
-## Before publishing
-
-1. Be on `main` with everything committed and pushed, and the version raised in both `packages/core/package.json` and `packages/penpair/package.json` (and `version` in `packages/core/src/index.ts`; a test fails if they differ). A change that existing users could not ignore is major, an additive change is minor, a fix is a patch. Add a section to `CHANGELOG.md`.
-2. Run every check:
-
-   ```bash
-   pnpm check            # typecheck, tests, build
-   pnpm smoke:package    # packs both packages, installs them in an empty project, runs the command and the library
-   ```
-
-3. Check what would be published: `npm pack --dry-run --ignore-scripts` in each package. The core ships `dist`, `skills`, `docs`, `LICENSE` and `README.md`; the wrapper ships `bin`, `LICENSE` and `README.md`. Nothing else. (`prepack` copies the root README and `docs/` into the core for the tarball; the copies are git-ignored.)
-
-## Publish
-
-The core first, because the wrapper depends on it at this exact version. Use `pnpm publish` so `workspace:*` is replaced by the real version.
-
-```bash
-cd packages/core && pnpm publish --access public
-cd ../penpair && pnpm publish --access public
-```
-
-## Verify
-
-```bash
-npm view @penpair/core version
-npm view penpair version
-```
-
-Then, in an empty folder, run `npx penpair --version` and `npx penpair setup --help`, so what was tested is what people get. Tag the release (`git tag v<version>`) and push the tag only if you want one.
-
-## 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 patch or minor version, never by changing a published one.