@magic-markdown/cli 0.3.0 → 0.3.5

package/dist/index.js

@@ -321,6 +321,17 @@ function fnv1a(value) {
   return hash;
 }
 
+// ../core/src/wikilinks.ts
+function parseWikilinkBody(value) {
+  const separatorIndex = value.indexOf("|");
+  const rawTarget = separatorIndex >= 0 ? value.slice(0, separatorIndex) : value;
+  const rawLabel = separatorIndex >= 0 ? value.slice(separatorIndex + 1) : void 0;
+  const target = rawTarget.trim();
+  if (!target) return void 0;
+  const label = rawLabel?.trim();
+  return label ? { target, label } : { target };
+}
+
 // ../core/src/markdown.ts
 var POLLUTING_PATTERNS = [
   { name: "CriticMarkup addition", pattern: /\{\+\+[\s\S]*?\+\+\}/ },
@@ -381,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);
@@ -469,6 +487,86 @@ function extractMarkdownImages(markdown, documentPath) {
   }
   return images;
 }
+function extractMarkdownLinks(markdown) {
+  const codeMasked = maskCode(markdown);
+  const referenceDefinitions = collectReferenceDefinitions(markdown, codeMasked);
+  const masked = maskReferenceDefinitions(markdown, codeMasked);
+  const lineStarts = getLineStarts(markdown);
+  const links = [];
+  let index = 0;
+  while (index < masked.length) {
+    const start = masked.indexOf("[", index);
+    if (start === -1) break;
+    if (masked[start + 1] === "[" || markdown[start - 1] === "!" || isEscaped(markdown, start)) {
+      index = start + 1;
+      continue;
+    }
+    const labelClose = findClosingBracket(masked, start);
+    if (labelClose === -1) {
+      index = start + 1;
+      continue;
+    }
+    const label = markdown.slice(start + 1, labelClose);
+    const afterLabel = labelClose + 1;
+    const position = positionAt(lineStarts, start);
+    if (masked[afterLabel] === "(") {
+      const destinationClose = findClosingParen(markdown, afterLabel + 1);
+      if (destinationClose === -1) {
+        index = afterLabel + 1;
+        continue;
+      }
+      const parsed = parseDestinationAndTitle(markdown.slice(afterLabel + 1, destinationClose));
+      if (parsed) {
+        links.push(toLinkReference({
+          label,
+          target: parsed.source,
+          title: parsed.title,
+          line: position.line,
+          column: position.column,
+          syntax: "inline"
+        }));
+      }
+      index = destinationClose + 1;
+      continue;
+    }
+    if (masked[afterLabel] === "[") {
+      const referenceClose = findClosingBracket(masked, afterLabel);
+      if (referenceClose === -1) {
+        index = afterLabel + 1;
+        continue;
+      }
+      const explicitLabel = markdown.slice(afterLabel + 1, referenceClose);
+      const definitionLabel = explicitLabel.length > 0 ? explicitLabel : label;
+      const definition = referenceDefinitions.get(normalizeReferenceLabel(definitionLabel));
+      if (definition) {
+        links.push(toLinkReference({
+          label,
+          target: definition.source,
+          title: definition.title,
+          line: position.line,
+          column: position.column,
+          syntax: explicitLabel.length > 0 ? "reference" : "collapsed_reference"
+        }));
+      }
+      index = referenceClose + 1;
+      continue;
+    }
+    const shortcutDefinition = referenceDefinitions.get(normalizeReferenceLabel(label));
+    if (shortcutDefinition) {
+      links.push(toLinkReference({
+        label,
+        target: shortcutDefinition.source,
+        title: shortcutDefinition.title,
+        line: position.line,
+        column: position.column,
+        syntax: "shortcut_reference"
+      }));
+    }
+    index = labelClose + 1;
+  }
+  extractWikilinks(markdown, masked, lineStarts).forEach((link2) => links.push(link2));
+  return links.sort((left, right) => left.line - right.line || left.column - right.column);
+}
 function toImageReference(image2) {
   const workspacePath = resolveWorkspaceImagePath(image2.source, image2.documentPath);
   return {
@@ -483,6 +581,54 @@ function toImageReference(image2) {
     ...workspacePath ? { workspacePath } : {}
   };
 }
+function toLinkReference(link2) {
+  return {
+    label: unescapeMarkdown(link2.label),
+    target: link2.target,
+    ...link2.title ? { title: link2.title } : {},
+    line: link2.line,
+    column: link2.column,
+    syntax: link2.syntax
+  };
+}
+function extractWikilinks(markdown, masked, lineStarts) {
+  const links = [];
+  let index = 0;
+  while (index < masked.length) {
+    const start = masked.indexOf("[[", index);
+    if (start === -1) break;
+    if (isEscaped(markdown, start)) {
+      index = start + 2;
+      continue;
+    }
+    const close2 = masked.indexOf("]]", start + 2);
+    if (close2 === -1 || markdown.slice(start + 2, close2).includes("\n")) {
+      index = start + 2;
+      continue;
+    }
+    const parsed = parseWikilinkBody(markdown.slice(start + 2, close2));
+    if (parsed) {
+      const position = positionAt(lineStarts, start);
+      links.push({
+        label: parsed.label ?? parsed.target,
+        target: parsed.target,
+        line: position.line,
+        column: position.column,
+        syntax: "wikilink"
+      });
+    }
+    index = close2 + 2;
+  }
+  return links;
+}
+function maskReferenceDefinitions(markdown, masked) {
+  const markdownLines = markdown.split(/(?<=\n)/);
+  const maskedLines = masked.split(/(?<=\n)/);
+  return maskedLines.map((line, index) => {
+    const original = markdownLines[index] ?? "";
+    return parseReferenceDefinition(original.replace(/\r?\n$/, "")) ? maskLine(line) : line;
+  }).join("");
+}
 function collectReferenceDefinitions(markdown, masked) {
   const definitions = /* @__PURE__ */ new Map();
   const lines = getLines(markdown);
@@ -818,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",
@@ -827,18 +1094,308 @@ 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) {
+  return links.map((link2) => resolveMarkdownLink(link2, currentDocument, documents));
+}
+function buildWorkspaceGraph(workspaceId, schemaVersion, documents) {
+  const edges = documents.flatMap((document) => document.links.map((link2, index) => toGraphEdge(document, link2, index)));
+  const incomingByDocId = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    if (!edge.targetDocId) continue;
+    incomingByDocId.set(edge.targetDocId, (incomingByDocId.get(edge.targetDocId) ?? 0) + 1);
+  }
+  const nodes = documents.map((document) => ({
+    docId: document.docId,
+    path: document.path,
+    title: document.title,
+    openComments: document.openComments,
+    openSuggestions: document.openSuggestions,
+    anchorsNeedingReview: document.anchorsNeedingReview,
+    outgoingLinks: document.links.length,
+    incomingLinks: incomingByDocId.get(document.docId) ?? 0,
+    unresolvedLinks: document.unresolvedLinks,
+    externalLinks: document.externalLinks
+  }));
+  return {
+    workspaceId,
+    schemaVersion,
+    nodes,
+    edges
+  };
+}
+function resolveMarkdownLink(link2, currentDocument, documents) {
+  const target = link2.target.trim();
+  const parsed = parseInternalTarget(target);
+  if (!target) return { ...link2, status: "unresolved" };
+  if (isExternalTarget(target)) return { ...link2, status: "external" };
+  if (!parsed) return { ...link2, status: "unresolved" };
+  if (!parsed.path) {
+    return parsed.fragment ? {
+      ...link2,
+      status: "anchor",
+      fragment: parsed.fragment,
+      targetDocId: currentDocument.docId,
+      targetPath: currentDocument.path,
+      targetTitle: currentDocument.title
+    } : { ...link2, status: "unresolved" };
+  }
+  if (link2.syntax === "wikilink" && !isPathLikeWikilinkTarget(parsed.path)) {
+    const candidates = findBasenameWikilinkCandidates(parsed.path, parsed.fragment, documents);
+    if (candidates.length === 1) return resolvedLink(link2, candidates[0]);
+    if (candidates.length > 1) return { ...link2, status: "ambiguous", fragment: parsed.fragment, candidates };
+    return { ...link2, status: "unresolved", fragment: parsed.fragment };
+  }
+  const linked = link2.syntax === "wikilink" ? resolvePathLikeWikilink(target, currentDocument.path, documents) : resolveWorkspaceDocumentLink(target, currentDocument.path, documents);
+  return linked ? resolvedLink(link2, linked) : { ...link2, status: "unresolved", fragment: parsed.fragment };
+}
+function resolvedLink(link2, target) {
+  return {
+    ...link2,
+    status: "resolved",
+    ...target.fragment ? { fragment: target.fragment } : {},
+    targetDocId: target.docId,
+    targetPath: target.path,
+    targetTitle: target.title
+  };
+}
+function toGraphEdge(document, link2, index) {
+  return {
+    id: `${document.docId}:${index}`,
+    sourceDocId: document.docId,
+    sourcePath: document.path,
+    sourceTitle: document.title,
+    label: link2.label,
+    target: link2.target,
+    ...link2.title ? { title: link2.title } : {},
+    line: link2.line,
+    column: link2.column,
+    syntax: link2.syntax,
+    status: link2.status,
+    ...link2.fragment ? { fragment: link2.fragment } : {},
+    ...link2.targetDocId ? { targetDocId: link2.targetDocId } : {},
+    ...link2.targetPath ? { targetPath: link2.targetPath } : {},
+    ...link2.targetTitle ? { targetTitle: link2.targetTitle } : {},
+    ...link2.candidates ? { candidates: link2.candidates } : {}
+  };
+}
+function resolveWorkspaceDocumentLink(target, currentPath, documents) {
+  const parsed = parseInternalTarget(target);
+  if (!parsed || !parsed.path) return void 0;
+  const workspacePath = resolveWorkspacePath(parsed.path, currentPath);
+  if (!workspacePath) return void 0;
+  const document = findLinkedDocument(candidateDocumentPaths(workspacePath), documents);
+  return document ? { ...document, ...parsed.fragment ? { fragment: parsed.fragment } : {} } : void 0;
+}
+function resolvePathLikeWikilink(target, currentPath, documents) {
+  const linked = resolveWorkspaceDocumentLink(target, currentPath, documents);
+  if (linked) return linked;
+  if (/^(?:\/|\.\/|\.\.\/)/.test(target)) return void 0;
+  return resolveWorkspaceDocumentLink(`/${target}`, currentPath, documents);
+}
+function findBasenameWikilinkCandidates(name, fragment, documents) {
+  const normalizedName = normalizeWikilinkName(name);
+  return documents.filter((doc) => normalizeWikilinkName(markdownStem(doc.path)) === normalizedName).map((doc) => ({ ...doc, ...fragment ? { fragment } : {} })).sort((left, right) => left.path.localeCompare(right.path, void 0, { numeric: true, sensitivity: "base" }));
+}
+function findLinkedDocument(paths, documents) {
+  for (const path of paths) {
+    const document = documents.find((candidate) => candidate.path === path);
+    if (document) return document;
+  }
+  return void 0;
+}
+function parseInternalTarget(target) {
+  const trimmed = target.trim();
+  if (!trimmed) return void 0;
+  const hashIndex = trimmed.indexOf("#");
+  const withoutFragment = hashIndex >= 0 ? trimmed.slice(0, hashIndex) : trimmed;
+  const fragment = hashIndex >= 0 ? safeDecode(trimmed.slice(hashIndex + 1)) : void 0;
+  const queryIndex = withoutFragment.indexOf("?");
+  const path = safeDecode(queryIndex >= 0 ? withoutFragment.slice(0, queryIndex) : withoutFragment);
+  return { path, ...fragment ? { fragment } : {} };
+}
+function resolveWorkspacePath(linkPath, currentPath) {
+  const path = linkPath.replaceAll("\\", "/").trim();
+  if (!path) return void 0;
+  const source = path.startsWith("/") ? path.slice(1) : `${dirname2(currentPath)}/${path}`;
+  return normalizeWorkspacePath2(source);
+}
+function normalizeWorkspacePath2(path) {
+  const segments = [];
+  for (const segment of path.split("/")) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      if (segments.length === 0) return void 0;
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+  return segments.join("/");
+}
+function candidateDocumentPaths(path) {
+  const candidates = [path];
+  if (path.endsWith("/")) {
+    candidates.push(`${path}README.md`, `${path}index.md`);
+  } else if (!/\.[^/.]+$/.test(path)) {
+    candidates.push(`${path}.md`, `${path}.mdx`, `${path}/README.md`, `${path}/index.md`);
+  }
+  return [...new Set(candidates)];
+}
+function isPathLikeWikilinkTarget(path) {
+  return /^(?:\/|\.\/|\.\.\/)/.test(path) || path.includes("/") || path.includes("\\") || /\.(md|mdx)$/i.test(path);
+}
+function isExternalTarget(target) {
+  const trimmed = target.trim();
+  if (!trimmed || trimmed.startsWith("#")) return false;
+  return /^[a-z][a-z0-9+.-]*:/i.test(trimmed) || trimmed.startsWith("//") || looksLikeBareDomain(trimmed);
+}
+function looksLikeBareDomain(value) {
+  return /^[a-z0-9-]+(?:\.[a-z0-9-]+)+(?:[/?#].*)?$/i.test(value) && !/\.(md|mdx)(?:[?#]|$)/i.test(value);
+}
+function markdownStem(path) {
+  const basename3 = path.split("/").pop() ?? path;
+  return basename3.replace(/\.mdx?$/i, "");
+}
+function normalizeWikilinkName(value) {
+  return value.trim().toLowerCase();
+}
+function dirname2(path) {
+  const index = path.lastIndexOf("/");
+  return index >= 0 ? path.slice(0, index) : "";
+}
+function safeDecode(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
 
 // ../core/src/sidecar.ts
 function defaultActor(name = "mdocs") {
@@ -916,9 +1473,12 @@ async function indexWorkspace(io) {
 }
 async function getWorkspaceMap(io) {
   const manifest = await indexWorkspace(io);
+  const graph = await workspaceGraphForManifest(io, manifest);
+  const graphNodesByDocId = new Map(graph.nodes.map((node) => [node.docId, node]));
   const docs = await Promise.all(
     manifest.docs.map(async (entry) => {
       const sidecar = await readSidecar(io, entry.docId);
+      const graphNode = graphNodesByDocId.get(entry.docId);
       return {
         docId: entry.docId,
         path: entry.path,
@@ -926,7 +1486,11 @@ async function getWorkspaceMap(io) {
         sidecarPath: sidecarPath(entry.docId),
         openComments: sidecar.comments.filter((comment2) => comment2.status === "open").length,
         openSuggestions: sidecar.suggestions.filter((suggestion) => suggestion.status === "open").length,
-        anchorsNeedingReview: sidecar.anchors.filter((anchor) => anchor.status !== "mapped").length
+        anchorsNeedingReview: sidecar.anchors.filter((anchor) => anchor.status !== "mapped").length,
+        outgoingLinks: graphNode?.outgoingLinks ?? 0,
+        incomingLinks: graphNode?.incomingLinks ?? 0,
+        unresolvedLinks: graphNode?.unresolvedLinks ?? 0,
+        externalLinks: graphNode?.externalLinks ?? 0
       };
     })
   );
@@ -936,6 +1500,9 @@ async function getWorkspaceMap(io) {
     docs
   };
 }
+async function getWorkspaceGraph(io) {
+  return workspaceGraphForManifest(io, await indexWorkspace(io));
+}
 async function getDocumentState(io, pathOrDocId) {
   const manifest = await indexWorkspace(io);
   const entry = findDoc(manifest, pathOrDocId);
@@ -964,10 +1531,31 @@ async function getDocumentState(io, pathOrDocId) {
       confidence: anchor.confidence
     })),
     images: extractMarkdownImages(markdown, entry.path),
+    links: resolveMarkdownLinks(extractMarkdownLinks(markdown), entry, manifest.docs),
     openComments: nextSidecar.comments.filter((comment2) => comment2.status === "open").length,
     openSuggestions: nextSidecar.suggestions.filter((suggestion) => suggestion.status === "open").length
   };
 }
+async function workspaceGraphForManifest(io, manifest) {
+  const documents = await Promise.all(
+    manifest.docs.map(async (entry) => {
+      const [markdown, sidecar] = await Promise.all([io.readText(entry.path), readSidecar(io, entry.docId)]);
+      const links = resolveMarkdownLinks(extractMarkdownLinks(markdown), entry, manifest.docs);
+      return {
+        docId: entry.docId,
+        path: entry.path,
+        title: entry.title,
+        openComments: sidecar.comments.filter((comment2) => comment2.status === "open").length,
+        openSuggestions: sidecar.suggestions.filter((suggestion) => suggestion.status === "open").length,
+        anchorsNeedingReview: sidecar.anchors.filter((anchor) => anchor.status !== "mapped").length,
+        externalLinks: links.filter((link2) => link2.status === "external").length,
+        unresolvedLinks: links.filter((link2) => link2.status === "unresolved" || link2.status === "ambiguous").length,
+        links
+      };
+    })
+  );
+  return buildWorkspaceGraph(manifest.workspaceId, manifest.schemaVersion, documents);
+}
 async function addComment(io, pathOrDocId, range, body, author = defaultActor()) {
   const state = await getDocumentState(io, pathOrDocId);
   assertLineRangeWithin(state.markdown, range);
@@ -1001,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();
@@ -1026,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
@@ -1068,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);
   }
@@ -1192,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"],
@@ -1234,7 +1928,7 @@ var DEFAULT_ROOT_PATH_RULES = {
   maxFileSizeBytes: 1024 * 1024
 };
 var MARKDOWN_FILE_PATTERN = /\.mdx?$/i;
-function normalizeWorkspacePath2(path) {
+function normalizeWorkspacePath3(path) {
   const normalized = path.replaceAll("\\", "/").replace(/\/+/g, "/").trim();
   if (!normalized) throw new Error("Workspace path cannot be empty.");
   if (normalized.startsWith("/") || /^[a-zA-Z]:\//.test(normalized)) {
@@ -1247,7 +1941,7 @@ function normalizeWorkspacePath2(path) {
   return parts.filter((part) => part && part !== ".").join("/");
 }
 function assertWorkspacePathAllowed(path, rules = DEFAULT_ROOT_PATH_RULES, sizeBytes, ignoreMatcher) {
-  const normalized = normalizeWorkspacePath2(path);
+  const normalized = normalizeWorkspacePath3(path);
   if (isIgnoredWorkspacePath(normalized, rules)) {
     throw new Error(`Workspace path is ignored by root policy: ${normalized}`);
   }
@@ -1278,7 +1972,7 @@ function isWorkspaceMarkdownPathAllowed(path, rules = DEFAULT_ROOT_PATH_RULES, s
 function createWorkspaceIgnoreMatcher(ignoreFiles) {
   const rules = parseWorkspaceIgnoreRules(ignoreFiles);
   return (path) => {
-    const normalized = normalizeWorkspacePath2(path);
+    const normalized = normalizeWorkspacePath3(path);
     let ignored = false;
     for (const rule of rules) {
       if (!matchesWorkspaceIgnoreRule(normalized, rule)) continue;
@@ -1288,7 +1982,7 @@ function createWorkspaceIgnoreMatcher(ignoreFiles) {
   };
 }
 function isIgnoredWorkspacePath(path, rules = DEFAULT_ROOT_PATH_RULES) {
-  const normalized = normalizeWorkspacePath2(path);
+  const normalized = normalizeWorkspacePath3(path);
   const parts = normalized.split("/");
   return parts.some((part) => rules.ignoredDirectories.includes(part));
 }
@@ -1308,8 +2002,8 @@ function matchesAny(path, patterns) {
   return patterns.some((pattern) => globToRegExp(pattern).test(path));
 }
 function parseWorkspaceIgnoreRules(ignoreFiles) {
-  return [...ignoreFiles].sort((left, right) => normalizeWorkspacePath2(left.path).localeCompare(normalizeWorkspacePath2(right.path))).flatMap((file) => {
-    const normalizedPath = normalizeWorkspacePath2(file.path);
+  return [...ignoreFiles].sort((left, right) => normalizeWorkspacePath3(left.path).localeCompare(normalizeWorkspacePath3(right.path))).flatMap((file) => {
+    const normalizedPath = normalizeWorkspacePath3(file.path);
     const basePath = normalizedPath.endsWith("/.gitignore") ? normalizedPath.slice(0, -"/.gitignore".length) : "";
     return file.content.split(/\r?\n/).flatMap((line) => {
       const rule = parseWorkspaceIgnoreRule(basePath, line);
@@ -1416,14 +2110,14 @@ function createSourceMapping(input, updatedAt = (/* @__PURE__ */ new Date()).toI
   };
 }
 function canonicalPathToReplicaPath(path, mapping) {
-  if (path === ".mdocs" || path.startsWith(".mdocs/")) return normalizeWorkspacePath2(path);
-  const canonicalPath = normalizeWorkspacePath2(path);
+  if (path === ".mdocs" || path.startsWith(".mdocs/")) return normalizeWorkspacePath3(path);
+  const canonicalPath = normalizeWorkspacePath3(path);
   const relativePath = stripPrefix(canonicalPath, normalizeOptionalPrefix(mapping.canonicalPrefix), "canonical");
   return joinWorkspacePath(normalizeOptionalPrefix(mapping.replicaPrefix), relativePath);
 }
 function replicaPathToCanonicalPath(path, mapping) {
-  if (path === ".mdocs" || path.startsWith(".mdocs/")) return normalizeWorkspacePath2(path);
-  const replicaPath = normalizeWorkspacePath2(path);
+  if (path === ".mdocs" || path.startsWith(".mdocs/")) return normalizeWorkspacePath3(path);
+  const replicaPath = normalizeWorkspacePath3(path);
   const relativePath = stripPrefix(replicaPath, normalizeOptionalPrefix(mapping.replicaPrefix), "replica");
   return joinWorkspacePath(normalizeOptionalPrefix(mapping.canonicalPrefix), relativePath);
 }
@@ -1438,7 +2132,7 @@ function sourceMappingPathRules(mapping, base) {
 function normalizeOptionalPrefix(prefix) {
   const value = prefix?.trim();
   if (!value || value === ".") return "";
-  return normalizeWorkspacePath2(value).replace(/\/+$/, "");
+  return normalizeWorkspacePath3(value).replace(/\/+$/, "");
 }
 function stripPrefix(path, prefix, label) {
   if (!prefix) return path;
@@ -1447,21 +2141,27 @@ function stripPrefix(path, prefix, label) {
   throw new Error(`Path ${path} is outside ${label} prefix ${prefix}`);
 }
 function joinWorkspacePath(prefix, path) {
-  if (!prefix) return normalizeWorkspacePath2(path);
+  if (!prefix) return normalizeWorkspacePath3(path);
   if (!path) return prefix;
-  return normalizeWorkspacePath2(`${prefix}/${path}`);
+  return normalizeWorkspacePath3(`${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 workspacePath = `/share/${encodeURIComponent(workspaceId)}`;
+  if (!rootId) return workspacePath;
+  const base = `${workspacePath}/${encodeURIComponent(rootId)}`;
+  return docId ? `${base}/${encodeURIComponent(docId)}` : base;
+}
 
 // ../../node_modules/orderedmap/dist/index.js
 function OrderedMap(content) {
@@ -3901,7 +4601,10 @@ function gatherMarks(schema2, marks) {
 // ../core/src/pm-schema.ts
 var canonicalSchema = new Schema({
   nodes: {
-    doc: { content: "block+" },
+    // The doc allows suggestion marks on its block children so pending
+    // block-level suggestions (node marks) survive fromJSON and can be
+    // structurally reverted before serialization.
+    doc: { content: "block+", marks: "insertion deletion modification" },
     paragraph: { group: "block", content: "inline*" },
     heading: {
       group: "block",
@@ -3969,14 +4672,45 @@ var canonicalSchema = new Schema({
       },
       inclusive: false
     },
+    wikilink: {
+      attrs: {
+        target: { default: null }
+      },
+      inclusive: false
+    },
     bold: {},
     italic: {},
     strike: {},
-    code: {}
+    code: {},
+    // Pending-suggestion marks (mirroring the web editor's extensions). They
+    // are never serialized — the canonical serializer reverts them first —
+    // but the schema must know them so suggestion-marked docs load intact.
+    insertion: {
+      attrs: { id: { default: null } },
+      inclusive: false,
+      excludes: "deletion modification insertion"
+    },
+    deletion: {
+      attrs: { id: { default: null } },
+      inclusive: false,
+      excludes: "insertion modification deletion"
+    },
+    modification: {
+      attrs: {
+        id: { default: null },
+        type: { default: null },
+        attrName: { default: null },
+        previousValue: { default: null },
+        newValue: { default: null }
+      },
+      inclusive: false,
+      excludes: "deletion insertion"
+    }
   }
 });
+var SUGGESTION_MARK_TYPES = /* @__PURE__ */ new Set(["insertion", "deletion", "modification"]);
 var CANONICAL_NODE_TYPES = new Set(Object.keys(canonicalSchema.nodes));
-var CANONICAL_MARK_TYPES = new Set(Object.keys(canonicalSchema.marks));
+var CANONICAL_MARK_TYPES = new Set(Object.keys(canonicalSchema.marks).filter((name) => !SUGGESTION_MARK_TYPES.has(name)));
 
 // ../../node_modules/markdown-it/lib/common/utils.mjs
 var utils_exports = {};
@@ -10171,9 +10905,28 @@ var markdownSerializer = new MarkdownSerializer(
         return `](${href.replace(/[()"]/g, "\\$&")})`;
       },
       mixable: false
+    },
+    wikilink: {
+      open(_state, mark, parent, index) {
+        const target = typeof mark.attrs.target === "string" ? mark.attrs.target : "";
+        const label = markedRangeText(parent, index, mark);
+        if (!target || label === target) return "[[";
+        return `[[${target}|`;
+      },
+      close: "]]",
+      mixable: false
     }
   }
 );
+function markedRangeText(parent, index, mark) {
+  let text2 = "";
+  for (let childIndex = index; childIndex < parent.childCount; childIndex += 1) {
+    const child = parent.child(childIndex);
+    if (!mark.isInSet(child.marks)) break;
+    text2 += child.textContent;
+  }
+  return text2;
+}
 function escapeImageAlt(value) {
   return value.replace(/\\/g, "\\\\").replace(/\[/g, "\\[").replace(/]/g, "\\]").replace(/\n+/g, " ");
 }
@@ -10237,7 +10990,7 @@ var RemoteDocumentIO = class {
 };
 
 // src/agent.ts
-var CLI_VERSION = "0.3.0";
+var CLI_VERSION = "0.3.5";
 var CLI_PACKAGE_NAME = "@magic-markdown/cli";
 var AGENT_COMMANDS = [
   {
@@ -10267,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: [
@@ -10288,26 +11042,40 @@ var AGENT_COMMANDS = [
   },
   {
     name: "remote",
-    summary: "Read, comment on, suggest edits to, monitor, and restore the active Magic Markdown remote join.",
-    usage: "mdocs remote map|context|comment|suggest|reject|events|history|restore --json",
+    summary: "Read, organize, comment on, suggest edits to, monitor, and restore the active Magic Markdown remote join.",
+    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",
+      "mdocs remote move-file docs/new-note.md --to archive/new-note.md --json",
       "mdocs remote suggest --range 4:9 --with-file /tmp/replacement.md --message-file /tmp/message.txt --json",
       "mdocs remote comment docs/example.md --range 3:5 --body-file /tmp/comment.txt --json",
       "mdocs remote reject suggestion_abc123 --json",
       "mdocs remote history --json",
-      "mdocs remote restore head_abc123 --json"
+      "mdocs remote restore head_abc123 --json",
+      "mdocs remote library --json",
+      "mdocs remote create-folder Research --json",
+      "mdocs remote move-root --folder fold_abc123 --json",
+      "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."
     ]
@@ -10322,28 +11090,51 @@ var AGENT_COMMANDS = [
   },
   {
     name: "map",
-    summary: "Return the indexed Markdown documents and review counts.",
+    summary: "Return the indexed Markdown documents, review counts, and link counts.",
     usage: "mdocs map --json",
     output: "json",
     mutates: true,
     examples: ["mdocs map --json"]
   },
+  {
+    name: "graph",
+    summary: "Return the workspace knowledge graph as document nodes and Markdown/wikilink edges.",
+    usage: "mdocs graph --json",
+    output: "json",
+    mutates: true,
+    examples: ["mdocs graph --json"],
+    notes: [
+      "Edges include resolved document links, ambiguous wikilinks, unresolved links, external links, and same-document anchor links.",
+      "Use this before broad agent edits to understand the Obsidian-style document graph and avoid changing related notes in isolation."
+    ]
+  },
   {
     name: "context",
-    summary: "Return agent-ready document Markdown, open review state, anchors, and image references.",
-    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.",
@@ -10376,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."
     ]
   },
   {
@@ -10493,7 +11285,7 @@ function getAgentGuidePayload() {
 function getAgentSkillMarkdown() {
   return `---
 name: magic-markdown
-description: Use the Magic Markdown CLI or MCP server to read, review, comment on, suggest edits to, and sync clean Markdown workspaces without hand-editing .mdocs sidecars. Use when an agent needs to interact with Magic Markdown documents, comments, suggestions, image context, checkpoints, or local source sync.
+description: Use the Magic Markdown CLI or MCP server to read, organize, review, comment on, suggest edits to, and sync clean Markdown workspaces without hand-editing .mdocs sidecars. Use when an agent needs to interact with Magic Markdown documents, library folders, comments, suggestions, image context, checkpoints, or local source sync.
 metadata:
   short-description: Operate Magic Markdown via CLI/MCP
 ---
@@ -10520,14 +11312,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, and anchor review 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.
-4. For a document, run \`mdocs context <path|docId> --json\` locally or \`mdocs remote context <path|docId> --json\` for a joined share.
-5. 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.
+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> --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>\`.
@@ -10540,13 +11336,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. 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
@@ -10561,7 +11358,7 @@ Start the local stdio MCP server with:
 mdocs serve-mcp --cwd /path/to/workspace
 \`\`\`
 
-The MCP server exposes document resources, image resources, a workspace map resource, 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() {
@@ -10618,7 +11415,7 @@ function toCliError(error) {
 
 // src/checkpoints.ts
 import { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname as dirname2, join } from "node:path";
+import { basename, dirname as dirname3, join } from "node:path";
 async function createCheckpoint(root, label) {
   const id = createId("checkpoint");
   const createdAt = nowIso();
@@ -10683,7 +11480,7 @@ async function restoreTree(snapshotRoot, root) {
       await mkdir(dest, { recursive: true });
       await restoreTree(source, dest);
     } else if (entry.isFile()) {
-      await mkdir(dirname2(dest), { recursive: true });
+      await mkdir(dirname3(dest), { recursive: true });
       await cp(source, dest);
     }
   }
@@ -10739,7 +11536,7 @@ function nextCommands(map) {
 
 // src/fs-io.ts
 import { mkdir as mkdir2, readFile as readFile2, readdir as readdir2, realpath, rename, rm as rm2, stat as stat2, writeFile as writeFile2 } from "node:fs/promises";
-import { dirname as dirname3, join as join2, relative, resolve } from "node:path";
+import { dirname as dirname4, join as join2, relative, resolve } from "node:path";
 var NodeWorkspaceIO = class {
   constructor(root, pathRules = DEFAULT_ROOT_PATH_RULES) {
     this.root = root;
@@ -10752,12 +11549,12 @@ var NodeWorkspaceIO = class {
   }
   async writeText(path, content) {
     const target = await this.resolveWritablePath(path, Buffer.byteLength(content, "utf8"));
-    await mkdir2(dirname3(target), { recursive: true });
+    await mkdir2(dirname4(target), { recursive: true });
     await writeFile2(target, content, "utf8");
   }
   async writeTextAtomic(path, content) {
     const target = await this.resolveWritablePath(path, Buffer.byteLength(content, "utf8"));
-    await mkdir2(dirname3(target), { recursive: true });
+    await mkdir2(dirname4(target), { recursive: true });
     const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
     await writeFile2(temporary, content, "utf8");
     await rename(temporary, target);
@@ -10794,12 +11591,12 @@ var NodeWorkspaceIO = class {
     const normalized = assertWorkspacePathAllowed(path, this.pathRules, sizeBytes);
     const root = await realpath(this.root);
     const target = resolve(root, normalized);
-    await mkdir2(dirname3(target), { recursive: true });
-    assertPathInsideRoot(root, await realpath(dirname3(target)));
+    await mkdir2(dirname4(target), { recursive: true });
+    assertPathInsideRoot(root, await realpath(dirname4(target)));
     return target;
   }
   async resolvePath(path) {
-    const normalized = normalizeWorkspacePath2(path);
+    const normalized = normalizeWorkspacePath3(path);
     const root = await realpath(this.root);
     const target = resolve(root, normalized);
     assertPathInsideRoot(root, target);
@@ -10836,7 +11633,7 @@ var PathMappedWorkspaceIO = class {
     return files.map((path) => replicaPathToCanonicalPath(path, this.mapping)).sort();
   }
   toReplicaPath(path) {
-    if (path === ".mdocs" || path.startsWith(".mdocs/")) return normalizeWorkspacePath2(path);
+    if (path === ".mdocs" || path.startsWith(".mdocs/")) return normalizeWorkspacePath3(path);
     return canonicalPathToReplicaPath(path, this.mapping);
   }
 };
@@ -10857,14 +11654,14 @@ async function walk(root, output, base, rules, ignoreFiles) {
     }
     if (entry.isFile()) {
       const stats = await stat2(absolute);
-      if (isWorkspaceMarkdownPathAllowed(relativePath, rules, stats.size, ignoreMatcher)) output.push(normalizeWorkspacePath2(relativePath));
+      if (isWorkspaceMarkdownPathAllowed(relativePath, rules, stats.size, ignoreMatcher)) output.push(normalizeWorkspacePath3(relativePath));
     }
   }
 }
 async function withDirectoryIgnoreFile(root, base, ignoreFiles) {
   try {
     const path = join2(relative(base, root).replaceAll("\\", "/"), ".gitignore").replace(/^\.\//, "");
-    const normalizedPath = path === ".gitignore" ? path : normalizeWorkspacePath2(path);
+    const normalizedPath = path === ".gitignore" ? path : normalizeWorkspacePath3(path);
     const content = await readFile2(join2(root, ".gitignore"), "utf8");
     return [...ignoreFiles, { path: normalizedPath, content }];
   } catch {
@@ -10985,8 +11782,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,
@@ -10997,21 +11795,20 @@ async function contextForDocument(io, path, startLine, endLine) {
     endLine: el,
     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}`;
 }
@@ -11074,7 +11871,12 @@ var actorProperties = {
 var tools = [
   {
     name: "mdocs_map",
-    description: "Return the workspace document map.",
+    description: "Return the workspace document map with review and link counts.",
+    inputSchema: noArgsSchema
+  },
+  {
+    name: "mdocs_graph",
+    description: "Return the workspace knowledge graph as document nodes and Markdown/wikilink edges. Edges include resolved, ambiguous, unresolved, external, and same-document anchor links.",
     inputSchema: noArgsSchema
   },
   {
@@ -11084,7 +11886,7 @@ var tools = [
   },
   {
     name: "mdocs_context",
-    description: "Return agent-ready document Markdown, open review state, anchors, and image references. 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: {
@@ -11096,12 +11898,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.",
@@ -11125,14 +11940,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
       },
@@ -11223,6 +12038,11 @@ async function dispatch(io, method, params) {
           uri: "mdocs://workspace/map",
           name: "Workspace Map",
           mimeType: "application/vnd.mdocs.workspace-map+json"
+        },
+        {
+          uri: "mdocs://workspace/graph",
+          name: "Workspace Knowledge Graph",
+          mimeType: "application/vnd.mdocs.workspace-graph+json"
         }
       ])
     };
@@ -11315,6 +12135,17 @@ async function readResource(io, path) {
       ]
     };
   }
+  if (path === "mdocs://workspace/graph") {
+    return {
+      contents: [
+        {
+          uri: path,
+          mimeType: "application/vnd.mdocs.workspace-graph+json",
+          text: JSON.stringify(await getWorkspaceGraph(io), null, 2)
+        }
+      ]
+    };
+  }
   const imageMatch = /^mdocs:\/\/documents\/([^/]+)\/images\/(\d+)$/.exec(path);
   if (imageMatch) {
     return readImageResource(io, path, imageMatch[1] ?? "", Number(imageMatch[2]));
@@ -11333,12 +12164,17 @@ async function readResource(io, path) {
 }
 async function callTool(io, name, args) {
   if (name === "mdocs_map") return getWorkspaceMap(io);
+  if (name === "mdocs_graph") return getWorkspaceGraph(io);
   if (name === "mdocs_doctor") return runDoctor(io, io.root);
   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(
@@ -11445,12 +12281,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)
   });
 }
@@ -11459,9 +12305,47 @@ async function fetchTree(record) {
     headers: shareHeaders(record.shareUrl)
   });
 }
+async function fetchLibrary(record) {
+  return fetchJson(libraryUrl(record), {
+    headers: shareHeaders(record.shareUrl)
+  });
+}
+async function postLibraryFolder(record, input, actor) {
+  return fetchJson(`${libraryUrl(record)}/folders`, {
+    method: "POST",
+    headers: { ...shareHeaders(record.shareUrl), "Content-Type": "application/json" },
+    body: JSON.stringify({ ...input, actor })
+  });
+}
+async function patchLibraryFolder(record, folderId, input, actor) {
+  return fetchJson(`${libraryUrl(record)}/folders/${encodeURIComponent(folderId)}`, {
+    method: "PATCH",
+    headers: { ...shareHeaders(record.shareUrl), "Content-Type": "application/json" },
+    body: JSON.stringify({ ...input, actor })
+  });
+}
+async function postMoveRoot(record, folderId, actor) {
+  return fetchJson(`${libraryUrl(record)}/move-root`, {
+    method: "POST",
+    headers: { ...shareHeaders(record.shareUrl), "Content-Type": "application/json" },
+    body: JSON.stringify({ folderId, actor })
+  });
+}
+async function postFolderInvite(record, folderId, input, actor) {
+  return fetchJson(
+    `${libraryUrl(record)}/folders/${encodeURIComponent(folderId)}/invites`,
+    {
+      method: "POST",
+      headers: { ...shareHeaders(record.shareUrl), "Content-Type": "application/json" },
+      body: JSON.stringify({ ...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.`
@@ -11469,19 +12353,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(
@@ -11489,6 +12373,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`,
@@ -11571,7 +12500,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
   });
 }
@@ -11579,6 +12508,17 @@ function agentUrl(record, docId, action, query) {
   const base = `${record.origin}/api/agent/${encodeURIComponent(record.workspaceId)}/${encodeURIComponent(record.rootId)}/${encodeURIComponent(docId)}/${action}`;
   return query ? `${base}?${query}` : base;
 }
+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}` };
 }
@@ -11616,7 +12556,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
     });
   }
@@ -11757,13 +12697,15 @@ 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 state = await postPresenceAndReadState(parsedShare, target, docId, agentId, agentName);
+  const rootScopedShare = rootScopedRecord(parsedShare);
+  const docId = parsedShare.docId ?? (rootScopedShare ? await firstDocIdForProject(rootScopedShare) : void 0);
+  const shareUrl = shareUrlForScope(target, { ...parsedShare, docId });
+  const state = rootScopedShare && docId ? await postPresenceAndReadState(rootScopedShare, shareUrl, docId, agentId, agentName) : void 0;
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const record = {
     joinId: joinIdFor(target),
     scope: parsedShare.scope,
-    shareUrl: target,
+    shareUrl,
     origin: parsedShare.origin,
     workspaceId: parsedShare.workspaceId,
     rootId: parsedShare.rootId,
@@ -11773,28 +12715,39 @@ 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);
 }
 async function runRemoteCommand(root, subcommand, parsed) {
-  const record = await readSelectedJoin(root, parsed.flags);
+  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":
+      return remoteMoveFile(root, record, parsed);
     case "comment":
       return remoteComment(root, record, parsed);
     case "suggest":
@@ -11807,18 +12760,83 @@ async function runRemoteCommand(root, subcommand, parsed) {
       return remoteHistory(record, parsed.flags);
     case "restore":
       return remoteRestore(record, parsed);
+    case "library": {
+      if (record.scope === "workspace") return fetchWorkspaceLibrary(record);
+      assertProjectScope(record, "library");
+      const rootRecord = assertRootScoped(record, "library");
+      await refreshPresence(rootRecord, record.docId);
+      return fetchLibrary(rootRecord);
+    }
+    case "create-folder":
+      return remoteCreateFolder(record, parsed);
+    case "update-folder":
+      return remoteUpdateFolder(record, parsed);
+    case "move-root":
+      return remoteMoveRoot(record, parsed);
+    case "invite-folder":
+      return remoteInviteFolder(record, parsed);
     case "rejoin":
       return rejoin(root, record.joinId, parsed.flags);
     default:
       throw new CliError("usage_error", `Unknown remote subcommand: ${subcommand}`, {
-        hint: "Use mdocs remote map|context|comment|suggest|reject|events|history|restore|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");
+  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);
+    return {
+      docId: doc.docId,
+      path: doc.path,
+      title: doc.title,
+      openComments: doc.openComments,
+      openSuggestions: doc.openSuggestions,
+      anchorsNeedingReview: doc.anchors.filter((anchor) => anchor.status !== "mapped").length,
+      externalLinks: links.filter((link2) => link2.status === "external").length,
+      unresolvedLinks: links.filter((link2) => link2.status === "unresolved" || link2.status === "ambiguous").length,
+      links
+    };
+  });
+  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];
@@ -11827,9 +12845,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) {
@@ -11839,20 +12858,32 @@ 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 state = await postPresenceAndReadState(record, record.shareUrl, docId, record.agentId, record.agentName);
+  const rootRecord = rootScopedRecord(record);
+  const docId = record.docId ?? (rootRecord ? await firstDocIdForProject(rootRecord) : void 0);
+  const shareUrl = shareUrlForScope(record.shareUrl, { ...record, docId });
+  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);
+  if (!record.docId && record.scope === "file") return record;
+  const shareUrl = shareUrlForScope(record.shareUrl, record);
+  if (shareUrl === record.shareUrl) return record;
+  const next = { ...record, shareUrl, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+  await writeJoinRecord(root, next);
+  return next;
 }
 async function refreshPresence(record, docId) {
   if (!docId) return;
@@ -11860,19 +12891,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,
@@ -11884,11 +12909,107 @@ 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,
-    images: document.images
+    ...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(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"));
+  if (tree.docs.some((doc) => doc.path === normalizedPath)) {
+    throw new CliError("validation_error", `Document already exists: ${normalizedPath}`, {
+      hint: "Choose a new path or use mdocs remote context to inspect the existing document."
+    });
+  }
+  const docId = createDocId();
+  const title = titleFromMarkdown(normalizedPath, markdown);
+  const sidecar = emptySidecar(docId, normalizedPath, title);
+  const baseDocument = {
+    workspaceId: rootRecord.workspaceId,
+    rootId: rootRecord.rootId,
+    docId,
+    path: normalizedPath,
+    title,
+    markdown,
+    sidecar,
+    anchors: [],
+    images: [],
+    links: [],
+    openComments: 0,
+    openSuggestions: 0,
+    currentSha: tree.root.canonical.head
   };
+  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.", {
+      hint: "Run mdocs remote move-file <path|docId> --to <new-path> --json."
+    });
+  }
+  const nextPathFlag = requiredFlag(parsed.flags, "to");
+  const document = await fetchDocument(record, pathOrDocId);
+  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}`, {
+      hint: "Choose a path that is not already in use."
+    });
+  }
+  const moved = await pushDocument(
+    rootScopedRecordFor(record, document.rootId),
+    { ...document, path: nextPath, title: titleFromMarkdown(nextPath, document.markdown) },
+    document.markdown,
+    document.sidecar
+  );
+  await recordHead(root, record, moved);
+  return { document: moved };
 }
 async function remoteComment(root, record, parsed) {
   const body = await readRequiredTextFlag(parsed.flags, root, ["body", "message"]);
@@ -11913,11 +13034,71 @@ async function remoteSuggest(root, record, parsed) {
   );
   return { suggestion: result.created, document: result.document };
 }
+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(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.", {
+      hint: "Run mdocs remote update-folder <folderId> --name <name> --json."
+    });
+  }
+  const input = {};
+  if (typeof parsed.flags.name === "string") input.name = parsed.flags.name;
+  if (parsed.flags.home === true || parsed.flags.home === "true") input.parentId = null;
+  else if (parsed.flags.parent !== void 0) input.parentId = optionalFolderTarget(parsed.flags.parent);
+  if (input.name === void 0 && input.parentId === void 0) {
+    throw new CliError("usage_error", "Nothing to update.", {
+      hint: "Pass --name <name>, --parent <folderId>, or --home."
+    });
+  }
+  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(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.", {
+      hint: "Run mdocs remote invite-folder <folderId> --email person@example.com --role edit --json."
+    });
+  }
+  const email = requiredFlag(parsed.flags, "email");
+  const role = typeof parsed.flags.role === "string" ? parsed.flags.role : "edit";
+  if (!["read", "suggest", "edit", "admin"].includes(role)) {
+    throw new CliError("usage_error", "Invalid --role.", {
+      hint: "Use --role read, suggest, edit, or admin."
+    });
+  }
+  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;
@@ -11927,12 +13108,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") {
@@ -11942,7 +13124,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 };
@@ -11956,11 +13138,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) {
@@ -11969,7 +13152,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) {
@@ -11985,7 +13168,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);
@@ -12002,7 +13186,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) {
@@ -12011,10 +13195,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) {
@@ -12023,7 +13208,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) {
@@ -12038,8 +13223,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(),
@@ -12048,7 +13234,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;
@@ -12057,11 +13243,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),
@@ -12069,8 +13255,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: "",
@@ -12078,6 +13264,15 @@ function parseShareUrl(value, flags) {
     lastSeenEventId: 0
   };
 }
+function shareUrlForScope(value, record) {
+  const url = new URL(value);
+  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) {
   return {
     connected: true,
@@ -12086,19 +13281,84 @@ 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)
   };
 }
+function assertProjectScope(record, command) {
+  if (record.scope === "project") return;
+  throw new CliError("usage_error", `remote ${command} requires a project-scoped join.`, {
+    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,
+    docId,
+    path,
+    title,
+    anchors: [],
+    comments: [],
+    suggestions: [],
+    changeSets: [],
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function defaultMarkdown(path) {
+  return `# ${titleFromMarkdown(path, "")}
+`;
+}
+function normalizeRemoteWorkspacePath(path, rules, sizeBytes) {
+  try {
+    return assertWorkspacePathAllowed(path, rules, sizeBytes);
+  } catch (error) {
+    throw new CliError("validation_error", error instanceof Error ? error.message : String(error));
+  }
+}
+function folderNameFromArgs(parsed) {
+  const name = parsed.command[2] ?? (typeof parsed.flags.name === "string" ? parsed.flags.name : void 0);
+  if (!name?.trim()) {
+    throw new CliError("usage_error", "Missing folder name.", {
+      hint: "Run mdocs remote create-folder <name> --json."
+    });
+  }
+  return name;
+}
+function optionalFolderTarget(value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  if (!trimmed || trimmed === "home" || trimmed === "null" || trimmed === "top") return null;
+  return trimmed;
+}
 
 // src/bridge.ts
 import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
@@ -12529,24 +13789,23 @@ async function main() {
       print(await getWorkspaceMap(io), parsed.flags);
       return;
     }
+    case "graph": {
+      print(await getWorkspaceGraph(io), parsed.flags);
+      return;
+    }
     case "state": {
       print(await getDocumentState(io, requiredArg(parsed.command[1], "path")), parsed.flags);
       return;
     }
     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,
@@ -12559,12 +13818,20 @@ async function main() {
           ...image2,
           ...image2.workspacePath ? { absolutePath: resolve5(cwd, image2.workspacePath) } : {}
         })),
-        comments: state.sidecar.comments.filter((comment2) => comment2.status === "open"),
-        suggestions: state.sidecar.suggestions.filter((suggestion) => suggestion.status === "open"),
-        anchors: state.anchors
+        links: state.links,
+        ...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);
@@ -12822,8 +14089,11 @@ Commands:
   agent commands --json              Print machine-readable command metadata
   init [path]                         Initialize .mdocs and index Markdown files
   map --json                          Print workspace map
+  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
@@ -12841,9 +14111,13 @@ 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|context|comment|suggest  Work with the active remote join
+  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> --token <bridge-token>
                                       Sync an approved local root with the workspace
                                       (--token from the web "Bind agent filesystem"