artyfax 0.2.3 → 0.3.1

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync as readFileSync2 } from "fs";
-import { resolve as resolve2 } from "path";
+import { readFileSync as readFileSync5, realpathSync } from "fs";
+import { resolve as resolve5 } from "path";
+import { fileURLToPath } from "url";
 
 // src/config.ts
 function getConfig(flags) {
@@ -11,28 +12,58 @@ function getConfig(flags) {
     console.error("No API key. Set ARTYFAX_API_KEY or pass --api-key.");
     process.exit(1);
   }
+  const endpoint = flags.endpoint || process.env.ARTYFAX_ENDPOINT || "https://artyfax.io";
+  let parsed;
+  try {
+    parsed = new URL(endpoint);
+  } catch {
+    console.error(`Invalid endpoint: "${endpoint}". Must be an absolute http(s) URL.`);
+    process.exit(1);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    console.error(`Invalid endpoint scheme: "${parsed.protocol}". Use http:// or https://.`);
+    process.exit(1);
+  }
+  const LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]", "0.0.0.0"]);
+  const isLocal = LOCAL_HOSTS.has(parsed.hostname);
+  if (parsed.protocol === "http:" && !isLocal) {
+    console.error(`Warning: sending your API key over plain HTTP to ${parsed.host}. Use https:// unless this is a trusted local endpoint.`);
+  }
   return {
     apiKey,
-    endpoint: flags.endpoint || process.env.ARTYFAX_ENDPOINT || "https://artyfax.io",
+    endpoint,
     passphrase: process.env.ARTYFAX_SECURE_PASSPHRASE || null
   };
 }
-async function apiFetch(config, path, init) {
+async function apiFetch(config, path, init2) {
+  const isFormData = typeof FormData !== "undefined" && init2?.body instanceof FormData;
   const res = await fetch(`${config.endpoint}/api${path}`, {
-    ...init,
+    ...init2,
     headers: {
-      "Content-Type": "application/json",
+      ...isFormData ? {} : { "Content-Type": "application/json" },
       "X-API-Key": config.apiKey,
       // design-34: identify the CLI on the server side so saved_via can
       // bucket CLI saves correctly. Format mirrors common CLI tools so a
       // server-side regex can stay simple.
       "User-Agent": `artyfax-cli/${VERSION}`,
-      ...init?.headers
+      ...init2?.headers
     }
   });
   if (!res.ok) {
-    const body = await res.json().catch(() => ({ error: `HTTP ${res.status}` }));
-    throw new Error(body.error ?? `HTTP ${res.status}`);
+    const raw = await res.text().catch(() => "");
+    let message = `HTTP ${res.status}`;
+    if (raw) {
+      try {
+        const parsed = JSON.parse(raw);
+        if (parsed.error) message = parsed.error;
+      } catch {
+        const snippet = raw.replace(/\s+/g, " ").trim().slice(0, 200);
+        if (snippet) message = `HTTP ${res.status}: ${snippet}`;
+      }
+    }
+    const err = new Error(message);
+    err.status = res.status;
+    throw err;
   }
   return res.json();
 }
@@ -102,7 +133,7 @@ function bufferToBase64(buffer) {
 
 // src/passphrase.ts
 async function promptPassphrase(prompt = "Passphrase: ") {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve6, reject) => {
     const rl = createInterface({ input: process.stdin, output: process.stderr });
     process.stderr.write(prompt);
     const cleanup = () => {
@@ -120,7 +151,7 @@ async function promptPassphrase(prompt = "Passphrase: ") {
       if (c2 === "\n" || c2 === "\r") {
         process.stderr.write("\n");
         cleanup();
-        resolve3(input);
+        resolve6(input);
       } else if (c2 === "" || c2.length === 0) {
         process.stderr.write("\n");
         cleanup();
@@ -204,11 +235,11 @@ function stripAnsi(s) {
   return s.replace(/\x1b\[[0-9;]*m/g, "");
 }
 function confirm(message) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve6) => {
     const rl = createInterface2({ input: process.stdin, output: process.stderr });
     rl.question(`${message} ${c.muted("[y/N]")} `, (answer) => {
       rl.close();
-      resolve3(answer.trim().toLowerCase() === "y");
+      resolve6(answer.trim().toLowerCase() === "y");
     });
   });
 }
@@ -282,19 +313,28 @@ ${c.muted("Use --force to save a new copy.")}`
 // src/resolve.ts
 async function resolveSlug(config, slugOrId) {
   if (slugOrId.includes("/")) {
+    const encodedSlug = slugOrId.split("/").map(encodeURIComponent).join("/");
     try {
-      const doc = await apiFetch(config, `/documents/by-slug/${slugOrId}`);
+      const doc = await apiFetch(config, `/documents/by-slug/${encodedSlug}`);
       return doc;
     } catch {
     }
   }
-  if (slugOrId.match(/^[0-9a-f-]{36}$/i)) {
+  if (/^[A-Z]+-\d+$/.test(slugOrId)) {
     try {
-      const doc = await apiFetch(config, `/documents/${slugOrId}`);
+      const { id } = await apiFetch(config, `/resolve/${encodeURIComponent(slugOrId)}`);
+      const doc = await apiFetch(config, `/documents/${id}`);
       return doc;
     } 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`
@@ -313,7 +353,7 @@ async function resolveSlug(config, slugOrId) {
 ` + partial.slice(0, 5).map((d) => `  ${d.slug}`).join("\n")
     );
   }
-  throw new Error(`Document not found: ${slugOrId}. Try \`arty search ${slugOrId}\` or \`arty list\``);
+  throw new Error(`Document not found: ${slugOrId}. Try \`artyfax search ${slugOrId}\` or \`artyfax list\``);
 }
 
 // src/commands/read.ts
@@ -396,6 +436,47 @@ async function unsecure(config, slugOrId) {
   spin.succeed(`${c.teal("Decrypted:")} ${doc.slug}`);
 }
 
+// src/commands/workspace.ts
+async function resolveWorkspaceId(config, raw) {
+  const [id] = await resolveWorkspaceIds(config, [raw]);
+  return id;
+}
+async function resolveWorkspaceIds(config, inputs) {
+  if (inputs.length === 0) return [];
+  const data = await apiFetch(config, "/workspaces");
+  return inputs.map((raw) => {
+    const q = raw.trim().toLowerCase();
+    const match = data.workspaces.find(
+      (w) => w.id === raw || w.slug.toLowerCase() === q || w.name.toLowerCase() === q
+    );
+    if (!match) {
+      const names = data.workspaces.map((w) => w.name).join(", ") || "none";
+      throw new Error(`Workspace not found: ${raw}. Available: ${names}`);
+    }
+    return match.id;
+  });
+}
+async function workspaceList(config, json) {
+  const spin = spinner("Loading workspaces\u2026");
+  spin.start();
+  const data = await apiFetch(config, "/workspaces");
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify(data.workspaces, null, 2));
+    return;
+  }
+  if (data.workspaces.length === 0) {
+    console.log(c.muted("No workspaces."));
+    return;
+  }
+  const rows = data.workspaces.map((w) => [
+    w.name,
+    c.muted(w.slug),
+    c.muted(w.id)
+  ]);
+  console.log(table(rows, { header: ["Name", c.muted("Slug"), c.muted("ID")] }));
+}
+
 // src/commands/list.ts
 async function list(config, opts) {
   const spin = spinner("Loading documents\u2026");
@@ -405,6 +486,8 @@ async function list(config, opts) {
   if (opts.offset) path += `&offset=${opts.offset}`;
   if (opts.archived) path += `&archived=1`;
   if (opts.parentId) path += `&parent_id=${encodeURIComponent(opts.parentId)}`;
+  if (opts.tag) path += `&tag=${encodeURIComponent(opts.tag)}`;
+  if (opts.workspace) path += `&workspace=${encodeURIComponent(await resolveWorkspaceId(config, opts.workspace))}`;
   const data = await apiFetch(config, path);
   spin.stop();
   if (opts.json) {
@@ -431,13 +514,12 @@ async function list(config, opts) {
 }
 
 // src/commands/search.ts
-async function search(config, query, json) {
+async function search(config, query, json, workspace) {
   const spin = spinner(`Searching for "${query}"\u2026`);
   spin.start();
-  const data = await apiFetch(
-    config,
-    `/search?q=${encodeURIComponent(query)}`
-  );
+  let path = `/search?q=${encodeURIComponent(query)}`;
+  if (workspace) path += `&workspace=${encodeURIComponent(await resolveWorkspaceId(config, workspace))}`;
+  const data = await apiFetch(config, path);
   spin.stop();
   if (json) {
     console.log(JSON.stringify(data.results));
@@ -448,7 +530,7 @@ async function search(config, query, json) {
     return;
   }
   const rows = data.results.map((r) => [
-    r.title,
+    r.title + (r.visible_via === "project" ? c.muted(" (via project)") : ""),
     c.muted(r.slug),
     c.muted(r.updated_at.slice(0, 10))
   ]);
@@ -563,6 +645,7 @@ async function metadata(config, slugOrId, opts) {
   const doc = await resolveSlug(config, slugOrId);
   const patch = {};
   if (opts.category !== void 0) patch.category = opts.category;
+  if (opts.slug !== void 0) patch.slug = opts.slug;
   if (opts.title !== void 0) patch.title = opts.title;
   if (opts.theme !== void 0) patch.theme = opts.theme;
   if (opts.visibility !== void 0) patch.visibility = opts.visibility;
@@ -570,7 +653,7 @@ async function metadata(config, slugOrId, opts) {
   if (opts.tags !== void 0) patch.tags = opts.tags.split(",").map((t) => t.trim());
   if (Object.keys(patch).length === 0) {
     spin.stop();
-    throw new Error("No metadata flags provided. Use --category, --tags, --title, --theme, --visibility, or --archived");
+    throw new Error("No metadata flags provided. Use --category, --slug, --tags, --title, --theme, --visibility, or --archived");
   }
   spin.text = "Updating metadata\u2026";
   await apiFetch(config, `/documents/${doc.id}/metadata`, {
@@ -586,6 +669,93 @@ async function metadata(config, slugOrId, opts) {
   }
 }
 
+// src/commands/image.ts
+import { readFileSync as readFileSync2, statSync } from "fs";
+import { extname, basename, resolve as resolve2 } from "path";
+var MIME_BY_EXT = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".avif": "image/avif",
+  ".svg": "image/svg+xml"
+};
+var MAX_BYTES = 5 * 1024 * 1024;
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+function readImageFile(file) {
+  const path = resolve2(file);
+  let stat;
+  try {
+    stat = statSync(path);
+  } catch {
+    throw new Error(`Image not found: ${path}`);
+  }
+  if (!stat.isFile()) throw new Error(`Not a file: ${path}`);
+  const ext = extname(path).toLowerCase();
+  const mime = MIME_BY_EXT[ext];
+  if (!mime) {
+    throw new Error(`Unsupported image extension: ${ext}. Allowed: ${Object.keys(MIME_BY_EXT).join(", ")}`);
+  }
+  if (stat.size > MAX_BYTES) {
+    throw new Error(`Image exceeds 5 MB limit (${formatBytes(stat.size)})`);
+  }
+  return { bytes: readFileSync2(path), name: basename(path), mime };
+}
+async function uploadImage(config, docId, file, kind) {
+  const form = new FormData();
+  form.set("file", new File([file.bytes], file.name, { type: file.mime }));
+  const query = kind === "cover" ? "?kind=cover" : "";
+  return apiFetch(config, `/documents/${docId}/images${query}`, {
+    method: "POST",
+    body: form
+  });
+}
+async function setCover(config, slugOrId, file, opts) {
+  const image = readImageFile(file);
+  const spin = spinner("Resolving document\u2026");
+  spin.start();
+  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";
+  const patch = { cover_image: uploaded.path };
+  if (typeof opts.alt === "string") patch.cover_alt = opts.alt;
+  await apiFetch(config, `/documents/${doc.id}/metadata`, {
+    method: "PATCH",
+    body: JSON.stringify(patch)
+  });
+  spin.stop();
+  if (opts.json) {
+    console.log(JSON.stringify({ ok: true, id: doc.id, slug: doc.slug, cover_image: uploaded.path }));
+  } else {
+    console.log(`${c.teal("Cover set")} on ${c.bright(doc.slug)} ${c.muted(`(${formatBytes(image.bytes.length)})`)}`);
+    console.log(c.muted("  Tip: covers render best at 1200\xD7630 (hero + social card shape)."));
+  }
+}
+async function addImage(config, slugOrId, file, opts) {
+  const image = readImageFile(file);
+  const spin = spinner("Resolving document\u2026");
+  spin.start();
+  const doc = await resolveSlug(config, slugOrId);
+  spin.text = `Uploading ${image.name}\u2026`;
+  const uploaded = await uploadImage(config, doc.id, image, "content");
+  spin.stop();
+  const alt = typeof opts.alt === "string" ? opts.alt : "";
+  const snippet = `![${alt}](${uploaded.path})`;
+  if (opts.json) {
+    console.log(JSON.stringify({ ok: true, id: doc.id, slug: doc.slug, path: uploaded.path, markdown: snippet }));
+  } else {
+    console.log(`${c.teal("Uploaded")} to ${c.bright(doc.slug)} ${c.muted(`(${formatBytes(image.bytes.length)})`)}`);
+    console.log(c.muted("  Paste this into the document body:"));
+    console.log(`  ${snippet}`);
+  }
+}
+
 // src/commands/share.ts
 async function shareCreate(config, slugOrId, json) {
   const spin = spinner("Resolving document\u2026");
@@ -601,9 +771,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}`);
   }
@@ -690,11 +864,49 @@ async function tagList(config, json) {
     console.log(c.muted("No tags found."));
     return;
   }
-  const rows = data.tags.map((t) => [t.tag, String(t.count)]);
-  console.log(table(rows, { header: ["Tag", "Count"] }));
+  const namespaces = data.namespaces ?? [];
+  const simple = data.simple ?? [];
+  for (const ns of namespaces) {
+    const heading = ns.intent ? `${c.bright(ns.prefix + ":")}  ${c.muted(ns.intent)}` : c.bright(ns.prefix + ":");
+    console.log("\n" + heading);
+    const rows = ns.tags.map((t) => [t.tag, String(t.count)]);
+    console.log(table(rows, { header: ["Tag", "Count"] }));
+  }
+  if (simple.length > 0) {
+    console.log("\n" + c.bright("(no namespace)"));
+    const rows = simple.map((t) => [t.tag, String(t.count)]);
+    console.log(table(rows, { header: ["Tag", "Count"] }));
+  }
+}
+async function tagDelete(config, tag, json) {
+  const spin = spinner(`Deleting tag \u201C${tag}\u201D\u2026`);
+  spin.start();
+  const data = await apiFetch(
+    config,
+    "/tags/delete",
+    { method: "POST", body: JSON.stringify({ tag }) }
+  );
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify(data));
+    return;
+  }
+  const { documents, annotations, snippets } = data.updated;
+  const total = documents + annotations + snippets;
+  if (total === 0) {
+    console.log(c.muted(`No items carried \u201C${tag}\u201D.`));
+    return;
+  }
+  console.log(
+    c.teal(`Removed \u201C${tag}\u201D from ${total} item(s)`) + c.muted(` (${documents} docs, ${annotations} annotations, ${snippets} snippets)`)
+  );
 }
 
 // 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();
@@ -706,18 +918,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");
@@ -726,25 +944,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;
@@ -754,87 +973,102 @@ 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/note.ts
-async function noteList(config, slugOrId, json) {
+// 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 = "Loading annotations\u2026";
+  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,
-    `/annotations/doc/${doc.id}`
+    `/documents/${doc.id}/publish`,
+    { method: "POST", body: JSON.stringify(body) }
   );
   spin.stop();
-  if (json) {
-    console.log(JSON.stringify(data.annotations));
+  if (opts.json) {
+    console.log(JSON.stringify({ published: true, slug: doc.slug, ...data }));
     return;
   }
-  if (data.annotations.length === 0) {
-    console.log(c.muted("No annotations found."));
+  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;
   }
-  console.log(`${c.bright(doc.slug)} \u2014 ${data.annotations.length} annotation${data.annotations.length === 1 ? "" : "s"}
-`);
-  for (const a of data.annotations) {
-    const type = a.type === "highlight" ? c.amber("highlight") : a.type === "comment" ? c.blue("comment") : c.muted(a.type);
-    const date = c.muted(a.created_at.slice(0, 10));
-    console.log(`  ${type}  ${date}`);
-    if (a.selector_text) console.log(`  ${c.muted(">")} ${a.selector_text.slice(0, 80)}${a.selector_text.length > 80 ? "\u2026" : ""}`);
-    if (a.body) console.log(`  ${a.body.slice(0, 120)}${a.body.length > 120 ? "\u2026" : ""}`);
-    console.log();
+  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."));
 }
-async function noteAdd(config, slugOrId, text, json) {
+
+// src/commands/annotation.ts
+async function annotationList(config, slugOrId, json, opts = {}) {
   const spin = spinner("Resolving document\u2026");
   spin.start();
   const doc = await resolveSlug(config, slugOrId);
-  let body;
-  if (text) {
-    body = text;
-  } else {
-    if (process.stdin.isTTY) {
-      spin.stop();
-      throw new Error("No text provided. Use --text or pipe text via stdin.");
-    }
-    spin.stop();
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-      chunks.push(chunk);
-    }
-    body = Buffer.concat(chunks).toString("utf-8").trim();
-    spin.start();
+  spin.text = "Loading annotations\u2026";
+  const qs = new URLSearchParams();
+  qs.set("include_recipients", opts.includeRecipients ? "true" : "false");
+  if (opts.since) qs.set("since", opts.since);
+  const path = `/annotations/doc/${doc.id}${qs.toString() ? `?${qs.toString()}` : ""}`;
+  const data = await apiFetch(config, path);
+  spin.stop();
+  const annotations = Array.isArray(data) ? data : data.annotations ?? [];
+  if (json) {
+    console.log(JSON.stringify(annotations, null, 2));
+    return;
   }
-  if (!body) {
-    spin.stop();
-    throw new Error("No text provided. Use --text or pipe to stdin");
+  if (annotations.length === 0) {
+    console.log(c.muted("No annotations found."));
+    return;
   }
-  spin.text = "Adding annotation\u2026";
-  const result = await apiFetch(
-    config,
-    `/annotations/doc/${doc.id}`,
-    {
-      method: "POST",
-      body: JSON.stringify({ type: "comment", body })
-    }
+  console.log(
+    `${c.bright(doc.slug)} \u2014 ${annotations.length} annotation${annotations.length === 1 ? "" : "s"}
+`
   );
-  spin.stop();
-  if (json) {
-    console.log(JSON.stringify({ added: true, id: result.annotation.id, slug: doc.slug }));
-  } else {
-    console.log(`${c.teal("Added note to")} ${doc.slug}`);
+  for (const a of annotations) {
+    const typeLabel = a.type === "highlight" ? c.amber("highlight") : a.type === "underline" ? c.amber("underline") : a.type === "strikethrough" ? c.muted("strikethrough") : a.type === "redact" ? c.muted("redact") : a.type === "note" ? c.blue("note") : c.muted(a.type);
+    const date = c.muted(a.created_at.slice(0, 10));
+    const authorTag = a.author === "recipient" ? c.muted(` \xB7 ${a.share_link_label ?? "recipient"}`) : "";
+    console.log(`  ${typeLabel}  ${date}${authorTag}`);
+    if (a.quoted_text) {
+      console.log(`  ${c.muted(">")} ${a.quoted_text.slice(0, 80)}${a.quoted_text.length > 80 ? "\u2026" : ""}`);
+    }
+    if (a.note) {
+      console.log(`  ${a.note.slice(0, 120)}${a.note.length > 120 ? "\u2026" : ""}`);
+    }
+    console.log();
   }
 }
-async function noteSearch(config, query, json) {
+async function annotationSearch(config, query, json) {
   const spin = spinner(`Searching annotations for "${query}"\u2026`);
   spin.start();
   const data = await apiFetch(
@@ -842,22 +1076,290 @@ async function noteSearch(config, query, json) {
     `/annotations/search?q=${encodeURIComponent(query)}`
   );
   spin.stop();
+  const annotations = Array.isArray(data) ? data : data.annotations ?? [];
   if (json) {
-    console.log(JSON.stringify(data.annotations));
+    console.log(JSON.stringify(annotations, null, 2));
     return;
   }
-  if (data.annotations.length === 0) {
+  if (annotations.length === 0) {
     console.log(c.muted(`No annotation results for "${query}".`));
     return;
   }
-  const rows = data.annotations.map((a) => [
-    a.type === "highlight" ? c.amber("HL") : c.blue("CM"),
-    a.body.slice(0, 60) + (a.body.length > 60 ? "\u2026" : ""),
-    c.muted(a.created_at.slice(0, 10))
-  ]);
+  const rows = annotations.map((a) => {
+    const text = a.note ?? a.quoted_text ?? "";
+    return [
+      a.type === "highlight" ? c.amber("HL") : a.type === "note" ? c.blue("NT") : c.muted(a.type.slice(0, 2).toUpperCase()),
+      text.slice(0, 60) + (text.length > 60 ? "\u2026" : ""),
+      c.muted(a.created_at.slice(0, 10))
+    ];
+  });
   console.log(table(rows, { header: ["", "Text", c.muted("Date")] }));
   console.log(c.muted(`
-${data.annotations.length} result${data.annotations.length === 1 ? "" : "s"}`));
+${annotations.length} result${annotations.length === 1 ? "" : "s"}`));
+}
+
+// src/commands/snippet.ts
+import { readFileSync as readFileSync3, statSync as statSync2 } from "fs";
+import { extname as extname2, basename as basename2, resolve as resolve3 } from "path";
+var MIME_BY_EXT2 = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml"
+};
+function parseTags(raw) {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw;
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+function typeBadge(type) {
+  if (type === "quote") return c.amber("quote");
+  if (type === "code") return c.blue("code ");
+  if (type === "image") return c.teal("image");
+  return c.muted(type);
+}
+function formatBytes2(bytes) {
+  if (!bytes) return "";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+function safeHostname(url) {
+  if (!url) return "";
+  try {
+    return new URL(url).hostname.replace(/^www\./, "");
+  } catch {
+    return "";
+  }
+}
+async function snippetList(config, options, json) {
+  const spin = spinner("Loading snippets\u2026");
+  spin.start();
+  const qs = new URLSearchParams();
+  if (options.type) qs.set("type", options.type);
+  if (options.starred) qs.set("starred", "1");
+  if (options.tag) qs.set("tag", options.tag);
+  if (options.limit) qs.set("limit", String(options.limit));
+  const data = await apiFetch(
+    config,
+    `/snippets${qs.toString() ? `?${qs.toString()}` : ""}`
+  );
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify(data));
+    return;
+  }
+  const items = Array.isArray(data) ? data : data.items ?? [];
+  const total = Array.isArray(data) ? data.length : data.total ?? items.length;
+  if (items.length === 0) {
+    console.log(c.muted("No snippets found."));
+    return;
+  }
+  const rows = items.map((s) => {
+    const star = s.starred ? c.amber("\u2605") : " ";
+    const preview = s.type === "image" ? s.alt || "(image)" : s.content.split("\n")[0];
+    const trimmed = preview.length > 60 ? preview.slice(0, 60) + "\u2026" : preview;
+    const source = s.source_site_name || safeHostname(s.source_url);
+    return [
+      star,
+      typeBadge(s.type),
+      c.bright(s.id),
+      trimmed,
+      c.muted(source || ""),
+      c.muted(s.created_at.slice(0, 10))
+    ];
+  });
+  console.log(table(rows, { header: ["", "", "ID", "Preview", "Source", c.muted("Date")] }));
+  console.log(c.muted(`
+${total} snippet${total === 1 ? "" : "s"} total`));
+}
+async function snippetSearch(config, query, options, json) {
+  const spin = spinner(`Searching snippets for "${query}"\u2026`);
+  spin.start();
+  const qs = new URLSearchParams({ q: query });
+  if (options.type) qs.set("type", options.type);
+  if (options.limit) qs.set("limit", String(options.limit));
+  const data = await apiFetch(config, `/snippets/search?${qs.toString()}`);
+  spin.stop();
+  const items = Array.isArray(data) ? data : data.items ?? [];
+  if (json) {
+    console.log(JSON.stringify(items));
+    return;
+  }
+  if (items.length === 0) {
+    console.log(c.muted(`No snippet results for "${query}".`));
+    return;
+  }
+  for (const s of items) {
+    const star = s.starred ? c.amber("\u2605 ") : "";
+    const tags = parseTags(s.tags);
+    const tagStr = tags.length ? " " + tags.map((t) => c.muted(`#${t}`)).join(" ") : "";
+    console.log(`${star}${typeBadge(s.type)}  ${c.bright(s.id)}${tagStr}`);
+    if (s.type === "image") {
+      console.log(`  ${c.muted("alt:")} ${s.alt || "(none)"}  ${c.muted(formatBytes2(s.byte_size))}`);
+    } else {
+      const lines = s.content.split("\n").slice(0, 3);
+      for (const line of lines) {
+        const trimmed = line.length > 100 ? line.slice(0, 100) + "\u2026" : line;
+        console.log(`  ${trimmed}`);
+      }
+      if (s.content.split("\n").length > 3) console.log(c.muted("  \u2026"));
+    }
+    if (s.note) console.log(`  ${c.muted("note:")} ${s.note}`);
+    if (s.source_url) console.log(`  ${c.muted("source:")} ${s.source_url}`);
+    console.log();
+  }
+  console.log(c.muted(`${items.length} result${items.length === 1 ? "" : "s"}`));
+}
+async function snippetShow(config, id, json) {
+  const spin = spinner("Loading snippet\u2026");
+  spin.start();
+  const s = await apiFetch(config, `/snippets/${id}`);
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify(s));
+    return;
+  }
+  const tags = parseTags(s.tags);
+  console.log(`${typeBadge(s.type)}  ${c.bright(s.id)}${s.starred ? "  " + c.amber("\u2605") : ""}`);
+  console.log(c.muted(`created ${s.created_at}`));
+  if (tags.length) console.log(c.muted("tags: ") + tags.map((t) => `#${t}`).join(" "));
+  console.log();
+  if (s.type === "image") {
+    console.log(`${c.muted("alt:")}    ${s.alt || "(none)"}`);
+    console.log(`${c.muted("mime:")}   ${s.mime || "(unknown)"}`);
+    if (s.width && s.height) console.log(`${c.muted("size:")}   ${s.width}\xD7${s.height} (${formatBytes2(s.byte_size)})`);
+    console.log(`${c.muted("url:")}    ${config.endpoint}/api/snippets/${s.id}/raw`);
+  } else {
+    if (s.type === "code" && s.language) console.log(c.muted(`language: ${s.language}
+`));
+    console.log(s.content);
+  }
+  if (s.note) {
+    console.log();
+    console.log(c.muted("Note:"));
+    console.log(s.note);
+  }
+  if (s.source_url || s.source_title || s.source_site_name || s.source_author) {
+    console.log();
+    console.log(c.muted("Source:"));
+    if (s.source_title) console.log(`  ${s.source_title}`);
+    if (s.source_url) console.log(`  ${c.muted(s.source_url)}`);
+    const meta = [s.source_site_name, s.source_author].filter(Boolean).join(" \xB7 ");
+    if (meta) console.log(`  ${c.muted(meta)}`);
+  }
+}
+async function snippetNew(config, options, json) {
+  if (options.image) {
+    const path = resolve3(options.image);
+    let stat;
+    try {
+      stat = statSync2(path);
+    } catch {
+      throw new Error(`Image not found: ${path}`);
+    }
+    if (!stat.isFile()) throw new Error(`Not a file: ${path}`);
+    const ext = extname2(path).toLowerCase();
+    const mime = MIME_BY_EXT2[ext];
+    if (!mime) {
+      throw new Error(`Unsupported image extension: ${ext}. Allowed: ${Object.keys(MIME_BY_EXT2).join(", ")}`);
+    }
+    if (stat.size > 25 * 1024 * 1024) {
+      throw new Error(`Image exceeds 25 MB limit (${formatBytes2(stat.size)})`);
+    }
+    const spin2 = spinner(`Uploading ${basename2(path)}\u2026`);
+    spin2.start();
+    const bytes = readFileSync3(path);
+    const form = new FormData();
+    form.set("metadata", JSON.stringify({
+      alt: options.alt ?? null,
+      note: options.note ?? null,
+      source_url: options.sourceUrl ?? null,
+      source_title: options.sourceTitle ?? null,
+      source_site_name: options.sourceSiteName ?? null,
+      source_author: options.sourceAuthor ?? null,
+      tags: options.tags ?? [],
+      starred: options.starred ? 1 : 0
+    }));
+    form.set("file", new File([bytes], basename2(path), { type: mime }));
+    const result2 = await apiFetch(config, "/snippets", {
+      method: "POST",
+      body: form
+    });
+    spin2.stop();
+    if (json) {
+      console.log(JSON.stringify(result2));
+    } else {
+      console.log(`${c.teal("Created image snippet")} ${c.bright(result2.id)}`);
+    }
+    return;
+  }
+  let content = options.text;
+  if (!content && options.file) {
+    content = readFileSync3(resolve3(options.file), "utf-8");
+  }
+  if (!content && !process.stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    content = Buffer.concat(chunks).toString("utf-8");
+  }
+  if (!content) {
+    throw new Error('No content. Provide --text "...", --file <path>, or pipe content via stdin.');
+  }
+  const spin = spinner("Creating snippet\u2026");
+  spin.start();
+  const result = await apiFetch(config, "/snippets", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      type: options.type ?? "quote",
+      content: content.trim(),
+      language: options.language ?? null,
+      note: options.note ?? null,
+      source_url: options.sourceUrl ?? null,
+      source_title: options.sourceTitle ?? null,
+      source_site_name: options.sourceSiteName ?? null,
+      source_author: options.sourceAuthor ?? null,
+      tags: options.tags ?? [],
+      starred: options.starred ? 1 : 0
+    })
+  });
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify(result));
+  } else {
+    console.log(`${c.teal("Created snippet")} ${c.bright(result.id)} ${c.muted(`(${result.type})`)}`);
+  }
+}
+async function snippetDelete(config, id, json) {
+  const spin = spinner("Deleting snippet\u2026");
+  spin.start();
+  await apiFetch(config, `/snippets/${id}`, { method: "DELETE" });
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify({ deleted: true, id }));
+  } else {
+    console.log(`${c.teal("Deleted snippet")} ${id}`);
+  }
+}
+async function snippetStar(config, id, starred, json) {
+  const result = await apiFetch(config, `/snippets/${id}`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ starred: starred ? 1 : 0 })
+  });
+  if (json) {
+    console.log(JSON.stringify(result));
+  } else {
+    console.log(`${c.teal(starred ? "Starred" : "Unstarred")} ${id}`);
+  }
 }
 
 // src/commands/doctor.ts
@@ -898,7 +1400,7 @@ async function doctor(config, json) {
     const where = hasProjectSkill ? "project" : "user";
     checks.push({ name: "Claude skill", status: "ok", detail: `installed (${where}-level)` });
   } else {
-    checks.push({ name: "Claude skill", status: "warn", detail: "not installed (run `arty skill install`)" });
+    checks.push({ name: "Claude skill", status: "warn", detail: "not installed (run `artyfax skill install`)" });
   }
   if (json) {
     console.log(JSON.stringify(checks));
@@ -922,32 +1424,739 @@ async function doctor(config, json) {
   }
 }
 
-// src/commands/skill.ts
-async function skillInstall(_project) {
-  console.log(c.amber("Skill installation is not available yet."));
-  console.log(c.muted("The Artyfax skill content is being designed in design-28."));
-  console.log(c.muted("Once ready, `arty skill install` will write skill files to ~/.claude/skills/artyfax"));
+// src/commands/work.ts
+var STATUS_SYMBOLS = {
+  backlog: "\u25CB",
+  up_next: "\u25CE",
+  on_hold: "\u23F8",
+  in_progress: "\u25CF",
+  in_review: "\u25C9",
+  done: "\u2713",
+  cancelled: "\u2717"
+};
+var STATUS_LABELS = {
+  backlog: "Backlog",
+  up_next: "Up Next",
+  on_hold: "On Hold",
+  in_progress: "In Progress",
+  in_review: "In Review",
+  done: "Done",
+  cancelled: "Cancelled"
+};
+function statusLabel(s) {
+  const sym = STATUS_SYMBOLS[s] || "?";
+  const label = STATUS_LABELS[s] || s;
+  return `${sym} ${label}`;
 }
-async function skillStatus() {
-  console.log(c.amber("Skill status is not available yet."));
-  console.log(c.muted("Run `arty doctor` to check basic setup."));
+function progress(item) {
+  if (item.task_total === 0) return c.muted("-");
+  return `${item.task_done}/${item.task_total}`;
 }
-async function skillUpdate() {
-  console.log(c.amber("Skill update is not available yet."));
+async function workBoard(config, json) {
+  const spin = spinner("Loading board\u2026");
+  spin.start();
+  const data = await apiFetch(config, "/projects/work");
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify(data.work_items, null, 2));
+    return;
+  }
+  if (data.work_items.length === 0) {
+    console.log(c.muted("No work items. Promote a document in its settings panel."));
+    return;
+  }
+  const byStatus = /* @__PURE__ */ new Map();
+  for (const item of data.work_items) {
+    const list2 = byStatus.get(item.work_status) || [];
+    list2.push(item);
+    byStatus.set(item.work_status, list2);
+  }
+  for (const status of ["up_next", "on_hold", "in_progress", "in_review", "backlog"]) {
+    const items = byStatus.get(status);
+    if (!items || items.length === 0) continue;
+    console.log(`
+${c.bright(statusLabel(status))} ${c.muted(`(${items.length})`)}`);
+    for (const item of items) {
+      const id = item.work_id ? c.amber(item.work_id.padEnd(8)) : c.muted("--------");
+      const prog = progress(item);
+      const agent = item.work_agent ? c.muted(`[${item.work_agent}]`) : "";
+      const current = item.task_current ? c.muted(` \u2014 ${item.task_current.slice(0, 50)}`) : "";
+      console.log(`  ${id} ${item.title} ${prog} ${agent}${current}`);
+    }
+  }
+  console.log();
 }
-
-// src/cli.ts
-var VERSION = true ? "0.2.3" : "0.0.0-dev";
-function brandedHelp() {
-  return `
-${c.amber("artyfax")} ${c.muted(`v${VERSION}`)} \u2014 your personal document library
-
-${c.bright("Usage:")} arty <command> [options]
-
-${c.bright("Documents")}
-  save <file>            Save a document (markdown or HTML)
-  read <slug>            Read document content (handles E2EE)
-  list                   List documents
+async function workList(config, json, flags) {
+  const spin = spinner("Loading work items\u2026");
+  spin.start();
+  const qs = new URLSearchParams();
+  if (flags.project) qs.set("project_id", flags.project);
+  if (flags.agent) qs.set("agent", flags.agent);
+  if (flags.status) qs.set("status", flags.status);
+  if (flags.type) qs.set("type", flags.type);
+  const data = await apiFetch(config, `/projects/work?${qs}`);
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify(data.work_items, null, 2));
+    return;
+  }
+  if (data.work_items.length === 0) {
+    console.log(c.muted("No matching work items."));
+    return;
+  }
+  const rows = data.work_items.map((item) => [
+    item.work_id ? c.amber(item.work_id) : c.muted("-"),
+    item.title.slice(0, 50),
+    statusLabel(item.work_status),
+    item.work_type || c.muted("-"),
+    item.work_agent || c.muted("-"),
+    progress(item)
+  ]);
+  console.log(table(rows, { header: ["ID", "Title", "Status", "Type", "Agent", "Progress"] }));
+}
+async function workNext(config, json, agent) {
+  const spin = spinner("Picking next\u2026");
+  spin.start();
+  const data = await apiFetch(config, "/projects/work?status=up_next");
+  spin.stop();
+  const items = data.work_items;
+  if (items.length === 0) {
+    console.log(json ? "null" : c.muted("No items in Up Next."));
+    return;
+  }
+  let pick = items[0];
+  if (agent) {
+    const assigned = items.find((i) => i.work_agent === agent.toLowerCase());
+    const unassigned = items.find((i) => !i.work_agent);
+    pick = assigned || unassigned || items[0];
+  }
+  if (json) {
+    console.log(JSON.stringify(pick, null, 2));
+    return;
+  }
+  const id = pick.work_id ? c.amber(pick.work_id) : pick.id;
+  console.log(`${id} ${c.bright(pick.title)}`);
+  if (pick.task_current) console.log(c.muted(`  Current: ${pick.task_current}`));
+  console.log(c.muted(`  Progress: ${progress(pick)} | Agent: ${pick.work_agent || "unassigned"}`));
+  console.log(c.muted(`  ID: ${pick.id}`));
+}
+async function resolveWorkId(config, idOrWorkId) {
+  const data = await apiFetch(config, `/resolve/${encodeURIComponent(idOrWorkId)}`);
+  return data.id;
+}
+async function workSetStatus(config, docId, status, json) {
+  const demote = ["none", "off", "remove"].includes(status.toLowerCase());
+  const spin = spinner(demote ? "Removing from board\u2026" : `Setting status to ${status}\u2026`);
+  spin.start();
+  const resolvedId = await resolveWorkId(config, docId);
+  const data = await apiFetch(config, `/documents/${resolvedId}/metadata`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ work_status: demote ? null : status })
+  });
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify(data));
+    return;
+  }
+  console.log(c.bright(`${data.work_id || docId} \u2192 ${demote ? "removed from board" : statusLabel(status)}`));
+}
+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;
+  if (!projectId) {
+    console.error(c.rose("Error: --project is required. Work items must belong to a project."));
+    process.exitCode = 1;
+    return;
+  }
+  const spin = spinner("Creating work item\u2026");
+  spin.start();
+  const id = crypto.randomUUID();
+  const slugBody = title.toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  const slug = `inbox/${slugBody || `item-${id.slice(0, 8)}`}`;
+  const saveRes = await apiFetch(config, "/documents", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      id,
+      slug,
+      title,
+      category: "inbox",
+      // 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: ""
+    })
+  });
+  if (saveRes.ok) {
+    const status = flags.status || "up_next";
+    await apiFetch(config, `/documents/${id}/metadata`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        project_id: projectId,
+        work_status: status,
+        work_type: flags.type || null,
+        work_agent: flags.agent || null
+      })
+    });
+  }
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify({ ok: true, id }));
+    return;
+  }
+  console.log(c.bright(`Created: ${title}`));
+  console.log(c.muted(`ID: ${id}`));
+}
+
+// src/commands/project.ts
+import { readFileSync as readFileSync4, writeFileSync, existsSync as existsSync2 } from "node:fs";
+import { resolve as resolve4 } from "node:path";
+var ARTYFAX_FILE = "ARTYFAX.md";
+var USER_MARKER = "<!-- arty:user -->";
+async function projectList(config, json) {
+  const spin = spinner("Loading projects\u2026");
+  spin.start();
+  const data = await apiFetch(config, "/projects");
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify(data.projects, null, 2));
+    return;
+  }
+  if (data.projects.length === 0) {
+    console.log(c.muted('No projects. Create one with `artyfax project create "Name" --prefix XX`.'));
+    return;
+  }
+  const rows = data.projects.map((p) => [
+    c.amber(p.prefix),
+    p.name,
+    c.muted(String(p.next_work_id - 1) + " items"),
+    p.description ? c.muted(p.description.slice(0, 40)) : ""
+  ]);
+  console.log(table(rows, { header: ["Prefix", "Name", "Items", "Description"] }));
+}
+async function projectCreate(config, name, prefix, description, json, workspaces) {
+  const spin = spinner("Creating project\u2026");
+  spin.start();
+  const workspace_ids = workspaces?.length ? await resolveWorkspaceIds(config, workspaces) : [];
+  const data = await apiFetch(config, "/projects", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      name,
+      prefix,
+      description,
+      workspace_scope: workspace_ids.length ? "scoped" : "global",
+      workspace_ids
+    })
+  });
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  console.log(c.bright(`Project created: ${name} (${c.amber(data.prefix)})`));
+}
+var STATUS_ORDER = ["in_progress", "in_review", "up_next", "on_hold", "backlog", "done", "cancelled"];
+var STATUS_HEADINGS = {
+  in_progress: "In Progress",
+  in_review: "In Review",
+  up_next: "Up Next",
+  on_hold: "On Hold",
+  backlog: "Backlog",
+  done: "Done",
+  cancelled: "Cancelled"
+};
+function formatProgress(item) {
+  if (item.task_total === 0) return "";
+  return ` [${item.task_done}/${item.task_total}]`;
+}
+function resolveProject(projects, hint) {
+  if (hint) {
+    return projects.find(
+      (p) => p.slug === hint || p.prefix.toLowerCase() === hint.toLowerCase() || p.name.toLowerCase() === hint.toLowerCase()
+    ) || null;
+  }
+  if (projects.length === 1) return projects[0];
+  return null;
+}
+function parseExistingPrefix(filePath) {
+  if (!existsSync2(filePath)) return null;
+  const content = readFileSync4(filePath, "utf-8");
+  const match = content.match(/^# .+\(([A-Z]+)\)/m);
+  return match ? match[1] : null;
+}
+function extractUserContent(filePath) {
+  if (!existsSync2(filePath)) return "";
+  const content = readFileSync4(filePath, "utf-8");
+  const matches = [...content.matchAll(new RegExp(`^${USER_MARKER}$`, "gm"))];
+  const match = matches[matches.length - 1];
+  if (!match || match.index == null) return "";
+  return content.substring(match.index + USER_MARKER.length);
+}
+function padTable(rows) {
+  const cols = rows[0].length;
+  const widths = Array.from(
+    { length: cols },
+    (_, i) => Math.max(...rows.map((r) => r[i].length))
+  );
+  const lines = [];
+  for (let r = 0; r < rows.length; r++) {
+    const cells = rows[r].map((cell, i) => ` ${cell.padEnd(widths[i])} `);
+    lines.push(`|${cells.join("|")}|`);
+    if (r === 0) {
+      const sep = widths.map((w) => "-".repeat(w + 2));
+      lines.push(`|${sep.join("|")}|`);
+    }
+  }
+  return lines.join("\n");
+}
+function generateWorkflow(project) {
+  const p = project.prefix;
+  const tbl = padTable([
+    ["Action", "CLI", "MCP"],
+    ["Board overview", "`artyfax work list`", `\`list_work(project: '${p}')\``],
+    ["Read a work item", "`artyfax read <slug>`", `\`get_document('${p}-2', include_annotations: true)\``],
+    ["Update content", "`artyfax update <slug> <file>`", `\`patch_document('${p}-2', patches)\``],
+    ["Tick a task", '`artyfax task <id> "text" <state>`', `\`update_task('${p}-2', task, state)\``],
+    ["Claim and start", "`artyfax work status <id> in_progress`", `\`start_work('${p}-2', agent: '<agent>')\``],
+    ["Change status", "`artyfax work status <id> <status>`", `\`update_work_status('${p}-2', status)\``],
+    ["Refresh this file", "`artyfax init`", "--"]
+  ]);
+  return `## Workflow
+
+This project tracks work in [Artyfax](https://artyfax.io). Reference this file for the landscape, then use the MCP tools or CLI for live data.
+
+${tbl}
+
+The CLI command is \`artyfax\`. The examples above spell it out in full; if you prefer, shorten it to \`arty\` or \`ax\` - they are the same command.
+
+All MCP tools that take a document ID also accept work IDs (e.g. \`${p}-2\`) directly.
+
+### Picking Up Agent Work
+
+When asked for the next task for a specific agent (for example "next Codex task"), use live Artyfax data and check: assigned \`in_progress\`, assigned \`up_next\`, assigned \`backlog\`, top unassigned \`up_next\`, and any work ID implied by the worktree name. If an assigned \`up_next\` item exists, use it. If the plausible choices differ (for example assigned backlog vs unassigned \`up_next\`), confirm before claiming. Never claim \`in_review\`, \`done\`, or another agent's item without explicit direction.
+
+### Lifecycle
+
+1. **Pick up work** - read this file for the landscape, then use live MCP/CLI data to select the correct item. Use the agent-specific pickup flow above when the requester names an agent.
+2. **Claim it before writing code** - \`start_work('${p}-15', agent: '<agent>')\` moves to In Progress, promotes to top of column, and shows your name on the board. Always do this before implementing anything so the board reflects active work. Claiming signals ownership; it is not approval to start coding when the work item still needs clarification.
+3. **Work, updating the board per task** - read the doc with \`get_document('${p}-15')\`, then for each task: mark it \`active\` when you start it and \`done\` when you finish it via \`update_task('${p}-15', '<task substring>', 'active'|'done')\`. \`active\` surfaces the live current task on the board so other sessions (and the user) can see what is being worked right now, not just a count.
+4. **Blocked?** - \`update_work_status('${p}-15', 'on_hold')\` and note why
+5. **Resuming work** - if you pick an item back up after it has left In Progress (it sits in In Review, on_hold, or up_next), call \`update_work_status('${p}-15', 'in_progress')\` *first*, so the board shows it active again while you work. Move it back to In Review only once the new work is finished.
+6. **Complete** - after pushing the final commit, call \`complete_work('${p}-15')\` to move to In Review. "In Review" means implementation is done and waiting for the user to verify - not that it's perfect. Before completing, every open question and every unticked task must be put to the user - you do not decide their fate yourself. A "stretch", "consider", or "optional" task is still an open question. Surface each one with a structured question/approval tool (\`AskUserQuestion\` where the runtime provides one) so the user chooses what happens: do it now, split it into a new follow-up work item, or drop it. You do not get to judge something "quick and safe" and skip the question. Never move an item to In Review with a dangling task or unanswered question left hanging.
+7. **Done** - only the user moves parent items from In Review to Done after personal review
+
+### Thin work items
+
+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.
+
+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.
+
+- **Target: per task.** Mark each task \`active\` on start and \`done\` on finish via \`update_task\`. It is a single lightweight call (substring match, server reparses progress automatically) - no full-content rewrite, so the cost is negligible. Prefer it over \`patch_document\` for ticking; reserve \`patch_document\` for editing the doc body.
+- **Floor: per logical section.** If per-task is genuinely too chatty for a fast run of trivial steps, batch a section's ticks in one \`update_task\` sequence the moment that section is done and verified - never later.
+- **Never batch only at the end.** A board that jumps from 0 to done in one shot defeats the purpose and hides active work from concurrent sessions.
+- **Cost note:** \`update_task\` is cheap, but each call is a synchronous round trip (MCP calls can't be backgrounded). For a long run of one-line tasks, the per-section floor is the sensible trade; for substantial tasks, always go per task.
+
+### Keeping this file current
+
+This file is generated by \`artyfax init\`. Do not hand-edit generated workflow or board sections for durable changes; update the CLI generator/template, then regenerate. Custom notes in the user section are preserved.
+
+Use Artyfax MCP/CLI for live work updates (status changes, task ticks, assignments). Run \`artyfax init\` to refresh this snapshot when the generated board view is stale or after meaningful board changes.
+
+### Conventions
+
+- **Work IDs** (e.g. ${p}-15) are stable. Reference them in commits and changelogs. All MCP tools accept them directly.
+- **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).
+`;
+}
+function generateSaving() {
+  return `## Saving documents
+
+Artyfax is the default home for documents. When you produce a document for the user, or they hand you one (markdown, HTML, a report, a generated artifact, a story), save it into Artyfax with the MCP tools or the \`artyfax\` CLI - not the local filesystem. Reach for a loose local file only when the user explicitly asks. A standalone HTML page is a first-class document: save it as-is, don't restyle it to match other documents and don't check whether the reader can render it first.
+
+### Images on documents
+
+To put a local or freshly generated image on a document, as a cover or inline, use the CLI - not the MCP \`set_cover_image\` tool, whose base64 path truncates large images over the transport and degrades them (its URL option only helps when the image already lives at a public URL).
+
+- \`artyfax cover <doc> <file>\` - set a document's cover image (renders best at 1200x630).
+- \`artyfax image <doc> <file>\` - upload an inline image and print the \`![alt](images/<hash>.<ext>)\` markdown to paste into the body.
+
+\`<doc>\` is a doc id, slug, or work id (any document). Accepts png/jpg/webp/gif/avif/svg up to 5 MB. A public image URL in \`![](...)\` is re-hosted automatically on save, so only local files need these commands; \`set_cover_image\` with \`image_url\` is still right for a cover already at a public URL.
+`;
+}
+function generateBoard(items) {
+  const byStatus = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const list2 = byStatus.get(item.work_status) || [];
+    list2.push(item);
+    byStatus.set(item.work_status, list2);
+  }
+  const lines = [];
+  for (const status of STATUS_ORDER) {
+    const group = byStatus.get(status);
+    if (!group || group.length === 0) continue;
+    const heading = STATUS_HEADINGS[status] || status;
+    if (status === "done" || status === "cancelled") {
+      lines.push(`## ${heading} (${group.length})`);
+      lines.push("");
+      lines.push(`${group.length} ${status === "done" ? "completed" : "cancelled"} items. Use \`artyfax work list --status ${status}\` or \`list_work(status: '${status}')\` for details.`);
+    } else {
+      lines.push(`## ${heading}`);
+      lines.push("");
+      for (const item of group) {
+        const id = item.work_id || item.id.slice(0, 8);
+        const prog = formatProgress(item);
+        const agent = item.work_agent ? ` @${item.work_agent}` : "";
+        lines.push(`- ${id} ${item.title}${prog}${agent}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+async function init(config, projectHint) {
+  const filePath = resolve4(process.cwd(), ARTYFAX_FILE);
+  const isUpdate = existsSync2(filePath);
+  const spin = spinner(isUpdate ? "Refreshing ARTYFAX.md\u2026" : "Initialising ARTYFAX.md\u2026");
+  spin.start();
+  const existingPrefix = isUpdate ? parseExistingPrefix(filePath) : null;
+  const hint = projectHint || existingPrefix || void 0;
+  const projects = await apiFetch(config, "/projects");
+  const project = resolveProject(projects.projects, hint);
+  if (!project) {
+    spin.stop();
+    if (projects.projects.length === 0) {
+      console.error(c.rose('No projects found. Create one first: artyfax project create "Name" --prefix XX'));
+    } else {
+      const prefixes = projects.projects.map((p) => c.amber(p.prefix)).join(", ");
+      console.error(c.rose(`Specify a project: artyfax init <prefix>`));
+      console.error(c.muted(`Available: ${prefixes}`));
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const qs = new URLSearchParams({ project_id: project.id });
+  const data = await apiFetch(config, `/projects/work?${qs}`);
+  spin.stop();
+  const userContent = extractUserContent(filePath);
+  const d = /* @__PURE__ */ new Date();
+  const now = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+  const generated = [
+    `# ${project.name} (${project.prefix})`,
+    "",
+    `Last updated: ${now} \xB7 Live data: \`artyfax work list\` or \`list_work(project: '${project.prefix}')\``,
+    "",
+    generateSaving(),
+    generateWorkflow(project),
+    generateBoard(data.work_items),
+    USER_MARKER
+  ].join("\n");
+  const content = generated + userContent;
+  writeFileSync(filePath, content);
+  const action = isUpdate ? "Updated" : "Created";
+  console.log(c.bright(`${action} ${ARTYFAX_FILE}`));
+  console.log(c.muted(`${project.name} (${project.prefix}) \xB7 ${data.work_items.length} work items`));
+  if (!isUpdate) {
+    const claudeMd = resolve4(process.cwd(), "CLAUDE.md");
+    if (existsSync2(claudeMd)) {
+      const claudeContent = readFileSync4(claudeMd, "utf-8");
+      if (!claudeContent.includes("@ARTYFAX.md")) {
+        console.log("");
+        console.log(c.muted("Add to CLAUDE.md to give agents the project board:"));
+        console.log(c.amber("  @ARTYFAX.md"));
+      }
+    }
+  }
+}
+
+// src/commands/skill.ts
+async function skillInstall(_project) {
+  console.log(c.amber("Skill installation is not available yet."));
+  console.log(c.muted("The Artyfax skill content is being designed in design-28."));
+  console.log(c.muted("Once ready, `artyfax skill install` will write skill files to ~/.claude/skills/artyfax"));
+}
+async function skillStatus() {
+  console.log(c.amber("Skill status is not available yet."));
+  console.log(c.muted("Run `artyfax doctor` to check basic setup."));
+}
+async function skillUpdate() {
+  console.log(c.amber("Skill update is not available yet."));
+}
+
+// src/commands/task.ts
+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 tasks = await fetchTasks(config, id);
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify(tasks, null, 2));
+    return;
+  }
+  if (tasks.length === 0) {
+    console.log(c.muted("No tasks found"));
+    return;
+  }
+  const stateIcon = { done: c.teal("\u2713"), active: c.amber("~"), pending: c.muted("\u25CB") };
+  for (const t of tasks) {
+    console.log(`${stateIcon[t.state]} ${c.muted(`[${t.index}]`)} ${t.text}`);
+  }
+  const done = tasks.filter((t) => t.state === "done").length;
+  const active = tasks.filter((t) => t.state === "active").length;
+  console.log(c.muted(`
+${done}/${tasks.length} done${active ? `, ${active} active` : ""}`));
+}
+async function taskUpdate(config, identifier, taskText, state, json) {
+  if (!["active", "done", "pending"].includes(state)) {
+    console.error(c.rose(`Invalid state "${state}". Must be: active, done, pending`));
+    process.exit(1);
+  }
+  const spin = spinner(`Setting task to ${state}\u2026`);
+  spin.start();
+  const id = await resolveId(config, identifier);
+  const tasks = await fetchTasks(config, id);
+  const needle = taskText.toLowerCase();
+  const match = tasks.find((t) => t.text.toLowerCase().includes(needle));
+  if (!match) {
+    spin.stop();
+    console.error(c.rose(`No task matching "${taskText}" found`));
+    process.exit(1);
+  }
+  await apiFetch(config, `/documents/${id}/task/${match.index}`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ state })
+  });
+  spin.stop();
+  if (json) {
+    console.log(JSON.stringify({ ok: true, task_index: match.index, task_text: match.text, state }));
+    return;
+  }
+  const stateLabel = { done: c.teal("done"), active: c.amber("active"), pending: c.muted("pending") };
+  console.log(`${stateLabel[state]} ${match.text}`);
+}
+
+// ../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 { 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.1" : "0.0.0-dev";
+function brandedHelp() {
+  return `
+${c.amber("artyfax")} ${c.muted(`v${VERSION}`)} \u2014 your personal document library
+
+${c.bright("Usage:")} artyfax <command> [options]
+        ${c.muted("aliases:")} arty <command> \xB7 ax <command>
+
+${c.bright("Documents")}
+  save <file>            Save a document (markdown or HTML)
+  read <slug>            Read document content (handles E2EE)
+  list                   List documents
   get <slug>             Document metadata as JSON
   search <query>         Full-text search
   update <slug> <file>   Push updated content (auto-encrypts secure docs)
@@ -956,20 +2165,48 @@ ${c.bright("Documents")}
   open <slug>            Open document in browser
   secure <slug>          Encrypt a document
   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
   share list [slug]      List shares
   share revoke <hash>    Revoke a share link
   cat list               List categories
-  tag list               List tags
+  tag list               List tags (grouped by namespace)
+  tag delete <tag>       Remove a tag from all docs, annotations, snippets
   version list <slug>    Version history
   version restore <slug> Restore a previous version
 
 ${c.bright("Annotations")}
-  note list <slug>       List annotations on a document
-  note add <slug>        Add an annotation
-  note search <query>    Search annotations
+  annotation list <slug> List a document's annotations (--include-recipients, --since)
+  annotation search <q>  Search annotations
+
+${c.bright("Snippets")}
+  snippets list                List snippets (filter --type --tag --starred)
+  snippets search <query>      Full-text search across snippets
+  snippets show <id>           Show a snippet's full content
+  snippets new                 Create a snippet (--text, --file, --image)
+  snippets delete <id>         Delete a snippet
+  snippets star <id>           Star a snippet
+  snippets unstar <id>         Unstar a snippet
+
+${c.bright("Work")}
+  work                   Board summary (kanban overview)
+  work list              List work items (--project, --agent, --status, --type)
+  work next              Pick next Up Next item (--agent)
+  work start <id>        Mark In Progress
+  work done <id>         Mark Done
+  work status <id> <s>   Set arbitrary status ("none" removes from board)
+  work create "title"    Quick-create a work item (--project, --type, --agent)
+
+${c.bright("Projects")}
+  project list           List projects
+  project create "name"  Create a project (--prefix XX)
+  init [prefix]          Generate or refresh ARTYFAX.md for a project board
+  workspace list         List workspaces
 
 ${c.bright("Tools")}
   doctor                 Verify CLI setup
@@ -992,10 +2229,10 @@ ${c.bright("Environment")}
 `.trim();
 }
 var COMMAND_HELP = {
-  save: `${c.amber("arty save")} \u2014 save a document
+  save: `${c.amber("artyfax save")} \u2014 save a document
 
-${c.bright("Usage:")} arty save <file> [options]
-        arty save --url <url> [options]
+${c.bright("Usage:")} artyfax save <file> [options]
+        artyfax save --url <url> [options]
 
 ${c.bright("Options:")}
   --url <url>          Save from URL (server-side extraction)
@@ -1011,23 +2248,27 @@ ${c.bright("Options:")}
   --json               JSON output
 
 ${c.bright("Examples:")}
-  arty save notes.md --category inbox
-  arty save --url https://example.com/article --category articles
-  arty save report.md --secure --category reports`,
-  read: `${c.amber("arty read")} \u2014 read document content
+  artyfax save notes.md --category inbox
+  artyfax save --url https://example.com/article --category articles
+  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:")} arty read <slug>
+${c.bright("Usage:")} artyfax read <slug>
 
 Outputs the document's markdown source to stdout. Handles E2EE
 decryption automatically (prompts for passphrase if needed).
 
 ${c.bright("Examples:")}
-  arty read inbox/my-doc
-  arty read my-doc                  # partial slug match
-  arty read inbox/my-doc > out.md   # pipe to file`,
-  list: `${c.amber("arty list")} \u2014 list documents
+  artyfax read inbox/my-doc
+  artyfax read my-doc                  # partial slug match
+  artyfax read inbox/my-doc > out.md   # pipe to file`,
+  list: `${c.amber("artyfax list")} \u2014 list documents
 
-${c.bright("Usage:")} arty list [options]
+${c.bright("Usage:")} artyfax list [options]
 
 ${c.bright("Options:")}
   --category <name>    Filter by category
@@ -1035,43 +2276,46 @@ ${c.bright("Options:")}
   --offset <n>         Skip first N results
   --archived           Include archived documents
   --parent-id <id>     Filter by parent document
+  --tag <tag>          Filter to documents carrying this exact tag
   --json               JSON output
 
 ${c.bright("Examples:")}
-  arty list --category inbox --limit 10
-  arty list --archived --json`,
-  get: `${c.amber("arty get")} \u2014 document metadata
+  artyfax list --category inbox --limit 10
+  artyfax list --tag role:design
+  artyfax list --archived --json`,
+  get: `${c.amber("artyfax get")} \u2014 document metadata
 
-${c.bright("Usage:")} arty get <slug>
+${c.bright("Usage:")} artyfax get <slug>
 
 Outputs full document metadata as JSON. For scripting and inspection.
 
 ${c.bright("Examples:")}
-  arty get inbox/my-doc
-  arty get my-doc | jq .category`,
-  search: `${c.amber("arty search")} \u2014 full-text search
+  artyfax get inbox/my-doc
+  artyfax get my-doc | jq .category`,
+  search: `${c.amber("artyfax search")} \u2014 full-text search
 
-${c.bright("Usage:")} arty search <query> [--json]
+${c.bright("Usage:")} artyfax search <query> [--json]
 
 ${c.bright("Examples:")}
-  arty search "deployment guide"
-  arty search cloudflare --json`,
-  update: `${c.amber("arty update")} \u2014 push updated content
+  artyfax search "deployment guide"
+  artyfax search cloudflare --json`,
+  update: `${c.amber("artyfax update")} \u2014 push updated content
 
-${c.bright("Usage:")} arty update <slug> [file]
-        cat file.md | arty update <slug>
+${c.bright("Usage:")} artyfax update <slug> [file]
+        cat file.md | artyfax update <slug>
 
 Reads from file or stdin. Auto-encrypts if the target is a secure document.
 
 ${c.bright("Examples:")}
-  arty update inbox/my-doc updated.md
-  echo "# New content" | arty update inbox/my-doc`,
-  metadata: `${c.amber("arty metadata")} \u2014 update document metadata
+  artyfax update inbox/my-doc updated.md
+  echo "# New content" | artyfax update inbox/my-doc`,
+  metadata: `${c.amber("artyfax metadata")} \u2014 update document metadata
 
-${c.bright("Usage:")} arty metadata <slug> [options]
+${c.bright("Usage:")} artyfax metadata <slug> [options]
 
 ${c.bright("Options:")}
   --category <name>    Move to category
+  --slug <cat/slug>    Rename the URL slug (cosmetic; URLs resolve by id)
   --tags <t1,t2>       Set tags (comma-separated)
   --title <name>       Update title
   --theme <name>       Set theme
@@ -1080,61 +2324,127 @@ ${c.bright("Options:")}
   --json               JSON output
 
 ${c.bright("Examples:")}
-  arty metadata inbox/my-doc --category reports --tags "q1,finance"
-  arty metadata my-doc --archived`,
-  delete: `${c.amber("arty delete")} \u2014 delete a document
+  artyfax metadata inbox/my-doc --category reports --tags "q1,finance"
+  artyfax metadata my-doc --slug plans/rename-safe-urls
+  artyfax metadata my-doc --archived`,
+  cover: `${c.amber("artyfax cover")} \u2014 set a document's cover image
 
-${c.bright("Usage:")} arty delete <slug> [--yes] [--json]
+${c.bright("Usage:")} artyfax cover <doc> <image-file> [options]
+
+Uploads a local image and sets it as the document's cover. Works for any
+document (pass a doc id, slug, or work id). Unlike the MCP set_cover_image
+tool, this carries a full-quality local image with no transport truncation.
+
+${c.bright("Options:")}
+  --alt "..."          Alt text for the cover image
+  --json               JSON output
+
+${c.bright("Notes:")}
+  Accepts png/jpg/webp/gif/avif/svg up to 5 MB. Covers render best at
+  1200\xD7630 (the hero + social card shape).
+
+${c.bright("Examples:")}
+  artyfax cover p8KV4dvrgJTA ./hero.png
+  artyfax cover inbox/my-doc ./hero.png --alt "Release banner"`,
+  image: `${c.amber("artyfax image")} \u2014 upload an inline image to a document
+
+${c.bright("Usage:")} artyfax image <doc> <image-file> [options]
+
+Uploads a local image into the document's image store and prints the
+markdown snippet to paste into the body. Works for any document (doc id,
+slug, or work id).
+
+${c.bright("Options:")}
+  --alt "..."          Alt text for the image
+  --json               JSON output
+
+${c.bright("Examples:")}
+  artyfax image p8KV4dvrgJTA ./screenshot.png
+  artyfax image inbox/my-doc ./diagram.png --alt "Architecture"`,
+  delete: `${c.amber("artyfax delete")} \u2014 delete a document
+
+${c.bright("Usage:")} artyfax delete <slug> [--yes] [--json]
 
 Prompts for confirmation unless --yes is passed.
 
 ${c.bright("Examples:")}
-  arty delete inbox/old-doc
-  arty delete inbox/old-doc --yes   # skip confirmation`,
-  open: `${c.amber("arty open")} \u2014 open in browser
+  artyfax delete inbox/old-doc
+  artyfax delete inbox/old-doc --yes   # skip confirmation`,
+  open: `${c.amber("artyfax open")} \u2014 open in browser
 
-${c.bright("Usage:")} arty open <slug>
+${c.bright("Usage:")} artyfax open <slug>
 
 Opens the document URL in your default browser.`,
-  share: `${c.amber("arty share")} \u2014 manage share links
+  share: `${c.amber("artyfax share")} \u2014 manage share links
+
+${c.bright("Usage:")} artyfax share create <slug>    Create a share link
+        artyfax share list [slug]      List all shares (or per-document)
+        artyfax share revoke <hash>    Revoke a share link
+
+${c.bright("Examples:")}
+  artyfax share create inbox/my-doc
+  artyfax share list --json
+  artyfax share revoke SnP5UJUhP6 --yes`,
+  version: `${c.amber("artyfax version")} \u2014 version history
 
-${c.bright("Usage:")} arty share create <slug>    Create a share link
-        arty share list [slug]      List all shares (or per-document)
-        arty share revoke <hash>    Revoke a share link
+${c.bright("Usage:")} artyfax version list <slug>     Show version history
+        artyfax version restore <slug>  Restore a previous version
 
 ${c.bright("Examples:")}
-  arty share create inbox/my-doc
-  arty share list --json
-  arty share revoke SnP5UJUhP6 --yes`,
-  version: `${c.amber("arty version")} \u2014 version history
+  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>
 
-${c.bright("Usage:")} arty version list <slug>     Show version history
-        arty version restore <slug>  Restore a previous version
+Public and shared views revert to serving the live document.
 
 ${c.bright("Examples:")}
-  arty version list inbox/my-doc
-  arty version restore inbox/my-doc --yes`,
-  note: `${c.amber("arty note")} \u2014 annotations
+  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:")} arty note list <slug>        List annotations
-        arty note add <slug>         Add a note (--text or stdin)
-        arty note search <query>     Search annotations
+${c.bright("Usage:")} artyfax annotation list <slug>     List annotations (--include-recipients, --since <iso>)
+        artyfax annotation search <query>   Search annotations
 
 ${c.bright("Examples:")}
-  arty note list inbox/my-doc
-  arty note add inbox/my-doc --text "Needs review"
-  echo "Reviewed and approved" | arty note add inbox/my-doc
-  arty note search "review"`,
-  doctor: `${c.amber("arty doctor")} \u2014 verify CLI setup
+  artyfax annotation list inbox/my-doc
+  artyfax annotation list inbox/my-doc --include-recipients
+  artyfax annotation list inbox/my-doc --since 2026-05-01T00:00:00Z
+  artyfax annotation search "review"`,
+  doctor: `${c.amber("artyfax doctor")} \u2014 verify CLI setup
 
 Checks API key, endpoint, connectivity, E2EE status, and skill installation.
 
-${c.bright("Usage:")} arty doctor [--json]`,
-  skill: `${c.amber("arty skill")} \u2014 Claude Code skill management
+${c.bright("Usage:")} artyfax doctor [--json]`,
+  skill: `${c.amber("artyfax skill")} \u2014 Claude Code skill management
 
-${c.bright("Usage:")} arty skill install [--project]   Install Artyfax skill
-        arty skill status               Check installation
-        arty skill update               Update to latest version`
+${c.bright("Usage:")} artyfax skill install [--project]   Install Artyfax skill
+        artyfax skill status               Check installation
+        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 = {};
@@ -1144,13 +2454,22 @@ function parseArgs(args) {
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg.startsWith("--")) {
-      const key = arg.slice(2);
-      const next = args[i + 1];
-      if (next && !next.startsWith("-")) {
-        flags[key] = next;
-        i++;
+      const body = arg.slice(2);
+      const eq = body.indexOf("=");
+      const key = eq === -1 ? body : body.slice(0, eq);
+      if (key === "") {
+        continue;
+      }
+      if (eq !== -1) {
+        flags[key] = body.slice(eq + 1);
       } else {
-        flags[key] = true;
+        const next = args[i + 1];
+        if (next !== void 0 && !next.startsWith("-")) {
+          flags[key] = next;
+          i++;
+        } else {
+          flags[key] = true;
+        }
       }
     } else if (arg.startsWith("-")) {
       flags[arg.slice(1)] = true;
@@ -1164,10 +2483,35 @@ function parseArgs(args) {
   }
   return { command, subcommand, positional, flags };
 }
-var SUB_RESOURCES = /* @__PURE__ */ new Set(["share", "cat", "tag", "version", "note", "skill"]);
+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",
+  "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;
@@ -1189,28 +2533,8 @@ async function main() {
     console.log(brandedHelp());
     process.exit(0);
   }
-  const KNOWN_COMMANDS = /* @__PURE__ */ new Set([
-    "save",
-    "read",
-    "list",
-    "get",
-    "search",
-    "delete",
-    "open",
-    "secure",
-    "unsecure",
-    "update",
-    "metadata",
-    "share",
-    "cat",
-    "tag",
-    "version",
-    "note",
-    "skill",
-    "doctor"
-  ]);
-  if (!KNOWN_COMMANDS.has(command)) {
-    error(`Unknown command: ${command}`, `Run \`arty --help\` for available commands`);
+  if (!isKnownCommand(command)) {
+    error(`Unknown command: ${command}`, `Run \`artyfax--help\` for available commands`);
   }
   if (command === "skill") {
     switch (subcommand) {
@@ -1224,7 +2548,7 @@ async function main() {
         await skillUpdate();
         break;
       default:
-        error(`Unknown skill subcommand: ${subcommand || "(none)"}`, "Usage: arty skill <install|status|update>");
+        error(`Unknown skill subcommand: ${subcommand || "(none)"}`, "Usage: artyfax skill <install|status|update>");
     }
     process.exit(0);
   }
@@ -1234,11 +2558,15 @@ async function main() {
     process.exit(0);
   }
   switch (command) {
+    case "init": {
+      await init(config, positional[0]);
+      break;
+    }
     case "save": {
       const fileOrUrl = positional[0];
       const url = flags.url;
       if (!fileOrUrl && !url) {
-        error("Missing file argument", "Usage: arty save <file> [--secure] [--category <name>]");
+        error("Missing file argument", "Usage: artyfax save <file> [--secure] [--category <name>]");
       }
       if (url) {
         await save(config, {
@@ -1263,7 +2591,7 @@ async function main() {
       }
       let content;
       try {
-        content = readFileSync2(resolve2(fileOrUrl), "utf-8");
+        content = readFileSync5(resolve5(fileOrUrl), "utf-8");
       } catch {
         error(`File not found: ${fileOrUrl}`);
       }
@@ -1285,7 +2613,7 @@ async function main() {
     }
     case "read": {
       const slug = positional[0];
-      if (!slug) error("Missing slug argument", "Usage: arty read <slug>");
+      if (!slug) error("Missing slug argument", "Usage: artyfax read <slug>");
       await read(config, slug, !!flags.secure);
       break;
     }
@@ -1306,57 +2634,78 @@ async function main() {
         offset,
         archived: !!flags.archived,
         parentId: flags["parent-id"],
+        tag: flags.tag,
+        workspace: flags.workspace,
         json
       });
       break;
     }
     case "get": {
       const slug = positional[0];
-      if (!slug) error("Missing slug argument", "Usage: arty get <slug>");
+      if (!slug) error("Missing slug argument", "Usage: artyfax get <slug>");
       await get(config, slug);
       break;
     }
     case "search": {
       const query = positional.join(" ");
-      if (!query) error("Missing search query", "Usage: arty search <query>");
-      await search(config, query, json);
+      if (!query) error("Missing search query", "Usage: artyfax search <query>");
+      await search(config, query, json, flags.workspace);
       break;
     }
     case "delete": {
       const slug = positional[0];
-      if (!slug) error("Missing slug argument", "Usage: arty delete <slug>");
+      if (!slug) error("Missing slug argument", "Usage: artyfax delete <slug>");
       await del(config, slug, yes, json);
       break;
     }
     case "open": {
       const slug = positional[0];
-      if (!slug) error("Missing slug argument", "Usage: arty open <slug>");
+      if (!slug) error("Missing slug argument", "Usage: artyfax open <slug>");
       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: arty secure <slug>");
+      if (!slug) error("Missing slug argument", "Usage: artyfax secure <slug>");
       await secure(config, slug);
       break;
     }
     case "unsecure": {
       const slug = positional[0];
-      if (!slug) error("Missing slug argument", "Usage: arty unsecure <slug>");
+      if (!slug) error("Missing slug argument", "Usage: artyfax unsecure <slug>");
       await unsecure(config, slug);
       break;
     }
     case "update": {
       const slug = positional[0];
-      if (!slug) error("Missing slug argument", "Usage: arty update <slug> [file] (reads from stdin if no file)");
+      if (!slug) error("Missing slug argument", "Usage: artyfax update <slug> [file] (reads from stdin if no file)");
       await update(config, slug, positional[1], json);
       break;
     }
     case "metadata": {
       const slug = positional[0];
-      if (!slug) error("Missing slug argument", "Usage: arty metadata <slug> --category <name> --tags <t1,t2>");
+      if (!slug) error("Missing slug argument", "Usage: artyfax metadata <slug> --category <name> --tags <t1,t2>");
       await metadata(config, slug, {
         category: flags.category,
+        slug: flags.slug,
         tags: flags.tags,
         title: flags.title,
         theme: flags.theme,
@@ -1366,11 +2715,25 @@ async function main() {
       });
       break;
     }
+    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 });
+      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 });
+      break;
+    }
     case "share": {
       switch (subcommand) {
         case "create": {
           const slug = positional[0];
-          if (!slug) error("Missing slug argument", "Usage: arty share create <slug>");
+          if (!slug) error("Missing slug argument", "Usage: artyfax share create <slug>");
           await shareCreate(config, slug, json);
           break;
         }
@@ -1379,78 +2742,293 @@ async function main() {
           break;
         case "revoke": {
           const hash = positional[0];
-          if (!hash) error("Missing share hash", "Usage: arty share revoke <hash>");
+          if (!hash) error("Missing share hash", "Usage: artyfax share revoke <hash>");
           await shareRevoke(config, hash, yes, json);
           break;
         }
         default:
-          error(`Unknown share subcommand: ${subcommand || "(none)"}`, "Usage: arty share <create|list|revoke>");
+          error(`Unknown share subcommand: ${subcommand || "(none)"}`, "Usage: artyfax share <create|list|revoke>");
       }
       break;
     }
     case "cat": {
-      if (subcommand !== "list") error(`Unknown cat subcommand: ${subcommand || "(none)"}`, "Usage: arty cat list");
+      if (subcommand !== "list") error(`Unknown cat subcommand: ${subcommand || "(none)"}`, "Usage: artyfax cat list");
       await catList(config, json);
       break;
     }
     case "tag": {
-      if (subcommand !== "list") error(`Unknown tag subcommand: ${subcommand || "(none)"}`, "Usage: arty tag list");
-      await tagList(config, json);
+      switch (subcommand) {
+        case "list":
+          await tagList(config, json);
+          break;
+        case "delete": {
+          const tag = positional[0];
+          if (!tag) error("Missing tag argument", "Usage: artyfax tag delete <tag>");
+          await tagDelete(config, tag, json);
+          break;
+        }
+        default:
+          error(`Unknown tag subcommand: ${subcommand || "(none)"}`, "Usage: artyfax tag list | artyfax tag delete <tag>");
+      }
       break;
     }
     case "version": {
       switch (subcommand) {
         case "list": {
           const slug = positional[0];
-          if (!slug) error("Missing slug argument", "Usage: arty version list <slug>");
+          if (!slug) error("Missing slug argument", "Usage: artyfax version list <slug>");
           await versionList(config, slug, json);
           break;
         }
         case "restore": {
           const slug = positional[0];
-          if (!slug) error("Missing slug argument", "Usage: arty version restore <slug>");
+          if (!slug) error("Missing slug argument", "Usage: artyfax version restore <slug>");
           await versionRestore(config, slug, yes, json);
           break;
         }
         default:
-          error(`Unknown version subcommand: ${subcommand || "(none)"}`, "Usage: arty version <list|restore>");
+          error(`Unknown version subcommand: ${subcommand || "(none)"}`, "Usage: artyfax version <list|restore>");
       }
       break;
     }
-    case "note": {
+    case "annotation": {
       switch (subcommand) {
         case "list": {
           const slug = positional[0];
-          if (!slug) error("Missing slug argument", "Usage: arty note list <slug>");
-          await noteList(config, slug, json);
+          if (!slug) error("Missing slug argument", "Usage: artyfax annotation list <slug> [--include-recipients] [--since <iso>]");
+          await annotationList(config, slug, json, {
+            includeRecipients: Boolean(flags["include-recipients"]),
+            since: typeof flags.since === "string" ? flags.since : void 0
+          });
           break;
         }
-        case "add": {
-          const slug = positional[0];
-          if (!slug) error("Missing slug argument", 'Usage: arty note add <slug> --text "..."');
-          await noteAdd(config, slug, flags.text, json);
+        case "search": {
+          const query = positional.join(" ");
+          if (!query) error("Missing search query", "Usage: artyfax annotation search <query>");
+          await annotationSearch(config, query, json);
+          break;
+        }
+        default:
+          error(`Unknown annotation subcommand: ${subcommand || "(none)"}`, "Usage: artyfax annotation <list|search>");
+      }
+      break;
+    }
+    case "snippets": {
+      const tagsCsv = flags.tags;
+      const parsedTags = tagsCsv ? tagsCsv.split(",").map((t) => t.trim()).filter(Boolean) : void 0;
+      switch (subcommand) {
+        case "list":
+        case void 0: {
+          await snippetList(config, {
+            type: flags.type,
+            starred: !!flags.starred,
+            tag: flags.tag,
+            limit: flags.limit ? Number(flags.limit) : void 0
+          }, json);
           break;
         }
         case "search": {
           const query = positional.join(" ");
-          if (!query) error("Missing search query", "Usage: arty note search <query>");
-          await noteSearch(config, query, json);
+          if (!query) error("Missing search query", "Usage: artyfax snippets search <query>");
+          await snippetSearch(config, query, {
+            type: flags.type,
+            limit: flags.limit ? Number(flags.limit) : void 0
+          }, json);
+          break;
+        }
+        case "show": {
+          const id = positional[0];
+          if (!id) error("Missing snippet id", "Usage: artyfax snippets show <id>");
+          await snippetShow(config, id, json);
+          break;
+        }
+        case "new": {
+          await snippetNew(config, {
+            image: flags.image,
+            type: flags.type ?? void 0,
+            text: flags.text,
+            file: flags.file,
+            language: flags.language,
+            note: flags.note,
+            sourceUrl: flags["source-url"],
+            sourceTitle: flags["source-title"],
+            sourceSiteName: flags["source-site-name"],
+            sourceAuthor: flags["source-author"],
+            alt: flags.alt,
+            tags: parsedTags,
+            starred: !!flags.starred
+          }, json);
+          break;
+        }
+        case "delete": {
+          const id = positional[0];
+          if (!id) error("Missing snippet id", "Usage: artyfax snippets delete <id>");
+          await snippetDelete(config, id, json);
+          break;
+        }
+        case "star": {
+          const id = positional[0];
+          if (!id) error("Missing snippet id", "Usage: artyfax snippets star <id>");
+          await snippetStar(config, id, true, json);
+          break;
+        }
+        case "unstar": {
+          const id = positional[0];
+          if (!id) error("Missing snippet id", "Usage: artyfax snippets unstar <id>");
+          await snippetStar(config, id, false, json);
+          break;
+        }
+        default:
+          error(`Unknown snippets subcommand: ${subcommand}`, "Usage: artyfax snippets <list|search|show|new|delete|star|unstar>");
+      }
+      break;
+    }
+    case "task":
+    case "tasks": {
+      const id = positional[0];
+      if (!id) error("Missing document or work ID", 'Usage: artyfax tasks <id>\n       artyfax task <id> "task text" <active|done|pending>');
+      if (positional.length <= 1) {
+        await taskList(config, id, json);
+      } else {
+        const state = positional[positional.length - 1];
+        const taskText = positional.slice(1, -1).join(" ");
+        if (!taskText) error("Missing task text", 'Usage: artyfax task <id> "task text" <active|done|pending>');
+        await taskUpdate(config, id, taskText, state, json);
+      }
+      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 note subcommand: ${subcommand || "(none)"}`, "Usage: arty note <list|add|search>");
+          error(`Unknown pages subcommand: ${subcommand || "(none)"}`, "Usage: artyfax pages <list|order|move>");
+      }
+      break;
+    }
+    case "work": {
+      switch (subcommand) {
+        case "":
+          await workBoard(config, json);
+          break;
+        case "list":
+          await workList(config, json, flags);
+          break;
+        case "next":
+          await workNext(config, json, flags.agent);
+          break;
+        case "start": {
+          const id = positional[0];
+          if (!id) error("Missing work item ID", "Usage: artyfax work start <id>");
+          await workSetStatus(config, id, "in_progress", json);
+          break;
+        }
+        case "done": {
+          const id = positional[0];
+          if (!id) error("Missing work item ID", "Usage: artyfax work done <id>");
+          await workSetStatus(config, id, "done", json);
+          break;
+        }
+        case "status": {
+          const id = positional[0];
+          const status = positional[1];
+          if (!id || !status) error("Missing arguments", "Usage: artyfax work status <id> <status>");
+          await workSetStatus(config, id, status, json);
+          break;
+        }
+        case "create": {
+          const title = positional.join(" ");
+          if (!title) error("Missing title", 'Usage: artyfax work create "Title"');
+          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|touch>");
+      }
+      break;
+    }
+    case "project": {
+      switch (subcommand) {
+        case "list":
+        case "":
+          await projectList(config, json);
+          break;
+        case "create": {
+          const name = positional.join(" ");
+          if (!name) error("Missing project name", 'Usage: artyfax project create "Name" --prefix XX');
+          const prefix = flags.prefix;
+          if (!prefix) error("Missing --prefix", 'Usage: artyfax project create "Name" --prefix XX');
+          const wsFlag = flags.workspaces ?? flags.workspace;
+          const workspaces = wsFlag ? wsFlag.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+          await projectCreate(config, name, prefix, flags.description, json, workspaces);
+          break;
+        }
+        default:
+          error(`Unknown project subcommand: ${subcommand}`, "Usage: artyfax project <list|create>");
+      }
+      break;
+    }
+    case "workspace": {
+      switch (subcommand) {
+        case "list":
+        case "":
+          await workspaceList(config, json);
+          break;
+        default:
+          error(`Unknown workspace subcommand: ${subcommand}`, "Usage: artyfax workspace <list>");
       }
       break;
     }
     default:
-      error(`Unknown command: ${command}`, `Run \`arty --help\` for available commands`);
+      error(`Unknown command: ${command}`, `Run \`artyfax--help\` for available commands`);
   }
 }
-main().catch((e) => {
-  console.error(c.rose(e.message || String(e)));
-  process.exit(1);
-});
+function isDirectRun() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  const self = fileURLToPath(import.meta.url);
+  try {
+    return realpathSync(entry) === realpathSync(self);
+  } catch {
+    return resolve5(entry) === self;
+  }
+}
+if (isDirectRun()) {
+  main().catch((e) => {
+    console.error(c.rose(e.message || String(e)));
+    process.exit(1);
+  });
+}
 export {
   VERSION,
+  isKnownCommand,
   parseArgs
 };