artyfax 0.2.3 → 0.3.0

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,8 +313,9 @@ ${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 {
     }
@@ -295,6 +327,14 @@ async function resolveSlug(config, slugOrId) {
     } catch {
     }
   }
+  if (/^[A-Z]+-\d+$/.test(slugOrId)) {
+    try {
+      const { id } = await apiFetch(config, `/resolve/${encodeURIComponent(slugOrId)}`);
+      const doc = await apiFetch(config, `/documents/${id}`);
+      return doc;
+    } catch {
+    }
+  }
   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,104 @@ 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`;
+}
+async function resolveDocArg(config, arg) {
+  const looksLikeBareId = !arg.includes("/") && !/^[A-Z]+-\d+$/.test(arg);
+  if (looksLikeBareId) {
+    try {
+      return await apiFetch(config, `/documents/${encodeURIComponent(arg)}`);
+    } catch (e) {
+      if (e.status !== 404) throw e;
+    }
+  }
+  return resolveSlug(config, arg);
+}
+function readImageFile(file) {
+  const path = resolve2(file);
+  let stat;
+  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 resolveDocArg(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 resolveDocArg(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");
@@ -690,8 +871,42 @@ 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
@@ -764,100 +979,337 @@ async function versionRestore(config, slugOrId, yes, json) {
   }
 }
 
-// src/commands/note.ts
-async function noteList(config, slugOrId, 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);
   spin.text = "Loading annotations\u2026";
-  const data = await apiFetch(
-    config,
-    `/annotations/doc/${doc.id}`
-  );
+  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(data.annotations));
+    console.log(JSON.stringify(annotations, null, 2));
     return;
   }
-  if (data.annotations.length === 0) {
+  if (annotations.length === 0) {
     console.log(c.muted("No annotations found."));
     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);
+  console.log(
+    `${c.bright(doc.slug)} \u2014 ${annotations.length} annotation${annotations.length === 1 ? "" : "s"}
+`
+  );
+  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));
-    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" : ""}`);
+    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 noteAdd(config, slugOrId, text, json) {
-  const spin = spinner("Resolving document\u2026");
+async function annotationSearch(config, query, json) {
+  const spin = spinner(`Searching annotations for "${query}"\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();
-  }
-  if (!body) {
-    spin.stop();
-    throw new Error("No text provided. Use --text or pipe to stdin");
-  }
-  spin.text = "Adding annotation\u2026";
-  const result = await apiFetch(
+  const data = await apiFetch(
     config,
-    `/annotations/doc/${doc.id}`,
-    {
-      method: "POST",
-      body: JSON.stringify({ type: "comment", body })
-    }
+    `/annotations/search?q=${encodeURIComponent(query)}`
   );
   spin.stop();
+  const annotations = Array.isArray(data) ? data : data.annotations ?? [];
   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}`);
+    console.log(JSON.stringify(annotations, null, 2));
+    return;
+  }
+  if (annotations.length === 0) {
+    console.log(c.muted(`No annotation results for "${query}".`));
+    return;
   }
+  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(`
+${annotations.length} result${annotations.length === 1 ? "" : "s"}`));
 }
-async function noteSearch(config, query, json) {
-  const spin = spinner(`Searching annotations for "${query}"\u2026`);
+
+// 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,
-    `/annotations/search?q=${encodeURIComponent(query)}`
+    `/snippets${qs.toString() ? `?${qs.toString()}` : ""}`
   );
   spin.stop();
   if (json) {
-    console.log(JSON.stringify(data.annotations));
+    console.log(JSON.stringify(data));
     return;
   }
-  if (data.annotations.length === 0) {
-    console.log(c.muted(`No annotation results for "${query}".`));
+  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 = 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))
-  ]);
-  console.log(table(rows, { header: ["", "Text", c.muted("Date")] }));
+  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(`
-${data.annotations.length} result${data.annotations.length === 1 ? "" : "s"}`));
+${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 +1350,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,27 +1374,576 @@ async function doctor(config, json) {
   }
 }
 
+// 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}`;
+}
+function progress(item) {
+  if (item.task_total === 0) return c.muted("-");
+  return `${item.task_done}/${item.task_total}`;
+}
+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();
+}
+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)}`));
+}
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+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",
+      md_content: `# ${title}
+`,
+      format: "md",
+      html_content: `<h1>${escapeHtml(title)}</h1>`
+    })
+  });
+  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
+
+When a work item only has a short title/description and no task checklist, don't jump straight into implementation.
+
+1. Read the title and description.
+2. Write an \`## Understanding\` section in the Artyfax document with the inferred scope, assumptions, and non-goals.
+3. Add an \`## Tasks\` checklist before editing code.
+4. Ask the requester to approve the understanding and task list before starting implementation. Use a structured question/approval tool when the runtime provides one. If not, say so and wait for typed approval.
+5. After approval, mark the first task \`active\`, then update checkbox progress as the work proceeds.
+
+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.
+
+### 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**: concise, state what it delivers, not how it works - the MCP tool guidance carries the exact length.
+- **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, `arty skill install` will write skill files to ~/.claude/skills/artyfax"));
+  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 `arty doctor` to check basic setup."));
+  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 taskList(config, identifier, json) {
+  const spin = spinner("Loading tasks\u2026");
+  spin.start();
+  const id = await resolveId(config, identifier);
+  const doc = await apiFetch(config, `/documents/${id}/content`);
+  spin.stop();
+  if (doc.format !== "md" || !doc.md_source) {
+    console.error(c.rose("Task listing only supported for markdown documents"));
+    process.exit(1);
+  }
+  const tasks = parseTasks(doc.md_source);
+  if (json) {
+    console.log(JSON.stringify(tasks, null, 2));
+    return;
+  }
+  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 doc = await apiFetch(config, `/documents/${id}/content`);
+  const tasks = parseTasks(doc.md_source);
+  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}`);
+}
+function parseTasks(content) {
+  const lines = content.split("\n");
+  const taskRe = /^[\t ]*[-*+]\s+\[([xX~ ])\]\s*(.*)/;
+  const fenceRe = /^\s*(`{3,}|~{3,})/;
+  let inFence = false;
+  const tasks = [];
+  let count = 0;
+  const charToState = { x: "done", X: "done", "~": "active", " ": "pending" };
+  for (const line of lines) {
+    if (fenceRe.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const m = line.match(taskRe);
+    if (m) {
+      tasks.push({ index: count, state: charToState[m[1]] || "pending", text: m[2].trim() });
+      count++;
+    }
+  }
+  return tasks;
+}
+
 // src/cli.ts
-var VERSION = true ? "0.2.3" : "0.0.0-dev";
+var VERSION = true ? "0.3.0" : "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("Usage:")} artyfax <command> [options]
+        ${c.muted("aliases:")} arty <command> \xB7 ax <command>
 
 ${c.bright("Documents")}
   save <file>            Save a document (markdown or HTML)
@@ -956,20 +1957,46 @@ ${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
 
 ${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 +2019,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 +2038,23 @@ ${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`,
+  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 +2062,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 +2110,95 @@ ${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:")} 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("Usage:")} arty delete <slug> [--yes] [--json]
+${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:")} 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 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:")}
-  arty share create inbox/my-doc
-  arty share list --json
-  arty share revoke SnP5UJUhP6 --yes`,
-  version: `${c.amber("arty version")} \u2014 version history
+  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 version list <slug>     Show version history
-        arty version restore <slug>  Restore a previous version
+${c.bright("Usage:")} artyfax version list <slug>     Show version history
+        artyfax version restore <slug>  Restore a previous version
 
 ${c.bright("Examples:")}
-  arty version list inbox/my-doc
-  arty version restore inbox/my-doc --yes`,
-  note: `${c.amber("arty note")} \u2014 annotations
+  artyfax version list inbox/my-doc
+  artyfax version restore inbox/my-doc --yes`,
+  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`
 };
 function parseArgs(args) {
   const flags = {};
@@ -1144,13 +2208,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,7 +2237,7 @@ 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"]);
 function isSubResource(cmd) {
   return SUB_RESOURCES.has(cmd);
 }
@@ -1190,6 +2263,7 @@ async function main() {
     process.exit(0);
   }
   const KNOWN_COMMANDS = /* @__PURE__ */ new Set([
+    "init",
     "save",
     "read",
     "list",
@@ -1201,16 +2275,24 @@ async function main() {
     "unsecure",
     "update",
     "metadata",
+    "cover",
+    "image",
     "share",
     "cat",
     "tag",
     "version",
-    "note",
+    "annotation",
     "skill",
-    "doctor"
+    "snippets",
+    "doctor",
+    "work",
+    "project",
+    "workspace",
+    "task",
+    "tasks"
   ]);
   if (!KNOWN_COMMANDS.has(command)) {
-    error(`Unknown command: ${command}`, `Run \`arty --help\` for available commands`);
+    error(`Unknown command: ${command}`, `Run \`artyfax--help\` for available commands`);
   }
   if (command === "skill") {
     switch (subcommand) {
@@ -1224,7 +2306,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 +2316,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 +2349,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 +2371,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 +2392,60 @@ 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 "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 +2455,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,77 +2482,254 @@ 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 "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;
         }
         default:
-          error(`Unknown note subcommand: ${subcommand || "(none)"}`, "Usage: arty note <list|add|search>");
+          error(`Unknown work subcommand: ${subcommand}`, "Usage: artyfax work <list|next|start|done|status|create>");
+      }
+      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,
   parseArgs