artyfax 0.3.0 → 0.3.2

package/dist/cli.js

@@ -55,7 +55,8 @@ async function apiFetch(config, path, init2) {
     if (raw) {
       try {
         const parsed = JSON.parse(raw);
-        if (parsed.error) message = parsed.error;
+        if (parsed.message) message = parsed.message;
+        else if (parsed.error) message = parsed.error;
       } catch {
         const snippet = raw.replace(/\s+/g, " ").trim().slice(0, 200);
         if (snippet) message = `HTTP ${res.status}: ${snippet}`;
@@ -320,13 +321,6 @@ async function resolveSlug(config, slugOrId) {
     } catch {
     }
   }
-  if (slugOrId.match(/^[0-9a-f-]{36}$/i)) {
-    try {
-      const doc = await apiFetch(config, `/documents/${slugOrId}`);
-      return doc;
-    } catch {
-    }
-  }
   if (/^[A-Z]+-\d+$/.test(slugOrId)) {
     try {
       const { id } = await apiFetch(config, `/resolve/${encodeURIComponent(slugOrId)}`);
@@ -335,6 +329,13 @@ async function resolveSlug(config, slugOrId) {
     } catch {
     }
   }
+  if (!slugOrId.includes("/") && !/^[A-Z]+-\d+$/.test(slugOrId)) {
+    try {
+      return await apiFetch(config, `/documents/${encodeURIComponent(slugOrId)}`);
+    } catch (e) {
+      if (e.status !== 404) throw e;
+    }
+  }
   const docs = await apiFetch(
     config,
     `/documents?limit=500`
@@ -375,6 +376,11 @@ async function read(config, slugOrId, forceSecure) {
   } else {
     process.stdout.write(data.md_source ?? data.content);
   }
+  if (data.content_hash) {
+    process.stderr.write(`
+content_hash: ${data.content_hash}
+`);
+  }
 }
 
 // src/commands/secure.ts
@@ -399,7 +405,7 @@ async function secure(config, slugOrId) {
   spin.text = "Uploading\u2026";
   await apiFetch(config, `/documents/${doc.id}/content`, {
     method: "PATCH",
-    body: JSON.stringify({ content: encrypted })
+    body: JSON.stringify({ content: encrypted, force: true })
   });
   await apiFetch(config, `/documents/${doc.id}`, {
     method: "PATCH",
@@ -427,7 +433,7 @@ async function unsecure(config, slugOrId) {
   spin.text = "Uploading\u2026";
   await apiFetch(config, `/documents/${doc.id}/content`, {
     method: "PATCH",
-    body: JSON.stringify({ content: plaintext })
+    body: JSON.stringify({ content: plaintext, force: true })
   });
   await apiFetch(config, `/documents/${doc.id}`, {
     method: "PATCH",
@@ -595,7 +601,7 @@ async function open(config, slugOrId) {
 // src/commands/update.ts
 import { readFileSync } from "fs";
 import { resolve } from "path";
-async function update(config, slugOrId, file, json) {
+async function update(config, slugOrId, file, json, force = false) {
   const spin = spinner("Resolving document\u2026");
   spin.start();
   const doc = await resolveSlug(config, slugOrId);
@@ -624,11 +630,35 @@ async function update(config, slugOrId, file, json) {
     const sdk = await getSDK(config);
     content = await encryptSecure(content, sdk);
   }
+  let ifMatch = null;
+  if (!force) {
+    spin.text = "Checking current version\u2026";
+    const cur = await apiFetch(config, `/documents/${doc.id}/content`);
+    ifMatch = cur.content_hash ?? null;
+  }
   spin.text = "Uploading\u2026";
-  await apiFetch(config, `/documents/${doc.id}/content`, {
-    method: "PATCH",
-    body: JSON.stringify({ content, source: "cli" })
-  });
+  try {
+    await apiFetch(config, `/documents/${doc.id}/content`, {
+      method: "PATCH",
+      body: JSON.stringify(
+        force ? { content, source: "cli", force: true } : { content, source: "cli", if_match: ifMatch ?? void 0 }
+      )
+    });
+  } catch (e) {
+    spin.stop();
+    const status = e.status;
+    if (status === 409) {
+      throw new Error(
+        "This document changed since you read it. Re-pull it with `artyfax read` and re-apply your edit, or pass --force to overwrite."
+      );
+    }
+    if (status === 428) {
+      throw new Error(
+        "Could not read the current version to guard this write. Re-run, or pass --force to overwrite."
+      );
+    }
+    throw e;
+  }
   spin.stop();
   if (json) {
     console.log(JSON.stringify({ updated: true, slug: doc.slug, id: doc.id, secure: doc.secure === 1 }));
@@ -687,17 +717,6 @@ function formatBytes(bytes) {
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
   return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 }
-async function resolveDocArg(config, arg) {
-  const looksLikeBareId = !arg.includes("/") && !/^[A-Z]+-\d+$/.test(arg);
-  if (looksLikeBareId) {
-    try {
-      return await apiFetch(config, `/documents/${encodeURIComponent(arg)}`);
-    } catch (e) {
-      if (e.status !== 404) throw e;
-    }
-  }
-  return resolveSlug(config, arg);
-}
 function readImageFile(file) {
   const path = resolve2(file);
   let stat;
@@ -730,7 +749,7 @@ async function setCover(config, slugOrId, file, opts) {
   const image = readImageFile(file);
   const spin = spinner("Resolving document\u2026");
   spin.start();
-  const doc = await resolveDocArg(config, slugOrId);
+  const doc = await resolveSlug(config, slugOrId);
   spin.text = `Uploading ${image.name}\u2026`;
   const uploaded = await uploadImage(config, doc.id, image, "cover");
   spin.text = "Setting cover\u2026";
@@ -752,7 +771,7 @@ async function addImage(config, slugOrId, file, opts) {
   const image = readImageFile(file);
   const spin = spinner("Resolving document\u2026");
   spin.start();
-  const doc = await resolveDocArg(config, slugOrId);
+  const doc = await resolveSlug(config, slugOrId);
   spin.text = `Uploading ${image.name}\u2026`;
   const uploaded = await uploadImage(config, doc.id, image, "content");
   spin.stop();
@@ -767,6 +786,106 @@ async function addImage(config, slugOrId, file, opts) {
   }
 }
 
+// ../shared/src/limits.ts
+var SERVER_SIDE_BYTE_CAP = 10 * 1024 * 1024;
+var CLIENT_UPLOAD_BYTE_CAP_BY_TIER = {
+  free: 25 * 1024 * 1024,
+  personal: 50 * 1024 * 1024,
+  pro: 100 * 1024 * 1024
+};
+var TOTAL_STORAGE_BYTES_BY_TIER = {
+  free: 100 * 1024 * 1024,
+  personal: 10 * 1024 * 1024 * 1024,
+  pro: 50 * 1024 * 1024 * 1024
+};
+
+// ../shared/src/unsplash.ts
+function sanitizeMarkdownLabel(text) {
+  if (!text) return "";
+  return text.replace(/[[\]]/g, "").replace(/\s+/g, " ").trim();
+}
+
+// src/commands/unsplash.ts
+async function search2(config, query, page) {
+  const qs = new URLSearchParams({ q: query, page: String(page) });
+  return apiFetch(config, `/unsplash/search?${qs.toString()}`);
+}
+async function unsplashSearch(config, query, opts) {
+  const spin = spinner("Searching Unsplash\u2026");
+  spin.start();
+  const res = await search2(config, query, opts.page ?? 1);
+  spin.stop();
+  if (opts.json) {
+    console.log(JSON.stringify(res));
+    return;
+  }
+  if (res.results.length === 0) {
+    console.log(c.muted(`No Unsplash photos found for "${query}".`));
+    return;
+  }
+  res.results.forEach((r, i) => {
+    const n = c.bright(String(i + 1).padStart(2));
+    const desc = r.description ? c.bright(r.description) : c.muted("(no description)");
+    console.log(`${n}. ${desc}`);
+    console.log(`    ${c.muted(`${r.photographer.name} \xB7 ${r.width}\xD7${r.height} \xB7 ${r.photo_id}`)}`);
+  });
+  console.log(
+    c.muted(
+      `
+  ${res.total} results. Use: artyfax cover <doc> --photo <id>  |  artyfax image <doc> --photo <id>`
+    )
+  );
+}
+async function resolvePhotoId(config, opts) {
+  if (opts.photo) return opts.photo;
+  if (!opts.unsplash) throw new Error('Provide --photo <id> or --unsplash "<query>"');
+  const res = await search2(config, opts.unsplash, 1);
+  if (res.results.length === 0) throw new Error(`No Unsplash photos found for "${opts.unsplash}"`);
+  return res.results[0].photo_id;
+}
+async function coverFromUnsplash(config, slugOrId, opts) {
+  const spin = spinner("Resolving document\u2026");
+  spin.start();
+  const doc = await resolveSlug(config, slugOrId);
+  spin.text = "Finding photo\u2026";
+  const photoId = await resolvePhotoId(config, opts);
+  spin.text = "Importing cover from Unsplash\u2026";
+  const result = await apiFetch(
+    config,
+    `/documents/${doc.id}/cover/from-unsplash`,
+    { method: "POST", body: JSON.stringify({ photo_id: photoId }) }
+  );
+  spin.stop();
+  if (opts.json) {
+    console.log(JSON.stringify({ ok: true, id: doc.id, slug: doc.slug, cover_image: result.path }));
+  } else {
+    console.log(`${c.teal("Cover set")} on ${c.bright(doc.slug)} ${c.muted(`(Unsplash ${photoId})`)}`);
+  }
+}
+async function imageFromUnsplash(config, slugOrId, opts) {
+  const spin = spinner("Resolving document\u2026");
+  spin.start();
+  const doc = await resolveSlug(config, slugOrId);
+  spin.text = "Finding photo\u2026";
+  const photoId = await resolvePhotoId(config, opts);
+  spin.text = "Importing image from Unsplash\u2026";
+  const result = await apiFetch(
+    config,
+    `/documents/${doc.id}/images/from-unsplash`,
+    { method: "POST", body: JSON.stringify({ photo_id: photoId }) }
+  );
+  spin.stop();
+  const markdown = `![${sanitizeMarkdownLabel(result.alt)}](${result.path})
+: ${result.credit_markdown}`;
+  if (opts.json) {
+    console.log(JSON.stringify({ ok: true, id: doc.id, slug: doc.slug, path: result.path, markdown }));
+  } else {
+    console.log(`${c.teal("Imported")} to ${c.bright(doc.slug)} ${c.muted(`(Unsplash ${photoId})`)}`);
+    console.log(c.muted("  Paste this into the document body:"));
+    console.log(`  ${markdown.replace("\n", "\n  ")}`);
+  }
+}
+
 // src/commands/share.ts
 async function shareCreate(config, slugOrId, json) {
   const spin = spinner("Resolving document\u2026");
@@ -782,9 +901,13 @@ async function shareCreate(config, slugOrId, json) {
     }
   );
   spin.stop();
-  const url = `${config.endpoint}/s/${result.hash}`;
+  const hash = result.share?.hash;
+  if (!hash) {
+    throw new Error("Share created but the server response contained no hash.");
+  }
+  const url = `${config.endpoint}/d/${hash}`;
   if (json) {
-    console.log(JSON.stringify({ hash: result.hash, url, slug: doc.slug }));
+    console.log(JSON.stringify({ hash, url, slug: doc.slug }));
   } else {
     console.log(`${c.teal("Share created:")} ${url}`);
   }
@@ -910,6 +1033,10 @@ async function tagDelete(config, tag, json) {
 }
 
 // src/commands/version.ts
+function fmtTs(ts) {
+  if (!ts) return "\u2014";
+  return ts.replace("T", " ").replace(/\.\d+Z$/, "");
+}
 async function versionList(config, slugOrId, json) {
   const spin = spinner("Resolving document\u2026");
   spin.start();
@@ -921,18 +1048,24 @@ async function versionList(config, slugOrId, json) {
     console.log(JSON.stringify(data.versions));
     return;
   }
-  if (data.versions.length === 0) {
-    console.log(c.muted("No versions found."));
+  const versions = data.versions ?? [];
+  const currentSaved = fmtTs(data.current?.updated_at);
+  if (versions.length === 0) {
+    console.log(`${c.bright(doc.slug)} \u2014 ${c.muted(`no previous versions (current saved ${currentSaved}).`)}`);
     return;
   }
-  console.log(`${c.bright(doc.slug)} \u2014 ${data.versions.length} version${data.versions.length === 1 ? "" : "s"}
-`);
-  const rows = data.versions.map((v, i) => [
-    i === 0 ? c.teal("current") : c.muted(`v${data.versions.length - i}`),
-    v.timestamp.replace("T", " ").replace(/\.\d+Z$/, ""),
-    v.word_count != null ? `${v.word_count} words` : c.muted("\u2014")
+  console.log(
+    `${c.bright(doc.slug)} \u2014 current saved ${c.muted(currentSaved)}, ${versions.length} previous version${versions.length === 1 ? "" : "s"}
+`
+  );
+  const n = versions.length;
+  const rows = versions.map((v, i) => [
+    c.muted(`v${n - i}`),
+    fmtTs(v.created_at),
+    v.source || c.muted("\u2014"),
+    v.published ? c.teal("\u25CF published") : ""
   ]);
-  console.log(table(rows, { header: ["", "Timestamp", "Words"] }));
+  console.log(table(rows, { header: ["", "Saved", "Source", ""] }));
 }
 async function versionRestore(config, slugOrId, yes, json) {
   const spin = spinner("Resolving document\u2026");
@@ -941,25 +1074,26 @@ async function versionRestore(config, slugOrId, yes, json) {
   spin.text = "Loading versions\u2026";
   const data = await apiFetch(config, `/documents/${doc.id}/versions`);
   spin.stop();
-  if (data.versions.length < 2) {
+  const versions = data.versions ?? [];
+  if (versions.length === 0) {
     console.log(c.muted("No previous versions to restore."));
     return;
   }
-  const previous = data.versions.slice(1);
-  console.log(`${c.bright(doc.slug)} \u2014 ${previous.length} previous version${previous.length === 1 ? "" : "s"}:
+  console.log(`${c.bright(doc.slug)} \u2014 ${versions.length} previous version${versions.length === 1 ? "" : "s"}:
 `);
-  for (let i = 0; i < previous.length; i++) {
-    const v = previous[i];
-    const label = `v${data.versions.length - 1 - i}`;
-    const ts = v.timestamp.replace("T", " ").replace(/\.\d+Z$/, "");
-    const words = v.word_count != null ? ` (${v.word_count} words)` : "";
-    console.log(`  ${c.amber(label)}  ${ts}${c.muted(words)}`);
-  }
-  const target = previous[0];
+  const n = versions.length;
+  versions.forEach((v, i) => {
+    const label = `v${n - i}`;
+    const source = v.source ? c.muted(` (${v.source})`) : "";
+    const pin = v.published ? c.teal("  \u25CF published") : "";
+    console.log(`  ${c.amber(label)}  ${fmtTs(v.created_at)}${source}${pin}`);
+  });
   console.log();
+  const target = versions[0];
   if (!yes) {
-    const ts = target.timestamp.replace("T", " ").replace(/\.\d+Z$/, "");
-    const confirmed = await confirm(`Restore to ${ts}?`);
+    const confirmed = await confirm(
+      `Restore to v${n} (${fmtTs(target.created_at)})? The current draft is snapshotted first, so this is reversible.`
+    );
     if (!confirmed) {
       console.log(c.muted("Cancelled."));
       return;
@@ -969,14 +1103,60 @@ async function versionRestore(config, slugOrId, yes, json) {
   restoreSpin.start();
   await apiFetch(config, `/documents/${doc.id}/versions/restore`, {
     method: "POST",
-    body: JSON.stringify({ timestamp: target.timestamp })
+    // The restore endpoint keys on the numeric version id, not a timestamp.
+    body: JSON.stringify({ version_id: target.id })
   });
   restoreSpin.stop();
   if (json) {
-    console.log(JSON.stringify({ restored: true, slug: doc.slug, timestamp: target.timestamp }));
+    console.log(JSON.stringify({ restored: true, slug: doc.slug, version_id: target.id, created_at: target.created_at }));
   } else {
-    console.log(`${c.teal("Restored:")} ${doc.slug} to ${target.timestamp.replace("T", " ").replace(/\.\d+Z$/, "")}`);
+    console.log(`${c.teal("Restored:")} ${doc.slug} to v${n} (${fmtTs(target.created_at)})`);
+  }
+}
+
+// src/commands/publish.ts
+async function publish(config, slugOrId, opts) {
+  const spin = spinner("Resolving document\u2026");
+  spin.start();
+  const doc = await resolveSlug(config, slugOrId);
+  spin.text = opts.version != null ? `Publishing version ${opts.version}\u2026` : "Publishing\u2026";
+  const body = {};
+  if (opts.version != null) body.version_id = opts.version;
+  const data = await apiFetch(
+    config,
+    `/documents/${doc.id}/publish`,
+    { method: "POST", body: JSON.stringify(body) }
+  );
+  spin.stop();
+  if (opts.json) {
+    console.log(JSON.stringify({ published: true, slug: doc.slug, ...data }));
+    return;
+  }
+  const versionNote = data.published_version_id != null ? c.muted(` (version ${data.published_version_id})`) : "";
+  console.log(`${c.teal("Published:")} ${doc.slug}${versionNote}`);
+  console.log(c.muted("Public and shared views now serve this version. Edits stay draft until you publish again."));
+}
+async function unpublish(config, slugOrId, json) {
+  const spin = spinner("Resolving document\u2026");
+  spin.start();
+  const doc = await resolveSlug(config, slugOrId);
+  spin.text = "Unpublishing\u2026";
+  const data = await apiFetch(
+    config,
+    `/documents/${doc.id}/unpublish`,
+    { method: "POST" }
+  );
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify({ unpublished: true, slug: doc.slug, ...data }));
+    return;
+  }
+  if (data.was_published === false) {
+    console.log(c.muted(`${doc.slug} was not published - nothing to do.`));
+    return;
   }
+  console.log(`${c.teal("Unpublished:")} ${doc.slug}`);
+  console.log(c.muted("Public and shared views now serve the live document again."));
 }
 
 // src/commands/annotation.ts
@@ -1511,8 +1691,32 @@ async function workSetStatus(config, docId, status, json) {
   }
   console.log(c.bright(`${data.work_id || docId} \u2192 ${demote ? "removed from board" : statusLabel(status)}`));
 }
-function escapeHtml(s) {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+async function workTouch(config, ids, flags, json) {
+  if (ids.length === 0) {
+    console.error(c.rose("Error: pass one or more work IDs or doc IDs to keep live."));
+    process.exitCode = 1;
+    return;
+  }
+  const action = typeof flags.action === "string" ? flags.action : void 0;
+  const agent = typeof flags.agent === "string" ? flags.agent : void 0;
+  const spin = spinner("Sending heartbeat\u2026");
+  spin.start();
+  const data = await apiFetch(config, "/projects/work/touch", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ ids, action, agent })
+  });
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify(data));
+    return;
+  }
+  const warmed = data.warmed ?? [];
+  if (warmed.length === 0) {
+    console.log(c.muted("No in-progress items matched - nothing warmed."));
+    return;
+  }
+  console.log(c.bright(`Kept live: ${warmed.length} item${warmed.length === 1 ? "" : "s"}`));
 }
 async function workCreate(config, title, flags, json) {
   const projectId = flags.project;
@@ -1534,10 +1738,12 @@ async function workCreate(config, title, flags, json) {
       slug,
       title,
       category: "inbox",
-      md_content: `# ${title}
-`,
+      // AX-165: stubs store no body. The title lives in metadata as the
+      // source of truth; the reader composes the empty-doc view from it and
+      // the editor seeds `# Title` on first edit.
+      md_content: "",
       format: "md",
-      html_content: `<h1>${escapeHtml(title)}</h1>`
+      html_content: ""
     })
   });
   if (saveRes.ok) {
@@ -1702,18 +1908,25 @@ When asked for the next task for a specific agent (for example "next Codex task"
 
 ### Thin work items
 
-When a work item only has a short title/description and no task checklist, don't jump straight into implementation.
+A work item that is only a title and a one-to-three-sentence description, with no task checklist, is **not** a starting point for implementation. It is a request to *design*, not to build - so stop.
 
-1. Read the title and description.
-2. Write an \`## Understanding\` section in the Artyfax document with the inferred scope, assumptions, and non-goals.
-3. Add an \`## Tasks\` checklist before editing code.
-4. Ask the requester to approve the understanding and task list before starting implementation. Use a structured question/approval tool when the runtime provides one. If not, say so and wait for typed approval.
-5. After approval, mark the first task \`active\`, then update checkbox progress as the work proceeds.
+A thin stub's body is usually **empty** - quick-create and the CLI store the title and description in metadata only, and the reader composes the view from them until real content exists (AX-165). So \`get_document\` returning empty \`content\` does not mean the item has no substance: read its \`description\` field. When you write the stub up into a design, that body content replaces the empty state, and the write-up should also refresh the title and description to match what the item now delivers.
+
+1. Write it up as a proper design/plan doc first.
+2. Put the write-up and the proposed tasks to the requester for **approval** - a structured question/approval tool where the runtime provides one (e.g. \`AskUserQuestion\`); otherwise say so and wait for typed approval.
+3. Only after approval: generate the task checklist, mark the first task \`active\`, and begin - updating progress as you go.
 
 If the requester corrects workflow sequencing mid-session, pause implementation, repair the Artyfax document/checklist first, and resume from the checklist rather than local memory.
 
 Open questions are a completion blocker, not just a planning step. Any unresolved question or unticked task - including ones you uncover while building - must go back to the user through a structured question (\`AskUserQuestion\` where available) before the item can move to In Review. You surface and the user decides; you never resolve an open question on your own authority.
 
+### Promoting to the board
+
+A document with \`project_id\` + \`parent\` and **no** \`work_status\` is a child doc carried under its parent - it is **not** a board card. Setting \`work_status\` is what promotes a doc to a board work item and mints its \`${p}-\` card.
+
+- **The parent is the single board item.** A parent-and-children design lives on the board as **one** card (the parent), which rolls up its children's progress via \`task_source: children\`. The children are docs carried under it, not separate cards.
+- **Never set \`work_status\` on a child doc without explicit approval.** Don't promote children to the board "for structure" or to make slices individually trackable - that is the whole point of parent/child docs: one board item carrying many docs. The default for a child doc is \`project_id\` + \`parent\`, no \`work_status\`. The user elevates a child to its own board card if and when they want it there - their call, never a default.
+
 ### Board update cadence
 
 The board is the cross-session signal - other agents and the user read live progress from it, so it must reflect reality *as you work*, not after the fact.
@@ -1732,7 +1945,7 @@ Use Artyfax MCP/CLI for live work updates (status changes, task ticks, assignmen
 ### Conventions
 
 - **Work IDs** (e.g. ${p}-15) are stable. Reference them in commits and changelogs. All MCP tools accept them directly.
-- **Descriptions**: concise, state what it delivers, not how it works - the MCP tool guidance carries the exact length.
+- **Descriptions are high-value content**: one field feeds the board card, grid cards, search, the public page's og:description (the Google snippet), and - for a body-less stub - the entire visible substance of the item. Craft deliberately (120-180 chars, plain text, state what it delivers) and refresh it whenever the item's scope shifts. A description you write is recorded as manual and never overwritten by body derivation; clear it (save it empty) to hand it back to auto-derivation. Exception: while a doc is body-less its description is a brain dump - edits stay part of the stub, and the first real content save re-derives it from the body's opening (write the intro as the summary it will become); once the doc has content, description edits lock as manual. If it can't fit the bar, the item has outgrown being a stub - put the substance in the body. The MCP tool guidance carries the full rules.
 - **Statuses**: backlog > up_next > in_progress > in_review > done (or on_hold, cancelled).
 `;
 }
@@ -1855,17 +2068,16 @@ async function resolveId(config, identifier) {
   const data = await apiFetch(config, `/resolve/${encodeURIComponent(identifier)}`);
   return data.id;
 }
+async function fetchTasks(config, id) {
+  const data = await apiFetch(config, `/documents/${id}/tasks`);
+  return data.tasks;
+}
 async function taskList(config, identifier, json) {
   const spin = spinner("Loading tasks\u2026");
   spin.start();
   const id = await resolveId(config, identifier);
-  const doc = await apiFetch(config, `/documents/${id}/content`);
+  const tasks = await fetchTasks(config, id);
   spin.stop();
-  if (doc.format !== "md" || !doc.md_source) {
-    console.error(c.rose("Task listing only supported for markdown documents"));
-    process.exit(1);
-  }
-  const tasks = parseTasks(doc.md_source);
   if (json) {
     console.log(JSON.stringify(tasks, null, 2));
     return;
@@ -1891,8 +2103,7 @@ async function taskUpdate(config, identifier, taskText, state, json) {
   const spin = spinner(`Setting task to ${state}\u2026`);
   spin.start();
   const id = await resolveId(config, identifier);
-  const doc = await apiFetch(config, `/documents/${id}/content`);
-  const tasks = parseTasks(doc.md_source);
+  const tasks = await fetchTasks(config, id);
   const needle = taskText.toLowerCase();
   const match = tasks.find((t) => t.text.toLowerCase().includes(needle));
   if (!match) {
@@ -1913,31 +2124,158 @@ async function taskUpdate(config, identifier, taskText, state, json) {
   const stateLabel = { done: c.teal("done"), active: c.amber("active"), pending: c.muted("pending") };
   console.log(`${stateLabel[state]} ${match.text}`);
 }
-function parseTasks(content) {
-  const lines = content.split("\n");
-  const taskRe = /^[\t ]*[-*+]\s+\[([xX~ ])\]\s*(.*)/;
-  const fenceRe = /^\s*(`{3,}|~{3,})/;
-  let inFence = false;
-  const tasks = [];
-  let count = 0;
-  const charToState = { x: "done", X: "done", "~": "active", " ": "pending" };
-  for (const line of lines) {
-    if (fenceRe.test(line)) {
-      inFence = !inFence;
-      continue;
-    }
-    if (inFence) continue;
-    const m = line.match(taskRe);
-    if (m) {
-      tasks.push({ index: count, state: charToState[m[1]] || "pending", text: m[2].trim() });
-      count++;
-    }
+
+// ../shared/src/child-order.ts
+function resolveChildOrder(input) {
+  const { activeIds, archivedIds, requested } = input;
+  const seen = /* @__PURE__ */ new Set();
+  const dupes = /* @__PURE__ */ new Set();
+  for (const id of requested) {
+    if (seen.has(id)) dupes.add(id);
+    seen.add(id);
+  }
+  if (dupes.size > 0) {
+    return { ok: false, error: `Duplicate id(s) in the order: ${[...dupes].join(", ")}` };
+  }
+  const activeSet = new Set(activeIds);
+  const archivedSet = new Set(archivedIds);
+  const archivedRequested = [];
+  const foreign = [];
+  for (const id of requested) {
+    if (activeSet.has(id)) continue;
+    if (archivedSet.has(id)) archivedRequested.push(id);
+    else foreign.push(id);
+  }
+  if (archivedRequested.length > 0) {
+    return {
+      ok: false,
+      error: `Archived page(s) can't be positioned: ${archivedRequested.join(", ")}. Archived pages keep their order automatically.`
+    };
+  }
+  if (foreign.length > 0) {
+    return { ok: false, error: `Not a child of this parent: ${foreign.join(", ")}` };
+  }
+  const requestedSet = new Set(requested);
+  const missing = activeIds.filter((id) => !requestedSet.has(id));
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      error: `The order must list every visible child. Missing: ${missing.join(", ")}`
+    };
   }
-  return tasks;
+  return { ok: true, childIds: [...requested, ...archivedIds] };
+}
+
+// src/commands/pages.ts
+async function fetchChildrenSorted(config, parentId) {
+  const { documents } = await apiFetch(
+    config,
+    `/documents?parent_id=${encodeURIComponent(parentId)}&archived=include&limit=all`
+  );
+  return [...documents].sort(
+    (a, b) => (a.sort_order ?? 0) - (b.sort_order ?? 0) || (a.title ?? "").localeCompare(b.title ?? "")
+  );
+}
+async function loadChildren(config, parentId) {
+  const sorted = await fetchChildrenSorted(config, parentId);
+  return {
+    activeIds: sorted.filter((d) => !d.archived).map((d) => d.id),
+    archivedIds: sorted.filter((d) => d.archived).map((d) => d.id)
+  };
+}
+async function writeOrder(config, parentId, childIds) {
+  await apiFetch(config, `/documents/${parentId}/children/order`, {
+    method: "PUT",
+    body: JSON.stringify({ child_ids: childIds })
+  });
+}
+function fail(spin, message) {
+  spin.stop();
+  console.error(c.rose(message));
+  process.exit(1);
+}
+async function pagesList(config, parentRef, json) {
+  const spin = spinner("Loading pages\u2026");
+  spin.start();
+  const parentId = (await resolveSlug(config, parentRef)).id;
+  const children = await fetchChildrenSorted(config, parentId);
+  spin.stop();
+  const visible = children.filter((d) => !d.archived);
+  const archivedCount = children.length - visible.length;
+  if (json) {
+    console.log(JSON.stringify(visible));
+    return;
+  }
+  if (visible.length === 0) {
+    console.log(
+      c.muted(
+        archivedCount > 0 ? `No visible child pages (${archivedCount} archived hidden).` : "No child pages."
+      )
+    );
+    return;
+  }
+  const rows = visible.map((d, i) => [c.muted(`${i + 1}`), d.title ?? "", c.muted(d.slug ?? "")]);
+  console.log(table(rows, { header: [c.muted("#"), "Title", c.muted("Slug")] }));
+  if (archivedCount > 0) {
+    console.log(c.muted(`
+${archivedCount} archived page${archivedCount === 1 ? "" : "s"} hidden`));
+  }
+}
+async function pagesOrder(config, parentRef, childRefs, json) {
+  const spin = spinner("Setting page order\u2026");
+  spin.start();
+  const parentId = (await resolveSlug(config, parentRef)).id;
+  const requested = await Promise.all(childRefs.map(async (r) => (await resolveSlug(config, r)).id));
+  const { activeIds, archivedIds } = await loadChildren(config, parentId);
+  const order = resolveChildOrder({ activeIds, archivedIds, requested });
+  if (!order.ok) fail(spin, order.error);
+  await writeOrder(config, parentId, order.childIds);
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify({ ok: true, child_ids: order.childIds }));
+    return;
+  }
+  const n = order.childIds.length;
+  console.log(`${c.teal("\u2713")} Reordered ${n} page${n === 1 ? "" : "s"}`);
+}
+async function pagesMove(config, childRef, position, targetRef, json) {
+  if (position !== "before" && position !== "after") {
+    console.error(c.rose(`Position must be "before" or "after", got "${position}".`));
+    process.exit(1);
+  }
+  const spin = spinner("Moving page\u2026");
+  spin.start();
+  const child = await resolveSlug(config, childRef);
+  const target = await resolveSlug(config, targetRef);
+  if (child.id === target.id) fail(spin, "Can't move a page relative to itself.");
+  if (!child.parent_id) fail(spin, `"${child.title}" is not a child page - it has no parent.`);
+  if (target.parent_id !== child.parent_id) {
+    fail(spin, `"${target.title}" is not a sibling of "${child.title}".`);
+  }
+  const { activeIds, archivedIds } = await loadChildren(config, child.parent_id);
+  if (!activeIds.includes(child.id)) {
+    fail(spin, `"${child.title}" is archived - unarchive it before reordering.`);
+  }
+  if (!activeIds.includes(target.id)) {
+    fail(spin, `"${target.title}" is archived - pick a visible sibling as the target.`);
+  }
+  const without = activeIds.filter((id) => id !== child.id);
+  const targetIdx = without.indexOf(target.id);
+  const insertIdx = position === "before" ? targetIdx : targetIdx + 1;
+  without.splice(insertIdx, 0, child.id);
+  const order = resolveChildOrder({ activeIds, archivedIds, requested: without });
+  if (!order.ok) fail(spin, order.error);
+  await writeOrder(config, child.parent_id, order.childIds);
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify({ ok: true, child_ids: order.childIds }));
+    return;
+  }
+  console.log(`${c.teal("\u2713")} Moved "${child.title}" ${position} "${target.title}"`);
 }
 
 // src/cli.ts
-var VERSION = true ? "0.3.0" : "0.0.0-dev";
+var VERSION = true ? "0.3.2" : "0.0.0-dev";
 function brandedHelp() {
   return `
 ${c.amber("artyfax")} ${c.muted(`v${VERSION}`)} \u2014 your personal document library
@@ -1959,6 +2297,8 @@ ${c.bright("Documents")}
   unsecure <slug>        Remove encryption
   cover <doc> <file>     Set a document's cover image from a local file
   image <doc> <file>     Upload a local image, print the markdown to embed
+  publish <doc>          Pin a published version (public/shared views serve it)
+  unpublish <doc>        Clear the published pointer, revert to serving live
 
 ${c.bright("Sub-resources")}
   share create <slug>    Create a share link
@@ -2040,7 +2380,11 @@ ${c.bright("Options:")}
 ${c.bright("Examples:")}
   artyfax save notes.md --category inbox
   artyfax save --url https://example.com/article --category articles
-  artyfax save report.md --secure --category reports`,
+  artyfax save report.md --secure --category reports
+
+${c.bright("Markdown:")} mermaid diagrams render (\`\`\`mermaid fences); colour flowchart
+  nodes on-brand with \`class <node> amber|teal|blue|violet|rose\` rather than raw hex.
+  Full syntax: the editor's Markdown Reference, or the seeded "Markdown Formatting" doc.`,
   read: `${c.amber("artyfax read")} \u2014 read document content
 
 ${c.bright("Usage:")} artyfax read <slug>
@@ -2179,6 +2523,25 @@ ${c.bright("Usage:")} artyfax version list <slug>     Show version history
 ${c.bright("Examples:")}
   artyfax version list inbox/my-doc
   artyfax version restore inbox/my-doc --yes`,
+  publish: `${c.amber("artyfax publish")} \u2014 pin a published version
+
+${c.bright("Usage:")} artyfax publish <doc> [version-id]
+
+Public and shared views serve the pinned version while later edits stay draft
+until you publish again. With no version-id, publishes the current draft;
+pass a version id (from ${c.amber("artyfax version list")}) to publish an older state.
+
+${c.bright("Examples:")}
+  artyfax publish plans/my-post
+  artyfax publish AX-12 1843`,
+  unpublish: `${c.amber("artyfax unpublish")} \u2014 clear the published pointer
+
+${c.bright("Usage:")} artyfax unpublish <doc>
+
+Public and shared views revert to serving the live document.
+
+${c.bright("Examples:")}
+  artyfax unpublish plans/my-post`,
   annotation: `${c.amber("artyfax annotation")} \u2014 read a document's annotations (highlights, underlines, strikethroughs, notes, comments, redactions)
 
 ${c.bright("Usage:")} artyfax annotation list <slug>     List annotations (--include-recipients, --since <iso>)
@@ -2198,7 +2561,20 @@ ${c.bright("Usage:")} artyfax doctor [--json]`,
 
 ${c.bright("Usage:")} artyfax skill install [--project]   Install Artyfax skill
         artyfax skill status               Check installation
-        artyfax skill update               Update to latest version`
+        artyfax skill update               Update to latest version`,
+  pages: `${c.amber("artyfax pages")} \u2014 list and reorder a parent document's child pages
+
+${c.bright("Usage:")} artyfax pages list <parent>                        Show child pages in reading order
+        artyfax pages order <parent> <child...>            Set the full reading order
+        artyfax pages move <child> before|after <target>   Nudge one page past a sibling
+
+Refs accept a document id, slug, or work id (e.g. ${c.muted("AX-12")}).
+${c.bright("order")} must name every visible child once; archived pages keep their order automatically.
+
+${c.bright("Examples:")}
+  artyfax pages list AX-94
+  artyfax pages order AX-94 intro setup usage
+  artyfax pages move usage before setup`
 };
 function parseArgs(args) {
   const flags = {};
@@ -2237,10 +2613,36 @@ function parseArgs(args) {
   }
   return { command, subcommand, positional, flags };
 }
-var SUB_RESOURCES = /* @__PURE__ */ new Set(["share", "cat", "tag", "version", "annotation", "skill", "snippets", "work", "project", "workspace"]);
+var SUB_RESOURCES = /* @__PURE__ */ new Set(["share", "cat", "tag", "version", "annotation", "skill", "snippets", "work", "project", "workspace", "pages"]);
 function isSubResource(cmd) {
   return SUB_RESOURCES.has(cmd);
 }
+var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
+  "init",
+  "save",
+  "read",
+  "list",
+  "get",
+  "search",
+  "delete",
+  "open",
+  "secure",
+  "unsecure",
+  "update",
+  "metadata",
+  "cover",
+  "image",
+  "unsplash",
+  "publish",
+  "unpublish",
+  "doctor",
+  "task",
+  "tasks",
+  ...SUB_RESOURCES
+]);
+function isKnownCommand(command) {
+  return KNOWN_COMMANDS.has(command);
+}
 async function main() {
   const parsed = parseArgs(process.argv.slice(2));
   const { command, subcommand, positional, flags } = parsed;
@@ -2262,36 +2664,7 @@ async function main() {
     console.log(brandedHelp());
     process.exit(0);
   }
-  const KNOWN_COMMANDS = /* @__PURE__ */ new Set([
-    "init",
-    "save",
-    "read",
-    "list",
-    "get",
-    "search",
-    "delete",
-    "open",
-    "secure",
-    "unsecure",
-    "update",
-    "metadata",
-    "cover",
-    "image",
-    "share",
-    "cat",
-    "tag",
-    "version",
-    "annotation",
-    "skill",
-    "snippets",
-    "doctor",
-    "work",
-    "project",
-    "workspace",
-    "task",
-    "tasks"
-  ]);
-  if (!KNOWN_COMMANDS.has(command)) {
+  if (!isKnownCommand(command)) {
     error(`Unknown command: ${command}`, `Run \`artyfax--help\` for available commands`);
   }
   if (command === "skill") {
@@ -2422,6 +2795,24 @@ async function main() {
       await open(config, slug);
       break;
     }
+    case "publish": {
+      const slug = positional[0];
+      if (!slug) error("Missing slug argument", "Usage: artyfax publish <doc> [version-id]");
+      const versionArg = positional[1];
+      let version;
+      if (versionArg !== void 0) {
+        version = Number(versionArg);
+        if (!Number.isInteger(version)) error(`Invalid version id: ${versionArg}`, "Usage: artyfax publish <doc> [version-id]");
+      }
+      await publish(config, slug, { version, json });
+      break;
+    }
+    case "unpublish": {
+      const slug = positional[0];
+      if (!slug) error("Missing slug argument", "Usage: artyfax unpublish <doc>");
+      await unpublish(config, slug, json);
+      break;
+    }
     case "secure": {
       const slug = positional[0];
       if (!slug) error("Missing slug argument", "Usage: artyfax secure <slug>");
@@ -2436,8 +2827,8 @@ async function main() {
     }
     case "update": {
       const slug = positional[0];
-      if (!slug) error("Missing slug argument", "Usage: artyfax update <slug> [file] (reads from stdin if no file)");
-      await update(config, slug, positional[1], json);
+      if (!slug) error("Missing slug argument", "Usage: artyfax update <slug> [file] [--force] (reads from stdin if no file)");
+      await update(config, slug, positional[1], json, !!flags.force);
       break;
     }
     case "metadata": {
@@ -2458,15 +2849,35 @@ async function main() {
     case "cover": {
       const slug = positional[0];
       const file = positional[1];
-      if (!slug || !file) error("Missing arguments", 'Usage: artyfax cover <doc> <image-file> [--alt "..."]');
-      await setCover(config, slug, file, { alt: flags.alt, json });
+      const unsplash = flags.unsplash;
+      const photo = flags.photo;
+      if (!slug) error("Missing arguments", 'Usage: artyfax cover <doc> <image-file>  |  cover <doc> --unsplash "<query>"  |  --photo <id>');
+      if (unsplash || photo) {
+        await coverFromUnsplash(config, slug, { unsplash, photo, json });
+      } else {
+        if (!file) error("Missing image", 'Provide an image file, or --unsplash "<query>", or --photo <id>');
+        await setCover(config, slug, file, { alt: flags.alt, json });
+      }
       break;
     }
     case "image": {
       const slug = positional[0];
       const file = positional[1];
-      if (!slug || !file) error("Missing arguments", 'Usage: artyfax image <doc> <image-file> [--alt "..."]');
-      await addImage(config, slug, file, { alt: flags.alt, json });
+      const unsplash = flags.unsplash;
+      const photo = flags.photo;
+      if (!slug) error("Missing arguments", 'Usage: artyfax image <doc> <image-file>  |  image <doc> --unsplash "<query>"  |  --photo <id>');
+      if (unsplash || photo) {
+        await imageFromUnsplash(config, slug, { unsplash, photo, json });
+      } else {
+        if (!file) error("Missing image", 'Provide an image file, or --unsplash "<query>", or --photo <id>');
+        await addImage(config, slug, file, { alt: flags.alt, json });
+      }
+      break;
+    }
+    case "unsplash": {
+      const query = positional.join(" ").trim();
+      if (!query) error("Missing query", "Usage: artyfax unsplash <query>");
+      await unsplashSearch(config, query, { json, page: flags.page ? Number(flags.page) : void 0 });
       break;
     }
     case "share": {
@@ -2637,6 +3048,38 @@ async function main() {
       }
       break;
     }
+    case "pages": {
+      switch (subcommand) {
+        case "list": {
+          const parent = positional[0];
+          if (!parent) error("Missing parent", "Usage: artyfax pages list <parent>");
+          await pagesList(config, parent, json);
+          break;
+        }
+        case "order": {
+          const parent = positional[0];
+          const childRefs = positional.slice(1);
+          if (!parent || childRefs.length === 0) {
+            error("Missing arguments", "Usage: artyfax pages order <parent> <child...>");
+          }
+          await pagesOrder(config, parent, childRefs, json);
+          break;
+        }
+        case "move": {
+          const child = positional[0];
+          const position = positional[1];
+          const target = positional[2];
+          if (!child || !position || !target) {
+            error("Missing arguments", "Usage: artyfax pages move <child> before|after <target>");
+          }
+          await pagesMove(config, child, position, target, json);
+          break;
+        }
+        default:
+          error(`Unknown pages subcommand: ${subcommand || "(none)"}`, "Usage: artyfax pages <list|order|move>");
+      }
+      break;
+    }
     case "work": {
       switch (subcommand) {
         case "":
@@ -2673,8 +3116,13 @@ async function main() {
           await workCreate(config, title, flags, json);
           break;
         }
+        case "touch": {
+          if (positional.length === 0) error("Missing work item ID(s)", "Usage: artyfax work touch <id...> [--action editing|building|reviewing|running]");
+          await workTouch(config, positional, flags, json);
+          break;
+        }
         default:
-          error(`Unknown work subcommand: ${subcommand}`, "Usage: artyfax work <list|next|start|done|status|create>");
+          error(`Unknown work subcommand: ${subcommand}`, "Usage: artyfax work <list|next|start|done|status|create|touch>");
       }
       break;
     }
@@ -2732,5 +3180,6 @@ if (isDirectRun()) {
 }
 export {
   VERSION,
+  isKnownCommand,
   parseArgs
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artyfax",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "CLI for Artyfax - your personal document library. Save, theme, search, and share.",
   "type": "module",
   "bin": {