recursive-board 0.1.2 → 0.3.0

package/dist/wi/wi.js

@@ -2,13 +2,15 @@
 
 // src/cli/wi.ts
 import { parseArgs } from "node:util";
-import { resolve as resolve2 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolve as resolve3 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/cli/vault.ts
-import { readdir, readFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { join, resolve as resolvePath, dirname, basename, sep } from "node:path";
+import { readdir, readFile, mkdir, writeFile, rename } from "node:fs/promises";
+import { existsSync, realpathSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join, resolve as resolvePath, dirname, basename, sep, isAbsolute } from "node:path";
 
 // src/shared/frontmatter.ts
 var KEY_LINE = /^([A-Za-z_][\w.-]*)\s*:(?:[ \t]+(.*))?$/;
@@ -99,6 +101,12 @@ function parseFrontmatter(text) {
     entry: (key) => byKey.get(key)
   };
 }
+function frontmatterBody(text) {
+  const block = splitBlock(text);
+  if (!block) return text;
+  const fenceEnd = text.indexOf("\n", block.contentEnd);
+  return fenceEnd === -1 ? "" : text.slice(fenceEnd + 1);
+}
 function rewrite(text, block, lines, ends) {
   const head = text.slice(0, block.contentStart);
   const tail = text.slice(block.contentEnd);
@@ -109,6 +117,7 @@ function setKey(text, key, value) {
   const block = splitBlock(text);
   if (!block) throw new Error(`cannot set "${key}": the file has no frontmatter`);
   const entry = readEntries(block.lines).find((e) => e.key === key);
+  if (entry?.value === value) return text;
   const line2 = `${key}: ${formatScalar(value)}`;
   const lines = [...block.lines];
   const ends = [...block.ends];
@@ -135,6 +144,47 @@ function removeKey(text, key) {
 function defaultEnd(text) {
   return text.includes("\r\n") ? "\r\n" : "\n";
 }
+function getList(text, key) {
+  const block = splitBlock(text);
+  if (!block) return void 0;
+  const entry = readEntries(block.lines).find((e) => e.key === key);
+  if (!entry) return void 0;
+  const first = KEY_LINE.exec(block.lines[entry.start])?.[2]?.trim() ?? "";
+  let parts;
+  if (first.startsWith("[")) {
+    parts = first.replace(/^\[|\]$/g, "").split(",");
+  } else if (first !== "") {
+    parts = first.split(/[,\s]+/);
+  } else {
+    parts = block.lines.slice(entry.start + 1, entry.end).map((line2) => /^[ \t]*-[ \t]+(.*)$/.exec(line2)?.[1] ?? "");
+  }
+  return parts.map((part) => {
+    const value = parseScalar(part);
+    return typeof value === "string" ? value : value === void 0 ? "" : String(value);
+  }).map((part) => part.trim()).filter((part) => part !== "");
+}
+function setList(text, key, values) {
+  if (values.length === 0) return removeKey(text, key);
+  const block = splitBlock(text);
+  if (!block) throw new Error(`cannot set "${key}": the file has no frontmatter`);
+  const entry = readEntries(block.lines).find((e) => e.key === key);
+  const current = getList(text, key);
+  if (entry && current !== void 0 && current.length === values.length && current.every((value, i) => value === values[i]) && block.lines.slice(entry.start + 1, entry.end).every((line2) => /^[ \t]*-[ \t]/.test(line2))) {
+    return text;
+  }
+  const eol = defaultEnd(text);
+  const replacement = [`${key}:`, ...values.map((value) => `  - ${formatScalar(value)}`)];
+  const lines = [...block.lines];
+  const ends = [...block.ends];
+  if (entry) {
+    lines.splice(entry.start, entry.end - entry.start, ...replacement);
+    ends.splice(entry.start, entry.end - entry.start, ...replacement.map(() => eol));
+  } else {
+    lines.push(...replacement);
+    ends.push(...replacement.map(() => eol));
+  }
+  return rewrite(text, block, lines, ends);
+}
 
 // src/shared/schema.ts
 var STATUSES = ["backlog", "options", "doing", "done"];
@@ -157,11 +207,15 @@ var OPTIONAL_FIELDS = [
   "blocked",
   "depends_on",
   "tags",
-  "archived"
+  "archived",
   // docs/adr/0007-archive-is-a-frontmatter-flag.md: a flag, not a status.
+  "area"
+  // docs/adr/0028-area-work-items.md: an ongoing space that keeps its status.
 ];
-var INHERITED_FIELDS = ["owner", "agent"];
 var WORK_ITEM_TYPE = "work-item";
+function isArea(value) {
+  return value === true;
+}
 var FOLDERS = ["Boards", "Templates"];
 var BOARDS = "Boards";
 function isStatus(value) {
@@ -214,7 +268,10 @@ var WI_CONFIG_FILE = ".wi.json";
 var DEFAULT_VAULT_CONFIG = {
   workItemFolder: "Boards",
   defaultRoot: null,
-  extraSections: []
+  extraSections: [],
+  maxAgents: null,
+  autoPromote: true,
+  areaTags: false
 };
 function parseVaultConfig(text) {
   if (text === null) return { ...DEFAULT_VAULT_CONFIG, extraSections: [] };
@@ -230,6 +287,9 @@ function parseVaultConfig(text) {
   const folderValue = "workItemFolder" in value ? value.workItemFolder : void 0;
   const rootValue = "defaultRoot" in value ? value.defaultRoot : void 0;
   const sectionsValue = "extraSections" in value ? value.extraSections : void 0;
+  const maxAgentsValue = "maxAgents" in value ? value.maxAgents : void 0;
+  const autoPromoteValue = "autoPromote" in value ? value.autoPromote : void 0;
+  const areaTagsValue = "areaTags" in value ? value.areaTags : void 0;
   let workItemFolder = DEFAULT_VAULT_CONFIG.workItemFolder;
   if (folderValue !== void 0) {
     if (typeof folderValue !== "string") {
@@ -252,15 +312,30 @@ function parseVaultConfig(text) {
     if (!Array.isArray(sectionsValue)) {
       throw new Error(`${WI_CONFIG_FILE}: extraSections must be an array of non-empty, single-line headings.`);
     }
-    const headings = sectionsValue;
-    for (const heading of headings) {
+    const headings2 = sectionsValue;
+    for (const heading of headings2) {
       if (typeof heading !== "string" || heading.trim() === "" || /[\r\n]/.test(heading)) {
         throw new Error(`${WI_CONFIG_FILE}: extraSections must be an array of non-empty, single-line headings.`);
       }
       extraSections.push(heading);
     }
   }
-  return { workItemFolder, defaultRoot, extraSections };
+  let maxAgents = null;
+  if (maxAgentsValue !== void 0 && maxAgentsValue !== null) {
+    if (typeof maxAgentsValue !== "number" || !Number.isSafeInteger(maxAgentsValue) || maxAgentsValue < 0) {
+      throw new Error(`${WI_CONFIG_FILE}: maxAgents must be a non-negative whole number or null.`);
+    }
+    maxAgents = maxAgentsValue;
+  }
+  if (autoPromoteValue !== void 0 && typeof autoPromoteValue !== "boolean") {
+    throw new Error(`${WI_CONFIG_FILE}: autoPromote must be true or false.`);
+  }
+  const autoPromote = autoPromoteValue ?? DEFAULT_VAULT_CONFIG.autoPromote;
+  if (areaTagsValue !== void 0 && typeof areaTagsValue !== "boolean") {
+    throw new Error(`${WI_CONFIG_FILE}: areaTags must be true or false.`);
+  }
+  const areaTags = areaTagsValue ?? DEFAULT_VAULT_CONFIG.areaTags;
+  return { workItemFolder, defaultRoot, extraSections, maxAgents, autoPromote, areaTags };
 }
 
 // src/shared/archive.ts
@@ -291,7 +366,83 @@ function activeDescendant(item, childrenOf, statusOf) {
 }
 
 // src/cli/vault.ts
+function maxAgentsForRun(vault, env = process.env) {
+  const override = env["WI_MAX_AGENTS"];
+  if (override === void 0) return vault.config.maxAgents;
+  if (override.trim() === "") return null;
+  if (!/^\d+$/.test(override) || !Number.isSafeInteger(Number(override))) {
+    throw new Error("WI_MAX_AGENTS must be a non-negative whole number.");
+  }
+  return Number(override);
+}
 var MARKDOWN = /\.md$/i;
+function wiConfigDir(env = process.env) {
+  const xdg = env["XDG_CONFIG_HOME"];
+  return xdg && isAbsolute(xdg) ? join(xdg, "wi") : join(homedir(), ".config", "wi");
+}
+function gitCommonDir(start) {
+  try {
+    const output = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+      cwd: start,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    return realpathSync(resolvePath(start, output));
+  } catch {
+    return null;
+  }
+}
+async function readJsonObject(path, description) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error(`${description} must contain valid JSON.`);
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${description} must contain a JSON object.`);
+  }
+  return value;
+}
+async function getRepoPointer(start, env = process.env) {
+  const commonDir = gitCommonDir(start);
+  if (!commonDir) return null;
+  const map = await readJsonObject(join(wiConfigDir(env), "repos.json"), "wi repos.json");
+  const value = map?.[commonDir];
+  if (value === void 0) return null;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`wi repos.json: entry for ${commonDir} must contain vault and board strings.`);
+  }
+  const entry = value;
+  if (typeof entry["vault"] !== "string" || typeof entry["board"] !== "string") {
+    throw new Error(`wi repos.json: entry for ${commonDir} must contain vault and board strings.`);
+  }
+  return { vault: entry["vault"], board: entry["board"] };
+}
+async function setRepoPointer(start, pointer, env = process.env) {
+  const commonDir = gitCommonDir(start);
+  if (!commonDir) throw new Error("wi here must run inside a Git repository.");
+  const dir = wiConfigDir(env);
+  const path = join(dir, "repos.json");
+  const map = await readJsonObject(path, "wi repos.json") ?? {};
+  map[commonDir] = pointer;
+  await mkdir(dir, { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(map, null, 2)}
+`, "utf8");
+  await rename(temporary, path);
+}
+async function getDefaultVault(env = process.env) {
+  const config = await readJsonObject(join(wiConfigDir(env), "config.json"), "wi config.json");
+  return typeof config?.["defaultVault"] === "string" ? config["defaultVault"] : null;
+}
 var IGNORED_HIDDEN = /* @__PURE__ */ new Set([".DS_Store", ".localized", ".gitkeep"]);
 function isUnaccounted(name) {
   if (!name.startsWith(".")) return false;
@@ -355,6 +506,7 @@ function toWorkItem(root, relPath, text) {
     parent: parseWikilink(parentRaw),
     parentRaw: typeof parentRaw === "string" ? parentRaw : void 0,
     board: frontmatter.get("board") === true,
+    area: isArea(frontmatter.get("area")),
     archived: frontmatter.get("archived") === true,
     frontmatter,
     text
@@ -432,7 +584,7 @@ async function loadVault(root) {
   }
   for (const siblings of children.values()) siblings.sort(compareSiblings);
   const resolveLink = (target) => target === null ? void 0 : byStem.get(linkKey(target));
-  const resolve3 = (ref) => {
+  const resolve4 = (ref) => {
     const trimmed = ref.trim();
     const byIdHit = byId.get(trimmed);
     if (byIdHit) return byIdHit;
@@ -458,7 +610,7 @@ async function loadVault(root) {
     takenIds: new Set(byId.keys()),
     takenStems: new Set(byStem.keys()),
     resolveLink,
-    resolve: resolve3,
+    resolve: resolve4,
     childrenOf: (item) => children.get(item.stem.toLowerCase()) ?? [],
     isArchived: (item) => archiveOwner(item, (current) => resolveLink(current.parent) ?? null, (current) => current.archived) !== null
   };
@@ -468,18 +620,21 @@ function isMissingFile(error) {
 }
 
 // src/cli/commands/new.ts
-import { existsSync as existsSync2 } from "node:fs";
-import { join as join3 } from "node:path";
+import { existsSync as existsSync3 } from "node:fs";
+import { join as join4 } from "node:path";
 
 // src/cli/write.ts
-import { writeFile, rename } from "node:fs/promises";
+import { writeFile as writeFile2, rename as rename2, readFile as readFile2, mkdir as mkdir2, rm, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
 import { dirname as dirname2, join as join2 } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 
 // src/shared/edits.ts
 function applyEdits(text, edits) {
   let out = text;
   for (const edit of edits) {
-    out = edit.op === "set" ? setKey(out, edit.key, edit.value) : removeKey(out, edit.key);
+    out = edit.op === "set" ? setKey(out, edit.key, edit.value) : edit.op === "list" ? setList(out, edit.key, edit.values) : removeKey(out, edit.key);
   }
   return out;
 }
@@ -490,14 +645,46 @@ function withStamp(edits, stamp = today()) {
 
 // src/cli/write.ts
 async function writeAtomic(path, text) {
-  const temp = join2(dirname2(path), `.wi-${process.pid}-${Date.now()}.tmp`);
-  await writeFile(temp, text, "utf8");
-  await rename(temp, path);
-}
-async function editItem(item, edits) {
-  const text = applyEdits(item.text, withStamp(edits));
-  if (text !== item.text) await writeAtomic(item.path, text);
-  return text;
+  const temp = join2(dirname2(path), `.wi-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.tmp`);
+  await writeFile2(temp, text, "utf8");
+  await rename2(temp, path);
+}
+var LOCK_WAIT_MS = 5e3;
+var LOCK_STALE_MS = 3e4;
+async function withFileLock(path, fn) {
+  const lock = join2(tmpdir(), `wi-lock-${createHash("sha1").update(path).digest("hex")}`);
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (; ; ) {
+    try {
+      await mkdir2(lock);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const age = await stat(lock).then((s) => Date.now() - s.mtimeMs, () => 0);
+      if (age > LOCK_STALE_MS) {
+        await rm(lock, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() > deadline) {
+        throw new Error(`another wi process is writing ${path}. Retry. If no wi runs, remove ${lock}.`);
+      }
+      await sleep(20);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    await rm(lock, { recursive: true, force: true });
+  }
+}
+async function editItem(item, edits, editBody = (text) => text) {
+  return withFileLock(item.path, async () => {
+    const current = await readFile2(item.path, "utf8");
+    if (editBody(applyEdits(current, edits)) === current) return current;
+    const text = editBody(applyEdits(current, withStamp(edits)));
+    await writeAtomic(item.path, text);
+    return text;
+  });
 }
 
 // src/shared/templates.ts
@@ -511,6 +698,24 @@ var TEMPLATES = [
       { heading: "Acceptance Criteria", starter: "- " },
       { heading: "Notes" }
     ]
+  },
+  {
+    name: "first-board-card",
+    description: "A short guide to adding and moving cards on your first board.",
+    sections: [
+      { heading: "Getting started", starter: "Add cards from a board column. Use Promote at the top of this card to give it its own board. To move this card, open its card menu and choose \u201CMove to\u2026\u201D." },
+      { heading: "Notes" }
+    ]
+  },
+  {
+    name: "area",
+    description: "An ongoing area of work.",
+    area: true,
+    sections: [
+      { heading: "Objective" },
+      { heading: "Context" },
+      { heading: "Notes" }
+    ]
   }
 ];
 var DEFAULT_TEMPLATE = "work-item";
@@ -525,15 +730,45 @@ function requireTemplate(name = DEFAULT_TEMPLATE) {
   if (template) return template;
   throw new Error(`no template called "${name}". There is: ${templateNames().join(", ")}.`);
 }
-function renderBody(template, extraSections = []) {
-  const parts = [];
+var BRIEF_HEADINGS = { objective: "Objective", context: "Context", criteria: "Acceptance Criteria" };
+function briefGaps(template, brief = {}) {
+  const headings2 = new Set(template.sections.map((s) => s.heading));
+  const gaps = [];
+  if (headings2.has(BRIEF_HEADINGS.objective) && !brief.objective?.trim()) gaps.push(BRIEF_HEADINGS.objective);
+  if (headings2.has(BRIEF_HEADINGS.criteria) && !brief.criteria?.some((c) => c.trim() !== "")) {
+    gaps.push(BRIEF_HEADINGS.criteria);
+  }
+  return gaps;
+}
+function briefContent(brief) {
+  const content = /* @__PURE__ */ new Map();
+  const objective = brief.objective?.trim();
+  if (objective) content.set(BRIEF_HEADINGS.objective, objective);
+  const context = (brief.context ?? []).map((c) => c.trim()).filter((c) => c !== "");
+  if (context.length > 0) content.set(BRIEF_HEADINGS.context, context.join("\n\n"));
+  const criteria = (brief.criteria ?? []).map((c) => c.trim()).filter((c) => c !== "");
+  for (const line2 of criteria) {
+    if (/[\r\n]/.test(line2)) throw new Error("each acceptance criterion must be one line.");
+  }
+  if (criteria.length > 0) content.set(BRIEF_HEADINGS.criteria, criteria.map((c) => `- ${c}`).join("\n"));
+  return content;
+}
+function renderBody(template, extraSections = [], brief = {}) {
+  const content = briefContent(brief);
   const sections = [
     ...template.sections,
     ...extraSections.map((heading) => ({ heading, starter: "- " }))
   ];
+  for (const heading of content.keys()) {
+    if (!sections.some((s) => s.heading === heading)) {
+      throw new Error(`template "${template.name}" has no ${heading} section.`);
+    }
+  }
+  const parts = [];
   for (const section of sections) {
     parts.push(`## ${section.heading}`, "");
-    if (section.starter !== void 0) parts.push(section.starter, "");
+    const filled = content.get(section.heading) ?? section.starter;
+    if (filled !== void 0) parts.push(filled, "");
   }
   return parts.join("\n");
 }
@@ -542,14 +777,17 @@ function renderVaultTemplate(template, defaultRoot = null, extraSections = []) {
     type: formatScalar(WORK_ITEM_TYPE),
     id: "wi-XXXX",
     title: "",
-    status: "backlog",
     parent: defaultRoot === null ? "" : formatScalar(formatWikilink(defaultRoot)),
     created: "",
     updated: ""
   };
-  const lines = CORE_FIELDS.filter((field) => field in placeholders).map(
+  placeholders["status"] = "backlog";
+  if (template.area) placeholders["area"] = "true";
+  const fields = CORE_FIELDS;
+  const lines = fields.filter((field) => field in placeholders).map(
     (field) => `${field}: ${placeholders[field]}`.trimEnd()
   );
+  if (template.area) lines.splice(4, 0, "area: true");
   return `---
 ${lines.join("\n")}
 ---
@@ -558,64 +796,38 @@ ${renderBody(template, extraSections)}`;
 }
 
 // src/shared/work-item.ts
+function inheritedChildFields(parent, status, overrides = {}) {
+  return {
+    owner: overrides.owner ?? parent.owner,
+    agent: overrides.agent ?? (status === "doing" ? parent.agent : void 0)
+  };
+}
 function renderWorkItem(item, extraSections = []) {
+  const template = requireTemplate(item.template);
+  if (Boolean(template.area) !== (item.area === true)) {
+    throw new Error(`template "${template.name}" does not match the work item kind`);
+  }
   const fields = [
     ["type", WORK_ITEM_TYPE],
     ["id", item.id],
-    ["title", item.title],
-    ["status", item.status],
-    ["parent", formatWikilink(item.parentStem)]
+    ["title", item.title]
   ];
+  fields.push(["status", item.status]);
+  if (item.area) fields.push(["area", true]);
+  fields.push(["parent", formatWikilink(item.parentStem)]);
   if (item.owner !== void 0 && item.owner !== "") fields.push(["owner", item.owner]);
   if (item.agent !== void 0 && item.agent !== "") fields.push(["agent", item.agent]);
   if (item.priority !== void 0) fields.push(["priority", item.priority]);
   fields.push(["created", item.created], ["updated", item.updated]);
-  const frontmatter = fields.map(([key, value]) => `${key}: ${formatScalar(value)}`).join("\n");
+  const lines = fields.map(([key, value]) => `${key}: ${formatScalar(value)}`);
+  if (item.tags !== void 0 && item.tags.length > 0) {
+    lines.push("tags:", ...item.tags.map((tag) => `  - ${formatScalar(tag)}`));
+  }
   return `---
-${frontmatter}
+${lines.join("\n")}
 ---
 
-${renderBody(requireTemplate(item.template), extraSections)}`;
-}
-
-// src/cli/commands/new.ts
-async function createItem(vault, options) {
-  const title = options.title.trim();
-  if (title === "") throw new Error("a work item needs a title");
-  const parentRef = options.parent ?? vault.config.defaultRoot ?? "";
-  if (parentRef.trim() === "") {
-    throw new Error("a work item needs a --parent. Only the root has none.");
-  }
-  requireTemplate(options.template);
-  const status = options.status ?? "backlog";
-  if (!isStatus(status)) {
-    throw new Error(`"${status}" is not a status. Use backlog, options, doing or done.`);
-  }
-  const parent = vault.resolve(parentRef);
-  const id = newId(vault.takenIds);
-  const stem = fileNameFor(title, id, vault.takenStems);
-  const relPath = `${vault.config.workItemFolder}/${stem}.md`;
-  const path = join3(vault.root, ...vault.config.workItemFolder.split("/"), `${stem}.md`);
-  if (existsSync2(path)) {
-    throw new Error(`${relPath} already exists. Refusing to overwrite it.`);
-  }
-  const stamp = today();
-  const fields = {
-    id,
-    title,
-    status,
-    parentStem: parent.stem,
-    created: stamp,
-    updated: stamp,
-    template: options.template
-  };
-  for (const field of INHERITED_FIELDS) {
-    const value = options[field] ?? parent.frontmatter.get(field);
-    if (value !== void 0 && value !== "") fields[field] = String(value);
-  }
-  if (options.priority !== void 0) fields.priority = options.priority;
-  await writeAtomic(path, renderWorkItem(fields, vault.config.extraSections));
-  return { id, stem, relPath, path, parentStem: parent.stem };
+${renderBody(template, extraSections, item.brief)}`;
 }
 
 // src/shared/transitions.ts
@@ -629,6 +841,29 @@ function statusEdits(from, to, hasPrevStatus) {
   }
   return edits;
 }
+function claimEdits(from, currentAgent, agent, hasPrevStatus, hasOtherDoingChild) {
+  if (from === "done") throw new Error("a done card cannot be claimed.");
+  if (currentAgent && currentAgent !== agent) {
+    throw new Error(`already claimed by ${currentAgent}. Release that claim first.`);
+  }
+  if (currentAgent === agent && from === "doing") return null;
+  if (hasOtherDoingChild) {
+    throw new Error("this board has a child in doing that another agent or a person works. Release or finish that child first.");
+  }
+  const status = statusEdits(from, "doing", hasPrevStatus);
+  if (currentAgent === agent) return status;
+  return [...status ?? [], { op: "set", key: "agent", value: agent }];
+}
+function releaseEdits(from, hasPrevStatus) {
+  return [...statusEdits(from, "options", hasPrevStatus) ?? [], { op: "remove", key: "agent" }];
+}
+function boardEdits(promoted) {
+  return promoted ? [{ op: "set", key: "board", value: true }] : [{ op: "remove", key: "board" }];
+}
+function firstChildPromotion(parent, autoPromote) {
+  if (!autoPromote || parent.isRoot || parent.area || parent.hasBoardKey || parent.childCount > 0) return null;
+  return boardEdits(true);
+}
 function moveEdits(currentParentStem, targetStem) {
   if (currentParentStem !== null && currentParentStem.toLowerCase() === targetStem.toLowerCase()) {
     return null;
@@ -650,6 +885,219 @@ function moveRefusal(check) {
   return null;
 }
 
+// src/shared/labels.ts
+var LABEL_COLOURS = [
+  "red",
+  "orange",
+  "yellow",
+  "green",
+  "cyan",
+  "blue",
+  "purple",
+  "pink"
+];
+function labelColour(label2) {
+  const key = label2.trim().replace(/^#/, "").toLowerCase();
+  let hash = 0;
+  for (let i = 0; i < key.length; i++) {
+    hash = hash * 31 + key.charCodeAt(i) >>> 0;
+  }
+  return LABEL_COLOURS[hash % LABEL_COLOURS.length];
+}
+
+// src/shared/area-tags.ts
+var AREA_TAG_PREFIX = "area/";
+function isAreaTag(tag) {
+  return tag.replace(/^#/, "").toLowerCase().startsWith(AREA_TAG_PREFIX);
+}
+function areaSlug(title) {
+  const slug = title.toLowerCase().normalize("NFKD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9_]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug === "" ? "untitled" : slug;
+}
+function areaTagFor(chain) {
+  const areas = chain.filter((node2) => node2.area).reverse();
+  if (areas.length === 0) return null;
+  return `${AREA_TAG_PREFIX}${areas.map((node2) => areaSlug(node2.title)).join("/")}`;
+}
+function withAreaTag(tags, tag) {
+  const kept = tags.filter((existing) => !isAreaTag(existing));
+  return tag === null ? kept : [...kept, tag];
+}
+function hasAreaTag(tags, tag) {
+  const current = tags.filter(isAreaTag).map((t) => t.replace(/^#/, ""));
+  return tag === null ? current.length === 0 : current.length === 1 && current[0] === tag;
+}
+var RGB = {
+  red: 15282503,
+  orange: 15496448,
+  yellow: 14724096,
+  green: 571726,
+  cyan: 49084,
+  blue: 552413,
+  purple: 7885550,
+  pink: 13973892
+};
+function shade(rgb, amount) {
+  const target = amount >= 0 ? 255 : 0;
+  const mix = (channel) => Math.round(channel + (target - channel) * Math.abs(amount));
+  return mix(rgb >> 16 & 255) << 16 | mix(rgb >> 8 & 255) << 8 | mix(rgb & 255);
+}
+function areaColourGroups(tags) {
+  const unique = [...new Set([...tags].map((t) => t.replace(/^#/, "")).filter(isAreaTag))];
+  const depth = (tag) => tag.split("/").length - 1;
+  unique.sort((a, b) => depth(b) - depth(a) || a.localeCompare(b));
+  return unique.flatMap((tag) => {
+    const top = tag.split("/").slice(0, 2).join("/");
+    const base = shade(RGB[labelColour(top)], Math.min(0.6, (depth(tag) - 1) * 0.3));
+    return [
+      { query: `tag:#${tag} ([board:true] OR [area:true])`, color: { a: 1, rgb: shade(base, -0.3) } },
+      { query: `tag:#${tag}`, color: { a: 1, rgb: base } }
+    ];
+  });
+}
+function isAreaColourGroup(group) {
+  if (typeof group !== "object" || group === null || !("query" in group)) return false;
+  return typeof group.query === "string" && group.query.startsWith(`tag:#${AREA_TAG_PREFIX}`);
+}
+
+// src/cli/commands/retag.ts
+import { readFile as readFile3 } from "node:fs/promises";
+import { existsSync as existsSync2 } from "node:fs";
+import { join as join3 } from "node:path";
+function node(item) {
+  return { title: item.title ?? item.stem, area: item.area };
+}
+function chainOf(vault, item) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (let current = item; current; current = vault.resolveLink(current.parent)) {
+    if (seen.has(current.relPath)) break;
+    seen.add(current.relPath);
+    chain.push(node(current));
+  }
+  return chain;
+}
+function expectedAreaTag(vault, item) {
+  return areaTagFor(chainOf(vault, item));
+}
+function tagsOf(item) {
+  return getList(item.text, "tags") ?? [];
+}
+function staleAreaTags(vault) {
+  return vault.items.flatMap((item) => {
+    if (!item.frontmatter.has("parent")) return [];
+    const tags = tagsOf(item);
+    const tag = expectedAreaTag(vault, item);
+    return hasAreaTag(tags, tag) ? [] : [{ item, from: tags, to: withAreaTag(tags, tag) }];
+  });
+}
+function requireAreaTags(vault) {
+  if (!vault.config.areaTags) {
+    throw new Error('area tags are off in this vault. Set "areaTags": true in .wi.json first.');
+  }
+}
+async function retag(vault, dryRun) {
+  requireAreaTags(vault);
+  const stale = staleAreaTags(vault);
+  if (!dryRun) {
+    for (const entry of stale) await editItem(entry.item, [{ op: "list", key: "tags", values: entry.to }]);
+  }
+  return stale;
+}
+async function writeGraphColours(vault, configDir = ".obsidian") {
+  requireAreaTags(vault);
+  const path = join3(vault.root, configDir, "graph.json");
+  if (!existsSync2(join3(vault.root, configDir))) {
+    throw new Error(`${configDir}/ is missing, so this vault has never been opened in Obsidian. Open it once, then retry.`);
+  }
+  let config = {};
+  if (existsSync2(path)) {
+    const parsed = JSON.parse(await readFile3(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`${configDir}/graph.json is not a JSON object. Nothing was written.`);
+    }
+    config = { ...parsed };
+  }
+  const tags = vault.items.flatMap((item) => {
+    const tag = expectedAreaTag(vault, item);
+    return tag === null ? [] : [tag];
+  });
+  const groups = areaColourGroups(tags);
+  const existing = Array.isArray(config["colorGroups"]) ? config["colorGroups"] : [];
+  const kept = existing.filter((group) => !isAreaColourGroup(group));
+  config["colorGroups"] = [...groups, ...kept];
+  await writeAtomic(path, `${JSON.stringify(config, null, 2)}
+`);
+  return { path: `${configDir}/graph.json`, groups: groups.length, kept: kept.length };
+}
+
+// src/cli/commands/new.ts
+async function createItem(vault, options) {
+  const title = options.title.trim();
+  if (title === "") throw new Error("a work item needs a title");
+  const parentRef = options.parent ?? vault.config.defaultRoot ?? "";
+  if (parentRef.trim() === "") {
+    throw new Error("a work item needs a --parent. Only the root has none.");
+  }
+  const template = requireTemplate(options.template);
+  const status = options.status ?? "backlog";
+  if (!isStatus(status)) {
+    throw new Error(`"${status}" is not a status. Use backlog, options, doing or done.`);
+  }
+  const parent = vault.resolve(parentRef);
+  const gaps = briefGaps(template, options.brief);
+  if (options.strict && gaps.length > 0) {
+    throw new Error(`the card has no ${gaps.join(" or ")}. Pass --objective and --criteria, or drop --strict.`);
+  }
+  renderBody(template, vault.config.extraSections, options.brief);
+  const id = newId(vault.takenIds);
+  const stem = fileNameFor(title, id, vault.takenStems);
+  const relPath = `${vault.config.workItemFolder}/${stem}.md`;
+  const path = join4(vault.root, ...vault.config.workItemFolder.split("/"), `${stem}.md`);
+  if (existsSync3(path)) {
+    throw new Error(`${relPath} already exists. Refusing to overwrite it.`);
+  }
+  const stamp = today();
+  const common = {
+    id,
+    title,
+    parentStem: parent.stem,
+    created: stamp,
+    updated: stamp,
+    template: options.template,
+    brief: options.brief
+  };
+  const inherited = inheritedChildFields({
+    owner: textField(parent.frontmatter.get("owner")),
+    agent: textField(parent.frontmatter.get("agent"))
+  }, status, options);
+  const fields = template.area ? { ...common, ...inherited, area: true, status } : { ...common, ...inherited, status };
+  if (options.priority !== void 0) fields.priority = options.priority;
+  const areaTag = vault.config.areaTags ? areaTagFor([{ title, area: template.area === true }, ...chainOf(vault, parent)]) : null;
+  if (areaTag !== null) fields.tags = [areaTag];
+  await writeAtomic(path, renderWorkItem(fields, vault.config.extraSections));
+  const promotion = firstChildPromotion({
+    isRoot: parent.parent === null && !parent.frontmatter.has("parent"),
+    area: parent.area,
+    hasBoardKey: parent.frontmatter.has("board"),
+    childCount: vault.childrenOf(parent).length
+  }, vault.config.autoPromote);
+  if (promotion) await editItem(parent, promotion);
+  return {
+    id,
+    stem,
+    relPath,
+    path,
+    parentStem: parent.stem,
+    promotedParent: promotion !== null,
+    gaps,
+    renamed: stem !== fileNameStem(title)
+  };
+}
+function textField(value) {
+  return value === void 0 || value === null ? void 0 : String(value);
+}
+
 // src/cli/commands/status.ts
 async function setStatus(vault, ref, status) {
   if (!isStatus(status)) {
@@ -664,11 +1112,119 @@ async function setStatus(vault, ref, status) {
   const from = item.status;
   const edits = statusEdits(from, status, item.frontmatter.has("prev_status"));
   if (edits === null) {
-    return { item, from, to: status, recorded: void 0, changed: false };
+    return { item, from, to: status, recorded: void 0, changed: false, parentReady: void 0 };
   }
   const recorded = status === "done" ? from : void 0;
   await editItem(item, edits);
-  return { item, from, to: status, recorded, changed: true };
+  return { item, from, to: status, recorded, changed: true, parentReady: status === "done" ? readyParent(vault, item) : void 0 };
+}
+function readyParent(vault, item) {
+  const parent = vault.resolveLink(item.parent);
+  if (parent === void 0 || !parent.frontmatter.has("parent") || parent.area || parent.status === "done") return void 0;
+  const open = vault.childrenOf(parent).filter((child) => !child.archived && child !== item && child.status !== "done");
+  return open.length === 0 ? parent : void 0;
+}
+
+// src/shared/notes.ts
+function headings(text) {
+  const body = frontmatterBody(text);
+  const offset = text.length - body.length;
+  const found = [];
+  let fence;
+  for (const match of body.matchAll(/([^\r\n]*)(\r?\n|$)/g)) {
+    if (match[0] === "") continue;
+    const line2 = match[1];
+    const marker = /^[ \t]*(`{3,}|~{3,})/.exec(line2)?.[1];
+    if (marker) {
+      if (fence === void 0) fence = { marker: marker[0], length: marker.length };
+      else if (marker[0] === fence.marker && marker.length >= fence.length) fence = void 0;
+      continue;
+    }
+    if (fence !== void 0) continue;
+    const heading = /^(#{1,6})[ \t]+(.+?)[ \t]*$/.exec(line2);
+    if (heading) found.push({
+      level: heading[1].length,
+      title: heading[2].trim().toLowerCase(),
+      start: offset + match.index,
+      end: offset + match.index + line2.length
+    });
+  }
+  return found;
+}
+function appendNote(text, line2) {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const all = headings(text);
+  const noteIndex = all.findIndex((heading2) => heading2.level === 2 && heading2.title === "notes");
+  const heading = all[noteIndex];
+  if (!heading) {
+    const gap = text.endsWith(eol + eol) ? "" : text.endsWith(eol) ? eol : eol + eol;
+    return `${text}${gap}## Notes${eol}${eol}${line2}${eol}`;
+  }
+  const start = heading.end;
+  const next = all.slice(noteIndex + 1).find((entry) => entry.level <= 2);
+  const end = next?.start ?? text.length;
+  const content = text.slice(start, end);
+  if (content === "") return `${text.slice(0, start)}${eol}${eol}${line2}${eol}${text.slice(end)}`;
+  const trailing = /(?:\r?\n[ \t]*)*$/.exec(content)?.[0] ?? "";
+  const prose = content.slice(0, content.length - trailing.length);
+  const insertion = prose === "" ? `${eol}${eol}${line2}${eol}${next ? eol : ""}` : `${prose}${eol}${line2}${trailing || eol}`;
+  return text.slice(0, start) + insertion + text.slice(end);
+}
+function noteLine(text, agent, now = /* @__PURE__ */ new Date()) {
+  const body = text.trim();
+  if (body === "") throw new Error("a note needs text.");
+  if (/[\r\n]/.test(body)) throw new Error("a note must be one line.");
+  const pad = (n) => String(n).padStart(2, "0");
+  const who = agent?.trim() ? `, ${agent.trim()}` : "";
+  return `- ${today(now)} ${pad(now.getHours())}:${pad(now.getMinutes())}${who}: ${body}`;
+}
+
+// src/cli/commands/claim-release.ts
+async function claimItem(vault, ref, agent) {
+  const item = vault.resolve(ref);
+  if (item.area) throw new Error(`${item.relPath} is an area, and an area cannot be claimed.`);
+  if (item.parent === null) throw new Error(`${item.relPath} is a root, and a root cannot be claimed.`);
+  const current = item.frontmatter.get("agent");
+  const currentAgent = typeof current === "string" && current.trim() !== "" ? current : void 0;
+  const holding = currentAgent === agent && item.status === "doing";
+  if (!holding && item.frontmatter.get("blocked") === true) {
+    throw new Error(`${item.relPath} is blocked. Clear its blocked flag when the block is gone, or claim another card.`);
+  }
+  const edits = claimEdits(
+    item.status,
+    currentAgent,
+    agent,
+    item.frontmatter.has("prev_status"),
+    item.board && vault.childrenOf(item).some((child) => child.status === "doing" && child.frontmatter.get("agent") !== agent)
+  );
+  if (edits === null) return { item, agent, from: item.status, to: "doing", changed: false };
+  await editItem(item, edits);
+  return { item, agent, from: item.status, to: "doing", changed: true };
+}
+async function releaseItem(vault, ref, reason, where) {
+  const item = vault.resolve(ref);
+  if (item.parent === null) throw new Error(`${item.relPath} is a root, and a root cannot be released.`);
+  const current = item.frontmatter.get("agent");
+  if (typeof current !== "string" || current.trim() === "") {
+    throw new Error(`${item.relPath} has no agent to release.`);
+  }
+  const note = `- ${today()} Released from ${current}: ${reason.replace(/\.$/, "")}.` + (where === void 0 ? "" : ` Work: ${where.replace(/\.$/, "")}.`);
+  await editItem(
+    item,
+    releaseEdits(item.status, item.frontmatter.has("prev_status")),
+    (text) => appendNote(text, note)
+  );
+  return { item, agent: current, from: item.status, to: "options", reason, where, changed: true };
+}
+
+// src/cli/commands/note.ts
+async function addNote(vault, ref, text, agent, now = /* @__PURE__ */ new Date()) {
+  const item = vault.resolve(ref);
+  const held = item.frontmatter.get("agent");
+  const who = agent ?? (typeof held === "string" && held.trim() !== "" ? held : void 0);
+  const line2 = noteLine(text, who, now);
+  await editItem(item, [], (body) => appendNote(body, line2));
+  return { item, line: line2 };
 }
 
 // src/cli/commands/children.ts
@@ -679,6 +1235,7 @@ function listChildren(vault, ref, options = {}) {
   }
   const parent = vault.resolve(ref);
   const rows = [];
+  const areas = [];
   const seen = /* @__PURE__ */ new Set([parent.relPath]);
   let cycle = false;
   const walk = (item, depth) => {
@@ -690,7 +1247,9 @@ function listChildren(vault, ref, options = {}) {
       seen.add(child.relPath);
       const effectiveArchived = vault.isArchived(child);
       if (!effectiveArchived || archived) {
-        rows.push({ item: child, childCount: vault.childrenOf(child).filter((kid) => !vault.isArchived(kid) || archived).length, depth, archived: effectiveArchived });
+        const row = { item: child, childCount: vault.childrenOf(child).filter((kid) => !vault.isArchived(kid) || archived).length, depth, archived: effectiveArchived };
+        if (child.area) areas.push(row);
+        else rows.push(row);
       }
       if (recursive) walk(child, depth + 1);
     }
@@ -701,7 +1260,7 @@ function listChildren(vault, ref, options = {}) {
   for (const value of STATUSES) {
     byStatus.set(value, filtered.filter((r) => r.item.status === value));
   }
-  return { parent, children: filtered, byStatus, cycle };
+  return { parent, children: filtered, areas: status === void 0 ? areas : [], byStatus, cycle };
 }
 
 // src/cli/commands/validate.ts
@@ -720,6 +1279,12 @@ async function validate(vault) {
   checkDefaultRoot(vault, report);
   checkRoots(vault, report);
   checkCycles(vault, report);
+  if (vault.config.areaTags) {
+    for (const { item, to } of staleAreaTags(vault)) {
+      const tag = to.find(isAreaTag);
+      report("area-tag-stale", "warning", item.relPath, item.id, tag ? `should carry the area tag ${tag}. Run wi retag.` : "carries an area tag but sits in no area. Run wi retag.");
+    }
+  }
   problems.sort((a, b) => a.relPath.localeCompare(b.relPath) || a.rule.localeCompare(b.rule));
   const errorCount = problems.filter((p) => p.severity === "error").length;
   return {
@@ -802,6 +1367,10 @@ function checkItem(item, vault, report) {
   if (item.title === void 0) say("title-missing", "error", "has no title.");
   const rawStatus = item.frontmatter.get("status");
   const isRoot = !item.frontmatter.has("parent");
+  const rawArea = item.frontmatter.get("area");
+  if (rawArea !== void 0 && rawArea !== true) {
+    say("area-invalid", "error", `carries area: ${rawArea}. The only valid marker is area: true.`);
+  }
   if (isRoot) {
     if (rawStatus !== void 0) {
       say(
@@ -950,28 +1519,28 @@ function checkCycles(vault, report) {
 }
 
 // src/cli/commands/template.ts
-import { readFile as readFile2 } from "node:fs/promises";
-import { existsSync as existsSync3 } from "node:fs";
-import { mkdir } from "node:fs/promises";
-import { join as join4 } from "node:path";
+import { readFile as readFile4 } from "node:fs/promises";
+import { existsSync as existsSync4 } from "node:fs";
+import { mkdir as mkdir3 } from "node:fs/promises";
+import { join as join5 } from "node:path";
 var TEMPLATES_FOLDER = "Templates";
 function listTemplates() {
   return TEMPLATES;
 }
 async function writeTemplates(vault) {
-  const folder = join4(vault.root, TEMPLATES_FOLDER);
-  await mkdir(folder, { recursive: true });
+  const folder = join5(vault.root, TEMPLATES_FOLDER);
+  await mkdir3(folder, { recursive: true });
   const written = [];
   for (const template of TEMPLATES) {
-    const path = join4(folder, `${template.name}.md`);
+    const path = join5(folder, `${template.name}.md`);
     const relPath = `${TEMPLATES_FOLDER}/${template.name}.md`;
     const next = renderVaultTemplate(template, vault.config.defaultRoot, vault.config.extraSections);
-    if (!existsSync3(path)) {
+    if (!existsSync4(path)) {
       await writeAtomic(path, next);
       written.push({ name: template.name, relPath, outcome: "created" });
       continue;
     }
-    const current = await readFile2(path, "utf8");
+    const current = await readFile4(path, "utf8");
     if (current === next) {
       written.push({ name: template.name, relPath, outcome: "unchanged" });
       continue;
@@ -983,9 +1552,9 @@ async function writeTemplates(vault) {
 }
 
 // src/cli/commands/remove.ts
-import { mkdir as mkdir2, rename as rename2 } from "node:fs/promises";
-import { existsSync as existsSync4 } from "node:fs";
-import { join as join5 } from "node:path";
+import { mkdir as mkdir4, rename as rename3 } from "node:fs/promises";
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join6 } from "node:path";
 var TRASH = ".trash";
 function subtree(vault, root) {
   const ordered = [];
@@ -1005,7 +1574,7 @@ function trashPath(vault, item) {
   const stem = item.stem;
   for (let n = 0; n < 1e3; n++) {
     const name = n === 0 ? `${stem}.md` : `${stem} ${n}.md`;
-    if (!existsSync4(join5(vault.root, TRASH, name))) return `${TRASH}/${name}`;
+    if (!existsSync5(join6(vault.root, TRASH, name))) return `${TRASH}/${name}`;
   }
   return `${TRASH}/${stem} ${Date.now()}.md`;
 }
@@ -1030,8 +1599,8 @@ async function removeItem(vault, ref, options = {}) {
   for (const target of doomed) {
     const trashedTo = trashPath(vault, target);
     if (!dryRun) {
-      await mkdir2(join5(vault.root, TRASH), { recursive: true });
-      await rename2(target.path, join5(vault.root, ...trashedTo.split("/")));
+      await mkdir4(join6(vault.root, TRASH), { recursive: true });
+      await rename3(target.path, join6(vault.root, ...trashedTo.split("/")));
     }
     removed.push({ item: target, trashedTo });
   }
@@ -1080,10 +1649,78 @@ async function archiveItem(vault, ref, undo) {
   return { item, archived, changed: true };
 }
 
+// src/cli/commands/promote.ts
+async function setPromoted(vault, ref, promoted) {
+  const item = vault.resolve(ref);
+  if (isArea(item.area)) {
+    throw new Error(`${item.relPath} is an area and cannot be ${promoted ? "promoted" : "demoted"}.`);
+  }
+  if (item.board === promoted) return { item, promoted, changed: false };
+  await editItem(item, boardEdits(promoted));
+  return { item, promoted, changed: true };
+}
+
+// src/shared/area.ts
+function areaRefusal(item, direction) {
+  if (item.isRoot) return `${item.label} is a root, and a root is not a card or area child.`;
+  if (direction === "card") {
+    if (!item.isArea) return `${item.label} is not an area. Nothing to convert back to a card.`;
+    return null;
+  }
+  if (item.isArea) return `${item.label} is already an area.`;
+  if (item.agent !== void 0 && item.agent.trim() !== "") {
+    return `${item.label} has agent "${item.agent}". Release it before converting it to an area.`;
+  }
+  return null;
+}
+function areaEdits(item, target) {
+  const refusal = areaRefusal(item, target.kind);
+  if (refusal !== null) throw new Error(refusal);
+  if (target.kind === "area") {
+    return [
+      { op: "set", key: "area", value: true },
+      { op: "remove", key: "prev_status" }
+    ];
+  }
+  return [
+    { op: "remove", key: "area" },
+    { op: "remove", key: "prev_status" }
+  ];
+}
+
+// src/cli/commands/area.ts
+async function setArea(vault, ref, options) {
+  const item = vault.resolve(ref);
+  const agent = item.frontmatter.get("agent");
+  const state = {
+    label: item.relPath,
+    isRoot: item.parent === null,
+    isArea: item.area,
+    status: item.status,
+    agent: typeof agent === "string" ? agent : void 0
+  };
+  const direction = options.off ? "card" : "area";
+  const refusal = areaRefusal(state, direction);
+  if (refusal !== null) throw new Error(refusal);
+  if (options.off) {
+    const status = item.status;
+    if (!isStatus(status)) throw new Error(`${item.relPath} has no valid status to preserve.`);
+    const target = { kind: "card" };
+    const edits2 = areaEdits(state, target);
+    const before2 = item.text;
+    const after2 = await editItem(item, edits2);
+    return { item, from: "area", to: "card", status, changed: before2 !== after2 };
+  }
+  const edits = areaEdits(state, { kind: "area" });
+  const before = item.text;
+  const after = await editItem(item, edits);
+  return { item, from: "card", to: "area", status: item.status, changed: before !== after };
+}
+
 // src/cli/commands/hook.ts
 import { execFile } from "node:child_process";
-import { existsSync as existsSync5 } from "node:fs";
-import { chmod, mkdir as mkdir3, readFile as readFile3, rm, writeFile as writeFile2 } from "node:fs/promises";
+import { existsSync as existsSync6 } from "node:fs";
+import { chmod, mkdir as mkdir5, readFile as readFile5, rm as rm2, writeFile as writeFile3 } from "node:fs/promises";
 import { dirname as dirname3, resolve } from "node:path";
 import { promisify } from "node:util";
 var run = promisify(execFile);
@@ -1115,8 +1752,8 @@ exec ${shellQuote(process.execPath)} ${shellQuote(entry)} validate --vault ${she
 async function hookStatus(vault) {
   const git = await gitHook(vault);
   if (!git) return { vault, gitRepo: null, preCommit: "not installed" };
-  const present = existsSync5(git.path);
-  const ours = present && isOurHook(await readFile3(git.path, "utf8"));
+  const present = existsSync6(git.path);
+  const ours = present && isOurHook(await readFile5(git.path, "utf8"));
   return {
     vault,
     gitRepo: git.top,
@@ -1126,51 +1763,269 @@ async function hookStatus(vault) {
 async function installHook(vault, entry, force) {
   const git = await gitHook(vault);
   if (!git) throw new Error(`${vault} is not inside a Git repository. Run: git -C ${shellQuote(vault)} init`);
-  if (existsSync5(git.path)) {
-    const current = await readFile3(git.path, "utf8");
+  if (existsSync6(git.path)) {
+    const current = await readFile5(git.path, "utf8");
     if (!isOurHook(current) && !force) {
       throw new Error(`${git.path} already exists and is not ours. Read it, then pass --force to replace it.`);
     }
   }
-  await mkdir3(dirname3(git.path), { recursive: true });
-  await writeFile2(git.path, hookBody(vault, entry), "utf8");
+  await mkdir5(dirname3(git.path), { recursive: true });
+  await writeFile3(git.path, hookBody(vault, entry), "utf8");
   await chmod(git.path, 493);
   return git.path;
 }
 async function uninstallHook(vault) {
   const git = await gitHook(vault);
-  if (!git || !existsSync5(git.path) || !isOurHook(await readFile3(git.path, "utf8"))) return null;
-  await rm(git.path);
+  if (!git || !existsSync6(git.path) || !isOurHook(await readFile5(git.path, "utf8"))) return null;
+  await rm2(git.path);
   return git.path;
 }
 
+// src/cli/commands/setup.ts
+import { cp, lstat, mkdir as mkdir6, readFile as readFile6, rename as rename4, rm as rm3, writeFile as writeFile4 } from "node:fs/promises";
+import { homedir as homedir2, platform } from "node:os";
+import { dirname as dirname4, join as join7, resolve as resolve2 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+function detectObsidianRegistryPath(location) {
+  if (location.registryPath) return location.registryPath;
+  switch (location.platform) {
+    case "darwin":
+      return join7(location.home, "Library", "Application Support", "obsidian", "obsidian.json");
+    case "linux":
+      return join7(location.home, ".config", "obsidian", "obsidian.json");
+    case "win32":
+      return join7(location.appData ?? join7(location.home, "AppData", "Roaming"), "obsidian", "obsidian.json");
+    default:
+      throw new Error(`wi setup does not know the Obsidian registry location for ${location.platform}.`);
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function readObsidianVaults(location) {
+  const path = detectObsidianRegistryPath(location);
+  let text;
+  try {
+    text = await readFile6(path, "utf8");
+  } catch (error) {
+    if (isMissingFile2(error)) return [];
+    throw error;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`cannot read Obsidian vault registry ${path}: invalid JSON.`);
+  }
+  if (!isRecord(parsed) || !isRecord(parsed["vaults"])) {
+    throw new Error(`cannot read Obsidian vault registry ${path}: expected a vaults object.`);
+  }
+  const paths = [];
+  for (const entry of Object.values(parsed["vaults"])) {
+    if (!isRecord(entry) || typeof entry["path"] !== "string" || entry["path"].trim() === "") continue;
+    const vaultPath = resolve2(entry["path"]);
+    if (!paths.includes(vaultPath)) paths.push(vaultPath);
+  }
+  return paths;
+}
+function isMissingFile2(error) {
+  return isRecord(error) && error["code"] === "ENOENT";
+}
+var MANAGED_MARKER = ".recursive-board-managed";
+var MANAGED_TEXT = "Installed by wi setup.\n";
+async function installSkillCopy(source, destination, force) {
+  let existing;
+  try {
+    existing = await lstat(destination);
+  } catch (error) {
+    if (!isMissingFile2(error)) throw error;
+  }
+  if (existing?.isSymbolicLink()) return "dev-link";
+  if (existing) {
+    const managed = existing.isDirectory() && await readFile6(join7(destination, MANAGED_MARKER), "utf8").then((value) => value === MANAGED_TEXT).catch(() => false);
+    if (!managed && !force) {
+      throw new Error(`${destination} already exists and was not installed by wi setup. Read it, then pass --force to replace it.`);
+    }
+    if (managed) {
+      const same = await readFile6(join7(destination, "SKILL.md"), "utf8").catch(() => null);
+      const expected = await readFile6(join7(source, "SKILL.md"), "utf8");
+      if (same === expected) return "already-installed";
+    }
+    await rm3(destination, { recursive: true, force: true });
+  }
+  await mkdir6(dirname4(destination), { recursive: true });
+  await cp(source, destination, { recursive: true, errorOnExist: true, force: false });
+  await writeFile4(join7(destination, MANAGED_MARKER), MANAGED_TEXT, "utf8");
+  return "installed";
+}
+async function writeDefaultVault(vault) {
+  const root = wiConfigDir();
+  const path = join7(root, "config.json");
+  let current = {};
+  try {
+    const parsed = JSON.parse(await readFile6(path, "utf8"));
+    if (!isRecord(parsed)) throw new Error(`cannot update ${path}: expected a JSON object.`);
+    current = parsed;
+  } catch (error) {
+    if (isMissingFile2(error)) {
+      current = {};
+    } else if (error instanceof SyntaxError) {
+      throw new Error(`cannot update ${path}: invalid JSON.`);
+    } else {
+      throw error;
+    }
+  }
+  await mkdir6(root, { recursive: true });
+  const temporary = `${path}.tmp-${process.pid}`;
+  await writeFile4(temporary, `${JSON.stringify({ ...current, defaultVault: resolve2(vault) }, null, 2)}
+`, "utf8");
+  await rename4(temporary, path);
+  return path;
+}
+async function hasWorkItems(path) {
+  try {
+    return (await loadVault(path)).items.length > 0;
+  } catch {
+    return false;
+  }
+}
+async function rankVaults(paths) {
+  const ranked = await Promise.all(paths.map(async (path) => ({ path, hasItems: await hasWorkItems(path) })));
+  ranked.sort((a, b) => Number(b.hasItems) - Number(a.hasItems) || a.path.localeCompare(b.path));
+  return ranked;
+}
+async function selectVault(vaults) {
+  const ranked = await rankVaults(vaults);
+  if (ranked.length === 0) {
+    throw new Error("no Obsidian vaults found. Open a vault in Obsidian, or run wi setup --vault <path>.");
+  }
+  stdout.write("Choose your default Obsidian vault:\n");
+  ranked.forEach((entry, index) => stdout.write(`  ${index + 1}. ${entry.path}${entry.hasItems ? " (work items found)" : ""}
+`));
+  const io = createInterface({ input: stdin, output: stdout });
+  try {
+    for (; ; ) {
+      const answer = (await io.question(`Vault [1-${ranked.length}]: `)).trim();
+      const choice = Number(answer);
+      if (Number.isInteger(choice) && choice >= 1 && choice <= ranked.length) return ranked[choice - 1].path;
+      stdout.write(`Enter a number from 1 to ${ranked.length}.
+`);
+    }
+  } finally {
+    io.close();
+  }
+}
+async function confirmHook() {
+  const io = createInterface({ input: stdin, output: stdout });
+  try {
+    return /^(y|yes)$/i.test((await io.question("This vault is a Git repository. Install the wi validation hook? [y/N] ")).trim());
+  } finally {
+    io.close();
+  }
+}
+async function runSetup(options) {
+  if (options.yes && !options.vault) throw new Error("wi setup --yes needs --vault <path> so it can run without questions.");
+  const home = homedir2();
+  const vault = resolve2(options.vault ?? await selectVault(await readObsidianVaults({
+    platform: platform(),
+    home,
+    ...process.env["APPDATA"] ? { appData: process.env["APPDATA"] } : {}
+  })));
+  const moduleDir = dirname4(fileURLToPath(import.meta.url));
+  const skillCandidates = [
+    resolve2(moduleDir, "..", "..", "..", "skills", "recursive-board"),
+    resolve2(moduleDir, "..", "..", "skills", "recursive-board")
+  ];
+  let packagedSkill;
+  for (const candidate of skillCandidates) {
+    try {
+      await readFile6(join7(candidate, "SKILL.md"), "utf8");
+      packagedSkill = candidate;
+      break;
+    } catch (error) {
+      if (!isMissingFile2(error)) throw error;
+    }
+  }
+  if (!packagedSkill) throw new Error("the recursive-board skill is missing from this installation.");
+  const destinations = [
+    join7(home, ".claude", "skills", "recursive-board"),
+    join7(home, ".agents", "skills", "recursive-board")
+  ];
+  const outcomes = await Promise.all(destinations.map((destination) => installSkillCopy(packagedSkill, destination, options.force)));
+  const configPath = await writeDefaultVault(vault);
+  stdout.write(`wi setup: default vault ${vault}
+`);
+  stdout.write(`wi setup: config ${configPath}
+`);
+  destinations.forEach((destination, index) => stdout.write(`wi setup: ${outcomes[index]} ${destination}
+`));
+  if (!options.yes) {
+    const status = await hookStatus(vault);
+    if (status.gitRepo && await confirmHook()) {
+      const entry = fileURLToPath(import.meta.url);
+      const hook = await installHook(vault, entry, false);
+      stdout.write(`wi setup: installed validation hook ${hook}
+`);
+    }
+  }
+}
+
 // src/cli/wi.ts
 var HELP = `wi \u2014 the Recursive Board CLI
 
 Usage
+  wi setup [--yes] [--vault <path>] [--force]
   wi new <title> [--parent <ref>] [--status <s>] [--template <t>] [--owner <o>] [--agent <a>]
-                                [--priority <n>]
+                 [--priority <n>] [--objective <text>] [--context <text>]... [--criteria <text>]...
+                 [--strict]
   wi status <ref> <status>
+  wi note <ref> <text> [--agent <name>]
+  wi area <ref> [--off]
+  wi claim <ref> --agent <name>
+  wi agents
+  wi release <ref> --reason <text> [--where <branch-or-path>]
   wi move <ref> --to <ref>
   wi archive <ref> [--undo]
+  wi promote <ref>
+  wi demote <ref>
   wi rm <ref> [--recursive] [--dry-run]
-  wi children <ref> [--status <s>] [--tree] [--archived]
+  wi children [<ref>] [--status <s>] [--tree] [--archived]
   wi validate
+  wi retag [--dry-run]
+  wi graph
   wi template [list|write]
   wi hook <install|uninstall|status> [--force]
+  wi here [--board <ref>] [--vault <path>]
 
 A <ref> is a work item id, a filename or a title. An id always wins.
 A <status> is one of: ${STATUSES.join(", ")}.
 A <template> is one of: ${templateNames().join(", ")}.
 
 Options
-  --vault <path>   The vault root. Defaults to $WI_VAULT, then the nearest configured vault or Boards/.
+  --vault <path>   The vault root. Defaults to $WI_VAULT, the nearest vault, this repo's pointer, then defaultVault.
+  --board <ref>    Board work item used by wi here.
   --json           Machine-readable output.
-  --force          Replace another pre-commit hook with wi hook install.
+  --force          Replace an unrelated hook, or an unmanaged skill during setup.
+  --yes            Run setup without prompts; requires --vault <path>.
   -h, --help       This text.
   -V, --version    Print the version.
 
 Notes
+  \`wi new\` writes the brief: --objective once, --context and --criteria once per paragraph or
+  criterion. It warns when the card has no Objective or Acceptance Criteria; --strict refuses it.
+  A title's unsafe filename characters become hyphens. When another item has the same filename,
+  the new file gets the id's suffix; wi never writes over a file.
+  \`wi new\` makes a parent a board when it gives the parent its first child. Set
+  "autoPromote": false in .wi.json to turn this off. A root or an area is never changed.
+  With "areaTags": true in .wi.json, each work item carries one tag naming its areas, such as
+  area/work/website. \`wi new\` writes it. After \`wi move\` or \`wi area\`, run \`wi retag\` to fix
+  the tags below. \`wi graph\` writes a colour group per area to .obsidian/graph.json and keeps
+  your own groups. Close the graph view first: Obsidian may write over the file.
+  \`wi note\` appends "- <date> <time>, <agent>: <text>" under Notes. The agent defaults to the
+  card's agent. The write re-reads the card under a lock, so two notes at once both survive.
+  \`wi status <ref> done\` says when that was the parent's last open child. It does not close the parent.
   Unticking a done item is \`wi status <ref> <its prev_status>\`, which also clears the record.
   \`wi validate\` exits 1 when the vault has errors, so it works as a pre-commit hook.
   \`wi template write\` regenerates Templates/ from the code, which is authoritative.
@@ -1181,9 +2036,18 @@ Notes
   folder, because the index cannot read it and may be missing a work item. Let the sync
   client download the file, or delete the stray file, then retry. There is no --force.
   \`wi archive\` changes one flag. Descendants disappear with their parent at read time.
+  \`wi area <ref>\` marks a card as an area and keeps its status. It refuses a card with an agent.
+  Use \`wi area <ref> --off\` to convert back without changing its status.
+  \`wi claim\` refuses a card with blocked: true, and \`wi children\` marks one [blocked].
+  \`wi claim\` lets an agent hold a card and its subtasks at once. It refuses a board with a child in
+  doing that a different agent or a person works.
+  \`wi agents\` reports the advisory limit, the number of distinct agents with a doing card, and each
+  claimed doing card. WI_MAX_AGENTS overrides
+  maxAgents from .wi.json for one run. Dispatchers decide whether to wait; wi claim does not enforce it.
   \`wi new\` warns when such a file exists because a new id or filename may clash with it.
+  \`wi here\` reads or sets this repository's vault and board pointer in your user config.
 `;
-var VERSION = "0.1.2";
+var VERSION = "0.3.0";
 var UsageError = class extends Error {
 };
 async function main(argv) {
@@ -1197,16 +2061,25 @@ async function main(argv) {
       status: { type: "string" },
       owner: { type: "string" },
       agent: { type: "string" },
+      reason: { type: "string" },
+      where: { type: "string" },
       priority: { type: "string" },
       template: { type: "string" },
+      objective: { type: "string" },
+      context: { type: "string", multiple: true },
+      criteria: { type: "string", multiple: true },
+      strict: { type: "boolean", default: false },
       vault: { type: "string" },
+      board: { type: "string" },
       tree: { type: "boolean", default: false },
       archived: { type: "boolean", default: false },
       undo: { type: "boolean", default: false },
+      off: { type: "boolean", default: false },
       recursive: { type: "boolean", short: "r", default: false },
       "dry-run": { type: "boolean", default: false },
       json: { type: "boolean", default: false },
       force: { type: "boolean", default: false },
+      yes: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false },
       version: { type: "boolean", short: "V", default: false }
     }
@@ -1216,14 +2089,29 @@ async function main(argv) {
 `);
     return 0;
   }
-  const [command, ...rest] = positionals;
+  let [command, ...rest] = positionals;
   if (values.help || command === void 0 || command === "help") {
     process.stdout.write(HELP);
     return command === void 0 && !values.help ? 2 : 0;
   }
-  if (values.force && (command !== "hook" || rest[0] !== "install")) {
-    throw new UsageError("--force applies only to wi hook install.");
+  if (values.force && !(command === "hook" && rest[0] === "install" || command === "setup")) {
+    throw new UsageError("--force applies only to wi hook install or wi setup.");
+  }
+  if (values.yes && command !== "setup") throw new UsageError("--yes applies only to wi setup.");
+  if (values.off && command !== "area") throw new UsageError("--off applies only to wi area.");
+  if ((values.objective !== void 0 || values.context !== void 0 || values.criteria !== void 0 || values.strict) && command !== "new") {
+    throw new UsageError("--objective, --context, --criteria and --strict apply only to wi new.");
   }
+  if (command === "setup") {
+    if (rest.length > 0) throw new UsageError("wi setup takes options only. Run wi setup --help for usage.");
+    await runSetup({
+      ...typeof values["vault"] === "string" ? { vault: values["vault"] } : {},
+      yes: values["yes"] === true,
+      force: values["force"] === true
+    });
+    return 0;
+  }
+  if (command === "here") return runHere(values, values.json === true);
   const vault = await openVault(values.vault);
   const json = values.json;
   switch (command) {
@@ -1231,16 +2119,39 @@ async function main(argv) {
       return runNew(vault, rest, values, json);
     case "status":
       return runStatus(vault, rest, json);
+    case "area":
+      return withRetagHint(vault, () => runArea(vault, rest, values, json));
+    case "note":
+      return runNote(vault, rest, values, json);
+    case "claim":
+      return runClaim(vault, rest, values, json);
+    case "agents":
+      return runAgents(vault, rest, json);
+    case "release":
+      return runRelease(vault, rest, values, json);
     case "move":
-      return runMove(vault, rest, values, json);
+      return withRetagHint(vault, () => runMove(vault, rest, values, json));
     case "archive":
       return runArchive(vault, rest, values, json);
+    case "promote":
+      return runPromote(vault, rest, true, json);
+    case "demote":
+      return runPromote(vault, rest, false, json);
     case "rm":
       return runRemove(vault, rest, values, json);
     case "children":
+      if (rest.length === 0) {
+        const board = await repoBoardForVault(vault);
+        if (!board) throw new UsageError("wi children needs a <ref> or a matching board pointer from wi here.");
+        rest = [board];
+      }
       return runChildren(vault, rest, values, json);
     case "validate":
       return runValidate(vault, json);
+    case "retag":
+      return runRetag(vault, rest, values, json);
+    case "graph":
+      return runGraph(vault, rest, json);
     case "template":
       return runTemplate(vault, rest, json);
     case "hook":
@@ -1251,10 +2162,18 @@ async function main(argv) {
 }
 async function openVault(flag) {
   const hint = flag ?? process.env["WI_VAULT"];
-  const root = hint ? resolve2(hint) : findVaultRoot(process.cwd());
+  let root = hint ? resolve3(hint) : findVaultRoot(process.cwd());
+  if (root === null) {
+    const pointer = await getRepoPointer(process.cwd());
+    root = pointer ? resolve3(pointer.vault) : null;
+  }
+  if (root === null) {
+    const configured = await getDefaultVault();
+    root = configured ? resolve3(configured) : null;
+  }
   if (root === null) {
     throw new UsageError(
-      "no vault found. Run wi inside a vault, pass --vault <path>, or set WI_VAULT."
+      "no vault found. Run wi inside a vault, pass --vault <path>, set WI_VAULT, run wi here, or configure defaultVault with wi setup."
     );
   }
   if (findVaultRoot(root) !== root) {
@@ -1262,11 +2181,45 @@ async function openVault(flag) {
   }
   return loadVault(root);
 }
+async function runHere(values, json) {
+  const start = process.cwd();
+  const hasFlags = typeof values["board"] === "string" || typeof values["vault"] === "string";
+  const needsExisting = !hasFlags || typeof values["board"] !== "string" || typeof values["vault"] !== "string";
+  const existing = needsExisting ? await getRepoPointer(start) : null;
+  if (!hasFlags) {
+    if (!existing) throw new UsageError("no board pointer is set for this Git repository. Run wi here --board <ref> --vault <path>.");
+    if (json) process.stdout.write(`${JSON.stringify(existing)}
+`);
+    else process.stdout.write(`vault  ${existing.vault}
+board  ${existing.board}
+`);
+    return 0;
+  }
+  const vault = await openVault(typeof values["vault"] === "string" ? values["vault"] : void 0);
+  const board = typeof values["board"] === "string" ? values["board"] : existing?.board ?? vault.config.defaultRoot;
+  if (!board) throw new UsageError("wi here needs --board <ref> or an existing repo board pointer.");
+  const resolved = vault.resolve(board);
+  const pointer = { vault: vault.root, board: resolved.id ?? resolved.stem };
+  await setRepoPointer(start, pointer);
+  if (json) process.stdout.write(`${JSON.stringify(pointer)}
+`);
+  else process.stdout.write(`set repo pointer
+vault  ${pointer.vault}
+board  ${pointer.board}
+`);
+  return 0;
+}
+async function repoBoardForVault(vault) {
+  const pointer = await getRepoPointer(process.cwd());
+  return pointer && resolve3(pointer.vault) === resolve3(vault.root) ? pointer.board : void 0;
+}
 async function runNew(vault, rest, values, json) {
   const title = rest.join(" ").trim();
   if (title === "") throw new UsageError('wi new needs a title. Try: wi new "Build server" --parent Main');
-  const parent = typeof values["parent"] === "string" ? values["parent"] : vault.config.defaultRoot;
-  if (!parent) throw new UsageError("wi new needs --parent <ref> or defaultRoot in .wi.json.");
+  const explicitParent = typeof values["parent"] === "string" ? values["parent"] : void 0;
+  const pointerBoard = explicitParent === void 0 ? await repoBoardForVault(vault) : void 0;
+  const parent = explicitParent ?? pointerBoard ?? vault.config.defaultRoot;
+  if (!parent) throw new UsageError("wi new needs --parent <ref>, a repo board pointer, or defaultRoot in .wi.json.");
   const priority = typeof values["priority"] === "string" ? Number(values["priority"]) : void 0;
   if (priority !== void 0 && !Number.isFinite(priority)) {
     throw new UsageError(`--priority must be a number, not "${values["priority"]}".`);
@@ -1278,7 +2231,13 @@ async function runNew(vault, rest, values, json) {
     ...typeof values["owner"] === "string" ? { owner: values["owner"] } : {},
     ...typeof values["agent"] === "string" ? { agent: values["agent"] } : {},
     ...typeof values["template"] === "string" ? { template: values["template"] } : {},
-    ...priority !== void 0 ? { priority } : {}
+    ...priority !== void 0 ? { priority } : {},
+    brief: {
+      objective: typeof values["objective"] === "string" ? values["objective"] : void 0,
+      context: Array.isArray(values["context"]) ? values["context"] : void 0,
+      criteria: Array.isArray(values["criteria"]) ? values["criteria"] : void 0
+    },
+    strict: values["strict"] === true
   });
   if (vault.unaccounted.length > 0) {
     process.stderr.write(
@@ -1286,9 +2245,28 @@ async function runNew(vault, rest, values, json) {
 `
     );
   }
-  if (json) print({ id: created.id, path: created.relPath, parent: created.parentStem });
-  else process.stdout.write(`${created.id}  ${created.relPath}  (child of ${created.parentStem})
+  if (created.gaps.length > 0) {
+    process.stderr.write(`wi: warning: ${created.id} has no ${created.gaps.join(" or ")}. Pass --objective and --criteria, or fill the card before work starts.
+`);
+  }
+  if (created.renamed) {
+    process.stderr.write(`wi: note: another item has this filename, so this one is ${created.relPath}. If they are different work, give the card a more specific title.
+`);
+  }
+  if (json) {
+    print({
+      id: created.id,
+      path: created.relPath,
+      parent: created.parentStem,
+      promoted_parent: created.promotedParent,
+      gaps: created.gaps
+    });
+  } else {
+    process.stdout.write(`${created.id}  ${created.relPath}  (child of ${created.parentStem})
+`);
+    if (created.promotedParent) process.stdout.write(`${created.parentStem}  promoted to a board (its first child)
 `);
+  }
   return 0;
 }
 async function runStatus(vault, rest, json) {
@@ -1304,7 +2282,8 @@ async function runStatus(vault, rest, json) {
       from: change.from ?? null,
       to: change.to,
       prev_status: change.recorded ?? null,
-      changed: change.changed
+      changed: change.changed,
+      parent_ready: change.parentReady?.id ?? null
     });
   } else if (!change.changed) {
     process.stdout.write(`${label(change.item)} is already ${change.to}. Nothing written.
@@ -1312,10 +2291,134 @@ async function runStatus(vault, rest, json) {
   } else {
     const recorded = change.recorded ? `  (prev_status: ${change.recorded})` : "";
     process.stdout.write(`${label(change.item)}  ${change.from ?? "\u2014"} \u2192 ${change.to}${recorded}
+`);
+  }
+  const ready = change.parentReady;
+  if (ready && !json) {
+    process.stdout.write(`${label(ready)}  every child is done. If its own criteria are met, run: wi status ${ready.id ?? ready.stem} done
+`);
+  }
+  return 0;
+}
+async function runArea(vault, rest, values, json) {
+  const ref = rest.join(" ").trim();
+  if (ref === "") {
+    throw new UsageError("wi area needs a <ref>. Use --off to convert an area back to a card.");
+  }
+  if (typeof values["status"] === "string") throw new UsageError("--status does not apply to wi area; conversion preserves the current status.");
+  const change = await setArea(vault, ref, {
+    off: values["off"] === true
+  });
+  if (json) {
+    print({
+      id: change.item.id,
+      path: change.item.relPath,
+      from: change.from,
+      to: change.to,
+      status: change.status ?? null,
+      changed: change.changed
+    });
+  } else {
+    process.stdout.write(`${label(change.item)}  ${change.from} \u2192 ${change.to}${change.status ? `  (status: ${change.status})` : ""}
+`);
+  }
+  return 0;
+}
+function singleLineOption(values, key) {
+  const value = values[key];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new UsageError(`--${key} needs non-empty text.`);
+  }
+  if (/[\r\n]/.test(value)) throw new UsageError(`--${key} must be one line.`);
+  return value.trim();
+}
+async function runClaim(vault, rest, values, json) {
+  const ref = rest.join(" ").trim();
+  if (ref === "") throw new UsageError("wi claim needs a <ref> and --agent <name>.");
+  const agent = singleLineOption(values, "agent");
+  const maxAgents = maxAgentsForRun(vault);
+  const active = activeAgentNames(vault);
+  const change = await claimItem(vault, ref, agent);
+  if (json) print({
+    id: change.item.id,
+    path: change.item.relPath,
+    agent: change.agent,
+    from: change.from ?? null,
+    to: change.to,
+    changed: change.changed
+  });
+  else process.stdout.write(change.changed ? `${label(change.item)}  ${change.from ?? "\u2014"} \u2192 doing  (agent: ${agent})
+` : `${label(change.item)} is already claimed by ${agent} in doing. Nothing written.
+`);
+  if (change.changed && maxAgents !== null && !active.has(agent) && active.size + 1 > maxAgents) {
+    process.stderr.write(`wi: warning: agent limit is ${maxAgents}; ${active.size + 1} agents now have a doing card.
 `);
   }
   return 0;
 }
+async function runNote(vault, rest, values, json) {
+  const [ref, ...words] = rest;
+  const text = words.join(" ").trim();
+  if (ref === void 0 || text === "") {
+    throw new UsageError('wi note needs a <ref> and the text. Try: wi note wi-a7f3 "Priced 12 lines."');
+  }
+  const agent = values["agent"] === void 0 ? void 0 : singleLineOption(values, "agent");
+  const added = await addNote(vault, ref, text, agent);
+  if (json) print({ id: added.item.id, path: added.item.relPath, line: added.line });
+  else process.stdout.write(`${label(added.item)}  ${added.line}
+`);
+  return 0;
+}
+function claimedDoing(vault) {
+  return vault.items.flatMap((item) => {
+    const agent = item.frontmatter.get("agent");
+    return item.status === "doing" && typeof agent === "string" && agent.trim() !== "" ? [{ agent, item }] : [];
+  });
+}
+function activeAgentNames(vault) {
+  return new Set(claimedDoing(vault).map((claim) => claim.agent));
+}
+function runAgents(vault, rest, json) {
+  if (rest.length > 0) throw new UsageError("wi agents takes no arguments.");
+  const maxAgents = maxAgentsForRun(vault);
+  const claims = claimedDoing(vault).sort((a, b) => a.agent.localeCompare(b.agent));
+  const activeAgents = new Set(claims.map((claim) => claim.agent)).size;
+  if (json) {
+    print({ maxAgents, activeAgents, claims: claims.map(({ agent, item }) => ({
+      agent,
+      id: item.id ?? null,
+      title: item.title ?? item.stem,
+      path: item.relPath
+    })) });
+    return 0;
+  }
+  process.stdout.write(`limit  ${maxAgents === null ? "none" : maxAgents}
+agents with a doing card  ${activeAgents}
+`);
+  for (const { agent, item } of claims) process.stdout.write(`  ${agent}  ${label(item)}
+`);
+  return 0;
+}
+async function runRelease(vault, rest, values, json) {
+  const ref = rest.join(" ").trim();
+  if (ref === "") throw new UsageError("wi release needs a <ref> and --reason <text>.");
+  const reason = singleLineOption(values, "reason");
+  const where = values["where"] === void 0 ? void 0 : singleLineOption(values, "where");
+  const change = await releaseItem(vault, ref, reason, where);
+  if (json) print({
+    id: change.item.id,
+    path: change.item.relPath,
+    agent: change.agent,
+    from: change.from ?? null,
+    to: change.to,
+    reason: change.reason,
+    where: change.where ?? null,
+    changed: change.changed
+  });
+  else process.stdout.write(`${label(change.item)}  ${change.from ?? "\u2014"} \u2192 options  (released ${change.agent})
+`);
+  return 0;
+}
 async function runMove(vault, rest, values, json) {
   const ref = rest.join(" ").trim();
   const to = typeof values["to"] === "string" ? values["to"] : "";
@@ -1353,6 +2456,19 @@ async function runArchive(vault, rest, values, json) {
   }
   return 0;
 }
+async function runPromote(vault, rest, promoted, json) {
+  const ref = rest.join(" ").trim();
+  if (ref === "") throw new UsageError(`wi ${promoted ? "promote" : "demote"} needs a <ref>.`);
+  const change = await setPromoted(vault, ref, promoted);
+  if (json) {
+    print({ id: change.item.id, path: change.item.relPath, promoted: change.promoted, changed: change.changed });
+  } else {
+    const verb = promoted ? "promoted" : "demoted";
+    process.stdout.write(`${label(change.item)}  ${change.changed ? verb : `already ${promoted ? "a board" : "a card"}; nothing written`}
+`);
+  }
+  return 0;
+}
 async function runRemove(vault, rest, values, json) {
   const ref = rest.join(" ").trim();
   if (ref === "") throw new UsageError("wi rm needs a <ref>.");
@@ -1395,6 +2511,14 @@ function runChildren(vault, rest, values, json) {
     print({
       parent: { id: listing.parent.id, path: listing.parent.relPath, board: listing.parent.board },
       cycle: listing.cycle,
+      areas: listing.areas.map((row) => ({
+        id: row.item.id,
+        title: row.item.title,
+        path: row.item.relPath,
+        children: row.childCount,
+        depth: row.depth,
+        archived: row.archived
+      })),
       children: listing.children.map((row) => ({
         id: row.item.id,
         title: row.item.title,
@@ -1402,7 +2526,8 @@ function runChildren(vault, rest, values, json) {
         status: row.item.status ?? null,
         children: row.childCount,
         depth: row.depth,
-        archived: row.archived
+        archived: row.archived,
+        blocked: row.item.frontmatter.get("blocked") === true
       }))
     });
     return 0;
@@ -1410,7 +2535,11 @@ function runChildren(vault, rest, values, json) {
   const out = [
     `${label(listing.parent)}${listing.parent.board ? "  [board]" : ""}`
   ];
-  if (listing.children.length === 0) {
+  if (listing.areas.length > 0) {
+    out.push(`  Areas (${listing.areas.length})`);
+    for (const row of listing.areas) out.push(`    ${"  ".repeat(row.depth)}${row3(row)}`);
+  }
+  if (listing.children.length === 0 && listing.areas.length === 0) {
     out.push("  no children");
   } else if (values["tree"] === true || typeof values["status"] === "string") {
     for (const row of listing.children) out.push(`  ${"  ".repeat(row.depth)}${row3(row)}`);
@@ -1425,6 +2554,39 @@ function runChildren(vault, rest, values, json) {
 `);
   return 0;
 }
+async function withRetagHint(vault, run2) {
+  const code = await run2();
+  if (vault.config.areaTags) {
+    const stale = staleAreaTags(await loadVault(vault.root)).length;
+    if (stale > 0) process.stderr.write(`wi: ${stale} work item${stale === 1 ? " has" : "s have"} a stale area tag. Run wi retag.
+`);
+  }
+  return code;
+}
+async function runRetag(vault, rest, values, json) {
+  if (rest.length > 0) throw new UsageError("wi retag takes no arguments.");
+  const dryRun = values["dry-run"] === true;
+  const changed = await retag(vault, dryRun);
+  if (json) {
+    print({ dryRun, changed: changed.map(({ item, from, to }) => ({ id: item.id ?? null, path: item.relPath, from, to })) });
+    return 0;
+  }
+  const verb = dryRun ? "would retag" : "retagged";
+  for (const { item, to } of changed) process.stdout.write(`${verb}  ${label(item)}  [${to.join(", ")}]
+`);
+  process.stdout.write(`${changed.length} work item${changed.length === 1 ? "" : "s"}${dryRun ? ", nothing written" : ""}
+`);
+  return 0;
+}
+async function runGraph(vault, rest, json) {
+  if (rest.length > 0) throw new UsageError("wi graph takes no arguments.");
+  const written = await writeGraphColours(vault);
+  if (json) print(written);
+  else process.stdout.write(`wrote ${written.groups} area colour groups to ${written.path}, kept ${written.kept} of your own
+reopen the graph view to see them
+`);
+  return 0;
+}
 async function runValidate(vault, json) {
   const report = await validate(vault);
   if (json) {
@@ -1507,7 +2669,7 @@ async function runHook(vault, rest, values, json) {
 ` : "done\n");
     return 0;
   }
-  const path = await installHook(vault.root, fileURLToPath(import.meta.url), values["force"] === true);
+  const path = await installHook(vault.root, fileURLToPath2(import.meta.url), values["force"] === true);
   if (json) print({ installed: path });
   else {
     process.stdout.write(`installed ${path}
@@ -1535,7 +2697,8 @@ function row3(row) {
   const kids = row.childCount > 0 ? `  (${row.childCount})` : "";
   const board = row.item.board ? "  [board]" : "";
   const archived = row.archived ? "  [archived]" : "";
-  return `${row.item.id ?? "(no id)"}  ${status.padEnd(7)}  ${row.item.title ?? row.item.stem}${kids}${board}${archived}`;
+  const blocked = row.item.frontmatter.get("blocked") === true ? "  [blocked]" : "";
+  return `${row.item.id ?? "(no id)"}  ${status.padEnd(7)}  ${row.item.title ?? row.item.stem}${kids}${board}${blocked}${archived}`;
 }
 function print(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}