@aisystemresources/emdee 0.1.0

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

@@ -0,0 +1,7 @@
+import type { VaultStorage } from "../../storage/VaultStorage";
+
+export type ToolContext =
+  | { mode: "local"; docsDir: string }
+  | { mode: "cloud"; storage: VaultStorage; userId: string };
+
+export type { DocIndex, DocNode, Link } from "../../../core/indexer";

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

@@ -0,0 +1,77 @@
+import { adminClient } from "../../supabase/admin";
+import { writeVaultFile } from "./vault";
+import type { ToolContext } from "./types";
+
+const IMAGE_BUCKET = "vault-images";
+
+const SUPPORTED_TYPES = ["image/jpeg", "image/png", "image/gif", "image/webp"] as const;
+type SupportedMediaType = (typeof SUPPORTED_TYPES)[number];
+
+function ext(mediaType: SupportedMediaType): string {
+  const map: Record<SupportedMediaType, string> = {
+    "image/jpeg": "jpg",
+    "image/png": "png",
+    "image/gif": "gif",
+    "image/webp": "webp",
+  };
+  return map[mediaType];
+}
+
+function slugify(s: string): string {
+  // SPRINT-055 (SIG-004): uppercase filenames are project convention.
+  return s.toUpperCase().trim().replace(/[^A-Z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+export async function uploadImage(ctx: ToolContext, args: Record<string, unknown>): Promise<unknown> {
+  if (ctx.mode === "local") {
+    return json({ error: "upload_image requires cloud mode — not available in local (stdio) mode" });
+  }
+
+  const imageData = String(args.image_data ?? "");
+  const mediaType = String(args.media_type ?? "") as SupportedMediaType;
+  const titleArg = args.title !== undefined ? String(args.title) : null;
+  const description = args.description !== undefined ? String(args.description) : "";
+  const pathArg = args.path !== undefined ? String(args.path) : null;
+
+  if (!imageData) return json({ error: "image_data is required" });
+  if (!(SUPPORTED_TYPES as readonly string[]).includes(mediaType)) {
+    return json({ error: `unsupported media_type — must be one of: ${SUPPORTED_TYPES.join(", ")}` });
+  }
+
+  let imageBuffer: Buffer;
+  try {
+    imageBuffer = Buffer.from(imageData, "base64");
+  } catch {
+    return json({ error: "image_data is not valid base64" });
+  }
+  if (imageBuffer.length === 0) return json({ error: "image_data decoded to empty buffer" });
+
+  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  const filename = `${ts}.${ext(mediaType)}`;
+  const storagePath = `${ctx.userId}/${filename}`;
+
+  const { error: uploadErr } = await adminClient()
+    .storage
+    .from(IMAGE_BUCKET)
+    .upload(storagePath, imageBuffer, { contentType: mediaType, upsert: false });
+
+  if (uploadErr) return json({ error: `storage upload failed: ${uploadErr.message}` });
+
+  const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!;
+  const imageUrl = `${supabaseUrl}/storage/v1/object/public/${IMAGE_BUCKET}/${storagePath}`;
+
+  const title = titleArg ?? `Image ${ts.slice(0, 10)}`;
+  const summary = description || "Image stored in vault";
+  const docSlug = titleArg ? slugify(titleArg) : ts.slice(0, 10);
+  const docPath = pathArg ?? `images/${docSlug}.md`;
+
+  const docContent = `# ${title}\n\n> ${summary}\n\n![${title}](${imageUrl})\n\n## Notes\n\n`;
+
+  await writeVaultFile(ctx, docPath, docContent);
+
+  return json({ doc_path: docPath, image_url: imageUrl, doc_created: true });
+}

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

@@ -0,0 +1,36 @@
+// SPRINT-092: strict argument validation for write-side MCP tools.
+//
+// The MCP SDK (@modelcontextprotocol/sdk/dist/esm/server/index.js) validates
+// only the outer CallToolRequestSchema — individual tool `arguments` are
+// passed through as Record<string, unknown> without JSON-Schema enforcement.
+// Adding `additionalProperties: false` to inputSchema is documentation only.
+//
+// This helper closes the gap at each tool's entry point: unknown parameter
+// names return a loud error instead of being silently dropped, and required
+// parameters must actually be present (not just default to "" when missing).
+
+export interface ArgSpec {
+  allowed: readonly string[];
+  required?: readonly string[];
+}
+
+export type ArgValidationError =
+  | { error: "unknown_arguments"; unknown: string[]; allowed: string[] }
+  | { error: "missing_required"; missing: string[]; allowed: string[] };
+
+export function validateArgs(
+  args: Record<string, unknown>,
+  spec: ArgSpec,
+): ArgValidationError | null {
+  const allowedSet = new Set(spec.allowed);
+  const unknown = Object.keys(args).filter((k) => !allowedSet.has(k));
+  if (unknown.length > 0) {
+    return { error: "unknown_arguments", unknown, allowed: [...spec.allowed] };
+  }
+  const required = spec.required ?? [];
+  const missing = required.filter((k) => !(k in args));
+  if (missing.length > 0) {
+    return { error: "missing_required", missing, allowed: [...spec.allowed] };
+  }
+  return null;
+}

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

@@ -0,0 +1,430 @@
+import { readFile, writeFile, mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { buildIndex, buildIndexFromContents, type DocIndex } from "../../../core/indexer";
+import { adminClient } from "../../supabase/admin";
+import { subscribeNamespaceInvalidate } from "../../cache/invalidation";
+import { missingSystemNodeFiles } from "../../system-nodes";
+import type { ToolContext } from "./types";
+
+/**
+ * Paths under SHARED_PATH_PREFIX point at docs owned by another user that
+ * this user has been granted read access to. Format:
+ *   __shared__/<owner_clerk_id>/<rel_path>
+ * These look like normal vault paths to MCP clients but are routed
+ * cross-namespace by readVaultFile and refused by every write op.
+ */
+export const SHARED_PATH_PREFIX = "__shared__/";
+
+export function validatePath(rel: string): void {
+  if (!rel || rel.includes("..")) throw new Error("invalid path");
+  if (!rel.endsWith(".md")) throw new Error("path must end in .md");
+}
+
+function localSafePath(docsDir: string, rel: string): string {
+  const resolved = path.resolve(docsDir, rel);
+  if (!resolved.startsWith(docsDir + path.sep) && resolved !== docsDir) {
+    throw new Error("path escapes docs directory");
+  }
+  return resolved;
+}
+
+function parseSharedPath(rel: string): { ownerId: string; relPath: string } | null {
+  if (!rel.startsWith(SHARED_PATH_PREFIX)) return null;
+  const rest = rel.slice(SHARED_PATH_PREFIX.length);
+  const slash = rest.indexOf("/");
+  if (slash === -1) return null;
+  return { ownerId: rest.slice(0, slash), relPath: rest.slice(slash + 1) };
+}
+
+async function listSharedDocsForGrantee(granteeId: string): Promise<Array<{ ownerId: string; relPath: string }>> {
+  const { data } = await adminClient()
+    .from("doc_shares")
+    .select("owner_id, path_prefix")
+    .eq("grantee_id", granteeId);
+  return (data ?? []).map((r) => ({ ownerId: r.owner_id as string, relPath: r.path_prefix as string }));
+}
+
+async function hasShareAccess(granteeId: string, ownerId: string, relPath: string): Promise<boolean> {
+  const { data } = await adminClient()
+    .from("doc_shares")
+    .select("id")
+    .eq("grantee_id", granteeId)
+    .eq("owner_id", ownerId)
+    .eq("path_prefix", relPath)
+    .maybeSingle();
+  return !!data;
+}
+
+/**
+ * Direct match OR ancestor match for `permission='write'`. Ancestor walk
+ * uses path conventions (cascade-by-hierarchy): write on
+ * `projects/DOUBLELEAD.md` covers `projects/DOUBLELEAD/IDEAS/NewIdea.md`.
+ * The strict-ancestor form (`<parts>/...md`) avoids cross-prefix false
+ * positives like `DOUBLELEAD-OFFSHOOT.md`.
+ */
+async function isWritableSharedPath(
+  granteeId: string,
+  ownerId: string,
+  relPath: string,
+): Promise<boolean> {
+  const admin = adminClient();
+
+  const { data: direct } = await admin
+    .from("doc_shares")
+    .select("id")
+    .eq("grantee_id", granteeId)
+    .eq("owner_id", ownerId)
+    .eq("path_prefix", relPath)
+    .eq("permission", "write")
+    .maybeSingle();
+  if (direct) return true;
+
+  const parts = relPath.split("/");
+  const candidates: string[] = [];
+  for (let i = parts.length - 1; i > 0; i--) {
+    candidates.push(parts.slice(0, i).join("/") + ".md");
+  }
+  if (candidates.length > 0) {
+    const { data: anc } = await admin
+      .from("doc_shares")
+      .select("path_prefix")
+      .eq("grantee_id", granteeId)
+      .eq("owner_id", ownerId)
+      .eq("permission", "write")
+      .in("path_prefix", candidates);
+    if ((anc?.length ?? 0) > 0) return true;
+  }
+
+  // Sibling-directory fallback: the share root (e.g. signals/SIGNALS.md) lives
+  // at the same level as the new file (signals/SIG-009.md), so neither a direct
+  // nor a directory-ancestor match fires. If ANY write-permission row exists for
+  // a file in the same directory, the grantee's cascade write grant covers it.
+  const dir = parts.slice(0, -1).join("/");
+  if (!dir) return false;
+  const { data: sib } = await admin
+    .from("doc_shares")
+    .select("id")
+    .eq("grantee_id", granteeId)
+    .eq("owner_id", ownerId)
+    .eq("permission", "write")
+    .like("path_prefix", `${dir}/%`)
+    .limit(1);
+  return (sib?.length ?? 0) > 0;
+}
+
+/**
+ * SPRINT-032: after a write-permission grantee creates a doc under a
+ * shared subtree, the share API never inserted a doc_shares row for the
+ * new path — so neither the writer nor any other grantee of the share
+ * root sees it. Mirror the cascade by inserting one row per
+ * (grantee, share_root) for the new path, copying each grantee's existing
+ * permission. Read grantees still see (read-only); write grantees can
+ * keep editing. Idempotent — repeat writes upsert to the same rows.
+ *
+ * Best-effort: a failure here is logged by the caller but doesn't fail
+ * the underlying write.
+ */
+async function propagateShareToNewPath(
+  ownerId: string,
+  newPath: string,
+  writerGranteeId: string,
+): Promise<void> {
+  const admin = adminClient();
+
+  // 1. Which share_roots authorised this write?
+  // First try ancestor-level matches (e.g. DOUBLELEAD.md covers DOUBLELEAD/**).
+  // If that finds nothing, fall back to sibling-directory: the share root lives
+  // at the same folder level as the new file (e.g. signals/SIGNALS.md is the
+  // root for signals/SIG-009.md). Without this fallback, propagation silently
+  // fails for the common case where the root is an index file in a sub-folder.
+  const parts = newPath.split("/");
+  const candidates: string[] = [];
+  for (let i = parts.length - 1; i > 0; i--) {
+    candidates.push(parts.slice(0, i).join("/") + ".md");
+  }
+
+  let authRows: { share_root: string | null }[] | null = null;
+  if (candidates.length > 0) {
+    const { data } = await admin
+      .from("doc_shares")
+      .select("share_root")
+      .eq("owner_id", ownerId)
+      .eq("grantee_id", writerGranteeId)
+      .eq("permission", "write")
+      .in("path_prefix", candidates);
+    authRows = data;
+  }
+
+  if (!authRows || authRows.length === 0) {
+    const dir = parts.slice(0, -1).join("/");
+    if (!dir) return;
+    const { data: sibData } = await admin
+      .from("doc_shares")
+      .select("share_root")
+      .eq("owner_id", ownerId)
+      .eq("grantee_id", writerGranteeId)
+      .eq("permission", "write")
+      .like("path_prefix", `${dir}/%`);
+    authRows = sibData;
+  }
+
+  if (!authRows || authRows.length === 0) return;
+
+  const shareRoots = [
+    ...new Set(
+      authRows
+        .map((r) => r.share_root as string | null)
+        .filter((s): s is string => !!s),
+    ),
+  ];
+  if (shareRoots.length === 0) return;
+
+  // 2. Every grantee of those share_roots, incl. read-only. Same group,
+  //    same view.
+  const { data: groupRows } = await admin
+    .from("doc_shares")
+    .select("grantee_id, permission, share_root")
+    .eq("owner_id", ownerId)
+    .in("share_root", shareRoots);
+  if (!groupRows || groupRows.length === 0) return;
+
+  // 3. Dedupe by (grantee, share_root). Write beats read for the same
+  //    pair (degenerate case — defensive only).
+  type Insert = {
+    owner_id: string;
+    grantee_id: string;
+    path_prefix: string;
+    permission: "read" | "write";
+    share_root: string;
+  };
+  const byKey = new Map<string, Insert>();
+  for (const r of groupRows) {
+    const grantee = r.grantee_id as string;
+    const share_root = r.share_root as string;
+    const permission = r.permission as "read" | "write";
+    const key = `${grantee}::${share_root}`;
+    const existing = byKey.get(key);
+    if (existing) {
+      if (permission === "write" && existing.permission === "read") {
+        existing.permission = "write";
+      }
+      continue;
+    }
+    byKey.set(key, {
+      owner_id: ownerId,
+      grantee_id: grantee,
+      path_prefix: newPath,
+      permission,
+      share_root,
+    });
+  }
+
+  const inserts = Array.from(byKey.values());
+  if (inserts.length === 0) return;
+
+  const { error } = await admin
+    .from("doc_shares")
+    .upsert(inserts, { onConflict: "owner_id,path_prefix,grantee_id" });
+  if (error) throw new Error(error.message);
+}
+
+/**
+ * SPRINT-035: module-scope `loadVaultIndex` memo. Replaces the per-ctx
+ * WeakMap (which was empty per-request because the MCP HTTP route
+ * allocates a fresh ToolContext per call — see
+ * `app/api/mcp/route.ts:164`), so a single Vercel function instance
+ * shares the computed index across all tool calls within the TTL window.
+ *
+ * Keyed by `(mode, userId | docsDir)` so cross-user requests on the same
+ * function instance don't collide. Invalidated whenever a write to that
+ * namespace publishes through the invalidation hub (which fires from
+ * SupabaseStorage.write / .delete regardless of whether the write
+ * originated from MCP, web, or any other surface).
+ *
+ * TTL bounded so stale reads from silent external mutations (anything
+ * bypassing the storage layer) are visible within one minute.
+ */
+interface IndexMemoEntry {
+  promise: Promise<DocIndex>;
+  expiresAt: number;
+}
+const indexMemoByKey = new Map<string, IndexMemoEntry>();
+const INDEX_MEMO_TTL_MS = 60_000;
+
+const indexStats = {
+  hits: 0,
+  misses: 0,
+  invalidations: 0,
+};
+
+function indexMemoKey(ctx: ToolContext): string {
+  return ctx.mode === "local" ? `local:${ctx.docsDir}` : `cloud:${ctx.userId}`;
+}
+
+function invalidateIndexMemo(ctx: ToolContext): void {
+  if (indexMemoByKey.delete(indexMemoKey(ctx))) indexStats.invalidations++;
+}
+
+// Subscribe to namespace-level invalidation events published by
+// SupabaseStorage.write / .delete. A write to namespace `X` clears the
+// `cloud:X` memo so the next read sees the fresh state. Cross-namespace
+// shared writes (Sim Yee → Edmund's vault) fire with Edmund's namespace,
+// so Edmund's memo clears even though Sim Yee was the writer.
+subscribeNamespaceInvalidate((namespace) => {
+  if (indexMemoByKey.delete(`cloud:${namespace}`)) indexStats.invalidations++;
+});
+
+export function getIndexMemoStats(): {
+  hits: number;
+  misses: number;
+  invalidations: number;
+  size: number;
+  hitRate: number;
+} {
+  const total = indexStats.hits + indexStats.misses;
+  return {
+    hits: indexStats.hits,
+    misses: indexStats.misses,
+    invalidations: indexStats.invalidations,
+    size: indexMemoByKey.size,
+    hitRate: total === 0 ? 0 : indexStats.hits / total,
+  };
+}
+
+async function buildVaultIndex(ctx: ToolContext): Promise<DocIndex> {
+  if (ctx.mode === "local") return buildIndex(ctx.docsDir);
+
+  const ownPrefix = `${ctx.userId}/`;
+  const ownFiles = await ctx.storage.listWithContent(ownPrefix);
+  const ownWithContent = ownFiles.map((f) => ({
+    path: f.path.slice(ownPrefix.length),
+    content: f.content,
+  }));
+  // SPRINT-093: inject the 5 canonical system nodes when the user hasn't
+  // written a stored version. Matches the /api/index injection so MCP
+  // readers see the same starter set the web renderer does.
+  const virtuals = missingSystemNodeFiles(ownWithContent.map((f) => f.path));
+  const ownIndex = buildIndexFromContents([...ownWithContent, ...virtuals]);
+
+  const shared = await listSharedDocsForGrantee(ctx.userId);
+  if (shared.length === 0) return ownIndex;
+
+  const sharedFiles = await Promise.all(
+    shared.map(async (s) => ({
+      path: `${SHARED_PATH_PREFIX}${s.ownerId}/${s.relPath}`,
+      content: (await ctx.storage.read(`${s.ownerId}/${s.relPath}`)) ?? "",
+    }))
+  );
+  const sharedIndex = buildIndexFromContents(sharedFiles);
+
+  return {
+    docs: [...ownIndex.docs, ...sharedIndex.docs],
+    edges: [...ownIndex.edges, ...sharedIndex.edges],
+    entry: ownIndex.entry,
+  };
+}
+
+/**
+ * Builds the index of the user's own vault, then appends docs shared with
+ * them. Both sub-indexes are sourced via storage.listWithContent / the
+ * cache so the bulk read is one round-trip. Edges from the two
+ * sub-indexes don't cross-link — wiki-link resolution stays within each
+ * owner's namespace, so the grantee can navigate shared docs by title
+ * without leaking back to their own vault.
+ *
+ * Memoised at module scope keyed by `(mode, userId)`: see `indexMemoByKey` above.
+ */
+export async function loadVaultIndex(ctx: ToolContext): Promise<DocIndex> {
+  const key = indexMemoKey(ctx);
+  const hit = indexMemoByKey.get(key);
+  if (hit && hit.expiresAt > Date.now()) {
+    indexStats.hits++;
+    return hit.promise;
+  }
+  const promise = buildVaultIndex(ctx).catch((err) => {
+    // Don't cache failures — a transient Supabase blip shouldn't poison
+    // future calls.
+    indexMemoByKey.delete(key);
+    throw err;
+  });
+  indexMemoByKey.set(key, { promise, expiresAt: Date.now() + INDEX_MEMO_TTL_MS });
+  indexStats.misses++;
+  return promise;
+}
+
+export async function readVaultFile(ctx: ToolContext, rel: string): Promise<string | null> {
+  if (ctx.mode === "local") {
+    try {
+      return await readFile(localSafePath(ctx.docsDir, rel), "utf8");
+    } catch {
+      return null;
+    }
+  }
+  const shared = parseSharedPath(rel);
+  if (shared) {
+    const allowed = await hasShareAccess(ctx.userId, shared.ownerId, shared.relPath);
+    if (!allowed) return null;
+    return ctx.storage.read(`${shared.ownerId}/${shared.relPath}`);
+  }
+  return ctx.storage.read(`${ctx.userId}/${rel}`);
+}
+
+export async function writeVaultFile(ctx: ToolContext, rel: string, content: string): Promise<void> {
+  const shared = parseSharedPath(rel);
+  if (shared) {
+    if (ctx.mode === "local") {
+      throw new Error("shared paths not available in local mode");
+    }
+    const allowed = await isWritableSharedPath(ctx.userId, shared.ownerId, shared.relPath);
+    if (!allowed) {
+      throw new Error("shared docs are read-only for you — ask the owner to grant write access or make the edit");
+    }
+    try {
+      await ctx.storage.write(`${shared.ownerId}/${shared.relPath}`, content);
+    } finally {
+      invalidateIndexMemo(ctx);
+    }
+    // SPRINT-032: extend share rows to the new path so the writer (and
+    // other grantees of the same share root) actually see it.
+    // Best-effort — a propagation failure is logged but doesn't fail
+    // the underlying write (the doc was created successfully).
+    try {
+      await propagateShareToNewPath(shared.ownerId, shared.relPath, ctx.userId);
+    } catch (e) {
+      console.error(
+        `share propagation failed for ${shared.ownerId}/${shared.relPath}:`,
+        e,
+      );
+    }
+    return;
+  }
+  try {
+    if (ctx.mode === "local") {
+      const file = localSafePath(ctx.docsDir, rel);
+      await mkdir(path.dirname(file), { recursive: true });
+      await writeFile(file, content, "utf8");
+      return;
+    }
+    await ctx.storage.write(`${ctx.userId}/${rel}`, content);
+  } finally {
+    // Bust the per-request memo whether the write succeeded or threw —
+    // a partial write may still have committed bucket content, and
+    // either way the cached index is stale.
+    invalidateIndexMemo(ctx);
+  }
+}
+
+export async function deleteVaultFile(ctx: ToolContext, rel: string): Promise<void> {
+  if (rel.startsWith(SHARED_PATH_PREFIX)) {
+    throw new Error("shared docs are read-only — ask the owner to delete");
+  }
+  try {
+    if (ctx.mode === "local") {
+      await rm(localSafePath(ctx.docsDir, rel), { force: true });
+      return;
+    }
+    await ctx.storage.delete(`${ctx.userId}/${rel}`);
+  } finally {
+    invalidateIndexMemo(ctx);
+  }
+}

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

@@ -0,0 +1,81 @@
+import { validatePath, writeVaultFile, loadVaultIndex } from "./vault";
+import { lintDocContent } from "./lint";
+import { evaluateLintGate } from "./lint_gate";
+import { buildLintVaultContext } from "./lint_doc";
+import { isUppercaseFilename, normalizeFilenameInPath } from "./filename";
+import type { ToolContext } from "./types";
+import { validateArgs } from "./validate_args";
+
+const ARG_SPEC = {
+  allowed: ["path", "content", "gate_on_warnings"],
+  required: ["path", "content"],
+} as const;
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+// Codes whose detection needs vault context (cross-doc lookups). Pulling
+// the index is expensive on the hot path, so we only do it when the
+// caller explicitly gated on one of these. Keep in sync with lint.ts.
+const CROSS_DOC_CODES = new Set([
+  "asymmetric_parent_edge",
+  "asymmetric_child_edge",
+  "sibling_assoc_redundant",
+]);
+
+function parseGateCodes(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((c): c is string => typeof c === "string");
+}
+
+/**
+ * Create or overwrite a doc. Returns an envelope including any lint warnings
+ * surfaced from the just-written content (missing preamble, undeclared
+ * inline mentions). Warnings are signal, not gate — the write always
+ * succeeds; the caller decides whether to act on them.
+ *
+ * Opt-in hard gate via `gate_on_warnings: string[]` — when non-empty,
+ * the proposed content is linted BEFORE the write; if any warning whose
+ * code is in the list fires, the write is skipped and the response is
+ * `{ error: "lint_gate_failed", fixes, original_warnings }`. Default
+ * `[]` preserves the legacy signal-not-gate behaviour.
+ */
+export async function writeDoc(ctx: ToolContext, args: Record<string, unknown>): Promise<unknown> {
+  const argErr = validateArgs(args, ARG_SPEC);
+  if (argErr) return json(argErr);
+  const rel = String(args.path);
+  validatePath(rel);
+
+  // SPRINT-055 (SIG-004): refuse non-uppercase filenames at the entry point.
+  // Cheaper than letting them in and lint-warning later — keeps the on-disk
+  // namespace homogeneous. Auto-fix via `normalizeFilenameInPath` is offered
+  // in the error envelope so the caller can re-run without recomputing.
+  if (!isUppercaseFilename(rel)) {
+    return json({
+      error: "filename_not_uppercase",
+      path: rel,
+      suggested: normalizeFilenameInPath(rel),
+      hint: "EMDEE filenames are all-caps ASCII (CLAUDE.md, SPRINT-029.md). Re-run write_doc with `path: <suggested>`.",
+    });
+  }
+
+  const content = String(args.content ?? "");
+  const gateCodes = parseGateCodes(args.gate_on_warnings);
+
+  if (gateCodes.length > 0) {
+    const needsVault = gateCodes.some((c) => CROSS_DOC_CODES.has(c));
+    const vaultCtx = needsVault ? buildLintVaultContext(await loadVaultIndex(ctx), rel) : undefined;
+    const gate = evaluateLintGate(content, gateCodes, vaultCtx);
+    if (!gate.ok) {
+      return json({ error: "lint_gate_failed", fixes: gate.fixes, original_warnings: gate.original_warnings });
+    }
+  }
+
+  await writeVaultFile(ctx, rel, content);
+
+  const lint = lintDocContent(content);
+  const payload: Record<string, unknown> = { ok: true, path: rel, message: `wrote ${rel}` };
+  if (lint.warnings.length > 0) payload.warnings = lint.warnings;
+  return json(payload);
+}

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

@@ -0,0 +1,59 @@
+import { validatePath, readVaultFile } from "./vault";
+import type { ToolContext } from "./types";
+import { validateArgs } from "./validate_args";
+
+const ARG_SPEC = {
+  allowed: ["path", "content"],
+  required: ["path", "content"],
+} as const;
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+interface SectionLoc { heading: string; headingLineIdx: number; bodyStartLineIdx: number; bodyEndLineIdx: number; }
+const FENCE_RE = /^\s*(?:```|~~~)/;
+const H2_RE = /^##\s+(.+?)\s*$/;
+
+function parseSections(content: string): SectionLoc[] {
+  const lines = content.split("\n");
+  const sections: SectionLoc[] = [];
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (FENCE_RE.test(lines[i])) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const m = lines[i].match(H2_RE);
+    if (!m) continue;
+    if (sections.length > 0) sections[sections.length - 1].bodyEndLineIdx = i;
+    sections.push({ heading: m[1].trim(), headingLineIdx: i, bodyStartLineIdx: i + 1, bodyEndLineIdx: lines.length });
+  }
+  return sections;
+}
+
+function simpleDiff(before: string, after: string): string {
+  const bl = before.split("\n"), al = after.split("\n");
+  let cp = 0, cs = 0;
+  while (cp < bl.length && cp < al.length && bl[cp] === al[cp]) cp++;
+  while (cs < bl.length - cp && cs < al.length - cp && bl[bl.length - 1 - cs] === al[al.length - 1 - cs]) cs++;
+  const out = [`--- before (${bl.length} lines)`, `+++ after  (${al.length} lines)`];
+  if (cp > 0) out.push(`  … ${cp} unchanged …`);
+  for (let i = cp; i < bl.length - cs; i++) out.push(`- ${bl[i]}`);
+  for (let i = cp; i < al.length - cs; i++) out.push(`+ ${al[i]}`);
+  if (cs > 0) out.push(`  … ${cs} unchanged …`);
+  return out.join("\n");
+}
+
+export async function writeDocPreview(ctx: ToolContext, args: Record<string, unknown>): Promise<unknown> {
+  const argErr = validateArgs(args, ARG_SPEC);
+  if (argErr) return json(argErr);
+  const rel = String(args.path);
+  validatePath(rel);
+  const newContent = String(args.content ?? "");
+  const before = await readVaultFile(ctx, rel);
+  if (before === null) return json({ action: "create", path: rel, new_size_lines: newContent.split("\n").length });
+  if (before === newContent) return json({ action: "no_change", path: rel });
+  const beforeSections = parseSections(before).map((s) => s.heading);
+  const afterSections = parseSections(newContent).map((s) => s.heading);
+  const removed = beforeSections.filter((h) => !afterSections.includes(h));
+  return json({ action: "replace", path: rel, sections_removed: removed, sections_before: beforeSections, sections_after: afterSections, diff: simpleDiff(before, newContent) });
+}