fix(#345): normalize CRLF before front-matter strip (review round 3)

F9 [WARNING] The line-anchored front-matter regex from round 2 requires a bare
LF after the opening `---`, so a Windows/CRLF foreign file (`---\r\n...`) slips
past the strip and leaks its front-matter into the body (where `title: Foo`
renders as a setext heading that title extraction hijacks). The canonical parser
whose regex shape this copied (page-file.ts) normalizes CRLF -> LF BEFORE its
FRONTMATTER_RE; the import path copied the regex but missed the normalization.
normalizeForeignMarkdown now replaces CRLF with LF first (which also makes
convertReferenceFootnotes' split('\n') consistent). Adds a CRLF fixture.

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

AGENTS.md

@@ -201,7 +201,7 @@ pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Four workspace packages:
 | `apps/client` | `client` | React 18 + Vite + Mantine 8 + TanStack Query + Jotai | SPA frontend |
 | `packages/editor-ext` | `@docmost/editor-ext` | Tiptap/ProseMirror | Shared Tiptap node/mark extensions, imported by both the client and the server |
 | `packages/mcp` | `@docmost/mcp` | MCP SDK, Tiptap, Yjs | Standalone MCP server, also bundled into the server at `/mcp`. Consumes the shared converter/schema from `@docmost/prosemirror-markdown` (#293) — it no longer carries its own vendored converter/schema copy |
-| `packages/prosemirror-markdown` | `@docmost/prosemirror-markdown` | Tiptap, marked, jsdom | The single, canonical ProseMirror↔Markdown converter + Docmost schema mirror (#293). Consumed by `mcp` and `git-sync`; there is exactly ONE copy of the converter now |
+| `packages/prosemirror-markdown` | `@docmost/prosemirror-markdown` | Tiptap, marked, jsdom | The single, canonical ProseMirror↔Markdown converter + Docmost schema mirror (#293). Consumed by `mcp`, `git-sync`, AND `apps/server` (server-side markdown import/export, #345); there is exactly ONE copy of the converter now |
 
 `build` targets are Nx-cached and dependency-ordered (`dependsOn: ["^build"]`), so `editor-ext` builds before the apps. `nx.json` sets `affected.defaultBase: main`.
 
@@ -284,7 +284,7 @@ The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes
 ### Client structure
 Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirrors the server domains: `page`, `space`, `comment`, `ai-chat`, `editor`, …). Conventions:
 - **TanStack Query** for server state (one `queries/` file per feature), **Jotai** atoms for local/shared UI state, **Mantine 8** + CSS modules (`*.module.css`) + `postcss-preset-mantine` for UI.
-- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, import/export) — editor schema changes often need to be made in `editor-ext`, not just the client. The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by both `mcp` and `git-sync` — do NOT reintroduce a per-package copy. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence.
+- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, schema, `canonicalizeFootnotes`) — editor schema changes often need to be made in `editor-ext`, not just the client. Server-side markdown import/export no longer lives in `editor-ext`: it goes through the canonical converter (#345, see below). The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by `mcp`, `git-sync`, and `apps/server` (#345) — do NOT reintroduce a per-package copy. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence.
 - API access goes through `apps/client/src/lib/api-client.ts` (axios). The `@` alias maps to `apps/client/src`.
 - Runtime config is injected at build time by `vite.config.ts` via `define` (`APP_URL`, `COLLAB_URL`, `APP_VERSION`, …) — these come from the root `.env`, not from `import.meta.env`.
 

apps/server/package.json

@@ -23,7 +23,7 @@
     "migration:reset": "tsx src/database/migrate.ts down-to NO_MIGRATIONS",
     "migration:codegen": "kysely-codegen --dialect=postgres --camel-case --env-file=../../.env --out-file=./src/database/types/db.d.ts",
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
-    "pretest": "pnpm --filter @docmost/editor-ext build",
+    "pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/prosemirror-markdown build",
     "test": "jest",
     "test:int": "jest --config test/jest-integration.json",
     "test:watch": "jest --watch",
@@ -43,6 +43,7 @@
     "@clickhouse/client": "^1.18.2",
     "@docmost/mcp": "workspace:*",
     "@docmost/pdf-inspector": "1.9.6",
+    "@docmost/prosemirror-markdown": "workspace:*",
     "@fastify/cookie": "^11.0.2",
     "@fastify/multipart": "^10.0.0",
     "@fastify/static": "^9.1.3",
@@ -175,7 +176,7 @@
       "/node_modules/"
     ],
     "transform": {
-      "happy-dom.+\\.js$": [
+      "(happy-dom.+|prosemirror-markdown/build/.+)\\.js$": [
         "babel-jest",
         {
           "presets": [
@@ -193,7 +194,7 @@
       "^.+\\.(t|j)sx?$": "ts-jest"
     },
     "transformIgnorePatterns": [
-      "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0)(@|/))"
+      "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0|@docmost/prosemirror-markdown)(@|/))"
     ],
     "collectCoverageFrom": [
       "**/*.(t|j)s"
@@ -204,7 +205,8 @@
       "^@docmost/db/(.*)$": "<rootDir>/database/$1",
       "^@docmost/transactional/(.*)$": "<rootDir>/integrations/transactional/$1",
       "^@docmost/ee/(.*)$": "<rootDir>/ee/$1",
-      "^src/(.*)$": "<rootDir>/$1"
+      "^src/(.*)$": "<rootDir>/$1",
+      "^@tiptap/react$": "<rootDir>/../test/stubs/tiptap-react.js"
     }
   }
 }

apps/server/src/collaboration/collaboration.util.ts

@@ -43,7 +43,6 @@ import {
   Column,
   Status,
   addUniqueIdsToDoc,
-  htmlToMarkdown,
   TransclusionSource,
   TransclusionReference,
   FootnoteReference,
@@ -51,6 +50,7 @@ import {
   FootnoteDefinition,
   PageEmbed,
 } from '@docmost/editor-ext';
+import { convertProseMirrorToMarkdown } from '@docmost/prosemirror-markdown';
 import { generateText, getSchema, JSONContent } from '@tiptap/core';
 import { generateHTML, generateJSON } from '../common/helpers/prosemirror/html';
 // @tiptap/html library works best for generating prosemirror json state but not HTML
@@ -239,6 +239,10 @@ export function prosemirrorNodeToYElement(node: any): Y.XmlElement | Y.XmlText {
 }
 
 export function jsonToMarkdown(tiptapJson: any): string {
-  const html = jsonToHtml(tiptapJson);
-  return htmlToMarkdown(html);
+  // Direct ProseMirror JSON -> Markdown via the canonical converter
+  // (`@docmost/prosemirror-markdown`) — no HTML intermediate, no second
+  // editor-ext markdown layer. Same serializer as the page/space export and the
+  // git-sync vault writer, so every server PM->MD path emits identical canonical
+  // markdown (issue #345).
+  return convertProseMirrorToMarkdown(tiptapJson);
 }

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

@@ -539,115 +539,3 @@ describe('AiChatToolsService model-friendly input validation (#190)', () => {
     expect(result.error?.message).toContain('parameter "pageId": missing (required)');
   });
 });
-
-/**
- * #294 F1 — the contract-parity test introspects only the ADVERTISED schema keys
- * (buildShape), not the execute bodies. Most execs are unchanged pass-throughs,
- * but two wirings actually CHANGED in the migration and are otherwise untested:
- *   - movePage now forwards the newly-added optional `position` field to the
- *     client (client.movePage(pageId, parentPageId, position));
- *   - the table trio unified its `tableRef` param to `table` and must forward it
- *     positionally. A field destructured under the wrong name would silently pass
- *     `undefined` to the client (execute is `any`-cast, so tsc won't catch it).
- */
-describe('AiChatToolsService #294 changed execute wirings', () => {
-  const calls: Record<string, unknown[][]> = {
-    movePage: [],
-    tableInsertRow: [],
-    tableDeleteRow: [],
-    tableUpdateCell: [],
-  };
-  const fakeClient: Partial<DocmostClientLike> = {
-    movePage: (...args: unknown[]) => {
-      calls.movePage.push(args);
-      return Promise.resolve({ success: true });
-    },
-    tableInsertRow: (...args: unknown[]) => {
-      calls.tableInsertRow.push(args);
-      return Promise.resolve({ ok: true });
-    },
-    tableDeleteRow: (...args: unknown[]) => {
-      calls.tableDeleteRow.push(args);
-      return Promise.resolve({ ok: true });
-    },
-    tableUpdateCell: (...args: unknown[]) => {
-      calls.tableUpdateCell.push(args);
-      return Promise.resolve({ ok: true });
-    },
-  };
-  const tokenServiceStub = {
-    generateAccessToken: jest.fn().mockResolvedValue('access-token'),
-    generateCollabToken: jest.fn().mockResolvedValue('collab-token'),
-  };
-  let service: AiChatToolsService;
-
-  beforeEach(() => {
-    for (const k of Object.keys(calls)) calls[k].length = 0;
-    jest.spyOn(loader, 'loadDocmostMcp').mockResolvedValue(
-      mockLoaded(function () {
-        return fakeClient as DocmostClientLike;
-      } as unknown as loader.DocmostClientCtor),
-    );
-    service = new AiChatToolsService(
-      tokenServiceStub as never,
-      {} as never,
-      {} as never,
-      {} as never,
-      {} as never,
-      {
-        asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
-      } as never,
-    );
-  });
-  afterEach(() => jest.restoreAllMocks());
-
-  const buildTools = () =>
-    service.forUser(
-      { id: 'user-1', email: 'u@example.com', workspaceId: 'ws-1' } as never,
-      'session-1',
-      'ws-1',
-      'chat-1',
-    );
-
-  it('movePage forwards the optional position to the client', async () => {
-    const tools = await buildTools();
-    await tools.movePage.execute(
-      { pageId: 'p1', parentPageId: 'parent1', position: 'a5' } as never,
-      {} as never,
-    );
-    expect(calls.movePage).toEqual([['p1', 'parent1', 'a5']]);
-  });
-
-  it('movePage passes undefined position and null parent when omitted (unchanged behavior)', async () => {
-    const tools = await buildTools();
-    await tools.movePage.execute({ pageId: 'p2' } as never, {} as never);
-    expect(calls.movePage).toEqual([['p2', null, undefined]]);
-  });
-
-  it('tableInsertRow forwards the unified `table` param positionally', async () => {
-    const tools = await buildTools();
-    await tools.tableInsertRow.execute(
-      { pageId: 'p1', table: '#0', cells: ['a', 'b'], index: 2 } as never,
-      {} as never,
-    );
-    expect(calls.tableInsertRow).toEqual([['p1', '#0', ['a', 'b'], 2]]);
-  });
-
-  it('tableDeleteRow forwards `table` positionally', async () => {
-    const tools = await buildTools();
-    await tools.tableDeleteRow.execute(
-      { pageId: 'p1', table: '#0', index: 1 } as never,
-      {} as never,
-    );
-    expect(calls.tableDeleteRow).toEqual([['p1', '#0', 1]]);
-  });
-
-  it('tableUpdateCell forwards `table` positionally', async () => {
-    const tools = await buildTools();
-    await tools.tableUpdateCell.execute(
-      { pageId: 'p1', table: '#0', row: 1, col: 2, text: 'x' } as never,
-      {} as never,
-    );
-    expect(calls.tableUpdateCell).toEqual([['p1', '#0', 1, 2, 'x']]);
-  });
-});

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

@@ -316,27 +316,50 @@ export class AiChatToolsService {
         execute: async () => resolveCurrentPageResult(openedPage),
       }),
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      // The execute body keeps this layer's { title, markdown } projection.
-      getPage: sharedTool(sharedToolSpecs.getPage, async ({ pageId }) => {
-        // getPage(pageId) -> { data: filterPage(page, markdown), success }.
-        const result = await client.getPage(pageId);
-        const data = (result?.data ?? {}) as {
-          title?: string;
-          content?: string;
-        };
-        return {
-          title: data.title ?? '',
-          markdown: typeof data.content === 'string' ? data.content : '',
-        };
+      getPage: tool({
+        description:
+          'Fetch a single page as Markdown by its page id. Returns the page ' +
+          '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.'),
+        }),
+        execute: async ({ pageId }) => {
+          // getPage(pageId) -> { data: filterPage(page, markdown), success }.
+          const result = await client.getPage(pageId);
+          const data = (result?.data ?? {}) as {
+            title?: string;
+            content?: string;
+          };
+          return {
+            title: data.title ?? '',
+            markdown: typeof data.content === 'string' ? data.content : '',
+          };
+        },
       }),
 
       // --- WRITE tools (all reversible — history/trash; §6.5 / D3) ---
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      createPage: sharedTool(
-        sharedToolSpecs.createPage,
-        async ({ title, content, spaceId, parentPageId }) => {
+      createPage: tool({
+        description:
+          'Create a new page with a Markdown body in a space, optionally under ' +
+          'a parent page. Returns the new page id and title. Reversible: a page ' +
+          'can be moved to trash later.',
+        inputSchema: modelFriendlyInput({
+          title: z.string().describe('The title of the new page.'),
+          content: z
+            .string()
+            .describe('The page body as Markdown (may be empty).'),
+          spaceId: z
+            .string()
+            .describe('The id of the space to create the page in.'),
+          parentPageId: z
+            .string()
+            .optional()
+            .describe('Optional parent page id to nest the new page under.'),
+        }),
+        execute: async ({ title, content, spaceId, parentPageId }) => {
           // createPage(title, content, spaceId, parentPageId?) ->
           // { data: filterPage(page, markdown), success }.
           const result = await client.createPage(
@@ -352,7 +375,7 @@ export class AiChatToolsService {
           };
           return { id: data.id ?? data.slugId, title: data.title ?? title };
         },
-      ),
+      }),
 
       updatePageContent: tool({
         description:
@@ -376,46 +399,115 @@ export class AiChatToolsService {
         },
       }),
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      renamePage: sharedTool(
-        sharedToolSpecs.renamePage,
-        async ({ pageId, title }) => {
+      renamePage: tool({
+        description:
+          "Rename a page (change its title only; the body is untouched). " +
+          'Reversible: rename back at any time.',
+        inputSchema: modelFriendlyInput({
+          pageId: z.string().describe('The id of the page to rename.'),
+          title: z.string().describe('The new title.'),
+        }),
+        execute: async ({ pageId, title }) => {
           // renamePage(pageId, title) -> { success, pageId, title }.
           await client.renamePage(pageId, title);
           return { pageId, title };
         },
-      ),
-
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      // The shared schema adds the optional `position` field this layer lacked
-      // before; the execute now forwards it (the client already accepted it).
-      movePage: sharedTool(
-        sharedToolSpecs.movePage,
-        async ({ pageId, parentPageId, position }) => {
-          // movePage(pageId, parentPageId, position?) -> raw move response.
-          await client.movePage(pageId, parentPageId ?? null, position);
-          return { pageId, parentPageId: parentPageId ?? null, moved: true };
-        },
-      ),
-
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      // GUARDRAIL (§14 H4) preserved: the shared schema exposes ONLY pageId, so
-      // permanentlyDelete/forceDelete are never part of the input and can never
-      // be forwarded — the agent physically cannot permanently delete a page.
-      deletePage: sharedTool(sharedToolSpecs.deletePage, async ({ pageId }) => {
-        // deletePage(pageId) hits POST /pages/delete with { pageId } only,
-        // which is the soft-delete (trash) path on the server.
-        await client.deletePage(pageId);
-        return { pageId, trashed: true };
       }),
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      // This layer keeps only its own execute-side guards (require a selection
-      // for a top-level comment; reject suggestedText on a reply / without a
-      // selection) — the schema+description are shared.
-      createComment: sharedTool(
-        sharedToolSpecs.createComment,
-        async ({
+      movePage: tool({
+        description:
+          'Move a page under a new parent page, or to the space root when no ' +
+          'parent is given. Reversible: move it back at any time.',
+        inputSchema: modelFriendlyInput({
+          pageId: z.string().describe('The id of the page to move.'),
+          parentPageId: z
+            .string()
+            .nullable()
+            .optional()
+            .describe(
+              'Target parent page id. Null/omitted moves the page to the ' +
+                'space root.',
+            ),
+        }),
+        execute: async ({ pageId, parentPageId }) => {
+          // movePage(pageId, parentPageId, position?) -> raw move response.
+          await client.movePage(pageId, parentPageId ?? null);
+          return { pageId, parentPageId: parentPageId ?? null, moved: true };
+        },
+      }),
+
+      deletePage: tool({
+        description:
+          'Move a page to the trash (SOFT delete only — fully reversible; the ' +
+          'page can be restored from trash). This NEVER permanently deletes.',
+        inputSchema: modelFriendlyInput({
+          pageId: z.string().describe('The id of the page to move to trash.'),
+        }),
+        // GUARDRAIL (§14 H4): the only field ever passed to the client is
+        // pageId. permanentlyDelete/forceDelete are not part of the schema and
+        // are never forwarded, so the agent physically cannot permanently
+        // delete a page through this tool.
+        execute: async ({ pageId }) => {
+          // deletePage(pageId) hits POST /pages/delete with { pageId } only,
+          // which is the soft-delete (trash) path on the server.
+          await client.deletePage(pageId);
+          return { pageId, trashed: true };
+        },
+      }),
+
+      // INTENTIONAL per-transport divergence (not shared): the description is
+      // tuned for the in-app agent (e.g. "retry with a corrected EXACT selection"
+      // and "Reversible via the comment UI"); the standalone MCP `create_comment`
+      // keeps its own wording. Kept per-layer.
+      createComment: tool({
+        description:
+          'Add an INLINE comment to a page, or reply to an existing top-level ' +
+          'comment (one level only — the backend rejects replies to replies). ' +
+          'The comment is anchored inline to the given exact `selection` text ' +
+          '(which gets highlighted); page-level comments are NOT supported. A ' +
+          "new top-level comment REQUIRES a `selection`. Replies inherit the " +
+          "parent's anchor and take no selection. If the call fails with a " +
+          '"selection not found" error, retry with a corrected EXACT selection ' +
+          'copied verbatim from a single paragraph/block. You may also attach a ' +
+          '`suggestedText` proposing a replacement for the `selection` (a human ' +
+          'applies it from the UI); when set, the `selection` must occur exactly ' +
+          'once in the page. Reversible via the comment UI.',
+        inputSchema: modelFriendlyInput({
+          pageId: z.string().describe('The id of the page to comment on.'),
+          content: z.string().describe('The comment body as Markdown.'),
+          selection: z
+            .string()
+            .min(1)
+            .max(250)
+            .optional()
+            .describe(
+              'EXACT contiguous text from a SINGLE paragraph/block to anchor ' +
+                '(highlight) the comment on (<=250 chars, avoid spanning across ' +
+                'formatting boundaries). Required for a new top-level comment; ' +
+                'omit only when replying via parentCommentId.',
+            ),
+          parentCommentId: z
+            .string()
+            .optional()
+            .describe(
+              'Optional id of a TOP-LEVEL comment to reply to (one level ' +
+                'of replies only).',
+            ),
+          suggestedText: z
+            .string()
+            .min(1)
+            .max(2000)
+            .optional()
+            .describe(
+              'Optional proposed replacement (PLAIN TEXT) for the `selection`, ' +
+                'applied by a human via the UI (never auto-applied). REQUIRES a ' +
+                '`selection`; NOT allowed on a reply. When set, the `selection` ' +
+                'must be UNIQUE in the page — expand it with surrounding context ' +
+                '(still <=250 chars) if it occurs more than once, or the call is ' +
+                'refused.',
+            ),
+        }),
+        execute: async ({
           pageId,
           content,
           selection,
@@ -456,17 +548,26 @@ export class AiChatToolsService {
           const data = (result?.data ?? {}) as { id?: string };
           return { commentId: data.id, pageId };
         },
-      ),
+      }),
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      resolveComment: sharedTool(
-        sharedToolSpecs.resolveComment,
-        async ({ commentId, resolved }) => {
+      resolveComment: tool({
+        description:
+          'Resolve or reopen a top-level comment thread (reversible — toggle ' +
+          'the resolved flag). Only top-level comments can be resolved.',
+        inputSchema: modelFriendlyInput({
+          commentId: z
+            .string()
+            .describe('The id of the top-level comment to resolve/reopen.'),
+          resolved: z
+            .boolean()
+            .describe('true to resolve the thread, false to reopen it.'),
+        }),
+        execute: async ({ commentId, resolved }) => {
           // resolveComment(commentId, resolved) -> { success, commentId, resolved }.
           await client.resolveComment(commentId, resolved);
           return { commentId, resolved };
         },
-      ),
+      }),
 
       // --- READ tools (added) ---
 
@@ -484,12 +585,33 @@ export class AiChatToolsService {
       // hierarchy mode but is worded for the in-app agent; the standalone MCP
       // `list_pages` carries its own wording. Kept per-layer so each side tunes
       // its own guidance.
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      listPages: sharedTool(
-        sharedToolSpecs.listPages,
-        async ({ spaceId, limit, tree }) =>
+      listPages: tool({
+        description:
+          'List the most recent pages, optionally scoped to a single space. ' +
+          'Returns a bounded list (default 50, max 100). Pass tree:true (with ' +
+          "spaceId) to instead get the space's full page hierarchy as a nested tree.",
+        inputSchema: modelFriendlyInput({
+          spaceId: z
+            .string()
+            .optional()
+            .describe('Optional space id to scope the listing to.'),
+          limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe('Maximum number of pages (1-100).'),
+          tree: z
+            .boolean()
+            .optional()
+            .describe(
+              'When true, return the full page hierarchy of the given space as a nested tree (children arrays) instead of the recent-pages flat list. Requires spaceId; ignores limit.',
+            ),
+        }),
+        execute: async ({ spaceId, limit, tree }) =>
           await client.listPages(spaceId, limit, tree),
-      ),
+      }),
 
       listSidebarPages: tool({
         description:
@@ -534,34 +656,41 @@ export class AiChatToolsService {
           }),
       ),
 
-      // NOT shared (kept inline): the MCP tool name `table_get` is noun-first
-      // while this key is `getTable` (verb-first), breaking the
-      // snake_case(inAppKey) convention the shared registry enforces. Its
-      // reference parameter is still named `table` (was `tableRef`) so it matches
-      // the migrated table row/cell tools below.
       getTable: tool({
         description:
           'Read a table as a matrix of cell texts (plus a parallel cellIds ' +
           'matrix so cells can be addressed for rich edits).',
         inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page.'),
-          table: z
+          tableRef: z
             .string()
             .describe(
-              '"#<index>" from the page outline, or a block id of any node ' +
-                'inside the table.',
+              '"#<index>" from getOutline, or a block id of any node inside ' +
+                'the table.',
             ),
         }),
-        execute: async ({ pageId, table }) =>
-          await client.getTable(pageId, table),
+        execute: async ({ pageId, tableRef }) =>
+          await client.getTable(pageId, tableRef),
       }),
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      listComments: sharedTool(
-        sharedToolSpecs.listComments,
-        async ({ pageId, includeResolved }) =>
+      listComments: tool({
+        description:
+          'List comments on a page in one call. By DEFAULT only ACTIVE ' +
+          'threads are returned; resolved threads (a resolved top-level ' +
+          'comment and all its replies) are hidden and their count reported ' +
+          'as `resolvedThreadsHidden` so you can re-query with ' +
+          '`includeResolved: true` to see everything. Returns ' +
+          '`{ items, resolvedThreadsHidden }`. Content is returned as Markdown.',
+        inputSchema: modelFriendlyInput({
+          pageId: z.string().describe('The id of the page.'),
+          includeResolved: z
+            .boolean()
+            .optional()
+            .describe('default only active threads; true — include resolved'),
+        }),
+        execute: async ({ pageId, includeResolved }) =>
           await client.listComments(pageId, includeResolved),
-      ),
+      }),
 
       getComment: tool({
         description: 'Fetch a single comment by id (content as Markdown).',
@@ -571,12 +700,26 @@ export class AiChatToolsService {
         execute: async ({ commentId }) => await client.getComment(commentId),
       }),
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      checkNewComments: sharedTool(
-        sharedToolSpecs.checkNewComments,
-        async ({ spaceId, since, parentPageId }) =>
+      checkNewComments: tool({
+        description:
+          'Find new comments across a space (optionally scoped to a subtree) ' +
+          'created after a given timestamp.',
+        inputSchema: modelFriendlyInput({
+          spaceId: z.string().describe('The id of the space to scan.'),
+          since: z
+            .string()
+            .describe('An ISO-8601 timestamp; only comments created after it.'),
+          parentPageId: z
+            .string()
+            .optional()
+            .describe(
+              'Optional page id to scope the scan to that page and its ' +
+                'descendants.',
+            ),
+        }),
+        execute: async ({ spaceId, since, parentPageId }) =>
           await client.checkNewComments(spaceId, since, parentPageId),
-      ),
+      }),
 
       listShares: sharedTool(
         sharedToolSpecs.listShares,
@@ -606,14 +749,19 @@ export class AiChatToolsService {
           await client.diffPageVersions(pageId, from, to),
       ),
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      exportPageMarkdown: sharedTool(
-        sharedToolSpecs.exportPageMarkdown,
-        async ({ pageId }) => {
+      exportPageMarkdown: tool({
+        description:
+          'Export a page to a single self-contained Docmost-flavoured ' +
+          'Markdown file (meta + body + comment threads). Lossless round-trip ' +
+          'with importPageMarkdown.',
+        inputSchema: modelFriendlyInput({
+          pageId: z.string().describe('The id of the page to export.'),
+        }),
+        execute: async ({ pageId }) => {
           const markdown = await client.exportPageMarkdown(pageId);
           return { markdown };
         },
-      ),
+      }),
 
       // --- WRITE tools (added; reversible via page history/trash) ---
 
@@ -663,12 +811,28 @@ export class AiChatToolsService {
         async ({ pageId, nodeId }) => await client.deleteNode(pageId, nodeId),
       ),
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      // The execute body keeps this layer's content normalization (parity with
-      // the standalone MCP server, index.ts update_page_json).
-      updatePageJson: sharedTool(
-        sharedToolSpecs.updatePageJson,
-        async ({ pageId, content, title }) => {
+      updatePageJson: tool({
+        description:
+          "Replace a page's body with a full ProseMirror document — a full " +
+          'overwrite — and/or update its title. Minimal example content: ' +
+          '{"type":"doc","content":[{"type":"paragraph","content":' +
+          '[{"type":"text","text":"Hi"}]}]}. The content arg may be a JSON ' +
+          'object or a JSON string (both accepted). Omit content for a ' +
+          'title-only update. Reversible: the previous version is kept in page ' +
+          'history.',
+        inputSchema: modelFriendlyInput({
+          pageId: z.string().describe('The id of the page to update.'),
+          content: z
+            .any()
+            .optional()
+            .describe(
+              'Full ProseMirror doc {"type":"doc","content":[...]} (JSON ' +
+                'object or JSON string); omit for a title-only update.',
+            ),
+          title: z.string().optional().describe('Optional new title.'),
+        }),
+        execute: async ({ pageId, content, title }) => {
+          // Parity with the standalone MCP server (index.ts update_page_json):
           // undefined/null pass through as undefined (title-only / no-op); any
           // string is JSON.parsed (so an empty string "" throws, matching the
           // MCP server); an object is passed through unchanged.
@@ -681,29 +845,66 @@ export class AiChatToolsService {
           }
           return await client.updatePageJson(pageId, doc, title);
         },
-      ),
+      }),
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      // The table reference parameter was unified to `table` (was `tableRef`).
-      tableInsertRow: sharedTool(
-        sharedToolSpecs.tableInsertRow,
-        async ({ pageId, table, cells, index }) =>
-          await client.tableInsertRow(pageId, table, cells, index),
-      ),
+      // NOT in the shared registry: this layer names the table argument
+      // `tableRef`, while the standalone MCP tool names it `table` (index.ts).
+      // Sharing one buildShape would rename a model-facing parameter on one
+      // transport, so the table row/cell tools stay per-layer by design.
+      tableInsertRow: tool({
+        description:
+          'Insert a row of plain-text cells into a table. Reversible via ' +
+          'page history.',
+        inputSchema: modelFriendlyInput({
+          pageId: z.string().describe('The id of the page.'),
+          tableRef: z
+            .string()
+            .describe('"#<index>" from getOutline, or a block id in the table.'),
+          cells: z.array(z.string()).describe('The cell texts for the row.'),
+          index: z
+            .number()
+            .int()
+            .optional()
+            .describe('0-based insert position (omit/out-of-range to append).'),
+        }),
+        execute: async ({ pageId, tableRef, cells, index }) =>
+          await client.tableInsertRow(pageId, tableRef, cells, index),
+      }),
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      tableDeleteRow: sharedTool(
-        sharedToolSpecs.tableDeleteRow,
-        async ({ pageId, table, index }) =>
-          await client.tableDeleteRow(pageId, table, index),
-      ),
+      // NOT shared — same `tableRef` (here) vs `table` (MCP) parameter-name
+      // divergence as tableInsertRow.
+      tableDeleteRow: tool({
+        description:
+          'Delete a table row at a 0-based index. Reversible via page history.',
+        inputSchema: modelFriendlyInput({
+          pageId: z.string().describe('The id of the page.'),
+          tableRef: z
+            .string()
+            .describe('"#<index>" from getOutline, or a block id in the table.'),
+          index: z.number().int().describe('0-based row index to delete.'),
+        }),
+        execute: async ({ pageId, tableRef, index }) =>
+          await client.tableDeleteRow(pageId, tableRef, index),
+      }),
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      tableUpdateCell: sharedTool(
-        sharedToolSpecs.tableUpdateCell,
-        async ({ pageId, table, row, col, text }) =>
-          await client.tableUpdateCell(pageId, table, row, col, text),
-      ),
+      // NOT shared — same `tableRef` (here) vs `table` (MCP) parameter-name
+      // divergence as tableInsertRow.
+      tableUpdateCell: tool({
+        description:
+          'Set the plain-text content of a table cell at [row, col] (0-based). ' +
+          'Reversible via page history.',
+        inputSchema: modelFriendlyInput({
+          pageId: z.string().describe('The id of the page.'),
+          tableRef: z
+            .string()
+            .describe('"#<index>" from getOutline, or a block id in the table.'),
+          row: z.number().int().describe('0-based row index.'),
+          col: z.number().int().describe('0-based column index.'),
+          text: z.string().describe('The new cell text.'),
+        }),
+        execute: async ({ pageId, tableRef, row, col, text }) =>
+          await client.tableUpdateCell(pageId, tableRef, row, col, text),
+      }),
 
       copyPageContent: sharedTool(
         sharedToolSpecs.copyPageContent,
@@ -717,14 +918,25 @@ export class AiChatToolsService {
           await client.importPageMarkdown(pageId, markdown),
       ),
 
-      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
-      // Both layers already carried the security-confirmation framing, so there
-      // was no real divergence to preserve — only wording drift.
-      sharePage: sharedTool(
-        sharedToolSpecs.sharePage,
-        async ({ pageId, searchIndexing }) =>
+      // INTENTIONAL per-transport divergence (not shared): adds a security
+      // confirmation framing ("Only share when the user explicitly asked, since
+      // this exposes the page to anyone with the link") for the in-app agent; the
+      // standalone MCP `share_page` keeps the plain public-URL wording.
+      sharePage: tool({
+        description:
+          'Make a page PUBLICLY accessible and return its public URL. ' +
+          'Reversible via unsharePage. Only share when the user explicitly ' +
+          'asked, since this exposes the page to anyone with the link.',
+        inputSchema: modelFriendlyInput({
+          pageId: z.string().describe('The id of the page to share.'),
+          searchIndexing: z
+            .boolean()
+            .optional()
+            .describe('Allow public search engines to index it (default true).'),
+        }),
+        execute: async ({ pageId, searchIndexing }) =>
           await client.sharePage(pageId, searchIndexing),
-      ),
+      }),
 
       unsharePage: sharedTool(
         sharedToolSpecs.unsharePage,

apps/server/src/core/ai-chat/tools/tool-tiers.ts

@@ -100,26 +100,54 @@ export const INLINE_TOOL_TIERS: Record<
     tier: 'core',
     catalogLine: 'getCurrentPage — the page the user is currently viewing.',
   },
-  // NOTE: getPage and listPages moved to @docmost/mcp's SHARED_TOOL_SPECS
-  // (#294); they carry their own tier ('core') + catalogLine there.
-  // NOTE: createComment, listComments and resolveComment moved to
-  // @docmost/mcp's SHARED_TOOL_SPECS (#294); they carry their own tier +
-  // catalogLine there. getComment stays inline (MCP-only shape divergence is
-  // n/a — it simply has no shared spec).
+  getPage: {
+    tier: 'core',
+    catalogLine: 'getPage — fetch a page as Markdown by its id.',
+  },
+  listPages: {
+    tier: 'core',
+    catalogLine: "listPages — list recent pages, or a space's full page tree.",
+  },
+  listComments: {
+    tier: 'core',
+    catalogLine: 'listComments — list all comments on a page (including resolved).',
+  },
   getComment: {
     tier: 'core',
     catalogLine: 'getComment — fetch a single comment by id.',
   },
+  createComment: {
+    tier: 'core',
+    catalogLine:
+      'createComment — add an inline comment (optionally with a suggested edit).',
+  },
+  resolveComment: {
+    tier: 'core',
+    catalogLine: 'resolveComment — resolve or reopen a comment thread.',
+  },
 
   // --- deferred inline ---
-  // NOTE: createPage, renamePage, movePage, deletePage, updatePageJson and
-  // exportPageMarkdown moved to @docmost/mcp's SHARED_TOOL_SPECS (#294); they
-  // carry their own deferred tier + catalogLine there.
+  createPage: {
+    tier: 'deferred',
+    catalogLine: 'createPage — create a new page with a Markdown body in a space.',
+  },
   updatePageContent: {
     tier: 'deferred',
     catalogLine:
       "updatePageContent — replace a page's body (and optionally title) with new Markdown.",
   },
+  renamePage: {
+    tier: 'deferred',
+    catalogLine: "renamePage — change a page's title only (body untouched).",
+  },
+  movePage: {
+    tier: 'deferred',
+    catalogLine: 'movePage — move a page under a new parent or to the space root.',
+  },
+  deletePage: {
+    tier: 'deferred',
+    catalogLine: 'deletePage — move a page to trash (soft delete, reversible).',
+  },
   listSidebarPages: {
     tier: 'deferred',
     catalogLine:
@@ -129,21 +157,42 @@ export const INLINE_TOOL_TIERS: Record<
     tier: 'deferred',
     catalogLine: 'getTable — read a table as a matrix of cell texts and cell ids.',
   },
-  // NOTE: tableInsertRow, tableDeleteRow and tableUpdateCell moved to
-  // @docmost/mcp's SHARED_TOOL_SPECS (#294); they carry their own deferred tier +
-  // catalogLine there. getTable stays inline (its MCP name table_get breaks the
-  // snake_case(inAppKey) convention, so it has no shared spec).
-  // NOTE: checkNewComments moved to @docmost/mcp's SHARED_TOOL_SPECS (#294);
-  // it carries its own deferred tier + catalogLine there.
+  checkNewComments: {
+    tier: 'deferred',
+    catalogLine:
+      'checkNewComments — find comments in a space created after a timestamp.',
+  },
   getPageHistory: {
     tier: 'deferred',
     catalogLine:
       'getPageHistory — fetch one page-history version with its ProseMirror content.',
   },
-  // NOTE: sharePage moved to @docmost/mcp's SHARED_TOOL_SPECS (#294); it carries
-  // its own deferred tier + catalogLine there. transformPage stays inline (its
-  // schema deliberately diverges — it omits the deleteComments field the MCP
-  // docmost_transform exposes, a comment-deletion guardrail).
+  exportPageMarkdown: {
+    tier: 'deferred',
+    catalogLine:
+      'exportPageMarkdown — export a page to self-contained Markdown (body + comments).',
+  },
+  updatePageJson: {
+    tier: 'deferred',
+    catalogLine:
+      "updatePageJson — overwrite a page's body with a full ProseMirror document.",
+  },
+  tableInsertRow: {
+    tier: 'deferred',
+    catalogLine: 'tableInsertRow — insert a row of plain-text cells into a table.',
+  },
+  tableDeleteRow: {
+    tier: 'deferred',
+    catalogLine: 'tableDeleteRow — delete a table row at a 0-based index.',
+  },
+  tableUpdateCell: {
+    tier: 'deferred',
+    catalogLine: 'tableUpdateCell — set the text of a table cell at [row, col].',
+  },
+  sharePage: {
+    tier: 'deferred',
+    catalogLine: 'sharePage — make a page publicly accessible and return its URL.',
+  },
   transformPage: {
     tier: 'deferred',
     catalogLine: "transformPage — run a sandboxed JS transform over a page's document.",

apps/server/src/core/page/services/page.service.ts

@@ -52,7 +52,9 @@ import {
   INTERNAL_LINK_REGEX,
   extractPageSlugId,
 } from '../../../integrations/export/utils';
-import { markdownToHtml, canonicalizeFootnotes } from '@docmost/editor-ext';
+import { canonicalizeFootnotes } from '@docmost/editor-ext';
+import { markdownToProseMirror } from '@docmost/prosemirror-markdown';
+import { normalizeForeignMarkdown } from '../../../integrations/import/utils/foreign-markdown';
 import { WatcherService } from '../../watcher/watcher.service';
 import { sql } from 'kysely';
 import { TransclusionService } from '../transclusion/transclusion.service';
@@ -1301,8 +1303,14 @@ export class PageService {
 
     switch (format) {
       case 'markdown': {
-        const html = await markdownToHtml(content as string);
-        prosemirrorJson = htmlToJson(html as string);
+        // Canonical markdown -> ProseMirror JSON directly via
+        // `@docmost/prosemirror-markdown` (issue #345) — no HTML intermediate,
+        // no editor-ext markdown layer. Foreign markdown surfaces the strict
+        // parser rejects (GFM `[^id]` reference footnotes) are normalized to the
+        // canonical inline form first.
+        prosemirrorJson = await markdownToProseMirror(
+          normalizeForeignMarkdown(content as string),
+        );
         break;
       }
       case 'html': {

apps/server/src/integrations/export/export-markdown.spec.ts

@@ -0,0 +1,145 @@
+// export.service.ts imports the ESM-only @sindresorhus/slugify (not in jest's
+// transform allowlist). It is irrelevant to the markdown-serialization path under
+// test (only used for page-mention link slugs on the DB path), so it is mocked
+// out to keep the module graph loadable under ts-jest (mirrors the import specs).
+jest.mock('@sindresorhus/slugify', () => ({
+  __esModule: true,
+  default: (input: string) => String(input),
+}));
+
+import { convertProseMirrorToMarkdown } from '@docmost/prosemirror-markdown';
+import { ExportService } from './export.service';
+import { ExportFormat } from './dto/export-dto';
+
+/**
+ * STEP 1 golden test for issue #345: server MARKDOWN export runs DIRECTLY through
+ * the canonical converter (`convertProseMirrorToMarkdown`) — no HTML intermediate
+ * and no `@docmost/editor-ext` markdown layer — so the emitted markdown is in the
+ * canonical package forms and is byte-identical to the git-sync vault body.
+ *
+ * These are the goldens the swap has to satisfy: they assert the CANONICAL
+ * surface (callout `> [!type]`, inline footnote `^[…]`, lossless image
+ * `<!--img …-->`) rather than the old editor-ext forms (`:::type`, `[^id]`,
+ * lossy `![alt](src)`).
+ *
+ * `exportPage(..., singlePage=false)` takes no DB path (no mention rewriting), so
+ * the service is constructed with null collaborators and only the pure
+ * PM -> Markdown path is exercised.
+ */
+
+function makeService(): ExportService {
+  return new ExportService(
+    null as any, // pageRepo
+    null as any, // pagePermissionRepo
+    null as any, // db
+    null as any, // storageService
+    null as any, // environmentService
+    null as any, // domainService
+  );
+}
+
+// A representative page exercising the node types whose canonical markdown form
+// changed with the move off the editor-ext layer: callout, inline footnote, and a
+// lossless image carrying width/align attrs that the old layer dropped.
+const REPRESENTATIVE_DOC = {
+  type: 'doc',
+  content: [
+    {
+      type: 'paragraph',
+      content: [
+        { type: 'text', text: 'Body ' },
+        { type: 'footnoteReference', attrs: { id: 'fn-1' } },
+        { type: 'text', text: ' end.' },
+      ],
+    },
+    {
+      type: 'callout',
+      attrs: { type: 'info', icon: null },
+      content: [
+        {
+          type: 'paragraph',
+          content: [{ type: 'text', text: 'Heads up' }],
+        },
+      ],
+    },
+    {
+      type: 'image',
+      attrs: {
+        src: '/files/pic.png',
+        alt: 'Pic',
+        width: 320,
+        align: 'left',
+      },
+    },
+    {
+      type: 'footnotesList',
+      content: [
+        {
+          type: 'footnoteDefinition',
+          attrs: { id: 'fn-1' },
+          content: [
+            {
+              type: 'paragraph',
+              content: [{ type: 'text', text: 'the note' }],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+describe('ExportService — markdown export via the canonical converter (#345)', () => {
+  it('emits canonical callout, inline footnote and lossless image forms', async () => {
+    const service = makeService();
+    const md = (await service.exportPage(ExportFormat.Markdown, {
+      title: '',
+      content: REPRESENTATIVE_DOC,
+    } as any)) as string;
+
+    // Callout: Obsidian `> [!type]`, NOT the legacy `:::type`.
+    expect(md).toContain('> [!info]');
+    expect(md).not.toContain(':::');
+
+    // Inline footnote: `^[…]`, NOT the reference `[^id]` form.
+    expect(md).toContain('^[the note]');
+    expect(md).not.toMatch(/\[\^/);
+
+    // Lossless image: trailing `<!--img …-->` carrying the dropped attrs.
+    expect(md).toContain('![Pic](/files/pic.png)');
+    expect(md).toContain('<!--img');
+    expect(md).toContain('"width":"320"');
+    expect(md).toContain('"align":"left"');
+  });
+
+  it('export body is byte-identical to the git-sync vault serializer (export == vault)', async () => {
+    const service = makeService();
+    // A title-less page: exportPage prepends NO heading, so the whole output is
+    // the page BODY — exactly what git-sync serializes (git-sync stores the title
+    // in frontmatter / the filename, never as an in-body H1).
+    const exported = (await service.exportPage(ExportFormat.Markdown, {
+      title: '',
+      content: REPRESENTATIVE_DOC,
+    } as any)) as string;
+
+    // The git-sync vault writer feeds this SAME converter (git-sync
+    // `stabilizePageBody` = convertProseMirrorToMarkdown(content) at the
+    // fixpoint). For an already-stable doc the single pass IS the fixpoint, so
+    // the two are byte-identical by construction — assert it.
+    const vaultBody = convertProseMirrorToMarkdown(REPRESENTATIVE_DOC);
+    expect(exported).toBe(vaultBody);
+  });
+
+  it('prepends the page title as an H1 heading (the one documented export/vault delta)', async () => {
+    const service = makeService();
+    const md = (await service.exportPage(ExportFormat.Markdown, {
+      title: 'My Page',
+      content: { type: 'doc', content: [] },
+    } as any)) as string;
+
+    // Export makes standalone files, so it prepends the title as an H1. This is
+    // the ONE deliberate difference from the vault body (which carries the title
+    // in frontmatter). The body below the heading still serializes canonically.
+    expect(md.startsWith('# My Page')).toBe(true);
+  });
+});

apps/server/src/integrations/export/export.service.ts

@@ -37,7 +37,7 @@ import {
   getAttachmentIds,
   getProsemirrorContent,
 } from '../../common/helpers/prosemirror/utils';
-import { htmlToMarkdown } from '@docmost/editor-ext';
+import { convertProseMirrorToMarkdown } from '@docmost/prosemirror-markdown';
 
 type AllowedAttachment = { id: string; fileName: string; filePath: string };
 
@@ -79,9 +79,8 @@ export class ExportService {
       prosemirrorJson.content.unshift(titleNode);
     }
 
-    const pageHtml = jsonToHtml(prosemirrorJson);
-
     if (format === ExportFormat.HTML) {
+      const pageHtml = jsonToHtml(prosemirrorJson);
       return `<!DOCTYPE html>
       <html>
         <head>
@@ -92,11 +91,14 @@ export class ExportService {
     }
 
     if (format === ExportFormat.Markdown) {
-      const newPageHtml = pageHtml.replace(
-        /<colgroup[^>]*>[\s\S]*?<\/colgroup>/gim,
-        '',
-      );
-      return htmlToMarkdown(newPageHtml);
+      // Direct ProseMirror JSON -> Markdown via the canonical converter
+      // (`@docmost/prosemirror-markdown`). This is the SAME serializer the
+      // git-sync vault writer feeds (see git-sync `stabilizePageBody`), so an
+      // exported page body is byte-identical to its vault representation — no
+      // HTML intermediate, no second markdown layer, no format drift (issue
+      // #345). The old `<colgroup>` scrub is gone with the HTML step: the
+      // converter emits GFM tables directly and never produces `<colgroup>`.
+      return convertProseMirrorToMarkdown(prosemirrorJson);
     }
 
     return;

apps/server/src/integrations/import/services/file-import-task.service.footnote-canonicalize.spec.ts

@@ -17,6 +17,22 @@ jest.mock('image-dimensions', () => ({
   __esModule: true,
   imageDimensionsFromData: () => undefined,
 }));
+// FileImportTaskService -> PageService -> collaboration.gateway ->
+// metrics.registry imports `prom-client`, which is not resolvable in this
+// workspace's node_modules (types-only stub, no runtime entry). Metrics are
+// disabled on this path, so a virtual no-op mock keeps the module graph loadable.
+jest.mock(
+  'prom-client',
+  () => ({
+    collectDefaultMetrics: () => undefined,
+    Registry: class {},
+    Histogram: class {},
+    Gauge: class {},
+    Counter: class {},
+    Summary: class {},
+  }),
+  { virtual: true },
+);
 
 import { promises as fs } from 'fs';
 import * as os from 'os';
@@ -26,14 +42,17 @@ import { ImportService } from './import.service';
 
 /**
  * Binding test for issue #228 / review #5: FileImportTaskService.processGenericImport
- * is a NON-editor write path (markdownToHtml -> processHTML -> JSON, never runs
- * footnoteSyncPlugin), so it canonicalizes footnotes before persisting. This pins
- * that binding — the same one import.service has a spec for — which previously had
- * NO spec at all.
+ * is a NON-editor write path, so a zip-imported `.md` page ends up with canonical
+ * footnotes before persisting: ordered by first reference, reused refs deduped,
+ * orphan definitions dropped.
  *
- * The markdown -> HTML -> ProseMirror conversion is REAL (a real ImportService,
- * its createYdoc stubbed); the filesystem is a real temp dir with one .md file;
- * the DB transaction is stubbed to capture the persisted page content.
+ * Since #345 the `.md` parse runs `normalizeForeignMarkdown` ->
+ * `markdownToProseMirror` -> `jsonToHtml` (feeding the shared HTML attachment /
+ * link pipeline) -> `processHTML` -> `canonicalizeFootnotes`. The parser assigns
+ * fresh `fn-*` ids, so we assert by definition BODY order rather than the source
+ * labels. The conversion is REAL (a real ImportService, its createYdoc stubbed);
+ * the filesystem is a real temp dir with one .md file; the DB transaction is
+ * stubbed to capture the persisted page content.
  */
 
 // Out-of-order references (c, a, b), a REUSED reference ([^a] twice), and an
@@ -49,13 +68,14 @@ const MARKDOWN = [
   '[^z]: orphan note',
 ].join('\n');
 
-function footnoteListIds(content: any): string[] {
+/** Definition body texts of the (single) footnotesList, in list order. */
+function footnoteListBodies(content: any): string[] {
   const list = (content?.content ?? []).find(
     (n: any) => n.type === 'footnotesList',
   );
   return (list?.content ?? [])
     .filter((n: any) => n.type === 'footnoteDefinition')
-    .map((n: any) => n.attrs?.id);
+    .map((n: any) => n.content?.[0]?.content?.[0]?.text);
 }
 
 // A permissive chainable stub for the spaces lookup (selectFrom(...).select(...)
@@ -71,80 +91,127 @@ function chainable(result: any): any {
   return proxy;
 }
 
+/**
+ * Run one markdown file through the REAL zip-import pipeline
+ * (`processGenericImport` -> `markdownToProseMirror` -> `jsonToHtml` ->
+ * `processHTML`/`htmlToJson`) and return the persisted page `content`. This is
+ * the server-specific PM->HTML->PM hop that the package's own PM<->MD tests do
+ * NOT cover.
+ */
+async function runZipImport(markdown: string): Promise<any> {
+  const extractDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fit-canon-'));
+  await fs.writeFile(path.join(extractDir, 'note.md'), markdown, 'utf-8');
+
+  const importService = new ImportService(
+    {} as any,
+    {} as any,
+    {} as any,
+    {} as any,
+  );
+  jest
+    .spyOn(importService as any, 'createYdoc')
+    .mockResolvedValue(Buffer.from([]) as any);
+
+  let captured: any = null;
+  const trx = {
+    insertInto: (table: string) => ({
+      values: (v: any) => {
+        if (table === 'pages') captured = v;
+        return { execute: async () => {} };
+      },
+    }),
+  };
+  const db: any = {
+    selectFrom: () => chainable({ slug: 'space-slug' }),
+    transaction: () => ({ execute: (fn: any) => fn(trx) }),
+  };
+
+  const importAttachmentService = {
+    processAttachments: async ({ html }: any) => html,
+  };
+  const service = new FileImportTaskService(
+    {} as any, // storageService
+    importService as any,
+    { nextPagePosition: async () => 'a0' } as any,
+    { insertBacklink: jest.fn() } as any,
+    db,
+    importAttachmentService as any,
+    { emit: jest.fn() } as any,
+    { logBatchWithContext: jest.fn() } as any,
+  );
+
+  const fileTask: any = {
+    id: 'task-1',
+    source: 'generic',
+    spaceId: 'space-1',
+    workspaceId: 'ws-1',
+    creatorId: 'user-1',
+  };
+
+  try {
+    await service.processGenericImport({ extractDir, fileTask });
+    expect(captured).toBeTruthy();
+    return captured.content;
+  } finally {
+    await fs.rm(extractDir, { recursive: true, force: true });
+  }
+}
+
+/** Find the first node of a given type anywhere in a PM content tree. */
+function findFirst(node: any, type: string): any {
+  if (!node || typeof node !== 'object') return null;
+  if (node.type === type) return node;
+  for (const child of node.content ?? []) {
+    const hit = findFirst(child, type);
+    if (hit) return hit;
+  }
+  return null;
+}
+
 describe('FileImportTaskService.processGenericImport — footnote canonicalization (#228)', () => {
   it('orders footnotes by first reference, dedupes reuse, and drops orphans on zip import', async () => {
-    const extractDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fit-canon-'));
-    await fs.writeFile(path.join(extractDir, 'note.md'), MARKDOWN, 'utf-8');
-
-    // Real ImportService for the html -> JSON conversion; stub the yjs encode.
-    const importService = new ImportService(
-      {} as any,
-      {} as any,
-      {} as any,
-      {} as any,
+    const content = await runZipImport(MARKDOWN);
+    // Definitions ordered by FIRST REFERENCE (C, A, B), NOT the markdown
+    // definition order (A, B, C). Ids are the parser's fresh `fn-*`, so pin
+    // the BODIES.
+    expect(footnoteListBodies(content)).toEqual(['note C', 'note A', 'note B']);
+    // Orphan [^z] dropped; reused [^a] collapses to one definition; one list.
+    expect(footnoteListBodies(content)).not.toContain('orphan note');
+    const lists = (content.content ?? []).filter(
+      (n: any) => n.type === 'footnotesList',
     );
-    jest
-      .spyOn(importService as any, 'createYdoc')
-      .mockResolvedValue(Buffer.from([]) as any);
+    expect(lists).toHaveLength(1);
+    expect(
+      footnoteListBodies(content).filter((b) => b === 'note A'),
+    ).toHaveLength(1);
+  });
 
-    let captured: any = null;
-    const trx = {
-      insertInto: (table: string) => ({
-        values: (v: any) => {
-          if (table === 'pages') captured = v;
-          return { execute: async () => {} };
-        },
-      }),
-    };
-    const db: any = {
-      selectFrom: () => chainable({ slug: 'space-slug' }),
-      transaction: () => ({ execute: (fn: any) => fn(trx) }),
-    };
+  // #345 F4: the zip path routes markdown through jsonToHtml -> processHTML ->
+  // htmlToJson (the shared HTML attachment pipeline). #345's headline is LOSSLESS
+  // image width/align via the `<!--img {...}-->` comment; a callout carries its
+  // `type`. This asserts those survive the PM->HTML->PM hop — the one hop the
+  // package's PM<->MD suite does not exercise.
+  it('preserves image width/align and callout type through the PM->HTML->PM hop', async () => {
+    const md = [
+      '# Doc',
+      '',
+      '![a picture](https://example.com/i.png) <!--img {"width":"320","align":"left"}-->',
+      '',
+      ':::warning',
+      'Careful now.',
+      ':::',
+    ].join('\n');
 
-    const importAttachmentService = {
-      processAttachments: async ({ html }: any) => html,
-    };
-    const backlinkRepo = { insertBacklink: jest.fn() };
-    const eventEmitter = { emit: jest.fn() };
-    const auditService = { logBatchWithContext: jest.fn() };
+    const content = await runZipImport(md);
 
-    const pageService = { nextPagePosition: async () => 'a0' };
+    const image = findFirst(content, 'image');
+    expect(image).toBeTruthy();
+    // The lossless sizing/alignment must survive the HTML hop.
+    expect(String(image.attrs?.width)).toBe('320');
+    expect(image.attrs?.align).toBe('left');
 
-    const service = new FileImportTaskService(
-      {} as any, // storageService
-      importService as any,
-      pageService as any,
-      backlinkRepo as any,
-      db,
-      importAttachmentService as any,
-      eventEmitter as any,
-      auditService as any,
-    );
-
-    const fileTask: any = {
-      id: 'task-1',
-      source: 'generic',
-      spaceId: 'space-1',
-      workspaceId: 'ws-1',
-      creatorId: 'user-1',
-    };
-
-    try {
-      await service.processGenericImport({ extractDir, fileTask });
-
-      expect(captured).toBeTruthy();
-      const content = captured.content;
-      // Reference order is c, a, b (NOT the markdown definition order a, b, c).
-      expect(footnoteListIds(content)).toEqual(['c', 'a', 'b']);
-      // Orphan [^z] dropped; reused [^a] collapses to one definition; one list.
-      expect(footnoteListIds(content)).not.toContain('z');
-      const lists = (content.content ?? []).filter(
-        (n: any) => n.type === 'footnotesList',
-      );
-      expect(lists).toHaveLength(1);
-      expect(footnoteListIds(content).filter((id) => id === 'a')).toHaveLength(1);
-    } finally {
-      await fs.rm(extractDir, { recursive: true, force: true });
-    }
+    const callout = findFirst(content, 'callout');
+    expect(callout).toBeTruthy();
+    expect(callout.attrs?.type).toBe('warning');
   });
 });

apps/server/src/integrations/import/services/file-import-task.service.ts

@@ -1,6 +1,9 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
 import * as path from 'path';
-import { jsonToText } from '../../../collaboration/collaboration.util';
+import {
+  jsonToHtml,
+  jsonToText,
+} from '../../../collaboration/collaboration.util';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
 import {
@@ -18,9 +21,11 @@ import { generateSlugId } from '../../../common/helpers';
 import { v7 } from 'uuid';
 import { generateJitteredKeyBetween } from 'fractional-indexing-jittered';
 import { FileTask, InsertablePage } from '@docmost/db/types/entity.types';
-import { markdownToHtml, canonicalizeFootnotes } from '@docmost/editor-ext';
+import { canonicalizeFootnotes } from '@docmost/editor-ext';
+import { markdownToProseMirror } from '@docmost/prosemirror-markdown';
 import { getProsemirrorContent } from '../../../common/helpers/prosemirror/utils';
 import { formatImportHtml } from '../utils/import-formatter';
+import { normalizeForeignMarkdown } from '../utils/foreign-markdown';
 import {
   buildAttachmentCandidates,
   collectMarkdownAndHtmlFiles,
@@ -461,7 +466,18 @@ export class FileImportTaskService {
               content = await fs.readFile(absPath, 'utf-8');
 
               if (page.fileExtension.toLowerCase() === '.md') {
-                content = await markdownToHtml(content);
+                // Parse markdown with the single canonical converter
+                // (`@docmost/prosemirror-markdown`), after normalizing foreign
+                // reference footnotes, then serialize to HTML so the shared HTML
+                // pipeline below (processAttachments + formatImportHtml +
+                // processHTML) keeps handling `.md` and `.html` imports
+                // uniformly. The markdown PARSE no longer goes through the
+                // editor-ext markdown layer (issue #345) — the drift source is
+                // gone. The PM -> HTML -> PM hop that follows is lossless
+                // plumbing for attachment/link resolution, NOT a second parse.
+                content = jsonToHtml(
+                  await markdownToProseMirror(normalizeForeignMarkdown(content)),
+                );
               }
             } catch (err: any) {
               if (err?.code === 'ENOENT') {
@@ -500,10 +516,12 @@ export class FileImportTaskService {
               this.importService.extractTitleAndRemoveHeading(pmState);
 
             // Canonicalize footnote topology on this non-editor write path
-            // (markdownToHtml/processHTML never runs footnoteSyncPlugin), so a
-            // zip-imported page's footnotes are reference-ordered, deduped, and
+            // (the HTML pipeline's processHTML never runs footnoteSyncPlugin), so
+            // a zip-imported page's footnotes are reference-ordered, deduped, and
             // orphan-free like the editor's invariant (issue #228). Pure +
-            // idempotent + shape-safe; a footnote-free doc is unchanged.
+            // idempotent + shape-safe; a footnote-free doc is unchanged. (For a
+            // `.md` file the package parser already yields canonical footnotes,
+            // so this is a no-op there.)
             // (Future consolidation, architecture B: like import.service, this
             // path persists directly rather than via PageService — a shared
             // "prepare JSON for persist" helper would centralize this call.)

apps/server/src/integrations/import/services/import.service.footnote-canonicalize.spec.ts

@@ -12,13 +12,19 @@ import { canonicalizeFootnotes } from '@docmost/editor-ext';
 
 /**
  * Integration-ish test for the USER-FACING markdown import path
- * (`ImportService.importPage`). It exercises the REAL markdown -> HTML -> JSON
- * conversion and asserts that the stored page content has its footnotes
- * canonicalized — the gap that issue #228 fixes: the import path builds
- * ProseMirror JSON directly (never running the editor's footnoteSyncPlugin), so
- * before this wiring the stored footnotes kept the markdown's physical
- * definition order (out of order vs. references), retained orphan definitions,
- * and did not collapse reused references.
+ * (`ImportService.importPage`). It exercises the REAL markdown -> ProseMirror
+ * conversion and asserts the stored page's footnotes are canonical: ordered by
+ * FIRST REFERENCE (not markdown definition order), reused references deduped to a
+ * single definition, and orphan definitions dropped.
+ *
+ * Since #345 the markdown parse runs through the canonical package
+ * (`normalizeForeignMarkdown` -> `markdownToProseMirror`), which owns this
+ * canonicalization: the input's GFM `[^id]` reference footnotes are normalized to
+ * inline `^[…]`, and the parser assigns fresh sequential ids (`fn-*`) in
+ * reference order while merging identical bodies — so we assert by definition
+ * BODY order, not by the source labels. `canonicalizeFootnotes` remains wired as
+ * an idempotent safety net (issue #228) and is a no-op on this already-canonical
+ * output.
  *
  * The DB/ydoc side-effects are stubbed: `getNewPagePosition` (DB query) and
  * `createYdoc` (Yjs encode) are spied, and `pageRepo.insertPage` captures the
@@ -67,24 +73,14 @@ function makeService() {
 }
 
 /** List the footnote-definition ids of the (single) footnotesList, in order. */
-function footnoteListIds(content: any): string[] {
+/** Definition body texts of the (single) footnotesList, in list order. */
+function footnoteListBodies(content: any): string[] {
   const list = (content.content ?? []).find(
     (n: any) => n.type === 'footnotesList',
   );
-  if (!list) return [];
-  return (list.content ?? [])
+  return (list?.content ?? [])
     .filter((n: any) => n.type === 'footnoteDefinition')
-    .map((n: any) => n.attrs?.id);
-}
-
-function definitionText(content: any, id: string): string | undefined {
-  const list = (content.content ?? []).find(
-    (n: any) => n.type === 'footnotesList',
-  );
-  const def = (list?.content ?? []).find(
-    (n: any) => n.type === 'footnoteDefinition' && n.attrs?.id === id,
-  );
-  return def?.content?.[0]?.content?.[0]?.text;
+    .map((n: any) => n.content?.[0]?.content?.[0]?.text);
 }
 
 describe('ImportService.importPage — footnote canonicalization (#228)', () => {
@@ -101,23 +97,23 @@ describe('ImportService.importPage — footnote canonicalization (#228)', () =>
     const content = getCaptured().content;
     expect(content).toBeTruthy();
 
-    // Reference order is c, a, b (NOT the markdown definition order a, b, c).
-    expect(footnoteListIds(content)).toEqual(['c', 'a', 'b']);
-
-    // Definitions preserved and attached to the right ids.
-    expect(definitionText(content, 'c')).toBe('note C');
-    expect(definitionText(content, 'a')).toBe('note A');
-    expect(definitionText(content, 'b')).toBe('note B');
+    // Definitions ordered by FIRST REFERENCE (C, A, B) — NOT the markdown
+    // definition order (A, B, C) — with the orphan [^z] dropped and the reused
+    // [^a] collapsed to a single definition. (Ids are the parser's fresh `fn-*`,
+    // so we pin the BODIES.)
+    expect(footnoteListBodies(content)).toEqual(['note C', 'note A', 'note B']);
 
     // Orphan definition [^z] is dropped.
-    expect(footnoteListIds(content)).not.toContain('z');
+    expect(footnoteListBodies(content)).not.toContain('orphan note');
 
     // Reused [^a] yields exactly ONE definition, and exactly one list.
     const lists = (content.content ?? []).filter(
       (n: any) => n.type === 'footnotesList',
     );
     expect(lists).toHaveLength(1);
-    expect(footnoteListIds(content).filter((id) => id === 'a')).toHaveLength(1);
+    expect(
+      footnoteListBodies(content).filter((b) => b === 'note A'),
+    ).toHaveLength(1);
   });
 
   it('is idempotent: canonicalizing the stored output again is a no-op', async () => {
@@ -134,6 +130,6 @@ describe('ImportService.importPage — footnote canonicalization (#228)', () =>
     // time must not change it (safe to wire into every write path).
     const second = canonicalizeFootnotes(stored);
     expect(second).toEqual(stored);
-    expect(footnoteListIds(second)).toEqual(['c', 'a', 'b']);
+    expect(footnoteListBodies(second)).toEqual(['note C', 'note A', 'note B']);
   });
 });

apps/server/src/integrations/import/services/import.service.ts

@@ -17,7 +17,9 @@ import {
 import { generateJitteredKeyBetween } from 'fractional-indexing-jittered';
 import { TiptapTransformer } from '@hocuspocus/transformer';
 import * as Y from 'yjs';
-import { markdownToHtml, canonicalizeFootnotes } from '@docmost/editor-ext';
+import { canonicalizeFootnotes } from '@docmost/editor-ext';
+import { markdownToProseMirror } from '@docmost/prosemirror-markdown';
+import { normalizeForeignMarkdown } from '../utils/foreign-markdown';
 import {
   FileTaskStatus,
   FileTaskType,
@@ -85,11 +87,13 @@ export class ImportService {
 
     const extracted = this.extractTitleAndRemoveHeading(prosemirrorState);
     const title = extracted.title;
-    // Imported markdown/HTML is built via markdownToHtml -> htmlToJson, which
-    // never runs the editor's footnoteSyncPlugin, so the footnote topology keeps
-    // the source's PHYSICAL definition order (out of order vs. references),
-    // retains orphan definitions, and is not deduped. Canonicalize before
-    // persisting so the stored page matches the editor's invariant (issue #228).
+    // The markdown path now canonicalizes footnotes itself (the package parser),
+    // but the HTML path (processHTML -> htmlToJson) does NOT run the editor's
+    // footnoteSyncPlugin, so an imported HTML doc can keep its source's PHYSICAL
+    // definition order (out of order vs. references), retain orphan definitions,
+    // and not be deduped. Canonicalize before persisting so the stored page
+    // matches the editor's invariant (issue #228); it is an idempotent no-op on
+    // the already-canonical markdown output.
     // Pure + idempotent + shape-safe: a doc with no footnotes is unchanged.
     // (Future consolidation, architecture B: this import path persists directly
     // via pageRepo.insertPage rather than through PageService.createPage, so the
@@ -133,12 +137,15 @@ export class ImportService {
   }
 
   async processMarkdown(markdownInput: string): Promise<any> {
-    try {
-      const html = await markdownToHtml(markdownInput);
-      return this.processHTML(html);
-    } catch (err) {
-      throw err;
-    }
+    // Canonical markdown -> ProseMirror JSON directly via
+    // `@docmost/prosemirror-markdown` (issue #345) — no HTML intermediate and no
+    // second editor-ext markdown layer. Foreign markdown surfaces the strict
+    // canonical parser does not accept (GFM `[^id]` reference footnotes) are
+    // rewritten to the canonical inline form by `normalizeForeignMarkdown` first.
+    // The HTML-cleanup pass (`normalizeImportHtml`) is intentionally skipped here:
+    // it targets foreign *HTML* (Notion/XWiki), which only ever arrives on the
+    // `.html` path (`processHTML`), never as canonical markdown.
+    return markdownToProseMirror(normalizeForeignMarkdown(markdownInput));
   }
 
   async processHTML(htmlInput: string): Promise<any> {

apps/server/src/integrations/import/utils/foreign-markdown.spec.ts

@@ -0,0 +1,218 @@
+import {
+  convertProseMirrorToMarkdown,
+  markdownToProseMirror,
+} from '@docmost/prosemirror-markdown';
+import { normalizeForeignMarkdown } from './foreign-markdown';
+
+/**
+ * STEP 2 goldens for issue #345: the foreign-markdown normalizer that runs at the
+ * import boundary BEFORE the strict canonical parser (`markdownToProseMirror`).
+ *
+ * Two layers:
+ *  1. PURE string→string cases pinning the normalizer's own behavior (GFM
+ *     reference footnotes → inline `^[…]`).
+ *  2. END-TO-END acceptance: for a foreign corpus, `normalizeForeignMarkdown`
+ *     then `markdownToProseMirror` then `convertProseMirrorToMarkdown` must leave
+ *     NO literal `[^id]` / `:::` garbage in the document and must re-export in the
+ *     canonical forms.
+ */
+
+describe('normalizeForeignMarkdown — GFM reference footnotes', () => {
+  it('inlines a single-line reference footnote and drops its definition', () => {
+    const out = normalizeForeignMarkdown(
+      'A note[^1] here.\n\n[^1]: The definition.',
+    );
+    expect(out).toBe('A note^[The definition.] here.\n');
+  });
+
+  it('inlines every reference to a reused id (downstream dedups)', () => {
+    const out = normalizeForeignMarkdown(
+      'X[^a] and Y[^a].\n\n[^a]: shared.',
+    );
+    expect(out).toBe('X^[shared.] and Y^[shared.].\n');
+  });
+
+  it('joins indented continuation lines of a definition with a space', () => {
+    const out = normalizeForeignMarkdown(
+      'See[^n].\n\n[^n]: line one\n    line two',
+    );
+    expect(out).toBe('See^[line one line two].\n');
+  });
+
+  it('never rewrites a reference inside a fenced code block', () => {
+    const out = normalizeForeignMarkdown(
+      '```\ncode[^1] here\n```\n\n[^1]: def.',
+    );
+    expect(out).toContain('code[^1] here');
+    // The (now orphaned) definition line is still removed.
+    expect(out).not.toContain('[^1]: def.');
+  });
+
+  it('never rewrites a reference inside an INLINE-code span (backticks)', () => {
+    // The `[^1]` inside backticks is literal code and must survive verbatim;
+    // the one outside is rewritten. (Bug #1: only fenced blocks were protected.)
+    const out = normalizeForeignMarkdown(
+      'Use `arr[^1]` in code but note[^1] in prose.\n\n[^1]: def.',
+    );
+    expect(out).toBe('Use `arr[^1]` in code but note^[def.] in prose.\n');
+  });
+
+  it('escapes brackets in a body so an unbalanced ] cannot truncate the footnote', () => {
+    // A foreign definition body with a stray `]` would, unescaped, close the
+    // canonical `^[...]` early and leak the tail as text (bug #2). The body's
+    // brackets are backslash-escaped so the footnote stays whole.
+    const out = normalizeForeignMarkdown(
+      'Ref[^1] here.\n\n[^1]: see item ] and [more] later',
+    );
+    expect(out).toBe('Ref^[see item \\] and \\[more\\] later] here.\n');
+    // The tokenizer must see exactly one unescaped closing bracket (our own).
+    expect(out.match(/(?<!\\)\]/g)).toHaveLength(1);
+  });
+
+  it('leaves a reference with no matching definition literal (no body to inline)', () => {
+    const out = normalizeForeignMarkdown('Dangling[^x] ref.');
+    expect(out).toBe('Dangling[^x] ref.');
+  });
+
+  it('returns the input unchanged when there are no reference footnotes', () => {
+    const md = '# Title\n\nJust text with `inline code` and a [link](/x).';
+    expect(normalizeForeignMarkdown(md)).toBe(md);
+  });
+
+  it('does NOT touch callout surfaces — the canonical parser handles them', () => {
+    const callouts = ':::info\nHi\n:::\n\n> [!warning]\n> Careful';
+    expect(normalizeForeignMarkdown(callouts)).toBe(callouts);
+  });
+
+  it('strips a leading YAML front-matter block (Obsidian/Hugo/git-sync files)', () => {
+    const out = normalizeForeignMarkdown(
+      '---\ntitle: My Page\ntags: [a, b]\n---\n\n# Heading\n\nBody.',
+    );
+    expect(out).toBe('# Heading\n\nBody.');
+    // The front-matter must not leak into the body as a setext heading.
+    expect(out).not.toContain('title: My Page');
+    expect(out).not.toContain('---');
+  });
+
+  it('does not strip a horizontal rule that is not leading front-matter', () => {
+    const md = 'Intro paragraph.\n\n---\n\nAfter the rule.';
+    expect(normalizeForeignMarkdown(md)).toBe(md);
+  });
+
+  it('is linear on a document with thousands of definitions (no quadratic blowup)', () => {
+    // F2(a): the pass-2 rewrite must be O(text), not O(text × defs). Build a
+    // pathological doc (many defs + many plain text lines) and assert it
+    // completes well under a second — a quadratic implementation took ~14s.
+    const N = 4000;
+    const refs = Array.from({ length: N }, (_, i) => `line ${i} plain text`).join('\n');
+    const defs = Array.from({ length: N }, (_, i) => `[^n${i}]: def ${i}`).join('\n');
+    const doc = `start[^n0] and[^n${N - 1}] end\n\n${refs}\n\n${defs}`;
+    const t0 = Date.now();
+    const out = normalizeForeignMarkdown(doc);
+    const elapsed = Date.now() - t0;
+    expect(elapsed).toBeLessThan(2000);
+    // Sanity: the two real references were still inlined.
+    expect(out).toContain('^[def 0]');
+    expect(out).toContain(`^[def ${N - 1}]`);
+  });
+
+  it('is bounded on a long unclosed backtick run (no inline-split ReDoS)', () => {
+    // F2(b): a huge unterminated backtick run must not cause quadratic
+    // backtracking in the inline-code split. Oversized lines skip the split
+    // entirely (left untouched), so this returns promptly.
+    const line = 'x' + '`'.repeat(200000);
+    const doc = `${line}\n\n[^1]: def`;
+    const t0 = Date.now();
+    normalizeForeignMarkdown(doc);
+    expect(Date.now() - t0).toBeLessThan(2000);
+  });
+
+  it('does not crash or slow down on thousands of prefix-chain definition ids', () => {
+    // F7: the rewrite must use a FIXED generic scanner, not an alternation built
+    // from the ids. A `(a|aa|aaa|…)` alternation over prefix-chain ids blows the
+    // V8 regex compiler (FATAL RegExpCompiler Allocation failed — uncatchable,
+    // kills the process). A fixed scanner has no id-dependent compilation cost.
+    const N = 4000;
+    const ids = Array.from({ length: N }, (_, i) => 'a'.repeat(i + 1));
+    const defs = ids.map((id) => `[^${id}]: body ${id.length}`).join('\n');
+    const doc = `ref[^${ids[0]}] and[^${ids[N - 1]}] end\n\n${defs}`;
+    const t0 = Date.now();
+    const out = normalizeForeignMarkdown(doc);
+    expect(Date.now() - t0).toBeLessThan(2000);
+    // Prefix disambiguation is correct: [^a] and [^aaaa...] inline their OWN body.
+    expect(out).toContain('^[body 1]');
+    expect(out).toContain(`^[body ${N}]`);
+  });
+
+  it('strips a CRLF (Windows) front-matter block, not just LF', () => {
+    // F9: the line-anchored regex needs LF after the opening `---`, so a Windows
+    // file (`---\r\n…`) would slip past the strip and leak the front-matter into
+    // the body. normalizeForeignMarkdown normalizes CRLF -> LF first.
+    const out = normalizeForeignMarkdown(
+      '---\r\ntitle: Foo\r\ntags: [a]\r\n---\r\n\r\n# Heading\r\n\r\nBody.',
+    );
+    expect(out).toBe('# Heading\n\nBody.');
+    expect(out).not.toContain('title: Foo');
+    expect(out).not.toContain('---');
+  });
+
+  it('strips front-matter whose value contains a triple-dash (line-anchored)', () => {
+    // F8: the block must close only on a `\n---` LINE, not the first inline
+    // `---`. A value like `title: Q1 --- Q2` must not truncate the front-matter
+    // and leak the rest (author/closing ---) into the body.
+    const out = normalizeForeignMarkdown(
+      '---\ntitle: Q1 --- Q2 results\nauthor: bob\n---\n\nReal body.',
+    );
+    expect(out).toBe('Real body.');
+    expect(out).not.toContain('author: bob');
+    expect(out).not.toContain('Q2 results');
+  });
+});
+
+describe('foreign markdown import acceptance (normalizer + canonical parser)', () => {
+  const FOREIGN = [
+    '# Doc',
+    '',
+    'Body refs [^c] and [^a] and [^b] and again [^a].',
+    '',
+    ':::info',
+    'A legacy callout.',
+    ':::',
+    '',
+    '| h1 | h2 |',
+    '| --- | --- |',
+    '| 1 | 2 |',
+    '',
+    '[^a]: note A',
+    '[^b]: note B',
+    '[^c]: note C',
+    '[^z]: orphan note',
+  ].join('\n');
+
+  it('leaves no literal [^id] or ::: in the imported doc and re-exports canonically', async () => {
+    const normalized = normalizeForeignMarkdown(FOREIGN);
+    const doc = await markdownToProseMirror(normalized);
+    const reexport = convertProseMirrorToMarkdown(doc);
+
+    // No foreign garbage leaks into the document.
+    expect(reexport).not.toMatch(/\[\^/); // no reference footnote refs/defs
+    expect(reexport).not.toContain(':::'); // no legacy callout fences
+
+    // Canonical forms are present.
+    expect(reexport).toContain('^[note C]');
+    expect(reexport).toContain('> [!info]');
+    expect(reexport).toContain('| h1 | h2 |');
+
+    // Footnotes: ordered by first reference (C, A, B), reused [^a] deduped to one,
+    // orphan [^z] dropped (it had no reference after normalization).
+    const list = doc.content.find((n: any) => n.type === 'footnotesList');
+    const bodies = list.content.map(
+      (d: any) => d.content[0].content[0].text,
+    );
+    expect(bodies).toEqual(['note C', 'note A', 'note B']);
+    expect(bodies).not.toContain('orphan note');
+    expect(
+      doc.content.filter((n: any) => n.type === 'footnotesList'),
+    ).toHaveLength(1);
+  });
+});

apps/server/src/integrations/import/utils/foreign-markdown.ts

@@ -0,0 +1,265 @@
+/**
+ * Foreign-markdown normalizer — an input-liberal / output-canonical adapter that
+ * runs at the IMPORT boundary, BEFORE the canonical parser
+ * (`markdownToProseMirror` from `@docmost/prosemirror-markdown`).
+ *
+ * The canonical parser is deliberately STRICT: it only understands Docmost's
+ * canonical markdown surface (Obsidian-style `> [!type]` callouts, Pandoc/Obsidian
+ * inline footnotes `^[body]`, lossless `![alt](src) <!--img {...}-->` images, …).
+ * Import, however, ingests FOREIGN files (GitHub/GFM, Notion, old Docmost
+ * exports). Those use surfaces the canonical parser does not accept, most notably
+ * GitHub-flavoured *reference* footnotes:
+ *
+ *     Text with a note[^1] and another[^long].
+ *
+ *     [^1]: The first definition.
+ *     [^long]: A second one.
+ *
+ * Left untouched, the parser does NOT recognise `[^id]` (it only parses `^[body]`),
+ * so the reference leaks as literal text — and worse, the trailing `[^id]: def`
+ * line is a valid CommonMark *link-reference definition*, so `[^id]` is silently
+ * rendered as a bogus link. This normalizer rewrites reference footnotes into the
+ * canonical inline form so the parser materialises real footnote nodes.
+ *
+ * This is a TEXT pre-pass, NOT a second parser fork: it does not re-implement any
+ * converter logic. Callout surfaces (`:::type` and `> [!type]`) are intentionally
+ * NOT touched here — the canonical parser already accepts BOTH natively (its
+ * `preprocessCallouts` pass), so normalizing them would be redundant and would
+ * only risk degrading the parser's nesting/code-fence-aware handling.
+ */
+
+/** Matches a fenced code block delimiter (``` or ~~~), capturing the marker run. */
+const CODE_FENCE_RE = /^(\s*)(`{3,}|~{3,})/;
+
+/**
+ * Matches a GFM footnote DEFINITION line: `[^id]: body`. The id is any run of
+ * non-`]` characters; the body is the remainder of the line (possibly empty).
+ */
+const FOOTNOTE_DEF_RE = /^\[\^([^\]]+)\]:[ \t]?(.*)$/;
+
+/** True when a line is a code-fence delimiter that toggles fenced-code state. */
+function fenceMarker(line: string): string | null {
+  const m = line.match(CODE_FENCE_RE);
+  return m ? m[2] : null;
+}
+
+/** True when a line is indented (leading space/tab) and not blank — a continuation. */
+function isIndentedContinuation(line: string): boolean {
+  return /^[ \t]+\S/.test(line);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Backslash-escape any square bracket in a footnote body before it is wrapped in
+ * `^[...]`. The canonical inline-footnote tokenizer scans the body with bracket
+ * balancing and closes on the first UNMATCHED `]`, so an unbalanced bracket in a
+ * foreign definition (e.g. `[^1]: see item ] later`) would otherwise truncate the
+ * footnote and leak the tail as literal text. Escaping every `[`/`]` makes the
+ * body an inert run of characters — the tokenizer then closes only on our own
+ * closing `]`. (A balanced `[link](url)` inside a body still round-trips because
+ * the escaped form renders the literal brackets, which is the safe reading for a
+ * footnote body; the alternative — brittle balance tracking — risks worse.)
+ */
+function escapeFootnoteBody(body: string): string {
+  return body.replace(/[[\]]/g, '\\$&');
+}
+
+/**
+ * Rewrite every `[^id]` reference on a line to its `^[body]` form, but ONLY in the
+ * text OUTSIDE inline-code spans. A `[^id]` inside backticks is literal code
+ * content and must be preserved verbatim (a footnote ref never lives inside code).
+ * We split the line on inline-code spans (paired backtick runs) and rewrite only
+ * the non-code segments.
+ */
+// Above this length a single line is not split into inline-code spans (see
+// below). A genuine markdown line carrying a footnote reference is never tens of
+// KB; the cap only bypasses the inline-code protection for pathological lines.
+const INLINE_SPLIT_MAX_LINE = 8192;
+
+function rewriteRefsOutsideInlineCode(
+  line: string,
+  replace: (text: string) => string,
+): string {
+  // The inline-code split alternation `(`+)(?:(?!\1)[\s\S])*\1` backtracks
+  // quadratically on a long UNCLOSED backtick run (its middle can consume the
+  // rest of the line, then fail to find a closing run and retry from each
+  // position). On an untrusted import this is a request-thread ReDoS. A real
+  // footnote line is short, so for an oversized line we skip the inline-code
+  // protection entirely and leave the line UNTOUCHED (rewriting it wholesale
+  // could corrupt a `[^id]` that legitimately lives inside inline code). This is
+  // a conservative bypass: an over-8KB line simply does not get its reference
+  // footnotes inlined — acceptable for a pathological input.
+  if (line.length > INLINE_SPLIT_MAX_LINE) return line;
+
+  // Alternation: an inline-code span (one or more backticks, then anything up to
+  // the SAME run of backticks) OR a run of non-backtick text. Unterminated
+  // backticks fall through as ordinary text (matched by the second branch on the
+  // leftover), so a stray backtick never swallows the rest of the line.
+  const parts = line.match(/(`+)(?:(?!\1)[\s\S])*\1|[^`]+|`+/g);
+  if (!parts) return line;
+  return parts
+    .map((seg) => (seg.startsWith('`') ? seg : replace(seg)))
+    .join('');
+}
+
+/**
+ * Convert GFM reference footnotes (`[^id]` + `[^id]: def`) into canonical inline
+ * footnotes (`^[def]`).
+ *
+ * - Definitions are collected first (a leading `[^id]: text` line plus any
+ *   immediately-following indented continuation lines, joined with a space) and
+ *   removed from the output.
+ * - Each in-text reference `[^id]` for which a definition was found is replaced by
+ *   `^[def]`. References with no matching definition are left literal (there is no
+ *   body to inline; the parser fails them open the same way).
+ * - Code is respected on both passes: `[^id]` inside a fenced ``` / ~~~ block is
+ *   never rewritten and a `[^id]:` line inside a fence is never a definition; and
+ *   on the rewrite pass a `[^id]` inside an INLINE-code span (backticks) is left
+ *   literal too.
+ * - The inlined body is bracket-escaped so an unbalanced `[`/`]` in a foreign
+ *   definition cannot truncate the resulting `^[...]` footnote.
+ *
+ * Deduplication / reference-ordering / orphan-dropping of the resulting footnotes
+ * is handled downstream by the canonical parser (`assembleFootnotes`); this pass
+ * only changes the surface syntax.
+ */
+function convertReferenceFootnotes(markdown: string): string {
+  const lines = markdown.split('\n');
+
+  // Pass 1: collect definitions and mark their lines for removal.
+  const defs = new Map<string, string>();
+  const dropped = new Array<boolean>(lines.length).fill(false);
+  let inFence = false;
+  let fence = '';
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const marker = fenceMarker(line);
+    if (inFence) {
+      if (marker && marker[0] === fence[0] && marker.length >= fence.length) {
+        inFence = false;
+        fence = '';
+      }
+      continue;
+    }
+    if (marker) {
+      inFence = true;
+      fence = marker;
+      continue;
+    }
+
+    const def = line.match(FOOTNOTE_DEF_RE);
+    if (!def) continue;
+
+    const id = def[1];
+    const body: string[] = [def[2].trim()];
+    dropped[i] = true;
+
+    // Consume immediately-following indented continuation lines (GFM lazy
+    // continuation is not supported by design — keep it simple and predictable).
+    let j = i + 1;
+    while (j < lines.length && isIndentedContinuation(lines[j])) {
+      body.push(lines[j].trim());
+      dropped[j] = true;
+      j++;
+    }
+    i = j - 1;
+
+    // Last definition wins for a duplicated id (matches CommonMark link-ref
+    // semantics closely enough for a foreign-input adapter).
+    defs.set(id, body.filter((s) => s.length > 0).join(' '));
+  }
+
+  if (defs.size === 0) {
+    return markdown;
+  }
+
+  // ONE fixed, generic scanner regex — NOT one built from the definition ids.
+  // It matches ANY `[^id]` shape, and the replacer decides per match via a map
+  // lookup whether that id is a real definition (replace) or not (leave as-is).
+  // This is genuinely O(total text) with no per-document regex compilation.
+  //
+  // Do NOT rebuild this as an alternation over `[...defs.keys()]`: a giant
+  // `(id1|id2|...)` alternation over thousands of ids can blow the V8 regex
+  // compiler's stack — a fatal, UNCATCHABLE "RegExpCompiler Allocation failed"
+  // on prefix-chain ids (`a`, `aa`, `aaa`, ...) that kills the whole process
+  // (worse than the earlier per-def thread-hang). A fixed scanner has no
+  // id-dependent compilation cost and cannot blow up.
+  const refRe = /\[\^([^\]]+)\]/g;
+  const rewriteSegment = (segment: string): string =>
+    segment.replace(refRe, (whole, id: string) => {
+      const body = defs.get(id);
+      // Only real definitions are inlined; an unknown id is left literal (same as
+      // the old per-def loop, which simply never matched it).
+      return body === undefined ? whole : `^[${escapeFootnoteBody(body)}]`;
+    });
+
+  // Pass 2: rewrite in-text references, skipping fenced code and dropped lines.
+  const out: string[] = [];
+  inFence = false;
+  fence = '';
+  for (let i = 0; i < lines.length; i++) {
+    if (dropped[i]) continue;
+    let line = lines[i];
+
+    const marker = fenceMarker(line);
+    if (inFence) {
+      out.push(line);
+      if (marker && marker[0] === fence[0] && marker.length >= fence.length) {
+        inFence = false;
+        fence = '';
+      }
+      continue;
+    }
+    if (marker) {
+      inFence = true;
+      fence = marker;
+      out.push(line);
+      continue;
+    }
+
+    line = rewriteRefsOutsideInlineCode(line, rewriteSegment);
+    out.push(line);
+  }
+
+  return out.join('\n');
+}
+
+/**
+ * Strip a single leading YAML front-matter block (`---\n…\n---`). Foreign files
+ * from Obsidian / Hugo / Jekyll / Notion — and Docmost's OWN git-sync page files
+ * — open with front-matter that the canonical parser does not consume, so
+ * without this it leaks into the body (and `title: Foo` above the closing `---`
+ * renders as a setext `<h2>` that `extractTitleAndRemoveHeading` can hijack as
+ * the page title). It is a no-op for front-matter-free input.
+ *
+ * LINE-ANCHORED (the same shape the canonical parser uses in
+ * prosemirror-markdown/page-file.ts): the block opens only on `---\n` at the
+ * very start and closes only on a `\n---` line. The retired `markdownToHtml`
+ * strip closed on the FIRST `---` ANYWHERE (an unanchored close), so a value
+ * containing a triple-dash (e.g. `title: Q1 --- Q2`) truncated the front-matter
+ * and leaked the rest into the body. An optional leading BOM is tolerated.
+ */
+const YAML_FRONT_MATTER_RE = /^\uFEFF?---\n[\s\S]*?\n---\n?/;
+
+/**
+ * Normalize a foreign markdown string into Docmost's canonical markdown surface
+ * so the strict canonical parser accepts it losslessly: normalize line endings,
+ * strip a leading YAML front-matter block, then rewrite GFM reference footnotes
+ * into inline footnotes. Add further fixture-driven foreign-surface cases here as
+ * they are found.
+ */
+export function normalizeForeignMarkdown(markdown: string): string {
+  if (!markdown) return markdown;
+  // Normalize CRLF -> LF FIRST. The line-anchored front-matter regex requires a
+  // bare `\n` after the opening `---`, and convertReferenceFootnotes splits on
+  // `\n`; a Windows/CRLF foreign file (`---\r\n…`) would otherwise slip past the
+  // front-matter strip and leak into the body. The canonical parser
+  // (page-file.ts parsePageFile) normalizes the same way before its FRONTMATTER_RE.
+  const src = markdown.replace(/\r\n/g, '\n');
+  const withoutFrontMatter = src.replace(YAML_FRONT_MATTER_RE, '').trimStart();
+  return convertReferenceFootnotes(withoutFrontMatter);
+}

apps/server/test/stubs/tiptap-react.js

@@ -0,0 +1,23 @@
+// Jest stub for @tiptap/react.
+//
+// The server export/import code paths transitively import editor-ext, whose node
+// extensions import from `@tiptap/react`. The real module re-exports all of
+// `@tiptap/core` (headless, safe under node) AND adds React view helpers
+// (`ReactNodeViewRenderer`, …) that eagerly pull in react-dom — which throws
+// `navigator is not defined` under jest's node environment.
+//
+// So this stub DELEGATES to the real `@tiptap/core` (keeping `mergeAttributes`,
+// `Node`, `Mark`, `nodeInputRule`, … working — they are used by
+// `jsonToHtml`/`htmlToJson` on the server) and overrides ONLY the React view
+// helpers with no-ops. Those helpers are referenced solely inside `addNodeView()`
+// — code that runs only in a live browser editor, never on the server; if any
+// were actually invoked here it would (correctly) surface as a test failure.
+const core = require('@tiptap/core');
+
+module.exports = {
+  ...core,
+  ReactNodeViewRenderer: () => () => ({}),
+  NodeViewWrapper: () => null,
+  NodeViewContent: () => null,
+  ReactRenderer: class {},
+};

packages/mcp/src/index.ts

@@ -118,19 +118,56 @@ export function createDocmostMcpServer(config: DocmostMcpConfig): McpServer {
 // transport exposes a `tree:true` mode that returns the full nested hierarchy;
 // the in-app copy keeps the same tree option but is worded for the in-app agent.
 // Kept per-layer so each side can tune its own guidance.
-// Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294). This
-// transport keeps applying its own defaults (limit=50, tree=false) in execute.
-registerShared(SHARED_TOOL_SPECS.listPages, async ({ spaceId, limit, tree }) => {
-  const result = await docmostClient.listPages(spaceId, limit ?? 50, tree ?? false);
-  return jsonContent(result);
-});
+server.registerTool(
+  "list_pages",
+  {
+    description:
+      "List most recent pages in a space ordered by updatedAt (descending). " +
+      "Returns a bounded list (default 50, max 100) — use search for lookups " +
+      "in large spaces. Pass tree:true (with spaceId) to instead get the " +
+      "space's full page hierarchy as a nested tree.",
+    inputSchema: {
+      spaceId: z.string().optional(),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Max pages to return (default 50, max 100)"),
+      tree: z
+        .boolean()
+        .optional()
+        .describe(
+          "When true, return the space's full page hierarchy as a nested tree (each node has a children array) instead of the recent-by-updatedAt flat list. Requires spaceId; ignores limit.",
+        ),
+    },
+  },
+  async ({ spaceId, limit, tree }) => {
+    const result = await docmostClient.listPages(spaceId, limit ?? 50, tree ?? false);
+    return jsonContent(result);
+  },
+);
 
 // Tool: get_page
-// Schema + description now live in the shared registry (#294).
-registerShared(SHARED_TOOL_SPECS.getPage, async ({ pageId }) => {
-  const page = await docmostClient.getPage(pageId);
-  return jsonContent(page);
-});
+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. 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),
+    },
+  },
+  async ({ pageId }) => {
+    const page = await docmostClient.getPage(pageId);
+    return jsonContent(page);
+  },
+);
 
 // Tool: get_page_json
 registerShared(SHARED_TOOL_SPECS.getPageJson, async ({ pageId }) => {
@@ -164,10 +201,6 @@ registerShared(
 );
 
 // Tool: table_get
-// NOT in the shared registry: the MCP tool name `table_get` is noun-first while
-// the in-app key is `getTable` (verb-first), breaking the snake_case(inAppKey)
-// convention the shared registry enforces (shared-tool-specs.contract.spec.ts).
-// Renaming the public MCP tool would break external clients, so it stays inline.
 server.registerTool(
   "table_get",
   {
@@ -190,10 +223,25 @@ server.registerTool(
 );
 
 // Tool: table_insert_row
-// Schema + description now live in the shared registry (#294); the `table`
-// parameter name is the canonical one (the in-app layer was unified to it).
-registerShared(
-  SHARED_TOOL_SPECS.tableInsertRow,
+// NOT in the shared registry: this transport names the table argument `table`,
+// while the in-app tool names it `tableRef` (ai-chat-tools.service.ts). Sharing
+// one buildShape would rename a public MCP parameter, so the table row/cell
+// tools stay per-transport by design.
+server.registerTool(
+  "table_insert_row",
+  {
+    description:
+      "Insert a row of plain-text cells into a table. `table` = `#<index>` or " +
+      "a block id inside it. `cells` = text per column (padded to the table's " +
+      "column count; error if more cells than columns). `index` = 0-based " +
+      "insert position (0 inserts before the header); omit to append at the end.",
+    inputSchema: {
+      pageId: z.string().min(1),
+      table: z.string().min(1),
+      cells: z.array(z.string()),
+      index: z.number().int().optional(),
+    },
+  },
   async ({ pageId, table, cells, index }) => {
     const result = await docmostClient.tableInsertRow(
       pageId,
@@ -206,9 +254,22 @@ registerShared(
 );
 
 // Tool: table_delete_row
-// Schema + description now live in the shared registry (#294).
-registerShared(
-  SHARED_TOOL_SPECS.tableDeleteRow,
+// NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
+// divergence as table_insert_row.
+server.registerTool(
+  "table_delete_row",
+  {
+    description:
+      "Delete the row at 0-based `index` from a table (`table` = `#<index>` or " +
+      "a block id inside it). Refuses to delete the table's only row. An " +
+      "out-of-range `index` throws. Deleting `index` 0 removes the header row, " +
+      "and the next row becomes the new header.",
+    inputSchema: {
+      pageId: z.string().min(1),
+      table: z.string().min(1),
+      index: z.number().int(),
+    },
+  },
   async ({ pageId, table, index }) => {
     const result = await docmostClient.tableDeleteRow(pageId, table, index);
     return jsonContent(result);
@@ -216,9 +277,24 @@ registerShared(
 );
 
 // Tool: table_update_cell
-// Schema + description now live in the shared registry (#294).
-registerShared(
-  SHARED_TOOL_SPECS.tableUpdateCell,
+// NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
+// divergence as table_insert_row.
+server.registerTool(
+  "table_update_cell",
+  {
+    description:
+      "Set the plain-text content of cell [row,col] (0-based) in a table " +
+      "(`table` = `#<index>` or a block id inside it). Replaces the cell's " +
+      "content with a single text paragraph; for rich formatting use patch_node " +
+      "on the cell's paragraph id from table_get.",
+    inputSchema: {
+      pageId: z.string().min(1),
+      table: z.string().min(1),
+      row: z.number().int(),
+      col: z.number().int(),
+      text: z.string(),
+    },
+  },
   async ({ pageId, table, row, col, text }) => {
     const result = await docmostClient.tableUpdateCell(
       pageId,
@@ -232,9 +308,22 @@ registerShared(
 );
 
 // Tool: create_page
-// Schema + description now live in the shared registry (#294).
-registerShared(
-  SHARED_TOOL_SPECS.createPage,
+server.registerTool(
+  "create_page",
+  {
+    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"),
+      spaceId: z.string().min(1),
+      parentPageId: z
+        .string()
+        .optional()
+        .describe("Optional parent page ID to nest under"),
+    },
+  },
   async ({ title, content, spaceId, parentPageId }) => {
     const result = await docmostClient.createPage(
       title,
@@ -247,11 +336,32 @@ registerShared(
 );
 
 // Tool: update_page_json
-// Schema + description now live in the shared registry (#294). The execute body
-// keeps this transport's content normalization (parse a JSON-string content,
-// pass undefined/null through for a title-only/no-op update).
-registerShared(
-  SHARED_TOOL_SPECS.updatePageJson,
+server.registerTool(
+  "update_page_json",
+  {
+    description:
+      "Replace a page's content with a raw ProseMirror JSON document " +
+      "(lossless write: preserves the block ids, callouts, tables and " +
+      "attributes you pass in). Typical flow: get_page_json -> modify the " +
+      "JSON -> update_page_json. Keep existing node ids intact so heading " +
+      "anchors and history stay stable. Minimal full-doc example: " +
+      '{"type":"doc","content":[{"type":"paragraph","content":' +
+      '[{"type":"text","text":"Hi"}]}]}. `content` may be a JSON object or a ' +
+      "JSON string (both accepted), and is OPTIONAL: omit it to update only " +
+      "the title (though prefer rename_page for a title-only change). " +
+      "Supplying neither content nor title is an error.",
+    inputSchema: {
+      pageId: z.string().min(1).describe("ID of the page to update"),
+      content: z
+        .any()
+        .optional()
+        .describe(
+          'ProseMirror document {"type":"doc","content":[...]} (JSON object or ' +
+            "JSON string). Omit to rename only.",
+        ),
+      title: z.string().optional().describe("Optional new title"),
+    },
+  },
   async ({ pageId, content, title }) => {
     // Only parse/validate the document when it was actually supplied; when it
     // is omitted, pass it straight through so the client performs a title-only
@@ -269,11 +379,26 @@ registerShared(
 );
 
 // Tool: export_page_markdown
-// Schema + description now live in the shared registry (#294).
-registerShared(SHARED_TOOL_SPECS.exportPageMarkdown, async ({ pageId }) => {
-  const md = await docmostClient.exportPageMarkdown(pageId);
-  return { content: [{ type: "text" as const, text: md }] };
-});
+server.registerTool(
+  "export_page_markdown",
+  {
+    description:
+      "Export a page to a single self-contained, lossless Docmost-flavoured " +
+      "Markdown file (custom extensions): YAML-free meta header, body with " +
+      "inline comment anchors and diagrams, and a trailing comments-thread " +
+      "block. Designed for a download -> edit body -> import_page_markdown " +
+      "round-trip that preserves everything, including comment highlights. " +
+      "Comment THREADS are preserved in the file but are not re-pushed to the " +
+      "server on import.",
+    inputSchema: {
+      pageId: z.string().min(1),
+    },
+  },
+  async ({ pageId }) => {
+    const md = await docmostClient.exportPageMarkdown(pageId);
+    return { content: [{ type: "text" as const, text: md }] };
+  },
+);
 
 // Tool: import_page_markdown
 registerShared(
@@ -297,11 +422,22 @@ registerShared(
 );
 
 // Tool: rename_page
-// Schema + description now live in the shared registry (#294).
-registerShared(SHARED_TOOL_SPECS.renamePage, async ({ pageId, title }) => {
-  const result = await docmostClient.renamePage(pageId, title);
-  return jsonContent(result);
-});
+server.registerTool(
+  "rename_page",
+  {
+    description:
+      "Rename a page (change its title only) without touching or resending " +
+      "its content.",
+    inputSchema: {
+      pageId: z.string().min(1).describe("ID of the page to rename"),
+      title: z.string().min(1).describe("New title"),
+    },
+  },
+  async ({ pageId, title }) => {
+    const result = await docmostClient.renamePage(pageId, title);
+    return jsonContent(result);
+  },
+);
 
 // Tool: edit_page_text
 registerShared(SHARED_TOOL_SPECS.editPageText, async ({ pageId, edits }) => {
@@ -380,10 +516,6 @@ registerShared(SHARED_TOOL_SPECS.deleteNode, async ({ pageId, nodeId }) => {
 });
 
 // Tool: insert_image
-// MCP-only by design (NOT in the shared registry): the in-app AI-chat agent
-// exposes no image tools (insert/replace), so there is no second layer to unify
-// — a SHARED_TOOL_SPECS entry's tier/catalogLine are in-app metadata and the
-// catalog-partition test forbids a spec without a live in-app tool (#294).
 server.registerTool(
   "insert_image",
   {
@@ -429,7 +561,6 @@ server.registerTool(
 );
 
 // Tool: replace_image
-// MCP-only by design (see insert_image): no in-app equivalent, stays inline.
 server.registerTool(
   "replace_image",
   {
@@ -472,10 +603,25 @@ server.registerTool(
 );
 
 // Tool: share_page
-// Schema + description now live in the shared registry (#294). The execute body
-// keeps this transport's own `searchIndexing ?? true` default.
-registerShared(
-  SHARED_TOOL_SPECS.sharePage,
+// INTENTIONAL per-transport divergence (not shared): the in-app copy adds a
+// security-confirmation framing ("only share when the user explicitly asked,
+// since this exposes the page to anyone with the link") tuned for the in-app
+// 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>. 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
+        .boolean()
+        .optional()
+        .describe("Allow search engines to index the page (default true)"),
+    },
+  },
   async ({ pageId, searchIndexing }) => {
     const result = await docmostClient.sharePage(pageId, searchIndexing ?? true);
     return jsonContent(result);
@@ -495,11 +641,29 @@ registerShared(SHARED_TOOL_SPECS.listShares, async () => {
 });
 
 // Tool: move_page
-// Schema + description now live in the shared registry (#294). The execute body
-// keeps this transport's cycle guard, its 'null'/'' -> null string coercion, and
-// its positive-confirmation check on the move response.
-registerShared(
-  SHARED_TOOL_SPECS.movePage,
+server.registerTool(
+  "move_page",
+  {
+    description:
+      "Move a page under a new parent (nesting) or to the space root.",
+    inputSchema: {
+      pageId: z.string().min(1),
+      parentPageId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe(
+          "Target parent page ID. Pass 'null' or empty string to move to root.",
+        ),
+      position: z
+        .string()
+        .min(5)
+        .optional()
+        .describe(
+          "fractional-index position key; min 5 chars; omit to append at the end.",
+        ),
+    },
+  },
   async ({ pageId, parentPageId, position }) => {
     const finalParentId =
       parentPageId === "" || parentPageId === "null" ? null : parentPageId;
@@ -534,22 +698,49 @@ registerShared(
 );
 
 // Tool: delete_page
-// Schema + description now live in the shared registry (#294). The shared schema
-// exposes ONLY pageId, so no permanent/force-delete flag can reach the client.
-registerShared(SHARED_TOOL_SPECS.deletePage, async ({ pageId }) => {
-  await docmostClient.deletePage(pageId);
-  return {
-    content: [
-      { type: "text" as const, text: `Successfully deleted page ${pageId}` },
-    ],
-  };
-});
+server.registerTool(
+  "delete_page",
+  {
+    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),
+    },
+  },
+  async ({ pageId }) => {
+    await docmostClient.deletePage(pageId);
+    return {
+      content: [
+        { type: "text" as const, text: `Successfully deleted page ${pageId}` },
+      ],
+    };
+  },
+);
 
 // --- Comment tools (ported from upstream PR #3 by Max Nikitin) ---
 
 // Tool: list_comments
-registerShared(
-  SHARED_TOOL_SPECS.listComments,
+server.registerTool(
+  "list_comments",
+  {
+    description:
+      "List comments on a page in one call (pagination is handled " +
+      "internally). By DEFAULT only ACTIVE threads are returned; resolved " +
+      "threads (a resolved top-level comment and all its replies) are hidden " +
+      "and their count reported as `resolvedThreadsHidden` so you can re-query " +
+      "with `includeResolved: true` to see everything. Returns " +
+      "`{ items, resolvedThreadsHidden }`. Content is returned as Markdown.",
+    inputSchema: {
+      pageId: z.string().describe("ID of the page"),
+      includeResolved: z
+        .boolean()
+        .optional()
+        .describe(
+          "default only active threads; true — include resolved",
+        ),
+    },
+  },
   async ({ pageId, includeResolved }) => {
     const comments = await docmostClient.listComments(pageId, includeResolved);
     return jsonContent(comments);
@@ -557,11 +748,55 @@ registerShared(
 );
 
 // Tool: create_comment
-// Schema + description now live in the shared registry (#294). The execute body
-// keeps this transport's own guards (require a selection for a top-level
-// comment; reject suggestedText on a reply / without a selection).
-registerShared(
-  SHARED_TOOL_SPECS.createComment,
+// INTENTIONAL per-transport divergence (not shared): the in-app copy tunes the
+// guidance for the in-app agent (e.g. "retry with a corrected EXACT selection"
+// and "Reversible via the comment UI"); this transport keeps its own wording.
+server.registerTool(
+  "create_comment",
+  {
+    description:
+      "Create a new comment on a page. The comment is ALWAYS inline and is " +
+      "anchored to (highlights) its `selection` text — there are no page-level " +
+      "comments. Content is provided as Markdown and automatically converted. " +
+      "A top-level comment REQUIRES an exact `selection`; if the selection " +
+      "cannot be found in the page the call fails (no orphan comment is left). " +
+      "Replies (parentCommentId set) inherit the parent's anchor and take no " +
+      "selection. You may also attach a `suggestedText` proposing a replacement " +
+      "for the `selection`; a human applies (or rejects) it from the UI. When " +
+      "`suggestedText` is set the `selection` MUST occur exactly once in the " +
+      "page — expand it with surrounding context if it is ambiguous.",
+    inputSchema: {
+      pageId: z.string().describe("ID of the page to comment on"),
+      content: z.string().min(1).describe("Comment content in Markdown format"),
+      selection: z
+        .string()
+        .min(1)
+        // Enforce the documented 250-char cap to match the description above.
+        .max(250)
+        .optional()
+        .describe(
+          "EXACT contiguous text from a single paragraph/block to anchor the " +
+            "comment on (<=250 chars). Required for a top-level comment; omit " +
+            "only when replying via parentCommentId.",
+        ),
+      parentCommentId: z
+        .string()
+        .optional()
+        .describe("Parent comment ID to create a reply (max 2 nesting levels)"),
+      suggestedText: z
+        .string()
+        .min(1)
+        .max(2000)
+        .optional()
+        .describe(
+          "Optional proposed replacement (PLAIN TEXT) for the `selection`, " +
+            "applied by a human via the UI (never auto-applied). REQUIRES a " +
+            "`selection`; NOT allowed on a reply. When set, the `selection` must " +
+            "be UNIQUE in the page — expand it with surrounding context (still " +
+            "<=250 chars) if it occurs more than once, or the call is refused.",
+        ),
+    },
+  },
   async ({ pageId, content, selection, parentCommentId, suggestedText }) => {
     if (!parentCommentId && (!selection || !selection.trim())) {
       throw new Error(
@@ -637,9 +872,28 @@ server.registerTool(
 );
 
 // Tool: resolve_comment
-// Schema + description now live in the shared registry (#294).
-registerShared(
-  SHARED_TOOL_SPECS.resolveComment,
+server.registerTool(
+  "resolve_comment",
+  {
+    description:
+      "Resolve (close) or reopen a comment thread. Only top-level comments can " +
+      "be resolved — the server rejects resolving a reply. Reversible: pass " +
+      "resolved=false to reopen. Resolving keeps the thread and its replies " +
+      "(unlike delete_comment, which permanently removes them).",
+    inputSchema: {
+      commentId: z
+        .string()
+        .min(1)
+        .describe("ID of the top-level comment thread to resolve or reopen"),
+      resolved: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe(
+          "true (default) marks the thread resolved/closed; false reopens it",
+        ),
+    },
+  },
   async ({ commentId, resolved }) => {
     const result = await docmostClient.resolveComment(commentId, resolved);
     return jsonContent(result);
@@ -647,10 +901,30 @@ registerShared(
 );
 
 // Tool: check_new_comments
-// Schema + description now live in the shared registry (#294). The execute body
-// keeps this transport's own guard rejecting an unparseable `since` timestamp.
-registerShared(
-  SHARED_TOOL_SPECS.checkNewComments,
+server.registerTool(
+  "check_new_comments",
+  {
+    description:
+      "Check for new comments across pages in a space since a given timestamp. " +
+      "Optionally scope to a page subtree (folder). Returns only comments " +
+      "created after the specified time.",
+    inputSchema: {
+      spaceId: z.string().describe("Space ID to check for new comments"),
+      since: z
+        .string()
+        .min(1)
+        .describe(
+          "ISO 8601 timestamp — only return comments created after this time (e.g. '2026-03-10T00:00:00Z')",
+        ),
+      parentPageId: z
+        .string()
+        .optional()
+        .describe(
+          "Optional root page ID to scope the check to a subtree (folder). " +
+            "Only pages under this parent will be checked.",
+        ),
+    },
+  },
   async ({ spaceId, since, parentPageId }) => {
     // Reject an unparseable timestamp up front: otherwise the comparison
     // against NaN silently treats every comment as "not new" and the tool
@@ -779,8 +1053,6 @@ server.registerTool(
 );
 
 // Tool: insert_footnote
-// MCP-only by design (see insert_image): the in-app AI-chat agent exposes no
-// footnote tool, so there is no second layer to unify — stays inline (#294).
 server.registerTool(
   "insert_footnote",
   {

packages/mcp/src/tool-specs.ts

@@ -316,34 +316,6 @@ export const SHARED_TOOL_SPECS = {
 
   // --- share management ---
 
-  // Unified from the per-layer inline definitions (#294). Both layers already
-  // carried the "only share when explicitly asked" security framing (the
-  // "per-transport divergence" note on the old inline copies was stale), so
-  // there was no real behavioral divergence to preserve — only wording drift.
-  sharePage: {
-    mcpName: 'share_page',
-    inAppKey: 'sharePage',
-    // CANONICAL: merges the MCP copy's URL-format + idempotency detail with the
-    // in-app copy's reversibility note; keeps the security framing both had.
-    description:
-      'Make a page PUBLICLY accessible (idempotent) and return its public URL ' +
-      '(format: <app>/share/<key>/p/<slugId>). This exposes the page content ' +
-      'to ANYONE with the URL — only share when the user explicitly asked. ' +
-      'Reversible: unshare it later to revoke the public URL.',
-    tier: 'deferred',
-    catalogLine: 'sharePage — make a page publicly accessible and return its URL.',
-    // Reconciled: MCP's stricter .min(1) on pageId kept; field descriptions from
-    // the in-app copy. The MCP execute keeps its own `searchIndexing ?? true`
-    // default (a per-layer concern, not part of the shared schema).
-    buildShape: (z) => ({
-      pageId: z.string().min(1).describe('The id of the page to share.'),
-      searchIndexing: z
-        .boolean()
-        .optional()
-        .describe('Allow public search engines to index it (default true).'),
-    }),
-  },
-
   unsharePage: {
     mcpName: 'unshare_page',
     inAppKey: 'unsharePage',
@@ -537,470 +509,4 @@ export const SHARED_TOOL_SPECS = {
       pageId: z.string().min(1),
     }),
   },
-
-  // --- page tools (unified from the per-layer inline definitions, #294) ---
-  //
-  // Descriptions merge both layers (the MCP copy's richer structural notes + the
-  // in-app copy's "Reversible via history/trash" framing where it added one).
-  // Field constraints keep the MCP copy's stricter .min(1) EXCEPT where the
-  // in-app layer deliberately allowed a looser value (documented per field).
-
-  getPage: {
-    mcpName: 'get_page',
-    inAppKey: 'getPage',
-    description:
-      'Fetch a single page as Markdown by its id. Returns the page title and ' +
-      'its Markdown content. The Markdown conversion is LOSSY (block ids, exact ' +
-      'table/callout structure are approximated); for a lossless representation ' +
-      'use the lossless page-JSON read tool. 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.',
-    tier: 'core',
-    catalogLine: 'getPage — fetch a page as Markdown by its id.',
-    // Reconciled: MCP's stricter .min(1) kept; in-app's more-informative
-    // "(or slugId)" describe kept.
-    buildShape: (z) => ({
-      pageId: z.string().min(1).describe('The id (or slugId) of the page.'),
-    }),
-  },
-
-  listPages: {
-    mcpName: 'list_pages',
-    inAppKey: 'listPages',
-    description:
-      'List the most recent pages (ordered by updatedAt, descending), ' +
-      'optionally scoped to a single space. Returns a bounded list (default ' +
-      '50, max 100) — use search for lookups in large spaces. Pass tree:true ' +
-      "(with spaceId) to instead get the space's full page hierarchy as a " +
-      'nested tree.',
-    tier: 'core',
-    catalogLine: "listPages — list recent pages, or a space's full page tree.",
-    buildShape: (z) => ({
-      spaceId: z
-        .string()
-        .optional()
-        .describe('Optional space id to scope the listing to.'),
-      limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(100)
-        .optional()
-        .describe('Maximum number of pages (default 50, max 100).'),
-      tree: z
-        .boolean()
-        .optional()
-        .describe(
-          "When true, return the space's full page hierarchy as a nested tree " +
-            '(children arrays) instead of the recent-by-updatedAt flat list. ' +
-            'Requires spaceId; ignores limit.',
-        ),
-    }),
-  },
-
-  createPage: {
-    mcpName: 'create_page',
-    inAppKey: 'createPage',
-    description:
-      'Create a new page with a Markdown body in a space, optionally under a ' +
-      'parent page (omit parentPageId to create at the space root). Returns ' +
-      'the new page id and title. Reversible: a page can be moved to trash ' +
-      'later.',
-    tier: 'deferred',
-    catalogLine: 'createPage — create a new page with a Markdown body in a space.',
-    // Reconciled schema DRIFT: the MCP copy pinned `content` to .min(1) while
-    // the in-app copy left it unbounded and DOCUMENTS an empty body as valid
-    // ("may be empty") — creating an empty page to fill in later is a real use
-    // case. The looser (no-min) form is kept, so create_page now also accepts an
-    // empty body (harmless — it creates an empty page) and no previously-valid
-    // in-app input is ever rejected. `title`/`spaceId` keep the MCP .min(1)
-    // (an empty title or space is never valid).
-    buildShape: (z) => ({
-      title: z.string().min(1).describe('The title of the new page.'),
-      content: z.string().describe('The page body as Markdown (may be empty).'),
-      spaceId: z.string().min(1).describe('The id of the space to create the page in.'),
-      parentPageId: z
-        .string()
-        .optional()
-        .describe('Optional parent page id to nest the new page under.'),
-    }),
-  },
-
-  movePage: {
-    mcpName: 'move_page',
-    inAppKey: 'movePage',
-    description:
-      'Move a page under a new parent page, or to the space root when no ' +
-      'parent is given. Reversible: move it back at any time.',
-    tier: 'deferred',
-    catalogLine: 'movePage — move a page under a new parent or to the space root.',
-    // Reconciled schema DRIFT: the MCP copy exposed a `position` field
-    // (fractional-index ordering) that the in-app copy lacked. Unified by
-    // KEEPING position (the in-app client already accepts an optional position
-    // arg, so the in-app execute now forwards it) — it is optional, so no
-    // previously-valid in-app call is rejected. `parentPageId` is `.nullable()`
-    // on both, so a real JSON null moves to root on either transport; the MCP
-    // execute additionally coerces the strings 'null'/'' to null as a robustness
-    // fallback (kept in its execute body, not in the shared schema).
-    buildShape: (z) => ({
-      pageId: z.string().min(1).describe('The id of the page to move.'),
-      parentPageId: z
-        .string()
-        .nullable()
-        .optional()
-        .describe(
-          'Target parent page id. Null or omitted moves the page to the space ' +
-            'root.',
-        ),
-      position: z
-        .string()
-        .min(5)
-        .optional()
-        .describe(
-          'Optional fractional-index position key (min 5 chars); omit to ' +
-            'append at the end.',
-        ),
-    }),
-  },
-
-  renamePage: {
-    mcpName: 'rename_page',
-    inAppKey: 'renamePage',
-    description:
-      'Rename a page (change its title only; the body is untouched, never ' +
-      'resent). Reversible: rename back at any time.',
-    tier: 'deferred',
-    catalogLine: "renamePage — change a page's title only (body untouched).",
-    buildShape: (z) => ({
-      pageId: z.string().min(1).describe('The id of the page to rename.'),
-      title: z.string().min(1).describe('The new title.'),
-    }),
-  },
-
-  deletePage: {
-    mcpName: 'delete_page',
-    inAppKey: 'deletePage',
-    description:
-      'Move a page to the trash — SOFT delete only: the page can be restored ' +
-      'from trash and nothing is ever permanently deleted.',
-    tier: 'deferred',
-    catalogLine: 'deletePage — move a page to trash (soft delete, reversible).',
-    // GUARDRAIL preserved (§14 H4): the schema exposes ONLY pageId, so a
-    // permanentlyDelete/forceDelete flag can never reach the client through this
-    // tool (asserted by ai-chat-tools.service.spec.ts).
-    buildShape: (z) => ({
-      pageId: z.string().min(1).describe('The id of the page to move to trash.'),
-    }),
-  },
-
-  updatePageJson: {
-    mcpName: 'update_page_json',
-    inAppKey: 'updatePageJson',
-    description:
-      "Replace a page's content with a raw ProseMirror JSON document (lossless " +
-      'write: preserves the block ids, callouts, tables and attributes you pass ' +
-      'in). Typical flow: read the page-JSON view -> modify the JSON -> write it back. ' +
-      'Keep existing node ids intact so heading anchors and history stay ' +
-      'stable. Minimal full-doc example: {"type":"doc","content":[{"type":' +
-      '"paragraph","content":[{"type":"text","text":"Hi"}]}]}. `content` may be ' +
-      'a JSON object or a JSON string (both accepted), and is OPTIONAL: omit it ' +
-      'to update only the title (though prefer the rename-page tool for a title-only ' +
-      'change). Supplying neither content nor title is an error. Reversible: ' +
-      'the previous version is kept in page history.',
-    tier: 'deferred',
-    catalogLine:
-      "updatePageJson — overwrite a page's body with a full ProseMirror document.",
-    buildShape: (z) => ({
-      pageId: z.string().min(1).describe('ID of the page to update'),
-      content: z
-        .any()
-        .optional()
-        .describe(
-          'ProseMirror document {"type":"doc","content":[...]} (JSON object or ' +
-            'JSON string). Omit to update only the title.',
-        ),
-      title: z.string().optional().describe('Optional new title'),
-    }),
-  },
-
-  exportPageMarkdown: {
-    mcpName: 'export_page_markdown',
-    inAppKey: 'exportPageMarkdown',
-    // CANONICAL: the MCP copy (a strict superset of the terse in-app wording).
-    description:
-      'Export a page to a single self-contained, lossless Docmost-flavoured ' +
-      'Markdown file (custom extensions): YAML-free meta header, body with ' +
-      'inline comment anchors and diagrams, and a trailing comments-thread ' +
-      'block. Designed for a download -> edit body -> page-Markdown import ' +
-      'round-trip that preserves everything, including comment highlights. ' +
-      'Comment THREADS are preserved in the file but are not re-pushed to the ' +
-      'server on import.',
-    tier: 'deferred',
-    catalogLine:
-      'exportPageMarkdown — export a page to self-contained Markdown (body + comments).',
-    buildShape: (z) => ({
-      pageId: z.string().min(1).describe('The id of the page to export.'),
-    }),
-  },
-
-  // --- comment tools (unified from the per-layer inline definitions, #294) ---
-  //
-  // create_comment and resolve_comment previously carried a "per-transport
-  // divergence" note in BOTH layers; #294 unifies their schema + description
-  // here. Only the four tools that genuinely exist in BOTH layers live in the
-  // registry: create/list/resolve comment and check_new_comments.
-  //
-  // update_comment and delete_comment are intentionally NOT here: they exist
-  // ONLY on the standalone MCP server. The in-app agent deliberately exposes no
-  // hard comment edit/delete tool (comment edits are irreversible / not
-  // version-tracked; see the guardrail tests in ai-chat-tools.service.spec.ts),
-  // so there is nothing to unify — they stay inline in index.ts.
-
-  createComment: {
-    mcpName: 'create_comment',
-    inAppKey: 'createComment',
-    // CANONICAL: the in-app copy (the more-maintained one). It keeps the same
-    // rules as the MCP copy — inline-only, top-level requires a `selection`, no
-    // page-level comments, replies inherit the anchor, suggestedText must be
-    // unique — and adds the "retry with a corrected EXACT selection" and reply-
-    // to-reply-rejected guidance the MCP copy lacked. Execute-side validation
-    // (reject suggestedText on a reply, require a selection) stays per-layer.
-    description:
-      'Add an INLINE comment to a page, or reply to an existing top-level ' +
-      'comment (one level only — the backend rejects replies to replies). ' +
-      'The comment is anchored inline to the given exact `selection` text ' +
-      '(which gets highlighted); page-level comments are NOT supported. A ' +
-      'new top-level comment REQUIRES a `selection`. Replies inherit the ' +
-      "parent's anchor and take no selection. If the call fails with a " +
-      '"selection not found" error, retry with a corrected EXACT selection ' +
-      'copied verbatim from a single paragraph/block. You may also attach a ' +
-      '`suggestedText` proposing a replacement for the `selection` (a human ' +
-      'applies it from the UI); when set, the `selection` must occur exactly ' +
-      'once in the page. Reversible via the comment UI.',
-    tier: 'core',
-    catalogLine:
-      'createComment — add an inline comment (optionally with a suggested edit).',
-    // Reconciled schema: the field set is identical across both layers; the
-    // only constraint drift is `content`, which the MCP copy pinned to
-    // .min(1) while the in-app copy left unbounded — the stricter MCP form is
-    // kept (an empty comment body is never valid).
-    buildShape: (z) => ({
-      pageId: z.string().describe('The id of the page to comment on.'),
-      content: z.string().min(1).describe('The comment body as Markdown.'),
-      selection: z
-        .string()
-        .min(1)
-        .max(250)
-        .optional()
-        .describe(
-          'EXACT contiguous text from a SINGLE paragraph/block to anchor ' +
-            '(highlight) the comment on (<=250 chars, avoid spanning across ' +
-            'formatting boundaries). Required for a new top-level comment; ' +
-            'omit only when replying via parentCommentId.',
-        ),
-      parentCommentId: z
-        .string()
-        .optional()
-        .describe(
-          'Optional id of a TOP-LEVEL comment to reply to (one level ' +
-            'of replies only).',
-        ),
-      suggestedText: z
-        .string()
-        .min(1)
-        .max(2000)
-        .optional()
-        .describe(
-          'Optional proposed replacement (PLAIN TEXT) for the `selection`, ' +
-            'applied by a human via the UI (never auto-applied). REQUIRES a ' +
-            '`selection`; NOT allowed on a reply. When set, the `selection` ' +
-            'must be UNIQUE in the page — expand it with surrounding context ' +
-            '(still <=250 chars) if it occurs more than once, or the call is ' +
-            'refused.',
-        ),
-    }),
-  },
-
-  listComments: {
-    mcpName: 'list_comments',
-    inAppKey: 'listComments',
-    // CANONICAL: the two copies are near-identical; the MCP copy is the
-    // superset (it keeps the "(pagination is handled internally)" note the
-    // in-app copy dropped), so it is used verbatim.
-    description:
-      'List comments on a page in one call (pagination is handled ' +
-      'internally). By DEFAULT only ACTIVE threads are returned; resolved ' +
-      'threads (a resolved top-level comment and all its replies) are hidden ' +
-      'and their count reported as `resolvedThreadsHidden` so you can re-query ' +
-      'with `includeResolved: true` to see everything. Returns ' +
-      '`{ items, resolvedThreadsHidden }`. Content is returned as Markdown.',
-    tier: 'core',
-    catalogLine:
-      'listComments — list all comments on a page (including resolved).',
-    buildShape: (z) => ({
-      pageId: z.string().describe('ID of the page'),
-      includeResolved: z
-        .boolean()
-        .optional()
-        .describe('default only active threads; true — include resolved'),
-    }),
-  },
-
-  resolveComment: {
-    mcpName: 'resolve_comment',
-    inAppKey: 'resolveComment',
-    // CANONICAL: the MCP copy's richer wording, minus its snake_case reference
-    // to `delete_comment` (a sibling tool that does NOT exist in the in-app
-    // layer) — rephrased transport-neutrally per the registry convention.
-    description:
-      'Resolve (close) or reopen a top-level comment thread (reversible — ' +
-      'pass resolved=false to reopen). Only top-level comments can be ' +
-      'resolved; the server rejects resolving a reply. Resolving keeps the ' +
-      'thread and its replies intact (it is not a deletion).',
-    tier: 'core',
-    catalogLine: 'resolveComment — resolve or reopen a comment thread.',
-    // Reconciled schema: `resolved` drifted — the MCP copy made it optional
-    // with .default(true) (resolve is the common case, documented), the in-app
-    // copy made it required. The MCP form is kept (a strict superset: it never
-    // rejects a previously-valid input and adds a sensible default), and
-    // commentId keeps the MCP copy's stricter .min(1).
-    buildShape: (z) => ({
-      commentId: z
-        .string()
-        .min(1)
-        .describe('ID of the top-level comment thread to resolve or reopen'),
-      resolved: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe(
-          'true (default) marks the thread resolved/closed; false reopens it',
-        ),
-    }),
-  },
-
-  checkNewComments: {
-    mcpName: 'check_new_comments',
-    inAppKey: 'checkNewComments',
-    // CANONICAL: the MCP copy (the more detailed of the two). The MCP layer's
-    // execute-side guard that rejects an unparseable `since` timestamp stays in
-    // its execute body (per-layer logic), not in the shared schema.
-    description:
-      'Check for new comments across pages in a space since a given ' +
-      'timestamp. Optionally scope to a page subtree (folder). Returns only ' +
-      'comments created after the specified time.',
-    tier: 'deferred',
-    catalogLine:
-      'checkNewComments — find comments in a space created after a timestamp.',
-    // Reconciled schema: `since` keeps the MCP copy's stricter .min(1) (the
-    // in-app copy left it unbounded); field descriptions use the MCP copy's
-    // more detailed wording (it carries an example timestamp).
-    buildShape: (z) => ({
-      spaceId: z.string().describe('Space ID to check for new comments'),
-      since: z
-        .string()
-        .min(1)
-        .describe(
-          "ISO 8601 timestamp — only return comments created after this time " +
-            "(e.g. '2026-03-10T00:00:00Z')",
-        ),
-      parentPageId: z
-        .string()
-        .optional()
-        .describe(
-          'Optional root page ID to scope the check to a subtree (folder). ' +
-            'Only pages under this parent will be checked.',
-        ),
-    }),
-  },
-
-  // --- table tools (unified from the per-layer inline definitions, #294) ---
-  //
-  // These tools carried a "NOT shared" note in BOTH layers because of a single
-  // parameter-NAME drift: the MCP layer named the table reference `table` while
-  // the in-app layer named it `tableRef`. #294 reconciles that drift by unifying
-  // on the MCP name `table` — renaming the MCP public parameter would break
-  // external MCP clients, whereas the in-app parameter is model-facing
-  // (prompt-only) and safe to rename. The in-app execute bodies now destructure
-  // `table` instead of `tableRef` (nothing else changes). Descriptions take the
-  // MCP copy's richer wording (it documented `#<index>`, padding, header-row
-  // behavior) plus the in-app copy's "Reversible via page history" note; sibling
-  // tool references are phrased transport-neutrally.
-  //
-  // NOT here (kept inline in index.ts): table_get / getTable. Its MCP tool name
-  // is noun-first (`table_get`) while the in-app key is verb-first (`getTable`),
-  // so it breaks the snake_case(inAppKey) naming convention the registry enforces
-  // (shared-tool-specs.contract.spec.ts). Renaming the public MCP tool would
-  // break external clients, so it stays per-transport (its in-app param was still
-  // aligned to `table` for consistency with the migrated trio below).
-
-  tableInsertRow: {
-    mcpName: 'table_insert_row',
-    inAppKey: 'tableInsertRow',
-    description:
-      'Insert a row of plain-text cells into a table. `table` is `#<index>` ' +
-      'from the page outline, or a block id inside it. `cells` is the text per ' +
-      "column (padded to the table's column count; an error if more cells than " +
-      'columns). `index` is the 0-based insert position (0 inserts before the ' +
-      'header); omit to append at the end. Reversible via page history.',
-    tier: 'deferred',
-    catalogLine: 'tableInsertRow — insert a row of plain-text cells into a table.',
-    buildShape: (z) => ({
-      pageId: z.string().min(1).describe('The id of the page.'),
-      table: z
-        .string()
-        .min(1)
-        .describe('"#<index>" from the page outline, or a block id in the table.'),
-      cells: z.array(z.string()).describe('The cell texts for the row (one per column).'),
-      index: z
-        .number()
-        .int()
-        .optional()
-        .describe('0-based insert position (0 inserts before the header); omit to append.'),
-    }),
-  },
-
-  tableDeleteRow: {
-    mcpName: 'table_delete_row',
-    inAppKey: 'tableDeleteRow',
-    description:
-      'Delete the row at 0-based `index` from a table (`table` is `#<index>` ' +
-      'from the page outline, or a block id inside it). Refuses to delete the ' +
-      "table's only row; an out-of-range `index` throws. Deleting `index` 0 " +
-      'removes the header row, and the next row becomes the new header. ' +
-      'Reversible via page history.',
-    tier: 'deferred',
-    catalogLine: 'tableDeleteRow — delete a table row at a 0-based index.',
-    buildShape: (z) => ({
-      pageId: z.string().min(1).describe('The id of the page.'),
-      table: z
-        .string()
-        .min(1)
-        .describe('"#<index>" from the page outline, or a block id in the table.'),
-      index: z.number().int().describe('0-based row index to delete.'),
-    }),
-  },
-
-  tableUpdateCell: {
-    mcpName: 'table_update_cell',
-    inAppKey: 'tableUpdateCell',
-    description:
-      'Set the plain-text content of cell [row, col] (0-based) in a table ' +
-      '(`table` is `#<index>` from the page outline, or a block id inside it). ' +
-      "Replaces the cell's content with a single text paragraph; for rich " +
-      "formatting, patch the cell's paragraph id (obtained from reading the " +
-      'table) instead. Reversible via page history.',
-    tier: 'deferred',
-    catalogLine: 'tableUpdateCell — set the text of a table cell at [row, col].',
-    buildShape: (z) => ({
-      pageId: z.string().min(1).describe('The id of the page.'),
-      table: z
-        .string()
-        .min(1)
-        .describe('"#<index>" from the page outline, or a block id in the table.'),
-      row: z.number().int().describe('0-based row index.'),
-      col: z.number().int().describe('0-based column index.'),
-      text: z.string().describe('The new cell text.'),
-    }),
-  },
 } satisfies Record<string, SharedToolSpec>;

pnpm-lock.yaml

@@ -543,6 +543,9 @@ importers:
       '@docmost/pdf-inspector':
         specifier: 1.9.6
         version: 1.9.6
+      '@docmost/prosemirror-markdown':
+        specifier: workspace:*
+        version: link:../../packages/prosemirror-markdown
       '@fastify/cookie':
         specifier: ^11.0.2
         version: 11.0.2