@yargote/artifacts-cli 0.1.0-beta.5 → 0.1.0-beta.7

package/README.md

@@ -11,9 +11,9 @@ Use Node 24 or later. The beta targets macOS and Linux. Windows has not been ver
 Choose one persistent installation:
 
 ```sh
-npm install --global @yargote/artifacts-cli@0.1.0-beta.5
+npm install --global @yargote/artifacts-cli@0.1.0-beta.7
 # Or, with pnpm and an existing global bin directory on PATH:
-pnpm add --global @yargote/artifacts-cli@0.1.0-beta.5
+pnpm add --global @yargote/artifacts-cli@0.1.0-beta.7
 artifacts --version
 ```
 
@@ -22,18 +22,18 @@ If pnpm reports that no global bin directory exists, run `pnpm setup` and reopen
 For one-off execution, pin the same version:
 
 ```sh
-npx --yes @yargote/artifacts-cli@0.1.0-beta.5 --help
-pnpm dlx @yargote/artifacts-cli@0.1.0-beta.5 --help
+npx --yes @yargote/artifacts-cli@0.1.0-beta.7 --help
+pnpm dlx @yargote/artifacts-cli@0.1.0-beta.7 --help
 ```
 
 `@beta` follows future prereleases. Exact versions remain reproducible. No stable `latest` release is part of this beta. An organization's pnpm minimum release age or trust policy can delay a new release. Follow that policy rather than disabling it globally.
 
 ## Complete first use
 
-An existing Artifacts account is required. Select the complete OAuth resource, including `/mcp`:
+An existing Artifacts account is required. Select the REST OAuth resource, which is the API origin without `/mcp`. When upgrading an older deployment, complete the [API migration](../../docs/deployment.md#migrate-the-api-hostname) before using the address below.
 
 ```sh
-export ARTIFACTS_SERVER='https://artifacts-mcp.yersonargotev.workers.dev/mcp'
+export ARTIFACTS_SERVER='https://artifacts-api.yersonargotev.workers.dev'
 artifacts login
 artifacts whoami
 ```
@@ -64,7 +64,7 @@ artifacts export ARTIFACT_ID --revision REVISION_ID --out artifact.zip
 artifacts logout
 ```
 
-Publication URLs require authenticated owner access. A retained request ID appears on stderr before each mutation. If the response is lost, run `artifacts retry REQUEST_ID` with the same server and state directory. Keep that state directory when upgrading, reinstalling, or switching between global and one-off execution.
+A publication URL requires sign-in. It opens for the owner and for a user whose verified email equals an email share of the artifact. That user sees only the published revision and its attachments. A retained request ID appears on stderr before each mutation. If the response is lost, run `artifacts retry REQUEST_ID` with the same server and state directory. Keep that state directory when upgrading, reinstalling, or switching between global and one-off execution.
 
 ## Upgrade or uninstall
 
@@ -82,7 +82,9 @@ Run `artifacts logout` before uninstalling if you want to clear credentials. Uni
 
 Skills, help, and version commands work without a server or login. Skills commands do not read credentials or create private state. They accept and ignore global `--server` and `--state-dir` values, including their environment defaults.
 
-`--server RESOURCE` selects the exact canonical OAuth resource. `ARTIFACTS_SERVER` supplies the same value. A resource ending in `/mcp` uses REST under `/mcp/v1`. The CLI has no production default.
+`--server RESOURCE` selects the exact canonical REST OAuth resource. `ARTIFACTS_SERVER` supplies the same value. Use the configured `API_URL` origin to call REST under `/v1`. The CLI has no production default and does not rewrite the supplied URL. Older deployments without `API_URL` still use their complete MCP resource and routes under `/mcp/v1`.
+
+A hostname change requires a new `artifacts login --server RESOURCE`. Credentials and retained operations remain bound to their exact original resource. Do not move an old operation file to the new resource or redirect its bearer requests.
 
 `--state-dir DIR` overrides `ARTIFACTS_STATE_DIR`. The default is `~/.local/state/artifacts`. The state directory must be private and owned by the current user. Credentials are separate from operation files. Profiles bind credentials to the exact resource. Retained operation paths hash the resource and request ID, so request IDs cannot select filesystem paths.
 
@@ -124,6 +126,9 @@ artifacts publish [ID] --command FILE
 artifacts export ID --revision REV --out FILE
 artifacts move ID --project NAME [--request-id ID]
 artifacts move ID --no-project [--request-id ID]
+artifacts share ID --email EMAIL [--notify] [--request-id ID]
+artifacts shares ID
+artifacts unshare ID SHARE_ID [--request-id ID]
 artifacts retry REQUEST_ID
 artifacts skills [list]
 artifacts skills get NAME [--full]
@@ -197,6 +202,27 @@ Every artifact read and list item includes `project`, a name or null. `projects`
 
 Version `0.1.0-beta.4` and earlier parse artifact responses strictly and fail with `invalid_response` against a server that returns `project`. Upgrade the CLI together with the server.
 
+## Share publication access
+
+These commands are available from `0.1.0-beta.6`. Check installed help for support.
+
+```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` trims and lowercases the email and prints one share as JSON with `shareId`, `artifactId`, `kind: "email"`, `value`, and `createdAt`. `shares` prints `{ "items": [...] }` with current grants and retains no operation. Take `SHARE_ID` from that output. `unshare` and a successful retry of an unshare exit zero with empty stdout. All three commands require the owner's `artifacts:publish` scope.
+
+A signed-in user whose verified email matches a share can view the published revision and its attachments. History, export, edits, and project moves remain owner-only. Shares created before first publication remain stored, but the URL opens only after 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 the complete normalized command before submission. Recover an uncertain result with `retry REQUEST_ID`. A replay confirms the original operation, so a historical share replay does not restore a revoked grant. An old unshare replay leaves a deliberate new share intact. Run `shares ARTIFACT_ID` to verify current grants.
+
+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.
+
 ## Complete commands and edits
 
 `--command FILE` accepts a complete create, update, or publish command. It cannot be combined with other mutation options. For update and publish, an optional positional artifact ID must equal the command's `artifactId`. Every field, including the omission of `response`, is retained.
@@ -228,7 +254,7 @@ Publish always selects an immutable revision. `--expected-version 0` expects no
 
 Each invocation resolves one access token for its reads, owner check, and submission. A concurrent login cannot change the command owner between these requests. Every mutation verifies the owner and retains an exclusive private operation file before submission. Missing request IDs default to random UUIDs. The operation stores its exact command, owner, and resource. It contains no credentials. Existing operation files require explicit `retry` and are never replaced by another preparation.
 
-`retry REQUEST_ID` verifies the current resource and owner, then sends the unchanged command once. Retry does not read a new head, change expected versions, add a response projection, or rebase a conflict. Its diagnostic identifies the result as a retained receipt. A fresh `read` returns current state.
+`retry REQUEST_ID` verifies the current resource and owner, then sends the unchanged command once. Retry does not read a new head, change expected versions, add a response projection, or rebase a conflict. Its diagnostic identifies replay of the original operation and warns that replay does not establish current state. A fresh `read` or `shares` returns current state.
 
 If a response is lost after commit, retry recovers the original receipt. If a conflict occurs, the retained operation remains available for inspection. A new read and a deliberate new command with a new request ID are required to incorporate another writer's changes.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yargote/artifacts-cli",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0-beta.7",
   "private": false,
   "type": "module",
   "description": "Command-line client for the Artifacts REST API.",
@@ -27,8 +27,8 @@
     "skills"
   ],
   "dependencies": {
-    "@yargote/artifacts-contracts": "0.1.0-beta.5",
-    "@yargote/artifacts-client": "0.1.0-beta.5",
+    "@yargote/artifacts-contracts": "0.1.0-beta.7",
+    "@yargote/artifacts-client": "0.1.0-beta.7",
     "openid-client": "6.8.8",
     "zod": "4.6.5"
   },

package/skills/artifacts-cli/SKILL.md

@@ -17,11 +17,11 @@ Run `artifacts whoami` before the first mutation when the current identity is no
 
 A revision is a complete snapshot with `metadata`, `content`, and `files`. The command reference contains its JSON shape. Use the requested title, language, content, and attachments. Do not include unrelated files or credentials.
 
-Use self-contained HTML for interactive content. Inline styles and scripts and embed required assets as data URLs. External requests, CDN dependencies, relative executable assets, forms, browser storage, and multi-file websites are unsupported. Attachments are downloads, not importable website resources. Markdown and text display inertly.
+Use self-contained HTML for interactive content. For several HTML boards in one canvas, use `design` and follow the design skill's `references/canvas.md`. Inline styles and scripts and embed required assets as data URLs. External requests, CDN dependencies, relative executable assets, forms, browser storage, and multi-file websites are unsupported. Attachments are downloads, not importable website resources. Markdown and text display inertly.
 
 Keep the whole revision within 1 MiB of decoded content, metadata, attachment paths, media types, and attachment bytes. At most 32 attachments are accepted. Base64 changes wire size, not the decoded limit. If required content exceeds a limit, explain the constraint without silently removing it.
 
-Before writing or restyling HTML, run `artifacts skills get artifacts-design --full` and follow it. It owns typography, embedded fonts, color, layout, and the rendered checks. Finish those checks before saving when browser tools are available. A successful CLI write proves persistence, not visual quality or browser compatibility. Interactive HTML follows the server's Chrome policy; do not promise it in every browser.
+Before writing or restyling HTML or design boards, run `artifacts skills get artifacts-design --full` and follow it. It owns typography, embedded fonts, color, layout, and the rendered checks. Finish those checks before saving when browser tools are available. A successful CLI write proves persistence, not visual quality or browser compatibility. Interactive HTML follows the server's Chrome policy; do not promise it in every browser.
 
 ## Create or revise
 
@@ -41,7 +41,17 @@ Use `move ID --project NAME` to file an existing artifact under a project and `m
 
 Publish when the user requests publication, a shareable artifact URL, or a change to the live artifact. Use the exact saved revision selected by the user or returned by the edit. Read the current publication version before preparing publication. Use zero only when the artifact is unpublished.
 
-A published URL still requires its owner's Artifacts login. Publishing a historical revision leaves the draft head unchanged. Report the returned protected URL only after the publication succeeds and its current state is verified.
+A published URL requires sign-in by the owner or a user whose verified email matches a current share. Publishing a historical revision leaves the draft head unchanged. Report the returned protected URL only after the publication succeeds and its current state is verified.
+
+## Share publication access
+
+Check installed help for `share`, `shares`, and `unshare` support. These commands are available from `0.1.0-beta.6`. Share only when the user requests access for an exact email. Use `share ARTIFACT_ID --email EMAIL`, then verify the normalized email with `shares ARTIFACT_ID`. Use the observed `shareId` with `unshare ARTIFACT_ID SHARE_ID` to revoke it. Unshare and its successful retry exit zero with empty stdout.
+
+A matching signed-in user must have a verified email. Access covers the published revision and its attachments. History, export, editing, and project moves stay owner-only. A share before first publication remains stored and waits for publication. Add `--notify` when the user asks for an invitation email. Invited people can sign in with an email code when the server enables email.
+
+Recover uncertain share or unshare results with `retry REQUEST_ID`. Replay confirms the original operation and does not establish current grants. An old share replay does not restore revoked access. An old unshare replay does not remove a deliberate new share. Verify current grants with `shares ARTIFACT_ID`.
+
+When the user asks to notify an invited person, add `--notify` to `artifacts share`. Preserve that flag in the retained command and use `artifacts retry` after an uncertain response. Report `requested` as an invitation request, never as confirmed delivery. A skipped notification still grants access. A new deliberate share command can request another attempt for existing access, subject to the owner's daily allowance.
 
 ## Recover an uncertain write
 
@@ -53,10 +63,12 @@ A `request_conflict` means the ID was used with different arguments. Do not desc
 
 ## Verify and deliver
 
-After create or update, read the explicit returned revision. Use `read ARTIFACT_ID --revision REVISION_ID --out FILE --quiet` to retain the full response without printing its snapshot. Check that the installed `--help` supports `--quiet` first. For older versions, use the command workflow's stdout redirection fallback. Compare the saved complete metadata, content, and decoded attachment bytes with the intended snapshot. For an update, check that its parent is the head used for preparation. Compact responses cannot verify omitted content.
+Retain successful create, update, or edit stdout in a private receipt file. After create or update, read the explicit returned revision. Use `read ARTIFACT_ID --revision REVISION_ID --out FILE --quiet` to retain the full response without printing its snapshot. Check that the installed `--help` supports `--quiet` first. For older versions, use the command workflow's stdout redirection fallback. Compare the saved complete metadata, content, and decoded attachment bytes with the intended snapshot. For an update, check that its parent is the head used for preparation. Compact responses cannot verify omitted content.
 
 After publication, read current publication and compare revision, version, and URL with the committed result. A replayed receipt describes the original commit; another writer may have changed the current publication afterward. Report that difference.
 
+For real panel and requested protected-publication checks, follow [the exact saved revision recipe](references/verify-retained.md). It prepares the existing verifier inputs from the write receipt and independent full read. It also gives an installed-browser route when the complete verifier runtime is unavailable. Report persistence, local rendering, panel rendering, and protected publication separately. Input preparation is not a browser pass.
+
 Follow list and history cursors when the request needs more than the first page. Export an explicit retained revision to the requested destination. The CLI checks the archive digest. Confirm that the file exists and inspect its manifest and relevant content before linking it.
 
 Report the title, saved revision, and draft or published state in the user's language. Link the actual export or returned protected publication URL. Distinguish persistence from any visual or browser checks that did not run. Keep local credential and session identifiers private.

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

@@ -61,7 +61,7 @@ Save this JSON as `snapshot.json`, replacing its content with the requested arti
 }
 ```
 
-`metadata.description` and `files` are required even when empty. Content kind is `html`, `markdown`, or `text`. 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.
+`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
@@ -75,6 +75,20 @@ For `read`, `--out FILE --quiet` saves the returned response without printing su
 
 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.
@@ -158,6 +172,31 @@ The publication example applies only to an unpublished artifact. For an existing
 
 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

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

@@ -1,6 +1,6 @@
 ---
 name: artifacts-design
-description: Design the HTML document of a retained Artifact with embedded fonts, light and dark Catppuccin tokens, purposeful layout, and rendered checks. Use before writing or restyling HTML for the artifacts or artifacts-cli skills.
+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
@@ -9,6 +9,8 @@ The calling skill owns the snapshot, size limit, and save workflow. This skill o
 
 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.
@@ -49,7 +51,7 @@ After the HTML file is complete, embed the fonts it names:
 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 embeds only the families the page names and adds italic faces only for `font-style: italic`, `<em>`, `<i>`, or `<cite>`. 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.
+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
 
@@ -77,6 +79,14 @@ Give the `<title>` a specific name of two to four words, or the name the user al
 
 ## 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).