@magic-markdown/cli 0.3.2 → 0.3.6

package/dist/index.js

@@ -392,9 +392,16 @@ function replaceLineRange(markdown, range, replacement) {
   const lines = getLines(markdown);
   const before = lines.slice(0, range.startLine - 1);
   const after = lines.slice(range.endLine);
-  const replacementLines = replacement.length === 0 ? [] : replacement.split(/\r?\n/);
+  const replacementLines = replacementLinesForRange(replacement);
   return [...before, ...replacementLines, ...after].join("\n");
 }
+function replacementLinesForRange(replacement) {
+  if (replacement.length === 0) return [];
+  const normalized = replacement.replace(/\r\n?/g, "\n");
+  const lines = normalized.split("\n");
+  if (normalized.endsWith("\n")) lines.pop();
+  return lines;
+}
 function extractMarkdownImages(markdown, documentPath) {
   const masked = maskCode(markdown);
   const referenceDefinitions = collectReferenceDefinitions(markdown, masked);
@@ -957,8 +964,129 @@ function scoreContext(lines, startLine, endLine, selector) {
   return Math.min(1, score);
 }
 
+// ../core/src/text-merge.ts
+var MAX_DIFF_CELLS = 25e6;
+function mergeText(base, ours, theirs) {
+  if (ours === theirs) return { ok: true, text: ours };
+  if (base === ours) return { ok: true, text: theirs };
+  if (base === theirs) return { ok: true, text: ours };
+  const baseLines = base.split("\n");
+  const ourLines = ours.split("\n");
+  const theirLines = theirs.split("\n");
+  let regionsA;
+  let regionsB;
+  try {
+    regionsA = diffTextRegions(baseLines, ourLines);
+    regionsB = diffTextRegions(baseLines, theirLines);
+  } catch {
+    return { ok: false, reason: "too_large" };
+  }
+  const clusters = clusterRegions(regionsA, regionsB);
+  const merged = [];
+  let baseCursor = 0;
+  for (const cluster of clusters) {
+    for (let line = baseCursor; line < cluster.lo; line += 1) merged.push(baseLines[line]);
+    const baseText = baseLines.slice(cluster.lo, cluster.hi);
+    const ourText = sideSlice(ourLines, regionsA, cluster.lo, cluster.hi);
+    const theirText = sideSlice(theirLines, regionsB, cluster.lo, cluster.hi);
+    const oursChanged = !linesEqual(ourText, baseText);
+    const theirsChanged = !linesEqual(theirText, baseText);
+    if (oursChanged && theirsChanged && !linesEqual(ourText, theirText)) {
+      return { ok: false, reason: "overlapping_changes" };
+    }
+    merged.push(...oursChanged ? ourText : theirText);
+    baseCursor = cluster.hi;
+  }
+  for (let line = baseCursor; line < baseLines.length; line += 1) merged.push(baseLines[line]);
+  return { ok: true, text: merged.join("\n") };
+}
+function diffTextRegions(base, side) {
+  let prefix = 0;
+  while (prefix < base.length && prefix < side.length && base[prefix] === side[prefix]) prefix += 1;
+  let suffix = 0;
+  while (suffix < base.length - prefix && suffix < side.length - prefix && base[base.length - 1 - suffix] === side[side.length - 1 - suffix]) {
+    suffix += 1;
+  }
+  const baseCore = base.slice(prefix, base.length - suffix);
+  const sideCore = side.slice(prefix, side.length - suffix);
+  if (!baseCore.length && !sideCore.length) return [];
+  if ((baseCore.length + 1) * (sideCore.length + 1) > MAX_DIFF_CELLS) throw new Error("diff too large");
+  const rows = baseCore.length + 1;
+  const cols = sideCore.length + 1;
+  const lcs = new Uint32Array(rows * cols);
+  for (let row2 = baseCore.length - 1; row2 >= 0; row2 -= 1) {
+    for (let col2 = sideCore.length - 1; col2 >= 0; col2 -= 1) {
+      lcs[row2 * cols + col2] = baseCore[row2] === sideCore[col2] ? lcs[(row2 + 1) * cols + col2 + 1] + 1 : Math.max(lcs[(row2 + 1) * cols + col2], lcs[row2 * cols + col2 + 1]);
+    }
+  }
+  const regions = [];
+  let row = 0;
+  let col = 0;
+  let pendingBase = -1;
+  let pendingSide = -1;
+  const flush = (baseEnd, sideEnd) => {
+    if (pendingBase < 0) return;
+    regions.push({
+      baseStart: prefix + pendingBase,
+      baseLength: baseEnd - pendingBase,
+      sideStart: prefix + pendingSide,
+      sideLength: sideEnd - pendingSide
+    });
+    pendingBase = -1;
+    pendingSide = -1;
+  };
+  while (row < baseCore.length || col < sideCore.length) {
+    if (row < baseCore.length && col < sideCore.length && baseCore[row] === sideCore[col]) {
+      flush(row, col);
+      row += 1;
+      col += 1;
+    } else {
+      if (pendingBase < 0) {
+        pendingBase = row;
+        pendingSide = col;
+      }
+      if (col >= sideCore.length || row < baseCore.length && lcs[(row + 1) * cols + col] >= lcs[row * cols + col + 1]) {
+        row += 1;
+      } else {
+        col += 1;
+      }
+    }
+  }
+  flush(row, col);
+  return regions;
+}
+function clusterRegions(regionsA, regionsB) {
+  const spans = [...regionsA, ...regionsB].map((region) => ({ lo: region.baseStart, hi: region.baseStart + region.baseLength })).sort((left, right) => left.lo - right.lo || left.hi - right.hi);
+  const clusters = [];
+  for (const span of spans) {
+    const last = clusters.at(-1);
+    if (last && span.lo <= last.hi) {
+      last.hi = Math.max(last.hi, span.hi);
+    } else {
+      clusters.push({ lo: span.lo, hi: span.hi });
+    }
+  }
+  return clusters;
+}
+function sideSlice(side, regions, lo, hi) {
+  return side.slice(lo + sideDeltaBefore(regions, lo, false), hi + sideDeltaBefore(regions, hi, true));
+}
+function sideDeltaBefore(regions, basePos, includeInsertionAt) {
+  let delta = 0;
+  for (const region of regions) {
+    const end = region.baseStart + region.baseLength;
+    if (end > basePos) break;
+    if (end === basePos && region.baseLength === 0 && !includeInsertionAt) break;
+    delta += region.sideLength - region.baseLength;
+  }
+  return delta;
+}
+function linesEqual(left, right) {
+  return left.length === right.length && left.every((line, index) => line === right[index]);
+}
+
 // ../core/src/patches.ts
-function applySuggestion(markdown, suggestion) {
+function applySuggestion(markdown, suggestion, input) {
   if (suggestion.status !== "open") {
     throw new MdocsError(
       "validation_error",
@@ -966,18 +1094,130 @@ function applySuggestion(markdown, suggestion) {
       "Only open suggestions can be applied. List open suggestions with the suggestions command."
     );
   }
-  const current = extractLineRange(markdown, suggestion.patch.range);
-  if (current !== suggestion.patch.before) {
+  const context = applySuggestionContext(input);
+  const baseResult = applySuggestionFromBase(markdown, suggestion, context.baseMarkdown);
+  if (baseResult.kind === "applied") return baseResult.markdown;
+  if (baseResult.kind === "conflict") {
+    throw new MdocsError(
+      "conflict",
+      `Suggestion ${suggestion.id} no longer applies cleanly: the document changed inside the suggested edit.`,
+      "Review the current text around the suggestion, then accept it manually or ask the agent for a fresh suggestion."
+    );
+  }
+  const range = currentSuggestionRange(markdown, suggestion, context.anchor);
+  if (!range) {
     throw new MdocsError(
       "conflict",
       `Suggestion ${suggestion.id} no longer applies cleanly: the document changed since it was created.`,
       "Re-read the document, then create a fresh suggestion against the current content."
     );
   }
-  const next = replaceLineRange(markdown, suggestion.patch.range, suggestion.patch.after);
+  const next = replaceLineRange(markdown, range, suggestion.patch.after);
   assertCleanMarkdown(next);
   return next;
 }
+function applySuggestionContext(input) {
+  if (!input) return {};
+  if ("selector" in input) return { anchor: input };
+  return input;
+}
+function applySuggestionFromBase(markdown, suggestion, baseMarkdown) {
+  if (!baseMarkdown || !suggestion.base?.contentHash) return { kind: "unavailable" };
+  if (contentHashForText(baseMarkdown) !== suggestion.base.contentHash) return { kind: "unavailable" };
+  if (!rangeIsWithin(baseMarkdown, suggestion.patch.range) || extractLineRange(baseMarkdown, suggestion.patch.range) !== suggestion.patch.before) {
+    return { kind: "conflict" };
+  }
+  const rebased = rebaseSuggestionPatch(baseMarkdown, markdown, suggestion);
+  if (rebased !== void 0) return { kind: "applied", markdown: rebased };
+  const suggestedMarkdown = replaceLineRange(baseMarkdown, suggestion.patch.range, suggestion.patch.after);
+  assertCleanMarkdown(suggestedMarkdown);
+  const merged = mergeText(baseMarkdown, markdown, suggestedMarkdown);
+  if (!merged.ok) return { kind: "conflict" };
+  assertCleanMarkdown(merged.text);
+  return { kind: "applied", markdown: merged.text };
+}
+function rebaseSuggestionPatch(baseMarkdown, markdown, suggestion) {
+  const baseLines = getLines(baseMarkdown);
+  const currentLines = getLines(markdown);
+  let regions;
+  try {
+    regions = diffTextRegions(baseLines, currentLines);
+  } catch {
+    return void 0;
+  }
+  const baseStart = suggestion.patch.range.startLine - 1;
+  const baseEnd = suggestion.patch.range.endLine;
+  if (regions.some((region) => regionTouchesSuggestionRange(region, baseStart, baseEnd))) return void 0;
+  const currentStart = baseStart + sideDeltaBefore(regions, baseStart, true);
+  const currentEnd = baseEnd + sideDeltaBefore(regions, baseEnd, false);
+  const currentRange = { startLine: currentStart + 1, endLine: currentEnd };
+  if (!rangeIsWithin(markdown, currentRange)) return void 0;
+  if (extractLineRange(markdown, currentRange) !== suggestion.patch.before) return void 0;
+  const next = replaceLineRange(markdown, currentRange, suggestion.patch.after);
+  assertCleanMarkdown(next);
+  return next;
+}
+function regionTouchesSuggestionRange(region, baseStart, baseEnd) {
+  if (region.baseLength === 0) return region.baseStart > baseStart && region.baseStart < baseEnd;
+  const regionEnd = region.baseStart + region.baseLength;
+  return region.baseStart < baseEnd && regionEnd > baseStart;
+}
+function currentSuggestionRange(markdown, suggestion, anchor) {
+  const hintedRange = suggestion.patch.range;
+  if (rangeIsWithin(markdown, hintedRange) && extractLineRange(markdown, hintedRange) === suggestion.patch.before) return hintedRange;
+  const candidates = findBeforeCandidates(markdown, suggestion.patch.before);
+  if (candidates.length === 0) return void 0;
+  if (candidates.length === 1) return candidates[0];
+  if (!anchor) return void 0;
+  const scored = candidates.map((range) => ({ range, score: scoreContext2(markdown, range, anchor) })).sort((left, right) => right.score - left.score);
+  const best = scored[0];
+  if (!best) return void 0;
+  const tied = scored.filter((candidate) => candidate.score === best.score);
+  if (tied.length > 1) return void 0;
+  if (best.score < 0.7) return void 0;
+  return best.range;
+}
+function findBeforeCandidates(markdown, before) {
+  const lines = getLines(markdown);
+  const beforeLines = linePattern(before);
+  if (beforeLines.length === 0 || beforeLines.length > lines.length) return [];
+  const ranges = [];
+  const beforeText = beforeLines.join("\n");
+  for (let index = 0; index <= lines.length - beforeLines.length; index += 1) {
+    if (lines.slice(index, index + beforeLines.length).join("\n") === beforeText) {
+      ranges.push({ startLine: index + 1, endLine: index + beforeLines.length });
+    }
+  }
+  return ranges;
+}
+function rangeIsWithin(markdown, range) {
+  const lineCount = getLines(markdown).length;
+  return range.startLine >= 1 && range.endLine >= range.startLine && range.endLine <= lineCount;
+}
+function linePattern(value) {
+  return value.replace(/\r\n?/g, "\n").split("\n");
+}
+function scoreContext2(markdown, range, anchor) {
+  const lines = getLines(markdown);
+  let score = anchor.selector.quote === extractLineRange(markdown, range) ? 0.7 : 0.65;
+  const expectedPrefix = contextPrefix(anchor.selector.prefix);
+  if (expectedPrefix) {
+    const actualPrefix = contextPrefix(lines.slice(Math.max(0, range.startLine - 4), range.startLine - 1).join("\n"));
+    if (actualPrefix?.endsWith(expectedPrefix)) score += 0.15;
+  }
+  const expectedSuffix = contextSuffix(anchor.selector.suffix);
+  if (expectedSuffix) {
+    const actualSuffix = contextSuffix(lines.slice(range.endLine, range.endLine + 3).join("\n"));
+    if (actualSuffix?.startsWith(expectedSuffix)) score += 0.15;
+  }
+  return Math.min(1, score);
+}
+function contextPrefix(value) {
+  return value?.split(/\r?\n/).filter(Boolean).slice(-3).join("\n") || void 0;
+}
+function contextSuffix(value) {
+  return value?.split(/\r?\n/).filter(Boolean).slice(0, 3).join("\n") || void 0;
+}
 
 // ../core/src/graph.ts
 function resolveMarkdownLinks(links, currentDocument, documents) {
@@ -1349,6 +1589,8 @@ async function addComment(io, pathOrDocId, range, body, author = defaultActor())
 }
 async function addSuggestion(io, pathOrDocId, range, replacement, message, author = { id: "agent_local", kind: "agent", name: "Local Agent" }, changeSetId) {
   const state = await getDocumentState(io, pathOrDocId);
+  const manifest = await indexWorkspace(io);
+  const entry = manifest.docs.find((doc) => doc.docId === state.docId);
   assertLineRangeWithin(state.markdown, range);
   assertCleanMarkdown(replacement);
   const now = nowIso();
@@ -1374,6 +1616,10 @@ async function addSuggestion(io, pathOrDocId, range, replacement, message, autho
       before,
       after: replacement
     },
+    base: {
+      contentHash: contentHashForText(state.markdown),
+      ...entry?.currentSha ? { head: entry.currentSha } : {}
+    },
     changeSetId,
     createdAt: now,
     updatedAt: now
@@ -1416,7 +1662,8 @@ async function acceptSuggestion(io, suggestionId, actor = defaultActor()) {
     const sidecar = await readSidecar(io, entry.docId);
     const suggestion = sidecar.suggestions.find((candidate) => candidate.id === suggestionId);
     if (!suggestion) continue;
-    const nextMarkdown = applySuggestion(markdown, suggestion);
+    const anchor = sidecar.anchors.find((candidate) => candidate.id === suggestion.anchorId);
+    const nextMarkdown = applySuggestion(markdown, suggestion, anchor);
     await io.writeText(entry.path, nextMarkdown);
     return updateSuggestionStatus(io, suggestionId, "accepted", actor);
   }
@@ -1540,6 +1787,105 @@ function sidecarMarkdownMatchScore(sidecar, markdown) {
   return score;
 }
 
+// ../core/src/context.ts
+function sliceMarkdown(markdown, startLine, endLine) {
+  const lines = markdown.split("\n");
+  const totalLines = lines.length;
+  const sl = startLine ?? 1;
+  const el = endLine ?? totalLines;
+  if (sl < 1 || el > totalLines || sl > el) {
+    throw new MdocsError(
+      "invalid_range",
+      `Line range ${sl}:${el} is out of bounds for a ${totalLines}-line document.`,
+      `Use startLine/endLine or --start-line/--end-line with 1-based line numbers within 1:${totalLines}.`
+    );
+  }
+  return { markdown: lines.slice(sl - 1, el).join("\n"), totalLines, startLine: sl, endLine: el };
+}
+function summarizeDocumentContext(document) {
+  const comments = openComments(document);
+  const suggestions = openSuggestions(document);
+  const currentSha = currentDocumentSha(document);
+  return {
+    docId: document.docId,
+    path: document.path,
+    title: document.title,
+    ...currentSha ? { currentSha } : {},
+    totalLines: document.markdown.split("\n").length,
+    byteLength: new TextEncoder().encode(document.markdown).byteLength,
+    headings: extractMarkdownHeadings(document.markdown),
+    reviewCounts: {
+      openComments: comments.length,
+      openSuggestions: suggestions.length,
+      anchorsNeedingReview: document.anchors.filter((anchor) => anchor.status !== "mapped").length
+    },
+    imageCounts: imageCounts(document.images),
+    linkCounts: linkCounts(document.links)
+  };
+}
+function reviewStateForDocument(document) {
+  const currentSha = currentDocumentSha(document);
+  return {
+    docId: document.docId,
+    path: document.path,
+    title: document.title,
+    ...currentSha ? { currentSha } : {},
+    comments: openComments(document),
+    suggestions: openSuggestions(document),
+    anchors: document.anchors
+  };
+}
+function currentDocumentSha(document) {
+  return "currentSha" in document ? document.currentSha : void 0;
+}
+function extractMarkdownHeadings(markdown) {
+  const headings = [];
+  let fence2;
+  const lines = markdown.split("\n");
+  lines.forEach((line, index) => {
+    const fenceMatch = /^( {0,3})(`{3,}|~{3,})/.exec(line);
+    if (fenceMatch) {
+      const marker = fenceMatch[2]?.[0];
+      if (!fence2) fence2 = marker;
+      else if (marker === fence2) fence2 = void 0;
+      return;
+    }
+    if (fence2) return;
+    const match2 = /^(#{1,6})[ \t]+(.+?)\s*#*\s*$/.exec(line);
+    if (!match2) return;
+    headings.push({
+      level: match2[1].length,
+      text: match2[2].trim(),
+      line: index + 1
+    });
+  });
+  return headings;
+}
+function openComments(document) {
+  return document.sidecar.comments.filter((comment2) => comment2.status === "open");
+}
+function openSuggestions(document) {
+  return document.sidecar.suggestions.filter((suggestion) => suggestion.status === "open");
+}
+function imageCounts(images) {
+  const local = images.filter((image2) => image2.isLocal).length;
+  return {
+    total: images.length,
+    local,
+    remote: images.length - local
+  };
+}
+function linkCounts(links) {
+  return {
+    total: links.length,
+    resolved: links.filter((link2) => link2.status === "resolved").length,
+    ambiguous: links.filter((link2) => link2.status === "ambiguous").length,
+    unresolved: links.filter((link2) => link2.status === "unresolved").length,
+    external: links.filter((link2) => link2.status === "external").length,
+    anchors: links.filter((link2) => link2.status === "anchor").length
+  };
+}
+
 // ../core/src/root-policy.ts
 var DEFAULT_ROOT_PATH_RULES = {
   include: ["**/*.md", "**/*.mdx", ".mdocs/**/*.json"],
@@ -1802,16 +2148,18 @@ function joinWorkspacePath(prefix, path) {
 
 // ../core/src/share-routes.ts
 function parseSharePath(pathname) {
-  const [, workspaceId, rootId, docId] = pathname.match(/^\/share\/([^/]+)\/([^/]+)(?:\/([^/]+))?\/?$/) ?? [];
-  if (!workspaceId || !rootId) return void 0;
+  const [, workspaceId, rootId, docId] = pathname.match(/^\/share\/([^/]+)(?:\/([^/]+)(?:\/([^/]+))?)?\/?$/) ?? [];
+  if (!workspaceId) return void 0;
   return {
     workspaceId: decodeURIComponent(workspaceId),
-    rootId: decodeURIComponent(rootId),
+    rootId: rootId ? decodeURIComponent(rootId) : void 0,
     docId: docId ? decodeURIComponent(docId) : void 0
   };
 }
 function buildSharePath(workspaceId, rootId, docId) {
-  const base = `/share/${encodeURIComponent(workspaceId)}/${encodeURIComponent(rootId)}`;
+  const workspacePath = `/share/${encodeURIComponent(workspaceId)}`;
+  if (!rootId) return workspacePath;
+  const base = `${workspacePath}/${encodeURIComponent(rootId)}`;
   return docId ? `${base}/${encodeURIComponent(docId)}` : base;
 }
 
@@ -10642,7 +10990,7 @@ var RemoteDocumentIO = class {
 };
 
 // src/agent.ts
-var CLI_VERSION = "0.3.2";
+var CLI_VERSION = "0.3.6";
 var CLI_PACKAGE_NAME = "@magic-markdown/cli";
 var AGENT_COMMANDS = [
   {
@@ -10672,11 +11020,12 @@ var AGENT_COMMANDS = [
   {
     name: "join",
     summary: "Join a Magic Markdown share URL through the CLI, announce presence, and remember the session for later rejoin.",
-    usage: "mdocs join <share-url> --scope file|project --doc <docId> --name <agent-name> --json",
+    usage: "mdocs join <share-url> --scope file|project|workspace --doc <docId> --name <agent-name> --json",
     output: "json",
     mutates: true,
     examples: [
       'mdocs join https://example.com/share/workspace/root/doc --scope file --doc doc_abc123 --name "Claude Code" --json',
+      'mdocs join https://example.com/share/workspace --scope workspace --name "Claude Code" --json',
       "mdocs join --json"
     ],
     notes: [
@@ -10694,13 +11043,14 @@ var AGENT_COMMANDS = [
   {
     name: "remote",
     summary: "Read, organize, comment on, suggest edits to, monitor, and restore the active Magic Markdown remote join.",
-    usage: "mdocs remote map|graph|context|create-file|move-file|comment|suggest|reject|events|history|restore|library|create-folder|update-folder|move-root|invite-folder --json",
+    usage: "mdocs remote map|graph|context|review|create-file|move-file|comment|suggest|reject|events|history|restore|library|create-folder|update-folder|move-root|invite-folder --json",
     output: "json",
     mutates: true,
     examples: [
-      "mdocs remote context --json",
-      "mdocs remote context --start-line 1 --end-line 100 --json",
-      "mdocs remote context --start-line 101 --end-line 200 --json",
+      "mdocs remote context --summary --json",
+      "mdocs remote context --start-line 1 --end-line 100 --no-review --json",
+      "mdocs remote context --start-line 101 --end-line 200 --no-review --json",
+      "mdocs remote review --json",
       "mdocs remote map --json",
       "mdocs remote graph --json",
       "mdocs remote create-file docs/new-note.md --with-file /tmp/initial.md --json",
@@ -10716,13 +11066,16 @@ var AGENT_COMMANDS = [
       "mdocs remote invite-folder fold_abc123 --email person@example.com --role edit --json"
     ],
     notes: [
+      "Use remote context --summary --json first on file-scoped joins and before reading large documents. It returns metadata, heading line numbers, current head, review counts, and suggested next commands without dumping Markdown.",
       "remote context accepts --start-line and --end-line (1-based, inclusive) to page through large documents. The response always includes totalLines, startLine, and endLine \u2014 if totalLines > endLine, request the next page with --start-line <endLine+1>.",
+      "Use remote context --no-review when reading document content only; use remote review to list open comments, open suggestions, and anchors separately.",
+      "remote map works on project and workspace-scoped joins. Workspace-scoped map lists every shared Home root; target duplicate paths as <rootId>:<path-or-docId>.",
       "remote graph requires a project-scoped join and returns the shared project's Obsidian-style Markdown/wikilink graph.",
       "remote create-file and remote move-file require a project-scoped join and edit access. They write through the root sync API, so version history and conflict handling stay intact.",
       "remote library, create-folder, update-folder, move-root, and invite-folder use the organization suite on top of the joined project. Folder invites require admin access on the joined root and can only target folders containing that root.",
       "remote comment/suggest never clobber concurrent edits: the server merges review additions, and the CLI rebases and retries automatically if a conflict still occurs.",
       "remote reject <suggestionId> withdraws a suggestion you submitted (for example, a duplicate). You can always withdraw your own; rejecting another author's suggestion requires edit access, and resolving a human's review work needs the user's explicit ask.",
-      "remote events returns truncated: true when older events were dropped from the bounded log; refetch full state with remote context instead of trusting the gap.",
+      "remote events returns truncated: true when older events were dropped from the bounded log; refetch with remote context --summary, then read needed content pages and remote review instead of trusting the gap.",
       "Agents have suggest-only access by default: comments and suggestions work, direct content rewrites are rejected with a forbidden_role error unless a human grants edit access.",
       "remote history lists content-addressed commits (every commit carries a full snapshot); remote restore <headId> restores the joined document to that snapshot as a new commit. Restore requires edit access \u2014 only run it when the user asked."
     ]
@@ -10757,20 +11110,31 @@ var AGENT_COMMANDS = [
   },
   {
     name: "context",
-    summary: "Return agent-ready document Markdown, open review state, anchors, image references, and resolved outgoing links.",
-    usage: "mdocs context <path|docId> [--start-line N] [--end-line N] --json",
+    summary: "Return agent-ready document Markdown, optional review state, image references, and resolved outgoing links.",
+    usage: "mdocs context <path|docId> [--summary] [--no-review] [--start-line N] [--end-line N] --json",
     output: "json",
     mutates: true,
     examples: [
+      "mdocs context docs/example.md --summary --json",
       "mdocs context docs/example.md --json",
-      "mdocs context docs/example.md --start-line 1 --end-line 100 --json",
-      "mdocs context docs/example.md --start-line 101 --end-line 200 --json"
+      "mdocs context docs/example.md --start-line 1 --end-line 100 --no-review --json",
+      "mdocs context docs/example.md --start-line 101 --end-line 200 --no-review --json"
     ],
     notes: [
+      "--summary returns metadata, heading line numbers, review counts, image counts, and link counts without returning Markdown.",
       "The response always includes totalLines, startLine, and endLine. If totalLines > endLine, request the next page with --start-line <endLine+1>.",
-      "--start-line and --end-line are 1-based and inclusive. Omitting both returns the full document."
+      "--start-line and --end-line are 1-based and inclusive. Omitting both returns the full document.",
+      "--no-review omits comments, suggestions, and anchors from content reads; use review/comments/suggestions commands when you need review state."
     ]
   },
+  {
+    name: "review",
+    summary: "Return open comments, open suggestions, and anchors for one document without returning Markdown.",
+    usage: "mdocs review <path|docId> --json",
+    output: "json",
+    mutates: true,
+    examples: ["mdocs review docs/example.md --json"]
+  },
   {
     name: "state",
     summary: "Return full merged Markdown and sidecar state for one document.",
@@ -10803,7 +11167,8 @@ var AGENT_COMMANDS = [
     ],
     notes: [
       "--range is 1-based and inclusive, validated against the current document line count.",
-      "The replacement text replaces the whole range; re-read context first so the range matches current content."
+      "The replacement text replaces the whole range; re-read context first so the range matches current content.",
+      "Prefer the smallest coherent range for the intended revision. If only one sentence inside a line changes, keep the rest of that line identical; use longer ranges only when the broader rewrite is genuinely needed."
     ]
   },
   {
@@ -10887,11 +11252,15 @@ var AGENT_COMMANDS = [
   {
     name: "bridge",
     summary: "Sync a local Markdown root with a Magic workspace over WebSocket (long-running).",
-    usage: "mdocs bridge --workspace <id> --root <path> --url <base-url>",
+    usage: "mdocs bridge --workspace <id> --root <path> --url <base-url> --request-token",
     output: "long-running",
     mutates: true,
-    examples: ["mdocs bridge --workspace workspace_abc --root . --root-id root_abc --url https://magic.example.com"],
-    notes: ["--url (or MDOCS_BASE_URL) is required; the bridge never assumes a localhost server."]
+    examples: ["mdocs bridge --workspace workspace_abc --root . --root-id root_abc --url https://magic.example.com --request-token"],
+    notes: [
+      "--request-token opens a human approval URL and avoids pasting bridge secrets into an agent session.",
+      "--token (or MDOCS_BRIDGE_TOKEN) still works when a scoped bridge token is already available.",
+      "--url (or MDOCS_BASE_URL) is required; the bridge never assumes a localhost server."
+    ]
   },
   {
     name: "serve-mcp",
@@ -10947,15 +11316,18 @@ Run \`mdocs help <command>\` (or \`mdocs <command> --help\`) for usage, examples
 
 1. If given a Magic Markdown share URL, run \`mdocs join <share-url> --json\` first, and always include \`--name "<your agent name>"\` (for example \`--name "Claude Code"\`) so collaborators can see which agent is connected. Use \`mdocs remote ...\` commands after joining.
 2. If working in a local workspace, run \`mdocs doctor --json\` to validate the workspace and learn recommended next commands.
-3. Run \`mdocs map --json\` or \`mdocs remote map --json\` to list documents, paths, docIds, open comments, open suggestions, anchor review counts, and link counts. File-scoped joins (most share links) cover a single document, so \`mdocs remote map\` is unavailable for them \u2014 use \`mdocs remote context --json\` instead. To organize a shared project, rejoin with \`--scope project\` and use \`mdocs remote library --json\`.
+3. Run \`mdocs map --json\` or \`mdocs remote map --json\` to list documents, paths, docIds, open comments, open suggestions, anchor review counts, and link counts. File-scoped joins (most share links) cover a single document, so \`mdocs remote map\` is unavailable for them \u2014 use \`mdocs remote context --summary --json\` instead. Project-scoped joins cover one root; workspace-scoped joins cover Home and can target duplicate paths as \`<rootId>:<path-or-docId>\`.
 4. Run \`mdocs graph --json\` or project-scoped \`mdocs remote graph --json\` before broad edits to inspect the Obsidian-style document graph built from Markdown links and wikilinks.
-5. For a document, run \`mdocs context <path|docId> --json\` locally or \`mdocs remote context <path|docId> --json\` for a joined share.
-6. Use \`mdocs comment\` / \`mdocs remote comment\` for review notes and \`mdocs suggest\` / \`mdocs remote suggest\` for proposed replacements. Do not insert comments, CriticMarkup, directives, or Magic markers into Markdown files.
+5. For a document, run \`mdocs context <path|docId> --summary --json\` locally or \`mdocs remote context <path|docId> --summary --json\` for a joined share before reading full content. Then page Markdown with \`--start-line\` / \`--end-line\` and \`--no-review\` when you only need document text.
+6. Pull review state separately with \`mdocs review <path|docId> --json\` locally or \`mdocs remote review <path|docId> --json\` for a joined share. Use \`mdocs comment\` / \`mdocs remote comment\` for review notes and \`mdocs suggest\` / \`mdocs remote suggest\` for proposed replacements. Do not insert comments, CriticMarkup, directives, or Magic markers into Markdown files.
 
 ## Editing Rules
 
 - Comments and suggestions are sidecar operations. They should not modify clean Markdown until a suggestion is accepted.
 - \`--range <start:end>\` is 1-based and inclusive, and validated against the current document: read the document first and quote line numbers from what you just read.
+- Prefer the smallest coherent suggestion range that contains the actual change. If one sentence, list item, table row, or short paragraph changes, suggest that unit rather than replacing surrounding unchanged paragraphs or sections.
+- Broader paragraph, section, or multi-section rewrites are appropriate when the edit genuinely changes structure, ordering, transitions, or multiple interdependent ideas. Do not avoid a long edit when it is the clearest correct revision.
+- When the narrowest Markdown line contains unchanged surrounding text, keep that unchanged text byte-for-byte identical in the replacement instead of rewording the whole paragraph.
 - Prefer \`--json\` for agent calls and parse stdout as JSON.
 - For multiline suggestion text, write the exact replacement to a temporary file and pass \`--with-file <file>\`.
 - For long comments or messages, use \`--body-file <file>\` or \`--message-file <file>\`.
@@ -10968,14 +11340,14 @@ Run \`mdocs help <command>\` (or \`mdocs <command> --help\`) for usage, examples
 - Errors go to stderr. With \`--json\` they are structured: \`{ "ok": false, "error": { "code", "message", "hint" }, "cliVersion" }\`. Follow the \`hint\`.
 - Exit codes: 0 ok, 1 internal, 2 usage/invalid range, 3 conflict, 4 not found, 5 network, 6 unauthorized (share link revoked or expired).
 - \`remote comment\` and \`remote suggest\` are concurrency-safe: the server merges review additions without clobbering concurrent edits, and the CLI rebases and retries automatically. A surviving \`conflict\` error means the document is changing rapidly \u2014 refetch context and retry.
-- \`remote events --json\` may return \`"truncated": true\` when older events were dropped from the bounded event log. Do not assume nothing happened; refetch full state with \`mdocs remote context --json\`.
+- \`remote events --json\` may return \`"truncated": true\` when older events were dropped from the bounded event log. Do not assume nothing happened; refetch with \`mdocs remote context --summary --json\`, then read needed pages and review state.
 - Retries are safe: remote writes carry a changeId and the server deduplicates replays.
 - Stale reads are safe too: the server merges your change three-way against the version you read, so non-overlapping concurrent edits never conflict. Only true overlaps return \`conflict\`.
 
 ## Access Roles and Version History
 
 - Agents are **suggest-only by default**: comments and suggestions always work, but direct content rewrites are rejected with a \`forbidden_role\` error until a human grants edit access. Propose changes with \`mdocs remote suggest\` instead of rewriting content.
-- Project-scoped agents with edit access can create and move Markdown files and can move the joined root into library folders. Folder invites and folder hierarchy updates require admin access on the joined root.
+- Project-scoped agents with edit access can create and move Markdown files and can move the joined root into library folders. Workspace-scoped agents can read/comment/suggest across Home roots; root organization commands still require a project-scoped join. Folder invites and folder hierarchy updates require admin access on the joined root.
 - Every accepted change is a content-addressed commit with a full snapshot. \`mdocs remote history --json\` lists commits with changed paths; \`mdocs remote restore <headId> --json\` restores the joined document to that snapshot (as a new commit, so it is reversible). Restore requires edit access \u2014 only run it when the user asked.
 
 ## Core Commands
@@ -10990,7 +11362,7 @@ Start the local stdio MCP server with:
 mdocs serve-mcp --cwd /path/to/workspace
 \`\`\`
 
-The MCP server exposes document resources, image resources, workspace map and graph resources, an agent guide resource, typed tools for comments and suggestions, and the \`magic_markdown_agent_workflow\` prompt.
+The MCP server exposes document resources, image resources, workspace map and graph resources, an agent guide resource, typed tools for comments and suggestions, and the \`magic_markdown_agent_workflow\` prompt. Use \`mdocs_context\` / \`magic_context\` with \`summary: true\` before dumping Markdown; use \`includeReview: false\` for content-only reads and \`mdocs_review\` / \`magic_review\` for review state.
 `;
 }
 function formatCommandReference() {
@@ -11414,8 +11786,9 @@ function withMcpImageResources(io, state) {
     }))
   };
 }
-async function contextForDocument(io, path, startLine, endLine) {
+async function contextForDocument(io, path, startLine, endLine, options = {}) {
   const state = await getDocumentState(io, path);
+  if (options.summary) return summarizeDocumentContext(state);
   const { markdown, totalLines, startLine: sl, endLine: el } = sliceMarkdown(state.markdown, startLine, endLine);
   return {
     path: state.path,
@@ -11427,21 +11800,19 @@ async function contextForDocument(io, path, startLine, endLine) {
     markdown,
     images: withMcpImageResources(io, state).images,
     links: state.links,
+    ...options.includeReview === false ? {} : reviewFields(state)
+  };
+}
+async function reviewForDocument(io, path) {
+  return reviewStateForDocument(await getDocumentState(io, path));
+}
+function reviewFields(state) {
+  return {
     comments: state.sidecar.comments.filter((comment2) => comment2.status === "open"),
     suggestions: state.sidecar.suggestions.filter((suggestion) => suggestion.status === "open"),
     anchors: state.anchors
   };
 }
-function sliceMarkdown(markdown, startLine, endLine) {
-  const lines = markdown.split("\n");
-  const totalLines = lines.length;
-  const sl = startLine ?? 1;
-  const el = endLine ?? totalLines;
-  if (sl < 1 || el > totalLines || sl > el) {
-    throw new Error(`Line range ${sl}:${el} is out of bounds for a ${totalLines}-line document.`);
-  }
-  return { markdown: lines.slice(sl - 1, el).join("\n"), totalLines, startLine: sl, endLine: el };
-}
 function imageResourceUri(docId, index) {
   return `mdocs://documents/${docId}/images/${index}`;
 }
@@ -11519,7 +11890,7 @@ var tools = [
   },
   {
     name: "mdocs_context",
-    description: "Return agent-ready document Markdown, open review state, anchors, image references, and resolved outgoing links. Use startLine/endLine to read a specific line range when the full document is too large for one context window. The response always includes totalLines so you know whether to page.",
+    description: "Return agent-ready document Markdown and resolved outgoing links. Use summary=true first to inspect title, line count, headings, current head, and review/link/image counts without dumping the full document. Use includeReview=false when reading content only, and mdocs_review for comments, suggestions, and anchors.",
     inputSchema: {
       type: "object",
       properties: {
@@ -11531,12 +11902,25 @@ var tools = [
         endLine: {
           type: "number",
           description: "1-based last line to include (default: last line of document)."
+        },
+        summary: {
+          type: "boolean",
+          description: "Return metadata, heading outline, current head, and counts instead of Markdown content."
+        },
+        includeReview: {
+          type: "boolean",
+          description: "Whether to include open comments, suggestions, and anchors in the content response (default: true). Use false to keep document reading separate from review state."
         }
       },
       required: ["path"],
       additionalProperties: false
     }
   },
+  {
+    name: "mdocs_review",
+    description: "Return open comments, open suggestions, and mapped anchors for one document without returning document Markdown.",
+    inputSchema: documentPathSchema
+  },
   {
     name: "mdocs_state",
     description: "Return full merged Markdown and sidecar state for one document.",
@@ -11560,14 +11944,14 @@ var tools = [
   },
   {
     name: "mdocs_suggest",
-    description: "Create a sidecar replacement suggestion without modifying clean Markdown.",
+    description: "Create a sidecar replacement suggestion without modifying clean Markdown. Prefer the smallest coherent range; use longer ranges only when the broader rewrite is genuinely needed.",
     inputSchema: {
       type: "object",
       properties: {
         path: documentPathSchema.properties.path,
         startLine: { type: "number", description: "1-based start line." },
         endLine: { type: "number", description: "1-based end line." },
-        replacement: { type: "string", description: "Exact replacement Markdown for the line range." },
+        replacement: { type: "string", description: "Exact replacement Markdown for the line range; keep unchanged surrounding text identical for narrow edits." },
         message: { type: "string", description: "Short explanation for the suggestion." },
         ...actorProperties
       },
@@ -11789,8 +12173,12 @@ async function callTool(io, name, args) {
   if (name === "mdocs_context") {
     const startLine = typeof args.startLine === "number" ? args.startLine : void 0;
     const endLine = typeof args.endLine === "number" ? args.endLine : void 0;
-    return contextForDocument(io, requiredString(args, "path"), startLine, endLine);
+    return contextForDocument(io, requiredString(args, "path"), startLine, endLine, {
+      summary: args.summary === true,
+      includeReview: args.includeReview !== false
+    });
   }
+  if (name === "mdocs_review") return reviewForDocument(io, requiredString(args, "path"));
   if (name === "mdocs_state") return withMcpImageResources(io, await getDocumentState(io, requiredString(args, "path")));
   if (name === "mdocs_comment") {
     return addComment(
@@ -11897,12 +12285,22 @@ async function postPresenceAndReadState(share, shareUrl, docId, agentId, agentNa
   });
 }
 async function fetchState(record) {
-  if (!record.docId) {
+  if (!record.rootId || !record.docId) {
     throw new CliError("usage_error", "This join has no current document.", {
       hint: "Pass a document path or docId, or list documents with mdocs remote map --json."
     });
   }
-  return fetchJson(agentUrl(record, record.docId, "state"), {
+  return fetchJson(agentUrl({ ...record, rootId: record.rootId }, record.docId, "state"), {
+    headers: shareHeaders(record.shareUrl)
+  });
+}
+async function fetchWorkspaceRoots(record) {
+  return fetchJson(`${record.origin}/api/workspaces/${encodeURIComponent(record.workspaceId)}/roots`, {
+    headers: shareHeaders(record.shareUrl)
+  });
+}
+async function fetchWorkspaceLibrary(record) {
+  return fetchJson(`${record.origin}/api/workspaces/${encodeURIComponent(record.workspaceId)}/library`, {
     headers: shareHeaders(record.shareUrl)
   });
 }
@@ -11948,8 +12346,10 @@ async function postFolderInvite(record, folderId, input, actor) {
   );
 }
 async function fetchDocument(record, pathOrDocId) {
+  if (record.scope === "workspace") return fetchWorkspaceDocument(record, pathOrDocId);
+  const rootRecord = requireRootRecord(record);
   if (record.scope === "file" && record.docId) {
-    const document = await fetchDocumentById(record, record.docId);
+    const document = await fetchDocumentById(rootRecord, record.docId);
     if (pathOrDocId === document.docId || pathOrDocId === document.path) return document;
     throw new CliError("usage_error", `This file-scoped join only covers ${document.path} (${document.docId}).`, {
       hint: `Join a share link for ${pathOrDocId} to work on it.`
@@ -11957,19 +12357,19 @@ async function fetchDocument(record, pathOrDocId) {
   }
   if (pathOrDocId.startsWith("doc_") || pathOrDocId === record.docId) {
     try {
-      return await fetchDocumentById(record, pathOrDocId);
+      return await fetchDocumentById(rootRecord, pathOrDocId);
     } catch (error) {
       if (!(error instanceof CliError) || error.code !== "not_found") throw error;
     }
   }
-  const tree = await fetchTree(record);
+  const tree = await fetchTree(rootRecord);
   const docId = tree.docs.find((doc) => doc.docId === pathOrDocId || doc.path === pathOrDocId)?.docId;
   if (!docId) {
     throw new CliError("not_found", `No document matches "${pathOrDocId}" in the joined workspace.`, {
       hint: "List documents and their paths/docIds with mdocs remote map --json."
     });
   }
-  return fetchDocumentById(record, docId);
+  return fetchDocumentById(rootRecord, docId);
 }
 function fetchDocumentById(record, docId) {
   return fetchJson(
@@ -11977,6 +12377,51 @@ function fetchDocumentById(record, docId) {
     { headers: shareHeaders(record.shareUrl) }
   );
 }
+async function fetchWorkspaceDocument(record, pathOrDocId) {
+  if (!pathOrDocId) {
+    throw new CliError("usage_error", "Workspace-scoped context requires a document path or docId.", {
+      hint: "Run mdocs remote map --json, then pass a path, docId, or <rootId>:<path-or-docId>."
+    });
+  }
+  const roots = await fetchWorkspaceRoots(record);
+  const rootIds = new Set(roots.map((root) => root.rootId));
+  const prefixed = splitWorkspaceDocumentTarget(pathOrDocId, rootIds);
+  if (prefixed) {
+    const rootRecord = { ...record, rootId: prefixed.rootId };
+    const tree = await fetchTree(rootRecord);
+    const match3 = tree.docs.find((doc) => doc.docId === prefixed.target || doc.path === prefixed.target);
+    if (!match3) {
+      throw new CliError("not_found", `No document matches "${prefixed.target}" in ${prefixed.rootId}.`, {
+        hint: "Run mdocs remote map --json to verify the root id and document path."
+      });
+    }
+    return fetchDocumentById(rootRecord, match3.docId);
+  }
+  const trees = await Promise.all(roots.map((root) => fetchTree({ ...record, rootId: root.rootId })));
+  const matches = trees.flatMap(
+    (tree) => tree.docs.filter((doc) => doc.docId === pathOrDocId || doc.path === pathOrDocId).map((doc) => ({ rootId: tree.root.rootId, doc }))
+  );
+  if (matches.length === 0) {
+    throw new CliError("not_found", `No document matches "${pathOrDocId}" in the joined Home workspace.`, {
+      hint: "Run mdocs remote map --json to list roots, paths, and docIds."
+    });
+  }
+  if (matches.length > 1) {
+    throw new CliError("usage_error", `Document target "${pathOrDocId}" is ambiguous across ${matches.length} roots.`, {
+      hint: `Prefix the target with a root id, for example ${matches[0].rootId}:${pathOrDocId}.`
+    });
+  }
+  const match2 = matches[0];
+  return fetchDocumentById({ ...record, rootId: match2.rootId }, match2.doc.docId);
+}
+function splitWorkspaceDocumentTarget(value, rootIds) {
+  const separator = value.indexOf(":");
+  if (separator <= 0) return void 0;
+  const rootId = value.slice(0, separator);
+  if (!rootIds.has(rootId)) return void 0;
+  const target = value.slice(separator + 1);
+  return target ? { rootId, target } : void 0;
+}
 async function postReview(record, docId, additions, actor) {
   const response = await fetchJson(
     `${record.origin}/api/workspaces/${encodeURIComponent(record.workspaceId)}/roots/${encodeURIComponent(record.rootId)}/documents/${encodeURIComponent(docId)}/review`,
@@ -12059,7 +12504,7 @@ function conflictError(eventPayload) {
   const conflict = eventPayload ?? {};
   const head = typeof conflict.canonicalHead === "string" ? ` Current head: ${conflict.canonicalHead}.` : "";
   return new CliError("conflict", `Remote change was not accepted: the document changed since it was read.${head}`, {
-    hint: "Refetch with mdocs remote context --json, re-apply your change against the fresh content, and retry.",
+    hint: "Refetch with mdocs remote context --summary --json, re-apply your change against the needed fresh content range, and retry.",
     details: eventPayload
   });
 }
@@ -12070,6 +12515,14 @@ function agentUrl(record, docId, action, query) {
 function libraryUrl(record) {
   return `${record.origin}/api/workspaces/${encodeURIComponent(record.workspaceId)}/roots/${encodeURIComponent(record.rootId)}/library`;
 }
+function requireRootRecord(record) {
+  if (!record.rootId) {
+    throw new CliError("usage_error", "This command needs a root-scoped join.", {
+      hint: "For Home joins, pass a document target from `mdocs remote map --json`, or use a project share for root organization commands."
+    });
+  }
+  return { origin: record.origin, workspaceId: record.workspaceId, rootId: record.rootId, shareUrl: record.shareUrl };
+}
 function shareHeaders(shareUrl) {
   return { Referer: shareUrl, Authorization: `Bearer ${shareUrl}` };
 }
@@ -12107,7 +12560,7 @@ function remoteHttpError(status, value, text2) {
   }
   if (status === 409) {
     return new CliError("conflict", message, {
-      hint: "Refetch with mdocs remote context --json and retry.",
+      hint: "Refetch with mdocs remote context --summary --json and retry.",
       details: value
     });
   }
@@ -12248,9 +12701,10 @@ async function runJoinCommand(root, parsed) {
   const parsedShare = parseShareUrl(target, parsed.flags);
   const agentName = resolveAgentName(parsed.flags);
   const agentId = normalizeAgentId(String(parsed.flags["agent-id"] ?? parsed.flags.actor ?? agentName));
-  const docId = parsedShare.docId ?? await firstDocIdForProject(parsedShare);
+  const rootScopedShare = rootScopedRecord(parsedShare);
+  const docId = parsedShare.docId ?? (rootScopedShare ? await firstDocIdForProject(rootScopedShare) : void 0);
   const shareUrl = shareUrlForScope(target, { ...parsedShare, docId });
-  const state = await postPresenceAndReadState(parsedShare, shareUrl, docId, agentId, agentName);
+  const state = rootScopedShare && docId ? await postPresenceAndReadState(rootScopedShare, shareUrl, docId, agentId, agentName) : void 0;
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const record = {
     joinId: joinIdFor(target),
@@ -12265,10 +12719,10 @@ async function runJoinCommand(root, parsed) {
     joinedAt: now,
     updatedAt: now,
     lastSeenEventId: 0,
-    currentHead: state.document.currentSha
+    currentHead: state?.document.currentSha
   };
   await writeJoinRecord(root, record);
-  return joinSummary(record, state.document);
+  return joinSummary(record, state?.document);
 }
 async function runJoinsCommand(root) {
   return listJoinRecords(root);
@@ -12277,18 +12731,23 @@ async function runRemoteCommand(root, subcommand, parsed) {
   const record = await normalizedSelectedJoin(root, parsed.flags);
   switch (subcommand) {
     case "map":
-    case void 0:
+    case void 0: {
       if (record.scope === "file") {
         throw new CliError("usage_error", "This join is file-scoped, so the project tree is not accessible.", {
-          hint: "Use `mdocs remote context --json` to read the joined document."
+          hint: "Use `mdocs remote context --summary --json` to inspect the joined document."
         });
       }
-      await refreshPresence(record, record.docId);
-      return fetchTree(record);
+      if (record.scope === "workspace") return remoteWorkspaceMap(record);
+      const rootRecord = assertRootScoped(record, "map");
+      await refreshPresence(rootRecord, record.docId);
+      return fetchTree(rootRecord);
+    }
     case "graph":
       return remoteGraph(record);
     case "context":
       return remoteContext(record, parsed.command[2], parsed.flags);
+    case "review":
+      return remoteReview(record, parsed.command[2]);
     case "create-file":
       return remoteCreateFile(root, record, parsed);
     case "move-file":
@@ -12305,10 +12764,13 @@ async function runRemoteCommand(root, subcommand, parsed) {
       return remoteHistory(record, parsed.flags);
     case "restore":
       return remoteRestore(record, parsed);
-    case "library":
+    case "library": {
+      if (record.scope === "workspace") return fetchWorkspaceLibrary(record);
       assertProjectScope(record, "library");
-      await refreshPresence(record, record.docId);
-      return fetchLibrary(record);
+      const rootRecord = assertRootScoped(record, "library");
+      await refreshPresence(rootRecord, record.docId);
+      return fetchLibrary(rootRecord);
+    }
     case "create-folder":
       return remoteCreateFolder(record, parsed);
     case "update-folder":
@@ -12321,15 +12783,16 @@ async function runRemoteCommand(root, subcommand, parsed) {
       return rejoin(root, record.joinId, parsed.flags);
     default:
       throw new CliError("usage_error", `Unknown remote subcommand: ${subcommand}`, {
-        hint: "Use mdocs remote map|graph|context|create-file|move-file|comment|suggest|reject|events|history|restore|library|create-folder|update-folder|move-root|invite-folder|rejoin."
+        hint: "Use mdocs remote map|graph|context|review|create-file|move-file|comment|suggest|reject|events|history|restore|library|create-folder|update-folder|move-root|invite-folder|rejoin."
       });
   }
 }
 async function remoteGraph(record) {
   assertProjectScope(record, "graph");
-  await refreshPresence(record, record.docId);
-  const tree = await fetchTree(record);
-  const documents = await Promise.all(tree.docs.map((doc) => fetchDocument(record, doc.docId)));
+  const rootRecord = assertRootScoped(record, "graph");
+  await refreshPresence(rootRecord, record.docId);
+  const tree = await fetchTree(rootRecord);
+  const documents = await Promise.all(tree.docs.map((doc) => fetchDocument(rootScopedRecordFor(record, rootRecord.rootId), doc.docId)));
   const lookup = documents.map((doc) => ({ docId: doc.docId, path: doc.path, title: doc.title }));
   const graphDocuments = documents.map((doc) => {
     const links = doc.links ?? resolveMarkdownLinks(extractMarkdownLinks(doc.markdown), doc, lookup);
@@ -12347,10 +12810,37 @@ async function remoteGraph(record) {
   });
   return buildWorkspaceGraph(record.workspaceId, SIDECAR_SCHEMA_VERSION, graphDocuments);
 }
+async function remoteWorkspaceMap(record) {
+  const roots = await fetchWorkspaceRoots(record);
+  const trees = await Promise.all(roots.map((root) => fetchTree(rootScopedRecordFor(record, root.rootId))));
+  const library = await fetchWorkspaceLibrary(record).catch(() => void 0);
+  return {
+    workspaceId: record.workspaceId,
+    scope: "workspace",
+    roots: trees.map((tree) => ({
+      root: tree.root,
+      docs: tree.docs.map((doc) => ({
+        rootId: tree.root.rootId,
+        docId: doc.docId,
+        path: doc.path,
+        title: doc.title,
+        openComments: doc.openComments,
+        openSuggestions: doc.openSuggestions,
+        anchorsNeedingReview: doc.anchorsNeedingReview,
+        outgoingLinks: doc.outgoingLinks,
+        incomingLinks: doc.incomingLinks,
+        unresolvedLinks: doc.unresolvedLinks,
+        externalLinks: doc.externalLinks
+      }))
+    })),
+    ...library ? { folders: library.folders } : {}
+  };
+}
 async function remoteHistory(record, flags) {
-  await refreshPresence(record, record.docId);
+  const rootRecord = assertRootScoped(record, "history");
+  await refreshPresence(rootRecord, record.docId);
   const limit = typeof flags.limit === "string" ? Number(flags.limit) || 50 : 50;
-  return fetchCommits(record, limit);
+  return fetchCommits(rootRecord, limit);
 }
 async function remoteRestore(record, parsed) {
   const headId = parsed.command[2];
@@ -12359,9 +12849,10 @@ async function remoteRestore(record, parsed) {
       hint: "List restorable commits with mdocs remote history --json, then run mdocs remote restore <headId>."
     });
   }
-  await refreshPresence(record, record.docId);
   const restoreAll = parsed.flags.all === true || parsed.flags.all === "true";
   let docId;
+  const rootRecord = assertRootScoped(record, "restore");
+  await refreshPresence(rootRecord, record.docId);
   if (!restoreAll) {
     const target = typeof parsed.flags.doc === "string" ? parsed.flags.doc : record.docId;
     if (!target) {
@@ -12371,22 +12862,23 @@ async function remoteRestore(record, parsed) {
     }
     docId = (await fetchDocument(record, target)).docId;
   }
-  return postRestore(record, headId, docId);
+  return postRestore(rootRecord, headId, docId);
 }
 async function rejoin(root, joinId, flags) {
   const record = await readSelectedJoin(root, { ...flags, ...joinId ? { join: joinId } : {} });
-  const docId = record.docId ?? await firstDocIdForProject(record);
+  const rootRecord = rootScopedRecord(record);
+  const docId = record.docId ?? (rootRecord ? await firstDocIdForProject(rootRecord) : void 0);
   const shareUrl = shareUrlForScope(record.shareUrl, { ...record, docId });
-  const state = await postPresenceAndReadState(record, shareUrl, docId, record.agentId, record.agentName);
+  const state = rootRecord && docId ? await postPresenceAndReadState(rootRecord, shareUrl, docId, record.agentId, record.agentName) : void 0;
   const next = {
     ...record,
     shareUrl,
     docId,
     updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    currentHead: state.document.currentSha
+    currentHead: state?.document.currentSha
   };
   await writeJoinRecord(root, next);
-  return joinSummary(next, state.document);
+  return joinSummary(next, state?.document);
 }
 async function normalizedSelectedJoin(root, flags) {
   const record = await readSelectedJoin(root, flags);
@@ -12403,19 +12895,13 @@ async function refreshPresence(record, docId) {
 }
 async function remoteContext(record, pathOrDocId, flags = {}) {
   const document = pathOrDocId ? await fetchDocument(record, pathOrDocId) : (await fetchState(record)).document;
-  await refreshPresence(record, document.docId);
+  await refreshPresence(rootScopedRecordFor(record, document.rootId), document.docId);
+  if (flags.summary || flags["metadata-only"]) {
+    return withRemoteSummaryNextCommands(summarizeDocumentContext(document), record, document, pathOrDocId);
+  }
   const startLine = typeof flags["start-line"] === "string" ? Number(flags["start-line"]) : void 0;
   const endLine = typeof flags["end-line"] === "string" ? Number(flags["end-line"]) : void 0;
-  const lines = document.markdown.split("\n");
-  const totalLines = lines.length;
-  const sl = startLine ?? 1;
-  const el = endLine ?? totalLines;
-  if (sl < 1 || el > totalLines || sl > el) {
-    throw new CliError("invalid_range", `Line range ${sl}:${el} is out of bounds for a ${totalLines}-line document.`, {
-      hint: `Use --start-line and --end-line with 1-based line numbers within 1:${totalLines}.`
-    });
-  }
-  const markdown = startLine !== void 0 || endLine !== void 0 ? lines.slice(sl - 1, el).join("\n") : document.markdown;
+  const { markdown, totalLines, startLine: sl, endLine: el } = sliceMarkdown(document.markdown, startLine, endLine);
   return {
     joinId: record.joinId,
     scope: record.scope,
@@ -12427,22 +12913,51 @@ async function remoteContext(record, pathOrDocId, flags = {}) {
     startLine: sl,
     endLine: el,
     markdown,
-    comments: document.sidecar.comments.filter((comment2) => comment2.status === "open"),
-    suggestions: document.sidecar.suggestions.filter((suggestion) => suggestion.status === "open"),
-    anchors: document.anchors,
+    ...flags["no-review"] ? {} : {
+      comments: document.sidecar.comments.filter((comment2) => comment2.status === "open"),
+      suggestions: document.sidecar.suggestions.filter((suggestion) => suggestion.status === "open"),
+      anchors: document.anchors
+    },
     images: document.images,
     links: document.links
   };
 }
+async function remoteReview(record, pathOrDocId) {
+  const document = pathOrDocId ? await fetchDocument(record, pathOrDocId) : (await fetchState(record)).document;
+  await refreshPresence(rootScopedRecordFor(record, document.rootId), document.docId);
+  return {
+    joinId: record.joinId,
+    scope: record.scope,
+    ...reviewStateForDocument(document)
+  };
+}
+function withRemoteSummaryNextCommands(summary, record, document, requestedTarget) {
+  const target = remoteCommandTarget(record, document, requestedTarget);
+  const firstEnd = Math.min(summary.totalLines, 120);
+  return {
+    ...summary,
+    nextCommands: [
+      `mdocs remote context${target} --start-line 1 --end-line ${firstEnd} --no-review --json`,
+      summary.totalLines > firstEnd ? `mdocs remote context${target} --start-line ${firstEnd + 1} --end-line ${Math.min(summary.totalLines, firstEnd + 120)} --no-review --json` : void 0,
+      summary.reviewCounts.openComments || summary.reviewCounts.openSuggestions || summary.reviewCounts.anchorsNeedingReview ? `mdocs remote review${target} --json` : void 0
+    ].filter((command) => Boolean(command))
+  };
+}
+function remoteCommandTarget(record, document, requestedTarget) {
+  if (record.scope === "file" && (!requestedTarget || requestedTarget === document.docId || requestedTarget === document.path)) return "";
+  if (record.scope === "workspace") return ` ${document.rootId}:${document.docId}`;
+  return ` ${document.docId}`;
+}
 async function remoteCreateFile(root, record, parsed) {
   assertProjectScope(record, "create-file");
+  const rootRecord = assertRootScoped(record, "create-file");
   const path = parsed.command[2];
   if (!path) {
     throw new CliError("usage_error", "Missing file path.", {
       hint: "Run mdocs remote create-file <path> --with-file /tmp/initial.md --json."
     });
   }
-  const tree = await fetchTree(record);
+  const tree = await fetchTree(rootRecord);
   const markdownInput = await readOptionalTextFlag(parsed.flags, root, ["with", "markdown", "body"]);
   const markdown = markdownInput ?? defaultMarkdown(path);
   const normalizedPath = normalizeRemoteWorkspacePath(path, tree.root.pathRules, Buffer.byteLength(markdown, "utf8"));
@@ -12455,8 +12970,8 @@ async function remoteCreateFile(root, record, parsed) {
   const title = titleFromMarkdown(normalizedPath, markdown);
   const sidecar = emptySidecar(docId, normalizedPath, title);
   const baseDocument = {
-    workspaceId: record.workspaceId,
-    rootId: record.rootId,
+    workspaceId: rootRecord.workspaceId,
+    rootId: rootRecord.rootId,
     docId,
     path: normalizedPath,
     title,
@@ -12469,12 +12984,13 @@ async function remoteCreateFile(root, record, parsed) {
     openSuggestions: 0,
     currentSha: tree.root.canonical.head
   };
-  const document = await pushDocument(record, baseDocument, markdown, sidecar);
+  const document = await pushDocument(rootRecord, baseDocument, markdown, sidecar);
   await recordHead(root, record, document);
   return { document };
 }
 async function remoteMoveFile(root, record, parsed) {
   assertProjectScope(record, "move-file");
+  const rootRecord = assertRootScoped(record, "move-file");
   const pathOrDocId = parsed.command[2];
   if (!pathOrDocId) {
     throw new CliError("usage_error", "Missing source document path or docId.", {
@@ -12483,7 +12999,7 @@ async function remoteMoveFile(root, record, parsed) {
   }
   const nextPathFlag = requiredFlag(parsed.flags, "to");
   const document = await fetchDocument(record, pathOrDocId);
-  const tree = await fetchTree(record);
+  const tree = await fetchTree(rootRecord);
   const nextPath = normalizeRemoteWorkspacePath(nextPathFlag, tree.root.pathRules, Buffer.byteLength(document.markdown, "utf8"));
   if (tree.docs.some((doc) => doc.docId !== document.docId && doc.path === nextPath)) {
     throw new CliError("validation_error", `Document already exists: ${nextPath}`, {
@@ -12491,7 +13007,7 @@ async function remoteMoveFile(root, record, parsed) {
     });
   }
   const moved = await pushDocument(
-    record,
+    rootScopedRecordFor(record, document.rootId),
     { ...document, path: nextPath, title: titleFromMarkdown(nextPath, document.markdown) },
     document.markdown,
     document.sidecar
@@ -12524,13 +13040,15 @@ async function remoteSuggest(root, record, parsed) {
 }
 async function remoteCreateFolder(record, parsed) {
   assertProjectScope(record, "create-folder");
+  const rootRecord = assertRootScoped(record, "create-folder");
   const name = folderNameFromArgs(parsed);
   const parentId = optionalFolderTarget(parsed.flags.parent);
-  await refreshPresence(record, record.docId);
-  return postLibraryFolder(record, { name, ...parentId ? { parentId } : {} }, actorForRecord(record));
+  await refreshPresence(rootRecord, record.docId);
+  return postLibraryFolder(rootRecord, { name, ...parentId ? { parentId } : {} }, actorForRecord(record));
 }
 async function remoteUpdateFolder(record, parsed) {
   assertProjectScope(record, "update-folder");
+  const rootRecord = assertRootScoped(record, "update-folder");
   const folderId = parsed.command[2];
   if (!folderId) {
     throw new CliError("usage_error", "Missing folder id.", {
@@ -12546,22 +13064,24 @@ async function remoteUpdateFolder(record, parsed) {
       hint: "Pass --name <name>, --parent <folderId>, or --home."
     });
   }
-  await refreshPresence(record, record.docId);
-  return patchLibraryFolder(record, folderId, input, actorForRecord(record));
+  await refreshPresence(rootRecord, record.docId);
+  return patchLibraryFolder(rootRecord, folderId, input, actorForRecord(record));
 }
 async function remoteMoveRoot(record, parsed) {
   assertProjectScope(record, "move-root");
+  const rootRecord = assertRootScoped(record, "move-root");
   const folderId = parsed.flags.home === true || parsed.flags.home === "true" ? null : optionalFolderTarget(parsed.flags.folder);
   if (folderId === void 0) {
     throw new CliError("usage_error", "Missing target folder.", {
       hint: "Pass --folder <folderId> to move into a folder, or --home to move to the top level."
     });
   }
-  await refreshPresence(record, record.docId);
-  return postMoveRoot(record, folderId, actorForRecord(record));
+  await refreshPresence(rootRecord, record.docId);
+  return postMoveRoot(rootRecord, folderId, actorForRecord(record));
 }
 async function remoteInviteFolder(record, parsed) {
   assertProjectScope(record, "invite-folder");
+  const rootRecord = assertRootScoped(record, "invite-folder");
   const folderId = parsed.command[2];
   if (!folderId) {
     throw new CliError("usage_error", "Missing folder id.", {
@@ -12575,14 +13095,14 @@ async function remoteInviteFolder(record, parsed) {
       hint: "Use --role read, suggest, edit, or admin."
     });
   }
-  await refreshPresence(record, record.docId);
-  return postFolderInvite(record, folderId, { email, role }, actorForRecord(record));
+  await refreshPresence(rootRecord, record.docId);
+  return postFolderInvite(rootRecord, folderId, { email, role }, actorForRecord(record));
 }
 async function remoteReject(root, record, parsed) {
   const suggestionId = parsed.command[2];
   if (!suggestionId) {
     throw new CliError("usage_error", "Missing suggestion id.", {
-      hint: "List open suggestions with mdocs remote context --json, then run mdocs remote reject <suggestionId>."
+      hint: "List open suggestions with mdocs remote review --json, then run mdocs remote reject <suggestionId>."
     });
   }
   const pathOrDocId = parsed.command[3] ?? record.docId;
@@ -12592,12 +13112,13 @@ async function remoteReject(root, record, parsed) {
     });
   }
   let document = await fetchDocument(record, pathOrDocId);
-  await refreshPresence(record, document.docId);
+  let documentRecord = rootScopedRecordFor(record, document.rootId);
+  await refreshPresence(documentRecord, document.docId);
   const actor = actorForRecord(record);
   const suggestion = document.sidecar.suggestions.find((candidate) => candidate.id === suggestionId);
   if (!suggestion) {
     throw new CliError("not_found", `Unknown suggestion: ${suggestionId}`, {
-      hint: "List suggestion ids with mdocs remote context --json."
+      hint: "List suggestion ids with mdocs remote review --json."
     });
   }
   if (suggestion.status !== "open") {
@@ -12607,7 +13128,7 @@ async function remoteReject(root, record, parsed) {
   }
   try {
     const additions = { anchors: [], comments: [], suggestions: [], withdrawSuggestionIds: [suggestionId] };
-    const pushed = await postReview(record, document.docId, additions, actor);
+    const pushed = await postReview(documentRecord, document.docId, additions, actor);
     await recordHead(root, record, pushed);
     const updated = pushed.sidecar.suggestions.find((candidate) => candidate.id === suggestionId);
     return { suggestion: updated ?? suggestion, document: pushed };
@@ -12621,11 +13142,12 @@ async function remoteReject(root, record, parsed) {
   }
   for (let index = 0; index < PUSH_REBASE_ATTEMPTS; index += 1) {
     if (index > 0) document = await fetchDocument(record, document.docId);
+    documentRecord = rootScopedRecordFor(record, document.rootId);
     const io = new RemoteDocumentIO(document);
     const rejected = await rejectSuggestion(io, suggestionId, actor);
     const state = await getDocumentState(io, document.docId);
     try {
-      const pushed = await pushDocument(record, document, state.markdown, state.sidecar);
+      const pushed = await pushDocument(documentRecord, document, state.markdown, state.sidecar);
       await recordHead(root, record, pushed);
       return { suggestion: rejected, document: pushed };
     } catch (error) {
@@ -12634,7 +13156,7 @@ async function remoteReject(root, record, parsed) {
     }
   }
   throw new CliError("conflict", "Remote change was not accepted after retries.", {
-    hint: "The document is changing rapidly. Refetch with mdocs remote context --json and retry."
+    hint: "The document is changing rapidly. Refetch with mdocs remote context --summary --json, then retry against the needed content range."
   });
 }
 function isWithdrawalUnsupported(error) {
@@ -12650,7 +13172,8 @@ async function submitReview(root, record, pathOrDocId, mutate) {
     });
   }
   let document = await fetchDocument(record, pathOrDocId);
-  await refreshPresence(record, document.docId);
+  let documentRecord = rootScopedRecordFor(record, document.rootId);
+  await refreshPresence(documentRecord, document.docId);
   const build = async (base) => {
     const io = new RemoteDocumentIO(base);
     const created = await mutate(io, base.docId);
@@ -12667,7 +13190,7 @@ async function submitReview(root, record, pathOrDocId, mutate) {
   };
   let attempt = await build(document);
   try {
-    const pushed = await postReview(record, document.docId, attempt.additions, actorForRecord(record));
+    const pushed = await postReview(documentRecord, document.docId, attempt.additions, actorForRecord(record));
     await recordHead(root, record, pushed);
     return { created: attempt.created, document: pushed };
   } catch (error) {
@@ -12676,10 +13199,11 @@ async function submitReview(root, record, pathOrDocId, mutate) {
   for (let index = 0; index < PUSH_REBASE_ATTEMPTS; index += 1) {
     if (index > 0) {
       document = await fetchDocument(record, document.docId);
+      documentRecord = rootScopedRecordFor(record, document.rootId);
       attempt = await build(document);
     }
     try {
-      const pushed = await pushDocument(record, document, attempt.state.markdown, attempt.state.sidecar);
+      const pushed = await pushDocument(documentRecord, document, attempt.state.markdown, attempt.state.sidecar);
       await recordHead(root, record, pushed);
       return { created: attempt.created, document: pushed };
     } catch (error) {
@@ -12688,7 +13212,7 @@ async function submitReview(root, record, pathOrDocId, mutate) {
     }
   }
   throw new CliError("conflict", "Remote change was not accepted after retries.", {
-    hint: "The document is changing rapidly. Refetch with mdocs remote context --json and retry."
+    hint: "The document is changing rapidly. Refetch with mdocs remote context --summary --json, then retry against the needed content range."
   });
 }
 function isReviewEndpointUnsupported(error) {
@@ -12703,8 +13227,9 @@ async function recordHead(root, record, document) {
 }
 async function remoteEvents(root, record, flags) {
   const after = typeof flags.after === "string" ? Number(flags.after) : record.lastSeenEventId;
-  await refreshPresence(record, record.docId);
-  const response = await fetchPendingEvents(record, after);
+  const rootRecord = assertRootScoped(record, "events");
+  await refreshPresence(rootRecord, record.docId);
+  const response = await fetchPendingEvents(rootRecord, after);
   await writeJoinRecord(root, {
     ...record,
     updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -12713,7 +13238,7 @@ async function remoteEvents(root, record, flags) {
   if (response.truncated) {
     return {
       ...response,
-      hint: "Older events were dropped from the bounded event log. Refetch full state with mdocs remote context --json instead of relying on the event stream."
+      hint: "Older events were dropped from the bounded event log. Refetch with mdocs remote context --summary --json, then read needed content pages and review state."
     };
   }
   return response;
@@ -12722,11 +13247,11 @@ function parseShareUrl(value, flags) {
   const url = new URL(value);
   const route = parseSharePath(url.pathname);
   if (!route) {
-    throw new CliError("usage_error", "Share URL must be a Magic Markdown /share/<workspace>/<root>[/doc] URL.", {
+    throw new CliError("usage_error", "Share URL must be a Magic Markdown /share/<workspace>[/<root>[/doc]] URL.", {
       hint: "Copy the share link from the Magic Markdown share dialog."
     });
   }
-  const scope = flags.scope === "project" || !route.docId && flags.scope !== "file" ? "project" : "file";
+  const scope = flags.scope === "workspace" || !route.rootId ? "workspace" : flags.scope === "project" || !route.docId && flags.scope !== "file" ? "project" : "file";
   const explicitDoc = typeof flags.doc === "string" ? flags.doc : typeof flags["doc-id"] === "string" ? flags["doc-id"] : void 0;
   return {
     joinId: joinIdFor(value),
@@ -12734,8 +13259,8 @@ function parseShareUrl(value, flags) {
     shareUrl: value,
     origin: url.origin,
     workspaceId: route.workspaceId,
-    rootId: route.rootId,
-    docId: explicitDoc ?? route.docId,
+    rootId: scope === "workspace" ? void 0 : route.rootId,
+    docId: scope === "workspace" ? void 0 : explicitDoc ?? route.docId,
     agentId: "",
     agentName: "",
     joinedAt: "",
@@ -12745,7 +13270,11 @@ function parseShareUrl(value, flags) {
 }
 function shareUrlForScope(value, record) {
   const url = new URL(value);
-  url.pathname = buildSharePath(record.workspaceId, record.rootId, record.scope === "file" ? record.docId : void 0);
+  url.pathname = buildSharePath(
+    record.workspaceId,
+    record.scope === "workspace" ? void 0 : record.rootId,
+    record.scope === "file" ? record.docId : void 0
+  );
   return url.toString();
 }
 function joinSummary(record, document) {
@@ -12756,16 +13285,19 @@ function joinSummary(record, document) {
     workspaceId: record.workspaceId,
     rootId: record.rootId,
     docId: record.docId,
-    currentHead: document.currentSha,
-    document: {
-      docId: document.docId,
-      path: document.path,
-      title: document.title
-    },
+    currentHead: document?.currentSha,
+    ...document ? {
+      document: {
+        docId: document.docId,
+        path: document.path,
+        title: document.title
+      }
+    } : {},
     nextCommands: [
-      "mdocs remote context --json",
+      record.scope === "workspace" ? "mdocs remote map --json" : "mdocs remote context --summary --json",
       record.scope === "project" ? "mdocs remote map --json" : void 0,
-      "mdocs remote events --json"
+      record.scope === "workspace" ? "mdocs remote library --json" : void 0,
+      record.scope === "workspace" ? void 0 : "mdocs remote events --json"
     ].filter(Boolean)
   };
 }
@@ -12775,6 +13307,22 @@ function assertProjectScope(record, command) {
     hint: "Rejoin the share with `mdocs join <share-url> --scope project --json`, then retry."
   });
 }
+function assertRootScoped(record, command) {
+  if (record.rootId) return rootScopedRecordFor(record, record.rootId);
+  throw new CliError("usage_error", `remote ${command} needs a specific project root.`, {
+    hint: "For Home workspace joins, run `mdocs remote map --json` and use a document target, or join a project share for root organization commands."
+  });
+}
+function rootScopedRecord(record) {
+  return record.rootId ? rootScopedRecordFor(record, record.rootId) : void 0;
+}
+function rootScopedRecordFor(record, rootId) {
+  return {
+    ...record,
+    rootId,
+    scope: record.scope === "file" ? "file" : "project"
+  };
+}
 function emptySidecar(docId, path, title) {
   return {
     schemaVersion: SIDECAR_SCHEMA_VERSION,
@@ -12823,6 +13371,7 @@ async function runBridge(options) {
   const root = resolve4(options.root);
   const localManifestSource = await readLocalSource(root);
   const rootId = options.rootId ?? options.sourceId ?? localManifestSource?.sourceId ?? rootIdForPath(root);
+  const token = options.token ?? (options.requestToken ? await requestBridgeToken(options, rootId) : void 0);
   const replicaId = `replica_${createHash2("sha256").update(`${root}:${options.actorId}`).digest("hex").slice(0, 12)}`;
   const replicaKind = actorKindForBridge(options.actorId) === "agent" ? "agent_runtime" : "local";
   const mapping = createSourceMapping({
@@ -12845,7 +13394,7 @@ async function runBridge(options) {
   const claimMode = Boolean(options.claimToken || localManifestSource?.canonicalHead);
   let lastAppliedHead = localManifestSource?.canonicalHead;
   let socket;
-  const registeredRoot = options.token ? await fetchScopedRoot(options, rootId) : await registerRoot(options, root, rootId, mapping);
+  const registeredRoot = token ? await fetchScopedRoot({ ...options, token }, rootId) : await registerRoot(options, root, rootId, mapping);
   lastAppliedHead = lastAppliedHead ?? registeredRoot?.canonical.head;
   await writeSourceState(lastAppliedHead);
   connect();
@@ -12868,7 +13417,7 @@ async function runBridge(options) {
     url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
     url.searchParams.set("actorId", options.actorId);
     url.searchParams.set("sourceId", sourceId);
-    if (options.token) url.searchParams.set("token", options.token);
+    if (token) url.searchParams.set("token", token);
     socket = new WebSocket(url);
     socket.addEventListener("open", () => {
       process.stdout.write(`mdocs bridge connected ${root} -> ${options.workspaceId}/${rootId}
@@ -13030,7 +13579,7 @@ async function runBridge(options) {
           `/api/workspaces/${encodeURIComponent(options.workspaceId)}/roots/${encodeURIComponent(rootId)}/documents/${encodeURIComponent(docId)}`,
           options.baseUrl
         ),
-        { headers: authHeaders(options.token) }
+        { headers: authHeaders(token) }
       );
       if (!response.ok) return void 0;
       const document = await response.json();
@@ -13089,6 +13638,60 @@ async function runBridge(options) {
     });
   }
 }
+async function requestBridgeToken(options, rootId) {
+  const response = await fetch(new URL("/api/bridge-requests", options.baseUrl), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      workspaceId: options.workspaceId,
+      rootId,
+      actorId: options.actorId,
+      actorName: options.actorName,
+      sourceName: options.sourceName,
+      role: "edit"
+    })
+  }).catch((error) => {
+    throw new Error(`Failed to create bridge approval request: ${error instanceof Error ? error.message : String(error)}`);
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to create bridge approval request: ${response.status} ${await response.text()}`);
+  }
+  const created = await response.json();
+  if (!created.requestId || !created.pollToken || !created.approveUrl) {
+    throw new Error("Bridge approval request response was missing requestId, pollToken, or approveUrl.");
+  }
+  process.stdout.write(`mdocs bridge approval needed: ${created.approveUrl}
+`);
+  if (created.expiresAt) process.stdout.write(`Waiting for approval until ${created.expiresAt}.
+`);
+  const deadline = Date.now() + (options.pairingTimeoutMs ?? 1e3 * 60 * 15);
+  while (Date.now() < deadline) {
+    await delay(2e3);
+    const pollResponse = await fetch(new URL(`/api/bridge-requests/${encodeURIComponent(created.requestId)}/token`, options.baseUrl), {
+      headers: { Authorization: `Bearer ${created.pollToken}` }
+    }).catch((error) => {
+      throw new Error(`Bridge approval polling failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    const payload = await pollResponse.json().catch(() => ({}));
+    if (pollResponse.status === 202) continue;
+    if (pollResponse.ok && payload.token) {
+      process.stdout.write(`mdocs bridge approved${payload.expiresAt ? `; token expires ${payload.expiresAt}` : ""}.
+`);
+      return payload.token;
+    }
+    if (pollResponse.status === 409 && payload.status === "rejected") {
+      throw new Error("Bridge approval request was rejected.");
+    }
+    if (pollResponse.status === 410 || payload.status === "expired") {
+      throw new Error("Bridge approval request expired before it was approved.");
+    }
+    throw new Error(`Bridge approval polling failed with status ${pollResponse.status}.`);
+  }
+  throw new Error("Bridge approval timed out before a token was issued.");
+}
+function delay(ms) {
+  return new Promise((resolve6) => setTimeout(resolve6, ms));
+}
 function authHeaders(token) {
   return token ? { Authorization: `Bearer ${token}` } : {};
 }
@@ -13255,18 +13858,13 @@ async function main() {
     }
     case "context": {
       const state = await getDocumentState(io, requiredArg(parsed.command[1], "path"));
+      if (parsed.flags.summary || parsed.flags["metadata-only"]) {
+        print(summarizeDocumentContext(state), parsed.flags);
+        return;
+      }
       const startLine = parsed.flags["start-line"] !== void 0 ? Number(parsed.flags["start-line"]) : void 0;
       const endLine = parsed.flags["end-line"] !== void 0 ? Number(parsed.flags["end-line"]) : void 0;
-      const lines = state.markdown.split("\n");
-      const totalLines = lines.length;
-      const sl = startLine ?? 1;
-      const el = endLine ?? totalLines;
-      if (sl < 1 || el > totalLines || sl > el) {
-        throw new CliError("invalid_range", `Line range ${sl}:${el} is out of bounds for a ${totalLines}-line document.`, {
-          hint: `Use --start-line and --end-line with 1-based line numbers within 1:${totalLines}.`
-        });
-      }
-      const markdown = startLine !== void 0 || endLine !== void 0 ? lines.slice(sl - 1, el).join("\n") : state.markdown;
+      const { markdown, totalLines, startLine: sl, endLine: el } = sliceMarkdown(state.markdown, startLine, endLine);
       print({
         docId: state.docId,
         path: state.path,
@@ -13280,12 +13878,19 @@ async function main() {
           ...image2.workspacePath ? { absolutePath: resolve5(cwd, image2.workspacePath) } : {}
         })),
         links: state.links,
-        comments: state.sidecar.comments.filter((comment2) => comment2.status === "open"),
-        suggestions: state.sidecar.suggestions.filter((suggestion) => suggestion.status === "open"),
-        anchors: state.anchors
+        ...parsed.flags["no-review"] ? {} : {
+          comments: state.sidecar.comments.filter((comment2) => comment2.status === "open"),
+          suggestions: state.sidecar.suggestions.filter((suggestion) => suggestion.status === "open"),
+          anchors: state.anchors
+        }
       }, parsed.flags);
       return;
     }
+    case "review": {
+      const state = await getDocumentState(io, requiredArg(parsed.command[1], "path"));
+      print(reviewStateForDocument(state), parsed.flags);
+      return;
+    }
     case "comments": {
       const state = await getDocumentState(io, requiredArg(parsed.command[1], "path"));
       print(state.sidecar.comments, parsed.flags);
@@ -13383,7 +13988,9 @@ async function main() {
         actorName: typeof parsed.flags["actor-name"] === "string" ? parsed.flags["actor-name"] : void 0,
         baseUrl: bridgeBaseUrl(parsed.flags),
         intervalMs: Number(parsed.flags.interval ?? 1e3),
-        token: typeof parsed.flags.token === "string" ? parsed.flags.token : process.env.MDOCS_BRIDGE_TOKEN || void 0
+        token: typeof parsed.flags.token === "string" ? parsed.flags.token : process.env.MDOCS_BRIDGE_TOKEN || void 0,
+        requestToken: Boolean(parsed.flags["request-token"] || parsed.flags.pair),
+        pairingTimeoutMs: typeof parsed.flags["pairing-timeout-ms"] === "string" ? Number(parsed.flags["pairing-timeout-ms"]) : void 0
       });
       return;
     }
@@ -13546,6 +14153,8 @@ Commands:
   graph --json                        Print workspace knowledge graph nodes and edges
   state <path> --json                 Print merged Markdown and sidecar state
   context <path> --json               Print agent-ready context
+  context <path> --summary --json     Print document metadata and headings
+  review <path> --json                Print open comments, suggestions, anchors
   comments <path> --json              List comments
   comment <path> --range 3:5 --body   Add a sidecar comment
   suggestions <path> --json           List suggestions
@@ -13563,17 +14172,19 @@ Commands:
   checkpoint create|list|restore      Manage local reversible checkpoints
   join <share-url> --json             Join a Magic Markdown share through the CLI
   joins --json                        List saved Magic Markdown remote joins
-  remote map|graph|context|create-file|move-file
+  remote map|graph|context|review|create-file|move-file
                                       Work with documents in the active remote join
   remote comment|suggest              Add remote review comments and suggestions
   remote reject <suggestionId>        Withdraw a suggestion you submitted remotely
   remote events|history|restore       Poll events, list commits, restore snapshots
   remote library|create-folder|update-folder|move-root|invite-folder
                                       Organize the joined project library
+  bridge --workspace <id> --root . --url <base-url> --request-token
+                                      Request human approval, then sync an
+                                      approved local root with the workspace
   bridge --workspace <id> --root . --url <base-url> --token <bridge-token>
                                       Sync an approved local root with the workspace
-                                      (--token from the web "Bind agent filesystem"
-                                      dialog, or MDOCS_BRIDGE_TOKEN)
+                                      (or set MDOCS_BRIDGE_TOKEN)
   bridge --claim <token> --root . --canonical-prefix prompts --replica-prefix packages/agent/prompts
                                       Claim an existing repo path as a Magic-canonical source mapping
   doctor --json                       Validate sidecar mappings