@magic-markdown/cli 0.3.0 → 0.3.2

package/dist/index.js

@@ -321,6 +321,17 @@ function fnv1a(value) {
   return hash;
 }
 
+// ../core/src/wikilinks.ts
+function parseWikilinkBody(value) {
+  const separatorIndex = value.indexOf("|");
+  const rawTarget = separatorIndex >= 0 ? value.slice(0, separatorIndex) : value;
+  const rawLabel = separatorIndex >= 0 ? value.slice(separatorIndex + 1) : void 0;
+  const target = rawTarget.trim();
+  if (!target) return void 0;
+  const label = rawLabel?.trim();
+  return label ? { target, label } : { target };
+}
+
 // ../core/src/markdown.ts
 var POLLUTING_PATTERNS = [
   { name: "CriticMarkup addition", pattern: /\{\+\+[\s\S]*?\+\+\}/ },
@@ -469,6 +480,86 @@ function extractMarkdownImages(markdown, documentPath) {
   }
   return images;
 }
+function extractMarkdownLinks(markdown) {
+  const codeMasked = maskCode(markdown);
+  const referenceDefinitions = collectReferenceDefinitions(markdown, codeMasked);
+  const masked = maskReferenceDefinitions(markdown, codeMasked);
+  const lineStarts = getLineStarts(markdown);
+  const links = [];
+  let index = 0;
+  while (index < masked.length) {
+    const start = masked.indexOf("[", index);
+    if (start === -1) break;
+    if (masked[start + 1] === "[" || markdown[start - 1] === "!" || isEscaped(markdown, start)) {
+      index = start + 1;
+      continue;
+    }
+    const labelClose = findClosingBracket(masked, start);
+    if (labelClose === -1) {
+      index = start + 1;
+      continue;
+    }
+    const label = markdown.slice(start + 1, labelClose);
+    const afterLabel = labelClose + 1;
+    const position = positionAt(lineStarts, start);
+    if (masked[afterLabel] === "(") {
+      const destinationClose = findClosingParen(markdown, afterLabel + 1);
+      if (destinationClose === -1) {
+        index = afterLabel + 1;
+        continue;
+      }
+      const parsed = parseDestinationAndTitle(markdown.slice(afterLabel + 1, destinationClose));
+      if (parsed) {
+        links.push(toLinkReference({
+          label,
+          target: parsed.source,
+          title: parsed.title,
+          line: position.line,
+          column: position.column,
+          syntax: "inline"
+        }));
+      }
+      index = destinationClose + 1;
+      continue;
+    }
+    if (masked[afterLabel] === "[") {
+      const referenceClose = findClosingBracket(masked, afterLabel);
+      if (referenceClose === -1) {
+        index = afterLabel + 1;
+        continue;
+      }
+      const explicitLabel = markdown.slice(afterLabel + 1, referenceClose);
+      const definitionLabel = explicitLabel.length > 0 ? explicitLabel : label;
+      const definition = referenceDefinitions.get(normalizeReferenceLabel(definitionLabel));
+      if (definition) {
+        links.push(toLinkReference({
+          label,
+          target: definition.source,
+          title: definition.title,
+          line: position.line,
+          column: position.column,
+          syntax: explicitLabel.length > 0 ? "reference" : "collapsed_reference"
+        }));
+      }
+      index = referenceClose + 1;
+      continue;
+    }
+    const shortcutDefinition = referenceDefinitions.get(normalizeReferenceLabel(label));
+    if (shortcutDefinition) {
+      links.push(toLinkReference({
+        label,
+        target: shortcutDefinition.source,
+        title: shortcutDefinition.title,
+        line: position.line,
+        column: position.column,
+        syntax: "shortcut_reference"
+      }));
+    }
+    index = labelClose + 1;
+  }
+  extractWikilinks(markdown, masked, lineStarts).forEach((link2) => links.push(link2));
+  return links.sort((left, right) => left.line - right.line || left.column - right.column);
+}
 function toImageReference(image2) {
   const workspacePath = resolveWorkspaceImagePath(image2.source, image2.documentPath);
   return {
@@ -483,6 +574,54 @@ function toImageReference(image2) {
     ...workspacePath ? { workspacePath } : {}
   };
 }
+function toLinkReference(link2) {
+  return {
+    label: unescapeMarkdown(link2.label),
+    target: link2.target,
+    ...link2.title ? { title: link2.title } : {},
+    line: link2.line,
+    column: link2.column,
+    syntax: link2.syntax
+  };
+}
+function extractWikilinks(markdown, masked, lineStarts) {
+  const links = [];
+  let index = 0;
+  while (index < masked.length) {
+    const start = masked.indexOf("[[", index);
+    if (start === -1) break;
+    if (isEscaped(markdown, start)) {
+      index = start + 2;
+      continue;
+    }
+    const close2 = masked.indexOf("]]", start + 2);
+    if (close2 === -1 || markdown.slice(start + 2, close2).includes("\n")) {
+      index = start + 2;
+      continue;
+    }
+    const parsed = parseWikilinkBody(markdown.slice(start + 2, close2));
+    if (parsed) {
+      const position = positionAt(lineStarts, start);
+      links.push({
+        label: parsed.label ?? parsed.target,
+        target: parsed.target,
+        line: position.line,
+        column: position.column,
+        syntax: "wikilink"
+      });
+    }
+    index = close2 + 2;
+  }
+  return links;
+}
+function maskReferenceDefinitions(markdown, masked) {
+  const markdownLines = markdown.split(/(?<=\n)/);
+  const maskedLines = masked.split(/(?<=\n)/);
+  return maskedLines.map((line, index) => {
+    const original = markdownLines[index] ?? "";
+    return parseReferenceDefinition(original.replace(/\r?\n$/, "")) ? maskLine(line) : line;
+  }).join("");
+}
 function collectReferenceDefinitions(markdown, masked) {
   const definitions = /* @__PURE__ */ new Map();
   const lines = getLines(markdown);
@@ -840,6 +979,184 @@ function applySuggestion(markdown, suggestion) {
   return next;
 }
 
+// ../core/src/graph.ts
+function resolveMarkdownLinks(links, currentDocument, documents) {
+  return links.map((link2) => resolveMarkdownLink(link2, currentDocument, documents));
+}
+function buildWorkspaceGraph(workspaceId, schemaVersion, documents) {
+  const edges = documents.flatMap((document) => document.links.map((link2, index) => toGraphEdge(document, link2, index)));
+  const incomingByDocId = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    if (!edge.targetDocId) continue;
+    incomingByDocId.set(edge.targetDocId, (incomingByDocId.get(edge.targetDocId) ?? 0) + 1);
+  }
+  const nodes = documents.map((document) => ({
+    docId: document.docId,
+    path: document.path,
+    title: document.title,
+    openComments: document.openComments,
+    openSuggestions: document.openSuggestions,
+    anchorsNeedingReview: document.anchorsNeedingReview,
+    outgoingLinks: document.links.length,
+    incomingLinks: incomingByDocId.get(document.docId) ?? 0,
+    unresolvedLinks: document.unresolvedLinks,
+    externalLinks: document.externalLinks
+  }));
+  return {
+    workspaceId,
+    schemaVersion,
+    nodes,
+    edges
+  };
+}
+function resolveMarkdownLink(link2, currentDocument, documents) {
+  const target = link2.target.trim();
+  const parsed = parseInternalTarget(target);
+  if (!target) return { ...link2, status: "unresolved" };
+  if (isExternalTarget(target)) return { ...link2, status: "external" };
+  if (!parsed) return { ...link2, status: "unresolved" };
+  if (!parsed.path) {
+    return parsed.fragment ? {
+      ...link2,
+      status: "anchor",
+      fragment: parsed.fragment,
+      targetDocId: currentDocument.docId,
+      targetPath: currentDocument.path,
+      targetTitle: currentDocument.title
+    } : { ...link2, status: "unresolved" };
+  }
+  if (link2.syntax === "wikilink" && !isPathLikeWikilinkTarget(parsed.path)) {
+    const candidates = findBasenameWikilinkCandidates(parsed.path, parsed.fragment, documents);
+    if (candidates.length === 1) return resolvedLink(link2, candidates[0]);
+    if (candidates.length > 1) return { ...link2, status: "ambiguous", fragment: parsed.fragment, candidates };
+    return { ...link2, status: "unresolved", fragment: parsed.fragment };
+  }
+  const linked = link2.syntax === "wikilink" ? resolvePathLikeWikilink(target, currentDocument.path, documents) : resolveWorkspaceDocumentLink(target, currentDocument.path, documents);
+  return linked ? resolvedLink(link2, linked) : { ...link2, status: "unresolved", fragment: parsed.fragment };
+}
+function resolvedLink(link2, target) {
+  return {
+    ...link2,
+    status: "resolved",
+    ...target.fragment ? { fragment: target.fragment } : {},
+    targetDocId: target.docId,
+    targetPath: target.path,
+    targetTitle: target.title
+  };
+}
+function toGraphEdge(document, link2, index) {
+  return {
+    id: `${document.docId}:${index}`,
+    sourceDocId: document.docId,
+    sourcePath: document.path,
+    sourceTitle: document.title,
+    label: link2.label,
+    target: link2.target,
+    ...link2.title ? { title: link2.title } : {},
+    line: link2.line,
+    column: link2.column,
+    syntax: link2.syntax,
+    status: link2.status,
+    ...link2.fragment ? { fragment: link2.fragment } : {},
+    ...link2.targetDocId ? { targetDocId: link2.targetDocId } : {},
+    ...link2.targetPath ? { targetPath: link2.targetPath } : {},
+    ...link2.targetTitle ? { targetTitle: link2.targetTitle } : {},
+    ...link2.candidates ? { candidates: link2.candidates } : {}
+  };
+}
+function resolveWorkspaceDocumentLink(target, currentPath, documents) {
+  const parsed = parseInternalTarget(target);
+  if (!parsed || !parsed.path) return void 0;
+  const workspacePath = resolveWorkspacePath(parsed.path, currentPath);
+  if (!workspacePath) return void 0;
+  const document = findLinkedDocument(candidateDocumentPaths(workspacePath), documents);
+  return document ? { ...document, ...parsed.fragment ? { fragment: parsed.fragment } : {} } : void 0;
+}
+function resolvePathLikeWikilink(target, currentPath, documents) {
+  const linked = resolveWorkspaceDocumentLink(target, currentPath, documents);
+  if (linked) return linked;
+  if (/^(?:\/|\.\/|\.\.\/)/.test(target)) return void 0;
+  return resolveWorkspaceDocumentLink(`/${target}`, currentPath, documents);
+}
+function findBasenameWikilinkCandidates(name, fragment, documents) {
+  const normalizedName = normalizeWikilinkName(name);
+  return documents.filter((doc) => normalizeWikilinkName(markdownStem(doc.path)) === normalizedName).map((doc) => ({ ...doc, ...fragment ? { fragment } : {} })).sort((left, right) => left.path.localeCompare(right.path, void 0, { numeric: true, sensitivity: "base" }));
+}
+function findLinkedDocument(paths, documents) {
+  for (const path of paths) {
+    const document = documents.find((candidate) => candidate.path === path);
+    if (document) return document;
+  }
+  return void 0;
+}
+function parseInternalTarget(target) {
+  const trimmed = target.trim();
+  if (!trimmed) return void 0;
+  const hashIndex = trimmed.indexOf("#");
+  const withoutFragment = hashIndex >= 0 ? trimmed.slice(0, hashIndex) : trimmed;
+  const fragment = hashIndex >= 0 ? safeDecode(trimmed.slice(hashIndex + 1)) : void 0;
+  const queryIndex = withoutFragment.indexOf("?");
+  const path = safeDecode(queryIndex >= 0 ? withoutFragment.slice(0, queryIndex) : withoutFragment);
+  return { path, ...fragment ? { fragment } : {} };
+}
+function resolveWorkspacePath(linkPath, currentPath) {
+  const path = linkPath.replaceAll("\\", "/").trim();
+  if (!path) return void 0;
+  const source = path.startsWith("/") ? path.slice(1) : `${dirname2(currentPath)}/${path}`;
+  return normalizeWorkspacePath2(source);
+}
+function normalizeWorkspacePath2(path) {
+  const segments = [];
+  for (const segment of path.split("/")) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      if (segments.length === 0) return void 0;
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+  return segments.join("/");
+}
+function candidateDocumentPaths(path) {
+  const candidates = [path];
+  if (path.endsWith("/")) {
+    candidates.push(`${path}README.md`, `${path}index.md`);
+  } else if (!/\.[^/.]+$/.test(path)) {
+    candidates.push(`${path}.md`, `${path}.mdx`, `${path}/README.md`, `${path}/index.md`);
+  }
+  return [...new Set(candidates)];
+}
+function isPathLikeWikilinkTarget(path) {
+  return /^(?:\/|\.\/|\.\.\/)/.test(path) || path.includes("/") || path.includes("\\") || /\.(md|mdx)$/i.test(path);
+}
+function isExternalTarget(target) {
+  const trimmed = target.trim();
+  if (!trimmed || trimmed.startsWith("#")) return false;
+  return /^[a-z][a-z0-9+.-]*:/i.test(trimmed) || trimmed.startsWith("//") || looksLikeBareDomain(trimmed);
+}
+function looksLikeBareDomain(value) {
+  return /^[a-z0-9-]+(?:\.[a-z0-9-]+)+(?:[/?#].*)?$/i.test(value) && !/\.(md|mdx)(?:[?#]|$)/i.test(value);
+}
+function markdownStem(path) {
+  const basename3 = path.split("/").pop() ?? path;
+  return basename3.replace(/\.mdx?$/i, "");
+}
+function normalizeWikilinkName(value) {
+  return value.trim().toLowerCase();
+}
+function dirname2(path) {
+  const index = path.lastIndexOf("/");
+  return index >= 0 ? path.slice(0, index) : "";
+}
+function safeDecode(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
 // ../core/src/sidecar.ts
 function defaultActor(name = "mdocs") {
   return {
@@ -916,9 +1233,12 @@ async function indexWorkspace(io) {
 }
 async function getWorkspaceMap(io) {
   const manifest = await indexWorkspace(io);
+  const graph = await workspaceGraphForManifest(io, manifest);
+  const graphNodesByDocId = new Map(graph.nodes.map((node) => [node.docId, node]));
   const docs = await Promise.all(
     manifest.docs.map(async (entry) => {
       const sidecar = await readSidecar(io, entry.docId);
+      const graphNode = graphNodesByDocId.get(entry.docId);
       return {
         docId: entry.docId,
         path: entry.path,
@@ -926,7 +1246,11 @@ async function getWorkspaceMap(io) {
         sidecarPath: sidecarPath(entry.docId),
         openComments: sidecar.comments.filter((comment2) => comment2.status === "open").length,
         openSuggestions: sidecar.suggestions.filter((suggestion) => suggestion.status === "open").length,
-        anchorsNeedingReview: sidecar.anchors.filter((anchor) => anchor.status !== "mapped").length
+        anchorsNeedingReview: sidecar.anchors.filter((anchor) => anchor.status !== "mapped").length,
+        outgoingLinks: graphNode?.outgoingLinks ?? 0,
+        incomingLinks: graphNode?.incomingLinks ?? 0,
+        unresolvedLinks: graphNode?.unresolvedLinks ?? 0,
+        externalLinks: graphNode?.externalLinks ?? 0
       };
     })
   );
@@ -936,6 +1260,9 @@ async function getWorkspaceMap(io) {
     docs
   };
 }
+async function getWorkspaceGraph(io) {
+  return workspaceGraphForManifest(io, await indexWorkspace(io));
+}
 async function getDocumentState(io, pathOrDocId) {
   const manifest = await indexWorkspace(io);
   const entry = findDoc(manifest, pathOrDocId);
@@ -964,10 +1291,31 @@ async function getDocumentState(io, pathOrDocId) {
       confidence: anchor.confidence
     })),
     images: extractMarkdownImages(markdown, entry.path),
+    links: resolveMarkdownLinks(extractMarkdownLinks(markdown), entry, manifest.docs),
     openComments: nextSidecar.comments.filter((comment2) => comment2.status === "open").length,
     openSuggestions: nextSidecar.suggestions.filter((suggestion) => suggestion.status === "open").length
   };
 }
+async function workspaceGraphForManifest(io, manifest) {
+  const documents = await Promise.all(
+    manifest.docs.map(async (entry) => {
+      const [markdown, sidecar] = await Promise.all([io.readText(entry.path), readSidecar(io, entry.docId)]);
+      const links = resolveMarkdownLinks(extractMarkdownLinks(markdown), entry, manifest.docs);
+      return {
+        docId: entry.docId,
+        path: entry.path,
+        title: entry.title,
+        openComments: sidecar.comments.filter((comment2) => comment2.status === "open").length,
+        openSuggestions: sidecar.suggestions.filter((suggestion) => suggestion.status === "open").length,
+        anchorsNeedingReview: sidecar.anchors.filter((anchor) => anchor.status !== "mapped").length,
+        externalLinks: links.filter((link2) => link2.status === "external").length,
+        unresolvedLinks: links.filter((link2) => link2.status === "unresolved" || link2.status === "ambiguous").length,
+        links
+      };
+    })
+  );
+  return buildWorkspaceGraph(manifest.workspaceId, manifest.schemaVersion, documents);
+}
 async function addComment(io, pathOrDocId, range, body, author = defaultActor()) {
   const state = await getDocumentState(io, pathOrDocId);
   assertLineRangeWithin(state.markdown, range);
@@ -1234,7 +1582,7 @@ var DEFAULT_ROOT_PATH_RULES = {
   maxFileSizeBytes: 1024 * 1024
 };
 var MARKDOWN_FILE_PATTERN = /\.mdx?$/i;
-function normalizeWorkspacePath2(path) {
+function normalizeWorkspacePath3(path) {
   const normalized = path.replaceAll("\\", "/").replace(/\/+/g, "/").trim();
   if (!normalized) throw new Error("Workspace path cannot be empty.");
   if (normalized.startsWith("/") || /^[a-zA-Z]:\//.test(normalized)) {
@@ -1247,7 +1595,7 @@ function normalizeWorkspacePath2(path) {
   return parts.filter((part) => part && part !== ".").join("/");
 }
 function assertWorkspacePathAllowed(path, rules = DEFAULT_ROOT_PATH_RULES, sizeBytes, ignoreMatcher) {
-  const normalized = normalizeWorkspacePath2(path);
+  const normalized = normalizeWorkspacePath3(path);
   if (isIgnoredWorkspacePath(normalized, rules)) {
     throw new Error(`Workspace path is ignored by root policy: ${normalized}`);
   }
@@ -1278,7 +1626,7 @@ function isWorkspaceMarkdownPathAllowed(path, rules = DEFAULT_ROOT_PATH_RULES, s
 function createWorkspaceIgnoreMatcher(ignoreFiles) {
   const rules = parseWorkspaceIgnoreRules(ignoreFiles);
   return (path) => {
-    const normalized = normalizeWorkspacePath2(path);
+    const normalized = normalizeWorkspacePath3(path);
     let ignored = false;
     for (const rule of rules) {
       if (!matchesWorkspaceIgnoreRule(normalized, rule)) continue;
@@ -1288,7 +1636,7 @@ function createWorkspaceIgnoreMatcher(ignoreFiles) {
   };
 }
 function isIgnoredWorkspacePath(path, rules = DEFAULT_ROOT_PATH_RULES) {
-  const normalized = normalizeWorkspacePath2(path);
+  const normalized = normalizeWorkspacePath3(path);
   const parts = normalized.split("/");
   return parts.some((part) => rules.ignoredDirectories.includes(part));
 }
@@ -1308,8 +1656,8 @@ function matchesAny(path, patterns) {
   return patterns.some((pattern) => globToRegExp(pattern).test(path));
 }
 function parseWorkspaceIgnoreRules(ignoreFiles) {
-  return [...ignoreFiles].sort((left, right) => normalizeWorkspacePath2(left.path).localeCompare(normalizeWorkspacePath2(right.path))).flatMap((file) => {
-    const normalizedPath = normalizeWorkspacePath2(file.path);
+  return [...ignoreFiles].sort((left, right) => normalizeWorkspacePath3(left.path).localeCompare(normalizeWorkspacePath3(right.path))).flatMap((file) => {
+    const normalizedPath = normalizeWorkspacePath3(file.path);
     const basePath = normalizedPath.endsWith("/.gitignore") ? normalizedPath.slice(0, -"/.gitignore".length) : "";
     return file.content.split(/\r?\n/).flatMap((line) => {
       const rule = parseWorkspaceIgnoreRule(basePath, line);
@@ -1416,14 +1764,14 @@ function createSourceMapping(input, updatedAt = (/* @__PURE__ */ new Date()).toI
   };
 }
 function canonicalPathToReplicaPath(path, mapping) {
-  if (path === ".mdocs" || path.startsWith(".mdocs/")) return normalizeWorkspacePath2(path);
-  const canonicalPath = normalizeWorkspacePath2(path);
+  if (path === ".mdocs" || path.startsWith(".mdocs/")) return normalizeWorkspacePath3(path);
+  const canonicalPath = normalizeWorkspacePath3(path);
   const relativePath = stripPrefix(canonicalPath, normalizeOptionalPrefix(mapping.canonicalPrefix), "canonical");
   return joinWorkspacePath(normalizeOptionalPrefix(mapping.replicaPrefix), relativePath);
 }
 function replicaPathToCanonicalPath(path, mapping) {
-  if (path === ".mdocs" || path.startsWith(".mdocs/")) return normalizeWorkspacePath2(path);
-  const replicaPath = normalizeWorkspacePath2(path);
+  if (path === ".mdocs" || path.startsWith(".mdocs/")) return normalizeWorkspacePath3(path);
+  const replicaPath = normalizeWorkspacePath3(path);
   const relativePath = stripPrefix(replicaPath, normalizeOptionalPrefix(mapping.replicaPrefix), "replica");
   return joinWorkspacePath(normalizeOptionalPrefix(mapping.canonicalPrefix), relativePath);
 }
@@ -1438,7 +1786,7 @@ function sourceMappingPathRules(mapping, base) {
 function normalizeOptionalPrefix(prefix) {
   const value = prefix?.trim();
   if (!value || value === ".") return "";
-  return normalizeWorkspacePath2(value).replace(/\/+$/, "");
+  return normalizeWorkspacePath3(value).replace(/\/+$/, "");
 }
 function stripPrefix(path, prefix, label) {
   if (!prefix) return path;
@@ -1447,9 +1795,9 @@ function stripPrefix(path, prefix, label) {
   throw new Error(`Path ${path} is outside ${label} prefix ${prefix}`);
 }
 function joinWorkspacePath(prefix, path) {
-  if (!prefix) return normalizeWorkspacePath2(path);
+  if (!prefix) return normalizeWorkspacePath3(path);
   if (!path) return prefix;
-  return normalizeWorkspacePath2(`${prefix}/${path}`);
+  return normalizeWorkspacePath3(`${prefix}/${path}`);
 }
 
 // ../core/src/share-routes.ts
@@ -1462,6 +1810,10 @@ function parseSharePath(pathname) {
     docId: docId ? decodeURIComponent(docId) : void 0
   };
 }
+function buildSharePath(workspaceId, rootId, docId) {
+  const base = `/share/${encodeURIComponent(workspaceId)}/${encodeURIComponent(rootId)}`;
+  return docId ? `${base}/${encodeURIComponent(docId)}` : base;
+}
 
 // ../../node_modules/orderedmap/dist/index.js
 function OrderedMap(content) {
@@ -3901,7 +4253,10 @@ function gatherMarks(schema2, marks) {
 // ../core/src/pm-schema.ts
 var canonicalSchema = new Schema({
   nodes: {
-    doc: { content: "block+" },
+    // The doc allows suggestion marks on its block children so pending
+    // block-level suggestions (node marks) survive fromJSON and can be
+    // structurally reverted before serialization.
+    doc: { content: "block+", marks: "insertion deletion modification" },
     paragraph: { group: "block", content: "inline*" },
     heading: {
       group: "block",
@@ -3969,14 +4324,45 @@ var canonicalSchema = new Schema({
       },
       inclusive: false
     },
+    wikilink: {
+      attrs: {
+        target: { default: null }
+      },
+      inclusive: false
+    },
     bold: {},
     italic: {},
     strike: {},
-    code: {}
+    code: {},
+    // Pending-suggestion marks (mirroring the web editor's extensions). They
+    // are never serialized — the canonical serializer reverts them first —
+    // but the schema must know them so suggestion-marked docs load intact.
+    insertion: {
+      attrs: { id: { default: null } },
+      inclusive: false,
+      excludes: "deletion modification insertion"
+    },
+    deletion: {
+      attrs: { id: { default: null } },
+      inclusive: false,
+      excludes: "insertion modification deletion"
+    },
+    modification: {
+      attrs: {
+        id: { default: null },
+        type: { default: null },
+        attrName: { default: null },
+        previousValue: { default: null },
+        newValue: { default: null }
+      },
+      inclusive: false,
+      excludes: "deletion insertion"
+    }
   }
 });
+var SUGGESTION_MARK_TYPES = /* @__PURE__ */ new Set(["insertion", "deletion", "modification"]);
 var CANONICAL_NODE_TYPES = new Set(Object.keys(canonicalSchema.nodes));
-var CANONICAL_MARK_TYPES = new Set(Object.keys(canonicalSchema.marks));
+var CANONICAL_MARK_TYPES = new Set(Object.keys(canonicalSchema.marks).filter((name) => !SUGGESTION_MARK_TYPES.has(name)));
 
 // ../../node_modules/markdown-it/lib/common/utils.mjs
 var utils_exports = {};
@@ -10171,9 +10557,28 @@ var markdownSerializer = new MarkdownSerializer(
         return `](${href.replace(/[()"]/g, "\\$&")})`;
       },
       mixable: false
+    },
+    wikilink: {
+      open(_state, mark, parent, index) {
+        const target = typeof mark.attrs.target === "string" ? mark.attrs.target : "";
+        const label = markedRangeText(parent, index, mark);
+        if (!target || label === target) return "[[";
+        return `[[${target}|`;
+      },
+      close: "]]",
+      mixable: false
     }
   }
 );
+function markedRangeText(parent, index, mark) {
+  let text2 = "";
+  for (let childIndex = index; childIndex < parent.childCount; childIndex += 1) {
+    const child = parent.child(childIndex);
+    if (!mark.isInSet(child.marks)) break;
+    text2 += child.textContent;
+  }
+  return text2;
+}
 function escapeImageAlt(value) {
   return value.replace(/\\/g, "\\\\").replace(/\[/g, "\\[").replace(/]/g, "\\]").replace(/\n+/g, " ");
 }
@@ -10237,7 +10642,7 @@ var RemoteDocumentIO = class {
 };
 
 // src/agent.ts
-var CLI_VERSION = "0.3.0";
+var CLI_VERSION = "0.3.2";
 var CLI_PACKAGE_NAME = "@magic-markdown/cli";
 var AGENT_COMMANDS = [
   {
@@ -10288,8 +10693,8 @@ var AGENT_COMMANDS = [
   },
   {
     name: "remote",
-    summary: "Read, comment on, suggest edits to, monitor, and restore the active Magic Markdown remote join.",
-    usage: "mdocs remote map|context|comment|suggest|reject|events|history|restore --json",
+    summary: "Read, organize, comment on, suggest edits to, monitor, and restore the active Magic Markdown remote join.",
+    usage: "mdocs remote map|graph|context|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: [
@@ -10297,14 +10702,24 @@ var AGENT_COMMANDS = [
       "mdocs remote context --start-line 1 --end-line 100 --json",
       "mdocs remote context --start-line 101 --end-line 200 --json",
       "mdocs remote map --json",
+      "mdocs remote graph --json",
+      "mdocs remote create-file docs/new-note.md --with-file /tmp/initial.md --json",
+      "mdocs remote move-file docs/new-note.md --to archive/new-note.md --json",
       "mdocs remote suggest --range 4:9 --with-file /tmp/replacement.md --message-file /tmp/message.txt --json",
       "mdocs remote comment docs/example.md --range 3:5 --body-file /tmp/comment.txt --json",
       "mdocs remote reject suggestion_abc123 --json",
       "mdocs remote history --json",
-      "mdocs remote restore head_abc123 --json"
+      "mdocs remote restore head_abc123 --json",
+      "mdocs remote library --json",
+      "mdocs remote create-folder Research --json",
+      "mdocs remote move-root --folder fold_abc123 --json",
+      "mdocs remote invite-folder fold_abc123 --email person@example.com --role edit --json"
     ],
     notes: [
       "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>.",
+      "remote graph requires a project-scoped join and returns the shared project's Obsidian-style Markdown/wikilink graph.",
+      "remote create-file and remote move-file require a project-scoped join and edit access. They write through the root sync API, so version history and conflict handling stay intact.",
+      "remote library, create-folder, update-folder, move-root, and invite-folder use the organization suite on top of the joined project. Folder invites require admin access on the joined root and can only target folders containing that root.",
       "remote comment/suggest never clobber concurrent edits: the server merges review additions, and the CLI rebases and retries automatically if a conflict still occurs.",
       "remote reject <suggestionId> withdraws a suggestion you submitted (for example, a duplicate). You can always withdraw your own; rejecting another author's suggestion requires edit access, and resolving a human's review work needs the user's explicit ask.",
       "remote events returns truncated: true when older events were dropped from the bounded log; refetch full state with remote context instead of trusting the gap.",
@@ -10322,15 +10737,27 @@ var AGENT_COMMANDS = [
   },
   {
     name: "map",
-    summary: "Return the indexed Markdown documents and review counts.",
+    summary: "Return the indexed Markdown documents, review counts, and link counts.",
     usage: "mdocs map --json",
     output: "json",
     mutates: true,
     examples: ["mdocs map --json"]
   },
+  {
+    name: "graph",
+    summary: "Return the workspace knowledge graph as document nodes and Markdown/wikilink edges.",
+    usage: "mdocs graph --json",
+    output: "json",
+    mutates: true,
+    examples: ["mdocs graph --json"],
+    notes: [
+      "Edges include resolved document links, ambiguous wikilinks, unresolved links, external links, and same-document anchor links.",
+      "Use this before broad agent edits to understand the Obsidian-style document graph and avoid changing related notes in isolation."
+    ]
+  },
   {
     name: "context",
-    summary: "Return agent-ready document Markdown, open review state, anchors, and image references.",
+    summary: "Return agent-ready document Markdown, open review state, anchors, image references, and resolved outgoing links.",
     usage: "mdocs context <path|docId> [--start-line N] [--end-line N] --json",
     output: "json",
     mutates: true,
@@ -10493,7 +10920,7 @@ function getAgentGuidePayload() {
 function getAgentSkillMarkdown() {
   return `---
 name: magic-markdown
-description: Use the Magic Markdown CLI or MCP server to read, review, comment on, suggest edits to, and sync clean Markdown workspaces without hand-editing .mdocs sidecars. Use when an agent needs to interact with Magic Markdown documents, comments, suggestions, image context, checkpoints, or local source sync.
+description: Use the Magic Markdown CLI or MCP server to read, organize, review, comment on, suggest edits to, and sync clean Markdown workspaces without hand-editing .mdocs sidecars. Use when an agent needs to interact with Magic Markdown documents, library folders, comments, suggestions, image context, checkpoints, or local source sync.
 metadata:
   short-description: Operate Magic Markdown via CLI/MCP
 ---
@@ -10520,9 +10947,10 @@ Run \`mdocs help <command>\` (or \`mdocs <command> --help\`) for usage, examples
 
 1. If given a Magic Markdown share URL, run \`mdocs join <share-url> --json\` first, and always include \`--name "<your agent name>"\` (for example \`--name "Claude Code"\`) so collaborators can see which agent is connected. Use \`mdocs remote ...\` commands after joining.
 2. If working in a local workspace, run \`mdocs doctor --json\` to validate the workspace and learn recommended next commands.
-3. Run \`mdocs map --json\` or \`mdocs remote map --json\` to list documents, paths, docIds, open comments, open suggestions, and anchor review counts. File-scoped joins (most share links) cover a single document, so \`mdocs remote map\` is unavailable for them \u2014 use \`mdocs remote context --json\` instead.
-4. For a document, run \`mdocs context <path|docId> --json\` locally or \`mdocs remote context <path|docId> --json\` for a joined share.
-5. Use \`mdocs comment\` / \`mdocs remote comment\` for review notes and \`mdocs suggest\` / \`mdocs remote suggest\` for proposed replacements. Do not insert comments, CriticMarkup, directives, or Magic markers into Markdown files.
+3. Run \`mdocs map --json\` or \`mdocs remote map --json\` to list documents, paths, docIds, open comments, open suggestions, anchor review counts, and link counts. File-scoped joins (most share links) cover a single document, so \`mdocs remote map\` is unavailable for them \u2014 use \`mdocs remote context --json\` instead. To organize a shared project, rejoin with \`--scope project\` and use \`mdocs remote library --json\`.
+4. Run \`mdocs graph --json\` or project-scoped \`mdocs remote graph --json\` before broad edits to inspect the Obsidian-style document graph built from Markdown links and wikilinks.
+5. For a document, run \`mdocs context <path|docId> --json\` locally or \`mdocs remote context <path|docId> --json\` for a joined share.
+6. Use \`mdocs comment\` / \`mdocs remote comment\` for review notes and \`mdocs suggest\` / \`mdocs remote suggest\` for proposed replacements. Do not insert comments, CriticMarkup, directives, or Magic markers into Markdown files.
 
 ## Editing Rules
 
@@ -10547,6 +10975,7 @@ Run \`mdocs help <command>\` (or \`mdocs <command> --help\`) for usage, examples
 ## Access Roles and Version History
 
 - Agents are **suggest-only by default**: comments and suggestions always work, but direct content rewrites are rejected with a \`forbidden_role\` error until a human grants edit access. Propose changes with \`mdocs remote suggest\` instead of rewriting content.
+- Project-scoped agents with edit access can create and move Markdown files and can move the joined root into library folders. Folder invites and folder hierarchy updates require admin access on the joined root.
 - Every accepted change is a content-addressed commit with a full snapshot. \`mdocs remote history --json\` lists commits with changed paths; \`mdocs remote restore <headId> --json\` restores the joined document to that snapshot (as a new commit, so it is reversible). Restore requires edit access \u2014 only run it when the user asked.
 
 ## Core Commands
@@ -10561,7 +10990,7 @@ Start the local stdio MCP server with:
 mdocs serve-mcp --cwd /path/to/workspace
 \`\`\`
 
-The MCP server exposes document resources, image resources, a workspace map resource, an agent guide resource, typed tools for comments and suggestions, and the \`magic_markdown_agent_workflow\` prompt.
+The MCP server exposes document resources, image resources, workspace map and graph resources, an agent guide resource, typed tools for comments and suggestions, and the \`magic_markdown_agent_workflow\` prompt.
 `;
 }
 function formatCommandReference() {
@@ -10618,7 +11047,7 @@ function toCliError(error) {
 
 // src/checkpoints.ts
 import { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname as dirname2, join } from "node:path";
+import { basename, dirname as dirname3, join } from "node:path";
 async function createCheckpoint(root, label) {
   const id = createId("checkpoint");
   const createdAt = nowIso();
@@ -10683,7 +11112,7 @@ async function restoreTree(snapshotRoot, root) {
       await mkdir(dest, { recursive: true });
       await restoreTree(source, dest);
     } else if (entry.isFile()) {
-      await mkdir(dirname2(dest), { recursive: true });
+      await mkdir(dirname3(dest), { recursive: true });
       await cp(source, dest);
     }
   }
@@ -10739,7 +11168,7 @@ function nextCommands(map) {
 
 // src/fs-io.ts
 import { mkdir as mkdir2, readFile as readFile2, readdir as readdir2, realpath, rename, rm as rm2, stat as stat2, writeFile as writeFile2 } from "node:fs/promises";
-import { dirname as dirname3, join as join2, relative, resolve } from "node:path";
+import { dirname as dirname4, join as join2, relative, resolve } from "node:path";
 var NodeWorkspaceIO = class {
   constructor(root, pathRules = DEFAULT_ROOT_PATH_RULES) {
     this.root = root;
@@ -10752,12 +11181,12 @@ var NodeWorkspaceIO = class {
   }
   async writeText(path, content) {
     const target = await this.resolveWritablePath(path, Buffer.byteLength(content, "utf8"));
-    await mkdir2(dirname3(target), { recursive: true });
+    await mkdir2(dirname4(target), { recursive: true });
     await writeFile2(target, content, "utf8");
   }
   async writeTextAtomic(path, content) {
     const target = await this.resolveWritablePath(path, Buffer.byteLength(content, "utf8"));
-    await mkdir2(dirname3(target), { recursive: true });
+    await mkdir2(dirname4(target), { recursive: true });
     const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
     await writeFile2(temporary, content, "utf8");
     await rename(temporary, target);
@@ -10794,12 +11223,12 @@ var NodeWorkspaceIO = class {
     const normalized = assertWorkspacePathAllowed(path, this.pathRules, sizeBytes);
     const root = await realpath(this.root);
     const target = resolve(root, normalized);
-    await mkdir2(dirname3(target), { recursive: true });
-    assertPathInsideRoot(root, await realpath(dirname3(target)));
+    await mkdir2(dirname4(target), { recursive: true });
+    assertPathInsideRoot(root, await realpath(dirname4(target)));
     return target;
   }
   async resolvePath(path) {
-    const normalized = normalizeWorkspacePath2(path);
+    const normalized = normalizeWorkspacePath3(path);
     const root = await realpath(this.root);
     const target = resolve(root, normalized);
     assertPathInsideRoot(root, target);
@@ -10836,7 +11265,7 @@ var PathMappedWorkspaceIO = class {
     return files.map((path) => replicaPathToCanonicalPath(path, this.mapping)).sort();
   }
   toReplicaPath(path) {
-    if (path === ".mdocs" || path.startsWith(".mdocs/")) return normalizeWorkspacePath2(path);
+    if (path === ".mdocs" || path.startsWith(".mdocs/")) return normalizeWorkspacePath3(path);
     return canonicalPathToReplicaPath(path, this.mapping);
   }
 };
@@ -10857,14 +11286,14 @@ async function walk(root, output, base, rules, ignoreFiles) {
     }
     if (entry.isFile()) {
       const stats = await stat2(absolute);
-      if (isWorkspaceMarkdownPathAllowed(relativePath, rules, stats.size, ignoreMatcher)) output.push(normalizeWorkspacePath2(relativePath));
+      if (isWorkspaceMarkdownPathAllowed(relativePath, rules, stats.size, ignoreMatcher)) output.push(normalizeWorkspacePath3(relativePath));
     }
   }
 }
 async function withDirectoryIgnoreFile(root, base, ignoreFiles) {
   try {
     const path = join2(relative(base, root).replaceAll("\\", "/"), ".gitignore").replace(/^\.\//, "");
-    const normalizedPath = path === ".gitignore" ? path : normalizeWorkspacePath2(path);
+    const normalizedPath = path === ".gitignore" ? path : normalizeWorkspacePath3(path);
     const content = await readFile2(join2(root, ".gitignore"), "utf8");
     return [...ignoreFiles, { path: normalizedPath, content }];
   } catch {
@@ -10997,6 +11426,7 @@ async function contextForDocument(io, path, startLine, endLine) {
     endLine: el,
     markdown,
     images: withMcpImageResources(io, state).images,
+    links: state.links,
     comments: state.sidecar.comments.filter((comment2) => comment2.status === "open"),
     suggestions: state.sidecar.suggestions.filter((suggestion) => suggestion.status === "open"),
     anchors: state.anchors
@@ -11074,7 +11504,12 @@ var actorProperties = {
 var tools = [
   {
     name: "mdocs_map",
-    description: "Return the workspace document map.",
+    description: "Return the workspace document map with review and link counts.",
+    inputSchema: noArgsSchema
+  },
+  {
+    name: "mdocs_graph",
+    description: "Return the workspace knowledge graph as document nodes and Markdown/wikilink edges. Edges include resolved, ambiguous, unresolved, external, and same-document anchor links.",
     inputSchema: noArgsSchema
   },
   {
@@ -11084,7 +11519,7 @@ var tools = [
   },
   {
     name: "mdocs_context",
-    description: "Return agent-ready document Markdown, open review state, anchors, and image references. Use startLine/endLine to read a specific line range when the full document is too large for one context window. The response always includes totalLines so you know whether to page.",
+    description: "Return agent-ready document Markdown, open review state, anchors, image references, and resolved outgoing links. Use startLine/endLine to read a specific line range when the full document is too large for one context window. The response always includes totalLines so you know whether to page.",
     inputSchema: {
       type: "object",
       properties: {
@@ -11223,6 +11658,11 @@ async function dispatch(io, method, params) {
           uri: "mdocs://workspace/map",
           name: "Workspace Map",
           mimeType: "application/vnd.mdocs.workspace-map+json"
+        },
+        {
+          uri: "mdocs://workspace/graph",
+          name: "Workspace Knowledge Graph",
+          mimeType: "application/vnd.mdocs.workspace-graph+json"
         }
       ])
     };
@@ -11315,6 +11755,17 @@ async function readResource(io, path) {
       ]
     };
   }
+  if (path === "mdocs://workspace/graph") {
+    return {
+      contents: [
+        {
+          uri: path,
+          mimeType: "application/vnd.mdocs.workspace-graph+json",
+          text: JSON.stringify(await getWorkspaceGraph(io), null, 2)
+        }
+      ]
+    };
+  }
   const imageMatch = /^mdocs:\/\/documents\/([^/]+)\/images\/(\d+)$/.exec(path);
   if (imageMatch) {
     return readImageResource(io, path, imageMatch[1] ?? "", Number(imageMatch[2]));
@@ -11333,6 +11784,7 @@ async function readResource(io, path) {
 }
 async function callTool(io, name, args) {
   if (name === "mdocs_map") return getWorkspaceMap(io);
+  if (name === "mdocs_graph") return getWorkspaceGraph(io);
   if (name === "mdocs_doctor") return runDoctor(io, io.root);
   if (name === "mdocs_context") {
     const startLine = typeof args.startLine === "number" ? args.startLine : void 0;
@@ -11459,6 +11911,42 @@ async function fetchTree(record) {
     headers: shareHeaders(record.shareUrl)
   });
 }
+async function fetchLibrary(record) {
+  return fetchJson(libraryUrl(record), {
+    headers: shareHeaders(record.shareUrl)
+  });
+}
+async function postLibraryFolder(record, input, actor) {
+  return fetchJson(`${libraryUrl(record)}/folders`, {
+    method: "POST",
+    headers: { ...shareHeaders(record.shareUrl), "Content-Type": "application/json" },
+    body: JSON.stringify({ ...input, actor })
+  });
+}
+async function patchLibraryFolder(record, folderId, input, actor) {
+  return fetchJson(`${libraryUrl(record)}/folders/${encodeURIComponent(folderId)}`, {
+    method: "PATCH",
+    headers: { ...shareHeaders(record.shareUrl), "Content-Type": "application/json" },
+    body: JSON.stringify({ ...input, actor })
+  });
+}
+async function postMoveRoot(record, folderId, actor) {
+  return fetchJson(`${libraryUrl(record)}/move-root`, {
+    method: "POST",
+    headers: { ...shareHeaders(record.shareUrl), "Content-Type": "application/json" },
+    body: JSON.stringify({ folderId, actor })
+  });
+}
+async function postFolderInvite(record, folderId, input, actor) {
+  return fetchJson(
+    `${libraryUrl(record)}/folders/${encodeURIComponent(folderId)}/invites`,
+    {
+      method: "POST",
+      headers: { ...shareHeaders(record.shareUrl), "Content-Type": "application/json" },
+      body: JSON.stringify({ ...input, actor })
+    }
+  );
+}
 async function fetchDocument(record, pathOrDocId) {
   if (record.scope === "file" && record.docId) {
     const document = await fetchDocumentById(record, record.docId);
@@ -11579,6 +12067,9 @@ function agentUrl(record, docId, action, query) {
   const base = `${record.origin}/api/agent/${encodeURIComponent(record.workspaceId)}/${encodeURIComponent(record.rootId)}/${encodeURIComponent(docId)}/${action}`;
   return query ? `${base}?${query}` : base;
 }
+function libraryUrl(record) {
+  return `${record.origin}/api/workspaces/${encodeURIComponent(record.workspaceId)}/roots/${encodeURIComponent(record.rootId)}/library`;
+}
 function shareHeaders(shareUrl) {
   return { Referer: shareUrl, Authorization: `Bearer ${shareUrl}` };
 }
@@ -11758,12 +12249,13 @@ async function runJoinCommand(root, parsed) {
   const agentName = resolveAgentName(parsed.flags);
   const agentId = normalizeAgentId(String(parsed.flags["agent-id"] ?? parsed.flags.actor ?? agentName));
   const docId = parsedShare.docId ?? await firstDocIdForProject(parsedShare);
-  const state = await postPresenceAndReadState(parsedShare, target, docId, agentId, agentName);
+  const shareUrl = shareUrlForScope(target, { ...parsedShare, docId });
+  const state = await postPresenceAndReadState(parsedShare, shareUrl, docId, agentId, agentName);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const record = {
     joinId: joinIdFor(target),
     scope: parsedShare.scope,
-    shareUrl: target,
+    shareUrl,
     origin: parsedShare.origin,
     workspaceId: parsedShare.workspaceId,
     rootId: parsedShare.rootId,
@@ -11782,7 +12274,7 @@ async function runJoinsCommand(root) {
   return listJoinRecords(root);
 }
 async function runRemoteCommand(root, subcommand, parsed) {
-  const record = await readSelectedJoin(root, parsed.flags);
+  const record = await normalizedSelectedJoin(root, parsed.flags);
   switch (subcommand) {
     case "map":
     case void 0:
@@ -11793,8 +12285,14 @@ async function runRemoteCommand(root, subcommand, parsed) {
       }
       await refreshPresence(record, record.docId);
       return fetchTree(record);
+    case "graph":
+      return remoteGraph(record);
     case "context":
       return remoteContext(record, parsed.command[2], parsed.flags);
+    case "create-file":
+      return remoteCreateFile(root, record, parsed);
+    case "move-file":
+      return remoteMoveFile(root, record, parsed);
     case "comment":
       return remoteComment(root, record, parsed);
     case "suggest":
@@ -11807,14 +12305,48 @@ async function runRemoteCommand(root, subcommand, parsed) {
       return remoteHistory(record, parsed.flags);
     case "restore":
       return remoteRestore(record, parsed);
+    case "library":
+      assertProjectScope(record, "library");
+      await refreshPresence(record, record.docId);
+      return fetchLibrary(record);
+    case "create-folder":
+      return remoteCreateFolder(record, parsed);
+    case "update-folder":
+      return remoteUpdateFolder(record, parsed);
+    case "move-root":
+      return remoteMoveRoot(record, parsed);
+    case "invite-folder":
+      return remoteInviteFolder(record, parsed);
     case "rejoin":
       return rejoin(root, record.joinId, parsed.flags);
     default:
       throw new CliError("usage_error", `Unknown remote subcommand: ${subcommand}`, {
-        hint: "Use mdocs remote map|context|comment|suggest|reject|events|history|restore|rejoin."
+        hint: "Use mdocs remote map|graph|context|create-file|move-file|comment|suggest|reject|events|history|restore|library|create-folder|update-folder|move-root|invite-folder|rejoin."
       });
   }
 }
+async function remoteGraph(record) {
+  assertProjectScope(record, "graph");
+  await refreshPresence(record, record.docId);
+  const tree = await fetchTree(record);
+  const documents = await Promise.all(tree.docs.map((doc) => fetchDocument(record, doc.docId)));
+  const lookup = documents.map((doc) => ({ docId: doc.docId, path: doc.path, title: doc.title }));
+  const graphDocuments = documents.map((doc) => {
+    const links = doc.links ?? resolveMarkdownLinks(extractMarkdownLinks(doc.markdown), doc, lookup);
+    return {
+      docId: doc.docId,
+      path: doc.path,
+      title: doc.title,
+      openComments: doc.openComments,
+      openSuggestions: doc.openSuggestions,
+      anchorsNeedingReview: doc.anchors.filter((anchor) => anchor.status !== "mapped").length,
+      externalLinks: links.filter((link2) => link2.status === "external").length,
+      unresolvedLinks: links.filter((link2) => link2.status === "unresolved" || link2.status === "ambiguous").length,
+      links
+    };
+  });
+  return buildWorkspaceGraph(record.workspaceId, SIDECAR_SCHEMA_VERSION, graphDocuments);
+}
 async function remoteHistory(record, flags) {
   await refreshPresence(record, record.docId);
   const limit = typeof flags.limit === "string" ? Number(flags.limit) || 50 : 50;
@@ -11844,9 +12376,11 @@ async function remoteRestore(record, parsed) {
 async function rejoin(root, joinId, flags) {
   const record = await readSelectedJoin(root, { ...flags, ...joinId ? { join: joinId } : {} });
   const docId = record.docId ?? await firstDocIdForProject(record);
-  const state = await postPresenceAndReadState(record, record.shareUrl, docId, record.agentId, record.agentName);
+  const shareUrl = shareUrlForScope(record.shareUrl, { ...record, docId });
+  const state = await postPresenceAndReadState(record, shareUrl, docId, record.agentId, record.agentName);
   const next = {
     ...record,
+    shareUrl,
     docId,
     updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     currentHead: state.document.currentSha
@@ -11854,6 +12388,15 @@ async function rejoin(root, joinId, flags) {
   await writeJoinRecord(root, next);
   return joinSummary(next, state.document);
 }
+async function normalizedSelectedJoin(root, flags) {
+  const record = await readSelectedJoin(root, flags);
+  if (!record.docId && record.scope === "file") return record;
+  const shareUrl = shareUrlForScope(record.shareUrl, record);
+  if (shareUrl === record.shareUrl) return record;
+  const next = { ...record, shareUrl, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+  await writeJoinRecord(root, next);
+  return next;
+}
 async function refreshPresence(record, docId) {
   if (!docId) return;
   await postPresence(record, record.shareUrl, docId, record.agentId, record.agentName).catch(() => void 0);
@@ -11887,8 +12430,74 @@ async function remoteContext(record, pathOrDocId, flags = {}) {
     comments: document.sidecar.comments.filter((comment2) => comment2.status === "open"),
     suggestions: document.sidecar.suggestions.filter((suggestion) => suggestion.status === "open"),
     anchors: document.anchors,
-    images: document.images
+    images: document.images,
+    links: document.links
+  };
+}
+async function remoteCreateFile(root, record, parsed) {
+  assertProjectScope(record, "create-file");
+  const path = parsed.command[2];
+  if (!path) {
+    throw new CliError("usage_error", "Missing file path.", {
+      hint: "Run mdocs remote create-file <path> --with-file /tmp/initial.md --json."
+    });
+  }
+  const tree = await fetchTree(record);
+  const markdownInput = await readOptionalTextFlag(parsed.flags, root, ["with", "markdown", "body"]);
+  const markdown = markdownInput ?? defaultMarkdown(path);
+  const normalizedPath = normalizeRemoteWorkspacePath(path, tree.root.pathRules, Buffer.byteLength(markdown, "utf8"));
+  if (tree.docs.some((doc) => doc.path === normalizedPath)) {
+    throw new CliError("validation_error", `Document already exists: ${normalizedPath}`, {
+      hint: "Choose a new path or use mdocs remote context to inspect the existing document."
+    });
+  }
+  const docId = createDocId();
+  const title = titleFromMarkdown(normalizedPath, markdown);
+  const sidecar = emptySidecar(docId, normalizedPath, title);
+  const baseDocument = {
+    workspaceId: record.workspaceId,
+    rootId: record.rootId,
+    docId,
+    path: normalizedPath,
+    title,
+    markdown,
+    sidecar,
+    anchors: [],
+    images: [],
+    links: [],
+    openComments: 0,
+    openSuggestions: 0,
+    currentSha: tree.root.canonical.head
   };
+  const document = await pushDocument(record, baseDocument, markdown, sidecar);
+  await recordHead(root, record, document);
+  return { document };
+}
+async function remoteMoveFile(root, record, parsed) {
+  assertProjectScope(record, "move-file");
+  const pathOrDocId = parsed.command[2];
+  if (!pathOrDocId) {
+    throw new CliError("usage_error", "Missing source document path or docId.", {
+      hint: "Run mdocs remote move-file <path|docId> --to <new-path> --json."
+    });
+  }
+  const nextPathFlag = requiredFlag(parsed.flags, "to");
+  const document = await fetchDocument(record, pathOrDocId);
+  const tree = await fetchTree(record);
+  const nextPath = normalizeRemoteWorkspacePath(nextPathFlag, tree.root.pathRules, Buffer.byteLength(document.markdown, "utf8"));
+  if (tree.docs.some((doc) => doc.docId !== document.docId && doc.path === nextPath)) {
+    throw new CliError("validation_error", `Document already exists: ${nextPath}`, {
+      hint: "Choose a path that is not already in use."
+    });
+  }
+  const moved = await pushDocument(
+    record,
+    { ...document, path: nextPath, title: titleFromMarkdown(nextPath, document.markdown) },
+    document.markdown,
+    document.sidecar
+  );
+  await recordHead(root, record, moved);
+  return { document: moved };
 }
 async function remoteComment(root, record, parsed) {
   const body = await readRequiredTextFlag(parsed.flags, root, ["body", "message"]);
@@ -11913,6 +12522,62 @@ async function remoteSuggest(root, record, parsed) {
   );
   return { suggestion: result.created, document: result.document };
 }
+async function remoteCreateFolder(record, parsed) {
+  assertProjectScope(record, "create-folder");
+  const name = folderNameFromArgs(parsed);
+  const parentId = optionalFolderTarget(parsed.flags.parent);
+  await refreshPresence(record, record.docId);
+  return postLibraryFolder(record, { name, ...parentId ? { parentId } : {} }, actorForRecord(record));
+}
+async function remoteUpdateFolder(record, parsed) {
+  assertProjectScope(record, "update-folder");
+  const folderId = parsed.command[2];
+  if (!folderId) {
+    throw new CliError("usage_error", "Missing folder id.", {
+      hint: "Run mdocs remote update-folder <folderId> --name <name> --json."
+    });
+  }
+  const input = {};
+  if (typeof parsed.flags.name === "string") input.name = parsed.flags.name;
+  if (parsed.flags.home === true || parsed.flags.home === "true") input.parentId = null;
+  else if (parsed.flags.parent !== void 0) input.parentId = optionalFolderTarget(parsed.flags.parent);
+  if (input.name === void 0 && input.parentId === void 0) {
+    throw new CliError("usage_error", "Nothing to update.", {
+      hint: "Pass --name <name>, --parent <folderId>, or --home."
+    });
+  }
+  await refreshPresence(record, record.docId);
+  return patchLibraryFolder(record, folderId, input, actorForRecord(record));
+}
+async function remoteMoveRoot(record, parsed) {
+  assertProjectScope(record, "move-root");
+  const folderId = parsed.flags.home === true || parsed.flags.home === "true" ? null : optionalFolderTarget(parsed.flags.folder);
+  if (folderId === void 0) {
+    throw new CliError("usage_error", "Missing target folder.", {
+      hint: "Pass --folder <folderId> to move into a folder, or --home to move to the top level."
+    });
+  }
+  await refreshPresence(record, record.docId);
+  return postMoveRoot(record, folderId, actorForRecord(record));
+}
+async function remoteInviteFolder(record, parsed) {
+  assertProjectScope(record, "invite-folder");
+  const folderId = parsed.command[2];
+  if (!folderId) {
+    throw new CliError("usage_error", "Missing folder id.", {
+      hint: "Run mdocs remote invite-folder <folderId> --email person@example.com --role edit --json."
+    });
+  }
+  const email = requiredFlag(parsed.flags, "email");
+  const role = typeof parsed.flags.role === "string" ? parsed.flags.role : "edit";
+  if (!["read", "suggest", "edit", "admin"].includes(role)) {
+    throw new CliError("usage_error", "Invalid --role.", {
+      hint: "Use --role read, suggest, edit, or admin."
+    });
+  }
+  await refreshPresence(record, record.docId);
+  return postFolderInvite(record, folderId, { email, role }, actorForRecord(record));
+}
 async function remoteReject(root, record, parsed) {
   const suggestionId = parsed.command[2];
   if (!suggestionId) {
@@ -12078,6 +12743,11 @@ function parseShareUrl(value, flags) {
     lastSeenEventId: 0
   };
 }
+function shareUrlForScope(value, record) {
+  const url = new URL(value);
+  url.pathname = buildSharePath(record.workspaceId, record.rootId, record.scope === "file" ? record.docId : void 0);
+  return url.toString();
+}
 function joinSummary(record, document) {
   return {
     connected: true,
@@ -12099,6 +12769,52 @@ function joinSummary(record, document) {
     ].filter(Boolean)
   };
 }
+function assertProjectScope(record, command) {
+  if (record.scope === "project") return;
+  throw new CliError("usage_error", `remote ${command} requires a project-scoped join.`, {
+    hint: "Rejoin the share with `mdocs join <share-url> --scope project --json`, then retry."
+  });
+}
+function emptySidecar(docId, path, title) {
+  return {
+    schemaVersion: SIDECAR_SCHEMA_VERSION,
+    docId,
+    path,
+    title,
+    anchors: [],
+    comments: [],
+    suggestions: [],
+    changeSets: [],
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function defaultMarkdown(path) {
+  return `# ${titleFromMarkdown(path, "")}
+`;
+}
+function normalizeRemoteWorkspacePath(path, rules, sizeBytes) {
+  try {
+    return assertWorkspacePathAllowed(path, rules, sizeBytes);
+  } catch (error) {
+    throw new CliError("validation_error", error instanceof Error ? error.message : String(error));
+  }
+}
+function folderNameFromArgs(parsed) {
+  const name = parsed.command[2] ?? (typeof parsed.flags.name === "string" ? parsed.flags.name : void 0);
+  if (!name?.trim()) {
+    throw new CliError("usage_error", "Missing folder name.", {
+      hint: "Run mdocs remote create-folder <name> --json."
+    });
+  }
+  return name;
+}
+function optionalFolderTarget(value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  if (!trimmed || trimmed === "home" || trimmed === "null" || trimmed === "top") return null;
+  return trimmed;
+}
 
 // src/bridge.ts
 import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
@@ -12529,6 +13245,10 @@ async function main() {
       print(await getWorkspaceMap(io), parsed.flags);
       return;
     }
+    case "graph": {
+      print(await getWorkspaceGraph(io), parsed.flags);
+      return;
+    }
     case "state": {
       print(await getDocumentState(io, requiredArg(parsed.command[1], "path")), parsed.flags);
       return;
@@ -12559,6 +13279,7 @@ async function main() {
           ...image2,
           ...image2.workspacePath ? { absolutePath: resolve5(cwd, image2.workspacePath) } : {}
         })),
+        links: state.links,
         comments: state.sidecar.comments.filter((comment2) => comment2.status === "open"),
         suggestions: state.sidecar.suggestions.filter((suggestion) => suggestion.status === "open"),
         anchors: state.anchors
@@ -12822,6 +13543,7 @@ Commands:
   agent commands --json              Print machine-readable command metadata
   init [path]                         Initialize .mdocs and index Markdown files
   map --json                          Print workspace map
+  graph --json                        Print workspace knowledge graph nodes and edges
   state <path> --json                 Print merged Markdown and sidecar state
   context <path> --json               Print agent-ready context
   comments <path> --json              List comments
@@ -12841,9 +13563,13 @@ Commands:
   checkpoint create|list|restore      Manage local reversible checkpoints
   join <share-url> --json             Join a Magic Markdown share through the CLI
   joins --json                        List saved Magic Markdown remote joins
-  remote map|context|comment|suggest  Work with the active remote join
+  remote map|graph|context|create-file|move-file
+                                      Work with documents in the active remote join
+  remote comment|suggest              Add remote review comments and suggestions
   remote reject <suggestionId>        Withdraw a suggestion you submitted remotely
   remote events|history|restore       Poll events, list commits, restore snapshots
+  remote library|create-folder|update-folder|move-root|invite-folder
+                                      Organize the joined project library
   bridge --workspace <id> --root . --url <base-url> --token <bridge-token>
                                       Sync an approved local root with the workspace
                                       (--token from the web "Bind agent filesystem"

package/package.json

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