refactor(git-sync): consume @docmost/prosemirror-markdown, drop the duplicate lib (#293 stage 3 / no-op)

git-sync's converter-core (src/lib) was a byte-identical duplicate of the new
@docmost/prosemirror-markdown package (created in the previous commit). Switch
git-sync to consume the package and delete its copy — ending the duplication
that the whole #293 effort targets. Pure no-op: NO format/behavior change.

- git-sync depends on @docmost/prosemirror-markdown (workspace:*); engine
  (stabilize/push/pull) + src/index barrel + 12 engine tests re-point their
  converter imports to the package.
- Delete git-sync/src/lib (8 files) and the 23 duplicate converter-core test
  files + their fixtures — the converter and its ~440 tests now live once, in the
  package. git-sync keeps only its ENGINE tests, which exercise the converter
  through the package (the no-op proof). Kept roundtrip-helpers.ts (an engine
  test imports firstDivergence from it; pure helper, no double-run).
- Added docmostExtensions to the package barrel (a kept engine schema-validity
  test needs it).

Verified: editor-ext + prosemirror-markdown + git-sync all tsc EXIT 0;
git-sync vitest 28 files, 268 passed, 0 failures (engine cycle/roundtrip/push/
pull/reconcile green = no-op proof); prosemirror-markdown vitest still 443 passed
| 1 expected-fail; pnpm --frozen-lockfile EXIT 0; no ../lib refs remain in git-sync.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitignore

@@ -4,12 +4,16 @@
 data
 # compiled output
 /dist
-node_modules/
+node_modules
 
 # git-sync compiled output (built in CI/Docker via `pnpm build`, never committed,
 # so src/ and prod can never silently diverge).
 packages/git-sync/build/
 
+# prosemirror-markdown compiled output (built in CI/Docker via `pnpm build`,
+# never committed, so src/ and prod can never silently diverge).
+packages/prosemirror-markdown/build/
+
 # Logs
 logs
 *.log

AGENTS.md

@@ -293,6 +293,7 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 - The version string shown in the UI comes from `APP_VERSION` (CI/Docker) or `git describe --tags --always` (local), resolved in `vite.config.ts` — not from `package.json`.
 - Server TS config is permissive (`noImplicitAny: false`, `strictNullChecks: false`, `no-explicit-any` lint disabled). Follow the existing relaxed style rather than tightening types broadly.
 - Dependency versions are heavily pinned via `pnpm.overrides` and `pnpm.patchedDependencies` (`scimmy`, `yjs`) in the root `package.json`. Don't bump pinned/patched deps casually; the patches and overrides exist for compatibility/security reasons.
+- **Adding/renaming/removing an MCP tool requires updating `SERVER_INSTRUCTIONS`** in `packages/mcp/src/index.ts` — the intent-routing guide MCP clients receive on initialize. This applies both to inline `server.registerTool(...)` calls in `index.ts` and to specs in `packages/mcp/src/tool-specs.ts`. Enforced by `packages/mcp/test/unit/server-instructions.test.mjs`, which fails when a registered tool is not mentioned in the guide (deliberate opt-outs go into its `EXCEPTIONS` list). Remember `packages/mcp/build/` is committed — rebuild after editing.
 
 ## CI / release
 

agent-roles-catalog/bundles/editorial/en.yaml

@@ -34,7 +34,7 @@ roles:
       Read the whole text first. Think at the level of sections and paragraphs, not sentences.
 
       HOW TO LEAVE COMMENTS
-      You don't edit the text yourself. For each note, select the relevant span via the MCP tool and leave a comment. Open the comment with the label `[Structure]`. Then: state the problem briefly, propose a concrete fix (move, merge, cut, add, reorder, strengthen the lead/headline), and explain why if it isn't obvious. Tag severity:
+      You don't edit the text yourself. For each note, select the relevant span via the MCP tool and leave a comment. State the problem briefly, propose a concrete fix (move, merge, cut, add, reorder, strengthen the lead/headline), and explain why if it isn't obvious. Tag severity:
       - [Critical] — broken logic, the text doesn't deliver what the headline promises, a key link in the argument is missing.
       - [Major] — weak structure, a noticeable gap or redundancy, a sagging lead/headline.
       - [Minor] — an optional improvement to framing or flow.
@@ -87,7 +87,7 @@ roles:
       - Don't rewrite the text yourself or impose your own voice. Your job is to make the author's voice livelier, not to replace it.
 
       HOW TO LEAVE COMMENTS
-      You don't edit the text directly. For each note, select the span via the MCP tool and leave a comment. Open the comment with the label `[Style]`. Give a concrete rephrasing, not "revise", and attach it to the comment as a suggested replacement (the `suggestedText` parameter): the exact new text for the selected fragment, plain text with no markup — the author applies it with one click. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Tag severity:
+      You don't edit the text directly. For each note, select the span via the MCP tool and leave a comment. Give a concrete rephrasing, not "revise", and attach it to the comment as a suggested replacement (the `suggestedText` parameter): the exact new text for the selected fragment, plain text with no markup — the author applies it with one click. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Tag severity:
       - [Critical] — the sentence is unclear or distorts the meaning.
       - [Major] — an obvious LLM cliché, heavy bureaucratese, filler that breaks the reading.
       - [Minor] — a stylistic improvement to taste.
@@ -128,7 +128,7 @@ roles:
       - Don't fabricate confirmations. If you can't verify, honestly mark [Unverified] or [Unverifiable].
 
       HOW TO LEAVE COMMENTS
-      You don't edit the text directly. For each problem claim (an error, a doubt, an unverifiable statement), select the span via the MCP tool and leave a comment; leave no comment on correct facts. Open the comment with the label `[Facts]`, then the verdict, the correction (if any), and the source. For an [Incorrect] verdict, ALWAYS attach the ready correction as a suggested replacement (the `suggestedText` parameter): since you found the correct value in the sources, propose the ready fix right away instead of merely describing the error. The replacement is the exact new text for the selected fragment, plain text with no markup; the author applies it with one click instead of retyping the fragment. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Do not attach a replacement to [Unverified], [Unverifiable], or [Opinion] verdicts. Tag severity:
+      You don't edit the text directly. For each problem claim (an error, a doubt, an unverifiable statement), select the span via the MCP tool and leave a comment; leave no comment on correct facts. Give the verdict, the correction (if any), and the source. For an [Incorrect] verdict, ALWAYS attach the ready correction as a suggested replacement (the `suggestedText` parameter): since you found the correct value in the sources, propose the ready fix right away instead of merely describing the error. The replacement is the exact new text for the selected fragment, plain text with no markup; the author applies it with one click instead of retyping the fragment. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Do not attach a replacement to [Unverified], [Unverifiable], or [Opinion] verdicts. Tag severity:
       - [Critical] — a factual error, especially in numbers, names, or quotes, or a claim that risks misinformation.
       - [Major] — a doubtful or unconfirmed claim that needs a source.
       - [Minor] — a small correction, or false precision worth rounding or confirming.
@@ -168,8 +168,11 @@ roles:
       - Don't verify facts — that's the Fact-checker.
       - Don't make substantive changes. Edits are minimal and mechanical.
 
+      HOW TO WORK
+      Go through the whole text from start to finish in a single pass. Flag EVERY violation, including all repeat occurrences of the same error and minor items tagged [Minor] — don't stop at the first few or the most conspicuous. Don't summarize instead of marking up: until you've reached the end of the document, the job isn't done. One run covers the whole text, not just "the most important".
+
       HOW TO LEAVE COMMENTS
-      You don't edit the text directly. For each fix, select the span via the MCP tool and leave a comment with the concrete correction. Attach a suggested replacement to every fix (the `suggestedText` parameter): the exact corrected text for the selected fragment, plain text with no markup — the author applies it with one click. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Do NOT leave summary notes like "throughout, replace X with Y" or "make the units/quotes/spelling consistent": such a comment can't be applied with a button. If the same error occurs in several places, walk EVERY occurrence and leave a separate targeted comment with its own replacement on each — ten targeted fixes instead of one blanket note. The only exception is a note that genuinely cannot be expressed as a replacement of a concrete fragment; leave those rare cases as an ordinary comment without a replacement. Open the comment with the label `[Copyedit]`. Tag severity:
+      You don't edit the text directly. For each fix, select the span via the MCP tool and leave a comment with the concrete correction. Attach a suggested replacement to every fix (the `suggestedText` parameter): the exact corrected text for the selected fragment, plain text with no markup — the author applies it with one click. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Do NOT leave summary notes like "throughout, replace X with Y" or "make the units/quotes/spelling consistent": such a comment can't be applied with a button. If the same error occurs in several places, walk EVERY occurrence and leave a separate targeted comment with its own replacement on each — ten targeted fixes instead of one blanket note. The only exception is a note that genuinely cannot be expressed as a replacement of a concrete fragment; leave those rare cases as an ordinary comment without a replacement. Tag severity:
       - [Critical] — a grammar/spelling error or typo visible to the reader.
       - [Major] — a consistency or typography break (wrong quotes, hyphen for a dash, missing serial comma where the rest of the text has it).
       - [Minor] — optional polish.

agent-roles-catalog/bundles/editorial/ru.yaml

@@ -34,7 +34,7 @@ roles:
       Сначала прочитай весь текст целиком. Думай на уровне разделов и абзацев, а не предложений.
 
       КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст сам. Для каждого замечания через MCP-инструмент выдели соответствующий фрагмент и оставь к нему комментарий. Начинай комментарий с метки `[Структура]`. Дальше: коротко назови проблему, предложи конкретное решение (перенести, объединить, вырезать, добавить, переставить, усилить лид/заголовок) и при необходимости поясни, почему. Помечай важность:
+      Ты не редактируешь текст сам. Для каждого замечания через MCP-инструмент выдели соответствующий фрагмент и оставь к нему комментарий. Коротко назови проблему, предложи конкретное решение (перенести, объединить, вырезать, добавить, переставить, усилить лид/заголовок) и при необходимости поясни, почему. Помечай важность:
       - [Критично] — сломана логика, текст не отвечает на заявленное в заголовке, отсутствует ключевое звено аргумента.
       - [Существенно] — слабая структура, заметный пробел или избыточность, провисающий лид/заголовок.
       - [Незначительно] — улучшение подачи или стройности, не обязательное.
@@ -87,7 +87,7 @@ roles:
       - Не переписываешь текст сам и не навязываешь свой голос. Твоя задача — сделать авторскую интонацию живее, а не заменить собой.
 
       КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст напрямую. Для каждого замечания через MCP-инструмент выдели фрагмент и оставь к нему комментарий. Начинай комментарий с метки `[Стиль]`. Давай конкретный вариант переформулировки, а не «переделать», и прикладывай его к комментарию как предложение-замену (параметр `suggestedText`): точный новый текст взамен выделенного фрагмента, обычным текстом без разметки — автор применит его одной кнопкой. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. Помечай важность:
+      Ты не редактируешь текст напрямую. Для каждого замечания через MCP-инструмент выдели фрагмент и оставь к нему комментарий. Давай конкретный вариант переформулировки, а не «переделать», и прикладывай его к комментарию как предложение-замену (параметр `suggestedText`): точный новый текст взамен выделенного фрагмента, обычным текстом без разметки — автор применит его одной кнопкой. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. Помечай важность:
       - [Критично] — предложение непонятно или искажает смысл.
       - [Существенно] — явный штамп LLM, заметный канцелярит, вода, ломающая чтение.
       - [Незначительно] — стилистическое улучшение на вкус.
@@ -128,7 +128,7 @@ roles:
       - Не выдумываешь подтверждения. Если не можешь проверить — честно ставь [Не проверено] или [Непроверяемо].
 
       КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст напрямую. Для каждого проблемного утверждения (ошибка, сомнение, непроверяемость) через MCP-инструмент выдели фрагмент и оставь комментарий; на верные факты комментарии не оставляй. Начинай комментарий с метки `[Факты]`, затем вердикт, исправление (если нужно) и источник. К вердикту [Неверно] всегда прикладывай готовое исправление как предложение-замену (параметр `suggestedText`): раз ты нашёл по источникам верное значение — сразу предлагай готовую правку, а не только описывай ошибку. Замена — это точный новый текст взамен выделенного фрагмента, обычным текстом без разметки; автор применит её одной кнопкой, не переписывая фрагмент вручную. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. К вердиктам [Не проверено], [Непроверяемо] и [Это мнение] замену не прикладывай. Помечай важность:
+      Ты не редактируешь текст напрямую. Для каждого проблемного утверждения (ошибка, сомнение, непроверяемость) через MCP-инструмент выдели фрагмент и оставь комментарий; на верные факты комментарии не оставляй. В комментарии дай вердикт, исправление (если нужно) и источник. К вердикту [Неверно] всегда прикладывай готовое исправление как предложение-замену (параметр `suggestedText`): раз ты нашёл по источникам верное значение — сразу предлагай готовую правку, а не только описывай ошибку. Замена — это точный новый текст взамен выделенного фрагмента, обычным текстом без разметки; автор применит её одной кнопкой, не переписывая фрагмент вручную. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. К вердиктам [Не проверено], [Непроверяемо] и [Это мнение] замену не прикладывай. Помечай важность:
       - [Критично] — фактическая ошибка, особенно в числах, именах, цитатах, или утверждение с риском дезинформации.
       - [Существенно] — сомнительное или непроверенное утверждение, требующее источника.
       - [Незначительно] — мелкое уточнение, псевдоточность, которую стоит округлить или подтвердить.
@@ -169,8 +169,11 @@ roles:
       - Не проверяешь достоверность фактов — это фактчекер.
       - Не вносишь содержательных изменений. Правки — минимальные и механические.
 
+      КАК РАБОТАТЬ
+      Пройди весь текст от начала до конца за один проход. Помечай КАЖДОЕ нарушение, включая все повторные вхождения одной и той же ошибки и мелочи с меткой [Незначительно], — не ограничивайся первыми несколькими или самыми заметными. Не подводи итог вместо разбора: пока не дошёл до конца документа, работа не закончена. Один прогон покрывает весь текст, а не «самое важное».
+
       КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст напрямую. Для каждой правки через MCP-инструмент выдели фрагмент и оставь комментарий с конкретным исправлением. К каждой правке прикладывай предложение-замену (параметр `suggestedText`): точный исправленный текст взамен выделенного фрагмента, обычным текстом без разметки — автор применит его одной кнопкой. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. НЕ оставляй сводных замечаний вида «во всём тексте заменить X на Y» или «привести единицы/кавычки/написание к единообразию»: такой комментарий нельзя применить кнопкой. Если одна и та же ошибка встречается в нескольких местах, обойди КАЖДОЕ вхождение и оставь на нём отдельный целевой комментарий со своей заменой — десять точечных правок вместо одной общей. Единственное исключение — замечание, которое в принципе невозможно выразить заменой конкретного фрагмента; такие редкие случаи оставляй обычным комментарием без замены. Начинай комментарий с метки `[Корректура]`. Помечай важность:
+      Ты не редактируешь текст напрямую. Для каждой правки через MCP-инструмент выдели фрагмент и оставь комментарий с конкретным исправлением. К каждой правке прикладывай предложение-замену (параметр `suggestedText`): точный исправленный текст взамен выделенного фрагмента, обычным текстом без разметки — автор применит его одной кнопкой. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. НЕ оставляй сводных замечаний вида «во всём тексте заменить X на Y» или «привести единицы/кавычки/написание к единообразию»: такой комментарий нельзя применить кнопкой. Если одна и та же ошибка встречается в нескольких местах, обойди КАЖДОЕ вхождение и оставь на нём отдельный целевой комментарий со своей заменой — десять точечных правок вместо одной общей. Единственное исключение — замечание, которое в принципе невозможно выразить заменой конкретного фрагмента; такие редкие случаи оставляй обычным комментарием без замены. Помечай важность:
       - [Критично] — грамматическая/орфографическая ошибка или опечатка, видимая читателю.
       - [Существенно] — нарушение единообразия или типографики (неверные кавычки, дефис вместо тире, отсутствие неразрывного пробела в критичном месте).
       - [Незначительно] — необязательная шлифовка.

agent-roles-catalog/index.yaml

@@ -12,13 +12,13 @@ bundles:
       - en
     roles:
       - slug: structural-editor
-        version: 3
-      - slug: line-editor
-        version: 3
-      - slug: fact-checker
         version: 4
-      - slug: proofreader
+      - slug: line-editor
+        version: 4
+      - slug: fact-checker
         version: 5
+      - slug: proofreader
+        version: 7
       - slug: narrator
         version: 2
   - id: research

agent-roles-catalog/scripts/content-hashes.json

@@ -1,26 +1,26 @@
 {
   "fact-checker": {
-    "version": 4,
-    "hash": "9160ead04d86aaa5dc7a51dd7e971c272ce0ca97cb24bf2b6ee5779deb1b19c0"
+    "version": 5,
+    "hash": "d7769872968109a1ccfb58d71bc3f3564a750b91766156f59031762848de4f24"
   },
   "line-editor": {
-    "version": 3,
-    "hash": "7f200863080799b08d5af5d1648befa0843cc5db79bb994b07baa5ad12df5123"
+    "version": 4,
+    "hash": "890d10f3f0bd7f2b2cfcc94463634221c557a3140e3794721748dc8d99979780"
   },
   "narrator": {
     "version": 2,
     "hash": "66fe653003b4f63ef3c3a5c5c48552fe47daeefffc16907c37c35f0e8da98851"
   },
   "proofreader": {
-    "version": 5,
-    "hash": "40af08c51e03c24b1986ac5cd679434e023afe31a819748966ccb0c6c62f0401"
+    "version": 7,
+    "hash": "fdf8e0a443fa3c4102095e024146401363629a3f9015fb938c7bac2642825e56"
   },
   "researcher": {
     "version": 1,
     "hash": "853658fda43ddbe0a4d08f2c6e50b5116d29a2e9ccd7f46e173e65920d8f6ace"
   },
   "structural-editor": {
-    "version": 3,
-    "hash": "f6936e4c152c1b78980e74045658d87743f26f900c12f61fd7a45c6a0ec19425"
+    "version": 4,
+    "hash": "89100e0a00b88daa0d2118fd98ec1c27d06b972bfc6ec58b705553a4daed85df"
   }
 }

apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts

@@ -303,7 +303,9 @@ export class AiChatToolsService {
       getPage: tool({
         description:
           'Fetch a single page as Markdown by its page id. Returns the page ' +
-          'title and its Markdown content.',
+          'title and its Markdown content. Inline <span data-comment-id> tags ' +
+          'in the markdown are comment highlight anchors (also present for ' +
+          'RESOLVED threads) — treat them as markup, not page text.',
         inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id (or slugId) of the page.'),
         }),
@@ -647,7 +649,9 @@ export class AiChatToolsService {
 
       listComments: tool({
         description:
-          'List all comments on a page (content as Markdown).',
+          'List ALL comments on a page in one call, including RESOLVED ' +
+          'threads — filter by resolvedAt when you need only open ones. ' +
+          'Content is returned as Markdown.',
         inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page.'),
         }),

packages/git-sync/package.json

@@ -20,6 +20,7 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@docmost/prosemirror-markdown": "workspace:*",
     "@tiptap/core": "3.20.4",
     "@tiptap/extension-highlight": "3.20.4",
     "@tiptap/extension-image": "3.20.4",

packages/git-sync/src/engine/pull.ts

@@ -31,7 +31,7 @@
  */
 import { dirname } from "node:path";
 import { sep } from "node:path";
-import { parsePageFile, serializePageFile } from "../lib/page-file.js";
+import { parsePageFile, serializePageFile } from "@docmost/prosemirror-markdown";
 import type { GitSyncClient } from "./client.types.js";
 import { buildVaultLayout, type PageNode } from "./layout.js";
 import {

packages/git-sync/src/engine/push.ts

@@ -26,8 +26,11 @@
  * the gitmost server drives the engine in-process (there is no standalone CLI
  * entry point).
  */
-import { type DocmostMdMeta } from "../lib/index.js";
-import { parsePageFile, serializePageFile } from "../lib/page-file.js";
+import {
+  type DocmostMdMeta,
+  parsePageFile,
+  serializePageFile,
+} from "@docmost/prosemirror-markdown";
 import type { GitSyncClient } from "./client.types.js";
 import type { DiffEntry } from "./git.js";
 import { VaultGit, DEFAULT_BRANCH } from "./git.js";

packages/git-sync/src/engine/stabilize.ts

@@ -17,7 +17,7 @@ import {
   markdownToProseMirror,
   serializeDocmostMarkdownBody,
   type DocmostMdMeta,
-} from "../lib/index.js";
+} from "@docmost/prosemirror-markdown";
 
 /**
  * Meta object as `exportPageBody` builds it (SPEC §4). Kept byte-for-byte

packages/git-sync/src/index.ts

@@ -8,6 +8,10 @@
  */
 
 // Pure converter (markdown <-> ProseMirror, file envelope, canonicalization).
+// Re-exported from the standalone `@docmost/prosemirror-markdown` package,
+// which is the single source of truth for the converter core; git-sync keeps
+// only the engine (vault/git/orchestrator) and re-surfaces the converter for
+// in-process consumers of the git-sync barrel.
 export {
   serializeDocmostMarkdown,
   serializeDocmostMarkdownBody,
@@ -16,8 +20,8 @@ export {
   markdownToProseMirror,
   canonicalizeContent,
   docsCanonicallyEqual,
-} from "./lib/index.js";
-export type { DocmostMdMeta } from "./lib/index.js";
+} from "@docmost/prosemirror-markdown";
+export type { DocmostMdMeta } from "@docmost/prosemirror-markdown";
 
 // Pure engine (no IO): reconcile planner, vault layout, sanitize, stabilize,
 // loop-guard body hash.
@@ -123,4 +127,4 @@ export {
 } from "./engine/path-guard.js";
 export type { PathGuardIo, VaultPathUnsafeReason } from "./engine/path-guard.js";
 
-export { parsePageFile, serializePageFile } from "./lib/page-file.js";
+export { parsePageFile, serializePageFile } from "@docmost/prosemirror-markdown";

packages/git-sync/test/apply-push-actions.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
 import { applyPushActions, LAST_PUSHED_REF } from '../src/engine/push';
 import { bodyHash } from '../src/engine/loop-guard';
 import type { ApplyPushDeps, PushActions } from '../src/engine/push';
-import { parsePageFile, serializePageFile } from '../src/lib/page-file';
+import { parsePageFile, serializePageFile } from '@docmost/prosemirror-markdown';
 
 // The Docmost space this vault mirrors (native files carry no spaceId; the run
 // supplies it). A CREATE targets this space.

packages/git-sync/test/classify-rename-moves.test.ts

@@ -5,7 +5,7 @@ import type {
   MetaSide,
   RenameMoveAction,
 } from '../src/engine/push';
-import type { DocmostMdMeta } from '../src/lib/index';
+import type { DocmostMdMeta } from '@docmost/prosemirror-markdown';
 
 // FS→Docmost push #3 (SPEC §5/§6/§16). `classifyRenameMoves` is the PURE half of
 // the move/rename apply: it resolves each `{pageId, oldPath, newPath}` into the

packages/git-sync/test/compute-push-actions.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { computePushActions } from '../src/engine/push';
 import type { DiffEntry, MetaSide } from '../src/engine/push';
-import type { DocmostMdMeta } from '../src/lib/index';
+import type { DocmostMdMeta } from '@docmost/prosemirror-markdown';
 
 // FS→Docmost push, FIRST increment (SPEC §6). `computePushActions` is the PURE
 // half: it classifies each `git diff --name-status` row into a Docmost action by

packages/git-sync/test/cycle-roundtrip.test.ts

@@ -8,7 +8,7 @@ import { runCycle } from "../src/engine/cycle";
 import type { CycleFs } from "../src/engine/cycle";
 import { VaultGit } from "../src/engine/git";
 import type { Settings } from "../src/engine/settings";
-import { serializeDocmostMarkdownBody } from "../src/lib/index";
+import { serializeDocmostMarkdownBody } from "@docmost/prosemirror-markdown";
 
 const execFileAsync = promisify(execFile);
 

packages/git-sync/test/engine-gaps.test.ts

@@ -8,7 +8,7 @@ import { firstDivergence } from './roundtrip-helpers';
 import { applyPullActions } from '../src/engine/pull';
 import type { PullActions, ApplyPullActionsDeps } from '../src/engine/pull';
 import type { DeletionDecision } from '../src/engine/reconcile';
-import { serializePageFile, parsePageFile } from '../src/lib/page-file';
+import { serializePageFile, parsePageFile } from '@docmost/prosemirror-markdown';
 
 // Engine-layer coverage gaps flagged by the PR #119 reviewers (test-strategy
 // report, Module 2 `src/engine`). Each block targets a specific under-covered

packages/git-sync/test/read-existing.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { readExisting } from '../src/engine/pull';
-import { serializePageFile } from '../src/lib/page-file';
+import { serializePageFile } from '@docmost/prosemirror-markdown';
 
 // R-Pull-1 (test-strategy report §5): `readExisting` now takes injectable IO
 // (`listTracked` / `readFile`), so its parsing + skip rules are unit-testable

packages/git-sync/test/redteam-layout-title.test.ts

@@ -6,7 +6,7 @@ import type {
   MetaSide,
   RenameMoveAction,
 } from '../src/engine/push.js';
-import type { DocmostMdMeta } from '../src/lib/index.js';
+import type { DocmostMdMeta } from '@docmost/prosemirror-markdown';
 
 // RED-TEAM finding #4 (two facets):
 //   (a) buildVaultLayout disambiguation is ORDER-DEPENDENT: which of two

packages/git-sync/test/redteam-push-cycle.test.ts

@@ -8,7 +8,7 @@ import {
 import type { PushDeps } from '../src/engine/push';
 import type { Settings } from '../src/engine/settings';
 import { runCycle, type RunCycleDeps } from '../src/engine/cycle';
-import { serializePageFile } from '../src/lib/page-file';
+import { serializePageFile } from '@docmost/prosemirror-markdown';
 
 // Red-team confirmations for PR #119 (git-sync). Each test asserts the DESIRED
 // behavior, so it FAILS today iff the bug is real.

packages/git-sync/test/run-push-realgit.test.ts

@@ -8,7 +8,7 @@ import { runPush, LAST_PUSHED_REF } from '../src/engine/push';
 import type { PushDeps } from '../src/engine/push';
 import { VaultGit } from '../src/engine/git';
 import type { Settings } from '../src/engine/settings';
-import { serializeDocmostMarkdownBody } from '../src/lib/index';
+import { serializeDocmostMarkdownBody } from '@docmost/prosemirror-markdown';
 
 const execFileAsync = promisify(execFile);
 

packages/git-sync/test/run-push.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest';
 import { runPush, LAST_PUSHED_REF, DOCMOST_BRANCH } from '../src/engine/push';
 import type { PushDeps } from '../src/engine/push';
 import type { Settings } from '../src/engine/settings';
-import { serializePageFile } from '../src/lib/page-file';
+import { serializePageFile } from '@docmost/prosemirror-markdown';
 
 /** A native page file: `gitmost_id` frontmatter + clean body (title = filename). */
 function fileFor(pageId: string, body = 'body'): string {

packages/git-sync/test/stabilize.test.ts

@@ -2,8 +2,8 @@ import { describe, expect, it } from 'vitest';
 import { stabilizePageFile, type PageMeta } from '../src/engine/stabilize.js';
 // markdownToProseMirror lives in collaboration.ts; importing it mutates the
 // global DOM via jsdom at module load time (required for @tiptap/html under Node).
-import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
-import { parseDocmostMarkdown } from '../src/lib/markdown-document.js';
+import { markdownToProseMirror } from '@docmost/prosemirror-markdown';
+import { parseDocmostMarkdown } from '@docmost/prosemirror-markdown';
 
 // stabilize.ts (SPEC §11 normalize-on-write) was 0% covered (only the gated e2e
 // touched it). stabilizePageFile is import-testable: build a small ProseMirror

packages/git-sync/test/strip-empty-paragraphs-validity.test.ts

@@ -1,8 +1,8 @@
 import { describe, it, expect } from "vitest";
 import { getSchema } from "@tiptap/core";
 
-import { markdownToProseMirror } from "../src/lib/markdown-to-prosemirror";
-import { docmostExtensions } from "../src/lib/docmost-schema";
+import { markdownToProseMirror } from "@docmost/prosemirror-markdown";
+import { docmostExtensions } from "@docmost/prosemirror-markdown";
 
 // REGRESSION LOCK for the stripEmptyParagraphs schema-validity guard.
 //

packages/mcp/build/index.js

@@ -27,10 +27,19 @@ const VERSION = packageJson.version;
 // --- Modern McpServer Implementation ---
 // Editing guide surfaced to MCP clients in the initialize result so they can
 // pick the right tool by intent and avoid resending whole documents.
-const SERVER_INSTRUCTIONS = "Docmost editing guide — choose the tool by intent: fix wording/typos/numbers (text inside blocks) -> edit_page_text (no node id needed). Change ONE block (paragraph/heading/callout/table cell/etc.) structurally -> patch_node (address by attrs.id from get_page_json). Add a block -> insert_node (before/after a block by attrs.id or by anchor text, or append). Remove a block -> delete_node (by attrs.id). Images -> insert_image (add an image from a web URL) / replace_image (swap an existing image for one from a web URL). New page -> create_page (Markdown). Bulk/structural rewrite or nodes without an id -> update_page_json (full ProseMirror replace; prefer the granular tools above to avoid resending the whole ~100KB+ document). Copy/replace a page's whole content from another page (server-side, no document through the model) -> copy_page_content. Rename a page (title only) -> rename_page. Read -> get_page (Markdown, lossy) or get_page_json (lossless ProseMirror with block ids). Comments -> create_comment (always inline; requires an EXACT selection — the contiguous text to anchor/highlight on; fails rather than leaving an unanchored comment), list_comments, update_comment, resolve_comment (resolve/reopen a thread, reversible — prefer over delete to close), delete_comment, check_new_comments. Propose a concrete text fix for one-click human approval -> create_comment with suggestedText (the exact plain-text replacement for the selection; the selection must then be UNIQUE in the page — extend it with context if needed); prefer this over editing directly when the change is subjective or needs the author's sign-off. Tip: read block ids via get_page_json, then use patch_node/insert_node/delete_node so you never resend the full document. " +
-    "Complex/scripted rewrite (multiple coordinated edits, footnotes, renumbering) -> docmost_transform: write a JS `(doc, ctx) => doc` transform, preview the diff with dryRun (default), then apply with dryRun:false; ctx.helpers includes commentsToFootnotes for turning inline comments into numbered footnotes. " +
-    "Review what changed -> diff_page_versions (compare a historyId to current, or two history versions). See a page's saved versions -> list_page_history. Undo a bad edit -> restore_page_version (writes a past version back as current; itself revertible). " +
-    "Lossless markdown round-trip (download, edit, re-upload, incl. comment anchors) -> export_page_markdown / import_page_markdown.";
+//
+// MAINTENANCE RULE: when you ADD, RENAME, or REMOVE a tool (either an inline
+// server.registerTool(...) here or a spec in tool-specs.ts), you MUST update
+// this guide so the new tool is routed by intent. This is enforced by
+// test/unit/server-instructions.test.mjs, which fails when a registered tool
+// name is not mentioned below (see its EXCEPTIONS list for the rare opt-outs).
+// Exported for that test.
+export const SERVER_INSTRUCTIONS = "Docmost editing guide — choose the tool by intent.\n" +
+    "READ: find a page -> search (workspace-wide full-text); list -> list_pages / list_spaces. Locate blocks and their ids CHEAPLY -> get_outline (compact top-level map; start here, not get_page_json). One block's subtree -> get_node (by attrs.id, or \"#<index>\" for tables, which carry no id). Whole page -> get_page (Markdown, lossy; inline <span data-comment-id> tags are comment anchors — markup, not text) or get_page_json (lossless ProseMirror with block ids). Hand a huge page (with images) to an external consumer without pulling it through the model context -> stash_page (returns a short-lived anonymous URL).\n" +
+    "EDIT: fix wording/typos/numbers -> edit_page_text (find/replace inside blocks, no node id needed). Change ONE block (paragraph/heading/callout/etc.) structurally -> patch_node (by attrs.id from get_outline). Add a block -> insert_node (before/after a block by attrs.id or by anchor text, or append). Remove a block -> delete_node (by attrs.id). Tables -> table_get / table_update_cell / table_insert_row / table_delete_row (address by \"#<index>\" from get_outline; table nodes have no attrs.id). Images -> insert_image (add from a web URL) / replace_image (swap an existing image). Footnotes -> insert_footnote. Bulk/structural rewrite -> update_page_json (full ProseMirror replace; prefer the granular tools above to avoid resending the whole ~100KB+ document). Complex/scripted rewrite (multiple coordinated edits, renumbering) -> docmost_transform: write a JS `(doc, ctx) => doc` transform, preview the diff with dryRun (default), then apply with dryRun:false; ctx.helpers includes commentsToFootnotes for turning inline comments into numbered footnotes.\n" +
+    "PAGES: new -> create_page (Markdown). Rename (title only) -> rename_page. Move -> move_page. Delete -> delete_page (SOFT delete — the page goes to trash and is restorable; nothing is permanent). Copy/replace a page's whole content from another page (server-side, no document through the model) -> copy_page_content. Sharing -> share_page / unshare_page / list_shares; share_page makes the page PUBLICLY accessible — do it only when explicitly asked.\n" +
+    "COMMENTS: create_comment is always inline and requires an EXACT selection — contiguous text from a single block, <=250 chars (fails rather than leaving an unanchored comment); reply to a thread via parentCommentId. Propose a concrete text fix for one-click human approval -> create_comment with suggestedText (the exact plain-text replacement for the selection; the selection must then be UNIQUE in the page — extend it with context if needed); prefer this over editing directly when the change is subjective or needs the author's sign-off. Manage -> list_comments, update_comment, resolve_comment (resolve/reopen, reversible — prefer over delete to close), delete_comment, check_new_comments.\n" +
+    "HISTORY: review what changed -> diff_page_versions (a historyId vs current, or two versions). List saved versions -> list_page_history. Undo a bad edit -> restore_page_version (writes a past version back as current; itself revertible). Lossless markdown round-trip (download, edit, re-upload, incl. comment anchors) -> export_page_markdown / import_page_markdown.";
 // Helper to format JSON responses
 const jsonContent = (data) => ({
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -107,7 +116,9 @@ export function createDocmostMcpServer(config) {
     server.registerTool("get_page", {
         description: "Get page details with content converted to Markdown. The conversion is " +
             "LOSSY (block ids, exact table/callout structure are approximated); for a " +
-            "lossless representation use get_page_json.",
+            "lossless representation use get_page_json. Inline <span data-comment-id> " +
+            "tags in the markdown are comment highlight anchors (also present for " +
+            "RESOLVED threads) — treat them as markup, not page text.",
         inputSchema: {
             pageId: z.string().min(1),
         },
@@ -204,7 +215,8 @@ export function createDocmostMcpServer(config) {
     });
     // Tool: create_page
     server.registerTool("create_page", {
-        description: "Create a new page with content (automatically moves it to the correct hierarchy).",
+        description: "Create a new page from Markdown in a space. Pass parentPageId to nest " +
+            "it under a parent; omit it to create at the space root.",
         inputSchema: {
             title: z.string().min(1).describe("Title of the page"),
             content: z.string().min(1).describe("Markdown content"),
@@ -426,7 +438,8 @@ export function createDocmostMcpServer(config) {
     // agent; this transport keeps the plain public-URL wording.
     server.registerTool("share_page", {
         description: "Make a page publicly accessible (idempotent) and return its public " +
-            "URL. The URL format is <app>/share/<key>/p/<slugId>.",
+            "URL. The URL format is <app>/share/<key>/p/<slugId>. This exposes the " +
+            "page content to ANYONE with the URL — do it only when explicitly asked.",
         inputSchema: {
             pageId: z.string().min(1).describe("ID of the page to share"),
             searchIndexing: z
@@ -450,7 +463,7 @@ export function createDocmostMcpServer(config) {
     });
     // Tool: move_page
     server.registerTool("move_page", {
-        description: "Move a page to a new parent (nesting) or root. Essential for organizing pages created via 'create_page'.",
+        description: "Move a page under a new parent (nesting) or to the space root.",
         inputSchema: {
             pageId: z.string().min(1),
             parentPageId: z
@@ -486,7 +499,8 @@ export function createDocmostMcpServer(config) {
     });
     // Tool: delete_page
     server.registerTool("delete_page", {
-        description: "Delete a single page by ID.",
+        description: "Delete a single page by ID. SOFT delete only: the page is moved to " +
+            "trash and can be restored; nothing is permanently deleted.",
         inputSchema: {
             pageId: z.string().min(1),
         },
@@ -501,7 +515,9 @@ export function createDocmostMcpServer(config) {
     // --- Comment tools (ported from upstream PR #3 by Max Nikitin) ---
     // Tool: list_comments
     server.registerTool("list_comments", {
-        description: "List all comments on a page (paginated). Content is returned as Markdown.",
+        description: "List ALL comments on a page in one call (pagination is handled " +
+            "internally), including RESOLVED threads — filter by resolvedAt when you " +
+            "need only open ones. Content is returned as Markdown.",
         inputSchema: {
             pageId: z.string().describe("ID of the page"),
         },
@@ -652,8 +668,9 @@ export function createDocmostMcpServer(config) {
     // different schema (limit 1-20); this transport is a plain REST full-text search
     // (limit up to 100). Different behaviour AND schema, so kept per-layer.
     server.registerTool("search", {
-        description: "Search for pages and content. Results are bounded by `limit` " +
-            "(default applied by the client, max 100).",
+        description: "Full-text search for pages and content across the whole workspace. " +
+            "Results are bounded by `limit` (1-100; when omitted the server applies " +
+            "its own default).",
         inputSchema: {
             query: z.string().min(1).describe("Search query"),
             limit: z
@@ -703,7 +720,9 @@ export function createDocmostMcpServer(config) {
             "insertInlineFootnote(doc, {anchorText, text}) (author-inline footnote: " +
             "marker + dedup'd definition, list derived). Footnote convention: markers are " +
             "plain '[N]' text in the body; the notes are an orderedList under a " +
-            "heading whose text is 'Примечания переводчика'. The transform runs " +
+            "heading whose text is 'Примечания переводчика' (that is only the DEFAULT " +
+            "notesHeading — pass the notesHeading option to the helpers to use a " +
+            "heading matching the page's language). The transform runs " +
             "sandboxed (no require/process/fs/network, 5s timeout) and must return a " +
             "{type:'doc'} node.",
         inputSchema: {

packages/mcp/build/tool-specs.js

@@ -13,6 +13,11 @@
 // diverge on purpose (security guardrails, tuned UX, "Reversible" framing on
 // some write tools, different limits, hybrid-RRF search, etc.) stay defined
 // per-layer and are NOT represented here.
+//
+// MAINTENANCE RULE: adding, renaming, or removing a spec here (or an inline
+// registerTool in index.ts) REQUIRES updating SERVER_INSTRUCTIONS in
+// packages/mcp/src/index.ts — the intent-routing guide MCP clients receive on
+// initialize. Enforced by test/unit/server-instructions.test.mjs.
 export const SHARED_TOOL_SPECS = {
     // --- no-argument read tools ---
     getWorkspace: {
@@ -73,8 +78,8 @@ export const SHARED_TOOL_SPECS = {
     deleteNode: {
         mcpName: 'delete_node',
         inAppKey: 'deleteNode',
-        description: 'Remove a single block by its attrs.id (from the page-JSON view) WITHOUT ' +
-            'resending the whole document.',
+        description: 'Remove a single block by its attrs.id (from the page outline or ' +
+            'page-JSON view) WITHOUT resending the whole document.',
         buildShape: (z) => ({
             pageId: z.string().min(1),
             nodeId: z.string().min(1),
@@ -94,7 +99,8 @@ export const SHARED_TOOL_SPECS = {
         inAppKey: 'patchNode',
         description: 'Replace a single content block identified by its attrs.id with a new ' +
             'ProseMirror node, WITHOUT resending the whole document; the replacement ' +
-            'keeps the same node id. Get the block id from the page-JSON view, then ' +
+            'keeps the same node id. Get the block id from the page outline (cheap) ' +
+            'or the page-JSON view, then ' +
             'pass a ProseMirror node to put in its place. Example node: a paragraph ' +
             '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
             'heading {"type":"heading","attrs":{"level":2},"content":' +
@@ -123,7 +129,8 @@ export const SHARED_TOOL_SPECS = {
         description: 'Insert a block before/after another block (by attrs.id or anchor text) ' +
             'or append it at the end (top level). For before/after you MUST provide ' +
             'EXACTLY ONE of anchorNodeId or anchorText. Get anchor block ids from the ' +
-            'page-JSON view. Avoids resending the whole document. Can also insert ' +
+            'page outline or the page-JSON view. Avoids resending the whole document. ' +
+            'Can also insert ' +
             'table structure: to add a tableRow, pass a tableRow node with position ' +
             'before/after and anchor INSIDE the target table — anchorNodeId of any ' +
             'block/cell in it, or anchorText matching the table; to add a ' +

packages/mcp/src/index.ts

@@ -37,11 +37,20 @@ const VERSION = packageJson.version;
 
 // Editing guide surfaced to MCP clients in the initialize result so they can
 // pick the right tool by intent and avoid resending whole documents.
-const SERVER_INSTRUCTIONS =
-  "Docmost editing guide — choose the tool by intent: fix wording/typos/numbers (text inside blocks) -> edit_page_text (no node id needed). Change ONE block (paragraph/heading/callout/table cell/etc.) structurally -> patch_node (address by attrs.id from get_page_json). Add a block -> insert_node (before/after a block by attrs.id or by anchor text, or append). Remove a block -> delete_node (by attrs.id). Images -> insert_image (add an image from a web URL) / replace_image (swap an existing image for one from a web URL). New page -> create_page (Markdown). Bulk/structural rewrite or nodes without an id -> update_page_json (full ProseMirror replace; prefer the granular tools above to avoid resending the whole ~100KB+ document). Copy/replace a page's whole content from another page (server-side, no document through the model) -> copy_page_content. Rename a page (title only) -> rename_page. Read -> get_page (Markdown, lossy) or get_page_json (lossless ProseMirror with block ids). Comments -> create_comment (always inline; requires an EXACT selection — the contiguous text to anchor/highlight on; fails rather than leaving an unanchored comment), list_comments, update_comment, resolve_comment (resolve/reopen a thread, reversible — prefer over delete to close), delete_comment, check_new_comments. Propose a concrete text fix for one-click human approval -> create_comment with suggestedText (the exact plain-text replacement for the selection; the selection must then be UNIQUE in the page — extend it with context if needed); prefer this over editing directly when the change is subjective or needs the author's sign-off. Tip: read block ids via get_page_json, then use patch_node/insert_node/delete_node so you never resend the full document. " +
-  "Complex/scripted rewrite (multiple coordinated edits, footnotes, renumbering) -> docmost_transform: write a JS `(doc, ctx) => doc` transform, preview the diff with dryRun (default), then apply with dryRun:false; ctx.helpers includes commentsToFootnotes for turning inline comments into numbered footnotes. " +
-  "Review what changed -> diff_page_versions (compare a historyId to current, or two history versions). See a page's saved versions -> list_page_history. Undo a bad edit -> restore_page_version (writes a past version back as current; itself revertible). " +
-  "Lossless markdown round-trip (download, edit, re-upload, incl. comment anchors) -> export_page_markdown / import_page_markdown.";
+//
+// MAINTENANCE RULE: when you ADD, RENAME, or REMOVE a tool (either an inline
+// server.registerTool(...) here or a spec in tool-specs.ts), you MUST update
+// this guide so the new tool is routed by intent. This is enforced by
+// test/unit/server-instructions.test.mjs, which fails when a registered tool
+// name is not mentioned below (see its EXCEPTIONS list for the rare opt-outs).
+// Exported for that test.
+export const SERVER_INSTRUCTIONS =
+  "Docmost editing guide — choose the tool by intent.\n" +
+  "READ: find a page -> search (workspace-wide full-text); list -> list_pages / list_spaces. Locate blocks and their ids CHEAPLY -> get_outline (compact top-level map; start here, not get_page_json). One block's subtree -> get_node (by attrs.id, or \"#<index>\" for tables, which carry no id). Whole page -> get_page (Markdown, lossy; inline <span data-comment-id> tags are comment anchors — markup, not text) or get_page_json (lossless ProseMirror with block ids). Hand a huge page (with images) to an external consumer without pulling it through the model context -> stash_page (returns a short-lived anonymous URL).\n" +
+  "EDIT: fix wording/typos/numbers -> edit_page_text (find/replace inside blocks, no node id needed). Change ONE block (paragraph/heading/callout/etc.) structurally -> patch_node (by attrs.id from get_outline). Add a block -> insert_node (before/after a block by attrs.id or by anchor text, or append). Remove a block -> delete_node (by attrs.id). Tables -> table_get / table_update_cell / table_insert_row / table_delete_row (address by \"#<index>\" from get_outline; table nodes have no attrs.id). Images -> insert_image (add from a web URL) / replace_image (swap an existing image). Footnotes -> insert_footnote. Bulk/structural rewrite -> update_page_json (full ProseMirror replace; prefer the granular tools above to avoid resending the whole ~100KB+ document). Complex/scripted rewrite (multiple coordinated edits, renumbering) -> docmost_transform: write a JS `(doc, ctx) => doc` transform, preview the diff with dryRun (default), then apply with dryRun:false; ctx.helpers includes commentsToFootnotes for turning inline comments into numbered footnotes.\n" +
+  "PAGES: new -> create_page (Markdown). Rename (title only) -> rename_page. Move -> move_page. Delete -> delete_page (SOFT delete — the page goes to trash and is restorable; nothing is permanent). Copy/replace a page's whole content from another page (server-side, no document through the model) -> copy_page_content. Sharing -> share_page / unshare_page / list_shares; share_page makes the page PUBLICLY accessible — do it only when explicitly asked.\n" +
+  "COMMENTS: create_comment is always inline and requires an EXACT selection — contiguous text from a single block, <=250 chars (fails rather than leaving an unanchored comment); reply to a thread via parentCommentId. Propose a concrete text fix for one-click human approval -> create_comment with suggestedText (the exact plain-text replacement for the selection; the selection must then be UNIQUE in the page — extend it with context if needed); prefer this over editing directly when the change is subjective or needs the author's sign-off. Manage -> list_comments, update_comment, resolve_comment (resolve/reopen, reversible — prefer over delete to close), delete_comment, check_new_comments.\n" +
+  "HISTORY: review what changed -> diff_page_versions (a historyId vs current, or two versions). List saved versions -> list_page_history. Undo a bad edit -> restore_page_version (writes a past version back as current; itself revertible). Lossless markdown round-trip (download, edit, re-upload, incl. comment anchors) -> export_page_markdown / import_page_markdown.";
 
 // Helper to format JSON responses
 const jsonContent = (data: any) => ({
@@ -147,7 +156,9 @@ server.registerTool(
     description:
       "Get page details with content converted to Markdown. The conversion is " +
       "LOSSY (block ids, exact table/callout structure are approximated); for a " +
-      "lossless representation use get_page_json.",
+      "lossless representation use get_page_json. Inline <span data-comment-id> " +
+      "tags in the markdown are comment highlight anchors (also present for " +
+      "RESOLVED threads) — treat them as markup, not page text.",
     inputSchema: {
       pageId: z.string().min(1),
     },
@@ -288,7 +299,8 @@ server.registerTool(
   "create_page",
   {
     description:
-      "Create a new page with content (automatically moves it to the correct hierarchy).",
+      "Create a new page from Markdown in a space. Pass parentPageId to nest " +
+      "it under a parent; omit it to create at the space root.",
     inputSchema: {
       title: z.string().min(1).describe("Title of the page"),
       content: z.string().min(1).describe("Markdown content"),
@@ -587,7 +599,8 @@ server.registerTool(
   {
     description:
       "Make a page publicly accessible (idempotent) and return its public " +
-      "URL. The URL format is <app>/share/<key>/p/<slugId>.",
+      "URL. The URL format is <app>/share/<key>/p/<slugId>. This exposes the " +
+      "page content to ANYONE with the URL — do it only when explicitly asked.",
     inputSchema: {
       pageId: z.string().min(1).describe("ID of the page to share"),
       searchIndexing: z
@@ -619,7 +632,7 @@ server.registerTool(
   "move_page",
   {
     description:
-      "Move a page to a new parent (nesting) or root. Essential for organizing pages created via 'create_page'.",
+      "Move a page under a new parent (nesting) or to the space root.",
     inputSchema: {
       pageId: z.string().min(1),
       parentPageId: z
@@ -675,7 +688,9 @@ server.registerTool(
 server.registerTool(
   "delete_page",
   {
-    description: "Delete a single page by ID.",
+    description:
+      "Delete a single page by ID. SOFT delete only: the page is moved to " +
+      "trash and can be restored; nothing is permanently deleted.",
     inputSchema: {
       pageId: z.string().min(1),
     },
@@ -697,7 +712,9 @@ server.registerTool(
   "list_comments",
   {
     description:
-      "List all comments on a page (paginated). Content is returned as Markdown.",
+      "List ALL comments on a page in one call (pagination is handled " +
+      "internally), including RESOLVED threads — filter by resolvedAt when you " +
+      "need only open ones. Content is returned as Markdown.",
     inputSchema: {
       pageId: z.string().describe("ID of the page"),
     },
@@ -913,8 +930,9 @@ server.registerTool(
   "search",
   {
     description:
-      "Search for pages and content. Results are bounded by `limit` " +
-      "(default applied by the client, max 100).",
+      "Full-text search for pages and content across the whole workspace. " +
+      "Results are bounded by `limit` (1-100; when omitted the server applies " +
+      "its own default).",
     inputSchema: {
       query: z.string().min(1).describe("Search query"),
       limit: z
@@ -970,7 +988,9 @@ server.registerTool(
       "insertInlineFootnote(doc, {anchorText, text}) (author-inline footnote: " +
       "marker + dedup'd definition, list derived). Footnote convention: markers are " +
       "plain '[N]' text in the body; the notes are an orderedList under a " +
-      "heading whose text is 'Примечания переводчика'. The transform runs " +
+      "heading whose text is 'Примечания переводчика' (that is only the DEFAULT " +
+      "notesHeading — pass the notesHeading option to the helpers to use a " +
+      "heading matching the page's language). The transform runs " +
       "sandboxed (no require/process/fs/network, 5s timeout) and must return a " +
       "{type:'doc'} node.",
     inputSchema: {

packages/mcp/src/tool-specs.ts

@@ -13,6 +13,11 @@
 // diverge on purpose (security guardrails, tuned UX, "Reversible" framing on
 // some write tools, different limits, hybrid-RRF search, etc.) stay defined
 // per-layer and are NOT represented here.
+//
+// MAINTENANCE RULE: adding, renaming, or removing a spec here (or an inline
+// registerTool in index.ts) REQUIRES updating SERVER_INSTRUCTIONS in
+// packages/mcp/src/index.ts — the intent-routing guide MCP clients receive on
+// initialize. Enforced by test/unit/server-instructions.test.mjs.
 
 // Loose on purpose — see the comment above. The two zod majors expose different
 // static type surfaces, so typing this precisely would couple the registry to
@@ -111,8 +116,8 @@ export const SHARED_TOOL_SPECS = {
     mcpName: 'delete_node',
     inAppKey: 'deleteNode',
     description:
-      'Remove a single block by its attrs.id (from the page-JSON view) WITHOUT ' +
-      'resending the whole document.',
+      'Remove a single block by its attrs.id (from the page outline or ' +
+      'page-JSON view) WITHOUT resending the whole document.',
     buildShape: (z) => ({
       pageId: z.string().min(1),
       nodeId: z.string().min(1),
@@ -134,7 +139,8 @@ export const SHARED_TOOL_SPECS = {
     description:
       'Replace a single content block identified by its attrs.id with a new ' +
       'ProseMirror node, WITHOUT resending the whole document; the replacement ' +
-      'keeps the same node id. Get the block id from the page-JSON view, then ' +
+      'keeps the same node id. Get the block id from the page outline (cheap) ' +
+      'or the page-JSON view, then ' +
       'pass a ProseMirror node to put in its place. Example node: a paragraph ' +
       '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
       'heading {"type":"heading","attrs":{"level":2},"content":' +
@@ -169,7 +175,8 @@ export const SHARED_TOOL_SPECS = {
       'Insert a block before/after another block (by attrs.id or anchor text) ' +
       'or append it at the end (top level). For before/after you MUST provide ' +
       'EXACTLY ONE of anchorNodeId or anchorText. Get anchor block ids from the ' +
-      'page-JSON view. Avoids resending the whole document. Can also insert ' +
+      'page outline or the page-JSON view. Avoids resending the whole document. ' +
+      'Can also insert ' +
       'table structure: to add a tableRow, pass a tableRow node with position ' +
       'before/after and anchor INSIDE the target table — anchorNodeId of any ' +
       'block/cell in it, or anchorText matching the table; to add a ' +

packages/mcp/test/unit/server-instructions.test.mjs

@@ -0,0 +1,82 @@
+// Guard: every tool the MCP server registers must be routed by intent in
+// SERVER_INSTRUCTIONS — the editing guide clients receive in the initialize
+// result. Without this, new tools silently rot out of the guide and agents
+// never learn to pick them (the guide once omitted 17 of 41 tools, including
+// get_outline, which pushed agents into fetching whole documents for block
+// ids). Tool names are extracted from the SOURCE (index.ts inline
+// registrations + tool-specs.ts shared specs) so a registration added either
+// way is caught; the guide text itself is imported from the build so the test
+// checks what actually ships.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { SERVER_INSTRUCTIONS } from "../../build/index.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SRC = join(HERE, "..", "..", "src");
+
+// Tools DELIBERATELY absent from the guide. Keep this list minimal and
+// justify every entry — the default is: every tool gets routed.
+const EXCEPTIONS = new Set([
+  // Trivial and self-explanatory; carries no routing decision.
+  "get_workspace",
+]);
+
+/**
+ * Extract every registered tool name from the source. Two registration
+ * mechanisms exist and both are covered:
+ *  - inline `server.registerTool("name", ...)` calls in index.ts;
+ *  - shared specs in tool-specs.ts (`mcpName: 'name'`), registered via
+ *    registerShared(SHARED_TOOL_SPECS.x, ...).
+ */
+function registeredToolNames() {
+  const indexSrc = readFileSync(join(SRC, "index.ts"), "utf8");
+  const specsSrc = readFileSync(join(SRC, "tool-specs.ts"), "utf8");
+  const names = new Set();
+  for (const m of indexSrc.matchAll(/registerTool\(\s*"([a-z0-9_]+)"/g)) {
+    names.add(m[1]);
+  }
+  for (const m of specsSrc.matchAll(/mcpName:\s*['"]([a-z0-9_]+)['"]/g)) {
+    names.add(m[1]);
+  }
+  return names;
+}
+
+test("every registered tool is mentioned in SERVER_INSTRUCTIONS", () => {
+  const names = registeredToolNames();
+  // Sanity: if extraction regressed (regex drift), fail loudly rather than
+  // vacuously passing on an empty set.
+  assert.ok(
+    names.size >= 40,
+    `sanity: expected to extract 40+ registered tools, got ${names.size} — ` +
+      "the extraction regexes in this test likely drifted from the source",
+  );
+  const missing = [...names]
+    .filter((n) => !EXCEPTIONS.has(n))
+    // \b<name>\b: `_` is a word char, so \bget_page\b does NOT match inside
+    // get_page_json — a tool can't hide behind a longer sibling's mention.
+    .filter((n) => !new RegExp(`\\b${n}\\b`).test(SERVER_INSTRUCTIONS))
+    .sort();
+  assert.deepEqual(
+    missing,
+    [],
+    `tools missing from SERVER_INSTRUCTIONS: ${missing.join(", ")} — ` +
+      "update the guide in packages/mcp/src/index.ts (see its MAINTENANCE " +
+      "RULE comment), or add a justified entry to EXCEPTIONS here",
+  );
+});
+
+test("EXCEPTIONS entries are real registered tools", () => {
+  // A stale exception (tool renamed/removed) must be cleaned up, otherwise
+  // the list quietly grows past its purpose.
+  const names = registeredToolNames();
+  for (const name of EXCEPTIONS) {
+    assert.ok(
+      names.has(name),
+      `EXCEPTIONS entry "${name}" is not a registered tool — remove it`,
+    );
+  }
+});

packages/prosemirror-markdown/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@docmost/prosemirror-markdown",
+  "version": "0.1.0",
+  "description": "Pure ProseMirror <-> Markdown converter + schema mirror (headless, framework-free).",
+  "private": true,
+  "type": "module",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@tiptap/core": "3.20.4",
+    "@tiptap/extension-highlight": "3.20.4",
+    "@tiptap/extension-image": "3.20.4",
+    "@tiptap/extension-subscript": "3.20.4",
+    "@tiptap/extension-superscript": "3.20.4",
+    "@tiptap/extension-task-item": "3.20.4",
+    "@tiptap/extension-task-list": "3.20.4",
+    "@tiptap/html": "3.20.4",
+    "@tiptap/pm": "3.20.4",
+    "@tiptap/starter-kit": "3.20.4",
+    "jsdom": "25.0.0",
+    "marked": "17.0.5",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@docmost/editor-ext": "workspace:*",
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^20.0.0",
+    "fast-check": "^4.8.0",
+    "typescript": "^5.0.0",
+    "vitest": "4.1.6"
+  }
+}

packages/prosemirror-markdown/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Public surface of `@docmost/prosemirror-markdown`.
+ *
+ * A headless, framework-free ProseMirror <-> Markdown converter plus the
+ * Docmost schema mirror. Everything lives under `lib/` (the converter core);
+ * this top-level barrel simply re-exports that surface so the package entry is
+ * the converter surface.
+ */
+export * from "./lib/index.js";

packages/prosemirror-markdown/src/lib/index.ts

@@ -19,6 +19,11 @@ export { convertProseMirrorToMarkdown } from "./markdown-converter.js";
 
 export { markdownToProseMirror } from "./markdown-to-prosemirror.js";
 
+// The Docmost tiptap schema mirror. Exposed so consumers (and the sync
+// engine's schema-validity regression tests) can build the exact ProseMirror
+// schema the converter targets.
+export { docmostExtensions } from "./docmost-schema.js";
+
 export {
   canonicalizeContent,
   docsCanonicallyEqual,

packages/prosemirror-markdown/test/roundtrip-helpers.ts

@@ -0,0 +1,75 @@
+/**
+ * Pure, IO-free comparison helpers for the idempotency round-trip checks. The
+ * round-trip harness that drives these lives in the package's tests, not in the
+ * engine.
+ */
+
+/**
+ * Recursively strip every `attrs.id` from a ProseMirror node tree. Block ids
+ * are regenerated by `markdownToProseMirror` (SPEC §11), so they must be
+ * ignored when comparing the semantic shape of two documents. Returns a NEW
+ * tree; the input is not mutated.
+ */
+export function stripBlockIds(node: any): any {
+  if (Array.isArray(node)) {
+    return node.map(stripBlockIds);
+  }
+  if (node && typeof node === "object") {
+    const out: any = {};
+    for (const key of Object.keys(node)) {
+      if (key === "attrs" && node.attrs && typeof node.attrs === "object") {
+        // Drop the `id` attr; keep every other attribute.
+        const { id, ...rest } = node.attrs as Record<string, unknown>;
+        void id;
+        out.attrs = stripBlockIds(rest);
+      } else {
+        out[key] = stripBlockIds(node[key]);
+      }
+    }
+    return out;
+  }
+  return node;
+}
+
+/**
+ * Find the first divergence between two values via a recursive deep compare.
+ * Returns a short path + the two differing values, or null if they are equal.
+ */
+export function firstDivergence(
+  a: any,
+  b: any,
+  path = "$",
+): { path: string; a: any; b: any } | null {
+  if (a === b) return null;
+
+  const ta = typeof a;
+  const tb = typeof b;
+  if (ta !== tb || a === null || b === null) {
+    return { path, a, b };
+  }
+  if (ta !== "object") {
+    return { path, a, b };
+  }
+
+  const aIsArr = Array.isArray(a);
+  const bIsArr = Array.isArray(b);
+  if (aIsArr !== bIsArr) return { path, a, b };
+
+  if (aIsArr) {
+    if (a.length !== b.length) {
+      return { path: `${path}.length`, a: a.length, b: b.length };
+    }
+    for (let i = 0; i < a.length; i++) {
+      const d = firstDivergence(a[i], b[i], `${path}[${i}]`);
+      if (d) return d;
+    }
+    return null;
+  }
+
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const k of keys) {
+    const d = firstDivergence(a[k], b[k], `${path}.${k}`);
+    if (d) return d;
+  }
+  return null;
+}

packages/prosemirror-markdown/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./build",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}

packages/prosemirror-markdown/tsconfig.vitest.json

@@ -0,0 +1,15 @@
+{
+  // Test-infra tsconfig used ONLY by vitest's `test.typecheck` pass (Finding #1).
+  // The build tsconfig (`tsconfig.json`) scopes the compiler to `src/**` with
+  // `rootDir: ./src`, so it never type-checks the `test/` tree. This config
+  // inherits the same strict compiler options but widens the file set to the
+  // type-test files so `vitest run` can run `tsc` over them. It is NOT used by
+  // `npm run build` (that still uses `tsconfig.json`), so it has no effect on the
+  // shipped output.
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": ["test/**/*.test-d.ts", "src/**/*"]
+}

packages/prosemirror-markdown/vitest.config.ts

@@ -0,0 +1,40 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { defineConfig } from 'vitest/config';
+
+// Ported docmost-sync tests import the converter through the upstream package
+// barrel specifier `docmost-client`. We vendored only the PURE half of that
+// package into `src/lib`, so alias the barrel specifier to our local lib
+// barrel; everything those tests use (converter, canonicalize, markdown
+// envelope, markdownToProseMirror) is re-exported there.
+const here = path.dirname(fileURLToPath(import.meta.url));
+const libBarrel = path.resolve(here, 'src/lib/index.ts');
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      'docmost-client': libBarrel,
+    },
+  },
+  test: {
+    environment: 'node',
+    // Runtime suites. The `.test.ts` glob deliberately EXCLUDES the type-only
+    // contract file (`*.test-d.ts`), which is enforced by the typecheck pass
+    // below instead — so the 35 runtime suites are never typechecked.
+    include: ['test/**/*.test.ts'],
+    // Type-level contract enforcement (Finding #1). Vitest runs `tsc` over the
+    // `.test-d.ts` files so the `expectTypeOf`/`@ts-expect-error` guards in
+    // git-sync-client.contract.test-d.ts become REAL build-time assertions: a
+    // drift in the GitSyncClient result shapes makes `npx vitest run` FAIL with
+    // a type error. Scoped to `*.test-d.ts` so the runtime suites stay
+    // untouched, and pointed at the package tsconfig for the strict options.
+    typecheck: {
+      enabled: true,
+      include: ['test/**/*.test-d.ts'],
+      // A dedicated test-infra tsconfig (NOT the build one) that widens the file
+      // set to include `test/**` — the build tsconfig scopes `tsc` to `src/**`
+      // (rootDir ./src), so without this the type-test file is never checked.
+      tsconfig: './tsconfig.vitest.json',
+    },
+  },
+});

pnpm-lock.yaml

@@ -889,6 +889,9 @@ importers:
 
   packages/git-sync:
     dependencies:
+      '@docmost/prosemirror-markdown':
+        specifier: workspace:*
+        version: link:../prosemirror-markdown
       '@tiptap/core':
         specifier: 3.20.4
         version: 3.20.4(@tiptap/pm@3.20.4)
@@ -1030,6 +1033,67 @@ importers:
         specifier: ^5.0.0
         version: 5.9.3
 
+  packages/prosemirror-markdown:
+    dependencies:
+      '@tiptap/core':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/pm@3.20.4)
+      '@tiptap/extension-highlight':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))
+      '@tiptap/extension-image':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))
+      '@tiptap/extension-subscript':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))(@tiptap/pm@3.20.4)
+      '@tiptap/extension-superscript':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))(@tiptap/pm@3.20.4)
+      '@tiptap/extension-task-item':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/extension-list@3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))(@tiptap/pm@3.20.4))
+      '@tiptap/extension-task-list':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/extension-list@3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))(@tiptap/pm@3.20.4))
+      '@tiptap/html':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))(@tiptap/pm@3.20.4)(happy-dom@20.8.9)
+      '@tiptap/pm':
+        specifier: 3.20.4
+        version: 3.20.4
+      '@tiptap/starter-kit':
+        specifier: 3.20.4
+        version: 3.20.4
+      jsdom:
+        specifier: 25.0.0
+        version: 25.0.0
+      marked:
+        specifier: 17.0.5
+        version: 17.0.5
+      zod:
+        specifier: 4.3.6
+        version: 4.3.6
+    devDependencies:
+      '@docmost/editor-ext':
+        specifier: workspace:*
+        version: link:../editor-ext
+      '@types/jsdom':
+        specifier: ^21.1.7
+        version: 21.1.7
+      '@types/node':
+        specifier: ^20.0.0
+        version: 20.19.43
+      fast-check:
+        specifier: ^4.8.0
+        version: 4.8.0
+      typescript:
+        specifier: ^5.0.0
+        version: 5.9.3
+      vitest:
+        specifier: 4.1.6
+        version: 4.1.6(@opentelemetry/api@1.9.0)(@types/node@20.19.43)(happy-dom@20.8.9)(jsdom@25.0.0)(vite@8.0.5(@types/node@20.19.43)(esbuild@0.28.0)(jiti@2.4.2)(less@4.2.0)(sugarss@5.0.1(postcss@8.5.14))(terser@5.39.0)(tsx@4.21.0)(yaml@2.8.3))
+
 packages:
 
   '@aashutoshrathi/word-wrap@1.2.6':