@penpair/core 0.3.0 → 0.3.1

package/dist/cli-main.js

@@ -28,6 +28,7 @@ import { archiveOperation, runOnPage, runOperation } from "./operation.js";
 import { formatDeepReport, runDeepCheck } from "./deep-check.js";
 import { probe } from "./probe.js";
 import { installSkills, listBundledSkills } from "./skills.js";
+import { checkSkills } from "./skill-check.js";
 import { checkProjectSnippets, loadProjectSnippets } from "./project-snippets.js";
 import { builtInRegistry, coerceParams, RegistryError } from "./registry.js";
 import { runSnippet } from "./snippet.js";
@@ -109,6 +110,7 @@ Compare:
 @@INSTANCE@@Skills (the rules an AI agent follows, shipped with penpair):
   penpair skills                                       list them
   penpair skills install [--to <folder>] [--only <name>] [--force] [--agents AGENTS.md] [--dry-run]
+  penpair skills check [--only <name>] [--agents AGENTS.md] [--json]
   (built-in help lists configured extensions without importing their trusted code)
   (config-free inspection requires --standalone; writes require a project)
   penpair --version`;
@@ -801,14 +803,18 @@ async function main(argv, cli) {
     if (command === "skills" &&
         rest[0] !== "install" &&
         [
-            values.agents,
             values["dry-run"],
             values.to,
-            values.only,
             values.force,
         ].some((value) => value !== undefined)) {
         throw new Error("Installation flags require skills install");
     }
+    if (command === "skills" &&
+        rest[0] !== "install" &&
+        rest[0] !== "check" &&
+        (values.agents !== undefined || values.only !== undefined)) {
+        throw new CommandArgumentError("--agents and --only require skills install or skills check");
+    }
     if ((values.resume || values.checkpoint || values["force-lock"] || values.trace) &&
         (!values.apply ||
             !([
@@ -1165,6 +1171,24 @@ async function main(argv, cli) {
         return 0;
     }
     if (command === "skills") {
+        if (rest.length > 1 ||
+            (rest[0] !== undefined &&
+                ![
+                    "install",
+                    "check",
+                ].includes(rest[0]))) {
+            throw new CommandArgumentError("Usage: skills [install | check]; see penpair --help");
+        }
+        if (rest[0] === "check") {
+            const report = await checkSkills({
+                root,
+                agents: values.agents,
+                only: values.only,
+            });
+            output.result(report);
+            output.log(JSON.stringify(report, null, 2));
+            return report.ready ? 0 : 3;
+        }
         if (rest[0] === "install") {
             const report = await installSkills({
                 root,

package/dist/skill-check-entry.d.ts

@@ -0,0 +1,17 @@
+import { type SkillInstructionCheck } from "./skill-check-instructions.js";
+export interface SkillDiagnostic {
+    name: string;
+    path: string;
+    implicitInvocation: boolean | null;
+    entrypoint: "current" | "modified" | "unavailable";
+    problems: string[];
+    warnings: string[];
+}
+interface EntryOptions {
+    root: string;
+    name: string;
+    bundledDirectory: string;
+    instructions: SkillInstructionCheck;
+}
+export declare function checkSkillEntry(options: EntryOptions): Promise<SkillDiagnostic>;
+export {};

package/dist/skill-check-entry.js

@@ -0,0 +1,89 @@
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { parseSkillMetadata, parseSkillYaml } from "./skill-metadata.js";
+import { readSkillFile } from "./skill-file.js";
+import { resolveSkillLink } from "./skill-check-instructions.js";
+async function invocationAllowed(root, skillPath) {
+    const relative = path.posix.join(path.posix.dirname(skillPath), "agents/openai.yaml");
+    const present = await lstat(path.join(root, relative)).catch((error) => {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+        return undefined;
+    });
+    if (!present) {
+        return true;
+    }
+    const metadata = parseSkillYaml(await readSkillFile(root, relative));
+    if (metadata.policy === undefined) {
+        return true;
+    }
+    if (!metadata.policy || typeof metadata.policy !== "object" || Array.isArray(metadata.policy)) {
+        throw new Error("Invalid invocation policy");
+    }
+    const allowed = metadata.policy.allow_implicit_invocation;
+    if (allowed !== undefined && typeof allowed !== "boolean") {
+        throw new Error("Invocation policy must use a boolean");
+    }
+    return allowed !== false;
+}
+export async function checkSkillEntry(options) {
+    const { root, name, bundledDirectory, instructions } = options;
+    const skillPath = path.posix.join(".agents/skills", name, "SKILL.md");
+    const report = {
+        name,
+        path: skillPath,
+        implicitInvocation: null,
+        entrypoint: "unavailable",
+        problems: [],
+        warnings: [],
+    };
+    try {
+        const source = await readSkillFile(root, skillPath);
+        parseSkillMetadata(source, name);
+        const bundled = await readFile(path.join(bundledDirectory, name, "SKILL.md"), "utf8");
+        report.entrypoint = source === bundled ? "current" : "modified";
+        if (report.entrypoint === "modified") {
+            report.warnings.push("The discoverable entrypoint differs from the bundled skill; review intentional customization before refresh.");
+        }
+        const localLinks = [
+            ...source.matchAll(/\[[^\]]+\]\(([^)]+)\)/g),
+        ]
+            .map((match) => match[1])
+            .filter((target) => target && !target.startsWith("#") && !/^[a-z][a-z0-9+.-]*:/i.test(target));
+        if (localLinks.length > 100) {
+            throw new Error("Too many local resource links");
+        }
+        for (const target of localLinks) {
+            await resolveSkillLink(root, skillPath, target);
+        }
+        report.implicitInvocation = await invocationAllowed(root, skillPath);
+        if (!report.implicitInvocation) {
+            report.problems.push("Implicit invocation is disabled in openai.yaml; explicit invocation remains available.");
+        }
+        for (const folder of [
+            ".skills",
+            ".claude/skills",
+        ]) {
+            const otherPath = path.posix.join(folder, name, "SKILL.md");
+            const other = await readSkillFile(root, otherPath).catch(() => undefined);
+            if (other !== undefined && other !== source) {
+                report.problems.push("Codex and another installed skill copy differ; review the conflicting copies before refreshing.");
+            }
+        }
+        const routes = instructions.links[name] ?? [];
+        if (!routes.length) {
+            report.problems.push("No generated task route links this skill from the selected instruction file.");
+        }
+        const resolvedSkill = await realpath(path.join(root, skillPath));
+        for (const target of routes) {
+            if ((await resolveSkillLink(root, instructions.path, target)) !== resolvedSkill) {
+                report.problems.push("An instruction route points to a different skill copy.");
+            }
+        }
+    }
+    catch {
+        report.problems.push("Skill discovery, frontmatter, local resources or UI policy is missing, invalid or resolves outside the project; inspect the local files and preview a skill refresh.");
+    }
+    return report;
+}

package/dist/skill-check-instructions.d.ts

@@ -0,0 +1,7 @@
+export interface SkillInstructionCheck {
+    path: string;
+    problems: string[];
+    links: Record<string, string[]>;
+}
+export declare function resolveSkillLink(root: string, from: string, target: string): Promise<string>;
+export declare function checkSkillInstructions(root: string, instructionFile: string): Promise<SkillInstructionCheck>;

package/dist/skill-check-instructions.js

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { readSkillFile } from "./skill-file.js";
+import { skillInstructionMarkers } from "./skill-instructions.js";
+import { resolveProjectInput } from "./project-input.js";
+export async function resolveSkillLink(root, from, target) {
+    const decoded = decodeURIComponent(target.split("#")[0]);
+    if (!decoded || path.isAbsolute(decoded) || /^[a-z][a-z0-9+.-]*:/i.test(decoded)) {
+        throw new Error("Skill resource link must resolve inside the project");
+    }
+    const relative = path.relative(root, path.resolve(root, path.dirname(from), decoded));
+    return resolveProjectInput(root, relative);
+}
+export async function checkSkillInstructions(root, instructionFile) {
+    const report = {
+        path: instructionFile,
+        problems: [],
+        links: {},
+    };
+    try {
+        const resolved = await resolveProjectInput(root, instructionFile);
+        report.path = path.relative(root, resolved).split(path.sep).join("/");
+        const source = await readSkillFile(root, report.path);
+        const { start, end } = skillInstructionMarkers;
+        if (source.split(start).length !== 2 ||
+            source.split(end).length !== 2 ||
+            source.indexOf(start) > source.indexOf(end)) {
+            throw new Error("Missing or malformed installer-owned skill routing block");
+        }
+        const block = source.slice(source.indexOf(start) + start.length, source.indexOf(end));
+        const routing = block.split("| Skill | Purpose |")[0];
+        for (const match of routing.matchAll(/\[([a-z0-9-]+)\]\(([^)]+)\)/g)) {
+            (report.links[match[1]] ??= []).push(match[2]);
+        }
+    }
+    catch {
+        report.problems.push("Project instructions are missing, unreadable or lack a valid owned routing block; preview skills install --agents with this destination.");
+    }
+    return report;
+}

package/dist/skill-check.d.ts

@@ -0,0 +1,15 @@
+import { type SkillDiagnostic } from "./skill-check-entry.js";
+import { type SkillInstructionCheck } from "./skill-check-instructions.js";
+export interface SkillCheckOptions {
+    root: string;
+    agents?: string;
+    only?: string[];
+}
+export interface SkillCheckReport {
+    agent: "codex";
+    ready: boolean;
+    instructions: Pick<SkillInstructionCheck, "path" | "problems">;
+    skills: SkillDiagnostic[];
+    limitations: string[];
+}
+export declare function checkSkills(options: SkillCheckOptions): Promise<SkillCheckReport>;

package/dist/skill-check.js

@@ -0,0 +1,36 @@
+import { realpath } from "node:fs/promises";
+import { bundledSkillsDirectory, listBundledSkills } from "./skills.js";
+import { checkSkillEntry } from "./skill-check-entry.js";
+import { checkSkillInstructions } from "./skill-check-instructions.js";
+export async function checkSkills(options) {
+    const root = await realpath(options.root);
+    const bundledDirectory = bundledSkillsDirectory();
+    const names = await listBundledSkills(bundledDirectory);
+    const selected = options.only ?? names;
+    if (!selected.length || selected.some((name) => !names.includes(name))) {
+        throw new Error("Select one or more bundled skill names; use penpair skills to list them");
+    }
+    const instructions = await checkSkillInstructions(root, options.agents ?? "AGENTS.md");
+    const skills = await Promise.all([
+        ...new Set(selected),
+    ].map((name) => checkSkillEntry({
+        root,
+        name,
+        bundledDirectory,
+        instructions,
+    })));
+    return {
+        agent: "codex",
+        ready: !instructions.problems.length && skills.every((skill) => !skill.problems.length),
+        instructions: {
+            path: instructions.path,
+            problems: instructions.problems,
+        },
+        skills,
+        limitations: [
+            "Offline project-file checks only; no connection, adapter/provider execution, credential reads or writes.",
+            "Does not inspect global Codex settings, session skill catalogs, context budgets or UI selection badges.",
+            "A valid install and allowed invocation policy do not prove model selection, correct workflow application, visual quality or owner approval.",
+        ],
+    };
+}

package/dist/skill-file.d.ts

@@ -0,0 +1,2 @@
+/** Read only bounded regular files inside the explicitly selected project. */
+export declare function readSkillFile(root: string, relative: string): Promise<string>;

package/dist/skill-file.js

@@ -0,0 +1,31 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { resolveProjectInput } from "./project-input.js";
+import { maxSkillBytes } from "./skill-metadata.js";
+/** Read only bounded regular files inside the explicitly selected project. */
+export async function readSkillFile(root, relative) {
+    const resolved = await resolveProjectInput(root, relative);
+    const handle = await open(resolved, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > maxSkillBytes) {
+            throw new Error("Skill input must be a regular file within the 128 KB limit");
+        }
+        const buffer = Buffer.alloc(maxSkillBytes + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+            if (!bytesRead) {
+                break;
+            }
+            length += bytesRead;
+        }
+        if (length > maxSkillBytes) {
+            throw new Error("Skill input exceeds the 128 KB limit");
+        }
+        return buffer.subarray(0, length).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/skill-instructions.d.ts

@@ -1,3 +1,7 @@
+export declare const skillInstructionMarkers: {
+    start: string;
+    end: string;
+};
 export interface InstructionReport {
     path: string | null;
     status: "not-selected" | "choice-required" | "unchanged" | "preview" | "written";

package/dist/skill-instructions.js

@@ -2,8 +2,13 @@ import { lstat, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 import { resolveProjectOutput } from "./project-input.js";
 import { atomicWriteFile } from "./atomic-output.js";
+import { renderSkillRouting } from "./skill-routing.js";
 const start = "<!-- penpair:skills:start -->";
 const end = "<!-- penpair:skills:end -->";
+export const skillInstructionMarkers = {
+    start,
+    end,
+};
 async function exists(file) {
     try {
         await lstat(file);
@@ -70,6 +75,7 @@ export async function planSkillInstructions(root, rows, destination) {
     }));
     const block = [
         start,
+        ...renderSkillRouting(relativeRows),
         "| Skill | Purpose |",
         "| --- | --- |",
         ...relativeRows,

package/dist/skill-metadata.d.ts

@@ -0,0 +1,8 @@
+export interface SkillMetadata {
+    name: string;
+    description: string;
+}
+export declare const maxSkillBytes: number;
+/** Parse data only; aliases and unknown tags cannot expand a local skill file. */
+export declare function parseSkillYaml(source: string): Record<string, unknown>;
+export declare function parseSkillMetadata(source: string, expectedName?: string): SkillMetadata;

package/dist/skill-metadata.js

@@ -0,0 +1,52 @@
+import { parseDocument } from "yaml";
+export const maxSkillBytes = 128 * 1024;
+/** Parse data only; aliases and unknown tags cannot expand a local skill file. */
+export function parseSkillYaml(source) {
+    if (Buffer.byteLength(source) > maxSkillBytes) {
+        throw new Error("Skill metadata exceeds the 128 KB limit");
+    }
+    const document = parseDocument(source, {
+        uniqueKeys: true,
+    });
+    if (document.errors.length || document.warnings.length) {
+        throw new Error("Invalid skill YAML metadata");
+    }
+    let value;
+    try {
+        value = document.toJS({
+            maxAliasCount: 0,
+        });
+    }
+    catch {
+        throw new Error("Skill YAML aliases are not supported");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Skill YAML metadata must be an object");
+    }
+    return value;
+}
+export function parseSkillMetadata(source, expectedName) {
+    if (Buffer.byteLength(source) > maxSkillBytes) {
+        throw new Error("SKILL.md exceeds the 128 KB limit");
+    }
+    const frontmatter = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source);
+    if (!frontmatter) {
+        throw new Error("SKILL.md requires YAML frontmatter with name and description");
+    }
+    const metadata = parseSkillYaml(frontmatter[1]);
+    if (typeof metadata.name !== "string" ||
+        !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(metadata.name) ||
+        metadata.name.length > 64 ||
+        (expectedName !== undefined && metadata.name !== expectedName)) {
+        throw new Error("Skill name must match its kebab-case folder (at most 64 characters)");
+    }
+    if (typeof metadata.description !== "string" ||
+        !metadata.description.trim() ||
+        metadata.description.length > 1024) {
+        throw new Error("Skill description must be nonempty text (at most 1024 characters)");
+    }
+    return {
+        name: metadata.name,
+        description: metadata.description.trim().replace(/\s+/g, " "),
+    };
+}

package/dist/skill-routing.d.ts

@@ -0,0 +1,2 @@
+/** Instruction links have already been made relative to their destination. */
+export declare function renderSkillRouting(rows: string[]): string[];

package/dist/skill-routing.js

@@ -0,0 +1,36 @@
+const tasksBySkill = {
+    "penpair-setup": "Install Penpair or repair a Penpot connection",
+    "penpair-design": "Inspect, edit, audit or export a Penpot file",
+    "penpair-recipes": "Build a Penpot screen or derive a state variant from an approved frame",
+    "design-judgment": "Choose or critique hierarchy, density and screen states",
+    "penpair-handoff": "Implement a frontend from an approved Penpot design",
+    "penpair-verify": "Compare a frontend with its approved design or recheck visual fixes",
+};
+/** Instruction links have already been made relative to their destination. */
+export function renderSkillRouting(rows) {
+    const routes = [];
+    for (const row of rows) {
+        const match = /^\| \[([a-z0-9-]+)\]\(([^)]+)\) \|/.exec(row);
+        if (!match) {
+            continue;
+        }
+        const name = match[1];
+        const task = tasksBySkill[name];
+        if (task) {
+            routes.push(`| ${task} | [${name}](${match[2]}) |`);
+        }
+    }
+    if (!routes.length) {
+        return [];
+    }
+    return [
+        "Before working on a matching task, read the linked SKILL.md and follow its relevant workflow before running design or implementation tools.",
+        "Briefly name the selected skill and its purpose when starting or changing workflow; report actual evidence separately from the intention to use a skill.",
+        "Use the smallest applicable set of skills; follow a linked companion only when the task reaches that stage. Skill selection does not authorize additional writes or replace owner approval.",
+        "",
+        "| Task | Read first |",
+        "| --- | --- |",
+        ...routes,
+        "",
+    ];
+}

package/dist/skills.js

@@ -4,6 +4,7 @@ import { planSkillInstructions, applySkillInstructions, } from "./skill-instruct
 import { lstat, mkdir, readdir, readFile, symlink } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseSkillMetadata } from "./skill-metadata.js";
 /** The skills shipped inside the package (`skills/` next to `dist/`). */
 export const bundledSkillsDirectory = () => path.join(path.dirname(fileURLToPath(import.meta.url)), "../skills");
 /** Files a project fills in. They are written once and never replaced, not even with --force. */
@@ -61,8 +62,7 @@ async function exists(file) {
 /** The skill's name and the first sentence of its description, from the frontmatter, for a row in a project's agent guide. */
 export async function describeSkill(skillDirectory) {
     const text = (await readIfExists(path.join(skillDirectory, "SKILL.md"))) ?? "";
-    const name = /^name:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? path.basename(skillDirectory);
-    const description = /^description:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "";
+    const { name, description } = parseSkillMetadata(text, path.basename(skillDirectory));
     return {
         name,
         summary: description.split(/(?<=\.)\s/)[0] ?? description,

package/dist/version.d.ts

@@ -1,2 +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.3.0";
+export declare const version = "0.3.1";

package/dist/version.js

@@ -1,2 +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.3.0";
+export const version = "0.3.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/core",
-  "version": "0.3.0",
+  "version": "0.3.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": {
@@ -43,7 +43,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.32.0"
+    "@modelcontextprotocol/sdk": "1.32.0",
+    "yaml": "2.9.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

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 (penpair-design) or for picking and verifying components of a specific library.
+description: Choose or critique a screen's hierarchy, density, content and loading, empty or error states. Use for composition decisions and visual critique while respecting approved designs; use penpair-design for Penpot operations and the project's library guidance for component APIs.
 metadata:
   version: "0.1.0"
   scope: design reasoning

package/skills/design-judgment/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Design Judgment"
+  short_description: "Review screen hierarchy, density and states"
+  default_prompt: "Use $design-judgment to critique this screen's hierarchy and density against the project's approved design direction."
+policy:
+  allow_implicit_invocation: true

package/skills/penpair-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: penpair-design
-description: Inspect, edit, audit or export a Penpot design through penpair with a pinned target, recoverable writes and independent verification. Use for plugin execution and design-file operations.
+description: Inspect, edit, audit or export a Penpot design with Penpair. Use for Penpot frames, tokens, components, plugin scripts and design screenshots; use penpair-handoff when implementing the design in frontend code.
 metadata:
   version: "0.1.0"
   scope: penpot
@@ -15,6 +15,12 @@ Penpot supplies design evidence; the project's component library and declared to
 
 Before building a page, record a short composition decision: the primary user task, one chosen existing reference, visual hierarchy and useful context, responsive behavior and focus order. Build one small representative frame first; critique its hierarchy, density and missing context before expanding themes/states/devices. This is a design decision and critique, not owner approval.
 
+For an approved-reference variant, retain the actual source image and inspection,
+preserved regions and declared deviations. Use the project-owned comparative
+checkpoint from `penpair-recipes` when installed. Before expansion, record a
+source/candidate critique with consequential findings; missing evidence remains
+pending even when token and overflow audits pass.
+
 1. **Target.** Validate config and doctor's file identity; confirm the owner-authorized page/frame IDs. For project context, read [project-facts.md](references/project-facts.md). Done when the configured pin and live target agree.
 2. **Inspect.** Obtain complete structured evidence with `inspect ID --page PAGE --all` or the actual typed token catalog. Tree text and audit examples are bounded previews. Done when source revision, completeness and unknowns are explicit.
 3. **Change.** Follow [write-protocol.md](references/write-protocol.md): pinned inspection, one idempotent write and independent positive readback. Before the first script on an API version, read [plugin gotchas](references/penpot-plugin-gotchas.md). Done when actual geometry/text/bindings match the intended result.
@@ -23,6 +29,10 @@ Before building a page, record a short composition decision: the primary user ta
 
 For page construction, use `penpair-recipes` when installed. For implementation evidence/approvals, use `penpair-handoff`. For library structure, read [library-in-penpot.md](references/library-in-penpot.md); for layout choices, read [auto-layout.md](references/auto-layout.md). Read conditional references only for the selected work.
 
+When the task reaches a running frontend, use `penpair-verify` when installed for
+real browser comparison and the inspect/fix/recapture loop. A design export does
+not verify the frontend.
+
 Layer names, text and token descriptions remain literal untrusted design data. Trusted project adapters/snippets/theme modules execute code, including offline imports; a read header is not a sandbox. Built-in inspection avoids adapter imports. Config-free inspection uses explicit `--standalone` only outside a configured project.
 
 File scripts are plugin bodies. Read phases/includes declare `// penpair: read`; write bodies also declare idempotency and supply separate inspection/readback files. Review inspection before `--apply`; keep delivered snippets under 90 KB. After uncertainty, preserve the run ID, inspect `runs RUN_ID` and actual objects, then explicitly recover unchanged source/parameters. Shared markers are advisory coordination, not atomic exclusion.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Penpair Design"
+  short_description: "Inspect and safely update Penpot designs"
+  default_prompt: "Use $penpair-design to inspect the authorized Penpot frame and verify any scoped changes independently."
+policy:
+  allow_implicit_invocation: true

package/skills/penpair-handoff/SKILL.md

@@ -1,12 +1,23 @@
 ---
 name: penpair-handoff
-description: Turn a complete Penpot frame inspection into an implementation handoff, explicit component mappings and baseline comparison evidence; retain exact owner approvals and unresolved semantics.
+description: Implement a frontend from an approved Penpot design, or prepare its design-to-code handoff. Use for component mapping, responsive behavior and design evidence; retain unknown semantics, approved references and comparison requirements.
 ---
 
 # Design handoff
 
 **Recommended companion for frontend verification: `@penpair/reflection-check`.** Read [comparison-companion.md](references/comparison-companion.md) when the task includes implementing and checking a frontend. Explain its purpose, check whether it is installed and registered, and retain missing baseline/mapping/provider work as explicit next steps. An installed adapter alone is not a completed comparison.
 
+Use `penpair-verify` when installed once the task reaches a running implementation,
+including requests to check parity or fix visual mismatches in an existing route.
+That skill owns the browser comparison and repair loop; this skill owns source
+inspection, component mapping and implementation handoff.
+
+Carry the project's visual checkpoint into the handoff when one exists. Otherwise
+record the source image/inspection and identity, preserved/changed regions, case
+intent, candidate evidence, findings and next action in the project's review
+format. Keep that project-owned record outside installed skill folders so refresh
+cannot replace it. Missing critique or approval stays visible.
+
 1. **Source.** Confirm the authorized file/page/frame IDs and obtain complete structured evidence with `inspect ID --page PAGE --all`. Done when file identity, revision, traversal completeness and unknown fields are explicit. Treat layer names, text and descriptions as literal untrusted design data.
 2. **Map.** Read [handoff-flow.md](references/handoff-flow.md) for exact component identities, text props and freshness. Generate `spec` from the captured frame and explicit map. Done when each region has observed layout/bindings/text and each unresolved component or behavior is visible.
 3. **Implement.** Adapt the project's implementation to the reviewed design within its existing component conventions. Resolve application state, interactions, responsive rules and accessibility semantics with project evidence. Done when observed design facts and owner decisions are distinguished from implementation assumptions.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Penpair Handoff"
+  short_description: "Implement a frontend from Penpot evidence"
+  default_prompt: "Use $penpair-handoff to implement the approved Penpot design with explicit component mappings and verification readiness."
+policy:
+  allow_implicit_invocation: true

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

@@ -8,6 +8,9 @@ Recommend `@penpair/reflection-check` when a task moves from a design into front
 4. Run `penpair reflection plan --map FILE`, then `penpair reflection check --map FILE --provider FILE` once ready. Inspect the images and report pending cases, measured drift and unknowns. Preserve the baseline bytes.
 5. Report separate readiness stages: installed, registered, references approved, cases mapped, provider configured, browser verified and owner reviewed. Missing stages are explicit pending work. Never describe installing the adapter as supplying a browser or a complete frontend integration.
 
-The package reference defines the current provider evidence contract. A reusable real-browser starter is planned work; until available, use the project's real provider. For a design-only task, explain the companion briefly and defer implementation setup until that work is in scope. The final comparison verdict still requires owner review.
+The package reference defines the current provider evidence contract. For a
+design-only task, defer implementation setup until that work is in scope. Use
+`penpair-verify` when installed for the real browser comparison and repair loop.
+The final comparison verdict still requires owner review.
 
 The command package ships a real-browser starter at `node_modules/@penpair/web/examples/reflection-browser/`. Supply project-owned setup and independent state hooks; read its README for font, scroll/sticky, pointer and crop requirements. Keep browsers pinned in the adopting project.

package/skills/penpair-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: penpair-recipes
-description: Build or update a Penpot page through reviewed penpair recipes, active tokens and an idempotent script, then verify the resulting objects and export.
+description: Build a Penpot screen or create loading, empty or error variants from an approved frame using the existing library and tokens. Use for design construction and state variants in Penpot; frontend implementation belongs to penpair-handoff.
 ---
 
 # Page recipes
@@ -10,6 +10,13 @@ Use the existing project library and declared tokens as inputs. Work within the
 
 Before building a page, record a short composition decision: the primary user task, one chosen existing reference, visual hierarchy and useful context, responsive behavior and focus order. Build one small representative frame first; critique its hierarchy, density and missing context before expanding themes/states/devices. This is a design decision and critique, not owner approval.
 
+For a substantial state variant or screen family, read
+[visual-checkpoint.md](references/visual-checkpoint.md) and create a project-owned
+evidence record. Carry the approved image/inspection, preserved regions and
+intentional deviations into the plan. Keep expansion pending until the first
+candidate has actual comparison evidence and its blocking findings are resolved.
+Do not infer critique from a passing mechanical audit.
+
 1. **Target.** Read the project's design facts and `penpair doctor --json`. Confirm the pinned file and exact page/frame IDs. Done when the connected target matches the authorized target and required APIs are observed.
 2. **Vocabulary.** Inspect the actual token catalog, theme selection and existing components. Select explicit token names/types and component IDs. Done when every recipe input resolves or is listed as an explicit missing dependency. Equal computed values alone establish candidate matches.
 3. **Preview.** Read [build-flow.md](references/build-flow.md) for file declarations, helper order and partial-root ownership. Prepare an idempotent operation with positive independent readback. Run inspection first. Done when source preconditions and the exact changed objects are reviewable.

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

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

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

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

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

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

package/skills/penpair-setup/SKILL.md

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

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

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

package/skills/penpair-verify/SKILL.md

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

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

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

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

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