@aisystemresources/emdee 0.1.0

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

@@ -0,0 +1,70 @@
+// SPRINT-024 Phase 1: per-section read. Returns one section's body +
+// content_hash + section_id without paying for the entire doc body.
+// Supports the same hash-conditional short-circuit as get_doc: pass
+// `expected_content_hash` from a prior read and we'll short-return
+// `{ unchanged: true, ... }` when the section body is byte-equal.
+//
+// Lookup precedence mirrors patch_section / append_section exactly
+// (see resolveSection in ./sections.ts) so the section_id flow is
+// uniform across read and write tools.
+
+import { validatePath, readVaultFile } from "./vault";
+import {
+  parseSections,
+  extractBody,
+  hashBody,
+  sectionId,
+  resolveSection,
+} from "./sections";
+import type { ToolContext } from "./types";
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+export async function readDocSection(ctx: ToolContext, args: Record<string, unknown>): Promise<unknown> {
+  const rel = String(args.path);
+  validatePath(rel);
+  const headingArg = args.heading !== undefined ? String(args.heading).trim() : "";
+  const sectionIdArg = args.section_id !== undefined ? String(args.section_id).trim() : "";
+  const expected = args.expected_content_hash !== undefined ? String(args.expected_content_hash) : "";
+  if (!headingArg && !sectionIdArg) throw new Error("heading or section_id required");
+
+  const content = await readVaultFile(ctx, rel);
+  if (content === null) return json({ error: "doc_not_found", path: rel });
+
+  const sections = parseSections(content);
+  const resolved = resolveSection(sections, sectionIdArg, headingArg);
+  if (resolved.kind === "mismatch") {
+    return json({
+      error: "section_id_heading_mismatch",
+      section_id_resolves_to: resolved.section_id_resolves_to,
+      heading_resolves_to: resolved.heading_resolves_to,
+    });
+  }
+  if (resolved.kind === "not_found") {
+    return json({
+      error: "section_not_found",
+      heading: headingArg || undefined,
+      section_id: sectionIdArg || undefined,
+      available: resolved.available,
+    });
+  }
+
+  const { loc, idx } = resolved;
+  const body = extractBody(content, loc);
+  const contentHash = hashBody(body);
+  const id = sectionId(loc.heading, idx);
+
+  if (expected && expected === contentHash) {
+    return json({ unchanged: true, section_id: id, content_hash: contentHash });
+  }
+
+  return json({
+    path: rel,
+    section_id: id,
+    heading: loc.heading,
+    body,
+    content_hash: contentHash,
+  });
+}

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

@@ -0,0 +1,167 @@
+import path from "node:path";
+import { validatePath, readVaultFile, writeVaultFile, deleteVaultFile, loadVaultIndex } from "./vault";
+import { adminClient } from "../../supabase/admin";
+import type { ToolContext } from "./types";
+import { validateArgs } from "./validate_args";
+
+const ARG_SPEC = {
+  allowed: ["old_path", "new_title", "new_path"],
+  required: ["old_path", "new_title"],
+} as const;
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function deriveTitle(content: string, fallbackPath: string): string {
+  const heading = content.match(/^#\s+(.+)$/m);
+  if (heading) return heading[1].trim();
+  return path.basename(fallbackPath, ".md");
+}
+
+function rewriteH1(content: string, newTitle: string): string {
+  if (/^#\s+.+$/m.test(content)) {
+    return content.replace(/^#\s+.+$/m, `# ${newTitle}`);
+  }
+  // No H1 — prepend one with the standard blockquote-summary placeholder.
+  return `# ${newTitle}\n\n> \n\n${content}`;
+}
+
+function sanitizeFilename(title: string): string {
+  // Match what the AddChild flow does — strip slashes/backslashes to keep
+  // the filename within a single directory. Other characters (spaces,
+  // hyphens, dashes) are preserved so titles like "ATLAS — BUILD" map
+  // back to "ATLAS — BUILD.md".
+  return title.replace(/[/\\]/g, "_");
+}
+
+function defaultNewPath(oldPath: string, newTitle: string): string {
+  const dir = path.dirname(oldPath);
+  const fname = `${sanitizeFilename(newTitle)}.md`;
+  return dir === "." ? fname : `${dir}/${fname}`;
+}
+
+/**
+ * Rewrites every `[[<oldTitle>]]` and `[[<oldTitle>|alias]]` occurrence
+ * (case-insensitive) to point at `newTitle`. Aliases are preserved.
+ * Returns the new content plus a boolean indicating whether anything
+ * changed.
+ */
+function rewriteWikiLinks(content: string, oldTitle: string, newTitle: string): { content: string; changed: boolean } {
+  if (oldTitle.toLowerCase() === newTitle.toLowerCase()) return { content, changed: false };
+  const re = new RegExp(`\\[\\[${escapeRegex(oldTitle)}(\\|[^\\]]+)?\\]\\]`, "gi");
+  let changed = false;
+  const next = content.replace(re, (_match, alias: string | undefined) => {
+    changed = true;
+    return `[[${newTitle}${alias ?? ""}]]`;
+  });
+  return { content: next, changed };
+}
+
+/**
+ * Atomic rename of a doc:
+ *  - rewrite its H1 to the new title
+ *  - write to the new path (default: same directory, sanitized title)
+ *  - delete the old path if it moved
+ *  - rewrite all `[[<old_title>]]` references across every other doc
+ *  - update doc_shares / share_invitations / sync_manifest path refs
+ *    (cloud mode only)
+ *
+ * Pre-flight checks block destination-path collisions and title
+ * collisions with other docs. Self-references inside the doc are
+ * rewritten too.
+ *
+ * On failure during the cross-doc rewrite phase, the renamed doc stays
+ * at the new path — partial rewrites are left in place. The caller can
+ * re-run with the same args; per-doc writes are idempotent because the
+ * old-title links won't be present in already-rewritten docs.
+ */
+export async function renameDoc(ctx: ToolContext, args: Record<string, unknown>): Promise<unknown> {
+  const argErr = validateArgs(args, ARG_SPEC);
+  if (argErr) return json(argErr);
+  const oldPath = String(args.old_path ?? "");
+  const newTitle = String(args.new_title ?? "").trim();
+  const newPath = args.new_path ? String(args.new_path) : defaultNewPath(oldPath, newTitle);
+
+  if (!oldPath) return json({ error: "old_path required" });
+  if (!newTitle) return json({ error: "new_title required" });
+
+  validatePath(oldPath);
+  validatePath(newPath);
+
+  const oldContent = await readVaultFile(ctx, oldPath);
+  if (oldContent === null) return json({ error: "source_not_found", path: oldPath });
+
+  const oldTitle = deriveTitle(oldContent, oldPath);
+
+  const index = await loadVaultIndex(ctx);
+
+  // Pre-flight: destination path must be free unless it equals source.
+  if (newPath !== oldPath) {
+    const exists = index.docs.some((d) => d.path === newPath);
+    if (exists) return json({ error: "destination_path_exists", path: newPath });
+  }
+
+  // Pre-flight: new title can't collide with another doc's title (the
+  // indexer uses title→path to resolve wiki-links, so duplicates would
+  // break navigation).
+  if (oldTitle.toLowerCase() !== newTitle.toLowerCase()) {
+    const conflict = index.docs.find(
+      (d) => d.path !== oldPath && d.title.toLowerCase() === newTitle.toLowerCase()
+    );
+    if (conflict) {
+      return json({ error: "title_conflict", path: conflict.path, title: conflict.title });
+    }
+  }
+
+  // Stage 1: rewrite the source doc's body (H1 + self-references).
+  let updatedSelf = rewriteH1(oldContent, newTitle);
+  updatedSelf = rewriteWikiLinks(updatedSelf, oldTitle, newTitle).content;
+  await writeVaultFile(ctx, newPath, updatedSelf);
+  if (newPath !== oldPath) {
+    await deleteVaultFile(ctx, oldPath);
+  }
+
+  // Stage 2: rewrite wiki-links in every other doc that mentions oldTitle.
+  let docsRewritten = 0;
+  for (const d of index.docs) {
+    if (d.path === oldPath) continue;
+    const result = rewriteWikiLinks(d.content, oldTitle, newTitle);
+    if (!result.changed) continue;
+    await writeVaultFile(ctx, d.path, result.content);
+    docsRewritten++;
+  }
+
+  // Stage 3 (cloud only): update DB rows that reference the path directly.
+  // doc_shares.path_prefix / share_root, share_invitations.path_prefix /
+  // share_root, sync_manifest.file_path (which uses the namespaced form).
+  if (ctx.mode === "cloud" && newPath !== oldPath) {
+    const admin = adminClient();
+    const ownerId = ctx.userId;
+    await Promise.all([
+      admin.from("doc_shares").update({ path_prefix: newPath })
+        .eq("owner_id", ownerId).eq("path_prefix", oldPath),
+      admin.from("doc_shares").update({ share_root: newPath })
+        .eq("owner_id", ownerId).eq("share_root", oldPath),
+      admin.from("share_invitations").update({ path_prefix: newPath })
+        .eq("inviter_id", ownerId).eq("path_prefix", oldPath),
+      admin.from("share_invitations").update({ share_root: newPath })
+        .eq("inviter_id", ownerId).eq("share_root", oldPath),
+      admin.from("sync_manifest").update({ file_path: `${ownerId}/${newPath}` })
+        .eq("clerk_id", ownerId).eq("file_path", `${ownerId}/${oldPath}`),
+    ]);
+  }
+
+  return json({
+    ok: true,
+    old_path: oldPath,
+    new_path: newPath,
+    old_title: oldTitle,
+    new_title: newTitle,
+    docs_rewritten: docsRewritten,
+  });
+}
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}

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

@@ -0,0 +1,41 @@
+import { validatePath } from "./vault";
+import { readTrashedState, writeTrashedState } from "../../trash/state";
+import type { ToolContext } from "./types";
+import { validateArgs } from "./validate_args";
+
+const ARG_SPEC = { allowed: ["path"], required: ["path"] } as const;
+
+// SPRINT-057 (SIG-008): restore a previously-trashed doc by clearing its
+// entry in `.emdee/trashed.json`. The doc's markdown is untouched
+// throughout the trash → restore cycle; only the lifecycle flag moves.
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+export async function restoreDoc(
+  ctx: ToolContext,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const argErr = validateArgs(args, ARG_SPEC);
+  if (argErr) return json(argErr);
+  const docPath = String(args.path ?? "");
+  if (!docPath) return json({ error: "path required" });
+  validatePath(docPath);
+
+  const state = await readTrashedState(ctx);
+  const entry = state[docPath];
+  if (!entry) {
+    return json({ error: "not_trashed", path: docPath });
+  }
+
+  delete state[docPath];
+  await writeTrashedState(ctx, state);
+
+  return json({
+    ok: true,
+    path: docPath,
+    restored_to: entry.original_parent_path,
+    was_trashed_at: entry.trashed_at,
+  });
+}

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

@@ -0,0 +1,36 @@
+import { loadVaultIndex } from "./vault";
+import type { ToolContext } from "./types";
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+function makeSnippet(content: string, query: string, radius = 60): string {
+  const i = content.toLowerCase().indexOf(query.toLowerCase());
+  if (i < 0) return "";
+  const start = Math.max(0, i - radius);
+  const end = Math.min(content.length, i + query.length + radius);
+  return (start > 0 ? "…" : "") + content.slice(start, end).replace(/\s+/g, " ").trim() + (end < content.length ? "…" : "");
+}
+
+export async function search(ctx: ToolContext, args: Record<string, unknown>): Promise<unknown> {
+  const query = String(args.query ?? "").trim();
+  if (!query) return json([]);
+  const limit = Math.max(1, Math.min(50, Number(args.limit ?? 10)));
+  const idx = await loadVaultIndex(ctx);
+  const q = query.toLowerCase();
+  const hits = idx.docs
+    .map((d) => {
+      const titleHit = d.title.toLowerCase().includes(q);
+      const summaryHit = d.summary.toLowerCase().includes(q);
+      const contentHit = d.content.toLowerCase().includes(q);
+      if (!titleHit && !summaryHit && !contentHit) return null;
+      const score = (titleHit ? 3 : 0) + (summaryHit ? 2 : 0) + (contentHit ? 1 : 0);
+      return { score, ref: { path: d.path, title: d.title, summary: d.summary, snippet: titleHit ? "" : makeSnippet(d.content, query) } };
+    })
+    .filter((x): x is { score: number; ref: { path: string; title: string; summary: string; snippet: string } } => x !== null)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map((x) => x.ref);
+  return json(hits);
+}

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

@@ -0,0 +1,130 @@
+// Shared section-parsing primitives used by get_doc / patch_section /
+// append_section / read_doc_section. Hoisted in SPRINT-024 Phase 1 to
+// keep the H2 parser + content-hash helper in one place; previous
+// per-tool copies were drifting at the edges.
+
+import { createHash } from "node:crypto";
+
+const FENCE_RE = /^\s*(?:```|~~~)/;
+const H2_RE = /^##\s+(.+?)\s*$/;
+
+export interface SectionLoc {
+  heading: string;
+  headingLineIdx: number;
+  bodyStartLineIdx: number;
+  bodyEndLineIdx: number;
+}
+
+export 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;
+}
+
+export function extractBody(content: string, loc: SectionLoc): string {
+  return content
+    .split("\n")
+    .slice(loc.bodyStartLineIdx, loc.bodyEndLineIdx)
+    .join("\n")
+    .replace(/^\s*\n+/, "")
+    .replace(/\n+\s*$/, "");
+}
+
+export function findSectionByHeading(sections: SectionLoc[], heading: string): SectionLoc | undefined {
+  const target = heading.replace(/^##\s*/, "").trim().toLowerCase();
+  return sections.find((s) => s.heading.toLowerCase() === target);
+}
+
+/**
+ * sha256-first-16-hex of the input string. Used for both section bodies
+ * (the version-guard hash that gates patch_section) and whole-doc raw
+ * content (the doc_content_hash returned by get_doc / get_context for
+ * hash-conditional reads, SPRINT-024 Phase 1).
+ */
+export function hashBody(body: string): string {
+  return createHash("sha256").update(body, "utf8").digest("hex").slice(0, 16);
+}
+
+/**
+ * Deterministic short ID for an H2 section. Derived from the lowercased
+ * heading text plus the section's 0-indexed ordinal among H2s in the doc,
+ * so two sections sharing a heading get distinct IDs. The ordinal also
+ * means the ID is stable across rename of the heading IF the section
+ * stays at the same position.
+ */
+export function sectionId(heading: string, ordinalIdx: number): string {
+  return createHash("sha256")
+    .update(heading.toLowerCase() + ":" + ordinalIdx, "utf8")
+    .digest("hex")
+    .slice(0, 12);
+}
+
+/**
+ * Resolve a section lookup. Shared between patch_section / append_section /
+ * read_doc_section so the section_id_heading_mismatch and section_not_found
+ * shapes are identical across tools.
+ *
+ * Precedence:
+ *  - section_id alone: derive IDs by ordinal; first match wins.
+ *  - heading alone: fuzzy heading match.
+ *  - both: resolve each independently; if they pick different sections,
+ *    returns { kind: "mismatch" } so the caller emits section_id_heading_mismatch.
+ */
+export type SectionResolution =
+  | { kind: "ok"; loc: SectionLoc; idx: number }
+  | {
+      kind: "mismatch";
+      section_id_resolves_to: string;
+      heading_resolves_to: string;
+    }
+  | { kind: "not_found"; available: Array<{ id: string; heading: string }> };
+
+export function resolveSection(
+  sections: SectionLoc[],
+  sectionIdArg: string,
+  headingArg: string,
+): SectionResolution {
+  let idTarget: { loc: SectionLoc; idx: number } | undefined;
+  let headingTarget: { loc: SectionLoc; idx: number } | undefined;
+
+  if (sectionIdArg) {
+    for (let i = 0; i < sections.length; i++) {
+      if (sectionId(sections[i].heading, i) === sectionIdArg) {
+        idTarget = { loc: sections[i], idx: i };
+        break;
+      }
+    }
+  }
+  if (headingArg) {
+    const loc = findSectionByHeading(sections, headingArg);
+    if (loc) {
+      const idx = sections.indexOf(loc);
+      headingTarget = { loc, idx };
+    }
+  }
+
+  if (sectionIdArg && headingArg && idTarget && headingTarget && idTarget.loc !== headingTarget.loc) {
+    return {
+      kind: "mismatch",
+      section_id_resolves_to: idTarget.loc.heading,
+      heading_resolves_to: headingTarget.loc.heading,
+    };
+  }
+
+  const picked = idTarget ?? headingTarget;
+  if (picked) return { kind: "ok", loc: picked.loc, idx: picked.idx };
+
+  return {
+    kind: "not_found",
+    available: sections.map((s, i) => ({ id: sectionId(s.heading, i), heading: s.heading })),
+  };
+}

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

@@ -0,0 +1,129 @@
+import path from "node:path";
+import { validatePath, readVaultFile, writeVaultFile, loadVaultIndex } from "./vault";
+import type { ToolContext } from "./types";
+import { validateArgs } from "./validate_args";
+
+const ARG_SPEC = {
+  allowed: ["source_path", "rewrite_source_content", "extracts"],
+  required: ["source_path", "rewrite_source_content", "extracts"],
+} as const;
+
+interface ExtractInput {
+  path: string;
+  content: string;
+}
+
+function deriveTitle(rel: string, content: string): string {
+  const heading = content.match(/^#\s+(.+)$/m);
+  if (heading) return heading[1].trim();
+  return path.basename(rel, ".md");
+}
+
+/**
+ * Atomically refactor a doc into concept nodes.
+ *
+ * Use this when a doc has grown into multiple distinct reusable ideas
+ * (e.g. "TFAR", "Always complete what you've started") that deserve their
+ * own nodes the rest of the vault can wiki-link to. Claude builds the
+ * extraction plan in chat, then calls split_doc once to execute.
+ *
+ * Pre-flight checks catch the failure modes that bit us before:
+ *  - extract path already exists
+ *  - extract H1 title collides with an existing doc (would break the
+ *    title→path map the indexer uses for wiki-link resolution)
+ *  - two extracts share a path or title
+ *
+ * On write failure mid-flight, the source rewrite is skipped so the
+ * original references aren't orphaned. Any extracts already written
+ * stay (idempotent — calling again with the same plan will fail the
+ * existence check, which is the desired safety).
+ */
+export async function splitDoc(ctx: ToolContext, args: Record<string, unknown>): Promise<unknown> {
+  const argErr = validateArgs(args, ARG_SPEC);
+  if (argErr) return json(argErr);
+  const sourcePath = String(args.source_path ?? "");
+  const rewriteContent = String(args.rewrite_source_content ?? "");
+  const extracts = Array.isArray(args.extracts) ? (args.extracts as ExtractInput[]) : [];
+
+  if (!sourcePath) return json({ error: "source_path required" });
+  if (!rewriteContent) return json({ error: "rewrite_source_content required (provide the new full markdown for the source doc with inline content replaced by wiki-links)" });
+  if (extracts.length === 0) return json({ error: "extracts array must be non-empty" });
+
+  validatePath(sourcePath);
+  for (const e of extracts) {
+    if (!e || typeof e.path !== "string" || typeof e.content !== "string") {
+      return json({ error: "each extract requires { path, content }" });
+    }
+    validatePath(e.path);
+  }
+
+  const index = await loadVaultIndex(ctx);
+  const sourceDoc = index.docs.find((d) => d.path === sourcePath);
+  if (!sourceDoc) return json({ error: "source_not_found", path: sourcePath });
+
+  const existingPaths = new Set(index.docs.map((d) => d.path));
+  const existingTitles = new Map<string, string>();
+  for (const d of index.docs) existingTitles.set(d.title.toLowerCase(), d.path);
+
+  const errors: string[] = [];
+  const seenPaths = new Set<string>();
+  const seenTitles = new Map<string, string>();
+
+  for (const e of extracts) {
+    if (seenPaths.has(e.path)) errors.push(`duplicate extract path in plan: ${e.path}`);
+    seenPaths.add(e.path);
+
+    if (existingPaths.has(e.path)) errors.push(`path already exists in vault: ${e.path}`);
+
+    const title = deriveTitle(e.path, e.content);
+    const titleLc = title.toLowerCase();
+
+    const collidingPath = existingTitles.get(titleLc);
+    if (collidingPath && collidingPath !== sourcePath) {
+      errors.push(`title "${title}" collides with existing doc ${collidingPath} — pick a different H1 or path`);
+    }
+
+    if (seenTitles.has(titleLc)) {
+      errors.push(`two extracts share title "${title}": ${seenTitles.get(titleLc)} and ${e.path}`);
+    }
+    seenTitles.set(titleLc, e.path);
+  }
+
+  if (errors.length > 0) {
+    return json({ error: "validation_failed", errors });
+  }
+
+  // Backup source so we can attempt rollback on partial failure.
+  const sourceBackup = await readVaultFile(ctx, sourcePath);
+  if (sourceBackup === null) return json({ error: "source_disappeared", path: sourcePath });
+
+  const written: string[] = [];
+  try {
+    for (const e of extracts) {
+      await writeVaultFile(ctx, e.path, e.content);
+      written.push(e.path);
+    }
+    await writeVaultFile(ctx, sourcePath, rewriteContent);
+  } catch (err) {
+    return json({
+      error: "write_failed_mid_flight",
+      message: (err as Error).message,
+      extracts_written: written,
+      source_rewritten: false,
+      note: "Source was NOT rewritten so existing references stay valid. Inspect the written extracts and either delete them or call split_doc again with only the remaining extracts.",
+    });
+  }
+
+  return json({
+    ok: true,
+    source_rewritten: sourcePath,
+    extracts_created: extracts.map((e) => ({
+      path: e.path,
+      title: deriveTitle(e.path, e.content),
+    })),
+  });
+}
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}

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

@@ -0,0 +1,116 @@
+import { validatePath, readVaultFile, loadVaultIndex } from "./vault";
+import { resolveWikiLink } from "../../../core/resolveLink";
+import { readTrashedState, writeTrashedState } from "../../trash/state";
+import type { ToolContext } from "./types";
+import { validateArgs } from "./validate_args";
+
+const ARG_SPEC = {
+  allowed: ["path", "original_parent_path"],
+  required: ["path"],
+} as const;
+
+// SPRINT-057 (SIG-008): trash a doc by flagging it in the .emdee/trashed.json
+// sidecar. The markdown is untouched; original Child of / Parent of edges
+// stay in the file so restore is lossless. The trash flag is what the
+// renderer consults to hide it from non-graveyard views.
+//
+// Pre-flight requires the doc to declare a parent via `## Child of`. The
+// first declared parent becomes the restore target. Multi-parent docs use
+// the first bullet — pass `original_parent_path` to override.
+
+const H2_RE = /^##\s+(.+?)\s*$/;
+const FENCE_RE = /^\s*(?:```|~~~)/;
+const BULLET_LINK_RE = /^\s*[-*]\s+\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/i;
+
+function findChildOfFirstWikiLink(content: string): string | null {
+  const lines = content.split("\n");
+  let inFence = false;
+  let inChildOf = false;
+  for (const line of lines) {
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const h = line.match(H2_RE);
+    if (h) {
+      inChildOf = h[1].trim().toLowerCase() === "child of";
+      continue;
+    }
+    if (!inChildOf) continue;
+    const m = line.match(BULLET_LINK_RE);
+    if (m) return m[1].trim();
+  }
+  return null;
+}
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+export async function trashDoc(
+  ctx: ToolContext,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const argErr = validateArgs(args, ARG_SPEC);
+  if (argErr) return json(argErr);
+  const docPath = String(args.path ?? "");
+  const explicitParent =
+    args.original_parent_path !== undefined ? String(args.original_parent_path) : "";
+
+  if (!docPath) return json({ error: "path required" });
+  validatePath(docPath);
+  if (explicitParent) validatePath(explicitParent);
+
+  const content = await readVaultFile(ctx, docPath);
+  if (content === null) return json({ error: "doc_not_found", path: docPath });
+
+  // Resolve original parent. Explicit arg wins; otherwise derive from the
+  // doc's first Child of bullet via the indexer.
+  let originalParent = explicitParent;
+  if (!originalParent) {
+    const parentTitle = findChildOfFirstWikiLink(content);
+    if (!parentTitle) {
+      return json({
+        error: "no_resolvable_parent",
+        path: docPath,
+        hint: "doc has no `## Child of` bullet — pass original_parent_path to record an explicit restore target, or give the doc a parent via patch_section first",
+      });
+    }
+    const index = await loadVaultIndex(ctx);
+    const resolved = resolveWikiLink(index, parentTitle, docPath);
+    if (!resolved || !resolved.path) {
+      return json({
+        error: "unresolved_parent",
+        path: docPath,
+        declared_parent_title: parentTitle,
+        hint: "the doc's Child of bullet points to a non-existent doc — pass original_parent_path to record an explicit restore target",
+      });
+    }
+    originalParent = resolved.path;
+  }
+
+  // Idempotent: already-trashed doc returns ok with the existing entry.
+  const state = await readTrashedState(ctx);
+  if (state[docPath]) {
+    return json({
+      ok: true,
+      path: docPath,
+      original_parent_path: state[docPath].original_parent_path,
+      trashed_at: state[docPath].trashed_at,
+      already_trashed: true,
+    });
+  }
+
+  const trashedAt = new Date().toISOString();
+  state[docPath] = { original_parent_path: originalParent, trashed_at: trashedAt };
+  await writeTrashedState(ctx, state);
+
+  return json({
+    ok: true,
+    path: docPath,
+    original_parent_path: originalParent,
+    trashed_at: trashedAt,
+    already_trashed: false,
+  });
+}