@yargote/artifacts-cli 0.0.0-stage → 0.1.0-beta.10

package/skills/artifacts-cli/references/commands.md

@@ -0,0 +1,240 @@
+# Command workflow
+
+Check the installed `artifacts --help` before use. These examples use the canonical resource selected for the task. `ARTIFACT_ID` and `REVISION_ID` stand for IDs observed in actual command output.
+
+## Inspect and install bundled skills
+
+When installed help lists `skills`, use these commands without a server or login.
+
+```sh
+artifacts skills
+artifacts skills get artifacts-cli --full
+artifacts skills get --all --full
+artifacts skills path artifacts-cli
+artifacts skills install
+artifacts skills install --agent claude --global
+```
+
+`skills` and `skills list` list names and descriptions. Plain `skills get artifacts-cli` returns the complete `SKILL.md`. `--full` includes references and templates with relative file paths. `skills path` without a name returns the catalog directory.
+
+Installation defaults to `artifacts-cli` in `.agents/skills` under the current directory. `--agent claude` selects `.claude/skills`. `--global` selects the user's home directory. Existing agent directories do not affect the default. The discovery file instructs the agent to load the installed CLI's complete instructions with `artifacts skills get artifacts-cli --full`. Installation reports the absolute path, leaves identical files unchanged, and requires `--force` to replace differing files.
+
+The published `0.1.0-beta.1` package predates skills commands. Do not assume support without checking help.
+
+## Authenticate
+
+```sh
+artifacts login --server https://artifacts.example.test/mcp
+artifacts whoami
+```
+
+Replace the example with the selected resource before executing it. Service commands select `--server RESOURCE` before `ARTIFACTS_SERVER`, then the connection saved by a successful identity-verified login. Ordinary overrides do not replace the saved connection. A later successful login replaces it with the verified REST resource. A failed login to another server preserves the previous connection and its credentials. Check installed help for saved-connection support.
+
+`--state-dir DIR` or `ARTIFACTS_STATE_DIR` selects an isolated private state directory. For automation, `ARTIFACTS_ACCESS_TOKEN` supplies an already authorized bearer token. Do not echo it or put it in an argument.
+
+Use `--no-browser` when the environment cannot open a browser automatically. Open the printed authorization URL and keep the CLI running for its loopback callback. A remote machine's loopback callback must be reachable by the browser used for login. Do not replace the callback with an arbitrary public listener.
+
+`logout` clears local credentials and attempts refresh-token revocation. It keeps the saved connection, so a later `artifacts login` can reuse it. Copied access JWTs can remain valid until expiry. The existing account page's global session revocation stops access across CLI, REST, MCP, and panel. Local logout does not claim to perform that global action.
+
+## Create a complete snapshot
+
+Save this JSON as `snapshot.json`, replacing its content with the requested artifact.
+
+```json
+{
+  "metadata": {
+    "title": "Project note",
+    "description": "A retained note",
+    "custom": { "source": "requested content" }
+  },
+  "content": {
+    "kind": "html",
+    "text": "<!doctype html><html lang=\"en\"><meta charset=\"utf-8\"><title>Project note</title><main><h1>Project note</h1><p>Retained content.</p></main></html>"
+  },
+  "files": [
+    {
+      "path": "notes.txt",
+      "mediaType": "text/plain",
+      "encoding": "utf8",
+      "data": "Retained attachment.\n"
+    }
+  ]
+}
+```
+
+`metadata.description` and `files` are required even when empty. Content kind is `html`, `markdown`, `text`, or `design`. Binary files use `encoding: "base64"` and canonical padded base64. Paths are unique normalized relative paths. Do not use empty, dot, parent, absolute, backslash, percent, or colon path segments. A file cannot also be another file's directory.
+
+```sh
+artifacts create --snapshot snapshot.json
+artifacts list --limit 25
+artifacts read ARTIFACT_ID --out saved.json --quiet
+```
+
+Keep the request ID printed for the mutation. Successful JSON goes to stdout; diagnostics and recovery instructions go to stderr. Exit zero indicates command success. A nonzero exit must be inspected before claiming completion.
+
+For `read`, `--out FILE --quiet` saves the returned response without printing successful JSON. It requires a nonempty output path. It preserves the selected response mode, so use the default full response for snapshot verification. Errors still go to stderr and exit nonzero. Without `--quiet`, `read --out FILE` also prints the response to stdout.
+
+Check installed help for `--quiet` support before running these examples. Older versions, including `0.1.0-beta.1`, can suppress stdout with `artifacts read ARTIFACT_ID --out saved.json > /dev/null`. This redirection preserves stderr and the command's exit status. Use the same fallback for the revision reads below.
+
+## Prepare a design canvas
+
+Read the design skill's `references/canvas.md` through `artifacts skills get artifacts-design --full`. Keep the index in `my-canvas/canvas.json` and complete UTF-8 board documents in `my-canvas/boards/*.html`.
+
+```sh
+artifacts skills path artifacts-cli
+node <returned-skill-directory>/scripts/prepare-retained.mjs ./my-canvas > snapshot.json
+artifacts create --snapshot snapshot.json
+```
+
+The positional form accepts exactly one directory. It preserves the index text and board HTML, sorts snapshot files by path, validates the complete `design` snapshot with the installed contracts, and rejects missing or orphan boards. It uses the directory basename as the title and an empty description. Edit the emitted metadata before saving when needed. Keep the script under the path returned by `skills path` so its package dependencies resolve. All board data, embedded fonts, index text, and metadata share the 1 MiB budget.
+
+The existing named-option form of `prepare-retained.mjs` builds a private retained-verification config from saved receipts and an independent read. It does not prepare a content snapshot. The two input forms cannot be combined.
+
+## Organize projects
+
+Check that installed help lists `projects` and `move` before using them.
+
+```sh
+artifacts create --snapshot snapshot.json --project "Client onboarding"
+artifacts projects
+artifacts list --project "client onboarding"
+artifacts move ARTIFACT_ID --project Archive
+artifacts move ARTIFACT_ID --no-project
+```
+
+A project name contains 1 to 80 characters after trimming and NFC normalization, without control characters. A name that matches an existing project regardless of letter case joins it and keeps its stored spelling. Every read and list item includes `project`, a name or null. `projects` prints `{ "items": [{ "name": "Client onboarding", "artifactCount": 1 }] }`, ordered by name without regard to letter case. A project exists only while it contains an artifact.
+
+`move` takes at least one of `--project NAME`, `--no-project`, `--slug SLUG`, or `--no-slug`, and at most one from each pair. It prints `{ "artifactId": "...", "project": "Archive" }`, or `null` for the project after `--no-project`. An option left out keeps that value. It creates no revision and leaves the publication unchanged. Moving to the current project succeeds without change. A lost move response is recovered with `retry REQUEST_ID` like any other retained mutation.
+
+## Name pages with slugs
+
+Check that installed help lists `--slug` before using it.
+
+```sh
+artifacts create --snapshot snapshot.json --project "Mi wiki" --slug concepts/rag
+artifacts read --project "mi wiki" --slug concepts/rag
+artifacts read --slug index
+artifacts move ARTIFACT_ID --slug concepts/retrieval
+artifacts move ARTIFACT_ID --no-slug
+```
+
+A slug contains 1 to 160 characters of lowercase ASCII kebab-case segments separated by `/`, such as `concepts/rag` or `index`. It is never normalized, and a trailing `.md` is rejected with a hint to remove it. A slug is unique within the owner's project, matched by the project's stored spelling. Artifacts without a project share one unfiled namespace, which `read --slug` without `--project` reads. Every read and list item includes `slug`, a name or null.
+
+`read` takes exactly one of an ID or `--slug`. `--project` applies only with `--slug`. A used slug fails `create` with `slug_conflict`, status 409, and the holder's `artifactId` in `details`. A locator with no artifact fails with `not_found`. `move ID --slug SLUG` renames a page in its project, and `move ID --no-slug` clears the slug. A move to another project keeps the slug unless `--slug` or `--no-slug` changes it. A move fails with `slug_conflict` and changes nothing when the target project already uses the target slug. A slug change creates no revision.
+
+## Search pages
+
+Check that installed help lists `search` before using it.
+
+```sh
+artifacts search envigado
+artifacts search "tarde envigado" --project "mi wiki"
+artifacts search envigado --limit 5 --cursor 5
+```
+
+`search QUERY` finds owned Markdown and text artifacts whose title, description, or content at the head revision contains every term. Quote a query with spaces. The query is plain text of 1 to 256 characters. Every whitespace-separated term must match, letter case and accents are ignored, and operators or punctuation in the query are treated as text, so input such as `"foo" OR NEAR(` never fails with a syntax error. HTML and design artifacts, older revisions, and artifacts shared with the caller are not searched. `--project` matches regardless of letter case. `--limit` is 1 to 25 and defaults to 10. Items are `{ artifactId, project, slug, title, snippet, rank }`, ordered by `rank` and then `artifactId`. `rank` is the FTS5 `bm25` score, where lower is more relevant, and `snippet` is an excerpt with each match wrapped in `**`. Pass `nextCursor` as `--cursor` for the next page; `null` means there are no more results.
+
+## Edit without losing retained data
+
+For a title change, save `changes.json` with only the requested field.
+
+```json
+{ "metadata": { "title": "Reviewed project note" } }
+```
+
+```sh
+artifacts edit ARTIFACT_ID --changes changes.json
+artifacts read ARTIFACT_ID --out current.json --quiet
+```
+
+For a complete replacement, read the current head, preserve untouched data in `next-snapshot.json`, and use that observed revision.
+
+```sh
+artifacts update ARTIFACT_ID --snapshot next-snapshot.json --expected-revision REVISION_ID
+```
+
+A complete command file can preserve a caller-owned request ID, snapshot, and expected revision. Use `artifacts create --command create.json`, `artifacts update --command update.json`, or `artifacts publish --command publish.json`. Do not add `response: "full"` to an existing command that omitted it. Optional response modes affect exact mutation identity.
+
+Command files contain the command itself, without the CLI's retained-operation wrapper.
+
+| Command | Required JSON fields |
+| --- | --- |
+| `create` | `requestId`, `snapshot` |
+| `update` | `requestId`, `artifactId`, `expectedRevisionId`, `snapshot` |
+| `publish` | `requestId`, `artifactId`, `revisionId`, `expectedPublicationVersion` |
+
+`requestId` is a caller-chosen string of 8 to 128 characters. Create and update also accept optional `response` with value `full` or `compact`. Create also accepts an optional `project` name and an optional `slug`. This complete update example replaces a snapshot. Substitute the observed IDs and preserve all required content and attachments in its `snapshot`.
+
+```json
+{
+  "requestId": "reviewed-update-001",
+  "artifactId": "OBSERVED_ARTIFACT_ID",
+  "expectedRevisionId": "OBSERVED_HEAD_REVISION_ID",
+  "snapshot": {
+    "metadata": { "title": "Reviewed project note", "description": "A retained note" },
+    "content": { "kind": "text", "text": "Reviewed content." },
+    "files": []
+  }
+}
+```
+
+Create uses the same `requestId` and complete `snapshot` fields without artifact or expected-revision IDs. A complete publication command has this shape. Replace zero with the observed publication version when already published.
+
+```json
+{
+  "requestId": "reviewed-publish-001",
+  "artifactId": "OBSERVED_ARTIFACT_ID",
+  "revisionId": "SELECTED_REVISION_ID",
+  "expectedPublicationVersion": 0
+}
+```
+
+## Inspect history and publish
+
+```sh
+artifacts history ARTIFACT_ID --summary
+artifacts read ARTIFACT_ID --revision REVISION_ID --out historical.json --quiet
+artifacts publish ARTIFACT_ID --revision REVISION_ID --expected-version 0
+```
+
+The publication example applies only to an unpublished artifact. For an existing publication, replace zero with the `publication.version` observed in a current read. After publishing, read again and compare current publication with the returned receipt.
+
+History returns `nextBeforeSequence`; pass it as `--before-sequence N` to continue. List returns `nextCursor`; pass it as `--cursor CURSOR`. Do not substitute an offset or assume that one page contains everything.
+
+## Share publication access
+
+Check installed help for these commands. They are available from `0.1.0-beta.6`.
+
+```sh
+artifacts share ARTIFACT_ID --email ana@example.com --request-id share-ana-001
+artifacts shares ARTIFACT_ID
+artifacts unshare ARTIFACT_ID SHARE_ID --request-id unshare-ana-001
+artifacts retry share-ana-001
+```
+
+Share requires the owner's `artifacts:publish` scope, trims and lowercases the email, and prints a share with `shareId`, `artifactId`, `kind: "email"`, `value`, and `createdAt`. `shares` requires the same scope and prints `{ "items": [...] }` with current grants without retaining a mutation. Use an observed `shareId` to unshare. Unshare requires the same scope. Unshare and its successful retry exit zero with empty stdout.
+
+The publication admits the owner and signed-in users whose verified email matches a current share. Guests see the published revision and attachments. History, export, editing, and project moves remain owner-only. Shares before first publication wait for publication. Add `--notify` to request one invitation email. Invited people can sign in with an email code when the server enables email.
+
+Share and unshare retain complete normalized commands. `retry REQUEST_ID` replays the original operation. A historical share replay does not regrant revoked access, and an old unshare replay leaves a deliberate new share intact. Verify current grants with `shares ARTIFACT_ID` after a replay.
+
+Share with `--notify` to request one email attempt. Access succeeds when mail is disabled or the owner has used the daily allowance. The JSON result adds `notification.status` as `requested` or `skipped`, with `disabled` or `rate_limited` as the skip reason. `requested` does not confirm delivery. A crash after commit can lose the message. An exact retry preserves the captured flag and never sends a second email. Use a new deliberate command to request another attempt for existing access.
+
+Owners can reserve 100 invitations per UTC day. Revoke, deletion, and failed delivery do not refund reservations. New access is limited to 100 people per artifact and 1000 grants per owner. Existing access remains listable and revocable.
+
+## Verify the exact saved revision
+
+Follow [the retained revision recipe](verify-retained.md) after successful authoring and requested publication. Retain each successful write stdout in a private receipt file. The recipe extracts its IDs, performs a full independent explicit-revision read, and prepares the existing verifier config without authoring or account mutations. It includes an installed-browser path and identifies the additional capabilities for complete verification.
+
+## Retry and export
+
+```sh
+artifacts retry REQUEST_ID
+artifacts export ARTIFACT_ID --revision REVISION_ID --out artifact.zip
+```
+
+`retry` loads the saved complete operation. It does not prepare a new edit or change expected versions. Keep the record after an uncertain result. The server checks current authority before replaying an original receipt.
+
+`read --out` and `export --out` create files exclusively. Use a new destination if one already exists. Do not delete an existing output merely to rerun an example.
+
+The archive contains `artifact.json`, `content.html`, `content.md`, or `content.txt`, and attachments under `files/`. Inspect the manifest's artifact and revision IDs, content, and required attachment bytes. Exporting the same retained revision through REST, MCP, or the panel must yield identical ZIP bytes.

package/skills/artifacts-cli/references/verify-retained.md

@@ -0,0 +1,119 @@
+# Verify the saved revision in the panel
+
+Use the successful create, update, or edit result and an independent full read to select the exact saved revision. Use an authorized browser session to inspect its real panel and, when requested, its protected publication. Preparation alone does not prove persistence or browser behavior.
+
+## Retain the authoring results
+
+Before the authorized write, use `umask 077` and save successful stdout to a new private receipt file. For example, add `> write-result.json` to the create or update command you already intend to run. Keep stderr and the retained request ID for recovery. Continue only after exit zero. Do not repeat a write to obtain a receipt after an uncertain response. Follow [retry recovery](commands.md#retry-and-export).
+
+If publication was requested, also retain the successful publish stdout as `publish-result.json`. Finish that authorized publication before the independent read below. Do not publish, share, or revoke access merely to verify an artifact.
+
+## Prepare the exact selection
+
+Use Node 24+ and a CLI whose help lists `skills path` and `read --quiet`. For older read output, use the [stdout fallback](commands.md#create-a-complete-snapshot). The installed helper requires only Node built-ins. It makes no service request and does not open a browser.
+
+Set `observed_panel_origin` to the panel origin observed in the authorized browser or supplied service configuration. Do not derive it from `ARTIFACTS_SERVER` or the publication host. Replace the example origin before execution.
+
+```sh
+umask 077
+observed_panel_origin=https://panel.example.test
+skill_directory=$(artifacts skills path artifacts-cli)
+artifact_id=$(node -e '
+try {
+	const id = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).artifactId;
+	if (typeof id !== "string" || id.length === 0) throw new Error();
+	process.stdout.write(id);
+} catch {
+	console.error("Cannot extract the artifact ID from the write receipt");
+	process.exitCode = 1;
+}
+' write-result.json)
+revision_id=$(node -e '
+try {
+	const id = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).revision.id;
+	if (typeof id !== "string" || id.length === 0) throw new Error();
+	process.stdout.write(id);
+} catch {
+	console.error("Cannot extract the revision ID from the write receipt");
+	process.exitCode = 1;
+}
+' write-result.json)
+artifacts read "$artifact_id" --revision "$revision_id" --response full --out saved-read.json --quiet
+```
+
+Stop if any extraction or read fails. A compact write receipt can select a revision. The independent read must contain the complete snapshot. Compare its complete metadata, content, and decoded attachment bytes with the intended snapshot. For an update, check the saved parent against the head used to prepare that update.
+
+Save `checks.json` with the requested viewport sizes and meaningful expectations for this document. Replace the example selectors and values with intended content behavior. Expectations run in order inside the content iframe after a fresh load at each viewport.
+
+```json
+{
+	"viewports": [{ "width": 1440, "height": 900 }, { "width": 390, "height": 844 }],
+	"expectations": [
+		{ "kind": "text", "selector": "#total", "text": "5.00" },
+		{ "kind": "click", "selector": "#change" },
+		{ "kind": "text", "selector": "#total", "text": "28.40" }
+	],
+	"timeoutMs": 10000
+}
+```
+
+Use `text` for exact rendered text, `visible` for visibility, `count` for an element count, or `attribute` for an exact attribute value. Use `name` and `value` with `attribute`. Interactions also support `fill` with `value`, `check` with `checked`, and `select` with a `values` array. Do not use arbitrary JavaScript or target panel controls in these expectations.
+
+Prepare a new private config with a future evidence directory that does not yet exist.
+
+```sh
+node "$skill_directory/scripts/prepare-retained.mjs" \
+  --receipt write-result.json --read saved-read.json \
+  --panel-origin "$observed_panel_origin" --checks checks.json \
+  --evidence "$PWD/new-retained-evidence" --out retained-config.json
+```
+
+When publication was requested, add `--publication-receipt publish-result.json` to that invocation. The helper compares its artifact, revision, version, and URL with the current publication in the saved read. A different publication or concurrent change fails preparation. Report the difference. Do not replace expected versions or publish again to make verification pass.
+
+The helper derives all selected IDs and URLs from these inputs. It accepts a newer draft head while keeping the saved revision pinned and reports `headChanged: true`. It emits `status: "prepared"`, never a verification pass. Without a publication receipt, it omits publication coverage even when another revision is published. Existing output files are preserved.
+
+## Inspect with an authorized browser
+
+This route works with the installed CLI, its bundled files, and browser-control capabilities. It requires no repository checkout. Use a user-supplied session or complete the normal sign-in flow. CLI OAuth login does not supply panel cookies. Keep browser authentication inside the browser. Never extract credentials to construct a Playwright context or state file.
+
+After sign-in setup, perform these read-only checks on the selected artifact. Do not create revisions, publish, share, log out, or revoke sessions. Normal protected-viewer admission can consume its one-use grant through the existing GET handoff.
+
+1. Read `retained-config.json` privately and open its exact `panelUrl`. Compare the artifact, revision, digest, and publication version with `expected`. Current panels expose `data-artifact-id`, `data-revision-id`, `data-revision-sha256`, and `data-publication-version`. Version zero means no publication. Report a newer head separately. Never switch the selected revision to the head.
+2. Establish the actual browser version and available frame, response, console, download, and viewport controls. Record missing capabilities. A browser name, load event, or empty console does not establish that content loaded.
+3. Inspect the actual preview iframe source, pinned revision, sandbox, referrer policy, and dimensions. Wait for a distinctive expected element within the configured deadline. Exercise each authorized content control and record the resulting visible state. Repeat at each available requested viewport and check keyboard interactions and overflow where relevant.
+4. When response inspection or native DevTools is available, inspect the iframe request. Record completion, status, content type, CSP, connection allowlist, cache policy, and DNS policy. Distinguish interactive content, inert fallback, and error responses. A pending request has no final response evidence. A top-level preview navigation deliberately returns 403 and cannot replace this iframe check.
+5. When the config includes `publicationUrl`, open that separate protected viewer through normal admission. Compare its selected revision, digest, and version with `expected`. Observe the real content and repeat the authorized interactions. Open `Archivos` and compare the complete attachment inventory and revision-bound links. Check protected download bytes when that capability is available. Missing attachment or response evidence remains unavailable.
+6. After publication interactions, reread the same explicit revision with the quoted IDs into a new private file. Compare its current `publication.revisionId`, `version`, and `url` with the saved read and publish receipt. Reload the selected panel and compare its publication markers again. Report a changed publication as a concurrent change. Do not report protected-publication success for a different selected revision.
+7. If the frame is blank, distinguish admission, pending transport, policy, browser compatibility, content execution, and browser-control failures from observed evidence. If debugger attachment stalls it, disconnect through normal browser controls, reload the same pinned page, and repeat the interaction with native controls. Preserve authentication and containment. Attribute a debugger failure only when that comparison demonstrates it.
+8. Save a sanitized report and private screenshots. Include selected IDs, digest, browser version, viewport sizes, actions, resulting visible states, observed response policies, and unavailable checks. Exclude cookies, tokens, viewer grants, callback queries, raw authentication requests, and private content from diagnostic logs.
+
+This is partial browser verification. Do not return the complete verifier's pass verdict. Missing exact bytes, ZIP, policy, attachment, console, or viewport evidence must remain explicit.
+
+## Run the existing complete verifier when available
+
+The CLI package does not install Playwright, `tsx`, Chrome, or the repository's verifier and rendering-policy modules. Complete automated verification needs an operator-provided installation of that existing verifier with its dependencies and actual supported Chrome. It also needs an explicitly supplied authenticated Playwright `BrowserContext` or owner-private storage-state file prepared through an approved sign-in flow.
+
+For repository operators, run this command from the repository root. The paths in this command are repository capabilities, not paths inside an installed CLI package.
+
+```sh
+node --import tsx .agents/skills/verify-artifacts/scripts/verify-retained.ts \
+  --config /private/path/retained-config.json \
+  --storage-state /private/path/browser-state.json
+```
+
+Pass the prepared config unchanged. The existing verifier validates the full schema and canonical snapshot hash. It checks pinned responses, markers, policies, interactions, ZIP, attachment bytes, viewports, and publication state before and after viewer checks. It writes private evidence and fails on mismatches or concurrent publication changes. Use its callable `verifyRetainedArtifact(context, config)` when an authorized context is supplied. Do not build another viewer or weaken sandbox policies to establish deployed behavior.
+
+If this runtime or authenticated input is unavailable, use the partial route above and name that limit. If browser access is unavailable too, report only the persistence checks actually completed.
+
+## Deliver the observed outcomes
+
+Report each outcome separately, with its evidence and missing checks.
+
+| Outcome | Evidence needed |
+| --- | --- |
+| Persistence | Full independent explicit-revision read and complete intended-snapshot comparison. Name any exact export check separately. |
+| Local rendering | Observed local document layout and interactions. This does not prove hosted rendering. |
+| Panel rendering | Exact real panel selection, pinned iframe, visible content, and observed interaction. Name missing response, policy, byte, console, or viewport checks. |
+| Protected publication | Separate authorized viewer admission for the selected published revision, visible content, interactions, and attachment checks. Report concurrent changes and unavailable checks. |
+
+Use `passed`, `failed`, `unavailable`, or `not requested` for each outcome as the evidence permits. Keep session identifiers and private evidence private. A successful helper invocation establishes only input preparation.

package/skills/artifacts-cli/scripts/prepare-retained.mjs

@@ -0,0 +1,149 @@
+import { lstat, readFile, readdir, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+function requireValue(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function object(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function prepareRetainedSelection({ receipt, expected, checks, panelOrigin, evidenceDirectory, publicationReceipt }) {
+  requireValue(object(receipt) && object(receipt.revision), 'Write receipt must identify a saved revision');
+  requireValue(
+    typeof receipt.artifactId === 'string' && receipt.artifactId.length > 0 &&
+    typeof receipt.revision.id === 'string' && receipt.revision.id.length > 0 &&
+    /^[a-f0-9]{64}$/.test(receipt.revision.sha256),
+    'Write receipt must contain artifact, revision, and SHA-256',
+  );
+  const snapshot = expected?.revision?.snapshot;
+  requireValue(
+    object(expected) && object(snapshot) && object(snapshot.metadata) &&
+    typeof snapshot.metadata.title === 'string' && typeof snapshot.metadata.description === 'string' &&
+    object(snapshot.content) && ['html', 'markdown', 'text', 'design'].includes(snapshot.content.kind) &&
+    typeof snapshot.content.text === 'string' && Array.isArray(snapshot.files),
+    'Independent read must contain the full snapshot, not a compact response',
+  );
+  requireValue(expected.artifactId === receipt.artifactId && expected.revision.id === receipt.revision.id && expected.revision.sha256 === receipt.revision.sha256, 'Independent read differs from the saved write receipt');
+  requireValue(typeof expected.headRevisionId === 'string' && expected.headRevisionId.length > 0, 'Independent read must identify its current draft head');
+  requireValue(object(checks) && Object.keys(checks).every((key) => ['viewports', 'expectations', 'timeoutMs'].includes(key)) && Array.isArray(checks.viewports) && checks.viewports.length > 0 && Array.isArray(checks.expectations), 'Checks must contain viewports and expectations, with optional timeoutMs');
+  let panel;
+  try { panel = new URL(panelOrigin); } catch { throw new Error('Panel origin must be an observed HTTP origin'); }
+  requireValue(['http:', 'https:'].includes(panel.protocol) && !panel.username && !panel.password && panel.pathname === '/' && !panel.search && !panel.hash, 'Panel origin must be an observed HTTP origin without a path, credentials, query, or fragment');
+  panel.pathname = `/artifacts/${encodeURIComponent(expected.artifactId)}`;
+  panel.searchParams.set('revisionId', expected.revision.id);
+  let publicationUrl;
+  if (publicationReceipt !== undefined) {
+    const current = expected.publication;
+    requireValue(
+      object(publicationReceipt) && object(current) &&
+      publicationReceipt.artifactId === expected.artifactId &&
+      publicationReceipt.revisionId === expected.revision.id && publicationReceipt.revisionId === current.revisionId &&
+      Number.isInteger(publicationReceipt.version) && publicationReceipt.version > 0 && publicationReceipt.version === current.version &&
+      typeof publicationReceipt.url === 'string' && publicationReceipt.url === current.url,
+      'Publication differs from the requested receipt or selected revision; report the changed or different publication',
+    );
+    let publication;
+    try { publication = new URL(current.url); } catch { throw new Error('Publication receipt must contain a stable HTTP URL'); }
+    requireValue(['http:', 'https:'].includes(publication.protocol) && !publication.username && !publication.password && !publication.search && !publication.hash && publication.pathname === `/a/${encodeURIComponent(expected.artifactId)}`, 'Publication receipt must contain the selected artifact stable HTTP URL');
+    publicationUrl = publication.href;
+  }
+  return {
+    expected,
+    panelUrl: panel.href,
+    ...(publicationUrl === undefined ? {} : { publicationUrl }),
+    ...checks,
+    evidenceDirectory: resolve(evidenceDirectory),
+  };
+}
+
+async function canvasContracts() {
+  const name = '@yargote/artifacts-contracts';
+  let path;
+  try { path = createRequire(import.meta.url).resolve(name); }
+  catch (error) {
+    if (error.code !== 'MODULE_NOT_FOUND') throw error;
+    path = createRequire(new URL('../../../apps/cli/package.json', import.meta.url)).resolve(name);
+  }
+  return import(pathToFileURL(path).href);
+}
+
+async function prepareCanvasDirectory(input) {
+  const directory = resolve(input);
+  requireValue((await lstat(directory)).isDirectory(), 'Canvas input must be a directory');
+  const { canvasIndexSchema, snapshotSchema } = await canvasContracts();
+  const indexFile = join(directory, 'canvas.json');
+  const indexInfo = await lstat(indexFile);
+  requireValue(indexInfo.isFile(), 'canvas.json must be a regular file');
+  requireValue(indexInfo.size <= 1_048_576, 'canvas.json exceeds the shared 1 MiB revision budget');
+  const indexBytes = await readFile(indexFile);
+  const text = indexBytes.toString('utf8');
+  requireValue(Buffer.from(text, 'utf8').equals(indexBytes), 'canvas.json must contain valid UTF-8');
+  const index = canvasIndexSchema.parse(JSON.parse(text));
+  const boardDirectory = join(directory, 'boards');
+  requireValue((await lstat(boardDirectory)).isDirectory(), 'boards must be a directory, not a symbolic link');
+  const entries = await readdir(boardDirectory, { withFileTypes: true });
+  for (const entry of entries) {
+    const path = `boards/${entry.name}`;
+    requireValue(entry.isFile(), `Canvas board ${path} must be a regular file`);
+    requireValue(Object.hasOwn(index.boards, path), `Orphan canvas board ${path} is absent from canvas.json`);
+  }
+  const files = [];
+  for (const path of [...index.order].sort()) {
+    const filename = join(directory, path);
+    let info;
+    try { info = await lstat(filename); }
+    catch (error) {
+      if (error.code === 'ENOENT') throw new Error(`Canvas board ${path} has no matching file`);
+      throw error;
+    }
+    requireValue(info.isFile(), `Canvas board ${path} must be a regular file`);
+    requireValue(info.size <= 1_048_576, `Canvas board ${path} exceeds the shared 1 MiB revision budget`);
+    const bytes = await readFile(filename);
+    const data = bytes.toString('utf8');
+    requireValue(Buffer.from(data, 'utf8').equals(bytes), `Canvas board ${path} must contain valid UTF-8`);
+    files.push({ path, mediaType: 'text/html', encoding: 'utf8', data });
+  }
+  return snapshotSchema.parse({
+    metadata: { title: basename(directory), description: '' },
+    content: { kind: 'design', text },
+    files,
+  });
+}
+
+const required = ['--receipt', '--read', '--panel-origin', '--checks', '--evidence', '--out'];
+try {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && !args[0].startsWith('--')) {
+    console.log(JSON.stringify(await prepareCanvasDirectory(args[0]), null, 2));
+  } else {
+    const options = new Map();
+    requireValue(args.length % 2 === 0, 'Use named options with one value each');
+    for (let index = 0; index < args.length; index += 2) {
+      const name = args[index];
+      requireValue([...required, '--publication-receipt'].includes(name) && !options.has(name) && typeof args[index + 1] === 'string' && args[index + 1].length > 0, 'Use each supported option once with a nonempty value');
+      options.set(name, args[index + 1]);
+    }
+    requireValue(required.every((name) => options.has(name)), 'Required options are --receipt --read --panel-origin --checks --evidence --out');
+    const json = async (name) => {
+      try { return JSON.parse(await readFile(options.get(name), 'utf8')); }
+      catch { throw new Error(`Cannot read valid JSON for ${name}`); }
+    };
+    const receipt = await json('--receipt');
+    const expected = await json('--read');
+    const checks = await json('--checks');
+    const publication = options.has('--publication-receipt') ? await json('--publication-receipt') : undefined;
+    const config = prepareRetainedSelection({ receipt, expected, checks, panelOrigin: options.get('--panel-origin'), evidenceDirectory: options.get('--evidence'), publicationReceipt: publication });
+    try { await writeFile(options.get('--out'), `${JSON.stringify(config, null, 2)}\n`, { flag: 'wx', mode: 0o600 }); }
+    catch (error) { throw new Error(error?.code === 'EEXIST' ? 'Config output already exists; choose a new output path' : 'Cannot create the private config output'); }
+    const headChanged = expected.headRevisionId !== expected.revision.id;
+    console.log(JSON.stringify({ status: 'prepared', headChanged, publication: publication === undefined ? 'not-requested' : 'requested' }));
+    if (headChanged) console.error('Current draft head differs from the selected saved revision. The selection remains pinned.');
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/skills/artifacts-design/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: artifacts-design
+description: Design HTML documents and multi-board design canvases of a retained Artifact with embedded fonts, light and dark Catppuccin tokens, purposeful layout, and rendered checks. Use before writing or restyling HTML or design boards for the artifacts or artifacts-cli skills.
+---
+
+# Design HTML artifacts
+
+The calling skill owns the snapshot, size limit, and save workflow. This skill owns how the document looks and behaves. Follow the user's visual direction first. When revising content only, keep an existing artifact's established style. When the user asks to redesign or improve the look, start from these defaults.
+
+The document renders in a sandbox that blocks every network request. Fonts, images, and icons load only as `data:` URIs. External stylesheets, Google Fonts links, and CDN scripts silently fail. Inline all CSS and JavaScript.
+
+For multiple boards, read [canvas authoring](references/canvas.md) before writing the index or HTML. It defines the board files, pages, geometry, shared font budget, and complete snapshot workflow.
+
+## Choose the composition
+
+Before writing HTML, identify the reader's task, the facts and assets available, and what the reader should understand or do first. Use supplied facts. Label illustrative inputs and assumptions, and leave unavailable evidence absent.
+
+Choose the element that carries the answer: a comparison, a diagram, a sequence, a chart, or a result beside its inputs. Give it the most space and put its supporting text nearby. If the same composition would fit an unrelated topic unchanged, use the subject's actual relationships or quantities to make the structure more specific. A report can be dense, an explanation can use large scenes, and a calculator can fit on one screen. Do not impose a hero, a section count, or a word budget.
+
+## Use the starter's tokens
+
+Copy the `<style>` block of [the starter](templates/starter.html) into the new document. It defines the color, font, and spacing tokens and shared components: contextual text and labels, lede, summary strip, pills, expandable rows, panel, note, table, filter bar, and footer. Delete components the page does not use. Derive every new color and type decision from its tokens.
+
+The starter supplies a vocabulary, not a layout. Compose the body for the reader's task:
+
+| Purpose | Composition |
+| --- | --- |
+| Report or guide | A conclusion first, a reading column near 68 characters, and evidence beside the claim it supports. |
+| Inventory, ledger, or status | A summary strip, a filter bar with a live count, then one `.row` per record. Its summary shows the identifier, title, and state; its detail holds everything else. Set `--cols` on `.rows` to match the summary cells. Rows stack to one column below 720 px. |
+| Compare options | Aligned criteria in a table, consistent scales, and the tradeoff stated in words. |
+| Explore data | A dominant chart or table sized to carry the page, with filters beside it. |
+| Calculate or simulate | Labeled inputs beside the result they change, with units and a realistic starting example. |
+| Explain a concept | A sequence of large diagrams with short captions; read [visual explanations](references/visual-explanations.md). |
+
+Open in a complete state with the user's real data. Never ship an empty shell or placeholder text.
+
+## Typography
+
+Use the bundled faces through the starter's tokens:
+
+- `--f-display` is Bricolage Grotesque. Use it for `h1` to `h3` and large figures only.
+- `--f-body` is Public Sans for running text, controls, labels, and table headers.
+- `--f-mono` is JetBrains Mono for code and identifiers. Use it for measurements when it helps the reader read or align them.
+- Newsreader is an optional reading face. For a long essay or editorial guide, set `--f-body` to `"Newsreader",Charter,Georgia,serif` and keep Public Sans for controls.
+
+Start with `h1` at `clamp(28px,4vw,40px)` and body at 15 to 16 px with a 1.55 line height. Set labels in the body face at 12 to 13 px, in sentence case without added tracking. Adjust the scale for the document's main visual and reading density. Keep `text-wrap: balance` on headings and `font-variant-numeric: tabular-nums` wherever digits align.
+
+After the HTML file is complete, embed the fonts it names:
+
+```sh
+node <skill-directory>/scripts/embed-fonts.mjs page.html
+```
+
+For the CLI, `<skill-directory>` is the output of `artifacts skills path artifacts-design`. The script rewrites the file in place and is safe to rerun after edits. It selects families from CSS `font-family` and `font` declarations in style elements and inline styles, including referenced custom properties. Comments, content text, and JavaScript strings do not select fonts. It adds italic faces for CSS `font-style: italic`, italic `font` shorthand, or real `<em>`, `<i>`, and `<cite>` elements. It refuses to write a page above 1 MiB. Three families add about 135 KB. Newsreader adds about 80 to 165 KB. Do not name another family unless you embed its `woff2` yourself, because an unembedded face silently falls back. Without Node, keep the fallback stacks and report that the fonts were not embedded.
+
+## Color
+
+The starter follows the viewer's system theme. Light uses Catppuccin Latte and dark uses Mocha, with Blue as the only accent. [Catppuccin roles](references/catppuccin.md) lists every token and the extra chart colors.
+
+- Define each color once as a token on bare `:root` and redefine only the tokens in both dark blocks. Never write a literal color in a component rule.
+- Keep `body` on `var(--page)`. Use `--surface` for the objects you set apart, and `--sunken` for table headers and hover.
+- Show state with soft pills: a `*-soft` background and `*-ink` text. Do not fill badges with saturated pastels. Map every state to neutral, accent, ok, warn, or bad. Do not add a hue for an extra state; distinguish it with its label.
+- Use the accent for links, focus, the selected state, and one primary action. Status colors carry meaning only.
+- When the user names a single dark look, set the Mocha values on bare `:root`, keep `color-scheme: dark`, and drop the media blocks.
+
+## Layout and components
+
+- Center one `.wrap` column at `--width` with `max(16px, env(safe-area-inset-*))` side gutters. Space siblings with grid or flex `gap`.
+- Use borders and fills by role. A summary strip, a table, and one panel can each earn a surface. Running text and headings sit on the page.
+- Use an eyebrow only for source or scope information the heading does not already give. A label names a field, and numbering appears only for real sequences.
+- Encode attention in form. A row that needs action gets a pill or a muted closed state, not only a different word.
+- Put wide code and diagrams in their own `overflow-x: auto` container. Use a `<table>` only for short records that stay readable when scrolled; use expandable rows for records with long text. The page itself never scrolls sideways at 375 px.
+- Draw diagrams in inline SVG with token colors and labels inside the view box. For icons, use inline Tabler outline SVGs with `currentColor`.
+- Respect `prefers-reduced-motion`. Use motion only to explain a change of state.
+
+## Copy
+
+Give the `<title>` a specific name of two to four words, or the name the user already uses for the document. Write labels from the reader's side, in the user's language. State units next to numbers. Put the source and date of the data in the footer.
+
+## Check the rendered page
+
+Run the local helper after embedding fonts and before saving:
+
+```sh
+node <skill-directory>/scripts/verify-local.mjs page.html --evidence ./page-evidence
+```
+
+For the CLI, resolve `<skill-directory>` with `artifacts skills path artifacts-design`. Read [local checks](references/local-checks.md) for existing runtime requirements, optional declarative control expectations, browser selection, and report fields. The helper never installs a dependency, changes the HTML, saves, publishes, or requires service credentials. Its report proves **renderizado local** and leaves visual review required. It does not verify the retained revision or authenticated publication.
+
+Run the [interface checks](references/interface-checks.md) before saving. They distinguish required checks from visual judgment. Render the finished page at 375 px and 1280 px in both light and dark when browser tools are available. Fix observed failures and repeat the affected checks. Report checks you could not run.
+
+The license notices for bundled fonts and adapted guidance are in [third-party notices](THIRD-PARTY-NOTICES.md).