test(git-sync): mock db.transaction in movePage provenance specs

After rebasing onto develop, movePage runs its cycle-check + UPDATE inside
executeTx(this.db) (develop #207 advisory-lock/atomic cycle-guard). The
git-sync provenance specs still passed a bare `{}` db, so executeTx hit
`db.transaction is not a function`. Reuse the same trxStub Proxy + transaction
mock the develop movePage specs use so both the advisory-lock `sql.execute(trx)`
and updatePage resolve. Production movePage keeps BOTH develop's lock/cycle
guard AND git-sync's provenance stamping; this only updates the test harness.

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

.env.example

@@ -187,6 +187,14 @@ MCP_DOCMOST_PASSWORD=
 # Per-request output-token ceiling for the anonymous assistant (default: 512).
 # Worst-case output per accepted call = agent steps (5) × this value.
 # SHARE_AI_MAX_OUTPUT_TOKENS=512
+#
+# Second cost backstop: a cluster-wide per-workspace rolling-DAY token budget
+# (input re-sent per step + output, summed across every accepted turn). The
+# hourly request cap above bounds how MANY calls run, not how expensive each is,
+# so this caps the owner's actual provider bill directly. Like the request cap it
+# 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

.github/workflows/develop.yml

@@ -56,3 +56,160 @@ jobs:
           tags: ${{ env.IMAGE }}:develop
           cache-from: type=gha,scope=develop-amd64
           cache-to: type=gha,scope=develop-amd64,mode=max,ignore-error=true
+
+  # e2e jobs run on every develop push but DO NOT gate the build/publish above:
+  # `build` stays `needs: test` only, so the :develop image still ships even if
+  # e2e fails. A failing e2e job turns the run red and triggers GitHub's email
+  # to the pusher — that red run + email is the intended notification, not a
+  # deploy block.
+  e2e-server:
+    runs-on: ubuntu-latest
+    env:
+      DATABASE_URL: postgresql://docmost:docmost@localhost:5432/docmost
+      REDIS_URL: redis://localhost:6379
+      APP_SECRET: ci-e2e-secret-change-me-min-32-characters
+      APP_URL: http://localhost:3000
+    services:
+      postgres:
+        image: pgvector/pgvector:pg18
+        env:
+          POSTGRES_DB: docmost
+          POSTGRES_USER: docmost
+          POSTGRES_PASSWORD: docmost
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U docmost"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build editor-ext
+        run: pnpm --filter @docmost/editor-ext build
+
+      - name: Run migrations
+        run: pnpm --filter ./apps/server migration:latest
+
+      - name: Run server e2e
+        run: pnpm --filter ./apps/server test:e2e
+
+  # Same rationale as e2e-server: this job is intentionally NOT in
+  # `build.needs`. Deploy of the :develop image must not be blocked by e2e;
+  # a red run plus GitHub's email to the pusher is the notification mechanism.
+  e2e-mcp:
+    runs-on: ubuntu-latest
+    env:
+      DATABASE_URL: postgresql://docmost:docmost@localhost:5432/docmost
+      REDIS_URL: redis://localhost:6379
+      APP_SECRET: ci-e2e-secret-change-me-min-32-characters
+      APP_URL: http://localhost:3000
+      NODE_ENV: production
+    services:
+      postgres:
+        image: pgvector/pgvector:pg18
+        env:
+          POSTGRES_DB: docmost
+          POSTGRES_USER: docmost
+          POSTGRES_PASSWORD: docmost
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U docmost"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build editor-ext
+        run: pnpm --filter @docmost/editor-ext build
+
+      - name: Build server
+        run: pnpm server:build
+
+      - name: Build mcp
+        run: pnpm --filter @docmost/mcp build
+
+      - name: Run migrations
+        run: pnpm --filter ./apps/server migration:latest
+
+      - name: Start server (prod)
+        # Capture stdout/stderr so a start-up crash (bind error, stack trace,
+        # migration mismatch) is diagnosable; without this the only signal is
+        # the generic health-loop timeout below, ~120s later.
+        run: pnpm --filter ./apps/server start:prod > /tmp/server.log 2>&1 &
+
+      - name: Wait for server health
+        run: |
+          for i in $(seq 1 60); do
+            if curl -fsS http://localhost:3000/api/health > /dev/null; then
+              echo "Server is healthy"
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "Server did not become healthy in time"
+          exit 1
+
+      - name: Dump server log on failure
+        if: failure()
+        run: cat /tmp/server.log || true
+
+      - name: Seed admin
+        run: |
+          curl -fsS -X POST http://localhost:3000/api/auth/setup \
+            -H "Content-Type: application/json" \
+            -d '{"name":"E2E","email":"e2e@example.com","password":"E2ePassword123","workspaceName":"E2E"}'
+
+      - name: Run mcp e2e
+        env:
+          DOCMOST_API_URL: http://localhost:3000/api
+          DOCMOST_EMAIL: e2e@example.com
+          DOCMOST_PASSWORD: E2ePassword123
+        run: pnpm --filter @docmost/mcp test:e2e

.gitignore

@@ -48,6 +48,7 @@ lerna-debug.log*
 .nx/installation
 .nx/cache
 .claude/worktrees/
+.claude/tmp/
 
 # TypeScript incremental build artifacts
 *.tsbuildinfo

AGENTS.md

@@ -284,37 +284,46 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 
 ### Cutting a release
 
-The git tag is the source of truth for the displayed version (UI reads `git describe --tags`); the `package.json` bump is metadata only. Steps:
+The git tag is the source of truth for the displayed version (the client UI reads `git describe --tags` via `vite.config.ts`); the `package.json` bump is metadata that backs the server `/version` endpoint (`version.service.ts`).
 
-1. Make sure `main` is clean and pushed (`git status`, `git push`).
+**Golden rule — tag on `develop` first, merge to `main` afterwards.** Cut the version-bump commit on `develop`, put the tag on *that* commit, and push it. Merge `develop` into `main` later (it does not block the tag or the release). Because the tag is in `develop`'s ancestry from the moment it is created, `git describe` on `develop` — and the `ghcr.io/vvzvlad/gitmost:develop` image — reports the new version immediately, with **no back-merge dance**. Do **not** tag `main`'s merge commit; that is the mistake described in the pitfall below (we hit it twice).
+
+Steps:
+
+1. Make sure `develop` is up to date, clean, and pushed to **both** remotes (`git status`; `git push gitea develop && git push github develop`).
 2. Pick `vX.Y.Z` (SemVer): **minor** bump for a batch of features, **patch** for fixes only. Review what landed with `git log <last-tag>..HEAD --no-merges`.
-3. Bump `"version"` to `X.Y.Z` in the **root** `package.json`, `apps/client/package.json`, and `apps/server/package.json` (keep all three in sync). Leave `packages/mcp` alone — it is versioned independently. Commit with the bare version as the subject, e.g. `0.91.0` (matches past bump commits).
-4. Update `CHANGELOG.md` (Keep a Changelog format): add a `## [X.Y.Z] - YYYY-MM-DD` section summarising `git log vPREV..HEAD --no-merges` grouped by type (Breaking / Added / Changed / Fixed / Removed), and add the `compare/vPREV...vX.Y.Z` link at the bottom. Fold the bump + changelog into the release commit.
-5. Tag the release commit with a **lightweight** tag (existing release tags are lightweight): `git tag vX.Y.Z`.
-6. Push commit and tag: `git push origin main && git push origin vX.Y.Z`. Pushing the `v*` tag triggers `release.yml` (multi-arch GHCR images + a draft GitHub Release).
-7. **Back-merge the release into `develop`** so develop builds report the new version: `git checkout develop && git merge --no-ff main && git push origin develop` (push to Gitea as well if that is the canonical remote).
+3. Bump `"version"` to `X.Y.Z` in the **root** `package.json`, `apps/client/package.json`, and `apps/server/package.json` (keep all three in sync). Leave `packages/mcp` alone — it is versioned independently. Commit **on `develop`** with the bare version as the subject, e.g. `0.94.1` (matches past bump commits).
+4. For a real release (skip for a bare hotfix tag), update `CHANGELOG.md` (Keep a Changelog format): add a `## [X.Y.Z] - YYYY-MM-DD` section summarising `git log vPREV..HEAD --no-merges` grouped by type (Breaking / Added / Changed / Fixed / Removed), and the `compare/vPREV...vX.Y.Z` link at the bottom. Fold it into the bump commit.
+5. Tag that develop commit with a **lightweight** tag (existing release tags are lightweight): `git tag vX.Y.Z`.
+6. Push the branch **and** the tag to **both** writable remotes — `git push <branch>` does **not** push tags, and tags are per-remote:
+   ```bash
+   git push gitea develop && git push gitea vX.Y.Z
+   git push github develop && git push github vX.Y.Z
+   ```
+   Pushing the `v*` tag to `github` triggers `release.yml` (multi-arch GHCR images + a draft GitHub Release). The tag *must* exist on `github`, because the `:develop` and release images are built there by GitHub Actions and `git describe` on the runner only sees the tags present on `github` (not your local clone or `gitea`).
+7. Merge `develop` into `main` when ready (commonly later — this does not gate the release):
+   ```bash
+   git checkout main
+   git merge --ff-only develop   # or a merge commit if fast-forward is not possible
+   git push gitea main && git push github main
+   ```
+   The tag is already reachable from `main` (it lives in the `develop` history that `main` now contains), so `main` reports `vX.Y.Z` too — no extra tagging needed.
 
-#### Why develop keeps showing the *previous* version (and why step 7 matters)
+#### Pitfall: tagging `main` instead of `develop` (the mistake to avoid)
 
-The UI version is `git describe --tags --always` (see `vite.config.ts`), which walks **backwards from the current commit** and picks the **nearest tag reachable in that commit's ancestry**, then appends `-<commits-since-tag>-g<short-hash>`.
+`git describe --tags --always` (see `vite.config.ts`) walks **backwards from the current commit** and picks the **nearest tag reachable in that commit's ancestry**, then appends `-<commits-since-tag>-g<short-hash>`.
 
-The release tag (`vX.Y.Z`) is created on **`main`'s release merge commit**, and that commit is **not** in `develop`'s history. So until the release is back-merged, `git describe` on `develop` cannot see the new tag and falls back to the *previous* reachable tag. Result: every develop build — and the `ghcr.io/vvzvlad/gitmost:develop` image — keeps reporting e.g. `v0.91.0-NNN-g<hash>` even though `main` is already tagged `v0.93.0`. This is the classic git-flow pitfall: the version on `develop` does **not** advance just because a release was tagged on `main`.
+The wrong flow we fell into twice: merge `develop` into `main` *first*, then tag `main`'s **release merge commit**. That merge commit is **not** in `develop`'s history, so `git describe` on `develop` cannot see the new tag and falls back to the *previous* reachable one. Result: every develop build — and the `ghcr.io/vvzvlad/gitmost:develop` image — keeps reporting e.g. `v0.93.0-NNN-g<hash>` even though a release was "cut". Tagging on `develop` (the golden rule above) avoids this entirely: the tag is in `develop`'s ancestry from the start, and `main` still gets it once `develop` is merged in.
 
-Back-merging `main → develop` (step 7) pulls the tagged release commit into `develop`'s ancestry, after which develop builds correctly show `vX.Y.Z-NNN-g<hash>`. If `develop` already drifted (release tagged but never back-merged), just run step 7 now — no new tag is needed.
+Second gotcha — the tag must exist on the remote CI builds from. `git describe` names a tag **ref**, not just a commit. The `:develop` and release images are built by GitHub Actions (`develop.yml` / `release.yml`, `actions/checkout` with `fetch-depth: 0`), so the version they print depends on which tags exist **on the `github` remote** — not on your local clone or on `gitea`. `git push <branch>` does **not** push tags; push them explicitly to **each** remote (`gitea` and `github`). A tag that only lives on `gitea` is invisible to the GitHub build.
 
-##### The tag must also exist on the remote that CI builds from (multi-remote gotcha)
+If you already tagged `main` (or `develop` still shows the old version), recover without re-tagging:
 
-`git describe` names a tag **ref**, not just a commit — so the back-merge is *necessary but not sufficient*. The develop image is built by GitHub Actions (`develop.yml`, `actions/checkout` with `fetch-depth: 0`, then `git describe --tags --always`), so the version it prints depends on which tags exist **on the `github` remote**, not on your local clone or on `gitea`.
+1. Make the tagged commit reachable from `develop` — either back-merge `main → develop` (`git checkout develop && git merge --no-ff main`), or confirm the tagged commit is already an ancestor of `develop`.
+2. Make sure the tag exists on `github`: compare `git ls-remote --tags github` with `gitea`, and push the missing one (`git push github vX.Y.Z` / `git push gitea vX.Y.Z`). Pushing a `v*` tag to `github` also fires `release.yml` — expected, just be aware.
+3. Re-run the develop build (`gh workflow run Develop`, or push any commit to `develop`) so `git describe` re-resolves with the tag now in scope.
 
-This repo has two writable remotes — `gitea` (canonical, where commits land) and `github` (where the `:develop` and release images are built) — plus `upstream` (docmost, never push). **`git push <branch>` does NOT push tags**; tags must be pushed explicitly and *to each remote separately*. A release tag that only lives on `gitea` is invisible to the GitHub Actions build: even with the tagged commit fully in `develop`'s history (step 7 done), `git describe` on the GitHub runner falls back to the previous tag it *does* have, so the develop image keeps showing e.g. `v0.91.0-NNN` while `git describe` locally already says `v0.93.0-NN`.
-
-Fix / checklist when develop still shows the old version after a back-merge:
-
-1. Confirm the tag is missing on github: `git ls-remote --tags github` (compare with `gitea`).
-2. Push it there: `git push github vX.Y.Z` (and `git push gitea vX.Y.Z` if it is missing on gitea too). Note: pushing a `v*` tag to `github` also triggers `release.yml` (multi-arch GHCR images + draft Release) — expected, but be aware.
-3. Re-run the develop build (`gh workflow run Develop`, or push any commit to `develop`) so `git describe` re-resolves with the tag now present.
-
-(The `git push origin ...` in steps 6–7 above is shorthand — there is no `origin` remote here; substitute `gitea` **and** `github` as appropriate, and always push release tags to both.)
+(There is no `origin` remote here — push to `gitea` **and** `github` explicitly, and always push release tags to both.)
 
 ## Planning docs
 

CHANGELOG.md

@@ -10,8 +10,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.94.0] - 2026-06-26
+
+This release makes AI chat durable and fast: assistant turns are persisted to
+the database step by step and exported server-side, the desktop app no longer
+freezes at 100% CPU on long agent runs, and MCP writes are badged with
+unspoofable AI attribution. It also reworks footnotes (Pandoc-style reuse and
+per-reference back-links), hardens page moves and duplication against cycles
+and lost edits, and caps the anonymous public-share assistant with a
+per-workspace rolling-day token budget.
+
 ### Added
 
+- **Custom pretty-links for shared pages (`/l/:alias`).** A page editor can give
+  any publicly shared page a short, memorable, workspace-scoped vanity address
+  backed by a new `share_aliases` table. Hitting `/l/<alias>` issues a `302`
+  (never `301`, since the target is retargetable) to the canonical
+  `/share/<key>/p/<slug>` page; an unknown, dangling, or no-longer-readable alias
+  serves the plain SPA index so that the existence of a name never leaks. An
+  alias can be moved to another page (with a confirm-reassign guard) and the
+  foreign key is `ON DELETE SET NULL`, so deleting the target leaves a dangling
+  alias any workspace member can reclaim. (#205)
+
 - **Persistent AI-chat history as the source of truth + server-side export.**
   An assistant turn is now persisted to the database step by step: the row is
   inserted upfront as `streaming` and updated as each agent step finishes, then
@@ -78,6 +98,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **AI chat: the desktop app no longer freezes at 100% CPU on long agent runs.**
+  `useChat` re-rendered on every streamed token and `MessageItem`/`ReasoningBlock`
+  re-parsed the whole transcript markdown (marked + DOMPurify) on every delta, so
+  per-turn work grew quadratically and saturated the main thread. The stream is now
+  throttled (`experimental_throttle`) to ~20 Hz and each finalized message row /
+  markdown part / reasoning block is memoized, so a long turn no longer re-parses
+  already-finished content. (#182)
 - **Editor: caret/selection landed on the wrong line when clicking inside code
   blocks and footnotes.** The affected NodeViews rendered their non-editable
   chrome (language menu, footnotes heading, footnote number marker) before the
@@ -92,6 +119,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   no longer froze on the previous step's authoritative usage; the current step's
   estimate is combined per-component with `max`, so the count rises smoothly and
   never jumps backwards. (#163)
+- **AI chat: "New chat" during a streaming first turn now resets the whole
+  chat, not just the role badge.** Starting a new chat mid-stream cleared the
+  header but left the in-flight turn's messages behind, so the fresh chat opened
+  pre-populated with the previous conversation; it now fully resets. (#161)
+- **AI chat: a dropped tool argument now yields an actionable error.** When the
+  model omitted a required parameter (typically `pageId`) in a parallel/batch
+  tool call, the assistant forwarded zod's raw "expected string, received
+  undefined" text; tool inputs now return a message naming each missing/invalid
+  parameter (the JSON Schema contract is unchanged and nothing is backfilled).
+  (#190)
+- **Page move: cycle checks are now atomic and depth-bounded.** Moving a page
+  under one of its own descendants is rejected in the same transaction as the
+  update (closing a TOCTOU window where two concurrent A→B / B→A moves could
+  form a cycle), and the recursive tree-traversal CTEs carry a cycle/depth guard
+  so a pre-existing cycle can no longer spin a query. (#207)
+- **Page/editor robustness batch.** Duplicating a page now copies shared
+  attachments for every referencing page (not just the first); colliding block
+  ids are de-duplicated on import/normalize so MCP addressed edits can't hit the
+  wrong node; transient collab store failures are retried so autosave edits
+  aren't lost; and an out-of-order tree move no longer drops the moved subtree.
+  (#206)
+
+### Security
+
+- **Public share AI: per-workspace rolling-day token budget.** The anonymous
+  share assistant now caps a workspace's actual token spend (input + output,
+  summed across every accepted turn) over a trailing day, on top of the hourly
+  request cap — so a caller who evades the per-IP throttle still cannot run up
+  the owner's provider bill without bound. Cluster-wide via Redis and FAILS
+  CLOSED if Redis is down; default 1,000,000 tokens/day, overridable via
+  `SHARE_AI_WORKSPACE_TOKEN_BUDGET_PER_DAY`. (#159)
 
 ## [0.93.0] - 2026-06-21
 

README.md

@@ -114,7 +114,7 @@ community feature, with no enterprise license. Open it from the page header; the
 - 🔭 **Viewer comments** — let read-only viewers leave comments.
 - 🔭 **Password-protected pages** — protect individual pages / shares with a password.
 - 🔭 **Windows / Linux app** — native desktop app for Windows and Linux.
-- 🔭 **Mobile app** — mobile apps (iOS first, Android to follow), reusing the existing responsive web UI and editor via a Capacitor wrapper, with offline planned for later. See [docs/mobile-app-plan.md](docs/mobile-app-plan.md).
+- 🔭 **Mobile app** — mobile apps (iOS first, Android to follow), reusing the existing responsive web UI and editor via a Capacitor wrapper, with offline planned for later. See [issue #195](https://gitea.vvzvlad.xyz/vvzvlad/gitmost/issues/195).
 - 🔭 **Offline mode** — offline sync & PWA support.
 - 🔭 **Editor & UX improvements** — blocks inside tables (lists, to-do items), column layout, additional heading levels, highlight blocks, custom emoji in callouts, floating images, anchor links for page mentions, toggles (shared-page width, aside/sidebar, spellcheck, ligatures), sanitized space-tree export, and mentions in breadcrumbs.
 

README.ru.md

@@ -115,7 +115,7 @@ real-time-коллаборации Docmost, поэтому запись нико
 - 🔭 **Комментарии зрителей** — возможность комментировать для пользователей с доступом только на чтение.
 - 🔭 **Защищённые паролем страницы** — защита отдельных страниц / шар паролем.
 - 🔭 **Приложение для Windows / Linux** — нативное десктоп-приложение для Windows и Linux.
-- 🔭 **Мобильное приложение** — мобильные приложения (iOS обязательно, Android как пойдёт) на базе существующей адаптивной веб-версии и редактора через обёртку Capacitor; оффлайн запланирован на будущее. См. [docs/mobile-app-plan.md](docs/mobile-app-plan.md).
+- 🔭 **Мобильное приложение** — мобильные приложения (iOS обязательно, Android как пойдёт) на базе существующей адаптивной веб-версии и редактора через обёртку Capacitor; оффлайн запланирован на будущее. См. [issue #195](https://gitea.vvzvlad.xyz/vvzvlad/gitmost/issues/195).
 - 🔭 **Офлайн-режим** — офлайн-синхронизация и поддержка PWA.
 - 🔭 **Улучшения редактора и UX** — блоки внутри таблиц (списки, чек-листы), колоночная вёрстка, дополнительные уровни заголовков, highlight-блоки, кастомные эмодзи в callout-ах, плавающие изображения, anchor-ссылки на упоминания страниц, тоглы (ширина шары, aside/сайдбар, spellcheck, лигатуры), санитизация экспорта дерева спейса и mentions в хлебных крошках.
 

apps/client/package.json

@@ -1,7 +1,7 @@
 {
   "name": "client",
   "private": true,
-  "version": "0.93.0",
+  "version": "0.94.1",
   "scripts": {
     "dev": "node scripts/copy-vad-assets.mjs && vite",
     "build": "node scripts/copy-vad-assets.mjs && tsc && vite build",

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

@@ -715,6 +715,8 @@
   "Test": "Test",
   "Available tools": "Available tools",
   "No tools available": "No tools available",
+  "Failed": "Failed",
+  "OK · {{n}}": "OK · {{n}}",
   "Created successfully": "Created successfully",
   "Deleted successfully": "Deleted successfully",
   "Clear": "Clear",
@@ -1167,8 +1169,9 @@
   "Pick an agent role whose persona the public assistant adopts. The safety rules always still apply.": "Pick an agent role whose persona the public assistant adopts. The safety rules always still apply.",
   "Built-in assistant persona": "Built-in assistant persona",
   "Minimize": "Minimize",
-  "Current context size": "Current context size",
-  "Tokens generated this turn": "Tokens generated this turn",
+  "Context size / model limit": "Context size / model limit",
+  "Context window (tokens)": "Context window (tokens)",
+  "Shown as used / total in the chat header. Leave empty to hide the limit.": "Shown as used / total in the chat header. Leave empty to hide the limit.",
   "AI agent": "AI agent",
   "Take a look at the current document": "Take a look at the current document",
   "AI agent is typing…": "AI agent is typing…",
@@ -1319,5 +1322,15 @@
   "Protocol": "Protocol",
   "How chat requests are sent and how reasoning is surfaced": "How chat requests are sent and how reasoning is surfaced",
   "OpenAI-compatible (surfaces reasoning)": "OpenAI-compatible (surfaces reasoning)",
-  "OpenAI (official)": "OpenAI (official)"
+  "OpenAI (official)": "OpenAI (official)",
+  "Custom address": "Custom address",
+  "A short, memorable link you can point at any shared page.": "A short, memorable link you can point at any shared page.",
+  "Use 2-60 lowercase letters, digits and hyphens": "Use 2-60 lowercase letters, digits and hyphens",
+  "This address is already in use": "This address is already in use",
+  "Move custom address?": "Move custom address?",
+  "Move here": "Move here",
+  "The address \"{{alias}}\" currently points to \"{{title}}\". Move it to this page?": "The address \"{{alias}}\" currently points to \"{{title}}\". Move it to this page?",
+  "The address \"{{alias}}\" is already in use. Move it to this page?": "The address \"{{alias}}\" is already in use. Move it to this page?",
+  "Failed to set custom address": "Failed to set custom address",
+  "Failed to remove custom address": "Failed to remove custom address"
 }

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

@@ -704,13 +704,19 @@
   "Ask the AI agent…": "Спросите AI-агента…",
   "Copy chat": "Копировать чат",
   "Created successfully": "Успешно создано",
-  "Current context size": "Текущий размер контекста",
-  "Tokens generated this turn": "Токенов сгенерировано за ход",
+  "Context size / model limit": "Размер контекста / лимит модели",
+  "Context window (tokens)": "Окно контекста (токены)",
+  "Shown as used / total in the chat header. Leave empty to hide the limit.": "Показывается в шапке чата как использовано / всего. Пусто — лимит скрыт.",
   "Delete this chat?": "Удалить этот чат?",
   "Deleted successfully": "Успешно удалено",
   "Edited by AI agent on behalf of {{name}}": "Отредактировано AI-агентом от имени {{name}}",
   "Failed to delete chat": "Не удалось удалить чат",
   "Failed to rename chat": "Не удалось переименовать чат",
+  "Failed": "Ошибка",
+  "OK · {{n}}": "OK · {{n}}",
+  "Test": "Тест",
+  "No tools available": "Инструменты недоступны",
+  "Available tools": "Доступные инструменты",
   "Minimize": "Свернуть",
   "No chats yet.": "Чатов пока нет.",
   "Send": "Отправить",
@@ -1169,5 +1175,15 @@
   "Protocol": "Протокол",
   "How chat requests are sent and how reasoning is surfaced": "Как отправляются запросы чата и как показывается reasoning",
   "OpenAI-compatible (surfaces reasoning)": "OpenAI-совместимый (показывает reasoning)",
-  "OpenAI (official)": "OpenAI (официальный)"
+  "OpenAI (official)": "OpenAI (официальный)",
+  "Custom address": "Пользовательский адрес",
+  "A short, memorable link you can point at any shared page.": "Короткая запоминающаяся ссылка, которую можно направить на любую опубликованную страницу.",
+  "Use 2-60 lowercase letters, digits and hyphens": "Используйте 2–60 строчных букв, цифр и дефисов",
+  "This address is already in use": "Этот адрес уже занят",
+  "Move custom address?": "Переместить пользовательский адрес?",
+  "Move here": "Переместить сюда",
+  "The address \"{{alias}}\" currently points to \"{{title}}\". Move it to this page?": "Адрес «{{alias}}» сейчас указывает на «{{title}}». Переместить его на эту страницу?",
+  "The address \"{{alias}}\" is already in use. Move it to this page?": "Адрес «{{alias}}» уже используется. Переместить его на эту страницу?",
+  "Failed to set custom address": "Не удалось задать пользовательский адрес",
+  "Failed to remove custom address": "Не удалось удалить пользовательский адрес"
 }

apps/client/src/features/ai-chat/components/ai-chat-window.tsx

@@ -45,6 +45,7 @@ import {
   shouldCollapseOnOutsidePointer,
   isHeaderClick,
 } from "@/features/ai-chat/utils/collapse-helpers.ts";
+import { selectContextBadge } from "@/features/ai-chat/utils/context-badge.ts";
 import { useClipboard } from "@/hooks/use-clipboard";
 import { notifications } from "@mantine/notifications";
 import classes from "@/features/ai-chat/components/ai-chat-window.module.css";
@@ -161,12 +162,6 @@ export default function AiChatWindow() {
   const { data: messageRows, isLoading: messagesLoading } =
     useAiChatMessagesQuery(activeChatId ?? undefined);
 
-  // Live turn-token total (reasoning + output) for the in-flight turn, pushed up
-  // (THROTTLED to ~8 Hz inside ChatThread) so the header badge ticks mid-stream.
-  // `null` means no turn is in flight -> the badge falls back to the persisted
-  // context size below.
-  const [liveTurnTokens, setLiveTurnTokens] = useState<number | null>(null);
-
   // The page the user is currently viewing. AiChatWindow lives in a pathless
   // parent layout route, so useParams() can't see :pageSlug. Match the full
   // pathname against the authenticated page route instead so "the current page"
@@ -193,6 +188,7 @@ export default function AiChatWindow() {
   const {
     threadKey,
     waitingForHistory,
+    startFreshThread,
     onTurnFinished,
     onServerChatId,
     cancelPendingAdoption,
@@ -215,12 +211,25 @@ export default function AiChatWindow() {
   // just-failed chat after they chose a fresh one.
   const startNewChat = useCallback((): void => {
     cancelPendingAdoption();
+    // Force a fresh, empty thread UNCONDITIONALLY (#161). Pressing "New chat"
+    // while a brand-new chat's first turn is still streaming leaves activeChatId
+    // null (the real id is adopted only at turn end), so setActiveChatId(null)
+    // alone is a no-op and the reconciler never remounts — the chat/stream/history
+    // would persist and only the role badge would drop. This always remounts the
+    // thread into a clean new chat.
+    startFreshThread();
     setActiveChatId(null);
     setHistoryOpen(false);
     setDraft("");
     // Default the picker back to "Universal assistant" for the fresh chat.
     setSelectedRoleId(null);
-  }, [cancelPendingAdoption, setActiveChatId, setDraft, setSelectedRoleId]);
+  }, [
+    cancelPendingAdoption,
+    startFreshThread,
+    setActiveChatId,
+    setDraft,
+    setSelectedRoleId,
+  ]);
 
   const selectChat = useCallback(
     (chatId: string): void => {
@@ -287,24 +296,19 @@ export default function AiChatWindow() {
   // shipped; older rows fall back to that turn's `usage` total. NOTE: reflects
   // PERSISTED rows (updates on chat open/switch); it does not tick live
   // mid-stream — acceptable for v1.
-  const contextTokens = useMemo(() => {
-    if (!activeChatId || !messageRows) return 0;
-    for (let i = messageRows.length - 1; i >= 0; i--) {
-      const meta = messageRows[i].metadata;
-      if (!meta) continue;
-      if (typeof meta.contextTokens === "number" && meta.contextTokens > 0) {
-        return meta.contextTokens;
-      }
-      const usage = meta.usage;
-      if (usage) {
-        const fallback =
-          usage.totalTokens ??
-          (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);
-        if (fallback > 0) return fallback;
-      }
-    }
-    return 0;
-  }, [activeChatId, messageRows]);
+  //
+  // The denominator `maxContextTokens` (the model's configured max window) is
+  // derived in the SAME backward scan: it is stamped alongside `contextTokens`
+  // on a completed turn, but the numerator and denominator are taken from the
+  // most recent row carrying EACH value independently — they may land on
+  // different rows (e.g. a fresh error row can carry contextTokens but not
+  // maxContextTokens), so we keep scanning for whichever is still unset. 0 when
+  // no row has it (older rows, or no admin-configured limit) — the badge then
+  // shows just the current size with no denominator.
+  const { contextTokens, maxContextTokens } = useMemo(
+    () => selectContextBadge(activeChatId ? messageRows : undefined),
+    [activeChatId, messageRows],
+  );
 
   // On (re)open, settle the geometry before paint (useLayoutEffect → no
   // first-frame jump): compute an initial top-right placement the first time,
@@ -495,20 +499,17 @@ export default function AiChatWindow() {
         )}
 
         <div style={{ flex: 1, display: "flex", justifyContent: "center" }}>
-          {/* While a turn streams, show the LIVE turn-token count (ticks ~8 Hz);
-              once it finishes, fall back to the persisted context size. Require
-              > 0 so the very first emit (an empty tail message, count 0) does not
-              flash a "0" badge before any token streams in (#151 review). */}
-          {liveTurnTokens !== null && liveTurnTokens > 0 ? (
-            <Tooltip label={t("Tokens generated this turn")} withArrow>
-              <span className={classes.badge}>
-                {formatTokens(liveTurnTokens)}
-              </span>
-            </Tooltip>
-          ) : contextTokens > 0 ? (
-            <Tooltip label={t("Current context size")} withArrow>
+          {/* Always show the persisted "current / max" context. The denominator
+              (the admin-configured model limit) is appended only when known;
+              not clamped when current > max (shown as-is, e.g. "210k / 200k").
+              Hidden entirely until a turn has recorded a context figure. */}
+          {contextTokens > 0 ? (
+            <Tooltip label={t("Context size / model limit")} withArrow>
               <span className={classes.badge}>
                 {formatTokens(contextTokens)}
+                {maxContextTokens > 0
+                  ? ` / ${formatTokens(maxContextTokens)}`
+                  : ""}
               </span>
             </Tooltip>
           ) : null}
@@ -622,6 +623,7 @@ export default function AiChatWindow() {
           ) : (
             <ChatThread
               key={threadKey}
+              threadKey={threadKey}
               chatId={activeChatId}
               initialRows={activeChatId ? messageRows : []}
               openPage={openPage}
@@ -634,7 +636,6 @@ export default function AiChatWindow() {
               assistantName={currentRole?.name}
               onTurnFinished={onTurnFinished}
               onServerChatId={onServerChatId}
-              onLiveTurnTokens={setLiveTurnTokens}
             />
           )}
         </div>

apps/client/src/features/ai-chat/components/chat-thread.tsx

@@ -20,7 +20,6 @@ import {
 } from "@/features/ai-chat/utils/role-launch.ts";
 import { describeChatError } from "@/features/ai-chat/utils/error-message.ts";
 import { extractServerChatId } from "@/features/ai-chat/utils/adopt-chat-id.ts";
-import { liveTurnTokens } from "@/features/ai-chat/utils/count-stream-tokens.ts";
 import {
   dequeue,
   enqueueMessage,
@@ -29,6 +28,14 @@ import {
 } from "@/features/ai-chat/utils/queue-helpers.ts";
 import classes from "@/features/ai-chat/components/ai-chat.module.css";
 
+// Throttle how often the streamed `messages` state triggers a re-render. Without
+// it, useChat updates state on EVERY token, so the whole transcript's markdown
+// (marked + DOMPurify) is re-parsed per token — on a long agent run that grows
+// into a quadratic CPU storm that pins the main thread and freezes the UI.
+// ~50ms (20 Hz) keeps streaming visually smooth while decoupling re-render cost
+// from the token rate.
+const STREAM_THROTTLE_MS = 50;
+
 /** The page the user is currently viewing, sent as chat context. */
 export interface OpenPageContext {
   id: string;
@@ -38,6 +45,11 @@ export interface OpenPageContext {
 interface ChatThreadProps {
   /** The open chat id, or null for a brand-new (not-yet-created) chat. */
   chatId: string | null;
+  /** This thread's mount key (the same value the parent uses as React `key`).
+   *  Forwarded to onTurnFinished so the session can tell a turn finishing on the
+   *  CURRENT thread from one ABANDONED by New chat mid-stream — whose onFinish/
+   *  onError still fire after unmount and must not adopt the abandoned chat (#161). */
+  threadKey?: string;
   /** Persisted rows to seed initial messages (existing chats only). */
   initialRows?: IAiChatMessageRow[];
   /** The page currently open in the workspace, or null on a non-page route.
@@ -59,20 +71,16 @@ interface ChatThreadProps {
   /** Called when a turn finishes; the parent refreshes the chat list and, for a
    *  new chat, adopts the freshly created chat id. `serverChatId` is the
    *  authoritative id the server streamed on the assistant message metadata, or
-   *  undefined on a failed turn — see adopt-chat-id.ts for the full #137 design. */
-  onTurnFinished: (serverChatId?: string) => void;
+   *  undefined on a failed turn — see adopt-chat-id.ts for the full #137 design.
+   *  `finishingThreadKey` (this thread's mount key) lets the session ignore a turn
+   *  finishing on a thread already abandoned by New chat mid-stream (#161). */
+  onTurnFinished: (serverChatId?: string, finishingThreadKey?: string) => void;
   /** Called EARLY (at the stream's `start` chunk) with the authoritative server
    *  chat id streamed on the assistant message metadata, so a brand-new chat
    *  adopts its real id WHILE the first turn is still streaming (#174 — makes the
    *  Copy/export button available mid-stream). Distinct from onTurnFinished,
    *  which fires only at the terminal outcome. */
   onServerChatId?: (serverChatId?: string) => void;
-  /** Reports the live turn-token total (reasoning + output) for the in-flight
-   *  turn so the parent can show a header badge that ticks mid-stream. THROTTLED
-   *  here (~8 Hz) so the parent re-renders a handful of times a second, not on
-   *  every streamed delta. Called with `null` when no turn is in flight (the
-   *  parent then reverts the badge to the persisted context size). */
-  onLiveTurnTokens?: (tokens: number | null) => void;
 }
 
 /**
@@ -109,6 +117,7 @@ function rowToUiMessage(row: IAiChatMessageRow): UIMessage {
  */
 export default function ChatThread({
   chatId,
+  threadKey,
   initialRows,
   openPage,
   roleId,
@@ -117,7 +126,6 @@ export default function ChatThread({
   assistantName,
   onTurnFinished,
   onServerChatId,
-  onLiveTurnTokens,
 }: ChatThreadProps) {
   const { t } = useTranslation();
 
@@ -246,6 +254,8 @@ export default function ChatThread({
     id: chatStoreId,
     messages: initialMessages,
     transport,
+    // See STREAM_THROTTLE_MS — bounds re-render/markdown-reparse frequency.
+    experimental_throttle: STREAM_THROTTLE_MS,
     // `onFinish` (ai@6 useChat) fires from a `finally` on EVERY terminal outcome
     // — success, user Stop/abort (`isAbort`), network drop (`isDisconnect`), and
     // stream error (`isError`). Keep calling `onTurnFinished()` on all of them
@@ -257,8 +267,10 @@ export default function ChatThread({
     onFinish: ({ message, isAbort, isDisconnect, isError }) => {
       // Forward the authoritative server chatId (streamed on the assistant
       // message metadata) so the parent adopts the REAL created chat id for a new
-      // chat — see adopt-chat-id.ts for the full #137 design.
-      onTurnFinished(extractServerChatId(message));
+      // chat — see adopt-chat-id.ts for the full #137 design. `threadKey` lets the
+      // session ignore this finish if it belongs to a thread abandoned by New chat
+      // mid-stream (#161).
+      onTurnFinished(extractServerChatId(message), threadKey);
       // Show a neutral "stopped" marker for an aborted turn; the red error banner
       // (via `error`) already covers isError, and a clean finish clears any marker.
       if (isError) setStopNotice(null);
@@ -279,7 +291,7 @@ export default function ChatThread({
       // Surface the raw failure in the browser console (devtools) for debugging;
       // the UI separately shows a friendly classified banner (see errorView).
       console.error("AI chat stream error:", streamError);
-      onTurnFinished();
+      onTurnFinished(undefined, threadKey);
     },
   });
 
@@ -328,53 +340,6 @@ export default function ChatThread({
   // the SAME on-screen banner text can be mirrored into the export (issue #160).
   const errorView = error ? describeChatError(error.message ?? "", t) : null;
 
-  // Report the live turn-token total to the parent header badge, THROTTLED to
-  // ~8 Hz so the parent re-renders a few times a second instead of on every
-  // streamed delta. The tail assistant message's reasoning+output (estimate while
-  // streaming, authoritative once a step reports usage) is the live figure. When
-  // the turn ends we emit a final exact value, then `null` so the parent reverts
-  // the badge to the persisted context size.
-  const lastEmitRef = useRef(0);
-  const emitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  useEffect(() => {
-    if (!onLiveTurnTokens) return;
-    if (!isStreaming) {
-      // Turn ended (or never started): clear any pending throttle and revert.
-      if (emitTimerRef.current) {
-        clearTimeout(emitTimerRef.current);
-        emitTimerRef.current = null;
-      }
-      lastEmitRef.current = 0;
-      onLiveTurnTokens(null);
-      return;
-    }
-    const tail = messages[messages.length - 1];
-    const live = tail?.role === "assistant" ? liveTurnTokens(tail) : null;
-    const total = live ? live.reasoning + live.output : 0;
-    const now = Date.now();
-    const MIN_INTERVAL = 120; // ms (~8 Hz)
-    const elapsed = now - lastEmitRef.current;
-    if (elapsed >= MIN_INTERVAL) {
-      lastEmitRef.current = now;
-      onLiveTurnTokens(total);
-    } else if (!emitTimerRef.current) {
-      // Schedule a trailing emit so the FINAL value of a burst is not dropped.
-      emitTimerRef.current = setTimeout(() => {
-        emitTimerRef.current = null;
-        lastEmitRef.current = Date.now();
-        onLiveTurnTokens(total);
-      }, MIN_INTERVAL - elapsed);
-    }
-  }, [messages, isStreaming, onLiveTurnTokens]);
-
-  // Clear any pending throttle timer on unmount (chat switch via `key`) so a
-  // trailing emit can't fire into a torn-down thread's parent.
-  useEffect(() => {
-    return () => {
-      if (emitTimerRef.current) clearTimeout(emitTimerRef.current);
-    };
-  }, []);
-
   // A role was picked with autoStart=false: the role is bound but NOTHING was
   // sent, so chatId stays null and the empty state would keep showing the cards.
   // This flag hides the cards and reveals the composer (with the role indicated)

apps/client/src/features/ai-chat/components/message-item-memo.test.tsx

@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from "vitest";
+import { render } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import type { UIMessage } from "@ai-sdk/react";
+
+// Stub react-i18next (the component reads `useTranslation`). Mirrors the stub in
+// reasoning-block.test.tsx.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+// Spy on `renderChatMarkdown` so we can count parse calls per text. We keep every
+// OTHER named export of markdown.ts intact via `importActual`, and override only
+// `renderChatMarkdown` with a `vi.fn()` that returns simple HTML so the component
+// still renders. This is the seam that proves the MarkdownPart memo works: a
+// finalized text part must NOT be re-parsed on a later streamed delta.
+// `vi.hoisted` so the spy exists when the hoisted `vi.mock` factory runs.
+const { renderChatMarkdownSpy } = vi.hoisted(() => ({
+  renderChatMarkdownSpy: vi.fn((text: string) => `<p>${text}</p>`),
+}));
+vi.mock("@/features/ai-chat/utils/markdown.ts", async () => {
+  const actual = await vi.importActual<
+    typeof import("@/features/ai-chat/utils/markdown.ts")
+  >("@/features/ai-chat/utils/markdown.ts");
+  return { ...actual, renderChatMarkdown: renderChatMarkdownSpy };
+});
+
+import MessageItem from "./message-item";
+
+// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
+
+const msg = (parts: UIMessage["parts"]): UIMessage =>
+  ({ id: "m1", role: "assistant", parts }) as UIMessage;
+
+const renderRow = (message: UIMessage) =>
+  render(
+    <MantineProvider>
+      <MessageItem message={message} />
+    </MantineProvider>,
+  );
+
+/** Count how many spy calls parsed exactly `text` (filtering by the first arg). */
+const callsFor = (text: string) =>
+  renderChatMarkdownSpy.mock.calls.filter((c) => c[0] === text).length;
+
+describe("MessageItem markdown memoization", () => {
+  it("does not re-parse finalized text parts when only a tail part grows", () => {
+    renderChatMarkdownSpy.mockClear();
+
+    // Two finalized text parts.
+    const first = msg([
+      { type: "text", text: "alpha" },
+      { type: "text", text: "beta" },
+    ]);
+    const { rerender } = renderRow(first);
+
+    // Both finalized parts parsed exactly once on the initial render.
+    expect(callsFor("alpha")).toBe(1);
+    expect(callsFor("beta")).toBe(1);
+
+    // A streamed delta: a NEW message object where only a third tail part grows;
+    // the first two parts' text is byte-identical.
+    const next = msg([
+      { type: "text", text: "alpha" },
+      { type: "text", text: "beta" },
+      { type: "text", text: "gamm" },
+    ]);
+    rerender(
+      <MantineProvider>
+        <MessageItem message={next} />
+      </MantineProvider>,
+    );
+
+    // The finalized parts hit the MarkdownPart memo: still parsed at most once
+    // each across BOTH renders (the resilient invariant). The only new parse is
+    // for the changed/added tail part.
+    expect(callsFor("alpha")).toBe(1);
+    expect(callsFor("beta")).toBe(1);
+    expect(callsFor("gamm")).toBe(1);
+  });
+});

apps/client/src/features/ai-chat/components/message-item.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from "vitest";
+import type { UIMessage } from "@ai-sdk/react";
+
+// Stub react-i18next: importing the component module pulls in `useTranslation`,
+// and we only exercise the pure `arePropsEqual` comparator (no rendering), so a
+// minimal `t` that echoes the key is enough. Mirrors the stub in
+// reasoning-block.test.tsx.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import { arePropsEqual } from "./message-item";
+
+/**
+ * Tests for `arePropsEqual`, the `React.memo` comparator for MessageItem. It must
+ * return false on any visible prop/content change (so the row re-renders) and
+ * true when nothing visible changed (so a finalized row is skipped). A FIXED
+ * message id is used so a content-identical clone yields an equal signature.
+ */
+const msg = (parts: UIMessage["parts"]): UIMessage =>
+  ({ id: "m1", role: "assistant", parts }) as UIMessage;
+
+const props = (
+  message: UIMessage,
+  over: Record<string, unknown> = {},
+) => ({
+  message,
+  showCitations: true,
+  neutralizeInternalLinks: false,
+  assistantName: "AI",
+  ...over,
+});
+
+describe("arePropsEqual", () => {
+  it("returns false when showCitations differs", () => {
+    const m = msg([{ type: "text", text: "answer" }]);
+    expect(
+      arePropsEqual(props(m), props(m, { showCitations: false })),
+    ).toBe(false);
+  });
+
+  it("returns false when neutralizeInternalLinks differs", () => {
+    const m = msg([{ type: "text", text: "answer" }]);
+    expect(
+      arePropsEqual(props(m), props(m, { neutralizeInternalLinks: true })),
+    ).toBe(false);
+  });
+
+  it("returns false when assistantName differs", () => {
+    const m = msg([{ type: "text", text: "answer" }]);
+    expect(
+      arePropsEqual(props(m), props(m, { assistantName: "Other" })),
+    ).toBe(false);
+  });
+
+  it("returns true on the identity fast path (same message object, equal props)", () => {
+    const m = msg([{ type: "text", text: "answer" }]);
+    expect(arePropsEqual(props(m), props(m))).toBe(true);
+  });
+
+  it("returns true for the same content in a different message object", () => {
+    const a = msg([{ type: "text", text: "answer" }]);
+    const b = msg([{ type: "text", text: "answer" }]);
+    expect(a).not.toBe(b);
+    expect(arePropsEqual(props(a), props(b))).toBe(true);
+  });
+
+  it("returns false when content changed in a different message object", () => {
+    const a = msg([{ type: "text", text: "answer" }]);
+    const b = msg([{ type: "text", text: "answer grown" }]);
+    expect(arePropsEqual(props(a), props(b))).toBe(false);
+  });
+});

apps/client/src/features/ai-chat/components/message-item.tsx

@@ -1,3 +1,4 @@
+import { memo } from "react";
 import { Box, Text } from "@mantine/core";
 import { useTranslation } from "react-i18next";
 import type { UIMessage } from "@ai-sdk/react";
@@ -10,6 +11,7 @@ import { assistantMessageHasVisibleContent } from "@/features/ai-chat/utils/mess
 import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
 import { resolveAssistantName } from "@/features/ai-chat/utils/assistant-name.ts";
 import { reasoningTokensForPart } from "@/features/ai-chat/utils/reasoning-tokens.ts";
+import { messageSignature } from "@/features/ai-chat/utils/message-signature.ts";
 import { describeChatError } from "@/features/ai-chat/utils/error-message.ts";
 import classes from "@/features/ai-chat/components/ai-chat.module.css";
 
@@ -34,6 +36,39 @@ interface MessageItemProps {
   assistantName?: string;
 }
 
+/**
+ * One assistant text part rendered as sanitized markdown. Memoized on its inputs
+ * so a finalized text part is NOT re-parsed on every streamed delta: during a
+ * turn only the actively-growing tail part changes its `text`, so every earlier
+ * part hits the memo and skips the expensive marked + DOMPurify pass. Props are
+ * primitives, so React.memo's default shallow compare is exactly right (the
+ * `text` string is compared by value).
+ */
+const MarkdownPart = memo(function MarkdownPart({
+  text,
+  neutralizeInternalLinks,
+}: {
+  text: string;
+  neutralizeInternalLinks: boolean;
+}) {
+  const html = renderChatMarkdown(text, { neutralizeInternalLinks });
+  if (html) {
+    return (
+      <div
+        className={classes.markdown}
+        // Sanitized by renderChatMarkdown (DOMPurify) before insertion.
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    );
+  }
+  // Fallback when markdown could not render synchronously: raw text.
+  return (
+    <Text className={classes.markdown} style={{ whiteSpace: "pre-wrap" }}>
+      {text}
+    </Text>
+  );
+});
+
 /**
  * Render a single UIMessage by iterating its `parts`:
  *  - `text` parts -> sanitized markdown.
@@ -41,12 +76,13 @@ interface MessageItemProps {
  * Other part kinds (reasoning, sources, files, step-start) are ignored for v1.
  * User messages render their text as a right-aligned plain bubble.
  *
- * This component is intentionally NOT memoized: `useChat` replaces the streaming
- * assistant message with a freshly cloned object on every streamed delta, so the
- * `message` prop identity (and its `parts`) changes each tick. Re-rendering the
- * text parts on each delta is what makes the answer stream in progressively.
+ * This component is memoized (see `arePropsEqual` at the bottom) on a cheap
+ * per-message content signature: the streaming TAIL message's signature changes
+ * on each delta so it still re-renders and streams in, while finalized rows are
+ * skipped. Each text part's markdown is itself memoized via `MarkdownPart`, so a
+ * long turn no longer re-parses the whole transcript on every token.
  */
-export default function MessageItem({
+function MessageItem({
   message,
   showCitations = true,
   neutralizeInternalLinks = false,
@@ -109,24 +145,12 @@ export default function MessageItem({
           // starts with an empty text part before the first token arrives); the
           // typing indicator covers that gap until real content streams in.
           if (!part.text.trim()) return null;
-          const html = renderChatMarkdown(part.text, {
-            neutralizeInternalLinks,
-          });
-          if (html) {
-            return (
-              <div
-                key={index}
-                className={classes.markdown}
-                // Sanitized by renderChatMarkdown (DOMPurify) before insertion.
-                dangerouslySetInnerHTML={{ __html: html }}
-              />
-            );
-          }
-          // Fallback when markdown could not render synchronously: raw text.
           return (
-            <Text key={index} className={classes.markdown} style={{ whiteSpace: "pre-wrap" }}>
-              {part.text}
-            </Text>
+            <MarkdownPart
+              key={index}
+              text={part.text}
+              neutralizeInternalLinks={neutralizeInternalLinks}
+            />
           );
         }
 
@@ -177,3 +201,26 @@ export default function MessageItem({
     </Box>
   );
 }
+
+/** Skip re-rendering a message whose visible content is unchanged. The streaming
+ *  TAIL message gets a fresh object whose signature changes each delta, so it
+ *  still re-renders and streams in; every FINALIZED message is skipped, turning a
+ *  per-token whole-transcript re-render into a tail-only one. */
+export function arePropsEqual(
+  prev: MessageItemProps,
+  next: MessageItemProps,
+): boolean {
+  if (
+    prev.showCitations !== next.showCitations ||
+    prev.neutralizeInternalLinks !== next.neutralizeInternalLinks ||
+    prev.assistantName !== next.assistantName
+  ) {
+    return false;
+  }
+  // Fast path: identical message object (finalized rows keep their identity
+  // across deltas) — skip without building signatures.
+  if (prev.message === next.message) return true;
+  return messageSignature(prev.message) === messageSignature(next.message);
+}
+
+export default memo(MessageItem, arePropsEqual);

apps/client/src/features/ai-chat/components/reasoning-block.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { memo, useMemo, useState } from "react";
 import { Box, Collapse, Group, Text, UnstyledButton } from "@mantine/core";
 import { IconChevronDown } from "@tabler/icons-react";
 import { useTranslation } from "react-i18next";
@@ -27,19 +27,23 @@ interface ReasoningBlockProps {
  * Providers that don't stream reasoning TEXT still render this block from the
  * authoritative count alone (header only, empty body) so the cost is visible.
  */
-export default function ReasoningBlock({ text, tokens }: ReasoningBlockProps) {
+function ReasoningBlock({ text, tokens }: ReasoningBlockProps) {
   const { t } = useTranslation();
   const [open, setOpen] = useState(false);
 
   // Authoritative count wins; otherwise estimate live from the streamed text.
   const count = tokens && tokens > 0 ? tokens : estimateTokens(text);
   const trimmed = text.trim();
-  // Collapse the blank-line gaps the model emits between every list item /
-  // paragraph so the reasoning renders compactly (tight lists, joined
-  // paragraphs) — see collapseBlankLines. ONLY here, not in the normal answer.
-  const html = trimmed
-    ? renderChatMarkdown(collapseBlankLines(trimmed), {})
-    : "";
+  // Memoize the markdown render so toggling `open` (or a parent re-render caused
+  // by an unrelated streamed delta) does not re-parse the reasoning text; it
+  // recomputes only when the reasoning text itself changes (while it streams in).
+  // collapseBlankLines collapses the blank-line gaps the model emits between every
+  // list item / paragraph so the reasoning renders compactly (tight lists, joined
+  // paragraphs) — ONLY here, not in the normal answer.
+  const html = useMemo(
+    () => (trimmed ? renderChatMarkdown(collapseBlankLines(trimmed), {}) : ""),
+    [trimmed],
+  );
 
   return (
     <Box className={classes.reasoningBlock} mb={6}>
@@ -87,3 +91,8 @@ export default function ReasoningBlock({ text, tokens }: ReasoningBlockProps) {
     </Box>
   );
 }
+
+// Memoized: re-renders only when `text`/`tokens` change (primitive props, default
+// shallow compare), so a parent re-render during streaming of OTHER content does
+// not re-run the markdown parse for an already-finalized reasoning block.
+export default memo(ReasoningBlock);

apps/client/src/features/ai-chat/hooks/use-chat-session.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { renderHook } from "@testing-library/react";
+import { renderHook, act } from "@testing-library/react";
 import { useChatSession } from "./use-chat-session";
 import type { UseChatSessionOptions } from "./use-chat-session";
 
@@ -227,6 +227,50 @@ describe("useChatSession", () => {
     expect(result.current.threadKey).toBe("C");
   });
 
+  it("#161: New chat during a streaming first turn forces a fresh thread (remount), not just a no-op", () => {
+    // Brand-new chat whose first turn is still streaming: the id is adopted only
+    // at turn end, so activeChatId AND thread.chatId are both null. Pressing "New
+    // chat" must still remount to a clean thread even though the atom is unchanged
+    // — the render-phase reconciler (null === null) would otherwise do nothing,
+    // leaving the old chat/stream/history in place (the bug: only the role badge
+    // dropped).
+    const { result } = setup({ activeChatId: null, chats: { items: [] } });
+    const keyBefore = result.current.threadKey;
+    act(() => result.current.startFreshThread());
+    expect(result.current.threadKey).not.toBe(keyBefore);
+  });
+
+  it("#161: an abandoned thread's late onTurnFinished does NOT adopt its chat (thread-aware guard)", () => {
+    // New chat mid-stream remounts to a fresh thread, but @ai-sdk/react does not
+    // abort the abandoned stream on unmount: its onFinish still fires later with
+    // the real server id, tagged with the OLD (abandoned) mount key. That must not
+    // adopt — it would yank the user back into the chat they just left.
+    const { result, setActiveChatId, onInvalidateChatList } = setup({
+      activeChatId: null,
+      chats: { items: [] },
+    });
+    const abandonedKey = result.current.threadKey;
+    act(() => result.current.startFreshThread());
+    expect(result.current.threadKey).not.toBe(abandonedKey);
+    // The abandoned turn finishes in the background, streaming its real id "A".
+    result.current.onTurnFinished("A", abandonedKey);
+    expect(setActiveChatId).not.toHaveBeenCalledWith("A");
+    // It still refreshes the chat list so the left-behind chat shows in history.
+    expect(onInvalidateChatList).toHaveBeenCalled();
+  });
+
+  it("#161: a turn finishing on the CURRENT thread still adopts (guard is key-scoped, not blanket)", () => {
+    // The happy path must keep working: onTurnFinished tagged with the mounted
+    // thread's own key adopts in place as before.
+    const { result, setActiveChatId } = setup({
+      activeChatId: null,
+      chats: { items: [] },
+    });
+    const currentKey = result.current.threadKey;
+    result.current.onTurnFinished("A", currentKey);
+    expect(setActiveChatId).toHaveBeenCalledWith("A");
+  });
+
   it("waitingForHistory gates the loader only while opening an unloaded existing chat", () => {
     // Open an existing chat whose history is still loading => loader on.
     const { result, rerender } = setup({

apps/client/src/features/ai-chat/hooks/use-chat-session.ts

@@ -31,9 +31,19 @@ export interface UseChatSessionResult {
   threadKey: string;
   /** Show the history loader instead of the live thread. */
   waitingForHistory: boolean;
+  /** Force a brand-new, empty thread (new mount key, no chat id) UNCONDITIONALLY,
+   *  even when `activeChatId` is unchanged. The window calls this from
+   *  startNewChat so "New chat" pressed WHILE a brand-new chat's first turn is
+   *  still streaming (activeChatId still null, nothing to diverge) actually
+   *  resets the chat instead of only dropping the role badge (#161). */
+  startFreshThread: () => void;
   /** Call when a turn finishes; `serverChatId` is the authoritative streamed id
-   *  (undefined on a failed turn). Handles new-chat id adoption + invalidations. */
-  onTurnFinished: (serverChatId?: string) => void;
+   *  (undefined on a failed turn). `finishingThreadKey` is the mount key of the
+   *  thread that produced the turn (omit => "current thread", back-compatible):
+   *  a turn ABANDONED by New chat mid-stream still fires this after its thread
+   *  unmounted, so adoption is gated to the still-mounted thread (#161). Handles
+   *  new-chat id adoption + invalidations. */
+  onTurnFinished: (serverChatId?: string, finishingThreadKey?: string) => void;
   /** Call EARLY (at the stream's `start` chunk) with the authoritative streamed
    *  chat id so a brand-new chat adopts its real id WHILE its first turn is still
    *  streaming — making `activeChatId`-gated affordances (e.g. the Copy/export
@@ -98,6 +108,15 @@ export function useChatSession(
       : switchThread(activeChatId),
   );
 
+  // Live mirror of the mounted thread's mount key, read by onTurnFinished to tell
+  // the CURRENT thread from one ABANDONED by New chat mid-stream. @ai-sdk/react
+  // does not abort a stream on unmount and proxies callbacks through a ref, so an
+  // abandoned turn's onFinish/onError still fires AFTER its ChatThread unmounted;
+  // matching its key against this ref keeps that late finish from adopting the
+  // abandoned chat and yanking the user out of the fresh chat they opened (#161).
+  const threadKeyRef = useRef(thread.key);
+  threadKeyRef.current = thread.key;
+
   // Error-path fallback for new-chat id adoption. When a brand-new chat's first
   // turn errors BEFORE the server's `start` chunk, no authoritative chatId ever
   // reaches the client, so the primary metadata adoption cannot run. We then ARM
@@ -115,7 +134,23 @@ export function useChatSession(
   // yet) we adopt the server's AUTHORITATIVE streamed id (never the newest in the
   // list, which races a second tab — #137; see adopt-chat-id.ts).
   const onTurnFinished = useCallback(
-    (serverChatId?: string) => {
+    (serverChatId?: string, finishingThreadKey?: string) => {
+      // Thread-aware guard (#161). A turn ABANDONED by "New chat" mid-stream still
+      // fires onFinish/onError after its ChatThread unmounted (@ai-sdk/react does
+      // not abort on unmount and proxies callbacks through a ref). If that late
+      // finish ran the adoption path it would set activeChatId to the abandoned
+      // chat's real id and yank the user out of the fresh chat they just opened.
+      // So adopt / arm the fallback ONLY for the still-mounted thread; an
+      // abandoned one merely refreshes the chat list (so the left-behind chat
+      // surfaces in history) and does nothing else. A missing key (undefined)
+      // means "current thread" — keeps old call sites/tests working.
+      if (
+        finishingThreadKey !== undefined &&
+        finishingThreadKey !== threadKeyRef.current
+      ) {
+        onInvalidateChatList();
+        return;
+      }
       // Read the live id from the ref, not the closure: on a failed turn this can
       // run twice in one turn (onFinish + onError) before any re-render, and the
       // primary branch below updates the ref so the second call sees the adopted id.
@@ -258,9 +293,28 @@ export function useChatSession(
     pendingNewChatRef.current = null;
   }, []);
 
+  // Force a fresh, empty thread regardless of `activeChatId` (#161). The render-
+  // phase reconciler only remounts when activeChatId diverges from thread.chatId,
+  // so "New chat" pressed while a brand-new chat's first turn is still streaming
+  // (activeChatId AND thread.chatId both null — the real id is adopted only at the
+  // end of the turn) is a no-op for it and the abandoned thread/stream/history
+  // would persist. Dispatching reconcile with a fresh key and chatId:null here
+  // always produces a new mount key, so React remounts ChatThread (a clean useChat
+  // store) and the post-dispatch state (activeChatId null === thread.chatId null)
+  // keeps the reconciler from interfering. Also disarms any pending fallback.
+  const startFreshThread = useCallback(() => {
+    pendingNewChatRef.current = null;
+    dispatch({
+      type: "reconcile",
+      chatId: null,
+      newKey: `new-${generateId()}`,
+    });
+  }, []);
+
   return {
     threadKey: thread.key,
     waitingForHistory,
+    startFreshThread,
     onTurnFinished,
     onServerChatId,
     cancelPendingAdoption,

apps/client/src/features/ai-chat/types/ai-chat.types.ts

@@ -116,6 +116,9 @@ export interface IAiChatMessageRow {
     // turn. Distinct from `usage` (legacy cumulative totalUsage). Shown in the
     // floating window's header badge.
     contextTokens?: number;
+    // The model's max context window (denominator for the header badge); set
+    // alongside contextTokens on a completed turn; absent on older rows.
+    maxContextTokens?: number;
     // Set on an assistant row whose turn ended in a provider/stream error; the
     // raw provider error text (e.g. "402: ...") for inline display in the thread.
     error?: string;

apps/client/src/features/ai-chat/utils/context-badge.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import type { IAiChatMessageRow } from "@/features/ai-chat/types/ai-chat.types.ts";
+import { selectContextBadge } from "@/features/ai-chat/utils/context-badge.ts";
+
+/**
+ * Pure-helper tests for the header context badge selection. Covers the two
+ * non-obvious rules: numerator and denominator are each taken from the most
+ * recent row carrying THAT value (they may live on different rows), and a fresh
+ * row with a zero/absent value must NOT shadow an older positive one.
+ */
+const row = (metadata: IAiChatMessageRow["metadata"]): IAiChatMessageRow => ({
+  id: Math.random().toString(),
+  role: "assistant",
+  content: null,
+  metadata,
+  createdAt: "2026-01-01T00:00:00.000Z",
+});
+
+describe("selectContextBadge", () => {
+  it("returns zeros for empty / nullish input", () => {
+    expect(selectContextBadge(undefined)).toEqual({
+      contextTokens: 0,
+      maxContextTokens: 0,
+    });
+    expect(selectContextBadge(null)).toEqual({
+      contextTokens: 0,
+      maxContextTokens: 0,
+    });
+    expect(selectContextBadge([])).toEqual({
+      contextTokens: 0,
+      maxContextTokens: 0,
+    });
+  });
+
+  it("reads both figures from the most recent row that carries them", () => {
+    expect(
+      selectContextBadge([
+        row({ contextTokens: 100, maxContextTokens: 200000 }),
+        row({ contextTokens: 1500, maxContextTokens: 200000 }),
+      ]),
+    ).toEqual({ contextTokens: 1500, maxContextTokens: 200000 });
+  });
+
+  it("falls back to legacy usage total for older rows without contextTokens", () => {
+    expect(
+      selectContextBadge([
+        row({ usage: { inputTokens: 30, outputTokens: 70 } }),
+      ]),
+    ).toEqual({ contextTokens: 100, maxContextTokens: 0 });
+
+    expect(
+      selectContextBadge([row({ usage: { totalTokens: 250 } })]),
+    ).toEqual({ contextTokens: 250, maxContextTokens: 0 });
+  });
+
+  it("takes numerator and denominator from different rows", () => {
+    // Freshest row (an error turn) carries contextTokens but no max; the older
+    // completed turn carries the max. Each is picked from its own latest row.
+    expect(
+      selectContextBadge([
+        row({ contextTokens: 800, maxContextTokens: 200000 }),
+        row({ contextTokens: 1200, error: "402: nope" }),
+      ]),
+    ).toEqual({ contextTokens: 1200, maxContextTokens: 200000 });
+  });
+
+  it("does not let a fresh zero/absent max shadow an older positive max", () => {
+    expect(
+      selectContextBadge([
+        row({ contextTokens: 100, maxContextTokens: 200000 }),
+        row({ contextTokens: 1200, maxContextTokens: 0 }),
+      ]),
+    ).toEqual({ contextTokens: 1200, maxContextTokens: 200000 });
+  });
+
+  it("skips rows with null metadata", () => {
+    expect(
+      selectContextBadge([
+        row({ contextTokens: 500, maxContextTokens: 200000 }),
+        row(null),
+      ]),
+    ).toEqual({ contextTokens: 500, maxContextTokens: 200000 });
+  });
+
+  it("reports current > max as-is (no clamp)", () => {
+    expect(
+      selectContextBadge([row({ contextTokens: 250000, maxContextTokens: 200000 })]),
+    ).toEqual({ contextTokens: 250000, maxContextTokens: 200000 });
+  });
+});

apps/client/src/features/ai-chat/utils/context-badge.ts

@@ -0,0 +1,49 @@
+import type { IAiChatMessageRow } from "@/features/ai-chat/types/ai-chat.types.ts";
+
+/**
+ * Derive the header context badge figures from the persisted message rows.
+ *
+ * - `contextTokens` (numerator): how much the conversation now occupies in the
+ *   model's context window. Read from the most recent row carrying a context
+ *   figure — `contextTokens` (final-step input+output) on rows recorded after
+ *   this shipped, else that turn's legacy `usage` total for older rows.
+ * - `maxContextTokens` (denominator): the model's configured max window, stamped
+ *   alongside `contextTokens` on a completed turn.
+ *
+ * Each value is taken from the most recent row carrying THAT value
+ * independently — they may land on different rows (e.g. a fresh error row can
+ * carry `contextTokens` but not `maxContextTokens`), so the scan continues for
+ * whichever is still unset. `0` means "no row has it" (older rows, or no
+ * admin-configured limit); the badge then omits the value.
+ */
+export function selectContextBadge(
+  messageRows: readonly IAiChatMessageRow[] | undefined | null,
+): { contextTokens: number; maxContextTokens: number } {
+  let contextTokens = 0;
+  let maxContextTokens = 0;
+  if (!messageRows) return { contextTokens, maxContextTokens };
+  for (let i = messageRows.length - 1; i >= 0; i--) {
+    const meta = messageRows[i].metadata;
+    if (!meta) continue;
+    if (contextTokens === 0) {
+      if (typeof meta.contextTokens === "number" && meta.contextTokens > 0) {
+        contextTokens = meta.contextTokens;
+      } else if (meta.usage) {
+        const usage = meta.usage;
+        const fallback =
+          usage.totalTokens ??
+          (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);
+        if (fallback > 0) contextTokens = fallback;
+      }
+    }
+    if (
+      maxContextTokens === 0 &&
+      typeof meta.maxContextTokens === "number" &&
+      meta.maxContextTokens > 0
+    ) {
+      maxContextTokens = meta.maxContextTokens;
+    }
+    if (contextTokens !== 0 && maxContextTokens !== 0) break;
+  }
+  return { contextTokens, maxContextTokens };
+}

apps/client/src/features/ai-chat/utils/count-stream-tokens.test.ts

@@ -1,17 +1,5 @@
 import { describe, expect, it } from "vitest";
-import type { UIMessage } from "@ai-sdk/react";
-import {
-  estimateTokens,
-  liveTurnTokens,
-} from "@/features/ai-chat/utils/count-stream-tokens.ts";
-
-const msg = (parts: unknown[], metadata?: unknown): UIMessage =>
-  ({
-    id: Math.random().toString(),
-    role: "assistant",
-    parts,
-    metadata,
-  }) as UIMessage;
+import { estimateTokens } from "@/features/ai-chat/utils/count-stream-tokens.ts";
 
 describe("estimateTokens", () => {
   it("returns 0 for the empty string", () => {
@@ -25,147 +13,3 @@ describe("estimateTokens", () => {
     expect(estimateTokens("12345678")).toBe(2);
   });
 });
-
-describe("liveTurnTokens — estimate path", () => {
-  it("is all zeros for an undefined message", () => {
-    expect(liveTurnTokens(undefined)).toEqual({
-      reasoning: 0,
-      output: 0,
-      authoritative: false,
-    });
-  });
-
-  it("is all zeros for a parts-less message", () => {
-    expect(liveTurnTokens({ id: "x", role: "assistant" } as UIMessage)).toEqual({
-      reasoning: 0,
-      output: 0,
-      authoritative: false,
-    });
-  });
-
-  it("estimates output from text parts", () => {
-    // 8 chars -> 2 tokens.
-    const r = liveTurnTokens(msg([{ type: "text", text: "12345678" }]));
-    expect(r).toEqual({ reasoning: 0, output: 2, authoritative: false });
-  });
-
-  it("estimates reasoning from reasoning parts (kept separate from output)", () => {
-    const r = liveTurnTokens(
-      msg([
-        { type: "reasoning", text: "12345678" },
-        { type: "text", text: "abcd" },
-      ]),
-    );
-    expect(r).toEqual({ reasoning: 2, output: 1, authoritative: false });
-  });
-
-  it("accumulates across multiple text + reasoning parts (multi-step)", () => {
-    const r = liveTurnTokens(
-      msg([
-        { type: "reasoning", text: "abcd" }, // 1
-        { type: "text", text: "abcd" }, // 1
-        { type: "tool-getPage", state: "output-available" }, // ignored
-        { type: "reasoning", text: "abcd" }, // 1
-        { type: "text", text: "abcdefgh" }, // 2
-      ]),
-    );
-    expect(r).toEqual({ reasoning: 2, output: 3, authoritative: false });
-  });
-
-  it("ignores non text/reasoning parts (tools, step-start)", () => {
-    const r = liveTurnTokens(
-      msg([
-        { type: "step-start" },
-        { type: "tool-getPage", state: "input-available" },
-      ]),
-    );
-    expect(r).toEqual({ reasoning: 0, output: 0, authoritative: false });
-  });
-});
-
-describe("liveTurnTokens — authoritative path", () => {
-  it("returns authoritative usage verbatim, splitting reasoning out of output", () => {
-    // outputTokens INCLUDES reasoning in the AI SDK shape -> answer = 100 - 30.
-    const r = liveTurnTokens(
-      msg([{ type: "text", text: "estimate would be tiny" }], {
-        usage: { inputTokens: 500, outputTokens: 100, reasoningTokens: 30 },
-      }),
-    );
-    expect(r).toEqual({ reasoning: 30, output: 70, authoritative: true });
-  });
-
-  it("treats missing reasoningTokens as 0 and keeps full output", () => {
-    const r = liveTurnTokens(
-      msg([{ type: "text", text: "x" }], {
-        usage: { inputTokens: 10, outputTokens: 42 },
-      }),
-    );
-    expect(r).toEqual({ reasoning: 0, output: 42, authoritative: true });
-  });
-
-  it("never returns a negative output when reasoning exceeds reported output", () => {
-    const r = liveTurnTokens(
-      msg([], { usage: { outputTokens: 10, reasoningTokens: 40 } }),
-    );
-    expect(r).toEqual({ reasoning: 40, output: 0, authoritative: true });
-  });
-
-  it("falls back to the estimate when metadata has no usage object", () => {
-    const r = liveTurnTokens(
-      msg([{ type: "text", text: "abcd" }], { chatId: "c1" }),
-    );
-    expect(r).toEqual({ reasoning: 0, output: 1, authoritative: false });
-  });
-});
-
-describe("liveTurnTokens — combined authoritative + estimate (#163)", () => {
-  it("ticks the in-flight step above the completed-steps authoritative base", () => {
-    // The authoritative usage is the sum over COMPLETED steps (step 1). The
-    // CURRENT step is streaming and its text is NOT in `usage` yet, but it IS in
-    // the parts -> the running estimate must push the live figure above the base
-    // so the badge keeps growing between step boundaries.
-    const longText = "x".repeat(800); // 800 chars -> 200 est output tokens
-    const r = liveTurnTokens(
-      msg([{ type: "text", text: longText }], {
-        usage: { inputTokens: 500, outputTokens: 40 }, // step-1 base: 40 output
-      }),
-    );
-    // max(authOutput=40, estOutput=200) = 200 -> the counter ticks, not frozen.
-    expect(r.output).toBe(200);
-    expect(r.authoritative).toBe(true);
-  });
-
-  it("ticks reasoning of the in-flight step above the authoritative reasoning base", () => {
-    const longReasoning = "r".repeat(400); // 400 chars -> 100 est reasoning
-    const r = liveTurnTokens(
-      msg([{ type: "reasoning", text: longReasoning }], {
-        usage: { inputTokens: 100, outputTokens: 20, reasoningTokens: 20 },
-      }),
-    );
-    // reasoning: max(20, 100) = 100 ; output: max(max(0,20-20)=0, 0) = 0.
-    expect(r.reasoning).toBe(100);
-    expect(r.output).toBe(0);
-    expect(r.authoritative).toBe(true);
-  });
-
-  it("snaps to the authoritative figure once it exceeds the rough estimate", () => {
-    // Short on-screen text (estimate tiny) but a large authoritative output:
-    // the exact figure wins at the boundary (the counter never under-reports).
-    const r = liveTurnTokens(
-      msg([{ type: "text", text: "abcd" }], {
-        usage: { inputTokens: 10, outputTokens: 5000 },
-      }),
-    );
-    expect(r.output).toBe(5000);
-  });
-
-  it("is monotonic: max never drops below the authoritative base when the estimate is smaller", () => {
-    // Mirrors the legacy 'verbatim' tests: estimate < authoritative -> unchanged.
-    const r = liveTurnTokens(
-      msg([{ type: "text", text: "tiny" }], {
-        usage: { inputTokens: 500, outputTokens: 100, reasoningTokens: 30 },
-      }),
-    );
-    expect(r).toEqual({ reasoning: 30, output: 70, authoritative: true });
-  });
-});

apps/client/src/features/ai-chat/utils/count-stream-tokens.ts

@@ -1,18 +1,11 @@
-import type { UIMessage } from "@ai-sdk/react";
-
 /**
- * Live token counting for a streaming AI-chat turn — split into REASONING
- * (thinking) and OUTPUT (answer) tokens, mirroring how Claude Code shows
- * `Thinking… · 60 tokens` next to its thinking indicator.
+ * Rough client-side token estimation for AI-chat UI affordances.
  *
- * No provider streams exact per-token usage mid-stream, so the live number is a
- * CLIENT ESTIMATE (chars/≈4 heuristic) that is reconciled to AUTHORITATIVE usage
- * once the server attaches it on a step/turn boundary (see the server's
- * `chatStreamMetadata` + the client's read of `message.metadata.usage`). When
- * authoritative usage is present we return it verbatim (the number "jumps to
- * exact"); otherwise we return the running estimate. Pure + unit-testable: it
- * never runs a real BPE tokenizer (that would be O(n²) on the hot path, bloat the
- * bundle, and be wrong for Gemini/Ollama anyway).
+ * No provider streams exact per-token usage mid-stream, so any in-flight figure
+ * is a CLIENT ESTIMATE (chars/≈4 heuristic). Pure + unit-testable: it never runs
+ * a real BPE tokenizer (that would be O(n²) on the hot path, bloat the bundle,
+ * and be wrong for Gemini/Ollama anyway). Used by the in-body reasoning counter
+ * ("Thinking · N tokens").
  */
 
 /**
@@ -24,90 +17,3 @@ export function estimateTokens(text: string): number {
   if (!text) return 0;
   return Math.ceil(text.length / 4);
 }
-
-/** Authoritative per-step/turn usage the server attaches to message metadata. */
-export interface AuthoritativeUsage {
-  inputTokens?: number;
-  outputTokens?: number;
-  totalTokens?: number;
-  reasoningTokens?: number;
-}
-
-/** Live token split for a turn's tail (streaming) assistant message. */
-export interface LiveTurnTokens {
-  /** Thinking/reasoning tokens (estimate, or authoritative when available). */
-  reasoning: number;
-  /** Answer/output tokens (estimate, or authoritative when available). */
-  output: number;
-  /** True when the numbers come from authoritative server usage, not estimate. */
-  authoritative: boolean;
-}
-
-/** Read the authoritative usage off a UIMessage's metadata, if the server set it. */
-function metadataUsage(message: UIMessage): AuthoritativeUsage | undefined {
-  const meta = message?.metadata as
-    | { usage?: AuthoritativeUsage }
-    | undefined;
-  const usage = meta?.usage;
-  if (!usage || typeof usage !== "object") return undefined;
-  return usage;
-}
-
-/**
- * Token split for the given (streaming) assistant message.
- *
- * COMBINES the authoritative server usage with the running text estimate so the
- * counter ticks in real time AND lands exact. The server only attaches
- * `metadata.usage` at a step/turn boundary (`finish-step`/`finish`) and it is
- * CUMULATIVE over COMPLETED steps — it does NOT yet include the in-flight step.
- * So a multi-step turn that returned the authoritative figure verbatim would
- * FREEZE between boundaries and jump in steps (issue #163).
- *
- * Instead we always compute the running ESTIMATE (chars/≈4 over the message's
- * `reasoning`/`text` parts, which grows on every streamed delta) and take the
- * per-component MAX of the authoritative base and the estimate:
- *   - between boundaries the estimate of the in-flight step ticks the number up;
- *   - at a boundary the authoritative figure snaps it to exact;
- *   - because the server's usage is cumulative and we only ever take the max, the
- *     number is MONOTONIC — it never drops.
- *
- * Providers that don't stream reasoning text still surface a reasoning count once
- * the authoritative usage arrives (`max(reasoningTokens, 0)`); on the pure
- * estimate path (no usage yet) such a turn shows `reasoning: 0` until then.
- */
-export function liveTurnTokens(message: UIMessage | undefined): LiveTurnTokens {
-  if (!message) return { reasoning: 0, output: 0, authoritative: false };
-
-  // Running ESTIMATE over every reasoning/text part — grows on each delta. This
-  // includes the IN-FLIGHT step, which the authoritative usage does not cover yet.
-  let estReasoning = 0;
-  let estOutput = 0;
-  for (const part of message.parts ?? []) {
-    if (part.type === "reasoning") {
-      estReasoning += estimateTokens((part as { text?: string }).text ?? "");
-    } else if (part.type === "text") {
-      estOutput += estimateTokens((part as { text?: string }).text ?? "");
-    }
-  }
-
-  const usage = metadataUsage(message);
-  if (!usage) {
-    // No authoritative usage streamed yet: the estimate IS the live figure.
-    return { reasoning: estReasoning, output: estOutput, authoritative: false };
-  }
-
-  // Authoritative sum over COMPLETED steps. `outputTokens` already INCLUDES
-  // reasoning in the AI SDK usage shape, so subtract it out for the "answer"
-  // figure (never go negative if a provider reports them inconsistently).
-  const authReasoning = usage.reasoningTokens ?? 0;
-  const authOutput = Math.max(0, (usage.outputTokens ?? 0) - authReasoning);
-
-  // Per-component max: the in-flight step's estimate ticks above the completed-
-  // steps base between boundaries, and the authoritative figure wins once it
-  // exceeds the (rough) estimate at the next boundary. Monotonic by construction.
-  return {
-    reasoning: Math.max(authReasoning, estReasoning),
-    output: Math.max(authOutput, estOutput),
-    authoritative: true,
-  };
-}

apps/client/src/features/ai-chat/utils/message-signature.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, it } from "vitest";
+import type { UIMessage } from "@ai-sdk/react";
+import { messageSignature } from "@/features/ai-chat/utils/message-signature.ts";
+
+/**
+ * Pure-helper tests for `messageSignature`, the cheap per-message content
+ * signature that drives MessageItem's memo (a streaming row's signature must
+ * change on every delta so it re-renders, while a finalized row's stays stable
+ * so it is skipped). Each test exercises ONE change signal and asserts it flips
+ * the signature; a content-identical clone must keep an EQUAL signature.
+ *
+ * The signature embeds `message.id` and `message.role`, so the `msg` factory
+ * uses a FIXED id/role here (not `Math.random()`): otherwise two messages with
+ * identical content would get different signatures and the negative case would
+ * be impossible to express.
+ */
+const msg = (
+  parts: UIMessage["parts"],
+  metadata?: unknown,
+): UIMessage =>
+  ({
+    id: "m1",
+    role: "assistant",
+    parts,
+    metadata,
+  }) as UIMessage;
+
+describe("messageSignature", () => {
+  it("changes when a text part grows", () => {
+    const before = msg([{ type: "text", text: "alpha" }]);
+    const after = msg([{ type: "text", text: "alpha beta" }]);
+    expect(messageSignature(before)).not.toBe(messageSignature(after));
+  });
+
+  it("changes when a new part is appended", () => {
+    const before = msg([{ type: "text", text: "alpha" }]);
+    const after = msg([
+      { type: "text", text: "alpha" },
+      { type: "text", text: "beta" },
+    ]);
+    expect(messageSignature(before)).not.toBe(messageSignature(after));
+  });
+
+  it("changes when a part's state flips", () => {
+    const before = msg([
+      { type: "tool-getPage", state: "input-streaming" } as never,
+    ]);
+    const after = msg([
+      { type: "tool-getPage", state: "output-available" } as never,
+    ]);
+    expect(messageSignature(before)).not.toBe(messageSignature(after));
+  });
+
+  it("changes when a tool part gains an output", () => {
+    const before = msg([
+      { type: "tool-getPage", state: "output-available" } as never,
+    ]);
+    const after = msg([
+      {
+        type: "tool-getPage",
+        state: "output-available",
+        output: { ok: true },
+      } as never,
+    ]);
+    expect(messageSignature(before)).not.toBe(messageSignature(after));
+  });
+
+  it("changes when a part gains an errorText", () => {
+    const before = msg([
+      { type: "tool-getPage", state: "output-error" } as never,
+    ]);
+    const after = msg([
+      {
+        type: "tool-getPage",
+        state: "output-error",
+        errorText: "boom",
+      } as never,
+    ]);
+    expect(messageSignature(before)).not.toBe(messageSignature(after));
+  });
+
+  it("changes when usage.reasoningTokens arrives on finish-step (text/state already frozen)", () => {
+    // The specifically-commented edge case: the authoritative turn total lands on
+    // the final finish-step AFTER the reasoning text length and state are frozen.
+    // Only the token count appears between these two snapshots, so the signature
+    // MUST still flip — otherwise the "Thinking · N tokens" header would never
+    // snap from the live estimate to the exact figure.
+    const before = msg([
+      { type: "reasoning", text: "thinking", state: "done" } as never,
+    ]);
+    const after = msg(
+      [{ type: "reasoning", text: "thinking", state: "done" } as never],
+      { usage: { reasoningTokens: 42 } },
+    );
+    expect(messageSignature(before)).not.toBe(messageSignature(after));
+  });
+
+  it("changes when metadata.error appears", () => {
+    const before = msg([{ type: "text", text: "answer" }]);
+    const after = msg([{ type: "text", text: "answer" }], { error: "boom" });
+    expect(messageSignature(before)).not.toBe(messageSignature(after));
+  });
+
+  it("changes when metadata.finishReason changes (e.g. to 'aborted')", () => {
+    const before = msg([{ type: "text", text: "answer" }], {
+      finishReason: "stop",
+    });
+    const after = msg([{ type: "text", text: "answer" }], {
+      finishReason: "aborted",
+    });
+    expect(messageSignature(before)).not.toBe(messageSignature(after));
+  });
+
+  it("is UNCHANGED for a content-identical clone (different object, same values)", () => {
+    // A finalized row that is re-created as a fresh object (different parts array
+    // by reference, same parts by value) must keep an EQUAL signature, so the
+    // memo skips re-rendering it.
+    const a = msg([
+      { type: "text", text: "alpha" },
+      { type: "tool-getPage", state: "output-available", output: { ok: true } } as never,
+    ]);
+    const b = msg([
+      { type: "text", text: "alpha" },
+      { type: "tool-getPage", state: "output-available", output: { ok: true } } as never,
+    ]);
+    expect(a).not.toBe(b);
+    expect(messageSignature(a)).toBe(messageSignature(b));
+  });
+});
+
+/**
+ * Per-part-kind coupling guard for the load-bearing invariant documented at the
+ * top of message-signature.ts: the signature MUST sample every VISIBLE field the
+ * MessageItem render body draws, or the memo freezes a stale row. This is an
+ * executable lock for the part kinds rendered TODAY — read alongside
+ * `MessageItem` (message-item.tsx) and the `assistantMessageHasVisibleContent`
+ * helper (message-content.ts), which "mirrors MessageItem's render decisions
+ * EXACTLY". For each kind, mutating a field the render body DRAWS must flip the
+ * signature. If a new visible field is rendered without being added here AND to
+ * the signature, the corresponding assertion below should fail — that is the
+ * guard. (This intentionally stops short of the render-descriptor refactor:
+ * adding a part kind or a visible field still requires a human to extend both
+ * the signature and this block.)
+ */
+describe("messageSignature ↔ render coupling (per visible part kind)", () => {
+  describe("text part — render draws part.text (MarkdownPart text={part.text})", () => {
+    it("flips when the visible text changes", () => {
+      // Streaming is append-only, so the visible text only grows; the signature
+      // samples its length, so the growth is the change signal.
+      const before = msg([{ type: "text", text: "answer" }]);
+      const after = msg([{ type: "text", text: "answer extended" }]);
+      expect(messageSignature(before)).not.toBe(messageSignature(after));
+    });
+  });
+
+  describe("reasoning part — render draws text + tokens (ReasoningBlock)", () => {
+    it("flips when the visible reasoning text changes", () => {
+      const before = msg([
+        { type: "reasoning", text: "think", state: "streaming" } as never,
+      ]);
+      const after = msg([
+        { type: "reasoning", text: "think harder", state: "streaming" } as never,
+      ]);
+      expect(messageSignature(before)).not.toBe(messageSignature(after));
+    });
+
+    it("flips when the visible token count (metadata.usage.reasoningTokens) lands", () => {
+      // The header's "Thinking · N tokens" reads reasoningTokensForPart, fed by
+      // metadata.usage.reasoningTokens — a VISIBLE field that arrives on the final
+      // finish-step after text length and state are frozen.
+      const before = msg([
+        { type: "reasoning", text: "think", state: "done" } as never,
+      ]);
+      const after = msg(
+        [{ type: "reasoning", text: "think", state: "done" } as never],
+        { usage: { reasoningTokens: 99 } },
+      );
+      expect(messageSignature(before)).not.toBe(messageSignature(after));
+    });
+  });
+
+  describe("tool-* part — render draws state/errorText/citations (ToolCallCard)", () => {
+    it("flips when the run state changes (running ↔ done icon + label)", () => {
+      // toolRunState(part.state) selects the spinner/check/error icon.
+      const before = msg([
+        { type: "tool-getPage", state: "input-available" } as never,
+      ]);
+      const after = msg([
+        { type: "tool-getPage", state: "output-available" } as never,
+      ]);
+      expect(messageSignature(before)).not.toBe(messageSignature(after));
+    });
+
+    it("flips when output arrives (drives the rendered citation links)", () => {
+      // toolCitations reads part.output to render the "/p/{id}" anchors.
+      const before = msg([
+        { type: "tool-getPage", state: "output-available" } as never,
+      ]);
+      const after = msg([
+        {
+          type: "tool-getPage",
+          state: "output-available",
+          output: { id: "page-1", title: "Doc" },
+        } as never,
+      ]);
+      expect(messageSignature(before)).not.toBe(messageSignature(after));
+    });
+
+    it("flips when errorText appears (the visible red error detail line)", () => {
+      const before = msg([
+        { type: "tool-getPage", state: "output-error" } as never,
+      ]);
+      const after = msg([
+        {
+          type: "tool-getPage",
+          state: "output-error",
+          errorText: "permission denied",
+        } as never,
+      ]);
+      expect(messageSignature(before)).not.toBe(messageSignature(after));
+    });
+  });
+
+  describe("metadata banners — render draws error / aborted notices", () => {
+    it("flips when metadata.error appears (ChatErrorAlert banner)", () => {
+      const before = msg([{ type: "text", text: "answer" }]);
+      const after = msg([{ type: "text", text: "answer" }], { error: "boom" });
+      expect(messageSignature(before)).not.toBe(messageSignature(after));
+    });
+
+    it("flips when metadata.finishReason becomes 'aborted' (ChatStoppedNotice)", () => {
+      const before = msg([{ type: "text", text: "answer" }], {
+        finishReason: "stop",
+      });
+      const after = msg([{ type: "text", text: "answer" }], {
+        finishReason: "aborted",
+      });
+      expect(messageSignature(before)).not.toBe(messageSignature(after));
+    });
+  });
+});

apps/client/src/features/ai-chat/utils/message-signature.ts

@@ -0,0 +1,44 @@
+import type { UIMessage } from "@ai-sdk/react";
+
+/** Cheap content signature for one message: changes iff something VISIBLE in the
+ *  row changed. Streaming is APPEND-ONLY (text parts only grow, parts are only
+ *  appended, a tool/text part flips state once), so a per-part [type, text
+ *  length, state, error/output presence] tuple + the persisted metadata
+ *  (error/finishReason) is a sufficient change signal without comparing full
+ *  strings on every delta. WARNING — load-bearing for the MessageItem memo:
+ *  if a future part kind's VISIBLE content can change WITHOUT changing [type,
+ *  text length, state, error/output presence] (e.g. a tool that streams
+ *  `preliminary` output, or a client-side regenerate that edits a finalized
+ *  row in place), extend this signature or the memo will freeze a stale row. */
+export function messageSignature(message: UIMessage): string {
+  const parts = message.parts
+    .map((p) => {
+      const any = p as {
+        type: string;
+        text?: string;
+        state?: string;
+        errorText?: string;
+        output?: unknown;
+      };
+      return [
+        any.type,
+        any.text?.length ?? 0,
+        any.state ?? "",
+        any.errorText ? 1 : 0,
+        any.output !== undefined ? 1 : 0,
+      ].join(":");
+    })
+    .join("|");
+  const meta = message.metadata as
+    | { error?: string; finishReason?: string; usage?: { reasoningTokens?: number } }
+    | undefined;
+  // `usage.reasoningTokens` is neither append-only nor part-bound: the authoritative
+  // turn total arrives on the final `finish-step` AFTER the reasoning text length and
+  // state are already frozen. Without it in the signature the row's signature would be
+  // unchanged at that point and the re-render skipped, so the "Thinking · N tokens"
+  // header (reasoningTokensForPart) would keep the live estimate instead of snapping
+  // to the exact figure.
+  return `${message.id}#${message.role}#${parts}#${meta?.error ?? ""}#${
+    meta?.finishReason ?? ""
+  }#${meta?.usage?.reasoningTokens ?? ""}`;
+}

apps/client/src/features/editor/components/footnote/footnote.module.css

@@ -104,6 +104,19 @@
   min-width: 0;
 }
 
+/* The inner editable paragraph inherits `.ProseMirror p { margin: 0.5em 0 }`,
+   which pushes the first text line ~0.5em below the "N." marker (aligned to
+   flex-start), making the number float above the text. Drop the outer margins
+   so the marker and the first line share the same top edge — same approach
+   used for callouts in core.css. */
+.definitionContent > :first-child {
+  margin-top: 0;
+}
+
+.definitionContent > :last-child {
+  margin-bottom: 0;
+}
+
 .backLink {
   flex: 0 0 auto;
   cursor: pointer;

apps/client/src/features/editor/styles/task-list.css

@@ -10,9 +10,15 @@ ul[data-type="taskList"] {
         display: flex;
 
         > label {
-            padding-top: 0.2rem;
+            /* Box exactly one text-line tall and center the checkbox in it, so the
+               checkbox lines up with the first line of the item's text. This tracks
+               the editor line-height (--mantine-line-height-xl) instead of a magic
+               padding-top that drifts from the real line box. */
             flex: 0 0 auto;
             margin-right: 0.5rem;
+            height: calc(var(--mantine-line-height-xl, 1.65) * 1em);
+            display: inline-flex;
+            align-items: center;
             user-select: none;
         }
 

apps/client/src/features/page/tree/model/tree-model.test.ts

@@ -752,6 +752,27 @@ describe("treeModel.placeByPosition", () => {
     });
     expect(t.map((n) => n.id)).toEqual(["r1", "child", "r2", "rp"]);
   });
+
+  it("returns same reference (no-op) when the destination parent is inside the source's own subtree (#206 ui-state-races-1)", () => {
+    // Moving `a` under its own descendant `b` is a cycle. Without the guard,
+    // remove(a) drops b too and insertByPosition can't re-place a -> the whole
+    // subtree silently vanishes. The guard refuses the move (same reference).
+    const cyclic: P[] = [
+      {
+        id: "a",
+        name: "A",
+        position: "a0",
+        children: [{ id: "b", name: "B", position: "a1" }],
+      },
+    ];
+    const t = treeModel.placeByPosition(cyclic, "a", {
+      parentId: "b",
+      position: "a5",
+    });
+    expect(t).toBe(cyclic);
+    expect(treeModel.find(t, "a")).not.toBeNull();
+    expect(treeModel.find(t, "b")).not.toBeNull();
+  });
 });
 
 describe("treeModel.move", () => {

apps/client/src/features/page/tree/model/tree-model.ts

@@ -294,6 +294,20 @@ export const treeModel = {
     const source = treeModel.find(tree, sourceId);
     if (!source) return tree;
     if (to.parentId !== null && !treeModel.find(tree, to.parentId)) return tree;
+    // Cycle guard, mirroring `move`'s `isDescendant` check (#206 ui-state-races-1).
+    // If the destination parent is INSIDE the moved node's own subtree (reachable
+    // when server-authoritative move events arrive out of order — e.g. X moved
+    // under Y, then Y under X, but on this receiver Y is still inside X), then
+    // `remove(sourceId)` would drop the future parent along with the whole subtree
+    // and `insertByPosition` could not find it again — the node and ALL its
+    // descendants would silently vanish. Refuse the move and return the same
+    // reference so callers can detect the no-op and reconcile (refetch) instead.
+    if (
+      to.parentId !== null &&
+      treeModel.isDescendant(tree, sourceId, to.parentId)
+    ) {
+      return tree;
+    }
     const removed = treeModel.remove(tree, sourceId);
     // Reuse the same position-ordered insertion as `insertByPosition` by
     // stamping the authoritative position onto the moved node first.

apps/client/src/features/share/components/share-alias-section.tsx

@@ -0,0 +1,237 @@
+import {
+  ActionIcon,
+  Button,
+  Group,
+  Modal,
+  Text,
+  TextInput,
+} from "@mantine/core";
+import { IconExternalLink } from "@tabler/icons-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import CopyTextButton from "@/components/common/copy.tsx";
+import { getAppUrl } from "@/lib/config.ts";
+import {
+  useRemoveShareAliasMutation,
+  useSetShareAliasMutation,
+  useShareAliasForPageQuery,
+} from "@/features/share/queries/share-query.ts";
+import { checkShareAliasAvailability } from "@/features/share/services/share-service.ts";
+import {
+  isValidShareAlias,
+  normalizeShareAlias,
+} from "@/features/share/share-alias.util.ts";
+
+interface ShareAliasSectionProps {
+  pageId: string;
+  readOnly: boolean;
+}
+
+// The prefix label shown next to the slug input, e.g. "docs.example.com/l/".
+function aliasPrefixLabel(): string {
+  const url = getAppUrl();
+  const host = url.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+  return `${host}/l/`;
+}
+
+export default function ShareAliasSection({
+  pageId,
+  readOnly,
+}: ShareAliasSectionProps) {
+  const { t } = useTranslation();
+  const { data: currentAlias } = useShareAliasForPageQuery(pageId);
+  const setAliasMutation = useSetShareAliasMutation();
+  const removeAliasMutation = useRemoveShareAliasMutation();
+
+  const [value, setValue] = useState("");
+  const [availability, setAvailability] = useState<{
+    valid: boolean;
+    available: boolean;
+    currentPageId: string | null;
+  } | null>(null);
+  const [reassign, setReassign] = useState<{
+    alias: string;
+    currentPageTitle: string | null;
+  } | null>(null);
+
+  // Seed the input from the page's current alias (if any).
+  useEffect(() => {
+    setValue(currentAlias?.alias ?? "");
+  }, [currentAlias?.alias, pageId]);
+
+  const normalized = useMemo(() => normalizeShareAlias(value), [value]);
+  const isValid = isValidShareAlias(normalized);
+  const unchanged = currentAlias?.alias === normalized;
+
+  // Debounced availability probe (skips when invalid or unchanged).
+  const debounceRef = useRef<ReturnType<typeof setTimeout>>();
+  useEffect(() => {
+    setAvailability(null);
+    if (!isValid || unchanged) return;
+    debounceRef.current && clearTimeout(debounceRef.current);
+    debounceRef.current = setTimeout(async () => {
+      try {
+        const res = await checkShareAliasAvailability(normalized);
+        setAvailability({
+          valid: res.valid,
+          available: res.available,
+          currentPageId: res.currentPageId,
+        });
+      } catch {
+        setAvailability(null);
+      }
+    }, 400);
+    return () => {
+      debounceRef.current && clearTimeout(debounceRef.current);
+    };
+  }, [normalized, isValid, unchanged]);
+
+  const prettyLink = currentAlias?.alias
+    ? `${getAppUrl()}/l/${currentAlias.alias}`
+    : null;
+
+  const handleSave = async (confirmReassign = false) => {
+    try {
+      await setAliasMutation.mutateAsync({
+        pageId,
+        alias: normalized,
+        confirmReassign,
+      });
+      setReassign(null);
+    } catch (error: any) {
+      // The address already points at another page: prompt to move it here.
+      if (error?.status === 409 || error?.response?.status === 409) {
+        const data = error?.response?.data;
+        if (data?.code === "ALIAS_REASSIGN_REQUIRED") {
+          setReassign({
+            alias: normalized,
+            currentPageTitle: data?.currentPageTitle ?? null,
+          });
+        }
+      }
+    }
+  };
+
+  const handleRemove = async () => {
+    if (!currentAlias?.id) return;
+    await removeAliasMutation.mutateAsync(currentAlias.id);
+    setValue("");
+  };
+
+  const showInvalid = normalized.length > 0 && !isValid;
+  const showTaken =
+    isValid && !unchanged && availability && !availability.available;
+
+  return (
+    <>
+      <Text size="sm" fw={500} mt="md">
+        {t("Custom address")}
+      </Text>
+      <Text size="xs" c="dimmed" mb={4}>
+        {t("A short, memorable link you can point at any shared page.")}
+      </Text>
+
+      {prettyLink && (
+        <Group my="xs" gap={4} wrap="nowrap">
+          <TextInput
+            variant="filled"
+            value={prettyLink}
+            readOnly
+            rightSection={<CopyTextButton text={prettyLink} />}
+            style={{ width: "100%" }}
+          />
+          <ActionIcon
+            component="a"
+            variant="default"
+            target="_blank"
+            href={prettyLink}
+            size="sm"
+          >
+            <IconExternalLink size={16} />
+          </ActionIcon>
+        </Group>
+      )}
+
+      <TextInput
+        value={value}
+        onChange={(e) => setValue(e.currentTarget.value)}
+        // Show the canonical form once the user pauses so what they type maps
+        // visibly to what gets stored.
+        onBlur={() => setValue(normalized)}
+        leftSection={
+          <Text size="xs" c="dimmed" pl={4} style={{ whiteSpace: "nowrap" }}>
+            {aliasPrefixLabel()}
+          </Text>
+        }
+        leftSectionWidth={Math.min(aliasPrefixLabel().length * 7 + 12, 180)}
+        placeholder={t("my-page")}
+        disabled={readOnly}
+        error={
+          showInvalid
+            ? t("Use 2-60 lowercase letters, digits and hyphens")
+            : showTaken
+              ? t("This address is already in use")
+              : undefined
+        }
+      />
+
+      <Group mt="xs" gap="xs">
+        <Button
+          size="compact-sm"
+          onClick={() => handleSave(false)}
+          loading={setAliasMutation.isPending}
+          disabled={readOnly || !isValid || unchanged}
+        >
+          {t("Save")}
+        </Button>
+        {currentAlias?.id && (
+          <Button
+            size="compact-sm"
+            variant="default"
+            color="red"
+            onClick={handleRemove}
+            loading={removeAliasMutation.isPending}
+            disabled={readOnly}
+          >
+            {t("Remove")}
+          </Button>
+        )}
+      </Group>
+
+      <Modal
+        opened={!!reassign}
+        onClose={() => setReassign(null)}
+        title={t("Move custom address?")}
+        centered
+        size="sm"
+      >
+        <Text size="sm">
+          {reassign?.currentPageTitle
+            ? t(
+                'The address "{{alias}}" currently points to "{{title}}". Move it to this page?',
+                {
+                  alias: reassign?.alias,
+                  title: reassign?.currentPageTitle,
+                },
+              )
+            : t(
+                'The address "{{alias}}" is already in use. Move it to this page?',
+                { alias: reassign?.alias },
+              )}
+        </Text>
+        <Group justify="flex-end" mt="md">
+          <Button variant="default" onClick={() => setReassign(null)}>
+            {t("Cancel")}
+          </Button>
+          <Button
+            color="red"
+            onClick={() => handleSave(true)}
+            loading={setAliasMutation.isPending}
+          >
+            {t("Move here")}
+          </Button>
+        </Group>
+      </Modal>
+    </>
+  );
+}

apps/client/src/features/share/components/share-modal.tsx

@@ -25,6 +25,7 @@ import CopyTextButton from "@/components/common/copy.tsx";
 import { getAppUrl } from "@/lib/config.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import classes from "@/features/share/components/share.module.css";
+import ShareAliasSection from "@/features/share/components/share-alias-section.tsx";
 import { useAtom } from "jotai";
 import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
 import { useSpaceQuery } from "@/features/space/queries/space-query.ts";
@@ -253,6 +254,9 @@ export default function ShareModal({ readOnly }: ShareModalProps) {
                     disabled={readOnly}
                   />
                 </Group>
+                {pageId && (
+                  <ShareAliasSection pageId={pageId} readOnly={readOnly} />
+                )}
               </>
             )}
           </>

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

@@ -10,6 +10,8 @@ import { useTranslation } from "react-i18next";
 import {
   ICreateShare,
   IShare,
+  IShareAlias,
+  ISetShareAlias,
   ISharedItem,
   ISharedPage,
   ISharedPageTree,
@@ -20,11 +22,14 @@ import {
 import {
   createShare,
   deleteShare,
+  getShareAliasForPage,
   getSharedPageTree,
   getShareForPage,
   getShareInfo,
   getSharePageInfo,
   getShares,
+  removeShareAlias,
+  setShareAlias,
   updateShare,
 } from "@/features/share/services/share-service.ts";
 import { IPagination, QueryParams } from "@/lib/types.ts";
@@ -170,6 +175,72 @@ export function useDeleteShareMutation() {
   });
 }
 
+export function useShareAliasForPageQuery(
+  pageId: string,
+): UseQueryResult<IShareAlias | null, Error> {
+  return useQuery({
+    // The endpoint resolves to null when the page has no alias; normalize the
+    // absence so React Query never sees `undefined`.
+    queryKey: ["share-alias-for-page", pageId],
+    queryFn: async () => (await getShareAliasForPage(pageId)) ?? null,
+    enabled: !!pageId,
+    staleTime: 60 * 1000,
+    retry: false,
+  });
+}
+
+export function useSetShareAliasMutation() {
+  const { t } = useTranslation();
+  const queryClient = useQueryClient();
+
+  return useMutation<IShareAlias, Error, ISetShareAlias>({
+    mutationFn: (data) => setShareAlias(data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        predicate: (item) =>
+          ["share-alias-for-page", "share-list"].includes(
+            item.queryKey[0] as string,
+          ),
+      });
+    },
+    onError: (error) => {
+      // A 409 reassign-required is handled inline by the modal (it shows the
+      // "move address here?" confirmation), so don't surface a generic toast.
+      if (error?.["status"] === 409) return;
+      notifications.show({
+        message:
+          error?.["response"]?.data?.message || t("Failed to set custom address"),
+        color: "red",
+      });
+    },
+  });
+}
+
+export function useRemoveShareAliasMutation() {
+  const { t } = useTranslation();
+  const queryClient = useQueryClient();
+
+  return useMutation<void, Error, string>({
+    mutationFn: (aliasId) => removeShareAlias(aliasId),
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        predicate: (item) =>
+          ["share-alias-for-page", "share-list"].includes(
+            item.queryKey[0] as string,
+          ),
+      });
+    },
+    onError: (error) => {
+      notifications.show({
+        message:
+          error?.["response"]?.data?.message ||
+          t("Failed to remove custom address"),
+        color: "red",
+      });
+    },
+  });
+}
+
 export function useGetSharedPageTreeQuery(
   shareId: string,
 ): UseQueryResult<ISharedPageTree, Error> {

apps/client/src/features/share/services/share-service.ts

@@ -4,6 +4,9 @@ import { IPage } from "@/features/page/types/page.types";
 import {
   ICreateShare,
   IShare,
+  IShareAlias,
+  IShareAliasAvailability,
+  ISetShareAlias,
   ISharedItem,
   ISharedPage,
   ISharedPageTree,
@@ -57,3 +60,33 @@ export async function getSharedPageTree(
   const req = await api.post<ISharedPageTree>("/shares/tree", { shareId });
   return req.data;
 }
+
+export async function getShareAliasForPage(
+  pageId: string,
+): Promise<IShareAlias | null> {
+  const req = await api.post<IShareAlias | null>("/share-aliases/for-page", {
+    pageId,
+  });
+  return req.data;
+}
+
+export async function setShareAlias(
+  data: ISetShareAlias,
+): Promise<IShareAlias> {
+  const req = await api.post<IShareAlias>("/share-aliases/set", data);
+  return req.data;
+}
+
+export async function removeShareAlias(aliasId: string): Promise<void> {
+  await api.post("/share-aliases/remove", { aliasId });
+}
+
+export async function checkShareAliasAvailability(
+  alias: string,
+): Promise<IShareAliasAvailability> {
+  const req = await api.post<IShareAliasAvailability>(
+    "/share-aliases/availability",
+    { alias },
+  );
+  return req.data;
+}

apps/client/src/features/share/share-alias.util.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import {
+  isValidShareAlias,
+  normalizeShareAlias,
+} from "@/features/share/share-alias.util.ts";
+
+// Mirrors the server-side util so the modal's live feedback matches what the
+// server will accept/store.
+describe("normalizeShareAlias", () => {
+  it("lowercases, trims and maps separators to single hyphens", () => {
+    expect(normalizeShareAlias("  My  Cool_Page ")).toBe("my-cool-page");
+  });
+
+  it("collapses repeated hyphens and trims edges", () => {
+    expect(normalizeShareAlias("--a---b--")).toBe("a-b");
+  });
+});
+
+describe("isValidShareAlias", () => {
+  it("accepts ascii hyphen-separated slugs of length 2..60", () => {
+    expect(isValidShareAlias("hello-world")).toBe(true);
+    expect(isValidShareAlias("a".repeat(60))).toBe(true);
+  });
+
+  it("rejects too short, edge/double hyphens, uppercase and non-ascii", () => {
+    expect(isValidShareAlias("a")).toBe(false);
+    expect(isValidShareAlias("-a")).toBe(false);
+    expect(isValidShareAlias("a--b")).toBe(false);
+    expect(isValidShareAlias("Hello")).toBe(false);
+    expect(isValidShareAlias("привет")).toBe(false);
+  });
+});

apps/client/src/features/share/share-alias.util.ts

@@ -0,0 +1,26 @@
+/**
+ * Client copy of the vanity share-alias helpers. Kept in sync with the server
+ * (`apps/server/src/core/share/share-alias.util.ts`) so live input feedback
+ * matches what the server will store/accept. ASCII-only, lowercase, hyphen
+ * separated, length 2..60.
+ */
+
+// Normalize a user-provided vanity alias into canonical ASCII storage form.
+export function normalizeShareAlias(raw: string): string {
+  return (raw ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+const ALIAS_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function isValidShareAlias(alias: string): boolean {
+  return (
+    typeof alias === "string" &&
+    alias.length >= 2 &&
+    alias.length <= 60 &&
+    ALIAS_RE.test(alias)
+  );
+}

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

@@ -75,6 +75,30 @@ export interface IShareInfoInput {
   pageId: string;
 }
 
+// Vanity /l/:alias pointer.
+export interface IShareAlias {
+  id: string;
+  workspaceId: string;
+  alias: string;
+  pageId: string | null;
+  creatorId: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ISetShareAlias {
+  pageId: string;
+  alias: string;
+  confirmReassign?: boolean;
+}
+
+export interface IShareAliasAvailability {
+  alias: string;
+  valid: boolean;
+  available: boolean;
+  currentPageId: string | null;
+}
+
 export interface ISharedPageTree {
   share: IShare;
   pageTree: Partial<IPage[]>;

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

@@ -183,6 +183,34 @@ describe("applyMoveTreeNode", () => {
     expect(moved?.hasChildren).toBe(true);
     expect(moved?.position).toBe("a4");
   });
+
+  it("does NOT drop a subtree on a cyclic/out-of-order move (parent inside source) (#206 ui-state-races-1)", () => {
+    // Locally `b` is still nested inside `a` (an earlier "a under b" echo hasn't
+    // applied yet). An out-of-order "move a under b" event now arrives — b is a
+    // descendant of a, so re-parenting would make placeByPosition remove a (and
+    // its whole subtree, incl. b) and fail to re-insert. Before the fix BOTH a
+    // and b silently vanished; now the reducer leaves the tree untouched.
+    const tree: SpaceTreeNode[] = [
+      node("a", {
+        position: "a0",
+        hasChildren: true,
+        children: [node("b", { position: "a1", parentPageId: "a" })],
+      }),
+    ];
+    const next = applyMoveTreeNode(tree, {
+      id: "a",
+      parentId: "b",
+      oldParentId: null,
+      index: 0,
+      position: "a4",
+      pageData: {},
+    });
+    // No silent data loss: both nodes survive.
+    expect(treeModel.find(next, "a")).not.toBeNull();
+    expect(treeModel.find(next, "b")).not.toBeNull();
+    // The cyclic move is refused as a no-op (same reference) pending reconcile.
+    expect(next).toBe(tree);
+  });
 });
 
 describe("applyDeleteTreeNode", () => {

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

@@ -76,6 +76,19 @@ export function applyMoveTreeNode(
   const oldParentId = (sourceBefore as SpaceTreeNode).parentPageId ?? null;
   const newParentId = payload.parentId as string | null;
 
+  // Cyclic / out-of-order move guard (#206 ui-state-races-1): if the
+  // authoritative new parent is currently INSIDE the moved node's own subtree on
+  // this client (e.g. server moved X under Y then Y under X and the events
+  // arrived such that Y is still nested in X here), re-parenting is impossible to
+  // represent locally. `placeByPosition` returns `prev` for this, but the
+  // `placed === prev` fallback below would then `remove` the source — dropping
+  // the node AND every descendant (incl. the would-be parent) silently. Leave the
+  // tree untouched instead; a later corrective event or a reconnect refetch
+  // reconciles it. Never delete a subtree we cannot safely re-place.
+  if (newParentId && treeModel.isDescendant(prev, payload.id, newParentId)) {
+    return prev;
+  }
+
   // Place the node by its fractional `position` among the new siblings — NOT by
   // the sender's absolute `index` (the sender computed that against its own
   // loaded set, which differs from this receiver's). Using the position keeps

apps/client/src/features/workspace/components/settings/components/ai-mcp-server-test-view.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { mcpTestButtonView } from "./ai-mcp-server-test-view";
+
+/**
+ * Pure-helper tests for the inline "Test" button presentation. Covers the four
+ * states (idle / loading is handled by the component's `isPending`, so here:
+ * idle / ok-with-tools / ok-without-tools / failed) and the tooltip text
+ * branches that are easiest to break silently.
+ */
+// Identity-ish translator that echoes the key and interpolates {{n}} so the
+// label/tooltip branches are observable without the real i18n bundle.
+const t = (key: string, options?: Record<string, unknown>): string =>
+  options && "n" in options
+    ? key.replace("{{n}}", String((options as { n: unknown }).n))
+    : key;
+
+describe("mcpTestButtonView", () => {
+  it("idle when there is no result", () => {
+    expect(mcpTestButtonView(undefined, t)).toEqual({
+      state: "idle",
+      color: undefined,
+      variant: "default",
+      label: "Test",
+      tooltip: "",
+    });
+  });
+
+  it("ok with tools lists them in the tooltip", () => {
+    expect(mcpTestButtonView({ ok: true, tools: ["a", "b"] }, t)).toEqual({
+      state: "ok",
+      color: "green",
+      variant: "light",
+      label: "OK · 2",
+      tooltip: "a, b",
+    });
+  });
+
+  it('ok with zero tools shows "No tools available"', () => {
+    expect(mcpTestButtonView({ ok: true, tools: [] }, t)).toEqual({
+      state: "ok",
+      color: "green",
+      variant: "light",
+      label: "OK · 0",
+      tooltip: "No tools available",
+    });
+  });
+
+  it("failed surfaces the error text in the tooltip", () => {
+    expect(
+      mcpTestButtonView({ ok: false, error: "402: nope" }, t),
+    ).toEqual({
+      state: "failed",
+      color: "red",
+      variant: "light",
+      label: "Failed",
+      tooltip: "402: nope",
+    });
+  });
+
+  it("failed when the request itself rejects (no result payload)", () => {
+    // 401/403/500/network: there is no { ok } body, only a thrown error. The
+    // row must still show a red "Failed" rather than reverting to idle "Test".
+    expect(
+      mcpTestButtonView(undefined, t, {
+        response: { data: { message: "Unauthorized" } },
+      }),
+    ).toEqual({
+      state: "failed",
+      color: "red",
+      variant: "light",
+      label: "Failed",
+      tooltip: "Unauthorized",
+    });
+  });
+
+  it("reject without a server message falls back to the generic label", () => {
+    // A bare network error (no response body) still surfaces as failed, using
+    // the i18n fallback for the tooltip.
+    expect(mcpTestButtonView(undefined, t, new Error("network down"))).toEqual({
+      state: "failed",
+      color: "red",
+      variant: "light",
+      label: "Failed",
+      tooltip: "Failed to update data",
+    });
+  });
+});

apps/client/src/features/workspace/components/settings/components/ai-mcp-server-test-view.ts

@@ -0,0 +1,90 @@
+import type { IAiMcpServerTestResult } from "@/features/workspace/services/ai-mcp-server-service.ts";
+
+/** Minimal translator shape (i18next `t`): key + optional interpolation. */
+type Translate = (key: string, options?: Record<string, unknown>) => string;
+
+/** Subset of an axios-style rejection we read for the reject tooltip. */
+type McpTestRequestError = {
+  response?: { data?: { message?: string } };
+};
+
+/**
+ * Best-effort extraction of a server-sent message from a rejected test request
+ * (axios stores it at `error.response.data.message`). Returns undefined for a
+ * bare/network error so the caller can fall back to a generic label.
+ */
+function readRequestErrorMessage(error: unknown): string | undefined {
+  if (error && typeof error === "object" && "response" in error) {
+    return (error as McpTestRequestError).response?.data?.message;
+  }
+  return undefined;
+}
+
+/**
+ * Presentation for the inline "Test" button, derived from the current test
+ * result tristate (no result yet / ok / failed). Color is never the only signal
+ * — the label and icon change too (a11y / colorblind-friendly). Kept as a single
+ * pure derivation (rather than two parallel if/else chains) so the button and
+ * tooltip can never drift apart, and so the text branches are unit-testable
+ * without rendering the row.
+ */
+export interface McpTestButtonView {
+  /** Tristate; the component maps this to the leftSection icon. */
+  state: "idle" | "ok" | "failed";
+  /** Mantine Button color; undefined = theme default (idle). */
+  color?: string;
+  /** Mantine Button variant. */
+  variant: string;
+  /** Translated button label. */
+  label: string;
+  /** Translated tooltip text; "" while there is no result (tooltip disabled). */
+  tooltip: string;
+}
+
+export function mcpTestButtonView(
+  result: IAiMcpServerTestResult | undefined,
+  t: Translate,
+  error?: unknown,
+): McpTestButtonView {
+  if (result?.ok) {
+    return {
+      state: "ok",
+      color: "green",
+      variant: "light",
+      label: t("OK · {{n}}", { n: result.tools.length }),
+      tooltip:
+        result.tools.length > 0
+          ? result.tools.join(", ")
+          : t("No tools available"),
+    };
+  }
+  if (result && result.ok === false) {
+    return {
+      state: "failed",
+      color: "red",
+      variant: "light",
+      label: t("Failed"),
+      tooltip: result.error,
+    };
+  }
+  if (error) {
+    // The test request itself rejected (401/403/500/network) — there is no
+    // `{ ok }` payload, so without this branch the row would silently revert to
+    // the idle "Test" instead of reporting the failure. Tooltip prefers the
+    // server-sent message, else the generic i18n fallback.
+    return {
+      state: "failed",
+      color: "red",
+      variant: "light",
+      label: t("Failed"),
+      tooltip: readRequestErrorMessage(error) ?? t("Failed to update data"),
+    };
+  }
+  return {
+    state: "idle",
+    color: undefined,
+    variant: "default",
+    label: t("Test"),
+    tooltip: "",
+  };
+}

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

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import {
   ActionIcon,
   Badge,
@@ -10,18 +10,28 @@ import {
   Stack,
   Switch,
   Text,
+  Tooltip,
 } from "@mantine/core";
 import { useDisclosure } from "@mantine/hooks";
 import { modals } from "@mantine/modals";
-import { IconPencil, IconPlus, IconTrash } from "@tabler/icons-react";
+import {
+  IconCheck,
+  IconPencil,
+  IconPlugConnected,
+  IconPlus,
+  IconTrash,
+  IconX,
+} from "@tabler/icons-react";
 import { useTranslation } from "react-i18next";
 import useUserRole from "@/hooks/use-user-role.tsx";
 import {
   useAiMcpServersQuery,
   useDeleteAiMcpServerMutation,
+  useTestAiMcpServerMutation,
   useUpdateAiMcpServerMutation,
 } from "@/features/workspace/queries/ai-mcp-server-query.ts";
 import { IAiMcpServer } from "@/features/workspace/services/ai-mcp-server-service.ts";
+import { mcpTestButtonView } from "@/features/workspace/components/settings/components/ai-mcp-server-test-view.ts";
 import AiMcpServerForm from "./ai-mcp-server-form.tsx";
 
 /**
@@ -112,55 +122,15 @@ export default function AiMcpServers() {
 
       <Stack gap="xs" mt="sm">
         {servers?.map((server) => (
-          <Group key={server.id} justify="space-between" wrap="nowrap">
-            <Stack gap={2} style={{ minWidth: 0 }}>
-              <Group gap="xs">
-                <Text fw={500} truncate>
-                  {server.name}
-                </Text>
-                <Badge size="xs" variant="light">
-                  {server.transport.toUpperCase()}
-                </Badge>
-              </Group>
-              <Text
-                size="xs"
-                c="dimmed"
-                truncate
-                style={{ fontFamily: "ui-monospace, Menlo, monospace" }}
-              >
-                {server.url}
-              </Text>
-            </Stack>
-
-            <Group gap="xs" wrap="nowrap">
-              <Switch
-                size="sm"
-                checked={server.enabled}
-                aria-label={t("Enabled")}
-                onChange={(event) =>
-                  updateMutation.mutate({
-                    id: server.id,
-                    enabled: event.currentTarget.checked,
-                  })
-                }
-              />
-              <ActionIcon
-                variant="subtle"
-                aria-label={t("Edit")}
-                onClick={() => openEdit(server)}
-              >
-                <IconPencil size={16} />
-              </ActionIcon>
-              <ActionIcon
-                variant="subtle"
-                color="red"
-                aria-label={t("Delete")}
-                onClick={() => confirmDelete(server)}
-              >
-                <IconTrash size={16} />
-              </ActionIcon>
-            </Group>
-          </Group>
+          <AiMcpServerRow
+            key={server.id}
+            server={server}
+            onEdit={openEdit}
+            onDelete={confirmDelete}
+            onToggleEnabled={(enabled) =>
+              updateMutation.mutate({ id: server.id, enabled })
+            }
+          />
         ))}
       </Stack>
 
@@ -180,3 +150,127 @@ export default function AiMcpServers() {
     </Paper>
   );
 }
+
+interface AiMcpServerRowProps {
+  server: IAiMcpServer;
+  onEdit: (server: IAiMcpServer) => void;
+  onDelete: (server: IAiMcpServer) => void;
+  onToggleEnabled: (enabled: boolean) => void;
+}
+
+/**
+ * A single external MCP server row: name/badge/url on the left and the
+ * Test / Switch / Edit / Delete controls on the right. Each row owns its own
+ * `useTestAiMcpServerMutation()` so the inline Test result and loading state are
+ * independent per row (a shared mutation would make `isPending` global and make
+ * every row flicker).
+ */
+function AiMcpServerRow({
+  server,
+  onEdit,
+  onDelete,
+  onToggleEnabled,
+}: AiMcpServerRowProps) {
+  const { t } = useTranslation();
+  const testMutation = useTestAiMcpServerMutation();
+  const result = testMutation.data;
+
+  // The row is keyed by `server.id`, so editing the connection-relevant fields
+  // (url/transport/headers) does NOT remount it — an old success/failure result
+  // would otherwise stick. Clear the result when those fields change.
+  useEffect(() => {
+    testMutation.reset();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [server.url, server.transport, server.hasHeaders]);
+
+  // Single derivation of the button/tooltip presentation from the test tristate
+  // (idle / ok / failed), so the two can never drift apart. Tooltip is "" while
+  // there is no result; the icon is mapped from `view.state` below. When the
+  // request itself rejects (401/403/500/network) there is no `data` payload, so
+  // we feed the mutation error in too — otherwise the row would silently revert
+  // to "Test" instead of showing a red "Failed".
+  const view = mcpTestButtonView(
+    result,
+    t,
+    testMutation.isError ? testMutation.error : undefined,
+  );
+  const tooltipLabel = view.tooltip;
+  const buttonColor = view.color;
+  const buttonVariant = view.variant;
+  const buttonLabel = view.label;
+  const buttonIcon =
+    view.state === "ok" ? (
+      <IconCheck size={16} />
+    ) : view.state === "failed" ? (
+      <IconX size={16} />
+    ) : (
+      <IconPlugConnected size={16} />
+    );
+
+  return (
+    <Group justify="space-between" wrap="nowrap">
+      <Stack gap={2} style={{ minWidth: 0 }}>
+        <Group gap="xs">
+          <Text fw={500} truncate>
+            {server.name}
+          </Text>
+          <Badge size="xs" variant="light">
+            {server.transport.toUpperCase()}
+          </Badge>
+        </Group>
+        <Text
+          size="xs"
+          c="dimmed"
+          truncate
+          style={{ fontFamily: "ui-monospace, Menlo, monospace" }}
+        >
+          {server.url}
+        </Text>
+      </Stack>
+
+      <Group gap="xs" wrap="nowrap">
+        {/* Always clickable: testing a disabled server before enabling it is useful. */}
+        <Tooltip
+          label={tooltipLabel}
+          disabled={view.state === "idle"}
+          multiline
+          maw={320}
+          withinPortal
+        >
+          <Button
+            size="xs"
+            miw={88}
+            color={buttonColor}
+            variant={buttonVariant}
+            leftSection={testMutation.isPending ? undefined : buttonIcon}
+            loading={testMutation.isPending}
+            onClick={() => testMutation.mutate(server.id)}
+          >
+            {buttonLabel}
+          </Button>
+        </Tooltip>
+        <Switch
+          size="sm"
+          checked={server.enabled}
+          aria-label={t("Enabled")}
+          onChange={(event) => onToggleEnabled(event.currentTarget.checked)}
+        />
+        <ActionIcon
+          variant="subtle"
+          aria-label={t("Edit")}
+          onClick={() => onEdit(server)}
+        >
+          <IconPencil size={16} />
+        </ActionIcon>
+        <ActionIcon
+          variant="subtle"
+          color="red"
+          aria-label={t("Delete")}
+          onClick={() => onDelete(server)}
+        >
+          <IconTrash size={16} />
+        </ActionIcon>
+      </Group>
+    </Group>
+  );
+}

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

@@ -7,6 +7,7 @@ import {
   Button,
   Group,
   Modal,
+  NumberInput,
   Paper,
   PasswordInput,
   Select,
@@ -83,6 +84,9 @@ const STT_LANGUAGE_OPTIONS: { value: string; label: string }[] = [
 // (empty means "leave unchanged" unless explicitly cleared).
 const formSchema = z.object({
   chatModel: z.string(),
+  // Max context window in tokens shown in the chat header badge. A number, or ""
+  // when the NumberInput is empty (no limit).
+  chatContextWindow: z.union([z.number(), z.literal("")]),
   // Chat provider implementation (reasoning surfacing). Default openai-compatible.
   chatApiStyle: z.enum(["openai-compatible", "openai"]),
   // Cheap model id for the anonymous public-share assistant; empty = use chatModel.
@@ -311,6 +315,7 @@ export default function AiProviderSettings() {
     validate: zod4Resolver(formSchema),
     initialValues: {
       chatModel: "",
+      chatContextWindow: "",
       chatApiStyle: "openai-compatible" as ChatApiStyle,
       publicShareChatModel: "",
       publicShareAssistantRoleId: "",
@@ -334,6 +339,7 @@ export default function AiProviderSettings() {
     if (!settings) return;
     form.setValues({
       chatModel: settings.chatModel ?? "",
+      chatContextWindow: settings.chatContextWindow ?? "",
       chatApiStyle: settings.chatApiStyle ?? "openai-compatible",
       publicShareChatModel: settings.publicShareChatModel ?? "",
       publicShareAssistantRoleId: settings.publicShareAssistantRoleId ?? "",
@@ -364,6 +370,12 @@ export default function AiProviderSettings() {
       // Everything is OpenAI-compatible.
       driver: "openai",
       chatModel: values.chatModel,
+      // Max context window for the chat header badge; empty NumberInput ("") →
+      // 0, which clears the limit server-side (no denominator shown).
+      chatContextWindow:
+        typeof values.chatContextWindow === "number"
+          ? values.chatContextWindow
+          : 0,
       chatApiStyle: values.chatApiStyle,
       // Cheap model id for the anonymous public-share assistant; empty falls
       // back to chatModel server-side.
@@ -767,6 +779,18 @@ export default function AiProviderSettings() {
           {t("Resolves to {{url}}", { url: chatResolved })}
         </Text>
 
+        <NumberInput
+          mt="sm"
+          label={t("Context window (tokens)")}
+          description={t(
+            "Shown as used / total in the chat header. Leave empty to hide the limit.",
+          )}
+          min={0}
+          allowDecimal={false}
+          disabled={isLoading}
+          {...form.getInputProps("chatContextWindow")}
+        />
+
         <Select
           mt="sm"
           label={t("Protocol")}

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

@@ -22,6 +22,8 @@ export type ChatApiStyle = "openai-compatible" | "openai";
 export interface IAiSettings {
   driver?: AiDriver;
   chatModel?: string;
+  // Max context window in tokens shown in the chat header badge; 0/unset = no limit.
+  chatContextWindow?: number;
   chatApiStyle?: ChatApiStyle;
   // Cheap model id for the anonymous public-share assistant; empty = chatModel.
   publicShareChatModel?: string;
@@ -56,6 +58,8 @@ export interface IAiSettings {
 export interface IAiSettingsUpdate {
   driver?: AiDriver;
   chatModel?: string;
+  // Max context window in tokens for the chat header badge; 0 = clear the limit.
+  chatContextWindow?: number;
   chatApiStyle?: ChatApiStyle;
   publicShareChatModel?: string;
   // Agent-role id whose persona the public-share assistant adopts; empty =

apps/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "server",
-  "version": "0.93.0",
+  "version": "0.94.1",
   "description": "",
   "author": "",
   "private": true,

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

@@ -182,4 +182,46 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
     expect(historyQueue.add).not.toHaveBeenCalled();
   });
+
+  // persist-1 — a transient DB failure during store must not silently lose the
+  // edit. hocuspocus unloads (destroys) the in-memory Y.Doc right after this
+  // hook resolves, so the store has to retry while it still holds the only copy.
+  it('retries a transient DB failure and still persists the edit (persist-1)', async () => {
+    const document = ydocFor(doc('NEW HUMAN CONTENT'));
+    pageRepo.findById.mockResolvedValue(persistedHumanPage('NEW HUMAN CONTENT'));
+    let attempts = 0;
+    pageRepo.updatePage.mockImplementation(async () => {
+      attempts += 1;
+      if (attempts === 1) throw new Error('deadlock detected'); // transient
+      callOrder.push('updatePage');
+    });
+
+    await ext.onStoreDocument(buildData(document, 'user') as any);
+
+    // First attempt failed and rolled back; the retry persisted the edit.
+    expect(pageRepo.updatePage).toHaveBeenCalledTimes(2);
+    // The edit WAS saved, so the post-store success path runs as normal.
+    expect((document as any).broadcastStateless).toHaveBeenCalledTimes(1);
+    expect(historyQueue.add).toHaveBeenCalledTimes(1);
+  });
+
+  // persist-1 — when every attempt fails the hook must NOT report a phantom
+  // success: no "page.updated" badge broadcast and no history snapshot for
+  // content that was never written.
+  it('does not run post-store side effects when every store attempt fails (persist-1)', async () => {
+    const document = ydocFor(doc('NEW HUMAN CONTENT'));
+    pageRepo.findById.mockResolvedValue(persistedHumanPage('NEW HUMAN CONTENT'));
+    pageRepo.updatePage.mockRejectedValue(new Error('connection reset'));
+
+    await expect(
+      ext.onStoreDocument(buildData(document, 'user') as any),
+    ).resolves.toBeUndefined();
+
+    // Bounded retry exhausted (MAX_STORE_ATTEMPTS).
+    expect(pageRepo.updatePage).toHaveBeenCalledTimes(3);
+    // No false-success: nothing downstream fires for the unsaved content.
+    expect((document as any).broadcastStateless).not.toHaveBeenCalled();
+    expect(historyQueue.add).not.toHaveBeenCalled();
+    expect(aiQueue.add).not.toHaveBeenCalled();
+  });
 });

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

@@ -196,83 +196,113 @@ export class PersistenceExtension implements Extension {
       context?.actor,
     );
 
-    try {
-      await executeTx(this.db, async (trx) => {
-        page = await this.pageRepo.findById(pageId, {
-          withLock: true,
-          includeContent: true,
-          trx,
-        });
+    // Persist with a small bounded retry. The in-memory Y.Doc is the ONLY copy
+    // of the latest edit until this hook returns: hocuspocus destroys/unloads the
+    // doc right after onStoreDocument resolves (see storeDocumentHooks' finally
+    // -> unloadDocument). If a transient DB error (deadlock, serialization
+    // failure, dropped connection) is merely logged and swallowed, the function
+    // resolves "successfully", the doc is unloaded, and the edit is lost silently
+    // (#206 persist-1). Retrying here re-attempts the write while we still hold
+    // the doc; on total failure we clear `page` so the post-store side effects
+    // (badge broadcast, history snapshot) never report a save that didn't happen.
+    const MAX_STORE_ATTEMPTS = 3;
+    for (let attempt = 1; attempt <= MAX_STORE_ATTEMPTS; attempt++) {
+      try {
+        await executeTx(this.db, async (trx) => {
+          page = await this.pageRepo.findById(pageId, {
+            withLock: true,
+            includeContent: true,
+            trx,
+          });
 
-        if (!page) {
-          this.logger.error(`Page with id ${pageId} not found`);
-          return;
-        }
-
-        if (isDeepStrictEqual(tiptapJson, page.content)) {
-          page = null;
-          return;
-        }
-
-        let contributorIds = undefined;
-        try {
-          const existingContributors = page.contributorIds || [];
-          contributorIds = Array.from(
-            new Set([
-              ...existingContributors,
-              ...editingUserIds,
-              page.creatorId,
-            ]),
-          );
-        } catch (err) {
-          //this.logger.debug('Contributors error:' + err?.['message']);
-        }
-
-        // Approach A — boundary snapshot before the agent's first edit.
-        // When this store is the agent's and the page's currently persisted
-        // state was authored by a human, pin that human state as its own
-        // history version BEFORE the agent overwrites it. `page` still holds the
-        // OLD content/provenance here, so saveHistory(page) captures the
-        // pre-agent state tagged 'user'. The agent's new content is snapshotted
-        // later by the debounced PAGE_HISTORY job ('agent'). Skip if the prior
-        // state is already agent-authored (boundary already pinned on the
-        // user->agent transition), if the page is effectively empty, or if the
-        // latest existing snapshot already equals this human state (avoid
-        // duplicates).
-        if (lastUpdatedSource === 'agent' && page.lastUpdatedSource !== 'agent') {
-          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) {
-            await this.pageHistoryRepo.saveHistory(page, {
-              contributorIds: page.contributorIds ?? undefined,
-              trx,
-            });
+          if (!page) {
+            this.logger.error(`Page with id ${pageId} not found`);
+            return;
           }
-        }
 
-        await this.pageRepo.updatePage(
-          {
-            content: tiptapJson,
-            textContent: textContent,
-            ydoc: ydocState,
-            lastUpdatedById: context.user.id,
-            // Human stays the responsible author; these annotate the source.
-            lastUpdatedSource,
-            lastUpdatedAiChatId: context?.aiChatId ?? null,
-            contributorIds: contributorIds,
-          },
-          pageId,
-          trx,
+          if (isDeepStrictEqual(tiptapJson, page.content)) {
+            page = null;
+            return;
+          }
+
+          let contributorIds = undefined;
+          try {
+            const existingContributors = page.contributorIds || [];
+            contributorIds = Array.from(
+              new Set([
+                ...existingContributors,
+                ...editingUserIds,
+                page.creatorId,
+              ]),
+            );
+          } catch (err) {
+            //this.logger.debug('Contributors error:' + err?.['message']);
+          }
+
+          // Approach A — boundary snapshot before the agent's first edit.
+          // When this store is the agent's and the page's currently persisted
+          // state was authored by a human, pin that human state as its own
+          // history version BEFORE the agent overwrites it. `page` still holds
+          // the OLD content/provenance here, so saveHistory(page) captures the
+          // pre-agent state tagged 'user'. The agent's new content is
+          // snapshotted later by the debounced PAGE_HISTORY job ('agent'). Skip
+          // if the prior state is already agent-authored (boundary already
+          // pinned on the user->agent transition), if the page is effectively
+          // empty, or if the latest existing snapshot already equals this human
+          // state (avoid duplicates).
+          if (
+            lastUpdatedSource === 'agent' &&
+            page.lastUpdatedSource !== 'agent'
+          ) {
+            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
+            ) {
+              await this.pageHistoryRepo.saveHistory(page, {
+                contributorIds: page.contributorIds ?? undefined,
+                trx,
+              });
+            }
+          }
+
+          await this.pageRepo.updatePage(
+            {
+              content: tiptapJson,
+              textContent: textContent,
+              ydoc: ydocState,
+              lastUpdatedById: context.user.id,
+              // Human stays the responsible author; these annotate the source.
+              lastUpdatedSource,
+              lastUpdatedAiChatId: context?.aiChatId ?? null,
+              contributorIds: contributorIds,
+            },
+            pageId,
+            trx,
+          );
+
+          this.logger.debug(`Page updated: ${pageId} - SlugId: ${page.slugId}`);
+        });
+        break;
+      } catch (err) {
+        this.logger.error(
+          `Failed to update page ${pageId} (attempt ${attempt}/${MAX_STORE_ATTEMPTS})`,
+          err,
         );
-
-        this.logger.debug(`Page updated: ${pageId} - SlugId: ${page.slugId}`);
-      });
-    } catch (err) {
-      this.logger.error(`Failed to update page ${pageId}`, err);
+        // The write failed and rolled back; clear the partially-assigned `page`
+        // so the post-store success branch below is skipped (no false "saved"
+        // broadcast / history snapshot for content that was never persisted).
+        page = null;
+        if (attempt < MAX_STORE_ATTEMPTS) {
+          await new Promise((resolve) => setTimeout(resolve, attempt * 50));
+        }
+      }
     }
 
     if (page) {

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

@@ -275,11 +275,12 @@ describe('flushAssistant', () => {
     expect(f.toolCalls).not.toBeNull();
   });
 
-  it('completed: attaches finishReason + normalized usage + contextTokens', () => {
+  it('completed: attaches finishReason + normalized usage + contextTokens + maxContextTokens', () => {
     const f = flushAssistant([toolStep], '', 'completed', {
       finishReason: 'stop',
       usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
       contextTokens: 15,
+      maxContextTokens: 200000,
     });
     expect(f.status).toBe('completed');
     expect(f.metadata.finishReason).toBe('stop');
@@ -290,6 +291,23 @@ describe('flushAssistant', () => {
       reasoningTokens: undefined,
     });
     expect(f.metadata.contextTokens).toBe(15);
+    expect(f.metadata.maxContextTokens).toBe(200000);
+  });
+
+  it('completed: omits maxContextTokens when unset or 0', () => {
+    // No maxContextTokens in the extra (admin set no context window).
+    const f = flushAssistant([toolStep], '', 'completed', {
+      finishReason: 'stop',
+      contextTokens: 15,
+    });
+    expect('maxContextTokens' in f.metadata).toBe(false);
+    // Explicit 0 is treated the same as unset (no limit -> key omitted).
+    const f0 = flushAssistant([toolStep], '', 'completed', {
+      finishReason: 'stop',
+      contextTokens: 15,
+      maxContextTokens: 0,
+    });
+    expect('maxContextTokens' in f0.metadata).toBe(false);
   });
 
   it('error: records the error and a derived finishReason', () => {

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

@@ -616,6 +616,10 @@ export class AiChatService implements OnModuleInit {
               contextTokens:
                 (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0) ||
                 undefined,
+              // Max context window for the chat header badge denominator;
+              // resolved from the admin-configured provider settings (in
+              // closure scope here). Omitted/0 = no limit.
+              maxContextTokens: resolved?.chatContextWindow,
             }),
           );
           // Lifecycle: release the external MCP clients leased for this turn.
@@ -1212,8 +1216,9 @@ export async function applyFinalize(
  * `metadata.parts` is built by assistantParts over the finished steps, then the
  * in-progress text appended as a trailing text part, so rowToUiMessage /
  * findRecent keep replaying the turn unchanged. `metadata.finishReason`,
- * `metadata.error`, `metadata.usage` and `metadata.contextTokens` are attached
- * only when provided/relevant, matching the pre-#183 onFinish/onError records.
+ * `metadata.error`, `metadata.usage`, `metadata.contextTokens` and
+ * `metadata.maxContextTokens` are attached only when provided/relevant, matching
+ * the pre-#183 onFinish/onError records.
  */
 export function flushAssistant(
   capturedSteps: ReadonlyArray<StepLike> | undefined,
@@ -1223,6 +1228,7 @@ export function flushAssistant(
     finishReason?: string;
     usage?: ChatStreamUsage | StreamUsage | undefined;
     contextTokens?: number;
+    maxContextTokens?: number;
     error?: string;
   },
 ): AssistantFlush {
@@ -1253,6 +1259,8 @@ export function flushAssistant(
       normalizeStreamUsage(extra.usage as StreamUsage) ?? extra.usage;
   }
   if (extra?.contextTokens) metadata.contextTokens = extra.contextTokens;
+  if (extra?.maxContextTokens)
+    metadata.maxContextTokens = extra.maxContextTokens;
   if (extra?.error) metadata.error = extra.error;
 
   return {

apps/server/src/core/ai-chat/public-share-chat.controller.spec.ts

@@ -34,6 +34,7 @@ describe('resolveShareAssistantRequest (extracted controller funnel)', () => {
     resolveShareRole?: jest.Mock;
     getShareChatModel?: jest.Mock;
     tryConsumeWorkspaceQuota?: jest.Mock;
+    withinShareTokenBudget?: jest.Mock;
   } = {}) {
     const aiSettings = {
       isPublicShareAssistantEnabled: jest
@@ -65,6 +66,8 @@ describe('resolveShareAssistantRequest (extracted controller funnel)', () => {
         over.getShareChatModel ?? jest.fn().mockResolvedValue('MODEL'),
       tryConsumeWorkspaceQuota:
         over.tryConsumeWorkspaceQuota ?? jest.fn().mockResolvedValue(true),
+      withinShareTokenBudget:
+        over.withinShareTokenBudget ?? jest.fn().mockResolvedValue(true),
     };
     const deps: ShareAssistantDeps = {
       aiSettings: aiSettings as never,
@@ -191,6 +194,39 @@ describe('resolveShareAssistantRequest (extracted controller funnel)', () => {
     expect(publicShareChat.tryConsumeWorkspaceQuota).toHaveBeenCalledWith('ws-1');
   });
 
+  it('withinShareTokenBudget false => 429 thrown BEFORE any stream (cost cap, #159 #5)', async () => {
+    const { deps, publicShareChat } = makeDeps({
+      withinShareTokenBudget: jest.fn().mockResolvedValue(false),
+    });
+    expect(await statusOf(deps, body())).toBe(429);
+    expect(publicShareChat.withinShareTokenBudget).toHaveBeenCalledWith('ws-1');
+    // The token budget is the COST backstop: an over-budget workspace must be
+    // rejected WITHOUT consuming a request slot, so the request cap never runs.
+    expect(publicShareChat.tryConsumeWorkspaceQuota).not.toHaveBeenCalled();
+  });
+
+  it('the token budget is checked BEFORE the request cap (over-budget wins, no slot spent)', async () => {
+    // Over budget AND the request cap would also reject: the read-only budget
+    // gate must win so the (mutating) request-slot consume is never reached.
+    const { deps, publicShareChat } = makeDeps({
+      withinShareTokenBudget: jest.fn().mockResolvedValue(false),
+      tryConsumeWorkspaceQuota: jest.fn().mockResolvedValue(false),
+    });
+    expect(await statusOf(deps, body())).toBe(429);
+    expect(publicShareChat.tryConsumeWorkspaceQuota).not.toHaveBeenCalled();
+  });
+
+  it('the token-budget gate is checked BEFORE the payload caps (429 wins over 413)', async () => {
+    const { deps } = makeDeps({
+      withinShareTokenBudget: jest.fn().mockResolvedValue(false),
+    });
+    const huge = {
+      role: 'user',
+      parts: [{ type: 'text', text: 'x'.repeat(MAX_SHARE_MESSAGE_CHARS + 1) }],
+    };
+    expect(await statusOf(deps, body({ messages: [huge] }))).toBe(429);
+  });
+
   it('messages over MAX_SHARE_MESSAGES => 413', async () => {
     const { deps } = makeDeps();
     const tooMany = Array.from({ length: MAX_SHARE_MESSAGES + 1 }, () => ({

apps/server/src/core/ai-chat/public-share-chat.controller.ts

@@ -151,6 +151,7 @@ export interface ShareAssistantDeps {
     | 'resolveShareRole'
     | 'getShareChatModel'
     | 'tryConsumeWorkspaceQuota'
+    | 'withinShareTokenBudget'
   >;
 }
 
@@ -267,9 +268,21 @@ export async function resolveShareAssistantRequest(
     throw new NotFoundException('Not found');
   }
 
-  // 5. Per-WORKSPACE anti-abuse cap (IP-independent; defense in depth). Checked
-  //    BEFORE res.hijack(), so an over-cap workspace gets a clean 429 and spends
-  //    nothing.
+  // 5a. Per-WORKSPACE rolling-day TOKEN budget (the COST backstop). Read-only and
+  //     checked FIRST so a workspace that has already burned its day's token
+  //     budget gets a clean 429 WITHOUT consuming a request slot, and spends
+  //     nothing. Counting requests alone does not bound the owner's provider
+  //     bill (issue #159, finding #5).
+  if (!(await deps.publicShareChat.withinShareTokenBudget(workspaceId))) {
+    throw new HttpException(
+      'This documentation assistant has reached its usage budget. Please try again later.',
+      HttpStatus.TOO_MANY_REQUESTS,
+    );
+  }
+
+  // 5b. Per-WORKSPACE anti-abuse request cap (IP-independent; defense in depth).
+  //     Checked BEFORE res.hijack(), so an over-cap workspace gets a clean 429
+  //     and spends nothing.
   if (!(await deps.publicShareChat.tryConsumeWorkspaceQuota(workspaceId))) {
     throw new HttpException(
       'This documentation assistant is temporarily busy. Please try again later.',

apps/server/src/core/ai-chat/public-share-chat.service.ts

@@ -17,7 +17,9 @@ import { buildShareSystemPrompt } from './public-share-chat.prompt';
 import { roleModelOverride } from './roles/role-model-config';
 import {
   PublicShareWorkspaceLimiter,
+  PublicShareWorkspaceTokenBudget,
   createPublicShareWorkspaceLimiter,
+  createPublicShareWorkspaceTokenBudget,
 } from './public-share-workspace-limiter';
 import { describeProviderError } from '../../integrations/ai/ai-error.util';
 import {
@@ -125,6 +127,16 @@ export class PublicShareChatService {
    */
   private readonly workspaceLimiter: PublicShareWorkspaceLimiter;
 
+  /**
+   * COST contour two: a per-workspace TOKEN budget over a rolling day. The
+   * request-count limiter above bounds how many anonymous calls run; this bounds
+   * how many provider TOKENS they spend (input re-sent per step + output),
+   * which is what the owner is actually billed for (issue #159, finding #5).
+   * Checked read-only before a turn streams; the real usage is recorded once the
+   * turn finishes (`onFinish`).
+   */
+  private readonly tokenBudget: PublicShareWorkspaceTokenBudget;
+
   constructor(
     private readonly ai: AiService,
     private readonly aiSettings: AiSettingsService,
@@ -133,6 +145,7 @@ export class PublicShareChatService {
     private readonly aiAgentRoleRepo: AiAgentRoleRepo,
   ) {
     this.workspaceLimiter = createPublicShareWorkspaceLimiter(redisService);
+    this.tokenBudget = createPublicShareWorkspaceTokenBudget(redisService);
   }
 
   /**
@@ -144,6 +157,48 @@ export class PublicShareChatService {
     return this.workspaceLimiter.tryConsume(workspaceId);
   }
 
+  /**
+   * Read-only pre-stream COST gate: true while the workspace is under its
+   * rolling-day token budget, false once the trailing-day token spend has
+   * reached it (the controller must then 429 BEFORE starting the stream). This
+   * bounds the owner's actual provider bill, which counting requests alone does
+   * not (issue #159, finding #5).
+   */
+  async withinShareTokenBudget(workspaceId: string): Promise<boolean> {
+    return this.tokenBudget.withinBudget(workspaceId);
+  }
+
+  /**
+   * Record a finished turn's real token spend against the rolling-day budget.
+   * Best-effort (the turn already ran): failures are swallowed by the budget.
+   */
+  async recordShareTokens(workspaceId: string, tokens: number): Promise<void> {
+    return this.tokenBudget.record(workspaceId, tokens);
+  }
+
+  /**
+   * `streamText` onFinish hook body: account a finished turn's REAL token spend
+   * (input re-sent per step + output, summed across all steps) against the
+   * per-workspace rolling-day budget, so a future turn over budget is rejected up
+   * front (issue #159, finding #5). `totalUsage` fields are `number | undefined`;
+   * fall back to the sum of input+output when the provider omits `totalTokens`.
+   * Fire-and-forget: the turn already streamed, so a record failure must not
+   * break it.
+   */
+  recordTurnUsage(
+    workspaceId: string,
+    totalUsage: {
+      totalTokens?: number;
+      inputTokens?: number;
+      outputTokens?: number;
+    },
+  ): void {
+    const tokens =
+      totalUsage.totalTokens ??
+      (totalUsage.inputTokens ?? 0) + (totalUsage.outputTokens ?? 0);
+    void this.recordShareTokens(workspaceId, tokens);
+  }
+
   /**
    * Resolve the admin-selected agent role for the anonymous public-share
    * assistant, scoped to the workspace and soft-delete aware. Returns null when
@@ -231,6 +286,8 @@ export class PublicShareChatService {
         // bill even if the per-IP throttle is evaded; worst case = steps × this.
         maxOutputTokens: resolveShareAiMaxOutputTokens(),
         abortSignal: signal,
+        onFinish: ({ totalUsage }) =>
+          this.recordTurnUsage(workspaceId, totalUsage),
         onError: ({ error }) => {
           // Reuse the shared formatter so provider error formatting stays
           // unified (statusCode + body) with the authenticated path.

apps/server/src/core/ai-chat/public-share-chat.spec.ts

@@ -11,8 +11,11 @@ import {
 import { PublicShareChatToolsService } from './tools/public-share-chat-tools.service';
 import {
   PublicShareWorkspaceLimiter,
+  PublicShareWorkspaceTokenBudget,
   resolveShareAiWorkspaceMax,
+  resolveShareAiWorkspaceTokenBudget,
   SHARE_AI_WORKSPACE_MAX_PER_WINDOW,
+  SHARE_AI_WORKSPACE_TOKEN_BUDGET_DEFAULT,
 } from './public-share-workspace-limiter';
 
 /**
@@ -546,6 +549,228 @@ describe('PublicShareWorkspaceLimiter (cluster-wide sliding-window per-workspace
   });
 });
 
+/**
+ * In-memory fake of the ioredis slice the TOKEN budget uses. Unlike the request
+ * limiter (one Lua), the budget runs TWO scripts over the same sorted set:
+ *  - the read-only CHECK (sums the token counts encoded as each member's leading
+ *    integer, admits while the sum is under budget, never mutates), and
+ *  - the RECORD (ZADDs a finished turn's `<tokens>:<unique>` member).
+ * The fake faithfully reproduces both (branching on the script body) so the spec
+ * exercises the REAL budget math, not a re-implementation.
+ */
+class FakeTokenRedis {
+  private sets = new Map<string, Array<{ score: number; member: string }>>();
+
+  async eval(
+    script: string,
+    _numKeys: number,
+    key: string,
+    nowStr: string,
+    windowMsStr: string,
+    arg3: string,
+  ): Promise<number> {
+    const now = Number(nowStr);
+    const windowMs = Number(windowMsStr);
+    const cutoff = now - windowMs;
+    const arr = (this.sets.get(key) ?? []).filter((e) => e.score > cutoff);
+    if (script.includes('ZADD')) {
+      // RECORD: arg3 is the `<tokens>:<unique>` member; append at score=now.
+      arr.push({ score: now, member: arg3 });
+      this.sets.set(key, arr);
+      return 1;
+    }
+    // CHECK: arg3 is the budget; sum the leading integer of each survivor.
+    const budget = Number(arg3);
+    this.sets.set(key, arr);
+    const total = arr.reduce((sum, e) => {
+      const m = /^(\d+)/.exec(e.member);
+      return sum + (m ? Number(m[1]) : 0);
+    }, 0);
+    return total >= budget ? 0 : 1;
+  }
+}
+
+function makeTokenBudget(budget: number, windowMs: number, clock: () => number) {
+  const redis = new FakeTokenRedis() as unknown as import('ioredis').Redis;
+  return new PublicShareWorkspaceTokenBudget(redis, budget, windowMs, clock);
+}
+
+describe('resolveShareAiWorkspaceTokenBudget (env-overridable per-day token budget)', () => {
+  const KEY = 'SHARE_AI_WORKSPACE_TOKEN_BUDGET_PER_DAY';
+  const saved = process.env[KEY];
+  afterEach(() => {
+    if (saved === undefined) delete process.env[KEY];
+    else process.env[KEY] = saved;
+  });
+
+  it('falls back to the default when unset', () => {
+    delete process.env[KEY];
+    expect(resolveShareAiWorkspaceTokenBudget()).toBe(
+      SHARE_AI_WORKSPACE_TOKEN_BUDGET_DEFAULT,
+    );
+  });
+
+  it('honors a positive override', () => {
+    process.env[KEY] = '250000';
+    expect(resolveShareAiWorkspaceTokenBudget()).toBe(250000);
+  });
+
+  it('ignores a non-positive / unparseable value (uses the default)', () => {
+    for (const bad of ['0', '-5', 'nope', '']) {
+      process.env[KEY] = bad;
+      expect(resolveShareAiWorkspaceTokenBudget()).toBe(
+        SHARE_AI_WORKSPACE_TOKEN_BUDGET_DEFAULT,
+      );
+    }
+  });
+});
+
+describe('PublicShareWorkspaceTokenBudget (cluster-wide rolling-day token cap)', () => {
+  it('admits while under budget and rejects once the recorded spend reaches it', async () => {
+    const budget = makeTokenBudget(1000, 60_000, () => 1_000);
+    expect(await budget.withinBudget('ws-1')).toBe(true); // nothing spent yet
+    await budget.record('ws-1', 600);
+    expect(await budget.withinBudget('ws-1')).toBe(true); // 600 < 1000
+    await budget.record('ws-1', 400);
+    // 1000 >= 1000: the budget is exhausted, so the next turn is rejected up front.
+    expect(await budget.withinBudget('ws-1')).toBe(false);
+  });
+
+  it('counts TOKENS, not requests: one fat turn can exhaust the budget alone', async () => {
+    const budget = makeTokenBudget(1000, 60_000, () => 1_000);
+    // A single accepted turn re-sends the whole transcript across 5 steps; here
+    // it lands as 1200 tokens — already over the day budget on its own.
+    await budget.record('ws-1', 1200);
+    expect(await budget.withinBudget('ws-1')).toBe(false);
+  });
+
+  it('ages out spend older than the window so the budget recovers', async () => {
+    let now = 0;
+    const budget = makeTokenBudget(1000, 60_000, () => now);
+    await budget.record('ws-1', 1000); // at budget
+    now += 59_999; // still inside the day window
+    expect(await budget.withinBudget('ws-1')).toBe(false);
+    now += 2; // the spend is now strictly older than windowMs
+    expect(await budget.withinBudget('ws-1')).toBe(true);
+  });
+
+  it('ignores non-positive / non-finite usage (never records phantom spend)', async () => {
+    const budget = makeTokenBudget(1000, 60_000, () => 1_000);
+    await budget.record('ws-1', 0);
+    await budget.record('ws-1', -50);
+    await budget.record('ws-1', Number.NaN);
+    await budget.record('ws-1', Infinity);
+    expect(await budget.withinBudget('ws-1')).toBe(true); // nothing accumulated
+  });
+
+  it('keeps separate budgets per workspace', async () => {
+    const budget = makeTokenBudget(500, 60_000, () => 1_000);
+    await budget.record('ws-a', 500); // ws-a exhausted
+    expect(await budget.withinBudget('ws-a')).toBe(false);
+    expect(await budget.withinBudget('ws-b')).toBe(true); // ws-b untouched
+  });
+
+  it('FAILS CLOSED on the read-only check when Redis rejects', async () => {
+    const failingRedis = {
+      eval: () => Promise.reject(new Error('redis down')),
+    } as unknown as import('ioredis').Redis;
+    const budget = new PublicShareWorkspaceTokenBudget(
+      failingRedis,
+      1000,
+      60_000,
+      () => 1_000,
+    );
+    const errSpy = jest
+      .spyOn(Logger.prototype, 'error')
+      .mockImplementation(() => undefined);
+    expect(await budget.withinBudget('ws-1')).toBe(false);
+    expect(errSpy).toHaveBeenCalled();
+    errSpy.mockRestore();
+  });
+
+  it('SWALLOWS a record failure (best-effort post-accounting, never throws)', async () => {
+    // The turn already streamed; a record failure must not surface to the caller.
+    const failingRedis = {
+      eval: () => Promise.reject(new Error('redis down')),
+    } as unknown as import('ioredis').Redis;
+    const budget = new PublicShareWorkspaceTokenBudget(
+      failingRedis,
+      1000,
+      60_000,
+      () => 1_000,
+    );
+    const errSpy = jest
+      .spyOn(Logger.prototype, 'error')
+      .mockImplementation(() => undefined);
+    await expect(budget.record('ws-1', 100)).resolves.toBeUndefined();
+    expect(errSpy).toHaveBeenCalled();
+    errSpy.mockRestore();
+  });
+});
+
+describe('PublicShareChatService.withinShareTokenBudget / recordShareTokens', () => {
+  it('delegates the cost gate + accounting to the redis-backed token budget', async () => {
+    const redis = new FakeTokenRedis();
+    const redisService = { getOrThrow: () => redis } as never;
+    const service = new PublicShareChatService(
+      {} as never,
+      {} as never,
+      {} as never,
+      redisService,
+      {} as never,
+    );
+    // Default budget is large, so a fresh workspace is under budget; recording a
+    // modest spend keeps it under budget (asserts the wiring the controller +
+    // onFinish rely on).
+    expect(await service.withinShareTokenBudget('ws-1')).toBe(true);
+    await service.recordShareTokens('ws-1', 1234);
+    expect(await service.withinShareTokenBudget('ws-1')).toBe(true);
+  });
+});
+
+describe('PublicShareChatService.recordTurnUsage (streamText onFinish accounting)', () => {
+  function makeService() {
+    const redisService = { getOrThrow: () => new FakeTokenRedis() } as never;
+    const service = new PublicShareChatService(
+      {} as never,
+      {} as never,
+      {} as never,
+      redisService,
+      {} as never,
+    );
+    const recordSpy = jest
+      .spyOn(service, 'recordShareTokens')
+      .mockResolvedValue(undefined);
+    return { service, recordSpy };
+  }
+
+  it('sums input+output when the provider omits totalTokens', () => {
+    const { service, recordSpy } = makeService();
+    // The onFinish payload shape: a totalUsage with per-component counts but no
+    // authoritative total (provider omitted it).
+    service.recordTurnUsage('ws-1', { inputTokens: 1200, outputTokens: 300 });
+    expect(recordSpy).toHaveBeenCalledWith('ws-1', 1500);
+  });
+
+  it('treats missing input/output components as 0 in the fallback sum', () => {
+    const { service, recordSpy } = makeService();
+    service.recordTurnUsage('ws-1', { outputTokens: 42 });
+    expect(recordSpy).toHaveBeenCalledWith('ws-1', 42);
+  });
+
+  it('prefers the authoritative totalTokens when present (not the sum)', () => {
+    const { service, recordSpy } = makeService();
+    // totalTokens is the provider's authoritative figure and may differ from a
+    // naive input+output sum (e.g. cached/ reasoning tokens); it must win.
+    service.recordTurnUsage('ws-1', {
+      totalTokens: 5000,
+      inputTokens: 1200,
+      outputTokens: 300,
+    });
+    expect(recordSpy).toHaveBeenCalledWith('ws-1', 5000);
+  });
+});
+
 describe('PublicShareChatService.tryConsumeWorkspaceQuota', () => {
   it('delegates to the redis-backed per-workspace limiter', async () => {
     const redis = new FakeRedis();

apps/server/src/core/ai-chat/public-share-workspace-limiter.ts

@@ -136,6 +136,177 @@ export class PublicShareWorkspaceLimiter {
   }
 }
 
+/**
+ * SECOND cost contour: a per-workspace TOKEN budget over a rolling DAY.
+ *
+ * The request-count cap above bounds how MANY anonymous calls a workspace
+ * admits, but NOT how expensive each one is: one accepted call runs the agent
+ * loop up to `stepCountIs(5)`, and every step re-sends the WHOLE client-held
+ * transcript (~hundreds of KB) as input, so the provider input alone can be tens
+ * of thousands of tokens PER step while `maxOutputTokens` only caps the output.
+ * The request cap is also hourly with no daily ceiling, so a steady stream at
+ * the hourly cap sustains ~24x its count per day. Counting requests therefore
+ * does not bound the owner's actual LLM bill (issue #159, finding #5).
+ *
+ * This contour caps the SPEND directly: the actual tokens consumed (input +
+ * output, summed across all steps of every accepted turn) over the trailing
+ * `windowMs` (one rolling day) must stay under `budget`. It is checked BEFORE a
+ * turn streams (read-only) and the turn's real usage is recorded AFTER it
+ * finishes (`streamText` onFinish). Like the request cap it is cluster-wide
+ * (shared Redis) and uses a sliding-window LOG so the day boundary cannot be
+ * gamed for a 2x burst.
+ *
+ * Pre-check is read-only, so a turn already over budget is rejected, but the
+ * tokens of an in-flight turn are not yet known and are accounted only once it
+ * finishes. The worst-case overshoot past the budget is therefore one turn
+ * (bounded by steps x (maxOutputTokens + transcript size)) — acceptable for a
+ * cost backstop on an optional anonymous assistant.
+ */
+
+/** Default per-workspace token budget over the rolling day. */
+export const SHARE_AI_WORKSPACE_TOKEN_BUDGET_DEFAULT = 1_000_000;
+/** Default token-budget window length: one rolling day. */
+export const SHARE_AI_WORKSPACE_TOKEN_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+/** Redis key namespace for the per-workspace token-spend sliding-window log. */
+const TOKEN_KEY_PREFIX = 'share-ai:ws-tokens:';
+
+/**
+ * Read-only sliding-window token-budget check.
+ *
+ * KEYS[1] = the per-workspace token sorted-set key
+ * ARGV[1] = now (epoch ms)
+ * ARGV[2] = windowMs
+ * ARGV[3] = budget (max tokens in the trailing window)
+ *
+ * Drops entries older than the window, then sums the token counts encoded as the
+ * leading integer of each surviving member. Returns 1 if the running total is
+ * still UNDER budget (admit), 0 once it has reached/exceeded the budget. Does NOT
+ * add anything — the turn's real usage is recorded separately once it finishes.
+ */
+const TOKEN_BUDGET_CHECK_LUA = `
+local key = KEYS[1]
+local now = tonumber(ARGV[1])
+local windowMs = tonumber(ARGV[2])
+local budget = tonumber(ARGV[3])
+redis.call('ZREMRANGEBYSCORE', key, 0, now - windowMs)
+local members = redis.call('ZRANGE', key, 0, -1)
+local total = 0
+for i = 1, #members do
+  local t = tonumber(string.match(members[i], '^(%d+)'))
+  if t then total = total + t end
+end
+if total >= budget then
+  return 0
+end
+return 1
+`;
+
+/**
+ * Record one finished turn's token spend in the sliding-window log.
+ *
+ * KEYS[1] = the per-workspace token sorted-set key
+ * ARGV[1] = now (epoch ms) — the entry score
+ * ARGV[2] = windowMs
+ * ARGV[3] = member (`<tokens>:<unique>`; the leading integer is the token count)
+ *
+ * Always ZADDs (the turn already ran and spent the tokens) and refreshes the
+ * key TTL so idle workspaces cost no memory. Trims expired entries first so the
+ * set never grows unbounded for a busy workspace.
+ */
+const TOKEN_RECORD_LUA = `
+local key = KEYS[1]
+local now = tonumber(ARGV[1])
+local windowMs = tonumber(ARGV[2])
+local member = ARGV[3]
+redis.call('ZREMRANGEBYSCORE', key, 0, now - windowMs)
+redis.call('ZADD', key, now, member)
+redis.call('PEXPIRE', key, windowMs)
+return 1
+`;
+
+/**
+ * Cluster-wide, sliding-window per-workspace TOKEN budget backed by Redis.
+ * `withinBudget(key)` is a read-only pre-stream gate; `record(key, tokens)`
+ * accounts a finished turn's real usage. Decoupled from NestJS so it is testable
+ * against a mocked/real ioredis client, mirroring the request-count limiter.
+ */
+export class PublicShareWorkspaceTokenBudget {
+  private readonly logger = new Logger(PublicShareWorkspaceTokenBudget.name);
+  private counter = 0;
+
+  constructor(
+    private readonly redis: Redis,
+    private readonly budget: number = SHARE_AI_WORKSPACE_TOKEN_BUDGET_DEFAULT,
+    private readonly windowMs: number = SHARE_AI_WORKSPACE_TOKEN_WINDOW_MS,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /**
+   * Read-only pre-stream check. Returns true while the workspace is under its
+   * rolling-day token budget, false once the trailing-window spend has reached
+   * it (caller must then 429 BEFORE streaming any tokens).
+   *
+   * FAILS CLOSED (false) on a Redis error: identical reasoning to the request
+   * limiter — when we cannot prove the workspace is under budget we DENY rather
+   * than admit an unmetered billable call. The assistant is optional, so a
+   * transient Redis blip briefly disabling it beats an unbounded provider bill.
+   */
+  async withinBudget(key: string): Promise<boolean> {
+    const t = this.now();
+    try {
+      const admitted = await this.redis.eval(
+        TOKEN_BUDGET_CHECK_LUA,
+        1,
+        TOKEN_KEY_PREFIX + key,
+        String(t),
+        String(this.windowMs),
+        String(this.budget),
+      );
+      return admitted === 1;
+    } catch (err) {
+      this.logger.error(
+        `share-ai token budget Redis failure for key "${key}"; failing closed`,
+        err as Error,
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Record a finished turn's token spend. Best-effort: the turn already ran, so
+   * a Redis failure here is logged but not propagated — it would only cause a
+   * slight under-count of the running budget, never a wrong answer to the
+   * caller. Non-positive / non-finite usage is ignored.
+   */
+  async record(key: string, tokens: number): Promise<void> {
+    if (!Number.isFinite(tokens) || tokens <= 0) return;
+    const spend = Math.floor(tokens);
+    const t = this.now();
+    // Member: `<tokens>:<unique>` — the check Lua sums the leading integer, and
+    // the unique suffix keeps distinct turns in the same ms from colliding on
+    // the sorted-set member (which would drop one entry and under-count).
+    const member = `${spend}:${t}-${this.counter++}-${Math.random()
+      .toString(36)
+      .slice(2)}`;
+    try {
+      await this.redis.eval(
+        TOKEN_RECORD_LUA,
+        1,
+        TOKEN_KEY_PREFIX + key,
+        String(t),
+        String(this.windowMs),
+        member,
+      );
+    } catch (err) {
+      this.logger.error(
+        `share-ai token budget record failure for key "${key}" (${spend} tokens); ignoring`,
+        err as Error,
+      );
+    }
+  }
+}
+
 /**
  * Read the per-workspace cap from the environment (overridable seam), falling
  * back to the sane default. A non-positive / unparseable value uses the default.
@@ -162,3 +333,31 @@ export function createPublicShareWorkspaceLimiter(
     SHARE_AI_WORKSPACE_WINDOW_MS,
   );
 }
+
+/**
+ * Read the per-workspace rolling-day token budget from the environment
+ * (overridable seam), falling back to the sane default. A non-positive /
+ * unparseable value uses the default.
+ */
+export function resolveShareAiWorkspaceTokenBudget(): number {
+  const raw = Number(process.env.SHARE_AI_WORKSPACE_TOKEN_BUDGET_PER_DAY);
+  return Number.isFinite(raw) && raw > 0
+    ? Math.floor(raw)
+    : SHARE_AI_WORKSPACE_TOKEN_BUDGET_DEFAULT;
+}
+
+/**
+ * Build the per-workspace token budget from the injected RedisService (the same
+ * global ioredis client used by the request-count limiter). Tiny factory so the
+ * service constructor stays declarative and the budget stays unit-testable with
+ * a hand-rolled fake redis.
+ */
+export function createPublicShareWorkspaceTokenBudget(
+  redisService: RedisService,
+): PublicShareWorkspaceTokenBudget {
+  return new PublicShareWorkspaceTokenBudget(
+    redisService.getOrThrow(),
+    resolveShareAiWorkspaceTokenBudget(),
+    SHARE_AI_WORKSPACE_TOKEN_WINDOW_MS,
+  );
+}

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

@@ -120,18 +120,25 @@ describe('AiChatToolsService deletePage guardrail (H4)', () => {
     const tools = await buildTools();
     const deletePage = tools.deletePage;
 
-    // The Zod input schema only allows `pageId`; parsing strips/ignores extra
-    // keys, so a permanent/force flag is never part of the validated input.
+    // The wrapped input schema (modelFriendlyInput) only allows `pageId`;
+    // validation strips/ignores extra keys, so a permanent/force flag is never
+    // part of the validated input handed to execute.
     const schema = (deletePage as unknown as { inputSchema: unknown })
       .inputSchema as {
-      parse: (v: unknown) => Record<string, unknown>;
+      validate: (
+        v: unknown,
+      ) =>
+        | { success: boolean; value?: Record<string, unknown> }
+        | Promise<{ success: boolean; value?: Record<string, unknown> }>;
     };
-    const parsed = schema.parse({
+    const result = await schema.validate({
       pageId: 'page-789',
       permanentlyDelete: true,
       forceDelete: true,
     });
 
+    expect(result.success).toBe(true);
+    const parsed = result.value as Record<string, unknown>;
     expect(parsed).toHaveProperty('pageId', 'page-789');
     expect(parsed).not.toHaveProperty('permanentlyDelete');
     expect(parsed).not.toHaveProperty('forceDelete');
@@ -207,19 +214,26 @@ describe('AiChatToolsService expanded toolset guardrails', () => {
     const tools = await buildTools();
     const transformPage = tools.transformPage;
 
-    // The Zod input schema only allows pageId/transformJs/dryRun; parsing
-    // strips unknown keys, so deleteComments can never reach the client.
+    // The wrapped input schema only allows pageId/transformJs/dryRun;
+    // validation strips unknown keys, so deleteComments can never reach the
+    // client.
     const schema = (transformPage as unknown as { inputSchema: unknown })
       .inputSchema as {
-      parse: (v: unknown) => Record<string, unknown>;
+      validate: (
+        v: unknown,
+      ) =>
+        | { success: boolean; value?: Record<string, unknown> }
+        | Promise<{ success: boolean; value?: Record<string, unknown> }>;
     };
-    const parsed = schema.parse({
+    const result = await schema.validate({
       pageId: 'p',
       transformJs: '(d)=>d',
       dryRun: true,
       deleteComments: true,
     });
 
+    expect(result.success).toBe(true);
+    const parsed = result.value as Record<string, unknown>;
     expect(parsed).toHaveProperty('pageId', 'p');
     expect(parsed).not.toHaveProperty('deleteComments');
   });
@@ -395,3 +409,95 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
     expect(updatePageJsonCalls).toHaveLength(0);
   });
 });
+
+/**
+ * Model-friendly tool-call validation (#190): when the model drops a required
+ * `pageId` in a parallel/batch tool call, the built-in input schema must return
+ * a CLEAR, actionable message (naming the parameter, reminding it not to drop
+ * ids in batches) instead of zod's raw "expected string, received undefined" —
+ * while a valid call still validates. This is wired centrally via
+ * modelFriendlyInput, so it applies to every in-app tool; createComment (the
+ * tool from the bug report) and a sharedTool-built tool (getPage's sibling
+ * getOutline) are exercised here end-to-end through forUser().
+ */
+describe('AiChatToolsService model-friendly input validation (#190)', () => {
+  const fakeClient: Partial<DocmostClientLike> = {};
+  const tokenServiceStub = {
+    generateAccessToken: jest.fn().mockResolvedValue('access-token'),
+    generateCollabToken: jest.fn().mockResolvedValue('collab-token'),
+  };
+  let service: AiChatToolsService;
+
+  beforeEach(() => {
+    jest.spyOn(loader, 'loadDocmostMcp').mockResolvedValue(
+      mockLoaded(function () {
+        return fakeClient as DocmostClientLike;
+      } as unknown as loader.DocmostClientCtor),
+    );
+    service = new AiChatToolsService(
+      tokenServiceStub as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+    );
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  function buildTools() {
+    return service.forUser(
+      { id: 'user-1', email: 'u@example.com', workspaceId: 'ws-1' } as never,
+      'session-1',
+      'ws-1',
+      'chat-1',
+    );
+  }
+
+  // The AI SDK Schema produced by modelFriendlyInput exposes `validate`.
+  type ValidatableSchema = {
+    validate: (
+      v: unknown,
+    ) =>
+      | { success: boolean; value?: unknown; error?: Error }
+      | Promise<{ success: boolean; value?: unknown; error?: Error }>;
+  };
+  const inputSchemaOf = (t: unknown) =>
+    (t as { inputSchema: unknown }).inputSchema as ValidatableSchema;
+
+  it('createComment: a dropped pageId yields a clear, model-actionable message', async () => {
+    const tools = await buildTools();
+    // The exact failing shape from the bug report's second parallel batch:
+    // content + selection, but pageId silently dropped.
+    const result = await inputSchemaOf(tools.createComment).validate({
+      content: 'A remark',
+      selection: 'титановый проводник',
+    });
+    expect(result.success).toBe(false);
+    expect(result.error?.message).toContain('parameter "pageId": missing (required)');
+    expect(result.error?.message).toContain('parallel/batch tool calls');
+    // Not the raw zod text the model previously received.
+    expect(result.error?.message).not.toContain('received undefined');
+  });
+
+  it('createComment: a valid call with pageId validates successfully', async () => {
+    const tools = await buildTools();
+    const result = await inputSchemaOf(tools.createComment).validate({
+      pageId: '019efe44-0000-0000-0000-000000000000',
+      content: 'A remark',
+      selection: 'титановый проводник',
+    });
+    expect(result.success).toBe(true);
+    expect(result.value).toMatchObject({
+      pageId: '019efe44-0000-0000-0000-000000000000',
+      content: 'A remark',
+    });
+  });
+
+  it('sharedTool-built tools (getOutline) also get the friendly message on a dropped pageId', async () => {
+    const tools = await buildTools();
+    const result = await inputSchemaOf(tools.getOutline).validate({});
+    expect(result.success).toBe(false);
+    expect(result.error?.message).toContain('parameter "pageId": missing (required)');
+  });
+});

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

@@ -15,6 +15,7 @@ import {
 } from './docmost-client.loader';
 import { resolveCurrentPageResult } from './current-page.util';
 import { parseNodeArg } from './parse-node-arg';
+import { modelFriendlyInput } from './model-friendly-input';
 
 /**
  * Per-user, per-request adapter that exposes Docmost READ operations to the
@@ -102,9 +103,13 @@ export class AiChatToolsService {
     ): Tool =>
       tool({
         description: spec.description,
-        inputSchema: spec.buildShape
-          ? z.object(spec.buildShape(z) as z.ZodRawShape)
-          : z.object({}),
+        // Wrap via modelFriendlyInput so a dropped/invalid parameter (e.g. a
+        // pageId omitted in a parallel batch, #190) yields a clear, actionable
+        // tool error instead of zod's raw text. No-arg specs still get an empty
+        // object schema.
+        inputSchema: modelFriendlyInput(
+          spec.buildShape ? (spec.buildShape(z) as z.ZodRawShape) : {},
+        ),
         execute,
       });
 
@@ -118,7 +123,7 @@ export class AiChatToolsService {
           'and entities), not a full sentence. If the first results look weak ' +
           'or incomplete, search again with different wording or synonyms ' +
           'before answering.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           query: z.string().describe('The search query.'),
           limit: z
             .number()
@@ -227,7 +232,7 @@ export class AiChatToolsService {
           '"the current page", or "here" refers to. Returns the page id and title, ' +
           'or null if the user is not currently on a page. Call this first whenever ' +
           'the user refers to the current page without giving an explicit id.',
-        inputSchema: z.object({}),
+        inputSchema: modelFriendlyInput({}),
         execute: async () => resolveCurrentPageResult(openedPage),
       }),
 
@@ -235,7 +240,7 @@ export class AiChatToolsService {
         description:
           'Fetch a single page as Markdown by its page id. Returns the page ' +
           'title and its Markdown content.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id (or slugId) of the page.'),
         }),
         execute: async ({ pageId }) => {
@@ -259,7 +264,7 @@ export class AiChatToolsService {
           'Create a new page with a Markdown body in a space, optionally under ' +
           'a parent page. Returns the new page id and title. Reversible: a page ' +
           'can be moved to trash later.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           title: z.string().describe('The title of the new page.'),
           content: z
             .string()
@@ -294,7 +299,7 @@ export class AiChatToolsService {
         description:
           "Replace a page's body with new Markdown content (and optionally its " +
           'title). Reversible: the previous version is kept in page history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page to update.'),
           content: z.string().describe('The new page body as Markdown.'),
           title: z
@@ -316,7 +321,7 @@ export class AiChatToolsService {
         description:
           "Rename a page (change its title only; the body is untouched). " +
           'Reversible: rename back at any time.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page to rename.'),
           title: z.string().describe('The new title.'),
         }),
@@ -331,7 +336,7 @@ export class AiChatToolsService {
         description:
           'Move a page under a new parent page, or to the space root when no ' +
           'parent is given. Reversible: move it back at any time.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page to move.'),
           parentPageId: z
             .string()
@@ -353,7 +358,7 @@ export class AiChatToolsService {
         description:
           'Move a page to the trash (SOFT delete only — fully reversible; the ' +
           'page can be restored from trash). This NEVER permanently deletes.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page to move to trash.'),
         }),
         // GUARDRAIL (§14 H4): the only field ever passed to the client is
@@ -379,7 +384,7 @@ export class AiChatToolsService {
           '"selection not found" error, retry with a corrected EXACT selection ' +
           'copied verbatim from a single paragraph/block. Reversible via the ' +
           'comment UI.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page to comment on.'),
           content: z.string().describe('The comment body as Markdown.'),
           selection: z
@@ -428,7 +433,7 @@ export class AiChatToolsService {
         description:
           'Resolve or reopen a top-level comment thread (reversible — toggle ' +
           'the resolved flag). Only top-level comments can be resolved.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           commentId: z
             .string()
             .describe('The id of the top-level comment to resolve/reopen.'),
@@ -460,7 +465,7 @@ export class AiChatToolsService {
           'List the most recent pages, optionally scoped to a single space. ' +
           'Returns a bounded list (default 50, max 100). Pass tree:true (with ' +
           "spaceId) to instead get the space's full page hierarchy as a nested tree.",
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           spaceId: z
             .string()
             .optional()
@@ -488,7 +493,7 @@ export class AiChatToolsService {
           'List sidebar pages for a space. With no pageId, returns the ' +
           "space's ROOT pages; with a pageId, returns that page's direct " +
           'CHILDREN.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           spaceId: z.string().describe('The id of the space.'),
           pageId: z
             .string()
@@ -520,7 +525,7 @@ export class AiChatToolsService {
         description:
           'Read a table as a matrix of cell texts (plus a parallel cellIds ' +
           'matrix so cells can be addressed for rich edits).',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page.'),
           tableRef: z
             .string()
@@ -536,7 +541,7 @@ export class AiChatToolsService {
       listComments: tool({
         description:
           'List all comments on a page (content as Markdown).',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page.'),
         }),
         execute: async ({ pageId }) => await client.listComments(pageId),
@@ -544,7 +549,7 @@ export class AiChatToolsService {
 
       getComment: tool({
         description: 'Fetch a single comment by id (content as Markdown).',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           commentId: z.string().describe('The id of the comment.'),
         }),
         execute: async ({ commentId }) => await client.getComment(commentId),
@@ -554,7 +559,7 @@ export class AiChatToolsService {
         description:
           'Find new comments across a space (optionally scoped to a subtree) ' +
           'created after a given timestamp.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           spaceId: z.string().describe('The id of the space to scan.'),
           since: z
             .string()
@@ -586,7 +591,7 @@ export class AiChatToolsService {
         description:
           'Fetch a single page-history version including its lossless ' +
           'ProseMirror content.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           historyId: z.string().describe('The id of the history version.'),
         }),
         execute: async ({ historyId }) =>
@@ -604,7 +609,7 @@ export class AiChatToolsService {
           'Export a page to a single self-contained Docmost-flavoured ' +
           'Markdown file (meta + body + comment threads). Lossless round-trip ' +
           'with importPageMarkdown.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page to export.'),
         }),
         execute: async ({ pageId }) => {
@@ -630,7 +635,7 @@ export class AiChatToolsService {
           '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
           'may be a JSON object or a JSON string (both accepted). Reversible: ' +
           'the previous version is kept in page history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page.'),
           nodeId: z
             .string()
@@ -663,7 +668,7 @@ export class AiChatToolsService {
           '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
           'may be a JSON object or a JSON string (both accepted). Reversible ' +
           'via page history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page.'),
           node: z
             .any()
@@ -722,7 +727,7 @@ export class AiChatToolsService {
           'object or a JSON string (both accepted). Omit content for a ' +
           'title-only update. Reversible: the previous version is kept in page ' +
           'history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page to update.'),
           content: z
             .any()
@@ -753,7 +758,7 @@ export class AiChatToolsService {
         description:
           'Insert a row of plain-text cells into a table. Reversible via ' +
           'page history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page.'),
           tableRef: z
             .string()
@@ -772,7 +777,7 @@ export class AiChatToolsService {
       tableDeleteRow: tool({
         description:
           'Delete a table row at a 0-based index. Reversible via page history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page.'),
           tableRef: z
             .string()
@@ -787,7 +792,7 @@ export class AiChatToolsService {
         description:
           'Set the plain-text content of a table cell at [row, col] (0-based). ' +
           'Reversible via page history.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page.'),
           tableRef: z
             .string()
@@ -817,7 +822,7 @@ export class AiChatToolsService {
           'Make a page PUBLICLY accessible and return its public URL. ' +
           'Reversible via unsharePage. Only share when the user explicitly ' +
           'asked, since this exposes the page to anyone with the link.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page to share.'),
           searchIndexing: z
             .boolean()
@@ -844,7 +849,7 @@ export class AiChatToolsService {
           "page's ProseMirror document for complex/scripted rewrites. dryRun " +
           '(default true) previews a diff WITHOUT writing; set dryRun:false to ' +
           'apply. Reversible: applying creates a new page-history snapshot.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page to transform.'),
           transformJs: z
             .string()

apps/server/src/core/ai-chat/tools/model-friendly-input.spec.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import {
+  modelFriendlyInput,
+  buildModelFriendlyMessage,
+} from './model-friendly-input';
+
+/**
+ * Unit tests for the centralized in-app tool input wrapper (#190). A dropped or
+ * invalid parameter must surface a clear, model-actionable message (naming the
+ * parameter and reminding the model not to drop ids in parallel batches), while
+ * a valid call validates cleanly and strips unknown keys — and the advertised
+ * JSON Schema keeps the unchanged required/description contract.
+ */
+describe('modelFriendlyInput', () => {
+  // Mirrors createComment's shape: pageId is the required id the model drops in
+  // parallel batches; selection is optional with a min length.
+  const shape = {
+    pageId: z.string().describe('The id of the page to comment on.'),
+    content: z.string().describe('The comment body as Markdown.'),
+    selection: z.string().min(1).max(250).optional(),
+  };
+
+  // Loose return type: the AI SDK ValidationResult is a discriminated union, but
+  // these tests assert on both branches, so a flat optional shape is simpler.
+  async function validate(
+    value: unknown,
+  ): Promise<{ success: boolean; value?: unknown; error?: Error }> {
+    const schema = modelFriendlyInput(shape);
+    return await schema.validate!(value);
+  }
+
+  it('rejects a dropped required pageId with a clear, actionable message', async () => {
+    const result = await validate({
+      content: 'Looks off here',
+      selection: 'титановый проводник',
+    });
+    expect(result.success).toBe(false);
+    const msg = result.error?.message ?? '';
+    // Names the dropped parameter...
+    expect(msg).toContain('parameter "pageId": missing (required)');
+    // ...and gives an explicit, non-raw instruction (not zod's raw text).
+    expect(msg).toContain('parallel/batch tool calls');
+    expect(msg).not.toContain('expected string, received undefined');
+  });
+
+  it('distinguishes a present-but-invalid parameter from a missing one', async () => {
+    // selection is present but too short (invalid), pageId is missing.
+    const result = await validate({ content: 'x', selection: '' });
+    expect(result.success).toBe(false);
+    const msg = result.error?.message ?? '';
+    expect(msg).toContain('parameter "pageId": missing (required)');
+    expect(msg).toContain('parameter "selection": invalid');
+  });
+
+  it('accepts a valid call and strips unknown keys from the validated value', async () => {
+    const result = await validate({
+      pageId: 'page-1',
+      content: 'A comment',
+      selection: 'anchor text',
+      bogus: true,
+    });
+    expect(result.success).toBe(true);
+    if (!result.success) throw new Error('expected success');
+    expect(result.value).toEqual({
+      pageId: 'page-1',
+      content: 'A comment',
+      selection: 'anchor text',
+    });
+    expect(result.value).not.toHaveProperty('bogus');
+  });
+
+  it('preserves the required/description contract in the advertised JSON Schema', async () => {
+    const schema = modelFriendlyInput(shape);
+    const json = (await schema.jsonSchema) as {
+      required?: string[];
+      properties?: Record<string, { description?: string }>;
+    };
+    // pageId + content stay required; selection stays optional.
+    expect(json.required).toEqual(expect.arrayContaining(['pageId', 'content']));
+    expect(json.required).not.toContain('selection');
+    expect(json.properties?.pageId.description).toBe(
+      'The id of the page to comment on.',
+    );
+  });
+
+  it('handles a no-arg tool (empty shape) without error', async () => {
+    const schema = modelFriendlyInput({});
+    const result = await schema.validate!({});
+    expect(result.success).toBe(true);
+  });
+});
+
+describe('buildModelFriendlyMessage', () => {
+  it('falls back to a generic message when issues carry an empty path', () => {
+    // safeParse on a non-object yields a root-level issue (empty path).
+    const error = z.object({ a: z.string() }).safeParse('not-an-object');
+    if (error.success) throw new Error('expected failure');
+    const msg = buildModelFriendlyMessage(error.error, 'not-an-object');
+    expect(msg).toContain('parameter "input"');
+  });
+});

apps/server/src/core/ai-chat/tools/model-friendly-input.ts

@@ -0,0 +1,93 @@
+import { jsonSchema, type Schema } from 'ai';
+import type { JSONSchema7 } from '@ai-sdk/provider';
+import { z } from 'zod';
+
+/**
+ * Centralized input-schema wrapper for every in-app AI-chat tool.
+ *
+ * THE PROBLEM (#190): when the model issues PARALLEL / batch tool calls it
+ * sometimes drops an "obvious" repeated required argument (typically `pageId`)
+ * from some of the calls. zod v4 correctly rejects the missing value, but the
+ * AI SDK forwards zod's RAW message ("Invalid input: expected string, received
+ * undefined") straight back to the model, which is not actionable — the model
+ * cannot tell WHICH parameter it dropped or that it must re-send it.
+ *
+ * THE FIX: keep the exact same validation, but replace the raw zod text with a
+ * model-friendly message that names every problematic parameter and tells the
+ * model to re-issue the call with all required parameters present. We do NOT
+ * guess/backfill the value (a silently-assumed "current page" could comment on
+ * the wrong page — cf. #159); the model is simply told to retry correctly.
+ *
+ * HOW IT WORKS: we build the tool's JSON Schema from the zod shape via
+ * `z.toJSONSchema(..., { target: 'draft-7' })` (so the advertised contract —
+ * `required` / `description` / field constraints — is unchanged) and hand the
+ * AI SDK a custom `validate` that runs `z.object(shape).safeParse(value)`. On
+ * failure the AI SDK wraps our returned `Error` in `InvalidToolInputError`, so
+ * our clear text is what reaches the model as the tool error.
+ */
+export function modelFriendlyInput<T extends z.ZodRawShape>(
+  shape: T,
+): Schema<z.output<z.ZodObject<T>>> {
+  const objectSchema = z.object(shape);
+  // draft-07 keeps required/description/constraints intact, matching what the
+  // model already saw — the tool contract does not change.
+  const json = z.toJSONSchema(objectSchema, {
+    target: 'draft-7',
+  }) as JSONSchema7;
+
+  return jsonSchema<z.output<z.ZodObject<T>>>(json, {
+    validate: (value) => {
+      const result = objectSchema.safeParse(value);
+      if (result.success) {
+        return { success: true, value: result.data };
+      }
+      return {
+        success: false,
+        error: new Error(buildModelFriendlyMessage(result.error, value)),
+      };
+    },
+  });
+}
+
+/**
+ * Turn a zod validation failure into a clear, model-actionable message naming
+ * each problematic parameter (and whether it is missing vs. invalid), plus an
+ * explicit reminder not to drop required ids in parallel/batch tool calls.
+ */
+export function buildModelFriendlyMessage(
+  error: z.ZodError,
+  value: unknown,
+): string {
+  const seen = new Set<string>();
+  const parts: string[] = [];
+  for (const issue of error.issues) {
+    const name = issue.path.length ? issue.path.map(String).join('.') : 'input';
+    // A parameter the model omitted entirely reads as `undefined` at its path;
+    // anything else is present-but-invalid (wrong type, too short, etc.).
+    const missing = valueAtPath(value, issue.path) === undefined;
+    const part = `parameter "${name}": ${missing ? 'missing (required)' : 'invalid'}`;
+    if (seen.has(part)) continue;
+    seen.add(part);
+    parts.push(part);
+  }
+  if (parts.length === 0) {
+    // Defensive: a ZodError always has issues, but never emit an empty list.
+    parts.push('input: invalid');
+  }
+  return (
+    `Invalid input for this tool — ${parts.join('; ')}. ` +
+    'Re-issue the call with EVERY required parameter present and valid. ' +
+    "Do not drop ids like pageId, even when making parallel/batch tool calls — " +
+    'each tool call must carry its own pageId.'
+  );
+}
+
+/** Read the value at a zod issue path; returns undefined if any hop is absent. */
+function valueAtPath(value: unknown, path: ReadonlyArray<PropertyKey>): unknown {
+  let current: unknown = value;
+  for (const key of path) {
+    if (current === null || typeof current !== 'object') return undefined;
+    current = (current as Record<PropertyKey, unknown>)[key];
+  }
+  return current;
+}

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

@@ -5,6 +5,7 @@ import { ShareService } from '../../share/share.service';
 import { SearchService } from '../../search/search.service';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { jsonToMarkdown } from '../../../collaboration/collaboration.util';
+import { modelFriendlyInput } from './model-friendly-input';
 
 /**
  * Isolated, READ-ONLY toolset for the ANONYMOUS public-share assistant.
@@ -52,7 +53,7 @@ export class PublicShareChatToolsService {
           '(key terms and entities), not a full sentence. If the first ' +
           'results look weak, search again with different wording before ' +
           'answering. Only pages inside this share are ever returned.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           query: z.string().describe('The search query.'),
           limit: z
             .number()
@@ -87,7 +88,7 @@ export class PublicShareChatToolsService {
           'Markdown, by its page id. Returns the page title and its Markdown ' +
           'content. Only pages inside this share can be read; reading any ' +
           'other page fails.',
-        inputSchema: z.object({
+        inputSchema: modelFriendlyInput({
           pageId: z
             .string()
             .describe('The id (or slugId) of a page within this share.'),
@@ -142,7 +143,7 @@ export class PublicShareChatToolsService {
           'List the pages (titles + ids) that make up THIS published ' +
           'documentation share, so you can orient yourself before reading or ' +
           'searching. Only pages inside this share are listed.',
-        inputSchema: z.object({}),
+        inputSchema: modelFriendlyInput({}),
         execute: async () => {
           // Reuse the same share-tree logic the public /shares/tree route uses:
           // it validates the share + workspace, excludes restricted subtrees,

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

@@ -60,11 +60,28 @@ describe('PageService', () => {
 
       const eventEmitter = { emit: jest.fn() };
 
+      // movePage now runs the cycle-check + UPDATE inside executeTx(this.db),
+      // i.e. this.db.transaction().execute(fn => fn(trx)). A permissive chainable
+      // Proxy stands in for the Kysely trx so the per-space advisory-lock
+      // `sql``.execute(trx)` resolves; a thrown BadRequestException still
+      // propagates out of the transaction unchanged.
+      const trxStub: any = new Proxy(function () {}, {
+        get: (_t, p) =>
+          p === 'then'
+            ? undefined
+            : p === 'execute' || p === 'executeTakeFirst'
+              ? () => Promise.resolve([])
+              : () => trxStub,
+      });
+      const db = {
+        transaction: () => ({ execute: (fn: any) => fn(trxStub) }),
+      };
+
       const svc = new PageService(
         pageRepo as any, // pageRepo
         {} as any, // pagePermissionRepo
         {} as any, // attachmentRepo
-        {} as any, // db
+        db as any, // db
         {} as any, // storageService
         {} as any, // attachmentQueue
         {} as any, // aiQueue
@@ -271,9 +288,23 @@ describe('PageService', () => {
           }),
           updatePage: jest.fn().mockResolvedValue({ numUpdatedRows: 1n }),
         };
+        // movePage now runs the cycle-check + UPDATE inside executeTx(this.db),
+        // which calls this.db.transaction().execute(fn => fn(trx)). A permissive
+        // chainable Proxy stands in for the Kysely trx so the per-space
+        // advisory-lock `sql``.execute(trx)` resolves and updatePage receives it.
+        const trxStub: any = new Proxy(function () {}, {
+          get: (_t, p) =>
+            p === 'then'
+              ? undefined
+              : p === 'execute' || p === 'executeTakeFirst'
+                ? () => Promise.resolve([])
+                : () => trxStub,
+        });
         const svc = makeSvc({
           pageRepo,
-          db: {} as any,
+          db: {
+            transaction: () => ({ execute: (fn: any) => fn(trxStub) }),
+          } as any,
         });
         // Legitimate move: destination ancestors do NOT include the moved page.
         jest
@@ -546,11 +577,27 @@ describe('PageService', () => {
         };
         const eventEmitter = { emit: jest.fn() };
 
+        // movePage now runs the cycle-check + UPDATE inside executeTx(this.db),
+        // i.e. this.db.transaction().execute(fn => fn(trx)). A permissive
+        // chainable Proxy stands in for the Kysely trx so the per-space
+        // advisory-lock `sql``.execute(trx)` resolves and updatePage runs.
+        const trxStub: any = new Proxy(function () {}, {
+          get: (_t, p) =>
+            p === 'then'
+              ? undefined
+              : p === 'execute' || p === 'executeTakeFirst'
+                ? () => Promise.resolve([])
+                : () => trxStub,
+        });
+        const db = {
+          transaction: () => ({ execute: (fn: any) => fn(trxStub) }),
+        };
+
         const svc = new PageService(
           pageRepo as any, // pageRepo
           {} as any, // pagePermissionRepo
           {} as any, // attachmentRepo
-          {} as any, // db
+          db as any, // db
           {} as any, // storageService
           {} as any, // attachmentQueue
           {} as any, // aiQueue

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

@@ -15,13 +15,13 @@ import {
   executeWithCursorPagination,
 } from '@docmost/db/pagination/cursor-pagination';
 import { InjectKysely } from 'nestjs-kysely';
-import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
 import { generateJitteredKeyBetween } from 'fractional-indexing-jittered';
 import { MovePageDto } from '../dto/move-page.dto';
 import { shapeSidebarPagesTree } from './sidebar-pages-tree.util';
 import { generateSlugId } from '../../../common/helpers';
 import { getPageTitle } from '../../../common/helpers';
-import { executeTx } from '@docmost/db/utils';
+import { dbOrTx, executeTx } from '@docmost/db/utils';
 import { AttachmentRepo } from '@docmost/db/repos/attachment/attachment.repo';
 import { v7 as uuid7 } from 'uuid';
 import {
@@ -62,6 +62,23 @@ import {
   agentSourceFields,
 } from '../../../common/decorators/auth-provenance.decorator';
 
+// Hard upper bound on how deep the recursive page-tree CTEs (ancestor /
+// descendant traversals) may walk. Real page trees are only a handful of levels
+// deep, so this cap never truncates a legitimate result; it purely defends the
+// recursive CTEs against runaway iteration if a parent/child cycle ever exists
+// in the data (e.g. one slipped in before the move guard, #207 #8). Without it a
+// cycle makes `withRecursive` loop forever (hang / statement timeout), and the
+// move guard itself calls one of these CTEs — so a cycle would disable the very
+// guard meant to prevent it. Each CTE carries a depth counter and stops here.
+const MAX_PAGE_TREE_DEPTH = 10_000;
+
+// Advisory-lock namespace (the first key of pg_advisory_xact_lock) used to
+// serialize concurrent page moves within a single space so the cycle check and
+// the move UPDATE stay atomic (see movePage, #207 #7). A dedicated namespace
+// constant keeps these locks from colliding with any other advisory lock; the
+// second key is hashtext(spaceId). Fits a signed int4 ('page' in ASCII).
+const PAGE_MOVE_LOCK_NAMESPACE = 0x70616765;
+
 @Injectable()
 export class PageService {
   private readonly logger = new Logger(PageService.name);
@@ -601,7 +618,13 @@ export class PageService {
       slugIdMap.set(entry.oldSlugId, entry);
     }
 
-    const attachmentMap = new Map<string, ICopyPageAttachment>();
+    // Keyed by old attachmentId. A single attachment can be referenced by more
+    // than one page in the copied subtree (e.g. a block copy-pasted into a child
+    // page keeps the same attachmentId). Each referencing page needs its own
+    // fresh attachment id / row / blob copy, so the value is a LIST of copy
+    // entries rather than a single one — otherwise the last page's entry would
+    // clobber the others and their images would 404 in the copies (#206 attach-1).
+    const attachmentMap = new Map<string, ICopyPageAttachment[]>();
 
     const insertablePages: InsertablePage[] = await Promise.all(
       pages.map(async (page) => {
@@ -617,12 +640,14 @@ export class PageService {
           attachmentIds.forEach((attachmentId: string) => {
             const newPageId = pageFromMap.newPageId;
             const newAttachmentId = uuid7();
-            attachmentMap.set(attachmentId, {
+            const existingEntries = attachmentMap.get(attachmentId) ?? [];
+            existingEntries.push({
               newPageId: newPageId,
               oldPageId: page.id,
               oldAttachmentId: attachmentId,
               newAttachmentId: newAttachmentId,
             });
+            attachmentMap.set(attachmentId, existingEntries);
 
             prosemirrorDoc.descendants((node: PMNode) => {
               if (isAttachmentNode(node.type.name)) {
@@ -819,51 +844,53 @@ export class PageService {
         .execute();
 
       for (const attachment of attachments) {
-        try {
-          const pageAttachment = attachmentMap.get(attachment.id);
-
-          // make sure the copied attachment belongs to the page it was copied from
-          if (attachment.pageId !== pageAttachment.oldPageId) {
-            continue;
-          }
-
-          const newAttachmentId = pageAttachment.newAttachmentId;
-
-          const newPageId = pageAttachment.newPageId;
-
-          const newPathFile = attachment.filePath.replace(
-            attachment.id,
-            newAttachmentId,
-          );
-
+        // One source attachment may need to be copied for several destination
+        // pages (it is referenced by more than one page in the subtree). Copy a
+        // distinct blob + row for every referencing page so each copy resolves
+        // (#206 attach-1). The old per-page ownership guard is gone: when the
+        // same attachmentId is shared, only one page would ever match the row's
+        // pageId, silently dropping the other copies.
+        const pageAttachments = attachmentMap.get(attachment.id) ?? [];
+        for (const pageAttachment of pageAttachments) {
           try {
-            await this.storageService.copy(attachment.filePath, newPathFile);
+            const newAttachmentId = pageAttachment.newAttachmentId;
 
-            await this.db
-              .insertInto('attachments')
-              .values({
-                id: newAttachmentId,
-                type: attachment.type,
-                filePath: newPathFile,
-                fileName: attachment.fileName,
-                fileSize: attachment.fileSize,
-                mimeType: attachment.mimeType,
-                fileExt: attachment.fileExt,
-                creatorId: attachment.creatorId,
-                workspaceId: attachment.workspaceId,
-                pageId: newPageId,
-                spaceId: spaceId,
-              })
-              .execute();
-          } catch (err) {
-            this.logger.error(
-              `Duplicate page: failed to copy attachment ${attachment.id}`,
-              err,
+            const newPageId = pageAttachment.newPageId;
+
+            const newPathFile = attachment.filePath.replace(
+              attachment.id,
+              newAttachmentId,
             );
-            // Continue with other attachments even if one fails
+
+            try {
+              await this.storageService.copy(attachment.filePath, newPathFile);
+
+              await this.db
+                .insertInto('attachments')
+                .values({
+                  id: newAttachmentId,
+                  type: attachment.type,
+                  filePath: newPathFile,
+                  fileName: attachment.fileName,
+                  fileSize: attachment.fileSize,
+                  mimeType: attachment.mimeType,
+                  fileExt: attachment.fileExt,
+                  creatorId: attachment.creatorId,
+                  workspaceId: attachment.workspaceId,
+                  pageId: newPageId,
+                  spaceId: spaceId,
+                })
+                .execute();
+            } catch (err) {
+              this.logger.error(
+                `Duplicate page: failed to copy attachment ${attachment.id}`,
+                err,
+              );
+              // Continue with other attachments even if one fails
+            }
+          } catch (err) {
+            this.logger.error(err);
           }
-        } catch (err) {
-          this.logger.error(err);
         }
       }
     }
@@ -915,34 +942,61 @@ export class PageService {
       }
     }
 
-    // Server-side cycle guard: a page may not be moved into itself or into any
-    // page within its own subtree. Without this, an MCP/REST/agent caller (or a
-    // fast drag racing the client check) could persist a cycle and broadcast it.
-    // Only relevant when re-parenting under a concrete parent; moving to root
-    // (parentPageId null/undefined) can never create a cycle.
-    if (dto.parentPageId) {
-      if (dto.parentPageId === dto.pageId) {
-        throw new BadRequestException('Cannot move a page into its own subtree');
-      }
-      // Walk the destination parent's ancestor chain (reusing the breadcrumb
-      // ancestor CTE). If the page being moved appears among those ancestors,
-      // the destination lives inside the moved page's subtree -> cycle.
-      const destAncestors = await this.getPageBreadCrumbs(dto.parentPageId);
-      if (destAncestors.some((ancestor) => ancestor.id === dto.pageId)) {
-        throw new BadRequestException('Cannot move a page into its own subtree');
-      }
-    }
+    // Server-side cycle guard + the move UPDATE run in ONE transaction. A page
+    // may not be moved into itself or into any page within its own subtree;
+    // without this an MCP/REST/agent caller (or a fast drag racing the client
+    // check) could persist a cycle and broadcast it. Crucially, doing the guard
+    // and the write as two separate, unlocked statements is a TOCTOU race: two
+    // concurrent moves ("A under B" and "B under A") can each read the same
+    // pre-write acyclic snapshot, both pass the guard, then persist
+    // A.parentPageId=B AND B.parentPageId=A — a parent/child cycle (#207 #7). A
+    // per-space advisory lock (held until COMMIT) serializes all moves within a
+    // space: the second mover blocks until the first commits and then sees the
+    // freshly written parent, so its guard rejects the cycle.
+    const updateResult = await executeTx(this.db, async (trx) => {
+      await sql`select pg_advisory_xact_lock(${sql.lit(
+        PAGE_MOVE_LOCK_NAMESPACE,
+      )}, hashtext(${movedPage.spaceId}))`.execute(trx);
 
-    const updateResult = await this.pageRepo.updatePage(
-      {
-        position: dto.position,
-        parentPageId: parentPageId,
-        // Agent-edit provenance: annotate the source on an agent move. A normal
-        // user request leaves the existing source value unchanged.
-        ...agentSourceFields(provenance, 'lastUpdatedSource', 'lastUpdatedAiChatId'),
-      },
-      dto.pageId,
-    );
+      // Only relevant when re-parenting under a concrete parent; moving to root
+      // (parentPageId null/undefined) can never create a cycle.
+      if (dto.parentPageId) {
+        if (dto.parentPageId === dto.pageId) {
+          throw new BadRequestException(
+            'Cannot move a page into its own subtree',
+          );
+        }
+        // Walk the destination parent's ancestor chain (reusing the breadcrumb
+        // ancestor CTE) inside the lock. If the page being moved appears among
+        // those ancestors, the destination lives inside the moved page's
+        // subtree -> cycle.
+        const destAncestors = await this.getPageBreadCrumbs(
+          dto.parentPageId,
+          trx,
+        );
+        if (destAncestors.some((ancestor) => ancestor.id === dto.pageId)) {
+          throw new BadRequestException(
+            'Cannot move a page into its own subtree',
+          );
+        }
+      }
+
+      return this.pageRepo.updatePage(
+        {
+          position: dto.position,
+          parentPageId: parentPageId,
+          // Agent-edit provenance: annotate the source on an agent move. A
+          // normal user request leaves the existing source value unchanged.
+          ...agentSourceFields(
+            provenance,
+            'lastUpdatedSource',
+            'lastUpdatedAiChatId',
+          ),
+        },
+        dto.pageId,
+        trx,
+      );
+    });
 
     // Guard against a phantom broadcast: if the row was concurrently deleted or
     // otherwise not updated, skip the PAGE_MOVED event so we don't replay a move
@@ -981,8 +1035,8 @@ export class PageService {
     });
   }
 
-  async getPageBreadCrumbs(childPageId: string) {
-    const ancestors = await this.db
+  async getPageBreadCrumbs(childPageId: string, trx?: KyselyTransaction) {
+    const ancestors = await dbOrTx(this.db, trx)
       .withRecursive('page_ancestors', (db) =>
         db
           .selectFrom('pages')
@@ -996,6 +1050,9 @@ export class PageService {
             'spaceId',
             'deletedAt',
           ])
+          // Depth counter: bounds the walk so a parent/child cycle in the data
+          // can't make this recursive CTE loop forever (#207 #8).
+          .select(sql<number>`0`.as('depth'))
           .where('id', '=', childPageId)
           .where('deletedAt', 'is', null)
           .unionAll((exp) =>
@@ -1011,12 +1068,25 @@ export class PageService {
                 'p.spaceId',
                 'p.deletedAt',
               ])
+              .select(sql<number>`pa.depth + 1`.as('depth'))
               .innerJoin('page_ancestors as pa', 'pa.parentPageId', 'p.id')
-              .where('p.deletedAt', 'is', null),
+              .where('p.deletedAt', 'is', null)
+              .where(sql<number>`pa.depth`, '<', MAX_PAGE_TREE_DEPTH),
           ),
       )
       .selectFrom('page_ancestors')
-      .selectAll('page_ancestors')
+      // Explicit column list (not selectAll) so the internal `depth` counter
+      // never leaks into the breadcrumb result shape.
+      .select([
+        'id',
+        'slugId',
+        'title',
+        'icon',
+        'position',
+        'parentPageId',
+        'spaceId',
+        'deletedAt',
+      ])
       .select((eb) =>
         eb
           .exists(
@@ -1137,16 +1207,21 @@ export class PageService {
         db
           .selectFrom('pages')
           .select(['id'])
+          // Depth counter: bounds the walk so a parent/child cycle in the data
+          // can't make this recursive CTE loop forever (#207 #8).
+          .select(sql<number>`0`.as('depth'))
           .where('id', '=', pageId)
           .unionAll((exp) =>
             exp
               .selectFrom('pages as p')
               .select(['p.id'])
-              .innerJoin('page_descendants as pd', 'pd.id', 'p.parentPageId'),
+              .select(sql<number>`pd.depth + 1`.as('depth'))
+              .innerJoin('page_descendants as pd', 'pd.id', 'p.parentPageId')
+              .where(sql<number>`pd.depth`, '<', MAX_PAGE_TREE_DEPTH),
           ),
       )
       .selectFrom('page_descendants')
-      .selectAll()
+      .select(['id'])
       .execute();
 
     const pageIds = descendants.map((d) => d.id);

apps/server/src/core/share/dto/share-alias.dto.ts

@@ -0,0 +1,44 @@
+import {
+  IsBoolean,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+} from 'class-validator';
+
+/**
+ * Create/retarget a vanity alias for a page. `confirmReassign` is the
+ * two-step guard for the "address already points at another page" case: the
+ * first call without it gets a 409 carrying the current target, the client
+ * confirms, and retries with `confirmReassign: true`.
+ */
+export class SetShareAliasDto {
+  @IsString()
+  @IsNotEmpty()
+  pageId: string;
+
+  @IsString()
+  @IsNotEmpty()
+  alias: string;
+
+  @IsBoolean()
+  @IsOptional()
+  confirmReassign?: boolean;
+}
+
+export class RemoveShareAliasDto {
+  @IsString()
+  @IsNotEmpty()
+  aliasId: string;
+}
+
+export class ShareAliasAvailabilityDto {
+  @IsString()
+  @IsNotEmpty()
+  alias: string;
+}
+
+export class ShareAliasForPageDto {
+  @IsString()
+  @IsNotEmpty()
+  pageId: string;
+}

apps/server/src/core/share/share-alias-redirect.controller.spec.ts

@@ -0,0 +1,252 @@
+import * as fs from 'node:fs';
+
+// `@sindresorhus/slugify` is ESM-only and not in jest's transformIgnorePatterns,
+// so the real module fails to parse under ts-jest. Stub it with a minimal,
+// deterministic slugifier — this spec asserts the controller's slug *assembly*
+// (`<title-slug>-<slugId>`, 70-char clamp, `untitled` fallback), not the upstream
+// slug algorithm. The factory keeps the real ESM module from ever being loaded.
+jest.mock('@sindresorhus/slugify', () => ({
+  __esModule: true,
+  default: (input: string) =>
+    String(input)
+      .toLowerCase()
+      .trim()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, ''),
+}));
+
+import { ShareAliasRedirectController } from './share-alias-redirect.controller';
+
+/**
+ * Routing/leak guard for the PUBLIC `GET /l/:alias` resolver.
+ *
+ * This is the most security-sensitive surface of the alias feature: an
+ * unauthenticated route that MUST serve the plain SPA index (exactly like any
+ * unknown path) for an unknown / dangling / no-longer-readable alias so that the
+ * existence of a name never leaks. Only a resolvable, still-readable alias may
+ * 302 to the canonical `/share/<key>/p/<title-slug>-<slugId>` page (302 — never
+ * 301 — because the target is retargetable). These tests pin that routing and
+ * the defensive percent-decoding, mirroring `share-seo.controller.routing.spec`.
+ */
+
+const STREAM_SENTINEL = { __isStream: true } as unknown as fs.ReadStream;
+
+// Stub fs at CALL time (jest.spyOn), NOT module load (jest.mock): the controller
+// transitively pulls bcrypt, whose native module is located by node-gyp-build
+// reading the filesystem at import time — a module-level fs mock breaks that.
+beforeEach(() => {
+  jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+  jest.spyOn(fs, 'createReadStream').mockReturnValue(STREAM_SENTINEL);
+});
+afterEach(() => jest.restoreAllMocks());
+
+function makeRes() {
+  const res: any = {
+    sent: undefined as unknown,
+    statusCode: undefined as number | undefined,
+    redirectUrl: undefined as string | undefined,
+    type: jest.fn(() => res),
+    status: jest.fn((code: number) => {
+      res.statusCode = code;
+      return res;
+    }),
+    send: jest.fn((v: unknown) => {
+      res.sent = v;
+      return res;
+    }),
+    redirect: jest.fn((url: string, code: number) => {
+      res.redirectUrl = url;
+      res.statusCode = code;
+      return res;
+    }),
+  };
+  return res;
+}
+
+function makeController(opts: {
+  resolved?: { share: any; page: any } | null;
+  selfHosted?: boolean;
+}) {
+  const shareAliasService = {
+    resolveReadableTarget: jest.fn(async () => opts.resolved ?? null),
+  };
+  const workspaceRepo = {
+    findFirst: jest.fn(async () => ({ id: 'ws-self' })),
+    findByHostname: jest.fn(async (sub: string) =>
+      sub === 'acme' ? { id: 'ws-acme' } : null,
+    ),
+  };
+  const environmentService = {
+    isSelfHosted: jest.fn(() => opts.selfHosted ?? true),
+  };
+  const controller = new ShareAliasRedirectController(
+    shareAliasService as any,
+    workspaceRepo as any,
+    environmentService as any,
+  );
+  return { controller, shareAliasService, workspaceRepo, environmentService };
+}
+
+const selfReq: any = { raw: { headers: { host: 'self' } } };
+
+describe('ShareAliasRedirectController.resolve', () => {
+  it('302-redirects a resolvable alias to the canonical share page', async () => {
+    const { controller, shareAliasService } = makeController({
+      resolved: {
+        share: { key: 'SHAREKEY' },
+        page: { slugId: 'abc123', title: 'Quarterly Report' },
+      },
+    });
+    const res = makeRes();
+
+    await controller.resolve('promo', selfReq, res);
+
+    expect(shareAliasService.resolveReadableTarget).toHaveBeenCalledWith(
+      'promo',
+      'ws-self',
+    );
+    expect(res.redirect).toHaveBeenCalledWith(
+      '/share/SHAREKEY/p/quarterly-report-abc123',
+      302,
+    );
+    // No index stream was served on a hit.
+    expect(res.sent).toBeUndefined();
+  });
+
+  it('falls back to "untitled" in the slug when the target has no title', async () => {
+    const { controller } = makeController({
+      resolved: { share: { key: 'K' }, page: { slugId: 'sid', title: '' } },
+    });
+    const res = makeRes();
+
+    await controller.resolve('promo', selfReq, res);
+
+    expect(res.redirect).toHaveBeenCalledWith('/share/K/p/untitled-sid', 302);
+  });
+
+  it('clamps the title-slug to the first 70 characters of the page title', async () => {
+    // 119-char title; only the first 70 chars must reach the slug. The 70-char
+    // boundary deliberately falls mid-word ("Entire" -> "entir") so the clamp is
+    // unambiguous: anything past char 70 ("...e Fiscal Year...") must be dropped.
+    const longTitle =
+      'The Comprehensive Quarterly Financial Performance Report For The Entire Fiscal Year Two Thousand Twenty Five And Beyond';
+    const { controller } = makeController({
+      resolved: {
+        share: { key: 'K' },
+        page: { slugId: 'sid', title: longTitle },
+      },
+    });
+    const res = makeRes();
+
+    await controller.resolve('promo', selfReq, res);
+
+    expect(res.redirect).toHaveBeenCalledWith(
+      '/share/K/p/the-comprehensive-quarterly-financial-performance-report-for-the-entir-sid',
+      302,
+    );
+  });
+
+  it('streams the SPA index WITHOUT a 302 for an unknown/dangling/unreadable alias (no leak)', async () => {
+    const { controller, shareAliasService } = makeController({ resolved: null });
+    const res = makeRes();
+
+    await controller.resolve('does-not-exist', selfReq, res);
+
+    expect(shareAliasService.resolveReadableTarget).toHaveBeenCalled();
+    // The plain index stream was served and no redirect leaked alias existence.
+    expect(res.redirect).not.toHaveBeenCalled();
+    expect(res.sent).toBe(STREAM_SENTINEL);
+    expect(res.type).toHaveBeenCalledWith('text/html');
+  });
+
+  it('streams the SPA index without even resolving when the workspace is null', async () => {
+    // Subdomain host that maps to no workspace => workspace === null.
+    const { controller, shareAliasService, workspaceRepo } = makeController({
+      selfHosted: false,
+    });
+    const res = makeRes();
+    const req: any = { raw: { headers: { host: 'unknown.example.com' } } };
+
+    await controller.resolve('promo', req, res);
+
+    expect(workspaceRepo.findByHostname).toHaveBeenCalledWith('unknown');
+    // Never even attempts to resolve (alias existence cannot leak per-host).
+    expect(shareAliasService.resolveReadableTarget).not.toHaveBeenCalled();
+    expect(res.redirect).not.toHaveBeenCalled();
+    expect(res.sent).toBe(STREAM_SENTINEL);
+  });
+
+  it('defensively decodes broken percent-encoding and treats it as unknown', async () => {
+    const { controller, shareAliasService } = makeController({ resolved: null });
+    const res = makeRes();
+
+    // '%E0%A4%A' is invalid -> decodeURIComponent throws -> raw value is used,
+    // and the alias resolves to nothing (no crash, served as index).
+    await controller.resolve('%E0%A4%A', selfReq, res);
+
+    expect(shareAliasService.resolveReadableTarget).toHaveBeenCalledWith(
+      '%E0%A4%A',
+      'ws-self',
+    );
+    expect(res.redirect).not.toHaveBeenCalled();
+    expect(res.sent).toBe(STREAM_SENTINEL);
+  });
+
+  it('decodes a valid percent-encoded alias before resolving', async () => {
+    const { controller, shareAliasService } = makeController({ resolved: null });
+    const res = makeRes();
+
+    await controller.resolve('my%2Dlink', selfReq, res);
+
+    expect(shareAliasService.resolveReadableTarget).toHaveBeenCalledWith(
+      'my-link',
+      'ws-self',
+    );
+  });
+
+  it('resolves the workspace via findFirst on the self-hosted path', async () => {
+    const { controller, workspaceRepo, shareAliasService } = makeController({
+      selfHosted: true,
+      resolved: null,
+    });
+    const res = makeRes();
+
+    await controller.resolve('promo', selfReq, res);
+
+    expect(workspaceRepo.findFirst).toHaveBeenCalled();
+    expect(workspaceRepo.findByHostname).not.toHaveBeenCalled();
+    expect(shareAliasService.resolveReadableTarget).toHaveBeenCalledWith(
+      'promo',
+      'ws-self',
+    );
+  });
+
+  it('resolves the workspace via findByHostname (subdomain) on the cloud path', async () => {
+    const { controller, workspaceRepo, shareAliasService } = makeController({
+      selfHosted: false,
+      resolved: null,
+    });
+    const res = makeRes();
+    const req: any = { raw: { headers: { host: 'acme.example.com' } } };
+
+    await controller.resolve('promo', req, res);
+
+    expect(workspaceRepo.findByHostname).toHaveBeenCalledWith('acme');
+    expect(workspaceRepo.findFirst).not.toHaveBeenCalled();
+    expect(shareAliasService.resolveReadableTarget).toHaveBeenCalledWith(
+      'promo',
+      'ws-acme',
+    );
+  });
+
+  it('serves a 404 when no built client index exists', async () => {
+    jest.spyOn(fs, 'existsSync').mockReturnValue(false);
+    const { controller } = makeController({ resolved: null });
+    const res = makeRes();
+
+    await controller.resolve('promo', selfReq, res);
+
+    expect(res.status).toHaveBeenCalledWith(404);
+    expect(res.redirect).not.toHaveBeenCalled();
+  });
+});

apps/server/src/core/share/share-alias-redirect.controller.ts

@@ -0,0 +1,95 @@
+import { Controller, Get, Param, Req, Res } from '@nestjs/common';
+import { FastifyReply, FastifyRequest } from 'fastify';
+import { join } from 'path';
+import * as fs from 'node:fs';
+import slugify from '@sindresorhus/slugify';
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
+import { EnvironmentService } from '../../integrations/environment/environment.service';
+import { Workspace } from '@docmost/db/types/entity.types';
+import { ShareAliasService } from './share-alias.service';
+
+/**
+ * Public resolver for vanity links `GET /l/:alias`. Excluded from the global
+ * `/api` prefix (see main.ts) and parallel to ShareSeoController.
+ *
+ * On a hit it issues a 302 (NEVER 301) to the canonical
+ * `/share/:key/p/:slug` page, so:
+ *   - the existing share render + SSR meta is reused verbatim (crawlers follow
+ *     the 302 and get the correct preview);
+ *   - because the alias target is mutable, a temporary redirect is always
+ *     re-resolved — a cached 301 would pin clients to the pre-swap page.
+ *
+ * Any unknown / dangling / no-longer-readable alias serves the plain SPA index
+ * (same as any unknown path) so the existence of a name never leaks.
+ */
+@Controller('l')
+export class ShareAliasRedirectController {
+  constructor(
+    private readonly shareAliasService: ShareAliasService,
+    private readonly workspaceRepo: WorkspaceRepo,
+    private readonly environmentService: EnvironmentService,
+  ) {}
+
+  @Get(':alias')
+  async resolve(
+    @Param('alias') rawAlias: string,
+    @Req() req: FastifyRequest,
+    @Res({ passthrough: false }) res: FastifyReply,
+  ) {
+    // NestJS does not apply middlewares to paths excluded from the global /api
+    // prefix, so the DomainMiddleware workspace resolution is duplicated here
+    // (same workaround as ShareSeoController).
+    let workspace: Workspace = null;
+    if (this.environmentService.isSelfHosted()) {
+      workspace = await this.workspaceRepo.findFirst();
+    } else {
+      const header = req.raw.headers.host;
+      const subdomain = header?.split('.')[0];
+      workspace = subdomain
+        ? await this.workspaceRepo.findByHostname(subdomain)
+        : null;
+    }
+
+    const clientDistPath = join(__dirname, '..', '..', '..', '..', 'client/dist');
+    const indexFilePath = join(clientDistPath, 'index.html');
+
+    let decoded = rawAlias;
+    try {
+      decoded = decodeURIComponent(rawAlias);
+    } catch {
+      // Malformed percent-encoding -> treat as unknown alias.
+    }
+
+    const resolved = workspace
+      ? await this.shareAliasService.resolveReadableTarget(
+          decoded,
+          workspace.id,
+        )
+      : null;
+
+    if (!resolved) {
+      return this.sendIndex(indexFilePath, res);
+    }
+
+    const slug = buildPageSlug(resolved.page.slugId, resolved.page.title);
+    // 302, NOT 301: the alias is retargetable, so the redirect must always be
+    // re-resolved by clients/crawlers.
+    return res.redirect(`/share/${resolved.share.key}/p/${slug}`, 302);
+  }
+
+  private sendIndex(indexFilePath: string, res: FastifyReply) {
+    if (!fs.existsSync(indexFilePath)) {
+      // No built client (e.g. API-only dev): nothing to serve.
+      res.status(404).send('Not found');
+      return;
+    }
+    const stream = fs.createReadStream(indexFilePath);
+    res.type('text/html').send(stream);
+  }
+}
+
+/** Canonical share page slug: `<title-slug>-<slugId>` (mirrors the client). */
+function buildPageSlug(slugId: string, title?: string): string {
+  const titleSlug = slugify(title?.substring(0, 70) || 'untitled');
+  return `${titleSlug}-${slugId}`;
+}

apps/server/src/core/share/share-alias.controller.spec.ts

@@ -0,0 +1,260 @@
+import {
+  BadRequestException,
+  ForbiddenException,
+  NotFoundException,
+} from '@nestjs/common';
+import { ShareAliasController } from './share-alias.controller';
+
+/**
+ * Authz-gate tests for the authenticated alias management controller. The access
+ * decisions for creating/retargeting/removing an alias live in THIS controller
+ * (the service spec delegates authorization to the caller), so each gate is
+ * pinned here against mocked PageRepo / ShareService / ShareAliasService /
+ * PageAccessService. A regression that drops any gate must fail here.
+ */
+describe('ShareAliasController authz gates', () => {
+  function makeController() {
+    const shareAliasService = {
+      setAlias: jest.fn(async () => ({ id: 'alias-1' })),
+      removeAlias: jest.fn(async () => undefined),
+      getAliasById: jest.fn(),
+      getAliasForPage: jest.fn(),
+      checkAvailability: jest.fn(),
+    };
+    const shareService = {
+      resolveReadableSharePage: jest.fn(),
+      isSharingAllowed: jest.fn(),
+    };
+    const pageRepo = { findById: jest.fn() };
+    const pageAccessService = {
+      validateCanEdit: jest.fn(async () => undefined),
+      validateCanView: jest.fn(async () => undefined),
+    };
+    const controller = new ShareAliasController(
+      shareAliasService as any,
+      shareService as any,
+      pageRepo as any,
+      pageAccessService as any,
+    );
+    return {
+      controller,
+      shareAliasService,
+      shareService,
+      pageRepo,
+      pageAccessService,
+    };
+  }
+
+  const user: any = { id: 'u-1' };
+  const workspace: any = { id: 'ws-1' };
+
+  describe('set', () => {
+    it('throws NotFoundException for a nonexistent page', async () => {
+      const { controller, pageRepo, pageAccessService } = makeController();
+      pageRepo.findById.mockResolvedValue(null);
+
+      await expect(
+        controller.set({ pageId: 'p-x', alias: 'promo' } as any, user, workspace),
+      ).rejects.toBeInstanceOf(NotFoundException);
+      expect(pageAccessService.validateCanEdit).not.toHaveBeenCalled();
+    });
+
+    it('throws NotFoundException for a page in another workspace', async () => {
+      const { controller, pageRepo } = makeController();
+      pageRepo.findById.mockResolvedValue({
+        id: 'p-1',
+        workspaceId: 'ws-OTHER',
+      });
+
+      await expect(
+        controller.set({ pageId: 'p-1', alias: 'promo' } as any, user, workspace),
+      ).rejects.toBeInstanceOf(NotFoundException);
+    });
+
+    it('enforces validateCanEdit before setting the alias', async () => {
+      const { controller, pageRepo, pageAccessService, shareService } =
+        makeController();
+      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
+      pageAccessService.validateCanEdit.mockRejectedValue(
+        new ForbiddenException('no edit'),
+      );
+
+      await expect(
+        controller.set({ pageId: 'p-1', alias: 'promo' } as any, user, workspace),
+      ).rejects.toBeInstanceOf(ForbiddenException);
+      // Gate short-circuits before any share resolution.
+      expect(shareService.resolveReadableSharePage).not.toHaveBeenCalled();
+    });
+
+    it('throws BadRequestException when the page is not publicly shared', async () => {
+      const { controller, pageRepo, shareService } = makeController();
+      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
+      shareService.resolveReadableSharePage.mockResolvedValue(null);
+
+      await expect(
+        controller.set({ pageId: 'p-1', alias: 'promo' } as any, user, workspace),
+      ).rejects.toThrow('Page is not publicly shared');
+      await expect(
+        controller.set({ pageId: 'p-1', alias: 'promo' } as any, user, workspace),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it('throws ForbiddenException when public sharing is disabled', async () => {
+      const { controller, pageRepo, shareService } = makeController();
+      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
+      shareService.resolveReadableSharePage.mockResolvedValue({
+        share: { spaceId: 'sp-1' },
+      });
+      shareService.isSharingAllowed.mockResolvedValue(false);
+
+      await expect(
+        controller.set({ pageId: 'p-1', alias: 'promo' } as any, user, workspace),
+      ).rejects.toBeInstanceOf(ForbiddenException);
+    });
+
+    it('delegates to setAlias on the happy path with all gates passed', async () => {
+      const { controller, pageRepo, shareService, shareAliasService } =
+        makeController();
+      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
+      shareService.resolveReadableSharePage.mockResolvedValue({
+        share: { spaceId: 'sp-1' },
+      });
+      shareService.isSharingAllowed.mockResolvedValue(true);
+
+      const result = await controller.set(
+        { pageId: 'p-1', alias: 'promo', confirmReassign: true } as any,
+        user,
+        workspace,
+      );
+
+      expect(shareAliasService.setAlias).toHaveBeenCalledWith({
+        workspaceId: 'ws-1',
+        pageId: 'p-1',
+        creatorId: 'u-1',
+        alias: 'promo',
+        confirmReassign: true,
+      });
+      expect(result).toEqual({ id: 'alias-1' });
+    });
+  });
+
+  describe('remove', () => {
+    it('throws NotFoundException for an unknown alias', async () => {
+      const { controller, shareAliasService } = makeController();
+      shareAliasService.getAliasById.mockResolvedValue(null);
+
+      await expect(
+        controller.remove({ aliasId: 'a-x' } as any, user, workspace),
+      ).rejects.toBeInstanceOf(NotFoundException);
+      expect(shareAliasService.removeAlias).not.toHaveBeenCalled();
+    });
+
+    it('requires validateCanEdit on the current target before removing', async () => {
+      const { controller, shareAliasService, pageRepo, pageAccessService } =
+        makeController();
+      shareAliasService.getAliasById.mockResolvedValue({
+        id: 'a-1',
+        pageId: 'p-1',
+      });
+      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
+      pageAccessService.validateCanEdit.mockRejectedValue(
+        new ForbiddenException('no edit'),
+      );
+
+      await expect(
+        controller.remove({ aliasId: 'a-1' } as any, user, workspace),
+      ).rejects.toBeInstanceOf(ForbiddenException);
+      expect(shareAliasService.removeAlias).not.toHaveBeenCalled();
+    });
+
+    it('removes a dangling alias (pageId null) WITHOUT an edit check', async () => {
+      const { controller, shareAliasService, pageRepo, pageAccessService } =
+        makeController();
+      shareAliasService.getAliasById.mockResolvedValue({
+        id: 'a-1',
+        pageId: null,
+      });
+
+      await controller.remove({ aliasId: 'a-1' } as any, user, workspace);
+
+      expect(pageRepo.findById).not.toHaveBeenCalled();
+      expect(pageAccessService.validateCanEdit).not.toHaveBeenCalled();
+      expect(shareAliasService.removeAlias).toHaveBeenCalledWith('a-1', 'ws-1');
+    });
+
+    it('removes when the editor can edit the current target', async () => {
+      const { controller, shareAliasService, pageRepo, pageAccessService } =
+        makeController();
+      shareAliasService.getAliasById.mockResolvedValue({
+        id: 'a-1',
+        pageId: 'p-1',
+      });
+      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
+
+      await controller.remove({ aliasId: 'a-1' } as any, user, workspace);
+
+      expect(pageAccessService.validateCanEdit).toHaveBeenCalled();
+      expect(shareAliasService.removeAlias).toHaveBeenCalledWith('a-1', 'ws-1');
+    });
+
+    it('removes even if the recorded target page no longer exists', async () => {
+      const { controller, shareAliasService, pageRepo, pageAccessService } =
+        makeController();
+      shareAliasService.getAliasById.mockResolvedValue({
+        id: 'a-1',
+        pageId: 'p-gone',
+      });
+      pageRepo.findById.mockResolvedValue(null);
+
+      await controller.remove({ aliasId: 'a-1' } as any, user, workspace);
+
+      expect(pageAccessService.validateCanEdit).not.toHaveBeenCalled();
+      expect(shareAliasService.removeAlias).toHaveBeenCalledWith('a-1', 'ws-1');
+    });
+  });
+
+  describe('forPage', () => {
+    it('throws NotFoundException for a cross-workspace/nonexistent page', async () => {
+      const { controller, pageRepo, pageAccessService } = makeController();
+      pageRepo.findById.mockResolvedValue({
+        id: 'p-1',
+        workspaceId: 'ws-OTHER',
+      });
+
+      await expect(
+        controller.forPage({ pageId: 'p-1' } as any, user, workspace),
+      ).rejects.toBeInstanceOf(NotFoundException);
+      expect(pageAccessService.validateCanView).not.toHaveBeenCalled();
+    });
+
+    it('requires validateCanView and returns the alias (or null)', async () => {
+      const { controller, pageRepo, pageAccessService, shareAliasService } =
+        makeController();
+      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
+      shareAliasService.getAliasForPage.mockResolvedValue({ id: 'a-1' });
+
+      const result = await controller.forPage(
+        { pageId: 'p-1' } as any,
+        user,
+        workspace,
+      );
+
+      expect(pageAccessService.validateCanView).toHaveBeenCalled();
+      expect(result).toEqual({ id: 'a-1' });
+    });
+
+    it('returns null when the page has no alias', async () => {
+      const { controller, pageRepo, shareAliasService } = makeController();
+      pageRepo.findById.mockResolvedValue({ id: 'p-1', workspaceId: 'ws-1' });
+      shareAliasService.getAliasForPage.mockResolvedValue(undefined);
+
+      const result = await controller.forPage(
+        { pageId: 'p-1' } as any,
+        user,
+        workspace,
+      );
+
+      expect(result).toBeNull();
+    });
+  });
+});

apps/server/src/core/share/share-alias.controller.ts

@@ -0,0 +1,139 @@
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  ForbiddenException,
+  HttpCode,
+  HttpStatus,
+  NotFoundException,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
+import { AuthUser } from '../../common/decorators/auth-user.decorator';
+import { AuthWorkspace } from '../../common/decorators/auth-workspace.decorator';
+import { User, Workspace } from '@docmost/db/types/entity.types';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { PageAccessService } from '../page/page-access/page-access.service';
+import { ShareService } from './share.service';
+import { ShareAliasService } from './share-alias.service';
+import {
+  RemoveShareAliasDto,
+  SetShareAliasDto,
+  ShareAliasAvailabilityDto,
+  ShareAliasForPageDto,
+} from './dto/share-alias.dto';
+
+/**
+ * Authenticated management of vanity `/l/:alias` links. The PUBLIC resolve path
+ * lives in `ShareAliasRedirectController` (`/l/:alias`); this controller only
+ * creates/retargets/removes/looks-up aliases for editors.
+ */
+@UseGuards(JwtAuthGuard)
+@Controller('share-aliases')
+export class ShareAliasController {
+  constructor(
+    private readonly shareAliasService: ShareAliasService,
+    private readonly shareService: ShareService,
+    private readonly pageRepo: PageRepo,
+    private readonly pageAccessService: PageAccessService,
+  ) {}
+
+  @HttpCode(HttpStatus.OK)
+  @Post('set')
+  async set(
+    @Body() dto: SetShareAliasDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const page = await this.pageRepo.findById(dto.pageId);
+    if (!page || page.workspaceId !== workspace.id) {
+      throw new NotFoundException('Page not found');
+    }
+
+    // Editing the page is required to point an address at it.
+    await this.pageAccessService.validateCanEdit(page, user);
+
+    // The page must currently be publicly readable through the share graph; an
+    // alias to a non-shared page would only ever 404.
+    const resolved = await this.shareService.resolveReadableSharePage(
+      undefined,
+      page.id,
+      workspace.id,
+    );
+    if (!resolved) {
+      throw new BadRequestException('Page is not publicly shared');
+    }
+
+    const sharingAllowed = await this.shareService.isSharingAllowed(
+      workspace.id,
+      resolved.share.spaceId,
+    );
+    if (!sharingAllowed) {
+      throw new ForbiddenException('Public sharing is disabled');
+    }
+
+    return this.shareAliasService.setAlias({
+      workspaceId: workspace.id,
+      pageId: page.id,
+      creatorId: user.id,
+      alias: dto.alias,
+      confirmReassign: dto.confirmReassign,
+    });
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @Post('remove')
+  async remove(
+    @Body() dto: RemoveShareAliasDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const alias = await this.shareAliasService.getAliasById(
+      dto.aliasId,
+      workspace.id,
+    );
+    if (!alias) {
+      throw new NotFoundException('Alias not found');
+    }
+
+    // Only someone who can edit the (current) target page may free the address.
+    // A dangling alias (page deleted) can be removed by any workspace member.
+    if (alias.pageId) {
+      const page = await this.pageRepo.findById(alias.pageId);
+      if (page) {
+        await this.pageAccessService.validateCanEdit(page, user);
+      }
+    }
+
+    await this.shareAliasService.removeAlias(alias.id, workspace.id);
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @Post('availability')
+  async availability(
+    @Body() dto: ShareAliasAvailabilityDto,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    return this.shareAliasService.checkAvailability(dto.alias, workspace.id);
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @Post('for-page')
+  async forPage(
+    @Body() dto: ShareAliasForPageDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const page = await this.pageRepo.findById(dto.pageId);
+    if (!page || page.workspaceId !== workspace.id) {
+      throw new NotFoundException('Page not found');
+    }
+    await this.pageAccessService.validateCanView(page, user);
+
+    return (
+      (await this.shareAliasService.getAliasForPage(page.id, workspace.id)) ??
+      null
+    );
+  }
+}

apps/server/src/core/share/share-alias.service.spec.ts

@@ -0,0 +1,252 @@
+import { BadRequestException, ConflictException } from '@nestjs/common';
+import { ShareAliasService } from './share-alias.service';
+
+/**
+ * Behaviour tests for the alias write/resolve semantics: create vs no-op vs the
+ * 409 reassign guard, uniqueness-race handling, availability probe, and the
+ * request-time readable-target resolution (which re-runs the share boundary).
+ */
+describe('ShareAliasService', () => {
+  function makeService() {
+    const shareAliasRepo = {
+      findByAliasAndWorkspace: jest.fn(),
+      findByPageId: jest.fn(),
+      findById: jest.fn(),
+      insert: jest.fn(),
+      updatePageId: jest.fn(),
+      delete: jest.fn(),
+    };
+    const pageRepo = { findById: jest.fn() };
+    const shareService = {
+      resolveReadableSharePage: jest.fn(),
+      isSharingAllowed: jest.fn(),
+    };
+    const service = new ShareAliasService(
+      shareAliasRepo as any,
+      pageRepo as any,
+      shareService as any,
+    );
+    return { service, shareAliasRepo, pageRepo, shareService };
+  }
+
+  describe('setAlias', () => {
+    it('rejects an invalid alias before touching the db', async () => {
+      const { service, shareAliasRepo } = makeService();
+      await expect(
+        service.setAlias({
+          workspaceId: 'ws-1',
+          pageId: 'p-1',
+          creatorId: 'u-1',
+          alias: 'A', // too short + uppercase
+        }),
+      ).rejects.toBeInstanceOf(BadRequestException);
+      expect(shareAliasRepo.findByAliasAndWorkspace).not.toHaveBeenCalled();
+    });
+
+    it('normalizes then inserts a brand-new alias', async () => {
+      const { service, shareAliasRepo } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
+      shareAliasRepo.insert.mockResolvedValue({ id: 'a-1', alias: 'my-page' });
+
+      const res = await service.setAlias({
+        workspaceId: 'ws-1',
+        pageId: 'p-1',
+        creatorId: 'u-1',
+        alias: '  My Page ',
+      });
+
+      expect(shareAliasRepo.findByAliasAndWorkspace).toHaveBeenCalledWith(
+        'my-page',
+        'ws-1',
+      );
+      expect(shareAliasRepo.insert).toHaveBeenCalledWith({
+        workspaceId: 'ws-1',
+        alias: 'my-page',
+        pageId: 'p-1',
+        creatorId: 'u-1',
+      });
+      expect(res).toMatchObject({ id: 'a-1' });
+    });
+
+    it('is a no-op when the alias already points at the same page', async () => {
+      const { service, shareAliasRepo } = makeService();
+      const existing = { id: 'a-1', alias: 'foo', pageId: 'p-1' };
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(existing);
+
+      const res = await service.setAlias({
+        workspaceId: 'ws-1',
+        pageId: 'p-1',
+        creatorId: 'u-1',
+        alias: 'foo',
+      });
+
+      expect(res).toBe(existing);
+      expect(shareAliasRepo.insert).not.toHaveBeenCalled();
+      expect(shareAliasRepo.updatePageId).not.toHaveBeenCalled();
+    });
+
+    it('throws 409 with current target when name is taken and not confirmed', async () => {
+      const { service, shareAliasRepo, pageRepo } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
+        id: 'a-1',
+        alias: 'foo',
+        pageId: 'p-other',
+      });
+      pageRepo.findById.mockResolvedValue({ id: 'p-other', title: 'Other' });
+
+      try {
+        await service.setAlias({
+          workspaceId: 'ws-1',
+          pageId: 'p-1',
+          creatorId: 'u-1',
+          alias: 'foo',
+        });
+        fail('expected ConflictException');
+      } catch (err) {
+        expect(err).toBeInstanceOf(ConflictException);
+        expect((err as ConflictException).getResponse()).toMatchObject({
+          code: 'ALIAS_REASSIGN_REQUIRED',
+          currentPageId: 'p-other',
+          currentPageTitle: 'Other',
+        });
+      }
+      expect(shareAliasRepo.updatePageId).not.toHaveBeenCalled();
+    });
+
+    it('retargets (UPDATE page_id) when confirmReassign is set', async () => {
+      const { service, shareAliasRepo } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
+        id: 'a-1',
+        alias: 'foo',
+        pageId: 'p-other',
+      });
+      shareAliasRepo.updatePageId.mockResolvedValue({ id: 'a-1', pageId: 'p-1' });
+
+      const res = await service.setAlias({
+        workspaceId: 'ws-1',
+        pageId: 'p-1',
+        creatorId: 'u-1',
+        alias: 'foo',
+        confirmReassign: true,
+      });
+
+      expect(shareAliasRepo.updatePageId).toHaveBeenCalledWith(
+        'a-1',
+        'p-1',
+        'ws-1',
+      );
+      expect(res).toMatchObject({ pageId: 'p-1' });
+    });
+
+    it('maps a unique-violation race to 409', async () => {
+      const { service, shareAliasRepo } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
+      shareAliasRepo.insert.mockRejectedValue({ code: '23505' });
+
+      await expect(
+        service.setAlias({
+          workspaceId: 'ws-1',
+          pageId: 'p-1',
+          creatorId: 'u-1',
+          alias: 'foo',
+        }),
+      ).rejects.toBeInstanceOf(ConflictException);
+    });
+  });
+
+  describe('checkAvailability', () => {
+    it('reports invalid for a bad slug without a db hit', async () => {
+      const { service, shareAliasRepo } = makeService();
+      const res = await service.checkAvailability('Bad Slug!', 'ws-1');
+      expect(res).toMatchObject({ valid: false, available: false });
+      expect(shareAliasRepo.findByAliasAndWorkspace).not.toHaveBeenCalled();
+    });
+
+    it('reports available when no row exists', async () => {
+      const { service, shareAliasRepo } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
+      const res = await service.checkAvailability('free-name', 'ws-1');
+      expect(res).toMatchObject({
+        alias: 'free-name',
+        valid: true,
+        available: true,
+        currentPageId: null,
+      });
+    });
+
+    it('reports taken with the current target page', async () => {
+      const { service, shareAliasRepo } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
+        id: 'a-1',
+        pageId: 'p-9',
+      });
+      const res = await service.checkAvailability('taken', 'ws-1');
+      expect(res).toMatchObject({ available: false, currentPageId: 'p-9' });
+    });
+  });
+
+  describe('resolveReadableTarget', () => {
+    it('returns null for an invalid alias', async () => {
+      const { service } = makeService();
+      expect(await service.resolveReadableTarget('!!', 'ws-1')).toBeNull();
+    });
+
+    it('returns null for an unknown or dangling alias', async () => {
+      const { service, shareAliasRepo } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValueOnce(undefined);
+      expect(await service.resolveReadableTarget('foo', 'ws-1')).toBeNull();
+
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValueOnce({
+        id: 'a-1',
+        pageId: null,
+      });
+      expect(await service.resolveReadableTarget('foo', 'ws-1')).toBeNull();
+    });
+
+    it('returns null when the page is no longer publicly readable', async () => {
+      const { service, shareAliasRepo, shareService } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
+        id: 'a-1',
+        pageId: 'p-1',
+      });
+      shareService.resolveReadableSharePage.mockResolvedValue(null);
+      expect(await service.resolveReadableTarget('foo', 'ws-1')).toBeNull();
+    });
+
+    it('returns null when sharing is disabled for the space', async () => {
+      const { service, shareAliasRepo, shareService } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
+        id: 'a-1',
+        pageId: 'p-1',
+      });
+      shareService.resolveReadableSharePage.mockResolvedValue({
+        share: { key: 'k', spaceId: 's-1' },
+        page: { slugId: 'sid', title: 'T' },
+      });
+      shareService.isSharingAllowed.mockResolvedValue(false);
+      expect(await service.resolveReadableTarget('foo', 'ws-1')).toBeNull();
+    });
+
+    it('returns the resolved share+page on success', async () => {
+      const { service, shareAliasRepo, shareService } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
+        id: 'a-1',
+        pageId: 'p-1',
+      });
+      const resolved = {
+        share: { key: 'k', spaceId: 's-1' },
+        page: { slugId: 'sid', title: 'T' },
+      };
+      shareService.resolveReadableSharePage.mockResolvedValue(resolved);
+      shareService.isSharingAllowed.mockResolvedValue(true);
+
+      const res = await service.resolveReadableTarget('FOO', 'ws-1');
+      expect(res).toBe(resolved);
+      // alias was normalized to lowercase before lookup
+      expect(shareAliasRepo.findByAliasAndWorkspace).toHaveBeenCalledWith(
+        'foo',
+        'ws-1',
+      );
+    });
+  });
+});

apps/server/src/core/share/share-alias.service.ts

@@ -0,0 +1,187 @@
+import {
+  BadRequestException,
+  ConflictException,
+  Injectable,
+  Logger,
+} from '@nestjs/common';
+import { ShareAliasRepo } from '@docmost/db/repos/share-alias/share-alias.repo';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { ShareService } from './share.service';
+import { Page, ShareAlias } from '@docmost/db/types/entity.types';
+import { isValidShareAlias, normalizeShareAlias } from './share-alias.util';
+
+/** Postgres unique_violation; the (workspace_id, alias) constraint races here. */
+const PG_UNIQUE_VIOLATION = '23505';
+
+export interface ResolvedAliasTarget {
+  share: NonNullable<
+    Awaited<ReturnType<ShareService['resolveReadableSharePage']>>
+  >['share'];
+  page: Page;
+}
+
+@Injectable()
+export class ShareAliasService {
+  private readonly logger = new Logger(ShareAliasService.name);
+
+  constructor(
+    private readonly shareAliasRepo: ShareAliasRepo,
+    private readonly pageRepo: PageRepo,
+    private readonly shareService: ShareService,
+  ) {}
+
+  /**
+   * Create or retarget a vanity alias. The alias is workspace-scoped:
+   *   - no row for this name        -> INSERT a new pointer
+   *   - row already points at pageId -> no-op (idempotent)
+   *   - row points elsewhere         -> the "swap". Without confirmReassign we
+   *     throw 409 carrying the current target so the client can confirm; with
+   *     it we UPDATE the single row's page_id (every /l/<alias> link follows the
+   *     302 to the new page instantly — no stale 301 cache).
+   *
+   * Caller is responsible for authorizing the page (edit rights + public
+   * readability); this method owns only the alias-name semantics.
+   */
+  async setAlias(opts: {
+    workspaceId: string;
+    pageId: string;
+    creatorId: string;
+    alias: string;
+    confirmReassign?: boolean;
+  }): Promise<ShareAlias> {
+    const { workspaceId, pageId, creatorId, confirmReassign } = opts;
+    const alias = normalizeShareAlias(opts.alias);
+    if (!isValidShareAlias(alias)) {
+      throw new BadRequestException(
+        'Invalid alias. Use 2-60 lowercase letters, digits and hyphens.',
+      );
+    }
+
+    const existing = await this.shareAliasRepo.findByAliasAndWorkspace(
+      alias,
+      workspaceId,
+    );
+
+    if (!existing) {
+      try {
+        return await this.shareAliasRepo.insert({
+          workspaceId,
+          alias,
+          pageId,
+          creatorId,
+        });
+      } catch (err: any) {
+        // Lost a uniqueness race: another request claimed the name first.
+        if (err?.code === PG_UNIQUE_VIOLATION) {
+          throw new ConflictException({ message: 'Alias already taken' });
+        }
+        this.logger.error(err);
+        throw new BadRequestException('Failed to set alias');
+      }
+    }
+
+    // Already points at this page -> nothing to do.
+    if (existing.pageId === pageId) {
+      return existing;
+    }
+
+    // Name occupied by a different (or dangling) target: require confirmation.
+    if (!confirmReassign) {
+      const currentPage = existing.pageId
+        ? await this.pageRepo.findById(existing.pageId)
+        : null;
+      throw new ConflictException({
+        message: 'Alias already in use',
+        code: 'ALIAS_REASSIGN_REQUIRED',
+        currentPageId: existing.pageId,
+        currentPageTitle: currentPage?.title ?? null,
+      });
+    }
+
+    return this.shareAliasRepo.updatePageId(existing.id, pageId, workspaceId);
+  }
+
+  /** Free a vanity name (no history kept). */
+  async removeAlias(aliasId: string, workspaceId: string): Promise<void> {
+    await this.shareAliasRepo.delete(aliasId, workspaceId);
+  }
+
+  /** Debounced availability probe for the modal. */
+  async checkAvailability(
+    rawAlias: string,
+    workspaceId: string,
+  ): Promise<{
+    alias: string;
+    valid: boolean;
+    available: boolean;
+    currentPageId: string | null;
+  }> {
+    const alias = normalizeShareAlias(rawAlias);
+    if (!isValidShareAlias(alias)) {
+      return { alias, valid: false, available: false, currentPageId: null };
+    }
+    const existing = await this.shareAliasRepo.findByAliasAndWorkspace(
+      alias,
+      workspaceId,
+    );
+    return {
+      alias,
+      valid: true,
+      available: !existing,
+      currentPageId: existing?.pageId ?? null,
+    };
+  }
+
+  /** A single alias row scoped to the workspace, or undefined. */
+  getAliasById(
+    aliasId: string,
+    workspaceId: string,
+  ): Promise<ShareAlias | undefined> {
+    return this.shareAliasRepo.findById(aliasId, workspaceId);
+  }
+
+  /** The alias currently targeting a page (modal display), or undefined. */
+  getAliasForPage(
+    pageId: string,
+    workspaceId: string,
+  ): Promise<ShareAlias | undefined> {
+    return this.shareAliasRepo.findByPageId(pageId, workspaceId);
+  }
+
+  /**
+   * Resolve a vanity alias to the canonical, publicly-READABLE share page, or
+   * null. This re-runs the authoritative share boundary at request time (so a
+   * later-unshared / restricted / sharing-disabled target collapses to null and
+   * the caller serves the generic SPA 404 — no existence leak). The alias row
+   * itself is just a pointer; this is where access is actually decided.
+   */
+  async resolveReadableTarget(
+    rawAlias: string,
+    workspaceId: string,
+  ): Promise<ResolvedAliasTarget | null> {
+    const alias = normalizeShareAlias(rawAlias);
+    if (!isValidShareAlias(alias)) return null;
+
+    const aliasRow = await this.shareAliasRepo.findByAliasAndWorkspace(
+      alias,
+      workspaceId,
+    );
+    // Unknown name or a dangling alias (target page deleted) -> not resolvable.
+    if (!aliasRow?.pageId) return null;
+
+    const resolved = await this.shareService.resolveReadableSharePage(
+      undefined,
+      aliasRow.pageId,
+      workspaceId,
+    );
+    if (!resolved) return null;
+
+    const sharingAllowed = await this.shareService.isSharingAllowed(
+      workspaceId,
+      resolved.share.spaceId,
+    );
+    if (!sharingAllowed) return null;
+
+    return resolved;
+  }
+}

apps/server/src/core/share/share-alias.util.spec.ts

@@ -0,0 +1,60 @@
+import { isValidShareAlias, normalizeShareAlias } from './share-alias.util';
+
+describe('normalizeShareAlias', () => {
+  it('lowercases and trims', () => {
+    expect(normalizeShareAlias('  HelloWorld  ')).toBe('helloworld');
+  });
+
+  it('converts spaces and underscores to single hyphens', () => {
+    expect(normalizeShareAlias('my cool   page')).toBe('my-cool-page');
+    expect(normalizeShareAlias('my_cool_page')).toBe('my-cool-page');
+  });
+
+  it('collapses repeated hyphens and trims edge hyphens', () => {
+    expect(normalizeShareAlias('--a---b--')).toBe('a-b');
+  });
+
+  it('handles null/undefined defensively', () => {
+    expect(normalizeShareAlias(undefined as unknown as string)).toBe('');
+  });
+});
+
+describe('isValidShareAlias', () => {
+  it('accepts ascii lowercase hyphen-separated slugs', () => {
+    expect(isValidShareAlias('hello')).toBe(true);
+    expect(isValidShareAlias('hello-world-2')).toBe(true);
+    expect(isValidShareAlias('a1')).toBe(true);
+  });
+
+  it('rejects too short / too long', () => {
+    expect(isValidShareAlias('a')).toBe(false);
+    expect(isValidShareAlias('a'.repeat(61))).toBe(false);
+    expect(isValidShareAlias('a'.repeat(60))).toBe(true);
+  });
+
+  it('rejects leading/trailing/double hyphens', () => {
+    expect(isValidShareAlias('-abc')).toBe(false);
+    expect(isValidShareAlias('abc-')).toBe(false);
+    expect(isValidShareAlias('a--b')).toBe(false);
+  });
+
+  it('rejects uppercase, cyrillic and other non-ascii', () => {
+    expect(isValidShareAlias('Hello')).toBe(false);
+    expect(isValidShareAlias('привет')).toBe(false);
+    expect(isValidShareAlias('a b')).toBe(false);
+    expect(isValidShareAlias('a_b')).toBe(false);
+    expect(isValidShareAlias('a.b')).toBe(false);
+  });
+
+  it('normalize + validate round-trips a messy input to a valid slug', () => {
+    const alias = normalizeShareAlias('  My  Cool_Page!! ');
+    // "!!" is not stripped by normalize (only case/separators), so the result
+    // still fails validation — the charset gate is intentionally separate.
+    expect(alias).toBe('my-cool-page!!');
+    expect(isValidShareAlias(alias)).toBe(false);
+
+    const ok = normalizeShareAlias('  My  Cool Page ');
+    expect(ok).toBe('my-cool-page');
+    expect(isValidShareAlias(ok)).toBe(true);
+  });
+});

apps/server/src/core/share/share-alias.util.ts

@@ -0,0 +1,30 @@
+/**
+ * Vanity share-alias helpers shared by the write path (set/availability) and the
+ * `/l/:alias` resolve path. Aliases are ASCII-only, lowercase, hyphen-separated
+ * slugs — deliberately no Cyrillic / transliteration: the user types the exact
+ * canonical form. Keep this in sync with the client copy in
+ * `apps/client/src/features/share/share-alias.util.ts`.
+ */
+
+// Normalize a user-provided vanity alias into canonical ASCII storage form.
+// This only canonicalizes shape (case, separators); it does NOT enforce the
+// charset — call isValidShareAlias afterwards to reject anything illegal.
+export function normalizeShareAlias(raw: string): string {
+  return (raw ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-') // spaces/underscores -> single hyphen
+    .replace(/-{2,}/g, '-') // collapse repeated hyphens
+    .replace(/^-+|-+$/g, ''); // trim leading/trailing hyphens
+}
+
+// ASCII only: lowercase letters/digits in hyphen-separated groups, length 2..60.
+const ALIAS_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function isValidShareAlias(alias: string): boolean {
+  return (
+    typeof alias === 'string' &&
+    alias.length >= 2 &&
+    alias.length <= 60 &&
+    ALIAS_RE.test(alias)
+  );
+}

apps/server/src/core/share/share.module.ts

@@ -5,13 +5,22 @@ import { TokenModule } from '../auth/token.module';
 import { ShareSeoController } from './share-seo.controller';
 import { TransclusionModule } from '../page/transclusion/transclusion.module';
 import { AiModule } from '../../integrations/ai/ai.module';
+import { ShareAliasService } from './share-alias.service';
+import { ShareAliasController } from './share-alias.controller';
+import { ShareAliasRedirectController } from './share-alias-redirect.controller';
 
 @Module({
   // AiModule (AiSettingsService) is used by the page-info route to surface
   // whether the anonymous public-share assistant is enabled for the workspace.
   imports: [TokenModule, TransclusionModule, AiModule],
-  controllers: [ShareController, ShareSeoController],
-  providers: [ShareService],
-  exports: [ShareService],
+  controllers: [
+    ShareController,
+    ShareSeoController,
+    // Vanity /l/:alias: authenticated management + public 302 resolver.
+    ShareAliasController,
+    ShareAliasRedirectController,
+  ],
+  providers: [ShareService, ShareAliasService],
+  exports: [ShareService, ShareAliasService],
 })
 export class ShareModule {}

apps/server/src/database/database.module.ts

@@ -23,6 +23,7 @@ import { UserTokenRepo } from './repos/user-token/user-token.repo';
 import { UserSessionRepo } from '@docmost/db/repos/session/user-session.repo';
 import { BacklinkRepo } from '@docmost/db/repos/backlink/backlink.repo';
 import { ShareRepo } from '@docmost/db/repos/share/share.repo';
+import { ShareAliasRepo } from '@docmost/db/repos/share-alias/share-alias.repo';
 import { NotificationRepo } from '@docmost/db/repos/notification/notification.repo';
 import { WatcherRepo } from '@docmost/db/repos/watcher/watcher.repo';
 import { LabelRepo } from '@docmost/db/repos/label/label.repo';
@@ -96,6 +97,7 @@ import { normalizePostgresUrl } from '../common/helpers';
     UserSessionRepo,
     BacklinkRepo,
     ShareRepo,
+    ShareAliasRepo,
     NotificationRepo,
     WatcherRepo,
     LabelRepo,
@@ -128,6 +130,7 @@ import { normalizePostgresUrl } from '../common/helpers';
     UserSessionRepo,
     BacklinkRepo,
     ShareRepo,
+    ShareAliasRepo,
     NotificationRepo,
     WatcherRepo,
     LabelRepo,

apps/server/src/database/migrations/20260626T130000-share-aliases.ts

@@ -0,0 +1,54 @@
+import { type Kysely, sql } from 'kysely';
+
+/**
+ * Vanity share aliases: a retargetable, human-readable pointer (`/l/<alias>`)
+ * that lives independently of any single `shares` row. The alias belongs to the
+ * WORKSPACE (stable address), and `page_id` is nullable with ON DELETE SET NULL
+ * so the address survives deletion of its current target (it 404s until
+ * retargeted) rather than disappearing with the page.
+ */
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('share_aliases')
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
+    )
+    .addColumn('workspace_id', 'uuid', (col) =>
+      col.references('workspaces.id').onDelete('cascade').notNull(),
+    )
+    // Normalized ASCII, lowercase. Uniqueness is enforced per-workspace below.
+    .addColumn('alias', 'varchar', (col) => col.notNull())
+    // Nullable + SET NULL: the address outlives its target page.
+    .addColumn('page_id', 'uuid', (col) =>
+      col.references('pages.id').onDelete('set null'),
+    )
+    .addColumn('creator_id', 'uuid', (col) =>
+      col.references('users.id').onDelete('set null'),
+    )
+    .addColumn('created_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addColumn('updated_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .execute();
+
+  // The vanity name is unique within a workspace (mirrors shares.key scoping).
+  await db.schema
+    .createIndex('share_aliases_workspace_id_alias_unique')
+    .on('share_aliases')
+    .columns(['workspace_id', 'alias'])
+    .unique()
+    .execute();
+
+  // "Which alias targets this page?" lookup for the share modal.
+  await db.schema
+    .createIndex('share_aliases_page_id_idx')
+    .on('share_aliases')
+    .column('page_id')
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('share_aliases').execute();
+}

apps/server/src/database/repos/share-alias/share-alias.repo.spec.ts

@@ -0,0 +1,120 @@
+import { ShareAliasRepo } from './share-alias.repo';
+import type { KyselyDB } from '../../types/kysely.types';
+
+/**
+ * SQL-shape unit tests for ShareAliasRepo. A live Postgres is out of scope;
+ * instead we spy on the Kysely builder to assert each method pins the
+ * workspace scope (so a name in one workspace can never resolve another's
+ * page) and threads the right columns.
+ */
+describe('ShareAliasRepo', () => {
+  function makeSelectRepo(result: unknown) {
+    const where = jest.fn();
+    const builder: any = {
+      select: jest.fn(() => builder),
+      where: jest.fn((...args: unknown[]) => {
+        where(...args);
+        return builder;
+      }),
+      executeTakeFirst: jest.fn().mockResolvedValue(result),
+    };
+    const db = { selectFrom: jest.fn(() => builder) } as unknown as KyselyDB;
+    return { repo: new ShareAliasRepo(db), db, where, builder };
+  }
+
+  it('findByAliasAndWorkspace scopes by alias AND workspace', async () => {
+    const row = { id: 'a-1', alias: 'foo', workspaceId: 'ws-1' };
+    const { repo, db, where } = makeSelectRepo(row);
+
+    const res = await repo.findByAliasAndWorkspace('foo', 'ws-1');
+
+    expect(res).toBe(row);
+    expect(db.selectFrom).toHaveBeenCalledWith('shareAliases');
+    expect(where).toHaveBeenCalledWith('alias', '=', 'foo');
+    expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
+  });
+
+  it('findByPageId scopes by page AND workspace', async () => {
+    const { repo, where } = makeSelectRepo(undefined);
+    await repo.findByPageId('p-1', 'ws-1');
+    expect(where).toHaveBeenCalledWith('pageId', '=', 'p-1');
+    expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
+  });
+
+  it('insert writes the provided columns and returns the row', async () => {
+    const values = jest.fn();
+    const inserted = { id: 'a-1' };
+    const builder: any = {
+      values: jest.fn((v: unknown) => {
+        values(v);
+        return builder;
+      }),
+      returning: jest.fn(() => builder),
+      executeTakeFirst: jest.fn().mockResolvedValue(inserted),
+    };
+    const db = { insertInto: jest.fn(() => builder) } as unknown as KyselyDB;
+    const repo = new ShareAliasRepo(db);
+
+    const res = await repo.insert({
+      workspaceId: 'ws-1',
+      alias: 'foo',
+      pageId: 'p-1',
+      creatorId: 'u-1',
+    });
+
+    expect(db.insertInto).toHaveBeenCalledWith('shareAliases');
+    expect(values).toHaveBeenCalledWith({
+      workspaceId: 'ws-1',
+      alias: 'foo',
+      pageId: 'p-1',
+      creatorId: 'u-1',
+    });
+    expect(res).toBe(inserted);
+  });
+
+  it('updatePageId retargets a single row scoped by id + workspace', async () => {
+    const set = jest.fn();
+    const where = jest.fn();
+    const builder: any = {
+      set: jest.fn((s: unknown) => {
+        set(s);
+        return builder;
+      }),
+      where: jest.fn((...args: unknown[]) => {
+        where(...args);
+        return builder;
+      }),
+      returning: jest.fn(() => builder),
+      executeTakeFirst: jest.fn().mockResolvedValue({ id: 'a-1' }),
+    };
+    const db = { updateTable: jest.fn(() => builder) } as unknown as KyselyDB;
+    const repo = new ShareAliasRepo(db);
+
+    await repo.updatePageId('a-1', 'p-2', 'ws-1');
+
+    expect(db.updateTable).toHaveBeenCalledWith('shareAliases');
+    expect(set.mock.calls[0][0].pageId).toBe('p-2');
+    expect(set.mock.calls[0][0].updatedAt).toBeInstanceOf(Date);
+    expect(where).toHaveBeenCalledWith('id', '=', 'a-1');
+    expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
+  });
+
+  it('delete scopes by id + workspace', async () => {
+    const where = jest.fn();
+    const builder: any = {
+      where: jest.fn((...args: unknown[]) => {
+        where(...args);
+        return builder;
+      }),
+      execute: jest.fn().mockResolvedValue(undefined),
+    };
+    const db = { deleteFrom: jest.fn(() => builder) } as unknown as KyselyDB;
+    const repo = new ShareAliasRepo(db);
+
+    await repo.delete('a-1', 'ws-1');
+
+    expect(db.deleteFrom).toHaveBeenCalledWith('shareAliases');
+    expect(where).toHaveBeenCalledWith('id', '=', 'a-1');
+    expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
+  });
+});

apps/server/src/database/repos/share-alias/share-alias.repo.ts

@@ -0,0 +1,109 @@
+import { Injectable } from '@nestjs/common';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
+import { dbOrTx } from '../../utils';
+import {
+  InsertableShareAlias,
+  ShareAlias,
+} from '@docmost/db/types/entity.types';
+
+/**
+ * Repository for vanity share aliases (`/l/:alias`). An alias is a long-lived,
+ * workspace-scoped pointer to a page; retargeting is a single UPDATE of
+ * `page_id`. All lookups are workspace-scoped so a name in one workspace can
+ * never resolve a page in another.
+ */
+@Injectable()
+export class ShareAliasRepo {
+  constructor(@InjectKysely() private readonly db: KyselyDB) {}
+
+  private baseFields: Array<keyof ShareAlias> = [
+    'id',
+    'workspaceId',
+    'alias',
+    'pageId',
+    'creatorId',
+    'createdAt',
+    'updatedAt',
+  ];
+
+  /** Resolve a (normalized) alias within a workspace, or undefined. */
+  async findByAliasAndWorkspace(
+    alias: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<ShareAlias | undefined> {
+    return dbOrTx(this.db, trx)
+      .selectFrom('shareAliases')
+      .select(this.baseFields)
+      .where('alias', '=', alias)
+      .where('workspaceId', '=', workspaceId)
+      .executeTakeFirst();
+  }
+
+  /** The alias currently pointing at a page (for the share modal). */
+  async findByPageId(
+    pageId: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<ShareAlias | undefined> {
+    return dbOrTx(this.db, trx)
+      .selectFrom('shareAliases')
+      .select(this.baseFields)
+      .where('pageId', '=', pageId)
+      .where('workspaceId', '=', workspaceId)
+      .executeTakeFirst();
+  }
+
+  async findById(
+    id: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<ShareAlias | undefined> {
+    return dbOrTx(this.db, trx)
+      .selectFrom('shareAliases')
+      .select(this.baseFields)
+      .where('id', '=', id)
+      .where('workspaceId', '=', workspaceId)
+      .executeTakeFirst();
+  }
+
+  async insert(
+    insertable: InsertableShareAlias,
+    trx?: KyselyTransaction,
+  ): Promise<ShareAlias> {
+    return dbOrTx(this.db, trx)
+      .insertInto('shareAliases')
+      .values(insertable)
+      .returning(this.baseFields)
+      .executeTakeFirst();
+  }
+
+  /** Retarget an existing alias to a new page (the "swap" operation). */
+  async updatePageId(
+    id: string,
+    pageId: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<ShareAlias> {
+    return dbOrTx(this.db, trx)
+      .updateTable('shareAliases')
+      .set({ pageId, updatedAt: new Date() })
+      .where('id', '=', id)
+      .where('workspaceId', '=', workspaceId)
+      .returning(this.baseFields)
+      .executeTakeFirst();
+  }
+
+  async delete(
+    id: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    await dbOrTx(this.db, trx)
+      .deleteFrom('shareAliases')
+      .where('id', '=', id)
+      .where('workspaceId', '=', workspaceId)
+      .execute();
+  }
+}

apps/server/src/database/repos/workspace/workspace.repo.ts

@@ -20,6 +20,7 @@ import { DB, Workspaces } from '@docmost/db/types/db';
 export const AI_PROVIDER_SETTINGS_ALLOWED: readonly string[] = [
   'driver',
   'chatModel',
+  'chatContextWindow',
   'chatApiStyle',
   'embeddingModel',
   'baseUrl',

apps/server/src/database/share-aliases.migration.spec.ts

@@ -0,0 +1,94 @@
+import * as migration from './migrations/20260626T130000-share-aliases';
+import type {
+  InsertableShareAlias,
+  ShareAlias,
+  UpdatableShareAlias,
+} from './types/entity.types';
+
+/**
+ * Sanity checks for the share_aliases migration + entity types. We don't run a
+ * live Postgres here (that's the integration suite); instead we assert the
+ * migration exposes the expected up/down contract and creates the table with
+ * the unique (workspace_id, alias) constraint and the page_id index, and that
+ * the generated entity types line up with the column set.
+ */
+describe('share-aliases migration', () => {
+  it('up creates the table, the unique index and the page_id index', async () => {
+    const calls: string[] = [];
+
+    const tableBuilder: any = new Proxy(
+      {},
+      {
+        get(_t, prop: string) {
+          if (prop === 'execute') return async () => undefined;
+          // addColumn/addConstraint/etc. are chainable no-ops.
+          return () => tableBuilder;
+        },
+      },
+    );
+
+    const indexBuilder: any = new Proxy(
+      {},
+      {
+        get(_t, prop: string) {
+          if (prop === 'execute') return async () => undefined;
+          return () => indexBuilder;
+        },
+      },
+    );
+
+    const schema = {
+      createTable: (name: string) => {
+        calls.push(`createTable:${name}`);
+        return tableBuilder;
+      },
+      createIndex: (name: string) => {
+        calls.push(`createIndex:${name}`);
+        return indexBuilder;
+      },
+    };
+
+    await migration.up({ schema } as any);
+
+    expect(calls).toContain('createTable:share_aliases');
+    expect(calls).toContain(
+      'createIndex:share_aliases_workspace_id_alias_unique',
+    );
+    expect(calls).toContain('createIndex:share_aliases_page_id_idx');
+  });
+
+  it('down drops the table', async () => {
+    const calls: string[] = [];
+    const dropBuilder: any = { execute: async () => undefined };
+    const schema = {
+      dropTable: (name: string) => {
+        calls.push(`dropTable:${name}`);
+        return dropBuilder;
+      },
+    };
+    await migration.down({ schema } as any);
+    expect(calls).toContain('dropTable:share_aliases');
+  });
+
+  it('entity types expose the alias columns', () => {
+    // Compile-time only: these typed declarations fail `tsc` if the entity types
+    // drift (missing/renamed columns, wrong nullability). The runtime assertions
+    // would be tautological, so the value is purely in the type-check.
+    const row: ShareAlias = {
+      id: 'a-1',
+      workspaceId: 'ws-1',
+      alias: 'foo',
+      pageId: 'p-1',
+      creatorId: 'u-1',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+    const insert: InsertableShareAlias = {
+      workspaceId: 'ws-1',
+      alias: 'foo',
+    };
+    const update: UpdatableShareAlias = { pageId: null };
+
+    expect([row, insert, update]).toHaveLength(3);
+  });
+});

apps/server/src/database/types/db.d.ts

@@ -305,6 +305,16 @@ export interface Pages {
   ydoc: Buffer | null;
 }
 
+export interface ShareAliases {
+  alias: string;
+  createdAt: Generated<Timestamp>;
+  creatorId: string | null;
+  id: Generated<string>;
+  pageId: string | null;
+  updatedAt: Generated<Timestamp>;
+  workspaceId: string;
+}
+
 export interface Shares {
   createdAt: Generated<Timestamp>;
   creatorId: string | null;
@@ -674,6 +684,7 @@ export interface DB {
   pageVerifiers: PageVerifiers;
   pages: Pages;
   scimTokens: ScimTokens;
+  shareAliases: ShareAliases;
   shares: Shares;
   spaceMembers: SpaceMembers;
   spaces: Spaces;

apps/server/src/database/types/entity.types.ts

@@ -30,6 +30,7 @@ import {
   AuthProviders,
   AuthAccounts,
   Shares,
+  ShareAliases,
   Favorites,
   FileTasks,
   UserMfa as _UserMFA,
@@ -172,6 +173,11 @@ export type Share = Selectable<Shares>;
 export type InsertableShare = Insertable<Shares>;
 export type UpdatableShare = Updateable<Omit<Shares, 'id'>>;
 
+// Share alias (vanity /l/:alias pointer)
+export type ShareAlias = Selectable<ShareAliases>;
+export type InsertableShareAlias = Insertable<ShareAliases>;
+export type UpdatableShareAlias = Updateable<Omit<ShareAliases, 'id'>>;
+
 // Favorite
 export type Favorite = Selectable<Favorites>;
 export type InsertableFavorite = Insertable<Favorites>;

apps/server/src/integrations/ai/ai-provider-settings-keys.spec.ts

@@ -41,3 +41,35 @@ describe('UpdateAiSettingsDto.chatApiStyle', () => {
     expect(errs.find((e) => e.property === 'chatApiStyle')).toBeUndefined();
   });
 });
+
+/** DTO validation for the new chatContextWindow field (@IsInt @Min(0)). */
+describe('UpdateAiSettingsDto.chatContextWindow', () => {
+  const errorsFor = async (chatContextWindow: unknown) =>
+    validate(plainToInstance(UpdateAiSettingsDto, { chatContextWindow }));
+
+  it('accepts a non-negative integer (incl. 0 = clear the limit)', async () => {
+    for (const v of [0, 200000]) {
+      const errs = await errorsFor(v);
+      expect(
+        errs.find((e) => e.property === 'chatContextWindow'),
+      ).toBeUndefined();
+    }
+  });
+
+  it('rejects a negative value', async () => {
+    const errs = await errorsFor(-1);
+    expect(errs.find((e) => e.property === 'chatContextWindow')).toBeDefined();
+  });
+
+  it('rejects a non-integer value', async () => {
+    const errs = await errorsFor(1.5);
+    expect(errs.find((e) => e.property === 'chatContextWindow')).toBeDefined();
+  });
+
+  it('accepts the field being omitted (optional)', async () => {
+    const errs = await validate(plainToInstance(UpdateAiSettingsDto, {}));
+    expect(
+      errs.find((e) => e.property === 'chatContextWindow'),
+    ).toBeUndefined();
+  });
+});

apps/server/src/integrations/ai/ai-settings.service.spec.ts

@@ -0,0 +1,43 @@
+import { parsePositiveInt } from './ai-settings.service';
+
+/**
+ * Round-trip coercion for numeric `::text` provider settings (e.g.
+ * chatContextWindow). Values are stored as text and read back as strings, so
+ * this guards the read path the DTO write-validation does not cover: a silent
+ * loss of `Math.floor` or a `> 0` → `>= 0` drift would otherwise go unnoticed.
+ */
+describe('parsePositiveInt', () => {
+  it('keeps a valid positive integer string', () => {
+    expect(parsePositiveInt('200000')).toBe(200000);
+  });
+
+  it('floors a fractional string', () => {
+    expect(parsePositiveInt('1.9')).toBe(1);
+    expect(parsePositiveInt('1.0')).toBe(1);
+  });
+
+  it('returns undefined for zero', () => {
+    expect(parsePositiveInt('0')).toBeUndefined();
+  });
+
+  it('returns undefined for a negative value', () => {
+    expect(parsePositiveInt('-5')).toBeUndefined();
+  });
+
+  it('returns undefined for an empty string', () => {
+    expect(parsePositiveInt('')).toBeUndefined();
+  });
+
+  it('returns undefined for a non-numeric string', () => {
+    expect(parsePositiveInt('abc')).toBeUndefined();
+  });
+
+  it('returns undefined for undefined / null', () => {
+    expect(parsePositiveInt(undefined)).toBeUndefined();
+    expect(parsePositiveInt(null)).toBeUndefined();
+  });
+
+  it('accepts a real number too (not only ::text strings)', () => {
+    expect(parsePositiveInt(42)).toBe(42);
+  });
+});

apps/server/src/integrations/ai/ai-settings.service.ts

@@ -18,6 +18,18 @@ import {
   PROVIDER_SETTINGS_KEYS,
 } from './ai.types';
 
+/**
+ * Coerce a raw provider value (stored as `::text`, so it arrives as a string —
+ * see workspace.repo.ts) into a positive integer, or `undefined` when it is not
+ * a finite number greater than zero. Used for numeric `::text` settings such as
+ * `chatContextWindow`. Fractions are floored: `"1.9" → 1`, `"0"`/`"-5"`/`""`/
+ * `"abc"`/`undefined` → `undefined`.
+ */
+export function parsePositiveInt(raw: unknown): number | undefined {
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+}
+
 /**
  * Shape of the partial update accepted by `update`. Mirrors the validated
  * controller DTO. `apiKey` / `embeddingApiKey` are write-only: undefined =
@@ -26,6 +38,8 @@ import {
 export interface UpdateAiSettingsInput {
   driver?: AiDriver;
   chatModel?: string;
+  // Max context window in tokens for the chat header badge. 0/empty = no limit.
+  chatContextWindow?: number;
   chatApiStyle?: ChatApiStyle;
   embeddingModel?: string;
   baseUrl?: string;
@@ -160,6 +174,9 @@ export class AiSettingsService {
     const config: ResolvedAiConfig = {
       driver: provider.driver,
       chatModel: provider.chatModel,
+      // Max context window for the chat header badge denominator. Stored as
+      // ::text; 0/unset/invalid = no limit (undefined).
+      chatContextWindow: parsePositiveInt(provider.chatContextWindow),
       // Plain passthrough; getChatModel defaults unset to 'openai-compatible'.
       chatApiStyle: provider.chatApiStyle,
       // Cheap model id for the anonymous public-share assistant; reuses the chat
@@ -219,6 +236,10 @@ export class AiSettingsService {
   async getMasked(workspaceId: string): Promise<MaskedAiSettings> {
     const provider = await this.readProvider(workspaceId);
 
+    // Stored as ::text; coerce to a positive integer (or undefined) so the
+    // client receives a real number.
+    const chatContextWindow = parsePositiveInt(provider.chatContextWindow);
+
     let hasApiKey = false;
     let hasEmbeddingApiKey = false;
     let hasSttApiKey = false;
@@ -243,6 +264,7 @@ export class AiSettingsService {
     return {
       driver: provider.driver,
       chatModel: provider.chatModel,
+      chatContextWindow,
       chatApiStyle: provider.chatApiStyle,
       embeddingModel: provider.embeddingModel,
       baseUrl: provider.baseUrl,

apps/server/src/integrations/ai/ai.types.ts

@@ -32,6 +32,9 @@ export const CHAT_API_STYLES: ChatApiStyle[] = ['openai-compatible', 'openai'];
 export interface AiProviderSettings {
   driver: AiDriver;
   chatModel: string;
+  // Max context window in tokens; surfaced to the chat header badge as the
+  // denominator ("current / max"). 0/unset = no limit (badge shows no denominator).
+  chatContextWindow?: number;
   // Chat provider implementation for the `openai` driver. Unset → defaults to
   // 'openai-compatible' (so reasoning is surfaced by default). See ChatApiStyle.
   chatApiStyle?: ChatApiStyle;
@@ -72,6 +75,7 @@ export interface AiProviderSettings {
 export const PROVIDER_SETTINGS_KEYS = [
   'driver',
   'chatModel',
+  'chatContextWindow',
   'chatApiStyle',
   'embeddingModel',
   'baseUrl',
@@ -98,6 +102,9 @@ export const PROVIDER_SETTINGS_KEYS = [
 export interface ResolvedAiConfig extends Partial<AiProviderSettings> {
   driver?: AiDriver;
   chatModel?: string;
+  // Max context window in tokens; surfaced to the chat header badge as the
+  // "current / max" denominator. 0/unset = no limit.
+  chatContextWindow?: number;
   // Cheap model id for the public-share assistant; reuses the chat creds.
   publicShareChatModel?: string;
   // Agent-role id whose persona the public-share assistant adopts (empty/unset
@@ -116,6 +123,9 @@ export interface ResolvedAiConfig extends Partial<AiProviderSettings> {
 export interface MaskedAiSettings {
   driver?: AiDriver;
   chatModel?: string;
+  // Max context window in tokens; the chat header badge denominator. 0/unset =
+  // no limit.
+  chatContextWindow?: number;
   chatApiStyle?: ChatApiStyle;
   embeddingModel?: string;
   baseUrl?: string;

apps/server/src/integrations/ai/dto/update-ai-settings.dto.ts

@@ -1,4 +1,4 @@
-import { IsIn, IsOptional, IsString } from 'class-validator';
+import { IsIn, IsInt, IsOptional, IsString, Min } from 'class-validator';
 import {
   AI_DRIVERS,
   AiDriver,
@@ -25,6 +25,13 @@ export class UpdateAiSettingsDto {
   @IsString()
   chatModel?: string;
 
+  // Max context window in tokens shown in the chat header badge. 0/empty =
+  // clear the limit (no denominator shown).
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  chatContextWindow?: number;
+
   @IsOptional()
   @IsIn(CHAT_API_STYLES)
   chatApiStyle?: ChatApiStyle;

apps/server/src/main.ts

@@ -41,7 +41,14 @@ async function bootstrap() {
   app.useLogger(app.get(PinoLogger));
 
   app.setGlobalPrefix('api', {
-    exclude: ['robots.txt', 'share/:shareId/p/:pageSlug', 'mcp'],
+    exclude: [
+      'robots.txt',
+      'share/:shareId/p/:pageSlug',
+      // Vanity link resolver lives outside /api so /l/<alias> is a clean
+      // public URL that 302s to the canonical share page.
+      'l/:alias',
+      'mcp',
+    ],
   });
 
   const reflector = app.get(Reflector);

apps/server/test/app.e2e-spec.ts

@@ -1,18 +1,34 @@
 import { Test, TestingModule } from '@nestjs/testing';
-import { INestApplication } from '@nestjs/common';
+import {
+  FastifyAdapter,
+  NestFastifyApplication,
+} from '@nestjs/platform-fastify';
 import * as request from 'supertest';
 import { AppModule } from '../src/app.module';
 
 describe('AppController (e2e)', () => {
-  let app: INestApplication;
+  let app: NestFastifyApplication;
 
   beforeEach(async () => {
     const moduleFixture: TestingModule = await Test.createTestingModule({
       imports: [AppModule],
     }).compile();
 
-    app = moduleFixture.createNestApplication();
+    // Docmost runs on Fastify (see src/main.ts). The default
+    // createNestApplication() would load @nestjs/platform-express, which is not
+    // a dependency of this project, so an explicit FastifyAdapter is required.
+    app = moduleFixture.createNestApplication<NestFastifyApplication>(
+      new FastifyAdapter(),
+    );
     await app.init();
+    // Fastify must finish booting before its HTTP server can serve requests.
+    await app.getHttpAdapter().getInstance().ready();
+  });
+
+  afterEach(async () => {
+    // Guard with optional chaining: if beforeEach throws before `app` is
+    // assigned, closing undefined would mask the original failure.
+    await app?.close();
   });
 
   it('/ (GET)', () => {

apps/server/test/integration/duplicate-page-shared-attachment.int-spec.ts

@@ -0,0 +1,207 @@
+import { randomUUID } from 'node:crypto';
+import { Kysely } from 'kysely';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { PagePermissionRepo } from '@docmost/db/repos/page/page-permission.repo';
+import { PageService } from 'src/core/page/services/page.service';
+import {
+  getTestDb,
+  destroyTestDb,
+  createWorkspace,
+  createSpace,
+  createUser,
+} from './db';
+
+/**
+ * #206 attach-1 — Duplicating a subtree where the SAME attachment is referenced
+ * by more than one page must copy a working blob/row for EVERY copy, not just
+ * the last page processed.
+ *
+ * Setup: root page A and child page B both embed the same image (attachmentId X,
+ * the attachment row owned by A in the DB). Duplicating A produces copies A' and
+ * B'. Before the fix the per-attachmentId map held a single entry, so B's entry
+ * clobbered A's and the row-ownership guard (`attachment.pageId !== oldPageId`)
+ * then skipped the only DB row entirely: zero blobs copied, zero new rows, both
+ * copies' images 404. The fix keys the map to a LIST and copies once per
+ * referencing page, dropping the broken guard.
+ *
+ * This drives the real PageService.duplicatePage against a real Postgres with a
+ * recording storage stub, and asserts: storage.copy called twice and two fresh
+ * attachment rows exist (one owned by A', one by B'), each matching the rewritten
+ * attachmentId in its page's content.
+ */
+describe('PageService.duplicatePage shared attachment [integration]', () => {
+  let db: Kysely<any>;
+  let pageRepo: PageRepo;
+  let pagePermissionRepo: PagePermissionRepo;
+  let pageService: PageService;
+  let workspaceId: string;
+  let spaceId: string;
+  let userId: string;
+
+  // Records every (source, dest) blob copy the service requests.
+  const copyCalls: Array<{ from: string; to: string }> = [];
+  const storageService = {
+    copy: async (from: string, to: string) => {
+      copyCalls.push({ from, to });
+    },
+  } as any;
+
+  // Duplicate persists transclusion/reference rows in best-effort try/catch
+  // blocks; a no-op stub keeps the harness focused on the attachment path.
+  const transclusionService = {
+    insertTransclusionsForPages: async () => {},
+    insertReferencesForPages: async () => {},
+    insertTemplateReferencesForPages: async () => {},
+  } as any;
+
+  const eventEmitter = { emit: () => true } as any;
+
+  function imageDoc(attachmentId: string) {
+    return {
+      type: 'doc',
+      content: [
+        {
+          type: 'image',
+          attrs: {
+            attachmentId,
+            src: `/api/files/${attachmentId}/image.png`,
+            width: '100%',
+            align: 'center',
+          },
+        },
+      ],
+    };
+  }
+
+  beforeAll(async () => {
+    db = getTestDb();
+    pageRepo = new PageRepo(db as any, {} as any, eventEmitter);
+    // filterAccessiblePageIds short-circuits to the input ids when the space has
+    // no restricted pages, so groupRepo/cache (2nd/3rd ctor args) are never hit.
+    pagePermissionRepo = new PagePermissionRepo(
+      db as any,
+      {} as any,
+      {} as any,
+    );
+    pageService = new PageService(
+      pageRepo,
+      pagePermissionRepo,
+      undefined as any, // attachmentRepo (unused on duplicate path)
+      db as any,
+      storageService,
+      undefined as any, // attachmentQueue
+      undefined as any, // aiQueue
+      undefined as any, // generalQueue
+      eventEmitter,
+      undefined as any, // collaborationGateway
+      undefined as any, // watcherService
+      transclusionService,
+    );
+
+    workspaceId = (await createWorkspace(db)).id;
+    spaceId = (await createSpace(db, workspaceId)).id;
+    userId = (await createUser(db, workspaceId)).id;
+  });
+
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  it('copies a shared attachment for every page that references it', async () => {
+    copyCalls.length = 0;
+
+    const attachmentId = randomUUID();
+    const pageAId = randomUUID();
+    const pageBId = randomUUID();
+
+    // Root A and child B both embed the same attachmentId.
+    await db
+      .insertInto('pages')
+      .values({
+        id: pageAId,
+        slugId: `a-${pageAId.slice(0, 8)}`,
+        title: 'A',
+        content: imageDoc(attachmentId) as any,
+        position: 'a0',
+        spaceId,
+        workspaceId,
+        creatorId: userId,
+      })
+      .execute();
+    await db
+      .insertInto('pages')
+      .values({
+        id: pageBId,
+        slugId: `b-${pageBId.slice(0, 8)}`,
+        title: 'B',
+        content: imageDoc(attachmentId) as any,
+        position: 'a0',
+        parentPageId: pageAId,
+        spaceId,
+        workspaceId,
+        creatorId: userId,
+      })
+      .execute();
+
+    // Single attachment row, owned by A.
+    await db
+      .insertInto('attachments')
+      .values({
+        id: attachmentId,
+        type: 'image',
+        filePath: `${spaceId}/${attachmentId}/image.png`,
+        fileName: 'image.png',
+        fileExt: 'png',
+        mimeType: 'image/png',
+        creatorId: userId,
+        workspaceId,
+        pageId: pageAId,
+        spaceId,
+      })
+      .execute();
+
+    const rootPage = await pageRepo.findById(pageAId);
+    const result = await pageService.duplicatePage(
+      rootPage as any,
+      undefined,
+      { id: userId, workspaceId } as any,
+    );
+
+    const newRootId = result.id;
+    const newChildIds = result.childPageIds;
+    expect(newChildIds).toHaveLength(1);
+    const newChildId = newChildIds[0];
+
+    // Both pages' images were copied: one blob per referencing page.
+    expect(copyCalls).toHaveLength(2);
+
+    // Two fresh attachment rows exist, one owned by each copied page.
+    const newAttachments = await db
+      .selectFrom('attachments')
+      .selectAll()
+      .where('pageId', 'in', [newRootId, newChildId])
+      .where('workspaceId', '=', workspaceId)
+      .execute();
+    expect(newAttachments).toHaveLength(2);
+
+    const ownerIds = newAttachments.map((a) => a.pageId).sort();
+    expect(ownerIds).toEqual([newRootId, newChildId].sort());
+
+    // Each copied page's content points at a rewritten attachmentId that now has
+    // a real row (i.e. the image src resolves instead of 404ing).
+    for (const pageId of [newRootId, newChildId]) {
+      const page = await db
+        .selectFrom('pages')
+        .select(['content'])
+        .where('id', '=', pageId)
+        .executeTakeFirstOrThrow();
+      const node = (page.content as any).content[0];
+      expect(node.type).toBe('image');
+      const referencedId = node.attrs.attachmentId;
+      expect(referencedId).not.toBe(attachmentId); // remapped to a fresh id
+      const row = newAttachments.find((a) => a.id === referencedId);
+      expect(row).toBeDefined();
+      expect(row!.pageId).toBe(pageId);
+    }
+  });
+});

apps/server/test/integration/page-move-cycle.int-spec.ts

@@ -0,0 +1,133 @@
+import { Kysely } from 'kysely';
+import { generateJitteredKeyBetween } from 'fractional-indexing-jittered';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { PageService } from 'src/core/page/services/page.service';
+import { Page } from '@docmost/db/types/entity.types';
+import {
+  getTestDb,
+  destroyTestDb,
+  createWorkspace,
+  createSpace,
+  createPage,
+} from './db';
+
+/**
+ * #207 #7 — TOCTOU in PageService.movePage: two concurrent moves
+ * ("A under B" + "B under A") must NOT be able to persist a parent/child cycle.
+ *
+ * Before the fix the cycle check (getPageBreadCrumbs) and the UPDATE were two
+ * separate, unlocked statements, so both movers could read the same pre-write
+ * acyclic snapshot, both pass the guard, and persist A.parentPageId=B AND
+ * B.parentPageId=A. The fix runs the guard + UPDATE in one transaction behind a
+ * per-space advisory lock, so the moves serialize: whichever commits second
+ * sees the first's write and its guard rejects the cycle.
+ *
+ * This test drives the real PageService.movePage against a real Postgres,
+ * firing the two opposing moves concurrently, and asserts that no cycle ever
+ * persists (walking parentPageId from both pages always reaches a root with no
+ * repeated id) and that exactly one of the two opposing moves is rejected.
+ */
+describe('PageService.movePage concurrent A<->B cycle guard [integration]', () => {
+  let db: Kysely<any>;
+  let pageRepo: PageRepo;
+  let pageService: PageService;
+  let workspaceId: string;
+  let spaceId: string;
+
+  // A valid fractional-index position key; movePage validates the position.
+  const position = generateJitteredKeyBetween(null, null);
+
+  beforeAll(async () => {
+    db = getTestDb();
+    // Event emission is a side effect movePage performs but the cycle behaviour
+    // does not depend on; a no-op emitter keeps the harness minimal.
+    const eventEmitter = { emit: () => true } as any;
+    pageRepo = new PageRepo(db as any, {} as any, eventEmitter);
+    // Only pageRepo (1), db (4) and eventEmitter (9) are touched by movePage;
+    // the remaining constructor deps are unused on this path.
+    pageService = new PageService(
+      pageRepo,
+      undefined as any,
+      undefined as any,
+      db as any,
+      undefined as any,
+      undefined as any,
+      undefined as any,
+      undefined as any,
+      eventEmitter,
+      undefined as any,
+      undefined as any,
+      undefined as any,
+    );
+
+    workspaceId = (await createWorkspace(db)).id;
+    spaceId = (await createSpace(db, workspaceId)).id;
+  });
+
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  async function findPage(id: string): Promise<Page> {
+    const page = await pageRepo.findById(id);
+    if (!page) throw new Error(`page ${id} not found`);
+    return page;
+  }
+
+  // Walk parentPageId upward from startId. Throws if a node repeats (cycle) or
+  // the walk fails to terminate; returns normally only when a root is reached.
+  async function assertReachesRoot(startId: string): Promise<void> {
+    const seen = new Set<string>();
+    let cur: string | null = startId;
+    let steps = 0;
+    while (cur) {
+      if (seen.has(cur)) {
+        throw new Error(`cycle detected: revisited ${cur}`);
+      }
+      seen.add(cur);
+      const row: { parentPageId: string | null } | undefined = await db
+        .selectFrom('pages')
+        .select('parentPageId')
+        .where('id', '=', cur)
+        .executeTakeFirst();
+      cur = row?.parentPageId ?? null;
+      if (++steps > 1000) {
+        throw new Error('parent walk did not terminate');
+      }
+    }
+  }
+
+  it('two opposing concurrent moves never persist a parent/child cycle', async () => {
+    // Repeat to exercise different scheduler interleavings of the two moves.
+    for (let i = 0; i < 8; i++) {
+      const a = await createPage(db, { workspaceId, spaceId, title: `A-${i}` });
+      const b = await createPage(db, { workspaceId, spaceId, title: `B-${i}` });
+
+      const movedA = await findPage(a.id);
+      const movedB = await findPage(b.id);
+
+      const results = await Promise.allSettled([
+        pageService.movePage(
+          { pageId: a.id, parentPageId: b.id, position } as any,
+          movedA,
+        ),
+        pageService.movePage(
+          { pageId: b.id, parentPageId: a.id, position } as any,
+          movedB,
+        ),
+      ]);
+
+      // No cycle may have been persisted by either ordering.
+      await assertReachesRoot(a.id);
+      await assertReachesRoot(b.id);
+
+      // The serialization guarantees exactly one of the opposing moves wins;
+      // the other must be rejected as a subtree cycle.
+      const rejected = results.filter(
+        (r): r is PromiseRejectedResult => r.status === 'rejected',
+      );
+      expect(rejected).toHaveLength(1);
+      expect(rejected[0].reason?.message).toMatch(/into its own subtree/);
+    }
+  });
+});

apps/server/test/integration/page-recursive-cte-cycle-guard.int-spec.ts

@@ -0,0 +1,134 @@
+import { CamelCasePlugin, Kysely } from 'kysely';
+import { PostgresJSDialect } from 'kysely-postgres-js';
+import * as postgres from 'postgres';
+import { PageService } from 'src/core/page/services/page.service';
+import {
+  getTestDb,
+  destroyTestDb,
+  createWorkspace,
+  createSpace,
+  createPage,
+  TEST_DATABASE_URL,
+} from './db';
+
+/**
+ * #207 #8 — recursive page-tree CTEs (ancestors in getPageBreadCrumbs,
+ * descendants in forceDelete) must not hang when a parent/child cycle already
+ * exists in the data. Before the fix neither CTE had a CYCLE clause or a depth
+ * cap, so a cycle (e.g. one persisted by the #7 TOCTOU race) made withRecursive
+ * loop forever — and since the move guard itself runs the ancestor CTE, a cycle
+ * would disable the very guard meant to prevent it.
+ *
+ * The fix adds a depth counter bounded by MAX_PAGE_TREE_DEPTH to both CTEs.
+ * These tests seed an A<->B cycle directly (bypassing the guard), then run the
+ * real CTE paths against Postgres with a short connection-level statement_timeout
+ * so a regression (an unbounded CTE) fails fast as a query timeout instead of a
+ * bounded result.
+ */
+describe('recursive page-tree CTEs cycle/depth guard [integration]', () => {
+  // Upper bound on rows the depth-capped CTEs can emit for a 2-node cycle: one
+  // row per depth level 0..MAX. Kept loose so the assertion does not couple to
+  // the exact constant, only to "bounded".
+  const BOUNDED_MAX_ROWS = 20_000;
+
+  let db: Kysely<any>;
+  // Dedicated Kysely whose connections carry a short statement_timeout, so an
+  // unbounded recursive CTE aborts quickly instead of hanging the suite.
+  let timeoutDb: Kysely<any>;
+  let workspaceId: string;
+  let spaceId: string;
+
+  beforeAll(async () => {
+    db = getTestDb();
+    timeoutDb = new Kysely<any>({
+      dialect: new PostgresJSDialect({
+        postgres: postgres(TEST_DATABASE_URL, {
+          max: 2,
+          onnotice: () => {},
+          // Applied to every connection on connect: cap any single statement.
+          connection: { statement_timeout: 4000 },
+          types: {
+            bigint: {
+              to: 20,
+              from: [20, 1700],
+              serialize: (value: number) => value.toString(),
+              parse: (value: string) => Number.parseInt(value),
+            },
+          },
+        }),
+      }),
+      plugins: [new CamelCasePlugin()],
+    });
+    workspaceId = (await createWorkspace(db)).id;
+    spaceId = (await createSpace(db, workspaceId)).id;
+  });
+
+  afterAll(async () => {
+    await timeoutDb.destroy();
+    await destroyTestDb();
+  });
+
+  // Seed two fresh pages and wire them into a direct parent/child cycle,
+  // bypassing PageService.movePage's guard the way the #7 race would.
+  async function seedCycle(): Promise<{ aId: string; bId: string }> {
+    const a = await createPage(db, { workspaceId, spaceId, title: 'cycle-A' });
+    const b = await createPage(db, { workspaceId, spaceId, title: 'cycle-B' });
+    await db
+      .updateTable('pages')
+      .set({ parentPageId: b.id })
+      .where('id', '=', a.id)
+      .execute();
+    await db
+      .updateTable('pages')
+      .set({ parentPageId: a.id })
+      .where('id', '=', b.id)
+      .execute();
+    return { aId: a.id, bId: b.id };
+  }
+
+  function makeService(database: Kysely<any>): PageService {
+    const eventEmitter = { emit: () => true } as any;
+    const attachmentQueue = { add: async () => undefined } as any;
+    return new PageService(
+      undefined as any, // pageRepo (unused by these paths)
+      undefined as any, // pagePermissionRepo
+      undefined as any, // attachmentRepo
+      database as any, // db
+      undefined as any, // storageService
+      attachmentQueue, // attachmentQueue
+      undefined as any, // aiQueue
+      undefined as any, // generalQueue
+      eventEmitter, // eventEmitter
+      undefined as any, // collaborationGateway
+      undefined as any, // watcherService
+      undefined as any, // transclusionService
+    );
+  }
+
+  it('getPageBreadCrumbs returns a bounded result (no hang) when a cycle exists', async () => {
+    const { aId } = await seedCycle();
+    const service = makeService(timeoutDb);
+
+    // Must resolve (the depth cap stops the walk) rather than time out.
+    const crumbs = await service.getPageBreadCrumbs(aId);
+
+    expect(Array.isArray(crumbs)).toBe(true);
+    expect(crumbs.length).toBeGreaterThan(1);
+    expect(crumbs.length).toBeLessThanOrEqual(BOUNDED_MAX_ROWS);
+  });
+
+  it('forceDelete descendant CTE is bounded (no hang) and removes the cyclic pages', async () => {
+    const { aId, bId } = await seedCycle();
+    const service = makeService(timeoutDb);
+
+    // Must complete instead of looping on the descendant CTE.
+    await service.forceDelete(aId, workspaceId);
+
+    const survivors = await db
+      .selectFrom('pages')
+      .select('id')
+      .where('id', 'in', [aId, bId])
+      .execute();
+    expect(survivors).toHaveLength(0);
+  });
+});

apps/server/test/jest-e2e.json

@@ -1,14 +1,18 @@
 {
-  "moduleFileExtensions": ["js", "json", "ts"],
+  "moduleFileExtensions": ["js", "json", "ts", "tsx"],
   "rootDir": ".",
   "testEnvironment": "node",
   "testRegex": ".e2e-spec.ts$",
   "transform": {
-    "^.+\\.(t|j)s$": "ts-jest"
+    "^.+\\.(t|j)sx?$": ["ts-jest", { "tsconfig": { "allowJs": true } }]
   },
+  "transformIgnorePatterns": [
+    "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0|@sindresorhus[+/][a-z0-9-]+|escape-string-regexp|p-limit|yocto-queue)(@|/))"
+  ],
   "moduleNameMapper": {
     "^@docmost/db/(.*)$": "<rootDir>/../src/database/$1",
     "^@docmost/transactional/(.*)$": "<rootDir>/../src/integrations/transactional/$1",
-    "^@docmost/ee/(.*)$": "<rootDir>/../src/ee/$1"
+    "^@docmost/ee/(.*)$": "<rootDir>/../src/ee/$1",
+    "^src/(.*)$": "<rootDir>/../src/$1"
   }
 }

docs/backlog/ai-chat-stream-integration-coverage.md

@@ -1,33 +0,0 @@
-# Отложенные интеграционные тесты `AiChatService.stream`
-
-Статус: **открыто.** Это остаток от прежнего документа
-`feature-test-coverage-deferred.md` (хвост тест-плана PR #49). Два из трёх
-его разделов уже закрыты новой интеграционной обвязкой против реального
-Postgres/Redis (`apps/server/test/integration/`, PR #115):
-
-- ✅ **Раздел 1 — repo-тесты против БД.** Закрыт `ai-agent-roles-repo`,
-  `ai-chat-repo-find-by-creator`, `page-template-references-cascade`,
-  `workspace-repo-update-setting` (`*.int-spec.ts`).
-- ✅ **Раздел 2 — достоверность Lua-окна cost-cap против реального Redis.**
-  Закрыт `public-share-workspace-limiter.int-spec.ts`.
-- ⬜ **Раздел 3 (ниже) — полная интеграция `AiChatService.stream`.** Всё ещё
-  не реализован; держим запись открытой, чтобы тест-долг не потерялся при
-  удалении исходного документа.
-
-## Полная интеграция `AiChatService.stream` (рефактор R1-stream)
-
-`apps/server/src/core/ai-chat/ai-chat.service.ts`. В PR #49 извлечён и
-покрыт только чистый `buildErrorAssistantRecord`. Полные интеграционные
-сценарии всё ещё отложены:
-
-- **Запись чата, упавшего на первом ходу** (`onError`) — ассистентская
-  запись об ошибке должна сохраняться, даже когда первый ход стрима падает.
-- **Жизненный цикл external-MCP клиентов** — клиенты закрываются и при
-  `throw`, и при `onFinish` (нет утечки соединений).
-- **Анти-tamper: история восстанавливается из БД, а не из `body.messages`** —
-  клиент не может подменить историю через тело запроса.
-
-Эти сценарии требуют сидирования SDK `streamText` (инъекция/seam колбэков
-`onError` / `onFinish` / `onAbort` + `res.hijack`). Отложено, чтобы не
-дестабилизировать 287-строчный `stream()`; делать вместе с выносом testable
-turn-pipeline.

docs/backlog/ai-chat-tool-definitions-duplicated.md

@@ -1,127 +0,0 @@
-# Дублирование определений инструментов: in-app агент vs standalone MCP-пакет
-
-Статус: **частично закрыто.** Квирк «node как объект ИЛИ JSON-строка» вынесен
-в общий хелпер `parseNodeArg` (см. «Прогресс» ниже); остальной долг (единый
-реестр спеков + унификация конвертера) всё ещё открыт. Это forward-looking
-стоимость поддержки, НЕ баг — код корректен сегодня. Держим запись открытой,
-чтобы при росте набора инструментов долг не разъезжался молча.
-
-## Прогресс
-
-- ✅ **Квирк node-arg вынесен в хелпер** (`refactor/ai-chat-tool-spec-registry`,
-  PR #114). Шесть рукописных копий нормализации «node как объект ИЛИ
-  JSON-строка» свёрнуты в `parseNodeArg`: по одному источнику на пакет —
-  `packages/mcp/src/lib/parse-node-arg.ts` (standalone) и
-  `apps/server/src/core/ai-chat/tools/parse-node-arg.ts` (in-app). Две копии
-  намеренны (ESM/CJS-граница), поведение тождественно.
-- ⏳ **Единый реестр спеков** (схема + описание на инструмент) и **вывод
-  `DocmostClientLike` из реального типа** — отложены (см. «Фикс»): требуют
-  пересечения ESM/CJS-границы для данных+zod и ломают тест-стабы in-app
-  инструментов при точных типах. Делать инкрементально.
-- ⏳ **Унификация конвертера ProseMirror ↔ Markdown** — открыта (см. раздел
-  «Расширение …» ниже); на неё опирается план git-синка
-  (`docs/backlog/git-sync-thin-meta.md`).
-
-## Суть
-
-Один и тот же набор инструментов поверх одного `DocmostClient` описан
-**тремя независимыми рукописными слоями**. Каждое добавление инструмента или
-правка его model-facing описания требует синхронной правки в 2–3 местах, а
-parity-баги (расхождение копий) приходится чинить/переоткрывать дважды.
-
-## Где дублируется (три слоя)
-
-1. **Standalone MCP-сервер** — `packages/mcp/src/index.ts` (~38 `registerTool`).
-   Для внешних MCP-клиентов (stdio/http). На каждый инструмент: zod-схема +
-   длинное model-facing описание + тонкий `execute`, вызывающий `DocmostClient`.
-2. **Встроенный AI-чат** — `apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts`
-   (~39 `tool({...})` через `ai`-SDK). Своя zod-схема + своё описание + свой
-   `execute` поверх ТОГО ЖЕ клиента (`@docmost/mcp` грузится в
-   `tools/docmost-client.loader.ts:188` через динамический `import()`).
-3. **Ручная копия сигнатур** — интерфейс `DocmostClientLike` в
-   `apps/server/src/core/ai-chat/tools/docmost-client.loader.ts:9` (в комментарии
-   прямо: «Signatures here mirror that file exactly»), скопирован руками из
-   `packages/mcp/src/client.ts`.
-
-## Что именно продублировано (с подтверждением по коду)
-
-- **zod-схема + описание** каждого инструмента — в слоях 1 и 2 целиком.
-- ~~**Квирк «node как объект ИЛИ JSON-строка»** реализован дважды (НЕ в общем
-  клиенте)~~ — **закрыто (PR #114):** вынесен в `parseNodeArg` (по хелперу на
-  пакет), 6 inline-копий устранены:
-  - in-app: `patchNode`, `insertNode`, `updatePageJson` →
-    `apps/server/src/core/ai-chat/tools/parse-node-arg.ts`;
-  - standalone: `patch_node`, `insert_node`, `update_page_json` →
-    `packages/mcp/src/lib/parse-node-arg.ts`.
-- **Guardrail/семантика `transformPage` (dryRun)** описана в обоих:
-  `ai-chat-tools.service.ts:~935` и `index.ts:~1006`.
-
-## Почему разделение слоёв 1 и 2 само по себе оправдано
-
-У путей разный транспорт и auth-контекст, и это правильно держать раздельно:
-in-app путь чеканит per-user JWT + provenance collab-токен (подписанная
-agent-claim, `docmost-client.loader.ts:159` — `getCollabToken`; см. план §6.5),
-а standalone обслуживает внешних клиентов по stdio/http. **Но** это оправдывает
-два тонких адаптера (`execute` + auth-обвязка), а НЕ две рукописные копии
-МЕТАДАННЫХ (схема + описание + квирки). Метаданные можно объявить один раз и
-переиспользовать обоими транспортами.
-
-## Доказательство стоимости (наблюдалось при фиксе edit_page_text)
-
-При исправлении ложного «успеха» `edit_page_text` (refuse форматных правок +
-`verify`-отчёт):
-- **Поведение** легло в общий `DocmostClient` → автоматически дошло до обоих
-  агентов ОДНОЙ правкой. Это «хороший» случай — логика в едином источнике.
-- **Описание** инструмента пришлось править ДВАЖДЫ: в `index.ts` (кодером) и
-  отдельно в `ai-chat-tools.service.ts:617`, где описание продолжало рекламировать
-  «Markdown wrappers tolerated via strip-and-retry» — ровно ту формулировку, что
-  ввела исходного агента в заблуждение. Копия молча разъехалась и какое-то время
-  встроенный агент получал устаревшую подсказку. Это и есть материализованный
-  parity-баг.
-
-## Расширение: дублируется не только описания инструментов — ещё и конвертер (PM ↔ Markdown)
-
-Зафиксировано при планировании встраивания git-синка (`docmost-sync` → gitmost,
-нативная in-process интеграция). Та же болезнь «несколько рукописных копий одного
-кода» теперь касается слоя конвертации ProseMirror ↔ Markdown и его lib, а не
-только метаданных инструментов.
-
-- **Копия в gitmost** — `packages/mcp/src/lib/`: `markdown-converter.ts` (~885
-  строк), `markdown-document.ts` (~136), `node-ops.ts`, `diff.ts`,
-  `docmost-schema.ts`. Канонизатора (`canonicalize.ts`) здесь НЕТ.
-- **Копия в docmost-sync** — `packages/docmost-client/src/lib/`: тот же набор +
-  `canonicalize.ts` (~11 КБ, держит идемпотентность round-trip, SPEC §11) +
-  `markdown-document.ts` с режимом «тело + якоря, без тредов комментов»
-  (`includeCommentThreads:false`, на ~20 строк больше).
-- **Третья копия (планируется)** — план git-синка вендорит чистую часть
-  конвертера в новый `packages/git-sync` (collab-файл не нужен: запись идёт
-  нативно через `openDirectConnection` + `@docmost/editor-ext`).
-
-Копии уже молча разъехались (docmost-sync vs `packages/mcp`): `collaboration.ts`
-~329 изменённых строк, `node-ops.ts` ~53, `markdown-converter.ts` ~24,
-`markdown-document.ts` ~20. Отдельно: `docmost-schema.ts` в lib дублирует
-**реальную** схему сервера `@docmost/editor-ext` (её использует collab/persistence)
-— расхождение схем = риск битой конвертации нод.
-
-Вывод: тот же фикс-вектор (единый источник правды), что и для инструментов, стоит
-распространить на конвертер — общий пакет конвертации, потребляемый `mcp`,
-`git-sync` и (в идеале) сервером. До конвергенции git-sync держит вендоренную
-копию валидированного конвертера с гейтом round-trip против схемы `editor-ext`
-(осознанный долг «третья копия сейчас, объединяем позже»).
-
-## Фикс
-
-Единый реестр спеков (полное устранение дублирования).** Вынести в
-  `packages/mcp` один источник на инструмент: `name` + zod-схема + model-facing
-  описание + общий хелпер нормализации node-строки (для patch/insert/update).
-  И `index.ts`, и `ai-chat-tools.service.ts` импортируют спеки и добавляют только
-  свой `execute`/auth. `DocmostClientLike` — выводить из типа реального клиента
-  (type-only import / генерация), а не копировать руками.
-  - Ограничение: `@docmost/mcp` — ESM-only, сервер грузит его через трюк
-    `new Function('import(specifier)')` (`docmost-client.loader.ts:174`), потому
-    что `module:commonjs` даунлевелит `import()` в `require()`. Реестр спеков
-    (данные + zod) должен пересекать ту же ESM/CJS-границу — выполнимо тем же
-    динамическим импортом; `ai`-SDK `tool()` и MCP `registerTool()` имеют разную
-    форму, поэтому реестр экспортирует транспорт-агностичные `{name, schema,
-    description}`, а каждая сторона оборачивает их сама. `zod` — общая зависимость
-    обоих пакетов, типы переносятся.

docs/mobile-app-plan.md

@@ -1,359 +0,0 @@
-# Мобильное приложение gitmost — исследование и план
-
-> Статус: исследовательский + проектный документ.
-> Контекст: gitmost — форк Docmost, чистое веб-приложение. Отдельного
-> мобильного (нативного/устанавливаемого) приложения **нет**.
-> Цель: определить путь к мобильным приложениям — **iOS обязательно, Android
-> как пойдёт** — с заделом на оффлайн в будущем (оффлайн сейчас не требуется).
-
-Документ фиксирует, что уже есть в коде, почему путь к мобилке предопределён
-устройством продукта, сравнивает варианты и описывает рекомендуемый план с
-привязкой к файлам.
-
----
-
-## 1. TL;DR
-
-1. **Нативного приложения нет.** В проекте отсутствуют Capacitor, React Native,
-   Cordova и т.п. Мобильного клиента ещё не начинали.
-2. **Адаптивная веб-версия — есть, и довольно проработанная.** Веб-клиент
-   открывается с телефона как mobile-friendly сайт: сворачиваемый сайдбар-drawer,
-   отдельные мобильные компоненты (история, поиск, хлебные крошки), responsive-
-   примитивы Mantine, mobile-tuned `viewport`. Это готовый фундамент UI.
-3. **Ядро продукта — веб-редактор — нативно не воспроизвести.** TipTap 3
-   (ProseMirror) + совместное редактирование на Yjs/Hocuspocus плотно сшиты с
-   React. Production-порта Yjs под Swift/Kotlin нет. Любой реалистичный путь
-   оставляет редактор в **WebView**.
-4. **API уже готов к нативному клиенту.** Сервер принимает JWT не только из
-   cookie, но и из заголовка `Authorization: Bearer`. Есть точка входа для
-   вебсокета совместного редактирования (`POST /auth/collab-token`).
-5. **Рекомендуемый путь — Capacitor:** обернуть существующий React-SPA в
-   нативную оболочку (iOS + Android из одного кода), добавить нативные плагины
-   (push, биометрия, share, файлы). Эволюция в гибрид (нативная навигация +
-   WebView-редактор) делается потом инкрементально, без переписывания.
-6. **Оффлайн-будущее уже заложено** (Yjs + `y-indexeddb`). Детальный план —
-   в [offline-sync-plan.md](offline-sync-plan.md); мобильное приложение этот
-   план переиспользует, а не дублирует.
-7. **Главный блокер — не технический, а лицензионный.** AGPL форка несовместима
-   с условиями App Store, если зашивать веб-клиент в бинарник: DRM/usage-rules
-   Apple = «дополнительные ограничения», запрещённые AGPLv3 §10. Развязки —
-   грузить клиент с сервера (не из `.ipa`), PWA или sideload. Детали и матрица —
-   в §9; закрывать **до** кода обёртки.
-
----
-
-## 2. Текущее состояние (как есть)
-
-### 2.1. Стек
-
-| Слой | Технологии |
-|---|---|
-| Бэкенд | NestJS 11 + Fastify, Kysely/Postgres, Redis/BullMQ. API в стиле RPC-POST (соглашение Docmost). Аутентификация — JWT. |
-| Фронт | React 18 + Vite + Mantine + TanStack Query + i18next. Обычный SPA. |
-| Ядро (редактор) | TipTap 3 (ProseMirror) + совместное редактирование на Yjs через Hocuspocus — см. [page-editor.tsx](../apps/client/src/features/editor/page-editor.tsx). |
-| Оффлайн-фундамент | `yjs` + `y-indexeddb` уже в зависимостях клиента (локальная CRDT-копия тела документа). |
-
-### 2.2. Мобильного приложения нет
-
-В `package.json` и `apps/*/package.json` нет `capacitor`, `react-native`,
-`cordova`, `expo`. Нативной оболочки в репозитории не заведено.
-
-### 2.3. Адаптивная веб-версия — есть
-
-| Что | Где |
-|---|---|
-| Адаптивная оболочка Mantine `AppShell` с `breakpoint: "sm"`, раздельные состояния `collapsed.mobile` / `collapsed.desktop` | [global-app-shell.tsx](../apps/client/src/components/layouts/global/global-app-shell.tsx) (L85–99) |
-| Отдельный мобильный сайдбар-drawer (`mobileSidebarAtom` отделён от `desktopSidebarAtom`), авто-закрытие при навигации по дереву | [sidebar-atom.ts](../apps/client/src/components/layouts/global/hooks/atoms/sidebar-atom.ts), [space-tree-row.tsx](../apps/client/src/features/page/tree/components/space-tree-row.tsx) (L147–148) |
-| Мобильная модалка истории + свой CSS | [history-modal.tsx](../apps/client/src/features/page-history/components/history-modal.tsx) (L17–19), `history-modal-mobile.tsx` |
-| Мобильный контрол поиска | [search-control.tsx](../apps/client/src/features/search/components/search-control.tsx) (L38–42) |
-| Мобильный рендер хлебных крошек через `useMediaQuery` | [breadcrumb.tsx](../apps/client/src/features/page/components/breadcrumbs/breadcrumb.tsx) (L41) |
-| Responsive-примитивы `hiddenFrom`/`visibleFrom` (~16 мест), медиа-запросы в CSS-модулях | по всему `apps/client/src` |
-| Mobile-tuned viewport (`width=device-width, user-scalable=no`) | [index.html](../apps/client/index.html) (L8) |
-
-> Важно: адаптив проверялся в мобильном **браузере**, а не в WebView нативной
-> оболочки. Перед сборкой приложения нужно прогнать UI как PWA/в WebView и
-> отловить отличия (жесты, экранная клавиатура/IME в редакторе, safe-area).
-
-### 2.4. Готовность API к нативному клиенту
-
-- **Bearer-токен уже поддержан.** JWT извлекается из cookie **или** из заголовка
-  `Authorization`: см. [jwt.strategy.ts](../apps/server/src/core/auth/strategies/jwt.strategy.ts) (L27–29).
-  Серверная сторона нативной авторизации менять не нужно.
-- **Токен сейчас не возвращается в теле логина.** [`login`](../apps/server/src/core/auth/auth.controller.ts)
-  (L55–105) кладёт JWT только в `httpOnly`-cookie ([`setAuthCookie`](../apps/server/src/core/auth/auth.controller.ts) L222–230).
-- **Точка входа вебсокета коллаборации:** [`POST /auth/collab-token`](../apps/server/src/core/auth/auth.controller.ts) (L187–193).
-- **CORS открыт без конфигурации:** [`app.enableCors()`](../apps/server/src/main.ts) (L144).
-- **OpenAPI/Swagger отсутствует** (`@nestjs/swagger` не подключён) — авто-генерации
-  типизированного клиента сейчас нет.
-
----
-
-## 3. Почему путь к мобилке предопределён
-
-Три факта диктуют решение независимо от моды:
-
-1. **Редактор практически невозможно переписать нативно.** ProseMirror + весь
-   набор TipTap-расширений + Yjs-CRDT — это не «поле ввода». Нативного
-   production-порта Yjs под Swift/Kotlin нет (есть Rust `yrs` с биндингами, но
-   это отдельный тяжёлый проект). Переписывание ядра нативно = годы и вечное
-   расхождение с веб-версией. **Вывод: редактор остаётся в WebView.**
-2. **API уже умеет нативного клиента** (Bearer, collab-token).
-3. **Оффлайн-фундамент уже заложен** на веб-уровне (Yjs + `y-indexeddb`),
-   и он работает внутри WebView.
-
----
-
-## 4. Три возможных пути
-
-| Путь | Суть | Плюсы | Минусы | Вердикт |
-|---|---|---|---|---|
-| **A. Полностью нативно** (Swift/Kotlin) | Переписать всё, включая редактор и CRDT-синк | Максимально нативный UX | Воспроизвести ProseMirror + расширения + Yjs; несоразмерные трудозатраты; вечное отставание от веба | ❌ Не наш случай |
-| **B. WebView-обёртка SPA (Capacitor)** | Обернуть существующий React-клиент в нативную оболочку, native-возможности — плагинами | Реюз ~100% кода (редактор, коллаборация, оффлайн); один кодовый бэйз → iOS+Android; быстро | Менее «нативно»; риск отказа App Store за «просто сайт» (4.2) — лечится нативной ценностью | ✅ Рекомендуется |
-| **C. Гибрид: нативная оболочка + WebView-редактор** | Навигация/списки/поиск/логин — нативно (React Native/Swift), экран редактирования — web в WebView | Лучший UX; путь Notion/Linear | Заметно больше работы; нужен мост JS↔native | ⚖️ Цель эволюции из B |
-
----
-
-## 5. Рекомендуемый путь
-
-**B (Capacitor) как первый релиз, с заложенной эволюцией в C.**
-
-Почему:
-- Capacitor создан под сценарий «есть веб-приложение → хочу его в App Store с
-  нативными возможностями». Переиспользуется весь React-клиент и, главное,
-  редактор — то, что нативно не сделать.
-- Один кодовый бэйз закрывает «iOS обязательно» и «Android как пойдёт»
-  одновременно, без второй команды.
-- Адаптивная вёрстка уже есть (см. §2.3) — переверстывать под телефон с нуля
-  не нужно; работа смещается в нативную обвязку.
-- Оффлайн-будущее подготовлено (Yjs + `y-indexeddb`); см.
-  [offline-sync-plan.md](offline-sync-plan.md).
-- Когда упрётесь в UX отдельных экранов — их по одному выносят в нативную
-  оболочку, оставив редактор в WebView. То есть B → C делается инкрементально.
-
-Почему **не** чистый React Native сразу: редактор всё равно придётся держать в
-WebView (ядро web-only), но при этом теряется прямой реюз остального React-кода
-и появляется мост как обязательная сложность с первого дня — для iOS-first
-старта это лишний оверхед.
-
-> Альтернатива: если критичен максимально нативный UX с первого релиза и есть
-> ресурс — сразу путь C на React Native (Expo) с WebView только под редактор.
-> Это сознательный размен «больше работы сейчас» за «более нативное ощущение».
-
-⚠️ **Лицензионная оговорка к iOS.** Обычный Capacitor зашивает веб-билд
-`apps/client` в `.ipa` — для публикации в App Store это **нарушает AGPL**
-(см. §9). Выбор Capacitor для **Android** остаётся в силе, но на **iOS**
-веб-клиент нельзя бандлить в бинарник: либо грузить его с сервера
-(`server.url`), либо PWA. То есть рекомендация «B (Capacitor)» применима к
-Android как есть, а к iOS — только в конфигурации без зашитого AGPL.
-
----
-
-## 6. Что доработать на бэкенде
-
-Немного, но конкретно:
-
-1. **Выдача токена в теле ответа для нативного хранения.** Сейчас логин кладёт
-   JWT только в `httpOnly`-cookie и не возвращает его в body. На мобиле
-   `httpOnly`-cookie между разными origin (`capacitor://localhost` ↔ API) — боль
-   с SameSite/CORS. Чище: мобильный логин-флоу, возвращающий JWT в ответе, чтобы
-   хранить его в Keychain/Keystore и слать как `Authorization: Bearer`. Сервер
-   уже принимает Bearer — менять надо только **выдачу**.
-   Файлы: [auth.controller.ts](../apps/server/src/core/auth/auth.controller.ts).
-2. **CORS.** Сейчас [`app.enableCors()`](../apps/server/src/main.ts) (L144) без
-   конфигурации. Под мобильные origin'ы и для безопасности задать явный whitelist.
-3. **Push-уведомления.** Модуль `notification` уже есть — добавить регистрацию
-   device-token и интеграцию **APNs** (iOS) / **FCM** (Android).
-4. **Опционально — OpenAPI/Swagger.** Сейчас спецификации нет; добавить
-   `@nestjs/swagger` дёшево и сильно ускорит мобильную разработку
-   (типизированный клиент).
-
----
-
-## 7. Android-специфика
-
-На пути Capacitor Android едет почти бесплатно (`npx cap add android` из того же
-веб-билда), но есть нюансы:
-
-- **Движок в плюс.** Android System WebView (Chromium) обновляется через Play
-  Store независимо от ОС и обычно свежее iOS WKWebView. Более рискованный движок
-  по совместимости — это iOS, а не Android.
-- **Фрагментация.** Дешёвые/старые устройства с малой памятью и устаревшим
-  WebView; стек тяжёлый (ProseMirror + Yjs + mermaid + katex + excalidraw) —
-  тестировать на бюджетных аппаратах.
-- **Обвязка под Android:** аппаратная/жестовая кнопка «Назад» (навигация внутри
-  приложения, а не выход), **FCM** для push, Android App Links (вместо iOS
-  Universal Links), подписание и Play Console.
-- **Главный риск именно для Android — ввод текста в ProseMirror на Gboard/IME.**
-  Историческая боль `contenteditable` на Android (прыжки курсора, дубли символов
-  при композиции). Стало лучше, но **проверять в первую очередь и рано**.
-- **Магазин.** Google Play лояльнее к webview-обёрткам, чем App Store; риск
-  «отклонят как просто сайт» для Play практически неактуален.
-
----
-
-## 8. iOS-специфика
-
-- **WKWebView** на движке WebKit жёстко привязан к версии ОС — это более
-  рискованный по совместимости движок (тестировать прежде всего его).
-- **App Store guideline 4.2 (minimum functionality).** Чистая webview-обёртка
-  рискует отклонением «это просто сайт». Лечится реальной нативной ценностью:
-  push, share-extension, биометрический разблок, оффлайн-кэш — всё это Capacitor
-  даёт плагинами.
-- **safe-area** под «чёлку»/системные панели, поведение экранной клавиатуры в
-  редакторе.
-
----
-
-## 9. Лицензионный блокер: AGPL ↔ App Store (iOS)
-
-> Это не инженерная, а **лицензионная** задача — закрывать её надо **до** кода
-> обёртки, иначе можно сделать приложение, которое некуда легально опубликовать.
-> Ниже — инженерно-лицензионный разбор, **не** юридическая консультация; финально
-> подтверждать у того, кто разбирается в лицензиях.
-
-### 9.1. Суть конфликта
-
-gitmost — форк Docmost под **AGPL-3.0** (константа форка: «100% open, AGPL-only»).
-Две вещи несовместимы:
-
-- **AGPLv3 §10** (последний абзац) запрещает накладывать на получателя кода
-  **любые дополнительные ограничения** сверх самой лицензии.
-- **Стандартный EULA App Store** ровно их и накладывает: **FairPlay/DRM**,
-  привязка установки к Apple ID с лимитом устройств (**usage rules**), запрет
-  свободного перераспространения бинарника.
-
-Приняв условия Apple, чтобы попасть в App Store, вы нарушаете AGPL кода, который
-раздаёте.
-
-### 9.2. Почему это бьёт именно по форку
-
-Запрет «дополнительных ограничений» связывает **лицензиатов, но не самого
-правообладателя**: владелец 100% копирайта может опубликовать свой код в App Store.
-Но в gitmost бóльшая часть копирайта принадлежит **upstream-Docmost** и
-контрибьюторам — вы выступаете дистрибьютором *чужого* AGPL-кода и не можете
-единолично добавить App-Store-исключение.
-
-Прецеденты: **VLC** (удалён из App Store в 2011 по жалобе на конфликт GPL с
-условиями стора; вернулся только после перелицензирования и согласия
-правообладателей), **GNU Go** — снят по той же причине. Это не теоретический риск.
-
-### 9.3. Ключевой принцип развязки: лицензия смотрит на `.ipa`, а не на устройство
-
-Определяющее — **что раздаёт сам Apple** (`.ipa` под FairPlay) и **кто раздаёт
-AGPL-байты**, а не то, окажутся ли они в итоге на устройстве:
-
-- AGPL **внутри `.ipa`** → получен под ограничениями Apple → **нарушение**.
-- AGPL **скачан с вашего сервера** → получен от вас под AGPL (исходники открыты,
-  §13 выполнен) → ограничения Apple на него **не** накладываются, даже если бандл
-  кэшируется в песочнице приложения.
-
-Следствие: **офлайн на iOS легально достижим** — если кэшированный бандл пришёл с
-вашего сервера, а не из `.ipa`. Ограничение тут не лицензионное, а в **ревью
-Apple** (см. §9.5).
-
-### 9.4. Варианты «грузить веб-клиент с сервера»
-
-**A. WebView навигируется на хостед-клиент (`server.url`).** Capacitor умеет
-`server: { url: 'https://app.example.com' }` — оболочка грузит WebView с удалённого
-URL, мост и нативные плагины по-прежнему инжектятся. В `.ipa` — ноль AGPL.
-
-- Плюс: лицензионно самый чистый; **origin = ваш домен**, поэтому cookie/CORS
-  работают как в браузере (боль `capacitor://localhost` ↔ API из §6 исчезает —
-  токен в body/Keychain может и не понадобиться).
-- Минус: холодный старт требует сети; сервер лёг → приложение кирпич; офлайна по
-  умолчанию нет.
-
-**B. OTA: пустой шелл скачивает и кэширует бандл.** Шелл при первом запуске тянет
-JS-бандл с вашего сервера и кэширует как веб-ассеты (механизм Cordova/CodePush).
-Open-source self-host-вариант — `@capgo/capacitor-updater` (важно для AGPL-проекта:
-без привязки к проприетарному Appflow).
-
-- Плюс: **даёт офлайн** — кэш AGPL легален, т.к. распространён вами, а не Apple.
-- Минус: упирается в политику Apple по hot-update (§9.5).
-
-**Не-обходы (мифы):** «никто не засудит» — это нарушение, а не обход; «LGPL-нуть
-обёртку» — не помогает (проблема в AGPL-веб-клиенте, а не в обёртке); «mere
-aggregation» — не катит: зашитый бандл это комбинированное распространяемое
-произведение, а не простая агрегация.
-
-### 9.5. Гейты Apple
-
-| # | Guideline | Суть | Влияние |
-|---|---|---|---|
-| 1 | **2.5.2** (исполняемый код) | Скачивать/исполнять **нативный** код нельзя, **но** есть исключение для скриптов, исполняемых встроенным WebKit/JavascriptCore, если они не меняют назначение приложения | Загрузка веб-клиента в `WKWebView` под исключение попадает: вариант A — чистый, B — терпимый, но с границами |
-| 2 | **4.2** (minimum functionality) | Чистый WebView-«просто сайт» рискует отклонением | Лечится нативной ценностью в оболочке (push/APNs, биометрия, share, файлы — ваш нативный код, не AGPL) |
-| 3 | конфликт двух гейтов | «Лицензионно чистый» вариант (пустой шелл качает всё) — самый рискованный для ревью; «безопасный для ревью» (зашить веб-билд в `.ipa`) — лицензионное нарушение | **Совместить (офлайн) + (чистая AGPL) + (низкий риск ревью) в одной конфигурации нельзя — выбираете любые два** |
-
-Безопасность: раз исполняете удалённый код — только HTTPS, желательно cert-pinning
-(подмена сервера = произвольный JS в WebView пользователя).
-
-### 9.6. Итоговая матрица распространения iOS
-
-| Конфигурация | AGPL-чистота | Офлайн | Риск ревью Apple |
-|---|---|---|---|
-| A. `server.url` на хостед-клиент | ✅ чистая | ❌ нет | средний (4.2, лечится плагинами) |
-| B. OTA пустой шелл + кэш бандла | ✅ чистая | ✅ есть | выше (2.5.2 + 4.2) |
-| Зашить веб-билд в `.ipa` (обычный Capacitor) | ❌ нарушение | ✅ | низкий |
-| **PWA** | ✅ чистая | ✅ | App Store не нужен |
-| Sideload / EU DMA-маркетплейсы (iOS 17.4+) | ✅ чистая | ✅ | вне App Store; **только ЕС** |
-
-**Вывод:** для iOS **PWA** — самое дешёвое решение, закрывающее всё сразу. Если
-присутствие именно в App Store критично — **вариант A** (`server.url` + нативные
-плагины под 4.2) легальный и реалистичный ценой «онлайн для холодного старта».
-Офлайн в App Store (вариант B) технически и лицензионно возможен, но это
-максимальный риск на ревью — закладывать только если офлайн на iOS обязателен.
-Совместить «App Store + зашитый офлайн AGPL» легально нельзя, пока копирайт не ваш.
-
----
-
-## 10. Оффлайн в будущем
-
-Оффлайн сейчас не требуется, но позиция хорошая:
-
-- Тело документа уже редактируется через Yjs (CRDT) + `y-indexeddb` — локальная
-  копия и автослияние правок работают, в том числе в WebView.
-- «Полностью онлайн» — это всё вокруг тела (навигация, заголовки, комментарии,
-  CRUD, вложения, авторизация). Их оффлайн-синхронизация описана отдельным
-  планом с этапами M0…M4 — см. [offline-sync-plan.md](offline-sync-plan.md).
-- Мобильное приложение **переиспользует** этот план, а не строит оффлайн заново.
-  Нюанс Android: System WebView под нехваткой места может чистить хранилище →
-  для оффлайна, возможно, понадобится дублировать критичные данные в нативное
-  хранилище, чтобы локальные копии не вычищались.
-
----
-
-## 11. Открытые вопросы (зафиксировать до старта)
-
-- **Q1.** Путь: Capacitor (B) с эволюцией в гибрид, или сразу React Native (C)?
-  Рекомендация — B.
-- **Q2.** Мобильная авторизация: отдельный логин-флоу с токеном в body + Keychain/
-  Keystore + Bearer (рекомендуется) или попытка работать через cookie в WebView?
-- **Q3.** Push: APNs + FCM сразу или iOS-first?
-- **Q4.** Подключать ли OpenAPI/Swagger для генерации мобильного клиента?
-- **Q5.** Когда включать оффлайн (M0…M4 из offline-sync-plan.md) относительно
-  первого мобильного релиза?
-- **Q6.** iOS-дистрибуция при AGPL (§9): App Store через `server.url`
-  (онлайн-клиент, без зашитого AGPL), PWA или sideload/EU-маркетплейсы? Этот
-  лицензионный путь нужно подтвердить **до** кода обёртки. Рекомендация — PWA для
-  iOS, Capacitor для Android.
-
----
-
-## 12. Чеклист первого шага (бутстрап Capacitor, iOS-first)
-
-- [ ] **Закрыть лицензионный путь iOS (§9) ДО кода обёртки:** выбрать
-      `server.url` / PWA / sideload и подтвердить у разбирающегося в лицензиях.
-- [ ] **Не бандлить AGPL-веб-клиент в iOS `.ipa`** (DRM/usage-rules App Store ⟂
-      AGPLv3 §10) — на iOS грузить клиент с сервера или идти через PWA.
-- [ ] Прогнать существующий адаптивный UI как PWA/в WebView, отловить отличия
-      (жесты, IME в редакторе, safe-area).
-- [ ] Добавить Capacitor в монорепо, нацелить на веб-билд `apps/client`
-      (Android — зашитый билд; iOS — `server.url`/PWA без зашитого AGPL, см. §9).
-- [ ] `npx cap add ios` (Android — `npx cap add android`, когда будет готова обвязка).
-- [ ] Бэкенд: мобильный логин-флоу с токеном в body; хранить токен в Keychain/
-      Keystore; слать `Authorization: Bearer`.
-- [ ] Бэкенд: явный CORS-whitelist под мобильные origin'ы.
-- [ ] Native-плагины под App Store 4.2: push, биометрия, share, файлы.
-- [ ] Push: APNs (iOS); FCM добавить вместе с Android.
-- [ ] Проверить вебсокет коллаборации из WebView (`/auth/collab-token` + Hocuspocus).
-- [ ] (Опционально) Подключить `@nestjs/swagger`.

docs/multi-cursor-editing-plan.md

@@ -1,205 +0,0 @@
-# Множественные курсоры (multi-cursor editing) — анализ и подходы
-
-> Статус: **черновик / обсуждение**. Код не пишется; цель этого документа — зафиксировать архитектурный вердикт, развилку подходов и рекомендацию.
->
-> Важное уточнение термина: речь про **несколько собственных курсоров одного пользователя в одном документе** (как в VS Code: `Alt+Click` добавить курсор, `Ctrl/Cmd+D` — следующее вхождение, `Ctrl/Cmd+Shift+L` — все вхождения), чтобы править несколько мест одновременно. **Не** про collaborative-курсоры соавторов — те в проекте уже работают (`CollaborationCaret` + Hocuspocus awareness).
->
-> Зафиксированные выводы (см. разделы ниже):
-> - Полноценный VS Code-style multi-cursor нельзя «включить флагом»: движок редактора (ProseMirror) хранит в состоянии **ровно одно выделение**, в отличие от Monaco/CodeMirror с массивом selections. Готового production-пакета в экосистеме Tiptap/ProseMirror нет.
-> - ~80% пользовательской ценности даёт ограниченный MVP («выделить все вхождения + одновременный ввод»), который опирается на **уже работающий** в проекте механизм `replaceAll` из расширения `SearchAndReplace`.
-> - Рекомендация: реализовать MVP (Вариант A); полноценный набор (Вариант B) — отдельный большой эпик, имеет смысл браться только если MVP окажется недостаточно.
-
-## 0. О чём речь (и о чём НЕ речь)
-
-**Что хочется** — несколько кареток в одном документе; набранный текст и `Backspace`/`Delete` применяются ко всем позициям одновременно; одно `Cmd/Ctrl+Z` откатывает всю мульти-правку целиком. Сценарии из VS Code:
-
-| Действие | Горячая клавиша | Суть |
-| --- | --- | --- |
-| Добавить курсор | `Alt+Click` | Курсор в произвольной точке клика |
-| Добавить курсор строкой выше/ниже | `Ctrl/Cmd+Alt+↑/↓` | Копия курсора на соседней строке |
-| Выделить следующее вхождение | `Ctrl/Cmd+D` | Добавить к набору следующее вхождение слова |
-| Выделить все вхождения | `Ctrl/Cmd+Shift+L` | Все вхождения сразу |
-| Колонковое/блочное выделение | `Alt+drag` | Прямоугольник курсоров по строкам |
-
-**О чём НЕ речь** — collaborative-курсоры (видеть, где сейчас находится другой соавтор). Это в Gitmost уже есть и работает отдельно: `CollaborationCaret` в [extensions.ts](apps/client/src/features/editor/extensions/extensions.ts) подключается через `collabExtensions(...)`, а сервер Hocuspocus по умолчанию форвардит awareness. Этот документ её не касается.
-
-## 1. Архитектурный вердикт: почему это не «включить флаг»
-
-Редактор Gitmost — **Tiptap поверх ProseMirror** (`@tiptap/core` 3.20.4, `@tiptap/pm` 3.20.4). Принципиальное отличие от VS Code: Monaco/CodeMirror хранит **массив selections**, а ProseMirror хранит в `EditorState` **ровно один** `Selection`:
-
-```
-EditorState = { doc, selection: Selection /* единственное */, storedMarks, ... }
-```
-
-На этой единственной selection завязано в ProseMirror почти всё:
-- команды ввода (`insertText`, `insertContent`) работают с текущей `selection`;
-- обработчики `handleTextInput`, `handleKeyDown`, `handlePaste`, `handleDrop` получают одно выделение;
-- история (undo/redo) оперирует transactions с одним выделением;
-- **критично для нас** — синхронизация через y-prosemirror тоже опирается на единственную selection (свою «awareness-selection» отдельно, но не на локальный массив).
-
-Доказательства из первоисточников:
-- Tiptap issue [ueberdosis/tiptap#3370](https://github.com/ueberdosis/tiptap/issues/3370) «Multiple cursors per user» — открыт, официальной поддержки нет.
-- Ответ **marijnh** (автор ProseMirror) на [discuss.prosemirror.net](https://discuss.prosemirror.net/t/multi-cursor-editing-in-prosemirror-or-tiptap/8397): готовой реализации нет, но путь обозначен — **«кастомный подкласс `Selection`, по аналогии с `CellSelection` из `prosemirror-tables`, который умеет содержать несколько отдельных диапазонов»**.
-- Production-готового пакета multi-cursor для Tiptap/ProseMirror в npm **нет** — пилить с нуля.
-
-**Вывод:** полноценный multi-cursor — это R&D-проект против устройства движка, а не настройка. Но самый ценный сценарий («поправить повторяющиеся одинаковые куски сразу в нескольких местах») реализуем дёшево, потому что массовая правка в одном transaction у нас уже написана.
-
-## 2. Что уже есть в коде и переиспользуемо
-
-В проекте уже есть расширение [SearchAndReplace](packages/editor-ext/src/lib/search-and-replace/search-and-replace.ts) (в `editor-ext`, подключено и в клиентском редакторе). Это почти готовый фундамент для главного сценария multi-cursor:
-
-- [search-and-replace.ts:100-174](packages/editor-ext/src/lib/search-and-replace/search-and-replace.ts#L100-L174) — `processSearches` уже находит **все** вхождения терма и возвращает массив `results: Range[]` (диапазоны `from`/`to`).
-- [search-and-replace.ts:157-168](packages/editor-ext/src/lib/search-and-replace/search-and-replace.ts#L157-L168) — уже рисует `Decoration.inline` для **всех** совпадений одновременно (это переиспользуется для подсветки «активных» курсоров).
-- [search-and-replace.ts:213-246](packages/editor-ext/src/lib/search-and-replace/search-and-replace.ts#L213-L246) — `replaceAll` уже выполняет **массовую правку в одном transaction**, идя **с конца**, чтобы корректно учитывать сдвиг позиций после каждой вставки/удаления. Это ровно та механика, что нужна для одновременного ввода в несколько курсоров.
-
-```ts
-// search-and-replace.ts:213-246 — готовый эталон массового transaction
-const replaceAll = (replaceTerm, results, { tr, dispatch }) => {
-  // Process replacements in reverse order to avoid position shifting issues
-  for (let i = resultsCopy.length - 1; i >= 0; i -= 1) {
-    const { from, to } = resultsCopy[i];
-    // ... собрать marks, удалить старый текст, вставить новый
-    tr.delete(from, to);
-    if (replaceTerm) tr.insert(from, tr.doc.type.schema.text(replaceTerm, marks));
-  }
-  dispatch(tr); // одна транзакция → одна запись в истории (один undo)
-};
-```
-
-То есть самая хитрая часть multi-cursor — применить правку к N позициям за один `tr` с корректным маппингом — у нас **уже работает** в `replaceAll`.
-
-Дополнительно в клиенте уже есть инфраструктура для горячих клавиш: в [page-editor.tsx:258-280](apps/client/src/features/editor/page-editor.tsx#L258-L280) есть блок `handleDOMEvents.keydown`, и используется утилита `platformModifierKey` (Cmd на macOS, Ctrl на других ОС — ровно то, что нужно для совместимых с VS Code шорткатов).
-
-## 3. Развилка: три подхода
-
-### 3.1 Вариант A — MVP: «выделить все вхождения + одновременный ввод» (рекомендация)
-
-Реализует главный сценарий из VS Code:
-- `Ctrl/Cmd+Shift+L` — берём слово под курсором (или текущее выделение), находим все вхождения, превращаем их в «активные курсоры»;
-- `Ctrl/Cmd+D` — добавить следующее вхождение к набору;
-- дальнейший ввод текста и `Backspace`/`Delete` применяются ко всем позициям одновременно через один transaction (копия механики `replaceAll`);
-- `Esc` — выйти из multi-cursor (один курсор).
-
-**Что переиспользуется:** массив `results` и логика массового `tr` берутся из [SearchAndReplace](packages/editor-ext/src/lib/search-and-replace/search-and-replace.ts) почти готовыми.
-
-**Визуальные каретки:** через `Decoration.widget(pos, () => cursorDomElement)` — ProseMirror умеет «из коробки»; для диапазонов — `Decoration.inline`.
-
-**Объём работы:** средний. Один новый Tiptap-extension в `packages/editor-ext/src/lib/multi-cursor/` + wiring в клиентском редакторе + горячие клавиши + CSS + юнит-тесты.
-
-**Риски:** средние и ограниченные. Скоуп узкий (только текстовые вхождения), сценарии предсказуемые, тестируются конечным числом кейсов.
-
-### 3.2 Вариант B — полноценный multi-cursor (как Monaco)
-
-Полный набор из §0: `Alt+Click` (произвольная точка), `Alt+drag` (колонковое выделение), `Ctrl/Cmd+Alt+↑/↓` (курсор на соседней строке), а также произвольный набор **несвязанных** курсоров (не по вхождениям).
-
-**Путь:** кастомный `MultiSelection extends Selection` (по подсказке мейнтейнера ProseMirror, по образцу `CellSelection` из `prosemirror-tables`), плюс **полная маршрутизация ввода**:
-- перехват `handleTextInput`, `handleKeyDown` (Backspace/Delete/стрелки/Enter/Home/End), `handlePaste`, `handleDrop`;
-- построение одного мульти-position transaction для каждого события;
-- визуальный рендер нескольких кареток и диапазонов;
-- undo-группировка (одно `Cmd/Ctrl+Z` откатывает все позиции разом);
-- перемапливание позиций курсоров при **любых** изменениях документа, включая remote Yjs-правки.
-
-**Объём работы:** очень большой (многие недели). Готового референса в экосистеме нет — это самостоятельный R&D с отладкой на реальном контенте.
-
-**Риски:** высокие — см. риск-карту в §4 (IME/composition, конфликты со сложными нодами вроде таблиц и code-блоков, взаимодействие с коллаборацией).
-
-### 3.3 Вариант C — эмуляция через коллаборацию (отбрасываем)
-
-Идея из Tiptap#3370: «проигрывать правки через отдельного pseudo-user через collaborative-слой». **Не берём:** ломает provenance правок (в проекте есть бейдж авторства «AI agent» в истории страницы, migration `20260616T130000-agent-provenance` — такой хак его загрязнит и запутает), портит историю undo, концептуально криво и хрупко.
-
-### Сводка
-
-| | Вариант A (MVP) | Вариант B (full) | Вариант C |
-| --- | --- | --- | --- |
-| Сценарии | «все вхождения», «+следующее вхождение» | полный набор VS Code | — |
-| База | готовый `replaceAll` | кастомный `Selection` с нуля | collaborative-слой |
-| Объём | средний | очень большой | — |
-| Риск | средний (ограниченный) | высокий | высокий |
-| Рекомендация | **да** | только если A мало | нет |
-
-## 4. Риск-карта
-
-Для обоих вариантов, но в варианте B каждый пункт — сильно жёстче.
-
-| Зона | Суть | Где больнее |
-| --- | --- | --- |
-| **Undo/redo** | Мульти-правка должна быть **одной** записью истории (одно `Cmd/Ctrl+Z` откатывает все позиции). Группировка через мету истории, см. как `replaceAll` делает один `dispatch(tr)`. | B |
-| **Коллаборация (Yjs)** | Пока активны ваши курсоры, может прилететь remote-правка — позиции курсоров надо перемапливать через `tr.mapping.map(pos)`. Один локальный `tr` с правками в N местах Yjs переварит нормально (это несколько правок в одном Update). | B |
-| **IME / dead keys** | Ввод через composition (буквы с акцентами, CJK) одновременно в несколько курсоров — крайне хрупко; для MVP (Вариант A) проще: на время composition можно схлопывать к одному курсору. | B |
-| **Schema / сложные узлы** | Курсор внутри code-блока + курсор в заголовке: одна и та же вставка может нарушить schema одного узла, но не другого. Нужно gracefully skip конфликтующие курсоры (не ронять весь `tr`). | B (A — почти не касается, т.к. вхождения — текстовые) |
-| **Таблицы / callouts** | `CellSelection`-подобная логика внутри таблиц — отдельная вселенная; в MVP курсоры в таблицах можно просто не поддерживать (как и в `replaceAll`). | B |
-| **Производительность** | Очень много курсоров → большой `DecorationSet` и длинный `tr`. Практически редко > нескольких десятков, но заложить верхнюю границу. | общий |
-
-## 5. Рекомендация
-
-**Брать Вариант A.** Он закрывает главный use-case («быстро поправить повторяющиеся одинаковые куски сразу в нескольких местах»), опирается на **уже работающий** `replaceAll`-механизм, и риск ограничен. Вариант B имеет смысл отдельным эпиком — только если A окажется недостаточно и будет устойчивый спрос на произвольные курсоры; тогда начинать стоит с прототипа кастомного `MultiSelection`, чтобы доказать жизнеспособность на сложных узлах до полной реализации.
-
-Сознательные границы MVP (Вариант A) — см. §6.7.
-
-## 6. План реализации Варианта A (MVP) — по шагам
-
-### 6.1. Новый extension
-
-Создать `packages/editor-ext/src/lib/multi-cursor/multi-cursor.ts` — Tiptap `Extension`:
-- плагин (ProseMirror `Plugin`) со state = `{ cursors: {from: number, to: number}[] }` и `DecorationSet` (виджеты-каретки для точечных курсоров + `Decoration.inline` для диапазонов);
-- команды:
-  - `selectAllOccurrences` — берёт слово под курсором (или текущее выделение), находит все вхождения (можно вынести общую с search-and-replace логику поиска в утилиту, чтобы не дублировать `processSearches`), заполняет `cursors`;
-  - `addNextOccurrence` (`Ctrl/Cmd+D`) — добавляет следующее вхождение к `cursors`;
-  - `exitMultiCursor` — очищает `cursors` (также вешается на `Esc`);
-- обработчики в `props`:
-  - `handleTextInput(view, from, to, text)` — если `cursors` непустой, строит один `tr`, вставляя `text` в каждую позицию **с конца** (копия механики из [search-and-replace.ts:213-246](packages/editor-ext/src/lib/search-and-replace/search-and-replace.ts#L213-L246));
-  - `handleKeyDown` — `Backspace`/`Delete` аналогично (удаление символа перед/после каждой позиции);
-  - игнорировать/схлопнуть multi-cursor при начале composition (IME) — см. §4.
-
-### 6.2. Маппинг позиций при изменениях документа
-
-В `state.apply` плагина — при любом `docChanged` перемапливать все позиции через `tr.mapping.map(pos)` и удалять «схлопнувшиеся» (`from === to` после маппинга — это нормально для каретки). Это покрывает и собственные правки, и **remote Yjs-правки** (y-prosemirror применяет их как обычные transactions — маппинг работает одинаково).
-
-### 6.3. Горячие клавиши
-
-Добавить в существующий блок [page-editor.tsx:258-280](apps/client/src/features/editor/page-editor.tsx#L258-L280) (там уже есть `platformModifierKey`):
-- `platformModifierKey + Shift + KeyL` → `selectAllOccurrences`;
-- `platformModifierKey + KeyD` → `addNextOccurrence`;
-- `Escape` → `exitMultiCursor`.
-
-⚠️ Проверить конфликт `Ctrl/Cmd+D` с браузерным «добавить в закладки» (предотвратить через `event.preventDefault()`) и с любыми существующими биндингами редактора.
-
-### 6.4. Регистрация
-
-- экспортировать расширение из `packages/editor-ext/src/lib/multi-cursor/index.ts` и добавить в `packages/editor-ext/src/index.ts`;
-- включить в `mainExtensions` в [extensions.ts](apps/client/src/features/editor/extensions/extensions.ts) (оно не зависит от коллаборации, поэтому идёт в основной набор, доступный и в обычном, и в коллаборативном редакторе).
-
-### 6.5. CSS
-
-Рядом с [collaboration.css](apps/client/src/features/editor/styles/collaboration.css) (и подключением через `styles/index.css`) — стили для классов вроде `.multi-cursor__caret` и `.multi-cursor__label`. Визуально отличать от collaborative-кареток (например, другим стилем/цветом), чтобы не путать свои мульти-курсоры с курсорами соавторов.
-
-### 6.6. Тесты
-
-Unit-тесты в `packages/editor-ext` (по образцу существующих там тестов) на:
-- корректность массового `tr` (ввод/удаление в N позициях, проверка результирующего документа);
-- маппинг позиций после локальной правки и после имитированной remote-правки;
-- граничные случаи: курсоры на границах узлов, схлопывание, пустой набор.
-
-### 6.7. Скоуп v1 / что сознательно НЕ входит
-
-Чтобы держать риск в пределах, в MVP **не делаем** (явно фиксируем как out-of-scope):
-- `Alt+Click` (произвольная точка) и `Alt+drag` (колонковое выделение) — это путь в Вариант B;
-- `Ctrl/Cmd+Alt+↑/↓` (курсор на соседней строке) — то же;
-- курсоры внутри таблиц, code-блоков и callouts — только обычный текст (как в `replaceAll`);
-- одновременный ввод через IME в несколько позиций (на время composition схлопываем к одному курсору);
-- курсоры, затрагивающие разные schema-узлы одновременно (если вставка нарушает schema в одной из позиций — пропускаем эту позицию, не роняем весь `tr`).
-
-Эти границы — кандидаты на v2 / переход к Варианту B.
-
-## 7. Открытые вопросы
-
-1. **Выделение диапазонов vs точечные курсоры.** В VS Code `Ctrl/Cmd+Shift+L` выделяет целые слова (диапазоны). Делаем ли мы в MVP то же (диапазоны + одновременная замена всего слова), или только точечные каретки после конца слова? Рекомендация: диапазоны — это даёт «переименовать все эти слова сразу», что и есть главная ценность.
-2. **Общая утилита поиска.** Вынести `processSearches` из search-and-replace в общую утилиту, чтобы не дублировать, или оставить независимую реализацию в multi-cursor? Рекомендация: вынести общую часть (поиск всех вхождений слова по документу), оба расширения используют её.
-3. **Граница производительности.** Ввести ли хард-кап на число одновременных курсоров (например, 100) с предупреждением пользователю? Рекомендация: да, как страховка.
-
-## 8. Источники
-
-- [Tiptap issue #3370 — Multiple cursors per user](https://github.com/ueberdosis/tiptap/issues/3370)
-- [discuss.ProseMirror — Multi-cursor editing in ProseMirror (ответ автора ProseMirror о кастомном подклассе Selection)](https://discuss.prosemirror.net/t/multi-cursor-editing-in-prosemirror-or-tiptap/8397)
-- `prosemirror-tables` / `CellSelection` — референс реализации «выделения из нескольких диапазонов» для Варианта B.
-- Внутренний код: [SearchAndReplace](packages/editor-ext/src/lib/search-and-replace/search-and-replace.ts) (эталон массового transaction), [page-editor.tsx](apps/client/src/features/editor/page-editor.tsx) (точки подключения горячих клавиш), [extensions.ts](apps/client/src/features/editor/extensions/extensions.ts) (регистрация расширений).

docs/offline-sync-plan.md

@@ -1,393 +0,0 @@
-# Offline-режим и синхронизация правок в gitmost
-
-> Статус: проектный документ, готов к реализации.
-> Контекст: gitmost — форк Docmost. Сейчас приложение полностью онлайн.
-> Цель: дать возможность работать оффлайн (читать и редактировать) и
-> синхронизироваться при возврате сети.
-
-Документ описывает текущее устройство, целевую архитектуру и пошаговый план
-реализации с привязкой к конкретным файлам. Его можно взять и реализовывать
-по этапам M0…M4.
-
----
-
-## 1. TL;DR
-
-1. **Половина оффлайна уже встроена.** Тело страницы редактируется через Yjs
-   (CRDT) + Hocuspocus, а на клиенте уже подключён `y-indexeddb`. Правки тела
-   *уже открытой* страницы переживают потерю сети и **сами мёржатся** при
-   реконнекте — без конфликтов.
-2. **«Полностью онлайн» — это всё вокруг тела документа:** загрузка самого
-   приложения, навигация (дерево/список), заголовки страниц, комментарии,
-   создание/перемещение/удаление страниц, вложения, авторизация.
-3. **Оффлайн делится на два контура с разными механизмами синхронизации:**
-   - **Контур A — тело документа:** CRDT (Yjs). Почти готов, нужно укрепить.
-   - **Контур B — структурные данные (REST):** не CRDT. Нужен паттерн
-     *локальный кэш + outbox (очередь мутаций) + правила разрешения конфликтов*.
-4. **PWA — обязательный фундамент, но это два слоя:**
-   - *Installability* (manifest + meta-теги) — **уже есть** в gitmost
-     (унаследовано от Docmost). Forkmost добавляет только косметику.
-   - *Service worker* (кэш app-shell, запуск без сети) — **нет нигде**, это и
-     есть реальная невыполненная часть. Без него установленное приложение без
-     сети покажет пустой экран.
-
----
-
-## 2. Текущее состояние (как есть)
-
-### 2.1. Контур A: тело документа — CRDT, почти готово
-
-| Где | Что делает |
-|---|---|
-| [page-editor.tsx](../apps/client/src/features/editor/page-editor.tsx) (L131–206) | На каждую страницу создаётся `Y.Doc`, к нему цепляются `IndexeddbPersistence("page.<id>")` (локальная копия) **и** `HocuspocusProvider` (WS-синк). |
-| [persistence.extension.ts](../apps/server/src/collaboration/extensions/persistence.extension.ts) | Сервер в `onStoreDocument` хранит в Postgres бинарный `ydoc` (Y state update) **плюс** отрендеренный tiptap-JSON `content` + `textContent`. В `onLoadDocument` поднимает `ydoc` обратно. |
-| [collaboration/extensions/redis-sync/](../apps/server/src/collaboration/extensions/redis-sync/) | Redis-синк для горизонтального масштабирования инстансов. |
-
-Почему это и есть оффлайн-редактирование: Yjs — CRDT, апдейты коммутативны.
-Пока клиент оффлайн, изменения копятся в `Y.Doc` и в IndexedDB; при возврате
-сети `HocuspocusProvider` обменивается state-векторами и **детерминированно
-сливает** правки. Конфликтов «кто кого перезаписал» в теле документа нет.
-
-### 2.2. Контур B: структурные данные — обычный REST, оффлайн недоступен
-
-| Сущность | Где | Механизм |
-|---|---|---|
-| Заголовок страницы | [title-editor.tsx](../apps/client/src/features/editor/title-editor.tsx) (L48–152) | REST `/pages/update`, дебаунс 500 мс. **НЕ Yjs.** |
-| CRUD страниц, move, restore | [page-service.ts](../apps/client/src/features/page/services/page-service.ts) | REST `/pages/*` |
-| Комментарии | [comment-service.ts](../apps/client/src/features/comment/services/comment-service.ts) | REST `/comments/*` |
-| Watchers, favorites, labels, дерево, поиск | соответствующие `features/*/services` | REST |
-
-Состояние клиента:
-- React Query: [main.tsx](../apps/client/src/main.tsx) (L26), `queryClient`
-  экспортируется, `retry:false`, `staleTime: 5 мин`. **Персистентности на диск
-  нет.** При перезагрузке без сети читать нечего.
-- HTTP: [api-client.ts](../apps/client/src/lib/api-client.ts) — axios `/api`,
-  `withCredentials`. На `401` → `redirectToLogin()`. **Важно для оффлайна:**
-  редирект на логин при сетевой ошибке недопустим (см. M4).
-
-### 2.3. PWA: что уже есть
-
-- [manifest.json](../apps/client/public/manifest.json) — присутствует
-  (`display: standalone`, иконки).
-- [index.html](../apps/client/index.html) (L9–16) — PWA meta-теги
-  (`apple-mobile-web-app-capable`, `mobile-web-app-capable`, `theme-color` и т.д.).
-- **Service worker отсутствует.** Нет `vite-plugin-pwa`, Workbox, precache.
-
-> Вывод по Forkmost (`Vito0912/forkmost`): их «PWA-наработки» — это только
-> манифест и meta-теги (closing issue Docmost #328 про *устанавливаемость*).
-> Service worker / оффлайн-кэша там нет. В gitmost installability уже есть,
-> поэтому из Forkmost переносить нечего, кроме косметики.
-
-### 2.4. Полезные примитивы, которые уже есть в проекте
-
-- **Fractional indexing для позиций страниц:**
-  [page.service.ts](../apps/server/src/core/page/services/page.service.ts)
-  использует `generateJitteredKeyBetween` из `fractional-indexing-jittered`.
-  Позиция — это строковый ключ (`position: string`), «jittered»-вариант
-  специально снижает коллизии при конкурентных/оффлайн-вставках. Это готовый
-  offline-friendly примитив для перемещений в дереве.
-- **Генерация ID:**
-  [nanoid.utils.ts](../apps/server/src/common/helpers/nanoid.utils.ts) —
-  `generateSlugId` (10 симв.) и `nanoIdGen`. ID можно генерировать на клиенте и
-  принимать на сервере (нужно для оффлайн-создания, см. M3).
-
----
-
-## 3. Целевая архитектура
-
-```
-                       ┌──────────────────────── Браузер (PWA) ────────────────────────┐
-                       │                                                                │
-   Тело документа      │   TipTap ⟷ Y.Doc ⟷ IndexeddbPersistence (локальная копия)      │
-   (Контур A, CRDT)    │                      │                                         │
-                       │                      └── HocuspocusProvider ──┐                │
-                       │                                               │                │
-   Структурные данные  │   React Query (read) ⟵ IndexedDB persister    │                │
-   (Контур B, REST)    │   Мутации ⟶ Outbox (IndexedDB) ──────────┐    │                │
-                       │                                          │    │                │
-   App shell           │   Service Worker (Workbox precache)      │    │                │
-                       └──────────────────────────────────────────┼────┼───────────────┘
-                                                                   │    │
-                                       (reconnect)                 ▼    ▼
-                       ┌──────────────────────── Сервер ───────────────────────────────┐
-                       │   REST API (idempotent upsert по client-id)   Hocuspocus (Yjs) │
-                       │            │                                        │           │
-                       │            └────────────── Postgres ───────────────┘           │
-                       └────────────────────────────────────────────────────────────────┘
-```
-
-Два независимых канала синхронизации:
-- **Контур A** синкается сам через Hocuspocus (Yjs). Руками конфликты не решаем.
-- **Контур B** синкается через outbox: оффлайн-мутации пишутся в журнал в
-  IndexedDB и проигрываются на сервер при реконнекте; конфликты решаются
-  явными правилами (LWW / per-entity).
-
----
-
-## 4. План реализации по этапам
-
-Этапы инкрементальны: каждый даёт пользователю ощутимый результат и может быть
-смёржен отдельно. Рекомендуемый порядок — строго M0 → M4.
-
-### M0 — PWA shell (фундамент: приложение запускается без сети)
-
-**Зачем:** без service worker установленное приложение без сети не загрузится.
-Это разблокирует всё остальное.
-
-**Что сделать:**
-1. Добавить `vite-plugin-pwa` (Workbox под капотом) в
-   [vite.config.ts](../apps/client/vite.config.ts).
-   - `registerType: 'autoUpdate'` или `prompt` (см. риск R3).
-   - `workbox.globPatterns` — прекэш JS/CSS/wasm/шрифтов/иконок.
-   - `manifest: false` или генерация из существующего
-     [manifest.json](../apps/client/public/manifest.json) (не дублировать).
-   - Навигационный fallback на `index.html` для SPA-роутов.
-   - Runtime caching: `CacheFirst` для статики, **`NetworkOnly` для `/api/**`
-     и `/collab`** на этом этапе (REST-кэш появится в M2; SW не должен молча
-     отдавать устаревшие ответы API).
-2. Зарегистрировать SW в [main.tsx](../apps/client/src/main.tsx)
-   (`registerSW` из `virtual:pwa-register`).
-3. Перенести косметику манифеста/метатегов из Forkmost при желании (бренд,
-   `orientation`, `msapplication-*`). Опционально, на оффлайн не влияет.
-
-**Файлы:** `apps/client/vite.config.ts`, `apps/client/src/main.tsx`,
-`apps/client/public/manifest.json`, `apps/client/index.html`.
-
-**Критерий приёмки:** приложение устанавливается, после первой загрузки
-открывается **без сети** (виден shell/лэйаут, а не пустой экран);
-обновление версии SW не ломает открытую сессию.
-
-**Риск:** низкий. Изолированный слой, кода приложения не трогает.
-
----
-
-### M1 — Укрепление оффлайна тела документа (Контур A)
-
-**Зачем:** убрать известные грабли Yjs и сделать поведение предсказуемым.
-
-**Что сделать:**
-1. **Закрыть ловушку «rebuild ydoc из JSON».** В
-   [persistence.extension.ts](../apps/server/src/collaboration/extensions/persistence.extension.ts)
-   `onLoadDocument` при пустом `page.ydoc` пересобирает документ из
-   `page.content` через `TiptapTransformer.toYdoc(...)`. Если это сработает,
-   пока оффлайн-клиент держит свой `Y.Doc` со своими client-id, при мёрже
-   возможно **дублирование контента** (классическая Yjs-ловушка).
-   - Гарантировать, что `ydoc` всегда персистится (после первого сохранения он
-     есть) и ветка rebuild не выполняется для страниц, у которых живут
-     оффлайн-клиенты. Минимум — единожды мигрировать `content → ydoc` для всех
-     страниц и далее считать `ydoc` единственным источником правды для тела.
-2. **Индикатор оффлайна/синка в UI.** Уже есть `yjsConnectionStatusAtom` и
-   `isLocalSynced/isRemoteSynced` в
-   [page-editor.tsx](../apps/client/src/features/editor/page-editor.tsx).
-   Показать состояние («оффлайн», «есть несинхронизированные правки»,
-   «синхронизировано»).
-3. **Заголовок страницы → в Yjs (рекомендуется).**
-   [title-editor.tsx](../apps/client/src/features/editor/title-editor.tsx)
-   сохраняет заголовок REST-ом (дебаунс 500 мс) — оффлайн это не работает и
-   расходится с телом. Варианты:
-   - (a) перенести заголовок в тот же `Y.Doc` (чистое CRDT-решение), либо
-   - (b) тащить заголовок через outbox из M3 (LWW). Решение зафиксировать
-     до старта M3 (см. открытый вопрос Q1).
-
-**Файлы:** `apps/server/src/collaboration/extensions/persistence.extension.ts`,
-`apps/client/src/features/editor/page-editor.tsx`,
-`apps/client/src/features/editor/title-editor.tsx` (если вариант a).
-
-**Критерий приёмки:** правки тела уже открытой страницы, сделанные оффлайн,
-после реконнекта появляются на сервере и у других клиентов без дублей и потерь;
-в UI виден статус синка.
-
-**Риск:** средний (Yjs-семантика, миграция `content → ydoc`).
-
----
-
-### M2 — Оффлайн-чтение и навигация (Контур B, read-path)
-
-**Зачем:** оффлайн нужно видеть дерево, список и метаданные, иначе некуда
-переходить; и нужно префетчить страницы «на оффлайн».
-
-**Что сделать:**
-1. **Персист React Query на диск.** Обернуть экспортируемый `queryClient` из
-   [main.tsx](../apps/client/src/main.tsx) в
-   `PersistQueryClientProvider` с IndexedDB-persister
-   (`@tanstack/query-persist-client-core` + idb-хранилище).
-   - Кэшировать: дерево пространства, список страниц, метаданные страницы,
-     комментарии. Выставить разумный `maxAge`/`gcTime`.
-   - Версионировать кэш (`buster`) по версии приложения, чтобы не «залипал»
-     после деплоя.
-2. **«Сделать доступным оффлайн».** Действие для пространства/ветки: префетч
-   метаданных **и** прогрев `IndexeddbPersistence` для тел страниц (открыть/
-   подгрузить `ydoc` каждой целевой страницы заранее), т.к. сейчас локально
-   лежат только *ранее открытые* страницы.
-3. **Runtime caching API в SW (read-only).** Для GET-эндпоинтов навигации —
-   `StaleWhileRevalidate`/`NetworkFirst` с фолбэком на кэш. Мутации (POST) —
-   по-прежнему мимо кэша (их берёт на себя M3).
-
-**Файлы:** `apps/client/src/main.tsx`, новый модуль
-`apps/client/src/lib/offline/` (persister, prefetch), точечно — хуки списков/
-дерева в `features/page/tree`.
-
-**Критерий приёмки:** после прогрева и ухода в оффлайн пользователь видит дерево
-и список, открывает заранее подготовленные страницы и читает их тело и
-комментарии.
-
-**Риск:** средний (консистентность кэша, инвалидция после деплоя).
-
----
-
-### M3 — Outbox для мутаций (Контур B, write-path) — ядро оффлайн-синка
-
-**Зачем:** дать оффлайн-создание/редактирование структурных данных с
-последующим проигрыванием на сервер.
-
-**Что сделать:**
-1. **Очередь мутаций (outbox) в IndexedDB.** Журнал операций
-   `{ id, entity, op, payload, clientId, baseVersion, createdAt, status }`.
-   Использовать **offline/paused mutations TanStack Query**
-   (`onlineManager` + `queryClient.resumePausedMutations()` + персист пауз),
-   либо отдельный модуль `apps/client/src/lib/offline/outbox.ts`.
-2. **Клиентская генерация ID.** Для оффлайн-создания страниц/комментариев
-   генерировать `id`/`slugId` на клиенте тем же алфавитом, что и
-   [nanoid.utils.ts](../apps/server/src/common/helpers/nanoid.utils.ts).
-   Для позиций в дереве — `generateJitteredKeyBetween` из
-   `fractional-indexing-jittered` (тот же пакет, что на сервере).
-3. **Идемпотентный upsert на сервере.** Эндпоинты `/pages/create`,
-   `/comments/create` и т.д. должны принимать клиентский `id` и быть
-   идемпотентными по нему (повторная отправка из очереди не должна плодить
-   дубликаты). Точки входа:
-   [page-service.ts](../apps/client/src/features/page/services/page-service.ts),
-   [comment-service.ts](../apps/client/src/features/comment/services/comment-service.ts)
-   и соответствующие контроллеры сервера.
-4. **Optimistic updates + откат.** Применять мутацию к кэшу сразу; при
-   неуспешном проигрывании после реконнекта — откат/пометка конфликта.
-5. **Правила разрешения конфликтов** (см. §5).
-6. **Проигрывание при реконнекте** в порядке `createdAt`, с экспоненциальным
-   backoff и идемпотентностью.
-
-**Файлы:** новый `apps/client/src/lib/offline/outbox.ts`, обёртки над
-`features/*/services/*`, серверные контроллеры/сервисы соответствующих
-сущностей (idempotent upsert).
-
-**Критерий приёмки:** оффлайн можно создать страницу, отредактировать заголовок,
-оставить комментарий, переместить страницу; после реконнекта всё появляется на
-сервере один раз (без дублей), конфликты разрешаются по заданным правилам.
-
-**Риск:** высокий (это самостоятельный класс багов синхронизации; требует
-серверных изменений и тестов на конфликты).
-
----
-
-### M4 — Вложения и оффлайн-авторизация
-
-**Что сделать:**
-1. **Вложения/картинки оффлайн.** Очередь загрузок: blob кладётся в локальный
-   кэш (Cache API/IndexedDB), в документ вставляется ссылка на локальный
-   ресурс; при реконнекте файл доуплоадивается, ссылка переписывается на
-   серверную. Точка входа — `features/attachments`.
-2. **Оффлайн-толерантная авторизация.** В
-   [api-client.ts](../apps/client/src/lib/api-client.ts) `401`/сетевые ошибки
-   **не должны** выкидывать на логин при отсутствии сети — отличать «нет сети»
-   от «реально разлогинен». Collab-токен (JWT с TTL,
-   [page-editor.tsx](../apps/client/src/features/editor/page-editor.tsx) L166–181)
-   оффлайн не обновить — синк должен просто ждать реконнекта, не ломая
-   локальную работу.
-
-**Критерий приёмки:** оффлайн-вставка картинки доезжает после реконнекта;
-протухший токен/нет сети не выкидывают пользователя из приложения и не теряют
-локальные правки.
-
-**Риск:** средний.
-
----
-
-## 5. Правила разрешения конфликтов (Контур B)
-
-CRDT здесь нет, правила задаём явно по типам сущностей:
-
-| Сущность | Стратегия |
-|---|---|
-| **Тело документа** | Yjs (CRDT) — руками ничего не решаем. |
-| **Комментарии** | Почти append-only. LWW по полю + дедуп по `clientId`. Простейший случай. |
-| **Метаданные страницы** (заголовок, иконка) | Last-Write-Wins по `updatedAt`. |
-| **Перемещение в дереве** | Самый сложный случай. Позиции — строковые fractional-ключи (`generateJitteredKeyBetween`), что снижает коллизии вставок. Нужен серверный реконсилер для «родитель удалён, а ребёнок перемещён» и конкурентных move: правило «удаление побеждает перемещение» (или наоборот — зафиксировать), плюс перегенерация позиции при коллизии. |
-| **Удаление vs правка** | Зафиксировать политику: правка удалённой сущности → конфликт в UI либо «удаление выигрывает». |
-
----
-
-## 6. Подводные камни (читать до старта)
-
-1. **Yjs rebuild из JSON → дубли.** Ветка `content → toYdoc` в
-   `onLoadDocument` опасна для долго-оффлайновых клиентов. Закрыть в M1.
-2. **Инвалидция кэша после деплоя.** Персист React Query и precache SW должны
-   версионироваться по версии приложения (`buster`/`globPatterns` хэши), иначе
-   пользователь застрянет на старом UI/данных.
-3. **Обновление service worker.** `autoUpdate` может перезагрузить вкладку с
-   несохранёнными правками. Для редактора предпочтительнее `prompt`-стратегия
-   (показать «доступно обновление», применить по согласию).
-4. **Идемпотентность обязательна.** Любая мутация из outbox может отправиться
-   повторно (реконнект/ретрай). Без серверного upsert по `clientId` — дубли.
-5. **Рост IndexedDB.** Прогрев тел страниц «на оффлайн» и кэш блобов могут
-   занять много места. Нужны лимиты/очистка (LRU).
-6. **Редирект на логин при сетевой ошибке.** Сейчас `401` → `redirectToLogin`.
-   Оффлайн это выкинет пользователя и потеряет контекст — чинить в M4.
-
----
-
-## 7. Зависимости (npm)
-
-| Пакет | Зачем | Этап |
-|---|---|---|
-| `vite-plugin-pwa` (+ Workbox) | SW, precache app-shell, генерация манифеста | M0 |
-| `@tanstack/query-persist-client-core` | Персист React Query на диск | M2 |
-| `idb` или `idb-keyval` | Обёртка над IndexedDB (persister/outbox/blob-кэш) | M2–M4 |
-| `fractional-indexing-jittered` | Клиентская генерация позиций (уже есть на сервере) | M3 |
-
-`yjs`, `y-indexeddb`, `@hocuspocus/provider` — **уже** в проекте, доустанавливать
-не нужно.
-
----
-
-## 8. Объём работ vs ценность (для приоритизации)
-
-| Уровень | Этапы | Что пользователь получает |
-|---|---|---|
-| **Минимальный** | M0 + M1 | Приложение грузится оффлайн; уже открытые страницы редактируются и синкаются (тело + заголовок). Навигация — только по закэшированному. |
-| **Средний** | + M2 + M3 | Оффлайн-навигация по подготовленным пространствам; оффлайн-создание страниц и комментариев с синком и LWW-конфликтами. |
-| **Полный** | + M4 (и при необходимости — переезд на синк-движок) | Вложения оффлайн, устойчивая авторизация. Полноценный local-first. |
-
-Прагматичный путь: довести **M0+M1** (это ~80% «редактирую то, что открыл»),
-затем M2/M3 инкрементально. Полный синк-движок (RxDB / ElectricSQL / PowerSync /
-Replicache / TanStack DB) рассматривать только если оффлайн станет ключевым
-сценарием продукта — это существенный рефакторинг данных и бэкенда.
-
----
-
-## 9. Открытые вопросы (зафиксировать до реализации)
-
-- **Q1.** Заголовок страницы: переносим в Yjs (M1, вариант a) или гоним через
-  outbox (M3, вариант b)? Рекомендация — (a), меньше конфликтных правил.
-- **Q2.** Политика конфликта «удаление vs правка»: «удаление выигрывает» или
-  явный конфликт в UI?
-- **Q3.** Стратегия обновления SW для редактора: `autoUpdate` или `prompt`?
-  Рекомендация — `prompt`.
-- **Q4.** Лимиты локального хранилища (сколько пространств/страниц/блобов
-  держать оффлайн, политика вытеснения).
-- **Q5.** Целимся в инкрементальный путь (M0…M4) или сразу в синк-движок (уровень
-  «полный»)? От этого зависит, переписывать ли REST-слой.
-
----
-
-## 10. Чеклист реализации
-
-- [ ] M0: `vite-plugin-pwa` подключён, SW регистрируется, app-shell в precache,
-      `/api` и `/collab` — `NetworkOnly`.
-- [ ] M0: приложение открывается без сети (shell виден).
-- [ ] M1: ветка rebuild ydoc из JSON обезврежена; миграция `content → ydoc`.
-- [ ] M1: индикатор статуса синка в UI.
-- [ ] M1: заголовок переведён в Yjs (или решение Q1 принято).
-- [ ] M2: React Query персистится в IndexedDB, кэш версионирован.
-- [ ] M2: действие «сделать доступным оффлайн» (метаданные + прогрев `ydoc`).
-- [ ] M3: outbox в IndexedDB, клиентские ID, идемпотентный upsert на сервере.
-- [ ] M3: optimistic updates + откат; правила конфликтов реализованы.
-- [ ] M4: очередь загрузки вложений + локальный blob-кэш.
-- [ ] M4: авторизация толерантна к оффлайну (нет редиректа на логин при отсутствии сети).

docs/streaming-dictation-plan.md

@@ -1,421 +0,0 @@
-# Потоковая диктовка (realtime STT) — дизайн
-
-> Статус: **черновик / дизайн**. Реализация ещё не начата.
-> Исходный кейс: при диктовке текст должен появляться **по мере речи**, а не одним
-> куском после остановки записи.
->
-> Принятые на старте предпосылки (требуют подтверждения, см. §3 «Развилки»):
-> - **Семантика** — настоящий realtime: аудио стримится во время речи, частичные
->   расшифровки (`delta`) дописываются в редактор немедленно (~150–300 мс до
->   первого частичного текста на проводном соединении).
-> - **Провайдер** — OpenAI Realtime API (или совместимый: Azure OpenAI). Это
->   ломает текущую провайдер-агностичность диктовки (см. §2) — realtime становится
->   **опциональной** возможностью поверх существующей пакетной диктовки, а не
->   заменой ей.
-
----
-
-## 1. Что есть сейчас (пакетная диктовка)
-
-Текущая диктовка — строго «запиши целиком → отправь → получи весь текст», без
-какого-либо стрима:
-
-**Клиент.**
-- [use-dictation.ts](../apps/client/src/features/dictation/hooks/use-dictation.ts) —
-  стейт-машина захвата на `MediaRecorder`. Чанки копятся в `chunksRef` в
-  `recorder.ondataavailable`, но **никуда не уходят по ходу записи**; единый `Blob`
-  собирается только в `recorder.onstop` и одним `multipart`-POST отправляется на
-  транскрипцию. Кодек — сжатый `audio/webm;codecs=opus` (Safari: `audio/mp4`).
-- [dictation-service.ts](../apps/client/src/features/dictation/services/dictation-service.ts) —
-  `transcribeAudio(blob, filename)` → `POST /ai-chat/transcribe`.
-- [mic-button.tsx](../apps/client/src/features/dictation/components/mic-button.tsx) —
-  кнопка с состояниями `idle → recording → transcribing → idle`.
-- [dictation-group.tsx](../apps/client/src/features/editor/components/fixed-toolbar/groups/dictation-group.tsx) —
-  снапшотит каретку в `onStart`, вставляет **готовый** текст в зафиксированную
-  позицию, клампит её под текущий размер документа (учёт коллаб-дрейфа).
-- В чате — тот же `MicButton` в [chat-input.tsx](../apps/client/src/features/ai-chat/components/chat-input.tsx),
-  текст дописывается в черновик сообщения.
-
-**Сервер.**
-- Эндпоинт `POST /ai-chat/transcribe` в
-  [ai-chat.controller.ts](../apps/server/src/core/ai-chat/ai-chat.controller.ts#L195-L281):
-  гейт `settings.ai.dictation === true` (иначе 403), приём файла до 25 МБ,
-  whitelist MIME, троттлинг 20 req/min на пользователя, маппинг MIME→`format`,
-  вызов `AiTranscriptionService.transcribe()`.
-- [ai-transcription.service.ts](../apps/server/src/core/ai-chat/ai-transcription.service.ts) —
-  тонкая обёртка над `AiService.transcribe()`.
-- [ai.service.ts](../apps/server/src/integrations/ai/ai.service.ts#L120-L187) —
-  два пути по `sttApiStyle`: `multipart` (AI SDK `experimental_transcribe`,
-  OpenAI/speaches/faster-whisper/Ollama) и `json` (base64 на
-  `{baseURL}/audio/transcriptions`, OpenRouter). Оба возвращают **весь текст за
-  один вызов**, без SSE/WS.
-- Конфиг STT — per-workspace в `settings.ai.provider` (`sttModel`, `sttBaseUrl`,
-  `sttApiStyle`), ключ зашифрован в `ai_provider_credentials`, расшифровывается
-  только в [ai-settings.service.ts](../apps/server/src/integrations/ai/ai-settings.service.ts#L113-L157)
-  (`resolve`) и **никогда не логируется и не уходит клиенту** (только маска
-  `hasSttApiKey`).
-
-**Вывод.** «По мере речи» в текущей архитектуре невозможно в принципе: текст
-рисуется одним куском в `onstop`. Нужен принципиально другой транспорт.
-
----
-
-## 2. Главное архитектурное противоречие
-
-Пакетная диктовка **провайдер-агностична**: работает с любым OpenAI-совместимым
-`/audio/transcriptions` (включая self-hosted speaches/faster-whisper и Ollama)
-просто через `sttBaseUrl` + `sttApiStyle`.
-
-Realtime STT — **не** часть OpenAI-совместимого REST. Это отдельный протокол
-(WebSocket/WebRTC + событийная модель), который реализуют единицы провайдеров:
-OpenAI Realtime, Azure OpenAI Realtime, и (с другим набором событий) пара сторонних
-вроде Together AI. Self-hosted whisper-серверы его, как правило, **не умеют**.
-
-Поэтому realtime нельзя «просто включить» вместо пакетной диктовки. Дизайн исходит
-из того, что:
-
-1. Пакетная диктовка (§1) **остаётся** как дефолт и фоллбэк.
-2. Realtime — **опциональная** возможность, доступная только когда workspace
-   настроен на realtime-совместимый провайдер (новый флаг/поле конфига, см. §5).
-3. Если realtime не настроен или соединение не поднялось — UI прозрачно
-   деградирует к пакетному пути.
-
----
-
-## 3. Контракт провайдера (OpenAI Realtime, transcription session)
-
-Сверено с актуальной документацией (ссылки в конце). Ключевые факты:
-
-**Создание сессии и эфемерный токен.**
-- REST `POST /v1/realtime/transcription_sessions` (в GA-вариантах —
-  `POST /v1/realtime/client_secrets` с телом-конфигом сессии) возвращает
-  `client_secret.value` — **эфемерный** токен с коротким TTL для браузера.
-  Постоянный ключ воркспейса при этом наружу не отдаётся.
-  > На момент реализации сверить точный эндпоинт и форму тела с текущими доками —
-  > API эволюционирует.
-
-**Транспорт.**
-- **WebRTC** — рекомендуется для браузерного аудио (захват + воспроизведение).
-- **WebSocket** — для серверных аудио-пайплайнов:
-  `wss://api.openai.com/v1/realtime?intent=transcription`, заголовки
-  `Authorization: Bearer <key>` и `OpenAI-Beta: realtime=v1`.
-
-**Формат входного аудио.** `pcm16` (raw 16-bit PCM, mono), частота 16 кГц или
-24 кГц; либо `g711`. **Не** webm/opus и **не** mp4 — то есть текущий
-`MediaRecorder`-путь для realtime неприменим (см. §6, AudioWorklet).
-
-**События клиент→сервер.**
-- `transcription_session.update` (или `session.update`) — конфиг модели/VAD/языка.
-- `input_audio_buffer.append` — чанк аудио (base64 PCM16).
-- `input_audio_buffer.commit` — закрыть сегмент вручную (когда VAD выключен).
-
-**События сервер→клиент.**
-- `conversation.item.input_audio_transcription.delta` — поле `delta` с
-  инкрементальным текстом (частичная расшифровка).
-- `conversation.item.input_audio_transcription.completed` — поле `transcript` с
-  финальным текстом сегмента. У обоих есть `item_id` для сопоставления сегментов.
-- `error` — ошибки сессии.
-
-**Turn detection / VAD.** `turn_detection: { type: "server_vad" }` —
-сервер сам нарезает речь на сегменты и эмитит `completed` на границе паузы; для
-непрерывной диктовки это удобнее ручного commit. Модели: `gpt-4o-transcribe`,
-`gpt-4o-mini-transcribe`, потоковая `gpt-realtime-whisper` (у неё настраиваемая
-задержка `delay`: `minimal…xhigh` — баланс «латентность ↔ качество»).
-
-> Важно: `delta`-события дают **черновой** текст, который последующие события
-> могут **переписать**. UI должен уметь заменять ранее показанный частичный текст
-> (см. §3 «Развилка B» про вставку в редактор).
-
----
-
-## 4. Развилка A — транспорт: прямое WebRTC vs серверный WS-прокси
-
-### Вариант A1 — браузер ↔ OpenAI напрямую (WebRTC, эфемерный токен)
-Наш сервер только минтит эфемерный токен (`/realtime/transcription_sessions`
-постоянным ключом воркспейса), браузер сам устанавливает WebRTC к OpenAI и
-получает `delta`/`completed`.
-
-- **Плюсы:** минимальная латентность (нет лишнего хопа), аудио не идёт через наш
-  сервер (нет нагрузки на bandwidth), меньше серверного кода.
-- **Минусы:**
-  - Работает **только** с настоящим OpenAI/Azure (нужна поддержка эфемерных
-    токенов и WebRTC) — `sttBaseUrl` на self-hosted/прокси-шлюз тут бесполезен.
-  - Браузер устанавливает соединение с внешним хостом напрямую — мимо нашего
-    [ssrf-guard](../apps/server/src/core/ai-chat/external-mcp/ssrf-guard.ts) и
-    серверного троттлинга/гейтинга на уровне каждого сообщения (гейт можно
-    проверить только в момент минтинга токена).
-  - Эфемерный токен живёт в браузере (короткий TTL смягчает, но это всё же
-    выдача наружу производного секрета).
-  - WebRTC в браузере (`RTCPeerConnection`, SDP-оффер, обмен через REST) — больше
-    клиентской машинерии и краевых случаев.
-
-### Вариант A2 (рекомендуется) — браузер ↔ наш сервер (WS) ↔ OpenAI (WS)
-Браузер шлёт PCM16-чанки по WebSocket на наш новый gateway; сервер держит upstream
-WS к `wss://api.openai.com/v1/realtime?intent=transcription` с **постоянным**
-ключом воркспейса и проксирует `delta`/`completed` обратно браузеру.
-
-- **Плюсы:**
-  - Ключ **никогда не покидает сервер** — ровно как в текущем коде
-    ([ai-settings.service.ts](../apps/server/src/integrations/ai/ai-settings.service.ts#L138-L154)),
-    эфемерные токены не нужны.
-  - Работает с **любым** realtime-совместимым эндпоинтом через `sttBaseUrl`
-    (OpenAI, Azure, будущий self-hosted), и upstream-URL проходит через
-    SSRF-валидацию перед коннектом.
-  - Гейт `settings.ai.dictation`, аутентификация (JWT воркспейса), троттлинг и
-    лимиты длительности/объёма применяются **на сервере** на каждом соединении.
-  - Совместимо с тем, что в проекте **уже есть WebSocket-инфраструктура** —
-    коллаб-сервер на Hocuspocus + Socket.IO-адаптер на Redis
-    ([collaboration/](../apps/server/src/collaboration/)), и Fastify-приложение.
-- **Минусы:**
-  - Аудио идёт через наш сервер (≈ десятки кбит/с на сессию для PCM16@24k ⇒
-    ~48 КБ/с; терпимо, но это нагрузка и нужно ограничивать конкуррентность).
-  - Двойной хоп добавляет немного латентности (доли сотни мс).
-  - Нужен новый WS-gateway и аккуратный proxy-стейт (бэкпрешер, очистка сокетов).
-
-**Решение (предлагается): A2.** Он единственный согласуется с инвариантами
-кодовой базы — «ключ только на сервере», провайдер-агностичность через `baseURL`,
-SSRF-guard, серверные гейты и троттлинг. A1 оставить как возможную оптимизацию
-латентности «потом», если упрёмся в bandwidth.
-
-Дальнейший дизайн исходит из **A2**.
-
----
-
-## 5. Развилка B — куда писать частичный текст в редакторе
-
-`delta` — черновой текст, который может быть переписан. Слепо вставлять каждую
-`delta` в документ Tiptap нельзя: (1) каждая правка документа порождает Yjs-апдейт,
-шумит в истории/коллабе и тяжела; (2) переписывание ранее показанного текста
-превращается в постоянные replace по диапазону.
-
-### Вариант B1 — провизорная вставка в документ + замена диапазона
-Вставляем `delta` прямо в документ, запоминаем диапазон провизорного текста,
-на каждую новую `delta`/`completed` заменяем этот диапазон. На `completed` —
-«фиксируем» (диапазон становится обычным текстом).
-
-- **Плюсы:** текст сразу «настоящий», работает для любого приёмника (редактор и
-  чат единообразно), не нужен слой декораций.
-- **Минусы:** активный коллаб + история засоряются промежуточными апдейтами;
-  замена диапазона воюет с коллаб-дрейфом (диапазон надо ремапить, как уже делает
-  [dictation-group.tsx](../apps/client/src/features/editor/components/fixed-toolbar/groups/dictation-group.tsx#L24-L26));
-  откат при отмене сложнее.
-
-### Вариант B2 (рекомендуется для редактора) — ProseMirror-декорация для interim, коммит только финала
-Частичный текст показываем виджет-декорацией (inline widget) у каретки — он **не
-часть документа**, не порождает Yjs-апдейтов и не попадает в историю. В документ
-коммитим только текст из `completed`-сегмента (как сейчас — `insertContentAt` в
-снапшот каретки, с тем же клампом под коллаб-дрейф).
-
-- **Плюсы:** ноль мусора в коллабе/истории до финала; отмена = просто снять
-  декорацию; финальная вставка переиспользует уже существующую и проверенную
-  логику `dictation-group`.
-- **Минусы:** нужна небольшая ProseMirror-плагин-декорация (новый код); «по мере
-  речи» виден interim как подсветка-призрак, а в документ «оседает» по сегментам
-  (на паузах VAD) — на практике это естественный UX (как у системных диктовок).
-
-### Для чата
-В [chat-input.tsx](../apps/client/src/features/ai-chat/components/chat-input.tsx)
-приёмник — обычный `textarea`/draft, декораций нет. Там проще **B1-подобно**:
-показывать `interim` как «хвост» черновика (например, отдельным стейтом, который
-рендерится приглушённо), а на `completed` дописывать в основной черновик. То есть
-интерфейс хука должен отдавать и `interim`, и `final` (см. §6).
-
-**Решение (предлагается):** редактор — **B2** (декорация + коммит финала), чат —
-показ interim-хвоста + коммит финала. Единый хук realtime отдаёт оба потока,
-а приёмник сам решает, как показывать interim.
-
----
-
-## 6. Детальный дизайн (A2 + B2)
-
-### 6.1 Клиент: захват аудио (PCM16 через Web Audio API)
-`MediaRecorder` отдаёт сжатый webm/opus — для realtime **не подходит**. Нужен
-сырой PCM16:
-
-1. `getUserMedia({ audio: true })` (как сейчас).
-2. `AudioContext` + `AudioWorkletNode` (новый worklet-процессор): забирает
-   Float32-фреймы, ресемплит к 24 кГц mono, конвертит в Int16, шлёт в основной
-   поток.
-3. Чанки PCM16 → base64 → событие `input_audio_buffer.append` на наш WS-gateway
-   (батчинг ~каждые 100–250 мс, чтобы не спамить сообщениями).
-4. На стоп — закрыть worklet, остановить треки (как в текущем `stopTracks`),
-   дослать остаток.
-
-Новый код, в идеале — отдельный хук `use-realtime-dictation.ts` рядом с
-[use-dictation.ts](../apps/client/src/features/dictation/hooks/use-dictation.ts),
-с тем же «фасадом» (`status/start/stop/cancel`) **плюс** колбэки `onInterim(text)`
-и `onFinal(text)`. `MicButton` выбирает реализацию (realtime vs batch) по флагу из
-конфига воркспейса; вся остальная обвязка (тултипы, состояния, обработка ошибок,
-гард двойного клика, очистка на unmount) переиспользуется один-в-один.
-
-> AudioWorklet требует безопасного контекста (HTTPS/localhost) — то же ограничение,
-> что уже есть у `getUserMedia` в текущем хуке. Нужен бандл worklet-файла через
-> Vite (`?url`/`?worker`); сверить с тем, как проект собирает воркеры.
-
-### 6.2 Сервер: WS-gateway + realtime-прокси
-Новый модуль внутри `core/ai-chat` (рядом с `ai-transcription.service.ts`):
-
-- **WS endpoint** (например, `ws://…/ai-chat/realtime-transcribe`). Поднять либо
-  как Nest WebSocketGateway, либо как Fastify-WS-роут — выбрать по тому, что уже
-  используется в проекте (Socket.IO-адаптер на Redis в
-  [collaboration/](../apps/server/src/collaboration/)). На коннекте:
-  - аутентификация JWT воркспейса (как у остальных `/ai-chat` маршрутов);
-  - гейт `settings.ai.dictation === true` (иначе закрыть с понятным кодом/причиной);
-  - троттлинг/лимит одновременных realtime-сессий на пользователя и на воркспейс
-    (realtime дороже пакетной диктовки — нужен явный потолок).
-- **Резолв конфига** через `AiSettingsService.resolve(workspaceId)`: нужны
-  `sttModel`, `sttBaseUrl||baseUrl`, `sttApiKey`. **До** коннекта прогнать
-  upstream-URL через [ssrf-guard](../apps/server/src/core/ai-chat/external-mcp/ssrf-guard.ts).
-- **Upstream WS** к `wss://<base>/realtime?intent=transcription` (npm `ws`),
-  заголовки `Authorization: Bearer <sttApiKey>` + `OpenAI-Beta: realtime=v1`.
-  Сразу отправить `transcription_session.update` с моделью/языком/`server_vad`.
-- **Прокси:** PCM16 от браузера → `input_audio_buffer.append` в upstream;
-  `…transcription.delta` / `…completed` / `error` из upstream → клиенту
-  (можно прозрачно ретранслировать, либо нормализовать в свой минимальный формат
-  `{type:'interim'|'final'|'error', text, itemId}` — предпочтительно
-  нормализовать, чтобы не привязывать клиент к сырой схеме OpenAI и упростить
-  будущую поддержку Azure/иных).
-- **Очистка:** при закрытии любого из двух сокетов — закрыть второй, освободить
-  ресурсы; таймаут простоя; лимит длительности сессии (аналог 120 с в текущем
-  хуке) и лимит суммарного объёма аудио.
-
-Расширить `AiService` (или новый `AiRealtimeService`) методом, инкапсулирующим
-upstream-WS, чтобы контроллер/gateway оставался тонким — симметрично текущему
-`transcribe()`.
-
-### 6.3 Конфиг воркспейса
-Добавить в [ai.types.ts](../apps/server/src/integrations/ai/ai.types.ts) и в
-[ai-settings.service.ts](../apps/server/src/integrations/ai/ai-settings.service.ts):
-- `sttRealtime?: boolean` — включает realtime-путь для воркспейса.
-- `sttRealtimeModel?: string` — модель realtime (например `gpt-4o-mini-transcribe`
-  / `gpt-realtime-whisper`); если пусто — фоллбэк на `sttModel`.
-- (опц.) `sttRealtimeBaseUrl?` — если realtime-эндпоинт отличается от `sttBaseUrl`.
-
-Ключ переиспользуется (`sttApiKey` → fallback `apiKey`), новых секретов не нужно.
-В `getMasked` отдавать новые **несекретные** поля; в `resolve` — как сейчас.
-UI настроек (Workspace settings → AI) — добавить тумблер «Realtime dictation» и
-поле модели рядом с существующими STT-полями; кнопка «Test endpoint» для realtime
-делает короткий тестовый коннект (открыть сессию, послать ~0.5 с тишины, дождаться
-`session.created`/`error`, закрыть) и возвращает `ok|error` через
-`describeProviderError`-подобную нормализацию.
-
-### 6.4 Клиентский конфиг-гейт
-Realtime-кнопку показывать только если `workspace.settings.ai.dictation === true`
-**и** `…ai.provider.sttRealtime === true`. Иначе — текущая пакетная кнопка. Маска
-настроек должна отдавать эти флаги клиенту (несекретные).
-
----
-
-## 7. Безопасность и соответствие конвенциям
-
-- **Ключ только на сервере** (вариант A2): постоянный ключ не уходит клиенту,
-  эфемерные токены не используются — инвариант
-  [§8 ai-settings](../apps/server/src/integrations/ai/ai-settings.service.ts#L38-L45)
-  сохранён. Ключ не логируется.
-- **SSRF:** upstream realtime-URL валидируется через
-  [ssrf-guard.ts](../apps/server/src/core/ai-chat/external-mcp/ssrf-guard.ts)
-  перед коннектом (особенно если разрешаем кастомный `sttRealtimeBaseUrl`).
-- **Гейт/авторизация/троттлинг** — на сервере, на каждом WS-коннекте; плюс жёсткий
-  лимит одновременных realtime-сессий (это дорого) и лимит длительности.
-- **Обработка ошибок (конвенция проекта).** Любая ошибка (upstream `error`,
-  разрыв сокета, провайдер-таймаут, не настроен realtime, отказ микрофона):
-  - на сервере — лог полностью (имя/сообщение/стек/`cause`, статус upstream) и
-    отдача клиенту **конкретной** причины (не «Something went wrong»), через
-    нормализатор уровня `describeProviderError`;
-  - на клиенте — `console.error(<context>, err)` + нотификация с реальной причиной
-    (как уже сделано в
-    [use-dictation.ts](../apps/client/src/features/dictation/hooks/use-dictation.ts#L187-L213)).
-- **Деградация:** realtime недоступен/упал на старте → молча используем пакетную
-  диктовку (она всегда есть); realtime упал в середине → коммитим уже полученные
-  `completed`-сегменты, показываем причину, предлагаем продолжить пакетно.
-
----
-
-## 8. Краевые случаи
-
-- **Коллаб-дрейф:** между `start` и каждым `completed` документ мог измениться —
-  ремап/кламп позиции вставки (логика уже есть в `dictation-group`); для interim
-  декорация привязывается к текущей каретке, не к абсолютной позиции.
-- **Отмена записи:** снять декорацию, ничего не коммитить, закрыть оба сокета.
-- **Тишина/нет речи:** VAD не эмитит сегментов — корректно завершить без вставки.
-- **Длинная диктовка:** server_vad нарезает на сегменты автоматически; следить за
-  лимитом длительности и объёма.
-- **Переписывание interim:** поздние `delta` правят ранние — UI всегда показывает
-  последнюю версию текущего (ещё не `completed`) сегмента.
-- **Языки/пунктуация:** прокидывать `language` в конфиг сессии (или авто);
-  модель сама расставляет пунктуацию.
-- **Несколько вкладок / двойной старт:** гард как в текущем хуке + серверный лимит
-  сессий.
-- **Старые браузеры без AudioWorklet:** фоллбэк на пакетную диктовку.
-
----
-
-## 9. Поэтапный план реализации
-
-1. **Конфиг и гейт.** `ai.types.ts` + `ai-settings.service.ts` (`sttRealtime`,
-   `sttRealtimeModel`), маска, UI-тумблер и «Test endpoint». Без транспорта —
-   просто читается/пишется.
-2. **Серверный realtime-прокси.** WS-gateway + `AiRealtimeService` (upstream WS к
-   OpenAI, SSRF, гейт, троттлинг, нормализация событий, очистка). Покрыть
-   юнит/моками парс событий и закрытие сокетов.
-3. **Клиентский захват PCM16.** AudioWorklet-процессор + `use-realtime-dictation`
-   (фасад `status/start/stop/cancel` + `onInterim/onFinal`), подключение к WS.
-4. **UI interim.** B2-декорация в редакторе + коммит финала через существующую
-   `dictation-group`-логику; в чате — interim-хвост + коммит. Переключение
-   realtime/batch в `MicButton` по флагу конфига.
-5. **Закалка.** Лимиты, таймауты, фоллбэки, нотификации с реальными причинами,
-   нагрузочная проверка одновременных сессий.
-
----
-
-## 10. Открытые вопросы / риски
-
-- **Подтвердить семантику** (предпосылки в шапке): нужен именно realtime «по мере
-  речи» (A2/B2), а не просто «прогрессивный вывод после стопа» (`stream:true` на
-  `gpt-4o-transcribe` — гораздо дешевле и проще, но текст идёт только **после**
-  остановки записи).
-- **Точная форма Realtime API** (эндпоинт сессии, имена событий, формат аудио)
-  меняется — сверить с актуальными доками на момент реализации.
-- **Стоимость/латентность** realtime заметно выше пакетной диктовки — нужен явный
-  потолок одновременных сессий и, возможно, явное предупреждение админу.
-- **Нагрузка на наш сервер** (аудио через прокси) — измерить на реальной
-  конкуррентности; при необходимости позднее добавить путь A1 (WebRTC напрямую).
-- **AudioWorklet-бандлинг** под Vite — проверить, как проект собирает воркеры.
-- Совместимость с Azure OpenAI Realtime (другой хост/версия API) — учесть в
-  нормализации событий, чтобы клиент не зависел от сырой схемы.
-
----
-
-## 11. Ориентир по затрагиваемым файлам
-
-Новые:
-- `apps/client/src/features/dictation/hooks/use-realtime-dictation.ts`
-- `apps/client/src/features/dictation/audio/pcm16-worklet.*` (worklet + загрузчик)
-- `apps/client/src/features/editor/.../dictation-interim-decoration.*` (ProseMirror-плагин)
-- `apps/server/src/core/ai-chat/ai-realtime.service.ts` (+ WS-gateway)
-
-Изменяемые:
-- [ai.types.ts](../apps/server/src/integrations/ai/ai.types.ts),
-  [ai-settings.service.ts](../apps/server/src/integrations/ai/ai-settings.service.ts) —
-  новые поля конфига + маска.
-- [ai.service.ts](../apps/server/src/integrations/ai/ai.service.ts) — realtime
-  test-connection (если делать через AiService).
-- [mic-button.tsx](../apps/client/src/features/dictation/components/mic-button.tsx) —
-  выбор realtime/batch по флагу.
-- [dictation-group.tsx](../apps/client/src/features/editor/components/fixed-toolbar/groups/dictation-group.tsx),
-  [chat-input.tsx](../apps/client/src/features/ai-chat/components/chat-input.tsx) —
-  обработка `onInterim/onFinal`.
-- Настройки AI в клиенте (Workspace settings → AI) — тумблер + модель + тест.
-- AI-модуль сервера ([app.module.ts](../apps/server/src/app.module.ts) /
-  `ai-chat`-модуль) — регистрация gateway.
-
----
-
-## Источники
-
-- [Realtime transcription — OpenAI API](https://developers.openai.com/api/docs/guides/realtime-transcription)
-- [Create transcription session — OpenAI API Reference](https://developers.openai.com/api/reference/resources/realtime/subresources/transcription_sessions/methods/create)
-- [Speech to text — OpenAI API](https://developers.openai.com/api/docs/guides/speech-to-text)
-- [Realtime and audio — OpenAI API](https://developers.openai.com/api/docs/guides/realtime)
-</content>
-</invoke>

package.json

@@ -1,7 +1,7 @@
 {
   "name": "docmost",
   "homepage": "https://docmost.com",
-  "version": "0.93.0",
+  "version": "0.94.1",
   "private": true,
   "scripts": {
     "build": "nx run-many -t build",

packages/editor-ext/src/lib/unique-id/unique-id.util.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect } from "vitest";
+import StarterKit from "@tiptap/starter-kit";
+import { addUniqueIdsToDoc } from "./unique-id.util";
+import { UniqueID } from "./unique-id";
+import { TransclusionSource } from "../transclusion/transclusion-source";
+
+// Minimal extension set: StarterKit (paragraph/heading) + the UniqueID config
+// the server uses for the addressing anchors.
+const extensions = [
+  StarterKit,
+  UniqueID.configure({ types: ["heading", "paragraph"] }),
+];
+
+// `transclusionSource` is also an addressed type, but its id is a cross-reference
+// KEY (a transclusionReference / the page_transclusions table resolves a source
+// by it), so it lives in the NO_REASSIGN set: a missing id is filled, a colliding
+// id is NOT reassigned (rewriting it would orphan its references).
+const extensionsWithSource = [
+  StarterKit,
+  // Narrow the content expression to `paragraph+` so the schema builds from
+  // StarterKit alone (the real allow-list references image/table/etc. nodes this
+  // minimal harness doesn't register). The node name — what NO_REASSIGN keys on
+  // — is unchanged.
+  TransclusionSource.extend({ content: "paragraph+" }),
+  UniqueID.configure({
+    types: ["heading", "paragraph", "transclusionSource"],
+  }),
+];
+
+const para = (id: string | undefined, text: string) => ({
+  type: "paragraph",
+  ...(id !== undefined ? { attrs: { id } } : {}),
+  content: [{ type: "text", text }],
+});
+
+const source = (id: string | undefined, text: string) => ({
+  type: "transclusionSource",
+  ...(id !== undefined ? { attrs: { id } } : {}),
+  // The schema requires at least one block child (content expression is `+`).
+  content: [{ type: "paragraph", content: [{ type: "text", text }] }],
+});
+
+const ids = (doc: any): (string | undefined)[] =>
+  (doc.content ?? []).map((n: any) => n.attrs?.id);
+
+describe("addUniqueIdsToDoc", () => {
+  it("fills ids on nodes that are missing one", () => {
+    const doc = { type: "doc", content: [para(undefined, "a"), para(undefined, "b")] };
+    const out = addUniqueIdsToDoc(doc, extensions);
+    const [a, b] = ids(out);
+    expect(a).toBeTruthy();
+    expect(b).toBeTruthy();
+    expect(a).not.toBe(b);
+  });
+
+  it("deduplicates two nodes that share the same id (#206 editor-pm-7)", () => {
+    // A copy/paste or bulk-JSON duplicate keeps the original id on both nodes.
+    const doc = {
+      type: "doc",
+      content: [para("dup", "first"), para("dup", "second")],
+    };
+    const out = addUniqueIdsToDoc(doc, extensions);
+    const [first, second] = ids(out);
+    // The first occurrence keeps the id (stable anchor); the duplicate is
+    // reassigned a fresh one so MCP addressing can't hit the wrong/both nodes.
+    expect(first).toBe("dup");
+    expect(second).toBeTruthy();
+    expect(second).not.toBe("dup");
+  });
+
+  it("leaves already-unique ids untouched", () => {
+    const doc = {
+      type: "doc",
+      content: [para("x1", "first"), para("x2", "second")],
+    };
+    const out = addUniqueIdsToDoc(doc, extensions);
+    expect(ids(out)).toEqual(["x1", "x2"]);
+  });
+
+  it("does NOT reassign a colliding transclusionSource id — BOTH keep it (NO_REASSIGN)", () => {
+    // Two sync-block sources sharing an id: rewriting either would orphan the
+    // transclusionReferences / page_transclusions rows that resolve a source by
+    // this key, so the dedupe MUST leave both ids intact. If the NO_REASSIGN
+    // guard is removed, the second source is reassigned a fresh id and this fails.
+    const doc = {
+      type: "doc",
+      content: [source("src", "first"), source("src", "second")],
+    };
+    const out = addUniqueIdsToDoc(doc, extensionsWithSource);
+    const [first, second] = ids(out);
+    expect(first).toBe("src");
+    expect(second).toBe("src");
+  });
+
+  it("still FILLS a missing id on a transclusionSource (only reassignment is suppressed)", () => {
+    // NO_REASSIGN suppresses dedupe of an EXISTING id, not filling a missing one:
+    // a source with no id still needs a key its references can resolve.
+    const doc = { type: "doc", content: [source(undefined, "only")] };
+    const out = addUniqueIdsToDoc(doc, extensionsWithSource);
+    const [id] = ids(out);
+    expect(id).toBeTruthy();
+  });
+});

packages/editor-ext/src/lib/unique-id/unique-id.util.ts

@@ -59,18 +59,44 @@ export function addUniqueIdsToDoc(
   ]);
   const contentNode = Node.fromJSON(schema, doc);
 
-  // Find nodes that don't have a unique ID
-  const nodesWithoutId = findChildren(contentNode, (node) => {
-    return !node.attrs[attributeName] && types.includes(node.type.name);
+  // All nodes of the configured types, in document order, so that the FIRST
+  // occurrence of any given id keeps it and later duplicates get reassigned.
+  const idNodes = findChildren(contentNode, (node) => {
+    return types.includes(node.type.name);
   });
 
-  // Edit the document to add unique IDs to the nodes that don't have a unique ID
+  // `transclusionSource` ids are cross-reference keys (a transclusionReference /
+  // the page_transclusions table resolves a source by this id), so rewriting one
+  // would orphan its references. We only fill a MISSING id for those, never
+  // reassign an existing one; plain block anchors (heading/paragraph) are safe to
+  // dedupe.
+  const NO_REASSIGN = new Set(["transclusionSource"]);
+
+  // Edit the document to (a) add ids where missing and (b) dedupe collisions. A
+  // duplicate id otherwise lets copy/paste/import produce two nodes sharing an
+  // id, so MCP addressed edits (patch_node / delete_node "before/after id") hit
+  // the wrong node or both (#206 editor-pm-7). This previously only filled
+  // missing ids and never deduplicated existing ones.
+  const seenIds = new Set<string>();
   let tr = EditorState.create({
     doc: contentNode,
   }).tr;
   // eslint-disable-next-line no-restricted-syntax
-  for (const { node, pos } of nodesWithoutId) {
-    tr = tr.setNodeAttribute(pos, attributeName, generateID({ node, pos }));
+  for (const { node, pos } of idNodes) {
+    const currentId = node.attrs[attributeName];
+    const isDuplicate = currentId != null && seenIds.has(currentId);
+    const needsNewId =
+      currentId == null || (isDuplicate && !NO_REASSIGN.has(node.type.name));
+
+    if (needsNewId) {
+      // setNodeAttribute only changes attributes (no size change), so positions
+      // from the original node stay valid across the whole loop.
+      const newId = generateID({ node, pos });
+      tr = tr.setNodeAttribute(pos, attributeName, newId);
+      seenIds.add(newId);
+    } else if (currentId != null) {
+      seenIds.add(currentId);
+    }
   }
 
   // Return the updated document

packages/mcp/test-e2e.mjs

@@ -7,6 +7,7 @@ import { writeFileSync, unlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { deflateSync } from "node:zlib";
+import { createServer } from "node:http";
 
 const API = process.env.DOCMOST_API_URL;
 if (!API || !process.env.DOCMOST_EMAIL || !process.env.DOCMOST_PASSWORD) {
@@ -104,7 +105,7 @@ async function main() {
       { find: "БУКВОЕД", replace: "КНИГОЛЮБ" },
       { find: "[1]", replace: "[42]" },
     ]);
-    check("edit_page_text: both edits applied", editRes.edits.every((e) => e.replacements === 1));
+    check("edit_page_text: both edits applied", editRes.applied.every((e) => e.replacements === 1));
     await new Promise((r) => setTimeout(r, 16000)); // wait for server persistence
     const pj2 = await client.getPageJson(pageId);
     const text2 = JSON.stringify(pj2.content);
@@ -149,11 +150,24 @@ async function main() {
     check("update_page_json: paragraph appended", JSON.stringify(pj4.content).includes("добавленный через update_page_json"));
     check("update_page_json: custom node id preserved", lastNode.attrs?.id === "testidjsonpush", lastNode.attrs?.id);
 
-    // 6b. images: upload / insert / replace (clean src, fresh attachment on replace)
-    const pngA = join(tmpdir(), `mcp-e2e-img-a-${Date.now()}.png`);
-    const pngB = join(tmpdir(), `mcp-e2e-img-b-${Date.now()}.png`);
-    writeFileSync(pngA, makePng(255, 0, 0)); // red
-    writeFileSync(pngB, makePng(0, 0, 255)); // blue (a DIFFERENT valid PNG)
+    // 6b. images: upload / insert / replace (clean src, fresh attachment on replace).
+    // insert_image / replace_image take an http(s) URL that the SERVER fetches;
+    // local file paths are intentionally unsupported. The Docmost server runs on
+    // the same host as this test, so serve the PNG bytes over a throwaway
+    // localhost HTTP server it can reach.
+    const bytesA = makePng(255, 0, 0); // red
+    const bytesB = makePng(0, 0, 255); // blue (a DIFFERENT valid PNG)
+    const imgServer = createServer((req, res) => {
+      res.writeHead(200, { "Content-Type": "image/png" });
+      res.end(req.url === "/b.png" ? bytesB : bytesA);
+    });
+    await new Promise((resolve, reject) => {
+      imgServer.once("error", reject);
+      imgServer.listen(0, "127.0.0.1", resolve);
+    });
+    const imgPort = imgServer.address().port;
+    const urlA = `http://127.0.0.1:${imgPort}/a.png`;
+    const urlB = `http://127.0.0.1:${imgPort}/b.png`;
     try {
       // Independent login to fetch file bytes with the same cookie the editor uses.
       const login = await axios.post(
@@ -173,7 +187,7 @@ async function main() {
         });
 
       // insert_image: append the first PNG, src must be clean (no ?v=) and fetchable.
-      const ins = await client.insertImage(pageId, pngA);
+      const ins = await client.insertImage(pageId, urlA);
       check("insert_image: src has no ?v= cache-buster", !ins.src.includes("?v="), ins.src);
       const fileA = await fetchFile(ins.src);
       check("insert_image: file fetch returns 200", fileA.status === 200, `status=${fileA.status}`);
@@ -199,7 +213,7 @@ async function main() {
 
       // replace_image: must create a NEW attachment with a clean, fetchable URL.
       // The 200 fetch is the assertion that catches the in-place-overwrite HTTP 500 regression.
-      const rep = await client.replaceImage(pageId, oldAttachmentId, pngB);
+      const rep = await client.replaceImage(pageId, oldAttachmentId, urlB);
       check("replace_image: new attachment id differs from old", rep.newAttachmentId !== oldAttachmentId, `${oldAttachmentId} -> ${rep.newAttachmentId}`);
       check("replace_image: src has no ?v= cache-buster", !rep.src.includes("?v="), rep.src);
       const fileB = await fetchFile(rep.src);
@@ -215,8 +229,7 @@ async function main() {
       check("replace_image: page has new attachment id", !!findImage(pjImg2.content.content, rep.newAttachmentId), rep.newAttachmentId);
       check("replace_image: old attachment id repointed away", !findImage(pjImg2.content.content, oldAttachmentId), oldAttachmentId);
     } finally {
-      try { unlinkSync(pngA); } catch {}
-      try { unlinkSync(pngB); } catch {}
+      imgServer.close();
     }
 
     // 6c. rich formatting: callout type, task list, inline marks, table alignment,
@@ -441,7 +454,10 @@ async function main() {
 
     // 9. comments: create / list / reply / update / check_new / delete
     const beforeComments = new Date(Date.now() - 1000).toISOString();
-    const c1 = await client.createComment(pageId, "Первый **комментарий** с [ссылкой](https://example.com).");
+    // A top-level comment requires an inline "selection": exact contiguous text
+    // that exists in the persisted page to anchor on. "Добавленный абзац." is a
+    // plain paragraph re-imported in section 5 and still present here.
+    const c1 = await client.createComment(pageId, "Первый **комментарий** с [ссылкой](https://example.com).", "inline", "Добавленный абзац.");
     check("create_comment: created", !!c1.data.id, c1.data.id);
     check("create_comment: markdown round-trip", c1.data.content.includes("**комментарий**"), c1.data.content);
     const reply = await client.createComment(pageId, "Ответ на комментарий.", "page", undefined, c1.data.id);