@magic-markdown/cli 0.3.12 → 0.3.17

package/dist/index.js

@@ -270,8 +270,8 @@ var require_punycode = __commonJS({
 });
 
 // src/index.ts
-import { readFile as readFile6 } from "node:fs/promises";
-import { resolve as resolve5 } from "node:path";
+import { readFile as readFile7 } from "node:fs/promises";
+import { resolve as resolve6 } from "node:path";
 
 // ../core/src/types.ts
 var SIDECAR_SCHEMA_VERSION = 1;
@@ -339,6 +339,7 @@ var POLLUTING_PATTERNS = [
   { name: "CriticMarkup substitution", pattern: /\{~~[\s\S]*?~~\}/ },
   { name: "CriticMarkup comment", pattern: /\{>>[\s\S]*?<<\}/ },
   { name: "mdocs HTML marker", pattern: /<!--\s*mdocs:/i },
+  { name: "mdocs suggestion marker", pattern: /<!--\s*\/?\s*mdocs-suggestion\b/i },
   { name: "mdocs directive", pattern: /:{1,3}(?:comment|suggestion|anchor)\b/i }
 ];
 function findCleanMarkdownViolations(markdown) {
@@ -405,7 +406,7 @@ function replacementLinesForRange(replacement) {
 function extractMarkdownImages(markdown, documentPath) {
   const masked = maskCode(markdown);
   const referenceDefinitions = collectReferenceDefinitions(markdown, masked);
-  const lineStarts = getLineStarts(markdown);
+  const lineStarts2 = getLineStarts(markdown);
   const images = [];
   let index = 0;
   while (index < masked.length) {
@@ -423,7 +424,7 @@ function extractMarkdownImages(markdown, documentPath) {
     }
     const alt = markdown.slice(labelOpen + 1, labelClose);
     const afterLabel = labelClose + 1;
-    const position = positionAt(lineStarts, start);
+    const position = positionAt(lineStarts2, start);
     if (masked[afterLabel] === "(") {
       const destinationClose = findClosingParen(markdown, afterLabel + 1);
       if (destinationClose === -1) {
@@ -491,7 +492,7 @@ function extractMarkdownLinks(markdown) {
   const codeMasked = maskCode(markdown);
   const referenceDefinitions = collectReferenceDefinitions(markdown, codeMasked);
   const masked = maskReferenceDefinitions(markdown, codeMasked);
-  const lineStarts = getLineStarts(markdown);
+  const lineStarts2 = getLineStarts(markdown);
   const links = [];
   let index = 0;
   while (index < masked.length) {
@@ -508,7 +509,7 @@ function extractMarkdownLinks(markdown) {
     }
     const label = markdown.slice(start + 1, labelClose);
     const afterLabel = labelClose + 1;
-    const position = positionAt(lineStarts, start);
+    const position = positionAt(lineStarts2, start);
     if (masked[afterLabel] === "(") {
       const destinationClose = findClosingParen(markdown, afterLabel + 1);
       if (destinationClose === -1) {
@@ -564,7 +565,7 @@ function extractMarkdownLinks(markdown) {
     }
     index = labelClose + 1;
   }
-  extractWikilinks(markdown, masked, lineStarts).forEach((link2) => links.push(link2));
+  extractWikilinks(markdown, masked, lineStarts2).forEach((link2) => links.push(link2));
   return links.sort((left, right) => left.line - right.line || left.column - right.column);
 }
 function toImageReference(image2) {
@@ -591,7 +592,7 @@ function toLinkReference(link2) {
     syntax: link2.syntax
   };
 }
-function extractWikilinks(markdown, masked, lineStarts) {
+function extractWikilinks(markdown, masked, lineStarts2) {
   const links = [];
   let index = 0;
   while (index < masked.length) {
@@ -608,7 +609,7 @@ function extractWikilinks(markdown, masked, lineStarts) {
     }
     const parsed = parseWikilinkBody(markdown.slice(start + 2, close2));
     if (parsed) {
-      const position = positionAt(lineStarts, start);
+      const position = positionAt(lineStarts2, start);
       links.push({
         label: parsed.label ?? parsed.target,
         target: parsed.target,
@@ -888,12 +889,12 @@ function getLineStarts(value) {
   }
   return starts;
 }
-function positionAt(lineStarts, index) {
+function positionAt(lineStarts2, index) {
   let low = 0;
-  let high = lineStarts.length - 1;
+  let high = lineStarts2.length - 1;
   while (low <= high) {
     const middle = Math.floor((low + high) / 2);
-    const start = lineStarts[middle] ?? 0;
+    const start = lineStarts2[middle] ?? 0;
     if (start <= index) {
       low = middle + 1;
     } else {
@@ -903,7 +904,7 @@ function positionAt(lineStarts, index) {
   const lineIndex = Math.max(0, high);
   return {
     line: lineIndex + 1,
-    column: index - (lineStarts[lineIndex] ?? 0) + 1
+    column: index - (lineStarts2[lineIndex] ?? 0) + 1
   };
 }
 
@@ -918,7 +919,8 @@ function selectorFromRange(markdown, range) {
 function remapAnchor(markdown, anchor) {
   const lines = getLines(markdown);
   const quoteLines = anchor.selector.quote.split(/\r?\n/);
-  const best = findQuote(lines, quoteLines);
+  const candidates = findQuoteCandidates(lines, quoteLines);
+  const best = bestCandidate(lines, candidates, anchor.selector);
   if (!best) {
     return {
       ...anchor,
@@ -939,284 +941,494 @@ function remapAnchor(markdown, anchor) {
 function remapAnchors(markdown, anchors) {
   return anchors.map((anchor) => remapAnchor(markdown, anchor));
 }
-function findQuote(lines, quoteLines) {
-  if (quoteLines.length === 0) return void 0;
+function findQuoteCandidates(lines, quoteLines) {
+  if (quoteLines.length === 0) return [];
+  const ranges = [];
+  const quoteText = quoteLines.join("\n");
   for (let index = 0; index <= lines.length - quoteLines.length; index += 1) {
     const candidate = lines.slice(index, index + quoteLines.length);
-    if (candidate.join("\n") === quoteLines.join("\n")) {
-      return { startLine: index + 1, endLine: index + quoteLines.length };
-    }
+    if (candidate.join("\n") === quoteText) ranges.push({ startLine: index + 1, endLine: index + quoteLines.length });
   }
-  return void 0;
+  return ranges;
+}
+function bestCandidate(lines, candidates, selector) {
+  if (candidates.length <= 1) return candidates[0];
+  const scored = candidates.map((range) => ({ range, score: scoreContext(lines, range.startLine, range.endLine, selector) })).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);
+  return tied.length === 1 ? best.range : void 0;
 }
 function scoreContext(lines, startLine, endLine, selector) {
   let score = 0.7;
-  if (selector.prefix) {
-    const expectedPrefix = selector.prefix.split(/\r?\n/).filter(Boolean).slice(-3).join("\n");
-    const actualPrefix = lines.slice(Math.max(0, startLine - 4), startLine - 1).join("\n");
+  const expectedPrefix = contextPrefix(selector.prefix);
+  if (expectedPrefix) {
+    const actualPrefix = contextPrefix(lines.slice(Math.max(0, startLine - 4), startLine - 1).join("\n"));
     if (expectedPrefix && actualPrefix.endsWith(expectedPrefix)) score += 0.15;
   }
-  if (selector.suffix) {
-    const expectedSuffix = selector.suffix.split(/\r?\n/).filter(Boolean).slice(0, 3).join("\n");
-    const actualSuffix = lines.slice(endLine, endLine + 3).join("\n");
+  const expectedSuffix = contextSuffix(selector.suffix);
+  if (expectedSuffix) {
+    const actualSuffix = contextSuffix(lines.slice(endLine, endLine + 3).join("\n"));
     if (expectedSuffix && 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") ?? "";
+}
+function contextSuffix(value) {
+  return value?.split(/\r?\n/).filter(Boolean).slice(0, 3).join("\n") ?? "";
+}
 
-// ../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;
+// ../core/src/review-markdown.ts
+var START_MARKER = "<!--mdocs-suggestion";
+var END_MARKER = "<!--/mdocs-suggestion-->";
+function parseReviewMarkdown(reviewMarkdown) {
+  const segments = [];
+  const suggestions = [];
+  let cursor = 0;
+  let canonicalOffset = 0;
+  while (cursor < reviewMarkdown.length) {
+    const markerStart = reviewMarkdown.indexOf(START_MARKER, cursor);
+    if (markerStart === -1) {
+      appendTextSegment(reviewMarkdown, segments, cursor, reviewMarkdown.length, canonicalOffset);
+      break;
+    }
+    appendTextSegment(reviewMarkdown, segments, cursor, markerStart, canonicalOffset);
+    canonicalOffset += markerStart - cursor;
+    const startClose = reviewMarkdown.indexOf("-->", markerStart);
+    if (startClose === -1) throw invalidReviewMarkdown("Unclosed mdocs suggestion marker.");
+    const attrs2 = parseMarkerAttributes(reviewMarkdown.slice(markerStart + START_MARKER.length, startClose));
+    if (!attrs2.id) throw invalidReviewMarkdown("Suggestion marker is missing an id.");
+    if (attrs2.kind !== "insert" && attrs2.kind !== "delete" && attrs2.kind !== "replace") {
+      throw invalidReviewMarkdown(`Suggestion ${attrs2.id} has an invalid kind.`);
+    }
+    const bodyStart = startClose + 3;
+    const markerEnd = reviewMarkdown.indexOf(END_MARKER, bodyStart);
+    if (markerEnd === -1) throw invalidReviewMarkdown(`Suggestion ${attrs2.id} is missing its closing marker.`);
+    const body = reviewMarkdown.slice(bodyStart, markerEnd);
+    if (body.includes(START_MARKER)) throw invalidReviewMarkdown(`Suggestion ${attrs2.id} contains a nested suggestion.`);
+    const parsedBody = parseSuggestionBody(attrs2.kind, body, attrs2.id);
+    const token = {
+      id: attrs2.id,
+      kind: attrs2.kind,
+      form: parsedBody.before.includes("\n") || parsedBody.after.includes("\n") ? "block" : "inline",
+      author: actorFromAttributes(attrs2),
+      message: attrs2.message,
+      createdAt: attrs2.createdAt,
+      updatedAt: attrs2.updatedAt,
+      before: parsedBody.before,
+      after: parsedBody.after,
+      markerStart,
+      markerEnd: markerEnd + END_MARKER.length,
+      canonicalStart: canonicalOffset,
+      canonicalEnd: canonicalOffset + parsedBody.before.length,
+      raw: reviewMarkdown.slice(markerStart, markerEnd + END_MARKER.length)
+    };
+    segments.push({ type: "suggestion", token });
+    suggestions.push(token);
+    canonicalOffset += token.before.length;
+    cursor = token.markerEnd;
+  }
+  return {
+    reviewMarkdown,
+    canonicalMarkdown: canonicalFromSegments(segments, statusLookup(void 0)),
+    segments,
+    suggestions
   };
-  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;
-      }
+}
+function projectCanonicalMarkdown(reviewMarkdown, sidecarStatuses) {
+  return canonicalFromSegments(parseReviewMarkdown(reviewMarkdown).segments, statusLookup(sidecarStatuses));
+}
+function deriveSidecarFromReviewMarkdown(sidecar, reviewMarkdown, options) {
+  const parsed = parseReviewMarkdown(reviewMarkdown);
+  const now = options.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const existingSuggestions = new Map(sidecar.suggestions.map((suggestion) => [suggestion.id, suggestion]));
+  const existingAnchors = new Map(sidecar.anchors.map((anchor) => [anchor.id, anchor]));
+  const anchors = sidecar.anchors.filter((anchor) => anchor.kind !== "suggestion");
+  const suggestions = [];
+  const base = { contentHash: contentHashForText(parsed.canonicalMarkdown), ...options.baseHead ? { head: options.baseHead } : {} };
+  for (const token of parsed.suggestions) {
+    const existing = existingSuggestions.get(token.id);
+    const anchorId = existing?.anchorId ?? stableAnchorIdForSuggestion(token.id);
+    const range = lineRangeForCanonicalSpan(parsed.canonicalMarkdown, token.canonicalStart, token.canonicalEnd);
+    const selector = selectorForCanonicalSpan(parsed.canonicalMarkdown, token.canonicalStart, token.canonicalEnd);
+    const anchor = {
+      ...existingAnchors.get(anchorId) ?? {},
+      id: anchorId,
+      kind: "suggestion",
+      status: "mapped",
+      selector,
+      range,
+      confidence: 1,
+      updatedAt: now
+    };
+    const author = token.author ?? existing?.author ?? options.author;
+    const message = token.message ?? existing?.message ?? "Suggested edit";
+    const suggestion = {
+      ...existing ?? {},
+      id: token.id,
+      anchorId,
+      status: "open",
+      kind: token.kind,
+      author,
+      message,
+      patch: {
+        type: "replace_lines",
+        range,
+        before: token.before,
+        after: token.after
+      },
+      base: existing?.base ?? base,
+      diff: {
+        before: token.before,
+        after: token.after,
+        summary: diffSummary(token.before, token.after)
+      },
+      projectionStatus: "clean",
+      reviewRange: { start: token.markerStart, end: token.markerEnd },
+      createdAt: token.createdAt ?? existing?.createdAt ?? now,
+      updatedAt: token.updatedAt ?? now
+    };
+    anchors.push(anchor);
+    suggestions.push(suggestion);
+  }
+  return {
+    ...sidecar,
+    reviewMarkdown,
+    anchors,
+    suggestions,
+    updatedAt: now
+  };
+}
+function createSuggestionMarkup(reviewMarkdown, patch, metadata) {
+  const parsed = parseReviewMarkdown(reviewMarkdown);
+  assertNoDuplicateSuggestionId(parsed, metadata.suggestionId);
+  const [contentStart, contentEnd] = lineRangeOffsets(parsed.canonicalMarkdown, patch.range);
+  const selected = parsed.canonicalMarkdown.slice(contentStart, contentEnd);
+  if (selected !== patch.before) {
+    throw new MdocsError(
+      "conflict",
+      "Suggestion target does not match the review document projection.",
+      "Re-read the document and create the suggestion against the current canonical text."
+    );
+  }
+  const [canonicalStart, canonicalEnd] = lineRangeReplacementOffsets(parsed.canonicalMarkdown, patch.range);
+  if (selectionTouchesSuggestion(parsed.suggestions, canonicalStart, canonicalEnd)) {
+    throw new MdocsError(
+      "conflict",
+      "Suggestion overlaps an unresolved suggestion.",
+      "Accept or reject the existing suggestion before creating another edit over the same text."
+    );
+  }
+  const rawStart = rawOffsetForCanonicalOffset(parsed.segments, canonicalStart);
+  const rawEnd = rawOffsetForCanonicalOffset(parsed.segments, canonicalEnd);
+  const before = parsed.canonicalMarkdown.slice(canonicalStart, canonicalEnd);
+  const after = replacementTextForSpan(parsed.canonicalMarkdown, patch, canonicalStart, canonicalEnd);
+  const marker = formatSuggestionMarker(metadata, kindForText(before, after), before, after);
+  const nextReviewMarkdown = `${reviewMarkdown.slice(0, rawStart)}${marker}${reviewMarkdown.slice(rawEnd)}`;
+  const token = parseReviewMarkdown(nextReviewMarkdown).suggestions.find((candidate) => candidate.id === metadata.suggestionId);
+  if (!token) throw invalidReviewMarkdown(`Failed to create suggestion ${metadata.suggestionId}.`);
+  return { reviewMarkdown: nextReviewMarkdown, token };
+}
+function projectReviewMarkdown(canonicalMarkdown, suggestions) {
+  let reviewMarkdown = canonicalMarkdown;
+  const open = suggestions.filter((suggestion) => suggestion.status === "open" && suggestion.patch?.type === "replace_lines").slice().sort((left, right) => left.patch.range.startLine - right.patch.range.startLine);
+  for (const suggestion of open) {
+    try {
+      reviewMarkdown = createSuggestionMarkup(reviewMarkdown, suggestion.patch, {
+        suggestionId: suggestion.id,
+        author: suggestion.author,
+        message: suggestion.message,
+        createdAt: suggestion.createdAt,
+        updatedAt: suggestion.updatedAt
+      }).reviewMarkdown;
+    } catch {
     }
   }
-  flush(row, col);
-  return regions;
+  return reviewMarkdown;
 }
-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 });
+function resolveSuggestionMarkup(reviewMarkdown, suggestionId, resolution) {
+  const parsed = parseReviewMarkdown(reviewMarkdown);
+  const token = parsed.suggestions.find((candidate) => candidate.id === suggestionId);
+  if (!token) {
+    throw new MdocsError("not_found", `Unknown suggestion: ${suggestionId}`, "Refresh review state and try again.");
+  }
+  const resolved = resolutionText(token, resolution);
+  return `${reviewMarkdown.slice(0, token.markerStart)}${resolved}${reviewMarkdown.slice(token.markerEnd)}`;
+}
+function escapeReviewSuggestionText(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll("{++", "\\{++").replaceAll("++}", "\\++}").replaceAll("{--", "\\{--").replaceAll("--}", "\\--}").replaceAll("{~~", "\\{~~").replaceAll("~>", "\\~>").replaceAll("~~}", "\\~~}");
+}
+function lineRangeForCanonicalSpan(markdown, start, end) {
+  assertCanonicalSpan(markdown, start, end);
+  return lineRangeForOffsets(markdown, start, end);
+}
+function selectorForCanonicalSpan(markdown, start, end) {
+  assertCanonicalSpan(markdown, start, end);
+  const context = 160;
+  const prefix = markdown.slice(Math.max(0, start - context), start);
+  const suffix = markdown.slice(end, Math.min(markdown.length, end + context));
+  return {
+    quote: markdown.slice(start, end),
+    ...prefix ? { prefix } : {},
+    ...suffix ? { suffix } : {}
+  };
+}
+function appendTextSegment(source, segments, start, end, canonicalStart) {
+  if (end <= start) return;
+  segments.push({
+    type: "text",
+    text: source.slice(start, end),
+    start,
+    end,
+    canonicalStart,
+    canonicalEnd: canonicalStart + (end - start)
+  });
+}
+function canonicalFromSegments(segments, statuses) {
+  return segments.map((segment) => {
+    if (segment.type === "text") return segment.text;
+    const status = statuses(segment.token.id);
+    if (status === "accepted") return acceptedText(segment.token);
+    return originalText(segment.token);
+  }).join("");
+}
+function parseMarkerAttributes(raw) {
+  const attrs2 = {};
+  const pattern = /\s+([a-zA-Z][\w:-]*)="([^"]*)"/g;
+  let match2;
+  while ((match2 = pattern.exec(raw)) !== null) {
+    const key = match2[1];
+    if (key === "id" || key === "kind" || key === "authorId" || key === "authorKind" || key === "authorName" || key === "authorEmail" || key === "message" || key === "createdAt" || key === "updatedAt") {
+      attrs2[key] = decodeAttribute(match2[2] ?? "");
     }
   }
-  return clusters;
+  return attrs2;
 }
-function sideSlice(side, regions, lo, hi) {
-  return side.slice(lo + sideDeltaBefore(regions, lo, false), hi + sideDeltaBefore(regions, hi, true));
+function actorFromAttributes(attrs2) {
+  if (!attrs2.authorId || !attrs2.authorName) return void 0;
+  const kind = attrs2.authorKind === "agent" || attrs2.authorKind === "system" || attrs2.authorKind === "human" ? attrs2.authorKind : "human";
+  return {
+    id: attrs2.authorId,
+    kind,
+    name: attrs2.authorName,
+    ...attrs2.authorEmail ? { email: attrs2.authorEmail } : {}
+  };
 }
-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;
+function parseSuggestionBody(kind, body, id) {
+  if (kind === "insert") {
+    return { before: "", after: parseWrappedBody(body, "{++", "++}", id) };
+  }
+  if (kind === "delete") {
+    return { before: parseWrappedBody(body, "{--", "--}", id), after: "" };
+  }
+  if (!body.startsWith("{~~") || !body.endsWith("~~}")) {
+    throw invalidReviewMarkdown(`Replacement suggestion ${id} has invalid CriticMarkup payload.`);
   }
-  return delta;
+  const inner = body.slice(3, -3);
+  const separator = findUnescaped2(inner, "~>");
+  if (separator === -1) throw invalidReviewMarkdown(`Replacement suggestion ${id} is missing a separator.`);
+  return {
+    before: unescapeReviewSuggestionText(inner.slice(0, separator)),
+    after: unescapeReviewSuggestionText(inner.slice(separator + 2))
+  };
 }
-function linesEqual(left, right) {
-  return left.length === right.length && left.every((line, index) => line === right[index]);
+function parseWrappedBody(body, open, close2, id) {
+  if (!body.startsWith(open) || !body.endsWith(close2) || isEscapedAt(body, body.length - close2.length)) {
+    throw invalidReviewMarkdown(`Suggestion ${id} has invalid CriticMarkup payload.`);
+  }
+  return unescapeReviewSuggestionText(body.slice(open.length, -close2.length));
 }
-
-// ../core/src/patches.ts
-function applySuggestion(markdown, suggestion, input) {
-  if (suggestion.status !== "open") {
-    throw new MdocsError(
-      "validation_error",
-      `Suggestion ${suggestion.id} is not open (status: ${suggestion.status}).`,
-      "Only open suggestions can be applied. List open suggestions with the suggestions command."
-    );
+function formatSuggestionMarker(metadata, kind, before, after) {
+  const attrs2 = [
+    ["id", metadata.suggestionId],
+    ["kind", kind]
+  ];
+  if (metadata.author) {
+    attrs2.push(["authorId", metadata.author.id]);
+    attrs2.push(["authorKind", metadata.author.kind]);
+    attrs2.push(["authorName", metadata.author.name]);
+    if (metadata.author.email) attrs2.push(["authorEmail", metadata.author.email]);
+  }
+  if (metadata.message) attrs2.push(["message", metadata.message]);
+  if (metadata.createdAt) attrs2.push(["createdAt", metadata.createdAt]);
+  if (metadata.updatedAt) attrs2.push(["updatedAt", metadata.updatedAt]);
+  const attrText = attrs2.map(([key, value]) => `${key}="${encodeAttribute(value)}"`).join(" ");
+  const body = kind === "insert" ? `{++${escapeReviewSuggestionText(after)}++}` : kind === "delete" ? `{--${escapeReviewSuggestionText(before)}--}` : `{~~${escapeReviewSuggestionText(before)}~>${escapeReviewSuggestionText(after)}~~}`;
+  return `${START_MARKER} ${attrText} -->${body}${END_MARKER}`;
+}
+function stableAnchorIdForSuggestion(suggestionId) {
+  return `anchor_${suggestionId.replace(/[^a-zA-Z0-9_:-]/g, "_")}`;
+}
+function diffSummary(before, after) {
+  if (!before && after) return "Inserted text";
+  if (before && !after) return "Deleted text";
+  return "Replaced text";
+}
+function unescapeReviewSuggestionText(value) {
+  let result = "";
+  for (let index = 0; index < value.length; index += 1) {
+    if (value[index] !== "\\") {
+      result += value[index];
+      continue;
+    }
+    const next = value[index + 1];
+    if (next === void 0) {
+      result += "\\";
+      continue;
+    }
+    result += next;
+    index += 1;
   }
-  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."
-    );
+  return result;
+}
+function findUnescaped2(value, needle, from = 0) {
+  let index = value.indexOf(needle, from);
+  while (index !== -1) {
+    if (!isEscapedAt(value, index)) return index;
+    index = value.indexOf(needle, index + needle.length);
   }
-  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."
-    );
+  return -1;
+}
+function isEscapedAt(value, index) {
+  let slashes = 0;
+  for (let cursor = index - 1; cursor >= 0 && value[cursor] === "\\"; cursor -= 1) slashes += 1;
+  return slashes % 2 === 1;
+}
+function statusLookup(statuses) {
+  if (!statuses) return () => "open";
+  if (isStatusMap(statuses)) return (suggestionId) => statuses.get(suggestionId) ?? "open";
+  if (Array.isArray(statuses)) {
+    const map = /* @__PURE__ */ new Map();
+    for (const item of statuses) {
+      const id = item.id ?? item.suggestionId;
+      if (id && item.status) map.set(id, item.status);
+    }
+    return (suggestionId) => map.get(suggestionId) ?? "open";
   }
-  const next = replaceLineRange(markdown, range, suggestion.patch.after);
-  assertCleanMarkdown(next);
-  return next;
+  const record = statuses;
+  return (suggestionId) => record[suggestionId] ?? "open";
 }
-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;
+function isStatusMap(value) {
+  return typeof value.get === "function";
+}
+function acceptedText(token) {
+  return token.kind === "delete" ? "" : token.after;
+}
+function originalText(token) {
+  return token.kind === "insert" ? "" : token.before;
+}
+function resolutionText(token, resolution) {
+  return resolution === "accept" ? acceptedText(token) : originalText(token);
+}
+function kindForText(before, after) {
+  if (before.length === 0) return "insert";
+  if (after.length === 0) return "delete";
+  return "replace";
+}
+function assertNoDuplicateSuggestionId(parsed, suggestionId) {
+  if (parsed.suggestions.some((suggestion) => suggestion.id === suggestionId)) {
+    throw new MdocsError("validation_error", `Duplicate suggestion id: ${suggestionId}`, "Suggestion ids must be stable and unique per document.");
   }
-  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 assertCanonicalSpan(markdown, start, end) {
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start || end > markdown.length) {
+    throw new MdocsError("invalid_range", `Invalid canonical span ${start}:${end}.`, "Re-read the document and try again.");
+  }
 }
-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 });
+function selectionTouchesSuggestion(tokens, start, end) {
+  return tokens.some((token) => {
+    if (token.canonicalStart === token.canonicalEnd) return start <= token.canonicalStart && end >= token.canonicalEnd;
+    return start < token.canonicalEnd && end > token.canonicalStart;
+  });
+}
+function rawOffsetForCanonicalOffset(segments, offset) {
+  for (const segment of segments) {
+    if (segment.type === "text") {
+      if (offset >= segment.canonicalStart && offset <= segment.canonicalEnd) {
+        return segment.start + (offset - segment.canonicalStart);
+      }
+      continue;
+    }
+    const token = segment.token;
+    if (offset > token.canonicalStart && offset < token.canonicalEnd) {
+      throw new MdocsError(
+        "conflict",
+        "Selection falls inside an unresolved suggestion.",
+        "Accept or reject the existing suggestion before editing inside it."
+      );
     }
   }
-  return ranges;
+  if (offset === segmentsEndCanonicalOffset(segments)) return segmentsEndRawOffset(segments);
+  throw new MdocsError("invalid_range", "Could not map canonical offset into review Markdown.", "Re-read the document and try again.");
 }
-function rangeIsWithin(markdown, range) {
-  const lineCount = getLines(markdown).length;
-  return range.startLine >= 1 && range.endLine >= range.startLine && range.endLine <= lineCount;
+function segmentsEndCanonicalOffset(segments) {
+  const last = segments[segments.length - 1];
+  if (!last) return 0;
+  return last.type === "text" ? last.canonicalEnd : last.token.canonicalEnd;
 }
-function linePattern(value) {
-  return value.replace(/\r\n?/g, "\n").split("\n");
+function segmentsEndRawOffset(segments) {
+  const last = segments[segments.length - 1];
+  if (!last) return 0;
+  return last.type === "text" ? last.end : last.token.markerEnd;
 }
-function scoreContext2(markdown, range, anchor) {
+function lineRangeOffsets(markdown, range) {
   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;
+  if (range.startLine < 1 || range.endLine < range.startLine || range.endLine > lines.length) {
+    throw new MdocsError("invalid_range", `Invalid line range ${range.startLine}:${range.endLine}.`, "Re-read the document and try again.");
   }
-  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;
+  let start = 0;
+  for (let index = 0; index < range.startLine - 1; index += 1) start += lines[index].length + 1;
+  let end = start;
+  for (let index = range.startLine - 1; index < range.endLine; index += 1) {
+    if (index > range.startLine - 1) end += 1;
+    end += lines[index].length;
+  }
+  return [start, end];
+}
+function lineRangeReplacementOffsets(markdown, range) {
+  const [start, contentEnd] = lineRangeOffsets(markdown, range);
+  if (contentEnd < markdown.length && markdown[contentEnd] === "\n") return [start, contentEnd + 1];
+  return [start, contentEnd];
+}
+function replacementTextForSpan(markdown, patch, start, end) {
+  const applied = replaceLineRange(markdown, patch.range, patch.after);
+  const suffixLength = markdown.length - end;
+  const replacementEnd = applied.length - suffixLength;
+  if (replacementEnd < start) return "";
+  return applied.slice(start, replacementEnd);
+}
+function lineRangeForOffsets(markdown, start, end) {
+  const starts = lineStarts(markdown);
+  return {
+    startLine: lineNumberAt(starts, start),
+    endLine: lineNumberAt(starts, Math.max(start, end - 1))
+  };
+}
+function lineStarts(markdown) {
+  const starts = [0];
+  for (let index = 0; index < markdown.length; index += 1) {
+    if (markdown[index] === "\n") starts.push(index + 1);
   }
-  return Math.min(1, score);
+  return starts;
 }
-function contextPrefix(value) {
-  return value?.split(/\r?\n/).filter(Boolean).slice(-3).join("\n") || void 0;
+function lineNumberAt(starts, offset) {
+  let line = 1;
+  for (let index = 0; index < starts.length; index += 1) {
+    if (starts[index] <= offset) line = index + 1;
+    else break;
+  }
+  return line;
 }
-function contextSuffix(value) {
-  return value?.split(/\r?\n/).filter(Boolean).slice(0, 3).join("\n") || void 0;
+function encodeAttribute(value) {
+  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function decodeAttribute(value) {
+  return value.replaceAll("&quot;", '"').replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
+}
+function invalidReviewMarkdown(message) {
+  return new MdocsError("validation_error", `Invalid review Markdown: ${message}`, "Repair or remove the malformed suggestion markup.");
 }
 
 // ../core/src/graph.ts
@@ -1521,6 +1733,7 @@ async function getDocumentState(io, pathOrDocId) {
     path: entry.path,
     title: entry.title,
     markdown,
+    reviewMarkdown: nextSidecar.reviewMarkdown ?? markdown,
     sidecar: nextSidecar,
     anchors: remappedAnchors.map((anchor) => ({
       id: anchor.id,
@@ -1608,6 +1821,7 @@ async function addSuggestion(io, pathOrDocId, range, replacement, message, autho
     id: createId("suggestion"),
     anchorId: anchor.id,
     status: "open",
+    kind: replacement.length === 0 ? "delete" : before.length === 0 ? "insert" : "replace",
     author,
     message,
     patch: {
@@ -1624,53 +1838,72 @@ async function addSuggestion(io, pathOrDocId, range, replacement, message, autho
     createdAt: now,
     updatedAt: now
   };
-  await writeSidecar(io, {
-    ...state.sidecar,
-    anchors: [...state.sidecar.anchors, anchor],
-    suggestions: [...state.sidecar.suggestions, suggestion],
+  const review = createSuggestionMarkup(state.sidecar.reviewMarkdown ?? state.markdown, suggestion.patch, {
+    suggestionId: suggestion.id,
+    author,
+    message,
+    createdAt: now,
     updatedAt: now
   });
-  return suggestion;
+  const nextSidecar = deriveSidecarFromReviewMarkdown(
+    { ...state.sidecar, reviewMarkdown: review.reviewMarkdown, anchors: [...state.sidecar.anchors, anchor] },
+    review.reviewMarkdown,
+    { author, baseHead: entry?.currentSha, now }
+  );
+  await writeSidecar(io, nextSidecar);
+  const enriched = nextSidecar.suggestions.find((candidate) => candidate.id === suggestion.id);
+  if (!enriched) throw new MdocsError("validation_error", `Could not derive suggestion ${suggestion.id}.`, "Refresh review state and try again.");
+  return enriched;
 }
-async function updateSuggestionStatus(io, suggestionId, status, actor = defaultActor()) {
+async function acceptSuggestion(io, suggestionId, actor = defaultActor()) {
   const manifest = await indexWorkspace(io);
   for (const entry of manifest.docs) {
+    const markdown = await io.readText(entry.path);
     const sidecar = await readSidecar(io, entry.docId);
     const suggestion = sidecar.suggestions.find((candidate) => candidate.id === suggestionId);
     if (!suggestion) continue;
     const now = nowIso();
-    const updated = {
-      ...suggestion,
-      status,
-      updatedAt: now,
-      resolvedAt: now,
-      resolvedBy: actor
-    };
-    await writeSidecar(io, {
-      ...sidecar,
-      suggestions: sidecar.suggestions.map((candidate) => candidate.id === suggestionId ? updated : candidate),
-      updatedAt: now
-    });
-    return updated;
+    const reviewMarkdown = sidecar.reviewMarkdown ?? markdown;
+    const resolvedReviewMarkdown = resolveSuggestionMarkup(reviewMarkdown, suggestionId, "accept");
+    const nextMarkdown = projectCanonicalMarkdown(resolvedReviewMarkdown);
+    assertCleanMarkdown(nextMarkdown);
+    const nextSidecar = deriveSidecarFromReviewMarkdown(
+      { ...sidecar, reviewMarkdown: resolvedReviewMarkdown },
+      resolvedReviewMarkdown,
+      { author: suggestion.author, baseHead: entry.currentSha, now }
+    );
+    await io.writeText(entry.path, nextMarkdown);
+    await writeSidecar(io, nextSidecar);
+    return resolvedSuggestion(suggestion, "accepted", actor, now);
   }
   throw new MdocsError("not_found", `Unknown suggestion: ${suggestionId}`, "List suggestion ids with the suggestions command.");
 }
-async function acceptSuggestion(io, suggestionId, actor = defaultActor()) {
+async function rejectSuggestion(io, suggestionId, actor = defaultActor()) {
   const manifest = await indexWorkspace(io);
   for (const entry of manifest.docs) {
-    const markdown = await io.readText(entry.path);
     const sidecar = await readSidecar(io, entry.docId);
     const suggestion = sidecar.suggestions.find((candidate) => candidate.id === suggestionId);
     if (!suggestion) continue;
-    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);
+    const now = nowIso();
+    const updated = resolvedSuggestion(suggestion, "rejected", actor, now);
+    const reviewMarkdown = resolveSuggestionMarkup(sidecar.reviewMarkdown ?? "", suggestionId, "reject");
+    const nextSidecar = deriveSidecarFromReviewMarkdown({ ...sidecar, reviewMarkdown }, reviewMarkdown, {
+      author: suggestion.author,
+      now
+    });
+    await writeSidecar(io, nextSidecar);
+    return updated;
   }
   throw new MdocsError("not_found", `Unknown suggestion: ${suggestionId}`, "List suggestion ids with the suggestions command.");
 }
-async function rejectSuggestion(io, suggestionId, actor = defaultActor()) {
-  return updateSuggestionStatus(io, suggestionId, "rejected", actor);
+function resolvedSuggestion(suggestion, status, actor, now) {
+  return {
+    ...suggestion,
+    status,
+    updatedAt: now,
+    resolvedAt: now,
+    resolvedBy: actor
+  };
 }
 async function resolveComment(io, commentId, actor = defaultActor()) {
   const manifest = await indexWorkspace(io);
@@ -4606,44 +4839,46 @@ function gatherMarks(schema2, marks) {
 }
 
 // ../core/src/pm-schema.ts
+var blockAttrs = { blockId: { default: null } };
 var canonicalSchema = new Schema({
   nodes: {
     // 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*" },
+    paragraph: { group: "block", content: "inline*", attrs: blockAttrs },
     heading: {
       group: "block",
       content: "inline*",
-      attrs: { level: { default: 1 } }
+      attrs: { ...blockAttrs, level: { default: 1 } }
     },
-    blockquote: { group: "block", content: "block+" },
+    blockquote: { group: "block", content: "block+", attrs: blockAttrs },
     codeBlock: {
       group: "block",
       content: "text*",
       marks: "",
       code: true,
-      attrs: { language: { default: null } }
+      attrs: { ...blockAttrs, language: { default: null } }
     },
-    horizontalRule: { group: "block" },
-    bulletList: { group: "block", content: "listItem+" },
+    horizontalRule: { group: "block", attrs: blockAttrs },
+    bulletList: { group: "block", content: "listItem+", attrs: blockAttrs },
     orderedList: {
       group: "block",
       content: "listItem+",
-      attrs: { start: { default: 1 } }
+      attrs: { ...blockAttrs, start: { default: 1 } }
     },
-    listItem: { content: "paragraph block*" },
-    taskList: { group: "block", content: "taskItem+" },
+    listItem: { content: "paragraph block*", attrs: blockAttrs },
+    taskList: { group: "block", content: "taskItem+", attrs: blockAttrs },
     taskItem: {
       content: "paragraph block*",
-      attrs: { checked: { default: false } }
+      attrs: { ...blockAttrs, checked: { default: false } }
     },
-    table: { group: "block", content: "tableRow+" },
-    tableRow: { content: "(tableCell | tableHeader)+" },
+    table: { group: "block", content: "tableRow+", attrs: blockAttrs },
+    tableRow: { content: "(tableCell | tableHeader)+", attrs: blockAttrs },
     tableHeader: {
       content: "block+",
       attrs: {
+        ...blockAttrs,
         colspan: { default: 1 },
         rowspan: { default: 1 },
         colwidth: { default: null }
@@ -4652,6 +4887,7 @@ var canonicalSchema = new Schema({
     tableCell: {
       content: "block+",
       attrs: {
+        ...blockAttrs,
         colspan: { default: 1 },
         rowspan: { default: 1 },
         colwidth: { default: null }
@@ -10950,6 +11186,36 @@ function backticksFor2(node, side) {
   return result;
 }
 
+// ../core/src/pm-parse.ts
+var parser = new MarkdownParser(canonicalSchema, new lib_default(), {
+  blockquote: { block: "blockquote" },
+  paragraph: { block: "paragraph" },
+  list_item: { block: "listItem" },
+  bullet_list: { block: "bulletList" },
+  ordered_list: {
+    block: "orderedList",
+    getAttrs: (tok) => ({ start: Number(tok.attrGet("start")) || 1 })
+  },
+  heading: { block: "heading", getAttrs: (tok) => ({ level: Number(tok.tag.slice(1)) || 1 }) },
+  code_block: { block: "codeBlock", noCloseToken: true },
+  fence: { block: "codeBlock", getAttrs: (tok) => ({ language: tok.info || null }), noCloseToken: true },
+  hr: { node: "horizontalRule" },
+  hardbreak: { node: "hardBreak" },
+  em: { mark: "italic" },
+  strong: { mark: "bold" },
+  s: { mark: "strike" },
+  link: { mark: "link", getAttrs: (tok) => ({ href: tok.attrGet("href") }) },
+  code_inline: { mark: "code", noCloseToken: true },
+  image: {
+    node: "image",
+    getAttrs: (tok) => ({
+      alt: tok.content,
+      src: tok.attrGet("src"),
+      title: tok.attrGet("title")
+    })
+  }
+});
+
 // ../core/src/remote-document-io.ts
 var RemoteDocumentIO = class {
   constructor(document) {
@@ -10997,7 +11263,7 @@ var RemoteDocumentIO = class {
 };
 
 // src/agent.ts
-var CLI_VERSION = "0.3.12";
+var CLI_VERSION = "0.3.17";
 var CLI_PACKAGE_NAME = "@magic-markdown/cli";
 var AGENT_COMMANDS = [
   {
@@ -11058,10 +11324,11 @@ var AGENT_COMMANDS = [
   {
     name: "remote",
     summary: "Read, organize, comment on, suggest edits to, monitor, and restore the active Magic Markdown remote join.",
-    usage: "mdocs remote map|graph|context|review|create-file|move-file|comment|suggest|reject|events|history|restore|library|create-folder|update-folder|move-root|invite-folder --json",
+    usage: "mdocs remote status|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 status --expect-scope file --expect-root root_abc --expect-doc doc_abc --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",
@@ -11081,6 +11348,7 @@ var AGENT_COMMANDS = [
       "mdocs remote invite-folder fold_abc123 --email person@example.com --role edit --json"
     ],
     notes: [
+      "Use remote status --json immediately after joining when the handoff includes expected scope/root/doc values. If it reports wrong_binding, stop and ask for the correct share or connector.",
       "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.",
@@ -11172,7 +11440,7 @@ var AGENT_COMMANDS = [
   },
   {
     name: "suggest",
-    summary: "Create a sidecar replacement suggestion without modifying clean Markdown.",
+    summary: "Create a reviewMarkdown replacement suggestion without modifying canonical Markdown.",
     usage: "mdocs suggest <path|docId> --range <start:end> --with <markdown> --message <text> --json",
     output: "json",
     mutates: true,
@@ -11282,20 +11550,39 @@ var AGENT_COMMANDS = [
   {
     name: "bridge resume",
     summary: "Backfill missed Magic changes after an agent restart, then keep the bridge running.",
-    usage: "mdocs bridge resume --root <path> [--url <base-url>] [--workspace <id>] [--root-id <id>] [--request-token] [--once]",
+    usage: "mdocs bridge resume --root <path> [--url <base-url>] [--workspace <id>] [--root-id <id>] [--request-token] [--forever] [--once]",
     output: "long-running",
     mutates: true,
     examples: [
-      "mdocs bridge resume --root . --request-token",
+      "mdocs bridge resume --root . --forever --request-token",
       "mdocs bridge resume --root . --once --request-token"
     ],
     notes: [
       "Reads non-secret connection defaults from .mdocs/bridge.json written by bridge setup.",
       "Use this after a sandbox/container/agent session restarts. It backfills canonical Magic changes before publishing local edits.",
+      "--forever is the intended startup/sandbox command: keep it running for live collaboration and liveness heartbeats.",
       "--request-token opens a human approval URL when no MDOCS_BRIDGE_TOKEN is available; do not ask users to paste bridge tokens by default.",
       "--once performs only the backfill/reconcile step and exits."
     ]
   },
+  {
+    name: "bridge startup",
+    summary: "Write a bridge runner and optional launchd/systemd startup hook for long-lived bridge environments.",
+    usage: "mdocs bridge startup --root <path> [--mode auto|shell|launchd|systemd] [--install] [--json]",
+    output: "json",
+    mutates: true,
+    examples: [
+      "mdocs bridge startup --root . --json",
+      "mdocs bridge startup --root . --mode shell --json",
+      "mdocs bridge startup --root . --mode systemd --install --json"
+    ],
+    notes: [
+      "Run this after bridge setup has written .mdocs/bridge.json.",
+      "Sandbox providers should put the returned startupCommand in their on-start hook.",
+      "--install installs and starts the generated launchd/systemd user service when the host supports it.",
+      "The generated runner stores no bridge token; provide MDOCS_BRIDGE_TOKEN through platform secrets if you use manual tokens."
+    ]
+  },
   {
     name: "bridge",
     summary: "Sync a local Markdown root with a Magic workspace over WebSocket (long-running).",
@@ -11358,11 +11645,12 @@ Run \`mdocs help <command>\` (or \`mdocs <command> --help\`) for usage, examples
 ## Start Here
 
 1. If given a Magic Markdown share URL, run \`mdocs join <share-url> --json\` first, and always include \`--name "<your agent name>"\` (for example \`--name "Claude Code"\`) so collaborators can see which agent is connected. Use \`mdocs remote ...\` commands after joining.
-2. If working in a local workspace, run \`mdocs doctor --json\` to validate the workspace and learn recommended next commands.
-3. Run \`mdocs map --json\` or \`mdocs remote map --json\` to list documents, paths, docIds, open comments, open suggestions, anchor review counts, and link counts. File-scoped joins (most share links) cover a single document, so \`mdocs remote map\` is unavailable for them \u2014 use \`mdocs remote context --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.
+2. If the handoff includes expected binding values, run \`mdocs remote status --expect-scope <file|project> --expect-root <rootId> --expect-doc <docId> --json\` after joining. If it reports \`wrong_binding\`, stop and ask for the correct share or connector.
+3. If working in a local workspace, run \`mdocs doctor --json\` to validate the workspace and learn recommended next commands.
+4. 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>\`.
+5. 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.
+6. 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.
+7. 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 hand-edit canonical Markdown files or \`.mdocs\` reviewMarkdown syntax directly.
 
 ## Filesystem Bridge / Resume
 
@@ -11383,16 +11671,24 @@ Return the Magic approval link and keep the bridge process running after approva
 If your sandbox, container, terminal, or agent session restarts after setup, do not ask for a raw bridge token. Start the latest CLI again and resume from the same root:
 
 \`\`\`bash
-npx --yes --package=@magic-markdown/cli@latest mdocs bridge resume --root . --request-token
+npx --yes --package=@magic-markdown/cli@latest mdocs bridge resume --root . --forever --request-token
+\`\`\`
+
+\`bridge resume --forever\` reads non-secret defaults from \`.mdocs/bridge.json\`, backfills missed Magic changes before publishing local edits, and then keeps polling/watching with liveness heartbeats. Use \`--once\` only when the user asked for a one-shot backfill rather than a live bridge.
+
+For sandboxes, VPSs, or local machines that support startup hooks, generate a durable runner after setup:
+
+\`\`\`bash
+npx --yes --package=@magic-markdown/cli@latest mdocs bridge startup --root . --json
 \`\`\`
 
-\`bridge resume\` reads non-secret defaults from \`.mdocs/bridge.json\`, backfills missed Magic changes before publishing local edits, and then keeps polling/watching. Use \`--once\` only when the user asked for a one-shot backfill rather than a live bridge.
+Put the returned \`startupCommand\` into the provider's on-start hook. On local macOS or systemd Linux hosts, \`mdocs bridge startup --root . --install\` writes and starts a user service. The generated runner stores no bridge token; use platform secrets for \`MDOCS_BRIDGE_TOKEN\` if you manage tokens manually.
 
 If Magic and the local root both changed the same document while you were offline, the bridge keeps the Magic canonical path, saves your local divergent version as a \`.conflict-...\` Markdown copy, and lets the conflict copy sync as a normal file. If Magic reports a server-side conflict, wait for the human to resolve it in Magic Markdown before retrying content pushes.
 
 ## Editing Rules
 
-- Comments and suggestions are sidecar operations. They should not modify clean Markdown until a suggestion is accepted.
+- Comments are sidecar operations; suggestions are reviewMarkdown operations derived into sidecar state. They should not modify canonical 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.
@@ -11407,7 +11703,7 @@ If Magic and the local root both changed the same document while you were offlin
 ## Errors, Conflicts, and Exit Codes
 
 - 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).
+- Exit codes: 0 ok, 1 internal, 2 usage/invalid range, 3 conflict, 4 not found or wrong binding, 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 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.
@@ -11431,7 +11727,7 @@ Start the local stdio MCP server with:
 mdocs serve-mcp --cwd /path/to/workspace
 \`\`\`
 
-The MCP server exposes document resources, image resources, workspace map and graph resources, an agent guide resource, typed tools for comments and suggestions, and the \`magic_markdown_agent_workflow\` prompt. 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.
+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 \`magic_status\` first when expected binding values are available; stop if it returns \`wrong_binding\`. Then 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() {
@@ -11459,6 +11755,7 @@ var CLI_EXIT_CODES = {
   invalid_range: 2,
   conflict: 3,
   not_found: 4,
+  wrong_binding: 4,
   network_error: 5,
   unauthorized: 6
 };
@@ -12022,7 +12319,7 @@ var tools = [
   },
   {
     name: "mdocs_suggest",
-    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.",
+    description: "Create a reviewMarkdown replacement suggestion without modifying canonical Markdown. Prefer the smallest coherent range; use longer ranges only when the broader rewrite is genuinely needed.",
     inputSchema: {
       type: "object",
       properties: {
@@ -12511,6 +12808,16 @@ async function postReview(record, docId, additions, actor) {
   );
   return response.document;
 }
+async function postReviewOperation(record, docId, operation, actor) {
+  return fetchJson(
+    `${record.origin}/api/workspaces/${encodeURIComponent(record.workspaceId)}/roots/${encodeURIComponent(record.rootId)}/documents/${encodeURIComponent(docId)}/review-ops`,
+    {
+      method: "POST",
+      headers: { ...shareHeaders(record.shareUrl), "Content-Type": "application/json" },
+      body: JSON.stringify({ actor, operation })
+    }
+  );
+}
 async function pushDocument(record, baseDocument, markdown, sidecar) {
   const createdAt = (/* @__PURE__ */ new Date()).toISOString();
   const payload = {
@@ -12769,7 +13076,6 @@ function joinStoreDir(root) {
 }
 
 // src/remote.ts
-var PUSH_REBASE_ATTEMPTS = 3;
 async function runJoinCommand(root, parsed) {
   const target = parsed.command[1];
   const existingId = typeof parsed.flags.id === "string" ? parsed.flags.id : void 0;
@@ -12808,6 +13114,8 @@ async function runJoinsCommand(root) {
 async function runRemoteCommand(root, subcommand, parsed) {
   const record = await normalizedSelectedJoin(root, parsed.flags);
   switch (subcommand) {
+    case "status":
+      return remoteStatus(record, parsed.flags);
     case "map":
     case void 0: {
       if (record.scope === "file") {
@@ -12861,10 +13169,53 @@ async function runRemoteCommand(root, subcommand, parsed) {
       return rejoin(root, record.joinId, parsed.flags);
     default:
       throw new CliError("usage_error", `Unknown remote subcommand: ${subcommand}`, {
-        hint: "Use mdocs remote map|graph|context|review|create-file|move-file|comment|suggest|reject|events|history|restore|library|create-folder|update-folder|move-root|invite-folder|rejoin."
+        hint: "Use mdocs remote status|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 remoteStatus(record, flags) {
+  const document = record.rootId && record.docId ? (await fetchState(record)).document : void 0;
+  const expected = expectedBinding(flags);
+  const actual = {
+    joinId: record.joinId,
+    scope: record.scope,
+    workspaceId: record.workspaceId,
+    rootId: record.rootId,
+    docId: document?.docId ?? record.docId,
+    path: document?.path,
+    currentHead: document?.currentSha ?? record.currentHead,
+    agent: { id: record.agentId, name: record.agentName },
+    currentDocument: document ? {
+      docId: document.docId,
+      path: document.path,
+      title: document.title,
+      currentSha: document.currentSha
+    } : void 0
+  };
+  const mismatches = bindingMismatches(expected, actual);
+  if (mismatches.length > 0) {
+    throw new CliError("wrong_binding", "This Magic binding is for a different document or scope.", {
+      hint: "Use the connector URL or CLI join command from the handoff copy.",
+      details: {
+        expected,
+        actual,
+        verification: { matches: false, mismatches }
+      }
+    });
+  }
+  return {
+    ok: true,
+    connected: true,
+    ...actual,
+    expected,
+    verification: { matches: true, mismatches: [] },
+    nextCommands: [
+      record.scope === "workspace" ? "mdocs remote map --json" : void 0,
+      record.scope === "project" ? "mdocs remote map --json" : void 0,
+      record.scope === "workspace" ? void 0 : "mdocs remote context --summary --json"
+    ].filter(Boolean)
+  };
+}
 async function remoteGraph(record) {
   assertProjectScope(record, "graph");
   const rootRecord = assertRootScoped(record, "graph");
@@ -13054,6 +13405,7 @@ async function remoteCreateFile(root, record, parsed) {
     path: normalizedPath,
     title,
     markdown,
+    reviewMarkdown: markdown,
     sidecar,
     anchors: [],
     images: [],
@@ -13108,13 +13460,24 @@ async function remoteSuggest(root, record, parsed) {
   const replacement = await readRequiredTextFlag(parsed.flags, root, ["with", "replacement"]);
   const message = await readOptionalTextFlag(parsed.flags, root, ["message"]) ?? "Suggested edit";
   const range = parseRange(requiredFlag(parsed.flags, "range"));
-  const result = await submitReview(
-    root,
-    record,
-    parsed.command[2] ?? record.docId,
-    (io, docId) => addSuggestion(io, docId, range, replacement, message, actorForRecord(record))
+  const pathOrDocId = parsed.command[2] ?? record.docId;
+  if (!pathOrDocId) {
+    throw new CliError("usage_error", "Missing document path or docId.", {
+      hint: "Pass a document path or docId, or join with --doc <docId>."
+    });
+  }
+  const document = await fetchDocument(record, pathOrDocId);
+  const documentRecord = rootScopedRecordFor(record, document.rootId);
+  await refreshPresence(documentRecord, document.docId);
+  const result = await postReviewOperation(
+    documentRecord,
+    document.docId,
+    { kind: "create_suggestion", baseHead: document.currentSha, payload: { ...range, replacement, message } },
+    actorForRecord(record)
   );
-  return { suggestion: result.created, document: result.document };
+  if (result.document) await recordHead(root, record, result.document);
+  const placementStatus = result.reviewRecord?.placement?.status;
+  return { suggestion: result.suggestion, reviewRecord: result.reviewRecord, placementStatus, projectionStatus: result.projectionStatus, document: result.document };
 }
 async function remoteCreateFolder(record, parsed) {
   assertProjectScope(record, "create-folder");
@@ -13204,44 +13567,14 @@ async function remoteReject(root, record, parsed) {
       hint: "Only open suggestions can be rejected."
     });
   }
-  try {
-    const additions = { anchors: [], comments: [], suggestions: [], withdrawSuggestionIds: [suggestionId] };
-    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 };
-  } catch (error) {
-    if (!isWithdrawalUnsupported(error)) throw error;
-  }
-  if (suggestion.author.id !== actor.id) {
-    throw new CliError("unauthorized", "You can only withdraw your own suggestions; rejecting another author's requires edit access.", {
-      hint: "Ask a human collaborator to reject it from the editor."
-    });
-  }
-  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(documentRecord, document, state.markdown, state.sidecar);
-      await recordHead(root, record, pushed);
-      return { suggestion: rejected, document: pushed };
-    } catch (error) {
-      const conflicted = isCliError(error) && error.code === "conflict";
-      if (!conflicted || index === PUSH_REBASE_ATTEMPTS - 1) throw error;
-    }
-  }
-  throw new CliError("conflict", "Remote change was not accepted after retries.", {
-    hint: "The document is changing rapidly. Refetch with mdocs remote context --summary --json, then retry against the needed content range."
-  });
-}
-function isWithdrawalUnsupported(error) {
-  if (isReviewEndpointUnsupported(error)) return true;
-  if (!isCliError(error)) return false;
-  const details = error.details ?? {};
-  return details.error === "empty_review";
+  const result = await postReviewOperation(
+    documentRecord,
+    document.docId,
+    { kind: "reject_suggestion", baseHead: document.currentSha, payload: { suggestionId } },
+    actor
+  );
+  if (result.document) await recordHead(root, record, result.document);
+  return { suggestion: result.suggestion ?? { ...suggestion, status: "rejected" }, reviewRecord: result.reviewRecord, document: result.document };
 }
 async function submitReview(root, record, pathOrDocId, mutate) {
   if (!pathOrDocId) {
@@ -13262,43 +13595,14 @@ async function submitReview(root, record, pathOrDocId, mutate) {
       additions: {
         anchors: state.sidecar.anchors.filter((anchor) => anchor.id === created.anchorId),
         comments: state.sidecar.comments.filter((comment2) => comment2.id === created.id),
-        suggestions: state.sidecar.suggestions.filter((suggestion) => suggestion.id === created.id)
+        reviewMarkdown: state.sidecar.reviewMarkdown
       }
     };
   };
-  let attempt = await build(document);
-  try {
-    const pushed = await postReview(documentRecord, document.docId, attempt.additions, actorForRecord(record));
-    await recordHead(root, record, pushed);
-    return { created: attempt.created, document: pushed };
-  } catch (error) {
-    if (!isReviewEndpointUnsupported(error)) throw error;
-  }
-  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(documentRecord, document, attempt.state.markdown, attempt.state.sidecar);
-      await recordHead(root, record, pushed);
-      return { created: attempt.created, document: pushed };
-    } catch (error) {
-      const conflicted = isCliError(error) && error.code === "conflict";
-      if (!conflicted || index === PUSH_REBASE_ATTEMPTS - 1) throw error;
-    }
-  }
-  throw new CliError("conflict", "Remote change was not accepted after retries.", {
-    hint: "The document is changing rapidly. Refetch with mdocs remote context --summary --json, then retry against the needed content range."
-  });
-}
-function isReviewEndpointUnsupported(error) {
-  if (!isCliError(error)) return false;
-  if (error.code === "unauthorized") return true;
-  if (error.code !== "not_found") return false;
-  const details = error.details ?? {};
-  return details.error !== "document_not_found";
+  const attempt = await build(document);
+  const pushed = await postReview(documentRecord, document.docId, attempt.additions, actorForRecord(record));
+  await recordHead(root, record, pushed);
+  return { created: attempt.created, document: pushed };
 }
 async function recordHead(root, record, document) {
   await writeJoinRecord(root, { ...record, updatedAt: (/* @__PURE__ */ new Date()).toISOString(), currentHead: document.currentSha });
@@ -13379,6 +13683,33 @@ function joinSummary(record, document) {
     ].filter(Boolean)
   };
 }
+function expectedBinding(flags) {
+  const scope = stringFlag(flags, "expect-scope", "expected-scope");
+  const rootId = stringFlag(flags, "expect-root", "expected-root");
+  const docId = stringFlag(flags, "expect-doc", "expected-doc");
+  const path = stringFlag(flags, "expect-path", "expected-path");
+  return {
+    ...scope ? { scope } : {},
+    ...rootId ? { rootId } : {},
+    ...docId ? { docId } : {},
+    ...path ? { path } : {}
+  };
+}
+function stringFlag(flags, primary, alias) {
+  const value = flags[primary] ?? flags[alias];
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function bindingMismatches(expected, actual) {
+  const checks = [
+    ["scope", expected.scope, actual.scope],
+    ["rootId", expected.rootId, actual.rootId],
+    ["docId", expected.docId, actual.docId],
+    ["path", expected.path, actual.path]
+  ];
+  return checks.flatMap(
+    ([field, expectedValue, actualValue]) => expectedValue && expectedValue !== actualValue ? [{ field, expected: expectedValue, actual: actualValue }] : []
+  );
+}
 function assertProjectScope(record, command) {
   if (record.scope === "project") return;
   throw new CliError("usage_error", `remote ${command} requires a project-scoped join.`, {
@@ -13446,6 +13777,8 @@ function optionalFolderTarget(value) {
 import { createHash as createHash2, randomUUID as randomUUID3 } from "node:crypto";
 import { basename as basename2, resolve as resolve4 } from "node:path";
 var BRIDGE_CONFIG_PATH = ".mdocs/bridge.json";
+var BRIDGE_STATUS_PATH = ".mdocs/bridge-status.json";
+var BRIDGE_HEARTBEAT_INTERVAL_MS = 1e4;
 function bridgeSetupIdentity(input) {
   const actorName = input.actorName?.trim() || "Agent";
   return {
@@ -13511,9 +13844,11 @@ async function runBridgeResume(options) {
 }
 async function runBridge(options) {
   const root = resolve4(options.root);
+  if (options.once && options.forever) {
+    throw new Error("Use either --once or --forever, not both.");
+  }
   const localManifestSource = await readLocalSource(root);
   const rootId = options.rootId ?? options.sourceId ?? localManifestSource?.sourceId ?? rootIdForPath(root);
-  const token = options.token ?? (options.requestToken ? await requestBridgeToken(options, rootId) : void 0);
   const replicaId = `replica_${createHash2("sha256").update(`${root}:${options.actorId}`).digest("hex").slice(0, 12)}`;
   const replicaKind = actorKindForBridge(options.actorId) === "agent" ? "agent_runtime" : "local";
   const mapping = createSourceMapping({
@@ -13536,7 +13871,29 @@ async function runBridge(options) {
   const claimMode = Boolean(options.claimToken || localManifestSource?.canonicalHead);
   let lastAppliedHead = localManifestSource?.canonicalHead;
   let socket;
-  const registeredRoot = token ? await fetchScopedRoot({ ...options, token }, rootId) : await registerRoot(options, root, rootId, mapping);
+  let lastSuccessfulSyncAt;
+  let lastHeartbeatAt;
+  let lastHeartbeatSentMs = 0;
+  let lastError;
+  await writeCurrentBridgeStatus("starting");
+  let token = options.token;
+  if (!token && options.requestToken) {
+    try {
+      token = await requestBridgeToken(options, rootId);
+    } catch (error) {
+      lastError = errorMessage(error);
+      await writeCurrentBridgeStatus("error");
+      throw error;
+    }
+  }
+  let registeredRoot;
+  try {
+    registeredRoot = token ? await fetchScopedRoot({ ...options, token }, rootId) : await registerRoot(options, root, rootId, mapping);
+  } catch (error) {
+    lastError = errorMessage(error);
+    await writeCurrentBridgeStatus("error");
+    throw error;
+  }
   lastAppliedHead = lastAppliedHead ?? registeredRoot?.canonical.head;
   await writeSourceState(lastAppliedHead);
   await writeBridgeConfig(root, {
@@ -13554,20 +13911,30 @@ async function runBridge(options) {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   });
   const backfilled = await resumeFromCanonical();
-  if (options.once) return;
+  if (options.once) {
+    lastSuccessfulSyncAt = (/* @__PURE__ */ new Date()).toISOString();
+    await writeCurrentBridgeStatus("once_complete");
+    return;
+  }
   connect();
   if (claimMode && !backfilled) await primeLocalSignatures();
   else await publishSnapshot("initial");
   const timer = setInterval(() => {
     void publishSnapshot("poll").catch((error) => {
-      process.stderr.write(`bridge poll failed: ${error instanceof Error ? error.message : String(error)}
+      lastError = errorMessage(error);
+      void writeCurrentBridgeStatus("error").catch(() => void 0);
+      sendHeartbeat("error", lastError);
+      process.stderr.write(`bridge poll failed: ${lastError}
 `);
     });
   }, options.intervalMs);
-  process.on("SIGINT", () => {
+  process.once("SIGINT", () => {
     clearInterval(timer);
-    socket?.close();
-    process.exit(0);
+    sendHeartbeat("offline", void 0, false);
+    void writeCurrentBridgeStatus("stopped").catch(() => void 0).finally(() => {
+      socket?.close();
+      process.exit(0);
+    });
   });
   await new Promise(() => void 0);
   function connect() {
@@ -13578,8 +13945,11 @@ async function runBridge(options) {
     if (token) url.searchParams.set("token", token);
     socket = new WebSocket(url);
     socket.addEventListener("open", () => {
+      lastError = void 0;
       process.stdout.write(`mdocs bridge connected ${root} -> ${options.workspaceId}/${rootId}
 `);
+      sendHeartbeat("synced");
+      void writeCurrentBridgeStatus("connected").catch(() => void 0);
     });
     socket.addEventListener("message", (event) => {
       if (typeof event.data !== "string") return;
@@ -13592,9 +13962,12 @@ async function runBridge(options) {
     });
     socket.addEventListener("close", () => {
       socket = void 0;
+      void writeCurrentBridgeStatus("offline").catch(() => void 0);
       setTimeout(connect, 1e3);
     });
     socket.addEventListener("error", () => {
+      lastError = "WebSocket error";
+      void writeCurrentBridgeStatus("error").catch(() => void 0);
       socket?.close();
     });
   }
@@ -13603,7 +13976,7 @@ async function runBridge(options) {
     const currentDocIds = new Set(map.docs.map((doc) => doc.docId));
     const treeSignature = hashJson(map.docs.map((doc) => ({ docId: doc.docId, path: doc.path })));
     if (treeSignature !== lastTreeSignature) {
-      if (send("file-tree", { reason, docs: map.docs, mapping, canonicalHead: lastAppliedHead })) {
+      if (send("file-tree", { reason, docs: map.docs, mapping: bridgeReplicaMetadata("synced"), canonicalHead: lastAppliedHead })) {
         lastTreeSignature = treeSignature;
       }
     }
@@ -13631,6 +14004,9 @@ async function runBridge(options) {
         pendingDeletes.add(docId);
       }
     }
+    lastError = void 0;
+    lastSuccessfulSyncAt = (/* @__PURE__ */ new Date()).toISOString();
+    maybeSendHeartbeat("synced");
   }
   async function resumeFromCanonical() {
     if (!options.resume && !token) return false;
@@ -13743,7 +14119,9 @@ async function runBridge(options) {
     }
     if (message.type === "sync-error") {
       const payload = message.payload;
-      process.stderr.write(`sync rejected${payload.code ? ` (${payload.code})` : ""}: ${payload.hint ?? "see workspace settings"}
+      lastError = `sync rejected${payload.code ? ` (${payload.code})` : ""}: ${payload.hint ?? "see workspace settings"}`;
+      void writeCurrentBridgeStatus("error").catch(() => void 0);
+      process.stderr.write(`${lastError}
 `);
       if (!payload.docId) return;
       pendingDocs.delete(payload.docId);
@@ -13782,6 +14160,12 @@ async function runBridge(options) {
     await io.writeTextAtomic(payload.path, payload.markdown);
     await io.writeTextAtomic(sidecarPath(payload.docId), `${JSON.stringify(payload.sidecar, null, 2)}
 `);
+    const reviewMarkdown = projectReviewMarkdown(payload.markdown, payload.sidecar.suggestions);
+    if (reviewMarkdown === payload.markdown) {
+      await io.deleteFile(reviewFilePath(payload.path)).catch(() => void 0);
+    } else {
+      await io.writeTextAtomic(reviewFilePath(payload.path), reviewMarkdown);
+    }
     await upsertManifestDocument(payload);
     signatures.set(payload.docId, remoteSignature);
     deniedSignatures.delete(payload.docId);
@@ -13862,6 +14246,63 @@ async function runBridge(options) {
     );
     return true;
   }
+  function maybeSendHeartbeat(status) {
+    if (Date.now() - lastHeartbeatSentMs < BRIDGE_HEARTBEAT_INTERVAL_MS) return;
+    sendHeartbeat(status);
+  }
+  function sendHeartbeat(status, error, writeLocalStatus = true) {
+    const heartbeatAt = (/* @__PURE__ */ new Date()).toISOString();
+    const sent = send("bridge-heartbeat", {
+      reason: "heartbeat",
+      canonicalHead: lastAppliedHead,
+      mapping: bridgeReplicaMetadata(status, error, heartbeatAt)
+    });
+    if (sent) {
+      lastHeartbeatAt = heartbeatAt;
+      lastHeartbeatSentMs = Date.now();
+      if (writeLocalStatus) {
+        void writeCurrentBridgeStatus(status === "error" ? "error" : status === "offline" ? "offline" : "connected").catch(() => void 0);
+      }
+    }
+    return sent;
+  }
+  function bridgeReplicaMetadata(status, error, now = (/* @__PURE__ */ new Date()).toISOString()) {
+    return {
+      ...mapping,
+      lastAppliedHead,
+      status,
+      updatedAt: now,
+      lastSeenAt: now,
+      bridgeVersion: CLI_VERSION,
+      pendingDocuments: pendingDocs.size,
+      pendingDeletes: pendingDeletes.size,
+      ...error ? { lastError: error } : {}
+    };
+  }
+  function currentBridgeStatus(state) {
+    return {
+      schemaVersion: 1,
+      workspaceId: options.workspaceId,
+      rootId,
+      actorId: options.actorId,
+      actorName: options.actorName,
+      sourceName: options.sourceName,
+      baseUrl: options.baseUrl,
+      state,
+      connected: state === "connected",
+      bridgeVersion: CLI_VERSION,
+      lastAppliedHead,
+      lastSuccessfulSyncAt,
+      lastHeartbeatAt,
+      lastError,
+      pendingDocuments: pendingDocs.size,
+      pendingDeletes: pendingDeletes.size,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  async function writeCurrentBridgeStatus(state) {
+    await writeBridgeStatus(root, currentBridgeStatus(state));
+  }
   async function primeLocalSignatures() {
     const map = await getWorkspaceMap(io);
     for (const doc of map.docs) {
@@ -13989,6 +14430,12 @@ async function writeBridgeConfig(root, config2) {
   await io.writeTextAtomic(BRIDGE_CONFIG_PATH, `${JSON.stringify(config2, null, 2)}
 `);
 }
+async function writeBridgeStatus(root, status) {
+  const io = new NodeWorkspaceIO(root);
+  await io.mkdir(".mdocs");
+  await io.writeTextAtomic(BRIDGE_STATUS_PATH, `${JSON.stringify(status, null, 2)}
+`);
+}
 async function fetchCanonicalSnapshot(options, rootId) {
   const response = await fetch(new URL(`/api/workspaces/${encodeURIComponent(options.workspaceId)}/roots/${encodeURIComponent(rootId)}/sync`, options.baseUrl), {
     headers: authHeaders(options.token)
@@ -14059,11 +14506,14 @@ function parseBridgeSyncMessage(data) {
   }
 }
 function delay(ms) {
-  return new Promise((resolve6) => setTimeout(resolve6, ms));
+  return new Promise((resolve7) => setTimeout(resolve7, ms));
 }
 function authHeaders(token) {
   return token ? { Authorization: `Bearer ${token}` } : {};
 }
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 async function fetchScopedRoot(options, rootId) {
   const response = await fetch(
     new URL(`/api/workspaces/${encodeURIComponent(options.workspaceId)}/roots/${encodeURIComponent(rootId)}`, options.baseUrl),
@@ -14167,6 +14617,9 @@ function conflictCopyPath(path) {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(/[:.]/g, "").slice(0, 15);
   return path.replace(/(\.[^./]+)?$/, (extension) => `.conflict-${stamp}${extension || ".md"}`);
 }
+function reviewFilePath(path) {
+  return path.replace(/(\.md)?$/i, ".review.md");
+}
 function hashJson(value) {
   return createHash2("sha256").update(JSON.stringify(value)).digest("hex");
 }
@@ -14198,10 +14651,246 @@ function readDocumentPayload(payload) {
   };
 }
 
+// src/bridge-startup.ts
+import { execFile as execFile2 } from "node:child_process";
+import { createHash as createHash3 } from "node:crypto";
+import { chmod, copyFile, mkdir as mkdir4, readFile as readFile6, stat as stat3, writeFile as writeFile4 } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { dirname as dirname5, join as join4, resolve as resolve5 } from "node:path";
+import { promisify as promisify2 } from "node:util";
+var execFileAsync2 = promisify2(execFile2);
+async function runBridgeStartup(options) {
+  const root = resolve5(options.root);
+  await assertBridgeConfigured(root);
+  const requestedMode = readBridgeStartupMode(options.mode);
+  const mode = requestedMode === "auto" ? await autoBridgeStartupMode() : requestedMode;
+  const startupDir = join4(root, ".mdocs", "startup");
+  await mkdir4(startupDir, { recursive: true });
+  const runnerPath = join4(startupDir, "bridge-runner.sh");
+  const runnerArgs = bridgeResumeArgs(root, options);
+  const runnerScript = bridgeRunnerScript(root, runnerArgs);
+  await writeFile4(runnerPath, runnerScript, "utf8");
+  await chmod(runnerPath, 493);
+  const nativePlan = mode === "launchd" ? await writeLaunchdPlan(root, startupDir, runnerPath) : mode === "systemd" ? await writeSystemdPlan(root, startupDir, runnerPath) : void 0;
+  if (options.install && !nativePlan) {
+    throw new CliError("usage_error", "Shell startup mode does not have a native service to install.", {
+      hint: "Use the printed startupCommand in your sandbox/provider startup hook, or pass --mode launchd/systemd on a supported host."
+    });
+  }
+  if (options.install && nativePlan) await nativePlan.install();
+  const result = {
+    ok: true,
+    root,
+    mode,
+    runnerPath,
+    startupCommand: shellCommand(["sh", runnerPath]),
+    servicePath: nativePlan?.servicePath,
+    installPath: nativePlan?.installPath,
+    installed: Boolean(options.install && nativePlan),
+    installCommands: nativePlan?.installCommands ?? [],
+    notes: [
+      "Sandbox providers such as Daytona, Sprites, and Modal should run startupCommand from their on-start hook.",
+      "The runner stores no bridge token. If you use manual tokens, provide MDOCS_BRIDGE_TOKEN through the platform secret environment.",
+      "If no MDOCS_BRIDGE_TOKEN is present, the runner uses --request-token and logs a Magic approval URL."
+    ]
+  };
+  await writeFile4(join4(startupDir, "bridge-startup.json"), `${JSON.stringify(result, null, 2)}
+`, "utf8");
+  return result;
+}
+function formatBridgeStartupResult(result) {
+  const lines = [
+    `Wrote Magic Markdown bridge runner: ${result.runnerPath}`,
+    `Startup command: ${result.startupCommand}`
+  ];
+  if (result.servicePath) lines.push(`Wrote ${result.mode} service file: ${result.servicePath}`);
+  if (result.installed && result.installPath) {
+    lines.push(`Installed ${result.mode} service: ${result.installPath}`);
+  } else if (result.installCommands.length > 0) {
+    lines.push("", "To install and start it manually:", ...result.installCommands.map((command) => `  ${command}`));
+  }
+  lines.push("", ...result.notes.map((note) => `Note: ${note}`));
+  return lines.join("\n");
+}
+function bridgeRunnerScript(root, args) {
+  return `#!/usr/bin/env sh
+set -eu
+cd ${shellQuote(root)}
+exec npx --yes --package=@magic-markdown/cli@latest mdocs ${shellCommand(args)} "$@"
+`;
+}
+function bridgeResumeArgs(root, options) {
+  const args = ["bridge", "resume", "--root", root, "--forever"];
+  if (options.requestToken !== false) args.push("--request-token");
+  if (options.baseUrl) args.push("--url", options.baseUrl);
+  if (options.intervalMs) args.push("--interval", String(options.intervalMs));
+  return args;
+}
+function readBridgeStartupMode(value) {
+  if (!value || value === "auto" || value === "shell" || value === "launchd" || value === "systemd") {
+    return value || "auto";
+  }
+  throw new CliError("usage_error", `Unknown bridge startup mode: ${value}`, {
+    hint: "Use --mode auto, shell, launchd, or systemd."
+  });
+}
+async function autoBridgeStartupMode() {
+  if (platform() === "darwin") return "launchd";
+  if (platform() === "linux" && await pathExists("/run/systemd/system")) return "systemd";
+  return "shell";
+}
+async function assertBridgeConfigured(root) {
+  const configPath = join4(root, ".mdocs", "bridge.json");
+  try {
+    const config2 = JSON.parse(await readFile6(configPath, "utf8"));
+    if (config2.schemaVersion !== 1) throw new Error("invalid schema");
+  } catch {
+    throw new CliError("usage_error", "This root does not have a bridge configuration yet.", {
+      hint: "Run mdocs bridge setup first, then run mdocs bridge startup from the same root."
+    });
+  }
+}
+async function writeLaunchdPlan(root, startupDir, runnerPath) {
+  const label = serviceLabel(root);
+  const servicePath = join4(startupDir, `${label}.plist`);
+  const installPath = join4(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+  const outLog = join4(root, ".mdocs", "bridge.log");
+  const errLog = join4(root, ".mdocs", "bridge.err.log");
+  await writeFile4(servicePath, launchdPlist(label, root, runnerPath, outLog, errLog), "utf8");
+  const target = `gui/$(id -u)`;
+  return {
+    servicePath,
+    installPath,
+    installCommands: [
+      shellCommand(["mkdir", "-p", dirname5(installPath)]),
+      shellCommand(["cp", servicePath, installPath]),
+      `launchctl bootout ${target} ${shellQuote(installPath)} 2>/dev/null || true`,
+      `launchctl bootstrap ${target} ${shellQuote(installPath)}`,
+      `launchctl enable ${target}/${label}`,
+      `launchctl kickstart -k ${target}/${label}`
+    ],
+    install: async () => {
+      await mkdir4(dirname5(installPath), { recursive: true });
+      await copyFile(servicePath, installPath);
+      const uid = typeof process.getuid === "function" ? process.getuid() : void 0;
+      if (uid === void 0) return;
+      const launchTarget = `gui/${uid}`;
+      await runOptionalCommand("launchctl", ["bootout", launchTarget, installPath]);
+      await runCommand("launchctl", ["bootstrap", launchTarget, installPath]);
+      await runCommand("launchctl", ["enable", `${launchTarget}/${label}`]);
+      await runCommand("launchctl", ["kickstart", "-k", `${launchTarget}/${label}`]);
+    }
+  };
+}
+async function writeSystemdPlan(root, startupDir, runnerPath) {
+  const unitName = `${serviceLabel(root)}.service`;
+  const servicePath = join4(startupDir, unitName);
+  const installPath = join4(homedir(), ".config", "systemd", "user", unitName);
+  await writeFile4(servicePath, systemdUnit(unitName, root, runnerPath), "utf8");
+  return {
+    servicePath,
+    installPath,
+    installCommands: [
+      shellCommand(["mkdir", "-p", dirname5(installPath)]),
+      shellCommand(["cp", servicePath, installPath]),
+      "systemctl --user daemon-reload",
+      shellCommand(["systemctl", "--user", "enable", "--now", unitName])
+    ],
+    install: async () => {
+      await mkdir4(dirname5(installPath), { recursive: true });
+      await copyFile(servicePath, installPath);
+      await runCommand("systemctl", ["--user", "daemon-reload"]);
+      await runCommand("systemctl", ["--user", "enable", "--now", unitName]);
+    }
+  };
+}
+function launchdPlist(label, root, runnerPath, outLog, errLog) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/sh</string>
+    <string>${escapeXml(runnerPath)}</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(root)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(outLog)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(errLog)}</string>
+</dict>
+</plist>
+`;
+}
+function systemdUnit(unitName, root, runnerPath) {
+  return `[Unit]
+Description=Magic Markdown bridge (${unitName})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${systemdQuote(root)}
+ExecStart=/bin/sh ${systemdQuote(runnerPath)}
+Restart=always
+RestartSec=5
+Environment=PATH=${systemdQuote(process.env.PATH || "/usr/local/bin:/usr/bin:/bin")}
+
+[Install]
+WantedBy=default.target
+`;
+}
+function serviceLabel(root) {
+  const digest = createHash3("sha256").update(root).digest("hex").slice(0, 12);
+  return `com.magic-markdown.bridge.${digest}`;
+}
+async function runOptionalCommand(command, args) {
+  try {
+    await execFileAsync2(command, args);
+  } catch {
+  }
+}
+async function runCommand(command, args) {
+  try {
+    await execFileAsync2(command, args);
+  } catch (error) {
+    const detail = error;
+    throw new CliError("internal_error", `${command} ${args.join(" ")} failed: ${detail.stderr || detail.message || String(error)}`);
+  }
+}
+async function pathExists(path) {
+  try {
+    await stat3(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function shellCommand(args) {
+  return args.map(shellQuote).join(" ");
+}
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function systemdQuote(value) {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%")}"`;
+}
+function escapeXml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+
 // src/index.ts
 async function main() {
   const parsed = parseArgs(process.argv.slice(2));
-  const cwd = resolve5(String(parsed.flags.cwd ?? process.cwd()));
+  const cwd = resolve6(String(parsed.flags.cwd ?? process.cwd()));
   const io = new NodeWorkspaceIO(cwd);
   const [command, subcommand] = parsed.command;
   if (parsed.flags.version || command === "version") {
@@ -14216,7 +14905,7 @@ async function main() {
   }
   switch (command) {
     case "init": {
-      const target = resolve5(parsed.command[1] ?? cwd);
+      const target = resolve6(parsed.command[1] ?? cwd);
       const targetIo = new NodeWorkspaceIO(target);
       const manifest = await indexWorkspace(targetIo);
       print(manifest, parsed.flags);
@@ -14253,7 +14942,7 @@ async function main() {
         markdown,
         images: state.images.map((image2) => ({
           ...image2,
-          ...image2.workspacePath ? { absolutePath: resolve5(cwd, image2.workspacePath) } : {}
+          ...image2.workspacePath ? { absolutePath: resolve6(cwd, image2.workspacePath) } : {}
         })),
         links: state.links,
         ...parsed.flags["no-review"] ? {} : {
@@ -14357,7 +15046,7 @@ async function main() {
       return;
     }
     case "bridge": {
-      const root = resolve5(String(parsed.flags.root ?? cwd));
+      const root = resolve6(String(parsed.flags.root ?? cwd));
       const baseOptions = {
         root,
         rootId: typeof parsed.flags["root-id"] === "string" ? parsed.flags["root-id"] : void 0,
@@ -14373,8 +15062,21 @@ async function main() {
         token: typeof parsed.flags.token === "string" ? parsed.flags.token : process.env.MDOCS_BRIDGE_TOKEN || void 0,
         requestToken: Boolean(parsed.flags["request-token"] || parsed.flags.pair),
         pairingTimeoutMs: typeof parsed.flags["pairing-timeout-ms"] === "string" ? Number(parsed.flags["pairing-timeout-ms"]) : void 0,
-        once: Boolean(parsed.flags.once)
+        once: Boolean(parsed.flags.once),
+        forever: Boolean(parsed.flags.forever)
       };
+      if (subcommand === "startup" || subcommand === "daemon") {
+        const result = await runBridgeStartup({
+          root,
+          mode: typeof parsed.flags.mode === "string" ? parsed.flags.mode : void 0,
+          install: Boolean(parsed.flags.install),
+          requestToken: !parsed.flags["no-request-token"],
+          baseUrl: optionalBridgeBaseUrl(parsed.flags),
+          intervalMs: typeof parsed.flags.interval === "string" ? Number(parsed.flags.interval) : void 0
+        });
+        print(parsed.flags.json ? result : formatBridgeStartupResult(result), parsed.flags);
+        return;
+      }
       if (subcommand === "resume") {
         await runBridgeResume({
           ...baseOptions,
@@ -14513,7 +15215,7 @@ async function readRequiredTextFlag2(flags, cwd, names) {
 async function readOptionalTextFlag2(flags, cwd, names) {
   for (const name of names) {
     const fileValue = flags[`${name}-file`];
-    if (typeof fileValue === "string") return readFile6(resolve5(cwd, fileValue), "utf8");
+    if (typeof fileValue === "string") return readFile7(resolve6(cwd, fileValue), "utf8");
     const value = flags[name];
     if (typeof value === "string") return value;
   }
@@ -14561,9 +15263,9 @@ Commands:
   comments <path> --json              List comments
   comment <path> --range 3:5 --body   Add a sidecar comment
   suggestions <path> --json           List suggestions
-  suggest <path> --range 3:5 --with   Add a sidecar suggestion
+  suggest <path> --range 3:5 --with   Add a reviewMarkdown suggestion
   suggest <path> --range 3:5 --with-file replacement.md
-                                      Add a multiline sidecar suggestion
+                                      Add a multiline reviewMarkdown suggestion
   accept <suggestionId>               Apply and accept a suggestion
   reject <suggestionId>               Reject a suggestion
   resolve-comment <commentId>         Resolve a comment thread
@@ -14575,6 +15277,7 @@ 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 status --json                Verify the active remote join binding
   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
@@ -14585,9 +15288,12 @@ Commands:
   bridge setup --workspace <id> --root . --url <base-url> [--folder-id <id>] --request-token
                                       Initialize, validate, request approval,
                                       and start an agent filesystem bridge
-  bridge resume --root . --request-token [--once]
+  bridge resume --root . --forever --request-token [--once]
                                       Backfill missed Magic changes, then keep
                                       the bridge running unless --once is set
+  bridge startup|daemon --root . [--mode auto|shell|launchd|systemd] [--install]
+                                      Write a bridge runner and startup hook
+                                      for sandboxes, launchd, or systemd
   bridge --workspace <id> --root . --url <base-url> --request-token
                                       Request human approval, then sync an
                                       approved local root with the workspace
@@ -14607,7 +15313,8 @@ Exit codes: 0 ok, 1 internal, 2 usage, 3 conflict, 4 not found, 5 network, 6 una
 `);
 }
 function commandHelp(commandPath) {
-  const candidates = [commandPath.slice(0, 2).join(" "), commandPath[0] ?? ""].filter(Boolean);
+  const normalizedPath = commandPath[0] === "bridge" && commandPath[1] === "daemon" ? ["bridge", "startup"] : commandPath;
+  const candidates = [normalizedPath.slice(0, 2).join(" "), normalizedPath[0] ?? ""].filter(Boolean);
   const spec = AGENT_COMMANDS.find((command) => candidates.includes(command.name));
   if (!spec) return false;
   const lines = [
@@ -14628,7 +15335,8 @@ function commandHelp(commandPath) {
   return true;
 }
 function usageFor(commandPath) {
-  const candidates = [commandPath.slice(0, 2).join(" "), commandPath[0] ?? ""].filter(Boolean);
+  const normalizedPath = commandPath[0] === "bridge" && commandPath[1] === "daemon" ? ["bridge", "startup"] : commandPath;
+  const candidates = [normalizedPath.slice(0, 2).join(" "), normalizedPath[0] ?? ""].filter(Boolean);
   return AGENT_COMMANDS.find((command) => candidates.includes(command.name))?.usage;
 }
 main().catch((error) => {
@@ -14643,7 +15351,8 @@ main().catch((error) => {
         code: cliError.code,
         message: cliError.message,
         ...hint ? { hint } : {},
-        ...usage && cliError.hint ? { usage } : {}
+        ...usage && cliError.hint ? { usage } : {},
+        ...cliError.details !== void 0 ? { details: cliError.details } : {}
       },
       cliVersion: CLI_VERSION
     };