@magic-markdown/cli 0.3.11 → 0.3.13

package/dist/index.js

@@ -918,7 +918,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,30 +940,44 @@ 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;
@@ -1163,6 +1178,9 @@ function regionTouchesSuggestionRange(region, baseStart, baseEnd) {
   return region.baseStart < baseEnd && regionEnd > baseStart;
 }
 function currentSuggestionRange(markdown, suggestion, anchor) {
+  const anchoredRange = currentAnchorRange(markdown, suggestion, anchor);
+  if (anchoredRange) return anchoredRange;
+  if (anchor && !anchorIsReliable(anchor)) return void 0;
   const hintedRange = suggestion.patch.range;
   if (rangeIsWithin(markdown, hintedRange) && extractLineRange(markdown, hintedRange) === suggestion.patch.before) return hintedRange;
   const candidates = findBeforeCandidates(markdown, suggestion.patch.before);
@@ -1177,6 +1195,14 @@ function currentSuggestionRange(markdown, suggestion, anchor) {
   if (best.score < 0.7) return void 0;
   return best.range;
 }
+function currentAnchorRange(markdown, suggestion, anchor) {
+  if (!anchor || !anchorIsReliable(anchor) || !anchor.range) return void 0;
+  if (!rangeIsWithin(markdown, anchor.range)) return void 0;
+  return extractLineRange(markdown, anchor.range) === suggestion.patch.before ? anchor.range : void 0;
+}
+function anchorIsReliable(anchor) {
+  return anchor.status === "mapped" && anchor.confidence >= 0.65;
+}
 function findBeforeCandidates(markdown, before) {
   const lines = getLines(markdown);
   const beforeLines = linePattern(before);
@@ -1200,22 +1226,22 @@ function linePattern(value) {
 function scoreContext2(markdown, range, anchor) {
   const lines = getLines(markdown);
   let score = anchor.selector.quote === extractLineRange(markdown, range) ? 0.7 : 0.65;
-  const expectedPrefix = contextPrefix(anchor.selector.prefix);
+  const expectedPrefix = contextPrefix2(anchor.selector.prefix);
   if (expectedPrefix) {
-    const actualPrefix = contextPrefix(lines.slice(Math.max(0, range.startLine - 4), range.startLine - 1).join("\n"));
+    const actualPrefix = contextPrefix2(lines.slice(Math.max(0, range.startLine - 4), range.startLine - 1).join("\n"));
     if (actualPrefix?.endsWith(expectedPrefix)) score += 0.15;
   }
-  const expectedSuffix = contextSuffix(anchor.selector.suffix);
+  const expectedSuffix = contextSuffix2(anchor.selector.suffix);
   if (expectedSuffix) {
-    const actualSuffix = contextSuffix(lines.slice(range.endLine, range.endLine + 3).join("\n"));
+    const actualSuffix = contextSuffix2(lines.slice(range.endLine, range.endLine + 3).join("\n"));
     if (actualSuffix?.startsWith(expectedSuffix)) score += 0.15;
   }
   return Math.min(1, score);
 }
-function contextPrefix(value) {
+function contextPrefix2(value) {
   return value?.split(/\r?\n/).filter(Boolean).slice(-3).join("\n") || void 0;
 }
-function contextSuffix(value) {
+function contextSuffix2(value) {
   return value?.split(/\r?\n/).filter(Boolean).slice(0, 3).join("\n") || void 0;
 }
 
@@ -4606,44 +4632,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 +4680,7 @@ var canonicalSchema = new Schema({
     tableCell: {
       content: "block+",
       attrs: {
+        ...blockAttrs,
         colspan: { default: 1 },
         rowspan: { default: 1 },
         colwidth: { default: null }
@@ -10950,6 +10979,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 +11056,7 @@ var RemoteDocumentIO = class {
 };
 
 // src/agent.ts
-var CLI_VERSION = "0.3.11";
+var CLI_VERSION = "0.3.13";
 var CLI_PACKAGE_NAME = "@magic-markdown/cli";
 var AGENT_COMMANDS = [
   {
@@ -11058,10 +11117,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 +11141,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.",
@@ -11279,6 +11340,23 @@ var AGENT_COMMANDS = [
       "--token (or MDOCS_BRIDGE_TOKEN) still works when a scoped bridge token is already available."
     ]
   },
+  {
+    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]",
+    output: "long-running",
+    mutates: true,
+    examples: [
+      "mdocs bridge resume --root . --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.",
+      "--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",
     summary: "Sync a local Markdown root with a Magic workspace over WebSocket (long-running).",
@@ -11341,11 +11419,38 @@ 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 insert comments, CriticMarkup, directives, or Magic markers into Markdown files.
+
+## Filesystem Bridge / Resume
+
+When a human asks you to bind an editable local Markdown filesystem to Magic Markdown, use the latest official package and the human-approval token flow:
+
+\`\`\`bash
+npx --yes --package=@magic-markdown/cli@latest mdocs bridge setup \\
+  --root . \\
+  --workspace <workspace-id> \\
+  --root-id <root-id> \\
+  --url <magic-url> \\
+  --actor-name "<agent name>" \\
+  --request-token
+\`\`\`
+
+Return the Magic approval link and keep the bridge process running after approval. Success looks like \`mdocs bridge connected ...\`.
+
+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
+\`\`\`
+
+\`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.
+
+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
 
@@ -11364,7 +11469,7 @@ Run \`mdocs help <command>\` (or \`mdocs <command> --help\`) for usage, examples
 ## 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.
@@ -11388,7 +11493,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() {
@@ -11416,6 +11521,7 @@ var CLI_EXIT_CODES = {
   invalid_range: 2,
   conflict: 3,
   not_found: 4,
+  wrong_binding: 4,
   network_error: 5,
   unauthorized: 6
 };
@@ -12468,6 +12574,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 = {
@@ -12765,6 +12881,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") {
@@ -12818,10 +12936,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");
@@ -13065,13 +13226,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", 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");
@@ -13336,6 +13508,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.`, {
@@ -13402,6 +13601,7 @@ function optionalFolderTarget(value) {
 // src/bridge.ts
 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";
 function bridgeSetupIdentity(input) {
   const actorName = input.actorName?.trim() || "Agent";
   return {
@@ -13426,7 +13626,43 @@ async function runBridgeSetup(options) {
     actorId: identity.actorId,
     actorName: identity.actorName,
     sourceName: identity.sourceName,
-    requestToken: options.requestToken || !options.token
+    requestToken: options.requestToken || !options.token,
+    resume: true
+  });
+}
+async function runBridgeResume(options) {
+  const root = resolve4(options.root);
+  const config2 = await readBridgeConfig(root);
+  const identity = bridgeSetupIdentity({
+    actorId: options.actorId ?? config2?.actorId,
+    actorName: options.actorName ?? config2?.actorName,
+    sourceName: options.sourceName ?? config2?.sourceName
+  });
+  const workspaceId = options.workspaceId ?? config2?.workspaceId;
+  const rootId = options.rootId ?? options.sourceId ?? config2?.rootId;
+  const baseUrl = options.baseUrl ?? config2?.baseUrl;
+  if (!workspaceId || !rootId || !baseUrl) {
+    throw new Error("Missing bridge resume configuration. Run mdocs bridge setup --workspace <id> --root <path> --root-id <id> --url <base-url> first.");
+  }
+  await runBridge({
+    root,
+    workspaceId,
+    rootId,
+    sourceId: options.sourceId,
+    sourceName: identity.sourceName,
+    folderId: options.folderId ?? config2?.folderId,
+    canonicalPrefix: options.canonicalPrefix ?? config2?.canonicalPrefix,
+    replicaPrefix: options.replicaPrefix ?? config2?.replicaPrefix,
+    claimToken: options.claimToken,
+    actorId: identity.actorId,
+    actorName: identity.actorName,
+    baseUrl,
+    intervalMs: options.intervalMs ?? config2?.intervalMs ?? 1e3,
+    token: options.token,
+    requestToken: options.requestToken || !options.token,
+    pairingTimeoutMs: options.pairingTimeoutMs,
+    once: options.once,
+    resume: true
   });
 }
 async function runBridge(options) {
@@ -13459,8 +13695,24 @@ async function runBridge(options) {
   const registeredRoot = token ? await fetchScopedRoot({ ...options, token }, rootId) : await registerRoot(options, root, rootId, mapping);
   lastAppliedHead = lastAppliedHead ?? registeredRoot?.canonical.head;
   await writeSourceState(lastAppliedHead);
+  await writeBridgeConfig(root, {
+    schemaVersion: 1,
+    workspaceId: options.workspaceId,
+    rootId,
+    baseUrl: options.baseUrl,
+    actorId: options.actorId,
+    actorName: options.actorName,
+    sourceName: options.sourceName,
+    folderId: options.folderId,
+    canonicalPrefix: options.canonicalPrefix,
+    replicaPrefix: options.replicaPrefix,
+    intervalMs: options.intervalMs,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const backfilled = await resumeFromCanonical();
+  if (options.once) return;
   connect();
-  if (claimMode) await primeLocalSignatures();
+  if (claimMode && !backfilled) await primeLocalSignatures();
   else await publishSnapshot("initial");
   const timer = setInterval(() => {
     void publishSnapshot("poll").catch((error) => {
@@ -13536,6 +13788,87 @@ async function runBridge(options) {
       }
     }
   }
+  async function resumeFromCanonical() {
+    if (!options.resume && !token) return false;
+    const remote = await fetchCanonicalSnapshot({ ...options, token }, rootId).catch(() => void 0);
+    if (!remote) return false;
+    const baseDocs = lastAppliedHead ? await fetchCommitDocuments({ ...options, token }, rootId, lastAppliedHead).catch(() => /* @__PURE__ */ new Map()) : /* @__PURE__ */ new Map();
+    const remoteDocIds = new Set(remote.docs.map((doc) => doc.docId));
+    let applied = 0;
+    let keptLocal = 0;
+    let conflicted = 0;
+    for (const doc of remote.docs) {
+      const base = baseDocs.get(doc.docId);
+      const decision = await reconcileRemoteDocument(doc, base);
+      if (decision === "applied") applied += 1;
+      if (decision === "kept_local") keptLocal += 1;
+      if (decision === "conflict") conflicted += 1;
+    }
+    for (const [docId, base] of baseDocs) {
+      if (remoteDocIds.has(docId)) continue;
+      const decision = await reconcileRemoteDelete(docId, base);
+      if (decision === "applied") applied += 1;
+      if (decision === "conflict") conflicted += 1;
+    }
+    lastAppliedHead = remote.head ?? lastAppliedHead;
+    await writeSourceState(lastAppliedHead);
+    process.stdout.write(
+      `mdocs bridge resume ${root}: applied ${applied}, kept local ${keptLocal}, conflicts ${conflicted}, head ${lastAppliedHead ?? "unknown"}
+`
+    );
+    return true;
+  }
+  async function reconcileRemoteDocument(remote, base) {
+    const remoteSignature = documentSignature(remote.markdown, remote.sidecar);
+    const baseSignature = base ? documentSignature(base.markdown, base.sidecar) : void 0;
+    const localState = await localStateForCanonical(remote);
+    const localSignature = localState ? documentSignature(localState.markdown, localState.sidecar) : void 0;
+    if (!localState) {
+      await applyCanonicalDocument(remote);
+      return "applied";
+    }
+    if (localSignature === remoteSignature && localState.path === remote.path && localState.docId === remote.docId) {
+      signatures.set(remote.docId, remoteSignature);
+      seenDocs.add(remote.docId);
+      return "noop";
+    }
+    if (localSignature === remoteSignature && localState.path === remote.path) {
+      await applyCanonicalDocument(remote);
+      return "applied";
+    }
+    if (baseSignature && localSignature === baseSignature) {
+      await applyCanonicalDocument(remote);
+      return "applied";
+    }
+    if (baseSignature && remoteSignature === baseSignature) {
+      signatures.set(remote.docId, baseSignature);
+      seenDocs.add(remote.docId);
+      return "kept_local";
+    }
+    signatures.set(remote.docId, baseSignature ?? remoteSignature);
+    await applyCanonicalDocument(remote);
+    return "conflict";
+  }
+  async function reconcileRemoteDelete(docId, base) {
+    const localState = await getDocumentState(io, docId).catch(() => void 0);
+    if (!localState) return "noop";
+    const baseSignature = documentSignature(base.markdown, base.sidecar);
+    const localSignature = documentSignature(localState.markdown, localState.sidecar);
+    if (localSignature !== baseSignature) {
+      const copyPath = conflictCopyPath(localState.path);
+      await io.writeTextAtomic(copyPath, localState.markdown);
+      await seedConflictCopySidecar(copyPath, localState);
+      process.stderr.write(`local conflict ${localState.path}; local version saved as ${copyPath}, canonical delete applied
+`);
+    }
+    await io.deleteFile(localState.path).catch(() => void 0);
+    await io.deleteFile(sidecarPath(docId)).catch(() => void 0);
+    await removeManifestDocument(docId, localState.path);
+    signatures.delete(docId);
+    seenDocs.delete(docId);
+    pendingDeletes.delete(docId);
+    return localSignature === baseSignature ? "applied" : "conflict";
+  }
   async function handleIncoming(message) {
     if (message.type === "file-changed") {
       await applyCanonicalDocument(readDocumentPayload(message.payload));
@@ -13561,7 +13894,7 @@ async function runBridge(options) {
 `);
       if (!payload.docId) return;
       pendingDocs.delete(payload.docId);
-      const canonical = await fetchCanonicalDocument(payload.docId);
+      const canonical = await fetchCanonicalDocument2(payload.docId);
       if (canonical) await applyCanonicalDocument(canonical);
     }
     if (message.type === "sync-error") {
@@ -13576,7 +13909,7 @@ async function runBridge(options) {
   }
   async function applyCanonicalDocument(payload) {
     const remoteSignature = documentSignature(payload.markdown, payload.sidecar);
-    const localState = await getDocumentState(io, payload.docId).catch(() => void 0);
+    const localState = await localStateForCanonical(payload);
     const localSignature = localState ? documentSignature(localState.markdown, localState.sidecar) : void 0;
     if (localSignature && signatures.has(payload.docId) && localSignature !== signatures.get(payload.docId) && localSignature !== remoteSignature) {
       const copyPath = conflictCopyPath(payload.path);
@@ -13598,9 +13931,14 @@ async function runBridge(options) {
     if (localState && localState.path !== payload.path) {
       await io.deleteFile(localState.path).catch(() => void 0);
     }
+    if (localState && localState.docId !== payload.docId) {
+      await io.deleteFile(sidecarPath(localState.docId)).catch(() => void 0);
+      await removeManifestDocument(localState.docId, localState.path);
+    }
     await io.writeTextAtomic(payload.path, payload.markdown);
     await io.writeTextAtomic(sidecarPath(payload.docId), `${JSON.stringify(payload.sidecar, null, 2)}
 `);
+    await upsertManifestDocument(payload);
     signatures.set(payload.docId, remoteSignature);
     deniedSignatures.delete(payload.docId);
     seenDocs.add(payload.docId);
@@ -13636,7 +13974,14 @@ async function runBridge(options) {
       updatedAt: now
     });
   }
-  async function fetchCanonicalDocument(docId) {
+  async function localStateForCanonical(payload) {
+    const byDocId = await getDocumentState(io, payload.docId).catch(() => void 0);
+    if (byDocId) return byDocId;
+    const map = await getWorkspaceMap(io).catch(() => void 0);
+    const byPath = map?.docs.find((doc) => doc.path === payload.path);
+    return byPath ? getDocumentState(io, byPath.docId).catch(() => void 0) : void 0;
+  }
+  async function fetchCanonicalDocument2(docId) {
     try {
       const response = await fetch(
         new URL(
@@ -13701,6 +14046,34 @@ async function runBridge(options) {
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
   }
+  async function upsertManifestDocument(payload) {
+    const manifest = await readManifest(io).catch(() => void 0);
+    if (!manifest) return;
+    await writeManifest(io, {
+      ...manifest,
+      docs: [
+        ...manifest.docs.filter((doc) => doc.docId !== payload.docId && doc.path !== payload.path),
+        {
+          docId: payload.docId,
+          path: payload.path,
+          title: payload.sidecar.title || titleFromMarkdown(payload.path, payload.markdown),
+          contentHash: contentHashForText(payload.markdown),
+          currentSha: payload.canonicalHead ?? payload.currentSha,
+          updatedAt: payload.sidecar.updatedAt
+        }
+      ].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0),
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  async function removeManifestDocument(docId, path) {
+    const manifest = await readManifest(io).catch(() => void 0);
+    if (!manifest) return;
+    await writeManifest(io, {
+      ...manifest,
+      docs: manifest.docs.filter((doc) => doc.docId !== docId && doc.path !== path),
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
 }
 async function requestBridgeToken(options, rootId) {
   const response = await fetch(new URL("/api/bridge-requests", options.baseUrl), {
@@ -13754,6 +14127,83 @@ async function requestBridgeToken(options, rootId) {
   }
   throw new Error("Bridge approval timed out before a token was issued.");
 }
+async function readBridgeConfig(root) {
+  const io = new NodeWorkspaceIO(root);
+  try {
+    const config2 = JSON.parse(await io.readText(BRIDGE_CONFIG_PATH));
+    if (config2.schemaVersion !== 1 || typeof config2.workspaceId !== "string" || typeof config2.rootId !== "string" || typeof config2.baseUrl !== "string" || typeof config2.actorId !== "string") {
+      return void 0;
+    }
+    return config2;
+  } catch {
+    return void 0;
+  }
+}
+async function writeBridgeConfig(root, config2) {
+  const io = new NodeWorkspaceIO(root);
+  await io.mkdir(".mdocs");
+  await io.writeTextAtomic(BRIDGE_CONFIG_PATH, `${JSON.stringify(config2, 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)
+  });
+  if (!response.ok) return void 0;
+  const snapshot = await response.json();
+  const docs = await Promise.all(
+    (snapshot.tree?.docs ?? []).map((doc) => typeof doc.docId === "string" ? doc.docId : void 0).filter((docId) => Boolean(docId)).map((docId) => fetchCanonicalDocument(options, rootId, docId))
+  );
+  return {
+    head: snapshot.tree?.root?.canonical.head,
+    docs: docs.filter((doc) => Boolean(doc))
+  };
+}
+async function fetchCommitDocuments(options, rootId, headId) {
+  const response = await fetch(
+    new URL(
+      `/api/workspaces/${encodeURIComponent(options.workspaceId)}/roots/${encodeURIComponent(rootId)}/commits/${encodeURIComponent(headId)}?content=1`,
+      options.baseUrl
+    ),
+    { headers: authHeaders(options.token) }
+  );
+  if (!response.ok) return /* @__PURE__ */ new Map();
+  const payload = await response.json();
+  const docs = (payload.docs ?? []).map((doc) => readCommitDocumentPayload(doc, options.workspaceId, rootId, headId)).filter((doc) => Boolean(doc));
+  return new Map(docs.map((doc) => [doc.docId, doc]));
+}
+async function fetchCanonicalDocument(options, rootId, docId) {
+  try {
+    const response = await fetch(
+      new URL(
+        `/api/workspaces/${encodeURIComponent(options.workspaceId)}/roots/${encodeURIComponent(rootId)}/documents/${encodeURIComponent(docId)}`,
+        options.baseUrl
+      ),
+      { headers: authHeaders(options.token) }
+    );
+    if (!response.ok) return void 0;
+    const document = await response.json();
+    return readDocumentPayload({ ...document, canonicalHead: document.currentSha });
+  } catch {
+    return void 0;
+  }
+}
+function readCommitDocumentPayload(payload, workspaceId, rootId, headId) {
+  if (!payload || typeof payload !== "object") return void 0;
+  const value = payload;
+  if (typeof value.markdown !== "string" || !value.sidecar || typeof value.sidecar !== "object") return void 0;
+  return readDocumentPayload({
+    workspaceId,
+    rootId,
+    docId: value.docId,
+    path: value.path,
+    title: value.title,
+    markdown: value.markdown,
+    sidecar: value.sidecar,
+    currentSha: headId,
+    canonicalHead: headId
+  });
+}
 function parseBridgeSyncMessage(data) {
   if (!data.trim()) return void 0;
   try {
@@ -14063,9 +14513,9 @@ async function main() {
       return;
     }
     case "bridge": {
-      const options = {
-        root: resolve5(String(parsed.flags.root ?? cwd)),
-        workspaceId: String(parsed.flags.workspace ?? "workspace_demo"),
+      const root = resolve5(String(parsed.flags.root ?? cwd));
+      const baseOptions = {
+        root,
         rootId: typeof parsed.flags["root-id"] === "string" ? parsed.flags["root-id"] : void 0,
         sourceId: typeof parsed.flags.source === "string" ? parsed.flags.source : void 0,
         sourceName: typeof parsed.flags["source-name"] === "string" ? parsed.flags["source-name"] : void 0,
@@ -14075,11 +14525,24 @@ async function main() {
         claimToken: typeof parsed.flags.claim === "string" ? parsed.flags.claim : void 0,
         actorId: typeof parsed.flags.actor === "string" ? parsed.flags.actor : void 0,
         actorName: typeof parsed.flags["actor-name"] === "string" ? parsed.flags["actor-name"] : void 0,
-        baseUrl: bridgeBaseUrl(parsed.flags),
         intervalMs: Number(parsed.flags.interval ?? 1e3),
         token: typeof parsed.flags.token === "string" ? parsed.flags.token : process.env.MDOCS_BRIDGE_TOKEN || void 0,
         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
+        pairingTimeoutMs: typeof parsed.flags["pairing-timeout-ms"] === "string" ? Number(parsed.flags["pairing-timeout-ms"]) : void 0,
+        once: Boolean(parsed.flags.once)
+      };
+      if (subcommand === "resume") {
+        await runBridgeResume({
+          ...baseOptions,
+          workspaceId: typeof parsed.flags.workspace === "string" ? parsed.flags.workspace : void 0,
+          baseUrl: optionalBridgeBaseUrl(parsed.flags)
+        });
+        return;
+      }
+      const options = {
+        ...baseOptions,
+        workspaceId: typeof parsed.flags.workspace === "string" ? parsed.flags.workspace : "workspace_demo",
+        baseUrl: bridgeBaseUrl(parsed.flags)
       };
       if (subcommand === "setup") await runBridgeSetup(options);
       else await runBridge({ ...options, actorId: options.actorId ?? "actor_local" });
@@ -14183,13 +14646,17 @@ function requiredFlag2(flags, name) {
   return value;
 }
 function bridgeBaseUrl(flags) {
-  if (typeof flags.url === "string" && flags.url.trim()) return flags.url.trim();
-  const configured = process.env.MDOCS_BASE_URL?.trim();
+  const configured = optionalBridgeBaseUrl(flags);
   if (configured) return configured;
   throw new CliError("usage_error", "Missing --url <base-url> for mdocs bridge.", {
     hint: "Pass the Magic Markdown origin explicitly (for example --url https://magic.example.com) or set MDOCS_BASE_URL. The bridge does not assume a localhost server."
   });
 }
+function optionalBridgeBaseUrl(flags) {
+  if (typeof flags.url === "string" && flags.url.trim()) return flags.url.trim();
+  const configured = process.env.MDOCS_BASE_URL?.trim();
+  return configured || void 0;
+}
 async function readRequiredTextFlag2(flags, cwd, names) {
   const value = await readOptionalTextFlag2(flags, cwd, names);
   if (value === void 0) {
@@ -14264,6 +14731,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
@@ -14274,6 +14742,9 @@ 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]
+                                      Backfill missed Magic changes, then keep
+                                      the bridge running unless --once is set
   bridge --workspace <id> --root . --url <base-url> --request-token
                                       Request human approval, then sync an
                                       approved local root with the workspace
@@ -14329,7 +14800,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
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magic-markdown/cli",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "description": "Magic Markdown agent CLI (mdocs): read, review, comment on, suggest edits to, and sync clean Markdown workspaces.",
   "type": "module",
   "license": "MIT",