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

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.4
+npm install --global @yargote/artifacts-cli@0.1.0-beta.6
 # Or, with pnpm and an existing global bin directory on PATH:
-pnpm add --global @yargote/artifacts-cli@0.1.0-beta.4
+pnpm add --global @yargote/artifacts-cli@0.1.0-beta.6
 artifacts --version
 ```
 
@@ -22,8 +22,8 @@ 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.4 --help
-pnpm dlx @yargote/artifacts-cli@0.1.0-beta.4 --help
+npx --yes @yargote/artifacts-cli@0.1.0-beta.6 --help
+pnpm dlx @yargote/artifacts-cli@0.1.0-beta.6 --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.
@@ -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
 
@@ -124,6 +124,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 +200,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 +252,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.4",
+  "version": "0.1.0-beta.6",
   "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.4",
-    "@yargote/artifacts-client": "0.1.0-beta.4",
+    "@yargote/artifacts-contracts": "0.1.0-beta.6",
+    "@yargote/artifacts-client": "0.1.0-beta.6",
     "openid-client": "6.8.8",
     "zod": "4.6.5"
   },

package/skills/artifacts-cli/SKILL.md

@@ -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
 

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

@@ -158,6 +158,27 @@ 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.
+
 ## Retry and export
 
 ```sh

package/skills/artifacts-design/SKILL.md

@@ -9,9 +9,15 @@ 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.
 
-## Start from the starter
+## Choose the composition
 
-Copy the `<style>` block of [the starter](templates/starter.html) into the new document. It defines the color, font, and spacing tokens and the shared primitives: eyebrow and label, lede, summary strip, pills, expandable rows, panel, note, table, filter bar, and footer. Delete primitives the page does not use. Derive every new color and type decision from its tokens.
+Before writing HTML, identify the reader's task, the facts and assets available, and what the reader should understand or do first. Use supplied facts. Label illustrative inputs and assumptions, and leave unavailable evidence absent.
+
+Choose the element that carries the answer: a comparison, a diagram, a sequence, a chart, or a result beside its inputs. Give it the most space and put its supporting text nearby. If the same composition would fit an unrelated topic unchanged, use the subject's actual relationships or quantities to make the structure more specific. A report can be dense, an explanation can use large scenes, and a calculator can fit on one screen. Do not impose a hero, a section count, or a word budget.
+
+## Use the starter's tokens
+
+Copy the `<style>` block of [the starter](templates/starter.html) into the new document. It defines the color, font, and spacing tokens and shared components: contextual text and labels, lede, summary strip, pills, expandable rows, panel, note, table, filter bar, and footer. Delete components the page does not use. Derive every new color and type decision from its tokens.
 
 The starter supplies a vocabulary, not a layout. Compose the body for the reader's task:
 
@@ -31,11 +37,11 @@ Open in a complete state with the user's real data. Never ship an empty shell or
 Use the bundled faces through the starter's tokens:
 
 - `--f-display` is Bricolage Grotesque. Use it for `h1` to `h3` and large figures only.
-- `--f-body` is Public Sans for running text and controls.
-- `--f-mono` is JetBrains Mono for code, identifiers, table headers, eyebrows, and labels.
+- `--f-body` is Public Sans for running text, controls, labels, and table headers.
+- `--f-mono` is JetBrains Mono for code and identifiers. Use it for measurements when it helps the reader read or align them.
 - Newsreader is an optional reading face. For a long essay or editorial guide, set `--f-body` to `"Newsreader",Charter,Georgia,serif` and keep Public Sans for controls.
 
-Keep the starter's scale: `h1` at `clamp(28px,4vw,40px)`, body at 15 to 16 px with a 1.55 line height, uppercase mono labels at 11 to 12 px with `.06em` tracking, and `text-wrap: balance` on headings. Use `font-variant-numeric: tabular-nums` wherever digits align.
+Start with `h1` at `clamp(28px,4vw,40px)` and body at 15 to 16 px with a 1.55 line height. Set labels in the body face at 12 to 13 px, in sentence case without added tracking. Adjust the scale for the document's main visual and reading density. Keep `text-wrap: balance` on headings and `font-variant-numeric: tabular-nums` wherever digits align.
 
 After the HTML file is complete, embed the fonts it names:
 
@@ -59,7 +65,7 @@ The starter follows the viewer's system theme. Light uses Catppuccin Latte and d
 
 - Center one `.wrap` column at `--width` with `max(16px, env(safe-area-inset-*))` side gutters. Space siblings with grid or flex `gap`.
 - Use borders and fills by role. A summary strip, a table, and one panel can each earn a surface. Running text and headings sit on the page.
-- Mark structure that is true: an eyebrow names the source or scope, a label names a field, and numbering appears only for real sequences.
+- Use an eyebrow only for source or scope information the heading does not already give. A label names a field, and numbering appears only for real sequences.
 - Encode attention in form. A row that needs action gets a pill or a muted closed state, not only a different word.
 - Put wide code and diagrams in their own `overflow-x: auto` container. Use a `<table>` only for short records that stay readable when scrolled; use expandable rows for records with long text. The page itself never scrolls sideways at 375 px.
 - Draw diagrams in inline SVG with token colors and labels inside the view box. For icons, use inline Tabler outline SVGs with `currentColor`.
@@ -71,6 +77,6 @@ Give the `<title>` a specific name of two to four words, or the name the user al
 
 ## Check the rendered page
 
-Run the [interface checks](references/interface-checks.md) when browser tools are available. Render at 375 px and 1280 px in both light and dark. Confirm that the fonts loaded, nothing overflows, and every control changes something visible. Fix what you see once, then save. Report checks you could not run.
+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).

package/skills/artifacts-design/THIRD-PARTY-NOTICES.md

@@ -119,6 +119,37 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## Hallmark
+
+The composition guidance in [SKILL.md](SKILL.md) and the review categories in
+[references/interface-checks.md](references/interface-checks.md) adapt ideas from
+[Hallmark](https://github.com/Nutlope/hallmark), reviewed on 2026-10-24.
+[Upstream license](https://github.com/Nutlope/hallmark/blob/main/LICENSE).
+
+```text
+MIT License
+
+Copyright (c) 2026 Hallmark contributors
+
+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.
+```
+
 ## Bundled fonts
 
 The files in [fonts](fonts) are the Latin subsets of Bricolage Grotesque, Public Sans, JetBrains Mono, and Newsreader, as served by Google Fonts on 2026-10-17. Each is licensed under the SIL Open Font License, Version 1.1. The copyright lines and the complete license text are in [fonts/OFL.txt](fonts/OFL.txt).

package/skills/artifacts-design/references/interface-checks.md

@@ -31,7 +31,9 @@ Keep input-driven calculations in document memory. Use labeled controls without
 
 Keep filters and tabs local to the document. Do not depend on host URL synchronization, router packages, persistent storage, network requests, or remote fonts. Embed fonts and other required assets as `data:` URIs within the snapshot budget.
 
-## Check the result
+## Required checks
+
+Check content fidelity, sandbox compatibility, and usable behavior regardless of the composition. Preserve supplied facts, units, qualifications, and requested controls. For a visual revision, record the existing content and actions before editing and confirm that they still work afterward.
 
 When browser tools are available, inspect the generated document at a narrow viewport around 375 px and a wide viewport around 1280 px, or the user's requested sizes. Verify that body content fits, labels remain legible, and only intentionally wide tables or code regions scroll locally. Check the artifact itself rather than relying on the surrounding application's appearance.
 
@@ -41,10 +43,18 @@ Finish when each relevant check passes or an unavailable check is identified. Fi
 
 For a requested audit, identify each issue by element or source location and state its correction. Distinguish source inspection from browser verification. Do not turn ordinary artifact delivery into an unsolicited audit report.
 
+## Visual judgment
+
+Check whether the main visual or result answers the reader's task, whether its labels stay close to what they describe, and whether the reading order is clear at both widths. Read the headings alone and check that they describe this document's content. Remove containers and repeated labels that add no grouping or information.
+
+Choose density, alignment, cards, and section rhythm for the content. A long report, a diagram sequence, and a calculator need different compositions. These choices are defaults to reconsider with a concrete reason, not automatic failures. Keep the user's requested style and content. Do not remove evidence or simplify away a qualification to meet an aesthetic preference.
+
 ## Sources
 
 Adapted on 2026-10-14 from [Emil Kowalski's design engineering skill](https://raw.githubusercontent.com/emilkowalski/skills/refs/heads/main/skills/emil-design-eng/SKILL.md) and [Vercel's web design guidelines skill](https://raw.githubusercontent.com/vercel-labs/agent-skills/refs/heads/main/skills/web-design-guidelines/SKILL.md).
 
 The accessibility and interface checks incorporate Vercel's Web Interface Guidelines `command.md` as local guidance. Its remote command workflow and output format are not required. The sandbox adaptations are specific to Artifacts.
 
+The composition workflow and the distinction between required checks and visual judgment draw on [Hallmark](https://github.com/Nutlope/hallmark), reviewed on 2026-10-24. This adaptation retains Artifacts' document types, palette, embedded fonts, and sandbox constraints.
+
 License notices are retained in [Third-party notices](../THIRD-PARTY-NOTICES.md).

package/skills/artifacts-design/templates/starter.html

@@ -47,7 +47,7 @@ code,kbd,pre{font-family:var(--f-mono);font-size:.86em}
 pre{margin:0;padding:14px 16px;background:var(--sunken);border-radius:8px;overflow-x:auto;line-height:1.5}
 :focus-visible{outline:2px solid var(--accent);outline-offset:2px}
 
-.eyebrow,.label{font:600 11.5px/1.2 var(--f-mono);letter-spacing:.06em;text-transform:uppercase;color:var(--muted)}
+.eyebrow,.label{font:600 12px/1.35 var(--f-body);color:var(--muted)}
 header{display:grid;gap:8px}
 .lede{color:var(--muted);max-width:68ch;font-size:16px}
 .prose{display:grid;gap:12px;max-width:68ch}
@@ -71,14 +71,14 @@ section{display:grid;gap:14px}
 
 .table{background:var(--surface);border:1px solid var(--line);border-radius:var(--radius);overflow-x:auto}
 table{width:100%;border-collapse:collapse;font-size:14px}
-th{font:600 11px/1.2 var(--f-mono);letter-spacing:.06em;text-transform:uppercase;color:var(--muted);text-align:left;padding:10px 14px;background:var(--sunken);border-bottom:1px solid var(--line);white-space:nowrap}
+th{font:600 12px/1.35 var(--f-body);color:var(--muted);text-align:left;padding:10px 14px;background:var(--sunken);border-bottom:1px solid var(--line);white-space:nowrap}
 td{padding:11px 14px;border-bottom:1px solid var(--line);vertical-align:top;font-variant-numeric:tabular-nums}
 tr:last-child td{border-bottom:0}
 td.num,th.num{text-align:right;white-space:nowrap}
 
 .rows{background:var(--surface);border:1px solid var(--line);border-radius:var(--radius);overflow:hidden}
 .rows-head,.row>summary{display:grid;grid-template-columns:var(--cols,88px minmax(0,2fr) minmax(0,1fr) minmax(0,1.4fr));gap:16px;padding:12px 16px;align-items:start}
-.rows-head{font:600 11px/1.2 var(--f-mono);letter-spacing:.06em;text-transform:uppercase;color:var(--muted);background:var(--sunken);border-bottom:1px solid var(--line)}
+.rows-head{font:600 12px/1.35 var(--f-body);color:var(--muted);background:var(--sunken);border-bottom:1px solid var(--line)}
 .row{border-bottom:1px solid var(--line)}
 .row:last-child{border-bottom:0}
 .row>summary{cursor:pointer;list-style:none}

package/src/index.js

@@ -6,7 +6,7 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { z } from 'zod';
-import { createSchema, moveSchema, publishSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { createSchema, listSharesSchema, moveSchema, publishSchema, shareSchema, unshareSchema, updateSchema } from '@yargote/artifacts-contracts';
 import { canonicalResource } from '@yargote/artifacts-contracts/http';
 import { createArtifactHttpClient, HttpError, prepareArtifactEdit } from '@yargote/artifacts-client';
 import { accessToken, login, logout } from "./auth.js";
@@ -46,6 +46,9 @@ Commands:
   export ID --revision REV --out FILE
   move ID --project NAME [--request-id ID]
   move ID --no-project [--request-id ID]
+  share ID --email EMAIL [--notify] [--request-id ID]
+  shares ID
+  unshare ID SHARE_ID [--request-id ID]
   retry REQUEST_ID
 
 Mutation command files contain the complete create, update, or publish JSON.
@@ -75,6 +78,7 @@ const commandOptions = {
     update: ['snapshot', 'expected-revision', 'request-id', 'response', 'command'],
     edit: ['changes', 'request-id'], history: ['limit', 'before-sequence', 'summary'],
     publish: ['revision', 'expected-version', 'request-id', 'command'],
+    share: ['email', 'notify', 'request-id'], shares: [], unshare: ['request-id'],
     export: ['revision', 'out'], move: ['project', 'no-project', 'request-id'], retry: [],
     skills: ['full', 'all', 'agent', 'global', 'force'],
 };
@@ -112,7 +116,7 @@ async function main() {
             summary: { type: 'boolean' }, out: { type: 'string' }, quiet: { type: 'boolean' },
             full: { type: 'boolean' }, all: { type: 'boolean' }, agent: { type: 'string' },
             global: { type: 'boolean' }, force: { type: 'boolean' },
-            project: { type: 'string' }, 'no-project': { type: 'boolean' },
+            project: { type: 'string' }, 'no-project': { type: 'boolean' }, email: { type: 'string' }, notify: { type: 'boolean' },
         },
     });
     const seen = new Set();
@@ -255,11 +259,18 @@ async function main() {
                 throw new UsageError('Specify exactly one of --project NAME or --no-project');
             return mutate({ kind: 'move', command: moveSchema.parse({ artifactId, requestId: values['request-id'] ?? randomUUID(), project: values.project ?? null }) });
         }
+        case 'share': return mutate({ kind: 'share', command: shareSchema.parse({ artifactId: argument(), requestId: values['request-id'] ?? randomUUID(), email: required('email'), ...(values.notify === undefined ? {} : { notify: values.notify }) }) });
+        case 'shares': return client.listShares(listSharesSchema.parse({ artifactId: argument() }));
+        case 'unshare': {
+            if (arguments_.length !== 2)
+                throw new UsageError('unshare requires two positional arguments');
+            return mutate({ kind: 'unshare', command: unshareSchema.parse({ artifactId: arguments_[0], shareId: arguments_[1], requestId: values['request-id'] ?? randomUUID() }) });
+        }
         case 'retry': {
             const requestId = argument();
             const owner = await client.identity();
             const operation = await loadOperation(stateDir, requestId, resource, owner.userId);
-            process.stderr.write(`Replaying retained ${operation.kind} operation ${requestId}. The result is its retained receipt and may differ from current state.\n`);
+            process.stderr.write(`Replaying retained ${operation.kind} operation ${requestId}. Replay confirms the original operation and does not establish current state.\n`);
             return submitOperation(client, operation);
         }
     }

package/src/operations.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { createSchema, moveSchema, publishSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { createSchema, moveSchema, publishSchema, shareSchema, unshareSchema, updateSchema } from '@yargote/artifacts-contracts';
 import type { ArtifactHttpClient } from '@yargote/artifacts-client';
 export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"create">;
@@ -97,6 +97,28 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     version: z.ZodLiteral<1>;
     resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
     ownerId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"share">;
+    command: z.ZodObject<{
+        requestId: z.ZodString;
+        artifactId: z.ZodString;
+        email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+        notify: z.ZodOptional<z.ZodBoolean>;
+        requireNew: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<1>;
+    resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    ownerId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"unshare">;
+    command: z.ZodObject<{
+        requestId: z.ZodString;
+        artifactId: z.ZodString;
+        shareId: z.ZodString;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<1>;
+    resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    ownerId: z.ZodString;
 }, z.core.$strict>], "kind">;
 export type PreparedOperation = z.infer<typeof operationSchema>;
 export type Mutation = {
@@ -111,11 +133,33 @@ export type Mutation = {
 } | {
     kind: 'move';
     command: z.input<typeof moveSchema>;
+} | {
+    kind: 'share';
+    command: z.input<typeof shareSchema>;
+} | {
+    kind: 'unshare';
+    command: z.input<typeof unshareSchema>;
 };
 export declare function operationPath(stateDir: string, resource: string, requestId: string): string;
 export declare function retainOperation(stateDir: string, resource: string, ownerId: string, mutation: Mutation): Promise<PreparedOperation>;
 export declare function loadOperation(stateDir: string, requestId: string, resource: string, ownerId: string): Promise<PreparedOperation>;
-export declare function submitOperation(client: ArtifactHttpClient, operation: PreparedOperation): Promise<{
+export declare function submitOperation(client: ArtifactHttpClient, operation: PreparedOperation): Promise<void> | Promise<{
+    shareId: string;
+    artifactId: string;
+    kind: "email";
+    value: string;
+    createdAt: string;
+    notification?: {
+        status: "requested";
+    } | {
+        status: "skipped";
+        reason: "disabled";
+    } | {
+        status: "skipped";
+        reason: "rate_limited";
+        retryAt: string;
+    } | undefined;
+}> | Promise<{
     artifactId: string;
     project: string | null;
 }> | Promise<{

package/src/operations.js

@@ -3,7 +3,7 @@ import { lstat, mkdir, open } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { createSchema, moveSchema, publishSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { createSchema, moveSchema, publishSchema, shareSchema, unshareSchema, updateSchema } from '@yargote/artifacts-contracts';
 import { canonicalResource } from '@yargote/artifacts-contracts/http';
 const binding = {
     version: z.literal(1),
@@ -15,6 +15,8 @@ export const operationSchema = z.discriminatedUnion('kind', [
     z.strictObject({ ...binding, kind: z.literal('update'), command: updateSchema }),
     z.strictObject({ ...binding, kind: z.literal('publish'), command: publishSchema }),
     z.strictObject({ ...binding, kind: z.literal('move'), command: moveSchema }),
+    z.strictObject({ ...binding, kind: z.literal('share'), command: shareSchema }),
+    z.strictObject({ ...binding, kind: z.literal('unshare'), command: unshareSchema }),
 ]);
 export function operationPath(stateDir, resource, requestId) {
     createSchema.shape.requestId.parse(requestId);
@@ -88,5 +90,9 @@ export function submitOperation(client, operation) {
         case 'update': return client.update(operation.command);
         case 'publish': return client.publish(operation.command);
         case 'move': return client.move(operation.command);
+        case 'share': return client.share(operation.command);
+        case 'unshare': return client.unshare(operation.command);
     }
+    const exhaustive = operation;
+    throw new Error(`Unsupported retained operation: ${exhaustive}`);
 }