fix(offline): address PR #120 review (comment 2513)

CHANGELOG: stop presenting the service-worker API cache as an active offline
store (/api is NetworkOnly) — describe it as a defensive purge of the legacy
api-get-cache from older clients; add an explicit upgrade note that the new CORS
allowlist rejects previously-allowed cross-domain REST clients until their origin
is added to CORS_ALLOWED_ORIGINS.

test(offline): cover make-offline ancestor-walk + dedup — a real-ancestor case
exercising the ancestorId===pageId guard (page warmed once), the dedup of
repeated tree failures into a single "tree" label, and the "breadcrumbs" label
when the breadcrumbs lookup rejects.

test(auth): cover clearOfflineCache in handleLogout — purged exactly once before
window.location.replace, and a thrown purge error does not block the redirect.

conventions: use pageKeys.detail() instead of raw ["pages", …] literals in
title-editor and use-page-collab-providers.

cleanup: remove the dead emit() in title-editor (the gateway ignores it; the
cross-user tree refresh is server-side via the Yjs title fragment); drop the
trivial Array.isArray(tiptapExtensions) test (schema is exercised transitively).

refactor: extract the shared page.<id> Yjs doc-name convention into
pageYdocName()/PAGE_YDOC_NAME_PREFIX so the editor providers, offline warm, and
offline purge can no longer drift apart.

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

.env.example

@@ -92,6 +92,19 @@ IFRAME_EMBED_ALLOWED=false
 # Example: https://intranet.example.com,https://portal.example.com
 IFRAME_ALLOWED_ORIGINS=
 
+# Comma-separated list of additional origins allowed to call the API via CORS.
+# The APP_URL origin and native mobile (Capacitor) origins are always allowed.
+# Leave empty for a same-origin (web-only) deployment.
+CORS_ALLOWED_ORIGINS=
+
+# Expose OpenAPI/Swagger docs at /api/docs (development/debugging aid only).
+SWAGGER_ENABLED=false
+
+# Capacitor (mobile shell): hosted client URL loaded by the iOS shell so the
+# AGPL web client is NOT bundled into the .ipa (see docs/mobile-app-plan.md §9).
+# Leave empty for Android bundled mode / local development.
+CAP_SERVER_URL=
+
 # Enable debug logging in production (default: false)
 DEBUG_MODE=false
 
@@ -124,26 +137,6 @@ MCP_DOCMOST_PASSWORD=
 # MCP_TOKEN=
 # MCP_SESSION_IDLE_MS=1800000
 #
-# BLOB SANDBOX (stash_page). An in-RAM, process-local store that hands large page
-# content + images to an external consumer WITHOUT bloating the model context or
-# requiring Docmost auth. The stash_page tool serializes a page, mirrors its
-# internal images into the store, and returns ONLY a short anonymous URL; the
-# consumer fetches blobs via `GET /api/sb/<uuid>` (no token — the capability is
-# the unguessable UUID + short TTL + TLS). Blobs are RAM-only and cleared on
-# restart. ETag = the blob's sha256 (integrity check).
-# SANDBOX_PUBLIC_URL is the base used to build those URLs; it MUST be reachable
-# by the consumer (do NOT use a loopback address if the consumer is remote).
-# Defaults to APP_URL when unset.
-# NOTE: the store is process-local — blobs live only on the instance that
-# created them. Behind a multi-replica load balancer WITHOUT sticky sessions a
-# consumer may hit a different instance and get a 404 (indistinguishable from an
-# expired blob). Single-host deployments are unaffected.
-# SANDBOX_PUBLIC_URL=https://docs.example.com
-# SANDBOX_TTL_MS=3600000
-# SANDBOX_MAX_BYTES=8388608
-# SANDBOX_MAX_IMAGE_BYTES=20971520
-# SANDBOX_MAX_TOTAL_BYTES=134217728
-#
 # AI-AGENT ATTRIBUTION (comments/pages written via MCP are badged as "AI"):
 # attribution is driven by a per-user `is_agent` flag on the users row. There is
 # NO admin UI/API for it — set it out-of-band with SQL. Use a DEDICATED service
@@ -153,7 +146,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.yaml and /bundles/<id>/<lang>.yaml). This value is
+# (the server appends /index.json and /bundles/<id>/<lang>.json). 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,45 +216,3 @@ 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,7 +25,6 @@ jobs:
   build:
     needs: test
     runs-on: ubuntu-latest
-    timeout-minutes: 30
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -66,8 +65,6 @@ 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
@@ -126,7 +123,6 @@ 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,7 +15,6 @@ 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
@@ -69,13 +68,6 @@ 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,12 +5,6 @@ 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
@@ -55,3 +49,8 @@ lerna-debug.log*
 
 # Self-hosted VAD / onnxruntime-web assets (copied from node_modules at dev/build time)
 apps/client/public/vad/
+
+# Capacitor native platform projects (generated locally via 'npx cap add ios|android')
+/ios
+/android
+.capacitor

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**. Five workspace packages:
+pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Four workspace packages:
 
 | Path | Name | Stack | Role |
 | --- | --- | --- | --- |
@@ -190,7 +190,6 @@ pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Five 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`.
 
@@ -242,12 +241,10 @@ Migration files live in `apps/server/src/database/migrations/` and are named `YY
 - **API server** — `dist/main` (`apps/server/src/main.ts`), the Fastify HTTP app (`AppModule`).
 - **Collaboration server** — `dist/collaboration/server/collab-main` (`pnpm collab`), a Hocuspocus/Yjs WebSocket server (`apps/server/src/collaboration/`) handling real-time document editing, persistence, and page-history snapshots. It listens on `COLLAB_PORT` (default `3001`), separate from the API server's `PORT` (default `3000`), and shares state with the API server through Redis.
 
-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.
+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`). Auth is JWT (cookie + bearer); authorization is **CASL** (`core/casl`) — every data access is scoped to the user's abilities.
 
 ### Module structure (server)
-`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`.
+`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`.
 
 **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.
 
@@ -257,22 +254,16 @@ Two routes are mounted **outside** the `/api` prefix at the root, as raw Fastify
 - **Redis** backs caching, the BullMQ queues, the WebSocket Socket.IO adapter, and collaboration sync.
 
 ### The two AI subsystems (the main fork additions)
-1. **Embedded MCP server** (`integrations/mcp/` + `packages/mcp`). The standalone `@docmost/mcp` server (40 agent-native tools: per-block patch/insert/delete by id, scripted `(doc)=>doc` transforms with dry-run diff, table editing, version diff/restore, comments, images, shares) is bundled and served over HTTP at `/mcp`. It writes through Docmost's real-time-collaboration layer so concurrent human edits aren't clobbered. Each request authenticates **per-user** via the `Authorization` header — either HTTP Basic (`base64(email:password)`, the user's own Docmost login, validated through `AuthService`) or a Bearer access JWT (the user's `authToken`) — and the session acts under that user's permissions. `MCP_DOCMOST_EMAIL` / `MCP_DOCMOST_PASSWORD` are an **optional service-account fallback**, used only when a request carries neither Basic nor Bearer credentials (back-compat for CI/scripts). An admin enables MCP with a workspace toggle (Workspace settings → AI). Optionally protected by a shared `MCP_TOKEN`: when set, every `/mcp` request must carry a matching `X-MCP-Token` header (its own header, separate from `Authorization`, which now carries the per-user Basic/Bearer credentials). Note: this changed from the older `Authorization: Bearer <MCP_TOKEN>` scheme — see `.env.example` and the CHANGELOG Breaking Changes entry.
+1. **Embedded MCP server** (`integrations/mcp/` + `packages/mcp`). The standalone `@docmost/mcp` server (39 agent-native tools: per-block patch/insert/delete by id, scripted `(doc)=>doc` transforms with dry-run diff, table editing, version diff/restore, comments, images, shares) is bundled and served over HTTP at `/mcp`. It writes through Docmost's real-time-collaboration layer so concurrent human edits aren't clobbered. Each request authenticates **per-user** via the `Authorization` header — either HTTP Basic (`base64(email:password)`, the user's own Docmost login, validated through `AuthService`) or a Bearer access JWT (the user's `authToken`) — and the session acts under that user's permissions. `MCP_DOCMOST_EMAIL` / `MCP_DOCMOST_PASSWORD` are an **optional service-account fallback**, used only when a request carries neither Basic nor Bearer credentials (back-compat for CI/scripts). An admin enables MCP with a workspace toggle (Workspace settings → AI). Optionally protected by a shared `MCP_TOKEN`: when set, every `/mcp` request must carry a matching `X-MCP-Token` header (its own header, separate from `Authorization`, which now carries the per-user Basic/Bearer credentials). Note: this changed from the older `Authorization: Bearer <MCP_TOKEN>` scheme — see `.env.example` and the CHANGELOG Breaking Changes entry.
 2. **AI agent chat** (`core/ai-chat/` server + `apps/client/src/features/ai-chat/` client). A built-in agent over the wiki using the Vercel **AI SDK** (`ai`, `@ai-sdk/*`) against any OpenAI-compatible provider configured per workspace (`integrations/ai/` — credentials encrypted at rest via `integrations/crypto`, stored in `ai_provider_credentials`). Key pieces:
    - `core/ai-chat/tools/` — the agent's ~40 read+write tools. Every tool runs under the **calling user's** CASL permissions via a per-user loopback access token (`docmost-client.loader.ts`), so the agent can never exceed what the user could do. Only **reversible** operations are exposed (page history + trash; no permanent delete). Agent edits get an "AI agent" provenance badge in page history (`20260616T130000-agent-provenance` migration).
    - `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 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.
+- 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.
 - 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,20 +12,6 @@ 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)
 - **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),
@@ -72,15 +58,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   append/prepend fragments, nor to COMMENT bodies — a comment may legitimately
   contain a standalone footnote definition, which canonicalization would drop.
   (#228)
-- **Out-of-band page transfer via an in-RAM blob sandbox (`stash_page`).** A
-  new MCP tool serializes a whole page (its full ProseMirror JSON, with every
-  internal image/file mirrored) into an ephemeral in-RAM blob and returns only
-  a short anonymous URL, so a large page can be handed to an external consumer
-  without flooding the model context. Blobs are served by unguessable UUID over
-  a new anonymous `GET /api/sb/:id` route (strong sha256 ETag, short TTL,
-  `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)
 
 ### Changed
 
@@ -90,17 +67,32 @@ 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)
+- **Offline reading support**: opened pages, their sidebar tree, breadcrumb
+  children, and comments are cached in IndexedDB (TanStack Query persister plus
+  `y-indexeddb` for the page's Yjs document), and a PWA service worker
+  (vite-plugin-pwa) serves an app shell so previously opened pages stay readable
+  offline. The two offline stores (the persisted query cache and the Yjs page
+  documents) are cleared on logout AND on sign-in so a previous user's private
+  data does not remain in the browser; the same purge also defensively drops any
+  legacy service-worker `api-get-cache` left by older clients (current builds
+  serve `/api` as NetworkOnly, so there is no active service-worker API cache).
+- **Mobile bootstrap**: a `returnToken` opt-in on login so native/mobile clients
+  can request the access JWT in the response body (`data.authToken`) in addition
+  to the httpOnly cookie (the web client stays cookie-only); an optional
+  OpenAPI/Swagger UI at `/api/docs` gated by `SWAGGER_ENABLED` (off by default);
+  and new env vars `CORS_ALLOWED_ORIGINS`, `SWAGGER_ENABLED`, `CAP_SERVER_URL`.
+
+### Changed
+
+- **CORS is now an explicit allowlist** (replaces the previous unconfigured
+  `app.enableCors()`). The same-origin web client is unaffected, but any
+  separately-hosted cross-domain client must now be listed in
+  `CORS_ALLOWED_ORIGINS` (native Capacitor/Ionic/localhost WebView origins are
+  allowed automatically). Requests with no `Origin` header (server-to-server)
+  are still allowed. **Upgrade note:** the old bare `app.enableCors()` reflected
+  *any* origin (with `credentials:false`), so any previously-working cross-domain
+  REST/browser client is now rejected until its origin is added to
+  `CORS_ALLOWED_ORIGINS` (see `.env.example`).
 
 ### Fixed
 

Dockerfile

@@ -17,9 +17,8 @@ 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 git \
+  && apt-get install -y --no-install-recommends curl bash \
   && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
@@ -39,14 +38,6 @@ 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

README.md

@@ -34,7 +34,7 @@ The goal of the fork is a **100% open, AGPL-only build with no Enterprise-Editio
 | --- | --- |
 | **EE code removed** | Stripped all client and server Enterprise-Edition code; ships as a clean community/AGPL build with no license checks. |
 | **Comment resolution** | Re-implemented from scratch as a community feature (resolve / re-open with Open/Resolved tabs). No EE code reused, available to anyone who can comment. |
-| **Embedded MCP server** | A community MCP server (`@docmost/mcp`, 40 tools) is served over HTTP at `/mcp` — no enterprise license required. Replaces the removed license-gated EE MCP. |
+| **Embedded MCP server** | A community MCP server (`@docmost/mcp`, 39 tools) is served over HTTP at `/mcp` — no enterprise license required. Replaces the removed license-gated EE MCP. |
 | **AI agent chat** | Built-in AI agent chat over your wiki, written from scratch as a community feature — no enterprise license. The agent reads and edits pages on your behalf (scoped to your permissions), with full-text + vector (RAG) search and optional web access via external MCP servers. |
 | **Rebranding** | App logo / name changed from *Docmost* to *Gitmost*. |
 | **Compact page tree** | Default page-tree indentation reduced from 16px to 8px per nesting level. |
@@ -44,7 +44,7 @@ The goal of the fork is a **100% open, AGPL-only build with no Enterprise-Editio
 ### Embedded MCP server
 
 Gitmost has **our own MCP server** — [docmost-mcp](https://github.com/vvzvlad/docmost-mcp),
-which we wrote — **built directly into the app** and served at `/mcp`. It exposes **40
+which we wrote — **built directly into the app** and served at `/mcp`. It exposes **39
 agent-native tools**: surgical per-block edits (patch / insert / delete by id),
 structure-preserving find/replace, scripted `(doc) => doc` transforms with a dry-run diff,
 structured table editing, version history with diff / restore, comments, images and share
@@ -60,7 +60,7 @@ every little fix. And it needs no enterprise license.
 | | **Gitmost `/mcp` (our docmost-mcp)** | Docmost's built-in MCP |
 | --- | :---: | :---: |
 | **Enterprise license** | Not required | Required |
-| **Tools** | 40, agent-native | Coarse (read Markdown, page CRUD, replace whole page) |
+| **Tools** | 39, agent-native | Coarse (read Markdown, page CRUD, replace whole page) |
 | **Per-block edits / find-replace / scripted transforms** | ✅ | — |
 | **Structured table editing, version diff / restore** | ✅ | — |
 | **Comments, images, share links** | ✅ | — |

README.ru.md

@@ -33,7 +33,7 @@
 | --- | --- |
 | **Удалён EE-код** | Вырезан весь код Enterprise-редакции на клиенте и сервере; это чистая community/AGPL-сборка без лицензионных проверок. |
 | **Резолв комментариев** | Переписан с нуля как community-функция (резолв / переоткрытие с вкладками «Открытые» / «Решённые»). EE-код не используется, доступно любому, кто может комментировать. |
-| **Встроенный MCP-сервер** | Community MCP-сервер (`@docmost/mcp`, 40 инструментов) отдаётся по HTTP на `/mcp` — без enterprise-лицензии. Заменяет удалённый лицензируемый EE MCP. |
+| **Встроенный MCP-сервер** | Community MCP-сервер (`@docmost/mcp`, 39 инструментов) отдаётся по HTTP на `/mcp` — без enterprise-лицензии. Заменяет удалённый лицензируемый EE MCP. |
 | **Чат с AI-агентом** | Встроенный чат с AI-агентом по содержимому вики, написанный с нуля как community-функция — без enterprise-лицензии. Агент читает и редактирует страницы от вашего имени (в рамках ваших прав), с полнотекстовым + векторным (RAG) поиском и опциональным доступом в интернет через внешние MCP-серверы. |
 | **Ребрендинг** | Логотип / название приложения изменены с *Docmost* на *Gitmost*. |
 | **Компактное дерево страниц** | Отступ дерева страниц по умолчанию уменьшен с 16px до 8px на уровень вложенности. |
@@ -44,7 +44,7 @@
 
 В Gitmost есть **наш собственный MCP-сервер** — [docmost-mcp](https://github.com/vvzvlad/docmost-mcp),
 который мы написали сами, — **встроенный прямо в приложение** и доступный на `/mcp`. Он даёт
-**40 agent-native инструментов**: точечное редактирование по блокам (patch / insert / delete
+**39 agent-native инструментов**: точечное редактирование по блокам (patch / insert / delete
 по id), find/replace с сохранением структуры, скриптовые трансформации `(doc) => doc` с
 предпросмотром диффа, структурное редактирование таблиц, история версий с диффом /
 восстановлением, комментарии, изображения и ссылки на шаринг — всё применяется через слой
@@ -60,7 +60,7 @@ real-time-коллаборации Docmost, поэтому запись нико
 | | **`/mcp` в Gitmost (наш docmost-mcp)** | Родной MCP у Docmost |
 | --- | :---: | :---: |
 | **Enterprise-лицензия** | Не нужна | Нужна |
-| **Инструменты** | 40, agent-native | Примитивные (Markdown, CRUD страниц, замена целиком) |
+| **Инструменты** | 39, agent-native | Примитивные (Markdown, CRUD страниц, замена целиком) |
 | **Правки по блокам / find-replace / скриптовые трансформации** | ✅ | — |
 | **Структурное редактирование таблиц, дифф / восстановление версий** | ✅ | — |
 | **Комментарии, изображения, ссылки на шаринг** | ✅ | — |

agent-roles-catalog/README.md

@@ -10,23 +10,17 @@ executable application logic except the validation script.
 
 ```
 agent-roles-catalog/
-  index.yaml                  # the catalog manifest: bundles, languages, role versions
+  index.json                  # the catalog manifest: bundles, languages, role versions
   bundles/
     <bundle-id>/
-      <lang>.yaml             # one file per declared language (e.g. ru.yaml, en.yaml)
+      <lang>.json             # one file per declared language (e.g. ru.json, en.json)
   scripts/
-    check.mjs                 # validates the catalog (uses the `yaml` parser)
+    check.mjs                 # validates the catalog (no dependencies)
     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,
@@ -38,8 +32,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.yaml` for the
-manifest and `<base>/bundles/<bundle-id>/<lang>.yaml` for each opened bundle
+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
 file (REMOTE only).
 
 That base URL is provided as a per-branch default in the Docker image (set in
@@ -48,56 +42,54 @@ 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 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.
+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.
 
-## `index.yaml` schema
+## `index.json` schema
 
-```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
-      # ...
+```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 }
+        // ...
+      ]
+    }
+  ]
+}
 ```
 
-`version` lives **here, in index.yaml**, per role. Bump it whenever a role's
+`version` lives **here, in index.json**, per role. Bump it whenever a role's
 content (instructions, name, description, etc.) changes, so consumers can detect
 updates.
 
-## Bundle (`<lang>.yaml`) schema
+## Bundle (`<lang>.json`) schema
 
-```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)
+```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)
+    }
+  ]
+}
 ```
 
-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
@@ -110,39 +102,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.yaml` and `en.yaml`), but no two different bundles may share a slug.
+`ru.json` and `en.json`), 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.yaml` with a new unique
+1. Add an entry to that bundle's `roles[]` in `index.json` with a new unique
    `slug` and `version: 1`.
-2. Add a role object with the same `slug` to **every** `<lang>.yaml` of the
+2. Add a role object with the same `slug` to **every** `<lang>.json` 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.yaml` (`id`, `name`, `description`,
+1. Add a bundle object to `index.json` (`id`, `name`, `description`,
    `languages`, `roles`).
-2. Create `bundles/<id>/<lang>.yaml` for each declared language, with one role
+2. Create `bundles/<id>/<lang>.json` 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.yaml`.
-2. Create `bundles/<id>/<lang>.yaml` containing every role of the 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,
    translated.
 3. Run the check.
 
 ### Change a role's content
 
-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`
+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`
 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.
@@ -168,7 +160,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.yaml` and the bundle `<lang>.yaml` files, never this file, so it has no
+`index.json` and the bundle `<lang>.json` 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
@@ -190,9 +182,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.yaml` version was not bumped, so the
+role's content changed while its `index.json` version was not bumped, so the
 version bump is always enforced first. The check also requires every
-`index.yaml` role to carry a finite numeric `version` (the server requires the
+`index.json` 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

@@ -1,280 +0,0 @@
-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

@@ -1,281 +0,0 @@
-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

@@ -1,129 +0,0 @@
-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

@@ -1,129 +0,0 @@
-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

@@ -0,0 +1,31 @@
+{
+  "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

@@ -1,36 +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/package.json

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

agent-roles-catalog/scripts/check.mjs

@@ -8,14 +8,6 @@ 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, "..");
@@ -31,21 +23,6 @@ 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"));
@@ -55,13 +32,13 @@ function readJson(path) {
   }
 }
 
-const indexPath = join(catalogDir, "index.yaml");
+const indexPath = join(catalogDir, "index.json");
 if (!existsSync(indexPath)) {
-  console.error(`Missing index.yaml at ${indexPath}`);
+  console.error(`Missing index.json at ${indexPath}`);
   process.exit(1);
 }
 
-const index = readYaml(indexPath);
+const index = readJson(indexPath);
 if (!index) {
   for (const e of errors) console.error(e);
   process.exit(1);
@@ -69,7 +46,7 @@ if (!index) {
 
 const bundles = Array.isArray(index.bundles) ? index.bundles : [];
 if (bundles.length === 0) {
-  errors.push("index.yaml has no bundles[]");
+  errors.push("index.json has no bundles[]");
 }
 
 // Track every slug seen across the whole catalog to detect duplicates.
@@ -78,7 +55,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.yaml is missing an id");
+    errors.push("A bundle in index.json is missing an id");
     continue;
   }
 
@@ -86,7 +63,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.yaml roles[] contains duplicate slugs`);
+    errors.push(`Bundle "${bundleId}" index.json roles[] contains duplicate slugs`);
   }
 
   // Each index role must carry a finite numeric "version". The server requires
@@ -95,7 +72,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.yaml role "${r.slug}" is missing a numeric "version"`
+        `Bundle "${bundleId}" index.json role "${r.slug}" is missing a numeric "version"`
       );
     }
   }
@@ -106,13 +83,13 @@ for (const bundle of bundles) {
   }
 
   for (const lang of languages) {
-    const langPath = join(catalogDir, "bundles", bundleId, `${lang}.yaml`);
+    const langPath = join(catalogDir, "bundles", bundleId, `${lang}.json`);
     if (!existsSync(langPath)) {
       errors.push(`Bundle "${bundleId}" declares language "${lang}" but ${langPath} is missing`);
       continue;
     }
 
-    const langFile = readYaml(langPath);
+    const langFile = readJson(langPath);
     if (!langFile) continue;
 
     const roles = Array.isArray(langFile.roles) ? langFile.roles : [];
@@ -135,12 +112,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.yaml: ${missingInFile.join(", ")}`
+        `Bundle "${bundleId}/${lang}" is missing roles declared in index.json: ${missingInFile.join(", ")}`
       );
     }
     if (extraInFile.length > 0) {
       errors.push(
-        `Bundle "${bundleId}/${lang}" has roles not declared in index.yaml: ${extraInFile.join(", ")}`
+        `Bundle "${bundleId}/${lang}" has roles not declared in index.json: ${extraInFile.join(", ")}`
       );
     }
 
@@ -172,7 +149,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.yaml has been bumped and the lock refreshed.
+// version in index.json 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
@@ -181,7 +158,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.yaml, so neither is here.
+// identity (not content) and `version` lives in index.json, 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 —
@@ -210,20 +187,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.yaml roles[]; already flagged above.
+        // Same slug declared twice in index.json roles[]; already flagged above.
         out.get(r.slug).version = r.version;
       }
     }
     for (const lang of languages) {
-      const langPath = join(catalogDir, "bundles", bundleId, `${lang}.yaml`);
+      const langPath = join(catalogDir, "bundles", bundleId, `${lang}.json`);
       if (!existsSync(langPath)) continue;
-      const langFile = readYaml(langPath);
+      const langFile = readJson(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.yaml; flagged above.
+        if (!entry) continue; // role not declared in index.json; flagged above.
         entry.langRoles.set(lang, role);
       }
     }
@@ -276,11 +253,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.yaml "version" is missing or not numeric; set a numeric "version" before refreshing the lock`
+        `role "${slug}" content changed but its index.json "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.yaml before refreshing the lock`
+        `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.json before refreshing the lock`
       );
     }
   }
@@ -332,10 +309,10 @@ for (const [slug, cur] of current) {
     continue;
   }
   if (cur.hash === prev.hash) {
-    // Content unchanged; the lock version must still agree with index.yaml.
+    // Content unchanged; the lock version must still agree with index.json.
     if (cur.version !== prev.version) {
       errors.push(
-        `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`
+        `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`
       );
     }
     continue;
@@ -346,11 +323,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.yaml "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.json "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.yaml, 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.json, then run: node scripts/check.mjs --update-hashes`
     );
   } else {
     errors.push(

apps/client/index.html

@@ -10,6 +10,7 @@
     <meta name="theme-color" content="#0E1117" media="(prefers-color-scheme: dark)" />
     <meta name="theme-color" content="#f6f7f9" media="(prefers-color-scheme: light)" />
     <link rel="manifest" href="/manifest.json" />
+    <link rel="apple-touch-icon" href="/icons/app-icon-192x192.png" />
     <meta name="mobile-web-app-capable" content="yes" />
     <meta name="apple-touch-fullscreen" content="yes" />
     <meta name="apple-mobile-web-app-title" content="Gitmost" />

apps/client/package.json

@@ -33,7 +33,9 @@
     "@slidoapp/emoji-mart-data": "1.2.4",
     "@slidoapp/emoji-mart-react": "1.1.5",
     "@tabler/icons-react": "3.40.0",
+    "@tanstack/query-async-storage-persister": "5.90.17",
     "@tanstack/react-query": "5.90.17",
+    "@tanstack/react-query-persist-client": "5.90.17",
     "@tanstack/react-virtual": "3.13.24",
     "ai": "6.0.207",
     "alfaaz": "1.1.0",
@@ -45,6 +47,7 @@
     "highlightjs-sap-abap": "0.3.0",
     "i18next": "25.10.1",
     "i18next-http-backend": "3.0.6",
+    "idb-keyval": "6.2.5",
     "jotai": "2.18.1",
     "jotai-optics": "0.4.0",
     "js-cookie": "3.0.7",
@@ -95,6 +98,7 @@
     "typescript": "5.9.3",
     "typescript-eslint": "8.57.1",
     "vite": "8.0.5",
+    "vite-plugin-pwa": "1.3.0",
     "vitest": "4.1.6"
   }
 }

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

@@ -464,6 +464,18 @@
   "Move page": "Move page",
   "Move page to a different space.": "Move page to a different space.",
   "Real-time editor connection lost. Retrying...": "Real-time editor connection lost. Retrying...",
+  "Offline — changes are saved locally and will sync when you reconnect": "Offline — changes are saved locally and will sync when you reconnect",
+  "Syncing changes…": "Syncing changes…",
+  "All changes synced": "All changes synced",
+  "Update available": "Update available",
+  "Reload": "Reload",
+  "Make available offline": "Make available offline",
+  "Saving page for offline use...": "Saving page for offline use...",
+  "Page is now available offline": "Page is now available offline",
+  "Failed to make page available offline": "Failed to make page available offline",
+  "You're offline": "You're offline",
+  "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.": "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.",
+  "Retry": "Retry",
   "Table of contents": "Table of contents",
   "Add headings (H1, H2, H3) to generate a table of contents.": "Add headings (H1, H2, H3) to generate a table of contents.",
   "Share": "Share",
@@ -1217,8 +1229,6 @@
   "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.",
@@ -1243,10 +1253,6 @@
   "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

@@ -474,6 +474,18 @@
   "Move page": "Переместить страницу",
   "Move page to a different space.": "Переместите страницу в другое пространство.",
   "Real-time editor connection lost. Retrying...": "Соединение с редактором в реальном времени потеряно. Повторная попытка...",
+  "Offline — changes are saved locally and will sync when you reconnect": "Нет сети — изменения сохраняются локально и синхронизируются при восстановлении соединения",
+  "Syncing changes…": "Синхронизация изменений…",
+  "All changes synced": "Все изменения синхронизированы",
+  "Update available": "Доступно обновление",
+  "Reload": "Перезагрузить",
+  "Make available offline": "Сделать доступным офлайн",
+  "Saving page for offline use...": "Сохраняем страницу для офлайн-доступа…",
+  "Page is now available offline": "Страница доступна офлайн",
+  "Failed to make page available offline": "Не удалось сделать страницу доступной офлайн",
+  "You're offline": "Вы офлайн",
+  "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.": "Эта страница не была сохранена для офлайн-доступа, поэтому её нельзя загрузить сейчас. Подключитесь к интернету и попробуйте снова.",
+  "Retry": "Повторить",
   "Table of contents": "Оглавление",
   "Add headings (H1, H2, H3) to generate a table of contents.": "Добавьте заголовки (H1, H2, H3), чтобы создать оглавление.",
   "Share": "Поделиться",

apps/client/public/manifest.json

@@ -1,30 +1,19 @@
 {
+  "id": "/",
   "name": "Gitmost",
   "short_name": "Gitmost",
+  "description": "Gitmost - open-source collaborative documentation and knowledge base.",
+  "lang": "en",
   "start_url": "/",
+  "scope": "/",
   "display": "standalone",
+  "orientation": "any",
   "background_color": "#0E1117",
   "theme_color": "#0E1117",
   "icons": [
-    {
-      "src": "icons/favicon-16x16.png",
-      "type": "image/png",
-      "sizes": "16x16"
-    },
-    {
-      "src": "icons/favicon-32x32.png",
-      "type": "image/png",
-      "sizes": "32x32"
-    },
-    {
-      "src": "icons/app-icon-192x192.png",
-      "type": "image/png",
-      "sizes": "180x180 192x192"
-    },
-    {
-      "src": "icons/app-icon-512x512.png",
-      "type": "image/png",
-      "sizes": "512x512"
-    }
+    { "src": "icons/favicon-16x16.png", "type": "image/png", "sizes": "16x16" },
+    { "src": "icons/favicon-32x32.png", "type": "image/png", "sizes": "32x32" },
+    { "src": "icons/app-icon-192x192.png", "type": "image/png", "sizes": "192x192", "purpose": "any" },
+    { "src": "icons/app-icon-512x512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" }
   ]
 }

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

@@ -1,37 +0,0 @@
-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/auth/hooks/use-auth.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+// react-i18next: identity t() so the hook renders without an i18n provider.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (k: string) => k }),
+}));
+
+// react-router-dom: only useNavigate is used by the hook.
+const navigateMock = vi.fn();
+vi.mock("react-router-dom", () => ({
+  useNavigate: () => navigateMock,
+}));
+
+// The auth service is the network boundary; stub login/logout per test.
+const loginMock = vi.fn();
+const logoutMock = vi.fn();
+vi.mock("@/features/auth/services/auth-service", () => ({
+  login: (...args: unknown[]) => loginMock(...args),
+  logout: (...args: unknown[]) => logoutMock(...args),
+  forgotPassword: vi.fn(),
+  passwordReset: vi.fn(),
+  setupWorkspace: vi.fn(),
+  verifyUserToken: vi.fn(),
+}));
+
+vi.mock("@/features/workspace/services/workspace-service.ts", () => ({
+  acceptInvitation: vi.fn(),
+}));
+
+// The offline cache purge is the unit under test — assert it is invoked.
+const clearOfflineCacheMock = vi.fn();
+vi.mock("@/features/offline/clear-offline-cache", () => ({
+  clearOfflineCache: () => clearOfflineCacheMock(),
+}));
+
+// app-route helpers are pure config; provide deterministic values.
+vi.mock("@/lib/app-route.ts", () => ({
+  default: { AUTH: { LOGIN: "/login" }, HOME: "/home" },
+  getPostLoginRedirect: () => "/home",
+}));
+
+// Mantine notifications: avoid touching the DOM-bound notification system.
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: vi.fn() },
+}));
+
+import useAuth from "./use-auth";
+
+beforeEach(() => {
+  navigateMock.mockReset();
+  loginMock.mockReset();
+  loginMock.mockResolvedValue(undefined);
+  logoutMock.mockReset();
+  logoutMock.mockResolvedValue(undefined);
+  clearOfflineCacheMock.mockReset();
+  clearOfflineCacheMock.mockResolvedValue(undefined);
+});
+
+describe("useAuth.handleSignIn", () => {
+  it("clears the offline cache BEFORE logging in (cross-user leak guard)", async () => {
+    const order: string[] = [];
+    clearOfflineCacheMock.mockImplementation(async () => {
+      order.push("clear");
+    });
+    loginMock.mockImplementation(async () => {
+      order.push("login");
+    });
+
+    const { result } = renderHook(() => useAuth());
+    await act(async () => {
+      await result.current.signIn({ email: "b@x", password: "pw" } as any);
+    });
+
+    expect(clearOfflineCacheMock).toHaveBeenCalledTimes(1);
+    expect(loginMock).toHaveBeenCalledTimes(1);
+    // The purge must run before the new session's login resolves.
+    expect(order).toEqual(["clear", "login"]);
+    expect(navigateMock).toHaveBeenCalledWith("/home");
+  });
+
+  it("does not block sign-in when the cache purge throws (best-effort)", async () => {
+    clearOfflineCacheMock.mockRejectedValue(new Error("idb unavailable"));
+
+    const { result } = renderHook(() => useAuth());
+    await act(async () => {
+      await result.current.signIn({ email: "b@x", password: "pw" } as any);
+    });
+
+    // Login still proceeds despite the cleanup failure.
+    expect(loginMock).toHaveBeenCalledTimes(1);
+    expect(navigateMock).toHaveBeenCalledWith("/home");
+  });
+});
+
+describe("useAuth.handleLogout", () => {
+  const replaceMock = vi.fn();
+  let originalLocation: Location;
+
+  beforeEach(() => {
+    replaceMock.mockReset();
+    // window.location.replace is the post-logout redirect. jsdom's real `replace`
+    // is a non-configurable method that warns "not implemented", so swap the
+    // whole location object for one whose `replace` we can capture.
+    originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      writable: true,
+      value: { replace: replaceMock },
+    });
+  });
+
+  afterEach(() => {
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      writable: true,
+      value: originalLocation,
+    });
+  });
+
+  it("purges the offline cache exactly once BEFORE redirecting (cross-user leak guard)", async () => {
+    const order: string[] = [];
+    clearOfflineCacheMock.mockImplementation(async () => {
+      order.push("clear");
+    });
+    replaceMock.mockImplementation((url: string) => {
+      order.push(`replace:${url}`);
+    });
+
+    const { result } = renderHook(() => useAuth());
+    await act(async () => {
+      await result.current.logout();
+    });
+
+    expect(clearOfflineCacheMock).toHaveBeenCalledTimes(1);
+    // Purge must complete before the redirect (which would otherwise interrupt
+    // the async cleanup).
+    expect(order).toEqual(["clear", "replace:/login?logout=1"]);
+  });
+
+  it("still redirects when the cache purge throws (best-effort, never blocks logout)", async () => {
+    clearOfflineCacheMock.mockRejectedValue(new Error("idb unavailable"));
+
+    const { result } = renderHook(() => useAuth());
+    await act(async () => {
+      await result.current.logout();
+    });
+
+    // The thrown purge error is swallowed and the redirect still fires.
+    expect(clearOfflineCacheMock).toHaveBeenCalledTimes(1);
+    expect(replaceMock).toHaveBeenCalledTimes(1);
+    expect(replaceMock).toHaveBeenCalledWith("/login?logout=1");
+  });
+});

apps/client/src/features/auth/hooks/use-auth.ts

@@ -23,6 +23,7 @@ import { acceptInvitation } from "@/features/workspace/services/workspace-servic
 import APP_ROUTE, { getPostLoginRedirect } from "@/lib/app-route.ts";
 import { RESET } from "jotai/utils";
 import { useTranslation } from "react-i18next";
+import { clearOfflineCache } from "@/features/offline/clear-offline-cache";
 
 export default function useAuth() {
   const { t } = useTranslation();
@@ -33,6 +34,20 @@ export default function useAuth() {
   const handleSignIn = async (data: ILogin) => {
     setIsLoading(true);
 
+    // Purge any previous user's offline data BEFORE signing in (mirrors logout).
+    // On a shared/kiosk device the prior session may have ended WITHOUT an
+    // explicit logout (cookie/JWT expiry, tab close, force-quit), leaving user
+    // A's persisted query cache (gitmost-rq-cache) and Yjs page bodies
+    // (page.<id>) in IndexedDB. Without this purge user B would briefly read A's
+    // cached currentUser/pages/comments on first render (UserProvider serves the
+    // cached user) and A's page bodies would stay readable offline. Best-effort:
+    // never block sign-in on cache cleanup.
+    try {
+      await clearOfflineCache();
+    } catch {
+      // best-effort: never block sign-in on cache cleanup
+    }
+
     try {
       await login(data);
       setIsLoading(false);
@@ -123,6 +138,13 @@ export default function useAuth() {
   const handleLogout = async () => {
     setCurrentUser(RESET);
     await logout();
+    // Purge the previous user's offline data while the page is still alive —
+    // window.location.replace below would otherwise interrupt async cleanup.
+    try {
+      await clearOfflineCache();
+    } catch {
+      // best-effort: never block logout on cache cleanup
+    }
     window.location.replace(`${APP_ROUTE.AUTH.LOGIN}?logout=1`);
   };
 

apps/client/src/features/auth/queries/auth-query.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { AxiosError } from "axios";
+import { collabTokenRetry } from "./auth-query";
+
+// Regression for the offline white-screen (#237/#238): offline the collab-token
+// POST rejects as an axios NETWORK error (isAxiosError === true but
+// error.response === undefined). The old predicate read `error.response.status`
+// without a guard and threw an uncaught TypeError inside the React Query retryer
+// BEFORE React mounted, blanking the whole app. The predicate must stay total.
+describe("collabTokenRetry", () => {
+  it("does NOT throw and returns a retryable value for a network error with no response (offline)", () => {
+    // An axios error with no `response` is exactly the offline/network-failure shape.
+    const networkError = new AxiosError("Network Error");
+    expect(networkError.response).toBeUndefined();
+
+    let result: boolean | number = false;
+    expect(() => {
+      result = collabTokenRetry(0, networkError);
+    }).not.toThrow();
+    // Network failures stay retryable (truthy), matching the original intent.
+    expect(result).toBe(true);
+  });
+
+  it("returns false (no retry) for a real 404 response", () => {
+    const notFound = new AxiosError("Not Found");
+    notFound.response = { status: 404 } as AxiosError["response"];
+    expect(collabTokenRetry(0, notFound)).toBe(false);
+  });
+
+  it("retries for a non-404 response (e.g. 500)", () => {
+    const serverError = new AxiosError("Server Error");
+    serverError.response = { status: 500 } as AxiosError["response"];
+    expect(collabTokenRetry(0, serverError)).toBe(true);
+  });
+
+  it("does not throw and retries for a non-axios error", () => {
+    let result: boolean | number = false;
+    expect(() => {
+      result = collabTokenRetry(0, new Error("boom"));
+    }).not.toThrow();
+    expect(result).toBe(true);
+  });
+});

apps/client/src/features/auth/queries/auth-query.tsx

@@ -3,6 +3,27 @@ import { getCollabToken, verifyUserToken } from "../services/auth-service";
 import { ICollabToken, IVerifyUserToken } from "../types/auth.types";
 import { isAxiosError } from "axios";
 
+/**
+ * Retry predicate for the collab-token query.
+ *
+ * Offline (or any network failure) the POST rejects as an axios NETWORK error:
+ * `isAxiosError(error) === true` but `error.response === undefined`. Reading
+ * `error.response.status` without a guard threw an uncaught TypeError inside the
+ * React Query retryer BEFORE React mounted, white-screening the whole app on an
+ * offline cold boot (#237/#238). Optional-chaining `error.response?.status`
+ * keeps the predicate total: a network error (no response) is retryable, a real
+ * 404 is not. Extracted (and exported) so it can be unit-tested in isolation.
+ */
+export function collabTokenRetry(
+  _failureCount: number,
+  error: Error,
+): boolean {
+  if (isAxiosError(error) && error.response?.status === 404) {
+    return false;
+  }
+  return true;
+}
+
 export function useVerifyUserTokenQuery(
   verify: IVerifyUserToken,
 ): UseQueryResult<any, Error> {
@@ -22,13 +43,7 @@ export function useCollabToken(): UseQueryResult<ICollabToken, Error> {
     //refetchInterval: 12 * 60 * 60 * 1000, // 12hrs
     //refetchIntervalInBackground: true,
     refetchOnMount: true,
-    //@ts-ignore
-    retry: (failureCount, error) => {
-      if (isAxiosError(error) && error.response.status === 404) {
-        return false;
-      }
-      return 10;
-    },
+    retry: collabTokenRetry,
     retryDelay: (retryAttempt) => {
       // Exponential backoff: 5s, 10s, 20s, etc.
       return 5000 * Math.pow(2, retryAttempt - 1);

apps/client/src/features/comment/queries/comment-query.ts

@@ -20,6 +20,7 @@ import { notifications } from "@mantine/notifications";
 import { IPagination } from "@/lib/types.ts";
 import { useTranslation } from "react-i18next";
 import { useEffect, useMemo } from "react";
+import { offlineMutationKeys } from "@/features/offline/offline-mutations";
 
 export const RQ_KEY = (pageId: string) => ["comments", pageId];
 
@@ -60,6 +61,9 @@ export function useCreateCommentMutation() {
   const { t } = useTranslation();
 
   return useMutation<IComment, Error, Partial<IComment>>({
+    // Stable key so a paused comment-create restored from IndexedDB after an
+    // offline reload finds its default mutationFn and is replayed on reconnect.
+    mutationKey: offlineMutationKeys.createComment,
     mutationFn: (data) => createComment(data),
     onSuccess: (newComment) => {
       const cache = queryClient.getQueryData(

apps/client/src/features/editor/atoms/editor-atoms.ts

@@ -10,6 +10,12 @@ export const readOnlyEditorAtom = atom<Editor | null>(null);
 
 export const yjsConnectionStatusAtom = atom<string>("");
 
+// Local (IndexedDB) persistence sync state for the current page's Y.Doc.
+export const isLocalSyncedAtom = atom<boolean>(false);
+
+// Remote (Hocuspocus) sync state for the current page's Y.Doc.
+export const isRemoteSyncedAtom = atom<boolean>(false);
+
 export const showLinkMenuAtom = atom(false);
 
 // Current page's edit mode — initialized from the user's saved preference on

apps/client/src/features/editor/contexts/editor-providers-context.tsx

@@ -0,0 +1,21 @@
+import { createContext, useContext } from "react";
+import type { HocuspocusProvider } from "@hocuspocus/provider";
+import type * as Y from "yjs";
+
+// Shared collaboration providers lifted above the title/body editors so that
+// both siblings bind to the SAME Y.Doc and HocuspocusProvider. The title lives
+// in a dedicated 'title' fragment of the same doc as the body.
+export interface EditorProvidersContextValue {
+  ydoc: Y.Doc;
+  remote: HocuspocusProvider;
+  providersReady: boolean;
+}
+
+export const EditorProvidersContext =
+  createContext<EditorProvidersContextValue | null>(null);
+
+// Returns the shared providers, or null when rendered outside of a provider.
+// Consumers must be null-safe (the body editor falls back to a non-collab mode).
+export function useEditorProviders(): EditorProvidersContextValue | null {
+  return useContext(EditorProvidersContext);
+}

apps/client/src/features/editor/full-editor.tsx

@@ -34,6 +34,8 @@ import {
 } from "@/features/editor/atoms/editor-atoms.ts";
 import { DictationGroup } from "@/features/editor/components/fixed-toolbar/groups/dictation-group";
 import { GenerateTitleGroup } from "@/features/editor/components/fixed-toolbar/groups/generate-title-group";
+import { usePageCollabProviders } from "@/features/editor/hooks/use-page-collab-providers";
+import { EditorProvidersContext } from "@/features/editor/contexts/editor-providers-context";
 
 const MemoizedTitleEditor = React.memo(TitleEditor);
 const MemoizedPageEditor = React.memo(PageEditor);
@@ -90,6 +92,10 @@ export function FullEditor({
     user.settings?.preferences?.pageEditMode ?? PageEditMode.Edit;
   const isEditMode = currentPageEditMode === PageEditMode.Edit;
 
+  // Single shared Y.Doc + HocuspocusProvider for both the title and body
+  // editors (title lives in the 'title' fragment of the same doc).
+  const { ydoc, remote, providersReady } = usePageCollabProviders(pageId);
+
   // Apply the user's saved preference only once on initial load, not on every
   // page navigation — so the mode sticks across navigations within a session.
   useEffect(() => {
@@ -110,28 +116,32 @@ export function FullEditor({
       )}
       <MemoizedDeletedPageBanner slugId={slugId} />
       <MemoizedTemporaryNoteBanner slugId={slugId} />
-      <MemoizedTitleEditor
-        pageId={pageId}
-        slugId={slugId}
-        title={title}
-        spaceSlug={spaceSlug}
-        editable={editable}
-      />
-      <PageByline
-        pageId={pageId}
-        creator={creator}
-        contributors={contributors}
-        editable={editable}
-        isEditMode={isEditMode}
-        isDictationEnabled={isDictationEnabled}
-        isTitleGenEnabled={isTitleGenEnabled}
-      />
-      <MemoizedPageEditor
-        pageId={pageId}
-        editable={editable}
-        content={content}
-        canComment={canComment}
-      />
+      <EditorProvidersContext.Provider
+        value={ydoc && remote ? { ydoc, remote, providersReady } : null}
+      >
+        <MemoizedTitleEditor
+          pageId={pageId}
+          slugId={slugId}
+          title={title}
+          spaceSlug={spaceSlug}
+          editable={editable}
+        />
+        <PageByline
+          pageId={pageId}
+          creator={creator}
+          contributors={contributors}
+          editable={editable}
+          isEditMode={isEditMode}
+          isDictationEnabled={isDictationEnabled}
+          isTitleGenEnabled={isTitleGenEnabled}
+        />
+        <MemoizedPageEditor
+          pageId={pageId}
+          editable={editable}
+          content={content}
+          canComment={canComment}
+        />
+      </EditorProvidersContext.Provider>
     </Container>
   );
 }

apps/client/src/features/editor/hooks/collab-token.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// jwt-decode is mocked so we can drive the four token states deterministically
+// (decode success with a chosen exp, or a thrown decode error).
+const decodeMock = vi.hoisted(() => vi.fn());
+vi.mock("jwt-decode", () => ({
+  jwtDecode: decodeMock,
+}));
+
+import { collabTokenNeedsRefresh } from "./collab-token";
+
+const NOW_MS = 1_000_000_000; // fixed "now" in ms (so NOW_MS/1000 seconds)
+
+beforeEach(() => {
+  decodeMock.mockReset();
+});
+
+describe("collabTokenNeedsRefresh", () => {
+  it("returns true when there is no token (fetch a fresh one)", () => {
+    expect(collabTokenNeedsRefresh(undefined, NOW_MS)).toBe(true);
+    // jwtDecode must not even be called for a missing token.
+    expect(decodeMock).not.toHaveBeenCalled();
+  });
+
+  it("returns true when the token is malformed (jwtDecode throws)", () => {
+    decodeMock.mockImplementation(() => {
+      throw new Error("invalid token");
+    });
+    expect(collabTokenNeedsRefresh("garbage", NOW_MS)).toBe(true);
+  });
+
+  it("returns false for a valid, not-yet-expired token (no reconnect)", () => {
+    // exp is in the future relative to NOW.
+    decodeMock.mockReturnValue({ exp: NOW_MS / 1000 + 60 });
+    expect(collabTokenNeedsRefresh("good", NOW_MS)).toBe(false);
+  });
+
+  it("returns true for a valid but expired token (refresh + reconnect)", () => {
+    // exp is in the past relative to NOW.
+    decodeMock.mockReturnValue({ exp: NOW_MS / 1000 - 60 });
+    expect(collabTokenNeedsRefresh("expired", NOW_MS)).toBe(true);
+  });
+
+  it("treats exp exactly equal to now as expired (>= boundary)", () => {
+    decodeMock.mockReturnValue({ exp: NOW_MS / 1000 });
+    expect(collabTokenNeedsRefresh("boundary", NOW_MS)).toBe(true);
+  });
+});

apps/client/src/features/editor/hooks/collab-token.ts

@@ -0,0 +1,26 @@
+import { jwtDecode } from "jwt-decode";
+
+/**
+ * Decide whether a collab token must be refreshed before reconnecting after an
+ * onAuthenticationFailed event. Pure and side-effect free so the four token
+ * states can be unit-tested directly:
+ *   - no token              -> true  (fetch a fresh one and reconnect)
+ *   - undecodable/malformed -> true  (jwtDecode throws -> refresh)
+ *   - valid, not expired    -> false (token is still good; do NOT reconnect)
+ *   - valid, expired        -> true  (refresh + reconnect)
+ *
+ * `nowMs` is injectable for deterministic tests; it defaults to `Date.now()`.
+ */
+export function collabTokenNeedsRefresh(
+  token: string | undefined,
+  nowMs: number = Date.now(),
+): boolean {
+  if (!token) return true;
+  try {
+    const payload = jwtDecode<{ exp: number }>(token);
+    return nowMs / 1000 >= payload.exp;
+  } catch {
+    // malformed/undecodable token -> refresh
+    return true;
+  }
+}

apps/client/src/features/editor/hooks/use-generate-page-title.test.tsx

@@ -139,7 +139,7 @@ describe("useGeneratePageTitle", () => {
     );
   });
 
-  it("happy path: applies the title, refreshes cache, writes the field, broadcasts", async () => {
+  it("happy path: applies the title, refreshes cache, broadcasts, and does NOT write the editor", async () => {
     const store = createStore();
     const titleEditor = makeTitleEditor();
     store.set(pageEditorAtom as never, makePageEditor("pageA"));
@@ -157,9 +157,11 @@ describe("useGeneratePageTitle", () => {
       title: "Generated Title",
     });
     expect(updatePageDataMock).toHaveBeenCalledWith(PAGE_A);
-    expect(titleEditor.commands.setContent).toHaveBeenCalledWith(
-      "Generated Title",
-    );
+    // The title editor is bound to the Yjs `title` fragment; the server REST
+    // update reseeds that fragment and the reseed reaches the bound editor on
+    // its own. Writing here too would double/garble the title, so the hook must
+    // NOT touch the editor (regression guard for the Yjs duplication trap).
+    expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
     expect(localEmitMock).toHaveBeenCalled();
     expect(emitMock).toHaveBeenCalled();
     expect(notificationsShowMock).toHaveBeenCalledWith(
@@ -167,7 +169,7 @@ describe("useGeneratePageTitle", () => {
     );
   });
 
-  it("does NOT write the visible title field when the user navigated away during generation", async () => {
+  it("keeps the DB write keyed by the captured pageId and still broadcasts after navigation", async () => {
     const store = createStore();
     const titleEditor = makeTitleEditor(); // persistent across navigation
     store.set(pageEditorAtom as never, makePageEditor("pageA"));
@@ -203,55 +205,9 @@ describe("useGeneratePageTitle", () => {
       pageId: "pageA",
       title: "Generated Title",
     });
-    // ...but we must NOT stamp page A's title into page B's visible field.
+    // ...the hook never writes the editor regardless of navigation...
     expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
-    // The change is still broadcast to other clients.
-    expect(emitMock).toHaveBeenCalled();
-  });
-
-  it("does NOT write the visible title field when the title editor is focused", async () => {
-    const store = createStore();
-    const titleEditor = makeTitleEditor();
-    store.set(pageEditorAtom as never, makePageEditor("pageA"));
-    store.set(titleEditorAtom as never, titleEditor);
-
-    // Resolve generation under our control so we can mark the live title editor
-    // as focused before the post-generation write runs.
-    let resolveTitle!: (t: string) => void;
-    generatePageTitleMock.mockReturnValue(
-      new Promise<string>((res) => {
-        resolveTitle = res;
-      }),
-    );
-    updateTitleMock.mockResolvedValue(PAGE_A);
-    const { result } = setup("pageA", store);
-
-    let pending!: Promise<void>;
-    act(() => {
-      pending = result.current.mutateAsync();
-    });
-
-    // The user clicked into the title field while the model ran — overwriting it
-    // now would clobber what they are actively typing.
-    act(() => {
-      (titleEditor as { isFocused: boolean }).isFocused = true;
-    });
-
-    await act(async () => {
-      resolveTitle("Generated Title");
-      await pending;
-    });
-
-    // The DB write still persists the value...
-    expect(updateTitleMock).toHaveBeenCalledWith({
-      pageId: "pageA",
-      title: "Generated Title",
-    });
-    expect(updatePageDataMock).toHaveBeenCalledWith(PAGE_A);
-    // ...but the visible field is left alone while it is focused.
-    expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
-    // The change is still broadcast to other clients.
-    expect(localEmitMock).toHaveBeenCalled();
+    // ...and the change is still broadcast to other clients.
     expect(emitMock).toHaveBeenCalled();
   });
 

apps/client/src/features/editor/hooks/use-generate-page-title.ts

@@ -1,13 +1,9 @@
-import { useRef } from "react";
 import { useMutation } from "@tanstack/react-query";
 import { useAtomValue } from "jotai";
 import { notifications } from "@mantine/notifications";
 import { useTranslation } from "react-i18next";
 import { htmlToMarkdown } from "@docmost/editor-ext";
-import {
-  pageEditorAtom,
-  titleEditorAtom,
-} from "@/features/editor/atoms/editor-atoms.ts";
+import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
 import {
   updatePageData,
   useUpdateTitlePageMutation,
@@ -33,18 +29,9 @@ const MAX_CONTENT_CHARS = 20000;
 export function useGeneratePageTitle(pageId: string) {
   const { t } = useTranslation();
   const pageEditor = useAtomValue(pageEditorAtom);
-  const titleEditor = useAtomValue(titleEditorAtom);
   const { mutateAsync: updateTitle } = useUpdateTitlePageMutation();
   const emit = useQueryEmit();
 
-  // The page/title editors come from GLOBAL atoms that re-point when the user
-  // navigates to another page. The mutation below awaits the model for 1-3s, and
-  // its closure captures the editors from the render that started it. Keep a live
-  // reference so the post-generation write targets whatever page is on screen
-  // *now*, not the page the generation was started from.
-  const editorsRef = useRef({ pageEditor, titleEditor });
-  editorsRef.current = { pageEditor, titleEditor };
-
   return useMutation<void, Error, void>({
     mutationFn: async () => {
       if (!pageEditor || pageEditor.isDestroyed) return;
@@ -70,33 +57,15 @@ export function useGeneratePageTitle(pageId: string) {
       const page = await updateTitle({ pageId, title }); // POST /pages/update
       updatePageData(page); // refresh the react-query cache
 
-      // Reflect the new title in the field immediately. The button lives in the
-      // byline, so the title editor is not focused — setContent is safe and stays
-      // undoable through its History extension (Ctrl/Cmd+Z reverts the change).
-      //
-      // Guard against navigation during generation: if the user switched pages
-      // while the model ran, the (persistent) title editor now shows ANOTHER
-      // page, so writing here would drop page A's title into page B's visible
-      // field. page-editor.tsx stamps the live page editor with its pageId
-      // (`editor.storage.pageId`), mirroring TitleEditor's `activePageId !==
-      // pageId` guard — bail the visible write unless that live editor still
-      // belongs to the page this title was generated for. The DB write above is
-      // already correct (keyed by the captured `pageId`), and the broadcast below
-      // still propagates page A's change to other clients.
-      const livePageEditor = editorsRef.current.pageEditor;
-      const liveTitleEditor = editorsRef.current.titleEditor;
-      // `storage.pageId` is stamped untyped in page-editor.tsx's onCreate.
-      const livePageId = (livePageEditor?.storage as { pageId?: string })
-        ?.pageId;
-      const stillOnPage = livePageId === pageId;
-      if (
-        stillOnPage &&
-        liveTitleEditor &&
-        !liveTitleEditor.isDestroyed &&
-        !liveTitleEditor.isFocused
-      ) {
-        liveTitleEditor.commands.setContent(page.title);
-      }
+      // Do NOT write the title into the editor here. The title editor is bound to
+      // the Yjs `title` fragment and Yjs is the source of truth. The server REST
+      // /pages/update reseeds that fragment (writePageTitle → writeTitleFragment,
+      // a full clear+replace) and the reseed reaches the bound title editor on
+      // its own as a remote provider update. The old REST-era setContent here
+      // would race that reseed and double/garble the title (the "Yjs duplication
+      // trap"), so it is intentionally omitted. The DB write above is keyed by
+      // the captured `pageId`, so it stays correct even if the user navigated
+      // away during generation.
 
       // Broadcast to other clients, mirroring TitleEditor.saveTitle's event shape.
       const event: UpdateEvent = {

apps/client/src/features/editor/hooks/use-page-collab-providers.ts

@@ -0,0 +1,189 @@
+import { useEffect, useRef, useState } from "react";
+import { IndexeddbPersistence } from "y-indexeddb";
+import * as Y from "yjs";
+import {
+  HocuspocusProvider,
+  onStatusParameters,
+  WebSocketStatus,
+  HocuspocusProviderWebsocket,
+  onSyncedParameters,
+  onStatelessParameters,
+} from "@hocuspocus/provider";
+import { useAtom, useSetAtom } from "jotai";
+import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
+import {
+  isLocalSyncedAtom,
+  isRemoteSyncedAtom,
+  yjsConnectionStatusAtom,
+} from "@/features/editor/atoms/editor-atoms";
+import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
+import { useDocumentVisibility } from "@mantine/hooks";
+import { useIdle } from "@/hooks/use-idle.ts";
+import { queryClient } from "@/main.tsx";
+import { IPage } from "@/features/page/types/page.types.ts";
+import { useParams } from "react-router-dom";
+import { extractPageSlugId } from "@/lib";
+import { FIVE_MINUTES } from "@/lib/constants.ts";
+import { collabTokenNeedsRefresh } from "@/features/editor/hooks/collab-token";
+import { pageYdocName } from "@/features/editor/page-ydoc-name";
+import { pageKeys } from "@/features/page/queries/page-query";
+
+export interface PageCollabProviders {
+  ydoc: Y.Doc | null;
+  remote: HocuspocusProvider | null;
+  socket: HocuspocusProviderWebsocket | null;
+  providersReady: boolean;
+}
+
+/**
+ * Owns the full collaboration provider lifecycle for a page so that the title
+ * and body editors can share a single Y.Doc + HocuspocusProvider. The behavior
+ * is relocated verbatim from page-editor.tsx: it creates the providers once per
+ * pageId, connects/disconnects on idle/visibility, attaches each render,
+ * destroys on unmount, refreshes the collab token on auth failure, and applies
+ * the onStateless 'page.updated' cache update.
+ */
+export function usePageCollabProviders(pageId: string): PageCollabProviders {
+  const collaborationURL = useCollaborationUrl();
+  const [yjsConnectionStatus, setYjsConnectionStatus] = useAtom(
+    yjsConnectionStatusAtom,
+  );
+  const setIsLocalSyncedAtom = useSetAtom(isLocalSyncedAtom);
+  const setIsRemoteSyncedAtom = useSetAtom(isRemoteSyncedAtom);
+  const { data: collabQuery, refetch: refetchCollabToken } = useCollabToken();
+  // The provider-creating effect runs only once per pageId, so any token read
+  // inside its handlers would be captured STALE (the old token at first render).
+  // Mirror the latest token into a ref the auth-failure handler can read live.
+  const collabTokenRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    collabTokenRef.current = collabQuery?.token;
+  }, [collabQuery?.token]);
+  const { isIdle, resetIdle } = useIdle(FIVE_MINUTES, { initialState: false });
+  const documentState = useDocumentVisibility();
+  const { pageSlug } = useParams();
+  const slugId = extractPageSlugId(pageSlug);
+
+  // Providers only created once per pageId
+  const providersRef = useRef<{
+    ydoc: Y.Doc;
+    local: IndexeddbPersistence;
+    remote: HocuspocusProvider;
+    socket: HocuspocusProviderWebsocket;
+  } | null>(null);
+  const [providersReady, setProvidersReady] = useState(false);
+
+  useEffect(() => {
+    if (!providersRef.current) {
+      const documentName = pageYdocName(pageId);
+      const ydoc = new Y.Doc();
+      const local = new IndexeddbPersistence(documentName, ydoc);
+      const socket = new HocuspocusProviderWebsocket({
+        url: collaborationURL,
+      });
+      const onLocalSyncedHandler = () => {
+        setIsLocalSyncedAtom(true);
+      };
+      const onStatusHandler = (event: onStatusParameters) => {
+        setYjsConnectionStatus(event.status);
+      };
+      const onSyncedHandler = (event: onSyncedParameters) => {
+        setIsRemoteSyncedAtom(event.state);
+      };
+      const onStatelessHandler = ({ payload }: onStatelessParameters) => {
+        try {
+          const message = JSON.parse(payload);
+          if (message?.type !== "page.updated" || !message.updatedAt) return;
+          const pageData = queryClient.getQueryData<IPage>(
+            pageKeys.detail(slugId),
+          );
+          if (pageData) {
+            queryClient.setQueryData(pageKeys.detail(slugId), {
+              ...pageData,
+              updatedAt: message.updatedAt,
+              ...(message.lastUpdatedBy && {
+                lastUpdatedBy: message.lastUpdatedBy,
+              }),
+            });
+          }
+        } catch {
+          // ignore unrelated stateless messages
+        }
+      };
+      const onAuthenticationFailedHandler = () => {
+        // Read the token from the ref, not the closed-over `collabQuery`: this
+        // handler is created once and would otherwise decode a stale token after
+        // a refetch. A missing/malformed token must NOT crash the handler —
+        // jwtDecode(undefined) throws — so treat any decode failure as "needs
+        // refresh" and proceed to refetch + reconnect instead of getting stuck.
+        if (!collabTokenNeedsRefresh(collabTokenRef.current)) return;
+        refetchCollabToken().then((result) => {
+          if (result.data?.token) {
+            socket.disconnect();
+            setTimeout(() => {
+              remote.configuration.token = result.data.token;
+              socket.connect();
+            }, 100);
+          }
+        });
+      };
+      const remote = new HocuspocusProvider({
+        websocketProvider: socket,
+        name: documentName,
+        document: ydoc,
+        token: collabQuery?.token,
+        onAuthenticationFailed: onAuthenticationFailedHandler,
+        onStatus: onStatusHandler,
+        onSynced: onSyncedHandler,
+        onStateless: onStatelessHandler,
+      });
+
+      local.on("synced", onLocalSyncedHandler);
+      providersRef.current = { ydoc, socket, local, remote };
+      setProvidersReady(true);
+    } else {
+      setProvidersReady(true);
+    }
+    // Only destroy on final unmount
+    return () => {
+      providersRef.current?.socket.destroy();
+      providersRef.current?.remote.destroy();
+      providersRef.current?.local.destroy();
+      providersRef.current = null;
+      // Reset shared sync state on page change/unmount.
+      setIsLocalSyncedAtom(false);
+      setIsRemoteSyncedAtom(false);
+    };
+  }, [pageId]);
+
+  // Only connect/disconnect on tab/idle, not destroy
+  useEffect(() => {
+    if (!providersReady || !providersRef.current) return;
+    const socket = providersRef.current.socket;
+
+    if (
+      isIdle &&
+      documentState === "hidden" &&
+      yjsConnectionStatus === WebSocketStatus.Connected
+    ) {
+      socket.disconnect();
+      return;
+    }
+    if (
+      documentState === "visible" &&
+      yjsConnectionStatus === WebSocketStatus.Disconnected
+    ) {
+      resetIdle();
+      socket.connect();
+    }
+  }, [isIdle, documentState, providersReady, resetIdle]);
+
+  // Attach here, to make sure the connection gets properly established
+  providersRef.current?.remote.attach();
+
+  return {
+    ydoc: providersRef.current?.ydoc ?? null,
+    remote: providersRef.current?.remote ?? null,
+    socket: providersRef.current?.socket ?? null,
+    providersReady,
+  };
+}

apps/client/src/features/editor/page-editor.tsx

@@ -6,16 +6,7 @@ import React, {
   useRef,
   useState,
 } from "react";
-import { IndexeddbPersistence } from "y-indexeddb";
-import * as Y from "yjs";
-import {
-  HocuspocusProvider,
-  onStatusParameters,
-  WebSocketStatus,
-  HocuspocusProviderWebsocket,
-  onSyncedParameters,
-  onStatelessParameters,
-} from "@hocuspocus/provider";
+import { WebSocketStatus } from "@hocuspocus/provider";
 import {
   Editor,
   EditorContent,
@@ -28,13 +19,15 @@ import {
   mainExtensions,
 } from "@/features/editor/extensions/extensions";
 import { useAtom, useAtomValue } from "jotai";
-import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom";
 import {
   currentPageEditModeAtom,
+  isLocalSyncedAtom,
+  isRemoteSyncedAtom,
   pageEditorAtom,
   yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms";
+import { useEditorProviders } from "@/features/editor/contexts/editor-providers-context";
 import { asideStateAtom } from "@/components/layouts/global/hooks/atoms/sidebar-atom";
 import {
   activeCommentIdAtom,
@@ -58,10 +51,8 @@ import {
 } from "@/features/editor/components/common/editor-paste-handler.tsx";
 import ExcalidrawMenu from "./components/excalidraw/excalidraw-menu-lazy";
 import DrawioMenu from "./components/drawio/drawio-menu";
-import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
 import SearchAndReplaceDialog from "@/features/editor/components/search-and-replace/search-and-replace-dialog.tsx";
-import { useDebouncedCallback, useDocumentVisibility } from "@mantine/hooks";
-import { useIdle } from "@/hooks/use-idle.ts";
+import { useDebouncedCallback } from "@mantine/hooks";
 import { queryClient } from "@/main.tsx";
 import { IPage } from "@/features/page/types/page.types.ts";
 import { useParams } from "react-router-dom";
@@ -72,9 +63,7 @@ import {
   GitmostInsertRecordingResult,
   gitmostInsertRecordingIntoEditor,
 } from "@/features/editor/gitmost/gitmost-recording.ts";
-import { FIVE_MINUTES } from "@/lib/constants.ts";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
-import { jwtDecode } from "jwt-decode";
 import { searchSpotlight } from "@/features/search/constants.ts";
 import { useEditorScroll } from "./hooks/use-editor-scroll";
 import { EditorLinkMenu } from "@/features/editor/components/link/link-menu";
@@ -103,7 +92,6 @@ export default function PageEditor({
   canComment,
 }: PageEditorProps) {
   const { t } = useTranslation();
-  const collaborationURL = useCollaborationUrl();
   const isComponentMounted = useRef(false);
   const editorRef = useRef<Editor | null>(null);
 
@@ -117,22 +105,10 @@ export default function PageEditor({
   const [, setActiveCommentId] = useAtom(activeCommentIdAtom);
   const [showCommentPopup, setShowCommentPopup] = useAtom(showCommentPopupAtom);
   const [showReadOnlyCommentPopup] = useAtom(showReadOnlyCommentPopupAtom);
-  const [isLocalSynced, setIsLocalSynced] = useState(false);
-  const [isRemoteSynced, setIsRemoteSynced] = useState(false);
   const [yjsConnectionStatus, setYjsConnectionStatus] = useAtom(
     yjsConnectionStatusAtom,
   );
   const menuContainerRef = useRef(null);
-  const { data: collabQuery, refetch: refetchCollabToken } = useCollabToken();
-  // Always holds the latest collab token. The provider effect below runs once
-  // per pageId, so a handler created inside it would otherwise close over a
-  // stale `collabQuery`. Reading the ref gives the current token instead.
-  const collabTokenRef = useRef<string | undefined>(undefined);
-  useEffect(() => {
-    collabTokenRef.current = collabQuery?.token;
-  }, [collabQuery?.token]);
-  const { isIdle, resetIdle } = useIdle(FIVE_MINUTES, { initialState: false });
-  const documentState = useDocumentVisibility();
   const { pageSlug } = useParams();
   const slugId = extractPageSlugId(pageSlug);
   const currentPageEditMode = useAtomValue(currentPageEditModeAtom);
@@ -141,141 +117,27 @@ export default function PageEditor({
     [isComponentMounted],
   );
   const { handleScrollTo } = useEditorScroll({ canScroll });
-  // Providers only created once per pageId
-  const providersRef = useRef<{
-    local: IndexeddbPersistence;
-    remote: HocuspocusProvider;
-    socket: HocuspocusProviderWebsocket;
-  } | null>(null);
-  const [providersReady, setProvidersReady] = useState(false);
 
-  useEffect(() => {
-    if (!providersRef.current) {
-      const documentName = `page.${pageId}`;
-      const ydoc = new Y.Doc();
-      const local = new IndexeddbPersistence(documentName, ydoc);
-      const socket = new HocuspocusProviderWebsocket({
-        url: collaborationURL,
-      });
-      const onLocalSyncedHandler = () => {
-        setIsLocalSynced(true);
-      };
-      const onStatusHandler = (event: onStatusParameters) => {
-        setYjsConnectionStatus(event.status);
-      };
-      const onSyncedHandler = (event: onSyncedParameters) => {
-        setIsRemoteSynced(event.state);
-      };
-      const onStatelessHandler = ({ payload }: onStatelessParameters) => {
-        try {
-          const message = JSON.parse(payload);
-          if (message?.type !== "page.updated" || !message.updatedAt) return;
-          const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
-          if (pageData) {
-            queryClient.setQueryData(["pages", slugId], {
-              ...pageData,
-              updatedAt: message.updatedAt,
-              ...(message.lastUpdatedBy && {
-                lastUpdatedBy: message.lastUpdatedBy,
-              }),
-            });
-          }
-        } catch {
-          // ignore unrelated stateless messages
-        }
-      };
-      const onAuthenticationFailedHandler = () => {
-        // Read the latest token via the ref (the closure-captured `collabQuery`
-        // may be stale). Guard the decode: a missing or unparseable token must
-        // not throw "Invalid token specified" and should trigger a refresh so
-        // the editor reconnects even when the initial token fetch failed.
-        const token = collabTokenRef.current;
-        let needsRefresh = true; // no/unparseable token -> fetch a fresh one and reconnect
-        if (token) {
-          try {
-            // A token that decodes but lacks a numeric `exp` must be treated as
-            // expired (`Date.now()/1000 >= undefined` is `false`, which would
-            // otherwise skip the reconnect), so refresh on any missing/non-number exp.
-            const exp = jwtDecode<{ exp?: number }>(token).exp;
-            needsRefresh = typeof exp !== "number" || Date.now() / 1000 >= exp;
-          } catch {
-            needsRefresh = true;
-          }
-        }
-        if (!needsRefresh) return;
-        refetchCollabToken().then((result) => {
-          if (result.data?.token) {
-            socket.disconnect();
-            setTimeout(() => {
-              remote.configuration.token = result.data.token;
-              socket.connect();
-            }, 100);
-          }
-        });
-      };
-      const remote = new HocuspocusProvider({
-        websocketProvider: socket,
-        name: documentName,
-        document: ydoc,
-        token: collabQuery?.token,
-        onAuthenticationFailed: onAuthenticationFailedHandler,
-        onStatus: onStatusHandler,
-        onSynced: onSyncedHandler,
-        onStateless: onStatelessHandler,
-      });
-
-      local.on("synced", onLocalSyncedHandler);
-      providersRef.current = { socket, local, remote };
-      setProvidersReady(true);
-    } else {
-      setProvidersReady(true);
-    }
-    // Only destroy on final unmount
-    return () => {
-      providersRef.current?.socket.destroy();
-      providersRef.current?.remote.destroy();
-      providersRef.current?.local.destroy();
-      providersRef.current = null;
-    };
-  }, [pageId]);
-
-  // Only connect/disconnect on tab/idle, not destroy
-  useEffect(() => {
-    if (!providersReady || !providersRef.current) return;
-    const socket = providersRef.current.socket;
-
-    if (
-      isIdle &&
-      documentState === "hidden" &&
-      yjsConnectionStatus === WebSocketStatus.Connected
-    ) {
-      socket.disconnect();
-      return;
-    }
-    if (
-      documentState === "visible" &&
-      yjsConnectionStatus === WebSocketStatus.Disconnected
-    ) {
-      resetIdle();
-      socket.connect();
-    }
-  }, [isIdle, documentState, providersReady, resetIdle]);
-
-  // Attach here, to make sure the connection gets properly established
-  providersRef.current?.remote.attach();
+  // Shared providers + Y.Doc lifted into full-editor via context. The provider
+  // lifecycle (creation, idle/visibility connect, attach, destroy, token
+  // refresh) lives in usePageCollabProviders. Null-safe when rendered without
+  // the context (defensive) — in practice full-editor always provides it.
+  const editorProviders = useEditorProviders();
+  const remote = editorProviders?.remote ?? null;
+  const providersReady = editorProviders?.providersReady ?? false;
+  const isLocalSynced = useAtomValue(isLocalSyncedAtom);
+  const isRemoteSynced = useAtomValue(isRemoteSyncedAtom);
 
   const extensions = useMemo(() => {
-    if (!providersReady || !providersRef.current || !currentUser?.user) {
+    if (!providersReady || !remote || !currentUser?.user) {
       return mainExtensions;
     }
 
-    const remoteProvider = providersRef.current.remote;
-
     return [
       ...mainExtensions,
-      ...collabExtensions(remoteProvider, currentUser?.user),
+      ...collabExtensions(remote, currentUser?.user),
     ];
-  }, [providersReady, currentUser?.user]);
+  }, [providersReady, remote, currentUser?.user]);
 
   const editor = useEditor(
     {
@@ -550,7 +412,7 @@ export default function PageEditor({
             {editor &&
               !editorIsEditable &&
               (editable || canComment) &&
-              providersRef.current && <ReadonlyBubbleMenu editor={editor} />}
+              remote && <ReadonlyBubbleMenu editor={editor} />}
             {showCommentPopup && (
               <CommentDialog editor={editor} pageId={pageId} />
             )}

apps/client/src/features/editor/page-ydoc-name.ts

@@ -0,0 +1,14 @@
+/**
+ * Single source of truth for the IndexedDB / Hocuspocus document name of a
+ * page's collaborative Yjs doc.
+ *
+ * The `page.<id>` convention is shared knowledge across three call sites: the
+ * live editor providers (`use-page-collab-providers`), the offline warm path
+ * (`make-offline`), and the offline purge (`clear-offline-cache`, which matches
+ * the databases to delete by this prefix). Centralizing it here stops those
+ * sites from silently drifting apart.
+ */
+export const PAGE_YDOC_NAME_PREFIX = "page.";
+
+export const pageYdocName = (pageId: string): string =>
+  `${PAGE_YDOC_NAME_PREFIX}${pageId}`;

apps/client/src/features/editor/title-collab.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// isChangeOrigin is mocked so we can simulate local vs remote/collab-origin
+// transactions without constructing a real ProseMirror/Yjs transaction.
+const isChangeOriginMock = vi.hoisted(() => vi.fn());
+vi.mock("@tiptap/extension-collaboration", () => ({
+  isChangeOrigin: isChangeOriginMock,
+}));
+
+import { shouldPropagateTitleChange } from "./title-collab";
+
+beforeEach(() => {
+  isChangeOriginMock.mockReset();
+});
+
+describe("shouldPropagateTitleChange", () => {
+  it("propagates a genuine local edit (isChangeOrigin false)", () => {
+    isChangeOriginMock.mockReturnValue(false);
+    expect(shouldPropagateTitleChange({ local: true })).toBe(true);
+    expect(isChangeOriginMock).toHaveBeenCalledWith({ local: true });
+  });
+
+  it("skips a remote/collab-origin update (isChangeOrigin true)", () => {
+    isChangeOriginMock.mockReturnValue(true);
+    expect(shouldPropagateTitleChange({ remote: true })).toBe(false);
+  });
+
+  it("propagates when there is no transaction (treated as local)", () => {
+    expect(shouldPropagateTitleChange(undefined)).toBe(true);
+    // isChangeOrigin must not be called for a missing transaction.
+    expect(isChangeOriginMock).not.toHaveBeenCalled();
+  });
+});

apps/client/src/features/editor/title-collab.ts

@@ -0,0 +1,19 @@
+import { isChangeOrigin } from "@tiptap/extension-collaboration";
+
+/**
+ * Whether a TitleEditor `onUpdate` should drive URL + tree propagation.
+ *
+ * Only genuine LOCAL edits propagate. Remote/collab-origin Yjs updates
+ * (detected via `isChangeOrigin`) are skipped so a remote title change is not
+ * re-broadcast back, which would create a feedback loop. A missing transaction
+ * is treated as a local edit (propagate).
+ *
+ * Extracted as a pure helper so the skip decision is unit-testable without
+ * mounting the full collaborative editor.
+ */
+export function shouldPropagateTitleChange(transaction: unknown): boolean {
+  return !(
+    transaction &&
+    isChangeOrigin(transaction as Parameters<typeof isChangeOrigin>[0])
+  );
+}

apps/client/src/features/editor/title-editor.test.tsx

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+
+// Drive the fallback-vs-collaborative switch (titleReady = providersReady &&
+// !!ydoc) by controlling what the editor-providers context returns.
+const editorProvidersValue: { ydoc: unknown; providersReady: boolean } = {
+  ydoc: null,
+  providersReady: false,
+};
+vi.mock("@/features/editor/contexts/editor-providers-context", () => ({
+  useEditorProviders: () => editorProvidersValue,
+}));
+
+// Mock the tiptap React bindings so the test does not mount a real editor:
+// useEditor returns a minimal stub and EditorContent renders a marker.
+vi.mock("@tiptap/react", () => ({
+  useEditor: () => ({
+    isInitialized: true,
+    commands: { focus: vi.fn() },
+    setEditable: vi.fn(),
+    getText: () => "",
+  }),
+  EditorContent: () => <div data-testid="collab-editor" />,
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (k: string) => k }),
+}));
+
+const navigateMock = vi.fn();
+vi.mock("react-router-dom", () => ({
+  useNavigate: () => navigateMock,
+}));
+
+vi.mock("@/features/websocket/use-query-emit.ts", () => ({
+  useQueryEmit: () => vi.fn(),
+}));
+
+// page-query transitively imports @/main.tsx; mock it to a pure stub.
+vi.mock("@/features/page/queries/page-query", () => ({
+  updatePageData: vi.fn(),
+}));
+vi.mock("@/main.tsx", () => ({
+  queryClient: { getQueryData: vi.fn(), setQueryData: vi.fn() },
+}));
+
+import { TitleEditor } from "./title-editor";
+
+const baseProps = {
+  pageId: "p1",
+  slugId: "slug-1",
+  title: "My Page Title",
+  spaceSlug: "space",
+  editable: true,
+};
+
+beforeEach(() => {
+  navigateMock.mockReset();
+  editorProvidersValue.ydoc = null;
+  editorProvidersValue.providersReady = false;
+});
+
+describe("TitleEditor fallback vs collaborative switch", () => {
+  it("renders a static <h1> with the title before the shared doc is ready", () => {
+    editorProvidersValue.ydoc = null;
+    editorProvidersValue.providersReady = false;
+
+    render(<TitleEditor {...baseProps} />);
+
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading.textContent).toBe("My Page Title");
+    // The collaborative editor must NOT mount until the doc is ready.
+    expect(screen.queryByTestId("collab-editor")).toBeNull();
+  });
+
+  it("renders the collaborative editor once the shared doc is ready", () => {
+    editorProvidersValue.ydoc = {}; // truthy shared doc
+    editorProvidersValue.providersReady = true;
+
+    render(<TitleEditor {...baseProps} />);
+
+    expect(screen.getByTestId("collab-editor")).toBeDefined();
+    // The static fallback <h1> is gone — Yjs is the single source of truth and
+    // the prop is never seeded into the collaborative editor.
+    expect(screen.queryByRole("heading", { level: 1 })).toBeNull();
+  });
+});

apps/client/src/features/editor/title-editor.tsx

@@ -1,5 +1,5 @@
 import "@/features/editor/styles/index.css";
-import React, { useCallback, useEffect, useState } from "react";
+import { useEffect } from "react";
 import { EditorContent, useEditor } from "@tiptap/react";
 import { Document } from "@tiptap/extension-document";
 import { Heading } from "@tiptap/extension-heading";
@@ -11,14 +11,11 @@ import {
   pageEditorAtom,
   titleEditorAtom,
 } from "@/features/editor/atoms/editor-atoms";
-import {
-  updatePageData,
-  useUpdateTitlePageMutation,
-} from "@/features/page/queries/page-query";
+import { pageKeys, updatePageData } from "@/features/page/queries/page-query";
 import { useDebouncedCallback, getHotkeyHandler } from "@mantine/hooks";
 import { useAtom } from "jotai";
-import { useQueryEmit } from "@/features/websocket/use-query-emit.ts";
-import { History } from "@tiptap/extension-history";
+import { Collaboration } from "@tiptap/extension-collaboration";
+import { shouldPropagateTitleChange } from "@/features/editor/title-collab";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import { useNavigate } from "react-router-dom";
 import { useTranslation } from "react-i18next";
@@ -28,6 +25,9 @@ import localEmitter from "@/lib/local-emitter.ts";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import { searchSpotlight } from "@/features/search/constants.ts";
 import { platformModifierKey } from "@/lib";
+import { useEditorProviders } from "@/features/editor/contexts/editor-providers-context";
+import { queryClient } from "@/main.tsx";
+import { IPage } from "@/features/page/types/page.types.ts";
 
 export interface TitleEditorProps {
   pageId: string;
@@ -45,65 +45,82 @@ export function TitleEditor({
   editable,
 }: TitleEditorProps) {
   const { t } = useTranslation();
-  const { mutateAsync: updateTitlePageMutationAsync } =
-    useUpdateTitlePageMutation();
   const pageEditor = useAtomValue(pageEditorAtom);
   const [, setTitleEditor] = useAtom(titleEditorAtom);
-  const emit = useQueryEmit();
   const navigate = useNavigate();
-  const [activePageId, setActivePageId] = useState(pageId);
   const currentPageEditMode = useAtomValue(currentPageEditModeAtom);
 
-  const titleEditor = useEditor({
-    extensions: [
-      Document.extend({
-        content: "heading",
-      }),
-      Heading.configure({
-        levels: [1],
-      }),
-      Text,
-      Placeholder.configure({
-        placeholder: t("Untitled"),
-        showOnlyWhenEditable: false,
-      }),
-      History.configure({
-        depth: 20,
-      }),
-      EmojiCommand,
-    ],
-    onCreate({ editor }) {
-      if (editor) {
-        // @ts-ignore
-        setTitleEditor(editor);
-        setActivePageId(pageId);
-      }
-    },
-    onUpdate({ editor }) {
-      debounceUpdate();
-    },
-    editable: editable,
-    content: title,
-    immediatelyRender: true,
-    shouldRerenderOnTransaction: false,
-    editorProps: {
-      attributes: {
-        "aria-label": t("Page title"),
+  // Shared Y.Doc (title lives in its own 'title' fragment of the same doc as
+  // the body). Yjs is the source of truth for the title content.
+  const editorProviders = useEditorProviders();
+  const ydoc = editorProviders?.ydoc ?? null;
+  const providersReady = editorProviders?.providersReady ?? false;
+
+  // Until the shared doc is ready, the collaborative editor binds nothing and
+  // would render an empty heading until the Yjs 'title' fragment hydrates. Show
+  // a non-editable static <h1> with the `title` prop in the meantime. The prop
+  // is NEVER fed into the collaborative editor (Yjs stays the single source of
+  // truth — seeding it would duplicate the title).
+  const titleReady = providersReady && !!ydoc;
+
+  const titleEditor = useEditor(
+    {
+      extensions: [
+        Document.extend({
+          content: "heading",
+        }),
+        Heading.configure({
+          levels: [1],
+        }),
+        Text,
+        Placeholder.configure({
+          placeholder: t("Untitled"),
+          showOnlyWhenEditable: false,
+        }),
+        // Bind the title to the dedicated 'title' fragment of the shared doc.
+        // Collaboration also manages undo/redo, so the History extension is
+        // intentionally omitted (it would conflict with Yjs). When the doc is
+        // not ready yet the editor renders empty until the doc arrives.
+        ...(ydoc
+          ? [Collaboration.configure({ document: ydoc, field: "title" })]
+          : []),
+        EmojiCommand,
+      ],
+      onCreate({ editor }) {
+        if (editor) {
+          // @ts-ignore
+          setTitleEditor(editor);
+        }
       },
-      handleDOMEvents: {
-        keydown: (_view, event) => {
-          if (platformModifierKey(event) && event.code === "KeyS") {
-            event.preventDefault();
-            return true;
-          }
-          if (platformModifierKey(event) && event.code === "KeyK") {
-            searchSpotlight.open();
-            return true;
-          }
+      onUpdate({ editor, transaction }) {
+        // Drive URL + tree propagation only on genuine local edits; skip
+        // remote/collab-origin Yjs updates to avoid feedback loops.
+        if (!shouldPropagateTitleChange(transaction)) return;
+        debouncedPropagateTitle(editor.getText());
+      },
+      editable: editable,
+      immediatelyRender: true,
+      shouldRerenderOnTransaction: false,
+      editorProps: {
+        attributes: {
+          "aria-label": t("Page title"),
+        },
+        handleDOMEvents: {
+          keydown: (_view, event) => {
+            if (platformModifierKey(event) && event.code === "KeyS") {
+              event.preventDefault();
+              return true;
+            }
+            if (platformModifierKey(event) && event.code === "KeyK") {
+              searchSpotlight.open();
+              return true;
+            }
+          },
         },
       },
     },
-  });
+    [pageId, ydoc],
+  );
 
   useEffect(() => {
     const anchorId = window.location.hash
@@ -113,59 +130,45 @@ export function TitleEditor({
     navigate(pageSlug, { replace: true });
   }, [title]);
 
-  const saveTitle = useCallback(() => {
-    if (!titleEditor || activePageId !== pageId) return;
-
-    if (
-      titleEditor.getText() === title ||
-      (titleEditor.getText() === "" && title === null)
-    ) {
-      return;
-    }
-
-    updateTitlePageMutationAsync({
-      pageId: pageId,
-      title: titleEditor.getText(),
-    }).then((page) => {
-      const event: UpdateEvent = {
-        operation: "updateOne",
-        spaceId: page.spaceId,
-        entity: ["pages"],
-        id: page.id,
-        payload: {
-          title: page.title,
-          slugId: page.slugId,
-          parentPageId: page.parentPageId,
-          icon: page.icon,
-        },
-      };
-
-      if (page.title !== titleEditor.getText()) return;
-
-      updatePageData(page);
-
-      localEmitter.emit("message", event);
-      emit(event);
+  // On a local title change: update the URL slug and propagate the change to
+  // the live tree/breadcrumbs for online users. No REST round-trip — the title
+  // itself is persisted through Yjs. Offline this simply no-ops the socket
+  // emit and the title syncs on reconnect.
+  const debouncedPropagateTitle = useDebouncedCallback((titleText: string) => {
+    const anchorId = window.location.hash
+      ? window.location.hash.substring(1)
+      : undefined;
+    navigate(buildPageUrl(spaceSlug, slugId, titleText, anchorId), {
+      replace: true,
     });
-  }, [pageId, title, titleEditor]);
 
-  const debounceUpdate = useDebouncedCallback(saveTitle, 500);
+    const page =
+      queryClient.getQueryData<IPage>(pageKeys.detail(slugId)) ??
+      queryClient.getQueryData<IPage>(pageKeys.detail(pageId));
+    if (!page) return;
 
-  useEffect(() => {
-    // Do not overwrite the title while the user is actively editing it. The
-    // server rebroadcasts PAGE_UPDATED to the author too, and that echo can
-    // carry a title that lags behind what the user has just typed; resetting
-    // content from it here would drop in-progress characters and jump the
-    // cursor. Apply external title changes only when the field is not focused.
-    if (
-      titleEditor &&
-      !titleEditor.isDestroyed &&
-      !titleEditor.isFocused &&
-      title !== titleEditor.getText()
-    ) {
-      titleEditor.commands.setContent(title);
-    }
-  }, [pageId, title, titleEditor]);
+    const updatedPage: IPage = { ...page, title: titleText };
+
+    const event: UpdateEvent = {
+      operation: "updateOne",
+      spaceId: page.spaceId,
+      entity: ["pages"],
+      id: page.id,
+      payload: {
+        title: titleText,
+        slugId: page.slugId,
+        parentPageId: page.parentPageId,
+        icon: page.icon,
+      },
+    };
+
+    updatePageData(updatedPage);
+    // Drive the local (same-tab) tree/breadcrumb update. The cross-user tree
+    // refresh is handled server-side: the collab process extracts the renamed
+    // 'title' Yjs fragment and broadcasts a treeUpdate. The previous socket
+    // `emit(event)` here was a no-op (the gateway ignores it) and was removed.
+    localEmitter.emit("message", event);
+  }, 500);
 
   useEffect(() => {
     setTimeout(() => {
@@ -175,13 +178,6 @@ export function TitleEditor({
     }, 300);
   }, [titleEditor]);
 
-  useEffect(() => {
-    return () => {
-      // force-save title on navigation
-      saveTitle();
-    };
-  }, [pageId]);
-
   useEffect(() => {
     if (!titleEditor) return;
     titleEditor.setEditable(editable && currentPageEditMode === PageEditMode.Edit);
@@ -248,16 +244,22 @@ export function TitleEditor({
 
   return (
     <div className="page-title">
-      <EditorContent
-        editor={titleEditor}
-        onKeyDown={(event) => {
-          // First handle the search hotkey
-          getHotkeyHandler([["mod+F", openSearchDialog]])(event);
+      {titleReady ? (
+        <EditorContent
+          editor={titleEditor}
+          onKeyDown={(event) => {
+            // First handle the search hotkey
+            getHotkeyHandler([["mod+F", openSearchDialog]])(event);
 
-          // Then handle other key events
-          handleTitleKeyDown(event);
-        }}
-      />
+            // Then handle other key events
+            handleTitleKeyDown(event);
+          }}
+        />
+      ) : (
+        // Static, non-editable fallback so the title is visible before Yjs
+        // hydrates the 'title' fragment. Not wired into the collaborative editor.
+        <h1>{title}</h1>
+      )}
     </div>
   );
 }

apps/client/src/features/offline/clear-offline-cache.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// vi.mock factories are hoisted above imports, so the spies they reference must
+// be declared via vi.hoisted (also hoisted). These are inspected by assertions.
+const h = vi.hoisted(() => ({
+  clear: vi.fn(),
+  del: vi.fn(),
+}));
+
+// The module under test imports the app entry at load time — it must be mocked.
+vi.mock("@/main.tsx", () => ({
+  queryClient: { clear: h.clear },
+}));
+vi.mock("idb-keyval", () => ({
+  del: h.del,
+}));
+
+import { clearOfflineCache } from "./clear-offline-cache";
+import { OFFLINE_CACHE_KEY } from "./query-persister";
+
+// jsdom does not provide indexedDB.databases() or Cache Storage, so the browser
+// globals are stubbed per-test. We restore them afterwards.
+const originalIndexedDB = (globalThis as any).indexedDB;
+const originalCaches = (globalThis as any).caches;
+
+beforeEach(() => {
+  h.clear.mockClear();
+  h.del.mockClear();
+});
+
+afterEach(() => {
+  (globalThis as any).indexedDB = originalIndexedDB;
+  (globalThis as any).caches = originalCaches;
+  vi.restoreAllMocks();
+});
+
+describe("clearOfflineCache", () => {
+  it("resolves without throwing when the browser globals are absent", async () => {
+    (globalThis as any).indexedDB = undefined;
+    delete (globalThis as any).caches;
+
+    await expect(clearOfflineCache()).resolves.toBeUndefined();
+
+    // The two store-agnostic steps still run.
+    expect(h.clear).toHaveBeenCalledTimes(1);
+    expect(h.del).toHaveBeenCalledWith(OFFLINE_CACHE_KEY);
+  });
+
+  it("deletes only `page.*` IndexedDB databases and only `api-get-cache` caches", async () => {
+    const deleteDatabase = vi.fn((_name: string) => {
+      const request: any = {};
+      // Resolve the deletion on the next microtask, like a real IDBRequest.
+      queueMicrotask(() => request.onsuccess && request.onsuccess());
+      return request;
+    });
+    (globalThis as any).indexedDB = {
+      databases: vi
+        .fn()
+        .mockResolvedValue([
+          { name: "page.aaa" },
+          { name: "page.bbb" },
+          { name: "keyval-store" },
+          { name: undefined },
+        ]),
+      deleteDatabase,
+    };
+
+    const cacheDelete = vi.fn().mockResolvedValue(true);
+    (globalThis as any).caches = {
+      keys: vi
+        .fn()
+        .mockResolvedValue([
+          "workbox-runtime-https://app/api-get-cache",
+          "other-cache",
+        ]),
+      delete: cacheDelete,
+    };
+
+    await expect(clearOfflineCache()).resolves.toBeUndefined();
+
+    // Only the two page.* databases are deleted.
+    expect(deleteDatabase).toHaveBeenCalledTimes(2);
+    expect(deleteDatabase).toHaveBeenCalledWith("page.aaa");
+    expect(deleteDatabase).toHaveBeenCalledWith("page.bbb");
+
+    // Only the api-get-cache entry is deleted.
+    expect(cacheDelete).toHaveBeenCalledTimes(1);
+    expect(cacheDelete).toHaveBeenCalledWith(
+      "workbox-runtime-https://app/api-get-cache",
+    );
+  });
+
+  it("never throws even if a step rejects (best-effort)", async () => {
+    h.del.mockRejectedValueOnce(new Error("idb boom"));
+    (globalThis as any).indexedDB = {
+      databases: vi.fn().mockRejectedValue(new Error("databases boom")),
+      deleteDatabase: vi.fn(),
+    };
+    (globalThis as any).caches = {
+      keys: vi.fn().mockRejectedValue(new Error("caches boom")),
+      delete: vi.fn(),
+    };
+
+    await expect(clearOfflineCache()).resolves.toBeUndefined();
+    expect(h.clear).toHaveBeenCalledTimes(1);
+  });
+});

apps/client/src/features/offline/clear-offline-cache.ts

@@ -0,0 +1,94 @@
+import { del } from "idb-keyval";
+
+import { queryClient } from "@/main.tsx";
+import { OFFLINE_CACHE_KEY } from "./query-persister";
+import { PAGE_YDOC_NAME_PREFIX } from "@/features/editor/page-ydoc-name";
+
+/**
+ * Best-effort purge of all of the current user's offline data from the browser.
+ *
+ * On logout the previous user's private data would otherwise linger locally and
+ * be readable by the next person on the device. This clears the three offline
+ * stores the app writes:
+ *   1. the in-memory + IndexedDB-persisted TanStack Query cache (idb-keyval key
+ *      `OFFLINE_CACHE_KEY`),
+ *   2. the Yjs page documents (IndexedDB databases named `page.<id>` created by
+ *      y-indexeddb in make-offline.ts), and
+ *   3. any legacy service worker `api-get-cache` Cache Storage entry. The
+ *      Workbox runtime no longer creates this cache (the GET /api NetworkFirst
+ *      rule was removed — offline reads come from the persisted RQ cache), so
+ *      this is now a defensive cleanup for caches left by older app versions.
+ *
+ * Fully best-effort: every step is isolated so a single failure neither blocks
+ * the remaining steps nor throws to the caller (logout must never be blocked on
+ * cache cleanup). Callers may ignore the resolved value.
+ *
+ * Limitations:
+ *   - Deleting the Yjs page databases relies on `indexedDB.databases()`, which
+ *     is unavailable in some browsers (notably Firefox). There we skip silently;
+ *     those `page.<id>` databases are then left in place.
+ *   - Cache Storage clearing only runs where `caches` exists (secure contexts /
+ *     service-worker-capable browsers).
+ */
+export async function clearOfflineCache(): Promise<void> {
+  // 1a. Drop the in-memory query cache immediately.
+  try {
+    queryClient.clear();
+  } catch {
+    // best-effort: ignore in-memory cache reset failures
+  }
+
+  // 1b. Delete the persisted RQ cache from IndexedDB.
+  try {
+    await del(OFFLINE_CACHE_KEY);
+  } catch {
+    // best-effort: ignore persisted-cache deletion failures
+  }
+
+  // 2. Delete the Yjs page IndexedDB databases (`page.<id>`).
+  // `indexedDB.databases()` is not implemented everywhere (e.g. Firefox); when
+  // it is missing we cannot enumerate the page databases, so we skip silently.
+  try {
+    if (
+      typeof indexedDB !== "undefined" &&
+      typeof indexedDB.databases === "function"
+    ) {
+      const dbs = await indexedDB.databases();
+      for (const db of dbs) {
+        const name = db?.name;
+        if (typeof name !== "string" || !name.startsWith(PAGE_YDOC_NAME_PREFIX))
+          continue;
+        try {
+          // Fire-and-forget delete; await a thin wrapper so a slow delete does
+          // not race the page teardown, but never reject on it.
+          await new Promise<void>((resolve) => {
+            const request = indexedDB.deleteDatabase(name);
+            request.onsuccess = () => resolve();
+            request.onerror = () => resolve();
+            request.onblocked = () => resolve();
+          });
+        } catch {
+          // best-effort per database
+        }
+      }
+    }
+  } catch {
+    // best-effort: ignore enumeration/deletion failures
+  }
+
+  // 3. Clear any legacy service worker API cache. Current builds no longer
+  // create it, but an older client may have left an "api-get-cache" entry
+  // (Workbox may prefix the name), so match by substring rather than exact name.
+  try {
+    if ("caches" in window) {
+      const keys = await caches.keys();
+      await Promise.all(
+        keys
+          .filter((key) => key.includes("api-get-cache"))
+          .map((key) => caches.delete(key)),
+      );
+    }
+  } catch {
+    // best-effort: ignore Cache Storage failures
+  }
+}

apps/client/src/features/offline/make-offline.test.ts

@@ -0,0 +1,373 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// vi.mock factories are hoisted above imports, so any spy they reference must be
+// declared with vi.hoisted (which is hoisted as well). These shared spies are
+// inspected by the assertions below.
+const h = vi.hoisted(() => ({
+  ydocDestroy: vi.fn(),
+  idbDestroy: vi.fn(),
+  providerOn: vi.fn(),
+  providerOff: vi.fn(),
+  providerDestroy: vi.fn(),
+}));
+
+// The module under test imports the app entry at load time — it must be mocked.
+vi.mock("@/main.tsx", () => ({
+  queryClient: { setQueryData: vi.fn(), prefetchQuery: vi.fn() },
+}));
+vi.mock("@/features/page/services/page-service", () => ({
+  getPageById: vi.fn(),
+  getPageBreadcrumbs: vi.fn(),
+  getSidebarPages: vi.fn(),
+  getAllSidebarPages: vi.fn(),
+}));
+vi.mock("@/features/space/services/space-service.ts", () => ({
+  getSpaceById: vi.fn(),
+}));
+vi.mock("@/features/comment/services/comment-service", () => ({
+  getPageComments: vi.fn(),
+}));
+
+// Use the `function` form (not an arrow) so Vitest binds the constructor return
+// value when the module under test calls `new Y.Doc()` etc.
+vi.mock("yjs", () => ({
+  Doc: vi.fn(function () {
+    return { destroy: h.ydocDestroy };
+  }),
+}));
+vi.mock("y-indexeddb", () => ({
+  IndexeddbPersistence: vi.fn(function () {
+    return { destroy: h.idbDestroy };
+  }),
+}));
+vi.mock("@hocuspocus/provider", () => ({
+  HocuspocusProvider: vi.fn(function () {
+    return { on: h.providerOn, off: h.providerOff, destroy: h.providerDestroy };
+  }),
+}));
+
+import {
+  warmInfiniteAll,
+  warmPageYdoc,
+  makePageAvailableOffline,
+} from "./make-offline";
+import { queryClient } from "@/main.tsx";
+import {
+  getPageById,
+  getPageBreadcrumbs,
+  getSidebarPages,
+} from "@/features/page/services/page-service";
+import { getPageComments } from "@/features/comment/services/comment-service";
+
+const setQueryData = (queryClient as any).setQueryData as ReturnType<
+  typeof vi.fn
+>;
+const prefetchQuery = (queryClient as any).prefetchQuery as ReturnType<
+  typeof vi.fn
+>;
+
+beforeEach(() => {
+  // Clear call history WITHOUT wiping the mock implementations the vi.mock
+  // factories installed (vi.clearAllMocks would drop the constructor return
+  // objects and break the provider/idb/yjs spies).
+  setQueryData.mockClear();
+  prefetchQuery.mockReset();
+  prefetchQuery.mockResolvedValue(undefined);
+  (getPageById as ReturnType<typeof vi.fn>).mockReset();
+  (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockReset();
+  (getSidebarPages as ReturnType<typeof vi.fn>).mockReset();
+  (getPageComments as ReturnType<typeof vi.fn>).mockReset();
+  h.ydocDestroy.mockClear();
+  h.idbDestroy.mockClear();
+  h.providerOn.mockClear();
+  h.providerOff.mockClear();
+  h.providerDestroy.mockClear();
+});
+
+describe("warmInfiniteAll", () => {
+  it("warms a single page and writes the InfiniteData cache shape", async () => {
+    const res = { items: [{ id: 1 }], meta: { nextCursor: null } };
+    const fetchPage = vi.fn().mockResolvedValue(res);
+
+    await warmInfiniteAll(["comments", "p1"], fetchPage);
+
+    expect(fetchPage).toHaveBeenCalledTimes(1);
+    expect(fetchPage).toHaveBeenCalledWith(undefined);
+    expect(setQueryData).toHaveBeenCalledTimes(1);
+    expect(setQueryData).toHaveBeenCalledWith(["comments", "p1"], {
+      pages: [res],
+      pageParams: [undefined],
+    });
+  });
+
+  it("walks the cursor chain across multiple pages", async () => {
+    const r0 = { items: [], meta: { nextCursor: "c1" } };
+    const r1 = { items: [], meta: { nextCursor: "c2" } };
+    const r2 = { items: [], meta: { nextCursor: null } };
+    const fetchPage = vi
+      .fn()
+      .mockResolvedValueOnce(r0)
+      .mockResolvedValueOnce(r1)
+      .mockResolvedValueOnce(r2);
+
+    await warmInfiniteAll(["comments", "p1"], fetchPage);
+
+    expect(fetchPage).toHaveBeenCalledTimes(3);
+    expect(fetchPage.mock.calls.map((c) => c[0])).toEqual([
+      undefined,
+      "c1",
+      "c2",
+    ]);
+    const payload = setQueryData.mock.calls[0][1];
+    expect(payload.pages).toEqual([r0, r1, r2]);
+    expect(payload.pageParams).toEqual([undefined, "c1", "c2"]);
+  });
+
+  it("caps pagination at maxPages and reports the truncation (returns false)", async () => {
+    // Always returns a non-null cursor — the cap is the only thing that stops it.
+    const fetchPage = vi
+      .fn()
+      .mockResolvedValue({ items: [], meta: { nextCursor: "more" } });
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    // Hitting maxPages with a cursor still pending is a truncated warm: the
+    // (partial) cache is still written, but the result is reported as false.
+    await expect(
+      warmInfiniteAll(["comments", "p1"], fetchPage, 2),
+    ).resolves.toBe(false);
+
+    expect(fetchPage).toHaveBeenCalledTimes(2);
+    const payload = setQueryData.mock.calls[0][1];
+    expect(payload.pages).toHaveLength(2);
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+
+  it("returns true on success", async () => {
+    const fetchPage = vi
+      .fn()
+      .mockResolvedValue({ items: [], meta: { nextCursor: null } });
+
+    await expect(
+      warmInfiniteAll(["comments", "p1"], fetchPage),
+    ).resolves.toBe(true);
+  });
+
+  it("reports errors (returns false) and never writes the cache on failure", async () => {
+    const fetchPage = vi.fn().mockRejectedValue(new Error("network"));
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await expect(
+      warmInfiniteAll(["comments", "p1"], fetchPage),
+    ).resolves.toBe(false);
+    expect(setQueryData).not.toHaveBeenCalled();
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+});
+
+describe("makePageAvailableOffline", () => {
+  const okPage = {
+    id: "uuid-1",
+    slugId: "slug-1",
+    space: { slug: "space-slug" },
+  };
+
+  it("returns ok:true with no failures when every step succeeds", async () => {
+    (getPageById as ReturnType<typeof vi.fn>).mockResolvedValue(okPage);
+    (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    (getSidebarPages as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    (getPageComments as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+
+    const result = await makePageAvailableOffline({
+      pageId: "uuid-1",
+      spaceId: "space-uuid",
+    });
+
+    expect(result).toEqual({ ok: true, failed: [] });
+  });
+
+  it("returns ok:false with the failed step label when a warm step fails", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    (getPageById as ReturnType<typeof vi.fn>).mockResolvedValue(okPage);
+    (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    (getSidebarPages as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    // Comments warm fails -> labeled "comments".
+    (getPageComments as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error("network"),
+    );
+
+    const result = await makePageAvailableOffline({
+      pageId: "uuid-1",
+      spaceId: "space-uuid",
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.failed).toContain("comments");
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+
+  // Helper: the page-ids passed to the sidebar-children warm (its query key is
+  // ["sidebar-pages", { pageId, spaceId }]) — i.e. which nodes were prefetched.
+  const warmedSidebarIds = () =>
+    prefetchQuery.mock.calls
+      .map((c) => c[0])
+      .filter((opts: any) => opts?.queryKey?.[0] === "sidebar-pages")
+      .map((opts: any) => opts.queryKey[1]?.pageId);
+
+  it("warms the page + every ancestor's children once and skips the self-ancestor guard", async () => {
+    (getPageById as ReturnType<typeof vi.fn>).mockResolvedValue(okPage);
+    // Breadcrumbs include two real ancestors, the page's OWN id (must be skipped
+    // by the ancestorId === pageId guard so it is not warmed twice), and a
+    // malformed entry with no id (also skipped).
+    (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockResolvedValue([
+      { id: "anc-1" },
+      { id: "uuid-1" }, // === pageId -> guard
+      { id: "anc-2" },
+      {}, // no id -> skipped
+    ]);
+    (getSidebarPages as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    (getPageComments as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+
+    const result = await makePageAvailableOffline({
+      pageId: "uuid-1",
+      spaceId: "space-uuid",
+    });
+
+    const ids = warmedSidebarIds();
+    // The page's own children (warmSidebarChildren(pageId)) plus each real
+    // ancestor — exactly once each. The self-ancestor (uuid-1 in breadcrumbs) is
+    // NOT a second warm: uuid-1 appears once (from the page's own children call).
+    expect(ids).toEqual(["uuid-1", "anc-1", "anc-2"]);
+    expect(ids.filter((id: string) => id === "uuid-1")).toHaveLength(1);
+    expect(result).toEqual({ ok: true, failed: [] });
+  });
+
+  it("dedupes repeated tree failures into a single 'tree' label", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    (getPageById as ReturnType<typeof vi.fn>).mockResolvedValue(okPage);
+    (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockResolvedValue([
+      { id: "anc-1" },
+      { id: "anc-2" },
+    ]);
+    (getSidebarPages as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    (getPageComments as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    // Fail ONLY the sidebar-children prefetches (page-own + both ancestors = 3
+    // failures); the currentUser/space prefetches still resolve.
+    prefetchQuery.mockImplementation(async (opts: any) => {
+      if (opts?.queryKey?.[0] === "sidebar-pages") throw new Error("network");
+      return undefined;
+    });
+
+    const result = await makePageAvailableOffline({
+      pageId: "uuid-1",
+      spaceId: "space-uuid",
+    });
+
+    // Three node warms failed but the contract collapses them to one "tree".
+    expect(result.ok).toBe(false);
+    expect(result.failed).toEqual(["tree"]);
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+
+  it("records 'breadcrumbs' (not 'tree') when the breadcrumbs lookup rejects", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    (getPageById as ReturnType<typeof vi.fn>).mockResolvedValue(okPage);
+    // Ancestor discovery fails -> the ancestor-walk is recorded as "breadcrumbs".
+    (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error("network"),
+    );
+    (getSidebarPages as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    (getPageComments as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+
+    const result = await makePageAvailableOffline({
+      pageId: "uuid-1",
+      spaceId: "space-uuid",
+    });
+
+    // The page's own children still warmed fine (prefetch resolves), so the only
+    // failure is the breadcrumbs lookup.
+    expect(result.ok).toBe(false);
+    expect(result.failed).toEqual(["breadcrumbs"]);
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+});
+
+describe("warmPageYdoc", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("resolves on synced, detaches the listener once, and tears everything down (settle-once)", async () => {
+    const promise = warmPageYdoc("p1", "ws://x");
+
+    // Grab the synced handler the provider registered.
+    expect(h.providerOn).toHaveBeenCalledWith("synced", expect.any(Function));
+    const handler = h.providerOn.mock.calls.find(
+      (c) => c[0] === "synced",
+    )![1] as () => void;
+
+    handler();
+    await expect(promise).resolves.toBeUndefined();
+
+    // Listener detached and everything cleaned up.
+    expect(h.providerOff).toHaveBeenCalledWith("synced", expect.any(Function));
+    expect(h.providerDestroy).toHaveBeenCalledTimes(1);
+    expect(h.idbDestroy).toHaveBeenCalledTimes(1);
+    expect(h.ydocDestroy).toHaveBeenCalledTimes(1);
+
+    // Firing the handler again must NOT re-run cleanup (settled guard).
+    handler();
+    expect(h.providerDestroy).toHaveBeenCalledTimes(1);
+    expect(h.idbDestroy).toHaveBeenCalledTimes(1);
+    expect(h.ydocDestroy).toHaveBeenCalledTimes(1);
+  });
+
+  it("resolves and cleans up after the timeout when synced never fires", async () => {
+    vi.useFakeTimers();
+    const promise = warmPageYdoc("p1", "ws://x");
+
+    // Do not fire "synced"; let the 8s safety timeout settle it.
+    await vi.advanceTimersByTimeAsync(8000);
+    await expect(promise).resolves.toBeUndefined();
+
+    expect(h.providerDestroy).toHaveBeenCalledTimes(1);
+    expect(h.idbDestroy).toHaveBeenCalledTimes(1);
+    expect(h.ydocDestroy).toHaveBeenCalledTimes(1);
+  });
+});

apps/client/src/features/offline/make-offline.ts

@@ -0,0 +1,315 @@
+import * as Y from "yjs";
+import { IndexeddbPersistence } from "y-indexeddb";
+import { HocuspocusProvider } from "@hocuspocus/provider";
+
+import { queryClient } from "@/main.tsx";
+import {
+  getPageById,
+  getPageBreadcrumbs,
+  getSidebarPages,
+} from "@/features/page/services/page-service";
+import {
+  pageKeys,
+  sidebarPagesQueryOptions,
+} from "@/features/page/queries/page-query";
+import { spaceByIdQueryOptions } from "@/features/space/queries/space-query";
+import { RQ_KEY } from "@/features/comment/queries/comment-query";
+import { getPageComments } from "@/features/comment/services/comment-service";
+import { getMyInfo } from "@/features/user/services/user-service";
+import { userKeys } from "@/features/user/hooks/use-current-user";
+import { IPage } from "@/features/page/types/page.types";
+import { IPagination } from "@/lib/types.ts";
+import { pageYdocName } from "@/features/editor/page-ydoc-name";
+
+/**
+ * Fully paginate an infinite query and write the @tanstack InfiniteData cache
+ * shape ({ pages, pageParams }) that the matching useInfiniteQuery hook reads.
+ *
+ * The default prefetchInfiniteQuery only warms the FIRST page, which leaves
+ * hooks that treat hasNextPage as still-loading (e.g. the comments panel)
+ * spinning forever offline, and silently truncates large lists. This walks the
+ * cursor chain until it runs out (or hits maxPages) so the whole list is cached.
+ *
+ * Best-effort: a failure does not throw (a partial/failed warm is still useful),
+ * but it is reported — the error is logged with context and `false` is returned
+ * so the caller can record the failed step instead of silently succeeding.
+ *
+ * Returns true ONLY if the cursor chain was fully exhausted and written. If the
+ * walk stops because it hit `maxPages` while a `nextCursor` is still pending,
+ * the cached list is truncated AND its last page keeps a nextCursor that cannot
+ * be re-fetched offline (hooks that gate on hasNextPage would spin forever), so
+ * that case is logged and returns false too — the caller records it as a failed
+ * warm instead of a silent truncated success. The (partial) cache is still
+ * written so what we did fetch is usable.
+ *
+ * Exported for unit testing of the cursor-walk / cache-write behavior.
+ */
+export async function warmInfiniteAll<T>(
+  queryKey: readonly unknown[],
+  fetchPage: (cursor: string | undefined) => Promise<IPagination<T>>,
+  maxPages = 50,
+): Promise<boolean> {
+  try {
+    const pages: IPagination<T>[] = [];
+    const pageParams: (string | undefined)[] = [];
+    let cursor: string | undefined = undefined;
+    let exhausted = false;
+
+    for (let i = 0; i < maxPages; i++) {
+      const res = await fetchPage(cursor);
+      pages.push(res);
+      pageParams.push(cursor);
+      cursor = res?.meta?.nextCursor ?? undefined;
+      if (!cursor) {
+        exhausted = true;
+        break;
+      }
+    }
+
+    queryClient.setQueryData(queryKey, { pages, pageParams });
+
+    if (!exhausted) {
+      // Stopped at maxPages with a cursor still pending: the list is truncated
+      // and the last cached page's nextCursor is un-fetchable offline. Report it
+      // as a failed warm rather than a silent truncated success.
+      console.error("warmInfiniteAll truncated at maxPages", {
+        queryKey,
+        maxPages,
+      });
+      return false;
+    }
+    return true;
+  } catch (error) {
+    console.error("warmInfiniteAll failed", { queryKey, error });
+    return false;
+  }
+}
+
+export interface MakePageAvailableOfflineParams {
+  pageId: string;
+  spaceId?: string;
+}
+
+/**
+ * Outcome of {@link makePageAvailableOffline}. `ok` is true only when every warm
+ * step succeeded; `failed` lists the labels of the steps that failed (a subset
+ * of: "currentUser", "page", "space", "tree", "breadcrumbs", "comments").
+ */
+export interface MakePageAvailableOfflineResult {
+  ok: boolean;
+  failed: string[];
+}
+
+/**
+ * Best-effort prefetch of a page's read queries so they get persisted to
+ * IndexedDB and become readable offline.
+ *
+ * Each step is isolated and this function does NOT throw — a partial warm is
+ * still useful. Instead of silently succeeding, every failed step is logged
+ * with a label and recorded in the returned result: `{ ok, failed }` where
+ * `ok` is true only if no step failed and `failed` lists the failed step
+ * labels. Only meaningful while online (the underlying requests must succeed).
+ */
+export async function makePageAvailableOffline({
+  pageId,
+  spaceId,
+}: MakePageAvailableOfflineParams): Promise<MakePageAvailableOfflineResult> {
+  const failed: string[] = [];
+
+  // Warm the current user (['currentUser']) so the auth-gated <Layout> can
+  // hydrate offline. UserProvider blanks the whole app while useCurrentUser has
+  // no data, and the offline POST /api/users/me fails as a network error, so
+  // without a persisted user a pinned page still white-screens after relaunch
+  // (#238). Persisted via OFFLINE_PERSIST_ROOTS; warmed here so the persisted
+  // cache actually has an entry to restore.
+  try {
+    await queryClient.prefetchQuery({
+      queryKey: userKeys.currentUser(),
+      queryFn: () => getMyInfo(),
+    });
+  } catch (error) {
+    console.error("makePageAvailableOffline: currentUser step failed", {
+      pageId,
+      error,
+    });
+    failed.push("currentUser");
+  }
+
+  // Fetch the page document ONCE and write it under BOTH cache keys, exactly
+  // like usePageQuery's onData effect. Every page consumer reads
+  // pageKeys.detail(slugId) (usePageQuery keys on the slugId for routed reads),
+  // so warming only the uuid key would leave the offline page blank.
+  let page: IPage | undefined;
+  try {
+    page = await getPageById({ pageId });
+    queryClient.setQueryData(pageKeys.detail(page.slugId), page);
+    queryClient.setQueryData(pageKeys.detail(page.id), page);
+  } catch (error) {
+    console.error("makePageAvailableOffline: page step failed", {
+      pageId,
+      error,
+    });
+    failed.push("page");
+  }
+
+  // Warm the space — page.tsx renders nothing until the space query resolves
+  // (useGetSpaceBySlugQuery). Awaited (not the fire-and-forget prefetchSpace) so
+  // the space is actually persisted before the caller fires its toast. Shares
+  // spaceByIdQueryOptions so the key/fn cannot drift from the hook.
+  try {
+    const spaceSlug = page?.space?.slug;
+    if (spaceSlug) {
+      await queryClient.prefetchQuery(spaceByIdQueryOptions(spaceSlug));
+    }
+  } catch (error) {
+    console.error("makePageAvailableOffline: space step failed", {
+      pageId,
+      error,
+    });
+    failed.push("space");
+  }
+
+  // Warm the sidebar tree root so the WHOLE root level renders offline (matches
+  // useGetRootSidebarPagesQuery's pageKeys.rootSidebar(spaceId) infinite cache).
+  // Fully paginated so large root levels are not truncated at 100.
+  if (spaceId) {
+    const ok = await warmInfiniteAll(pageKeys.rootSidebar(spaceId), (cursor) =>
+      getSidebarPages({ spaceId, cursor, limit: 100 }),
+    );
+    if (!ok) failed.push("tree");
+  }
+
+  // Warm the children of the page and of every ancestor so the path to this
+  // page is expandable offline. We MIRROR fetchAllAncestorChildren exactly via
+  // sidebarPagesQueryOptions — same pageKeys.sidebar({ pageId, spaceId }) key,
+  // same getAllSidebarPages fn (which aggregates ALL children pages, so nothing
+  // is truncated at 100), same 30min staleTime — otherwise the warmed cache
+  // would never be read by the offline tree.
+  const warmSidebarChildren = async (id: string): Promise<boolean> => {
+    try {
+      // Keep EXACTLY { pageId, spaceId } so the key hashes identically to
+      // fetchAllAncestorChildren's (no parentPageId, no extra fields).
+      const params = { pageId: id, spaceId };
+      await queryClient.prefetchQuery(sidebarPagesQueryOptions(params));
+      return true;
+    } catch (error) {
+      console.error("makePageAvailableOffline: tree node step failed", {
+        pageId: id,
+        error,
+      });
+      return false;
+    }
+  };
+
+  // The page's own children.
+  if (!(await warmSidebarChildren(pageId))) failed.push("tree");
+
+  // Each ancestor's children. Use the breadcrumbs endpoint ONLY to discover the
+  // ancestor ids — we intentionally do NOT cache the breadcrumbs themselves
+  // (the UI derives the path from the tree).
+  try {
+    const ancestors = (await getPageBreadcrumbs(pageId)) as
+      | Array<{ id?: string }>
+      | undefined;
+    for (const ancestor of ancestors ?? []) {
+      const ancestorId = ancestor?.id;
+      if (!ancestorId || ancestorId === pageId) continue;
+      if (!(await warmSidebarChildren(ancestorId))) failed.push("tree");
+    }
+  } catch (error) {
+    console.error("makePageAvailableOffline: breadcrumbs step failed", {
+      pageId,
+      error,
+    });
+    failed.push("breadcrumbs");
+  }
+
+  // Comments (matches useCommentsQuery's RQ_KEY(pageId) infinite cache).
+  // useCommentsQuery reports isLoading while hasNextPage is true, so warming
+  // only the first page leaves the offline comments panel spinning forever on
+  // pages with >100 comments. Fully paginate so the last cached page has no
+  // nextCursor and the panel settles offline.
+  const commentsOk = await warmInfiniteAll(RQ_KEY(pageId), (cursor) =>
+    getPageComments({ pageId, cursor, limit: 100 }),
+  );
+  if (!commentsOk) failed.push("comments");
+
+  // Dedupe — the tree label can be recorded once per failed node/ancestor.
+  const uniqueFailed = [...new Set(failed)];
+  return { ok: uniqueFailed.length === 0, failed: uniqueFailed };
+}
+
+/**
+ * Best-effort warm-up of the page's Yjs document into IndexedDB so the editor
+ * can open offline.
+ *
+ * Opens a local IndexeddbPersistence plus a transient HocuspocusProvider to
+ * pull the server state into IndexedDB, then tears both down once synced (or
+ * after a timeout). Entirely wrapped in try/catch — NEVER throws.
+ *
+ * Only meaningful when online at warm time; offline it is a no-op that resolves.
+ */
+export async function warmPageYdoc(
+  pageId: string,
+  collabUrl: string,
+  token?: string,
+): Promise<void> {
+  let ydoc: Y.Doc | null = null;
+  let local: IndexeddbPersistence | null = null;
+  let remote: HocuspocusProvider | null = null;
+
+  try {
+    const documentName = pageYdocName(pageId);
+    ydoc = new Y.Doc();
+    local = new IndexeddbPersistence(documentName, ydoc);
+    remote = new HocuspocusProvider({
+      url: collabUrl,
+      name: documentName,
+      document: ydoc,
+      token,
+    });
+
+    const provider = remote;
+
+    await new Promise<void>((resolve) => {
+      let settled = false;
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        // Clear the pending timeout and detach the listener so neither leaks
+        // after we resolve.
+        if (timeoutId !== undefined) clearTimeout(timeoutId);
+        try {
+          provider.off("synced", finish);
+        } catch {
+          // best-effort
+        }
+        resolve();
+      };
+
+      // Resolve once the server state has synced into the local doc...
+      provider.on("synced", finish);
+      // ...or give up after a short timeout so we never hang.
+      timeoutId = setTimeout(finish, 8000);
+    });
+  } catch {
+    // best-effort
+  } finally {
+    try {
+      remote?.destroy();
+    } catch {
+      // best-effort
+    }
+    try {
+      local?.destroy();
+    } catch {
+      // best-effort
+    }
+    try {
+      ydoc?.destroy();
+    } catch {
+      // best-effort
+    }
+  }
+}

apps/client/src/features/offline/offline-fallback.tsx

@@ -0,0 +1,45 @@
+import { Button, Container, Group, Stack, Text, Title } from "@mantine/core";
+import { Helmet } from "react-helmet-async";
+import { useTranslation } from "react-i18next";
+import { getAppName } from "@/lib/config";
+
+/**
+ * Shown when the authenticated app shell cannot hydrate because the current
+ * user is unavailable AND there is no cached user to fall back on (e.g. an
+ * offline cold boot of a page that was never warmed for offline).
+ *
+ * Previously UserProvider returned a bare `<></>` in this situation, which
+ * white-screened the whole app on any offline reload (#237/#238). Rendering an
+ * explicit "you're offline" state with a retry instead gives the user a clear,
+ * non-blank fallback and a way to recover once the network returns.
+ */
+export function OfflineFallback() {
+  const { t } = useTranslation();
+
+  return (
+    <>
+      <Helmet>
+        <title>
+          {t("You're offline")} - {getAppName()}
+        </title>
+      </Helmet>
+      <Container size="sm" py={80}>
+        <Stack align="center" gap="md">
+          <Title order={2} ta="center">
+            {t("You're offline")}
+          </Title>
+          <Text c="dimmed" size="lg" ta="center">
+            {t(
+              "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.",
+            )}
+          </Text>
+          <Group justify="center">
+            <Button onClick={() => window.location.reload()} variant="subtle">
+              {t("Retry")}
+            </Button>
+          </Group>
+        </Stack>
+      </Container>
+    </>
+  );
+}

apps/client/src/features/offline/offline-mutations.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { QueryClient, hydrate, dehydrate } from "@tanstack/react-query";
+
+// Stub the network services so a replayed mutation hits a spy, not the network.
+const h = vi.hoisted(() => ({
+  createPage: vi.fn(),
+  movePage: vi.fn(),
+  createComment: vi.fn(),
+}));
+
+vi.mock("@/features/page/services/page-service", () => ({
+  createPage: h.createPage,
+  movePage: h.movePage,
+}));
+vi.mock("@/features/comment/services/comment-service", () => ({
+  createComment: h.createComment,
+}));
+// page-query pulls in the app entry (queryClient) and a lot of UI deps via its
+// cache helpers; we only need invalidateOnCreatePage to be a no-op here.
+vi.mock("@/features/page/queries/page-query", () => ({
+  invalidateOnCreatePage: vi.fn(),
+}));
+
+import {
+  offlineMutationKeys,
+  registerOfflineMutationDefaults,
+} from "./offline-mutations";
+
+beforeEach(() => {
+  h.createPage.mockReset().mockResolvedValue({ id: "new-page" });
+  h.movePage.mockReset().mockResolvedValue(undefined);
+  h.createComment.mockReset().mockResolvedValue({ id: "new-comment" });
+});
+
+describe("registerOfflineMutationDefaults", () => {
+  it("registers a default mutationFn for every offline mutation key", () => {
+    const qc = new QueryClient();
+    registerOfflineMutationDefaults(qc);
+
+    for (const key of Object.values(offlineMutationKeys)) {
+      const defaults = qc.getMutationDefaults(key);
+      expect(typeof defaults?.mutationFn).toBe("function");
+    }
+  });
+
+  // The headline durability guarantee: a paused mutation dehydrated into
+  // IndexedDB while offline must, after a reload, have a mutationFn so
+  // resumePausedMutations() actually replays the write on reconnect.
+  it("makes a rehydrated paused create replayable by resumePausedMutations", async () => {
+    // 1) Simulate the offline tab: a paused create mutation gets dehydrated.
+    const offlineClient = new QueryClient();
+    const observer = offlineClient.getMutationCache().build(offlineClient, {
+      mutationKey: offlineMutationKeys.createPage,
+    });
+    // Force the dehydrate-worthy paused state (offline = isPaused) with the
+    // payload the user submitted before losing connectivity.
+    observer.state.isPaused = true;
+    observer.state.status = "pending";
+    observer.state.variables = { spaceId: "s1", title: "Offline page" };
+
+    const dehydrated = dehydrate(offlineClient, {
+      shouldDehydrateMutation: () => true,
+    });
+    expect(dehydrated.mutations).toHaveLength(1);
+    // The dehydrated mutation carries NO mutationFn (functions aren't
+    // serializable) — only its key + variables survive the reload.
+    expect((dehydrated.mutations[0] as any).mutationFn).toBeUndefined();
+
+    // 2) Simulate the fresh page after reload: register defaults, then hydrate
+    //    the persisted paused mutation back in.
+    const freshClient = new QueryClient();
+    registerOfflineMutationDefaults(freshClient);
+    hydrate(freshClient, dehydrated);
+
+    expect(freshClient.getMutationCache().getAll()).toHaveLength(1);
+
+    // 3) Reconnect: replay the paused mutations.
+    await freshClient.resumePausedMutations();
+
+    // The default mutationFn ran with the persisted variables — the write is
+    // NOT silently dropped.
+    expect(h.createPage).toHaveBeenCalledTimes(1);
+    expect(h.createPage).toHaveBeenCalledWith({
+      spaceId: "s1",
+      title: "Offline page",
+    });
+  });
+
+  it("makes a rehydrated paused move replayable by resumePausedMutations", async () => {
+    const offlineClient = new QueryClient();
+    const observer = offlineClient.getMutationCache().build(offlineClient, {
+      mutationKey: offlineMutationKeys.movePage,
+    });
+    observer.state.isPaused = true;
+    observer.state.status = "pending";
+    observer.state.variables = { pageId: "p1", parentPageId: null, position: "a" };
+
+    const dehydrated = dehydrate(offlineClient, {
+      shouldDehydrateMutation: () => true,
+    });
+
+    const freshClient = new QueryClient();
+    registerOfflineMutationDefaults(freshClient);
+    hydrate(freshClient, dehydrated);
+    await freshClient.resumePausedMutations();
+
+    expect(h.movePage).toHaveBeenCalledTimes(1);
+    expect(h.movePage).toHaveBeenCalledWith({
+      pageId: "p1",
+      parentPageId: null,
+      position: "a",
+    });
+  });
+});

apps/client/src/features/offline/offline-mutations.ts

@@ -0,0 +1,64 @@
+import type { QueryClient } from "@tanstack/react-query";
+import { createPage, movePage } from "@/features/page/services/page-service";
+import { createComment } from "@/features/comment/services/comment-service";
+import { invalidateOnCreatePage } from "@/features/page/queries/page-query";
+import type {
+  IMovePage,
+  IPage,
+  IPageInput,
+} from "@/features/page/types/page.types";
+import type { IComment } from "@/features/comment/types/comment.types";
+
+/**
+ * Stable mutation keys for the offline-relevant structural mutations.
+ *
+ * When the browser goes offline, React Query PAUSES these mutations and the
+ * PersistQueryClientProvider dehydrates the paused mutation into IndexedDB. On a
+ * reload-while-offline the mutation is restored, but a restored mutation has NO
+ * observer (no component is mounted) — so its replay relies entirely on the
+ * `mutationFn` registered via `setMutationDefaults` for its `mutationKey`.
+ * Without that, `resumePausedMutations()` finds a paused mutation with no
+ * `mutationFn` and silently no-ops, dropping the offline create/move/comment
+ * (#237/#238). Each offline mutation hook tags itself with the matching key so
+ * the rehydrated paused mutation can find its default `mutationFn` and replay.
+ */
+export const offlineMutationKeys = {
+  createPage: ["create-page"] as const,
+  movePage: ["move-page"] as const,
+  createComment: ["create-comment"] as const,
+};
+
+/**
+ * Register default `mutationFn`s (and the minimal success side effects safe to
+ * run without a mounted component) for the offline-relevant mutation keys, so a
+ * paused mutation restored from IndexedDB after an offline reload is replayable
+ * by `resumePausedMutations()` on reconnect.
+ *
+ * Called once when the QueryClient is created (see main.tsx). The hooks still
+ * carry their own inline `mutationFn`/`onSuccess` for the live in-session path;
+ * these defaults only take over for a rehydrated paused mutation that lost its
+ * observer across the reload.
+ */
+export function registerOfflineMutationDefaults(queryClient: QueryClient): void {
+  queryClient.setMutationDefaults(offlineMutationKeys.createPage, {
+    mutationFn: (data: Partial<IPageInput>) => createPage(data),
+    // Re-converge the sidebar tree / recent-changes from the authoritative
+    // create response. Pure cache writes — safe with no component mounted.
+    onSuccess: (data: IPage) => {
+      invalidateOnCreatePage(data);
+    },
+  });
+
+  queryClient.setMutationDefaults(offlineMutationKeys.movePage, {
+    // Replay the server-side move. The tree re-converges from the next online
+    // sidebar fetch / websocket `moveTreeNode` echo, so no cache write is
+    // needed here (the optimistic tree state was local-only anyway).
+    mutationFn: (data: IMovePage) => movePage(data),
+  });
+
+  queryClient.setMutationDefaults(offlineMutationKeys.createComment, {
+    // Replay the server-side comment create. The comments list refetches on the
+    // online reload, so the replay only needs to persist the write.
+    mutationFn: (data: Partial<IComment>) => createComment(data),
+  });
+}

apps/client/src/features/offline/persist-roots.guard.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+
+// The query modules transitively import the app entry (@/main.tsx) for the
+// shared queryClient; mock it so importing the key factories has no side effects.
+import { vi } from "vitest";
+vi.mock("@/main.tsx", () => ({
+  queryClient: { setQueryData: vi.fn(), getQueryData: vi.fn() },
+}));
+
+import { OFFLINE_PERSIST_ROOTS } from "./query-persister";
+import { pageKeys } from "@/features/page/queries/page-query";
+import { spaceKeys } from "@/features/space/queries/space-query";
+import { RQ_KEY } from "@/features/comment/queries/comment-query";
+import { userKeys } from "@/features/user/hooks/use-current-user";
+
+/**
+ * Architecture guard (#13): every string persisted via OFFLINE_PERSIST_ROOTS
+ * must be the ROOT (queryKey[0]) of some exported query-key factory. If a
+ * factory's root is renamed without updating the persist registry — or vice
+ * versa — offline persist/warm silently breaks (persisted keys never match the
+ * live queries). This turns that silent regression into a red build.
+ *
+ * Each factory is invoked with throwaway args; only queryKey[0] is inspected.
+ */
+function rootOf(key: readonly unknown[]): string {
+  return String(key[0]);
+}
+
+const FACTORY_ROOTS = new Set<string>([
+  rootOf(pageKeys.detail("x")),
+  rootOf(pageKeys.sidebar({})),
+  rootOf(pageKeys.rootSidebar("x")),
+  rootOf(pageKeys.breadcrumbs("x")),
+  rootOf(pageKeys.recentChanges("x")),
+  rootOf(spaceKeys.detail("x")),
+  rootOf(spaceKeys.list()),
+  rootOf(RQ_KEY("x")),
+  rootOf(userKeys.currentUser()),
+]);
+
+describe("OFFLINE_PERSIST_ROOTS is backed by real query-key factories", () => {
+  it("maps every persisted root to an exported factory root", () => {
+    const unbacked = [...OFFLINE_PERSIST_ROOTS].filter(
+      (root) => !FACTORY_ROOTS.has(root),
+    );
+    expect(unbacked).toEqual([]);
+  });
+});

apps/client/src/features/offline/query-persister.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "vitest";
+import {
+  shouldDehydrateOfflineQuery,
+  OFFLINE_PERSIST_ROOTS,
+} from "./query-persister";
+
+// Small helper to build the structural query shape the predicate reads.
+const makeQuery = (status: string, queryKey: readonly unknown[]) =>
+  ({ state: { status }, queryKey }) as any;
+
+describe("shouldDehydrateOfflineQuery", () => {
+  it("returns true for a successful query whose root is in the allowlist", () => {
+    expect(shouldDehydrateOfflineQuery(makeQuery("success", ["pages", "abc"]))).toBe(
+      true,
+    );
+    expect(
+      shouldDehydrateOfflineQuery(
+        makeQuery("success", ["sidebar-pages", { pageId: "p", spaceId: "s" }]),
+      ),
+    ).toBe(true);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["comments", "p1"])),
+    ).toBe(true);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["space", "s"])),
+    ).toBe(true);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["recent-changes"])),
+    ).toBe(true);
+    // currentUser is persisted so the auth-gated Layout can hydrate offline.
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["currentUser"])),
+    ).toBe(true);
+  });
+
+  it("returns false when the status is not success (status gate)", () => {
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("pending", ["pages", "abc"])),
+    ).toBe(false);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("error", ["pages", "abc"])),
+    ).toBe(false);
+  });
+
+  it("returns false for a successful query whose root is NOT in the allowlist (privacy gate)", () => {
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["collab-token", "ws"])),
+    ).toBe(false);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["trash", "s"])),
+    ).toBe(false);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["unknown"])),
+    ).toBe(false);
+  });
+
+  it("returns false for an empty/undefined queryKey", () => {
+    // String(undefined) is not a member of the allowlist.
+    expect(shouldDehydrateOfflineQuery(makeQuery("success", []))).toBe(false);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", undefined as any)),
+    ).toBe(false);
+  });
+});
+
+describe("OFFLINE_PERSIST_ROOTS", () => {
+  it("contains exactly the expected 9 navigation/read roots", () => {
+    const expected = [
+      "pages",
+      "sidebar-pages",
+      "root-sidebar-pages",
+      "breadcrumbs",
+      "comments",
+      "space",
+      "spaces",
+      "recent-changes",
+      "currentUser",
+    ];
+    expect(OFFLINE_PERSIST_ROOTS.size).toBe(9);
+    for (const root of expected) {
+      expect(OFFLINE_PERSIST_ROOTS.has(root)).toBe(true);
+    }
+  });
+
+  it("does NOT contain volatile/auth keys", () => {
+    expect(OFFLINE_PERSIST_ROOTS.has("collab-token")).toBe(false);
+    expect(OFFLINE_PERSIST_ROOTS.has("trash")).toBe(false);
+  });
+});

apps/client/src/features/offline/query-persister.ts

@@ -0,0 +1,58 @@
+import { get, set, del } from "idb-keyval";
+import { createAsyncStoragePersister } from "@tanstack/query-async-storage-persister";
+
+// Structural subset of a TanStack Query we read when deciding what to persist.
+// We avoid importing the branded `Query` class because the persist-client and
+// react-query may resolve to different `@tanstack/query-core` copies, whose
+// `Query` types are nominally incompatible (private brand). This structural
+// shape stays assignable to whichever copy the persister expects.
+type DehydratableQuery = {
+  state: { status: string };
+  queryKey: readonly unknown[];
+};
+
+// idb-keyval key under which TanStack Query persists its dehydrated cache.
+// Exported so the logout cache-clear logic deletes the exact same key (no
+// magic-string drift between persist and purge).
+export const OFFLINE_CACHE_KEY = "gitmost-rq-cache";
+
+// IndexedDB-backed storage adapter for TanStack Query's async persister.
+const idbStorage = {
+  getItem: (key: string) => get<string>(key).then((v) => v ?? null),
+  setItem: (key: string, value: string) => set(key, value),
+  removeItem: (key: string) => del(key),
+};
+
+export const queryPersister = createAsyncStoragePersister({
+  storage: idbStorage,
+  key: OFFLINE_CACHE_KEY,
+  throttleTime: 1000,
+});
+
+// Only navigation/read query roots are persisted for offline reading.
+// Volatile/auth queries (collab tokens, trash lists) are intentionally excluded.
+//
+// `currentUser` IS persisted: UserProvider gates the entire <Layout> subtree on
+// useCurrentUser(), and offline the POST /api/users/me fails as a no-response
+// network error. Without the persisted/hydrated user the gate blanked every
+// authenticated route on an offline cold boot (#237/#238). It is the logged-in
+// user's own profile (already mirrored to localStorage["currentUser"]), so
+// persisting it to IndexedDB leaks nothing new while unlocking offline reads.
+export const OFFLINE_PERSIST_ROOTS = new Set<string>([
+  "pages",
+  "sidebar-pages",
+  "root-sidebar-pages",
+  "breadcrumbs",
+  "comments",
+  "space",
+  "spaces",
+  "recent-changes",
+  "currentUser",
+]);
+
+export function shouldDehydrateOfflineQuery(query: DehydratableQuery): boolean {
+  return (
+    query.state.status === "success" &&
+    OFFLINE_PERSIST_ROOTS.has(String(query.queryKey?.[0]))
+  );
+}

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

@@ -1,227 +0,0 @@
-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,7 +1,6 @@
 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";
@@ -42,7 +41,6 @@ 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
@@ -110,10 +108,6 @@ const HistoryItem = memo(function HistoryItem({
             onActivate={() => setHistoryModalOpen(false)}
           />
         )}
-
-        {isGitSyncEdit && (
-          <GitSyncBadge authorName={historyItem.lastUpdatedBy?.name} />
-        )}
       </Group>
     </UnstyledButton>
   );

apps/client/src/features/page/components/header/page-header-menu.tsx

@@ -12,6 +12,8 @@ import {
   IconList,
   IconMarkdown,
   IconPrinter,
+  IconCloud,
+  IconCloudCheck,
   IconStar,
   IconStarFilled,
   IconTrash,
@@ -39,6 +41,8 @@ import { Trans, useTranslation } from "react-i18next";
 import ExportModal from "@/components/common/export-modal";
 import { htmlToMarkdown } from "@docmost/editor-ext";
 import {
+  isLocalSyncedAtom,
+  isRemoteSyncedAtom,
   pageEditorAtom,
   yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms.ts";
@@ -411,14 +415,16 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
 function ConnectionWarning() {
   const { t } = useTranslation();
   const yjsConnectionStatus = useAtomValue(yjsConnectionStatusAtom);
+  const isLocalSynced = useAtomValue(isLocalSyncedAtom);
+  const isRemoteSynced = useAtomValue(isRemoteSyncedAtom);
   const [showWarning, setShowWarning] = useState(false);
   const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  useEffect(() => {
-    const isDisconnected = ["disconnected", "connecting"].includes(
-      yjsConnectionStatus,
-    );
+  const isDisconnected = ["disconnected", "connecting"].includes(
+    yjsConnectionStatus,
+  );
 
+  useEffect(() => {
     if (isDisconnected) {
       if (!timeoutRef.current) {
         timeoutRef.current = setTimeout(() => setShowWarning(true), 5000);
@@ -430,7 +436,7 @@ function ConnectionWarning() {
       }
       setShowWarning(false);
     }
-  }, [yjsConnectionStatus]);
+  }, [isDisconnected]);
 
   // Cleanup only on unmount
   useEffect(() => {
@@ -441,22 +447,59 @@ function ConnectionWarning() {
     };
   }, []);
 
-  if (!showWarning) return null;
+  // State (1): offline/disconnected — changes are kept locally. Preserve the
+  // existing >5s debounce before surfacing this state.
+  if (isDisconnected) {
+    if (!showWarning) return null;
 
+    const offlineLabel = t(
+      "Offline — changes are saved locally and will sync when you reconnect",
+    );
+    return (
+      <Tooltip label={offlineLabel} openDelay={250} withArrow>
+        <ThemeIcon
+          variant="default"
+          c="red"
+          role="status"
+          aria-label={offlineLabel}
+          style={{ border: "none" }}
+        >
+          <IconWifiOff size={20} stroke={2} />
+        </ThemeIcon>
+      </Tooltip>
+    );
+  }
+
+  // State (2): connected but the remote replica is not fully caught up yet.
+  if (!isRemoteSynced || !isLocalSynced) {
+    const syncingLabel = t("Syncing changes…");
+    return (
+      <Tooltip label={syncingLabel} openDelay={250} withArrow>
+        <ThemeIcon
+          variant="default"
+          c="dimmed"
+          role="status"
+          aria-label={syncingLabel}
+          style={{ border: "none" }}
+        >
+          <IconCloud size={20} stroke={2} />
+        </ThemeIcon>
+      </Tooltip>
+    );
+  }
+
+  // State (3): fully synced — subtle confirmation indicator.
+  const syncedLabel = t("All changes synced");
   return (
-    <Tooltip
-      label={t("Real-time editor connection lost. Retrying...")}
-      openDelay={250}
-      withArrow
-    >
+    <Tooltip label={syncedLabel} openDelay={250} withArrow>
       <ThemeIcon
         variant="default"
-        c="red"
+        c="dimmed"
         role="status"
-        aria-label={t("Real-time editor connection lost. Retrying...")}
+        aria-label={syncedLabel}
         style={{ border: "none" }}
       >
-        <IconWifiOff size={20} stroke={2} />
+        <IconCloudCheck size={20} stroke={2} />
       </ThemeIcon>
     </Tooltip>
   );

apps/client/src/features/page/queries/page-query.ts

@@ -1,6 +1,7 @@
 import {
   InfiniteData,
   QueryKey,
+  queryOptions,
   useInfiniteQuery,
   UseInfiniteQueryResult,
   useMutation,
@@ -42,12 +43,38 @@ import { treeModel } from "@/features/page/tree/model/tree-model";
 import { SpaceTreeNode } from "@/features/page/tree/types";
 import { useQueryEmit } from "@/features/websocket/use-query-emit";
 import { moveToTrashNotificationMessage } from "@/features/page/components/move-to-trash-notification";
+import { offlineMutationKeys } from "@/features/offline/offline-mutations";
+
+/**
+ * Centralized React Query key factories for page queries. The hooks below and
+ * the offline warm path (features/offline/make-offline.ts) share these so the
+ * runtime keys can never silently drift apart.
+ */
+export const pageKeys = {
+  detail: (idOrSlug: string) => ["pages", idOrSlug] as const,
+  sidebar: (data: unknown) => ["sidebar-pages", data] as const,
+  rootSidebar: (spaceId: string) => ["root-sidebar-pages", spaceId] as const,
+  breadcrumbs: (pageId: string) => ["breadcrumbs", pageId] as const,
+  recentChanges: (spaceId?: string) => ["recent-changes", spaceId] as const,
+};
+
+/**
+ * Shared queryOptions for the sidebar-pages (ancestor children) query. Both
+ * fetchAllAncestorChildren and the offline warm path consume this so the key,
+ * queryFn and staleTime stay identical.
+ */
+export const sidebarPagesQueryOptions = (params: SidebarPagesParams) =>
+  queryOptions({
+    queryKey: pageKeys.sidebar(params),
+    queryFn: () => getAllSidebarPages(params),
+    staleTime: 30 * 60 * 1000,
+  });
 
 export function usePageQuery(
   pageInput: Partial<IPageInput>,
 ): UseQueryResult<IPage, Error> {
   const query = useQuery({
-    queryKey: ["pages", pageInput.pageId],
+    queryKey: pageKeys.detail(pageInput.pageId),
     queryFn: () => getPageById(pageInput),
     enabled: !!pageInput.pageId,
     staleTime: 5 * 60 * 1000,
@@ -56,9 +83,9 @@ export function usePageQuery(
   useEffect(() => {
     if (query.data) {
       if (isValidUuid(pageInput.pageId)) {
-        queryClient.setQueryData(["pages", query.data.slugId], query.data);
+        queryClient.setQueryData(pageKeys.detail(query.data.slugId), query.data);
       } else {
-        queryClient.setQueryData(["pages", query.data.id], query.data);
+        queryClient.setQueryData(pageKeys.detail(query.data.id), query.data);
       }
     }
   }, [query.data]);
@@ -69,6 +96,10 @@ export function usePageQuery(
 export function useCreatePageMutation() {
   const { t } = useTranslation();
   return useMutation<IPage, Error, Partial<IPageInput>>({
+    // Stable key so a paused create restored from IndexedDB after an offline
+    // reload finds its default mutationFn (registerOfflineMutationDefaults) and
+    // is replayed by resumePausedMutations() on reconnect instead of being lost.
+    mutationKey: offlineMutationKeys.createPage,
     mutationFn: (data) => createPage(data),
     onSuccess: (data) => {
       invalidateOnCreatePage(data);
@@ -80,18 +111,20 @@ export function useCreatePageMutation() {
 }
 
 export function updatePageData(data: IPage) {
-  const pageBySlug = queryClient.getQueryData<IPage>(["pages", data.slugId]);
-  const pageById = queryClient.getQueryData<IPage>(["pages", data.id]);
+  const pageBySlug = queryClient.getQueryData<IPage>(
+    pageKeys.detail(data.slugId),
+  );
+  const pageById = queryClient.getQueryData<IPage>(pageKeys.detail(data.id));
 
   if (pageBySlug) {
-    queryClient.setQueryData(["pages", data.slugId], {
+    queryClient.setQueryData(pageKeys.detail(data.slugId), {
       ...pageBySlug,
       ...data,
     });
   }
 
   if (pageById) {
-    queryClient.setQueryData(["pages", data.id], { ...pageById, ...data });
+    queryClient.setQueryData(pageKeys.detail(data.id), { ...pageById, ...data });
   }
 
   invalidateOnUpdatePage(
@@ -145,11 +178,11 @@ export function useRemovePageMutation() {
       });
 
       // Stamp deletedAt so a re-visit shows the trash banner, not stale state.
-      const cached = queryClient.getQueryData<IPage>(["pages", pageId]);
+      const cached = queryClient.getQueryData<IPage>(pageKeys.detail(pageId));
       if (cached) {
         const stamped = { ...cached, deletedAt: new Date() };
-        queryClient.setQueryData(["pages", cached.id], stamped);
-        queryClient.setQueryData(["pages", cached.slugId], stamped);
+        queryClient.setQueryData(pageKeys.detail(cached.id), stamped);
+        queryClient.setQueryData(pageKeys.detail(cached.slugId), stamped);
       }
 
       invalidateOnDeletePage(pageId);
@@ -188,6 +221,9 @@ export function useDeletePageMutation() {
 
 export function useMovePageMutation() {
   return useMutation<void, Error, IMovePage>({
+    // Stable key so a paused move restored from IndexedDB after an offline
+    // reload finds its default mutationFn and is replayed on reconnect.
+    mutationKey: offlineMutationKeys.movePage,
     mutationFn: (data) => movePage(data),
   });
 }
@@ -267,8 +303,11 @@ export function useRestorePageMutation() {
       // Replace would strip space/permissions/content and break the editor.
       const merge = (cached: IPage | undefined) =>
         cached ? { ...cached, ...restoredPage } : cached;
-      queryClient.setQueryData<IPage>(["pages", restoredPage.id], merge);
-      queryClient.setQueryData<IPage>(["pages", restoredPage.slugId], merge);
+      queryClient.setQueryData<IPage>(pageKeys.detail(restoredPage.id), merge);
+      queryClient.setQueryData<IPage>(
+        pageKeys.detail(restoredPage.slugId),
+        merge,
+      );
     },
     onError: (error) => {
       notifications.show({
@@ -283,7 +322,7 @@ export function useGetSidebarPagesQuery(
   data: SidebarPagesParams | null,
 ): UseInfiniteQueryResult<InfiniteData<IPagination<IPage>, unknown>> {
   return useInfiniteQuery({
-    queryKey: ["sidebar-pages", data],
+    queryKey: pageKeys.sidebar(data),
     enabled: !!data?.pageId || !!data?.spaceId,
     queryFn: ({ pageParam }) =>
       getSidebarPages({ ...data, cursor: pageParam, limit: 100 }),
@@ -294,7 +333,7 @@ export function useGetSidebarPagesQuery(
 
 export function useGetRootSidebarPagesQuery(data: SidebarPagesParams) {
   return useInfiniteQuery({
-    queryKey: ["root-sidebar-pages", data.spaceId],
+    queryKey: pageKeys.rootSidebar(data.spaceId),
     queryFn: async ({ pageParam }) => {
       return getSidebarPages({
         spaceId: data.spaceId,
@@ -320,7 +359,7 @@ export function usePageBreadcrumbsQuery(
   pageId: string,
 ): UseQueryResult<Partial<IPage[]>, Error> {
   return useQuery({
-    queryKey: ["breadcrumbs", pageId],
+    queryKey: pageKeys.breadcrumbs(pageId),
     queryFn: () => getPageBreadcrumbs(pageId),
     enabled: !!pageId,
   });
@@ -332,10 +371,12 @@ export async function fetchAllAncestorChildren(
   // refresh (#159 #8), which must NOT receive the 30-min-cached children.
   opts?: { fresh?: boolean },
 ) {
-  // not using a hook here, so we can call it inside a useEffect hook
+  // not using a hook here, so we can call it inside a useEffect hook. Reuse the
+  // shared sidebarPagesQueryOptions (key + queryFn) so the offline warm path and
+  // this fetch never drift, but override staleTime for the `fresh` reconnect
+  // refresh (#159 #8), which must force a server refetch (staleTime 0).
   const response = await queryClient.fetchQuery({
-    queryKey: ["sidebar-pages", params],
-    queryFn: () => getAllSidebarPages(params),
+    ...sidebarPagesQueryOptions(params),
     staleTime: opts?.fresh ? 0 : 30 * 60 * 1000,
   });
 
@@ -345,7 +386,7 @@ export async function fetchAllAncestorChildren(
 
 export function useRecentChangesQuery(spaceId?: string) {
   return useInfiniteQuery({
-    queryKey: ["recent-changes", spaceId],
+    queryKey: pageKeys.recentChanges(spaceId),
     queryFn: ({ pageParam }) =>
       getRecentChanges({ spaceId, cursor: pageParam, limit: 15 }),
     initialPageParam: undefined as string | undefined,
@@ -416,12 +457,12 @@ export function invalidateOnCreatePage(data: Partial<IPage>) {
 
   let queryKey: QueryKey = null;
   if (data.parentPageId === null) {
-    queryKey = ["root-sidebar-pages", data.spaceId];
+    queryKey = pageKeys.rootSidebar(data.spaceId);
   } else {
-    queryKey = [
-      "sidebar-pages",
-      { pageId: data.parentPageId, spaceId: data.spaceId },
-    ];
+    queryKey = pageKeys.sidebar({
+      pageId: data.parentPageId,
+      spaceId: data.spaceId,
+    });
   }
 
   //update all sidebar pages
@@ -481,7 +522,7 @@ export function invalidateOnCreatePage(data: Partial<IPage>) {
 
     //update root sidebar pages haschildern
     const rootSideBarMatches = queryClient.getQueriesData({
-      queryKey: ["root-sidebar-pages", data.spaceId],
+      queryKey: pageKeys.rootSidebar(data.spaceId),
       exact: false,
     });
 
@@ -505,7 +546,7 @@ export function invalidateOnCreatePage(data: Partial<IPage>) {
 
   //update recent changes
   queryClient.invalidateQueries({
-    queryKey: ["recent-changes", data.spaceId],
+    queryKey: pageKeys.recentChanges(data.spaceId),
   });
 }
 
@@ -519,9 +560,9 @@ export function invalidateOnUpdatePage(
   invalidatePageTree();
   let queryKey: QueryKey = null;
   if (parentPageId === null) {
-    queryKey = ["root-sidebar-pages", spaceId];
+    queryKey = pageKeys.rootSidebar(spaceId);
   } else {
-    queryKey = ["sidebar-pages", { pageId: parentPageId, spaceId: spaceId }];
+    queryKey = pageKeys.sidebar({ pageId: parentPageId, spaceId: spaceId });
   }
   //update all sidebar pages
   queryClient.setQueryData<InfiniteData<IPagination<IPage>>>(
@@ -544,7 +585,7 @@ export function invalidateOnUpdatePage(
 
   //update recent changes
   queryClient.invalidateQueries({
-    queryKey: ["recent-changes", spaceId],
+    queryKey: pageKeys.recentChanges(spaceId),
   });
 }
 
@@ -559,8 +600,8 @@ export function updateCacheOnMovePage(
   // Remove page from old parent's cache
   const oldQueryKey =
     oldParentId === null
-      ? ["root-sidebar-pages", spaceId]
-      : ["sidebar-pages", { pageId: oldParentId, spaceId }];
+      ? pageKeys.rootSidebar(spaceId)
+      : pageKeys.sidebar({ pageId: oldParentId, spaceId });
 
   queryClient.setQueryData<InfiniteData<IPagination<IPage>>>(
     oldQueryKey,
@@ -580,7 +621,7 @@ export function updateCacheOnMovePage(
   if (oldParentId !== null) {
     const oldParentCache = queryClient.getQueryData<
       InfiniteData<IPagination<IPage>>
-    >(["sidebar-pages", { pageId: oldParentId, spaceId }]);
+    >(pageKeys.sidebar({ pageId: oldParentId, spaceId }));
 
     const remainingChildren =
       oldParentCache?.pages.flatMap((p) => p.items).length ?? 0;
@@ -618,8 +659,8 @@ export function updateCacheOnMovePage(
   // Add page to new parent's cache
   const newQueryKey =
     newParentId === null
-      ? ["root-sidebar-pages", spaceId]
-      : ["sidebar-pages", { pageId: newParentId, spaceId }];
+      ? pageKeys.rootSidebar(spaceId)
+      : pageKeys.sidebar({ pageId: newParentId, spaceId });
 
   queryClient.setQueryData<InfiniteData<IPagination<Partial<IPage>>>>(
     newQueryKey,

apps/client/src/features/page/tree/components/space-tree-node-menu.tsx

@@ -7,6 +7,7 @@ import { notifications } from "@mantine/notifications";
 import {
   IconArrowRight,
   IconClockHour4,
+  IconCloudDownload,
   IconCopy,
   IconDotsVertical,
   IconFileExport,
@@ -35,6 +36,12 @@ import {
   useToggleTemplateMutation,
   useToggleTemporaryMutation,
 } from "@/features/page-embed/queries/page-embed-query";
+import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
+import { getCollaborationUrl } from "@/lib/config.ts";
+import {
+  makePageAvailableOffline,
+  warmPageYdoc,
+} from "@/features/offline/make-offline";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
 import { treeModel } from "@/features/page/tree/model/tree-model";
 import { pageToTreeNode } from "@/features/page/tree/utils";
@@ -72,6 +79,45 @@ export function NodeMenu({ node, canEdit }: NodeMenuProps) {
   const isTemplate = !!node.isTemplate;
   const toggleTemporary = useToggleTemporaryMutation();
   const isTemporary = !!node.temporaryExpiresAt;
+  const { data: collabQuery } = useCollabToken();
+
+  const handleMakeAvailableOffline = async () => {
+    notifications.show({ message: t("Saving page for offline use...") });
+    try {
+      // Prefetch read queries so they get persisted to IndexedDB. The result
+      // reports whether every warm step succeeded.
+      const result = await makePageAvailableOffline({
+        pageId: node.id,
+        spaceId: node.spaceId,
+      });
+      // Best-effort: warm the page's Yjs document into IndexedDB.
+      await warmPageYdoc(node.id, getCollaborationUrl(), collabQuery?.token);
+
+      if (result.ok) {
+        notifications.show({ message: t("Page is now available offline") });
+      } else {
+        // Partial warm — the page may still be partly usable offline, but some
+        // queries failed to cache, so surface it as an error rather than a
+        // silent success.
+        notifications.show({
+          message: t("Failed to make page available offline"),
+          color: "red",
+        });
+      }
+    } catch (err) {
+      // makePageAvailableOffline no longer throws, but warmPageYdoc and other
+      // unexpected failures stay guarded here. Log the raw error and surface the
+      // real cause to the user instead of a bare generic string (AGENTS.md).
+      console.error("handleMakeAvailableOffline failed", err);
+      const reason =
+        (err as { response?: { data?: { message?: string } } })?.response?.data
+          ?.message ?? (err instanceof Error ? err.message : String(err));
+      notifications.show({
+        message: `${t("Failed to make page available offline")}: ${reason}`,
+        color: "red",
+      });
+    }
+  };
 
   const handleToggleTemplate = async () => {
     const next = !isTemplate;
@@ -228,6 +274,17 @@ export function NodeMenu({ node, canEdit }: NodeMenuProps) {
             {t("Export")}
           </Menu.Item>
 
+          <Menu.Item
+            leftSection={<IconCloudDownload size={16} />}
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              handleMakeAvailableOffline();
+            }}
+          >
+            {t("Make available offline")}
+          </Menu.Item>
+
           {canEdit && (
             <>
               <Menu.Item

apps/client/src/features/page/tree/hooks/use-tree-mutation.ts

@@ -15,7 +15,6 @@ import {
   useCreatePageMutation,
   useRemovePageMutation,
   useMovePageMutation,
-  useUpdatePageMutation,
   updateCacheOnMovePage,
 } from "@/features/page/queries/page-query.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
@@ -27,7 +26,6 @@ export type UseTreeMutation = {
     parentId: string | null,
     opts?: { temporary?: boolean },
   ) => Promise<void>;
-  handleRename: (id: string, name: string) => Promise<void>;
   handleDelete: (id: string) => Promise<void>;
 };
 
@@ -39,7 +37,6 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
   // children) and then immediately invokes a handler.
   const store = useStore();
   const createPageMutation = useCreatePageMutation();
-  const updatePageMutation = useUpdatePageMutation();
   const removePageMutation = useRemovePageMutation();
   const movePageMutation = useMovePageMutation();
   const navigate = useNavigate();
@@ -205,20 +202,6 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
     [spaceId, createPageMutation, setData, store, navigate, spaceSlug],
   );
 
-  const handleRename = useCallback(
-    async (id: string, name: string) => {
-      setData((prev) =>
-        treeModel.update(prev, id, { name } as Partial<SpaceTreeNode>),
-      );
-      try {
-        await updatePageMutation.mutateAsync({ pageId: id, title: name });
-      } catch (error) {
-        console.error("Error updating page title:", error);
-      }
-    },
-    [updatePageMutation, setData],
-  );
-
   const handleDelete = useCallback(
     async (id: string) => {
       const node = treeModel.find(
@@ -264,7 +247,7 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
     [removePageMutation, setData, store, pageSlug, navigate, spaceSlug],
   );
 
-  return { handleMove, handleCreate, handleRename, handleDelete };
+  return { handleMove, handleCreate, handleDelete };
 }
 
 function isPageInNode(node: SpaceTreeNode, pageSlug: string): boolean {

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

@@ -1,240 +0,0 @@
-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,14 +1,5 @@
-import {
-  Group,
-  Box,
-  Button,
-  TextInput,
-  Stack,
-  Textarea,
-  Divider,
-  Switch,
-} from "@mantine/core";
-import React, { useState } from "react";
+import { Group, Box, Button, TextInput, Stack, Textarea } from "@mantine/core";
+import React from "react";
 import { useForm } from "@mantine/form";
 import { zod4Resolver } from "mantine-form-zod-resolver";
 import { z } from "zod/v4";
@@ -38,37 +29,6 @@ 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: {
@@ -144,43 +104,6 @@ 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/queries/space-query.ts

@@ -1,5 +1,6 @@
 import {
   keepPreviousData,
+  queryOptions,
   useInfiniteQuery,
   useMutation,
   useQuery,
@@ -31,11 +32,37 @@ import { getRecentChanges } from "@/features/page/services/page-service.ts";
 import { useEffect } from "react";
 import { validate as isValidUuid } from "uuid";
 
+/**
+ * Centralized React Query key factories for space queries. The hooks below and
+ * the offline warm path (features/offline/make-offline.ts) share these so the
+ * runtime keys can never silently drift apart.
+ */
+export const spaceKeys = {
+  detail: (idOrSlug: string) => ["space", idOrSlug] as const,
+  list: (params?: QueryParams) => ["spaces", params] as const,
+  members: (spaceId: string, query?: string) =>
+    ["spaceMembers", spaceId, query] as const,
+};
+
+/**
+ * Shared queryOptions for fetching a space by id/slug. Both
+ * useGetSpaceBySlugQuery and the offline warm path consume this so the key,
+ * queryFn and staleTime stay identical. (`enabled` is intentionally omitted —
+ * prefetchQuery ignores it anyway and the warm path always passes a real id;
+ * the hook reapplies `enabled` itself.)
+ */
+export const spaceByIdQueryOptions = (spaceId: string) =>
+  queryOptions({
+    queryKey: spaceKeys.detail(spaceId),
+    queryFn: () => getSpaceById(spaceId),
+    staleTime: 5 * 60 * 1000,
+  });
+
 export function useGetSpacesQuery(
   params?: QueryParams,
 ): UseQueryResult<IPagination<ISpace>, Error> {
   return useQuery({
-    queryKey: ["spaces", params],
+    queryKey: spaceKeys.list(params),
     queryFn: () => getSpaces(params),
     placeholderData: keepPreviousData,
     refetchOnMount: true,
@@ -44,16 +71,16 @@ export function useGetSpacesQuery(
 
 export function useSpaceQuery(spaceId: string): UseQueryResult<ISpace, Error> {
   const query = useQuery({
-    queryKey: ["space", spaceId],
+    queryKey: spaceKeys.detail(spaceId),
     queryFn: () => getSpaceById(spaceId),
     enabled: !!spaceId,
   });
   useEffect(() => {
     if (query.data) {
       if (isValidUuid(spaceId)) {
-        queryClient.setQueryData(["space", query.data.slug], query.data);
+        queryClient.setQueryData(spaceKeys.detail(query.data.slug), query.data);
       } else {
-        queryClient.setQueryData(["space", query.data.id], query.data);
+        queryClient.setQueryData(spaceKeys.detail(query.data.id), query.data);
       }
     }
   }, [query.data]);
@@ -62,8 +89,11 @@ export function useSpaceQuery(spaceId: string): UseQueryResult<ISpace, Error> {
 }
 
 export const prefetchSpace = (spaceSlug: string, spaceId?: string) => {
+  // Note: intentionally NOT using spaceByIdQueryOptions here — that factory sets
+  // a 5min staleTime which would let this prefetch skip fetching fresh data;
+  // prefetchSpace must always refetch (default staleTime: 0).
   queryClient.prefetchQuery({
-    queryKey: ["space", spaceSlug],
+    queryKey: spaceKeys.detail(spaceSlug),
     queryFn: () => getSpaceById(spaceSlug),
   });
 
@@ -100,10 +130,8 @@ export function useGetSpaceBySlugQuery(
   spaceId: string,
 ): UseQueryResult<ISpace, Error> {
   return useQuery({
-    queryKey: ["space", spaceId],
-    queryFn: () => getSpaceById(spaceId),
+    ...spaceByIdQueryOptions(spaceId),
     enabled: !!spaceId,
-    staleTime: 5 * 60 * 1000,
   });
 }
 
@@ -116,14 +144,16 @@ export function useUpdateSpaceMutation() {
     onSuccess: (data, variables) => {
       notifications.show({ message: t("Space updated successfully") });
 
-      const space = queryClient.getQueryData([
-        "space",
-        variables.spaceId,
-      ]) as ISpace;
+      const space = queryClient.getQueryData(
+        spaceKeys.detail(variables.spaceId),
+      ) as ISpace;
       if (space) {
         const updatedSpace = { ...space, ...data };
-        queryClient.setQueryData(["space", variables.spaceId], updatedSpace);
-        queryClient.setQueryData(["space", data.slug], updatedSpace);
+        queryClient.setQueryData(
+          spaceKeys.detail(variables.spaceId),
+          updatedSpace,
+        );
+        queryClient.setQueryData(spaceKeys.detail(data.slug), updatedSpace);
       }
 
       queryClient.invalidateQueries({
@@ -148,7 +178,7 @@ export function useDeleteSpaceMutation() {
 
       if (variables.slug) {
         queryClient.removeQueries({
-          queryKey: ["space", variables.slug],
+          queryKey: spaceKeys.detail(variables.slug),
           exact: true,
         });
       }
@@ -156,7 +186,7 @@ export function useDeleteSpaceMutation() {
       // Remove space-specific queries
       if (variables.id) {
         queryClient.removeQueries({
-          queryKey: ["space", variables.id],
+          queryKey: spaceKeys.detail(variables.id),
           exact: true,
         });
 
@@ -196,7 +226,7 @@ export function useSpaceMembersInfiniteQuery(
   query?: string,
 ) {
   return useInfiniteQuery({
-    queryKey: ["spaceMembers", spaceId, query],
+    queryKey: spaceKeys.members(spaceId, query),
     queryFn: ({ pageParam }) =>
       getSpaceMembers(spaceId, { cursor: pageParam, limit: 50, query }),
     enabled: !!spaceId,

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

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

apps/client/src/features/user/hooks/use-current-user.ts

@@ -2,9 +2,19 @@ import { useQuery, UseQueryResult } from "@tanstack/react-query";
 import { getMyInfo } from "@/features/user/services/user-service";
 import { ICurrentUser } from "@/features/user/types/user.types";
 
+/**
+ * Centralized React Query key factory for current-user queries. This hook and
+ * the offline warm path (features/offline/make-offline.ts) share it so the
+ * runtime key can never silently drift, and the OFFLINE_PERSIST_ROOTS guard
+ * test can assert the persisted "currentUser" root maps to a real factory.
+ */
+export const userKeys = {
+  currentUser: () => ["currentUser"] as const,
+};
+
 export default function useCurrentUser(): UseQueryResult<ICurrentUser> {
   return useQuery({
-    queryKey: ["currentUser"],
+    queryKey: userKeys.currentUser(),
     queryFn: async () => {
       return await getMyInfo();
     },

apps/client/src/features/user/user-provider.test.tsx

@@ -0,0 +1,118 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import { MemoryRouter } from "react-router-dom";
+import { HelmetProvider } from "react-helmet-async";
+
+// Control useCurrentUser per test; stub the rest of UserProvider's network/
+// socket dependencies so we only exercise its render-gating logic.
+const h = vi.hoisted(() => ({ useCurrentUser: vi.fn() }));
+
+vi.mock("@/features/user/hooks/use-current-user", () => ({
+  default: h.useCurrentUser,
+}));
+vi.mock("@/features/auth/queries/auth-query.tsx", () => ({
+  useCollabToken: () => ({ data: undefined }),
+}));
+vi.mock("@/features/websocket/use-query-subscription.ts", () => ({
+  useQuerySubscription: () => {},
+}));
+vi.mock("@/features/websocket/use-tree-socket.ts", () => ({
+  useTreeSocket: () => {},
+}));
+vi.mock("@/features/notification/hooks/use-notification-socket.ts", () => ({
+  useNotificationSocket: () => {},
+}));
+vi.mock("@/main.tsx", () => ({ queryClient: {} }));
+vi.mock("@/features/user/connect-resync.ts", () => ({
+  makeConnectHandler: () => () => {},
+}));
+vi.mock("socket.io-client", () => ({
+  io: () => ({ on: vi.fn(), disconnect: vi.fn() }),
+}));
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (k: string) => k,
+    i18n: {
+      changeLanguage: vi.fn(),
+      language: "en-US",
+      resolvedLanguage: "en-US",
+    },
+  }),
+}));
+
+import { UserProvider } from "./user-provider";
+
+const networkError = { message: "Network Error" }; // axios network error: no `response`
+
+function renderProvider() {
+  return render(
+    <HelmetProvider>
+      <MemoryRouter>
+        <MantineProvider>
+          <UserProvider>
+            <div data-testid="app-child">app content</div>
+          </UserProvider>
+        </MantineProvider>
+      </MemoryRouter>
+    </HelmetProvider>,
+  );
+}
+
+beforeEach(() => {
+  h.useCurrentUser.mockReset();
+});
+
+describe("UserProvider offline render-gating", () => {
+  it("renders the app (cached children) when useCurrentUser errors offline but a cached user exists", () => {
+    // Offline reload: the persisted ['currentUser'] cache hydrates `data`, but
+    // the background POST /api/users/me refetch fails as a network error.
+    h.useCurrentUser.mockReturnValue({
+      data: {
+        user: { id: "u1", locale: "en" },
+        workspace: { id: "w1" },
+      },
+      isLoading: false,
+      error: networkError,
+      isError: true,
+    });
+
+    renderProvider();
+
+    // The cached app must render — NOT a blank fragment (#237/#238).
+    expect(screen.getByTestId("app-child")).toBeDefined();
+    expect(screen.queryByText("You're offline")).toBeNull();
+  });
+
+  it("renders the offline fallback (not a blank fragment) when erroring with no cached user", () => {
+    h.useCurrentUser.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      error: networkError,
+      isError: true,
+    });
+
+    const { container } = renderProvider();
+
+    // Previously this returned `<></>` — a blank white screen. Now it must show
+    // an explicit offline fallback.
+    expect(screen.getByText("You're offline")).toBeDefined();
+    expect(screen.queryByTestId("app-child")).toBeNull();
+    expect(container.textContent?.length).toBeGreaterThan(0);
+  });
+
+  it("renders the app normally on a successful currentUser load", () => {
+    h.useCurrentUser.mockReturnValue({
+      data: {
+        user: { id: "u1", locale: "en" },
+        workspace: { id: "w1" },
+      },
+      isLoading: false,
+      error: null,
+      isError: false,
+    });
+
+    renderProvider();
+    expect(screen.getByTestId("app-child")).toBeDefined();
+  });
+});

apps/client/src/features/user/user-provider.tsx

@@ -11,6 +11,7 @@ import { useTreeSocket } from "@/features/websocket/use-tree-socket.ts";
 import { useNotificationSocket } from "@/features/notification/hooks/use-notification-socket.ts";
 import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
 import { Error404 } from "@/components/ui/error-404.tsx";
+import { OfflineFallback } from "@/features/offline/offline-fallback.tsx";
 import { queryClient } from "@/main.tsx";
 import { makeConnectHandler } from "@/features/user/connect-resync.ts";
 
@@ -70,14 +71,30 @@ export function UserProvider({ children }: React.PropsWithChildren) {
     document.documentElement.lang = i18n.resolvedLanguage || i18n.language || "en-US";
   }, [i18n.language, i18n.resolvedLanguage]);
 
-  if (isLoading) return <></>;
+  // First load with no cached user yet: render nothing briefly while the
+  // persisted ['currentUser'] cache hydrates (avoids flashing the offline
+  // fallback before restore). Once we have a user we render the app even if a
+  // refetch is still in flight.
+  if (isLoading && !data) return <></>;
 
   if (isError && error?.["response"]?.status === 404) {
     return <Error404 />;
   }
 
+  // We have a (possibly cached/stale) user — render the app. Offline, the
+  // POST /api/users/me refetch fails as a network error, but the persisted/
+  // hydrated user is enough to render the cached UI. Previously `if (error)
+  // return <></>` blanked every authenticated route on an offline reload even
+  // though the cached data was present (#237/#238).
+  if (data) {
+    return <>{children}</>;
+  }
+
+  // No user AND an error (offline cold boot of a page never warmed for offline,
+  // or no persisted cache to restore): show an explicit offline fallback rather
+  // than a blank white screen.
   if (error) {
-    return <></>;
+    return <OfflineFallback />;
   }
 
   return <>{children}</>;

apps/client/src/main.tsx

@@ -11,7 +11,8 @@ import { MantineProvider } from "@mantine/core";
 import { BrowserRouter } from "react-router-dom";
 import { ModalsProvider } from "@mantine/modals";
 import { Notifications } from "@mantine/notifications";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { QueryClient } from "@tanstack/react-query";
+import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
 import { HelmetProvider } from "react-helmet-async";
 import "./i18n";
 import { PostHogProvider } from "posthog-js/react";
@@ -21,6 +22,13 @@ import {
   isCloud,
   isPostHogEnabled,
 } from "@/lib/config.ts";
+import {
+  queryPersister,
+  shouldDehydrateOfflineQuery,
+} from "@/features/offline/query-persister";
+import { registerOfflineMutationDefaults } from "@/features/offline/offline-mutations";
+import { PwaUpdatePrompt } from "@/pwa/pwa-update-prompt";
+import { isCapacitorNativePlatform } from "@/pwa/is-capacitor";
 import posthog from "posthog-js";
 
 export const queryClient = new QueryClient({
@@ -30,10 +38,18 @@ export const queryClient = new QueryClient({
       refetchOnWindowFocus: false,
       retry: false,
       staleTime: 5 * 60 * 1000,
+      // Keep cached read data around long enough to be persisted/restored for offline use.
+      gcTime: 1000 * 60 * 60 * 24,
     },
   },
 });
 
+// Register default mutationFns for the offline-relevant structural mutations so
+// a paused mutation restored from IndexedDB after an offline reload still has a
+// mutationFn and is replayed by resumePausedMutations() on reconnect (instead
+// of silently no-op'ing and dropping the offline create/move/comment).
+registerOfflineMutationDefaults(queryClient);
+
 if (isCloud() && isPostHogEnabled) {
   posthog.init(getPostHogKey(), {
     api_host: getPostHogHost(),
@@ -50,15 +66,34 @@ root.render(
   <BrowserRouter>
     <MantineProvider theme={theme} cssVariablesResolver={mantineCssResolver}>
       <ModalsProvider>
-        <QueryClientProvider client={queryClient}>
+        <PersistQueryClientProvider
+          client={queryClient}
+          persistOptions={{
+            persister: queryPersister,
+            maxAge: 1000 * 60 * 60 * 24,
+            buster: APP_VERSION,
+            dehydrateOptions: {
+              shouldDehydrateQuery: shouldDehydrateOfflineQuery,
+            },
+          }}
+        >
           <Notifications position="bottom-center" limit={3} zIndex={10000} />
+          {/* Skip SW registration inside the Capacitor native WebView — the
+              native shell serves assets itself; a browser SW would conflict. */}
+          {!isCapacitorNativePlatform() && <PwaUpdatePrompt />}
           <HelmetProvider>
             <PostHogProvider client={posthog}>
               <App />
             </PostHogProvider>
           </HelmetProvider>
-        </QueryClientProvider>
+        </PersistQueryClientProvider>
       </ModalsProvider>
     </MantineProvider>
   </BrowserRouter>,
 );
+
+// Service worker registration is owned by <PwaUpdatePrompt /> above (via
+// vite-plugin-pwa's useRegisterSW: Workbox precache + prompt-based updates,
+// and skipped inside the Capacitor native WebView). The earlier hand-written
+// /sw.js registration from the mobile bootstrap was removed here to avoid a
+// double registration / competing service worker.

apps/client/src/pwa/is-capacitor.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { isCapacitorNativePlatform } from "./is-capacitor";
+
+describe("isCapacitorNativePlatform", () => {
+  afterEach(() => {
+    // Keep tests isolated from each other and from the rest of the suite.
+    delete (globalThis as any).Capacitor;
+  });
+
+  it("returns false when Capacitor is undefined", () => {
+    expect(isCapacitorNativePlatform()).toBe(false);
+  });
+
+  it("uses isNativePlatform() when it is a function", () => {
+    (globalThis as any).Capacitor = { isNativePlatform: () => true };
+    expect(isCapacitorNativePlatform()).toBe(true);
+
+    (globalThis as any).Capacitor = { isNativePlatform: () => false };
+    expect(isCapacitorNativePlatform()).toBe(false);
+  });
+
+  it("falls back to the boolean property when isNativePlatform is not a function", () => {
+    (globalThis as any).Capacitor = { isNativePlatform: true };
+    expect(isCapacitorNativePlatform()).toBe(true);
+
+    (globalThis as any).Capacitor = { isNativePlatform: false };
+    expect(isCapacitorNativePlatform()).toBe(false);
+  });
+
+  it("returns false when reading Capacitor throws (try/catch)", () => {
+    Object.defineProperty(globalThis, "Capacitor", {
+      configurable: true,
+      get() {
+        throw new Error("boom");
+      },
+    });
+    expect(isCapacitorNativePlatform()).toBe(false);
+  });
+});

apps/client/src/pwa/is-capacitor.ts

@@ -0,0 +1,23 @@
+/**
+ * Detects whether the client is running inside a Capacitor native WebView
+ * (native iOS/Android shell from the feature/mobile-app-bootstrap branch).
+ *
+ * This is a pure runtime check against the global `Capacitor` object that the
+ * native bridge injects — no `@capacitor/*` dependency is added. On the plain
+ * browser / installed-PWA path `window.Capacitor` is undefined, so this returns
+ * false and the Workbox service worker registers normally.
+ *
+ * Inside the native WebView the SW must NOT register: it would layer a redundant
+ * (and conflicting) cache over Capacitor's own asset serving and interfere with
+ * the native auth/CORS flow.
+ */
+export function isCapacitorNativePlatform(): boolean {
+  try {
+    const cap = (globalThis as any)?.Capacitor;
+    return !!(cap && typeof cap.isNativePlatform === "function"
+      ? cap.isNativePlatform()
+      : cap?.isNativePlatform);
+  } catch {
+    return false;
+  }
+}

apps/client/src/pwa/pwa-update-prompt.tsx

@@ -0,0 +1,59 @@
+import { useEffect } from "react";
+import { Button } from "@mantine/core";
+import { notifications } from "@mantine/notifications";
+import { useTranslation } from "react-i18next";
+import { useRegisterSW } from "virtual:pwa-register/react";
+
+// Stable notification id so we can show/hide a single update prompt.
+const UPDATE_NOTIFICATION_ID = "pwa-update-available";
+
+/**
+ * Listens for a waiting service worker and surfaces a Mantine notification
+ * prompting the user to reload into the new version.
+ *
+ * Must be mounted inside the Mantine provider subtree (Notifications must be
+ * available). Renders nothing itself.
+ */
+export function PwaUpdatePrompt() {
+  const { t } = useTranslation();
+
+  const {
+    needRefresh: [needRefresh],
+    updateServiceWorker,
+  } = useRegisterSW({
+    onRegisterError(error) {
+      // Best-effort: a failed registration must not break the app.
+      console.error("Service worker registration error:", error);
+    },
+  });
+
+  useEffect(() => {
+    if (!needRefresh) return;
+
+    notifications.show({
+      id: UPDATE_NOTIFICATION_ID,
+      title: t("Update available"),
+      message: (
+        <Button
+          size="xs"
+          variant="light"
+          mt="xs"
+          onClick={() => updateServiceWorker(true)}
+        >
+          {t("Reload")}
+        </Button>
+      ),
+      autoClose: false,
+      withCloseButton: true,
+    });
+
+    // Hide the notification when the prompt is no longer needed / on cleanup.
+    return () => {
+      notifications.hide(UPDATE_NOTIFICATION_ID);
+    };
+  }, [needRefresh, t, updateServiceWorker]);
+
+  return null;
+}
+
+export default PwaUpdatePrompt;

apps/client/src/pwa/sw-strategy.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { isApiPath, isCollabOrSocketPath } from "./sw-strategy";
+
+describe("isApiPath", () => {
+  it("matches the /api segment and its subtree", () => {
+    expect(isApiPath("/api")).toBe(true);
+    expect(isApiPath("/api/")).toBe(true);
+    expect(isApiPath("/api/pages")).toBe(true);
+  });
+
+  it("does not over-match sibling paths", () => {
+    expect(isApiPath("/apidocs")).toBe(false);
+    expect(isApiPath("/apixyz")).toBe(false);
+    expect(isApiPath("/")).toBe(false);
+    expect(isApiPath("/pages")).toBe(false);
+  });
+});
+
+describe("isCollabOrSocketPath", () => {
+  it("matches the /collab and /socket.io segments and their subtrees", () => {
+    expect(isCollabOrSocketPath("/collab")).toBe(true);
+    expect(isCollabOrSocketPath("/collab/x")).toBe(true);
+    expect(isCollabOrSocketPath("/socket.io")).toBe(true);
+    expect(isCollabOrSocketPath("/socket.io/abc")).toBe(true);
+  });
+
+  it("does not over-match sibling paths", () => {
+    expect(isCollabOrSocketPath("/collaborators")).toBe(false);
+    expect(isCollabOrSocketPath("/collabx")).toBe(false);
+    expect(isCollabOrSocketPath("/socket.iox")).toBe(false);
+  });
+});

apps/client/src/pwa/sw-strategy.ts

@@ -0,0 +1,32 @@
+/**
+ * Canonical service-worker routing predicates.
+ *
+ * IMPORTANT: With vite-plugin-pwa using Workbox `generateSW`, the
+ * `runtimeCaching[].urlPattern` functions are serialized standalone into the
+ * generated service worker and CANNOT reference imported symbols. The matching
+ * logic is therefore duplicated as inline regex literals in
+ * apps/client/vite.config.ts. This module is the testable source of truth, and
+ * the two MUST be kept in sync. This duplication is intentional and is the
+ * documented Workbox limitation.
+ *
+ * Matching is anchored to a path SEGMENT boundary (`^/<seg>(/|$)`) so that
+ * sibling paths like `/apidocs`, `/collaborators`, `/socket.iox` are NOT
+ * wrongly treated as API/realtime traffic.
+ */
+
+/**
+ * True when `pathname` is the `/api` segment or anything beneath it.
+ * `/api` and `/api/...` -> true; `/apidocs`, `/apixyz` -> false.
+ */
+export function isApiPath(pathname: string): boolean {
+  return /^\/api(\/|$)/.test(pathname);
+}
+
+/**
+ * True when `pathname` is the `/collab` or `/socket.io` segment (or beneath it).
+ * `/collab`, `/collab/x`, `/socket.io`, `/socket.io/abc` -> true;
+ * `/collaborators`, `/collabx`, `/socket.iox` -> false.
+ */
+export function isCollabOrSocketPath(pathname: string): boolean {
+  return /^\/(collab|socket\.io)(\/|$)/.test(pathname);
+}

apps/client/src/vite-env.d.ts

@@ -1,2 +1,4 @@
 /// <reference types="vite/client" />
+/// <reference types="vite-plugin-pwa/react" />
+/// <reference types="vite-plugin-pwa/info" />
 declare const APP_VERSION: string

apps/client/vite.config.ts

@@ -1,5 +1,6 @@
 import { defineConfig, loadEnv } from "vite";
 import react from "@vitejs/plugin-react";
+import { VitePWA } from "vite-plugin-pwa";
 import * as path from "path";
 import { execSync } from "node:child_process";
 
@@ -53,7 +54,51 @@ export default defineConfig(({ mode }) => {
       },
       APP_VERSION: JSON.stringify(resolveAppVersion(envPath)),
     },
-    plugins: [react()],
+    plugins: [
+      react(),
+      VitePWA({
+        registerType: "prompt",
+        injectRegister: null,
+        strategies: "generateSW",
+        manifest: false,
+        workbox: {
+          globPatterns: ["**/*.{js,css,html,svg,png,ico,woff2,json}"],
+          navigateFallback: "index.html",
+          // Segment-anchored (`^/<seg>(/|$)`) so navigation requests to these
+          // segments are consistently excluded from the SPA fallback, mirroring
+          // the runtimeCaching urlPattern regexes below.
+          //
+          // `/share`, `/mcp`, and `/robots.txt` mirror the server static-serve
+          // exclude list (apps/server/src/main.ts setGlobalPrefix `exclude`):
+          // robots.txt, the SEO/OG/analytics-injected public share HTML, and the
+          // embedded MCP endpoint are served by server controllers, so the SW must
+          // never shadow them with the precached index.html app shell (doing so
+          // would break SEO and MCP).
+          navigateFallbackDenylist: [
+            /^\/api(\/|$)/,
+            /^\/collab(\/|$)/,
+            /^\/socket\.io(\/|$)/,
+            /^\/share(\/|$)/,
+            /^\/mcp(\/|$)/,
+            /^\/robots\.txt$/,
+          ],
+          cleanupOutdatedCaches: true,
+          clientsClaim: true,
+          // The urlPattern regexes below mirror apps/client/src/pwa/sw-strategy.ts
+          // and MUST be kept in sync with it. Workbox `generateSW` serializes these
+          // functions standalone into the generated service worker, so they cannot
+          // import the module — the matching logic is intentionally duplicated as
+          // self-contained inline regex literals anchored to a path segment boundary.
+          runtimeCaching: [
+            { urlPattern: ({ url }) => /^\/(collab|socket\.io)(\/|$)/.test(url.pathname), handler: "NetworkOnly" },
+            // All /api stays network-only; offline reads come from the persisted
+            // React Query cache (IndexedDB) + y-indexeddb, not the SW HTTP cache.
+            { urlPattern: ({ url }) => /^\/api(\/|$)/.test(url.pathname), handler: "NetworkOnly" },
+          ],
+        },
+        devOptions: { enabled: false },
+      }),
+    ],
     build: {
       rolldownOptions: {
         output: {

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 && pnpm --filter @docmost/git-sync build && pnpm --filter @docmost/mcp build",
+    "pretest": "pnpm --filter @docmost/editor-ext build",
     "test": "jest",
     "test:int": "jest --config test/jest-integration.json",
     "test:watch": "jest --watch",
@@ -41,7 +41,6 @@
     "@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",
@@ -65,6 +64,7 @@
     "@nestjs/platform-fastify": "^11.1.19",
     "@nestjs/platform-socket.io": "^11.1.19",
     "@nestjs/schedule": "^6.1.3",
+    "@nestjs/swagger": "^11.2.0",
     "@nestjs/terminus": "^11.1.1",
     "@nestjs/throttler": "^6.5.0",
     "@nestjs/websockets": "^11.1.19",
@@ -126,7 +126,6 @@
     "typesense": "^3.0.5",
     "undici": "7.24.0",
     "ws": "^8.20.1",
-    "yaml": "^2.8.3",
     "yauzl": "^3.2.1",
     "zod": "^4.3.6"
   },
@@ -190,12 +189,7 @@
           ]
         }
       ],
-      "^.+\\.(t|j)sx?$": [
-        "ts-jest",
-        {
-          "isolatedModules": true
-        }
-      ]
+      "^.+\\.(t|j)sx?$": "ts-jest"
     },
     "transformIgnorePatterns": [
       "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0)(@|/))"
@@ -205,17 +199,11 @@
     ],
     "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",
-      "^@docmost/git-sync$": "<rootDir>/../../../packages/git-sync/src/index.ts",
-      "^@docmost/git-sync/(.*)$": "<rootDir>/../../../packages/git-sync/src/$1",
-      "^(\\.{1,2}/.*)\\.js$": "$1"
+      "^src/(.*)$": "<rootDir>/$1"
     }
   }
 }

apps/server/src/app.module.ts

@@ -28,8 +28,6 @@ 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';
 
@@ -91,8 +89,6 @@ try {
     TelemetryModule,
     ThrottleModule,
     McpModule,
-    GitSyncModule,
-    SandboxModule,
     AiModule,
     AiChatModule,
     ...enterpriseModules,

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

@@ -24,7 +24,9 @@ import { CollabWsAdapter } from './adapter/collab-ws.adapter';
 import {
   CollaborationHandler,
   CollabEventHandlers,
+  writeTitleFragment,
 } from './collaboration.handler';
+import { User } from '@docmost/db/types/entity.types';
 
 @Injectable()
 export class CollaborationGateway {
@@ -150,42 +152,42 @@ export class CollaborationGateway {
   }
 
   /**
-   * 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.
+   * Write a new page title INTO the page's Yjs 'title' fragment, Redis-INDEPENDENT.
    *
-   * 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.
+   * Unlike the Redis-routed `handleYjsEvent` path — which routes through
+   * `redisSync?.handleEvent` and SILENTLY no-ops when Redis is disabled
+   * (COLLAB_DISABLE_REDIS=true → redisSync === null) — this goes straight
+   * through the local Hocuspocus `openDirectConnection`. The title sync
+   * therefore works in BOTH single-process (no Redis) and Redis-clustered
+   * deployments.
    *
-   * 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.
+   * openDirectConnection loads the doc from persistence when no editor is
+   * connected, so this works whether or not an editor is currently open: the
+   * clear+reseed lands on the loaded doc and is persisted by onStoreDocument.
+   *
+   * Provenance: when the caller is the agent, the actor/aiChatId are threaded
+   * into the connection `context` so onStoreDocument sees `context.actor ===
+   * 'agent'` for the resulting title store (mirrors the body/REST path). The
+   * resulting title store is usually a no-op anyway — PageService already wrote
+   * the same title to the page.title column, so onStoreDocument's
+   * `titleText !== page.title` guard skips the column write — but we wire the
+   * context for correctness regardless.
    */
-  async writePageBody(
-    documentName: string,
-    payload: {
-      prosemirrorJson: unknown;
-      baseProsemirrorJson?: unknown;
-      userId: string;
-    },
+  async writePageTitle(
+    pageId: string,
+    title: string,
+    context?: { user?: User; actor?: string; aiChatId?: string },
   ): Promise<void> {
-    if (this.redisSync) {
-      await this.handleYjsEvent(
-        'gitSyncWriteBody',
-        documentName,
-        payload as any,
-      );
-      return;
+    const documentName = `page.${pageId}`;
+    const connection = await this.hocuspocus.openDirectConnection(
+      documentName,
+      context ?? {},
+    );
+    try {
+      await connection.transact((doc) => writeTitleFragment(doc, title));
+    } finally {
+      await connection.disconnect();
     }
-    await this.collabEventsService
-      .getHandlers(this.hocuspocus)
-      .gitSyncWriteBody(documentName, payload as any);
   }
 
   /*

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

@@ -1,262 +0,0 @@
-// 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.spec.ts

@@ -0,0 +1,139 @@
+import * as Y from 'yjs';
+import { TiptapTransformer } from '@hocuspocus/transformer';
+import { writeTitleFragment } from './collaboration.handler';
+import { CollaborationGateway } from './collaboration.gateway';
+import {
+  buildTitleSeedYdoc,
+  jsonToText,
+  tiptapExtensions,
+} from './collaboration.util';
+
+// Read the plain text held in the doc's 'title' XmlFragment, the same way
+// PersistenceExtension.onStoreDocument extracts it before writing page.title.
+const readTitleText = (doc: Y.Doc): string => {
+  const titleJson = TiptapTransformer.fromYdoc(doc, 'title');
+  return titleJson ? jsonToText(titleJson).trim() : '';
+};
+
+describe('writeTitleFragment — the clear+seed title write (Bug 1)', () => {
+  it('replaces an OLD title fragment with EXACTLY the new title (no duplication)', () => {
+    // Seed the doc's 'title' fragment with an OLD title, like a real page.
+    const doc = new Y.Doc();
+    Y.applyUpdate(doc, Y.encodeStateAsUpdate(buildTitleSeedYdoc('Old Title')));
+    expect(readTitleText(doc)).toBe('Old Title');
+
+    writeTitleFragment(doc, 'New Title');
+
+    // The fragment must contain EXACTLY the new title — not "Old TitleNew Title"
+    // (append) or "New TitleNew Title" (duplication). A single heading node.
+    expect(readTitleText(doc)).toBe('New Title');
+
+    const titleJson = TiptapTransformer.fromYdoc(doc, 'title') as any;
+    expect(titleJson.content).toHaveLength(1);
+    expect(titleJson.content[0].type).toBe('heading');
+  });
+
+  it('seeds the title fragment when it started empty', () => {
+    const doc = new Y.Doc();
+    // Force the 'title' fragment to exist but be empty.
+    doc.getXmlFragment('title');
+    expect(readTitleText(doc)).toBe('');
+
+    writeTitleFragment(doc, 'First Title');
+
+    expect(readTitleText(doc)).toBe('First Title');
+  });
+
+  it('does not corrupt the body when rewriting the title', () => {
+    // A doc with both a body and an old title; the body must survive untouched.
+    const doc = new Y.Doc();
+    const bodyDoc = TiptapTransformer.toYdoc(
+      {
+        type: 'doc',
+        content: [
+          { type: 'paragraph', content: [{ type: 'text', text: 'body text' }] },
+        ],
+      },
+      'default',
+      tiptapExtensions,
+    );
+    Y.applyUpdate(doc, Y.encodeStateAsUpdate(bodyDoc));
+    Y.applyUpdate(doc, Y.encodeStateAsUpdate(buildTitleSeedYdoc('Old')));
+
+    writeTitleFragment(doc, 'New');
+
+    expect(readTitleText(doc)).toBe('New');
+    const bodyJson = TiptapTransformer.fromYdoc(doc, 'default');
+    expect(jsonToText(bodyJson)).toContain('body text');
+  });
+});
+
+describe('CollaborationGateway.writePageTitle — Redis-independent path', () => {
+  // Build a gateway with only its hocuspocus.openDirectConnection stubbed; the
+  // method must drive the clear+seed through that direct connection (NOT through
+  // redisSync), so the title write survives COLLAB_DISABLE_REDIS.
+  const makeGateway = (doc: Y.Doc) => {
+    const disconnect = jest.fn().mockResolvedValue(undefined);
+    const transact = jest.fn(async (fn: (d: Y.Doc) => void) => {
+      fn(doc);
+    });
+    const openDirectConnection = jest
+      .fn()
+      .mockResolvedValue({ transact, disconnect });
+
+    const gateway = Object.create(CollaborationGateway.prototype);
+    // redisSync is intentionally null — this is the no-Redis scenario.
+    gateway.redisSync = null;
+    gateway.hocuspocus = { openDirectConnection } as any;
+
+    return { gateway, openDirectConnection, transact, disconnect };
+  };
+
+  it('writes the new title via openDirectConnection and disconnects', async () => {
+    const doc = new Y.Doc();
+    Y.applyUpdate(doc, Y.encodeStateAsUpdate(buildTitleSeedYdoc('Old Title')));
+
+    const { gateway, openDirectConnection, disconnect } = makeGateway(doc);
+
+    await gateway.writePageTitle('page-1', 'New Title', { user: { id: 'u1' } });
+
+    expect(openDirectConnection).toHaveBeenCalledWith(
+      'page.page-1',
+      expect.objectContaining({ user: { id: 'u1' } }),
+    );
+    expect(readTitleText(doc)).toBe('New Title');
+    expect(disconnect).toHaveBeenCalledTimes(1);
+  });
+
+  it('threads agent provenance into the connection context', async () => {
+    const doc = new Y.Doc();
+    const { gateway, openDirectConnection } = makeGateway(doc);
+
+    await gateway.writePageTitle('page-1', 'Agent Title', {
+      user: { id: 'u1' },
+      actor: 'agent',
+      aiChatId: 'chat-1',
+    });
+
+    expect(openDirectConnection).toHaveBeenCalledWith(
+      'page.page-1',
+      expect.objectContaining({ actor: 'agent', aiChatId: 'chat-1' }),
+    );
+  });
+
+  it('disconnects even when the transaction throws', async () => {
+    const disconnect = jest.fn().mockResolvedValue(undefined);
+    const openDirectConnection = jest.fn().mockResolvedValue({
+      transact: jest.fn().mockRejectedValue(new Error('boom')),
+      disconnect,
+    });
+    const gateway = Object.create(CollaborationGateway.prototype);
+    gateway.redisSync = null;
+    gateway.hocuspocus = { openDirectConnection } as any;
+
+    await expect(
+      gateway.writePageTitle('page-1', 'X', {}),
+    ).rejects.toThrow('boom');
+    expect(disconnect).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -2,21 +2,47 @@ import { Injectable, Logger } from '@nestjs/common';
 import { Hocuspocus, Document } from '@hocuspocus/server';
 import { TiptapTransformer } from '@hocuspocus/transformer';
 import {
+  buildTitleSeedYdoc,
   prosemirrorNodeToYElement,
   tiptapExtensions,
 } from './collaboration.util';
 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']
 >;
 
+/**
+ * Clear+reseed the 'title' XmlFragment of `doc` so it holds EXACTLY `title`.
+ *
+ * Used by the gateway's direct `writePageTitle` method to write a new page
+ * title INTO the page's Yjs 'title' fragment. The title lives in the same
+ * Y.Doc as the body; onStoreDocument extracts it on every save, so a REST/MCP
+ * rename that only updated the page.title DB column would be reverted on the
+ * next collaborative save unless the Yjs 'title' fragment is kept in sync.
+ * The whole fragment is replaced (no merge/append),
+ * mirroring the 'replace' body path: the new title fully supersedes the old.
+ *
+ * DELIBERATE TRADE-OFF: because this does a FULL clear+replace of the 'title'
+ * fragment, a REST/MCP rename arriving while a user is actively editing the
+ * title in an open editor WILL overwrite that in-progress edit. This is
+ * acceptable — the title is a short, rarely-concurrently-edited field — and is
+ * preferable to leaving a stale Yjs title that onStoreDocument would revert the
+ * DB column to on the next save.
+ */
+export function writeTitleFragment(doc: Y.Doc, title: string): void {
+  const titleFragment = doc.getXmlFragment('title');
+
+  if (titleFragment.length > 0) {
+    titleFragment.delete(0, titleFragment.length);
+  }
+
+  const newTitleDoc = buildTitleSeedYdoc(title);
+  Y.applyUpdate(doc, Y.encodeStateAsUpdate(newTitleDoc));
+}
+
 @Injectable()
 export class CollaborationHandler {
   private readonly logger = new Logger(CollaborationHandler.name);
@@ -116,130 +142,9 @@ 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.spec.ts

@@ -1,9 +1,12 @@
 import * as Y from 'yjs';
+import { TiptapTransformer } from '@hocuspocus/transformer';
 import {
   getPageId,
   isEmptyParagraphDoc,
   jsonToNode,
   prosemirrorNodeToYElement,
+  buildTitleSeedYdoc,
+  jsonToText,
 } from './collaboration.util';
 import { Node } from '@tiptap/pm/model';
 
@@ -241,3 +244,43 @@ describe('prosemirrorNodeToYElement', () => {
     expect(element.get(1).get(0).toString()).toBe('two');
   });
 });
+
+describe('buildTitleSeedYdoc', () => {
+  it('builds a level-1 heading carrying the title text', () => {
+    const doc = buildTitleSeedYdoc('Hello World');
+    const json: any = TiptapTransformer.fromYdoc(doc, 'title');
+
+    const first = json.content?.[0];
+    expect(first.type).toBe('heading');
+    expect(first.attrs.level).toBe(1);
+    expect(jsonToText(json).trim()).toBe('Hello World');
+  });
+
+  it('produces a non-empty title fragment for a non-empty title', () => {
+    const doc = buildTitleSeedYdoc('Some Title');
+    expect(doc.get('title', Y.XmlFragment).length).toBeGreaterThan(0);
+  });
+
+  it('produces a heading with no text child for an empty title', () => {
+    const doc = buildTitleSeedYdoc('');
+    const json: any = TiptapTransformer.fromYdoc(doc, 'title');
+
+    const first = json.content?.[0];
+    expect(first.type).toBe('heading');
+    // No text content for an empty title.
+    expect(first.content ?? []).toHaveLength(0);
+    expect(jsonToText(json).trim()).toBe('');
+  });
+
+  it('round-trips a title through build -> extract -> build -> extract', () => {
+    const title = 'Round Trip Title';
+    const doc1 = buildTitleSeedYdoc(title);
+    const text1 = jsonToText(TiptapTransformer.fromYdoc(doc1, 'title')).trim();
+
+    const doc2 = buildTitleSeedYdoc(text1);
+    const text2 = jsonToText(TiptapTransformer.fromYdoc(doc2, 'title')).trim();
+
+    expect(text1).toBe(title);
+    expect(text2).toBe(text1);
+  });
+});

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

@@ -59,6 +59,7 @@ import { generateHTML, generateJSON } from '../common/helpers/prosemirror/html';
 import { Node, Schema } from '@tiptap/pm/model';
 import * as Y from 'yjs';
 import { Logger } from '@nestjs/common';
+import { TiptapTransformer } from '@hocuspocus/transformer';
 
 export const tiptapExtensions = [
   StarterKit.configure({
@@ -143,6 +144,34 @@ export function jsonToText(tiptapJson: JSONContent) {
   return generateText(tiptapJson, tiptapExtensions);
 }
 
+/**
+ * Build a standalone Y.Doc that holds ONLY the page title, in a dedicated Yjs
+ * fragment named exactly 'title' (the collaborative title-editor contract with
+ * the client). The ProseMirror shape is a doc with a single level-1 heading
+ * whose text is the title (empty title => heading with no text child).
+ *
+ * The encoded state of the returned doc can be merged into a body doc via
+ * `Y.applyUpdate(doc, Y.encodeStateAsUpdate(titleSeed))` to seed the title
+ * fragment for legacy pages. Seeding MUST be guarded by an emptiness check on
+ * the existing 'title' fragment to avoid the Yjs duplication trap.
+ */
+export function buildTitleSeedYdoc(title: string): Y.Doc {
+  return TiptapTransformer.toYdoc(
+    {
+      type: 'doc',
+      content: [
+        {
+          type: 'heading',
+          attrs: { level: 1 },
+          content: title ? [{ type: 'text', text: title }] : [],
+        },
+      ],
+    },
+    'title',
+    tiptapExtensions,
+  );
+}
+
 export function jsonToNode(tiptapJson: JSONContent) {
   const schema = getSchema(tiptapExtensions);
   try {

apps/server/src/collaboration/constants.ts

@@ -1,3 +1,9 @@
 export const HISTORY_INTERVAL = 5 * 60 * 1000;
 export const HISTORY_FAST_INTERVAL = 60 * 1000;
 export const HISTORY_FAST_THRESHOLD = 5 * 60 * 1000;
+
+// Redis pub/sub channel that bridges a PAGE_UPDATED tree snapshot (a title/icon
+// rename) from the standalone collab process to the API process, which is the
+// single broadcast authority. Imported by both halves of the bridge:
+// PageTreeBridgePublisher (collab process) and PageTreeBridgeSubscriber (API process).
+export const COLLAB_TREE_UPDATE_CHANNEL = 'collab:tree-update';

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

@@ -1,89 +0,0 @@
-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

@@ -1,223 +1,483 @@
-// 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 { TiptapTransformer } from '@hocuspocus/transformer';
 import { PersistenceExtension } from './persistence.extension';
-import {
-  onChangePayload,
-  onStoreDocumentPayload,
-} from '@hocuspocus/server';
+import { buildTitleSeedYdoc, tiptapExtensions } from '../collaboration.util';
 
-/**
- * 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';
+// Direct instantiation with stub deps, mirroring the auth/env unit specs.
+const bodyJson = {
+  type: 'doc',
+  content: [{ type: 'paragraph', content: [{ type: 'text', text: 'hello' }] }],
+};
 
-  // `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(),
-  });
+// Build a body Y.Doc with a known JSON, plus a monkey-patched broadcastStateless
+// (the real Hocuspocus Document supplies it; a bare Y.Doc does not).
+const buildDoc = () => {
+  const d: any = TiptapTransformer.toYdoc(bodyJson, 'default', tiptapExtensions);
+  d.broadcastStateless = jest.fn();
+  return d;
+};
 
-  const build = (pageOverrides?: { lastUpdatedSource?: string }) => {
-    const pageRepo = {
-      findById: jest.fn().mockResolvedValue(persistedPage(pageOverrides)),
-      updatePage: jest.fn().mockResolvedValue({ numUpdatedRows: 1n }),
+const cloneOut = (doc: any) =>
+  JSON.parse(JSON.stringify(TiptapTransformer.fromYdoc(doc, 'default')));
+
+const addTitleFragment = (doc: any, title: string) =>
+  Y.applyUpdate(doc, Y.encodeStateAsUpdate(buildTitleSeedYdoc(title)));
+
+describe('PersistenceExtension', () => {
+  let pageRepo: any;
+  let pageHistoryRepo: any;
+  let trx: any;
+  let db: any;
+  let aiQueue: any;
+  let historyQueue: any;
+  let notificationQueue: any;
+  let collabHistory: any;
+  let transclusionService: any;
+  let ext: PersistenceExtension;
+
+  beforeEach(() => {
+    pageRepo = {
+      findById: jest.fn(),
+      updatePage: jest.fn().mockResolvedValue(undefined),
     };
-    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),
+    pageHistoryRepo = {
+      findPageLastHistory: jest.fn(),
+      saveHistory: jest.fn(),
     };
-    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 = {
+    trx = {};
+    db = { transaction: () => ({ execute: (fn: any) => fn(trx) }) };
+    aiQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    historyQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    collabHistory = { addContributors: jest.fn().mockResolvedValue(undefined) };
+    transclusionService = {
       syncPageTransclusions: jest.fn().mockResolvedValue(undefined),
       syncPageReferences: jest.fn().mockResolvedValue(undefined),
       syncPageTemplateReferences: jest.fn().mockResolvedValue(undefined),
     };
 
-    const ext = new PersistenceExtension(
+    ext = new PersistenceExtension(
       pageRepo as any,
       pageHistoryRepo as any,
-      {} as any, // db
+      db as any,
       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();
+  describe('seedTitleFragment', () => {
+    it('returns false for empty/whitespace/null titles', () => {
+      const doc = new Y.Doc();
+      expect((ext as any).seedTitleFragment(doc, '')).toBe(false);
+      expect((ext as any).seedTitleFragment(doc, '   ')).toBe(false);
+      expect((ext as any).seedTitleFragment(doc, null)).toBe(false);
+    });
 
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
-    );
+    it('does NOT re-seed an existing non-empty title fragment', () => {
+      const doc = new Y.Doc();
+      addTitleFragment(doc, 'Existing');
 
-    expect(sourceOf(pageRepo)).toBe('git-sync');
+      expect((ext as any).seedTitleFragment(doc, 'Other')).toBe(false);
+
+      const text = TiptapTransformer.fromYdoc(doc, 'title');
+      expect(JSON.stringify(text)).toContain('Existing');
+      expect(JSON.stringify(text)).not.toContain('Other');
+    });
+
+    it('seeds an empty fragment from a non-empty title and returns true', () => {
+      const doc = new Y.Doc();
+      expect((ext as any).seedTitleFragment(doc, 'Hello')).toBe(true);
+
+      const json: any = TiptapTransformer.fromYdoc(doc, 'title');
+      expect(JSON.stringify(json)).toContain('Hello');
+    });
+
+    it('returns false (defensive) when reading the fragment throws', () => {
+      const fakeDoc = {
+        get: () => {
+          throw new Error('boom');
+        },
+      };
+      expect((ext as any).seedTitleFragment(fakeDoc as any, 'X')).toBe(false);
+    });
   });
 
-  it("keeps 'git-sync' for an explicit git-sync store even with a sticky agent marker (#14 loop-guard)", async () => {
-    const { ext, pageRepo } = build();
+  describe('onStoreDocument', () => {
+    const basePage = (overrides: any) => ({
+      id: 'PAGE_ID',
+      slugId: 'slug',
+      spaceId: 'space',
+      parentPageId: null,
+      creatorId: 'creator',
+      contributorIds: ['creator'],
+      workspaceId: 'ws',
+      title: 'whatever',
+      content: null,
+      lastUpdatedSource: 'user',
+      createdAt: new Date().toISOString(),
+      ...overrides,
+    });
 
-    // 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' }),
-    );
+    const context = { user: { id: 'u1', name: 'U', avatarUrl: null } };
 
-    expect(sourceOf(pageRepo)).toBe('git-sync');
+    it('no-op when neither body nor title changed', async () => {
+      const document = buildDoc();
+      const page = basePage({
+        content: cloneOut(document),
+        title: 'hello title',
+      });
+      pageRepo.findById.mockResolvedValue(page);
+
+      await ext.onStoreDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+        context,
+      } as any);
+
+      expect(pageRepo.updatePage).not.toHaveBeenCalled();
+      expect(document.broadcastStateless).not.toHaveBeenCalled();
+      expect(collabHistory.addContributors).not.toHaveBeenCalled();
+      expect(transclusionService.syncPageTransclusions).not.toHaveBeenCalled();
+      expect(aiQueue.add).not.toHaveBeenCalled();
+      expect(historyQueue.add).not.toHaveBeenCalled();
+    });
+
+    it('title-only change persists the title without body side-effects', async () => {
+      const document = buildDoc();
+      addTitleFragment(document, 'New Title');
+      const page = basePage({
+        content: cloneOut(document),
+        title: 'Old Title',
+      });
+      pageRepo.findById.mockResolvedValue(page);
+
+      await ext.onStoreDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+        context,
+      } as any);
+
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      const call = pageRepo.updatePage.mock.calls[0];
+      expect(call[0].title).toBe('New Title');
+      expect(call[0].ydoc).toBeDefined();
+      expect(call[0].contributorIds).toBeDefined();
+      expect('content' in call[0]).toBe(false);
+      // Title-only must not touch the body-authorship provenance.
+      expect('lastUpdatedSource' in call[0]).toBe(false);
+      expect(call[1]).toBe('PAGE_ID');
+      expect(call[3].treeUpdate.title).toBe('New Title');
+
+      expect(collabHistory.addContributors).toHaveBeenCalledTimes(1);
+      expect(collabHistory.addContributors).toHaveBeenCalledWith(
+        'PAGE_ID',
+        expect.any(Array),
+      );
+      expect(document.broadcastStateless).toHaveBeenCalledTimes(1);
+      expect(transclusionService.syncPageTransclusions).not.toHaveBeenCalled();
+      expect(aiQueue.add).not.toHaveBeenCalled();
+      expect(historyQueue.add).not.toHaveBeenCalled();
+    });
+
+    it('an EMPTY title fragment does NOT overwrite a non-empty page.title (anti-corruption guard, Bug 2)', async () => {
+      // The client can momentarily seed the 'title' fragment as an EMPTY heading
+      // (hasTitleFragment true, extracted text '') before the real title syncs.
+      // Body is unchanged here, so the only candidate write is the title -> the
+      // guard must turn this into a full no-op (no updatePage, no broadcast).
+      const document = buildDoc();
+      addTitleFragment(document, ''); // empty heading: length > 0 but text ''
+      const page = basePage({
+        content: cloneOut(document),
+        title: 'Real Title',
+      });
+      pageRepo.findById.mockResolvedValue(page);
+
+      await ext.onStoreDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+        context,
+      } as any);
+
+      // No write at all: the empty title is not authoritative and the body is
+      // unchanged, so onStoreDocument must take the no-op fast path.
+      expect(pageRepo.updatePage).not.toHaveBeenCalled();
+      expect(document.broadcastStateless).not.toHaveBeenCalled();
+    });
+
+    it('an EMPTY title fragment alongside a body change persists the body but NOT an empty title (anti-corruption guard, Bug 2)', async () => {
+      const document = buildDoc();
+      addTitleFragment(document, ''); // empty title fragment
+      const page = basePage({
+        content: { type: 'doc', content: [] }, // different body -> bodyChanged
+        title: 'Real Title',
+      });
+      pageRepo.findById.mockResolvedValue(page);
+
+      await ext.onStoreDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+        context,
+      } as any);
+
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      const call = pageRepo.updatePage.mock.calls[0];
+      // Body is persisted, but the title is NOT included (empty == not
+      // authoritative) and no tree update is broadcast for the title.
+      expect(call[0].content).toBeTruthy();
+      expect('title' in call[0]).toBe(false);
+      expect(call[3]).toBeUndefined();
+    });
+
+    it('body + title change persists both with full body side-effects', async () => {
+      const document = buildDoc();
+      addTitleFragment(document, 'New Title');
+      const page = basePage({
+        content: { type: 'doc', content: [] },
+        title: 'Old Title',
+      });
+      pageRepo.findById.mockResolvedValue(page);
+
+      await ext.onStoreDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+        context,
+      } as any);
+
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      const call = pageRepo.updatePage.mock.calls[0];
+      expect(call[0].content).toBeTruthy();
+      expect(call[0].title).toBe('New Title');
+      expect(call[0].ydoc).toBeDefined();
+      expect(call[0].lastUpdatedSource).toBe('user');
+      expect(call[3].treeUpdate).toBeDefined();
+
+      expect(transclusionService.syncPageTransclusions).toHaveBeenCalled();
+      expect(aiQueue.add).toHaveBeenCalled();
+      expect(historyQueue.add).toHaveBeenCalled();
+      expect(collabHistory.addContributors).toHaveBeenCalled();
+      expect(document.broadcastStateless).toHaveBeenCalled();
+    });
+
+    it('body-only change persists the body without a tree update', async () => {
+      const document = buildDoc();
+      const page = basePage({
+        content: { type: 'doc', content: [] },
+        title: 'whatever',
+      });
+      pageRepo.findById.mockResolvedValue(page);
+
+      await ext.onStoreDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+        context,
+      } as any);
+
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      const call = pageRepo.updatePage.mock.calls[0];
+      expect(call[0].content).toBeTruthy();
+      expect('title' in call[0]).toBe(false);
+      // No treeUpdate for a body-only save.
+      expect(call[3]).toBeUndefined();
+
+      expect(transclusionService.syncPageTransclusions).toHaveBeenCalled();
+      expect(aiQueue.add).toHaveBeenCalled();
+      expect(historyQueue.add).toHaveBeenCalled();
+      expect(document.broadcastStateless).toHaveBeenCalled();
+    });
   });
 
-  it("tags 'agent' when the storing writer itself is the agent (no prior onChange)", async () => {
-    const { ext, pageRepo } = build();
+  describe('onLoadDocument', () => {
+    it('returns early (no DB read) when the document is not empty', async () => {
+      const document = { isEmpty: () => false };
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
 
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'agent-user' }, actor: 'agent' }),
-    );
+      expect(result).toBeUndefined();
+      expect(pageRepo.findById).not.toHaveBeenCalled();
+    });
 
-    expect(sourceOf(pageRepo)).toBe('agent');
-  });
+    it('returns undefined and does not persist when the page is null', async () => {
+      const document = { isEmpty: () => true };
+      pageRepo.findById.mockResolvedValue(null);
 
-  // --- 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' });
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
 
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
-    );
+      expect(result).toBeUndefined();
+      expect(pageRepo.updatePage).not.toHaveBeenCalled();
+    });
 
-    expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
-  });
+    it('seeds + persists under a lock when the persisted ydoc lacks a title fragment', async () => {
+      const src = TiptapTransformer.toYdoc(bodyJson, 'default', tiptapExtensions);
+      const page = {
+        id: 'PAGE_ID',
+        title: 'Legacy Title',
+        ydoc: Buffer.from(Y.encodeStateAsUpdate(src)),
+        content: null,
+      };
+      // Both the cheap pre-check and the locked re-read return the same row.
+      pageRepo.findById.mockResolvedValue(page);
 
-  // --- 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' });
+      const document = { isEmpty: () => true };
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
 
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
-    );
+      // The locked re-read must take the row lock inside the tx.
+      const lockedReadCall = pageRepo.findById.mock.calls.find(
+        (c: any[]) => c[1]?.withLock,
+      );
+      expect(lockedReadCall).toBeDefined();
+      expect(lockedReadCall[1].trx).toBe(trx);
 
-    expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
-  });
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      const call = pageRepo.updatePage.mock.calls[0];
+      expect(Buffer.isBuffer(call[0].ydoc)).toBe(true);
+      expect(call[1]).toBe('PAGE_ID');
+      // Persist must run inside the transaction.
+      expect(call[2]).toBe(trx);
+      expect(result).toBeTruthy();
+    });
 
-  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' });
+    it('does NOT lock or persist when the ydoc already has a title fragment', async () => {
+      const src = TiptapTransformer.toYdoc(bodyJson, 'default', tiptapExtensions);
+      Y.applyUpdate(src, Y.encodeStateAsUpdate(buildTitleSeedYdoc('Has Title')));
+      const page = {
+        id: 'PAGE_ID',
+        title: 'Has Title',
+        ydoc: Buffer.from(Y.encodeStateAsUpdate(src)),
+        content: null,
+      };
+      pageRepo.findById.mockResolvedValue(page);
 
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'agent-user' }, actor: 'agent' }),
-    );
+      const document = { isEmpty: () => true };
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
 
-    expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
-  });
+      // Hot path: only the cheap lock-free read, no locked re-read, no write.
+      expect(pageRepo.findById).toHaveBeenCalledTimes(1);
+      expect(pageRepo.findById.mock.calls[0][1]?.withLock).toBeFalsy();
+      expect(pageRepo.updatePage).not.toHaveBeenCalled();
+      expect(result).toBeTruthy();
+    });
 
-  it('does NOT pin a boundary snapshot for a plain user store', async () => {
-    const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'user' });
+    it('converts legacy content -> ydoc inside a tx and persists a {ydoc} Buffer', async () => {
+      const page = {
+        id: 'PAGE_ID',
+        title: 'T',
+        ydoc: null,
+        content: bodyJson,
+      };
+      pageRepo.findById.mockResolvedValue(page);
 
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'user-1' }, actor: 'user' }),
-    );
+      const document = { isEmpty: () => true };
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
 
-    expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      const lockedReadCall = pageRepo.findById.mock.calls.find(
+        (c: any[]) => c[1]?.withLock,
+      );
+      expect(lockedReadCall).toBeDefined();
+      expect(lockedReadCall[1].trx).toBe(trx);
+
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      const call = pageRepo.updatePage.mock.calls[0];
+      expect(Buffer.isBuffer(call[0].ydoc)).toBe(true);
+      expect(call[2]).toBe(trx);
+      // The rebuilt doc carries the body.
+      expect(JSON.stringify(cloneOut(result))).toContain('hello');
+    });
+
+    it('SKIPS rebuild when the locked re-read shows the ydoc was already healed', async () => {
+      // Simulate a concurrent process: the cheap pre-check sees ydoc=null (legacy
+      // rebuild path), but by the time we hold the lock another process has
+      // already persisted a healthy ydoc. We must adopt it, not rebuild/clobber.
+      const healed = TiptapTransformer.toYdoc(
+        { type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'healed' }] }] },
+        'default',
+        tiptapExtensions,
+      );
+      Y.applyUpdate(healed, Y.encodeStateAsUpdate(buildTitleSeedYdoc('Healed Title')));
+      const healedYdoc = Buffer.from(Y.encodeStateAsUpdate(healed));
+
+      const preCheck = { id: 'PAGE_ID', title: 'T', ydoc: null, content: bodyJson };
+      const lockedRow = {
+        id: 'PAGE_ID',
+        title: 'Healed Title',
+        ydoc: healedYdoc,
+        content: bodyJson,
+      };
+      pageRepo.findById
+        .mockResolvedValueOnce(preCheck) // cheap pre-check
+        .mockResolvedValueOnce(lockedRow); // locked re-read
+
+      const document = { isEmpty: () => true };
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
+
+      // The healthy ydoc had a title fragment already, so nothing was rebuilt or
+      // seeded -> no clobbering write.
+      expect(pageRepo.updatePage).not.toHaveBeenCalled();
+      // The returned doc is the healed body, NOT a fresh rebuild of bodyJson.
+      expect(JSON.stringify(cloneOut(result))).toContain('healed');
+    });
+
+    it('REJECTS the load when the rebuild persist fails (does not return an unpersisted doc)', async () => {
+      const page = { id: 'PAGE_ID', title: 'T', ydoc: null, content: bodyJson };
+      pageRepo.findById.mockResolvedValue(page);
+      pageRepo.updatePage.mockRejectedValue(new Error('db down'));
+      const errSpy = jest
+        .spyOn((ext as any).logger, 'error')
+        .mockImplementation(() => undefined);
+
+      const document = { isEmpty: () => true };
+      await expect(
+        ext.onLoadDocument({
+          documentName: 'page.PAGE_ID',
+          document,
+        } as any),
+      ).rejects.toThrow('db down');
+      expect(errSpy).toHaveBeenCalled();
+    });
+
+    it('seed-only persist FAILURE returns the doc from the existing ydoc (no throw)', async () => {
+      const src = TiptapTransformer.toYdoc(bodyJson, 'default', tiptapExtensions);
+      const page = {
+        id: 'PAGE_ID',
+        title: 'Legacy Title',
+        ydoc: Buffer.from(Y.encodeStateAsUpdate(src)),
+        content: null,
+      };
+      pageRepo.findById.mockResolvedValue(page);
+      pageRepo.updatePage.mockRejectedValue(new Error('db down'));
+      const errSpy = jest
+        .spyOn((ext as any).logger, 'error')
+        .mockImplementation(() => undefined);
+
+      const document = { isEmpty: () => true };
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
+
+      // Non-fatal: we fall back to the doc loaded from the existing page.ydoc.
+      expect(result).toBeTruthy();
+      expect(JSON.stringify(cloneOut(result))).toContain('hello');
+      expect(errSpy).toHaveBeenCalled();
+    });
   });
 });

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

@@ -2,7 +2,6 @@ import {
   afterUnloadDocumentPayload,
   Extension,
   onChangePayload,
-  onDisconnectPayload,
   onLoadDocumentPayload,
   onStoreDocumentPayload,
 } from '@hocuspocus/server';
@@ -10,6 +9,7 @@ import * as Y from 'yjs';
 import { Injectable, Logger } from '@nestjs/common';
 import { TiptapTransformer } from '@hocuspocus/transformer';
 import {
+  buildTitleSeedYdoc,
   getPageId,
   isEmptyParagraphDoc,
   jsonToText,
@@ -53,17 +53,7 @@ export function resolveSource(
   stickyTouched: boolean,
   contextActor?: string,
 ): ProvenanceSource {
-  // 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';
+  return stickyTouched || contextActor === 'agent' ? 'agent' : 'user';
 }
 
 /**
@@ -127,6 +117,10 @@ export class PersistenceExtension implements Extension {
       return;
     }
 
+    // Cheap, lock-free pre-check (hot path stays lock-free). It tells us whether
+    // any heal (legacy rebuild and/or title seed) is needed; the heal itself
+    // re-reads the row FOR UPDATE and re-validates inside a transaction so it
+    // runs exactly once (see healUnderLock).
     const page = await this.pageRepo.findById(pageId, {
       includeContent: true,
       includeYdoc: true,
@@ -138,27 +132,70 @@ export class PersistenceExtension implements Extension {
     }
 
     if (page.ydoc) {
-      this.logger.debug(`ydoc loaded from db: ${pageId}`);
-
       const doc = new Y.Doc();
-      const dbState = new Uint8Array(page.ydoc);
+      Y.applyUpdate(doc, new Uint8Array(page.ydoc));
 
-      Y.applyUpdate(doc, dbState);
-      return doc;
+      // Legacy pages persisted their title only in the `page.title` column; the
+      // ydoc has no 'title' fragment. Decide cheaply (no lock) whether a seed is
+      // needed by inspecting the loaded doc's 'title' fragment. A seed is needed
+      // only when that fragment is empty AND there is a non-empty column title.
+      let titleSeedNeeded = false;
+      try {
+        const titleFrag = doc.get('title', Y.XmlFragment);
+        titleSeedNeeded = titleFrag.length === 0 && !!page.title?.trim();
+      } catch (err) {
+        // A malformed title fragment must not break loading; skip the seed.
+        this.logger.warn(`failed to inspect title fragment: ${err?.['message']}`);
+        titleSeedNeeded = false;
+      }
+
+      if (!titleSeedNeeded) {
+        // Fully healthy: a ydoc with a title fragment (or nothing to seed).
+        this.logger.debug(`ydoc loaded from db: ${pageId}`);
+        return doc;
+      }
+
+      // SEED-ONLY heal: a valid page.ydoc already exists; we only need to add the
+      // title fragment. If the persist fails we must NOT hand out an unpersisted
+      // fresh-client-id seed (it could later duplicate the title), so we fall
+      // back to the healthy doc loaded from the EXISTING page.ydoc, without the
+      // seed. The title just won't render until a later successful heal —
+      // non-fatal, non-corrupting.
+      try {
+        return await this.healUnderLock(pageId);
+      } catch (err) {
+        this.logger.error(
+          `Failed to persist seeded ydoc for page ${pageId}; serving existing ydoc without title seed`,
+          err,
+        );
+        return doc;
+      }
     }
 
-    // if no ydoc state in db convert json in page.content to Ydoc.
+    // NOTE (offline-sync M1, Goal 2): this per-load self-heal converts +
+    // title-seeds + persists every legacy page (content set, ydoc null) on its
+    // first open, which neutralizes the duplication trap incrementally. A
+    // proactive one-shot BATCH migration over all such pages could be added
+    // later, but it requires the tiptap schema + TiptapTransformer (Node/Yjs),
+    // which a Kysely SQL migration cannot run; no runnable-task/CLI convention
+    // exists in this repo yet, so we deliberately avoid a fragile migration.
+    //
+    // If no ydoc state in db, REBUILD a Y.Doc from the JSON in page.content under
+    // a row lock (see healUnderLock).
     if (page.content) {
-      this.logger.debug(`converting json to ydoc: ${pageId}`);
-
-      const ydoc = TiptapTransformer.toYdoc(
-        page.content,
-        'default',
-        tiptapExtensions,
-      );
-
-      Y.encodeStateAsUpdate(ydoc);
-      return ydoc;
+      // REBUILD heal: surface failures. If the persist fails we REFUSE the load
+      // (re-throw) rather than hand out an unpersisted fresh-client-id rebuild —
+      // returning it would re-arm the duplication trap. A transient DB failure
+      // means the client reconnects and retries: correctness over availability.
+      try {
+        return await this.healUnderLock(pageId);
+      } catch (err) {
+        this.logger.error(
+          `Failed to persist rebuilt ydoc for page ${pageId}; refusing load`,
+          err,
+        );
+        throw err;
+      }
     }
 
     this.logger.debug(`creating fresh ydoc: ${pageId}`);
@@ -166,36 +203,90 @@ export class PersistenceExtension implements Extension {
   }
 
   /**
-   * 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.
+   * Serialize the legacy self-heal (rebuild from page.content and/or seed the
+   * title fragment, then persist) so it runs exactly ONCE per page, closing the
+   * Yjs duplication trap. Both TiptapTransformer.toYdoc and buildTitleSeedYdoc
+   * mint FRESH Yjs client-ids every call, so two concurrent rebuilds (the API
+   * process via openDirectConnection AND the standalone collab process both
+   * seeing `ydoc IS NULL`) could each persist a different-client-id state and let
+   * a long-offline client merge-and-duplicate. We prevent that by re-reading the
+   * row FOR UPDATE inside a transaction and re-validating state under the lock:
+   * whoever wins the lock heals; the loser observes the healthy `ydoc` and adopts
+   * it instead of rebuilding. The persist happens IN THE SAME TX, so a failed
+   * write rolls back and propagates out (the caller then decides refuse vs.
+   * fall-back).
    */
-  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;
+  private async healUnderLock(pageId: string): Promise<Y.Doc> {
+    return executeTx(this.db, async (trx) => {
+      const locked = await this.pageRepo.findById(pageId, {
+        withLock: true,
+        includeContent: true,
+        includeYdoc: true,
+        trx,
+      });
+
+      const doc = new Y.Doc();
+      let rebuilt = false;
+
+      if (locked?.ydoc) {
+        // Another process already healed (or the page always had a ydoc): adopt
+        // the healthy persisted state, do NOT rebuild.
+        Y.applyUpdate(doc, new Uint8Array(locked.ydoc));
+      } else if (locked?.content) {
+        this.logger.debug(`converting json to ydoc: ${pageId}`);
+        const built = TiptapTransformer.toYdoc(
+          locked.content,
+          'default',
+          tiptapExtensions,
+        );
+        Y.applyUpdate(doc, Y.encodeStateAsUpdate(built));
+        rebuilt = true;
+      }
+      // else: no ydoc and no content -> a fresh empty doc.
+
+      // Idempotent, emptiness-guarded title seed (safe to call always).
+      const seeded = this.seedTitleFragment(doc, locked?.title ?? null);
+
+      if (rebuilt || seeded) {
+        // Persist IN THE SAME TX. If this throws, the tx rolls back and the
+        // error propagates out of executeTx to the caller.
+        await this.pageRepo.updatePage(
+          { ydoc: Buffer.from(Y.encodeStateAsUpdate(doc)) },
+          pageId,
+          trx,
+        );
+        this.logger.debug(`persisted rebuilt/seeded ydoc: ${pageId}`);
+      }
+
+      return doc;
+    });
+  }
+
+  /**
+   * Seed the 'title' fragment of `doc` from the `page.title` column for legacy
+   * pages whose persisted ydoc has no title fragment yet.
+   *
+   * Guarded STRICTLY by emptiness: we only seed when the existing 'title'
+   * fragment is empty AND there is a non-empty column title. Seeding a non-empty
+   * fragment would re-introduce the Yjs duplication trap, so we never do it.
+   * Returns true when a seed was applied (so the caller can persist).
+   * Defensive: a malformed title must not break document loading.
+   */
+  private seedTitleFragment(doc: Y.Doc, title: string | null): boolean {
+    const trimmed = (title ?? '').trim();
+    if (!trimmed) return false;
+
     try {
-      await instance.debouncer.executeNow(debounceId);
+      const titleFrag = doc.get('title', Y.XmlFragment);
+      if (titleFrag.length !== 0) return false;
+
+      const titleSeed = buildTitleSeedYdoc(title);
+      Y.applyUpdate(doc, Y.encodeStateAsUpdate(titleSeed));
+      this.logger.debug('seeded title fragment from page.title column');
+      return true;
     } catch (err) {
-      this.logger.error(
-        `onDisconnect flush failed for ${documentName}: ` +
-          (err instanceof Error ? err.message : String(err)),
-      );
+      this.logger.warn(`failed to seed title fragment: ${err?.['message']}`);
+      return false;
     }
   }
 
@@ -216,16 +307,38 @@ export class PersistenceExtension implements Extension {
       this.logger.warn('jsonToText' + err?.['message']);
     }
 
+    // Title lives in the SAME Y.Doc as the body, in a dedicated 'title' fragment
+    // (the collaborative title-editor contract with the client). Extract it
+    // defensively: a malformed title fragment must NOT crash the document store.
+    // `hasTitleFragment` distinguishes "the doc actually carries a title
+    // fragment" from "legacy doc with no title fragment" — only the former may
+    // write page.title, so a legacy doc never clobbers the column with ''.
+    let titleText = '';
+    let hasTitleFragment = false;
+    try {
+      const titleFrag = document.get('title', Y.XmlFragment);
+      hasTitleFragment = !!titleFrag && titleFrag.length > 0;
+      if (hasTitleFragment) {
+        const titleJson = TiptapTransformer.fromYdoc(document, 'title');
+        titleText = titleJson ? jsonToText(titleJson).trim() : '';
+      }
+    } catch (err) {
+      this.logger.warn('title extraction: ' + err?.['message']);
+      hasTitleFragment = false;
+    }
+
     let page: Page = null;
+    // Tracks whether the BODY ('default') changed in this store. The heavy
+    // body-only side-effects (transclusion sync, mentions, RAG, history) stay
+    // gated on this so a title-only change does not trigger them.
+    let bodyChanged = false;
+    // Tracks a successful title-only persist so the post-tx contributor folding
+    // (collabHistory.addContributors) runs for the title-only case too.
+    let titleOnlyPersisted = false;
     const editingUserIds = this.consumeContributors(documentName);
     // 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,
@@ -255,11 +368,80 @@ export class PersistenceExtension implements Extension {
             return;
           }
 
-          if (isDeepStrictEqual(tiptapJson, page.content)) {
+          bodyChanged = !isDeepStrictEqual(tiptapJson, page.content);
+          // Only a populated 'title' fragment may update page.title; compare
+          // against the current column value (treat null as '').
+          //
+          // ANTI-CORRUPTION GUARD (Bug 2): the client's collaborative title-editor
+          // can momentarily initialize the 'title' fragment as an EMPTY heading
+          // (so `hasTitleFragment` is true, but the extracted `titleText` is '')
+          // BEFORE the server's real-title seed has synced. Writing that '' would
+          // silently wipe a non-empty page.title to "untitled". A wiki page is
+          // never legitimately retitled to empty via this path, so we treat an
+          // empty extracted title as "not authoritative" and never persist it.
+          // The `titleText.length > 0` clause makes this guard apply to BOTH the
+          // title-only branch and the body+title branch below.
+          //
+          // DELIBERATE: this intentionally makes it impossible to retitle a page
+          // to EMPTY via the collab path — a wiki page is never legitimately
+          // empty-titled. If a non-empty-title rule ever needs relaxing or
+          // enforcing differently, the REST UpdatePageDto is the place to validate
+          // the title, not this collab guard.
+          const titleChanged =
+            hasTitleFragment &&
+            titleText.length > 0 &&
+            titleText !== (page.title ?? '');
+
+          // No-op fast path: neither body nor title changed.
+          if (!bodyChanged && !titleChanged) {
             page = null;
             return;
           }
 
+          // Title-only change: the body is unchanged, so skip the heavy body
+          // history/contributor logic and persist just the new title and the
+          // ydoc (the title fragment edit lives in the same ydoc). The early-skip
+          // used to drop this case entirely, losing the title change.
+          if (!bodyChanged) {
+            // Fold the window's editing users into contributors the same way the
+            // body branch does, so a user who edited ONLY the title is not dropped
+            // from page.contributorIds.
+            const contributorIds = Array.from(
+              new Set([
+                ...(page.contributorIds || []),
+                ...editingUserIds,
+                page.creatorId,
+              ]),
+            );
+            await this.pageRepo.updatePage(
+              {
+                title: titleText,
+                ydoc: ydocState,
+                lastUpdatedById: context.user.id,
+                contributorIds,
+                // A title-only change is not a body-authorship transition; leave
+                // lastUpdatedSource/aiChatId untouched so the user->agent history
+                // boundary in the body branch is not bypassed.
+              },
+              pageId,
+              trx,
+              // Mirror PageService.update's tree snapshot so a collaborative rename
+              // propagates to other users' sidebar/breadcrumbs like the REST rename.
+              {
+                treeUpdate: {
+                  id: pageId,
+                  slugId: page.slugId,
+                  spaceId: page.spaceId,
+                  parentPageId: page.parentPageId ?? null,
+                  title: titleText,
+                },
+              },
+            );
+            this.logger.debug(`Page title updated: ${pageId} - SlugId: ${page.slugId}`);
+            titleOnlyPersisted = true;
+            return;
+          }
+
           let contributorIds = undefined;
           try {
             const existingContributors = page.contributorIds || [];
@@ -274,41 +456,25 @@ export class PersistenceExtension implements Extension {
             //this.logger.debug('Contributors error:' + err?.['message']);
           }
 
-          // 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) {
+          // 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') {
             const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
               pageId,
               { includeContent: true, trx },
             );
             const humanBaselineMissing =
-              !lastHistory ||
-              !isDeepStrictEqual(lastHistory.content, page.content);
-            if (
-              !isEmptyParagraphDoc(page.content as any) &&
-              humanBaselineMissing
-            ) {
+              !lastHistory || !isDeepStrictEqual(lastHistory.content, page.content);
+            if (!isEmptyParagraphDoc(page.content as any) && humanBaselineMissing) {
               await this.pageHistoryRepo.saveHistory(page, {
                 contributorIds: page.contributorIds ?? undefined,
                 trx,
@@ -326,9 +492,27 @@ export class PersistenceExtension implements Extension {
               lastUpdatedSource,
               lastUpdatedAiChatId: context?.aiChatId ?? null,
               contributorIds: contributorIds,
+              // Persist the title in the SAME transaction when the title fragment
+              // changed alongside the body.
+              ...(titleChanged ? { title: titleText } : {}),
             },
             pageId,
             trx,
+            // Mirror PageService.update's tree snapshot so a collaborative rename
+            // propagates to other users' sidebar/breadcrumbs like the REST rename.
+            // Only attach when the title actually changed; a body-only save must
+            // not trigger a tree broadcast.
+            titleChanged
+              ? {
+                  treeUpdate: {
+                    id: pageId,
+                    slugId: page.slugId,
+                    spaceId: page.spaceId,
+                    parentPageId: page.parentPageId ?? null,
+                    title: titleText,
+                  },
+                }
+              : undefined,
           );
 
           this.logger.debug(`Page updated: ${pageId} - SlugId: ${page.slugId}`);
@@ -349,6 +533,8 @@ export class PersistenceExtension implements Extension {
       }
     }
 
+    // `page` is truthy whenever anything was persisted (body OR title-only), so
+    // the page.updated broadcast fires for a title-only change too.
     if (page) {
       document.broadcastStateless(
         JSON.stringify({
@@ -366,11 +552,20 @@ export class PersistenceExtension implements Extension {
             : undefined,
         }),
       );
+    }
 
+    // Record the window's editing users in collab history for a title-only
+    // change too (the body branch does this below, gated on bodyChanged).
+    if (page && titleOnlyPersisted) {
+      await this.collabHistory.addContributors(pageId, editingUserIds);
+    }
+
+    // Body-only side-effects: skip them for a title-only change (body unchanged).
+    if (page && bodyChanged) {
       await this.syncTransclusion(pageId, page.workspaceId, tiptapJson);
     }
 
-    if (page) {
+    if (page && bodyChanged) {
       await this.collabHistory.addContributors(pageId, editingUserIds);
 
       const mentions = extractMentions(tiptapJson);

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

@@ -1,208 +0,0 @@
-// 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,15 +51,9 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
   private instance!: Hocuspocus;
   private readonly customEvents: TCE;
   private replyIdCounter: number = 0;
-  private pendingReplies: Record<
-    number,
-    {
-      // @ts-ignore
-      resolve: PromiseWithResolvers<any>['resolve'];
-      // @ts-ignore
-      reject: PromiseWithResolvers<any>['reject'];
-    }
-  > = {};
+  // @ts-ignore
+  private pendingReplies: Record<number, PromiseWithResolvers<any>['resolve']> =
+    {};
 
   constructor(configuration: Configuration<TCE>) {
     const {
@@ -182,45 +176,25 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
     }
     if (type === 'customEventStart') {
       const { documentName, eventName, payload, replyTo, replyId } = msg;
-      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),
-        };
-      }
+      const res = await this.handleEventLocally(
+        eventName as Extract<keyof TCE, string>,
+        documentName,
+        payload,
+      );
+      const reply: RSAMessageCustomEventComplete = {
+        type: 'customEventComplete',
+        replyId,
+        payload: res,
+      };
       this.pub.publish(`${replyTo}`, this.pack(reply));
       return;
     }
     if (type === 'customEventComplete') {
-      const { replyId, payload, error } = msg;
-      const pending = this.pendingReplies[replyId];
-      if (!pending) return;
+      const { replyId, payload } = msg;
+      const resolveFn = this.pendingReplies[replyId];
+      if (!resolveFn) return;
       delete this.pendingReplies[replyId];
-      if (error !== undefined) {
-        pending.reject(new Error(error));
-      } else {
-        pending.resolve(payload);
-      }
+      resolveFn(payload);
       return;
     }
     const { socketId } = msg;
@@ -299,22 +273,11 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
       };
       const msg = this.pack(proxyMessage);
       this.pub.publish(`${this.msgChannel}:${proxyTo}`, msg);
-      // 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 };
+      // @ts-ignore
+      const { promise, resolve, reject } = Promise.withResolvers();
+      this.pendingReplies[replyId] = resolve;
       setTimeout(() => {
-        // 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');
-        }
+        reject('TIMEOUT');
       }, this.customEventTTL);
       return promise as Promise<ReturnType<TCE[TName]>>;
     }

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

@@ -72,10 +72,6 @@ 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

@@ -1,535 +0,0 @@
-/**
- * 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/listeners/page-tree-bridge.publisher.spec.ts

@@ -0,0 +1,81 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { RedisService } from '@nestjs-labs/nestjs-ioredis';
+import { PageTreeBridgePublisher } from './page-tree-bridge.publisher';
+import { COLLAB_TREE_UPDATE_CHANNEL } from '../constants';
+import {
+  PageEvent,
+  TreeUpdateSnapshot,
+} from '../../database/listeners/page.listener';
+
+const treeUpdate: TreeUpdateSnapshot = {
+  id: 'page-1',
+  slugId: 'slug-1',
+  spaceId: 'space-1',
+  parentPageId: null,
+  title: 'Renamed',
+  icon: '🚀',
+};
+
+describe('PageTreeBridgePublisher', () => {
+  let publisher: PageTreeBridgePublisher;
+  let redis: { publish: jest.Mock };
+
+  beforeEach(async () => {
+    redis = { publish: jest.fn().mockResolvedValue(1) };
+    const redisService = { getOrThrow: () => redis } as unknown as RedisService;
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        PageTreeBridgePublisher,
+        { provide: RedisService, useValue: redisService },
+      ],
+    }).compile();
+
+    publisher = module.get<PageTreeBridgePublisher>(PageTreeBridgePublisher);
+  });
+
+  it('WITH a `treeUpdate`: publishes the JSON snapshot on the channel', async () => {
+    const event: PageEvent = {
+      pageIds: ['page-1'],
+      workspaceId: 'ws-1',
+      treeUpdate,
+    };
+
+    await publisher.onPageUpdated(event);
+
+    expect(redis.publish).toHaveBeenCalledTimes(1);
+    expect(redis.publish).toHaveBeenCalledWith(
+      COLLAB_TREE_UPDATE_CHANNEL,
+      JSON.stringify(treeUpdate),
+    );
+  });
+
+  it('content-only save (NO `treeUpdate`): does NOT publish', async () => {
+    const event: PageEvent = {
+      pageIds: ['page-1'],
+      workspaceId: 'ws-1',
+    };
+
+    await publisher.onPageUpdated(event);
+
+    expect(redis.publish).not.toHaveBeenCalled();
+  });
+
+  it('a publish rejection is caught (no throw)', async () => {
+    redis.publish.mockRejectedValueOnce(new Error('redis down'));
+    const errorSpy = jest
+      .spyOn(publisher['logger'], 'error')
+      .mockImplementation(() => undefined);
+
+    const event: PageEvent = {
+      pageIds: ['page-1'],
+      workspaceId: 'ws-1',
+      treeUpdate,
+    };
+
+    await expect(publisher.onPageUpdated(event)).resolves.toBeUndefined();
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+
+    errorSpy.mockRestore();
+  });
+});

apps/server/src/collaboration/listeners/page-tree-bridge.publisher.ts

@@ -0,0 +1,55 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { RedisService } from '@nestjs-labs/nestjs-ioredis';
+import type { Redis } from 'ioredis';
+import { EventName } from '../../common/events/event.contants';
+import { PageEvent } from '../../database/listeners/page.listener';
+import { COLLAB_TREE_UPDATE_CHANNEL } from '../constants';
+
+/**
+ * Collab-process half of the cross-process tree-update bridge.
+ *
+ * The standalone collab process bootstraps `CollabAppModule`, which does NOT
+ * import `WsModule`/`PageWsListener`. So when a collaborative title/icon rename
+ * persists and emits `EventName.PAGE_UPDATED` with a `treeUpdate` snapshot, there
+ * is no listener in this process to broadcast it — the live tree update would be
+ * lost for 2-process (COLLAB_URL set) deployments.
+ *
+ * This publisher fills that gap: it forwards the `treeUpdate` snapshot over a
+ * Redis pub/sub channel to the API process, which re-broadcasts it via
+ * `WsTreeService` (the single broadcast authority).
+ *
+ * It is registered ONLY in `CollabAppModule.providers`, so it never runs in the
+ * API process (where `PageWsListener` already broadcasts the same event locally).
+ * That module placement is what prevents a double broadcast. In single-process
+ * mode `CollabAppModule` is not loaded at all, so this publisher never runs.
+ */
+@Injectable()
+export class PageTreeBridgePublisher {
+  private readonly logger = new Logger(PageTreeBridgePublisher.name);
+  private readonly redis: Redis;
+
+  constructor(private readonly redisService: RedisService) {
+    this.redis = this.redisService.getOrThrow();
+  }
+
+  @OnEvent(EventName.PAGE_UPDATED)
+  async onPageUpdated(event: PageEvent): Promise<void> {
+    // Mirror PageWsListener's gating: only title/icon changes carry a snapshot.
+    // Content-only saves leave `treeUpdate` undefined and are ignored.
+    if (!event.treeUpdate) return;
+
+    try {
+      await this.redis.publish(
+        COLLAB_TREE_UPDATE_CHANNEL,
+        JSON.stringify(event.treeUpdate),
+      );
+    } catch (err) {
+      // A Redis publish failure must not break the store path.
+      this.logger.error(
+        `Failed to publish tree update to ${COLLAB_TREE_UPDATE_CHANNEL}`,
+        err instanceof Error ? err.stack : String(err),
+      );
+    }
+  }
+}

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

@@ -1,26 +0,0 @@
-/**
- * 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

@@ -1,20 +0,0 @@
-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

@@ -1,159 +0,0 @@
-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

@@ -1,274 +0,0 @@
-/**
- * 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 };
-}