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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yerson Argote
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,217 @@
-# Temporary Holding Version
+# Artifacts CLI reference
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `artifacts` Node CLI reads and writes retained artifacts through REST. It prints JSON results to stdout and diagnostics to stderr. Offline skills commands print plain text. Node 24 or later is required. Its private credential database uses Node's experimental built-in SQLite API.
+
+The `@yargote/artifacts-cli` package exposes the `artifacts` binary as compiled ESM JavaScript. Its client and contracts dependencies install automatically. Repository development uses `pnpm artifacts` with the same command syntax.
+
+## Install the beta
+
+Use Node 24 or later. The beta targets macOS and Linux. Windows has not been verified.
+
+Choose one persistent installation:
+
+```sh
+npm install --global @yargote/artifacts-cli@0.1.0-beta.2
+# Or, with pnpm and an existing global bin directory on PATH:
+pnpm add --global @yargote/artifacts-cli@0.1.0-beta.2
+artifacts --version
+```
+
+If pnpm reports that no global bin directory exists, run `pnpm setup` and reopen your shell before installation.
+
+For one-off execution, pin the same version:
+
+```sh
+npx --yes @yargote/artifacts-cli@0.1.0-beta.2 --help
+pnpm dlx @yargote/artifacts-cli@0.1.0-beta.2 --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`:
+
+```sh
+export ARTIFACTS_SERVER='https://artifacts-mcp.yersonargotev.workers.dev/mcp'
+artifacts login
+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.
+
+Create `snapshot.json`:
+
+```json
+{
+	"metadata": { "title": "My first CLI artifact", "description": "Created through REST" },
+	"content": { "kind": "text", "text": "Hello from the Artifacts CLI." },
+	"files": []
+}
+```
+
+```sh
+artifacts create --snapshot snapshot.json
+artifacts list --limit 5
+```
+
+The create result contains `artifactId` and `headRevisionId`. Use those values to read, publish, and export the exact revision:
+
+```sh
+artifacts read ARTIFACT_ID
+artifacts publish ARTIFACT_ID --revision REVISION_ID --expected-version 0
+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.
+
+## Upgrade or uninstall
+
+Install another exact version with the same package manager to change the executable version. Credentials and retained operation files live outside the package installation and remain available.
+
+```sh
+npm uninstall --global @yargote/artifacts-cli
+# Or:
+pnpm remove --global @yargote/artifacts-cli
+```
+
+Run `artifacts logout` before uninstalling if you want to clear credentials. Uninstalling does not delete retained operations.
+
+## Server and local state
+
+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.
+
+`--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.
+
+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 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_ACCESS_TOKEN` supplies an access token for automation. It does not require local login. Tokens are never command arguments or retained operation fields.
+
+The private `credentials.sqlite` file stores credentials. The separate `credentials-lock.sqlite` file contains no credentials and holds a SQLite write lock to serialize refresh and logout across processes. A committed uncertainty marker in the data file survives process death, while SQLite releases the lock. Login and logout generations prevent a late browser callback from restoring signed-out credentials. An uncertain refresh requires login.
+
+## Command syntax
+
+`artifacts --help` prints this command reference. `artifacts --version` prints the installed package version without requiring a server or login.
+
+```text
+artifacts login [--no-browser]
+artifacts logout
+artifacts whoami
+artifacts create --snapshot FILE [--request-id ID] [--response full|compact]
+artifacts create --command FILE
+artifacts list [--limit N] [--cursor CURSOR]
+artifacts read ID [--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
+artifacts edit ID --changes FILE [--request-id ID]
+artifacts history ID [--limit N] [--before-sequence N] [--summary]
+artifacts publish ID --revision REV --expected-version N [--request-id ID]
+artifacts publish [ID] --command FILE
+artifacts export ID --revision REV --out FILE
+artifacts retry REQUEST_ID
+artifacts skills [list]
+artifacts skills get NAME [--full]
+artifacts skills get --all [--full]
+artifacts skills path [NAME]
+artifacts skills install [NAME] [--agent claude] [--global] [--force]
+```
+
+Global `--server RESOURCE` and `--state-dir DIR` options can appear before or after the command. Options cannot be repeated. Unknown options and options for another command fail before submission.
+
+## Bundled skills
+
+Check `artifacts --help` for `skills` support. The published `0.1.0-beta.1` package predates this command group. These commands describe the current source and packages built from it.
+
+`artifacts skills` and `artifacts skills list` print each bundled skill's name and description, separated by a tab. The initial catalog contains `artifacts-cli`. Its complete source directory is bundled with the CLI, so the instructions match the installed version and work offline.
+
+`artifacts skills get artifacts-cli` prints the complete `SKILL.md` without headers or changes to its bytes. `--full` includes every bundled reference and template. Each file starts with a catalog-relative marker such as `=== artifacts-cli/references/commands.md ===`. `artifacts skills get --all` prints every `SKILL.md` with these markers. Add `--full` to include every skill's support files.
+
+`artifacts skills path` prints the absolute bundled catalog directory. Add a skill name to print that skill's directory. These paths belong to the CLI package and do not depend on the current directory.
+
+Install a discovery skill for an agent with one of these commands.
+
+| Command | Destination |
+| --- | --- |
+| `artifacts skills install` | `./.agents/skills/artifacts-cli/SKILL.md` |
+| `artifacts skills install --agent claude` | `./.claude/skills/artifacts-cli/SKILL.md` |
+| `artifacts skills install --global` | `~/.agents/skills/artifacts-cli/SKILL.md` |
+| `artifacts skills install --agent claude --global` | `~/.claude/skills/artifacts-cli/SKILL.md` |
+
+The optional name defaults to `artifacts-cli`. The default destination always uses `.agents`, even if `.claude` already exists. Only explicit `--agent claude` selects `.claude`. Local paths resolve from the current directory. Global paths resolve from the user's home directory.
+
+The command prints the absolute destination. It leaves identical files unchanged, including their modification time. A differing file requires `--force`. Forced installation replaces only `SKILL.md` and preserves neighboring files. A directory or symbolic link at `SKILL.md` is rejected.
+
+The discovery file instructs the agent to run `artifacts skills get artifacts-cli --full` and follow the returned instructions. It contains no copied workflow or fixed package path. After a CLI upgrade, the same discovery command loads that installed version's skill.
+
+## Artifact input and output
+
+Create and update snapshot files contain the complete domain snapshot.
+
+```json
+{
+	"metadata": { "title": "Example", "description": "A retained document", "custom": { "team": "design" } },
+	"content": { "kind": "html", "text": "<h1>Example</h1>" },
+	"files": [{ "path": "data.txt", "mediaType": "text/plain", "encoding": "utf8", "data": "retained attachment" }]
+}
+```
+
+`read --out FILE` saves the returned artifact JSON and also prints it to stdout. Add `--quiet` to suppress successful stdout while saving the same bytes for the selected response mode. `--quiet` is available only for `read` and requires a nonempty `--out FILE`. Errors still go to stderr and exit with code `1`.
+
+Check installed help for `--quiet` support. Version `0.1.0-beta.1` predates this option. With that version, `artifacts read ARTIFACT_ID --out saved.json > /dev/null` suppresses stdout while preserving stderr and the exit status.
+
+A default full read contains the complete snapshot under `revision.snapshot`. `export --out FILE` saves the exact ZIP and prints its filename, local path, media type, SHA-256, and byte count. Output files use exclusive creation and never overwrite an existing path.
+
+History defaults to complete revisions. `--summary` returns revision metadata and attachment summaries. `--before-sequence` continues a page. `list --cursor` continues an artifact list.
+
+## 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.
+
+A complete update command has this shape.
+
+```json
+{
+	"requestId": "reviewed-update-001",
+	"artifactId": "artifact-id",
+	"expectedRevisionId": "reviewed-revision-id",
+	"snapshot": {
+		"metadata": { "title": "Reviewed title", "description": "Complete replacement" },
+		"content": { "kind": "text", "text": "Reviewed text" },
+		"files": []
+	}
+}
+```
+
+`edit ID --changes FILE` reads the current snapshot, merges partial `metadata` and `content` changes, and retains the resulting complete update. An explicit `files` array replaces the attachments. Omitted fields and attachments are preserved.
+
+```json
+{ "metadata": { "title": "Changed title" }, "content": { "text": "Changed text" } }
+```
+
+Publish always selects an immutable revision. `--expected-version 0` expects no existing publication. Later publication commands require the current publication version.
+
+## Recovery
+
+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.
+
+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.
+
+Commands exit with code `1` on failure and print a JSON error to stderr. Server errors preserve their HTTP status, code, and conflict details. Successful JSON stdout contains no progress messages or credentials.
+
+## License and support
+
+This package is MIT licensed. The client and contracts packages have their own MIT licenses. This does not license the private Artifacts application repository. Contact your Artifacts service administrator with `artifacts --version`, Node and package-manager versions, and a redacted error. Never include credentials or the contents of `credentials.sqlite`.

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@yargote/artifacts-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.2",
+  "private": false,
+  "type": "module",
+  "description": "Command-line client for the Artifacts REST API.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yersonargotev/artifacts.git",
+    "directory": "apps/cli"
+  },
+  "homepage": "https://github.com/yersonargotev",
+  "bugs": {
+    "url": "https://github.com/yersonargotev"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "artifacts": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "skills"
+  ],
+  "dependencies": {
+    "@yargote/artifacts-contracts": "0.1.0-beta.2",
+    "@yargote/artifacts-client": "0.1.0-beta.2",
+    "openid-client": "6.8.8",
+    "zod": "4.6.5"
+  },
+  "artifactsSkills": [
+    "artifacts-cli"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta",
+    "provenance": false
+  }
+}

package/skills/artifacts-cli/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: artifacts-cli
+description: Create, revise, inspect, publish, and export retained Artifacts through the artifacts CLI and REST API. Use when the user chooses the CLI or a terminal workflow for Artifacts. Exclude generic build artifacts and unrelated local files.
+---
+
+# Manage retained Artifacts with the CLI
+
+Use the installed `artifacts` executable. Run `artifacts --help` and read [the command workflow](references/commands.md) before the first operation. With bundled skills support, `artifacts skills get artifacts-cli --full` returns this skill and its complete command reference. If the executable is unavailable, report that prerequisite. Do not substitute database writes or invent CLI results.
+
+## 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.
+
+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.
+
+## Prepare retained content
+
+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.
+
+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.
+
+Finish requested visual and interaction 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
+
+Create a draft when the user asks to save new content. Use a complete snapshot file and retain the CLI's request ID and operation record until the result is verified.
+
+Resolve an existing artifact by its supplied ID, an observed publication URL, or a paginated list. If several results match, ask which one the user means. Read its current full snapshot before editing. Preserve metadata, custom JSON, content fields, and attachments the user did not ask to change.
+
+Use `edit` for partial changes that preserve omitted fields. Use `update` for a complete next snapshot with the observed `headRevisionId` as its expected revision. Changing the attachment list replaces that inventory; an empty list removes all attachments. An update creates a retained revision and does not change the published revision.
+
+## Publish deliberately
+
+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.
+
+## Recover an uncertain write
+
+The CLI retains complete mutations before sending them. After a connection failure or uncertain result, use `retry` with that retained request ID once. Keep the same resource, owner, request ID, response mode, snapshot, and expected versions. Do not rerun a convenience edit or generate a new ID to repeat an operation whose outcome is unknown.
+
+If the retry remains unavailable, report the uncertainty and retain the recovery record. A conflict stops the failed operation. Read the current state and report the concurrent change. Do not replace expected versions to force a write. A changed operation needs a deliberate new command and request ID.
+
+A `request_conflict` means the ID was used with different arguments. Do not describe it as success. Authentication, validation, missing-artifact, and service failures likewise remain failures.
+
+## 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.
+
+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.
+
+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

@@ -0,0 +1,156 @@
+# Command workflow
+
+Check the installed `artifacts --help` before use. These examples use the canonical resource selected for the task. `ARTIFACT_ID` and `REVISION_ID` stand for IDs observed in actual command output.
+
+## Inspect and install bundled skills
+
+When installed help lists `skills`, use these commands without a server or login.
+
+```sh
+artifacts skills
+artifacts skills get artifacts-cli --full
+artifacts skills get --all --full
+artifacts skills path artifacts-cli
+artifacts skills install
+artifacts skills install --agent claude --global
+```
+
+`skills` and `skills list` list names and descriptions. Plain `skills get artifacts-cli` returns the complete `SKILL.md`. `--full` includes references and templates with relative file paths. `skills path` without a name returns the catalog directory.
+
+Installation defaults to `artifacts-cli` in `.agents/skills` under the current directory. `--agent claude` selects `.claude/skills`. `--global` selects the user's home directory. Existing agent directories do not affect the default. The discovery file instructs the agent to load the installed CLI's complete instructions with `artifacts skills get artifacts-cli --full`. Installation reports the absolute path, leaves identical files unchanged, and requires `--force` to replace differing files.
+
+The published `0.1.0-beta.1` package predates skills commands. Do not assume support without checking help.
+
+## Authenticate
+
+```sh
+export ARTIFACTS_SERVER=https://artifacts.example.test/mcp
+artifacts login
+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.
+
+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.
+
+## Create a complete snapshot
+
+Save this JSON as `snapshot.json`, replacing its content with the requested artifact.
+
+```json
+{
+  "metadata": {
+    "title": "Project note",
+    "description": "A retained note",
+    "custom": { "source": "requested content" }
+  },
+  "content": {
+    "kind": "html",
+    "text": "<!doctype html><html lang=\"en\"><meta charset=\"utf-8\"><title>Project note</title><main><h1>Project note</h1><p>Retained content.</p></main></html>"
+  },
+  "files": [
+    {
+      "path": "notes.txt",
+      "mediaType": "text/plain",
+      "encoding": "utf8",
+      "data": "Retained attachment.\n"
+    }
+  ]
+}
+```
+
+`metadata.description` and `files` are required even when empty. Content kind is `html`, `markdown`, 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.
+
+```sh
+artifacts create --snapshot snapshot.json
+artifacts list --limit 25
+artifacts read ARTIFACT_ID --out saved.json --quiet
+```
+
+Keep the request ID printed for the mutation. Successful JSON goes to stdout; diagnostics and recovery instructions go to stderr. Exit zero indicates command success. A nonzero exit must be inspected before claiming completion.
+
+For `read`, `--out FILE --quiet` saves the returned response without printing successful JSON. It requires a nonempty output path. It preserves the selected response mode, so use the default full response for snapshot verification. Errors still go to stderr and exit nonzero. Without `--quiet`, `read --out FILE` also prints the response to stdout.
+
+Check installed help for `--quiet` support before running these examples. Older versions, including `0.1.0-beta.1`, can suppress stdout with `artifacts read ARTIFACT_ID --out saved.json > /dev/null`. This redirection preserves stderr and the command's exit status. Use the same fallback for the revision reads below.
+
+## Edit without losing retained data
+
+For a title change, save `changes.json` with only the requested field.
+
+```json
+{ "metadata": { "title": "Reviewed project note" } }
+```
+
+```sh
+artifacts edit ARTIFACT_ID --changes changes.json
+artifacts read ARTIFACT_ID --out current.json --quiet
+```
+
+For a complete replacement, read the current head, preserve untouched data in `next-snapshot.json`, and use that observed revision.
+
+```sh
+artifacts update ARTIFACT_ID --snapshot next-snapshot.json --expected-revision REVISION_ID
+```
+
+A complete command file can preserve a caller-owned request ID, snapshot, and expected revision. Use `artifacts create --command create.json`, `artifacts update --command update.json`, or `artifacts publish --command publish.json`. Do not add `response: "full"` to an existing command that omitted it. Optional response modes affect exact mutation identity.
+
+Command files contain the command itself, without the CLI's retained-operation wrapper.
+
+| Command | Required JSON fields |
+| --- | --- |
+| `create` | `requestId`, `snapshot` |
+| `update` | `requestId`, `artifactId`, `expectedRevisionId`, `snapshot` |
+| `publish` | `requestId`, `artifactId`, `revisionId`, `expectedPublicationVersion` |
+
+`requestId` is a caller-chosen string of 8 to 128 characters. Create and update also accept optional `response` with value `full` or `compact`. This complete update example replaces a snapshot. Substitute the observed IDs and preserve all required content and attachments in its `snapshot`.
+
+```json
+{
+  "requestId": "reviewed-update-001",
+  "artifactId": "OBSERVED_ARTIFACT_ID",
+  "expectedRevisionId": "OBSERVED_HEAD_REVISION_ID",
+  "snapshot": {
+    "metadata": { "title": "Reviewed project note", "description": "A retained note" },
+    "content": { "kind": "text", "text": "Reviewed content." },
+    "files": []
+  }
+}
+```
+
+Create uses the same `requestId` and complete `snapshot` fields without artifact or expected-revision IDs. A complete publication command has this shape. Replace zero with the observed publication version when already published.
+
+```json
+{
+  "requestId": "reviewed-publish-001",
+  "artifactId": "OBSERVED_ARTIFACT_ID",
+  "revisionId": "SELECTED_REVISION_ID",
+  "expectedPublicationVersion": 0
+}
+```
+
+## Inspect history and publish
+
+```sh
+artifacts history ARTIFACT_ID --summary
+artifacts read ARTIFACT_ID --revision REVISION_ID --out historical.json --quiet
+artifacts publish ARTIFACT_ID --revision REVISION_ID --expected-version 0
+```
+
+The publication example applies only to an unpublished artifact. For an existing publication, replace zero with the `publication.version` observed in a current read. After publishing, read again and compare current publication with the returned receipt.
+
+History returns `nextBeforeSequence`; pass it as `--before-sequence N` to continue. List returns `nextCursor`; pass it as `--cursor CURSOR`. Do not substitute an offset or assume that one page contains everything.
+
+## Retry and export
+
+```sh
+artifacts retry REQUEST_ID
+artifacts export ARTIFACT_ID --revision REVISION_ID --out artifact.zip
+```
+
+`retry` loads the saved complete operation. It does not prepare a new edit or change expected versions. Keep the record after an uncertain result. The server checks current authority before replaying an original receipt.
+
+`read --out` and `export --out` create files exclusively. Use a new destination if one already exists. Do not delete an existing output merely to rerun an example.
+
+The archive contains `artifact.json`, `content.html`, `content.md`, or `content.txt`, and attachments under `files/`. Inspect the manifest's artifact and revision IDs, content, and required attachment bytes. Exporting the same retained revision through REST, MCP, or the panel must yield identical ZIP bytes.

package/src/auth.d.ts

@@ -0,0 +1,18 @@
+import { type Identity } from '@yargote/artifacts-contracts/http';
+export declare function login(options: {
+    resource: string;
+    stateDir: string;
+    noBrowser: boolean;
+    onAuthorizationUrl: (url: string) => void;
+}): Promise<Identity>;
+export declare function accessToken(options: {
+    resource: string;
+    stateDir: string;
+}): Promise<string>;
+export declare function logout(options: {
+    resource: string;
+    stateDir: string;
+}): Promise<{
+    signedOut: true;
+    remoteRevocation: 'confirmed' | 'unconfirmed' | 'not-needed';
+}>;