@yargote/artifacts-cli 0.1.0-beta.6 → 0.1.0-beta.8

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.6
+npm install --global @yargote/artifacts-cli@0.1.0-beta.8
 # Or, with pnpm and an existing global bin directory on PATH:
-pnpm add --global @yargote/artifacts-cli@0.1.0-beta.6
+pnpm add --global @yargote/artifacts-cli@0.1.0-beta.8
 artifacts --version
 ```
 
@@ -22,23 +22,26 @@ 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.6 --help
-pnpm dlx @yargote/artifacts-cli@0.1.0-beta.6 --help
+npx --yes @yargote/artifacts-cli@0.1.0-beta.8 --help
+pnpm dlx @yargote/artifacts-cli@0.1.0-beta.8 --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`:
+Check `artifacts --help` for saved-connection support. With an older package that requires a server on every command, keep `ARTIFACTS_SERVER` set to the selected REST resource.
+
+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'
-artifacts login
+artifacts login --server 'https://artifacts-api.yersonargotev.workers.dev'
 artifacts whoami
 ```
 
-Login opens browser authorization. After you approve access, `whoami` prints JSON with your user ID and scopes. Use `artifacts login --no-browser` to open the printed authorization URL yourself on the same machine.
+Login opens browser authorization. After you approve access and the CLI verifies your identity, it saves the resolved REST resource in private state. A new terminal can run `artifacts whoami` without a server option or environment variable. It prints JSON with your user ID and scopes.
+
+Use `artifacts login --no-browser` to open the printed authorization URL yourself on the same machine. This manual flow saves the connection only after identity verification succeeds.
 
 Create `snapshot.json`:
 
@@ -82,19 +85,33 @@ 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` overrides `ARTIFACTS_SERVER`, which overrides the connection saved by the last successful login in the selected state directory.
+
+An ordinary command override applies to that command and does not replace the saved connection. A later successful login replaces it with the verified canonical REST resource. A failed login to another server preserves the previous selection and its credentials.
+
+Login also accepts an MCP resource that advertises its REST resource. Use the configured `API_URL` origin to call REST under `/v1`.
 
-`--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.
+Without an override or saved connection, run `artifacts login --server RESOURCE` first. The CLI has no production default and does not rewrite the supplied URL. Existing installations keep their exact-resource credentials, but must complete a successful login to save a connection.
+
+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. Each state directory has its own saved connection and credential profiles. Credentials and the saved connection share one private database, 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.
 
 HTTPS is required except for HTTP on the exact loopback hosts `localhost`, `127.0.0.1`, and `[::1]`. Server URLs cannot contain credentials, a query, or a fragment.
 
 ## Authentication
 
-`artifacts login --server RESOURCE` verifies protected-resource metadata, registers a public native OAuth client, and opens browser authorization with PKCE. `--no-browser` prints the authorization URL for manual navigation. The loopback callback listener starts before browser navigation. Login requests read, write, and publication scopes. Client registration is reused for the profile.
+`artifacts login --server RESOURCE` verifies protected-resource metadata. If a resource advertises `artifacts_rest_resource`, the relation may name the same resource or one distinct REST resource. Login verifies metadata for a distinct resource and prints its REST URL to stderr. The distinct resource may omit the relation or name itself, but cannot name another resource. After identity verification, login saves that REST URL for later commands. An existing `ARTIFACTS_SERVER` still overrides it. Unset the variable to use the saved connection. Login anonymously checks `<resource>/v1/identity` before registering a public native OAuth client and opening browser authorization with PKCE. This check confirms REST compatibility. Login verifies your identity again with the received token before atomically saving credentials and the connection.
+
+Errors identify the phase, method, endpoint, and HTTP status when a response exists. Network failures have no HTTP status. If the compatibility check fails, confirm the configured REST URL with your service administrator. A valid MCP metadata document alone does not establish REST compatibility.
+
+`--no-browser` runs the same checks and prints the authorization URL for manual navigation. The loopback callback listener starts before browser navigation. Login requests read, write, and publication scopes. Client registration is reused for the profile.
 
 `artifacts whoami` returns the verified user, session, OAuth client, and scopes.
 
-`artifacts logout` clears local credentials and attempts to revoke the refresh token. Its JSON contains `signedOut: true` and `remoteRevocation` with `confirmed`, `unconfirmed`, or `not-needed`. Issued access JWTs can remain valid until expiry or central-session revocation.
+`artifacts logout` clears local credentials and attempts to revoke the refresh token. It preserves the saved connection, so `artifacts login` can reuse the server without another URL. Its JSON contains `signedOut: true` and `remoteRevocation` with `confirmed`, `unconfirmed`, or `not-needed`. Issued access JWTs can remain valid until expiry or central-session revocation.
 
 `ARTIFACTS_ACCESS_TOKEN` supplies an access token for automation. It does not require local login. Tokens are never command arguments or retained operation fields.
 
@@ -108,12 +125,14 @@ The private `credentials.sqlite` file stores credentials. The separate `credenti
 artifacts login [--no-browser]
 artifacts logout
 artifacts whoami
-artifacts create --snapshot FILE [--project NAME] [--request-id ID]
+artifacts create --snapshot FILE [--project NAME] [--slug SLUG] [--request-id ID]
                  [--response full|compact]
 artifacts create --command FILE
 artifacts list [--limit N] [--cursor CURSOR] [--project NAME]
 artifacts projects
 artifacts read ID [--revision REV] [--response full|compact] [--out FILE [--quiet]]
+artifacts read --slug SLUG [--project NAME] [--revision REV] [--response full|compact]
+               [--out FILE [--quiet]]
 artifacts update ID --snapshot FILE --expected-revision REV [--request-id ID]
                  [--response full|compact]
 artifacts update [ID] --command FILE
@@ -200,6 +219,18 @@ 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.
 
+## Slugs
+
+A slug names a page within its project, so `read` can find it without its ID. `create --slug SLUG` sets it. 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 complete create command file can include the same optional `slug` field.
+
+```sh
+artifacts create --snapshot snapshot.json --project Mi-Wiki --slug concepts/rag
+artifacts read --project mi-wiki --slug concepts/rag
+artifacts read --slug index
+```
+
+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` reads without `--project`. `read` takes exactly one of an ID or `--slug`, and `--project` applies only with `--slug`. A used slug fails `create` with `slug_conflict`, status 409, and the holder's `artifactId`. A locator with no artifact fails with `not_found`. Every artifact read and list item includes `slug`, a name or null. Version `0.1.0-beta.7` and earlier reject responses that include `slug` with `invalid_response`.
+
 ## Share publication access
 
 These commands are available from `0.1.0-beta.6`. Check installed help for support.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yargote/artifacts-cli",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.8",
   "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.6",
-    "@yargote/artifacts-client": "0.1.0-beta.6",
+    "@yargote/artifacts-contracts": "0.1.0-beta.8",
+    "@yargote/artifacts-client": "0.1.0-beta.8",
     "openid-client": "6.8.8",
     "zod": "4.6.5"
   },

package/skills/artifacts-cli/SKILL.md

@@ -9,7 +9,7 @@ Use the installed `artifacts` executable. Run `artifacts --help` and read [the c
 
 ## Select the account and resource
 
-Use the resource selected by the user or the existing `ARTIFACTS_SERVER` environment value. Pass `--server RESOURCE` or set `ARTIFACTS_SERVER` for service commands. Skills, help, and version commands work offline without a server or login. Login does not set an implicit default. A resource is the canonical OAuth URL, such as `https://artifacts.example.test/mcp`. REST routes are below that resource at `/v1`. Do not infer a production connection from an example or silently switch to a local server.
+Use the resource selected by the user. Service commands select `--server RESOURCE` before `ARTIFACTS_SERVER`, then the connection saved by a successful login in the selected private state directory. Ordinary command overrides do not replace that connection. Skills, help, and version commands work offline without a server or login. Check installed help for saved-connection support. A resource is the canonical OAuth URL, such as `https://artifacts.example.test/mcp`. REST routes are below that resource at `/v1`. Do not infer a production connection from an example or silently switch to a local server.
 
 Run `artifacts whoami` before the first mutation when the current identity is not established. Keep the selected resource and owner consistent throughout one operation. If login is needed, use `artifacts login --server RESOURCE`. The user authenticates in the browser. Do not collect their password or read another application's credentials. Never put tokens in command arguments, operation files, logs, or the final reply.
 
@@ -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
 
@@ -35,6 +35,8 @@ Use `edit` for partial changes that preserve omitted fields. Use `update` for a
 
 When the user names a project for new content, add `--project NAME` to `create`. Run `artifacts projects` first when an existing project may already fit. A name matching an existing project regardless of letter case joins it and keeps the stored spelling. Do not invent a project the user did not ask for. Use `list --project NAME` to find artifacts in a project.
 
+When the user names a page, add `--slug SLUG` such as `concepts/rag` to `create`, and read it later with `read --project NAME --slug SLUG`, or `read --slug SLUG` for an unfiled page, instead of listing for its ID. Omit the `.md` suffix. A `slug_conflict` error names the `artifactId` that already holds the slug in that project.
+
 Use `move ID --project NAME` to file an existing artifact under a project and `move ID --no-project` to remove it from one. A move changes only the project. It creates no revision and leaves the publication unchanged. It is a retained mutation, so recover an uncertain move with `retry`. Verify it with `read` or `list --project NAME`. A project disappears when its last artifact leaves it.
 
 ## Publish deliberately
@@ -63,10 +65,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

@@ -24,16 +24,17 @@ The published `0.1.0-beta.1` package predates skills commands. Do not assume sup
 ## Authenticate
 
 ```sh
-export ARTIFACTS_SERVER=https://artifacts.example.test/mcp
-artifacts login
+artifacts login --server https://artifacts.example.test/mcp
 artifacts whoami
 ```
 
-Replace the example with the selected resource before executing it. Service commands read `ARTIFACTS_SERVER` or an explicit `--server RESOURCE`. Login does not save a default resource. `--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.
+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. 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.
+`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
 
@@ -61,7 +62,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 +76,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.
@@ -91,6 +106,20 @@ A project name contains 1 to 80 characters after trimming and NFC normalization,
 
 `move` takes exactly one of `--project NAME` or `--no-project` and prints `{ "artifactId": "...", "project": "Archive" }`, or `null` for the project after `--no-project`. 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
+```
+
+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`. A move keeps the slug and fails with `slug_conflict` when the destination project already uses it.
+
 ## Edit without losing retained data
 
 For a title change, save `changes.json` with only the requested field.
@@ -120,7 +149,7 @@ Command files contain the command itself, without the CLI's retained-operation w
 | `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. This complete update example replaces a snapshot. Substitute the observed IDs and preserve all required content and attachments in its `snapshot`.
+`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
 {
@@ -179,6 +208,10 @@ Share with `--notify` to request one email attempt. Access succeeds when mail is
 
 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).