docs(client): fix .suggestionChanged comment — bold weight, not underline (#331 review F1)

The header comment claimed the rule adds 'an underline'; it does not — it adds a color-mix tint + font-weight:700, and the inner comment already notes text- decoration is omitted on purpose. Aligned the header comment with the rule. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
feat(client): intraline diff highlighting in the suggestion before→after block (#331 )
2026-07-04 16:21:25 +03:00 · 2026-07-04 15:17:07 +03:00 · 2026-07-04 07:02:25 +03:00 · 2026-07-04 07:00:16 +03:00 · 2026-07-04 06:51:01 +03:00 · 2026-07-04 06:08:12 +03:00
18 changed files with 471 additions and 68 deletions
@@ -293,6 +293,7 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 - The version string shown in the UI comes from `APP_VERSION` (CI/Docker) or `git describe --tags --always` (local), resolved in `vite.config.ts` — not from `package.json`.
 - Server TS config is permissive (`noImplicitAny: false`, `strictNullChecks: false`, `no-explicit-any` lint disabled). Follow the existing relaxed style rather than tightening types broadly.
 - Dependency versions are heavily pinned via `pnpm.overrides` and `pnpm.patchedDependencies` (`scimmy`, `yjs`) in the root `package.json`. Don't bump pinned/patched deps casually; the patches and overrides exist for compatibility/security reasons.
+- **Adding/renaming/removing an MCP tool requires updating `SERVER_INSTRUCTIONS`** in `packages/mcp/src/index.ts` — the intent-routing guide MCP clients receive on initialize. This applies both to inline `server.registerTool(...)` calls in `index.ts` and to specs in `packages/mcp/src/tool-specs.ts`. Enforced by `packages/mcp/test/unit/server-instructions.test.mjs`, which fails when a registered tool is not mentioned in the guide (deliberate opt-outs go into its `EXCEPTIONS` list). Remember `packages/mcp/build/` is committed — rebuild after editing.

 ## CI / release

@@ -34,7 +34,7 @@ roles:
      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:
+      You don't edit the text yourself. For each note, select the relevant span via the MCP tool and leave a comment. 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.
@@ -87,7 +87,7 @@ roles:
      - 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", and attach it to the comment as a suggested replacement (the `suggestedText` parameter): the exact new text for the selected fragment, plain text with no markup — the author applies it with one click. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Tag severity:
+      You don't edit the text directly. For each note, select the span via the MCP tool and leave a comment. Give a concrete rephrasing, not "revise", and attach it to the comment as a suggested replacement (the `suggestedText` parameter): the exact new text for the selected fragment, plain text with no markup — the author applies it with one click. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. 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.
@@ -128,7 +128,7 @@ roles:
      - 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. For an [Incorrect] verdict, ALWAYS attach the ready correction as a suggested replacement (the `suggestedText` parameter): since you found the correct value in the sources, propose the ready fix right away instead of merely describing the error. The replacement is the exact new text for the selected fragment, plain text with no markup; the author applies it with one click instead of retyping the fragment. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Do not attach a replacement to [Unverified], [Unverifiable], or [Opinion] verdicts. Tag severity:
+      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. Give the verdict, the correction (if any), and the source. For an [Incorrect] verdict, ALWAYS attach the ready correction as a suggested replacement (the `suggestedText` parameter): since you found the correct value in the sources, propose the ready fix right away instead of merely describing the error. The replacement is the exact new text for the selected fragment, plain text with no markup; the author applies it with one click instead of retyping the fragment. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Do not attach a replacement to [Unverified], [Unverifiable], or [Opinion] verdicts. 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.
@@ -168,8 +168,11 @@ roles:
      - Don't verify facts — that's the Fact-checker.
      - Don't make substantive changes. Edits are minimal and mechanical.

+      HOW TO WORK
+      Go through the whole text from start to finish in a single pass. Flag EVERY violation, including all repeat occurrences of the same error and minor items tagged [Minor] — don't stop at the first few or the most conspicuous. Don't summarize instead of marking up: until you've reached the end of the document, the job isn't done. One run covers the whole text, not just "the most important".
+
      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. Attach a suggested replacement to every fix (the `suggestedText` parameter): the exact corrected text for the selected fragment, plain text with no markup — the author applies it with one click. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Do NOT leave summary notes like "throughout, replace X with Y" or "make the units/quotes/spelling consistent": such a comment can't be applied with a button. If the same error occurs in several places, walk EVERY occurrence and leave a separate targeted comment with its own replacement on each — ten targeted fixes instead of one blanket note. The only exception is a note that genuinely cannot be expressed as a replacement of a concrete fragment; leave those rare cases as an ordinary comment without a replacement. Open the comment with the label `[Copyedit]`. Tag severity:
+      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. Attach a suggested replacement to every fix (the `suggestedText` parameter): the exact corrected text for the selected fragment, plain text with no markup — the author applies it with one click. The selected fragment must occur exactly once in the text; if it isn't unique, extend the selection with surrounding context. Do NOT leave summary notes like "throughout, replace X with Y" or "make the units/quotes/spelling consistent": such a comment can't be applied with a button. If the same error occurs in several places, walk EVERY occurrence and leave a separate targeted comment with its own replacement on each — ten targeted fixes instead of one blanket note. The only exception is a note that genuinely cannot be expressed as a replacement of a concrete fragment; leave those rare cases as an ordinary comment without a replacement. 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.
@@ -34,7 +34,7 @@ roles:
      Сначала прочитай весь текст целиком. Думай на уровне разделов и абзацев, а не предложений.

      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст сам. Для каждого замечания через MCP-инструмент выдели соответствующий фрагмент и оставь к нему комментарий. Начинай комментарий с метки `[Структура]`. Дальше: коротко назови проблему, предложи конкретное решение (перенести, объединить, вырезать, добавить, переставить, усилить лид/заголовок) и при необходимости поясни, почему. Помечай важность:
+      Ты не редактируешь текст сам. Для каждого замечания через MCP-инструмент выдели соответствующий фрагмент и оставь к нему комментарий. Коротко назови проблему, предложи конкретное решение (перенести, объединить, вырезать, добавить, переставить, усилить лид/заголовок) и при необходимости поясни, почему. Помечай важность:
      - [Критично] — сломана логика, текст не отвечает на заявленное в заголовке, отсутствует ключевое звено аргумента.
      - [Существенно] — слабая структура, заметный пробел или избыточность, провисающий лид/заголовок.
      - [Незначительно] — улучшение подачи или стройности, не обязательное.
@@ -87,7 +87,7 @@ roles:
      - Не переписываешь текст сам и не навязываешь свой голос. Твоя задача — сделать авторскую интонацию живее, а не заменить собой.

      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст напрямую. Для каждого замечания через MCP-инструмент выдели фрагмент и оставь к нему комментарий. Начинай комментарий с метки `[Стиль]`. Давай конкретный вариант переформулировки, а не «переделать», и прикладывай его к комментарию как предложение-замену (параметр `suggestedText`): точный новый текст взамен выделенного фрагмента, обычным текстом без разметки — автор применит его одной кнопкой. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. Помечай важность:
+      Ты не редактируешь текст напрямую. Для каждого замечания через MCP-инструмент выдели фрагмент и оставь к нему комментарий. Давай конкретный вариант переформулировки, а не «переделать», и прикладывай его к комментарию как предложение-замену (параметр `suggestedText`): точный новый текст взамен выделенного фрагмента, обычным текстом без разметки — автор применит его одной кнопкой. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. Помечай важность:
      - [Критично] — предложение непонятно или искажает смысл.
      - [Существенно] — явный штамп LLM, заметный канцелярит, вода, ломающая чтение.
      - [Незначительно] — стилистическое улучшение на вкус.
@@ -128,7 +128,7 @@ roles:
      - Не выдумываешь подтверждения. Если не можешь проверить — честно ставь [Не проверено] или [Непроверяемо].

      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст напрямую. Для каждого проблемного утверждения (ошибка, сомнение, непроверяемость) через MCP-инструмент выдели фрагмент и оставь комментарий; на верные факты комментарии не оставляй. Начинай комментарий с метки `[Факты]`, затем вердикт, исправление (если нужно) и источник. К вердикту [Неверно] всегда прикладывай готовое исправление как предложение-замену (параметр `suggestedText`): раз ты нашёл по источникам верное значение — сразу предлагай готовую правку, а не только описывай ошибку. Замена — это точный новый текст взамен выделенного фрагмента, обычным текстом без разметки; автор применит её одной кнопкой, не переписывая фрагмент вручную. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. К вердиктам [Не проверено], [Непроверяемо] и [Это мнение] замену не прикладывай. Помечай важность:
+      Ты не редактируешь текст напрямую. Для каждого проблемного утверждения (ошибка, сомнение, непроверяемость) через MCP-инструмент выдели фрагмент и оставь комментарий; на верные факты комментарии не оставляй. В комментарии дай вердикт, исправление (если нужно) и источник. К вердикту [Неверно] всегда прикладывай готовое исправление как предложение-замену (параметр `suggestedText`): раз ты нашёл по источникам верное значение — сразу предлагай готовую правку, а не только описывай ошибку. Замена — это точный новый текст взамен выделенного фрагмента, обычным текстом без разметки; автор применит её одной кнопкой, не переписывая фрагмент вручную. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. К вердиктам [Не проверено], [Непроверяемо] и [Это мнение] замену не прикладывай. Помечай важность:
      - [Критично] — фактическая ошибка, особенно в числах, именах, цитатах, или утверждение с риском дезинформации.
      - [Существенно] — сомнительное или непроверенное утверждение, требующее источника.
      - [Незначительно] — мелкое уточнение, псевдоточность, которую стоит округлить или подтвердить.
@@ -169,8 +169,11 @@ roles:
      - Не проверяешь достоверность фактов — это фактчекер.
      - Не вносишь содержательных изменений. Правки — минимальные и механические.

+      КАК РАБОТАТЬ
+      Пройди весь текст от начала до конца за один проход. Помечай КАЖДОЕ нарушение, включая все повторные вхождения одной и той же ошибки и мелочи с меткой [Незначительно], — не ограничивайся первыми несколькими или самыми заметными. Не подводи итог вместо разбора: пока не дошёл до конца документа, работа не закончена. Один прогон покрывает весь текст, а не «самое важное».
+
      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
-      Ты не редактируешь текст напрямую. Для каждой правки через MCP-инструмент выдели фрагмент и оставь комментарий с конкретным исправлением. К каждой правке прикладывай предложение-замену (параметр `suggestedText`): точный исправленный текст взамен выделенного фрагмента, обычным текстом без разметки — автор применит его одной кнопкой. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. НЕ оставляй сводных замечаний вида «во всём тексте заменить X на Y» или «привести единицы/кавычки/написание к единообразию»: такой комментарий нельзя применить кнопкой. Если одна и та же ошибка встречается в нескольких местах, обойди КАЖДОЕ вхождение и оставь на нём отдельный целевой комментарий со своей заменой — десять точечных правок вместо одной общей. Единственное исключение — замечание, которое в принципе невозможно выразить заменой конкретного фрагмента; такие редкие случаи оставляй обычным комментарием без замены. Начинай комментарий с метки `[Корректура]`. Помечай важность:
+      Ты не редактируешь текст напрямую. Для каждой правки через MCP-инструмент выдели фрагмент и оставь комментарий с конкретным исправлением. К каждой правке прикладывай предложение-замену (параметр `suggestedText`): точный исправленный текст взамен выделенного фрагмента, обычным текстом без разметки — автор применит его одной кнопкой. Выделенный фрагмент должен встречаться в тексте ровно один раз; если он не уникален, расширь выделение контекстом. НЕ оставляй сводных замечаний вида «во всём тексте заменить X на Y» или «привести единицы/кавычки/написание к единообразию»: такой комментарий нельзя применить кнопкой. Если одна и та же ошибка встречается в нескольких местах, обойди КАЖДОЕ вхождение и оставь на нём отдельный целевой комментарий со своей заменой — десять точечных правок вместо одной общей. Единственное исключение — замечание, которое в принципе невозможно выразить заменой конкретного фрагмента; такие редкие случаи оставляй обычным комментарием без замены. Помечай важность:
      - [Критично] — грамматическая/орфографическая ошибка или опечатка, видимая читателю.
      - [Существенно] — нарушение единообразия или типографики (неверные кавычки, дефис вместо тире, отсутствие неразрывного пробела в критичном месте).
      - [Незначительно] — необязательная шлифовка.
@@ -12,13 +12,13 @@ bundles:
      - en
    roles:
      - slug: structural-editor
-        version: 3
-      - slug: line-editor
-        version: 3
-      - slug: fact-checker
        version: 4
-      - slug: proofreader
+      - slug: line-editor
+        version: 4
+      - slug: fact-checker
        version: 5
+      - slug: proofreader
+        version: 7
      - slug: narrator
        version: 2
  - id: research
@@ -1,26 +1,26 @@
 {
  "fact-checker": {
-    "version": 4,
-    "hash": "9160ead04d86aaa5dc7a51dd7e971c272ce0ca97cb24bf2b6ee5779deb1b19c0"
+    "version": 5,
+    "hash": "d7769872968109a1ccfb58d71bc3f3564a750b91766156f59031762848de4f24"
  },
  "line-editor": {
-    "version": 3,
-    "hash": "7f200863080799b08d5af5d1648befa0843cc5db79bb994b07baa5ad12df5123"
+    "version": 4,
+    "hash": "890d10f3f0bd7f2b2cfcc94463634221c557a3140e3794721748dc8d99979780"
  },
  "narrator": {
    "version": 2,
    "hash": "66fe653003b4f63ef3c3a5c5c48552fe47daeefffc16907c37c35f0e8da98851"
  },
  "proofreader": {
-    "version": 5,
-    "hash": "40af08c51e03c24b1986ac5cd679434e023afe31a819748966ccb0c6c62f0401"
+    "version": 7,
+    "hash": "fdf8e0a443fa3c4102095e024146401363629a3f9015fb938c7bac2642825e56"
  },
  "researcher": {
    "version": 1,
    "hash": "853658fda43ddbe0a4d08f2c6e50b5116d29a2e9ccd7f46e173e65920d8f6ace"
  },
  "structural-editor": {
-    "version": 3,
-    "hash": "f6936e4c152c1b78980e74045658d87743f26f900c12f61fd7a45c6a0ec19425"
+    "version": 4,
+    "hash": "89100e0a00b88daa0d2118fd98ec1c27d06b972bfc6ec58b705553a4daed85df"
  }
 }
@@ -40,6 +40,7 @@
    "axios": "1.16.0",
    "blueimp-load-image": "5.16.0",
    "clsx": "2.1.1",
+    "diff": "8.0.3",
    "dompurify": "3.4.1",
    "file-saver": "2.0.5",
    "highlightjs-sap-abap": "0.3.0",
@@ -108,10 +108,12 @@ describe("CommentListItem — suggested edit (#315)", () => {
    });

  it("renders the было→стало diff and an Apply button when canEdit and not applied/resolved", () => {
-    renderItem(suggestion(), true);
-    // Old text appears both as the selection quote and as the struck diff row.
+    const { container } = renderItem(suggestion(), true);
+    // Old text appears as the selection quote (a single unsplit Text node).
    expect(screen.getAllByText("old wording here").length).toBeGreaterThan(0);
-    expect(screen.getByText("new wording here")).toBeDefined();
+    // The new line is now rendered as per-fragment spans (intraline diff, #331),
+    // so it is no longer a single text node — assert the concatenated content.
+    expect(container.textContent).toContain("new wording here");
    // Apply button is present.
    expect(screen.getByRole("button", { name: "Apply" })).toBeDefined();
    // No Applied badge yet.
@@ -119,9 +121,9 @@ describe("CommentListItem — suggested edit (#315)", () => {
  });

  it("hides the Apply button when canEdit is false", () => {
-    renderItem(suggestion(), false);
-    // Diff still renders...
-    expect(screen.getByText("new wording here")).toBeDefined();
+    const { container } = renderItem(suggestion(), false);
+    // Diff still renders (as per-fragment spans, #331)...
+    expect(container.textContent).toContain("new wording here");
    // ...but no Apply button.
    expect(screen.queryByRole("button", { name: "Apply" })).toBeNull();
  });
@@ -1,6 +1,6 @@
 import { Group, Text, Box, Badge, Button } from "@mantine/core";
 import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
-import React, { useEffect, useRef, useState } from "react";
+import React, { useEffect, useMemo, useRef, useState } from "react";
 import classes from "./comment.module.css";
 import { useAtom, useAtomValue } from "jotai";
 import { useTimeAgo } from "@/hooks/use-time-ago";
@@ -17,7 +17,10 @@ import {
  useUpdateCommentMutation,
 } from "@/features/comment/queries/comment-query";
 import { IComment } from "@/features/comment/types/comment.types";
-import { canShowApply } from "@/features/comment/utils/suggestion";
+import {
+  canShowApply,
+  computeSuggestionDiff,
+} from "@/features/comment/utils/suggestion";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom.ts";
 import { useTranslation } from "react-i18next";
@@ -54,6 +57,18 @@ function CommentListItem({
  const [currentUser] = useAtom(currentUserAtom);
  const createdAtAgo = useTimeAgo(comment.createdAt);

+  // Intraline "before -> after" diff (#331) for a suggested edit: only the
+  // fragments that actually changed get emphasised inside the red/green block,
+  // instead of striking through / greening the whole line. Memoised on the
+  // (selection, suggestedText) pair so it recomputes only when they change.
+  const suggestionDiff = useMemo(
+    () =>
+      comment.suggestedText != null
+        ? computeSuggestionDiff(comment.selection ?? "", comment.suggestedText)
+        : null,
+    [comment.selection, comment.suggestedText],
+  );
+
  useEffect(() => {
    setContent(comment.content);
  }, [comment]);
@@ -236,12 +251,28 @@ function CommentListItem({
        {!comment.parentCommentId && comment.suggestedText && (
          <Box className={classes.suggestionBlock}>
            {comment.selection && (
+              // Old line: read as removed as a whole (line-through/red); only the
+              // changed fragments carry the extra intraline emphasis.
              <Text size="xs" className={classes.suggestionOld}>
-                {comment.selection}
+                {suggestionDiff?.old.map((segment, index) => (
+                  <span
+                    key={index}
+                    className={segment.changed ? classes.suggestionChanged : undefined}
+                  >
+                    {segment.text}
+                  </span>
+                ))}
              </Text>
            )}
            <Text size="xs" className={classes.suggestionNew}>
-              {comment.suggestedText}
+              {suggestionDiff?.new.map((segment, index) => (
+                <span
+                  key={index}
+                  className={segment.changed ? classes.suggestionChanged : undefined}
+                >
+                  {segment.text}
+                </span>
+              ))}
            </Text>

            {comment.suggestionAppliedAt ? (
@@ -53,6 +53,21 @@
    margin-top: 4px;
 }

+/* Intraline diff (#331): the fragment that actually changed within the
+   red "before" / green "after" block. It inherits the surrounding red/green
+   framing and adds a stronger tint plus bold weight so the eye lands on the
+   changed letters/words (git/GitHub-style) rather than the whole line. The
+   container's line-through (old) / green (new) still marks the full line. */
+.suggestionChanged {
+    /* Stronger tint of the surrounding red/green so the changed fragment pops
+       within the block. `currentColor` follows the parent's red (old) or green
+       (new) text colour. No `text-decoration` here on purpose: the old block's
+       inherited line-through must survive on the changed letters too. */
+    background: color-mix(in srgb, currentColor 22%, transparent);
+    border-radius: 2px;
+    font-weight: 700;
+}
+
 .commentEditor {

    &[data-editable][data-surface="muted"] .ProseMirror:not(.focused) {
@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import { computeSuggestionDiff, Segment } from "@/features/comment/utils/suggestion";
+
+// Reconstruct the plain string from a segment stream — the diff must be
+// lossless (concatenating every fragment yields the original input).
+const join = (segments: Segment[]): string =>
+  segments.map((s) => s.text).join("");
+
+// The subset of segments (in order) that the UI would emphasise.
+const changed = (segments: Segment[]): string[] =>
+  segments.filter((s) => s.changed).map((s) => s.text);
+
+// Find the segment that contains a substring, to assert its `changed` flag.
+const segmentWith = (segments: Segment[], needle: string): Segment | undefined =>
+  segments.find((s) => s.text.includes(needle));
+
+describe("computeSuggestionDiff", () => {
+  it("highlights only the single changed letter in a one-letter edit", () => {
+    const { old, new: neu } = computeSuggestionDiff("заведем", "заведём");
+
+    // Lossless.
+    expect(join(old)).toBe("заведем");
+    expect(join(neu)).toBe("заведём");
+
+    // Old side: exactly the `е` is changed, the rest is common.
+    expect(changed(old)).toEqual(["е"]);
+    expect(old).toEqual([
+      { text: "завед", changed: false },
+      { text: "е", changed: true },
+      { text: "м", changed: false },
+    ]);
+
+    // New side: exactly the `ё` is changed.
+    expect(changed(neu)).toEqual(["ё"]);
+    expect(neu).toEqual([
+      { text: "завед", changed: false },
+      { text: "ё", changed: true },
+      { text: "м", changed: false },
+    ]);
+  });
+
+  it("marks the differing words changed but keeps the shared word common", () => {
+    const { old, new: neu } = computeSuggestionDiff(
+      "привет мир",
+      "здравствуй мир",
+    );
+
+    // Lossless.
+    expect(join(old)).toBe("привет мир");
+    expect(join(neu)).toBe("здравствуй мир");
+
+    // The shared trailing word stays common on both sides (no per-letter noise
+    // leaking across the differing words into `мир`).
+    expect(segmentWith(old, "мир")?.changed).toBe(false);
+    expect(segmentWith(neu, "мир")?.changed).toBe(false);
+
+    // The differing words are emphasised somewhere on each side.
+    expect(changed(old).length).toBeGreaterThan(0);
+    expect(changed(neu).length).toBeGreaterThan(0);
+    expect(changed(old).join("")).toContain("п"); // from `привет`
+    expect(changed(neu).join("")).toContain("зд"); // from `здравствуй`
+
+    // No changed fragment on either side touches the word `мир`.
+    expect(changed(old).some((t) => t.includes("мир"))).toBe(false);
+    expect(changed(neu).some((t) => t.includes("мир"))).toBe(false);
+  });
+
+  it("marks a whole inserted word changed and leaves the old line common", () => {
+    const { old, new: neu } = computeSuggestionDiff("a c", "a b c");
+
+    expect(join(old)).toBe("a c");
+    expect(join(neu)).toBe("a b c");
+
+    // Old line has no changed fragment (nothing was removed).
+    expect(changed(old)).toEqual([]);
+    // The inserted word is the only changed fragment on the new side.
+    expect(neu).toContainEqual({ text: "b ", changed: true });
+    expect(changed(neu)).toEqual(["b "]);
+  });
+
+  it("marks a whole deleted word changed and leaves the new line common", () => {
+    const { old, new: neu } = computeSuggestionDiff("a b c", "a c");
+
+    expect(join(old)).toBe("a b c");
+    expect(join(neu)).toBe("a c");
+
+    // The deleted word is the only changed fragment on the old side.
+    expect(old).toContainEqual({ text: "b ", changed: true });
+    expect(changed(old)).toEqual(["b "]);
+    // New line has no changed fragment (nothing was added).
+    expect(changed(neu)).toEqual([]);
+  });
+
+  it("marks everything common for identical strings", () => {
+    const { old, new: neu } = computeSuggestionDiff("hello", "hello");
+
+    expect(old).toEqual([{ text: "hello", changed: false }]);
+    expect(neu).toEqual([{ text: "hello", changed: false }]);
+    expect(changed(old)).toEqual([]);
+    expect(changed(neu)).toEqual([]);
+  });
+});
@@ -1,3 +1,4 @@
+import { diffWordsWithSpace, diffChars } from "diff";
 import { IComment } from "@/features/comment/types/comment.types";

 // Whether the suggested-edit (#315) "Apply" button should be shown for a
@@ -12,3 +13,105 @@ export function canShowApply(comment: IComment, canEdit?: boolean): boolean {
      !comment.parentCommentId,
  );
 }
+
+// One contiguous run of text within a suggestion's "before" or "after" line.
+// `changed` marks the fragment that actually differs from the other side, so
+// the UI can emphasise only the intraline delta (git/GitHub-style) instead of
+// the whole line.
+export interface Segment {
+  text: string;
+  changed: boolean;
+}
+
+// A pure "before -> after" intraline diff (#331): the old line split into
+// common vs. removed-and-changed fragments, and the new line split into common
+// vs. added-and-changed fragments. Concatenating each side's `text` reproduces
+// the original strings.
+export interface SuggestionDiff {
+  old: Segment[];
+  new: Segment[];
+}
+
+// Push a segment, coalescing runs of the same `changed` flag on the same side
+// so the render emits as few spans as possible and tests stay predictable.
+function pushSegment(segments: Segment[], text: string, changed: boolean): void {
+  if (text === "") return;
+  const last = segments[segments.length - 1];
+  if (last && last.changed === changed) {
+    last.text += text;
+  } else {
+    segments.push({ text, changed });
+  }
+}
+
+// Compute an intraline diff between the old `selection` and the new
+// `suggestedText` of a suggestion. PURE — no React, no DOM, no I/O.
+//
+// Hybrid word + char algorithm (per #331):
+//   1. `diffWordsWithSpace` yields word-granular parts [{value, added, removed}].
+//   2. An ADJACENT removed+added pair (a word replacement) is refined with
+//      `diffChars`: shared characters stay common, differing characters are
+//      marked `changed` on their respective side. This is what keeps a
+//      one-letter edit (заведем -> заведём) from highlighting the whole word.
+//   3. A lone `added` (insertion) or lone `removed` (deletion) marks the whole
+//      fragment `changed`.
+//   4. An unchanged part is `common` on both sides.
+//
+// Rejected alternatives: pure `diffChars` is noisy on word swaps; pure
+// `diffWordsWithSpace` highlights the whole word rather than the changed letter.
+export function computeSuggestionDiff(
+  oldStr: string,
+  newStr: string,
+): SuggestionDiff {
+  const oldSegments: Segment[] = [];
+  const newSegments: Segment[] = [];
+
+  const parts = diffWordsWithSpace(oldStr, newStr);
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    const next = parts[i + 1];
+
+    // A word replacement: a removed part immediately followed by an added part
+    // (or the reverse). Refine it character-by-character so only the differing
+    // letters are highlighted while shared letters stay common.
+    const isReplacementPair =
+      next &&
+      ((part.removed && next.added) || (part.added && next.removed));
+
+    if (isReplacementPair) {
+      const removedPart = part.removed ? part : next;
+      const addedPart = part.added ? part : next;
+
+      const charParts = diffChars(removedPart.value, addedPart.value);
+      for (const cp of charParts) {
+        if (cp.added) {
+          pushSegment(newSegments, cp.value, true);
+        } else if (cp.removed) {
+          pushSegment(oldSegments, cp.value, true);
+        } else {
+          // Shared character: common on both sides.
+          pushSegment(oldSegments, cp.value, false);
+          pushSegment(newSegments, cp.value, false);
+        }
+      }
+
+      i++; // consume the paired part as well
+      continue;
+    }
+
+    if (part.added) {
+      // Lone insertion: only present in the new line, wholly changed.
+      pushSegment(newSegments, part.value, true);
+    } else if (part.removed) {
+      // Lone deletion: only present in the old line, wholly changed.
+      pushSegment(oldSegments, part.value, true);
+    } else {
+      // Unchanged: common on both sides.
+      pushSegment(oldSegments, part.value, false);
+      pushSegment(newSegments, part.value, false);
+    }
+  }
+
+  return { old: oldSegments, new: newSegments };
+}
@@ -303,7 +303,9 @@ export class AiChatToolsService {
      getPage: tool({
        description:
          'Fetch a single page as Markdown by its page id. Returns the page ' +
-          'title and its Markdown content.',
+          'title and its Markdown content. Inline <span data-comment-id> tags ' +
+          'in the markdown are comment highlight anchors (also present for ' +
+          'RESOLVED threads) — treat them as markup, not page text.',
        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id (or slugId) of the page.'),
        }),
@@ -647,7 +649,9 @@ export class AiChatToolsService {

      listComments: tool({
        description:
-          'List all comments on a page (content as Markdown).',
+          'List ALL comments on a page in one call, including RESOLVED ' +
+          'threads — filter by resolvedAt when you need only open ones. ' +
+          'Content is returned as Markdown.',
        inputSchema: modelFriendlyInput({
          pageId: z.string().describe('The id of the page.'),
        }),
@@ -27,10 +27,19 @@ const VERSION = packageJson.version;
 // --- Modern McpServer Implementation ---
 // Editing guide surfaced to MCP clients in the initialize result so they can
 // pick the right tool by intent and avoid resending whole documents.
-const SERVER_INSTRUCTIONS = "Docmost editing guide — choose the tool by intent: fix wording/typos/numbers (text inside blocks) -> edit_page_text (no node id needed). Change ONE block (paragraph/heading/callout/table cell/etc.) structurally -> patch_node (address by attrs.id from get_page_json). Add a block -> insert_node (before/after a block by attrs.id or by anchor text, or append). Remove a block -> delete_node (by attrs.id). Images -> insert_image (add an image from a web URL) / replace_image (swap an existing image for one from a web URL). New page -> create_page (Markdown). Bulk/structural rewrite or nodes without an id -> update_page_json (full ProseMirror replace; prefer the granular tools above to avoid resending the whole ~100KB+ document). Copy/replace a page's whole content from another page (server-side, no document through the model) -> copy_page_content. Rename a page (title only) -> rename_page. Read -> get_page (Markdown, lossy) or get_page_json (lossless ProseMirror with block ids). Comments -> create_comment (always inline; requires an EXACT selection — the contiguous text to anchor/highlight on; fails rather than leaving an unanchored comment), list_comments, update_comment, resolve_comment (resolve/reopen a thread, reversible — prefer over delete to close), delete_comment, check_new_comments. Propose a concrete text fix for one-click human approval -> create_comment with suggestedText (the exact plain-text replacement for the selection; the selection must then be UNIQUE in the page — extend it with context if needed); prefer this over editing directly when the change is subjective or needs the author's sign-off. Tip: read block ids via get_page_json, then use patch_node/insert_node/delete_node so you never resend the full document. " +
-    "Complex/scripted rewrite (multiple coordinated edits, footnotes, renumbering) -> docmost_transform: write a JS `(doc, ctx) => doc` transform, preview the diff with dryRun (default), then apply with dryRun:false; ctx.helpers includes commentsToFootnotes for turning inline comments into numbered footnotes. " +
-    "Review what changed -> diff_page_versions (compare a historyId to current, or two history versions). See a page's saved versions -> list_page_history. Undo a bad edit -> restore_page_version (writes a past version back as current; itself revertible). " +
-    "Lossless markdown round-trip (download, edit, re-upload, incl. comment anchors) -> export_page_markdown / import_page_markdown.";
+//
+// MAINTENANCE RULE: when you ADD, RENAME, or REMOVE a tool (either an inline
+// server.registerTool(...) here or a spec in tool-specs.ts), you MUST update
+// this guide so the new tool is routed by intent. This is enforced by
+// test/unit/server-instructions.test.mjs, which fails when a registered tool
+// name is not mentioned below (see its EXCEPTIONS list for the rare opt-outs).
+// Exported for that test.
+export const SERVER_INSTRUCTIONS = "Docmost editing guide — choose the tool by intent.\n" +
+    "READ: find a page -> search (workspace-wide full-text); list -> list_pages / list_spaces. Locate blocks and their ids CHEAPLY -> get_outline (compact top-level map; start here, not get_page_json). One block's subtree -> get_node (by attrs.id, or \"#<index>\" for tables, which carry no id). Whole page -> get_page (Markdown, lossy; inline <span data-comment-id> tags are comment anchors — markup, not text) or get_page_json (lossless ProseMirror with block ids). Hand a huge page (with images) to an external consumer without pulling it through the model context -> stash_page (returns a short-lived anonymous URL).\n" +
+    "EDIT: fix wording/typos/numbers -> edit_page_text (find/replace inside blocks, no node id needed). Change ONE block (paragraph/heading/callout/etc.) structurally -> patch_node (by attrs.id from get_outline). Add a block -> insert_node (before/after a block by attrs.id or by anchor text, or append). Remove a block -> delete_node (by attrs.id). Tables -> table_get / table_update_cell / table_insert_row / table_delete_row (address by \"#<index>\" from get_outline; table nodes have no attrs.id). Images -> insert_image (add from a web URL) / replace_image (swap an existing image). Footnotes -> insert_footnote. Bulk/structural rewrite -> update_page_json (full ProseMirror replace; prefer the granular tools above to avoid resending the whole ~100KB+ document). Complex/scripted rewrite (multiple coordinated edits, renumbering) -> docmost_transform: write a JS `(doc, ctx) => doc` transform, preview the diff with dryRun (default), then apply with dryRun:false; ctx.helpers includes commentsToFootnotes for turning inline comments into numbered footnotes.\n" +
+    "PAGES: new -> create_page (Markdown). Rename (title only) -> rename_page. Move -> move_page. Delete -> delete_page (SOFT delete — the page goes to trash and is restorable; nothing is permanent). Copy/replace a page's whole content from another page (server-side, no document through the model) -> copy_page_content. Sharing -> share_page / unshare_page / list_shares; share_page makes the page PUBLICLY accessible — do it only when explicitly asked.\n" +
+    "COMMENTS: create_comment is always inline and requires an EXACT selection — contiguous text from a single block, <=250 chars (fails rather than leaving an unanchored comment); reply to a thread via parentCommentId. Propose a concrete text fix for one-click human approval -> create_comment with suggestedText (the exact plain-text replacement for the selection; the selection must then be UNIQUE in the page — extend it with context if needed); prefer this over editing directly when the change is subjective or needs the author's sign-off. Manage -> list_comments, update_comment, resolve_comment (resolve/reopen, reversible — prefer over delete to close), delete_comment, check_new_comments.\n" +
+    "HISTORY: review what changed -> diff_page_versions (a historyId vs current, or two versions). List saved versions -> list_page_history. Undo a bad edit -> restore_page_version (writes a past version back as current; itself revertible). Lossless markdown round-trip (download, edit, re-upload, incl. comment anchors) -> export_page_markdown / import_page_markdown.";
 // Helper to format JSON responses
 const jsonContent = (data) => ({
    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -107,7 +116,9 @@ export function createDocmostMcpServer(config) {
    server.registerTool("get_page", {
        description: "Get page details with content converted to Markdown. The conversion is " +
            "LOSSY (block ids, exact table/callout structure are approximated); for a " +
-            "lossless representation use get_page_json.",
+            "lossless representation use get_page_json. Inline <span data-comment-id> " +
+            "tags in the markdown are comment highlight anchors (also present for " +
+            "RESOLVED threads) — treat them as markup, not page text.",
        inputSchema: {
            pageId: z.string().min(1),
        },
@@ -204,7 +215,8 @@ export function createDocmostMcpServer(config) {
    });
    // Tool: create_page
    server.registerTool("create_page", {
-        description: "Create a new page with content (automatically moves it to the correct hierarchy).",
+        description: "Create a new page from Markdown in a space. Pass parentPageId to nest " +
+            "it under a parent; omit it to create at the space root.",
        inputSchema: {
            title: z.string().min(1).describe("Title of the page"),
            content: z.string().min(1).describe("Markdown content"),
@@ -426,7 +438,8 @@ export function createDocmostMcpServer(config) {
    // agent; this transport keeps the plain public-URL wording.
    server.registerTool("share_page", {
        description: "Make a page publicly accessible (idempotent) and return its public " +
-            "URL. The URL format is <app>/share/<key>/p/<slugId>.",
+            "URL. The URL format is <app>/share/<key>/p/<slugId>. This exposes the " +
+            "page content to ANYONE with the URL — do it only when explicitly asked.",
        inputSchema: {
            pageId: z.string().min(1).describe("ID of the page to share"),
            searchIndexing: z
@@ -450,7 +463,7 @@ export function createDocmostMcpServer(config) {
    });
    // Tool: move_page
    server.registerTool("move_page", {
-        description: "Move a page to a new parent (nesting) or root. Essential for organizing pages created via 'create_page'.",
+        description: "Move a page under a new parent (nesting) or to the space root.",
        inputSchema: {
            pageId: z.string().min(1),
            parentPageId: z
@@ -486,7 +499,8 @@ export function createDocmostMcpServer(config) {
    });
    // Tool: delete_page
    server.registerTool("delete_page", {
-        description: "Delete a single page by ID.",
+        description: "Delete a single page by ID. SOFT delete only: the page is moved to " +
+            "trash and can be restored; nothing is permanently deleted.",
        inputSchema: {
            pageId: z.string().min(1),
        },
@@ -501,7 +515,9 @@ export function createDocmostMcpServer(config) {
    // --- Comment tools (ported from upstream PR #3 by Max Nikitin) ---
    // Tool: list_comments
    server.registerTool("list_comments", {
-        description: "List all comments on a page (paginated). Content is returned as Markdown.",
+        description: "List ALL comments on a page in one call (pagination is handled " +
+            "internally), including RESOLVED threads — filter by resolvedAt when you " +
+            "need only open ones. Content is returned as Markdown.",
        inputSchema: {
            pageId: z.string().describe("ID of the page"),
        },
@@ -652,8 +668,9 @@ export function createDocmostMcpServer(config) {
    // different schema (limit 1-20); this transport is a plain REST full-text search
    // (limit up to 100). Different behaviour AND schema, so kept per-layer.
    server.registerTool("search", {
-        description: "Search for pages and content. Results are bounded by `limit` " +
-            "(default applied by the client, max 100).",
+        description: "Full-text search for pages and content across the whole workspace. " +
+            "Results are bounded by `limit` (1-100; when omitted the server applies " +
+            "its own default).",
        inputSchema: {
            query: z.string().min(1).describe("Search query"),
            limit: z
@@ -703,7 +720,9 @@ export function createDocmostMcpServer(config) {
            "insertInlineFootnote(doc, {anchorText, text}) (author-inline footnote: " +
            "marker + dedup'd definition, list derived). Footnote convention: markers are " +
            "plain '[N]' text in the body; the notes are an orderedList under a " +
-            "heading whose text is 'Примечания переводчика'. The transform runs " +
+            "heading whose text is 'Примечания переводчика' (that is only the DEFAULT " +
+            "notesHeading — pass the notesHeading option to the helpers to use a " +
+            "heading matching the page's language). The transform runs " +
            "sandboxed (no require/process/fs/network, 5s timeout) and must return a " +
            "{type:'doc'} node.",
        inputSchema: {
@@ -13,6 +13,11 @@
 // diverge on purpose (security guardrails, tuned UX, "Reversible" framing on
 // some write tools, different limits, hybrid-RRF search, etc.) stay defined
 // per-layer and are NOT represented here.
+//
+// MAINTENANCE RULE: adding, renaming, or removing a spec here (or an inline
+// registerTool in index.ts) REQUIRES updating SERVER_INSTRUCTIONS in
+// packages/mcp/src/index.ts — the intent-routing guide MCP clients receive on
+// initialize. Enforced by test/unit/server-instructions.test.mjs.
 export const SHARED_TOOL_SPECS = {
    // --- no-argument read tools ---
    getWorkspace: {
@@ -73,8 +78,8 @@ export const SHARED_TOOL_SPECS = {
    deleteNode: {
        mcpName: 'delete_node',
        inAppKey: 'deleteNode',
-        description: 'Remove a single block by its attrs.id (from the page-JSON view) WITHOUT ' +
-            'resending the whole document.',
+        description: 'Remove a single block by its attrs.id (from the page outline or ' +
+            'page-JSON view) WITHOUT resending the whole document.',
        buildShape: (z) => ({
            pageId: z.string().min(1),
            nodeId: z.string().min(1),
@@ -94,7 +99,8 @@ export const SHARED_TOOL_SPECS = {
        inAppKey: 'patchNode',
        description: 'Replace a single content block identified by its attrs.id with a new ' +
            'ProseMirror node, WITHOUT resending the whole document; the replacement ' +
-            'keeps the same node id. Get the block id from the page-JSON view, then ' +
+            'keeps the same node id. Get the block id from the page outline (cheap) ' +
+            'or the page-JSON view, then ' +
            'pass a ProseMirror node to put in its place. Example node: a paragraph ' +
            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
            'heading {"type":"heading","attrs":{"level":2},"content":' +
@@ -123,7 +129,8 @@ export const SHARED_TOOL_SPECS = {
        description: 'Insert a block before/after another block (by attrs.id or anchor text) ' +
            'or append it at the end (top level). For before/after you MUST provide ' +
            'EXACTLY ONE of anchorNodeId or anchorText. Get anchor block ids from the ' +
-            'page-JSON view. Avoids resending the whole document. Can also insert ' +
+            'page outline or the page-JSON view. Avoids resending the whole document. ' +
+            'Can also insert ' +
            'table structure: to add a tableRow, pass a tableRow node with position ' +
            'before/after and anchor INSIDE the target table — anchorNodeId of any ' +
            'block/cell in it, or anchorText matching the table; to add a ' +
@@ -37,11 +37,20 @@ const VERSION = packageJson.version;

 // Editing guide surfaced to MCP clients in the initialize result so they can
 // pick the right tool by intent and avoid resending whole documents.
-const SERVER_INSTRUCTIONS =
-  "Docmost editing guide — choose the tool by intent: fix wording/typos/numbers (text inside blocks) -> edit_page_text (no node id needed). Change ONE block (paragraph/heading/callout/table cell/etc.) structurally -> patch_node (address by attrs.id from get_page_json). Add a block -> insert_node (before/after a block by attrs.id or by anchor text, or append). Remove a block -> delete_node (by attrs.id). Images -> insert_image (add an image from a web URL) / replace_image (swap an existing image for one from a web URL). New page -> create_page (Markdown). Bulk/structural rewrite or nodes without an id -> update_page_json (full ProseMirror replace; prefer the granular tools above to avoid resending the whole ~100KB+ document). Copy/replace a page's whole content from another page (server-side, no document through the model) -> copy_page_content. Rename a page (title only) -> rename_page. Read -> get_page (Markdown, lossy) or get_page_json (lossless ProseMirror with block ids). Comments -> create_comment (always inline; requires an EXACT selection — the contiguous text to anchor/highlight on; fails rather than leaving an unanchored comment), list_comments, update_comment, resolve_comment (resolve/reopen a thread, reversible — prefer over delete to close), delete_comment, check_new_comments. Propose a concrete text fix for one-click human approval -> create_comment with suggestedText (the exact plain-text replacement for the selection; the selection must then be UNIQUE in the page — extend it with context if needed); prefer this over editing directly when the change is subjective or needs the author's sign-off. Tip: read block ids via get_page_json, then use patch_node/insert_node/delete_node so you never resend the full document. " +
-  "Complex/scripted rewrite (multiple coordinated edits, footnotes, renumbering) -> docmost_transform: write a JS `(doc, ctx) => doc` transform, preview the diff with dryRun (default), then apply with dryRun:false; ctx.helpers includes commentsToFootnotes for turning inline comments into numbered footnotes. " +
-  "Review what changed -> diff_page_versions (compare a historyId to current, or two history versions). See a page's saved versions -> list_page_history. Undo a bad edit -> restore_page_version (writes a past version back as current; itself revertible). " +
-  "Lossless markdown round-trip (download, edit, re-upload, incl. comment anchors) -> export_page_markdown / import_page_markdown.";
+//
+// MAINTENANCE RULE: when you ADD, RENAME, or REMOVE a tool (either an inline
+// server.registerTool(...) here or a spec in tool-specs.ts), you MUST update
+// this guide so the new tool is routed by intent. This is enforced by
+// test/unit/server-instructions.test.mjs, which fails when a registered tool
+// name is not mentioned below (see its EXCEPTIONS list for the rare opt-outs).
+// Exported for that test.
+export const SERVER_INSTRUCTIONS =
+  "Docmost editing guide — choose the tool by intent.\n" +
+  "READ: find a page -> search (workspace-wide full-text); list -> list_pages / list_spaces. Locate blocks and their ids CHEAPLY -> get_outline (compact top-level map; start here, not get_page_json). One block's subtree -> get_node (by attrs.id, or \"#<index>\" for tables, which carry no id). Whole page -> get_page (Markdown, lossy; inline <span data-comment-id> tags are comment anchors — markup, not text) or get_page_json (lossless ProseMirror with block ids). Hand a huge page (with images) to an external consumer without pulling it through the model context -> stash_page (returns a short-lived anonymous URL).\n" +
+  "EDIT: fix wording/typos/numbers -> edit_page_text (find/replace inside blocks, no node id needed). Change ONE block (paragraph/heading/callout/etc.) structurally -> patch_node (by attrs.id from get_outline). Add a block -> insert_node (before/after a block by attrs.id or by anchor text, or append). Remove a block -> delete_node (by attrs.id). Tables -> table_get / table_update_cell / table_insert_row / table_delete_row (address by \"#<index>\" from get_outline; table nodes have no attrs.id). Images -> insert_image (add from a web URL) / replace_image (swap an existing image). Footnotes -> insert_footnote. Bulk/structural rewrite -> update_page_json (full ProseMirror replace; prefer the granular tools above to avoid resending the whole ~100KB+ document). Complex/scripted rewrite (multiple coordinated edits, renumbering) -> docmost_transform: write a JS `(doc, ctx) => doc` transform, preview the diff with dryRun (default), then apply with dryRun:false; ctx.helpers includes commentsToFootnotes for turning inline comments into numbered footnotes.\n" +
+  "PAGES: new -> create_page (Markdown). Rename (title only) -> rename_page. Move -> move_page. Delete -> delete_page (SOFT delete — the page goes to trash and is restorable; nothing is permanent). Copy/replace a page's whole content from another page (server-side, no document through the model) -> copy_page_content. Sharing -> share_page / unshare_page / list_shares; share_page makes the page PUBLICLY accessible — do it only when explicitly asked.\n" +
+  "COMMENTS: create_comment is always inline and requires an EXACT selection — contiguous text from a single block, <=250 chars (fails rather than leaving an unanchored comment); reply to a thread via parentCommentId. Propose a concrete text fix for one-click human approval -> create_comment with suggestedText (the exact plain-text replacement for the selection; the selection must then be UNIQUE in the page — extend it with context if needed); prefer this over editing directly when the change is subjective or needs the author's sign-off. Manage -> list_comments, update_comment, resolve_comment (resolve/reopen, reversible — prefer over delete to close), delete_comment, check_new_comments.\n" +
+  "HISTORY: review what changed -> diff_page_versions (a historyId vs current, or two versions). List saved versions -> list_page_history. Undo a bad edit -> restore_page_version (writes a past version back as current; itself revertible). Lossless markdown round-trip (download, edit, re-upload, incl. comment anchors) -> export_page_markdown / import_page_markdown.";

 // Helper to format JSON responses
 const jsonContent = (data: any) => ({
@@ -147,7 +156,9 @@ server.registerTool(
    description:
      "Get page details with content converted to Markdown. The conversion is " +
      "LOSSY (block ids, exact table/callout structure are approximated); for a " +
-      "lossless representation use get_page_json.",
+      "lossless representation use get_page_json. Inline <span data-comment-id> " +
+      "tags in the markdown are comment highlight anchors (also present for " +
+      "RESOLVED threads) — treat them as markup, not page text.",
    inputSchema: {
      pageId: z.string().min(1),
    },
@@ -288,7 +299,8 @@ server.registerTool(
  "create_page",
  {
    description:
-      "Create a new page with content (automatically moves it to the correct hierarchy).",
+      "Create a new page from Markdown in a space. Pass parentPageId to nest " +
+      "it under a parent; omit it to create at the space root.",
    inputSchema: {
      title: z.string().min(1).describe("Title of the page"),
      content: z.string().min(1).describe("Markdown content"),
@@ -587,7 +599,8 @@ server.registerTool(
  {
    description:
      "Make a page publicly accessible (idempotent) and return its public " +
-      "URL. The URL format is <app>/share/<key>/p/<slugId>.",
+      "URL. The URL format is <app>/share/<key>/p/<slugId>. This exposes the " +
+      "page content to ANYONE with the URL — do it only when explicitly asked.",
    inputSchema: {
      pageId: z.string().min(1).describe("ID of the page to share"),
      searchIndexing: z
@@ -619,7 +632,7 @@ server.registerTool(
  "move_page",
  {
    description:
-      "Move a page to a new parent (nesting) or root. Essential for organizing pages created via 'create_page'.",
+      "Move a page under a new parent (nesting) or to the space root.",
    inputSchema: {
      pageId: z.string().min(1),
      parentPageId: z
@@ -675,7 +688,9 @@ server.registerTool(
 server.registerTool(
  "delete_page",
  {
-    description: "Delete a single page by ID.",
+    description:
+      "Delete a single page by ID. SOFT delete only: the page is moved to " +
+      "trash and can be restored; nothing is permanently deleted.",
    inputSchema: {
      pageId: z.string().min(1),
    },
@@ -697,7 +712,9 @@ server.registerTool(
  "list_comments",
  {
    description:
-      "List all comments on a page (paginated). Content is returned as Markdown.",
+      "List ALL comments on a page in one call (pagination is handled " +
+      "internally), including RESOLVED threads — filter by resolvedAt when you " +
+      "need only open ones. Content is returned as Markdown.",
    inputSchema: {
      pageId: z.string().describe("ID of the page"),
    },
@@ -913,8 +930,9 @@ server.registerTool(
  "search",
  {
    description:
-      "Search for pages and content. Results are bounded by `limit` " +
-      "(default applied by the client, max 100).",
+      "Full-text search for pages and content across the whole workspace. " +
+      "Results are bounded by `limit` (1-100; when omitted the server applies " +
+      "its own default).",
    inputSchema: {
      query: z.string().min(1).describe("Search query"),
      limit: z
@@ -970,7 +988,9 @@ server.registerTool(
      "insertInlineFootnote(doc, {anchorText, text}) (author-inline footnote: " +
      "marker + dedup'd definition, list derived). Footnote convention: markers are " +
      "plain '[N]' text in the body; the notes are an orderedList under a " +
-      "heading whose text is 'Примечания переводчика'. The transform runs " +
+      "heading whose text is 'Примечания переводчика' (that is only the DEFAULT " +
+      "notesHeading — pass the notesHeading option to the helpers to use a " +
+      "heading matching the page's language). The transform runs " +
      "sandboxed (no require/process/fs/network, 5s timeout) and must return a " +
      "{type:'doc'} node.",
    inputSchema: {
@@ -13,6 +13,11 @@
 // diverge on purpose (security guardrails, tuned UX, "Reversible" framing on
 // some write tools, different limits, hybrid-RRF search, etc.) stay defined
 // per-layer and are NOT represented here.
+//
+// MAINTENANCE RULE: adding, renaming, or removing a spec here (or an inline
+// registerTool in index.ts) REQUIRES updating SERVER_INSTRUCTIONS in
+// packages/mcp/src/index.ts — the intent-routing guide MCP clients receive on
+// initialize. Enforced by test/unit/server-instructions.test.mjs.

 // Loose on purpose — see the comment above. The two zod majors expose different
 // static type surfaces, so typing this precisely would couple the registry to
@@ -111,8 +116,8 @@ export const SHARED_TOOL_SPECS = {
    mcpName: 'delete_node',
    inAppKey: 'deleteNode',
    description:
-      'Remove a single block by its attrs.id (from the page-JSON view) WITHOUT ' +
-      'resending the whole document.',
+      'Remove a single block by its attrs.id (from the page outline or ' +
+      'page-JSON view) WITHOUT resending the whole document.',
    buildShape: (z) => ({
      pageId: z.string().min(1),
      nodeId: z.string().min(1),
@@ -134,7 +139,8 @@ export const SHARED_TOOL_SPECS = {
    description:
      'Replace a single content block identified by its attrs.id with a new ' +
      'ProseMirror node, WITHOUT resending the whole document; the replacement ' +
-      'keeps the same node id. Get the block id from the page-JSON view, then ' +
+      'keeps the same node id. Get the block id from the page outline (cheap) ' +
+      'or the page-JSON view, then ' +
      'pass a ProseMirror node to put in its place. Example node: a paragraph ' +
      '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
      'heading {"type":"heading","attrs":{"level":2},"content":' +
@@ -169,7 +175,8 @@ export const SHARED_TOOL_SPECS = {
      'Insert a block before/after another block (by attrs.id or anchor text) ' +
      'or append it at the end (top level). For before/after you MUST provide ' +
      'EXACTLY ONE of anchorNodeId or anchorText. Get anchor block ids from the ' +
-      'page-JSON view. Avoids resending the whole document. Can also insert ' +
+      'page outline or the page-JSON view. Avoids resending the whole document. ' +
+      'Can also insert ' +
      'table structure: to add a tableRow, pass a tableRow node with position ' +
      'before/after and anchor INSIDE the target table — anchorNodeId of any ' +
      'block/cell in it, or anchorText matching the table; to add a ' +
@@ -0,0 +1,82 @@
+// Guard: every tool the MCP server registers must be routed by intent in
+// SERVER_INSTRUCTIONS — the editing guide clients receive in the initialize
+// result. Without this, new tools silently rot out of the guide and agents
+// never learn to pick them (the guide once omitted 17 of 41 tools, including
+// get_outline, which pushed agents into fetching whole documents for block
+// ids). Tool names are extracted from the SOURCE (index.ts inline
+// registrations + tool-specs.ts shared specs) so a registration added either
+// way is caught; the guide text itself is imported from the build so the test
+// checks what actually ships.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { SERVER_INSTRUCTIONS } from "../../build/index.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SRC = join(HERE, "..", "..", "src");
+
+// Tools DELIBERATELY absent from the guide. Keep this list minimal and
+// justify every entry — the default is: every tool gets routed.
+const EXCEPTIONS = new Set([
+  // Trivial and self-explanatory; carries no routing decision.
+  "get_workspace",
+]);
+
+/**
+ * Extract every registered tool name from the source. Two registration
+ * mechanisms exist and both are covered:
+ *  - inline `server.registerTool("name", ...)` calls in index.ts;
+ *  - shared specs in tool-specs.ts (`mcpName: 'name'`), registered via
+ *    registerShared(SHARED_TOOL_SPECS.x, ...).
+ */
+function registeredToolNames() {
+  const indexSrc = readFileSync(join(SRC, "index.ts"), "utf8");
+  const specsSrc = readFileSync(join(SRC, "tool-specs.ts"), "utf8");
+  const names = new Set();
+  for (const m of indexSrc.matchAll(/registerTool\(\s*"([a-z0-9_]+)"/g)) {
+    names.add(m[1]);
+  }
+  for (const m of specsSrc.matchAll(/mcpName:\s*['"]([a-z0-9_]+)['"]/g)) {
+    names.add(m[1]);
+  }
+  return names;
+}
+
+test("every registered tool is mentioned in SERVER_INSTRUCTIONS", () => {
+  const names = registeredToolNames();
+  // Sanity: if extraction regressed (regex drift), fail loudly rather than
+  // vacuously passing on an empty set.
+  assert.ok(
+    names.size >= 40,
+    `sanity: expected to extract 40+ registered tools, got ${names.size} — ` +
+      "the extraction regexes in this test likely drifted from the source",
+  );
+  const missing = [...names]
+    .filter((n) => !EXCEPTIONS.has(n))
+    // \b<name>\b: `_` is a word char, so \bget_page\b does NOT match inside
+    // get_page_json — a tool can't hide behind a longer sibling's mention.
+    .filter((n) => !new RegExp(`\\b${n}\\b`).test(SERVER_INSTRUCTIONS))
+    .sort();
+  assert.deepEqual(
+    missing,
+    [],
+    `tools missing from SERVER_INSTRUCTIONS: ${missing.join(", ")} — ` +
+      "update the guide in packages/mcp/src/index.ts (see its MAINTENANCE " +
+      "RULE comment), or add a justified entry to EXCEPTIONS here",
+  );
+});
+
+test("EXCEPTIONS entries are real registered tools", () => {
+  // A stale exception (tool renamed/removed) must be cleaned up, otherwise
+  // the list quietly grows past its purpose.
+  const names = registeredToolNames();
+  for (const name of EXCEPTIONS) {
+    assert.ok(
+      names.has(name),
+      `EXCEPTIONS entry "${name}" is not a registered tool — remove it`,
+    );
+  }
+});
@@ -335,6 +335,9 @@ importers:
      clsx:
        specifier: 2.1.1
        version: 2.1.1
+      diff:
+        specifier: 8.0.3
+        version: 8.0.3
      dompurify:
        specifier: 3.4.1
        version: 3.4.1
Author	SHA1	Message	Date
claude code agent 227	94f60cf0ec	docs(client): fix .suggestionChanged comment — bold weight, not underline (#331 review F1) The header comment claimed the rule adds 'an underline'; it does not — it adds a color-mix tint + font-weight:700, and the inner comment already notes text- decoration is omitted on purpose. Aligned the header comment with the rule. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-04 16:21:25 +03:00
claude code agent 227	f13105333a	feat(client): intraline diff highlighting in the suggestion before→after block (#331 ) The suggestion block (#315) struck the whole `selection` red and showed the whole `suggestedText` green, so a one-letter edit (заведем→заведём) highlighted the entire line. Now only the CHANGED fragments are emphasized intraline, git-style. Pure, render-only — nothing changes in the DB/backend/MCP/IComment/mutations/ Apply/Badge. New pure `computeSuggestionDiff(old, new) => { old: Segment[], new: Segment[] }` (Segment = {text, changed}) in suggestion.ts: hybrid word+char — `diffWordsWithSpace` for the word skeleton, then `diffChars` inside an adjacent removed+added pair so only the differing letters (not the whole word) are flagged; a lone insertion/deletion is wholly changed; equal parts are common on both sides. Concatenating each side reproduces the input (lossless). Wrapped in `useMemo` on [selection, suggestedText]. comment-list-item.tsx renders per-segment spans instead of two whole <Text>; changed segments get `.suggestionChanged` (a stronger currentColor tint + bold, NO text-decoration so the old block's inherited line-through survives on the changed letters — the whole old line still reads removed, new as added). `diff@8.0.3` (jsdiff, already in the root package.json) added to apps/client/package.json (+ lockfile, additive) so the workspace resolves it; it bundles its own types. Tests: new suggestion.test.ts (one-letter ё/е; word replacement keeping the shared word common with no per-letter noise; word insertion/deletion; identical) — asserts segment text + changed flags, non-vacuous. Two pre-existing comment-list-item.test assertions switched from getByText (a single text node) to container.textContent (the new line is now multiple spans) — adapts to the intended DOM change, not a weakening. Verified: tsc --noEmit clean; client vitest 892 passed \| 1 expected-fail. Visual/pixel check of the tint at the 390px comment panel needs a human (no screenshot tooling in-repo). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-04 15:17:07 +03:00
vvzvlad	f5d19f9728	Merge pull request 'build(git-sync): пакет @docmost/git-sync в develop, code-only (#326 step 1 / PR-A)' (#327 ) from feat/293-A-git-sync-package into develop Reviewed-on: #327	2026-07-04 07:02:25 +03:00
agent_vscode	351615e5bc	prompt(mcp): fix inaccurate and misleading tool descriptions Audit of all 41 tool descriptions against the actual implementation found factually wrong or misleading texts: - list_comments claimed '(paginated)' — it takes only pageId and returns ALL comments in one call (internal pagination); now also states that RESOLVED threads are included and how to filter them. In-app twin synced. - search claimed the limit default is 'applied by the client' — the client deliberately omits it so the SERVER applies its default. - create_page's '(automatically moves it to the correct hierarchy)' said nothing useful — now documents parentPageId nesting semantics; move_page drops the stale 'essential for organizing pages created via create_page'. - share_page now warns the page becomes accessible to ANYONE with the URL. - get_page (both transports) now explains inline <span data-comment-id> tags are comment anchors (incl. resolved) — markup, not page text. - patch_node/delete_node/insert_node pointed only at the expensive page-JSON view for block ids — now route through the cheap page outline first. - docmost_transform marks 'Примечания переводчика' as the DEFAULT notesHeading, overridable for non-Russian pages. Checks: @docmost/mcp tests 450/450 (incl. the server-instructions guard); server ai-chat-tools spec 20/20; mcp build/ artifacts rebuilt. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-04 07:00:16 +03:00
agent_vscode	1fda0ec8b0	prompt(mcp): rewrite SERVER_INSTRUCTIONS to cover all tools + guard test The intent-routing guide had rotted: 17 of 41 registered tools were absent (get_outline, get_node, the whole table_* family, search, stash_page, sharing, page lifecycle), and two tips were actively harmful — 'read block ids via get_page_json' told agents to pull the whole ~100KB document when get_outline exists precisely to grab ids cheaply, and 'table cell -> patch_node by attrs.id' dead-ends because table nodes carry no attrs.id. - Rewrite SERVER_INSTRUCTIONS as intent clusters (READ / EDIT / PAGES / COMMENTS / HISTORY) covering every tool except get_workspace; add safety notes (share_page = PUBLIC, delete_page = soft) and a comment-anchor markup warning for get_page. - delete_page tool description: state SOFT delete / restorable explicitly. - MAINTENANCE RULE comments at both registration sites (index.ts, tool-specs.ts) + an AGENTS.md convention bullet: adding/renaming/removing a tool REQUIRES updating the guide. - New guard test (test/unit/server-instructions.test.mjs): extracts every registered tool name from source and fails when one is not mentioned in the shipped SERVER_INSTRUCTIONS (word-boundary match, so get_page can't hide behind get_page_json); EXCEPTIONS list is itself validated against the registry. SERVER_INSTRUCTIONS exported for the test. Tests: @docmost/mcp 450/450 (448 + 2 new). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-04 06:51:01 +03:00
agent_vscode	2637640291	prompt(agents): drop the role-name label prefix from comments (#315 ) Chat now shows the agent's name in the comment header, so the '[Copyedit]' / '[Structure]' / '[Style]' / '[Facts]' prefix each role prepended just duplicated the visible author. - Remove the 'open the comment with the label [Role]' instruction from all four labelled roles (structural-editor, line-editor, fact-checker, proofreader), ru + en; the narrator was already label-free. - Severity tags ([Critical]/[Major]/[Minor]) and the fact-checker's verdicts ([Incorrect]/[Unverified]/…) are kept — they carry meaning, not the role name. - Versions bumped: structural-editor 3->4, line-editor 3->4, fact-checker 4->5, proofreader 6->7; content-hash lock refreshed. Check: agent-roles-catalog check.mjs OK. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-04 06:08:12 +03:00
agent_vscode	aa0428e28b	prompt(agents): make the copyeditor exhaustive in one pass (#315 ) The copyeditor had to be re-run several times to surface all issues: it has no 'work the whole document' instruction (unlike the developmental editor and the narrator), and the severity labels nudge it toward reporting only the salient few. - Add a HOW TO WORK section (ru + en): one pass over the whole text start to finish; flag EVERY violation including all repeat occurrences and [Minor] items; don't summarize instead of marking up; one run covers the whole text, not just 'the most important'. - proofreader version 5 -> 6, content-hash lock refreshed. Check: agent-roles-catalog check.mjs OK. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-04 05:50:39 +03:00