@aisystemresources/emdee 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# Silent Mane
+
+Local-first knowledge graph backed by plain markdown. Humans browse it through a React renderer; agents (Claude, Cursor, Codex) read and write the same files through an MCP server. The vault is the source of truth — anything an LLM says traces back to a file you wrote.
+
+## Why
+
+LLM agents need a stable, human-readable substrate to read and write their own context over time. Most knowledge-graph tools are either built for humans (Obsidian) or built for agents (vector stores). Silent Mane is a single substrate for both: the markdown a human edits is the exact bytes an agent reads, with no hidden index, no parallel summaries, no schema gymnastics. Build up a working journal that survives across sessions.
+
+## Status
+
+Published on npm as `@aisystemresources/emdee`. The CLI (`emdee init`, `emdee mcp`, `emdee list`, `emdee drift-batch`) is globally installable; `emdee start` / `emdee serve-next` still require a repo checkout because they run the full Vite / Next viewer.
+
+## Install (consumer)
+
+```bash
+npm install -g @aisystemresources/emdee
+cd ~/my-vault
+emdee init --nickname "Your Name"      # writes ./docs/YOUR-NAME.md as the owner node
+emdee list                              # your owner + 5 virtual system nodes
+emdee mcp                               # stdio MCP server — point Claude Code / claude.ai at it
+```
+
+## Quick start (developer)
+
+```bash
+git clone https://github.com/elz-ming/silent-mane.git
+cd silent-mane
+npm install
+./bin/mane.js init      # seeds docs/ with the entry doc, conventions, and sample branch
+npm run dev             # Vite dev server with hot reload at http://localhost:5173
+npm run mcp             # MCP server over stdio (point Claude.ai / Cursor / Codex at it)
+```
+
+`mane init` lays down:
+
+- `docs/MANE.md` — vault entry point
+- `docs/VAULT.md` — meta-pillar grouping the system docs below
+- `docs/INFO.md` — conventions (filenames, relationships, writing format)
+- `docs/INSTRUCTIONS.md` — CEO operating protocol for cross-project agents
+- `docs/BRAIN.md` — cross-project distilled wisdom (always-loaded prior)
+- `docs/WORKFLOWS.md` — concrete procedures the vault runs
+- `docs/SAMPLE.md` + `docs/sample/` — pedagogical examples; delete with `rm -rf docs/sample/` once you've read them
+
+Set `SILENT_MANE_ENTRY=your-file.md` to override the default entry name.
+
+
+## MCP tools
+
+The MCP server (`mane mcp`) exposes:
+
+- `list_docs` — every doc as `{path, title, summary}`. Cold-start enumeration.
+- `get_summary(path)` — one doc's `{path, title, summary}`. Cheap.
+- `get_neighbors(path)` — focal doc + 1-hop neighbors, categorized as `parents / children / associated`. Each neighbor carries the prose note attached to its wiki-link.
+- `get_doc(path)` — full markdown plus per-section `content_hash` for safe patches.
+- `search(query, limit?)` — substring match over titles, summaries, content.
+- `append_section(path, heading, body, create_if_missing?)` — section-scoped append. Safer than `write_doc` for incremental edits.
+- `patch_section(path, heading, body, expected_content_hash)` — version-guarded section replacement. Mismatched hash returns a structured `version_conflict`.
+- `write_doc_preview(path, content)` — diff and list of removed sections before any full-file write.
+- `write_doc(path, content)` — full-file replace (destructive; prefer the section-scoped tools).
+
+## Design principles
+
+1. **Markdown is the only source of truth.** No persisted index, no derived database, no parallel summaries.
+2. **Same substrate, different lenses.** Renderer and MCP read the same files via the same indexer. Nothing the LLM sees is invisible to the human.
+3. **Convention over schema.** Light structure — H1 + `> blockquote` summary + three relationship sections (`## Parent of`, `## Child of`, `## Associated with`). The LLM parses English natively; rigid schemas only add authoring friction.
+4. **Single summary per doc.** The blockquote under the H1 is the routing decision for both humans and LLMs.
+
+## What's in here
+
+- `bin/mane.js` — the `mane` CLI (`init`, `start`, `mcp`)
+- `src/core/indexer.ts` — walks `docs/`, parses wiki-links and relationship sections, derives summaries, skips fenced code blocks
+- `src/mcp/server.ts` — MCP server with the tool surface above
+- `src/web/` — React + TypeScript renderer (Toast UI Editor + Cytoscape egocentric graph, category-colored nodes)
+- `src/server/dev-plugin.ts` — Vite middleware that serves the index in dev
+- `api/index.ts` — Vercel serverless function that serves the index in prod
+- `templates/` — vault seeds plus typed templates for `PROJECT`, `NOVEL`, `PERSON`, `HACKATHON`, `CONCEPT`. The engineering layer is type-agnostic — types are conventions plus templates, not schema. Adding a new type is one new file.
+
+## Conventions for the vault
+
+The seeded `docs/INFO.md` is the full conventions reference: filename rules, the relationship grammar (first wiki-link on each bullet is the declared edge, inline links are context-only), the LEARNINGS authoring format, attribution lines for provenance. Read it once when you start a vault, refer back when you forget how something works.
+
+## Deploying to Vercel
+
+Vercel auto-detects Vite. Set `SILENT_MANE_DOCS` (or commit a `docs/` for a public vault) and it will serve the SPA plus the `/api/index` endpoint. The default `.gitignore` excludes `docs/` so your vault stays private; remove that line if you want the vault public.
+

package/bin/emdee.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { spawn } from "node:child_process";
+import { mkdir, writeFile, access } from "node:fs/promises";
+import readline from "node:readline/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(__dirname, "..");
+
+// SPRINT-090: `start` and `serve-next` shell out to Vite / Next.js against
+// the full repo. Those files (app/, next.config.*, etc.) aren't in the
+// published tarball, so when the CLI is installed via `npm install -g`
+// those commands need to bail loudly rather than crash with a confusing
+// Vite / Next stack.
+async function ensureRepoCheckout(commandName) {
+  try {
+    await access(path.join(pkgRoot, "app"));
+  } catch {
+    console.error(
+      `emdee ${commandName} requires a repo checkout — clone https://github.com/AISystemResources/emdee\n` +
+        `The published npm package ships the CLI + MCP server only, not the web viewer.`
+    );
+    process.exit(1);
+  }
+}
+
+// SPRINT-093: keep owner-title derivation logic in lockstep with
+// src/lib/owner/identity.ts. The published tarball is plain JS (no tsx),
+// so this duplicates the 15-line function rather than pull in a runtime
+// compilation step. `e2e/cli/init.spec.ts` pins the two copies together —
+// if they ever diverge, the consistency test fails.
+function normalizeOwnerTitle(input) {
+  const normalized = input
+    .trim()
+    .toUpperCase()
+    .replace(/[._\s]/g, "-")
+    .replace(/[^A-Z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return normalized || "OWNER";
+}
+
+function ownerNodeScaffold(title) {
+  return `# ${title}
+
+> Your personal subtree. Top-level content (projects, people, notes, etc.) lives here. Renameable any time via \`rename_doc\` — inbound wiki-link references update atomically across the vault.
+
+## Child of
+
+* [[EMDEE]]
+
+## Parent of
+
+## Associated with
+
+## Notes
+`;
+}
+
+const program = new Command();
+program.name("emdee").description("Emdee — local docs + knowledge graph + MCP").version("0.1.0");
+
+program
+  .command("init")
+  .description("Create a docs/ folder with your owner node. The 5 system nodes (EMDEE, VAULT, SHARED, GRAVEYARD, IMAGES) are virtual — never written to disk.")
+  .option("--nickname <name>", "Display name for the owner node (required non-interactively)")
+  .action(async (opts) => {
+    const cwd = process.cwd();
+    const docsDir = path.join(cwd, "docs");
+    await mkdir(docsDir, { recursive: true });
+
+    let nickname = (opts.nickname ?? "").trim();
+    if (!nickname) {
+      if (!process.stdin.isTTY) {
+        console.error("emdee init needs --nickname when running non-interactively.");
+        process.exit(1);
+      }
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      nickname = (await rl.question("Your name (owner node title): ")).trim();
+      rl.close();
+      if (!nickname) {
+        console.error("emdee init: nickname cannot be empty.");
+        process.exit(1);
+      }
+    }
+
+    const title = normalizeOwnerTitle(nickname);
+    if (title === "OWNER") {
+      console.error(`emdee init: "${nickname}" normalised to the fallback OWNER — pick a name with ASCII letters.`);
+      process.exit(1);
+    }
+
+    const target = path.join(docsDir, `${title}.md`);
+    try {
+      await access(target);
+      console.log(`Already initialised at docs/${title}.md — leaving it alone.`);
+    } catch {
+      await writeFile(target, ownerNodeScaffold(title), "utf8");
+      console.log(`Created docs/${title}.md — your owner node.`);
+    }
+    console.log(
+      `\nThe 5 system nodes (EMDEE, VAULT, SHARED, GRAVEYARD, IMAGES) are virtual — they appear in \`emdee list\` and \`get_doc\` without being written to disk.`
+    );
+  });
+
+program
+  .command("start")
+  .description("Start the Emdee viewer against ./docs — requires a repo checkout")
+  .option("-p, --port <port>", "port", "5173")
+  .option("-d, --docs <dir>", "docs directory", "docs")
+  .action(async (opts) => {
+    await ensureRepoCheckout("start");
+    const docs = path.resolve(process.cwd(), opts.docs);
+    const child = spawn("npx", ["vite", "--port", opts.port], {
+      cwd: pkgRoot,
+      stdio: "inherit",
+      env: { ...process.env, EMDEE_DOCS: docs },
+    });
+    child.on("exit", (code) => process.exit(code ?? 0));
+  });
+
+program
+  .command("serve-next")
+  .description("Start the Emdee viewer using Next.js (App Router) — requires a repo checkout")
+  .option("-p, --port <port>", "port", "3000")
+  .option("-d, --docs <dir>", "docs directory", "docs")
+  .action(async (opts) => {
+    await ensureRepoCheckout("serve-next");
+    const docs = path.resolve(process.cwd(), opts.docs);
+    const child = spawn("npx", ["next", "dev", "--port", opts.port], {
+      cwd: pkgRoot,
+      stdio: "inherit",
+      env: { ...process.env, EMDEE_DOCS: docs },
+    });
+    child.on("exit", (code) => process.exit(code ?? 0));
+  });
+
+program
+  .command("mcp")
+  .description("Run the Emdee MCP server over stdio")
+  .option("-d, --docs <dir>", "docs directory", "docs")
+  .action((opts) => {
+    const docs = path.resolve(process.cwd(), opts.docs);
+    const child = spawn("npx", ["tsx", path.join(pkgRoot, "src/mcp/server.ts")], {
+      cwd: pkgRoot,
+      stdio: "inherit",
+      env: { ...process.env, EMDEE_DOCS: docs },
+    });
+    child.on("exit", (code) => process.exit(code ?? 0));
+  });
+
+program
+  .command("list")
+  .description("Print one doc path per line (token-cheap; local docs/ only)")
+  .option("-d, --docs <dir>", "docs directory", "docs")
+  .option("--prefix <prefix>", "filter to paths starting with this prefix")
+  .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);
+    const child = spawn("npx", args, {
+      cwd: pkgRoot,
+      stdio: "inherit",
+      env: { ...process.env, EMDEE_DOCS: docs },
+    });
+    child.on("exit", (code) => process.exit(code ?? 0));
+  });
+
+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("--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")
+  .action((opts) => {
+    const docs = path.resolve(process.cwd(), opts.docs);
+    const args = [
+      "tsx",
+      path.join(pkgRoot, "src/cli/read-commands.ts"),
+      "drift-batch",
+      "--limit", opts.limit,
+      "--offset", opts.offset,
+    ];
+    if (opts.prefix) args.push("--prefix", opts.prefix);
+    const child = spawn("npx", args, {
+      cwd: pkgRoot,
+      stdio: "inherit",
+      env: { ...process.env, EMDEE_DOCS: docs },
+    });
+    child.on("exit", (code) => process.exit(code ?? 0));
+  });
+
+program.parseAsync();

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@aisystemresources/emdee",
+  "version": "0.1.0",
+  "description": "Local-first document management with markdown rendering, knowledge graph, and MCP server.",
+  "type": "module",
+  "bin": {
+    "emdee": "./bin/emdee.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "next dev --webpack",
+    "build": "next build --webpack",
+    "start": "next start",
+    "lint": "eslint",
+    "mcp": "tsx src/mcp/server.ts",
+    "typecheck": "tsc --noEmit",
+    "e2e": "playwright test",
+    "e2e:ui": "playwright test --ui",
+    "e2e:report": "playwright show-report",
+    "check:migrations": "node scripts/check-migration-drift.mjs",
+    "ci-package": "node scripts/verify-package.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/cli/",
+    "src/core/",
+    "src/lib/cache/",
+    "src/lib/mcp/",
+    "src/lib/storage/",
+    "src/lib/supabase/",
+    "src/lib/trash/",
+    "src/lib/owner/",
+    "src/lib/system-nodes.ts",
+    "src/mcp/",
+    "templates/",
+    "README.md"
+  ],
+  "dependencies": {
+    "@clerk/nextjs": "^7.3.3",
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@sparticuz/chromium": "^149.0.0",
+    "@supabase/ssr": "^0.10.3",
+    "@supabase/supabase-js": "^2.105.4",
+    "@toast-ui/editor": "^3.2.2",
+    "commander": "^12.1.0",
+    "cytoscape": "^3.30.2",
+    "jszip": "^3.10.1",
+    "marked": "^18.0.4",
+    "next": "16.2.6",
+    "puppeteer-core": "^25.1.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "tsx": "^4.22.4"
+  },
+  "devDependencies": {
+    "@clerk/testing": "^2.1.5",
+    "@playwright/test": "^1.61.0",
+    "@tailwindcss/postcss": "^4",
+    "@types/cytoscape": "^3.21.4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.6",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "overrides": {
+    "postcss": "^8.5.10",
+    "dompurify": "^3.4.11",
+    "esbuild": "^0.28.1"
+  }
+}

package/src/cli/read-commands.ts

@@ -0,0 +1,64 @@
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { buildIndex } from "../core/indexer";
+
+const docsDir = path.resolve(process.env.EMDEE_DOCS ?? path.join(process.cwd(), "docs"));
+
+async function cmdList(argv: string[]): Promise<void> {
+  const { values } = parseArgs({
+    args: argv,
+    options: { prefix: { type: "string" } },
+    strict: true,
+  });
+  const idx = await buildIndex(docsDir);
+  const prefix = values.prefix ?? "";
+  for (const d of idx.docs) {
+    if (!prefix || d.path.startsWith(prefix)) process.stdout.write(d.path + "\n");
+  }
+}
+
+async function cmdDriftBatch(argv: string[]): Promise<void> {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      limit: { type: "string", default: "10" },
+      offset: { type: "string", default: "0" },
+      prefix: { type: "string" },
+    },
+    strict: true,
+  });
+  const limit = Math.max(1, Number(values.limit) | 0);
+  const offset = Math.max(0, Number(values.offset) | 0);
+  const idx = await buildIndex(docsDir);
+  const filtered = idx.docs
+    .filter((d) => !values.prefix || d.path.startsWith(values.prefix))
+    .sort((a, b) => a.path.localeCompare(b.path))
+    .slice(offset, offset + limit);
+  for (const d of filtered) {
+    process.stdout.write(`--- ${d.path}\n`);
+    process.stdout.write(`${d.summary ?? ""}\n\n`);
+    process.stdout.write(`${d.content}\n\n`);
+  }
+}
+
+const [, , sub, ...rest] = process.argv;
+
+async function main(): Promise<void> {
+  switch (sub) {
+    case "list":
+      await cmdList(rest);
+      return;
+    case "drift-batch":
+      await cmdDriftBatch(rest);
+      return;
+    default:
+      process.stderr.write(`unknown subcommand: ${sub ?? "(none)"}\n`);
+      process.stderr.write(`usage: emdee <list|drift-batch> [--prefix P] [--limit N] [--offset K]\n`);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});