@afbin/cli 0.4.1 → 0.4.2

package/README.md

@@ -7,12 +7,17 @@ Command examples use `afbin` as shorthand for `npx --yes @afbin/cli@latest` (`np
 ## Preview and host
 
 ```sh
+afbin preview --port 7474
 afbin preview report.jsx appendix.jsx
 afbin preview . --share
 afbin serve --dir ./team --port 7445
 afbin config set host http://app.lvh.me:7445
 ```
 
+With no paths, `afbin preview --port 7474` starts an empty preview service; it does not select other files in the current directory. Open the printed URL to **Import an HTML file**, or choose **Connect to server** in your `.jsx.html` file and enter `http://localhost:7474`. Confirm the title, comment count and workspace filename, then choose **Import and open**. The server imports a workspace copy using the same validation and conflict checks as `afbin import`, and opens the existing full editor. The original HTML file stays unchanged; browser edits/comments then save to the workspace. Nothing is published. HTML payloads are limited to 25 MB; encoded JSON requests are separately limited to 50 MB, so unusually escaped files may reach the transport limit earlier.
+
+A custom hosted preview service uses an HTTPS reverse proxy and `afbin preview --public-url https://preview.example.com`; the explicit public origin enables its Host/Origin checks and does not broaden the listener. Use `--share` only if the proxy or users must reach the listener from another machine. This is a preview-service connection, separate from account hosting through `serve`. Everyone who can reach a preview service can import, edit and comment within its workspace.
+
 Preview writes browser saves to selected local files without publishing. Shared previews allow
 anyone who can reach them to edit/comment; stop the foreground process to end the session.
 Add assigns stable workspace-local IDs. Preview retains those IDs without sign-in or cloud access, including after publication. Push preserves the local files and creates a separate publication copy whose references use remote IDs.

package/dist/afbin.mjs

@@ -649,6 +649,15 @@ var init_program = __esm({
   }
 });
 
+// ../contracts/src/preview-connect.ts
+var PREVIEW_CONNECT_MAX_BYTES;
+var init_preview_connect = __esm({
+  "../contracts/src/preview-connect.ts"() {
+    "use strict";
+    PREVIEW_CONNECT_MAX_BYTES = 25 * 1024 * 1024;
+  }
+});
+
 // ../contracts/src/index.ts
 var init_src = __esm({
   "../contracts/src/index.ts"() {
@@ -683,6 +692,7 @@ var init_src = __esm({
     init_mutation_notifications();
     init_schedules();
     init_program();
+    init_preview_connect();
   }
 });
 
@@ -1218,7 +1228,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@afbin/cli",
-      version: "0.4.1",
+      version: "0.4.2",
       type: "module",
       license: "Apache-2.0",
       description: "Local files, published artifacts and agent authoring",
@@ -8385,6 +8395,7 @@ var init_commands = __esm({
       image: { value: "ID", description: "Download a comment image by its image.id from the comment listing; requires --output." },
       variant: { value: "VARIANT", description: "Comment image: preview (default, includes drawn marks), original (without marks), or thumbnail." },
       port: { value: "PORT", description: "Listen on this port; serve defaults to 7445, preview chooses an available one." },
+      "public-url": { value: "ORIGIN", description: "Explicit HTTPS origin of a reverse proxy serving this preview; does not change the listening interface." },
       share: { description: "Allow network access to the selected preview files; everyone who can reach it may edit." },
       service: { value: "NAME", description: "Prepare a local service for offline use: sql or chromium." },
       config: { value: "PATH", description: "Read explicit operator settings for the foreground server." },
@@ -8463,7 +8474,7 @@ var init_commands = __esm({
       { name: "add", usage: "<path> [<path> ...]", description: "Assign stable account-scoped identities to local files without publishing.", min: 1, max: Infinity, flags: [], examples: ["afbin add sales.csv report.jsx --json"] },
       { name: "mv", usage: "<from> <to>", description: "Move a registered local file while retaining its identity.", min: 2, max: 2, flags: [], examples: ["afbin mv sales.csv data.csv"] },
       { name: "import", usage: "<file.jsx.html> [--output <file.jsx>]", description: "Import an offline HTML file into local JSX without publishing; defaults to the same basename with .jsx. Existing local documents reconcile safely.", min: 1, max: 1, flags: ["output"], examples: ["afbin import report.jsx.html", "afbin import review.jsx.html --output report.jsx"] },
-      { name: "preview", usage: "<path> [<path> ...]", description: "Preview and edit local JSX files without publishing. Directories select their JSX files.", min: 1, max: Infinity, flags: ["port", "share"], examples: ["afbin preview report.jsx appendix.jsx", "afbin preview . --share"] },
+      { name: "preview", usage: "[<path> ...]", description: "Preview and edit local JSX files without publishing. With no paths, start an empty server for HTML imports. Directories select their JSX files.", min: 0, max: Infinity, flags: ["port", "share", "public-url"], examples: ["afbin preview report.jsx appendix.jsx", "afbin preview . --share"] },
       { name: "query", usage: "<ref> [<ref> ...]", description: "Read dataset rows or declared queries; --write runs a named mutation or dataset SQL.", min: 1, max: Infinity, flags: ["input", "name", "param", "limit", "cursor", "remote", "write", "dry-run", "output", "format"], examples: ["afbin query sales.csv", "afbin query report123 --name tasks", "afbin query report123 --write --name change_status --param task_id=1 --param status=Done"] },
       { name: "pull", usage: "[<ref> ...]", description: "Retrieve artifacts or account resources and reconcile tracked files.", min: 0, max: Infinity, flags: ["type", "output", "format", "dry-run", "force"], examples: ["afbin pull abc123 --output report.jsx", "afbin pull report.jsx@2", "afbin pull --type profile"] },
       { name: "fork", usage: "<ref> [<ref> ...]", description: "Create a distinct private local draft from a resource; publish it later with push. --as gives the copy to a test user instead.", min: 1, max: Infinity, flags: ["type", "output", "as", "dry-run"], examples: ["afbin fork abc123 --output copy.jsx", "afbin fork report.jsx --dry-run", "afbin fork abc123 --as tu_9fA2b --json"] },
@@ -18283,7 +18294,7 @@ var teaching_default;
 var init_teaching = __esm({
   "src/generated/teaching.json"() {
     teaching_default = {
-      version: "0.4.1",
+      version: "0.4.2",
       protocol: 3,
       files: {
         "SKILL.md": '---\nname: artifactbin\ndescription: "Required for every artifactbin task: any artifactbin.dev or self-hosted artifactbin link, any afbin command, and any request to publish, edit, comment on, query or export an artifact, document, dashboard, deck or dataset. Read this skill before acting; use the documented npm CLI or authenticated HTTP API contracts."\n---\n## Read first\n\nartifactbin publishes editable `.jsx`: a YAML fence, self-contained HTML and kit JSX with Tailwind `className`. Datasets/media are artifacts too.\n\nnpm CLI: local files/browser approval. Direct HTTP: email auth without CLI installation; [HTTP API](references/http-api.md).\n\n- Run via `npx --yes @afbin/cli@latest <command>`; Windows uses `npx.cmd`. `afbin` below is shorthand. Node/npm and offline caches: [npm and local files](references/npm-local.md).\n- Preview is local; HTML downloads use `.jsx.html`. CLI browser approval allows guests; HTTP requires email.\n- Automatic browser approval also applies to `--yes`. If unavailable, ask for email: `afbin auth --email <email>`; then code: `afbin auth --email <email> --otp <code>`. Credentials: `~/.artifactbin/hosts/<origin-id>/credentials.env`; never mint or print tokens.\n- For a supplied artifact: `afbin pull <url-or-id> --output report.jsx`, edit the file, `afbin push report.jsx`. For a new artifact, write the file and push it. Share its returned URL.\n- Several people \u2014 shared, friends, a team, each person, sign-up, vote, RSVP, who did what: read `afbin help apps` BEFORE picking a data shape: accounts, never typed names.\n- Few turns: `afbin help <page type>`, ONE design system in the fence, then push a FIRST designed version within six calls of the pull \u2014 the fence, the title, real opening copy and one substantive section \u2014 and fill the rest in later pushes; a person is waiting on a blank page. A successful push IS the verification that source was accepted. Skip pulling, diffing or grepping it just to confirm publication; filling sections is not re-checking.\n- For an existing artifact, prefer `afbin query ID --name tasks` to read and `afbin query ID --write --name change_status --param task_id=1 --param status=Done` to update. Use its declared names/arguments; preserve its source.\n- Sessions are browser/UI QA for newly authored or changed `<Mutation>`, page-local state and row/cell action context. Use a live session (`afbin help live-sessions`) on each identity\'s isolated copy (`afbin help apps`), then the original `--as guest` (identity writes off). One session at a time. Stop once each works once per identity.\n- Local files: `afbin add <files> --json` assigns reference IDs; preview/push register named files. Push runs `afbin validate` and publishes unpublished IDs.\n- Every body element has a persistent `id` for its lifetime. Move it with the same id; never reuse an id.\n- Unlisted tags such as `<form>` are refused; read the markup allowlist.\n- The kit covers content, layout, data, charts, tables, controls and motion. Use Helmet `<script>` (Solid, npm) for behaviour; exported components mount by name.\n- Preserve its identity: the CLI maintains `id`, `edit_id`, `head_version`, `state` and `version` in the YAML fence. Fork deliberately: copy the file and remove those five fields.\n- Publishing does not verify appearance, whether or not you can view images. For visual review, one `afbin export <ref> --output out.png` shows the whole document, every slide, in one image; never one slide at a time. For styling, no other skill, palette tool or image tooling is needed \u2014 the design system carries the palette and type.\n- On refusal, follow the returned code and instruction; a conflict never touches your file, and after an uncertain write repeat the same command and arguments to recover it.\n\n`afbin -h` and `afbin help <topic>` work offline; `afbin help` prints this file\u2019s location.\n\n## Example\n\nBefore writing, read `afbin help <page type>` for design and markup; skipping the frame leaves content flush to the viewport edge.\n\n```jsx\n---\n# CLI maintains id, edit_id, head_version, state and version.\ntitle: Q3 sales review\ntemplate: dashboard\ntheme: volta\nvisibility: unlisted\n---\n<Helmet>\n<title>Q3 sales review</title>\n<style>{`.kpi { letter-spacing: -0.02em } /* custom CSS lives here */`}</style>\n{/* afbin add sales.csv --json gives its ref:<id> (abc123 here); SQL reads sales.rows. */}\n<Import name="sales" src="ref:abc123" />\n{/* $region is reader state; data="$monthly" binds query rows to the view. */}\n<Value name="region" type="string" />\n<Query name="regions">{`select distinct region from sales.rows order by 1`}</Query>\n<Query name="monthly">{`\nselect month, sum(revenue) as revenue from sales.rows\nwhere $region is null or region = $region group by 1 order by 1\n`}</Query>\n<Query name="by_region">{`select region, sum(revenue) as revenue from sales.rows group by 1 order by 2 desc`}</Query>\n{/* Tasks: afbin help users; columns id:number, title:string, status:string,\nassignee:user. Replace ntf123 with that published dataset\'s ID. */}\n<Import name="tasks" src="ref:ntf123" />\n<Value name="task_id" type="number" default={1} />\n<Value name="status" type="string" default="Done" />\n<Mutation name="change_status" expectedAffected={1}>{`\nupdate tasks.rows set status = $status where id = $task_id\n`}</Mutation>\n{/* Actor shown separately: Task Review pricing is now Done.\nJoined recipients only; rules combine per user/run. */}\n<Notify name="status_notice" on="change_status">{`\nselect assignee as "to", \'Task \' || title || \' is now \' || status as message\nfrom tasks.rows where id = $task_id\n`}</Notify>\n</Helmet>\n{/* Body: static JSX, HTML and kit components, Tailwind className, no CDN scripts.\nEach node has a persistent id: keep it when moving; never reuse it. */}\n<div data-design="tw" className="@container px-4 py-8 @2xl:px-8">\n<header className="max-w-prose">\n<h1 className="text-3xl @2xl:text-5xl font-bold">Revenue grew in every region but one</h1>\n<p>Container prefixes like @2xl: start at phone width.</p>\n</header>\n{/* Changing $region reruns its queries. */}\n<Select label="Region" value="$region" options="$regions" placeholder="All regions" />\n{/* Grid columns: w is out of 12; narrow screens stack. */}\n<Grid mode="flow" className="mt-6">\n<GridItem w={4}>\n{/* data="$monthly" binds computed query rows. */}\n<Card><CardHeader><CardTitle>Total revenue</CardTitle></CardHeader>\n<CardContent className="kpi text-4xl font-semibold">\n<Number data="$monthly" col="revenue" agg="sum" prefix="$" format=",.0f" />\n</CardContent></Card>\n</GridItem>\n<GridItem w={8}>\n{/* Vega-Lite or shipped recipes, never hand-rolled <svg>. */}\n<Question title="Revenue by month" data="$monthly" height="320px"\nviz={{"kind":"vega-lite","spec":{"mark":"line","encoding":{"x":{"field":"month","type":"temporal"},"y":{"field":"revenue","type":"quantitative"}}}}} />\n</GridItem>\n</Grid>\n<h2 className="mt-8 text-2xl font-semibold">By region</h2>\n<DataTable data="$by_region" height="240px" />\n<Button run="$change_status">Complete selected task</Button>\n</div>\n```\n\n## Read next\n\n- [design](references/design.md) \u2014 visual design.\n- [markup](references/markup.md); [data](references/markup-data.md) and [example](references/markup-data-example.md).\n- [page types](references/templates.md) \u2014 `afbin help templates`, then `references/templates-<name>.md`.\n- [design systems](references/design-systems.md) \u2014 `afbin help design-systems`, then `system-<slug>.md`; [worked briefs](references/worked-briefs.md).\n- [sync and recovery](references/publishing.md) \u2014 status, diff, dry-run, force, uncertain writes.\n- [errors](references/errors.md) \u2014 refusal codes and fixes.\n- [comments](references/publishing-annotations.md) \u2014 `afbin comment`; `afbin help remote-review`.\n- [apps](references/apps.md) \u2014 shared pages, grants, mentions.\n- [datasets and media](references/publishing-datasets.md), [catalogs](references/databases.md), [user fields](references/databases-users.md), [queries](references/publishing-query.md).\n- [history](references/publishing-versions.md) \u2014 `afbin log`, `afbin delete`, restore, export.\n- [authentication](references/publishing-auth.md) \u2014 sign-in and credentials.\n- [lambdas](references/lambdas.md).\n- [live sessions](references/live-sessions.md) \u2014 Playwright, `mx`, screenshots.\n- [commands](references/commands.md) \u2014 every command and flag; [Markdown import](references/markdown.md) for a one-time `.md` push.\n',
@@ -18338,9 +18349,9 @@ var init_teaching = __esm({
         "references/themes.md": '## Read first\n\n`theme` is the fence field a design is named in. A new artifact names one\nof the design systems in [design-systems.md](design-systems.md). Six older\nmood themes remain valid legacy values, so every artifact that carries one renders\nexactly as it did: `modernist`, `organic`, `industry`, `terminal`,\n`manuscript` and `pop`. They carry tokens and fonts only, no class vocabulary.\n\nEditing such an artifact, keep its theme and author in token classes\n(`text-muted-foreground`, `bg-muted`, `bg-primary`, `border-border`); do not\nmove it to a system unless the user asks, since the look changes. In every\ntheme "accent" means the `primary` token; the alert colour is `destructive`;\nthe CSS token `--accent` is a quiet neutral surface tint, never the accent.\n\nOverriding tokens with ordinary `:root` CSS in the Helmet style block, and\nthe full list of palette and type keys, is documented once in the `<Helmet>`\nsection of [markup.md](markup.md).\n',
         "references/worked-briefs.md": "## Read first\n\nA brief is eight to twelve lines: reader, job, facts, priority, page type,\nsystem, thesis, composition, acceptance, unknowns. The thesis names the\norganizing idea, the object the hand draws and the device that carries the\ndata. The rejected line is what teaches: the obvious composition and why it\nfails this reader. Read at most one brief per task, and only when the job is\nunfamiliar; never copy a brief's system or object into a different subject.\n\n## The briefs\n\n### Dashboard \xB7 allocate attention\n\nReader: a support lead beginning a shift. Facts: 180 open, 36 overdue, 15\nagents; overdue is a subset. Priority: Technical holds half the overdue.\nSystem: `system-volta.md`, one loud number on quiet paper. Thesis: a shift\nbriefing whose diagnosis leads into a queue comparison and an inspectable\nledger; the split bar carries the overdue share. Composition: diagnosis \u2192\ncomparison \u2192 filtered detail; mobile keeps that order. Rejected: a tile grid\nof eight KPIs that shows everything and prioritizes nothing. Acceptance:\nthe queue filter updates every derived number; sort works; no clipped labels.\n\n### Editorial \xB7 understand evidence (restrained)\n\nReader: a market committee deciding whether to continue an earlier-opening\npilot. Facts: six Sundays, 510 transactions, 42 survey responses, 26\npreferring the earlier hour, $1,800 extra staffing. System:\n`system-dossier.md`, paper narrates and ink proves. Thesis: a pilot report\nthat states what the count proves and what it cannot, with every percentage\nnaming its denominator; the facts rail carries the numbers. Composition:\nfindings up front \u2192 numbered claims \u2192 method footer. Rejected: an\nillustrated feature with invented voices; the committee wants the evidence,\nnot the atmosphere. Acceptance: transactions never read as shoppers.\n\n### Plan \xB7 execute a change (restrained)\n\nReader: a coding agent, then a reviewer. Facts: a document-approval flow in a\nTypeScript app; authors cannot approve their own work; an approval must\nnever attach to stale content. System: `system-drafting.md`, every line a\nmeasurement. Thesis: an engineering drawing set where the race invariant\nleads as a drawing, then contracts, then evidence-aware tasks. Composition:\ninvariant \u2192 wireframes \u2192 flow \u2192 ledger. Rejected: a task timeline with a\ncomponent inventory; it executes nothing. Acceptance: discovery, implementation\nand verified results are distinguished; every task starts pending.\n\n### Deck \xB7 make a decision\n\nReader: a volunteer cinema board approving a projector. Facts: 1,280 seats\noffered, 960 admissions, three late starts from faults, $32,000 to replace.\nSystem: `system-redline.md`, one word then the number. Thesis: a decision\nprogramme where each slide is its own composition and the motion is the last\nslide; the big-number slide carries the late starts. Composition: experience\n\u2192 evidence \u2192 options \u2192 cost \u2192 unknowns \u2192 motion. Rejected: a cover, a\ncontents slide and six identical chart slides. Acceptance: admissions never\nread as unique people; no invented payback.\n\n### App \xB7 complete a workflow\n\nReader: a maker booking a machine. Facts: three tools, three slots, one\nalready taken. System: `system-signout.md`, the sheet on the wall made\nclickable. Thesis: availability is the primary surface, the selection stays\nvisible, confirmation becomes a booking record. Composition: sheet \u2192 review\n\u2192 record, with unavailable, empty and success states drawn. Rejected: a\nform with a submit button and a toast. Acceptance: the taken slot stays\ntaken; back navigation keeps the selection; refresh behaviour is stated.\n\n### Landing \xB7 nothing fits\n\nReader: a first-time visitor to a ceramics exhibition. Facts: three\nweekends, free admission, three paid workshops. The user supplies a brand:\nunglazed clay, one cobalt, a stencil face no system carries. No listed\nsystem fits: the nearest, `system-almanac.md`, loses the stencil and the\ncobalt. Thesis: an invitation whose opening is one drawn kiln with the dates,\nthe price and the next action composed into it; the schedule is the second\nsurface. Composition: invitation \u2192 programme \u2192 practicalities. Resolution:\nsay so in the catalogue's four lines, offer the nearest, and on approval\nwrite a one-artifact system in the artifact's Helmet. Acceptance: the\nprimary action reaches the schedule; the demo is labelled as one.\n",
         "references/errors.md": "# Errors and recovery\n\nLocal checks run before authentication. Every refusal returns a stable code, the field or location at fault and a recovery instruction; with --json it is one document with error.code, error.message and error.fix, exit status 2. Follow the returned instruction; the codes below say the same. A server refusal may add current source or a diff. A conflict never touches your file. For a refusal or interrupted write, preserve the returned code, fix and pending request record, then retry push: its frozen request recovers the original result.\n\n## approval_origin_mismatch\n\nThe selected server advertises its browser approval page on a different origin, and has not published that origin as another address of itself, so the pairing cannot be trusted for the selected origin.\n\nSelect the server by its public origin with --server; credentials are never sent to an origin you did not select.\n\n## unmanaged_installation\n\nThis command needs the npm distribution.\n\nPrepare Node with __AFBIN_SERVER__/chat/ensure-node.sh (Windows: ensure-node.ps1), then run npx --yes @afbin/cli@latest <command>.\n\n## compatible_release_unavailable\n\nNo published release matches the version and protocol the selected server named.\n\nRetry after a compatible npm release is published, using npx --yes @afbin/cli@latest <command> (Windows: npx.cmd).\n\n## outside_workspace\n\nThe destination is outside the workspace afbin runs in.\n\nWrite inside the workspace, e.g. --output shot.png, and move the file afterwards if it must live elsewhere.\n\n## sql_in_argument\n\nA query argument was SQL; arguments name the datasets or documents to query.\n\nPut the SQL in a file and run afbin query <ref> --input query.sql, or pipe it: afbin query <ref> --input - < query.sql.\n\n## image_fetch_failed\n\nThe server could not fetch an external image URL named by the document.\n\nCheck the URL is public and reachable, or register the local image with afbin add --json and reference its returned ID.\n\n## dataset_read_only\n\nThe dataset does not accept row mutations: Postgres datasets are read-only and stored datasets need access: readwrite.\n\nPublish a stored dataset with afbin push <file> --type dataset --access readwrite; Postgres datasets cannot be written.\n\n## renderer_unavailable\n\nThis representation requires a published head, and this target is not one.\n\nUse PNG/JPG for a local JSX image, push before exporting the HTML offline file, or export csv, json, yaml or original.\n\n## unsupported_version_export\n\nThis target has no version to show: the published viewer opens the head, and a local file is a draft rather than a history.\n\nExport a published id at a version (afbin export <id>@<n> --format png), open the head, or afbin pull <ref>@<n> for that content.\n\n## previous_engine_version\n\nThat version was written for the previous query engine and needs converting by hand, so it cannot be restored as it stands.\n\nRead it with afbin pull <id>@<v> --output -, carry what you need into the current document by hand, then afbin push.\n\n## unpublished_draft\n\nThe published viewer requires a published, unchanged document.\n\nUse afbin preview <path> for local drafts, or publish with afbin push, then open it.\n\n## not_forkable\n\nA folder names the original children and a Postgres dataset keeps its bound secret.\n\nFork a document, dataset rows or a file.\n\n## output_exists\n\nThe destination is taken; fork and export never replace a source or an existing file.\n\nChoose a free --output path, or use export --force to replace it after a recoverable backup.\n\n## type_mismatch\n\n--type disagrees with the type the named source actually is.\n\nRemove --type, or name a source of that type.\n\n## session_disconnected\n\nThe remote session was removed; a replacement is never created silently.\n\nStart a new session with afbin remote <command>.\n\n## transport_error\n\nThe selected server could not be reached, so no request was answered.\n\nCheck the server URL (--server or ARTIFACTBIN_URL) and your network, then retry; afbin config set host <url> changes the default server.\n\n## auth_required\n\nThis remote operation needs credentials for the selected origin.\n\nRun afbin auth, or set ARTIFACTBIN_TOKEN and ARTIFACTBIN_URL for the selected server.\n\n## browser_unavailable\n\nThe browser could not be opened; authentication stopped immediately and kept its pairing.\n\nApprove the printed code at the printed URL on any device and rerun the command, which collects that approval; or ask for the user email and run afbin auth --email <email>, then complete with --otp <code>.\n\n## otp_required\n\nAn email login code was sent; authentication is not complete.\n\nAsk for the emailed code and run afbin auth --email <email> --otp <code>, using the same --server as before.\n\n## otp_send_failed\n\nThe server could not send the login email.\n\nCheck the email and server, then retry afbin auth --email <email>; wait before retrying if rate limited.\n\n## otp_rejected\n\nThe email code was invalid, expired, or already used.\n\nCheck the email and code, or request a new one with afbin auth --email <email>, then complete with --otp <code>.\n\n## approval_required\n\nBrowser approval is pending; --yes cannot approve it.\n\nUse afbin auth --email <email> when a browser is unavailable, or open verification_url, approve, and rerun afbin auth before expires_at.\n\n## access_denied\n\nBrowser approval was denied.\n\nRun afbin auth only when you intend to start a new approval request.\n\n## approval_expired\n\nThe browser approval window expired.\n\nRun afbin auth --email <email> when a browser is unavailable, or afbin auth to start another browser approval.\n\n## cli_update_required\n\nThe server requires a newer CLI protocol.\n\nRun npx --yes @afbin/cli@latest <command> (Windows: npx.cmd), then retry the command.\n\n## cli_npm_required\n\nafbin now runs through npm.\n\nInstall Node.js if needed, then use npx --yes @afbin/cli@latest <command> (Windows: npx.cmd). Your files and account stay the same.\n\n## state_conflict\n\nMetadata or content changed since the observed head.\n\nInspect afbin diff --remote <ref>, reconcile the changes, then push. Use --force only when you intend a conditional replacement.\n\n## version_conflict\n\nThe content version changed since the observed head.\n\nInspect afbin diff --remote <ref> and reconcile the current content before pushing again.\n\n## edit_conflict\n\nThe body edit could not be rebased without a conflict.\n\nInspect the returned diff and current source; reconcile your proposal before pushing again.\n\n## outcome_unknown\n\nA write has no confirmed response; it may have committed.\n\nKeep the pending request journal and repeat the same command and arguments to recover the frozen request with the same operation key. Do not start a new write to retry.\n\n## pending_recovery\n\nAn interrupted operation must be recovered before starting a different write.\n\nRerun afbin push. For an uncertain conditional update, afbin pull --force archives the proposal and reads the current head; uncertain creates must be recovered first.\n\n## result_deleted\n\nThe original create result was deleted; its operation key will never create a replacement.\n\nRestore that artifact and pull it, or deliberately create a new local file to fork. Keep the recovery record.\n\n## wrong_server\n\nThe artifact URL or workspace belongs to a different server, and that origin is not one the selected server publishes as another address of itself. The refusal names both origins: the one that was selected and the one the URL or the workspace carries.\n\nPass --server <the origin named in the refusal> to select that server, or run the command from a workspace tracked against it; keep work for another server in a separate directory. When one deployment answers at two hostnames, its operator publishes the second one and afbin then treats them as one server.\n\n## account_mismatch\n\nThe authenticated account differs from the workspace account.\n\nSign in with the workspace account before retrying. Do not discard tracking or recovery records.\n\n## duplicate_identity\n\nTwo local files claim the same published artifact.\n\nKeep one tracked file. To READ another version without a second working copy: afbin pull <id>@<v> --output - , or afbin export <id>@<v> --format original --output <file>. To keep working on one: afbin fork <id>@<v>, which gives the copy its own identity.\n\n## invalid_policy\n\nThe dataset policy is not one this server accepts: an unsupported field, a role other than viewer, or a table or column the dataset does not have.\n\nThe detail names the field, table or column. Read the dataset's own tables with afbin pull <ref> --format yaml, correct the policy there and push the YAML; afbin push <ref> --policy viewers-write writes a grant for every table the dataset declares.\n\n## not_found\n\nThe selected server does not have this artifact, or this account cannot reach it \u2014 existence is never revealed, so the two are one answer.\n\nCheck the reference with afbin list and the account with afbin auth. Someone else's artifact becomes yours to push only through afbin fork <ref>.\n\n## policy_locked\n\nThe dataset carries a write policy. Replacing the content of a governed dataset is the OWNER's alone, and reverting one is refused for everyone, because viewers' rows are in it.\n\nAsk the owner to push the change, or take your own copy with afbin fork <ref>. As the owner, push the rows you want \u2014 read an older version with afbin pull <ref>@<v> --output - and push that content instead of reverting.\n\n## policy_mismatch\n\nThe policy does not fit the dataset it is aimed at: a policy declared in the YAML disagrees with --policy, or a replacement no longer has a table or column the policy grants.\n\nThe detail names the table or column. Keep it in the pushed rows, or change the policy first: afbin pull <ref> --format yaml, edit policy there and push the YAML before replacing the content.\n\n## combined_policy_write\n\nOne request cannot both replace content and change the policy, and a dataset that does not exist yet cannot be given one.\n\nPush the content first, then afbin pull <ref> --format yaml and push that YAML with its policy. afbin push <ref> --policy viewers-write does both, in that order, in one command.\n\n## policy_changed\n\nThe policy revision moved since the one this push observed, so the compare-and-swap wrote nothing.\n\nRun afbin pull <ref> --format yaml for the current policy and its policy_revision, reapply your change there and push the YAML again.\n\n## dataset_error\n\nThe dataset itself could not be published, refreshed or restored: rows or columns the tier rejects, an unreadable stored table, or a connection the server could not use.\n\nThe detail names the fault. Correct the rows, columns or connection in the source file and push again; afbin validate checks the local definition first and afbin help data shows the Dataset and Table forms.\n\n## version_not_writable\n\nHistorical selectors are read-only.\n\nUse @version with pull, diff or log. To restore old content, pull that version into the tracked file and push the file without a suffix.\n\n## invalid_reference\n\nThe value is not an artifact reference.\n\nUse <url|id|path>[@version] at the command line, ref:<id> in published markup, and $query for result bindings.\n\n## testuser_limit\n\nThis account already holds as many live test users as it may at once.\n\nErase one you are finished with: afbin testuser list shows them, then delete one with afbin testuser delete <id>, or afbin testuser delete --all. Mint the next with afbin testuser new.\n\n## testuser_expired\n\nThe named test user is past its 24-hour life; the sweep erases an expired test user and everything it owned.\n\nMint another with afbin testuser new, give it the page again with afbin fork <id> --as <testuser>, and rerun the session against that copy.\n\n## not_your_testuser\n\nThat test user belongs to another account or has already been erased; a test user is only ever its own account's.\n\nRun afbin testuser list for the ids this account holds, and afbin testuser new if there is none.\n\n## testuser_requires_account\n\nOnly a signed-in account mints test users: a guest or a test user has no account to own the sandbox.\n\nRun afbin auth to sign in as yourself, then afbin testuser new.\n\n## sandbox_only\n\nA test user may act on artifacts test users own and on other test users, and is a guest everywhere else: on an account's artifact it reads what the link grants and nothing more \u2014 no $_me write, like, follow, comment or fork.\n\nGive the test user its own copy to act on: afbin fork <id> --as <testuser>, then point the session at that copy. Nothing a test user does reaches the original.\n\n## sign_in_required\n\nThe page ran a <Mutation> binding $_me and the reader is signed out, so there is no account to record in the row.\n\nSign in, or verify with a test user: afbin testuser new, then afbin fork <id> --as <testuser> and browse the copy with afbin sessions script new --as <testuser>.\n\n## invalid_markup\n\nStatic JSX does not satisfy the local authoring grammar.\n\nRun afbin help markup and correct the indicated source. afbin validate --fix applies mechanical formatting only.\n\n## invalid_dataset\n\nA local dataset is not supported tabular data.\n\nUse CSV, a JSON array of row objects, or a .geojson FeatureCollection. Use afbin help data for Query and Mutation examples.\n\n## unsupported_file_type\n\nThis local format cannot be published through native push.\n\nUse a .jsx document, CSV/JSON/GeoJSON rows, or an allowed media/file format. See afbin help publishing-datasets.\n",
-        "references/commands.md": "## add\n\n```text\nafbin add <path> [<path> ...]\n\nAssign stable account-scoped identities to local files without publishing.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n\nExamples:\n  afbin add sales.csv report.jsx --json\n```\n\n## mv\n\n```text\nafbin mv <from> <to>\n\nMove a registered local file while retaining its identity.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n\nExamples:\n  afbin mv sales.csv data.csv\n```\n\n## import\n\n```text\nafbin import <file.jsx.html> [--output <file.jsx>]\n\nImport an offline HTML file into local JSX without publishing; defaults to the same basename with .jsx. Existing local documents reconcile safely.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n\nExamples:\n  afbin import report.jsx.html\n  afbin import review.jsx.html --output report.jsx\n```\n\n## preview\n\n```text\nafbin preview <path> [<path> ...]\n\nPreview and edit local JSX files without publishing. Directories select their JSX files.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --port <PORT>\n    Listen on this port; serve defaults to 7445, preview chooses an available one.\n  --share\n    Allow network access to the selected preview files; everyone who can reach it may edit.\n\nExamples:\n  afbin preview report.jsx appendix.jsx\n  afbin preview . --share\n```\n\n## query\n\n```text\nafbin query <ref> [<ref> ...]\n\nRead dataset rows or declared queries; --write runs a named mutation or dataset SQL.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --input <PATH>\n    Read command input from a local file; use - for stdin. Schedule commands take inline JSON instead.\n  --name <NAME>\n    Select a named query, mutation or table, or name a remote terminal session.\n  --param <NAME=VALUE>\n    Bind a named scalar parameter; repeat for distinct names.\n  --limit <N>\n    Maximum results in this page (1\u2013100).\n  --cursor <CURSOR>\n    Continue from a returned next_cursor.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n  --write\n    Execute a named document mutation or a dataset row mutation; otherwise only read.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n\nExamples:\n  afbin query sales.csv\n  afbin query report123 --name tasks\n  afbin query report123 --write --name change_status --param task_id=1 --param status=Done\n```\n\n## pull\n\n```text\nafbin pull [<ref> ...]\n\nRetrieve artifacts or account resources and reconcile tracked files.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n\nExamples:\n  afbin pull abc123 --output report.jsx\n  afbin pull report.jsx@2\n  afbin pull --type profile\n```\n\n## fork\n\n```text\nafbin fork <ref> [<ref> ...]\n\nCreate a distinct private local draft from a resource; publish it later with push. --as gives the copy to a test user instead.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --as <WHO>\n    Act as somebody else: a test user id from afbin testuser new, or guest on a session. fork --as <testuser-id> gives the copy to that test user, inside its sandbox; sessions script new --as guest|<testuser-id> chooses who a NEW session's pages browse as, once, when it is created. Omit --as and everything runs as you.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n\nExamples:\n  afbin fork abc123 --output copy.jsx\n  afbin fork report.jsx --dry-run\n  afbin fork abc123 --as tu_9fA2b --json\n```\n\n## export\n\n```text\nafbin export <ref> [<ref> ...]\n\nExport one image of the whole document, every slide stacked; --page picks one slide; --format html saves the offline file (one .jsx.html that opens, edits and comments without a connection); data and original bytes too.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --name <NAME>\n    Select a named query, mutation or table, or name a remote terminal session.\n  --page <N>\n    One slide or page only; without it the image is the whole document, every slide stacked.\n  --og\n    Export the selected social preview image: uploaded cover or saved document framing.\n  --refresh\n    Refresh the selected resources' external data or imported assets; on export, wait for a fresh image. Requires explicit targets.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n\nExamples:\n  afbin export abc123 --output report.png\n  afbin export abc123 --format html --output report.jsx.html\n  afbin export sales.csv --format json --output -\n```\n\n## push\n\n```text\nafbin push [<ref> ...]\n\nCreate, update or upload; no paths pushes changed tracked files. Markdown converts once to adjacent JSX. Program definitions use .program.json.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --access <ACCESS>\n    Publish or change a dataset's row access: read (the default) or readwrite, which a document writing to it requires.\n  --policy <POLICY>\n    Grant dataset row writes: viewers-write lets everyone who can view it insert, update and delete rows; none removes the grant.\n  --restore\n    Restore the selected soft-deleted resources; requires explicit targets.\n  --refresh\n    Refresh the selected resources' external data or imported assets; on export, wait for a fresh image. Requires explicit targets.\n  --secret-env <NAME>\n    Read a secret value from this environment variable; it is never written to YAML, journals or output.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n\nExamples:\n  afbin push report.jsx\n  afbin push worker.program.json\n  afbin push tasks.csv --type dataset --access readwrite\n  afbin push --dry-run\n  afbin push --restore abc123\n```\n\n## validate\n\n```text\nafbin validate [path ...]\n\nCheck local files without network access; --remote adds read-only server checks.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --fix\n    Apply mechanical local fixes. Push never fixes source.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n\nExamples:\n  afbin validate report.jsx\n  afbin validate --fix report.jsx\n```\n\n## status\n\n```text\nafbin status [<ref> ...]\n\nReport local changes, conflicts and installation state; remote state is last observed.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n\nExamples:\n  afbin status\n  afbin status --remote\n```\n\n## diff\n\n```text\nafbin diff [<ref> ...]\n\nCompute changes locally against the saved, historical or refreshed base.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n\nExamples:\n  afbin diff report.jsx\n  afbin diff --remote report.jsx\n```\n\n## log\n\n```text\nafbin log <ref> [<ref> ...]\n\nList versions, newest first; @version starts at that version or earlier.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --filter <FIELD=VALUE>\n    Combine supported filters; run afbin help filters for each collection.\n  --limit <N>\n    Maximum results in this page (1\u2013100).\n  --cursor <CURSOR>\n    Continue from a returned next_cursor.\n\nExamples:\n  afbin log report.jsx --limit 10\n```\n\n## list\n\n```text\nafbin list [<ref> ...]\n\nList resources or summaries; default accessible artifacts, newest first.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --in <REF>\n    Scope to a containing folder, artifact or dataset.\n  --filter <FIELD=VALUE>\n    Combine supported filters; run afbin help filters for each collection.\n  --limit <N>\n    Maximum results in this page (1\u2013100).\n  --cursor <CURSOR>\n    Continue from a returned next_cursor.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n\nExamples:\n  afbin list --json\n  afbin list --type session\n  afbin list --type table --in orders.yaml\n```\n\n## delete\n\n```text\nafbin delete <ref> [<ref> ...]\n\nSoft-delete resources, revoke tokens, terminate sessions or delete comments; keep local files.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --in <REF>\n    Scope to a containing folder, artifact or dataset.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n\nExamples:\n  afbin delete report.jsx --dry-run\n  afbin delete --type comment --in abc123 ann_123\n```\n\n## comment\n\n```text\nafbin comment <ref> [<ref> ...]\n\nList threads, post an anchored comment, reply, resolve or reopen.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --image <ID>\n    Download a comment image by its image.id from the comment listing; requires --output.\n  --variant <VARIANT>\n    Comment image: preview (default, includes drawn marks), original (without marks), or thumbnail.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --request <ID>\n    Stable idempotency identity for runs start or schedule run, or correlation for a managed agent reply.\n  --phase <PHASE>\n    Record acknowledged, completed or blocked with a reply.\n  --body <TEXT>\n    Post this comment text.\n  --input <PATH>\n    Read command input from a local file; use - for stdin. Schedule commands take inline JSON instead.\n  --thread <ID>\n    Select an existing thread for a reply or state change.\n  --node <ID>\n    Anchor a new thread to this node.\n  --quote <TEXT>\n    Anchor a new thread to this quote.\n  --state <STATE>\n    Set the selected thread to open or resolved; fixed names ignore case.\n  --filter <FIELD=VALUE>\n    Combine supported filters; run afbin help filters for each collection.\n  --limit <N>\n    Maximum results in this page (1\u2013100).\n  --cursor <CURSOR>\n    Continue from a returned next_cursor.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n\nExamples:\n  afbin comment report.jsx\n  afbin comment report.jsx --image cim_123 --output screenshot.webp\n  afbin comment report.jsx --node heading --body \"Clarify this\"\n  afbin comment report.jsx --thread ann_123 --body \"Fixed\" --state resolved\n```\n\n## open\n\n```text\nafbin open <ref> [<ref> ...]\n\nOpen the published view of a resource, or print its URL with --json.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n\nExamples:\n  afbin open report.jsx\n  afbin open abc123 --json\n```\n\n## help\n\n```text\nafbin help [topic]\n\nRead the bundled example, markup, data, themes, templates, schemas or command help; --for <template> prints everything a document of that kind needs in one call.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --for <TEMPLATE>\n    Print every reference a document of this template needs, in reading order, as one output.\n\nExamples:\n  afbin help --for deck\n  afbin help markup\n  afbin help dashboard\n```\n\n## serve\n\n```text\nafbin serve [--dir <path>] [--config <path>] [--port <port>] [--db-url <url>]\n\nRun a persistent authenticated server in the foreground.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --config <PATH>\n    Read explicit operator settings for the foreground server.\n  --dir <PATH>\n    Store server settings and uploaded objects here; defaults to ~/.artifactbin/server.\n  --db-url <URL>\n    Override the server application database with pglite:// or postgres://; object storage stays under --dir.\n  --port <PORT>\n    Listen on this port; serve defaults to 7445, preview chooses an available one.\n\nExamples:\n  afbin serve --dir ~/team-artifacts --port 7445\n  afbin serve --dir ~/team-artifacts --db-url postgres://localhost/artifactbin\n```\n\n## config\n\n```text\nafbin config get <key> | set <key> <value>\n\nRead or change client defaults without starting a server.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n\nExamples:\n  afbin config set host http://app.lvh.me:7445\n  afbin config get host\n```\n\n## auth\n\n```text\nafbin auth [<artifact>]\n\nSign in through browser approval, or use --email when a browser is unavailable.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --email <EMAIL>\n    Sign in by email OTP without opening a browser; use on remote or headless machines.\n  --otp <CODE>\n    Complete email login with the six-digit code; requires --email and does not send another code.\n\nExamples:\n  afbin auth\n  afbin auth --email you@example.com\n  afbin auth --email you@example.com --otp 123456\n```\n\n## setup\n\n```text\nafbin setup \n\nChoose and install local agent skills; remember your choices without signing in. Set ARTIFACTBIN_SKILLS=off in the environment to install no skill at all and leave every harness folder untouched \u2014 what a checkout\u2019s development loop (npm run afbin) runs under.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --harness <NAME>\n    Select a skill installation target: claude, codex, pi, opencode; repeat to select several, or use none.\n  --service <NAME>\n    Prepare a local service for offline use: sql or chromium.\n\nExamples:\n  afbin setup --service sql\n  afbin setup\n  afbin setup --yes\n  afbin setup --harness codex --harness pi\n```\n\n## update\n\n```text\nafbin update \n\nShow the npm command for your next launch with the latest version.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --harness <NAME>\n    Select a skill installation target: claude, codex, pi, opencode; repeat to select several, or use none.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n\nExamples:\n  afbin update --yes --json\n```\n\n## schedule\n\n```text\nafbin schedule create | list | get|update|pause|resume|delete|run|history <schedule-id>\n\nSchedule a live artifact with cron and timezone; inspect history or run it now. Each attempt executes the current published head.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --artifact <ID>\n    Published live artifact ID for a schedule, including program artifacts.\n  --cron <EXPRESSION>\n    Five-field cron expression interpreted in --timezone.\n  --timezone <ZONE>\n    IANA timezone, for example Asia/Kolkata or UTC.\n  --input <PATH>\n    Read command input from a local file; use - for stdin. Schedule commands take inline JSON instead.\n  --max-attempts <N>\n    Maximum attempts for a scheduled occurrence.\n  --retry-backoff <SECONDS>\n    Seconds between retry attempts.\n  --request <ID>\n    Stable idempotency identity for runs start or schedule run, or correlation for a managed agent reply.\n\nExamples:\n  afbin schedule create --artifact abc123 --cron '0 9 * * *' --timezone Asia/Kolkata --input '{\"region\":\"east\"}' --json\n  afbin schedule list --json\n  afbin schedule pause sch_123 --json\n  afbin schedule run sch_123 --json\n  afbin schedule history sch_123 --json\n```\n\n## runs\n\n```text\nafbin runs start <artifact> | status|events|cancel <run-id>\n\nExecute a published Lambda artifact and inspect its output, receipt and events. Read afbin help lambdas.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --input <PATH>\n    Read command input from a local file; use - for stdin. Schedule commands take inline JSON instead.\n  --request <ID>\n    Stable idempotency identity for runs start or schedule run, or correlation for a managed agent reply.\n  --after <SEQUENCE>\n    Read run events after this sequence (default 0).\n  --limit <N>\n    Maximum results in this page (1\u2013100).\n\nExamples:\n  afbin runs start abc123 --request weekly-1 --input input.json --json\n  afbin runs status run_123 --json\n  afbin runs events run_123 --after 0 --json\n  afbin runs cancel run_123 --json\n```\n\n## sessions\n\n```text\nafbin sessions script new|<id> | status <id> | close <id>\n\nRun async Playwright scripts in a persistent isolated browser session. Read afbin help live-sessions for context, pages and output.image.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --input <PATH>\n    Read command input from a local file; use - for stdin. Schedule commands take inline JSON instead.\n  --execution <ID>\n    Read a browser session execution receipt without replaying the script.\n  --as <WHO>\n    Act as somebody else: a test user id from afbin testuser new, or guest on a session. fork --as <testuser-id> gives the copy to that test user, inside its sandbox; sessions script new --as guest|<testuser-id> chooses who a NEW session's pages browse as, once, when it is created. Omit --as and everything runs as you.\n\nExamples:\n  afbin sessions script new --input actions.js --json\n  afbin sessions script new --as guest --input actions.js --json\n  afbin sessions script new --as tu_9fA2b --input actions.js --json\n  afbin sessions status session_id --execution execution_id --json\n  afbin sessions close session_id --json\n```\n\n## mention\n\n```text\nafbin mention <ref> <@username> [<@username> ...]\n\nResolve eligible @usernames to stable mentions. Save the returned markup or post the comment to notify them.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --include-access\n    Explicitly grant viewing access with invitations; requires sharing authority.\n\nExamples:\n  afbin mention a1B2c3 @alex --json\n```\n\n## invite\n\n```text\nafbin invite <ref> <@username> [<@username> ...]\n\nInvite people by username to an artifact. Auto-accept follows recipient preferences; never forces membership.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --include-access\n    Explicitly grant viewing access with invitations; requires sharing authority.\n\nExamples:\n  afbin invite a1B2c3 @alex @sam --json\n```\n\n## join\n\n```text\nafbin join <ref>\n\nJoin as yourself: owners/editors join immediately; other readers request approval.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n\nExamples:\n  afbin join a1B2c3 --json\n```\n\n## members\n\n```text\nafbin members <ref> [accept | approve <user-id> | dismiss [user-id] | leave]\n\nRead membership or accept, approve, dismiss or leave. Commenting does not require joining.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n\nExamples:\n  afbin members a1B2c3 --json\n  afbin members a1B2c3 approve usr_abc --json\n```\n\n## testuser\n\n```text\nafbin testuser new | list | delete <id> | delete --all\n\nMint, list and erase throwaway test users: the other person on a page you are verifying. Deleting one erases everything it owns.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --all\n    Erase every test user this account holds; testuser delete only.\n\nExamples:\n  afbin testuser new --json\n  afbin testuser list --json\n  afbin testuser delete tu_9fA2b --json\n  afbin testuser delete --all --json\n```\n\n## remote\n\n```text\nafbin remote [command [args ...]]\n\nStart a background agent with browser access, or attach to an existing session.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --name <NAME>\n    Select a named query, mutation or table, or name a remote terminal session.\n  --session <REF>\n    Attach to an existing authorized remote session instead of launching a command.\n  --history <PATH>\n    Snapshot a UTF-8 context handoff for the background agent.\n  --foreground\n    Keep the local terminal attached instead of launching in the background.\n  --stop <ID>\n    Stop a managed remote agent and its local process.\n  --ready <ID>\n    Acknowledge context loading from the managed agent process.\n\nExamples:\n  afbin remote pi\n  afbin remote --name codex2 codex\n  afbin remote --session rs_123\n```\n",
+        "references/commands.md": "## add\n\n```text\nafbin add <path> [<path> ...]\n\nAssign stable account-scoped identities to local files without publishing.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n\nExamples:\n  afbin add sales.csv report.jsx --json\n```\n\n## mv\n\n```text\nafbin mv <from> <to>\n\nMove a registered local file while retaining its identity.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n\nExamples:\n  afbin mv sales.csv data.csv\n```\n\n## import\n\n```text\nafbin import <file.jsx.html> [--output <file.jsx>]\n\nImport an offline HTML file into local JSX without publishing; defaults to the same basename with .jsx. Existing local documents reconcile safely.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n\nExamples:\n  afbin import report.jsx.html\n  afbin import review.jsx.html --output report.jsx\n```\n\n## preview\n\n```text\nafbin preview [<path> ...]\n\nPreview and edit local JSX files without publishing. With no paths, start an empty server for HTML imports. Directories select their JSX files.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --port <PORT>\n    Listen on this port; serve defaults to 7445, preview chooses an available one.\n  --share\n    Allow network access to the selected preview files; everyone who can reach it may edit.\n  --public-url <ORIGIN>\n    Explicit HTTPS origin of a reverse proxy serving this preview; does not change the listening interface.\n\nExamples:\n  afbin preview report.jsx appendix.jsx\n  afbin preview . --share\n```\n\n## query\n\n```text\nafbin query <ref> [<ref> ...]\n\nRead dataset rows or declared queries; --write runs a named mutation or dataset SQL.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --input <PATH>\n    Read command input from a local file; use - for stdin. Schedule commands take inline JSON instead.\n  --name <NAME>\n    Select a named query, mutation or table, or name a remote terminal session.\n  --param <NAME=VALUE>\n    Bind a named scalar parameter; repeat for distinct names.\n  --limit <N>\n    Maximum results in this page (1\u2013100).\n  --cursor <CURSOR>\n    Continue from a returned next_cursor.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n  --write\n    Execute a named document mutation or a dataset row mutation; otherwise only read.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n\nExamples:\n  afbin query sales.csv\n  afbin query report123 --name tasks\n  afbin query report123 --write --name change_status --param task_id=1 --param status=Done\n```\n\n## pull\n\n```text\nafbin pull [<ref> ...]\n\nRetrieve artifacts or account resources and reconcile tracked files.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n\nExamples:\n  afbin pull abc123 --output report.jsx\n  afbin pull report.jsx@2\n  afbin pull --type profile\n```\n\n## fork\n\n```text\nafbin fork <ref> [<ref> ...]\n\nCreate a distinct private local draft from a resource; publish it later with push. --as gives the copy to a test user instead.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --as <WHO>\n    Act as somebody else: a test user id from afbin testuser new, or guest on a session. fork --as <testuser-id> gives the copy to that test user, inside its sandbox; sessions script new --as guest|<testuser-id> chooses who a NEW session's pages browse as, once, when it is created. Omit --as and everything runs as you.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n\nExamples:\n  afbin fork abc123 --output copy.jsx\n  afbin fork report.jsx --dry-run\n  afbin fork abc123 --as tu_9fA2b --json\n```\n\n## export\n\n```text\nafbin export <ref> [<ref> ...]\n\nExport one image of the whole document, every slide stacked; --page picks one slide; --format html saves the offline file (one .jsx.html that opens, edits and comments without a connection); data and original bytes too.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --name <NAME>\n    Select a named query, mutation or table, or name a remote terminal session.\n  --page <N>\n    One slide or page only; without it the image is the whole document, every slide stacked.\n  --og\n    Export the selected social preview image: uploaded cover or saved document framing.\n  --refresh\n    Refresh the selected resources' external data or imported assets; on export, wait for a fresh image. Requires explicit targets.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n\nExamples:\n  afbin export abc123 --output report.png\n  afbin export abc123 --format html --output report.jsx.html\n  afbin export sales.csv --format json --output -\n```\n\n## push\n\n```text\nafbin push [<ref> ...]\n\nCreate, update or upload; no paths pushes changed tracked files. Markdown converts once to adjacent JSX. Program definitions use .program.json.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --access <ACCESS>\n    Publish or change a dataset's row access: read (the default) or readwrite, which a document writing to it requires.\n  --policy <POLICY>\n    Grant dataset row writes: viewers-write lets everyone who can view it insert, update and delete rows; none removes the grant.\n  --restore\n    Restore the selected soft-deleted resources; requires explicit targets.\n  --refresh\n    Refresh the selected resources' external data or imported assets; on export, wait for a fresh image. Requires explicit targets.\n  --secret-env <NAME>\n    Read a secret value from this environment variable; it is never written to YAML, journals or output.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n\nExamples:\n  afbin push report.jsx\n  afbin push worker.program.json\n  afbin push tasks.csv --type dataset --access readwrite\n  afbin push --dry-run\n  afbin push --restore abc123\n```\n\n## validate\n\n```text\nafbin validate [path ...]\n\nCheck local files without network access; --remote adds read-only server checks.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --fix\n    Apply mechanical local fixes. Push never fixes source.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n\nExamples:\n  afbin validate report.jsx\n  afbin validate --fix report.jsx\n```\n\n## status\n\n```text\nafbin status [<ref> ...]\n\nReport local changes, conflicts and installation state; remote state is last observed.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n\nExamples:\n  afbin status\n  afbin status --remote\n```\n\n## diff\n\n```text\nafbin diff [<ref> ...]\n\nCompute changes locally against the saved, historical or refreshed base.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n\nExamples:\n  afbin diff report.jsx\n  afbin diff --remote report.jsx\n```\n\n## log\n\n```text\nafbin log <ref> [<ref> ...]\n\nList versions, newest first; @version starts at that version or earlier.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --filter <FIELD=VALUE>\n    Combine supported filters; run afbin help filters for each collection.\n  --limit <N>\n    Maximum results in this page (1\u2013100).\n  --cursor <CURSOR>\n    Continue from a returned next_cursor.\n\nExamples:\n  afbin log report.jsx --limit 10\n```\n\n## list\n\n```text\nafbin list [<ref> ...]\n\nList resources or summaries; default accessible artifacts, newest first.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --in <REF>\n    Scope to a containing folder, artifact or dataset.\n  --filter <FIELD=VALUE>\n    Combine supported filters; run afbin help filters for each collection.\n  --limit <N>\n    Maximum results in this page (1\u2013100).\n  --cursor <CURSOR>\n    Continue from a returned next_cursor.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n\nExamples:\n  afbin list --json\n  afbin list --type session\n  afbin list --type table --in orders.yaml\n```\n\n## delete\n\n```text\nafbin delete <ref> [<ref> ...]\n\nSoft-delete resources, revoke tokens, terminate sessions or delete comments; keep local files.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --in <REF>\n    Scope to a containing folder, artifact or dataset.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n\nExamples:\n  afbin delete report.jsx --dry-run\n  afbin delete --type comment --in abc123 ann_123\n```\n\n## comment\n\n```text\nafbin comment <ref> [<ref> ...]\n\nList threads, post an anchored comment, reply, resolve or reopen.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --image <ID>\n    Download a comment image by its image.id from the comment listing; requires --output.\n  --variant <VARIANT>\n    Comment image: preview (default, includes drawn marks), original (without marks), or thumbnail.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --request <ID>\n    Stable idempotency identity for runs start or schedule run, or correlation for a managed agent reply.\n  --phase <PHASE>\n    Record acknowledged, completed or blocked with a reply.\n  --body <TEXT>\n    Post this comment text.\n  --input <PATH>\n    Read command input from a local file; use - for stdin. Schedule commands take inline JSON instead.\n  --thread <ID>\n    Select an existing thread for a reply or state change.\n  --node <ID>\n    Anchor a new thread to this node.\n  --quote <TEXT>\n    Anchor a new thread to this quote.\n  --state <STATE>\n    Set the selected thread to open or resolved; fixed names ignore case.\n  --filter <FIELD=VALUE>\n    Combine supported filters; run afbin help filters for each collection.\n  --limit <N>\n    Maximum results in this page (1\u2013100).\n  --cursor <CURSOR>\n    Continue from a returned next_cursor.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n\nExamples:\n  afbin comment report.jsx\n  afbin comment report.jsx --image cim_123 --output screenshot.webp\n  afbin comment report.jsx --node heading --body \"Clarify this\"\n  afbin comment report.jsx --thread ann_123 --body \"Fixed\" --state resolved\n```\n\n## open\n\n```text\nafbin open <ref> [<ref> ...]\n\nOpen the published view of a resource, or print its URL with --json.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n\nExamples:\n  afbin open report.jsx\n  afbin open abc123 --json\n```\n\n## help\n\n```text\nafbin help [topic]\n\nRead the bundled example, markup, data, themes, templates, schemas or command help; --for <template> prints everything a document of that kind needs in one call.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --for <TEMPLATE>\n    Print every reference a document of this template needs, in reading order, as one output.\n\nExamples:\n  afbin help --for deck\n  afbin help markup\n  afbin help dashboard\n```\n\n## serve\n\n```text\nafbin serve [--dir <path>] [--config <path>] [--port <port>] [--db-url <url>]\n\nRun a persistent authenticated server in the foreground.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --config <PATH>\n    Read explicit operator settings for the foreground server.\n  --dir <PATH>\n    Store server settings and uploaded objects here; defaults to ~/.artifactbin/server.\n  --db-url <URL>\n    Override the server application database with pglite:// or postgres://; object storage stays under --dir.\n  --port <PORT>\n    Listen on this port; serve defaults to 7445, preview chooses an available one.\n\nExamples:\n  afbin serve --dir ~/team-artifacts --port 7445\n  afbin serve --dir ~/team-artifacts --db-url postgres://localhost/artifactbin\n```\n\n## config\n\n```text\nafbin config get <key> | set <key> <value>\n\nRead or change client defaults without starting a server.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n\nExamples:\n  afbin config set host http://app.lvh.me:7445\n  afbin config get host\n```\n\n## auth\n\n```text\nafbin auth [<artifact>]\n\nSign in through browser approval, or use --email when a browser is unavailable.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --email <EMAIL>\n    Sign in by email OTP without opening a browser; use on remote or headless machines.\n  --otp <CODE>\n    Complete email login with the six-digit code; requires --email and does not send another code.\n\nExamples:\n  afbin auth\n  afbin auth --email you@example.com\n  afbin auth --email you@example.com --otp 123456\n```\n\n## setup\n\n```text\nafbin setup \n\nChoose and install local agent skills; remember your choices without signing in. Set ARTIFACTBIN_SKILLS=off in the environment to install no skill at all and leave every harness folder untouched \u2014 what a checkout\u2019s development loop (npm run afbin) runs under.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --harness <NAME>\n    Select a skill installation target: claude, codex, pi, opencode; repeat to select several, or use none.\n  --service <NAME>\n    Prepare a local service for offline use: sql or chromium.\n\nExamples:\n  afbin setup --service sql\n  afbin setup\n  afbin setup --yes\n  afbin setup --harness codex --harness pi\n```\n\n## update\n\n```text\nafbin update \n\nShow the npm command for your next launch with the latest version.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --harness <NAME>\n    Select a skill installation target: claude, codex, pi, opencode; repeat to select several, or use none.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n\nExamples:\n  afbin update --yes --json\n```\n\n## schedule\n\n```text\nafbin schedule create | list | get|update|pause|resume|delete|run|history <schedule-id>\n\nSchedule a live artifact with cron and timezone; inspect history or run it now. Each attempt executes the current published head.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --artifact <ID>\n    Published live artifact ID for a schedule, including program artifacts.\n  --cron <EXPRESSION>\n    Five-field cron expression interpreted in --timezone.\n  --timezone <ZONE>\n    IANA timezone, for example Asia/Kolkata or UTC.\n  --input <PATH>\n    Read command input from a local file; use - for stdin. Schedule commands take inline JSON instead.\n  --max-attempts <N>\n    Maximum attempts for a scheduled occurrence.\n  --retry-backoff <SECONDS>\n    Seconds between retry attempts.\n  --request <ID>\n    Stable idempotency identity for runs start or schedule run, or correlation for a managed agent reply.\n\nExamples:\n  afbin schedule create --artifact abc123 --cron '0 9 * * *' --timezone Asia/Kolkata --input '{\"region\":\"east\"}' --json\n  afbin schedule list --json\n  afbin schedule pause sch_123 --json\n  afbin schedule run sch_123 --json\n  afbin schedule history sch_123 --json\n```\n\n## runs\n\n```text\nafbin runs start <artifact> | status|events|cancel <run-id>\n\nExecute a published Lambda artifact and inspect its output, receipt and events. Read afbin help lambdas.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --input <PATH>\n    Read command input from a local file; use - for stdin. Schedule commands take inline JSON instead.\n  --request <ID>\n    Stable idempotency identity for runs start or schedule run, or correlation for a managed agent reply.\n  --after <SEQUENCE>\n    Read run events after this sequence (default 0).\n  --limit <N>\n    Maximum results in this page (1\u2013100).\n\nExamples:\n  afbin runs start abc123 --request weekly-1 --input input.json --json\n  afbin runs status run_123 --json\n  afbin runs events run_123 --after 0 --json\n  afbin runs cancel run_123 --json\n```\n\n## sessions\n\n```text\nafbin sessions script new|<id> | status <id> | close <id>\n\nRun async Playwright scripts in a persistent isolated browser session. Read afbin help live-sessions for context, pages and output.image.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --input <PATH>\n    Read command input from a local file; use - for stdin. Schedule commands take inline JSON instead.\n  --execution <ID>\n    Read a browser session execution receipt without replaying the script.\n  --as <WHO>\n    Act as somebody else: a test user id from afbin testuser new, or guest on a session. fork --as <testuser-id> gives the copy to that test user, inside its sandbox; sessions script new --as guest|<testuser-id> chooses who a NEW session's pages browse as, once, when it is created. Omit --as and everything runs as you.\n\nExamples:\n  afbin sessions script new --input actions.js --json\n  afbin sessions script new --as guest --input actions.js --json\n  afbin sessions script new --as tu_9fA2b --input actions.js --json\n  afbin sessions status session_id --execution execution_id --json\n  afbin sessions close session_id --json\n```\n\n## mention\n\n```text\nafbin mention <ref> <@username> [<@username> ...]\n\nResolve eligible @usernames to stable mentions. Save the returned markup or post the comment to notify them.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --include-access\n    Explicitly grant viewing access with invitations; requires sharing authority.\n\nExamples:\n  afbin mention a1B2c3 @alex --json\n```\n\n## invite\n\n```text\nafbin invite <ref> <@username> [<@username> ...]\n\nInvite people by username to an artifact. Auto-accept follows recipient preferences; never forces membership.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --include-access\n    Explicitly grant viewing access with invitations; requires sharing authority.\n\nExamples:\n  afbin invite a1B2c3 @alex @sam --json\n```\n\n## join\n\n```text\nafbin join <ref>\n\nJoin as yourself: owners/editors join immediately; other readers request approval.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n\nExamples:\n  afbin join a1B2c3 --json\n```\n\n## members\n\n```text\nafbin members <ref> [accept | approve <user-id> | dismiss [user-id] | leave]\n\nRead membership or accept, approve, dismiss or leave. Commenting does not require joining.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n\nExamples:\n  afbin members a1B2c3 --json\n  afbin members a1B2c3 approve usr_abc --json\n```\n\n## testuser\n\n```text\nafbin testuser new | list | delete <id> | delete --all\n\nMint, list and erase throwaway test users: the other person on a page you are verifying. Deleting one erases everything it owns.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --all\n    Erase every test user this account holds; testuser delete only.\n\nExamples:\n  afbin testuser new --json\n  afbin testuser list --json\n  afbin testuser delete tu_9fA2b --json\n  afbin testuser delete --all --json\n```\n\n## remote\n\n```text\nafbin remote [command [args ...]]\n\nStart a background agent with browser access, or attach to an existing session.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --name <NAME>\n    Select a named query, mutation or table, or name a remote terminal session.\n  --session <REF>\n    Attach to an existing authorized remote session instead of launching a command.\n  --history <PATH>\n    Snapshot a UTF-8 context handoff for the background agent.\n  --foreground\n    Keep the local terminal attached instead of launching in the background.\n  --stop <ID>\n    Stop a managed remote agent and its local process.\n  --ready <ID>\n    Acknowledge context loading from the managed agent process.\n\nExamples:\n  afbin remote pi\n  afbin remote --name codex2 codex\n  afbin remote --session rs_123\n```\n",
         "references/markdown.md": "# One-time Markdown import\n\nRun `afbin push report.md` to convert and publish `report.jsx`. The Markdown file stays untouched; edit and push JSX thereafter. A second Markdown push is refused, even if the generated JSX was deleted. An existing JSX destination is never overwritten.\n\n`afbin validate report.md` checks the conversion locally. `afbin push report.md --dry-run` preflights the virtual JSX without writing conversion records, files or remote objects.\n\nSupported: headings, paragraphs, emphasis, lists, block quotes, tables, links, images, fenced/inline code and horizontal rules. Raw HTML/JSX and task checkboxes are refused. Author interactive components directly in JSX. Local file references are refused. Register files with afbin add --json and use their IDs.\n",
-        "references/publishing.md": "# Files, sync and recovery\n\nA .jsx file has a YAML fence and static JSX body. The fence carries document metadata. Portable local identity, history and comments live in the workspace .artifactbin directory; credentials remain in your private home state. Keep that workspace state with the folder when moving it. Explicit push creates a per-server publication copy and local-to-remote ID mapping under .artifactbin/publications without replacing local IDs. Omitted push paths select registered and tracked files. Missing tracked files are skipped. Referenced unpublished IDs publish first; explicitly push a published dataset to update it.\n\nA CLI reference is <url|id|path>[@version]; an existing complete filename wins over an id. Published references inside markup use ref:<id>. Run afbin add --json to assign local IDs before authoring references. Publication maps those IDs and ref: references to reserved remote IDs in its server copy; the local source keeps its local identity. Existing remote documents retain their remote identity when edited.\n\nRun afbin validate report.jsx before publishing; validate --fix applies mechanical fixes. status and diff use saved state; add --remote only to refresh a comparison. An unchanged push makes no request. push --dry-run performs authoritative server validation without publishing or saving state.\n\nSuccessful writes return canonical source and identity in the same response. Push preserves edits made while the request was in flight. Retry an uncertain write with push: its frozen journal recovers the original result. A refused conflict leaves your proposal untouched and supplies a diff. pull --force overwrites local changes, so preserve a wanted proposal first; it keeps the replaced bytes under ~/.artifactbin/backups/local and reports that absolute path, archives a pending conditional proposal before replacing the working file, and cannot cancel an uncertain create. push --force observes and conditionally replaces the remote head; it never fixes markup. Deleted create results remain retired.\n\nTo adapt a document you can read, run afbin fork <ref>: it writes a private local draft without identity or invitations and records forked_from; push creates the copy. Forking a page that WRITES datasets is different: those datasets are copied under your account and the page is repointed at your copies on the server, so the fork answers status created with the id and url of that copy, and the local file is already tracked against it \u2014 edit and push to update it, never to publish a second page. fork --dry-run names the datasets first; datasets a page only reads stay shared. A historical pull keeps the current head conditions separately; pushing it performs a conditional replacement.\n\n```text\nafbin preview <path> [<path> ...]\n\nPreview and edit local JSX files without publishing. Directories select their JSX files.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --port <PORT>\n    Listen on this port; serve defaults to 7445, preview chooses an available one.\n  --share\n    Allow network access to the selected preview files; everyone who can reach it may edit.\n\nExamples:\n  afbin preview report.jsx appendix.jsx\n  afbin preview . --share\n```\n\n```text\nafbin pull [<ref> ...]\n\nRetrieve artifacts or account resources and reconcile tracked files.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n\nExamples:\n  afbin pull abc123 --output report.jsx\n  afbin pull report.jsx@2\n  afbin pull --type profile\n```\n\n```text\nafbin push [<ref> ...]\n\nCreate, update or upload; no paths pushes changed tracked files. Markdown converts once to adjacent JSX. Program definitions use .program.json.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --access <ACCESS>\n    Publish or change a dataset's row access: read (the default) or readwrite, which a document writing to it requires.\n  --policy <POLICY>\n    Grant dataset row writes: viewers-write lets everyone who can view it insert, update and delete rows; none removes the grant.\n  --restore\n    Restore the selected soft-deleted resources; requires explicit targets.\n  --refresh\n    Refresh the selected resources' external data or imported assets; on export, wait for a fresh image. Requires explicit targets.\n  --secret-env <NAME>\n    Read a secret value from this environment variable; it is never written to YAML, journals or output.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n\nExamples:\n  afbin push report.jsx\n  afbin push worker.program.json\n  afbin push tasks.csv --type dataset --access readwrite\n  afbin push --dry-run\n  afbin push --restore abc123\n```\n\n```text\nafbin validate [path ...]\n\nCheck local files without network access; --remote adds read-only server checks.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --fix\n    Apply mechanical local fixes. Push never fixes source.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n\nExamples:\n  afbin validate report.jsx\n  afbin validate --fix report.jsx\n```\n\n```text\nafbin status [<ref> ...]\n\nReport local changes, conflicts and installation state; remote state is last observed.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n\nExamples:\n  afbin status\n  afbin status --remote\n```\n\n```text\nafbin diff [<ref> ...]\n\nCompute changes locally against the saved, historical or refreshed base.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n\nExamples:\n  afbin diff report.jsx\n  afbin diff --remote report.jsx\n```\n\n## Local preview\n\nRun `afbin preview report.jsx appendix.jsx` or `afbin preview .` to view and edit files without publishing. Browser saves write to disk; clean viewers refresh after external changes. Local comments stay in client SQLite. `--share` lets anyone reaching the foreground session edit and comment on selected files. Stop with Ctrl-C.\n\nRun `afbin add <files> --json` to obtain stable IDs before writing cross-file references. Artifact source uses `ref:ID` for datasets/media and `/a/ID` for document links. Preview resolves registered local files first and other IDs through the workspace host/account. Push publishes unpublished dependencies under their reserved IDs; no path-reference rewriting occurs. Preview and push register directly named files automatically. Local preview can differ from published content until edits are pushed. Preview never increments server versions or changes the saved remote baseline.\n\n## Identity and authored scripts\n\nEvery body element has a persistent id for its lifetime. Move a node with the same id; never reuse an id for another node. Preserve existing data-annotation-anchor values with their element; never author, change or reuse one. New comments do not add it.\n\nThe Helmet script runs in the document as an ES module: it binds the declared names from `page` as Solid signals (`signal('$name')`, `query`, `mutation`) and libraries by npm name or https URL, and reaches other hosts only through `proxy(url)` from `page`, to hosts the Helmet declares with `csp-connect` and the reader allows. Account APIs, cookies and the app's storage stay out of reach.\n\nSee [authentication](publishing-auth.md) for how afbin signs in. Full replacement, metadata and folder settings are fields of the file you push.\n",
+        "references/publishing.md": "# Files, sync and recovery\n\nA .jsx file has a YAML fence and static JSX body. The fence carries document metadata. Portable local identity, history and comments live in the workspace .artifactbin directory; credentials remain in your private home state. Keep that workspace state with the folder when moving it. Explicit push creates a per-server publication copy and local-to-remote ID mapping under .artifactbin/publications without replacing local IDs. Omitted push paths select registered and tracked files. Missing tracked files are skipped. Referenced unpublished IDs publish first; explicitly push a published dataset to update it.\n\nA CLI reference is <url|id|path>[@version]; an existing complete filename wins over an id. Published references inside markup use ref:<id>. Run afbin add --json to assign local IDs before authoring references. Publication maps those IDs and ref: references to reserved remote IDs in its server copy; the local source keeps its local identity. Existing remote documents retain their remote identity when edited.\n\nRun afbin validate report.jsx before publishing; validate --fix applies mechanical fixes. status and diff use saved state; add --remote only to refresh a comparison. An unchanged push makes no request. push --dry-run performs authoritative server validation without publishing or saving state.\n\nSuccessful writes return canonical source and identity in the same response. Push preserves edits made while the request was in flight. Retry an uncertain write with push: its frozen journal recovers the original result. A refused conflict leaves your proposal untouched and supplies a diff. pull --force overwrites local changes, so preserve a wanted proposal first; it keeps the replaced bytes under ~/.artifactbin/backups/local and reports that absolute path, archives a pending conditional proposal before replacing the working file, and cannot cancel an uncertain create. push --force observes and conditionally replaces the remote head; it never fixes markup. Deleted create results remain retired.\n\nTo adapt a document you can read, run afbin fork <ref>: it writes a private local draft without identity or invitations and records forked_from; push creates the copy. Forking a page that WRITES datasets is different: those datasets are copied under your account and the page is repointed at your copies on the server, so the fork answers status created with the id and url of that copy, and the local file is already tracked against it \u2014 edit and push to update it, never to publish a second page. fork --dry-run names the datasets first; datasets a page only reads stay shared. A historical pull keeps the current head conditions separately; pushing it performs a conditional replacement.\n\n```text\nafbin preview [<path> ...]\n\nPreview and edit local JSX files without publishing. With no paths, start an empty server for HTML imports. Directories select their JSX files.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --port <PORT>\n    Listen on this port; serve defaults to 7445, preview chooses an available one.\n  --share\n    Allow network access to the selected preview files; everyone who can reach it may edit.\n  --public-url <ORIGIN>\n    Explicit HTTPS origin of a reverse proxy serving this preview; does not change the listening interface.\n\nExamples:\n  afbin preview report.jsx appendix.jsx\n  afbin preview . --share\n```\n\n```text\nafbin pull [<ref> ...]\n\nRetrieve artifacts or account resources and reconcile tracked files.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n\nExamples:\n  afbin pull abc123 --output report.jsx\n  afbin pull report.jsx@2\n  afbin pull --type profile\n```\n\n```text\nafbin push [<ref> ...]\n\nCreate, update or upload; no paths pushes changed tracked files. Markdown converts once to adjacent JSX. Program definitions use .program.json.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --access <ACCESS>\n    Publish or change a dataset's row access: read (the default) or readwrite, which a document writing to it requires.\n  --policy <POLICY>\n    Grant dataset row writes: viewers-write lets everyone who can view it insert, update and delete rows; none removes the grant.\n  --restore\n    Restore the selected soft-deleted resources; requires explicit targets.\n  --refresh\n    Refresh the selected resources' external data or imported assets; on export, wait for a fresh image. Requires explicit targets.\n  --secret-env <NAME>\n    Read a secret value from this environment variable; it is never written to YAML, journals or output.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n\nExamples:\n  afbin push report.jsx\n  afbin push worker.program.json\n  afbin push tasks.csv --type dataset --access readwrite\n  afbin push --dry-run\n  afbin push --restore abc123\n```\n\n```text\nafbin validate [path ...]\n\nCheck local files without network access; --remote adds read-only server checks.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --fix\n    Apply mechanical local fixes. Push never fixes source.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n\nExamples:\n  afbin validate report.jsx\n  afbin validate --fix report.jsx\n```\n\n```text\nafbin status [<ref> ...]\n\nReport local changes, conflicts and installation state; remote state is last observed.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n\nExamples:\n  afbin status\n  afbin status --remote\n```\n\n```text\nafbin diff [<ref> ...]\n\nCompute changes locally against the saved, historical or refreshed base.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --remote\n    Fetch current remote state; comparison still runs locally.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n\nExamples:\n  afbin diff report.jsx\n  afbin diff --remote report.jsx\n```\n\n## Local preview\n\nRun `afbin preview report.jsx appendix.jsx` or `afbin preview .` to view and edit files without publishing. Run `afbin preview --port 7474` without paths for an empty import server: open its URL to Import an HTML file, or choose Connect to server in an offline .jsx.html file and enter http://localhost:7474. Confirm the workspace filename with Import and open. The original HTML stays unchanged; the server imports a copy with existing validation/conflict checks, then browser edits and comments save to that workspace. No other files are implicitly selected. Compatible hosted preview services use an explicit HTTPS reverse-proxy origin declared with --public-url https://preview.example.com; it does not change the listening interface. Browser saves write to disk; clean viewers refresh after external changes. Local comments stay in client SQLite. `--share` lets anyone reaching the foreground session edit and comment on selected files. Stop with Ctrl-C.\n\nRun `afbin add <files> --json` to obtain stable IDs before writing cross-file references. Artifact source uses `ref:ID` for datasets/media and `/a/ID` for document links. Preview resolves registered local files first and other IDs through the workspace host/account. Push publishes unpublished dependencies under their reserved IDs; no path-reference rewriting occurs. Preview and push register directly named files automatically. Local preview can differ from published content until edits are pushed. Preview never increments server versions or changes the saved remote baseline.\n\n## Identity and authored scripts\n\nEvery body element has a persistent id for its lifetime. Move a node with the same id; never reuse an id for another node. Preserve existing data-annotation-anchor values with their element; never author, change or reuse one. New comments do not add it.\n\nThe Helmet script runs in the document as an ES module: it binds the declared names from `page` as Solid signals (`signal('$name')`, `query`, `mutation`) and libraries by npm name or https URL, and reaches other hosts only through `proxy(url)` from `page`, to hosts the Helmet declares with `csp-connect` and the reader allows. Account APIs, cookies and the app's storage stay out of reach.\n\nSee [authentication](publishing-auth.md) for how afbin signs in. Full replacement, metadata and folder settings are fields of the file you push.\n",
         "references/publishing-auth.md": "# Authentication and local installation\n\nPrepare Node/npm if needed using the selected server helpers: __AFBIN_SERVER__/chat/ensure-node.sh (macOS/Linux), or __AFBIN_SERVER__/chat/ensure-node.ps1 (Windows PowerShell). The helper reuses supported Node or installs official LTS for your user. Run `npx --yes @afbin/cli@latest <command>`; PowerShell uses `npx.cmd --yes @afbin/cli@latest <command>`. `afbin` below is shorthand. npm owns package installation and version selection; afbin never replaces a running executable. `afbin update` only prints the command for your next launch; it does not replace binaries or install skills. Use `afbin setup` for local skill installation. If a harness loads skills at startup, restart it when setup reports `restart_required`.\n\nafbin authenticates itself the first time a command needs the server: it opens browser approval (log in, or continue anonymously), waits, and resumes the command \u2014 nothing to paste, no token you or the agent handle. Run afbin auth to establish or check credentials deliberately; it is idempotent. Credentials live in ~/.artifactbin/hosts/<origin-id>/credentials.env (0600), inside ~/.artifactbin (0700). Environment credentials override saved credentials and remain origin-scoped. Local help, validation, status and diff never sign in or create state.\n\nWhen a browser is unavailable (remote/headless), run `afbin auth --email <email>` directly: it sends a code and returns `otp_required` without waiting. Ask the user for their email and then the emailed code. Complete login with `afbin auth --email <email> --otp <code>`; this never opens a browser or resends the code. Add the same `--server <origin>` to both commands for another server. Email login selects that email account even if a connection is already saved. For an artifact owned by a guest browser, email login does not transfer ownership; use the owning browser to connect it.\n\nBrowser launch failure returns `browser_unavailable` immediately and keeps the pairing: approving the printed code on any device lets a rerun of the same command continue. The waiting message and timeout errors recommend `afbin auth --email <email>`; agents should ask for the email and use this fallback, then retry the original command. Agents need not invoke auth in the normal browser path; a server command signs in on demand and resumes once approved. On an unattended approval timeout the command returns a structured error carrying the approval URL and expiry to relay to a person. Denial and expiry never create credentials. Connected commands show newer-version notices from their normal server responses, at most hourly. Local-only commands make no update requests. `afbin config set updates false` disables notices; update by launching the explicit npm command shown.\n\nCredentials are kept per server origin under ~/.artifactbin (one file per origin), so `--server`, a tracked workspace or an exported ARTIFACTBIN_URL selects the matching credential without re-approval; login never changes the default. Use `afbin config set host <origin>` to select it. Set ARTIFACTBIN_HOME to use a different private state directory, for example one per environment; exported variables reach every afbin your agent runs.\n\n```text\nafbin auth [<artifact>]\n\nSign in through browser approval, or use --email when a browser is unavailable.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --email <EMAIL>\n    Sign in by email OTP without opening a browser; use on remote or headless machines.\n  --otp <CODE>\n    Complete email login with the six-digit code; requires --email and does not send another code.\n\nExamples:\n  afbin auth\n  afbin auth --email you@example.com\n  afbin auth --email you@example.com --otp 123456\n```\n\n```text\nafbin update \n\nShow the npm command for your next launch with the latest version.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --harness <NAME>\n    Select a skill installation target: claude, codex, pi, opencode; repeat to select several, or use none.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n\nExamples:\n  afbin update --yes --json\n```\n\n```text\nafbin serve [--dir <path>] [--config <path>] [--port <port>] [--db-url <url>]\n\nRun a persistent authenticated server in the foreground.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --config <PATH>\n    Read explicit operator settings for the foreground server.\n  --dir <PATH>\n    Store server settings and uploaded objects here; defaults to ~/.artifactbin/server.\n  --db-url <URL>\n    Override the server application database with pglite:// or postgres://; object storage stays under --dir.\n  --port <PORT>\n    Listen on this port; serve defaults to 7445, preview chooses an available one.\n\nExamples:\n  afbin serve --dir ~/team-artifacts --port 7445\n  afbin serve --dir ~/team-artifacts --db-url postgres://localhost/artifactbin\n```\n\n## One server, several addresses\n\nA deployment may answer at more than one hostname \u2014 a marketing name that proxies to the app, or a previous name kept alive. afbin asks the origin you selected which addresses it answers at, and believes an alias only when the canonical origin's own answer names it: the two origins have to agree. A URL copied from either name then resolves to the same artifact, a folder tracked against one keeps working when the other is selected, and browser approval shown on either is accepted. Requests and credentials always go to the canonical origin of the server YOU selected \u2014 never to an origin a pasted URL named, and never to an alias; a pasted URL supplies its artifact id and nothing else. A server that publishes no addresses behaves exactly as before, with the two origins separate. Self-hosters list the extra origins in `APP__ALIAS_ORIGINS` on the deployment; `APP__PUBLIC_BASE_URL` stays the canonical one.\n\n`afbin serve --dir ./team --port 7445` initializes and runs an authenticated server in the foreground. Its directory owns settings, objects and the default PGLite database. `--db-url postgres://\u2026` or `--db-url pglite://\u2026` overrides only the application database. Server settings are separate from client defaults and per-host credentials. There is no managed self daemon.\n",
         "references/publishing-annotations.md": '# Comments\n\nUse the artifact reference consistently. New threads use exactly one node ID or quote. An ambiguous quote is refused; use the returned current node IDs. Replies name a thread on the same artifact. Pagination applies only to listing.\n\n```text\nafbin comment <ref> [<ref> ...]\n\nList threads, post an anchored comment, reply, resolve or reopen.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --image <ID>\n    Download a comment image by its image.id from the comment listing; requires --output.\n  --variant <VARIANT>\n    Comment image: preview (default, includes drawn marks), original (without marks), or thumbnail.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --request <ID>\n    Stable idempotency identity for runs start or schedule run, or correlation for a managed agent reply.\n  --phase <PHASE>\n    Record acknowledged, completed or blocked with a reply.\n  --body <TEXT>\n    Post this comment text.\n  --input <PATH>\n    Read command input from a local file; use - for stdin. Schedule commands take inline JSON instead.\n  --thread <ID>\n    Select an existing thread for a reply or state change.\n  --node <ID>\n    Anchor a new thread to this node.\n  --quote <TEXT>\n    Anchor a new thread to this quote.\n  --state <STATE>\n    Set the selected thread to open or resolved; fixed names ignore case.\n  --filter <FIELD=VALUE>\n    Combine supported filters; run afbin help filters for each collection.\n  --limit <N>\n    Maximum results in this page (1\u2013100).\n  --cursor <CURSOR>\n    Continue from a returned next_cursor.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n\nExamples:\n  afbin comment report.jsx\n  afbin comment report.jsx --image cim_123 --output screenshot.webp\n  afbin comment report.jsx --node heading --body "Clarify this"\n  afbin comment report.jsx --thread ann_123 --body "Fixed" --state resolved\n```\n\n## Inspect comment screenshots\n\nRead the thread with afbin comment <artifact> --json (follow next_cursor if needed). For each attached image.id relevant to the request, after acknowledging run afbin comment <artifact> --image <image-id> --output <fresh-workspace-path>.webp --json, then open the returned path with your image viewing tool before answering. The default preview includes drawn marks; --variant original omits them. This downloads the saved capture, not a new rendering of the document. Use this authenticated CLI download for image bytes; metadata URLs are browser-session endpoints. If download fails or your model cannot inspect images, reply blocked and state the limitation; never describe unseen pixels from the snippet or surrounding document.\n\nComments are sidecar relations to the node\'s persistent BODY `id`; reading or writing a comment does not rewrite source or flush the editor. Legacy data-annotation-anchor attributes are preservation-only: preserve an existing value with its element; never author, change or reuse one. New comments do not add it.\n\nListing a document returns its OPEN threads only. Read the ones already settled with `afbin comment <ref> --filter state=resolved`, or both lists at once with `--filter state=all`.\n\n"snippet" is the current node text. "quote" is the selected text; quote_found says whether it is still present. Comment Markdown supports links and emphasis: `![alt](url)` is not an image, but a literal exclamation mark plus a link. A comment cannot embed a picture. A deleted thread is not erased; there is no undo for it here.\n\nBearer requests retain their account attribution.\n',
         "references/publishing-datasets.md": '# Datasets and media\n\nRegister CSV, JSON or GeoJSON files with afbin add --json and import the returned ref:ID with <Import name="d" src="ref:ID" />. A `.geojson` file becomes one row per feature plus a `geometry` column (`afbin help markup-maps`). Push accepts file paths directly. SQL names d.rows for a flat dataset (each catalog table as d.<table>); data="$query" binds the result. A connected Postgres query runs inside it: <Query source="ref:<id>">. A dataset pushed without flags lets everyone read it and lets its owner\'s pages write it for their accepted members (`afbin help apps`). Add `--policy viewers-write` to the push that CREATES it when everyone who can open the page must be able to write rows without joining: a dataset created without it keeps its default policy, which the flag cannot replace. Finer rules live in the dataset YAML\'s policy.\n\nTyped user columns use a dataset YAML resource pointing at a `<Dataset>` JSX definition: `afbin help users` contains the complete files and publish command.\n\nImages and PDFs use their native formats; other supported files use file artifacts. Accepted file extensions: mp4, webm, mov; mp3, wav, ogg, m4a, flac; glb, gltf, obj, fbx, stl; png, jpg, jpeg, webp, gif, svg, avif; pdf, txt, csv, json, xlsx; woff, woff2, ttf, otf; zip (default limit 50 MB, FILES__MAX_BYTES). Artifact references use IDs, never local paths. Each registered file retains its identity through preview and publication. Standalone asset replacement reports affected dependents. Read [data authoring](markup-data.md) and [catalogs](databases.md) when using connected or multi-table datasets; connection, table and notebook definitions live in dataset YAML.\n\n```text\nafbin push [<ref> ...]\n\nCreate, update or upload; no paths pushes changed tracked files. Markdown converts once to adjacent JSX. Program definitions use .program.json.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  --access <ACCESS>\n    Publish or change a dataset\'s row access: read (the default) or readwrite, which a document writing to it requires.\n  --policy <POLICY>\n    Grant dataset row writes: viewers-write lets everyone who can view it insert, update and delete rows; none removes the grant.\n  --restore\n    Restore the selected soft-deleted resources; requires explicit targets.\n  --refresh\n    Refresh the selected resources\' external data or imported assets; on export, wait for a fresh image. Requires explicit targets.\n  --secret-env <NAME>\n    Read a secret value from this environment variable; it is never written to YAML, journals or output.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n\nExamples:\n  afbin push report.jsx\n  afbin push worker.program.json\n  afbin push tasks.csv --type dataset --access readwrite\n  afbin push --dry-run\n  afbin push --restore abc123\n```\n\n```text\nafbin pull [<ref> ...]\n\nRetrieve artifacts or account resources and reconcile tracked files.\n\n  -h, --help\n    Show local command help.\n  --version\n    Show the installed CLI version.\n  --json\n    Write one JSON document to stdout; diagnostics go to stderr.\n  --server <URL>\n    Use this server origin for this command.\n  -y, --yes\n    Accept confirmation defaults for this operation; never bypass authentication.\n  --type <TYPE>\n    Select the resource kind: artifact, folder, dataset, file, profile or session; list adds table; delete adds comment. Fixed names ignore case.\n  -o, --output <PATH>\n    Write resulting content to this file or directory.\n  --format <FORMAT>\n    Select a supported content representation; fixed format names ignore case.\n  -n, --dry-run\n    Validate the operation without changing local or remote state.\n  -f, --force\n    Overwrite local changes on pull, or observe and conditionally replace a stale head on push. On delete, allow referenced assets.\n\nExamples:\n  afbin pull abc123 --output report.jsx\n  afbin pull report.jsx@2\n  afbin pull --type profile\n```\n\nA stored `<Table>` that declares its `columns` may start with `rows={[]}`: a sheet the people using the page fill in later publishes empty, with its shape, and needs no seed row. A dataset published `--policy viewers-write` stays its OWNER\'s to re-push \u2014 new rows, new columns, the grant kept \u2014 as long as the columns the policy names are still there; anyone else with edit access is refused `policy_locked`, and a governed dataset is never reverted, because viewers\' rows are in it. Read an earlier version with `afbin pull <id>@<v> --output -` or take a copy with `afbin fork <id>@<v>`, then push the content you want.\n\nAn imported URL is NOT an artifact and never appears in `afbin list`. Imported bytes count against your ACCOUNT\'s byte quota; a URL is charged once, to whoever first named the URL. Your external URL stays in the document while the server serves its stored copy.\n',
@@ -18354,7 +18365,7 @@ var init_teaching = __esm({
         "references/design.md": "## Read first\n\nThree choices, in this order, each from its own reference: the PAGE TYPE\nfrom the content's shape ([templates.md](templates.md)), the DESIGN SYSTEM\nfrom the subject's world ([design-systems.md](design-systems.md)), then\nthe THESIS from the subject itself (below). The system carries the fonts,\nthe palette, both colour modes, the type roles and the components; what\nyour own Helmet CSS adds, you carry yourself:\n\n- **A family the system lacks is a Helmet meta**:\n  `<meta name=\"font-display\" content=\"Lobster\" />` (also `font-body`,\n  `font-mono`) names a Google family; the page imports it from Google Fonts.\n  Spend it only where the subject demands a face no system carries.\n- Utilities compile `!important`; never fight one from a style block. Give\n  keyboard focus a visible state.\n\n**Plans:** UI plans use [templates-plan.md](templates-plan.md); other workflows use\nuseful visuals. Todos use plain lists or tables, without checkboxes. Strike\ncompleted labels (`<s>`), preserving context. Save progress by editing.\n\n## Ground it in the subject\n\n- Pin one concrete subject, its audience, and the page's single job before\n  authoring.\n- Build with real content throughout, never lorem placeholder.\n\n## The thesis\n\nOne sentence before you build: the reader's benefit, the organizing visual\nidea, and how the evidence or the actions fit it. \"A shift briefing that\nsurfaces the queue with the largest overdue backlog, then opens its ledger\"\nis a thesis; \"clean, modern, blue\" is a style label. The thesis names\ntwo things the system never supplies:\n\n- **The object.** One thing from the subject's own world, drawn in the\n  system's hand (its `h-*` classes) and carried through the chapter labels,\n  the figure numbering and one small drawing: the page's motif. One\n  object, total commitment, no second conceit; a quiet thesis in a deadpan\n  register is as valid as a loud one.\n- **The device.** Which of the system's devices carries the data: the split\n  bar, the stamp, the ledger. The data lives inside it.\n\nName the rejected default too: the composition any similar page would\nhave had; if your thesis is that default, revise it. Record system and\nthesis in the Helmet comment, so a later edit extends the design instead of reskinning it.\n\n## Hierarchy\n\n- One idea per viewport. A headline states the FINDING (\"Churn halved after\n  onboarding\"), never the topic (\"Churn analysis\").\n- Contrast in size is the design: small uppercase tracked eyebrows against\n  large tight headlines beats five mid-sized headings.\n- Body copy caps at `max-w-prose` (~65ch); evidence (charts, tables) breaks\n  wider. Width contrast IS the layout.\n\n## Typography\n\n- The PAIRING comes with the system, chosen as a set; never fight it with a\n  second family. Its type roles (`t-display-l`, `t-title`, `t-body`,\n  `t-label`, `t-numeral`) set size, leading, weight and tracking; headings\n  take the display face without a class.\n- Spend the roles in three jobs. DISPLAY carries the argument: few, large,\n  sentence case. BODY carries reading, capped at `max-w-prose`. UTILITY\n  carries the apparatus: eyebrows, folios, figure numbers, table digits.\n- Stay on the system's scale; a size utility on an element that carries a\n  role replaces the role, so put layout utilities there and never type ones.\n\n## Space\n\n- Whitespace is structure, not waste. Pad sections generously (`py-16`); the\n  gap between sections exceeds the gap within one. Space sibling groups with\n  flex/grid `gap-*`, not per-element margins.\n- Align to the grid; when in doubt, flush left. Centered body copy is almost\n  always wrong. Wide content (tables, code) gets its own `overflow-x-auto`\n  container; the page never scrolls sideways.\n\n## Colour\n\n- The system owns hue: author in its token classes. A subject that needs its\n  own hue gets ONE `--ds-*` token reassigned under `:root` and `.dark`, and\n  every component, chart and device follows; never a second palette.\n- ONE accent, meaning one thing (the subject, the exception). Context sits in\n  the system's quiet grounds. If everything is highlighted, nothing is.\n- Status colour (positive, caution, negative) is separate from the accent and\n  always travels with a word or a glyph, never colour alone.\n\n## Motion\n\n- Motion deliberately: one orchestrated moment lands harder than scattered\n  effects, and extra animation reads as AI-generated. The vocabulary is\n  [markup-motion.md](markup-motion.md); the system's motion rules set the register.\n\n## Charts\n\n- Label axes with names, units and ticks. Keep legends unless directly labeled.\n- The system's chart series order, unless the user requests custom colours.\n  [Chart guidance](markup-data-authoring.md).\n\n## Structure is information\n\n- Eyebrows, numbering, dividers and labels must encode something TRUE about\n  the content, not decorate it.\n- Numbered markers (01 / 02 / 03) only when the content really is a sequence\n  whose order the reader needs.\n\n## Avoid the default AI look\n\nUnprompted AI design clusters around a few looks: cream + serif + terracotta;\nnear-black with one acid accent; a purple-blue gradient hero; emoji as\nsection markers; everything centered; rounded cards with accent rails. If\nyour user asks for one of these, follow their words exactly;\n\n## Restraint\n\n- Prefer plain typography over one more Card. Decoration that carries no\n  information comes out.\n",
         "references/markup-data-authoring.md": "## Read first\n\n## Build chart attributes without counting braces\n\nConstruct the viz object as JSON, then serialize it inside ONE JSX expression.\nUse the generated element in the document. JavaScript's `JSON.stringify` works\nthe same way. After a brace error, regenerate the attribute from the object;\ndo not repeatedly patch a guessed run of closing braces.\n\n## Preserve what the statistic means\n\nCheck the input row's grain before aggregating. Averages or medians of group\nmedians are not the average or median of the underlying observations. Preserve\nthe supplied groups, or explicitly label the derived statistic (for example,\n\"average of monthly medians\"). Never silently\nsubstitute `avg` for `median`.\n",
         "references/markup.md": '## Start\n\n`markup` is **static JSX data** over the component registry.\nMarkup carries content, data and layout; the Helmet script carries behaviour.\n\n- **Static JSX only**: literal props (strings, numbers, booleans, arrays,\n  `{{\u2026}}` objects), plus safe signal conditions; no arbitrary expressions,\n  spreads or inline handlers (`onClick=` is\n  rejected; the Helmet script attaches handlers with `addEventListener`). In\n  JSX, every tag closes (`<br />`); use `{/* \u2026 */}` comments; omit\n  `<html>`/`<head>`/`<body>`.\n- **Style with Tailwind classes via `className`**, starting from a\n  `<div data-design="tw" className="@container \u2026">` wrapper with `@2xl:`\n  container variants for responsive layout.\n- Data (`<Import>`, `<Value>`, `<Query>`, `<Mutation>`, embeds, controls): [data](markup-data.md).\n  Editable dataset cells: [editing](markup-editing.md).\n  [motion](markup-motion.md) \xB7 [svg](markup-svg.md).\n\n## Component vocabulary (the complete allowlist)\n\nKit components (85):\n`Dialog DialogTrigger DialogContent DialogClose Mermaid DeckGL Card CardHeader CardTitle CardDescription CardContent CardFooter CardAction Badge Button Alert AlertTitle AlertDescription Table TableHeader TableBody TableFooter TableRow TableHead TableCell TableCaption Separator Skeleton Progress Breadcrumb BreadcrumbList BreadcrumbItem BreadcrumbLink BreadcrumbPage BreadcrumbSeparator BreadcrumbEllipsis Avatar AvatarImage AvatarFallback AvatarBadge AvatarGroup AvatarGroupCount Tabs TabsList TabsTrigger TabsContent Accordion AccordionItem AccordionTrigger AccordionContent Collapsible CollapsibleTrigger CollapsibleContent Tooltip TooltipTrigger TooltipContent TooltipProvider Popover PopoverTrigger PopoverContent PopoverAnchor PopoverHeader PopoverTitle PopoverDescription Grid GridItem Input Textarea Select Slider DatePicker Segmented Switch SlideDeck Slide File Icon User UserImage UserHandle SignIn DataTable Column For Files`\n\nPlus the embeds `Question` `Number` and Helmet\'s `Import` `Value` `Query`\n`Mutation`; a name outside it is rejected with the registry echoed\nback. Unknown props are ignored; bindings and Column contracts are checked at\npublish.\n\n[Conditions and dialogs](markup-state.md).\n\n**HTML tags: write the ordinary tag you mean** \u2014 105 are allowed\n(prose, headings, lists, tables, links, media, the bare controls `input`\n`select` `textarea` `button` (themed), SVG): an unlisted tag returns `400`\nwith `allowed_html_tags`. Only these are refused\noutright, no list: `script` `object` `embed` `base` `meta` `link` `form` `frame` `frameset` `applet` `noscript` .\n\n## `<Helmet>` \u2014 the document\'s own head\n\nAt most ONE per document, holding at most one each of `<title>`, `<style>`\nand `<script>`, plus `<meta name content />` pairs, plus any number of the\nDATA declarations `<Import>`, `<Value>`, `<Query>`, `<Mutation>` ([data](markup-data.md)).\nWrite it anywhere; it is hoisted when stored.\n\n```jsx\n<Helmet>\n  <title>Quarterly review</title>\n  <style>{`.rise { animation: rise .9s both } @keyframes rise { from { opacity: 0 } }`}</style>\n</Helmet>\n```\n\nThe `<script>` is an ES module in the document: Solid bound to the declared\nnames, npm libraries, exported components \u2014 [scripts](markup-scripts.md).\n\n- **Custom CSS lives in that `<style>` block**; an inline `style={{\u2026}}` is fine\n  for a one-off. Scope rules to your own class names (bare element selectors\n  leak into chart chrome); colors from theme tokens (`var(--primary)`).\n  **Utilities compile `!important`** \u2014 never fight a Tailwind class from a\n  style block. CSS is unconstrained: `position: fixed`/`sticky`, `vh` (the\n  real viewport), `@import url(\u2026)`, `url()` and `@font-face` all work.\n  There is no `<link>` and no body `<style>`.\n- **Override a theme** in that block under `:root` \u2014 no theme-name selector\n  or `!important`: `:root { --background: #0c0d0e; --primary: #ff6a1f; --chart-1: #ec6100; --font-display: Georgia, serif; }`.\n- **Theme tokens first**: `text-muted-foreground`, `bg-muted`, `border-border`,\n  `bg-background` follow the active theme; hardcoded palettes fight it. ONE\n  bespoke accent (`text-[#e2483d]`) is legitimate for the one bold moment \u2014\n  it will not follow a later theme switch.\n- `theme`, `template` and `colorMode` are top-level fields of the YAML fence\n  atop the file you push, not Helmet content. No page type named \u2192 pick\n  it from the content\'s shape ([templates.md](templates.md)); torn \u2192 ask the user. `colorMode`\n  (`light | dark`) is the AUTHOR\'S DEFAULT \u2014 readers flip it, so design in theme tokens.\n\n## Images and icons\n\nGalleries: [image bindings](markup-repeat.md).\n\n- `<img src="ref:<imageId>" />` \u2014 an [uploaded image](publishing-datasets.md).\n  Web URLs also work and are served as written.\n- In parent markup only `<img src>` and `<File src>` take a URL;\n  `srcSet`/`background` reject an external one. `href` is free.\n- `<iframe src="https://\u2026" title="\u2026" />` frames a player: YouTube\n  (nocookie), Vimeo, Loom; others need `csp-frame`.\n- `<Icon name="chart-bar" />` \u2014 a lucide icon, inline (kebab-case names from\n  lucide.dev). Size it with a `size-*` class; it inherits `currentColor`.\n\n[Scripts, components and libraries (Three.js)](markup-scripts.md).\n',
-        "references/publishing.md": "# Files, sync and recovery\n\nA .jsx file has a YAML fence and static JSX body. The fence carries document metadata. Portable local identity, history and comments live in the workspace .artifactbin directory; credentials remain in your private home state. Keep that workspace state with the folder when moving it. Explicit push creates a per-server publication copy and local-to-remote ID mapping under .artifactbin/publications without replacing local IDs. Omitted push paths select registered and tracked files. Missing tracked files are skipped. Referenced unpublished IDs publish first; explicitly push a published dataset to update it.\n\nA CLI reference is <url|id|path>[@version]; an existing complete filename wins over an id. Published references inside markup use ref:<id>. Run afbin add --json to assign local IDs before authoring references. Publication maps those IDs and ref: references to reserved remote IDs in its server copy; the local source keeps its local identity. Existing remote documents retain their remote identity when edited.\n\nRun afbin validate report.jsx before publishing; validate --fix applies mechanical fixes. status and diff use saved state; add --remote only to refresh a comparison. An unchanged push makes no request. push --dry-run performs authoritative server validation without publishing or saving state.\n\nSuccessful writes return canonical source and identity in the same response. Push preserves edits made while the request was in flight. Retry an uncertain write with push: its frozen journal recovers the original result. A refused conflict leaves your proposal untouched and supplies a diff. pull --force overwrites local changes, so preserve a wanted proposal first; it keeps the replaced bytes under ~/.artifactbin/backups/local and reports that absolute path, archives a pending conditional proposal before replacing the working file, and cannot cancel an uncertain create. push --force observes and conditionally replaces the remote head; it never fixes markup. Deleted create results remain retired.\n\nTo adapt a document you can read, run afbin fork <ref>: it writes a private local draft without identity or invitations and records forked_from; push creates the copy. Forking a page that WRITES datasets is different: those datasets are copied under your account and the page is repointed at your copies on the server, so the fork answers status created with the id and url of that copy, and the local file is already tracked against it \u2014 edit and push to update it, never to publish a second page. fork --dry-run names the datasets first; datasets a page only reads stay shared. A historical pull keeps the current head conditions separately; pushing it performs a conditional replacement.\n\n## Local preview\n\nRun `afbin preview report.jsx appendix.jsx` or `afbin preview .` to view and edit files without publishing. Browser saves write to disk; clean viewers refresh after external changes. Local comments stay in client SQLite. `--share` lets anyone reaching the foreground session edit and comment on selected files. Stop with Ctrl-C.\n\nRun `afbin add <files> --json` to obtain stable IDs before writing cross-file references. Artifact source uses `ref:ID` for datasets/media and `/a/ID` for document links. Preview resolves registered local files first and other IDs through the workspace host/account. Push publishes unpublished dependencies under their reserved IDs; no path-reference rewriting occurs. Preview and push register directly named files automatically. Local preview can differ from published content until edits are pushed. Preview never increments server versions or changes the saved remote baseline.\n\n## Identity and authored scripts\n\nEvery body element has a persistent id for its lifetime. Move a node with the same id; never reuse an id for another node. Preserve existing data-annotation-anchor values with their element; never author, change or reuse one. New comments do not add it.\n\nThe Helmet script runs in the document as an ES module: it binds the declared names from `page` as Solid signals (`signal('$name')`, `query`, `mutation`) and libraries by npm name or https URL, and reaches other hosts only through `proxy(url)` from `page`, to hosts the Helmet declares with `csp-connect` and the reader allows. Account APIs, cookies and the app's storage stay out of reach.\n\nSee [authentication](publishing-auth.md) for how afbin signs in. Full replacement, metadata and folder settings are fields of the file you push.\n",
+        "references/publishing.md": "# Files, sync and recovery\n\nA .jsx file has a YAML fence and static JSX body. The fence carries document metadata. Portable local identity, history and comments live in the workspace .artifactbin directory; credentials remain in your private home state. Keep that workspace state with the folder when moving it. Explicit push creates a per-server publication copy and local-to-remote ID mapping under .artifactbin/publications without replacing local IDs. Omitted push paths select registered and tracked files. Missing tracked files are skipped. Referenced unpublished IDs publish first; explicitly push a published dataset to update it.\n\nA CLI reference is <url|id|path>[@version]; an existing complete filename wins over an id. Published references inside markup use ref:<id>. Run afbin add --json to assign local IDs before authoring references. Publication maps those IDs and ref: references to reserved remote IDs in its server copy; the local source keeps its local identity. Existing remote documents retain their remote identity when edited.\n\nRun afbin validate report.jsx before publishing; validate --fix applies mechanical fixes. status and diff use saved state; add --remote only to refresh a comparison. An unchanged push makes no request. push --dry-run performs authoritative server validation without publishing or saving state.\n\nSuccessful writes return canonical source and identity in the same response. Push preserves edits made while the request was in flight. Retry an uncertain write with push: its frozen journal recovers the original result. A refused conflict leaves your proposal untouched and supplies a diff. pull --force overwrites local changes, so preserve a wanted proposal first; it keeps the replaced bytes under ~/.artifactbin/backups/local and reports that absolute path, archives a pending conditional proposal before replacing the working file, and cannot cancel an uncertain create. push --force observes and conditionally replaces the remote head; it never fixes markup. Deleted create results remain retired.\n\nTo adapt a document you can read, run afbin fork <ref>: it writes a private local draft without identity or invitations and records forked_from; push creates the copy. Forking a page that WRITES datasets is different: those datasets are copied under your account and the page is repointed at your copies on the server, so the fork answers status created with the id and url of that copy, and the local file is already tracked against it \u2014 edit and push to update it, never to publish a second page. fork --dry-run names the datasets first; datasets a page only reads stay shared. A historical pull keeps the current head conditions separately; pushing it performs a conditional replacement.\n\n## Local preview\n\nRun `afbin preview report.jsx appendix.jsx` or `afbin preview .` to view and edit files without publishing. Run `afbin preview --port 7474` without paths for an empty import server: open its URL to Import an HTML file, or choose Connect to server in an offline .jsx.html file and enter http://localhost:7474. Confirm the workspace filename with Import and open. The original HTML stays unchanged; the server imports a copy with existing validation/conflict checks, then browser edits and comments save to that workspace. No other files are implicitly selected. Compatible hosted preview services use an explicit HTTPS reverse-proxy origin declared with --public-url https://preview.example.com; it does not change the listening interface. Browser saves write to disk; clean viewers refresh after external changes. Local comments stay in client SQLite. `--share` lets anyone reaching the foreground session edit and comment on selected files. Stop with Ctrl-C.\n\nRun `afbin add <files> --json` to obtain stable IDs before writing cross-file references. Artifact source uses `ref:ID` for datasets/media and `/a/ID` for document links. Preview resolves registered local files first and other IDs through the workspace host/account. Push publishes unpublished dependencies under their reserved IDs; no path-reference rewriting occurs. Preview and push register directly named files automatically. Local preview can differ from published content until edits are pushed. Preview never increments server versions or changes the saved remote baseline.\n\n## Identity and authored scripts\n\nEvery body element has a persistent id for its lifetime. Move a node with the same id; never reuse an id for another node. Preserve existing data-annotation-anchor values with their element; never author, change or reuse one. New comments do not add it.\n\nThe Helmet script runs in the document as an ES module: it binds the declared names from `page` as Solid signals (`signal('$name')`, `query`, `mutation`) and libraries by npm name or https URL, and reaches other hosts only through `proxy(url)` from `page`, to hosts the Helmet declares with `csp-connect` and the reader allows. Account APIs, cookies and the app's storage stay out of reach.\n\nSee [authentication](publishing-auth.md) for how afbin signs in. Full replacement, metadata and folder settings are fields of the file you push.\n",
         "references/publishing-auth.md": "# Authentication and local installation\n\nPrepare Node/npm if needed using the selected server helpers: __AFBIN_SERVER__/chat/ensure-node.sh (macOS/Linux), or __AFBIN_SERVER__/chat/ensure-node.ps1 (Windows PowerShell). The helper reuses supported Node or installs official LTS for your user. Run `npx --yes @afbin/cli@latest <command>`; PowerShell uses `npx.cmd --yes @afbin/cli@latest <command>`. `afbin` below is shorthand. npm owns package installation and version selection; afbin never replaces a running executable. `afbin update` only prints the command for your next launch; it does not replace binaries or install skills. Use `afbin setup` for local skill installation. If a harness loads skills at startup, restart it when setup reports `restart_required`.\n\nafbin authenticates itself the first time a command needs the server: it opens browser approval (log in, or continue anonymously), waits, and resumes the command \u2014 nothing to paste, no token you or the agent handle. Run afbin auth to establish or check credentials deliberately; it is idempotent. Credentials live in ~/.artifactbin/hosts/<origin-id>/credentials.env (0600), inside ~/.artifactbin (0700). Environment credentials override saved credentials and remain origin-scoped. Local help, validation, status and diff never sign in or create state.\n\nWhen a browser is unavailable (remote/headless), run `afbin auth --email <email>` directly: it sends a code and returns `otp_required` without waiting. Ask the user for their email and then the emailed code. Complete login with `afbin auth --email <email> --otp <code>`; this never opens a browser or resends the code. Add the same `--server <origin>` to both commands for another server. Email login selects that email account even if a connection is already saved. For an artifact owned by a guest browser, email login does not transfer ownership; use the owning browser to connect it.\n\nBrowser launch failure returns `browser_unavailable` immediately and keeps the pairing: approving the printed code on any device lets a rerun of the same command continue. The waiting message and timeout errors recommend `afbin auth --email <email>`; agents should ask for the email and use this fallback, then retry the original command. Agents need not invoke auth in the normal browser path; a server command signs in on demand and resumes once approved. On an unattended approval timeout the command returns a structured error carrying the approval URL and expiry to relay to a person. Denial and expiry never create credentials. Connected commands show newer-version notices from their normal server responses, at most hourly. Local-only commands make no update requests. `afbin config set updates false` disables notices; update by launching the explicit npm command shown.\n\nCredentials are kept per server origin under ~/.artifactbin (one file per origin), so `--server`, a tracked workspace or an exported ARTIFACTBIN_URL selects the matching credential without re-approval; login never changes the default. Use `afbin config set host <origin>` to select it. Set ARTIFACTBIN_HOME to use a different private state directory, for example one per environment; exported variables reach every afbin your agent runs.\n\n## One server, several addresses\n\nA deployment may answer at more than one hostname \u2014 a marketing name that proxies to the app, or a previous name kept alive. afbin asks the origin you selected which addresses it answers at, and believes an alias only when the canonical origin's own answer names it: the two origins have to agree. A URL copied from either name then resolves to the same artifact, a folder tracked against one keeps working when the other is selected, and browser approval shown on either is accepted. Requests and credentials always go to the canonical origin of the server YOU selected \u2014 never to an origin a pasted URL named, and never to an alias; a pasted URL supplies its artifact id and nothing else. A server that publishes no addresses behaves exactly as before, with the two origins separate. Self-hosters list the extra origins in `APP__ALIAS_ORIGINS` on the deployment; `APP__PUBLIC_BASE_URL` stays the canonical one.\n\n`afbin serve --dir ./team --port 7445` initializes and runs an authenticated server in the foreground. Its directory owns settings, objects and the default PGLite database. `--db-url postgres://\u2026` or `--db-url pglite://\u2026` overrides only the application database. Server settings are separate from client defaults and per-host credentials. There is no managed self daemon.\n",
         "references/publishing-annotations.md": '# Comments\n\nUse the artifact reference consistently. New threads use exactly one node ID or quote. An ambiguous quote is refused; use the returned current node IDs. Replies name a thread on the same artifact. Pagination applies only to listing.\n\n## Inspect comment screenshots\n\nRead the thread with afbin comment <artifact> --json (follow next_cursor if needed). For each attached image.id relevant to the request, after acknowledging run afbin comment <artifact> --image <image-id> --output <fresh-workspace-path>.webp --json, then open the returned path with your image viewing tool before answering. The default preview includes drawn marks; --variant original omits them. This downloads the saved capture, not a new rendering of the document. Use this authenticated CLI download for image bytes; metadata URLs are browser-session endpoints. If download fails or your model cannot inspect images, reply blocked and state the limitation; never describe unseen pixels from the snippet or surrounding document.\n\nComments are sidecar relations to the node\'s persistent BODY `id`; reading or writing a comment does not rewrite source or flush the editor. Legacy data-annotation-anchor attributes are preservation-only: preserve an existing value with its element; never author, change or reuse one. New comments do not add it.\n\nListing a document returns its OPEN threads only. Read the ones already settled with `afbin comment <ref> --filter state=resolved`, or both lists at once with `--filter state=all`.\n\n"snippet" is the current node text. "quote" is the selected text; quote_found says whether it is still present. Comment Markdown supports links and emphasis: `![alt](url)` is not an image, but a literal exclamation mark plus a link. A comment cannot embed a picture. A deleted thread is not erased; there is no undo for it here.\n\nBearer requests retain their account attribution.\n',
         "references/publishing-datasets.md": '# Datasets and media\n\nRegister CSV, JSON or GeoJSON files with afbin add --json and import the returned ref:ID with <Import name="d" src="ref:ID" />.  Push accepts file paths directly. SQL names d.rows for a flat dataset (each catalog table as d.<table>); data="$query" binds the result. A connected Postgres query runs inside it: <Query source="ref:<id>">. A dataset pushed without flags lets everyone read it and lets its owner\'s pages write it for their accepted members (`afbin help apps`). Add `--policy viewers-write` to the push that CREATES it when everyone who can open the page must be able to write rows without joining.\n\nImages and PDFs use their native formats; other supported files use file artifacts.  Artifact references use IDs, never local paths. Each registered file retains its identity through preview and publication. Standalone asset replacement reports affected dependents. Read [data authoring](markup-data.md) and [catalogs](databases.md) when using connected or multi-table datasets; connection, table and notebook definitions live in dataset YAML.\n\nAn imported URL is NOT an artifact and never appears in `afbin list`. Imported bytes count against your ACCOUNT\'s byte quota; a URL is charged once, to whoever first named the URL. Your external URL stays in the document while the server serves its stored copy.\n',
@@ -18376,8 +18387,8 @@ afbin \u2014 local files, published artifacts
     Move a registered local file while retaining its identity.
   afbin import <file.jsx.html> [\\-\\-output <file.jsx>]
     Import an offline HTML file into local JSX without publishing; defaults to the same basename with .jsx. Existing local documents reconcile safely.
-  afbin preview <path> [<path> ...]
-    Preview and edit local JSX files without publishing. Directories select their JSX files.
+  afbin preview [<path> ...]
+    Preview and edit local JSX files without publishing. With no paths, start an empty server for HTML imports. Directories select their JSX files.
   afbin query <ref> [<ref> ...]
     Read dataset rows or declared queries; \\-\\-write runs a named mutation or dataset SQL.
   afbin pull [<ref> ...]
@@ -18508,9 +18519,9 @@ Examples:
 .fi
 .SH PREVIEW
 .nf
-afbin preview <path> [<path> ...]
+afbin preview [<path> ...]
 
-Preview and edit local JSX files without publishing. Directories select their JSX files.
+Preview and edit local JSX files without publishing. With no paths, start an empty server for HTML imports. Directories select their JSX files.
 
   \\-h, \\-\\-help
     Show local command help.
@@ -18526,6 +18537,8 @@ Preview and edit local JSX files without publishing. Directories select their JS
     Listen on this port; serve defaults to 7445, preview chooses an available one.
   \\-\\-share
     Allow network access to the selected preview files; everyone who can reach it may edit.
+  \\-\\-public\\-url <ORIGIN>
+    Explicit HTTPS origin of a reverse proxy serving this preview; does not change the listening interface.
 
 Examples:
   afbin preview report.jsx appendix.jsx
@@ -56900,9 +56913,16 @@ async function previewFiles(root, cwd, inputs) {
   if (!files.size) throw new CliError("missing_file", "No JSX documents were found in the selected paths.");
   return [...files];
 }
+function previewPublicOrigin(value2) {
+  if (value2 === void 0) return void 0;
+  const origin = normalizeOrigin(value2);
+  if (!origin || !origin.startsWith("https://")) throw new CliError("invalid_arguments", "--public-url must be an HTTPS origin without a path, credentials, query or fragment.");
+  return origin;
+}
 var init_preview_options = __esm({
   "src/preview-options.ts"() {
     "use strict";
+    init_server_identity();
     init_journal();
     init_errors();
   }
@@ -83788,10 +83808,11 @@ async function runCli(argv, context = {}) {
     if (command === "preview" && !flags2.help) {
       const port = Number(flags2.port ?? 0);
       if (!Number.isInteger(port) || port < 0 || port > 65535) throw new CliError("invalid_arguments", "--port must be an integer from 0 to 65535.");
+      const publicUrl = previewPublicOrigin(typeof flags2["public-url"] === "string" ? flags2["public-url"] : void 0);
       const workspace2 = await loadWorkspace(context.cwd, home), known = await localIdentities(workspace2);
-      const paths = await previewFiles(workspace2.root, workspace2.cwd, positionals.map((path) => known[path] ? resolve28(workspace2.root, known[path]) : path));
+      const paths = positionals.length ? await previewFiles(workspace2.root, workspace2.cwd, positionals.map((path) => known[path] ? resolve28(workspace2.root, known[path]) : path)) : [];
       await registerLocalFiles(workspace2, paths.map((path) => resolve28(workspace2.root, path)));
-      return await (context.preview ?? servePreview)({ cwd: workspace2.root, home, paths, port, share: !!flags2.share, json: json3, server: typeof flags2.server === "string" ? flags2.server : workspace2.tracking?.server ?? await exportedServer(home, context.env) });
+      return await (context.preview ?? servePreview)({ cwd: workspace2.root, home, paths, port, share: !!flags2.share, json: json3, ...publicUrl ? { publicUrl } : {}, server: typeof flags2.server === "string" ? flags2.server : workspace2.tracking?.server ?? await exportedServer(home, context.env) });
     }
     if (command === "config" && !flags2.help) {
       const [action, key3, value2] = positionals;

package/dist/index.mjs

@@ -5706,6 +5706,15 @@ var init_program = __esm({
   }
 });
 
+// ../contracts/src/preview-connect.ts
+var PREVIEW_CONNECT_MAX_BYTES;
+var init_preview_connect = __esm({
+  "../contracts/src/preview-connect.ts"() {
+    "use strict";
+    PREVIEW_CONNECT_MAX_BYTES = 25 * 1024 * 1024;
+  }
+});
+
 // ../contracts/src/index.ts
 var init_src = __esm({
   "../contracts/src/index.ts"() {
@@ -5740,6 +5749,7 @@ var init_src = __esm({
     init_mutation_notifications();
     init_schedules();
     init_program();
+    init_preview_connect();
   }
 });
 
@@ -6267,7 +6277,7 @@ var CliError = class extends Error {
 // package.json
 var package_default = {
   name: "@afbin/cli",
-  version: "0.4.1",
+  version: "0.4.2",
   type: "module",
   license: "Apache-2.0",
   description: "Local files, published artifacts and agent authoring",