recursive-board 0.1.1 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # Recursive Board
 
+> **Install with your agent.** Paste this prompt into your coding agent: "Check that Node.js 20.12 or later is installed, run `npm install --global recursive-board`, then run `wi setup`."
+
 Recursive Board turns a folder of Markdown files in an Obsidian vault into a hierarchical work board. Each work item is one Markdown file. Its parent link defines where it belongs.
 
 **Markdown is canonical. The plugin is a view, never the database.** The plugin renders and edits work items in Obsidian. The `wi` command-line tool supports scripts and agents. Both use the same schema and rules.
@@ -40,10 +42,18 @@ Place an optional `.wi.json` file at the vault root to choose the work-item fold
 
 `workItemFolder` is a vault-relative folder path. It defaults to `Boards`. `defaultRoot` is the filename stem of a root work item. It defaults to `null`, which means `wi new` needs an explicit `--parent`. `extraSections` is an array of non-empty, single-line headings. It defaults to `[]`. Each heading is added after the built-in template sections with an empty `- ` starter. The setting applies to `wi new`, `wi template write`, and items created in the plugin. Invalid values make `.wi.json` fail to load.
 
-`wi` finds the vault from `--vault <path>`, then `$WI_VAULT`, then the nearest folder with `.wi.json` or `Boards/`.
+`wi setup` writes the selected vault to the user config at `$XDG_CONFIG_HOME/wi/config.json`, or `~/.config/wi/config.json` when `XDG_CONFIG_HOME` is unset. The format is `{"defaultVault":"/absolute/path/to/vault"}`. Vault detection uses Obsidian's registry on macOS, Linux, and Windows. `--vault <path>` selects a vault directly, and `--yes --vault <path>` runs without prompts.
+
+`wi` finds the vault from `--vault <path>`, then `$WI_VAULT`, then the nearest folder with `.wi.json` or `Boards/`, then the current Git repo's pointer, then `defaultVault` in `~/.config/wi/config.json` (or `$XDG_CONFIG_HOME/wi/config.json`). Use `wi here --vault <path> --board <ref>` once in a repo to save its vault and board outside the repo. The pointer is keyed by Git's common directory, so linked worktrees share it. Run `wi here` to print the current repo's pointer.
 
 ## Start a board
 
+### Create one in Obsidian
+
+Enable Recursive Board in an empty vault. Use the **Create your first board** button in the notice, or run **Create your first board** from the command palette. Enter a name (the default is `Main`). The plugin creates the board, adds a starter card that explains how to move it, and opens the board.
+
+### Manual fallback
+
 1. Create the file `Boards/Project.md` with this content. A root item has no `parent` and no `status`:
 
    ```markdown
@@ -81,13 +91,14 @@ Reload Obsidian after replacing plugin files. If your vault syncs its `.obsidian
 ```sh
 npm install --global recursive-board
 wi --help
+wi setup
 ```
 
-Run `wi` inside a vault, pass `--vault <path>`, or set `WI_VAULT`. Commands accept a work-item id, filename, or title as a reference. An id takes precedence when references are ambiguous. Add `--json` for machine-readable output. The `--vault <path>` and `--json` flags apply to all commands.
+Run `wi` inside a vault, pass `--vault <path>`, set `WI_VAULT`, or set a repo pointer with `wi here`. Commands accept a work-item id, filename, or title as a reference. An id takes precedence when references are ambiguous. Add `--json` for machine-readable output. The `--vault <path>` and `--json` flags apply to all commands. With a repo pointer, `wi new` uses its board when `--parent` is omitted, and `wi children` uses it when the reference is omitted.
 
 ## Use with coding agents
 
-`skills/recursive-board/SKILL.md` teaches an agent to read and change a vault through `wi`. Copy that folder into your agent's skills folder, for example `~/.claude/skills/` for Claude Code or `~/.agents/skills/`. From a source checkout, `npm run install:skill` links it there and links `wi` into `~/.local/bin`.
+`skills/recursive-board/SKILL.md` teaches an agent to read and change a vault through `wi`. `wi setup` installs copies into `~/.claude/skills/recursive-board/` and `~/.agents/skills/recursive-board/`. It leaves symlinked development installs alone and refuses to replace an unmanaged folder unless you pass `--force`. From a source checkout, `npm run install:skill` links the skill and `wi` into `~/.local/bin`.
 
 ## Install the Git validation hook
 
@@ -105,14 +116,18 @@ The pre-commit hook runs `wi validate` and stops a commit when the vault has err
 
 | Command | What it does |
 | --- | --- |
-| `wi new <title> [--parent <ref>] [--status <status>] [--template <name>] [--owner <name>] [--agent <name>] [--priority <number>]` | Creates a work item under the given parent. If `--parent` is omitted, uses `defaultRoot` from `.wi.json`. |
+| `wi setup [--yes] [--vault <path>] [--force]` | Installs the agent skill, selects and saves a default vault, and offers the Git validation hook for a Git vault. `--yes` requires `--vault` and asks no questions. |
+| `wi new <title> [--parent <ref>] [--status <status>] [--template <name>] [--owner <name>] [--agent <name>] [--priority <number>]` | Creates a work item under the given parent. If `--parent` is omitted, uses the repo pointer's board, then `defaultRoot` from `.wi.json`. |
 | `wi status <ref> <status>` | Changes an item's status. Use `backlog`, `options`, `doing`, or `done`. Leaving `done` clears the recorded previous status. |
+| `wi claim <ref> --agent <name>` | Claims a card for an agent and moves it to doing in one write. Refuses a different agent, a done card, or a board with a child in doing. Repeating an active claim by the same agent writes nothing. |
+| `wi release <ref> --reason <text> [--where <branch-or-path>]` | Clears the agent, moves the card to options, and adds a dated line to Notes with the reason and optional work location. Refuses an unclaimed card. |
 | `wi move <ref> --to <ref>` | Changes the item's parent. Its status stays the same, and its children move with it. |
 | `wi archive <ref> [--undo]` | Archives an item. `--undo` unarchives it. Archived items are hidden from normal reads; descendants are hidden with an archived parent. |
 | `wi rm <ref> [--recursive] [--dry-run]` | Moves an item to the vault's `.trash` folder. Use `--dry-run` to preview. Items with children require `--recursive`. |
-| `wi children <ref> [--status <status>] [--tree] [--archived]` | Lists an item's children. `--status` filters by status, `--tree` shows descendants, and `--archived` includes archived items. |
+| `wi children [<ref>] [--status <status>] [--tree] [--archived]` | Lists an item's children. If the ref is omitted, uses the repo pointer's board. `--status` filters by status, `--tree` shows descendants, and `--archived` includes archived items. |
 | `wi validate` | Checks work-item structure and reports errors and warnings. Exits with code 1 when it finds errors. |
 | `wi hook install\|uninstall\|status [--vault <path>]` | Installs, removes, or inspects the Git pre-commit validation hook. `install --force` replaces an unrelated hook. |
+| `wi here [--board <ref>] [--vault <path>]` | Prints this Git repo's pointer, or sets it in user config. Linked worktrees share the pointer. |
 | `wi template [list\|write]` | Lists available templates, or writes the code's templates into `Templates/` with `wi template write`. Defaults to `list`. |
 | `wi --help` or `wi help` | Prints usage, options, and notes. |
 | `wi --version` | Prints the installed CLI version. |
@@ -123,6 +138,8 @@ The pre-commit hook runs `wi validate` and stops a commit when the vault has err
 
 Use `wi` for work-item changes. Do not edit work-item Markdown directly with scripts or bulk text tools. Use `wi validate` to check the vault after changes. `wi rm` moves items into `.trash`; removing a parent requires `--recursive`. Use `wi rm <ref> --dry-run` to review the affected items first.
 
+A dispatcher assigns a card with `wi claim <ref> --agent <name>`. If that worker stops, the dispatcher runs `wi release <ref> --reason <text> [--where <branch-or-path>]` so the next worker can find the unfinished work. Keep a card in doing until its work is accepted.
+
 ## Development
 
 Requirements: Node.js 23.6 or later and npm. The tests run the TypeScript source directly, which needs type stripping. The built `wi` runs on Node.js 20.12 or later.

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];
@@ -157,11 +166,16 @@ 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 with no 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) {
@@ -252,8 +266,8 @@ 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.`);
       }
@@ -292,6 +306,73 @@ function activeDescendant(item, childrenOf, statusOf) {
 
 // src/cli/vault.ts
 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 +436,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 +514,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 +540,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
   };
@@ -472,7 +554,7 @@ import { existsSync as existsSync2 } from "node:fs";
 import { join as join3 } from "node:path";
 
 // src/cli/write.ts
-import { writeFile, rename } from "node:fs/promises";
+import { writeFile as writeFile2, rename as rename2 } from "node:fs/promises";
 import { dirname as dirname2, join as join2 } from "node:path";
 
 // src/shared/edits.ts
@@ -491,12 +573,13 @@ 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);
+  await writeFile2(temp, text, "utf8");
+  await rename2(temp, path);
 }
-async function editItem(item, edits) {
-  const text = applyEdits(item.text, withStamp(edits));
-  if (text !== item.text) await writeAtomic(item.path, text);
+async function editItem(item, edits, editBody = (text) => text) {
+  if (editBody(applyEdits(item.text, edits)) === item.text) return item.text;
+  const text = editBody(applyEdits(item.text, withStamp(edits)));
+  await writeAtomic(item.path, text);
   return text;
 }
 
@@ -511,6 +594,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. To move this card, open its card menu and choose \u201CMove to\u2026\u201D." },
+      { heading: "Notes" }
+    ]
+  },
+  {
+    name: "area",
+    description: "An ongoing area of work with no status.",
+    area: true,
+    sections: [
+      { heading: "Objective" },
+      { heading: "Context" },
+      { heading: "Notes" }
+    ]
   }
 ];
 var DEFAULT_TEMPLATE = "work-item";
@@ -542,14 +643,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(
+  if (template.area) placeholders["area"] = "true";
+  else placeholders["status"] = "backlog";
+  const fields = template.area ? CORE_FIELDS.filter((field) => field !== "status") : CORE_FIELDS;
+  const lines = fields.filter((field) => field in placeholders).map(
     (field) => `${field}: ${placeholders[field]}`.trimEnd()
   );
+  if (template.area) lines.splice(3, 0, "area: true");
   return `---
 ${lines.join("\n")}
 ---
@@ -559,13 +663,18 @@ ${renderBody(template, extraSections)}`;
 
 // src/shared/work-item.ts
 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]
   ];
+  if (item.area) fields.push(["area", true]);
+  else fields.push(["status", item.status]);
+  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]);
@@ -575,7 +684,7 @@ function renderWorkItem(item, extraSections = []) {
 ${frontmatter}
 ---
 
-${renderBody(requireTemplate(item.template), extraSections)}`;
+${renderBody(template, extraSections)}`;
 }
 
 // src/cli/commands/new.ts
@@ -586,9 +695,12 @@ async function createItem(vault, options) {
   if (parentRef.trim() === "") {
     throw new Error("a work item needs a --parent. Only the root has none.");
   }
-  requireTemplate(options.template);
+  const template = requireTemplate(options.template);
   const status = options.status ?? "backlog";
-  if (!isStatus(status)) {
+  if (template.area && options.status !== void 0) {
+    throw new Error("an area cannot have a status");
+  }
+  if (!template.area && !isStatus(status)) {
     throw new Error(`"${status}" is not a status. Use backlog, options, doing or done.`);
   }
   const parent = vault.resolve(parentRef);
@@ -600,15 +712,15 @@ async function createItem(vault, options) {
     throw new Error(`${relPath} already exists. Refusing to overwrite it.`);
   }
   const stamp = today();
-  const fields = {
+  const common = {
     id,
     title,
-    status,
     parentStem: parent.stem,
     created: stamp,
     updated: stamp,
     template: options.template
   };
+  const fields = template.area ? { ...common, area: true } : { ...common, status };
   for (const field of INHERITED_FIELDS) {
     const value = options[field] ?? parent.frontmatter.get(field);
     if (value !== void 0 && value !== "") fields[field] = String(value);
@@ -629,6 +741,20 @@ function statusEdits(from, to, hasPrevStatus) {
   }
   return edits;
 }
+function claimEdits(from, currentAgent, agent, hasPrevStatus, hasDoingChild) {
+  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 (hasDoingChild) throw new Error("this board has a child in doing. Release or finish the 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 moveEdits(currentParentStem, targetStem) {
   if (currentParentStem !== null && currentParentStem.toLowerCase() === targetStem.toLowerCase()) {
     return null;
@@ -671,6 +797,86 @@ async function setStatus(vault, ref, status) {
   return { item, from, to: status, recorded, changed: true };
 }
 
+// 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 === "" ? `${content}${line2}${eol}${next ? eol : ""}` : `${prose}${eol}${line2}${trailing || eol}`;
+  return text.slice(0, start) + insertion + text.slice(end);
+}
+
+// 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 edits = claimEdits(
+    item.status,
+    currentAgent,
+    agent,
+    item.frontmatter.has("prev_status"),
+    item.board && vault.childrenOf(item).some((child) => child.status === "doing")
+  );
+  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/children.ts
 function listChildren(vault, ref, options = {}) {
   const { status, recursive = false, archived = false } = options;
@@ -679,6 +885,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 +897,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 +910,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
@@ -802,7 +1011,14 @@ 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");
-  if (isRoot) {
+  const isArea2 = item.frontmatter.get("area") === true;
+  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 (isArea2 && rawStatus !== void 0) {
+    say("status-on-area", "error", "is an area and carries a status. Areas have no status; remove the status field.");
+  } else if (isRoot) {
     if (rawStatus !== void 0) {
       say(
         "status-on-root",
@@ -810,9 +1026,9 @@ function checkItem(item, vault, report) {
         `is a root and carries status "${rawStatus}". A root is not a card in anyone's column, so it takes no status.`
       );
     }
-  } else if (rawStatus === void 0) {
+  } else if (!isArea2 && rawStatus === void 0) {
     say("status-missing", "error", `has no status. Use one of: ${STATUSES.join(", ")}.`);
-  } else if (!isStatus(rawStatus)) {
+  } else if (!isArea2 && !isStatus(rawStatus)) {
     say(
       "status-invalid",
       "error",
@@ -952,7 +1168,7 @@ 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 { mkdir as mkdir2 } from "node:fs/promises";
 import { join as join4 } from "node:path";
 var TEMPLATES_FOLDER = "Templates";
 function listTemplates() {
@@ -960,7 +1176,7 @@ function listTemplates() {
 }
 async function writeTemplates(vault) {
   const folder = join4(vault.root, TEMPLATES_FOLDER);
-  await mkdir(folder, { recursive: true });
+  await mkdir2(folder, { recursive: true });
   const written = [];
   for (const template of TEMPLATES) {
     const path = join4(folder, `${template.name}.md`);
@@ -983,7 +1199,7 @@ async function writeTemplates(vault) {
 }
 
 // src/cli/commands/remove.ts
-import { mkdir as mkdir2, rename as rename2 } from "node:fs/promises";
+import { mkdir as mkdir3, rename as rename3 } from "node:fs/promises";
 import { existsSync as existsSync4 } from "node:fs";
 import { join as join5 } from "node:path";
 var TRASH = ".trash";
@@ -1030,8 +1246,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 mkdir3(join5(vault.root, TRASH), { recursive: true });
+      await rename3(target.path, join5(vault.root, ...trashedTo.split("/")));
     }
     removed.push({ item: target, trashedTo });
   }
@@ -1083,7 +1299,7 @@ async function archiveItem(vault, ref, undo) {
 // 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 { chmod, mkdir as mkdir4, readFile as readFile3, rm, writeFile as writeFile3 } from "node:fs/promises";
 import { dirname as dirname3, resolve } from "node:path";
 import { promisify } from "node:util";
 var run = promisify(execFile);
@@ -1132,8 +1348,8 @@ async function installHook(vault, entry, 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 mkdir4(dirname3(git.path), { recursive: true });
+  await writeFile3(git.path, hookBody(vault, entry), "utf8");
   await chmod(git.path, 493);
   return git.path;
 }
@@ -1144,29 +1360,226 @@ async function uninstallHook(vault) {
   return git.path;
 }
 
+// src/cli/commands/setup.ts
+import { cp, lstat, mkdir as mkdir5, readFile as readFile4, rename as rename4, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
+import { homedir as homedir2, platform } from "node:os";
+import { dirname as dirname4, join as join6, 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 join6(location.home, "Library", "Application Support", "obsidian", "obsidian.json");
+    case "linux":
+      return join6(location.home, ".config", "obsidian", "obsidian.json");
+    case "win32":
+      return join6(location.appData ?? join6(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 readFile4(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 readFile4(join6(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 readFile4(join6(destination, "SKILL.md"), "utf8").catch(() => null);
+      const expected = await readFile4(join6(source, "SKILL.md"), "utf8");
+      if (same === expected) return "already-installed";
+    }
+    await rm2(destination, { recursive: true, force: true });
+  }
+  await mkdir5(dirname4(destination), { recursive: true });
+  await cp(source, destination, { recursive: true, errorOnExist: true, force: false });
+  await writeFile4(join6(destination, MANAGED_MARKER), MANAGED_TEXT, "utf8");
+  return "installed";
+}
+async function writeDefaultVault(vault) {
+  const root = wiConfigDir();
+  const path = join6(root, "config.json");
+  let current = {};
+  try {
+    const parsed = JSON.parse(await readFile4(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 mkdir5(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 readFile4(join6(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 = [
+    join6(home, ".claude", "skills", "recursive-board"),
+    join6(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>]
   wi status <ref> <status>
+  wi claim <ref> --agent <name>
+  wi release <ref> --reason <text> [--where <branch-or-path>]
   wi move <ref> --to <ref>
   wi archive <ref> [--undo]
   wi rm <ref> [--recursive] [--dry-run]
-  wi children <ref> [--status <s>] [--tree] [--archived]
+  wi children [<ref>] [--status <s>] [--tree] [--archived]
   wi validate
   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.
 
@@ -1182,8 +1595,9 @@ Notes
   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 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.1";
+var VERSION = "0.2.0";
 var UsageError = class extends Error {
 };
 async function main(argv) {
@@ -1197,9 +1611,12 @@ 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" },
       vault: { type: "string" },
+      board: { type: "string" },
       tree: { type: "boolean", default: false },
       archived: { type: "boolean", default: false },
       undo: { type: "boolean", default: false },
@@ -1207,6 +1624,7 @@ async function main(argv) {
       "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 +1634,25 @@ 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 (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,6 +1660,10 @@ async function main(argv) {
       return runNew(vault, rest, values, json);
     case "status":
       return runStatus(vault, rest, json);
+    case "claim":
+      return runClaim(vault, rest, values, json);
+    case "release":
+      return runRelease(vault, rest, values, json);
     case "move":
       return runMove(vault, rest, values, json);
     case "archive":
@@ -1238,6 +1671,11 @@ async function main(argv) {
     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);
@@ -1251,10 +1689,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 +1708,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"]}".`);
@@ -1316,6 +1796,52 @@ async function runStatus(vault, rest, json) {
   }
   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 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.
+`);
+  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"] : "";
@@ -1395,6 +1921,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,
@@ -1410,7 +1944,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)}`);
@@ -1507,7 +2045,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}

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "recursive-board",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "wi: the CLI that owns every write into a Recursive Board vault",
   "author": "vic-cio",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vic-cio/recursive-board.git"
+  },
   "engines": {
     "node": ">=20.12"
   },
@@ -12,12 +16,14 @@
     "wi": "./dist/wi/wi.js"
   },
   "files": [
-    "dist/wi/"
+    "dist/wi/",
+    "skills/"
   ],
   "scripts": {
     "test": "npm run typecheck && node --test 'src/**/*.test.ts' 'scripts/**/*.test.ts'",
     "test:unit": "node --test 'src/**/*.test.ts' 'scripts/**/*.test.ts'",
     "fixture": "node scripts/fixture.ts",
+    "bench": "node scripts/bench.ts",
     "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.plugin.json",
     "wi": "node ./src/cli/wi.ts",
     "build": "node build/plugin.mjs && node build/wi.mjs",
@@ -33,6 +39,5 @@
     "esbuild": "^0.28.2",
     "obsidian": "^1.13.1",
     "typescript": "^5.9.3"
-  },
-  "repository": "https://github.com/vic-cio/recursive-board.git"
+  }
 }

package/skills/recursive-board/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: recursive-board
+description: Read and change work items in a Recursive Board vault through the `wi` CLI. Use when asked what is on a board, backlog or agenda; to add, tick, move, archive or remove a card; to break work into child items; or to take on and work a card. Also use whenever the working directory holds a `Boards/` folder or a `.wi.json` file.
+---
+
+# recursive-board
+
+A Recursive Board vault stores each work item as one Markdown file. `wi` owns work-item metadata
+and applies the same rules as the Obsidian plugin. Edit card body text directly when the workflow
+below calls for it.
+
+## Setup
+
+After installing the `recursive-board` npm package, run `wi setup` once. It copies this skill to
+both `~/.claude/skills/recursive-board/` and `~/.agents/skills/recursive-board/`, detects vaults
+from Obsidian's registry, and saves the selected default vault. Use `wi setup --vault <path>` to
+select a vault directly, or `wi setup --yes --vault <path>` for unattended setup. Setup keeps
+symlinked development installs and refuses to replace an unmanaged skill folder unless passed
+`--force`.
+
+## Before the first write
+
+If the vault root has an `AGENTS.md`, read it. The vault owner's rules there (what you may
+delete, how to name cards) take priority over this page.
+
+## Reaching the vault
+
+`wi` finds the vault in this order: `--vault <path>`, `$WI_VAULT`, the nearest folder above the
+working directory that holds `.wi.json` or `Boards/`, this Git repo's pointer, then
+`defaultVault` in `~/.config/wi/config.json` (or `$XDG_CONFIG_HOME/wi/config.json`). To set a
+repo pointer, run `wi here --vault <path> --board <ref>` once from that repo. It is stored in
+user config outside the repo, keyed by Git's common directory, so linked worktrees share it.
+Run `wi here` to print the current repo's pointer. With a pointer, `wi new` defaults to its board
+and `wi children` can omit the reference. Explicit `--parent` and `wi children <ref>` still work.
+
+`wi --help` is the full command reference. Read it for any flag this page does not name.
+
+## Reading
+
+A `<ref>` is an id (`wi-3k9p`), a filename, or a title. Use the id once you have it: it is exact
+and survives a rename.
+
+```bash
+wi children <root> --tree          # the whole tree under a root item
+wi children <ref>                  # one board, grouped by status
+wi children <ref> --status doing   # one column
+wi children                       # use the repo pointer's board
+```
+
+Add `--json` when you parse the result. A card's own text (objective, criteria, notes) is in
+its file in the work-item folder (`Boards/` by default). Read the file.
+
+## Writing
+
+```bash
+wi new "<title>" --parent <ref> [--status backlog] [--priority <n>]   # 1 is the highest
+wi status <ref> <backlog|options|doing|done>
+wi claim <ref> --agent <name>        # assign and move to doing in one write
+wi release <ref> --reason <text> [--where <branch-or-path>]
+wi move <ref> --to <new parent ref>
+wi archive <ref>                    # --undo reverses it
+wi rm <ref> --recursive --dry-run   # read what it lists, then run it without --dry-run
+```
+
+- Write a new title as an imperative phrase. It becomes the filename, so make it unique.
+- `wi new` writes the frontmatter and the template sections. Fill the body sections with a file
+  edit afterwards. Leave the frontmatter to `wi`.
+- To untick a done item, set it back to its `prev_status`.
+- A dispatcher claims cards from options for its workers. `wi claim` refuses a card claimed by a
+  different agent, a done card, or a board with a child in doing. A repeat by the same agent in
+  doing writes nothing.
+- When a worker stops, its dispatcher runs `wi release` with a reason and, when available, the
+  branch or worktree path. Release clears the agent, returns the card to options, and records the
+  continuation location in Notes.
+- Run `wi validate` after a batch of writes. Exit 0 is clean. Exit 1 lists what broke.
+
+## Working a card
+
+For `/recursive-board <card> <instruction>`, use the instruction to clarify the request and the
+card's Objective, Context and Acceptance Criteria as the brief:
+
+1. Resolve the vault and board from the repo map (`wi here`). If the repo has no entry, ask once
+   which board to use, then record it with `wi here --board <board> --vault <vault>`.
+2. Read the card body. If Objective or Acceptance Criteria is missing, write a proposed brief in
+   the card and ask for approval; wait before doing the work.
+3. Claim it with `wi claim <card> --agent <agent name>`. Work in the current repo on a new
+   `card/<slug>` branch. Run the repo's tests and commit the result.
+4. If the work is too large or cannot finish, stop with a split proposal or continuation note in
+   your report, then run `wi release <card> --reason <reason> --where <branch-or-path>`. Let the
+   dispatcher decide whether to create child cards.
+5. When finished, add one dated line under the card's Notes with the branch and result. Leave the
+   card in `doing` and stop for review. Do not merge or push; those wait for the owner's verdict.
+
+## Outcomes
+
+`wi` prints the change it made, for example `wi-3k9p  Write the release notes  doing → done`.
+Report that line to the user. A refusal (exit 2) names its reason. It is a rule doing its job:
+read it and change the approach. Do not work around it with a file tool.