fix(#370 ): thread trx into addPageWatchers (F7 self-deadlock) + restore contributors on commit-failure (F8) + assert the lock (F9) (review round 2)

The round-1 F3 fix (wrapping the processor's find+save in a locked tx) itself introduced two regressions: F7 [CRITICAL] addPageWatchers ran WITHOUT trx inside the tx holding FOR UPDATE on pages[pageId]. The watcher insert's FK check takes FOR KEY SHARE on the same row, but on a DIFFERENT pool connection — a true self-deadlock (our tx connection sits idle-in-transaction awaiting the JS await, the insert connection blocks on the lock). Now passes trx (addPageWatchers already accepts it and routes it through insertMany), so the FK lock is taken on the connection that already holds FOR UPDATE — no self-conflict. F8 [WARNING] popContributors is a destructive Redis SPOP; the inner catch only restores on a throw INSIDE the callback. A COMMIT failure throws OUTSIDE it, rolling the snapshot back while the pop is gone → a retry writes an unattributed version. Now tracks the popped set and restores it in an outer catch (idempotent SADD), leaving BullMQ to retry with attribution intact. F9 [WARNING] The spec asserted saveHistory args with a loosened objectContaining that stopped verifying trx, and never pinned withLock/trx on findById or the trx on addPageWatchers — which is exactly why F7 slipped. Restored the exact saveHistory(trx) assertion and added findById({withLock,trx}) + addPageWatchers trx assertions (the latter would have caught F7), plus a commit-failure test. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
fix(#370 ): ES2021-safe spec, source-specific idle ceiling, processor lock, tested index mapping (review round 1)
2026-07-06 04:10:06 +03:00 · 2026-07-06 04:10:06 +03:00 · 2026-07-06 04:10:06 +03:00 · 2026-07-06 03:55:02 +03:00 · 2026-07-06 01:28:31 +03:00 · 2026-07-06 00:36:31 +03:00
73 changed files with 5305 additions and 1458 deletions
@@ -151,6 +151,12 @@ jobs:
      - name: Build editor-ext
        run: pnpm --filter @docmost/editor-ext build

+      # @docmost/prosemirror-markdown is an ESM workspace package the server
+      # imports at runtime; its build/ is gitignored and test:e2e has no pretest
+      # hook, so build it before the e2e run (mirrors the test.yml job).
+      - name: Build prosemirror-markdown
+        run: pnpm --filter @docmost/prosemirror-markdown build
+
      - name: Run migrations
        run: pnpm --filter ./apps/server migration:latest

@@ -13,6 +13,49 @@ permissions:
  contents: read

 jobs:
+  # Guard against a long-lived branch adding a migration whose timestamped
+  # filename sorts BEFORE migrations already applied on the target branch (and
+  # thus in prod). The Kysely startup migrator rejects that as "corrupted
+  # migrations" and crash-loops the app on boot (incident #361). This gate fails
+  # the PR so the migration is renamed to a current timestamp before merge. Only
+  # runs for pull_request events (needs a base branch to diff against).
+  migration-order:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout (full history for the base-branch diff)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Added migrations must sort after the newest on the base branch
+        env:
+          TARGET_BRANCH: ${{ github.base_ref }}
+        run: |
+          set -euo pipefail
+          MIG_DIR="apps/server/src/database/migrations"
+          # checkout above already did fetch-depth:0 (full history). Fetch the base
+          # WITHOUT --depth (a shallow graft would truncate the base history and
+          # break the merge-base when the base has moved ahead of the PR merge —
+          # exactly the long-branch-vs-moving-base case this gate guards, #361).
+          git fetch --no-tags origin "$TARGET_BRANCH"
+          newest_on_target=$(git ls-tree -r --name-only "origin/${TARGET_BRANCH}" "$MIG_DIR" | sort | tail -1)
+          # NO `|| true`: a diff failure (e.g. an unresolved merge-base) must fail
+          # the job CLOSED — a gate whose job is to BLOCK must never pass on error.
+          # `set -e` above already aborts on a non-zero diff exit.
+          added=$(git diff --diff-filter=A --name-only "origin/${TARGET_BRANCH}...HEAD" -- "$MIG_DIR")
+          bad=0
+          for f in $added; do
+            if [[ "$f" < "$newest_on_target" || "$f" == "$newest_on_target" ]]; then
+              echo "::error::Migration $f sorts at or before the newest on ${TARGET_BRANCH} ($newest_on_target) — rename it with a CURRENT timestamp before merge (do not change its contents). See incident #361."
+              bad=1
+            fi
+          done
+          if [ "$bad" -eq 0 ]; then
+            echo "Migration order OK (added migrations all sort after $newest_on_target)."
+          fi
+          exit $bad
+
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 20
@@ -201,7 +201,7 @@ pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Four workspace packages:
 | `apps/client` | `client` | React 18 + Vite + Mantine 8 + TanStack Query + Jotai | SPA frontend |
 | `packages/editor-ext` | `@docmost/editor-ext` | Tiptap/ProseMirror | Shared Tiptap node/mark extensions, imported by both the client and the server |
 | `packages/mcp` | `@docmost/mcp` | MCP SDK, Tiptap, Yjs | Standalone MCP server, also bundled into the server at `/mcp`. Consumes the shared converter/schema from `@docmost/prosemirror-markdown` (#293) — it no longer carries its own vendored converter/schema copy |
-| `packages/prosemirror-markdown` | `@docmost/prosemirror-markdown` | Tiptap, marked, jsdom | The single, canonical ProseMirror↔Markdown converter + Docmost schema mirror (#293). Consumed by `mcp` and `git-sync`; there is exactly ONE copy of the converter now |
+| `packages/prosemirror-markdown` | `@docmost/prosemirror-markdown` | Tiptap, marked, jsdom | The single, canonical ProseMirror↔Markdown converter + Docmost schema mirror (#293). Consumed by `mcp`, `git-sync`, AND `apps/server` (server-side markdown import/export, #345); there is exactly ONE copy of the converter now |

 `build` targets are Nx-cached and dependency-ordered (`dependsOn: ["^build"]`), so `editor-ext` builds before the apps. `nx.json` sets `affected.defaultBase: main`.

@@ -214,6 +214,12 @@ Run from the repo root unless noted. The dev workflow needs **Postgres (with the
 > server, `APP_SECRET` mismatch between processes, a stale `editor-ext` white-
 > screening the client, LAN exposure. See **[docs/dev-stand.md](docs/dev-stand.md)**
 > for the step-by-step and the traps.
+>
+> **Testing the app against a stand** (browser E2E + out-of-band verification) has
+> its own non-obvious traps — the page has two ProseMirror editors (only the body is
+> collab-bound), a ~10s store debounce, and API-seeding the thing under test is a
+> silent no-test. See **[docs/how-to-test.md](docs/how-to-test.md)** before writing
+> UI tests.

 ```bash
 pnpm install                 # install all workspaces (uses pnpm patches; see package.json `pnpm.patchedDependencies`)
@@ -250,7 +256,10 @@ pnpm --filter server migration:codegen                   # regenerate src/databa
 ```
 Migration files live in `apps/server/src/database/migrations/` and are named `YYYYMMDDThhmmss-description.ts`. Fork-specific migrations only **add** tables (`page_embeddings`, `ai_chats`, `ai_chat_messages`, `ai_provider_credentials`, `ai_mcp_servers`, `page_template_references`) and columns (e.g. `pages.is_template`, a `NOT NULL DEFAULT false` boolean) — never drop/rewrite Docmost data.

-**Migration ordering — always check when merging branches/features.** Kysely runs migrations in **alphabetical (= timestamp) order** and refuses to start if a *new* migration sorts **before** one already applied to the DB (`corrupted migrations: ... must always have a name that comes alphabetically after the last executed migration`). When you merge a branch or land a feature, verify your migration's timestamp still sorts **after every migration that may already be applied on the target** (`/bin/ls -1 apps/server/src/database/migrations | sort | tail`). Branches developed in parallel routinely break this: a feature branch adds `…T130000-…`, `main` meanwhile ships and deploys `…T150000-…`, and after the merge the older-timestamped file is rejected at boot. **Fix = rename your migration to a timestamp after the latest one already in the target** (content unchanged — the filename is the ordering key), then rebuild so the compiled `dist/database/migrations/` picks up the new name.
+**Migration ordering — always check when merging branches/features.** Kysely runs migrations in **alphabetical (= timestamp) order**. A *new* migration that sorts **before** one already applied to the DB is a "back-dated" migration, which branches developed in parallel routinely produce: a feature branch adds `…T130000-…`, `develop` meanwhile ships and deploys `…T150000-…`, and after the merge the older-timestamped file has been skipped. Two layers guard this (both added for incident #361, where a back-dated migration crash-looped prod for ~11 min):
+
+- **CI gate (primary):** the `migration-order` job in `.github/workflows/test.yml` fails a PR whose added migration sorts at/before the newest on the base branch. **So the fix is to rename your migration to a timestamp after the latest one already in the target** (`/bin/ls -1 apps/server/src/database/migrations | sort | tail`; content unchanged — the filename is the ordering key), then rebuild so the compiled `dist/database/migrations/` picks up the new name.
+- **Runtime safety net:** both Migrators (`migration.service.ts` startup auto-migrate + `migrate.ts` CLI) set `allowUnorderedMigrations: true`, so the app does **not** refuse to start on an out-of-order migration — it applies the skipped older one instead of crash-looping. Kysely's `#ensureNoMissingMigrations` guard is still on (a *removed* applied migration is still an error). Because apply order can then differ from lexicographic across instances, migrations must stay **independent** (each creates its own objects) — the CI gate remains the primary line; this net only covers a gate bypass (manual push / hotfix branch).

 ## Architecture — the big picture

@@ -284,7 +293,7 @@ The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes
 ### Client structure
 Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirrors the server domains: `page`, `space`, `comment`, `ai-chat`, `editor`, …). Conventions:
 - **TanStack Query** for server state (one `queries/` file per feature), **Jotai** atoms for local/shared UI state, **Mantine 8** + CSS modules (`*.module.css`) + `postcss-preset-mantine` for UI.
- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, import/export) — editor schema changes often need to be made in `editor-ext`, not just the client. The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by both `mcp` and `git-sync` — do NOT reintroduce a per-package copy. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence.
+- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, schema, `canonicalizeFootnotes`) — editor schema changes often need to be made in `editor-ext`, not just the client. Server-side markdown import/export no longer lives in `editor-ext`: it goes through the canonical converter (#345, see below). The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by `mcp`, `git-sync`, and `apps/server` (#345) — do NOT reintroduce a per-package copy. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence.
 - API access goes through `apps/client/src/lib/api-client.ts` (axios). The `@` alias maps to `apps/client/src`.
 - Runtime config is injected at build time by `vite.config.ts` via `define` (`APP_URL`, `COLLAB_URL`, `APP_VERSION`, …) — these come from the root `.env`, not from `import.meta.env`.

@@ -294,7 +303,7 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 - **Errors must never be swallowed or shown as generic messages.** Every caught error MUST (1) be logged in full to the console/logger — error name, message, stack, `cause`, and (for HTTP/provider failures) the status code and response body — and (2) be surfaced to the user with a *specific, human-readable explanation of what actually went wrong*, never a bare generic string like "Something went wrong" / "Could not start recording" / "Transcription failed". Include the real reason (the underlying error/provider message) in the user-facing text. On the server, wrap third-party/provider failures with `describeProviderError` (or equivalent) and rethrow as a meaningful HTTP status + message — never let them collapse into an opaque 500. On the client, `console.error(<context>, err)` the raw error AND show the extracted reason (e.g. `err.response?.data?.message`, or the error `name: message`) in the notification.
 - The version string shown in the UI comes from `APP_VERSION` (CI/Docker) or `git describe --tags --always` (local), resolved in `vite.config.ts` — not from `package.json`.
 - Server TS config is permissive (`noImplicitAny: false`, `strictNullChecks: false`, `no-explicit-any` lint disabled). Follow the existing relaxed style rather than tightening types broadly.
- Dependency versions are heavily pinned via `pnpm.overrides` and `pnpm.patchedDependencies` (`scimmy`, `yjs`) in the root `package.json`. Don't bump pinned/patched deps casually; the patches and overrides exist for compatibility/security reasons.
+- 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`.
 - **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
@@ -12,6 +12,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ### Added

+- **Save intentional page versions.** Press `Cmd/Ctrl+S` (or use the page menu)
+  to save a named version of a page. The history panel now distinguishes
+  intentional versions (a "Saved" / "Agent version" badge) from automatic
+  snapshots, dims autosaves, and offers an "Only versions" filter. Automatic
+  snapshots switched from a fixed interval to a trailing idle-flush with a
+  max-wait ceiling, and a boundary snapshot is pinned whenever the editing source
+  changes (e.g. a person's edits followed by the AI agent). (#370)
+
 - **Place several images side by side in a row.** A new "Inline (side by
  side)" alignment mode in the image bubble menu renders consecutive inline
  images as a row that wraps onto the next line on narrow screens. The row is
@@ -169,6 +177,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ### Fixed

+- **The server no longer runs out of heap during long autonomous agent runs.** A
+  new pnpm patch on `ai@6.0.134` stops the SDK from building a cumulative
+  snapshot of the ENTIRE turn text on every streamed text-delta when no output
+  strategy was requested (our server never requests one). Unpatched, those
+  O(n²) `partialOutput` snapshots piled up in a never-consumed internal
+  `tee()` branch of the stream result — a ~20-step, ~28k-chunk agent run
+  retained ~1.7 GB and OOM'd the 2 GB JS heap. Streaming granularity is
+  unchanged; the patch must be re-created if `ai` is ever bumped. (#184)
 - **Internal links in exported Markdown no longer lose their visible text.** A
  link whose target page name had no file extension (e.g. a bare title) was
  collapsed to empty text during export, producing an unclickable, label-less
@@ -1373,6 +1373,39 @@
  "The role catalog is unavailable": "The role catalog is unavailable",
  "Please try again later.": "Please try again later.",
  "No bundles available": "No bundles available",
+  "Content": "Content",
+  "Content language of the roles": "Content language of the roles",
+  "{{count}} updates available in {{bundles}} bundles": "{{count}} updates available in {{bundles}} bundles",
+  "Update all ({{count}})": "Update all ({{count}})",
+  "Updating {{current}}/{{total}}…": "Updating {{current}}/{{total}}…",
+  "{{count}} roles are installed in another language. A different language installs separately and appears as new.": "{{count}} roles are installed in another language. A different language installs separately and appears as new.",
+  "{{count}} roles": "{{count}} roles",
+  "{{count}} new — none installed": "{{count}} new — none installed",
+  "All installed · up to date": "All installed · up to date",
+  "{{count}} updates · {{installed}} up to date": "{{count}} updates · {{installed}} up to date",
+  "{{count}} new": "{{count}} new",
+  "{{count}} installed": "{{count}} installed",
+  "{{count}} updates": "{{count}} updates",
+  "Install bundle": "Install bundle",
+  "Install {{count}} selected": "Install {{count}} selected",
+  "Install bundle ({{count}})": "Install bundle ({{count}})",
+  "{{selected}} of {{total}} selected": "{{selected}} of {{total}} selected",
+  "Select all": "Select all",
+  "Deselect all": "Deselect all",
+  "Skipped": "Skipped",
+  "v{{version}}": "v{{version}}",
+  "{{count}} roles installed": "{{count}} roles installed",
+  "{{count}} roles installed · {{renamed}} renamed": "{{count}} roles installed · {{renamed}} renamed",
+  "{{count}} roles updated": "{{count}} roles updated",
+  "Installed {{installed}} · {{skipped}} skipped": "Installed {{installed}} · {{skipped}} skipped",
+  "A role named \"{{name}}\" already exists in this workspace.": "A role named \"{{name}}\" already exists in this workspace.",
+  "\"{{name}}\" is already installed.": "\"{{name}}\" is already installed.",
+  "Rename & install": "Rename & install",
+  "Couldn’t load the catalog": "Couldn’t load the catalog",
+  "Check your connection and try again. Installed roles are not affected.": "Check your connection and try again. Installed roles are not affected.",
+  "Retry": "Retry",
+  "The catalog is empty": "The catalog is empty",
+  "No role bundles are published for this language yet. Try switching the content language.": "No role bundles are published for this language yet. Try switching the content language.",
  "Already up to date": "Already up to date",
  "Updated to the latest version": "Updated to the latest version",
  "This role is no longer in the catalog": "This role is no longer in the catalog",
@@ -1385,5 +1418,14 @@
  "The commented text changed since this suggestion was made; it was not applied.": "The commented text changed since this suggestion was made; it was not applied.",
  "Dismiss": "Dismiss",
  "Suggestion dismissed": "Suggestion dismissed",
-  "Failed to dismiss suggestion": "Failed to dismiss suggestion"
+  "Failed to dismiss suggestion": "Failed to dismiss suggestion",
+  "Save version": "Save version",
+  "Ctrl+S": "Ctrl+S",
+  "Version saved": "Version saved",
+  "Already saved as the latest version": "Already saved as the latest version",
+  "Agent version": "Agent version",
+  "Boundary": "Boundary",
+  "Autosave": "Autosave",
+  "Only versions": "Only versions",
+  "No saved versions yet.": "No saved versions yet."
 }
@@ -1235,6 +1235,39 @@
  "The role catalog is unavailable": "Каталог ролей недоступен",
  "Please try again later.": "Попробуйте позже.",
  "No bundles available": "Наборы недоступны",
+  "Content": "Язык контента",
+  "Content language of the roles": "Язык контента ролей",
+  "{{count}} updates available in {{bundles}} bundles": "Доступно обновлений: {{count}} в наборах: {{bundles}}",
+  "Update all ({{count}})": "Обновить все ({{count}})",
+  "Updating {{current}}/{{total}}…": "Обновление {{current}}/{{total}}…",
+  "{{count}} roles are installed in another language. A different language installs separately and appears as new.": "Ролей установлено на другом языке: {{count}}. Другой язык устанавливается отдельно и отображается как новый.",
+  "{{count}} roles": "ролей: {{count}}",
+  "{{count}} new — none installed": "новых: {{count}} — ничего не установлено",
+  "All installed · up to date": "Все установлены · актуальны",
+  "{{count}} updates · {{installed}} up to date": "обновлений: {{count}} · актуальны: {{installed}}",
+  "{{count}} new": "новых: {{count}}",
+  "{{count}} installed": "установлено: {{count}}",
+  "{{count}} updates": "обновлений: {{count}}",
+  "Install bundle": "Установить набор",
+  "Install {{count}} selected": "Установить выбранные ({{count}})",
+  "Install bundle ({{count}})": "Установить набор ({{count}})",
+  "{{selected}} of {{total}} selected": "выбрано {{selected}} из {{total}}",
+  "Select all": "Выбрать все",
+  "Deselect all": "Снять выбор",
+  "Skipped": "Пропущено",
+  "v{{version}}": "v{{version}}",
+  "{{count}} roles installed": "Установлено ролей: {{count}}",
+  "{{count}} roles installed · {{renamed}} renamed": "Установлено ролей: {{count}} · переименовано: {{renamed}}",
+  "{{count}} roles updated": "Обновлено ролей: {{count}}",
+  "Installed {{installed}} · {{skipped}} skipped": "Установлено: {{installed}} · пропущено: {{skipped}}",
+  "A role named \"{{name}}\" already exists in this workspace.": "Роль с именем «{{name}}» уже существует в этом рабочем пространстве.",
+  "\"{{name}}\" is already installed.": "«{{name}}» уже установлена.",
+  "Rename & install": "Переименовать и установить",
+  "Couldn’t load the catalog": "Не удалось загрузить каталог",
+  "Check your connection and try again. Installed roles are not affected.": "Проверьте подключение и попробуйте снова. Установленные роли не затронуты.",
+  "Retry": "Повторить",
+  "The catalog is empty": "Каталог пуст",
+  "No role bundles are published for this language yet. Try switching the content language.": "Для этого языка ещё не опубликовано ни одного набора ролей. Попробуйте сменить язык контента.",
  "No roles configured": "Роли не настроены",
  "Already up to date": "Уже актуальна",
  "Updated to the latest version": "Обновлено до последней версии",
@@ -1248,5 +1281,14 @@
  "The commented text changed since this suggestion was made; it was not applied.": "Прокомментированный текст изменился после создания предложения; оно не было применено.",
  "Dismiss": "Не применять",
  "Suggestion dismissed": "Предложение отклонено",
-  "Failed to dismiss suggestion": "Не удалось отклонить предложение"
+  "Failed to dismiss suggestion": "Не удалось отклонить предложение",
+  "Save version": "Сохранить версию",
+  "Ctrl+S": "Ctrl+S",
+  "Version saved": "Версия сохранена",
+  "Already saved as the latest version": "Уже сохранено как последняя версия",
+  "Agent version": "Версия агента",
+  "Boundary": "Граница",
+  "Autosave": "Автосейв",
+  "Only versions": "Только версии",
+  "No saved versions yet.": "Пока нет сохранённых версий."
 }
@@ -1,6 +1,7 @@
 import {
  useInfiniteQuery,
  useMutation,
+  useQueries,
  useQuery,
  useQueryClient,
 } from "@tanstack/react-query";
@@ -307,6 +308,29 @@ export function useAiRoleCatalogBundleQuery(
  });
 }

+/**
+ * Eagerly open EVERY listed bundle's content in parallel for one language. The
+ * redesigned catalog shows each bundle's status summary in its COLLAPSED header,
+ * which needs every role's install state up front — so contents can no longer be
+ * lazy-loaded on expand. The catalog is small, so a fan-out of `useQueries` (one
+ * cached read per bundle, sharing the same cache keys as
+ * `useAiRoleCatalogBundleQuery`) is cheap. Gated by `enabled` (modal open + a
+ * resolved language) so nothing fetches while the modal is closed.
+ */
+export function useAiRoleCatalogBundlesQueries(
+  bundleIds: string[],
+  language: string,
+  enabled: boolean,
+) {
+  return useQueries({
+    queries: bundleIds.map((bundleId) => ({
+      queryKey: AI_ROLE_CATALOG_BUNDLE_RQ_KEY(bundleId, language),
+      queryFn: () => getAiRoleCatalogBundle(bundleId, language),
+      enabled: enabled && !!language,
+    })),
+  });
+}
+
 export function useImportAiRolesFromCatalogMutation() {
  const queryClient = useQueryClient();
  const { t } = useTranslation();
@@ -77,7 +77,14 @@ describe("useImportAiRolesFromCatalogMutation — success notifications", () =>
  });

  it("errors:[] -> only the summary notification (counts interpolated)", async () => {
-    await runMutation({ created: 3, renamed: 1, skipped: 2, errors: [] });
+    await runMutation({
+      created: 3,
+      renamed: 1,
+      skipped: 2,
+      errors: [],
+      createdRoles: [],
+      skippedRoles: [],
+    });
    expect(notificationsShowMock).toHaveBeenCalledTimes(1);
    expect(notificationsShowMock).toHaveBeenCalledWith({
      message: "Imported 3, renamed 1, skipped 2",
@@ -93,6 +100,8 @@ describe("useImportAiRolesFromCatalogMutation — success notifications", () =>
        { slug: "a", message: "name taken" },
        { slug: "b", message: "name taken" },
      ],
+      createdRoles: [{ slug: "ok", name: "Ok" }],
+      skippedRoles: [],
    });
    expect(notificationsShowMock).toHaveBeenCalledTimes(2);
    expect(notificationsShowMock).toHaveBeenNthCalledWith(1, {
@@ -108,12 +108,25 @@ export interface IAiRoleImportPayload {
  conflict: "skip" | "rename";
 }

-/** Import result counts (mirrors `importFromCatalog()`). */
+/**
+ * Import result (mirrors `importFromCatalog()`). The counters (`created`,
+ * `skipped`, `renamed`) drive the summary notification; the per-role lists
+ * (`createdRoles`, `skippedRoles`) drive the redesigned catalog modal's inline
+ * result plaque — which roles were installed (and any rename) and which were
+ * skipped and why (so the plaque can name the conflicting role and offer
+ * "Rename & install").
+ */
 export interface IAiRoleImportResult {
  created: number;
  skipped: number;
  renamed: number;
  errors: { slug: string; message: string }[];
+  createdRoles: { slug: string; name: string; renamedTo?: string }[];
+  skippedRoles: {
+    slug: string;
+    name: string;
+    reason: "name-conflict" | "already-installed";
+  }[];
 }

 /**
@@ -0,0 +1,234 @@
+import { describe, it, expect } from "vitest";
+import {
+  bundleCounts,
+  bundlePhase,
+  installedLangForRole,
+  mapBundleRolesToView,
+  mapCatalogRoleToView,
+  nameConflictSlugs,
+  partialOffersRename,
+  type CatalogViewRole,
+} from "./catalog-bundle-model.ts";
+import type {
+  IAiRole,
+  IAiRoleCatalogRole,
+} from "@/features/ai-chat/types/ai-chat.types.ts";
+
+function installedRole(
+  source: { slug: string; language: string; version: number },
+  overrides: Partial<IAiRole> = {},
+): IAiRole {
+  return {
+    id: `role-${source.slug}-${source.language}`,
+    name: source.slug,
+    emoji: null,
+    description: null,
+    enabled: true,
+    autoStart: true,
+    launchMessage: null,
+    source,
+    ...overrides,
+  };
+}
+
+function catalogRole(
+  overrides: Partial<IAiRoleCatalogRole> = {},
+): IAiRoleCatalogRole {
+  return {
+    slug: "writer",
+    emoji: "✍️",
+    name: "Writer",
+    description: "Drafts copy.",
+    instructions: "be a writer",
+    autoStart: true,
+    launchMessage: null,
+    version: 3,
+    ...overrides,
+  };
+}
+
+// Build a minimal view role for bundlePhase tests.
+function viewRole(status: CatalogViewRole["status"]): CatalogViewRole {
+  return { slug: `s-${status}`, name: status, description: "", version: 1, status };
+}
+
+describe("bundlePhase", () => {
+  it("empty bundle -> empty", () => {
+    expect(bundlePhase([])).toBe("empty");
+  });
+
+  it("all importable, none installed -> allNew", () => {
+    expect(bundlePhase([viewRole("import"), viewRole("import")])).toBe(
+      "allNew",
+    );
+  });
+
+  it("nothing to import or update -> allInstalled", () => {
+    expect(bundlePhase([viewRole("installed"), viewRole("installed")])).toBe(
+      "allInstalled",
+    );
+  });
+
+  it("updates present, nothing to import -> updates", () => {
+    expect(bundlePhase([viewRole("update"), viewRole("installed")])).toBe(
+      "updates",
+    );
+  });
+
+  it("import + installed (no updates) -> mixed", () => {
+    expect(bundlePhase([viewRole("import"), viewRole("installed")])).toBe(
+      "mixed",
+    );
+  });
+
+  it("import + update -> mixed", () => {
+    expect(bundlePhase([viewRole("import"), viewRole("update")])).toBe("mixed");
+  });
+
+  it("a skipped role with nothing installed -> mixed (NOT allInstalled)", () => {
+    // F1: a bundle whose only non-installed role was skipped has 0 installed for
+    // it, so the collapsed 'All installed · up to date' header would contradict
+    // the open 'Installed 0 · 1 skipped' plaque. It must be mixed until resolved.
+    expect(bundlePhase([viewRole("skipped")])).toBe("mixed");
+  });
+
+  it("installed + a skipped role -> mixed (partial success is not allInstalled)", () => {
+    expect(bundlePhase([viewRole("installed"), viewRole("skipped")])).toBe(
+      "mixed",
+    );
+  });
+});
+
+describe("bundleCounts", () => {
+  it("tallies each status once", () => {
+    expect(
+      bundleCounts([
+        viewRole("import"),
+        viewRole("import"),
+        viewRole("installed"),
+        viewRole("update"),
+        viewRole("skipped"),
+      ]),
+    ).toEqual({ importable: 2, installed: 1, update: 1, skipped: 1 });
+  });
+});
+
+describe("nameConflictSlugs / partialOffersRename (reason -> action)", () => {
+  it("only name-conflict skips become the transient overlay / offer rename", () => {
+    const skipped = [
+      { slug: "writer", name: "Writer", reason: "name-conflict" as const },
+      { slug: "editor", name: "Editor", reason: "already-installed" as const },
+    ];
+    expect(nameConflictSlugs(skipped)).toEqual(["writer"]);
+    expect(partialOffersRename(skipped)).toBe(true);
+  });
+
+  it("an already-installed-only skip is informational: no overlay, no rename", () => {
+    const skipped = [
+      { slug: "editor", name: "Editor", reason: "already-installed" as const },
+    ];
+    expect(nameConflictSlugs(skipped)).toEqual([]);
+    expect(partialOffersRename(skipped)).toBe(false);
+  });
+});
+
+describe("installedLangForRole", () => {
+  it("returns the other language when the same slug is installed elsewhere", () => {
+    const roles = [installedRole({ slug: "writer", language: "ru", version: 2 })];
+    expect(installedLangForRole("writer", roles, "en")).toBe("ru");
+  });
+
+  it("returns undefined when the same slug is installed in the SAME language", () => {
+    const roles = [installedRole({ slug: "writer", language: "en", version: 2 })];
+    expect(installedLangForRole("writer", roles, "en")).toBeUndefined();
+  });
+
+  it("returns undefined when no install of the slug exists", () => {
+    expect(installedLangForRole("writer", [], "en")).toBeUndefined();
+  });
+
+  it("ignores manually-created roles (no source)", () => {
+    const roles = [
+      installedRole({ slug: "writer", language: "ru", version: 2 }, {
+        source: null,
+      }),
+    ];
+    expect(installedLangForRole("writer", roles, "en")).toBeUndefined();
+  });
+});
+
+describe("mapCatalogRoleToView", () => {
+  it("no install -> import status, catalog version, emoji preserved", () => {
+    const view = mapCatalogRoleToView(catalogRole(), [], "en");
+    expect(view).toMatchObject({
+      slug: "writer",
+      emoji: "✍️",
+      name: "Writer",
+      description: "Drafts copy.",
+      status: "import",
+      version: 3,
+    });
+    expect(view.installedRoleId).toBeUndefined();
+    expect(view.installedLang).toBeUndefined();
+  });
+
+  it("import with the slug installed in another language -> installedLang set", () => {
+    const roles = [installedRole({ slug: "writer", language: "ru", version: 9 })];
+    const view = mapCatalogRoleToView(catalogRole(), roles, "en");
+    expect(view.status).toBe("import");
+    expect(view.installedLang).toBe("ru");
+  });
+
+  it("installed (up to date) -> installed status, catalog version, installedRoleId", () => {
+    const installed = installedRole({
+      slug: "writer",
+      language: "en",
+      version: 3,
+    });
+    const view = mapCatalogRoleToView(catalogRole(), [installed], "en");
+    expect(view).toMatchObject({
+      status: "installed",
+      version: 3,
+      installedRoleId: installed.id,
+    });
+  });
+
+  it("update -> version=from, newVersion=to, installedRoleId", () => {
+    const installed = installedRole({
+      slug: "writer",
+      language: "en",
+      version: 1,
+    });
+    const view = mapCatalogRoleToView(catalogRole(), [installed], "en");
+    expect(view).toMatchObject({
+      status: "update",
+      version: 1,
+      newVersion: 3,
+      installedRoleId: installed.id,
+    });
+  });
+
+  it("missing emoji -> emoji undefined; null description -> empty string", () => {
+    const view = mapCatalogRoleToView(
+      catalogRole({ emoji: null, description: null }),
+      [],
+      "en",
+    );
+    expect(view.emoji).toBeUndefined();
+    expect(view.description).toBe("");
+  });
+});
+
+describe("mapBundleRolesToView", () => {
+  it("maps a bundle's roles preserving order", () => {
+    const roles = [
+      catalogRole({ slug: "a", name: "A", version: 1 }),
+      catalogRole({ slug: "b", name: "B", version: 1 }),
+    ];
+    const installed = [installedRole({ slug: "a", language: "en", version: 1 })];
+    const view = mapBundleRolesToView(roles, installed, "en");
+    expect(view.map((r) => r.slug)).toEqual(["a", "b"]);
+    expect(view[0].status).toBe("installed");
+    expect(view[1].status).toBe("import");
+  });
+});
@@ -0,0 +1,206 @@
+import type {
+  IAiRole,
+  IAiRoleCatalogRole,
+} from "@/features/ai-chat/types/ai-chat.types.ts";
+import { catalogRoleInstallState } from "@/features/ai-chat/utils/catalog-role-install-state.ts";
+
+/**
+ * The redesigned catalog modal renders bundles as cards with a summary status
+ * (readable without expanding) and a single primary action. The per-role and
+ * per-bundle view model that drives that UI is derived here as PURE functions so
+ * the mapping, the "installed in another language" hint, and the bundle-phase
+ * computation are unit-testable without mounting the component (mirrors the
+ * `catalogRoleInstallState` precedent).
+ */
+
+/**
+ * A role's status in the catalog view model.
+ *  - `import`    — not installed in the current content language.
+ *  - `installed` — installed and up to date.
+ *  - `update`    — installed, but the catalog ships a newer version.
+ *  - `skipped`   — TRANSIENT client-only status set after a conflicted import
+ *                  (a name collision under `conflict:'skip'`); never from the
+ *                  backend.
+ */
+export type RoleStatus = "import" | "installed" | "update" | "skipped";
+
+/** A catalog role mapped into the modal's view model. */
+export interface CatalogViewRole {
+  // Slug is the stable identity within a bundle; used as the row key and as the
+  // `slugs[]` payload for import.
+  slug: string;
+  // Optional in the catalog — the row reserves space and renders nothing when
+  // absent.
+  emoji?: string;
+  name: string;
+  description: string;
+  // For `installed`/`import`: the catalog version. For `update`: the installed
+  // (from) version, with `newVersion` holding the catalog (to) version.
+  version: number;
+  newVersion?: number;
+  status: RoleStatus;
+  // The language a same-slug role is installed under, when it differs from the
+  // current content language (drives the Р5 hint). Only set for `import` roles.
+  installedLang?: string;
+  // The workspace role id, present for `installed`/`update` — needed to call the
+  // update-from-catalog mutation.
+  installedRoleId?: string;
+}
+
+/**
+ * The summary phase of a bundle, derived from its roles' statuses. Determines
+ * the collapsed-header summary and the bundle's single primary action.
+ *  - `empty`        — the bundle has no roles.
+ *  - `allNew`       — everything is importable, nothing installed.
+ *  - `allInstalled` — everything installed & up to date; nothing else pending.
+ *  - `updates`      — updates available and nothing left to import.
+ *  - `mixed`        — any other combination.
+ */
+export type BundlePhase =
+  | "empty"
+  | "allNew"
+  | "allInstalled"
+  | "updates"
+  | "mixed";
+
+/** Per-status tallies for a bundle's roles (the single source of truth). */
+export interface BundleCounts {
+  importable: number;
+  installed: number;
+  update: number;
+  skipped: number;
+}
+
+/**
+ * Count a bundle's roles by status ONCE. Both `bundlePhase` and the panel derive
+ * from this, so the tally logic lives in exactly one place (no rescans / drift).
+ */
+export function bundleCounts(roles: CatalogViewRole[]): BundleCounts {
+  const counts: BundleCounts = {
+    importable: 0,
+    installed: 0,
+    update: 0,
+    skipped: 0,
+  };
+  for (const r of roles) {
+    if (r.status === "import") counts.importable += 1;
+    else if (r.status === "installed") counts.installed += 1;
+    else if (r.status === "update") counts.update += 1;
+    else if (r.status === "skipped") counts.skipped += 1;
+  }
+  return counts;
+}
+
+export function bundlePhase(roles: CatalogViewRole[]): BundlePhase {
+  if (roles.length === 0) return "empty";
+  const { importable, installed, update, skipped } = bundleCounts(roles);
+  // A `skipped` role is a pending post-import conflict (0 installed for it), so a
+  // bundle that has ANY skipped role is NOT "all installed & up to date" — that
+  // would make the collapsed green "up to date" header contradict the open
+  // panel's "Installed 0 · 1 skipped" plaque. It is `mixed` until resolved.
+  if (importable === 0 && update === 0 && skipped === 0) return "allInstalled";
+  if (update > 0 && importable === 0 && skipped === 0) return "updates";
+  if (importable > 0 && installed === 0 && update === 0 && skipped === 0)
+    return "allNew";
+  return "mixed";
+}
+
+/**
+ * The subset of a skip result that should be shown as a TRANSIENT `skipped`
+ * overlay in the bundle (so the row offers a re-import path). Only NAME-CONFLICT
+ * skips qualify: an `already-installed` skip (a concurrent-import race) has
+ * nothing to act on — re-importing the same slug would just skip again — so it
+ * must NOT be overlaid (else the row shows a misleading "Rename & install" that
+ * self-heals into a false "installed"). Pure so both reason branches are tested.
+ */
+export function nameConflictSlugs(
+  skipped: { slug: string; reason: "name-conflict" | "already-installed" }[],
+): string[] {
+  return skipped
+    .filter((s) => s.reason === "name-conflict")
+    .map((s) => s.slug);
+}
+
+/**
+ * Whether a partial-import result should offer the "Rename & install" action:
+ * only when at least one skip is a name conflict (renameable). An
+ * `already-installed`-only partial is informational.
+ */
+export function partialOffersRename(
+  skipped: { reason: "name-conflict" | "already-installed" }[],
+): boolean {
+  return skipped.some((s) => s.reason === "name-conflict");
+}
+
+/**
+ * For a role NOT installed in the current `language`, find a workspace role with
+ * the same catalog `slug` installed under a DIFFERENT language, and return that
+ * language. Drives the "installed in another language" hint (Р5): a different
+ * language of the same slug is a separate install and appears as `import`.
+ */
+export function installedLangForRole(
+  slug: string,
+  workspaceRoles: IAiRole[],
+  language: string,
+): string | undefined {
+  const other = workspaceRoles.find(
+    (r) =>
+      r.source?.slug === slug &&
+      !!r.source?.language &&
+      r.source.language !== language,
+  );
+  return other?.source?.language;
+}
+
+/**
+ * Map one catalog role to the view model, computing its install status against
+ * the workspace roles (via `catalogRoleInstallState`) and, for importable roles,
+ * the other-language hint.
+ */
+export function mapCatalogRoleToView(
+  role: IAiRoleCatalogRole,
+  workspaceRoles: IAiRole[],
+  language: string,
+): CatalogViewRole {
+  const state = catalogRoleInstallState(role, workspaceRoles, language);
+  const base = {
+    slug: role.slug,
+    emoji: role.emoji ?? undefined,
+    name: role.name,
+    description: role.description ?? "",
+  };
+  if (state.state === "update") {
+    return {
+      ...base,
+      status: "update",
+      version: state.fromVersion,
+      newVersion: state.toVersion,
+      installedRoleId: state.installed.id,
+    };
+  }
+  if (state.state === "installed") {
+    return {
+      ...base,
+      status: "installed",
+      version: role.version,
+      installedRoleId: state.installed.id,
+    };
+  }
+  return {
+    ...base,
+    status: "import",
+    version: role.version,
+    installedLang: installedLangForRole(role.slug, workspaceRoles, language),
+  };
+}
+
+/**
+ * Map a whole bundle's catalog roles to the view model, preserving order.
+ */
+export function mapBundleRolesToView(
+  roles: IAiRoleCatalogRole[],
+  workspaceRoles: IAiRole[],
+  language: string,
+): CatalogViewRole[] {
+  return roles.map((r) => mapCatalogRoleToView(r, workspaceRoles, language));
+}
@@ -1,10 +1,19 @@
 import { atom } from "jotai";
 import { Editor } from "@tiptap/core";
+import type { HocuspocusProvider } from "@hocuspocus/provider";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import type { DictationUnavailableReason } from "@/features/dictation/dictation-status";

 export const pageEditorAtom = atom<Editor | null>(null);

+// #370 — the active page's collab provider, published by the page editor so the
+// header menu can emit the "save-version" stateless signal (Cmd+S / button).
+// Null when the page is read-only / collab isn't connected. A typed initial
+// value (rather than an explicit generic) keeps jotai's overload resolution on
+// the writable PrimitiveAtom branch.
+const initialCollabProvider: HocuspocusProvider | null = null;
+export const collabProviderAtom = atom(initialCollabProvider);
+
 export const titleEditorAtom = atom<Editor | null>(null);

 export const readOnlyEditorAtom = atom<Editor | null>(null);
@@ -24,6 +24,7 @@ import {
  GitmostListPagesResult,
  GitmostListSpacesResult,
  gitmostDecodePayloadToFile,
+  gitmostInsertTranscriptIntoEditor,
  gitmostUploadFileToEditor,
 } from "@/features/editor/gitmost/gitmost-recording.ts";

@@ -281,6 +282,18 @@ export default function GitmostGlobalBridge() {
            pageId: page.id,
          };
        }
+
+        // Best-effort: append the transcript (heading + one paragraph per line)
+        // below the just-inserted audio node. The audio insert already
+        // succeeded, so a transcript failure must NOT turn this into an error —
+        // wrap it and, on any throw, log and still return ok. A missing/empty/
+        // non-string transcript is a no-op inside the helper (audio only).
+        try {
+          gitmostInsertTranscriptIntoEditor(editor, payload?.transcript);
+        } catch (err) {
+          console.error("[gitmost] transcript insert failed", err);
+        }
+
        return { ok: true, pageId: page.id };
      } catch (err: any) {
        console.error("[gitmost] createPageWithRecording failed", err);
@@ -0,0 +1,150 @@
+import { describe, it, expect } from "vitest";
+import { Editor } from "@tiptap/core";
+import { Document } from "@tiptap/extension-document";
+import { Paragraph } from "@tiptap/extension-paragraph";
+import { Text } from "@tiptap/extension-text";
+import { Heading } from "@tiptap/extension-heading";
+import { Bold } from "@tiptap/extension-bold";
+import { Italic } from "@tiptap/extension-italic";
+import { Link } from "@tiptap/extension-link";
+import { gitmostInsertTranscriptIntoEditor } from "./gitmost-recording.ts";
+
+const ZWSP = ""; // U+200B, the helper's block-trigger neutralizer
+
+/**
+ * #377 — the web-side bridge must append the native host's transcript below the
+ * recording. These exercise the pure insert helper through a REAL Tiptap editor
+ * (Document/Paragraph/Text/Heading + Bold/Italic/Link marks so an HTML-parsing
+ * regression would be caught), asserting the resulting document rather than
+ * mocking the editor: transcript present -> "Transcript" heading + one paragraph
+ * per non-empty line; content is inserted as LITERAL TEXT (no HTML/markdown
+ * parsing); col-0 markdown block triggers are neutralized so git-sync keeps them
+ * paragraphs; absent/empty/non-string -> no-op.
+ */
+describe("gitmostInsertTranscriptIntoEditor", () => {
+  const makeEditor = () =>
+    new Editor({
+      // Bold/Italic/Link are registered specifically so that IF the helper ever
+      // regressed to inserting an HTML/markdown string (instead of a text node),
+      // TipTap would parse `<b>`/`*..*`/`[..](..)` into marks and the literal-
+      // text assertions below would fail.
+      extensions: [Document, Paragraph, Text, Heading, Bold, Italic, Link],
+      // Start from a single empty paragraph (a fresh page's baseline). The
+      // helper appends at the end of the doc, i.e. below existing content.
+      content: { type: "doc", content: [{ type: "paragraph" }] },
+    });
+
+  it("inserts a Transcript heading + one paragraph per non-empty line, verbatim", () => {
+    const editor = makeEditor();
+
+    const inserted = gitmostInsertTranscriptIntoEditor(
+      editor,
+      "You: hello there\nSpeaker 1: hi\n\nYou: bye",
+    );
+
+    expect(inserted).toBe(true);
+
+    const nodes = (editor.getJSON().content ?? []) as any[];
+    // A level-2 "Transcript" heading is present.
+    const heading = nodes.find((n) => n.type === "heading");
+    expect(heading?.attrs?.level).toBe(2);
+    expect(heading?.content?.[0]?.text).toBe("Transcript");
+
+    // Every non-empty transcript line becomes a paragraph, in order, verbatim;
+    // the blank line between them is dropped.
+    const texts = nodes
+      .filter((n) => n.type === "paragraph")
+      .map((n) => n.content?.[0]?.text)
+      .filter((t) => typeof t === "string");
+    expect(texts).toEqual(["You: hello there", "Speaker 1: hi", "You: bye"]);
+
+    editor.destroy();
+  });
+
+  it("inserts HTML + markdown metacharacters as LITERAL text (no injection / no mark parsing)", () => {
+    const editor = makeEditor();
+    const line =
+      "You: <b>bold</b> <script>alert(1)</script> and *stars* and [link](x)";
+
+    const inserted = gitmostInsertTranscriptIntoEditor(editor, line);
+    expect(inserted).toBe(true);
+
+    const paras = (editor.getJSON().content ?? []).filter(
+      (n: any) => n.type === "paragraph",
+    ) as any[];
+    // The transcript line is exactly ONE paragraph holding a SINGLE text node
+    // whose text is the verbatim string — not split into bold/link/other nodes,
+    // not carrying any marks, not raw HTML. This FAILS if the helper switched to
+    // insertContent(htmlString): TipTap would then parse <b>/[link](x)/*stars*.
+    const content = paras[paras.length - 1].content;
+    expect(content).toHaveLength(1);
+    expect(content[0].type).toBe("text");
+    expect(content[0].marks ?? []).toEqual([]);
+    expect(content[0].text).toBe(line);
+    // And no bold/italic/link mark exists anywhere in the document.
+    const html = editor.getHTML();
+    expect(html).not.toMatch(/<(strong|b|em|i|a)\b/);
+    // The angle brackets survived as escaped entities (literal text), not a live
+    // <script>/<b> element.
+    expect(html).not.toMatch(/<script/i);
+
+    editor.destroy();
+  });
+
+  it("neutralizes col-0 markdown block triggers with a leading ZWSP (git-sync safety)", () => {
+    const editor = makeEditor();
+    // Trigger lines (some with a leaked indent) + a normal prefixed line.
+    const inserted = gitmostInsertTranscriptIntoEditor(
+      editor,
+      [
+        "- dash",
+        "  > quote", // leading indent must be trimmed then neutralized
+        "# hash",
+        "1. one",
+        "> [!info] note",
+        "```js",
+        "---", // solid thematic break -> horizontalRule (text-losing) if unneutralized
+        "***",
+        "___",
+        "You: normal line",
+      ].join("\n"),
+    );
+    expect(inserted).toBe(true);
+
+    const texts = (editor.getJSON().content ?? [])
+      .filter((n: any) => n.type === "paragraph")
+      .map((n: any) => n.content?.[0]?.text)
+      .filter((t: any) => typeof t === "string") as string[];
+
+    // Every block-trigger line is prefixed with the invisible ZWSP (indent
+    // trimmed first); the normal `You:` line is left byte-exact.
+    expect(texts).toEqual([
+      ZWSP + "- dash",
+      ZWSP + "> quote",
+      ZWSP + "# hash",
+      ZWSP + "1. one",
+      ZWSP + "> [!info] note",
+      ZWSP + "```js",
+      ZWSP + "---",
+      ZWSP + "***",
+      ZWSP + "___",
+      "You: normal line",
+    ]);
+
+    editor.destroy();
+  });
+
+  it("is a no-op for undefined / empty / whitespace-only / non-string transcripts", () => {
+    for (const value of [undefined, "", "   \n  \n", 42, {}, null]) {
+      const editor = makeEditor();
+      const before = JSON.stringify(editor.getJSON());
+
+      const inserted = gitmostInsertTranscriptIntoEditor(editor, value as any);
+
+      expect(inserted).toBe(false);
+      // Document is untouched (audio-only behavior preserved).
+      expect(JSON.stringify(editor.getJSON())).toBe(before);
+      editor.destroy();
+    }
+  });
+});
@@ -65,6 +65,11 @@ export interface GitmostCreatePagePayload {
  base64: string;
  filename: string;
  mimeType: string;
+  // Optional transcript for the recording: plain text, `\n`-separated, each
+  // line already formatted as `You: ...` / `Speaker N: ...` by the native host
+  // (ready to insert, no parsing needed). Omitted (no speech / no models) ->
+  // audio only.
+  transcript?: string;
 }

 export interface GitmostCreatePageResult {
@@ -235,6 +240,83 @@ export async function gitmostUploadFileToEditor(
  }
 }

+// Zero-width space (U+200B). Prepended to a transcript line that begins with a
+// markdown BLOCK trigger: it is invisible in the rendered doc but shifts the
+// trigger off column 0, so the git-sync doc->markdown->doc round-trip keeps the
+// line a plain paragraph (see GITMOST_MD_BLOCK_TRIGGER_RE).
+const GITMOST_ZWSP = "";
+
+// A markdown BLOCK-level construct that, sitting at column 0 of a paragraph
+// line, the git-sync markdown serializer (packages/prosemirror-markdown
+// markdown-converter.ts, `case "paragraph"`) would re-parse into a NON-paragraph
+// block on the doc->markdown->doc cycle. That serializer emits paragraph text
+// verbatim with NO block-escape (the pre-existing root cause), so a leading
+// `#`/`-`/`*`/`+`/`>`, an ordered-list `N.`/`N)`, a code fence ```/~~~, a table
+// `|`, or a `> [!info]` callout opener would silently become a heading / list /
+// quote / code block / table / callout. The final alternative matches a WHOLE-
+// LINE thematic break — solid `---`/`***`/`___` or spaced `- - -`/`_ _ _` (3+ of
+// the same `-`/`*`/`_`) — which round-trips into a `horizontalRule`; because
+// that node carries NO text, an un-neutralized separator line would LOSE its
+// text entirely (worse than the list/quote case). This matches a TRIMMED line's
+// start; the transcript's own `You:` / `Speaker N:` prefix begins with a letter
+// and never matches, so prefixed lines are left byte-exact.
+const GITMOST_MD_BLOCK_TRIGGER_RE =
+  /^(?:#{1,6}(?:\s|$)|[-*+](?:\s|$)|>|\d+[.)](?:\s|$)|```|~~~|\||([-*_])(?:\s*\1){2,}\s*$)/;
+
+// Append a transcript block BELOW the recording's audio node in a live editor:
+// a "Transcript" heading followed by one paragraph per non-empty transcript
+// line. The transcript is plain text, `\n`-separated, each line already
+// formatted as `You: ...` / `Speaker N: ...` by the native host — line text is
+// inserted as a TEXT node (never HTML/markdown), so there is no injection or
+// mark-parsing surface. Each kept line is trimmed (drops an indent that would
+// both leak into the display and, at col 0, form a markdown block trigger) and,
+// if it still begins with a col-0 markdown block trigger, gets an invisible
+// zero-width space prepended so the git-sync round-trip cannot turn it into a
+// list/quote/heading/callout/code/table (defensive boundary against the
+// serializer's missing block-escape). This is best-effort and meant to run
+// AFTER the audio has already been inserted; the caller must guard against a
+// throw so a transcript failure never fails the (already successful) recording.
+// Returns true when a block was inserted, false when there was nothing to
+// insert (transcript undefined/empty/not-a-string). A non-string value is a
+// no-op, not an error.
+export function gitmostInsertTranscriptIntoEditor(
+  editor: Editor,
+  transcript: unknown,
+): boolean {
+  if (typeof transcript !== "string") return false;
+  const lines = transcript
+    .split("\n")
+    // Trim each line and drop blank (whitespace-only) ones.
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    // Neutralize a col-0 markdown block trigger with an invisible ZWSP so the
+    // git-sync round-trip keeps the line a paragraph. Host lines (`You:` /
+    // `Speaker N:`) never match and stay byte-exact.
+    .map((line) =>
+      GITMOST_MD_BLOCK_TRIGGER_RE.test(line) ? GITMOST_ZWSP + line : line,
+    );
+  if (lines.length === 0) return false;
+
+  const content = [
+    {
+      type: "heading",
+      attrs: { level: 2 },
+      content: [{ type: "text", text: "Transcript" }],
+    },
+    ...lines.map((line) => ({
+      type: "paragraph",
+      content: [{ type: "text", text: line }],
+    })),
+  ];
+
+  // Append at the end of the document. On a freshly-created recording page the
+  // audio node is the last block, so the end position places the transcript
+  // directly below it.
+  const endPos = editor.state.doc.content.size;
+  editor.chain().focus().insertContentAt(endPos, content).run();
+  return true;
+}
+
 // Full insert path used by the open-page bridge (insertRecording): guard the
 // editor, validate/decode the payload, then upload. Never throws — resolves to
 // a result code.
@@ -31,11 +31,18 @@ import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom";
 import {
+  collabProviderAtom,
  currentPageEditModeAtom,
  dictationAvailabilityAtom,
  pageEditorAtom,
  yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms";
+import { notifications } from "@mantine/notifications";
+import {
+  VERSION_SAVED_MESSAGE_TYPE,
+  type VersionSavedMessage,
+  saveVersionPending,
+} from "@/features/page-history/version-messages";
 import { asideStateAtom } from "@/components/layouts/global/hooks/atoms/sidebar-atom";
 import {
  activeCommentIdAtom,
@@ -123,6 +130,7 @@ export default function PageEditor({

  const [currentUser] = useAtom(currentUserAtom);
  const [, setEditor] = useAtom(pageEditorAtom);
+  const setCollabProvider = useSetAtom(collabProviderAtom);
  const [, setAsideState] = useAtom(asideStateAtom);
  const [, setActiveCommentId] = useAtom(activeCommentIdAtom);
  const [showCommentPopup, setShowCommentPopup] = useAtom(showCommentPopupAtom);
@@ -180,6 +188,24 @@ export default function PageEditor({
      const onStatelessHandler = ({ payload }: onStatelessParameters) => {
        try {
          const message = JSON.parse(payload);
+          // #370 — a version was saved somewhere; live-refresh the history panel
+          // on every client. Only the client that pressed Save (tracked by the
+          // module-level flag) shows the confirmation toast.
+          if (message?.type === VERSION_SAVED_MESSAGE_TYPE) {
+            const versionMsg = message as VersionSavedMessage;
+            queryClient.invalidateQueries({
+              queryKey: ["page-history-list"],
+            });
+            if (saveVersionPending.current) {
+              saveVersionPending.current = false;
+              notifications.show({
+                message: versionMsg.alreadySaved
+                  ? t("Already saved as the latest version")
+                  : t("Version saved"),
+              });
+            }
+            return;
+          }
          if (message?.type !== "page.updated" || !message.updatedAt) return;
          const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
          if (pageData) {
@@ -237,12 +263,16 @@ export default function PageEditor({

      local.on("synced", onLocalSyncedHandler);
      providersRef.current = { socket, local, remote };
+      // #370 — publish the provider so the header menu can emit save-version.
+      setCollabProvider(remote);
      setProvidersReady(true);
    } else {
+      setCollabProvider(providersRef.current.remote);
      setProvidersReady(true);
    }
    // Only destroy on final unmount
    return () => {
+      setCollabProvider(null);
      providersRef.current?.socket.destroy();
      providersRef.current?.remote.destroy();
      providersRef.current?.local.destroy();
@@ -1,4 +1,11 @@
-import { Text, Group, UnstyledButton, Avatar, Tooltip } from "@mantine/core";
+import {
+  Text,
+  Group,
+  UnstyledButton,
+  Avatar,
+  Tooltip,
+  Badge,
+} from "@mantine/core";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
 import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
 import { formattedDate } from "@/lib/time";
@@ -7,36 +14,59 @@ import clsx from "clsx";
 import { IPageHistory } from "@/features/page-history/types/page.types";
 import { memo, useCallback } from "react";
 import { useSetAtom } from "jotai";
+import { useTranslation } from "react-i18next";
 import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";

 const MAX_VISIBLE_AVATARS = 5;

+/**
+ * #370 — map a snapshot's intentionality tier to its badge. `version: true`
+ * marks the intentional points (manual / agent); autosaves (boundary / idle /
+ * legacy null) are non-versions and get dimmed in the list.
+ */
+type HistoryKindMeta = { labelKey: string; color: string; version: boolean };
+export function historyKindMeta(kind?: string | null): HistoryKindMeta {
+  switch (kind) {
+    case "manual":
+      return { labelKey: "Saved", color: "blue", version: true };
+    case "agent":
+      return { labelKey: "Agent version", color: "violet", version: true };
+    case "boundary":
+      return { labelKey: "Boundary", color: "gray", version: false };
+    default: // "idle" | null | undefined (legacy autosave)
+      return { labelKey: "Autosave", color: "gray", version: false };
+  }
+}
+
 interface HistoryItemProps {
  historyItem: IPageHistory;
-  index: number;
-  onSelect: (id: string, index: number) => void;
-  onHover?: (id: string, index: number) => void;
+  // The previous snapshot for diff/restore is resolved by id from the FULL list
+  // in the parent (resolvePrevSnapshotId), so the item only needs to report its
+  // own id — never a list index (which would be the filtered-view index).
+  onSelect: (id: string) => void;
+  onHover?: (id: string) => void;
  onHoverEnd?: () => void;
  isActive: boolean;
 }

 const HistoryItem = memo(function HistoryItem({
  historyItem,
-  index,
  onSelect,
  onHover,
  onHoverEnd,
  isActive,
 }: HistoryItemProps) {
  const setHistoryModalOpen = useSetAtom(historyAtoms);
+  const { t } = useTranslation();
+  const kindMeta = historyKindMeta(historyItem.kind);

  const handleClick = useCallback(() => {
-    onSelect(historyItem.id, index);
-  }, [onSelect, historyItem.id, index]);
+    onSelect(historyItem.id);
+  }, [onSelect, historyItem.id]);

  const handleMouseEnter = useCallback(() => {
-    onHover?.(historyItem.id, index);
-  }, [onHover, historyItem.id, index]);
+    onHover?.(historyItem.id);
+  }, [onHover, historyItem.id]);

  const contributors = historyItem.contributors;
  const hasContributors = contributors && contributors.length > 0;
@@ -49,8 +79,20 @@ const HistoryItem = memo(function HistoryItem({
      onMouseEnter={handleMouseEnter}
      onMouseLeave={onHoverEnd}
      className={clsx(classes.history, { [classes.active]: isActive })}
+      // #370 — dim autosnapshots so intentional versions stand out.
+      style={{ opacity: kindMeta.version ? 1 : 0.55 }}
    >
-      <Text size="sm">{formattedDate(new Date(historyItem.createdAt))}</Text>
+      <Group gap={6} wrap="nowrap" justify="space-between">
+        <Text size="sm">{formattedDate(new Date(historyItem.createdAt))}</Text>
+        <Badge
+          size="xs"
+          radius="sm"
+          variant={kindMeta.version ? "filled" : "light"}
+          color={kindMeta.color}
+        >
+          {t(kindMeta.labelKey)}
+        </Badge>
+      </Group>

      <Group gap={6} wrap="nowrap" mt={4}>
        {hasContributors ? (
@@ -9,7 +9,7 @@ import {
  historyAtoms,
 } from "@/features/page-history/atoms/history-atoms";
 import { useAtom, useSetAtom } from "jotai";
-import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
  Button,
  ScrollArea,
@@ -17,9 +17,12 @@ import {
  Divider,
  Loader,
  Center,
+  Switch,
+  Text,
 } from "@mantine/core";
 import { useTranslation } from "react-i18next";
 import { useHistoryRestore } from "@/features/page-history/hooks";
+import { resolvePrevSnapshotId } from "@/features/page-history/utils/resolve-prev-snapshot";

 const PREFETCH_DELAY_MS = 150;

@@ -47,6 +50,23 @@ function HistoryList({ pageId }: Props) {
    [pageHistoryData],
  );

+  // #370 — "only versions" filter: hide autosnapshots (idle/boundary/legacy
+  // null), keep only intentional points (manual/agent). Filtering is over the
+  // already-loaded pages; the diff/restore still targets the true previous
+  // snapshot, so items carry their index within the FULL list.
+  const [onlyVersions, setOnlyVersions] = useState(false);
+  const isVersion = useCallback(
+    (kind?: string | null) => kind === "manual" || kind === "agent",
+    [],
+  );
+  const visibleItems = useMemo(
+    () =>
+      onlyVersions
+        ? historyItems.filter((item) => isVersion(item.kind))
+        : historyItems,
+    [historyItems, onlyVersions, isVersion],
+  );
+
  const loadMoreRef = useRef<HTMLDivElement>(null);
  const prefetchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);

@@ -60,11 +80,13 @@ function HistoryList({ pageId }: Props) {
  }, []);

  const handleHover = useCallback(
-    (historyId: string, index: number) => {
+    (historyId: string) => {
      clearPrefetchTimeout();
      prefetchTimeoutRef.current = setTimeout(() => {
        prefetchPageHistory(historyId);
-        const prevId = historyItems[index + 1]?.id;
+        // The true previous snapshot in the FULL list (not the previous visible
+        // one under the "only versions" filter).
+        const prevId = resolvePrevSnapshotId(historyItems, historyId);
        if (prevId) {
          prefetchPageHistory(prevId);
        }
@@ -78,9 +100,11 @@ function HistoryList({ pageId }: Props) {
  }, [clearPrefetchTimeout]);

  const handleSelect = useCallback(
-    (id: string, index: number) => {
+    (id: string) => {
      setActiveHistoryId(id);
-      setActiveHistoryPrevId(historyItems[index + 1]?.id ?? "");
+      // Baseline = true previous snapshot in the FULL list, so the "only
+      // versions" filter never diffs/restores against the wrong item.
+      setActiveHistoryPrevId(resolvePrevSnapshotId(historyItems, id));
    },
    [historyItems, setActiveHistoryId, setActiveHistoryPrevId],
  );
@@ -128,12 +152,27 @@ function HistoryList({ pageId }: Props) {

  return (
    <div>
+      <Group px="xs" py={6} justify="flex-end">
+        <Switch
+          size="xs"
+          checked={onlyVersions}
+          onChange={(e) => setOnlyVersions(e.currentTarget.checked)}
+          label={t("Only versions")}
+        />
+      </Group>
+
      <ScrollArea h={620} w="100%" type="scroll" scrollbarSize={5}>
-        {historyItems.map((historyItem, index) => (
+        {onlyVersions && visibleItems.length === 0 && (
+          <Center py="md">
+            <Text size="sm" c="dimmed">
+              {t("No saved versions yet.")}
+            </Text>
+          </Center>
+        )}
+        {visibleItems.map((historyItem) => (
          <HistoryItem
            key={historyItem.id}
            historyItem={historyItem}
-            index={index}
            onSelect={handleSelect}
            onHover={handleHover}
            onHoverEnd={clearPrefetchTimeout}
@@ -24,6 +24,10 @@ export interface IPageHistory {
  updatedAt: string;
  lastUpdatedBy: IPageHistoryUser;
  contributors?: IPageHistoryUser[];
+  // #370 — intentionality tier: 'manual'/'agent' are versions (intentional
+  // points), 'idle'/'boundary' are autosnapshots; null/undefined = legacy
+  // autosave. Derived server-side, drives the history badge + "versions" filter.
+  kind?: "manual" | "agent" | "idle" | "boundary" | null;
  // Provenance markers copied off the page row when the snapshot was saved.
  // `'agent'` marks a version written by the AI agent; `lastUpdatedAiChatId`
  // (when present) deep-links to the chat that produced the edit.
@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import { resolvePrevSnapshotId } from "./resolve-prev-snapshot";
+
+// #370 F4 — the risky client path: with the "only versions" filter active, diff
+// and restore must still baseline against the TRUE previous snapshot in the FULL
+// list, never the previous VISIBLE version (which would skip the autosnapshots
+// between two versions). These pin that the resolution is by FULL-list order.
+describe("resolvePrevSnapshotId", () => {
+  // Newest-first, as the history list stores it: a version, then two autosaves,
+  // then an older version.
+  const full = [
+    { id: "v2", kind: "manual" },
+    { id: "a2", kind: "idle" },
+    { id: "a1", kind: "boundary" },
+    { id: "v1", kind: "manual" },
+    { id: "a0", kind: null },
+  ];
+
+  it("returns the immediate FULL-list successor, not the previous visible version", () => {
+    // Selecting v2 while filtered to versions-only must baseline against a2 (the
+    // real chronological predecessor), NOT v1 (the previous visible version).
+    expect(resolvePrevSnapshotId(full, "v2")).toBe("a2");
+  });
+
+  it("resolves an autosnapshot's predecessor by full-list order", () => {
+    expect(resolvePrevSnapshotId(full, "a1")).toBe("v1");
+  });
+
+  it("returns '' for the oldest item (no predecessor)", () => {
+    expect(resolvePrevSnapshotId(full, "a0")).toBe("");
+  });
+
+  it("returns '' for an id not in the list", () => {
+    expect(resolvePrevSnapshotId(full, "missing")).toBe("");
+  });
+
+  it("does not depend on a filtered subset — same result whatever is visible", () => {
+    // The helper only ever sees the full list; a filtered view cannot change the
+    // baseline it computes.
+    expect(resolvePrevSnapshotId(full, "v1")).toBe("a0");
+  });
+});
@@ -0,0 +1,22 @@
+/**
+ * #370 — resolve the TRUE previous snapshot for a history item.
+ *
+ * The history panel can be filtered to "only versions" (manual/agent), but diff
+ * and restore must always compare against the immediately-preceding snapshot in
+ * the FULL, unfiltered list — NOT the previous VISIBLE item. Comparing against
+ * the previous visible version would silently skip the autosnapshots between two
+ * versions and diff/restore the wrong baseline.
+ *
+ * Given the full (newest-first) list and an item id, this returns the id of the
+ * item right after it in the full list (its chronological predecessor), or "" if
+ * it is the oldest / not found. Pure and list-order-preserving so it can be unit
+ * tested without mounting the component.
+ */
+export function resolvePrevSnapshotId(
+  fullItems: ReadonlyArray<{ id: string }>,
+  id: string,
+): string {
+  const index = fullItems.findIndex((item) => item.id === id);
+  if (index === -1) return "";
+  return fullItems[index + 1]?.id ?? "";
+}
@@ -0,0 +1,28 @@
+/**
+ * #370 — page-version stateless wire formats. Kept in one place so the client
+ * emitter (Save hotkey / button) and the client listener (page-editor) agree
+ * with the server (PersistenceExtension) on the message shapes.
+ */
+
+/** Client → server: "save a version now". The server derives the tier
+ * (manual/agent) from the signed connection actor, never from this payload. */
+export const SAVE_VERSION_MESSAGE_TYPE = "save-version";
+
+/** Server → all clients: a version was saved (or promoted / already existed). */
+export const VERSION_SAVED_MESSAGE_TYPE = "version.saved";
+
+export interface VersionSavedMessage {
+  type: typeof VERSION_SAVED_MESSAGE_TYPE;
+  historyId: string;
+  kind: "manual" | "agent";
+  /** True when the latest snapshot was already a manual version (a no-op save). */
+  alreadySaved: boolean;
+}
+
+/**
+ * Cross-component coordination flag so only the client that pressed Save shows
+ * the confirmation toast, while every other client silently refreshes its
+ * history panel on the broadcast. A module-level ref avoids stale-closure
+ * pitfalls in the editor's long-lived stateless handler.
+ */
+export const saveVersionPending = { current: false };
@@ -3,6 +3,7 @@ import {
  IconArrowRight,
  IconArrowsHorizontal,
  IconClockHour4,
+  IconDeviceFloppy,
  IconDots,
  IconEye,
  IconEyeOff,
@@ -17,7 +18,7 @@ import {
  IconTrash,
  IconWifiOff,
 } from "@tabler/icons-react";
-import React, { useEffect, useRef, useState } from "react";
+import React, { useCallback, useEffect, useRef, useState } from "react";
 import { useAsideTriggerProps } from "@/hooks/use-toggle-aside.tsx";
 import { useAtom, useAtomValue } from "jotai";
 import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
@@ -39,9 +40,14 @@ import { Trans, useTranslation } from "react-i18next";
 import ExportModal from "@/components/common/export-modal";
 import { htmlToMarkdown } from "@docmost/editor-ext";
 import {
+  collabProviderAtom,
  pageEditorAtom,
  yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms.ts";
+import {
+  SAVE_VERSION_MESSAGE_TYPE,
+  saveVersionPending,
+} from "@/features/page-history/version-messages.ts";
 import { formattedDate } from "@/lib/time.ts";
 import { PageEditModeToggle } from "@/features/user/components/page-state-pref.tsx";
 import MovePageModal from "@/features/page/components/move-page-modal.tsx";
@@ -72,9 +78,34 @@ export default function PageHeaderMenu({ readOnly }: PageHeaderMenuProps) {
  });
  const isDeleted = !!page?.deletedAt;
  const [workspace] = useAtom(workspaceAtom);
+  const collabProvider = useAtomValue(collabProviderAtom);
  // Community public-sharing entry point (replaces the removed EE PageShareModal)
  const workspaceSharingDisabled = workspace?.settings?.sharing?.disabled === true;

+  // #370 — explicit "save a version" (Cmd+S / Save button). One path for the
+  // human; the server derives the tier from the signed actor. Readers can't save
+  // (the button is hidden and the collab connection is read-only server-side).
+  const handleSaveVersion = useCallback(() => {
+    if (readOnly || !collabProvider) return;
+    // Flag this client as the initiator so only it shows the confirmation toast;
+    // a safety timeout clears it if no broadcast comes back (e.g. offline).
+    saveVersionPending.current = true;
+    window.setTimeout(() => {
+      saveVersionPending.current = false;
+    }, 5000);
+    collabProvider.sendStateless(
+      JSON.stringify({ type: SAVE_VERSION_MESSAGE_TYPE }),
+    );
+  }, [readOnly, collabProvider]);
+
+  // mod+S must also block the browser's "Save page" dialog. `triggerOnContent-
+  // Editable` + empty ignore-list so it fires while typing in the editor/title.
+  useHotkeys(
+    [["mod+S", handleSaveVersion, { preventDefault: true }]],
+    [],
+    true,
+  );
+
  useHotkeys(
    [
      [
@@ -133,15 +164,16 @@ export default function PageHeaderMenu({ readOnly }: PageHeaderMenuProps) {
        </ActionIcon>
      </Tooltip>

-      <PageActionMenu readOnly={readOnly} />
+      <PageActionMenu readOnly={readOnly} onSaveVersion={handleSaveVersion} />
    </>
  );
 }

 interface PageActionMenuProps {
  readOnly?: boolean;
+  onSaveVersion?: () => void;
 }
-function PageActionMenu({ readOnly }: PageActionMenuProps) {
+function PageActionMenu({ readOnly, onSaveVersion }: PageActionMenuProps) {
  const { t } = useTranslation();
  const [, setHistoryModalOpen] = useAtom(historyAtoms);
  const clipboard = useClipboard({ timeout: 500 });
@@ -302,6 +334,20 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
            </Group>
          </Menu.Item>

+          {!readOnly && (
+            <Menu.Item
+              leftSection={<IconDeviceFloppy size={16} />}
+              onClick={onSaveVersion}
+              rightSection={
+                <Text size="xs" c="dimmed">
+                  {t("Ctrl+S")}
+                </Text>
+              }
+            >
+              {t("Save version")}
+            </Menu.Item>
+          )}
+
          <Menu.Item
            leftSection={<IconHistory size={16} />}
            onClick={openHistoryModal}
@@ -23,7 +23,7 @@
    "migration:reset": "tsx src/database/migrate.ts down-to NO_MIGRATIONS",
    "migration:codegen": "kysely-codegen --dialect=postgres --camel-case --env-file=../../.env --out-file=./src/database/types/db.d.ts",
    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
-    "pretest": "pnpm --filter @docmost/editor-ext build",
+    "pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/prosemirror-markdown build",
    "test": "jest",
    "test:int": "jest --config test/jest-integration.json",
    "test:watch": "jest --watch",
@@ -43,6 +43,7 @@
    "@clickhouse/client": "^1.18.2",
    "@docmost/mcp": "workspace:*",
    "@docmost/pdf-inspector": "1.9.6",
+    "@docmost/prosemirror-markdown": "workspace:*",
    "@fastify/cookie": "^11.0.2",
    "@fastify/multipart": "^10.0.0",
    "@fastify/static": "^9.1.3",
@@ -175,7 +176,7 @@
      "/node_modules/"
    ],
    "transform": {
-      "happy-dom.+\\.js$": [
+      "(happy-dom.+|prosemirror-markdown/build/.+)\\.js$": [
        "babel-jest",
        {
          "presets": [
@@ -193,7 +194,7 @@
      "^.+\\.(t|j)sx?$": "ts-jest"
    },
    "transformIgnorePatterns": [
-      "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0)(@|/))"
+      "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0|@docmost/prosemirror-markdown)(@|/))"
    ],
    "collectCoverageFrom": [
      "**/*.(t|j)s"
@@ -204,7 +205,8 @@
      "^@docmost/db/(.*)$": "<rootDir>/database/$1",
      "^@docmost/transactional/(.*)$": "<rootDir>/integrations/transactional/$1",
      "^@docmost/ee/(.*)$": "<rootDir>/ee/$1",
-      "^src/(.*)$": "<rootDir>/$1"
+      "^src/(.*)$": "<rootDir>/$1",
+      "^@tiptap/react$": "<rootDir>/../test/stubs/tiptap-react.js"
    }
  }
 }
@@ -43,7 +43,6 @@ import {
  Column,
  Status,
  addUniqueIdsToDoc,
-  htmlToMarkdown,
  TransclusionSource,
  TransclusionReference,
  FootnoteReference,
@@ -51,6 +50,7 @@ import {
  FootnoteDefinition,
  PageEmbed,
 } from '@docmost/editor-ext';
+import { convertProseMirrorToMarkdown } from '@docmost/prosemirror-markdown';
 import { generateText, getSchema, JSONContent } from '@tiptap/core';
 import { generateHTML, generateJSON } from '../common/helpers/prosemirror/html';
 // @tiptap/html library works best for generating prosemirror json state but not HTML
@@ -239,6 +239,10 @@ export function prosemirrorNodeToYElement(node: any): Y.XmlElement | Y.XmlText {
 }

 export function jsonToMarkdown(tiptapJson: any): string {
-  const html = jsonToHtml(tiptapJson);
-  return htmlToMarkdown(html);
+  // Direct ProseMirror JSON -> Markdown via the canonical converter
+  // (`@docmost/prosemirror-markdown`) — no HTML intermediate, no second
+  // editor-ext markdown layer. Same serializer as the page/space export and the
+  // git-sync vault writer, so every server PM->MD path emits identical canonical
+  // markdown (issue #345).
+  return convertProseMirrorToMarkdown(tiptapJson);
 }
@@ -1,3 +1,29 @@
-export const HISTORY_INTERVAL = 5 * 60 * 1000;
-export const HISTORY_FAST_INTERVAL = 60 * 1000;
-export const HISTORY_FAST_THRESHOLD = 5 * 60 * 1000;
+/**
+ * #370 — page-history intentionality tiers. Domain of `page_history.kind`.
+ *   - 'manual' / 'agent'  → Tier 1 versions (intentional points)
+ *   - 'idle' / 'boundary' → Tier 0 autosnapshots (safety net)
+ * A legacy `null` kind is treated as an autosave.
+ */
+export type PageHistoryKind = 'manual' | 'agent' | 'idle' | 'boundary';
+
+/**
+ * #370 — trailing idle-flush windows. A page's pending idle snapshot is
+ * re-armed on every store and fires this long after edits go quiet, so a burst
+ * of edits collapses into a single autosnapshot instead of one-per-store. Human
+ * sessions are noisier and less risky, so they flush less often than the agent.
+ */
+export const IDLE_INTERVAL_USER = 60 * 60 * 1000; // 60m
+export const IDLE_INTERVAL_AGENT = 15 * 60 * 1000; // 15m
+
+/**
+ * #370 — max-wait ceiling for the idle flush. Pure trailing debounce starves the
+ * safety net: hocuspocus stores at least every ~45s, so a CONTINUOUS editing
+ * session would re-arm the trailing timer forever and never take an idle
+ * snapshot until edits finally go quiet (up to IDLE_INTERVAL_USER = 60m). This
+ * ceiling bounds the actual wait from the FIRST edit of a burst, so an idle
+ * snapshot fires at least this often during a long unbroken session — restoring
+ * a recovery point cadence closer to the old heuristic without one-per-store
+ * noise. Mirrors hocuspocus's own maxDebounce idea.
+ */
+export const IDLE_MAX_WAIT_USER = 10 * 60 * 1000; // 10m
+export const IDLE_MAX_WAIT_AGENT = 5 * 60 * 1000; // 5m
@@ -1,84 +1,93 @@
+import { computeHistoryJob, resolveSource } from './persistence.extension';
 import {
-  computeHistoryJob,
-  resolveSource,
-} from './persistence.extension';
-import {
-  HISTORY_FAST_INTERVAL,
-  HISTORY_FAST_THRESHOLD,
-  HISTORY_INTERVAL,
+  IDLE_INTERVAL_AGENT,
+  IDLE_INTERVAL_USER,
+  IDLE_MAX_WAIT_AGENT,
+  IDLE_MAX_WAIT_USER,
 } from '../constants';

-// A fixed clock + fixed createdAt make pageAge deterministic.
-const NOW = 1_700_000_000_000;
 const PAGE_ID = '550e8400-e29b-41d4-a716-446655440000';

-// Build a minimal page whose age (NOW - createdAt) is exactly `ageMs`.
-const pageAged = (ageMs: number) => ({
-  id: PAGE_ID,
-  createdAt: new Date(NOW - ageMs),
-});
+const page = { id: PAGE_ID };

-describe('computeHistoryJob', () => {
-  it('agent edit → delay MUST be 0 and job id is source-keyed', () => {
-    // INVARIANT (§15 H2 / persistence.extension): the agent delay MUST stay 0.
-    // The worker re-reads the page row at run time, so any non-zero delay risks
-    // snapshotting content a later human edit has already overwritten. This is
-    // the load-bearing assertion of this spec — do not relax it.
-    const { jobId, delay } = computeHistoryJob(pageAged(0), 'agent', NOW);
-    expect(delay).toBe(0);
-    expect(jobId).toBe(`${PAGE_ID}-agent`);
-  });
-
-  it('agent edit on an OLD page is still delay 0 (age never applies to agents)', () => {
-    // Even when the page is far older than the fast threshold, the agent path
-    // must short-circuit to 0 — age-based debounce is a human-only concern.
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD + 60_000),
-      'agent',
-      NOW,
-    );
-    expect(delay).toBe(0);
-    expect(jobId).toBe(`${PAGE_ID}-agent`);
-  });
-
-  it('human edit on a YOUNG page (age < threshold) → fast interval, bare job id', () => {
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD - 1),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_FAST_INTERVAL);
+describe('computeHistoryJob (#370 — shared trailing idle pipeline)', () => {
+  it('human edit → user idle window, bare page.id job', () => {
+    // Humans and the agent now share ONE idle job per page (jobId = page.id).
+    // The agent's old delay=0 fast path is GONE — intentional agent points now
+    // arrive via the explicit save-version signal, not a zero-delay snapshot.
+    const { jobId, delay } = computeHistoryJob(page, 'user');
+    expect(delay).toBe(IDLE_INTERVAL_USER);
    expect(jobId).toBe(PAGE_ID);
  });

-  it('human edit on an OLD page (age > threshold) → standard interval', () => {
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD + 1),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_INTERVAL);
+  it('agent edit → agent idle window (shorter), still the bare page.id job', () => {
+    const { jobId, delay } = computeHistoryJob(page, 'agent');
+    expect(delay).toBe(IDLE_INTERVAL_AGENT);
+    // No `-agent` suffix anymore: the agent joins the common idle pipeline.
    expect(jobId).toBe(PAGE_ID);
  });

-  it('boundary: pageAge EXACTLY === threshold takes the slow branch (the `<` is strict)', () => {
-    // Off-by-one guard: the condition is `pageAge < HISTORY_FAST_THRESHOLD`, so
-    // an age of exactly the threshold is NOT "fast" — it must use HISTORY_INTERVAL.
-    const { delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_INTERVAL);
+  it('agent flushes sooner than a human', () => {
+    expect(IDLE_INTERVAL_AGENT).toBeLessThan(IDLE_INTERVAL_USER);
  });

-  it('treats any non-"agent" source string as human', () => {
-    // resolveSource only ever yields 'agent' | 'user', but guard the contract:
-    // the agent branch keys strictly on === 'agent'.
-    const { jobId, delay } = computeHistoryJob(pageAged(0), 'user', NOW);
-    expect(delay).toBe(HISTORY_FAST_INTERVAL);
+  it('treats any non-"agent" source string as human (keys strictly on === agent)', () => {
+    const { jobId, delay } = computeHistoryJob(page, 'user');
+    expect(delay).toBe(IDLE_INTERVAL_USER);
    expect(jobId).toBe(PAGE_ID);
  });
+
+  // #370 review round-1 WARNING: the max-wait ceiling prevents autosnapshot
+  // starvation during a continuous editing session (the trailing timer would
+  // otherwise re-arm forever and never fire).
+  describe('max-wait ceiling', () => {
+    const T0 = 1_000_000; // arbitrary fixed epoch for deterministic tests
+
+    it('once a burst is armed, delay clamps to the remaining max-wait budget', () => {
+      // 1 minute into the burst the USER interval (60m) far exceeds the remaining
+      // max-wait budget (10m - 1m = 9m), so the delay is clamped DOWN to that
+      // remaining budget — the full interval is NOT used once a ceiling applies.
+      const { delay } = computeHistoryJob(page, 'user', T0, T0 + 60_000);
+      expect(delay).toBe(IDLE_MAX_WAIT_USER - 60_000);
+    });
+
+    it('never waits longer than the max-wait budget from the burst start', () => {
+      // A store arriving right at the ceiling → delay 0 (fire promptly).
+      const { delay } = computeHistoryJob(
+        page,
+        'user',
+        T0,
+        T0 + IDLE_MAX_WAIT_USER,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('past the ceiling never returns a negative delay', () => {
+      const { delay } = computeHistoryJob(
+        page,
+        'user',
+        T0,
+        T0 + IDLE_MAX_WAIT_USER + 5 * 60_000,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('the agent ceiling is shorter than the user ceiling', () => {
+      expect(IDLE_MAX_WAIT_AGENT).toBeLessThan(IDLE_MAX_WAIT_USER);
+      const { delay } = computeHistoryJob(
+        page,
+        'agent',
+        T0,
+        T0 + IDLE_MAX_WAIT_AGENT,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('without a burstStart there is no ceiling (backward-compatible)', () => {
+      expect(computeHistoryJob(page, 'user').delay).toBe(IDLE_INTERVAL_USER);
+      expect(computeHistoryJob(page, 'agent').delay).toBe(IDLE_INTERVAL_AGENT);
+    });
+  });
 });

 describe('resolveSource (truth table)', () => {
@@ -40,11 +40,12 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
  let pageHistoryRepo: {
    saveHistory: jest.Mock;
    findPageLastHistory: jest.Mock;
+    updateHistoryKind: jest.Mock;
  };
  let aiQueue: { add: jest.Mock };
-  let historyQueue: { add: jest.Mock };
+  let historyQueue: { add: jest.Mock; remove: jest.Mock };
  let notificationQueue: { add: jest.Mock };
-  let collabHistory: { addContributors: jest.Mock };
+  let collabHistory: { addContributors: jest.Mock; popContributors: jest.Mock };
  let transclusionService: {
    syncPageTransclusions: jest.Mock;
    syncPageReferences: jest.Mock;
@@ -93,13 +94,22 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
    pageHistoryRepo = {
      saveHistory: jest.fn().mockImplementation(async () => {
        callOrder.push('saveHistory');
+        return { id: 'history-1' };
      }),
      findPageLastHistory: jest.fn().mockResolvedValue(null),
+      updateHistoryKind: jest.fn().mockResolvedValue(undefined),
    };
    aiQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    historyQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    historyQueue = {
+      add: jest.fn().mockResolvedValue(undefined),
+      // #370 — enqueuePageHistory now removes any pending idle job before re-adding.
+      remove: jest.fn().mockResolvedValue(undefined),
+    };
    notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    collabHistory = { addContributors: jest.fn().mockResolvedValue(undefined) };
+    collabHistory = {
+      addContributors: jest.fn().mockResolvedValue(undefined),
+      popContributors: jest.fn().mockResolvedValue([]),
+    };
    transclusionService = {
      syncPageTransclusions: jest.fn().mockResolvedValue(undefined),
      syncPageReferences: jest.fn().mockResolvedValue(undefined),
@@ -165,6 +175,50 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
    expect(pageRepo.updatePage.mock.calls[0][0].lastUpdatedSource).toBe('user');
  });

+  // #370 review round-1 SUGGESTION: the boundary was GENERALIZED from a
+  // user→agent special-case to ANY lastUpdatedSource transition. These pin the
+  // generalized behaviour it was rebuilt for.
+  describe('generalized boundary — any source transition', () => {
+    // Same persisted page but with an explicit prior source.
+    const pageWithPriorSource = (prior: string | null) => ({
+      ...persistedHumanPage('NEW CONTENT'),
+      lastUpdatedSource: prior,
+    });
+
+    it('agent→user transition fires the boundary (pins the prior agent revision)', async () => {
+      const document = ydocFor(doc('NEW CONTENT'));
+      pageRepo.findById.mockResolvedValue(pageWithPriorSource('agent'));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await ext.onStoreDocument(buildData(document, 'user') as any);
+
+      expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+      expect(callOrder).toEqual(['saveHistory', 'updatePage']);
+      expect(pageRepo.updatePage.mock.calls[0][0].lastUpdatedSource).toBe('user');
+    });
+
+    it('git→user transition fires the boundary (git-sync overwrite is a source change)', async () => {
+      const document = ydocFor(doc('NEW CONTENT'));
+      pageRepo.findById.mockResolvedValue(pageWithPriorSource('git'));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await ext.onStoreDocument(buildData(document, 'user') as any);
+
+      expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+      expect(callOrder).toEqual(['saveHistory', 'updatePage']);
+    });
+
+    it('a null prior source (first-ever edit) does NOT fire the boundary', async () => {
+      const document = ydocFor(doc('NEW CONTENT'));
+      pageRepo.findById.mockResolvedValue(pageWithPriorSource(null));
+
+      await ext.onStoreDocument(buildData(document, 'agent') as any);
+
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+    });
+  });
+
  it('idempotency: unchanged content → no updatePage, no history, no queues', async () => {
    // The Y.Doc content equals the persisted content deeply → early skip.
    // A Y.Doc round-trip normalizes attrs (e.g. paragraph indent), so derive
@@ -469,4 +523,125 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
    // Contributors keyed by the UUID so they match the PAGE_HISTORY job (page.id).
    expect(collabHistory.addContributors.mock.calls[0][0]).toBe(PAGE_ID);
  });
+
+  // #370 — explicit save-version (Cmd+S / agent save tool) over the stateless
+  // seam. The tier is derived from the SIGNED connection actor, the store path
+  // is reused, and promote-not-dup avoids duplicating heavy content rows.
+  describe('save-version (#370)', () => {
+    const emitSave = (document: any, actor: 'user' | 'agent') =>
+      ext.onStateless({
+        connection: {
+          readOnly: false,
+          context: { user: { id: USER_ID, name: 'Alice' }, actor },
+        } as any,
+        documentName: `page.${PAGE_ID}`,
+        document: document as any,
+        payload: JSON.stringify({ type: 'save-version' }),
+      } as any);
+
+    // findById returns a page whose content already equals the live doc, so the
+    // store path is a no-op and we isolate the versioning decision.
+    const pageMatchingDoc = (document: any) => ({
+      ...persistedHumanPage('IGNORED'),
+      content: TiptapTransformer.fromYdoc(document, 'default'),
+    });
+
+    it('human save with no prior snapshot → writes a manual version + broadcasts', async () => {
+      const document = ydocFor(doc('VERSION ME'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await emitSave(document, 'user');
+
+      expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+      expect(pageHistoryRepo.saveHistory.mock.calls[0][1]).toEqual(
+        expect.objectContaining({ kind: 'manual' }),
+      );
+      // The pending idle autosnapshot is cancelled by the explicit version.
+      expect(historyQueue.remove).toHaveBeenCalledWith(PAGE_ID);
+      const msg = JSON.parse(
+        (document as any).broadcastStateless.mock.calls[(document as any).broadcastStateless.mock.calls.length - 1][0],
+      );
+      expect(msg).toMatchObject({
+        type: 'version.saved',
+        kind: 'manual',
+        alreadySaved: false,
+      });
+    });
+
+    it('agent save derives kind=agent from the signed actor', async () => {
+      const document = ydocFor(doc('AGENT VERSION'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await emitSave(document, 'agent');
+
+      expect(pageHistoryRepo.saveHistory.mock.calls[pageHistoryRepo.saveHistory.mock.calls.length - 1][1]).toEqual(
+        expect.objectContaining({ kind: 'agent' }),
+      );
+    });
+
+    it('promote-not-dup: latest snapshot is an autosave with identical content → upgrades in place', async () => {
+      const document = ydocFor(doc('SAME'));
+      const page = pageMatchingDoc(document);
+      pageRepo.findById.mockResolvedValue(page);
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+        id: 'auto-1',
+        content: page.content,
+        kind: 'idle',
+      });
+
+      await emitSave(document, 'user');
+
+      // No heavy new content row — the existing autosave is promoted to manual.
+      expect(pageHistoryRepo.updateHistoryKind).toHaveBeenCalledWith(
+        'auto-1',
+        'manual',
+        expect.anything(),
+      );
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      const msg = JSON.parse(
+        (document as any).broadcastStateless.mock.calls[(document as any).broadcastStateless.mock.calls.length - 1][0],
+      );
+      expect(msg).toMatchObject({ historyId: 'auto-1', alreadySaved: false });
+    });
+
+    it('no-op when the latest snapshot is already a manual version of this content', async () => {
+      const document = ydocFor(doc('ALREADY SAVED'));
+      const page = pageMatchingDoc(document);
+      pageRepo.findById.mockResolvedValue(page);
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+        id: 'ver-1',
+        content: page.content,
+        kind: 'manual',
+      });
+
+      await emitSave(document, 'user');
+
+      expect(pageHistoryRepo.updateHistoryKind).not.toHaveBeenCalled();
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      const msg = JSON.parse(
+        (document as any).broadcastStateless.mock.calls[(document as any).broadcastStateless.mock.calls.length - 1][0],
+      );
+      expect(msg).toMatchObject({ alreadySaved: true, kind: 'manual' });
+    });
+
+    it('a read-only connection cannot save a version', async () => {
+      const document = ydocFor(doc('READER'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+
+      await ext.onStateless({
+        connection: {
+          readOnly: true,
+          context: { user: { id: USER_ID }, actor: 'user' },
+        } as any,
+        documentName: `page.${PAGE_ID}`,
+        document: document as any,
+        payload: JSON.stringify({ type: 'save-version' }),
+      } as any);
+
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      expect(pageHistoryRepo.updateHistoryKind).not.toHaveBeenCalled();
+    });
+  });
 });
@@ -36,9 +36,11 @@ import {
 import { Page } from '@docmost/db/types/entity.types';
 import { CollabHistoryService } from '../services/collab-history.service';
 import {
-  HISTORY_FAST_INTERVAL,
-  HISTORY_FAST_THRESHOLD,
-  HISTORY_INTERVAL,
+  IDLE_INTERVAL_AGENT,
+  IDLE_INTERVAL_USER,
+  IDLE_MAX_WAIT_AGENT,
+  IDLE_MAX_WAIT_USER,
+  PageHistoryKind,
 } from '../constants';
 import { TransclusionService } from '../../core/page/transclusion/transclusion.service';
 import { observeCollabStore } from '../../integrations/metrics/metrics.registry';
@@ -51,6 +53,16 @@ import { observeCollabStore } from '../../integrations/metrics/metrics.registry'
 */
 export const INTENTIONAL_CLEAR_MESSAGE_TYPE = 'intentional-clear';

+/**
+ * #370 — wire format of the client→server "save a version" signal. Sent by the
+ * human (Cmd+S / Save button) and by the agent's explicit save tool over the
+ * SAME stateless channel. The intentionality tier ('manual' vs 'agent') is
+ * derived SERVER-SIDE from the signed connection actor, never from this
+ * payload, so a version's type is unforgeable. The document is taken from the
+ * connection (not the payload), so the signal cannot be aimed at another page.
+ */
+export const SAVE_VERSION_MESSAGE_TYPE = 'save-version';
+
 /**
 * #251 — how long an intentional-clear signal stays "pending" before it is
 * ignored. The signal is set on the clearing keystroke but consumed by the
@@ -87,35 +99,39 @@ export function resolveSource(
 }

 /**
- * Compute the BullMQ job id + delay for a page-history snapshot job. Pure so
- * the data-loss-sensitive timing arithmetic is unit-testable; `now` is injected
- * (caller passes `Date.now()`) for determinism.
+ * #370 — compute the BullMQ job id + delay for a page's trailing idle-flush
+ * autosnapshot. Pure so the timing is unit-testable.
 *
- * - Agent edits: delay 0 and a source-keyed job id `${page.id}-agent`. The
- *   delay MUST stay 0 — the worker re-reads the page row at run time, so any
- *   delay risks reading content a later human edit has already overwritten
- *   (mis-tagged snapshot). 0 minimizes that window. The `-agent` suffix keeps
- *   the job from coalescing with the bare-page.id human job.
- * - Human edits: age-based debounce so rapid human edits coalesce into one
- *   snapshot; job id is the bare `page.id`.
- *
- * BullMQ forbids ':' in custom job ids (Redis key separator), so '-' is used;
- * page.id is a UUID, so `${page.id}-agent` cannot collide with a human job.
+ * Both humans and the agent now share ONE idle pipeline (the agent's old
+ * `delay=0` fast path is gone — intentional agent points arrive via the
+ * explicit save-version signal instead). The job id is the bare `page.id`, so a
+ * page has at most one pending idle job; the caller removes-and-re-adds it on
+ * every store to keep it debounced to the trailing edge of an edit burst. The
+ * window differs by source only: the agent flushes sooner than a human.
 */
 export function computeHistoryJob(
-  page: Pick<Page, 'id' | 'createdAt'>,
+  page: Pick<Page, 'id'>,
  source: string,
-  now: number,
+  // Epoch ms of the FIRST edit in the current burst (when the pending idle job
+  // was first armed). Used to enforce the max-wait ceiling so a continuous
+  // editing session cannot re-arm the trailing timer forever. `now` is injectable
+  // for tests; both default to a live clock / no ceiling when omitted.
+  burstStart?: number,
+  now: number = Date.now(),
 ): { jobId: string; delay: number } {
  const isAgent = source === 'agent';
-  const pageAge = now - new Date(page.createdAt).getTime();
-  const delay = isAgent
-    ? 0
-    : pageAge < HISTORY_FAST_THRESHOLD
-      ? HISTORY_FAST_INTERVAL
-      : HISTORY_INTERVAL;
-  const jobId = isAgent ? `${page.id}-agent` : page.id;
-  return { jobId, delay };
+  const interval = isAgent ? IDLE_INTERVAL_AGENT : IDLE_INTERVAL_USER;
+  const maxWait = isAgent ? IDLE_MAX_WAIT_AGENT : IDLE_MAX_WAIT_USER;
+
+  let delay = interval;
+  if (burstStart !== undefined) {
+    // Time already elapsed since the burst's first edit; the snapshot must fire
+    // no later than `maxWait` after that, so shrink the trailing delay to the
+    // remaining budget (never negative, so BullMQ fires it promptly).
+    const remaining = burstStart + maxWait - now;
+    delay = Math.max(0, Math.min(interval, remaining));
+  }
+  return { jobId: page.id, delay };
 }

@Injectable()
@@ -127,6 +143,11 @@ export class PersistenceExtension implements Extension {
  // coalescing window" per document and OR it across all edits in the window,
  // so the snapshot is marked 'agent' regardless of who wrote last.
  private agentTouched: Map<string, boolean> = new Map();
+  // #370 — epoch ms of the FIRST edit in the current idle-flush burst, per page.
+  // Set when the pending idle job is first armed (empty entry), read to enforce
+  // the max-wait ceiling in computeHistoryJob, and cleared when the idle job is
+  // consumed/cancelled so the next burst starts a fresh window.
+  private idleBurstStart: Map<string, number> = new Map();
  // #251 — per-document "intentional clear pending" flags. Keyed by
  // documentName, value = expiry timestamp (ms). Set by onStateless when the
  // client reports a deliberate clear; consumed once by the next
@@ -326,20 +347,19 @@ export class PersistenceExtension implements Extension {
            //this.logger.debug('Contributors error:' + err?.['message']);
          }

-          // Approach A — boundary snapshot before the agent's first edit.
-          // When this store is the agent's and the page's currently persisted
-          // state was authored by a human, pin that human state as its own
-          // history version BEFORE the agent overwrites it. `page` still holds
-          // the OLD content/provenance here, so saveHistory(page) captures the
-          // pre-agent state tagged 'user'. The agent's new content is
-          // snapshotted later by the debounced PAGE_HISTORY job ('agent'). Skip
-          // if the prior state is already agent-authored (boundary already
-          // pinned on the user->agent transition), if the page is effectively
-          // empty, or if the latest existing snapshot already equals this human
-          // state (avoid duplicates).
+          // #370 — boundary snapshot on ANY source transition. When the store
+          // flips the page's provenance (user↔agent↔git), pin the OUTGOING
+          // state as its own history version BEFORE the incoming source
+          // overwrites it. `page` still holds the OLD content/provenance here,
+          // so saveHistory(page) captures the pre-transition state tagged with
+          // its own source, kind='boundary'. The incoming content is snapshotted
+          // later by the debounced idle job. Skip if the page is effectively
+          // empty or if the latest existing snapshot already equals this state
+          // (the shared isDeepStrictEqual gate — avoids duplicates). Generalizing
+          // beyond the old user→agent special-case also covers git-sync for free.
          if (
-            lastUpdatedSource === 'agent' &&
-            page.lastUpdatedSource !== 'agent'
+            page.lastUpdatedSource &&
+            page.lastUpdatedSource !== lastUpdatedSource
          ) {
            // pageHistory.pageId is uuid-typed; use page.id (never the doc-name
            // slugId) so a `page.<slugId>` doc cannot throw 22P02 here (#260).
@@ -347,15 +367,13 @@ export class PersistenceExtension implements Extension {
              page.id,
              { includeContent: true, trx },
            );
-            const humanBaselineMissing =
+            const baselineMissing =
              !lastHistory ||
              !isDeepStrictEqual(lastHistory.content, page.content);
-            if (
-              !isEmptyParagraphDoc(page.content as any) &&
-              humanBaselineMissing
-            ) {
+            if (!isEmptyParagraphDoc(page.content as any) && baselineMissing) {
              await this.pageHistoryRepo.saveHistory(page, {
                contributorIds: page.contributorIds ?? undefined,
+                kind: 'boundary',
                trx,
              });
            }
@@ -480,6 +498,14 @@ export class PersistenceExtension implements Extension {
      return; // unrelated / malformed stateless message
    }

+    // #370 — explicit "save a version" (human Cmd+S / agent save tool). Edit
+    // rights are already enforced by the readOnly reject above (a reader can't
+    // create a version), exactly as intentional-clear requires.
+    if (message?.type === SAVE_VERSION_MESSAGE_TYPE) {
+      await this.handleSaveVersion(data);
+      return;
+    }
+
    if (message?.type !== INTENTIONAL_CLEAR_MESSAGE_TYPE) return;

    this.intentionalClear.set(
@@ -488,6 +514,117 @@ export class PersistenceExtension implements Extension {
    );
  }

+  /**
+   * #370 — persist an intentional version from the live in-memory ydoc.
+   *
+   * One stateless path serves BOTH the human and the agent; the tier is derived
+   * SERVER-SIDE from the signed connection actor ('agent' → 'agent', anything
+   * else → 'manual'), so the version type cannot be spoofed by the client. We
+   * take the fresh ydoc from the collab process memory and run it through the
+   * EXISTING store path first (so pages.content/ydoc reflect the exact content
+   * being versioned — a REST endpoint would race the up-to-10s-stale page row),
+   * then snapshot it into page_history with the intentional kind.
+   *
+   * Promote-not-dup: if the latest history row already holds this exact content
+   * and it is an autosave (idle/boundary/legacy-null), upgrade its kind in place
+   * instead of duplicating a heavy content row; if it is already 'manual', it is
+   * a no-op (the client shows an "already saved" toast). Otherwise a fresh
+   * version row is written, popping the aggregated contributors from Redis.
+   */
+  private async handleSaveVersion(data: onStatelessPayload): Promise<void> {
+    const { connection, document, documentName } = data;
+    const context = connection?.context;
+    const pageId = getPageId(documentName);
+    // Unforgeable: 'agent' only for a signed agent connection, else 'manual'.
+    const kind: PageHistoryKind =
+      context?.actor === 'agent' ? 'agent' : 'manual';
+
+    // Flush the live ydoc through the normal store path so the page row + ydoc
+    // hold exactly what we are about to version (also fires the idle enqueue we
+    // supersede below, plus any source-transition boundary). onStoreDocument
+    // only needs document/documentName/context.
+    await this.onStoreDocument({
+      document,
+      documentName,
+      context,
+    } as onStoreDocumentPayload);
+
+    let result:
+      | { historyId: string; kind: PageHistoryKind; alreadySaved: boolean }
+      | undefined;
+
+    await executeTx(this.db, async (trx) => {
+      const page = await this.pageRepo.findById(pageId, {
+        withLock: true,
+        includeContent: true,
+        trx,
+      });
+      if (!page) return;
+      // Never version an effectively-empty page (mirrors the processor's
+      // first-history guard); there is nothing intentional to pin.
+      if (isEmptyParagraphDoc(page.content as any)) return;
+
+      const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
+        page.id,
+        { includeContent: true, trx },
+      );
+
+      if (
+        lastHistory &&
+        isDeepStrictEqual(lastHistory.content, page.content)
+      ) {
+        // Content is already snapshotted. Promote-not-dup.
+        if (lastHistory.kind === 'manual') {
+          result = {
+            historyId: lastHistory.id,
+            kind: 'manual',
+            alreadySaved: true,
+          };
+          return;
+        }
+        await this.pageHistoryRepo.updateHistoryKind(
+          lastHistory.id,
+          kind,
+          trx,
+        );
+        result = { historyId: lastHistory.id, kind, alreadySaved: false };
+        return;
+      }
+
+      // Fresh version row. Pop the contributors aggregated since the last
+      // snapshot (SPOP); restore them if the write fails so they aren't lost.
+      const contributorIds = await this.collabHistory.popContributors(page.id);
+      try {
+        const saved = await this.pageHistoryRepo.saveHistory(page, {
+          contributorIds,
+          kind,
+          trx,
+        });
+        result = { historyId: saved.id, kind, alreadySaved: false };
+      } catch (err) {
+        await this.collabHistory.addContributors(page.id, contributorIds);
+        throw err;
+      }
+    });
+
+    // Housekeeping: this explicit version supersedes the page's pending idle
+    // autosnapshot, so cancel it (delayed job → remove() just deletes it) and
+    // end the current idle burst so the next edit starts a fresh max-wait window.
+    await this.historyQueue.remove(pageId).catch(() => undefined);
+    this.idleBurstStart.delete(pageId);
+
+    if (result) {
+      document.broadcastStateless(
+        JSON.stringify({
+          type: 'version.saved',
+          historyId: result.historyId,
+          kind: result.kind,
+          alreadySaved: result.alreadySaved,
+        }),
+      );
+    }
+  }
+
  async onChange(data: onChangePayload) {
    const documentName = data.documentName;
    const userId = data.context?.user?.id;
@@ -545,17 +682,45 @@ export class PersistenceExtension implements Extension {
    page: Page,
    lastUpdatedSource: string,
  ): Promise<void> {
-    // Job id + delay arithmetic lives in the pure `computeHistoryJob` (see its
-    // doc comment for the agent-delay-0 / age-based-debounce invariants).
+    // #370 — trailing idle debounce with a max-wait ceiling. One pending idle
+    // job per page (jobId = page.id); on every store we remove the pending
+    // delayed job and re-add it, so the snapshot lands `delay` after edits go
+    // quiet rather than once per store (precedent: workspace.service.ts).
+    // remove() on a delayed job simply deletes it (0 if absent, no throw); if the
+    // job is already ACTIVE and the remove is a no-op, the add still de-dups and
+    // the processor's isDeepStrictEqual gate collapses the duplicate content.
+    //
+    // The FIRST arm of a burst records `burstStart`; computeHistoryJob shrinks
+    // the delay to the remaining max-wait budget from that point, so a continuous
+    // session cannot re-arm the trailing timer forever and starve the snapshot.
+    // A burst marker older than THIS TIER's max-wait means the previous idle job
+    // has already fired — start a fresh window instead of firing immediately on
+    // the next edit. Must use the SAME source-specific max-wait computeHistoryJob
+    // uses (agent 5m / user 10m): a hardcoded USER ceiling would leave an agent
+    // burst's marker stale for 5..10m, forcing delay=0 on every store in that
+    // window and writing one idle row per store — exactly the per-store bloat the
+    // debounce exists to prevent, on the continuous-agent path.
+    const maxWait =
+      lastUpdatedSource === 'agent' ? IDLE_MAX_WAIT_AGENT : IDLE_MAX_WAIT_USER;
+    const now = Date.now();
+    let burstStart = this.idleBurstStart.get(page.id);
+    if (burstStart === undefined || now - burstStart >= maxWait) {
+      burstStart = now;
+      this.idleBurstStart.set(page.id, burstStart);
+    }
+
    const { jobId, delay } = computeHistoryJob(
      page,
      lastUpdatedSource,
-      Date.now(),
+      burstStart,
+      now,
    );

+    await this.historyQueue.remove(jobId).catch(() => undefined);
+
    await this.historyQueue.add(
      QueueJob.PAGE_HISTORY,
-      { pageId: page.id } as IPageHistoryJob,
+      { pageId: page.id, kind: 'idle' } as IPageHistoryJob,
      { jobId, delay },
    );
  }
@@ -66,6 +66,15 @@ describe('HistoryProcessor.process', () => {
    notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
    generalQueue = { add: jest.fn().mockResolvedValue(undefined) };

+    // #370 F3 — the processor now serializes its find+save under a page-row lock
+    // via executeTx. A db whose transaction().execute(fn) runs fn with a trx stub
+    // drives the real executeTx() helper without a database.
+    const db = {
+      transaction: () => ({
+        execute: (fn: (trx: any) => Promise<any>) => fn({ __trx: true }),
+      }),
+    };
+
    // WorkerHost's constructor reads `this.worker`; passing repos positionally
    // matches the constructor and avoids the Nest DI container.
    proc = new HistoryProcessor(
@@ -73,6 +82,7 @@ describe('HistoryProcessor.process', () => {
      pageRepo as any,
      collabHistory as any,
      watcherService as any,
+      db as any,
      notificationQueue as any,
      generalQueue as any,
    );
@@ -126,15 +136,26 @@ describe('HistoryProcessor.process', () => {
    await proc.process(buildJob());

    expect(collabHistory.popContributors).toHaveBeenCalledWith(PAGE_ID);
+    // #370 F3/F9 — the snapshot decision runs under a page-row lock. Pin the lock
+    // structurally so a refactor that drops withLock/trx (silently reintroducing
+    // the TOCTOU double-insert) turns this red. The tx stub is { __trx: true }.
+    expect(pageRepo.findById).toHaveBeenCalledWith(
+      PAGE_ID,
+      expect.objectContaining({ withLock: true, trx: { __trx: true } }),
+    );
+    // #370 F7 — addPageWatchers MUST receive the trx, or its FK-check runs on a
+    // separate connection and self-deadlocks against our FOR UPDATE. Asserting
+    // the trx arg here is exactly what would have caught that regression.
    expect(watcherService.addPageWatchers).toHaveBeenCalledWith(
      ['u1', 'u2'],
      PAGE_ID,
      SPACE_ID,
      WORKSPACE_ID,
+      { __trx: true },
    );
    expect(pageHistoryRepo.saveHistory).toHaveBeenCalledWith(
      expect.objectContaining({ id: PAGE_ID }),
-      { contributorIds: ['u1', 'u2'] },
+      { contributorIds: ['u1', 'u2'], kind: 'idle', trx: { __trx: true } },
    );
    expect(generalQueue.add).toHaveBeenCalledWith(
      QueueJob.PAGE_BACKLINKS,
@@ -186,6 +207,48 @@ describe('HistoryProcessor.process', () => {
    ]);
  });

+  it('COMMIT failure (throw outside the tx callback) → contributors RESTORED', async () => {
+    // #370 F8 — a commit-time failure throws OUTSIDE the callback, so the inner
+    // try/catch does not run; the outer catch must restore the popped set (else a
+    // BullMQ retry writes an unattributed version). Use a db whose execute() runs
+    // the callback THEN throws, simulating a commit abort.
+    pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+      content: { type: 'doc', content: [] },
+    });
+    const commitFail = {
+      transaction: () => ({
+        execute: async (fn: (trx: any) => Promise<any>) => {
+          await fn({ __trx: true }); // callback succeeds (saveHistory ok)
+          throw new Error('commit aborted'); // ...but the COMMIT fails
+        },
+      }),
+    };
+    const procCommitFail = new HistoryProcessor(
+      pageHistoryRepo as any,
+      pageRepo as any,
+      collabHistory as any,
+      watcherService as any,
+      commitFail as any,
+      notificationQueue as any,
+      generalQueue as any,
+    );
+    jest
+      .spyOn(procCommitFail['logger'], 'error')
+      .mockImplementation(() => undefined);
+
+    await expect(procCommitFail.process(buildJob())).rejects.toThrow(
+      'commit aborted',
+    );
+    // The inner catch did NOT run (save succeeded), so only the outer catch can
+    // restore — assert it did.
+    expect(collabHistory.addContributors).toHaveBeenCalledWith(PAGE_ID, [
+      'u1',
+      'u2',
+    ]);
+    // And the post-snapshot queue work must NOT have run (we rethrew).
+    expect(generalQueue.add).not.toHaveBeenCalled();
+  });
+
  it('backlinks + notification queue failures are swallowed (history still committed)', async () => {
    pageHistoryRepo.findPageLastHistory.mockResolvedValue({
      content: { type: 'doc', content: [] },
@@ -19,6 +19,9 @@ import { isDeepStrictEqual } from 'node:util';
 import { CollabHistoryService } from '../services/collab-history.service';
 import { WatcherService } from '../../core/watcher/watcher.service';
 import { isEmptyParagraphDoc } from '../collaboration.util';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { executeTx } from '@docmost/db/utils';

@Processor(QueueName.HISTORY_QUEUE)
 export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
@@ -29,6 +32,7 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
    private readonly pageRepo: PageRepo,
    private readonly collabHistory: CollabHistoryService,
    private readonly watcherService: WatcherService,
+    @InjectKysely() private readonly db: KyselyDB,
    @InjectQueue(QueueName.NOTIFICATION_QUEUE) private notificationQueue: Queue,
    @InjectQueue(QueueName.GENERAL_QUEUE) private generalQueue: Queue,
  ) {
@@ -41,6 +45,9 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
    try {
      const { pageId } = job.data;

+      // Read the page WITHOUT a lock first, only to bail early on the two cheap
+      // no-write cases (page gone / empty first snapshot) without opening a
+      // transaction. The authoritative check-then-write happens locked below.
      const page = await this.pageRepo.findById(pageId, {
        includeContent: true,
      });
@@ -51,40 +58,109 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
        return;
      }

-      const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
-        pageId,
-        { includeContent: true },
-      );
+      // #370 F3 — the snapshot decision (findPageLastHistory → saveHistory) must
+      // be serialized against manual-save/boundary writers, which run under a
+      // page-row lock in onStoreDocument. Without it, this processor and a
+      // concurrent manual-save each read the same lastHistory (MVCC), both see
+      // content != lastHistory, and both insert — producing two page_history rows
+      // with IDENTICAL content (one 'idle', one 'manual'), defeating
+      // promote-not-dup and the version-vs-autosave split. Taking the same
+      // page-row lock makes the second writer observe the first's committed row so
+      // the isDeepStrictEqual gate collapses the duplicate. Only the read+write
+      // is transacted; the post-snapshot queue work stays outside.
+      let contributorIds: string[] = [];
+      let snapshotWritten = false;
+      let lastHistoryContent: unknown;
+      // #370 F8 — the contributor set popped from Redis (destructive SPOP) must be
+      // restored if the snapshot does not durably land. The inner try/catch only
+      // covers a throw INSIDE the callback; a COMMIT failure (connection drop,
+      // serialization/deadlock abort on commit — the transient class the epic
+      // already retries) throws OUTSIDE it, rolling the snapshot back while the
+      // pop is already gone. We track the popped set here and restore it in the
+      // outer catch so a BullMQ retry re-attributes the version. addContributors
+      // is an idempotent Redis SADD, so a double-restore is harmless.
+      let poppedForRestore: string[] = [];

-      if (!lastHistory && isEmptyParagraphDoc(page.content as any)) {
-        this.logger.debug(
-          `Skipping first history for page ${pageId}: empty content`,
-        );
-        await this.collabHistory.clearContributors(pageId);
+      try {
+        await executeTx(this.db, async (trx) => {
+          const lockedPage = await this.pageRepo.findById(pageId, {
+            includeContent: true,
+            withLock: true,
+            trx,
+          });
+          if (!lockedPage) return;
+
+          const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
+            pageId,
+            { includeContent: true, trx },
+          );
+          lastHistoryContent = lastHistory?.content;
+
+          if (!lastHistory && isEmptyParagraphDoc(lockedPage.content as any)) {
+            this.logger.debug(
+              `Skipping first history for page ${pageId}: empty content`,
+            );
+            return;
+          }
+
+          if (
+            lastHistory &&
+            isDeepStrictEqual(lastHistory.content, lockedPage.content)
+          ) {
+            return; // already snapshotted at this content — nothing to write
+          }
+
+          contributorIds = await this.collabHistory.popContributors(pageId);
+          poppedForRestore = contributorIds;
+          try {
+            // Pass `trx` so the watcher insert's FK check (FOR KEY SHARE on
+            // pages[pageId]) runs on the SAME connection that already holds the
+            // FOR UPDATE lock from findById — otherwise it takes the FK lock on a
+            // separate pool connection and self-deadlocks against our own tx.
+            await this.watcherService.addPageWatchers(
+              contributorIds,
+              pageId,
+              lockedPage.spaceId,
+              lockedPage.workspaceId,
+              trx,
+            );
+
+            // #370 — every job on this queue is a trailing idle-flush autosnapshot.
+            await this.pageHistoryRepo.saveHistory(lockedPage, {
+              contributorIds,
+              kind: job.data.kind ?? 'idle',
+              trx,
+            });
+            snapshotWritten = true;
+            this.logger.debug(`History created for page: ${pageId}`);
+          } catch (err) {
+            await this.collabHistory.addContributors(pageId, contributorIds);
+            poppedForRestore = [];
+            throw err;
+          }
+        });
+      } catch (err) {
+        // A throw here means the tx did NOT commit (callback threw, or the commit
+        // itself failed and rolled back). If we popped contributors and the inner
+        // catch did not already restore them, restore now so the retry keeps
+        // attribution. snapshotWritten is irrelevant: it is set before commit, so
+        // it can be true even when the commit rolled the snapshot back.
+        if (poppedForRestore.length) {
+          await this.collabHistory.addContributors(pageId, poppedForRestore);
+        }
+        throw err;
+      }
+
+      // No snapshot written (page vanished / empty-first / unchanged content) →
+      // clear the contributor set for the skip cases and stop.
+      if (!snapshotWritten) {
+        if (!lastHistoryContent && isEmptyParagraphDoc(page.content as any)) {
+          await this.collabHistory.clearContributors(pageId);
+        }
        return;
      }

-      if (
-        !lastHistory ||
-        !isDeepStrictEqual(lastHistory.content, page.content)
-      ) {
-        const contributorIds = await this.collabHistory.popContributors(pageId);
-
-        try {
-          await this.watcherService.addPageWatchers(
-            contributorIds,
-            pageId,
-            page.spaceId,
-            page.workspaceId,
-          );
-
-          await this.pageHistoryRepo.saveHistory(page, { contributorIds });
-          this.logger.debug(`History created for page: ${pageId}`);
-        } catch (err) {
-          await this.collabHistory.addContributors(pageId, contributorIds);
-          throw err;
-        }
-
+      {
        const mentions = extractMentions(page.content);
        const pageMentions = extractPageMentions(mentions);
        const internalLinkSlugIds = extractInternalLinkSlugIds(page.content);
@@ -102,7 +178,7 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
            );
          });

-        if (contributorIds.length > 0 && lastHistory?.content) {
+        if (contributorIds.length > 0 && lastHistoryContent) {
          await this.notificationQueue
            .add(QueueJob.PAGE_UPDATED, {
              pageId,
@@ -610,6 +610,63 @@ describe('AiAgentRolesService guards', () => {
      expect(repo.insert.mock.calls[0][0].name).toBe('Researcher (2)');
    });

+    it('createdRoles lists the installed role (no renamedTo when not renamed)', async () => {
+      const { service } = makeImportService({});
+      const res = await service.importFromCatalog('ws-1', 'u1', dto());
+      expect(res.createdRoles).toEqual([
+        { slug: 'researcher', name: 'Researcher' },
+      ]);
+      expect(res.skippedRoles).toEqual([]);
+    });
+
+    it('createdRoles carries renamedTo on a rename', async () => {
+      const existing = [makeRow({ id: 'r-x', name: 'Researcher' })];
+      const { service } = makeImportService({ existing });
+      const res = await service.importFromCatalog(
+        'ws-1',
+        'u1',
+        dto({ conflict: 'rename' }),
+      );
+      expect(res.createdRoles).toEqual([
+        { slug: 'researcher', name: 'Researcher', renamedTo: 'Researcher (2)' },
+      ]);
+      expect(res.skippedRoles).toEqual([]);
+    });
+
+    it('skippedRoles: already-installed slug carries reason "already-installed"', async () => {
+      const existing = [
+        makeRow({
+          id: 'r-existing',
+          name: 'Old researcher',
+          source: { slug: 'researcher', language: 'en', version: 1 } as never,
+        }),
+      ];
+      const { service } = makeImportService({ existing });
+      const res = await service.importFromCatalog('ws-1', 'u1', dto());
+      expect(res.skippedRoles).toEqual([
+        {
+          slug: 'researcher',
+          name: 'Researcher',
+          reason: 'already-installed',
+        },
+      ]);
+      expect(res.createdRoles).toEqual([]);
+    });
+
+    it('skippedRoles: a name collision under conflict:skip carries reason "name-conflict"', async () => {
+      const existing = [makeRow({ id: 'r-x', name: 'Researcher' })];
+      const { service } = makeImportService({ existing });
+      const res = await service.importFromCatalog(
+        'ws-1',
+        'u1',
+        dto({ conflict: 'skip' }),
+      );
+      expect(res.skippedRoles).toEqual([
+        { slug: 'researcher', name: 'Researcher', reason: 'name-conflict' },
+      ]);
+      expect(res.createdRoles).toEqual([]);
+    });
+
    it('dto.slugs filters; an unknown slug becomes an error entry', async () => {
      const { service, repo } = makeImportService({
        bundleRoles: [catalogRole()],
@@ -677,6 +734,15 @@ describe('AiAgentRolesService guards', () => {
      // 'a' converged on the concurrent install (skip); 'b' imported; no errors.
      expect(res).toMatchObject({ created: 1, skipped: 1, renamed: 0 });
      expect(res.errors).toEqual([]);
+      // The per-role list records 'a' as an already-installed skip (the UI reads
+      // skippedRoles, not the counter, to render its plaque — assert the array,
+      // not just the count).
+      expect(res.skippedRoles).toContainEqual({
+        slug: 'a',
+        name: 'A',
+        reason: 'already-installed',
+      });
+      expect(res.createdRoles.map((r) => r.slug)).toEqual(['b']);
      // Both inserts were attempted (the batch did not abort on the 23505).
      expect(repo.insert).toHaveBeenCalledTimes(2);
    });
@@ -305,6 +305,16 @@ export class AiAgentRolesService {
    skipped: number;
    renamed: number;
    errors: { slug: string; message: string }[];
+    // Per-role lists alongside the counters (kept for back-compat). The redesigned
+    // catalog UI needs the actual roles — which were created (and any rename) and
+    // which were skipped and why — to render an inline result plaque with the
+    // conflicting role's name and a "Rename & install" affordance.
+    createdRoles: { slug: string; name: string; renamedTo?: string }[];
+    skippedRoles: {
+      slug: string;
+      name: string;
+      reason: 'name-conflict' | 'already-installed';
+    }[];
  }> {
    const { file, versions } = await this.loadBundleById(
      dto.bundleId,
@@ -312,6 +322,13 @@ export class AiAgentRolesService {
    );

    const errors: { slug: string; message: string }[] = [];
+    const createdRoles: { slug: string; name: string; renamedTo?: string }[] =
+      [];
+    const skippedRoles: {
+      slug: string;
+      name: string;
+      reason: 'name-conflict' | 'already-installed';
+    }[] = [];

    // Resolve the selected catalog roles (honor dto.slugs; flag unknown ones).
    let selected = file.roles;
@@ -351,16 +368,27 @@ export class AiAgentRolesService {
      // Already installed from the catalog in THIS language => skip (use
      // update-from-catalog). A different language of the same slug still imports.
      const installKey = `${role.slug}:${dto.language}`;
+      const originalName = role.name.trim();
      if (installedKeys.has(installKey)) {
        skipped++;
+        skippedRoles.push({
+          slug: role.slug,
+          name: originalName,
+          reason: 'already-installed',
+        });
        continue;
      }

-      let name = role.name.trim();
+      let name = originalName;
      let didRename = false;
      if (takenNames.has(name.toLowerCase())) {
        if (dto.conflict === 'skip') {
          skipped++;
+          skippedRoles.push({
+            slug: role.slug,
+            name: originalName,
+            reason: 'name-conflict',
+          });
          continue;
        }
        // conflict === 'rename': find a free " (N)" suffix.
@@ -380,6 +408,11 @@ export class AiAgentRolesService {
        });
        created++;
        if (didRename) renamed++;
+        createdRoles.push({
+          slug: role.slug,
+          name: originalName,
+          ...(didRename ? { renamedTo: name } : {}),
+        });
        takenNames.add(name.toLowerCase());
        installedKeys.add(installKey);
      } catch (err) {
@@ -391,6 +424,11 @@ export class AiAgentRolesService {
        // skipped (already installed) and continue; do NOT abort or error.
        if (isSourceUniqueViolation(err)) {
          skipped++;
+          skippedRoles.push({
+            slug: role.slug,
+            name: originalName,
+            reason: 'already-installed',
+          });
          installedKeys.add(installKey);
          continue;
        }
@@ -407,7 +445,7 @@ export class AiAgentRolesService {
      }
    }

-    return { created, skipped, renamed, errors };
+    return { created, skipped, renamed, errors, createdRoles, skippedRoles };
  }

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

-      getPage: tool({
-        description:
-          'Fetch a single page as Markdown by its page id. Returns the page ' +
-          'title and its Markdown content. Inline <span data-comment-id> tags ' +
-          'in the markdown are comment highlight anchors (also present for ' +
-          'RESOLVED threads) — treat them as markup, not page text.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id (or slugId) of the page.'),
-        }),
-        execute: async ({ pageId }) => {
-          // getPage(pageId) -> { data: filterPage(page, markdown), success }.
-          const result = await client.getPage(pageId);
-          const data = (result?.data ?? {}) as {
-            title?: string;
-            content?: string;
-          };
-          return {
-            title: data.title ?? '',
-            markdown: typeof data.content === 'string' ? data.content : '',
-          };
-        },
+      // 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) ---

-      createPage: tool({
-        description:
-          'Create a new page with a Markdown body in a space, optionally under ' +
-          'a parent page. Returns the new page id and title. Reversible: a page ' +
-          'can be moved to trash later.',
-        inputSchema: modelFriendlyInput({
-          title: z.string().describe('The title of the new page.'),
-          content: z
-            .string()
-            .describe('The page body as Markdown (may be empty).'),
-          spaceId: z
-            .string()
-            .describe('The id of the space to create the page in.'),
-          parentPageId: z
-            .string()
-            .optional()
-            .describe('Optional parent page id to nest the new page under.'),
-        }),
-        execute: async ({ title, content, spaceId, parentPageId }) => {
+      // 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(
@@ -375,7 +352,7 @@ export class AiChatToolsService {
          };
          return { id: data.id ?? data.slugId, title: data.title ?? title };
        },
-      }),
+      ),

      updatePageContent: tool({
        description:
@@ -399,115 +376,46 @@ export class AiChatToolsService {
        },
      }),

-      renamePage: tool({
-        description:
-          "Rename a page (change its title only; the body is untouched). " +
-          'Reversible: rename back at any time.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page to rename.'),
-          title: z.string().describe('The new title.'),
-        }),
-        execute: async ({ pageId, title }) => {
+      // 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 };
        },
-      }),
+      ),

-      movePage: tool({
-        description:
-          'Move a page under a new parent page, or to the space root when no ' +
-          'parent is given. Reversible: move it back at any time.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page to move.'),
-          parentPageId: z
-            .string()
-            .nullable()
-            .optional()
-            .describe(
-              'Target parent page id. Null/omitted moves the page to the ' +
-                'space root.',
-            ),
-        }),
-        execute: async ({ pageId, parentPageId }) => {
+      // 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);
+          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 };
      }),

-      deletePage: tool({
-        description:
-          'Move a page to the trash (SOFT delete only — fully reversible; the ' +
-          'page can be restored from trash). This NEVER permanently deletes.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page to move to trash.'),
-        }),
-        // GUARDRAIL (§14 H4): the only field ever passed to the client is
-        // pageId. permanentlyDelete/forceDelete are not part of the schema and
-        // are never forwarded, so the agent physically cannot permanently
-        // delete a page through this tool.
-        execute: async ({ pageId }) => {
-          // deletePage(pageId) hits POST /pages/delete with { pageId } only,
-          // which is the soft-delete (trash) path on the server.
-          await client.deletePage(pageId);
-          return { pageId, trashed: true };
-        },
-      }),
-
-      // INTENTIONAL per-transport divergence (not shared): the description is
-      // tuned for the in-app agent (e.g. "retry with a corrected EXACT selection"
-      // and "Reversible via the comment UI"); the standalone MCP `create_comment`
-      // keeps its own wording. Kept per-layer.
-      createComment: tool({
-        description:
-          'Add an INLINE comment to a page, or reply to an existing top-level ' +
-          'comment (one level only — the backend rejects replies to replies). ' +
-          'The comment is anchored inline to the given exact `selection` text ' +
-          '(which gets highlighted); page-level comments are NOT supported. A ' +
-          "new top-level comment REQUIRES a `selection`. Replies inherit the " +
-          "parent's anchor and take no selection. If the call fails with a " +
-          '"selection not found" error, retry with a corrected EXACT selection ' +
-          'copied verbatim from a single paragraph/block. You may also attach a ' +
-          '`suggestedText` proposing a replacement for the `selection` (a human ' +
-          'applies it from the UI); when set, the `selection` must occur exactly ' +
-          'once in the page. Reversible via the comment UI.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page to comment on.'),
-          content: z.string().describe('The comment body as Markdown.'),
-          selection: z
-            .string()
-            .min(1)
-            .max(250)
-            .optional()
-            .describe(
-              'EXACT contiguous text from a SINGLE paragraph/block to anchor ' +
-                '(highlight) the comment on (<=250 chars, avoid spanning across ' +
-                'formatting boundaries). Required for a new top-level comment; ' +
-                'omit only when replying via parentCommentId.',
-            ),
-          parentCommentId: z
-            .string()
-            .optional()
-            .describe(
-              'Optional id of a TOP-LEVEL comment to reply to (one level ' +
-                'of replies only).',
-            ),
-          suggestedText: z
-            .string()
-            .min(1)
-            .max(2000)
-            .optional()
-            .describe(
-              'Optional proposed replacement (PLAIN TEXT) for the `selection`, ' +
-                'applied by a human via the UI (never auto-applied). REQUIRES a ' +
-                '`selection`; NOT allowed on a reply. When set, the `selection` ' +
-                'must be UNIQUE in the page — expand it with surrounding context ' +
-                '(still <=250 chars) if it occurs more than once, or the call is ' +
-                'refused.',
-            ),
-        }),
-        execute: async ({
+      // 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,
@@ -548,26 +456,17 @@ export class AiChatToolsService {
          const data = (result?.data ?? {}) as { id?: string };
          return { commentId: data.id, pageId };
        },
-      }),
+      ),

-      resolveComment: tool({
-        description:
-          'Resolve or reopen a top-level comment thread (reversible — toggle ' +
-          'the resolved flag). Only top-level comments can be resolved.',
-        inputSchema: modelFriendlyInput({
-          commentId: z
-            .string()
-            .describe('The id of the top-level comment to resolve/reopen.'),
-          resolved: z
-            .boolean()
-            .describe('true to resolve the thread, false to reopen it.'),
-        }),
-        execute: async ({ commentId, resolved }) => {
+      // 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) ---

@@ -585,33 +484,12 @@ export class AiChatToolsService {
      // hierarchy mode but is worded for the in-app agent; the standalone MCP
      // `list_pages` carries its own wording. Kept per-layer so each side tunes
      // its own guidance.
-      listPages: tool({
-        description:
-          'List the most recent pages, optionally scoped to a single space. ' +
-          'Returns a bounded list (default 50, max 100). Pass tree:true (with ' +
-          "spaceId) to instead get the space's full page hierarchy as a nested tree.",
-        inputSchema: modelFriendlyInput({
-          spaceId: z
-            .string()
-            .optional()
-            .describe('Optional space id to scope the listing to.'),
-          limit: z
-            .number()
-            .int()
-            .min(1)
-            .max(100)
-            .optional()
-            .describe('Maximum number of pages (1-100).'),
-          tree: z
-            .boolean()
-            .optional()
-            .describe(
-              'When true, return the full page hierarchy of the given space as a nested tree (children arrays) instead of the recent-pages flat list. Requires spaceId; ignores limit.',
-            ),
-        }),
-        execute: async ({ spaceId, limit, tree }) =>
+      // 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:
@@ -656,41 +534,34 @@ export class AiChatToolsService {
          }),
      ),

+      // NOT shared (kept inline): the MCP tool name `table_get` is noun-first
+      // while this key is `getTable` (verb-first), breaking the
+      // snake_case(inAppKey) convention the shared registry enforces. Its
+      // reference parameter is still named `table` (was `tableRef`) so it matches
+      // the migrated table row/cell tools below.
      getTable: tool({
        description:
          'Read a table as a matrix of cell texts (plus a parallel cellIds ' +
          'matrix so cells can be addressed for rich edits).',
        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page.'),
-          tableRef: z
+          table: z
            .string()
            .describe(
-              '"#<index>" from getOutline, or a block id of any node inside ' +
-                'the table.',
+              '"#<index>" from the page outline, or a block id of any node ' +
+                'inside the table.',
            ),
        }),
-        execute: async ({ pageId, tableRef }) =>
-          await client.getTable(pageId, tableRef),
+        execute: async ({ pageId, table }) =>
+          await client.getTable(pageId, table),
      }),

-      listComments: tool({
-        description:
-          'List comments on a page in one call. By DEFAULT only ACTIVE ' +
-          'threads are returned; resolved threads (a resolved top-level ' +
-          'comment and all its replies) are hidden and their count reported ' +
-          'as `resolvedThreadsHidden` so you can re-query with ' +
-          '`includeResolved: true` to see everything. Returns ' +
-          '`{ items, resolvedThreadsHidden }`. Content is returned as Markdown.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page.'),
-          includeResolved: z
-            .boolean()
-            .optional()
-            .describe('default only active threads; true — include resolved'),
-        }),
-        execute: async ({ pageId, includeResolved }) =>
+      // 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).',
@@ -700,26 +571,12 @@ export class AiChatToolsService {
        execute: async ({ commentId }) => await client.getComment(commentId),
      }),

-      checkNewComments: tool({
-        description:
-          'Find new comments across a space (optionally scoped to a subtree) ' +
-          'created after a given timestamp.',
-        inputSchema: modelFriendlyInput({
-          spaceId: z.string().describe('The id of the space to scan.'),
-          since: z
-            .string()
-            .describe('An ISO-8601 timestamp; only comments created after it.'),
-          parentPageId: z
-            .string()
-            .optional()
-            .describe(
-              'Optional page id to scope the scan to that page and its ' +
-                'descendants.',
-            ),
-        }),
-        execute: async ({ spaceId, since, parentPageId }) =>
+      // 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,
@@ -749,19 +606,14 @@ export class AiChatToolsService {
          await client.diffPageVersions(pageId, from, to),
      ),

-      exportPageMarkdown: tool({
-        description:
-          'Export a page to a single self-contained Docmost-flavoured ' +
-          'Markdown file (meta + body + comment threads). Lossless round-trip ' +
-          'with importPageMarkdown.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page to export.'),
-        }),
-        execute: async ({ pageId }) => {
+      // 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) ---

@@ -811,28 +663,12 @@ export class AiChatToolsService {
        async ({ pageId, nodeId }) => await client.deleteNode(pageId, nodeId),
      ),

-      updatePageJson: tool({
-        description:
-          "Replace a page's body with a full ProseMirror document — a full " +
-          'overwrite — and/or update its title. Minimal example content: ' +
-          '{"type":"doc","content":[{"type":"paragraph","content":' +
-          '[{"type":"text","text":"Hi"}]}]}. The content arg may be a JSON ' +
-          'object or a JSON string (both accepted). Omit content for a ' +
-          'title-only update. Reversible: the previous version is kept in page ' +
-          'history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page to update.'),
-          content: z
-            .any()
-            .optional()
-            .describe(
-              'Full ProseMirror doc {"type":"doc","content":[...]} (JSON ' +
-                'object or JSON string); omit for a title-only update.',
-            ),
-          title: z.string().optional().describe('Optional new title.'),
-        }),
-        execute: async ({ pageId, content, title }) => {
-          // Parity with the standalone MCP server (index.ts update_page_json):
+      // 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.
@@ -845,66 +681,29 @@ export class AiChatToolsService {
          }
          return await client.updatePageJson(pageId, doc, title);
        },
-      }),
+      ),

-      // NOT in the shared registry: this layer names the table argument
-      // `tableRef`, while the standalone MCP tool names it `table` (index.ts).
-      // Sharing one buildShape would rename a model-facing parameter on one
-      // transport, so the table row/cell tools stay per-layer by design.
-      tableInsertRow: tool({
-        description:
-          'Insert a row of plain-text cells into a table. Reversible via ' +
-          'page history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page.'),
-          tableRef: z
-            .string()
-            .describe('"#<index>" from getOutline, or a block id in the table.'),
-          cells: z.array(z.string()).describe('The cell texts for the row.'),
-          index: z
-            .number()
-            .int()
-            .optional()
-            .describe('0-based insert position (omit/out-of-range to append).'),
-        }),
-        execute: async ({ pageId, tableRef, cells, index }) =>
-          await client.tableInsertRow(pageId, tableRef, cells, index),
-      }),
+      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
+      // The table reference parameter was unified to `table` (was `tableRef`).
+      tableInsertRow: sharedTool(
+        sharedToolSpecs.tableInsertRow,
+        async ({ pageId, table, cells, index }) =>
+          await client.tableInsertRow(pageId, table, cells, index),
+      ),

-      // NOT shared — same `tableRef` (here) vs `table` (MCP) parameter-name
-      // divergence as tableInsertRow.
-      tableDeleteRow: tool({
-        description:
-          'Delete a table row at a 0-based index. Reversible via page history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page.'),
-          tableRef: z
-            .string()
-            .describe('"#<index>" from getOutline, or a block id in the table.'),
-          index: z.number().int().describe('0-based row index to delete.'),
-        }),
-        execute: async ({ pageId, tableRef, index }) =>
-          await client.tableDeleteRow(pageId, tableRef, index),
-      }),
+      // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
+      tableDeleteRow: sharedTool(
+        sharedToolSpecs.tableDeleteRow,
+        async ({ pageId, table, index }) =>
+          await client.tableDeleteRow(pageId, table, index),
+      ),

-      // NOT shared — same `tableRef` (here) vs `table` (MCP) parameter-name
-      // divergence as tableInsertRow.
-      tableUpdateCell: tool({
-        description:
-          'Set the plain-text content of a table cell at [row, col] (0-based). ' +
-          'Reversible via page history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page.'),
-          tableRef: z
-            .string()
-            .describe('"#<index>" from getOutline, or a block id in the table.'),
-          row: z.number().int().describe('0-based row index.'),
-          col: z.number().int().describe('0-based column index.'),
-          text: z.string().describe('The new cell text.'),
-        }),
-        execute: async ({ pageId, tableRef, row, col, text }) =>
-          await client.tableUpdateCell(pageId, tableRef, row, col, text),
-      }),
+      // 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,
@@ -918,25 +717,14 @@ export class AiChatToolsService {
          await client.importPageMarkdown(pageId, markdown),
      ),

-      // INTENTIONAL per-transport divergence (not shared): adds a security
-      // confirmation framing ("Only share when the user explicitly asked, since
-      // this exposes the page to anyone with the link") for the in-app agent; the
-      // standalone MCP `share_page` keeps the plain public-URL wording.
-      sharePage: tool({
-        description:
-          'Make a page PUBLICLY accessible and return its public URL. ' +
-          'Reversible via unsharePage. Only share when the user explicitly ' +
-          'asked, since this exposes the page to anyone with the link.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page to share.'),
-          searchIndexing: z
-            .boolean()
-            .optional()
-            .describe('Allow public search engines to index it (default true).'),
-        }),
-        execute: async ({ pageId, searchIndexing }) =>
+      // 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,
@@ -100,54 +100,26 @@ export const INLINE_TOOL_TIERS: Record<
    tier: 'core',
    catalogLine: 'getCurrentPage — the page the user is currently viewing.',
  },
-  getPage: {
-    tier: 'core',
-    catalogLine: 'getPage — fetch a page as Markdown by its id.',
-  },
-  listPages: {
-    tier: 'core',
-    catalogLine: "listPages — list recent pages, or a space's full page tree.",
-  },
-  listComments: {
-    tier: 'core',
-    catalogLine: 'listComments — list all comments on a page (including resolved).',
-  },
+  // NOTE: getPage and listPages moved to @docmost/mcp's SHARED_TOOL_SPECS
+  // (#294); they carry their own tier ('core') + catalogLine there.
+  // NOTE: createComment, listComments and resolveComment moved to
+  // @docmost/mcp's SHARED_TOOL_SPECS (#294); they carry their own tier +
+  // catalogLine there. getComment stays inline (MCP-only shape divergence is
+  // n/a — it simply has no shared spec).
  getComment: {
    tier: 'core',
    catalogLine: 'getComment — fetch a single comment by id.',
  },
-  createComment: {
-    tier: 'core',
-    catalogLine:
-      'createComment — add an inline comment (optionally with a suggested edit).',
-  },
-  resolveComment: {
-    tier: 'core',
-    catalogLine: 'resolveComment — resolve or reopen a comment thread.',
-  },

  // --- deferred inline ---
-  createPage: {
-    tier: 'deferred',
-    catalogLine: 'createPage — create a new page with a Markdown body in a space.',
-  },
+  // NOTE: createPage, renamePage, movePage, deletePage, updatePageJson and
+  // exportPageMarkdown moved to @docmost/mcp's SHARED_TOOL_SPECS (#294); they
+  // carry their own deferred tier + catalogLine there.
  updatePageContent: {
    tier: 'deferred',
    catalogLine:
      "updatePageContent — replace a page's body (and optionally title) with new Markdown.",
  },
-  renamePage: {
-    tier: 'deferred',
-    catalogLine: "renamePage — change a page's title only (body untouched).",
-  },
-  movePage: {
-    tier: 'deferred',
-    catalogLine: 'movePage — move a page under a new parent or to the space root.',
-  },
-  deletePage: {
-    tier: 'deferred',
-    catalogLine: 'deletePage — move a page to trash (soft delete, reversible).',
-  },
  listSidebarPages: {
    tier: 'deferred',
    catalogLine:
@@ -157,42 +129,21 @@ export const INLINE_TOOL_TIERS: Record<
    tier: 'deferred',
    catalogLine: 'getTable — read a table as a matrix of cell texts and cell ids.',
  },
-  checkNewComments: {
-    tier: 'deferred',
-    catalogLine:
-      'checkNewComments — find comments in a space created after a timestamp.',
-  },
+  // NOTE: tableInsertRow, tableDeleteRow and tableUpdateCell moved to
+  // @docmost/mcp's SHARED_TOOL_SPECS (#294); they carry their own deferred tier +
+  // catalogLine there. getTable stays inline (its MCP name table_get breaks the
+  // snake_case(inAppKey) convention, so it has no shared spec).
+  // NOTE: checkNewComments moved to @docmost/mcp's SHARED_TOOL_SPECS (#294);
+  // it carries its own deferred tier + catalogLine there.
  getPageHistory: {
    tier: 'deferred',
    catalogLine:
      'getPageHistory — fetch one page-history version with its ProseMirror content.',
  },
-  exportPageMarkdown: {
-    tier: 'deferred',
-    catalogLine:
-      'exportPageMarkdown — export a page to self-contained Markdown (body + comments).',
-  },
-  updatePageJson: {
-    tier: 'deferred',
-    catalogLine:
-      "updatePageJson — overwrite a page's body with a full ProseMirror document.",
-  },
-  tableInsertRow: {
-    tier: 'deferred',
-    catalogLine: 'tableInsertRow — insert a row of plain-text cells into a table.',
-  },
-  tableDeleteRow: {
-    tier: 'deferred',
-    catalogLine: 'tableDeleteRow — delete a table row at a 0-based index.',
-  },
-  tableUpdateCell: {
-    tier: 'deferred',
-    catalogLine: 'tableUpdateCell — set the text of a table cell at [row, col].',
-  },
-  sharePage: {
-    tier: 'deferred',
-    catalogLine: 'sharePage — make a page publicly accessible and return its URL.',
-  },
+  // NOTE: sharePage moved to @docmost/mcp's SHARED_TOOL_SPECS (#294); it carries
+  // its own deferred tier + catalogLine there. transformPage stays inline (its
+  // schema deliberately diverges — it omits the deleteComments field the MCP
+  // docmost_transform exposes, a comment-deletion guardrail).
  transformPage: {
    tier: 'deferred',
    catalogLine: "transformPage — run a sandboxed JS transform over a page's document.",
@@ -52,7 +52,9 @@ import {
  INTERNAL_LINK_REGEX,
  extractPageSlugId,
 } from '../../../integrations/export/utils';
-import { markdownToHtml, canonicalizeFootnotes } from '@docmost/editor-ext';
+import { canonicalizeFootnotes } from '@docmost/editor-ext';
+import { markdownToProseMirror } from '@docmost/prosemirror-markdown';
+import { normalizeForeignMarkdown } from '../../../integrations/import/utils/foreign-markdown';
 import { WatcherService } from '../../watcher/watcher.service';
 import { sql } from 'kysely';
 import { TransclusionService } from '../transclusion/transclusion.service';
@@ -1301,8 +1303,14 @@ export class PageService {

    switch (format) {
      case 'markdown': {
-        const html = await markdownToHtml(content as string);
-        prosemirrorJson = htmlToJson(html as string);
+        // Canonical markdown -> ProseMirror JSON directly via
+        // `@docmost/prosemirror-markdown` (issue #345) — no HTML intermediate,
+        // no editor-ext markdown layer. Foreign markdown surfaces the strict
+        // parser rejects (GFM `[^id]` reference footnotes) are normalized to the
+        // canonical inline form first.
+        prosemirrorJson = await markdownToProseMirror(
+          normalizeForeignMarkdown(content as string),
+        );
        break;
      }
      case 'html': {
@@ -4,7 +4,6 @@ import { EventName } from '../../common/events/event.contants';
 import { InjectQueue } from '@nestjs/bullmq';
 import { QueueJob, QueueName } from '../../integrations/queue/constants';
 import { Queue } from 'bullmq';
-import { EnvironmentService } from '../../integrations/environment/environment.service';

 /**
 * Thin snapshot of a page node carried inside domain events so the WebSocket
@@ -112,48 +111,24 @@ export class PageListener {
  private readonly logger = new Logger(PageListener.name);

  constructor(
-    private readonly environmentService: EnvironmentService,
-    @InjectQueue(QueueName.SEARCH_QUEUE) private searchQueue: Queue,
    @InjectQueue(QueueName.AI_QUEUE) private aiQueue: Queue,
  ) {}

  @OnEvent(EventName.PAGE_CREATED)
  async handlePageCreated(event: PageEvent) {
    const { pageIds, workspaceId } = event;
-    if (this.isTypesense()) {
-      await this.searchQueue.add(QueueJob.PAGE_CREATED, {
-        pageIds,
-      });
-    }
-
    await this.aiQueue.add(QueueJob.PAGE_CREATED, { pageIds, workspaceId });
  }

-  @OnEvent(EventName.PAGE_UPDATED)
-  async handlePageUpdated(event: PageEvent) {
-    const { pageIds } = event;
-
-    await this.searchQueue.add(QueueJob.PAGE_UPDATED, { pageIds });
-  }
-
  @OnEvent(EventName.PAGE_DELETED)
  async handlePageDeleted(event: PageEvent) {
    const { pageIds, workspaceId } = event;
-    if (this.isTypesense()) {
-      await this.searchQueue.add(QueueJob.PAGE_DELETED, { pageIds });
-    }
-
    await this.aiQueue.add(QueueJob.PAGE_DELETED, { pageIds, workspaceId });
  }

  @OnEvent(EventName.PAGE_SOFT_DELETED)
  async handlePageSoftDeleted(event: PageEvent) {
    const { pageIds, workspaceId } = event;
-
-    if (this.isTypesense()) {
-      await this.searchQueue.add(QueueJob.PAGE_SOFT_DELETED, { pageIds });
-    }
-
    await this.aiQueue.add(QueueJob.PAGE_SOFT_DELETED, {
      pageIds,
      workspaceId,
@@ -163,14 +138,6 @@ export class PageListener {
  @OnEvent(EventName.PAGE_RESTORED)
  async handlePageRestored(event: PageEvent) {
    const { pageIds, workspaceId } = event;
-    if (this.isTypesense()) {
-      await this.searchQueue.add(QueueJob.PAGE_RESTORED, { pageIds });
-    }
-
    await this.aiQueue.add(QueueJob.PAGE_RESTORED, { pageIds, workspaceId });
  }
-
-  isTypesense(): boolean {
-    return this.environmentService.getSearchDriver() === 'typesense';
-  }
 }
@@ -4,7 +4,6 @@ import { EventName } from '../../common/events/event.contants';
 import { InjectQueue } from '@nestjs/bullmq';
 import { QueueJob, QueueName } from '../../integrations/queue/constants';
 import { Queue } from 'bullmq';
-import { EnvironmentService } from '../../integrations/environment/environment.service';

 export class SpaceEvent {
  spaceId: string;
@@ -15,22 +14,12 @@ export class SpaceListener {
  private readonly logger = new Logger(SpaceListener.name);

  constructor(
-    private readonly environmentService: EnvironmentService,
-    @InjectQueue(QueueName.SEARCH_QUEUE) private searchQueue: Queue,
    @InjectQueue(QueueName.AI_QUEUE) private aiQueue: Queue,
  ) {}

  @OnEvent(EventName.SPACE_DELETED)
  async handleSpaceDeleted(event: SpaceEvent) {
    const { spaceId } = event;
-    if (this.isTypesense()) {
-      await this.searchQueue.add(QueueJob.SPACE_DELETED, { spaceId });
-    }
-
    await this.aiQueue.add(QueueJob.SPACE_DELETED, { spaceId });
  }
-
-  isTypesense(): boolean {
-    return this.environmentService.getSearchDriver() === 'typesense';
-  }
 }
@@ -4,7 +4,6 @@ import { EventName } from '../../common/events/event.contants';
 import { InjectQueue } from '@nestjs/bullmq';
 import { QueueJob, QueueName } from '../../integrations/queue/constants';
 import { Queue } from 'bullmq';
-import { EnvironmentService } from '../../integrations/environment/environment.service';

 export class WorkspaceEvent {
  workspaceId: string;
@@ -15,22 +14,12 @@ export class WorkspaceListener {
  private readonly logger = new Logger(WorkspaceListener.name);

  constructor(
-    private readonly environmentService: EnvironmentService,
-    @InjectQueue(QueueName.SEARCH_QUEUE) private searchQueue: Queue,
    @InjectQueue(QueueName.AI_QUEUE) private aiQueue: Queue,
  ) {}

  @OnEvent(EventName.WORKSPACE_DELETED)
  async handlePageDeleted(event: WorkspaceEvent) {
    const { workspaceId } = event;
-    if (this.isTypesense()) {
-      await this.searchQueue.add(QueueJob.WORKSPACE_DELETED, { workspaceId });
-    }
-
    await this.aiQueue.add(QueueJob.WORKSPACE_DELETED, { workspaceId });
  }
-
-  isTypesense(): boolean {
-    return this.environmentService.getSearchDriver() === 'typesense';
-  }
 }
@@ -24,6 +24,10 @@ const migrator = new Migrator({
    path,
    migrationFolder,
  }),
+  // Match the startup auto-migrator (migration.service.ts): a back-dated
+  // migration from a long-lived branch must be applied, not rejected as
+  // "corrupted migrations" (incident #361). See that file for the full rationale.
+  allowUnorderedMigrations: true,
 });

 run(db, migrator, migrationFolder);
@@ -0,0 +1,27 @@
+import { type Kysely } from 'kysely';
+
+/**
+ * #370 — page-versioning intentionality tier on a history snapshot.
+ *
+ * Adds `page_history.kind`, the three-tier "how intentional was this snapshot"
+ * marker that lets versions (intentional points) be told apart from autosaves:
+ *   - 'manual'   — a human explicitly saved a version (Cmd+S / Save button)
+ *   - 'agent'    — the AI agent explicitly saved a version
+ *   - 'idle'     — trailing idle-flush autosnapshot (safety net)
+ *   - 'boundary' — autosnapshot pinned on a source transition (user↔agent↔git)
+ *
+ * Nullable with NO default (mirrors last_updated_source in the agent-provenance
+ * migration): legacy rows predate the marker and read back as `null`, which the
+ * client renders as a plain autosave. Stored as a short varchar to stay
+ * forward-compatible without an enum migration.
+ */
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .alterTable('page_history')
+    .addColumn('kind', 'varchar(20)', (col) => col)
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.alterTable('page_history').dropColumn('kind').execute();
+}
@@ -13,6 +13,7 @@ import { jsonArrayFrom, jsonObjectFrom } from 'kysely/helpers/postgres';
 import { ExpressionBuilder, sql } from 'kysely';
 import { DB } from '@docmost/db/types/db';
 import { resolveAgentProvenance } from '../agent-provenance';
+import { PageHistoryKind } from '../../../collaboration/constants';

 /**
 * Role-resolution subquery for a page-history row's bound AI chat (#300). Joins
@@ -46,6 +47,9 @@ export class PageHistoryRepo {
    'lastUpdatedById',
    'lastUpdatedSource',
    'lastUpdatedAiChatId',
+    // #370 — intentionality tier ('manual' | 'agent' | 'idle' | 'boundary');
+    // null on legacy rows (= autosave). Selected so callers can read/promote it.
+    'kind',
    'contributorIds',
    'spaceId',
    'workspaceId',
@@ -85,9 +89,15 @@ export class PageHistoryRepo {

  async saveHistory(
    page: Page,
-    opts?: { contributorIds?: string[]; trx?: KyselyTransaction },
-  ): Promise<void> {
-    await this.insertPageHistory(
+    opts?: {
+      contributorIds?: string[];
+      // #370 — intentionality tier for this snapshot. Omitted → null (legacy
+      // autosave semantics). Callers derive it server-side, never from a client.
+      kind?: PageHistoryKind;
+      trx?: KyselyTransaction;
+    },
+  ): Promise<PageHistory> {
+    return await this.insertPageHistory(
      {
        pageId: page.id,
        slugId: page.slugId,
@@ -99,6 +109,7 @@ export class PageHistoryRepo {
        // Copy the provenance marker off the page row, as for lastUpdatedById.
        lastUpdatedSource: page.lastUpdatedSource,
        lastUpdatedAiChatId: page.lastUpdatedAiChatId,
+        kind: opts?.kind ?? null,
        contributorIds: opts?.contributorIds,
        spaceId: page.spaceId,
        workspaceId: page.workspaceId,
@@ -107,6 +118,25 @@ export class PageHistoryRepo {
    );
  }

+  /**
+   * #370 — promote an existing snapshot's intentionality tier in place. Used by
+   * the manual-save "promote-not-dup" path: when the latest history row already
+   * holds the exact content being versioned, we upgrade its `kind` instead of
+   * duplicating a heavy content row.
+   */
+  async updateHistoryKind(
+    pageHistoryId: string,
+    kind: PageHistoryKind,
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    const db = dbOrTx(this.db, trx);
+    await db
+      .updateTable('pageHistory')
+      .set({ kind })
+      .where('id', '=', pageHistoryId)
+      .execute();
+  }
+
  async findPageHistoryByPageId(pageId: string, pagination: PaginationOptions) {
    const query = this.db
      .selectFrom('pageHistory')
@@ -19,6 +19,16 @@ export class MigrationService {
        path,
        migrationFolder: path.join(__dirname, '..', 'migrations'),
      }),
+      // A long-lived branch can add a migration whose timestamped filename sorts
+      // BEFORE migrations already applied in prod (e.g. #234's 20260627 landing
+      // after 20260704 was live). With the default (ordered) setting the startup
+      // migrator then sees "corrupted migrations" — the applied set is no longer a
+      // prefix of the sorted list — throws, and the app crash-loops on boot
+      // (incident #361: 502s for ~11 min). allowUnorderedMigrations runs any
+      // not-yet-applied migration regardless of filename order, so a back-dated
+      // migration is applied instead of bricking startup. A CI order-gate still
+      // discourages back-dating; this is the runtime safety net.
+      allowUnorderedMigrations: true,
    });

    const { error, results } = await migrator.migrateToLatest();
@@ -280,6 +280,7 @@ export interface PageHistory {
  createdAt: Generated<Timestamp>;
  icon: string | null;
  id: Generated<string>;
+  kind: string | null;
  lastUpdatedAiChatId: string | null;
  lastUpdatedById: string | null;
  lastUpdatedSource: string | null;
@@ -0,0 +1,124 @@
+import { readFileSync } from 'fs';
+import { streamText, Output } from 'ai';
+import { MockLanguageModelV3, simulateReadableStream } from 'ai/test';
+
+/**
+ * Regression tests for patches/ai@6.0.134.patch (server heap OOM on long
+ * autonomous agent runs, #184).
+ *
+ * Unpatched ai@6.0.134 substitutes the default text() output strategy even
+ * when the caller passes NO `output` option. Its createOutputTransformStream
+ * then accumulates the ENTIRE turn text and, on EVERY text-delta, enqueues a
+ * flat snapshot of all text so far as `partialOutput` (O(n^2) memory). Those
+ * snapshots pile up in the never-consumed leftover tee() branch of
+ * DefaultStreamTextResult.baseStream, which is what OOM'd production during a
+ * ~28k-chunk agent turn. The pnpm patch skips partialOutput production
+ * entirely when no output strategy was requested, while keeping per-delta
+ * streaming granularity.
+ */
+describe('ai@6.0.134 pnpm patch: no partialOutput accumulation without an output strategy', () => {
+  const makeModel = () =>
+    new MockLanguageModelV3({
+      doStream: async () => ({
+        stream: simulateReadableStream({
+          chunks: [
+            { type: 'stream-start' as const, warnings: [] },
+            { type: 'text-start' as const, id: '1' },
+            { type: 'text-delta' as const, id: '1', delta: 'Hello' },
+            { type: 'text-delta' as const, id: '1', delta: ', ' },
+            { type: 'text-delta' as const, id: '1', delta: 'world!' },
+            { type: 'text-end' as const, id: '1' },
+            {
+              type: 'finish' as const,
+              finishReason: { unified: 'stop' as const, raw: 'stop' },
+              usage: {
+                inputTokens: {
+                  total: 1,
+                  noCache: undefined,
+                  cacheRead: undefined,
+                  cacheWrite: undefined,
+                },
+                outputTokens: { total: 1, text: 1, reasoning: undefined },
+              },
+            },
+          ],
+        }),
+      }),
+    });
+
+  it('preserves per-delta streaming granularity in textStream', async () => {
+    const result = streamText({ model: makeModel(), prompt: 'hi' });
+
+    const deltas: string[] = [];
+    for await (const delta of result.textStream) {
+      deltas.push(delta);
+    }
+
+    // The patch must NOT coalesce or drop deltas: three model deltas arrive
+    // as three separate textStream chunks.
+    expect(deltas).toEqual(['Hello', ', ', 'world!']);
+  });
+
+  it('emits NO partialOutput values when the caller did not request an output strategy', async () => {
+    const result = streamText({ model: makeModel(), prompt: 'hi' });
+
+    // Fully consume the primary stream first (mirrors production usage).
+    for await (const _ of result.textStream) {
+      // drain
+    }
+
+    const partials: unknown[] = [];
+    for await (const partial of result.experimental_partialOutputStream) {
+      partials.push(partial);
+    }
+
+    // TRIPWIRE: on unpatched ai@6.0.134 the default text() output strategy
+    // yields one cumulative partial per text-delta here (['Hello', 'Hello, ',
+    // 'Hello, world!']). An empty stream proves the patch is applied and no
+    // cumulative snapshots are being produced (and thus none can pile up in
+    // the leftover internal tee branch).
+    expect(partials).toEqual([]);
+  });
+
+  it('preserves cumulative partialOutput when the caller DOES request an output strategy', async () => {
+    // PRESERVE-BRANCH GUARD: the patch only short-circuits partialOutput when
+    // `output == null`. When an output strategy IS set (here Output.text()),
+    // createOutputTransformStream must fall through to the ORIGINAL code path
+    // and keep publishing cumulative snapshots, so object/text-output consumers
+    // behave byte-identically to unpatched ai. A careless re-port that routed
+    // output-set calls into the skip branch would leave partialOutput empty and
+    // silently break those consumers — this test is the tripwire for that.
+    const result = streamText({
+      model: makeModel(),
+      prompt: 'hi',
+      experimental_output: Output.text(),
+    });
+
+    // Drain the primary stream fully and accumulate the complete output text.
+    let fullText = '';
+    for await (const delta of result.textStream) {
+      fullText += delta;
+    }
+
+    const partials: string[] = [];
+    for await (const partial of result.experimental_partialOutputStream) {
+      partials.push(partial);
+    }
+
+    // With a strategy set, partialOutput must be PRESERVED (non-empty) and
+    // cumulative: the last emitted partial equals the full accumulated text.
+    expect(partials.length).toBeGreaterThan(0);
+    expect(partials[partials.length - 1]).toBe(fullText);
+    expect(fullText).toBe('Hello, world!');
+  });
+
+  it('both installed dist builds (CJS and ESM) carry the patch marker', () => {
+    // Secondary guard: pins the patch to BOTH bundles the SDK ships, since
+    // the NestJS server consumes CJS while other tooling may load ESM.
+    const cjsPath = require.resolve('ai');
+    const mjsPath = cjsPath.replace(/index\.js$/, 'index.mjs');
+    expect(cjsPath).toMatch(/index\.js$/);
+    expect(readFileSync(cjsPath, 'utf8')).toContain('PATCH(docmost');
+    expect(readFileSync(mjsPath, 'utf8')).toContain('PATCH(docmost');
+  });
+});
@@ -0,0 +1,145 @@
+// export.service.ts imports the ESM-only @sindresorhus/slugify (not in jest's
+// transform allowlist). It is irrelevant to the markdown-serialization path under
+// test (only used for page-mention link slugs on the DB path), so it is mocked
+// out to keep the module graph loadable under ts-jest (mirrors the import specs).
+jest.mock('@sindresorhus/slugify', () => ({
+  __esModule: true,
+  default: (input: string) => String(input),
+}));
+
+import { convertProseMirrorToMarkdown } from '@docmost/prosemirror-markdown';
+import { ExportService } from './export.service';
+import { ExportFormat } from './dto/export-dto';
+
+/**
+ * STEP 1 golden test for issue #345: server MARKDOWN export runs DIRECTLY through
+ * the canonical converter (`convertProseMirrorToMarkdown`) — no HTML intermediate
+ * and no `@docmost/editor-ext` markdown layer — so the emitted markdown is in the
+ * canonical package forms and is byte-identical to the git-sync vault body.
+ *
+ * These are the goldens the swap has to satisfy: they assert the CANONICAL
+ * surface (callout `> [!type]`, inline footnote `^[…]`, lossless image
+ * `<!--img …-->`) rather than the old editor-ext forms (`:::type`, `[^id]`,
+ * lossy `![alt](src)`).
+ *
+ * `exportPage(..., singlePage=false)` takes no DB path (no mention rewriting), so
+ * the service is constructed with null collaborators and only the pure
+ * PM -> Markdown path is exercised.
+ */
+
+function makeService(): ExportService {
+  return new ExportService(
+    null as any, // pageRepo
+    null as any, // pagePermissionRepo
+    null as any, // db
+    null as any, // storageService
+    null as any, // environmentService
+    null as any, // domainService
+  );
+}
+
+// A representative page exercising the node types whose canonical markdown form
+// changed with the move off the editor-ext layer: callout, inline footnote, and a
+// lossless image carrying width/align attrs that the old layer dropped.
+const REPRESENTATIVE_DOC = {
+  type: 'doc',
+  content: [
+    {
+      type: 'paragraph',
+      content: [
+        { type: 'text', text: 'Body ' },
+        { type: 'footnoteReference', attrs: { id: 'fn-1' } },
+        { type: 'text', text: ' end.' },
+      ],
+    },
+    {
+      type: 'callout',
+      attrs: { type: 'info', icon: null },
+      content: [
+        {
+          type: 'paragraph',
+          content: [{ type: 'text', text: 'Heads up' }],
+        },
+      ],
+    },
+    {
+      type: 'image',
+      attrs: {
+        src: '/files/pic.png',
+        alt: 'Pic',
+        width: 320,
+        align: 'left',
+      },
+    },
+    {
+      type: 'footnotesList',
+      content: [
+        {
+          type: 'footnoteDefinition',
+          attrs: { id: 'fn-1' },
+          content: [
+            {
+              type: 'paragraph',
+              content: [{ type: 'text', text: 'the note' }],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+describe('ExportService — markdown export via the canonical converter (#345)', () => {
+  it('emits canonical callout, inline footnote and lossless image forms', async () => {
+    const service = makeService();
+    const md = (await service.exportPage(ExportFormat.Markdown, {
+      title: '',
+      content: REPRESENTATIVE_DOC,
+    } as any)) as string;
+
+    // Callout: Obsidian `> [!type]`, NOT the legacy `:::type`.
+    expect(md).toContain('> [!info]');
+    expect(md).not.toContain(':::');
+
+    // Inline footnote: `^[…]`, NOT the reference `[^id]` form.
+    expect(md).toContain('^[the note]');
+    expect(md).not.toMatch(/\[\^/);
+
+    // Lossless image: trailing `<!--img …-->` carrying the dropped attrs.
+    expect(md).toContain('![Pic](/files/pic.png)');
+    expect(md).toContain('<!--img');
+    expect(md).toContain('"width":"320"');
+    expect(md).toContain('"align":"left"');
+  });
+
+  it('export body is byte-identical to the git-sync vault serializer (export == vault)', async () => {
+    const service = makeService();
+    // A title-less page: exportPage prepends NO heading, so the whole output is
+    // the page BODY — exactly what git-sync serializes (git-sync stores the title
+    // in frontmatter / the filename, never as an in-body H1).
+    const exported = (await service.exportPage(ExportFormat.Markdown, {
+      title: '',
+      content: REPRESENTATIVE_DOC,
+    } as any)) as string;
+
+    // The git-sync vault writer feeds this SAME converter (git-sync
+    // `stabilizePageBody` = convertProseMirrorToMarkdown(content) at the
+    // fixpoint). For an already-stable doc the single pass IS the fixpoint, so
+    // the two are byte-identical by construction — assert it.
+    const vaultBody = convertProseMirrorToMarkdown(REPRESENTATIVE_DOC);
+    expect(exported).toBe(vaultBody);
+  });
+
+  it('prepends the page title as an H1 heading (the one documented export/vault delta)', async () => {
+    const service = makeService();
+    const md = (await service.exportPage(ExportFormat.Markdown, {
+      title: 'My Page',
+      content: { type: 'doc', content: [] },
+    } as any)) as string;
+
+    // Export makes standalone files, so it prepends the title as an H1. This is
+    // the ONE deliberate difference from the vault body (which carries the title
+    // in frontmatter). The body below the heading still serializes canonically.
+    expect(md.startsWith('# My Page')).toBe(true);
+  });
+});
@@ -37,7 +37,7 @@ import {
  getAttachmentIds,
  getProsemirrorContent,
 } from '../../common/helpers/prosemirror/utils';
-import { htmlToMarkdown } from '@docmost/editor-ext';
+import { convertProseMirrorToMarkdown } from '@docmost/prosemirror-markdown';

 type AllowedAttachment = { id: string; fileName: string; filePath: string };

@@ -79,9 +79,8 @@ export class ExportService {
      prosemirrorJson.content.unshift(titleNode);
    }

-    const pageHtml = jsonToHtml(prosemirrorJson);
-
    if (format === ExportFormat.HTML) {
+      const pageHtml = jsonToHtml(prosemirrorJson);
      return `<!DOCTYPE html>
      <html>
        <head>
@@ -92,11 +91,14 @@ export class ExportService {
    }

    if (format === ExportFormat.Markdown) {
-      const newPageHtml = pageHtml.replace(
-        /<colgroup[^>]*>[\s\S]*?<\/colgroup>/gim,
-        '',
-      );
-      return htmlToMarkdown(newPageHtml);
+      // Direct ProseMirror JSON -> Markdown via the canonical converter
+      // (`@docmost/prosemirror-markdown`). This is the SAME serializer the
+      // git-sync vault writer feeds (see git-sync `stabilizePageBody`), so an
+      // exported page body is byte-identical to its vault representation — no
+      // HTML intermediate, no second markdown layer, no format drift (issue
+      // #345). The old `<colgroup>` scrub is gone with the HTML step: the
+      // converter emits GFM tables directly and never produces `<colgroup>`.
+      return convertProseMirrorToMarkdown(prosemirrorJson);
    }

    return;
@@ -17,6 +17,22 @@ jest.mock('image-dimensions', () => ({
  __esModule: true,
  imageDimensionsFromData: () => undefined,
 }));
+// FileImportTaskService -> PageService -> collaboration.gateway ->
+// metrics.registry imports `prom-client`, which is not resolvable in this
+// workspace's node_modules (types-only stub, no runtime entry). Metrics are
+// disabled on this path, so a virtual no-op mock keeps the module graph loadable.
+jest.mock(
+  'prom-client',
+  () => ({
+    collectDefaultMetrics: () => undefined,
+    Registry: class {},
+    Histogram: class {},
+    Gauge: class {},
+    Counter: class {},
+    Summary: class {},
+  }),
+  { virtual: true },
+);

 import { promises as fs } from 'fs';
 import * as os from 'os';
@@ -26,14 +42,17 @@ import { ImportService } from './import.service';

 /**
 * Binding test for issue #228 / review #5: FileImportTaskService.processGenericImport
- * is a NON-editor write path (markdownToHtml -> processHTML -> JSON, never runs
- * footnoteSyncPlugin), so it canonicalizes footnotes before persisting. This pins
- * that binding — the same one import.service has a spec for — which previously had
- * NO spec at all.
+ * is a NON-editor write path, so a zip-imported `.md` page ends up with canonical
+ * footnotes before persisting: ordered by first reference, reused refs deduped,
+ * orphan definitions dropped.
 *
- * The markdown -> HTML -> ProseMirror conversion is REAL (a real ImportService,
- * its createYdoc stubbed); the filesystem is a real temp dir with one .md file;
- * the DB transaction is stubbed to capture the persisted page content.
+ * Since #345 the `.md` parse runs `normalizeForeignMarkdown` ->
+ * `markdownToProseMirror` -> `jsonToHtml` (feeding the shared HTML attachment /
+ * link pipeline) -> `processHTML` -> `canonicalizeFootnotes`. The parser assigns
+ * fresh `fn-*` ids, so we assert by definition BODY order rather than the source
+ * labels. The conversion is REAL (a real ImportService, its createYdoc stubbed);
+ * the filesystem is a real temp dir with one .md file; the DB transaction is
+ * stubbed to capture the persisted page content.
 */

 // Out-of-order references (c, a, b), a REUSED reference ([^a] twice), and an
@@ -49,13 +68,14 @@ const MARKDOWN = [
  '[^z]: orphan note',
 ].join('\n');

-function footnoteListIds(content: any): string[] {
+/** Definition body texts of the (single) footnotesList, in list order. */
+function footnoteListBodies(content: any): string[] {
  const list = (content?.content ?? []).find(
    (n: any) => n.type === 'footnotesList',
  );
  return (list?.content ?? [])
    .filter((n: any) => n.type === 'footnoteDefinition')
-    .map((n: any) => n.attrs?.id);
+    .map((n: any) => n.content?.[0]?.content?.[0]?.text);
 }

 // A permissive chainable stub for the spaces lookup (selectFrom(...).select(...)
@@ -71,80 +91,127 @@ function chainable(result: any): any {
  return proxy;
 }

+/**
+ * Run one markdown file through the REAL zip-import pipeline
+ * (`processGenericImport` -> `markdownToProseMirror` -> `jsonToHtml` ->
+ * `processHTML`/`htmlToJson`) and return the persisted page `content`. This is
+ * the server-specific PM->HTML->PM hop that the package's own PM<->MD tests do
+ * NOT cover.
+ */
+async function runZipImport(markdown: string): Promise<any> {
+  const extractDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fit-canon-'));
+  await fs.writeFile(path.join(extractDir, 'note.md'), markdown, 'utf-8');
+
+  const importService = new ImportService(
+    {} as any,
+    {} as any,
+    {} as any,
+    {} as any,
+  );
+  jest
+    .spyOn(importService as any, 'createYdoc')
+    .mockResolvedValue(Buffer.from([]) as any);
+
+  let captured: any = null;
+  const trx = {
+    insertInto: (table: string) => ({
+      values: (v: any) => {
+        if (table === 'pages') captured = v;
+        return { execute: async () => {} };
+      },
+    }),
+  };
+  const db: any = {
+    selectFrom: () => chainable({ slug: 'space-slug' }),
+    transaction: () => ({ execute: (fn: any) => fn(trx) }),
+  };
+
+  const importAttachmentService = {
+    processAttachments: async ({ html }: any) => html,
+  };
+  const service = new FileImportTaskService(
+    {} as any, // storageService
+    importService as any,
+    { nextPagePosition: async () => 'a0' } as any,
+    { insertBacklink: jest.fn() } as any,
+    db,
+    importAttachmentService as any,
+    { emit: jest.fn() } as any,
+    { logBatchWithContext: jest.fn() } as any,
+  );
+
+  const fileTask: any = {
+    id: 'task-1',
+    source: 'generic',
+    spaceId: 'space-1',
+    workspaceId: 'ws-1',
+    creatorId: 'user-1',
+  };
+
+  try {
+    await service.processGenericImport({ extractDir, fileTask });
+    expect(captured).toBeTruthy();
+    return captured.content;
+  } finally {
+    await fs.rm(extractDir, { recursive: true, force: true });
+  }
+}
+
+/** Find the first node of a given type anywhere in a PM content tree. */
+function findFirst(node: any, type: string): any {
+  if (!node || typeof node !== 'object') return null;
+  if (node.type === type) return node;
+  for (const child of node.content ?? []) {
+    const hit = findFirst(child, type);
+    if (hit) return hit;
+  }
+  return null;
+}
+
 describe('FileImportTaskService.processGenericImport — footnote canonicalization (#228)', () => {
  it('orders footnotes by first reference, dedupes reuse, and drops orphans on zip import', async () => {
-    const extractDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fit-canon-'));
-    await fs.writeFile(path.join(extractDir, 'note.md'), MARKDOWN, 'utf-8');
-
-    // Real ImportService for the html -> JSON conversion; stub the yjs encode.
-    const importService = new ImportService(
-      {} as any,
-      {} as any,
-      {} as any,
-      {} as any,
+    const content = await runZipImport(MARKDOWN);
+    // Definitions ordered by FIRST REFERENCE (C, A, B), NOT the markdown
+    // definition order (A, B, C). Ids are the parser's fresh `fn-*`, so pin
+    // the BODIES.
+    expect(footnoteListBodies(content)).toEqual(['note C', 'note A', 'note B']);
+    // Orphan [^z] dropped; reused [^a] collapses to one definition; one list.
+    expect(footnoteListBodies(content)).not.toContain('orphan note');
+    const lists = (content.content ?? []).filter(
+      (n: any) => n.type === 'footnotesList',
    );
-    jest
-      .spyOn(importService as any, 'createYdoc')
-      .mockResolvedValue(Buffer.from([]) as any);
+    expect(lists).toHaveLength(1);
+    expect(
+      footnoteListBodies(content).filter((b) => b === 'note A'),
+    ).toHaveLength(1);
+  });

-    let captured: any = null;
-    const trx = {
-      insertInto: (table: string) => ({
-        values: (v: any) => {
-          if (table === 'pages') captured = v;
-          return { execute: async () => {} };
-        },
-      }),
-    };
-    const db: any = {
-      selectFrom: () => chainable({ slug: 'space-slug' }),
-      transaction: () => ({ execute: (fn: any) => fn(trx) }),
-    };
+  // #345 F4: the zip path routes markdown through jsonToHtml -> processHTML ->
+  // htmlToJson (the shared HTML attachment pipeline). #345's headline is LOSSLESS
+  // image width/align via the `<!--img {...}-->` comment; a callout carries its
+  // `type`. This asserts those survive the PM->HTML->PM hop — the one hop the
+  // package's PM<->MD suite does not exercise.
+  it('preserves image width/align and callout type through the PM->HTML->PM hop', async () => {
+    const md = [
+      '# Doc',
+      '',
+      '![a picture](https://example.com/i.png) <!--img {"width":"320","align":"left"}-->',
+      '',
+      ':::warning',
+      'Careful now.',
+      ':::',
+    ].join('\n');

-    const importAttachmentService = {
-      processAttachments: async ({ html }: any) => html,
-    };
-    const backlinkRepo = { insertBacklink: jest.fn() };
-    const eventEmitter = { emit: jest.fn() };
-    const auditService = { logBatchWithContext: jest.fn() };
+    const content = await runZipImport(md);

-    const pageService = { nextPagePosition: async () => 'a0' };
+    const image = findFirst(content, 'image');
+    expect(image).toBeTruthy();
+    // The lossless sizing/alignment must survive the HTML hop.
+    expect(String(image.attrs?.width)).toBe('320');
+    expect(image.attrs?.align).toBe('left');

-    const service = new FileImportTaskService(
-      {} as any, // storageService
-      importService as any,
-      pageService as any,
-      backlinkRepo as any,
-      db,
-      importAttachmentService as any,
-      eventEmitter as any,
-      auditService as any,
-    );
-
-    const fileTask: any = {
-      id: 'task-1',
-      source: 'generic',
-      spaceId: 'space-1',
-      workspaceId: 'ws-1',
-      creatorId: 'user-1',
-    };
-
-    try {
-      await service.processGenericImport({ extractDir, fileTask });
-
-      expect(captured).toBeTruthy();
-      const content = captured.content;
-      // Reference order is c, a, b (NOT the markdown definition order a, b, c).
-      expect(footnoteListIds(content)).toEqual(['c', 'a', 'b']);
-      // Orphan [^z] dropped; reused [^a] collapses to one definition; one list.
-      expect(footnoteListIds(content)).not.toContain('z');
-      const lists = (content.content ?? []).filter(
-        (n: any) => n.type === 'footnotesList',
-      );
-      expect(lists).toHaveLength(1);
-      expect(footnoteListIds(content).filter((id) => id === 'a')).toHaveLength(1);
-    } finally {
-      await fs.rm(extractDir, { recursive: true, force: true });
-    }
+    const callout = findFirst(content, 'callout');
+    expect(callout).toBeTruthy();
+    expect(callout.attrs?.type).toBe('warning');
  });
 });
@@ -1,6 +1,9 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
 import * as path from 'path';
-import { jsonToText } from '../../../collaboration/collaboration.util';
+import {
+  jsonToHtml,
+  jsonToText,
+} from '../../../collaboration/collaboration.util';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
 import {
@@ -18,9 +21,11 @@ import { generateSlugId } from '../../../common/helpers';
 import { v7 } from 'uuid';
 import { generateJitteredKeyBetween } from 'fractional-indexing-jittered';
 import { FileTask, InsertablePage } from '@docmost/db/types/entity.types';
-import { markdownToHtml, canonicalizeFootnotes } from '@docmost/editor-ext';
+import { canonicalizeFootnotes } from '@docmost/editor-ext';
+import { markdownToProseMirror } from '@docmost/prosemirror-markdown';
 import { getProsemirrorContent } from '../../../common/helpers/prosemirror/utils';
 import { formatImportHtml } from '../utils/import-formatter';
+import { normalizeForeignMarkdown } from '../utils/foreign-markdown';
 import {
  buildAttachmentCandidates,
  collectMarkdownAndHtmlFiles,
@@ -461,7 +466,18 @@ export class FileImportTaskService {
              content = await fs.readFile(absPath, 'utf-8');

              if (page.fileExtension.toLowerCase() === '.md') {
-                content = await markdownToHtml(content);
+                // Parse markdown with the single canonical converter
+                // (`@docmost/prosemirror-markdown`), after normalizing foreign
+                // reference footnotes, then serialize to HTML so the shared HTML
+                // pipeline below (processAttachments + formatImportHtml +
+                // processHTML) keeps handling `.md` and `.html` imports
+                // uniformly. The markdown PARSE no longer goes through the
+                // editor-ext markdown layer (issue #345) — the drift source is
+                // gone. The PM -> HTML -> PM hop that follows is lossless
+                // plumbing for attachment/link resolution, NOT a second parse.
+                content = jsonToHtml(
+                  await markdownToProseMirror(normalizeForeignMarkdown(content)),
+                );
              }
            } catch (err: any) {
              if (err?.code === 'ENOENT') {
@@ -500,10 +516,12 @@ export class FileImportTaskService {
              this.importService.extractTitleAndRemoveHeading(pmState);

            // Canonicalize footnote topology on this non-editor write path
-            // (markdownToHtml/processHTML never runs footnoteSyncPlugin), so a
-            // zip-imported page's footnotes are reference-ordered, deduped, and
+            // (the HTML pipeline's processHTML never runs footnoteSyncPlugin), so
+            // a zip-imported page's footnotes are reference-ordered, deduped, and
            // orphan-free like the editor's invariant (issue #228). Pure +
-            // idempotent + shape-safe; a footnote-free doc is unchanged.
+            // idempotent + shape-safe; a footnote-free doc is unchanged. (For a
+            // `.md` file the package parser already yields canonical footnotes,
+            // so this is a no-op there.)
            // (Future consolidation, architecture B: like import.service, this
            // path persists directly rather than via PageService — a shared
            // "prepare JSON for persist" helper would centralize this call.)
@@ -12,13 +12,19 @@ import { canonicalizeFootnotes } from '@docmost/editor-ext';

 /**
 * Integration-ish test for the USER-FACING markdown import path
- * (`ImportService.importPage`). It exercises the REAL markdown -> HTML -> JSON
- * conversion and asserts that the stored page content has its footnotes
- * canonicalized — the gap that issue #228 fixes: the import path builds
- * ProseMirror JSON directly (never running the editor's footnoteSyncPlugin), so
- * before this wiring the stored footnotes kept the markdown's physical
- * definition order (out of order vs. references), retained orphan definitions,
- * and did not collapse reused references.
+ * (`ImportService.importPage`). It exercises the REAL markdown -> ProseMirror
+ * conversion and asserts the stored page's footnotes are canonical: ordered by
+ * FIRST REFERENCE (not markdown definition order), reused references deduped to a
+ * single definition, and orphan definitions dropped.
+ *
+ * Since #345 the markdown parse runs through the canonical package
+ * (`normalizeForeignMarkdown` -> `markdownToProseMirror`), which owns this
+ * canonicalization: the input's GFM `[^id]` reference footnotes are normalized to
+ * inline `^[…]`, and the parser assigns fresh sequential ids (`fn-*`) in
+ * reference order while merging identical bodies — so we assert by definition
+ * BODY order, not by the source labels. `canonicalizeFootnotes` remains wired as
+ * an idempotent safety net (issue #228) and is a no-op on this already-canonical
+ * output.
 *
 * The DB/ydoc side-effects are stubbed: `getNewPagePosition` (DB query) and
 * `createYdoc` (Yjs encode) are spied, and `pageRepo.insertPage` captures the
@@ -67,24 +73,14 @@ function makeService() {
 }

 /** List the footnote-definition ids of the (single) footnotesList, in order. */
-function footnoteListIds(content: any): string[] {
+/** Definition body texts of the (single) footnotesList, in list order. */
+function footnoteListBodies(content: any): string[] {
  const list = (content.content ?? []).find(
    (n: any) => n.type === 'footnotesList',
  );
-  if (!list) return [];
-  return (list.content ?? [])
+  return (list?.content ?? [])
    .filter((n: any) => n.type === 'footnoteDefinition')
-    .map((n: any) => n.attrs?.id);
-}
-
-function definitionText(content: any, id: string): string | undefined {
-  const list = (content.content ?? []).find(
-    (n: any) => n.type === 'footnotesList',
-  );
-  const def = (list?.content ?? []).find(
-    (n: any) => n.type === 'footnoteDefinition' && n.attrs?.id === id,
-  );
-  return def?.content?.[0]?.content?.[0]?.text;
+    .map((n: any) => n.content?.[0]?.content?.[0]?.text);
 }

 describe('ImportService.importPage — footnote canonicalization (#228)', () => {
@@ -101,23 +97,23 @@ describe('ImportService.importPage — footnote canonicalization (#228)', () =>
    const content = getCaptured().content;
    expect(content).toBeTruthy();

-    // Reference order is c, a, b (NOT the markdown definition order a, b, c).
-    expect(footnoteListIds(content)).toEqual(['c', 'a', 'b']);
-
-    // Definitions preserved and attached to the right ids.
-    expect(definitionText(content, 'c')).toBe('note C');
-    expect(definitionText(content, 'a')).toBe('note A');
-    expect(definitionText(content, 'b')).toBe('note B');
+    // Definitions ordered by FIRST REFERENCE (C, A, B) — NOT the markdown
+    // definition order (A, B, C) — with the orphan [^z] dropped and the reused
+    // [^a] collapsed to a single definition. (Ids are the parser's fresh `fn-*`,
+    // so we pin the BODIES.)
+    expect(footnoteListBodies(content)).toEqual(['note C', 'note A', 'note B']);

    // Orphan definition [^z] is dropped.
-    expect(footnoteListIds(content)).not.toContain('z');
+    expect(footnoteListBodies(content)).not.toContain('orphan note');

    // Reused [^a] yields exactly ONE definition, and exactly one list.
    const lists = (content.content ?? []).filter(
      (n: any) => n.type === 'footnotesList',
    );
    expect(lists).toHaveLength(1);
-    expect(footnoteListIds(content).filter((id) => id === 'a')).toHaveLength(1);
+    expect(
+      footnoteListBodies(content).filter((b) => b === 'note A'),
+    ).toHaveLength(1);
  });

  it('is idempotent: canonicalizing the stored output again is a no-op', async () => {
@@ -134,6 +130,6 @@ describe('ImportService.importPage — footnote canonicalization (#228)', () =>
    // time must not change it (safe to wire into every write path).
    const second = canonicalizeFootnotes(stored);
    expect(second).toEqual(stored);
-    expect(footnoteListIds(second)).toEqual(['c', 'a', 'b']);
+    expect(footnoteListBodies(second)).toEqual(['note C', 'note A', 'note B']);
  });
 });
@@ -17,7 +17,9 @@ import {
 import { generateJitteredKeyBetween } from 'fractional-indexing-jittered';
 import { TiptapTransformer } from '@hocuspocus/transformer';
 import * as Y from 'yjs';
-import { markdownToHtml, canonicalizeFootnotes } from '@docmost/editor-ext';
+import { canonicalizeFootnotes } from '@docmost/editor-ext';
+import { markdownToProseMirror } from '@docmost/prosemirror-markdown';
+import { normalizeForeignMarkdown } from '../utils/foreign-markdown';
 import {
  FileTaskStatus,
  FileTaskType,
@@ -85,11 +87,13 @@ export class ImportService {

    const extracted = this.extractTitleAndRemoveHeading(prosemirrorState);
    const title = extracted.title;
-    // Imported markdown/HTML is built via markdownToHtml -> htmlToJson, which
-    // never runs the editor's footnoteSyncPlugin, so the footnote topology keeps
-    // the source's PHYSICAL definition order (out of order vs. references),
-    // retains orphan definitions, and is not deduped. Canonicalize before
-    // persisting so the stored page matches the editor's invariant (issue #228).
+    // The markdown path now canonicalizes footnotes itself (the package parser),
+    // but the HTML path (processHTML -> htmlToJson) does NOT run the editor's
+    // footnoteSyncPlugin, so an imported HTML doc can keep its source's PHYSICAL
+    // definition order (out of order vs. references), retain orphan definitions,
+    // and not be deduped. Canonicalize before persisting so the stored page
+    // matches the editor's invariant (issue #228); it is an idempotent no-op on
+    // the already-canonical markdown output.
    // Pure + idempotent + shape-safe: a doc with no footnotes is unchanged.
    // (Future consolidation, architecture B: this import path persists directly
    // via pageRepo.insertPage rather than through PageService.createPage, so the
@@ -133,12 +137,15 @@ export class ImportService {
  }

  async processMarkdown(markdownInput: string): Promise<any> {
-    try {
-      const html = await markdownToHtml(markdownInput);
-      return this.processHTML(html);
-    } catch (err) {
-      throw err;
-    }
+    // Canonical markdown -> ProseMirror JSON directly via
+    // `@docmost/prosemirror-markdown` (issue #345) — no HTML intermediate and no
+    // second editor-ext markdown layer. Foreign markdown surfaces the strict
+    // canonical parser does not accept (GFM `[^id]` reference footnotes) are
+    // rewritten to the canonical inline form by `normalizeForeignMarkdown` first.
+    // The HTML-cleanup pass (`normalizeImportHtml`) is intentionally skipped here:
+    // it targets foreign *HTML* (Notion/XWiki), which only ever arrives on the
+    // `.html` path (`processHTML`), never as canonical markdown.
+    return markdownToProseMirror(normalizeForeignMarkdown(markdownInput));
  }

  async processHTML(htmlInput: string): Promise<any> {
@@ -0,0 +1,218 @@
+import {
+  convertProseMirrorToMarkdown,
+  markdownToProseMirror,
+} from '@docmost/prosemirror-markdown';
+import { normalizeForeignMarkdown } from './foreign-markdown';
+
+/**
+ * STEP 2 goldens for issue #345: the foreign-markdown normalizer that runs at the
+ * import boundary BEFORE the strict canonical parser (`markdownToProseMirror`).
+ *
+ * Two layers:
+ *  1. PURE string→string cases pinning the normalizer's own behavior (GFM
+ *     reference footnotes → inline `^[…]`).
+ *  2. END-TO-END acceptance: for a foreign corpus, `normalizeForeignMarkdown`
+ *     then `markdownToProseMirror` then `convertProseMirrorToMarkdown` must leave
+ *     NO literal `[^id]` / `:::` garbage in the document and must re-export in the
+ *     canonical forms.
+ */
+
+describe('normalizeForeignMarkdown — GFM reference footnotes', () => {
+  it('inlines a single-line reference footnote and drops its definition', () => {
+    const out = normalizeForeignMarkdown(
+      'A note[^1] here.\n\n[^1]: The definition.',
+    );
+    expect(out).toBe('A note^[The definition.] here.\n');
+  });
+
+  it('inlines every reference to a reused id (downstream dedups)', () => {
+    const out = normalizeForeignMarkdown(
+      'X[^a] and Y[^a].\n\n[^a]: shared.',
+    );
+    expect(out).toBe('X^[shared.] and Y^[shared.].\n');
+  });
+
+  it('joins indented continuation lines of a definition with a space', () => {
+    const out = normalizeForeignMarkdown(
+      'See[^n].\n\n[^n]: line one\n    line two',
+    );
+    expect(out).toBe('See^[line one line two].\n');
+  });
+
+  it('never rewrites a reference inside a fenced code block', () => {
+    const out = normalizeForeignMarkdown(
+      '```\ncode[^1] here\n```\n\n[^1]: def.',
+    );
+    expect(out).toContain('code[^1] here');
+    // The (now orphaned) definition line is still removed.
+    expect(out).not.toContain('[^1]: def.');
+  });
+
+  it('never rewrites a reference inside an INLINE-code span (backticks)', () => {
+    // The `[^1]` inside backticks is literal code and must survive verbatim;
+    // the one outside is rewritten. (Bug #1: only fenced blocks were protected.)
+    const out = normalizeForeignMarkdown(
+      'Use `arr[^1]` in code but note[^1] in prose.\n\n[^1]: def.',
+    );
+    expect(out).toBe('Use `arr[^1]` in code but note^[def.] in prose.\n');
+  });
+
+  it('escapes brackets in a body so an unbalanced ] cannot truncate the footnote', () => {
+    // A foreign definition body with a stray `]` would, unescaped, close the
+    // canonical `^[...]` early and leak the tail as text (bug #2). The body's
+    // brackets are backslash-escaped so the footnote stays whole.
+    const out = normalizeForeignMarkdown(
+      'Ref[^1] here.\n\n[^1]: see item ] and [more] later',
+    );
+    expect(out).toBe('Ref^[see item \\] and \\[more\\] later] here.\n');
+    // The tokenizer must see exactly one unescaped closing bracket (our own).
+    expect(out.match(/(?<!\\)\]/g)).toHaveLength(1);
+  });
+
+  it('leaves a reference with no matching definition literal (no body to inline)', () => {
+    const out = normalizeForeignMarkdown('Dangling[^x] ref.');
+    expect(out).toBe('Dangling[^x] ref.');
+  });
+
+  it('returns the input unchanged when there are no reference footnotes', () => {
+    const md = '# Title\n\nJust text with `inline code` and a [link](/x).';
+    expect(normalizeForeignMarkdown(md)).toBe(md);
+  });
+
+  it('does NOT touch callout surfaces — the canonical parser handles them', () => {
+    const callouts = ':::info\nHi\n:::\n\n> [!warning]\n> Careful';
+    expect(normalizeForeignMarkdown(callouts)).toBe(callouts);
+  });
+
+  it('strips a leading YAML front-matter block (Obsidian/Hugo/git-sync files)', () => {
+    const out = normalizeForeignMarkdown(
+      '---\ntitle: My Page\ntags: [a, b]\n---\n\n# Heading\n\nBody.',
+    );
+    expect(out).toBe('# Heading\n\nBody.');
+    // The front-matter must not leak into the body as a setext heading.
+    expect(out).not.toContain('title: My Page');
+    expect(out).not.toContain('---');
+  });
+
+  it('does not strip a horizontal rule that is not leading front-matter', () => {
+    const md = 'Intro paragraph.\n\n---\n\nAfter the rule.';
+    expect(normalizeForeignMarkdown(md)).toBe(md);
+  });
+
+  it('is linear on a document with thousands of definitions (no quadratic blowup)', () => {
+    // F2(a): the pass-2 rewrite must be O(text), not O(text × defs). Build a
+    // pathological doc (many defs + many plain text lines) and assert it
+    // completes well under a second — a quadratic implementation took ~14s.
+    const N = 4000;
+    const refs = Array.from({ length: N }, (_, i) => `line ${i} plain text`).join('\n');
+    const defs = Array.from({ length: N }, (_, i) => `[^n${i}]: def ${i}`).join('\n');
+    const doc = `start[^n0] and[^n${N - 1}] end\n\n${refs}\n\n${defs}`;
+    const t0 = Date.now();
+    const out = normalizeForeignMarkdown(doc);
+    const elapsed = Date.now() - t0;
+    expect(elapsed).toBeLessThan(2000);
+    // Sanity: the two real references were still inlined.
+    expect(out).toContain('^[def 0]');
+    expect(out).toContain(`^[def ${N - 1}]`);
+  });
+
+  it('is bounded on a long unclosed backtick run (no inline-split ReDoS)', () => {
+    // F2(b): a huge unterminated backtick run must not cause quadratic
+    // backtracking in the inline-code split. Oversized lines skip the split
+    // entirely (left untouched), so this returns promptly.
+    const line = 'x' + '`'.repeat(200000);
+    const doc = `${line}\n\n[^1]: def`;
+    const t0 = Date.now();
+    normalizeForeignMarkdown(doc);
+    expect(Date.now() - t0).toBeLessThan(2000);
+  });
+
+  it('does not crash or slow down on thousands of prefix-chain definition ids', () => {
+    // F7: the rewrite must use a FIXED generic scanner, not an alternation built
+    // from the ids. A `(a|aa|aaa|…)` alternation over prefix-chain ids blows the
+    // V8 regex compiler (FATAL RegExpCompiler Allocation failed — uncatchable,
+    // kills the process). A fixed scanner has no id-dependent compilation cost.
+    const N = 4000;
+    const ids = Array.from({ length: N }, (_, i) => 'a'.repeat(i + 1));
+    const defs = ids.map((id) => `[^${id}]: body ${id.length}`).join('\n');
+    const doc = `ref[^${ids[0]}] and[^${ids[N - 1]}] end\n\n${defs}`;
+    const t0 = Date.now();
+    const out = normalizeForeignMarkdown(doc);
+    expect(Date.now() - t0).toBeLessThan(2000);
+    // Prefix disambiguation is correct: [^a] and [^aaaa...] inline their OWN body.
+    expect(out).toContain('^[body 1]');
+    expect(out).toContain(`^[body ${N}]`);
+  });
+
+  it('strips a CRLF (Windows) front-matter block, not just LF', () => {
+    // F9: the line-anchored regex needs LF after the opening `---`, so a Windows
+    // file (`---\r\n…`) would slip past the strip and leak the front-matter into
+    // the body. normalizeForeignMarkdown normalizes CRLF -> LF first.
+    const out = normalizeForeignMarkdown(
+      '---\r\ntitle: Foo\r\ntags: [a]\r\n---\r\n\r\n# Heading\r\n\r\nBody.',
+    );
+    expect(out).toBe('# Heading\n\nBody.');
+    expect(out).not.toContain('title: Foo');
+    expect(out).not.toContain('---');
+  });
+
+  it('strips front-matter whose value contains a triple-dash (line-anchored)', () => {
+    // F8: the block must close only on a `\n---` LINE, not the first inline
+    // `---`. A value like `title: Q1 --- Q2` must not truncate the front-matter
+    // and leak the rest (author/closing ---) into the body.
+    const out = normalizeForeignMarkdown(
+      '---\ntitle: Q1 --- Q2 results\nauthor: bob\n---\n\nReal body.',
+    );
+    expect(out).toBe('Real body.');
+    expect(out).not.toContain('author: bob');
+    expect(out).not.toContain('Q2 results');
+  });
+});
+
+describe('foreign markdown import acceptance (normalizer + canonical parser)', () => {
+  const FOREIGN = [
+    '# Doc',
+    '',
+    'Body refs [^c] and [^a] and [^b] and again [^a].',
+    '',
+    ':::info',
+    'A legacy callout.',
+    ':::',
+    '',
+    '| h1 | h2 |',
+    '| --- | --- |',
+    '| 1 | 2 |',
+    '',
+    '[^a]: note A',
+    '[^b]: note B',
+    '[^c]: note C',
+    '[^z]: orphan note',
+  ].join('\n');
+
+  it('leaves no literal [^id] or ::: in the imported doc and re-exports canonically', async () => {
+    const normalized = normalizeForeignMarkdown(FOREIGN);
+    const doc = await markdownToProseMirror(normalized);
+    const reexport = convertProseMirrorToMarkdown(doc);
+
+    // No foreign garbage leaks into the document.
+    expect(reexport).not.toMatch(/\[\^/); // no reference footnote refs/defs
+    expect(reexport).not.toContain(':::'); // no legacy callout fences
+
+    // Canonical forms are present.
+    expect(reexport).toContain('^[note C]');
+    expect(reexport).toContain('> [!info]');
+    expect(reexport).toContain('| h1 | h2 |');
+
+    // Footnotes: ordered by first reference (C, A, B), reused [^a] deduped to one,
+    // orphan [^z] dropped (it had no reference after normalization).
+    const list = doc.content.find((n: any) => n.type === 'footnotesList');
+    const bodies = list.content.map(
+      (d: any) => d.content[0].content[0].text,
+    );
+    expect(bodies).toEqual(['note C', 'note A', 'note B']);
+    expect(bodies).not.toContain('orphan note');
+    expect(
+      doc.content.filter((n: any) => n.type === 'footnotesList'),
+    ).toHaveLength(1);
+  });
+});
@@ -0,0 +1,265 @@
+/**
+ * Foreign-markdown normalizer — an input-liberal / output-canonical adapter that
+ * runs at the IMPORT boundary, BEFORE the canonical parser
+ * (`markdownToProseMirror` from `@docmost/prosemirror-markdown`).
+ *
+ * The canonical parser is deliberately STRICT: it only understands Docmost's
+ * canonical markdown surface (Obsidian-style `> [!type]` callouts, Pandoc/Obsidian
+ * inline footnotes `^[body]`, lossless `![alt](src) <!--img {...}-->` images, …).
+ * Import, however, ingests FOREIGN files (GitHub/GFM, Notion, old Docmost
+ * exports). Those use surfaces the canonical parser does not accept, most notably
+ * GitHub-flavoured *reference* footnotes:
+ *
+ *     Text with a note[^1] and another[^long].
+ *
+ *     [^1]: The first definition.
+ *     [^long]: A second one.
+ *
+ * Left untouched, the parser does NOT recognise `[^id]` (it only parses `^[body]`),
+ * so the reference leaks as literal text — and worse, the trailing `[^id]: def`
+ * line is a valid CommonMark *link-reference definition*, so `[^id]` is silently
+ * rendered as a bogus link. This normalizer rewrites reference footnotes into the
+ * canonical inline form so the parser materialises real footnote nodes.
+ *
+ * This is a TEXT pre-pass, NOT a second parser fork: it does not re-implement any
+ * converter logic. Callout surfaces (`:::type` and `> [!type]`) are intentionally
+ * NOT touched here — the canonical parser already accepts BOTH natively (its
+ * `preprocessCallouts` pass), so normalizing them would be redundant and would
+ * only risk degrading the parser's nesting/code-fence-aware handling.
+ */
+
+/** Matches a fenced code block delimiter (``` or ~~~), capturing the marker run. */
+const CODE_FENCE_RE = /^(\s*)(`{3,}|~{3,})/;
+
+/**
+ * Matches a GFM footnote DEFINITION line: `[^id]: body`. The id is any run of
+ * non-`]` characters; the body is the remainder of the line (possibly empty).
+ */
+const FOOTNOTE_DEF_RE = /^\[\^([^\]]+)\]:[ \t]?(.*)$/;
+
+/** True when a line is a code-fence delimiter that toggles fenced-code state. */
+function fenceMarker(line: string): string | null {
+  const m = line.match(CODE_FENCE_RE);
+  return m ? m[2] : null;
+}
+
+/** True when a line is indented (leading space/tab) and not blank — a continuation. */
+function isIndentedContinuation(line: string): boolean {
+  return /^[ \t]+\S/.test(line);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Backslash-escape any square bracket in a footnote body before it is wrapped in
+ * `^[...]`. The canonical inline-footnote tokenizer scans the body with bracket
+ * balancing and closes on the first UNMATCHED `]`, so an unbalanced bracket in a
+ * foreign definition (e.g. `[^1]: see item ] later`) would otherwise truncate the
+ * footnote and leak the tail as literal text. Escaping every `[`/`]` makes the
+ * body an inert run of characters — the tokenizer then closes only on our own
+ * closing `]`. (A balanced `[link](url)` inside a body still round-trips because
+ * the escaped form renders the literal brackets, which is the safe reading for a
+ * footnote body; the alternative — brittle balance tracking — risks worse.)
+ */
+function escapeFootnoteBody(body: string): string {
+  return body.replace(/[[\]]/g, '\\$&');
+}
+
+/**
+ * Rewrite every `[^id]` reference on a line to its `^[body]` form, but ONLY in the
+ * text OUTSIDE inline-code spans. A `[^id]` inside backticks is literal code
+ * content and must be preserved verbatim (a footnote ref never lives inside code).
+ * We split the line on inline-code spans (paired backtick runs) and rewrite only
+ * the non-code segments.
+ */
+// Above this length a single line is not split into inline-code spans (see
+// below). A genuine markdown line carrying a footnote reference is never tens of
+// KB; the cap only bypasses the inline-code protection for pathological lines.
+const INLINE_SPLIT_MAX_LINE = 8192;
+
+function rewriteRefsOutsideInlineCode(
+  line: string,
+  replace: (text: string) => string,
+): string {
+  // The inline-code split alternation `(`+)(?:(?!\1)[\s\S])*\1` backtracks
+  // quadratically on a long UNCLOSED backtick run (its middle can consume the
+  // rest of the line, then fail to find a closing run and retry from each
+  // position). On an untrusted import this is a request-thread ReDoS. A real
+  // footnote line is short, so for an oversized line we skip the inline-code
+  // protection entirely and leave the line UNTOUCHED (rewriting it wholesale
+  // could corrupt a `[^id]` that legitimately lives inside inline code). This is
+  // a conservative bypass: an over-8KB line simply does not get its reference
+  // footnotes inlined — acceptable for a pathological input.
+  if (line.length > INLINE_SPLIT_MAX_LINE) return line;
+
+  // Alternation: an inline-code span (one or more backticks, then anything up to
+  // the SAME run of backticks) OR a run of non-backtick text. Unterminated
+  // backticks fall through as ordinary text (matched by the second branch on the
+  // leftover), so a stray backtick never swallows the rest of the line.
+  const parts = line.match(/(`+)(?:(?!\1)[\s\S])*\1|[^`]+|`+/g);
+  if (!parts) return line;
+  return parts
+    .map((seg) => (seg.startsWith('`') ? seg : replace(seg)))
+    .join('');
+}
+
+/**
+ * Convert GFM reference footnotes (`[^id]` + `[^id]: def`) into canonical inline
+ * footnotes (`^[def]`).
+ *
+ * - Definitions are collected first (a leading `[^id]: text` line plus any
+ *   immediately-following indented continuation lines, joined with a space) and
+ *   removed from the output.
+ * - Each in-text reference `[^id]` for which a definition was found is replaced by
+ *   `^[def]`. References with no matching definition are left literal (there is no
+ *   body to inline; the parser fails them open the same way).
+ * - Code is respected on both passes: `[^id]` inside a fenced ``` / ~~~ block is
+ *   never rewritten and a `[^id]:` line inside a fence is never a definition; and
+ *   on the rewrite pass a `[^id]` inside an INLINE-code span (backticks) is left
+ *   literal too.
+ * - The inlined body is bracket-escaped so an unbalanced `[`/`]` in a foreign
+ *   definition cannot truncate the resulting `^[...]` footnote.
+ *
+ * Deduplication / reference-ordering / orphan-dropping of the resulting footnotes
+ * is handled downstream by the canonical parser (`assembleFootnotes`); this pass
+ * only changes the surface syntax.
+ */
+function convertReferenceFootnotes(markdown: string): string {
+  const lines = markdown.split('\n');
+
+  // Pass 1: collect definitions and mark their lines for removal.
+  const defs = new Map<string, string>();
+  const dropped = new Array<boolean>(lines.length).fill(false);
+  let inFence = false;
+  let fence = '';
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const marker = fenceMarker(line);
+    if (inFence) {
+      if (marker && marker[0] === fence[0] && marker.length >= fence.length) {
+        inFence = false;
+        fence = '';
+      }
+      continue;
+    }
+    if (marker) {
+      inFence = true;
+      fence = marker;
+      continue;
+    }
+
+    const def = line.match(FOOTNOTE_DEF_RE);
+    if (!def) continue;
+
+    const id = def[1];
+    const body: string[] = [def[2].trim()];
+    dropped[i] = true;
+
+    // Consume immediately-following indented continuation lines (GFM lazy
+    // continuation is not supported by design — keep it simple and predictable).
+    let j = i + 1;
+    while (j < lines.length && isIndentedContinuation(lines[j])) {
+      body.push(lines[j].trim());
+      dropped[j] = true;
+      j++;
+    }
+    i = j - 1;
+
+    // Last definition wins for a duplicated id (matches CommonMark link-ref
+    // semantics closely enough for a foreign-input adapter).
+    defs.set(id, body.filter((s) => s.length > 0).join(' '));
+  }
+
+  if (defs.size === 0) {
+    return markdown;
+  }
+
+  // ONE fixed, generic scanner regex — NOT one built from the definition ids.
+  // It matches ANY `[^id]` shape, and the replacer decides per match via a map
+  // lookup whether that id is a real definition (replace) or not (leave as-is).
+  // This is genuinely O(total text) with no per-document regex compilation.
+  //
+  // Do NOT rebuild this as an alternation over `[...defs.keys()]`: a giant
+  // `(id1|id2|...)` alternation over thousands of ids can blow the V8 regex
+  // compiler's stack — a fatal, UNCATCHABLE "RegExpCompiler Allocation failed"
+  // on prefix-chain ids (`a`, `aa`, `aaa`, ...) that kills the whole process
+  // (worse than the earlier per-def thread-hang). A fixed scanner has no
+  // id-dependent compilation cost and cannot blow up.
+  const refRe = /\[\^([^\]]+)\]/g;
+  const rewriteSegment = (segment: string): string =>
+    segment.replace(refRe, (whole, id: string) => {
+      const body = defs.get(id);
+      // Only real definitions are inlined; an unknown id is left literal (same as
+      // the old per-def loop, which simply never matched it).
+      return body === undefined ? whole : `^[${escapeFootnoteBody(body)}]`;
+    });
+
+  // Pass 2: rewrite in-text references, skipping fenced code and dropped lines.
+  const out: string[] = [];
+  inFence = false;
+  fence = '';
+  for (let i = 0; i < lines.length; i++) {
+    if (dropped[i]) continue;
+    let line = lines[i];
+
+    const marker = fenceMarker(line);
+    if (inFence) {
+      out.push(line);
+      if (marker && marker[0] === fence[0] && marker.length >= fence.length) {
+        inFence = false;
+        fence = '';
+      }
+      continue;
+    }
+    if (marker) {
+      inFence = true;
+      fence = marker;
+      out.push(line);
+      continue;
+    }
+
+    line = rewriteRefsOutsideInlineCode(line, rewriteSegment);
+    out.push(line);
+  }
+
+  return out.join('\n');
+}
+
+/**
+ * Strip a single leading YAML front-matter block (`---\n…\n---`). Foreign files
+ * from Obsidian / Hugo / Jekyll / Notion — and Docmost's OWN git-sync page files
+ * — open with front-matter that the canonical parser does not consume, so
+ * without this it leaks into the body (and `title: Foo` above the closing `---`
+ * renders as a setext `<h2>` that `extractTitleAndRemoveHeading` can hijack as
+ * the page title). It is a no-op for front-matter-free input.
+ *
+ * LINE-ANCHORED (the same shape the canonical parser uses in
+ * prosemirror-markdown/page-file.ts): the block opens only on `---\n` at the
+ * very start and closes only on a `\n---` line. The retired `markdownToHtml`
+ * strip closed on the FIRST `---` ANYWHERE (an unanchored close), so a value
+ * containing a triple-dash (e.g. `title: Q1 --- Q2`) truncated the front-matter
+ * and leaked the rest into the body. An optional leading BOM is tolerated.
+ */
+const YAML_FRONT_MATTER_RE = /^\uFEFF?---\n[\s\S]*?\n---\n?/;
+
+/**
+ * Normalize a foreign markdown string into Docmost's canonical markdown surface
+ * so the strict canonical parser accepts it losslessly: normalize line endings,
+ * strip a leading YAML front-matter block, then rewrite GFM reference footnotes
+ * into inline footnotes. Add further fixture-driven foreign-surface cases here as
+ * they are found.
+ */
+export function normalizeForeignMarkdown(markdown: string): string {
+  if (!markdown) return markdown;
+  // Normalize CRLF -> LF FIRST. The line-anchored front-matter regex requires a
+  // bare `\n` after the opening `---`, and convertReferenceFootnotes splits on
+  // `\n`; a Windows/CRLF foreign file (`---\r\n…`) would otherwise slip past the
+  // front-matter strip and leak into the body. The canonical parser
+  // (page-file.ts parsePageFile) normalizes the same way before its FRONTMATTER_RE.
+  const src = markdown.replace(/\r\n/g, '\n');
+  const withoutFrontMatter = src.replace(YAML_FRONT_MATTER_RE, '').trimStart();
+  return convertReferenceFootnotes(withoutFrontMatter);
+}
@@ -2,15 +2,36 @@ import { FastifyReply, FastifyRequest } from 'fastify';
 import { isStreamingResponse } from './metrics.constants';
 import { observeHttp } from './metrics.registry';

+// URL path prefixes served by @fastify/static (client build output under
+// client/dist). `/assets/` holds the content-hashed bundle (index-*.js,
+// chunk-*.js) — a NEW set of names every deploy, i.e. an UNBOUNDED label set
+// (#362); the others (/vad/, /brand/, /locales/, /icons/ — copied verbatim from
+// public/) have stable names, so they are merely repetitive per-file labels
+// rather than unbounded. Either way none of these belong in the API-route
+// histogram: collapse them all to one bounded `static` label. (Edge latency for
+// static is already measured by Traefik's traefik_router_request_duration_*.)
+const STATIC_PATH_PREFIXES = [
+  '/assets/',
+  '/vad/',
+  '/brand/',
+  '/locales/',
+  '/icons/',
+];
+
 /**
 * Resolve the BOUNDED route label for an HTTP response.
 *
- * HARD REQUIREMENT (#355): use the ROUTE TEMPLATE (`/pages/:id`), NEVER the raw
- * URL (`/pages/abc-123`), so label cardinality stays finite. Fastify exposes the
- * matched template on `req.routeOptions.url`. On 404s (no route matched) that is
- * missing → collapse to the literal `unknown`.
+ * HARD REQUIREMENT (#355): use the ROUTE TEMPLATE (`/pages/:id`), NEVER a raw
+ * URL (`/pages/abc-123` or `/assets/index-CAbxDtto.js`), so label cardinality
+ * stays finite. Fastify exposes the matched template on `req.routeOptions.url`,
+ * BUT @fastify/static serves each file through a route whose matched url is the
+ * raw (hashed) file path — so for static assets that value is itself unbounded.
+ * Detect static requests by their path prefix FIRST and collapse to `static`;
+ * otherwise use the route template; on a 404 (no route matched) → `unknown`.
 */
 export function resolveRouteLabel(req: FastifyRequest): string {
+  const path = (req.url ?? '').split('?', 1)[0];
+  if (STATIC_PATH_PREFIXES.some((p) => path.startsWith(p))) return 'static';
  const url = req.routeOptions?.url;
  return typeof url === 'string' && url.length > 0 ? url : 'unknown';
 }
@@ -46,7 +46,6 @@ export class MetricsBullService implements OnModuleInit, OnModuleDestroy {
    @InjectQueue(QueueName.GENERAL_QUEUE) generalQueue: Queue,
    @InjectQueue(QueueName.BILLING_QUEUE) billingQueue: Queue,
    @InjectQueue(QueueName.FILE_TASK_QUEUE) fileTaskQueue: Queue,
-    @InjectQueue(QueueName.SEARCH_QUEUE) searchQueue: Queue,
    @InjectQueue(QueueName.AI_QUEUE) aiQueue: Queue,
    @InjectQueue(QueueName.HISTORY_QUEUE) historyQueue: Queue,
    @InjectQueue(QueueName.NOTIFICATION_QUEUE) notificationQueue: Queue,
@@ -58,7 +57,6 @@ export class MetricsBullService implements OnModuleInit, OnModuleDestroy {
      { label: 'general', queue: generalQueue },
      { label: 'billing', queue: billingQueue },
      { label: 'file-task', queue: fileTaskQueue },
-      { label: 'search', queue: searchQueue },
      { label: 'ai', queue: aiQueue },
      { label: 'history', queue: historyQueue },
      { label: 'notification', queue: notificationQueue },
@@ -25,6 +25,61 @@ describe('resolveRouteLabel (histogram route label)', () => {
    const req = { url: '/x' } as unknown as FastifyRequest;
    expect(resolveRouteLabel(req)).toBe('unknown');
  });
+
+  it.each([
+    '/assets/index-CAbxDtto.js',
+    '/assets/chunk-3OPIFGDE-CJOt9nr5.js',
+    '/assets/excalidraw-menu-DpsI0kFW.js',
+    '/vad/silero_vad_v5.onnx',
+    '/brand/logo.svg',
+    '/locales/en.json',
+    '/icons/app-icon-192x192.png',
+  ])('collapses hashed/static asset %p to "static" (#362 cardinality)', (url) => {
+    // @fastify/static serves each file through a route whose matched url is the
+    // raw (hashed) file path, so routeOptions.url is itself unbounded here.
+    const req = {
+      url,
+      routeOptions: { url },
+    } as unknown as FastifyRequest;
+    const label = resolveRouteLabel(req);
+    expect(label).toBe('static');
+    expect(label).not.toContain('.js');
+    expect(label).not.toContain('index-');
+  });
+
+  it('strips the query string before the static-prefix check', () => {
+    const req = {
+      url: '/assets/index-CAbxDtto.js?v=2',
+      routeOptions: { url: '/assets/index-CAbxDtto.js' },
+    } as unknown as FastifyRequest;
+    expect(resolveRouteLabel(req)).toBe('static');
+  });
+
+  it('does NOT collapse a real API route that merely mentions assets', () => {
+    // A templated API route is kept as-is; only the static path PREFIXES collapse.
+    const req = {
+      url: '/api/pages/assets-guide',
+      routeOptions: { url: '/api/pages/:id' },
+    } as unknown as FastifyRequest;
+    expect(resolveRouteLabel(req)).toBe('/api/pages/:id');
+  });
+
+  it.each([
+    // The TRAILING SLASH on the prefix is the anti-false-collapse guard: a path
+    // that is the prefix WITHOUT its slash, or merely shares the prefix as a
+    // substring of a longer segment, must NOT collapse. These would collapse
+    // under a buggy `includes('/assets/')` / slashless-prefix impl.
+    '/assets',
+    '/assetsx/foo.js',
+    '/iconset/x.png',
+  ])('does NOT collapse the prefix-boundary case %p', (url) => {
+    const req = {
+      url,
+      routeOptions: { url: '/some/:route' },
+    } as unknown as FastifyRequest;
+    expect(resolveRouteLabel(req)).not.toBe('static');
+    expect(resolveRouteLabel(req)).toBe('/some/:route');
+  });
 });

 describe('isStreamingResponse (SSE exclusion)', () => {
@@ -4,7 +4,6 @@ export enum QueueName {
  GENERAL_QUEUE = '{general-queue}',
  BILLING_QUEUE = '{billing-queue}',
  FILE_TASK_QUEUE = '{file-task-queue}',
-  SEARCH_QUEUE = '{search-queue}',
  AI_QUEUE = '{ai-queue}',
  HISTORY_QUEUE = '{history-queue}',
  NOTIFICATION_QUEUE = '{notification-queue}',
@@ -32,12 +31,6 @@ export enum QueueJob {
  IMPORT_TASK = 'import-task',
  EXPORT_TASK = 'export-task',

-  SEARCH_INDEX_PAGE = 'search-index-page',
-  SEARCH_INDEX_PAGES = 'search-index-pages',
-  SEARCH_INDEX_COMMENT = 'search-index-comment',
-  SEARCH_INDEX_COMMENTS = 'search-index-comments',
-  SEARCH_INDEX_ATTACHMENT = 'search-index-attachment',
-  SEARCH_INDEX_ATTACHMENTS = 'search-index-attachments',
  SEARCH_REMOVE_PAGE = 'search-remove-page',
  SEARCH_REMOVE_ASSET = 'search-remove-attachment',
  SEARCH_REMOVE_FACE = 'search-remove-comment',
@@ -20,6 +20,10 @@ export interface IStripeSeatsSyncJob {

 export interface IPageHistoryJob {
  pageId: string;
+  // #370 — intentionality tier the worker stamps on the snapshot. All jobs on
+  // this queue are trailing idle-flush autosnapshots, so this is 'idle' (absent
+  // → treated as 'idle' by the processor).
+  kind?: 'idle';
 }

 /**
@@ -57,14 +57,6 @@ import { GeneralQueueProcessor } from './processors/general-queue.processor';
        attempts: 1,
      },
    }),
-    BullModule.registerQueue({
-      name: QueueName.SEARCH_QUEUE,
-      defaultJobOptions: {
-        removeOnComplete: true,
-        removeOnFail: true,
-        attempts: 2,
-      },
-    }),
    BullModule.registerQueue({
      name: QueueName.AI_QUEUE,
      defaultJobOptions: {
@@ -38,6 +38,24 @@ export const TEST_DATABASE_URL =
  process.env.TEST_DATABASE_URL ??
  'postgresql://docmost:docmost_dev_pw@localhost:5432/docmost_test';

+// Build the raw postgres.js client (mirrors database.module.ts: max pool,
+// silenced notices, bigint-as-number parsing). Kept separate so the singleton
+// can hold a reference to bound its shutdown in destroyTestDb.
+function buildTestSql(url: string = TEST_DATABASE_URL) {
+  return postgres(url, {
+    max: 5,
+    onnotice: () => {},
+    types: {
+      bigint: {
+        to: 20,
+        from: [20, 1700],
+        serialize: (value: number) => value.toString(),
+        parse: (value: string) => Number.parseInt(value),
+      },
+    },
+  });
+}
+
 /**
 * Build a Kysely instance that MIRRORS the app's setup in database.module.ts:
 * PostgresJSDialect over postgres(), CamelCasePlugin, and the bigint type
@@ -47,38 +65,40 @@ export const TEST_DATABASE_URL =
 */
 export function buildTestDb(url: string = TEST_DATABASE_URL): Kysely<any> {
  return new Kysely<any>({
-    dialect: new PostgresJSDialect({
-      postgres: postgres(url, {
-        max: 5,
-        onnotice: () => {},
-        types: {
-          bigint: {
-            to: 20,
-            from: [20, 1700],
-            serialize: (value: number) => value.toString(),
-            parse: (value: string) => Number.parseInt(value),
-          },
-        },
-      }),
-    }),
+    dialect: new PostgresJSDialect({ postgres: buildTestSql(url) }),
    plugins: [new CamelCasePlugin()],
  });
 }

 let singleton: Kysely<any> | undefined;
+let singletonSql: ReturnType<typeof buildTestSql> | undefined;

 /** Lazily-built shared Kysely for the test suite (one per worker; maxWorkers=1). */
 export function getTestDb(): Kysely<any> {
  if (!singleton) {
-    singleton = buildTestDb();
+    singletonSql = buildTestSql();
+    singleton = new Kysely<any>({
+      dialect: new PostgresJSDialect({ postgres: singletonSql }),
+      plugins: [new CamelCasePlugin()],
+    });
  }
  return singleton;
 }

 export async function destroyTestDb(): Promise<void> {
-  if (singleton) {
-    await singleton.destroy();
-    singleton = undefined;
+  if (!singleton) return;
+  const sql = singletonSql;
+  // Clear the refs first so a hung end() cannot leave a half-closed singleton.
+  singleton = undefined;
+  singletonSql = undefined;
+  // postgres.js .end() waits indefinitely for in-flight queries by default; a
+  // leaked/stuck pooled connection would hang the afterAll hook (a 60s hook
+  // timeout in CI). Bound the shutdown: the { timeout } grace period lets
+  // active queries drain, then force-closes lingering sockets so teardown
+  // always completes. We close the pool directly instead of Kysely.destroy()
+  // (which would call sql.end() again with no timeout).
+  if (sql) {
+    await sql.end({ timeout: 5 });
  }
 }

@@ -4,10 +4,14 @@
  "testEnvironment": "node",
  "testRegex": ".e2e-spec.ts$",
  "transform": {
+    "prosemirror-markdown/build/.+\\.js$": [
+      "babel-jest",
+      { "presets": [["@babel/preset-env", { "targets": { "node": "current" } }]] }
+    ],
    "^.+\\.(t|j)sx?$": ["ts-jest", { "tsconfig": { "allowJs": true } }]
  },
  "transformIgnorePatterns": [
-    "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0|@sindresorhus[+/][a-z0-9-]+|escape-string-regexp|p-limit|yocto-queue)(@|/))"
+    "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0|@sindresorhus[+/][a-z0-9-]+|escape-string-regexp|p-limit|yocto-queue|@docmost/prosemirror-markdown)(@|/))"
  ],
  "moduleNameMapper": {
    "^@docmost/db/(.*)$": "<rootDir>/../src/database/$1",
@@ -4,14 +4,19 @@
  "testRegex": ".*\\.int-spec\\.ts$",
  "testPathIgnorePatterns": ["/node_modules/"],
  "transform": {
+    "prosemirror-markdown/build/.+\\.js$": [
+      "babel-jest",
+      { "presets": [["@babel/preset-env", { "targets": { "node": "current" } }]] }
+    ],
    "^.+\\.(t|j)sx?$": "ts-jest"
  },
  "transformIgnorePatterns": [
-    "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0)(@|/))"
+    "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0|@docmost/prosemirror-markdown)(@|/))"
  ],
  "testEnvironment": "node",
  "testTimeout": 60000,
  "maxWorkers": 1,
+  "forceExit": true,
  "globalSetup": "<rootDir>/test/integration/global-setup.ts",
  "globalTeardown": "<rootDir>/test/integration/global-teardown.ts",
  "moduleNameMapper": {
@@ -0,0 +1,23 @@
+// Jest stub for @tiptap/react.
+//
+// The server export/import code paths transitively import editor-ext, whose node
+// extensions import from `@tiptap/react`. The real module re-exports all of
+// `@tiptap/core` (headless, safe under node) AND adds React view helpers
+// (`ReactNodeViewRenderer`, …) that eagerly pull in react-dom — which throws
+// `navigator is not defined` under jest's node environment.
+//
+// So this stub DELEGATES to the real `@tiptap/core` (keeping `mergeAttributes`,
+// `Node`, `Mark`, `nodeInputRule`, … working — they are used by
+// `jsonToHtml`/`htmlToJson` on the server) and overrides ONLY the React view
+// helpers with no-ops. Those helpers are referenced solely inside `addNodeView()`
+// — code that runs only in a live browser editor, never on the server; if any
+// were actually invoked here it would (correctly) surface as a test failure.
+const core = require('@tiptap/core');
+
+module.exports = {
+  ...core,
+  ReactNodeViewRenderer: () => () => ({}),
+  NodeViewWrapper: () => null,
+  NodeViewContent: () => null,
+  ReactRenderer: class {},
+};
@@ -131,5 +131,14 @@ const { Client } = require("pg");
 7. **Migrations don't auto-run in dev** — run `migration:latest` after every pull
   or branch switch.

+8. **Automation (Playwright): type into the BODY editor, not the title.** A page has
+   two `.ProseMirror` editors — `[aria-label='Page title']` (non-collab) and
+   `[aria-label='Page content']` (the collab body). `document.querySelector('.ProseMirror')`
+   returns the TITLE editor, so typing there never changes body content and `mod+S`
+   versions nothing. Target `[aria-label='Page content']`, confirm it's collab-bound
+   (`el.editor.extensionManager.extensions.some(e=>e.name==='collaboration')`), and
+   wait ~10-12s for the store debounce before asserting `pages.content` changed. Full
+   testing methodology + traps: **[how-to-test.md](how-to-test.md)**.
+
 See also the **Commands** and **Architecture → Two server processes** sections in
 [`AGENTS.md`](../AGENTS.md).
@@ -0,0 +1,108 @@
+# How to test the application (browser E2E + out-of-band)
+
+How to actually verify a feature end-to-end against a running stand — driving the
+**real app in a browser** and confirming results **out-of-band** in the DB/git, not
+through the same API you're supposed to be testing. Written from real false-positives
+that wasted hours (see **Traps** — read them before you write a test).
+
+Prereq: a running stand — see **[dev-stand.md](dev-stand.md)**. Automation uses
+Playwright (`pip install playwright && python -m playwright install chromium`).
+
+## Principles
+
+1. **Drive the behaviour under test through the browser.** The stand exists so you
+   exercise the real UI + realtime-collab + server path. Using `POST /api/pages/*` to
+   perform the action you're validating tests the API, not the app — an e2e suite can
+   do that. API calls are fine ONLY for one-time setup/fixtures, never for the
+   interaction you're asserting on.
+2. **Evidence before claim.** Nothing "passes" without an artifact: a DB row, a git
+   diff, a screenshot looked at as an image. If you can't show it, you didn't verify it.
+3. **Verify out-of-band.** Judge results from a source independent of the UI: `psql`
+   against the DB, a fresh `git clone` of a synced repo, a hard reload. Optimistic UI
+   lies about persistence.
+4. **Disconfirm by default.** For each feature, actively try to prove it's broken
+   before concluding it works. Reload after every create/edit/save.
+5. **Recon actuatability FIRST.** Before building editor tests, confirm the
+   interaction even works in your harness (does a typed edit reach the DB?). Skipping
+   this is how you ship a pile of tests that all silently exercised the wrong thing.
+
+## The editor: two ProseMirror instances (READ THIS)
+
+A page has **two** `.ProseMirror` editors:
+
+| index | selector | role | collab? |
+|---|---|---|---|
+| 0 | `[aria-label='Page title']` | title field | **NO** (16 exts, no `collaboration`) |
+| 1 | `[aria-label='Page content']` | body | **YES** (95 exts, has `collaboration`) |
+
+`document.querySelector('.ProseMirror')` returns the **title** editor (first match).
+Type there and you edit the title only — body page content never changes, so `mod+S`
+"versions" unchanged content and every content test silently no-ops.
+
+**Always target the body editor** and confirm it's collab-bound before typing:
+
+```js
+const el = document.querySelector("[aria-label='Page content']");
+el.editor.extensionManager.extensions.some(e => e.name === 'collaboration'); // must be true
+```
+
+Body edits emit ~20 `/collab` websocket frames while typing and land in
+`pages.content` after the **hocuspocus store debounce (~10s)** — so **wait ~12s**
+before asserting persistence (checking at 6–8s is a false negative). `mod+S` (the
+`save-version` stateless message) flushes immediately, so a version created right
+after a settled body edit holds the typed text.
+
+## A known-good browser flow
+
+```
+1. goto /s/<space-slug>            # the "Create page" button lives in the space sidebar, not /home
+2. click button[aria-label='Create page']   # fully UI-driven page creation
+3. type into [aria-label='Page title']       # optional title
+4. click [aria-label='Page content'] → type body text
+5. wait ~12s (store debounce)
+6. assert pages.content changed (psql)       # out-of-band
+7. mod+S / menu Save → assert page_history row (psql)
+8. reload / fresh context → re-assert (persistence round-trip)
+```
+
+Auth: log in ONCE, save `storage_state.json`, reuse it across pages/agents (re-login
+per run trips shared rate-limits). Cookie-based session authorizes both REST and the
+collab websocket.
+
+## Judging out-of-band
+
+```bash
+# page content / history
+docker exec <db> psql -U docmost -d docmost -tAc \
+  "select coalesce(kind,'null'), content::text from page_history where page_id='<id>' order by created_at;"
+# git-sync round-trip: clone the space repo and diff against what you pushed
+git clone http://<user>:<pass>@127.0.0.1:3000/git/<spaceId>.git /tmp/x
+```
+
+`page_history.content` is full JSON — parse it, don't truncate the snippet, or a
+marker check misses. For sync/async features (autosave, git-sync, idle-flush) use an
+active probe: write a unique marker, wait past the debounce/poll window, re-read
+out-of-band, ≥2 iterations — never conclude "broken" from a single snapshot.
+
+## Traps (each of these produced a false result in a real run)
+
+- **Wrong editor.** Typed into `.ProseMirror` (= title). Edits never touched body
+  content. → target `[aria-label='Page content']`.
+- **Checked persistence too early.** Store debounce ~10s; a 6–8s check reads stale.
+- **Truncated the DB snapshot** below where the test marker sits → false "content
+  missing".
+- **API-seeded the content under test**, then "verified" the feature — that validated
+  the API, not the app.
+- **Reused a fixed marker on a non-rebooted stand** → title/row collisions inflate
+  counts (`count==2`). Use a unique per-run marker (timestamp).
+- **Idle/async read once** and called it "permanently broken" — it was mid-debounce.
+- **Concluded env-limitation without a cross-build control.** If unsure whether a
+  failure is your harness or the product, run the SAME harness against a known-good
+  build; a divergence localizes it.
+
+## Scope note
+
+Some paths genuinely need a human in a real browser (rich drag-drop, native file
+pickers, clipboard, and anything the harness can't actuate). Label those UNTESTED in
+the report — "handled gracefully" is not "works". Keep four states distinct:
+verified-working, defect, untested, env-limitation.
@@ -96,7 +96,8 @@
  "pnpm": {
    "patchedDependencies": {
      "scimmy@1.3.5": "patches/scimmy@1.3.5.patch",
-      "yjs@13.6.30": "patches/yjs@13.6.30.patch"
+      "yjs@13.6.30": "patches/yjs@13.6.30.patch",
+      "ai@6.0.134": "patches/ai@6.0.134.patch"
    },
    "overrides": {
      "prosemirror-changeset": "2.4.0",
@@ -118,56 +118,19 @@ export function createDocmostMcpServer(config: DocmostMcpConfig): McpServer {
 // transport exposes a `tree:true` mode that returns the full nested hierarchy;
 // the in-app copy keeps the same tree option but is worded for the in-app agent.
 // Kept per-layer so each side can tune its own guidance.
-server.registerTool(
-  "list_pages",
-  {
-    description:
-      "List most recent pages in a space ordered by updatedAt (descending). " +
-      "Returns a bounded list (default 50, max 100) — use search for lookups " +
-      "in large spaces. Pass tree:true (with spaceId) to instead get the " +
-      "space's full page hierarchy as a nested tree.",
-    inputSchema: {
-      spaceId: z.string().optional(),
-      limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(100)
-        .optional()
-        .describe("Max pages to return (default 50, max 100)"),
-      tree: z
-        .boolean()
-        .optional()
-        .describe(
-          "When true, return the space's full page hierarchy as a nested tree (each node has a children array) instead of the recent-by-updatedAt flat list. Requires spaceId; ignores limit.",
-        ),
-    },
-  },
-  async ({ spaceId, limit, tree }) => {
-    const result = await docmostClient.listPages(spaceId, limit ?? 50, tree ?? false);
-    return jsonContent(result);
-  },
-);
+// 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
-server.registerTool(
-  "get_page",
-  {
-    description:
-      "Get page details with content converted to Markdown. The conversion is " +
-      "LOSSY (block ids, exact table/callout structure are approximated); for a " +
-      "lossless representation use get_page_json. Inline <span data-comment-id> " +
-      "tags in the markdown are comment highlight anchors (also present for " +
-      "RESOLVED threads) — treat them as markup, not page text.",
-    inputSchema: {
-      pageId: z.string().min(1),
-    },
-  },
-  async ({ pageId }) => {
-    const page = await docmostClient.getPage(pageId);
-    return jsonContent(page);
-  },
-);
+// 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 }) => {
@@ -201,6 +164,10 @@ registerShared(
 );

 // Tool: table_get
+// NOT in the shared registry: the MCP tool name `table_get` is noun-first while
+// the in-app key is `getTable` (verb-first), breaking the snake_case(inAppKey)
+// convention the shared registry enforces (shared-tool-specs.contract.spec.ts).
+// Renaming the public MCP tool would break external clients, so it stays inline.
 server.registerTool(
  "table_get",
  {
@@ -223,25 +190,10 @@ server.registerTool(
 );

 // Tool: table_insert_row
-// NOT in the shared registry: this transport names the table argument `table`,
-// while the in-app tool names it `tableRef` (ai-chat-tools.service.ts). Sharing
-// one buildShape would rename a public MCP parameter, so the table row/cell
-// tools stay per-transport by design.
-server.registerTool(
-  "table_insert_row",
-  {
-    description:
-      "Insert a row of plain-text cells into a table. `table` = `#<index>` or " +
-      "a block id inside it. `cells` = text per column (padded to the table's " +
-      "column count; error if more cells than columns). `index` = 0-based " +
-      "insert position (0 inserts before the header); omit to append at the end.",
-    inputSchema: {
-      pageId: z.string().min(1),
-      table: z.string().min(1),
-      cells: z.array(z.string()),
-      index: z.number().int().optional(),
-    },
-  },
+// 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,
@@ -254,22 +206,9 @@ server.registerTool(
 );

 // Tool: table_delete_row
-// NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
-// divergence as table_insert_row.
-server.registerTool(
-  "table_delete_row",
-  {
-    description:
-      "Delete the row at 0-based `index` from a table (`table` = `#<index>` or " +
-      "a block id inside it). Refuses to delete the table's only row. An " +
-      "out-of-range `index` throws. Deleting `index` 0 removes the header row, " +
-      "and the next row becomes the new header.",
-    inputSchema: {
-      pageId: z.string().min(1),
-      table: z.string().min(1),
-      index: z.number().int(),
-    },
-  },
+// 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);
@@ -277,24 +216,9 @@ server.registerTool(
 );

 // Tool: table_update_cell
-// NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
-// divergence as table_insert_row.
-server.registerTool(
-  "table_update_cell",
-  {
-    description:
-      "Set the plain-text content of cell [row,col] (0-based) in a table " +
-      "(`table` = `#<index>` or a block id inside it). Replaces the cell's " +
-      "content with a single text paragraph; for rich formatting use patch_node " +
-      "on the cell's paragraph id from table_get.",
-    inputSchema: {
-      pageId: z.string().min(1),
-      table: z.string().min(1),
-      row: z.number().int(),
-      col: z.number().int(),
-      text: z.string(),
-    },
-  },
+// 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,
@@ -308,22 +232,9 @@ server.registerTool(
 );

 // Tool: create_page
-server.registerTool(
-  "create_page",
-  {
-    description:
-      "Create a new page from Markdown in a space. Pass parentPageId to nest " +
-      "it under a parent; omit it to create at the space root.",
-    inputSchema: {
-      title: z.string().min(1).describe("Title of the page"),
-      content: z.string().min(1).describe("Markdown content"),
-      spaceId: z.string().min(1),
-      parentPageId: z
-        .string()
-        .optional()
-        .describe("Optional parent page ID to nest under"),
-    },
-  },
+// 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,
@@ -336,32 +247,11 @@ server.registerTool(
 );

 // Tool: update_page_json
-server.registerTool(
-  "update_page_json",
-  {
-    description:
-      "Replace a page's content with a raw ProseMirror JSON document " +
-      "(lossless write: preserves the block ids, callouts, tables and " +
-      "attributes you pass in). Typical flow: get_page_json -> modify the " +
-      "JSON -> update_page_json. Keep existing node ids intact so heading " +
-      "anchors and history stay stable. Minimal full-doc example: " +
-      '{"type":"doc","content":[{"type":"paragraph","content":' +
-      '[{"type":"text","text":"Hi"}]}]}. `content` may be a JSON object or a ' +
-      "JSON string (both accepted), and is OPTIONAL: omit it to update only " +
-      "the title (though prefer rename_page for a title-only change). " +
-      "Supplying neither content nor title is an error.",
-    inputSchema: {
-      pageId: z.string().min(1).describe("ID of the page to update"),
-      content: z
-        .any()
-        .optional()
-        .describe(
-          'ProseMirror document {"type":"doc","content":[...]} (JSON object or ' +
-            "JSON string). Omit to rename only.",
-        ),
-      title: z.string().optional().describe("Optional new title"),
-    },
-  },
+// 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
@@ -379,26 +269,11 @@ server.registerTool(
 );

 // Tool: export_page_markdown
-server.registerTool(
-  "export_page_markdown",
-  {
-    description:
-      "Export a page to a single self-contained, lossless Docmost-flavoured " +
-      "Markdown file (custom extensions): YAML-free meta header, body with " +
-      "inline comment anchors and diagrams, and a trailing comments-thread " +
-      "block. Designed for a download -> edit body -> import_page_markdown " +
-      "round-trip that preserves everything, including comment highlights. " +
-      "Comment THREADS are preserved in the file but are not re-pushed to the " +
-      "server on import.",
-    inputSchema: {
-      pageId: z.string().min(1),
-    },
-  },
-  async ({ pageId }) => {
-    const md = await docmostClient.exportPageMarkdown(pageId);
-    return { content: [{ type: "text" as const, text: md }] };
-  },
-);
+// 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(
@@ -422,22 +297,11 @@ registerShared(
 );

 // Tool: rename_page
-server.registerTool(
-  "rename_page",
-  {
-    description:
-      "Rename a page (change its title only) without touching or resending " +
-      "its content.",
-    inputSchema: {
-      pageId: z.string().min(1).describe("ID of the page to rename"),
-      title: z.string().min(1).describe("New title"),
-    },
-  },
-  async ({ pageId, title }) => {
-    const result = await docmostClient.renamePage(pageId, title);
-    return jsonContent(result);
-  },
-);
+// 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 }) => {
@@ -516,6 +380,10 @@ registerShared(SHARED_TOOL_SPECS.deleteNode, async ({ pageId, nodeId }) => {
 });

 // Tool: insert_image
+// MCP-only by design (NOT in the shared registry): the in-app AI-chat agent
+// exposes no image tools (insert/replace), so there is no second layer to unify
+// — a SHARED_TOOL_SPECS entry's tier/catalogLine are in-app metadata and the
+// catalog-partition test forbids a spec without a live in-app tool (#294).
 server.registerTool(
  "insert_image",
  {
@@ -561,6 +429,7 @@ server.registerTool(
 );

 // Tool: replace_image
+// MCP-only by design (see insert_image): no in-app equivalent, stays inline.
 server.registerTool(
  "replace_image",
  {
@@ -603,25 +472,10 @@ server.registerTool(
 );

 // Tool: share_page
-// INTENTIONAL per-transport divergence (not shared): the in-app copy adds a
-// security-confirmation framing ("only share when the user explicitly asked,
-// since this exposes the page to anyone with the link") tuned for the in-app
-// agent; this transport keeps the plain public-URL wording.
-server.registerTool(
-  "share_page",
-  {
-    description:
-      "Make a page publicly accessible (idempotent) and return its public " +
-      "URL. The URL format is <app>/share/<key>/p/<slugId>. This exposes the " +
-      "page content to ANYONE with the URL — do it only when explicitly asked.",
-    inputSchema: {
-      pageId: z.string().min(1).describe("ID of the page to share"),
-      searchIndexing: z
-        .boolean()
-        .optional()
-        .describe("Allow search engines to index the page (default true)"),
-    },
-  },
+// 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);
@@ -641,29 +495,11 @@ registerShared(SHARED_TOOL_SPECS.listShares, async () => {
 });

 // Tool: move_page
-server.registerTool(
-  "move_page",
-  {
-    description:
-      "Move a page under a new parent (nesting) or to the space root.",
-    inputSchema: {
-      pageId: z.string().min(1),
-      parentPageId: z
-        .string()
-        .nullable()
-        .optional()
-        .describe(
-          "Target parent page ID. Pass 'null' or empty string to move to root.",
-        ),
-      position: z
-        .string()
-        .min(5)
-        .optional()
-        .describe(
-          "fractional-index position key; min 5 chars; omit to append at the end.",
-        ),
-    },
-  },
+// 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;
@@ -698,49 +534,22 @@ server.registerTool(
 );

 // Tool: delete_page
-server.registerTool(
-  "delete_page",
-  {
-    description:
-      "Delete a single page by ID. SOFT delete only: the page is moved to " +
-      "trash and can be restored; nothing is permanently deleted.",
-    inputSchema: {
-      pageId: z.string().min(1),
-    },
-  },
-  async ({ pageId }) => {
-    await docmostClient.deletePage(pageId);
-    return {
-      content: [
-        { type: "text" as const, text: `Successfully deleted page ${pageId}` },
-      ],
-    };
-  },
-);
+// 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
-server.registerTool(
-  "list_comments",
-  {
-    description:
-      "List comments on a page in one call (pagination is handled " +
-      "internally). By DEFAULT only ACTIVE threads are returned; resolved " +
-      "threads (a resolved top-level comment and all its replies) are hidden " +
-      "and their count reported as `resolvedThreadsHidden` so you can re-query " +
-      "with `includeResolved: true` to see everything. Returns " +
-      "`{ items, resolvedThreadsHidden }`. Content is returned as Markdown.",
-    inputSchema: {
-      pageId: z.string().describe("ID of the page"),
-      includeResolved: z
-        .boolean()
-        .optional()
-        .describe(
-          "default only active threads; true — include resolved",
-        ),
-    },
-  },
+registerShared(
+  SHARED_TOOL_SPECS.listComments,
  async ({ pageId, includeResolved }) => {
    const comments = await docmostClient.listComments(pageId, includeResolved);
    return jsonContent(comments);
@@ -748,55 +557,11 @@ server.registerTool(
 );

 // Tool: create_comment
-// INTENTIONAL per-transport divergence (not shared): the in-app copy tunes the
-// guidance for the in-app agent (e.g. "retry with a corrected EXACT selection"
-// and "Reversible via the comment UI"); this transport keeps its own wording.
-server.registerTool(
-  "create_comment",
-  {
-    description:
-      "Create a new comment on a page. The comment is ALWAYS inline and is " +
-      "anchored to (highlights) its `selection` text — there are no page-level " +
-      "comments. Content is provided as Markdown and automatically converted. " +
-      "A top-level comment REQUIRES an exact `selection`; if the selection " +
-      "cannot be found in the page the call fails (no orphan comment is left). " +
-      "Replies (parentCommentId set) inherit the parent's anchor and take no " +
-      "selection. You may also attach a `suggestedText` proposing a replacement " +
-      "for the `selection`; a human applies (or rejects) it from the UI. When " +
-      "`suggestedText` is set the `selection` MUST occur exactly once in the " +
-      "page — expand it with surrounding context if it is ambiguous.",
-    inputSchema: {
-      pageId: z.string().describe("ID of the page to comment on"),
-      content: z.string().min(1).describe("Comment content in Markdown format"),
-      selection: z
-        .string()
-        .min(1)
-        // Enforce the documented 250-char cap to match the description above.
-        .max(250)
-        .optional()
-        .describe(
-          "EXACT contiguous text from a single paragraph/block to anchor the " +
-            "comment on (<=250 chars). Required for a top-level comment; omit " +
-            "only when replying via parentCommentId.",
-        ),
-      parentCommentId: z
-        .string()
-        .optional()
-        .describe("Parent comment ID to create a reply (max 2 nesting levels)"),
-      suggestedText: z
-        .string()
-        .min(1)
-        .max(2000)
-        .optional()
-        .describe(
-          "Optional proposed replacement (PLAIN TEXT) for the `selection`, " +
-            "applied by a human via the UI (never auto-applied). REQUIRES a " +
-            "`selection`; NOT allowed on a reply. When set, the `selection` must " +
-            "be UNIQUE in the page — expand it with surrounding context (still " +
-            "<=250 chars) if it occurs more than once, or the call is refused.",
-        ),
-    },
-  },
+// 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(
@@ -872,28 +637,9 @@ server.registerTool(
 );

 // Tool: resolve_comment
-server.registerTool(
-  "resolve_comment",
-  {
-    description:
-      "Resolve (close) or reopen a comment thread. Only top-level comments can " +
-      "be resolved — the server rejects resolving a reply. Reversible: pass " +
-      "resolved=false to reopen. Resolving keeps the thread and its replies " +
-      "(unlike delete_comment, which permanently removes them).",
-    inputSchema: {
-      commentId: z
-        .string()
-        .min(1)
-        .describe("ID of the top-level comment thread to resolve or reopen"),
-      resolved: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe(
-          "true (default) marks the thread resolved/closed; false reopens it",
-        ),
-    },
-  },
+// 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);
@@ -901,30 +647,10 @@ server.registerTool(
 );

 // Tool: check_new_comments
-server.registerTool(
-  "check_new_comments",
-  {
-    description:
-      "Check for new comments across pages in a space since a given timestamp. " +
-      "Optionally scope to a page subtree (folder). Returns only comments " +
-      "created after the specified time.",
-    inputSchema: {
-      spaceId: z.string().describe("Space ID to check for new comments"),
-      since: z
-        .string()
-        .min(1)
-        .describe(
-          "ISO 8601 timestamp — only return comments created after this time (e.g. '2026-03-10T00:00:00Z')",
-        ),
-      parentPageId: z
-        .string()
-        .optional()
-        .describe(
-          "Optional root page ID to scope the check to a subtree (folder). " +
-            "Only pages under this parent will be checked.",
-        ),
-    },
-  },
+// 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
@@ -1053,6 +779,8 @@ server.registerTool(
 );

 // Tool: insert_footnote
+// MCP-only by design (see insert_image): the in-app AI-chat agent exposes no
+// footnote tool, so there is no second layer to unify — stays inline (#294).
 server.registerTool(
  "insert_footnote",
  {
@@ -316,6 +316,34 @@ export const SHARED_TOOL_SPECS = {

  // --- share management ---

+  // Unified from the per-layer inline definitions (#294). Both layers already
+  // carried the "only share when explicitly asked" security framing (the
+  // "per-transport divergence" note on the old inline copies was stale), so
+  // there was no real behavioral divergence to preserve — only wording drift.
+  sharePage: {
+    mcpName: 'share_page',
+    inAppKey: 'sharePage',
+    // CANONICAL: merges the MCP copy's URL-format + idempotency detail with the
+    // in-app copy's reversibility note; keeps the security framing both had.
+    description:
+      'Make a page PUBLICLY accessible (idempotent) and return its public URL ' +
+      '(format: <app>/share/<key>/p/<slugId>). This exposes the page content ' +
+      'to ANYONE with the URL — only share when the user explicitly asked. ' +
+      'Reversible: unshare it later to revoke the public URL.',
+    tier: 'deferred',
+    catalogLine: 'sharePage — make a page publicly accessible and return its URL.',
+    // Reconciled: MCP's stricter .min(1) on pageId kept; field descriptions from
+    // the in-app copy. The MCP execute keeps its own `searchIndexing ?? true`
+    // default (a per-layer concern, not part of the shared schema).
+    buildShape: (z) => ({
+      pageId: z.string().min(1).describe('The id of the page to share.'),
+      searchIndexing: z
+        .boolean()
+        .optional()
+        .describe('Allow public search engines to index it (default true).'),
+    }),
+  },
+
  unsharePage: {
    mcpName: 'unshare_page',
    inAppKey: 'unsharePage',
@@ -509,4 +537,470 @@ export const SHARED_TOOL_SPECS = {
      pageId: z.string().min(1),
    }),
  },
+
+  // --- page tools (unified from the per-layer inline definitions, #294) ---
+  //
+  // Descriptions merge both layers (the MCP copy's richer structural notes + the
+  // in-app copy's "Reversible via history/trash" framing where it added one).
+  // Field constraints keep the MCP copy's stricter .min(1) EXCEPT where the
+  // in-app layer deliberately allowed a looser value (documented per field).
+
+  getPage: {
+    mcpName: 'get_page',
+    inAppKey: 'getPage',
+    description:
+      'Fetch a single page as Markdown by its id. Returns the page title and ' +
+      'its Markdown content. The Markdown conversion is LOSSY (block ids, exact ' +
+      'table/callout structure are approximated); for a lossless representation ' +
+      'use the lossless page-JSON read tool. Inline <span data-comment-id> tags in the markdown ' +
+      'are comment highlight anchors (also present for RESOLVED threads) — ' +
+      'treat them as markup, not page text.',
+    tier: 'core',
+    catalogLine: 'getPage — fetch a page as Markdown by its id.',
+    // Reconciled: MCP's stricter .min(1) kept; in-app's more-informative
+    // "(or slugId)" describe kept.
+    buildShape: (z) => ({
+      pageId: z.string().min(1).describe('The id (or slugId) of the page.'),
+    }),
+  },
+
+  listPages: {
+    mcpName: 'list_pages',
+    inAppKey: 'listPages',
+    description:
+      'List the most recent pages (ordered by updatedAt, descending), ' +
+      'optionally scoped to a single space. Returns a bounded list (default ' +
+      '50, max 100) — use search for lookups in large spaces. Pass tree:true ' +
+      "(with spaceId) to instead get the space's full page hierarchy as a " +
+      'nested tree.',
+    tier: 'core',
+    catalogLine: "listPages — list recent pages, or a space's full page tree.",
+    buildShape: (z) => ({
+      spaceId: z
+        .string()
+        .optional()
+        .describe('Optional space id to scope the listing to.'),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe('Maximum number of pages (default 50, max 100).'),
+      tree: z
+        .boolean()
+        .optional()
+        .describe(
+          "When true, return the space's full page hierarchy as a nested tree " +
+            '(children arrays) instead of the recent-by-updatedAt flat list. ' +
+            'Requires spaceId; ignores limit.',
+        ),
+    }),
+  },
+
+  createPage: {
+    mcpName: 'create_page',
+    inAppKey: 'createPage',
+    description:
+      'Create a new page with a Markdown body in a space, optionally under a ' +
+      'parent page (omit parentPageId to create at the space root). Returns ' +
+      'the new page id and title. Reversible: a page can be moved to trash ' +
+      'later.',
+    tier: 'deferred',
+    catalogLine: 'createPage — create a new page with a Markdown body in a space.',
+    // Reconciled schema DRIFT: the MCP copy pinned `content` to .min(1) while
+    // the in-app copy left it unbounded and DOCUMENTS an empty body as valid
+    // ("may be empty") — creating an empty page to fill in later is a real use
+    // case. The looser (no-min) form is kept, so create_page now also accepts an
+    // empty body (harmless — it creates an empty page) and no previously-valid
+    // in-app input is ever rejected. `title`/`spaceId` keep the MCP .min(1)
+    // (an empty title or space is never valid).
+    buildShape: (z) => ({
+      title: z.string().min(1).describe('The title of the new page.'),
+      content: z.string().describe('The page body as Markdown (may be empty).'),
+      spaceId: z.string().min(1).describe('The id of the space to create the page in.'),
+      parentPageId: z
+        .string()
+        .optional()
+        .describe('Optional parent page id to nest the new page under.'),
+    }),
+  },
+
+  movePage: {
+    mcpName: 'move_page',
+    inAppKey: 'movePage',
+    description:
+      'Move a page under a new parent page, or to the space root when no ' +
+      'parent is given. Reversible: move it back at any time.',
+    tier: 'deferred',
+    catalogLine: 'movePage — move a page under a new parent or to the space root.',
+    // Reconciled schema DRIFT: the MCP copy exposed a `position` field
+    // (fractional-index ordering) that the in-app copy lacked. Unified by
+    // KEEPING position (the in-app client already accepts an optional position
+    // arg, so the in-app execute now forwards it) — it is optional, so no
+    // previously-valid in-app call is rejected. `parentPageId` is `.nullable()`
+    // on both, so a real JSON null moves to root on either transport; the MCP
+    // execute additionally coerces the strings 'null'/'' to null as a robustness
+    // fallback (kept in its execute body, not in the shared schema).
+    buildShape: (z) => ({
+      pageId: z.string().min(1).describe('The id of the page to move.'),
+      parentPageId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe(
+          'Target parent page id. Null or omitted moves the page to the space ' +
+            'root.',
+        ),
+      position: z
+        .string()
+        .min(5)
+        .optional()
+        .describe(
+          'Optional fractional-index position key (min 5 chars); omit to ' +
+            'append at the end.',
+        ),
+    }),
+  },
+
+  renamePage: {
+    mcpName: 'rename_page',
+    inAppKey: 'renamePage',
+    description:
+      'Rename a page (change its title only; the body is untouched, never ' +
+      'resent). Reversible: rename back at any time.',
+    tier: 'deferred',
+    catalogLine: "renamePage — change a page's title only (body untouched).",
+    buildShape: (z) => ({
+      pageId: z.string().min(1).describe('The id of the page to rename.'),
+      title: z.string().min(1).describe('The new title.'),
+    }),
+  },
+
+  deletePage: {
+    mcpName: 'delete_page',
+    inAppKey: 'deletePage',
+    description:
+      'Move a page to the trash — SOFT delete only: the page can be restored ' +
+      'from trash and nothing is ever permanently deleted.',
+    tier: 'deferred',
+    catalogLine: 'deletePage — move a page to trash (soft delete, reversible).',
+    // GUARDRAIL preserved (§14 H4): the schema exposes ONLY pageId, so a
+    // permanentlyDelete/forceDelete flag can never reach the client through this
+    // tool (asserted by ai-chat-tools.service.spec.ts).
+    buildShape: (z) => ({
+      pageId: z.string().min(1).describe('The id of the page to move to trash.'),
+    }),
+  },
+
+  updatePageJson: {
+    mcpName: 'update_page_json',
+    inAppKey: 'updatePageJson',
+    description:
+      "Replace a page's content with a raw ProseMirror JSON document (lossless " +
+      'write: preserves the block ids, callouts, tables and attributes you pass ' +
+      'in). Typical flow: read the page-JSON view -> modify the JSON -> write it back. ' +
+      'Keep existing node ids intact so heading anchors and history stay ' +
+      'stable. Minimal full-doc example: {"type":"doc","content":[{"type":' +
+      '"paragraph","content":[{"type":"text","text":"Hi"}]}]}. `content` may be ' +
+      'a JSON object or a JSON string (both accepted), and is OPTIONAL: omit it ' +
+      'to update only the title (though prefer the rename-page tool for a title-only ' +
+      'change). Supplying neither content nor title is an error. Reversible: ' +
+      'the previous version is kept in page history.',
+    tier: 'deferred',
+    catalogLine:
+      "updatePageJson — overwrite a page's body with a full ProseMirror document.",
+    buildShape: (z) => ({
+      pageId: z.string().min(1).describe('ID of the page to update'),
+      content: z
+        .any()
+        .optional()
+        .describe(
+          'ProseMirror document {"type":"doc","content":[...]} (JSON object or ' +
+            'JSON string). Omit to update only the title.',
+        ),
+      title: z.string().optional().describe('Optional new title'),
+    }),
+  },
+
+  exportPageMarkdown: {
+    mcpName: 'export_page_markdown',
+    inAppKey: 'exportPageMarkdown',
+    // CANONICAL: the MCP copy (a strict superset of the terse in-app wording).
+    description:
+      'Export a page to a single self-contained, lossless Docmost-flavoured ' +
+      'Markdown file (custom extensions): YAML-free meta header, body with ' +
+      'inline comment anchors and diagrams, and a trailing comments-thread ' +
+      'block. Designed for a download -> edit body -> page-Markdown import ' +
+      'round-trip that preserves everything, including comment highlights. ' +
+      'Comment THREADS are preserved in the file but are not re-pushed to the ' +
+      'server on import.',
+    tier: 'deferred',
+    catalogLine:
+      'exportPageMarkdown — export a page to self-contained Markdown (body + comments).',
+    buildShape: (z) => ({
+      pageId: z.string().min(1).describe('The id of the page to export.'),
+    }),
+  },
+
+  // --- comment tools (unified from the per-layer inline definitions, #294) ---
+  //
+  // create_comment and resolve_comment previously carried a "per-transport
+  // divergence" note in BOTH layers; #294 unifies their schema + description
+  // here. Only the four tools that genuinely exist in BOTH layers live in the
+  // registry: create/list/resolve comment and check_new_comments.
+  //
+  // update_comment and delete_comment are intentionally NOT here: they exist
+  // ONLY on the standalone MCP server. The in-app agent deliberately exposes no
+  // hard comment edit/delete tool (comment edits are irreversible / not
+  // version-tracked; see the guardrail tests in ai-chat-tools.service.spec.ts),
+  // so there is nothing to unify — they stay inline in index.ts.
+
+  createComment: {
+    mcpName: 'create_comment',
+    inAppKey: 'createComment',
+    // CANONICAL: the in-app copy (the more-maintained one). It keeps the same
+    // rules as the MCP copy — inline-only, top-level requires a `selection`, no
+    // page-level comments, replies inherit the anchor, suggestedText must be
+    // unique — and adds the "retry with a corrected EXACT selection" and reply-
+    // to-reply-rejected guidance the MCP copy lacked. Execute-side validation
+    // (reject suggestedText on a reply, require a selection) stays per-layer.
+    description:
+      'Add an INLINE comment to a page, or reply to an existing top-level ' +
+      'comment (one level only — the backend rejects replies to replies). ' +
+      'The comment is anchored inline to the given exact `selection` text ' +
+      '(which gets highlighted); page-level comments are NOT supported. A ' +
+      'new top-level comment REQUIRES a `selection`. Replies inherit the ' +
+      "parent's anchor and take no selection. If the call fails with a " +
+      '"selection not found" error, retry with a corrected EXACT selection ' +
+      'copied verbatim from a single paragraph/block. You may also attach a ' +
+      '`suggestedText` proposing a replacement for the `selection` (a human ' +
+      'applies it from the UI); when set, the `selection` must occur exactly ' +
+      'once in the page. Reversible via the comment UI.',
+    tier: 'core',
+    catalogLine:
+      'createComment — add an inline comment (optionally with a suggested edit).',
+    // Reconciled schema: the field set is identical across both layers; the
+    // only constraint drift is `content`, which the MCP copy pinned to
+    // .min(1) while the in-app copy left unbounded — the stricter MCP form is
+    // kept (an empty comment body is never valid).
+    buildShape: (z) => ({
+      pageId: z.string().describe('The id of the page to comment on.'),
+      content: z.string().min(1).describe('The comment body as Markdown.'),
+      selection: z
+        .string()
+        .min(1)
+        .max(250)
+        .optional()
+        .describe(
+          'EXACT contiguous text from a SINGLE paragraph/block to anchor ' +
+            '(highlight) the comment on (<=250 chars, avoid spanning across ' +
+            'formatting boundaries). Required for a new top-level comment; ' +
+            'omit only when replying via parentCommentId.',
+        ),
+      parentCommentId: z
+        .string()
+        .optional()
+        .describe(
+          'Optional id of a TOP-LEVEL comment to reply to (one level ' +
+            'of replies only).',
+        ),
+      suggestedText: z
+        .string()
+        .min(1)
+        .max(2000)
+        .optional()
+        .describe(
+          'Optional proposed replacement (PLAIN TEXT) for the `selection`, ' +
+            'applied by a human via the UI (never auto-applied). REQUIRES a ' +
+            '`selection`; NOT allowed on a reply. When set, the `selection` ' +
+            'must be UNIQUE in the page — expand it with surrounding context ' +
+            '(still <=250 chars) if it occurs more than once, or the call is ' +
+            'refused.',
+        ),
+    }),
+  },
+
+  listComments: {
+    mcpName: 'list_comments',
+    inAppKey: 'listComments',
+    // CANONICAL: the two copies are near-identical; the MCP copy is the
+    // superset (it keeps the "(pagination is handled internally)" note the
+    // in-app copy dropped), so it is used verbatim.
+    description:
+      'List comments on a page in one call (pagination is handled ' +
+      'internally). By DEFAULT only ACTIVE threads are returned; resolved ' +
+      'threads (a resolved top-level comment and all its replies) are hidden ' +
+      'and their count reported as `resolvedThreadsHidden` so you can re-query ' +
+      'with `includeResolved: true` to see everything. Returns ' +
+      '`{ items, resolvedThreadsHidden }`. Content is returned as Markdown.',
+    tier: 'core',
+    catalogLine:
+      'listComments — list all comments on a page (including resolved).',
+    buildShape: (z) => ({
+      pageId: z.string().describe('ID of the page'),
+      includeResolved: z
+        .boolean()
+        .optional()
+        .describe('default only active threads; true — include resolved'),
+    }),
+  },
+
+  resolveComment: {
+    mcpName: 'resolve_comment',
+    inAppKey: 'resolveComment',
+    // CANONICAL: the MCP copy's richer wording, minus its snake_case reference
+    // to `delete_comment` (a sibling tool that does NOT exist in the in-app
+    // layer) — rephrased transport-neutrally per the registry convention.
+    description:
+      'Resolve (close) or reopen a top-level comment thread (reversible — ' +
+      'pass resolved=false to reopen). Only top-level comments can be ' +
+      'resolved; the server rejects resolving a reply. Resolving keeps the ' +
+      'thread and its replies intact (it is not a deletion).',
+    tier: 'core',
+    catalogLine: 'resolveComment — resolve or reopen a comment thread.',
+    // Reconciled schema: `resolved` drifted — the MCP copy made it optional
+    // with .default(true) (resolve is the common case, documented), the in-app
+    // copy made it required. The MCP form is kept (a strict superset: it never
+    // rejects a previously-valid input and adds a sensible default), and
+    // commentId keeps the MCP copy's stricter .min(1).
+    buildShape: (z) => ({
+      commentId: z
+        .string()
+        .min(1)
+        .describe('ID of the top-level comment thread to resolve or reopen'),
+      resolved: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe(
+          'true (default) marks the thread resolved/closed; false reopens it',
+        ),
+    }),
+  },
+
+  checkNewComments: {
+    mcpName: 'check_new_comments',
+    inAppKey: 'checkNewComments',
+    // CANONICAL: the MCP copy (the more detailed of the two). The MCP layer's
+    // execute-side guard that rejects an unparseable `since` timestamp stays in
+    // its execute body (per-layer logic), not in the shared schema.
+    description:
+      'Check for new comments across pages in a space since a given ' +
+      'timestamp. Optionally scope to a page subtree (folder). Returns only ' +
+      'comments created after the specified time.',
+    tier: 'deferred',
+    catalogLine:
+      'checkNewComments — find comments in a space created after a timestamp.',
+    // Reconciled schema: `since` keeps the MCP copy's stricter .min(1) (the
+    // in-app copy left it unbounded); field descriptions use the MCP copy's
+    // more detailed wording (it carries an example timestamp).
+    buildShape: (z) => ({
+      spaceId: z.string().describe('Space ID to check for new comments'),
+      since: z
+        .string()
+        .min(1)
+        .describe(
+          "ISO 8601 timestamp — only return comments created after this time " +
+            "(e.g. '2026-03-10T00:00:00Z')",
+        ),
+      parentPageId: z
+        .string()
+        .optional()
+        .describe(
+          'Optional root page ID to scope the check to a subtree (folder). ' +
+            'Only pages under this parent will be checked.',
+        ),
+    }),
+  },
+
+  // --- table tools (unified from the per-layer inline definitions, #294) ---
+  //
+  // These tools carried a "NOT shared" note in BOTH layers because of a single
+  // parameter-NAME drift: the MCP layer named the table reference `table` while
+  // the in-app layer named it `tableRef`. #294 reconciles that drift by unifying
+  // on the MCP name `table` — renaming the MCP public parameter would break
+  // external MCP clients, whereas the in-app parameter is model-facing
+  // (prompt-only) and safe to rename. The in-app execute bodies now destructure
+  // `table` instead of `tableRef` (nothing else changes). Descriptions take the
+  // MCP copy's richer wording (it documented `#<index>`, padding, header-row
+  // behavior) plus the in-app copy's "Reversible via page history" note; sibling
+  // tool references are phrased transport-neutrally.
+  //
+  // NOT here (kept inline in index.ts): table_get / getTable. Its MCP tool name
+  // is noun-first (`table_get`) while the in-app key is verb-first (`getTable`),
+  // so it breaks the snake_case(inAppKey) naming convention the registry enforces
+  // (shared-tool-specs.contract.spec.ts). Renaming the public MCP tool would
+  // break external clients, so it stays per-transport (its in-app param was still
+  // aligned to `table` for consistency with the migrated trio below).
+
+  tableInsertRow: {
+    mcpName: 'table_insert_row',
+    inAppKey: 'tableInsertRow',
+    description:
+      'Insert a row of plain-text cells into a table. `table` is `#<index>` ' +
+      'from the page outline, or a block id inside it. `cells` is the text per ' +
+      "column (padded to the table's column count; an error if more cells than " +
+      'columns). `index` is the 0-based insert position (0 inserts before the ' +
+      'header); omit to append at the end. Reversible via page history.',
+    tier: 'deferred',
+    catalogLine: 'tableInsertRow — insert a row of plain-text cells into a table.',
+    buildShape: (z) => ({
+      pageId: z.string().min(1).describe('The id of the page.'),
+      table: z
+        .string()
+        .min(1)
+        .describe('"#<index>" from the page outline, or a block id in the table.'),
+      cells: z.array(z.string()).describe('The cell texts for the row (one per column).'),
+      index: z
+        .number()
+        .int()
+        .optional()
+        .describe('0-based insert position (0 inserts before the header); omit to append.'),
+    }),
+  },
+
+  tableDeleteRow: {
+    mcpName: 'table_delete_row',
+    inAppKey: 'tableDeleteRow',
+    description:
+      'Delete the row at 0-based `index` from a table (`table` is `#<index>` ' +
+      'from the page outline, or a block id inside it). Refuses to delete the ' +
+      "table's only row; an out-of-range `index` throws. Deleting `index` 0 " +
+      'removes the header row, and the next row becomes the new header. ' +
+      'Reversible via page history.',
+    tier: 'deferred',
+    catalogLine: 'tableDeleteRow — delete a table row at a 0-based index.',
+    buildShape: (z) => ({
+      pageId: z.string().min(1).describe('The id of the page.'),
+      table: z
+        .string()
+        .min(1)
+        .describe('"#<index>" from the page outline, or a block id in the table.'),
+      index: z.number().int().describe('0-based row index to delete.'),
+    }),
+  },
+
+  tableUpdateCell: {
+    mcpName: 'table_update_cell',
+    inAppKey: 'tableUpdateCell',
+    description:
+      'Set the plain-text content of cell [row, col] (0-based) in a table ' +
+      '(`table` is `#<index>` from the page outline, or a block id inside it). ' +
+      "Replaces the cell's content with a single text paragraph; for rich " +
+      "formatting, patch the cell's paragraph id (obtained from reading the " +
+      'table) instead. Reversible via page history.',
+    tier: 'deferred',
+    catalogLine: 'tableUpdateCell — set the text of a table cell at [row, col].',
+    buildShape: (z) => ({
+      pageId: z.string().min(1).describe('The id of the page.'),
+      table: z
+        .string()
+        .min(1)
+        .describe('"#<index>" from the page outline, or a block id in the table.'),
+      row: z.number().int().describe('0-based row index.'),
+      col: z.number().int().describe('0-based column index.'),
+      text: z.string().describe('The new cell text.'),
+    }),
+  },
 } satisfies Record<string, SharedToolSpec>;
@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+// Import DIRECTLY from src (NOT the docmost-client barrel, which pulls in
+// collaboration.ts and mutates global DOM at import time).
+import { convertProseMirrorToMarkdown } from "../src/lib/markdown-converter.js";
+import { markdownToProseMirror } from "../src/lib/markdown-to-prosemirror.js";
+
+/**
+ * gitmost #377 (round-1 review, finding #1) — proof, against the REAL
+ * converter, that the transcript-insert boundary defense survives git-sync.
+ *
+ * The web bridge (apps/client .../gitmost/gitmost-recording.ts,
+ * `gitmostInsertTranscriptIntoEditor`) appends each transcript line as a
+ * PARAGRAPH text node. The paragraph serializer here (`case "paragraph"`) emits
+ * that text VERBATIM with no block-escape, so a line whose text begins with a
+ * col-0 markdown block trigger would, on the doc -> markdown -> doc git-sync
+ * cycle, silently re-parse into a heading / list / quote / callout / code block.
+ * That missing block-escape is the pre-existing root cause; the bridge's
+ * boundary defense prepends an invisible zero-width space (U+200B) to a line
+ * that begins with such a trigger, shifting it off column 0.
+ *
+ * This test keeps a COPY of the bridge's trigger regex (the bridge is in a
+ * different package and can't be imported here) and asserts:
+ *   1. bare trigger lines DO corrupt (documents the root cause), and
+ *   2. the ZWSP-neutralized form round-trips as a single PARAGRAPH with the
+ *      text byte-preserved.
+ */
+
+const ZWSP = ""; // U+200B
+
+// MUST stay in sync with GITMOST_MD_BLOCK_TRIGGER_RE in the client bridge.
+const MD_BLOCK_TRIGGER_RE =
+  /^(?:#{1,6}(?:\s|$)|[-*+](?:\s|$)|>|\d+[.)](?:\s|$)|```|~~~|\||([-*_])(?:\s*\1){2,}\s*$)/;
+
+const doc = (...nodes: any[]) => ({ type: "doc", content: nodes });
+const para = (t: string) => ({
+  type: "paragraph",
+  content: [{ type: "text", text: t }],
+});
+
+const roundtrip = async (text: string) => {
+  const md = convertProseMirrorToMarkdown(doc(para(text)));
+  const back = await markdownToProseMirror(md);
+  return back.content as any[];
+};
+
+describe("gitmost transcript neutralization (git-sync round-trip)", () => {
+  // Lines that, at column 0, the serializer's missing block-escape would let
+  // git-sync re-parse into a non-paragraph block.
+  const triggerLines = [
+    "- dash",
+    "* star",
+    "+ plus",
+    "> quote",
+    "# hash",
+    "1. one",
+    "1) one",
+    "> [!info] note",
+    "```js",
+    "~~~",
+    // Solid + spaced thematic breaks — these re-parse into a `horizontalRule`,
+    // which carries NO text, so a bare separator line LOSES its text entirely
+    // (round-2 finding). `_` also only forms a block via this construct.
+    "---",
+    "***",
+    "___",
+    "- - -", // spaced dash break (solid form is caught by [-*+]\s too, but this is the break)
+    "_ _ _",
+  ];
+
+  it("BARE trigger lines corrupt into non-paragraph blocks (root cause)", async () => {
+    for (const line of triggerLines) {
+      const blocks = await roundtrip(line);
+      // At least one produced block is NOT a paragraph — i.e. corruption.
+      const allParagraphs = blocks.every((b) => b.type === "paragraph");
+      expect(
+        allParagraphs,
+        `expected "${line}" to corrupt when inserted bare`,
+      ).toBe(false);
+    }
+  });
+
+  it("BARE solid thematic breaks corrupt into a text-LOSING horizontalRule", async () => {
+    // The severe case: no text node survives. Documents why neutralization
+    // matters more here than for list/quote (where the text survived).
+    for (const line of ["---", "***", "___"]) {
+      const blocks = await roundtrip(line);
+      expect(blocks.map((b) => b.type)).toContain("horizontalRule");
+      // No block carries the original text anywhere.
+      const flat = JSON.stringify(blocks);
+      expect(flat).not.toContain(line);
+    }
+  });
+
+  it("ZWSP-neutralized trigger lines round-trip as a single paragraph, text preserved", async () => {
+    for (const line of triggerLines) {
+      // The regex must actually classify each as a trigger.
+      expect(MD_BLOCK_TRIGGER_RE.test(line), `regex missed "${line}"`).toBe(
+        true,
+      );
+      const neutralized = ZWSP + line;
+      const blocks = await roundtrip(neutralized);
+
+      expect(blocks).toHaveLength(1);
+      expect(blocks[0].type).toBe("paragraph");
+      // Text is byte-preserved (ZWSP + original line), so the display is the
+      // original line with only an invisible leading character.
+      expect(blocks[0].content[0].text).toBe(neutralized);
+    }
+  });
+
+  it("normal host-prefixed lines never match the trigger regex and round-trip byte-exact", async () => {
+    for (const line of [
+      "You: hello there",
+      "Speaker 1: - and then a dash mid-line",
+      "Speaker 2: 1. not a list",
+    ]) {
+      expect(MD_BLOCK_TRIGGER_RE.test(line)).toBe(false);
+      const blocks = await roundtrip(line);
+      expect(blocks).toHaveLength(1);
+      expect(blocks[0].type).toBe("paragraph");
+      expect(blocks[0].content[0].text).toBe(line);
+    }
+  });
+});
@@ -0,0 +1,68 @@
+diff --git a/dist/index.js b/dist/index.js
+index ae447a12f7823ec0a00837ee9f0eb809a610d5f8..a3402b2c2d021ef432cfa76e35d370073d525135 100644
+--- a/dist/index.js
+++ b/dist/index.js
+@@ -6578,9 +6578,19 @@ function createOutputTransformStream(output) {
+         controller.enqueue({ part: chunk, partialOutput: void 0 });
+         return;
+       }
+-      text2 += chunk.text;
+       textChunk += chunk.text;
+       textProviderMetadata = (_a21 = chunk.providerMetadata) != null ? _a21 : textProviderMetadata;
+      if (output == null) {
+        // PATCH(docmost #OOM): no output strategy requested -> publish each
+        // text-delta immediately and do NOT build cumulative partialOutput
+        // snapshots. Unpatched, the default text() output snapshots the ENTIRE
+        // accumulated turn text on every delta (O(n^2) memory) and those
+        // snapshots pile up in the never-consumed leftover tee branch of
+        // DefaultStreamTextResult.baseStream -> heap OOM on long agent turns.
+        publishTextChunk({ controller });
+        return;
+      }
+      text2 += chunk.text;
+       const result = await output.parsePartialOutput({ text: text2 });
+       if (result !== void 0) {
+         const currentJson = JSON.stringify(result.partial);
+@@ -6959,7 +6969,7 @@ var DefaultStreamTextResult = class {
+         })
+       );
+     }
+-    this.baseStream = stream.pipeThrough(createOutputTransformStream(output != null ? output : text())).pipeThrough(eventProcessor);
+    this.baseStream = stream.pipeThrough(createOutputTransformStream(output)).pipeThrough(eventProcessor);
+     const { maxRetries, retry } = prepareRetries({
+       maxRetries: maxRetriesArg,
+       abortSignal
+diff --git a/dist/index.mjs b/dist/index.mjs
+index 663875332e3f9a9bd167c25583c515876f42951b..b840b0502c9894df983e0154805abb80e70e6331 100644
+--- a/dist/index.mjs
+++ b/dist/index.mjs
+@@ -6501,9 +6501,19 @@ function createOutputTransformStream(output) {
+         controller.enqueue({ part: chunk, partialOutput: void 0 });
+         return;
+       }
+-      text2 += chunk.text;
+       textChunk += chunk.text;
+       textProviderMetadata = (_a21 = chunk.providerMetadata) != null ? _a21 : textProviderMetadata;
+      if (output == null) {
+        // PATCH(docmost #OOM): no output strategy requested -> publish each
+        // text-delta immediately and do NOT build cumulative partialOutput
+        // snapshots. Unpatched, the default text() output snapshots the ENTIRE
+        // accumulated turn text on every delta (O(n^2) memory) and those
+        // snapshots pile up in the never-consumed leftover tee branch of
+        // DefaultStreamTextResult.baseStream -> heap OOM on long agent turns.
+        publishTextChunk({ controller });
+        return;
+      }
+      text2 += chunk.text;
+       const result = await output.parsePartialOutput({ text: text2 });
+       if (result !== void 0) {
+         const currentJson = JSON.stringify(result.partial);
+@@ -6882,7 +6892,7 @@ var DefaultStreamTextResult = class {
+         })
+       );
+     }
+-    this.baseStream = stream.pipeThrough(createOutputTransformStream(output != null ? output : text())).pipeThrough(eventProcessor);
+    this.baseStream = stream.pipeThrough(createOutputTransformStream(output)).pipeThrough(eventProcessor);
+     const { maxRetries, retry } = prepareRetries({
+       maxRetries: maxRetriesArg,
+       abortSignal
@@ -44,6 +44,9 @@ overrides:
  ip-address: 10.1.1

 patchedDependencies:
+  ai@6.0.134:
+    hash: f60bfc3357e01e1f3978c6c40fdd65aeb33fefaad7179cde8676465b6c5ff4d9
+    path: patches/ai@6.0.134.patch
  scimmy@1.3.5:
    hash: 775d80f86830b2c5dd1a250c9802c10f8fc3da3c7898373de5aa0c23993d1673
    path: patches/scimmy@1.3.5.patch
@@ -543,6 +546,9 @@ importers:
      '@docmost/pdf-inspector':
        specifier: 1.9.6
        version: 1.9.6
+      '@docmost/prosemirror-markdown':
+        specifier: workspace:*
+        version: link:../../packages/prosemirror-markdown
      '@fastify/cookie':
        specifier: ^11.0.2
        version: 11.0.2
@@ -623,10 +629,10 @@ importers:
        version: 8.3.0(socket.io-adapter@2.5.4)
      ai:
        specifier: ^6.0.134
-        version: 6.0.134(zod@4.3.6)
+        version: 6.0.134(patch_hash=f60bfc3357e01e1f3978c6c40fdd65aeb33fefaad7179cde8676465b6c5ff4d9)(zod@4.3.6)
      ai-sdk-ollama:
        specifier: ^3.8.1
-        version: 3.8.1(ai@6.0.134(zod@4.3.6))(zod@4.3.6)
+        version: 3.8.1(ai@6.0.134(patch_hash=f60bfc3357e01e1f3978c6c40fdd65aeb33fefaad7179cde8676465b6c5ff4d9)(zod@4.3.6))(zod@4.3.6)
      bcrypt:
        specifier: ^6.0.0
        version: 6.0.0
@@ -16355,17 +16361,17 @@ snapshots:

  agent-base@7.1.4: {}

-  ai-sdk-ollama@3.8.1(ai@6.0.134(zod@4.3.6))(zod@4.3.6):
+  ai-sdk-ollama@3.8.1(ai@6.0.134(patch_hash=f60bfc3357e01e1f3978c6c40fdd65aeb33fefaad7179cde8676465b6c5ff4d9)(zod@4.3.6))(zod@4.3.6):
    dependencies:
      '@ai-sdk/provider': 3.0.8
      '@ai-sdk/provider-utils': 4.0.21(zod@4.3.6)
-      ai: 6.0.134(zod@4.3.6)
+      ai: 6.0.134(patch_hash=f60bfc3357e01e1f3978c6c40fdd65aeb33fefaad7179cde8676465b6c5ff4d9)(zod@4.3.6)
      jsonrepair: 3.13.3
      ollama: 0.6.3
    transitivePeerDependencies:
      - zod

-  ai@6.0.134(zod@4.3.6):
+  ai@6.0.134(patch_hash=f60bfc3357e01e1f3978c6c40fdd65aeb33fefaad7179cde8676465b6c5ff4d9)(zod@4.3.6):
    dependencies:
      '@ai-sdk/gateway': 3.0.77(zod@4.3.6)
      '@ai-sdk/provider': 3.0.8