fix(mcp): pre-validate node JSON против схемы + путь битого узла (#409 , остаток Фазы 1)

Структурные редакторы (patchNode/insertNode/updatePageJson/transformPage) кидали опаковый Yjs-крах на агентском JSON с вложенным узлом без/с неизвестным `type`: «Failed to encode document to Yjs (fromJSON): Unknown node type: undefined» — ГЛУБОКО в энкодере, уже ПОСЛЕ открытия collab-сессии, а хинт мислейблил это как проблему атрибута. Агент ретраил вслепую (~34 краха в истории 06-17…07-07). - findInvalidNode(doc) в prosemirror-markdown/node-ops.ts: DFS по content, возвращает {path, summary} первого узла с отсутствующим/не-строковым `type` или типом/маркой вне схемы. Множество имён — из getSchema(docmostExtensions), ТОГО ЖЕ, из которого энкод-путь строит docmostSchema → «известный тип» обходчика ровно то, что примет PMNode.fromJSON/toYdoc (сверено на 45 узлах + 12 марках, ни ложных положительных, ни пропуска краш-типа). - unstorableYjsError: findInvalidNode ПЕРВЫМ (node-shape крах больше не мислейблится как атрибут), затем findUnstorableAttr, generic-фраза последней. - assertValidNodeShape(op, node) ДО getCollabTokenWithReauth/mutatePageContent в patchNode/insertNode/updatePageJson: fail-fast — collab-сессия не открывается, page-lock не берётся, сообщение детерминировано (mock-тест ассертит collabTokenFetched===false на битом пути). tableUpdateCell не тронут (строит абзац из plain text через makeCellParagraph, агентский JSON не глотает). - Описания patch_node/insert_node/update_page_json: каждый узел, включая вложенные, несёт строковый `type` из схемы; текст-листы {"type":"text",...}. sanitizeForYjs (стрип undefined-атрибутов) сохранён — другой класс отказа. Внутреннее ревью: APPROVE WITH SUGGESTIONS — schema-fidelity/fail-fast/ no-false-positive/precedence подтверждены; замечания необязательны (тест перечисления схемы, depth-guard безобиден т.к. энкодер падает раньше). prosemirror-markdown vitest 726/726, mcp node --test 613/613. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-10 10:49:51 +03:00
27 changed files with 2163 additions and 1820 deletions
@@ -1,13 +1,5 @@
 name: Test

-# NO `paths:` filter on purpose (issue #447). The tool-spec REGISTRY is split
-# across two packages that MUST stay in sync: the specs live in `packages/mcp`
-# but the parity/tier guard tests that read them live in the `apps/server` jest
-# suite. A PR touching only `packages/mcp/**` must therefore still run the SERVER
-# suite (and vice-versa), or an in-app wiring break slips through green and only
-# surfaces on develop after merge. The `test` job below runs BOTH suites via
-# `pnpm -r test` on every PR; the dedicated `mcp-server-parity` job makes that
-# cross-package gate explicit and fast. Do not add a `paths:` filter here.
 on:
  pull_request:
  workflow_call:
@@ -140,53 +132,3 @@ jobs:
      # isolated `docmost_test` DB and migrates it to latest.
      - name: Run server integration tests
        run: pnpm --filter server test:int
-
-  # Cross-package tool-spec parity gate (issue #447). The tool-spec registry lives
-  # in `packages/mcp` but its parity/tier guard tests live in the `apps/server`
-  # jest suite, so a PR touching ONLY one of the two packages must still run BOTH
-  # sides — otherwise an in-app wiring break (e.g. PR #434 drawio) passes the mcp
-  # suite green and only surfaces on develop after merge. The `test` job already
-  # runs everything via `pnpm -r test`; this job is a fast, explicitly-named guard
-  # that runs the mcp `node --test` suite AND the server tool-guard jest specs
-  # together, so the coupling is visible and can never be accidentally split by a
-  # path filter. No Postgres/Redis needed: these specs mock the DB/loader.
-  mcp-server-parity:
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      # Shared deps first (build/ dirs are gitignored; see test.yml build order).
-      - name: Build editor-ext
-        run: pnpm --filter @docmost/editor-ext build
-
-      - name: Build prosemirror-markdown
-        run: pnpm --filter @docmost/prosemirror-markdown build
-
-      # Build the mcp package so build/ carries a FRESH REGISTRY_STAMP (#447): the
-      # build runs gen-registry-stamp.mjs before tsc, so a build/ vs src/ skew
-      # cannot slip into the tests that exercise the loader's stale-check.
-      - name: Build mcp (regenerates REGISTRY_STAMP)
-        run: pnpm --filter @docmost/mcp build
-
-      # mcp side: the standalone MCP server's own tool-spec / instructions guards.
-      - name: Run mcp tool-spec suite
-        run: pnpm --filter @docmost/mcp test
-
-      # server side: the parity + tier guards that read packages/mcp/src/tool-specs
-      # and assert the in-app AI-chat wiring matches it.
-      - name: Run server tool-spec guard specs
-        run: pnpm --filter server exec jest shared-tool-specs.contract tool-tiers ai-chat-tools.service --runInBand
@@ -19,11 +19,6 @@ packages/prosemirror-markdown/build/
 # markdown convention; the package is private and rebuilt at deploy.
 packages/mcp/build/

-# mcp REGISTRY_STAMP codegen output (issue #447). Regenerated into src/ by
-# scripts/gen-registry-stamp.mjs on every `build`/`pretest` (before tsc), so it
-# is a build artifact like build/ — never committed, always fresh.
-packages/mcp/src/registry-stamp.generated.ts
-
 # Logs
 logs
 *.log
@@ -248,22 +248,6 @@ pnpm collab:dev              # run the collaboration server process standalone (
 > that order). Reach for it whenever you run a consumer package's checks on their
 > own rather than through the full `pnpm build`.

-> **Editing an MCP tool spec requires a rebuild (issue #447).** The running
-> server loads the **compiled** `packages/mcp/build/` of `@docmost/mcp` (via the
-> runtime loader in `apps/server/src/core/ai-chat/tools/docmost-client.loader.ts`),
-> but the parity/tier guard tests read `packages/mcp/src/tool-specs.ts`. So if you
-> edit `tool-specs.ts` (any tool name, description, tier, catalog line, or input
-> schema) **without rebuilding**, `build/` and `src/` silently diverge — the tests
-> stay green while the server serves the OLD tools. To close that gap, the build
-> emits a `REGISTRY_STAMP` (a deterministic hash of the tool-specs content, via
-> `scripts/gen-registry-stamp.mjs` before `tsc`); on dev/test startup the loader
-> recomputes it from `src/` and **refuses to start with a "@docmost/mcp build is
-> stale …" error** on a mismatch (a pure no-op in prod, where only `build/` ships).
-> After editing tool specs, rebuild:
-> ```bash
-> pnpm --filter @docmost/mcp build     # or: pnpm --filter @docmost/mcp watch
-> ```
-
 **Lint** (per package — there is no root lint script):
 ```bash
 pnpm --filter server lint    # eslint --fix on server .ts
@@ -338,7 +322,7 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 - The version string shown in the UI comes from `APP_VERSION` (CI/Docker) or `git describe --tags --always` (local), resolved in `vite.config.ts` — not from `package.json`.
 - Server TS config is permissive (`noImplicitAny: false`, `strictNullChecks: false`, `no-explicit-any` lint disabled). Follow the existing relaxed style rather than tightening types broadly.
 - Dependency versions are heavily pinned via `pnpm.overrides` and `pnpm.patchedDependencies` (`scimmy`, `yjs`, `ai`) in the root `package.json`. Don't bump pinned/patched deps casually; the patches and overrides exist for compatibility/security reasons. The `ai@6.0.134` patch disables the SDK's O(n²) cumulative `partialOutput` accumulation when no output strategy is requested (server heap OOM on long agent runs, #184; tripwire test: `apps/server/src/integrations/ai/ai-sdk-partial-output.patch.spec.ts`) — it MUST be re-created via `pnpm patch` when bumping `ai`.
- **The MCP tool inventory in `SERVER_INSTRUCTIONS` is GENERATED from the registry** (`packages/mcp/src/server-instructions.ts`: `buildToolInventory()` over `SHARED_TOOL_SPECS`) and spliced into the hand-written routing prose (`ROUTING_PROSE`). So adding/renaming/removing a **shared** spec in `packages/mcp/src/tool-specs.ts` auto-updates the `<tool_inventory>` — no manual `SERVER_INSTRUCTIONS` edit needed. Only an **inline** MCP-only tool (those registered via `server.registerTool(...)` in `index.ts`, not through the registry) needs a one-line entry in `INLINE_MCP_INVENTORY`. Enforced by `packages/mcp/test/unit/tool-inventory.test.mjs`, which fails when a registered tool is missing from the generated inventory (there is no `EXCEPTIONS` opt-out anymore — every tool must appear). Update `ROUTING_PROSE` when a tool's *intent guidance* (when-to-use) changes. `packages/mcp/build/` is gitignored and rebuilt in CI/Docker via `pnpm build` (same convention as `git-sync`/`prosemirror-markdown`) — never commit it; rebuild locally after editing to run the tests.
+- **Adding/renaming/removing an MCP tool requires updating `SERVER_INSTRUCTIONS`** in `packages/mcp/src/index.ts` — the intent-routing guide MCP clients receive on initialize. This applies both to inline `server.registerTool(...)` calls in `index.ts` and to specs in `packages/mcp/src/tool-specs.ts`. Enforced by `packages/mcp/test/unit/server-instructions.test.mjs`, which fails when a registered tool is not mentioned in the guide (deliberate opt-outs go into its `EXCEPTIONS` list). `packages/mcp/build/` is gitignored and rebuilt in CI/Docker via `pnpm build` (same convention as `git-sync`/`prosemirror-markdown`) — never commit it; rebuild locally after editing to run the tests.

 ## CI / release

@@ -1,125 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { PROMPT_TOOL_NAMES } from './ai-chat.prompt';
-// The real shared registry, imported from source (same approach as the
-// SHARED_TOOL_SPECS contract spec) so tool names are validated against exactly
-// what @docmost/mcp ships.
-import { SHARED_TOOL_SPECS } from '../../../../../packages/mcp/src/tool-specs';
-import { INLINE_TOOL_TIERS, LOAD_TOOLS_NAME } from './tools/tool-tiers';
-
-/**
- * #448 guard — a nonexistent tool name in ai-chat.prompt.ts must fail a test.
- *
- * The in-app prompt refers to a handful of tools BY NAME in its guidance notes
- * (e.g. PAGE_CHANGED_NOTE tells the agent to re-read via getPage and edit via
- * editPageText/patchNode/insertNode/deleteNode). Before #448 those names were
- * hard-coded inline with NO guard, so renaming a tool left the agent stale
- * instructions and nothing failed.
- *
- * APPROACH — substitution + a precise source scan:
- *  1. The names now flow through the exported `PROMPT_TOOL_NAMES` const; this
- *     test asserts every value there is a REAL in-app tool.
- *  2. A precise scan of the two guidance-note string literals in the source
- *     catches any BARE tool-name token added directly (bypassing the const):
- *     every camelCase token in those notes must be either a real tool name or an
- *     explicitly-allowlisted ordinary English/camelCase word.
- *
- * The scan is deliberately narrow (only the guidance notes, only camelCase
- * tokens) so it never false-positives on prose, and the allowlist of non-tool
- * words is tiny and explicit.
- */
-
-// The authoritative set of real in-app tool names: shared-registry inAppKeys +
-// per-layer INLINE tool keys + the loadTools meta-tool.
-const VALID_TOOL_NAMES = new Set<string>([
-  ...Object.values(SHARED_TOOL_SPECS).map((s) => s.inAppKey),
-  ...Object.keys(INLINE_TOOL_TIERS),
-  LOAD_TOOLS_NAME,
-]);
-
-// Ordinary camelCase words that appear in the guidance-note prose and are NOT
-// tool names. Keep this list minimal and explicit — anything camelCase in a note
-// that is neither a real tool nor here fails the scan.
-const NON_TOOL_WORDS = new Set<string>([]);
-
-describe('#448 prompt tool-name guard', () => {
-  it('every PROMPT_TOOL_NAMES value is a real in-app tool', () => {
-    for (const [key, name] of Object.entries(PROMPT_TOOL_NAMES)) {
-      expect(typeof name).toBe('string');
-      expect(VALID_TOOL_NAMES.has(name)).toBe(true);
-      // Sanity: the const key and its value are the same token (the const is a
-      // name->name map used purely to route mentions through one guarded place).
-      expect(key).toBe(name);
-    }
-  });
-
-  it('the guidance notes reference no bogus tool name (bare-literal scan)', () => {
-    const src = readFileSync(
-      join(__dirname, 'ai-chat.prompt.ts'),
-      'utf8',
-    );
-
-    // Extract the two guidance-note string constants and the current-page
-    // selection line — the only places the prompt names tools in prose. Each is
-    // a `const NAME =` ... `;` block; we scan their raw text for camelCase
-    // tokens. (Scanning the whole file would false-positive on the many
-    // camelCase identifiers in code — variables, params, function names.)
-    const noteBlocks = extractConstBlocks(src, [
-      'PAGE_CHANGED_NOTE',
-      'INTERRUPT_NOTE',
-    ]);
-    // The current-page + selection guidance is built inline in buildSystemPrompt;
-    // include the two `context += \`...\`` template lines that mention tools.
-    const contextLines = src
-      .split('\n')
-      .filter((l) => l.includes('context +=') && l.includes('getCurrentPage'))
-      .join('\n');
-
-    // Neutralize string-literal escape sequences (\n, \t, ...) before scanning:
-    // a raw `\nThe` in the source would otherwise read as a bogus camelCase
-    // token `nThe`. Replace any backslash-escape with a space.
-    const scanText = (noteBlocks + '\n' + contextLines).replace(/\\./g, ' ');
-    expect(scanText.length).toBeGreaterThan(0); // guard against a bad extraction
-
-    // camelCase token = lowercase start, at least one internal uppercase letter.
-    const tokens = new Set(scanText.match(/\b[a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*\b/g) ?? []);
-    const offenders = [...tokens].filter(
-      (t) => !VALID_TOOL_NAMES.has(t) && !NON_TOOL_WORDS.has(t),
-    );
-    expect(offenders).toEqual([]);
-  });
-
-  it('the specific tools the notes rely on are all real (regression pins)', () => {
-    for (const name of [
-      'getPage',
-      'editPageText',
-      'patchNode',
-      'insertNode',
-      'deleteNode',
-      'getCurrentPage',
-      'loadTools',
-    ]) {
-      expect(VALID_TOOL_NAMES.has(name)).toBe(true);
-    }
-  });
-});
-
-/**
- * Extract the raw text of one or more top-level `const NAME = ... ;` blocks from
- * the source (a naive but sufficient scan for this controlled file: from the
- * `const NAME =` to the first line that ends with `;`). Returns the blocks
- * concatenated.
- */
-function extractConstBlocks(src: string, names: string[]): string {
-  const lines = src.split('\n');
-  const out: string[] = [];
-  for (const name of names) {
-    const start = lines.findIndex((l) => l.trimStart().startsWith(`const ${name} =`));
-    if (start < 0) continue;
-    for (let i = start; i < lines.length; i++) {
-      out.push(lines[i]);
-      if (lines[i].trimEnd().endsWith(';')) break;
-    }
-  }
-  return out.join('\n');
-}
@@ -2,30 +2,6 @@ import { Workspace } from '@docmost/db/types/entity.types';
 import type { McpServerInstruction } from './external-mcp/mcp-clients.service';
 import type { ToolCatalogEntry } from './tools/tool-tiers';

-/**
- * The in-app tool names this prompt refers to BY NAME in its guidance notes
- * (issue #448). Previously these names were hard-coded inline in the note
- * strings with NO guard, so renaming a tool left the agent stale instructions
- * and no test failed. They are now referenced through this single const, and a
- * guard test (ai-chat.prompt.tool-names.spec.ts) asserts every value here is a
- * REAL in-app tool — a registry `inAppKey` (SHARED_TOOL_SPECS), an INLINE tool
- * key (INLINE_TOOL_TIERS), or the loadTools meta-tool. Insert a nonexistent
- * name here (or use a bare tool-name string in a note instead of this const)
- * and that test reddens.
- *
- * `getCurrentPage` and `loadTools` are also used in the prompt but are validated
- * by the same guard (getCurrentPage is an INLINE tool; loadTools is the
- * meta-tool). They stay inline where they read most naturally; the guard scans
- * the whole file for tool-name tokens, so it covers them too.
- */
-export const PROMPT_TOOL_NAMES = {
-  getPage: 'getPage',
-  editPageText: 'editPageText',
-  patchNode: 'patchNode',
-  insertNode: 'insertNode',
-  deleteNode: 'deleteNode',
-} as const;
-
 /**
 * Default agent persona used when the admin has not configured a custom system
 * prompt (`settings.ai.provider.systemPrompt`).
@@ -115,15 +91,15 @@ const PAGE_CHANGED_NOTE =
  'NOTE: The user edited the open page AFTER your last response in this ' +
  'conversation, so any copy of that page you produced or remember from earlier ' +
  'is now STALE and must not be reused. Before you edit the page, you MUST first ' +
-  `re-read its current content with the ${PROMPT_TOOL_NAMES.getPage} tool and base your work on that ` +
+  're-read its current content with the getPage tool and base your work on that ' +
  'live version — never on your earlier copy or on the transcript. The unified ' +
  'diff below shows exactly what the user changed since you last spoke (lines ' +
  'starting with "-" were removed, "+" were added) and is the source of truth. ' +
  'Preserve every one of the user\'s edits: make the smallest change that ' +
-  `satisfies the request using the targeted edit tools (${PROMPT_TOOL_NAMES.editPageText}, ${PROMPT_TOOL_NAMES.patchNode}, ` +
-  `${PROMPT_TOOL_NAMES.insertNode}, ${PROMPT_TOOL_NAMES.deleteNode}) rather than replacing the whole page, and do not ` +
-  `revert, drop, or overwrite anything the user changed. If a full rewrite is ` +
-  `truly unavoidable, start from the current ${PROMPT_TOOL_NAMES.getPage} content and carry over all ` +
+  'satisfies the request using the targeted edit tools (editPageText, patchNode, ' +
+  'insertNode, deleteNode) rather than replacing the whole page, and do not ' +
+  'revert, drop, or overwrite anything the user changed. If a full rewrite is ' +
+  'truly unavoidable, start from the current getPage content and carry over all ' +
  'of the user\'s edits.';

 /**
@@ -1,17 +1,6 @@
 import { AiChatToolsService } from './ai-chat-tools.service';
 import * as loader from './docmost-client.loader';
 import type { DocmostClientLike } from './docmost-client.loader';
-
-// Test-double type for the loopback client. `DocmostClientLike` is now DERIVED
-// from the real `DocmostClient` (issue #446), so its method RETURN types are the
-// concrete client shapes. These stubs deliberately return minimal recording
-// shapes (e.g. `{ ok: true }`), which no longer satisfy those concrete returns —
-// so the doubles are typed with the same method NAMES but loose async returns.
-// Each is still cast to `DocmostClientLike` at the (return-erased) mock site, so
-// the positional-call type-safety on the PRODUCTION client is unaffected.
-type FakeDocmostClient = Partial<
-  Record<keyof DocmostClientLike, (...args: any[]) => Promise<any>>
->;
 // The real zod-agnostic shared tool-spec registry. It has no runtime deps, so
 // importing the TS source directly keeps these mocks honest: the service builds
 // the shared tools from exactly the specs the package ships, not a hand-stub.
@@ -42,7 +31,7 @@ describe('AiChatToolsService deletePage guardrail (H4)', () => {

  // Minimal fake DocmostClient: only the write methods the tools touch need to
  // exist; deletePage records its args. No network, no ESM import.
-  const fakeClient: FakeDocmostClient = {
+  const fakeClient: Partial<DocmostClientLike> = {
    deletePage: (...args: unknown[]) => {
      deletePageCalls.push(args);
      return Promise.resolve({ success: true });
@@ -171,7 +160,7 @@ describe('AiChatToolsService deletePage guardrail (H4)', () => {
 describe('AiChatToolsService expanded toolset guardrails', () => {
  // No client method is invoked here — every assertion is on tool presence /
  // input schema — so an empty fake client is sufficient.
-  const fakeClient: FakeDocmostClient = {};
+  const fakeClient: Partial<DocmostClientLike> = {};

  const tokenServiceStub = {
    generateAccessToken: jest.fn().mockResolvedValue('access-token'),
@@ -276,7 +265,7 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
  const insertNodeCalls: unknown[][] = [];
  const updatePageJsonCalls: unknown[][] = [];

-  const fakeClient: FakeDocmostClient = {
+  const fakeClient: Partial<DocmostClientLike> = {
    patchNode: (...args: unknown[]) => {
      patchNodeCalls.push(args);
      return Promise.resolve({ ok: true });
@@ -450,7 +439,7 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
 * getOutline) are exercised here end-to-end through forUser().
 */
 describe('AiChatToolsService model-friendly input validation (#190)', () => {
-  const fakeClient: FakeDocmostClient = {};
+  const fakeClient: Partial<DocmostClientLike> = {};
  const tokenServiceStub = {
    generateAccessToken: jest.fn().mockResolvedValue('access-token'),
    generateCollabToken: jest.fn().mockResolvedValue('collab-token'),
@@ -568,7 +557,7 @@ describe('AiChatToolsService #294 changed execute wirings', () => {
    tableDeleteRow: [],
    tableUpdateCell: [],
  };
-  const fakeClient: FakeDocmostClient = {
+  const fakeClient: Partial<DocmostClientLike> = {
    movePage: (...args: unknown[]) => {
      calls.movePage.push(args);
      return Promise.resolve({ success: true });
@@ -677,7 +666,7 @@ describe('AiChatToolsService #410 footnote + image tools', () => {
    insertImage: [],
    replaceImage: [],
  };
-  const fakeClient: FakeDocmostClient = {
+  const fakeClient: Partial<DocmostClientLike> = {
    insertFootnote: (...args: unknown[]) => {
      calls.insertFootnote.push(args);
      return Promise.resolve({ success: true, footnoteId: 'fn1', reused: false });
@@ -26,100 +26,6 @@ import {
  type ToolCatalogEntry,
 } from './tool-tiers';

-/**
- * Compile-time contract (issue #446): the in-app tool `execute` closures below
- * call the loopback `DocmostClient` POSITIONALLY (e.g.
- * `client.drawioGet(pageId, node, format ?? 'xml')`). Those closures receive an
- * AI-SDK-erased (`any`) input, so a positional call inside them is NOT checked
- * against the real signature — a parameter reorder/type-change in
- * `packages/mcp/src/client.ts` would otherwise reach production as a runtime
- * "wrong argument" tool failure with zero compile signal (the restored #294
- * debt). This never-called function reproduces every positional call with
- * correctly-typed placeholder arguments against the DERIVED `DocmostClientLike`
- * (a `Pick` of the real `DocmostClient`), so any such reorder/rename becomes a
- * SERVER COMPILE ERROR here. It emits nothing (types only) and is never invoked;
- * keep each call in lockstep with the matching `execute` body below.
- */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function __assertClientCallContract(client: DocmostClientLike): void {
-  // Placeholders standing in for the AI-SDK-erased execute inputs. Their types
-  // are deliberately concrete so the positional calls are checked end-to-end.
-  const s = '' as string;
-  const n = 0 as number;
-  const node: unknown = null;
-  const edits: Array<{ find: string; replace: string; replaceAll?: boolean }> =
-    [];
-  const cells: string[] = [];
-  const align = undefined as 'left' | 'center' | 'right' | undefined;
-
-  // --- read ---
-  void client.search(s, undefined, n);
-  void client.getPage(s);
-  void client.getPageRaw(s);
-  void client.getWorkspace();
-  void client.getSpaces();
-  void client.listPages(s, n, true);
-  void client.listSidebarPages(s, s);
-  void client.getOutline(s);
-  void client.getPageJson(s);
-  void client.getNode(s, s);
-  void client.searchInPage(s, s, {
-    regex: true,
-    caseSensitive: true,
-    limit: n,
-  });
-  void client.getTable(s, s);
-  void client.listComments(s, true);
-  void client.getComment(s);
-  void client.checkNewComments(s, s, s);
-  void client.listShares();
-  void client.listPageHistory(s, s);
-  void client.getPageHistory(s);
-  void client.diffPageVersions(s, s, s);
-  void client.exportPageMarkdown(s);
-  // --- write (page) ---
-  void client.createPage(s, s, s, s);
-  void client.updatePage(s, s, s);
-  void client.renamePage(s, s);
-  void client.movePage(s, s, s);
-  void client.deletePage(s);
-  void client.editPageText(s, edits);
-  void client.patchNode(s, s, node);
-  void client.insertNode(s, node, {
-    position: 'append',
-    anchorNodeId: s,
-    anchorText: s,
-  });
-  void client.deleteNode(s, s);
-  void client.updatePageJson(s, node, s);
-  void client.tableInsertRow(s, s, cells, n);
-  void client.tableDeleteRow(s, s, n);
-  void client.tableUpdateCell(s, s, n, n, s);
-  void client.copyPageContent(s, s);
-  void client.importPageMarkdown(s, s);
-  void client.sharePage(s, true);
-  void client.unsharePage(s);
-  void client.restorePageVersion(s);
-  void client.transformPage(s, s, { dryRun: true });
-  void client.stashPage(s);
-  // --- write (image / footnote), in-app since #410 ---
-  void client.insertFootnote(s, s, s);
-  void client.insertImage(s, s, {
-    align,
-    alt: s,
-    replaceText: s,
-    afterText: s,
-  });
-  void client.replaceImage(s, s, s, { align, alt: s });
-  // --- draw.io diagrams (#423) ---
-  void client.drawioGet(s, s, 'xml');
-  void client.drawioCreate(s, { position: 'append', anchorNodeId: s }, s, s);
-  void client.drawioUpdate(s, s, s, s);
-  // --- write (comment) ---
-  void client.createComment(s, s, 'inline', s, s, s);
-  void client.resolveComment(s, true);
-}
-
 /**
 * Per-user, per-request adapter that exposes Docmost READ operations to the
 * agent as AI SDK tools (STAGE A = read only).
@@ -292,17 +198,6 @@ export class AiChatToolsService {
        execute,
      });

-    // The in-app toolset. It starts with the tools kept INLINE here for a
-    // documented per-layer reason: an intentional behaviour/schema divergence from
-    // the standalone MCP surface (searchPages' hybrid RRF, updatePageContent's
-    // Markdown write, transformPage's guardrailed shorter schema), a
-    // snake_case/camelCase naming clash the shared registry forbids (getTable vs
-    // the MCP `table_get`), per-request state the registry loop cannot provide
-    // (getCurrentPage reads the resolved openedPage; searchPages closes over the
-    // per-request user/embedding deps), or a tool with no MCP twin
-    // (listSidebarPages/getComment/getPageHistory). Every SHARED tool is then added
-    // by the registry loop below (see it), so there is exactly one arg-mapping per
-    // shared tool and it can never drift from the MCP host again (#445).
    const tools: Record<string, Tool> = {
      // INTENTIONAL per-transport divergence (not in the shared registry): this
      // in-app search runs a semantic + keyword hybrid (RRF) with in-process
@@ -437,8 +332,44 @@ 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 : '',
+        };
+      }),
+
      // --- 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(title, content, spaceId, parentPageId?) ->
+          // { data: filterPage(page, markdown), success }.
+          const result = await client.createPage(
+            title,
+            content ?? '',
+            spaceId,
+            parentPageId,
+          );
+          const data = (result?.data ?? {}) as {
+            id?: string;
+            slugId?: string;
+            title?: string;
+          };
+          return { id: data.id ?? data.slugId, title: data.title ?? title };
+        },
+      ),
+
      updatePageContent: tool({
        description:
          "Replace a page's body with new Markdown content (and optionally its " +
@@ -461,6 +392,121 @@ export class AiChatToolsService {
        },
      }),

+      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
+      renamePage: sharedTool(
+        sharedToolSpecs.renamePage,
+        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 ({
+          pageId,
+          content,
+          selection,
+          parentCommentId,
+          suggestedText,
+        }) => {
+          // createComment(pageId, content, type, selection?, parentCommentId?,
+          // suggestedText?). Top-level comments are inline and must carry a
+          // selection to anchor on; replies inherit the parent's anchor (no
+          // selection). Throwing here surfaces a tool error to the model (Vercel
+          // `ai` SDK) so the agent retries with a better selection — do not
+          // catch/suppress it.
+          if (!parentCommentId && (!selection || !selection.trim())) {
+            throw new Error(
+              "createComment requires a 'selection' (exact text to anchor on) for a new top-level comment.",
+            );
+          }
+          if (suggestedText !== undefined) {
+            if (parentCommentId) {
+              throw new Error(
+                "createComment: 'suggestedText' cannot be attached to a reply; it applies only to a top-level inline comment.",
+              );
+            }
+            if (!selection || !selection.trim()) {
+              throw new Error(
+                "createComment: 'suggestedText' requires a 'selection' to anchor and rewrite.",
+              );
+            }
+          }
+          const result = await client.createComment(
+            pageId,
+            content,
+            'inline',
+            selection,
+            parentCommentId,
+            suggestedText,
+          );
+          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(commentId, resolved) -> { success, commentId, resolved }.
+          await client.resolveComment(commentId, resolved);
+          return { commentId, resolved };
+        },
+      ),
+
+      // --- READ tools (added) ---
+
+      getWorkspace: sharedTool(
+        sharedToolSpecs.getWorkspace,
+        async () => await client.getWorkspace(),
+      ),
+
+      listSpaces: sharedTool(
+        sharedToolSpecs.listSpaces,
+        async () => await client.getSpaces(),
+      ),
+
+      // INTENTIONAL per-transport divergence (not shared): keeps the `tree:true`
+      // 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 }) =>
+          await client.listPages(spaceId, limit, tree),
+      ),
+
      listSidebarPages: tool({
        description:
          'List sidebar pages for a space. With no pageId, returns the ' +
@@ -479,6 +525,31 @@ export class AiChatToolsService {
          await client.listSidebarPages(spaceId, pageId),
      }),

+      getOutline: sharedTool(
+        sharedToolSpecs.getOutline,
+        async ({ pageId }) => await client.getOutline(pageId),
+      ),
+
+      getPageJson: sharedTool(
+        sharedToolSpecs.getPageJson,
+        async ({ pageId }) => await client.getPageJson(pageId),
+      ),
+
+      getNode: sharedTool(
+        sharedToolSpecs.getNode,
+        async ({ pageId, nodeId }) => await client.getNode(pageId, nodeId),
+      ),
+
+      searchInPage: sharedTool(
+        sharedToolSpecs.searchInPage,
+        async ({ pageId, query, regex, caseSensitive, limit }) =>
+          await client.searchInPage(pageId, query, {
+            regex,
+            caseSensitive,
+            limit,
+          }),
+      ),
+
      // 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
@@ -501,6 +572,13 @@ export class AiChatToolsService {
          await client.getTable(pageId, table),
      }),

+      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
+      listComments: sharedTool(
+        sharedToolSpecs.listComments,
+        async ({ pageId, includeResolved }) =>
+          await client.listComments(pageId, includeResolved),
+      ),
+
      getComment: tool({
        description: 'Fetch a single comment by id (content as Markdown).',
        inputSchema: modelFriendlyInput({
@@ -509,6 +587,24 @@ 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 }) =>
+          await client.checkNewComments(spaceId, since, parentPageId),
+      ),
+
+      listShares: sharedTool(
+        sharedToolSpecs.listShares,
+        async () => await client.listShares(),
+      ),
+
+      listPageHistory: sharedTool(
+        sharedToolSpecs.listPageHistory,
+        async ({ pageId, cursor }) =>
+          await client.listPageHistory(pageId, cursor),
+      ),
+
      getPageHistory: tool({
        description:
          'Fetch a single page-history version including its lossless ' +
@@ -520,8 +616,203 @@ export class AiChatToolsService {
          await client.getPageHistory(historyId),
      }),

+      diffPageVersions: sharedTool(
+        sharedToolSpecs.diffPageVersions,
+        async ({ pageId, from, to }) =>
+          await client.diffPageVersions(pageId, from, to),
+      ),
+
+      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
+      exportPageMarkdown: sharedTool(
+        sharedToolSpecs.exportPageMarkdown,
+        async ({ pageId }) => {
+          const markdown = await client.exportPageMarkdown(pageId);
+          return { markdown };
+        },
+      ),
+
      // --- WRITE tools (added; reversible via page history/trash) ---

+      editPageText: sharedTool(
+        sharedToolSpecs.editPageText,
+        async ({ pageId, edits }) => await client.editPageText(pageId, edits),
+      ),
+
+      // Returns ONLY the short link object — never the document body — so a
+      // large page can be handed to an external consumer without bloating
+      // context.
+      stashPage: sharedTool(
+        sharedToolSpecs.stashPage,
+        async ({ pageId }) => await client.stashPage(pageId),
+      ),
+
+      // Schema + description from the shared registry (identical across both
+      // transports). The execute body keeps its OWN parseNodeArg normalization:
+      // the model sometimes serializes the node as a JSON string, and we parse it
+      // before the client's typeof-object guard rejects it (parity with the
+      // standalone MCP server, index.ts patch_node).
+      patchNode: sharedTool(
+        sharedToolSpecs.patchNode,
+        async ({ pageId, nodeId, node }) => {
+          const parsedNode = parseNodeArg(node);
+          return await client.patchNode(pageId, nodeId, parsedNode);
+        },
+      ),
+
+      // Shared registry schema + description; execute retains parseNodeArg on the
+      // incoming node (parity with the standalone MCP server, index.ts
+      // insert_node).
+      insertNode: sharedTool(
+        sharedToolSpecs.insertNode,
+        async ({ pageId, node, position, anchorNodeId, anchorText }) => {
+          const parsedNode = parseNodeArg(node);
+          return await client.insertNode(pageId, parsedNode, {
+            position,
+            anchorNodeId,
+            anchorText,
+          });
+        },
+      ),
+
+      deleteNode: sharedTool(
+        sharedToolSpecs.deleteNode,
+        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 }) => {
+          // 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.
+          let doc;
+          if (content === undefined || content === null) {
+            doc = undefined;
+          } else {
+            // String -> JSON.parse (throwing on invalid); object passes through.
+            doc = parseNodeArg(content, 'content was a string but not valid JSON');
+          }
+          return await client.updatePageJson(pageId, doc, title);
+        },
+      ),
+
+      // Schema + description live in @docmost/mcp's SHARED_TOOL_SPECS (#410).
+      // Promoted from MCP-only so the in-app agent can attach a REAL footnote to
+      // already-written text instead of leaving a literal `^[...]` string.
+      insertFootnote: sharedTool(
+        sharedToolSpecs.insertFootnote,
+        async ({ pageId, anchorText, text }) =>
+          await client.insertFootnote(pageId, anchorText, text),
+      ),
+
+      // Schema + description live in @docmost/mcp's SHARED_TOOL_SPECS (#410).
+      // The schema field is `imageUrl`; the client method takes it positionally.
+      insertImage: sharedTool(
+        sharedToolSpecs.insertImage,
+        async ({ pageId, imageUrl, align, alt, replaceText, afterText }) =>
+          await client.insertImage(pageId, imageUrl, {
+            align,
+            alt,
+            replaceText,
+            afterText,
+          }),
+      ),
+
+      // Schema + description live in @docmost/mcp's SHARED_TOOL_SPECS (#410).
+      replaceImage: sharedTool(
+        sharedToolSpecs.replaceImage,
+        async ({ pageId, attachmentId, imageUrl, align, alt }) =>
+          await client.replaceImage(pageId, attachmentId, imageUrl, {
+            align,
+            alt,
+          }),
+      ),
+
+      // Schema + description live in @docmost/mcp's SHARED_TOOL_SPECS (#423).
+      // meta.hash in the result is the baseHash drawioUpdate requires.
+      drawioGet: sharedTool(
+        sharedToolSpecs.drawioGet,
+        async ({ pageId, node, format }) =>
+          await client.drawioGet(pageId, node, format ?? 'xml'),
+      ),
+
+      // Schema + description live in @docmost/mcp's SHARED_TOOL_SPECS (#423).
+      // The flat schema fields are regrouped into the client's `where` object.
+      drawioCreate: sharedTool(
+        sharedToolSpecs.drawioCreate,
+        async ({ pageId, xml, position, anchorNodeId, anchorText, title }) =>
+          await client.drawioCreate(
+            pageId,
+            { position, anchorNodeId, anchorText },
+            xml,
+            title,
+          ),
+      ),
+
+      // Schema + description live in @docmost/mcp's SHARED_TOOL_SPECS (#423).
+      // baseHash is the optimistic lock: mismatch => structured conflict error.
+      drawioUpdate: sharedTool(
+        sharedToolSpecs.drawioUpdate,
+        async ({ pageId, node, xml, baseHash }) =>
+          await client.drawioUpdate(pageId, node, xml, baseHash),
+      ),
+
+      // 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),
+      ),
+
+      // 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),
+      ),
+
+      // 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),
+      ),
+
+      copyPageContent: sharedTool(
+        sharedToolSpecs.copyPageContent,
+        async ({ sourcePageId, targetPageId }) =>
+          await client.copyPageContent(sourcePageId, targetPageId),
+      ),
+
+      importPageMarkdown: sharedTool(
+        sharedToolSpecs.importPageMarkdown,
+        async ({ pageId, markdown }) =>
+          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 }) =>
+          await client.sharePage(pageId, searchIndexing),
+      ),
+
+      unsharePage: sharedTool(
+        sharedToolSpecs.unsharePage,
+        async ({ pageId }) => await client.unsharePage(pageId),
+      ),
+
+      restorePageVersion: sharedTool(
+        sharedToolSpecs.restorePageVersion,
+        async ({ historyId }) => await client.restorePageVersion(historyId),
+      ),
+
      // INTENTIONAL per-transport divergence (not shared): deliberately omits the
      // `deleteComments` schema field (comment-deletion guardrail) and carries a
      // much shorter description; the standalone MCP `docmost_transform` exposes
@@ -550,29 +841,6 @@ export class AiChatToolsService {
      }),
    };

-    // Add EVERY shared tool from the zod-agnostic registry in one loop (#445).
-    // The spec owns the canonical arg->client mapping; this host only decides
-    // WHICH mapping to run and returns its value directly (no envelope). For each
-    // spec:
-    //   - skip `mcpOnly` specs (they belong to the standalone MCP host only);
-    //   - use `inAppExecute` when the spec declares a DELIBERATE per-layer
-    //     difference (a projected result shape, a different guardrail message);
-    //   - otherwise use the canonical `execute` (raw client result, identical to
-    //     the MCP host's before it wraps it as JSON).
-    // The execute receives the AI-SDK-validated, type-erased input; the spec reads
-    // the same fields its buildShape declares. This is the SINGLE place the in-app
-    // arg mapping lives — it can no longer silently drift from the MCP host.
-    for (const spec of Object.values(sharedToolSpecs)) {
-      if (spec.mcpOnly) continue;
-      const run = spec.inAppExecute ?? spec.execute;
-      if (!run) continue; // defensive: a shared spec always carries one of them.
-      tools[spec.inAppKey] = sharedTool(
-        spec,
-        (async (args) =>
-          run(client, args as Record<string, unknown>)) as Tool['execute'],
-      );
-    }
-
    // Passive "new comments: N" signal (#417). PER-TURN state (forUser runs once
    // per turn), so the watermark starts now and only comments a human leaves
    // WHILE this turn runs are signalled — exactly the mid-turn loop; between-turn
@@ -7,16 +7,6 @@ import type {
  DocmostClientLike,
  CommentSignalTrackerLike,
 } from './docmost-client.loader';
-
-// Test-double type for the loopback client. `DocmostClientLike` is now DERIVED
-// from the real `DocmostClient` (issue #446), so its method RETURN types are the
-// concrete client shapes. These probe stubs deliberately return minimal shapes
-// (e.g. `getPageRaw` yielding only `{ title }`), so the doubles use the same
-// method NAMES but loose async returns; each is cast to `DocmostClientLike` at
-// the (return-erased) mock site, leaving production positional-call safety intact.
-type FakeDocmostClient = Partial<
-  Record<keyof DocmostClientLike, (...args: any[]) => Promise<any>>
->;
 import { SHARED_TOOL_SPECS } from '../../../../../../packages/mcp/src/tool-specs';
 // The REAL shared tracker factory, imported from source (same cross-boundary
 // approach the tool-specs spec uses) so the in-app wiring is exercised against
@@ -278,7 +268,7 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
  // seeded at forUser time).
  const future = new Date(Date.now() + 3_600_000).toISOString();

-  function buildService(fakeClient: FakeDocmostClient) {
+  function buildService(fakeClient: Partial<DocmostClientLike>) {
    jest.spyOn(loader, 'loadDocmostMcp').mockResolvedValue({
      DocmostClient: function () {
        return fakeClient as DocmostClientLike;
@@ -327,7 +317,7 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
  afterEach(() => jest.restoreAllMocks());

  it('emits the signal (model-only) on a non-comment tool when a new comment exists', async () => {
-    const fakeClient: FakeDocmostClient = {
+    const fakeClient: Partial<DocmostClientLike> = {
      getPage: async () => ({
        data: { title: 'Иранские языки', content: 'body' },
        success: true,
@@ -352,7 +342,7 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
  });

  it('does NOT add the signal to the listComments tool itself (tautological)', async () => {
-    const fakeClient: FakeDocmostClient = {
+    const fakeClient: Partial<DocmostClientLike> = {
      listComments: async () => ({
        items: [{ createdAt: future }],
        resolvedThreadsHidden: 0,
@@ -366,7 +356,7 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
  });

  it('no new comments => tool output is byte-identical AND the model sees no signal', async () => {
-    const fakeClient: FakeDocmostClient = {
+    const fakeClient: Partial<DocmostClientLike> = {
      getPage: async () => ({
        data: { title: 'T', content: 'body' },
        success: true,
@@ -382,7 +372,7 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
  });

  it('injection-safety: a malicious page title cannot forge a second signal', async () => {
-    const fakeClient: FakeDocmostClient = {
+    const fakeClient: Partial<DocmostClientLike> = {
      getPage: async () => ({
        data: { title: 'body-title', content: 'body' },
        success: true,
@@ -1,173 +0,0 @@
-import { createHash } from 'node:crypto';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { computeSrcRegistryStamp } from './docmost-client.loader';
-
-// The exact message the loader throws on a build/src skew (issue #447). Kept as a
-// literal here so a reworded prod message reddens this test (the message is a
-// developer-facing contract: it tells them how to fix it).
-const STALE_BUILD_MESSAGE =
-  '@docmost/mcp build is stale (tool-specs changed since last build) — run: pnpm --filter @docmost/mcp build';
-
-// Replica of the loader's inline stale-check predicate + throw from
-// `loadDocmostMcp`. That guard is not independently exported (it lives inside the
-// dynamic-import IIFE, wired to a fixed `require.resolve('@docmost/mcp')`), so we
-// exercise the exact same three-condition logic against a stamp produced by the
-// REAL `computeSrcRegistryStamp`. This documents and locks the throw/no-throw
-// behaviour; if the prod predicate changes, this replica must change with it.
-function assertStaleGuard(
-  srcStamp: string | null,
-  registryStamp: string | undefined,
-): void {
-  if (
-    srcStamp !== null &&
-    typeof registryStamp === 'string' &&
-    srcStamp !== registryStamp
-  ) {
-    throw new Error(STALE_BUILD_MESSAGE);
-  }
-}
-
-// Build a throwaway `<pkg>/build/index.js` + optional `<pkg>/src/tool-specs.ts`
-// layout so `computeSrcRegistryStamp(<pkg>/build/index.js)` resolves src the same
-// way the loader does (dirname(dirname(entry))/src/tool-specs.ts).
-function makeFakePackage(toolSpecsSource: string | null): {
-  entry: string;
-  cleanup: () => void;
-} {
-  const root = mkdtempSync(join(tmpdir(), 'mcp-stamp-'));
-  const buildDir = join(root, 'build');
-  mkdirSync(buildDir, { recursive: true });
-  const entry = join(buildDir, 'index.js');
-  writeFileSync(entry, '// fake @docmost/mcp build entry\n', 'utf8');
-  if (toolSpecsSource !== null) {
-    const srcDir = join(root, 'src');
-    mkdirSync(srcDir, { recursive: true });
-    writeFileSync(join(srcDir, 'tool-specs.ts'), toolSpecsSource, 'utf8');
-  }
-  return { entry, cleanup: () => rmSync(root, { recursive: true, force: true }) };
-}
-
-describe('computeSrcRegistryStamp (#447 stale-build guard)', () => {
-  it('returns null when src/tool-specs.ts is absent (prod no-op path)', () => {
-    // A prod image ships only build/, no src/ — the guard must be a silent no-op.
-    const { entry, cleanup } = makeFakePackage(null);
-    try {
-      expect(computeSrcRegistryStamp(entry)).toBeNull();
-    } finally {
-      cleanup();
-    }
-  });
-
-  it('returns null for a bogus package entry (swallowed error path)', () => {
-    // A resolution/read hiccup must NEVER break startup — it resolves to null.
-    expect(
-      computeSrcRegistryStamp('/no/such/pkg/build/index.js'),
-    ).toBeNull();
-  });
-
-  it('computes a 64-char sha256 hex when src/tool-specs.ts exists', () => {
-    const { entry, cleanup } = makeFakePackage('export const specs = 1;\n');
-    try {
-      const stamp = computeSrcRegistryStamp(entry);
-      expect(stamp).toMatch(/^[0-9a-f]{64}$/);
-    } finally {
-      cleanup();
-    }
-  });
-
-  it('normalizes CRLF->LF and strips a single trailing newline', () => {
-    // A CRLF+trailing-newline variant of the same content hashes identically to
-    // the bare-LF form — the guard must not fire on a checkout-style difference.
-    const bare = makeFakePackage('alpha\nbeta');
-    const crlfTrailing = makeFakePackage('alpha\r\nbeta\r\n');
-    try {
-      expect(computeSrcRegistryStamp(crlfTrailing.entry)).toBe(
-        computeSrcRegistryStamp(bare.entry),
-      );
-    } finally {
-      bare.cleanup();
-      crlfTrailing.cleanup();
-    }
-  });
-
-  // CROSS-IMPL EQUALITY (covers reviewer suggestion 2). The SAME fixed input and
-  // EXPECTED hash are asserted in the mcp-side node test
-  // (packages/mcp/test/unit/registry-stamp.test.mjs) against the codegen's
-  // `computeRegistryStamp`. Asserting the SAME pair here against the loader's
-  // `computeSrcRegistryStamp` proves both implementations normalize+hash
-  // identically; a divergence in EITHER side reddens one of the two tests.
-  it('matches the documented cross-impl hash for a fixed input', () => {
-    const FIXED_INPUT = 'line1\r\nline2\n';
-    const EXPECTED =
-      '683376e290829b482c2655745caffa7a1dccfa10afaa62dac2b42dd6c68d0f83';
-    const { entry, cleanup } = makeFakePackage(FIXED_INPUT);
-    try {
-      expect(computeSrcRegistryStamp(entry)).toBe(EXPECTED);
-    } finally {
-      cleanup();
-    }
-  });
-
-  it('the documented EXPECTED is the normalize+sha256 of the fixed input', () => {
-    // Proves EXPECTED is not a magic constant but the documented computation.
-    const FIXED_INPUT = 'line1\r\nline2\n';
-    const normalized = FIXED_INPUT.replace(/\r\n/g, '\n').replace(/\n$/, '');
-    const expected = createHash('sha256')
-      .update(normalized, 'utf8')
-      .digest('hex');
-    const { entry, cleanup } = makeFakePackage(FIXED_INPUT);
-    try {
-      expect(computeSrcRegistryStamp(entry)).toBe(expected);
-    } finally {
-      cleanup();
-    }
-  });
-});
-
-describe('loadDocmostMcp stale-check predicate (#447)', () => {
-  it('THROWS the exact stale message when src stamp != built REGISTRY_STAMP', () => {
-    const { entry, cleanup } = makeFakePackage('export const specs = 1;\n');
-    try {
-      const srcStamp = computeSrcRegistryStamp(entry);
-      expect(srcStamp).not.toBeNull();
-      // Simulate a stale build: build/ carries a DIFFERENT stamp than src.
-      expect(() => assertStaleGuard(srcStamp, 'a'.repeat(64))).toThrow(
-        STALE_BUILD_MESSAGE,
-      );
-    } finally {
-      cleanup();
-    }
-  });
-
-  it('does NOT throw when src stamp equals the built REGISTRY_STAMP', () => {
-    const { entry, cleanup } = makeFakePackage('export const specs = 1;\n');
-    try {
-      const srcStamp = computeSrcRegistryStamp(entry);
-      // Fresh build: build/ stamp == src stamp -> guard is a no-op.
-      expect(() => assertStaleGuard(srcStamp, srcStamp as string)).not.toThrow();
-    } finally {
-      cleanup();
-    }
-  });
-
-  it('does NOT throw when src is absent (prod: srcStamp === null)', () => {
-    // Even against a present-but-mismatched REGISTRY_STAMP, a null src stamp
-    // (prod image with build/ only) must skip the check entirely.
-    expect(() => assertStaleGuard(null, 'a'.repeat(64))).not.toThrow();
-  });
-
-  it('does NOT throw when REGISTRY_STAMP is absent (pre-#447 build)', () => {
-    // An older @docmost/mcp build has no REGISTRY_STAMP export; the guard must be
-    // a no-op so an out-of-date build never wrongly blocks startup.
-    const { entry, cleanup } = makeFakePackage('export const specs = 1;\n');
-    try {
-      const srcStamp = computeSrcRegistryStamp(entry);
-      expect(() => assertStaleGuard(srcStamp, undefined)).not.toThrow();
-    } finally {
-      cleanup();
-    }
-  });
-});
@@ -1,93 +1,264 @@
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import type { DocmostClient, SharedToolSpec } from '@docmost/mcp';
-
-// Re-export SharedToolSpec so downstream server modules keep a single import
-// path (they import it from this loader). The shape is DERIVED from the package
-// entry, not re-declared here — see the import above (issue #446).
-export type { SharedToolSpec } from '@docmost/mcp';

 /**
- * The exact set of `DocmostClient` methods the per-user in-app tool adapter
- * consumes. This is the AUTHORITATIVE list of the client surface the server
- * depends on; the adapter calls these methods POSITIONALLY, so this set is what
- * the derived type below type-checks against the real class (issue #446).
+ * Minimal structural type for the `DocmostClient` class we consume from the
+ * ESM-only `@docmost/mcp` package. We only need the constructor + the read/write
+ * methods used by the per-user tool adapter; the full client surface lives in
+ * `packages/mcp/src/client.ts`. Signatures here mirror that file exactly.
+ *
+ * DRIFT GUARD: the method NAMES below are runtime-checked against the real
+ * `DocmostClient` by `packages/mcp/test/unit/client-host-contract.test.mjs`
+ * (which can import the ESM class directly). If you rename/remove a method here
+ * or in client.ts, that test fails — so a stale mirror cannot silently ship a
+ * runtime "x is not a function" into an agent tool call. Keep the two in sync.
+ *
+ * STAGED PLAN — full derivation `DocmostClientLike = <real DocmostClient type>`
+ * (issue #193, layer 3) is intentionally NOT done; it stays a hand-mirror for
+ * now because of two verified blockers across the ESM(mcp)/CJS(server) boundary:
+ *   1. `@docmost/mcp` emits NO declaration files (its tsconfig has no
+ *      `declaration`, package.json has no `types`/types-export) and the server
+ *      tsconfig has no path mapping for it — the server only loads it via the
+ *      runtime `import()` trick below, so there is no type to import today.
+ *   2. The real client methods have inferred, CONCRETE return types; the in-app
+ *      tool adapter reads results through loose `Record<string,unknown>` returns
+ *      + `as` casts (e.g. `(result?.data ?? {}) as { title?: string }`).
+ *      Deriving the exact type would make those casts non-overlapping ("may be a
+ *      mistake") and break the build, and `Partial<DocmostClientLike>` test stubs
+ *      would have to satisfy the full concrete surface.
+ * To do it safely later (incrementally): (a) turn on `declaration: true` in
+ * packages/mcp/tsconfig.json + add a `types` export condition and commit the
+ * emitted `.d.ts`; (b) `import type { DocmostClient } from '@docmost/mcp'` here
+ * and replace this interface with a `Pick<DocmostClient, ...>` of the consumed
+ * methods; (c) audit every `as` cast in ai-chat-tools.service.ts against the now
+ * concrete return types (double-cast through `unknown` only where genuinely
+ * needed); (d) keep the runtime guard test as a belt-and-braces check. Until
+ * then the guard test above is the cheap, behaviour-neutral protection.
 */
-type DocmostClientMethod =
+export interface DocmostClientLike {
  // --- read ---
-  | 'search'
-  | 'getPage'
-  | 'getPageRaw'
-  | 'getWorkspace'
-  | 'getSpaces'
-  | 'listPages'
-  | 'listSidebarPages'
-  | 'getOutline'
-  | 'getPageJson'
-  | 'getNode'
-  | 'searchInPage'
-  | 'getTable'
-  | 'listComments'
-  | 'getComment'
-  | 'checkNewComments'
-  | 'listShares'
-  | 'listPageHistory'
-  | 'getPageHistory'
-  | 'diffPageVersions'
-  | 'exportPageMarkdown'
+  search(
+    query: string,
+    spaceId?: string,
+    limit?: number,
+  ): Promise<{ items: unknown[]; success: boolean }>;
+  getPage(
+    pageId: string,
+  ): Promise<{ data: Record<string, unknown>; success: boolean }>;
+  // Light raw page info (`/pages/info`): title + slugId + ProseMirror content,
+  // WITHOUT the Markdown render / subpage expansion getPage does. Used by the
+  // comment-signal probe to read just the page title on a hit.
+  getPageRaw(pageId: string): Promise<Record<string, unknown> | null>;
+  getWorkspace(): Promise<{ data: Record<string, unknown>; success: boolean }>;
+  getSpaces(): Promise<unknown[]>;
+  listPages(
+    spaceId?: string,
+    limit?: number,
+    tree?: boolean,
+  ): Promise<unknown[]>;
+  listSidebarPages(spaceId: string, pageId?: string): Promise<unknown[]>;
+  getOutline(pageId: string): Promise<Record<string, unknown>>;
+  getPageJson(pageId: string): Promise<Record<string, unknown>>;
+  getNode(pageId: string, nodeId: string): Promise<Record<string, unknown>>;
+  searchInPage(
+    pageId: string,
+    query: string,
+    opts?: { regex?: boolean; caseSensitive?: boolean; limit?: number },
+  ): Promise<Record<string, unknown>>;
+  getTable(pageId: string, tableRef: string): Promise<Record<string, unknown>>;
+  // Returns `{ items, resolvedThreadsHidden }`. DEFAULT (includeResolved unset/
+  // false) hides resolved threads wholesale; pass true for the full feed.
+  listComments(
+    pageId: string,
+    includeResolved?: boolean,
+  ): Promise<{ items: unknown[]; resolvedThreadsHidden: number }>;
+  getComment(
+    commentId: string,
+  ): Promise<{ data: Record<string, unknown>; success: boolean }>;
+  checkNewComments(
+    spaceId: string,
+    since: string,
+    parentPageId?: string,
+  ): Promise<unknown>;
+  listShares(): Promise<unknown[]>;
+  listPageHistory(
+    pageId: string,
+    cursor?: string,
+  ): Promise<{ items: unknown[]; nextCursor: string | null }>;
+  getPageHistory(historyId: string): Promise<Record<string, unknown>>;
+  diffPageVersions(
+    pageId: string,
+    from?: string,
+    to?: string,
+  ): Promise<Record<string, unknown>>;
+  exportPageMarkdown(pageId: string): Promise<string>;
  // --- write (page) ---
-  | 'createPage'
-  | 'updatePage'
-  | 'renamePage'
-  | 'movePage'
-  | 'deletePage'
-  | 'editPageText'
-  | 'patchNode'
-  | 'insertNode'
-  | 'deleteNode'
-  | 'updatePageJson'
-  | 'tableInsertRow'
-  | 'tableDeleteRow'
-  | 'tableUpdateCell'
-  | 'copyPageContent'
-  | 'importPageMarkdown'
-  | 'sharePage'
-  | 'unsharePage'
-  | 'restorePageVersion'
-  | 'transformPage'
-  | 'stashPage'
-  // --- write (image / footnote), in-app since #410 ---
-  | 'insertImage'
-  | 'replaceImage'
-  | 'insertFootnote'
+  createPage(
+    title: string,
+    content: string,
+    spaceId: string,
+    parentPageId?: string,
+  ): Promise<{ data: Record<string, unknown>; success: boolean }>;
+  // Markdown content update via the collab path (carries provenance via the
+  // collab-token provider). Optionally also updates the title.
+  updatePage(
+    pageId: string,
+    content: string,
+    title?: string,
+  ): Promise<Record<string, unknown>>;
+  // Title-only rename via REST.
+  renamePage(
+    pageId: string,
+    title: string,
+  ): Promise<Record<string, unknown>>;
+  // Move via REST. parentPageId null => move to space root.
+  movePage(
+    pageId: string,
+    parentPageId: string | null,
+    position?: string,
+  ): Promise<unknown>;
+  // SOFT delete only (POST /pages/delete with { pageId }). NEVER permanent.
+  deletePage(pageId: string): Promise<unknown>;
+  editPageText(
+    pageId: string,
+    edits: Array<{ find: string; replace: string; replaceAll?: boolean }>,
+  ): Promise<Record<string, unknown>>;
+  patchNode(
+    pageId: string,
+    nodeId: string,
+    node: unknown,
+  ): Promise<Record<string, unknown>>;
+  insertNode(
+    pageId: string,
+    node: unknown,
+    opts: {
+      position: 'before' | 'after' | 'append';
+      anchorNodeId?: string;
+      anchorText?: string;
+    },
+  ): Promise<Record<string, unknown>>;
+  deleteNode(
+    pageId: string,
+    nodeId: string,
+  ): Promise<Record<string, unknown>>;
+  updatePageJson(
+    pageId: string,
+    doc?: unknown,
+    title?: string,
+  ): Promise<Record<string, unknown>>;
+  // Attach an author-inline footnote after the first occurrence of anchorText;
+  // numbering + the footnotes list are derived server-side.
+  insertFootnote(
+    pageId: string,
+    anchorText: string,
+    text: string,
+  ): Promise<Record<string, unknown>>;
+  // Download a web image and insert it into the page (append, or replace/after a
+  // text anchor). `url` is the image http(s) URL.
+  insertImage(
+    pageId: string,
+    url: string,
+    opts?: {
+      align?: 'left' | 'center' | 'right';
+      alt?: string;
+      replaceText?: string;
+      afterText?: string;
+    },
+  ): Promise<Record<string, unknown>>;
+  // Swap an existing image (by its attachmentId) for a new one fetched from a web
+  // URL, repointing every reference in the live document.
+  replaceImage(
+    pageId: string,
+    oldAttachmentId: string,
+    url: string,
+    opts?: { align?: 'left' | 'center' | 'right'; alt?: string },
+  ): Promise<Record<string, unknown>>;
  // --- draw.io diagrams (#423, stage 1) ---
-  | 'drawioGet'
-  | 'drawioCreate'
-  | 'drawioUpdate'
+  // Read a diagram as decoded mxGraph XML (default) or the raw .drawio.svg.
+  // meta.hash is the optimistic-lock key drawioUpdate expects as baseHash.
+  drawioGet(
+    pageId: string,
+    node: string,
+    format?: 'xml' | 'svg',
+  ): Promise<Record<string, unknown>>;
+  // Lint mxGraph XML, build the .drawio.svg attachment and insert a drawio node.
+  drawioCreate(
+    pageId: string,
+    where: {
+      position: 'before' | 'after' | 'append';
+      anchorNodeId?: string;
+      anchorText?: string;
+    },
+    xml: string,
+    title?: string,
+  ): Promise<Record<string, unknown>>;
+  // Optimistic-locked full replacement of a diagram (baseHash from drawioGet).
+  drawioUpdate(
+    pageId: string,
+    node: string,
+    xml: string,
+    baseHash: string,
+  ): Promise<Record<string, unknown>>;
+  tableInsertRow(
+    pageId: string,
+    tableRef: string,
+    cells: string[],
+    index?: number,
+  ): Promise<Record<string, unknown>>;
+  tableDeleteRow(
+    pageId: string,
+    tableRef: string,
+    index: number,
+  ): Promise<Record<string, unknown>>;
+  tableUpdateCell(
+    pageId: string,
+    tableRef: string,
+    row: number,
+    col: number,
+    text: string,
+  ): Promise<Record<string, unknown>>;
+  copyPageContent(
+    sourcePageId: string,
+    targetPageId: string,
+  ): Promise<Record<string, unknown>>;
+  importPageMarkdown(
+    pageId: string,
+    fullMarkdown: string,
+  ): Promise<Record<string, unknown>>;
+  sharePage(
+    pageId: string,
+    searchIndexing?: boolean,
+  ): Promise<Record<string, unknown>>;
+  unsharePage(pageId: string): Promise<Record<string, unknown>>;
+  restorePageVersion(historyId: string): Promise<Record<string, unknown>>;
+  // The opts type declares deleteComments? to match the real client signature,
+  // but the agent tool NEVER sets it (comment deletion stays unreachable).
+  transformPage(
+    pageId: string,
+    transformJs: string,
+    opts?: { dryRun?: boolean; deleteComments?: boolean },
+  ): Promise<Record<string, unknown>>;
  // --- write (comment) ---
-  | 'createComment'
-  | 'resolveComment';
-
-/**
- * The client surface the per-user tool adapter consumes, DERIVED from the real
- * `DocmostClient` type in `@docmost/mcp` (issue #446, restored #294 debt). This
- * replaces the former hand-mirror of ~45 method signatures.
- *
- * `import type` (above) is fully ERASED at compile time, so nothing is actually
- * imported from the ESM-only package at runtime — the server still loads the
- * class through the dynamic `import()` trick in `loadDocmostMcp` below; this is
- * purely a compile-time type. Deriving via `Pick` means a parameter reorder or a
- * type change to any of these methods in `client.ts` now becomes a SERVER
- * COMPILE ERROR at the positional call sites in ai-chat-tools.service.ts,
- * instead of a silent runtime "wrong argument" failure inside an agent tool.
- *
- * This made the old name-only drift-guard test
- * (packages/mcp/test/unit/client-host-contract.test.mjs) redundant — tsc now
- * enforces both names AND signatures — so that test was removed.
- */
-export type DocmostClientLike = Pick<DocmostClient, DocmostClientMethod>;
+  createComment(
+    pageId: string,
+    content: string,
+    type?: 'page' | 'inline',
+    selection?: string,
+    parentCommentId?: string,
+    suggestedText?: string,
+  ): Promise<{ data: Record<string, unknown>; success: boolean }>;
+  resolveComment(
+    commentId: string,
+    resolved: boolean,
+  ): Promise<Record<string, unknown>>;
+  // Serialize a page + mirror its internal images into the blob sandbox; returns
+  // ONLY a short anonymous URL (the body never enters the model context).
+  stashPage(pageId: string): Promise<{
+    uri: string;
+    sha256: string;
+    size: number;
+    images: { mirrored: number; failed: number };
+  }>;
+}

 export type DocmostClientConfig = {
  apiUrl: string;
@@ -109,7 +280,32 @@ export type DocmostClientConfig = {
 };

 export interface DocmostClientCtor {
-  new (config: DocmostClientConfig): DocmostClient;
+  new (config: DocmostClientConfig): DocmostClientLike;
+}
+
+/**
+ * Local hand-mirror of the `SharedToolSpec` shape exported from
+ * `@docmost/mcp` (packages/mcp/src/tool-specs.ts). Same approach as
+ * `DocmostClientLike`: we do not import the ESM package's types directly across
+ * the CJS/ESM boundary. The registry itself has no runtime deps, but keeping the
+ * type local avoids coupling the server build to the package's type surface.
+ *
+ * `buildShape` is intentionally zod-agnostic: it returns a plain ZodRawShape
+ * built with whatever zod namespace the caller passes (the server passes its own
+ * zod v4; the MCP package passes its zod v3). See the registry module comment.
+ */
+export interface SharedToolSpec {
+  mcpName: string;
+  inAppKey: string;
+  description: string;
+  // Deferred-tool metadata (#332). Optional in this mirror so an older/stale
+  // @docmost/mcp build (pre-#332) still type-checks; the in-app catalog builder
+  // reads them defensively. The external /mcp server ignores both fields.
+  tier?: 'core' | 'deferred';
+  catalogLine?: string;
+  // Loose `z` on purpose: the registry is zod-agnostic so the server can pass
+  // its own zod (v4) and the MCP package its own (v3) into the same builder.
+  buildShape?: (z: any) => Record<string, unknown>;
 }

 /**
@@ -148,50 +344,6 @@ interface DocmostMcpModule {
  // loader in unit tests. The in-app layer treats an absent factory as "signal
  // disabled" — a pure no-op that leaves tool results byte-identical.
  createCommentSignalTracker?: CommentSignalTrackerFactory;
-  // Optional (#447): a deterministic hash of the tool-specs registry content,
-  // generated into build/ by the package's build. Absent on a pre-#447 build (or
-  // the mocked loader in unit tests) — the stale-check below is a NO-OP when it
-  // is missing, so an older build never wrongly fails startup.
-  REGISTRY_STAMP?: string;
-}
-
-/**
- * Recompute the REGISTRY_STAMP (#447) from the @docmost/mcp source tree, if it is
- * present. Returns the stamp string, or `null` when the source is absent (a prod
- * image ships only build/, no src/). MUST stay byte-for-byte identical to
- * packages/mcp/scripts/gen-registry-stamp.mjs's `computeRegistryStamp` so the
- * build-time and src-time hashes agree: same input file (src/tool-specs.ts), same
- * normalization (CRLF -> LF, strip a single trailing newline), same sha256.
- *
- * DEV vs PROD detection is by FILE EXISTENCE, not NODE_ENV: we resolve the
- * package's own directory from `require.resolve('@docmost/mcp')` (which points at
- * build/index.js) and look for ../src/tool-specs.ts next to it. In a dev/test
- * worktree that file exists; in a prod image (build/ only, src/ stripped) it does
- * not, so this returns null and the caller skips the check. Any error (ENOENT, a
- * bad resolve) is swallowed to null — the stale-check must NEVER break startup.
- *
- * Exported for unit testing (docmost-client.loader.spec.ts): the export keyword
- * is behaviourally a no-op — the module-internal caller `loadDocmostMcp` is
- * unaffected. The test drives the null (no-src) path and asserts this
- * normalize+sha256 stays identical to the codegen's `computeRegistryStamp`.
- */
-export function computeSrcRegistryStamp(packageEntry: string): string | null {
-  try {
-    // packageEntry is <pkg>/build/index.js; the source lives at <pkg>/src/.
-    const toolSpecsPath = join(
-      dirname(dirname(packageEntry)),
-      'src',
-      'tool-specs.ts',
-    );
-    if (!existsSync(toolSpecsPath)) return null; // prod: no src tree -> skip.
-    const source = readFileSync(toolSpecsPath, 'utf8');
-    const normalized = source.replace(/\r\n/g, '\n').replace(/\n$/, '');
-    return createHash('sha256').update(normalized, 'utf8').digest('hex');
-  } catch {
-    // Never let a resolution/read hiccup break server startup — treat as "no
-    // src available" and skip the check (identical to the prod no-op path).
-    return null;
-  }
 }

 // TS with module:commonjs downlevels a literal `import()` to `require()`, which
@@ -223,23 +375,6 @@ export async function loadDocmostMcp(): Promise<{
      const mod = (await esmImport(
        pathToFileURL(entry).href,
      )) as DocmostMcpModule;
-      // #447 stale-build guard (dev/test only). The server loads the COMPILED
-      // build/ of @docmost/mcp, but the parity/tier guard tests read src/. If a
-      // tool spec is edited in src without rebuilding the package, build/ and src/
-      // silently diverge and the running server serves the OLD tools. Here we
-      // recompute the stamp from src/tool-specs.ts and compare it to the stamp
-      // baked into build/. In PROD the src tree is absent (image ships build/
-      // only), so computeSrcRegistryStamp returns null and this is a pure no-op.
-      const srcStamp = computeSrcRegistryStamp(entry);
-      if (
-        srcStamp !== null &&
-        typeof mod.REGISTRY_STAMP === 'string' &&
-        srcStamp !== mod.REGISTRY_STAMP
-      ) {
-        throw new Error(
-          '@docmost/mcp build is stale (tool-specs changed since last build) — run: pnpm --filter @docmost/mcp build',
-        );
-      }
      return mod;
    })().catch((err) => {
      // Do not cache a rejected import — allow the next call to retry.
@@ -5,26 +5,18 @@
  "private": true,
  "type": "module",
  "main": "./build/index.js",
-  "types": "./build/index.d.ts",
  "exports": {
-    ".": {
-      "types": "./build/index.d.ts",
-      "default": "./build/index.js"
-    },
-    "./http": {
-      "types": "./build/http.d.ts",
-      "default": "./build/http.js"
-    }
+    ".": "./build/index.js",
+    "./http": "./build/http.js"
  },
  "bin": {
    "docmost-mcp": "./build/stdio.js"
  },
  "scripts": {
-    "gen:stamp": "node scripts/gen-registry-stamp.mjs",
-    "build": "node scripts/gen-registry-stamp.mjs && tsc",
+    "build": "tsc",
    "start": "node build/stdio.js",
-    "watch": "node scripts/gen-registry-stamp.mjs && tsc --watch",
-    "pretest": "node scripts/gen-registry-stamp.mjs && tsc",
+    "watch": "tsc --watch",
+    "pretest": "tsc",
    "test": "node --test \"test/unit/*.test.mjs\" \"test/mock/*.test.mjs\"",
    "test:unit": "node --test \"test/unit/*.test.mjs\"",
    "test:mock": "node --test \"test/mock/*.test.mjs\"",
@@ -1,67 +0,0 @@
-// Codegen: emit src/registry-stamp.generated.ts with a REGISTRY_STAMP hash of
-// the tool-specs REGISTRY CONTENT, so a build/ vs src/ skew (issue #447) is
-// detectable at runtime.
-//
-// WHY hash the raw source text (not extracted structured data):
-// SHARED_TOOL_SPECS carries `buildShape` functions (the input SCHEMAS) which are
-// NOT serializable. The input schema is exactly one of the things that MUST stay
-// in sync between build/ and src/, so we cannot drop it from the hash. Rather
-// than probe zod with a fragile shim to reconstruct the schema shape, we hash the
-// STABLE, deterministic source TEXT of tool-specs.ts. That text fully captures
-// every field that must stay in sync — mcpName, inAppKey, description, tier,
-// catalogLine AND the buildShape bodies (input schemas) — with zero probing
-// fragility. Any edit to a spec (a renamed tool, a reworded description, a
-// changed schema field) changes the text and therefore the stamp.
-//
-// DETERMINISM: the hash is computed over the file bytes with line endings
-// normalized to LF and a single trailing newline stripped, so a CRLF checkout or
-// an editor's trailing-newline habit cannot make build/ and src/ disagree. No
-// Date.now / randomness. The loader's dev-only stale-check (docmost-client.loader.ts)
-// re-runs THIS SAME normalization + sha256 over src/tool-specs.ts and compares to
-// the built REGISTRY_STAMP; the two must compute identically.
-//
-// This script runs from the `build` and `pretest` npm scripts BEFORE tsc, so
-// build/ always carries a stamp derived from the tool-specs.ts that was compiled.
-
-import { createHash } from 'node:crypto';
-import { readFileSync, writeFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const SRC_DIR = join(__dirname, '..', 'src');
-const TOOL_SPECS_PATH = join(SRC_DIR, 'tool-specs.ts');
-const OUT_PATH = join(SRC_DIR, 'registry-stamp.generated.ts');
-
-/**
- * Deterministic stamp of the tool-specs registry content. Kept as a plain
- * function (exported) so the algorithm has a single home; the loader duplicates
- * only the tiny normalize+sha256 steps because it lives in the CJS server build
- * and cannot import this ESM script. If you change the normalization here, mirror
- * it in apps/server/src/core/ai-chat/tools/docmost-client.loader.ts.
- */
-export function computeRegistryStamp(toolSpecsSource) {
-  const normalized = toolSpecsSource.replace(/\r\n/g, '\n').replace(/\n$/, '');
-  return createHash('sha256').update(normalized, 'utf8').digest('hex');
-}
-
-function main() {
-  const source = readFileSync(TOOL_SPECS_PATH, 'utf8');
-  const stamp = computeRegistryStamp(source);
-  const out =
-    '// AUTO-GENERATED by scripts/gen-registry-stamp.mjs — DO NOT EDIT BY HAND.\n' +
-    '// A deterministic hash of src/tool-specs.ts content (tool names, descriptions,\n' +
-    '// tiers, catalog lines and input schemas). Regenerated on every build/pretest\n' +
-    '// so build/ always matches the compiled src. The in-app loader recomputes this\n' +
-    '// from src and refuses to run on a mismatch (issue #447). This file is\n' +
-    '// gitignored and produced by the build — see .gitignore.\n' +
-    `export const REGISTRY_STAMP = ${JSON.stringify(stamp)};\n`;
-  writeFileSync(OUT_PATH, out, 'utf8');
-  // eslint-disable-next-line no-console
-  console.log(`gen-registry-stamp: wrote ${OUT_PATH} (${stamp.slice(0, 12)}…)`);
-}
-
-// Only run when invoked directly (not when imported for computeRegistryStamp).
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
-  main();
-}
@@ -42,6 +42,7 @@ import {
  insertTableRow,
  deleteTableRow,
  updateTableCell,
+  findInvalidNode,
 } from "@docmost/prosemirror-markdown";
 import { searchInDoc, SearchOptions } from "./lib/page-search.js";
 import { withPageLock } from "./lib/page-lock.js";
@@ -1660,6 +1661,27 @@ export class DocmostClient {
    }
  }

+  /**
+   * Pre-write SHAPE gate (#409). Walk the WHOLE node tree with the shared
+   * `findInvalidNode` and throw a rich, path-anchored error the instant a nested
+   * node has an absent/unknown `type` (or an unknown mark) — the exact shape that
+   * otherwise surfaces DEEP in the Yjs encode as the cryptic
+   * `Unknown node type: undefined`, but only AFTER a collab session was opened
+   * and a page lock taken. Calling this BEFORE `getCollabTokenWithReauth` /
+   * `mutatePageContent` fails fast: no collab connection, no lock, deterministic
+   * message. `op` names the tool for the message prefix (e.g. "patch_node").
+   *
+   * `findInvalidNode` derives its "known type" set from the very same
+   * `docmostExtensions` the encode path uses, so a node this gate accepts is one
+   * the encoder will accept too.
+   */
+  private assertValidNodeShape(op: string, node: any): void {
+    const bad = findInvalidNode(node);
+    if (bad) {
+      throw new Error(`${op}: invalid node — ${bad.summary}`);
+    }
+  }
+
  /**
   * Replace page content with a raw ProseMirror JSON document (lossless) and/or
   * update its title. Both `doc` and `title` are optional, but at least one must
@@ -1711,6 +1733,12 @@ export class DocmostClient {
    // page on overwrite.
    this.validateDocStructure(doc);

+    // #409: beyond the string-`type` check above, reject a nested node whose
+    // `type` is a string but NOT a known Docmost schema node (a typo/unknown
+    // block) — the same `Unknown node type` the encoder throws — with a rich,
+    // path-anchored message, still BEFORE any collab connection.
+    this.assertValidNodeShape("update_page_json", doc);
+
    // Sanitize URLs before writing. This closes the JSON-path bypass: unlike
    // the markdown link path (which TipTap sanitizes), raw JSON could otherwise
    // inject javascript:/data: link hrefs or media srcs straight into the doc.
@@ -2131,6 +2159,14 @@ export class DocmostClient {
      target.attrs.id = nodeId;
    }

+    // #409: fail fast on a malformed node SHAPE (a nested child with an
+    // absent/unknown `type`, e.g. a text leaf written as `{"text":"foo"}` with
+    // no `"type":"text"`) BEFORE opening a collab session or taking the page
+    // lock — the root-only `typeof node.type === "string"` check above never
+    // sees nested children, and the encoder's `Unknown node type: undefined`
+    // would otherwise only surface after the connection.
+    this.assertValidNodeShape("patch_node", target);
+
    const collabToken = await this.getCollabTokenWithReauth();
    // Open the collab doc by the canonical UUID, never the slugId (#260).
    const pageUuid = await this.resolvePageId(pageId);
@@ -2221,6 +2257,11 @@ export class DocmostClient {
      }
    }

+    // #409: fail fast on a malformed node SHAPE (a nested child with an
+    // absent/unknown `type`) BEFORE opening a collab session or taking the page
+    // lock — the root-only check above never sees nested children.
+    this.assertValidNodeShape("insert_node", node);
+
    const collabToken = await this.getCollabTokenWithReauth();
    // Open the collab doc by the canonical UUID, never the slugId (#260).
    const pageUuid = await this.resolvePageId(pageId);
@@ -6,7 +6,6 @@ import { dirname, join } from "path";
 import { DocmostClient, DocmostMcpConfig } from "./client.js";
 import { parseNodeArg } from "@docmost/prosemirror-markdown";
 import { SHARED_TOOL_SPECS, SharedToolSpec } from "./tool-specs.js";
-import { SERVER_INSTRUCTIONS } from "./server-instructions.js";
 import {
  createCommentSignalTracker,
  CommentSignalTracker,
@@ -30,14 +29,6 @@ export { destroyAllSessions } from "./lib/collab-session.js";
 export { SHARED_TOOL_SPECS } from "./tool-specs.js";
 export type { SharedToolSpec } from "./tool-specs.js";

-// Re-export the build-time REGISTRY_STAMP (issue #447): a deterministic hash of
-// the tool-specs registry content, generated into src/registry-stamp.generated.ts
-// by scripts/gen-registry-stamp.mjs BEFORE tsc, so it lands in build/. The in-app
-// loader recomputes the same hash from src/tool-specs.ts (dev/test only) and
-// refuses to run on a mismatch, catching a build/ vs src/ skew (a spec edited in
-// src without rebuilding the package the server actually loads from build/).
-export { REGISTRY_STAMP } from "./registry-stamp.generated.js";
-
 // Re-export the shared "new comments: N" signal helper (#417) so the in-app
 // layer reads the SAME watermark/debounce/injection-safe line builder off the
 // loaded module (same pattern as SHARED_TOOL_SPECS). Both surfaces then differ
@@ -75,12 +66,19 @@ const VERSION = packageJson.version;
 // Editing guide surfaced to MCP clients in the initialize result so they can
 // pick the right tool by intent and avoid resending whole documents.
 //
-// The guide is now SPLIT (issue #448): the hand-written routing prose lives in
-// server-instructions.ts and the tool INVENTORY is GENERATED from the registry
-// (SHARED_TOOL_SPECS + INLINE_MCP_INVENTORY), so it can no longer drift out of
-// sync with the registered tools. Re-exported here (its old home) so existing
-// importers are unaffected; the composition lives in server-instructions.ts.
-export { SERVER_INSTRUCTIONS };
+// MAINTENANCE RULE: when you ADD, RENAME, or REMOVE a tool (either an inline
+// server.registerTool(...) here or a spec in tool-specs.ts), you MUST update
+// this guide so the new tool is routed by intent. This is enforced by
+// test/unit/server-instructions.test.mjs, which fails when a registered tool
+// name is not mentioned below (see its EXCEPTIONS list for the rare opt-outs).
+// Exported for that test.
+export const SERVER_INSTRUCTIONS =
+  "Docmost editing guide — choose the tool by intent.\n" +
+  "READ: find a page -> search (workspace-wide full-text); list -> list_pages / list_spaces. Locate blocks and their ids CHEAPLY -> get_outline (compact top-level map; start here, not get_page_json). One block's subtree -> get_node (by attrs.id, or \"#<index>\" for tables, which carry no id). Find every occurrence of a string/regex ON a page (and where each is) -> search_in_page, NOT block-by-block get_node — it returns each hit's node ref + block index + context for a targeted comment. Whole page -> get_page (Markdown, lossy; inline <span data-comment-id> tags are comment anchors — markup, not text) or get_page_json (lossless ProseMirror with block ids). Hand a huge page (with images) to an external consumer without pulling it through the model context -> stash_page (returns a short-lived anonymous URL).\n" +
+  "EDIT: fix wording/typos/numbers -> edit_page_text (find/replace inside blocks, no node id needed). Change ONE block (paragraph/heading/callout/etc.) structurally -> patch_node (by attrs.id from get_outline). Add a block -> insert_node (before/after a block by attrs.id or by anchor text, or append). Remove a block -> delete_node (by attrs.id). Tables -> table_get / table_update_cell / table_insert_row / table_delete_row (address by \"#<index>\" from get_outline; table nodes have no attrs.id). Images -> insert_image (add from a web URL) / replace_image (swap an existing image). Draw.io diagrams -> drawio_create (create from mxGraph XML and insert), drawio_get (read a diagram as mxGraph XML + a hash), drawio_update (replace a diagram; pass the hash from drawio_get as baseHash for optimistic locking). Footnotes -> insert_footnote. Bulk/structural rewrite -> update_page_json (full ProseMirror replace; prefer the granular tools above to avoid resending the whole ~100KB+ document). Complex/scripted rewrite (multiple coordinated edits, renumbering) -> docmost_transform: write a JS `(doc, ctx) => doc` transform, preview the diff with dryRun (default), then apply with dryRun:false; ctx.helpers includes commentsToFootnotes for turning inline comments into numbered footnotes.\n" +
+  "PAGES: new -> create_page (Markdown). Rename (title only) -> rename_page. Move -> move_page. Delete -> delete_page (SOFT delete — the page goes to trash and is restorable; nothing is permanent). Copy/replace a page's whole content from another page (server-side, no document through the model) -> copy_page_content. Sharing -> share_page / unshare_page / list_shares; share_page makes the page PUBLICLY accessible — do it only when explicitly asked.\n" +
+  "COMMENTS: create_comment is always inline and requires an EXACT selection — contiguous text from a single block, <=250 chars (fails rather than leaving an unanchored comment); reply to a thread via parentCommentId. Propose a concrete text fix for one-click human approval -> create_comment with suggestedText (the exact plain-text replacement for the selection; the selection must then be UNIQUE in the page — extend it with context if needed); prefer this over editing directly when the change is subjective or needs the author's sign-off. Manage -> list_comments, update_comment, resolve_comment (resolve/reopen, reversible — prefer over delete to close), delete_comment, check_new_comments.\n" +
+  "HISTORY: review what changed -> diff_page_versions (a historyId vs current, or two versions). List saved versions -> list_page_history. Undo a bad edit -> restore_page_version (writes a past version back as current; itself revertible). Lossless markdown round-trip (download, edit, re-upload, incl. comment anchors) -> export_page_markdown / import_page_markdown.";

 // Helper to format JSON responses
 const jsonContent = (data: any) => ({
@@ -196,10 +194,10 @@ export function createDocmostMcpServer(config: DocmostMcpConfig): McpServer {
    { instructions: SERVER_INSTRUCTIONS },
  );

-  // Single choke point for MCP tool timing. Both `registerSharedFromSpec` (below)
-  // and the inline `server.registerTool(...)` calls funnel through this one
-  // method, so monkeypatching it HERE — before any tool is registered and before
-  // the registry loop captures a reference to it — times every tool with no
+  // Single choke point for MCP tool timing. Both `registerShared` (below) and
+  // the inline `server.registerTool(...)` calls funnel through this one method,
+  // so monkeypatching it HERE — before any tool is registered and before
+  // `registerShared` captures a reference to it — times every tool with no
  // per-tool boilerplate. The wrapped handler records wall-clock duration and,
  // in a `finally`, feeds the host's dependency-neutral sink
  // `config.onMetric("mcp_tool_duration_seconds", seconds, { tool })`. The tool
@@ -255,56 +253,92 @@ export function createDocmostMcpServer(config: DocmostMcpConfig): McpServer {
    return originalRegisterTool(...args.slice(0, -1), signalledHandler);
  };

-  // Register EVERY shared tool from the zod-agnostic registry in one loop (#445).
-  // The spec owns the canonical name + description + (optional) schema builder AND
-  // the canonical execute mapping; the host only supplies the RESULT ENVELOPE. For
-  // each spec:
-  //   - skip `inAppOnly` specs (they belong to the in-app host only);
-  //   - if the spec has an `mcpExecute` override (a deliberate per-layer
-  //     difference — a guardrail, an omitted param, or a non-JSON envelope like a
-  //     resource_link/bare success line), the override OWNS the full MCP content
-  //     result and is used VERBATIM;
-  //   - otherwise the canonical `execute` returns RAW data and this host wraps it
-  //     in the standard JSON text envelope (jsonContent), exactly as the old inline
-  //     bodies did.
-  // buildShape is invoked with THIS package's zod (v3); the in-app layer passes its
-  // own zod (v4). The registry's execute returns `unknown` (it is zod-agnostic), so
-  // the wrapping is typed loosely and cast — runtime behaviour is unchanged.
-  const registerSharedFromSpec = (spec: SharedToolSpec) => {
-    if (spec.inAppOnly) return;
-    const handler = async (args: any) => {
-      if (spec.mcpExecute) {
-        // The override owns the full MCP result envelope (not re-wrapped).
-        return (await spec.mcpExecute(docmostClient, args)) as {
-          content: { type: "text"; text: string }[];
-        };
-      }
-      // Canonical execute returns raw data; wrap it as JSON text content.
-      const raw = await spec.execute!(docmostClient, args);
-      return jsonContent(raw);
-    };
-    return (server.registerTool as any)(
+  // Register a tool from the shared, zod-agnostic spec registry. The spec owns
+  // the canonical name + model-facing description + (optional) schema builder;
+  // only the execute body is supplied per call. buildShape is invoked with THIS
+  // package's zod (v3); the in-app layer passes its own zod (v4).
+  //
+  // The spec's schema builder returns a plain ZodRawShape (Record<string,
+  // unknown> in the shared module since it must stay zod-agnostic), so the
+  // McpServer.registerTool overloads cannot infer the execute arg's shape from
+  // it. We type `execute` loosely and cast the call through `any`; runtime
+  // behaviour is unchanged — each execute body destructures the same fields the
+  // builder declares.
+  const registerShared = (
+    spec: SharedToolSpec,
+    execute: (args: any) => Promise<{ content: { type: "text"; text: string }[] }>,
+  ) =>
+    (server.registerTool as any)(
      spec.mcpName,
      spec.buildShape
        ? { description: spec.description, inputSchema: spec.buildShape(z) }
        : { description: spec.description },
-      handler,
+      execute,
    );
-  };

-  for (const spec of Object.values(SHARED_TOOL_SPECS)) {
-    registerSharedFromSpec(spec as SharedToolSpec);
-  }
+  // Tool: get_workspace
+  registerShared(SHARED_TOOL_SPECS.getWorkspace, async () => {
+    const workspace = await docmostClient.getWorkspace();
+    return jsonContent(workspace);
+  });

-  // --- INLINE tools kept per-transport (NOT in the shared registry) ---
-  // Each stays inline for a documented reason: a snake_case/camelCase naming
-  // clash the registry convention forbids (table_get), an intentional
-  // per-transport behaviour/schema divergence (search, docmost_transform), or a
-  // tool that exists ONLY on this standalone MCP surface (update_comment,
-  // delete_comment — the in-app agent deliberately exposes no hard comment
-  // edit/delete tool).
+  // Tool: list_spaces
+  registerShared(SHARED_TOOL_SPECS.listSpaces, async () => {
+    const spaces = await docmostClient.getSpaces();
+    return jsonContent(spaces);
+  });

-  // Tool: table_get
+// Tool: list_pages
+// INTENTIONAL per-transport divergence (not in the shared registry): this
+// 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);
+});
+
+// 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);
+});
+
+// Tool: get_page_json
+registerShared(SHARED_TOOL_SPECS.getPageJson, async ({ pageId }) => {
+  const page = await docmostClient.getPageJson(pageId);
+  return jsonContent(page);
+});
+
+// Tool: get_outline
+registerShared(SHARED_TOOL_SPECS.getOutline, async ({ pageId }) => {
+  const result = await docmostClient.getOutline(pageId);
+  return jsonContent(result);
+});
+
+// Tool: get_node
+registerShared(SHARED_TOOL_SPECS.getNode, async ({ pageId, nodeId }) => {
+  const result = await docmostClient.getNode(pageId, nodeId);
+  return jsonContent(result);
+});
+
+// Tool: search_in_page
+registerShared(
+  SHARED_TOOL_SPECS.searchInPage,
+  async ({ pageId, query, regex, caseSensitive, limit }) => {
+    const result = await docmostClient.searchInPage(pageId, query, {
+      regex,
+      caseSensitive,
+      limit,
+    });
+    return jsonContent(result);
+  },
+);
+
+// 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).
@@ -330,6 +364,383 @@ 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,
+  async ({ pageId, table, cells, index }) => {
+    const result = await docmostClient.tableInsertRow(
+      pageId,
+      table,
+      cells,
+      index,
+    );
+    return jsonContent(result);
+  },
+);
+
+// Tool: table_delete_row
+// Schema + description now live in the shared registry (#294).
+registerShared(
+  SHARED_TOOL_SPECS.tableDeleteRow,
+  async ({ pageId, table, index }) => {
+    const result = await docmostClient.tableDeleteRow(pageId, table, index);
+    return jsonContent(result);
+  },
+);
+
+// Tool: table_update_cell
+// Schema + description now live in the shared registry (#294).
+registerShared(
+  SHARED_TOOL_SPECS.tableUpdateCell,
+  async ({ pageId, table, row, col, text }) => {
+    const result = await docmostClient.tableUpdateCell(
+      pageId,
+      table,
+      row,
+      col,
+      text,
+    );
+    return jsonContent(result);
+  },
+);
+
+// Tool: create_page
+// Schema + description now live in the shared registry (#294).
+registerShared(
+  SHARED_TOOL_SPECS.createPage,
+  async ({ title, content, spaceId, parentPageId }) => {
+    const result = await docmostClient.createPage(
+      title,
+      content,
+      spaceId,
+      parentPageId,
+    );
+    return jsonContent(result);
+  },
+);
+
+// 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,
+  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
+    // (or no-op) update.
+    let doc;
+    if (content === undefined || content === null) {
+      doc = undefined;
+    } else {
+      // String -> JSON.parse (throwing on invalid); object passes through.
+      doc = parseNodeArg(content, "content was a string but not valid JSON");
+    }
+    const result = await docmostClient.updatePageJson(pageId, doc, title);
+    return jsonContent(result);
+  },
+);
+
+// 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 }] };
+});
+
+// Tool: import_page_markdown
+registerShared(
+  SHARED_TOOL_SPECS.importPageMarkdown,
+  async ({ pageId, markdown }) => {
+    const res = await docmostClient.importPageMarkdown(pageId, markdown);
+    return jsonContent(res);
+  },
+);
+
+// Tool: copy_page_content
+registerShared(
+  SHARED_TOOL_SPECS.copyPageContent,
+  async ({ sourcePageId, targetPageId }) => {
+    const result = await docmostClient.copyPageContent(
+      sourcePageId,
+      targetPageId,
+    );
+    return jsonContent(result);
+  },
+);
+
+// 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);
+});
+
+// Tool: edit_page_text
+registerShared(SHARED_TOOL_SPECS.editPageText, async ({ pageId, edits }) => {
+  const result = await docmostClient.editPageText(pageId, edits);
+  return jsonContent(result);
+});
+
+// Tool: stash_page — returns a resource_link (NOT embedded text) so the doc
+// body never enters the model context. Registered directly (not via
+// registerShared) because that helper only emits text content. Also returns
+// `structuredContent` carrying the full documented `{uri, sha256, size, images}`
+// shape alongside the resource_link, so MCP clients receive the blob's sha256
+// (its ETag, for integrity) and mirror counts, not just the link.
+server.registerTool(
+  SHARED_TOOL_SPECS.stashPage.mcpName,
+  {
+    description: SHARED_TOOL_SPECS.stashPage.description,
+    inputSchema: SHARED_TOOL_SPECS.stashPage.buildShape!(z),
+  },
+  async ({ pageId }: { pageId: string }) => {
+    const result = await docmostClient.stashPage(pageId);
+    return {
+      content: [
+        {
+          type: "resource_link" as const,
+          uri: result.uri,
+          name: "page.json",
+          mimeType: "application/json",
+          size: result.size,
+        },
+      ],
+      // Mirror the full documented result shape ({ uri, size, sha256, images })
+      // as structuredContent so MCP clients get the blob's sha256 (its ETag, for
+      // integrity) and the mirror counts, not just the resource_link.
+      structuredContent: {
+        uri: result.uri,
+        sha256: result.sha256,
+        size: result.size,
+        images: result.images,
+      },
+    };
+  },
+);
+
+// Tool: patch_node — schema + description from the shared registry (identical
+// across both transports). The execute body keeps its own parseNodeArg
+// normalization (the model sometimes serializes `node` as a JSON string).
+registerShared(
+  SHARED_TOOL_SPECS.patchNode,
+  async ({ pageId, nodeId, node }) => {
+    const parsedNode = parseNodeArg(node);
+    const result = await docmostClient.patchNode(pageId, nodeId, parsedNode);
+    return jsonContent(result);
+  },
+);
+
+// Tool: insert_node — schema + description from the shared registry. As with
+// patch_node, the execute body retains parseNodeArg on the incoming node.
+registerShared(
+  SHARED_TOOL_SPECS.insertNode,
+  async ({ pageId, node, position, anchorNodeId, anchorText }) => {
+    const parsedNode = parseNodeArg(node);
+    const result = await docmostClient.insertNode(pageId, parsedNode, {
+      position,
+      anchorNodeId,
+      anchorText,
+    });
+    return jsonContent(result);
+  },
+);
+
+// Tool: delete_node
+registerShared(SHARED_TOOL_SPECS.deleteNode, async ({ pageId, nodeId }) => {
+  const result = await docmostClient.deleteNode(pageId, nodeId);
+  return jsonContent(result);
+});
+
+// Tool: insert_image
+// Schema + description now live in the shared registry (#410) so BOTH this MCP
+// server and the in-app AI-chat agent expose it. The execute body is unchanged.
+registerShared(
+  SHARED_TOOL_SPECS.insertImage,
+  async ({ pageId, imageUrl, align, alt, replaceText, afterText }) => {
+    const result = await docmostClient.insertImage(pageId, imageUrl, {
+      align,
+      alt,
+      replaceText,
+      afterText,
+    });
+    return jsonContent(result);
+  },
+);
+
+// Tool: replace_image
+// Schema + description now live in the shared registry (#410).
+registerShared(
+  SHARED_TOOL_SPECS.replaceImage,
+  async ({ pageId, attachmentId, imageUrl, align, alt }) => {
+    const result = await docmostClient.replaceImage(
+      pageId,
+      attachmentId,
+      imageUrl,
+      {
+        align,
+        alt,
+      },
+    );
+    return jsonContent(result);
+  },
+);
+
+// Tool: drawio_get — read a draw.io diagram as mxGraph XML (or the raw SVG).
+registerShared(
+  SHARED_TOOL_SPECS.drawioGet,
+  async ({ pageId, node, format }) => {
+    const result = await docmostClient.drawioGet(pageId, node, format ?? "xml");
+    return jsonContent(result);
+  },
+);
+
+// Tool: drawio_create — lint mxGraph XML, build the .drawio.svg, insert a node.
+registerShared(
+  SHARED_TOOL_SPECS.drawioCreate,
+  async ({ pageId, xml, position, anchorNodeId, anchorText, title }) => {
+    const result = await docmostClient.drawioCreate(
+      pageId,
+      { position, anchorNodeId, anchorText },
+      xml,
+      title,
+    );
+    return jsonContent(result);
+  },
+);
+
+// Tool: drawio_update — optimistic-locked full replacement of a diagram.
+registerShared(
+  SHARED_TOOL_SPECS.drawioUpdate,
+  async ({ pageId, node, xml, baseHash }) => {
+    const result = await docmostClient.drawioUpdate(pageId, node, xml, baseHash);
+    return jsonContent(result);
+  },
+);
+
+// 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,
+  async ({ pageId, searchIndexing }) => {
+    const result = await docmostClient.sharePage(pageId, searchIndexing ?? true);
+    return jsonContent(result);
+  },
+);
+
+// Tool: unshare_page
+registerShared(SHARED_TOOL_SPECS.unsharePage, async ({ pageId }) => {
+  const result = await docmostClient.unsharePage(pageId);
+  return jsonContent(result);
+});
+
+// Tool: list_shares
+registerShared(SHARED_TOOL_SPECS.listShares, async () => {
+  const result = await docmostClient.listShares();
+  return jsonContent(result);
+});
+
+// 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,
+  async ({ pageId, parentPageId, position }) => {
+    const finalParentId =
+      parentPageId === "" || parentPageId === "null" ? null : parentPageId;
+
+    // Cheap cycle guard: a page cannot be moved directly under itself.
+    // (Deeper descendant-cycle detection is intentionally out of scope.)
+    if (finalParentId !== null && finalParentId === pageId) {
+      throw new Error("cannot move a page under itself");
+    }
+
+    const result = await docmostClient.movePage(
+      pageId,
+      finalParentId || null,
+      position,
+    );
+
+    // Require POSITIVE confirmation: the live /pages/move success shape is
+    // exactly { success: true, status: 200 }. An empty body, a 204, or any odd
+    // shape lacking success === true must NOT be reported as a successful move,
+    // so we surface the raw API result instead of declaring success.
+    if (!(result && typeof result === "object" && result.success === true)) {
+      throw new Error(
+        `Failed to move page ${pageId}: ${JSON.stringify(result)}`,
+      );
+    }
+
+    return jsonContent({
+      message: `Successfully moved page ${pageId} to parent ${finalParentId || "root"}`,
+      result,
+    });
+  },
+);
+
+// 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}` },
+    ],
+  };
+});
+
+// --- Comment tools (ported from upstream PR #3 by Max Nikitin) ---
+
+// Tool: list_comments
+registerShared(
+  SHARED_TOOL_SPECS.listComments,
+  async ({ pageId, includeResolved }) => {
+    const comments = await docmostClient.listComments(pageId, includeResolved);
+    return jsonContent(comments);
+  },
+);
+
+// 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,
+  async ({ pageId, content, selection, parentCommentId, suggestedText }) => {
+    if (!parentCommentId && (!selection || !selection.trim())) {
+      throw new Error(
+        "create_comment: a 'selection' (exact text to anchor on) is required for a top-level comment; omit it only when replying via parentCommentId.",
+      );
+    }
+    if (suggestedText !== undefined) {
+      if (parentCommentId) {
+        throw new Error(
+          "create_comment: 'suggestedText' cannot be attached to a reply; it applies only to a top-level inline comment.",
+        );
+      }
+      if (!selection || !selection.trim()) {
+        throw new Error(
+          "create_comment: 'suggestedText' requires a 'selection' to anchor and rewrite.",
+        );
+      }
+    }
+    const result = await docmostClient.createComment(
+      pageId,
+      content,
+      "inline",
+      selection,
+      parentCommentId,
+      suggestedText,
+    );
+    return jsonContent(result);
+  },
+);
+
 // Tool: update_comment
 server.registerTool(
  "update_comment",
@@ -374,6 +785,39 @@ server.registerTool(
  },
 );

+// Tool: resolve_comment
+// Schema + description now live in the shared registry (#294).
+registerShared(
+  SHARED_TOOL_SPECS.resolveComment,
+  async ({ commentId, resolved }) => {
+    const result = await docmostClient.resolveComment(commentId, resolved);
+    return jsonContent(result);
+  },
+);
+
+// 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,
+  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
+    // returns zero results without signalling the bad input.
+    if (Number.isNaN(Date.parse(since))) {
+      throw new Error(
+        `Invalid 'since' timestamp: ${JSON.stringify(since)} — expected an ISO 8601 date (e.g. '2026-03-10T00:00:00Z')`,
+      );
+    }
+    const result = await docmostClient.checkNewComments(
+      spaceId,
+      since,
+      parentPageId,
+    );
+    return jsonContent(result);
+  },
+);
+
 // Tool: search
 // INTENTIONAL per-transport divergence (not shared): the in-app `searchPages`
 // runs a semantic + keyword hybrid (RRF) with in-process access control and a
@@ -483,5 +927,43 @@ server.registerTool(
  },
 );

+// Tool: insert_footnote
+// Schema + description now live in the shared registry (#410) so the in-app
+// AI-chat agent exposes it too. The execute body is unchanged.
+registerShared(
+  SHARED_TOOL_SPECS.insertFootnote,
+  async ({ pageId, anchorText, text }) => {
+    const result = await docmostClient.insertFootnote(pageId, anchorText, text);
+    return jsonContent(result);
+  },
+);
+
+// Tool: diff_page_versions
+registerShared(
+  SHARED_TOOL_SPECS.diffPageVersions,
+  async ({ pageId, from, to }) => {
+    const result = await docmostClient.diffPageVersions(pageId, from, to);
+    return jsonContent(result);
+  },
+);
+
+// Tool: list_page_history
+registerShared(
+  SHARED_TOOL_SPECS.listPageHistory,
+  async ({ pageId, cursor }) => {
+    const result = await docmostClient.listPageHistory(pageId, cursor);
+    return jsonContent(result);
+  },
+);
+
+// Tool: restore_page_version
+registerShared(
+  SHARED_TOOL_SPECS.restorePageVersion,
+  async ({ historyId }) => {
+    const result = await docmostClient.restorePageVersion(historyId);
+    return jsonContent(result);
+  },
+);
+
  return server;
 }
@@ -13,7 +13,11 @@ import { JSDOM } from "jsdom";
 import { markdownToProseMirror } from "@docmost/prosemirror-markdown";
 import { docmostExtensions, docmostSchema } from "./docmost-schema.js";
 import { withPageLock } from "./page-lock.js";
-import { sanitizeForYjs, findUnstorableAttr } from "@docmost/prosemirror-markdown";
+import {
+  sanitizeForYjs,
+  findUnstorableAttr,
+  findInvalidNode,
+} from "@docmost/prosemirror-markdown";
 import { canonicalizeFootnotes } from "./footnote-canonicalize.js";
 import { normalizeAndMergeFootnotes } from "./footnote-normalize-merge.js";
 import { VerifyReport } from "./diff.js";
@@ -28,11 +32,25 @@ export { markdownToProseMirror };
 * place. `label` names the stage that failed (diagnostic). `sanitizeForYjs`
 * already stripped `undefined` attrs, so a remaining failure is pinpointed via
 * `findUnstorableAttr`.
+ *
+ * Diagnostics precedence (#409): the dominant crash here is
+ * `Unknown node type: undefined` — a nested node with an absent/unknown `type`
+ * (a SHAPE problem, e.g. `{"text":"foo"}` missing `"type":"text"`). That points
+ * at the node, not an attribute, so `findInvalidNode` is consulted FIRST and,
+ * on a hit, yields a path-anchored node-shape message. Only when the document
+ * shape is sound do we fall back to `findUnstorableAttr` (undefined/function/
+ * symbol/bigint attr values); the generic "attribute likely holds a value Yjs
+ * cannot store" sentence is the last resort.
 */
 function unstorableYjsError(safe: any, label: string, e: unknown): Error {
+  const base = `Failed to encode document to Yjs (${label}): ${e instanceof Error ? e.message : String(e)}.`;
+  const badNode = findInvalidNode(safe);
+  if (badNode) {
+    return new Error(`${base} Invalid node: ${badNode.summary}`);
+  }
  const bad = findUnstorableAttr(safe);
  return new Error(
-    `Failed to encode document to Yjs (${label}): ${e instanceof Error ? e.message : String(e)}.${bad ? ` Offending attribute: ${bad}.` : " A node/mark attribute likely holds a value Yjs cannot store (e.g. undefined)."}`,
+    `${base}${bad ? ` Offending attribute: ${bad}.` : " A node/mark attribute likely holds a value Yjs cannot store (e.g. undefined)."}`,
  );
 }

@@ -1,237 +0,0 @@
-// SERVER_INSTRUCTIONS — the editing guide surfaced to MCP clients in the
-// initialize result so they can pick the right tool by intent and avoid
-// resending whole documents.
-//
-// This guide is split into TWO parts that are composed at the bottom:
-//
-//  1. ROUTING_PROSE — the hand-written "when to use what" intent hints (READ /
-//     EDIT / PAGES / COMMENTS / HISTORY). This is legitimately manual: it
-//     encodes editorial judgement (which tool for which situation, the cheap-
-//     first ordering, the guardrail nudges) that cannot be derived from the
-//     registry. It is NOT the drift-guard for the tool set.
-//
-//  2. A GENERATED <tool_inventory> — every tool the server registers, listed
-//     by name + one-line purpose, grouped by family, built from the SAME
-//     registry the server registers tools from (SHARED_TOOL_SPECS' mcpName +
-//     catalogLine) PLUS the handful of inline MCP-only tools (their inventory
-//     lines live in INLINE_MCP_INVENTORY below). Because this list is BUILT
-//     from the registry, it can never drift out of sync with the registered
-//     tools — adding/renaming/removing a spec changes it automatically, with no
-//     prose edit and no scraper test. An unmapped tool still appears (under
-//     "OTHER"), so a new tool can never silently vanish from the guide.
-//
-// This replaces the old hand-maintained monolithic guide + its regex scraper
-// test (test/unit/server-instructions.test.mjs), which only checked that every
-// registered name appeared SOMEWHERE in the prose and drifted whenever a name
-// was reworded.
-//
-// OUT OF SCOPE (issue #448): the README / README.ru tool catalogs are still
-// hand-maintained prose and are NOT generated from this registry. Regenerating
-// them from SHARED_TOOL_SPECS is tracked separately as an optional docs script
-// under issue #412 — until then a tool rename still needs a manual README edit.
-
-import { SHARED_TOOL_SPECS, SharedToolSpec } from "./tool-specs.js";
-
-/**
- * The hand-written routing prose — the intent hints that tell a client which
- * tool to reach for in which situation. Kept manual on purpose (it encodes
- * editorial judgement, not a mechanical name list). The generated inventory
- * below is spliced in after it.
- */
-export const ROUTING_PROSE =
-  "Docmost editing guide — choose the tool by intent. The <tool_inventory> at the end lists every tool with a one-line purpose; the notes below are the routing hints for WHEN to reach for each.\n" +
-  "READ: find a page -> search (workspace-wide full-text); list -> list_pages / list_spaces. Locate blocks and their ids CHEAPLY -> get_outline (compact top-level map; start here, not get_page_json). One block's subtree -> get_node (by attrs.id, or \"#<index>\" for tables, which carry no id). Find every occurrence of a string/regex ON a page (and where each is) -> search_in_page, NOT block-by-block get_node — it returns each hit's node ref + block index + context for a targeted comment. Whole page -> get_page (Markdown, lossy; inline <span data-comment-id> tags are comment anchors — markup, not text) or get_page_json (lossless ProseMirror with block ids). Hand a huge page (with images) to an external consumer without pulling it through the model context -> stash_page (returns a short-lived anonymous URL).\n" +
-  "EDIT: fix wording/typos/numbers -> edit_page_text (find/replace inside blocks, no node id needed). Change ONE block (paragraph/heading/callout/etc.) structurally -> patch_node (by attrs.id from get_outline). Add a block -> insert_node (before/after a block by attrs.id or by anchor text, or append). Remove a block -> delete_node (by attrs.id). Tables -> table_get / table_update_cell / table_insert_row / table_delete_row (address by \"#<index>\" from get_outline; table nodes have no attrs.id). Images -> insert_image (add from a web URL) / replace_image (swap an existing image). Draw.io diagrams -> drawio_create (create from mxGraph XML and insert), drawio_get (read a diagram as mxGraph XML + a hash), drawio_update (replace a diagram; pass the hash from drawio_get as baseHash for optimistic locking). Footnotes -> insert_footnote. Bulk/structural rewrite -> update_page_json (full ProseMirror replace; prefer the granular tools above to avoid resending the whole ~100KB+ document). Complex/scripted rewrite (multiple coordinated edits, renumbering) -> docmost_transform: write a JS `(doc, ctx) => doc` transform, preview the diff with dryRun (default), then apply with dryRun:false; ctx.helpers includes commentsToFootnotes for turning inline comments into numbered footnotes.\n" +
-  "PAGES: new -> create_page (Markdown). Rename (title only) -> rename_page. Move -> move_page. Delete -> delete_page (SOFT delete — the page goes to trash and is restorable; nothing is permanent). Copy/replace a page's whole content from another page (server-side, no document through the model) -> copy_page_content. Sharing -> share_page / unshare_page / list_shares; share_page makes the page PUBLICLY accessible — do it only when explicitly asked.\n" +
-  "COMMENTS: create_comment is always inline and requires an EXACT selection — contiguous text from a single block, <=250 chars (fails rather than leaving an unanchored comment); reply to a thread via parentCommentId. Propose a concrete text fix for one-click human approval -> create_comment with suggestedText (the exact plain-text replacement for the selection; the selection must then be UNIQUE in the page — extend it with context if needed); prefer this over editing directly when the change is subjective or needs the author's sign-off. Manage -> list_comments, update_comment, resolve_comment (resolve/reopen, reversible — prefer over delete to close), delete_comment, check_new_comments.\n" +
-  "HISTORY: review what changed -> diff_page_versions (a historyId vs current, or two versions). List saved versions -> list_page_history. Undo a bad edit -> restore_page_version (writes a past version back as current; itself revertible). Lossless markdown round-trip (download, edit, re-upload, incl. comment anchors) -> export_page_markdown / import_page_markdown.";
-
-/**
- * A single generated inventory line: the tool's registered NAME + a one-line
- * purpose. For a registry tool the purpose is its `catalogLine` (falling back
- * to the first sentence of its description); for an inline MCP-only tool it is
- * the hand-written line in INLINE_MCP_INVENTORY.
- */
-export interface ToolInventoryLine {
-  name: string;
-  purpose: string;
-}
-
-/**
- * The families the inventory is grouped under, in display order. A tool is
- * placed by looking its mcpName up in TOOL_FAMILY; anything not listed there
- * falls into "OTHER" so it is never dropped from the guide.
- */
-const FAMILY_ORDER = [
-  "READ",
-  "EDIT",
-  "PAGES",
-  "COMMENTS",
-  "HISTORY",
-  "OTHER",
-] as const;
-type Family = (typeof FAMILY_ORDER)[number];
-
-/**
- * mcpName -> family for the generated inventory grouping. Purely cosmetic (it
- * orders the inventory to mirror the routing prose); an unmapped tool still
- * appears under OTHER, so forgetting to add an entry here can never drop a tool
- * from the guide — it only lands it in the catch-all group.
- */
-const TOOL_FAMILY: Record<string, Family> = {
-  // READ
-  search: "READ",
-  list_pages: "READ",
-  list_spaces: "READ",
-  get_outline: "READ",
-  get_node: "READ",
-  search_in_page: "READ",
-  get_page: "READ",
-  get_page_json: "READ",
-  get_workspace: "READ",
-  stash_page: "READ",
-  // EDIT
-  edit_page_text: "EDIT",
-  patch_node: "EDIT",
-  insert_node: "EDIT",
-  delete_node: "EDIT",
-  update_page_json: "EDIT",
-  table_get: "EDIT",
-  table_update_cell: "EDIT",
-  table_insert_row: "EDIT",
-  table_delete_row: "EDIT",
-  insert_image: "EDIT",
-  replace_image: "EDIT",
-  insert_footnote: "EDIT",
-  drawio_get: "EDIT",
-  drawio_create: "EDIT",
-  drawio_update: "EDIT",
-  docmost_transform: "EDIT",
-  // PAGES
-  create_page: "PAGES",
-  rename_page: "PAGES",
-  move_page: "PAGES",
-  delete_page: "PAGES",
-  copy_page_content: "PAGES",
-  share_page: "PAGES",
-  unshare_page: "PAGES",
-  list_shares: "PAGES",
-  // COMMENTS
-  create_comment: "COMMENTS",
-  list_comments: "COMMENTS",
-  update_comment: "COMMENTS",
-  resolve_comment: "COMMENTS",
-  delete_comment: "COMMENTS",
-  check_new_comments: "COMMENTS",
-  // HISTORY
-  diff_page_versions: "HISTORY",
-  list_page_history: "HISTORY",
-  restore_page_version: "HISTORY",
-  export_page_markdown: "HISTORY",
-  import_page_markdown: "HISTORY",
-};
-
-/**
- * Inventory lines for the INLINE MCP-only tools — the ones registered directly
- * in index.ts (not via SHARED_TOOL_SPECS) because they diverge per transport or
- * exist only on this standalone surface. They carry no `catalogLine`, so their
- * one-line purpose is hand-written here. This is the ONLY hand-maintained tool
- * list left, and it is tiny; a new inline tool without an entry here is caught
- * by the completeness guard in `tool-inventory.test.mjs`.
- */
-export const INLINE_MCP_INVENTORY: ToolInventoryLine[] = [
-  {
-    name: "table_get",
-    purpose:
-      "read a table as a matrix of cell texts + per-cell paragraph ids.",
-  },
-  {
-    name: "search",
-    purpose:
-      "full-text search for pages and content across the whole workspace.",
-  },
-  {
-    name: "docmost_transform",
-    purpose:
-      "edit a page by running a sandboxed JS `(doc, ctx) => doc` transform, with a dryRun diff preview.",
-  },
-  {
-    name: "update_comment",
-    purpose: "update an existing comment's content (creator only).",
-  },
-  {
-    name: "delete_comment",
-    purpose: "delete a comment (creator or space admin only).",
-  },
-];
-
-/**
- * Derive the one-line purpose for a registry spec: prefer its hand-written
- * `catalogLine` (already a "name — purpose" line — we take the purpose after
- * the em dash), else fall back to the first sentence of its description.
- */
-function purposeForSpec(spec: SharedToolSpec): string {
-  const line = spec.catalogLine?.trim();
-  if (line) {
-    const dash = line.indexOf(" — ");
-    if (dash >= 0) return line.slice(dash + 3).trim();
-    return line;
-  }
-  const desc = (spec.description ?? "").replace(/\s+/g, " ").trim();
-  const firstSentence = desc.split(/(?<=[.!?])\s/)[0];
-  return firstSentence || desc || "(no description)";
-}
-
-/**
- * Build the flat list of every registered tool's inventory line: one per shared
- * registry spec (skipping `inAppOnly` specs, which are not registered on this
- * MCP host) PLUS every inline MCP-only tool. Pure and deterministic — the
- * registry drives it, so it can never drift from what index.ts registers.
- */
-export function buildToolInventoryLines(
-  specs: Record<string, SharedToolSpec> = SHARED_TOOL_SPECS,
-  inline: ToolInventoryLine[] = INLINE_MCP_INVENTORY,
-): ToolInventoryLine[] {
-  const lines: ToolInventoryLine[] = [];
-  for (const spec of Object.values(specs)) {
-    if (spec.inAppOnly) continue; // not registered on the MCP host
-    lines.push({ name: spec.mcpName, purpose: purposeForSpec(spec) });
-  }
-  for (const l of inline) lines.push({ ...l });
-  return lines;
-}
-
-/**
- * Render the generated `<tool_inventory>` block: every tool name + purpose,
- * grouped by family (families in FAMILY_ORDER; tools within a family sorted by
- * name for stable output; unmapped tools fall into OTHER). Pure.
- */
-export function buildToolInventory(
-  specs: Record<string, SharedToolSpec> = SHARED_TOOL_SPECS,
-  inline: ToolInventoryLine[] = INLINE_MCP_INVENTORY,
-): string {
-  const byFamily = new Map<Family, ToolInventoryLine[]>();
-  for (const family of FAMILY_ORDER) byFamily.set(family, []);
-  for (const line of buildToolInventoryLines(specs, inline)) {
-    const family = TOOL_FAMILY[line.name] ?? "OTHER";
-    byFamily.get(family)!.push(line);
-  }
-  const sections: string[] = [];
-  for (const family of FAMILY_ORDER) {
-    const items = byFamily.get(family)!;
-    if (items.length === 0) continue;
-    items.sort((a, b) => a.name.localeCompare(b.name));
-    for (const item of items) {
-      sections.push(`  ${family}  ${item.name} — ${item.purpose}`);
-    }
-  }
-  return ["<tool_inventory>", ...sections, "</tool_inventory>"].join("\n");
-}
-
-/**
- * The composed editing guide: the hand-written routing prose followed by the
- * generated, drift-proof tool inventory. Exported (and used by index.ts /
- * createDocmostMcpServer) as the MCP server's `instructions`.
- */
-export const SERVER_INSTRUCTIONS =
-  ROUTING_PROSE + "\n" + buildToolInventory();
@@ -14,107 +14,16 @@
 // some write tools, different limits, hybrid-RRF search, etc.) stay defined
 // per-layer and are NOT represented here.
 //
-// SERVER_INSTRUCTIONS note (issue #448): the intent-routing guide MCP clients
-// receive on initialize is now SPLIT — its tool INVENTORY is GENERATED from this
-// registry (mcpName + catalogLine) by server-instructions.ts, so adding /
-// renaming / removing a spec here updates the guide's inventory AUTOMATICALLY;
-// no prose edit is needed. Only an INLINE MCP-only tool (registerTool in
-// index.ts, not a spec here) needs a hand-written line in INLINE_MCP_INVENTORY —
-// enforced by test/unit/tool-inventory.test.mjs. The routing PROSE (the "when to
-// use what" hints) in server-instructions.ts stays manual, but it is no longer a
-// drift-guard for the tool set.
+// MAINTENANCE RULE: adding, renaming, or removing a spec here (or an inline
+// registerTool in index.ts) REQUIRES updating SERVER_INSTRUCTIONS in
+// packages/mcp/src/index.ts — the intent-routing guide MCP clients receive on
+// initialize. Enforced by test/unit/server-instructions.test.mjs.

 // Loose on purpose — see the comment above. The two zod majors expose different
 // static type surfaces, so typing this precisely would couple the registry to
 // one of them. Each builder uses only the common, stable subset of the API.
 type ZodLike = any;

-// The `node` normalizer shared by BOTH hosts (patch_node / insert_node /
-// update_page_json): the model sometimes serializes a ProseMirror node arg as a
-// JSON string, so we parse a string to an object (throwing a documented message
-// on invalid JSON) and pass an object through. It lives in the converter package
-// (#414) so it is the ONE copy both the MCP server and the in-app server import;
-// putting it in a shared execute here keeps that single normalization in one
-// place instead of hand-mirrored per host. Pure — safe across the zod boundary.
-import { parseNodeArg } from '@docmost/prosemirror-markdown';
-// Type-only import (erased at compile) of the real client so `DocmostClientLike`
-// is DERIVED from it (issue #446), not hand-mirrored. The loosest correct client
-// surface both hosts satisfy: the in-app host passes its own DERIVED
-// `DocmostClientLike` (a Pick of the same class) and the MCP host passes the real
-// `DocmostClient`, so both are structurally assignable to this shared alias.
-import type { DocmostClient } from './client.js';
-
-/**
- * The client surface a shared `execute` may call — the LOOSEST correct type both
- * hosts satisfy: a `Pick` of the real `DocmostClient` methods the executes below
- * use. DERIVED from the real class (issue #446) so a signature change to any
- * consumed method surfaces as a compile error in the execute bodies here, not a
- * silent runtime "wrong argument". Kept as a Pick (not the whole class) so the
- * standalone MCP host's full `DocmostClient` AND the in-app host's OWN narrower
- * `DocmostClientLike` (also a Pick of the same class, a superset of these methods)
- * are both structurally assignable to it. `import type` is fully erased, so
- * tool-specs.ts pulls in no runtime dependency on the client and still crosses the
- * zod-major boundary freely. When you add a client call to an execute below, add
- * its method name here too (a compile error will point you at it).
- */
-export type DocmostClientLike = Pick<
-  DocmostClient,
-  | 'getWorkspace'
-  | 'getSpaces'
-  | 'listShares'
-  | 'listPages'
-  | 'getPage'
-  | 'getPageJson'
-  | 'getOutline'
-  | 'getNode'
-  | 'searchInPage'
-  | 'listComments'
-  | 'checkNewComments'
-  | 'listPageHistory'
-  | 'diffPageVersions'
-  | 'exportPageMarkdown'
-  | 'createPage'
-  | 'renamePage'
-  | 'movePage'
-  | 'deletePage'
-  | 'editPageText'
-  | 'patchNode'
-  | 'insertNode'
-  | 'deleteNode'
-  | 'updatePageJson'
-  | 'tableInsertRow'
-  | 'tableDeleteRow'
-  | 'tableUpdateCell'
-  | 'copyPageContent'
-  | 'importPageMarkdown'
-  | 'sharePage'
-  | 'unsharePage'
-  | 'restorePageVersion'
-  | 'stashPage'
-  | 'insertFootnote'
-  | 'insertImage'
-  | 'replaceImage'
-  | 'drawioGet'
-  | 'drawioCreate'
-  | 'drawioUpdate'
-  | 'createComment'
-  | 'resolveComment'
->;
-
-/**
- * A shared tool `execute`: the single canonical mapping from validated schema
- * args to the client call. Plain JS — it crosses the zod-major boundary (v3 in
- * the MCP package, v4 on the server) freely, receiving the already-validated,
- * type-erased args from whichever host invoked it. It returns RAW data; the host
- * applies its own result envelope (the MCP transport wraps it as JSON text
- * content, the in-app AI-SDK host returns it as-is). Host-specific overrides
- * (`mcpExecute`/`inAppExecute`) return a value the host uses instead of wrapping.
- */
-export type SharedToolExecute = (
-  client: DocmostClientLike,
-  args: Record<string, unknown>,
-) => Promise<unknown>;
-
 export interface SharedToolSpec {
  /** snake_case tool name passed to McpServer.registerTool. */
  mcpName: string;
@@ -145,53 +54,8 @@ export interface SharedToolSpec {
   * in-app side uses z.object({})).
   */
  buildShape?: (z: ZodLike) => Record<string, unknown>;
-  /**
-   * Single canonical mapping from validated schema args to the client call,
-   * shared by BOTH hosts. Returns RAW data — the MCP host wraps it as JSON text
-   * content (jsonContent), the in-app host returns it as-is. Present on tools
-   * whose mapping AND raw result are identical across the two layers. When a host
-   * needs a genuinely different mapping or result shape, it supplies an override
-   * (below) and the host uses that INSTEAD of `execute`.
-   */
-  execute?: SharedToolExecute;
-  /**
-   * MCP-host override for a DELIBERATE per-layer difference (a guardrail, an
-   * omitted param, or a non-JSON result envelope like a resource_link / a bare
-   * success line). When present, the MCP host calls this and uses its return
-   * value VERBATIM (it is NOT re-wrapped in jsonContent), so this override owns
-   * the full MCP content envelope.
-   */
-  mcpExecute?: SharedToolExecute;
-  /**
-   * In-app-host override for a DELIBERATE per-layer difference (a projected
-   * result shape, a different guardrail message). When present, the in-app host
-   * calls this and returns its value as the tool result (no wrapping).
-   */
-  inAppExecute?: SharedToolExecute;
-  /** Registered only on the MCP host (skipped by the in-app registry loop). */
-  mcpOnly?: boolean;
-  /** Registered only on the in-app host (skipped by the MCP registry loop). */
-  inAppOnly?: boolean;
 }

-// --- Shared execute helpers -------------------------------------------------
-//
-// Each helper is the ONE canonical arg->client mapping for a tool (or a host
-// override where the two layers deliberately differ). They are attached to their
-// spec below. Kept as named functions (not inline) so the spec table stays
-// readable and each mapping is individually greppable/testable.
-//
-// The `args` are the host's already-validated, zod-erased input; we read the
-// same fields the tool's buildShape declares. Return RAW data unless the name is
-// an mcp*/inApp* override that owns the host's full result shape.
-
-/** Format a JSON payload as the MCP transport's text-content envelope. Mirrors
- *  the private `jsonContent` in index.ts so an mcpExecute override that must NOT
- *  be re-wrapped can still emit the standard envelope for the data part. */
-const mcpJson = (data: unknown) => ({
-  content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
-});
-
 export const SHARED_TOOL_SPECS = {
  // --- no-argument read tools ---

@@ -201,7 +65,6 @@ export const SHARED_TOOL_SPECS = {
    description: 'Fetch metadata about the current workspace (name, settings).',
    tier: 'core',
    catalogLine: 'getWorkspace — fetch current workspace metadata (name, settings).',
-    execute: (client) => client.getWorkspace(),
  },

  listSpaces: {
@@ -212,7 +75,6 @@ export const SHARED_TOOL_SPECS = {
      'spaces (id, name, slug, ...).',
    tier: 'core',
    catalogLine: 'listSpaces — list the spaces the user can access (id, name, slug).',
-    execute: (client) => client.getSpaces(),
  },

  listShares: {
@@ -222,7 +84,6 @@ export const SHARED_TOOL_SPECS = {
      'List all public shares in the workspace with page titles and public URLs.',
    tier: 'deferred',
    catalogLine: 'listShares — list all public shares in the workspace with their URLs.',
-    execute: (client) => client.listShares(),
  },

  // --- single-pageId read tools ---
@@ -241,7 +102,6 @@ export const SHARED_TOOL_SPECS = {
    buildShape: (z) => ({
      pageId: z.string().min(1),
    }),
-    execute: (client, { pageId }) => client.getPageJson(pageId as string),
  },

  getOutline: {
@@ -259,7 +119,6 @@ export const SHARED_TOOL_SPECS = {
    buildShape: (z) => ({
      pageId: z.string().min(1),
    }),
-    execute: (client, { pageId }) => client.getOutline(pageId as string),
  },

  // --- two-id read tool ---
@@ -280,8 +139,6 @@ export const SHARED_TOOL_SPECS = {
      pageId: z.string().min(1),
      nodeId: z.string().min(1),
    }),
-    execute: (client, { pageId, nodeId }) =>
-      client.getNode(pageId as string, nodeId as string),
  },

  // --- in-page occurrence search (client-side, over ProseMirror plain text) ---
@@ -339,12 +196,6 @@ export const SHARED_TOOL_SPECS = {
        .optional()
        .describe('Max matches to RETURN (default 50, max 200); total is always reported.'),
    }),
-    execute: (client, { pageId, query, regex, caseSensitive, limit }) =>
-      client.searchInPage(pageId as string, query as string, {
-        regex: regex as boolean | undefined,
-        caseSensitive: caseSensitive as boolean | undefined,
-        limit: limit as number | undefined,
-      }),
  },

  // --- node delete ---
@@ -361,8 +212,6 @@ export const SHARED_TOOL_SPECS = {
      pageId: z.string().min(1),
      nodeId: z.string().min(1),
    }),
-    execute: (client, { pageId, nodeId }) =>
-      client.deleteNode(pageId as string, nodeId as string),
  },

  // --- single-block structural write (patch / insert) ---
@@ -387,7 +236,10 @@ export const SHARED_TOOL_SPECS = {
      'heading {"type":"heading","attrs":{"level":2},"content":' +
      '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
      '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
-      'JSON object or a JSON string (both accepted). Cheaper and safer than ' +
+      'JSON object or a JSON string (both accepted). EVERY node, including ' +
+      'nested children, must carry a string `type` from the Docmost schema; ' +
+      'text leaves are {"type":"text","text":"..."} (a bare {"text":"..."} is ' +
+      'rejected up front). Cheaper and safer than ' +
      'replacing the whole document for one-block structural edits. Reversible: ' +
      'the previous version is kept in page history.',
    tier: 'deferred',
@@ -410,11 +262,6 @@ export const SHARED_TOOL_SPECS = {
            'JSON object or JSON string both accepted.',
        ),
    }),
-    // parseNodeArg normalizes a JSON-string node into an object (the model
-    // sometimes serializes it as a string) before the client's typeof-object
-    // guard rejects it — identical on both hosts.
-    execute: (client, { pageId, nodeId, node }) =>
-      client.patchNode(pageId as string, nodeId as string, parseNodeArg(node)),
  },

  insertNode: {
@@ -438,7 +285,10 @@ export const SHARED_TOOL_SPECS = {
      '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
      'heading {"type":"heading","attrs":{"level":2},"content":' +
      '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-      '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
+      '{"type":"text","text":"x","marks":[{"type":"bold"}]}. EVERY node, ' +
+      'including nested children, must carry a string `type` from the Docmost ' +
+      'schema; text leaves are {"type":"text","text":"..."} (a bare ' +
+      '{"text":"..."} is rejected up front). The node may be a ' +
      'JSON object or a JSON string (both accepted). Reversible via page history.',
    tier: 'deferred',
    catalogLine:
@@ -468,12 +318,6 @@ export const SHARED_TOOL_SPECS = {
            'are tolerated as a fallback; prefer plain text or anchorNodeId.',
        ),
    }),
-    execute: (client, { pageId, node, position, anchorNodeId, anchorText }) =>
-      client.insertNode(pageId as string, parseNodeArg(node), {
-        position: position as 'before' | 'after' | 'append',
-        anchorNodeId: anchorNodeId as string | undefined,
-        anchorText: anchorText as string | undefined,
-      }),
  },

  // --- share management ---
@@ -504,11 +348,6 @@ export const SHARED_TOOL_SPECS = {
        .optional()
        .describe('Allow public search engines to index it (default true).'),
    }),
-    // `searchIndexing ?? true` is a no-op default: the client method already
-    // defaults searchIndexing to true, so passing `undefined` (the in-app form)
-    // and `?? true` (the old MCP form) are byte-identical — one canonical mapping.
-    execute: (client, { pageId, searchIndexing }) =>
-      client.sharePage(pageId as string, (searchIndexing as boolean | undefined) ?? true),
  },

  unsharePage: {
@@ -520,7 +359,6 @@ export const SHARED_TOOL_SPECS = {
    buildShape: (z) => ({
      pageId: z.string().min(1).describe('ID of the page to unshare'),
    }),
-    execute: (client, { pageId }) => client.unsharePage(pageId as string),
  },

  // --- version history ---
@@ -549,12 +387,6 @@ export const SHARED_TOOL_SPECS = {
        .optional()
        .describe("historyId, or 'current'/omit for current content"),
    }),
-    execute: (client, { pageId, from, to }) =>
-      client.diffPageVersions(
-        pageId as string,
-        from as string | undefined,
-        to as string | undefined,
-      ),
  },

  listPageHistory: {
@@ -574,8 +406,6 @@ export const SHARED_TOOL_SPECS = {
        .optional()
        .describe('Pagination cursor from a previous nextCursor'),
    }),
-    execute: (client, { pageId, cursor }) =>
-      client.listPageHistory(pageId as string, cursor as string | undefined),
  },

  restorePageVersion: {
@@ -592,8 +422,6 @@ export const SHARED_TOOL_SPECS = {
    buildShape: (z) => ({
      historyId: z.string().min(1),
    }),
-    execute: (client, { historyId }) =>
-      client.restorePageVersion(historyId as string),
  },

  // --- markdown round-trip ---
@@ -615,8 +443,6 @@ export const SHARED_TOOL_SPECS = {
      pageId: z.string().min(1),
      markdown: z.string().min(1),
    }),
-    execute: (client, { pageId, markdown }) =>
-      client.importPageMarkdown(pageId as string, markdown as string),
  },

  // --- server-side content copy ---
@@ -639,8 +465,6 @@ export const SHARED_TOOL_SPECS = {
        .min(1)
        .describe('Page whose content is REPLACED (title/slug kept)'),
    }),
-    execute: (client, { sourcePageId, targetPageId }) =>
-      client.copyPageContent(sourcePageId as string, targetPageId as string),
  },

  // --- surgical text edit (folds in the documented drift-bug fix) ---
@@ -690,11 +514,6 @@ export const SHARED_TOOL_SPECS = {
        .min(1)
        .describe('List of find/replace operations, applied in order'),
    }),
-    execute: (client, { pageId, edits }) =>
-      client.editPageText(
-        pageId as string,
-        edits as Parameters<DocmostClientLike['editPageText']>[1],
-      ),
  },

  // --- hand a large page to an external consumer without bloating context ---
@@ -723,33 +542,6 @@ export const SHARED_TOOL_SPECS = {
    buildShape: (z) => ({
      pageId: z.string().min(1),
    }),
-    // In-app returns the full documented `{ uri, size, sha256, images }` object
-    // as-is (the canonical execute).
-    execute: (client, { pageId }) => client.stashPage(pageId as string),
-    // The MCP transport must deliver the body as a resource_link (so it never
-    // enters the model context) PLUS a structuredContent mirror of the documented
-    // shape (sha256 = the blob's ETag, mirror counts). Owns its full envelope, so
-    // it is NOT wrapped in jsonContent.
-    mcpExecute: async (client, { pageId }) => {
-      const result = await client.stashPage(pageId as string);
-      return {
-        content: [
-          {
-            type: 'resource_link' as const,
-            uri: result.uri,
-            name: 'page.json',
-            mimeType: 'application/json',
-            size: result.size,
-          },
-        ],
-        structuredContent: {
-          uri: result.uri,
-          sha256: result.sha256,
-          size: result.size,
-          images: result.images,
-        },
-      };
-    },
  },

  // --- page tools (unified from the per-layer inline definitions, #294) ---
@@ -776,20 +568,6 @@ export const SHARED_TOOL_SPECS = {
    buildShape: (z) => ({
      pageId: z.string().min(1).describe('The id (or slugId) of the page.'),
    }),
-    // MCP wraps the raw `{ data, success }` as JSON. The in-app host instead
-    // projects a token-efficient `{ title, markdown }` (its long-standing shape).
-    execute: (client, { pageId }) => client.getPage(pageId as string),
-    inAppExecute: async (client, { pageId }) => {
-      // getPage(pageId) -> { data: filterPage(page, markdown), success }.
-      const result = (await client.getPage(pageId as string)) as {
-        data?: { title?: string; content?: string };
-      };
-      const data = result?.data ?? {};
-      return {
-        title: data.title ?? '',
-        markdown: typeof data.content === 'string' ? data.content : '',
-      };
-    },
  },

  listPages: {
@@ -824,15 +602,6 @@ export const SHARED_TOOL_SPECS = {
            'Requires spaceId; ignores limit.',
        ),
    }),
-    // `limit ?? 50` / `tree ?? false` are no-op defaults: the client method
-    // already defaults limit=50, tree=false, so the old MCP explicit-default form
-    // and the in-app pass-through form are byte-identical — one canonical mapping.
-    execute: (client, { spaceId, limit, tree }) =>
-      client.listPages(
-        spaceId as string | undefined,
-        (limit as number | undefined) ?? 50,
-        (tree as boolean | undefined) ?? false,
-      ),
  },

  createPage: {
@@ -861,28 +630,6 @@ export const SHARED_TOOL_SPECS = {
        .optional()
        .describe('Optional parent page id to nest the new page under.'),
    }),
-    // MCP wraps the raw create response as JSON. In-app projects `{ id, title }`
-    // and defensively coerces a missing body to '' (the schema makes content a
-    // required string, so `?? ''` only guards an absent field — preserved).
-    execute: (client, { title, content, spaceId, parentPageId }) =>
-      client.createPage(
-        title as string,
-        content as string,
-        spaceId as string,
-        parentPageId as string | undefined,
-      ),
-    inAppExecute: async (client, { title, content, spaceId, parentPageId }) => {
-      // createPage(title, content, spaceId, parentPageId?) ->
-      // { data: filterPage(page, markdown), success }.
-      const result = (await client.createPage(
-        title as string,
-        (content as string | undefined) ?? '',
-        spaceId as string,
-        parentPageId as string | undefined,
-      )) as { data?: { id?: string; slugId?: string; title?: string } };
-      const data = result?.data ?? {};
-      return { id: data.id ?? data.slugId, title: data.title ?? (title as string) };
-    },
  },

  movePage: {
@@ -920,62 +667,6 @@ export const SHARED_TOOL_SPECS = {
            'append at the end.',
        ),
    }),
-    // The MCP host keeps its robustness guards (coerce 'null'/'' -> null, a cheap
-    // self-cycle guard, and a POSITIVE { success: true } confirmation) and its
-    // human-readable success envelope — owns its full result, so it is NOT
-    // wrapped in jsonContent.
-    mcpExecute: async (client, { pageId, parentPageId, position }) => {
-      const finalParentId =
-        parentPageId === '' || parentPageId === 'null'
-          ? null
-          : (parentPageId as string | null | undefined);
-
-      // Cheap cycle guard: a page cannot be moved directly under itself.
-      // (Deeper descendant-cycle detection is intentionally out of scope.)
-      if (finalParentId !== null && finalParentId === pageId) {
-        throw new Error('cannot move a page under itself');
-      }
-
-      const result = await client.movePage(
-        pageId as string,
-        finalParentId || null,
-        position as string | undefined,
-      );
-
-      // Require POSITIVE confirmation: the live /pages/move success shape is
-      // exactly { success: true, status: 200 }. An empty body, a 204, or any odd
-      // shape lacking success === true must NOT be reported as a successful move.
-      if (
-        !(
-          result &&
-          typeof result === 'object' &&
-          (result as { success?: unknown }).success === true
-        )
-      ) {
-        throw new Error(
-          `Failed to move page ${pageId}: ${JSON.stringify(result)}`,
-        );
-      }
-
-      return mcpJson({
-        message: `Successfully moved page ${pageId} to parent ${finalParentId || 'root'}`,
-        result,
-      });
-    },
-    // The in-app host has no guards; it forwards `parentPageId ?? null` + the
-    // optional position and projects `{ pageId, parentPageId, moved }`.
-    inAppExecute: async (client, { pageId, parentPageId, position }) => {
-      await client.movePage(
-        pageId as string,
-        (parentPageId as string | null | undefined) ?? null,
-        position as string | undefined,
-      );
-      return {
-        pageId,
-        parentPageId: (parentPageId as string | null | undefined) ?? null,
-        moved: true,
-      };
-    },
  },

  renamePage: {
@@ -990,13 +681,6 @@ export const SHARED_TOOL_SPECS = {
      pageId: z.string().min(1).describe('The id of the page to rename.'),
      title: z.string().min(1).describe('The new title.'),
    }),
-    // MCP wraps the raw rename response; in-app projects `{ pageId, title }`.
-    execute: (client, { pageId, title }) =>
-      client.renamePage(pageId as string, title as string),
-    inAppExecute: async (client, { pageId, title }) => {
-      await client.renamePage(pageId as string, title as string);
-      return { pageId, title };
-    },
  },

  deletePage: {
@@ -1013,23 +697,6 @@ export const SHARED_TOOL_SPECS = {
    buildShape: (z) => ({
      pageId: z.string().min(1).describe('The id of the page to move to trash.'),
    }),
-    // deletePage(pageId) hits POST /pages/delete with { pageId } only — the
-    // soft-delete (trash) path. GUARDRAIL: the schema exposes ONLY pageId, so no
-    // permanent/force-delete flag can reach the client on either host (asserted by
-    // ai-chat-tools.service.spec.ts). MCP emits a bare success line (owns its full
-    // envelope); in-app projects `{ pageId, trashed }`.
-    mcpExecute: async (client, { pageId }) => {
-      await client.deletePage(pageId as string);
-      return {
-        content: [
-          { type: 'text' as const, text: `Successfully deleted page ${pageId}` },
-        ],
-      };
-    },
-    inAppExecute: async (client, { pageId }) => {
-      await client.deletePage(pageId as string);
-      return { pageId, trashed: true };
-    },
  },

  updatePageJson: {
@@ -1044,7 +711,10 @@ export const SHARED_TOOL_SPECS = {
      '"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: ' +
+      'change). Supplying neither content nor title is an error. EVERY node, ' +
+      'including nested children, must carry a string `type` from the Docmost ' +
+      'schema; text leaves are {"type":"text","text":"..."} (a bare ' +
+      '{"text":"..."} is rejected up front). Reversible: ' +
      'the previous version is kept in page history.',
    tier: 'deferred',
    catalogLine:
@@ -1060,19 +730,6 @@ export const SHARED_TOOL_SPECS = {
        ),
      title: z.string().optional().describe('Optional new title'),
    }),
-    // Content normalization is identical on both hosts: only parse/validate the
-    // document when actually supplied; undefined/null passes straight through so
-    // the client performs a title-only (or no-op) update. A string is JSON.parsed
-    // (an empty string "" therefore throws), an object passes through unchanged.
-    execute: (client, { pageId, content, title }) => {
-      let doc: unknown;
-      if (content === undefined || content === null) {
-        doc = undefined;
-      } else {
-        doc = parseNodeArg(content, 'content was a string but not valid JSON');
-      }
-      return client.updatePageJson(pageId as string, doc, title as string | undefined);
-    },
  },

  exportPageMarkdown: {
@@ -1093,17 +750,6 @@ export const SHARED_TOOL_SPECS = {
    buildShape: (z) => ({
      pageId: z.string().min(1).describe('The id of the page to export.'),
    }),
-    // The markdown is a bare string. MCP returns it as a single text-content
-    // element (NOT jsonContent — that would JSON-quote the whole document);
-    // in-app projects `{ markdown }`.
-    mcpExecute: async (client, { pageId }) => {
-      const md = await client.exportPageMarkdown(pageId as string);
-      return { content: [{ type: 'text' as const, text: md }] };
-    },
-    inAppExecute: async (client, { pageId }) => {
-      const markdown = await client.exportPageMarkdown(pageId as string);
-      return { markdown };
-    },
  },

  // --- comment tools (unified from the per-layer inline definitions, #294) ---
@@ -1186,69 +832,6 @@ export const SHARED_TOOL_SPECS = {
            'refused.',
        ),
    }),
-    // Both hosts enforce the SAME guardrails (a top-level comment requires a
-    // selection; suggestedText is forbidden on a reply / without a selection) but
-    // with per-layer error wording (snake_case 'create_comment:' on the MCP
-    // surface, camelCase 'createComment' in-app) and different result shapes (MCP
-    // jsonContent, in-app projects `{ commentId, pageId }`). Preserved byte-for-
-    // byte via the two overrides.
-    mcpExecute: async (client, { pageId, content, selection, parentCommentId, suggestedText }) => {
-      if (!parentCommentId && (!selection || !(selection as string).trim())) {
-        throw new Error(
-          "create_comment: a 'selection' (exact text to anchor on) is required for a top-level comment; omit it only when replying via parentCommentId.",
-        );
-      }
-      if (suggestedText !== undefined) {
-        if (parentCommentId) {
-          throw new Error(
-            "create_comment: 'suggestedText' cannot be attached to a reply; it applies only to a top-level inline comment.",
-          );
-        }
-        if (!selection || !(selection as string).trim()) {
-          throw new Error(
-            "create_comment: 'suggestedText' requires a 'selection' to anchor and rewrite.",
-          );
-        }
-      }
-      const result = await client.createComment(
-        pageId as string,
-        content as string,
-        'inline',
-        selection as string | undefined,
-        parentCommentId as string | undefined,
-        suggestedText as string | undefined,
-      );
-      return mcpJson(result);
-    },
-    inAppExecute: async (client, { pageId, content, selection, parentCommentId, suggestedText }) => {
-      if (!parentCommentId && (!selection || !(selection as string).trim())) {
-        throw new Error(
-          "createComment requires a 'selection' (exact text to anchor on) for a new top-level comment.",
-        );
-      }
-      if (suggestedText !== undefined) {
-        if (parentCommentId) {
-          throw new Error(
-            "createComment: 'suggestedText' cannot be attached to a reply; it applies only to a top-level inline comment.",
-          );
-        }
-        if (!selection || !(selection as string).trim()) {
-          throw new Error(
-            "createComment: 'suggestedText' requires a 'selection' to anchor and rewrite.",
-          );
-        }
-      }
-      const result = (await client.createComment(
-        pageId as string,
-        content as string,
-        'inline',
-        selection as string | undefined,
-        parentCommentId as string | undefined,
-        suggestedText as string | undefined,
-      )) as { data?: { id?: string } };
-      const data = result?.data ?? {};
-      return { commentId: data.id, pageId };
-    },
  },

  listComments: {
@@ -1274,8 +857,6 @@ export const SHARED_TOOL_SPECS = {
        .optional()
        .describe('default only active threads; true — include resolved'),
    }),
-    execute: (client, { pageId, includeResolved }) =>
-      client.listComments(pageId as string, includeResolved as boolean | undefined),
  },

  resolveComment: {
@@ -1309,13 +890,6 @@ export const SHARED_TOOL_SPECS = {
          'true (default) marks the thread resolved/closed; false reopens it',
        ),
    }),
-    // MCP wraps the raw resolve response; in-app projects `{ commentId, resolved }`.
-    execute: (client, { commentId, resolved }) =>
-      client.resolveComment(commentId as string, resolved as boolean),
-    inAppExecute: async (client, { commentId, resolved }) => {
-      await client.resolveComment(commentId as string, resolved as boolean);
-      return { commentId, resolved };
-    },
  },

  checkNewComments: {
@@ -1351,30 +925,6 @@ export const SHARED_TOOL_SPECS = {
            'Only pages under this parent will be checked.',
        ),
    }),
-    // The in-app host has NO `since` guard (the canonical execute, raw). The MCP
-    // host additionally rejects an unparseable `since` up front — otherwise the
-    // NaN comparison silently treats every comment as "not new" and returns zero
-    // without signalling the bad input. This guard is a DELIBERATE per-layer
-    // difference (the in-app surface never had it), preserved via mcpExecute.
-    execute: (client, { spaceId, since, parentPageId }) =>
-      client.checkNewComments(
-        spaceId as string,
-        since as string,
-        parentPageId as string | undefined,
-      ),
-    mcpExecute: async (client, { spaceId, since, parentPageId }) => {
-      if (Number.isNaN(Date.parse(since as string))) {
-        throw new Error(
-          `Invalid 'since' timestamp: ${JSON.stringify(since)} — expected an ISO 8601 date (e.g. '2026-03-10T00:00:00Z')`,
-        );
-      }
-      const result = await client.checkNewComments(
-        spaceId as string,
-        since as string,
-        parentPageId as string | undefined,
-      );
-      return mcpJson(result);
-    },
  },

  // --- table tools (unified from the per-layer inline definitions, #294) ---
@@ -1421,13 +971,6 @@ export const SHARED_TOOL_SPECS = {
        .optional()
        .describe('0-based insert position (0 inserts before the header); omit to append.'),
    }),
-    execute: (client, { pageId, table, cells, index }) =>
-      client.tableInsertRow(
-        pageId as string,
-        table as string,
-        cells as string[],
-        index as number | undefined,
-      ),
  },

  tableDeleteRow: {
@@ -1449,8 +992,6 @@ export const SHARED_TOOL_SPECS = {
        .describe('"#<index>" from the page outline, or a block id in the table.'),
      index: z.number().int().describe('0-based row index to delete.'),
    }),
-    execute: (client, { pageId, table, index }) =>
-      client.tableDeleteRow(pageId as string, table as string, index as number),
  },

  tableUpdateCell: {
@@ -1474,14 +1015,6 @@ export const SHARED_TOOL_SPECS = {
      col: z.number().int().describe('0-based column index.'),
      text: z.string().describe('The new cell text.'),
    }),
-    execute: (client, { pageId, table, row, col, text }) =>
-      client.tableUpdateCell(
-        pageId as string,
-        table as string,
-        row as number,
-        col as number,
-        text as string,
-      ),
  },

  // --- footnote + image write tools (promoted from inline MCP-only, #410) ---
@@ -1526,8 +1059,6 @@ export const SHARED_TOOL_SPECS = {
        .min(1)
        .describe('The footnote content as markdown (becomes the definition).'),
    }),
-    execute: (client, { pageId, anchorText, text }) =>
-      client.insertFootnote(pageId as string, anchorText as string, text as string),
  },

  insertImage: {
@@ -1565,13 +1096,6 @@ export const SHARED_TOOL_SPECS = {
          'Insert the image right after the first top-level block whose text contains this string',
        ),
    }),
-    execute: (client, { pageId, imageUrl, align, alt, replaceText, afterText }) =>
-      client.insertImage(pageId as string, imageUrl as string, {
-        align: align as 'left' | 'center' | 'right' | undefined,
-        alt: alt as string | undefined,
-        replaceText: replaceText as string | undefined,
-        afterText: afterText as string | undefined,
-      }),
  },

  replaceImage: {
@@ -1603,11 +1127,6 @@ export const SHARED_TOOL_SPECS = {
      align: z.enum(['left', 'center', 'right']).optional(),
      alt: z.string().optional(),
    }),
-    execute: (client, { pageId, attachmentId, imageUrl, align, alt }) =>
-      client.replaceImage(pageId as string, attachmentId as string, imageUrl as string, {
-        align: align as 'left' | 'center' | 'right' | undefined,
-        alt: alt as string | undefined,
-      }),
  },

  // --- draw.io diagrams (issue #423, stage 1) ---
@@ -1637,12 +1156,6 @@ export const SHARED_TOOL_SPECS = {
        .optional()
        .describe('"xml" (default) for mxGraph XML, or "svg" for the raw .drawio.svg.'),
    }),
-    execute: (client, { pageId, node, format }) =>
-      client.drawioGet(
-        pageId as string,
-        node as string,
-        (format as 'xml' | 'svg' | undefined) ?? 'xml',
-      ),
  },

  drawioCreate: {
@@ -1689,18 +1202,6 @@ export const SHARED_TOOL_SPECS = {
        .describe('Anchor text fragment (for before/after).'),
      title: z.string().optional().describe('Optional diagram title.'),
    }),
-    // The flat schema fields are regrouped into the client's `where` object.
-    execute: (client, { pageId, xml, position, anchorNodeId, anchorText, title }) =>
-      client.drawioCreate(
-        pageId as string,
-        {
-          position: position as 'before' | 'after' | 'append',
-          anchorNodeId: anchorNodeId as string | undefined,
-          anchorText: anchorText as string | undefined,
-        },
-        xml as string,
-        title as string | undefined,
-      ),
  },

  drawioUpdate: {
@@ -1734,12 +1235,5 @@ export const SHARED_TOOL_SPECS = {
        .min(1)
        .describe('The meta.hash from the drawio_get this edit is based on.'),
    }),
-    execute: (client, { pageId, node, xml, baseHash }) =>
-      client.drawioUpdate(
-        pageId as string,
-        node as string,
-        xml as string,
-        baseHash as string,
-      ),
  },
 } satisfies Record<string, SharedToolSpec>;
@@ -0,0 +1,240 @@
+// Mock regression for the FAIL-FAST invalid-node validation (#409).
+//
+// A structural editor (patch_node / insert_node / update_page_json) given a doc
+// whose NESTED child has an absent/unknown `type` (the exact shape the Yjs
+// encoder rejects with `Unknown node type: undefined`) must throw a RICH,
+// path-anchored error BEFORE it ever opens a collab session or takes a page
+// lock. We prove the fail-fast by standing up a collab stack whose HTTP handler
+// records EVERY request: a correct fail-fast never even fetches the collab
+// token (which `getCollabTokenWithReauth`, called AFTER the validation, would
+// request), and never drives a document change on the Hocuspocus doc.
+//
+// The happy path (a well-formed doc) is exercised too: it must reach the collab
+// write and succeed, so the gate is not over-eager.
+//
+// findInvalidNode's per-shape summaries are unit-tested in the package
+// (test/find-invalid-node.test.ts); this exercises the END-TO-END wiring through
+// the real client methods.
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import http from "node:http";
+import { WebSocketServer } from "ws";
+import { Hocuspocus } from "@hocuspocus/server";
+import { DocmostClient } from "../../build/client.js";
+import { buildYDoc } from "../../build/lib/collaboration.js";
+
+// A minimal valid seed doc with a real block id, so the happy-path patch_node
+// finds its target.
+const SEED_ID = "seed-para-id";
+function seedDoc() {
+  return {
+    type: "doc",
+    content: [
+      {
+        type: "paragraph",
+        attrs: { id: SEED_ID },
+        content: [{ type: "text", text: "seed" }],
+      },
+    ],
+  };
+}
+
+// Stand up an HTTP server that authenticates + hands out a collab token AND
+// upgrades /collab to a Hocuspocus instance seeded with the doc. `state` records
+// whether the collab token was ever fetched (proving the write path was entered)
+// and whether the Hocuspocus doc ever changed.
+async function spawnCollabStack() {
+  const state = { changed: false, collabTokenFetched: false };
+
+  const hocuspocus = new Hocuspocus({
+    quiet: true,
+    async onLoadDocument() {
+      return buildYDoc(seedDoc());
+    },
+    async onChange() {
+      state.changed = true;
+    },
+  });
+
+  const wss = new WebSocketServer({ noServer: true });
+
+  const server = http.createServer((req, res) => {
+    let raw = "";
+    req.on("data", (c) => (raw += c));
+    req.on("end", () => {
+      if (req.url === "/api/auth/login") {
+        res.writeHead(200, {
+          "Content-Type": "application/json",
+          "Set-Cookie": "authToken=t; Path=/; HttpOnly",
+        });
+        res.end(JSON.stringify({ success: true }));
+        return;
+      }
+      if (req.url === "/api/auth/collab-token") {
+        state.collabTokenFetched = true;
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ data: { token: "collab-jwt" } }));
+        return;
+      }
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ message: "not found" }));
+    });
+  });
+
+  server.on("upgrade", (request, socket, head) => {
+    if (!request.url || !request.url.startsWith("/collab")) {
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(request, socket, head, (ws) => {
+      hocuspocus.handleConnection(ws, request);
+    });
+  });
+
+  const baseURL = await new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      resolve(`http://127.0.0.1:${port}/api`);
+    });
+  });
+
+  openStacks.push({ server, hocuspocus });
+  return { state, baseURL };
+}
+
+const openStacks = [];
+after(async () => {
+  await Promise.all(
+    openStacks.map(
+      ({ server, hocuspocus }) =>
+        new Promise((resolve) => {
+          server.close(() => {
+            Promise.resolve(hocuspocus.destroy?.()).finally(resolve);
+          });
+        }),
+    ),
+  );
+});
+
+const PAGE = "11111111-1111-4111-8111-111111111111";
+
+// A node whose NESTED text leaf is missing "type":"text" (dominant #409 shape).
+const nestedTypelessNode = () => ({
+  type: "paragraph",
+  content: [{ text: "oops", marks: [] }],
+});
+
+// A node with a NESTED unknown type NAME (typo).
+const nestedUnknownTypeNode = () => ({
+  type: "paragraph",
+  content: [{ type: "paragraf", content: [{ type: "text", text: "x" }] }],
+});
+
+test("patch_node fails fast on a nested typeless node — no collab connection", async () => {
+  const { state, baseURL } = await spawnCollabStack();
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+
+  await assert.rejects(
+    () => client.patchNode(PAGE, SEED_ID, nestedTypelessNode()),
+    (err) => {
+      assert.match(err.message, /patch_node: invalid node/);
+      assert.match(err.message, /missing "type"/);
+      assert.match(err.message, /content\[0\]/); // path-anchored
+      return true;
+    },
+  );
+
+  assert.equal(
+    state.collabTokenFetched,
+    false,
+    "must NOT fetch a collab token — validation runs before getCollabTokenWithReauth",
+  );
+  assert.equal(state.changed, false, "the collab doc must never be written");
+});
+
+test("insert_node fails fast on a nested UNKNOWN type — no collab connection", async () => {
+  const { state, baseURL } = await spawnCollabStack();
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+
+  await assert.rejects(
+    () =>
+      client.insertNode(PAGE, nestedUnknownTypeNode(), {
+        position: "append",
+      }),
+    (err) => {
+      assert.match(err.message, /insert_node: invalid node/);
+      assert.match(err.message, /unknown node type "paragraf"/);
+      return true;
+    },
+  );
+
+  assert.equal(state.collabTokenFetched, false);
+  assert.equal(state.changed, false);
+});
+
+test("update_page_json fails fast on a nested typeless node — no collab connection", async () => {
+  const { state, baseURL } = await spawnCollabStack();
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+
+  const badDoc = {
+    type: "doc",
+    content: [{ type: "paragraph", content: [{ text: "oops" }] }],
+  };
+
+  await assert.rejects(
+    () => client.updatePageJson(PAGE, badDoc),
+    (err) => {
+      // update_page_json runs validateDocStructure first (string-type check),
+      // which already rejects a typeless node — so the message may come from
+      // either guard, but the write must not happen.
+      assert.match(err.message, /type/i);
+      return true;
+    },
+  );
+
+  assert.equal(state.collabTokenFetched, false);
+  assert.equal(state.changed, false);
+});
+
+test("update_page_json fails fast on a nested UNKNOWN type name — rich #409 message", async () => {
+  const { state, baseURL } = await spawnCollabStack();
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+
+  // validateDocStructure passes (type is a string); assertValidNodeShape must
+  // catch the unknown schema name and produce the rich path-anchored message.
+  const badDoc = {
+    type: "doc",
+    content: [{ type: "paragraf", content: [{ type: "text", text: "x" }] }],
+  };
+
+  await assert.rejects(
+    () => client.updatePageJson(PAGE, badDoc),
+    (err) => {
+      assert.match(err.message, /update_page_json: invalid node/);
+      assert.match(err.message, /unknown node type "paragraf"/);
+      return true;
+    },
+  );
+
+  assert.equal(state.collabTokenFetched, false);
+  assert.equal(state.changed, false);
+});
+
+test("patch_node with a well-formed node proceeds to the collab write", async () => {
+  const { state, baseURL } = await spawnCollabStack();
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+
+  const result = await client.patchNode(PAGE, SEED_ID, {
+    type: "paragraph",
+    content: [{ type: "text", text: "replacement" }],
+  });
+
+  assert.equal(result.success, true);
+  assert.equal(result.replaced, 1);
+  assert.equal(
+    state.collabTokenFetched,
+    true,
+    "a valid node must reach the collab write path",
+  );
+  assert.equal(state.changed, true, "the collab doc must be written");
+});
@@ -0,0 +1,224 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+import { DocmostClient } from "../../build/index.js";
+
+// Drift guard for the THIRD hand-written layer of the AI tool set (issue #193,
+// layer 3): the in-app server hand-mirrors the DocmostClient method signatures
+// it consumes as the `DocmostClientLike` interface in
+// apps/server/src/core/ai-chat/tools/docmost-client.loader.ts ("Signatures here
+// mirror that file exactly"). That mirror lives across the ESM(mcp)/CJS(server)
+// boundary and the package ships NO .d.ts, so the server typecheck cannot verify
+// the names against the real class — a rename/removal in client.ts would surface
+// only as a runtime "x is not a function" inside an agent tool call.
+//
+// SCOPE: this guard checks the method-NAME set only, not signatures. It pins the
+// contract from the mcp side (ESM, where the real class is directly importable):
+// every method the embedding host depends on MUST exist as a function on a real
+// DocmostClient instance. If you rename/remove a client method, this fails here
+// AND you must update DocmostClientLike to match. It does NOT verify parameter or
+// return-type parity — signature drift between the hand-mirror and client.ts can
+// still ship silently; full signature/type parity is the deferred staged-plan
+// item below.
+//
+// Keep the HOST_CONTRACT_METHODS NAME list aligned with the method NAMES declared
+// in the server's DocmostClientLike interface (the in-app per-user tool adapter
+// only — it is a SUBSET of the DocmostClient surface — covers only what the in-app adapter
+// consumes; the standalone MCP transport (packages/mcp/src/index.ts) calls additional
+// client methods (deleteComment/updateComment) that this guard does NOT track — the
+// MCP transport's own typecheck covers those. insertImage/replaceImage/insertFootnote
+// were MCP-only but are now in-app-consumed too (#410), so they ARE tracked below. Full type-derivation
+// of DocmostClientLike from this class is deferred (see the staged plan in
+// docmost-client.loader.ts): the package emits no declarations and the real
+// (inferred, concrete) return types conflict with the host's loose
+// `Record<string,unknown>` + `as`-cast result handling.
+const HOST_CONTRACT_METHODS = [
+  // read
+  "search",
+  "getPage",
+  "getPageRaw",
+  "getWorkspace",
+  "getSpaces",
+  "listPages",
+  "listSidebarPages",
+  "getOutline",
+  "getPageJson",
+  "getNode",
+  "searchInPage",
+  "getTable",
+  "listComments",
+  "getComment",
+  "checkNewComments",
+  "listShares",
+  "listPageHistory",
+  "getPageHistory",
+  "diffPageVersions",
+  "exportPageMarkdown",
+  // write (page)
+  "createPage",
+  "updatePage",
+  "renamePage",
+  "movePage",
+  "deletePage",
+  "editPageText",
+  "patchNode",
+  "insertNode",
+  "deleteNode",
+  "updatePageJson",
+  "tableInsertRow",
+  "tableDeleteRow",
+  "tableUpdateCell",
+  "copyPageContent",
+  "importPageMarkdown",
+  "sharePage",
+  "unsharePage",
+  "restorePageVersion",
+  "transformPage",
+  "stashPage",
+  // write (image / footnote) — MCP-only until #410 promoted them to in-app tools
+  "insertImage",
+  "replaceImage",
+  "insertFootnote",
+  // draw.io diagrams (#423, stage 1) — read + create + optimistic-locked update
+  "drawioGet",
+  "drawioCreate",
+  "drawioUpdate",
+  // write (comment)
+  "createComment",
+  "resolveComment",
+];
+
+test("DocmostClient implements every method the in-app DocmostClientLike mirror declares", () => {
+  // The constructor is side-effect-free (no network/login on construction): it
+  // only stores config and creates an axios instance, so it is safe to build a
+  // throwaway instance here with a dummy token provider.
+  const client = new DocmostClient({
+    apiUrl: "http://127.0.0.1:1/api",
+    getToken: async () => "test-token",
+  });
+
+  const missing = HOST_CONTRACT_METHODS.filter(
+    (name) => typeof client[name] !== "function",
+  );
+
+  assert.deepEqual(
+    missing,
+    [],
+    `DocmostClient is missing host-contract method(s): ${missing.join(", ")}. ` +
+      `Update packages/mcp/src/client.ts and/or the server's DocmostClientLike ` +
+      `interface (apps/server/src/core/ai-chat/tools/docmost-client.loader.ts) ` +
+      `so the hand-mirrored method NAMES stay aligned (this guards names only, ` +
+      `not signatures).`,
+  );
+});
+
+test("HOST_CONTRACT_METHODS has no duplicates", () => {
+  assert.equal(
+    new Set(HOST_CONTRACT_METHODS).size,
+    HOST_CONTRACT_METHODS.length,
+  );
+});
+
+// Parse the method names declared in the server's `DocmostClientLike` interface
+// body. We read the .ts source as plain text (no TS compiler dep, and the file
+// lives in the CJS server tree across the ESM boundary): scan from the
+// `export interface DocmostClientLike {` line to its closing brace at column 0,
+// matching member-signature lines like `  methodName(`. Nested param-object
+// braces (`opts: { ... }`) are indented, so only the interface's own closing
+// `}` (column 0) ends the scan.
+function parseDocmostClientLikeMethods() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  // packages/mcp/test/unit -> repo root is four levels up.
+  const loaderPath = resolve(
+    here,
+    "../../../../apps/server/src/core/ai-chat/tools/docmost-client.loader.ts",
+  );
+  let source;
+  try {
+    source = readFileSync(loaderPath, "utf8");
+  } catch (err) {
+    if (err && err.code === "ENOENT") {
+      throw new Error(
+        `Expected monorepo layout; server tree at ${loaderPath} not found. ` +
+          `This drift-guard reads the server's DocmostClientLike interface via a ` +
+          `fixed relative path and must run from inside the monorepo checkout.`,
+      );
+    }
+    throw err;
+  }
+  const lines = source.split(/\r?\n/);
+
+  const startIdx = lines.findIndex((l) =>
+    /^export interface DocmostClientLike\s*\{/.test(l),
+  );
+  assert.notEqual(
+    startIdx,
+    -1,
+    `Could not find "export interface DocmostClientLike {" in ${loaderPath}. ` +
+      `If the interface was renamed/moved, update this drift-guard test.`,
+  );
+
+  const methods = [];
+  let closed = false;
+  // Track whether we are inside a `/* ... */` block comment. Inner lines of a
+  // block comment need NOT start with `*`, so a `name(` line inside one would be
+  // falsely parsed as an interface method without this. (`//` line comments can
+  // never match the method regex below since they start with `/`.)
+  let inBlockComment = false;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (inBlockComment) {
+      // Stay in the block until we see its closing `*/`.
+      if (line.includes("*/")) inBlockComment = false;
+      continue;
+    }
+    // Enter a block comment only when it opens without closing on the same line;
+    // a self-contained `/* ... */` on one line cannot precede a method name we
+    // care about (such lines start with `/`, so the method regex won't match).
+    if (line.includes("/*") && !line.includes("*/")) {
+      inBlockComment = true;
+      continue;
+    }
+    if (/^\}/.test(line)) {
+      closed = true;
+      break;
+    }
+    // Method-name match: a TS identifier (letters/digits/`_`/`$`, not starting
+    // with a digit) optionally followed by a generic clause (`method<T>(`), then
+    // the opening paren of the signature.
+    const m = /^\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*(?:<[^>]*>)?\(/.exec(line);
+    if (m) methods.push(m[1]);
+  }
+  assert.ok(
+    closed,
+    `Did not find the closing brace of DocmostClientLike in ${loaderPath}.`,
+  );
+  assert.ok(
+    methods.length > 0,
+    `Parsed zero methods from DocmostClientLike in ${loaderPath} — the parser ` +
+      `is likely out of date with the interface formatting.`,
+  );
+  return methods;
+}
+
+// The point of the guard is to protect the DocmostClientLike mirror <-> client.ts
+// link, but HOST_CONTRACT_METHODS is itself a HAND-COPY of that interface kept in
+// sync manually. The list<->interface link must be tested too: a method consumed
+// by the adapter and added to DocmostClientLike but forgotten here (or removed
+// from the interface but left here) would otherwise escape both the server
+// typecheck (pkg emits no .d.ts) and the first test above (name not in the list).
+// Assert the two agree BOTH ways.
+test("HOST_CONTRACT_METHODS exactly mirrors the server's DocmostClientLike interface", () => {
+  const interfaceMethods = parseDocmostClientLikeMethods();
+  assert.deepEqual(
+    [...HOST_CONTRACT_METHODS].sort(),
+    [...interfaceMethods].sort(),
+    `HOST_CONTRACT_METHODS has drifted from the DocmostClientLike interface in ` +
+      `apps/server/src/core/ai-chat/tools/docmost-client.loader.ts. Add/remove ` +
+      `method names in HOST_CONTRACT_METHODS so it lists EXACTLY the methods ` +
+      `declared in that interface (both directions are checked).`,
+  );
+});
@@ -1,101 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-
-import { computeRegistryStamp } from "../../scripts/gen-registry-stamp.mjs";
-import { REGISTRY_STAMP } from "../../build/index.js";
-
-// Guard tests for the build/src-skew stamp (issue #447). The codegen script
-// exports `computeRegistryStamp(sourceText)` — a sha256 over normalized source
-// text (CRLF->LF, single trailing newline stripped). The in-app loader
-// (apps/server/.../docmost-client.loader.ts) DUPLICATES that normalize+sha256 to
-// recompute the stamp from src and refuse a stale build. These tests pin the
-// algorithm's behaviour AND assert the built stamp matches the current src, so a
-// stale generated file OR a normalize divergence reddens.
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const TOOL_SPECS_PATH = join(__dirname, "..", "..", "src", "tool-specs.ts");
-
-test("computeRegistryStamp is deterministic: same input -> same hash", () => {
-  const input = "export const X = 1;\nexport const Y = 2;\n";
-  assert.equal(computeRegistryStamp(input), computeRegistryStamp(input));
-});
-
-test("computeRegistryStamp returns a 64-char lowercase hex sha256", () => {
-  const stamp = computeRegistryStamp("anything");
-  assert.match(stamp, /^[0-9a-f]{64}$/);
-});
-
-test("normalizes CRLF vs LF: the same content hashes equal", () => {
-  const lf = "line1\nline2\nline3";
-  const crlf = "line1\r\nline2\r\nline3";
-  assert.equal(computeRegistryStamp(crlf), computeRegistryStamp(lf));
-});
-
-test("normalizes a trailing newline: with/without a final \\n hashes equal", () => {
-  const noTrailing = "alpha\nbeta";
-  const trailing = "alpha\nbeta\n";
-  assert.equal(computeRegistryStamp(trailing), computeRegistryStamp(noTrailing));
-});
-
-test("a CRLF checkout WITH a trailing CRLF still hashes equal to bare LF", () => {
-  // A worst-case Windows checkout: CRLF line endings + a trailing CRLF. Both the
-  // \r\n->\n replace and the trailing-newline strip must apply for parity.
-  const bare = "alpha\nbeta";
-  const crlfTrailing = "alpha\r\nbeta\r\n";
-  assert.equal(
-    computeRegistryStamp(crlfTrailing),
-    computeRegistryStamp(bare),
-  );
-});
-
-test("a real content change hashes differently", () => {
-  const before = "export const description = 'search a page';\n";
-  const after = "export const description = 'search a PAGE';\n";
-  assert.notEqual(computeRegistryStamp(before), computeRegistryStamp(after));
-});
-
-// Only a SINGLE trailing newline is stripped — a second blank line is content and
-// must change the hash. This pins the exact `/\n$/` semantics the loader mirrors.
-test("only ONE trailing newline is stripped (two differ from one)", () => {
-  assert.notEqual(
-    computeRegistryStamp("x\n"),
-    computeRegistryStamp("x\n\n"),
-  );
-});
-
-// Cross-impl equality against a fixed, documented input. The SAME literal input
-// and expected hash are asserted in the server-side jest test
-// (docmost-client.loader.spec.ts). If either side's normalize+sha256 ever
-// diverges, one of the two tests reddens. Input exercises BOTH normalize steps.
-test("fixed-input hash matches the documented cross-impl value", () => {
-  const FIXED_INPUT = "line1\r\nline2\n";
-  const EXPECTED =
-    "683376e290829b482c2655745caffa7a1dccfa10afaa62dac2b42dd6c68d0f83";
-  assert.equal(computeRegistryStamp(FIXED_INPUT), EXPECTED);
-});
-
-// DESYNC GUARD (covers reviewer suggestion 2). Recompute the stamp from the
-// actual src/tool-specs.ts and assert it equals the REGISTRY_STAMP baked into the
-// freshly-built build/index.js. This reddens if the generated file is stale OR if
-// the codegen normalize ever diverges from what produced the built stamp.
-test("built REGISTRY_STAMP equals the stamp recomputed from src/tool-specs.ts", () => {
-  const source = readFileSync(TOOL_SPECS_PATH, "utf8");
-  assert.equal(computeRegistryStamp(source), REGISTRY_STAMP);
-});
-
-// Sanity: the fixed-input helper computes the SAME way the codegen does, proving
-// the EXPECTED constant above is not an arbitrary magic value but the documented
-// normalize+sha256 of FIXED_INPUT. Belt-and-braces so a bad EXPECTED can't hide a
-// real regression.
-test("the documented EXPECTED constant is the normalize+sha256 of FIXED_INPUT", () => {
-  const FIXED_INPUT = "line1\r\nline2\n";
-  const normalized = FIXED_INPUT.replace(/\r\n/g, "\n").replace(/\n$/, "");
-  const expected = createHash("sha256")
-    .update(normalized, "utf8")
-    .digest("hex");
-  assert.equal(computeRegistryStamp(FIXED_INPUT), expected);
-});
@@ -0,0 +1,82 @@
+// Guard: every tool the MCP server registers must be routed by intent in
+// SERVER_INSTRUCTIONS — the editing guide clients receive in the initialize
+// result. Without this, new tools silently rot out of the guide and agents
+// never learn to pick them (the guide once omitted 17 of 41 tools, including
+// get_outline, which pushed agents into fetching whole documents for block
+// ids). Tool names are extracted from the SOURCE (index.ts inline
+// registrations + tool-specs.ts shared specs) so a registration added either
+// way is caught; the guide text itself is imported from the build so the test
+// checks what actually ships.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { SERVER_INSTRUCTIONS } from "../../build/index.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SRC = join(HERE, "..", "..", "src");
+
+// Tools DELIBERATELY absent from the guide. Keep this list minimal and
+// justify every entry — the default is: every tool gets routed.
+const EXCEPTIONS = new Set([
+  // Trivial and self-explanatory; carries no routing decision.
+  "get_workspace",
+]);
+
+/**
+ * Extract every registered tool name from the source. Two registration
+ * mechanisms exist and both are covered:
+ *  - inline `server.registerTool("name", ...)` calls in index.ts;
+ *  - shared specs in tool-specs.ts (`mcpName: 'name'`), registered via
+ *    registerShared(SHARED_TOOL_SPECS.x, ...).
+ */
+function registeredToolNames() {
+  const indexSrc = readFileSync(join(SRC, "index.ts"), "utf8");
+  const specsSrc = readFileSync(join(SRC, "tool-specs.ts"), "utf8");
+  const names = new Set();
+  for (const m of indexSrc.matchAll(/registerTool\(\s*"([a-z0-9_]+)"/g)) {
+    names.add(m[1]);
+  }
+  for (const m of specsSrc.matchAll(/mcpName:\s*['"]([a-z0-9_]+)['"]/g)) {
+    names.add(m[1]);
+  }
+  return names;
+}
+
+test("every registered tool is mentioned in SERVER_INSTRUCTIONS", () => {
+  const names = registeredToolNames();
+  // Sanity: if extraction regressed (regex drift), fail loudly rather than
+  // vacuously passing on an empty set.
+  assert.ok(
+    names.size >= 40,
+    `sanity: expected to extract 40+ registered tools, got ${names.size} — ` +
+      "the extraction regexes in this test likely drifted from the source",
+  );
+  const missing = [...names]
+    .filter((n) => !EXCEPTIONS.has(n))
+    // \b<name>\b: `_` is a word char, so \bget_page\b does NOT match inside
+    // get_page_json — a tool can't hide behind a longer sibling's mention.
+    .filter((n) => !new RegExp(`\\b${n}\\b`).test(SERVER_INSTRUCTIONS))
+    .sort();
+  assert.deepEqual(
+    missing,
+    [],
+    `tools missing from SERVER_INSTRUCTIONS: ${missing.join(", ")} — ` +
+      "update the guide in packages/mcp/src/index.ts (see its MAINTENANCE " +
+      "RULE comment), or add a justified entry to EXCEPTIONS here",
+  );
+});
+
+test("EXCEPTIONS entries are real registered tools", () => {
+  // A stale exception (tool renamed/removed) must be cleaned up, otherwise
+  // the list quietly grows past its purpose.
+  const names = registeredToolNames();
+  for (const name of EXCEPTIONS) {
+    assert.ok(
+      names.has(name),
+      `EXCEPTIONS entry "${name}" is not a registered tool — remove it`,
+    );
+  }
+});
@@ -1,104 +0,0 @@
-// Guard: the GENERATED <tool_inventory> in SERVER_INSTRUCTIONS (issue #448)
-// names every tool the server registers. The inventory is BUILT from the
-// registry (SHARED_TOOL_SPECS' mcpName/catalogLine + INLINE_MCP_INVENTORY), so
-// the shared-registry tools can never drift by construction; this test's job is
-// to catch the ONE remaining manual list — INLINE_MCP_INVENTORY — falling out
-// of sync with the inline `server.registerTool(...)` calls in index.ts.
-//
-// It also asserts the composed guide keeps its routing prose (the hand-written
-// intent hints) and is a valid non-empty string — the structural guarantees the
-// old name-scraper test (server-instructions.test.mjs, now deleted) carried,
-// minus its now-redundant per-name prose scrape.
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-
-import {
-  SERVER_INSTRUCTIONS,
-  ROUTING_PROSE,
-  buildToolInventoryLines,
-} from "../../build/server-instructions.js";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const SRC = join(HERE, "..", "..", "src");
-
-/**
- * Every tool name the MCP server registers, scraped from the SOURCE:
- *  - inline `server.registerTool("name", ...)` calls in index.ts;
- *  - shared specs in tool-specs.ts (`mcpName: 'name'`).
- * Same two registration mechanisms the old guard covered.
- */
-function registeredToolNames() {
-  const indexSrc = readFileSync(join(SRC, "index.ts"), "utf8");
-  const specsSrc = readFileSync(join(SRC, "tool-specs.ts"), "utf8");
-  const names = new Set();
-  for (const m of indexSrc.matchAll(/registerTool\(\s*"([a-z0-9_]+)"/g)) {
-    names.add(m[1]);
-  }
-  for (const m of specsSrc.matchAll(/mcpName:\s*['"]([a-z0-9_]+)['"]/g)) {
-    names.add(m[1]);
-  }
-  return names;
-}
-
-test("the generated inventory names every registered tool", () => {
-  const registered = registeredToolNames();
-  // Sanity: if the scrape regressed (regex drift), fail loudly rather than
-  // vacuously passing on an empty set.
-  assert.ok(
-    registered.size >= 40,
-    `sanity: expected 40+ registered tools, got ${registered.size} — ` +
-      "the extraction regexes in this test likely drifted from the source",
-  );
-  const inventory = new Set(buildToolInventoryLines().map((l) => l.name));
-  const missing = [...registered].filter((n) => !inventory.has(n)).sort();
-  assert.deepEqual(
-    missing,
-    [],
-    `tools missing from the generated <tool_inventory>: ${missing.join(", ")} — ` +
-      "a SHARED spec is covered automatically; an INLINE MCP-only tool needs a " +
-      "line added to INLINE_MCP_INVENTORY in src/server-instructions.ts",
-  );
-});
-
-test("the inventory has no phantom tool (every line is a real registered tool)", () => {
-  const registered = registeredToolNames();
-  const phantom = buildToolInventoryLines()
-    .map((l) => l.name)
-    .filter((n) => !registered.has(n))
-    .sort();
-  assert.deepEqual(
-    phantom,
-    [],
-    `<tool_inventory> lists tools that are NOT registered: ${phantom.join(", ")}`,
-  );
-});
-
-test("every inventory line has a non-empty purpose", () => {
-  for (const line of buildToolInventoryLines()) {
-    assert.equal(typeof line.purpose, "string");
-    assert.ok(line.purpose.trim().length > 0, `${line.name}: empty purpose`);
-  }
-});
-
-test("SERVER_INSTRUCTIONS keeps the routing prose and the generated inventory", () => {
-  assert.equal(typeof SERVER_INSTRUCTIONS, "string");
-  assert.ok(SERVER_INSTRUCTIONS.length > 0, "SERVER_INSTRUCTIONS is empty");
-  // Routing prose is spliced in verbatim (the hand-written intent hints).
-  assert.ok(
-    SERVER_INSTRUCTIONS.startsWith(ROUTING_PROSE),
-    "the routing prose is not preserved at the head of the guide",
-  );
-  // The generated inventory block is present.
-  assert.match(SERVER_INSTRUCTIONS, /<tool_inventory>/);
-  assert.match(SERVER_INSTRUCTIONS, /<\/tool_inventory>/);
-  // The routing families are still present in the prose.
-  for (const family of ["READ:", "EDIT:", "PAGES:", "COMMENTS:", "HISTORY:"]) {
-    assert.ok(
-      SERVER_INSTRUCTIONS.includes(family),
-      `routing prose lost its ${family} section`,
-    );
-  }
-});
@@ -0,0 +1,82 @@
+// #409: unstorableYjsError diagnostics PRECEDENCE. The opaque Yjs encode failure
+// (`Unknown node type: undefined`) is a node-SHAPE problem, so the shared
+// findInvalidNode is consulted FIRST and yields a path-anchored node message;
+// only a shape-sound doc falls back to findUnstorableAttr (undefined/function/
+// etc. attr values). Exercised through `assertYjsEncodable`, which runs the same
+// encode + error-wrapping the live write path uses.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { assertYjsEncodable } from "../../build/lib/collaboration.js";
+import {
+  findInvalidNode,
+  findUnstorableAttr,
+} from "@docmost/prosemirror-markdown";
+
+const doc = (...content) => ({ type: "doc", content });
+
+test("a nested typeless node yields the rich node-shape message (not an attr hint)", () => {
+  const bad = doc({
+    type: "paragraph",
+    content: [{ text: "oops", marks: [] }], // missing "type":"text"
+  });
+  assert.throws(
+    () => assertYjsEncodable(bad),
+    (err) => {
+      assert.match(err.message, /Invalid node:/);
+      assert.match(err.message, /missing "type"/);
+      assert.match(err.message, /content\[0\]/);
+      // It must NOT fall through to the generic attribute sentence.
+      assert.doesNotMatch(err.message, /Offending attribute/);
+      assert.doesNotMatch(
+        err.message,
+        /attribute likely holds a value Yjs cannot store/,
+      );
+      return true;
+    },
+  );
+});
+
+test("PRECEDENCE: a genuine undefined-attr case is a node-SHAPE-clean case, so the attr fallback fires", () => {
+  // A doc whose node shapes are ALL valid but that carries a Yjs-unstorable
+  // undefined attribute. unstorableYjsError checks findInvalidNode FIRST (must
+  // miss here) and only then findUnstorableAttr (must hit) — this is exactly the
+  // division of labor that keeps a real attr problem from being mislabelled as a
+  // node-shape problem, and vice versa. We assert the two helpers directly (the
+  // wrapper is not exported) because sanitizeForYjs strips undefined attrs before
+  // the live encoder ever sees them, so this branch cannot be reached through
+  // assertYjsEncodable without also failing the clone.
+  const attrProblem = doc({
+    type: "paragraph",
+    attrs: { id: "p1", indent: undefined },
+    content: [{ type: "text", text: "hi" }],
+  });
+  // findInvalidNode: shape is clean -> null (so the wrapper does NOT emit
+  // "Invalid node").
+  assert.equal(findInvalidNode(attrProblem), null);
+  // findUnstorableAttr: pinpoints the undefined attr -> the fallback message.
+  assert.match(findUnstorableAttr(attrProblem) ?? "", /indent \(undefined\)/);
+});
+
+test("PRECEDENCE: a node-shape problem is caught by findInvalidNode even when an attr is also unstorable", () => {
+  // Both a shape problem (typeless nested leaf) AND an unstorable attr exist;
+  // findInvalidNode wins, so the model is pointed at the node shape (the real
+  // root cause of `Unknown node type: undefined`), not the attribute.
+  const both = doc({
+    type: "paragraph",
+    attrs: { id: "p1", indent: undefined },
+    content: [{ text: "oops" }],
+  });
+  const shape = findInvalidNode(both);
+  assert.notEqual(shape, null);
+  assert.match(shape.summary, /missing "type"/);
+});
+
+test("a fully valid document encodes without throwing", () => {
+  const good = doc({
+    type: "paragraph",
+    attrs: { id: "p1" },
+    content: [{ type: "text", text: "hi" }],
+  });
+  assert.doesNotThrow(() => assertYjsEncodable(good));
+});
@@ -5,8 +5,6 @@
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
-    "declaration": true,
-    "declarationMap": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
@@ -56,6 +56,7 @@ export {
  deleteNodeById,
  sanitizeForYjs,
  findUnstorableAttr,
+  findInvalidNode,
  insertNodeRelative,
  readTable,
  insertTableRow,
@@ -14,7 +14,9 @@
 * `content`, non-object nodes, and absent `attrs` are tolerated.
 */

+import { getSchema } from "@tiptap/core";
 import { stripInlineMarkdown } from "./text-normalize.js";
+import { docmostExtensions } from "./docmost-schema.js";

 /** Deep-clone a JSON-serializable value without mutating the original. */
 function clone<T>(value: T): T {
@@ -383,6 +385,119 @@ export function findUnstorableAttr(doc: any): string | null {
  return null;
 }

+/**
+ * The Docmost schema's known node and mark NAME sets, derived ONCE from the very
+ * same `docmostExtensions` the Yjs encode path builds its schema from
+ * (`getSchema(docmostExtensions)` — mirrored in mcp's `docmostSchema`). Deriving
+ * both from the same extension list guarantees `findInvalidNode`'s "known type"
+ * set matches exactly what `PMNode.fromJSON`/`toYdoc` will actually accept, so
+ * the walker never flags a node the encoder would have stored (or vice versa).
+ * Lazy + cached: the schema is only built on first use.
+ */
+let schemaNames: { nodes: Set<string>; marks: Set<string> } | null = null;
+function getSchemaNames(): { nodes: Set<string>; marks: Set<string> } {
+  if (schemaNames == null) {
+    const schema = getSchema(docmostExtensions);
+    schemaNames = {
+      nodes: new Set(Object.keys(schema.nodes)),
+      marks: new Set(Object.keys(schema.marks)),
+    };
+  }
+  return schemaNames;
+}
+
+/**
+ * Depth-first walk of the JSON `content` tree looking for the FIRST node whose
+ * SHAPE the Yjs encode path will reject with an opaque
+ * `Unknown node type: undefined` (issue #409). Returns `{ path, summary }` for
+ * the offending node, or `null` when every node (and every mark) is a known
+ * Docmost schema type.
+ *
+ * Two failure modes are detected, in order, per node:
+ *   1. `type` is missing or not a string — the dominant `undefined` case, e.g.
+ *      a text leaf written as `{"text":"foo"}` with no `"type":"text"`.
+ *   2. `type` is a string but NOT a known Docmost node name (a typo / unknown
+ *      block), OR one of the node's marks carries an unknown mark name.
+ *
+ * The returned `summary` is a model-actionable, path-anchored message such as:
+ *   `node.content[2].content[0]: missing "type" (keys: text, marks) — did you
+ *    mean {"type": "text", ...}?`
+ * or for an unknown type:
+ *   `node.content[1]: unknown node type "paragraf" — not in the Docmost schema`
+ *
+ * `path` is the same dotted JSON path used in the summary (e.g.
+ * `node.content[2].content[0]`) so callers can surface it separately. Null-safe:
+ * a non-object doc returns `null`.
+ *
+ * NOTE: This is a SHAPE check, not a full ProseMirror content-model validation
+ * (it does not verify that a paragraph may legally contain a table, etc.). Its
+ * job is to turn the specific "unknown/absent node type" Yjs crash into a clear,
+ * pre-write diagnostic; the schema's own `.check()` still catches deeper
+ * content-model violations at encode time.
+ */
+export function findInvalidNode(
+  doc: any,
+): { path: string; summary: string } | null {
+  if (!isObject(doc)) return null;
+  const { nodes, marks } = getSchemaNames();
+
+  // Build the "did you mean" hint for a typeless node from its own keys, so the
+  // model sees WHICH object is malformed and the canonical text-leaf fix.
+  const keyHint = (node: Record<string, any>): string => {
+    const keys = Object.keys(node);
+    const looksLikeText =
+      typeof node.text === "string" && node.type === undefined;
+    const suffix = looksLikeText
+      ? ` — did you mean {"type": "text", ...}?`
+      : ` — every node needs a string "type" from the Docmost schema`;
+    return `missing "type" (keys: ${keys.join(", ") || "none"})${suffix}`;
+  };
+
+  const walk = (
+    node: any,
+    path: string,
+  ): { path: string; summary: string } | null => {
+    if (!isObject(node)) return null;
+
+    // (1) missing / non-string type.
+    if (typeof node.type !== "string") {
+      return { path, summary: `${path}: ${keyHint(node)}` };
+    }
+    // (2) string type that is not a known Docmost node.
+    if (!nodes.has(node.type)) {
+      return {
+        path,
+        summary: `${path}: unknown node type "${node.type}" — not in the Docmost schema`,
+      };
+    }
+    // (2b) unknown mark on an otherwise-valid node.
+    if (Array.isArray(node.marks)) {
+      for (let i = 0; i < node.marks.length; i++) {
+        const mark = node.marks[i];
+        if (isObject(mark) && typeof mark.type === "string" && !marks.has(mark.type)) {
+          return {
+            path: `${path}.marks[${i}]`,
+            summary: `${path}.marks[${i}]: unknown mark type "${mark.type}" — not in the Docmost schema`,
+          };
+        }
+      }
+    }
+
+    if (Array.isArray(node.content)) {
+      for (let i = 0; i < node.content.length; i++) {
+        const hit = walk(node.content[i], `${path}.content[${i}]`);
+        if (hit != null) return hit;
+      }
+    }
+    return null;
+  };
+
+  // The root doc node is addressed as "node" (matching the mcp arg name); its
+  // children are node.content[i]. The root itself is checked too so a typeless
+  // root is reported rather than silently skipped.
+  return walk(doc, "node");
+}
+
 /**
 * Table structural node types and the container each must live directly inside.
 * Used by `insertNodeRelative` to splice rows/cells into the correct ancestor
@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'vitest';
+import { findInvalidNode } from '../src/lib/node-ops.js';
+
+// findInvalidNode (#409): a depth-first SHAPE gate that turns the encoder's
+// opaque `Unknown node type: undefined` into a path-anchored, pre-write
+// diagnostic. It flags the FIRST node whose `type` is absent/non-string or not
+// a known Docmost schema node, or that carries an unknown mark; returns null for
+// a well-formed doc.
+
+const doc = (...content: any[]) => ({ type: 'doc', content });
+const para = (...content: any[]) => ({
+  type: 'paragraph',
+  attrs: { id: 'p1' },
+  content,
+});
+const text = (value: string, marks?: any[]) => {
+  const node: any = { type: 'text', text: value };
+  if (marks) node.marks = marks;
+  return node;
+};
+
+describe('findInvalidNode', () => {
+  it('returns null for a fully valid document', () => {
+    const good = doc(
+      para(text('hello ', [{ type: 'bold' }]), text('world')),
+      {
+        type: 'heading',
+        attrs: { id: 'h1', level: 2 },
+        content: [text('Title')],
+      },
+    );
+    expect(findInvalidNode(good)).toBeNull();
+  });
+
+  it('flags a NESTED typeless text leaf with a path-precise summary', () => {
+    // A text leaf written as {"text":"foo"} with no "type":"text" — the dominant
+    // `Unknown node type: undefined` cause.
+    const bad = doc(
+      para(text('ok')),
+      para({ text: 'foo', marks: [] } as any),
+    );
+    const hit = findInvalidNode(bad);
+    expect(hit).not.toBeNull();
+    // Second paragraph (index 1), first child (index 0).
+    expect(hit!.path).toBe('node.content[1].content[0]');
+    expect(hit!.summary).toContain('node.content[1].content[0]');
+    expect(hit!.summary).toContain('missing "type"');
+    expect(hit!.summary).toContain('keys: text, marks');
+    expect(hit!.summary).toContain('did you mean {"type": "text", ...}');
+  });
+
+  it('flags a non-string type (e.g. numeric)', () => {
+    const bad = doc(para({ type: 123, content: [] } as any));
+    const hit = findInvalidNode(bad);
+    expect(hit).not.toBeNull();
+    expect(hit!.path).toBe('node.content[0].content[0]');
+    expect(hit!.summary).toContain('missing "type"');
+  });
+
+  it('flags an UNKNOWN node type name that is not in the Docmost schema', () => {
+    const bad = doc({
+      type: 'paragraf', // typo — not a real node
+      attrs: { id: 'x' },
+      content: [text('hi')],
+    });
+    const hit = findInvalidNode(bad);
+    expect(hit).not.toBeNull();
+    expect(hit!.path).toBe('node.content[0]');
+    expect(hit!.summary).toContain('unknown node type "paragraf"');
+    expect(hit!.summary).toContain('not in the Docmost schema');
+  });
+
+  it('flags an UNKNOWN mark type on an otherwise-valid node', () => {
+    const bad = doc(para(text('hi', [{ type: 'blink' }])));
+    const hit = findInvalidNode(bad);
+    expect(hit).not.toBeNull();
+    expect(hit!.path).toBe('node.content[0].content[0].marks[0]');
+    expect(hit!.summary).toContain('unknown mark type "blink"');
+  });
+
+  it('accepts every real Docmost node/mark type it is asked about', () => {
+    // Known node (callout) and known marks (italic, code) must NOT be flagged.
+    const good = doc({
+      type: 'callout',
+      attrs: { id: 'c1', type: 'info' },
+      content: [para(text('x', [{ type: 'italic' }, { type: 'code' }]))],
+    });
+    expect(findInvalidNode(good)).toBeNull();
+  });
+
+  it('reports the root itself when the root is typeless', () => {
+    const hit = findInvalidNode({ content: [] } as any);
+    expect(hit).not.toBeNull();
+    expect(hit!.path).toBe('node');
+  });
+
+  it('is null-safe for non-object input', () => {
+    expect(findInvalidNode(null)).toBeNull();
+    expect(findInvalidNode(undefined)).toBeNull();
+    expect(findInvalidNode('nope' as any)).toBeNull();
+  });
+});