@penpair/core 0.1.0 → 0.1.2

package/dist/instance/config.js

@@ -39,6 +39,8 @@ export function validateConfig(value) {
     }
     if (v.baselines !== undefined)
         validateBaselines(v.baselines, fail);
+    if (v.adapters !== undefined && !(Array.isArray(v.adapters) && v.adapters.every((e) => typeof e === "string" && e.length > 0)))
+        fail("adapters must be a list of package names or relative paths");
     return v;
 }
 const instanceNamePattern = /^[a-z][a-z0-9-]{0,30}$/;
@@ -67,6 +69,8 @@ export function validateProjectConfig(value) {
         fail("snippets must be a list of relative paths that stay inside the project");
     if (v.baselines !== undefined)
         validateBaselines(v.baselines, fail);
+    if (v.adapters !== undefined && !(Array.isArray(v.adapters) && v.adapters.every((e) => typeof e === "string" && e.length > 0)))
+        fail("adapters must be a list of package names or relative paths");
     return v;
 }
 /** The config of a project that runs its own Penpot; anything else cannot start, stop or back up containers. */

package/dist/instance/init.d.ts

@@ -1,6 +1,5 @@
+import { type LocalProfile } from "../local-profile.js";
 import { type ProjectConfig } from "./config.js";
-export declare function isPortFree(port: number, host?: string): Promise<boolean>;
-export declare function firstFreePort(from: number, avoid?: number[], free?: (port: number) => Promise<boolean>): Promise<number>;
 export interface InitOptions {
     instance?: string;
     port?: number;
@@ -10,7 +9,7 @@ export interface InitOptions {
     composeProject?: string;
     /** Use a Penpot someone else runs (a team server or the hosted service) instead of starting one: its origin, such as https://design.penpot.app. */
     external?: string;
-    /** Add the instance directory to .gitignore. */
+    /** Add the instance directory and the key file to .gitignore. */
     gitignore?: boolean;
     isFree?: (port: number) => Promise<boolean>;
 }
@@ -21,8 +20,12 @@ export interface InitResult {
     files: string[];
     gitignoreAdded: boolean;
 }
+/** A short, valid instance name from the folder's name; "design" when nothing usable is left. */
+export declare function defaultInstanceName(root: string): string;
 /**
- * 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 declare function init(root: string, options?: InitOptions): Promise<InitResult>;
+export declare function init(root: string, options?: InitOptions, deps?: {
+    local?: LocalProfile;
+}): Promise<InitResult>;

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.");
@@ -52,6 +51,6 @@ export async function setup(root, io, options) {
     io.say("Everything answers. Last: the rules your assistant follows.");
     if (options.installSkills)
         await options.installSkills();
-    io.say("Done. Try `penpair pages`, or tell your assistant to read the penpot-design skill and start.");
+    io.say("Done. Try `penpair pages`, or tell your assistant to read the penpair-design skill and start.");
     return { config, connect };
 }

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/skills.d.ts

@@ -20,6 +20,8 @@ export interface InstallOptions {
     /** For tests. */
     source?: string;
 }
+/** Skills that changed name. Installing the new one leaves the old folder behind, which `installSkills` then reports. */
+export declare const renamedSkills: Record<string, string>;
 export interface InstallReport {
     installed: string[];
     unchanged: string[];
@@ -28,5 +30,11 @@ export interface InstallReport {
     linked: string[];
     /** One line per skill for the project's AGENTS.md. */
     agentsRows: string[];
+    /** Folders of skills that were renamed and are still in the project, and whether their project-facts file was carried over. */
+    legacy: {
+        folder: string;
+        renamedTo: string;
+        carriedFacts: boolean;
+    }[];
 }
 export declare function installSkills(options: InstallOptions): Promise<InstallReport>;

package/dist/skills.js

@@ -44,6 +44,8 @@ export async function describeSkill(skillDirectory) {
     const description = /^description:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "";
     return { name, summary: description.split(/(?<=\.)\s/)[0] ?? description };
 }
+/** Skills that changed name. Installing the new one leaves the old folder behind, which `installSkills` then reports. */
+export const renamedSkills = { "penpot-design": "penpair-design" };
 export async function installSkills(options) {
     const source = options.source ?? bundledSkillsDirectory();
     const to = options.to ?? ".skills";
@@ -52,7 +54,7 @@ export async function installSkills(options) {
     for (const name of chosen)
         if (!names.includes(name))
             throw new Error(`no skill named ${name}; shipped: ${names.join(", ")}`);
-    const report = { installed: [], unchanged: [], kept: [], linked: [], agentsRows: [] };
+    const report = { installed: [], unchanged: [], kept: [], linked: [], agentsRows: [], legacy: [] };
     for (const name of chosen) {
         const from = path.join(source, name);
         for (const file of await filesUnder(from)) {
@@ -87,5 +89,18 @@ export async function installSkills(options) {
         const { summary } = await describeSkill(from);
         report.agentsRows.push(`| [${name}](${path.posix.join(to, name, "SKILL.md")}) | ${summary} |`);
     }
+    for (const [oldName, newName] of Object.entries(renamedSkills)) {
+        if (!chosen.includes(newName) || !(await exists(path.join(options.root, to, oldName))))
+            continue;
+        // The project-facts file is the project's own work: carry it over when the new copy is still the empty template.
+        const oldFacts = await readIfExists(path.join(options.root, to, oldName, "references/project-facts.md"));
+        const newFactsFile = path.join(options.root, to, newName, "references/project-facts.md");
+        const template = await readIfExists(path.join(source, newName, "references/project-facts.md"));
+        const current = await readIfExists(newFactsFile);
+        const carriedFacts = oldFacts !== undefined && oldFacts !== template && current === template;
+        if (carriedFacts)
+            await writeFile(newFactsFile, oldFacts);
+        report.legacy.push({ folder: path.posix.join(to, oldName), renamedTo: newName, carriedFacts });
+    }
     return report;
 }

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.2";

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.2";

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.2",
+  "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",
@@ -20,19 +20,14 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
-    "./cli": "./dist/cli.js",
     "./package.json": "./package.json"
   },
-  "bin": {
-    "penpair": "dist/cli.js"
-  },
   "files": [
     "dist",
     "skills",
-    "docs",
     "LICENSE",
     "README.md"
   ],

package/skills/design-judgment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-judgment
-description: Decide how a screen is structured, filled and judged before it is built. Use when designing or redesigning a page or flow (list, detail, queue, dashboard, admin), choosing a composition or density, deciding what fills a card or panel, defining loading, empty and error states, mapping status or feedback to components, comparing layout options, or critiquing a design or a rendered screen. Do not use for writing to Penpot (penpot-design) or for picking and verifying components of a specific library.
+description: Decide how a screen is structured, filled and judged before it is built. Use when designing or redesigning a page or flow (list, detail, queue, dashboard, admin), choosing a composition or density, deciding what fills a card or panel, defining loading, empty and error states, mapping status or feedback to components, comparing layout options, or critiquing a design or a rendered screen. Do not use for writing to Penpot (penpair-design) or for picking and verifying components of a specific library.
 metadata:
   version: "0.1.0"
   scope: design reasoning

package/skills/{penpot-design → penpair-design}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: penpot-design
+name: penpair-design
 description: Work in a Penpot file through penpair: inspect, build, change, audit, export and archive frames and components, bind every value to a token, keep layout as flat auto-layout, and run Penpot as one instance per project. Use when creating, editing, inspecting or exporting anything in Penpot, adding or binding tokens, writing a project snippet, setting up or checking a Penpot instance, or diagnosing a plugin or connection error. Do not use for deciding how a screen should be structured (design-judgment).
 metadata:
   version: "0.1.0"
@@ -8,7 +8,7 @@ metadata:
 compatibility: A running Penpot (local Docker, a team server or the hosted service) with the plugin connected in a visible editor tab, Node 22, penpair installed.
 ---
 
-# penpot-design
+# penpair-design
 
 Penpot is the authority for the design; the code adapts to the frames. The project's component library defines what exists: a component, token or layout the library has wins, and only what it lacks becomes a project-specific component or token.
 

package/skills/{penpot-design → penpair-design}/references/penpot-plugin-gotchas.md

@@ -43,6 +43,8 @@ Each one cost real time. They are written as the behaviour to use. Penpot 2.18.3
 - **Exports can fail once and then work, and can be stale right after a write or a page switch.** Export again, and compare two in a row.
 - The MCP key is personal, one per account, shown once. A key for another instance silently drives another file; penpair refuses it unless told otherwise.
 - A snippet receives data only through its parameters; it cannot read repository files.
+- **Token values can be changed in place** (`token.value = ...`, `token.description = ...`), and `token.remove()`, `set.remove()`, `theme.addSet(set)`, `theme.removeSet(set)` and `theme.remove()` all work. **Not for a typography token:** creating one normalises it (`fontFamilies: "Inter"` becomes `fontFamily: ["Inter"]`), but assigning a new value stores the object as given, un-normalised. Remove the token and add it again, and compare typography values in their normalised form. (Checked on Penpot 2.18.4, hosted.)
+- A new token set is inactive and a set's `resolvedValue` is null until a theme activates it; a file with no active theme resolves no tokens at all.
 
 ## Rendering differences to design for
 

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 (penpot-design) or deciding how a screen looks (design-judgment).
+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).
 metadata:
   version: "0.1.0"
   scope: setup and connection
@@ -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/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.
 
 ## 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.