Merge pull request 'refactor(agent-roles-catalog): YAML catalog with block-scalar instructions (#229)' (#231) from feat/229-catalog-yaml into develop

Reviewed-on: #231

.env.example

@@ -124,6 +124,26 @@ MCP_DOCMOST_PASSWORD=
 # MCP_TOKEN=
 # MCP_SESSION_IDLE_MS=1800000
 #
+# BLOB SANDBOX (stash_page). An in-RAM, process-local store that hands large page
+# content + images to an external consumer WITHOUT bloating the model context or
+# requiring Docmost auth. The stash_page tool serializes a page, mirrors its
+# internal images into the store, and returns ONLY a short anonymous URL; the
+# consumer fetches blobs via `GET /api/sb/<uuid>` (no token — the capability is
+# the unguessable UUID + short TTL + TLS). Blobs are RAM-only and cleared on
+# restart. ETag = the blob's sha256 (integrity check).
+# SANDBOX_PUBLIC_URL is the base used to build those URLs; it MUST be reachable
+# by the consumer (do NOT use a loopback address if the consumer is remote).
+# Defaults to APP_URL when unset.
+# NOTE: the store is process-local — blobs live only on the instance that
+# created them. Behind a multi-replica load balancer WITHOUT sticky sessions a
+# consumer may hit a different instance and get a 404 (indistinguishable from an
+# expired blob). Single-host deployments are unaffected.
+# SANDBOX_PUBLIC_URL=https://docs.example.com
+# SANDBOX_TTL_MS=3600000
+# SANDBOX_MAX_BYTES=8388608
+# SANDBOX_MAX_IMAGE_BYTES=20971520
+# SANDBOX_MAX_TOTAL_BYTES=134217728
+#
 # AI-AGENT ATTRIBUTION (comments/pages written via MCP are badged as "AI"):
 # attribution is driven by a per-user `is_agent` flag on the users row. There is
 # NO admin UI/API for it — set it out-of-band with SQL. Use a DEDICATED service
@@ -132,6 +152,14 @@ MCP_DOCMOST_PASSWORD=
 # NEVER set is_agent on a human or shared account — every action by that account
 # (including normal human edits) would then be mis-attributed as AI.
 
+# Agent-roles catalog source: an http(s):// base URL to the catalog's raw files
+# (the server appends /index.yaml and /bundles/<id>/<lang>.yaml). This value is
+# baked into the Docker image at build time per branch (see the Dockerfile ARG
+# AI_AGENT_ROLES_CATALOG_URL and the CI build-args). Set it here only to point a
+# local/non-Docker run at a catalog; if unset, the "import role from catalog"
+# admin feature is unavailable. Local-filesystem sources are no longer supported.
+# AI_AGENT_ROLES_CATALOG_URL=
+
 # Per-embedding-call timeout in milliseconds for the RAG indexer.
 # A slow/hung embeddings endpoint fails after this and the batch continues.
 # AI_EMBEDDING_TIMEOUT_MS=120000

.github/workflows/develop.yml

@@ -25,6 +25,7 @@ jobs:
   build:
     needs: test
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -52,6 +53,7 @@ jobs:
           platforms: linux/amd64
           build-args: |
             APP_VERSION=${{ steps.version.outputs.value }}
+            AI_AGENT_ROLES_CATALOG_URL=https://raw.githubusercontent.com/vvzvlad/gitmost/develop/agent-roles-catalog
           push: true
           tags: ${{ env.IMAGE }}:develop
           cache-from: type=gha,scope=develop-amd64
@@ -64,6 +66,8 @@ jobs:
   # deploy block.
   e2e-server:
     runs-on: ubuntu-latest
+    # Hard cap: the full-AppModule e2e leaks open handles and hung jest to the 6h max.
+    timeout-minutes: 15
     env:
       DATABASE_URL: postgresql://docmost:docmost@localhost:5432/docmost
       REDIS_URL: redis://localhost:6379
@@ -122,6 +126,7 @@ jobs:
   # a red run plus GitHub's email to the pusher is the notification mechanism.
   e2e-mcp:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     env:
       DATABASE_URL: postgresql://docmost:docmost@localhost:5432/docmost
       REDIS_URL: redis://localhost:6379

.github/workflows/release.yml

@@ -17,6 +17,7 @@ permissions:
 env:
   VERSION: ${{ inputs.version || github.ref_name }}
   IMAGE: ghcr.io/vvzvlad/gitmost
+  AI_AGENT_ROLES_CATALOG_URL: https://raw.githubusercontent.com/vvzvlad/gitmost/main/agent-roles-catalog
 
 jobs:
   # Run the reusable test suite first so a failing test blocks the image build.
@@ -57,6 +58,7 @@ jobs:
           platforms: ${{ matrix.platform }}
           build-args: |
             APP_VERSION=${{ env.VERSION }}
+            AI_AGENT_ROLES_CATALOG_URL=${{ env.AI_AGENT_ROLES_CATALOG_URL }}
           outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
           cache-from: type=gha,scope=${{ matrix.suffix }}
           cache-to: type=gha,scope=${{ matrix.suffix }},mode=max,ignore-error=true
@@ -85,6 +87,7 @@ jobs:
           platforms: ${{ matrix.platform }}
           build-args: |
             APP_VERSION=${{ env.VERSION }}
+            AI_AGENT_ROLES_CATALOG_URL=${{ env.AI_AGENT_ROLES_CATALOG_URL }}
           push: false
           tags: |
             ${{ env.IMAGE }}:latest

.github/workflows/test.yml

@@ -15,6 +15,7 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     # Real Postgres + Redis so the server integration suite (`*.int-spec.ts`,
     # behind `pnpm --filter server test:int`) runs in CI (red-team finding #7).
     # Without it, cost-cap / FK-cascade / jsonb-round-trip / real-apply tests

AGENTS.md

@@ -241,7 +241,7 @@ Migration files live in `apps/server/src/database/migrations/` and are named `YY
 - **API server** — `dist/main` (`apps/server/src/main.ts`), the Fastify HTTP app (`AppModule`).
 - **Collaboration server** — `dist/collaboration/server/collab-main` (`pnpm collab`), a Hocuspocus/Yjs WebSocket server (`apps/server/src/collaboration/`) handling real-time document editing, persistence, and page-history snapshots. It listens on `COLLAB_PORT` (default `3001`), separate from the API server's `PORT` (default `3000`), and shares state with the API server through Redis.
 
-The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes `robots.txt`, public share pages, and `mcp` from the prefix). A `preHandler` hook enforces that a resolved `workspaceId` exists for most `/api` routes (multi-tenant by hostname/subdomain via `DomainMiddleware`). Auth is JWT (cookie + bearer); authorization is **CASL** (`core/casl`) — every data access is scoped to the user's abilities.
+The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes `robots.txt`, public share pages, and `mcp` from the prefix). A `preHandler` hook enforces that a resolved `workspaceId` exists for most `/api` routes (multi-tenant by hostname/subdomain via `DomainMiddleware`). `GET /api/sb/:id` (the anonymous blob-sandbox read route) is listed in that preHandler's `excludedPaths`, so it is exempt from workspace resolution and carries no session auth at all (its capability is the unguessable UUID + TTL + TLS) — unlike `/api/files/public/...`, which still resolves a workspace and requires a workspace-bound attachment JWT. Auth is JWT (cookie + bearer); authorization is **CASL** (`core/casl`) — every data access is scoped to the user's abilities.
 
 ### Module structure (server)
 `AppModule` wires integration modules (`integrations/*`: storage [local/S3/Azure], mail, queue [BullMQ on Redis], security, telemetry, throttle, `mcp`, `ai`) plus `CoreModule`, `DatabaseModule`, and `CollaborationModule`. `CoreModule` (`core/*`) holds the domain modules: `page`, `space`, `comment`, `workspace`, `user`, `auth`, `group`, `attachment`, `search`, `share`, `ai-chat`, etc. Each domain module follows NestJS controller → service → repo layering; DB repos live under `database/repos` and are injected app-wide from the global `DatabaseModule`.
@@ -254,7 +254,7 @@ The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes
 - **Redis** backs caching, the BullMQ queues, the WebSocket Socket.IO adapter, and collaboration sync.
 
 ### The two AI subsystems (the main fork additions)
-1. **Embedded MCP server** (`integrations/mcp/` + `packages/mcp`). The standalone `@docmost/mcp` server (38 agent-native tools: per-block patch/insert/delete by id, scripted `(doc)=>doc` transforms with dry-run diff, table editing, version diff/restore, comments, images, shares) is bundled and served over HTTP at `/mcp`. It writes through Docmost's real-time-collaboration layer so concurrent human edits aren't clobbered. Each request authenticates **per-user** via the `Authorization` header — either HTTP Basic (`base64(email:password)`, the user's own Docmost login, validated through `AuthService`) or a Bearer access JWT (the user's `authToken`) — and the session acts under that user's permissions. `MCP_DOCMOST_EMAIL` / `MCP_DOCMOST_PASSWORD` are an **optional service-account fallback**, used only when a request carries neither Basic nor Bearer credentials (back-compat for CI/scripts). An admin enables MCP with a workspace toggle (Workspace settings → AI). Optionally protected by a shared `MCP_TOKEN`: when set, every `/mcp` request must carry a matching `X-MCP-Token` header (its own header, separate from `Authorization`, which now carries the per-user Basic/Bearer credentials). Note: this changed from the older `Authorization: Bearer <MCP_TOKEN>` scheme — see `.env.example` and the CHANGELOG Breaking Changes entry.
+1. **Embedded MCP server** (`integrations/mcp/` + `packages/mcp`). The standalone `@docmost/mcp` server (40 agent-native tools: per-block patch/insert/delete by id, scripted `(doc)=>doc` transforms with dry-run diff, table editing, version diff/restore, comments, images, shares) is bundled and served over HTTP at `/mcp`. It writes through Docmost's real-time-collaboration layer so concurrent human edits aren't clobbered. Each request authenticates **per-user** via the `Authorization` header — either HTTP Basic (`base64(email:password)`, the user's own Docmost login, validated through `AuthService`) or a Bearer access JWT (the user's `authToken`) — and the session acts under that user's permissions. `MCP_DOCMOST_EMAIL` / `MCP_DOCMOST_PASSWORD` are an **optional service-account fallback**, used only when a request carries neither Basic nor Bearer credentials (back-compat for CI/scripts). An admin enables MCP with a workspace toggle (Workspace settings → AI). Optionally protected by a shared `MCP_TOKEN`: when set, every `/mcp` request must carry a matching `X-MCP-Token` header (its own header, separate from `Authorization`, which now carries the per-user Basic/Bearer credentials). Note: this changed from the older `Authorization: Bearer <MCP_TOKEN>` scheme — see `.env.example` and the CHANGELOG Breaking Changes entry.
 2. **AI agent chat** (`core/ai-chat/` server + `apps/client/src/features/ai-chat/` client). A built-in agent over the wiki using the Vercel **AI SDK** (`ai`, `@ai-sdk/*`) against any OpenAI-compatible provider configured per workspace (`integrations/ai/` — credentials encrypted at rest via `integrations/crypto`, stored in `ai_provider_credentials`). Key pieces:
    - `core/ai-chat/tools/` — the agent's ~40 read+write tools. Every tool runs under the **calling user's** CASL permissions via a per-user loopback access token (`docmost-client.loader.ts`), so the agent can never exceed what the user could do. Only **reversible** operations are exposed (page history + trash; no permanent delete). Agent edits get an "AI agent" provenance badge in page history (`20260616T130000-agent-provenance` migration).
    - `core/ai-chat/embedding/` — RAG indexer + a BullMQ consumer on `AI_QUEUE` that embeds pages into `page_embeddings` (vector search), complementing Postgres full-text search. Pages are (re)indexed on edit; `AI_EMBEDDING_TIMEOUT_MS` bounds a hung embeddings endpoint.

CHANGELOG.md

@@ -28,6 +28,117 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   answer was cut off and builds on it instead of restarting; the rest of the
   queue still flushes normally afterward. (#198)
 
+- **Importable multilingual agent-roles catalog.** Admins can browse a curated
+  catalog of agent roles, grouped into bundles and offered in several languages,
+  and import the ones they want into the workspace (with skip-or-rename handling
+  for name collisions); the same role in a different language imports as a
+  separate install. An imported role remembers its catalog origin and offers a
+  one-click update when the catalog ships a newer revision. Backed by four new
+  admin endpoints — `POST /ai-chat/roles/catalog` (browse bundles),
+  `/catalog/bundle` (read one bundle's roles), `/import`, and
+  `/update-from-catalog` — and a new `source` column linking a role to its
+  catalog slug/language/version. The catalog source is configured via the
+  `AI_AGENT_ROLES_CATALOG_URL` env var — an `http(s)://` base URL to the
+  catalog's raw files; the image ships a per-branch default baked in CI, and it
+  can be overridden at runtime via the env var (see `.env.example`). (#222)
+- **Author footnotes inline from an agent, and deterministic server-side footnote
+  canonicalization on every non-editor write path.** A new MCP `insert_footnote`
+  tool places a footnote at a body anchor by content only — the agent supplies
+  WHERE (anchor text) and WHAT (markdown); the number and the bottom
+  `footnotesList` are derived server-side, so an agent can never assign a number,
+  edit the list, or desync, and a same-content note reuses one definition. Under
+  the hood, the editor's footnote-integrity invariant (one trailing list,
+  numbering by first reference, no orphans/duplicates, no raw `[^id]`) is now
+  enforced as a pure `canonicalizeFootnotes(doc)` on the FULL-document write paths
+  that bypass the editor's plugins: server markdown/HTML import, `PageService`
+  create and full-document (`replace`) updates, the client markdown paste, and the
+  MCP markdown page-import / `update_page` (markdown) / `update_page_json` /
+  `docmost_transform` / `insert_footnote` / `copy_page_content` paths. It is
+  idempotent (a no-op once canonical) and is deliberately NOT applied to
+  append/prepend fragments, nor to COMMENT bodies — a comment may legitimately
+  contain a standalone footnote definition, which canonicalization would drop.
+  (#228)
+- **Out-of-band page transfer via an in-RAM blob sandbox (`stash_page`).** A
+  new MCP tool serializes a whole page (its full ProseMirror JSON, with every
+  internal image/file mirrored) into an ephemeral in-RAM blob and returns only
+  a short anonymous URL, so a large page can be handed to an external consumer
+  without flooding the model context. Blobs are served by unguessable UUID over
+  a new anonymous `GET /api/sb/:id` route (strong sha256 ETag, short TTL,
+  `nosniff` + restrictive CSP + attachment disposition for non-image mimes) and
+  are RAM-only, bound to the instance that created them. Tunable via five
+  `SANDBOX_*` env vars (see `.env.example`). (#243)
+
+### Changed
+
+- **Enabling a public share no longer auto-shares the whole sub-tree.** Turning
+  a page "Shared to web" now defaults to the page alone; descendant pages become
+  public only when you explicitly turn on the dedicated "Include sub-pages"
+  toggle. Previously the create call defaulted to including sub-pages, silently
+  exposing every child of a freshly shared page. (#216)
+
+- **The agent-roles catalog is now stored as YAML instead of JSON.** Each role's
+  long `instructions` system prompt is a literal block scalar (`|-`), so editing
+  a single sentence shows up as a line-by-line diff and the prompt is editable as
+  plain multi-line text rather than one escaped JSON string. The catalog content
+  files become `index.yaml` and `bundles/<id>/<lang>.yaml` (old `.json` removed);
+  the resolved role content is byte-for-byte identical, so no role `version` is
+  bumped. The server fetches `<base>/index.yaml` and
+  `<base>/bundles/<id>/<lang>.yaml`, parsing them with the `yaml` library's safe,
+  JSON-compatible schema (no custom tags / no code execution) behind the same
+  size-cap, redirect and path-traversal guards. The `AI_AGENT_ROLES_CATALOG_URL`
+  base-URL contract is unchanged. (#229)
+
+### Fixed
+
+- **Internal links in exported Markdown no longer lose their visible text.** A
+  link whose target page name had no file extension (e.g. a bare title) was
+  collapsed to empty text during export, producing an unclickable, label-less
+  link; the page name is now preserved. (#204)
+- **Deep pages no longer render a blank breadcrumb while the sidebar tree loads.**
+  The breadcrumb now falls back to the page's own ancestor chain (fetched
+  independently of the lazily-built sidebar tree) so a deep page resolves its
+  trail immediately; navigating away no longer leaves the previously-viewed
+  page's breadcrumb showing until the new one resolves. (#206, #218)
+- **Pasted GitHub-style callouts (`> [!NOTE]` …) now convert to real callouts.**
+  GitHub admonition blocks pasted as Markdown are recognized and rendered as
+  callout blocks instead of plain block-quotes. (#192)
+- **The editor stays read-only until collaboration has synced.** While a page is
+  connecting, the body is shown as a non-editable static view with a
+  "Connecting… (read-only)" banner, so edits typed before the document finishes
+  syncing can no longer be silently dropped. (#218)
+- **A shared page now keeps EXACTLY ONE custom address (`/l/:alias`).** Editing a
+  page's vanity slug previously inserted a second `share_aliases` row instead of
+  renaming the existing one, leaving the old `/l/<old>` link live forever and
+  making the share modal's lookup nondeterministic. Slug edits and confirmed
+  reassigns now rename/retarget the single row, and a new partial unique index on
+  `(workspace_id, page_id)` enforces the invariant in the database. **Upgrade
+  note:** the accompanying migration `20260627T120000` IRREVERSIBLY deletes the
+  orphaned duplicate alias rows the old bug created (keeping the newest per
+  page), so any previously-live duplicate `/l/<old>` link begins returning the
+  generic 404 after upgrade — intended, but not undoable by `down()`. (#226,
+  #227)
+- **Typing a custom address already used by another page no longer looks like a
+  dead end.** The share modal previously flagged such a name with a red "This
+  address is already in use" error, hiding the fact that saving offers to MOVE
+  the address to the current page. The field now shows an informational hint —
+  "This address is in use. Saving will move it to this page." — and keeps Save
+  enabled, so the existing reassign-confirm flow (`409 ALIAS_REASSIGN_REQUIRED` →
+  "Move custom address?") is discoverable instead of reading as terminal. (#227)
+
+### Security
+
+- **The anonymous public-share page payload is trimmed to an explicit allowlist.**
+  The `/shares/page-info` route (the only unauthenticated path serializing a
+  page + its share) now returns only the fields the public renderer needs;
+  internal metadata — creator/last-updater/contributor ids, space/workspace ids,
+  AI/source bookkeeping, lock/template flags, parent/position and raw timestamps
+  — is no longer exposed to anonymous viewers. (#218)
+- **A forged or mismatched share id can no longer render a page off its slug
+  alone.** When the public URL carries a share id/key, the page must be reachable
+  through that exact share (its own share or an ancestor `includeSubPages`
+  share); any other value now returns the generic "not found" instead of
+  serving the page. (#218)
+
 ## [0.94.0] - 2026-06-26
 
 This release makes AI chat durable and fast: assistant turns are persisted to
@@ -106,6 +217,13 @@ per-workspace rolling-day token budget.
   applies it through the existing `/pages/update` route — reflecting it in the
   title field and broadcasting to other clients. Gated by the `settings.ai.generative`
   flag and throttled per user. (#199)
+- **AI chat: header button auto-opens the chat bound to the current document.**
+  Clicking the AI-chat button in the header while viewing a page now reopens the
+  latest chat tied to that document instead of whatever chat was last active,
+  reusing the existing `ai_chats.page_id` provenance (no migration). The newest
+  chat you created on the page wins; with no bound chat — or off a page, or if
+  the lookup fails — it falls soft to a fresh chat and keeps the current
+  selection otherwise. (#191)
 
 ### Changed
 

Dockerfile

@@ -23,6 +23,11 @@ RUN apt-get update \
 
 WORKDIR /app
 
+# Agent-roles catalog base URL: per-branch default set at build time (CI);
+# overridable at runtime via the AI_AGENT_ROLES_CATALOG_URL env var.
+ARG AI_AGENT_ROLES_CATALOG_URL=""
+ENV AI_AGENT_ROLES_CATALOG_URL=$AI_AGENT_ROLES_CATALOG_URL
+
 # Copy apps
 COPY --from=builder /app/apps/server/dist /app/apps/server/dist
 COPY --from=builder /app/apps/client/dist /app/apps/client/dist

README.md

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

README.ru.md

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

agent-roles-catalog/README.md

@@ -0,0 +1,201 @@
+# Agent roles catalog
+
+This directory is **data, not application code**. It holds the content of an
+"agent roles catalog": reusable agent role definitions (system prompts plus a
+little metadata), grouped into bundles and translated into one or more
+languages. A separate server reads these files and serves them; nothing here is
+executable application logic except the validation script.
+
+## File layout
+
+```
+agent-roles-catalog/
+  index.yaml                  # the catalog manifest: bundles, languages, role versions
+  bundles/
+    <bundle-id>/
+      <lang>.yaml             # one file per declared language (e.g. ru.yaml, en.yaml)
+  scripts/
+    check.mjs                 # validates the catalog (uses the `yaml` parser)
+    content-hashes.json       # check artifact: per-role content-hash lock (NOT served)
+  package.json                # defines the `check` script
+  README.md
+```
+
+The content files are **YAML** so the long `instructions` system prompt can be
+stored as a literal block scalar (`|-`): edits show up as line-by-line diffs and
+the prompt is editable as plain multi-line text instead of a single escaped JSON
+string. The `content-hashes.json` lockfile under `scripts/` stays JSON — it is a
+check artifact, never served.
+
+Currently shipped bundles:
+
+- `editorial` — the editorial suite (structural-editor, line-editor,
+  fact-checker, proofreader, narrator), languages `ru`, `en`.
+- `research` — a single `researcher` role, languages `ru`, `en`.
+
+## How it's served
+
+The server does not bundle this data; it reads it at request time from a single
+configured location, the `AI_AGENT_ROLES_CATALOG_URL` env var
+(`EnvironmentService.getAiAgentRolesCatalogSource()`), an `http(s)://` base URL
+to the catalog's raw files. The server fetches `<base>/index.yaml` for the
+manifest and `<base>/bundles/<bundle-id>/<lang>.yaml` for each opened bundle
+file (REMOTE only).
+
+That base URL is provided as a per-branch default in the Docker image (set in
+CI: a `develop` build points at the `develop` raw URL, a release build at the
+`main` raw URL) and can be overridden at runtime via the
+`AI_AGENT_ROLES_CATALOG_URL` env var. Local-filesystem sources are no longer
+supported; if the value is unset the catalog is unavailable.
+
+The fetched YAML is parsed with a safe, JSON-compatible schema and re-validated
+server-side (the catalog is treated as untrusted input). See `.env.example` for
+the variable and the CHANGELOG for the rollout.
+
+## `index.yaml` schema
+
+```yaml
+schemaVersion: 1
+bundles:
+  - id: editorial # unique bundle id; matches bundles/<id>/
+    name: # localized display name
+      ru: "..."
+      en: "..."
+    description:
+      ru: "..."
+      en: "..."
+    languages: # which <lang>.yaml files must exist
+      - ru
+      - en
+    roles:
+      - slug: structural-editor
+        version: 1
+      # ...
+```
+
+`version` lives **here, in index.yaml**, per role. Bump it whenever a role's
+content (instructions, name, description, etc.) changes, so consumers can detect
+updates.
+
+## Bundle (`<lang>.yaml`) schema
+
+```yaml
+schemaVersion: 1
+language: ru
+roles:
+  - slug: structural-editor # REQUIRED, unique across the whole catalog
+    emoji: "🧱"
+    name: "..." # REQUIRED, localized
+    description: "..." # localized
+    instructions: |- # REQUIRED, the system prompt, localized (literal block scalar)
+      First line of the prompt.
+      Second line.
+    autoStart: true # whether the role starts working immediately
+    launchMessage: "..." # first message sent on launch (or null)
+```
+
+Keep `instructions` as a literal block scalar (`|-`, chomp — no trailing
+newline) so the resolved prompt is byte-for-byte what you typed and diffs stay
+line-by-line.
+
+Notes:
+
+- `modelConfig` is intentionally absent; the server treats an absent
+  `modelConfig` as `null`.
+- A role's `slug`, `emoji`, and `autoStart` are identical across all language
+  files of the same bundle. Only `name`, `description`, `instructions`, and
+  `launchMessage` are translated.
+
+## Slug uniqueness
+
+**Every `slug` must be UNIQUE ACROSS THE WHOLE CATALOG**, not just within a
+bundle. A slug appears once per language file of its bundle (same slug in
+`ru.yaml` and `en.yaml`), but no two different bundles may share a slug.
+`scripts/check.mjs` enforces this.
+
+## How to add things
+
+### Add a role to an existing bundle
+
+1. Add an entry to that bundle's `roles[]` in `index.yaml` with a new unique
+   `slug` and `version: 1`.
+2. Add a role object with the same `slug` to **every** `<lang>.yaml` of the
+   bundle, translating `name`, `description`, `instructions`, and
+   `launchMessage`.
+3. Run the check (see below).
+
+### Add a bundle
+
+1. Add a bundle object to `index.yaml` (`id`, `name`, `description`,
+   `languages`, `roles`).
+2. Create `bundles/<id>/<lang>.yaml` for each declared language, with one role
+   object per `roles[]` entry.
+3. Run the check.
+
+### Add a language to a bundle
+
+1. Add the language code to that bundle's `languages[]` in `index.yaml`.
+2. Create `bundles/<id>/<lang>.yaml` containing every role of the bundle,
+   translated.
+3. Run the check.
+
+### Change a role's content
+
+Edit the role in the relevant `<lang>.yaml` file(s) and **bump that role's
+`version`** in `index.yaml`. Then run `node scripts/check.mjs --update-hashes`
+to refresh the content-hash lock (`scripts/content-hashes.json`). `check.mjs`
+now **fails if a role's content changed but its `version` was not bumped**, so
+this step is mandatory — the lock can only be refreshed after the bump.
+
+## Validating
+
+From this directory:
+
+```sh
+node scripts/check.mjs   # or: npm run check
+```
+
+It fails (exit code 1) if any slug is duplicated across the catalog, if a
+bundle's index `roles[]` don't match the slugs present in each language file, if
+a declared language file is missing, or if any role is missing a required field
+(`slug`, `name`, `instructions`). It prints `OK` on success.
+
+### Content-hash guard
+
+`check.mjs` also guards against changing a role's content without bumping its
+`version`. It keeps a lockfile, `scripts/content-hashes.json`, mapping each role
+`slug` to `{ version, hash }`, where `hash` is a SHA-256 over the role's
+content fields (`emoji`, `autoStart`, `name`, `description`, `instructions`,
+`launchMessage`) across all of its language files, in a deterministic canonical
+form. This lockfile is a **check artifact only** — the server fetches only
+`index.yaml` and the bundle `<lang>.yaml` files, never this file, so it has no
+effect on the served catalog or its schema.
+
+On a normal run, for every role the check recomputes the hash and compares it
+against the lock:
+
+- content unchanged and versions agree → OK;
+- content changed but `version` not bumped above the lock → **error** asking you
+  to bump and refresh;
+- content changed and `version` bumped → **error** asking you to record it by
+  refreshing the lock;
+- role missing from the lock, or a lock entry for a role that no longer exists →
+  **error** asking you to refresh.
+
+Refresh the lock with:
+
+```sh
+node scripts/check.mjs --update-hashes   # alias: --fix
+```
+
+This recomputes the lock from the current catalog, prunes entries for removed
+roles, and prints what changed — but it **refuses to write** (exit 1) if any
+role's content changed while its `index.yaml` version was not bumped, so the
+version bump is always enforced first. The check also requires every
+`index.yaml` role to carry a finite numeric `version` (the server requires the
+same).
+
+Known, accepted limitation: a deliberate prune-then-readd of a slug (remove the
+role and run `--update-hashes`, then re-add it with changed content at the same
+version) is **not** caught, because a brand-new slug has no lock baseline to
+enforce a bump against.

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

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

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

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

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

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

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

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

agent-roles-catalog/index.yaml

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

agent-roles-catalog/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "agent-roles-catalog",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "check": "node scripts/check.mjs"
+  },
+  "devDependencies": {
+    "yaml": "^2.8.3"
+  }
+}

agent-roles-catalog/scripts/check.mjs

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+// Validates the agent roles catalog.
+// Fails (exit 1) on: duplicate slugs across the whole catalog, mismatches
+// between a bundle's index roles[] and the slugs present in each language
+// file, a missing declared language file, or a role missing required fields.
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+// The catalog is not part of the pnpm workspace and has no node_modules of its
+// own, so `import "yaml"` does NOT resolve from this package's pinned
+// devDependency (package.json lists `yaml` only to document the version). Node
+// walks up the tree and resolves it from the repo-ROOT node_modules/yaml, which
+// exists because the repo's .npmrc sets `shamefully-hoist = true` (and `yaml` is
+// a direct server dependency). Run this script from a checkout where the root
+// deps are installed.
+import YAML from "yaml";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const catalogDir = join(__dirname, "..");
+
+// `--update-hashes` (alias `--fix`) recomputes the content-hash lockfile from
+// the current catalog instead of just validating against it.
+const updateHashes =
+  process.argv.includes("--update-hashes") || process.argv.includes("--fix");
+
+// The content-hash lockfile lives under scripts/ and is a CHECK ARTIFACT only:
+// the server never fetches it, so it has zero impact on the served schema.
+const lockPath = join(__dirname, "content-hashes.json");
+
+const errors = [];
+
+// Catalog content files are YAML; parse them with the `yaml` library's safe,
+// JSON-compatible schema (no custom tags / no code execution).
+function readYaml(path) {
+  try {
+    return YAML.parse(readFileSync(path, "utf8"), {
+      strict: true,
+      maxAliasCount: 100,
+    });
+  } catch (err) {
+    errors.push(`Cannot read/parse ${path}: ${err.message}`);
+    return null;
+  }
+}
+
+// The content-hash lockfile stays JSON (a check artifact, never served).
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    errors.push(`Cannot read/parse ${path}: ${err.message}`);
+    return null;
+  }
+}
+
+const indexPath = join(catalogDir, "index.yaml");
+if (!existsSync(indexPath)) {
+  console.error(`Missing index.yaml at ${indexPath}`);
+  process.exit(1);
+}
+
+const index = readYaml(indexPath);
+if (!index) {
+  for (const e of errors) console.error(e);
+  process.exit(1);
+}
+
+const bundles = Array.isArray(index.bundles) ? index.bundles : [];
+if (bundles.length === 0) {
+  errors.push("index.yaml has no bundles[]");
+}
+
+// Track every slug seen across the whole catalog to detect duplicates.
+const slugSeen = new Map(); // slug -> "bundleId/lang"
+
+for (const bundle of bundles) {
+  const bundleId = bundle.id;
+  if (!bundleId) {
+    errors.push("A bundle in index.yaml is missing an id");
+    continue;
+  }
+
+  const indexSlugs = (bundle.roles || []).map((r) => r.slug);
+  // Duplicate slugs inside the bundle index roles[].
+  const indexSlugSet = new Set(indexSlugs);
+  if (indexSlugSet.size !== indexSlugs.length) {
+    errors.push(`Bundle "${bundleId}" index.yaml roles[] contains duplicate slugs`);
+  }
+
+  // Each index role must carry a finite numeric "version". The server requires
+  // this (see ai-agent-roles-catalog.provider.ts), and the content-hash guard
+  // below relies on it for the bump comparison, so enforce it here too.
+  for (const r of bundle.roles || []) {
+    if (typeof r.version !== "number" || !Number.isFinite(r.version)) {
+      errors.push(
+        `Bundle "${bundleId}" index.yaml role "${r.slug}" is missing a numeric "version"`
+      );
+    }
+  }
+
+  const languages = Array.isArray(bundle.languages) ? bundle.languages : [];
+  if (languages.length === 0) {
+    errors.push(`Bundle "${bundleId}" declares no languages`);
+  }
+
+  for (const lang of languages) {
+    const langPath = join(catalogDir, "bundles", bundleId, `${lang}.yaml`);
+    if (!existsSync(langPath)) {
+      errors.push(`Bundle "${bundleId}" declares language "${lang}" but ${langPath} is missing`);
+      continue;
+    }
+
+    const langFile = readYaml(langPath);
+    if (!langFile) continue;
+
+    const roles = Array.isArray(langFile.roles) ? langFile.roles : [];
+    const fileSlugs = roles.map((r) => r && r.slug);
+
+    // (d) Required fields per role.
+    for (const role of roles) {
+      for (const field of ["slug", "name", "instructions"]) {
+        if (role == null || role[field] == null || role[field] === "") {
+          errors.push(
+            `Bundle "${bundleId}/${lang}" has a role missing required field "${field}" (slug=${role && role.slug})`
+          );
+        }
+      }
+    }
+
+    // (b) index roles[] must match the slugs present in each language file.
+    const fileSlugSet = new Set(fileSlugs);
+    const missingInFile = indexSlugs.filter((s) => !fileSlugSet.has(s));
+    const extraInFile = fileSlugs.filter((s) => !indexSlugSet.has(s));
+    if (missingInFile.length > 0) {
+      errors.push(
+        `Bundle "${bundleId}/${lang}" is missing roles declared in index.yaml: ${missingInFile.join(", ")}`
+      );
+    }
+    if (extraInFile.length > 0) {
+      errors.push(
+        `Bundle "${bundleId}/${lang}" has roles not declared in index.yaml: ${extraInFile.join(", ")}`
+      );
+    }
+
+    // (a) Duplicate slugs across the whole catalog.
+    for (const slug of fileSlugs) {
+      if (!slug) continue;
+      const where = `${bundleId}/${lang}`;
+      // Only flag duplicates across DIFFERENT bundles or files; the same slug
+      // is expected to appear once per language file of the same bundle.
+      if (slugSeen.has(slug)) {
+        const prev = slugSeen.get(slug);
+        const prevBundle = prev.split("/")[0];
+        if (prevBundle !== bundleId) {
+          errors.push(
+            `Slug "${slug}" is duplicated across the catalog: ${prev} and ${where}`
+          );
+        }
+      } else {
+        slugSeen.set(slug, where);
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Content-hash guard: detect "content changed without a version bump".
+//
+// check.mjs cannot use git history, so we maintain a lockfile
+// (scripts/content-hashes.json) mapping each role slug to its recorded
+// { version, hash }. On every run we recompute each role's content hash and
+// compare it against the lock; a content change is only allowed once the role's
+// version in index.yaml has been bumped and the lock refreshed.
+//
+// Known, accepted limitation: a deliberate prune-then-readd of a slug (remove
+// the role and run --update-hashes, then re-add it with changed content at the
+// same version) is NOT caught, because a brand-new slug has no lock baseline to
+// enforce a bump against. We document this rather than building tombstones.
+// ---------------------------------------------------------------------------
+
+// Content fields hashed for each role, in a fixed canonical order. `slug` is
+// identity (not content) and `version` lives in index.yaml, so neither is here.
+// `modelConfig` (an OPTIONAL role field the server also serves) is intentionally
+// EXCLUDED: no shipped role uses it today, and being an object it would need a
+// deterministic deep canonicalization (recursive key sort) before hashing —
+// otherwise JSON.stringify key-order would make the hash non-deterministic. If a
+// role ever gains a `modelConfig`, add it here WITH such canonicalization so a
+// change to it is still caught by the bump guard.
+const CONTENT_FIELDS = [
+  "emoji",
+  "autoStart",
+  "name",
+  "description",
+  "instructions",
+  "launchMessage",
+];
+
+// Build a map of slug -> { version, langRoles: { lang: roleObject } } from the
+// current catalog so we can compute hashes and read index versions.
+function collectCatalogRoles() {
+  const out = new Map(); // slug -> { version, langRoles: Map<lang, role> }
+  for (const bundle of bundles) {
+    const bundleId = bundle.id;
+    if (!bundleId) continue;
+    const languages = Array.isArray(bundle.languages) ? bundle.languages : [];
+    for (const r of bundle.roles || []) {
+      if (!r || !r.slug) continue;
+      if (!out.has(r.slug)) {
+        out.set(r.slug, { version: r.version, langRoles: new Map() });
+      } else {
+        // Same slug declared twice in index.yaml roles[]; already flagged above.
+        out.get(r.slug).version = r.version;
+      }
+    }
+    for (const lang of languages) {
+      const langPath = join(catalogDir, "bundles", bundleId, `${lang}.yaml`);
+      if (!existsSync(langPath)) continue;
+      const langFile = readYaml(langPath);
+      if (!langFile) continue;
+      const roles = Array.isArray(langFile.roles) ? langFile.roles : [];
+      for (const role of roles) {
+        if (!role || !role.slug) continue;
+        const entry = out.get(role.slug);
+        if (!entry) continue; // role not declared in index.yaml; flagged above.
+        entry.langRoles.set(lang, role);
+      }
+    }
+  }
+  return out;
+}
+
+// Deterministic content hash for a role: languages sorted ascending, each
+// language's content fields taken in CONTENT_FIELDS order (null when absent).
+function contentHash(langRoles) {
+  const langs = [...langRoles.keys()].sort();
+  const canonical = langs.map((lang) => {
+    const role = langRoles.get(lang);
+    const fields = {};
+    for (const field of CONTENT_FIELDS) {
+      fields[field] = role && role[field] != null ? role[field] : null;
+    }
+    return [lang, fields];
+  });
+  return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+
+// Compute current { version, hash } for every catalog role.
+const catalogRoles = collectCatalogRoles();
+const current = new Map(); // slug -> { version, hash }
+for (const [slug, entry] of catalogRoles) {
+  current.set(slug, {
+    version: entry.version,
+    hash: contentHash(entry.langRoles),
+  });
+}
+
+// Load the existing lock (may be absent on first run).
+let lock = {};
+if (existsSync(lockPath)) {
+  const parsed = readJson(lockPath);
+  if (parsed && typeof parsed === "object") lock = parsed;
+}
+
+if (updateHashes) {
+  // Refresh the lock from the current catalog, but refuse to write if any role's
+  // content changed without its version being bumped above the existing lock.
+  const blockers = [];
+  for (const [slug, cur] of current) {
+    const prev = lock[slug];
+    if (!prev) continue; // new role; nothing to enforce a bump against.
+    if (cur.hash === prev.hash) continue; // content unchanged.
+    // Defense-in-depth: a non-numeric version must never pass the bump check via
+    // `undefined <= N` (which is false). The standard checks already flag a
+    // missing numeric version, but guard here too before comparing.
+    if (typeof cur.version !== "number" || !Number.isFinite(cur.version)) {
+      blockers.push(
+        `role "${slug}" content changed but its index.yaml "version" is missing or not numeric; set a numeric "version" before refreshing the lock`
+      );
+    } else if (cur.version <= prev.version) {
+      blockers.push(
+        `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.yaml before refreshing the lock`
+      );
+    }
+  }
+  // Still honor the standard checks before allowing a write.
+  if (errors.length > 0) {
+    console.error("Catalog check FAILED:");
+    for (const e of errors) console.error(`  - ${e}`);
+    process.exit(1);
+  }
+  if (blockers.length > 0) {
+    console.error("Refusing to update content-hash lock:");
+    for (const b of blockers) console.error(`  - ${b}`);
+    process.exit(1);
+  }
+
+  // Compute the change summary relative to the old lock, pruning removed slugs.
+  const newLock = {};
+  const added = [];
+  const changed = [];
+  const removed = [];
+  for (const [slug, cur] of [...current].sort((a, b) => a[0].localeCompare(b[0]))) {
+    newLock[slug] = { version: cur.version, hash: cur.hash };
+    const prev = lock[slug];
+    if (!prev) added.push(slug);
+    else if (prev.hash !== cur.hash || prev.version !== cur.version) changed.push(slug);
+  }
+  for (const slug of Object.keys(lock)) {
+    if (!current.has(slug)) removed.push(slug);
+  }
+  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + "\n");
+  console.log(`Wrote ${lockPath}`);
+  if (added.length) console.log(`  added:   ${added.join(", ")}`);
+  if (changed.length) console.log(`  updated: ${changed.join(", ")}`);
+  if (removed.length) console.log(`  pruned:  ${removed.join(", ")}`);
+  if (!added.length && !changed.length && !removed.length) {
+    console.log("  (no changes; lock already up to date)");
+  }
+  console.log("OK");
+  process.exit(0);
+}
+
+// Normal run: validate current content against the lock.
+for (const [slug, cur] of current) {
+  const prev = lock[slug];
+  if (!prev) {
+    errors.push(
+      `role "${slug}" is not recorded in the content-hash lock; run: node scripts/check.mjs --update-hashes`
+    );
+    continue;
+  }
+  if (cur.hash === prev.hash) {
+    // Content unchanged; the lock version must still agree with index.yaml.
+    if (cur.version !== prev.version) {
+      errors.push(
+        `role "${slug}" content is unchanged but its index.yaml version (${cur.version}) differs from the lock (${prev.version}); run: node scripts/check.mjs --update-hashes`
+      );
+    }
+    continue;
+  }
+  // Content changed.
+  // Defense-in-depth: treat a non-numeric version as an error before the `<=`
+  // comparison, so a missing version can never silently pass the bump check
+  // (and we avoid a misleading "version bumped to undefined" message).
+  if (typeof cur.version !== "number" || !Number.isFinite(cur.version)) {
+    errors.push(
+      `role "${slug}" content changed but its index.yaml "version" is missing or not numeric; set a numeric "version", then run: node scripts/check.mjs --update-hashes`
+    );
+  } else if (cur.version <= prev.version) {
+    errors.push(
+      `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.yaml, then run: node scripts/check.mjs --update-hashes`
+    );
+  } else {
+    errors.push(
+      `role "${slug}" content changed and version bumped to ${cur.version}; record it by running: node scripts/check.mjs --update-hashes`
+    );
+  }
+}
+// Lock entries for slugs that no longer exist in the catalog.
+for (const slug of Object.keys(lock)) {
+  if (!current.has(slug)) {
+    errors.push(
+      `content-hash lock has entry for unknown role "${slug}" (no longer in the catalog); run: node scripts/check.mjs --update-hashes`
+    );
+  }
+}
+
+if (errors.length > 0) {
+  console.error("Catalog check FAILED:");
+  for (const e of errors) console.error(`  - ${e}`);
+  process.exit(1);
+}
+
+console.log("OK");

agent-roles-catalog/scripts/content-hashes.json

@@ -0,0 +1,26 @@
+{
+  "fact-checker": {
+    "version": 3,
+    "hash": "a94931fbd20272570a588c72159ac9e48a89c99bd8f718449cda5e7ca4280fdf"
+  },
+  "line-editor": {
+    "version": 2,
+    "hash": "cca324110dc6f96d2a8a239a2fb95b0ba09fad5806c9b6090a3c210ea7883ceb"
+  },
+  "narrator": {
+    "version": 1,
+    "hash": "36b38785fea6ae1c70bf6fb6b29ae5278bb86e389e61f7b9736675a589fa434c"
+  },
+  "proofreader": {
+    "version": 3,
+    "hash": "a36047c5cab837b2a727f63d4ddafc269b1fc44b90b365e770ecdb8f77e13952"
+  },
+  "researcher": {
+    "version": 1,
+    "hash": "853658fda43ddbe0a4d08f2c6e50b5116d29a2e9ccd7f46e173e65920d8f6ace"
+  },
+  "structural-editor": {
+    "version": 2,
+    "hash": "83093baa7262aef8193871a1afcf2b43b11a56fe2d00cade41355cf66d972b74"
+  }
+}

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

@@ -1333,6 +1333,7 @@
   "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",
+  "This address is in use. Saving will move it to this page.": "This address is in use. Saving will move it to this page.",
   "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?",
@@ -1346,5 +1347,23 @@
   "Could not generate a title": "Could not generate a title",
   "AI title generation is disabled": "AI title generation is disabled",
   "AI is not configured": "AI is not configured",
-  "Too many requests, please try again later": "Too many requests, please try again later"
+  "Too many requests, please try again later": "Too many requests, please try again later",
+  "Import from catalog": "Import from catalog",
+  "Browse the catalog": "Browse the catalog",
+  "Role catalog": "Role catalog",
+  "On name conflict": "On name conflict",
+  "Skip": "Skip",
+  "Import": "Import",
+  "Installed": "Installed",
+  "v{{from}} → v{{to}}": "v{{from}} → v{{to}}",
+  "Imported {{created}}, renamed {{renamed}}, skipped {{skipped}}": "Imported {{created}}, renamed {{renamed}}, skipped {{skipped}}",
+  "Failed to import {{count}} role(s)": "Failed to import {{count}} role(s)",
+  "The role catalog is unavailable": "The role catalog is unavailable",
+  "Please try again later.": "Please try again later.",
+  "No bundles available": "No bundles available",
+  "Already up to date": "Already up to date",
+  "Updated to the latest version": "Updated to the latest version",
+  "This role is no longer in the catalog": "This role is no longer in the catalog",
+  "This language is no longer available in the catalog": "This language is no longer available in the catalog",
+  "Connecting… (read-only)": "Connecting… (read-only)"
 }

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

@@ -1190,6 +1190,7 @@
   "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": "Этот адрес уже занят",
+  "This address is in use. Saving will move it to this page.": "Этот адрес уже используется. При сохранении он будет перемещён на эту страницу.",
   "Move custom address?": "Переместить пользовательский адрес?",
   "Move here": "Переместить сюда",
   "The address \"{{alias}}\" currently points to \"{{title}}\". Move it to this page?": "Адрес «{{alias}}» сейчас указывает на «{{title}}». Переместить его на эту страницу?",
@@ -1203,5 +1204,24 @@
   "Could not generate a title": "Не удалось придумать название",
   "AI title generation is disabled": "Генерация названий через AI отключена",
   "AI is not configured": "AI не настроен",
-  "Too many requests, please try again later": "Слишком много запросов, попробуйте позже"
+  "Too many requests, please try again later": "Слишком много запросов, попробуйте позже",
+  "Import from catalog": "Импорт из каталога",
+  "Browse the catalog": "Открыть каталог",
+  "Role catalog": "Каталог ролей",
+  "On name conflict": "При конфликте имён",
+  "Skip": "Пропустить",
+  "Import": "Импортировать",
+  "Installed": "Установлено",
+  "v{{from}} → v{{to}}": "v{{from}} → v{{to}}",
+  "Imported {{created}}, renamed {{renamed}}, skipped {{skipped}}": "Импортировано: {{created}}, переименовано: {{renamed}}, пропущено: {{skipped}}",
+  "Failed to import {{count}} role(s)": "Не удалось импортировать ролей: {{count}}",
+  "The role catalog is unavailable": "Каталог ролей недоступен",
+  "Please try again later.": "Попробуйте позже.",
+  "No bundles available": "Наборы недоступны",
+  "No roles configured": "Роли не настроены",
+  "Already up to date": "Уже актуальна",
+  "Updated to the latest version": "Обновлено до последней версии",
+  "This role is no longer in the catalog": "Эта роль больше не представлена в каталоге",
+  "This language is no longer available in the catalog": "Этот язык больше не доступен в каталоге",
+  "Connecting… (read-only)": "Подключение… (только чтение)"
 }

apps/client/src/components/layouts/global/app-header.tsx

@@ -10,12 +10,12 @@ import classes from "./app-header.module.css";
 import { BrandLogo } from "@/components/ui/brand-logo";
 import TopMenu from "@/components/layouts/global/top-menu.tsx";
 import { Link } from "react-router-dom";
-import { useAtom, useSetAtom } from "jotai";
+import { useAtom } from "jotai";
 import {
   desktopSidebarAtom,
   mobileSidebarAtom,
 } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
-import { aiChatWindowOpenAtom } from "@/features/ai-chat/atoms/ai-chat-atom.ts";
+import { useOpenAiChatForCurrentPage } from "@/features/ai-chat/hooks/use-open-ai-chat.ts";
 import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
 import { useToggleSidebar } from "@/components/layouts/global/hooks/hooks/use-toggle-sidebar.ts";
 import SidebarToggle from "@/components/ui/sidebar-toggle-button.tsx";
@@ -38,7 +38,9 @@ export function AppHeader() {
   const toggleDesktop = useToggleSidebar(desktopSidebarAtom);
 
   const [workspace] = useAtom(workspaceAtom);
-  const setAiChatWindowOpen = useSetAtom(aiChatWindowOpenAtom);
+  // Opening from the header auto-opens the document's bound chat (last chat
+  // created on the current page); off a page it keeps the current selection.
+  const openAiChat = useOpenAiChatForCurrentPage();
   // AI chat entry point: only shown when the workspace enables it (A7 gate).
   const aiChatEnabled = workspace?.settings?.ai?.chat === true;
 
@@ -105,7 +107,7 @@ export function AppHeader() {
                 color="dark"
                 size="sm"
                 aria-label={t("AI chat")}
-                onClick={() => setAiChatWindowOpen((v) => !v)}
+                onClick={openAiChat}
               >
                 <IconMessage size={20} />
               </ActionIcon>

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

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { Provider, createStore } from "jotai";
+import type { ReactNode } from "react";
+import { useOpenAiChatForCurrentPage } from "./use-open-ai-chat";
+import {
+  activeAiChatIdAtom,
+  aiChatWindowOpenAtom,
+  aiChatDraftAtom,
+  selectedAiRoleIdAtom,
+} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
+
+// useMatch is the only react-router-dom export the hook uses; drive its return
+// per test to simulate "on a page" vs "off a page".
+const useMatchMock = vi.fn();
+vi.mock("react-router-dom", () => ({
+  useMatch: () => useMatchMock(),
+}));
+
+// The bound-chat resolver is the network boundary; stub it per test.
+const getBoundChatMock = vi.fn();
+vi.mock("@/features/ai-chat/services/ai-chat-service.ts", () => ({
+  getBoundChat: (pageId: string) => getBoundChatMock(pageId),
+}));
+
+// Put the hook on a page route by default ("doc-p1" -> page id "p1"); individual
+// tests override useMatch to go off-page.
+function onPage(pageSlug = "doc-p1") {
+  useMatchMock.mockReturnValue({ params: { pageSlug } });
+}
+function offPage() {
+  useMatchMock.mockReturnValue(null);
+}
+
+// Render the hook inside an explicit jotai store so atom side effects are
+// assertable; the store is returned for setup + assertions.
+function setup(seed?: (store: ReturnType<typeof createStore>) => void) {
+  const store = createStore();
+  seed?.(store);
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <Provider store={store}>{children}</Provider>
+  );
+  const { result } = renderHook(() => useOpenAiChatForCurrentPage(), { wrapper });
+  return { store, open: () => act(() => result.current()) };
+}
+
+describe("useOpenAiChatForCurrentPage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    onPage();
+  });
+
+  it("on a page: resolves the bound chat, selects it, and opens the window", async () => {
+    getBoundChatMock.mockResolvedValue("bound-chat-1");
+    const { store, open } = setup((s) => s.set(aiChatDraftAtom, "stale draft"));
+
+    await open();
+
+    expect(getBoundChatMock).toHaveBeenCalledWith("p1");
+    expect(store.get(activeAiChatIdAtom)).toBe("bound-chat-1");
+    expect(store.get(aiChatWindowOpenAtom)).toBe(true);
+    expect(store.get(aiChatDraftAtom)).toBe(""); // cleared on a real switch
+  });
+
+  it("on a page with no bound chat: opens a fresh chat (null)", async () => {
+    getBoundChatMock.mockResolvedValue(null);
+    const { store, open } = setup((s) => s.set(activeAiChatIdAtom, "previous"));
+
+    await open();
+
+    expect(store.get(activeAiChatIdAtom)).toBeNull();
+    expect(store.get(aiChatWindowOpenAtom)).toBe(true);
+  });
+
+  it("off a page: keeps the current selection and does NOT resolve", async () => {
+    offPage();
+    const { store, open } = setup((s) => {
+      s.set(activeAiChatIdAtom, "keep-me");
+      s.set(aiChatDraftAtom, "untouched");
+    });
+
+    await open();
+
+    expect(getBoundChatMock).not.toHaveBeenCalled();
+    expect(store.get(activeAiChatIdAtom)).toBe("keep-me");
+    expect(store.get(aiChatDraftAtom)).toBe("untouched"); // no switch -> kept
+    expect(store.get(aiChatWindowOpenAtom)).toBe(true);
+  });
+
+  it("window already open: re-click does NOT re-resolve or switch chats", async () => {
+    getBoundChatMock.mockResolvedValue("would-switch");
+    const { store, open } = setup((s) => {
+      s.set(aiChatWindowOpenAtom, true);
+      s.set(activeAiChatIdAtom, "current");
+    });
+
+    await open();
+
+    expect(getBoundChatMock).not.toHaveBeenCalled();
+    expect(store.get(activeAiChatIdAtom)).toBe("current");
+    expect(store.get(aiChatWindowOpenAtom)).toBe(true);
+  });
+
+  it("does NOT clear the draft when the resolved chat equals the current one", async () => {
+    getBoundChatMock.mockResolvedValue("same");
+    const { store, open } = setup((s) => {
+      s.set(activeAiChatIdAtom, "same");
+      s.set(aiChatDraftAtom, "in-progress");
+    });
+
+    await open();
+
+    expect(store.get(aiChatDraftAtom)).toBe("in-progress"); // no switch
+    expect(store.get(aiChatWindowOpenAtom)).toBe(true);
+  });
+
+  it("fail-soft: a resolve error opens a fresh chat (null)", async () => {
+    getBoundChatMock.mockRejectedValue(new Error("network"));
+    const { store, open } = setup((s) => s.set(activeAiChatIdAtom, "previous"));
+
+    await open();
+
+    expect(store.get(activeAiChatIdAtom)).toBeNull();
+    expect(store.get(aiChatWindowOpenAtom)).toBe(true);
+  });
+
+  it("clears the picked role on a real switch", async () => {
+    getBoundChatMock.mockResolvedValue("bound");
+    const { store, open } = setup((s) => s.set(selectedAiRoleIdAtom, "role-1"));
+
+    await open();
+
+    expect(store.get(selectedAiRoleIdAtom)).toBeNull();
+  });
+});

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

@@ -0,0 +1,67 @@
+import { useCallback } from "react";
+import { useAtom, useSetAtom } from "jotai";
+import { useMatch } from "react-router-dom";
+import {
+  aiChatWindowOpenAtom,
+  activeAiChatIdAtom,
+  aiChatDraftAtom,
+  selectedAiRoleIdAtom,
+} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
+import { getBoundChat } from "@/features/ai-chat/services/ai-chat-service.ts";
+import { extractPageSlugId } from "@/lib";
+
+/**
+ * The generic "open the AI chat" action, WITH document binding: when invoked
+ * while viewing a page, it resolves that page's bound chat and selects it before
+ * opening — so the last chat for this document re-opens by itself. With no bound
+ * chat (or off a page) it keeps the current selection / opens a fresh chat. Used
+ * by the app-header entry point; NOT by the provenance badge (which deep-links).
+ */
+export function useOpenAiChatForCurrentPage() {
+  const [windowOpen, setWindowOpen] = useAtom(aiChatWindowOpenAtom);
+  const [activeChatId, setActiveChatId] = useAtom(activeAiChatIdAtom);
+  const setDraft = useSetAtom(aiChatDraftAtom);
+  const setSelectedRoleId = useSetAtom(selectedAiRoleIdAtom);
+
+  // Same route-match trick the window uses: read :pageSlug from the pathname.
+  // AiChatWindow lives in a pathless parent layout route, so useParams() can't
+  // see :pageSlug — match the full path against the authenticated page route.
+  const match = useMatch("/s/:spaceSlug/p/:pageSlug");
+  const pageId = extractPageSlugId(match?.params?.pageSlug);
+
+  return useCallback(async () => {
+    // Re-clicks while the window is already open (incl. minimized) must NOT
+    // re-resolve and yank the user to another chat: resolve only on a genuine
+    // closed -> open transition. (`windowOpen` is already true here, so there
+    // is nothing to set — just bail.)
+    if (windowOpen) return;
+    // Open the window FIRST so the control feels instant: the bound-chat
+    // round-trip below must never gate the window appearing, or on a slow
+    // connection the first click reads as a hung control until the POST returns.
+    setWindowOpen(true);
+    let resolved: string | null = activeChatId; // off-a-page: keep current
+    if (pageId) {
+      try {
+        resolved = await getBoundChat(pageId); // null => fresh chat
+      } catch {
+        resolved = null; // fail-soft: a fresh chat is always a safe fallback
+      }
+    }
+    // Clear the composer draft / picked role ONLY on an actual switch, so
+    // reopening the same chat does not wipe an in-progress draft. Applied after
+    // the resolve so the window is already visible while the switch settles.
+    if (resolved !== activeChatId) {
+      setActiveChatId(resolved);
+      setDraft("");
+      setSelectedRoleId(null);
+    }
+  }, [
+    windowOpen,
+    activeChatId,
+    pageId,
+    setWindowOpen,
+    setActiveChatId,
+    setDraft,
+    setSelectedRoleId,
+  ]);
+}

apps/client/src/features/ai-chat/queries/ai-chat-query.ts

@@ -13,21 +13,40 @@ import {
   deleteAiRole,
   getAiChatMessages,
   getAiChats,
+  getAiRoleCatalog,
+  getAiRoleCatalogBundle,
   getAiRoles,
+  importAiRolesFromCatalog,
   renameAiChat,
   updateAiRole,
+  updateAiRoleFromCatalog,
 } from "@/features/ai-chat/services/ai-chat-service.ts";
 import {
   IAiChat,
   IAiChatMessageRow,
   IAiRole,
+  IAiRoleCatalog,
+  IAiRoleCatalogBundle,
   IAiRoleCreate,
+  IAiRoleImportPayload,
+  IAiRoleImportResult,
   IAiRoleUpdate,
+  IAiRoleUpdateFromCatalogResult,
 } from "@/features/ai-chat/types/ai-chat.types.ts";
 import { IPagination } from "@/lib/types.ts";
 
 export const AI_CHATS_RQ_KEY = ["ai-chats"];
 export const AI_ROLES_RQ_KEY = ["ai-roles"];
+// Catalog reads resolve bundle names per language, so the language is part of
+// the cache key (a language switch refetches rather than reusing stale names).
+export const AI_ROLE_CATALOG_RQ_KEY = (language: string) => [
+  "ai-role-catalog",
+  language,
+];
+export const AI_ROLE_CATALOG_BUNDLE_RQ_KEY = (
+  bundleId: string,
+  language: string,
+) => ["ai-role-catalog-bundle", bundleId, language];
 export const AI_CHAT_MESSAGES_RQ_KEY = (chatId: string) => [
   "ai-chat-messages",
   chatId,
@@ -223,3 +242,109 @@ export function useDeleteAiRoleMutation() {
     },
   });
 }
+
+/**
+ * Browse the role catalog for a language. Gated by `enabled` so the (admin-only)
+ * fetch runs only when the catalog modal is open. The catalog can 502 when the
+ * curated source is unreachable; callers handle the error state in the UI.
+ */
+export function useAiRoleCatalogQuery(language: string, enabled: boolean) {
+  return useQuery<IAiRoleCatalog, Error>({
+    queryKey: AI_ROLE_CATALOG_RQ_KEY(language),
+    queryFn: () => getAiRoleCatalog(language),
+    enabled,
+  });
+}
+
+/**
+ * Open one catalog bundle (role content + versions). Gated by `enabled` so the
+ * fetch only runs when a bundle is actually expanded.
+ */
+export function useAiRoleCatalogBundleQuery(
+  bundleId: string,
+  language: string,
+  enabled: boolean,
+) {
+  return useQuery<IAiRoleCatalogBundle, Error>({
+    queryKey: AI_ROLE_CATALOG_BUNDLE_RQ_KEY(bundleId, language),
+    queryFn: () => getAiRoleCatalogBundle(bundleId, language),
+    enabled,
+  });
+}
+
+export function useImportAiRolesFromCatalogMutation() {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+
+  return useMutation<IAiRoleImportResult, Error, IAiRoleImportPayload>({
+    mutationFn: (payload) => importAiRolesFromCatalog(payload),
+    onSuccess: (result) => {
+      notifications.show({
+        message: t("Imported {{created}}, renamed {{renamed}}, skipped {{skipped}}", {
+          created: result.created,
+          renamed: result.renamed,
+          skipped: result.skipped,
+        }),
+      });
+      // Surface partial failures (e.g. unique-name races) as a red warning.
+      if (result.errors.length > 0) {
+        notifications.show({
+          color: "red",
+          message: t("Failed to import {{count}} role(s)", {
+            count: result.errors.length,
+          }),
+        });
+      }
+      queryClient.invalidateQueries({ queryKey: AI_ROLES_RQ_KEY });
+      // Imported roles can appear in the chat picker / badges.
+      queryClient.invalidateQueries({ queryKey: AI_CHATS_RQ_KEY });
+    },
+    onError: (error) => {
+      const message = error["response"]?.data?.message;
+      notifications.show({
+        message: message ?? t("Failed to update data"),
+        color: "red",
+      });
+    },
+  });
+}
+
+export function useUpdateAiRoleFromCatalogMutation() {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+
+  return useMutation<IAiRoleUpdateFromCatalogResult, Error, string>({
+    mutationFn: (id) => updateAiRoleFromCatalog(id),
+    onSuccess: (result) => {
+      // The server returns updated:false with a reason for a no-op (already
+      // up to date / removed from catalog / language no longer offered). Map
+      // each reason to a specific message instead of a generic "up to date".
+      // Narrow the discriminated union via `"reason" in result` (the `updated`
+      // boolean discriminant does not narrow under this project's
+      // strictNullChecks:false). Inside the branch, `reason` is the typed literal
+      // union, so the comparisons below are compiler-checked.
+      let message: string;
+      if (!("reason" in result)) {
+        message = t("Updated to the latest version");
+      } else if (result.reason === "not-in-catalog") {
+        message = t("This role is no longer in the catalog");
+      } else if (result.reason === "language-unavailable") {
+        message = t("This language is no longer available in the catalog");
+      } else {
+        // "up-to-date" (the only remaining reason).
+        message = t("Already up to date");
+      }
+      notifications.show({ message });
+      queryClient.invalidateQueries({ queryKey: AI_ROLES_RQ_KEY });
+      // The role badge denormalized onto the chat list may have changed.
+      queryClient.invalidateQueries({ queryKey: AI_CHATS_RQ_KEY });
+    },
+    onError: (error) => {
+      const message = error["response"]?.data?.message;
+      notifications.show({
+        message: message ?? t("Failed to update data"),
+        color: "red",
+      });
+    },
+  });
+}

apps/client/src/features/ai-chat/queries/import-from-catalog-message.test.tsx

@@ -0,0 +1,106 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import React from "react";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { IAiRoleImportResult } from "@/features/ai-chat/types/ai-chat.types.ts";
+
+// `useImportAiRolesFromCatalogMutation` always shows an Imported/renamed/skipped
+// summary, and ADDITIONALLY a red "Failed to import N role(s)" notification when
+// the result carries partial errors. These tests pin both branches via
+// renderHook with a mocked service (twin precedent:
+// update-from-catalog-message.test.tsx).
+
+const notificationsShowMock = vi.fn();
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: (opts: unknown) => notificationsShowMock(opts) },
+}));
+
+// `t` echoes the key with interpolated values so we assert against the exact
+// English message strings (mirrors react-i18next's default interpolation).
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, vars?: Record<string, unknown>) =>
+      vars
+        ? key.replace(/\{\{(\w+)\}\}/g, (_m, name) => String(vars[name]))
+        : key,
+  }),
+}));
+
+vi.mock("@/features/ai-chat/services/ai-chat-service.ts", () => ({
+  importAiRolesFromCatalog: vi.fn(),
+  // Other named exports referenced by ai-chat-query.ts must exist on the mock so
+  // the module import resolves; they are unused by these tests.
+  createAiRole: vi.fn(),
+  deleteAiChat: vi.fn(),
+  deleteAiRole: vi.fn(),
+  getAiChatMessages: vi.fn(),
+  getAiChats: vi.fn(),
+  getAiRoleCatalog: vi.fn(),
+  getAiRoleCatalogBundle: vi.fn(),
+  getAiRoles: vi.fn(),
+  renameAiChat: vi.fn(),
+  updateAiRole: vi.fn(),
+  updateAiRoleFromCatalog: vi.fn(),
+}));
+
+import { importAiRolesFromCatalog } from "@/features/ai-chat/services/ai-chat-service.ts";
+import { useImportAiRolesFromCatalogMutation } from "@/features/ai-chat/queries/ai-chat-query.ts";
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+  };
+}
+
+async function runMutation(result: IAiRoleImportResult) {
+  vi.mocked(importAiRolesFromCatalog).mockResolvedValue(result);
+  const { result: hook } = renderHook(
+    () => useImportAiRolesFromCatalogMutation(),
+    { wrapper: createWrapper() },
+  );
+  hook.current.mutate({
+    bundleId: "general",
+    language: "en",
+    conflict: "rename",
+  });
+  await waitFor(() => expect(hook.current.isSuccess).toBe(true));
+}
+
+describe("useImportAiRolesFromCatalogMutation — success notifications", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("errors:[] -> only the summary notification (counts interpolated)", async () => {
+    await runMutation({ created: 3, renamed: 1, skipped: 2, errors: [] });
+    expect(notificationsShowMock).toHaveBeenCalledTimes(1);
+    expect(notificationsShowMock).toHaveBeenCalledWith({
+      message: "Imported 3, renamed 1, skipped 2",
+    });
+  });
+
+  it("errors.length > 0 -> summary PLUS the red failure notification", async () => {
+    await runMutation({
+      created: 1,
+      renamed: 0,
+      skipped: 0,
+      errors: [
+        { slug: "a", message: "name taken" },
+        { slug: "b", message: "name taken" },
+      ],
+    });
+    expect(notificationsShowMock).toHaveBeenCalledTimes(2);
+    expect(notificationsShowMock).toHaveBeenNthCalledWith(1, {
+      message: "Imported 1, renamed 0, skipped 0",
+    });
+    expect(notificationsShowMock).toHaveBeenNthCalledWith(2, {
+      color: "red",
+      message: "Failed to import 2 role(s)",
+    });
+  });
+});

apps/client/src/features/ai-chat/queries/update-from-catalog-message.test.tsx

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import React from "react";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { IAiRoleUpdateFromCatalogResult } from "@/features/ai-chat/types/ai-chat.types.ts";
+
+// `useUpdateAiRoleFromCatalogMutation` maps the server's discriminated result to
+// a user-facing notification message. These tests pin each of the four branches
+// (updated / not-in-catalog / language-unavailable / up-to-date) via renderHook
+// with a mocked service (precedent: share-query.null-normalization.test.tsx).
+
+const notificationsShowMock = vi.fn();
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: (opts: unknown) => notificationsShowMock(opts) },
+}));
+
+// `t` echoes the key so we assert against the exact English message strings.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock("@/features/ai-chat/services/ai-chat-service.ts", () => ({
+  updateAiRoleFromCatalog: vi.fn(),
+  // Other named exports referenced by ai-chat-query.ts must exist on the mock so
+  // the module import resolves; they are unused by these tests.
+  createAiRole: vi.fn(),
+  deleteAiChat: vi.fn(),
+  deleteAiRole: vi.fn(),
+  getAiChatMessages: vi.fn(),
+  getAiChats: vi.fn(),
+  getAiRoleCatalog: vi.fn(),
+  getAiRoleCatalogBundle: vi.fn(),
+  getAiRoles: vi.fn(),
+  importAiRolesFromCatalog: vi.fn(),
+  renameAiChat: vi.fn(),
+  updateAiRole: vi.fn(),
+}));
+
+import { updateAiRoleFromCatalog } from "@/features/ai-chat/services/ai-chat-service.ts";
+import { useUpdateAiRoleFromCatalogMutation } from "@/features/ai-chat/queries/ai-chat-query.ts";
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+  };
+}
+
+async function runMutation(result: IAiRoleUpdateFromCatalogResult) {
+  vi.mocked(updateAiRoleFromCatalog).mockResolvedValue(result);
+  const { result: hook } = renderHook(
+    () => useUpdateAiRoleFromCatalogMutation(),
+    { wrapper: createWrapper() },
+  );
+  hook.current.mutate("role-1");
+  await waitFor(() => expect(hook.current.isSuccess).toBe(true));
+}
+
+describe("useUpdateAiRoleFromCatalogMutation — reason → message", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("updated:true -> 'Updated to the latest version'", async () => {
+    await runMutation({
+      updated: true,
+      fromVersion: 1,
+      toVersion: 2,
+      role: { id: "role-1" } as never,
+    });
+    expect(notificationsShowMock).toHaveBeenCalledWith({
+      message: "Updated to the latest version",
+    });
+  });
+
+  it("not-in-catalog -> 'This role is no longer in the catalog'", async () => {
+    await runMutation({ updated: false, reason: "not-in-catalog" });
+    expect(notificationsShowMock).toHaveBeenCalledWith({
+      message: "This role is no longer in the catalog",
+    });
+  });
+
+  it("language-unavailable -> 'This language is no longer available in the catalog'", async () => {
+    await runMutation({ updated: false, reason: "language-unavailable" });
+    expect(notificationsShowMock).toHaveBeenCalledWith({
+      message: "This language is no longer available in the catalog",
+    });
+  });
+
+  it("up-to-date -> 'Already up to date'", async () => {
+    await runMutation({ updated: false, reason: "up-to-date" });
+    expect(notificationsShowMock).toHaveBeenCalledWith({
+      message: "Already up to date",
+    });
+  });
+});

apps/client/src/features/ai-chat/services/ai-chat-service.ts

@@ -6,8 +6,13 @@ import {
   IAiChatMessageRow,
   IAiChatMessagesParams,
   IAiRole,
+  IAiRoleCatalog,
+  IAiRoleCatalogBundle,
   IAiRoleCreate,
+  IAiRoleImportPayload,
+  IAiRoleImportResult,
   IAiRoleUpdate,
+  IAiRoleUpdateFromCatalogResult,
 } from "@/features/ai-chat/types/ai-chat.types.ts";
 
 /**
@@ -37,6 +42,17 @@ export async function getAiChatMessages(
   return req.data;
 }
 
+/**
+ * Resolve the chat bound to a document (the current user's most-recent chat
+ * created on that page), or null when there is none. Drives auto-open-on-page.
+ */
+export async function getBoundChat(pageId: string): Promise<string | null> {
+  const req = await api.post<{ chatId: string | null }>("/ai-chat/bound-chat", {
+    pageId,
+  });
+  return req.data.chatId;
+}
+
 /** Rename a chat. */
 export async function renameAiChat(data: {
   chatId: string;
@@ -112,3 +128,54 @@ export async function deleteAiRole(id: string): Promise<{ success: true }> {
   });
   return req.data;
 }
+
+/**
+ * Role catalog API (`/ai-chat/roles/*`, admin-only — the server enforces this).
+ * Browse a curated catalog, import roles/bundles into the workspace, and update
+ * an imported role when the catalog ships a newer version. Same `{ data }`
+ * unwrap convention as above.
+ */
+
+/** Browse the catalog, optionally localized to `language`. */
+export async function getAiRoleCatalog(
+  language?: string,
+): Promise<IAiRoleCatalog> {
+  const req = await api.post<IAiRoleCatalog>("/ai-chat/roles/catalog", {
+    language,
+  });
+  return req.data;
+}
+
+/** Open one catalog bundle in a language (role content + versions). */
+export async function getAiRoleCatalogBundle(
+  bundleId: string,
+  language: string,
+): Promise<IAiRoleCatalogBundle> {
+  const req = await api.post<IAiRoleCatalogBundle>(
+    "/ai-chat/roles/catalog/bundle",
+    { bundleId, language },
+  );
+  return req.data;
+}
+
+/** Import roles from a catalog bundle into the workspace (admin). */
+export async function importAiRolesFromCatalog(
+  payload: IAiRoleImportPayload,
+): Promise<IAiRoleImportResult> {
+  const req = await api.post<IAiRoleImportResult>(
+    "/ai-chat/roles/import",
+    payload,
+  );
+  return req.data;
+}
+
+/** Update an already-imported role from its catalog source (admin). */
+export async function updateAiRoleFromCatalog(
+  id: string,
+): Promise<IAiRoleUpdateFromCatalogResult> {
+  const req = await api.post<IAiRoleUpdateFromCatalogResult>(
+    "/ai-chat/roles/update-from-catalog",
+    { id },
+  );
+  return req.data;
+}

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

@@ -57,10 +57,79 @@ export interface IAiRole {
   autoStart: boolean;
   // Custom auto-start text; null/empty => the default launch message is sent.
   launchMessage: string | null;
+  // Catalog origin of an imported role, or null for a manually-created one.
+  // Admin-only (present only in the admin list view); the picker view omits it.
+  // The admin UI compares `version` against the catalog to offer an update.
+  source?: { slug: string; language: string; version: number } | null;
   createdAt?: string;
   updatedAt?: string;
 }
 
+/** One bundle's summary in the catalog index (mirrors `getCatalog().bundles[]`). */
+export interface IAiRoleCatalogBundleSummary {
+  id: string;
+  name: string;
+  description: string | null;
+  languages: string[];
+  roles: { slug: string; version: number }[];
+}
+
+/** The browsable catalog index (mirrors `getCatalog()`). */
+export interface IAiRoleCatalog {
+  languages: string[];
+  bundles: IAiRoleCatalogBundleSummary[];
+}
+
+/** A single role inside an opened catalog bundle (localized content + version). */
+export interface IAiRoleCatalogRole {
+  slug: string;
+  emoji: string | null;
+  name: string;
+  description: string | null;
+  instructions: string;
+  autoStart: boolean;
+  launchMessage: string | null;
+  version: number;
+}
+
+/** An opened catalog bundle (mirrors `getCatalogBundle()`). */
+export interface IAiRoleCatalogBundle {
+  bundleId: string;
+  language: string;
+  roles: IAiRoleCatalogRole[];
+}
+
+/** Import payload (mirrors the server `ImportFromCatalogDto`). */
+export interface IAiRoleImportPayload {
+  bundleId: string;
+  language: string;
+  // Omitted => import the whole bundle; otherwise only these slugs.
+  slugs?: string[];
+  conflict: "skip" | "rename";
+}
+
+/** Import result counts (mirrors `importFromCatalog()`). */
+export interface IAiRoleImportResult {
+  created: number;
+  skipped: number;
+  renamed: number;
+  errors: { slug: string; message: string }[];
+}
+
+/**
+ * Update-from-catalog result (mirrors the server `updateFromCatalog()`). A
+ * discriminated union on `updated`: a no-op carries a typed `reason` the UI maps
+ * to a specific message; a successful update carries the version bump + new role.
+ * Keeping the union (not a widened `reason?: string`) lets the consumer's literal
+ * comparisons be compiler-checked.
+ */
+export type IAiRoleUpdateFromCatalogResult =
+  | {
+      updated: false;
+      reason: "not-in-catalog" | "up-to-date" | "language-unavailable";
+    }
+  | { updated: true; fromVersion: number; toVersion: number; role: IAiRole };
+
 /** Admin create payload for a role. */
 export interface IAiRoleCreate {
   name: string;

apps/client/src/features/ai-chat/utils/catalog-role-install-state.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from "vitest";
+import { catalogRoleInstallState } from "./catalog-role-install-state.ts";
+import type { IAiRole } from "@/features/ai-chat/types/ai-chat.types.ts";
+
+// Build a workspace role with a catalog source. Fields irrelevant to the
+// install-state decision are filled with harmless defaults.
+function installedRole(
+  source: { slug: string; language: string; version: number },
+  overrides: Partial<IAiRole> = {},
+): IAiRole {
+  return {
+    id: `role-${source.slug}-${source.language}`,
+    name: source.slug,
+    emoji: null,
+    description: null,
+    enabled: true,
+    autoStart: true,
+    launchMessage: null,
+    source,
+    ...overrides,
+  };
+}
+
+const catalogRole = { slug: "writer", version: 3 };
+
+// Mirrors the role-launch.ts precedent: the modal's role-state computation is a
+// pure function so the import/installed/update decision is testable directly.
+describe("catalogRoleInstallState", () => {
+  it("no matching installed role -> import", () => {
+    const result = catalogRoleInstallState(catalogRole, [], "en");
+    expect(result).toEqual({ state: "import" });
+  });
+
+  it("same slug + language, installed version > catalog -> installed", () => {
+    const installed = installedRole({
+      slug: "writer",
+      language: "en",
+      version: 5,
+    });
+    const result = catalogRoleInstallState(catalogRole, [installed], "en");
+    expect(result).toEqual({ state: "installed", installed });
+  });
+
+  it("same slug + language, installed version == catalog -> installed", () => {
+    const installed = installedRole({
+      slug: "writer",
+      language: "en",
+      version: 3,
+    });
+    const result = catalogRoleInstallState(catalogRole, [installed], "en");
+    expect(result).toEqual({ state: "installed", installed });
+  });
+
+  it("same slug + language, installed version < catalog -> update (from/to)", () => {
+    const installed = installedRole({
+      slug: "writer",
+      language: "en",
+      version: 1,
+    });
+    const result = catalogRoleInstallState(catalogRole, [installed], "en");
+    expect(result).toEqual({
+      state: "update",
+      installed,
+      fromVersion: 1,
+      toVersion: 3,
+    });
+  });
+
+  it("same slug but DIFFERENT language -> import (a separate install)", () => {
+    // 'writer' is installed in 'ru'; browsing the 'en' catalog must offer it as a
+    // fresh import, not treat the ru copy as already installed.
+    const installed = installedRole({
+      slug: "writer",
+      language: "ru",
+      version: 5,
+    });
+    const result = catalogRoleInstallState(catalogRole, [installed], "en");
+    expect(result).toEqual({ state: "import" });
+  });
+
+  it("matches the right language when the same slug is installed in several", () => {
+    const ru = installedRole(
+      { slug: "writer", language: "ru", version: 5 },
+      { id: "ru-role" },
+    );
+    const en = installedRole(
+      { slug: "writer", language: "en", version: 1 },
+      { id: "en-role" },
+    );
+    const result = catalogRoleInstallState(catalogRole, [ru, en], "en");
+    expect(result).toEqual({
+      state: "update",
+      installed: en,
+      fromVersion: 1,
+      toVersion: 3,
+    });
+  });
+
+  it("ignores manually-created roles (no source) sharing the name", () => {
+    const manual = installedRole(
+      { slug: "writer", language: "en", version: 9 },
+      { source: null },
+    );
+    const result = catalogRoleInstallState(catalogRole, [manual], "en");
+    expect(result).toEqual({ state: "import" });
+  });
+});

apps/client/src/features/ai-chat/utils/catalog-role-install-state.ts

@@ -0,0 +1,49 @@
+import type {
+  IAiRole,
+  IAiRoleCatalogRole,
+} from "@/features/ai-chat/types/ai-chat.types.ts";
+
+/**
+ * The install state of a single catalog role relative to the workspace's
+ * existing roles. Extracted as a pure function so the catalog modal's role-state
+ * computation is unit-testable without mounting the component (mirrors the
+ * `roleLaunchMessage` precedent in role-launch.ts).
+ *
+ * A catalog role is matched to an installed role by BOTH `source.slug` and
+ * `source.language`: the same slug in a different language is a separate install
+ * (so it shows as "import", not "installed"). When matched, the installed source
+ * version decides the state:
+ *   - no match                          -> "import"
+ *   - matched & installed version >= catalog version -> "installed"
+ *   - matched & installed version <  catalog version -> "update" (from -> to)
+ */
+export type CatalogRoleInstallState =
+  | { state: "import" }
+  | { state: "installed"; installed: IAiRole }
+  | {
+      state: "update";
+      installed: IAiRole;
+      fromVersion: number;
+      toVersion: number;
+    };
+
+export function catalogRoleInstallState(
+  role: Pick<IAiRoleCatalogRole, "slug" | "version">,
+  workspaceRoles: IAiRole[],
+  language: string,
+): CatalogRoleInstallState {
+  const installed = workspaceRoles.find(
+    (r) => r.source?.slug === role.slug && r.source?.language === language,
+  );
+  if (!installed) return { state: "import" };
+  const fromVersion = installed.source?.version ?? 0;
+  if (fromVersion >= role.version) {
+    return { state: "installed", installed };
+  }
+  return {
+    state: "update",
+    installed,
+    fromVersion,
+    toVersion: role.version,
+  };
+}

apps/client/src/features/editor/components/emoji-menu/utils.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  sortFrequentlyUsedEmoji,
+  getFrequentlyUsedEmoji,
+  LOCAL_STORAGE_FREQUENT_KEY,
+} from "./utils";
+
+describe("sortFrequentlyUsedEmoji", () => {
+  it("orders known emoji by descending usage count", async () => {
+    const result = await sortFrequentlyUsedEmoji({
+      rocket: 1,
+      joy: 9,
+      heart_eyes: 5,
+    });
+    expect(result.map((e) => e.id)).toEqual(["joy", "heart_eyes", "rocket"]);
+  });
+
+  it("caps the result at the top 5 most frequent", async () => {
+    const result = await sortFrequentlyUsedEmoji({
+      rocket: 1,
+      joy: 2,
+      heart_eyes: 3,
+      grinning: 4,
+      laughing: 5,
+      scream: 6,
+      sweat_smile: 7,
+    });
+    expect(result).toHaveLength(5);
+    // Highest counts retained, lowest (rocket:1, joy:2) dropped.
+    expect(result.map((e) => e.id)).toEqual([
+      "sweat_smile",
+      "scream",
+      "laughing",
+      "grinning",
+      "heart_eyes",
+    ]);
+  });
+
+  it("drops ids that have no matching emoji in the index", async () => {
+    const result = await sortFrequentlyUsedEmoji({
+      __definitely_not_a_real_emoji_id__: 100,
+      rocket: 1,
+    });
+    expect(result.map((e) => e.id)).toEqual(["rocket"]);
+  });
+
+  it("maps each entry to its native glyph and a command", async () => {
+    const [entry] = await sortFrequentlyUsedEmoji({ rocket: 5 });
+    expect(entry.id).toBe("rocket");
+    expect(typeof entry.emoji).toBe("string");
+    expect(entry.emoji.length).toBeGreaterThan(0);
+    expect(typeof entry.command).toBe("function");
+  });
+
+  it("returns an empty list for empty input", async () => {
+    expect(await sortFrequentlyUsedEmoji({})).toEqual([]);
+  });
+});
+
+describe("getFrequentlyUsedEmoji", () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it("falls back to the default map when nothing is stored", () => {
+    const result = getFrequentlyUsedEmoji();
+    expect(result["+1"]).toBe(10);
+    expect(result["rocket"]).toBe(1);
+  });
+
+  it("parses a valid stored JSON map", () => {
+    localStorage.setItem(
+      LOCAL_STORAGE_FREQUENT_KEY,
+      JSON.stringify({ rocket: 42 }),
+    );
+    expect(getFrequentlyUsedEmoji()).toEqual({ rocket: 42 });
+  });
+
+  // BUG (issue #204, Phase 2): getFrequentlyUsedEmoji() does an unprotected
+  // JSON.parse() of the raw localStorage value. A corrupt value (e.g. truncated
+  // by a crash, or written by another tab/extension) makes the emoji menu throw
+  // on open instead of degrading gracefully to the default set.
+  //
+  // Documented with it.fails: this asserts the DESIRED behavior (return a sane
+  // default, never throw). It currently FAILS because the function throws —
+  // flip to `it()` once utils.ts guards the JSON.parse.
+  it.fails(
+    "should degrade to a sane default on corrupt localStorage (currently throws)",
+    () => {
+      localStorage.setItem(LOCAL_STORAGE_FREQUENT_KEY, "{not valid json");
+      let result: Record<string, number> | undefined;
+      expect(() => {
+        result = getFrequentlyUsedEmoji();
+      }).not.toThrow();
+      // Should hand back a usable, non-empty map rather than nothing.
+      expect(result).toBeTruthy();
+      expect(Object.keys(result ?? {}).length).toBeGreaterThan(0);
+    },
+  );
+});

apps/client/src/features/editor/components/table/handle/lib/sort-cells.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from "vitest";
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import {
+  isHeaderCell,
+  sortItems,
+  weaveItems,
+  type SortableItem,
+} from "./sort-cells";
+
+// isHeaderCell only reads node.type.name and node.attrs?.header, so a minimal
+// duck-typed node is sufficient (no real ProseMirror schema needed).
+function fakeNode(typeName: string, attrs: Record<string, unknown> = {}) {
+  return { type: { name: typeName }, attrs } as unknown as ProseMirrorNode;
+}
+
+function item<T>(
+  payload: T,
+  text: string,
+  originalOrder: number,
+  opts: { isHeader?: boolean; isEmpty?: boolean } = {},
+): SortableItem<T> {
+  return {
+    payload,
+    text,
+    originalOrder,
+    isHeader: opts.isHeader ?? false,
+    isEmpty: opts.isEmpty ?? text.trim() === "",
+  };
+}
+
+describe("isHeaderCell", () => {
+  it("recognizes the tableHeader node type", () => {
+    expect(isHeaderCell(fakeNode("tableHeader"))).toBe(true);
+  });
+
+  it("recognizes the snake_case table_header node type", () => {
+    expect(isHeaderCell(fakeNode("table_header"))).toBe(true);
+  });
+
+  it("treats a plain cell with header:true attr as a header", () => {
+    expect(isHeaderCell(fakeNode("tableCell", { header: true }))).toBe(true);
+  });
+
+  it("returns false for a regular body cell", () => {
+    expect(isHeaderCell(fakeNode("tableCell", { header: false }))).toBe(false);
+    expect(isHeaderCell(fakeNode("tableCell"))).toBe(false);
+  });
+});
+
+describe("sortItems", () => {
+  it("sorts non-empty rows ascending using a base/numeric collator", () => {
+    const data = [
+      item("c", "cherry", 0),
+      item("a", "Apple", 1),
+      item("b", "banana", 2),
+    ];
+    expect(sortItems(data, "asc").map((i) => i.payload)).toEqual([
+      "a",
+      "b",
+      "c",
+    ]);
+  });
+
+  it("sorts descending when direction is desc", () => {
+    const data = [
+      item("a", "apple", 0),
+      item("b", "banana", 1),
+      item("c", "cherry", 2),
+    ];
+    expect(sortItems(data, "desc").map((i) => i.payload)).toEqual([
+      "c",
+      "b",
+      "a",
+    ]);
+  });
+
+  it("orders numerically, not lexically (numeric collator)", () => {
+    const data = [
+      item("ten", "10", 0),
+      item("two", "2", 1),
+      item("one", "1", 2),
+    ];
+    expect(sortItems(data, "asc").map((i) => i.payload)).toEqual([
+      "one",
+      "two",
+      "ten",
+    ]);
+  });
+
+  it("always pushes empty cells to the bottom regardless of direction", () => {
+    const data = [
+      item("empty", "", 0, { isEmpty: true }),
+      item("b", "banana", 1),
+      item("a", "apple", 2),
+    ];
+    const asc = sortItems(data, "asc");
+    expect(asc.map((i) => i.payload)).toEqual(["a", "b", "empty"]);
+    const desc = sortItems(data, "desc");
+    // Empty stays last even when the rest is reversed.
+    expect(desc[desc.length - 1].payload).toBe("empty");
+  });
+
+  it("keeps empty cells in their original relative order (stable)", () => {
+    const data = [
+      item("e1", "", 5, { isEmpty: true }),
+      item("e2", "", 2, { isEmpty: true }),
+      item("a", "apple", 9),
+    ];
+    const sorted = sortItems(data, "asc");
+    // e2 (originalOrder 2) before e1 (originalOrder 5).
+    expect(sorted.map((i) => i.payload)).toEqual(["a", "e2", "e1"]);
+  });
+
+  it("does not mutate the input array", () => {
+    const data = [item("b", "banana", 0), item("a", "apple", 1)];
+    const snapshot = data.map((i) => i.payload);
+    sortItems(data, "asc");
+    expect(data.map((i) => i.payload)).toEqual(snapshot);
+  });
+});
+
+describe("weaveItems", () => {
+  it("keeps header rows pinned in place and fills body slots from sorted data", () => {
+    const header = item("H", "Name", 0, { isHeader: true });
+    const all = [
+      header,
+      item("orig-b", "b", 1),
+      item("orig-a", "a", 2),
+    ];
+    const sortedBody = [item("orig-a", "a", 2), item("orig-b", "b", 1)];
+
+    const woven = weaveItems(all, sortedBody);
+    // Header never moves out of row 0...
+    expect(woven[0]).toBe(header);
+    // ...and the body positions are filled in sorted order.
+    expect(woven.slice(1).map((i) => i.payload)).toEqual(["orig-a", "orig-b"]);
+  });
+
+  it("does not consume body data for header positions (header stays at top)", () => {
+    const header = item("H", "head", 0, { isHeader: true });
+    const all = [header, item("x", "x", 1), item("y", "y", 2)];
+    const sortedBody = [item("y", "y", 2), item("x", "x", 1)];
+    const woven = weaveItems(all, sortedBody);
+    expect(woven[0].isHeader).toBe(true);
+    expect(woven.filter((i) => !i.isHeader).map((i) => i.payload)).toEqual([
+      "y",
+      "x",
+    ]);
+  });
+
+  it("interleaves correctly when a header sits between body rows", () => {
+    const header = item("H", "head", 1, { isHeader: true });
+    const all = [
+      item("b1", "b1", 0),
+      header,
+      item("b2", "b2", 2),
+    ];
+    const sortedBody = [item("b2", "b2", 2), item("b1", "b1", 0)];
+    const woven = weaveItems(all, sortedBody);
+    expect(woven.map((i) => i.payload)).toEqual(["b2", "H", "b1"]);
+    expect(woven[1]).toBe(header);
+  });
+});

apps/client/src/features/editor/editor-sync-state.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { WebSocketStatus } from "@hocuspocus/provider";
+import { isCollabSynced, isBodyEditable } from "./editor-sync-state";
+
+describe("isCollabSynced", () => {
+  it("is true only when Connected and synced", () => {
+    expect(isCollabSynced(WebSocketStatus.Connected, true)).toBe(true);
+  });
+
+  it("is false while connecting or not yet synced", () => {
+    expect(isCollabSynced(WebSocketStatus.Connecting, true)).toBe(false);
+    expect(isCollabSynced(WebSocketStatus.Connected, false)).toBe(false);
+    expect(isCollabSynced(WebSocketStatus.Disconnected, true)).toBe(false);
+  });
+});
+
+describe("isBodyEditable (pre-sync data-loss gate, #218)", () => {
+  const base = { editable: true, inEditMode: true, showStatic: false };
+
+  it("allows editing only after the static (pre-sync) phase ends", () => {
+    expect(isBodyEditable(base)).toBe(true);
+  });
+
+  it("never editable while the static read-only editor is shown", () => {
+    expect(isBodyEditable({ ...base, showStatic: true })).toBe(false);
+  });
+
+  it("honors read-only and view mode", () => {
+    expect(isBodyEditable({ ...base, editable: false })).toBe(false);
+    expect(isBodyEditable({ ...base, inEditMode: false })).toBe(false);
+  });
+});

apps/client/src/features/editor/editor-sync-state.ts

@@ -0,0 +1,32 @@
+import { WebSocketStatus } from "@hocuspocus/provider";
+
+/**
+ * The collab document is usable only once the provider is Connected AND has
+ * synced (both the local IndexedDB replica and the remote room). Until then the
+ * in-browser Y.Doc is empty/stale, so edits would either be dropped or clobber
+ * the server's authoritative doc when it finally arrives.
+ */
+export function isCollabSynced(
+  status: WebSocketStatus | string,
+  isSynced: boolean,
+): boolean {
+  return status === WebSocketStatus.Connected && isSynced;
+}
+
+/**
+ * Whether the page BODY editor may accept edits.
+ *
+ * `showStatic` is true during the pre-sync window (a read-only static editor is
+ * shown). Gating editability on `!showStatic` guarantees the body never becomes
+ * editable before the collab doc is synced, so early keystrokes on a freshly
+ * created page can't land only in local ProseMirror and then be lost when the
+ * server's initial empty doc syncs in (#218). Read-only and view modes are
+ * still honored via `editable`/`inEditMode`.
+ */
+export function isBodyEditable(opts: {
+  editable: boolean;
+  inEditMode: boolean;
+  showStatic: boolean;
+}): boolean {
+  return opts.editable && opts.inEditMode && !opts.showStatic;
+}

apps/client/src/features/editor/extensions/markdown-clipboard.canonicalize.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect } from "vitest";
+import { Editor } from "@tiptap/core";
+import { Document } from "@tiptap/extension-document";
+import { Paragraph } from "@tiptap/extension-paragraph";
+import { Text } from "@tiptap/extension-text";
+import { Node as PMNode, Fragment, Slice } from "@tiptap/pm/model";
+import {
+  FootnoteReference,
+  FootnotesList,
+  FootnoteDefinition,
+  FOOTNOTE_REFERENCE_NAME,
+  FOOTNOTE_DEFINITION_NAME,
+  FOOTNOTES_LIST_NAME,
+} from "@docmost/editor-ext";
+import { canonicalizePastedFootnotes } from "./markdown-clipboard";
+
+/**
+ * A markdown paste builds its ProseMirror fragment via DOM -> parseSlice and is
+ * applied with a manual transaction (handlePaste returns true), so it bypasses
+ * the editor's footnoteSyncPlugin — which never reorders an existing list. These
+ * tests pin canonicalizePastedFootnotes, the focused hook that makes a pasted
+ * out-of-order markdown footnote block come out canonical (issue #228).
+ */
+
+const extensions = [
+  Document,
+  Paragraph,
+  Text,
+  FootnoteReference,
+  FootnotesList,
+  FootnoteDefinition,
+];
+
+function makeSchema() {
+  const editor = new Editor({ extensions, content: { type: "doc", content: [] } });
+  const { schema } = editor;
+  return { editor, schema };
+}
+
+/** List footnote def ids of the (single) footnotesList in a slice, in order. */
+function listIds(slice: Slice): string[] {
+  const out: string[] = [];
+  slice.content.forEach((node: PMNode) => {
+    if (node.type.name === FOOTNOTES_LIST_NAME) {
+      node.content.forEach((def: PMNode) => {
+        if (def.type.name === FOOTNOTE_DEFINITION_NAME) out.push(def.attrs.id);
+      });
+    }
+  });
+  return out;
+}
+
+function hasList(slice: Slice): boolean {
+  let found = false;
+  slice.content.forEach((n: PMNode) => {
+    if (n.type.name === FOOTNOTES_LIST_NAME) found = true;
+  });
+  return found;
+}
+
+describe("canonicalizePastedFootnotes", () => {
+  it("reorders a pasted block to reference order, dedups reuse, drops orphans", () => {
+    const { editor, schema } = makeSchema();
+    // Body references c, a, b (and again a => reuse); definitions a, b, c, z
+    // (z is an orphan) — the exact shape a markdown paste produces.
+    const slice = new Slice(
+      Fragment.fromArray([
+        schema.nodes.paragraph.create(null, [
+          schema.text("body "),
+          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "c" }),
+          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "a" }),
+          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "b" }),
+          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "a" }),
+        ]),
+        schema.nodes[FOOTNOTES_LIST_NAME].create(null, [
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "a" }, [
+            schema.nodes.paragraph.create(null, [schema.text("note A")]),
+          ]),
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "b" }, [
+            schema.nodes.paragraph.create(null, [schema.text("note B")]),
+          ]),
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "c" }, [
+            schema.nodes.paragraph.create(null, [schema.text("note C")]),
+          ]),
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "z" }, [
+            schema.nodes.paragraph.create(null, [schema.text("orphan")]),
+          ]),
+        ]),
+      ]),
+      0,
+      0,
+    );
+
+    const out = canonicalizePastedFootnotes(slice, schema);
+    // Reference order, orphan z dropped, reused a appears once.
+    expect(listIds(out)).toEqual(["c", "a", "b"]);
+    editor.destroy();
+  });
+
+  it("leaves a reference-ONLY paste untouched (no synthesized definitions)", () => {
+    // A paste that reuses an id defined in the TARGET doc must NOT gain a
+    // synthesized empty definition here — it carries no footnotesList of its own.
+    const { editor, schema } = makeSchema();
+    const slice = new Slice(
+      Fragment.from(
+        schema.nodes.paragraph.create(null, [
+          schema.text("see "),
+          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "a" }),
+        ]),
+      ),
+      0,
+      0,
+    );
+    const out = canonicalizePastedFootnotes(slice, schema);
+    expect(hasList(out)).toBe(false);
+    expect(out).toBe(slice); // returned unchanged (same reference)
+    editor.destroy();
+  });
+
+  it("leaves a definitions-ONLY paste untouched (no references -> no empty paste)", () => {
+    // A whole-block paste of ONLY definitions (a footnotesList with no matching
+    // footnoteReference anywhere in the selection). Canonicalizing it would strip
+    // the reference-less list -> an EMPTY paste, losing the pasted text. The hook
+    // must leave such a block untouched.
+    const { editor, schema } = makeSchema();
+    const slice = new Slice(
+      Fragment.fromArray([
+        schema.nodes[FOOTNOTES_LIST_NAME].create(null, [
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "a" }, [
+            schema.nodes.paragraph.create(null, [schema.text("note A")]),
+          ]),
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "b" }, [
+            schema.nodes.paragraph.create(null, [schema.text("note B")]),
+          ]),
+        ]),
+      ]),
+      0,
+      0,
+    );
+    const out = canonicalizePastedFootnotes(slice, schema);
+    expect(out).toBe(slice); // returned unchanged (same reference, content kept)
+    expect(listIds(out)).toEqual(["a", "b"]);
+    editor.destroy();
+  });
+
+  it("leaves an open (partial) slice untouched even if it carries a list", () => {
+    // An open slice (openStart/openEnd > 0) is a partial selection, not a
+    // standalone block, so it is returned as-is BEFORE any footnote handling.
+    const { editor, schema } = makeSchema();
+    const slice = new Slice(
+      Fragment.fromArray([
+        schema.nodes.paragraph.create(null, [
+          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "a" }),
+        ]),
+        schema.nodes[FOOTNOTES_LIST_NAME].create(null, [
+          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "a" }, [
+            schema.nodes.paragraph.create(null, [schema.text("A")]),
+          ]),
+        ]),
+      ]),
+      1,
+      1,
+    );
+    const out = canonicalizePastedFootnotes(slice, schema);
+    expect(out).toBe(slice);
+    editor.destroy();
+  });
+});

apps/client/src/features/editor/extensions/markdown-clipboard.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from "vitest";
+import { normalizeTableColumnWidths } from "./markdown-clipboard";
+
+// normalizeTableColumnWidths mutates a DOM subtree (jsdom provides document).
+function root(html: string): HTMLElement {
+  const div = document.createElement("div");
+  div.innerHTML = html;
+  return div;
+}
+
+function firstRowColWidths(container: HTMLElement): (string | null)[] {
+  const row = container.querySelector("tr");
+  return Array.from(row?.children ?? []).map((c) =>
+    c.getAttribute("colwidth"),
+  );
+}
+
+describe("normalizeTableColumnWidths", () => {
+  // The core "squash столбцов вставленной таблицы" concern: markdown has no
+  // widths, so every pasted table would otherwise render at table-layout:fixed
+  // / 100% and squash columns. This stamps an explicit per-column px width.
+  it("stamps the default px width on every column when no widths are present", () => {
+    const container = root(
+      "<table><tbody><tr><td>a</td><td>b</td><td>c</td></tr></tbody></table>",
+    );
+    normalizeTableColumnWidths(container);
+    expect(firstRowColWidths(container)).toEqual(["150", "150", "150"]);
+  });
+
+  it("derives column widths from a colgroup", () => {
+    const container = root(
+      "<table>" +
+        '<colgroup><col style="width:200px"><col style="width:80px"></colgroup>' +
+        "<tbody><tr><td>a</td><td>b</td></tr></tbody>" +
+        "</table>",
+    );
+    normalizeTableColumnWidths(container);
+    expect(firstRowColWidths(container)).toEqual(["200", "80"]);
+  });
+
+  it("derives column widths from per-cell width attributes", () => {
+    const container = root(
+      '<table><tbody><tr><td width="120">a</td><td width="90">b</td></tr></tbody></table>',
+    );
+    normalizeTableColumnWidths(container);
+    expect(firstRowColWidths(container)).toEqual(["120", "90"]);
+  });
+
+  it("derives column widths from a cell style:width:px", () => {
+    const container = root(
+      '<table><tbody><tr><td style="width:140px">a</td><td>b</td></tr></tbody></table>',
+    );
+    normalizeTableColumnWidths(container);
+    // First cell width parsed; a fully-unmeasured column is left untouched
+    // (the 100 fallback only fills in NULL gaps inside an otherwise-measured
+    // multi-column slice, e.g. a colspan).
+    expect(firstRowColWidths(container)).toEqual(["140", null]);
+  });
+
+  it("fills a null gap inside a measured colspanned slice with 100", () => {
+    // colgroup gives [200, null]; the single colspan=2 cell spans both, so its
+    // slice is [200, null] -> the null is backfilled to 100 => "200,100".
+    const container = root(
+      "<table>" +
+        '<colgroup><col style="width:200px"><col></colgroup>' +
+        '<tbody><tr><td colspan="2">merged</td></tr></tbody>' +
+        "</table>",
+    );
+    normalizeTableColumnWidths(container);
+    expect(firstRowColWidths(container)).toEqual(["200,100"]);
+  });
+
+  it("splits a measured width across a colspanned cell", () => {
+    const container = root(
+      '<table><tbody><tr><td colspan="2" width="300">merged</td><td width="100">x</td></tr></tbody></table>',
+    );
+    normalizeTableColumnWidths(container);
+    // 300 / colspan(2) = 150 per underlying column => "150,150" on the merged cell.
+    expect(firstRowColWidths(container)).toEqual(["150,150", "100"]);
+  });
+
+  it("falls back to the default width per spanned column when nothing is measurable", () => {
+    const container = root(
+      '<table><tbody><tr><td colspan="2">merged</td><td>x</td></tr></tbody></table>',
+    );
+    normalizeTableColumnWidths(container);
+    expect(firstRowColWidths(container)).toEqual(["150,150", "150"]);
+  });
+
+  it("leaves cells that already have a colwidth untouched", () => {
+    const container = root(
+      '<table><tbody><tr><td colwidth="42">a</td><td>b</td></tr></tbody></table>',
+    );
+    normalizeTableColumnWidths(container);
+    expect(firstRowColWidths(container)).toEqual(["42", "150"]);
+  });
+
+  it("normalizes every table in the subtree", () => {
+    const container = root(
+      "<table><tbody><tr><td>a</td></tr></tbody></table>" +
+        "<table><tbody><tr><td>b</td><td>c</td></tr></tbody></table>",
+    );
+    normalizeTableColumnWidths(container);
+    const tables = container.querySelectorAll("table");
+    const widths = Array.from(tables).map((t) =>
+      Array.from(t.querySelector("tr")!.children).map((c) =>
+        c.getAttribute("colwidth"),
+      ),
+    );
+    expect(widths).toEqual([["150"], ["150", "150"]]);
+  });
+
+  it("only annotates the first row (column widths are defined once)", () => {
+    const container = root(
+      "<table><tbody>" +
+        "<tr><td>a</td><td>b</td></tr>" +
+        "<tr><td>c</td><td>d</td></tr>" +
+        "</tbody></table>",
+    );
+    normalizeTableColumnWidths(container);
+    const rows = container.querySelectorAll("tr");
+    expect(
+      Array.from(rows[1].children).map((c) => c.getAttribute("colwidth")),
+    ).toEqual([null, null]);
+  });
+});

apps/client/src/features/editor/extensions/markdown-clipboard.ts

@@ -3,7 +3,14 @@ import { Extension } from "@tiptap/core";
 import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
 import { DOMParser, DOMSerializer, Fragment, Slice } from "@tiptap/pm/model";
 import { find } from "linkifyjs";
-import { markdownToHtml, htmlToMarkdown } from "@docmost/editor-ext";
+import {
+  markdownToHtml,
+  htmlToMarkdown,
+  canonicalizeFootnotes,
+  FOOTNOTES_LIST_NAME,
+  FOOTNOTE_REFERENCE_NAME,
+} from "@docmost/editor-ext";
+import type { Schema } from "@tiptap/pm/model";
 
 export const MarkdownClipboard = Extension.create({
   name: "markdownClipboard",
@@ -83,12 +90,25 @@ export const MarkdownClipboard = Extension.create({
             const body = elementFromString(parsed);
             normalizeTableColumnWidths(body);
 
-            const contentNodes = DOMParser.fromSchema(
+            const parsedSlice = DOMParser.fromSchema(
               this.editor.schema,
             ).parseSlice(body, {
               preserveWhitespace: true,
             });
 
+            // A markdown paste builds its ProseMirror fragment directly (DOM ->
+            // parseSlice), bypassing the editor's footnoteSyncPlugin, which never
+            // reorders an existing list. So a pasted markdown block whose footnote
+            // definitions are out of order (or contains orphan defs) would be
+            // stored out of order. Canonicalize the self-contained pasted block so
+            // its footnotes come out reference-ordered, deduped and orphan-free
+            // (issue #228). See canonicalizePastedFootnotes for why this is scoped
+            // to whole-block pastes that carry their own footnotesList.
+            const contentNodes = canonicalizePastedFootnotes(
+              parsedSlice,
+              this.editor.schema,
+            );
+
             tr.replaceRange(from, to, contentNodes);
             const insertEnd = tr.mapping.map(from, 1);
             tr.setSelection(TextSelection.near(tr.doc.resolve(Math.max(from, insertEnd - 2)), -1));
@@ -133,6 +153,54 @@ export const MarkdownClipboard = Extension.create({
   },
 });
 
+/**
+ * Reorder/dedup the footnotes of a SELF-CONTAINED pasted markdown block to the
+ * canonical invariant (the live footnoteSyncPlugin never reorders an existing
+ * list, so an out-of-order pasted block would otherwise persist out of order).
+ *
+ * Scoped deliberately to whole-block pastes (openStart/openEnd === 0) that carry
+ * their OWN footnotesList: canonicalizeFootnotes would synthesize empty
+ * definitions for any reference lacking a definition, which is correct for a
+ * standalone block but would be wrong for a reference-only paste that REUSES a
+ * footnote already defined in the target document — so those are left untouched
+ * for the paste/sync plugins to merge. Residual: when the pasted block is merged
+ * into a doc that already has footnotes, ordering RELATIVE to the pre-existing
+ * footnotes is still governed by the sync plugin (which does not reorder).
+ *
+ * Also requires at least one footnoteReference in the selection: a definitions-ONLY
+ * paste (`[^a]: …` with no `[^a]` reference in the same block) has no references,
+ * so canonicalizeFootnotes would drop the whole list and the paste would come out
+ * EMPTY — losing the pasted text. Such a block is left as-is for the sync plugin.
+ */
+export function canonicalizePastedFootnotes(slice: Slice, schema: Schema): Slice {
+  if (slice.openStart !== 0 || slice.openEnd !== 0) return slice;
+
+  let hasFootnotesList = false;
+  let hasReference = false;
+  slice.content.forEach((node) => {
+    if (node.type.name === FOOTNOTES_LIST_NAME) hasFootnotesList = true;
+    // footnoteReference is an inline atom, never a top-level slice child here
+    // (this function early-returns for open slices, so children are whole
+    // blocks), so it is only reachable by descending.
+    node.descendants((child) => {
+      if (child.type.name === FOOTNOTE_REFERENCE_NAME) hasReference = true;
+    });
+  });
+  if (!hasFootnotesList) return slice;
+  // No reference anywhere -> a definitions-only paste; canonicalizing would strip
+  // the reference-less list (empty paste). Leave it untouched.
+  if (!hasReference) return slice;
+
+  const content = slice.content.toJSON();
+  if (!Array.isArray(content)) return slice;
+
+  const canonical = canonicalizeFootnotes({ type: "doc", content }) as {
+    content?: unknown[];
+  };
+  const fragment = Fragment.fromJSON(schema, canonical.content ?? []);
+  return new Slice(fragment, 0, 0);
+}
+
 function elementFromString(value) {
   // add a wrapper to preserve leading and trailing whitespace
   const wrappedValue = `<body>${value}</body>`;

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

@@ -84,6 +84,10 @@ import { PageEmbedLookupProvider } from "@/features/editor/components/page-embed
 import { PageEmbedAncestryProvider } from "@/features/editor/components/page-embed/page-embed-ancestry-context";
 import PageEmbedPicker from "@/features/editor/components/page-embed/page-embed-picker";
 import { useTranslation } from "react-i18next";
+import {
+  isBodyEditable,
+  isCollabSynced,
+} from "@/features/editor/editor-sync-state";
 
 interface PageEditorProps {
   pageId: string;
@@ -440,6 +444,9 @@ export default function PageEditor({
 
   const isSynced = isLocalSynced && isRemoteSynced;
 
+  const hasConnectedOnceRef = useRef(false);
+  const [showStatic, setShowStatic] = useState(true);
+
   useEffect(() => {
     const timeout = setTimeout(() => {
       if (yjsConnectionStatus === WebSocketStatus.Connecting || !isSynced) {
@@ -451,17 +458,21 @@ export default function PageEditor({
   }, [yjsConnectionStatus, isSynced]);
   useEffect(() => {
     if (!editor) return;
-    editor.setEditable(editable && currentPageEditMode === PageEditMode.Edit);
-  }, [currentPageEditMode, editor, editable]);
-
-  const hasConnectedOnceRef = useRef(false);
-  const [showStatic, setShowStatic] = useState(true);
+    // Keep the body read-only until the collab doc has synced (showStatic), so
+    // early keystrokes on a freshly created page can't be lost (#218).
+    editor.setEditable(
+      isBodyEditable({
+        editable,
+        inEditMode: currentPageEditMode === PageEditMode.Edit,
+        showStatic,
+      }),
+    );
+  }, [currentPageEditMode, editor, editable, showStatic]);
 
   useEffect(() => {
     if (
       !hasConnectedOnceRef.current &&
-      yjsConnectionStatus === WebSocketStatus.Connected &&
-      isSynced
+      isCollabSynced(yjsConnectionStatus, isSynced)
     ) {
       hasConnectedOnceRef.current = true;
       setShowStatic(false);
@@ -473,17 +484,43 @@ export default function PageEditor({
       <PageEmbedLookupProvider>
         <PageEmbedAncestryProvider hostPageId={pageId}>
       {showStatic ? (
-        <EditorProvider
-          editable={false}
-          immediatelyRender={true}
-          extensions={mainExtensions}
-          content={content}
-          editorProps={{
-            attributes: {
-              "aria-label": t("Page content"),
-            },
-          }}
-        />
+        <div style={{ position: "relative" }}>
+          {/* Surface the pre-sync read-only window so edits typed before the
+              collab provider connects aren't silently swallowed (#218). Shown
+              only when the user is otherwise allowed to edit. */}
+          {editable && currentPageEditMode === PageEditMode.Edit && (
+            <div
+              role="status"
+              aria-live="polite"
+              className="print-hide"
+              style={{
+                position: "absolute",
+                top: 0,
+                right: 0,
+                zIndex: 2,
+                padding: "2px 8px",
+                fontSize: "12px",
+                borderRadius: "4px",
+                background: "var(--mantine-color-gray-light)",
+                color: "var(--mantine-color-dimmed)",
+                pointerEvents: "none",
+              }}
+            >
+              {t("Connecting… (read-only)")}
+            </div>
+          )}
+          <EditorProvider
+            editable={false}
+            immediatelyRender={true}
+            extensions={mainExtensions}
+            content={content}
+            editorProps={{
+              attributes: {
+                "aria-label": t("Page content"),
+              },
+            }}
+          />
+        </div>
       ) : (
         <div className="editor-container" style={{ position: "relative" }}>
           <div ref={menuContainerRef}>

apps/client/src/features/home/components/new-note-button.tsx

@@ -1,4 +1,4 @@
-import { Button, Group, Menu, Text } from "@mantine/core";
+import { Button, Menu, Stack, Text } from "@mantine/core";
 import { IconHourglass, IconPlus } from "@tabler/icons-react";
 import { ReactNode } from "react";
 import { useNavigate } from "react-router-dom";
@@ -21,11 +21,15 @@ function CreateNoteButton({
   temporary,
   label,
   icon,
+  color,
 }: {
   writableSpaces: ISpace[];
   temporary: boolean;
   label: string;
   icon: ReactNode;
+  // Mantine color token; lets the temporary action tint toward the warm
+  // orange/amber used by the clock marker + banner while "New note" stays neutral.
+  color: string;
 }) {
   const { t } = useTranslation();
   const navigate = useNavigate();
@@ -54,7 +58,8 @@ function CreateNoteButton({
       <Button
         size="md"
         variant="light"
-        color="gray"
+        color={color}
+        fullWidth
         leftSection={icon}
         loading={isPending}
         onClick={() => createNote(writableSpaces[0])}
@@ -71,7 +76,8 @@ function CreateNoteButton({
         <Button
           size="md"
           variant="light"
-          color="gray"
+          color={color}
+          fullWidth
           leftSection={icon}
           loading={isPending}
         >
@@ -109,8 +115,10 @@ function CreateNoteButton({
 // Prominent home-screen actions to create a new note (page). Because the home
 // screen has no active space, the target space is resolved from the user's
 // writable spaces: created directly when there is one, picked from a dropdown
-// when there are several. Renders two equal-width buttons: a regular note and a
-// temporary note (which auto-moves to Trash after the workspace lifetime).
+// when there are several. Renders two full-width, vertically stacked buttons: a
+// neutral regular note and an orange-tinted temporary note (which auto-moves to
+// Trash after the workspace lifetime). Stacking full-width keeps the longer
+// "New temporary note" label from clipping on narrow mobile widths.
 export default function NewNoteButton() {
   const { t } = useTranslation();
   const { data } = useGetSpacesQuery({ limit: 100 });
@@ -121,19 +129,21 @@ export default function NewNoteButton() {
   if (writableSpaces.length === 0) return null;
 
   return (
-    <Group grow gap="sm">
+    <Stack gap="sm">
       <CreateNoteButton
         writableSpaces={writableSpaces}
         temporary={false}
         label={t("New note")}
         icon={<IconPlus size={18} />}
+        color="gray"
       />
       <CreateNoteButton
         writableSpaces={writableSpaces}
         temporary={true}
         label={t("New temporary note")}
         icon={<IconHourglass size={18} />}
+        color="orange"
       />
-    </Group>
+    </Stack>
   );
 }

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

@@ -0,0 +1,69 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { getDefaultStore } from "jotai";
+
+// Mock the app entry so importing the query module doesn't boot the whole app
+// (it only needs queryClient's cache methods, which we stub here). The spies are
+// declared via vi.hoisted so they exist before the hoisted vi.mock factory runs.
+const { setQueryData, getQueryData, invalidateQueries } = vi.hoisted(() => ({
+  setQueryData: vi.fn(),
+  getQueryData: vi.fn(() => undefined as unknown),
+  invalidateQueries: vi.fn(),
+}));
+vi.mock("@/main.tsx", () => ({
+  queryClient: { setQueryData, getQueryData, invalidateQueries },
+}));
+
+import { syncTemporaryExpiresInCache } from "./page-embed-query";
+import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
+import { SpaceTreeNode } from "@/features/page/tree/types.ts";
+
+const mkNode = (id: string, slugId: string): SpaceTreeNode =>
+  ({
+    id,
+    slugId,
+    name: id,
+    position: "a0",
+    spaceId: "space-1",
+    parentPageId: null,
+    hasChildren: false,
+    children: [],
+  }) as unknown as SpaceTreeNode;
+
+describe("syncTemporaryExpiresInCache — treeDataAtom patch", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    getQueryData.mockReturnValue(undefined);
+  });
+
+  it("patches the in-tree node's temporaryExpiresAt (sidebar marker updates without reload)", () => {
+    const store = getDefaultStore();
+    const tree = [mkNode("p1", "slug-1"), mkNode("p2", "slug-2")];
+    store.set(treeDataAtom, tree);
+
+    const deadline = "2026-07-01T00:00:00.000Z";
+    syncTemporaryExpiresInCache({ id: "p1", slugId: "slug-1" }, deadline);
+
+    const next = store.get(treeDataAtom);
+    // A new atom value was written...
+    expect(next).not.toBe(tree);
+    // ...the matching node gained the deadline...
+    expect(next.find((n) => n.id === "p1")?.temporaryExpiresAt).toBe(deadline);
+    // ...and the untouched sibling is unchanged.
+    expect(next.find((n) => n.id === "p2")?.temporaryExpiresAt).toBeUndefined();
+  });
+
+  it("leaves the atom value at the SAME reference when the id is absent from the tree (no write)", () => {
+    const store = getDefaultStore();
+    const tree = [mkNode("p1", "slug-1")];
+    store.set(treeDataAtom, tree);
+
+    syncTemporaryExpiresInCache(
+      { id: "not-in-tree", slugId: "missing" },
+      "2026-07-01T00:00:00.000Z",
+    );
+
+    // treeModel.update is a no-op (same reference) for an unknown id, so the
+    // guard skips the store write entirely — same reference back.
+    expect(store.get(treeDataAtom)).toBe(tree);
+  });
+});

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

@@ -1,5 +1,6 @@
 import { useMutation } from "@tanstack/react-query";
 import { notifications } from "@mantine/notifications";
+import { getDefaultStore } from "jotai";
 import {
   toggleTemplate,
   toggleTemporary,
@@ -9,6 +10,9 @@ import type {
   ToggleTemporaryResponse,
 } from "@/features/page-embed/types/page-embed.types";
 import { queryClient } from "@/main.tsx";
+import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
+import { treeModel } from "@/features/page/tree/model/tree-model";
+import { SpaceTreeNode } from "@/features/page/tree/types.ts";
 
 /**
  * After toggling a note's temporary state, mirror the new deadline into the
@@ -30,6 +34,19 @@ export function syncTemporaryExpiresInCache(
       });
     }
   }
+  // Patch the in-memory sidebar tree node so its temporary clock marker
+  // appears/disappears immediately — WITHOUT a reload. The page cache update
+  // above only drives the in-page banner/menu; the sidebar reads
+  // `temporaryExpiresAt` straight off the `treeDataAtom` node. The app uses
+  // jotai's default store (no <Provider>), so `getDefaultStore()` is the same
+  // store the sidebar's hooks read from. `treeModel.update` returns the same
+  // reference (a no-op) when the page isn't in the currently loaded tree.
+  const store = getDefaultStore();
+  const prevTree = store.get(treeDataAtom);
+  const nextTree = treeModel.update(prevTree, page.id, {
+    temporaryExpiresAt,
+  } as Partial<SpaceTreeNode>);
+  if (nextTree !== prevTree) store.set(treeDataAtom, nextTree);
   queryClient.invalidateQueries({
     predicate: (item) =>
       ["sidebar-pages"].includes(item.queryKey[0] as string),

apps/client/src/features/page/components/breadcrumbs/breadcrumb.tsx

@@ -1,7 +1,7 @@
 import { useAtomValue } from "jotai";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
 import React, { useCallback, useEffect, useState } from "react";
-import { findBreadcrumbPath } from "@/features/page/tree/utils";
+import { computeBreadcrumbState } from "./breadcrumb.utils";
 import {
   Button,
   Anchor,
@@ -15,8 +15,12 @@ import { IconCornerDownRightDouble, IconDots } from "@tabler/icons-react";
 import { Link, useParams } from "react-router-dom";
 import classes from "./breadcrumb.module.css";
 import { SpaceTreeNode } from "@/features/page/tree/types.ts";
+import { IPage } from "@/features/page/types/page.types.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import {
+  usePageQuery,
+  usePageBreadcrumbsQuery,
+} from "@/features/page/queries/page-query.ts";
 import { extractPageSlugId } from "@/lib";
 import { useMediaQuery } from "@mantine/hooks";
 import { useTranslation } from "react-i18next";
@@ -38,14 +42,29 @@ export default function Breadcrumb() {
   const { data: currentPage } = usePageQuery({
     pageId: extractPageSlugId(pageSlug),
   });
+  // The page's own ancestor chain, fetched independently of the lazily-built
+  // sidebar tree so a deep page doesn't render a blank breadcrumb for seconds
+  // while the tree backfills (#218).
+  const { data: ancestors } = usePageBreadcrumbsQuery(currentPage?.id);
   const isMobile = useMediaQuery("(max-width: 48em)");
 
   useEffect(() => {
-    if (treeData?.length > 0 && currentPage) {
-      const breadcrumb = findBreadcrumbPath(treeData, currentPage.id);
-      setBreadcrumbNodes(breadcrumb || null);
-    }
-  }, [currentPage?.id, treeData]);
+    if (!currentPage) return;
+
+    // Selection/mapping + stale-clearing live in a pure, unit-tested helper
+    // (#218). It resolves the correct chain when possible and, on a transient
+    // miss, clears a chain left over from a previously-viewed page instead of
+    // showing the wrong trail — while keeping a chain already resolved for THIS
+    // page to avoid a blank flash.
+    setBreadcrumbNodes((previous) =>
+      computeBreadcrumbState(
+        treeData,
+        ancestors as IPage[] | undefined,
+        currentPage.id,
+        previous,
+      ),
+    );
+  }, [currentPage?.id, treeData, ancestors]);
 
   const HiddenNodesTooltipContent = () =>
     breadcrumbNodes?.slice(1, -1).map((node) => (

apps/client/src/features/page/components/breadcrumbs/breadcrumb.utils.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from "vitest";
+import {
+  computeBreadcrumbState,
+  resolveBreadcrumbNodes,
+} from "./breadcrumb.utils";
+import { SpaceTreeNode } from "@/features/page/tree/types.ts";
+import { IPage } from "@/features/page/types/page.types.ts";
+
+// Pure selection/mapping behind the breadcrumb (#218): tree-hit prefers the live
+// sidebar tree, tree-miss maps the page's own ancestors, and "no data" returns
+// null so the component keeps its prior state.
+
+function treeNode(id: string, over?: Partial<SpaceTreeNode>): SpaceTreeNode {
+  return {
+    id,
+    slugId: `slug-${id}`,
+    name: `node-${id}`,
+    icon: null,
+    position: "a",
+    hasChildren: false,
+    spaceId: "space-1",
+    parentPageId: null,
+    children: [],
+    ...over,
+  } as SpaceTreeNode;
+}
+
+function ancestorPage(id: string, over?: Partial<IPage>): IPage {
+  return {
+    id,
+    slugId: `slug-${id}`,
+    title: `title-${id}`,
+    icon: "📄",
+    position: "m",
+    spaceId: "space-1",
+    parentPageId: null,
+    hasChildren: true,
+    ...over,
+  } as IPage;
+}
+
+describe("resolveBreadcrumbNodes", () => {
+  it("tree-hit: returns the path found in the live sidebar tree", () => {
+    const child = treeNode("child");
+    const root = treeNode("root", { hasChildren: true, children: [child] });
+    // findBreadcrumbPath walks the tree; the chain ends at the target page.
+    const result = resolveBreadcrumbNodes([root], [ancestorPage("child")], "child");
+
+    expect(result).not.toBeNull();
+    expect(result!.map((n) => n.id)).toEqual(["root", "child"]);
+    // Came from the tree, NOT the ancestor mapping (icon stays the tree's null).
+    expect(result![result!.length - 1].icon).toBeNull();
+  });
+
+  it("tree-miss: maps the page's own ancestors (title->name, hasChildren default)", () => {
+    // Tree has no node for the target page -> findBreadcrumbPath misses.
+    const unrelated = treeNode("unrelated");
+    const ancestors = [
+      ancestorPage("a", { hasChildren: true }),
+      ancestorPage("b", { hasChildren: undefined as any }),
+    ];
+
+    const result = resolveBreadcrumbNodes([unrelated], ancestors, "missing-page");
+
+    expect(result).not.toBeNull();
+    expect(result!.map((n) => n.id)).toEqual(["a", "b"]);
+    // Non-trivial field transform: title -> name.
+    expect(result![0].name).toBe("title-a");
+    // hasChildren defaults to false when the ancestor row omits it.
+    expect(result![1].hasChildren).toBe(false);
+    expect(result![0].hasChildren).toBe(true);
+  });
+
+  it("falls back to ancestors when the tree is empty", () => {
+    const result = resolveBreadcrumbNodes([], [ancestorPage("a")], "a");
+    expect(result!.map((n) => n.id)).toEqual(["a"]);
+  });
+
+  it("returns null when there is no tree hit and no ancestor data", () => {
+    expect(resolveBreadcrumbNodes([], [], "x")).toBeNull();
+    expect(resolveBreadcrumbNodes(undefined, undefined, "x")).toBeNull();
+    expect(resolveBreadcrumbNodes(null, null, "x")).toBeNull();
+  });
+});
+
+describe("computeBreadcrumbState (stale-chain clearing on navigation)", () => {
+  it("uses a freshly resolved chain when available", () => {
+    const child = treeNode("B");
+    const root = treeNode("root", { hasChildren: true, children: [child] });
+    const next = computeBreadcrumbState([root], null, "B", null);
+    expect(next!.map((n) => n.id)).toEqual(["root", "B"]);
+  });
+
+  it("navigating A->B to a page absent from treeData clears the previous A chain (no stale trail)", () => {
+    // Previous chain ends at page A; we are now on page B, which is not yet in
+    // the lazily-built tree and whose ancestors have not loaded.
+    const previous = [treeNode("rootA"), treeNode("A")];
+    const next = computeBreadcrumbState([treeNode("unrelated")], undefined, "B", previous);
+    // Must NOT keep showing A's (clickable) chain.
+    expect(next).toBeNull();
+  });
+
+  it("keeps a chain that already ends at the current page through a transient miss", () => {
+    // We already resolved B once (chain ends at B); a transient miss must not
+    // blank it.
+    const previous = [treeNode("rootB"), treeNode("B")];
+    const next = computeBreadcrumbState([], undefined, "B", previous);
+    expect(next).toBe(previous);
+  });
+
+  it("returns null when nothing resolves and there is no previous chain", () => {
+    expect(computeBreadcrumbState([], undefined, "B", null)).toBeNull();
+  });
+});

apps/client/src/features/page/components/breadcrumbs/breadcrumb.utils.ts

@@ -0,0 +1,61 @@
+import { IPage } from "@/features/page/types/page.types.ts";
+import { SpaceTreeNode } from "@/features/page/tree/types.ts";
+import { findBreadcrumbPath, pageToTreeNode } from "@/features/page/tree/utils";
+
+/**
+ * Pure selection/mapping for the breadcrumb nodes (#218). Three branches:
+ *   1. tree-hit  — the lazily-built sidebar tree already contains this page's
+ *      ancestor chain, so prefer it (stays live with sidebar renames/moves).
+ *   2. tree-miss — fall back to the page's own ancestor data so a deep page
+ *      resolves immediately instead of rendering a blank breadcrumb for seconds
+ *      while the tree backfills. Mapped through the canonical `pageToTreeNode`
+ *      (title -> name, hasChildren defaulted to false).
+ *   3. neither   — no data yet, return null (the caller decides whether to keep
+ *      a prior chain via computeBreadcrumbState).
+ */
+export function resolveBreadcrumbNodes(
+  treeData: SpaceTreeNode[] | null | undefined,
+  ancestors: IPage[] | null | undefined,
+  pageId: string,
+): SpaceTreeNode[] | null {
+  if (treeData && treeData.length > 0) {
+    const breadcrumb = findBreadcrumbPath(treeData, pageId);
+    if (breadcrumb) {
+      return breadcrumb;
+    }
+  }
+
+  if (ancestors && ancestors.length > 0) {
+    return ancestors.map((page) =>
+      pageToTreeNode(page, { hasChildren: page.hasChildren ?? false }),
+    );
+  }
+
+  return null;
+}
+
+/**
+ * Decide the next breadcrumb state, given the previous one. When a chain
+ * resolves (#218) it always wins. When nothing resolves yet, a stale chain from
+ * a previously-viewed page must be CLEARED rather than left showing the wrong,
+ * clickable trail (the reverse regression of the original blank-breadcrumb fix
+ * when navigating A -> B to a deep page not yet in the lazily-built tree). The
+ * one chain we keep through a transient miss is one that already ends at the
+ * current page — that means we already resolved THIS page, so keeping it avoids
+ * a needless blank flash without ever showing the previous page's chain.
+ */
+export function computeBreadcrumbState(
+  treeData: SpaceTreeNode[] | null | undefined,
+  ancestors: IPage[] | null | undefined,
+  pageId: string,
+  previous: SpaceTreeNode[] | null,
+): SpaceTreeNode[] | null {
+  const resolved = resolveBreadcrumbNodes(treeData, ancestors, pageId);
+  if (resolved) {
+    return resolved;
+  }
+
+  const previousEndsAtCurrentPage =
+    previous != null && previous[previous.length - 1]?.id === pageId;
+  return previousEndsAtCurrentPage ? previous : null;
+}

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

@@ -176,8 +176,8 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
         pageId: page.id,
         temporary: next,
       });
-      // Reflect the new deadline in the page cache so the menu label flips and
-      // any banner updates. The sidebar icon refreshes via its own query.
+      // Reflect the new deadline in the page cache (menu label + banner) AND in
+      // the sidebar tree node so its clock marker updates immediately, no reload.
       syncTemporaryExpiresInCache(page, res.temporaryExpiresAt);
       notifications.show({
         message: next

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

@@ -32,7 +32,7 @@ import {
 import { notifications } from "@mantine/notifications";
 import { IPagination, QueryParams } from "@/lib/types.ts";
 import { queryClient } from "@/main.tsx";
-import { buildTree } from "@/features/page/tree/utils";
+import { buildTree, pageToTreeNode } from "@/features/page/tree/utils";
 import { useEffect } from "react";
 import { validate as isValidUuid } from "uuid";
 import { useTranslation } from "react-i18next";
@@ -210,18 +210,15 @@ export function useRestorePageMutation() {
 
       // Check if the page already exists in the tree (it shouldn't)
       if (!treeModel.find(currentTree, restoredPage.id)) {
-        // Create the tree node data with hasChildren from backend
-        const nodeData: SpaceTreeNode = {
-          id: restoredPage.id,
-          slugId: restoredPage.slugId,
+        // Create the tree node data with hasChildren from backend. Routed
+        // through the canonical mapper so the field copy stays in lockstep with
+        // buildTree. The server NULLS `temporaryExpiresAt` on restore (a restored
+        // page is made permanent), so the mapper carries that null through and
+        // the node correctly shows no clock marker.
+        const nodeData: SpaceTreeNode = pageToTreeNode(restoredPage, {
           name: restoredPage.title || "Untitled",
-          icon: restoredPage.icon,
-          position: restoredPage.position,
-          spaceId: restoredPage.spaceId,
-          parentPageId: restoredPage.parentPageId,
           hasChildren: restoredPage.hasChildren || false,
-          children: [],
-        };
+        });
 
         // Determine the parent and index
         const parentId = restoredPage.parentPageId || null;
@@ -410,6 +407,11 @@ export function invalidateOnCreatePage(data: Partial<IPage>) {
     slugId: data.slugId,
     spaceId: data.spaceId,
     title: data.title,
+    // Carry the death-timer deadline so a note created as temporary keeps its
+    // sidebar clock marker when the tree is rebuilt from this cached entry
+    // (buildTree → mergeRootTrees). Omitting it overwrote the optimistic/socket
+    // node's marker with `undefined`, hiding it until a reload.
+    temporaryExpiresAt: data.temporaryExpiresAt,
   };
 
   let queryKey: QueryKey = null;

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

@@ -37,6 +37,7 @@ import {
 } from "@/features/page-embed/queries/page-embed-query";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
 import { treeModel } from "@/features/page/tree/model/tree-model";
+import { pageToTreeNode } from "@/features/page/tree/utils";
 import { useTreeMutation } from "@/features/page/tree/hooks/use-tree-mutation.ts";
 import type { SpaceTreeNode } from "@/features/page/tree/types.ts";
 import classes from "@/features/page/tree/styles/tree.module.css";
@@ -130,18 +131,14 @@ export function NodeMenu({ node, canEdit }: NodeMenuProps) {
       const currentIndex = siblings?.index ?? 0;
       const newIndex = currentIndex + 1;
 
-      const treeNodeData: SpaceTreeNode = {
-        id: duplicatedPage.id,
-        slugId: duplicatedPage.slugId,
-        name: duplicatedPage.title,
-        position: duplicatedPage.position,
-        spaceId: duplicatedPage.spaceId,
-        parentPageId: duplicatedPage.parentPageId,
-        icon: duplicatedPage.icon,
-        hasChildren: duplicatedPage.hasChildren,
+      // Routed through the canonical mapper so the field copy stays in lockstep
+      // with buildTree. The server does NOT arm a death timer on duplicate (the
+      // copy's `temporaryExpiresAt` defaults to null = permanent), so the mapper
+      // carries that null through and the duplicated node correctly shows no
+      // clock marker — matching the server without a reload.
+      const treeNodeData: SpaceTreeNode = pageToTreeNode(duplicatedPage, {
         canEdit: true,
-        children: [],
-      };
+      });
 
       setData((prev) =>
         treeModel.insert(prev, parentId, treeNodeData, newIndex),

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

@@ -9,6 +9,7 @@ import { treeModel } from "@/features/page/tree/model/tree-model";
 import type { DropOp } from "@/features/page/tree/model/tree-model.types";
 import { dropOpToMovePayload } from "./drop-op-to-move-payload";
 import { SpaceTreeNode } from "@/features/page/tree/types.ts";
+import { pageToTreeNode } from "@/features/page/tree/utils";
 import { IPage } from "@/features/page/types/page.types.ts";
 import {
   useCreatePageMutation,
@@ -139,18 +140,15 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
         throw new Error("Failed to create page");
       }
 
-      const newNode: SpaceTreeNode = {
-        id: createdPage.id,
-        slugId: createdPage.slugId,
+      // Route through the canonical mapper so the field copy (esp.
+      // `temporaryExpiresAt`, which shows the temporary-note clock marker on
+      // optimistic insert) can't drift from buildTree. `name: ""` because a
+      // freshly created page is untitled; `hasChildren: false` because it has no
+      // children yet.
+      const newNode: SpaceTreeNode = pageToTreeNode(createdPage, {
         name: "",
-        position: createdPage.position,
-        spaceId: createdPage.spaceId,
-        parentPageId: createdPage.parentPageId,
         hasChildren: false,
-        // Show the temporary-note icon immediately on optimistic insert.
-        temporaryExpiresAt: createdPage.temporaryExpiresAt,
-        children: [],
-      };
+      });
 
       // Read latest tree at call time. Without this, callers that mutate the
       // tree (e.g. lazy-load children on expand) immediately before calling
@@ -173,7 +171,22 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
       // optimistic node's id IS the real created page id (createdPage.id), so
       // the ids match exactly regardless of which path runs first.
       setData((prev) => {
-        if (treeModel.find(prev, newNode.id)) return prev;
+        const existing = treeModel.find(prev, newNode.id);
+        if (existing) {
+          // The server `addTreeNode` broadcast won the race and already inserted
+          // this node. Older broadcasts could omit `temporaryExpiresAt`, leaving
+          // a temporary note WITHOUT its clock marker until reload; patch it on
+          // from the authoritative create response so the marker shows now.
+          if (
+            newNode.temporaryExpiresAt &&
+            !(existing as SpaceTreeNode).temporaryExpiresAt
+          ) {
+            return treeModel.update(prev, newNode.id, {
+              temporaryExpiresAt: newNode.temporaryExpiresAt,
+            } as Partial<SpaceTreeNode>);
+          }
+          return prev;
+        }
         return treeModel.insert(prev, parentId, newNode, lastIndex);
       });
 

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

@@ -393,6 +393,101 @@ describe("handleCreate optimistic-insert idempotency (find-then-skip)", () => {
   });
 });
 
+// handleCreate race-guard temporaryExpiresAt patch: when the server's
+// addTreeNode broadcast wins the race and inserts the node BEFORE the optimistic
+// updater runs, the updater must not re-insert. Two sub-branches:
+//  (a) the node the broadcast inserted carries NO deadline (an older broadcast
+//      omitted it) while the authoritative create response DOES → patch the
+//      deadline on so the clock marker shows now, without a reload.
+//  (b) the existing node ALREADY has a deadline → do NOT overwrite it; return
+//      `prev` by reference (a no-op write).
+describe("handleCreate race-guard temporaryExpiresAt patch", () => {
+  type TN = TreeNode<{ name: string; temporaryExpiresAt?: string | null }>;
+
+  // Mirrors the setData updater in use-tree-mutation handleCreate.
+  const applyOptimisticInsert = (
+    tree: TN[],
+    parentId: string | null,
+    node: TN,
+    index: number,
+  ): TN[] => {
+    const existing = treeModel.find(tree, node.id) as TN | null;
+    if (existing) {
+      if (node.temporaryExpiresAt && !existing.temporaryExpiresAt) {
+        return treeModel.update(tree, node.id, {
+          temporaryExpiresAt: node.temporaryExpiresAt,
+        });
+      }
+      return tree;
+    }
+    return treeModel.insert(tree, parentId, node, index);
+  };
+
+  const fixtureTN: TN[] = [
+    { id: "a", name: "A" },
+    { id: "b", name: "B" },
+  ];
+
+  const deadline = "2026-07-01T00:00:00.000Z";
+
+  it("(a) patches temporaryExpiresAt when the existing node has none + the response carries a deadline", () => {
+    // Server broadcast won the race and inserted the node WITHOUT a deadline.
+    const afterServer = treeModel.insert(fixtureTN, null, {
+      id: "new",
+      name: "",
+    });
+    expect((treeModel.find(afterServer, "new") as TN).temporaryExpiresAt).toBe(
+      undefined,
+    );
+
+    // The authoritative create response carries the deadline.
+    const created: TN = { id: "new", name: "", temporaryExpiresAt: deadline };
+    const patched = applyOptimisticInsert(
+      afterServer,
+      null,
+      created,
+      afterServer.length,
+    );
+
+    // A new reference (the patch wrote) and the node now has the deadline...
+    expect(patched).not.toBe(afterServer);
+    expect((treeModel.find(patched, "new") as TN).temporaryExpiresAt).toBe(
+      deadline,
+    );
+    // ...and still exactly one node (no duplicate re-insert).
+    expect(patched.filter((n) => n.id === "new")).toHaveLength(1);
+  });
+
+  it("(b) does NOT overwrite an existing deadline; returns prev by reference", () => {
+    const existingDeadline = deadline;
+    // The node already exists WITH a deadline (the broadcast carried it).
+    const afterServer = treeModel.insert(fixtureTN, null, {
+      id: "new",
+      name: "",
+      temporaryExpiresAt: existingDeadline,
+    });
+
+    // The create response carries a DIFFERENT deadline; the guard must ignore it.
+    const created: TN = {
+      id: "new",
+      name: "",
+      temporaryExpiresAt: "2099-01-01T00:00:00.000Z",
+    };
+    const after = applyOptimisticInsert(
+      afterServer,
+      null,
+      created,
+      afterServer.length,
+    );
+
+    // prev returned by reference (no write) and the original deadline is kept.
+    expect(after).toBe(afterServer);
+    expect((treeModel.find(after, "new") as TN).temporaryExpiresAt).toBe(
+      existingDeadline,
+    );
+  });
+});
+
 // moveTreeNode socket-handler semantics: the receiver must place the moved node
 // by `position` (NOT index 0) and apply the `pageData` the payload carries so a
 // moved node's title/icon/chevron stay correct. This mirrors the reducer in

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

@@ -9,26 +9,45 @@ export function sortPositionKeys(keys: any[]) {
   });
 }
 
+/**
+ * Single canonical `IPage -> SpaceTreeNode` field mapper. Every place that
+ * materialises a tree node from a page (buildTree, the optimistic insert in
+ * handleCreate, restore, duplicate) routes through here so the field copy —
+ * crucially `temporaryExpiresAt` — can never silently drift between sites. The
+ * `overrides` cover the small per-site differences (e.g. `name: ""` for an
+ * optimistic create, `name: title || "Untitled"` for restore, `canEdit: true`
+ * for duplicate). The default `temporaryExpiresAt` comes straight off the page,
+ * so restore (which the server nulls) stays permanent and a temporary create
+ * keeps its clock marker without a reload.
+ */
+export function pageToTreeNode(
+  page: IPage,
+  overrides?: Partial<SpaceTreeNode>,
+): SpaceTreeNode {
+  return {
+    id: page.id,
+    slugId: page.slugId,
+    name: page.title,
+    icon: page.icon,
+    position: page.position,
+    hasChildren: page.hasChildren,
+    spaceId: page.spaceId,
+    parentPageId: page.parentPageId,
+    canEdit: page.canEdit ?? page.permissions?.canEdit,
+    isTemplate: page.isTemplate,
+    temporaryExpiresAt: page.temporaryExpiresAt,
+    children: [],
+    ...overrides,
+  };
+}
+
 export function buildTree(pages: IPage[]): SpaceTreeNode[] {
   const pageMap: Record<string, SpaceTreeNode> = {};
 
   const tree: SpaceTreeNode[] = [];
 
   pages.forEach((page) => {
-    pageMap[page.id] = {
-      id: page.id,
-      slugId: page.slugId,
-      name: page.title,
-      icon: page.icon,
-      position: page.position,
-      hasChildren: page.hasChildren,
-      spaceId: page.spaceId,
-      parentPageId: page.parentPageId,
-      canEdit: page.canEdit ?? page.permissions?.canEdit,
-      isTemplate: page.isTemplate,
-      temporaryExpiresAt: page.temporaryExpiresAt,
-      children: [],
-    };
+    pageMap[page.id] = pageToTreeNode(page);
   });
 
   // Defense-in-depth: a duplicate id in `pages` would push two references to the

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

@@ -0,0 +1,149 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import type { IShareAlias } from "@/features/share/types/share.types";
+
+// matchMedia / storage are stubbed globally in vitest.setup.ts.
+
+// The mutation + query hooks reach react-query/network; the availability probe
+// hits the API. Stub them so the section renders in isolation and we can drive
+// the exact branches (taken name -> hint, 409 -> reassign modal).
+const setMutateAsync = vi.fn();
+let currentAlias: IShareAlias | null = null;
+let availabilityResult: {
+  valid: boolean;
+  available: boolean;
+  currentPageId: string | null;
+} = { valid: true, available: true, currentPageId: null };
+
+vi.mock("@/features/share/queries/share-query.ts", () => ({
+  useShareAliasForPageQuery: () => ({ data: currentAlias }),
+  useSetShareAliasMutation: () => ({
+    mutateAsync: setMutateAsync,
+    isPending: false,
+  }),
+  useRemoveShareAliasMutation: () => ({
+    mutateAsync: vi.fn(),
+    isPending: false,
+  }),
+}));
+
+vi.mock("@/features/share/services/share-service.ts", () => ({
+  checkShareAliasAvailability: vi.fn(async () => availabilityResult),
+}));
+
+import ShareAliasSection from "./share-alias-section";
+
+const aliasRow = (alias: string, pageId: string): IShareAlias => ({
+  id: `alias-${alias}`,
+  workspaceId: "ws-1",
+  alias,
+  pageId,
+  creatorId: "user-1",
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+});
+
+function renderSection(pageId = "page-Y") {
+  return render(
+    <MantineProvider>
+      <ShareAliasSection pageId={pageId} readOnly={false} />
+    </MantineProvider>,
+  );
+}
+
+describe("ShareAliasSection — taken-name handling is never a dead end", () => {
+  beforeEach(() => {
+    setMutateAsync.mockReset();
+    currentAlias = null;
+    availabilityResult = { valid: true, available: true, currentPageId: null };
+  });
+
+  it("shows a 'will move it here' HINT (not a terminal error) when the name belongs to another page, and keeps Save enabled", async () => {
+    // Page Y already owns "bee"; the user retypes a name owned by page X.
+    currentAlias = aliasRow("bee", "page-Y");
+    availabilityResult = {
+      valid: true,
+      available: false,
+      currentPageId: "page-X",
+    };
+
+    renderSection("page-Y");
+    const input = screen.getByPlaceholderText("my-page") as HTMLInputElement;
+    fireEvent.change(input, { target: { value: "test2" } });
+
+    // The reassign hint replaces the old dead-end red error.
+    await waitFor(
+      () =>
+        expect(
+          screen.getByText(
+            "This address is in use. Saving will move it to this page.",
+          ),
+        ).toBeDefined(),
+      { timeout: 2000 },
+    );
+    // The old terminal "already in use" error must NOT be shown.
+    expect(screen.queryByText("This address is already in use")).toBeNull();
+
+    // Save stays enabled so the confirm-reassign flow can run.
+    const saveBtn = screen.getByRole("button", {
+      name: "Save",
+    }) as HTMLButtonElement;
+    expect(saveBtn.disabled).toBe(false);
+  });
+
+  it("opens the reassign-confirm modal on a 409 ALIAS_REASSIGN_REQUIRED (path forward, not a dead end)", async () => {
+    currentAlias = aliasRow("bee", "page-Y");
+    availabilityResult = {
+      valid: true,
+      available: false,
+      currentPageId: "page-X",
+    };
+    // The server rejects the un-confirmed save asking the client to confirm.
+    setMutateAsync.mockRejectedValueOnce({
+      status: 409,
+      response: {
+        status: 409,
+        data: {
+          code: "ALIAS_REASSIGN_REQUIRED",
+          currentPageId: "page-X",
+          currentPageTitle: "Alias Test Page X",
+        },
+      },
+    });
+
+    renderSection("page-Y");
+    const input = screen.getByPlaceholderText("my-page") as HTMLInputElement;
+    fireEvent.change(input, { target: { value: "test2" } });
+
+    const saveBtn = screen.getByRole("button", {
+      name: "Save",
+    }) as HTMLButtonElement;
+    await waitFor(() => expect(saveBtn.disabled).toBe(false), {
+      timeout: 2000,
+    });
+    fireEvent.click(saveBtn);
+
+    // First save sent WITHOUT confirmReassign.
+    await waitFor(() =>
+      expect(setMutateAsync).toHaveBeenCalledWith(
+        expect.objectContaining({ alias: "test2", confirmReassign: false }),
+      ),
+    );
+
+    // The "Move custom address?" confirm modal must appear (the path forward).
+    await waitFor(() =>
+      expect(screen.getByText("Move custom address?")).toBeDefined(),
+    );
+    expect(screen.getByRole("button", { name: "Move here" })).toBeDefined();
+
+    // Confirming retries WITH confirmReassign: true.
+    setMutateAsync.mockResolvedValueOnce(aliasRow("test2", "page-Y"));
+    fireEvent.click(screen.getByRole("button", { name: "Move here" }));
+    await waitFor(() =>
+      expect(setMutateAsync).toHaveBeenCalledWith(
+        expect.objectContaining({ alias: "test2", confirmReassign: true }),
+      ),
+    );
+  });
+});

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

@@ -120,8 +120,13 @@ export default function ShareAliasSection({
   };
 
   const showInvalid = normalized.length > 0 && !isValid;
-  const showTaken =
-    isValid && !unchanged && availability && !availability.available;
+  // The typed name is already in use by ANOTHER page. This is NOT a dead end:
+  // hitting Save triggers the server's 409 `ALIAS_REASSIGN_REQUIRED` and opens
+  // the "Move custom address?" confirm modal that retargets the address here.
+  // So surface it as an informational hint (not a terminal red error) and keep
+  // Save enabled, instead of looking like the address is unusable.
+  const reassignable =
+    isValid && !unchanged && !!availability && !availability.available;
 
   // The slug prefix (e.g. "docs.example.com/l/") is static for the session.
   const prefixLabel = aliasPrefixLabel();
@@ -198,9 +203,12 @@ export default function ShareAliasSection({
         error={
           showInvalid
             ? t("Use 2-60 lowercase letters, digits and hyphens")
-            : showTaken
-              ? t("This address is already in use")
-              : undefined
+            : undefined
+        }
+        description={
+          reassignable
+            ? t("This address is in use. Saving will move it to this page.")
+            : undefined
         }
       />
 

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

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import { MemoryRouter } from "react-router-dom";
+
+// matchMedia / storage are stubbed globally in vitest.setup.ts.
+
+// Enabling a public share must NOT silently expose the whole sub-tree (#216):
+// the create call defaults includeSubPages to false. This was a one-literal,
+// security-relevant default with no test — lock it.
+
+const createMutateAsync = vi.fn(async () => ({}));
+const deleteMutateAsync = vi.fn(async () => ({}));
+
+// No existing share for this page (toggle starts OFF).
+let shareData: any = undefined;
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock("@/features/share/queries/share-query.ts", () => ({
+  useCreateShareMutation: () => ({ mutateAsync: createMutateAsync }),
+  useDeleteShareMutation: () => ({ mutateAsync: deleteMutateAsync }),
+  useUpdateShareMutation: () => ({ mutateAsync: vi.fn() }),
+  useShareForPageQuery: () => ({ data: shareData }),
+}));
+
+vi.mock("@/features/page/queries/page-query.ts", () => ({
+  usePageQuery: () => ({ data: { id: "page-1", title: "Doc" } }),
+}));
+
+vi.mock("@/features/space/queries/space-query.ts", () => ({
+  useSpaceQuery: () => ({ data: { settings: {} } }),
+}));
+
+import ShareModal from "./share-modal";
+
+function renderModal() {
+  return render(
+    <MemoryRouter>
+      <MantineProvider>
+        <ShareModal readOnly={false} />
+      </MantineProvider>
+    </MemoryRouter>,
+  );
+}
+
+describe("ShareModal — enabling a share defaults includeSubPages to false (#216)", () => {
+  beforeEach(() => {
+    createMutateAsync.mockClear();
+    deleteMutateAsync.mockClear();
+    shareData = undefined;
+  });
+
+  it("creates the share with includeSubPages: false when the user turns it on", async () => {
+    renderModal();
+
+    // Open the share popover.
+    fireEvent.click(screen.getByRole("button", { name: "Share" }));
+
+    // The "Share to web" toggle is the only switch in the not-yet-shared state.
+    const toggle = await screen.findByRole("switch");
+    fireEvent.click(toggle);
+
+    await waitFor(() => expect(createMutateAsync).toHaveBeenCalledTimes(1));
+    expect(createMutateAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        pageId: "page-1",
+        includeSubPages: false,
+      }),
+    );
+  });
+});

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

@@ -73,7 +73,10 @@ export default function ShareModal({ readOnly }: ShareModalProps) {
       if (value) {
         await createShareMutation.mutateAsync({
           pageId: pageId,
-          includeSubPages: true,
+          // Opt-in: enabling a share must NOT silently expose the whole
+          // sub-tree (#216). Sub-pages are shared only when the user turns on
+          // the dedicated "Include sub-pages" toggle.
+          includeSubPages: false,
           searchIndexing: false,
         });
       } else if (share && share.id) {

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

@@ -35,9 +35,17 @@ export interface ISharedItem extends IShare {
   };
 }
 
-export interface ISharedPage extends IShare {
-  page: IPage;
-  share: IShare & {
+// The `/shares/page-info` (anonymous) response. Mirrors the server-side
+// PublicSharePayload allowlist (#218): the server trims `page`/`share` to these
+// fields exactly, so the client type must not over-declare internal metadata it
+// will never receive. Keep this in sync with share-public-payload.ts.
+export interface ISharedPage {
+  page: Pick<IPage, "id" | "slugId" | "title" | "icon" | "content">;
+  share: {
+    id: string;
+    key: string;
+    includeSubPages: boolean;
+    searchIndexing: boolean;
     level: number;
     sharedPage: { id: string; slugId: string; title: string; icon: string };
   };
@@ -73,6 +81,10 @@ export type IUpdateShare = ICreateShare & { shareId: string; pageId?: string };
 
 export interface IShareInfoInput {
   pageId: string;
+  // The share id/key from the `/share/:shareId/p/:slug` URL. When present the
+  // server binds content access to this exact share (#218): a forged/mismatched
+  // shareId 404s instead of rendering the page off its slug alone.
+  shareId?: string;
 }
 
 // Vanity /l/:alias pointer.

apps/client/src/features/space/components/space-create-note-buttons.tsx

@@ -1,5 +1,5 @@
 import { useState } from "react";
-import { Button, Group } from "@mantine/core";
+import { Button, Stack } from "@mantine/core";
 import { IconHourglass, IconPlus } from "@tabler/icons-react";
 import { useParams } from "react-router-dom";
 import { useTranslation } from "react-i18next";
@@ -45,12 +45,16 @@ export default function SpaceCreateNoteButtons() {
       .finally(() => setPending(null));
   };
 
+  // Two full-width, vertically stacked buttons: a neutral regular note and an
+  // orange-tinted temporary note. Stacking full-width keeps the longer "New
+  // temporary note" label from clipping on narrow mobile widths.
   return (
-    <Group grow gap="sm">
+    <Stack gap="sm">
       <Button
         size="md"
         variant="light"
         color="gray"
+        fullWidth
         leftSection={<IconPlus size={18} />}
         loading={pending === "regular"}
         disabled={pending !== null}
@@ -61,7 +65,8 @@ export default function SpaceCreateNoteButtons() {
       <Button
         size="md"
         variant="light"
-        color="gray"
+        color="orange"
+        fullWidth
         leftSection={<IconHourglass size={18} />}
         loading={pending === "temporary"}
         disabled={pending !== null}
@@ -69,6 +74,6 @@ export default function SpaceCreateNoteButtons() {
       >
         {t("New temporary note")}
       </Button>
-    </Group>
+    </Stack>
   );
 }

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

@@ -323,4 +323,18 @@ describe("applyAddTreeNode", () => {
       "child",
     ]);
   });
+
+  it("carries temporaryExpiresAt onto the inserted node so the clock marker shows on create (no reload)", () => {
+    // A note created as temporary broadcasts addTreeNode with the death-timer
+    // deadline in its payload; the receiver's inserted node must keep it so
+    // space-tree-row renders the orange clock marker immediately.
+    const tree = roots();
+    const expiresAt = "2026-06-27T21:00:00.000Z";
+    const next = applyAddTreeNode(tree, {
+      parentId: null as unknown as string,
+      index: 0,
+      data: node("temp", { position: "a3", temporaryExpiresAt: expiresAt }),
+    });
+    expect(treeModel.find(next, "temp")?.temporaryExpiresAt).toBe(expiresAt);
+  });
 });

apps/client/src/features/workspace/components/settings/components/ai-agent-roles-catalog-modal.tsx

@@ -0,0 +1,407 @@
+import { useEffect, useMemo, useState } from "react";
+import {
+  Accordion,
+  Alert,
+  Badge,
+  Button,
+  Center,
+  Checkbox,
+  Group,
+  Loader,
+  Modal,
+  Radio,
+  Select,
+  Stack,
+  Text,
+} from "@mantine/core";
+import { IconAlertTriangle } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import {
+  useAiRoleCatalogBundleQuery,
+  useAiRoleCatalogQuery,
+  useImportAiRolesFromCatalogMutation,
+  useUpdateAiRoleFromCatalogMutation,
+} from "@/features/ai-chat/queries/ai-chat-query.ts";
+import {
+  IAiRole,
+  IAiRoleCatalogBundleSummary,
+  IAiRoleCatalogRole,
+} from "@/features/ai-chat/types/ai-chat.types.ts";
+import { catalogRoleInstallState } from "@/features/ai-chat/utils/catalog-role-install-state.ts";
+
+interface AiAgentRolesCatalogModalProps {
+  opened: boolean;
+  onClose: () => void;
+  // The current admin role list (full view, including `source`). Used to compute
+  // each catalog role's install state (import / installed / update available).
+  roles: IAiRole[];
+}
+
+/** How a name collision with an existing role is handled on import. */
+type Conflict = "skip" | "rename";
+
+/**
+ * Admin modal: browse the curated role catalog, import roles, and update an
+ * imported role when the catalog ships a newer version.
+ *
+ * Import is per-bundle (the endpoint takes a single bundleId). Each bundle's
+ * Accordion panel has its own "Import" button that imports only that bundle's
+ * checked roles — the simplest mapping to the one-bundle-per-call API and the
+ * clearest UX. Selection state is tracked per bundle.
+ */
+export default function AiAgentRolesCatalogModal({
+  opened,
+  onClose,
+  roles,
+}: AiAgentRolesCatalogModalProps) {
+  const { t, i18n } = useTranslation();
+
+  // The user's i18n base subtag (e.g. "ru-RU" => "ru"); the preferred catalog
+  // language both when seeding and when reconciling against offered languages.
+  const baseLang = (i18n.language || "en").split("-")[0].toLowerCase();
+
+  // Fetch the catalog only while the modal is open. `language` drives both the
+  // catalog query (bundle names) and bundle reads (role content). Seed it
+  // synchronously from the base subtag so the first fetch already uses the
+  // user's language; the effect below still reconciles against the catalog's
+  // offered languages once they load.
+  const [language, setLanguage] = useState<string>(() => baseLang);
+  const catalogQuery = useAiRoleCatalogQuery(language || "en", opened);
+
+  // On name conflict: Skip (default) or Rename to a free " (N)" name.
+  const [conflict, setConflict] = useState<Conflict>("skip");
+
+  // The currently expanded bundle id (Accordion is single-open: one bundle's
+  // roles are fetched at a time).
+  const [expanded, setExpanded] = useState<string | null>(null);
+
+  // Per-bundle selected slugs (import-state roles checked for import).
+  const [selected, setSelected] = useState<Record<string, Set<string>>>({});
+
+  const languages = catalogQuery.data?.languages;
+
+  // Pick a sensible default language from the catalog once it loads: the i18n
+  // base subtag (e.g. "ru-RU" => "ru") if offered, else "en", else the first.
+  useEffect(() => {
+    if (!languages || languages.length === 0) return;
+    if (language && languages.includes(language)) return;
+    const preferred = languages.includes(baseLang)
+      ? baseLang
+      : languages.includes("en")
+        ? "en"
+        : languages[0];
+    setLanguage(preferred);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [languages]);
+
+  // Reset per-language UI state when the language changes (the bundle content,
+  // hence the install computations, are language-specific).
+  useEffect(() => {
+    setExpanded(null);
+    setSelected({});
+  }, [language]);
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      title={t("Role catalog")}
+      size="lg"
+    >
+      <Stack>
+        <Select
+          label={t("Language")}
+          data={languages ?? []}
+          value={language || null}
+          onChange={(value) => value && setLanguage(value)}
+          allowDeselect={false}
+          disabled={!languages || languages.length === 0}
+          comboboxProps={{ withinPortal: true }}
+        />
+
+        <Radio.Group
+          label={t("On name conflict")}
+          value={conflict}
+          onChange={(value) => setConflict(value as Conflict)}
+        >
+          <Group mt="xs">
+            <Radio value="skip" label={t("Skip")} />
+            <Radio value="rename" label={t("Rename")} />
+          </Group>
+        </Radio.Group>
+
+        {catalogQuery.isLoading && (
+          <Center py="lg">
+            <Loader size="sm" />
+          </Center>
+        )}
+
+        {catalogQuery.isError && (
+          <Alert
+            color="red"
+            icon={<IconAlertTriangle size={16} />}
+            title={t("The role catalog is unavailable")}
+          >
+            {t("Please try again later.")}
+          </Alert>
+        )}
+
+        {catalogQuery.data && catalogQuery.data.bundles.length === 0 && (
+          <Text size="sm" c="dimmed">
+            {t("No bundles available")}
+          </Text>
+        )}
+
+        {catalogQuery.data && catalogQuery.data.bundles.length > 0 && (
+          <Accordion
+            variant="separated"
+            value={expanded}
+            onChange={setExpanded}
+          >
+            {catalogQuery.data.bundles.map((bundle) => (
+              <BundlePanel
+                key={bundle.id}
+                bundle={bundle}
+                language={language}
+                expanded={expanded === bundle.id}
+                roles={roles}
+                conflict={conflict}
+                selected={selected[bundle.id]}
+                onToggleSlug={(slug, checked) =>
+                  setSelected((prev) => {
+                    const next = new Set(prev[bundle.id] ?? []);
+                    if (checked) next.add(slug);
+                    else next.delete(slug);
+                    return { ...prev, [bundle.id]: next };
+                  })
+                }
+                onSetSelected={(slugs) =>
+                  setSelected((prev) => ({
+                    ...prev,
+                    [bundle.id]: new Set(slugs),
+                  }))
+                }
+              />
+            ))}
+          </Accordion>
+        )}
+
+        <Group justify="flex-end" mt="sm">
+          <Button variant="default" onClick={onClose}>
+            {t("Close")}
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
+
+interface BundlePanelProps {
+  bundle: IAiRoleCatalogBundleSummary;
+  language: string;
+  expanded: boolean;
+  roles: IAiRole[];
+  conflict: Conflict;
+  selected: Set<string> | undefined;
+  onToggleSlug: (slug: string, checked: boolean) => void;
+  onSetSelected: (slugs: string[]) => void;
+}
+
+/** One catalog bundle: its roles (fetched when expanded) + a per-bundle import. */
+function BundlePanel({
+  bundle,
+  language,
+  expanded,
+  roles,
+  conflict,
+  selected,
+  onToggleSlug,
+  onSetSelected,
+}: BundlePanelProps) {
+  const { t } = useTranslation();
+
+  // Only fetch this bundle's roles once it is actually expanded.
+  const bundleQuery = useAiRoleCatalogBundleQuery(
+    bundle.id,
+    language,
+    expanded && !!language,
+  );
+
+  const importMutation = useImportAiRolesFromCatalogMutation();
+  const updateMutation = useUpdateAiRoleFromCatalogMutation();
+
+  // Compute each catalog role's install state against the current workspace
+  // roles (matched by source.slug + source.language). The decision lives in the
+  // pure `catalogRoleInstallState` helper so it is unit-tested directly.
+  const computed = useMemo(() => {
+    const list = bundleQuery.data?.roles ?? [];
+    return list.map((role) => ({
+      role,
+      ...catalogRoleInstallState(role, roles, language),
+    }));
+  }, [bundleQuery.data, roles, language]);
+
+  // Default-check every importable role once the bundle content arrives (unless
+  // the user already touched the selection for this bundle).
+  useEffect(() => {
+    if (!bundleQuery.data || selected !== undefined) return;
+    onSetSelected(
+      computed.filter((c) => c.state === "import").map((c) => c.role.slug),
+    );
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [bundleQuery.data]);
+
+  const importableSlugs = computed
+    .filter((c) => c.state === "import")
+    .map((c) => c.role.slug);
+  const checkedSlugs = importableSlugs.filter((slug) => selected?.has(slug));
+
+  function handleImport() {
+    importMutation.mutate({
+      bundleId: bundle.id,
+      language,
+      slugs: checkedSlugs,
+      conflict,
+    });
+  }
+
+  return (
+    <Accordion.Item value={bundle.id}>
+      <Accordion.Control>
+        <Stack gap={2}>
+          <Text fw={500}>{bundle.name}</Text>
+          {bundle.description && (
+            <Text size="xs" c="dimmed">
+              {bundle.description}
+            </Text>
+          )}
+        </Stack>
+      </Accordion.Control>
+      <Accordion.Panel>
+        {bundleQuery.isLoading && (
+          <Center py="md">
+            <Loader size="sm" />
+          </Center>
+        )}
+
+        {bundleQuery.isError && (
+          <Alert
+            color="red"
+            icon={<IconAlertTriangle size={16} />}
+            title={t("The role catalog is unavailable")}
+          >
+            {t("Please try again later.")}
+          </Alert>
+        )}
+
+        {bundleQuery.data && (
+          <Stack gap="xs">
+            {computed.map((entry) => (
+              <CatalogRoleRow
+                key={entry.role.slug}
+                role={entry.role}
+                state={entry.state}
+                checked={
+                  entry.state === "import"
+                    ? !!selected?.has(entry.role.slug)
+                    : false
+                }
+                onToggle={(checked) => onToggleSlug(entry.role.slug, checked)}
+                fromVersion={
+                  entry.state === "update" ? entry.fromVersion : undefined
+                }
+                onUpdate={
+                  entry.state === "update"
+                    ? () => updateMutation.mutate(entry.installed.id)
+                    : undefined
+                }
+                updating={updateMutation.isPending}
+              />
+            ))}
+
+            <Group justify="flex-end" mt="xs">
+              <Button
+                size="xs"
+                onClick={handleImport}
+                loading={importMutation.isPending}
+                disabled={checkedSlugs.length === 0}
+              >
+                {t("Import")}
+              </Button>
+            </Group>
+          </Stack>
+        )}
+      </Accordion.Panel>
+    </Accordion.Item>
+  );
+}
+
+interface CatalogRoleRowProps {
+  role: IAiRoleCatalogRole;
+  state: "import" | "installed" | "update";
+  checked: boolean;
+  onToggle: (checked: boolean) => void;
+  // The installed role's current source version (only set in the "update" state).
+  fromVersion?: number;
+  onUpdate?: () => void;
+  updating: boolean;
+}
+
+/** A single catalog role row with its install-state affordance. */
+function CatalogRoleRow({
+  role,
+  state,
+  checked,
+  onToggle,
+  fromVersion,
+  onUpdate,
+  updating,
+}: CatalogRoleRowProps) {
+  const { t } = useTranslation();
+
+  return (
+    <Group justify="space-between" wrap="nowrap" align="flex-start">
+      <Group gap="xs" wrap="nowrap" align="flex-start" style={{ minWidth: 0 }}>
+        {state === "import" && (
+          <Checkbox
+            checked={checked}
+            onChange={(event) => onToggle(event.currentTarget.checked)}
+            aria-label={role.name}
+          />
+        )}
+        <Stack gap={2} style={{ minWidth: 0 }}>
+          <Text fw={500} truncate>
+            {role.emoji ? `${role.emoji} ` : ""}
+            {role.name}
+          </Text>
+          {role.description && (
+            <Text size="xs" c="dimmed">
+              {role.description}
+            </Text>
+          )}
+        </Stack>
+      </Group>
+
+      <Group gap="xs" wrap="nowrap" style={{ flex: "none" }}>
+        {state === "installed" && (
+          <Badge size="sm" variant="light" color="gray">
+            {t("Installed")}
+          </Badge>
+        )}
+        {state === "update" && (
+          <>
+            <Badge size="sm" variant="light" color="blue">
+              {t("v{{from}} → v{{to}}", {
+                from: fromVersion ?? 0,
+                to: role.version,
+              })}
+            </Badge>
+            <Button size="xs" variant="light" onClick={onUpdate} loading={updating}>
+              {t("Update")}
+            </Button>
+          </>
+        )}
+      </Group>
+    </Group>
+  );
+}

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

@@ -13,7 +13,12 @@ import {
 } from "@mantine/core";
 import { useDisclosure } from "@mantine/hooks";
 import { modals } from "@mantine/modals";
-import { IconPencil, IconPlus, IconTrash } from "@tabler/icons-react";
+import {
+  IconPackageImport,
+  IconPencil,
+  IconPlus,
+  IconTrash,
+} from "@tabler/icons-react";
 import { useTranslation } from "react-i18next";
 import useUserRole from "@/hooks/use-user-role.tsx";
 import {
@@ -23,6 +28,7 @@ import {
 } from "@/features/ai-chat/queries/ai-chat-query.ts";
 import { IAiRole } from "@/features/ai-chat/types/ai-chat.types.ts";
 import AiAgentRoleForm from "./ai-agent-role-form.tsx";
+import AiAgentRolesCatalogModal from "./ai-agent-roles-catalog-modal.tsx";
 
 /**
  * Admin section: list / add / edit / delete reusable agent roles. A role
@@ -39,6 +45,9 @@ export default function AiAgentRoles() {
   const deleteMutation = useDeleteAiRoleMutation();
 
   const [opened, { open, close }] = useDisclosure(false);
+  // Separate disclosure for the catalog (import/update) modal.
+  const [catalogOpened, { open: openCatalog, close: closeCatalog }] =
+    useDisclosure(false);
   // The role being edited; undefined => the modal is in "create" mode.
   const [editing, setEditing] = useState<IAiRole | undefined>(undefined);
 
@@ -86,14 +95,24 @@ export default function AiAgentRoles() {
           />
           <Text fw={600}>{t("Agent roles")}</Text>
         </Group>
-        <Button
-          leftSection={<IconPlus size={16} />}
-          variant="default"
-          size="xs"
-          onClick={openCreate}
-        >
-          {t("Add role")}
-        </Button>
+        <Group gap="xs" wrap="nowrap">
+          <Button
+            leftSection={<IconPackageImport size={16} />}
+            variant="default"
+            size="xs"
+            onClick={openCatalog}
+          >
+            {t("Import from catalog")}
+          </Button>
+          <Button
+            leftSection={<IconPlus size={16} />}
+            variant="default"
+            size="xs"
+            onClick={openCreate}
+          >
+            {t("Add role")}
+          </Button>
+        </Group>
       </Group>
       <Text size="xs" c="dimmed" mt={4}>
         {t(
@@ -102,9 +121,19 @@ export default function AiAgentRoles() {
       </Text>
 
       {!isLoading && (!roles || roles.length === 0) && (
-        <Text size="sm" c="dimmed" mt="sm">
-          {t("No roles configured")}
-        </Text>
+        <Group gap="sm" mt="sm" align="center">
+          <Text size="sm" c="dimmed">
+            {t("No roles configured")}
+          </Text>
+          <Button
+            leftSection={<IconPackageImport size={16} />}
+            variant="light"
+            size="xs"
+            onClick={openCatalog}
+          >
+            {t("Browse the catalog")}
+          </Button>
+        </Group>
       )}
 
       <Stack gap="xs" mt="sm">
@@ -170,6 +199,12 @@ export default function AiAgentRoles() {
         {/* Remount the form per target so its internal state re-hydrates. */}
         <AiAgentRoleForm key={editing?.id ?? "new"} role={editing} onClose={close} />
       </Modal>
+
+      <AiAgentRolesCatalogModal
+        opened={catalogOpened}
+        onClose={closeCatalog}
+        roles={roles ?? []}
+      />
     </Paper>
   );
 }

apps/client/src/pages/share/shared-page.tsx

@@ -24,6 +24,9 @@ export default function SharedPage() {
 
   const { data, isLoading, isError, error } = useSharePageQuery({
     pageId: extractPageSlugId(pageSlug),
+    // Forward the URL's shareId so the server binds content to this share
+    // (#218): a forged shareId 404s instead of rendering the page off its slug.
+    shareId,
   });
 
   const sharedTreeData = useAtomValue(sharedTreeDataAtom);

apps/server/package.json

@@ -125,6 +125,7 @@
     "typesense": "^3.0.5",
     "undici": "7.24.0",
     "ws": "^8.20.1",
+    "yaml": "^2.8.3",
     "yauzl": "^3.2.1",
     "zod": "^4.3.6"
   },

apps/server/src/app.module.ts

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

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

@@ -205,6 +205,32 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     expect(historyQueue.add).toHaveBeenCalledTimes(1);
   });
 
+  // #206 persist-6 — RED (it.failing): a momentarily-empty live Y.Doc must not
+  // overwrite non-empty persisted content. `onStoreDocument` empty-guards the
+  // LOAD path but not the STORE path, so today an empty doc (a client/agent
+  // glitch, a bad merge, an emptying transclusion) is written straight over the
+  // page and the content is wiped silently. A store-side empty-guard is a real
+  // behaviour change (a deliberate "select-all + delete" is also empty), so it
+  // is left UNFIXED pending a product decision; this documents the data-loss
+  // path and flips to a normal passing test the moment the guard lands.
+  it.failing(
+    'does NOT overwrite non-empty content with a momentarily-empty live doc (persist-6)',
+    async () => {
+      const emptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
+      const document = ydocFor(emptyDoc);
+      pageRepo.findById.mockResolvedValue({
+        ...persistedHumanPage('IGNORED'),
+        content: doc('IMPORTANT RICH CONTENT'),
+      });
+
+      await ext.onStoreDocument(buildData(document, 'user') as any);
+
+      // Desired contract: the empty incoming doc is rejected and the rich page
+      // survives. Today updatePage is called with the empty content (data loss).
+      expect(pageRepo.updatePage).not.toHaveBeenCalled();
+    },
+  );
+
   // 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.

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

@@ -0,0 +1,44 @@
+import { AiChatController } from './ai-chat.controller';
+import type { User, Workspace } from '@docmost/db/types/entity.types';
+
+/**
+ * Wiring spec for the #191 `POST /ai-chat/bound-chat` endpoint. It must forward
+ * the requesting user + workspace + pageId to findLatestByPage and return the
+ * matched chat's id, or `{ chatId: null }` when there is none. The repo already
+ * scopes to the caller's OWN chats, so a foreign pageId simply yields no match
+ * (null) — no extra page-access check is needed. Exercised with hand-rolled
+ * mocks, no Nest graph and no DB.
+ */
+describe('AiChatController.boundChat', () => {
+  const user = { id: 'u1' } as User;
+  const workspace = { id: 'ws1' } as Workspace;
+
+  function makeController(chat: unknown) {
+    const aiChatRepo = {
+      findLatestByPage: jest.fn().mockResolvedValue(chat),
+    };
+    const controller = new AiChatController(
+      {} as never,
+      aiChatRepo as never,
+      {} as never,
+      {} as never,
+    );
+    return { controller, aiChatRepo };
+  }
+
+  it('returns the owned chat id and scopes the lookup to user + workspace + page', async () => {
+    const { controller, aiChatRepo } = makeController({
+      id: 'c1',
+      creatorId: 'u1',
+    });
+    const res = await controller.boundChat({ pageId: 'p1' }, user, workspace);
+    expect(aiChatRepo.findLatestByPage).toHaveBeenCalledWith('u1', 'ws1', 'p1');
+    expect(res).toEqual({ chatId: 'c1' });
+  });
+
+  it('returns { chatId: null } for a page with no owned chat (incl. foreign pageId)', async () => {
+    const { controller } = makeController(undefined);
+    const res = await controller.boundChat({ pageId: 'foreign' }, user, workspace);
+    expect(res).toEqual({ chatId: null });
+  });
+});

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

@@ -30,6 +30,7 @@ import { FileInterceptor } from '../../common/interceptors/file.interceptor';
 import { AiChatService, AiChatStreamBody } from './ai-chat.service';
 import { AiTranscriptionService } from './ai-transcription.service';
 import {
+  BoundChatDto,
   ChatIdDto,
   ExportChatDto,
   GeneratePageTitleDto,
@@ -67,6 +68,28 @@ export class AiChatController {
     return this.aiChatRepo.findByCreator(user.id, workspace.id, pagination);
   }
 
+  /**
+   * Resolve the chat bound to a document for the requesting user: the most-recent
+   * non-deleted chat created on that page (ai_chats.page_id). Returns
+   * { chatId: null } when the page has no owned chat (-> a fresh chat). No page
+   * access check needed: only the caller's OWN chats are matched, so a foreign
+   * pageId reveals nothing.
+   */
+  @HttpCode(HttpStatus.OK)
+  @Post('bound-chat')
+  async boundChat(
+    @Body() dto: BoundChatDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ): Promise<{ chatId: string | null }> {
+    const chat = await this.aiChatRepo.findLatestByPage(
+      user.id,
+      workspace.id,
+      dto.pageId,
+    );
+    return { chatId: chat?.id ?? null };
+  }
+
   /** Fetch the messages of a chat (oldest first, paginated). */
   @HttpCode(HttpStatus.OK)
   @Post('messages')

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

@@ -37,6 +37,12 @@ export class GetChatMessagesDto {
   cursor?: string;
 }
 
+/** Resolve the chat bound to a document (the page's most-recent owned chat). */
+export class BoundChatDto {
+  @IsString()
+  pageId: string;
+}
+
 /** Export a chat to Markdown (#183). `lang` localizes the few fixed
  *  role/tool-action labels; defaults to English server-side. */
 export class ExportChatDto {

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

@@ -0,0 +1,157 @@
+import { McpClientsService } from './mcp-clients.service';
+
+/**
+ * #204 (Phase 1, highest-value MCP gap) — external MCP client lease / refcount /
+ * eviction lifecycle.
+ *
+ * `toolsFor` hands the streaming turn a release handle; the real transports must
+ * be closed EXACTLY once and only when (a) the cache entry has been evicted AND
+ * (b) no turn still leases it. The bugs this guards against:
+ *   - leak: an evicted entry whose clients are never closed (refCount stuck > 0);
+ *   - premature close: a TTL/CRUD eviction closing a client a turn is still
+ *     executing tool calls against;
+ *   - double close: a release handle closing the same client more than once.
+ *
+ * The private `buildEntry` is stubbed so no real network/MCP connection happens;
+ * we drive only the lease bookkeeping in `toolsFor` / `release` / `evict` /
+ * `invalidate`, which is the untested surface.
+ */
+describe('McpClientsService lease/refcount/eviction', () => {
+  type FakeClient = { tools: () => Promise<any>; close: jest.Mock };
+
+  function fakeClient(): FakeClient {
+    return {
+      tools: async () => ({}),
+      close: jest.fn().mockResolvedValue(undefined),
+    };
+  }
+
+  // Minimal CacheEntry the service's lease logic operates on.
+  function makeEntry(clients: FakeClient[]) {
+    const timer = setTimeout(() => {}, 60_000);
+    timer.unref?.();
+    return {
+      tools: {},
+      clients,
+      outcomes: [],
+      instructions: [],
+      expiresAt: Date.now() + 60_000,
+      refCount: 0,
+      evicted: false,
+      closed: false,
+      timer,
+    } as any;
+  }
+
+  let service: McpClientsService;
+
+  beforeEach(() => {
+    service = new McpClientsService({} as any, {} as any);
+  });
+
+  function stubBuild(entry: any) {
+    jest.spyOn(service as any, 'buildEntry').mockResolvedValue(entry);
+  }
+
+  it('leases on toolsFor and keeps the client warm (no close) on release', async () => {
+    const client = fakeClient();
+    const entry = makeEntry([client]);
+    stubBuild(entry);
+
+    const lease = await service.toolsFor('ws-1');
+    expect(entry.refCount).toBe(1);
+
+    await lease.clients[0].close();
+    // Released but NOT evicted: the cached entry stays warm for reuse, so the
+    // transport must NOT be closed yet.
+    expect(entry.refCount).toBe(0);
+    expect(client.close).not.toHaveBeenCalled();
+  });
+
+  it('defers close when an entry is evicted while still leased, then closes once on release', async () => {
+    const client = fakeClient();
+    const entry = makeEntry([client]);
+    stubBuild(entry);
+
+    const lease = await service.toolsFor('ws-2');
+    (service as any).evict(entry);
+
+    // Evicted under an active lease: close is deferred to the last release.
+    expect(entry.evicted).toBe(true);
+    expect(client.close).not.toHaveBeenCalled();
+
+    await lease.clients[0].close();
+    expect(client.close).toHaveBeenCalledTimes(1);
+    expect(entry.closed).toBe(true);
+  });
+
+  it('shares one entry across concurrent leases; closes only after the LAST release', async () => {
+    const client = fakeClient();
+    const entry = makeEntry([client]);
+    stubBuild(entry);
+
+    const lease1 = await service.toolsFor('ws-3');
+    const lease2 = await service.toolsFor('ws-3');
+    expect(entry.refCount).toBe(2);
+
+    (service as any).evict(entry);
+
+    await lease1.clients[0].close();
+    // One lease remains: a stream could still be running — must stay open.
+    expect(entry.refCount).toBe(1);
+    expect(client.close).not.toHaveBeenCalled();
+
+    await lease2.clients[0].close();
+    expect(entry.refCount).toBe(0);
+    expect(client.close).toHaveBeenCalledTimes(1);
+  });
+
+  it('release is idempotent: closing the same handle twice decrements once and closes once', async () => {
+    const client = fakeClient();
+    const entry = makeEntry([client]);
+    stubBuild(entry);
+
+    const lease = await service.toolsFor('ws-4');
+    (service as any).evict(entry);
+
+    await lease.clients[0].close();
+    await lease.clients[0].close();
+
+    expect(entry.refCount).toBe(0); // not -1
+    expect(client.close).toHaveBeenCalledTimes(1);
+  });
+
+  it('evicting an unleased entry closes its clients immediately', async () => {
+    const client = fakeClient();
+    const entry = makeEntry([client]);
+    stubBuild(entry);
+
+    const built = await (service as any).getOrBuildEntry('ws-5');
+    expect(built.refCount).toBe(0);
+
+    (service as any).evict(entry);
+    expect(client.close).toHaveBeenCalledTimes(1);
+    expect(entry.closed).toBe(true);
+  });
+
+  it('invalidate (TTL/CRUD) does NOT close a client that a turn still leases', async () => {
+    const client = fakeClient();
+    const entry = makeEntry([client]);
+    stubBuild(entry);
+
+    const lease = await service.toolsFor('ws-6');
+    expect(entry.refCount).toBe(1);
+
+    service.invalidate('ws-6');
+    // invalidate evicts asynchronously once the build promise resolves.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(entry.evicted).toBe(true);
+    // Still leased: the mid-turn eviction must not pull the transport.
+    expect(client.close).not.toHaveBeenCalled();
+
+    await lease.clients[0].close();
+    expect(client.close).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -39,6 +39,10 @@ describe('AiAgentRolesController admin gate', () => {
       create: jest.fn().mockResolvedValue({ id: 'r1' }),
       update: jest.fn().mockResolvedValue({ id: 'r1' }),
       remove: jest.fn().mockResolvedValue({ success: true }),
+      getCatalog: jest.fn().mockResolvedValue({ languages: [], bundles: [] }),
+      getCatalogBundle: jest.fn().mockResolvedValue({ roles: [] }),
+      importFromCatalog: jest.fn().mockResolvedValue({ created: 0 }),
+      updateFromCatalog: jest.fn().mockResolvedValue({ updated: false }),
     };
     const controller = new AiAgentRolesController(
       rolesService as never,
@@ -109,6 +113,90 @@ describe('AiAgentRolesController admin gate', () => {
     });
   });
 
+  // Catalog routes (browse + import) are ALL admin-only: a non-admin caller must
+  // get ForbiddenException with the service untouched; an admin delegates with
+  // the right arguments (import/update-from-catalog carry workspace.id).
+  describe('catalog routes admin gate', () => {
+    const catalogDto = { language: 'en' } as never;
+    const bundleDto = { bundleId: 'general', language: 'en' } as never;
+    const importDto = {
+      bundleId: 'general',
+      language: 'en',
+      conflict: 'skip',
+    } as never;
+    const updateDto = { id: 'r1' } as never;
+
+    describe('non-admin is rejected and the service is NOT called', () => {
+      it('catalog', async () => {
+        const { controller, rolesService } = makeController(false);
+        await expect(
+          controller.catalog(catalogDto, user, workspace),
+        ).rejects.toBeInstanceOf(ForbiddenException);
+        expect(rolesService.getCatalog).not.toHaveBeenCalled();
+      });
+
+      it('catalog/bundle', async () => {
+        const { controller, rolesService } = makeController(false);
+        await expect(
+          controller.catalogBundle(bundleDto, user, workspace),
+        ).rejects.toBeInstanceOf(ForbiddenException);
+        expect(rolesService.getCatalogBundle).not.toHaveBeenCalled();
+      });
+
+      it('import', async () => {
+        const { controller, rolesService } = makeController(false);
+        await expect(
+          controller.import(importDto, user, workspace),
+        ).rejects.toBeInstanceOf(ForbiddenException);
+        expect(rolesService.importFromCatalog).not.toHaveBeenCalled();
+      });
+
+      it('update-from-catalog', async () => {
+        const { controller, rolesService } = makeController(false);
+        await expect(
+          controller.updateFromCatalog(updateDto, user, workspace),
+        ).rejects.toBeInstanceOf(ForbiddenException);
+        expect(rolesService.updateFromCatalog).not.toHaveBeenCalled();
+      });
+    });
+
+    describe('admin delegates to the service', () => {
+      it('catalog passes the requested language', async () => {
+        const { controller, rolesService } = makeController(true);
+        await controller.catalog(catalogDto, user, workspace);
+        expect(rolesService.getCatalog).toHaveBeenCalledWith('en');
+      });
+
+      it('catalog/bundle passes bundleId + language', async () => {
+        const { controller, rolesService } = makeController(true);
+        await controller.catalogBundle(bundleDto, user, workspace);
+        expect(rolesService.getCatalogBundle).toHaveBeenCalledWith(
+          'general',
+          'en',
+        );
+      });
+
+      it('import passes workspace.id + user.id + dto', async () => {
+        const { controller, rolesService } = makeController(true);
+        await controller.import(importDto, user, workspace);
+        expect(rolesService.importFromCatalog).toHaveBeenCalledWith(
+          'ws-1',
+          'u1',
+          importDto,
+        );
+      });
+
+      it('update-from-catalog passes workspace.id + dto', async () => {
+        const { controller, rolesService } = makeController(true);
+        await controller.updateFromCatalog(updateDto, user, workspace);
+        expect(rolesService.updateFromCatalog).toHaveBeenCalledWith(
+          'ws-1',
+          updateDto,
+        );
+      });
+    });
+  });
+
   describe('list (member-reachable)', () => {
     it('non-admin reaches list and the service is asked for the picker view (isAdmin=false)', async () => {
       const { controller, rolesService } = makeController(false);

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

@@ -22,6 +22,12 @@ import {
   CreateAgentRoleDto,
   UpdateAgentRoleDto,
 } from './dto/agent-role.dto';
+import {
+  CatalogBundleDto,
+  CatalogQueryDto,
+  ImportFromCatalogDto,
+  UpdateFromCatalogDto,
+} from './dto/agent-role-catalog.dto';
 
 /** Path/body param for the per-role routes (update/delete). */
 class AgentRoleIdDto {
@@ -113,4 +119,54 @@ export class AiAgentRolesController {
     this.assertAdmin(user, workspace);
     return this.rolesService.remove(workspace.id, idDto.id);
   }
+
+  // --- Catalog (admin-only): browse + import + update imported roles. ---
+
+  /** Browse the curated catalog (localized to dto.language). */
+  @HttpCode(HttpStatus.OK)
+  @Post('catalog')
+  async catalog(
+    @Body() dto: CatalogQueryDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    this.assertAdmin(user, workspace);
+    return this.rolesService.getCatalog(dto.language);
+  }
+
+  /** Open one catalog bundle in a language (role content + versions). */
+  @HttpCode(HttpStatus.OK)
+  @Post('catalog/bundle')
+  async catalogBundle(
+    @Body() dto: CatalogBundleDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    this.assertAdmin(user, workspace);
+    return this.rolesService.getCatalogBundle(dto.bundleId, dto.language);
+  }
+
+  /** Import roles from a catalog bundle into the workspace. */
+  @HttpCode(HttpStatus.OK)
+  @Post('import')
+  async import(
+    @Body() dto: ImportFromCatalogDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    this.assertAdmin(user, workspace);
+    return this.rolesService.importFromCatalog(workspace.id, user.id, dto);
+  }
+
+  /** Update an already-imported role from its catalog source. */
+  @HttpCode(HttpStatus.OK)
+  @Post('update-from-catalog')
+  async updateFromCatalog(
+    @Body() dto: UpdateFromCatalogDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    this.assertAdmin(user, workspace);
+    return this.rolesService.updateFromCatalog(workspace.id, dto);
+  }
 }

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

@@ -1,16 +1,19 @@
 import { Module } from '@nestjs/common';
 import { AiAgentRolesController } from './ai-agent-roles.controller';
 import { AiAgentRolesService } from './ai-agent-roles.service';
+import { AiAgentRolesCatalogProvider } from './catalog/ai-agent-roles-catalog.provider';
 
 /**
  * Agent roles unit (v1). Admin CRUD + member-visible listing for the chat
- * role picker. AiAgentRoleRepo (DatabaseModule, global) and
- * WorkspaceAbilityFactory (CaslModule, global) are resolved without explicit
- * imports. The stream-time role resolution + model override live in
- * AiChatService / AiService; this module only hosts the management API.
+ * role picker, plus the admin catalog (browse/import/update). AiAgentRoleRepo
+ * (DatabaseModule, global), WorkspaceAbilityFactory (CaslModule, global) and
+ * EnvironmentService (EnvironmentModule, global — used by the catalog provider)
+ * are resolved without explicit imports. The stream-time role resolution +
+ * model override live in AiChatService / AiService; this module only hosts the
+ * management API.
  */
 @Module({
   controllers: [AiAgentRolesController],
-  providers: [AiAgentRolesService],
+  providers: [AiAgentRolesService, AiAgentRolesCatalogProvider],
 })
 export class AiAgentRolesModule {}

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

@@ -1,4 +1,9 @@
-import { BadRequestException, ConflictException } from '@nestjs/common';
+import {
+  BadGatewayException,
+  BadRequestException,
+  ConflictException,
+  Logger,
+} from '@nestjs/common';
 import { AiAgentRolesService } from './ai-agent-roles.service';
 import type { AiAgentRole } from '@docmost/db/types/entity.types';
 import type {
@@ -27,12 +32,22 @@ describe('AiAgentRolesService guards', () => {
       enabled: true,
       autoStart: true,
       launchMessage: null,
+      source: null,
       createdAt: new Date(),
       updatedAt: new Date(),
       ...over,
     } as AiAgentRole;
   }
 
+  // A stubbed catalog provider; the CRUD tests never reach it (they exercise
+  // create/update/remove/list only), so the methods just reject if hit.
+  function makeCatalog() {
+    return {
+      fetchIndex: jest.fn(),
+      fetchBundle: jest.fn(),
+    };
+  }
+
   function makeService(opts: { existing?: AiAgentRole | undefined } = {}) {
     const repo = {
       findById: jest.fn().mockResolvedValue(opts.existing),
@@ -41,8 +56,9 @@ describe('AiAgentRolesService guards', () => {
       softDelete: jest.fn().mockResolvedValue(undefined),
       listByWorkspace: jest.fn().mockResolvedValue([]),
     };
-    const service = new AiAgentRolesService(repo as never);
-    return { service, repo };
+    const catalog = makeCatalog();
+    const service = new AiAgentRolesService(repo as never, catalog as never);
+    return { service, repo, catalog };
   }
 
   describe('update', () => {
@@ -163,6 +179,7 @@ describe('AiAgentRolesService guards', () => {
         enabled: false,
         autoStart: true,
         launchMessage: null,
+        source: null,
         createdAt,
         updatedAt,
       });
@@ -397,7 +414,7 @@ describe('AiAgentRolesService guards', () => {
         softDelete: jest.fn(),
         listByWorkspace: jest.fn().mockResolvedValue(rows),
       };
-      const service = new AiAgentRolesService(repo as never);
+      const service = new AiAgentRolesService(repo as never, makeCatalog() as never);
       return { service, repo };
     }
 
@@ -461,4 +478,630 @@ describe('AiAgentRolesService guards', () => {
       ).rejects.toBeInstanceOf(ConflictException);
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // Catalog: import (skip / rename / already-installed) and update reconciliation
+  // against a MOCKED catalog provider + mocked repo (mirrors the CRUD style).
+  // ---------------------------------------------------------------------------
+  describe('importFromCatalog', () => {
+    function catalogRole(over: Record<string, unknown> = {}) {
+      return {
+        slug: 'researcher',
+        name: 'Researcher',
+        instructions: 'be a researcher',
+        ...over,
+      };
+    }
+
+    function makeImportService(opts: {
+      indexRoles?: { slug: string; version: number }[];
+      bundleRoles?: Record<string, unknown>[];
+      existing?: AiAgentRole[];
+    }) {
+      const index = {
+        schemaVersion: 1,
+        bundles: [
+          {
+            id: 'general',
+            name: { en: 'General' },
+            languages: ['en'],
+            roles: opts.indexRoles ?? [{ slug: 'researcher', version: 3 }],
+          },
+        ],
+      };
+      const bundle = {
+        schemaVersion: 1,
+        language: 'en',
+        roles: opts.bundleRoles ?? [catalogRole()],
+      };
+      const repo = {
+        findById: jest.fn(),
+        insert: jest.fn().mockImplementation((v) => Promise.resolve(makeRow(v))),
+        update: jest.fn().mockResolvedValue(undefined),
+        softDelete: jest.fn(),
+        listByWorkspace: jest.fn().mockResolvedValue(opts.existing ?? []),
+      };
+      const catalog = {
+        fetchIndex: jest.fn().mockResolvedValue(index),
+        fetchBundle: jest.fn().mockResolvedValue(bundle),
+      };
+      const service = new AiAgentRolesService(repo as never, catalog as never);
+      return { service, repo, catalog };
+    }
+
+    const dto = (over: Record<string, unknown> = {}) =>
+      ({
+        bundleId: 'general',
+        language: 'en',
+        conflict: 'skip',
+        ...over,
+      }) as never;
+
+    it('inserts a new role with source { slug, language, version } from the index', async () => {
+      const { service, repo } = makeImportService({});
+      const res = await service.importFromCatalog('ws-1', 'u1', dto());
+      expect(res).toMatchObject({ created: 1, skipped: 0, renamed: 0 });
+      expect(res.errors).toEqual([]);
+      const values = repo.insert.mock.calls[0][0];
+      expect(values.source).toEqual({
+        slug: 'researcher',
+        language: 'en',
+        version: 3,
+      });
+      expect(values.enabled).toBe(true);
+    });
+
+    it('already-installed catalog slug => skipped (no insert)', async () => {
+      const existing = [
+        makeRow({
+          id: 'r-existing',
+          name: 'Old researcher',
+          source: { slug: 'researcher', language: 'en', version: 1 } as never,
+        }),
+      ];
+      const { service, repo } = makeImportService({ existing });
+      const res = await service.importFromCatalog('ws-1', 'u1', dto());
+      expect(res).toMatchObject({ created: 0, skipped: 1, renamed: 0 });
+      expect(repo.insert).not.toHaveBeenCalled();
+    });
+
+    it('same slug installed in a DIFFERENT language => NOT skipped (separate install)', async () => {
+      // Installed as `ru`; importing the `en` variant of the same slug must
+      // still import (dedup key is slug+language, matching the client UI).
+      const existing = [
+        makeRow({
+          id: 'r-ru',
+          name: 'Исследователь',
+          source: { slug: 'researcher', language: 'ru', version: 1 } as never,
+        }),
+      ];
+      const { service, repo } = makeImportService({ existing });
+      const res = await service.importFromCatalog('ws-1', 'u1', dto());
+      expect(res).toMatchObject({ created: 1, skipped: 0, renamed: 0 });
+      expect(repo.insert).toHaveBeenCalledTimes(1);
+      expect(repo.insert.mock.calls[0][0].source).toEqual({
+        slug: 'researcher',
+        language: 'en',
+        version: 3,
+      });
+    });
+
+    it('name collision + conflict:skip => skipped (no insert)', async () => {
+      const existing = [makeRow({ id: 'r-x', name: 'Researcher' })];
+      const { service, repo } = makeImportService({ existing });
+      const res = await service.importFromCatalog(
+        'ws-1',
+        'u1',
+        dto({ conflict: 'skip' }),
+      );
+      expect(res).toMatchObject({ created: 0, skipped: 1, renamed: 0 });
+      expect(repo.insert).not.toHaveBeenCalled();
+    });
+
+    it('name collision + conflict:rename => inserts under " (2)"', async () => {
+      const existing = [makeRow({ id: 'r-x', name: 'Researcher' })];
+      const { service, repo } = makeImportService({ existing });
+      const res = await service.importFromCatalog(
+        'ws-1',
+        'u1',
+        dto({ conflict: 'rename' }),
+      );
+      expect(res).toMatchObject({ created: 1, skipped: 0, renamed: 1 });
+      expect(repo.insert.mock.calls[0][0].name).toBe('Researcher (2)');
+    });
+
+    it('dto.slugs filters; an unknown slug becomes an error entry', async () => {
+      const { service, repo } = makeImportService({
+        bundleRoles: [catalogRole()],
+      });
+      const res = await service.importFromCatalog(
+        'ws-1',
+        'u1',
+        dto({ slugs: ['researcher', 'ghost'] }),
+      );
+      expect(res.created).toBe(1);
+      expect(res.errors).toEqual([
+        { slug: 'ghost', message: 'Role not found in catalog bundle' },
+      ]);
+      expect(repo.insert).toHaveBeenCalledTimes(1);
+    });
+
+    it('insert unique-violation (23505) is recorded as an error, import continues', async () => {
+      const { service, repo } = makeImportService({
+        bundleRoles: [
+          catalogRole({ slug: 'a', name: 'A' }),
+          catalogRole({ slug: 'b', name: 'B' }),
+        ],
+        indexRoles: [
+          { slug: 'a', version: 1 },
+          { slug: 'b', version: 1 },
+        ],
+      });
+      repo.insert
+        .mockRejectedValueOnce({ code: '23505' })
+        .mockImplementationOnce((v) => Promise.resolve(makeRow(v)));
+      const res = await service.importFromCatalog('ws-1', 'u1', dto());
+      expect(res.created).toBe(1);
+      expect(res.errors).toEqual([
+        { slug: 'a', message: 'A role with this name already exists' },
+      ]);
+    });
+
+    it('source-uniqueness 23505 (concurrent import of same slug+language) => skipped, NOT an error, batch continues', async () => {
+      // Two parallel imports of the same bundle each build installedKeys from a
+      // stale snapshot, so both reach the insert for slug 'a'. The DB partial
+      // unique index on (workspace, source->>slug, source->>language) rejects the
+      // loser with a 23505 carrying the source-index constraint name. That must
+      // be treated as "already installed" (skip), not a per-role error, and the
+      // rest of the batch (slug 'b') must still import.
+      const { service, repo } = makeImportService({
+        bundleRoles: [
+          catalogRole({ slug: 'a', name: 'A' }),
+          catalogRole({ slug: 'b', name: 'B' }),
+        ],
+        indexRoles: [
+          { slug: 'a', version: 1 },
+          { slug: 'b', version: 1 },
+        ],
+      });
+      // The kysely-postgres-js driver surfaces the violated constraint on
+      // `constraint_name` (not node-postgres' `.constraint`), matching prod.
+      const sourceRace = Object.assign(new Error('duplicate key'), {
+        code: '23505',
+        constraint_name: 'ai_agent_roles_workspace_source_unique',
+      });
+      repo.insert
+        .mockRejectedValueOnce(sourceRace)
+        .mockImplementationOnce((v) => Promise.resolve(makeRow(v)));
+      const res = await service.importFromCatalog('ws-1', 'u1', dto());
+      // 'a' converged on the concurrent install (skip); 'b' imported; no errors.
+      expect(res).toMatchObject({ created: 1, skipped: 1, renamed: 0 });
+      expect(res.errors).toEqual([]);
+      // Both inserts were attempted (the batch did not abort on the 23505).
+      expect(repo.insert).toHaveBeenCalledTimes(2);
+    });
+
+    it('non-unique insert error => generic message, root cause logged, import continues', async () => {
+      const logSpy = jest
+        .spyOn(Logger.prototype, 'error')
+        .mockImplementation(() => undefined);
+      try {
+        const { service, repo } = makeImportService({
+          bundleRoles: [
+            catalogRole({ slug: 'a', name: 'A' }),
+            catalogRole({ slug: 'b', name: 'B' }),
+          ],
+          indexRoles: [
+            { slug: 'a', version: 1 },
+            { slug: 'b', version: 1 },
+          ],
+        });
+        // A non-23505 failure (e.g. a not-null violation) on the first insert.
+        const boom = Object.assign(new Error('null value in column'), {
+          code: '23502',
+        });
+        repo.insert
+          .mockRejectedValueOnce(boom)
+          .mockImplementationOnce((v) => Promise.resolve(makeRow(v)));
+        const res = await service.importFromCatalog('ws-1', 'u1', dto());
+        // The generic (non-409) user-facing message; the second role still imports.
+        expect(res.created).toBe(1);
+        expect(res.errors).toEqual([
+          { slug: 'a', message: 'Failed to import role' },
+        ]);
+        // The root cause was logged with the slug for diagnosis.
+        expect(logSpy).toHaveBeenCalledTimes(1);
+        expect(String(logSpy.mock.calls[0][0])).toContain('slug=a');
+      } finally {
+        logSpy.mockRestore();
+      }
+    });
+
+    it('bundleId absent from the index => BadGateway (no insert)', async () => {
+      // The requested bundle is not listed in the fetched index (a stale client
+      // or an index/bundle drift); the import must surface a 502 rather than
+      // silently doing nothing or dereferencing a missing meta.
+      const { service, repo } = makeImportService({});
+      await expect(
+        service.importFromCatalog('ws-1', 'u1', dto({ bundleId: 'missing' })),
+      ).rejects.toBeInstanceOf(BadGatewayException);
+      expect(repo.insert).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('updateFromCatalog', () => {
+    function makeUpdateService(opts: {
+      role?: AiAgentRole;
+      indexBundles?: unknown[];
+      bundleRoles?: Record<string, unknown>[];
+      others?: AiAgentRole[];
+    }) {
+      const index = {
+        schemaVersion: 1,
+        bundles: opts.indexBundles ?? [
+          {
+            id: 'general',
+            name: { en: 'General' },
+            languages: ['en'],
+            roles: [{ slug: 'researcher', version: 5 }],
+          },
+        ],
+      };
+      const bundle = {
+        schemaVersion: 1,
+        language: 'en',
+        roles: opts.bundleRoles ?? [
+          { slug: 'researcher', name: 'Researcher v5', instructions: 'new' },
+        ],
+      };
+      const repo = {
+        findById: jest.fn().mockResolvedValue(opts.role),
+        insert: jest.fn(),
+        update: jest.fn().mockResolvedValue(undefined),
+        softDelete: jest.fn(),
+        listByWorkspace: jest.fn().mockResolvedValue(opts.others ?? []),
+      };
+      const catalog = {
+        fetchIndex: jest.fn().mockResolvedValue(index),
+        fetchBundle: jest.fn().mockResolvedValue(bundle),
+      };
+      const service = new AiAgentRolesService(repo as never, catalog as never);
+      return { service, repo, catalog };
+    }
+
+    const imported = (version: number, over: Partial<AiAgentRole> = {}) =>
+      makeRow({
+        id: 'r1',
+        name: 'Researcher',
+        source: { slug: 'researcher', language: 'en', version } as never,
+        ...over,
+      });
+
+    it('role not imported from catalog (source null) => BadRequest', async () => {
+      const { service } = makeUpdateService({ role: makeRow({ source: null }) });
+      await expect(
+        service.updateFromCatalog('ws-1', { id: 'r1' } as never),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it('role not found => BadRequest', async () => {
+      const { service } = makeUpdateService({ role: undefined });
+      await expect(
+        service.updateFromCatalog('ws-1', { id: 'r1' } as never),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it('catalog version <= source.version => up-to-date (no update)', async () => {
+      const { service, repo } = makeUpdateService({ role: imported(5) });
+      const res = await service.updateFromCatalog('ws-1', { id: 'r1' } as never);
+      expect(res).toEqual({ updated: false, reason: 'up-to-date' });
+      expect(repo.update).not.toHaveBeenCalled();
+    });
+
+    it('slug no longer listed in any bundle => not-in-catalog', async () => {
+      const { service, repo } = makeUpdateService({
+        role: imported(1),
+        indexBundles: [
+          {
+            id: 'general',
+            name: { en: 'General' },
+            languages: ['en'],
+            roles: [{ slug: 'other', version: 9 }],
+          },
+        ],
+      });
+      const res = await service.updateFromCatalog('ws-1', { id: 'r1' } as never);
+      expect(res).toEqual({ updated: false, reason: 'not-in-catalog' });
+      expect(repo.update).not.toHaveBeenCalled();
+    });
+
+    it('source.language no longer offered by the bundle => language-unavailable', async () => {
+      const { service, repo } = makeUpdateService({
+        role: imported(1, {
+          source: { slug: 'researcher', language: 'ru', version: 1 } as never,
+        }),
+        indexBundles: [
+          {
+            id: 'general',
+            name: { en: 'General' },
+            languages: ['en'],
+            roles: [{ slug: 'researcher', version: 5 }],
+          },
+        ],
+      });
+      const res = await service.updateFromCatalog('ws-1', { id: 'r1' } as never);
+      expect(res).toEqual({ updated: false, reason: 'language-unavailable' });
+      expect(repo.update).not.toHaveBeenCalled();
+    });
+
+    it('newer version => updates content + bumps source.version, returns versions', async () => {
+      const role = imported(1);
+      const { service, repo } = makeUpdateService({ role });
+      // The post-update re-fetch returns the bumped row.
+      repo.findById
+        .mockResolvedValueOnce(role)
+        .mockResolvedValueOnce(
+          imported(5, { name: 'Researcher v5', instructions: 'new' }),
+        );
+      const res = await service.updateFromCatalog('ws-1', { id: 'r1' } as never);
+      expect(res).toMatchObject({
+        updated: true,
+        fromVersion: 1,
+        toVersion: 5,
+      });
+      const patch = repo.update.mock.calls[0][2];
+      expect(patch.source).toEqual({
+        slug: 'researcher',
+        language: 'en',
+        version: 5,
+      });
+      expect(patch.name).toBe('Researcher v5');
+      // enabled is never touched by an update-from-catalog.
+      expect('enabled' in patch).toBe(false);
+    });
+
+    it('slug listed in the index but missing from the bundle file => not-in-catalog', async () => {
+      // Index/bundle drift: the index still advertises a newer `researcher`
+      // (v5 > installed v1) in an offered language, but the fetched bundle file
+      // no longer contains that slug. The update must no-op as not-in-catalog,
+      // not throw or write a half-resolved role.
+      const { service, repo } = makeUpdateService({
+        role: imported(1),
+        bundleRoles: [
+          { slug: 'someone-else', name: 'Other', instructions: 'x' },
+        ],
+      });
+      const res = await service.updateFromCatalog('ws-1', { id: 'r1' } as never);
+      expect(res).toEqual({ updated: false, reason: 'not-in-catalog' });
+      expect(repo.update).not.toHaveBeenCalled();
+    });
+
+    it('new catalog name collides with another live role => keeps current name', async () => {
+      const role = imported(1);
+      const other = makeRow({ id: 'r2', name: 'Researcher v5' });
+      const { service, repo } = makeUpdateService({ role, others: [role, other] });
+      repo.findById
+        .mockResolvedValueOnce(role)
+        .mockResolvedValueOnce(imported(5));
+      await service.updateFromCatalog('ws-1', { id: 'r1' } as never);
+      // The colliding catalog name is dropped; the current name is kept.
+      expect(repo.update.mock.calls[0][2].name).toBe('Researcher');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Catalog browse (getCatalog / getCatalogBundle) against a MOCKED provider.
+  // Covers the localized() three-tier fallback (requested lang -> en -> first ->
+  // null), the sorted union of bundle languages, the missing-bundle BadGateway,
+  // and the role-version default.
+  // ---------------------------------------------------------------------------
+  describe('getCatalog', () => {
+    function makeBrowseService(index: unknown) {
+      const repo = {
+        findById: jest.fn(),
+        insert: jest.fn(),
+        update: jest.fn(),
+        softDelete: jest.fn(),
+        listByWorkspace: jest.fn(),
+      };
+      const catalog = {
+        fetchIndex: jest.fn().mockResolvedValue(index),
+        fetchBundle: jest.fn(),
+      };
+      const service = new AiAgentRolesService(repo as never, catalog as never);
+      return { service, catalog };
+    }
+
+    it('returns the sorted union of every bundle language', async () => {
+      const { service } = makeBrowseService({
+        schemaVersion: 1,
+        bundles: [
+          {
+            id: 'a',
+            name: { en: 'A' },
+            languages: ['ru', 'en'],
+            roles: [],
+          },
+          {
+            id: 'b',
+            name: { en: 'B' },
+            languages: ['en', 'de'],
+            roles: [],
+          },
+        ],
+      });
+      const res = await service.getCatalog('en');
+      expect(res.languages).toEqual(['de', 'en', 'ru']);
+    });
+
+    it('localized name uses the requested language when present', async () => {
+      const { service } = makeBrowseService({
+        schemaVersion: 1,
+        bundles: [
+          {
+            id: 'a',
+            name: { en: 'General', ru: 'Общие' },
+            description: { en: 'desc-en', ru: 'desc-ru' },
+            languages: ['en', 'ru'],
+            roles: [{ slug: 'researcher', version: 2 }],
+          },
+        ],
+      });
+      const res = await service.getCatalog('ru');
+      expect(res.bundles[0]).toMatchObject({
+        id: 'a',
+        name: 'Общие',
+        description: 'desc-ru',
+        languages: ['en', 'ru'],
+        roles: [{ slug: 'researcher', version: 2 }],
+      });
+    });
+
+    it('localized name falls back to en when the requested language is missing', async () => {
+      const { service } = makeBrowseService({
+        schemaVersion: 1,
+        bundles: [
+          {
+            id: 'a',
+            name: { en: 'General', ru: 'Общие' },
+            languages: ['en', 'ru'],
+            roles: [],
+          },
+        ],
+      });
+      const res = await service.getCatalog('fr');
+      expect(res.bundles[0].name).toBe('General');
+    });
+
+    it('localized name falls back to the first available locale when en is absent', async () => {
+      const { service } = makeBrowseService({
+        schemaVersion: 1,
+        bundles: [
+          {
+            id: 'a',
+            name: { ru: 'Общие', de: 'Allgemein' },
+            languages: ['ru', 'de'],
+            roles: [],
+          },
+        ],
+      });
+      const res = await service.getCatalog('fr');
+      // Neither 'fr' nor 'en' is present -> first available value.
+      expect(res.bundles[0].name).toBe('Общие');
+    });
+
+    it('empty name map => falls back to the bundle id; absent description => null', async () => {
+      const { service } = makeBrowseService({
+        schemaVersion: 1,
+        bundles: [
+          {
+            id: 'a',
+            name: {},
+            languages: ['en'],
+            roles: [],
+          },
+        ],
+      });
+      const res = await service.getCatalog('en');
+      expect(res.bundles[0].name).toBe('a');
+      expect(res.bundles[0].description).toBeNull();
+    });
+  });
+
+  describe('getCatalogBundle', () => {
+    function makeBundleService(opts: {
+      index: unknown;
+      bundle: unknown;
+    }) {
+      const repo = {
+        findById: jest.fn(),
+        insert: jest.fn(),
+        update: jest.fn(),
+        softDelete: jest.fn(),
+        listByWorkspace: jest.fn(),
+      };
+      const catalog = {
+        fetchIndex: jest.fn().mockResolvedValue(opts.index),
+        fetchBundle: jest.fn().mockResolvedValue(opts.bundle),
+      };
+      const service = new AiAgentRolesService(repo as never, catalog as never);
+      return { service, catalog };
+    }
+
+    const index = {
+      schemaVersion: 1,
+      bundles: [
+        {
+          id: 'general',
+          name: { en: 'General' },
+          languages: ['en'],
+          roles: [{ slug: 'researcher', version: 4 }],
+        },
+      ],
+    };
+
+    it('missing bundle in the index => BadGateway', async () => {
+      const { service, catalog } = makeBundleService({
+        index,
+        bundle: { schemaVersion: 1, language: 'en', roles: [] },
+      });
+      await expect(
+        service.getCatalogBundle('ghost', 'en'),
+      ).rejects.toBeInstanceOf(BadGatewayException);
+      expect(catalog.fetchBundle).not.toHaveBeenCalled();
+    });
+
+    it('maps role content with the version taken from the index', async () => {
+      const { service } = makeBundleService({
+        index,
+        bundle: {
+          schemaVersion: 1,
+          language: 'en',
+          roles: [
+            {
+              slug: 'researcher',
+              name: 'Researcher',
+              instructions: 'be a researcher',
+              emoji: '🔬',
+              autoStart: false,
+              launchMessage: 'go',
+            },
+          ],
+        },
+      });
+      const res = await service.getCatalogBundle('general', 'en');
+      expect(res).toMatchObject({ bundleId: 'general', language: 'en' });
+      expect(res.roles[0]).toEqual({
+        slug: 'researcher',
+        emoji: '🔬',
+        name: 'Researcher',
+        description: null,
+        instructions: 'be a researcher',
+        autoStart: false,
+        launchMessage: 'go',
+        version: 4,
+      });
+    });
+
+    it('role absent from the index meta => version defaults to 1; autoStart defaults to true', async () => {
+      const { service } = makeBundleService({
+        index,
+        bundle: {
+          schemaVersion: 1,
+          language: 'en',
+          roles: [
+            { slug: 'newcomer', name: 'Newcomer', instructions: 'hi' },
+          ],
+        },
+      });
+      const res = await service.getCatalogBundle('general', 'en');
+      expect(res.roles[0]).toMatchObject({
+        slug: 'newcomer',
+        version: 1,
+        autoStart: true,
+        emoji: null,
+        launchMessage: null,
+      });
+    });
+  });
 });

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

@@ -1,12 +1,24 @@
 import {
+  BadGatewayException,
   BadRequestException,
   ConflictException,
   Injectable,
+  Logger,
 } from '@nestjs/common';
-import { AiAgentRoleRepo } from '@docmost/db/repos/ai-agent-roles/ai-agent-roles.repo';
-import { AiAgentRole } from '@docmost/db/types/entity.types';
+import {
+  AiAgentRoleRepo,
+  parseSource,
+} from '@docmost/db/repos/ai-agent-roles/ai-agent-roles.repo';
+import { AiAgentRole, RoleSource } from '@docmost/db/types/entity.types';
 import { CreateAgentRoleDto, UpdateAgentRoleDto } from './dto/agent-role.dto';
+import { ImportFromCatalogDto, UpdateFromCatalogDto } from './dto/agent-role-catalog.dto';
 import { RoleModelConfig } from './role-model-config';
+import { AiAgentRolesCatalogProvider } from './catalog/ai-agent-roles-catalog.provider';
+import {
+  CatalogBundleFile,
+  CatalogBundleMeta,
+  CatalogRole,
+} from './catalog/catalog-types';
 
 /**
  * Full (admin) view of an agent role. There are no secret columns on this table
@@ -24,6 +36,10 @@ export interface AgentRoleView {
   enabled: boolean;
   autoStart: boolean;
   launchMessage: string | null;
+  // Catalog origin of an imported role, or null for a manually-created one. The
+  // admin UI uses `version` to offer an UPDATE when the catalog ships a newer
+  // revision. Admin-only (deliberately absent from AgentRolePickerView).
+  source: RoleSource | null;
   createdAt: Date;
   updatedAt: Date;
 }
@@ -56,7 +72,12 @@ export interface AgentRolePickerView {
  */
 @Injectable()
 export class AiAgentRolesService {
-  constructor(private readonly repo: AiAgentRoleRepo) {}
+  private readonly logger = new Logger(AiAgentRolesService.name);
+
+  constructor(
+    private readonly repo: AiAgentRoleRepo,
+    private readonly catalog: AiAgentRolesCatalogProvider,
+  ) {}
 
   /**
    * List the workspace's roles. Admins get the full view (the settings page needs
@@ -165,6 +186,316 @@ export class AiAgentRolesService {
     return { success: true };
   }
 
+  // -------------------------------------------------------------------------
+  // Catalog (admin-only). The catalog is curated, untrusted YAML fetched +
+  // validated by AiAgentRolesCatalogProvider; this layer resolves localized
+  // text and reconciles a bundle against the workspace's existing roles.
+  // -------------------------------------------------------------------------
+
+  /**
+   * Browse the catalog. Returns the union of every bundle's languages (sorted)
+   * plus per-bundle metadata with `name` / `description` resolved to the
+   * requested `language` (fallback: 'en', then the first available locale).
+   */
+  async getCatalog(language?: string): Promise<{
+    languages: string[];
+    bundles: {
+      id: string;
+      name: string;
+      description: string | null;
+      languages: string[];
+      roles: { slug: string; version: number }[];
+    }[];
+  }> {
+    const index = await this.catalog.fetchIndex();
+    const languages = Array.from(
+      new Set(index.bundles.flatMap((b) => b.languages)),
+    ).sort();
+    const bundles = index.bundles.map((b) => ({
+      id: b.id,
+      name: localized(b.name, language) ?? b.id,
+      description: b.description ? localized(b.description, language) : null,
+      languages: b.languages,
+      roles: b.roles.map((r) => ({ slug: r.slug, version: r.version })),
+    }));
+    return { languages, bundles };
+  }
+
+  /**
+   * Shared read prefix for the two bundle-by-id catalog paths (getCatalogBundle /
+   * importFromCatalog): fetch the index, resolve the requested bundle's meta
+   * (502 if the index does not list it), fetch its per-language file, and build
+   * the slug->version map from the meta. The callers keep their own response /
+   * write logic; only this duplicated read is factored out here.
+   */
+  private async loadBundleById(
+    bundleId: string,
+    language: string,
+  ): Promise<{
+    meta: CatalogBundleMeta;
+    file: CatalogBundleFile;
+    versions: Map<string, number>;
+  }> {
+    const index = await this.catalog.fetchIndex();
+    const meta = index.bundles.find((b) => b.id === bundleId);
+    if (!meta) {
+      throw new BadGatewayException('Catalog bundle not found');
+    }
+    const file = await this.catalog.fetchBundle(bundleId, language);
+    return { meta, file, versions: versionMap(meta) };
+  }
+
+  /**
+   * Open one bundle in a language: returns each role's content plus the version
+   * taken from the index (so the client can compare against an imported role's
+   * source.version). A missing bundle/language => BadGateway (catalog issue).
+   */
+  async getCatalogBundle(
+    bundleId: string,
+    language: string,
+  ): Promise<{
+    bundleId: string;
+    language: string;
+    roles: {
+      slug: string;
+      emoji: string | null;
+      name: string;
+      description: string | null;
+      instructions: string;
+      autoStart: boolean;
+      launchMessage: string | null;
+      version: number;
+    }[];
+  }> {
+    const { file, versions } = await this.loadBundleById(bundleId, language);
+    return {
+      bundleId,
+      language,
+      roles: file.roles.map((r) => ({
+        slug: r.slug,
+        emoji: r.emoji ?? null,
+        name: r.name,
+        description: r.description ?? null,
+        instructions: r.instructions,
+        autoStart: r.autoStart ?? true,
+        launchMessage: r.launchMessage ?? null,
+        version: versions.get(r.slug) ?? 1,
+      })),
+    };
+  }
+
+  /**
+   * Import a bundle's roles into the workspace. A role is "already installed"
+   * (and thus skipped — updates are a separate action) only when an existing
+   * role matches BOTH its `source.slug` AND `source.language`: this is a
+   * multilingual catalog, so a different language of the same slug (e.g. the
+   * `ru` variant of a slug already installed as `en`) is a SEPARATE install and
+   * still imports. A name collision with an existing role is either skipped or
+   * imported under a free " (N)" name, per `dto.conflict`. Inserts run
+   * sequentially (the repo exposes no batch insert and the volume is tiny); a
+   * unique-name race still surfaces as an error entry rather than aborting the
+   * whole import.
+   */
+  async importFromCatalog(
+    workspaceId: string,
+    creatorId: string,
+    dto: ImportFromCatalogDto,
+  ): Promise<{
+    created: number;
+    skipped: number;
+    renamed: number;
+    errors: { slug: string; message: string }[];
+  }> {
+    const { file, versions } = await this.loadBundleById(
+      dto.bundleId,
+      dto.language,
+    );
+
+    const errors: { slug: string; message: string }[] = [];
+
+    // Resolve the selected catalog roles (honor dto.slugs; flag unknown ones).
+    let selected = file.roles;
+    if (dto.slugs && dto.slugs.length > 0) {
+      const wanted = new Set(dto.slugs);
+      const present = new Set(file.roles.map((r) => r.slug));
+      for (const slug of dto.slugs) {
+        if (!present.has(slug)) {
+          errors.push({ slug, message: 'Role not found in catalog bundle' });
+        }
+      }
+      selected = file.roles.filter((r) => wanted.has(r.slug));
+    }
+
+    const existingRoles = await this.repo.listByWorkspace(workspaceId);
+    // Catalog roles already installed in this workspace, keyed by slug+language
+    // (skip; never duplicate). The key MUST match the client install-state and
+    // updateFromCatalog (both match by source.slug AND source.language): the
+    // `ru` variant of a slug already installed as `en` is a separate install.
+    const installedKeys = new Set(
+      existingRoles
+        .map((r) => parseSource(r.source))
+        .filter((s): s is RoleSource => s !== null)
+        .map((s) => `${s.slug}:${s.language}`),
+    );
+    // Live role names (lowercased) for collision detection. Mutated as we
+    // insert so two imported roles cannot both grab the same name.
+    const takenNames = new Set(
+      existingRoles.map((r) => r.name.trim().toLowerCase()),
+    );
+
+    let created = 0;
+    let skipped = 0;
+    let renamed = 0;
+
+    for (const role of selected) {
+      // Already installed from the catalog in THIS language => skip (use
+      // update-from-catalog). A different language of the same slug still imports.
+      const installKey = `${role.slug}:${dto.language}`;
+      if (installedKeys.has(installKey)) {
+        skipped++;
+        continue;
+      }
+
+      let name = role.name.trim();
+      let didRename = false;
+      if (takenNames.has(name.toLowerCase())) {
+        if (dto.conflict === 'skip') {
+          skipped++;
+          continue;
+        }
+        // conflict === 'rename': find a free " (N)" suffix.
+        name = freeName(name, takenNames);
+        didRename = true;
+      }
+
+      const version = versions.get(role.slug) ?? 1;
+      try {
+        await this.repo.insert({
+          workspaceId,
+          creatorId,
+          name,
+          ...catalogRoleContentFields(role),
+          enabled: true,
+          source: { slug: role.slug, language: dto.language, version },
+        });
+        created++;
+        if (didRename) renamed++;
+        takenNames.add(name.toLowerCase());
+        installedKeys.add(installKey);
+      } catch (err) {
+        // A 23505 from the source-uniqueness index means a CONCURRENT import
+        // already installed this exact slug+language between our snapshot
+        // (installedKeys) and this insert: the in-process snapshot cannot see a
+        // sibling request's writes, so the partial unique index is the backstop.
+        // Outcome is identical to the snapshot-based skip above — count it as
+        // skipped (already installed) and continue; do NOT abort or error.
+        if (isSourceUniqueViolation(err)) {
+          skipped++;
+          installedKeys.add(installKey);
+          continue;
+        }
+        // Otherwise: a unique-NAME race (23505 on the name index) is expected and
+        // self-explanatory (it becomes a friendly per-role error). Any OTHER
+        // insert failure is unexpected, so log the root cause with enough context
+        // to diagnose it — the user-facing message is deliberately generic.
+        if (!isUniqueViolation(err)) {
+          this.logger.error(
+            `Failed to import catalog role (workspaceId=${workspaceId} bundleId=${dto.bundleId} slug=${role.slug}): ${err instanceof Error ? err.stack ?? err.message : String(err)}`,
+          );
+        }
+        errors.push({ slug: role.slug, message: importErrorMessage(err) });
+      }
+    }
+
+    return { created, skipped, renamed, errors };
+  }
+
+  /**
+   * Update an already-imported role from its catalog source when the catalog
+   * ships a newer version. Returns a discriminated result so the UI can explain
+   * a no-op (up-to-date / removed from catalog / language no longer offered).
+   * Never touches `enabled`; keeps the current name if the catalog's new name
+   * would collide with another role (avoiding the unique-name 409).
+   */
+  async updateFromCatalog(
+    workspaceId: string,
+    dto: UpdateFromCatalogDto,
+  ): Promise<
+    | { updated: false; reason: 'not-in-catalog' | 'up-to-date' | 'language-unavailable' }
+    | { updated: true; fromVersion: number; toVersion: number; role: AgentRoleView }
+  > {
+    const role = await this.repo.findById(dto.id, workspaceId);
+    if (!role) throw new BadRequestException('Role not found');
+
+    const source = parseSource(role.source);
+    if (!source || !source.slug) {
+      throw new BadRequestException('Role was not imported from the catalog');
+    }
+
+    const index = await this.catalog.fetchIndex();
+    // Find the bundle whose meta lists this slug, and its catalog version.
+    let meta: CatalogBundleMeta | undefined;
+    let currentVersion: number | undefined;
+    for (const b of index.bundles) {
+      const m = b.roles.find((r) => r.slug === source.slug);
+      if (m) {
+        meta = b;
+        currentVersion = m.version;
+        break;
+      }
+    }
+    if (!meta || currentVersion === undefined) {
+      return { updated: false, reason: 'not-in-catalog' };
+    }
+    if (currentVersion <= source.version) {
+      return { updated: false, reason: 'up-to-date' };
+    }
+    if (!meta.languages.includes(source.language)) {
+      return { updated: false, reason: 'language-unavailable' };
+    }
+
+    const file = await this.catalog.fetchBundle(meta.id, source.language);
+    const fresh = file.roles.find((r) => r.slug === source.slug);
+    if (!fresh) {
+      return { updated: false, reason: 'not-in-catalog' };
+    }
+
+    // Keep the current name when the catalog's new name would collide with
+    // another live role (avoids the unique-name 409). Same-name (case-insensitive)
+    // means "no rename needed".
+    const newName = fresh.name.trim();
+    let name = newName;
+    if (newName.toLowerCase() !== role.name.trim().toLowerCase()) {
+      const others = await this.repo.listByWorkspace(workspaceId);
+      const collision = others.some(
+        (r) =>
+          r.id !== role.id &&
+          r.name.trim().toLowerCase() === newName.toLowerCase(),
+      );
+      if (collision) name = role.name;
+    }
+
+    await this.repo.update(dto.id, workspaceId, {
+      name,
+      ...catalogRoleContentFields(fresh),
+      // enabled is deliberately NOT changed.
+      source: {
+        slug: source.slug,
+        language: source.language,
+        version: currentVersion,
+      },
+    });
+
+    const updated = await this.repo.findById(dto.id, workspaceId);
+    if (!updated) throw new BadRequestException('Role not found');
+    return {
+      updated: true,
+      fromVersion: source.version,
+      toVersion: currentVersion,
+      role: this.toView(updated),
+    };
+  }
+
   private toView(row: AiAgentRole): AgentRoleView {
     return {
       id: row.id,
@@ -176,6 +507,9 @@ export class AiAgentRolesService {
       enabled: row.enabled,
       autoStart: row.autoStart,
       launchMessage: row.launchMessage ?? null,
+      // parseSource yields a fully-valid RoleSource | null (the row is already
+      // normalized; this also keeps the field type honest without a cast).
+      source: parseSource(row.source),
       createdAt: row.createdAt,
       updatedAt: row.updatedAt,
     };
@@ -205,11 +539,7 @@ export class AiAgentRolesService {
  * failures keep surfacing as 500s.
  */
 function rethrowDuplicateName(err: unknown, name: string): never {
-  if (
-    err &&
-    typeof err === 'object' &&
-    (err as { code?: unknown }).code === '23505'
-  ) {
+  if (isUniqueViolation(err)) {
     throw new ConflictException(
       `A role named "${name}" already exists in this workspace.`,
     );
@@ -217,13 +547,120 @@ function rethrowDuplicateName(err: unknown, name: string): never {
   throw err;
 }
 
-/** '' / whitespace-only / undefined => null; otherwise the trimmed value. */
-function emptyToNull(value: string | undefined): string | null {
-  if (value === undefined) return null;
+/** Whether `err` is a Postgres unique-violation (SQLSTATE 23505). */
+function isUniqueViolation(err: unknown): boolean {
+  return (
+    !!err &&
+    typeof err === 'object' &&
+    (err as { code?: unknown }).code === '23505'
+  );
+}
+
+/**
+ * The partial unique index name from the
+ * 20260626T160000-ai-agent-roles-catalog-source-unique migration: unique on
+ * (workspace_id, source->>'slug', source->>'language') for catalog-imported,
+ * non-deleted rows. A 23505 carrying this constraint name is a source-collision
+ * (concurrent import of the same slug+language), distinct from a name-collision.
+ */
+const SOURCE_UNIQUE_CONSTRAINT = 'ai_agent_roles_workspace_source_unique';
+
+/**
+ * Whether `err` is the 23505 raised by the SOURCE-uniqueness index specifically
+ * (vs the name-uniqueness index). The active driver (`kysely-postgres-js` over
+ * `postgres@3.4.8`) exposes the violated constraint name on `constraint_name`,
+ * so we key off that (accepting the node-postgres-style `.constraint` as a
+ * fallback for other drivers) — that way a source race is skipped while a name
+ * race still surfaces as a friendly per-role error. A 23505 with no constraint
+ * name (e.g. a wrapped/test error) is NOT treated as a source collision,
+ * preserving the existing name-race behavior.
+ */
+function isSourceUniqueViolation(err: unknown): boolean {
+  if (!isUniqueViolation(err)) return false;
+  const e = err as { constraint_name?: unknown; constraint?: unknown };
+  return (
+    e.constraint_name === SOURCE_UNIQUE_CONSTRAINT ||
+    e.constraint === SOURCE_UNIQUE_CONSTRAINT
+  );
+}
+
+/**
+ * The role-content fields shared by import (insert) and update (patch) of a
+ * catalog role: emoji/description/launchMessage normalized to null, model config
+ * normalized, autoStart defaulted. The caller adds the write-specific fields
+ * (`name`, `source`, and on insert `workspaceId`/`creatorId`/`enabled`).
+ */
+function catalogRoleContentFields(role: CatalogRole): {
+  emoji: string | null;
+  description: string | null;
+  instructions: string;
+  modelConfig: Record<string, unknown> | null;
+  autoStart: boolean;
+  launchMessage: string | null;
+} {
+  return {
+    emoji: emptyToNull(role.emoji),
+    description: emptyToNull(role.description),
+    instructions: role.instructions,
+    modelConfig: normalizeModelConfig(role.modelConfig) as
+      | Record<string, unknown>
+      | null,
+    autoStart: role.autoStart ?? true,
+    launchMessage: emptyToNull(role.launchMessage ?? undefined),
+  };
+}
+
+/** '' / whitespace-only / undefined / null => null; otherwise the trimmed value. */
+function emptyToNull(value: string | null | undefined): string | null {
+  if (value === undefined || value === null) return null;
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : null;
 }
 
+/** slug -> version map from a bundle's index metadata. */
+function versionMap(meta: CatalogBundleMeta): Map<string, number> {
+  return new Map(meta.roles.map((r) => [r.slug, r.version]));
+}
+
+/**
+ * Resolve a localized value `{ en, ru, ... }` to `language`, falling back to
+ * 'en', then the first available locale. Returns null only for an empty map.
+ */
+function localized(
+  map: Record<string, string>,
+  language?: string,
+): string | null {
+  if (language && typeof map[language] === 'string') return map[language];
+  if (typeof map.en === 'string') return map.en;
+  const first = Object.values(map)[0];
+  return typeof first === 'string' ? first : null;
+}
+
+/**
+ * Find a free display name by appending " (2)", " (3)", ... when `base` is
+ * already taken (case-insensitive against `taken`). Caller adds the result to
+ * `taken` after a successful insert.
+ */
+function freeName(base: string, taken: Set<string>): string {
+  // `taken` is finite, so within `taken.size + 2` iterations a candidate index
+  // is guaranteed free; the 1000 cap is a defensive upper bound far above any
+  // realistic per-name collision count. The throw below is therefore
+  // unreachable in practice and only satisfies the return-type checker.
+  for (let n = 2; n < 1000; n++) {
+    const candidate = `${base} (${n})`;
+    if (!taken.has(candidate.toLowerCase())) return candidate;
+  }
+  throw new BadRequestException(`Too many roles named "${base}"`);
+}
+
+/** A short, safe message for an import insert failure (409 vs other). */
+function importErrorMessage(err: unknown): string {
+  if (isUniqueViolation(err)) {
+    return 'A role with this name already exists';
+  }
+  return 'Failed to import role';
+}
+
 /**
  * Normalize an incoming modelConfig DTO to the persisted shape, or null when
  * there is no usable override (no driver and no chatModel). The DTO's @IsIn

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

@@ -0,0 +1,459 @@
+import { BadGatewayException, BadRequestException } from '@nestjs/common';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import {
+  AiAgentRolesCatalogProvider,
+  isCatalogBundleFile,
+  isCatalogIndex,
+  isCatalogRole,
+} from './ai-agent-roles-catalog.provider';
+
+/**
+ * Provider tests against a mocked remote source (no network). They cover the
+ * happy read path (fetchIndex / fetchBundle) over the YAML catalog format, the
+ * block-scalar `instructions` round-trip, the malformed-shape rejection, the
+ * malformed-YAML rejection, rejection of non-http(s) sources (local sources are
+ * gone), and — most importantly — the `^[a-z0-9-]+$` path-traversal guard that
+ * runs BEFORE any path/URL is built. Fixtures are serialized with the same
+ * `yaml` library the provider parses with (`stringifyYaml`), so the tests
+ * exercise real YAML, not the JSON subset.
+ */
+describe('AiAgentRolesCatalogProvider', () => {
+  function makeProvider(source: string) {
+    const env = {
+      getAiAgentRolesCatalogSource: () => source,
+    };
+    return new AiAgentRolesCatalogProvider(env as never);
+  }
+
+  it('non-http(s) source => BadGateway (local sources removed)', async () => {
+    for (const source of ['', '/var/lib/agent-roles-catalog', './agent-roles-catalog']) {
+      const provider = makeProvider(source);
+      await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
+        BadGatewayException,
+      );
+    }
+  });
+
+  describe('remote fetch streaming size cap', () => {
+    const realFetch = global.fetch;
+    afterEach(() => {
+      global.fetch = realFetch;
+    });
+
+    /** A web ReadableStream that yields `chunks` (each a Uint8Array). */
+    function streamOf(chunks: Uint8Array[]): ReadableStream<Uint8Array> {
+      let i = 0;
+      return new ReadableStream<Uint8Array>({
+        pull(controller) {
+          if (i < chunks.length) controller.enqueue(chunks[i++]);
+          else controller.close();
+        },
+        // The provider cancels the reader on the too-large path; no-op here.
+        cancel() {},
+      });
+    }
+
+    /** A ReadableStream whose first read rejects (e.g. a mid-body AbortError). */
+    function errorStream(err: Error): ReadableStream<Uint8Array> {
+      return new ReadableStream<Uint8Array>({
+        pull() {
+          throw err;
+        },
+        cancel() {},
+      });
+    }
+
+    function mockResponse(opts: {
+      ok?: boolean;
+      status?: number;
+      headers?: Record<string, string>;
+      body: ReadableStream<Uint8Array> | null;
+      text?: string;
+    }): Response {
+      return {
+        ok: opts.ok ?? true,
+        status: opts.status ?? 200,
+        headers: { get: (k: string) => opts.headers?.[k.toLowerCase()] ?? null },
+        body: opts.body,
+        text: async () => opts.text ?? 'unused',
+      } as unknown as Response;
+    }
+
+    it('fetchBundle remote happy path => parses + validates', async () => {
+      const yaml = stringifyYaml({
+        schemaVersion: 1,
+        language: 'en',
+        roles: [
+          {
+            slug: 'researcher',
+            name: 'Researcher',
+            instructions: 'be a researcher',
+          },
+        ],
+      });
+      const body = streamOf([new TextEncoder().encode(yaml)]);
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(mockResponse({ body })) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      const bundle = await provider.fetchBundle('general', 'en');
+      expect(bundle.roles[0].slug).toBe('researcher');
+    });
+
+    it('fetchBundle remote malformed (role missing instructions) => BadGateway', async () => {
+      const yaml = stringifyYaml({
+        schemaVersion: 1,
+        language: 'fr',
+        roles: [{ slug: 'researcher', name: 'Chercheur' }],
+      });
+      const body = streamOf([new TextEncoder().encode(yaml)]);
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(mockResponse({ body })) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      await expect(provider.fetchBundle('general', 'fr')).rejects.toBeInstanceOf(
+        BadGatewayException,
+      );
+    });
+
+    it('declared Content-Length over the cap => BadGateway before reading the body', async () => {
+      global.fetch = jest.fn().mockResolvedValue(
+        mockResponse({
+          headers: { 'content-length': String(2_000_000) },
+          body: streamOf([new Uint8Array(10)]),
+        }),
+      ) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
+        BadGatewayException,
+      );
+    });
+
+    it('streamed body exceeding the cap (no/under-reported Content-Length) => BadGateway', async () => {
+      // 1.5 MB streamed in 256 KB chunks, with no Content-Length header.
+      const chunks = Array.from(
+        { length: 6 },
+        () => new Uint8Array(256 * 1024),
+      );
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(mockResponse({ body: streamOf(chunks) })) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
+        BadGatewayException,
+      );
+    });
+
+    it('fetch rejects (network failure) => BadGateway (unavailable)', async () => {
+      global.fetch = jest
+        .fn()
+        .mockRejectedValue(new Error('ECONNREFUSED')) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
+        BadGatewayException,
+      );
+    });
+
+    it('passes redirect:"error" to fetch (redirect-SSRF hardening)', async () => {
+      const fetchMock = jest
+        .fn()
+        .mockResolvedValue(
+          mockResponse({ body: streamOf([new Uint8Array(0)]) }),
+        );
+      global.fetch = fetchMock as never;
+      const provider = makeProvider('https://catalog.example.com');
+      // Body shape is irrelevant; an empty stream parses to an empty YAML doc
+      // (null), fails the shape guard and throws, but the fetch call (with its
+      // init) still happened.
+      await expect(provider.fetchIndex()).rejects.toBeDefined();
+      expect(fetchMock).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({ redirect: 'error' }),
+      );
+    });
+
+    it('redirect response rejects (redirect:"error") => BadGateway', async () => {
+      // With redirect:"error", the platform fetch rejects on a 3xx instead of
+      // following it. Simulate that: the mock rejects when asked not to follow.
+      global.fetch = jest.fn().mockImplementation((_url, init) => {
+        if (init?.redirect === 'error') {
+          return Promise.reject(
+            new TypeError('fetch failed: unexpected redirect'),
+          );
+        }
+        return Promise.resolve(
+          mockResponse({ status: 302, body: null }),
+        );
+      }) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
+        BadGatewayException,
+      );
+    });
+
+    it('non-ok response (503) => BadGateway carrying the status', async () => {
+      global.fetch = jest.fn().mockResolvedValue(
+        mockResponse({ ok: false, status: 503, body: null }),
+      ) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      await expect(provider.fetchIndex()).rejects.toThrow(/503/);
+    });
+
+    it('small streamed body parses normally (cap not hit)', async () => {
+      const yaml = stringifyYaml({
+        schemaVersion: 1,
+        bundles: [
+          {
+            id: 'general',
+            name: { en: 'General' },
+            languages: ['en'],
+            roles: [{ slug: 'researcher', version: 2 }],
+          },
+        ],
+      });
+      const body = streamOf([new TextEncoder().encode(yaml)]);
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(mockResponse({ body })) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      const index = await provider.fetchIndex();
+      expect(index.bundles[0].id).toBe('general');
+    });
+
+    it('body read aborts mid-stream (AbortError) => BadGateway (not a generic 500)', async () => {
+      // The 10s timer aborts the whole request; on a slow/dripping source the
+      // body read (reader.read()) rejects with an AbortError AFTER fetch()
+      // resolved. The provider must map that to BadGateway, not let it escape.
+      const abortErr = Object.assign(new Error('The operation was aborted'), {
+        name: 'AbortError',
+      });
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(mockResponse({ body: errorStream(abortErr) })) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
+        BadGatewayException,
+      );
+    });
+
+    it('null body (no readable stream) => response.text() fallback parses', async () => {
+      const yaml = stringifyYaml({
+        schemaVersion: 1,
+        bundles: [
+          {
+            id: 'general',
+            name: { en: 'General' },
+            languages: ['en'],
+            roles: [{ slug: 'researcher', version: 2 }],
+          },
+        ],
+      });
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(mockResponse({ body: null, text: yaml })) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      const index = await provider.fetchIndex();
+      expect(index.bundles[0].id).toBe('general');
+    });
+
+    it('null body + text() over the cap => BadGateway (too large)', async () => {
+      const oversized = 'a'.repeat(1_000_001);
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(
+          mockResponse({ body: null, text: oversized }),
+        ) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
+        BadGatewayException,
+      );
+    });
+
+    it('invalid YAML body => BadGateway (parse failure)', async () => {
+      // An unterminated flow mapping is not valid YAML, so YAML.parse throws and
+      // the provider maps it to BadGateway (not a generic 500).
+      const body = streamOf([
+        new TextEncoder().encode('schemaVersion: {not: closed'),
+      ]);
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(mockResponse({ body })) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
+        BadGatewayException,
+      );
+    });
+
+    it('YAML with a duplicate key (strict) => BadGateway (parse failure)', async () => {
+      // strict:true rejects duplicate mapping keys rather than last-wins coercing
+      // them — a defensive parse on untrusted input.
+      const body = streamOf([
+        new TextEncoder().encode(
+          'schemaVersion: 1\nbundles: []\nschemaVersion: 2\n',
+        ),
+      ]);
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(mockResponse({ body })) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
+        BadGatewayException,
+      );
+    });
+
+    it('malformed index.yaml (valid YAML, wrong shape) => BadGateway', async () => {
+      // Parses as YAML but fails isCatalogIndex (schemaVersion not a number).
+      const body = streamOf([
+        new TextEncoder().encode(
+          stringifyYaml({ schemaVersion: 'x', bundles: [] }),
+        ),
+      ]);
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(mockResponse({ body })) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      await expect(provider.fetchIndex()).rejects.toThrow(/malformed/i);
+    });
+
+    it('block-scalar instructions round-trips to the exact multi-line string', async () => {
+      // The whole point of the YAML migration: a long `instructions` prompt is
+      // stored as a literal block scalar (|-) for line-by-line diffs, and must
+      // resolve byte-for-byte to the original multi-line string.
+      const instructions = [
+        'Line one of the prompt.',
+        '',
+        '  Indented bullet that must survive.',
+        'Final line, no trailing newline.',
+      ].join('\n');
+      const yaml = stringifyYaml(
+        {
+          schemaVersion: 1,
+          language: 'en',
+          roles: [{ slug: 'researcher', name: 'Researcher', instructions }],
+        },
+        { lineWidth: 0 },
+      );
+      // Sanity: the fixture really uses a literal block scalar (|, optionally
+      // with an indentation indicator), not a flow/quoted string.
+      expect(yaml).toMatch(/instructions: \|/);
+      const body = streamOf([new TextEncoder().encode(yaml)]);
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(mockResponse({ body })) as never;
+      const provider = makeProvider('https://catalog.example.com');
+      const bundle = await provider.fetchBundle('research', 'en');
+      expect(bundle.roles[0].instructions).toBe(instructions);
+    });
+  });
+
+  describe('path-traversal / SSRF guard (^[a-z0-9-]+$)', () => {
+    const bad = ['../etc', 'a/b', 'A', 'foo.bar', 'foo_bar', '', '..'];
+
+    for (const value of bad) {
+      it(`rejects bundleId="${value}" with BadRequest`, async () => {
+        const provider = makeProvider('https://catalog.example.com');
+        await expect(
+          provider.fetchBundle(value, 'en'),
+        ).rejects.toBeInstanceOf(BadRequestException);
+      });
+
+      it(`rejects language="${value}" with BadRequest`, async () => {
+        const provider = makeProvider('https://catalog.example.com');
+        await expect(
+          provider.fetchBundle('general', value),
+        ).rejects.toBeInstanceOf(BadRequestException);
+      });
+    }
+  });
+
+  // ---------------------------------------------------------------------------
+  // Pin the REAL shipped catalog files (not synthetic fixtures). The JSON->YAML
+  // migration was a hand conversion, so the realistic failure is a hand-edit
+  // error in one of the 5 content YAML files (the index + the four per-bundle/
+  // lang files: index.yaml plus bundles/{editorial,research}/{en,ru}.yaml) — a
+  // quote/colon in a description, a broken
+  // emoji/arrow, a block-scalar indent slip that silently changes or drops
+  // instructions). Nothing else in CI parses these files — `scripts/check.mjs`
+  // is not wired into any turbo/husky/CI step — so this is the only automated
+  // guard over the shipped content. We read them straight off disk, parse with
+  // the SAME options the provider uses (strict + maxAliasCount, see parseYaml in
+  // the provider), and run them through the provider's own type guards. A future
+  // edit that breaks a real file fails here.
+  // ---------------------------------------------------------------------------
+  describe('real shipped catalog files (the YAML migration must not break them)', () => {
+    // Spec lives at apps/server/src/core/ai-chat/roles/catalog/; the catalog
+    // ships at the repo root (agent-roles-catalog/) — seven levels up.
+    const CATALOG_DIR = join(
+      __dirname,
+      '../../../../../../../agent-roles-catalog',
+    );
+    // Match the provider's parseYaml exactly (untrusted-input parse options).
+    const PARSE_OPTS = { strict: true, maxAliasCount: 100 } as const;
+
+    function readCatalogYaml(rel: string): unknown {
+      return parseYaml(readFileSync(join(CATALOG_DIR, rel), 'utf8'), PARSE_OPTS);
+    }
+
+    // Load + validate the real index lazily (only when a test runs), so a broken
+    // real file fails ONLY these catalog tests — not collection of the entire
+    // spec, which also holds the unrelated mocked-remote provider tests above.
+    function loadRealIndex() {
+      const parsed = readCatalogYaml('index.yaml');
+      if (!isCatalogIndex(parsed)) {
+        throw new Error('Real index.yaml is not a valid catalog index');
+      }
+      return parsed;
+    }
+
+    it('index.yaml parses + validates with the provider guard', () => {
+      expect(isCatalogIndex(readCatalogYaml('index.yaml'))).toBe(true);
+    });
+
+    it('editorial bundle still ships the fact-checker role', () => {
+      const editorial = loadRealIndex().bundles.find((b) => b.id === 'editorial');
+      expect(editorial).toBeDefined();
+      expect(editorial?.roles.map((r) => r.slug)).toContain('fact-checker');
+    });
+
+    // Driven by the real index (read inside the test, so it's lazy): every
+    // declared bundle + language file must parse, validate, and be in EXACT slug
+    // correspondence with the index — every declared role present AND no
+    // undeclared extras — mirroring scripts/check.mjs, which requires both
+    // directions. A bundle or language added later is covered automatically.
+    it('every declared bundle/language file is valid and in exact slug correspondence', () => {
+      const index = loadRealIndex();
+      // Guard against an empty index silently passing the loops below.
+      expect(index.bundles.length).toBeGreaterThan(0);
+      for (const bundle of index.bundles) {
+        const declaredSlugs = bundle.roles.map((r) => r.slug);
+        expect(bundle.languages.length).toBeGreaterThan(0);
+        for (const lang of bundle.languages) {
+          const rel = `bundles/${bundle.id}/${lang}.yaml`;
+          const file = readCatalogYaml(rel);
+          expect(isCatalogBundleFile(file)).toBe(true);
+          // Narrow for TS and access fields safely.
+          if (!isCatalogBundleFile(file)) continue;
+          expect(file.language).toBe(lang);
+          const fileSlugs = file.roles.map((r) => r.slug);
+          // Existing direction: every declared role is present in the file.
+          for (const slug of declaredSlugs) {
+            expect(fileSlugs).toContain(slug);
+          }
+          // Symmetric direction: the file carries NO undeclared/extra roles, so
+          // file slugs and declared slugs must be the SAME set (exact match).
+          // Catches a hand-edit that copies a stray role into a bundle file.
+          expect([...fileSlugs].sort()).toEqual([...declaredSlugs].sort());
+          expect(file.roles.length).toBeGreaterThan(0);
+          for (const role of file.roles) {
+            expect(isCatalogRole(role)).toBe(true);
+            expect(typeof role.instructions).toBe('string');
+            expect(role.instructions.trim().length).toBeGreaterThan(0);
+            expect(role.name.trim().length).toBeGreaterThan(0);
+          }
+        }
+      }
+    });
+  });
+});

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

@@ -0,0 +1,328 @@
+import {
+  BadGatewayException,
+  BadRequestException,
+  Injectable,
+  Logger,
+} from '@nestjs/common';
+import { parse as parseYamlDoc } from 'yaml';
+import { EnvironmentService } from '../../../../integrations/environment/environment.service';
+import {
+  CatalogBundleFile,
+  CatalogBundleMeta,
+  CatalogIndex,
+  CatalogRole,
+} from './catalog-types';
+
+/** Identifier shape allowed in any path/URL segment (bundleId, language). The
+ *  ONLY characters that can appear in a fetched path — the path-traversal and
+ *  SSRF guard. Anything else is rejected before a path/URL is built. */
+const SEGMENT_RE = /^[a-z0-9-]+$/;
+
+/** Remote fetch timeout and response-size cap. A curated catalog file is tiny;
+ *  the cap stops a hostile/misconfigured source from streaming unbounded data. */
+const FETCH_TIMEOUT_MS = 10_000;
+const MAX_BYTES = 1_000_000;
+
+/**
+ * Fetches + validates the agent-roles catalog from its configured source. The
+ * source (EnvironmentService.getAiAgentRolesCatalogSource()) is an http(s)://
+ * base URL — REMOTE only; local-filesystem sources are no longer supported. The
+ * value is baked into the Docker image at build time (set per-branch in CI).
+ *
+ * The catalog is UNTRUSTED input: every file is YAML-parsed with a SAFE schema
+ * (standard JSON-compatible tags only — no custom `!!` tags / no code execution)
+ * and run through a hand-written type guard before any field is exposed, and
+ * every dynamic path segment is validated against SEGMENT_RE up front
+ * (path-traversal + SSRF).
+ */
+@Injectable()
+export class AiAgentRolesCatalogProvider {
+  private readonly logger = new Logger(AiAgentRolesCatalogProvider.name);
+
+  constructor(private readonly environmentService: EnvironmentService) {}
+
+  /** Read + validate the top-level index (`index.yaml`). */
+  async fetchIndex(): Promise<CatalogIndex> {
+    const raw = await this.readRelative('index.yaml');
+    const parsed = this.parseYaml(raw, 'index.yaml');
+    if (!isCatalogIndex(parsed)) {
+      throw new BadGatewayException(
+        'Agent roles catalog index is malformed (index.yaml)',
+      );
+    }
+    return parsed;
+  }
+
+  /** Read + validate one language file (`bundles/<bundleId>/<language>.yaml`). */
+  async fetchBundle(
+    bundleId: string,
+    language: string,
+  ): Promise<CatalogBundleFile> {
+    // SECURITY: validate BEFORE building any path/URL (path-traversal + SSRF).
+    this.assertSegment(bundleId, 'bundleId');
+    this.assertSegment(language, 'language');
+    const rel = `bundles/${bundleId}/${language}.yaml`;
+    const raw = await this.readRelative(rel);
+    const parsed = this.parseYaml(raw, rel);
+    if (!isCatalogBundleFile(parsed)) {
+      throw new BadGatewayException(
+        `Agent roles catalog bundle is malformed (${rel})`,
+      );
+    }
+    return parsed;
+  }
+
+  /** Reject a segment that is not a safe `[a-z0-9-]+` identifier. */
+  private assertSegment(value: string, field: string): void {
+    if (typeof value !== 'string' || !SEGMENT_RE.test(value)) {
+      throw new BadRequestException(`Invalid ${field}`);
+    }
+  }
+
+  /**
+   * Safe YAML parse with a clear BadGateway on malformed content. The catalog is
+   * untrusted, so we lean on the `yaml` library's default `core` schema, which
+   * only produces JSON-compatible values (objects/arrays/strings/numbers/
+   * booleans/null) and NEVER constructs arbitrary types or runs code — there is
+   * no `!!js`-style tag handling. `strict: true` rejects duplicate keys instead
+   * of silently coercing them. (Note: in yaml@2.8.x an unknown custom tag does
+   * NOT throw even under `strict` — the parser logs a warning and resolves the
+   * node to a plain scalar; the catalog stays safe because the default schema
+   * never builds arbitrary types from a tag and our hand-written type guards
+   * reject any value of the wrong shape.) The alias-expansion guard
+   * (`maxAliasCount`) bounds billion-laughs blow-ups (the 1 MB streaming
+   * cap already limits the input itself). JSON is a YAML subset, so a leftover
+   * `.json`-style body still parses here too.
+   */
+  private parseYaml(raw: string, rel: string): unknown {
+    try {
+      return parseYamlDoc(raw, { strict: true, maxAliasCount: 100 });
+    } catch (err) {
+      const reason = shortError(err);
+      this.logger.error(`Agent roles catalog YAML parse failed (${rel}): ${reason}`);
+      throw new BadGatewayException(
+        `Agent roles catalog file is not valid YAML (${rel}): ${reason}`,
+      );
+    }
+  }
+
+  /** Read a relative catalog path as text from the configured remote source. */
+  private async readRelative(rel: string): Promise<string> {
+    const source = this.environmentService
+      .getAiAgentRolesCatalogSource()
+      .trim();
+    if (!/^https?:\/\//i.test(source)) {
+      this.logger.error(
+        'Agent roles catalog source is not configured (expected an http(s):// base URL)',
+      );
+      throw new BadGatewayException(
+        'Agent roles catalog is unavailable: source is not configured',
+      );
+    }
+    return this.fetchRemote(source, rel);
+  }
+
+  /**
+   * Fetch a remote catalog file with a timeout + a STREAMING size cap. The body
+   * is never buffered in full before the check: we reject on a too-large
+   * Content-Length up front, then read the stream chunk-by-chunk and abort the
+   * moment the running total exceeds MAX_BYTES, so a hostile/misconfigured
+   * source cannot make us hold an unbounded body in memory.
+   */
+  private async fetchRemote(base: string, rel: string): Promise<string> {
+    const url = `${base.replace(/\/+$/, '')}/${rel}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      let response: Response;
+      try {
+        // `redirect: 'error'` hardens against redirect-SSRF: a
+        // compromised-but-trusted upstream cannot 3xx the fetch into the
+        // internal network (e.g. http://169.254.169.254/...). A redirect
+        // response rejects here and is mapped to BadGateway below.
+        response = await fetch(url, {
+          signal: controller.signal,
+          redirect: 'error',
+        });
+      } catch (err) {
+        const reason = shortError(err);
+        this.logger.error(
+          `Agent roles catalog remote fetch failed (${rel}): ${reason}`,
+        );
+        throw new BadGatewayException(
+          `Agent roles catalog is unavailable: ${reason}`,
+        );
+      }
+      if (!response.ok) {
+        this.logger.error(
+          `Agent roles catalog remote returned ${response.status} (${rel})`,
+        );
+        throw new BadGatewayException(
+          `Agent roles catalog returned ${response.status}`,
+        );
+      }
+      // Reject a too-large declared size before reading any body bytes.
+      const declared = Number(response.headers.get('content-length'));
+      if (Number.isFinite(declared) && declared > MAX_BYTES) {
+        throw new BadGatewayException('Agent roles catalog file is too large');
+      }
+      // Bound the actual read: a missing/lying Content-Length is caught here.
+      // The 10s timer aborts the WHOLE request, so a slow/dripping hostile
+      // source rejects reader.read() (or response.text()) with an AbortError
+      // mid-body. Map that — and any other read failure — to a logged
+      // BadGateway so the admin endpoint returns 502 (not a generic 500). The
+      // cap's own BadGateway is rethrown as-is (no double-wrap).
+      try {
+        if (response.body) {
+          return await readStreamCapped(response.body, MAX_BYTES);
+        }
+        // Edge: no readable stream — fall back to a buffered read + length check.
+        const text = await response.text();
+        if (text.length > MAX_BYTES) {
+          throw new BadGatewayException('Agent roles catalog file is too large');
+        }
+        return text;
+      } catch (err) {
+        if (err instanceof BadGatewayException) throw err;
+        const reason = shortError(err);
+        this.logger.error(
+          `Agent roles catalog body read failed (${rel}): ${reason}`,
+        );
+        throw new BadGatewayException(
+          `Agent roles catalog is unavailable: ${reason}`,
+        );
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/**
+ * Read a web ReadableStream into a UTF-8 string, throwing as soon as the
+ * accumulated byte count exceeds `maxBytes` (the reader is cancelled so the
+ * underlying connection is released). Never buffers more than the cap + the
+ * final chunk before bailing out.
+ */
+async function readStreamCapped(
+  body: ReadableStream<Uint8Array>,
+  maxBytes: number,
+): Promise<string> {
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      total += value.length;
+      if (total > maxBytes) {
+        throw new BadGatewayException('Agent roles catalog file is too large');
+      }
+      chunks.push(value);
+    }
+  } finally {
+    // Release the stream on both the normal and the too-large/abort paths.
+    await reader.cancel().catch(() => undefined);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+/**
+ * A short, non-sensitive error string for logging/propagation: only the first
+ * line of the message head is kept (upstream bodies / URLs are discarded).
+ */
+function shortError(err: unknown): string {
+  let message = '';
+  if (typeof err === 'string') {
+    message = err;
+  } else if (
+    err &&
+    typeof err === 'object' &&
+    typeof (err as { message?: unknown }).message === 'string'
+  ) {
+    // Read `.message` directly (works for Error instances and the realm-shifted
+    // Error-likes jest can hand back, where `instanceof Error` is false).
+    message = (err as { message: string }).message;
+  }
+  const head = (message || 'unknown error').split('\n')[0];
+  return head.length > 200 ? `${head.slice(0, 200)}…` : head;
+}
+
+// ---------------------------------------------------------------------------
+// Hand-written type guards (no zod / new deps). Each validates the exact wire
+// shape declared in catalog-types.ts; anything else is rejected by the caller.
+// ---------------------------------------------------------------------------
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function isStringMap(v: unknown): v is Record<string, string> {
+  if (!isObject(v)) return false;
+  return Object.values(v).every((x) => typeof x === 'string');
+}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}
+
+export function isCatalogRole(v: unknown): v is CatalogRole {
+  if (!isObject(v)) return false;
+  if (typeof v.slug !== 'string') return false;
+  if (typeof v.name !== 'string') return false;
+  if (typeof v.instructions !== 'string') return false;
+  if (v.emoji !== undefined && typeof v.emoji !== 'string') return false;
+  if (v.description !== undefined && typeof v.description !== 'string') {
+    return false;
+  }
+  if (v.autoStart !== undefined && typeof v.autoStart !== 'boolean') {
+    return false;
+  }
+  if (
+    v.launchMessage !== undefined &&
+    v.launchMessage !== null &&
+    typeof v.launchMessage !== 'string'
+  ) {
+    return false;
+  }
+  if (
+    v.modelConfig !== undefined &&
+    v.modelConfig !== null &&
+    !isObject(v.modelConfig)
+  ) {
+    return false;
+  }
+  return true;
+}
+
+export function isCatalogBundleFile(v: unknown): v is CatalogBundleFile {
+  if (!isObject(v)) return false;
+  if (typeof v.schemaVersion !== 'number') return false;
+  if (typeof v.language !== 'string') return false;
+  if (!Array.isArray(v.roles)) return false;
+  return v.roles.every(isCatalogRole);
+}
+
+function isCatalogBundleMeta(v: unknown): v is CatalogBundleMeta {
+  if (!isObject(v)) return false;
+  if (typeof v.id !== 'string') return false;
+  if (!isStringMap(v.name)) return false;
+  if (v.description !== undefined && !isStringMap(v.description)) return false;
+  if (!isStringArray(v.languages)) return false;
+  if (!Array.isArray(v.roles)) return false;
+  return v.roles.every(
+    (r) =>
+      isObject(r) &&
+      typeof r.slug === 'string' &&
+      typeof r.version === 'number',
+  );
+}
+
+export function isCatalogIndex(v: unknown): v is CatalogIndex {
+  if (!isObject(v)) return false;
+  if (typeof v.schemaVersion !== 'number') return false;
+  if (!Array.isArray(v.bundles)) return false;
+  return v.bundles.every(isCatalogBundleMeta);
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Catalog wire shapes. The catalog is curated, untrusted YAML (a GitHub repo or
+ * a local folder), so every shape is validated by a hand-written type guard in
+ * the provider before any field is used — no zod on the server (YAML is parsed
+ * with the `yaml` library's safe, JSON-compatible schema).
+ *
+ * Localized fields (`name` / `description` at the bundle level) are
+ * `Record<language, string>` so one bundle serves many UI languages; per-role
+ * `name` / `description` are already language-specific (the bundle file is keyed
+ * by language).
+ */
+
+/** One role's content as shipped in a per-language bundle file. */
+export interface CatalogRole {
+  slug: string;
+  emoji?: string;
+  name: string;
+  description?: string;
+  instructions: string;
+  autoStart?: boolean;
+  launchMessage?: string | null;
+  // Optional model override; same loose object shape as ai_agent_roles.model_config.
+  modelConfig?: Record<string, unknown> | null;
+}
+
+/** A single language file: `bundles/<id>/<language>.yaml`. */
+export interface CatalogBundleFile {
+  schemaVersion: number;
+  language: string;
+  roles: CatalogRole[];
+}
+
+/** Bundle metadata as listed in the top-level index. Versions live here (per
+ *  slug), so an UPDATE check needs only the index, not every language file. */
+export interface CatalogBundleMeta {
+  id: string;
+  // Localized display name/description: { en: '...', ru: '...' }.
+  name: Record<string, string>;
+  description?: Record<string, string>;
+  languages: string[];
+  roles: { slug: string; version: number }[];
+}
+
+/** Top-level catalog index: `index.yaml`. */
+export interface CatalogIndex {
+  schemaVersion: number;
+  bundles: CatalogBundleMeta[];
+}

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

@@ -0,0 +1,62 @@
+import {
+  IsArray,
+  IsIn,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Matches,
+  MaxLength,
+} from 'class-validator';
+
+/** Safe identifier shape for any catalog path segment (bundleId / language).
+ *  Mirrors SEGMENT_RE in the catalog provider — the path-traversal/SSRF guard
+ *  is enforced both at the API boundary (here) and in the provider. */
+const SEGMENT_RE = /^[a-z0-9-]+$/;
+
+/** Browse the catalog, optionally localized to `language` (defaults applied in
+ *  the service: fall back to 'en', then the first available language). */
+export class CatalogQueryDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(16)
+  language?: string;
+}
+
+/** Open one catalog bundle in a specific language. */
+export class CatalogBundleDto {
+  @IsString()
+  @Matches(SEGMENT_RE)
+  bundleId: string;
+
+  @IsString()
+  @Matches(SEGMENT_RE)
+  language: string;
+}
+
+/** Import roles from a catalog bundle into the workspace. */
+export class ImportFromCatalogDto {
+  @IsString()
+  @Matches(SEGMENT_RE)
+  bundleId: string;
+
+  @IsString()
+  @Matches(SEGMENT_RE)
+  language: string;
+
+  // Omitted => import the whole bundle; otherwise only these slugs.
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  slugs?: string[];
+
+  // How to handle a name collision with an existing (non-catalog) role:
+  // 'skip' leaves it; 'rename' imports under a free " (N)" name.
+  @IsIn(['skip', 'rename'])
+  conflict: 'skip' | 'rename';
+}
+
+/** Update an already-imported role from its catalog source. */
+export class UpdateFromCatalogDto {
+  @IsUUID()
+  id: string;
+}

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

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

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

@@ -16,6 +16,7 @@ import {
 import { resolveCurrentPageResult } from './current-page.util';
 import { parseNodeArg } from './parse-node-arg';
 import { modelFriendlyInput } from './model-friendly-input';
+import { SandboxStore } from '../../../integrations/sandbox/sandbox.store';
 
 /**
  * Per-user, per-request adapter that exposes Docmost READ operations to the
@@ -41,6 +42,8 @@ export class AiChatToolsService {
     private readonly pageEmbeddingRepo: PageEmbeddingRepo,
     private readonly spaceMemberRepo: SpaceMemberRepo,
     private readonly pagePermissionRepo: PagePermissionRepo,
+    // Shared singleton in-RAM blob store backing the stash tool.
+    private readonly sandboxStore: SandboxStore,
   ) {}
 
   async forUser(
@@ -86,11 +89,17 @@ export class AiChatToolsService {
         aiChatId,
       });
 
+    // Bind the stash tool to the shared in-RAM SandboxStore. The store owns the
+    // anonymous-URL composition (putAndLink) and the live/evict probes the MCP
+    // package needs to keep its mirror counts honest under FIFO eviction (the
+    // package never touches env or the store). asSink() centralizes the uri↔id
+    // mapping next to putAndLink, shared with the embedded-MCP wiring site.
     const { DocmostClient, sharedToolSpecs } = await loadDocmostMcp();
     const client: DocmostClientLike = new DocmostClient({
       apiUrl,
       getToken,
       getCollabToken,
+      sandbox: this.sandboxStore.asSink(),
     });
 
     // Build an ai-SDK tool from a shared, zod-agnostic spec. The spec owns the
@@ -625,6 +634,14 @@ export class AiChatToolsService {
         async ({ pageId, edits }) => await client.editPageText(pageId, edits),
       ),
 
+      // Returns ONLY the short link object — never the document body — so a
+      // large page can be handed to an external consumer without bloating
+      // context.
+      stashPage: sharedTool(
+        sharedToolSpecs.stashPage,
+        async ({ pageId }) => await client.stashPage(pageId),
+      ),
+
       patchNode: tool({
         description:
           'Replace a single content block (by id) with a new ProseMirror ' +

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

@@ -154,6 +154,14 @@ export interface DocmostClientLike {
     commentId: string,
     resolved: boolean,
   ): Promise<Record<string, unknown>>;
+  // Serialize a page + mirror its internal images into the blob sandbox; returns
+  // ONLY a short anonymous URL (the body never enters the model context).
+  stashPage(pageId: string): Promise<{
+    uri: string;
+    sha256: string;
+    size: number;
+    images: { mirrored: number; failed: number };
+  }>;
 }
 
 export type DocmostClientConfig = {
@@ -161,6 +169,18 @@ export type DocmostClientConfig = {
   getToken: () => Promise<string>;
   // Provenance collab-token provider for content mutations (signed agent claim).
   getCollabToken?: () => Promise<string>;
+  // Optional blob-sandbox sink for the stash tool. `put` stores a blob in the
+  // host's in-RAM SandboxStore and returns the anonymous read URL + integrity.
+  // The optional `has`/`evict` probes let stashPage keep its mirror counts
+  // honest under the store's FIFO eviction (mirror of the package's sink type).
+  sandbox?: {
+    put: (
+      buf: Buffer,
+      mime: string,
+    ) => { uri: string; sha256: string; size: number };
+    has?: (uri: string) => boolean;
+    evict?: (uri: string) => void;
+  };
 };
 
 export interface DocmostClientCtor {

apps/server/src/core/page/services/page.service.footnote-canonicalize.spec.ts

@@ -0,0 +1,153 @@
+// Binding test for issue #228 must-fix #1 / test-coverage #12: footnote
+// canonicalization moved OUT of parseProsemirrorContent and is now applied only
+// on FULL-document writes (createPage, and updatePageContent with operation
+// 'replace'), NEVER on an append/prepend FRAGMENT.
+//
+// The Yjs encode / plain-text extract are stubbed (partial module mock keeps the
+// REAL canonicalizeFootnotes) and parseProsemirrorContent is spied to return the
+// raw fixture, so the test isolates the canonicalize BINDING from schema/Yjs.
+jest.mock('@docmost/editor-ext', () => {
+  const actual = jest.requireActual('@docmost/editor-ext');
+  return {
+    ...actual,
+    createYdocFromJson: jest.fn(() => Buffer.from([])),
+    jsonToText: jest.fn(() => ''),
+  };
+});
+
+import { PageService } from './page.service';
+
+const refNode = (id: string) => ({ type: 'footnoteReference', attrs: { id } });
+const defNode = (id: string, text: string) => ({
+  type: 'footnoteDefinition',
+  attrs: { id },
+  content: [{ type: 'paragraph', content: [{ type: 'text', text }] }],
+});
+const doc = (...content: any[]) => ({ type: 'doc', content });
+
+/** A full doc whose footnote definitions are OUT of reference order (b,a refs;
+ *  a,b defs) — canonicalization must reorder the definitions to [b, a]. */
+const outOfOrderFull = () =>
+  doc(
+    { type: 'paragraph', content: [{ type: 'text', text: 'x' }, refNode('b'), refNode('a')] },
+    { type: 'footnotesList', content: [defNode('a', 'A'), defNode('b', 'B')] },
+  );
+
+/** A definition-ONLY fragment (no references): canonicalizing it would drop the
+ *  whole footnotesList (referenceIds is empty) — i.e. LOSE the footnote. */
+const defOnlyFragment = () =>
+  doc({ type: 'footnotesList', content: [defNode('a', 'appended note')] });
+
+/** A reference-only fragment that REUSES an id defined elsewhere in the live
+ *  doc: canonicalizing it would synthesize a bogus empty footnotesList/def. */
+const refReuseFragment = () =>
+  doc({ type: 'paragraph', content: [{ type: 'text', text: 'more' }, refNode('a')] });
+
+function listDefIds(content: any): string[] {
+  const list = (content.content ?? []).find((n: any) => n.type === 'footnotesList');
+  return (list?.content ?? [])
+    .filter((n: any) => n.type === 'footnoteDefinition')
+    .map((n: any) => n.attrs?.id);
+}
+function hasFootnotesList(content: any): boolean {
+  return (content.content ?? []).some((n: any) => n.type === 'footnotesList');
+}
+
+describe('PageService footnote canonicalization binding (#228)', () => {
+  function makeService() {
+    let insertedContent: any = null;
+    let yjsPayload: any = null;
+
+    const pageRepo = {
+      insertPage: jest.fn(async (values: any) => {
+        insertedContent = values.content;
+        return { id: 'page-id', slugId: 'slug-id' };
+      }),
+    };
+    const generalQueue = { add: jest.fn().mockReturnValue({ catch: jest.fn() }) };
+    const collaborationGateway = {
+      handleYjsEvent: jest.fn(async (_evt: string, _name: string, payload: any) => {
+        yjsPayload = payload;
+      }),
+    };
+
+    const service = new PageService(
+      pageRepo as any,
+      {} as any, // pagePermissionRepo
+      {} as any, // attachmentRepo
+      {} as any, // db
+      {} as any, // storageService
+      {} as any, // attachmentQueue
+      {} as any, // aiQueue
+      generalQueue as any,
+      {} as any, // eventEmitter
+      collaborationGateway as any,
+      {} as any, // watcherService
+      {} as any, // transclusionService
+    );
+    // Isolate the canonicalize BINDING: return the raw fixture (a deep clone so
+    // canonicalize never mutates the caller's object) instead of running the
+    // real markdown/HTML/JSON parse + schema validation.
+    jest
+      .spyOn(service as any, 'parseProsemirrorContent')
+      .mockImplementation(async (content: any) => structuredClone(content));
+    jest.spyOn(service as any, 'nextPagePosition').mockResolvedValue('a0');
+
+    return { service, getInsertedContent: () => insertedContent, getYjsPayload: () => yjsPayload };
+  }
+
+  it('createPage (full write) canonicalizes footnotes into reference order', async () => {
+    const { service, getInsertedContent } = makeService();
+    await service.create('user-id', 'workspace-id', {
+      spaceId: 'space-id',
+      content: outOfOrderFull(),
+      format: 'json',
+    } as any);
+    // Definitions reordered to reference order [b, a].
+    expect(listDefIds(getInsertedContent())).toEqual(['b', 'a']);
+  });
+
+  it("updatePageContent operation 'replace' canonicalizes footnotes", async () => {
+    const { service, getYjsPayload } = makeService();
+    await service.updatePageContent(
+      'page-id',
+      outOfOrderFull(),
+      'replace' as any,
+      'json' as any,
+      { id: 'user-id' } as any,
+    );
+    expect(getYjsPayload().operation).toBe('replace');
+    expect(listDefIds(getYjsPayload().prosemirrorJson)).toEqual(['b', 'a']);
+  });
+
+  it("append of a definition-only fragment is NOT canonicalized (footnote preserved, not dropped)", async () => {
+    const { service, getYjsPayload } = makeService();
+    await service.updatePageContent(
+      'page-id',
+      defOnlyFragment(),
+      'append' as any,
+      'json' as any,
+      { id: 'user-id' } as any,
+    );
+    // Canonicalizing a reference-less fragment would DROP the whole list; the
+    // fragment must pass through untouched so the merge keeps the definition.
+    expect(getYjsPayload().operation).toBe('append');
+    expect(hasFootnotesList(getYjsPayload().prosemirrorJson)).toBe(true);
+    expect(listDefIds(getYjsPayload().prosemirrorJson)).toEqual(['a']);
+  });
+
+  it('prepend of a reference-reuse fragment is NOT canonicalized (no synthesized garbage list)', async () => {
+    const { service, getYjsPayload } = makeService();
+    await service.updatePageContent(
+      'page-id',
+      refReuseFragment(),
+      'prepend' as any,
+      'json' as any,
+      { id: 'user-id' } as any,
+    );
+    // Canonicalizing would synthesize a bogus empty footnotesList for the reused
+    // reference; the fragment must pass through with no list at all.
+    expect(getYjsPayload().operation).toBe('prepend');
+    expect(hasFootnotesList(getYjsPayload().prosemirrorJson)).toBe(false);
+  });
+});

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

@@ -52,7 +52,7 @@ import {
   INTERNAL_LINK_REGEX,
   extractPageSlugId,
 } from '../../../integrations/export/utils';
-import { markdownToHtml } from '@docmost/editor-ext';
+import { markdownToHtml, canonicalizeFootnotes } from '@docmost/editor-ext';
 import { WatcherService } from '../../watcher/watcher.service';
 import { sql } from 'kysely';
 import { TransclusionService } from '../transclusion/transclusion.service';
@@ -160,9 +160,14 @@ export class PageService {
     let ydoc = undefined;
 
     if (createPageDto?.content && createPageDto?.format) {
-      const prosemirrorJson = await this.parseProsemirrorContent(
-        createPageDto.content,
-        createPageDto.format,
+      // createPage always writes a FULL document, so canonicalize footnotes to
+      // the editor's invariant before persisting (issue #228). Pure + idempotent
+      // + shape-safe: a doc with no footnotes is returned unchanged.
+      const prosemirrorJson = canonicalizeFootnotes(
+        await this.parseProsemirrorContent(
+          createPageDto.content,
+          createPageDto.format,
+        ),
       );
 
       content = prosemirrorJson;
@@ -343,7 +348,17 @@ export class PageService {
     format: ContentFormat,
     user: User,
   ): Promise<void> {
-    const prosemirrorJson = await this.parseProsemirrorContent(content, format);
+    let prosemirrorJson = await this.parseProsemirrorContent(content, format);
+
+    // Canonicalize footnotes ONLY for a full-document write ('replace'). For an
+    // append/prepend FRAGMENT, canonicalizing is semantically wrong (it would
+    // drop a definition-only fragment's list, or synthesize a duplicate empty
+    // definition for a fragment reusing an existing id) — the fragment merges
+    // into the live doc where the editor's footnoteSyncPlugin keeps the invariant
+    // (issue #228, must-fix #1).
+    if (operation === 'replace') {
+      prosemirrorJson = canonicalizeFootnotes(prosemirrorJson);
+    }
 
     const documentName = `page.${pageId}`;
     await this.collaborationGateway.handleYjsEvent(
@@ -1301,6 +1316,24 @@ export class PageService {
       }
     }
 
+    // NOTE: footnote canonicalization is intentionally NOT done here. This
+    // method serves BOTH full writes (createPage / updatePageContent with
+    // operation 'replace') AND fragment writes (append / prepend). Canonicalizing
+    // a FRAGMENT is semantically wrong — e.g. a definition-only fragment has no
+    // references, so the canonicalizer would drop its whole footnotesList (lost
+    // footnotes), and a fragment reusing an existing id would synthesize an empty
+    // duplicate definition. The canonicalizer therefore runs only at the
+    // FULL-DOCUMENT callers (createPage, and updatePageContent for 'replace'),
+    // never on a fragment (issue #228, must-fix #1).
+    // (Future consolidation, architecture B: the import services persist via a
+    // different path; folding all of these into one "prepare JSON for persist"
+    // helper would centralize the canonicalize call — left as follow-up.)
+    //
+    // ENFORCEMENT RULE (#228): any NEW FULL-document persist path MUST call
+    // `canonicalizeFootnotes(json)` before writing (see createPage and
+    // updatePageContent 'replace'); append/prepend FRAGMENT writes MUST NOT (it
+    // would drop or duplicate footnotes — that is exactly why this is per-call-site
+    // rather than a single wrapper here).
     try {
       jsonToNode(prosemirrorJson);
     } catch (err) {

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

@@ -1,4 +1,5 @@
 import { BadRequestException, ConflictException } from '@nestjs/common';
+import { NoResultError } from 'kysely';
 import { ShareAliasService } from './share-alias.service';
 
 /**
@@ -7,13 +8,18 @@ import { ShareAliasService } from './share-alias.service';
  * request-time readable-target resolution (which re-runs the share boundary).
  */
 describe('ShareAliasService', () => {
+  // Sentinel handed to repo calls so tests can assert they ran inside the tx.
+  const trx = { __trx: true };
+
   function makeService() {
     const shareAliasRepo = {
       findByAliasAndWorkspace: jest.fn(),
       findByPageId: jest.fn(),
       findById: jest.fn(),
       insert: jest.fn(),
+      updateAlias: jest.fn(),
       updatePageId: jest.fn(),
+      deleteOthersForPage: jest.fn(),
       delete: jest.fn(),
     };
     const pageRepo = { findById: jest.fn() };
@@ -21,12 +27,19 @@ describe('ShareAliasService', () => {
       resolveReadableSharePage: jest.fn(),
       isSharingAllowed: jest.fn(),
     };
+    // Fake kysely db: only .transaction().execute(cb) is used by setAlias.
+    const db = {
+      transaction: jest.fn(() => ({
+        execute: jest.fn(async (cb: any) => cb(trx)),
+      })),
+    };
     const service = new ShareAliasService(
       shareAliasRepo as any,
       pageRepo as any,
       shareService as any,
+      db as any,
     );
-    return { service, shareAliasRepo, pageRepo, shareService };
+    return { service, shareAliasRepo, pageRepo, shareService, db };
   }
 
   describe('setAlias', () => {
@@ -43,9 +56,10 @@ describe('ShareAliasService', () => {
       expect(shareAliasRepo.findByAliasAndWorkspace).not.toHaveBeenCalled();
     });
 
-    it('normalizes then inserts a brand-new alias', async () => {
+    it('normalizes then inserts a brand-new alias (page has none yet)', async () => {
       const { service, shareAliasRepo } = makeService();
       shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
+      shareAliasRepo.findByPageId.mockResolvedValue(undefined);
       shareAliasRepo.insert.mockResolvedValue({ id: 'a-1', alias: 'my-page' });
 
       const res = await service.setAlias({
@@ -58,17 +72,70 @@ describe('ShareAliasService', () => {
       expect(shareAliasRepo.findByAliasAndWorkspace).toHaveBeenCalledWith(
         'my-page',
         'ws-1',
+        trx,
+      );
+      expect(shareAliasRepo.insert).toHaveBeenCalledWith(
+        {
+          workspaceId: 'ws-1',
+          alias: 'my-page',
+          pageId: 'p-1',
+          creatorId: 'u-1',
+        },
+        trx,
+      );
+      expect(shareAliasRepo.updateAlias).not.toHaveBeenCalled();
+      // self-heal still runs, keeping just the inserted row
+      expect(shareAliasRepo.deleteOthersForPage).toHaveBeenCalledWith(
+        'p-1',
+        'a-1',
+        'ws-1',
+        trx,
       );
-      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 () => {
+    it('renames the existing row in place when editing to a free name (te -> ted)', async () => {
+      const { service, shareAliasRepo } = makeService();
+      // The new slug is free...
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
+      // ...but the page already owns an alias named `te`.
+      shareAliasRepo.findByPageId.mockResolvedValue({
+        id: 'a-1',
+        alias: 'te',
+        pageId: 'p-1',
+      });
+      shareAliasRepo.updateAlias.mockResolvedValue({
+        id: 'a-1',
+        alias: 'ted',
+        pageId: 'p-1',
+      });
+
+      const res = await service.setAlias({
+        workspaceId: 'ws-1',
+        pageId: 'p-1',
+        creatorId: 'u-1',
+        alias: 'ted',
+      });
+
+      // RENAME, not INSERT a second row.
+      expect(shareAliasRepo.insert).not.toHaveBeenCalled();
+      expect(shareAliasRepo.updateAlias).toHaveBeenCalledWith(
+        'a-1',
+        'ted',
+        'ws-1',
+        trx,
+      );
+      // ...and any other row for the page is reaped, so `te` cannot survive.
+      expect(shareAliasRepo.deleteOthersForPage).toHaveBeenCalledWith(
+        'p-1',
+        'a-1',
+        'ws-1',
+        trx,
+      );
+      expect(res).toMatchObject({ id: 'a-1', alias: 'ted' });
+    });
+
+    it('is a no-op when the alias already points at the same page (and self-heals)', async () => {
       const { service, shareAliasRepo } = makeService();
       const existing = { id: 'a-1', alias: 'foo', pageId: 'p-1' };
       shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(existing);
@@ -82,7 +149,45 @@ describe('ShareAliasService', () => {
 
       expect(res).toBe(existing);
       expect(shareAliasRepo.insert).not.toHaveBeenCalled();
+      expect(shareAliasRepo.updateAlias).not.toHaveBeenCalled();
       expect(shareAliasRepo.updatePageId).not.toHaveBeenCalled();
+      // self-heal reaps any legacy duplicate rows for the page
+      expect(shareAliasRepo.deleteOthersForPage).toHaveBeenCalledWith(
+        'p-1',
+        'a-1',
+        'ws-1',
+        trx,
+      );
+    });
+
+    it('self-heals a page with pre-existing duplicate rows down to one', async () => {
+      const { service, shareAliasRepo } = makeService();
+      // Name free; the page already has a (legacy) alias row we rename.
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
+      shareAliasRepo.findByPageId.mockResolvedValue({
+        id: 'a-keep',
+        alias: 'old',
+        pageId: 'p-1',
+      });
+      shareAliasRepo.updateAlias.mockResolvedValue({
+        id: 'a-keep',
+        alias: 'new',
+        pageId: 'p-1',
+      });
+
+      await service.setAlias({
+        workspaceId: 'ws-1',
+        pageId: 'p-1',
+        creatorId: 'u-1',
+        alias: 'new',
+      });
+
+      expect(shareAliasRepo.deleteOthersForPage).toHaveBeenCalledWith(
+        'p-1',
+        'a-keep',
+        'ws-1',
+        trx,
+      );
     });
 
     it('throws 409 with current target when name is taken and not confirmed', async () => {
@@ -134,15 +239,190 @@ describe('ShareAliasService', () => {
         'a-1',
         'p-1',
         'ws-1',
+        trx,
       );
+      // ORDER MATTERS: the target page's existing alias row(s) are reaped BEFORE
+      // the retarget, so the non-deferrable (workspace_id, page_id) index never
+      // sees two rows for the page mid-statement. There is no trailing self-heal.
+      expect(shareAliasRepo.deleteOthersForPage).toHaveBeenCalledWith(
+        'p-1',
+        'a-1',
+        'ws-1',
+        trx,
+      );
+      expect(shareAliasRepo.deleteOthersForPage).toHaveBeenCalledTimes(1);
+      const deleteOrder =
+        shareAliasRepo.deleteOthersForPage.mock.invocationCallOrder[0];
+      const updateOrder =
+        shareAliasRepo.updatePageId.mock.invocationCallOrder[0];
+      expect(deleteOrder).toBeLessThan(updateOrder);
       expect(res).toMatchObject({ pageId: 'p-1' });
     });
 
-    it('maps a unique-violation race to 409', async () => {
+    it('maps a unique-violation race (no constraint info) to 409 "Alias already taken"', async () => {
       const { service, shareAliasRepo } = makeService();
       shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
       shareAliasRepo.insert.mockRejectedValue({ code: '23505' });
 
+      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({
+          message: 'Alias already taken',
+        });
+      }
+    });
+
+    it('maps the (workspace_id, alias) index violation to "Alias already taken"', async () => {
+      const { service, shareAliasRepo } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
+      // postgres@3.x driver exposes the index name as `constraint_name`.
+      shareAliasRepo.insert.mockRejectedValue({
+        code: '23505',
+        constraint_name: 'share_aliases_workspace_id_alias_unique',
+      });
+
+      try {
+        await service.setAlias({
+          workspaceId: 'ws-1',
+          pageId: 'p-1',
+          creatorId: 'u-1',
+          alias: 'foo',
+        });
+        fail('expected ConflictException');
+      } catch (err) {
+        expect((err as ConflictException).getResponse()).toMatchObject({
+          message: 'Alias already taken',
+        });
+      }
+    });
+
+    it('maps the (workspace_id, page_id) index violation to a DISTINCT page-race outcome', async () => {
+      const { service, shareAliasRepo } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
+      shareAliasRepo.insert.mockRejectedValue({
+        code: '23505',
+        constraint_name: 'share_aliases_workspace_id_page_id_unique',
+      });
+
+      try {
+        await service.setAlias({
+          workspaceId: 'ws-1',
+          pageId: 'p-1',
+          creatorId: 'u-1',
+          alias: 'foo',
+        });
+        fail('expected ConflictException');
+      } catch (err) {
+        expect(err).toBeInstanceOf(ConflictException);
+        // NOT the misleading "Alias already taken" — a separate, page-scoped code.
+        expect((err as ConflictException).getResponse()).toMatchObject({
+          code: 'ALIAS_PAGE_RACE',
+        });
+        expect((err as ConflictException).getResponse()).not.toMatchObject({
+          message: 'Alias already taken',
+        });
+      }
+    });
+
+    it('reads the index name from `.constraint` when `.constraint_name` is absent', async () => {
+      const { service, shareAliasRepo } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
+      // Fallback path for non-postgres@3.x drivers.
+      shareAliasRepo.insert.mockRejectedValue({
+        code: '23505',
+        constraint: 'share_aliases_workspace_id_page_id_unique',
+      });
+
+      try {
+        await service.setAlias({
+          workspaceId: 'ws-1',
+          pageId: 'p-1',
+          creatorId: 'u-1',
+          alias: 'foo',
+        });
+        fail('expected ConflictException');
+      } catch (err) {
+        expect((err as ConflictException).getResponse()).toMatchObject({
+          code: 'ALIAS_PAGE_RACE',
+        });
+      }
+    });
+
+    it('maps a concurrent-delete race in the SWAP branch to a retryable 409 (not a 200-without-alias)', async () => {
+      const { service, shareAliasRepo } = makeService();
+      // Name points at another page; reassign confirmed -> swap branch.
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
+        id: 'a-1',
+        alias: 'foo',
+        pageId: 'p-other',
+      });
+      // A concurrent removeAlias deleted the row between read and UPDATE, so the
+      // repo's executeTakeFirstOrThrow finds 0 rows and throws NoResultError.
+      shareAliasRepo.updatePageId.mockRejectedValue(
+        new NoResultError({} as any),
+      );
+
+      try {
+        await service.setAlias({
+          workspaceId: 'ws-1',
+          pageId: 'p-1',
+          creatorId: 'u-1',
+          alias: 'foo',
+          confirmReassign: true,
+        });
+        fail('expected ConflictException');
+      } catch (err) {
+        // Crucially NOT a resolved 200 carrying `undefined` as the alias.
+        expect(err).toBeInstanceOf(ConflictException);
+        expect((err as ConflictException).getResponse()).toMatchObject({
+          code: 'ALIAS_PAGE_RACE',
+        });
+      }
+    });
+
+    it('maps a concurrent-delete race in the RENAME branch to a retryable 409 (not a generic 400)', async () => {
+      const { service, shareAliasRepo } = makeService();
+      // New slug is free, but the page already owns an alias we rename in place.
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
+      shareAliasRepo.findByPageId.mockResolvedValue({
+        id: 'a-1',
+        alias: 'te',
+        pageId: 'p-1',
+      });
+      // The row vanished before the UPDATE; repo throws NoResultError rather
+      // than returning undefined (which would dereference undefined.id -> 400).
+      shareAliasRepo.updateAlias.mockRejectedValue(new NoResultError({} as any));
+
+      try {
+        await service.setAlias({
+          workspaceId: 'ws-1',
+          pageId: 'p-1',
+          creatorId: 'u-1',
+          alias: 'ted',
+        });
+        fail('expected ConflictException');
+      } catch (err) {
+        expect(err).toBeInstanceOf(ConflictException);
+        expect(err).not.toBeInstanceOf(BadRequestException);
+        expect((err as ConflictException).getResponse()).toMatchObject({
+          code: 'ALIAS_PAGE_RACE',
+        });
+      }
+    });
+
+    it('maps a non-unique-violation db error to BadRequest (Failed to set alias)', async () => {
+      const { service, shareAliasRepo } = makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue(undefined);
+      shareAliasRepo.insert.mockRejectedValue({ code: '08006' }); // connection error
+
       await expect(
         service.setAlias({
           workspaceId: 'ws-1',
@@ -150,7 +430,7 @@ describe('ShareAliasService', () => {
           creatorId: 'u-1',
           alias: 'foo',
         }),
-      ).rejects.toBeInstanceOf(ConflictException);
+      ).rejects.toBeInstanceOf(BadRequestException);
     });
   });
 

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

@@ -9,9 +9,24 @@ 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';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB } from '@docmost/db/types/kysely.types';
+import {
+  executeTx,
+  isUniqueViolation,
+  violatedConstraint,
+} from '@docmost/db/utils';
+import { NoResultError } from 'kysely';
 
-/** Postgres unique_violation; the (workspace_id, alias) constraint races here. */
-const PG_UNIQUE_VIOLATION = '23505';
+/**
+ * Unique index name from the share_aliases migrations whose violation we map to
+ * a DISTINCT, non-misleading outcome:
+ *   - PAGE_ID: partial `(workspace_id, page_id) WHERE page_id IS NOT NULL`
+ *             -> a concurrent writer already gave THIS page an alias.
+ * The `(workspace_id, alias)` index (the vanity NAME being taken) needs no
+ * constant: it is the default "Alias already taken" mapping.
+ */
+const UNIQUE_PAGE_ID_INDEX = 'share_aliases_workspace_id_page_id_unique';
 
 export interface ResolvedAliasTarget {
   share: NonNullable<
@@ -28,16 +43,30 @@ export class ShareAliasService {
     private readonly shareAliasRepo: ShareAliasRepo,
     private readonly pageRepo: PageRepo,
     private readonly shareService: ShareService,
+    @InjectKysely() private readonly db: KyselyDB,
   ) {}
 
   /**
-   * 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).
+   * Create, RENAME or retarget a page's vanity alias. INVARIANT: a page has
+   * EXACTLY ONE custom address. The alias name is workspace-scoped:
+   *   - name free, page has no alias yet -> INSERT a new pointer
+   *   - name free, page already has one  -> RENAME that row in place (the slug
+   *     edit, e.g. `te` -> `ted`); we never spawn a second row, so no orphan
+   *     `/l/<old>` link survives
+   *   - name already points at pageId    -> no-op (idempotent)
+   *   - name points at ANOTHER page      -> 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 cache).
+   *
+   * To keep the invariant self-healing we DELETE every other alias row still
+   * pointing at this page (a legacy duplicate, or the target page's own former
+   * alias during a swap). The whole thing runs in one transaction. Because the
+   * `(workspace_id, page_id)` unique index is NON-deferrable (checked at the end
+   * of each statement), the swap branch DELETEs the target page's existing row
+   * BEFORE retargeting, so the page is never transiently carried by two rows;
+   * the other branches self-heal AFTER their write. Either way the page never
+   * ends a statement with duplicate rows.
    *
    * Caller is responsible for authorizing the page (edit rights + public
    * readability); this method owns only the alias-name semantics.
@@ -57,48 +86,128 @@ export class ShareAliasService {
       );
     }
 
-    const existing = await this.shareAliasRepo.findByAliasAndWorkspace(
-      alias,
-      workspaceId,
-    );
-
-    if (!existing) {
-      try {
-        return await this.shareAliasRepo.insert({
-          workspaceId,
+    try {
+      return await executeTx(this.db, async (trx) => {
+        const byName = await this.shareAliasRepo.findByAliasAndWorkspace(
           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' });
+          workspaceId,
+          trx,
+        );
+
+        // The name is occupied by a DIFFERENT (or dangling) target page.
+        if (byName && byName.pageId !== pageId) {
+          if (!confirmReassign) {
+            const currentPage = byName.pageId
+              ? await this.pageRepo.findById(byName.pageId)
+              : null;
+            throw new ConflictException({
+              message: 'Alias already in use',
+              code: 'ALIAS_REASSIGN_REQUIRED',
+              currentPageId: byName.pageId,
+              currentPageTitle: currentPage?.title ?? null,
+            });
+          }
+          // Confirmed swap. ORDER MATTERS: the partial unique index on
+          // `(workspace_id, page_id)` is NON-deferrable, so it is checked at the
+          // end of EVERY statement. If we retargeted `byName` onto `pageId`
+          // first while `pageId` still had its OWN alias row, there would
+          // momentarily be two rows with this page_id -> immediate 23505 and a
+          // rolled-back tx (a misleading "Alias already taken"). So we FIRST drop
+          // the target page's existing alias row(s), THEN retarget. `byName.id`
+          // still points at its old page here, so excluding it via `keepId` is
+          // harmless; after the retarget it is the page's only row, so no
+          // trailing self-heal is needed.
+          await this.shareAliasRepo.deleteOthersForPage(
+            pageId,
+            byName.id,
+            workspaceId,
+            trx,
+          );
+          return await this.shareAliasRepo.updatePageId(
+            byName.id,
+            pageId,
+            workspaceId,
+            trx,
+          );
         }
-        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;
-    }
+        // The name is FREE, or already points at THIS page. Ensure the page has
+        // a single row carrying this name: rename its current one, or insert.
+        const current =
+          byName ??
+          (await this.shareAliasRepo.findByPageId(pageId, workspaceId, trx));
 
-    // 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,
+        let row: ShareAlias;
+        if (current) {
+          row =
+            current.alias === alias
+              ? current // same-name no-op
+              : await this.shareAliasRepo.updateAlias(
+                  current.id,
+                  alias,
+                  workspaceId,
+                  trx,
+                );
+        } else {
+          row = await this.shareAliasRepo.insert(
+            { workspaceId, alias, pageId, creatorId },
+            trx,
+          );
+        }
+
+        // Self-heal: a page keeps EXACTLY ONE custom address.
+        await this.shareAliasRepo.deleteOthersForPage(
+          pageId,
+          row.id,
+          workspaceId,
+          trx,
+        );
+        return row;
       });
+    } catch (err: any) {
+      if (
+        err instanceof ConflictException ||
+        err instanceof BadRequestException
+      ) {
+        throw err;
+      }
+      // The row we read was deleted (concurrent `removeAlias`) before our UPDATE
+      // matched it, so `executeTakeFirstOrThrow` found no row. Surface a
+      // retryable conflict instead of a 200-without-alias (swap branch) or a
+      // generic 400 from dereferencing `undefined.id` (rename branch).
+      if (err instanceof NoResultError) {
+        this.logger.warn(
+          'share alias update matched no row (concurrent-delete race)',
+        );
+        throw new ConflictException({
+          message: 'The address changed concurrently, please retry',
+          code: 'ALIAS_PAGE_RACE',
+        });
+      }
+      // A unique index fired. Which one decides the message — always log the
+      // constraint so the race is diagnosable.
+      if (isUniqueViolation(err)) {
+        const constraint = violatedConstraint(err);
+        this.logger.warn(
+          `share alias unique violation on ${constraint ?? '<unknown>'}`,
+        );
+        // `(workspace_id, page_id)`: a concurrent request already gave this page
+        // an alias. The page still has exactly one custom address (the racing
+        // writer's), so this is not a user-facing name clash — surface a
+        // distinct, non-misleading message instead of "Alias already taken".
+        if (constraint === UNIQUE_PAGE_ID_INDEX) {
+          throw new ConflictException({
+            message: 'This page is being given an address by another request',
+            code: 'ALIAS_PAGE_RACE',
+          });
+        }
+        // `(workspace_id, alias)` or any other/unknown unique index: treat as
+        // the vanity name being claimed first.
+        throw new ConflictException({ message: 'Alias already taken' });
+      }
+      this.logger.error(err);
+      throw new BadRequestException('Failed to set alias');
     }
-
-    return this.shareAliasRepo.updatePageId(existing.id, pageId, workspaceId);
   }
 
   /** Free a vanity name (no history kept). */

apps/server/src/core/share/share-get-shared-page-binding.spec.ts

@@ -0,0 +1,161 @@
+import { NotFoundException } from '@nestjs/common';
+import { ShareService } from './share.service';
+
+/**
+ * Regression for issue #218: public-share content must be bound to the requested
+ * shareId. `getSharedPage` resolves the page off its slug, but when the caller
+ * supplies a shareId it must be reachable THROUGH that exact share — a forged or
+ * mismatched shareId 404s instead of rendering the page off its slug alone. A
+ * request with no shareId keeps the legacy slug-capability behavior.
+ */
+const WS = 'ws-1';
+const PAGE_ID = 'page-uuid-1';
+const OWN_SHARE_ID = 'share-own';
+const OWN_SHARE_KEY = 'ownkey';
+
+function buildService(over: {
+  resolvedShare?: any;
+  ancestorShare?: any; // returned by shareRepo.findById(requestedShareId)
+  ancestorFound?: boolean; // getShareAncestorPage result
+} = {}) {
+  const resolvedShare = over.resolvedShare ?? {
+    id: OWN_SHARE_ID,
+    key: OWN_SHARE_KEY,
+    includeSubPages: false,
+    spaceId: 'space-1',
+    workspaceId: WS,
+  };
+  const page = { id: PAGE_ID, deletedAt: null, content: { type: 'doc' } };
+
+  const shareRepo = {
+    findById: jest.fn(async () => over.ancestorShare ?? null),
+  };
+
+  const service = new ShareService(
+    shareRepo as any,
+    {} as any, // pageRepo (resolveReadableSharePage is spied)
+    {} as any, // pagePermissionRepo
+    {} as any, // db
+    {} as any, // tokenService
+    {} as any, // transclusionService
+    {} as any, // workspaceRepo
+  );
+
+  jest
+    .spyOn(service, 'resolveReadableSharePage')
+    .mockResolvedValue({ share: resolvedShare, page } as any);
+  jest
+    .spyOn(service, 'updatePublicAttachments')
+    .mockResolvedValue(page.content as any);
+  jest
+    .spyOn(service, 'getShareAncestorPage')
+    .mockResolvedValue(over.ancestorFound ? { id: 'anc' } : null);
+
+  return { service, shareRepo, page, resolvedShare };
+}
+
+describe('ShareService.getSharedPage — share binding (#218)', () => {
+  it('returns the page when no shareId is supplied (legacy slug path)', async () => {
+    const { service } = buildService();
+    const out = await service.getSharedPage({ pageId: PAGE_ID } as any, WS);
+    expect(out.page.id).toBe(PAGE_ID);
+  });
+
+  it('returns the page when the shareId matches the resolved share key', async () => {
+    const { service } = buildService();
+    const out = await service.getSharedPage(
+      { pageId: PAGE_ID, shareId: OWN_SHARE_KEY } as any,
+      WS,
+    );
+    expect(out.page.id).toBe(PAGE_ID);
+  });
+
+  it('returns the page when the shareId matches the resolved share id (case-insensitive key)', async () => {
+    const { service } = buildService();
+    const out = await service.getSharedPage(
+      { pageId: PAGE_ID, shareId: OWN_SHARE_KEY.toUpperCase() } as any,
+      WS,
+    );
+    expect(out.page.id).toBe(PAGE_ID);
+  });
+
+  it('404s for a forged shareId that resolves to nothing', async () => {
+    const { service } = buildService({ ancestorShare: null });
+    await expect(
+      service.getSharedPage(
+        { pageId: PAGE_ID, shareId: 'doesnotexist99' } as any,
+        WS,
+      ),
+    ).rejects.toBeInstanceOf(NotFoundException);
+  });
+
+  it('allows an includeSubPages ANCESTOR share that contains the page', async () => {
+    const { service } = buildService({
+      ancestorShare: {
+        id: 'ancestor-share',
+        pageId: 'ancestor-page',
+        includeSubPages: true,
+        workspaceId: WS,
+      },
+      ancestorFound: true,
+    });
+    const out = await service.getSharedPage(
+      { pageId: PAGE_ID, shareId: 'ancestorkey' } as any,
+      WS,
+    );
+    expect(out.page.id).toBe(PAGE_ID);
+  });
+
+  it('404s for a different share WITHOUT includeSubPages', async () => {
+    const { service } = buildService({
+      ancestorShare: {
+        id: 'other-share',
+        pageId: 'other-page',
+        includeSubPages: false,
+        workspaceId: WS,
+      },
+    });
+    await expect(
+      service.getSharedPage(
+        { pageId: PAGE_ID, shareId: 'otherkey' } as any,
+        WS,
+      ),
+    ).rejects.toBeInstanceOf(NotFoundException);
+  });
+
+  it('404s for an includeSubPages share that does NOT contain the page', async () => {
+    const { service } = buildService({
+      ancestorShare: {
+        id: 'unrelated-share',
+        pageId: 'unrelated-page',
+        includeSubPages: true,
+        workspaceId: WS,
+      },
+      ancestorFound: false,
+    });
+    await expect(
+      service.getSharedPage(
+        { pageId: PAGE_ID, shareId: 'unrelatedkey' } as any,
+        WS,
+      ),
+    ).rejects.toBeInstanceOf(NotFoundException);
+  });
+
+  it('404s for a share in a different workspace', async () => {
+    const { service } = buildService({
+      ancestorShare: {
+        id: 'foreign-share',
+        pageId: 'foreign-page',
+        includeSubPages: true,
+        workspaceId: 'other-ws',
+      },
+      ancestorFound: true,
+    });
+    await expect(
+      service.getSharedPage(
+        { pageId: PAGE_ID, shareId: 'foreignkey' } as any,
+        WS,
+      ),
+    ).rejects.toBeInstanceOf(NotFoundException);
+  });
+});

apps/server/src/core/share/share-public-payload.ts

@@ -0,0 +1,69 @@
+import { Page } from '@docmost/db/types/entity.types';
+
+/**
+ * The EXACT shape returned to anonymous public-share viewers by the
+ * `/shares/page-info` route — the only unauthenticated path that serializes the
+ * full {page, share} records. This is a security boundary (#218): the raw rows
+ * carry internal metadata — creatorId/lastUpdatedById/contributorIds,
+ * spaceId/workspaceId, AI/source bookkeeping, lock/template flags,
+ * parent/position and raw timestamps — none of which may leak to an
+ * unauthenticated viewer. Keeping the allowlist as an explicit TYPE plus a
+ * single mapper means a new leaking field cannot be returned without also
+ * widening this contract (and tripping its key-test in share.controller.spec.ts).
+ */
+export interface PublicSharePayload {
+  page: {
+    id: string;
+    slugId: string;
+    title: string | null;
+    icon: string | null;
+    content: unknown;
+  };
+  share: {
+    id: string;
+    key: string;
+    includeSubPages: boolean | null;
+    searchIndexing: boolean | null;
+    level: number;
+    sharedPage: unknown;
+  };
+}
+
+/**
+ * The subset of the resolved share read by the public payload. Declared
+ * structurally so the richer getShareForPage result (which adds `level` and
+ * `sharedPage` on top of the base Shares row) passes without a cast.
+ */
+interface PublicShareSource {
+  id: string;
+  key: string;
+  includeSubPages: boolean | null;
+  searchIndexing: boolean | null;
+  // `level` is derived via a SQL literal in getShareForPage, so it surfaces as
+  // `unknown` in the resolved share; it is a number at runtime.
+  level: unknown;
+  sharedPage: unknown;
+}
+
+export function toPublicSharePayload(
+  page: Page,
+  share: PublicShareSource,
+): PublicSharePayload {
+  return {
+    page: {
+      id: page.id,
+      slugId: page.slugId,
+      title: page.title,
+      icon: page.icon,
+      content: page.content,
+    },
+    share: {
+      id: share.id,
+      key: share.key,
+      includeSubPages: share.includeSubPages,
+      searchIndexing: share.searchIndexing,
+      level: share.level as number,
+      sharedPage: share.sharedPage,
+    },
+  };
+}

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

@@ -0,0 +1,190 @@
+import { ShareController } from './share.controller';
+import {
+  PublicSharePayload,
+  toPublicSharePayload,
+} from './share-public-payload';
+
+// The `/shares/page-info` route is the ONLY anonymous path that serializes the
+// full {page, share} records. Trimming the response to an explicit allowlist is
+// a security control (#218): a regression that returns `...shareData` (or adds a
+// new field to the allowlist) must fail loudly. These tests lock the exact key
+// set returned to anonymous viewers so internal metadata can never silently leak.
+
+const PAGE_KEYS = ['id', 'slugId', 'title', 'icon', 'content'].sort();
+const SHARE_KEYS = [
+  'id',
+  'key',
+  'includeSubPages',
+  'searchIndexing',
+  'level',
+  'sharedPage',
+].sort();
+
+// A page row carrying internal metadata that MUST NOT reach anonymous viewers.
+function internalPage() {
+  return {
+    id: 'page-1',
+    slugId: 'slug-1',
+    title: 'Public Title',
+    icon: '📄',
+    content: { type: 'doc', content: [] },
+    // --- leaky internals ---
+    creatorId: 'user-1',
+    lastUpdatedById: 'user-2',
+    contributorIds: ['user-1', 'user-2'],
+    spaceId: 'space-1',
+    workspaceId: 'ws-1',
+    parentPageId: 'parent-1',
+    position: 'aa',
+    isLocked: true,
+    isTemplate: false,
+    textContent: 'secret text content',
+    ydoc: Buffer.from('binary'),
+    createdAt: new Date('2020-01-01'),
+    updatedAt: new Date('2020-01-02'),
+    deletedAt: null,
+  } as any;
+}
+
+// A resolved share carrying internal metadata.
+function internalShare() {
+  return {
+    id: 'share-1',
+    key: 'share-key',
+    includeSubPages: false,
+    searchIndexing: true,
+    level: 0,
+    sharedPage: { id: 'page-1', slugId: 'slug-1', title: 'Public Title' },
+    // --- leaky internals ---
+    creatorId: 'user-1',
+    spaceId: 'space-1',
+    workspaceId: 'ws-1',
+    pageId: 'page-1',
+    createdAt: new Date('2020-01-01'),
+    updatedAt: new Date('2020-01-02'),
+    deletedAt: null,
+  } as any;
+}
+
+function buildController(over?: { aiAssistant?: boolean }) {
+  const shareService = {
+    // Deliberately returns the FULL internal records (as the real service does).
+    getSharedPage: jest.fn(async () => ({
+      page: internalPage(),
+      share: internalShare(),
+    })),
+    isSharingAllowed: jest.fn(async () => true),
+  };
+  const aiSettings = {
+    isPublicShareAssistantEnabled: jest.fn(
+      async () => over?.aiAssistant ?? false,
+    ),
+    resolvePublicShareAssistantName: jest.fn(async () => 'Assistant'),
+  };
+  const licenseCheckService = {
+    resolveFeatures: jest.fn(() => ({ tier: 'free' })),
+  };
+
+  const controller = new ShareController(
+    shareService as any,
+    {} as any, // shareRepo
+    {} as any, // pageRepo
+    {} as any, // pagePermissionRepo
+    {} as any, // pageAccessService
+    licenseCheckService as any,
+    aiSettings as any,
+    {} as any, // auditService
+  );
+
+  return { controller, shareService, aiSettings, licenseCheckService };
+}
+
+const workspace = {
+  id: 'ws-1',
+  licenseKey: null,
+  plan: 'free',
+} as any;
+
+describe('ShareController.getSharedPageInfo — public payload whitelist (#218)', () => {
+  it('returns EXACTLY the page allowlist keys (no leaked internals)', async () => {
+    const { controller } = buildController();
+
+    const res = await controller.getSharedPageInfo(
+      { pageId: 'page-1' } as any,
+      workspace,
+    );
+
+    expect(Object.keys(res.page).sort()).toEqual(PAGE_KEYS);
+    for (const leaked of [
+      'creatorId',
+      'lastUpdatedById',
+      'contributorIds',
+      'spaceId',
+      'workspaceId',
+      'parentPageId',
+      'position',
+      'textContent',
+      'ydoc',
+      'createdAt',
+      'updatedAt',
+      'deletedAt',
+    ]) {
+      expect((res.page as any)[leaked]).toBeUndefined();
+    }
+    // The serialized payload must not carry the secret text content either.
+    expect(JSON.stringify(res.page)).not.toContain('secret text content');
+  });
+
+  it('returns EXACTLY the share allowlist keys (no leaked internals)', async () => {
+    const { controller } = buildController();
+
+    const res = await controller.getSharedPageInfo(
+      { pageId: 'page-1' } as any,
+      workspace,
+    );
+
+    expect(Object.keys(res.share).sort()).toEqual(SHARE_KEYS);
+    for (const leaked of [
+      'creatorId',
+      'spaceId',
+      'workspaceId',
+      'pageId',
+      'createdAt',
+      'updatedAt',
+      'deletedAt',
+    ]) {
+      expect((res.share as any)[leaked]).toBeUndefined();
+    }
+  });
+
+  it('surfaces the public AI-assistant flags and license features alongside the trimmed payload', async () => {
+    const { controller } = buildController({ aiAssistant: true });
+
+    const res = await controller.getSharedPageInfo(
+      { pageId: 'page-1' } as any,
+      workspace,
+    );
+
+    expect(res.aiAssistant).toBe(true);
+    expect(res.aiAssistantName).toBe('Assistant');
+    expect(res.features).toEqual({ tier: 'free' });
+    // Top-level keys are limited to the trimmed payload + the public extras.
+    expect(Object.keys(res).sort()).toEqual(
+      ['page', 'share', 'aiAssistant', 'aiAssistantName', 'features'].sort(),
+    );
+  });
+});
+
+describe('toPublicSharePayload — key set is the contract', () => {
+  it('copies only the allowlisted page/share keys', () => {
+    const payload: PublicSharePayload = toPublicSharePayload(
+      internalPage(),
+      internalShare(),
+    );
+
+    expect(Object.keys(payload.page).sort()).toEqual(PAGE_KEYS);
+    expect(Object.keys(payload.share).sort()).toEqual(SHARE_KEYS);
+    expect(payload.page.id).toBe('page-1');
+    expect(payload.share.key).toBe('share-key');
+  });
+});

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

@@ -36,6 +36,7 @@ import {
   IAuditService,
 } from '../../integrations/audit/audit.service';
 import { AiSettingsService } from '../../integrations/ai/ai-settings.service';
+import { toPublicSharePayload } from './share-public-payload';
 
 @UseGuards(JwtAuthGuard)
 @Controller('shares')
@@ -93,8 +94,13 @@ export class ShareController {
       ? await this.aiSettings.resolvePublicShareAssistantName(workspace.id)
       : null;
 
+    // Trim the public payload to the explicit allowlist the anonymous renderer
+    // needs (#218); the PublicSharePayload type + mapper guarantee internal
+    // metadata can never leak to anonymous viewers (see share-public-payload.ts).
+    const { page, share } = shareData;
+
     return {
-      ...shareData,
+      ...toPublicSharePayload(page, share),
       aiAssistant,
       aiAssistantName,
       features: this.licenseCheckService.resolveFeatures(

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

@@ -189,9 +189,9 @@ export class ShareService {
   }
 
   async getSharedPage(dto: ShareInfoDto, workspaceId: string) {
-    // Resolve via the single canonical boundary. There is no independent
-    // requested shareId here (the share is resolved FROM the page), so no
-    // share-id match is performed.
+    // Resolve via the single canonical boundary. The share is resolved FROM the
+    // page (the request carries the page slug), so the boundary itself performs
+    // no share-id match here.
     const resolved = await this.resolveReadableSharePage(
       null,
       dto.pageId,
@@ -205,11 +205,85 @@ export class ShareService {
 
     const { share, page } = resolved;
 
+    // Bind content to the requested share (#218). When the caller supplies a
+    // shareId/key (the `/share/:shareId/p/:slug` route now forwards it), the
+    // page must be reachable THROUGH that exact share — a forged or mismatched
+    // shareId must 404 instead of rendering the page off its slug alone, and it
+    // must not be answerable with the page's real (canonical) share key. A
+    // request with no shareId keeps the legacy slug-capability behavior (the
+    // `/share/p/:slug` route + internal title look-ups); the slug nanoid stays
+    // the access secret there — an inherited Docmost design we don't widen.
+    // FUTURE: this ancestor-aware match could fold INTO resolveReadableSharePage
+    // (so the boundary's narrow `share.id === shareId` gate isn't effectively
+    // dead). Deferred — it widens the contract for the 3 other callers that pass
+    // no shareId (share-alias.controller, share-alias.service, share-seo.controller);
+    // the two ai-chat callers (public-share-chat.controller,
+    // public-share-chat-tools.service) already pass a real shareId. Kept here as
+    // a local post-check until that consolidation is worth the blast radius.
+    if (dto.shareId) {
+      const reachable = await this.isPageReachableThroughShare(
+        dto.shareId,
+        share,
+        page.id,
+        workspaceId,
+      );
+      if (!reachable) {
+        throw new NotFoundException('Shared page not found');
+      }
+    }
+
     page.content = await this.updatePublicAttachments(page);
 
     return { page, share };
   }
 
+  /**
+   * Does `requestedShareId` (a share id OR key) legitimately grant access to
+   * `pageId`? True when it names the page's own resolved share, or an ancestor
+   * share with `includeSubPages` that contains the page. Any other value
+   * (unknown key, wrong workspace, a sibling share that doesn't cover the page)
+   * is false, so a guessed slug paired with a forged shareId can't render.
+   */
+  private async isPageReachableThroughShare(
+    requestedShareId: string,
+    resolvedShare: NonNullable<
+      Awaited<ReturnType<ShareService['getShareForPage']>>
+    >,
+    pageId: string,
+    workspaceId: string,
+  ): Promise<boolean> {
+    // Fast path: the request names the page's own resolved share.
+    if (this.shareIdGrantsAccess(requestedShareId, resolvedShare)) {
+      return true;
+    }
+
+    // Otherwise it may name an includeSubPages ANCESTOR share: the page has its
+    // own closer share but is also served under the ancestor's public tree.
+    const requested = await this.shareRepo.findById(requestedShareId);
+    if (!requested || requested.workspaceId !== workspaceId) return false;
+    if (!requested.includeSubPages) return false;
+
+    const ancestor = await this.getShareAncestorPage(requested.pageId, pageId);
+    return !!ancestor;
+  }
+
+  /**
+   * Does the requested share id/key directly name `resolvedShare` — by id, or
+   * by key (case-insensitive)? This is the "names the page's OWN share" half of
+   * the access concept; ancestor includeSubPages shares are matched separately.
+   * Intentionally narrower than `resolveReadableSharePage`'s id-only gate, which
+   * keeps its own contract for the callers that pass a shareId there.
+   */
+  private shareIdGrantsAccess(
+    requestedShareId: string,
+    resolvedShare: { id: string; key?: string | null },
+  ): boolean {
+    return (
+      requestedShareId === resolvedShare.id ||
+      requestedShareId.toLowerCase() === resolvedShare.key?.toLowerCase()
+    );
+  }
+
   async getShareForPage(pageId: string, workspaceId: string) {
     // here we try to check if a page was shared directly or if it inherits the share from its closest shared ancestor
     const share = await this.db
@@ -351,7 +425,14 @@ export class ShareService {
         .limit(1)
         .executeTakeFirst();
     } catch (err) {
-      // empty
+      // Fail closed (return null -> caller 404s), but never silently: this is
+      // now a live public-share path (isPageReachableThroughShare), so a
+      // transient DB error here would otherwise turn a legitimate viewer of an
+      // includeSubPages descendant into a misleading "not found" with no trace.
+      this.logger.error(
+        `getShareAncestorPage failed (ancestorPageId=${ancestorPageId}, childPageId=${childPageId})`,
+        err instanceof Error ? err.stack : String(err),
+      );
     }
 
     return ancestor;

apps/server/src/database/listeners/page.listener.ts

@@ -21,6 +21,41 @@ export interface TreeNodeSnapshot {
   position: string;
   spaceId: string;
   parentPageId: string | null;
+  // Death-timer deadline carried so the `addTreeNode` broadcast shows the
+  // temporary-note clock marker immediately on every client (incl. the author,
+  // whose optimistic insert can lose the race to this broadcast). null/absent =>
+  // permanent.
+  temporaryExpiresAt?: Date | string | null;
+}
+
+/**
+ * Single canonical builder for a `TreeNodeSnapshot` from a page-like row. Both
+ * the `PAGE_CREATED` event enrichment (`page.repo.insertPage`) and the
+ * `addTreeNode` broadcast (`WsTreeService.broadcastPageCreated`) build this same
+ * snapshot; routing both through here keeps the optional `temporaryExpiresAt`
+ * (and the `?? null` normalisation that pins a permanent note to an explicit
+ * null) from silently drifting between the two literals.
+ */
+export function toTreeNodeSnapshot(page: {
+  id: string;
+  slugId: string;
+  title: string | null;
+  icon: string | null;
+  position: string;
+  spaceId: string;
+  parentPageId: string | null;
+  temporaryExpiresAt?: Date | string | null;
+}): TreeNodeSnapshot {
+  return {
+    id: page.id,
+    slugId: page.slugId,
+    title: page.title,
+    icon: page.icon,
+    position: page.position,
+    spaceId: page.spaceId,
+    parentPageId: page.parentPageId,
+    temporaryExpiresAt: page.temporaryExpiresAt ?? null,
+  };
 }
 
 export class PageEvent {

apps/server/src/database/migrations/20260626T150000-ai-agent-roles-catalog-source.ts

@@ -0,0 +1,19 @@
+import { type Kysely } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  // `source` links an imported role back to its catalog origin
+  // `{ slug, language, version }`. Nullable: null => a manually-created role
+  // (no catalog provenance). The version lets the admin UI offer an UPDATE when
+  // the catalog ships a newer revision of the same slug.
+  await db.schema
+    .alterTable('ai_agent_roles')
+    .addColumn('source', 'jsonb', (col) => col)
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .alterTable('ai_agent_roles')
+    .dropColumn('source')
+    .execute();
+}

apps/server/src/database/migrations/20260626T160000-ai-agent-roles-catalog-source-unique.ts

@@ -0,0 +1,31 @@
+import { type Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  // A catalog-imported role is uniquely identified within a workspace by its
+  // `source.slug` + `source.language` (a multilingual catalog: the `ru` variant
+  // of a slug installed as `en` is a SEPARATE install — hence both keys). The
+  // import path skips a slug+language already installed using an in-memory
+  // snapshot (installedKeys), but two CONCURRENT imports of the same bundle each
+  // read a stale snapshot and would both insert the same slug+language,
+  // duplicating the role. This partial unique index is the database-level
+  // backstop: the second insert gets a 23505 the service treats as
+  // "already installed" (skip), so the two imports converge on ONE role.
+  //
+  // Partial on `source IS NOT NULL` so MANUALLY-created roles (source NULL) are
+  // unconstrained — there can be many of those. Also partial on
+  // `deleted_at IS NULL` (like the existing name-unique index) so a soft-deleted
+  // role does not block re-importing the same slug+language later, matching the
+  // app's snapshot (listByWorkspace filters out soft-deleted rows).
+  await sql`
+    CREATE UNIQUE INDEX IF NOT EXISTS ai_agent_roles_workspace_source_unique
+    ON ai_agent_roles (workspace_id, (source ->> 'slug'), (source ->> 'language'))
+    WHERE source IS NOT NULL AND deleted_at IS NULL
+  `.execute(db);
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .dropIndex('ai_agent_roles_workspace_source_unique')
+    .ifExists()
+    .execute();
+}

apps/server/src/database/migrations/20260627T120000-share-aliases-one-per-page.ts

@@ -0,0 +1,48 @@
+import { type Kysely, sql } from 'kysely';
+
+/**
+ * Enforce "a page has EXACTLY ONE custom address" at the DB level. The original
+ * `share_aliases` table only had a unique index on `(workspace_id, alias)`, so a
+ * page could accumulate several alias rows (every slug edit used to INSERT a new
+ * one), leaving orphan `/l/<old>` links live forever and making the share
+ * modal's `findByPageId` lookup nondeterministic.
+ *
+ * We first dedup any pre-existing rows (keeping the NEWEST per page — the same
+ * "current" choice the read path now makes), then add a PARTIAL unique index on
+ * `(workspace_id, page_id)`. It is partial (`WHERE page_id IS NOT NULL`) so that
+ * multiple DANGLING aliases (target page deleted -> `page_id` SET NULL) can
+ * still coexist without colliding.
+ *
+ * ⚠️ IRREVERSIBLE DATA LOSS (intended): the dedup DELETE below permanently drops
+ * every alias row but the newest per page. Those duplicates were live `/l/<old>`
+ * pointers (resolved by name via `findByAliasAndWorkspace`, not by page), so
+ * after this upgrade any such OLD vanity link starts returning the SPA 404. This
+ * is the point — it kills the orphan rows the pre-invariant bug accumulated —
+ * but `down()` only drops the unique index; it CANNOT restore the deleted rows.
+ */
+export async function up(db: Kysely<any>): Promise<void> {
+  // Reap legacy duplicates: for each (workspace_id, page_id) keep only the row
+  // with the greatest (created_at, id) — matches ShareAliasRepo.findByPageId.
+  await sql`
+    DELETE FROM share_aliases sa
+    USING share_aliases keep
+    WHERE sa.page_id IS NOT NULL
+      AND sa.workspace_id = keep.workspace_id
+      AND sa.page_id = keep.page_id
+      AND (keep.created_at, keep.id) > (sa.created_at, sa.id)
+  `.execute(db);
+
+  await db.schema
+    .createIndex('share_aliases_workspace_id_page_id_unique')
+    .on('share_aliases')
+    .columns(['workspace_id', 'page_id'])
+    .unique()
+    .where('page_id', 'is not', null)
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .dropIndex('share_aliases_workspace_id_page_id_unique')
+    .execute();
+}

apps/server/src/database/repos/ai-agent-roles/ai-agent-roles.repo.spec.ts

@@ -1,4 +1,4 @@
-import { AiAgentRoleRepo } from './ai-agent-roles.repo';
+import { AiAgentRoleRepo, parseSource } from './ai-agent-roles.repo';
 import type { KyselyDB } from '../../types/kysely.types';
 
 /**
@@ -132,4 +132,77 @@ describe('AiAgentRoleRepo insert/update auto-start columns', () => {
     expect(set2.mock.calls[0][0].launchMessage).toBeNull();
     expect('autoStart' in set2.mock.calls[0][0]).toBe(false);
   });
+
+  it('insert binds `source` (jsonb); update sets it only when present', async () => {
+    const { repo, values } = makeInsertRepo();
+    await repo.insert({
+      workspaceId: 'ws-1',
+      name: 'R',
+      instructions: 'do',
+      source: { slug: 'researcher', language: 'en', version: 1 },
+    });
+    // jsonbBind returns a RawBuilder for a non-empty object (not null).
+    expect(values.mock.calls[0][0].source).not.toBeNull();
+
+    const { repo: repo2, set } = makeUpdateRepo();
+    await repo2.update('r-1', 'ws-1', { name: 'X' });
+    expect('source' in set.mock.calls[0][0]).toBe(false);
+
+    const { repo: repo3, set: set3 } = makeUpdateRepo();
+    await repo3.update('r-1', 'ws-1', {
+      source: { slug: 's', language: 'en', version: 2 },
+    });
+    expect('source' in set3.mock.calls[0][0]).toBe(true);
+  });
+});
+
+/**
+ * parseSource is THE single form validator for the `source` jsonb column: a
+ * JSON-string (legacy double-encoded) is parsed; a FULLY-VALID object
+ * ({ slug, language, version }) passes through as a typed RoleSource; anything
+ * partial or wrong-shaped degrades to null (= manual role). This is the
+ * stricter-than-before guard that closes the drift where a weak `{}`/`{slug:123}`
+ * value used to be stamped as a valid source by the read path.
+ */
+describe('parseSource', () => {
+  it('parses a legacy double-encoded JSON string into the typed source', () => {
+    expect(
+      parseSource('{"slug":"researcher","language":"en","version":1}'),
+    ).toEqual({ slug: 'researcher', language: 'en', version: 1 });
+  });
+
+  it('passes a fully-valid already-parsed object through', () => {
+    const obj = { slug: 's', language: 'en', version: 2 };
+    expect(parseSource(obj)).toEqual(obj);
+  });
+
+  it('returns the typed RoleSource (extra keys tolerated) for a valid shape', () => {
+    const src = parseSource({ slug: 's', language: 'ru', version: 3 });
+    expect(src).not.toBeNull();
+    // Narrowed to RoleSource: the fields are present and correctly typed.
+    expect(src?.slug).toBe('s');
+    expect(src?.language).toBe('ru');
+    expect(src?.version).toBe(3);
+  });
+
+  it('null / array / non-object / unparseable string => null', () => {
+    expect(parseSource(null)).toBeNull();
+    expect(parseSource([1, 2])).toBeNull();
+    expect(parseSource(42)).toBeNull();
+    expect(parseSource('not json')).toBeNull();
+  });
+
+  it('partial / wrong-typed shapes => null (no weak-but-typed-as-valid drift)', () => {
+    // Empty object: no slug/language/version.
+    expect(parseSource({})).toBeNull();
+    // slug present but not a string.
+    expect(parseSource({ slug: 123, language: 'en', version: 1 })).toBeNull();
+    // slug only, missing language + version.
+    expect(parseSource({ slug: 'a' })).toBeNull();
+    // empty-string slug / language are not valid catalog keys.
+    expect(parseSource({ slug: '', language: 'en', version: 1 })).toBeNull();
+    expect(parseSource({ slug: 'a', language: '', version: 1 })).toBeNull();
+    // version must be a number, not a numeric string.
+    expect(parseSource({ slug: 'a', language: 'en', version: '1' })).toBeNull();
+  });
 });

apps/server/src/database/repos/ai-agent-roles/ai-agent-roles.repo.ts

@@ -2,7 +2,7 @@ import { Injectable } from '@nestjs/common';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
 import { dbOrTx, jsonbBind, parseJsonbValue } from '../../utils';
-import { AiAgentRole } from '@docmost/db/types/entity.types';
+import { AiAgentRole, RoleSource } from '@docmost/db/types/entity.types';
 
 /** The jsonb shape persisted in `model_config` (loosely typed for the column). */
 type ModelConfigValue = Record<string, unknown> | null;
@@ -81,6 +81,8 @@ export class AiAgentRoleRepo {
       autoStart?: boolean;
       // null/'' => stored as null (client default launch message).
       launchMessage?: string | null;
+      // Catalog origin { slug, language, version } | null. null => manual role.
+      source?: Record<string, unknown> | null;
     },
     trx?: KyselyTransaction,
   ): Promise<AiAgentRole> {
@@ -103,6 +105,9 @@ export class AiAgentRoleRepo {
         autoStart: values.autoStart ?? true,
         // Empty string is treated as "no custom text" => null.
         launchMessage: values.launchMessage || null,
+        // Same cast reason as modelConfig (see above).
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        source: jsonbBind(values.source) as any,
       })
       .returningAll()
       .executeTakeFirst();
@@ -124,6 +129,8 @@ export class AiAgentRoleRepo {
       autoStart?: boolean;
       // undefined => unchanged; null/'' => clear to null; string => set.
       launchMessage?: string | null;
+      // undefined => unchanged; null => clear; object => set.
+      source?: Record<string, unknown> | null;
     },
     trx?: KyselyTransaction,
   ): Promise<void> {
@@ -142,6 +149,9 @@ export class AiAgentRoleRepo {
       // Empty string clears to null (client default launch message).
       set.launchMessage = patch.launchMessage || null;
     }
+    if (patch.source !== undefined) {
+      set.source = jsonbBind(patch.source);
+    }
     await db
       .updateTable('aiAgentRoles')
       .set(set)
@@ -192,14 +202,46 @@ export function parseModelConfig(
   );
 }
 
-/** Normalize a DB row so `modelConfig` is always an object or null. The cast
- *  bridges parseModelConfig's concrete `Record | null` to the column's broad
- *  generated `JsonValue` type (an object is a valid JsonValue at runtime). */
+/**
+ * THE single form validator for the `source` jsonb column: parse the value read
+ * from the DB into a fully-valid {@link RoleSource} or null. Same legacy
+ * double-encoding self-heal as {@link parseModelConfig} (a JSON string is parsed
+ * once), then validates the FULL shape — `slug` and `language` non-empty
+ * strings, `version` a number. A null / corrupt / partially-shaped value (e.g.
+ * `{}`, `{ slug: 123 }`, `{ slug: 'a' }` missing language/version) degrades to
+ * null (= manually created, no catalog provenance), so a bad row never breaks
+ * the read path AND never stamps a half-built object as a valid `RoleSource`.
+ * Both the repo read-path and the service share this so the contract cannot
+ * drift between layers.
+ */
+export function parseSource(value: unknown): RoleSource | null {
+  return parseJsonbValue(value, isRoleSource);
+}
+
+/** Full-shape guard for a persisted `source` jsonb value (see parseSource). */
+function isRoleSource(v: unknown): v is RoleSource {
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
+  const obj = v as Record<string, unknown>;
+  return (
+    typeof obj.slug === 'string' &&
+    obj.slug.length > 0 &&
+    typeof obj.language === 'string' &&
+    obj.language.length > 0 &&
+    typeof obj.version === 'number'
+  );
+}
+
+/** Normalize a DB row so `modelConfig` and `source` are always a valid object or
+ *  null. The casts bridge the concrete parsed types (`Record | null`,
+ *  `RoleSource | null`) to the column's broad generated `JsonValue` type — both
+ *  are valid JsonValues at runtime; RoleSource lacks the JsonObject index
+ *  signature so it routes through `unknown`. */
 function normalizeRow(row: AiAgentRole): AiAgentRole {
   return {
     ...row,
     modelConfig: parseModelConfig(
       row.modelConfig,
     ) as AiAgentRole['modelConfig'],
+    source: parseSource(row.source) as unknown as AiAgentRole['source'],
   };
 }

apps/server/src/database/repos/ai-chat/ai-chat.repo.spec.ts

@@ -0,0 +1,85 @@
+import { AiChatRepo } from './ai-chat.repo';
+import type { KyselyDB } from '../../types/kysely.types';
+
+/**
+ * Unit test for AiChatRepo.findLatestByPage — the "bound chat" resolver behind
+ * #191 (auto-open the last chat created on a document). It builds the scoping
+ * query, so we assert the EXACT predicates/ordering the spec mandates over a
+ * chainable builder mock (no live DB): user + workspace + page scope, the
+ * deletedAt filter, newest-by-createdAt with an id tiebreaker, limit 1. A
+ * live-Postgres ordering test is out of scope for this pure unit test.
+ */
+describe('AiChatRepo.findLatestByPage', () => {
+  type Recorded = {
+    table?: string;
+    wheres: Array<[string, string, unknown]>;
+    orderBys: Array<[string, string]>;
+    limit?: number;
+  };
+
+  function makeDb(result: unknown): { db: KyselyDB; rec: Recorded } {
+    const rec: Recorded = { wheres: [], orderBys: [] };
+    const builder: Record<string, unknown> = {};
+    const chain = () => builder;
+    builder.selectAll = chain;
+    builder.where = (col: string, op: string, val: unknown) => {
+      rec.wheres.push([col, op, val]);
+      return builder;
+    };
+    builder.orderBy = (col: string, dir: string) => {
+      rec.orderBys.push([col, dir]);
+      return builder;
+    };
+    builder.limit = (n: number) => {
+      rec.limit = n;
+      return builder;
+    };
+    builder.executeTakeFirst = () => Promise.resolve(result);
+    const db = {
+      selectFrom: (table: string) => {
+        rec.table = table;
+        return builder;
+      },
+    } as unknown as KyselyDB;
+    return { db, rec };
+  }
+
+  it('returns the matched chat and scopes by user + workspace + page (deletedAt null)', async () => {
+    const chat = { id: 'c1', creatorId: 'u1', workspaceId: 'ws1', pageId: 'p1' };
+    const { db, rec } = makeDb(chat);
+    const repo = new AiChatRepo(db);
+
+    const res = await repo.findLatestByPage('u1', 'ws1', 'p1');
+
+    expect(res).toBe(chat);
+    expect(rec.table).toBe('aiChats');
+    expect(rec.wheres).toEqual(
+      expect.arrayContaining([
+        ['creatorId', '=', 'u1'],
+        ['workspaceId', '=', 'ws1'],
+        ['pageId', '=', 'p1'],
+        ['deletedAt', 'is', null],
+      ]),
+    );
+  });
+
+  it('orders newest-first by createdAt then id, limit 1', async () => {
+    const { db, rec } = makeDb(undefined);
+    const repo = new AiChatRepo(db);
+
+    await repo.findLatestByPage('u1', 'ws1', 'p1');
+
+    expect(rec.orderBys).toEqual([
+      ['createdAt', 'desc'],
+      ['id', 'desc'],
+    ]);
+    expect(rec.limit).toBe(1);
+  });
+
+  it('returns undefined when the page has no owned chat', async () => {
+    const { db } = makeDb(undefined);
+    const repo = new AiChatRepo(db);
+
+    await expect(repo.findLatestByPage('u1', 'ws1', 'p1')).resolves.toBeUndefined();
+  });
+});

apps/server/src/database/repos/ai-chat/ai-chat.repo.ts

@@ -80,6 +80,32 @@ export class AiChatRepo {
     });
   }
 
+  /**
+   * The "bound chat" for a document: the requesting user's most recently
+   * created, non-deleted chat whose origin page is `pageId`. Auto-opened when
+   * the AI chat window is opened on that page. Newest-by-createdAt wins, so a
+   * chat created later on the same page supersedes earlier ones — exactly how
+   * "new chat -> becomes the bound one" falls out for free. Scoped to the user +
+   * workspace, so a foreign pageId can only ever match the caller's own chats.
+   */
+  async findLatestByPage(
+    creatorId: string,
+    workspaceId: string,
+    pageId: string,
+  ): Promise<AiChat | undefined> {
+    return this.db
+      .selectFrom('aiChats')
+      .selectAll('aiChats')
+      .where('creatorId', '=', creatorId)
+      .where('workspaceId', '=', workspaceId)
+      .where('pageId', '=', pageId)
+      .where('deletedAt', 'is', null)
+      .orderBy('createdAt', 'desc')
+      .orderBy('id', 'desc') // stable tiebreaker, mirrors findByCreator's cursor
+      .limit(1)
+      .executeTakeFirst();
+  }
+
   async insert(
     insertable: InsertableAiChat,
     trx?: KyselyTransaction,

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

@@ -7,7 +7,7 @@ import { executeWithCursorPagination } from '@docmost/db/pagination/cursor-pagin
 import { jsonObjectFrom } from 'kysely/helpers/postgres';
 import { ExpressionBuilder, SelectQueryBuilder, sql } from 'kysely';
 import { DB } from '@docmost/db/types/db';
-import { dbOrTx } from '@docmost/db/utils';
+import { dbOrTx, isUniqueViolation } from '@docmost/db/utils';
 
 export const FavoriteType = {
   PAGE: 'page',
@@ -29,7 +29,8 @@ export class FavoriteRepo {
         .returningAll()
         .executeTakeFirst();
     } catch (err: any) {
-      if (err?.code === '23505') return undefined;
+      // Idempotent favorite: a duplicate (already-favorited) is not an error.
+      if (isUniqueViolation(err)) return undefined;
       throw err;
     }
   }

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

@@ -16,7 +16,10 @@ import { jsonArrayFrom, jsonObjectFrom } from 'kysely/helpers/postgres';
 import { SpaceMemberRepo } from '@docmost/db/repos/space/space-member.repo';
 import { EventEmitter2 } from '@nestjs/event-emitter';
 import { EventName } from '../../../common/events/event.contants';
-import { TreeUpdateSnapshot } from '../../listeners/page.listener';
+import {
+  TreeUpdateSnapshot,
+  toTreeNodeSnapshot,
+} from '../../listeners/page.listener';
 
 /**
  * Optional extras for the PAGE_UPDATED event emitted by updatePage(s). Lets the
@@ -200,17 +203,10 @@ export class PageRepo {
     this.eventEmitter.emit(EventName.PAGE_CREATED, {
       pageIds: [result.id],
       workspaceId: result.workspaceId,
-      pages: [
-        {
-          id: result.id,
-          slugId: result.slugId,
-          title: result.title,
-          icon: result.icon,
-          position: result.position,
-          spaceId: result.spaceId,
-          parentPageId: result.parentPageId,
-        },
-      ],
+      // Built via the shared snapshot helper so the field copy (and the
+      // death-timer deadline that shows the sidebar clock marker without a
+      // reload) can't drift from the `addTreeNode` broadcast literal.
+      pages: [toTreeNodeSnapshot(result)],
     });
 
     return result;

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

@@ -10,16 +10,21 @@ import type { KyselyDB } from '../../types/kysely.types';
 describe('ShareAliasRepo', () => {
   function makeSelectRepo(result: unknown) {
     const where = jest.fn();
+    const orderBy = jest.fn();
     const builder: any = {
       select: jest.fn(() => builder),
       where: jest.fn((...args: unknown[]) => {
         where(...args);
         return builder;
       }),
+      orderBy: jest.fn((...args: unknown[]) => {
+        orderBy(...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 };
+    return { repo: new ShareAliasRepo(db), db, where, orderBy, builder };
   }
 
   it('findByAliasAndWorkspace scopes by alias AND workspace', async () => {
@@ -34,11 +39,15 @@ describe('ShareAliasRepo', () => {
     expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
   });
 
-  it('findByPageId scopes by page AND workspace', async () => {
-    const { repo, where } = makeSelectRepo(undefined);
+  it('findByPageId scopes by page AND workspace, deterministically ordered', async () => {
+    const { repo, where, orderBy } = makeSelectRepo(undefined);
     await repo.findByPageId('p-1', 'ws-1');
     expect(where).toHaveBeenCalledWith('pageId', '=', 'p-1');
     expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
+    // Explicit ORDER BY removes the nondeterministic heap order for any legacy
+    // duplicate rows (newest createdAt wins, id as a stable tiebreak).
+    expect(orderBy).toHaveBeenCalledWith('createdAt', 'desc');
+    expect(orderBy).toHaveBeenCalledWith('id', 'desc');
   });
 
   it('insert writes the provided columns and returns the row', async () => {
@@ -85,7 +94,9 @@ describe('ShareAliasRepo', () => {
         return builder;
       }),
       returning: jest.fn(() => builder),
-      executeTakeFirst: jest.fn().mockResolvedValue({ id: 'a-1' }),
+      // Retarget uses executeTakeFirstOrThrow so a row reaped by a concurrent
+      // delete (0 rows matched) raises NoResultError instead of returning undefined.
+      executeTakeFirstOrThrow: jest.fn().mockResolvedValue({ id: 'a-1' }),
     };
     const db = { updateTable: jest.fn(() => builder) } as unknown as KyselyDB;
     const repo = new ShareAliasRepo(db);
@@ -99,6 +110,60 @@ describe('ShareAliasRepo', () => {
     expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
   });
 
+  it('updateAlias renames 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),
+      // Rename uses executeTakeFirstOrThrow so a row reaped by a concurrent
+      // delete (0 rows matched) raises NoResultError instead of returning undefined.
+      executeTakeFirstOrThrow: jest
+        .fn()
+        .mockResolvedValue({ id: 'a-1', alias: 'ted' }),
+    };
+    const db = { updateTable: jest.fn(() => builder) } as unknown as KyselyDB;
+    const repo = new ShareAliasRepo(db);
+
+    const res = await repo.updateAlias('a-1', 'ted', 'ws-1');
+
+    expect(db.updateTable).toHaveBeenCalledWith('shareAliases');
+    expect(set.mock.calls[0][0].alias).toBe('ted');
+    expect(set.mock.calls[0][0].updatedAt).toBeInstanceOf(Date);
+    // a rename must NOT touch page_id (the page's pointer is preserved)
+    expect(set.mock.calls[0][0]).not.toHaveProperty('pageId');
+    expect(where).toHaveBeenCalledWith('id', '=', 'a-1');
+    expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
+    expect(res).toMatchObject({ alias: 'ted' });
+  });
+
+  it('deleteOthersForPage reaps every row for the page except keepId', 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.deleteOthersForPage('p-1', 'a-keep', 'ws-1');
+
+    expect(db.deleteFrom).toHaveBeenCalledWith('shareAliases');
+    expect(where).toHaveBeenCalledWith('pageId', '=', 'p-1');
+    expect(where).toHaveBeenCalledWith('workspaceId', '=', 'ws-1');
+    expect(where).toHaveBeenCalledWith('id', '!=', 'a-keep');
+  });
+
   it('delete scopes by id + workspace', async () => {
     const where = jest.fn();
     const builder: any = {

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

@@ -41,7 +41,14 @@ export class ShareAliasRepo {
       .executeTakeFirst();
   }
 
-  /** The alias currently pointing at a page (for the share modal). */
+  /**
+   * The alias currently pointing at a page (for the share modal). The service
+   * enforces a single alias row per page, but legacy rows (pre-invariant) may
+   * still exist until self-healed; the explicit ORDER BY makes the "current"
+   * choice DETERMINISTIC (newest wins — i.e. the most recently created address,
+   * which is the one the user last asked for) instead of an arbitrary Postgres
+   * heap order.
+   */
   async findByPageId(
     pageId: string,
     workspaceId: string,
@@ -52,6 +59,8 @@ export class ShareAliasRepo {
       .select(this.baseFields)
       .where('pageId', '=', pageId)
       .where('workspaceId', '=', workspaceId)
+      .orderBy('createdAt', 'desc')
+      .orderBy('id', 'desc')
       .executeTakeFirst();
   }
 
@@ -79,7 +88,60 @@ export class ShareAliasRepo {
       .executeTakeFirst();
   }
 
-  /** Retarget an existing alias to a new page (the "swap" operation). */
+  /**
+   * Rename an existing alias row in place (the vanity-slug edit, e.g.
+   * `te` -> `ted`). Keeps the row's id/page_id/creator so the page's single
+   * alias pointer is preserved — only the human-readable name changes.
+   *
+   * Uses `executeTakeFirstOrThrow`: if a concurrent `delete` reaps this row
+   * between the service's read and this UPDATE (READ COMMITTED), the UPDATE
+   * matches 0 rows and kysely throws `NoResultError` rather than returning
+   * `undefined` for a `Promise<ShareAlias>`. The service maps that to a
+   * retryable conflict instead of dereferencing `undefined.id`.
+   */
+  async updateAlias(
+    id: string,
+    alias: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<ShareAlias> {
+    return dbOrTx(this.db, trx)
+      .updateTable('shareAliases')
+      .set({ alias, updatedAt: new Date() })
+      .where('id', '=', id)
+      .where('workspaceId', '=', workspaceId)
+      .returning(this.baseFields)
+      .executeTakeFirstOrThrow();
+  }
+
+  /**
+   * Self-heal helper: drop every OTHER alias row still pointing at a page,
+   * keeping only `keepId`. Enforces the "exactly one custom address per page"
+   * invariant after a rename/retarget and reaps any legacy duplicates.
+   */
+  async deleteOthersForPage(
+    pageId: string,
+    keepId: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    await dbOrTx(this.db, trx)
+      .deleteFrom('shareAliases')
+      .where('pageId', '=', pageId)
+      .where('workspaceId', '=', workspaceId)
+      .where('id', '!=', keepId)
+      .execute();
+  }
+
+  /**
+   * Retarget an existing alias to a new page (the "swap" operation).
+   *
+   * Uses `executeTakeFirstOrThrow`: if a concurrent `delete` reaps this row
+   * between the service's read and this UPDATE, the UPDATE matches 0 rows and
+   * kysely throws `NoResultError` instead of returning `undefined` into the 200
+   * response (a "success" with no alias). The service maps that to a retryable
+   * conflict.
+   */
   async updatePageId(
     id: string,
     pageId: string,
@@ -92,7 +154,7 @@ export class ShareAliasRepo {
       .where('id', '=', id)
       .where('workspaceId', '=', workspaceId)
       .returning(this.baseFields)
-      .executeTakeFirst();
+      .executeTakeFirstOrThrow();
   }
 
   async delete(