@aisystemresources/emdee 0.2.0 → 0.3.0

package/.claude/commands/describe-image.md

@@ -0,0 +1,17 @@
+---
+name: describe-image
+description: Describe an EMDEE vault image doc and rename it from timestamp to semantic title.
+argument-hint: <vault-path>
+---
+
+Take the vault doc path from `$ARGUMENTS`. Run the emdee-describe-image skill workflow:
+
+1. `emdee get-image --doc-path $ARGUMENTS --remote --out /tmp/emdee-describe.jpg` — save the image locally
+2. Read the image visually and compose:
+   - A semantic title, 3-6 words, UPPERCASE-with-HYPHENS (e.g. `HANDSTAND-BALANCE-DRILL`)
+   - A one-line summary, 15-30 words
+3. `emdee rename-doc --old-path $ARGUMENTS --new-title <TITLE> --remote`
+4. Get the fresh preamble hash: `emdee get-doc --path <new-path> --remote --json`
+5. `emdee patch-preamble --path <new-path> --body "> <summary>" --expected-hash <hash> --remote`
+
+Report the before/after path + title + summary as a punch list at the end.

package/.claude/commands/summarise.md

@@ -0,0 +1,24 @@
+---
+name: summarise
+description: Refresh drifting doc summaries. Optional path prefix argument narrows the batch.
+argument-hint: [path-prefix]
+---
+
+Run the emdee-summariser skill's batch flow:
+
+1. `emdee list-summary-drift --remote --limit 20 --format text` (append `--prefix $ARGUMENTS` if the user provided one) → get up to 20 candidate paths
+2. For each path, `emdee get-doc --path <path> --remote --full --format text` → read the body
+3. Compose a fresh summary (15-40 words) that answers "what is this and why does it exist"
+4. Present all proposals as a punch list — do NOT patch yet:
+
+```
+<path>
+  Current: <old blockquote>
+  Proposed: <new blockquote>
+```
+
+5. Wait for the user's approval (per-doc or bulk). On approval:
+   - `emdee get-doc --path <path> --remote --json` → fetch preamble.content_hash
+   - `emdee patch-preamble --path <path> --body "> <new>" --expected-hash <hash> --remote`
+
+Never batch-patch without human review — image content is high-signal but the model can misread ambiguous shots.

package/.claude/commands/vault-status.md

@@ -0,0 +1,21 @@
+---
+name: vault-status
+description: Show a mini dashboard of the user's EMDEE vault — total docs + top 3 drifting summaries.
+---
+
+Run these commands via the Bash tool and present the results as a compact dashboard:
+
+1. `emdee list --remote | wc -l` → total doc count
+2. `emdee list-summary-drift --remote --limit 3 --format text` → top 3 drifting paths
+
+Format the output as:
+
+```
+Vault: <N> docs total, <M> with drifting summaries
+Top drift candidates:
+  - <path 1>
+  - <path 2>
+  - <path 3>
+```
+
+If `emdee list --remote` errors with "run login", tell the user to run `emdee login` first and stop.

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "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",
+  "author": {
+    "name": "AI System Resources",
+    "url": "https://emdee.tech"
+  },
+  "homepage": "https://emdee.tech",
+  "repository": "https://github.com/AISystemResources/emdee",
+  "license": "MIT",
+  "keywords": ["knowledge-graph", "markdown", "vault", "mcp", "claude"],
+  "mcpServers": {
+    "emdee": {
+      "type": "http",
+      "url": "https://emdee.tech/api/mcp"
+    }
+  },
+  "skills": "./skills"
+}

package/README.md

@@ -8,6 +8,23 @@ LLM agents need a stable, human-readable substrate to read and write their own c
 
 ## Install
 
+**Claude Code plugin (recommended — MCP + CLI + skills in one shot):**
+
+```bash
+claude plugin install @aisystemresources/emdee
+```
+
+This installs the CLI, wires up the emdee.tech MCP server, and drops in 4 auto-loading skills. Then:
+
+```bash
+emdee login                          # PKCE flow, opens browser
+emdee whoami                         # confirms your namespace
+```
+
+Slash commands available after install: `/vault-status`, `/describe-image <path>`, `/summarise [prefix]`.
+
+**CLI-only (no plugin, for scripting or non-Claude-Code use):**
+
 ```bash
 npm install -g @aisystemresources/emdee
 cd ~/my-vault
@@ -16,6 +33,8 @@ emdee list                           # your owner + 5 virtual system nodes
 emdee mcp                            # stdio MCP server — point Claude Code at it
 ```
 
+**claude.ai users:** the plugin doesn't apply (different install model). Use the connect panel on emdee.tech to add the HTTP MCP server directly.
+
 ## The 5-node OS layer
 
 Every Emdee vault has exactly 5 canonical top-level nodes, plus your owner node:

package/bin/emdee.js

@@ -664,4 +664,78 @@ program
     shellRead("list-summary-drift", opts, extra);
   });
 
+// -----------------------------------------------------------------------
+// Deferred parity gap closers (post-SPRINT-091): 4 remaining tool verbs.
+// -----------------------------------------------------------------------
+
+program
+  .command("get-image")
+  .description("Fetch an image doc's binary. Default output prints metadata JSON; --out writes decoded bytes to file.")
+  .requiredOption("--doc-path <path>", "Path to the image doc (e.g. images/PHOTO-...md)")
+  .option("--out <path>", "Write the decoded image bytes to this file")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Pretty-print metadata")
+  .action((opts) => {
+    const outResolved = opts.out ? path.resolve(process.cwd(), opts.out) : "";
+    const extra = ["--doc-path", opts.docPath];
+    if (outResolved) extra.push("--out", outResolved);
+    if (opts.remote) extra.push("--remote");
+    if (opts.json) extra.push("--json");
+    shellRead("get-image", opts, extra);
+  });
+
+program
+  .command("distill-doc")
+  .description("Read-only intake for split planning: returns section boundaries + rubric-quoted vault context.")
+  .requiredOption("--path <path>", "Doc to distill")
+  .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("distill-doc", opts, extra);
+  });
+
+program
+  .command("materialize-subgroup")
+  .description("Promote an H3 subgroup inside a doc's Parent of into a real intermediate parent doc.")
+  .requiredOption("--source-path <path>", "Source doc holding the subgroup")
+  .requiredOption("--subgroup-heading <heading>", "H3 heading text (without ###)")
+  .option("--new-doc-title <title>", "Override the derived new doc title")
+  .option("--new-doc-path <path>", "Override the derived new doc path")
+  .option("--summary <text>", "Blockquote summary for the new intermediate")
+  .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, {
+      sourcePath: "--source-path", subgroupHeading: "--subgroup-heading",
+      newDocTitle: "--new-doc-title", newDocPath: "--new-doc-path",
+      summary: "--summary", remote: "--remote", json: "--json",
+    });
+    shellWrite("materialize-subgroup", opts, extra);
+  });
+
+program
+  .command("split-doc")
+  .description("Atomically refactor a doc into concept nodes. Extracts array read from a JSON file.")
+  .requiredOption("--source-path <path>", "Source doc being split")
+  .requiredOption("--rewrite-source-content <text>", "New markdown for the source (with wiki-links to extracts)")
+  .requiredOption("--extracts-file <path>", 'JSON file: [{"path":"<new>.md","content":"<md>"}, ...]')
+  .option("-d, --docs <dir>", "docs directory (local mode)")
+  .option("--remote", "Route through emdee.tech")
+  .option("--json", "Machine-parseable output")
+  .action((opts) => {
+    const extractsResolved = path.resolve(process.cwd(), opts.extractsFile);
+    const extra = argsFromOpts(opts, {
+      sourcePath: "--source-path",
+      rewriteSourceContent: "--rewrite-source-content",
+      remote: "--remote", json: "--json",
+    });
+    extra.push("--extracts-file", extractsResolved);
+    shellWrite("split-doc", opts, extra);
+  });
+
 program.parseAsync();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aisystemresources/emdee",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local-first document management with markdown rendering, knowledge graph, and MCP server.",
   "type": "module",
   "bin": {
@@ -36,6 +36,8 @@
     "src/mcp/",
     "skills/",
     "templates/",
+    ".claude-plugin/",
+    ".claude/commands/",
     "README.md"
   ],
   "dependencies": {

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 { getImage } from "../lib/mcp/tools/get_image";
+import { writeFileSync } from "node:fs";
 
 const docsDir = path.resolve(process.env.EMDEE_DOCS ?? path.join(process.cwd(), "docs"));
 
@@ -273,14 +275,59 @@ async function cmdDriftBatch(argv: string[]): Promise<void> {
   }
 }
 
+// get-image needs a bespoke handler: the tool returns a two-part content
+// block (text metadata + image data). Default output is the metadata JSON;
+// with --out, decode the base64 and write the binary to a file.
+async function cmdGetImage(argv: string[]): Promise<void> {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      "doc-path": { type: "string" },
+      out: { type: "string" },
+      remote: { type: "boolean" },
+      json: { type: "boolean" },
+    },
+    strict: true,
+  });
+  const docPath = asString(values["doc-path"]);
+  if (!docPath) {
+    process.stderr.write("get-image: --doc-path required\n");
+    process.exit(1);
+  }
+  const args = { doc_path: docPath };
+  const result = values.remote
+    ? await callTool("get_image", args)
+    : await (getImage as unknown as ToolFn)({ mode: "local", docsDir }, args);
+
+  const content = (result as { content?: Array<{ type: string; text?: string; data?: string; mimeType?: string }> }).content ?? [];
+  const meta = content.find((c) => c.type === "text");
+  const image = content.find((c) => c.type === "image");
+  const metaParsed = meta?.text ? JSON.parse(meta.text) : {};
+
+  if (image?.data && values.out) {
+    const outPath = path.resolve(values.out);
+    writeFileSync(outPath, Buffer.from(image.data, "base64"));
+    process.stdout.write(`Saved ${image.data.length} base64 bytes (${image.mimeType}) to ${outPath}\n`);
+    return;
+  }
+
+  const payload = {
+    ...metaParsed,
+    mime_type: image?.mimeType,
+    size_bytes: image?.data ? Buffer.from(image.data, "base64").byteLength : 0,
+  };
+  process.stdout.write(JSON.stringify(payload, null, values.json ? 2 : 0) + "\n");
+}
+
 const [, , sub, ...rest] = process.argv;
 
 async function main(): Promise<void> {
   if (sub === "list") return cmdList(rest);
   if (sub === "drift-batch") return cmdDriftBatch(rest);
+  if (sub === "get-image") return cmdGetImage(rest);
   if (sub && READ_VERBS[sub]) return runStructuredRead(sub, rest);
   process.stderr.write(`unknown read subcommand: ${sub ?? "(none)"}\n`);
-  process.stderr.write(`verbs: list, drift-batch, ${Object.keys(READ_VERBS).join(", ")}\n`);
+  process.stderr.write(`verbs: list, drift-batch, get-image, ${Object.keys(READ_VERBS).join(", ")}\n`);
   process.exit(1);
 }
 

package/src/cli/write-commands.ts

@@ -25,6 +25,10 @@ import { writeDocPreview } from "../lib/mcp/tools/write_doc_preview";
 import { trashDoc } from "../lib/mcp/tools/trash_doc";
 import { restoreDoc } from "../lib/mcp/tools/restore_doc";
 import { deleteDoc } from "../lib/mcp/tools/delete_doc";
+import { distillDoc } from "../lib/mcp/tools/distill_doc";
+import { materializeSubgroup } from "../lib/mcp/tools/materialize_subgroup";
+import { splitDoc } from "../lib/mcp/tools/split_doc";
+import { readFileSync } from "node:fs";
 import { callTool, unwrapText } from "./remote-client";
 import { NeedsLoginError } from "./auth";
 
@@ -286,6 +290,63 @@ const VERBS: Record<string, VerbSpec> = {
     parse: { ...COMMON, path: { type: "string" } },
     buildArgs: (v) => ({ path: asString(v.path) }),
   },
+  "distill-doc": {
+    // READ-ONLY intake for split planning — lives under write commands
+    // alongside its executor split_doc so users find them together.
+    toolName: "distill_doc",
+    toolFn: distillDoc as unknown as ToolFn,
+    parse: { ...COMMON, path: { type: "string" } },
+    buildArgs: (v) => ({ path: asString(v.path) }),
+  },
+  "materialize-subgroup": {
+    toolName: "materialize_subgroup",
+    toolFn: materializeSubgroup as unknown as ToolFn,
+    parse: {
+      ...COMMON,
+      "source-path": { type: "string" },
+      "subgroup-heading": { type: "string" },
+      "new-doc-title": { type: "string" },
+      "new-doc-path": { type: "string" },
+      summary: { type: "string" },
+    },
+    buildArgs: (v) => {
+      const args: Record<string, unknown> = {
+        source_path: asString(v["source-path"]),
+        subgroup_heading: asString(v["subgroup-heading"]),
+      };
+      const t = optionalString(v["new-doc-title"]);
+      if (t) args.new_doc_title = t;
+      const p = optionalString(v["new-doc-path"]);
+      if (p) args.new_doc_path = p;
+      const s = optionalString(v.summary);
+      if (s) args.summary = s;
+      return args;
+    },
+  },
+  "split-doc": {
+    toolName: "split_doc",
+    toolFn: splitDoc as unknown as ToolFn,
+    parse: {
+      ...COMMON,
+      "source-path": { type: "string" },
+      "rewrite-source-content": { type: "string" },
+      // Extracts is a complex array-of-objects; take it via --extracts-file
+      // pointing at a JSON document rather than shoehorn it into a flag.
+      "extracts-file": { type: "string" },
+    },
+    buildArgs: (v) => {
+      const args: Record<string, unknown> = {
+        source_path: asString(v["source-path"]),
+        rewrite_source_content: asString(v["rewrite-source-content"]),
+      };
+      const extractsFile = optionalString(v["extracts-file"]);
+      if (extractsFile) {
+        const parsed = JSON.parse(readFileSync(extractsFile, "utf8"));
+        args.extracts = parsed;
+      }
+      return args;
+    },
+  },
 };
 
 function formatOutput(result: unknown, wantJson: boolean): string {

package/src/lib/supabase/oauth.ts

@@ -14,10 +14,10 @@ export async function registerClient(clientName: string | null, redirectUris: st
   return data.client_id;
 }
 
-export async function getClient(clientId: string): Promise<{ client_id: string; redirect_uris: string[] } | null> {
+export async function getClient(clientId: string): Promise<{ client_id: string; client_name: string | null; redirect_uris: string[] } | null> {
   const { data } = await adminClient()
     .from("oauth_clients")
-    .select("client_id, redirect_uris")
+    .select("client_id, client_name, redirect_uris")
     .eq("client_id", clientId)
     .maybeSingle();
   return data ?? null;