@aisystemresources/emdee 0.3.2 → 0.3.3

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "aisystemresources",
+  "owner": {
+    "name": "AI System Resources",
+    "url": "https://emdee.tech"
+  },
+  "plugins": [
+    {
+      "name": "emdee",
+      "source": "./",
+      "description": "A markdown knowledge graph shared by humans and their AI agents. Bundles the emdee.tech MCP server, the emdee CLI, and 4 Claude Code skills that teach vault conventions + workflows."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "emdee",
-  "displayName": "Emdee — Local-first knowledge graph",
-  "description": "Local-first knowledge graph backed by plain markdown. Bundles the emdee.tech MCP server, the emdee CLI, and 4 Claude Code skills that teach vault conventions + workflows.",
-  "version": "0.2.2",
+  "displayName": "Emdee — Markdown knowledge graph for humans and agents",
+  "description": "A markdown knowledge graph shared by humans and their AI agents. Bundles the emdee.tech MCP server, the emdee CLI, and 4 Claude Code skills that teach vault conventions + workflows.",
+  "version": "0.3.2",
   "author": {
     "name": "AI System Resources",
     "url": "https://emdee.tech"

package/bin/emdee.js

@@ -664,6 +664,33 @@ program
     shellRead("list-summary-drift", opts, extra);
   });
 
+program
+  .command("lint-doc")
+  .description("Audit one doc for quality defects (missing preamble, asymmetric edges, sibling assocs, etc).")
+  .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("lint-doc", opts, extra);
+  });
+
+program
+  .command("lint-vault")
+  .description("Batch-lint every doc in the vault. Returns aggregated warnings by code + per-doc punch list.")
+  .option("--prefix <p>", "Path prefix filter (scope to a subtree)")
+  .option("--limit <n>", "Max docs in the punch list (default: all)")
+  .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", remote: "--remote", json: "--json",
+    });
+    shellRead("lint-vault", opts, extra);
+  });
+
 // -----------------------------------------------------------------------
 // Deferred parity gap closers (post-SPRINT-091): 4 remaining tool verbs.
 // -----------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aisystemresources/emdee",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Local-first document management with markdown rendering, knowledge graph, and MCP server.",
   "type": "module",
   "bin": {

package/skills/emdee-conventions.md

@@ -2,19 +2,19 @@
 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.
+  doc shape (H1 + blockquote + relationship sections), edge discipline, CLI
+  tool selection (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.
+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); you read and write the same files through 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.
+Every vault has exactly 5 canonical top-level docs plus one owner node. **These 5 are virtual** — they appear in every read (`emdee list`, `emdee get-doc`, etc.) without being on disk. Edit them and your version wins.
 
 | Node | Purpose |
 |---|---|
@@ -50,13 +50,13 @@ Every vault has exactly 5 canonical top-level docs plus one owner node. **These
 Freeform content.
 ```
 
-Rules the lint enforces (see `lint_doc(path)` or `emdee patch-section --gate-on <code>`):
+Rules the lint enforces (see `emdee lint-doc --path X` 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.
+- **Sibling order is derived, never declared.** `emdee 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
 
@@ -66,22 +66,25 @@ Rules the lint enforces (see `lint_doc(path)` or `emdee patch-section --gate-on
 
 ## Tool selection
 
-Prefer CLI over MCP for token efficiency:
+Everything runs through the `emdee` CLI. `--remote` routes through the authenticated cloud vault at emdee.tech; omit for local mode.
 
 ```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
+emdee list --remote                    # top-level vault paths
+emdee get-doc --path X --remote --full # doc body + per-section hashes
+emdee search --query "keyword" --remote
 ```
 
-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.
+Reads: `list`, `list-docs`, `get-doc`, `get-summary`, `get-neighbors`, `get-context`, `read-doc-section`, `search`, `list-summary-drift`, `drift-batch`, `lint-doc`, `get-image`.
+
+Writes: `patch-section`, `patch-preamble`, `append-section`, `append-doc`, `create-child`, `add-association`, `move-doc`, `rename-doc`, `trash-doc`, `restore-doc`, `delete-doc`, `write-doc`, `write-doc-preview`, `distill-doc`, `materialize-subgroup`, `split-doc`.
 
 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` |
+| 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.
@@ -95,12 +98,12 @@ Every destructive write (`patch-section`, `patch-preamble`, `move-doc`) requires
 ## 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.
+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. **Any change to a tool's behaviour (CLI verb or MCP surface) requires an e2e spec in the same PR.** Test 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
+- `emdee lint-doc --path X --remote` — surface every warning code the doc trips
+- `emdee get-doc --path X --remote` — see current state including per-section hashes
+- Read the source of truth: `emdee get-doc --path "edmund/projects/emdee_os/LEARNINGS.md" --remote --full`

package/skills/emdee-describe-image.md

@@ -9,7 +9,7 @@ description: |
 
 # emdee-describe-image — rename + summarise uploaded images
 
-When you see an EMDEE image doc that hasn't been described yet, run this workflow. It uses the existing `get_image` + `rename_doc` + `patch_preamble` MCP tools (or their `emdee` CLI equivalents) — no new server-side dependencies.
+When you see an EMDEE image doc that hasn't been described yet, run this workflow. Pure `emdee` CLI — no MCP calls. Every command routes through the authenticated cloud vault via `--remote`.
 
 ## Trigger patterns
 
@@ -22,17 +22,11 @@ Any vault doc where:
 
 ### 1. Read the image
 
-```
-get_image(doc_path=<PATH>)
-```
-
-Or via CLI (when SPRINT-091 chunk 4 lands `get-image`):
-
-```
-emdee get-image --path <PATH> --remote
+```bash
+emdee get-image --doc-path <PATH> --out /tmp/img.png --remote
 ```
 
-The MCP tool returns the image as a visual content block — you can see it.
+Then read `/tmp/img.png` — you'll see it as a visual content block and can describe what's in it.
 
 ### 2. Compose
 
@@ -43,11 +37,11 @@ The MCP tool returns the image as a visual content block — you can see it.
 
 ### 3. Rename
 
-```
+```bash
 emdee rename-doc --old-path <PATH> --new-title <TITLE> --remote
 ```
 
-The tool atomically:
+Atomically:
 - Rewrites the H1
 - Moves the file (default: same folder, `<TITLE>.md`)
 - Updates every `[[<old title>]]` wiki-link across the vault
@@ -56,13 +50,13 @@ The tool atomically:
 
 Fetch the fresh preamble hash:
 
-```
+```bash
 emdee get-doc --path <NEW-PATH> --remote --json
 ```
 
 Take `preamble.content_hash` from the response, then:
 
-```
+```bash
 emdee patch-preamble --path <NEW-PATH> \
   --body "> <your 15-30 word summary>" \
   --expected-hash <hash> --remote
@@ -72,8 +66,8 @@ emdee patch-preamble --path <NEW-PATH> \
 
 If several images need describing:
 
-```
-emdee list-docs --prefix "IMAGES/" --remote | \
+```bash
+emdee list-docs --prefix "IMAGES/" --remote --format text | \
   xargs -I{} emdee get-summary --path {} --remote --format text
 ```
 
@@ -81,7 +75,7 @@ Filter for `_description pending_` in the output, then run the 4-step workflow p
 
 ## Failure modes
 
-- **Title collision** — `rename_doc` returns `title_conflict`. Pick a more specific title (add a subject qualifier).
+- **Title collision** — `rename-doc` returns `title_conflict`. Pick a more specific title (add a subject qualifier).
 - **`_description pending_` was already replaced** — someone else already ran this. `emdee get-doc` will show the new summary; skip.
 - **Image is illegible** — set the summary to `> Illegible / unable to describe from image alone.` and flag it in the user-facing report so they can annotate manually.
 

package/skills/emdee-onboarder.md

@@ -107,7 +107,7 @@ Load the conventions skill (if not already loaded) and let it take over.
 ## What to avoid
 
 - **Don't dump the full conventions in step 2.** The user is trying to see one thing work. Ship them from zero → seeing their first graph node in under 5 minutes. Depth comes after.
-- **Don't force `create_child` before they know what to create.** The step-3 question ("what do you want to track first?") is critical. If they say "I don't know yet," don't create a doc — instead, suggest they browse [emdee.tech](https://emdee.tech) in incognito to see the public demo vault. Come back when they have an answer.
+- **Don't force `create-child` before they know what to create.** The step-3 question ("what do you want to track first?") is critical. If they say "I don't know yet," don't create a doc — instead, suggest they browse [emdee.tech](https://emdee.tech) in incognito to see the public demo vault. Come back when they have an answer.
 - **Don't reference SPRINTs / LOGS / LEARNINGS in onboarding.** Those are for later. Zero-to-one first.
 
 ## Success signal

package/skills/emdee-summariser.md

@@ -9,7 +9,7 @@ description: |
 
 # emdee-summariser — refresh drifting doc summaries
 
-Docs in EMDEE carry a one-line `> blockquote` summary right below the H1. That summary is what routing sees — search, `get_summary`, cheap enumeration all pivot on it. When the body drifts (new sections, refined framing, changed scope), the summary should catch up. This skill runs that refresh.
+Docs in EMDEE carry a one-line `> blockquote` summary right below the H1. That summary is what routing sees — `emdee search`, `emdee get-summary`, cheap enumeration all pivot on it. When the body drifts (new sections, refined framing, changed scope), the summary should catch up. This skill runs that refresh.
 
 ## Trigger patterns
 

package/src/cli/read-commands.ts

@@ -25,6 +25,8 @@ import { search } from "../lib/mcp/tools/search";
 import { readDocSection } from "../lib/mcp/tools/read_doc_section";
 import { listDocs } from "../lib/mcp/tools/list_docs";
 import { listSummaryDrift } from "../lib/mcp/tools/list_summary_drift";
+import { lintDoc } from "../lib/mcp/tools/lint_doc";
+import { lintVault } from "../lib/mcp/tools/lint_vault";
 import { getImage } from "../lib/mcp/tools/get_image";
 import { writeFileSync } from "node:fs";
 
@@ -175,6 +177,29 @@ const READ_VERBS: Record<string, ReadVerb> = {
       return args;
     },
   },
+  "lint-doc": {
+    toolName: "lint_doc",
+    toolFn: lintDoc as unknown as ToolFn,
+    parse: { ...COMMON, path: { type: "string" } },
+    buildArgs: (v) => ({ path: asString(v.path) }),
+  },
+  "lint-vault": {
+    toolName: "lint_vault",
+    toolFn: lintVault as unknown as ToolFn,
+    parse: {
+      ...COMMON,
+      prefix: { type: "string" },
+      limit: { type: "string" },
+    },
+    buildArgs: (v) => {
+      const args: Record<string, unknown> = {};
+      const prefix = optionalString(v.prefix);
+      if (prefix) args.prefix = prefix;
+      const limit = optionalString(v.limit);
+      if (limit) args.limit = Number(limit);
+      return args;
+    },
+  },
 };
 
 function formatReadOutput(result: unknown, wantJson: boolean): string {

package/src/lib/mcp/tools/index.ts

@@ -17,6 +17,7 @@ export { renameDoc } from "./rename_doc";
 export { patchPreamble } from "./patch_preamble";
 export { appendDoc } from "./append_doc";
 export { lintDoc } from "./lint_doc";
+export { lintVault } from "./lint_vault";
 export { distillDoc } from "./distill_doc";
 export { createChild } from "./create_child";
 export { addAssociation } from "./add_association";

package/src/lib/mcp/tools/lint_vault.ts

@@ -0,0 +1,59 @@
+import { loadVaultIndex } from "./vault";
+import { lintDocContent, type LintWarning } from "./lint";
+import { buildLintVaultContext } from "./lint_doc";
+import type { ToolContext } from "./types";
+
+// SPRINT-101: batch lint the caller's entire vault in one shot.
+//
+// Reuses the vault index's in-memory `content` (already fetched by
+// `loadVaultIndex`) so we run every per-doc + cross-doc rule without a
+// single extra Storage/cache round-trip. On a ~1500-doc vault this is
+// milliseconds, not seconds.
+//
+// Response shape:
+//   { scanned, with_warnings, warnings_by_code, docs: [{path, warnings[]}] }
+//
+// Prefix filter is optional — pass `prefix: "edmund/projects/emdee_os/"`
+// to lint a subtree instead of the whole vault. Useful when a hygiene
+// pass is scoped to one area and you don't want a punch list of every
+// unrelated drift.
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+export async function lintVault(ctx: ToolContext, args: Record<string, unknown>): Promise<unknown> {
+  const prefix = typeof args.prefix === "string" && args.prefix.length > 0 ? args.prefix : null;
+  const limit = typeof args.limit === "number" && args.limit > 0 ? args.limit : null;
+
+  const index = await loadVaultIndex(ctx);
+
+  const perDoc: Array<{ path: string; warnings: LintWarning[] }> = [];
+  const byCode: Record<string, number> = {};
+  let scanned = 0;
+
+  for (const doc of index.docs) {
+    if (prefix && !doc.path.startsWith(prefix)) continue;
+    scanned++;
+    const lintCtx = buildLintVaultContext(index, doc.path);
+    const result = lintDocContent(doc.content, lintCtx);
+    if (result.warnings.length === 0) continue;
+    perDoc.push({ path: doc.path, warnings: result.warnings });
+    for (const w of result.warnings) {
+      byCode[w.code] = (byCode[w.code] ?? 0) + 1;
+    }
+  }
+
+  // Sort docs with most warnings first — top of the punch list is where
+  // the operator's attention buys the most cleanup per unit of effort.
+  perDoc.sort((a, b) => b.warnings.length - a.warnings.length);
+  const docs = limit ? perDoc.slice(0, limit) : perDoc;
+
+  return json({
+    scanned,
+    with_warnings: perDoc.length,
+    warnings_total: Object.values(byCode).reduce((a, b) => a + b, 0),
+    warnings_by_code: byCode,
+    docs,
+  });
+}

package/src/lib/storage/SupabaseStorage.ts

@@ -134,18 +134,28 @@ export class SupabaseStorage implements VaultStorage {
       if (!folder || folder.includes("/")) {
         return this.walkFolder(folder);
       }
-      const { data, error } = await adminClient()
-        .from(CACHE_TABLE)
-        .select("file_path, updated_at")
-        .eq("namespace", folder);
-      if (!error && data) {
-        return data.map((r) => ({
-          path: `${folder}/${r.file_path}`,
-          content: "",
-          updatedAt: r.updated_at as string,
-        }));
+      const admin = adminClient();
+      // HARD RULE 6: PostgREST caps `.select()` at 1000 rows server-side.
+      // Vaults > 1000 docs silently truncate without an explicit range loop.
+      const PAGE = 1000;
+      const rows: Array<{ file_path: string; updated_at: string }> = [];
+      for (let offset = 0; ; offset += PAGE) {
+        const { data, error } = await admin
+          .from(CACHE_TABLE)
+          .select("file_path, updated_at")
+          .eq("namespace", folder)
+          .order("file_path", { ascending: true })
+          .range(offset, offset + PAGE - 1);
+        if (error) return this.walkFolder(folder);
+        const page = (data ?? []) as Array<{ file_path: string; updated_at: string }>;
+        rows.push(...page);
+        if (page.length < PAGE) break;
       }
-      return this.walkFolder(folder);
+      return rows.map((r) => ({
+        path: `${folder}/${r.file_path}`,
+        content: "",
+        updatedAt: r.updated_at,
+      }));
     });
   }
 
@@ -186,13 +196,29 @@ export class SupabaseStorage implements VaultStorage {
       }
 
       const admin = adminClient();
-      const { data, error } = await admin
-        .from(CACHE_TABLE)
-        .select("file_path, content, updated_at")
-        .eq("namespace", folder);
+      // HARD RULE 6: PostgREST caps `.select()` at 1000 rows server-side.
+      // Vaults > 1000 docs silently truncate without an explicit range loop.
+      const PAGE = 1000;
+      const rows: Array<{ file_path: string; content: string; updated_at: string }> = [];
+      let queryError: unknown = null;
+      for (let offset = 0; ; offset += PAGE) {
+        const { data, error } = await admin
+          .from(CACHE_TABLE)
+          .select("file_path, content, updated_at")
+          .eq("namespace", folder)
+          .order("file_path", { ascending: true })
+          .range(offset, offset + PAGE - 1);
+        if (error) {
+          queryError = error;
+          break;
+        }
+        const page = (data ?? []) as Array<{ file_path: string; content: string; updated_at: string }>;
+        rows.push(...page);
+        if (page.length < PAGE) break;
+      }
 
-      if (!error && data && data.length > 0) {
-        return data.map((r) => ({
+      if (!queryError && rows.length > 0) {
+        return rows.map((r) => ({
           path: `${folder}/${r.file_path}`,
           content: r.content,
           updatedAt: r.updated_at,