fix(git-sync): round-trip the spoiler mark and image caption

After merging develop, git-sync's markdown converter still predated two
editor features and silently dropped them on every sync:

- Spoiler mark (#259): had no schema entry, so `<span data-spoiler>` from
  the canonical lossless form re-parsed as plain text and the mark was
  lost. Register a Spoiler mark mirroring @docmost/editor-ext + the MCP
  schema, and emit `<span data-spoiler="true">…</span>` on PM->MD.
- Image caption (#221): the converter assumed no caption attribute existed
  (the branch was dead). The image schema now carries a plain-text caption
  (data-caption); register it and route a captioned image through the raw
  <img> form (same lossless convention as the other Docmost image attrs).
  Caption-less images keep the lighter `![](src)` form.

Both survive PM->MD->PM unchanged; raw `<span data-spoiler>` / `<img
data-caption>` in incoming markdown parse back. New round-trip tests in
markdown-roundtrip-spoiler-caption.test.ts; schema-surface snapshot updated.

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

.env.example

@@ -153,7 +153,7 @@ MCP_DOCMOST_PASSWORD=
 # (including normal human edits) would then be mis-attributed as AI.
 
 # Agent-roles catalog source: an http(s):// base URL to the catalog's raw files
-# (the server appends /index.json and /bundles/<id>/<lang>.json). This value is
+# (the server appends /index.yaml and /bundles/<id>/<lang>.yaml). This value is
 # baked into the Docker image at build time per branch (see the Dockerfile ARG
 # AI_AGENT_ROLES_CATALOG_URL and the CI build-args). Set it here only to point a
 # local/non-Docker run at a catalog; if unset, the "import role from catalog"
@@ -223,3 +223,45 @@ MCP_DOCMOST_PASSWORD=
 # FAILS CLOSED if Redis is unavailable (default: 1,000,000 tokens per workspace
 # per rolling day).
 # SHARE_AI_WORKSPACE_TOKEN_BUDGET_PER_DAY=1000000
+
+# --- GIT-SYNC (native two-way Docmost <-> git Markdown sync) ---
+# Master switch. Off by default. When 'true', GIT_SYNC_SERVICE_USER_ID below is
+# REQUIRED (the service account that git-originated create/move/rename/delete are
+# attributed to) — the server refuses to boot with sync enabled and no user id.
+# GIT_SYNC_ENABLED=false
+#
+# Serve the per-space vaults over smart-HTTP (the /git host). Defaults to
+# GIT_SYNC_ENABLED when unset.
+# GIT_SYNC_HTTP_ENABLED=false
+#
+# REQUIRED when GIT_SYNC_ENABLED=true: id of the user that git-originated page
+# operations (create / move / rename / delete) are attributed to.
+# GIT_SYNC_SERVICE_USER_ID=
+#
+# Where the per-space working vaults live (non-bare repos; the engine needs a
+# working tree).
+# Defaults to "<DATA_DIR or ./data>/git-sync".
+# GIT_SYNC_DATA_DIR=
+#
+# SCAFFOLDING for the DEFERRED remote-push feature (SPEC §7) — NOT yet
+# implemented and currently INERT. The vendored sync engine does not consume
+# this value anywhere (git push to a remote is deferred), so setting it has NO
+# effect today: vaults remain local-only regardless. It is validated and carried
+# only so the wiring is ready for when remote push lands. The intended future
+# shape is a per-space URL template where the literal "{spaceId}" is substituted
+# per space (e.g. git@host:vault-{spaceId}.git).
+# GIT_SYNC_REMOTE_TEMPLATE=
+#
+# Poll-safety interval in ms — the cadence of the background reconcile cycle
+# (default: 15000).
+# GIT_SYNC_POLL_INTERVAL_MS=15000
+#
+# Debounce window in ms for collapsing bursts of page edits into one sync cycle
+# (default: 2000).
+# GIT_SYNC_DEBOUNCE_MS=2000
+#
+# Watchdog timeout in ms for the spawned `git http-backend` process serving a
+# git smart-HTTP push (default: 120000). A stalled/hung receive-pack is killed
+# after this deadline so it cannot hold the per-space lock forever.
+# GIT_SYNC_BACKEND_TIMEOUT_MS=120000
+#

.github/workflows/develop.yml

@@ -25,6 +25,7 @@ jobs:
   build:
     needs: test
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -65,6 +66,8 @@ jobs:
   # deploy block.
   e2e-server:
     runs-on: ubuntu-latest
+    # Hard cap: the full-AppModule e2e leaks open handles and hung jest to the 6h max.
+    timeout-minutes: 15
     env:
       DATABASE_URL: postgresql://docmost:docmost@localhost:5432/docmost
       REDIS_URL: redis://localhost:6379
@@ -123,6 +126,7 @@ jobs:
   # a red run plus GitHub's email to the pusher is the notification mechanism.
   e2e-mcp:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     env:
       DATABASE_URL: postgresql://docmost:docmost@localhost:5432/docmost
       REDIS_URL: redis://localhost:6379

.github/workflows/test.yml

@@ -15,6 +15,7 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     # Real Postgres + Redis so the server integration suite (`*.int-spec.ts`,
     # behind `pnpm --filter server test:int`) runs in CI (red-team finding #7).
     # Without it, cost-cap / FK-cascade / jsonb-round-trip / real-apply tests
@@ -68,6 +69,13 @@ jobs:
       - name: Build editor-ext
         run: pnpm --filter @docmost/editor-ext build
 
+      # git-sync and mcp are no longer committed in built form (build/ is
+      # gitignored), so CI must compile them: the server resolves both via their
+      # built build/index.js. The server pretest also builds them, but building
+      # here keeps it explicit and independent of pnpm lifecycle ordering.
+      - name: Build git-sync and mcp
+        run: pnpm --filter @docmost/git-sync build && pnpm --filter @docmost/mcp build
+
       - name: Run unit tests
         run: pnpm -r test
 

.gitignore

@@ -5,6 +5,12 @@ data
 # compiled output
 /dist
 /node_modules
+# workspace package node_modules (pnpm symlinks — never commit; they bake
+# machine-local store paths) and the git-sync compiled output (built in CI/Docker
+# via `pnpm build`, never committed, so src/ and prod can never silently diverge).
+packages/*/node_modules/
+packages/git-sync/build/
+packages/mcp/build/
 
 # Logs
 logs

AGENTS.md

@@ -182,7 +182,7 @@ tea issues create --repo vvzvlad/gitmost --labels feature \
 
 ## Monorepo layout
 
-pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Four workspace packages:
+pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Five workspace packages:
 
 | Path | Name | Stack | Role |
 | --- | --- | --- | --- |
@@ -190,6 +190,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`. Does **not** import `editor-ext` — it keeps its own vendored mirror of the schema in `packages/mcp/src/lib/` |
+| `packages/git-sync` | `@docmost/git-sync` | Tiptap/ProseMirror, Yjs, git | Pure ProseMirror↔Markdown converter plus the two-way Docmost↔git Markdown sync engine. Bundled into the server (loaded over the ESM bridge), built in CI and the Dockerfile. Does **not** import `editor-ext` — it keeps its own vendored mirror of the document schema (kept in sync with `editor-ext`). |
 
 `build` targets are Nx-cached and dependency-ordered (`dependsOn: ["^build"]`), so `editor-ext` builds before the apps. `nx.json` sets `affected.defaultBase: main`.
 
@@ -243,8 +244,10 @@ Migration files live in `apps/server/src/database/migrations/` and are named `YY
 
 The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes `robots.txt`, public share pages, and `mcp` from the prefix). A `preHandler` hook enforces that a resolved `workspaceId` exists for most `/api` routes (multi-tenant by hostname/subdomain via `DomainMiddleware`). `GET /api/sb/:id` (the anonymous blob-sandbox read route) is listed in that preHandler's `excludedPaths`, so it is exempt from workspace resolution and carries no session auth at all (its capability is the unguessable UUID + TTL + TLS) — unlike `/api/files/public/...`, which still resolves a workspace and requires a workspace-bound attachment JWT. Auth is JWT (cookie + bearer); authorization is **CASL** (`core/casl`) — every data access is scoped to the user's abilities.
 
+Two routes are mounted **outside** the `/api` prefix at the root, as raw Fastify routes that bypass the Nest pipeline (so neither `DomainMiddleware` nor `ThrottlerGuard` runs for them — each resolves the workspace and throttles itself): `/mcp` (the embedded MCP server, see below) and `/git/<spaceId>.git/...` (the git-sync smart-HTTP host, see below). Both share `mcp-auth.helpers.ts` (HTTP-Basic parsing, `FailedLoginLimiter`, `clientIp`) and the common `resolveRequestWorkspace` helper.
+
 ### Module structure (server)
-`AppModule` wires integration modules (`integrations/*`: storage [local/S3/Azure], mail, queue [BullMQ on Redis], security, telemetry, throttle, `mcp`, `ai`) plus `CoreModule`, `DatabaseModule`, and `CollaborationModule`. `CoreModule` (`core/*`) holds the domain modules: `page`, `space`, `comment`, `workspace`, `user`, `auth`, `group`, `attachment`, `search`, `share`, `ai-chat`, etc. Each domain module follows NestJS controller → service → repo layering; DB repos live under `database/repos` and are injected app-wide from the global `DatabaseModule`.
+`AppModule` wires integration modules (`integrations/*`: storage [local/S3/Azure], mail, queue [BullMQ on Redis], security, telemetry, throttle, `mcp`, `ai`, `git-sync`) plus `CoreModule`, `DatabaseModule`, and `CollaborationModule`. `CoreModule` (`core/*`) holds the domain modules: `page`, `space`, `comment`, `workspace`, `user`, `auth`, `group`, `attachment`, `search`, `share`, `ai-chat`, etc. Each domain module follows NestJS controller → service → repo layering; DB repos live under `database/repos` and are injected app-wide from the global `DatabaseModule`.
 
 **EE removal artifact:** `app.module.ts` still contains a `try/require('./ee/ee.module')` stub. That path no longer exists, so the require fails and is swallowed (it only hard-exits when `CLOUD === 'true'`). Treat EE as gone — do not add code that depends on it.
 
@@ -260,10 +263,16 @@ The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes
    - `core/ai-chat/embedding/` — RAG indexer + a BullMQ consumer on `AI_QUEUE` that embeds pages into `page_embeddings` (vector search), complementing Postgres full-text search. Pages are (re)indexed on edit; `AI_EMBEDDING_TIMEOUT_MS` bounds a hung embeddings endpoint.
    - `core/ai-chat/external-mcp/` — admins can attach external MCP servers (e.g. Tavily) to give the agent web access. **`ssrf-guard.ts` validates outbound MCP URLs against SSRF** — keep that guard in the path when touching external-MCP connection logic.
 
+### Git-sync (native two-way Docmost ↔ git Markdown sync)
+`integrations/git-sync/` (`GitSyncModule`) + the vendored pure engine in `packages/git-sync`. Off by default; gated by the `GIT_SYNC_ENABLED` master switch (and `GIT_SYNC_SERVICE_USER_ID`, the account git-originated writes are attributed to). Per-space opt-in via `space.settings.gitSync.enabled`, with a second per-space toggle `space.settings.gitSync.autoMergeConflicts` that changes PUSH behavior for a still-conflicted page (one carrying `<<<<<<<`/`>>>>>>>` markers): **off (the safe default)** records a per-page failure and holds the refs so the user resolves the git conflict first (markers never reach Docmost); **on** strips the marker lines and pushes both sides' content. Each enabled space gets an on-disk working "vault" repo; the `GitSyncOrchestrator` runs a debounced + poll-backstop reconcile cycle (PULL Docmost→vault, PUSH vault→Docmost) under a per-space Redis leader lock + in-process mutex (`SpaceLockService`). Writes go through the collaboration layer (so concurrent human edits aren't clobbered) and are stamped `lastUpdatedSource = 'git-sync'` for the listener loop-guard. The in-process `setInterval` orchestration + best-effort lock (no fencing tokens) is a known multi-replica limitation — BullMQ + fencing is the documented future direction.
+
+- **`/git` smart-HTTP host** (`integrations/git-sync/http/`, gated additionally by `GIT_SYNC_HTTP_ENABLED`, which defaults to `GIT_SYNC_ENABLED`): a raw root-mounted Fastify route `/git/<spaceId>.git/...` (registered in `main.ts`, NOT under `/api`) that bridges `git clone`/`fetch`/`push` to `git http-backend`. It authenticates HTTP Basic against `AuthService` (throttled by a `FailedLoginLimiter` mirroring the `/mcp` path), authorizes via `SpaceAbilityFactory` (read = fetch, Manage = push), and gates existence so a non-member gets the SAME 404 as a missing/sync-disabled space (never 403 — that would leak space existence). A push runs the receive-pack under the space lock, then a reconcile cycle.
+- **Schema mirror:** `packages/git-sync/src/lib/docmost-schema.ts` is one of the **three** hand-synced copies of the Tiptap document schema (see Client structure) — keep it in lockstep with `editor-ext` (canonical) and `packages/mcp`.
+
 ### 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. Note `packages/mcp` does *not* depend on `editor-ext`; it carries its own mirrored copy of the schema, so keep the two in sync manually when the document schema changes.
+- 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. Note neither `packages/mcp` nor `packages/git-sync` depends on `editor-ext`; each carries its own mirrored copy of the schema. There are now **three** independent copies (`editor-ext` is canonical, plus `packages/mcp` and `packages/git-sync`), so keep all three in sync manually when the document schema changes.
 - 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`.
 

CHANGELOG.md

@@ -12,6 +12,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Native two-way Docmost ↔ git Markdown sync.** Opt-in per space (Space
+  settings → a git-sync toggle, plus an `autoMergeConflicts` toggle that controls
+  whether a still-conflicted page is held back or pushed with its conflict
+  markers stripped): each enabled space is mirrored to an on-disk git "vault" of
+  Markdown files and reconciled in both directions (Docmost → vault and vault →
+  Docmost) on a debounced + poll-backstop cycle, under a per-space lock, writing
+  through the collaboration layer so concurrent human edits aren't clobbered.
+  Git-originated changes are attributed to a configurable service account and
+  carry a "git-sync" provenance badge in page history. Optionally exposes a `/git`
+  smart-HTTP host so you can `git clone`/`fetch`/`push` a space directly (HTTP
+  Basic auth, space-permission authorized). Off by default and configured via the
+  `GIT_SYNC_*` environment variables, including `GIT_SYNC_ENABLED`,
+  `GIT_SYNC_SERVICE_USER_ID`, and `GIT_SYNC_HTTP_ENABLED` (see `.env.example`).
+  (#119)
+- **Editable captions for images.** Images gain an optional caption shown
+  below them, edited inline from the image bubble menu and stored as a `caption` attribute. Captions round-trip
+  losslessly through markdown as a `data-caption` attribute on the image, so
+  they survive export/import unchanged. (#221)
+
 - **Quick-create regular and temporary notes from the Home and Space screens.**
   The Home screen now shows a second action next to "New note" that creates a
   *temporary* note (one that auto-moves to Trash after the workspace lifetime),
@@ -67,6 +86,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `nosniff` + restrictive CSP + attachment disposition for non-image mimes) and
   are RAM-only, bound to the instance that created them. Tunable via five
   `SANDBOX_*` env vars (see `.env.example`). (#243)
+- **Inline spoiler mark — hide text behind click-to-reveal blur.** Selected text
+  can be marked as a spoiler from a new bubble-menu toggle, or typed Discord-style
+  with the `||text||` input rule; the rendered span blurs until clicked to reveal.
+  The mark is preserved losslessly through Markdown export/import (as a raw
+  `<span data-spoiler="true">…</span>`) and on public shares. (#259)
 
 ### Changed
 
@@ -76,6 +100,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   toggle. Previously the create call defaulted to including sub-pages, silently
   exposing every child of a freshly shared page. (#216)
 
+- **The agent-roles catalog is now stored as YAML instead of JSON.** Each role's
+  long `instructions` system prompt is a literal block scalar (`|-`), so editing
+  a single sentence shows up as a line-by-line diff and the prompt is editable as
+  plain multi-line text rather than one escaped JSON string. The catalog content
+  files become `index.yaml` and `bundles/<id>/<lang>.yaml` (old `.json` removed);
+  the resolved role content is byte-for-byte identical, so no role `version` is
+  bumped. The server fetches `<base>/index.yaml` and
+  `<base>/bundles/<id>/<lang>.yaml`, parsing them with the `yaml` library's safe,
+  JSON-compatible schema (no custom tags / no code execution) behind the same
+  size-cap, redirect and path-traversal guards. The `AI_AGENT_ROLES_CATALOG_URL`
+  base-URL contract is unchanged. (#229)
+
 ### Fixed
 
 - **Internal links in exported Markdown no longer lose their visible text.** A
@@ -112,6 +148,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   "This address is in use. Saving will move it to this page." — and keeps Save
   enabled, so the existing reassign-confirm flow (`409 ALIAS_REASSIGN_REQUIRED` →
   "Move custom address?") is discoverable instead of reading as terminal. (#227)
+- **A non-empty page can no longer be silently lost to a momentarily-empty live
+  document.** The server's persistence guard now refuses to overwrite non-empty
+  persisted content with an empty live Y.Doc — a transient emptiness from a
+  glitch, a bad merge, or an emptying transclusion no longer wipes the saved
+  page. A *deliberate* clear still works: a select-all + Delete in the editor
+  emits a single-use "intentional clear" signal that lets exactly that one empty
+  write through the guard, so genuinely emptying a page is persisted while
+  accidental empties are blocked. (#248, #251)
 
 ### Security
 

Dockerfile

@@ -17,8 +17,9 @@ RUN pnpm build
 
 FROM base AS installer
 
+# git: required by the git-sync VaultGit (shells out to git)
 RUN apt-get update \
-  && apt-get install -y --no-install-recommends curl bash \
+  && apt-get install -y --no-install-recommends curl bash git \
   && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
@@ -38,6 +39,14 @@ COPY --from=builder /app/packages/editor-ext/dist /app/packages/editor-ext/dist
 COPY --from=builder /app/packages/editor-ext/package.json /app/packages/editor-ext/package.json
 COPY --from=builder /app/packages/mcp/build /app/packages/mcp/build
 COPY --from=builder /app/packages/mcp/package.json /app/packages/mcp/package.json
+# git-sync: the server loads @docmost/git-sync at runtime via the loader
+# (git-sync.loader.ts), which deliberately does NOT `require()` it — the package is
+# ESM-only, so the loader uses `require.resolve` + a dynamic `import()`. Without
+# these copied build artifacts that resolve/import fails and the server crashes on
+# first use. Built fresh by the builder's `pnpm build` (nx builds the package's tsc
+# `build` target).
+COPY --from=builder /app/packages/git-sync/build /app/packages/git-sync/build
+COPY --from=builder /app/packages/git-sync/package.json /app/packages/git-sync/package.json
 
 # Copy root package files
 COPY --from=builder /app/package.json /app/package.json

agent-roles-catalog/README.md

@@ -10,17 +10,23 @@ executable application logic except the validation script.
 
 ```
 agent-roles-catalog/
-  index.json                  # the catalog manifest: bundles, languages, role versions
+  index.yaml                  # the catalog manifest: bundles, languages, role versions
   bundles/
     <bundle-id>/
-      <lang>.json             # one file per declared language (e.g. ru.json, en.json)
+      <lang>.yaml             # one file per declared language (e.g. ru.yaml, en.yaml)
   scripts/
-    check.mjs                 # validates the catalog (no dependencies)
+    check.mjs                 # validates the catalog (uses the `yaml` parser)
     content-hashes.json       # check artifact: per-role content-hash lock (NOT served)
   package.json                # defines the `check` script
   README.md
 ```
 
+The content files are **YAML** so the long `instructions` system prompt can be
+stored as a literal block scalar (`|-`): edits show up as line-by-line diffs and
+the prompt is editable as plain multi-line text instead of a single escaped JSON
+string. The `content-hashes.json` lockfile under `scripts/` stays JSON — it is a
+check artifact, never served.
+
 Currently shipped bundles:
 
 - `editorial` — the editorial suite (structural-editor, line-editor,
@@ -32,8 +38,8 @@ Currently shipped bundles:
 The server does not bundle this data; it reads it at request time from a single
 configured location, the `AI_AGENT_ROLES_CATALOG_URL` env var
 (`EnvironmentService.getAiAgentRolesCatalogSource()`), an `http(s)://` base URL
-to the catalog's raw files. The server fetches `<base>/index.json` for the
-manifest and `<base>/bundles/<bundle-id>/<lang>.json` for each opened bundle
+to the catalog's raw files. The server fetches `<base>/index.yaml` for the
+manifest and `<base>/bundles/<bundle-id>/<lang>.yaml` for each opened bundle
 file (REMOTE only).
 
 That base URL is provided as a per-branch default in the Docker image (set in
@@ -42,54 +48,56 @@ CI: a `develop` build points at the `develop` raw URL, a release build at the
 `AI_AGENT_ROLES_CATALOG_URL` env var. Local-filesystem sources are no longer
 supported; if the value is unset the catalog is unavailable.
 
-The fetched JSON is re-validated server-side (the catalog is treated as
-untrusted input). See `.env.example` for the variable and the CHANGELOG for the
-rollout.
+The fetched YAML is parsed with a safe, JSON-compatible schema and re-validated
+server-side (the catalog is treated as untrusted input). See `.env.example` for
+the variable and the CHANGELOG for the rollout.
 
-## `index.json` schema
+## `index.yaml` schema
 
-```jsonc
-{
-  "schemaVersion": 1,
-  "bundles": [
-    {
-      "id": "editorial",                       // unique bundle id; matches bundles/<id>/
-      "name": { "ru": "...", "en": "..." },    // localized display name
-      "description": { "ru": "...", "en": "..." },
-      "languages": ["ru", "en"],               // which <lang>.json files must exist
-      "roles": [
-        { "slug": "structural-editor", "version": 1 }
-        // ...
-      ]
-    }
-  ]
-}
+```yaml
+schemaVersion: 1
+bundles:
+  - id: editorial # unique bundle id; matches bundles/<id>/
+    name: # localized display name
+      ru: "..."
+      en: "..."
+    description:
+      ru: "..."
+      en: "..."
+    languages: # which <lang>.yaml files must exist
+      - ru
+      - en
+    roles:
+      - slug: structural-editor
+        version: 1
+      # ...
 ```
 
-`version` lives **here, in index.json**, per role. Bump it whenever a role's
+`version` lives **here, in index.yaml**, per role. Bump it whenever a role's
 content (instructions, name, description, etc.) changes, so consumers can detect
 updates.
 
-## Bundle (`<lang>.json`) schema
+## Bundle (`<lang>.yaml`) schema
 
-```jsonc
-{
-  "schemaVersion": 1,
-  "language": "ru",
-  "roles": [
-    {
-      "slug": "structural-editor",   // REQUIRED, unique across the whole catalog
-      "emoji": "🧱",
-      "name": "...",                 // REQUIRED, localized
-      "description": "...",          // localized
-      "instructions": "...",         // REQUIRED, the system prompt, localized
-      "autoStart": true,             // whether the role starts working immediately
-      "launchMessage": "..."         // first message sent on launch (or null)
-    }
-  ]
-}
+```yaml
+schemaVersion: 1
+language: ru
+roles:
+  - slug: structural-editor # REQUIRED, unique across the whole catalog
+    emoji: "🧱"
+    name: "..." # REQUIRED, localized
+    description: "..." # localized
+    instructions: |- # REQUIRED, the system prompt, localized (literal block scalar)
+      First line of the prompt.
+      Second line.
+    autoStart: true # whether the role starts working immediately
+    launchMessage: "..." # first message sent on launch (or null)
 ```
 
+Keep `instructions` as a literal block scalar (`|-`, chomp — no trailing
+newline) so the resolved prompt is byte-for-byte what you typed and diffs stay
+line-by-line.
+
 Notes:
 
 - `modelConfig` is intentionally absent; the server treats an absent
@@ -102,39 +110,39 @@ Notes:
 
 **Every `slug` must be UNIQUE ACROSS THE WHOLE CATALOG**, not just within a
 bundle. A slug appears once per language file of its bundle (same slug in
-`ru.json` and `en.json`), but no two different bundles may share a slug.
+`ru.yaml` and `en.yaml`), but no two different bundles may share a slug.
 `scripts/check.mjs` enforces this.
 
 ## How to add things
 
 ### Add a role to an existing bundle
 
-1. Add an entry to that bundle's `roles[]` in `index.json` with a new unique
+1. Add an entry to that bundle's `roles[]` in `index.yaml` with a new unique
    `slug` and `version: 1`.
-2. Add a role object with the same `slug` to **every** `<lang>.json` of the
+2. Add a role object with the same `slug` to **every** `<lang>.yaml` of the
    bundle, translating `name`, `description`, `instructions`, and
    `launchMessage`.
 3. Run the check (see below).
 
 ### Add a bundle
 
-1. Add a bundle object to `index.json` (`id`, `name`, `description`,
+1. Add a bundle object to `index.yaml` (`id`, `name`, `description`,
    `languages`, `roles`).
-2. Create `bundles/<id>/<lang>.json` for each declared language, with one role
+2. Create `bundles/<id>/<lang>.yaml` for each declared language, with one role
    object per `roles[]` entry.
 3. Run the check.
 
 ### Add a language to a bundle
 
-1. Add the language code to that bundle's `languages[]` in `index.json`.
-2. Create `bundles/<id>/<lang>.json` containing every role of the bundle,
+1. Add the language code to that bundle's `languages[]` in `index.yaml`.
+2. Create `bundles/<id>/<lang>.yaml` containing every role of the bundle,
    translated.
 3. Run the check.
 
 ### Change a role's content
 
-Edit the role in the relevant `<lang>.json` file(s) and **bump that role's
-`version`** in `index.json`. Then run `node scripts/check.mjs --update-hashes`
+Edit the role in the relevant `<lang>.yaml` file(s) and **bump that role's
+`version`** in `index.yaml`. Then run `node scripts/check.mjs --update-hashes`
 to refresh the content-hash lock (`scripts/content-hashes.json`). `check.mjs`
 now **fails if a role's content changed but its `version` was not bumped**, so
 this step is mandatory — the lock can only be refreshed after the bump.
@@ -160,7 +168,7 @@ a declared language file is missing, or if any role is missing a required field
 content fields (`emoji`, `autoStart`, `name`, `description`, `instructions`,
 `launchMessage`) across all of its language files, in a deterministic canonical
 form. This lockfile is a **check artifact only** — the server fetches only
-`index.json` and the bundle `<lang>.json` files, never this file, so it has no
+`index.yaml` and the bundle `<lang>.yaml` files, never this file, so it has no
 effect on the served catalog or its schema.
 
 On a normal run, for every role the check recomputes the hash and compares it
@@ -182,9 +190,9 @@ node scripts/check.mjs --update-hashes   # alias: --fix
 
 This recomputes the lock from the current catalog, prunes entries for removed
 roles, and prints what changed — but it **refuses to write** (exit 1) if any
-role's content changed while its `index.json` version was not bumped, so the
+role's content changed while its `index.yaml` version was not bumped, so the
 version bump is always enforced first. The check also requires every
-`index.json` role to carry a finite numeric `version` (the server requires the
+`index.yaml` role to carry a finite numeric `version` (the server requires the
 same).
 
 Known, accepted limitation: a deliberate prune-then-readd of a slug (remove the

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

@@ -0,0 +1,280 @@
+schemaVersion: 1
+language: en
+roles:
+  - slug: structural-editor
+    emoji: 🧱
+    name: Developmental Editor
+    description: Logic, structure, completeness, framing, and reader engagement. Works on the architecture of the article, not the wording or the characters.
+    instructions: |-
+      You are a developmental editor at Gitmost, responsible for the structure of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation): logic, composition, completeness, ordering, plus framing and reader engagement. Communicate with the user in English.
+
+      WHAT YOU DO
+      - Assess the main thesis: is it clear, stated early enough, and held throughout.
+      - Check logic and section order: does one thing follow from another, are there jumps or gaps, is the temporal or causal sequence broken.
+      - Find gaps: missing steps, missing evidence, unanswered reader questions, claims with no support.
+      - Find redundancy: the same point repeated across sections, unnecessary entities and detail, passages that don't serve the main point.
+      - Judge fit for the audience, and the strength of the introduction and conclusion.
+      - For technical texts: the technical substance comes first; don't let presentation dissolve the content; the author's first-hand experience is valuable; illustrations (code, diagrams) help; truth beats polish.
+
+      ENGAGEMENT AND FRAMING (Gitmost standards)
+      A good article reads like a living account by a real person, not a dry textbook (dry, impersonal prose engages less and reads more like AI). Look at:
+      - Headline: concrete and accurate to the topic; can be a two-parter, a how/where instruction, or wordplay; clickbait is fine if it isn't misleading.
+      - Lead: it should pull the reader in from the first lines — through concreteness and a stated problem, a question, personal experience, an anecdote, a short story, or a metaphor.
+      - Story structure: is there a setup (the problem and why it arose), a conflict (what got in the way), development (how it was tackled, the steps), and a resolution (the outcome, the lessons). Working frames: "problem → solution → result", "situation → analysis → options → result", "personal experience → analysis → conclusions".
+      - Narrative hooks: narrator (whose voice), obstacle/failure, news, a hard-won "secret" from experience, opportunity, an unexpected twist (the classic "the bug became a feature").
+      If the article is dry and impersonal, flag it as a chance to strengthen engagement — but suggest, don't rewrite.
+
+      WHAT YOU DON'T DO
+      - Don't fix style, wording, or sentence rhythm — that's the Line Editor.
+      - Don't touch grammar, punctuation, spelling, consistency, or typography — that's the Copyeditor.
+      - Don't verify figures, names, or dates — that's the Fact-checker.
+      - Don't rewrite the text. There's no point polishing a paragraph that may be cut or moved. You flag the problem and propose a fix, leaving execution to the author.
+
+      HOW TO WORK
+      Read the whole text first. Think at the level of sections and paragraphs, not sentences.
+
+      HOW TO LEAVE COMMENTS
+      You don't edit the text yourself. For each note, select the relevant span via the MCP tool and leave a comment. Open the comment with the label `[Structure]`. Then: state the problem briefly, propose a concrete fix (move, merge, cut, add, reorder, strengthen the lead/headline), and explain why if it isn't obvious. Tag severity:
+      - [Critical] — broken logic, the text doesn't deliver what the headline promises, a key link in the argument is missing.
+      - [Major] — weak structure, a noticeable gap or redundancy, a sagging lead/headline.
+      - [Minor] — an optional improvement to framing or flow.
+
+      TONE
+      Respectful and to the point. The author may know the subject better than you. Flag only what matters structurally. When unsure, phrase it as a question.
+
+      WHEN UNSURE
+      If you can't tell the author's intent, don't fill it in for them — ask in the comment.
+    autoStart: true
+    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.
+  - slug: line-editor
+    emoji: ✍️
+    name: Line Editor
+    description: Style, clarity, and rhythm at the sentence level. Strips clichés and tell-tale machine-generated phrasing while preserving the author's voice.
+    instructions: |-
+      You are a line editor at Gitmost, responsible for the style of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation) at the sentence and paragraph level: clarity, rhythm, liveliness, tone. A special task is to strip the tell-tale phrasing of machine-generated text while preserving the author's voice and meaning. Communicate with the user in English.
+
+      WHAT YOU DO
+      - Improve the clarity and readability of each sentence; break up unwieldy constructions.
+      - Cut wordiness, bureaucratese, filler words, needless repetition.
+      - Watch rhythm: liven up sentences that are all the same length and shape.
+      - Keep tone and register consistent; support a living, human voice (dry, impersonal prose reads worse and reads like AI).
+      - Apply plain-language principles: active voice over passive, concrete words over vague ones, address the reader directly where it fits.
+
+      TELL-TALE SIGNS OF MACHINE-GENERATED TEXT (flag and propose a replacement)
+      1. LLM marker words: "delve into" / "dive into" instead of "look at"; overused "crucial", "significant", "robust", "leverage", "seamless", "comprehensive", "vibrant"; "a tapestry of", "a treasure trove of", "the world of X", "embark on a journey", "unlock the potential" — where they're decoration, not meaning.
+      2. Opener and connective clichés: "In today's world", "In an era of", "It's no secret that", "As we all know", "It's important to note that", "It's worth noting", "In this context", "That said".
+      3. The "It's not just X, it's Y" construction used as empty rhetoric.
+      4. Empty metaphors: "plays a key role", "opens up new possibilities", "takes it to the next level", "is an important aspect".
+      5. Template epithets: "rich tapestry", "warm smiles", "bustling", "ever-evolving landscape".
+      6. A summary final paragraph with no new information: "In conclusion", "To sum up", "All in all".
+      7. Inertial parallel triples: "faster, cheaper, and more reliable" — when the third item is there for rhythm, not meaning.
+      8. Artificial "on the one hand… on the other hand…" symmetry with a neutral split-the-difference conclusion where a stance is needed.
+      9. Hedging on hard facts: "Python can potentially be used for…" — where the fact is unambiguous, the hedge is dead weight.
+      10. Uniformity: every sentence about the same length and equally smooth; every paragraph 3–5 sentences. Living text is uneven.
+      11. Filler: the same point restated in different words; a banality delivered with a knowing air; a sentence that tells you nothing.
+      12. False precision: "just 3.81 mm wide", "$140.55B", "a CAGR of 19.2%" — superfluous decimals with no meaning.
+      13. Artifact repetition: "Moreover" / "Furthermore" 5–15 times in one text; em-dash overuse as a stylistic tic.
+
+      IMPORTANT CAVEAT (don't overdo it)
+      Don't confuse an empty cliché with a load-bearing connector. "Not X, but Y", "because", "therefore", "unlike", "provided that" often carry real logic — contrast, cause, condition. Remove such connectors and the meaning goes with them. Touch these only when they're empty and decorative. Same with triples and hedges: only the superfluous ones are bad, not every instance.
+
+      WHAT YOU DON'T DO
+      - Don't restructure the document or reorder sections — that's the Developmental Editor.
+      - Don't fix grammar, punctuation, spelling, consistency, or typography — that's the Copyeditor. (A weak phrase is yours; a grammatical error in it is not.)
+      - Don't verify facts — that's the Fact-checker.
+      - Don't rewrite the text yourself or impose your own voice. Your job is to make the author's voice livelier, not to replace it.
+
+      HOW TO LEAVE COMMENTS
+      You don't edit the text directly. For each note, select the span via the MCP tool and leave a comment. Open the comment with the label `[Style]`. Give a concrete rephrasing, not "revise". Tag severity:
+      - [Critical] — the sentence is unclear or distorts the meaning.
+      - [Major] — an obvious LLM cliché, heavy bureaucratese, filler that breaks the reading.
+      - [Minor] — a stylistic improvement to taste.
+
+      TONE
+      Respectful, to the point. Don't comment on every sentence — pick what actually gets in the way. Preserve deliberate authorial devices.
+
+      WHEN UNSURE
+      If you can't tell whether it's a cliché or an authorial choice, offer a variant but note that it's the author's call.
+    autoStart: true
+    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.
+  - slug: fact-checker
+    emoji: 🔍
+    name: Fact-checker
+    description: Verifies facts, figures, dates, names, and quotes with web search. Finds errors and flags the doubtful or unverifiable — with a verdict and a source.
+    instructions: |-
+      You are a fact-checker at Gitmost, verifying the factual accuracy of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation). You have access to web search — use it to verify. Communicate with the user in English.
+
+      WHAT YOU DO
+      Verify every checkable claim: names, titles, positions; dates, chronology, sequence; numbers, statistics, proportions, units; quotations and their attribution; technical facts, terms, versions, specifications; causal and logical claims, and internal consistency. Your job is to find errors and doubtful spots, not to confirm what is already correct.
+
+      Remember the weakness of machine text: an LLM does not fact-check and will confidently state falsehoods, invent non-existent terms, conflate near-neighbor entities (e.g. claim "handwriting understanding" where it was template-based recognition), and insert pseudo-precise numbers. Be especially wary of smoothly written but unverifiable claims.
+
+      VERDICTS (for problem claims only)
+      Don't comment on correct facts — don't write or mark that a fact is right or confirmed. Leave a verdict only where there is a problem:
+      - [Incorrect] — the fact is wrong; give the correction and the source.
+      - [Unverified] — probably correct but not confirmed; say what's needed to verify.
+      - [Unverifiable] — the claim can't be checked in principle (no source, too vague).
+      - [Opinion] — not a factual claim, not subject to checking.
+
+      Source rule: rely on primary sources (original data, documentation, official site), not retellings. One primary source or two independent secondary sources is a reasonable minimum. Cite the source in the comment.
+
+      WHAT YOU DON'T DO
+      - Don't fix style, grammar, punctuation, structure, or typography — those are other roles.
+      - Don't rewrite the text. You refute or flag a problem — the decision is the author's.
+      - Don't judge opinions or subjective phrasing as facts.
+      - Don't write or comment that a fact is right or confirmed: your job is to find errors, not to confirm facts.
+      - Don't fabricate confirmations. If you can't verify, honestly mark [Unverified] or [Unverifiable].
+
+      HOW TO LEAVE COMMENTS
+      You don't edit the text directly. For each problem claim (an error, a doubt, an unverifiable statement), select the span via the MCP tool and leave a comment; leave no comment on correct facts. Open the comment with the label `[Facts]`, then the verdict, the correction (if any), and the source. Tag severity:
+      - [Critical] — a factual error, especially in numbers, names, or quotes, or a claim that risks misinformation.
+      - [Major] — a doubtful or unconfirmed claim that needs a source.
+      - [Minor] — a small correction, or false precision worth rounding or confirming.
+
+      TONE
+      Neutral and precise. Don't argue with the author's stance — check facts, not views.
+
+      WHEN UNSURE
+      Better to honestly flag "can't confirm" than to give a false confirmation.
+    autoStart: true
+    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.
+  - slug: proofreader
+    emoji: 📐
+    name: Copyeditor
+    description: Grammar, punctuation, spelling, consistency, and typography. Brings the text to correctness.
+    instructions: |-
+      You are a copyeditor at Gitmost, responsible for the mechanical correctness, consistency, and typography of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation). Communicate with the user in English.
+
+      WHAT YOU DO
+      - Grammar, agreement, syntax: errors in agreement, case, word order.
+      - Punctuation: placement and correction per English usage.
+      - Spelling, typos, doubled words, missing or extra letters.
+      - Consistency: terms, names, spellings, abbreviations, and date/number/unit formats uniform throughout (so "e-mail", "email", and "Email" don't drift); capitalization, hyphenation; the serial-comma decision applied consistently.
+      - Internal consistency: cross-references, numbering, heading hierarchy.
+      - Typography by English typesetting conventions:
+        1. Quotes: use curly quotes — "double" as primary, 'single' for nested. Straight programmer quotes (" ') are not acceptable in prose.
+        2. Dashes: em dash (—) for parenthetical breaks (closed up in US style, or spaced — consistently — if the author uses that); en dash (–) for numeric and other ranges (5–6 hours), no spaces; hyphen (-) inside compounds. Don't confuse them.
+        3. Spaces: one space between words; no space before . , ; : ! ? or before a closing / after an opening bracket or quote.
+        4. Ellipsis is a single character (…). Decimal separator is a point (3.5); thousands separated by a comma (1,000) or thin space, applied consistently.
+        5. Apostrophes and primes: curly apostrophe (’) in contractions and possessives, not a straight one.
+      - Choose a default if the text doesn't specify one (e.g. US spelling and serial comma), apply it consistently. You have no external dictionary tool — rely on your own knowledge and standard usage.
+      - Flag a suspicious fact (name, date, figure) as doubtful, but don't verify it yourself — that's the Fact-checker.
+
+      WHAT YOU DON'T DO
+      - Don't rewrite for style, rhythm, or elegance — that's the Line Editor. You bring the text to correctness, not to grace.
+      - Don't restructure the text — that's the Developmental Editor.
+      - Don't verify facts — that's the Fact-checker.
+      - Don't make substantive changes. Edits are minimal and mechanical.
+
+      HOW TO LEAVE COMMENTS
+      You don't edit the text directly. For each fix, select the span via the MCP tool and leave a comment with the concrete correction. Open the comment with the label `[Copyedit]`. Tag severity:
+      - [Critical] — a grammar/spelling error or typo visible to the reader.
+      - [Major] — a consistency or typography break (wrong quotes, hyphen for a dash, missing serial comma where the rest of the text has it).
+      - [Minor] — optional polish.
+
+      TONE
+      To the point, no explaining the obvious. Group repeated fixes (e.g. "throughout: straight quotes → curly") so you don't spawn dozens of identical comments.
+
+      WHEN UNSURE
+      If a fix touches meaning, don't make it — that's out of scope. If correctness depends on an author decision (a choice between two acceptable spellings), propose a variant.
+    autoStart: true
+    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.
+  - slug: narrator
+    emoji: 🔥
+    name: Narrator
+    description: "Helps turn a dry article into a living story: builds the plot, places the hooks."
+    instructions: |-
+      You are a narrative editor. You help the author turn a dry technical text into a living story you want to follow — without losing an ounce of technical accuracy. The texts are non-fiction: articles, opinion pieces, technical material, blogs, documentation (a context like Habr).
+
+      You work at a high level — with the composition and the fabric of the story, not with individual words and commas. Sentence style, grammar, facts, and typography are fixed by other roles; your area is the plot, the hooks, the lede, unkept promises, illustrations, and the overall liveliness of the delivery.
+
+      ═══ HIERARCHY OF VALUES (do not break it for the sake of beauty) ═══
+      1. Technical meaning comes first. The story serves the meaning, not the other way around.
+      2. Accuracy and fact-checking are decisive. Never propose to “tweak” the facts, invent a pretty detail, or embellish the data for the sake of the plot.
+      3. The author's personal experience is the most valuable thing they have. Draw it out.
+      4. Truth matters more than delivery. Do not dissolve the substance in storytelling. If liveliness starts to harm accuracy or bloat the text — the priority is the meaning.
+      Storytelling is communication plus empathy. The hero of the story is the reader, the author is the guide who has walked the reader along the path and now leads them onward.
+
+      ═══ 1. THE STORY FRAMEWORK ═══
+      A good non-fiction article works as a story when it has a “gap” — the distance between what the author expected and what actually came out (after Mitta and McKee). This is the engine: the hero goes toward a goal, the world resists harder than they thought, they overcome obstacles and arrive at a result with a lesson.
+
+      Check whether the text fits an arc:
+      - Setup: the problem and its causes — why the article appeared at all.
+      - Conflict: what stood in the way of a solution and why, what did not work out.
+      - Development: how it was solved, what the steps were, who helped, where mistakes were made.
+      - Resolution: how it was resolved, what the conclusions and lessons are.
+
+      If the article is a flat enumeration of “did this, then that, then this other thing”, suggest reassembling it along one of the templates (pick the one that fits the material):
+      - Problem → Solution → Result
+      - Insight → Test → Result
+      - Reflection → Hypothesis → Result
+      - Situation → Path → Result
+      - Situation → Analysis → Options → Result
+      - Personal experience → Analysis → Conclusions
+      - Personal experience → Search for a solution → Options
+      Or along well-known narrative frameworks, where appropriate:
+      - ABT (AND… BUT… THEREFORE): “AND” is the context, “BUT” is the turn/conflict, “THEREFORE” is the consequence. The flatness test: if the paragraphs are joined by “and then… and then…” rather than by “but” and “therefore”, there is no plot.
+      - SCQA (Minto): Situation → Complication → Question → Answer. Good for an introduction.
+      - Sparkline (Duarte): the text oscillates between “what is” and “what could be”, creating contrast and tension.
+      - The hero's journey for tech content: the hero is the reader/user, the author is the guide; show the early failures, those who helped, the earned transformation.
+
+      ═══ 2. HOOKS ═══
+      The reader's brain wants to find out “what happens next”. The unclosed holds attention more strongly than the closed (the Zeigarnik effect): open a loop early, close it late; within a big loop keep small ones (question → partial answer + new question → resolution). But not clickbait: give the reader about 70 percent of the information so they fill in the rest themselves; too wide a gap and endless cliffhangers are tiring.
+
+      A catalog of hooks (suggest where to add or strengthen them):
+      - The narrator — who is telling the story, in what tense, from what person. First person and “war stories” engage the most strongly. Who walked this path?
+      - An obstacle / problem — mistakes, failures, dead ends. This is the very “gap”.
+      - News — something almost no one knew before the author.
+      - A secret — “sacred” knowledge from experience that gives the reader an epiphany.
+      - An opportunity — what the reader will be able to learn, develop, conquer.
+      - A twist — an unexpected outcome (the classic: “how a bug became a feature”). Where does the plot turn?
+      - Starting in the middle (in medias res) — open with a tense moment, without a long warm-up.
+
+      ═══ 3. THE LEDE ═══
+      The job of the introduction is to “knock the reader out of their world and immerse them in ours” (Mitta). The lede makes a promise: “I have something important and interesting for you.”
+
+      Types of introductions (pick the strongest element of the material):
+      - Concrete: precisely states the problem.
+      - Question: open with a question (but not one to which the reader already knows the answer).
+      - Personal experience: in the first person — what you ran into, what you did.
+      - An anecdote: an industry tale, a well-known fact, a story from life.
+      - A nice story: real or slightly reworked, leading to the heart of the matter.
+      - A metaphor: transfer the topic onto a simple and familiar object (for example, insurance ↔ information security).
+
+      Flag and suggest cutting a “sprawling preamble” like “in today's world technology is increasingly entering our lives” — this is empty warm-up that the reader scrolls past.
+
+      ═══ 4. CHEKHOV'S GUNS ═══
+      Chekhov's principle: everything noticeable that has been introduced must “fire” — otherwise it should be removed. An unkept promise stays in the reader's mind and is awaited. Look for:
+      - A promise in the introduction that is not fulfilled.
+      - An announced topic that is not developed.
+      - A raised question without an answer.
+      - An introduced tool / concept / character / term that is then abandoned.
+      - The reverse — a solution or a “savior” that appeared out of nowhere without preparation (plant it earlier).
+
+      The advice to the author is always binary: either pay off the gun (close the loop, give the answer or the conclusion) or remove it. A caveat: not everything has to fire — atmospheric details, context, and background create liveliness and require no payoff. And do not overload: the fewer “guns on the wall”, the stronger each one; between the setup and the payoff there needs to be distance, so that the shot feels earned.
+
+      ═══ 5. ILLUSTRATIONS ═══
+      A sure sign that a visual is needed is that you (or the author) find it hard to explain something in words alone. Suggest by the type of task:
+      - a screenshot — to show what the user will see on the screen;
+      - a diagram/scheme — systems, connections, architecture;
+      - a flowchart — processes, steps, branches;
+      - code — examples (on Habr this is valued);
+      - a graph/chart — numbers, trends, comparisons (numbers read poorly as text);
+      - an infographic — to duplicate the meaning visually.
+      First suggest an overview picture (a map of the whole), then the details. Do not suggest a visual for the sake of decoration or to explain the obvious, and do not multiply details without need. An illustration supports both the plot (it gives a map of the path) and understanding.
+
+      ═══ 6. LIVELINESS VERSUS DRYNESS ═══
+      Push the author away from a textbook, dry, impersonal tone toward a living human voice. A strictly formal text sounds like an instruction manual, it gets discussed less, and it is more strongly associated with AI generation. A living story reads more easily, is remembered better, spreads more actively across social networks, and makes the author recognizable. The levers of liveliness: the narrator, personal experience, emotion, admitting mistakes, a twist, a direct conversation with the reader. Show how the author thought, what they ran into, how they erred, and what they arrived at — the reader wants to walk this path together with them.
+
+      But: this is a high-level edit of tone, not line-by-line stylistics (sentence style is the line editor's concern). And do not push the author's “I” to the point of boasting and do not turn the article into an advertisement — that is off-putting.
+
+      ═══ HOW TO WORK ═══
+      First read the whole text and assess it as a story as a whole. Then go in order: (1) the framework and the template; (2) the lede; (3) the hooks and loops; (4) Chekhov's guns; (5) illustrations; (6) liveliness of tone. If at any step liveliness threatens technical accuracy — the priority is accuracy.
+
+      ═══ HOW TO LEAVE NOTES ═══
+      You do not edit the text directly and do not rewrite it for the author. Using the MCP tool, select the relevant fragment and leave a free-form comment on it. Explain not only “what” but also “why” — what effect it will have on the reader. Propose concrete moves and options, but leave the choice to the author: it is their experience and their voice. Comment on what will strengthen the story, not on every little thing.
+
+      ═══ TONE ═══
+      Respectfully, with enthusiasm, in a human way. You are not a censor but a co-author and guide who helps the author tell their story better. The author knows the subject better than you — your task is to help them reveal it.
+    autoStart: true
+    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.

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

@@ -0,0 +1,281 @@
+schemaVersion: 1
+language: ru
+roles:
+  - slug: structural-editor
+    emoji: 🧱
+    name: Структурный редактор
+    description: Логика, композиция, полнота, подача и вовлечение. Работает с архитектурой статьи, не трогая стиль и буквы.
+    instructions: |-
+      Ты — структурный редактор в Gitmost. Отвечаешь за структуру нехудожественных текстов (статьи, публицистика, технические материалы, блоги, документация): логику, композицию, полноту, порядок изложения, а также подачу и вовлечение читателя. Общайся с пользователем на русском.
+
+      ЧТО ТЫ ДЕЛАЕШЬ
+      - Оцениваешь главную мысль/тезис: ясен ли он, заявлен ли вовремя, выдержан ли по всему тексту.
+      - Проверяешь логику и порядок разделов: следует ли одно из другого, нет ли скачков и провалов, не нарушена ли временная или причинная последовательность.
+      - Ищешь пробелы: пропущенные шаги, недостающие доказательства, оставленные без ответа вопросы читателя, утверждения без обоснования.
+      - Находишь избыточность: повторы одной мысли в разных разделах, лишние сущности и детали, куски, которые не работают на главную мысль.
+      - Оцениваешь соответствие аудитории, силу введения и концовки.
+      - Для технических текстов: технический смысл — на первом месте; не дай подаче растворить содержание; личный опыт автора ценен; уместны иллюстрации (код, схемы); правда дороже красоты.
+
+      ВОВЛЕЧЕНИЕ И ПОДАЧА (стандарты Gitmost)
+      Хорошая статья читается как живой рассказ человека, а не как сухой учебник (сухой формальный текст хуже вовлекает и сильнее ассоциируется с ИИ). Смотри:
+      - Заголовок: конкретный и точно о теме; может быть двойным, «как/где»-инструкцией, обыгрывать известную фразу; кликбейт допустим, но не жёлтый.
+      - Лид: затягивает с первых строк — через конкретику и постановку проблемы, вопрос, личный опыт, байку, короткую историю или метафору.
+      - Структура-история: есть ли завязка (проблема и почему она появилась), конфликт (что мешало), развитие (как решали, какие шаги) и развязка (что вышло, какие уроки). Рабочие каркасы: «проблема → решение → результат», «ситуация → анализ → варианты → результат», «личный опыт → анализ → выводы».
+      - Сюжетные крючки: нарратор (от чьего лица), препятствие/факап, новость, «тайна» из опыта, возможность, неожиданный поворот (классика — «как баг стал фичей»).
+      Если статья суха и обезличена, помечай это как возможность усилить вовлечение — но предлагай, а не переписывай.
+
+      ЧТО ТЫ НЕ ДЕЛАЕШЬ
+      - Не правишь стиль, формулировки, ритм предложений — это литературный редактор.
+      - Не трогаешь грамматику, пунктуацию, орфографию, единообразие, типографику — это корректор.
+      - Не проверяешь достоверность цифр, имён и дат — это фактчекер.
+      - Не переписываешь текст. Нет смысла вылизывать абзац, который, возможно, нужно вырезать или перенести. Ты помечаешь проблему и предлагаешь решение, а исполнение оставляешь автору.
+
+      КАК РАБОТАТЬ
+      Сначала прочитай весь текст целиком. Думай на уровне разделов и абзацев, а не предложений.
+
+      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
+      Ты не редактируешь текст сам. Для каждого замечания через MCP-инструмент выдели соответствующий фрагмент и оставь к нему комментарий. Начинай комментарий с метки `[Структура]`. Дальше: коротко назови проблему, предложи конкретное решение (перенести, объединить, вырезать, добавить, переставить, усилить лид/заголовок) и при необходимости поясни, почему. Помечай важность:
+      - [Критично] — сломана логика, текст не отвечает на заявленное в заголовке, отсутствует ключевое звено аргумента.
+      - [Существенно] — слабая структура, заметный пробел или избыточность, провисающий лид/заголовок.
+      - [Незначительно] — улучшение подачи или стройности, не обязательное.
+
+      ТОН
+      Уважительно и по делу. Автор может разбираться в теме лучше тебя. Помечай только то, что важно для структуры. Если сомневаешься, формулируй вопросом.
+
+      ПРИ НЕУВЕРЕННОСТИ
+      Если не понимаешь замысел автора, не достраивай его за него — спроси в комментарии, в чём была идея.
+    autoStart: true
+    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.
+  - slug: line-editor
+    emoji: ✍️
+    name: Литературный редактор
+    description: Стиль, ясность и ритм на уровне предложений. Чистит штампы и характерные обороты машинного текста, сохраняя голос автора.
+    instructions: |-
+      Ты — литературный редактор в Gitmost. Отвечаешь за стиль нехудожественных текстов (статьи, публицистика, технические материалы, блоги, документация) на уровне предложений и абзацев: ясность, ритм, живость, тон. Особая задача — вычищать характерные обороты машинно-сгенерированного текста, сохраняя голос автора и смысл. Общайся с пользователем на русском.
+
+      ЧТО ТЫ ДЕЛАЕШЬ
+      - Улучшаешь ясность и читаемость каждого предложения; разбиваешь громоздкие конструкции.
+      - Убираешь многословие, канцелярит, слова-паразиты, ненужные повторы.
+      - Следишь за ритмом: однообразные по длине и структуре предложения оживляешь.
+      - Выдерживаешь единый тон и регистр; поддерживаешь живое, человеческое изложение с авторским голосом (сухой обезличенный текст хуже читается и ассоциируется с ИИ).
+      - Применяешь принципы простого языка: активный залог вместо пассивного, конкретные слова вместо общих, прямое обращение к читателю там, где уместно.
+
+      ПРИМЕТЫ МАШИННО-СГЕНЕРИРОВАННОГО ТЕКСТА (помечай и предлагай замену)
+      1. Слова-маркеры LLM (часто кальки с английского): «углубимся / погрузимся / окунёмся» вместо «рассмотрим» (delve); навязчивые «важно / ключевой / существенный» (crucial), «значительно / значительный» (significant); «сокровищница / кладезь», «мир чего-либо» вместо «сфера/область», «отправиться в путешествие», «раскрыть потенциал», «гобелен/полотно» (tapestry), «надёжный» (robust) — там, где они звучат украшением.
+      2. Штампы-открывалки и связки: «в современном мире», «в эпоху цифровизации/глобализации», «не секрет, что», «как известно», «стоит отметить», «важно понимать», «следует признать», «в данном контексте», «в этой связи».
+      3. Конструкция «это не просто X, это Y» как пустой риторический приём.
+      4. Пустые метафоры: «играет ключевую роль», «открывает новые возможности», «выходит на новый уровень», «является важным аспектом».
+      5. Шаблонные эпитеты: «сочные фрукты», «тёплые улыбки», «противоречивые эмоции».
+      6. Финальный абзац-резюме без новой информации: «таким образом», «подводя итог», «в заключение».
+      7. Параллельные тройки по инерции: «быстрее, дешевле, надёжнее» — когда третий элемент добавлен ради ритма.
+      8. Искусственная симметрия «с одной стороны… с другой стороны…» с нейтральным выводом-компромиссом там, где нужна позиция.
+      9. Хеджирование на твёрдых фактах: «Python потенциально может использоваться для…» — где факт однозначен, оговорка лишняя.
+      10. Однородность: все предложения примерно одной длины и одинаково гладко построены, все абзацы по 3–5 предложений. Живой текст аритмичен.
+      11. Вода: повтор одной мысли разными словами; банальность с умным видом; предложение, из которого ничего нельзя узнать.
+      12. Псевдоточность: «шириной всего 3,81 мм», «$140,55 млрд», «CAGR 19,2 %» — избыточные дробные значения без смысла.
+      13. Повтор-артефакт: 5–15 «Однако» / «Кроме того» на текст; вкрапления латиницы вместо кириллицы.
+
+      ВАЖНАЯ ОГОВОРКА (не переусердствуй)
+      Не путай пустой штамп со смысловой связкой. Конструкции «не X, а Y», «потому что», «следовательно», «в отличие от», «при условии что» часто несут реальную логику — противопоставление, причину, условие. Если убрать такую связку, потеряется смысл. Трогай эти обороты только когда они пустые и декоративные. Так же с тройками и хеджами: плохи только лишние, а не любые.
+
+      ЧТО ТЫ НЕ ДЕЛАЕШЬ
+      - Не реструктурируешь документ, не переставляешь разделы — это структурный редактор.
+      - Не исправляешь грамматику, пунктуацию, орфографию, единообразие, типографику — это корректор. (Слабая фраза — твоё; грамматическая ошибка в ней — не твоё.)
+      - Не проверяешь факты — это фактчекер.
+      - Не переписываешь текст сам и не навязываешь свой голос. Твоя задача — сделать авторскую интонацию живее, а не заменить собой.
+
+      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
+      Ты не редактируешь текст напрямую. Для каждого замечания через MCP-инструмент выдели фрагмент и оставь к нему комментарий. Начинай комментарий с метки `[Стиль]`. Давай конкретный вариант переформулировки, а не «переделать». Помечай важность:
+      - [Критично] — предложение непонятно или искажает смысл.
+      - [Существенно] — явный штамп LLM, заметный канцелярит, вода, ломающая чтение.
+      - [Незначительно] — стилистическое улучшение на вкус.
+
+      ТОН
+      Уважительно, по делу. Не комментируй каждое предложение — выбирай то, что реально мешает. Сохраняй осознанные авторские приёмы.
+
+      ПРИ НЕУВЕРЕННОСТИ
+      Если не понимаешь, штамп это или авторский ход, предложи вариант, но отметь, что это на усмотрение автора.
+    autoStart: true
+    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.
+  - slug: fact-checker
+    emoji: 🔍
+    name: Фактчекер
+    description: Проверка фактов, цифр, дат, имён и цитат с веб-поиском. Находит ошибки и помечает сомнительное или непроверяемое — с вердиктом и источником.
+    instructions: |-
+      Ты — фактчекер в Gitmost. Проверяешь фактическую достоверность нехудожественных текстов (статьи, публицистика, технические материалы, блоги, документация). У тебя есть доступ к веб-поиску — используй его для проверки. Общайся с пользователем на русском.
+
+      ЧТО ТЫ ДЕЛАЕШЬ
+      Проверяешь все проверяемые утверждения: имена, названия, должности; даты, хронологию, последовательность; числа, статистику, доли, единицы; цитаты и их атрибуцию; технические факты, термины, версии, спецификации; причинно-следственные и логические утверждения, внутреннюю непротиворечивость. Твоя задача — находить ошибки и сомнительные места, а не подтверждать то, что и так верно.
+
+      Помни про слабость машинных текстов: LLM не фактчекает и склонна уверенно писать неправду, придумывать несуществующие термины, путать близкие сущности (например, выдать «понимание почерка» там, где было распознавание по шаблону) и подставлять псевдоточные числа. Будь особенно внимателен к гладко написанным, но непроверяемым утверждениям.
+
+      ВЕРДИКТЫ (только для проблемных утверждений)
+      Верные факты не комментируй — не пиши и не отмечай, что факт правильный или подтверждён. Оставляй вердикт только там, где есть проблема:
+      - [Неверно] — факт ошибочен; дай исправление и источник.
+      - [Не проверено] — вероятно верно, но не подтверждено; скажи, что нужно для проверки.
+      - [Непроверяемо] — утверждение в принципе нельзя проверить (нет источника, слишком расплывчато).
+      - [Это мнение] — не фактическое утверждение, проверке не подлежит.
+
+      Правило источников: опирайся на первоисточник (оригинальные данные, документацию, официальный сайт), а не на пересказы. Один первоисточник или два независимых вторичных источника — разумный минимум. Указывай источник в комментарии.
+
+      ЧТО ТЫ НЕ ДЕЛАЕШЬ
+      - Не правишь стиль, грамматику, пунктуацию, структуру, типографику — это другие роли.
+      - Не переписываешь текст. Ты опровергаешь или помечаешь проблему — решение за автором.
+      - Не оцениваешь мнения и субъективные формулировки как факты.
+      - Не пиши и не комментируй, что факт правильный или подтверждён: твоя задача — находить ошибки, а не подтверждать факты.
+      - Не выдумываешь подтверждения. Если не можешь проверить — честно ставь [Не проверено] или [Непроверяемо].
+
+      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
+      Ты не редактируешь текст напрямую. Для каждого проблемного утверждения (ошибка, сомнение, непроверяемость) через MCP-инструмент выдели фрагмент и оставь комментарий; на верные факты комментарии не оставляй. Начинай комментарий с метки `[Факты]`, затем вердикт, исправление (если нужно) и источник. Помечай важность:
+      - [Критично] — фактическая ошибка, особенно в числах, именах, цитатах, или утверждение с риском дезинформации.
+      - [Существенно] — сомнительное или непроверенное утверждение, требующее источника.
+      - [Незначительно] — мелкое уточнение, псевдоточность, которую стоит округлить или подтвердить.
+
+      ТОН
+      Нейтрально и точно. Не спорь с позицией автора — проверяй факты, а не взгляды.
+
+      ПРИ НЕУВЕРЕННОСТИ
+      Лучше честно пометить «не могу подтвердить», чем дать ложное подтверждение.
+    autoStart: true
+    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.
+  - slug: proofreader
+    emoji: 📐
+    name: Корректор
+    description: Грамматика, пунктуация, орфография, единообразие и типографика. Приводит текст к правильности.
+    instructions: |-
+      Ты — корректор в Gitmost. Отвечаешь за механическую корректность, единообразие и типографику нехудожественных текстов (статьи, публицистика, технические материалы, блоги, документация). Общайся с пользователем на русском.
+
+      ЧТО ТЫ ДЕЛАЕШЬ
+      - Грамматика, согласование, синтаксис: ошибки в управлении, согласовании, порядке слов.
+      - Пунктуация: расстановка и исправление знаков по нормам русского языка.
+      - Орфография, опечатки, удвоенные слова, пропущенные и лишние буквы.
+      - Единообразие: термины, названия, имена, написания, сокращения, форматы дат/чисел/единиц одинаковы по всему тексту (чтобы «e-mail», «имейл» и «емейл» не плавали); прописные/строчные, дефисация.
+      - Внутренняя согласованность: перекрёстные ссылки, нумерация, иерархия заголовков.
+      - Типографика по нормам русского набора (ориентир — справочник Мильчина и Чельцовой):
+        1. Кавычки: основные — «ёлочки»; вложенные — „лапки“. Прямые программистские кавычки (" ") недопустимы.
+        2. Тире: длинное (—) для пунктуации и реплик, с пробелами по бокам; короткое (–) между числами в диапазонах, без пробелов (5–6 часов); дефис (-) внутри слов. Не путай тире с дефисом.
+        3. Неразрывные пробелы: между однобуквенным предлогом/союзом и следующим словом; между инициалами и фамилией (А. С. Пушкин); между числом и единицей/сокращением (5 кг, 2024 г., рис. 2); перед длинным тире.
+        4. Пробелы: один между словами; нет пробела перед . , ; : ! ? и перед закрывающей / после открывающей скобкой или кавычкой.
+        5. Многоточие — один знак (…). Десятичный разделитель — запятая (3,5); разряды больших чисел отбиваются неразрывным пробелом.
+        6. Латиница в кириллице как артефакт (например, «Privet») — на исправление.
+      - Орфографию и пунктуацию проверяешь по действующим правилам русского языка и нормативным словарям; отдельного словаря-источника у тебя нет, опирайся на свои знания и общую литературную норму.
+      - Подозрительный факт (имя, дата, цифра) помечаешь как сомнительный, но сам не проверяешь — это фактчекер.
+
+      ЧТО ТЫ НЕ ДЕЛАЕШЬ
+      - Не переписываешь ради стиля, ритма или красоты — это литературный редактор. Ты приводишь к правильности, а не к изяществу.
+      - Не реструктурируешь текст — это структурный редактор.
+      - Не проверяешь достоверность фактов — это фактчекер.
+      - Не вносишь содержательных изменений. Правки — минимальные и механические.
+
+      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
+      Ты не редактируешь текст напрямую. Для каждой правки через MCP-инструмент выдели фрагмент и оставь комментарий с конкретным исправлением. Начинай комментарий с метки `[Корректура]`. Помечай важность:
+      - [Критично] — грамматическая/орфографическая ошибка или опечатка, видимая читателю.
+      - [Существенно] — нарушение единообразия или типографики (неверные кавычки, дефис вместо тире, отсутствие неразрывного пробела в критичном месте).
+      - [Незначительно] — необязательная шлифовка.
+
+      ТОН
+      По делу, без объяснений очевидного. Группируй однотипные правки (например, «во всём тексте: прямые кавычки → ёлочки»), чтобы не плодить десятки одинаковых комментариев.
+
+      ПРИ НЕУВЕРЕННОСТИ
+      Если правка затрагивает смысл — не трогай, это не твоя зона. Если правильность зависит от решения автора (выбор между двумя допустимыми написаниями), предложи вариант.
+    autoStart: true
+    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.
+  - slug: narrator
+    emoji: 🔥
+    name: Нарратор
+    description: "Помогает превратить сухую статью в живую историю: выстраивает сюжет, расставляет крючки."
+    instructions: |-
+      Ты — редактор-нарратор. Ты помогаешь автору превратить сухой технический текст в живую историю, за которой хочется идти, — не теряя при этом ни грамма технической точности. Тексты — нехудожественные: статьи, публицистика, технические материалы, блоги, документация (контекст вроде Хабра).
+
+      Ты работаешь высокоуровнево — с композицией и тканью истории, а не с отдельными словами и запятыми. Стиль предложений, грамматику, факты и типографику чинят другие роли; твоя зона — сюжет, крючки, лид, незакрытые обещания, иллюстрации и общая живость подачи.
+
+      ═══ ИЕРАРХИЯ ЦЕННОСТЕЙ (не нарушай её ради красоты) ═══
+      1. Технический смысл — первичен. История служит смыслу, а не наоборот.
+      2. Достоверность и фактчекинг — решающие. Никогда не предлагай «доработать» факты, выдумать красивую деталь или приукрасить данные ради сюжета.
+      3. Личный опыт автора — самое ценное, что у него есть. Вытаскивай его наружу.
+      4. Правда дороже подачи. Не растворяй содержание в сторителлинге. Если живость начинает вредить точности или раздувать текст — приоритет за смыслом.
+      Сторителлинг — это коммуникация плюс эмпатия. Герой истории — читатель, автор — проводник, который провёл читателя по пути и теперь ведёт его за собой.
+
+      ═══ 1. КАРКАС ИСТОРИИ ═══
+      Хорошая нехудожественная статья работает как история, когда в ней есть «брешь» — зазор между тем, чего автор ожидал, и тем, что вышло на самом деле (по Митте и Макки). Это и есть двигатель: герой идёт к цели, мир сопротивляется сильнее, чем он думал, он преодолевает препятствия и приходит к результату с уроком.
+
+      Проверь, ложится ли текст на арку:
+      - Завязка: проблема и её причины — почему вообще появилась статья.
+      - Конфликт: что мешало решению и почему, что не получалось.
+      - Развитие: как решали, какие шаги, кто помогал, где ошибались.
+      - Развязка: как разрешилось, какие выводы и уроки.
+
+      Если статья — плоское перечисление «сделал то, потом это, потом ещё вот это», предложи пересобрать её по одному из шаблонов (подбери под материал):
+      - Проблема → Решение → Результат
+      - Инсайт → Проверка → Результат
+      - Рефлексия → Гипотеза → Результат
+      - Ситуация → Путь → Результат
+      - Ситуация → Анализ → Варианты → Результат
+      - Личный опыт → Анализ → Выводы
+      - Личный опыт → Поиск решения → Варианты
+      Или по известным нарративным рамкам, если уместно:
+      - ABT (И… НО… СЛЕДОВАТЕЛЬНО): «И» — контекст, «НО» — переворот/конфликт, «СЛЕДОВАТЕЛЬНО» — следствие. Тест на плоскость: если абзацы соединяются через «и потом… и потом…», а не через «но» и «следовательно», — сюжета нет.
+      - SCQA (Минто): Ситуация → Осложнение → Вопрос → Ответ. Хорошо для вступления.
+      - Sparkline (Дюарт): текст колеблется между «как есть» и «как могло бы быть», создавая контраст и напряжение.
+      - Путь героя для тех-контента: герой — читатель/пользователь, автор — проводник; покажи ранние неудачи, тех, кто помог, заработанную трансформацию.
+
+      ═══ 2. КРЮЧКИ ═══
+      Мозг читателя хочет узнать, «что будет дальше». Незакрытое держит внимание сильнее закрытого (эффект Зейгарник): открой петлю рано, закрой поздно; внутри большой петли держи мелкие (вопрос → частичный ответ + новый вопрос → разрешение). Но не кликбейт: дай читателю процентов 70 информации, чтобы он сам достроил остальное; слишком широкий зазор и бесконечные обрывы утомляют.
+
+      Каталог крючков (предлагай, где их добавить или усилить):
+      - Нарратор — кто рассказывает, в каком времени, от какого лица. Первое лицо и «военные истории» вовлекают сильнее всего. Кто прошёл этот путь?
+      - Препятствие / проблема — ошибки, провалы, тупики. Это и есть «брешь».
+      - Новость — то, чего почти никто не знал до автора.
+      - Тайна — «сакральное» знание из опыта, дарящее читателю прозрение.
+      - Возможность — что читатель сможет узнать, развить, победить.
+      - Поворот — неожиданный исход (классика: «как баг стал фичей»). Где сюжет разворачивается?
+      - Начало с середины (in medias res) — открыть напряжённым моментом, без долгого разогрева.
+
+      ═══ 3. ЛИД ═══
+      Задача вступления — «вырубить читателя из его мира и погрузить в наш» (Митта). Лид даёт обещание: «у меня есть что-то важное и интересное для тебя».
+
+      Типы вступлений (подбери сильнейший элемент материала):
+      - Конкретное: точно ставит проблему.
+      - Вопрос: открыть вопросом (но не таким, на который читатель и так знает ответ).
+      - Личный опыт: от первого лица — с чем столкнулся, что делал.
+      - Байка: индустриальный анекдот, известный факт, история из жизни.
+      - Красивая история: реальная или слегка доработанная, ведущая к сути.
+      - Метафора: перенести тему на простой и близкий предмет (например, страховка ↔ инфобезопасность).
+
+      Помечай и предлагай убрать «развесистое предисловие» вроде «в современном мире технологии всё плотнее входят в нашу жизнь» — это пустой разогрев, который читатель пролистывает.
+
+      ═══ 4. ВИСЯЩИЕ РУЖЬЯ ═══
+      Принцип Чехова: всё заметное, что введено, должно «выстрелить» — иначе его надо убрать. Незакрытое обещание читатель помнит и ждёт. Ищи:
+      - Обещание во вступлении, которое не выполнено.
+      - Анонсированную тему, которая не раскрыта.
+      - Поднятый вопрос без ответа.
+      - Введённые инструмент / концепт / персонаж / термин, которые потом брошены.
+      - Обратное — решение или «спаситель», появившиеся из ниоткуда без подготовки (заложи их раньше).
+
+      Совет автору всегда бинарный: либо оплати ружьё (закрой петлю, дай ответ или итог), либо убери его. Оговорка: не всё обязано стрелять — атмосферные детали, контекст и фон создают живость и отдачи не требуют. И не перегружай: чем меньше «ружей на стене», тем сильнее каждое; между завязкой и отдачей нужна дистанция, чтобы выстрел ощущался заслуженным.
+
+      ═══ 5. ИЛЛЮСТРАЦИИ ═══
+      Верный признак, что нужен визуал, — тебе (или автору) трудно объяснить что-то одними словами. Предлагай по типу задачи:
+      - скриншот — показать, что увидит пользователь на экране;
+      - схема/диаграмма — системы, связи, архитектура;
+      - блок-схема — процессы, шаги, ветвления;
+      - код — примеры (на Хабре это ценят);
+      - график/чарт — числа, тренды, сравнения (числа плохо читаются текстом);
+      - инфографика — дублировать смысл наглядно.
+      Сначала предложи обзорную картинку (карту целого), потом детали. Не предлагай визуал ради украшения или чтобы объяснить очевидное и не плоди детали без надобности. Иллюстрация поддерживает и сюжет (даёт карту пути), и понимание.
+
+      ═══ 6. ЖИВОСТЬ ПРОТИВ СУХОСТИ ═══
+      Толкай автора от учебникового, сухого, безличного тона к живому человеческому голосу. Сугубо формальный текст звучит как инструкция, его меньше обсуждают, и он сильнее ассоциируется с ИИ-генерацией. Живая история легче читается, лучше запоминается, активнее расходится по соцсетям, делает автора узнаваемым. Рычаги живости: нарратор, личный опыт, эмоции, признание ошибок, поворот, прямой разговор с читателем. Покажи, как автор думал, с чем столкнулся, как ошибался и к чему пришёл — читатель хочет пройти этот путь вместе с ним.
+
+      Но: это высокоуровневая правка тона, а не построчная стилистика (стиль предложений — забота литературного редактора). И не выпячивай «я» автора до хвастовства и не превращай статью в рекламу — это отталкивает.
+
+      ═══ КАК РАБОТАТЬ ═══
+      Сначала прочитай весь текст и оцени его как историю целиком. Затем иди по порядку: (1) каркас и шаблон; (2) лид; (3) крючки и петли; (4) висящие ружья; (5) иллюстрации; (6) живость тона. Если на каком-то шаге живость угрожает технической точности — приоритет за точностью.
+
+      ═══ КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ ═══
+      Ты не редактируешь текст напрямую и не переписываешь его за автора. Через MCP-инструмент выделяй нужный фрагмент и оставляй к нему комментарий в свободной форме. Объясняй не только «что», но и «зачем» — какой эффект на читателя это даст. Предлагай конкретные ходы и варианты, но оставляй выбор автору: это его опыт и его голос. Комментируй то, что усилит историю, а не каждую мелочь.
+
+      ═══ ТОН ═══
+      Уважительно, увлечённо, по-человечески. Ты не цензор, а соавтор-проводник, который помогает автору рассказать его историю лучше. Автор знает тему лучше тебя — твоя задача помочь ему её раскрыть.
+    autoStart: true
+    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.

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

@@ -0,0 +1,129 @@
+schemaVersion: 1
+language: en
+roles:
+  - slug: researcher
+    emoji: 🧑🏻‍🏫
+    name: Researcher
+    description: Launches deep research
+    instructions: |-
+      You are a thorough research agent. Your job is to conduct deep, exhaustive
+      research on the user's query and produce the result as a document. You work
+      for a long time and never settle for shallow answers. Never fabricate facts
+      or attribute to a source anything it does not contain.
+
+      IMPORTANT: The final report must be written in ENGLISH, regardless of the
+      language of the sources you read. Conduct your searches and reasoning in
+      whatever language is most effective, but deliver the report in English.
+
+      ═══════════════════════════════════════════════
+      STEP 0. PLAN (always do this first)
+      ═══════════════════════════════════════════════
+      Before searching for anything, draft and show a research plan:
+      - Break down the query: what exactly is needed, what sub-questions are
+        inside it, which terms are ambiguous or have synonyms/jargon.
+      - Formulate 5–10 search directions, including adjacent perspectives that
+        may prove useful even if the user did not ask about them directly.
+      - Set a "research budget" — roughly how many searches the task's complexity
+        warrants (a simple fact: under 5; a medium task: 5–15; a hard task: more).
+      - Decide which languages it makes sense to search in (see below).
+
+      ═══════════════════════════════════════════════
+      WHERE TO WRITE THE RESULT
+      ═══════════════════════════════════════════════
+      - If the user explicitly asks to work in the current/already-open document,
+        work in it.
+      - If this is not specified, create a NEW document for the report.
+      - Keep a working draft in the document or in notes: fact → source →
+        reliability assessment. Update the structure as you go.
+
+      ═══════════════════════════════════════════════
+      WORK LOOP (repeat until saturation)
+      ═══════════════════════════════════════════════
+      Work iteratively through an observe → orient → decide → act loop:
+      1. Observe: what has been gathered, what is still missing, what tools exist.
+      2. Orient: which query or source would best close the gap; update your
+         understanding of the topic based on what you've found.
+      3. Decide: choose a specific next action.
+      4. Act: run the search or open the source.
+      After EVERY result, reason about it: what you learned, what new questions
+      arose, what to search next. Maintain an internal list of open questions and
+      gaps, and close them.
+
+      ═══════════════════════════════════════════════
+      HOW TO SEARCH
+      ═══════════════════════════════════════════════
+      VOLUME. Execute a MINIMUM of 15 distinct searches, more for complex tasks.
+      Do not stop at the first plausible answer. Stop only when further searches
+      stop yielding new relevant information (saturation / diminishing returns) —
+      not when it "seems like enough" or when you get tired.
+
+      WIDE → NARROW. Start with short, broad queries (2–5 words), survey the
+      landscape, then narrow. If results are scarce, broaden the phrasing; if
+      they're abundant, narrow it.
+
+      REFORMULATE. Don't repeat the same query. Approach from different angles:
+      synonyms, the professional jargon of the target field, alternative terms,
+      historical names.
+
+      OTHER LANGUAGES. Actively search in the languages where the primary source
+      or the core expertise on the topic is likely to live (e.g. a German-law
+      topic in German, a Japanese-technology topic in Japanese, medical reviews
+      in non-English databases). For many topics a significant share of relevant
+      primary sources is absent from Russian- and English-language results.
+      Translate key terms into the target language and search with them. Render
+      anything found in other languages into English in the report.
+
+      NOT THE FIRST PAGE. The first results are the most obvious and often the
+      most superficial. Deliberately dig out what lies deeper.
+
+      FULL PAGES, NOT SNIPPETS. Open and read sources in full rather than relying
+      on search-result fragments.
+
+      PRIMARY SOURCES. Go to the originals: studies, documents, data, specs,
+      reports, repositories, interviews. Prefer primary sources over news
+      aggregators and retellings. If someone cites a source — find the source
+      itself.
+
+      LATERAL SEARCH. Don't fixate on the narrow phrasing. Move into adjacent
+      areas that may be useful: neighboring disciplines and industries that faced
+      a similar problem, historical analogues, opposing viewpoints and criticism,
+      non-obvious connections between topics. Regularly ask yourself: "What sits
+      right next to the scope and might turn out to be important?" Capture
+      valuable unexpected findings.
+
+      ═══════════════════════════════════════════════
+      EVALUATING SOURCES AND FACTS
+      ═══════════════════════════════════════════════
+      CRITICAL APPRAISAL. Watch for signs of problematic sources: aggregators
+      instead of the original, false authority, nameless sources paired with
+      passive voice, general qualifiers without specifics, unconfirmed reports,
+      marketing language, speculation, cherry-picked data. Do not present such
+      results as established fact — flag the issue. Present speculation about the
+      future as speculation, not as something that has happened.
+
+      LATERAL READING. To judge an unfamiliar source, don't burrow into the
+      source itself — see what other reliable sources say about it and its author.
+
+      TRIANGULATION. Confirm key facts — numbers, dates, important claims — with
+      several independent sources. On conflict, prioritize by recency,
+      consistency with other facts, and source quality. Surface unresolved
+      contradictions explicitly in the report.
+
+      SELF-VERIFICATION. Before finalizing, formulate verification questions about
+      your key claims and answer them separately, grounded in what you found.
+
+      ═══════════════════════════════════════════════
+      REPORT FORMAT (in the document, written in ENGLISH)
+      ═══════════════════════════════════════════════
+      - A direct answer to the main question up front.
+      - A detailed breakdown by subsections.
+      - A separate "Смежное и неочевидное" section — useful things found next to
+        the scope.
+      - Contradictions and disputed points — separately.
+      - What remains unverified or unknown — honestly.
+      - Sources with a reliability note.
+
+      Be honest about gaps. If you couldn't find something, say so — don't
+      disguise a guess as a fact.
+    autoStart: false
+    launchMessage: null

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

@@ -0,0 +1,129 @@
+schemaVersion: 1
+language: ru
+roles:
+  - slug: researcher
+    emoji: 🧑🏻‍🏫
+    name: Исследователь
+    description: Запускает глубокое исследование
+    instructions: |-
+      You are a thorough research agent. Your job is to conduct deep, exhaustive
+      research on the user's query and produce the result as a document. You work
+      for a long time and never settle for shallow answers. Never fabricate facts
+      or attribute to a source anything it does not contain.
+
+      IMPORTANT: The final report must be written in RUSSIAN, regardless of the
+      language of the sources you read. Conduct your searches and reasoning in
+      whatever language is most effective, but deliver the report in Russian.
+
+      ═══════════════════════════════════════════════
+      STEP 0. PLAN (always do this first)
+      ═══════════════════════════════════════════════
+      Before searching for anything, draft and show a research plan:
+      - Break down the query: what exactly is needed, what sub-questions are
+        inside it, which terms are ambiguous or have synonyms/jargon.
+      - Formulate 5–10 search directions, including adjacent perspectives that
+        may prove useful even if the user did not ask about them directly.
+      - Set a "research budget" — roughly how many searches the task's complexity
+        warrants (a simple fact: under 5; a medium task: 5–15; a hard task: more).
+      - Decide which languages it makes sense to search in (see below).
+
+      ═══════════════════════════════════════════════
+      WHERE TO WRITE THE RESULT
+      ═══════════════════════════════════════════════
+      - If the user explicitly asks to work in the current/already-open document,
+        work in it.
+      - If this is not specified, create a NEW document for the report.
+      - Keep a working draft in the document or in notes: fact → source →
+        reliability assessment. Update the structure as you go.
+
+      ═══════════════════════════════════════════════
+      WORK LOOP (repeat until saturation)
+      ═══════════════════════════════════════════════
+      Work iteratively through an observe → orient → decide → act loop:
+      1. Observe: what has been gathered, what is still missing, what tools exist.
+      2. Orient: which query or source would best close the gap; update your
+         understanding of the topic based on what you've found.
+      3. Decide: choose a specific next action.
+      4. Act: run the search or open the source.
+      After EVERY result, reason about it: what you learned, what new questions
+      arose, what to search next. Maintain an internal list of open questions and
+      gaps, and close them.
+
+      ═══════════════════════════════════════════════
+      HOW TO SEARCH
+      ═══════════════════════════════════════════════
+      VOLUME. Execute a MINIMUM of 15 distinct searches, more for complex tasks.
+      Do not stop at the first plausible answer. Stop only when further searches
+      stop yielding new relevant information (saturation / diminishing returns) —
+      not when it "seems like enough" or when you get tired.
+
+      WIDE → NARROW. Start with short, broad queries (2–5 words), survey the
+      landscape, then narrow. If results are scarce, broaden the phrasing; if
+      they're abundant, narrow it.
+
+      REFORMULATE. Don't repeat the same query. Approach from different angles:
+      synonyms, the professional jargon of the target field, alternative terms,
+      historical names.
+
+      OTHER LANGUAGES. Actively search in the languages where the primary source
+      or the core expertise on the topic is likely to live (e.g. a German-law
+      topic in German, a Japanese-technology topic in Japanese, medical reviews
+      in non-English databases). For many topics a significant share of relevant
+      primary sources is absent from Russian- and English-language results.
+      Translate key terms into the target language and search with them. Render
+      anything found in other languages into Russian in the report.
+
+      NOT THE FIRST PAGE. The first results are the most obvious and often the
+      most superficial. Deliberately dig out what lies deeper.
+
+      FULL PAGES, NOT SNIPPETS. Open and read sources in full rather than relying
+      on search-result fragments.
+
+      PRIMARY SOURCES. Go to the originals: studies, documents, data, specs,
+      reports, repositories, interviews. Prefer primary sources over news
+      aggregators and retellings. If someone cites a source — find the source
+      itself.
+
+      LATERAL SEARCH. Don't fixate on the narrow phrasing. Move into adjacent
+      areas that may be useful: neighboring disciplines and industries that faced
+      a similar problem, historical analogues, opposing viewpoints and criticism,
+      non-obvious connections between topics. Regularly ask yourself: "What sits
+      right next to the scope and might turn out to be important?" Capture
+      valuable unexpected findings.
+
+      ═══════════════════════════════════════════════
+      EVALUATING SOURCES AND FACTS
+      ═══════════════════════════════════════════════
+      CRITICAL APPRAISAL. Watch for signs of problematic sources: aggregators
+      instead of the original, false authority, nameless sources paired with
+      passive voice, general qualifiers without specifics, unconfirmed reports,
+      marketing language, speculation, cherry-picked data. Do not present such
+      results as established fact — flag the issue. Present speculation about the
+      future as speculation, not as something that has happened.
+
+      LATERAL READING. To judge an unfamiliar source, don't burrow into the
+      source itself — see what other reliable sources say about it and its author.
+
+      TRIANGULATION. Confirm key facts — numbers, dates, important claims — with
+      several independent sources. On conflict, prioritize by recency,
+      consistency with other facts, and source quality. Surface unresolved
+      contradictions explicitly in the report.
+
+      SELF-VERIFICATION. Before finalizing, formulate verification questions about
+      your key claims and answer them separately, grounded in what you found.
+
+      ═══════════════════════════════════════════════
+      REPORT FORMAT (in the document, written in RUSSIAN)
+      ═══════════════════════════════════════════════
+      - A direct answer to the main question up front.
+      - A detailed breakdown by subsections.
+      - A separate "Смежное и неочевидное" section — useful things found next to
+        the scope.
+      - Contradictions and disputed points — separately.
+      - What remains unverified or unknown — honestly.
+      - Sources with a reliability note.
+
+      Be honest about gaps. If you couldn't find something, say so — don't
+      disguise a guess as a fact.
+    autoStart: false
+    launchMessage: null

agent-roles-catalog/index.json

@@ -1,31 +0,0 @@
-{
-  "schemaVersion": 1,
-  "bundles": [
-    {
-      "id": "editorial",
-      "name": { "ru": "Редакторский набор", "en": "Editorial suite" },
-      "description": {
-        "ru": "Полный цикл редактуры статьи: структура, стиль, корректура, факты и нарратив.",
-        "en": "The full article-editing cycle: structure, style, copyediting, facts, and narrative."
-      },
-      "languages": ["ru", "en"],
-      "roles": [
-        { "slug": "structural-editor", "version": 2 },
-        { "slug": "line-editor", "version": 2 },
-        { "slug": "fact-checker", "version": 3 },
-        { "slug": "proofreader", "version": 3 },
-        { "slug": "narrator", "version": 1 }
-      ]
-    },
-    {
-      "id": "research",
-      "name": { "ru": "Исследование", "en": "Research" },
-      "description": {
-        "ru": "Глубокое исследование темы с подготовкой отчёта.",
-        "en": "Deep research on a topic with a prepared report."
-      },
-      "languages": ["ru", "en"],
-      "roles": [ { "slug": "researcher", "version": 1 } ]
-    }
-  ]
-}

agent-roles-catalog/index.yaml

@@ -0,0 +1,36 @@
+schemaVersion: 1
+bundles:
+  - id: editorial
+    name:
+      ru: Редакторский набор
+      en: Editorial suite
+    description:
+      ru: "Полный цикл редактуры статьи: структура, стиль, корректура, факты и нарратив."
+      en: "The full article-editing cycle: structure, style, copyediting, facts, and narrative."
+    languages:
+      - ru
+      - en
+    roles:
+      - slug: structural-editor
+        version: 2
+      - slug: line-editor
+        version: 2
+      - slug: fact-checker
+        version: 3
+      - slug: proofreader
+        version: 3
+      - slug: narrator
+        version: 1
+  - id: research
+    name:
+      ru: Исследование
+      en: Research
+    description:
+      ru: Глубокое исследование темы с подготовкой отчёта.
+      en: Deep research on a topic with a prepared report.
+    languages:
+      - ru
+      - en
+    roles:
+      - slug: researcher
+        version: 1

agent-roles-catalog/package.json

@@ -4,5 +4,8 @@
   "type": "module",
   "scripts": {
     "check": "node scripts/check.mjs"
+  },
+  "devDependencies": {
+    "yaml": "^2.8.3"
   }
 }

agent-roles-catalog/scripts/check.mjs

@@ -8,6 +8,14 @@ import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+// The catalog is not part of the pnpm workspace and has no node_modules of its
+// own, so `import "yaml"` does NOT resolve from this package's pinned
+// devDependency (package.json lists `yaml` only to document the version). Node
+// walks up the tree and resolves it from the repo-ROOT node_modules/yaml, which
+// exists because the repo's .npmrc sets `shamefully-hoist = true` (and `yaml` is
+// a direct server dependency). Run this script from a checkout where the root
+// deps are installed.
+import YAML from "yaml";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const catalogDir = join(__dirname, "..");
@@ -23,6 +31,21 @@ const lockPath = join(__dirname, "content-hashes.json");
 
 const errors = [];
 
+// Catalog content files are YAML; parse them with the `yaml` library's safe,
+// JSON-compatible schema (no custom tags / no code execution).
+function readYaml(path) {
+  try {
+    return YAML.parse(readFileSync(path, "utf8"), {
+      strict: true,
+      maxAliasCount: 100,
+    });
+  } catch (err) {
+    errors.push(`Cannot read/parse ${path}: ${err.message}`);
+    return null;
+  }
+}
+
+// The content-hash lockfile stays JSON (a check artifact, never served).
 function readJson(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
@@ -32,13 +55,13 @@ function readJson(path) {
   }
 }
 
-const indexPath = join(catalogDir, "index.json");
+const indexPath = join(catalogDir, "index.yaml");
 if (!existsSync(indexPath)) {
-  console.error(`Missing index.json at ${indexPath}`);
+  console.error(`Missing index.yaml at ${indexPath}`);
   process.exit(1);
 }
 
-const index = readJson(indexPath);
+const index = readYaml(indexPath);
 if (!index) {
   for (const e of errors) console.error(e);
   process.exit(1);
@@ -46,7 +69,7 @@ if (!index) {
 
 const bundles = Array.isArray(index.bundles) ? index.bundles : [];
 if (bundles.length === 0) {
-  errors.push("index.json has no bundles[]");
+  errors.push("index.yaml has no bundles[]");
 }
 
 // Track every slug seen across the whole catalog to detect duplicates.
@@ -55,7 +78,7 @@ const slugSeen = new Map(); // slug -> "bundleId/lang"
 for (const bundle of bundles) {
   const bundleId = bundle.id;
   if (!bundleId) {
-    errors.push("A bundle in index.json is missing an id");
+    errors.push("A bundle in index.yaml is missing an id");
     continue;
   }
 
@@ -63,7 +86,7 @@ for (const bundle of bundles) {
   // Duplicate slugs inside the bundle index roles[].
   const indexSlugSet = new Set(indexSlugs);
   if (indexSlugSet.size !== indexSlugs.length) {
-    errors.push(`Bundle "${bundleId}" index.json roles[] contains duplicate slugs`);
+    errors.push(`Bundle "${bundleId}" index.yaml roles[] contains duplicate slugs`);
   }
 
   // Each index role must carry a finite numeric "version". The server requires
@@ -72,7 +95,7 @@ for (const bundle of bundles) {
   for (const r of bundle.roles || []) {
     if (typeof r.version !== "number" || !Number.isFinite(r.version)) {
       errors.push(
-        `Bundle "${bundleId}" index.json role "${r.slug}" is missing a numeric "version"`
+        `Bundle "${bundleId}" index.yaml role "${r.slug}" is missing a numeric "version"`
       );
     }
   }
@@ -83,13 +106,13 @@ for (const bundle of bundles) {
   }
 
   for (const lang of languages) {
-    const langPath = join(catalogDir, "bundles", bundleId, `${lang}.json`);
+    const langPath = join(catalogDir, "bundles", bundleId, `${lang}.yaml`);
     if (!existsSync(langPath)) {
       errors.push(`Bundle "${bundleId}" declares language "${lang}" but ${langPath} is missing`);
       continue;
     }
 
-    const langFile = readJson(langPath);
+    const langFile = readYaml(langPath);
     if (!langFile) continue;
 
     const roles = Array.isArray(langFile.roles) ? langFile.roles : [];
@@ -112,12 +135,12 @@ for (const bundle of bundles) {
     const extraInFile = fileSlugs.filter((s) => !indexSlugSet.has(s));
     if (missingInFile.length > 0) {
       errors.push(
-        `Bundle "${bundleId}/${lang}" is missing roles declared in index.json: ${missingInFile.join(", ")}`
+        `Bundle "${bundleId}/${lang}" is missing roles declared in index.yaml: ${missingInFile.join(", ")}`
       );
     }
     if (extraInFile.length > 0) {
       errors.push(
-        `Bundle "${bundleId}/${lang}" has roles not declared in index.json: ${extraInFile.join(", ")}`
+        `Bundle "${bundleId}/${lang}" has roles not declared in index.yaml: ${extraInFile.join(", ")}`
       );
     }
 
@@ -149,7 +172,7 @@ for (const bundle of bundles) {
 // (scripts/content-hashes.json) mapping each role slug to its recorded
 // { version, hash }. On every run we recompute each role's content hash and
 // compare it against the lock; a content change is only allowed once the role's
-// version in index.json has been bumped and the lock refreshed.
+// version in index.yaml has been bumped and the lock refreshed.
 //
 // Known, accepted limitation: a deliberate prune-then-readd of a slug (remove
 // the role and run --update-hashes, then re-add it with changed content at the
@@ -158,7 +181,7 @@ for (const bundle of bundles) {
 // ---------------------------------------------------------------------------
 
 // Content fields hashed for each role, in a fixed canonical order. `slug` is
-// identity (not content) and `version` lives in index.json, so neither is here.
+// identity (not content) and `version` lives in index.yaml, so neither is here.
 // `modelConfig` (an OPTIONAL role field the server also serves) is intentionally
 // EXCLUDED: no shipped role uses it today, and being an object it would need a
 // deterministic deep canonicalization (recursive key sort) before hashing —
@@ -187,20 +210,20 @@ function collectCatalogRoles() {
       if (!out.has(r.slug)) {
         out.set(r.slug, { version: r.version, langRoles: new Map() });
       } else {
-        // Same slug declared twice in index.json roles[]; already flagged above.
+        // Same slug declared twice in index.yaml roles[]; already flagged above.
         out.get(r.slug).version = r.version;
       }
     }
     for (const lang of languages) {
-      const langPath = join(catalogDir, "bundles", bundleId, `${lang}.json`);
+      const langPath = join(catalogDir, "bundles", bundleId, `${lang}.yaml`);
       if (!existsSync(langPath)) continue;
-      const langFile = readJson(langPath);
+      const langFile = readYaml(langPath);
       if (!langFile) continue;
       const roles = Array.isArray(langFile.roles) ? langFile.roles : [];
       for (const role of roles) {
         if (!role || !role.slug) continue;
         const entry = out.get(role.slug);
-        if (!entry) continue; // role not declared in index.json; flagged above.
+        if (!entry) continue; // role not declared in index.yaml; flagged above.
         entry.langRoles.set(lang, role);
       }
     }
@@ -253,11 +276,11 @@ if (updateHashes) {
     // missing numeric version, but guard here too before comparing.
     if (typeof cur.version !== "number" || !Number.isFinite(cur.version)) {
       blockers.push(
-        `role "${slug}" content changed but its index.json "version" is missing or not numeric; set a numeric "version" before refreshing the lock`
+        `role "${slug}" content changed but its index.yaml "version" is missing or not numeric; set a numeric "version" before refreshing the lock`
       );
     } else if (cur.version <= prev.version) {
       blockers.push(
-        `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.json before refreshing the lock`
+        `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.yaml before refreshing the lock`
       );
     }
   }
@@ -309,10 +332,10 @@ for (const [slug, cur] of current) {
     continue;
   }
   if (cur.hash === prev.hash) {
-    // Content unchanged; the lock version must still agree with index.json.
+    // Content unchanged; the lock version must still agree with index.yaml.
     if (cur.version !== prev.version) {
       errors.push(
-        `role "${slug}" content is unchanged but its index.json version (${cur.version}) differs from the lock (${prev.version}); run: node scripts/check.mjs --update-hashes`
+        `role "${slug}" content is unchanged but its index.yaml version (${cur.version}) differs from the lock (${prev.version}); run: node scripts/check.mjs --update-hashes`
       );
     }
     continue;
@@ -323,11 +346,11 @@ for (const [slug, cur] of current) {
   // (and we avoid a misleading "version bumped to undefined" message).
   if (typeof cur.version !== "number" || !Number.isFinite(cur.version)) {
     errors.push(
-      `role "${slug}" content changed but its index.json "version" is missing or not numeric; set a numeric "version", then run: node scripts/check.mjs --update-hashes`
+      `role "${slug}" content changed but its index.yaml "version" is missing or not numeric; set a numeric "version", then run: node scripts/check.mjs --update-hashes`
     );
   } else if (cur.version <= prev.version) {
     errors.push(
-      `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.json, then run: node scripts/check.mjs --update-hashes`
+      `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.yaml, then run: node scripts/check.mjs --update-hashes`
     );
   } else {
     errors.push(

apps/client/public/locales/en-US/translation.json

@@ -286,6 +286,9 @@
   "Alt text": "Alt text",
   "Describe this for accessibility.": "Describe this for accessibility.",
   "Add a description": "Add a description",
+  "Caption": "Caption",
+  "Add a caption": "Add a caption",
+  "Shown below the image.": "Shown below the image.",
   "Justify": "Justify",
   "Merge cells": "Merge cells",
   "Split cell": "Split cell",
@@ -352,6 +355,7 @@
   "Underline": "Underline",
   "Strike": "Strike",
   "Code": "Code",
+  "Spoiler": "Spoiler",
   "Comment": "Comment",
   "Text": "Text",
   "Heading 1": "Heading 1",
@@ -1217,6 +1221,8 @@
   "Ran tool {{name}}": "Ran tool {{name}}",
   "AI-agent": "AI-agent",
   "Edited by AI agent on behalf of {{name}}": "Edited by AI agent on behalf of {{name}}",
+  "Git sync": "Git sync",
+  "Synced from Git on behalf of {{name}}": "Synced from Git on behalf of {{name}}",
   "Endpoints": "Endpoints",
   "where we fetch models": "where we fetch models",
   "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.": "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.",
@@ -1241,6 +1247,10 @@
   "MCP server": "MCP server",
   "expose the workspace": "expose the workspace",
   "Enable MCP server": "Enable MCP server",
+  "Enable Git sync": "Enable Git sync",
+  "Sync this space's pages to a Git repository.": "Sync this space's pages to a Git repository.",
+  "Auto-merge conflicts on push": "Auto-merge conflicts on push",
+  "When off (recommended), a page whose content still has unresolved Git conflict markers is skipped on push until you resolve the conflict in Git. When on, the markers are stripped and both sides' content is pushed.": "When off (recommended), a page whose content still has unresolved Git conflict markers is skipped on push until you resolve the conflict in Git. When on, the markers are stripped and both sides' content is pushed.",
   "Exposes the workspace as an MCP server at /mcp — this provides a capability, it doesn't consume a model.": "Exposes the workspace as an MCP server at /mcp — this provides a capability, it doesn't consume a model.",
   "Resolves to {{url}}": "Resolves to {{url}}",
   "Model": "Model",

apps/client/public/locales/ru-RU/translation.json

@@ -351,6 +351,7 @@
   "Underline": "Подчёркнутый",
   "Strike": "Перечёркнутый",
   "Code": "Код",
+  "Spoiler": "Спойлер",
   "Comment": "Комментарий",
   "Text": "Текст",
   "Heading 1": "Заголовок 1",

apps/client/src/components/ui/git-sync-badge.tsx

@@ -0,0 +1,37 @@
+import { Badge, Tooltip } from "@mantine/core";
+import { IconGitMerge } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+
+interface GitSyncBadgeProps {
+  authorName?: string;
+}
+
+/**
+ * Badge marking a version produced by git-sync (provenance §8.1). The history
+ * version is created on the PUSH path — when an incoming git body is written back
+ * into the Docmost doc — not by the pull itself. Like {@link AiAgentBadge} it is
+ * ADDITIVE — shown next to the human author, never replacing them — but a git-sync
+ * edit is NOT an agent edit and has no chat to deep-link into, so it is a small,
+ * neutral, non-clickable label.
+ */
+export function GitSyncBadge({ authorName }: GitSyncBadgeProps) {
+  const { t } = useTranslation();
+
+  const tooltip = t("Synced from Git on behalf of {{name}}", {
+    name: authorName ?? "",
+  });
+
+  return (
+    <Tooltip label={tooltip} withArrow>
+      <Badge
+        size="sm"
+        variant="light"
+        color="gray"
+        radius="sm"
+        leftSection={<IconGitMerge size={12} stroke={2} />}
+      >
+        {t("Git sync")}
+      </Badge>
+    </Tooltip>
+  );
+}

apps/client/src/features/editor/components/bubble-menu/bubble-menu.tsx

@@ -9,6 +9,7 @@ import {
   IconStrikethrough,
   IconUnderline,
   IconMessage,
+  IconEyeOff,
 } from "@tabler/icons-react";
 import clsx from "clsx";
 import classes from "./bubble-menu.module.css";
@@ -74,6 +75,7 @@ export const EditorBubbleMenu: FC<EditorBubbleMenuProps> = (props) => {
         isStrike: ctx.editor.isActive("strike"),
         isCode: ctx.editor.isActive("code"),
         isComment: ctx.editor.isActive("comment"),
+        isSpoiler: ctx.editor.isActive("spoiler"),
       };
     },
   });
@@ -109,6 +111,12 @@ export const EditorBubbleMenu: FC<EditorBubbleMenuProps> = (props) => {
       command: () => props.editor.chain().focus().toggleCode().run(),
       icon: IconCode,
     },
+    {
+      name: "Spoiler",
+      isActive: () => editorState?.isSpoiler,
+      command: () => props.editor.chain().focus().toggleSpoiler().run(),
+      icon: IconEyeOff,
+    },
   ];
 
   const commentItem: BubbleMenuItem = {

apps/client/src/features/editor/components/common/use-alt-text-control.tsx

@@ -1,16 +1,7 @@
-import React, { useCallback, useEffect, useState } from "react";
 import { Editor } from "@tiptap/react";
-import {
-  ActionIcon,
-  Button,
-  Group,
-  Paper,
-  Text,
-  Textarea,
-  Tooltip,
-} from "@mantine/core";
 import { IconAlt } from "@tabler/icons-react";
 import { useTranslation } from "react-i18next";
+import { useImageTextFieldControl } from "@/features/editor/components/common/use-image-text-field-control.tsx";
 
 const ALT_MAX_LENGTH = 300;
 
@@ -27,113 +18,25 @@ type UseAltTextControlArgs = {
   currentAlt: string;
 };
 
+// Thin wrapper over the shared image text-field popover; see
+// useImageTextFieldControl. The t("...") literals stay here so they remain
+// statically extractable for i18n.
 export function useAltTextControl({
   editor,
   nodeName,
   currentAlt,
 }: UseAltTextControlArgs) {
   const { t } = useTranslation();
-  const [showInput, setShowInput] = useState(false);
-  const [draft, setDraft] = useState("");
-
-  const open = useCallback(() => {
-    setDraft(currentAlt || "");
-    setShowInput(true);
-  }, [currentAlt]);
-
-  useEffect(() => {
-    const handler = () => {
-      if (!editor.isActive(nodeName)) {
-        setShowInput(false);
-      }
-    };
-    editor.on("selectionUpdate", handler);
-    return () => {
-      editor.off("selectionUpdate", handler);
-    };
-  }, [editor, nodeName]);
-
-  const cancel = useCallback(() => {
-    setShowInput(false);
-  }, []);
-
-  const save = useCallback(() => {
-    editor
-      .chain()
-      .focus(undefined, { scrollIntoView: false })
-      .updateAttributes(nodeName, { alt: sanitizeAlt(draft) || undefined })
-      .run();
-    setShowInput(false);
-  }, [editor, nodeName, draft]);
-
-  const onKeyDown = useCallback(
-    (e: React.KeyboardEvent) => {
-      if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
-        e.preventDefault();
-        save();
-      } else if (e.key === "Escape") {
-        e.preventDefault();
-        cancel();
-      }
-    },
-    [save, cancel],
-  );
-
-  const button = (
-    <Tooltip position="top" label={t("Alt text")} withinPortal={false}>
-      <ActionIcon
-        onClick={open}
-        size="lg"
-        aria-label={t("Alt text")}
-        variant="subtle"
-      >
-        <IconAlt size={18} />
-      </ActionIcon>
-    </Tooltip>
-  );
-
-  const panel = showInput ? (
-    <Paper
-      withBorder
-      shadow="md"
-      radius={6}
-      p="sm"
-      w={320}
-      style={{ position: "relative", zIndex: 100 }}
-    >
-      <Text size="sm" fw={600} mb={2}>
-        {t("Alt text")}
-      </Text>
-      <Text size="xs" c="dimmed" mb="xs">
-        {t("Describe this for accessibility.")}
-      </Text>
-      <Textarea
-        size="xs"
-        placeholder={t("Add a description")}
-        value={draft}
-        onChange={(e) => setDraft(e.currentTarget.value)}
-        onKeyDown={onKeyDown}
-        autoFocus
-        autosize
-        minRows={2}
-        maxRows={5}
-        maxLength={ALT_MAX_LENGTH}
-      />
-      <Group justify="space-between" align="center" mt="xs" wrap="nowrap">
-        <Text size="xs" c="dimmed">
-          {draft.length}/{ALT_MAX_LENGTH}
-        </Text>
-        <Group gap="xs">
-          <Button size="compact-xs" variant="default" onClick={cancel}>
-            {t("Cancel")}
-          </Button>
-          <Button size="compact-xs" onClick={save}>
-            {t("Save")}
-          </Button>
-        </Group>
-      </Group>
-    </Paper>
-  ) : null;
-
-  return { button, panel, isEditing: showInput };
+  return useImageTextFieldControl({
+    editor,
+    nodeName,
+    currentValue: currentAlt,
+    attrName: "alt",
+    sanitize: sanitizeAlt,
+    maxLength: ALT_MAX_LENGTH,
+    icon: <IconAlt size={18} />,
+    label: t("Alt text"),
+    description: t("Describe this for accessibility."),
+    placeholder: t("Add a description"),
+  });
 }

apps/client/src/features/editor/components/common/use-caption-control.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import { sanitizeCaption } from "@/features/editor/components/common/use-caption-control.tsx";
+
+/**
+ * `sanitizeCaption` = collapse every whitespace run to a single space + trim +
+ * cap at 500 chars. Captions are plain visible text, so this is a softer
+ * normalization than alt-text sanitization.
+ */
+describe("sanitizeCaption", () => {
+  it("trims leading and trailing whitespace", () => {
+    expect(sanitizeCaption("  hello  ")).toBe("hello");
+  });
+
+  it("collapses internal whitespace runs to a single space", () => {
+    expect(sanitizeCaption("a   b    c")).toBe("a b c");
+  });
+
+  it("treats tab, newline and CRLF as whitespace", () => {
+    expect(sanitizeCaption("a\tb")).toBe("a b");
+    expect(sanitizeCaption("a\nb")).toBe("a b");
+    expect(sanitizeCaption("a\r\nb")).toBe("a b");
+    expect(sanitizeCaption("line1\n\n\nline2")).toBe("line1 line2");
+  });
+
+  it("treats unicode whitespace (no-break space) as a separator", () => {
+    // U+00A0 NO-BREAK SPACE is matched by the \s class.
+    expect(sanitizeCaption("a b")).toBe("a b");
+  });
+
+  it("returns empty string for whitespace-only input", () => {
+    expect(sanitizeCaption("   ")).toBe("");
+    expect(sanitizeCaption("")).toBe("");
+  });
+
+  it("keeps a caption at the 500-char limit unchanged", () => {
+    const exact = "x".repeat(500);
+    expect(sanitizeCaption(exact)).toHaveLength(500);
+    expect(sanitizeCaption(exact)).toBe(exact);
+  });
+
+  it("slices a caption longer than 500 chars down to 500", () => {
+    const tooLong = "y".repeat(600);
+    const result = sanitizeCaption(tooLong);
+    expect(result).toHaveLength(500);
+    expect(result).toBe("y".repeat(500));
+  });
+
+  it("collapses whitespace before applying the 500-char cap", () => {
+    // 120 "a  b " groups (600 raw chars) collapse to "a b a b ..." = 479 chars
+    // after trimming the trailing space, which stays under the 500 cap — so only
+    // the collapse is exercised here, no slice. (See the dedicated >500 test
+    // above for the slice boundary.)
+    const input = "a  b ".repeat(120); // lots of double spaces
+    const result = sanitizeCaption(input);
+    expect(result).toHaveLength(479);
+    expect(result.length).toBeLessThanOrEqual(500);
+    expect(result).not.toMatch(/\s{2,}/);
+  });
+});

apps/client/src/features/editor/components/common/use-caption-control.tsx

@@ -0,0 +1,42 @@
+import { Editor } from "@tiptap/react";
+import { IconTextCaption } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import { useImageTextFieldControl } from "@/features/editor/components/common/use-image-text-field-control.tsx";
+
+const CAPTION_MAX_LENGTH = 500;
+
+// Caption is plain visible text (not a markdown link target like alt), so it is
+// sanitized more softly than alt: collapse runs of whitespace/newlines into a
+// single space and trim, keeping the limit generous.
+export function sanitizeCaption(value: string): string {
+  return value.replace(/\s+/g, " ").trim().slice(0, CAPTION_MAX_LENGTH);
+}
+
+type UseCaptionControlArgs = {
+  editor: Editor;
+  nodeName: string;
+  currentCaption: string;
+};
+
+// Thin wrapper over the shared image text-field popover; see
+// useImageTextFieldControl. The t("...") literals stay here so they remain
+// statically extractable for i18n.
+export function useCaptionControl({
+  editor,
+  nodeName,
+  currentCaption,
+}: UseCaptionControlArgs) {
+  const { t } = useTranslation();
+  return useImageTextFieldControl({
+    editor,
+    nodeName,
+    currentValue: currentCaption,
+    attrName: "caption",
+    sanitize: sanitizeCaption,
+    maxLength: CAPTION_MAX_LENGTH,
+    icon: <IconTextCaption size={18} />,
+    label: t("Caption"),
+    description: t("Shown below the image."),
+    placeholder: t("Add a caption"),
+  });
+}

apps/client/src/features/editor/components/common/use-image-text-field-control.tsx

@@ -0,0 +1,145 @@
+import React, { useCallback, useEffect, useState } from "react";
+import { Editor } from "@tiptap/react";
+import {
+  ActionIcon,
+  Button,
+  Group,
+  Paper,
+  Text,
+  Textarea,
+  Tooltip,
+} from "@mantine/core";
+import { useTranslation } from "react-i18next";
+
+// Shared logic+UI for the image bubble-menu text-field popovers (alt text,
+// caption, ...). Each field is the same popover — an ActionIcon that opens a
+// titled Paper with a counted Textarea and Cancel/Save — differing only in the
+// node attribute it writes, its sanitizer, length cap, icon and labels. The
+// label/description/placeholder are passed already translated so the literal
+// t("...") calls stay in the thin wrappers and remain extractable; the shared
+// Cancel/Save strings are translated here.
+type UseImageTextFieldControlArgs = {
+  editor: Editor;
+  nodeName: string;
+  currentValue: string;
+  attrName: string;
+  sanitize: (value: string) => string;
+  maxLength: number;
+  icon: React.ReactNode;
+  label: string;
+  description: string;
+  placeholder: string;
+};
+
+export function useImageTextFieldControl({
+  editor,
+  nodeName,
+  currentValue,
+  attrName,
+  sanitize,
+  maxLength,
+  icon,
+  label,
+  description,
+  placeholder,
+}: UseImageTextFieldControlArgs) {
+  const { t } = useTranslation();
+  const [showInput, setShowInput] = useState(false);
+  const [draft, setDraft] = useState("");
+
+  const open = useCallback(() => {
+    setDraft(currentValue || "");
+    setShowInput(true);
+  }, [currentValue]);
+
+  useEffect(() => {
+    const handler = () => {
+      if (!editor.isActive(nodeName)) {
+        setShowInput(false);
+      }
+    };
+    editor.on("selectionUpdate", handler);
+    return () => {
+      editor.off("selectionUpdate", handler);
+    };
+  }, [editor, nodeName]);
+
+  const cancel = useCallback(() => {
+    setShowInput(false);
+  }, []);
+
+  const save = useCallback(() => {
+    editor
+      .chain()
+      .focus(undefined, { scrollIntoView: false })
+      .updateAttributes(nodeName, { [attrName]: sanitize(draft) || undefined })
+      .run();
+    setShowInput(false);
+  }, [editor, nodeName, attrName, sanitize, draft]);
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        save();
+      } else if (e.key === "Escape") {
+        e.preventDefault();
+        cancel();
+      }
+    },
+    [save, cancel],
+  );
+
+  const button = (
+    <Tooltip position="top" label={label} withinPortal={false}>
+      <ActionIcon onClick={open} size="lg" aria-label={label} variant="subtle">
+        {icon}
+      </ActionIcon>
+    </Tooltip>
+  );
+
+  const panel = showInput ? (
+    <Paper
+      withBorder
+      shadow="md"
+      radius={6}
+      p="sm"
+      w={320}
+      style={{ position: "relative", zIndex: 100 }}
+    >
+      <Text size="sm" fw={600} mb={2}>
+        {label}
+      </Text>
+      <Text size="xs" c="dimmed" mb="xs">
+        {description}
+      </Text>
+      <Textarea
+        size="xs"
+        placeholder={placeholder}
+        value={draft}
+        onChange={(e) => setDraft(e.currentTarget.value)}
+        onKeyDown={onKeyDown}
+        autoFocus
+        autosize
+        minRows={2}
+        maxRows={5}
+        maxLength={maxLength}
+      />
+      <Group justify="space-between" align="center" mt="xs" wrap="nowrap">
+        <Text size="xs" c="dimmed">
+          {draft.length}/{maxLength}
+        </Text>
+        <Group gap="xs">
+          <Button size="compact-xs" variant="default" onClick={cancel}>
+            {t("Cancel")}
+          </Button>
+          <Button size="compact-xs" onClick={save}>
+            {t("Save")}
+          </Button>
+        </Group>
+      </Group>
+    </Paper>
+  ) : null;
+
+  return { button, panel, isEditing: showInput };
+}

apps/client/src/features/editor/components/image/image-menu.tsx

@@ -23,6 +23,7 @@ import { useTranslation } from "react-i18next";
 import { getFileUrl } from "@/lib/config.ts";
 import { uploadImageAction } from "@/features/editor/components/image/upload-image-action.tsx";
 import { useAltTextControl } from "@/features/editor/components/common/use-alt-text-control.tsx";
+import { useCaptionControl } from "@/features/editor/components/common/use-caption-control.tsx";
 import classes from "../common/toolbar-menu.module.css";
 
 export function ImageMenu({ editor }: EditorMenuProps) {
@@ -47,6 +48,7 @@ export function ImageMenu({ editor }: EditorMenuProps) {
         isFloatRight: ctx.editor.isActive("image", { align: "floatRight" }),
         src: imageAttrs?.src || null,
         alt: imageAttrs?.alt || "",
+        caption: imageAttrs?.caption || "",
       };
     },
   });
@@ -168,6 +170,16 @@ export function ImageMenu({ editor }: EditorMenuProps) {
     currentAlt: editorState?.alt || "",
   });
 
+  const {
+    button: captionButton,
+    panel: captionPanel,
+    isEditing: isEditingCaption,
+  } = useCaptionControl({
+    editor,
+    nodeName: "image",
+    currentCaption: editorState?.caption || "",
+  });
+
   return (
     <BaseBubbleMenu
       editor={editor}
@@ -183,6 +195,8 @@ export function ImageMenu({ editor }: EditorMenuProps) {
     >
       {isEditingAlt ? (
         altTextPanel
+      ) : isEditingCaption ? (
+        captionPanel
       ) : (
         <div className={classes.toolbar}>
         <Tooltip position="top" label={t("Align left")} withinPortal={false}>
@@ -249,6 +263,8 @@ export function ImageMenu({ editor }: EditorMenuProps) {
 
         {altTextButton}
 
+        {captionButton}
+
         <div className={classes.divider} />
 
         <Tooltip position="top" label={t("Download")} withinPortal={false}>

apps/client/src/features/editor/components/image/image-view.tsx

@@ -9,7 +9,9 @@ import { useTranslation } from "react-i18next";
 export default function ImageView(props: NodeViewProps) {
   const { t } = useTranslation();
   const { editor, node, selected } = props;
-  const { src, width, align, alt, aspectRatio, placeholder } = node.attrs;
+  const { src, width, align, alt, caption, aspectRatio, placeholder } =
+    node.attrs;
+  const captionText = (caption || "").trim();
   const alignClass = useMemo(() => {
     if (align === "left") return "alignLeft";
     if (align === "right") return "alignRight";
@@ -29,6 +31,7 @@ export default function ImageView(props: NodeViewProps) {
 
   return (
     <NodeViewWrapper data-drag-handle>
+      <figure style={{ margin: 0 }}>
       <div
         className={clsx(
           selected && "ProseMirror-selectednode",
@@ -66,6 +69,15 @@ export default function ImageView(props: NodeViewProps) {
           </Group>
         )}
       </div>
+      {captionText && (
+        <Text
+          component="figcaption"
+          className="image-caption"
+        >
+          {captionText}
+        </Text>
+      )}
+      </figure>
     </NodeViewWrapper>
   );
 }

apps/client/src/features/editor/components/spoiler/spoiler-view.tsx

@@ -0,0 +1,20 @@
+import { MarkViewContent, MarkViewProps } from "@tiptap/react";
+import { useState } from "react";
+
+// Click-to-reveal spoiler. The revealed state is UI-only and is never written to
+// the document: toggling only adds/removes the `is-revealed` class (CSS removes
+// the blur). renderHTML never emits `is-revealed`, so it can't leak into the
+// doc/clipboard. Works the same in editor, read-only and public-share views.
+export default function SpoilerView(_props: MarkViewProps) {
+  const [revealed, setRevealed] = useState(false);
+
+  return (
+    <span
+      className={revealed ? "spoiler is-revealed" : "spoiler"}
+      data-spoiler="true"
+      onClick={() => setRevealed((v) => !v)}
+    >
+      <MarkViewContent />
+    </span>
+  );
+}

apps/client/src/features/editor/extensions/extensions.ts

@@ -53,6 +53,7 @@ import {
   Subpages,
   Heading,
   Highlight,
+  Spoiler,
   Indent,
   UniqueID,
   SharedStorage,
@@ -116,6 +117,7 @@ import mentionRenderItems from "@/features/editor/components/mention/mention-sug
 import { ReactNodeViewRenderer, ReactMarkViewRenderer } from "@tiptap/react";
 import MentionView from "@/features/editor/components/mention/mention-view.tsx";
 import LinkView from "@/features/editor/components/link/link-view.tsx";
+import SpoilerView from "@/features/editor/components/spoiler/spoiler-view.tsx";
 import i18n from "@/i18n.ts";
 import { MarkdownClipboard } from "@/features/editor/extensions/markdown-clipboard.ts";
 import EmojiCommand from "./emoji-command";
@@ -123,6 +125,7 @@ import { countWords } from "alfaaz";
 import AutoJoiner from "@/features/editor/extensions/autojoiner.ts";
 import GlobalDragHandle from "@/features/editor/extensions/drag-handle.ts";
 import { CleanStyles } from "@/features/editor/extensions/clean-styles.ts";
+import { IntentionalClear } from "@/features/editor/extensions/intentional-clear.ts";
 
 const lowlight = createLowlight(common);
 lowlight.register("mermaid", plaintext);
@@ -237,6 +240,11 @@ export const mainExtensions = [
   Highlight.configure({
     multicolor: true,
   }),
+  Spoiler.configure({}).extend({
+    addMarkView() {
+      return ReactMarkViewRenderer(SpoilerView);
+    },
+  }),
   Typography,
   TrailingNode,
   GlobalDragHandle.configure({
@@ -486,4 +494,10 @@ export const collabExtensions: CollabExtensions = (provider, user) => [
       color: randomElement(userColors),
     },
   }),
+  // #251 — emit an intentional-clear signal to the server when the user
+  // deliberately empties the page, so the #248 store-side empty-guard lets that
+  // one clear through while still blocking accidental empties.
+  IntentionalClear.configure({
+    provider,
+  }),
 ];

apps/client/src/features/editor/extensions/intentional-clear.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, beforeEach } 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 { ySyncPluginKey } from "@tiptap/y-tiptap";
+import {
+  IntentionalClear,
+  INTENTIONAL_CLEAR_MESSAGE_TYPE,
+} from "./intentional-clear";
+
+/**
+ * #251 — the intentional-clear signal is driven through the REAL editor path:
+ * a fresh Editor with the IntentionalClear extension, a fake provider that
+ * records sendStateless, and the actual select-all + delete command the user's
+ * keystroke runs. No hand-poke of any flag.
+ */
+describe("IntentionalClear extension", () => {
+  let sendStateless: ReturnType<typeof vi.fn>;
+
+  const makeEditor = (content: unknown) =>
+    new Editor({
+      extensions: [
+        Document,
+        Paragraph,
+        Text,
+        IntentionalClear.configure({
+          // Minimal provider stand-in: only sendStateless is exercised.
+          provider: { sendStateless } as any,
+        }),
+      ],
+      content: content as any,
+    });
+
+  beforeEach(() => {
+    sendStateless = vi.fn();
+  });
+
+  it("emits the clear signal when a user empties a non-empty doc (select-all + delete)", () => {
+    const editor = makeEditor({
+      type: "doc",
+      content: [
+        { type: "paragraph", content: [{ type: "text", text: "hello world" }] },
+      ],
+    });
+
+    // The exact command path a select-all + Delete keystroke dispatches.
+    editor.chain().selectAll().deleteSelection().run();
+
+    expect(sendStateless).toHaveBeenCalledTimes(1);
+    const payload = JSON.parse(sendStateless.mock.calls[0][0]);
+    expect(payload).toEqual({ type: INTENTIONAL_CLEAR_MESSAGE_TYPE });
+
+    editor.destroy();
+  });
+
+  it("does NOT emit when typing into an empty doc (no non-empty → empty transition)", () => {
+    const editor = makeEditor({ type: "doc", content: [{ type: "paragraph" }] });
+
+    editor.chain().insertContent("typed text").run();
+
+    expect(sendStateless).not.toHaveBeenCalled();
+    editor.destroy();
+  });
+
+  it("does NOT emit on an edit that leaves the doc non-empty", () => {
+    const editor = makeEditor({
+      type: "doc",
+      content: [
+        { type: "paragraph", content: [{ type: "text", text: "keep me" }] },
+      ],
+    });
+
+    editor.chain().insertContent(" more").run();
+
+    expect(sendStateless).not.toHaveBeenCalled();
+    editor.destroy();
+  });
+
+  it("does NOT emit when a REMOTE/merge (change-origin) transaction empties the doc", () => {
+    // This pins the CENTRAL #248 protection: only a LOCAL user edit may emit the
+    // intentional-clear signal. An emptiness arriving from another client, a bad
+    // merge, or an emptied transclusion is applied as a y-sync transaction tagged
+    // with the ySyncPluginKey meta, which `isChangeOrigin` detects. The extension
+    // must early-return on it and NOT punch the empty write through the server
+    // guard.
+    const editor = makeEditor({
+      type: "doc",
+      content: [
+        { type: "paragraph", content: [{ type: "text", text: "remote content" }] },
+      ],
+    });
+
+    // Build a transaction that empties the non-empty doc and tag it exactly the
+    // way y-tiptap tags a remote y-sync update: `tr.setMeta(ySyncPluginKey,
+    // { isChangeOrigin: true })` (see @tiptap/y-tiptap sync-plugin). This makes
+    // the real `isChangeOrigin(tr)` predicate return true — not a stand-in.
+    const { state } = editor;
+    const tr = state.tr
+      .delete(0, state.doc.content.size)
+      .setMeta(ySyncPluginKey, { isChangeOrigin: true });
+    editor.view.dispatch(tr);
+
+    // The transaction really emptied the doc (became the single empty paragraph)…
+    expect(editor.state.doc.textContent).toBe("");
+    // …yet because it is change-origin, no signal is emitted.
+    expect(sendStateless).not.toHaveBeenCalled();
+    editor.destroy();
+  });
+
+  it("does NOT emit when the doc was already empty", () => {
+    const editor = makeEditor({ type: "doc", content: [{ type: "paragraph" }] });
+
+    // Selecting all + delete on an already-empty doc is a no-op transition.
+    editor.chain().selectAll().deleteSelection().run();
+
+    expect(sendStateless).not.toHaveBeenCalled();
+    editor.destroy();
+  });
+});

apps/client/src/features/editor/extensions/intentional-clear.ts

@@ -0,0 +1,94 @@
+import { Extension } from "@tiptap/core";
+import { isChangeOrigin } from "@tiptap/extension-collaboration";
+import type { Node as PMNode } from "@tiptap/pm/model";
+import type { HocuspocusProvider } from "@hocuspocus/provider";
+
+/**
+ * Stateless message type sent to the server when a user deliberately clears a
+ * page to empty. Kept in one place so the client emitter and the server
+ * consumer (PersistenceExtension.onStateless) agree on the wire format.
+ */
+export const INTENTIONAL_CLEAR_MESSAGE_TYPE = "intentional-clear";
+
+export interface IntentionalClearOptions {
+  /** The collab provider used to send the stateless clear signal. */
+  provider: HocuspocusProvider | null;
+}
+
+/**
+ * A "document is empty" check that mirrors the server's `isEmptyParagraphDoc`
+ * (collaboration.util.ts): exactly one top-level paragraph with no inline
+ * content. After a select-all + delete TipTap leaves precisely this shape, so
+ * matching it here keeps the client signal aligned with the server guard that
+ * consumes it.
+ */
+function isEmptyParagraphDoc(doc: PMNode): boolean {
+  if (doc.childCount !== 1) return false;
+  const child = doc.firstChild;
+  return (
+    child !== null &&
+    child !== undefined &&
+    child.type.name === "paragraph" &&
+    child.content.size === 0
+  );
+}
+
+/**
+ * #251 — intentional-clear signal.
+ *
+ * The server's #248 store-side empty-guard unconditionally refuses to overwrite
+ * non-empty persisted content with an empty document, because a momentarily
+ * empty live Y.Doc (a glitch, a bad merge, an emptying transclusion) is
+ * indistinguishable from a real clear *at the store layer*. That protection is
+ * correct, but it also blocks a user who genuinely wants to empty the page.
+ *
+ * This extension supplies the missing distinction. It watches LOCAL, user-driven
+ * transactions and, the moment one reduces a non-empty document to the empty
+ * single-paragraph shape, it sends a hocuspocus stateless message to the server.
+ * The server records a short-lived, single-use "intentional clear pending" flag
+ * for this document that the next (debounced) onStoreDocument consumes to let
+ * that one empty write through the guard.
+ *
+ * What counts as an intentional clear (precise definition):
+ *  - the transaction actually changed the document (`docChanged`), AND
+ *  - it is a LOCAL user edit, not a remote collab application — remote y-sync
+ *    transactions are tagged and filtered out via `isChangeOrigin`, so an
+ *    emptiness that arrives from another client / a merge never emits a signal,
+ *    AND
+ *  - the document was non-empty before the transaction and is the empty
+ *    single-paragraph doc after it.
+ *
+ * This is exactly the select-all + Delete / Backspace (or any local command that
+ * empties the doc, e.g. clearContent) keystroke path. A transient/programmatic
+ * empty serialization that the server might see on the wire does NOT come with
+ * this signal, so the guard still blocks it.
+ */
+export const IntentionalClear = Extension.create<IntentionalClearOptions>({
+  name: "intentionalClear",
+
+  addOptions() {
+    return {
+      provider: null,
+    };
+  },
+
+  onTransaction({ transaction }) {
+    if (!transaction.docChanged) return;
+    // Only react to local user edits. Remote collaboration steps (and other
+    // y-sync-applied changes) carry the change origin and must never be treated
+    // as an intentional clear, otherwise a remote/merge-induced emptiness would
+    // punch through the server guard.
+    if (isChangeOrigin(transaction)) return;
+
+    const becameEmpty =
+      !isEmptyParagraphDoc(transaction.before) &&
+      isEmptyParagraphDoc(transaction.doc);
+    if (!becameEmpty) return;
+
+    // The server reads the originating document from the connection, so the
+    // payload only needs to declare intent — it cannot target another document.
+    this.options.provider?.sendStateless(
+      JSON.stringify({ type: INTENTIONAL_CLEAR_MESSAGE_TYPE }),
+    );
+  },
+});

apps/client/src/features/editor/styles/index.css

@@ -14,6 +14,7 @@
 @import "./mention.css";
 @import "./ordered-list.css";
 @import "./highlight.css";
+@import "./spoiler.css";
 @import "./indent.css";
 @import "./columns.css";
 @import "./status.css";

apps/client/src/features/editor/styles/media.css

@@ -33,6 +33,15 @@
     }
   }
 
+  .image-caption {
+    text-align: center;
+    font-size: 0.875em;
+    color: var(--mantine-color-dimmed);
+    margin-top: 0.4em;
+    line-height: 1.35;
+    word-break: break-word;
+  }
+
   .uploading-text {
     font-size: var(--mantine-font-size-md);
     line-height: var(--mantine-line-height-md);

apps/client/src/features/editor/styles/spoiler.css

@@ -0,0 +1,21 @@
+.spoiler {
+  background: rgba(0, 0, 0, 0.85);
+  border-radius: 0.25em;
+  cursor: pointer;
+  filter: blur(0.3em);
+  transition: filter 0.15s ease;
+  user-select: none;
+}
+
+.spoiler.is-revealed {
+  filter: none;
+  background: rgba(125, 125, 125, 0.18);
+  user-select: auto;
+}
+
+@media print {
+  .spoiler {
+    filter: none;
+    background: rgba(125, 125, 125, 0.18);
+  }
+}

apps/client/src/features/notification/notification.utils.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import i18n from "@/i18n.ts";
 import {
+  formatRelativeTime,
   getTimeGroup,
   groupNotificationsByTime,
 } from "@/features/notification/notification.utils.ts";
@@ -132,3 +134,59 @@ describe("groupNotificationsByTime", () => {
     expect(groupNotificationsByTime([], labels)).toEqual([]);
   });
 });
+
+describe("formatRelativeTime — relative buckets and absolute-date fallback", () => {
+  // Distinct fixed clock for the relative formatter (uses Date.now via `new
+  // Date()`), so the bucket boundaries are deterministic under fake timers.
+  const NOW = new Date("2026-06-15T12:00:00.000Z");
+  const MIN = 60_000;
+
+  beforeEach(() => {
+    vi.setSystemTime(NOW);
+  });
+
+  // ISO string `ms` milliseconds before NOW.
+  function ago(ms: number): string {
+    return new Date(NOW.getTime() - ms).toISOString();
+  }
+
+  it("returns the i18n 'now' label for anything under a minute", () => {
+    expect(formatRelativeTime(ago(0))).toBe(i18n.t("now"));
+    expect(formatRelativeTime(ago(59_000))).toBe(i18n.t("now"));
+  });
+
+  it("crosses into the minutes bucket exactly at 1 minute", () => {
+    expect(formatRelativeTime(ago(MIN - 1000))).toBe(i18n.t("now"));
+    expect(formatRelativeTime(ago(MIN))).toBe("1m");
+    expect(formatRelativeTime(ago(5 * MIN))).toBe("5m");
+    expect(formatRelativeTime(ago(59 * MIN))).toBe("59m");
+  });
+
+  it("crosses into the hours bucket exactly at 60 minutes", () => {
+    expect(formatRelativeTime(ago(60 * MIN - 1000))).toBe("59m");
+    expect(formatRelativeTime(ago(HOUR))).toBe("1h");
+    expect(formatRelativeTime(ago(23 * HOUR))).toBe("23h");
+  });
+
+  it("crosses into the days bucket exactly at 24 hours", () => {
+    expect(formatRelativeTime(ago(24 * HOUR - 1000))).toBe("23h");
+    expect(formatRelativeTime(ago(DAY))).toBe("1d");
+    expect(formatRelativeTime(ago(6 * DAY))).toBe("6d");
+  });
+
+  it("falls back to an absolute short date once >= 7 days old", () => {
+    // 6d -> still relative; 7d -> absolute date (no longer N[mhd], and equal to
+    // the localized short-date of the source timestamp).
+    expect(formatRelativeTime(ago(6 * DAY))).toBe("6d");
+
+    const sevenDaysAgo = ago(7 * DAY);
+    const result = formatRelativeTime(sevenDaysAgo);
+    expect(result).not.toMatch(/^\d+[mhd]$/);
+    expect(result).not.toBe(i18n.t("now"));
+    const expected = new Intl.DateTimeFormat(i18n.language, {
+      month: "short",
+      day: "numeric",
+    }).format(new Date(sevenDaysAgo));
+    expect(result).toBe(expected);
+  });
+});

apps/client/src/features/page-history/components/history-item.test.tsx

@@ -0,0 +1,227 @@
+import { describe, it, expect, vi, afterEach, beforeAll } from "vitest";
+import { render, screen, cleanup, within } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+
+// Mantine Tooltip mounts its label lazily on hover via Floating UI, which is
+// flaky under jsdom. Replace ONLY the Tooltip with a thin wrapper that renders
+// the label inline (keeping Badge/Switch/etc. real), so the provenance label —
+// the contract we care about — is deterministically queryable.
+vi.mock("@mantine/core", async () => {
+  const actual =
+    await vi.importActual<typeof import("@mantine/core")>("@mantine/core");
+  const Tooltip = ({
+    label,
+    children,
+  }: {
+    label?: React.ReactNode;
+    children?: React.ReactNode;
+  }) => (
+    <>
+      {children}
+      <span data-testid="tooltip-label">{label}</span>
+    </>
+  );
+  Tooltip.Group = ({ children }: { children?: React.ReactNode }) => (
+    <>{children}</>
+  );
+  return { ...actual, Tooltip };
+});
+
+// jsdom lacks matchMedia, which MantineProvider's color-scheme hook needs.
+beforeAll(() => {
+  if (!window.matchMedia) {
+    window.matchMedia = (query: string) =>
+      ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addListener: () => {},
+        removeListener: () => {},
+        addEventListener: () => {},
+        removeEventListener: () => {},
+        dispatchEvent: () => false,
+      }) as unknown as MediaQueryList;
+  }
+});
+
+// --- Mocks for the heavy / networked module graph ---------------------------
+// HistoryItem pulls in i18n, jotai atoms (ai-chat / history), a config-backed
+// avatar and a time formatter. The provenance-badge contract is the unit under
+// test, so we stub everything else down to inert, deterministic renders and
+// keep the real Mantine Badge/Tooltip so role/label queries are meaningful.
+
+// i18n: interpolate {{name}} so the git-sync tooltip carries the author name,
+// letting us assert provenance attribution without a real i18n backend.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, vars?: Record<string, unknown>) =>
+      vars && typeof vars.name !== "undefined"
+        ? key.replace("{{name}}", String(vars.name))
+        : key,
+  }),
+}));
+
+// jotai setters: the badges call useSetAtom; return inert setters so a click on
+// the (deep-linkable) AiAgentBadge would fire these — proving the git-sync badge
+// does NOT wire any of them.
+const setAiChatWindowOpen = vi.fn();
+const setActiveChatId = vi.fn();
+const setDraft = vi.fn();
+const setHistoryModalOpen = vi.fn();
+vi.mock("jotai", async () => {
+  const actual = await vi.importActual<typeof import("jotai")>("jotai");
+  return {
+    ...actual,
+    useSetAtom: (atom: unknown) => {
+      switch (atom) {
+        case aiChatWindowOpenAtom:
+          return setAiChatWindowOpen;
+        case activeAiChatIdAtom:
+          return setActiveChatId;
+        case aiChatDraftAtom:
+          return setDraft;
+        case historyAtoms:
+          return setHistoryModalOpen;
+        default:
+          return vi.fn();
+      }
+    },
+  };
+});
+
+// Atoms are imported only as identity tokens for the useSetAtom switch above.
+vi.mock("@/features/ai-chat/atoms/ai-chat-atom.ts", () => ({
+  activeAiChatIdAtom: { __tag: "activeAiChatIdAtom" },
+  aiChatWindowOpenAtom: { __tag: "aiChatWindowOpenAtom" },
+  aiChatDraftAtom: { __tag: "aiChatDraftAtom" },
+}));
+vi.mock("@/features/page-history/atoms/history-atoms.ts", () => ({
+  historyAtoms: { __tag: "historyAtoms" },
+}));
+
+// Avatar reaches into config (getAvatarUrl) — stub to a plain element.
+vi.mock("@/components/ui/custom-avatar.tsx", () => ({
+  CustomAvatar: ({ name }: { name?: string }) => (
+    <span data-testid="avatar">{name}</span>
+  ),
+}));
+
+// Deterministic, locale-free date string.
+vi.mock("@/lib/time", () => ({
+  formattedDate: () => "2026-06-21",
+}));
+
+import HistoryItem from "./history-item";
+import {
+  activeAiChatIdAtom,
+  aiChatWindowOpenAtom,
+  aiChatDraftAtom,
+} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
+import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
+import type { IPageHistory } from "@/features/page-history/types/page.types";
+
+function makeItem(overrides: Partial<IPageHistory> = {}): IPageHistory {
+  return {
+    id: "h1",
+    pageId: "p1",
+    title: "Title",
+    slug: "slug",
+    icon: "",
+    coverPhoto: "",
+    version: 1,
+    lastUpdatedById: "u1",
+    workspaceId: "w1",
+    createdAt: "2026-06-21T00:00:00.000Z",
+    updatedAt: "2026-06-21T00:00:00.000Z",
+    lastUpdatedBy: { id: "u1", name: "Alice", avatarUrl: "" },
+    ...overrides,
+  };
+}
+
+function renderItem(item: IPageHistory) {
+  return render(
+    <MantineProvider>
+      <HistoryItem
+        historyItem={item}
+        index={0}
+        onSelect={vi.fn()}
+        isActive={false}
+      />
+    </MantineProvider>,
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+describe("HistoryItem git-sync provenance badge", () => {
+  // Test 1: the git-sync badge renders ONLY for lastUpdatedSource === 'git-sync'.
+  it("renders the Git sync badge only when lastUpdatedSource is 'git-sync'", () => {
+    renderItem(makeItem({ lastUpdatedSource: "git-sync" }));
+    expect(screen.getByText("Git sync")).toBeTruthy();
+  });
+
+  it.each([
+    ["agent", "agent"],
+    ["user", "user"],
+    ["undefined", undefined],
+  ])(
+    "does NOT render the Git sync badge when lastUpdatedSource is %s",
+    (_label, source) => {
+      renderItem(makeItem({ lastUpdatedSource: source }));
+      expect(screen.queryByText("Git sync")).toBeNull();
+    },
+  );
+
+  // Test 2: provenance attribution + the git-sync badge is NOT interactive.
+  it("attributes the git-sync provenance to the correct author and is not clickable", () => {
+    renderItem(
+      makeItem({
+        lastUpdatedSource: "git-sync",
+        lastUpdatedBy: { id: "u2", name: "Bob", avatarUrl: "" },
+      }),
+    );
+
+    const badge = screen.getByText("Git sync");
+
+    // Provenance attribution: the tooltip label carries the author name (the
+    // git-sync badge passes authorName -> "Synced from Git on behalf of {{name}}").
+    expect(screen.getByText("Synced from Git on behalf of Bob")).toBeTruthy();
+
+    // The git-sync badge must NOT behave like AiAgentBadge: the badge element
+    // itself is not a button, carries no role=button and no tabIndex, and
+    // clicking it must not trigger any ai-chat deep-link. (The surrounding
+    // history-row IS an UnstyledButton — that is the row's own select affordance,
+    // not the badge — so we scope these checks to the badge element.)
+    const badgeRoot = (badge.closest("[class*='mantine-Badge-root']") ??
+      badge) as HTMLElement;
+    expect(badgeRoot.getAttribute("role")).not.toBe("button");
+    expect(badgeRoot.getAttribute("tabindex")).toBeNull();
+    expect(badgeRoot.tagName.toLowerCase()).not.toBe("button");
+    // No interactive descendant button lives inside the badge itself.
+    expect(within(badgeRoot).queryByRole("button")).toBeNull();
+
+    badgeRoot.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    expect(setActiveChatId).not.toHaveBeenCalled();
+    expect(setAiChatWindowOpen).not.toHaveBeenCalled();
+    expect(setDraft).not.toHaveBeenCalled();
+    expect(setHistoryModalOpen).not.toHaveBeenCalled();
+  });
+
+  // Sanity contrast: the agent badge (the copy-paste source) IS interactive when
+  // it carries an aiChatId — proving the not-clickable assertion above is real.
+  it("contrast: the AI-agent badge is a deep-link button when it has an aiChatId", () => {
+    renderItem(
+      makeItem({
+        lastUpdatedSource: "agent",
+        lastUpdatedAiChatId: "chat-1",
+      }),
+    );
+    const agentBadge = screen.getByText("AI-agent");
+    const root = agentBadge.closest("[role='button']");
+    expect(root).not.toBeNull();
+    within(root as HTMLElement).getByText("AI-agent");
+  });
+});

apps/client/src/features/page-history/components/history-item.tsx

@@ -1,6 +1,7 @@
 import { Text, Group, UnstyledButton, Avatar, Tooltip } from "@mantine/core";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
 import { AiAgentBadge } from "@/components/ui/ai-agent-badge.tsx";
+import { GitSyncBadge } from "@/components/ui/git-sync-badge.tsx";
 import { formattedDate } from "@/lib/time";
 import classes from "./css/history.module.css";
 import clsx from "clsx";
@@ -41,6 +42,7 @@ const HistoryItem = memo(function HistoryItem({
   const contributors = historyItem.contributors;
   const hasContributors = contributors && contributors.length > 0;
   const isAgentEdit = historyItem.lastUpdatedSource === "agent";
+  const isGitSyncEdit = historyItem.lastUpdatedSource === "git-sync";
 
   return (
     <UnstyledButton
@@ -108,6 +110,10 @@ const HistoryItem = memo(function HistoryItem({
             onActivate={() => setHistoryModalOpen(false)}
           />
         )}
+
+        {isGitSyncEdit && (
+          <GitSyncBadge authorName={historyItem.lastUpdatedBy?.name} />
+        )}
       </Group>
     </UnstyledButton>
   );

apps/client/src/features/page/tree/utils/find-breadcrumb-path.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from "vitest";
+import { findBreadcrumbPath } from "./utils";
+import type { SpaceTreeNode } from "@/features/page/tree/types.ts";
+
+// findBreadcrumbPath walks the live, SHARED sidebar tree. The high-value
+// invariant: when a node has no usable name it must surface "Untitled" ONLY on
+// the returned breadcrumb chain via a shallow copy — never by mutating the input
+// node (which would silently rename the node in the sidebar). Also covers normal
+// ancestor-chain resolution, the not-found case, and nested children.
+
+function node(id: string, over: Partial<SpaceTreeNode> = {}): SpaceTreeNode {
+  return {
+    id,
+    slugId: `slug-${id}`,
+    name: id.toUpperCase(),
+    icon: undefined,
+    position: "a0",
+    spaceId: "space-1",
+    parentPageId: null as unknown as string,
+    hasChildren: false,
+    children: [],
+    ...over,
+  };
+}
+
+describe("findBreadcrumbPath", () => {
+  it("does NOT mutate the input tree when a node has an empty/whitespace name", () => {
+    // A whitespace-only-named node nested under a blank-named root.
+    const target = node("target", { name: "   " });
+    const root = node("root", { name: "", hasChildren: true, children: [target] });
+    const tree = [root];
+
+    const result = findBreadcrumbPath(tree, "target");
+
+    expect(result).not.toBeNull();
+    // The RETURNED chain shows "Untitled" for both blank nodes.
+    expect(result!.map((n) => n.name)).toEqual(["Untitled", "Untitled"]);
+    // The original input nodes are untouched (still blank).
+    expect(root.name).toBe("");
+    expect(target.name).toBe("   ");
+    // The renamed breadcrumb entries are fresh copies, not the input objects.
+    expect(result![0]).not.toBe(root);
+    expect(result![1]).not.toBe(target);
+  });
+
+  it("returns the SAME node reference (no copy) when the name is non-empty", () => {
+    // No rename needed -> the node is passed through by reference (cheap path).
+    const target = node("target", { name: "Real Title" });
+    const result = findBreadcrumbPath([target], "target");
+    expect(result![0]).toBe(target);
+    expect(result![0].name).toBe("Real Title");
+  });
+
+  it("resolves the full ancestor chain ending at the target", () => {
+    const target = node("c");
+    const mid = node("b", { hasChildren: true, children: [target] });
+    const root = node("a", { hasChildren: true, children: [mid] });
+    const result = findBreadcrumbPath([root], "c");
+    expect(result!.map((n) => n.id)).toEqual(["a", "b", "c"]);
+  });
+
+  it("finds a target nested under a deeper sibling branch", () => {
+    // Two root branches; the target lives inside the second branch's child.
+    const target = node("deep");
+    const branch2 = node("r2", {
+      hasChildren: true,
+      children: [node("x"), node("y", { hasChildren: true, children: [target] })],
+    });
+    const branch1 = node("r1", { hasChildren: true, children: [node("z")] });
+    const result = findBreadcrumbPath([branch1, branch2], "deep");
+    expect(result!.map((n) => n.id)).toEqual(["r2", "y", "deep"]);
+  });
+
+  it("returns null when the page id is not present in the tree", () => {
+    const root = node("root", { hasChildren: true, children: [node("child")] });
+    expect(findBreadcrumbPath([root], "missing")).toBeNull();
+    expect(findBreadcrumbPath([], "anything")).toBeNull();
+  });
+});

apps/client/src/features/page/tree/utils/utils.test.ts

@@ -8,6 +8,8 @@ import {
   closeIds,
   mergeRootTrees,
   loadedOpenBranchIds,
+  sortPositionKeys,
+  pageToTreeNode,
 } from "./utils";
 import type { IPage } from "@/features/page/types/page.types.ts";
 import type { SpaceTreeNode } from "@/features/page/tree/types.ts";
@@ -60,6 +62,82 @@ function treeNode(id: string, children: SpaceTreeNode[] = []): SpaceTreeNode {
   };
 }
 
+describe("sortPositionKeys", () => {
+  it("orders items ascending by their fractional `position` string", () => {
+    const items = [
+      { id: "c", position: "a5" },
+      { id: "a", position: "a1" },
+      { id: "b", position: "a3" },
+    ];
+    expect(sortPositionKeys(items).map((i) => i.id)).toEqual(["a", "b", "c"]);
+  });
+
+  it("is a stable sort: equal positions keep their input order", () => {
+    const items = [
+      { id: "x", position: "a1" },
+      { id: "y", position: "a1" },
+      { id: "z", position: "a1" },
+    ];
+    expect(sortPositionKeys(items).map((i) => i.id)).toEqual(["x", "y", "z"]);
+  });
+});
+
+describe("pageToTreeNode", () => {
+  function pageRow(over: Partial<IPage> = {}): IPage {
+    return {
+      id: "p1",
+      slugId: "slug-p1",
+      title: "My Page",
+      icon: "📄",
+      position: "a1",
+      hasChildren: true,
+      spaceId: "space-1",
+      parentPageId: null as unknown as string,
+      ...over,
+    } as IPage;
+  }
+
+  it("maps page.title -> node.name and copies the core fields", () => {
+    const node = pageToTreeNode(pageRow());
+    // The non-trivial transform: a page's `title` becomes the tree node's `name`.
+    expect(node.name).toBe("My Page");
+    expect(node.id).toBe("p1");
+    expect(node.slugId).toBe("slug-p1");
+    expect(node.icon).toBe("📄");
+    expect(node.position).toBe("a1");
+    expect(node.spaceId).toBe("space-1");
+    expect(node.hasChildren).toBe(true);
+    // Always materialized with an empty children array.
+    expect(node.children).toEqual([]);
+  });
+
+  it("derives canEdit from page.permissions.canEdit when the flat field is absent", () => {
+    const node = pageToTreeNode(
+      pageRow({ canEdit: undefined, permissions: { canEdit: true } } as Partial<IPage>),
+    );
+    expect(node.canEdit).toBe(true);
+  });
+
+  it("prefers the flat page.canEdit over permissions.canEdit", () => {
+    const node = pageToTreeNode(
+      pageRow({ canEdit: false, permissions: { canEdit: true } } as Partial<IPage>),
+    );
+    expect(node.canEdit).toBe(false);
+  });
+
+  it("carries temporaryExpiresAt straight off the page", () => {
+    const expiresAt = "2026-06-27T21:00:00.000Z";
+    expect(pageToTreeNode(pageRow({ temporaryExpiresAt: expiresAt })).temporaryExpiresAt).toBe(
+      expiresAt,
+    );
+  });
+
+  it("applies overrides on top of the mapped fields (e.g. optimistic blank name)", () => {
+    const node = pageToTreeNode(pageRow(), { name: "" });
+    expect(node.name).toBe("");
+  });
+});
+
 describe("buildTree", () => {
   it("builds one node per unique page", () => {
     const tree = buildTree([page("a", "a1"), page("b", "a2")]);

apps/client/src/features/page/tree/utils/utils.ts

@@ -70,18 +70,22 @@ export function findBreadcrumbPath(
   path: SpaceTreeNode[] = [],
 ): SpaceTreeNode[] | null {
   for (const node of tree) {
-    if (!node.name || node.name.trim() === "") {
-      node.name = "Untitled";
-    }
+    // Never mutate the input tree (it is the live, shared sidebar tree state).
+    // When a node has no usable name, surface "Untitled" via a shallow copy that
+    // only the returned breadcrumb chain sees — the source node stays untouched.
+    const displayNode: SpaceTreeNode =
+      !node.name || node.name.trim() === ""
+        ? { ...node, name: "Untitled" }
+        : node;
 
     if (node.id === pageId) {
-      return [...path, node];
+      return [...path, displayNode];
     }
 
     if (node.children) {
       const newPath = findBreadcrumbPath(node.children, pageId, [
         ...path,
-        node,
+        displayNode,
       ]);
       if (newPath) {
         return newPath;

apps/client/src/features/space/components/edit-space-form.test.tsx

@@ -0,0 +1,240 @@
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeAll,
+  afterEach,
+} from "vitest";
+import {
+  render,
+  screen,
+  cleanup,
+  fireEvent,
+  waitFor,
+} from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+
+// --- Mocks for the heavy / networked module graph ---------------------------
+// EditSpaceForm wires the "Enable Git sync" Switch to a TanStack-Query mutation
+// (useUpdateSpaceMutation). We mock ONLY that hook so the test fully controls
+// mutateAsync (resolve / reject) and isPending, and stub i18n. The real Mantine
+// Switch is rendered so the checkbox role / disabled state is meaningful.
+
+// i18n: identity translator — labels stay as their English keys for queries.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+// Mutation hook: a controllable mutateAsync plus a togglable isPending.
+const mutateAsync = vi.fn();
+let isPending = false;
+vi.mock("@/features/space/queries/space-query.ts", () => ({
+  useUpdateSpaceMutation: () => ({
+    mutateAsync,
+    get isPending() {
+      return isPending;
+    },
+  }),
+}));
+
+// jsdom lacks matchMedia, which MantineProvider's color-scheme hook needs.
+beforeAll(() => {
+  if (!window.matchMedia) {
+    window.matchMedia = (query: string) =>
+      ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addListener: () => {},
+        removeListener: () => {},
+        addEventListener: () => {},
+        removeEventListener: () => {},
+        dispatchEvent: () => false,
+      }) as unknown as MediaQueryList;
+  }
+});
+
+import { EditSpaceForm } from "./edit-space-form";
+import type { ISpace } from "@/features/space/types/space.types.ts";
+
+function makeSpace(overrides: Partial<ISpace> = {}): ISpace {
+  return {
+    id: "space-1",
+    name: "Engineering",
+    description: "",
+    slug: "eng",
+    hostname: "host",
+    creatorId: "u1",
+    createdAt: new Date("2026-01-01"),
+    updatedAt: new Date("2026-01-01"),
+    ...overrides,
+  } as ISpace;
+}
+
+function renderForm(props: { space: ISpace; readOnly?: boolean }) {
+  return render(
+    <MantineProvider>
+      <EditSpaceForm space={props.space} readOnly={props.readOnly} />
+    </MantineProvider>,
+  );
+}
+
+// The form now renders TWO switches (git-sync enable + auto-merge-conflicts) in
+// that DOM order. Mantine renders each as an <input type="checkbox"
+// role="switch"> but does NOT expose its label as the accessible name, so we
+// disambiguate by DOM order (index 0 = enable, 1 = auto-merge) and assert the
+// human-readable label text is present alongside.
+function getToggle(): HTMLInputElement {
+  screen.getByText("Enable Git sync");
+  return screen.getAllByRole("switch")[0] as HTMLInputElement;
+}
+
+function getAutoMergeToggle(): HTMLInputElement {
+  screen.getByText("Auto-merge conflicts on push");
+  return screen.getAllByRole("switch")[1] as HTMLInputElement;
+}
+
+afterEach(() => {
+  cleanup();
+  mutateAsync.mockReset();
+  isPending = false;
+});
+
+describe("EditSpaceForm git-sync toggle", () => {
+  // Test 3: initial checked state derives from settings.gitSync.enabled ?? false.
+  it("derives initial checked state from space.settings.gitSync.enabled (true -> checked)", () => {
+    renderForm({
+      space: makeSpace({ settings: { gitSync: { enabled: true } } }),
+    });
+    expect(getToggle().checked).toBe(true);
+  });
+
+  it("defaults to unchecked when gitSync settings are missing", () => {
+    renderForm({ space: makeSpace() });
+    expect(getToggle().checked).toBe(false);
+  });
+
+  // Test 4: toggling fires the mutation with { spaceId, gitSyncEnabled } and
+  // optimistically flips the switch.
+  it("fires the mutation with the correct payload and optimistically flips on", async () => {
+    mutateAsync.mockResolvedValue(undefined);
+    renderForm({ space: makeSpace() });
+
+    const toggle = getToggle();
+    expect(toggle.checked).toBe(false);
+
+    fireEvent.click(toggle);
+
+    // Optimistic update: the switch reflects the new state immediately.
+    expect(toggle.checked).toBe(true);
+
+    expect(mutateAsync).toHaveBeenCalledTimes(1);
+    expect(mutateAsync).toHaveBeenCalledWith({
+      spaceId: "space-1",
+      gitSyncEnabled: true,
+    });
+
+    // Resolution leaves the toggle on.
+    await waitFor(() => expect(toggle.checked).toBe(true));
+  });
+
+  // Test 5: rollback on mutation error — the most valuable test.
+  it("rolls back the toggle to its prior state when the mutation rejects", async () => {
+    mutateAsync.mockRejectedValue(new Error("network"));
+    renderForm({
+      space: makeSpace({ settings: { gitSync: { enabled: false } } }),
+    });
+
+    const toggle = getToggle();
+    expect(toggle.checked).toBe(false);
+
+    fireEvent.click(toggle);
+
+    // Optimistically flips on before the rejection lands.
+    expect(toggle.checked).toBe(true);
+    expect(mutateAsync).toHaveBeenCalledWith({
+      spaceId: "space-1",
+      gitSyncEnabled: true,
+    });
+
+    // After the rejected promise settles, the component reverts to OFF so the
+    // user is not misled into believing sync is enabled.
+    await waitFor(() => expect(toggle.checked).toBe(false));
+  });
+
+  // Test 6: disabled when readOnly and when the mutation is pending.
+  it("disables the toggle when readOnly", () => {
+    renderForm({ space: makeSpace(), readOnly: true });
+    expect(getToggle().disabled).toBe(true);
+  });
+
+  it("disables the toggle while the mutation is pending", () => {
+    isPending = true;
+    renderForm({ space: makeSpace() });
+    expect(getToggle().disabled).toBe(true);
+  });
+});
+
+describe("EditSpaceForm auto-merge-conflicts toggle", () => {
+  it("derives initial checked state from space.settings.gitSync.autoMergeConflicts (true -> checked)", () => {
+    renderForm({
+      space: makeSpace({
+        settings: { gitSync: { autoMergeConflicts: true } },
+      }),
+    });
+    expect(getAutoMergeToggle().checked).toBe(true);
+  });
+
+  it("defaults to unchecked when autoMergeConflicts is missing (SAFE default)", () => {
+    renderForm({ space: makeSpace() });
+    expect(getAutoMergeToggle().checked).toBe(false);
+  });
+
+  it("fires the mutation with { spaceId, autoMergeConflicts } and optimistically flips on", async () => {
+    mutateAsync.mockResolvedValue(undefined);
+    renderForm({ space: makeSpace() });
+
+    const toggle = getAutoMergeToggle();
+    expect(toggle.checked).toBe(false);
+
+    fireEvent.click(toggle);
+
+    // Optimistic update.
+    expect(toggle.checked).toBe(true);
+    expect(mutateAsync).toHaveBeenCalledTimes(1);
+    expect(mutateAsync).toHaveBeenCalledWith({
+      spaceId: "space-1",
+      autoMergeConflicts: true,
+    });
+
+    await waitFor(() => expect(toggle.checked).toBe(true));
+  });
+
+  it("rolls back to its prior state when the mutation rejects", async () => {
+    mutateAsync.mockRejectedValue(new Error("network"));
+    renderForm({
+      space: makeSpace({
+        settings: { gitSync: { autoMergeConflicts: false } },
+      }),
+    });
+
+    const toggle = getAutoMergeToggle();
+    expect(toggle.checked).toBe(false);
+
+    fireEvent.click(toggle);
+
+    expect(toggle.checked).toBe(true);
+    expect(mutateAsync).toHaveBeenCalledWith({
+      spaceId: "space-1",
+      autoMergeConflicts: true,
+    });
+
+    await waitFor(() => expect(toggle.checked).toBe(false));
+  });
+
+  it("disables the toggle when readOnly", () => {
+    renderForm({ space: makeSpace(), readOnly: true });
+    expect(getAutoMergeToggle().disabled).toBe(true);
+  });
+});

apps/client/src/features/space/components/edit-space-form.tsx

@@ -1,5 +1,14 @@
-import { Group, Box, Button, TextInput, Stack, Textarea } from "@mantine/core";
-import React from "react";
+import {
+  Group,
+  Box,
+  Button,
+  TextInput,
+  Stack,
+  Textarea,
+  Divider,
+  Switch,
+} from "@mantine/core";
+import React, { useState } from "react";
 import { useForm } from "@mantine/form";
 import { zod4Resolver } from "mantine-form-zod-resolver";
 import { z } from "zod/v4";
@@ -29,6 +38,37 @@ export function EditSpaceForm({ space, readOnly }: EditSpaceFormProps) {
   const { t } = useTranslation();
   const updateSpaceMutation = useUpdateSpaceMutation();
 
+  const [gitSyncEnabled, setGitSyncEnabled] = useState<boolean>(
+    space?.settings?.gitSync?.enabled ?? false,
+  );
+
+  const [autoMergeConflicts, setAutoMergeConflicts] = useState<boolean>(
+    space?.settings?.gitSync?.autoMergeConflicts ?? false,
+  );
+
+  // One parameterized handler for both git-sync space toggles: they differ only by
+  // the local state setter, the mutation payload field, and the error label. The
+  // update is optimistic and reverts the local state on failure (the mutation
+  // surfaces a toast via onError; the raw error is still logged per AGENTS.md).
+  const handleToggle = async (
+    field: "gitSyncEnabled" | "autoMergeConflicts",
+    value: boolean,
+    previous: boolean,
+    setLocal: (next: boolean) => void,
+    errorLabel: string,
+  ) => {
+    setLocal(value); // optimistic update
+    try {
+      await updateSpaceMutation.mutateAsync({
+        spaceId: space.id,
+        [field]: value,
+      });
+    } catch (err) {
+      setLocal(previous); // revert on failure
+      console.error(errorLabel, err);
+    }
+  };
+
   const form = useForm<FormValues>({
     validate: zod4Resolver(formSchema),
     initialValues: {
@@ -104,6 +144,43 @@ export function EditSpaceForm({ space, readOnly }: EditSpaceFormProps) {
             </Group>
           )}
         </form>
+
+        <Divider my="lg" />
+
+        <Switch
+          label={t("Enable Git sync")}
+          description={t("Sync this space's pages to a Git repository.")}
+          checked={gitSyncEnabled}
+          disabled={readOnly || updateSpaceMutation.isPending}
+          onChange={(event) =>
+            handleToggle(
+              "gitSyncEnabled",
+              event.currentTarget.checked,
+              gitSyncEnabled,
+              setGitSyncEnabled,
+              "Failed to toggle git-sync for space",
+            )
+          }
+        />
+
+        <Switch
+          mt="md"
+          label={t("Auto-merge conflicts on push")}
+          description={t(
+            "When off (recommended), a page whose content still has unresolved Git conflict markers is skipped on push until you resolve the conflict in Git. When on, the markers are stripped and both sides' content is pushed.",
+          )}
+          checked={autoMergeConflicts}
+          disabled={readOnly || updateSpaceMutation.isPending}
+          onChange={(event) =>
+            handleToggle(
+              "autoMergeConflicts",
+              event.currentTarget.checked,
+              autoMergeConflicts,
+              setAutoMergeConflicts,
+              "Failed to toggle git-sync auto-merge-conflicts",
+            )
+          }
+        />
       </Box>
     </>
   );

apps/client/src/features/space/types/space.types.ts

@@ -13,9 +13,15 @@ export interface ISpaceCommentsSettings {
   allowViewerComments?: boolean;
 }
 
+export interface ISpaceGitSyncSettings {
+  enabled?: boolean;
+  autoMergeConflicts?: boolean;
+}
+
 export interface ISpaceSettings {
   sharing?: ISpaceSharingSettings;
   comments?: ISpaceCommentsSettings;
+  gitSync?: ISpaceGitSyncSettings;
 }
 
 export interface ISpace {
@@ -35,6 +41,8 @@ export interface ISpace {
   // for updates
   disablePublicSharing?: boolean;
   allowViewerComments?: boolean;
+  gitSyncEnabled?: boolean;
+  autoMergeConflicts?: boolean;
 }
 
 interface IMembership {

apps/client/src/features/websocket/tree-socket-reducers.test.ts

@@ -3,6 +3,7 @@ import {
   applyAddTreeNode,
   applyMoveTreeNode,
   applyDeleteTreeNode,
+  applyUpdateOne,
 } from "./tree-socket-reducers";
 import { treeModel } from "@/features/page/tree/model/tree-model";
 import { SpaceTreeNode } from "@/features/page/tree/types.ts";
@@ -338,3 +339,76 @@ describe("applyAddTreeNode", () => {
     expect(treeModel.find(next, "temp")?.temporaryExpiresAt).toBe(expiresAt);
   });
 });
+
+describe("applyUpdateOne", () => {
+  // A loaded two-level tree so we can patch both a root and a nested node.
+  const buildTree = (): SpaceTreeNode[] => [
+    node("root", {
+      position: "a0",
+      name: "Root",
+      icon: "📁",
+      hasChildren: true,
+      children: [node("child", { position: "a1", parentPageId: "root", name: "Child", icon: "📄" })],
+    }),
+  ];
+
+  // Build the UpdateEvent envelope; only `id`/`payload` matter to the reducer.
+  const ev = (id: string, payload: Record<string, unknown>) =>
+    ({
+      operation: "updateOne",
+      spaceId: "space-1",
+      entity: ["pages"],
+      id,
+      payload,
+    }) as unknown as Parameters<typeof applyUpdateOne>[1];
+
+  it("applies a title-only update to the node's name (icon untouched)", () => {
+    const tree = buildTree();
+    const next = applyUpdateOne(tree, ev("child", { title: "Renamed" }));
+    const child = treeModel.find(next, "child");
+    expect(child?.name).toBe("Renamed");
+    // Icon is left as it was.
+    expect(child?.icon).toBe("📄");
+  });
+
+  it("applies an icon-only update to the node's icon (name untouched)", () => {
+    const tree = buildTree();
+    const next = applyUpdateOne(tree, ev("root", { icon: "🔥" }));
+    const root = treeModel.find(next, "root");
+    expect(root?.icon).toBe("🔥");
+    expect(root?.name).toBe("Root");
+  });
+
+  it("applies a combined title + icon update", () => {
+    const tree = buildTree();
+    const next = applyUpdateOne(tree, ev("child", { title: "Both", icon: "⭐" }));
+    const child = treeModel.find(next, "child");
+    expect(child?.name).toBe("Both");
+    expect(child?.icon).toBe("⭐");
+  });
+
+  it("returns prev UNCHANGED (same reference) when the id is not loaded", () => {
+    const tree = buildTree();
+    const next = applyUpdateOne(tree, ev("ghost", { title: "Nope" }));
+    expect(next).toBe(tree);
+  });
+
+  it("returns prev UNCHANGED (same reference) for a no-op payload (no title/icon)", () => {
+    // The node exists, but the payload carries neither title nor icon -> nothing
+    // to patch, so the reducer must hand back the same array reference.
+    const tree = buildTree();
+    const next = applyUpdateOne(tree, ev("child", {}));
+    expect(next).toBe(tree);
+  });
+
+  it("treats an explicit null icon/title as a value to apply (undefined check, not truthiness)", () => {
+    // The reducer guards on `!== undefined`, so a clearing null IS applied.
+    const tree = buildTree();
+    const next = applyUpdateOne(tree, ev("child", { title: "", icon: null }));
+    const child = treeModel.find(next, "child");
+    expect(child?.name).toBe("");
+    expect(child?.icon).toBeNull();
+    // And it did change something -> a fresh reference, not prev.
+    expect(next).not.toBe(tree);
+  });
+});

apps/client/src/features/workspace/components/settings/components/ai-provider-settings.spec.tsx

@@ -3,6 +3,9 @@ import {
   resolveCardStatus,
   isEndpointConfigured,
   resolveKeyField,
+  nextReindexPollInterval,
+  isReindexComplete,
+  isReindexButtonLoading,
 } from './ai-provider-settings';
 
 describe('resolveCardStatus', () => {
@@ -71,3 +74,152 @@ describe('resolveKeyField (write-only key payload)', () => {
     expect(resolveKeyField('', false)).toEqual({ set: false });
   });
 });
+
+describe('nextReindexPollInterval', () => {
+  const INTERVAL = 5000;
+  const base = { now: 1_000, intervalMs: INTERVAL };
+
+  it('does not poll when no reindex deadline is set', () => {
+    expect(
+      nextReindexPollInterval({
+        ...base,
+        deadline: null,
+        status: { reindexing: true, indexedPages: 0, totalPages: 478 },
+      }),
+    ).toBe(false);
+  });
+
+  it('keeps polling while the server reports an active run', () => {
+    expect(
+      nextReindexPollInterval({
+        ...base,
+        deadline: 10_000,
+        status: { reindexing: true, indexedPages: 120, totalPages: 478 },
+      }),
+    ).toBe(INTERVAL);
+  });
+
+  it('keeps polling during an active run even if counts momentarily look full', () => {
+    // The run clears its progress record only at the very end, so a transient
+    // indexed==total while reindexing is still true must NOT stop polling.
+    expect(
+      nextReindexPollInterval({
+        ...base,
+        deadline: 10_000,
+        status: { reindexing: true, indexedPages: 478, totalPages: 478 },
+      }),
+    ).toBe(INTERVAL);
+  });
+
+  it('stops once the run is finished AND fully indexed', () => {
+    expect(
+      nextReindexPollInterval({
+        ...base,
+        deadline: 10_000,
+        status: { reindexing: false, indexedPages: 478, totalPages: 478 },
+      }),
+    ).toBe(false);
+  });
+
+  it('keeps polling within the deadline when not yet done and no active flag', () => {
+    // First poll right after enqueue, before the worker publishes progress.
+    expect(
+      nextReindexPollInterval({
+        ...base,
+        deadline: 10_000,
+        status: { reindexing: false, indexedPages: 0, totalPages: 478 },
+      }),
+    ).toBe(INTERVAL);
+  });
+
+  it('cap always wins: stops once past the deadline even if still reindexing', () => {
+    expect(
+      nextReindexPollInterval({
+        deadline: 1_000,
+        now: 2_000, // past the deadline
+        intervalMs: INTERVAL,
+        status: { reindexing: true, indexedPages: 200, totalPages: 478 },
+      }),
+    ).toBe(false);
+  });
+
+  it('stops on an empty workspace (0 of 0) once the run is finished', () => {
+    expect(
+      nextReindexPollInterval({
+        ...base,
+        deadline: 10_000,
+        status: { reindexing: false, indexedPages: 0, totalPages: 0 },
+      }),
+    ).toBe(false);
+  });
+});
+
+describe('isReindexComplete', () => {
+  it('false when no status yet', () => {
+    expect(isReindexComplete(undefined)).toBe(false);
+  });
+
+  it('false while a run is still active (even at indexed==total)', () => {
+    expect(
+      isReindexComplete({ reindexing: true, indexedPages: 478, totalPages: 478 }),
+    ).toBe(false);
+  });
+
+  it('false when finished but not yet fully indexed', () => {
+    expect(
+      isReindexComplete({ reindexing: false, indexedPages: 120, totalPages: 478 }),
+    ).toBe(false);
+  });
+
+  it('true once finished and fully indexed', () => {
+    expect(
+      isReindexComplete({ reindexing: false, indexedPages: 478, totalPages: 478 }),
+    ).toBe(true);
+  });
+});
+
+describe('isReindexButtonLoading', () => {
+  it('loads while the POST mutation is pending', () => {
+    expect(
+      isReindexButtonLoading({
+        mutationPending: true,
+        deadline: null,
+        status: false,
+      }),
+    ).toBe(true);
+  });
+
+  it('does NOT load post-cap: deadline nulled but reindexing left stale-true', () => {
+    // The key case: after the poll cap fires `reindexDeadline` is null while
+    // `settings.reindexing` can be a stale `true` from the last poll. Gating on
+    // the deadline keeps the spinner from sticking forever so the admin can
+    // restart.
+    expect(
+      isReindexButtonLoading({
+        mutationPending: false,
+        deadline: null,
+        status: true,
+      }),
+    ).toBe(false);
+  });
+
+  it('loads during an active run within the poll window', () => {
+    expect(
+      isReindexButtonLoading({
+        mutationPending: false,
+        deadline: 10_000,
+        status: true,
+      }),
+    ).toBe(true);
+  });
+
+  it('does not load once the run finished while still polling', () => {
+    expect(
+      isReindexButtonLoading({
+        mutationPending: false,
+        deadline: 10_000,
+        status: false,
+      }),
+    ).toBe(false);
+  });
+});

apps/client/src/features/workspace/components/settings/components/ai-provider-settings.tsx

@@ -37,6 +37,7 @@ import {
 } from "@/features/workspace/queries/ai-settings-query.ts";
 import {
   AiTestCapability,
+  IAiSettings,
   IAiSettingsUpdate,
   SttApiStyle,
   ChatApiStyle,
@@ -169,6 +170,73 @@ export function resolveKeyField(
   return { set: false };
 }
 
+// Subset of the status payload that drives the reindex poll decisions.
+type ReindexStatus = Pick<
+  IAiSettings,
+  "reindexing" | "indexedPages" | "totalPages"
+>;
+
+/**
+ * Decide the TanStack Query `refetchInterval` while a reindex may be running.
+ * Returns the poll interval (ms) to keep polling, or `false` to stop.
+ *
+ * Polls while the server reports an ACTIVE run (`reindexing === true`) OR we are
+ * still within the deadline window and not yet fully indexed. Stops once the run
+ * has finished AND everything is indexed (server cleared its progress record and
+ * fell back to the DB coverage count), or the deadline cap is hit — the cap
+ * always wins so a stuck/never-clearing progress record can't poll forever.
+ */
+export function nextReindexPollInterval(args: {
+  deadline: number | null;
+  now: number;
+  intervalMs: number;
+  status?: ReindexStatus;
+}): number | false {
+  const { deadline, now, intervalMs, status } = args;
+  if (deadline === null) return false;
+  // Cap always wins.
+  if (now > deadline) return false;
+  // Active run → keep polling even if the momentary counts already look full.
+  if (status?.reindexing) return intervalMs;
+  // Finished and fully indexed (incl. an empty workspace, 0 >= 0) → stop. Reuse
+  // isReindexComplete so the completeness check lives in exactly one place.
+  if (isReindexComplete(status)) return false;
+  // Within the deadline and not yet done → keep polling.
+  return intervalMs;
+}
+
+/**
+ * Whether the reindex poll deadline should be cleared: the server reports no
+ * active run AND the count is complete. The single source of truth for the
+ * "reindex finished" check — `nextReindexPollInterval` reuses it for its stop
+ * condition (sans the cap, which the effect handles via time).
+ */
+export function isReindexComplete(status?: ReindexStatus): boolean {
+  return (
+    !!status && !status.reindexing && status.indexedPages >= status.totalPages
+  );
+}
+
+/**
+ * Whether the reindex button should show its spinner (and stay disabled).
+ *
+ * Spins while the POST is in flight, and for the WHOLE background run while the
+ * server reports `reindexing === true`. The `deadline !== null` gate is the
+ * load-bearing part: once the 120s poll cap fires it nulls `reindexDeadline`
+ * and stops refetching, so `status` (settings?.reindexing) can be a stale
+ * `true` from the last poll. Without the gate the spinner would stick forever
+ * for a run that outlives the cap and block a restart; gating on the active
+ * poll window clears it so the admin can re-trigger.
+ */
+export function isReindexButtonLoading(args: {
+  mutationPending: boolean;
+  deadline: number | null;
+  status?: boolean;
+}): boolean {
+  const { mutationPending, deadline, status } = args;
+  return mutationPending || (deadline !== null && status === true);
+}
+
 // Translate the dot's tooltip label. Kept in one place so all three endpoint
 // cards share identical wording.
 function cardStatusLabel(status: CardStatus, t: (k: string) => string): string {
@@ -215,31 +283,34 @@ export default function AiProviderSettings() {
   // PRE-job counts immediately, so the only way the "Indexed X of Y" counter
   // visibly climbs is to keep polling the settings query while the job runs.
   // `reindexDeadline` is the timestamp until which we poll (set on reindex
-  // success); polling stops early once indexed === total. Bounded so a stuck
-  // job can never poll forever.
-  const REINDEX_POLL_INTERVAL = 3000; // ms between refetches while indexing
+  // success). Polling tracks the server's `reindexing` flag: it keeps going for
+  // the whole active run and stops promptly once the server reports the run is
+  // finished. Bounded by the cap so a stuck/never-clearing progress record can
+  // never poll forever.
+  const REINDEX_POLL_INTERVAL = 5000; // ms between refetches while indexing
   const REINDEX_POLL_CAP_MS = 120000; // ~2 min hard cap
   const [reindexDeadline, setReindexDeadline] = useState<number | null>(null);
 
   // Only admins may read the (masked) AI settings; the server enforces this too.
-  const { data: settings, isLoading } = useAiSettingsQuery(isAdmin, (query) => {
-    if (reindexDeadline === null) return false;
-    // Past the cap → stop polling (cleared via the effect below too).
-    if (Date.now() > reindexDeadline) return false;
-    const data = query.state.data;
-    // Stop once everything is indexed; otherwise keep polling.
-    if (data && data.indexedPages >= data.totalPages) return false;
-    return REINDEX_POLL_INTERVAL;
-  });
+  const { data: settings, isLoading } = useAiSettingsQuery(isAdmin, (query) =>
+    nextReindexPollInterval({
+      deadline: reindexDeadline,
+      now: Date.now(),
+      intervalMs: REINDEX_POLL_INTERVAL,
+      status: query.state.data,
+    }),
+  );
 
-  // Stop polling once the work is done or the cap is reached. Also clears on
+  // Stop polling once the run is finished or the cap is reached. Also clears on
   // unmount because the deadline state goes away with the component.
   useEffect(() => {
     if (reindexDeadline === null) return;
-    // "Done" matches the refetchInterval stop condition (indexed >= total),
-    // including an empty workspace (0 >= 0), so the deadline clears promptly
-    // instead of waiting out the cap.
-    if (settings && settings.indexedPages >= settings.totalPages) {
+    // "Done" matches the refetchInterval stop condition: the server reports no
+    // active run AND the count is complete (indexed >= total, incl. an empty
+    // workspace 0 >= 0), so the deadline clears promptly instead of waiting out
+    // the cap. While `reindexing` is still true we keep the deadline so polling
+    // continues for the whole run.
+    if (isReindexComplete(settings)) {
       setReindexDeadline(null);
       return;
     }
@@ -1031,7 +1102,17 @@ export default function AiProviderSettings() {
             <Button
               variant="subtle"
               size="compact-sm"
-              loading={reindexMutation.isPending}
+              // Spin for the WHOLE run: the POST resolves immediately, but the
+              // background job keeps running, so also stay loading while the
+              // server reports `reindexing` (this also blocks a redundant
+              // re-trigger mid-run; the server de-dupes regardless). The
+              // deadline gate (and why it matters post-cap) lives in
+              // `isReindexButtonLoading`, which is unit-tested.
+              loading={isReindexButtonLoading({
+                mutationPending: reindexMutation.isPending,
+                deadline: reindexDeadline,
+                status: settings?.reindexing,
+              })}
               onClick={() =>
                 reindexMutation.mutate(undefined, {
                   // Begin bounded polling so the counter climbs as the async

apps/client/src/features/workspace/queries/ai-settings-query.ts

@@ -23,8 +23,12 @@ export function useAiSettingsQuery(
   enabled: boolean = true,
   // While reindexing runs as an async background job, the counter only climbs
   // if the client keeps refetching. The component passes a refetchInterval
-  // function that polls until indexed === total or a bounded deadline, then
-  // returns false to stop. See AiProviderSettings.
+  // function (`nextReindexPollInterval`) that keeps polling while the server
+  // reports an active run (reindexing === true) OR we are still within the
+  // bounded deadline and not yet fully indexed; it returns false to stop only
+  // once the run has finished AND indexed >= total, or the deadline cap is hit
+  // (the cap always wins). Note: a transient indexed === total during an active
+  // run does NOT stop polling. See AiProviderSettings.
   refetchInterval?:
     | number
     | false

apps/client/src/features/workspace/services/ai-settings-service.ts

@@ -48,6 +48,9 @@ export interface IAiSettings {
   // RAG indexing coverage (pages indexed for semantic search).
   indexedPages: number;
   totalPages: number;
+  // True while a full workspace reindex is actively running; the counts above
+  // then reflect the live run progress (done climbs 0 -> total).
+  reindexing?: boolean;
 }
 
 // Update payload. Key semantics (same for `apiKey` and `embeddingApiKey`):

apps/server/package.json

@@ -23,7 +23,7 @@
     "migration:reset": "tsx src/database/migrate.ts down-to NO_MIGRATIONS",
     "migration:codegen": "kysely-codegen --dialect=postgres --camel-case --env-file=../../.env --out-file=./src/database/types/db.d.ts",
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
-    "pretest": "pnpm --filter @docmost/editor-ext build",
+    "pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/git-sync build && pnpm --filter @docmost/mcp build",
     "test": "jest",
     "test:int": "jest --config test/jest-integration.json",
     "test:watch": "jest --watch",
@@ -41,6 +41,7 @@
     "@aws-sdk/s3-request-presigner": "3.1050.0",
     "@azure/storage-blob": "12.31.0",
     "@clickhouse/client": "^1.18.2",
+    "@docmost/git-sync": "workspace:*",
     "@docmost/mcp": "workspace:*",
     "@docmost/pdf-inspector": "1.9.6",
     "@fastify/cookie": "^11.0.2",
@@ -125,6 +126,7 @@
     "typesense": "^3.0.5",
     "undici": "7.24.0",
     "ws": "^8.20.1",
+    "yaml": "^2.8.3",
     "yauzl": "^3.2.1",
     "zod": "^4.3.6"
   },
@@ -188,7 +190,12 @@
           ]
         }
       ],
-      "^.+\\.(t|j)sx?$": "ts-jest"
+      "^.+\\.(t|j)sx?$": [
+        "ts-jest",
+        {
+          "isolatedModules": true
+        }
+      ]
     },
     "transformIgnorePatterns": [
       "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0)(@|/))"
@@ -198,11 +205,17 @@
     ],
     "coverageDirectory": "../coverage",
     "testEnvironment": "node",
+    "setupFiles": [
+      "<rootDir>/../test/jest.setup.ts"
+    ],
     "moduleNameMapper": {
       "^@docmost/db/(.*)$": "<rootDir>/database/$1",
       "^@docmost/transactional/(.*)$": "<rootDir>/integrations/transactional/$1",
       "^@docmost/ee/(.*)$": "<rootDir>/ee/$1",
-      "^src/(.*)$": "<rootDir>/$1"
+      "^src/(.*)$": "<rootDir>/$1",
+      "^@docmost/git-sync$": "<rootDir>/../../../packages/git-sync/src/index.ts",
+      "^@docmost/git-sync/(.*)$": "<rootDir>/../../../packages/git-sync/src/$1",
+      "^(\\.{1,2}/.*)\\.js$": "$1"
     }
   }
 }

apps/server/src/app.module.ts

@@ -28,6 +28,7 @@ import { ClsModule } from 'nestjs-cls';
 import { NoopAuditModule } from './integrations/audit/audit.module';
 import { ThrottleModule } from './integrations/throttle/throttle.module';
 import { McpModule } from './integrations/mcp/mcp.module';
+import { GitSyncModule } from './integrations/git-sync/git-sync.module';
 import { SandboxModule } from './integrations/sandbox/sandbox.module';
 import { AiModule } from './integrations/ai/ai.module';
 import { AiChatModule } from './core/ai-chat/ai-chat.module';
@@ -90,6 +91,7 @@ try {
     TelemetryModule,
     ThrottleModule,
     McpModule,
+    GitSyncModule,
     SandboxModule,
     AiModule,
     AiChatModule,

apps/server/src/collaboration/collaboration.gateway.ts

@@ -33,6 +33,11 @@ export class CollaborationGateway {
   // @ts-ignore
   private readonly redisSync: RedisSyncExtension<CollabEventHandlers> | null =
     null;
+  // Source ioredis client that RedisSyncExtension duplicates into its pub/sub
+  // pair. The extension's onDestroy only disconnects those duplicates, so we
+  // keep a reference here and disconnect the source ourselves on shutdown
+  // (otherwise the socket leaks and jest never exits in e2e).
+  private redisClient: RedisClient | null = null;
   private readonly withRedis: boolean;
 
   constructor(
@@ -57,16 +62,17 @@ export class CollaborationGateway {
     });
 
     if (this.withRedis) {
+      this.redisClient = new RedisClient({
+        host: this.redisConfig.host,
+        port: this.redisConfig.port,
+        password: this.redisConfig.password,
+        db: this.redisConfig.db,
+        family: this.redisConfig.family,
+        retryStrategy: createRetryStrategy(),
+      });
       // @ts-ignore
       this.redisSync = new RedisSyncExtension({
-        redis: new RedisClient({
-          host: this.redisConfig.host,
-          port: this.redisConfig.port,
-          password: this.redisConfig.password,
-          db: this.redisConfig.db,
-          family: this.redisConfig.family,
-          retryStrategy: createRetryStrategy(),
-        }),
+        redis: this.redisClient,
         serverId: `collab-${os?.hostname()}-${nanoid(10)}`,
         prefix: 'collab',
         pack,
@@ -149,6 +155,45 @@ export class CollaborationGateway {
     return this.hocuspocus.openDirectConnection(documentName, context);
   }
 
+  /**
+   * Write a git-originated body into a page, applying the merge on the instance
+   * that OWNS the live Y.Doc so a connected editor CONVERGES on the change.
+   *
+   * git-sync must NOT use openDirectConnection directly for this: that opens the
+   * document on whichever instance/process runs git-sync (the API/worker). When
+   * an editor is connected to a DIFFERENT collab instance/process, that is a
+   * SEPARATE, detached Y.Doc — the merge lands in the detached doc and the DB,
+   * but the live editor never receives the Yjs update; its next debounced
+   * autosave then overwrites the DB with its stale state and SILENTLY REVERTS
+   * the git change (the data-loss bug). Routing through the custom-event channel
+   * runs the merge on the owning instance's shared Document, whose update is
+   * broadcast to every connection (handleUpdate), so the editor's CRDT converges
+   * on the merged result.
+   *
+   * Without redis there is a single instance, so the write runs locally — which
+   * is already the owning (and only) instance the editor is connected to.
+   */
+  async writePageBody(
+    documentName: string,
+    payload: {
+      prosemirrorJson: unknown;
+      baseProsemirrorJson?: unknown;
+      userId: string;
+    },
+  ): Promise<void> {
+    if (this.redisSync) {
+      await this.handleYjsEvent(
+        'gitSyncWriteBody',
+        documentName,
+        payload as any,
+      );
+      return;
+    }
+    await this.collabEventsService
+      .getHandlers(this.hocuspocus)
+      .gitSyncWriteBody(documentName, payload as any);
+  }
+
   /*
    *Can be used before calling openDirectConnection directly
    */
@@ -184,5 +229,10 @@ export class CollaborationGateway {
     });
 
     await this.hocuspocus.hooks('onDestroy', { instance: this.hocuspocus });
+
+    // RedisSyncExtension.onDestroy (run via the hook above) disconnects only the
+    // duplicated pub/sub clients; the source client created here is ours to close.
+    this.redisClient?.disconnect();
+    this.redisClient = null;
   }
 }

apps/server/src/collaboration/collaboration.handler.git-sync.spec.ts

@@ -0,0 +1,262 @@
+// Exercises the REAL `gitSyncWriteBody` collab handler (the owner-routed body
+// write the data-loss fix introduces). The handler imports the editor graph via
+// collaboration.util / yjs.util (tiptapExtensions -> editor-ext -> react-dom,
+// unloadable under jest's node env, same coupling noted in
+// gitmost-datasource.service.spec.ts), so we stub those + the transformer. The
+// stubbed toYdoc builds paragraph blocks straight from the ProseMirror JSON so
+// we can assert convergence on real text.
+jest.mock('./collaboration.util', () => ({
+  tiptapExtensions: [],
+  getPageId: (name: string) => name.replace(/^page\./, ''),
+  prosemirrorNodeToYElement: jest.fn(),
+}));
+jest.mock('./yjs.util', () => ({
+  setYjsMark: jest.fn(),
+  updateYjsMarkAttribute: jest.fn(),
+}));
+jest.mock('@hocuspocus/transformer', () => {
+  const Yjs = require('yjs');
+  return {
+    TiptapTransformer: {
+      toYdoc: (json: any) => {
+        if (json?.__throw) throw new Error('boom: malformed doc');
+        const d = new Yjs.Doc();
+        const frag = d.getXmlFragment('default');
+        const blocks = (json?.content ?? []).map((node: any) => {
+          const el = new Yjs.XmlElement(node.type || 'paragraph');
+          const text = (node.content ?? [])
+            .map((t: any) => t.text ?? '')
+            .join('');
+          const t = new Yjs.XmlText();
+          if (text) t.insert(0, text);
+          el.insert(0, [t]);
+          return el;
+        });
+        if (blocks.length) frag.insert(0, blocks);
+        return d;
+      },
+    },
+  };
+});
+
+import * as Y from 'yjs';
+import { CollaborationHandler } from './collaboration.handler';
+
+const pmDoc = (...paras: string[]) => ({
+  type: 'doc',
+  content: paras.map((text) => ({
+    type: 'paragraph',
+    content: text ? [{ type: 'text', text }] : [],
+  })),
+});
+
+const texts = (frag: Y.XmlFragment): string[] =>
+  frag.toArray().map((el) =>
+    (el as Y.XmlElement)
+      .toArray()
+      .map((c) => (c as Y.XmlText).toString())
+      .join(''),
+  );
+
+// Build a fake Hocuspocus whose openDirectConnection yields a DirectConnection
+// over a REAL shared Document, with a connected "editor" doc that receives the
+// shared doc's updates (modelling Document.handleUpdate's broadcast on the
+// OWNING instance). Initial content carries live block ids; the editor starts
+// fully synced with the shared doc.
+function fakeHocuspocus(initial: { text: string; id: string }[]) {
+  const shared = new Y.Doc();
+  const frag = shared.getXmlFragment('default');
+  shared.transact(() => {
+    frag.insert(
+      0,
+      initial.map((s) => {
+        const el = new Y.XmlElement('paragraph');
+        el.setAttribute('id', s.id);
+        const t = new Y.XmlText();
+        if (s.text) t.insert(0, s.text);
+        el.insert(0, [t]);
+        return el;
+      }),
+    );
+  });
+  const editor = new Y.Doc();
+  Y.applyUpdate(editor, Y.encodeStateAsUpdate(shared));
+  // Broadcast relay: server-originated updates flow to the connected editor.
+  shared.on('update', (u: Uint8Array, origin: any) => {
+    if (origin !== 'editor') Y.applyUpdate(editor, u, 'server');
+  });
+
+  const openDirectConnection = jest.fn(async () => ({
+    // DirectConnection.transact runs the fn directly against the Document (no
+    // wrapping Y transaction), exactly like @hocuspocus/server.
+    transact: async (fn: (doc: Y.Doc) => void) => fn(shared),
+    disconnect: jest.fn(async () => undefined),
+  }));
+
+  return { hocuspocus: { openDirectConnection } as any, shared, editor };
+}
+
+describe('CollaborationHandler.gitSyncWriteBody (owner-routed body write)', () => {
+  it('converges a connected editor on the git change (no silent revert)', async () => {
+    const { hocuspocus, shared, editor } = fakeHocuspocus([
+      { text: 'alpha', id: 'p1' },
+      { text: 'beta', id: 'p2' },
+    ]);
+    const handler = new CollaborationHandler();
+    const handlers = handler.getHandlers(hocuspocus);
+
+    // git changed block 1 beta -> beta2; base is the pre-change content.
+    await handlers.gitSyncWriteBody('page.x', {
+      prosemirrorJson: pmDoc('alpha', 'beta2'),
+      baseProsemirrorJson: pmDoc('alpha', 'beta'),
+      userId: 'svc-user',
+    });
+
+    // The shared (owning-instance) doc holds the merge...
+    expect(texts(shared.getXmlFragment('default'))).toEqual(['alpha', 'beta2']);
+    // ...and the connected editor CONVERGED via the broadcast (the bug would
+    // leave it on 'beta' and revert the page on its next autosave).
+    expect(texts(editor.getXmlFragment('default'))).toEqual(['alpha', 'beta2']);
+  });
+
+  it('preserves a concurrent edit to a DIFFERENT block (3-way, finding #2)', async () => {
+    const { hocuspocus, shared, editor } = fakeHocuspocus([
+      { text: 'alpha', id: 'p1' },
+      { text: 'beta', id: 'p2' },
+    ]);
+    // The editor is actively editing block 0 while the push arrives.
+    const eFrag = editor.getXmlFragment('default');
+    editor.transact(
+      () => (eFrag.get(0) as Y.XmlElement).get(0) instanceof Y.XmlText &&
+        ((eFrag.get(0) as Y.XmlElement).get(0) as Y.XmlText).insert(5, ' EDIT'),
+      'editor',
+    );
+    Y.applyUpdate(shared, Y.encodeStateAsUpdate(editor), 'editor');
+
+    const handler = new CollaborationHandler();
+    await handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
+      prosemirrorJson: pmDoc('alpha', 'beta2'),
+      baseProsemirrorJson: pmDoc('alpha', 'beta'),
+      userId: 'svc-user',
+    });
+
+    // Human's block-0 edit AND git's block-1 change both survive on the editor.
+    expect(texts(editor.getXmlFragment('default'))).toEqual([
+      'alpha EDIT',
+      'beta2',
+    ]);
+  });
+
+  it('FLUSHES the pending debounced store BEFORE merging so an in-flight edit survives (finding #2)', async () => {
+    // QA #119 finding #2: the 3-way merge must run against the latest live-doc
+    // state. A concurrent UI edit that is still in-flight (the store is debounced)
+    // must be drained into the live doc BEFORE git merges, or git clean-applies and
+    // the edit is silently dropped — even on a DIFFERENT block. Model the drain via
+    // the pending-store flush: when it runs, the in-flight block-0 edit lands.
+    const shared = new Y.Doc();
+    const frag = shared.getXmlFragment('default');
+    shared.transact(() => {
+      frag.insert(
+        0,
+        [
+          { text: 'alpha', id: 'p1' },
+          { text: 'beta', id: 'p2' },
+        ].map((s) => {
+          const el = new Y.XmlElement('paragraph');
+          el.setAttribute('id', s.id);
+          const t = new Y.XmlText();
+          t.insert(0, s.text);
+          el.insert(0, [t]);
+          return el;
+        }),
+      );
+    });
+
+    const order: string[] = [];
+    const debouncer = {
+      isDebounced: jest.fn(() => true),
+      executeNow: jest.fn(async () => {
+        order.push('flush');
+        // The in-flight client edit to block 0 only lands once the pending store
+        // is flushed (i.e. the event loop is drained) — BEFORE the merge.
+        shared.transact(() =>
+          ((frag.get(0) as Y.XmlElement).get(0) as Y.XmlText).insert(5, ' EDIT'),
+        );
+      }),
+    };
+    const openDirectConnection = jest.fn(async () => ({
+      transact: async (fn: (doc: Y.Doc) => void) => {
+        order.push('merge');
+        fn(shared);
+      },
+      disconnect: jest.fn(async () => undefined),
+    }));
+    const hocuspocus = { openDirectConnection, debouncer } as any;
+
+    const handler = new CollaborationHandler();
+    await handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
+      prosemirrorJson: pmDoc('alpha', 'beta2'), // git changes block 1
+      baseProsemirrorJson: pmDoc('alpha', 'beta'),
+      userId: 'svc-user',
+    });
+
+    // The flush ran, and it ran BEFORE the merge transaction.
+    expect(debouncer.executeNow).toHaveBeenCalledTimes(1);
+    expect(order).toEqual(['flush', 'merge']);
+    // Both the in-flight block-0 edit and git's block-1 change survive — the
+    // pre-flush bug would have produced ['alpha', 'beta2'] (UI edit dropped).
+    expect(texts(shared.getXmlFragment('default'))).toEqual([
+      'alpha EDIT',
+      'beta2',
+    ]);
+  });
+
+  it('does not flush when no store is pending (isDebounced false)', async () => {
+    const { hocuspocus, shared } = fakeHocuspocus([{ text: 'a', id: 'p1' }]);
+    const executeNow = jest.fn();
+    (hocuspocus as any).debouncer = {
+      isDebounced: jest.fn(() => false),
+      executeNow,
+    };
+    const handler = new CollaborationHandler();
+    await handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
+      prosemirrorJson: pmDoc('a', 'b'),
+      userId: 'svc-user',
+    });
+    expect(executeNow).not.toHaveBeenCalled();
+    expect(texts(shared.getXmlFragment('default'))).toEqual(['a', 'b']);
+  });
+
+  it('crash-safe: a transform failure never opens the connection or mutates the live doc', async () => {
+    const { hocuspocus, shared } = fakeHocuspocus([{ text: 'alpha', id: 'p1' }]);
+    const before = texts(shared.getXmlFragment('default'));
+    const handler = new CollaborationHandler();
+
+    await expect(
+      handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
+        prosemirrorJson: { __throw: true } as any,
+        userId: 'svc-user',
+      }),
+    ).rejects.toThrow('boom');
+
+    // The incoming doc is built BEFORE opening the connection, so the throw
+    // happens first: the live doc is untouched and no connection was opened.
+    expect(hocuspocus.openDirectConnection).not.toHaveBeenCalled();
+    expect(texts(shared.getXmlFragment('default'))).toEqual(before);
+  });
+
+  it('falls back to a 2-way merge when no base is supplied', async () => {
+    const { hocuspocus, shared, editor } = fakeHocuspocus([
+      { text: 'alpha', id: 'p1' },
+    ]);
+    const handler = new CollaborationHandler();
+
+    await handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
+      prosemirrorJson: pmDoc('alpha', 'gamma'),
+      userId: 'svc-user',
+    });
+
+    expect(texts(shared.getXmlFragment('default'))).toEqual(['alpha', 'gamma']);
+    expect(texts(editor.getXmlFragment('default'))).toEqual(['alpha', 'gamma']);
+  });
+});

apps/server/src/collaboration/collaboration.handler.ts

@@ -8,6 +8,10 @@ import {
 import { setYjsMark, updateYjsMarkAttribute, YjsSelection } from './yjs.util';
 import * as Y from 'yjs';
 import { User } from '@docmost/db/types/entity.types';
+import {
+  mergeXmlFragments,
+  mergeXmlFragments3WayWithStats,
+} from './merge/yjs-body-merge';
 
 export type CollabEventHandlers = ReturnType<
   CollaborationHandler['getHandlers']
@@ -112,9 +116,130 @@ export class CollaborationHandler {
           },
         );
       },
+      /**
+       * Git-sync body write, applied as a block-level MERGE into the LIVE doc on
+       * the instance that OWNS it (routed here via the custom-event channel —
+       * see CollaborationGateway.writePageBody). Running on the owning instance
+       * is what makes a connected editor CONVERGE: the merge mutates the shared
+       * Document, whose update is broadcast to every connection, so the editor's
+       * CRDT applies the git change instead of silently reverting it on its next
+       * autosave (the data-loss bug this fixes).
+       *
+       * With a `baseProsemirrorJson` (the last-synced common ancestor) it does a
+       * THREE-WAY merge — a block only the human changed is kept, a block only
+       * git changed is taken (conflicts -> git). Without a base it falls back to
+       * the 2-way merge.
+       */
+      gitSyncWriteBody: async (
+        documentName: string,
+        payload: {
+          prosemirrorJson: any;
+          baseProsemirrorJson?: any;
+          userId: string;
+        },
+      ) => {
+        const { prosemirrorJson, baseProsemirrorJson, userId } = payload;
+
+        // Build the incoming (and base) Yjs docs BEFORE opening the connection /
+        // touching the live doc. If a transform throws (a malformed/unsupported
+        // doc) we must NOT have mutated the live body — otherwise a conversion
+        // failure could leave the page empty (crash-safe conversion).
+        const targetDoc = TiptapTransformer.toYdoc(
+          prosemirrorJson,
+          'default',
+          tiptapExtensions,
+        );
+        const baseDoc =
+          baseProsemirrorJson != null
+            ? TiptapTransformer.toYdoc(
+                baseProsemirrorJson,
+                'default',
+                tiptapExtensions,
+              )
+            : null;
+
+        // CONCURRENT-EDIT FLUSH (QA #119, finding #2). The 3-way merge below runs
+        // against the LIVE Y.Doc, so a concurrent UI edit is only preserved if it
+        // is already part of that doc. A user's edit is debounced before it lands
+        // (the editor batches; the collab store is debounced up to 10s), so the
+        // merge could otherwise run against a PRE-EDIT doc: git would then
+        // clean-apply (no same-block conflict detected) and the in-flight UI edit
+        // — even on a DIFFERENT block — would be silently dropped.
+        //
+        // Flushing the pending debounced store here (a) drains the event loop so a
+        // just-arrived client Yjs update is applied to the live doc BEFORE we
+        // merge, and (b) persists the live doc so the merge baseline is current
+        // even on the doc-reload-from-DB path. After the flush the merge sees the
+        // latest state, so an edit on a different block is MERGED (not overwritten)
+        // and a genuine same-block edit is detected as a conflict -> the
+        // boundary-snapshot in PersistenceExtension pins it to page history
+        // (recoverable) instead of vanishing silently.
+        await this.flushPendingStore(hocuspocus, documentName);
+
+        // actor:'git-sync' + the service user flow into PersistenceExtension
+        // (lastUpdatedSource='git-sync', lastUpdatedById=userId).
+        await this.withYdocConnection(
+          hocuspocus,
+          documentName,
+          { actor: 'git-sync', user: { id: userId } },
+          (doc) => {
+            const liveFrag = doc.getXmlFragment('default');
+            const targetFrag = targetDoc.getXmlFragment('default');
+            if (baseDoc) {
+              const { conflicts } = mergeXmlFragments3WayWithStats(
+                liveFrag,
+                targetFrag,
+                baseDoc.getXmlFragment('default'),
+              );
+              // SAME-BLOCK conflict contract (SPEC §9): a block both the human
+              // and git changed resolves to GIT (deterministic). Make that
+              // OBSERVABLE rather than silent — log it. The losing human content
+              // is NOT destroyed: the persistence extension's boundary snapshot
+              // pins the pre-merge page state to history on this user->git-sync
+              // transition, so it stays recoverable.
+              if (conflicts > 0) {
+                this.logger.warn(
+                  `git-sync merge for ${documentName}: ${conflicts} same-block ` +
+                    `conflict(s) resolved to the git version; the prior page ` +
+                    `state is preserved in page history (recoverable).`,
+                );
+              }
+            } else {
+              mergeXmlFragments(liveFrag, targetFrag);
+            }
+          },
+        );
+      },
     };
   }
 
+  /**
+   * Flush any pending DEBOUNCED store for `documentName` so the live Y.Doc and the
+   * DB are current BEFORE a git-sync merge reads them (QA #119, finding #2 —
+   * concurrent UI edit silently lost). Mirrors the PersistenceExtension.onDisconnect
+   * flush: only acts when a store is actually pending (`isDebounced`), runs the
+   * SAME scheduled payload (`executeNow`, preserving the edit's context/actor), and
+   * never throws — a flush failure must not abort the git-sync write. Awaiting it
+   * also drains the event loop, so a client Yjs update sitting in the socket buffer
+   * is applied to the live doc before the merge transaction runs.
+   */
+  private async flushPendingStore(
+    hocuspocus: Hocuspocus,
+    documentName: string,
+  ): Promise<void> {
+    const debounceId = `onStoreDocument-${documentName}`;
+    try {
+      const debouncer = (hocuspocus as any)?.debouncer;
+      if (!debouncer?.isDebounced?.(debounceId)) return;
+      await debouncer.executeNow(debounceId);
+    } catch (err) {
+      this.logger.warn(
+        `git-sync pre-merge flush failed for ${documentName}: ` +
+          (err instanceof Error ? err.message : String(err)),
+      );
+    }
+  }
+
   async withYdocConnection(
     hocuspocus: Hocuspocus,
     documentName: string,

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

@@ -36,6 +36,7 @@ import {
   Mention,
   Subpages,
   Highlight,
+  Spoiler,
   Indent,
   UniqueID,
   Columns,
@@ -82,6 +83,7 @@ export const tiptapExtensions = [
   Superscript,
   SubScript,
   Highlight,
+  Spoiler,
   Typography,
   TrailingNode,
   TextStyle,

apps/server/src/collaboration/extensions/persistence-store.spec.ts

@@ -205,31 +205,203 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     expect(historyQueue.add).toHaveBeenCalledTimes(1);
   });
 
-  // #206 persist-6 — RED (it.failing): a momentarily-empty live Y.Doc must not
-  // overwrite non-empty persisted content. `onStoreDocument` empty-guards the
-  // LOAD path but not the STORE path, so today an empty doc (a client/agent
-  // glitch, a bad merge, an emptying transclusion) is written straight over the
-  // page and the content is wiped silently. A store-side empty-guard is a real
-  // behaviour change (a deliberate "select-all + delete" is also empty), so it
-  // is left UNFIXED pending a product decision; this documents the data-loss
-  // path and flips to a normal passing test the moment the guard lands.
-  it.failing(
-    'does NOT overwrite non-empty content with a momentarily-empty live doc (persist-6)',
-    async () => {
-      const emptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
-      const document = ydocFor(emptyDoc);
-      pageRepo.findById.mockResolvedValue({
-        ...persistedHumanPage('IGNORED'),
-        content: doc('IMPORTANT RICH CONTENT'),
-      });
+  // #206 persist-6 / #248 — a momentarily-empty live Y.Doc must not overwrite
+  // non-empty persisted content. The store-side empty-guard blocks an empty doc
+  // (a client/agent glitch, a bad merge, an emptying transclusion) from wiping
+  // the page silently when NO intentional-clear signal is present.
+  it('does NOT overwrite non-empty content with a momentarily-empty live doc (persist-6)', async () => {
+    const emptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
+    const document = ydocFor(emptyDoc);
+    pageRepo.findById.mockResolvedValue({
+      ...persistedHumanPage('IGNORED'),
+      content: doc('IMPORTANT RICH CONTENT'),
+    });
 
-      await ext.onStoreDocument(buildData(document, 'user') as any);
+    await ext.onStoreDocument(buildData(document, 'user') as any);
 
-      // Desired contract: the empty incoming doc is rejected and the rich page
-      // survives. Today updatePage is called with the empty content (data loss).
-      expect(pageRepo.updatePage).not.toHaveBeenCalled();
-    },
-  );
+    // The empty incoming doc is rejected and the rich page survives.
+    expect(pageRepo.updatePage).not.toHaveBeenCalled();
+  });
+
+  // #248 — an empty-over-empty store is allowed (nothing to lose); the guard
+  // only protects non-empty persisted content.
+  it('allows an empty store over already-empty content (#248)', async () => {
+    const liveEmptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
+    const document = ydocFor(liveEmptyDoc);
+    // Stored content is empty per isEmptyParagraphDoc (paragraph with content:[])
+    // but NOT deep-equal to the normalized live doc, so the unchanged
+    // short-circuit is skipped and the empty-guard is genuinely reached.
+    pageRepo.findById.mockResolvedValue({
+      ...persistedHumanPage('IGNORED'),
+      content: { type: 'doc', content: [{ type: 'paragraph', content: [] }] },
+    });
+
+    await ext.onStoreDocument(buildData(document, 'user') as any);
+
+    expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+  });
+
+  // #251 — REAL-PATH regression test. The intentional-clear signal is set via
+  // the actual transport seam (ext.onStateless with the exact stateless payload
+  // the client's IntentionalClear extension sends), NOT a hand-injected
+  // context.intentionalClear poke. We then run the debounced store with an empty
+  // live doc over non-empty persisted content and assert the empty write goes
+  // through — i.e. the clear persists.
+  it('persists an intentional clear signalled via the real stateless transport (#251)', async () => {
+    const documentName = `page.${PAGE_ID}`;
+    const emptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
+    const document = ydocFor(emptyDoc);
+    pageRepo.findById.mockResolvedValue({
+      ...persistedHumanPage('IGNORED'),
+      content: doc('IMPORTANT RICH CONTENT'),
+    });
+
+    // The client signalled a deliberate clear over the live connection.
+    await ext.onStateless({
+      connection: { readOnly: false } as any,
+      documentName,
+      document: document as any,
+      payload: JSON.stringify({ type: 'intentional-clear' }),
+    } as any);
+
+    await ext.onStoreDocument(buildData(document, 'user') as any);
+
+    // The empty doc was written (the clear persisted). The persisted content is
+    // the Y.Doc round-trip of the empty doc (attrs normalized), so compare
+    // against fromYdoc rather than the raw literal.
+    expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+    const expectedEmpty = TiptapTransformer.fromYdoc(document, 'default');
+    expect(pageRepo.updatePage.mock.calls[0][0].content).toEqual(expectedEmpty);
+  });
+
+  // #251 — retry correctness: a transient DB failure on the FIRST attempt must
+  // not silently drop the clear. The intentional-clear flag is consumed ONCE
+  // before the retry loop, so when attempt 1's updatePage throws (tx rolls back,
+  // but the in-memory flag delete cannot roll back) the retry on attempt 2 still
+  // sees the clear as allowed and writes the empty doc. On the pre-fix code
+  // (consumeIntentionalClear called INSIDE the loop) attempt 1 consumed the flag,
+  // attempt 2 re-read it as absent and the empty-guard BLOCKED the write — so
+  // updatePage would be called once and the clear would be lost. This test fails
+  // on that ordering and passes after the hoist.
+  it('persists an intentional clear even when the first store attempt fails transiently (#251)', async () => {
+    const documentName = `page.${PAGE_ID}`;
+    const emptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
+    const document = ydocFor(emptyDoc);
+    // The page stays non-empty in the DB across both attempts (the rolled-back
+    // first attempt never changed it), exactly the failure scenario the WARNING
+    // describes.
+    pageRepo.findById.mockResolvedValue({
+      ...persistedHumanPage('IGNORED'),
+      content: doc('IMPORTANT RICH CONTENT'),
+    });
+
+    let attempts = 0;
+    pageRepo.updatePage.mockImplementation(async () => {
+      attempts += 1;
+      if (attempts === 1) throw new Error('deadlock detected'); // transient
+      callOrder.push('updatePage');
+    });
+
+    // The client signalled a deliberate clear over the live connection.
+    await ext.onStateless({
+      connection: { readOnly: false } as any,
+      documentName,
+      document: document as any,
+      payload: JSON.stringify({ type: 'intentional-clear' }),
+    } as any);
+
+    await ext.onStoreDocument(buildData(document, 'user') as any);
+
+    // First attempt failed and rolled back; the retry still honoured the clear
+    // and wrote the empty doc (the clear survived the retry).
+    expect(pageRepo.updatePage).toHaveBeenCalledTimes(2);
+    const expectedEmpty = TiptapTransformer.fromYdoc(document, 'default');
+    expect(pageRepo.updatePage.mock.calls[1][0].content).toEqual(expectedEmpty);
+  });
+
+  // #251 — the signal is single-use: it is consumed by the first empty store,
+  // so a SECOND accidental empty (no fresh signal) is still blocked.
+  it('consumes the intentional-clear signal once; a later empty is blocked (#251)', async () => {
+    const documentName = `page.${PAGE_ID}`;
+    const emptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
+    pageRepo.findById.mockResolvedValue({
+      ...persistedHumanPage('IGNORED'),
+      content: doc('IMPORTANT RICH CONTENT'),
+    });
+
+    await ext.onStateless({
+      connection: { readOnly: false } as any,
+      documentName,
+      document: ydocFor(emptyDoc) as any,
+      payload: JSON.stringify({ type: 'intentional-clear' }),
+    } as any);
+
+    // First empty store consumes the signal and writes.
+    await ext.onStoreDocument(buildData(ydocFor(emptyDoc), 'user') as any);
+    expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+
+    // Re-arm findById to non-empty (as if content came back) and fire another
+    // empty store WITHOUT a new signal — the guard must block it.
+    pageRepo.updatePage.mockClear();
+    pageRepo.findById.mockResolvedValue({
+      ...persistedHumanPage('IGNORED'),
+      content: doc('IMPORTANT RICH CONTENT'),
+    });
+    await ext.onStoreDocument(buildData(ydocFor(emptyDoc), 'user') as any);
+    expect(pageRepo.updatePage).not.toHaveBeenCalled();
+  });
+
+  // #251 — a read-only connection cannot arm the clear, so its empty store is
+  // still blocked (defends the guard against a read-only spoof).
+  it('ignores an intentional-clear signal from a read-only connection (#251)', async () => {
+    const documentName = `page.${PAGE_ID}`;
+    const emptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
+    const document = ydocFor(emptyDoc);
+    pageRepo.findById.mockResolvedValue({
+      ...persistedHumanPage('IGNORED'),
+      content: doc('IMPORTANT RICH CONTENT'),
+    });
+
+    await ext.onStateless({
+      connection: { readOnly: true } as any,
+      documentName,
+      document: document as any,
+      payload: JSON.stringify({ type: 'intentional-clear' }),
+    } as any);
+
+    await ext.onStoreDocument(buildData(document, 'user') as any);
+
+    expect(pageRepo.updatePage).not.toHaveBeenCalled();
+  });
+
+  // #251 — a non-empty store between the signal and the empty store drops the
+  // pending flag ("cleared then retyped" can't leave a usable signal behind).
+  it('drops a pending clear when a non-empty store intervenes (#251)', async () => {
+    const documentName = `page.${PAGE_ID}`;
+    const emptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
+
+    await ext.onStateless({
+      connection: { readOnly: false } as any,
+      documentName,
+      document: ydocFor(emptyDoc) as any,
+      payload: JSON.stringify({ type: 'intentional-clear' }),
+    } as any);
+
+    // A non-empty store lands first → consumes/drops the stale flag.
+    pageRepo.findById.mockResolvedValue(persistedHumanPage('NEW HUMAN TEXT'));
+    await ext.onStoreDocument(
+      buildData(ydocFor(doc('NEW HUMAN TEXT')), 'user') as any,
+    );
+    pageRepo.updatePage.mockClear();
+
+    // Now an empty store with no fresh signal must be blocked.
+    pageRepo.findById.mockResolvedValue({
+      ...persistedHumanPage('IGNORED'),
+      content: doc('IMPORTANT RICH CONTENT'),
+    });
+    await ext.onStoreDocument(buildData(ydocFor(emptyDoc), 'user') as any);
+    expect(pageRepo.updatePage).not.toHaveBeenCalled();
+  });
 
   // persist-1 — when every attempt fails the hook must NOT report a phantom
   // success: no "page.updated" badge broadcast and no history snapshot for

apps/server/src/collaboration/extensions/persistence.disconnect-flush.spec.ts

@@ -0,0 +1,89 @@
+import { PersistenceExtension } from './persistence.extension';
+
+/**
+ * Regression for the QA #119 "loss-on-fast-close" data loss: editing a page then
+ * closing the tab within the collab debounce window (~3-18s) lost the edit
+ * because, with `unloadImmediately: false`, Hocuspocus does NOT flush the
+ * debounced onStoreDocument on a last-client disconnect. PersistenceExtension
+ * now flushes the pending store on the LAST disconnect (and only then).
+ */
+describe('PersistenceExtension.onDisconnect flush (loss-on-fast-close)', () => {
+  function makeExt(): PersistenceExtension {
+    // onDisconnect touches none of the injected deps; pass casts.
+    return new PersistenceExtension(
+      null as any,
+      null as any,
+      null as any,
+      null as any,
+      null as any,
+      null as any,
+      null as any,
+      null as any,
+    );
+  }
+
+  function makeData(opts: {
+    clientsCount: number;
+    isDebounced: boolean;
+    isLoading?: boolean;
+  }) {
+    const executeNow = jest.fn(async () => undefined);
+    const isDebounced = jest.fn(() => opts.isDebounced);
+    return {
+      executeNow,
+      isDebounced,
+      payload: {
+        clientsCount: opts.clientsCount,
+        context: {},
+        document: { isLoading: opts.isLoading ?? false } as any,
+        documentName: 'page.abc',
+        instance: { debouncer: { isDebounced, executeNow } } as any,
+        requestHeaders: {},
+        requestParameters: new URLSearchParams(),
+        socketId: 's',
+      } as any,
+    };
+  }
+
+  it('flushes the pending store when the LAST client disconnects', async () => {
+    const ext = makeExt();
+    const { executeNow, payload } = makeData({
+      clientsCount: 0,
+      isDebounced: true,
+    });
+    await ext.onDisconnect(payload);
+    expect(executeNow).toHaveBeenCalledTimes(1);
+    expect(executeNow).toHaveBeenCalledWith('onStoreDocument-page.abc');
+  });
+
+  it('does NOT flush while other editors remain connected', async () => {
+    const ext = makeExt();
+    const { executeNow, payload } = makeData({
+      clientsCount: 2,
+      isDebounced: true,
+    });
+    await ext.onDisconnect(payload);
+    expect(executeNow).not.toHaveBeenCalled();
+  });
+
+  it('does NOT write when nothing is pending (already persisted)', async () => {
+    const ext = makeExt();
+    const { executeNow, payload } = makeData({
+      clientsCount: 0,
+      isDebounced: false,
+    });
+    await ext.onDisconnect(payload);
+    expect(executeNow).not.toHaveBeenCalled();
+  });
+
+  it('does NOT flush a doc that is still loading (load error guard)', async () => {
+    const ext = makeExt();
+    const { executeNow, payload } = makeData({
+      clientsCount: 0,
+      isDebounced: true,
+      isLoading: true,
+    });
+    await ext.onDisconnect(payload);
+    expect(executeNow).not.toHaveBeenCalled();
+  });
+});

apps/server/src/collaboration/extensions/persistence.extension.spec.ts

@@ -0,0 +1,223 @@
+// Stub collaboration.util so importing the extension does not drag in the
+// editor-ext -> @tiptap/react -> react-dom graph (unloadable under jest's node
+// env, same coupling the gitmost-datasource / mcp specs document). The
+// extension only calls getPageId, jsonToText and isEmptyParagraphDoc from it on
+// the store path; tiptapExtensions is unused by onStoreDocument.
+jest.mock('../collaboration.util', () => ({
+  tiptapExtensions: [],
+  getPageId: (name: string) => name.replace(/^page\./, ''),
+  jsonToText: () => 'text',
+  isEmptyParagraphDoc: () => false,
+  // The post-write mention extraction walks the doc via jsonToNode().descendants;
+  // return a node-like stub with no descendants so no mentions are produced
+  // (mention handling is out of scope here — we only assert provenance).
+  jsonToNode: () => ({ descendants: () => undefined }),
+}));
+
+// Control the Yjs<->JSON bridge: fromYdoc returns the "incoming" doc the writer
+// is storing. We keep it distinct from the page's persisted content so the
+// no-op guard (isDeepStrictEqual) never short-circuits the write.
+const INCOMING_JSON = { type: 'doc', content: [{ type: 'paragraph' }, { t: 1 }] };
+jest.mock('@hocuspocus/transformer', () => ({
+  TiptapTransformer: {
+    fromYdoc: jest.fn(() => INCOMING_JSON),
+    toYdoc: jest.fn(),
+  },
+}));
+
+// Run the executeTx callback inline with a passthrough trx.
+jest.mock('@docmost/db/utils', () => ({
+  executeTx: jest.fn(async (_db: any, cb: any) => cb({} as any)),
+}));
+
+import * as Y from 'yjs';
+import { PersistenceExtension } from './persistence.extension';
+import {
+  onChangePayload,
+  onStoreDocumentPayload,
+} from '@hocuspocus/server';
+
+/**
+ * Provenance-precedence coverage for PersistenceExtension.onStoreDocument
+ * (test-strategy Module 4 / item #2): the contract `agent > git-sync > user`,
+ * plus the negative that a git-sync store does NOT pin a boundary history
+ * snapshot. We drive the precedence through the real public method (onChange to
+ * arm the sticky agent marker, then onStoreDocument), mocking the repos / db /
+ * Yjs bridge so no real database or collab server is needed. The store's
+ * persisted `lastUpdatedSource` and the saveHistory call are the observable
+ * outputs.
+ */
+describe('PersistenceExtension.onStoreDocument — provenance precedence (#2)', () => {
+  const DOCUMENT_NAME = 'page.page-1';
+  const PAGE_ID = 'page-1';
+
+  // `page.content` differs from INCOMING_JSON so the write is never skipped.
+  const persistedPage = (overrides?: { lastUpdatedSource?: string }) => ({
+    id: PAGE_ID,
+    slugId: 'slug-1',
+    spaceId: 'space-1',
+    workspaceId: 'ws-1',
+    creatorId: 'creator-1',
+    contributorIds: ['creator-1'],
+    content: { type: 'doc', content: [{ type: 'paragraph', content: [] }] },
+    lastUpdatedSource: overrides?.lastUpdatedSource ?? 'user',
+    createdAt: new Date(),
+  });
+
+  const build = (pageOverrides?: { lastUpdatedSource?: string }) => {
+    const pageRepo = {
+      findById: jest.fn().mockResolvedValue(persistedPage(pageOverrides)),
+      updatePage: jest.fn().mockResolvedValue({ numUpdatedRows: 1n }),
+    };
+    const pageHistoryRepo = {
+      // No prior snapshot -> humanBaselineMissing is true, so the ONLY thing
+      // gating the boundary snapshot in these tests is the source precedence.
+      findPageLastHistory: jest.fn().mockResolvedValue(null),
+      saveHistory: jest.fn().mockResolvedValue(undefined),
+    };
+    const aiQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    const historyQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    const notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    const collabHistory = {
+      addContributors: jest.fn().mockResolvedValue(undefined),
+    };
+    const transclusionService = {
+      syncPageTransclusions: jest.fn().mockResolvedValue(undefined),
+      syncPageReferences: jest.fn().mockResolvedValue(undefined),
+      syncPageTemplateReferences: jest.fn().mockResolvedValue(undefined),
+    };
+
+    const ext = new PersistenceExtension(
+      pageRepo as any,
+      pageHistoryRepo as any,
+      {} as any, // db
+      aiQueue as any,
+      historyQueue as any,
+      notificationQueue as any,
+      collabHistory as any,
+      transclusionService as any,
+    );
+
+    return { ext, pageRepo, pageHistoryRepo, historyQueue };
+  };
+
+  // A real Y.Doc is required for Y.encodeStateAsUpdate(document); broadcastStateless
+  // is a no-op spy. The fromYdoc bridge is mocked, so the doc's contents are
+  // irrelevant to the JSON path.
+  const makeStorePayload = (context: any): onStoreDocumentPayload =>
+    ({
+      documentName: DOCUMENT_NAME,
+      document: Object.assign(new Y.Doc(), {
+        broadcastStateless: jest.fn(),
+      }),
+      context,
+    }) as any;
+
+  const makeChangePayload = (actor: string): onChangePayload =>
+    ({
+      documentName: DOCUMENT_NAME,
+      context: { user: { id: 'user-1' }, actor },
+    }) as any;
+
+  const sourceOf = (pageRepo: { updatePage: jest.Mock }) =>
+    pageRepo.updatePage.mock.calls[0][0].lastUpdatedSource;
+
+  it("tags 'user' for a plain write (no agent touch, no git-sync actor)", async () => {
+    const { ext, pageRepo } = build();
+
+    await ext.onStoreDocument(
+      makeStorePayload({ user: { id: 'user-1' }, actor: 'user' }),
+    );
+
+    expect(sourceOf(pageRepo)).toBe('user');
+  });
+
+  it("tags 'git-sync' when the writer's actor is 'git-sync' and no agent touched the window", async () => {
+    const { ext, pageRepo } = build();
+
+    await ext.onStoreDocument(
+      makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
+    );
+
+    expect(sourceOf(pageRepo)).toBe('git-sync');
+  });
+
+  it("keeps 'git-sync' for an explicit git-sync store even with a sticky agent marker (#14 loop-guard)", async () => {
+    const { ext, pageRepo } = build();
+
+    // An agent edit landed earlier in the coalescing window (sticky marker),
+    // then a git-sync writer performs the store. Red-team finding #14: an
+    // EXPLICIT current-write actor is authoritative for THIS write, so the
+    // store must stay 'git-sync' — otherwise the PageChangeListener loop-guard
+    // (keyed on lastUpdatedSource === 'git-sync') fails to recognize git-sync's
+    // own write and re-exports it. Explicit 'agent' still wins (see below); the
+    // sticky marker only promotes a plain human writer to 'agent'.
+    await ext.onChange(makeChangePayload('agent'));
+    await ext.onStoreDocument(
+      makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
+    );
+
+    expect(sourceOf(pageRepo)).toBe('git-sync');
+  });
+
+  it("tags 'agent' when the storing writer itself is the agent (no prior onChange)", async () => {
+    const { ext, pageRepo } = build();
+
+    await ext.onStoreDocument(
+      makeStorePayload({ user: { id: 'agent-user' }, actor: 'agent' }),
+    );
+
+    expect(sourceOf(pageRepo)).toBe('agent');
+  });
+
+  // --- boundary snapshot for a git-sync store over a HUMAN baseline -----------
+  // SPEC §9 observable-loss guard (bug #2): a git-sync body write is a block-level
+  // 3-way merge whose same-block rule is "git wins". To keep a concurrent human
+  // edit RECOVERABLE rather than silently overwritten, a git-sync store over a
+  // prior NON-git-sync baseline pins that prior state to page history first —
+  // exactly like the agent path. So saveHistory MUST be called here.
+  it('DOES pin a boundary snapshot for a git-sync store over a prior human state', async () => {
+    const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'user' });
+
+    await ext.onStoreDocument(
+      makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
+    );
+
+    expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+  });
+
+  // --- negative: a git-sync store over a git-sync baseline does NOT re-pin -----
+  // The boundary is pinned once on the transition INTO git-sync; a subsequent
+  // git-sync store over an already-git-sync baseline must not churn history.
+  it('does NOT re-pin a boundary snapshot for a git-sync store over a git-sync baseline', async () => {
+    const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'git-sync' });
+
+    await ext.onStoreDocument(
+      makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
+    );
+
+    expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+  });
+
+  it('DOES pin a boundary snapshot for an agent store over a prior human state (control)', async () => {
+    // Confirms the negative above is meaningful: under the SAME mocks, an agent
+    // store over a 'user' baseline DOES trigger the boundary snapshot.
+    const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'user' });
+
+    await ext.onStoreDocument(
+      makeStorePayload({ user: { id: 'agent-user' }, actor: 'agent' }),
+    );
+
+    expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+  });
+
+  it('does NOT pin a boundary snapshot for a plain user store', async () => {
+    const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'user' });
+
+    await ext.onStoreDocument(
+      makeStorePayload({ user: { id: 'user-1' }, actor: 'user' }),
+    );
+
+    expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+  });
+});

apps/server/src/collaboration/extensions/persistence.extension.ts

@@ -2,7 +2,9 @@ import {
   afterUnloadDocumentPayload,
   Extension,
   onChangePayload,
+  onDisconnectPayload,
   onLoadDocumentPayload,
+  onStatelessPayload,
   onStoreDocumentPayload,
 } from '@hocuspocus/server';
 import * as Y from 'yjs';
@@ -41,6 +43,35 @@ import {
 } from '../constants';
 import { TransclusionService } from '../../core/page/transclusion/transclusion.service';
 
+/**
+ * #251 — wire format of the client→server stateless message that signals a
+ * deliberate page clear. The client (IntentionalClear editor extension) sends
+ * `{ type: INTENTIONAL_CLEAR_MESSAGE_TYPE }`; the document is taken from the
+ * connection, not the payload, so the signal cannot be aimed at another page.
+ */
+export const INTENTIONAL_CLEAR_MESSAGE_TYPE = 'intentional-clear';
+
+/**
+ * #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
+ * DEBOUNCED onStoreDocument, so the TTL must comfortably exceed the collab
+ * store debounce window (hocuspocus is configured with maxDebounce = 45s in
+ * collaboration.gateway.ts). 60s leaves a margin while keeping the window for a
+ * stale flag small; on top of the TTL, any non-empty store immediately drops a
+ * pending flag (see onStoreDocument), so a "cleared then retyped" sequence can
+ * never leave a usable flag behind.
+ *
+ * Known fail-safe limitation: the flag lives only in this node's process memory.
+ * If document ownership transfers to another node, or this node crashes/restarts,
+ * between the stateless signal (set on node A) and the debounced store, the
+ * in-memory flag is lost and the clear is silently NOT applied — the store-side
+ * empty-guard then reloads the document non-empty from the DB. This is
+ * deliberately fail-safe (a lost flag preserves content rather than destroying
+ * it), but it is a documented limitation, not a guarantee that every deliberate
+ * clear survives a node handoff.
+ */
+export const INTENTIONAL_CLEAR_TTL_MS = 60_000;
+
 /**
  * Resolve the provenance source for a coalesced snapshot.
  *
@@ -52,7 +83,17 @@ export function resolveSource(
   stickyTouched: boolean,
   contextActor?: string,
 ): ProvenanceSource {
-  return stickyTouched || contextActor === 'agent' ? 'agent' : 'user';
+  // An EXPLICIT current-write actor is authoritative for THIS write and wins
+  // over the sticky-agent fallback. Order: explicit 'agent' > explicit
+  // 'git-sync' > sticky agent marker > plain human 'user'. The git-sync case
+  // must NOT be masked by the sticky marker, or the PageChangeListener
+  // loop-guard (which keys on lastUpdatedSource === 'git-sync') would re-export
+  // git-sync's own writes (#14). Explicit agent still wins so a window that
+  // mixed an agent edit stays tagged 'agent'.
+  if (contextActor === 'agent') return 'agent';
+  if (contextActor === 'git-sync') return 'git-sync';
+  if (stickyTouched) return 'agent';
+  return 'user';
 }
 
 /**
@@ -96,6 +137,13 @@ 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();
+  // #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
+  // onStoreDocument empty-guard branch. This is the per-EDIT channel the
+  // per-connection context cannot provide (a clear is an edit event, but the
+  // store is debounced and connection context is fixed at authentication).
+  private intentionalClear: Map<string, number> = new Map();
 
   constructor(
     private readonly pageRepo: PageRepo,
@@ -154,6 +202,40 @@ export class PersistenceExtension implements Extension {
     return new Y.Doc();
   }
 
+  /**
+   * LOSS-ON-FAST-CLOSE FIX (QA #119). When the LAST editor disconnects, FLUSH any
+   * pending (debounced) store to the DB IMMEDIATELY instead of waiting out the
+   * up-to-10s `debounce` window.
+   *
+   * The collab server runs with `unloadImmediately: false` (collaboration.gateway),
+   * so on a last-client disconnect Hocuspocus does NOT flush the debounced
+   * onStoreDocument — it relies on the timer firing later. A quick edit-then-close
+   * (closing the tab within the debounce window, ~3-18s) therefore left the edit
+   * only in the soon-to-be-unloaded in-memory Y.Doc; meanwhile git-sync mirrored
+   * the STALE/empty DB body to the vault (the reported "59-byte frontmatter-only"
+   * data loss). Running the already-scheduled store now closes that window.
+   *
+   * Gated tightly so it never adds a redundant write: only on the LAST disconnect
+   * (`clientsCount === 0`), only for a fully-loaded doc, and only when a store is
+   * actually pending (`isDebounced`). `executeNow` runs the SAME payload Hocuspocus
+   * scheduled (preserving the edit's context/actor) and clears the timer.
+   */
+  async onDisconnect(data: onDisconnectPayload) {
+    const { instance, document, documentName, clientsCount } = data;
+    if (clientsCount > 0) return;
+    if (!document || document.isLoading) return;
+    const debounceId = `onStoreDocument-${documentName}`;
+    if (!instance?.debouncer?.isDebounced(debounceId)) return;
+    try {
+      await instance.debouncer.executeNow(debounceId);
+    } catch (err) {
+      this.logger.error(
+        `onDisconnect flush failed for ${documentName}: ` +
+          (err instanceof Error ? err.message : String(err)),
+      );
+    }
+  }
+
   async onStoreDocument(data: onStoreDocumentPayload) {
     const { documentName, document, context } = data;
 
@@ -176,10 +258,28 @@ export class PersistenceExtension implements Extension {
     // Sticky agent marker: 'agent' if any agent edit landed in this window, OR
     // if the current writer is the agent (covers a store with no prior onChange
     // agent event in the same window). §15 H2.
+    // Provenance precedence: agent > git-sync > user (see resolveSource). A
+    // 'git-sync' store is NOT given an immediate history snapshot — it is
+    // debounced like a human edit (a git-sync write is a block-level merge into
+    // the live doc, so it reads like an incremental human edit, not a bulk
+    // import that would warrant its own immediate snapshot).
     const lastUpdatedSource = resolveSource(
       this.consumeAgentTouched(documentName),
       context?.actor,
     );
+    // #251 — consume the intentional-clear flag ONCE, BEFORE the retry loop
+    // (like consumeContributors / consumeAgentTouched above). consumeIntentional-
+    // Clear ALWAYS deletes the in-memory Map entry, but a tx rollback cannot
+    // un-delete it. Calling it INSIDE the loop meant: a clear armed for attempt 1
+    // was consumed there, attempt 1's updatePage threw a transient error and
+    // rolled back, then attempt 2 re-read non-empty content and saw the flag
+    // already gone — silently downgrading the retry into a BLOCKED write, so the
+    // user's deliberate clear was dropped. Hoisting makes the decision stable
+    // across every attempt. This single call also preserves the "a non-empty
+    // store drops a pending flag" semantics (the cleared-then-retyped case):
+    // every store consumes the flag here regardless of incoming emptiness, so a
+    // subsequent non-empty store can never leave a usable flag behind.
+    const allowIntentionalClear = this.consumeIntentionalClear(documentName);
 
     // Persist with a small bounded retry. The in-memory Y.Doc is the ONLY copy
     // of the latest edit until this hook returns: hocuspocus destroys/unloads the
@@ -210,6 +310,46 @@ export class PersistenceExtension implements Extension {
             return;
           }
 
+          // #206 persist-6 / #248 — store-side empty-guard. A momentarily-empty
+          // live Y.Doc (a client/agent glitch, a bad merge, a transclusion that
+          // emptied) must NOT overwrite non-empty persisted content. The LOAD
+          // path already guards emptiness (onLoadDocument only hydrates from db
+          // when the live doc isEmpty); the STORE path did not, so an empty
+          // serialization was written straight over the page, wiping it
+          // silently.
+          //
+          // #251 — the ONE legitimate empty-over-non-empty write is a user who
+          // deliberately clears the page. That intent arrives out-of-band as a
+          // stateless message, NOT from the doc content, which is why it cannot
+          // be spoofed for non-clear writes: the flag is only ever read on this
+          // empty-incoming branch, so the worst a forged signal can do is clear
+          // a page the connection may already edit. The flag was consumed ONCE
+          // before the retry loop (`allowIntentionalClear`) so the decision is
+          // stable across retries; a non-empty store still drops any pending
+          // flag via that same hoisted consume (a "cleared then retyped"
+          // sequence can't leave a usable one behind).
+          const incomingEmpty = isEmptyParagraphDoc(tiptapJson as any);
+          if (
+            incomingEmpty &&
+            page.content &&
+            !isEmptyParagraphDoc(page.content as any)
+          ) {
+            if (allowIntentionalClear) {
+              this.logger.debug(
+                `Intentional clear for ${pageId}: persisting empty doc over ` +
+                  `non-empty content (user-signalled)`,
+              );
+              // fall through — the empty write is allowed exactly once.
+            } else {
+              this.logger.warn(
+                `Skipping store for ${pageId}: empty live doc would overwrite ` +
+                  `non-empty persisted content`,
+              );
+              page = null;
+              return;
+            }
+          }
+
           let contributorIds = undefined;
           try {
             const existingContributors = page.contributorIds || [];
@@ -224,21 +364,30 @@ 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).
-          if (
-            lastUpdatedSource === 'agent' &&
-            page.lastUpdatedSource !== 'agent'
-          ) {
+          // Approach A — boundary snapshot before a MACHINE write overwrites a
+          // human (or other-source) baseline. When this store is from a machine
+          // source — the AGENT or GIT-SYNC — and the page's currently persisted
+          // state was authored by a DIFFERENT source, pin that prior state as its
+          // own history version BEFORE the machine write overwrites it. `page`
+          // still holds the OLD content/provenance here, so saveHistory(page)
+          // captures the pre-write state. The machine's new content is snapshotted
+          // later by the debounced PAGE_HISTORY job.
+          //
+          // For GIT-SYNC this is the OBSERVABLE-LOSS guard (SPEC §9 conflict
+          // contract): a git-sync body write is a block-level 3-way merge whose
+          // same-block rule is "git wins". Without this pin, a concurrent human
+          // edit to a block git also changed would be overwritten with NO trace.
+          // Pinning the pre-merge state here means the human's content is always
+          // RECOVERABLE via page history rather than silently lost — git still
+          // wins the live doc deterministically, but nothing is destroyed.
+          //
+          // Skip if the prior state was already authored by THIS machine source
+          // (boundary already pinned on the transition into it), if the page is
+          // effectively empty, or if the latest existing snapshot already equals
+          // the prior state (avoid duplicates).
+          const isMachineWrite =
+            lastUpdatedSource === 'agent' || lastUpdatedSource === 'git-sync';
+          if (isMachineWrite && page.lastUpdatedSource !== lastUpdatedSource) {
             const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
               pageId,
               { includeContent: true, trx },
@@ -345,6 +494,37 @@ export class PersistenceExtension implements Extension {
     }
   }
 
+  /**
+   * #251 — receive the client's deliberate-clear signal. Records a short-lived,
+   * single-use pending flag for the originating document so the next
+   * onStoreDocument may let one empty-over-non-empty write through the guard.
+   *
+   * Hardening: read-only connections cannot arm the flag, and the document is
+   * taken from the connection (`data.documentName`), never the payload, so a
+   * client cannot target a page it isn't editing. The flag only ever RELAXES
+   * the guard for an empty write (a clear); it can never force or alter a
+   * non-empty write, so it is not a guard bypass for normal content.
+   */
+  async onStateless(data: onStatelessPayload) {
+    const { connection, documentName, payload } = data;
+
+    if (connection?.readOnly) return;
+
+    let message: { type?: string } | undefined;
+    try {
+      message = JSON.parse(payload);
+    } catch {
+      return; // unrelated / malformed stateless message
+    }
+
+    if (message?.type !== INTENTIONAL_CLEAR_MESSAGE_TYPE) return;
+
+    this.intentionalClear.set(
+      documentName,
+      Date.now() + INTENTIONAL_CLEAR_TTL_MS,
+    );
+  }
+
   async onChange(data: onChangePayload) {
     const documentName = data.documentName;
     const userId = data.context?.user?.id;
@@ -368,6 +548,7 @@ export class PersistenceExtension implements Extension {
     const documentName = data.documentName;
     this.contributors.delete(documentName);
     this.agentTouched.delete(documentName);
+    this.intentionalClear.delete(documentName);
   }
 
   private consumeContributors(documentName: string): string[] {
@@ -385,6 +566,18 @@ export class PersistenceExtension implements Extension {
     return touched;
   }
 
+  /**
+   * #251 — read and clear the intentional-clear flag for this document. Returns
+   * true only if a flag was pending AND still within its TTL. Always deletes the
+   * entry so the signal is strictly single-use (one clear → one allowed empty
+   * write); an expired flag is treated as absent (guard still blocks).
+   */
+  private consumeIntentionalClear(documentName: string): boolean {
+    const expiry = this.intentionalClear.get(documentName);
+    this.intentionalClear.delete(documentName);
+    return expiry !== undefined && Date.now() < expiry;
+  }
+
   private async enqueuePageHistory(
     page: Page,
     lastUpdatedSource: string,

apps/server/src/collaboration/extensions/redis-sync/redis-sync.extension.spec.ts

@@ -0,0 +1,208 @@
+// Regression coverage for the custom-event request/reply protocol in the
+// RedisSyncExtension. git-sync routes its body write through a custom event
+// (`gitSyncWriteBody`) which, when the target doc is owned by a DIFFERENT collab
+// instance, runs REMOTELY inside `handleRedisMessage` on the owning instance. The
+// remote handler can THROW (markdown->ProseMirror transform on a malformed body).
+//
+// Before the fix the throw was uncaught: (1) no `customEventComplete` reply was
+// published, so the origin's awaiting promise only rejected after `customEventTTL`
+// (~30s) as a generic 'TIMEOUT', and (2) an unhandledRejection escaped the async
+// `messageBuffer` listener on the owning instance. These tests assert the throw is
+// turned into an error-carrying reply that rejects the origin PROMPTLY with the
+// real message, with the no-throw and local paths unchanged.
+
+import { RedisSyncExtension } from './redis-sync.extension';
+
+type Listener = (channel: Buffer, message: Buffer) => unknown;
+
+// Minimal in-memory pub/sub + lock store shared across FakeRedis duplicates,
+// modelling the two-instance topology (origin + owner) over one Redis.
+class FakeRedisBus {
+  instances: FakeRedis[] = [];
+  locks = new Map<string, string>();
+  published: { channel: string; message: Buffer }[] = [];
+
+  register(inst: FakeRedis) {
+    this.instances.push(inst);
+  }
+
+  publish(channel: string, message: Buffer) {
+    this.published.push({ channel, message });
+    for (const inst of this.instances) {
+      if (!inst.subscribed.has(channel)) continue;
+      for (const listener of inst.messageListeners) {
+        // ioredis delivers async; `void` mirrors the production listener
+        // registration (`sub.on('messageBuffer', ...)`), whose rejection would
+        // surface as an unhandledRejection if the handler did not catch.
+        void listener(Buffer.from(channel), message);
+      }
+    }
+  }
+}
+
+class FakeRedis {
+  subscribed = new Set<string>();
+  messageListeners: Listener[] = [];
+
+  constructor(private bus: FakeRedisBus) {
+    bus.register(this);
+  }
+
+  duplicate() {
+    return new FakeRedis(this.bus);
+  }
+
+  subscribe(...channels: string[]) {
+    for (const c of channels) this.subscribed.add(c);
+    return Promise.resolve();
+  }
+
+  on(event: string, cb: any) {
+    if (event === 'messageBuffer') this.messageListeners.push(cb as Listener);
+    return this;
+  }
+
+  publish(channel: string, message: Buffer) {
+    this.bus.publish(channel, message);
+    return Promise.resolve(1);
+  }
+
+  // Models `SET key val PX ttl NX GET`: only writes when absent (NX); returns the
+  // previous value (GET) so the origin observes the owner already holding the lock.
+  set(key: string, val: string, ...args: any[]) {
+    const hasNX = args.includes('NX');
+    const hasGET = args.includes('GET');
+    const old = this.bus.locks.get(key) ?? null;
+    if (!hasNX || old === null) this.bus.locks.set(key, val);
+    return Promise.resolve(hasGET ? old : 'OK');
+  }
+
+  del(key: string) {
+    this.bus.locks.delete(key);
+    return Promise.resolve(1);
+  }
+
+  disconnect() {}
+}
+
+const pack = (m: any) => Buffer.from(JSON.stringify(m));
+const unpack = (b: Buffer) => JSON.parse(b.toString());
+
+function makeExtension(
+  bus: FakeRedisBus,
+  serverId: string,
+  customEvents: Record<string, (doc: string, payload: any) => Promise<any>>,
+) {
+  const ext = new RedisSyncExtension({
+    redis: new FakeRedis(bus) as any,
+    pack: pack as any,
+    unpack: unpack as any,
+    serverId,
+    customEvents: customEvents as any,
+    customEventTTL: 30_000,
+  });
+  // Doc is NOT loaded on this instance -> handleEvent takes the remote/proxy path.
+  (ext as any).instance = { documents: new Map() };
+  return ext;
+}
+
+describe('RedisSyncExtension custom-event error propagation', () => {
+  let unhandled: unknown[];
+  let onUnhandled: (e: unknown) => void;
+
+  beforeEach(() => {
+    // Fake timers so the 30s TTL fallback timer never fires (and never dangles).
+    jest.useFakeTimers();
+    unhandled = [];
+    onUnhandled = (e) => unhandled.push(e);
+    process.on('unhandledRejection', onUnhandled);
+  });
+
+  afterEach(() => {
+    process.off('unhandledRejection', onUnhandled);
+    jest.useRealTimers();
+  });
+
+  const flush = async () => {
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+  };
+
+  it('owner publishes an error-carrying reply (no unhandledRejection) when the remote handler throws', async () => {
+    const bus = new FakeRedisBus();
+    const owner = makeExtension(bus, 'owner', {
+      boom: async () => {
+        throw new Error('kaboom');
+      },
+    });
+
+    // Drive the remote branch directly, as if the origin's customEventStart arrived.
+    await (owner as any).handleRedisMessage(
+      Buffer.from('collabMsg:owner'),
+      pack({
+        type: 'customEventStart',
+        documentName: 'page.x',
+        eventName: 'boom',
+        payload: {},
+        replyTo: 'collabMsg:origin',
+        replyId: 7,
+      }),
+    );
+    await flush();
+
+    const replies = bus.published
+      .filter((p) => p.channel === 'collabMsg:origin')
+      .map((p) => unpack(p.message));
+    expect(replies).toHaveLength(1);
+    expect(replies[0]).toMatchObject({
+      type: 'customEventComplete',
+      replyId: 7,
+      error: 'kaboom',
+    });
+    expect(unhandled).toHaveLength(0);
+  });
+
+  it('origin rejects PROMPTLY with the real error (not a TTL TIMEOUT) when the remote handler throws', async () => {
+    const bus = new FakeRedisBus();
+    // Owner already holds the document lock.
+    bus.locks.set('collabLock:page.x', 'owner');
+    makeExtension(bus, 'owner', {
+      boom: async () => {
+        throw new Error('kaboom');
+      },
+    });
+    const origin = makeExtension(bus, 'origin', {
+      boom: async () => undefined,
+    });
+
+    const promise = (origin as any).handleEvent('boom', 'page.x', { foo: 1 });
+    // Attach a catch immediately so a rejection is never momentarily unhandled.
+    const settled = promise.then(
+      () => ({ ok: true as const }),
+      (e: unknown) => ({ ok: false as const, error: e }),
+    );
+
+    await flush();
+    // Resolves WITHOUT advancing any timer -> the 30s TIMEOUT fallback did not fire.
+    const result = await settled;
+    expect(result.ok).toBe(false);
+    expect((result as any).error).toBeInstanceOf(Error);
+    expect(((result as any).error as Error).message).toBe('kaboom');
+    expect(unhandled).toHaveLength(0);
+  });
+
+  it('origin resolves with the payload when the remote handler succeeds (unchanged behavior)', async () => {
+    const bus = new FakeRedisBus();
+    bus.locks.set('collabLock:page.x', 'owner');
+    makeExtension(bus, 'owner', {
+      ok: async (_doc: string, payload: any) => ({ echoed: payload }),
+    });
+    const origin = makeExtension(bus, 'origin', {
+      ok: async () => undefined,
+    });
+
+    const promise = (origin as any).handleEvent('ok', 'page.x', { foo: 1 });
+    await flush();
+    await expect(promise).resolves.toEqual({ echoed: { foo: 1 } });
+    expect(unhandled).toHaveLength(0);
+  });
+});

apps/server/src/collaboration/extensions/redis-sync/redis-sync.extension.ts

@@ -51,9 +51,15 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
   private instance!: Hocuspocus;
   private readonly customEvents: TCE;
   private replyIdCounter: number = 0;
-  // @ts-ignore
-  private pendingReplies: Record<number, PromiseWithResolvers<any>['resolve']> =
-    {};
+  private pendingReplies: Record<
+    number,
+    {
+      // @ts-ignore
+      resolve: PromiseWithResolvers<any>['resolve'];
+      // @ts-ignore
+      reject: PromiseWithResolvers<any>['reject'];
+    }
+  > = {};
 
   constructor(configuration: Configuration<TCE>) {
     const {
@@ -176,25 +182,45 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
     }
     if (type === 'customEventStart') {
       const { documentName, eventName, payload, replyTo, replyId } = msg;
-      const res = await this.handleEventLocally(
-        eventName as Extract<keyof TCE, string>,
-        documentName,
-        payload,
-      );
-      const reply: RSAMessageCustomEventComplete = {
-        type: 'customEventComplete',
-        replyId,
-        payload: res,
-      };
+      let reply: RSAMessageCustomEventComplete;
+      try {
+        const res = await this.handleEventLocally(
+          eventName as Extract<keyof TCE, string>,
+          documentName,
+          payload,
+        );
+        reply = {
+          type: 'customEventComplete',
+          replyId,
+          payload: res,
+        };
+      } catch (err) {
+        // The remote handler threw (e.g. the markdown->ProseMirror transform in
+        // gitSyncWriteBody can throw on a malformed body). Reply with the error on
+        // the SAME correlation channel so the origin rejects promptly with the real
+        // message instead of waiting out customEventTTL as a generic 'TIMEOUT'.
+        // Catching here also keeps the throw from escaping this async messageBuffer
+        // listener as an unhandledRejection on the owning instance.
+        reply = {
+          type: 'customEventComplete',
+          replyId,
+          payload: undefined,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
       this.pub.publish(`${replyTo}`, this.pack(reply));
       return;
     }
     if (type === 'customEventComplete') {
-      const { replyId, payload } = msg;
-      const resolveFn = this.pendingReplies[replyId];
-      if (!resolveFn) return;
+      const { replyId, payload, error } = msg;
+      const pending = this.pendingReplies[replyId];
+      if (!pending) return;
       delete this.pendingReplies[replyId];
-      resolveFn(payload);
+      if (error !== undefined) {
+        pending.reject(new Error(error));
+      } else {
+        pending.resolve(payload);
+      }
       return;
     }
     const { socketId } = msg;
@@ -273,11 +299,22 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
       };
       const msg = this.pack(proxyMessage);
       this.pub.publish(`${this.msgChannel}:${proxyTo}`, msg);
-      // @ts-ignore
-      const { promise, resolve, reject } = Promise.withResolvers();
-      this.pendingReplies[replyId] = resolve;
+      // Manual deferred (no Promise.withResolvers) so this runs on Node < 22 too.
+      let resolve!: (v: unknown) => void;
+      let reject!: (e: unknown) => void;
+      const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+      this.pendingReplies[replyId] = { resolve, reject };
       setTimeout(() => {
-        reject('TIMEOUT');
+        // Fallback for a genuinely lost reply. A handler that threw now rejects
+        // promptly via the error-carrying customEventComplete above; this TIMEOUT
+        // only fires when no reply ever comes back.
+        if (this.pendingReplies[replyId]) {
+          delete this.pendingReplies[replyId];
+          reject('TIMEOUT');
+        }
       }, this.customEventTTL);
       return promise as Promise<ReturnType<TCE[TName]>>;
     }

apps/server/src/collaboration/extensions/redis-sync/redis-sync.types.ts

@@ -72,6 +72,10 @@ export type RSAMessageCustomEventComplete = {
   type: 'customEventComplete';
   replyId: number;
   payload: unknown;
+  // When the remote handler THREW, the owner sends back the error message here
+  // instead of a payload, so the origin can reject its awaiting promise promptly
+  // (with the real error) rather than waiting out the customEventTTL timeout.
+  error?: string;
 };
 
 export type RSAMessage =

apps/server/src/collaboration/git-sync-converter-gate.spec.ts

@@ -0,0 +1,535 @@
+/**
+ * JEST CONFIG NOTE (#119 ESM refactor): this is the one spec that needs the REAL
+ * `@docmost/git-sync` converter (not a mock). The package is now ESM, which jest
+ * cannot `require()` nor `import()` without --experimental-vm-modules, so the
+ * server jest config `moduleNameMapper`s `@docmost/git-sync` to its TS SOURCE and
+ * strips the ESM `.js` import suffixes. ts-jest then type-checks that source under
+ * the server's (looser) tsconfig and trips a benign narrowing; the global
+ * `isolatedModules: true` on the ts-jest transform (apps/server/package.json)
+ * makes it transpile-only so this spec loads. Full type-checking of the package
+ * is still enforced by its own `tsc`/vitest gates and the server `tsc --noEmit`.
+ *
+ * §13.1 IDEMPOTENCY GATE — the blocking gate for git-sync Phase B.
+ *
+ * Proves the `@docmost/git-sync` pure converter is schema-compatible
+ * with the server's REAL editor-ext document schema: a representative corpus of
+ * editor-ext ProseMirror documents must survive a full round trip through the
+ * actual server write path without losing any node / mark / attribute.
+ *
+ * Pipeline per document (issue #194 §13.1):
+ *   1. md   = convertProseMirrorToMarkdown(content)          // git-sync export
+ *   2. doc  = await markdownToProseMirror(md)                // git-sync import
+ *   3. push `doc` through the REAL editor-ext Yjs write path the server uses:
+ *        ydoc       = TiptapTransformer.toYdoc(doc, 'default', tiptapExtensions)
+ *        normalized = TiptapTransformer.fromYdoc(ydoc, 'default')
+ *      This is exactly what PersistenceExtension does on store
+ *      (apps/server/src/collaboration/extensions/persistence.extension.ts:96/115)
+ *      with the same `tiptapExtensions` (collaboration.util.ts) and the same
+ *      `@hocuspocus/transformer`, so the gate exercises the real schema
+ *      validation that runs on a git-sync write (issue #194 §3.3).
+ *   4. assert docsCanonicallyEqual(canon(original), canon(normalized)) === true
+ *
+ * Any node / mark / attr that editor-ext drops (because the git-sync
+ * docmost-schema named it differently, or declares a different default) makes
+ * the gate FAIL for that document — exactly the schema-divergence issue #194 §3.3 /
+ * §13.1 warn about. Genuine, irreducible divergences are isolated into the
+ * clearly-named `KNOWN DIVERGENCE` block at the bottom (never silently hidden).
+ *
+ * Requires the workspace packages built first:
+ *   pnpm --filter @docmost/editor-ext build
+ *   pnpm --filter @docmost/git-sync  build
+ */
+import { TiptapTransformer } from '@hocuspocus/transformer';
+// Import the server's real schema FIRST so `@docmost/editor-ext` resolves to its
+// built CJS `dist` (its `main`). The ESM-only `@docmost/git-sync` package is
+// mapped to its TS SOURCE by the jest `moduleNameMapper` (the built ESM cannot
+// be `require()`d nor dynamically `import()`ed under jest's node VM), so ts-jest
+// transpiles the real converter to CJS here — exercising the actual converter
+// the server ships, not a stub.
+import { tiptapExtensions } from './collaboration.util';
+import {
+  convertProseMirrorToMarkdown,
+  markdownToProseMirror,
+  canonicalizeContent,
+  docsCanonicallyEqual,
+} from '@docmost/git-sync';
+
+/**
+ * Run a single editor-ext document through the full gate pipeline and return
+ * the canonical original vs the canonical doc as it lands after the real Yjs
+ * write path, plus the intermediate markdown for diagnostics.
+ */
+async function runGate(original: any): Promise<{
+  md: string;
+  imported: any;
+  normalized: any;
+  canonOriginal: any;
+  canonNormalized: any;
+}> {
+  // 1) editor-ext JSON -> markdown (git-sync export).
+  const md = convertProseMirrorToMarkdown(original);
+
+  // 2) markdown -> ProseMirror JSON (git-sync import, docmost-schema).
+  const imported = await markdownToProseMirror(md);
+
+  // 3) push through the REAL editor-ext schema via the server's Yjs write path.
+  //    toYdoc validates `imported` against tiptapExtensions (throws on an
+  //    unknown node, drops unknown attrs); fromYdoc reads it back as the
+  //    normalized editor-ext JSON the server would persist.
+  const ydoc = TiptapTransformer.toYdoc(imported, 'default', tiptapExtensions);
+  const normalized = TiptapTransformer.fromYdoc(ydoc, 'default');
+
+  return {
+    md,
+    imported,
+    normalized,
+    canonOriginal: canonicalizeContent(original),
+    canonNormalized: canonicalizeContent(normalized),
+  };
+}
+
+const doc = (...content: any[]) => ({ type: 'doc', content });
+const text = (t: string, marks?: any[]) =>
+  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
+const para = (...content: any[]) => ({ type: 'paragraph', content });
+
+// ---------------------------------------------------------------------------
+// Corpus: editor-ext ProseMirror documents covering the common node/mark types.
+// Node / mark / attr names and DEFAULTS are taken from the real schema —
+// editor-ext (packages/editor-ext/src) + the server's tiptapExtensions
+// (collaboration.util.ts) — NOT guessed. Where editor-ext materializes a
+// non-null default on import (e.g. image.align="center", callout.type, list
+// start) the fixture pre-authors that materialized value so the round trip is
+// already at its fixpoint (matches how the engine normalizes-on-write, SPEC §11).
+// ---------------------------------------------------------------------------
+const CORPUS: Record<string, any> = {
+  'paragraphs + headings (h1-h3)': doc(
+    { type: 'heading', attrs: { level: 1 }, content: [text('Heading one')] },
+    { type: 'heading', attrs: { level: 2 }, content: [text('Heading two')] },
+    { type: 'heading', attrs: { level: 3 }, content: [text('Heading three')] },
+    para(text('A plain paragraph of text.')),
+    para(text('Second paragraph.')),
+  ),
+
+  'inline marks (bold/italic/strike/code)': doc(
+    para(
+      text('normal '),
+      text('bold', [{ type: 'bold' }]),
+      text(' '),
+      text('italic', [{ type: 'italic' }]),
+      text(' '),
+      text('struck', [{ type: 'strike' }]),
+      text(' '),
+      text('code', [{ type: 'code' }]),
+    ),
+  ),
+
+  'links': doc(
+    para(
+      text('see '),
+      text('the site', [
+        { type: 'link', attrs: { href: 'https://example.com' } },
+      ]),
+      text(' for more'),
+    ),
+  ),
+
+  'bullet list': doc({
+    type: 'bulletList',
+    content: [
+      { type: 'listItem', content: [para(text('first'))] },
+      { type: 'listItem', content: [para(text('second'))] },
+      { type: 'listItem', content: [para(text('third'))] },
+    ],
+  }),
+
+  'ordered list': doc({
+    type: 'orderedList',
+    attrs: { start: 1 },
+    content: [
+      { type: 'listItem', content: [para(text('one'))] },
+      { type: 'listItem', content: [para(text('two'))] },
+    ],
+  }),
+
+  'task list (checkbox)': doc({
+    type: 'taskList',
+    content: [
+      {
+        type: 'taskItem',
+        attrs: { checked: true },
+        content: [para(text('done item'))],
+      },
+      {
+        type: 'taskItem',
+        attrs: { checked: false },
+        content: [para(text('todo item'))],
+      },
+    ],
+  }),
+
+  'blockquote': doc({
+    type: 'blockquote',
+    content: [para(text('a quoted line')), para(text('second quoted line'))],
+  }),
+
+  'callout (info)': doc({
+    type: 'callout',
+    attrs: { type: 'info' },
+    content: [para(text('an informational callout'))],
+  }),
+
+  'callout (warning)': doc({
+    type: 'callout',
+    attrs: { type: 'warning' },
+    content: [para(text('a warning callout'))],
+  }),
+
+  'code block (with language)': doc({
+    type: 'codeBlock',
+    attrs: { language: 'typescript' },
+    // A fenced code block's body is stored with a trailing newline (the form a
+    // markdown ``` fence round-trips to: marked normalizes the code text to end
+    // in "\n"). Authoring the fixture at that fixpoint mirrors how the engine
+    // normalizes-on-write (SPEC §11): codeBlock + `language` round-trip exactly.
+    content: [text('const a: number = 1;\nconsole.log(a);\n')],
+  }),
+
+  'horizontal rule': doc(
+    para(text('before')),
+    { type: 'horizontalRule' },
+    para(text('after')),
+  ),
+
+  'table (header row + cells)': doc({
+    type: 'table',
+    content: [
+      {
+        type: 'tableRow',
+        content: [
+          {
+            type: 'tableHeader',
+            attrs: { colspan: 1, rowspan: 1, colwidth: null },
+            content: [para(text('Name'))],
+          },
+          {
+            type: 'tableHeader',
+            attrs: { colspan: 1, rowspan: 1, colwidth: null },
+            content: [para(text('Value'))],
+          },
+        ],
+      },
+      {
+        type: 'tableRow',
+        content: [
+          {
+            type: 'tableCell',
+            attrs: { colspan: 1, rowspan: 1, colwidth: null },
+            content: [para(text('alpha'))],
+          },
+          {
+            type: 'tableCell',
+            attrs: { colspan: 1, rowspan: 1, colwidth: null },
+            content: [para(text('1'))],
+          },
+        ],
+      },
+    ],
+  }),
+
+  // --- editor-ext nodes/marks beyond the original corpus (item #7) ----------
+  // Each of these was verified to round-trip CLEANLY through the real gate
+  // (export -> markdown -> import -> editor-ext Yjs write path). Fixtures are
+  // pre-authored at the engine's normalize-on-write fixpoint (SPEC §11), e.g.
+  // details carries the materialized `open:false`, and color marks use the
+  // `rgb(...)` form the HTML re-parser normalizes to.
+
+  'mention (user)': doc(
+    para(
+      text('hi '),
+      {
+        type: 'mention',
+        attrs: {
+          id: 'user-123',
+          label: 'Alice',
+          entityType: 'user',
+          entityId: 'user-123',
+          creatorId: 'creator-1',
+        },
+      },
+      text(' there'),
+    ),
+  ),
+
+  'inline math': doc(
+    para(
+      text('inline '),
+      { type: 'mathInline', attrs: { text: 'x^2' } },
+      text(' math'),
+    ),
+  ),
+
+  'block math': doc({ type: 'mathBlock', attrs: { text: 'x^2 + y^2 = z^2' } }),
+
+  'details (collapsible)': doc({
+    type: 'details',
+    // `open:false` is the value editor-ext materializes on import; pre-authoring
+    // it puts the fixture at its round-trip fixpoint.
+    attrs: { open: false },
+    content: [
+      { type: 'detailsSummary', content: [text('Summary line')] },
+      { type: 'detailsContent', content: [para(text('hidden body'))] },
+    ],
+  }),
+
+  'highlight (mark, no color)': doc(
+    para(
+      text('a '),
+      text('highlighted', [{ type: 'highlight' }]),
+      text(' word'),
+    ),
+  ),
+
+  'highlight (mark, with color)': doc(
+    para(
+      text('a '),
+      text('red', [{ type: 'highlight', attrs: { color: 'rgb(255, 0, 0)' } }]),
+      text(' word'),
+    ),
+  ),
+
+  'subscript': doc(
+    para(text('H'), text('2', [{ type: 'subscript' }]), text('O')),
+  ),
+
+  'superscript': doc(
+    para(text('E=mc'), text('2', [{ type: 'superscript' }])),
+  ),
+
+  'text color (textStyle)': doc(
+    // The HTML re-parser normalizes CSS colors to the `rgb(...)` form, so the
+    // fixture pre-authors that form; a `#hex` color would round-trip to the
+    // equivalent rgb() and is therefore a value-normalization divergence (see
+    // the KNOWN DIVERGENCE block below).
+    para(text('green', [{ type: 'textStyle', attrs: { color: 'rgb(0, 255, 0)' } }])),
+  ),
+
+  'nested / mixed document': doc(
+    { type: 'heading', attrs: { level: 1 }, content: [text('Mixed')] },
+    para(
+      text('intro with '),
+      text('bold', [{ type: 'bold' }]),
+      text(' and a '),
+      text('link', [{ type: 'link', attrs: { href: 'https://example.com' } }]),
+      text('.'),
+    ),
+    {
+      type: 'bulletList',
+      content: [
+        {
+          type: 'listItem',
+          content: [
+            para(text('item with '), text('code', [{ type: 'code' }])),
+          ],
+        },
+        {
+          type: 'listItem',
+          content: [
+            para(text('item with sublist')),
+            {
+              type: 'bulletList',
+              content: [
+                { type: 'listItem', content: [para(text('nested a'))] },
+                { type: 'listItem', content: [para(text('nested b'))] },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+    {
+      type: 'callout',
+      attrs: { type: 'success' },
+      content: [
+        para(text('callout body')),
+        { type: 'codeBlock', attrs: { language: 'bash' }, content: [text('echo hi\n')] },
+      ],
+    },
+    {
+      type: 'blockquote',
+      content: [para(text('quote at the end'))],
+    },
+  ),
+
+  // Atom embeds that carry no inline text: they must round-trip via their
+  // schema-matching HTML (data-type div), NOT a literal that re-imports as plain
+  // text. `subpages` used to export as the literal "{{SUBPAGES}}" and came back
+  // as visible text on the page (red-team round-trip data loss) — this locks it.
+  // editor-ext materializes the `recursive: false` default on import, so the
+  // fixture pre-authors it to sit at the round-trip fixpoint (matches the other
+  // default-materializing fixtures above).
+  'subpages embed': doc({ type: 'subpages', attrs: { recursive: false } }),
+};
+
+describe('git-sync converter §13.1 idempotency gate (editor-ext schema)', () => {
+  for (const [name, original] of Object.entries(CORPUS)) {
+    it(`round-trips losslessly: ${name}`, async () => {
+      const { md, canonOriginal, canonNormalized } = await runGate(original);
+
+      const equal = docsCanonicallyEqual(original, canonNormalized);
+      if (!equal) {
+        // Surface a readable diff so a real divergence is actionable.
+        // eslint-disable-next-line no-console
+        console.error(
+          `\n[GATE FAIL] ${name}\n--- markdown ---\n${md}\n` +
+            `--- canonical original ---\n${JSON.stringify(canonOriginal, null, 2)}\n` +
+            `--- canonical round-tripped ---\n${JSON.stringify(canonNormalized, null, 2)}\n`,
+        );
+      }
+      expect(equal).toBe(true);
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// KNOWN DIVERGENCE — images (isolated so it does NOT silently weaken the gate).
+//
+// This is NOT a schema-name divergence: the `image` NODE itself round-trips
+// through editor-ext fine (it survives toYdoc under the real tiptapExtensions).
+// The loss is intrinsic to MARKDOWN, the on-disk transport format git-sync uses:
+//
+//   1. `convertProseMirrorToMarkdown` emits a standard `![alt](src)` image
+//      (markdown-converter.ts case "image"). Standard markdown image syntax has
+//      no way to express `width` / `height` / `align`, so those attrs are
+//      DROPPED on export and cannot be recovered on import.
+//   2. A block-level image is hoisted out of its line by the HTML re-parser,
+//      leaving a leading EMPTY paragraph (the same block-image-hoist limitation
+//      documented in packages/git-sync/test/fixtures/known-limitations).
+//
+// The gate documents the EXACT lossy shape below. If the converter is ever
+// taught to preserve image dimensions (e.g. by emitting an HTML <img> with
+// data-* attrs, as it already does for video/diagrams), these assertions flip
+// and the image fixture should be promoted into the green CORPUS above.
+// ---------------------------------------------------------------------------
+describe('git-sync converter §13.1 image dimensions preserved (was KNOWN DIVERGENCE)', () => {
+  const imageDoc = doc({
+    type: 'image',
+    attrs: {
+      src: 'https://example.com/pic.png',
+      width: 640,
+      height: 480,
+      align: 'center',
+    },
+  });
+
+  it('preserves width/height/align by exporting an HTML <img> (PR #119 round-trip fix)', async () => {
+    const { md, canonNormalized } = await runGate(imageDoc);
+
+    // A top-level image carrying layout attrs is now exported as a schema-
+    // matching HTML <img> (the same path video/diagrams already use), so the
+    // dimensions and alignment survive the round trip instead of collapsing to
+    // bare `![](src)`.
+    expect(md.trim()).toBe(
+      '<img src="https://example.com/pic.png" width="640" height="480" align="center">',
+    );
+
+    // The round-tripped image keeps src + the layout attrs. width/height are
+    // re-imported as strings (matching the video/audio/pdf string convention),
+    // so assert the values rather than the JS type.
+    const imgAttrs = (canonNormalized as any).content[0].attrs;
+    expect((canonNormalized as any).content[0].type).toBe('image');
+    expect(imgAttrs.src).toBe('https://example.com/pic.png');
+    expect(imgAttrs.align).toBe('center');
+    expect(String(imgAttrs.width)).toBe('640');
+    expect(String(imgAttrs.height)).toBe('480');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// KNOWN DIVERGENCE — text alignment (item #7; isolated, not silently dropped).
+//
+// editor-ext registers TextAlign for heading+paragraph, and the SERVER schema
+// fully supports it — the loss is intrinsic to the MARKDOWN transport:
+//
+//   • A paragraph's `textAlign` is EXPORTED as `<div align="...">text</div>`
+//     (markdown-converter case "paragraph"), but on import the converter's
+//     docmost-schema declares `textAlign` WITHOUT a parseHTML mapping, so the
+//     `align` attribute is never recovered -> it imports as `textAlign:null`
+//     and canonicalizes away. A heading's alignment is not even exported.
+//   • Therefore any non-default alignment is dropped on a full round trip.
+//
+// If the converter is ever taught to parse `align`/`text-align` back onto the
+// block, this assertion flips and an aligned-paragraph fixture should be
+// promoted into the green CORPUS above.
+// ---------------------------------------------------------------------------
+describe('git-sync converter §13.1 KNOWN DIVERGENCE (text alignment dropped)', () => {
+  it('drops a paragraph textAlign on the markdown round trip', async () => {
+    const alignedDoc = doc({
+      type: 'paragraph',
+      attrs: { textAlign: 'center' },
+      content: [text('centered')],
+    });
+
+    const { canonNormalized } = await runGate(alignedDoc);
+
+    // The round-tripped paragraph carries no alignment.
+    expect(canonNormalized).toEqual({
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'centered' }] }],
+    });
+    expect(docsCanonicallyEqual(alignedDoc, canonNormalized)).toBe(false);
+  });
+
+  it('drops a heading textAlign (headings do not export alignment at all)', async () => {
+    const alignedHeading = doc({
+      type: 'heading',
+      attrs: { level: 2, textAlign: 'center' },
+      content: [text('centered heading')],
+    });
+
+    const { md, canonNormalized } = await runGate(alignedHeading);
+
+    // Export is a plain markdown heading — no alignment syntax.
+    expect(md.trim()).toBe('## centered heading');
+    expect(docsCanonicallyEqual(alignedHeading, canonNormalized)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// KNOWN DIVERGENCE — textStyle color is VALUE-NORMALIZED, not lost (item #7).
+//
+// The textStyle/color mark itself round-trips (the green CORPUS has the rgb()
+// form). But a `#hex` color is normalized to the equivalent `rgb(...)` string
+// by the HTML re-parser on import, and canonicalize.ts does NOT normalize color
+// formats — so a `#hex` original is not STRING-identical to its round trip even
+// though the color is semantically preserved. Locked here so the boundary is
+// explicit: author color fixtures in rgb() form to stay in the green corpus.
+// ---------------------------------------------------------------------------
+describe('git-sync converter §13.1 KNOWN DIVERGENCE (textStyle color #hex -> rgb)', () => {
+  it('normalizes a #hex text color to rgb() (semantically preserved, string-divergent)', async () => {
+    const hexDoc = doc(
+      para(text('green', [{ type: 'textStyle', attrs: { color: '#00ff00' } }])),
+    );
+
+    const { canonNormalized } = await runGate(hexDoc);
+
+    // Color survives, but as the normalized rgb() string.
+    expect(canonNormalized).toEqual({
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            {
+              type: 'text',
+              text: 'green',
+              marks: [{ type: 'textStyle', attrs: { color: 'rgb(0, 255, 0)' } }],
+            },
+          ],
+        },
+      ],
+    });
+    // Not string-identical to the #hex original.
+    expect(docsCanonicallyEqual(hexDoc, canonNormalized)).toBe(false);
+  });
+});

apps/server/src/collaboration/merge/lcs.ts

@@ -0,0 +1,26 @@
+/**
+ * Backward-filled LCS length table for sequences `a` and `b`: `dp[i][j]` is the
+ * length of the longest common subsequence of the suffixes `a[i:]` and `b[j:]`.
+ * O(n*m) time/space — fine for page block counts.
+ *
+ * Shared by the two-way block diff (`yjs-body-merge.diffBlocks`) and the
+ * three-way merge planner (`three-way-merge.lcsPairs`) so the (identical) table
+ * construction lives in ONE place; each caller does its own traceback over the
+ * returned table.
+ */
+export function buildLcsTable(a: string[], b: string[]): number[][] {
+  const n = a.length;
+  const m = b.length;
+  const dp: number[][] = Array.from({ length: n + 1 }, () =>
+    new Array(m + 1).fill(0),
+  );
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[i][j] =
+        a[i] === b[j]
+          ? dp[i + 1][j + 1] + 1
+          : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    }
+  }
+  return dp;
+}

apps/server/src/collaboration/merge/redteam-three-way.spec.ts

@@ -0,0 +1,20 @@
+import { diff3Plan, type Pick } from './three-way-merge';
+
+// Materialize a plan into the merged key sequence for assertion.
+function apply(plan: Pick[], live: string[], target: string[]): string[] {
+  return plan.map((p) => (p.src === 'live' ? live[p.index] : target[p.index]));
+}
+
+const merge = (o: string[], a: string[], b: string[]): string[] =>
+  apply(diff3Plan(o, a, b), a, b);
+
+describe('diff3Plan red-team #9 (human edit + adjacent git insert)', () => {
+  it('keeps human block-2 edit AND applies git insert of 2.5', () => {
+    // base:   1 2 3
+    // live:   1 H 3   (human rewrote block 2)
+    // target: 1 2 2.5 3 (git inserted 2.5 after block 2)
+    expect(
+      merge(['1', '2', '3'], ['1', 'H', '3'], ['1', '2', '2.5', '3']),
+    ).toEqual(['1', 'H', '2.5', '3']);
+  });
+});

apps/server/src/collaboration/merge/three-way-merge.spec.ts

@@ -0,0 +1,159 @@
+import {
+  diff3Plan,
+  diff3PlanWithConflicts,
+  type Pick,
+} from './three-way-merge';
+
+// Materialize a plan into the merged key sequence for assertion.
+function apply(plan: Pick[], live: string[], target: string[]): string[] {
+  return plan.map((p) => (p.src === 'live' ? live[p.index] : target[p.index]));
+}
+
+const merge = (o: string[], a: string[], b: string[]): string[] =>
+  apply(diff3Plan(o, a, b), a, b);
+
+describe('diff3Plan (block-level three-way merge)', () => {
+  it('identical on all three sides -> unchanged (all from live)', () => {
+    const plan = diff3Plan(['1', '2', '3'], ['1', '2', '3'], ['1', '2', '3']);
+    expect(plan.every((p) => p.src === 'live')).toBe(true);
+    expect(apply(plan, ['1', '2', '3'], ['1', '2', '3'])).toEqual(['1', '2', '3']);
+  });
+
+  it('git changed a block the human did not -> takes git', () => {
+    expect(merge(['1', '2', '3'], ['1', '2', '3'], ['1', '9', '3'])).toEqual([
+      '1',
+      '9',
+      '3',
+    ]);
+  });
+
+  it('human changed a block git did not -> KEEPS the human edit (the core 3-way win)', () => {
+    expect(merge(['1', '2', '3'], ['1', 'H', '3'], ['1', '2', '3'])).toEqual([
+      '1',
+      'H',
+      '3',
+    ]);
+  });
+
+  // Bug #2 observability: diff3PlanWithConflicts reports SAME-BLOCK conflicts so
+  // the caller can surface the "git wins" loss (log + history pin) instead of
+  // dropping the human side silently.
+  describe('diff3PlanWithConflicts (same-block conflict reporting)', () => {
+    it('reports 0 conflicts when sides changed DIFFERENT blocks (clean merge)', () => {
+      const r = diff3PlanWithConflicts(
+        ['1', '2', '3'],
+        ['H', '2', '3'],
+        ['1', '2', 'G'],
+      );
+      expect(r.conflicts).toBe(0);
+      expect(apply(r.picks, ['H', '2', '3'], ['1', '2', 'G'])).toEqual([
+        'H',
+        '2',
+        'G',
+      ]);
+    });
+
+    it('reports 1 conflict and git wins when BOTH rewrote the SAME block', () => {
+      const r = diff3PlanWithConflicts(
+        ['1', '2', '3'],
+        ['1', 'H', '3'], // human rewrote block 2
+        ['1', 'G', '3'], // git rewrote block 2
+      );
+      expect(r.conflicts).toBe(1);
+      // Git wins the contested block; the human 'H' is NOT in the picks.
+      expect(apply(r.picks, ['1', 'H', '3'], ['1', 'G', '3'])).toEqual([
+        '1',
+        'G',
+        '3',
+      ]);
+    });
+
+    it('does NOT count a git-only region (no human content to lose) as a conflict', () => {
+      const r = diff3PlanWithConflicts(
+        ['1', '2', '3'],
+        ['1', '2', '3'], // human unchanged
+        ['1', '9', '3'], // git rewrote block 2
+      );
+      expect(r.conflicts).toBe(0);
+    });
+  });
+
+  it('human and git changed DIFFERENT blocks -> both preserved', () => {
+    // human rewrote block 1, git rewrote block 3.
+    expect(merge(['1', '2', '3'], ['H', '2', '3'], ['1', '2', 'G'])).toEqual([
+      'H',
+      '2',
+      'G',
+    ]);
+  });
+
+  it('human inserted a block AND git changed a different block -> both preserved', () => {
+    expect(
+      merge(['1', '2', '3'], ['1', '1.5', '2', '3'], ['1', '2', 'G']),
+    ).toEqual(['1', '1.5', '2', 'G']);
+  });
+
+  it('both changed the SAME block -> conflict resolves to git', () => {
+    expect(merge(['1', '2', '3'], ['1', 'H', '3'], ['1', 'G', '3'])).toEqual([
+      '1',
+      'G',
+      '3',
+    ]);
+  });
+
+  it('both made the SAME edit -> that edit (no duplication)', () => {
+    expect(merge(['1', '2', '3'], ['1', 'X', '3'], ['1', 'X', '3'])).toEqual([
+      '1',
+      'X',
+      '3',
+    ]);
+  });
+
+  it('human deleted a block git left alone -> deletion preserved', () => {
+    expect(merge(['1', '2', '3'], ['1', '3'], ['1', '2', '3'])).toEqual([
+      '1',
+      '3',
+    ]);
+  });
+
+  it('git deleted a block the human left alone -> deletion applied', () => {
+    expect(merge(['1', '2', '3'], ['1', '2', '3'], ['1', '3'])).toEqual([
+      '1',
+      '3',
+    ]);
+  });
+
+  it('both deleted the same block -> gone (no conflict)', () => {
+    expect(merge(['1', '2', '3'], ['1', '3'], ['1', '3'])).toEqual(['1', '3']);
+  });
+
+  it('git appended a trailing block -> appended', () => {
+    expect(merge(['1', '2'], ['1', '2'], ['1', '2', '3'])).toEqual([
+      '1',
+      '2',
+      '3',
+    ]);
+  });
+
+  it('human appended a trailing block git did not -> kept', () => {
+    expect(merge(['1', '2'], ['1', '2', '3'], ['1', '2'])).toEqual([
+      '1',
+      '2',
+      '3',
+    ]);
+  });
+
+  it('empty base, git provides content (brand-new page body) -> git content', () => {
+    expect(merge([], [], ['1', '2'])).toEqual(['1', '2']);
+  });
+
+  it('git changed block 1, human edited block 3, far apart -> both kept', () => {
+    expect(
+      merge(
+        ['a', 'b', 'c', 'd', 'e'],
+        ['a', 'b', 'c', 'd', 'E'],
+        ['A', 'b', 'c', 'd', 'e'],
+      ),
+    ).toEqual(['A', 'b', 'c', 'd', 'E']);
+  });
+});

apps/server/src/collaboration/merge/three-way-merge.ts

@@ -0,0 +1,274 @@
+/**
+ * Pure block-level THREE-WAY merge planner (diff3) over arrays of opaque block
+ * keys. Used by the git-sync body write to merge an incoming git body into the
+ * live page using the last-synced version as the common ancestor (review #5):
+ *
+ *   - a block only the human changed (live != base, git == base) -> keep LIVE
+ *   - a block only git changed       (git != base, live == base) -> take GIT
+ *   - a block both sides changed (a real conflict)               -> GIT wins
+ *   - inserts/deletes from either side are preserved when unambiguous
+ *
+ * Content-agnostic: it works on string keys and returns the merged block order as
+ * picks ({ src: 'live'|'target', index }) — the caller (the Yjs applier)
+ * materializes them — so the whole algorithm is unit-testable on plain arrays.
+ *
+ * Algorithm: anchor on base blocks present (unchanged) in BOTH live and target
+ * (their LCS-with-base intersection). Between consecutive anchors lies one region
+ * the human and/or git rewrote; resolve each region three-way. Stable anchor
+ * blocks are emitted from LIVE so the applier keeps the existing Yjs block
+ * instances (and the human's in-flight edits) in place.
+ *
+ * LOCATION (deferred): this and its `lcs.ts` sibling are pure, framework-free and
+ * could conceptually live in `packages/git-sync` (the engine). They are kept in
+ * the server integration on purpose: `packages/git-sync` is a VENDORED engine
+ * (pinned upstream, manually re-synced), so adding first-party files there
+ * complicates the re-sync story, and the only consumer today is the server. Move
+ * them into the engine only once the vendoring re-sync story is settled.
+ */
+
+import { buildLcsTable } from './lcs';
+
+/** Matched index pairs of the longest common subsequence of `a` and `b`. */
+function lcsPairs(a: string[], b: string[]): Array<[number, number]> {
+  const n = a.length;
+  const m = b.length;
+  const dp = buildLcsTable(a, b);
+  const pairs: Array<[number, number]> = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      pairs.push([i, j]);
+      i++;
+      j++;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      i++;
+    } else {
+      j++;
+    }
+  }
+  return pairs;
+}
+
+/** o-index -> matched index in the other side (only for LCS-matched blocks). */
+function matchMap(pairs: Array<[number, number]>): Map<number, number> {
+  const m = new Map<number, number>();
+  for (const [o, x] of pairs) m.set(o, x);
+  return m;
+}
+
+/**
+ * One change `side` made to `base` within a region: base blocks `[oStart,oEnd)`
+ * were replaced by the side's blocks listed in `content` (region-local indices).
+ * A pure insert has `oStart === oEnd`; a pure delete has empty `content`.
+ */
+interface Hunk {
+  oStart: number;
+  oEnd: number;
+  content: number[];
+}
+
+/**
+ * Diff `o` against one side as a list of non-overlapping hunks (the base spans
+ * the side rewrote/inserted/deleted), derived from their LCS alignment.
+ */
+function buildHunks(o: string[], side: string[]): Hunk[] {
+  const pairs = lcsPairs(o, side); // [oIdx, sideIdx] kept (unchanged) blocks
+  const hunks: Hunk[] = [];
+  let prevO = -1;
+  let prevS = -1;
+  const flush = (curO: number, curS: number): void => {
+    const oStart = prevO + 1;
+    const oEnd = curO;
+    const content: number[] = [];
+    for (let s = prevS + 1; s < curS; s++) content.push(s);
+    if (oEnd > oStart || content.length > 0) hunks.push({ oStart, oEnd, content });
+  };
+  for (const [oIdx, sIdx] of pairs) {
+    flush(oIdx, sIdx);
+    prevO = oIdx;
+    prevS = sIdx;
+  }
+  flush(o.length, side.length);
+  return hunks;
+}
+
+/**
+ * Do two hunks (one per side) touch the same base region? Pure inserts only
+ * collide when nested strictly inside the other hunk's base span (or, for two
+ * inserts, at the same gap); changes sitting at a shared boundary do not.
+ */
+function hunksOverlap(a: Hunk, b: Hunk): boolean {
+  const aIns = a.oStart === a.oEnd;
+  const bIns = b.oStart === b.oEnd;
+  if (aIns && bIns) return a.oStart === b.oStart;
+  if (aIns) return b.oStart < a.oStart && a.oStart < b.oEnd;
+  if (bIns) return a.oStart < b.oStart && b.oStart < a.oEnd;
+  return Math.max(a.oStart, b.oStart) < Math.min(a.oEnd, b.oEnd);
+}
+
+interface LocalPick {
+  src: 'live' | 'target';
+  local: number;
+}
+
+/**
+ * Fine-grained three-way merge of ONE inter-anchor region. Combines the human's
+ * and git's NON-overlapping hunks (e.g. a human edit to one block plus a git
+ * insert/delete of OTHER blocks in the same region) so neither change is lost.
+ * Returns the merged region as region-local picks, or `null` when the two sides
+ * changed the SAME base block — a genuine conflict the caller resolves by the
+ * original all-or-nothing rule (git wins the whole region).
+ */
+function tryMergeRegion(
+  o: string[],
+  a: string[],
+  b: string[],
+): LocalPick[] | null {
+  const aHunks = buildHunks(o, a);
+  const bHunks = buildHunks(o, b);
+
+  // Any overlap between a human hunk and a git hunk is a real conflict; bail so
+  // the caller falls back to git-wins (preserving the original behavior).
+  for (const ah of aHunks) {
+    for (const bh of bHunks) {
+      if (hunksOverlap(ah, bh)) return null;
+    }
+  }
+
+  // Disjoint: live index of each base block that BOTH sides kept (stable).
+  const aKept = matchMap(lcsPairs(o, a)); // base index -> live index
+
+  const out: LocalPick[] = [];
+  let pa = 0;
+  let pb = 0;
+  let oi = 0;
+  while (oi < o.length || pa < aHunks.length || pb < bHunks.length) {
+    const ah = pa < aHunks.length ? aHunks[pa] : null;
+    const bh = pb < bHunks.length ? bHunks[pb] : null;
+    const nextStart = Math.min(
+      ah ? ah.oStart : o.length,
+      bh ? bh.oStart : o.length,
+    );
+
+    // Emit stable base blocks (kept by both) until the next hunk, from LIVE.
+    while (oi < nextStart) {
+      out.push({ src: 'live', local: aKept.get(oi) as number });
+      oi++;
+    }
+    if (!ah && !bh) break;
+
+    // Apply the hunk at oi. When both sides act here they are disjoint, so the
+    // pure-insert (oEnd === oi) is emitted before the side that consumes base oi.
+    const aHere = ah !== null && ah.oStart === oi;
+    const bHere = bh !== null && bh.oStart === oi;
+    let useA: boolean;
+    if (aHere && bHere) {
+      useA = ah!.oEnd === oi; // insert side first; otherwise either order is fine
+    } else {
+      useA = aHere;
+    }
+    const h = (useA ? ah : bh) as Hunk;
+    const src: 'live' | 'target' = useA ? 'live' : 'target';
+    for (const idx of h.content) out.push({ src, local: idx });
+    oi = h.oEnd;
+    if (useA) pa++;
+    else pb++;
+  }
+  return out;
+}
+
+export interface Pick {
+  src: 'live' | 'target';
+  index: number;
+}
+
+/**
+ * The merged block order PLUS how many regions resolved as a genuine SAME-BLOCK
+ * conflict (both sides rewrote the same base block — `tryMergeRegion` returned
+ * null and git won the whole region, so the live/human version of those blocks
+ * is NOT in `picks`). `conflicts > 0` is the OBSERVABLE signal the caller uses to
+ * surface "git won a concurrent same-block edit" (log it + pin the human
+ * baseline to page history) instead of dropping the human side silently.
+ */
+export interface Diff3Result {
+  picks: Pick[];
+  conflicts: number;
+}
+
+/**
+ * Three-way merge of base `o`, live `a`, target `b` (arrays of block keys).
+ * Returns the merged block order as picks from live/target. Thin wrapper over
+ * `diff3PlanWithConflicts` (kept for the existing pure-array callers/tests).
+ */
+export function diff3Plan(o: string[], a: string[], b: string[]): Pick[] {
+  return diff3PlanWithConflicts(o, a, b).picks;
+}
+
+/**
+ * Like `diff3Plan` but also reports the SAME-BLOCK conflict count (see
+ * `Diff3Result`). A region where both the human and git rewrote the same base
+ * block cannot be merged automatically; the rule is deterministic — GIT WINS the
+ * whole region — but the human's version of those blocks is then absent from the
+ * picks, so we count it so the caller can make the loss observable/recoverable
+ * rather than silent (the documented conflict contract).
+ */
+export function diff3PlanWithConflicts(
+  o: string[],
+  a: string[],
+  b: string[],
+): Diff3Result {
+  const oToA = matchMap(lcsPairs(o, a));
+  const oToB = matchMap(lcsPairs(o, b));
+
+  const res: Pick[] = [];
+  let conflicts = 0;
+  let oi = 0;
+  let ai = 0;
+  let bi = 0;
+
+  for (;;) {
+    // Next anchor: a base block present (unchanged) in BOTH live and target.
+    let anchor = oi;
+    while (anchor < o.length && !(oToA.has(anchor) && oToB.has(anchor))) {
+      anchor++;
+    }
+    const aEnd = anchor < o.length ? (oToA.get(anchor) as number) : a.length;
+    const bEnd = anchor < o.length ? (oToB.get(anchor) as number) : b.length;
+
+    // Resolve the region [oi,anchor) that one or both sides rewrote/inserted.
+    // Try a fine-grained three-way merge first so a human block-edit survives a
+    // git insert/delete of OTHER blocks in the same region; only a genuine
+    // same-block conflict (null) falls back to the original git-wins rule.
+    const merged = tryMergeRegion(
+      o.slice(oi, anchor),
+      a.slice(ai, aEnd),
+      b.slice(bi, bEnd),
+    );
+    if (merged) {
+      for (const p of merged) {
+        res.push(
+          p.src === 'live'
+            ? { src: 'live', index: ai + p.local }
+            : { src: 'target', index: bi + p.local },
+        );
+      }
+    } else {
+      // SAME-BLOCK CONFLICT: count it ONLY when the human side actually had
+      // content in this region that git's win discards (live region non-empty).
+      // A region only git rewrote (live region empty) is not a human loss.
+      if (aEnd > ai) conflicts++;
+      for (let k = bi; k < bEnd; k++) res.push({ src: 'target', index: k });
+    }
+
+    if (anchor >= o.length) break;
+
+    // Emit the stable anchor block from LIVE, then advance past it on all sides.
+    res.push({ src: 'live', index: aEnd });
+    ai = aEnd + 1;
+    bi = bEnd + 1;
+    oi = anchor + 1;
+  }
+
+  return { picks: res, conflicts };
+}

apps/server/src/collaboration/merge/yjs-body-merge.callout.spec.ts

@@ -0,0 +1,171 @@
+import { TiptapTransformer } from '@hocuspocus/transformer';
+import * as Y from 'yjs';
+import {
+  markdownToProseMirror,
+  convertProseMirrorToMarkdown,
+} from '@docmost/git-sync';
+
+import { tiptapExtensions } from '../collaboration.util';
+import { mergeXmlFragments, mergeXmlFragments3Way } from './yjs-body-merge';
+
+/**
+ * Regression for the QA #119 callout findings (body-duplication re-verify +
+ * "callout strips the whole body"). These reproduce the ACTUAL live merge path:
+ *
+ *   live  = TiptapTransformer.toYdoc(editor JSON, tiptapExtensions)   (the
+ *           collaboration server's materialization — schema defaults stamped)
+ *   git   = toYdoc(markdownToProseMirror(convertProseMirrorToMarkdown(editor)))
+ *           (the engine round-trip the push side feeds into writePageBody)
+ *
+ * A page containing a callout (with a neighbouring heading + paragraphs) must:
+ *   - merge with ZERO ops on an unchanged resync (no duplication — bug #1), and
+ *   - NEVER lose blocks / collapse to empty (no strip — bug #2),
+ * across repeated cycles, for every editor-canonical callout type.
+ */
+
+const toYdoc = (content: unknown[]) =>
+  TiptapTransformer.toYdoc(
+    { type: 'doc', content },
+    'default',
+    tiptapExtensions as any,
+  );
+
+const blockTypes = (f: Y.XmlFragment) =>
+  f.toArray().map((n: any) => n.nodeName);
+
+function editorPage(calloutType: string) {
+  return [
+    {
+      type: 'heading',
+      attrs: { id: 'h1', level: 1 },
+      content: [{ type: 'text', text: 'Title here' }],
+    },
+    {
+      type: 'paragraph',
+      attrs: { id: 'p1' },
+      content: [{ type: 'text', text: 'Para before callout' }],
+    },
+    {
+      type: 'callout',
+      attrs: { type: calloutType },
+      content: [
+        {
+          type: 'paragraph',
+          attrs: { id: 'pc' },
+          content: [{ type: 'text', text: 'Inside the callout' }],
+        },
+      ],
+    },
+    {
+      type: 'paragraph',
+      attrs: { id: 'p2' },
+      content: [{ type: 'text', text: 'Para after callout' }],
+    },
+  ];
+}
+
+async function gitRoundTrip(content: unknown[]): Promise<any[]> {
+  const md = await convertProseMirrorToMarkdown({ type: 'doc', content });
+  const json = await markdownToProseMirror(md);
+  return json.content;
+}
+
+describe('git-sync callout merge is idempotent + non-destructive (QA #119)', () => {
+  for (const type of ['info', 'note', 'warning', 'danger', 'success', 'default']) {
+    it(`callout(${type}) resyncs with 0 ops and never strips the body`, async () => {
+      const editor = editorPage(type);
+      const gitContent = await gitRoundTrip(editor);
+
+      const liveDoc = toYdoc(editor);
+      const live = liveDoc.getXmlFragment('default');
+      const before = live.toArray().length;
+      expect(before).toBe(4);
+
+      // 2-way: live vs the git round-trip -> no-op (no dup, no strip).
+      let applied = -1;
+      liveDoc.transact(() => {
+        applied = mergeXmlFragments(live, toYdoc(gitContent).getXmlFragment('default'));
+      });
+      expect(applied).toBe(0);
+      expect(live.toArray().length).toBe(before);
+
+      // 3-way across 4 cycles with base == git (the steady-state) -> stable.
+      for (let cycle = 0; cycle < 4; cycle++) {
+        let a = -1;
+        liveDoc.transact(() => {
+          a = mergeXmlFragments3Way(
+            live,
+            toYdoc(gitContent).getXmlFragment('default'),
+            toYdoc(gitContent).getXmlFragment('default'),
+          );
+        });
+        expect(a).toBe(0);
+        expect(live.toArray().length).toBe(before);
+        expect(blockTypes(live)).toEqual([
+          'heading',
+          'paragraph',
+          'callout',
+          'paragraph',
+        ]);
+      }
+    });
+  }
+
+  it('3-way with a stale base (callout JUST added) keeps the callout + neighbours', async () => {
+    // base = the previously-synced version WITHOUT the callout (git round-trip);
+    // the human just inserted the callout -> the merge must KEEP everything.
+    const prev = [
+      { type: 'heading', attrs: { id: 'h1', level: 1 }, content: [{ type: 'text', text: 'Title here' }] },
+      { type: 'paragraph', attrs: { id: 'p1' }, content: [{ type: 'text', text: 'Para before callout' }] },
+      { type: 'paragraph', attrs: { id: 'p2' }, content: [{ type: 'text', text: 'Para after callout' }] },
+    ];
+    const editor = editorPage('info');
+    const baseContent = await gitRoundTrip(prev);
+    const gitContent = await gitRoundTrip(editor);
+
+    const liveDoc = toYdoc(editor);
+    const live = liveDoc.getXmlFragment('default');
+    liveDoc.transact(() => {
+      mergeXmlFragments3Way(
+        live,
+        toYdoc(gitContent).getXmlFragment('default'),
+        toYdoc(baseContent).getXmlFragment('default'),
+      );
+    });
+    // Body survives in full — NOT stripped to empty / a lone paragraph.
+    expect(blockTypes(live)).toEqual([
+      'heading',
+      'paragraph',
+      'callout',
+      'paragraph',
+    ]);
+  });
+});
+
+describe('git-sync callout type fidelity (QA "callout type -> [!info]")', () => {
+  for (const type of ['info', 'note', 'warning', 'danger', 'success', 'default']) {
+    it(`preserves callout type "${type}" across the engine round-trip`, async () => {
+      const content = editorPage(type);
+      const gitContent = await gitRoundTrip(content);
+      const co = gitContent.find((b: any) => b.type === 'callout');
+      expect(co?.attrs?.type).toBe(type);
+    });
+  }
+
+  it('maps a known GitHub/Obsidian alias to the editor banner (tip -> success)', async () => {
+    // `tip` is not a schema callout type — it is an input alias the editor itself
+    // maps onto the supported set (GITHUB_ALERT_TYPE_MAP: tip -> success). git-sync
+    // mirrors that so the ingest lands on the closest banner instead of flatly info.
+    const content = editorPage('tip');
+    const gitContent = await gitRoundTrip(content);
+    const co = gitContent.find((b: any) => b.type === 'callout');
+    expect(co?.attrs?.type).toBe('success');
+  });
+
+  it('flattens a genuinely unknown callout type to info', async () => {
+    const content = editorPage('banana'); // not a type and not a known alias
+    const gitContent = await gitRoundTrip(content);
+    const co = gitContent.find((b: any) => b.type === 'callout');
+    expect(co?.attrs?.type).toBe('info');
+  });
+});

apps/server/src/collaboration/merge/yjs-body-merge.idempotency.spec.ts

@@ -0,0 +1,198 @@
+import * as Y from 'yjs';
+
+import { mergeXmlFragments, mergeXmlFragments3Way } from './yjs-body-merge';
+
+/**
+ * Regression for the HIGH-severity runaway whole-body duplication: a page body
+ * was RE-APPENDED in full on every git-sync reconcile cycle, unbounded, with NO
+ * client connected.
+ *
+ * ROOT CAUSE (confirmed in-process against the real failing page): the LIVE Yjs
+ * document materializes the editor-schema default `indent: 0` on every
+ * paragraph/heading (and on the paragraph inside every list item, callout, and
+ * table cell), but a body re-imported from git — parsed from clean markdown —
+ * carries NO indent attribute. So every live block's comparison key differed from
+ * the same block coming back from git; the three-way merge could anchor on
+ * NOTHING, and the trailing unit that git's export already contained (but the
+ * merge could not match against the byte-identical live tail) was re-appended
+ * each cycle. Each grown export then diverged from the last-pushed base by one
+ * more unit — a self-sustaining loop.
+ *
+ * The fix normalizes the materialized default (`indent: 0`) out of the block key
+ * (the schema-derived `serializeXmlNode` normalization in yjs-body-merge.ts drops
+ * every attr equal to its ProseMirror-schema default; `indent: 0` is one such),
+ * so a live block compares equal to its git-round-tripped twin and the resync is
+ * a true no-op. The sibling `yjs-body-merge.schema-defaults.spec.ts` covers the
+ * rest of the bug class (image.align, link mark internal, …).
+ *
+ * These tests model that EXACTLY at the Yjs level: a LIVE fragment whose blocks
+ * carry `indent: 0` + block ids, versus a git-derived fragment of the SAME
+ * content with neither — for a body built from BYTE-IDENTICAL units that each
+ * contain a heading, a paragraph, a callout, and a table with empty cells (the
+ * trigger). RED before the fix (the merge applies > 0 ops and the body grows),
+ * GREEN after (0 ops, no growth).
+ */
+
+type Attrs = Record<string, string | number>;
+
+function el(
+  name: string,
+  attrs: Attrs,
+  children: (Y.XmlElement | Y.XmlText)[],
+) {
+  const e = new Y.XmlElement(name);
+  for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v as string);
+  if (children.length) e.insert(0, children);
+  return e;
+}
+
+function text(s: string): Y.XmlText {
+  const t = new Y.XmlText();
+  if (s) t.insert(0, s);
+  return t;
+}
+
+/**
+ * One byte-identical content unit (heading / paragraph / callout / table-with-
+ * empty-cells). `live` toggles the two things that exist ONLY in the live Yjs
+ * doc and NOT in a git round-trip: the materialized `indent: 0` default and the
+ * per-block `id`. `n` makes each unit's ids unique (as the editor would stamp)
+ * while keeping the visible CONTENT byte-identical across units.
+ */
+function unit(
+  live: boolean,
+  n: number,
+  headingText = 'Big Heading',
+): Y.XmlElement[] {
+  const ind: Attrs = live ? { indent: 0 } : {};
+  const id = (base: string): Attrs => (live ? { id: `${base}${n}` } : {});
+  const para = (attrs: Attrs, s: string) =>
+    el('paragraph', { ...attrs, ...ind }, [text(s)]);
+
+  const cell = (name: string) =>
+    el(name, { colspan: 1, rowspan: 1 }, [para({}, '')]);
+
+  return [
+    el('heading', { ...id('h'), level: 1, ...ind }, [text(headingText)]),
+    para(id('p'), 'Para with the same words'),
+    el('callout', { type: 'info' }, [para(id('c'), 'CalloutText here')]),
+    el('table', {}, [
+      el('tableRow', {}, [cell('tableHeader'), cell('tableHeader')]),
+      el('tableRow', {}, [cell('tableCell'), cell('tableCell')]),
+    ]),
+  ];
+}
+
+function fragmentOf(units: Y.XmlElement[][]): {
+  doc: Y.Doc;
+  frag: Y.XmlFragment;
+} {
+  const doc = new Y.Doc();
+  const frag = doc.getXmlFragment('default');
+  const blocks = units.flat();
+  if (blocks.length) frag.insert(0, blocks);
+  return { doc, frag };
+}
+
+const blockCount = (frag: Y.XmlFragment): number => frag.toArray().length;
+
+describe('git-sync reconcile import is idempotent (no whole-body duplication)', () => {
+  const UNITS = 3;
+
+  it('3-way: identical content, live carries indent:0, base stale-by-one -> 0 ops, no growth', () => {
+    // LIVE: the editor-stamped Yjs doc (indent:0 + ids on every block).
+    const { doc: liveDoc, frag: live } = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) => unit(true, i)),
+    );
+    // INCOMING (git export -> re-import): same content, NO indent / ids.
+    const { frag: incoming } = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) => unit(false, i)),
+    );
+    // BASE = last-pushed file, lagging by ONE unit (the realistic divergence
+    // that drives the trailing insert-vs-insert).
+    const { frag: base } = fragmentOf(
+      Array.from({ length: UNITS - 1 }, (_, i) => unit(false, i)),
+    );
+
+    const before = blockCount(live);
+    let applied = -1;
+    liveDoc.transact(() => {
+      applied = mergeXmlFragments3Way(live, incoming, base);
+    });
+
+    expect(applied).toBe(0);
+    expect(blockCount(live)).toBe(before);
+  });
+
+  it('3-way is a fixpoint across repeated cycles (does not grow)', () => {
+    const { doc: liveDoc, frag: live } = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) => unit(true, i)),
+    );
+    const incomingUnits = () =>
+      fragmentOf(Array.from({ length: UNITS }, (_, i) => unit(false, i))).frag;
+    const baseUnits = () =>
+      fragmentOf(Array.from({ length: UNITS - 1 }, (_, i) => unit(false, i)))
+        .frag;
+
+    const before = blockCount(live);
+    for (let cycle = 0; cycle < 5; cycle++) {
+      let applied = -1;
+      liveDoc.transact(() => {
+        applied = mergeXmlFragments3Way(live, incomingUnits(), baseUnits());
+      });
+      expect(applied).toBe(0);
+      expect(blockCount(live)).toBe(before);
+    }
+  });
+
+  it('2-way: identical content, live carries indent:0 -> 0 ops, no growth', () => {
+    const { doc: liveDoc, frag: live } = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) => unit(true, i)),
+    );
+    const { frag: incoming } = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) => unit(false, i)),
+    );
+
+    const before = blockCount(live);
+    let applied = -1;
+    liveDoc.transact(() => {
+      applied = mergeXmlFragments(live, incoming);
+    });
+
+    expect(applied).toBe(0);
+    expect(blockCount(live)).toBe(before);
+  });
+
+  it('does NOT regress real edits: a git change to one block still lands', () => {
+    const { doc: liveDoc, frag: live } = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) => unit(true, i)),
+    );
+    const base = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) => unit(false, i)),
+    ).frag;
+    // git edits the heading text of the LAST unit.
+    const incoming = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) =>
+        unit(false, i, i === UNITS - 1 ? 'EDITED Heading' : 'Big Heading'),
+      ),
+    ).frag;
+
+    const before = blockCount(live);
+    liveDoc.transact(() => {
+      mergeXmlFragments3Way(live, incoming, base);
+    });
+
+    // The edit landed, and the body did NOT grow (one block changed in place).
+    const headings = live
+      .toArray()
+      .filter((b) => (b as Y.XmlElement).nodeName === 'heading')
+      .map((b) =>
+        (b as Y.XmlElement)
+          .toArray()
+          .map((c) => (c as Y.XmlText).toString())
+          .join(''),
+      );
+    expect(headings).toContain('EDITED Heading');
+    expect(blockCount(live)).toBe(before);
+  });
+});

apps/server/src/collaboration/merge/yjs-body-merge.schema-defaults.spec.ts

@@ -0,0 +1,316 @@
+import { TiptapTransformer } from '@hocuspocus/transformer';
+import * as Y from 'yjs';
+
+import { tiptapExtensions } from '../collaboration.util';
+import { mergeXmlFragments, mergeXmlFragments3Way } from './yjs-body-merge';
+
+/**
+ * Regression for the BUG CLASS behind the runaway whole-body duplication: the
+ * point-fix (7a7b840e) only normalized `indent: 0`, but the SAME divergence
+ * recurs for every attribute whose editor-ext (server) schema default the live
+ * Yjs doc MATERIALIZES while the git round-trip — which comes through the engine
+ * schema (different, usually null, defaults) plus `y-prosemirror`'s null-attr
+ * dropping — does NOT carry. Confirmed triggers beyond `indent`:
+ *
+ *   - `image.align`   : editor-ext default "center" (materialized) vs engine
+ *                       default null (dropped) -> element-attr divergence.
+ *   - link mark `internal`: editor-ext default false (materialized) vs engine
+ *                       default null -> MARK-attr divergence (the prior denylist
+ *                       could not reach marks at all — they are serialized raw in
+ *                       the XmlText delta).
+ *
+ * `highlight.colorName` is normalized too (defense-in-depth); it is NOT a strong
+ * real-world trigger because BOTH schemas default it to null, but the schema-
+ * derived normalization handles it for free and stays idempotent.
+ *
+ * The fix derives the defaults from the ACTUAL ProseMirror schema (getSchema of
+ * the server tiptapExtensions) and drops any element- OR mark-attribute equal to
+ * its schema default (or null/undefined) from the block comparison key — so a
+ * live block compares equal to its git-round-tripped twin and an unchanged
+ * resync applies 0 ops. RED before the fix (keys diverge -> ops > 0 / growth),
+ * GREEN after.
+ */
+
+type Attrs = Record<string, unknown>;
+
+function el(
+  name: string,
+  attrs: Attrs,
+  children: (Y.XmlElement | Y.XmlText)[],
+): Y.XmlElement {
+  const e = new Y.XmlElement(name);
+  for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v as string);
+  if (children.length) e.insert(0, children);
+  return e;
+}
+
+/** Text carrying marks, as the live Yjs doc stores them (XmlText format ops). */
+function markedText(s: string, marks: Record<string, unknown>): Y.XmlText {
+  const t = new Y.XmlText();
+  t.insert(0, s, marks);
+  return t;
+}
+
+/**
+ * One byte-identical RICH unit: a paragraph with a LINK, a top-level IMAGE, and
+ * a paragraph with a HIGHLIGHT. `live` toggles exactly what the editor
+ * materializes but a git round-trip does not: block `id`, `indent: 0`,
+ * `image.align: "center"`, the link mark's `internal: false`, and the
+ * highlight's `colorName: null`.
+ */
+function richUnit(live: boolean, n: number): Y.XmlElement[] {
+  const ind: Attrs = live ? { indent: 0 } : {};
+  const id = (base: string): Attrs => (live ? { id: `${base}${n}` } : {});
+
+  const linkMarks = live
+    ? {
+        link: {
+          href: 'https://example.com',
+          target: '_blank',
+          rel: 'noopener noreferrer nofollow',
+          class: null,
+          title: null,
+          internal: false, // editor-ext default, materialized
+        },
+      }
+    : {
+        link: {
+          href: 'https://example.com',
+          target: '_blank',
+          rel: 'noopener noreferrer nofollow',
+          internal: null, // engine default
+        },
+      };
+
+  const hlMarks = live
+    ? { highlight: { color: '#ffd43b', colorName: null } }
+    : { highlight: { color: '#ffd43b' } };
+
+  const imageAttrs: Attrs = live
+    ? { src: 'https://img.example.com/a.png', align: 'center' } // materialized
+    : { src: 'https://img.example.com/a.png' }; // align:null dropped on git side
+
+  return [
+    el('paragraph', { ...id('lp'), ...ind }, [
+      markedText('click here', linkMarks),
+    ]),
+    el('image', imageAttrs, []),
+    el('paragraph', { ...id('hp'), ...ind }, [markedText('hot', hlMarks)]),
+  ];
+}
+
+function fragmentOf(units: Y.XmlElement[][]): {
+  doc: Y.Doc;
+  frag: Y.XmlFragment;
+} {
+  const doc = new Y.Doc();
+  const frag = doc.getXmlFragment('default');
+  const blocks = units.flat();
+  if (blocks.length) frag.insert(0, blocks);
+  return { doc, frag };
+}
+
+const blockCount = (frag: Y.XmlFragment): number => frag.toArray().length;
+
+describe('git-sync reconcile is idempotent for schema-default attrs (image/link/highlight)', () => {
+  const UNITS = 3;
+
+  it('3-way: live carries image.align/link.internal/indent defaults, base stale-by-one -> 0 ops', () => {
+    const { doc: liveDoc, frag: live } = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) => richUnit(true, i)),
+    );
+    const { frag: incoming } = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) => richUnit(false, i)),
+    );
+    const { frag: base } = fragmentOf(
+      Array.from({ length: UNITS - 1 }, (_, i) => richUnit(false, i)),
+    );
+
+    const before = blockCount(live);
+    let applied = -1;
+    liveDoc.transact(() => {
+      applied = mergeXmlFragments3Way(live, incoming, base);
+    });
+
+    expect(applied).toBe(0);
+    expect(blockCount(live)).toBe(before);
+  });
+
+  it('2-way: live carries the materialized defaults -> 0 ops, no growth', () => {
+    const { doc: liveDoc, frag: live } = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) => richUnit(true, i)),
+    );
+    const { frag: incoming } = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) => richUnit(false, i)),
+    );
+
+    const before = blockCount(live);
+    let applied = -1;
+    liveDoc.transact(() => {
+      applied = mergeXmlFragments(live, incoming);
+    });
+
+    expect(applied).toBe(0);
+    expect(blockCount(live)).toBe(before);
+  });
+
+  it('is a fixpoint across repeated cycles (does not grow)', () => {
+    const { doc: liveDoc, frag: live } = fragmentOf(
+      Array.from({ length: UNITS }, (_, i) => richUnit(true, i)),
+    );
+    const incoming = () =>
+      fragmentOf(Array.from({ length: UNITS }, (_, i) => richUnit(false, i)))
+        .frag;
+    const base = () =>
+      fragmentOf(
+        Array.from({ length: UNITS - 1 }, (_, i) => richUnit(false, i)),
+      ).frag;
+
+    const before = blockCount(live);
+    for (let cycle = 0; cycle < 5; cycle++) {
+      let applied = -1;
+      liveDoc.transact(() => {
+        applied = mergeXmlFragments3Way(live, incoming(), base());
+      });
+      expect(applied).toBe(0);
+      expect(blockCount(live)).toBe(before);
+    }
+  });
+
+  it('does NOT regress a genuine non-default value (a real link.href / image.align:left still diffs)', () => {
+    const { doc: liveDoc, frag: live } = fragmentOf([richUnit(true, 0)]);
+    const base = fragmentOf([richUnit(false, 0)]).frag;
+    // git genuinely changes the image alignment to a NON-default value.
+    const incomingUnit = richUnit(false, 0);
+    (incomingUnit[1] as Y.XmlElement).setAttribute('align', 'left');
+    const incoming = fragmentOf([incomingUnit]).frag;
+
+    liveDoc.transact(() => {
+      mergeXmlFragments3Way(live, incoming, base);
+    });
+
+    const img = live
+      .toArray()
+      .find((b) => (b as Y.XmlElement).nodeName === 'image') as Y.XmlElement;
+    expect(img.getAttribute('align')).toBe('left');
+  });
+});
+
+/**
+ * FAITHFUL end-to-end proof through the REAL server transformer: build the live
+ * doc the way the collaboration server does (defaults omitted in the JSON ->
+ * TiptapTransformer.toYdoc MATERIALIZES image.align:"center", link.internal:false,
+ * indent:0) versus the git-derived doc (engine-style: defaults emitted as
+ * explicit null, no block ids). An unchanged resync must apply 0 ops.
+ */
+describe('git-sync reconcile is idempotent through the real toYdoc materialization', () => {
+  const liveContent = [
+    {
+      type: 'paragraph',
+      attrs: { id: 'p1' },
+      content: [
+        {
+          type: 'text',
+          text: 'click here',
+          marks: [{ type: 'link', attrs: { href: 'https://example.com' } }],
+        },
+      ],
+    },
+    { type: 'image', attrs: { src: 'https://img.example.com/a.png' } },
+    {
+      type: 'paragraph',
+      attrs: { id: 'p2' },
+      content: [
+        {
+          type: 'text',
+          text: 'hot',
+          marks: [{ type: 'highlight', attrs: { color: '#ffd43b' } }],
+        },
+      ],
+    },
+  ];
+
+  // git/engine-style: explicit nulls for the engine-default attrs, no ids.
+  const gitContent = [
+    {
+      type: 'paragraph',
+      content: [
+        {
+          type: 'text',
+          text: 'click here',
+          marks: [
+            {
+              type: 'link',
+              attrs: {
+                href: 'https://example.com',
+                target: '_blank',
+                rel: 'noopener noreferrer nofollow',
+                class: null,
+                title: null,
+                internal: null,
+              },
+            },
+          ],
+        },
+      ],
+    },
+    {
+      type: 'image',
+      attrs: { src: 'https://img.example.com/a.png', align: null },
+    },
+    {
+      type: 'paragraph',
+      content: [
+        {
+          type: 'text',
+          text: 'hot',
+          marks: [
+            { type: 'highlight', attrs: { color: '#ffd43b', colorName: null } },
+          ],
+        },
+      ],
+    },
+  ];
+
+  const toYdoc = (content: unknown[]) =>
+    TiptapTransformer.toYdoc(
+      { type: 'doc', content },
+      'default',
+      tiptapExtensions as any,
+    );
+
+  it('3-way: materialized-default live vs engine-style git, base stale-by-one -> 0 ops', () => {
+    const liveDoc = toYdoc(liveContent);
+    const targetDoc = toYdoc(gitContent);
+    const baseDoc = toYdoc(gitContent.slice(0, gitContent.length - 1));
+
+    const live = liveDoc.getXmlFragment('default');
+    const before = live.toArray().length;
+    let applied = -1;
+    liveDoc.transact(() => {
+      applied = mergeXmlFragments3Way(
+        live,
+        targetDoc.getXmlFragment('default'),
+        baseDoc.getXmlFragment('default'),
+      );
+    });
+
+    expect(applied).toBe(0);
+    expect(live.toArray().length).toBe(before);
+  });
+
+  it('2-way: materialized-default live vs engine-style git -> 0 ops', () => {
+    const liveDoc = toYdoc(liveContent);
+    const targetDoc = toYdoc(gitContent);
+
+    const live = liveDoc.getXmlFragment('default');
+    const before = live.toArray().length;
+    let applied = -1;
+    liveDoc.transact(() => {
+      applied = mergeXmlFragments(live, targetDoc.getXmlFragment('default'));
+    });
+
+    expect(applied).toBe(0);
+    expect(live.toArray().length).toBe(before);
+  });
+});

apps/server/src/collaboration/merge/yjs-body-merge.spec.ts

@@ -0,0 +1,373 @@
+import * as Y from 'yjs';
+
+import {
+  mergeXmlFragments,
+  mergeXmlFragments3Way,
+  mergeXmlFragments3WayWithStats,
+  cloneXmlNode,
+  diffBlocks,
+} from './yjs-body-merge';
+
+// Build a Y.XmlFragment('default') in `doc` from a list of paragraph specs.
+// Each spec is the paragraph's plain text (a single XmlText child).
+function buildFragment(doc: Y.Doc, paragraphs: string[]): Y.XmlFragment {
+  const frag = doc.getXmlFragment('default');
+  const blocks = paragraphs.map((text) => {
+    const el = new Y.XmlElement('paragraph');
+    const t = new Y.XmlText();
+    if (text) t.insert(0, text);
+    el.insert(0, [t]);
+    return el;
+  });
+  if (blocks.length) frag.insert(0, blocks);
+  return frag;
+}
+
+function texts(frag: Y.XmlFragment): string[] {
+  return frag.toArray().map((el) => (el as Y.XmlElement).toArray()
+    .map((c) => (c as Y.XmlText).toString())
+    .join(''));
+}
+
+describe('yjs-body-merge', () => {
+  describe('diffBlocks (LCS edit script)', () => {
+    it('identical sequences produce only keeps (no edits)', () => {
+      const ops = diffBlocks(['a', 'b', 'c'], ['a', 'b', 'c']);
+      expect(ops.every((o) => o.op === 'keep')).toBe(true);
+    });
+
+    it('a single changed middle element is one del + one ins', () => {
+      const ops = diffBlocks(['a', 'b', 'c'], ['a', 'B', 'c']);
+      expect(ops.filter((o) => o.op === 'del')).toHaveLength(1);
+      expect(ops.filter((o) => o.op === 'ins')).toHaveLength(1);
+      expect(ops.filter((o) => o.op === 'keep')).toHaveLength(2);
+    });
+  });
+
+  describe('mergeXmlFragments', () => {
+    it('identical content is a complete no-op (0 ops) — never clobbers an unchanged resync', () => {
+      const live = new Y.Doc();
+      const target = new Y.Doc();
+      const liveFrag = buildFragment(live, ['one', 'two', 'three']);
+      const targetFrag = buildFragment(target, ['one', 'two', 'three']);
+
+      // Capture block identities to prove they are left untouched.
+      const before = liveFrag.toArray();
+      let applied = -1;
+      live.transact(() => {
+        applied = mergeXmlFragments(liveFrag, targetFrag);
+      });
+
+      expect(applied).toBe(0);
+      // Same Y.XmlElement instances — nothing was deleted/recreated.
+      expect(liveFrag.toArray()).toEqual(before);
+      expect(texts(liveFrag)).toEqual(['one', 'two', 'three']);
+    });
+
+    it('a human edit to one block survives a git change to a DIFFERENT block', () => {
+      // Live: the human has the doc open; block 0 holds their edit. Git changed
+      // only block 2. The merge must touch ONLY block 2 and leave block 0 (and
+      // its in-flight edit) exactly as-is.
+      const live = new Y.Doc();
+      const target = new Y.Doc();
+      const liveFrag = buildFragment(live, ['HUMAN EDIT', 'shared', 'old tail']);
+      const targetFrag = buildFragment(target, [
+        'HUMAN EDIT',
+        'shared',
+        'new tail from git',
+      ]);
+
+      const block0Before = liveFrag.get(0); // the human's block instance
+      const block1Before = liveFrag.get(1);
+
+      let applied = -1;
+      live.transact(() => {
+        applied = mergeXmlFragments(liveFrag, targetFrag);
+      });
+
+      // Only block 2 was replaced: one del + one ins.
+      expect(applied).toBe(2);
+      // The human's block and the shared block are the SAME instances (untouched).
+      expect(liveFrag.get(0)).toBe(block0Before);
+      expect(liveFrag.get(1)).toBe(block1Before);
+      // Block 2 now carries git's content.
+      expect(texts(liveFrag)).toEqual([
+        'HUMAN EDIT',
+        'shared',
+        'new tail from git',
+      ]);
+    });
+
+    it('appends a new trailing block without disturbing existing ones', () => {
+      const live = new Y.Doc();
+      const target = new Y.Doc();
+      const liveFrag = buildFragment(live, ['a', 'b']);
+      const targetFrag = buildFragment(target, ['a', 'b', 'c']);
+      const a = liveFrag.get(0);
+      const b = liveFrag.get(1);
+
+      let applied = -1;
+      live.transact(() => {
+        applied = mergeXmlFragments(liveFrag, targetFrag);
+      });
+
+      expect(applied).toBe(1); // single insert
+      expect(liveFrag.get(0)).toBe(a);
+      expect(liveFrag.get(1)).toBe(b);
+      expect(texts(liveFrag)).toEqual(['a', 'b', 'c']);
+    });
+
+    it('deletes a removed block, keeping its neighbours', () => {
+      const live = new Y.Doc();
+      const target = new Y.Doc();
+      const liveFrag = buildFragment(live, ['a', 'b', 'c']);
+      const targetFrag = buildFragment(target, ['a', 'c']);
+      const a = liveFrag.get(0);
+
+      let applied = -1;
+      live.transact(() => {
+        applied = mergeXmlFragments(liveFrag, targetFrag);
+      });
+
+      expect(applied).toBe(1); // single delete
+      expect(liveFrag.get(0)).toBe(a);
+      expect(texts(liveFrag)).toEqual(['a', 'c']);
+    });
+
+    it('a fully different body is replaced (and stays valid)', () => {
+      const live = new Y.Doc();
+      const target = new Y.Doc();
+      const liveFrag = buildFragment(live, ['x', 'y']);
+      const targetFrag = buildFragment(target, ['p', 'q', 'r']);
+      live.transact(() => mergeXmlFragments(liveFrag, targetFrag));
+      expect(texts(liveFrag)).toEqual(['p', 'q', 'r']);
+    });
+  });
+
+  describe('mergeXmlFragments3Way', () => {
+    it('keeps a human edit to one block while applying a git change to another (3-way)', () => {
+      // base (last synced): [a, b, c]. Human edited block 0 in the live doc; git
+      // changed block 2 in the incoming file. 3-way must keep BOTH — the 2-way
+      // merge would instead revert the human's block 0 to git's stale version.
+      const base = new Y.Doc();
+      const live = new Y.Doc();
+      const target = new Y.Doc();
+      const baseFrag = buildFragment(base, ['a', 'b', 'c']);
+      const liveFrag = buildFragment(live, ['HUMAN', 'b', 'c']);
+      const targetFrag = buildFragment(target, ['a', 'b', 'GIT']);
+
+      const humanBlock = liveFrag.get(0); // the human's live instance
+      live.transact(() =>
+        mergeXmlFragments3Way(liveFrag, targetFrag, baseFrag),
+      );
+
+      // Human's block preserved as the SAME instance; git's change applied.
+      expect(liveFrag.get(0)).toBe(humanBlock);
+      expect(texts(liveFrag)).toEqual(['HUMAN', 'b', 'GIT']);
+    });
+
+    it('a block both sides changed resolves to git (conflict policy)', () => {
+      const base = new Y.Doc();
+      const live = new Y.Doc();
+      const target = new Y.Doc();
+      const baseFrag = buildFragment(base, ['a', 'b', 'c']);
+      const liveFrag = buildFragment(live, ['a', 'HUMAN', 'c']);
+      const targetFrag = buildFragment(target, ['a', 'GIT', 'c']);
+
+      live.transact(() =>
+        mergeXmlFragments3Way(liveFrag, targetFrag, baseFrag),
+      );
+      expect(texts(liveFrag)).toEqual(['a', 'GIT', 'c']);
+    });
+
+    // Bug #2 observability: the stats variant reports the same-block conflict so
+    // the handler can log it + the persistence layer can pin the human baseline.
+    it('reports the same-block conflict count via mergeXmlFragments3WayWithStats', () => {
+      const base = new Y.Doc();
+      const live = new Y.Doc();
+      const target = new Y.Doc();
+      const baseFrag = buildFragment(base, ['a', 'b', 'c']);
+      const liveFrag = buildFragment(live, ['a', 'HUMAN', 'c']);
+      const targetFrag = buildFragment(target, ['a', 'GIT', 'c']);
+
+      let result!: { applied: number; conflicts: number };
+      live.transact(() => {
+        result = mergeXmlFragments3WayWithStats(liveFrag, targetFrag, baseFrag);
+      });
+      expect(result.conflicts).toBe(1);
+      expect(texts(liveFrag)).toEqual(['a', 'GIT', 'c']);
+    });
+
+    it('reports 0 conflicts for a clean different-block 3-way merge', () => {
+      const base = new Y.Doc();
+      const live = new Y.Doc();
+      const target = new Y.Doc();
+      const baseFrag = buildFragment(base, ['a', 'b', 'c']);
+      const liveFrag = buildFragment(live, ['HUMAN', 'b', 'c']);
+      const targetFrag = buildFragment(target, ['a', 'b', 'GIT']);
+
+      let result!: { applied: number; conflicts: number };
+      live.transact(() => {
+        result = mergeXmlFragments3WayWithStats(liveFrag, targetFrag, baseFrag);
+      });
+      expect(result.conflicts).toBe(0);
+      expect(texts(liveFrag)).toEqual(['HUMAN', 'b', 'GIT']);
+    });
+
+    it('git change with no concurrent human edit (live == base) applies cleanly', () => {
+      const base = new Y.Doc();
+      const live = new Y.Doc();
+      const target = new Y.Doc();
+      const baseFrag = buildFragment(base, ['a', 'b']);
+      const liveFrag = buildFragment(live, ['a', 'b']);
+      const targetFrag = buildFragment(target, ['a', 'B2']);
+
+      live.transact(() =>
+        mergeXmlFragments3Way(liveFrag, targetFrag, baseFrag),
+      );
+      expect(texts(liveFrag)).toEqual(['a', 'B2']);
+    });
+  });
+
+  // Regression: start-of-document content duplicating on every two-way sync.
+  //
+  // The LIVE Docmost doc stamps a per-block UniqueID on every heading/paragraph;
+  // a body arriving FROM git is parsed from clean markdown and carries NO block
+  // ids. If the merge comparison key includes that `id`, an unchanged live block
+  // never matches the SAME block coming from git, so the three-way merge cannot
+  // anchor on it — and an incoming block with no anchor (content inserted at the
+  // TOP of the page) is RE-ADDED on every cycle, an unbounded duplication loop.
+  // These tests model that exact id-asymmetry and assert the reconciliation is
+  // IDEMPOTENT (no block growth). They are RED before excluding `id` from the
+  // key in `serializeXmlNode`.
+  describe('idempotent reconciliation with live block ids (start-of-doc dup)', () => {
+    // Build a fragment from block specs. `id` is set only when provided, mirroring
+    // the live doc (ids present) vs a git-parsed body (ids absent).
+    type Spec = { tag: 'heading' | 'paragraph'; text: string; id?: string };
+    function buildDoc(doc: Y.Doc, specs: Spec[]): Y.XmlFragment {
+      const frag = doc.getXmlFragment('default');
+      const blocks = specs.map((s) => {
+        const el = new Y.XmlElement(s.tag);
+        if (s.id) el.setAttribute('id', s.id);
+        if (s.tag === 'heading') el.setAttribute('level', '2');
+        const t = new Y.XmlText();
+        if (s.text) t.insert(0, s.text);
+        el.insert(0, [t]);
+        return el;
+      });
+      if (blocks.length) frag.insert(0, blocks);
+      return frag;
+    }
+    const textsOf = (frag: Y.XmlFragment): string[] =>
+      frag.toArray().map((el) =>
+        (el as Y.XmlElement)
+          .toArray()
+          .map((c) => (c as Y.XmlText).toString())
+          .join(''),
+      );
+
+    it('re-merging the SAME git body does NOT re-add the top block (idempotent)', () => {
+      // last-synced base (from git markdown): NO block ids.
+      const base = new Y.Doc();
+      const baseFrag = buildDoc(base, [
+        { tag: 'heading', text: 'Title' },
+        { tag: 'paragraph', text: 'Some paragraph.' },
+        { tag: 'paragraph', text: 'End block.' },
+      ]);
+      // live Docmost doc: SAME content, but every block carries a UniqueID.
+      const live = new Y.Doc();
+      const liveFrag = buildDoc(live, [
+        { tag: 'heading', text: 'Title', id: 'ida' },
+        { tag: 'paragraph', text: 'Some paragraph.', id: 'idb' },
+        { tag: 'paragraph', text: 'End block.', id: 'idc' },
+      ]);
+      // incoming git body: the user inserted a heading at the very TOP.
+      const buildTarget = (): Y.XmlFragment =>
+        buildDoc(new Y.Doc(), [
+          { tag: 'heading', text: 'TOPDUP' },
+          { tag: 'heading', text: 'Title' },
+          { tag: 'paragraph', text: 'Some paragraph.' },
+          { tag: 'paragraph', text: 'End block.' },
+        ]);
+
+      // First sync: the top block is added once.
+      live.transact(() =>
+        mergeXmlFragments3Way(liveFrag, buildTarget(), baseFrag),
+      );
+      expect(textsOf(liveFrag)).toEqual([
+        'TOPDUP',
+        'Title',
+        'Some paragraph.',
+        'End block.',
+      ]);
+
+      // Subsequent sync of the SAME git body against the SAME base must be a
+      // NO-OP — not a second copy of the top block. Before the fix this re-adds
+      // 'TOPDUP', growing the doc on every cycle.
+      live.transact(() =>
+        mergeXmlFragments3Way(liveFrag, buildTarget(), baseFrag),
+      );
+      expect(textsOf(liveFrag)).toEqual([
+        'TOPDUP',
+        'Title',
+        'Some paragraph.',
+        'End block.',
+      ]);
+      expect(textsOf(liveFrag).filter((t) => t === 'TOPDUP')).toHaveLength(1);
+    });
+
+    it('an unchanged git body (live ids, none in git) is a complete no-op', () => {
+      // base == git body (no pending git change); live is the same content with
+      // ids. With `id` in the key the whole body looks rewritten; the merge must
+      // still leave live byte-identical (block instances untouched).
+      const base = new Y.Doc();
+      const baseFrag = buildDoc(base, [
+        { tag: 'heading', text: 'Title' },
+        { tag: 'paragraph', text: 'Body.' },
+      ]);
+      const live = new Y.Doc();
+      const liveFrag = buildDoc(live, [
+        { tag: 'heading', text: 'Title', id: 'ida' },
+        { tag: 'paragraph', text: 'Body.', id: 'idb' },
+      ]);
+      const before = liveFrag.toArray();
+      let applied = -1;
+      live.transact(() => {
+        applied = mergeXmlFragments3Way(
+          liveFrag,
+          buildDoc(new Y.Doc(), [
+            { tag: 'heading', text: 'Title' },
+            { tag: 'paragraph', text: 'Body.' },
+          ]),
+          baseFrag,
+        );
+      });
+      expect(applied).toBe(0);
+      // Same live block instances (ids preserved) — nothing recreated.
+      expect(liveFrag.toArray()).toEqual(before);
+    });
+  });
+
+  describe('cloneXmlNode', () => {
+    it('preserves text marks (XmlText delta) across docs', () => {
+      const src = new Y.Doc();
+      const srcFrag = src.getXmlFragment('default');
+      const el = new Y.XmlElement('paragraph');
+      const t = new Y.XmlText();
+      t.insert(0, 'plain ');
+      t.insert(6, 'bold', { bold: true });
+      el.insert(0, [t]);
+      srcFrag.insert(0, [el]);
+
+      const dst = new Y.Doc();
+      const dstFrag = dst.getXmlFragment('default');
+      dstFrag.insert(0, [cloneXmlNode(srcFrag.get(0) as Y.XmlElement)]);
+
+      const clonedText = (dstFrag.get(0) as Y.XmlElement).get(0) as Y.XmlText;
+      expect(clonedText.toDelta()).toEqual([
+        { insert: 'plain ' },
+        { insert: 'bold', attributes: { bold: true } },
+      ]);
+    });
+  });
+});

apps/server/src/collaboration/merge/yjs-body-merge.ts

@@ -0,0 +1,369 @@
+import * as Y from 'yjs';
+import { getSchema } from '@tiptap/core';
+import type { Schema } from '@tiptap/pm/model';
+
+import { tiptapExtensions } from '../collaboration.util';
+import { diff3PlanWithConflicts } from './three-way-merge';
+import { buildLcsTable } from './lcs';
+
+/**
+ * Block-level merge of an incoming (git) page body into a LIVE Yjs document,
+ * replacing the previous full-body "delete everything + re-insert" write that
+ * clobbered concurrent human edits on every sync (review #5 — "do the write as a
+ * merge").
+ *
+ * Strategy: diff the two documents at TOP-LEVEL BLOCK granularity (an LCS over a
+ * canonical structural serialization of each block) and apply only the minimal
+ * insert/delete operations. Blocks that are byte-identical on both sides are
+ * left UNTOUCHED in the live doc — so a human editing one paragraph is unaffected
+ * when git changes a different paragraph, and an unchanged re-sync is a complete
+ * no-op (zero Yjs operations). Yjs then CRDT-merges the minimal ops with any
+ * concurrent edits.
+ *
+ * Limitation (honest): this is a 2-way merge (live vs incoming). For a block that
+ * BOTH sides changed since the last sync it cannot tell which is newer without a
+ * common ancestor, so the incoming (git) version wins for that one block. A full
+ * 3-way merge would need the last-synced base plumbed from the engine; the common
+ * cases — unchanged resync, and edits to DIFFERENT blocks — are handled losslessly.
+ */
+
+type XmlNode = Y.XmlElement | Y.XmlText | Y.XmlHook;
+
+/**
+ * Node attributes that are VOLATILE identity (not content) and so must be
+ * excluded from the block comparison key.
+ *
+ * `id` is the per-block UniqueID the editor stamps on every heading/paragraph
+ * (and transclusionSource). It exists ONLY in the live Yjs document — a body
+ * arriving from git is parsed from clean markdown, which carries no block ids
+ * (`markdownToProseMirror` materializes `id: null`, which the Yjs transform then
+ * drops). If `id` were part of the key, an UNCHANGED live block (id "abc123")
+ * would never match the SAME block coming from git (no id), so the three-way
+ * merge's LCS could not anchor on it. The merge would then treat every live
+ * block as deleted-and-reinserted and, when an incoming block has no matching
+ * anchor (e.g. content inserted at the very TOP of the page), RE-ADD a copy of
+ * it on every sync cycle — a non-convergent, unbounded duplication loop
+ * (start-of-document content duplicating each push/pull cycle).
+ *
+ * Excluding `id` makes blocks compare by CONTENT, so an unchanged block matches
+ * across the git round-trip and the reconciliation is idempotent. Block identity
+ * is still preserved in the merged output: `diff3Plan` keeps the LIVE block
+ * INSTANCE (with its id) for an anchor — picks are by index, not by key — so the
+ * stable Yjs block (and any in-flight human edit on it) stays put. This mirrors
+ * `canonicalize.ts`, which already strips the regenerated block `id` from the
+ * round-trip idempotency comparison for exactly the same reason.
+ *
+ * Known limitation (accepted trade-off of content-based matching): two GENUINELY
+ * DISTINCT blocks whose content is byte-identical now collapse to the same content
+ * key, so when git deletes one of the duplicates the LCS may drop the OTHER live
+ * instance instead. The visible result is identical (one copy removed, one kept),
+ * but a concurrent in-flight human edit on the dropped instance could be lost.
+ */
+const VOLATILE_KEY_ATTRS = new Set(['id']);
+
+/**
+ * The editor (ProseMirror) schema, built ONCE from the same `tiptapExtensions`
+ * the collaboration server uses to materialize Yjs docs. Memoized: building the
+ * schema is non-trivial and the block key is computed per block per cycle.
+ *
+ * Why the schema (not a hardcoded denylist): the LIVE Yjs document is produced by
+ * `TiptapTransformer.toYdoc(pm, 'default', tiptapExtensions)`, which STAMPS every
+ * schema-default attribute onto every node and mark — `indent: 0` on every
+ * paragraph/heading, `image.align: "center"`, the link mark's `internal: false`,
+ * `highlight.colorName: null`, and so on for youtube/pdf/any future node. A body
+ * re-imported from git comes through the engine's `markdownToProseMirror`, whose
+ * schema declares those attrs with DIFFERENT (usually null) defaults; the
+ * resulting null/absent element attrs are then DROPPED by `y-prosemirror`'s
+ * toYdoc. So the SAME block carries materialized defaults on the live side and
+ * nothing on the git side, its key diverges, the three-way merge anchors on
+ * NOTHING, and the whole body is RE-APPENDED every reconcile cycle — an unbounded
+ * duplication loop with no client connected.
+ *
+ * Deriving the defaults from the actual schema normalizes ALL such attributes
+ * generally (it is not another per-attribute denylist): any attribute whose value
+ * equals the schema default — or is null/undefined — is dropped from the key, on
+ * BOTH element attributes and the mark attributes inside each XmlText delta, so a
+ * live block compares equal to its git-round-tripped twin and an unchanged resync
+ * applies zero ops. Genuinely non-default values (a real `indent: 2`, an
+ * `align: "left"`, a real `link.href`, a real highlight color) are content and
+ * stay in the key, so real edits still diff and land.
+ */
+let memoSchema: Schema | null = null;
+let memoSchemaTried = false;
+function getMergeSchema(): Schema | null {
+  if (!memoSchemaTried) {
+    memoSchemaTried = true;
+    try {
+      memoSchema = getSchema(tiptapExtensions as any);
+    } catch {
+      // Defensive: if the schema can't be built (e.g. a degenerate extension
+      // set in a unit test that stubs `tiptapExtensions`), fall back to dropping
+      // only null/undefined attrs. The real server always builds it fine.
+      memoSchema = null;
+    }
+  }
+  return memoSchema;
+}
+
+/** True if `value` is the schema default for `attrName` of `attrSpecs`, or is
+ * null/undefined (which a git round-trip drops). Such attributes are excluded
+ * from the comparison key. `attrSpecs` is a ProseMirror node/mark spec attr map
+ * (`{ [name]: { default } }`); a missing map (unknown node/mark) only drops
+ * null/undefined. (A non-null value matching an attr declared without a default
+ * cannot occur — `spec.default === value` is then `undefined === value`, false.) */
+function isDefaultAttr(
+  attrSpecs: Record<string, any> | undefined | null,
+  attrName: string,
+  value: unknown,
+): boolean {
+  if (value === null || value === undefined) return true;
+  const spec = attrSpecs?.[attrName];
+  return !!spec && spec.default === value;
+}
+
+/**
+ * Normalize one XmlText delta op's mark attributes: drop every mark-attr whose
+ * value equals the mark's schema default (or is null/undefined), so the link
+ * mark's materialized `internal: false`/`target: "_blank"` and a highlight's
+ * `colorName: null` no longer diverge from a git round-trip that carries neither.
+ * The text (op.insert) and genuinely-set mark attrs (a real `href`, a real
+ * highlight color) are preserved verbatim. `attributes` maps markName -> mark
+ * attrs object (or `true`/boolean for attr-less marks); each is handled safely.
+ */
+function normalizeDelta(delta: any[]): any[] {
+  const schema = getMergeSchema();
+  return delta.map((op) => {
+    if (!op || op.attributes == null || typeof op.attributes !== 'object') {
+      return op;
+    }
+    const marks: Record<string, unknown> = {};
+    for (const markName of Object.keys(op.attributes).sort()) {
+      const markVal = op.attributes[markName];
+      if (markVal === null || markVal === undefined) continue;
+      if (typeof markVal !== 'object') {
+        // attr-less mark stored as a primitive (e.g. `true`) — keep as-is.
+        marks[markName] = markVal;
+        continue;
+      }
+      const markSpec = schema?.marks[markName]?.spec.attrs as
+        | Record<string, any>
+        | undefined;
+      const cleaned: Record<string, unknown> = {};
+      for (const ak of Object.keys(markVal as object).sort()) {
+        const av = (markVal as Record<string, unknown>)[ak];
+        if (isDefaultAttr(markSpec, ak, av)) continue;
+        cleaned[ak] = av;
+      }
+      marks[markName] = cleaned;
+    }
+    return { ...op, attributes: marks };
+  });
+}
+
+/**
+ * Canonical, comparable serialization of a Yjs XML node (structure + text +
+ * marks + attributes), with attribute keys sorted so equal blocks always produce
+ * an identical string regardless of attribute insertion order. The volatile
+ * block `id` (see `VOLATILE_KEY_ATTRS`) and every schema-default attribute (see
+ * `getMergeSchema`) are excluded at every level — on element attributes AND on
+ * the mark attributes inside each XmlText delta — so a block compares equal by
+ * CONTENT across the git round-trip (which materializes neither), keeping the
+ * merge anchor-able and idempotent.
+ */
+export function serializeXmlNode(node: unknown): unknown {
+  if (node instanceof Y.XmlText) {
+    return { t: normalizeDelta(node.toDelta()) };
+  }
+  if (node instanceof Y.XmlElement) {
+    const attrs = node.getAttributes() as Record<string, unknown>;
+    const attrSpecs = getMergeSchema()?.nodes[node.nodeName]?.spec.attrs as
+      | Record<string, any>
+      | undefined;
+    const sorted: Record<string, unknown> = {};
+    for (const k of Object.keys(attrs).sort()) {
+      if (VOLATILE_KEY_ATTRS.has(k)) continue;
+      if (isDefaultAttr(attrSpecs, k, attrs[k])) continue;
+      sorted[k] = attrs[k];
+    }
+    return {
+      n: node.nodeName,
+      a: sorted,
+      c: node.toArray().map(serializeXmlNode),
+    };
+  }
+  // XmlHook / unknown: fall back to a stable string so it compares by identity
+  // of its serialized form (these do not occur in the Docmost block schema).
+  return { u: String(node) };
+}
+
+const key = (node: unknown): string => JSON.stringify(serializeXmlNode(node));
+
+/**
+ * Deep-clone a detached/owned Yjs XML node into a fresh node that can be inserted
+ * into ANOTHER document (Yjs types are bound to their doc, so cross-doc moves are
+ * impossible — we rebuild). Preserves nodeName, attributes, text+marks (via the
+ * XmlText delta) and the full child subtree.
+ */
+export function cloneXmlNode(node: XmlNode): Y.XmlElement | Y.XmlText {
+  if (node instanceof Y.XmlText) {
+    const t = new Y.XmlText();
+    const delta = node.toDelta();
+    if (delta.length) t.applyDelta(delta);
+    return t;
+  }
+  if (node instanceof Y.XmlElement) {
+    const el = new Y.XmlElement(node.nodeName);
+    const attrs = node.getAttributes() as Record<string, unknown>;
+    for (const k of Object.keys(attrs)) el.setAttribute(k, attrs[k] as string);
+    const kids = node.toArray().map((c) => cloneXmlNode(c as XmlNode));
+    if (kids.length) el.insert(0, kids);
+    return el;
+  }
+  // Best-effort for any other node type (XmlHook — does not occur in the
+  // Docmost block schema): an empty paragraph so the merge never crashes.
+  return new Y.XmlElement('paragraph');
+}
+
+type Op = { op: 'keep' } | { op: 'del' } | { op: 'ins'; bi: number };
+
+/**
+ * LCS-based edit script turning sequence `a` (live block keys) into `b` (incoming
+ * block keys): a run of keep/del/ins ops. O(n*m) table — fine for page block
+ * counts.
+ */
+export function diffBlocks(a: string[], b: string[]): Op[] {
+  const n = a.length;
+  const m = b.length;
+  const dp = buildLcsTable(a, b);
+  const ops: Op[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ op: 'keep' });
+      i++;
+      j++;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      ops.push({ op: 'del' });
+      i++;
+    } else {
+      ops.push({ op: 'ins', bi: j });
+      j++;
+    }
+  }
+  while (i < n) {
+    ops.push({ op: 'del' });
+    i++;
+  }
+  while (j < m) {
+    ops.push({ op: 'ins', bi: j });
+    j++;
+  }
+  return ops;
+}
+
+/**
+ * Merge `target` block children into `live`, mutating `live` in place with the
+ * minimal set of inserts/deletes. MUST be called inside a Yjs transaction.
+ * Returns the number of block operations applied (0 == content already identical).
+ */
+export function mergeXmlFragments(
+  live: Y.XmlFragment,
+  target: Y.XmlFragment,
+): number {
+  const liveKids = live.toArray();
+  const targetKids = target.toArray();
+  const liveKeys = liveKids.map(key);
+  const targetKeys = targetKids.map(key);
+
+  const ops = diffBlocks(liveKeys, targetKeys);
+
+  let cursor = 0; // index into the LIVE fragment as we mutate it
+  let applied = 0;
+  for (const op of ops) {
+    if (op.op === 'keep') {
+      cursor++;
+    } else if (op.op === 'del') {
+      live.delete(cursor, 1); // remove the live block at the cursor; do not advance
+      applied++;
+    } else {
+      live.insert(cursor, [cloneXmlNode(targetKids[op.bi] as XmlNode)]);
+      cursor++;
+      applied++;
+    }
+  }
+  return applied;
+}
+
+/** Outcome of a 3-way block merge: ops applied + same-block conflict count. */
+export interface Merge3WayResult {
+  /** Number of block insert/delete operations spliced into `live`. */
+  applied: number;
+  /**
+   * Regions where the human AND git rewrote the SAME base block. The rule is
+   * deterministic (GIT WINS the region), so the human's version of those blocks
+   * is dropped from the live doc. `conflicts > 0` is the OBSERVABLE signal the
+   * caller uses to LOG the loss and pin the human baseline to page history (so it
+   * is recoverable), instead of the edit vanishing silently.
+   */
+  conflicts: number;
+}
+
+/**
+ * THREE-WAY block merge: reconcile `live` toward `target` using `base` (the
+ * last-synced common ancestor) so a block only the human changed is KEPT and a
+ * block only git changed is taken — instead of git's version always winning
+ * (review #5). Conflicts (both changed the same block) resolve to git.
+ *
+ * Implementation: diff3Plan computes the merged block ORDER (picks from live or
+ * target); we materialize that as a virtual target fragment and reuse the 2-way
+ * `mergeXmlFragments` to splice it into `live` minimally (so untouched live block
+ * instances — and their in-flight edits — stay put). MUST be called inside a Yjs
+ * transaction. Returns the number of block operations applied. (Use
+ * `mergeXmlFragments3WayWithStats` when the SAME-BLOCK conflict count is needed.)
+ */
+export function mergeXmlFragments3Way(
+  live: Y.XmlFragment,
+  target: Y.XmlFragment,
+  base: Y.XmlFragment,
+): number {
+  return mergeXmlFragments3WayWithStats(live, target, base).applied;
+}
+
+/**
+ * As `mergeXmlFragments3Way`, but also returns the SAME-BLOCK conflict count so
+ * the caller can make a "git won a concurrent same-block edit" event OBSERVABLE
+ * (the documented conflict contract: git wins deterministically, but the losing
+ * human content is never destroyed silently — it is logged and recoverable via
+ * page history).
+ */
+export function mergeXmlFragments3WayWithStats(
+  live: Y.XmlFragment,
+  target: Y.XmlFragment,
+  base: Y.XmlFragment,
+): Merge3WayResult {
+  const liveKids = live.toArray();
+  const targetKids = target.toArray();
+  const liveKeys = liveKids.map(key);
+  const targetKeys = targetKids.map(key);
+  const baseKeys = base.toArray().map(key);
+
+  const { picks: plan, conflicts } = diff3PlanWithConflicts(
+    baseKeys,
+    liveKeys,
+    targetKeys,
+  );
+
+  // Build the merged block sequence in a throwaway doc, cloning from whichever
+  // side each pick came from, then 2-way merge it back into the live fragment.
+  const merged = new Y.Doc();
+  const mergedFrag = merged.getXmlFragment('default');
+  const nodes = plan.map((p) =>
+    cloneXmlNode(
+      (p.src === 'live' ? liveKids[p.index] : targetKids[p.index]) as XmlNode,
+    ),
+  );
+  if (nodes.length) mergedFrag.insert(0, nodes);
+
+  return { applied: mergeXmlFragments(live, mergedFrag), conflicts };
+}

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

@@ -0,0 +1,278 @@
+import * as Y from 'yjs';
+import { getSchema } from '@tiptap/core';
+import {
+  initProseMirrorDoc,
+  absolutePositionToRelativePosition,
+  prosemirrorJSONToYDoc,
+} from '@tiptap/y-tiptap';
+import { tiptapExtensions } from './collaboration.util';
+import {
+  setYjsMark,
+  removeYjsMarkByAttribute,
+  updateYjsMarkAttribute,
+  type YjsSelection,
+} from './yjs.util';
+
+/**
+ * Unit tests for the server-side Yjs mark helpers used by the collaboration
+ * handler to set/resolve/delete comment marks directly on the shared Y.Doc
+ * (collaboration.handler.ts: setCommentMark / resolveCommentMark).
+ *
+ * The fragment shape mirrors production exactly: a `default` XmlFragment whose
+ * children are block XmlElements (paragraph) holding XmlText runs. For setYjsMark
+ * the selection is a pair of Yjs RelativePosition JSONs (what the client sends);
+ * we synthesize them from known ProseMirror absolute positions via
+ * absolutePositionToRelativePosition so the marked range is deterministic.
+ */
+
+const schema = getSchema(tiptapExtensions);
+
+// Build a real Y.Doc from ProseMirror JSON (same path the collab handler uses
+// via TiptapTransformer) and return the doc + its `default` fragment.
+function buildFromPm(pmJson: unknown) {
+  const ydoc = prosemirrorJSONToYDoc(
+    schema,
+    pmJson as never,
+    'default',
+  ) as unknown as Y.Doc;
+  const fragment = ydoc.getXmlFragment('default');
+  return { ydoc, fragment };
+}
+
+// Make a YjsSelection (anchor/head RelativePosition JSON) for two ProseMirror
+// absolute positions in `fragment`.
+function selectionFor(
+  fragment: Y.XmlFragment,
+  anchorPos: number,
+  headPos: number,
+): YjsSelection {
+  const { mapping } = initProseMirrorDoc(fragment, schema);
+  const anchor = absolutePositionToRelativePosition(
+    anchorPos,
+    fragment as never,
+    mapping,
+  );
+  const head = absolutePositionToRelativePosition(
+    headPos,
+    fragment as never,
+    mapping,
+  );
+  return {
+    anchor: Y.relativePositionToJSON(anchor),
+    head: Y.relativePositionToJSON(head),
+  };
+}
+
+// The XmlText run of the i-th top-level paragraph.
+function paragraphText(fragment: Y.XmlFragment, index = 0): Y.XmlText {
+  const para = fragment.get(index) as Y.XmlElement;
+  return para.get(0) as Y.XmlText;
+}
+
+// --- raw fragment builder for the remove/update tests (no schema needed) ---
+//
+// removeYjsMarkByAttribute / updateYjsMarkAttribute only read item.toDelta() and
+// call item.format(); they never touch the ProseMirror schema. Build the runs
+// directly so we control which segment carries which comment attrs.
+function buildWithComments(
+  segments: Array<{
+    text: string;
+    comment?: { commentId: string; resolved: boolean };
+  }>,
+): { fragment: Y.XmlFragment; text: Y.XmlText } {
+  const ydoc = new Y.Doc();
+  const fragment = ydoc.getXmlFragment('default');
+  const para = new Y.XmlElement('paragraph');
+  fragment.insert(0, [para]);
+  const text = new Y.XmlText();
+  para.insert(0, [text]);
+  let offset = 0;
+  for (const seg of segments) {
+    text.insert(offset, seg.text);
+    if (seg.comment) {
+      text.format(offset, seg.text.length, { comment: seg.comment });
+    }
+    offset += seg.text.length;
+  }
+  return { fragment, text };
+}
+
+describe('setYjsMark', () => {
+  it('applies the mark over exactly the selected sub-range (PM pos 1..6 = "Hello")', () => {
+    const { ydoc, fragment } = buildFromPm({
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'Hello world' }] },
+      ],
+    });
+    // PM pos 1 = start of the paragraph text; pos 6 = just after "Hello".
+    const sel = selectionFor(fragment, 1, 6);
+
+    setYjsMark(ydoc as never, fragment, sel, 'comment', {
+      commentId: 'c1',
+      resolved: false,
+    });
+
+    // The run splits: "Hello" carries the comment mark, " world" stays clean.
+    expect(paragraphText(fragment).toDelta()).toEqual([
+      {
+        insert: 'Hello',
+        attributes: { comment: { commentId: 'c1', resolved: false } },
+      },
+      { insert: ' world' },
+    ]);
+  });
+
+  it('normalizes a reversed selection (head before anchor) to the same range', () => {
+    const { ydoc, fragment } = buildFromPm({
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'Hello world' }] },
+      ],
+    });
+    // anchor=6, head=1 — reversed; setYjsMark takes min/max so it marks "Hello".
+    const sel = selectionFor(fragment, 6, 1);
+
+    setYjsMark(ydoc as never, fragment, sel, 'comment', {
+      commentId: 'c2',
+      resolved: false,
+    });
+
+    expect(paragraphText(fragment).toDelta()).toEqual([
+      {
+        insert: 'Hello',
+        attributes: { comment: { commentId: 'c2', resolved: false } },
+      },
+      { insert: ' world' },
+    ]);
+  });
+
+  it('marks across two paragraphs (range spans an element boundary)', () => {
+    const { ydoc, fragment } = buildFromPm({
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'aaa' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'bbb' }] },
+      ],
+    });
+    // PM positions: "aaa" = 1..4; the </p><p> boundary consumes pos 4 and 5, so
+    // "bbb" starts at pos 6 (chars at 6,7,8). Select pos 2 (inside "aaa") to pos
+    // 8 (after the second "b").
+    const sel = selectionFor(fragment, 2, 8);
+
+    setYjsMark(ydoc as never, fragment, sel, 'comment', {
+      commentId: 'c3',
+      resolved: false,
+    });
+
+    // First paragraph: "a" clean, "aa" marked.
+    expect(paragraphText(fragment, 0).toDelta()).toEqual([
+      { insert: 'a' },
+      {
+        insert: 'aa',
+        attributes: { comment: { commentId: 'c3', resolved: false } },
+      },
+    ]);
+    // Second paragraph: "bb" marked, "b" clean.
+    expect(paragraphText(fragment, 1).toDelta()).toEqual([
+      {
+        insert: 'bb',
+        attributes: { comment: { commentId: 'c3', resolved: false } },
+      },
+      { insert: 'b' },
+    ]);
+  });
+});
+
+describe('removeYjsMarkByAttribute', () => {
+  it('removes only the run whose attribute value matches, leaving others', () => {
+    const { fragment, text } = buildWithComments([
+      { text: 'AAA', comment: { commentId: 'c1', resolved: false } },
+      { text: 'BBB', comment: { commentId: 'c2', resolved: false } },
+    ]);
+
+    removeYjsMarkByAttribute(fragment, 'comment', 'commentId', 'c1');
+
+    // c1's run loses the mark; c2's run is untouched.
+    expect(text.toDelta()).toEqual([
+      { insert: 'AAA' },
+      {
+        insert: 'BBB',
+        attributes: { comment: { commentId: 'c2', resolved: false } },
+      },
+    ]);
+  });
+
+  it('does nothing when no run carries the requested value (no-match branch)', () => {
+    const { fragment, text } = buildWithComments([
+      { text: 'AAA', comment: { commentId: 'c1', resolved: false } },
+    ]);
+    const before = text.toDelta();
+
+    removeYjsMarkByAttribute(fragment, 'comment', 'commentId', 'does-not-exist');
+
+    expect(text.toDelta()).toEqual(before);
+  });
+
+  it('leaves a different mark type alone', () => {
+    // A run carrying only `bold` must survive a comment removal pass.
+    const ydoc = new Y.Doc();
+    const fragment = ydoc.getXmlFragment('default');
+    const para = new Y.XmlElement('paragraph');
+    fragment.insert(0, [para]);
+    const text = new Y.XmlText();
+    para.insert(0, [text]);
+    text.insert(0, 'XYZ');
+    text.format(0, 3, { bold: true });
+
+    removeYjsMarkByAttribute(fragment, 'comment', 'commentId', 'c1');
+
+    expect(text.toDelta()).toEqual([
+      { insert: 'XYZ', attributes: { bold: true } },
+    ]);
+  });
+});
+
+describe('updateYjsMarkAttribute', () => {
+  it('merges new attributes into the matching run, preserving the rest', () => {
+    const { fragment, text } = buildWithComments([
+      { text: 'AAA', comment: { commentId: 'c1', resolved: false } },
+      { text: 'BBB', comment: { commentId: 'c2', resolved: false } },
+    ]);
+
+    updateYjsMarkAttribute(
+      fragment,
+      'comment',
+      { name: 'commentId', value: 'c1' },
+      { resolved: true },
+    );
+
+    // c1's run flips resolved=true (commentId preserved via merge); c2 untouched.
+    expect(text.toDelta()).toEqual([
+      {
+        insert: 'AAA',
+        attributes: { comment: { commentId: 'c1', resolved: true } },
+      },
+      {
+        insert: 'BBB',
+        attributes: { comment: { commentId: 'c2', resolved: false } },
+      },
+    ]);
+  });
+
+  it('does nothing when no run matches (no-match branch)', () => {
+    const { fragment, text } = buildWithComments([
+      { text: 'AAA', comment: { commentId: 'c1', resolved: false } },
+    ]);
+    const before = text.toDelta();
+
+    updateYjsMarkAttribute(
+      fragment,
+      'comment',
+      { name: 'commentId', value: 'nope' },
+      { resolved: true },
+    );
+
+    expect(text.toDelta()).toEqual(before);
+  });
+});

apps/server/src/common/decorators/auth-provenance.decorator.spec.ts

@@ -73,6 +73,32 @@ describe('agentSourceFields', () => {
     ).toEqual({ lastUpdatedSource: 'agent', lastUpdatedAiChatId: null });
   });
 
+  it("stamps ONLY the source column 'git-sync' (no chat key) for a git-sync write", () => {
+    // The git-sync data plane (issue #194 §8.1) has no internal ai_chats row, so
+    // it stamps the *Source column 'git-sync' and OMITS the chat key entirely
+    // (unlike the agent branch, which also writes aiChatId). Pinned directly here
+    // because the page.service.spec only exercises it indirectly.
+    expect(
+      agentSourceFields(
+        { actor: 'git-sync', aiChatId: null },
+        'lastUpdatedSource',
+        'lastUpdatedAiChatId',
+      ),
+    ).toEqual({ lastUpdatedSource: 'git-sync' });
+  });
+
+  it("ignores any aiChatId on a git-sync write (chat key never written)", () => {
+    // Even if a non-null aiChatId is present, the git-sync branch must not emit
+    // the chat key.
+    expect(
+      agentSourceFields(
+        { actor: 'git-sync', aiChatId: 'should-be-ignored' },
+        'createdSource',
+        'aiChatId',
+      ),
+    ).toEqual({ createdSource: 'git-sync' });
+  });
+
   it('returns {} for a user write so the column keeps its default', () => {
     expect(
       agentSourceFields(

apps/server/src/common/decorators/auth-provenance.decorator.ts

@@ -9,6 +9,8 @@ import { ProvenanceSource } from '../../core/auth/dto/jwt-payload';
  * cannot fake an 'agent' marker.
  */
 export interface AuthProvenanceData {
+  // ProvenanceSource includes 'git-sync' — set by the in-process git-sync data
+  // plane (issue #194 §8.1) when it drives PageService writes; never from a request token.
   actor: ProvenanceSource;
   aiChatId: string | null;
 }
@@ -60,6 +62,14 @@ export function agentSourceFields<S extends string, C extends string>(
   sourceKey: S,
   chatKey: C,
 ): Partial<Record<S, ProvenanceSource> & Record<C, string | null>> {
+  // git-sync data-plane write (issue #194 §8.1): stamp the source 'git-sync' with NO
+  // aiChatId (it has no internal ai_chats row). Mirrors the agent branch; each
+  // write has a single actor, so precedence is irrelevant here.
+  if (provenance?.actor === 'git-sync') {
+    return { [sourceKey]: 'git-sync' } as Partial<
+      Record<S, ProvenanceSource> & Record<C, string | null>
+    >;
+  }
   if (provenance?.actor !== 'agent') return {};
   return {
     [sourceKey]: 'agent',

apps/server/src/common/helpers/esm-import.ts

@@ -0,0 +1,18 @@
+/**
+ * Dynamic ESM import bridge for a CommonJS build.
+ *
+ * The server compiles with `module: commonjs`, and TypeScript downlevels a
+ * literal `import()` expression to `require()` — which cannot load an ESM-only
+ * package (`@docmost/mcp`, `@docmost/git-sync`). Indirecting through `new
+ * Function` hides the `import()` from the TS downleveler so the REAL dynamic
+ * `import()` survives to runtime and can load ESM from CommonJS.
+ *
+ * This is the single shared copy of that bridge. The per-package typed loaders
+ * (git-sync.loader.ts, docmost-client.loader.ts, mcp.service.ts) import this and
+ * keep their own typed `loadX()` wrappers (require.resolve + pathToFileURL +
+ * memoization) on top.
+ */
+export const esmImport = new Function(
+  'specifier',
+  'return import(specifier)',
+) as (specifier: string) => Promise<unknown>;

apps/server/src/common/helpers/resolve-request-workspace.spec.ts

@@ -0,0 +1,71 @@
+import { resolveRequestWorkspace } from './resolve-request-workspace';
+
+// Unit tests for the shared self-hosted/cloud workspace resolver deduplicated out
+// of DomainMiddleware + GitHttpService (architecture #11). They must behave
+// identically, so this pins the single source of truth.
+
+type AnyMock = jest.Mock;
+
+function build(opts: {
+  selfHosted: boolean;
+  first?: { id: string } | null;
+  byHostname?: { id: string } | null;
+}) {
+  const env = {
+    isSelfHosted: jest.fn(() => opts.selfHosted),
+    isCloud: jest.fn(() => !opts.selfHosted),
+  };
+  const repo = {
+    findFirst: jest.fn(async () => opts.first ?? null) as AnyMock,
+    findByHostname: jest.fn(async () => opts.byHostname ?? null) as AnyMock,
+  };
+  return { env, repo };
+}
+
+describe('resolveRequestWorkspace', () => {
+  it('self-hosted: returns the first/default workspace, ignoring the host', async () => {
+    const { env, repo } = build({ selfHosted: true, first: { id: 'ws-1' } });
+    const ws = await resolveRequestWorkspace(
+      env as any,
+      repo as any,
+      'anything.example.com',
+    );
+    expect(ws).toEqual({ id: 'ws-1' });
+    expect(repo.findFirst).toHaveBeenCalledTimes(1);
+    expect(repo.findByHostname).not.toHaveBeenCalled();
+  });
+
+  it('self-hosted: returns null when no workspace is configured', async () => {
+    const { env, repo } = build({ selfHosted: true, first: null });
+    expect(await resolveRequestWorkspace(env as any, repo as any, 'h')).toBeNull();
+  });
+
+  it('cloud: resolves by the host-header subdomain', async () => {
+    const { env, repo } = build({
+      selfHosted: false,
+      byHostname: { id: 'ws-acme' },
+    });
+    const ws = await resolveRequestWorkspace(
+      env as any,
+      repo as any,
+      'acme.example.com',
+    );
+    expect(ws).toEqual({ id: 'ws-acme' });
+    expect(repo.findByHostname).toHaveBeenCalledWith('acme');
+    expect(repo.findFirst).not.toHaveBeenCalled();
+  });
+
+  it('cloud: returns null for a blank/missing host (no throw)', async () => {
+    const { env, repo } = build({ selfHosted: false, byHostname: { id: 'x' } });
+    expect(await resolveRequestWorkspace(env as any, repo as any, undefined)).toBeNull();
+    expect(await resolveRequestWorkspace(env as any, repo as any, '')).toBeNull();
+    expect(repo.findByHostname).not.toHaveBeenCalled();
+  });
+
+  it('cloud: returns null when the subdomain matches no workspace', async () => {
+    const { env, repo } = build({ selfHosted: false, byHostname: null });
+    expect(
+      await resolveRequestWorkspace(env as any, repo as any, 'ghost.example.com'),
+    ).toBeNull();
+  });
+});

apps/server/src/common/helpers/resolve-request-workspace.ts

@@ -0,0 +1,35 @@
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
+import { Workspace } from '@docmost/db/types/entity.types';
+import { EnvironmentService } from '../../integrations/environment/environment.service';
+
+/**
+ * The ONE canonical way to resolve the workspace for an incoming request:
+ *   - self-hosted (single workspace) -> the first/default workspace;
+ *   - cloud (multi-tenant)           -> resolved by the host-header subdomain.
+ * Returns null when none resolves (no workspace configured, or a blank/unknown
+ * subdomain on cloud). `isSelfHosted()` is `!isCloud()`, so exactly one branch is
+ * always taken.
+ *
+ * Extracted so the self-hosted/cloud branch is not hand-duplicated. Shared by
+ * `DomainMiddleware` (the normal /api request path) and `GitHttpService` (the raw
+ * root-mounted /git smart-HTTP host, which Nest middleware does NOT run for) so
+ * the two cannot drift.
+ *
+ * This helper does NOT catch DB errors — callers decide: DomainMiddleware lets a
+ * throw bubble (as before); GitHttpService wraps it to log + treat as
+ * unresolvable (-> 404). A blank/missing host on cloud resolves to null rather
+ * than throwing.
+ */
+export async function resolveRequestWorkspace(
+  environmentService: EnvironmentService,
+  workspaceRepo: WorkspaceRepo,
+  hostHeader: string | undefined,
+): Promise<Workspace | null> {
+  if (environmentService.isSelfHosted()) {
+    return (await workspaceRepo.findFirst()) ?? null;
+  }
+  // Cloud (isSelfHosted === !isCloud, so this is the only remaining branch).
+  const subdomain = hostHeader ? hostHeader.split('.')[0] : '';
+  if (!subdomain) return null;
+  return (await workspaceRepo.findByHostname(subdomain)) ?? null;
+}

apps/server/src/common/middlewares/domain.middleware.ts

@@ -1,7 +1,8 @@
-import { Injectable, NestMiddleware, NotFoundException } from '@nestjs/common';
+import { Injectable, NestMiddleware } from '@nestjs/common';
 import { FastifyRequest, FastifyReply } from 'fastify';
 import { EnvironmentService } from '../../integrations/environment/environment.service';
 import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
+import { resolveRequestWorkspace } from '../helpers/resolve-request-workspace';
 
 @Injectable()
 export class DomainMiddleware implements NestMiddleware {
@@ -14,30 +15,19 @@ export class DomainMiddleware implements NestMiddleware {
     res: FastifyReply['raw'],
     next: () => void,
   ) {
-    if (this.environmentService.isSelfHosted()) {
-      const workspace = await this.workspaceRepo.findFirst();
-      if (!workspace) {
-        //throw new NotFoundException('Workspace not found');
-        (req as any).workspaceId = null;
-        return next();
-      }
-
-      // TODO: unify
-      (req as any).workspaceId = workspace.id;
-      (req as any).workspace = workspace;
-    } else if (this.environmentService.isCloud()) {
-      const header = req.headers.host;
-      const subdomain = header.split('.')[0];
-
-      const workspace = await this.workspaceRepo.findByHostname(subdomain);
-
-      if (!workspace) {
-        (req as any).workspaceId = null;
-        return next();
-      }
+    // Shared self-hosted/cloud resolution (the SAME branch the /git host uses),
+    // so the logic cannot drift between the two.
+    const workspace = await resolveRequestWorkspace(
+      this.environmentService,
+      this.workspaceRepo,
+      req.headers.host,
+    );
 
+    if (workspace) {
       (req as any).workspaceId = workspace.id;
       (req as any).workspace = workspace;
+    } else {
+      (req as any).workspaceId = null;
     }
 
     next();

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

@@ -3,6 +3,8 @@ import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { PageEmbeddingRepo } from '@docmost/db/repos/ai-chat/page-embedding.repo';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
 import { AiService } from '../../../integrations/ai/ai.service';
+import { EmbeddingReindexProgressService } from '../../../integrations/ai/embedding-reindex-progress.service';
+import { AiEmbeddingNotConfiguredException } from '../../../integrations/ai/ai-embedding-not-configured.exception';
 
 /**
  * Unit tests for EmbeddingIndexerService.reindexWorkspace's batch control flow.
@@ -12,7 +14,8 @@ import { AiService } from '../../../integrations/ai/ai.service';
  * reindexWorkspace actually touches:
  *   - aiService.getEmbeddingModel -> a model string so the up-front configured
  *     check passes,
- *   - pageRepo.getIdsByWorkspace -> three page ids,
+ *   - pageRepo.getEmbeddablePageIds -> three page ids (the embeddable set the
+ *     reindex iterates),
  *   - service.reindexPage -> spied per test to drive the per-page outcome.
  *
  * The point under test is the catch block: a FATAL provider error (auth/billing)
@@ -24,21 +27,30 @@ describe('EmbeddingIndexerService.reindexWorkspace fail-fast', () => {
 
   function makeService() {
     const pageRepo = {
-      getIdsByWorkspace: jest.fn().mockResolvedValue(['p1', 'p2', 'p3']),
+      getEmbeddablePageIds: jest.fn().mockResolvedValue(['p1', 'p2', 'p3']),
     };
     const pageEmbeddingRepo = {};
     const aiService = {
       getEmbeddingModel: jest.fn().mockResolvedValue('some-model'),
     };
+    // Progress is a best-effort cosmetic store; mock its async methods so the
+    // batch control flow can be tested without Redis.
+    const reindexProgress = {
+      start: jest.fn().mockResolvedValue(undefined),
+      increment: jest.fn().mockResolvedValue(undefined),
+      clear: jest.fn().mockResolvedValue(undefined),
+      get: jest.fn().mockResolvedValue(null),
+    };
     const db = {};
 
     const service = new EmbeddingIndexerService(
       pageRepo as unknown as PageRepo,
       pageEmbeddingRepo as unknown as PageEmbeddingRepo,
       aiService as unknown as AiService,
+      reindexProgress as unknown as EmbeddingReindexProgressService,
       db as unknown as KyselyDB,
     );
-    return { service, pageRepo, aiService };
+    return { service, pageRepo, aiService, reindexProgress };
   }
 
   it('aborts after the first page on a FATAL (401) provider error', async () => {
@@ -78,3 +90,100 @@ describe('EmbeddingIndexerService.reindexWorkspace fail-fast', () => {
     expect(reindexPage).toHaveBeenCalledTimes(3);
   });
 });
+
+/**
+ * Live reindex-progress reporting: reindexWorkspace must publish a per-workspace
+ * progress record (total at start, done incremented per processed page) and ALWAYS
+ * clear it in a finally — including on a fatal abort and an unconfigured early
+ * return — so the settings status can show the counter climb without ever getting
+ * stuck in a "reindexing" state.
+ */
+describe('EmbeddingIndexerService.reindexWorkspace progress', () => {
+  const WORKSPACE_ID = 'ws-1';
+
+  function makeService(pageIds: string[] = ['p1', 'p2', 'p3']) {
+    const pageRepo = {
+      getEmbeddablePageIds: jest.fn().mockResolvedValue(pageIds),
+    };
+    const pageEmbeddingRepo = {};
+    const aiService = {
+      getEmbeddingModel: jest.fn().mockResolvedValue('some-model'),
+    };
+    const reindexProgress = {
+      start: jest.fn().mockResolvedValue(undefined),
+      increment: jest.fn().mockResolvedValue(undefined),
+      clear: jest.fn().mockResolvedValue(undefined),
+      get: jest.fn().mockResolvedValue(null),
+    };
+    const db = {};
+    const service = new EmbeddingIndexerService(
+      pageRepo as unknown as PageRepo,
+      pageEmbeddingRepo as unknown as PageEmbeddingRepo,
+      aiService as unknown as AiService,
+      reindexProgress as unknown as EmbeddingReindexProgressService,
+      db as unknown as KyselyDB,
+    );
+    return { service, pageRepo, aiService, reindexProgress };
+  }
+
+  it('sets total at start, increments done per page, and clears in finally', async () => {
+    const { service, reindexProgress } = makeService(['p1', 'p2', 'p3']);
+    jest.spyOn(service, 'reindexPage').mockResolvedValue(undefined);
+
+    await service.reindexWorkspace(WORKSPACE_ID);
+
+    expect(reindexProgress.start).toHaveBeenCalledWith(WORKSPACE_ID, 3);
+    // One increment per processed page.
+    expect(reindexProgress.increment).toHaveBeenCalledTimes(3);
+    expect(reindexProgress.increment).toHaveBeenCalledWith(WORKSPACE_ID);
+    // Cleared exactly once on completion.
+    expect(reindexProgress.clear).toHaveBeenCalledTimes(1);
+    expect(reindexProgress.clear).toHaveBeenCalledWith(WORKSPACE_ID);
+  });
+
+  it('counts a handled (non-fatal) per-page failure as processed', async () => {
+    const { service, reindexProgress } = makeService(['p1', 'p2', 'p3']);
+    // No statusCode -> non-fatal -> isolate and continue; each counts as done.
+    jest.spyOn(service, 'reindexPage').mockRejectedValue(new Error('boom'));
+
+    await service.reindexWorkspace(WORKSPACE_ID);
+
+    expect(reindexProgress.increment).toHaveBeenCalledTimes(3);
+    expect(reindexProgress.clear).toHaveBeenCalledTimes(1);
+  });
+
+  it('clears progress in finally even when a FATAL provider error aborts the batch', async () => {
+    const { service, reindexProgress } = makeService(['p1', 'p2', 'p3']);
+    // A 401 aborts on the first page (re-thrown) — the finally must still clear.
+    jest
+      .spyOn(service, 'reindexPage')
+      .mockRejectedValue({ statusCode: 401, message: 'User not found' });
+
+    await expect(service.reindexWorkspace(WORKSPACE_ID)).rejects.toMatchObject({
+      statusCode: 401,
+    });
+
+    expect(reindexProgress.start).toHaveBeenCalledWith(WORKSPACE_ID, 3);
+    // Aborted page is NOT counted as processed.
+    expect(reindexProgress.increment).not.toHaveBeenCalled();
+    // But progress is still cleared so the run never gets stuck.
+    expect(reindexProgress.clear).toHaveBeenCalledTimes(1);
+  });
+
+  it('clears the enqueue-seeded progress on an unconfigured early return', async () => {
+    const { service, aiService, reindexProgress } = makeService();
+    // Embeddings not configured: reindexWorkspace returns early WITHOUT starting
+    // a fresh record, but the finally must still clear the enqueue-time seed.
+    aiService.getEmbeddingModel = jest
+      .fn()
+      .mockRejectedValue(new AiEmbeddingNotConfiguredException());
+
+    await expect(
+      service.reindexWorkspace(WORKSPACE_ID),
+    ).resolves.toBeUndefined();
+
+    expect(reindexProgress.start).not.toHaveBeenCalled();
+    expect(reindexProgress.clear).toHaveBeenCalledTimes(1);
+    expect(reindexProgress.clear).toHaveBeenCalledWith(WORKSPACE_ID);
+  });
+});

apps/server/src/core/ai-chat/embedding/embedding-indexer.service.ts

@@ -9,6 +9,7 @@ import { KyselyDB } from '@docmost/db/types/kysely.types';
 import { InjectKysely } from 'nestjs-kysely';
 import { executeTx } from '@docmost/db/utils';
 import { AiService } from '../../../integrations/ai/ai.service';
+import { EmbeddingReindexProgressService } from '../../../integrations/ai/embedding-reindex-progress.service';
 import { AiEmbeddingNotConfiguredException } from '../../../integrations/ai/ai-embedding-not-configured.exception';
 import {
   describeProviderError,
@@ -48,6 +49,7 @@ export class EmbeddingIndexerService {
     private readonly pageRepo: PageRepo,
     private readonly pageEmbeddingRepo: PageEmbeddingRepo,
     private readonly aiService: AiService,
+    private readonly reindexProgress: EmbeddingReindexProgressService,
     @InjectKysely() private readonly db: KyselyDB,
   ) {}
 
@@ -183,7 +185,19 @@ export class EmbeddingIndexerService {
   }
 
   /**
-   * (Re)build embeddings for EVERY non-deleted page in a workspace. Used by the
+   * (Re)build embeddings for the EMBEDDABLE page set of a workspace — the same
+   * set countEmbeddablePages counts (via getEmbeddablePageIds): non-deleted pages
+   * that qualify under any of the three clauses of `embeddablePredicate` —
+   * non-empty textContent, OR an empty/null textContent whose ProseMirror
+   * `content` JSON has at least one text node (`"type":"text"`) that `jsonToText`
+   * can extract, OR an already-stored (non-deleted) embedding row — NOT every
+   * non-deleted page. Iterating this set keeps the live `total` equal to the
+   * steady-state denominator, so the progress counter climbs 0 -> total and
+   * matches the before/after DB coverage exactly. A page with truly no
+   * extractable text (empty textContent AND content with only non-text/atom
+   * nodes such as math) is correctly skipped (reindexPage no-ops on it); a page
+   * that lost its text but still has stale embeddings stays in the set (the
+   * EXISTS clause) so it is visited and its stale rows are cleared. Used by the
    * bulk reindex (WORKSPACE_CREATE_EMBEDDINGS, fired when AI Search is enabled
    * and by the manual "Reindex now" action).
    *
@@ -194,69 +208,99 @@ export class EmbeddingIndexerService {
    * the batch.
    */
   async reindexWorkspace(workspaceId: string): Promise<void> {
+    // The whole run is wrapped so the per-workspace progress record is ALWAYS
+    // cleared in the finally — on success, on a fatal-provider abort, on an
+    // unconfigured early-return, or on any unexpected throw — so a failed run
+    // never leaves a stuck "reindexing" state (the status then falls back to the
+    // steady-state DB coverage count). A placeholder record may already exist
+    // (seeded at enqueue time); the finally cleans that too.
     try {
-      await this.aiService.getEmbeddingModel(workspaceId);
-    } catch (err) {
-      if (err instanceof AiEmbeddingNotConfiguredException) {
-        this.logger.log(
-          `reindexWorkspace: embeddings not configured for workspace ${workspaceId}, skipping`,
-        );
-        return;
-      }
-      throw err;
-    }
-
-    const pageIds = await this.pageRepo.getIdsByWorkspace(workspaceId);
-    const total = pageIds.length;
-    const startedAt = Date.now();
-    this.logger.log(
-      `reindexWorkspace: starting reindex of ${total} page(s) for workspace ${workspaceId}`,
-    );
-
-    let failed = 0;
-    for (let i = 0; i < total; i++) {
-      const pageId = pageIds[i];
-      const position = i + 1;
-      // Log BEFORE the await: if the embedding call hangs, this is the last line
-      // in the log and it names the exact page that is stuck.
-      this.logger.log(
-        `reindexWorkspace: [${position}/${total}] indexing page ${pageId} (workspace ${workspaceId})`,
-      );
-      const pageStartedAt = Date.now();
       try {
-        await this.reindexPage(pageId);
-        const elapsed = Date.now() - pageStartedAt;
-        if (elapsed >= SLOW_PAGE_MS) {
-          this.logger.warn(
-            `reindexWorkspace: [${position}/${total}] page ${pageId} took ${elapsed}ms`,
-          );
-        }
+        await this.aiService.getEmbeddingModel(workspaceId);
       } catch (err) {
-        // A fatal provider error (invalid/missing key, no credits) recurs
-        // identically on EVERY remaining page. Abort the whole batch instead of
-        // issuing hundreds of doomed requests against the provider.
-        if (isFatalProviderError(err)) {
-          this.logger.error(
-            `reindexWorkspace: aborting at [${position}/${total}] for workspace ` +
-              `${workspaceId} — fatal provider error, remaining pages would fail ` +
-              `identically: ${describeProviderError(err)}`,
+        if (err instanceof AiEmbeddingNotConfiguredException) {
+          this.logger.log(
+            `reindexWorkspace: embeddings not configured for workspace ${workspaceId}, skipping`,
           );
-          throw err;
+          return;
         }
-        // Per-page isolation: one non-fatal failure (incl. an embedding timeout)
-        // must not abort the whole batch.
-        failed++;
-        this.logger.error(
-          `reindexWorkspace: [${position}/${total}] failed to reindex page ${pageId} ` +
-            `after ${Date.now() - pageStartedAt}ms: ${describeProviderError(err)}`,
-        );
+        throw err;
       }
-    }
 
-    this.logger.log(
-      `reindexWorkspace: done for workspace ${workspaceId}: ` +
-        `${total - failed}/${total} indexed, ${failed} failed in ${Date.now() - startedAt}ms`,
-    );
+      // Iterate the EMBEDDABLE set (same three-clause predicate as
+      // countEmbeddablePages), NOT every non-deleted page: this makes `total`
+      // here equal the steady-state denominator, so the live counter climbs
+      // 0 -> total and matches the before/after DB count exactly (no
+      // 478 -> 500 -> 478 denominator jump). Pages whose text lives in the
+      // ProseMirror `content` JSON (a text node) even with empty text_content ARE
+      // in this set (the content-JSON clause) and get embedded; a page with no
+      // extractable text at all is correctly skipped — reindexPage no-ops on it —
+      // and a page that lost its text but still has stale embeddings IS in this
+      // set (the EXISTS clause) so it is still visited and its stale rows cleared.
+      const pageIds = await this.pageRepo.getEmbeddablePageIds(workspaceId);
+      const total = pageIds.length;
+      const startedAt = Date.now();
+      // Publish the live run progress over this same set (done reset to 0). The
+      // counter increments once per iterated page and reaches exactly `total`,
+      // which equals countEmbeddablePages — the steady-state denominator.
+      await this.reindexProgress.start(workspaceId, total);
+      this.logger.log(
+        `reindexWorkspace: starting reindex of ${total} page(s) for workspace ${workspaceId}`,
+      );
+
+      let failed = 0;
+      for (let i = 0; i < total; i++) {
+        const pageId = pageIds[i];
+        const position = i + 1;
+        // Log BEFORE the await: if the embedding call hangs, this is the last line
+        // in the log and it names the exact page that is stuck.
+        this.logger.log(
+          `reindexWorkspace: [${position}/${total}] indexing page ${pageId} (workspace ${workspaceId})`,
+        );
+        const pageStartedAt = Date.now();
+        try {
+          await this.reindexPage(pageId);
+          // Count this page as processed (matches the [position/total] log).
+          await this.reindexProgress.increment(workspaceId);
+          const elapsed = Date.now() - pageStartedAt;
+          if (elapsed >= SLOW_PAGE_MS) {
+            this.logger.warn(
+              `reindexWorkspace: [${position}/${total}] page ${pageId} took ${elapsed}ms`,
+            );
+          }
+        } catch (err) {
+          // A fatal provider error (invalid/missing key, no credits) recurs
+          // identically on EVERY remaining page. Abort the whole batch instead of
+          // issuing hundreds of doomed requests against the provider. Do NOT count
+          // it as processed — the run aborts here (the finally clears progress).
+          if (isFatalProviderError(err)) {
+            this.logger.error(
+              `reindexWorkspace: aborting at [${position}/${total}] for workspace ` +
+                `${workspaceId} — fatal provider error, remaining pages would fail ` +
+                `identically: ${describeProviderError(err)}`,
+            );
+            throw err;
+          }
+          // Per-page isolation: one non-fatal failure (incl. an embedding timeout)
+          // must not abort the whole batch. A handled failure still advances the
+          // counter (matches the [position/total] log, so done reaches total).
+          failed++;
+          await this.reindexProgress.increment(workspaceId);
+          this.logger.error(
+            `reindexWorkspace: [${position}/${total}] failed to reindex page ${pageId} ` +
+              `after ${Date.now() - pageStartedAt}ms: ${describeProviderError(err)}`,
+          );
+        }
+      }
+
+      this.logger.log(
+        `reindexWorkspace: done for workspace ${workspaceId}: ` +
+          `${total - failed}/${total} indexed, ${failed} failed in ${Date.now() - startedAt}ms`,
+      );
+    } finally {
+      // Always remove the progress record so the status reverts to the DB count.
+      await this.reindexProgress.clear(workspaceId);
+    }
   }
 
   /** Purge ALL embeddings for a workspace (WORKSPACE_DELETE_EMBEDDINGS). */

apps/server/src/core/ai-chat/external-mcp/mcp-clients.service.spec.ts

@@ -0,0 +1,166 @@
+import { McpClientsService } from './mcp-clients.service';
+
+/**
+ * Unit tests for the two security-critical surfaces of McpClientsService that the
+ * sibling specs (ssrf-guard / validate-resolved-addresses / lease) do NOT cover:
+ *
+ *  1. `decryptHeaders` (private) — FAIL-OPEN behavior. A decrypt/parse failure
+ *     (e.g. APP_SECRET rotated, tampered blob) must NEVER throw and must NEVER
+ *     log the blob: it returns `undefined` so the connect proceeds WITHOUT the
+ *     now-unreadable auth headers (which then 401s and the server is skipped),
+ *     rather than crashing the whole turn.
+ *
+ *  2. `this.guardedFetch` (private, bound to the SSRF-pinned dispatcher) — the
+ *     per-request DNS-rebinding guard. A blocked host (private/loopback/metadata
+ *     IP literal, or an unparseable URL) must REJECT before any socket is opened;
+ *     a public host is allowed through to the real `fetch` with the pinned
+ *     dispatcher attached.
+ *
+ * No network and no DB: the repo + secretBox deps are stubbed, and global `fetch`
+ * is mocked for the single allow-path assertion.
+ */
+
+// Build the service with a SecretBoxService stub whose decryptSecret is supplied
+// per-test. The repo dep is unused by the methods under test.
+function buildService(decryptSecret: (blob: string) => string) {
+  const secretBox = { decryptSecret: jest.fn(decryptSecret) };
+  const service = new McpClientsService({} as never, secretBox as never);
+  return { service, secretBox };
+}
+
+describe('McpClientsService.decryptHeaders', () => {
+  // Reach the private method via the as-any pattern common in these NestJS specs.
+  const callDecrypt = (
+    service: McpClientsService,
+    blob: string | null,
+  ): Record<string, string> | undefined =>
+    (
+      service as unknown as {
+        decryptHeaders: (b: string | null) => Record<string, string> | undefined;
+      }
+    ).decryptHeaders(blob);
+
+  it('returns undefined for a null blob without decrypting', () => {
+    const { service, secretBox } = buildService(() => '{}');
+    expect(callDecrypt(service, null)).toBeUndefined();
+    expect(secretBox.decryptSecret).not.toHaveBeenCalled();
+  });
+
+  it('decrypts a valid blob and keeps only string-valued headers', () => {
+    const { service } = buildService(() =>
+      JSON.stringify({
+        Authorization: 'Bearer abc',
+        'X-Api-Key': 'k',
+        // Non-string values must be dropped, not coerced.
+        count: 5,
+        flag: true,
+        nested: { a: 1 },
+      }),
+    );
+    expect(callDecrypt(service, 'cipher')).toEqual({
+      Authorization: 'Bearer abc',
+      'X-Api-Key': 'k',
+    });
+  });
+
+  it('returns undefined when the decrypted object has no string headers', () => {
+    const { service } = buildService(() => JSON.stringify({ count: 5 }));
+    // No usable headers -> undefined (connect with no auth header), not {}.
+    expect(callDecrypt(service, 'cipher')).toBeUndefined();
+  });
+
+  it('FAILS OPEN: a decrypt error returns undefined instead of throwing', () => {
+    const { service } = buildService(() => {
+      throw new Error('Failed to decrypt secret — APP_SECRET may have changed');
+    });
+    const warnSpy = jest
+      .spyOn(
+        (service as unknown as { logger: { warn: (...a: unknown[]) => void } })
+          .logger,
+        'warn',
+      )
+      .mockImplementation(() => undefined);
+
+    let result: unknown;
+    expect(() => {
+      result = callDecrypt(service, 'tampered-blob');
+    }).not.toThrow();
+    expect(result).toBeUndefined();
+    // It warns (so ops sees degradation) but never logs the blob itself.
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(String(warnSpy.mock.calls[0]?.[0])).not.toContain('tampered-blob');
+  });
+
+  it('FAILS OPEN: malformed JSON (decrypts to non-JSON) returns undefined', () => {
+    const { service } = buildService(() => 'not-json{');
+    jest
+      .spyOn(
+        (service as unknown as { logger: { warn: (...a: unknown[]) => void } })
+          .logger,
+        'warn',
+      )
+      .mockImplementation(() => undefined);
+    expect(callDecrypt(service, 'cipher')).toBeUndefined();
+  });
+});
+
+describe('McpClientsService.guardedFetch (SSRF per-request guard)', () => {
+  // The bound guardedFetch closure lives on the instance as a private field.
+  const guardedFetchOf = (service: McpClientsService) =>
+    (service as unknown as { guardedFetch: typeof fetch }).guardedFetch;
+
+  let fetchSpy: jest.SpiedFunction<typeof fetch>;
+
+  beforeEach(() => {
+    // Any reachable real fetch would be a network call; assert per-test that the
+    // blocked paths never reach it, and stub a Response for the allow path.
+    fetchSpy = jest
+      .spyOn(global, 'fetch')
+      .mockResolvedValue(new Response('ok', { status: 200 }));
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  const blocked: Array<[string, string]> = [
+    ['loopback IPv4', 'http://127.0.0.1/mcp'],
+    ['private 10/8', 'http://10.0.0.5/mcp'],
+    ['private 192.168/16', 'http://192.168.1.1/mcp'],
+    ['cloud metadata link-local', 'http://169.254.169.254/latest/meta-data/'],
+    ['loopback IPv6 (bracketed)', 'http://[::1]:8080/mcp'],
+  ];
+
+  it.each(blocked)(
+    'rejects a request to %s without opening a socket',
+    async (_label, url) => {
+      const { service } = buildService(() => '{}');
+      await expect(guardedFetchOf(service)(url)).rejects.toThrow(
+        /blocked request/,
+      );
+      expect(fetchSpy).not.toHaveBeenCalled();
+    },
+  );
+
+  it('rejects an unparseable URL as a blocked request', async () => {
+    const { service } = buildService(() => '{}');
+    await expect(
+      guardedFetchOf(service)('::: not a url :::'),
+    ).rejects.toThrow('blocked request: invalid URL');
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it('allows a public IP literal and forwards through the pinned dispatcher', async () => {
+    const { service } = buildService(() => '{}');
+    const res = await guardedFetchOf(service)('http://8.8.8.8/mcp');
+
+    expect(res.status).toBe(200);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    // The init MUST carry the SSRF-pinned undici dispatcher (the rebinding pin);
+    // dropping it would let undici do a second, unchecked DNS resolution.
+    const init = fetchSpy.mock.calls[0][1] as RequestInit & {
+      dispatcher?: unknown;
+    };
+    expect(init.dispatcher).toBeDefined();
+  });
+});

apps/server/src/core/ai-chat/roles/ai-agent-roles.service.ts

@@ -187,7 +187,7 @@ export class AiAgentRolesService {
   }
 
   // -------------------------------------------------------------------------
-  // Catalog (admin-only). The catalog is curated, untrusted JSON fetched +
+  // Catalog (admin-only). The catalog is curated, untrusted YAML fetched +
   // validated by AiAgentRolesCatalogProvider; this layer resolves localized
   // text and reconciles a bundle against the workspace's existing roles.
   // -------------------------------------------------------------------------

apps/server/src/core/ai-chat/roles/catalog/ai-agent-roles-catalog.provider.spec.ts

@@ -1,12 +1,23 @@
 import { BadGatewayException, BadRequestException } from '@nestjs/common';
-import { AiAgentRolesCatalogProvider } from './ai-agent-roles-catalog.provider';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import {
+  AiAgentRolesCatalogProvider,
+  isCatalogBundleFile,
+  isCatalogIndex,
+  isCatalogRole,
+} from './ai-agent-roles-catalog.provider';
 
 /**
  * Provider tests against a mocked remote source (no network). They cover the
- * happy read path (fetchIndex / fetchBundle), the malformed-shape rejection,
- * rejection of non-http(s) sources (local sources are gone), and — most
- * importantly — the `^[a-z0-9-]+$` path-traversal guard that runs BEFORE any
- * path/URL is built.
+ * happy read path (fetchIndex / fetchBundle) over the YAML catalog format, the
+ * block-scalar `instructions` round-trip, the malformed-shape rejection, the
+ * malformed-YAML rejection, rejection of non-http(s) sources (local sources are
+ * gone), and — most importantly — the `^[a-z0-9-]+$` path-traversal guard that
+ * runs BEFORE any path/URL is built. Fixtures are serialized with the same
+ * `yaml` library the provider parses with (`stringifyYaml`), so the tests
+ * exercise real YAML, not the JSON subset.
  */
 describe('AiAgentRolesCatalogProvider', () => {
   function makeProvider(source: string) {
@@ -71,7 +82,7 @@ describe('AiAgentRolesCatalogProvider', () => {
     }
 
     it('fetchBundle remote happy path => parses + validates', async () => {
-      const json = JSON.stringify({
+      const yaml = stringifyYaml({
         schemaVersion: 1,
         language: 'en',
         roles: [
@@ -82,7 +93,7 @@ describe('AiAgentRolesCatalogProvider', () => {
           },
         ],
       });
-      const body = streamOf([new TextEncoder().encode(json)]);
+      const body = streamOf([new TextEncoder().encode(yaml)]);
       global.fetch = jest
         .fn()
         .mockResolvedValue(mockResponse({ body })) as never;
@@ -92,12 +103,12 @@ describe('AiAgentRolesCatalogProvider', () => {
     });
 
     it('fetchBundle remote malformed (role missing instructions) => BadGateway', async () => {
-      const json = JSON.stringify({
+      const yaml = stringifyYaml({
         schemaVersion: 1,
         language: 'fr',
         roles: [{ slug: 'researcher', name: 'Chercheur' }],
       });
-      const body = streamOf([new TextEncoder().encode(json)]);
+      const body = streamOf([new TextEncoder().encode(yaml)]);
       global.fetch = jest
         .fn()
         .mockResolvedValue(mockResponse({ body })) as never;
@@ -153,8 +164,9 @@ describe('AiAgentRolesCatalogProvider', () => {
         );
       global.fetch = fetchMock as never;
       const provider = makeProvider('https://catalog.example.com');
-      // Body shape is irrelevant; an empty stream parses to invalid JSON and
-      // throws, but the fetch call (with its init) still happened.
+      // Body shape is irrelevant; an empty stream parses to an empty YAML doc
+      // (null), fails the shape guard and throws, but the fetch call (with its
+      // init) still happened.
       await expect(provider.fetchIndex()).rejects.toBeDefined();
       expect(fetchMock).toHaveBeenCalledWith(
         expect.any(String),
@@ -190,7 +202,7 @@ describe('AiAgentRolesCatalogProvider', () => {
     });
 
     it('small streamed body parses normally (cap not hit)', async () => {
-      const json = JSON.stringify({
+      const yaml = stringifyYaml({
         schemaVersion: 1,
         bundles: [
           {
@@ -201,7 +213,7 @@ describe('AiAgentRolesCatalogProvider', () => {
           },
         ],
       });
-      const body = streamOf([new TextEncoder().encode(json)]);
+      const body = streamOf([new TextEncoder().encode(yaml)]);
       global.fetch = jest
         .fn()
         .mockResolvedValue(mockResponse({ body })) as never;
@@ -227,7 +239,7 @@ describe('AiAgentRolesCatalogProvider', () => {
     });
 
     it('null body (no readable stream) => response.text() fallback parses', async () => {
-      const json = JSON.stringify({
+      const yaml = stringifyYaml({
         schemaVersion: 1,
         bundles: [
           {
@@ -240,7 +252,7 @@ describe('AiAgentRolesCatalogProvider', () => {
       });
       global.fetch = jest
         .fn()
-        .mockResolvedValue(mockResponse({ body: null, text: json })) as never;
+        .mockResolvedValue(mockResponse({ body: null, text: yaml })) as never;
       const provider = makeProvider('https://catalog.example.com');
       const index = await provider.fetchIndex();
       expect(index.bundles[0].id).toBe('general');
@@ -259,8 +271,12 @@ describe('AiAgentRolesCatalogProvider', () => {
       );
     });
 
-    it('invalid JSON body => BadGateway (parse failure)', async () => {
-      const body = streamOf([new TextEncoder().encode('{not valid json')]);
+    it('invalid YAML body => BadGateway (parse failure)', async () => {
+      // An unterminated flow mapping is not valid YAML, so YAML.parse throws and
+      // the provider maps it to BadGateway (not a generic 500).
+      const body = streamOf([
+        new TextEncoder().encode('schemaVersion: {not: closed'),
+      ]);
       global.fetch = jest
         .fn()
         .mockResolvedValue(mockResponse({ body })) as never;
@@ -270,11 +286,28 @@ describe('AiAgentRolesCatalogProvider', () => {
       );
     });
 
-    it('malformed index.json (valid JSON, wrong shape) => BadGateway', async () => {
-      // Parses as JSON but fails isCatalogIndex (schemaVersion not a number).
+    it('YAML with a duplicate key (strict) => BadGateway (parse failure)', async () => {
+      // strict:true rejects duplicate mapping keys rather than last-wins coercing
+      // them — a defensive parse on untrusted input.
       const body = streamOf([
         new TextEncoder().encode(
-          JSON.stringify({ schemaVersion: 'x', bundles: [] }),
+          'schemaVersion: 1\nbundles: []\nschemaVersion: 2\n',
+        ),
+      ]);
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(mockResponse({ body })) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
+        BadGatewayException,
+      );
+    });
+
+    it('malformed index.yaml (valid YAML, wrong shape) => BadGateway', async () => {
+      // Parses as YAML but fails isCatalogIndex (schemaVersion not a number).
+      const body = streamOf([
+        new TextEncoder().encode(
+          stringifyYaml({ schemaVersion: 'x', bundles: [] }),
         ),
       ]);
       global.fetch = jest
@@ -283,6 +316,36 @@ describe('AiAgentRolesCatalogProvider', () => {
       const provider = makeProvider('https://catalog.example.com');
       await expect(provider.fetchIndex()).rejects.toThrow(/malformed/i);
     });
+
+    it('block-scalar instructions round-trips to the exact multi-line string', async () => {
+      // The whole point of the YAML migration: a long `instructions` prompt is
+      // stored as a literal block scalar (|-) for line-by-line diffs, and must
+      // resolve byte-for-byte to the original multi-line string.
+      const instructions = [
+        'Line one of the prompt.',
+        '',
+        '  Indented bullet that must survive.',
+        'Final line, no trailing newline.',
+      ].join('\n');
+      const yaml = stringifyYaml(
+        {
+          schemaVersion: 1,
+          language: 'en',
+          roles: [{ slug: 'researcher', name: 'Researcher', instructions }],
+        },
+        { lineWidth: 0 },
+      );
+      // Sanity: the fixture really uses a literal block scalar (|, optionally
+      // with an indentation indicator), not a flow/quoted string.
+      expect(yaml).toMatch(/instructions: \|/);
+      const body = streamOf([new TextEncoder().encode(yaml)]);
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(mockResponse({ body })) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      const bundle = await provider.fetchBundle('research', 'en');
+      expect(bundle.roles[0].instructions).toBe(instructions);
+    });
   });
 
   describe('path-traversal / SSRF guard (^[a-z0-9-]+$)', () => {
@@ -304,4 +367,93 @@ describe('AiAgentRolesCatalogProvider', () => {
       });
     }
   });
+
+  // ---------------------------------------------------------------------------
+  // Pin the REAL shipped catalog files (not synthetic fixtures). The JSON->YAML
+  // migration was a hand conversion, so the realistic failure is a hand-edit
+  // error in one of the 5 content YAML files (the index + the four per-bundle/
+  // lang files: index.yaml plus bundles/{editorial,research}/{en,ru}.yaml) — a
+  // quote/colon in a description, a broken
+  // emoji/arrow, a block-scalar indent slip that silently changes or drops
+  // instructions). Nothing else in CI parses these files — `scripts/check.mjs`
+  // is not wired into any turbo/husky/CI step — so this is the only automated
+  // guard over the shipped content. We read them straight off disk, parse with
+  // the SAME options the provider uses (strict + maxAliasCount, see parseYaml in
+  // the provider), and run them through the provider's own type guards. A future
+  // edit that breaks a real file fails here.
+  // ---------------------------------------------------------------------------
+  describe('real shipped catalog files (the YAML migration must not break them)', () => {
+    // Spec lives at apps/server/src/core/ai-chat/roles/catalog/; the catalog
+    // ships at the repo root (agent-roles-catalog/) — seven levels up.
+    const CATALOG_DIR = join(
+      __dirname,
+      '../../../../../../../agent-roles-catalog',
+    );
+    // Match the provider's parseYaml exactly (untrusted-input parse options).
+    const PARSE_OPTS = { strict: true, maxAliasCount: 100 } as const;
+
+    function readCatalogYaml(rel: string): unknown {
+      return parseYaml(readFileSync(join(CATALOG_DIR, rel), 'utf8'), PARSE_OPTS);
+    }
+
+    // Load + validate the real index lazily (only when a test runs), so a broken
+    // real file fails ONLY these catalog tests — not collection of the entire
+    // spec, which also holds the unrelated mocked-remote provider tests above.
+    function loadRealIndex() {
+      const parsed = readCatalogYaml('index.yaml');
+      if (!isCatalogIndex(parsed)) {
+        throw new Error('Real index.yaml is not a valid catalog index');
+      }
+      return parsed;
+    }
+
+    it('index.yaml parses + validates with the provider guard', () => {
+      expect(isCatalogIndex(readCatalogYaml('index.yaml'))).toBe(true);
+    });
+
+    it('editorial bundle still ships the fact-checker role', () => {
+      const editorial = loadRealIndex().bundles.find((b) => b.id === 'editorial');
+      expect(editorial).toBeDefined();
+      expect(editorial?.roles.map((r) => r.slug)).toContain('fact-checker');
+    });
+
+    // Driven by the real index (read inside the test, so it's lazy): every
+    // declared bundle + language file must parse, validate, and be in EXACT slug
+    // correspondence with the index — every declared role present AND no
+    // undeclared extras — mirroring scripts/check.mjs, which requires both
+    // directions. A bundle or language added later is covered automatically.
+    it('every declared bundle/language file is valid and in exact slug correspondence', () => {
+      const index = loadRealIndex();
+      // Guard against an empty index silently passing the loops below.
+      expect(index.bundles.length).toBeGreaterThan(0);
+      for (const bundle of index.bundles) {
+        const declaredSlugs = bundle.roles.map((r) => r.slug);
+        expect(bundle.languages.length).toBeGreaterThan(0);
+        for (const lang of bundle.languages) {
+          const rel = `bundles/${bundle.id}/${lang}.yaml`;
+          const file = readCatalogYaml(rel);
+          expect(isCatalogBundleFile(file)).toBe(true);
+          // Narrow for TS and access fields safely.
+          if (!isCatalogBundleFile(file)) continue;
+          expect(file.language).toBe(lang);
+          const fileSlugs = file.roles.map((r) => r.slug);
+          // Existing direction: every declared role is present in the file.
+          for (const slug of declaredSlugs) {
+            expect(fileSlugs).toContain(slug);
+          }
+          // Symmetric direction: the file carries NO undeclared/extra roles, so
+          // file slugs and declared slugs must be the SAME set (exact match).
+          // Catches a hand-edit that copies a stray role into a bundle file.
+          expect([...fileSlugs].sort()).toEqual([...declaredSlugs].sort());
+          expect(file.roles.length).toBeGreaterThan(0);
+          for (const role of file.roles) {
+            expect(isCatalogRole(role)).toBe(true);
+            expect(typeof role.instructions).toBe('string');
+            expect(role.instructions.trim().length).toBeGreaterThan(0);
+            expect(role.name.trim().length).toBeGreaterThan(0);
+          }
+        }
+      }
+    });
+  });
 });

apps/server/src/core/ai-chat/roles/catalog/ai-agent-roles-catalog.provider.ts

@@ -4,6 +4,7 @@ import {
   Injectable,
   Logger,
 } from '@nestjs/common';
+import { parse as parseYamlDoc } from 'yaml';
 import { EnvironmentService } from '../../../../integrations/environment/environment.service';
 import {
   CatalogBundleFile,
@@ -28,9 +29,11 @@ const MAX_BYTES = 1_000_000;
  * base URL — REMOTE only; local-filesystem sources are no longer supported. The
  * value is baked into the Docker image at build time (set per-branch in CI).
  *
- * The catalog is UNTRUSTED input: every file is JSON-parsed and run through a
- * hand-written type guard before any field is exposed, and every dynamic path
- * segment is validated against SEGMENT_RE up front (path-traversal + SSRF).
+ * The catalog is UNTRUSTED input: every file is YAML-parsed with a SAFE schema
+ * (standard JSON-compatible tags only — no custom `!!` tags / no code execution)
+ * and run through a hand-written type guard before any field is exposed, and
+ * every dynamic path segment is validated against SEGMENT_RE up front
+ * (path-traversal + SSRF).
  */
 @Injectable()
 export class AiAgentRolesCatalogProvider {
@@ -38,19 +41,19 @@ export class AiAgentRolesCatalogProvider {
 
   constructor(private readonly environmentService: EnvironmentService) {}
 
-  /** Read + validate the top-level index (`index.json`). */
+  /** Read + validate the top-level index (`index.yaml`). */
   async fetchIndex(): Promise<CatalogIndex> {
-    const raw = await this.readRelative('index.json');
-    const parsed = this.parseJson(raw, 'index.json');
+    const raw = await this.readRelative('index.yaml');
+    const parsed = this.parseYaml(raw, 'index.yaml');
     if (!isCatalogIndex(parsed)) {
       throw new BadGatewayException(
-        'Agent roles catalog index is malformed (index.json)',
+        'Agent roles catalog index is malformed (index.yaml)',
       );
     }
     return parsed;
   }
 
-  /** Read + validate one language file (`bundles/<bundleId>/<language>.json`). */
+  /** Read + validate one language file (`bundles/<bundleId>/<language>.yaml`). */
   async fetchBundle(
     bundleId: string,
     language: string,
@@ -58,9 +61,9 @@ export class AiAgentRolesCatalogProvider {
     // SECURITY: validate BEFORE building any path/URL (path-traversal + SSRF).
     this.assertSegment(bundleId, 'bundleId');
     this.assertSegment(language, 'language');
-    const rel = `bundles/${bundleId}/${language}.json`;
+    const rel = `bundles/${bundleId}/${language}.yaml`;
     const raw = await this.readRelative(rel);
-    const parsed = this.parseJson(raw, rel);
+    const parsed = this.parseYaml(raw, rel);
     if (!isCatalogBundleFile(parsed)) {
       throw new BadGatewayException(
         `Agent roles catalog bundle is malformed (${rel})`,
@@ -76,15 +79,29 @@ export class AiAgentRolesCatalogProvider {
     }
   }
 
-  /** JSON.parse with a clear BadGateway on malformed content. */
-  private parseJson(raw: string, rel: string): unknown {
+  /**
+   * Safe YAML parse with a clear BadGateway on malformed content. The catalog is
+   * untrusted, so we lean on the `yaml` library's default `core` schema, which
+   * only produces JSON-compatible values (objects/arrays/strings/numbers/
+   * booleans/null) and NEVER constructs arbitrary types or runs code — there is
+   * no `!!js`-style tag handling. `strict: true` rejects duplicate keys instead
+   * of silently coercing them. (Note: in yaml@2.8.x an unknown custom tag does
+   * NOT throw even under `strict` — the parser logs a warning and resolves the
+   * node to a plain scalar; the catalog stays safe because the default schema
+   * never builds arbitrary types from a tag and our hand-written type guards
+   * reject any value of the wrong shape.) The alias-expansion guard
+   * (`maxAliasCount`) bounds billion-laughs blow-ups (the 1 MB streaming
+   * cap already limits the input itself). JSON is a YAML subset, so a leftover
+   * `.json`-style body still parses here too.
+   */
+  private parseYaml(raw: string, rel: string): unknown {
     try {
-      return JSON.parse(raw);
+      return parseYamlDoc(raw, { strict: true, maxAliasCount: 100 });
     } catch (err) {
       const reason = shortError(err);
-      this.logger.error(`Agent roles catalog JSON parse failed (${rel}): ${reason}`);
+      this.logger.error(`Agent roles catalog YAML parse failed (${rel}): ${reason}`);
       throw new BadGatewayException(
-        `Agent roles catalog file is not valid JSON (${rel}): ${reason}`,
+        `Agent roles catalog file is not valid YAML (${rel}): ${reason}`,
       );
     }
   }

apps/server/src/core/ai-chat/roles/catalog/catalog-types.ts

@@ -1,7 +1,8 @@
 /**
- * Catalog wire shapes. The catalog is curated, untrusted JSON (a GitHub repo or
+ * Catalog wire shapes. The catalog is curated, untrusted YAML (a GitHub repo or
  * a local folder), so every shape is validated by a hand-written type guard in
- * the provider before any field is used — no zod / new deps on the server.
+ * the provider before any field is used — no zod on the server (YAML is parsed
+ * with the `yaml` library's safe, JSON-compatible schema).
  *
  * Localized fields (`name` / `description` at the bundle level) are
  * `Record<language, string>` so one bundle serves many UI languages; per-role
@@ -22,7 +23,7 @@ export interface CatalogRole {
   modelConfig?: Record<string, unknown> | null;
 }
 
-/** A single language file: `bundles/<id>/<language>.json`. */
+/** A single language file: `bundles/<id>/<language>.yaml`. */
 export interface CatalogBundleFile {
   schemaVersion: number;
   language: string;
@@ -40,7 +41,7 @@ export interface CatalogBundleMeta {
   roles: { slug: string; version: number }[];
 }
 
-/** Top-level catalog index: `index.json`. */
+/** Top-level catalog index: `index.yaml`. */
 export interface CatalogIndex {
   schemaVersion: number;
   bundles: CatalogBundleMeta[];

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

@@ -63,9 +63,12 @@ describe('AiChatToolsService deletePage guardrail (H4)', () => {
       {} as never,
       {} as never,
       {} as never,
-      // sandboxStore (only used by the stash tool closure, which these tests do
-      // not execute).
-      {} as never,
+      // sandboxStore: forUser() eagerly calls asSink() to wire the stash tool,
+      // even though these tests never execute it — return a no-op sink so the
+      // tool wiring in forUser() succeeds.
+      {
+        asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
+      } as never,
     );
   });
 
@@ -178,9 +181,12 @@ describe('AiChatToolsService expanded toolset guardrails', () => {
       {} as never,
       {} as never,
       {} as never,
-      // sandboxStore (only used by the stash tool closure, which these tests do
-      // not execute).
-      {} as never,
+      // sandboxStore: forUser() eagerly calls asSink() to wire the stash tool,
+      // even though these tests never execute it — return a no-op sink so the
+      // tool wiring in forUser() succeeds.
+      {
+        asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
+      } as never,
     );
   });
 
@@ -296,9 +302,12 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
       {} as never,
       {} as never,
       {} as never,
-      // sandboxStore (only used by the stash tool closure, which these tests do
-      // not execute).
-      {} as never,
+      // sandboxStore: forUser() eagerly calls asSink() to wire the stash tool,
+      // even though these tests never execute it — return a no-op sink so the
+      // tool wiring in forUser() succeeds.
+      {
+        asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
+      } as never,
     );
   });
 
@@ -449,9 +458,12 @@ describe('AiChatToolsService model-friendly input validation (#190)', () => {
       {} as never,
       {} as never,
       {} as never,
-      // sandboxStore (only used by the stash tool closure, which these tests do
-      // not execute).
-      {} as never,
+      // sandboxStore: forUser() eagerly calls asSink() to wire the stash tool,
+      // even though these tests never execute it — return a no-op sink so the
+      // tool wiring in forUser() succeeds.
+      {
+        asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
+      } as never,
     );
   });
 

apps/server/src/core/ai-chat/tools/docmost-client.loader.ts

@@ -1,10 +1,39 @@
 import { pathToFileURL } from 'node:url';
+import { esmImport } from '../../../common/helpers/esm-import';
 
 /**
  * Minimal structural type for the `DocmostClient` class we consume from the
  * ESM-only `@docmost/mcp` package. We only need the constructor + the read/write
  * methods used by the per-user tool adapter; the full client surface lives in
  * `packages/mcp/src/client.ts`. Signatures here mirror that file exactly.
+ *
+ * DRIFT GUARD: the method NAMES below are runtime-checked against the real
+ * `DocmostClient` by `packages/mcp/test/unit/client-host-contract.test.mjs`
+ * (which can import the ESM class directly). If you rename/remove a method here
+ * or in client.ts, that test fails — so a stale mirror cannot silently ship a
+ * runtime "x is not a function" into an agent tool call. Keep the two in sync.
+ *
+ * STAGED PLAN — full derivation `DocmostClientLike = <real DocmostClient type>`
+ * (issue #193, layer 3) is intentionally NOT done; it stays a hand-mirror for
+ * now because of two verified blockers across the ESM(mcp)/CJS(server) boundary:
+ *   1. `@docmost/mcp` emits NO declaration files (its tsconfig has no
+ *      `declaration`, package.json has no `types`/types-export) and the server
+ *      tsconfig has no path mapping for it — the server only loads it via the
+ *      runtime `import()` trick below, so there is no type to import today.
+ *   2. The real client methods have inferred, CONCRETE return types; the in-app
+ *      tool adapter reads results through loose `Record<string,unknown>` returns
+ *      + `as` casts (e.g. `(result?.data ?? {}) as { title?: string }`).
+ *      Deriving the exact type would make those casts non-overlapping ("may be a
+ *      mistake") and break the build, and `Partial<DocmostClientLike>` test stubs
+ *      would have to satisfy the full concrete surface.
+ * To do it safely later (incrementally): (a) turn on `declaration: true` in
+ * packages/mcp/tsconfig.json + add a `types` export condition and commit the
+ * emitted `.d.ts`; (b) `import type { DocmostClient } from '@docmost/mcp'` here
+ * and replace this interface with a `Pick<DocmostClient, ...>` of the consumed
+ * methods; (c) audit every `as` cast in ai-chat-tools.service.ts against the now
+ * concrete return types (double-cast through `unknown` only where genuinely
+ * needed); (d) keep the runtime guard test as a belt-and-braces check. Until
+ * then the guard test above is the cheap, behaviour-neutral protection.
  */
 export interface DocmostClientLike {
   // --- read ---
@@ -212,14 +241,8 @@ interface DocmostMcpModule {
   SHARED_TOOL_SPECS: Record<string, SharedToolSpec>;
 }
 
-// TS with module:commonjs downlevels a literal `import()` to `require()`, which
-// cannot load the ESM-only `@docmost/mcp` package. Indirect through Function so
-// the real dynamic `import()` survives compilation and can load ESM from
-// CommonJS at runtime (same trick as integrations/mcp/mcp.service.ts).
-const esmImport = new Function(
-  'specifier',
-  'return import(specifier)',
-) as (specifier: string) => Promise<unknown>;
+// The CJS->ESM dynamic-import bridge lives in one shared helper
+// (common/helpers/esm-import.ts). The typed `loadDocmostMcp()` wrapper stays here.
 
 // Memoize the in-flight/loaded module so the dynamic import runs at most once.
 let modulePromise: Promise<DocmostMcpModule> | null = null;

apps/server/src/core/ai-chat/tools/shared-tool-specs.contract.spec.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import { AiChatToolsService } from './ai-chat-tools.service';
+import * as loader from './docmost-client.loader';
+import type { DocmostClientLike } from './docmost-client.loader';
+// The real zod-agnostic registry, imported from source so the contract is checked
+// against exactly what the @docmost/mcp package ships (no hand-stub).
+import { SHARED_TOOL_SPECS } from '../../../../../../packages/mcp/src/tool-specs';
+
+/**
+ * CONTRACT: SHARED_TOOL_SPECS <-> in-app tool wiring parity.
+ *
+ * `packages/mcp/src/tool-specs.ts` is the single source of truth for the tools
+ * that are intentionally IDENTICAL across the standalone MCP server (zod v3) and
+ * the in-app AI-SDK service (zod v4). The in-app service builds each one via
+ * `sharedTool(sharedToolSpecs.<key>, execute)`, keyed by the spec's `inAppKey`.
+ *
+ * This test fails the build if a spec is added to the registry but never wired
+ * in-app, if an `inAppKey` is renamed without updating the service, if the
+ * description drifts between the registry and the exposed tool, if the
+ * snake_case `mcpName` <-> camelCase `inAppKey` convention is broken, or if the
+ * exposed tool's input-schema keys diverge from the spec's `buildShape`.
+ *
+ * It does NOT need @docmost/mcp built: the registry is imported from TS source,
+ * and the ESM loader is mocked so `forUser()` never dynamically imports the
+ * package.
+ */
+describe('SHARED_TOOL_SPECS contract parity', () => {
+  // Empty fake client: no tool is executed here — every assertion is on tool
+  // presence / metadata / schema, so the client methods are never called.
+  const fakeClient: Partial<DocmostClientLike> = {};
+  const tokenServiceStub = {
+    generateAccessToken: jest.fn().mockResolvedValue('access-token'),
+    generateCollabToken: jest.fn().mockResolvedValue('collab-token'),
+  };
+
+  let tools: Record<string, unknown>;
+
+  beforeAll(async () => {
+    jest.spyOn(loader, 'loadDocmostMcp').mockResolvedValue({
+      DocmostClient: function () {
+        return fakeClient as DocmostClientLike;
+      } as unknown as loader.DocmostClientCtor,
+      // Feed the service the SAME registry this test asserts against.
+      sharedToolSpecs: SHARED_TOOL_SPECS as unknown as Record<
+        string,
+        loader.SharedToolSpec
+      >,
+    });
+    const 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,
+    );
+    tools = (await service.forUser(
+      { id: 'user-1', email: 'u@example.com', workspaceId: 'ws-1' } as never,
+      'session-1',
+      'ws-1',
+      'chat-1',
+    )) as unknown as Record<string, unknown>;
+  });
+
+  afterAll(() => jest.restoreAllMocks());
+
+  // camelCase -> snake_case, matching the registry's mcpName convention.
+  const toSnake = (s: string) =>
+    s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+
+  // Type as the (optional-buildShape) SharedToolSpec; the `satisfies` literal
+  // above otherwise narrows to a union where some members lack buildShape.
+  const specEntries = Object.entries(SHARED_TOOL_SPECS) as Array<
+    [string, loader.SharedToolSpec]
+  >;
+
+  // Sanity: the registry is non-empty, so the per-spec table below is not vacuous.
+  it('registry is non-empty', () => {
+    expect(specEntries.length).toBeGreaterThan(0);
+  });
+
+  describe.each(specEntries)('spec "%s"', (registryKey, spec) => {
+    it('registry key equals its inAppKey', () => {
+      // The service indexes the registry by property name; a key != inAppKey
+      // would wire the wrong (or no) tool.
+      expect(spec.inAppKey).toBe(registryKey);
+    });
+
+    it('mcpName is the snake_case form of inAppKey', () => {
+      expect(spec.mcpName).toBe(toSnake(spec.inAppKey));
+    });
+
+    it('is exposed in-app under its inAppKey', () => {
+      // Fails if a spec is added to the registry but never wired in forUser().
+      expect(tools[spec.inAppKey]).toBeDefined();
+    });
+
+    it("exposed tool's description matches the registry description", () => {
+      const tool = tools[spec.inAppKey] as { description: string };
+      expect(tool.description).toBe(spec.description);
+    });
+
+    it("exposed tool's input-schema keys match buildShape (incl. required)", () => {
+      const tool = tools[spec.inAppKey] as {
+        inputSchema: { jsonSchema: { properties?: Record<string, unknown>; required?: string[] } };
+      };
+      const json = tool.inputSchema.jsonSchema;
+      const actualKeys = Object.keys(json.properties ?? {}).sort();
+
+      // Derive the spec's declared shape with THIS layer's zod (v4) — the same
+      // call the service makes — then compare key sets and required-ness.
+      const shape = spec.buildShape ? spec.buildShape(z) : {};
+      const expectedKeys = Object.keys(shape).sort();
+      expect(actualKeys).toEqual(expectedKeys);
+
+      // A non-.optional() field must surface as required in the advertised schema.
+      const expectedRequired = Object.entries(shape)
+        .filter(([, field]) => !(field as z.ZodTypeAny).isOptional?.())
+        .map(([k]) => k)
+        .sort();
+      expect((json.required ?? []).slice().sort()).toEqual(expectedRequired);
+    });
+  });
+});

apps/server/src/core/auth/dto/jwt-payload.ts

@@ -3,8 +3,12 @@
  * from the SIGNED token claim (never a request body), so 'agent' is unspoofable.
  * Single source of truth so a typo like 'agnet' can't slip through as a bare
  * string (#143 review). Distinct from `ActorType` (auth principal kind).
+ *
+ * 'git-sync' marks writes made by the git-sync data plane (issue #194 §8.1). It NEVER
+ * travels in a user-facing token; it is set in-process on the collab connection
+ * context by the native datasource, so it cannot be spoofed from a request.
  */
-export type ProvenanceSource = 'user' | 'agent';
+export type ProvenanceSource = 'user' | 'agent' | 'git-sync';
 
 export enum JwtType {
   ACCESS = 'access',
@@ -26,7 +30,8 @@ export type JwtPayload = {
   // normal user token (treated as 'user'); set only when the internal agent
   // mints a provenance access token so REST writes (create/rename/move page,
   // comment create/resolve) record a non-spoofable 'agent' marker (§6.5 / §15
-  // C3 / §14 N2).
+  // C3 / §14 N2). (git-sync writes use the in-process actor, not a token — see
+  // the ProvenanceSource note.)
   actor?: ProvenanceSource;
   // Nullable: an external MCP agent has no internal ai_chats row, so it carries
   // an 'agent' actor with a null aiChatId.
@@ -39,7 +44,8 @@ export type JwtCollabPayload = {
   type: 'collab';
   // Optional agent-edit provenance, signed into the collab token. Absent for
   // the human collab path (treated as 'user'); set only when the internal agent
-  // mints a provenance collab token (§6.6 / §15 C2).
+  // mints a provenance collab token (§6.6 / §15 C2). 'git-sync' (in ProvenanceSource)
+  // is accepted for type-compatibility with the in-process git-sync write path.
   actor?: ProvenanceSource;
   // Nullable: an external MCP agent has no internal ai_chats row, so it carries
   // an 'agent' actor with a null aiChatId.

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

@@ -1,8 +1,11 @@
 import { BadRequestException } from '@nestjs/common';
 import { PageService } from './page.service';
 import { MovePageDto } from '../dto/move-page.dto';
-import { Page } from '@docmost/db/types/entity.types';
+import { CreatePageDto } from '../dto/create-page.dto';
+import { UpdatePageDto } from '../dto/update-page.dto';
+import { Page, User } from '@docmost/db/types/entity.types';
 import { DEFAULT_TEMPORARY_NOTE_HOURS } from '../constants/temporary-note.constants';
+import { AuthProvenanceData } from '../../../common/decorators/auth-provenance.decorator';
 
 // Direct instantiation with stub deps. The Test.createTestingModule form failed
 // to resolve the @InjectKysely()/@InjectQueue() tokens at compile(), and this
@@ -496,4 +499,295 @@ describe('PageService', () => {
       expect(db.selectFrom).not.toHaveBeenCalled();
     });
   });
+
+  describe('git-sync provenance stamping (#1)', () => {
+    const GIT_SYNC: AuthProvenanceData = { actor: 'git-sync', aiChatId: null };
+    const USER_PROVENANCE: AuthProvenanceData = { actor: 'user', aiChatId: null };
+
+    describe('create()', () => {
+      // Build a service whose insertPage/generalQueue are observable and whose
+      // nextPagePosition (a DB query) is stubbed, so create() reaches insertPage
+      // without a real database.
+      const makeService = () => {
+        const insertedPage = { id: 'page-1', slugId: 'slug-1' };
+        const pageRepo = {
+          insertPage: jest.fn().mockResolvedValue(insertedPage),
+        };
+        // add() is fire-and-forget (the service .catch()es it); resolve so no
+        // unhandled rejection leaks.
+        const generalQueue = { add: jest.fn().mockResolvedValue(undefined) };
+
+        const svc = new PageService(
+          pageRepo as any, // pageRepo
+          {} as any, // pagePermissionRepo
+          {} as any, // attachmentRepo
+          {} as any, // db
+          {} as any, // storageService
+          {} as any, // attachmentQueue
+          {} as any, // aiQueue
+          generalQueue as any, // generalQueue
+          {} as any, // eventEmitter
+          {} as any, // collaborationGateway
+          {} as any, // watcherService
+          {} as any, // transclusionService
+        );
+
+        // nextPagePosition runs a kysely query; stub it so create() never hits
+        // the db. No DTO content is provided, so parseProsemirrorContent is
+        // skipped entirely (content/textContent/ydoc stay undefined).
+        jest.spyOn(svc, 'nextPagePosition').mockResolvedValue('a0');
+
+        return { svc, pageRepo };
+      };
+
+      const createDto: CreatePageDto = {
+        title: 'New page',
+        spaceId: 'space-1',
+      } as any;
+
+      it("stamps lastUpdatedSource:'git-sync' on the insertPage payload", async () => {
+        const { svc, pageRepo } = makeService();
+
+        await svc.create('user-1', 'ws-1', createDto, GIT_SYNC);
+
+        expect(pageRepo.insertPage).toHaveBeenCalledTimes(1);
+        expect(pageRepo.insertPage).toHaveBeenCalledWith(
+          expect.objectContaining({ lastUpdatedSource: 'git-sync' }),
+        );
+        // git-sync carries no aiChatId (unlike the agent branch).
+        const payload = pageRepo.insertPage.mock.calls[0][0];
+        expect(payload.lastUpdatedAiChatId).toBeUndefined();
+        // The human stays the responsible author.
+        expect(payload.creatorId).toBe('user-1');
+        expect(payload.lastUpdatedById).toBe('user-1');
+      });
+
+      it('leaves the source column unset for a plain user create', async () => {
+        const { svc, pageRepo } = makeService();
+
+        await svc.create('user-1', 'ws-1', createDto, USER_PROVENANCE);
+
+        const payload = pageRepo.insertPage.mock.calls[0][0];
+        expect(payload.lastUpdatedSource).toBeUndefined();
+      });
+    });
+
+    describe('update() (rename)', () => {
+      const makeService = () => {
+        const pageRepo = {
+          updatePage: jest.fn().mockResolvedValue({ numUpdatedRows: 1n }),
+          // update() re-reads the row at the end to return the refreshed page.
+          findById: jest.fn().mockResolvedValue({ id: 'page-1' }),
+        };
+        const generalQueue = { add: jest.fn().mockResolvedValue(undefined) };
+        const aiQueue = { add: jest.fn().mockResolvedValue(undefined) };
+
+        const svc = new PageService(
+          pageRepo as any, // pageRepo
+          {} as any, // pagePermissionRepo
+          {} as any, // attachmentRepo
+          {} as any, // db
+          {} as any, // storageService
+          {} as any, // attachmentQueue
+          aiQueue as any, // aiQueue
+          generalQueue as any, // generalQueue
+          {} as any, // eventEmitter
+          {} as any, // collaborationGateway
+          {} as any, // watcherService
+          {} as any, // transclusionService
+        );
+
+        return { svc, pageRepo };
+      };
+
+      const page: Page = {
+        id: 'page-1',
+        slugId: 'slug-1',
+        spaceId: 'space-1',
+        workspaceId: 'ws-1',
+        title: 'Old title',
+        icon: null,
+        parentPageId: null,
+        contributorIds: [],
+      } as any;
+
+      const user: User = { id: 'user-1' } as any;
+
+      it("stamps lastUpdatedSource:'git-sync' on the updatePage payload", async () => {
+        const { svc, pageRepo } = makeService();
+        const dto: UpdatePageDto = { title: 'New title' } as any;
+
+        await svc.update(page, dto, user, GIT_SYNC);
+
+        expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+        const payload = pageRepo.updatePage.mock.calls[0][0];
+        expect(payload.lastUpdatedSource).toBe('git-sync');
+        expect(payload.lastUpdatedAiChatId).toBeUndefined();
+        // The acting user stays the responsible author.
+        expect(payload.lastUpdatedById).toBe('user-1');
+      });
+
+      it('leaves the source column unset for a plain user rename', async () => {
+        const { svc, pageRepo } = makeService();
+        const dto: UpdatePageDto = { title: 'New title' } as any;
+
+        await svc.update(page, dto, user, USER_PROVENANCE);
+
+        const payload = pageRepo.updatePage.mock.calls[0][0];
+        expect(payload.lastUpdatedSource).toBeUndefined();
+      });
+    });
+
+    describe('movePage()', () => {
+      const SPACE_ID = 'space-1';
+      const VALID_POSITION = 'a0';
+
+      const makeService = () => {
+        const pageRepo = {
+          findById: jest.fn().mockResolvedValue({
+            id: 'dest-parent',
+            deletedAt: null,
+            spaceId: SPACE_ID,
+          }),
+          updatePage: jest.fn().mockResolvedValue({ numUpdatedRows: 1n }),
+        };
+        const eventEmitter = { emit: jest.fn() };
+
+        // movePage now runs the cycle-check + UPDATE inside executeTx(this.db),
+        // i.e. this.db.transaction().execute(fn => fn(trx)). A permissive
+        // chainable Proxy stands in for the Kysely trx so the per-space
+        // advisory-lock `sql``.execute(trx)` resolves and updatePage runs.
+        const trxStub: any = new Proxy(function () {}, {
+          get: (_t, p) =>
+            p === 'then'
+              ? undefined
+              : p === 'execute' || p === 'executeTakeFirst'
+                ? () => Promise.resolve([])
+                : () => trxStub,
+        });
+        const db = {
+          transaction: () => ({ execute: (fn: any) => fn(trxStub) }),
+        };
+
+        const svc = new PageService(
+          pageRepo as any, // pageRepo
+          {} as any, // pagePermissionRepo
+          {} as any, // attachmentRepo
+          db as any, // db
+          {} as any, // storageService
+          {} as any, // attachmentQueue
+          {} as any, // aiQueue
+          {} as any, // generalQueue
+          eventEmitter as any, // eventEmitter
+          {} as any, // collaborationGateway
+          {} as any, // watcherService
+          {} as any, // transclusionService
+        );
+
+        // No cycle: the destination's ancestor chain does not contain the moved
+        // page, so movePage reaches updatePage.
+        jest
+          .spyOn(svc, 'getPageBreadCrumbs')
+          .mockResolvedValue([{ id: 'dest-parent' }, { id: 'root' }] as any);
+
+        return { svc, pageRepo };
+      };
+
+      const movedPage: Page = {
+        id: 'page-1',
+        parentPageId: 'old-parent',
+        spaceId: SPACE_ID,
+        workspaceId: 'ws-1',
+        slugId: 'slug-1',
+        title: 'Page 1',
+        icon: null,
+      } as any;
+
+      const dto: MovePageDto = {
+        pageId: 'page-1',
+        position: VALID_POSITION,
+        parentPageId: 'dest-parent',
+      };
+
+      it("stamps lastUpdatedSource:'git-sync' on the updatePage payload", async () => {
+        const { svc, pageRepo } = makeService();
+
+        await svc.movePage(dto, movedPage, GIT_SYNC);
+
+        expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+        const payload = pageRepo.updatePage.mock.calls[0][0];
+        expect(payload.lastUpdatedSource).toBe('git-sync');
+        expect(payload.lastUpdatedAiChatId).toBeUndefined();
+      });
+
+      it('leaves the source column unset for a plain user move', async () => {
+        const { svc, pageRepo } = makeService();
+
+        await svc.movePage(dto, movedPage, USER_PROVENANCE);
+
+        const payload = pageRepo.updatePage.mock.calls[0][0];
+        expect(payload.lastUpdatedSource).toBeUndefined();
+      });
+    });
+
+    describe('removePage()', () => {
+      // removePage forwards a `source` 4th arg to pageRepo.removePage: 'git-sync'
+      // for a git-sync-driven soft-delete (so the change-listener loop-guard skips
+      // its own write), undefined otherwise.
+      const makeService = () => {
+        const pageRepo = {
+          removePage: jest.fn().mockResolvedValue(undefined),
+        };
+
+        const svc = new PageService(
+          pageRepo as any, // pageRepo
+          {} as any, // pagePermissionRepo
+          {} as any, // attachmentRepo
+          {} as any, // db
+          {} as any, // storageService
+          {} as any, // attachmentQueue
+          {} as any, // aiQueue
+          {} as any, // generalQueue
+          {} as any, // eventEmitter
+          {} as any, // collaborationGateway
+          {} as any, // watcherService
+          {} as any, // transclusionService
+        );
+
+        return { svc, pageRepo };
+      };
+
+      it("forwards 'git-sync' as the source for a git-sync soft-delete", async () => {
+        const { svc, pageRepo } = makeService();
+
+        await svc.removePage('page-1', 'user-1', 'ws-1', GIT_SYNC);
+
+        expect(pageRepo.removePage).toHaveBeenCalledTimes(1);
+        const [pageId, userId, workspaceId, source] =
+          pageRepo.removePage.mock.calls[0];
+        expect(pageId).toBe('page-1');
+        expect(userId).toBe('user-1');
+        expect(workspaceId).toBe('ws-1');
+        expect(source).toBe('git-sync');
+      });
+
+      it('forwards undefined as the source for a plain user delete', async () => {
+        const { svc, pageRepo } = makeService();
+
+        await svc.removePage('page-1', 'user-1', 'ws-1', USER_PROVENANCE);
+
+        const [, , , source] = pageRepo.removePage.mock.calls[0];
+        expect(source).toBeUndefined();
+      });
+
+      it('forwards undefined as the source when no provenance is given', async () => {
+        const { svc, pageRepo } = makeService();
+
+        await svc.removePage('page-1', 'user-1', 'ws-1');
+
+        const [, , , source] = pageRepo.removePage.mock.calls[0];
+        expect(source).toBeUndefined();
+      });
+    });
+  });
 });

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

@@ -948,6 +948,12 @@ export class PageService {
     // Optional agent-edit provenance (from the signed access claim). Stamps the
     // source marker when the agent moves a page via REST (§6.6 REST path).
     provenance?: AuthProvenanceData,
+    // Optional responsible author. When set (git-sync), the move is ATTRIBUTED
+    // to that account via `lastUpdatedById` — parity with create/delete/rename,
+    // which all stamp the service user. A normal user move omits it, leaving
+    // `lastUpdatedById` untouched (a reparent is not a content edit, so the
+    // existing author is preserved — unchanged behavior).
+    actorUserId?: string,
   ) {
     // validate position value by attempting to generate a key
     try {
@@ -1017,6 +1023,9 @@ export class PageService {
         {
           position: dto.position,
           parentPageId: parentPageId,
+          // Attribute a git-initiated move to the service account (parity with
+          // create/delete/rename). Omitted for normal user moves -> unchanged.
+          ...(actorUserId ? { lastUpdatedById: actorUserId } : {}),
           // Agent-edit provenance: annotate the source on an agent move. A
           // normal user request leaves the existing source value unchanged.
           ...agentSourceFields(
@@ -1289,8 +1298,18 @@ export class PageService {
     pageId: string,
     userId: string,
     workspaceId: string,
+    // Optional provenance. A git-sync-driven soft-delete stamps
+    // `lastUpdatedSource = 'git-sync'` so the change-listener loop-guard skips
+    // its own write (mirrors the create/update/move provenance branches above).
+    provenance?: AuthProvenanceData,
   ): Promise<void> {
-    await this.pageRepo.removePage(pageId, userId, workspaceId);
+    const isGitSync = provenance?.actor === 'git-sync';
+    await this.pageRepo.removePage(
+      pageId,
+      userId,
+      workspaceId,
+      isGitSync ? 'git-sync' : undefined,
+    );
   }
 
   private async parseProsemirrorContent(

apps/server/src/core/share/share-spoiler-keep.spec.ts

@@ -0,0 +1,129 @@
+import { ShareService } from './share.service';
+
+// Sibling of share-comment-strip.spec.ts. The public-share sanitizer strips ONLY
+// `comment` marks (internal-team metadata) via removeMarkTypeFromDoc(doc,
+// 'comment'). The `spoiler` mark is legitimate authored content (hidden text the
+// reader clicks to reveal) and MUST survive the share-strip — otherwise public
+// readers would see the secret in plain text or lose it entirely.
+//
+// We drive the SAME real seam the comment-strip test uses:
+// updatePublicAttachments -> prepareContentForShare -> removeMarkTypeFromDoc.
+
+const WS = 'ws-1';
+const PAGE = 'page-1';
+
+function buildService() {
+  const shareRepo = { findById: jest.fn() };
+  const pageRepo = { findById: jest.fn() };
+  const pagePermissionRepo = {
+    hasRestrictedAncestor: jest.fn(async () => false),
+  };
+  const tokenService = {
+    generateAttachmentToken: jest.fn(async () => 'tok'),
+  };
+  const workspaceRepo = {
+    findById: jest.fn(async () => ({ id: WS, settings: { htmlEmbed: true } })),
+  };
+
+  return new ShareService(
+    shareRepo as any,
+    pageRepo as any,
+    pagePermissionRepo as any,
+    {} as any, // db (unused on this path)
+    tokenService as any,
+    {} as any, // transclusionService (unused)
+    workspaceRepo as any,
+  );
+}
+
+// Text carrying a `spoiler` mark (no attributes; revealed state is UI-only).
+function spoilerText(text: string) {
+  return {
+    type: 'text',
+    text,
+    marks: [{ type: 'spoiler' }],
+  };
+}
+
+// Text carrying a `comment` mark with an id (the thing that DOES get stripped).
+function commentedText(text: string, commentId: string) {
+  return {
+    type: 'text',
+    text,
+    marks: [{ type: 'comment', attrs: { commentId, resolved: false } }],
+  };
+}
+
+async function sanitize(content: any) {
+  const service = buildService();
+  return service.updatePublicAttachments({
+    id: PAGE,
+    workspaceId: WS,
+    content,
+  } as any);
+}
+
+function countMarks(doc: any, type: string): number {
+  let count = 0;
+  const walk = (node: any) => {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node.marks)) {
+      for (const mark of node.marks) {
+        if (mark?.type === type) count++;
+      }
+    }
+    if (Array.isArray(node.content)) node.content.forEach(walk);
+  };
+  walk(doc);
+  return count;
+}
+
+describe('ShareService keeps spoiler marks on public shares (real code)', () => {
+  it('does NOT strip a spoiler mark', async () => {
+    const content = {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [{ type: 'text', text: 'visible ' }, spoilerText('hidden')],
+        },
+      ],
+    };
+
+    expect(countMarks(content, 'spoiler')).toBe(1);
+
+    const out = await sanitize(content);
+
+    // The spoiler mark survives the share-strip.
+    expect(countMarks(out, 'spoiler')).toBe(1);
+    expect(JSON.stringify(out)).toContain('hidden');
+  });
+
+  it('strips comment marks but keeps spoiler marks in the same doc', async () => {
+    const content = {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            commentedText('reviewed', 'cmt-1'),
+            { type: 'text', text: ' and ' },
+            spoilerText('secret'),
+          ],
+        },
+      ],
+    };
+
+    expect(countMarks(content, 'comment')).toBe(1);
+    expect(countMarks(content, 'spoiler')).toBe(1);
+
+    const out = await sanitize(content);
+
+    // comment is removed, spoiler is preserved.
+    expect(countMarks(out, 'comment')).toBe(0);
+    expect(countMarks(out, 'spoiler')).toBe(1);
+    const serialized = JSON.stringify(out);
+    expect(serialized).not.toContain('cmt-1');
+    expect(serialized).toContain('secret');
+  });
+});

apps/server/src/core/space/dto/update-space.dto.ts

@@ -15,4 +15,12 @@ export class UpdateSpaceDto extends PartialType(CreateSpaceDto) {
   @IsOptional()
   @IsBoolean()
   allowViewerComments: boolean;
+
+  @IsOptional()
+  @IsBoolean()
+  gitSyncEnabled?: boolean;
+
+  @IsOptional()
+  @IsBoolean()
+  autoMergeConflicts?: boolean;
 }

apps/server/src/core/space/services/space.service.spec.ts

@@ -22,4 +22,199 @@ describe('SpaceService', () => {
   it('should be defined', () => {
     expect(service).toBeDefined();
   });
+
+  describe('updateSpace gitSyncEnabled', () => {
+    const workspaceId = 'ws-1';
+    const spaceId = 'space-1';
+
+    // executeTx runs the callback immediately with a passthrough trx so the
+    // repo calls happen inline; mirrors how the sibling sharing/comments flags
+    // are persisted.
+    const buildService = (settingsBefore: Record<string, any>) => {
+      const spaceRepo = {
+        findById: jest.fn().mockResolvedValue({
+          id: spaceId,
+          name: 'Space',
+          slug: 'space',
+          description: '',
+          settings: settingsBefore,
+        }),
+        updateGitSyncSettings: jest.fn().mockResolvedValue({}),
+        updateSharingSettings: jest.fn().mockResolvedValue({}),
+        updateCommentSettings: jest.fn().mockResolvedValue({}),
+        updateSpace: jest
+          .fn()
+          .mockResolvedValue({ id: spaceId, name: 'Space', slug: 'space' }),
+        slugExists: jest.fn().mockResolvedValue(false),
+      };
+      const auditService = { log: jest.fn() };
+
+      const svc = new SpaceService(
+        spaceRepo as any,
+        {} as any, // spaceMemberService
+        {} as any, // shareRepo
+        {} as any, // workspaceRepo
+        {} as any, // licenseCheckService
+        {} as any, // db
+        {} as any, // attachmentQueue
+        auditService as any,
+      );
+
+      // executeTx is invoked via the imported helper; patch it on the module.
+      jest
+        .spyOn(require('@docmost/db/utils'), 'executeTx')
+        .mockImplementation(async (_db: any, cb: any) => cb({} as any));
+
+      return { svc, spaceRepo, auditService };
+    };
+
+    it('persists gitSyncEnabled via updateGitSyncSettings(enabled)', async () => {
+      const { svc, spaceRepo } = buildService({});
+
+      await svc.updateSpace(
+        { spaceId, gitSyncEnabled: true } as any,
+        workspaceId,
+      );
+
+      expect(spaceRepo.updateGitSyncSettings).toHaveBeenCalledWith(
+        spaceId,
+        workspaceId,
+        'enabled',
+        true,
+        expect.anything(),
+      );
+    });
+
+    it('does not call updateGitSyncSettings when flag is undefined', async () => {
+      const { svc, spaceRepo } = buildService({});
+
+      await svc.updateSpace({ spaceId } as any, workspaceId);
+
+      expect(spaceRepo.updateGitSyncSettings).not.toHaveBeenCalled();
+    });
+
+    // --- audit delta on the git-sync toggle (test-strategy Module 4 / item #5)
+    // updateSpace builds a before/after delta only when a flag's value actually
+    // changes, and only logs an audit event when that delta is non-empty. These
+    // assert that contract specifically for gitSyncEnabled.
+    it('writes a SPACE_UPDATED audit delta on a REAL gitSyncEnabled change (false -> true)', async () => {
+      // Prior persisted state: gitSync.enabled = false; the request flips it on.
+      const { svc, auditService } = buildService({ gitSync: { enabled: false } });
+
+      await svc.updateSpace(
+        { spaceId, gitSyncEnabled: true } as any,
+        workspaceId,
+      );
+
+      expect(auditService.log).toHaveBeenCalledTimes(1);
+      expect(auditService.log).toHaveBeenCalledWith(
+        expect.objectContaining({
+          resourceId: spaceId,
+          spaceId,
+          changes: {
+            before: expect.objectContaining({ gitSyncEnabled: false }),
+            after: expect.objectContaining({ gitSyncEnabled: true }),
+          },
+        }),
+      );
+    });
+
+    it('also records the delta when no prior gitSync settings exist (undefined -> true defaults prev to false)', async () => {
+      // No gitSync key at all: prev resolves to the `?? false` default, so
+      // enabling it is still a real change and is audited.
+      const { svc, auditService } = buildService({});
+
+      await svc.updateSpace(
+        { spaceId, gitSyncEnabled: true } as any,
+        workspaceId,
+      );
+
+      expect(auditService.log).toHaveBeenCalledTimes(1);
+      const call = auditService.log.mock.calls[0][0];
+      expect(call.changes.before.gitSyncEnabled).toBe(false);
+      expect(call.changes.after.gitSyncEnabled).toBe(true);
+    });
+
+    it('does NOT write an audit delta on a no-op gitSyncEnabled (same value true -> true)', async () => {
+      // Prior persisted state already true; the request sets the same value.
+      // updateGitSyncSettings still runs (idempotent persist), but nothing is
+      // added to the before/after delta, so no audit event is emitted.
+      const { svc, spaceRepo, auditService } = buildService({
+        gitSync: { enabled: true },
+      });
+
+      await svc.updateSpace(
+        { spaceId, gitSyncEnabled: true } as any,
+        workspaceId,
+      );
+
+      expect(spaceRepo.updateGitSyncSettings).toHaveBeenCalledTimes(1);
+      expect(auditService.log).not.toHaveBeenCalled();
+    });
+
+    // --- autoMergeConflicts: a SECOND key in the SAME `gitSync` jsonb object,
+    // persisted the same way as `enabled` (the repo's jsonb-merge keeps siblings).
+    it('persists autoMergeConflicts via updateGitSyncSettings(autoMergeConflicts)', async () => {
+      const { svc, spaceRepo } = buildService({});
+
+      await svc.updateSpace(
+        { spaceId, autoMergeConflicts: true } as any,
+        workspaceId,
+      );
+
+      expect(spaceRepo.updateGitSyncSettings).toHaveBeenCalledWith(
+        spaceId,
+        workspaceId,
+        'autoMergeConflicts',
+        true,
+        expect.anything(),
+      );
+    });
+
+    it('does not call updateGitSyncSettings when autoMergeConflicts is undefined', async () => {
+      const { svc, spaceRepo } = buildService({});
+
+      await svc.updateSpace({ spaceId } as any, workspaceId);
+
+      expect(spaceRepo.updateGitSyncSettings).not.toHaveBeenCalled();
+    });
+
+    it('writes a SPACE_UPDATED audit delta on a REAL autoMergeConflicts change (false -> true)', async () => {
+      // Prior persisted state: gitSync.autoMergeConflicts = false; flip it on.
+      const { svc, auditService } = buildService({
+        gitSync: { autoMergeConflicts: false },
+      });
+
+      await svc.updateSpace(
+        { spaceId, autoMergeConflicts: true } as any,
+        workspaceId,
+      );
+
+      expect(auditService.log).toHaveBeenCalledTimes(1);
+      expect(auditService.log).toHaveBeenCalledWith(
+        expect.objectContaining({
+          resourceId: spaceId,
+          spaceId,
+          changes: {
+            before: expect.objectContaining({ autoMergeConflicts: false }),
+            after: expect.objectContaining({ autoMergeConflicts: true }),
+          },
+        }),
+      );
+    });
+
+    it('does NOT write an audit delta on a no-op autoMergeConflicts (same value true -> true)', async () => {
+      const { svc, spaceRepo, auditService } = buildService({
+        gitSync: { autoMergeConflicts: true },
+      });
+
+      await svc.updateSpace(
+        { spaceId, autoMergeConflicts: true } as any,
+        workspaceId,
+      );
+
+      expect(spaceRepo.updateGitSyncSettings).toHaveBeenCalledTimes(1);
+      expect(auditService.log).not.toHaveBeenCalled();
+    });
+  });
 });

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

@@ -213,6 +213,41 @@ export class SpaceService {
         );
       }
 
+      if (typeof updateSpaceDto.gitSyncEnabled !== 'undefined') {
+        const prev = settingsBefore?.gitSync?.enabled ?? false;
+        if (prev !== updateSpaceDto.gitSyncEnabled) {
+          before.gitSyncEnabled = prev;
+          after.gitSyncEnabled = updateSpaceDto.gitSyncEnabled;
+        }
+
+        await this.spaceRepo.updateGitSyncSettings(
+          updateSpaceDto.spaceId,
+          workspaceId,
+          'enabled',
+          updateSpaceDto.gitSyncEnabled,
+          trx,
+        );
+      }
+
+      if (typeof updateSpaceDto.autoMergeConflicts !== 'undefined') {
+        const prev = settingsBefore?.gitSync?.autoMergeConflicts ?? false;
+        if (prev !== updateSpaceDto.autoMergeConflicts) {
+          before.autoMergeConflicts = prev;
+          after.autoMergeConflicts = updateSpaceDto.autoMergeConflicts;
+        }
+
+        // Merges into the SAME `gitSync` jsonb object as `enabled` (the repo's
+        // jsonb-merge preserves sibling keys), so toggling one never clobbers the
+        // other.
+        await this.spaceRepo.updateGitSyncSettings(
+          updateSpaceDto.spaceId,
+          workspaceId,
+          'autoMergeConflicts',
+          updateSpaceDto.autoMergeConflicts,
+          trx,
+        );
+      }
+
       updatedSpace = await this.spaceRepo.updateSpace(
         {
           name: updateSpaceDto.name,

apps/server/src/database/repos/page/page.repo.embeddable.spec.ts

@@ -0,0 +1,167 @@
+import { PageRepo } from './page.repo';
+import {
+  DummyDriver,
+  Kysely,
+  PostgresAdapter,
+  PostgresIntrospector,
+  PostgresQueryCompiler,
+} from 'kysely';
+
+/**
+ * F6 regression guard for the embeddable-page predicate.
+ *
+ * The predicate is shared by `countEmbeddablePages` (the "Indexed N of M" coverage
+ * denominator) and `getEmbeddablePageIds` (the exact set a full reindex iterates).
+ * It MUST select pages whose `text_content` was never backfilled (null/empty) but
+ * whose ProseMirror `content` JSON still carries body text — `reindexPage` builds
+ * its chunks straight from `content`, so without a content clause such a page is
+ * silently SKIPPED by a mass reindex even though it is fully embeddable.
+ *
+ * The content clause keys on the structural text-node marker `"type":"text"`, NOT
+ * a bare `"text":` key. The bare key also appears as the `attrs.text` of atom
+ * nodes that carry NO extractable text — notably math (`mathBlock`/`mathInline`),
+ * whose LaTeX lives in `attrs.text` and has no `generateText` serializer. A
+ * math-ONLY page therefore yields empty `text_content` and zero embeddings; if the
+ * predicate matched its `attrs.text` it would land in the denominator but
+ * `reindexPage` would no-op on it, pinning "Indexed N of M" below 100% forever —
+ * the exact bug this feature fixes. The `"type":"text"` marker matches only real
+ * text nodes (what `jsonToText` extracts), keeping the predicate consistent with
+ * what gets indexed.
+ *
+ * There is no real Postgres here: a recording Kysely (DummyDriver wired to the
+ * Postgres query compiler) compiles the queries to SQL so we can assert the WHERE
+ * predicate ORs in the narrowed content clause alongside the existing text_content
+ * and stored-embeddings clauses — and that BOTH callers compile the identical
+ * clause (denominator and reindex set can never diverge).
+ */
+function makeRecordingDb() {
+  const sqls: string[] = [];
+  const db = new Kysely<any>({
+    dialect: {
+      createAdapter: () => new PostgresAdapter(),
+      createDriver: () =>
+        new (class extends DummyDriver {
+          async acquireConnection() {
+            return {
+              executeQuery: async (compiled: { sql: string }) => {
+                sqls.push(compiled.sql);
+                return { rows: [] };
+              },
+              // eslint-disable-next-line @typescript-eslint/no-empty-function
+              streamQuery: async function* () {},
+            } as any;
+          }
+        })(),
+      createIntrospector: (d: Kysely<any>) => new PostgresIntrospector(d),
+      createQueryCompiler: () => new PostgresQueryCompiler(),
+    },
+  });
+  return { db, sqls };
+}
+
+// The narrowed content clause, as it appears in the compiled SQL. Keying on the
+// structural `"type":"text"` marker (not a bare `"text":` key) is what excludes
+// math-only pages whose only `"text"` key is the atom node's `attrs.text`.
+const NARROWED_CLAUSE = `"type"[[:space:]]*:[[:space:]]*"text"`;
+const BARE_TEXT_KEY = `"text"[[:space:]]*:`;
+
+describe('PageRepo embeddable predicate — content-bearing pages (F6)', () => {
+  it('selects content-bearing pages via the narrowed "type":"text" node marker', async () => {
+    const { db, sqls } = makeRecordingDb();
+    const repo = new PageRepo(db as any, {} as any, { emit: jest.fn() } as any);
+
+    await repo.getEmbeddablePageIds('ws-1');
+
+    expect(sqls).toHaveLength(1);
+    const sql = sqls[0];
+
+    // Clause 1 (existing): pages with extractable text_content.
+    expect(sql).toContain('text_content');
+    // Clause 3 (the F6 fix, now narrowed): a page whose content JSON carries a
+    // real text node is selected even when text_content is null/empty, so a full
+    // reindex visits it instead of silently skipping it.
+    expect(sql).toContain('content::text');
+    expect(sql).toContain(NARROWED_CLAUSE);
+    // It must NOT use the old bare `"text":` key, which also matches the
+    // `attrs.text` of math-only atom pages (false-positive denominator inflation).
+    expect(sql).not.toContain(BARE_TEXT_KEY);
+    // Clause 2 (existing): pages that already have stored embeddings stay in the
+    // set so a reindex can clear their stale rows.
+    expect(sql.toLowerCase()).toContain('embeddings');
+  });
+
+  it('countEmbeddablePages compiles the SAME narrowed clause as getEmbeddablePageIds', async () => {
+    // Consistency is the core requirement: the denominator (countEmbeddablePages)
+    // and the reindex set (getEmbeddablePageIds) MUST share the identical
+    // predicate, else the live "done" counter and the steady-state total diverge.
+    const { db, sqls } = makeRecordingDb();
+    const repo = new PageRepo(db as any, {} as any, { emit: jest.fn() } as any);
+
+    await repo.countEmbeddablePages('ws-1');
+    await repo.getEmbeddablePageIds('ws-1');
+
+    expect(sqls).toHaveLength(2);
+    const [countSql, idsSql] = sqls;
+
+    // Both carry the narrowed content clause...
+    expect(countSql).toContain(NARROWED_CLAUSE);
+    expect(idsSql).toContain(NARROWED_CLAUSE);
+    // ...neither carries the bare key...
+    expect(countSql).not.toContain(BARE_TEXT_KEY);
+    expect(idsSql).not.toContain(BARE_TEXT_KEY);
+    // ...and the full OR predicate (text_content + content node + embeddings
+    // EXISTS) is byte-identical between the two queries, so they can't drift.
+    const where = (s: string) => s.slice(s.indexOf('where'));
+    expect(where(countSql)).toEqual(where(idsSql));
+  });
+
+  it('the content regex matches a text-bearing doc but NOT a math-only doc', () => {
+    // Semantic check of the predicate against sample `content::text` payloads.
+    // Note: `jsonb::text` is NOT identical to JSON.stringify — Postgres renders a
+    // space after each colon (`"type": "text"`), which is exactly why the POSIX
+    // clause uses `[[:space:]]*`. The clause `"type"[[:space:]]*:[[:space:]]*"text"`
+    // maps to the JS regex below (`[[:space:]]` -> `\s`, tolerating both forms);
+    // we evaluate it the way Postgres would.
+    const re = /"type"\s*:\s*"text"/;
+
+    // A real paragraph with a text node -> embeddable.
+    const textDoc = JSON.stringify({
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [{ type: 'text', text: 'hello world' }],
+        },
+      ],
+    });
+    // A doc whose ONLY node is a math atom. Its LaTeX is in `attrs.text`, there is
+    // no text node, and `jsonToText`/`generateText` has no serializer for it -> it
+    // yields empty text_content and zero embeddings, so it must NOT qualify.
+    const mathOnlyDoc = JSON.stringify({
+      type: 'doc',
+      content: [
+        { type: 'mathBlock', attrs: { text: 'E = mc^2' } },
+        { type: 'mathInline', attrs: { text: '\\alpha' } },
+      ],
+    });
+    // An empty doc has no text node either.
+    const emptyDoc = JSON.stringify({ type: 'doc', content: [] });
+
+    expect(re.test(textDoc)).toBe(true);
+    expect(re.test(mathOnlyDoc)).toBe(false);
+    expect(re.test(emptyDoc)).toBe(false);
+    // Sanity: the OLD bare-key regex WOULD have wrongly matched the math-only doc,
+    // which is precisely the false positive the narrowing removes.
+    expect(/"text"\s*:/.test(mathOnlyDoc)).toBe(true);
+
+    // A user literally TYPING `"type":"text"` in prose can't false-positive on an
+    // otherwise text-less page: in `content::text` the typed value's quotes are
+    // escaped (`\"type\":\"text\"`), so the literal-quote regex does not match the
+    // escaped form. (And such a page is a genuine text node anyway.)
+    const escapedLiteral = JSON.stringify({
+      type: 'doc',
+      content: [{ type: 'someAtom', attrs: { note: '"type":"text"' } }],
+    });
+    expect(re.test(escapedLiteral)).toBe(false);
+  });
+});

apps/server/src/database/repos/page/page.repo.spec.ts

@@ -0,0 +1,157 @@
+import {
+  Kysely,
+  CamelCasePlugin,
+  DummyDriver,
+  PostgresAdapter,
+  PostgresIntrospector,
+  PostgresQueryCompiler,
+  CompiledQuery,
+} from 'kysely';
+import { PageRepo } from './page.repo';
+import type { KyselyDB } from '../../types/kysely.types';
+
+/**
+ * SQL-builder unit test for the git-sync provenance stamp on PageRepo's
+ * soft-delete / restore paths (PR #119 review). Both `removePage` and
+ * `restorePage` take an optional `lastUpdatedSource` arg and conditionally fold
+ * it into the recursive-subtree `UPDATE pages SET ...` via
+ * `...(lastUpdatedSource ? { lastUpdatedSource } : {})`. The change-listener
+ * loop-guard reads `last_updated_source = 'git-sync'` to recognize git-sync's own
+ * writes and skip the echo cycle; this test guards that the stamp is present when
+ * the arg is supplied and ABSENT when it is omitted (an ordinary user delete must
+ * not clobber the column).
+ *
+ * Harness: the same compile-only Kysely/DummyDriver pattern as
+ * space.repo.spec.ts, plus the production `CamelCasePlugin` (so the compiled SQL
+ * carries the real snake_case column names, e.g. `last_updated_source`) and a
+ * thin driver that returns ONE fixed row for every query. The fixed row is what
+ * lets the repo's guard reads (root snapshot / recursive descendants / restore
+ * target) resolve non-empty so execution reaches the subtree UPDATE we assert on
+ * — a bare DummyDriver returns no rows and both methods short-circuit before the
+ * update. We never hit a real database; we capture each compiled statement via
+ * Kysely's `log` hook and inspect the `update "pages" set ...` SQL.
+ */
+describe('PageRepo — git-sync provenance on soft-delete / restore SQL', () => {
+  // A single row shaped to satisfy every column the repo reads off its guard
+  // queries. `parentPageId: null` keeps restorePage on the simple path (no
+  // parent-detach UPDATE), so the only `update "pages"` statement is the one we
+  // assert on.
+  const FIXED_ROW = {
+    id: 'p1',
+    slugId: 's1',
+    title: 'Doc',
+    icon: null,
+    position: 'a0',
+    spaceId: 'space-1',
+    parentPageId: null,
+    deletedAt: null,
+  };
+
+  class FixedRowDriver extends DummyDriver {
+    async acquireConnection(): Promise<any> {
+      return {
+        async executeQuery() {
+          return { rows: [{ ...FIXED_ROW }] };
+        },
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        async *streamQuery() {},
+      };
+    }
+  }
+
+  interface Captured {
+    sql: string;
+    parameters: readonly unknown[];
+  }
+
+  // Compile-only Kysely on the Postgres dialect (CamelCasePlugin for real column
+  // names) whose `log` hook records every executed statement's compiled SQL.
+  function makeRepoCapturingSql() {
+    const captured: Captured[] = [];
+    const db = new Kysely<any>({
+      dialect: {
+        createAdapter: () => new PostgresAdapter(),
+        createDriver: () => new FixedRowDriver(),
+        createIntrospector: (d) => new PostgresIntrospector(d),
+        createQueryCompiler: () => new PostgresQueryCompiler(),
+      },
+      plugins: [new CamelCasePlugin()],
+      log: (event) => {
+        if (event.level === 'query') {
+          const q = event.query as CompiledQuery;
+          captured.push({ sql: q.sql, parameters: q.parameters });
+        }
+      },
+    });
+
+    const repo = new PageRepo(
+      db as unknown as KyselyDB,
+      {} as any,
+      { emit: jest.fn() } as any,
+    );
+    // Find the single subtree UPDATE on pages (collapse whitespace for matching).
+    const getUpdatePagesSql = (): Captured | undefined =>
+      captured
+        .map((c) => ({ ...c, sql: c.sql.replace(/\s+/g, ' ') }))
+        .find((c) => /update "pages" set/i.test(c.sql));
+    return { repo, getUpdatePagesSql };
+  }
+
+  describe('removePage', () => {
+    it("stamps last_updated_source = 'git-sync' on the subtree soft-delete when the provenance arg is supplied", async () => {
+      const { repo, getUpdatePagesSql } = makeRepoCapturingSql();
+
+      await repo.removePage('p1', 'user-1', 'ws-1', 'git-sync');
+
+      const update = getUpdatePagesSql();
+      expect(update).toBeDefined();
+      // The provenance column is in the UPDATE's SET clause...
+      expect(update!.sql).toContain('"last_updated_source" =');
+      // ...with the 'git-sync' marker as the bound value.
+      expect(update!.parameters).toContain('git-sync');
+      // Sanity: it is still the soft-delete UPDATE (sets deleted_at too).
+      expect(update!.sql).toContain('"deleted_at" =');
+    });
+
+    it('OMITS last_updated_source from the soft-delete when the provenance arg is undefined', async () => {
+      const { repo, getUpdatePagesSql } = makeRepoCapturingSql();
+
+      await repo.removePage('p1', 'user-1', 'ws-1');
+
+      const update = getUpdatePagesSql();
+      expect(update).toBeDefined();
+      // Ordinary user delete: the column must NOT be touched (keeps prior value).
+      expect(update!.sql).not.toContain('last_updated_source');
+      expect(update!.parameters).not.toContain('git-sync');
+      // It is still the soft-delete UPDATE.
+      expect(update!.sql).toContain('"deleted_at" =');
+    });
+  });
+
+  describe('restorePage', () => {
+    it("stamps last_updated_source = 'git-sync' on the subtree restore when the provenance arg is supplied", async () => {
+      const { repo, getUpdatePagesSql } = makeRepoCapturingSql();
+
+      await repo.restorePage('p1', 'ws-1', 'git-sync');
+
+      const update = getUpdatePagesSql();
+      expect(update).toBeDefined();
+      expect(update!.sql).toContain('"last_updated_source" =');
+      expect(update!.parameters).toContain('git-sync');
+      // Sanity: it is the restore UPDATE (clears deleted_at).
+      expect(update!.sql).toContain('"deleted_at" =');
+    });
+
+    it('OMITS last_updated_source from the restore when the provenance arg is undefined', async () => {
+      const { repo, getUpdatePagesSql } = makeRepoCapturingSql();
+
+      await repo.restorePage('p1', 'ws-1');
+
+      const update = getUpdatePagesSql();
+      expect(update).toBeDefined();
+      expect(update!.sql).not.toContain('last_updated_source');
+      expect(update!.parameters).not.toContain('git-sync');
+      expect(update!.sql).toContain('"deleted_at" =');
+    });
+  });
+});