@aisystemresources/emdee 0.1.2 → 0.2.0

package/README.md

@@ -44,6 +44,38 @@ npm run mcp                            # stdio MCP server
 
 The web viewer (`emdee start`, `emdee serve-next`) is repo-only — it needs the Next.js `app/` tree that isn't in the published tarball. `init`, `list`, `drift-batch`, `mcp` all work from the global install.
 
+## Claude Code skills
+
+The package ships a set of `.md` skill files under `skills/` that teach Claude Code the vault conventions + workflows. Install them into your Claude Code skills directory:
+
+```bash
+emdee skills-install
+```
+
+This copies:
+
+- **emdee-conventions** — always-loaded; teaches Claude the 5-node OS layer, doc shape, edge discipline, tool selection (CLI vs MCP), path conventions. Loading this once means Claude writes correctly to the vault the first time in every session.
+- **emdee-describe-image** — auto-triggers on IMAGES/ docs with `_description pending_` summary. Runs the 4-step get-image → rename-doc → patch-preamble workflow.
+- **emdee-summariser** — batch-refresh drifting doc summaries via `list-summary-drift`.
+- **emdee-onboarder** — walks a new user from `emdee init` through their first project doc + connecting to Claude.
+
+Re-run `emdee skills-install` after upgrading the package to pick up updated skill content.
+
+## CLI
+
+Every MCP tool has a matching `emdee <verb>` CLI command. Same guards, same errors, same semantics — 3–40× cheaper in tokens because the JSON-RPC envelope is skipped. Everything supports `--remote` (routes through emdee.tech via `POST /api/mcp`) or defaults local.
+
+```bash
+emdee login                                     # PKCE flow, saves creds to ~/.config/emdee/
+emdee whoami
+emdee list --remote                             # your live vault paths
+emdee get-doc --path VAULT.md --full --remote   # full markdown
+emdee create-child --parent-path VAULT.md --title "MY-PROJECT" --remote
+emdee patch-section --path X --heading Notes --body "..." --expected-hash <hash> --remote
+```
+
+Full verb list via `emdee --help`. Auth commands: `login`, `logout`, `whoami`. Reads: `get-doc`, `get-summary`, `get-neighbors`, `get-context`, `search`, `read-doc-section`, `list-docs`, `list-summary-drift`, `list`, `drift-batch`. Writes: `patch-section`, `append-section`, `append-doc`, `patch-preamble`, `write-doc`, `write-doc-preview`, `create-child`, `add-association`, `move-doc`, `rename-doc`, `trash-doc`, `restore-doc`, `delete-doc`.
+
 ## MCP tools
 
 The stdio server (`emdee mcp`) exposes 18 tools.

package/bin/emdee.js

@@ -159,13 +159,15 @@ program
 
 program
   .command("list")
-  .description("Print one doc path per line (token-cheap; local docs/ only)")
-  .option("-d, --docs <dir>", "docs directory", "docs")
+  .description("Print one doc path per line. Local by default; --remote reads your live vault via emdee.tech.")
+  .option("-d, --docs <dir>", "docs directory (local mode)", "docs")
   .option("--prefix <prefix>", "filter to paths starting with this prefix")
+  .option("--remote", "route through emdee.tech (requires `emdee login`)")
   .action((opts) => {
     const docs = path.resolve(process.cwd(), opts.docs);
     const args = ["tsx", path.join(pkgRoot, "src/cli/read-commands.ts"), "list"];
     if (opts.prefix) args.push("--prefix", opts.prefix);
+    if (opts.remote) args.push("--remote");
     const child = spawn("npx", args, {
       cwd: pkgRoot,
       stdio: "inherit",
@@ -177,10 +179,11 @@ program
 program
   .command("drift-batch")
   .description("Print a batch of docs (path + summary + body) for offline summariser workflows")
-  .option("-d, --docs <dir>", "docs directory", "docs")
+  .option("-d, --docs <dir>", "docs directory (local mode)", "docs")
   .option("--limit <n>", "docs per batch", "10")
   .option("--offset <k>", "skip the first K docs", "0")
   .option("--prefix <prefix>", "filter to paths starting with this prefix")
+  .option("--remote", "route through emdee.tech (requires `emdee login`)")
   .action((opts) => {
     const docs = path.resolve(process.cwd(), opts.docs);
     const args = [
@@ -191,6 +194,7 @@ program
       "--offset", opts.offset,
     ];
     if (opts.prefix) args.push("--prefix", opts.prefix);
+    if (opts.remote) args.push("--remote");
     const child = spawn("npx", args, {
       cwd: pkgRoot,
       stdio: "inherit",
@@ -199,4 +203,465 @@ program
     child.on("exit", (code) => process.exit(code ?? 0));
   });
 
+// SPRINT-091: PKCE login against emdee.tech. Credentials stashed in
+// ~/.config/emdee/credentials.json for `--remote` calls to pick up.
+function shellAuth(sub, extra = []) {
+  const child = spawn(
+    "npx",
+    ["tsx", path.join(pkgRoot, "src/cli/auth-commands.ts"), sub, ...extra],
+    { cwd: pkgRoot, stdio: "inherit", env: { ...process.env } },
+  );
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+// SPRINT-091 chunk 2: write verbs shell through the dispatcher.
+function shellWrite(verb, opts, extra = []) {
+  const docs = opts.docs ? path.resolve(process.cwd(), opts.docs) : path.join(process.cwd(), "docs");
+  const child = spawn(
+    "npx",
+    ["tsx", path.join(pkgRoot, "src/cli/write-commands.ts"), verb, ...extra],
+    { cwd: pkgRoot, stdio: "inherit", env: { ...process.env, EMDEE_DOCS: docs } },
+  );
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+// SPRINT-091 chunk 3: structured read verbs share read-commands.ts dispatcher.
+function shellRead(verb, opts, extra = []) {
+  const docs = opts.docs ? path.resolve(process.cwd(), opts.docs) : path.join(process.cwd(), "docs");
+  const child = spawn(
+    "npx",
+    ["tsx", path.join(pkgRoot, "src/cli/read-commands.ts"), verb, ...extra],
+    { cwd: pkgRoot, stdio: "inherit", env: { ...process.env, EMDEE_DOCS: docs } },
+  );
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+// Every write verb takes the same core flag surface; a small helper builds
+// the extra-args array from commander's parsed opts + a spec of which flags
+// map to which write-commands.ts flag names.
+function argsFromOpts(opts, mapping) {
+  const extra = [];
+  for (const [optKey, cliFlag] of Object.entries(mapping)) {
+    const v = opts[optKey];
+    if (Array.isArray(v)) {
+      for (const item of v) extra.push(cliFlag, item);
+    } else if (typeof v === "string" && v.length > 0) {
+      extra.push(cliFlag, v);
+    } else if (v === true) {
+      extra.push(cliFlag);
+    }
+  }
+  return extra;
+}
+
+program
+  .command("login")
+  .description("Sign in to emdee.tech via browser (PKCE). Stashes tokens in ~/.config/emdee/.")
+  .option("--host <url>", "override the cloud host (defaults to $EMDEE_CLOUD_URL or https://emdee.tech)")
+  .action((opts) => {
+    const extra = opts.host ? ["--host", opts.host] : [];
+    shellAuth("login", extra);
+  });
+
+program
+  .command("logout")
+  .description("Remove stored credentials.")
+  .action(() => shellAuth("logout"));
+
+program
+  .command("whoami")
+  .description("Print the currently logged-in email + namespace.")
+  .action(() => shellAuth("whoami"));
+
+// SPRINT-094: install the EMDEE Claude Code skills into ~/.claude/skills/
+program
+  .command("skills-install")
+  .description("Copy packaged skills/*.md into a Claude Code skills directory (default ~/.claude/skills/).")
+  .option("--dir <path>", "Target directory")
+  .action((opts) => {
+    // Resolve --dir against the user's original cwd (not pkgRoot). We resolve
+    // here in the shell so the child process sees an absolute path regardless
+    // of where tsx runs from.
+    const resolvedDir = opts.dir ? path.resolve(process.cwd(), opts.dir) : "";
+    const extra = resolvedDir ? ["--dir", resolvedDir] : [];
+    const child = spawn(
+      "npx",
+      ["tsx", path.join(pkgRoot, "src/cli/skills-install.ts"), ...extra],
+      { cwd: pkgRoot, stdio: "inherit", env: { ...process.env } },
+    );
+    child.on("exit", (code) => process.exit(code ?? 0));
+  });
+
+// -----------------------------------------------------------------------
+// SPRINT-091 chunk 2: write-side CLI verbs.
+// Each mirrors the corresponding MCP tool. --remote routes through cloud;
+// --json returns the raw MCP envelope for machine consumption.
+// -----------------------------------------------------------------------
+
+program
+  .command("patch-section")
+  .description("Replace an H2 section's body — version-guarded. Same shape as the patch_section MCP tool.")
+  .requiredOption("--path <path>", "Vault doc path")
+  .requiredOption("--body <text>", "New section body")
+  .requiredOption("--expected-hash <hash>", "Prior content_hash from get_doc")
+  .option("--section-id <id>", "Section id (preferred over --heading)")
+  .option("--heading <heading>", "H2 heading text (without ##)")
+  .option("--gate-on <code...>", "Lint codes to hard-block on")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      path: "--path", body: "--body", expectedHash: "--expected-hash",
+      sectionId: "--section-id", heading: "--heading", gateOn: "--gate-on",
+      remote: "--remote", json: "--json",
+    });
+    shellWrite("patch-section", opts, extra);
+  });
+
+program
+  .command("append-section")
+  .description("Append markdown to the end of an existing H2 section. --create-if-missing adds it at end of file.")
+  .requiredOption("--path <path>", "Vault doc path")
+  .requiredOption("--body <text>", "Content to append")
+  .option("--section-id <id>", "Section id (preferred over --heading)")
+  .option("--heading <heading>", "H2 heading text (without ##)")
+  .option("--create-if-missing", "Create the section at end of file if not found")
+  .option("--gate-on <code...>", "Lint codes to hard-block on")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      path: "--path", body: "--body", sectionId: "--section-id",
+      heading: "--heading", createIfMissing: "--create-if-missing",
+      gateOn: "--gate-on", remote: "--remote", json: "--json",
+    });
+    shellWrite("append-section", opts, extra);
+  });
+
+program
+  .command("append-doc")
+  .description("Append to the end of a doc (after every section). Ideal for LOGS, daily notes.")
+  .requiredOption("--path <path>", "Vault doc path")
+  .requiredOption("--body <text>", "Content to append")
+  .option("--gate-on <code...>", "Lint codes to hard-block on")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      path: "--path", body: "--body", gateOn: "--gate-on",
+      remote: "--remote", json: "--json",
+    });
+    shellWrite("append-doc", opts, extra);
+  });
+
+program
+  .command("patch-preamble")
+  .description("Replace the region between H1 and first H2 (blockquote summary + intro paragraphs).")
+  .requiredOption("--path <path>", "Vault doc path")
+  .requiredOption("--body <text>", "New preamble body")
+  .requiredOption("--expected-hash <hash>", "Prior preamble content_hash from get_doc")
+  .option("--gate-on <code...>", "Lint codes to hard-block on")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      path: "--path", body: "--body", expectedHash: "--expected-hash",
+      gateOn: "--gate-on", remote: "--remote", json: "--json",
+    });
+    shellWrite("patch-preamble", opts, extra);
+  });
+
+program
+  .command("create-child")
+  .description("Atomic write + parent-of patch: create a new doc as child of an existing one.")
+  .requiredOption("--parent-path <path>", "Parent doc path")
+  .requiredOption("--title <title>", "New doc's H1 title")
+  .option("--body <text>", "Optional body appended after ## Notes")
+  .option("--summary <text>", "Optional blockquote summary (placeholder if omitted)")
+  .option("--child-path <path>", "Override the derived child path")
+  .option("--gate-on <code...>", "Lint codes to hard-block on")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      parentPath: "--parent-path", title: "--title", body: "--body",
+      summary: "--summary", childPath: "--child-path", gateOn: "--gate-on",
+      remote: "--remote", json: "--json",
+    });
+    shellWrite("create-child", opts, extra);
+  });
+
+program
+  .command("add-association")
+  .description("Atomic two-sided assoc patch. Hard-refuses hierarchy or sibling duplicates.")
+  .requiredOption("--a-path <path>", "First doc path")
+  .requiredOption("--b-path <path>", "Second doc path")
+  .option("--label <text>", "Shared label on both bullets")
+  .option("--gate-on <code...>", "Lint codes to hard-block on")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      aPath: "--a-path", bPath: "--b-path", label: "--label",
+      gateOn: "--gate-on", remote: "--remote", json: "--json",
+    });
+    shellWrite("add-association", opts, extra);
+  });
+
+program
+  .command("move-doc")
+  .description("Atomic reparent: three-side edge update (child's Child of + both parents' Parent of).")
+  .requiredOption("--path <path>", "Child doc to reparent")
+  .requiredOption("--new-parent-path <path>", "New parent doc")
+  .option("--old-parent-path <path>", "Old parent (required if child has multiple Child of bullets)")
+  .option("--position <n>", "0-indexed position in new parent's Parent of")
+  .option("--gate-on <code...>", "Lint codes to hard-block on")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      path: "--path", newParentPath: "--new-parent-path",
+      oldParentPath: "--old-parent-path", position: "--position",
+      gateOn: "--gate-on", remote: "--remote", json: "--json",
+    });
+    shellWrite("move-doc", opts, extra);
+  });
+
+program
+  .command("rename-doc")
+  .description("Rewrite H1, move file, update every [[old_title]] wiki-link across the vault. DESTRUCTIVE.")
+  .requiredOption("--old-path <path>", "Existing doc path")
+  .requiredOption("--new-title <title>", "New H1 title")
+  .option("--new-path <path>", "Override the derived new path")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      oldPath: "--old-path", newTitle: "--new-title", newPath: "--new-path",
+      remote: "--remote", json: "--json",
+    });
+    shellWrite("rename-doc", opts, extra);
+  });
+
+// -----------------------------------------------------------------------
+// SPRINT-091 chunk 3: full-file writes + lifecycle.
+// -----------------------------------------------------------------------
+
+program
+  .command("write-doc")
+  .description("Create or overwrite an entire doc. DESTRUCTIVE — always run write-doc-preview first.")
+  .requiredOption("--path <path>", "Vault doc path")
+  .requiredOption("--content <text>", "Full markdown content")
+  .option("--gate-on <code...>", "Lint codes to hard-block on")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      path: "--path", content: "--content", gateOn: "--gate-on",
+      remote: "--remote", json: "--json",
+    });
+    shellWrite("write-doc", opts, extra);
+  });
+
+program
+  .command("write-doc-preview")
+  .description("Diff + list of sections that would be removed by write-doc. Always call before write-doc.")
+  .requiredOption("--path <path>", "Vault doc path")
+  .requiredOption("--content <text>", "Proposed full markdown content")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      path: "--path", content: "--content",
+      remote: "--remote", json: "--json",
+    });
+    shellWrite("write-doc-preview", opts, extra);
+  });
+
+program
+  .command("trash-doc")
+  .description("Sidecar-based soft delete. Restore is lossless (edges preserved).")
+  .requiredOption("--path <path>", "Vault doc path")
+  .option("--original-parent-path <path>", "Override the auto-derived restore target")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      path: "--path", originalParentPath: "--original-parent-path",
+      remote: "--remote", json: "--json",
+    });
+    shellWrite("trash-doc", opts, extra);
+  });
+
+program
+  .command("restore-doc")
+  .description("Reverse a previous trash-doc. Edges were never touched.")
+  .requiredOption("--path <path>", "Vault doc path")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, { path: "--path", remote: "--remote", json: "--json" });
+    shellWrite("restore-doc", opts, extra);
+  });
+
+program
+  .command("delete-doc")
+  .description("Permanently remove a doc. NO UNDO. Returns inbound_edges + title_conflicts.")
+  .requiredOption("--path <path>", "Vault doc path")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, { path: "--path", remote: "--remote", json: "--json" });
+    shellWrite("delete-doc", opts, extra);
+  });
+
+// -----------------------------------------------------------------------
+// SPRINT-091 chunk 3: structured reads (get-doc, get-summary, get-neighbors,
+// get-context, search, read-doc-section, list-docs, list-summary-drift).
+// -----------------------------------------------------------------------
+
+program
+  .command("get-doc")
+  .description("Fetch a doc's envelope (title + summary + preamble + section headings). Pass --full for the body.")
+  .requiredOption("--path <path>", "Vault doc path")
+  .option("--full", "Include the full markdown body")
+  .option("--format <fmt>", "text | json (default text for --full)")
+  .option("--expected-hash <hash>", "Short-circuit if focal unchanged")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      path: "--path", full: "--full", format: "--format",
+      expectedHash: "--expected-hash", remote: "--remote", json: "--json",
+    });
+    shellRead("get-doc", opts, extra);
+  });
+
+program
+  .command("get-summary")
+  .description("Return {path, title, summary} for one doc — cheapest way to preview.")
+  .requiredOption("--path <path>", "Vault doc path")
+  .option("--format <fmt>", "text | json")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      path: "--path", format: "--format", remote: "--remote", json: "--json",
+    });
+    shellRead("get-summary", opts, extra);
+  });
+
+program
+  .command("get-neighbors")
+  .description("Return the doc + 1-hop neighbours categorised by relationship type.")
+  .requiredOption("--path <path>", "Vault doc path")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, { path: "--path", remote: "--remote", json: "--json" });
+    shellRead("get-neighbors", opts, extra);
+  });
+
+program
+  .command("get-context")
+  .description("Return the focal doc + multi-hop neighbourhood within a token budget.")
+  .requiredOption("--path <path>", "Vault doc path")
+  .option("--hops <n>", "Max BFS depth (1-3, default 2)")
+  .option("--budget-tokens <n>", "Rough token cap (default 8000)")
+  .option("--include-full", "Inline focal + hop-1 bodies")
+  .option("--include-associates", "Include assoc edges in the walk")
+  .option("--expected-hash <hash>", "Short-circuit if focal unchanged")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      path: "--path", hops: "--hops", budgetTokens: "--budget-tokens",
+      includeFull: "--include-full", includeAssociates: "--include-associates",
+      expectedHash: "--expected-hash", remote: "--remote", json: "--json",
+    });
+    shellRead("get-context", opts, extra);
+  });
+
+program
+  .command("search")
+  .description("Case-insensitive substring match over titles, summaries, content.")
+  .requiredOption("--query <text>", "Search query")
+  .option("--limit <n>", "Max results (default 10)")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      query: "--query", limit: "--limit", remote: "--remote", json: "--json",
+    });
+    shellRead("search", opts, extra);
+  });
+
+program
+  .command("read-doc-section")
+  .description("Read one H2 section's body without paying for the whole doc.")
+  .requiredOption("--path <path>", "Vault doc path")
+  .option("--section-id <id>", "Section id (preferred over --heading)")
+  .option("--heading <heading>", "H2 heading text (without ##)")
+  .option("--expected-hash <hash>", "Short-circuit if unchanged")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      path: "--path", sectionId: "--section-id", heading: "--heading",
+      expectedHash: "--expected-hash", remote: "--remote", json: "--json",
+    });
+    shellRead("read-doc-section", opts, extra);
+  });
+
+program
+  .command("list-docs")
+  .description("Enumerate every doc in the vault. Structured (vs `list` which is bytes-only).")
+  .option("--format <fmt>", "text | json (default text)")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      format: "--format", remote: "--remote", json: "--json",
+    });
+    shellRead("list-docs", opts, extra);
+  });
+
+program
+  .command("list-summary-drift")
+  .description("Return paths whose body has drifted since their summary was last authored.")
+  .option("--prefix <p>", "Path prefix filter")
+  .option("--limit <n>", "Max candidates (default 20)")
+  .option("--offset <k>", "Skip first N candidates")
+  .option("--format <fmt>", "text | json (default text)")
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extra = argsFromOpts(opts, {
+      prefix: "--prefix", limit: "--limit", offset: "--offset",
+      format: "--format", remote: "--remote", json: "--json",
+    });
+    shellRead("list-summary-drift", opts, extra);
+  });
+
 program.parseAsync();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aisystemresources/emdee",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Local-first document management with markdown rendering, knowledge graph, and MCP server.",
   "type": "module",
   "bin": {
@@ -34,6 +34,7 @@
     "src/lib/owner/",
     "src/lib/system-nodes.ts",
     "src/mcp/",
+    "skills/",
     "templates/",
     "README.md"
   ],

package/skills/emdee-conventions.md

@@ -0,0 +1,106 @@
+---
+name: emdee-conventions
+description: |
+  Use whenever reading or writing an EMDEE vault. Covers the 5-node OS layer,
+  doc shape (H1 + blockquote + relationship sections), edge discipline, tool
+  selection (CLI vs MCP, atomic multi-side writes), and path conventions
+  (UPPERCASE filenames, lowercase folders, hub-next-to-folder). Load this once
+  and every subsequent vault operation lands correctly the first time.
+---
+
+# EMDEE conventions — always-loaded
+
+You are working inside an Emdee vault. Every doc is plain markdown. Humans browse it through a Next.js renderer at [emdee.tech](https://emdee.tech); agents (Claude Code, Claude.ai, Cursor) read and write the same files through an MCP server OR the `emdee` CLI. The vault is the source of truth — anything you say must trace back to a file the user wrote.
+
+## The 5-node OS layer (virtual system nodes)
+
+Every vault has exactly 5 canonical top-level docs plus one owner node. **These 5 are virtual** — they appear in every read (`emdee list`, `get_doc`, MCP responses) without being on disk. Edit them and your version wins.
+
+| Node | Purpose |
+|---|---|
+| `EMDEE` | Vault root — everything's anchor |
+| `VAULT` | Private notes, projects, knowledge |
+| `SHARED` | Content shared into this vault by others (cloud only) |
+| `GRAVEYARD` | Archived / retired docs |
+| `IMAGES` | Images and visual assets |
+| `<YOUR-NAME>` | Personal subtree, one per user, uppercase |
+
+## Doc shape (universal)
+
+```md
+# TITLE
+
+> One-line blockquote summary — this is what routing sees.
+
+## Child of
+
+* [[PARENT]]
+
+## Parent of
+
+* [[CHILD1]]
+* [[CHILD2]]
+
+## Associated with
+
+* [[CROSS-TREE-NODE]] — optional prose about the link
+
+## Notes
+
+Freeform content.
+```
+
+Rules the lint enforces (see `lint_doc(path)` or `emdee patch-section --gate-on <code>`):
+
+- **One parent per doc.** `## Child of` should have exactly one bullet. Multiple parents → demote secondaries to `## Associated with`.
+- **No sibling associations.** Docs that share a parent are already related through it. `## Associated with` is for cross-tree links (project↔person, sprint↔learning).
+- **Reciprocal edges.** If A's `## Parent of` lists `[[B]]`, B's `## Child of` must list `[[A]]`. Asymmetric edges fire `asymmetric_parent_edge` / `asymmetric_child_edge` warnings.
+- **First wiki-link = declared edge.** `* [[TARGET]] — prose about the link`. The bullet's leading link is the edge; other links in the bullet are inline mentions only.
+- **Sibling order is derived, never declared.** `get_neighbors` returns `prev_sibling` / `next_sibling` computed from the parent's `## Parent of` order. Do NOT add `[[next-node]]` / `[[prev-node]]` bullets.
+
+## Path conventions
+
+- **Filenames UPPERCASE with HYPHENS:** `EDMUND.md`, `HANDSTAND-BALANCE-DRILL.md`. Never `edmund.md` or `handstandBalanceDrill.md`.
+- **Folders lowercase:** `edmund/personal/philosophy/CLARITY-IS-POWER.md`. Not `edmund/Personal/PHILOSOPHY/`.
+- **Hub sits next to folder.** `edmund/personal/PHILOSOPHY.md` (the hub) + `edmund/personal/philosophy/*` (the children). NOT `edmund/personal/philosophy/PHILOSOPHY.md`. The hub is a sibling of the folder it heads.
+
+## Tool selection
+
+Prefer CLI over MCP for token efficiency:
+
+```bash
+emdee list --remote                    # 40× cheaper than list_docs MCP call
+emdee get-doc --path X --remote --full # 3× cheaper than get_doc MCP call
+```
+
+All 16 tool verbs are available as `emdee <verb>`. Same guards, same errors, same semantics as the MCP tool of the same name (hyphenated). Everything supports `--remote` (cloud) or defaults local.
+
+For writes, always prefer the atomic multi-side variants over raw section patches:
+
+| Instead of… | Use… |
+|---|---|
+| Two `patch_section` calls (child's Child of + parent's Parent of) | `emdee create-child` |
+| Two `patch_section` calls on both docs' Associated with | `emdee add-association` |
+| Three `patch_section` calls to reparent | `emdee move-doc` |
+| Search+replace across every doc that references a title | `emdee rename-doc` |
+
+The atomic variants take care of edge discipline (hard-refuse on sibling-assoc-redundant, would-duplicate-hierarchy) and rollback semantics.
+
+For destructive full-file writes, always run `emdee write-doc-preview` first — `write-doc` silently drops any section not in the new payload.
+
+## Version-guarded writes
+
+Every destructive write (`patch-section`, `patch-preamble`, `move-doc`) requires `--expected-hash <hash>` from a prior read. Get it via `emdee get-doc --path X` (returns per-section content_hash + doc_content_hash). A stale hash returns `version_conflict` — refetch, reconcile, retry.
+
+## HARD RULES you'll trip if you're not careful
+
+1. **Any Supabase `.select()` reading > 1000 rows must paginate.** Use `.range(offset, offset + PAGE - 1)` in a loop. `.range()` alone doesn't lift the server-side 1000-row cap.
+2. **`patch_section` on a `## Child of` requires patching the new parent's `## Parent of` in the same turn.** Otherwise you leave an asymmetric edge. Or just use `move-doc`.
+3. **New / modified MCP tools require an e2e spec in the same PR.** Test the tool's behaviour end-to-end via a real `ToolContext` + temp filesystem.
+4. **Migrations touch `supabase/migrations/**` and are NEVER auto-merged.** Human review required.
+
+## When in doubt
+
+- `emdee lint-doc --path X` — surface every warning code the doc trips
+- `emdee get-doc --path X` — see current state including per-section hashes
+- Read the source of truth: `edmund/projects/emdee_os/LEARNINGS.md` in the vault