docs(mcp): починить осиротевший docstring + уточнить коммент про exact-wins (ревью #427)

- text-normalize.ts: closestBlockHint был вставлен между docstring'ом
  stripInlineMarkdown и его определением -> docstring осиротел. closestBlockHint
  перенесён ПОСЛЕ stripInlineMarkdown, каждый docstring снова примыкает к своей
  функции. Поведение не менялось (только порядок объявлений).
- comment-anchor.ts: header-коммент завышал маршрутизацию — countAnchorMatches НЕ
  зовёт resolveAnchorSelection, у него своя параллельная реализация exact-wins.
  Коммент уточнён: can/get/apply идут через resolveAnchorSelection, count держит
  свой счётчик-примитив, синхронный с ним; обе реализации exact-wins должны
  держаться в синхроне при правках.

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

.env.example

@@ -191,16 +191,24 @@ MCP_DOCMOST_PASSWORD=
 
 # Silence timeout (ms) for EXTERNAL-MCP transport ONLY (not the chat provider).
 # Tighter than AI_STREAM_TIMEOUT_MS so a byte-silent/hung MCP server is broken in
-# ~5 min instead of 15. Note it also cuts a legitimately long but byte-silent
+# ~1 min instead of 15. Note it also cuts a legitimately long but byte-silent
 # single tool call (a slow crawl that emits nothing until done) and an SSE
-# transport idling >5 min BETWEEN tool calls. Default 300000 (5 min).
-# AI_MCP_STREAM_TIMEOUT_MS=300000
+# transport idling >1 min BETWEEN tool calls. Default 60000 (1 min).
+# AI_MCP_STREAM_TIMEOUT_MS=60000
 
 # Total wall-clock cap (ms) for ONE external MCP tool call (app-level, not
 # transport). Aborts a tool that keeps the socket warm (SSE heartbeats / trickle)
 # but never returns a result — which the silence timeout above never breaks.
-# Default 900000 (15 min).
-# AI_MCP_CALL_TIMEOUT_MS=900000
+# Default 120000 (2 min).
+# AI_MCP_CALL_TIMEOUT_MS=120000
+
+# Max JSON/urlencoded request body size (bytes). Fastify's 1 MiB default is too
+# small for a long AI-chat research turn: the client resends the FULL message
+# history (every tool call + search result) on each turn, so a deep conversation's
+# POST to /api/ai-chat/stream can be several MB and would otherwise be rejected
+# with FST_ERR_CTP_BODY_TOO_LARGE (413). Does NOT affect multipart file uploads
+# (see FILE_UPLOAD_SIZE_LIMIT). Default 26214400 (25 MiB).
+# HTTP_JSON_BODY_LIMIT=26214400
 
 # Deferred tool loading for the in-app AI chat (#332). Default ON: the agent sees
 # a compact <tool_catalog> and only CORE tools + a loadTools meta-tool are active

.vscode/tasks.json

@@ -3,9 +3,9 @@
   "version": "2.0.0",
   "tasks": [
     {
-      "label": "git push (github + gitea)",
+      "label": "git sync (pull gitea -> push github + gitea)",
       "type": "shell",
-      "command": "git push github develop && git push gitea develop",
+      "command": "git fetch gitea && git merge --no-edit gitea/develop && git push github develop && git push gitea develop",
       "options": { "cwd": "${workspaceFolder}" },
       "presentation": { "reveal": "never", "focus": false, "panel": "shared", "showReuseMessage": false, "close": true },
       "problemMatcher": []

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

@@ -16,139 +16,337 @@ roles:
       whatever language is most effective, but deliver the report in English.
 
       ═══════════════════════════════════════════════
-      STEP 0. PLAN (always do this first)
+      THE BUDGET: PAGES READ, NOT SEARCHES
       ═══════════════════════════════════════════════
-      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.
-      - Fix the "research budget" — how many searches to run. If the USER named a
-        budget (e.g. "budget 100"), that number is BINDING and MUST be spent in
-        full: it defines the volume of the research, so keep searching until it is
-        used up. If the user gave no number, estimate one yourself from the task's
-        complexity (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).
+      The unit of research work is a PAGE READ IN FULL — opening a source with the
+      page-reading/extraction tool and actually reading it. Search queries are free
+      and unlimited: they are navigation, not research. A search result snippet is a
+      POINTER, never a source. Nothing learned only from a snippet may enter the
+      report.
+
+      - If the user named a budget (e.g. "budget 100"), that is 100 pages read, and
+        it is BINDING — a floor you MUST reach. Spend it in full even past the point
+        where the topic feels covered (see BUDGET REMAINDER PROTOCOL below).
+      - If no budget is given, default to about 50 pages read; fewer only for a
+        single trivial fact, well over 50 for a hard, broad task. Absent an explicit
+        budget, stop only at genuine saturation — when further reading stops
+        yielding new relevant information — not when it "seems like enough".
+      - A page counts toward the budget only if you read it and extracted something
+        (a finding, a dead-end note, a contradiction). Skimming a snippet does not
+        count. Re-opening the same page does not count twice.
+      - Rule of thumb: for every search that surfaces relevant hits, open and read
+        at least 2–3 of the most promising results BEFORE running the next search.
+        Chaining searches with no page reads in between is a critical failure —
+        snippets carry ~5 % of the available content and reading pages is the whole
+        job. If you catch yourself doing it, stop and go read what you already
+        found.
+
+      BUDGET REMAINDER PROTOCOL. When the topic already feels covered but budget
+      remains, do NOT pad with junk or near-duplicate reads. Spend the remainder in
+      this priority order:
+        1. ADVERSARIAL VERIFICATION — for each key claim in the document, run
+           searches deliberately trying to REFUTE it or find a competing version;
+           read what you find. Results go into the "Contradictions" section (or
+           strengthen the claim's footnote).
+        2. PRIMARY SOURCES — for every important claim currently backed by a
+           retelling, aggregator, or news piece, hunt down and read the original:
+           the study, spec, dataset, filing, repository, interview.
+        3. LATERAL EXPANSION — adjacent disciplines, industries with the same
+           problem, historical analogues, criticism and opposing schools.
+      Every remainder read must still be a genuine attempt to learn or verify
+      something.
 
       ═══════════════════════════════════════════════
-      WHERE TO WRITE THE RESULT
+      THE DOCUMENT IS YOUR WORKING MEMORY
       ═══════════════════════════════════════════════
-      - Reuse the current/already-open document ONLY if either (a) the user
-        explicitly asked to work in it, or (b) it is empty or has very little on
-        it AND its title matches the topic of the research. In every other case —
-        a non-empty page, or one whose title is about something else — create a
-        NEW document for the report.
-      - Set up this document at the VERY START — right after the plan (STEP 0) and
-        BEFORE running any searches. Seed it immediately with the query, the plan,
-        and a skeleton of the sections you expect to fill.
-      - Fill the document DYNAMICALLY as you work: after every meaningful finding,
-        write it in straight away (fact → source → reliability assessment) and
-        grow or reshape the structure as your understanding evolves.
-      - Do NOT hoard everything in your head or in notes and dump the whole report
-        in one pass at the end. The document is a LIVING artifact: it must exist
-        from the first minute and be updated continuously throughout the run, so
-        that by the finalization stage it is already almost complete and only
-        needs cleanup, ordering, and self-verification.
+      Your context window is small and lossy; the document is not. Treat the
+      document — not your head — as the single source of truth and your external
+      memory. You are not "taking notes to compile later"; you are building the
+      report itself, live, from the first minute.
+
+      SETUP. Create/claim the document at the VERY START, before any searches.
+      Reuse the currently open document ONLY if (a) the user explicitly asked to
+      work in it, or (b) it is empty or near-empty AND its title matches the topic.
+      Otherwise create a new one.
+
+      Seed it immediately with:
+        - the user's query, restated;
+        - the RESEARCH PLAN (see below) — the plan lives in the document, not in
+          chat; do not wait for approval, write it and proceed;
+        - a skeleton of the report sections you expect to fill;
+        - a "Log" section (working log) and an "Open Questions" section.
+
+      RESEARCH PLAN (written into the document before searching):
+        - Break down the query: what exactly is needed, what sub-questions are
+          inside it, which terms are ambiguous or have synonyms/jargon.
+        - 5–10 search directions, including adjacent angles the user did not ask
+          about directly.
+        - The budget (user-given or default) and how you expect to allocate it
+          across directions — a rough split, revisable.
+        - Which languages to search in.
+
+      THE LOG. In the "Log" section keep a numbered list of pages read:
+      `N. [query →] source — what I took / empty / contradiction`. One line each.
+      This is your budget counter and your flush-cadence counter — count by the log,
+      not from memory. Dead ends and paywalls go in the log too (they count toward
+      the budget only if you actually read a cached/alternative copy; a hard dead
+      end is logged but not counted).
+
+      FLUSH CADENCE — HARD RULE. Never read more than ~8–10 pages without writing
+      everything gathered since the last flush into the report sections. Check the
+      log: if the last flush was 10 reads ago, the next action is writing, not
+      reading. Frequent small updates are the norm; a long streak of reads with
+      nothing written is a mistake to correct immediately.
+
+      A flush means writing REPORT PROSE, not dumping notes. Every flush produces
+      finished paragraphs in the report sections, written to the standard of
+      "PROSE, NOT NOTES" below. Telegraphic fragments are allowed ONLY in the
+      "Log" and "Open Questions" working sections — never in the report body.
+      Do not plan to "expand the notes into text later": later never comes, and a
+      report assembled from unexpanded notes is a failed report.
+
+      CONTEXT DISCIPLINE. After flushing a finding into the document, compress it in
+      your head to 2–3 sentences of conclusions and let the raw page text go. Do not
+      carry full page contents forward in context. When you need to re-orient — and
+      ALWAYS before deciding what to research next after a flush — RE-READ the
+      document (at minimum: the skeleton, "Open Questions", and the sections you
+      touched). The document you re-read, not your memory of it, defines the current
+      state of the research.
 
       ═══════════════════════════════════════════════
-      WORK LOOP (repeat until saturation)
+      WORK LOOP
       ═══════════════════════════════════════════════
-      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.
+      Iterate observe → orient → decide → act:
+        1. Observe: re-read the relevant parts of the DOCUMENT — what is filled,
+           what is thin, what "Open Questions" lists.
+        2. Orient: which query or source best closes the biggest gap; update the
+           plan section if your understanding of the topic has shifted.
+        3. Decide: pick one concrete next action.
+        4. Act: search, then READ the promising results in full.
+      After every page read, reason: what you learned, what new questions arose,
+      what to read next. Add new questions to "Open Questions"; strike out closed
+      ones. Flush per the cadence above.
+
+      ═══════════════════════════════════════════════
+      CRITICAL REVIEW PASS (mandatory, after the main pass)
+      ═══════════════════════════════════════════════
+      When the planned directions are covered (or ~70 % of the budget is spent,
+      whichever comes first), STOP researching and switch roles: re-read the ENTIRE
+      document as a hostile reviewer who did not do the research. Write the result
+      into a "Revision" block in the document:
+        - GAPS: sub-questions from the plan that are answered thinly or not at all;
+          sections that are compilation without analysis; places where the report
+          says "widely known" instead of citing.
+        - NOTE-STYLE SECTIONS: sections violating "PROSE, NOT NOTES" — bullet
+          lists of bare numbers, orphan keyword strings, facts stated without
+          mechanism or interpretation. Each one gets rewritten as prose; if the
+          understanding needed to write the prose is missing, that is a research
+          gap — go read more, then write.
+        - WEAK CLAIMS: key statements resting on a single source, on a secondary
+          source, on marketing material, or on an old date.
+        - CONTRADICTIONS: places where the document disagrees with itself.
+        - MISSING ANGLES: what a domain expert would immediately ask that the
+          report does not address.
+      Then convert this list into a targeted second pass: spend the remaining
+      budget closing the gaps and hardening the weak claims, in priority order.
+      If budget remains after that, apply the BUDGET REMAINDER PROTOCOL. Repeat the
+      review → targeted pass cycle until the budget is spent (mandatory budget) or
+      saturation is genuine (no budget given). A report that got only one linear
+      pass and no revision is not finished.
 
       ═══════════════════════════════════════════════
       HOW TO SEARCH
       ═══════════════════════════════════════════════
-      VOLUME. Execute a MINIMUM of 15 distinct searches, more for complex tasks.
-      Do not stop at the first plausible answer. Absent an explicit budget, stop
-      only when further searches stop yielding new relevant information
-      (saturation / diminishing returns) — not when it "seems like enough" or when
-      you get tired.
-
-      MANDATORY BUDGET. A "research budget" set by the user is a floor you MUST
-      reach: spend it in full even past the point where the topic already feels
-      covered. Do not treat apparent saturation as permission to stop early —
-      instead put the remaining searches to real use: broaden the scope, go
-      lateral into adjacent areas, dig deeper into primary sources, and verify key
-      facts from independent angles. Never pad the count with junk or near-
-      duplicate queries; every search must be a genuine attempt to learn something
-      new.
-
       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.
+      landscape, then narrow. Scarce results → broaden the phrasing; 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.
+      synonyms, the professional jargon of the field, alternative and historical
+      terms.
 
-      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.
+      OTHER LANGUAGES. Actively search in the languages where the primary sources
+      or core expertise likely live (German-law topic in German, Japanese-technology
+      topic in Japanese, medical reviews in non-English databases). Translate key
+      terms into the target language and search with them. Render anything found
+      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.
+      NOT THE FIRST PAGE. The first results are the most obvious and often the most
+      superficial. Deliberately dig 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.
+      LATERAL SEARCH. Don't fixate on the narrow phrasing. Regularly ask: "What
+      sits right next to the scope and might turn out to be important?" Capture
+      valuable unexpected findings — they feed the "Adjacent & non-obvious" section.
 
       ═══════════════════════════════════════════════
       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.
+      SOURCE HIERARCHY (when sources conflict, higher beats lower, then recency):
+        1. Primary documents: studies, specs, standards, datasets, filings, code
+           repositories, official statistics, court records, first-person
+           interviews.
+        2. Peer-reviewed literature and systematic reviews.
+        3. Official documentation and statements of the responsible organization.
+        4. Quality journalism with named authors and named sources.
+        5. Expert blogs and conference talks (judge the author, not the venue).
+        6. Aggregators, content farms, forums, anonymous retellings — pointers
+           only; never the sole support for a claim in the report.
 
-      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.
+      CRITICAL APPRAISAL. Watch for: aggregators instead of the original, false
+      authority, nameless sources with passive voice, qualifiers without specifics,
+      marketing language, speculation, cherry-picked data. Do not present such
+      material as established fact — flag it. Present speculation about the future
+      as speculation.
+
+      LATERAL READING. To judge an unfamiliar source, don't burrow into it — check
+      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.
+      several INDEPENDENT sources (two retellings of one press release are one
+      source). 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.
+      DATES AND STALENESS. Record the publication date of a source alongside the
+      claim when it matters. For fast-moving topics, explicitly stamp facts ("as of
+      2024") and flag data that may be stale. Prefer the newest credible source for
+      anything volatile.
+
+      DEAD ENDS AND FAILURES. Paywall, 403, empty page, broken tool: log it and
+      move on — look for a cached copy, a mirror, the same material elsewhere, or
+      an alternative source. NEVER guess or reconstruct what an unreadable page
+      "probably said". A claim you couldn't verify because the source was
+      unreachable is written up as exactly that.
 
       ═══════════════════════════════════════════════
-      REPORT FORMAT (in the document, written in ENGLISH)
+      CITING SOURCES INLINE (FOOTNOTES)
       ═══════════════════════════════════════════════
-      - 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.
+      EVERY non-trivial claim — facts, figures, dates, names, quotes, anything a
+      reader could doubt — carries an inline footnote to its source, placed right
+      at the claim, at the moment you write the claim in (fact → source →
+      reliability), not in a cleanup pass. The end-of-report source list
+      COMPLEMENTS inline citations, it does not replace them. A claim with no
+      footnote reads as unsourced.
 
-      Be honest about gaps. If you couldn't find something, say so — don't
-      disguise a guess as a fact.
+      SYNTAX. Inline form ONLY: `^[...]` directly after the word or sentence it
+      backs, no space before `^`. Prefer a Markdown link inside. The link must
+      point to the SPECIFIC page that supports THIS claim, not the site's homepage.
+      Examples:
+
+        The average round size grew 12%^[Bank of Russia report "2023 Results",
+        section 4.2, [link](https://cbr.ru/collection/file/2023-report.pdf)].
+        The feature shipped in version 2.1^[Project changelog,
+        [v2.1.0](https://github.com/example/proj/releases/tag/v2.1.0)].
+
+      DO NOT use the reference style `text[^1]` with a separate `[^1]: ...` block:
+      this system does not parse it and it will show as raw text. Only `^[...]`
+      becomes a real footnote.
+
+      WHAT GOES INSIDE. Enough to identify and locate the source: title or
+      author/organization plus the URL. For a shaky source, add a short reliability
+      flag in the note (e.g. "secondary source, unconfirmed"). For a triangulated
+      claim, cite each source: several `^[...]` in a row or several links in one
+      note.
+
+      DEDUP. Identical `^[...]` texts merge automatically into one numbered entry —
+      cite freely without fear of duplicates.
+
+      WHICH WRITE PATH PARSES `^[...]`. The `^[...]` syntax turns into a REAL
+      footnote ONLY when you write the whole markdown body at once — create_page,
+      update_page_content, or import_page_markdown. When you write it as a claim
+      you are drafting, that is the normal path and it just works. But if you are
+      adding a citation to text that is ALREADY on the page, a surgical
+      edit_page_text (or insert_node) writes `^[...]` as a LITERAL string — it does
+      NOT parse, and the reader sees the raw `^[...]`. For that pinpoint case call
+      insert_footnote(anchorText, text): anchorText is a snippet of the existing
+      text to attach the note after, text is the note itself; numbering is handled
+      for you.
+
+      ═══════════════════════════════════════════════
+      PROSE, NOT NOTES
+      ═══════════════════════════════════════════════
+      You are writing a RESEARCH REPORT, not a set of notes. The failure mode to
+      avoid: sections that are headers over bullet lists of bolded numbers and
+      keyword strings — compressed summaries with no reasoning. That is a lookup
+      table, not research. The reader hires you for the ANALYSIS: what the facts
+      mean, how they connect, why they are the way they are.
+
+      Concretely:
+        - DEFAULT TO PARAGRAPHS. Every section is connected analytical prose:
+          full sentences, transitions, a line of argument. A section that consists
+          only of a bullet list is unfinished.
+        - EXPLAIN, DON'T JUST STATE. A number or fact enters the report together
+          with its meaning: what it is compared to, what drives it, what follows
+          from it, under what conditions it holds. "Inventory accuracy rose from
+          65% to 95–99%" alone is a note; the report says where these numbers come
+          from, on what scale they were measured, why the jump is that large, and
+          what caveats apply.
+        - MECHANISMS AND CAUSES. Wherever the material allows, answer "why" and
+          "how", not only "what": the mechanism behind an effect, the trade-off
+          behind a design choice, the reason two sources disagree.
+        - BULLETS ARE FOR GENUINE ENUMERATIONS ONLY: lists of items that are truly
+          parallel and need no individual discussion (a list of standards, a set of
+          frequency bands). Even then, each item is a full phrase, and the list is
+          introduced and followed by prose that interprets it. Never use bullets to
+          avoid writing sentences.
+        - NO ORPHAN KEYWORDS. Strings like "Equipment, blood, tissues, drugs, cold
+          chain" are raw material, not report text. Either develop them into
+          sentences that say something, or state explicitly that the topic is only
+          surveyed and why.
+        - EVERY SECTION ANSWERS A QUESTION. Before writing a section, know what
+          question it answers for the reader; the section is finished when a reader
+          who knows nothing about the topic comes away with an understanding, not a
+          word list to google.
+        - DENSITY OVER LENGTH. This is not a demand for padding or watery
+          academic filler — keep the text tight. The requirement is that
+          compression must never discard the reasoning, only the redundancy.
+
+      ═══════════════════════════════════════════════
+      LANGUAGE AND TERMINOLOGY OF THE REPORT
+      ═══════════════════════════════════════════════
+      The report is in English. Rules:
+        - Technical terms: use the established English term; give the original in
+          parentheses at first mention when the source language differs —
+          "embeddings (встраивания)". If no settled English term exists, keep the
+          original and gloss it once.
+        - Product names, API names, identifiers, code, CLI commands, config keys:
+          never translate, never transliterate.
+        - Quotes from sources: translate into English, keep the original phrasing
+          in the footnote or parentheses when the exact wording matters.
+        - Machine-readable artifacts inside the report (code blocks, tables of
+          identifiers) stay in their original language.
+
+      ═══════════════════════════════════════════════
+      REPORT FORMAT (in the document, in ENGLISH)
+      ═══════════════════════════════════════════════
+        - Direct answer to the main question up front.
+        - Detailed breakdown by subsections.
+        - "Adjacent & non-obvious" — useful things found next to the scope.
+        - "Contradictions & disputes" — conflicts between sources, results of
+          adversarial verification.
+        - "Unknown & unverified" — honestly: what was not found, what could not be
+          verified, and why.
+        - Inline footnotes throughout, plus a consolidated source list with
+          reliability notes at the end.
+
+      ═══════════════════════════════════════════════
+      FINALIZATION CHECKLIST (run before declaring done)
+      ═══════════════════════════════════════════════
+        □ Budget: the log shows the mandatory budget fully spent (or genuine
+          saturation documented, if no budget was given).
+        □ At least one full CRITICAL REVIEW PASS was done and its gaps were
+          addressed.
+        □ Every non-trivial claim has an inline `^[...]` footnote; no claim rests
+          solely on a snippet or a tier-6 source.
+        □ No section of the report body is note-style: no bare bullet lists of
+          numbers, no orphan keyword strings; every section is connected prose
+          that explains, not just states ("PROSE, NOT NOTES").
+        □ Key figures/dates are triangulated or explicitly flagged as
+          single-source.
+        □ The direct answer at the top matches the body of the report.
+        □ "Unknown" is honestly filled — not empty by omission.
+        □ Working sections ("Log", "Open Questions", "Revision") are moved to an
+          appendix at the end of the document or clearly separated from the report
+          body.
+      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

@@ -16,139 +16,336 @@ roles:
       whatever language is most effective, but deliver the report in Russian.
 
       ═══════════════════════════════════════════════
-      STEP 0. PLAN (always do this first)
+      THE BUDGET: PAGES READ, NOT SEARCHES
       ═══════════════════════════════════════════════
-      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.
-      - Fix the "research budget" — how many searches to run. If the USER named a
-        budget (e.g. "budget 100"), that number is BINDING and MUST be spent in
-        full: it defines the volume of the research, so keep searching until it is
-        used up. If the user gave no number, estimate one yourself from the task's
-        complexity (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).
+      The unit of research work is a PAGE READ IN FULL — opening a source with the
+      page-reading/extraction tool and actually reading it. Search queries are free
+      and unlimited: they are navigation, not research. A search result snippet is a
+      POINTER, never a source. Nothing learned only from a snippet may enter the
+      report.
+
+      - If the user named a budget (e.g. "budget 100"), that is 100 pages read, and
+        it is BINDING — a floor you MUST reach. Spend it in full even past the point
+        where the topic feels covered (see BUDGET REMAINDER PROTOCOL below).
+      - If no budget is given, default to about 50 pages read; fewer only for a
+        single trivial fact, well over 50 for a hard, broad task. Absent an explicit
+        budget, stop only at genuine saturation — when further reading stops
+        yielding new relevant information — not when it "seems like enough".
+      - A page counts toward the budget only if you read it and extracted something
+        (a finding, a dead-end note, a contradiction). Skimming a snippet does not
+        count. Re-opening the same page does not count twice.
+      - Rule of thumb: for every search that surfaces relevant hits, open and read
+        at least 2–3 of the most promising results BEFORE running the next search.
+        Chaining searches with no page reads in between is a critical failure —
+        snippets carry ~5 % of the available content and reading pages is the whole
+        job. If you catch yourself doing it, stop and go read what you already
+        found.
+
+      BUDGET REMAINDER PROTOCOL. When the topic already feels covered but budget
+      remains, do NOT pad with junk or near-duplicate reads. Spend the remainder in
+      this priority order:
+        1. ADVERSARIAL VERIFICATION — for each key claim in the document, run
+           searches deliberately trying to REFUTE it or find a competing version;
+           read what you find. Results go into the "Противоречия" section (or
+           strengthen the claim's footnote).
+        2. PRIMARY SOURCES — for every important claim currently backed by a
+           retelling, aggregator, or news piece, hunt down and read the original:
+           the study, spec, dataset, filing, repository, interview.
+        3. LATERAL EXPANSION — adjacent disciplines, industries with the same
+           problem, historical analogues, criticism and opposing schools.
+      Every remainder read must still be a genuine attempt to learn or verify
+      something.
 
       ═══════════════════════════════════════════════
-      WHERE TO WRITE THE RESULT
+      THE DOCUMENT IS YOUR WORKING MEMORY
       ═══════════════════════════════════════════════
-      - Reuse the current/already-open document ONLY if either (a) the user
-        explicitly asked to work in it, or (b) it is empty or has very little on
-        it AND its title matches the topic of the research. In every other case —
-        a non-empty page, or one whose title is about something else — create a
-        NEW document for the report.
-      - Set up this document at the VERY START — right after the plan (STEP 0) and
-        BEFORE running any searches. Seed it immediately with the query, the plan,
-        and a skeleton of the sections you expect to fill.
-      - Fill the document DYNAMICALLY as you work: after every meaningful finding,
-        write it in straight away (fact → source → reliability assessment) and
-        grow or reshape the structure as your understanding evolves.
-      - Do NOT hoard everything in your head or in notes and dump the whole report
-        in one pass at the end. The document is a LIVING artifact: it must exist
-        from the first minute and be updated continuously throughout the run, so
-        that by the finalization stage it is already almost complete and only
-        needs cleanup, ordering, and self-verification.
+      Your context window is small and lossy; the document is not. Treat the
+      document — not your head — as the single source of truth and your external
+      memory. You are not "taking notes to compile later"; you are building the
+      report itself, live, from the first minute.
+
+      SETUP. Create/claim the document at the VERY START, before any searches.
+      Reuse the currently open document ONLY if (a) the user explicitly asked to
+      work in it, or (b) it is empty or near-empty AND its title matches the topic.
+      Otherwise create a new one.
+
+      Seed it immediately with:
+        - the user's query, restated;
+        - the RESEARCH PLAN (see below) — the plan lives in the document, not in
+          chat; do not wait for approval, write it and proceed;
+        - a skeleton of the report sections you expect to fill;
+        - a "Журнал" section (working log) and an "Открытые вопросы" section.
+
+      RESEARCH PLAN (written into the document before searching):
+        - Break down the query: what exactly is needed, what sub-questions are
+          inside it, which terms are ambiguous or have synonyms/jargon.
+        - 5–10 search directions, including adjacent angles the user did not ask
+          about directly.
+        - The budget (user-given or default) and how you expect to allocate it
+          across directions — a rough split, revisable.
+        - Which languages to search in.
+
+      THE LOG. In the "Журнал" section keep a numbered list of pages read:
+      `N. [запрос →] источник — что взял / пусто / противоречие`. One line each.
+      This is your budget counter and your flush-cadence counter — count by the log,
+      not from memory. Dead ends and paywalls go in the log too (they count toward
+      the budget only if you actually read a cached/alternative copy; a hard dead
+      end is logged but not counted).
+
+      FLUSH CADENCE — HARD RULE. Never read more than ~8–10 pages without writing
+      everything gathered since the last flush into the report sections. Check the
+      log: if the last flush was 10 reads ago, the next action is writing, not
+      reading. Frequent small updates are the norm; a long streak of reads with
+      nothing written is a mistake to correct immediately.
+
+      A flush means writing REPORT PROSE, not dumping notes. Every flush produces
+      finished paragraphs in the report sections, written to the standard of
+      "PROSE, NOT NOTES" below. Telegraphic fragments are allowed ONLY in the
+      «Журнал» and «Открытые вопросы» working sections — never in the report body.
+      Do not plan to "expand the notes into text later": later never comes, and a
+      report assembled from unexpanded notes is a failed report.
+
+      CONTEXT DISCIPLINE. After flushing a finding into the document, compress it in
+      your head to 2–3 sentences of conclusions and let the raw page text go. Do not
+      carry full page contents forward in context. When you need to re-orient — and
+      ALWAYS before deciding what to research next after a flush — RE-READ the
+      document (at minimum: the skeleton, "Открытые вопросы", and the sections you
+      touched). The document you re-read, not your memory of it, defines the current
+      state of the research.
 
       ═══════════════════════════════════════════════
-      WORK LOOP (repeat until saturation)
+      WORK LOOP
       ═══════════════════════════════════════════════
-      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.
+      Iterate observe → orient → decide → act:
+        1. Observe: re-read the relevant parts of the DOCUMENT — what is filled,
+           what is thin, what "Открытые вопросы" lists.
+        2. Orient: which query or source best closes the biggest gap; update the
+           plan section if your understanding of the topic has shifted.
+        3. Decide: pick one concrete next action.
+        4. Act: search, then READ the promising results in full.
+      After every page read, reason: what you learned, what new questions arose,
+      what to read next. Add new questions to "Открытые вопросы"; strike out closed
+      ones. Flush per the cadence above.
+
+      ═══════════════════════════════════════════════
+      CRITICAL REVIEW PASS (mandatory, after the main pass)
+      ═══════════════════════════════════════════════
+      When the planned directions are covered (or ~70 % of the budget is spent,
+      whichever comes first), STOP researching and switch roles: re-read the ENTIRE
+      document as a hostile reviewer who did not do the research. Write the result
+      into a "Ревизия" block in the document:
+        - GAPS: sub-questions from the plan that are answered thinly or not at all;
+          sections that are compilation without analysis; places where the report
+          says "widely known" instead of citing.
+        - NOTE-STYLE SECTIONS: sections violating "PROSE, NOT NOTES" — bullet
+          lists of bare numbers, orphan keyword strings, facts stated without
+          mechanism or interpretation. Each one gets rewritten as prose; if the
+          understanding needed to write the prose is missing, that is a research
+          gap — go read more, then write.
+        - WEAK CLAIMS: key statements resting on a single source, on a secondary
+          source, on marketing material, or on an old date.
+        - CONTRADICTIONS: places where the document disagrees with itself.
+        - MISSING ANGLES: what a domain expert would immediately ask that the
+          report does not address.
+      Then convert this list into a targeted second pass: spend the remaining
+      budget closing the gaps and hardening the weak claims, in priority order.
+      If budget remains after that, apply the BUDGET REMAINDER PROTOCOL. Repeat the
+      review → targeted pass cycle until the budget is spent (mandatory budget) or
+      saturation is genuine (no budget given). A report that got only one linear
+      pass and no revision is not finished.
 
       ═══════════════════════════════════════════════
       HOW TO SEARCH
       ═══════════════════════════════════════════════
-      VOLUME. Execute a MINIMUM of 15 distinct searches, more for complex tasks.
-      Do not stop at the first plausible answer. Absent an explicit budget, stop
-      only when further searches stop yielding new relevant information
-      (saturation / diminishing returns) — not when it "seems like enough" or when
-      you get tired.
-
-      MANDATORY BUDGET. A "research budget" set by the user is a floor you MUST
-      reach: spend it in full even past the point where the topic already feels
-      covered. Do not treat apparent saturation as permission to stop early —
-      instead put the remaining searches to real use: broaden the scope, go
-      lateral into adjacent areas, dig deeper into primary sources, and verify key
-      facts from independent angles. Never pad the count with junk or near-
-      duplicate queries; every search must be a genuine attempt to learn something
-      new.
-
       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.
+      landscape, then narrow. Scarce results → broaden the phrasing; 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.
+      synonyms, the professional jargon of the field, alternative and historical
+      terms.
 
-      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.
+      OTHER LANGUAGES. Actively search in the languages where the primary sources
+      or core expertise likely live (German-law topic in German, Japanese-technology
+      topic in Japanese, medical reviews in non-English databases). Translate key
+      terms into the target language and search with them. Render anything found
+      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.
+      NOT THE FIRST PAGE. The first results are the most obvious and often the most
+      superficial. Deliberately dig 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.
+      LATERAL SEARCH. Don't fixate on the narrow phrasing. Regularly ask: "What
+      sits right next to the scope and might turn out to be important?" Capture
+      valuable unexpected findings — they feed the "Смежное и неочевидное" section.
 
       ═══════════════════════════════════════════════
       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.
+      SOURCE HIERARCHY (when sources conflict, higher beats lower, then recency):
+        1. Primary documents: studies, specs, standards, datasets, filings, code
+           repositories, official statistics, court records, first-person
+           interviews.
+        2. Peer-reviewed literature and systematic reviews.
+        3. Official documentation and statements of the responsible organization.
+        4. Quality journalism with named authors and named sources.
+        5. Expert blogs and conference talks (judge the author, not the venue).
+        6. Aggregators, content farms, forums, anonymous retellings — pointers
+           only; never the sole support for a claim in the report.
 
-      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.
+      CRITICAL APPRAISAL. Watch for: aggregators instead of the original, false
+      authority, nameless sources with passive voice, qualifiers without specifics,
+      marketing language, speculation, cherry-picked data. Do not present such
+      material as established fact — flag it. Present speculation about the future
+      as speculation.
+
+      LATERAL READING. To judge an unfamiliar source, don't burrow into it — check
+      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.
+      several INDEPENDENT sources (two retellings of one press release are one
+      source). 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.
+      DATES AND STALENESS. Record the publication date of a source alongside the
+      claim when it matters. For fast-moving topics, explicitly stamp facts («по
+      состоянию на 2024 год») and flag data that may be stale. Prefer the newest
+      credible source for anything volatile.
+
+      DEAD ENDS AND FAILURES. Paywall, 403, empty page, broken tool: log it and
+      move on — look for a cached copy, a mirror, the same material elsewhere, or
+      an alternative source. NEVER guess or reconstruct what an unreadable page
+      "probably said". A claim you couldn't verify because the source was
+      unreachable is written up as exactly that.
 
       ═══════════════════════════════════════════════
-      REPORT FORMAT (in the document, written in RUSSIAN)
+      CITING SOURCES INLINE (FOOTNOTES)
       ═══════════════════════════════════════════════
-      - 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.
+      EVERY non-trivial claim — facts, figures, dates, names, quotes, anything a
+      reader could doubt — carries an inline footnote to its source, placed right
+      at the claim, at the moment you write the claim in (fact → source →
+      reliability), not in a cleanup pass. The end-of-report source list
+      COMPLEMENTS inline citations, it does not replace them. A claim with no
+      footnote reads as unsourced.
 
-      Be honest about gaps. If you couldn't find something, say so — don't
-      disguise a guess as a fact.
+      SYNTAX. Inline form ONLY: `^[...]` directly after the word or sentence it
+      backs, no space before `^`. Prefer a Markdown link inside. The link must
+      point to the SPECIFIC page that supports THIS claim, not the site's homepage.
+      Examples:
+
+        Средний размер раунда вырос на 12 %^[Отчёт ЦБ «Итоги 2023», раздел 4.2,
+        [ссылка](https://cbr.ru/collection/file/2023-report.pdf)].
+        Функция появилась в версии 2.1^[Changelog проекта,
+        [v2.1.0](https://github.com/example/proj/releases/tag/v2.1.0)].
+
+      DO NOT use the reference style `text[^1]` with a separate `[^1]: ...` block:
+      this system does not parse it and it will show as raw text. Only `^[...]`
+      becomes a real footnote.
+
+      WHAT GOES INSIDE. Enough to identify and locate the source: title or
+      author/organization plus the URL. For a shaky source, add a short reliability
+      flag in the note (e.g. «вторичный источник, не подтверждён»). For a
+      triangulated claim, cite each source: several `^[...]` in a row or several
+      links in one note.
+
+      DEDUP. Identical `^[...]` texts merge automatically into one numbered entry —
+      cite freely without fear of duplicates.
+
+      WHICH WRITE PATH PARSES `^[...]`. The `^[...]` syntax turns into a REAL
+      footnote ONLY when you write the whole markdown body at once — create_page,
+      update_page_content, or import_page_markdown. When you write it as a claim
+      you are drafting, that is the normal path and it just works. But if you are
+      adding a citation to text that is ALREADY on the page, a surgical
+      edit_page_text (or insert_node) writes `^[...]` as a LITERAL string — it does
+      NOT parse, and the reader sees the raw `^[...]`. For that pinpoint case call
+      insert_footnote(anchorText, text): anchorText is a snippet of the existing
+      text to attach the note after, text is the note itself; numbering is handled
+      for you.
+
+      ═══════════════════════════════════════════════
+      PROSE, NOT NOTES
+      ═══════════════════════════════════════════════
+      You are writing a RESEARCH REPORT, not a конспект. The failure mode to avoid:
+      sections that are headers over bullet lists of bolded numbers and keyword
+      strings — compressed summaries with no reasoning. That is a lookup table, not
+      research. The reader hires you for the ANALYSIS: what the facts mean, how
+      they connect, why they are the way they are.
+
+      Concretely:
+        - DEFAULT TO PARAGRAPHS. Every section is connected analytical prose:
+          full sentences, transitions, a line of argument. A section that consists
+          only of a bullet list is unfinished.
+        - EXPLAIN, DON'T JUST STATE. A number or fact enters the report together
+          with its meaning: what it is compared to, what drives it, what follows
+          from it, under what conditions it holds. «Точность инвентаря выросла с
+          65 % до 95–99 %» alone is a note; the report says where these numbers
+          come from, on what scale they were measured, why the jump is that large,
+          and what caveats apply.
+        - MECHANISMS AND CAUSES. Wherever the material allows, answer "why" and
+          "how", not only "what": the mechanism behind an effect, the trade-off
+          behind a design choice, the reason two sources disagree.
+        - BULLETS ARE FOR GENUINE ENUMERATIONS ONLY: lists of items that are truly
+          parallel and need no individual discussion (a list of standards, a set of
+          frequency bands). Even then, each item is a full phrase, and the list is
+          introduced and followed by prose that interprets it. Never use bullets to
+          avoid writing sentences.
+        - NO ORPHAN KEYWORDS. Strings like «Оборудование, кровь, ткани, лекарства,
+          холодовая цепь» are raw material, not report text. Either develop them
+          into sentences that say something, or state explicitly that the topic is
+          only surveyed and why.
+        - EVERY SECTION ANSWERS A QUESTION. Before writing a section, know what
+          question it answers for the reader; the section is finished when a reader
+          who knows nothing about the topic comes away with an understanding, not a
+          word list to google.
+        - DENSITY OVER LENGTH. This is not a demand for padding or watery
+          academic filler — keep the text tight. The requirement is that
+          compression must never discard the reasoning, only the redundancy.
+
+      ═══════════════════════════════════════════════
+      LANGUAGE AND TERMINOLOGY OF THE REPORT
+      ═══════════════════════════════════════════════
+      The report is in Russian. Rules:
+        - Technical terms: use the established Russian term; give the original in
+          parentheses at first mention — «встраивания (embeddings)». If no settled
+          Russian term exists, keep the original and gloss it once.
+        - Product names, API names, identifiers, code, CLI commands, config keys:
+          never translate, never transliterate.
+        - Quotes from sources: translate into Russian, keep the original phrasing
+          in the footnote or parentheses when the exact wording matters.
+        - Machine-readable artifacts inside the report (code blocks, tables of
+          identifiers) stay in their original language.
+
+      ═══════════════════════════════════════════════
+      REPORT FORMAT (in the document, in RUSSIAN)
+      ═══════════════════════════════════════════════
+        - Direct answer to the main question up front.
+        - Detailed breakdown by subsections.
+        - «Смежное и неочевидное» — useful things found next to the scope.
+        - «Противоречия и спорное» — conflicts between sources, results of
+          adversarial verification.
+        - «Неизвестное и непроверенное» — honestly: what was not found, what could
+          not be verified, and why.
+        - Inline footnotes throughout, plus a consolidated source list with
+          reliability notes at the end.
+
+      ═══════════════════════════════════════════════
+      FINALIZATION CHECKLIST (run before declaring done)
+      ═══════════════════════════════════════════════
+        □ Budget: the log shows the mandatory budget fully spent (or genuine
+          saturation documented, if no budget was given).
+        □ At least one full CRITICAL REVIEW PASS was done and its gaps were
+          addressed.
+        □ Every non-trivial claim has an inline `^[...]` footnote; no claim rests
+          solely on a snippet or a tier-6 source.
+        □ No section of the report body is note-style: no bare bullet lists of
+          numbers, no orphan keyword strings; every section is connected prose
+          that explains, not just states ("PROSE, NOT NOTES").
+        □ Key figures/dates are triangulated or explicitly flagged as
+          single-source.
+        □ The direct answer at the top matches the body of the report.
+        □ «Неизвестное» is honestly filled — not empty by omission.
+        □ Working sections («Журнал», «Открытые вопросы», «Ревизия») are moved to
+          an appendix at the end of the document or clearly separated from the
+          report body.
+      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

@@ -33,4 +33,4 @@ bundles:
       - en
     roles:
       - slug: researcher
-        version: 4
+        version: 8

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

@@ -16,8 +16,8 @@
     "hash": "cef39fed321779631ddd1077fcba53399adf0e48b301df281c71eb042610900d"
   },
   "researcher": {
-    "version": 4,
-    "hash": "9446ec6d2c8a6ec548358537ac392b8bf9b4d2a832ebb105d5514eac2c76da74"
+    "version": 8,
+    "hash": "0e76efa180c3e443c8856b8787e9643923d10486b373ce078c12dc16eb04611b"
   },
   "structural-editor": {
     "version": 4,

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

@@ -1,4 +1,9 @@
-import { Hocuspocus } from '@hocuspocus/server';
+import {
+  connectedPayload,
+  Extension,
+  Hocuspocus,
+  onConnectPayload,
+} from '@hocuspocus/server';
 import { IncomingMessage } from 'http';
 import WebSocket from 'ws';
 import { AuthenticationExtension } from './extensions/authentication.extension';
@@ -25,6 +30,56 @@ import {
   CollaborationHandler,
   CollabEventHandlers,
 } from './collaboration.handler';
+import {
+  incDocLoad,
+  incDocUnload,
+  isMetricsEnabled,
+  observeCollabConnect,
+  registerDocsOpenSource,
+} from '../integrations/metrics/metrics.registry';
+
+/**
+ * #402 — collab lifecycle metrics as a lightweight hocuspocus extension.
+ *
+ * - afterLoadDocument / afterUnloadDocument (fire once PER DOCUMENT) drive the
+ *   doc load/unload counters.
+ * - collab_connect_duration_seconds: I time the onConnect→connected hook pair,
+ *   i.e. connection ACCEPTANCE (which includes the auth handshake). This is the
+ *   cleanest per-connection correlation hocuspocus exposes: both payloads carry
+ *   the SAME `request` IncomingMessage object, so a WeakMap keyed on it gives a
+ *   per-connection start with NO leak (the entry is GC'd with the request if a
+ *   connection is rejected in onAuthenticate and `connected` never fires).
+ *   I deliberately do NOT observe at afterLoadDocument: that hook fires per
+ *   DOCUMENT, not per connection, so a second client joining an already-open
+ *   doc would be missed. auth/load latencies are their own separate metrics.
+ *
+ * All helpers are no-ops when METRICS_PORT is unset; these hooks are per
+ * connect/load/unload (never per message), so there is no hot-path cost.
+ */
+class CollabMetricsExtension implements Extension {
+  // Keyed by the per-connection request object → connect start time (ms).
+  private readonly connectStarts = new WeakMap<object, number>();
+
+  async onConnect(data: onConnectPayload) {
+    this.connectStarts.set(data.request, performance.now());
+  }
+
+  async connected(data: connectedPayload) {
+    const start = this.connectStarts.get(data.request);
+    if (start !== undefined) {
+      observeCollabConnect((performance.now() - start) / 1000);
+      this.connectStarts.delete(data.request);
+    }
+  }
+
+  async afterLoadDocument() {
+    incDocLoad();
+  }
+
+  async afterUnloadDocument() {
+    incDocUnload();
+  }
+}
 
 @Injectable()
 export class CollaborationGateway {
@@ -58,9 +113,18 @@ export class CollaborationGateway {
         this.authenticationExtension,
         this.persistenceExtension,
         this.loggerExtension,
+        // #402 collab lifecycle + connect-duration metrics (no-op when off).
+        new CollabMetricsExtension(),
       ],
     });
 
+    // #402 — read-on-scrape source for collab_docs_open. Wire ONCE, gated, so
+    // nothing runs when metrics are disabled. The gauge's collect() pulls the
+    // live count from the hocuspocus instance on each scrape (no inc/dec drift).
+    if (isMetricsEnabled()) {
+      registerDocsOpenSource(() => this.hocuspocus.getDocumentsCount());
+    }
+
     if (this.withRedis) {
       this.redisClient = new RedisClient({
         host: this.redisConfig.host,

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

@@ -16,6 +16,7 @@ import { isUserDisabled } from '../../common/helpers';
 import { getPageId } from '../collaboration.util';
 import { JwtCollabPayload, JwtType } from '../../core/auth/dto/jwt-payload';
 import { resolveProvenance } from '../../common/decorators/auth-provenance.decorator';
+import { observeCollabAuth } from '../../integrations/metrics/metrics.registry';
 
 @Injectable()
 export class AuthenticationExtension implements Extension {
@@ -30,6 +31,18 @@ export class AuthenticationExtension implements Extension {
   ) {}
 
   async onAuthenticate(data: onAuthenticatePayload) {
+    // #402 — time the whole auth (verify + user/page/permission lookups) into
+    // collab_auth_duration_seconds. finally so failed auths are timed too.
+    // No-op when METRICS_PORT is unset. Behavior unchanged.
+    const start = performance.now();
+    try {
+      return await this.doAuthenticate(data);
+    } finally {
+      observeCollabAuth((performance.now() - start) / 1000);
+    }
+  }
+
+  private async doAuthenticate(data: onAuthenticatePayload) {
     const { documentName, token } = data;
     const pageId = getPageId(documentName);
 

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

@@ -41,7 +41,10 @@ import {
   HISTORY_INTERVAL,
 } from '../constants';
 import { TransclusionService } from '../../core/page/transclusion/transclusion.service';
-import { observeCollabStore } from '../../integrations/metrics/metrics.registry';
+import {
+  observeCollabLoad,
+  observeCollabStore,
+} from '../../integrations/metrics/metrics.registry';
 
 /**
  * #251 — wire format of the client→server stateless message that signals a
@@ -150,10 +153,14 @@ export class PersistenceExtension implements Extension {
     const { documentName, document } = data;
     const pageId = getPageId(documentName);
 
+    // #402 — the early return below (live doc already non-empty) does NOT touch
+    // the DB, so it is deliberately NOT timed. We only observe the real DB-load
+    // work, and only on each real-load return, tagged by the loaded doc size.
     if (!document.isEmpty('default')) {
       return;
     }
 
+    const startedAt = performance.now();
     const page = await this.pageRepo.findById(pageId, {
       includeContent: true,
       includeYdoc: true,
@@ -171,6 +178,7 @@ export class PersistenceExtension implements Extension {
       const dbState = new Uint8Array(page.ydoc);
 
       Y.applyUpdate(doc, dbState);
+      observeCollabLoad(dbState.length, (performance.now() - startedAt) / 1000);
       return doc;
     }
 
@@ -184,26 +192,42 @@ export class PersistenceExtension implements Extension {
         tiptapExtensions,
       );
 
-      Y.encodeStateAsUpdate(ydoc);
+      // Reuse this single encode for the size label (do NOT add a second one).
+      const encoded = Y.encodeStateAsUpdate(ydoc);
+      observeCollabLoad(
+        encoded.byteLength,
+        (performance.now() - startedAt) / 1000,
+      );
       return ydoc;
     }
 
     this.logger.debug(`creating fresh ydoc: ${pageId}`);
+    observeCollabLoad(0, (performance.now() - startedAt) / 1000);
     return new Y.Doc();
   }
 
   async onStoreDocument(data: onStoreDocumentPayload) {
     // #355 — time the full store (persist + post-store side effects) into
-    // collab_store_duration_seconds. No-op when METRICS_PORT is unset.
+    // collab_store_duration_seconds. #402 — also tag by document size bucket.
+    // No-op when METRICS_PORT is unset.
     const startedAt = performance.now();
+    // Default 0 so a throw before storeDocument returns still records a
+    // (smallest-bucket) observation rather than dropping the timing entirely.
+    let bytes = 0;
     try {
-      await this.storeDocument(data);
+      bytes = await this.storeDocument(data);
     } finally {
-      observeCollabStore((performance.now() - startedAt) / 1000);
+      observeCollabStore(bytes, (performance.now() - startedAt) / 1000);
     }
   }
 
-  private async storeDocument(data: onStoreDocumentPayload) {
+  /**
+   * Persist the document. Returns the serialized ydoc byte size (used as the
+   * store histogram's size_bucket). The single Y.encodeStateAsUpdate below is
+   * the ONLY serialization — its byteLength is reused for the label (no second
+   * encode).
+   */
+  private async storeDocument(data: onStoreDocumentPayload): Promise<number> {
     const { documentName, document, context } = data;
 
     const pageId = getPageId(documentName);
@@ -455,6 +479,11 @@ export class PersistenceExtension implements Extension {
 
       await this.enqueuePageHistory(page, lastUpdatedSource);
     }
+
+    // #402 — report the serialized size for the store histogram's size_bucket.
+    // ydocState is always computed above (there is no earlier no-write return in
+    // this method), so this reflects the doc that was serialized this store.
+    return ydocState.byteLength;
   }
 
   /**

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

@@ -64,6 +64,32 @@ describe('AiChatService.stream — abort during external-MCP setup finalizes the
     ],
   };
 
+  // A minimal raw ServerResponse stand-in for the turns that PROCEED past setup
+  // and reach streamText (the deadline + legacy paths). The setup-only abort test
+  // never wires the stream, so it keeps using `{ raw: {} }`.
+  function makeRawRes() {
+    return {
+      raw: {
+        writeHead: jest.fn(function writeHead(this: unknown) {
+          return this;
+        }),
+        write: jest.fn(),
+        once: jest.fn(),
+        flushHeaders: jest.fn(),
+      },
+    };
+  }
+
+  // A fake streamText result: the service only calls consumeStream() and
+  // pipeUIMessageStreamToResponse() on it (both fire-and-forget). Its terminal
+  // callbacks are never invoked, so the run is not finalized through them.
+  function makeStreamResult() {
+    return {
+      consumeStream: jest.fn(),
+      pipeUIMessageStreamToResponse: jest.fn(),
+    };
+  }
+
   beforeEach(() => {
     streamTextMock.mockReset();
     jest.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined as never);
@@ -71,7 +97,10 @@ describe('AiChatService.stream — abort during external-MCP setup finalizes the
     jest.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined as never);
   });
 
-  afterEach(() => jest.restoreAllMocks());
+  afterEach(() => {
+    jest.restoreAllMocks();
+    jest.useRealTimers();
+  });
 
   it('stops the hung toolset build, rejects, and settles the run "aborted" — never reaching streamText', async () => {
     const runController = new AbortController();
@@ -118,4 +147,149 @@ describe('AiChatService.stream — abort during external-MCP setup finalizes the
     expect(toolsFor).toHaveBeenCalledTimes(1);
     expect(streamTextMock).not.toHaveBeenCalled();
   });
+
+  // Item 1 — the onLateResolve leg of raceAgainstAbortAndTimeout. When `toolsFor`
+  // loses the race (abort) but RESOLVES LATER with a leased toolset, the setup site
+  // must release that abandoned toolset's leases (call close() on its client
+  // handles) so their lease refcount is not pinned forever by a toolset nobody
+  // consumes. Nothing else exercises this path.
+  it('releases the leases of a toolset that resolves AFTER the race was already lost (onLateResolve)', async () => {
+    const runController = new AbortController();
+    // A controllable build: it hangs until we resolve it by hand, and the run is
+    // stopped mid-build so the race rejects BEFORE the build settles.
+    let resolveTools: (v: unknown) => void = () => undefined;
+    const toolsForPromise = new Promise((resolve) => {
+      resolveTools = resolve;
+    });
+    const toolsFor = jest.fn(() => {
+      setTimeout(() => runController.abort(new Error('user stop')), 0);
+      return toolsForPromise;
+    });
+    const { svc } = makeService({ toolsFor });
+
+    const begin = jest.fn(async () => ({
+      runId: 'run-1',
+      signal: runController.signal,
+    }));
+
+    const promise = svc.stream({
+      user: { id: 'user-1' } as never,
+      workspace: { id: 'ws-1' } as never,
+      sessionId: 'sess-1',
+      body: body as never,
+      res: { raw: {} } as never,
+      signal: new AbortController().signal,
+      model: {} as never,
+      role: null,
+      runHooks: {
+        begin,
+        onAssistantSeeded: jest.fn(),
+        onStep: jest.fn(),
+        onSettled: jest.fn(),
+      } as never,
+    });
+
+    // The race is lost to the abort: the turn rejects with the stop reason.
+    await expect(promise).rejects.toThrow('user stop');
+
+    // NOW the abandoned build resolves late with a leased client. onLateResolve must
+    // release it (call close on the lease handle).
+    const close = jest.fn().mockResolvedValue(undefined);
+    resolveTools({
+      tools: {},
+      clients: [{ close }],
+      outcomes: [],
+      instructions: [],
+    });
+    // Flush the microtasks so work.then -> onLateResolve -> Promise.all(close) runs.
+    await new Promise((r) => setImmediate(r));
+
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  // Item 2 — the PURE DEADLINE branch (MCP_TOOLSET_BUILD_DEADLINE_MS). `toolsFor`
+  // never settles and the run's signal is NOT aborted: the race rejects with a
+  // "setup timed out" error, the catch does NOT re-throw (runId set but signal not
+  // aborted), and the turn PROCEEDS Docmost-only. It must reach streamText (the turn
+  // continues, not wedged) and must NOT be finalized 'aborted'.
+  it('proceeds Docmost-only (reaches streamText) when the build hits the deadline without an abort', async () => {
+    jest.useFakeTimers();
+
+    // The build hangs forever; the run's signal is never aborted.
+    const toolsFor = jest.fn(() => new Promise(() => {}));
+    const { svc } = makeService({ toolsFor });
+
+    streamTextMock.mockReturnValue(makeStreamResult() as never);
+
+    const onSettled = jest.fn();
+    const runSignal = new AbortController().signal; // never aborts
+    const begin = jest.fn(async () => ({ runId: 'run-1', signal: runSignal }));
+
+    const promise = svc.stream({
+      user: { id: 'user-1' } as never,
+      workspace: { id: 'ws-1' } as never,
+      sessionId: 'sess-1',
+      body: body as never,
+      res: makeRawRes() as never,
+      signal: new AbortController().signal,
+      model: {} as never,
+      role: null,
+      runHooks: {
+        begin,
+        onAssistantSeeded: jest.fn(),
+        onStep: jest.fn(),
+        onSettled,
+      } as never,
+    });
+
+    // Advance past the 60s build deadline; advanceTimersByTimeAsync flushes the
+    // promise microtasks between timer fires so the whole setup chain runs.
+    await jest.advanceTimersByTimeAsync(60_001);
+    // The turn does not throw out of setup — it continues to stream.
+    await expect(promise).resolves.toBeUndefined();
+
+    // The turn CONTINUED: streamText was reached (Docmost-only), not wedged.
+    expect(toolsFor).toHaveBeenCalledTimes(1);
+    expect(streamTextMock).toHaveBeenCalledTimes(1);
+    // The run was NOT finalized as aborted (the deadline is not a Stop) — the setup
+    // catch settle path never ran, so onSettled is left to streamText's callbacks.
+    expect(onSettled).not.toHaveBeenCalled();
+  });
+
+  // Item 3 — the LEGACY no-runId path. The catch's re-throw is gated on
+  // `runId && effectiveSignal.aborted`. With NO runId (no runHooks) an abort during
+  // setup must NOT re-throw (runId falsy) — the turn warns + proceeds Docmost-only
+  // and streams, and is never finalized 'aborted' via the re-throw. Locks the
+  // `runId &&` half of the guard.
+  it('does NOT re-throw on a setup abort when there is no runId (legacy path proceeds Docmost-only)', async () => {
+    const socketController = new AbortController();
+    // The build hangs; the SOCKET signal (legacy effectiveSignal) aborts mid-build.
+    const toolsFor = jest.fn(() => {
+      setTimeout(() => socketController.abort(new Error('socket closed')), 0);
+      return new Promise(() => {});
+    });
+    const { svc } = makeService({ toolsFor });
+
+    streamTextMock.mockReturnValue(makeStreamResult() as never);
+
+    // No runHooks => runId undefined, effectiveSignal === the socket signal.
+    const promise = svc.stream({
+      user: { id: 'user-1' } as never,
+      workspace: { id: 'ws-1' } as never,
+      sessionId: 'sess-1',
+      body: body as never,
+      res: makeRawRes() as never,
+      signal: socketController.signal,
+      model: {} as never,
+      role: null,
+    });
+
+    // The turn does NOT reject out of setup (no re-throw on the legacy path).
+    await expect(promise).resolves.toBeUndefined();
+
+    // It proceeded Docmost-only and reached streamText — streamText then observes
+    // the already-aborted socket signal via its own abortSignal.
+    expect(toolsFor).toHaveBeenCalledTimes(1);
+    expect(streamTextMock).toHaveBeenCalledTimes(1);
+  });
 });

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

@@ -16,6 +16,7 @@ import {
   rowToUiMessage,
   prepareAgentStep,
   flushAssistant,
+  stripNulChars,
   chatStreamMetadata,
   accumulateStepUsage,
   isInterruptResume,
@@ -28,11 +29,13 @@ import { buildSystemPrompt } from './ai-chat.prompt';
 import type { McpClientsService } from './external-mcp/mcp-clients.service';
 
 /**
- * Unit tests for compactToolOutput: the pure helper that shrinks LARGE tool
- * outputs before they are persisted (and re-sent to the provider on later
- * turns). The contract is: small outputs pass through unchanged (by identity);
- * large outputs keep their shape and small scalar fields (id/title/pageId — the
- * client reads these to render citations) while big payloads are truncated.
+ * Unit tests for compactToolOutput: the pure helper that shrinks tool outputs
+ * before they are persisted (and re-sent to the provider on later turns). The
+ * contract is: small and normal outputs — including whole page reads (tens of
+ * KB) — pass through unchanged (by identity); only an output above the high
+ * safety cap (> 200 KB) is compacted, and even then it keeps its shape and
+ * small scalar fields (id/title/pageId — the client reads these to render
+ * citations) while the big payloads are reduced.
  */
 describe('compactToolOutput', () => {
   it('returns a small object unchanged (by identity)', () => {
@@ -41,7 +44,7 @@ describe('compactToolOutput', () => {
   });
 
   it('truncates a large getPage-shaped markdown body but keeps the title', () => {
-    const big = 'x'.repeat(20000);
+    const big = 'x'.repeat(300000);
     const result = compactToolOutput({ title: 'T', markdown: big }) as {
       title: string;
       markdown: string;
@@ -49,15 +52,16 @@ describe('compactToolOutput', () => {
     // Shallow scalar field is preserved (citations depend on it).
     expect(result.title).toBe('T');
     // The big payload is shrunk far below the original size.
-    expect(result.markdown.length).toBeLessThan(20000);
-    expect(result.markdown).toContain('[truncated');
+    expect(result.markdown.length).toBeLessThan(300000);
+    expect(result.markdown).toContain('omitted from stored chat history');
   });
 
   it('caps a long array and appends a single truncation marker', () => {
-    // 200 small objects, each padded so the total serialized size > 4000 bytes.
+    // 200 objects, each padded so the total serialized size
+    // > 200000 bytes (the new safety cap).
     const long = Array.from({ length: 200 }, (_, i) => ({
       id: 'n' + i,
-      pad: 'y'.repeat(40),
+      pad: 'y'.repeat(1200),
     }));
     const result = compactToolOutput(long) as Array<Record<string, unknown>>;
     // 50 kept + 1 marker.
@@ -75,8 +79,8 @@ describe('compactToolOutput', () => {
 
   it('replaces a subtree beyond the depth cap with a marker', () => {
     // Build a deeply nested object (> TOOL_OUTPUT_MAX_DEPTH levels) with a big
-    // string at the bottom so the total serialized size exceeds the threshold.
-    let nested: Record<string, unknown> = { leaf: 'z'.repeat(8000) };
+    // string at the bottom so the total serialized size exceeds the 200 KB cap.
+    let nested: Record<string, unknown> = { leaf: 'z'.repeat(250000) };
     for (let i = 0; i < 20; i++) {
       nested = { child: nested };
     }
@@ -85,7 +89,7 @@ describe('compactToolOutput', () => {
   });
 
   it('produces a much smaller JSON than the original for a large input', () => {
-    const big = 'x'.repeat(20000);
+    const big = 'x'.repeat(300000);
     const original = { title: 'T', markdown: big };
     const result = compactToolOutput(original);
     const originalBytes = Buffer.byteLength(JSON.stringify(original), 'utf8');
@@ -448,6 +452,45 @@ describe('flushAssistant', () => {
   });
 });
 
+/**
+ * stripNulChars: a NUL (U+0000) is rejected by Postgres in BOTH the `content`
+ * (text) and `toolCalls`/`metadata` (jsonb) columns, so it must be stripped from
+ * every persisted string. String.fromCharCode(0) avoids embedding a raw NUL byte
+ * in this source file.
+ */
+describe('stripNulChars', () => {
+  const NUL = String.fromCharCode(0);
+
+  it('deep-strips NUL from strings in nested objects/arrays', () => {
+    const out = stripNulChars({
+      content: `a${NUL}b`,
+      parts: [{ type: 'text', text: `x${NUL}${NUL}y` }],
+      nested: [`p${NUL}q`, 42, null],
+    });
+    expect(out.content).toBe('ab');
+    expect((out.parts[0] as { text: string }).text).toBe('xy');
+    expect(out.nested[0]).toBe('pq');
+    expect(out.nested[1]).toBe(42);
+    expect(out.nested[2]).toBeNull();
+    expect(JSON.stringify(out).includes(NUL)).toBe(false);
+  });
+
+  it('returns the SAME reference when there is no NUL (no needless clone)', () => {
+    const input = { a: 'clean', b: [1, 2, { c: 'ok' }] };
+    expect(stripNulChars(input)).toBe(input);
+  });
+
+  it('flushAssistant produces a NUL-free row even when the turn text carries one', () => {
+    const f = flushAssistant([], `partial${NUL}answer`, 'error', {
+      error: `bo${NUL}om`,
+    });
+    expect(f.content).toBe('partialanswer');
+    const serialized =
+      f.content + JSON.stringify(f.toolCalls) + JSON.stringify(f.metadata);
+    expect(serialized.includes(NUL)).toBe(false);
+  });
+});
+
 /**
  * chatStreamMetadata: attach metadata to the streamed assistant UI message per
  * part type — `chatId` on `start` (so the client adopts the real created chat id

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

@@ -63,8 +63,12 @@ const MAX_AGENT_STEPS = 20;
 // per-server connect bound in mcp-clients.service (CONNECT_TIMEOUT_MS): even if
 // that per-server timeout regressed, this outer deadline — together with the run's
 // abort signal — guarantees the setup phase can never wedge a turn at step 0 (the
-// production hang) and the run always finalizes. Generous: the per-server bound
-// should fire first in practice; this only backstops a total build stall.
+// production hang) and the run always finalizes. It stays a TRUE backstop because
+// buildEntry connects to the servers CONCURRENTLY, so the total build time is
+// bounded by the SLOWEST single server (~2×CONNECT_TIMEOUT_MS), not the SUM across
+// them — the per-server bound fires first no matter how many servers are enabled,
+// and this outer deadline only catches a total build stall the per-server bound
+// somehow missed.
 const MCP_TOOLSET_BUILD_DEADLINE_MS = 60_000;
 
 // System-prompt addendum injected ONLY on the final step (see prepareAgentStep).
@@ -791,8 +795,11 @@ export class AiChatService implements OnModuleInit {
         // a hung build would hang the turn at step 0 forever (the production hang),
         // unobservant of an explicit Stop. The deadline is defense-in-depth ABOVE
         // the per-server connect bound in mcp-clients.service. On a LATE resolve
-        // (the race was already lost) close the abandoned toolset's leased clients
-        // so their transports are not leaked.
+        // (the race was already lost) RELEASE the abandoned toolset's leases —
+        // c.close() here is the lease handle, so it decrements the cache entry's
+        // refcount; it does NOT force-close the transports (the cache OWNS the
+        // clients and closes them on TTL/evict). This just prevents the lease
+        // refcount from being pinned >=1 forever by a toolset nobody will consume.
         external = await raceAgainstAbortAndTimeout(
           this.mcpClients.toolsFor(workspace.id),
           effectiveSignal,
@@ -1635,16 +1642,25 @@ type StepLike = {
 /**
  * Compaction tunables for persisted tool OUTPUTS. Read tools (getPage,
  * getPageJson, getNode, diffPageVersions, exportPageMarkdown, ...) return whole
- * pages with no size cap. Their outputs are stored in `metadata.parts` and
- * RE-SENT to the provider on every later turn via convertToModelMessages, so an
- * uncompacted large body grows token cost, latency, and DB row size on every
- * turn. We shrink the big payloads while preserving the object's shape and its
- * small scalar fields (id/title/pageId) the client reads to render citations.
+ * pages. Their outputs are stored in `metadata.parts` and RE-SENT to the
+ * provider on every later turn via convertToModelMessages. We deliberately keep
+ * these outputs FULL up to a high safety cap (MAX_TOOL_OUTPUT_BYTES) so the
+ * model never sees a shortened copy of content it already fetched: an earlier
+ * 4000-byte cap shrank normal page reads (often tens of KB) to a tiny preview,
+ * and the model — seeing a truncation marker in its OWN history — re-read the
+ * same page, wasting tokens. Only a single output LARGER than the cap is
+ * compacted at all, purely as a backstop against a pathological payload; even
+ * then we preserve the object's shape and its small scalar fields
+ * (id/title/pageId) that the client reads to render citations.
  */
-// Only outputs whose JSON serialization exceeds this are compacted at all
-// (fast path: smaller outputs are returned unchanged, by identity).
-const MAX_TOOL_OUTPUT_BYTES = 4000;
-// A string longer than this is truncated to a leading preview.
+// HIGH safety backstop: only an output whose JSON serialization EXCEEDS this is
+// compacted at all. Normal reads (whole pages, tens of KB) stay well under it
+// and are stored + replayed VERBATIM (fast path: returned unchanged, by
+// identity). Only a single pathologically huge output (> 200 KB) is compacted.
+const MAX_TOOL_OUTPUT_BYTES = 200_000;
+// Inside the backstop path only (i.e. once the whole output already exceeded
+// MAX_TOOL_OUTPUT_BYTES), a string longer than this is reduced to a leading
+// preview; normal outputs never reach this branch.
 const TOOL_OUTPUT_STRING_LIMIT = 600;
 // Number of leading characters kept from a truncated string.
 const TOOL_OUTPUT_STRING_PREVIEW = 500;
@@ -1687,9 +1703,9 @@ export function compactToolOutput(output: unknown): unknown {
 function compactValue(value: unknown, depth: number): unknown {
   if (typeof value === 'string') {
     if (value.length > TOOL_OUTPUT_STRING_LIMIT) {
-      return `${value.slice(0, TOOL_OUTPUT_STRING_PREVIEW)}…[truncated ${
+      return `${value.slice(0, TOOL_OUTPUT_STRING_PREVIEW)}…[${
         value.length - TOOL_OUTPUT_STRING_PREVIEW
-      } chars]`;
+      } chars omitted from stored chat history to bound replay size — call the tool again to read the full output]`;
     }
     return value;
   }
@@ -1876,6 +1892,45 @@ export async function applyFinalize(
   });
 }
 
+/**
+ * Deep-strip NUL characters (`\u0000`) from every string in a value, returning
+ * the SAME reference when nothing changed (so the no-NUL common case allocates
+ * nothing). Postgres rejects a NUL in BOTH `text` and `jsonb` columns ("invalid
+ * input syntax for type json" / "unsupported Unicode escape sequence"), so a
+ * stray NUL in model output or a tool result — e.g. a truncated multibyte read
+ * of a web page — otherwise fails EVERY persist of the assistant row, silently
+ * dropping that turn's content from the DB while the live stream still shows it.
+ * Applied at the flushAssistant choke point so content + toolCalls + metadata are
+ * all covered. Exported for the unit test.
+ */
+export function stripNulChars<T>(value: T): T {
+  if (typeof value === 'string') {
+    return (value.includes('\u0000')
+      ? value.replace(/\u0000/g, '')
+      : value) as T;
+  }
+  if (Array.isArray(value)) {
+    let changed = false;
+    const out = value.map((v) => {
+      const s = stripNulChars(v);
+      if (s !== v) changed = true;
+      return s;
+    });
+    return (changed ? out : value) as T;
+  }
+  if (value && typeof value === 'object') {
+    let changed = false;
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      const s = stripNulChars(v);
+      if (s !== v) changed = true;
+      out[k] = s;
+    }
+    return (changed ? out : value) as T;
+  }
+  return value;
+}
+
 /**
  * PURE assistant-row builder (#183 step-granular durability). Given the turn's
  * accumulated steps + the in-progress (not-yet-finished) text + the lifecycle
@@ -1945,12 +2000,16 @@ export function flushAssistant(
     };
   }
 
-  return {
+  // Strip NUL chars from the whole row before persisting: Postgres rejects a NUL
+  // in both the `content` (text) and `toolCalls`/`metadata` (jsonb) columns, and a
+  // single stray NUL in model/tool output would otherwise fail EVERY write of this
+  // row and silently drop the turn's content from the DB (see stripNulChars).
+  return stripNulChars({
     content: stepsText + trailing,
     toolCalls: serializeSteps(finished),
     metadata,
     status,
-  };
+  });
 }
 
 /**

apps/server/src/core/ai-chat/external-mcp/mcp-call-timeout.spec.ts

@@ -181,25 +181,25 @@ describe('mcp timeout env helpers', () => {
     else process.env.AI_MCP_CALL_TIMEOUT_MS = ORIG_CALL;
   });
 
-  it('mcpStreamTimeoutMs defaults to 5 min and honors a positive override', () => {
+  it('mcpStreamTimeoutMs defaults to 1 min and honors a positive override', () => {
     delete process.env.AI_MCP_STREAM_TIMEOUT_MS;
-    expect(mcpStreamTimeoutMs()).toBe(300_000);
-    process.env.AI_MCP_STREAM_TIMEOUT_MS = '60000';
     expect(mcpStreamTimeoutMs()).toBe(60_000);
+    process.env.AI_MCP_STREAM_TIMEOUT_MS = '90000';
+    expect(mcpStreamTimeoutMs()).toBe(90_000);
     for (const bad of ['0', '-1', 'x', '']) {
       process.env.AI_MCP_STREAM_TIMEOUT_MS = bad;
-      expect(mcpStreamTimeoutMs()).toBe(300_000);
+      expect(mcpStreamTimeoutMs()).toBe(60_000);
     }
   });
 
-  it('mcpCallTimeoutMs defaults to 15 min and honors a positive override', () => {
+  it('mcpCallTimeoutMs defaults to 2 min and honors a positive override', () => {
     delete process.env.AI_MCP_CALL_TIMEOUT_MS;
-    expect(mcpCallTimeoutMs()).toBe(900_000);
-    process.env.AI_MCP_CALL_TIMEOUT_MS = '120000';
     expect(mcpCallTimeoutMs()).toBe(120_000);
+    process.env.AI_MCP_CALL_TIMEOUT_MS = '180000';
+    expect(mcpCallTimeoutMs()).toBe(180_000);
     for (const bad of ['0', '-1', 'x', '']) {
       process.env.AI_MCP_CALL_TIMEOUT_MS = bad;
-      expect(mcpCallTimeoutMs()).toBe(900_000);
+      expect(mcpCallTimeoutMs()).toBe(120_000);
     }
   });
 });

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

@@ -255,54 +255,49 @@ export class McpClientsService {
     const callTimeoutMs = mcpCallTimeoutMs();
     const instructions: McpServerInstruction[] = [];
 
-    for (const server of servers) {
-      // Track the connected client OUTSIDE the try so the catch can close it when
-      // it was obtained but not yet registered in `clients` (e.g. tools() threw or
-      // timed out after a successful connect). `registered` flips only once the
-      // client is owned by `clients` (closed at entry teardown), so the catch never
-      // double-closes a registered client.
+    // Per-server connect+tools result, still tagged with its server so the merge
+    // below can be applied in the SAME order as `servers` (see the parallel note).
+    type PerServerResult =
+      | { ok: true; client: McpClient; guarded: Record<string, Tool> }
+      | { ok: false; reason: string };
+
+    // Connect to (and list tools for) every enabled server CONCURRENTLY, so the
+    // total build time is bounded by the SLOWEST single server (~2×
+    // CONNECT_TIMEOUT_MS: connect + tools), NOT the SUM across servers. The
+    // sequential loop this replaced summed those bounds, so with enough all-timing-
+    // out servers the outer MCP_TOOLSET_BUILD_DEADLINE_MS could fire before the
+    // per-server bounds, dropping ALL external tools and inverting the "per-server
+    // bound is primary, outer is a backstop" invariant. Each server keeps its OWN
+    // try/catch + connectWithTimeout/withTimeout bound + close-on-failure logic; a
+    // failed server is skipped, never fatal. Nothing here mutates the shared
+    // arrays — every result is merged IN SERVER ORDER after Promise.all, so tool-
+    // key precedence/disambiguation, `outcomes`, `instructions` and `clients`
+    // ordering all match the previous sequential behavior exactly.
+    const perServer = async (
+      server: (typeof servers)[number],
+    ): Promise<PerServerResult> => {
+      // Track the connected client so the catch can close it when it was obtained
+      // but tools() then threw/timed out (connectWithTimeout closes its OWN orphan
+      // on a connect timeout, so `client` stays undefined on that path). On success
+      // the client is handed back and registered by the merge below (owned by the
+      // entry, closed at teardown) — so it is never double-closed.
       let client: McpClient | undefined;
-      let registered = false;
       try {
         client = await this.connectWithTimeout(server, CONNECT_TIMEOUT_MS);
         const raw = await withTimeout(client.tools(), CONNECT_TIMEOUT_MS);
-        clients.push(client);
-        registered = true;
         const allow = server.toolAllowlist;
         const picked =
           Array.isArray(allow) && allow.length > 0 ? pick(raw, allow) : raw;
         // Bound each tool's execute with a per-call total-timeout guard before
         // merging, so a single chatty-but-stuck call is aborted after the cap.
         const guarded = wrapToolsWithCallTimeout(picked, callTimeoutMs);
-        // Namespace each tool with the sanitized server name AND disambiguate
-        // against names already merged from earlier servers, so no external
-        // tool is silently overwritten on collision. The returned count drives
-        // whether this server's prompt guidance is included (≥1 tool merged).
-        const merged = this.mergeNamespaced(
-          tools,
-          guarded,
-          server.name,
-          server.id,
-        );
-        outcomes.push({ name: server.name, ok: true });
-        // Include this server's guidance ONLY when it actually contributed at
-        // least one tool the agent can call (allowlist may have filtered all of
-        // them out) AND the admin authored non-blank instructions. The header
-        // prefix is the sanitized server name (= the tool namespace prefix).
-        const guide = server.instructions?.trim();
-        if (merged.count > 0 && guide) {
-          instructions.push({
-            serverName: server.name,
-            toolPrefix: merged.prefix,
-            instructions: guide,
-          });
-        }
+        return { ok: true, client, guarded };
       } catch (err) {
         // A failed server is skipped — the turn proceeds with the rest. If connect
         // returned a live client but a later step (tools()) threw, that client was
         // never registered in `clients`, so close it here or its transport/socket
         // leaks (compounding every 60s cache rebuild during a flaky-server outage).
-        if (client && !registered) {
+        if (client) {
           void client.close().catch(() => undefined);
         }
         // Log a short warning (never the URL/headers) so ops can see degradation,
@@ -311,7 +306,45 @@ export class McpClientsService {
         this.logger.warn(
           `External MCP server "${server.name}" unavailable: ${reason}`,
         );
-        outcomes.push({ name: server.name, ok: false, reason });
+        return { ok: false, reason };
+      }
+    };
+
+    // Promise.all preserves array order regardless of settle order, so `results[i]`
+    // is `servers[i]`'s outcome — the merge below stays deterministic and matches
+    // the old sequential order (later servers still override/disambiguate against
+    // earlier ones on a tool-key clash).
+    const results = await Promise.all(servers.map(perServer));
+    for (let i = 0; i < servers.length; i += 1) {
+      const server = servers[i];
+      const result = results[i];
+      if (result.ok !== true) {
+        outcomes.push({ name: server.name, ok: false, reason: result.reason });
+        continue;
+      }
+      clients.push(result.client);
+      // Namespace each tool with the sanitized server name AND disambiguate
+      // against names already merged from earlier servers, so no external
+      // tool is silently overwritten on collision. The returned count drives
+      // whether this server's prompt guidance is included (≥1 tool merged).
+      const merged = this.mergeNamespaced(
+        tools,
+        result.guarded,
+        server.name,
+        server.id,
+      );
+      outcomes.push({ name: server.name, ok: true });
+      // Include this server's guidance ONLY when it actually contributed at
+      // least one tool the agent can call (allowlist may have filtered all of
+      // them out) AND the admin authored non-blank instructions. The header
+      // prefix is the sanitized server name (= the tool namespace prefix).
+      const guide = server.instructions?.trim();
+      if (merged.count > 0 && guide) {
+        instructions.push({
+          serverName: server.name,
+          toolPrefix: merged.prefix,
+          instructions: guide,
+        });
       }
     }
 
@@ -523,12 +556,12 @@ export function validateResolvedAddresses(addrs: readonly LookupAddress[]): {
  */
 function buildPinnedDispatcher(): Agent {
   // External-MCP traffic uses a DEDICATED, shorter silence timeout
-  // (`AI_MCP_STREAM_TIMEOUT_MS`, default 5 min) — deliberately tighter than the
+  // (`AI_MCP_STREAM_TIMEOUT_MS`, default 1 min) — deliberately tighter than the
   // chat provider's 15-min `streamTimeoutMs()` — so a byte-silent/hung MCP
-  // upstream is broken in ~5 min instead of 15. We keep the keep-alive options
+  // upstream is broken in ~1 min instead of 15. We keep the keep-alive options
   // from `streamingDispatcherOptions()` but OVERRIDE headers/body timeouts.
   // Accepted trade-off: a legitimately long but byte-silent single tool call,
-  // and an SSE transport idling >5 min BETWEEN tool calls, are also cut here; the
+  // and an SSE transport idling >1 min BETWEEN tool calls, are also cut here; the
   // per-call total cap (wrapToolsWithCallTimeout, `AI_MCP_CALL_TIMEOUT_MS`) is the
   // complementary guard for chatty-but-stuck calls that keep the socket warm yet
   // never return.

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

@@ -52,7 +52,7 @@ export class CreateAgentRoleDto {
   description?: string;
 
   @IsString()
-  @MaxLength(20000)
+  @MaxLength(100000)
   instructions: string;
 
   // null/omitted => use the workspace default model.
@@ -102,7 +102,7 @@ export class UpdateAgentRoleDto {
 
   @IsOptional()
   @IsString()
-  @MaxLength(20000)
+  @MaxLength(100000)
   instructions?: string;
 
   @IsOptional()

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

@@ -652,6 +652,125 @@ describe('AiChatToolsService #294 changed execute wirings', () => {
   });
 });
 
+/**
+ * #410 — the footnote + image tools were promoted from MCP-only into the shared
+ * registry and are now wired in-app. Assert they are REGISTERED in the in-app
+ * toolset and forward their args to the client with the correct arg->method
+ * mapping (the schema fields `imageUrl`/`attachmentId` map onto the client's
+ * positional `url`/`oldAttachmentId`). A field destructured under the wrong name
+ * would silently pass `undefined` (execute is `any`-cast, so tsc won't catch it).
+ */
+describe('AiChatToolsService #410 footnote + image tools', () => {
+  const calls: Record<string, unknown[][]> = {
+    insertFootnote: [],
+    insertImage: [],
+    replaceImage: [],
+  };
+  const fakeClient: Partial<DocmostClientLike> = {
+    insertFootnote: (...args: unknown[]) => {
+      calls.insertFootnote.push(args);
+      return Promise.resolve({ success: true, footnoteId: 'fn1', reused: false });
+    },
+    insertImage: (...args: unknown[]) => {
+      calls.insertImage.push(args);
+      return Promise.resolve({ success: true, attachmentId: 'att1' });
+    },
+    replaceImage: (...args: unknown[]) => {
+      calls.replaceImage.push(args);
+      return Promise.resolve({ success: true, replaced: 1 });
+    },
+  };
+  const tokenServiceStub = {
+    generateAccessToken: jest.fn().mockResolvedValue('access-token'),
+    generateCollabToken: jest.fn().mockResolvedValue('collab-token'),
+  };
+  let service: AiChatToolsService;
+
+  beforeEach(() => {
+    for (const k of Object.keys(calls)) calls[k].length = 0;
+    jest.spyOn(loader, 'loadDocmostMcp').mockResolvedValue(
+      mockLoaded(function () {
+        return fakeClient as DocmostClientLike;
+      } as unknown as loader.DocmostClientCtor),
+    );
+    service = new AiChatToolsService(
+      tokenServiceStub as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {
+        asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
+      } as never,
+    );
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  const buildTools = () =>
+    service.forUser(
+      { id: 'user-1', email: 'u@example.com', workspaceId: 'ws-1' } as never,
+      'session-1',
+      'ws-1',
+      'chat-1',
+    );
+
+  it('registers all three tools in the in-app toolset', async () => {
+    const tools = await buildTools();
+    expect(tools.insertFootnote).toBeDefined();
+    expect(tools.insertImage).toBeDefined();
+    expect(tools.replaceImage).toBeDefined();
+  });
+
+  it('insertFootnote forwards (pageId, anchorText, text) positionally', async () => {
+    const tools = await buildTools();
+    const r = await tools.insertFootnote.execute(
+      { pageId: 'p1', anchorText: 'the claim', text: 'See source.' } as never,
+      {} as never,
+    );
+    expect(calls.insertFootnote).toEqual([['p1', 'the claim', 'See source.']]);
+    expect(r).toMatchObject({ footnoteId: 'fn1' });
+  });
+
+  it('insertImage maps imageUrl->url and packs the option fields', async () => {
+    const tools = await buildTools();
+    await tools.insertImage.execute(
+      {
+        pageId: 'p1',
+        imageUrl: 'https://x/img.png',
+        align: 'center',
+        alt: 'A',
+        replaceText: '[img]',
+        afterText: undefined,
+      } as never,
+      {} as never,
+    );
+    expect(calls.insertImage).toEqual([
+      [
+        'p1',
+        'https://x/img.png',
+        { align: 'center', alt: 'A', replaceText: '[img]', afterText: undefined },
+      ],
+    ]);
+  });
+
+  it('replaceImage maps attachmentId->oldAttachmentId and imageUrl->url', async () => {
+    const tools = await buildTools();
+    await tools.replaceImage.execute(
+      {
+        pageId: 'p1',
+        attachmentId: 'att-old',
+        imageUrl: 'https://x/new.png',
+        align: 'right',
+        alt: 'B',
+      } as never,
+      {} as never,
+    );
+    expect(calls.replaceImage).toEqual([
+      ['p1', 'att-old', 'https://x/new.png', { align: 'right', alt: 'B' }],
+    ]);
+  });
+});
+
 /**
  * getCurrentPage selection contract (#388): the tool surfaces the selection that
  * was sanitized + nested onto the resolved open-page context (last forUser arg).

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

@@ -697,6 +697,38 @@ export class AiChatToolsService {
         },
       ),
 
+      // Schema + description live in @docmost/mcp's SHARED_TOOL_SPECS (#410).
+      // Promoted from MCP-only so the in-app agent can attach a REAL footnote to
+      // already-written text instead of leaving a literal `^[...]` string.
+      insertFootnote: sharedTool(
+        sharedToolSpecs.insertFootnote,
+        async ({ pageId, anchorText, text }) =>
+          await client.insertFootnote(pageId, anchorText, text),
+      ),
+
+      // Schema + description live in @docmost/mcp's SHARED_TOOL_SPECS (#410).
+      // The schema field is `imageUrl`; the client method takes it positionally.
+      insertImage: sharedTool(
+        sharedToolSpecs.insertImage,
+        async ({ pageId, imageUrl, align, alt, replaceText, afterText }) =>
+          await client.insertImage(pageId, imageUrl, {
+            align,
+            alt,
+            replaceText,
+            afterText,
+          }),
+      ),
+
+      // Schema + description live in @docmost/mcp's SHARED_TOOL_SPECS (#410).
+      replaceImage: sharedTool(
+        sharedToolSpecs.replaceImage,
+        async ({ pageId, attachmentId, imageUrl, align, alt }) =>
+          await client.replaceImage(pageId, attachmentId, imageUrl, {
+            align,
+            alt,
+          }),
+      ),
+
       // Schema + description now live in @docmost/mcp's SHARED_TOOL_SPECS (#294).
       // The table reference parameter was unified to `table` (was `tableRef`).
       tableInsertRow: sharedTool(

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

@@ -141,6 +141,33 @@ export interface DocmostClientLike {
     doc?: unknown,
     title?: string,
   ): Promise<Record<string, unknown>>;
+  // Attach an author-inline footnote after the first occurrence of anchorText;
+  // numbering + the footnotes list are derived server-side.
+  insertFootnote(
+    pageId: string,
+    anchorText: string,
+    text: string,
+  ): Promise<Record<string, unknown>>;
+  // Download a web image and insert it into the page (append, or replace/after a
+  // text anchor). `url` is the image http(s) URL.
+  insertImage(
+    pageId: string,
+    url: string,
+    opts?: {
+      align?: 'left' | 'center' | 'right';
+      alt?: string;
+      replaceText?: string;
+      afterText?: string;
+    },
+  ): Promise<Record<string, unknown>>;
+  // Swap an existing image (by its attachmentId) for a new one fetched from a web
+  // URL, repointing every reference in the live document.
+  replaceImage(
+    pageId: string,
+    oldAttachmentId: string,
+    url: string,
+    opts?: { align?: 'left' | 'center' | 'right'; alt?: string },
+  ): Promise<Record<string, unknown>>;
   tableInsertRow(
     pageId: string,
     tableRef: string,

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

@@ -27,13 +27,26 @@ import type { DocmostClientLike } from './docmost-client.loader';
  */
 
 describe('tool tier metadata (#332)', () => {
-  it('core set is the documented 13 + searchInPage (14)', () => {
-    expect(CORE_TOOL_KEYS).toHaveLength(14);
+  it('core set is the documented 13 + searchInPage + insertFootnote (15)', () => {
+    expect(CORE_TOOL_KEYS).toHaveLength(15);
     expect(CORE_TOOL_SET.has('searchInPage')).toBe(true); // #330, promoted to core
+    expect(CORE_TOOL_SET.has('insertFootnote')).toBe(true); // #410, promoted to core
     // loadTools is a meta-tool, not a normal core key.
     expect(CORE_TOOL_SET.has(LOAD_TOOLS_NAME)).toBe(false);
   });
 
+  it('#410 image tools are DEFERRED, footnote tool is CORE', () => {
+    // insert_footnote is core (symmetric with editPageText); the image tools stay
+    // deferred (rare, fat — loaded on demand). Assert both the spec tier and the
+    // CORE_TOOL_SET membership so a future tier edit that desyncs them fails here.
+    expect(SHARED_TOOL_SPECS.insertFootnote.tier).toBe('core');
+    expect(CORE_TOOL_SET.has('insertFootnote')).toBe(true);
+    expect(SHARED_TOOL_SPECS.insertImage.tier).toBe('deferred');
+    expect(CORE_TOOL_SET.has('insertImage')).toBe(false);
+    expect(SHARED_TOOL_SPECS.replaceImage.tier).toBe('deferred');
+    expect(CORE_TOOL_SET.has('replaceImage')).toBe(false);
+  });
+
   it('SHARED_TOOL_SPECS tier agrees with CORE_TOOL_SET for every shared tool', () => {
     for (const [key, spec] of Object.entries(SHARED_TOOL_SPECS)) {
       const isCoreByTier = spec.tier === 'core';

apps/server/src/core/ai-chat/tools/tool-tiers.ts

@@ -38,10 +38,13 @@ export interface ToolCatalogEntry {
 }
 
 /**
- * CORE (always-active) in-app tool keys — 13 frequent/tiny tools. `searchInPage`
- * (#330) is added to core on top of the issue's original tier list: it is
- * frequent for the editorial roles this feature targets. `loadTools` is active
- * too but is not a normal tool key (it is added to activeTools separately).
+ * CORE (always-active) in-app tool keys — 13 frequent/tiny tools + `searchInPage`
+ * (#330) + `insertFootnote` (#410). `searchInPage` is core because it is frequent
+ * for the editorial roles this feature targets; `insertFootnote` is core so the
+ * footnote tool is NOT hidden while its natural sibling `editPageText` is always
+ * active (that asymmetry is exactly what pushed the agent to write literal
+ * `^[...]`). `loadTools` is active too but is not a normal tool key (it is added
+ * to activeTools separately).
  */
 export const CORE_TOOL_KEYS = [
   'searchPages',
@@ -60,6 +63,9 @@ export const CORE_TOOL_KEYS = [
   // #330 search_in_page — frequent for editorial sweeps; core despite predating
   // the issue's tier list.
   'searchInPage',
+  // #410 insert_footnote — core so pinpoint citations to already-written text
+  // don't degrade into literal `^[...]`; kept symmetric with editPageText.
+  'insertFootnote',
 ] as const;
 
 /** O(1) membership test for the core tier. */

apps/server/src/integrations/ai/ai-streaming-fetch.ts

@@ -123,19 +123,19 @@ export function streamKeepAliveMs(): number {
   return positiveEnv('AI_STREAM_KEEPALIVE_MS', DEFAULT_STREAM_KEEPALIVE_MS);
 }
 
-/** Default SILENCE timeout for EXTERNAL-MCP transport (5 min). */
-const DEFAULT_MCP_STREAM_TIMEOUT_MS = 300_000;
+/** Default SILENCE timeout for EXTERNAL-MCP transport (1 min). */
+const DEFAULT_MCP_STREAM_TIMEOUT_MS = 60_000;
 
-/** Default total wall-clock cap for ONE external MCP tool call (15 min). */
-const DEFAULT_MCP_CALL_TIMEOUT_MS = 900_000;
+/** Default total wall-clock cap for ONE external MCP tool call (2 min). */
+const DEFAULT_MCP_CALL_TIMEOUT_MS = 120_000;
 
 /**
  * SILENCE timeout (ms) for EXTERNAL-MCP transport ONLY. Override with
  * `AI_MCP_STREAM_TIMEOUT_MS`; a missing/invalid/non-positive value falls back to
- * {@link DEFAULT_MCP_STREAM_TIMEOUT_MS} (5 min).
+ * {@link DEFAULT_MCP_STREAM_TIMEOUT_MS} (1 min).
  *
  * Deliberately tighter than the chat provider's {@link streamTimeoutMs} (15 min)
- * so a byte-silent/hung MCP upstream is broken in ~5 min instead of 15. This is
+ * so a byte-silent/hung MCP upstream is broken in ~1 min instead of 15. This is
  * the undici `headersTimeout`/`bodyTimeout` for the external-MCP dispatcher only
  * — it must NOT change the chat provider, which legitimately needs 15 min between
  * reasoning chunks (#175).
@@ -153,7 +153,7 @@ export function mcpStreamTimeoutMs(): number {
 /**
  * Total wall-clock cap (ms) for ONE external MCP tool call — APP-LEVEL, not
  * transport. Override with `AI_MCP_CALL_TIMEOUT_MS`; a missing/invalid/
- * non-positive value falls back to {@link DEFAULT_MCP_CALL_TIMEOUT_MS} (15 min).
+ * non-positive value falls back to {@link DEFAULT_MCP_CALL_TIMEOUT_MS} (2 min).
  *
  * Catches a tool that keeps the connection warm (SSE heartbeats / trickle) but
  * never returns a result — which the transport silence timeout

apps/server/src/integrations/mcp/mcp-auth.helpers.ts

@@ -149,6 +149,15 @@ export type DocmostMcpConfig = (
     has?: (uri: string) => boolean;
     evict?: (uri: string) => void;
   };
+  // Dependency-neutral metrics sink injected by McpService (mirror of the
+  // package's onMetric). The package emits generic (name, value, labels)
+  // samples; McpService maps them onto the prom-client registry. Undefined
+  // when metrics are disabled → the package no-ops.
+  onMetric?: (
+    name: string,
+    value: number,
+    labels?: Record<string, string>,
+  ) => void;
 };
 
 export interface ResolvedMcpAuth {

apps/server/src/integrations/mcp/mcp.service.ts

@@ -30,6 +30,11 @@ import {
   ResolvedMcpAuth,
 } from './mcp-auth.helpers';
 import { SandboxStore } from '../sandbox/sandbox.store';
+import {
+  isMetricsEnabled,
+  observeMcpTool,
+  incConnectTimeout,
+} from '../metrics/metrics.registry';
 
 // Minimal shape of the embedded MCP HTTP handler exported by @docmost/mcp/http.
 interface McpHttpHandler {
@@ -331,7 +336,31 @@ export class McpService implements OnModuleDestroy {
             // can store blobs in the shared in-RAM store regardless of which
             // credential variant resolved. The sink (put/has/evict + uri↔id
             // mapping) is owned by SandboxStore.asSink().
-            return { ...resolved.config, sandbox: this.sandboxStore.asSink() };
+            // Route the package's dependency-neutral metric samples onto the
+            // prom-client registry. When metrics are disabled, onMetric is
+            // undefined → the package's tool-timer/timeout hooks are a
+            // negligible-overhead no-op: the registerTool wrapper still runs a
+            // performance.now() + async try/finally per tool call, but the
+            // `onMetric?.()` short-circuits so no label/object is built. (Cost
+            // is immaterial at LLM tool-call rate.) labels?.tool is guarded
+            // defensively (the tool wrapper always sets it).
+            return {
+              ...resolved.config,
+              sandbox: this.sandboxStore.asSink(),
+              onMetric: isMetricsEnabled()
+                ? (
+                    name: string,
+                    value: number,
+                    labels?: Record<string, string>,
+                  ) => {
+                    if (name === 'mcp_tool_duration_seconds') {
+                      observeMcpTool(labels?.tool ?? 'other', value);
+                    } else if (name === 'collab_connect_timeouts_total') {
+                      incConnectTimeout();
+                    }
+                  }
+                : undefined,
+            };
           },
           {
             identify: (req: IncomingMessage) => {

apps/server/src/integrations/metrics/metrics.constants.ts

@@ -2,6 +2,11 @@
  * Perf-metrics contract (#355). These names/labels are FIXED by the already
  * deployed scrape+dashboard infra (VictoriaMetrics scraping docmost:9464,
  * Grafana dashboards, alerts). Do NOT rename them.
+ *
+ * #402 extends the #355 table with the collab-lifecycle + MCP-tool families
+ * (grouped below). These are the fixed contract from #402; same "do not rename"
+ * rule applies. Server-side families land in Pass 1; the MCP-tool histogram is
+ * fed by the MCP callback in a later pass but its NAME is fixed here now.
  */
 export const METRIC_HTTP_REQUEST_DURATION = 'http_request_duration_seconds';
 export const METRIC_DB_QUERY_DURATION = 'db_query_duration_seconds';
@@ -9,6 +14,17 @@ export const METRIC_BULLMQ_QUEUE_DEPTH = 'bullmq_queue_depth';
 export const METRIC_BULLMQ_JOB_DURATION = 'bullmq_job_duration_seconds';
 export const METRIC_COLLAB_STORE_DURATION = 'collab_store_duration_seconds';
 
+// #402 additions — collaboration lifecycle + MCP tool timing.
+export const METRIC_COLLAB_LOAD_DURATION = 'collab_doc_load_duration_seconds';
+export const METRIC_COLLAB_DOCS_OPEN = 'collab_docs_open';
+export const METRIC_COLLAB_DOC_LOADS_TOTAL = 'collab_doc_loads_total';
+export const METRIC_COLLAB_DOC_UNLOADS_TOTAL = 'collab_doc_unloads_total';
+export const METRIC_COLLAB_CONNECT_DURATION = 'collab_connect_duration_seconds';
+export const METRIC_COLLAB_CONNECT_TIMEOUTS_TOTAL =
+  'collab_connect_timeouts_total';
+export const METRIC_COLLAB_AUTH_DURATION = 'collab_auth_duration_seconds';
+export const METRIC_MCP_TOOL_DURATION = 'mcp_tool_duration_seconds';
+
 // Histogram buckets (seconds). Chosen to give useful p50/p95/p99 resolution
 // for typical web/DB latencies without exploding series cardinality.
 export const HTTP_BUCKETS = [
@@ -23,6 +39,12 @@ export const COLLAB_BUCKETS = [
 export const JOB_BUCKETS = [
   0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120,
 ];
+// #402 — MCP tool-call latency. Same shape as COLLAB_BUCKETS but stretched to
+// 10s at the top: an MCP tool round-trip (LLM-driven doc ops) can be slower
+// than a single collab store, so keep resolution out to 10s.
+export const MCP_TOOL_BUCKETS = [
+  0.005, 0.025, 0.1, 0.25, 0.5, 1, 2.5, 5, 10,
+];
 
 /**
  * Extract the first SQL token (select/insert/update/delete/...) from a query,
@@ -58,6 +80,30 @@ export function firstSqlToken(sql: string | undefined): string {
   return KNOWN_SQL_TOKENS.has(token) ? token : 'other';
 }
 
+/**
+ * #402 — bucket a document byte size into ONE of four fixed labels for the
+ * collab load/store histograms' `size_bucket` label. Using the raw byte count
+ * would be a continuous, unbounded label; four coarse buckets keep series
+ * cardinality bounded (each of collab_doc_load / collab_store gets ×4 series).
+ *
+ * The SAME function is shared by both the load and store paths so their buckets
+ * can never drift apart. Non-finite / negative sizes collapse to the smallest
+ * bucket ('lt64k') as a safe default (they can't be legitimately huge and we
+ * must never throw here — this runs on every store/load when metrics are on).
+ */
+// Module-const thresholds, built once (not per observe).
+const SIZE_THRESHOLDS = { lt64k: 65536, lt256k: 262144, lt1m: 1048576 } as const;
+
+export function sizeBucket(
+  bytes: number | undefined | null,
+): 'lt64k' | 'lt256k' | 'lt1m' | 'ge1m' {
+  if (bytes == null || !Number.isFinite(bytes) || bytes < 0) return 'lt64k';
+  if (bytes < SIZE_THRESHOLDS.lt64k) return 'lt64k';
+  if (bytes < SIZE_THRESHOLDS.lt256k) return 'lt256k';
+  if (bytes < SIZE_THRESHOLDS.lt1m) return 'lt1m';
+  return 'ge1m';
+}
+
 /**
  * Whether an HTTP response must be EXCLUDED from http_request_duration_seconds.
  *

apps/server/src/integrations/metrics/metrics.registry.ts

@@ -1,5 +1,6 @@
 import {
   collectDefaultMetrics,
+  Counter,
   Histogram,
   Gauge,
   Registry,
@@ -9,11 +10,21 @@ import {
   DB_BUCKETS,
   HTTP_BUCKETS,
   JOB_BUCKETS,
+  MCP_TOOL_BUCKETS,
   METRIC_BULLMQ_JOB_DURATION,
   METRIC_BULLMQ_QUEUE_DEPTH,
+  METRIC_COLLAB_AUTH_DURATION,
+  METRIC_COLLAB_CONNECT_DURATION,
+  METRIC_COLLAB_CONNECT_TIMEOUTS_TOTAL,
+  METRIC_COLLAB_DOC_LOADS_TOTAL,
+  METRIC_COLLAB_DOC_UNLOADS_TOTAL,
+  METRIC_COLLAB_DOCS_OPEN,
+  METRIC_COLLAB_LOAD_DURATION,
   METRIC_COLLAB_STORE_DURATION,
   METRIC_DB_QUERY_DURATION,
   METRIC_HTTP_REQUEST_DURATION,
+  METRIC_MCP_TOOL_DURATION,
+  sizeBucket,
 } from './metrics.constants';
 
 /**
@@ -39,7 +50,24 @@ let httpHist: Histogram<'method' | 'route' | 'status'> | null = null;
 let dbHist: Histogram<'op'> | null = null;
 let queueDepthGauge: Gauge<'queue'> | null = null;
 let jobHist: Histogram<'queue'> | null = null;
-let collabHist: Histogram | null = null;
+// #402 — collab store now carries a size_bucket label (see sizeBucket()).
+let collabHist: Histogram<'size_bucket'> | null = null;
+// #402 collab-lifecycle + MCP instruments.
+let collabLoadHist: Histogram<'size_bucket'> | null = null;
+let docsOpenGauge: Gauge | null = null;
+let docLoadsCounter: Counter | null = null;
+let docUnloadsCounter: Counter | null = null;
+let connectTimeoutsCounter: Counter | null = null;
+let collabConnectHist: Histogram | null = null;
+let collabAuthHist: Histogram | null = null;
+let mcpToolHist: Histogram<'tool'> | null = null;
+
+// #402 — read-on-scrape source for collab_docs_open. The gauge is NEVER
+// inc/dec'd (that drifts under crashes/handoffs); instead its collect() callback
+// pulls the authoritative live count from here on every scrape. Registered once,
+// gated, by the collaboration gateway via registerDocsOpenSource(). Null until
+// then → the collect() is a no-op.
+let docsOpenSource: (() => number) | null = null;
 
 function init(): void {
   if (registry || !enabled) return;
@@ -82,10 +110,71 @@ function init(): void {
 
   collabHist = new Histogram({
     name: METRIC_COLLAB_STORE_DURATION,
-    help: 'Collaboration onStoreDocument duration in seconds',
+    help: 'Collaboration onStoreDocument duration in seconds, by document size bucket',
+    labelNames: ['size_bucket'],
     buckets: COLLAB_BUCKETS,
     registers: [registry],
   });
+
+  collabLoadHist = new Histogram({
+    name: METRIC_COLLAB_LOAD_DURATION,
+    help: 'Collaboration onLoadDocument DB-load duration in seconds, by document size bucket',
+    labelNames: ['size_bucket'],
+    buckets: COLLAB_BUCKETS,
+    registers: [registry],
+  });
+
+  docsOpenGauge = new Gauge({
+    name: METRIC_COLLAB_DOCS_OPEN,
+    help: 'Number of collaboration documents currently open in memory',
+    registers: [registry],
+    // Read-on-scrape: pull the live count from the registered source (the
+    // hocuspocus instance) so the value can never drift. No-op until a source
+    // is registered.
+    collect() {
+      if (docsOpenSource) this.set(docsOpenSource());
+    },
+  });
+
+  docLoadsCounter = new Counter({
+    name: METRIC_COLLAB_DOC_LOADS_TOTAL,
+    help: 'Total collaboration documents loaded into memory',
+    registers: [registry],
+  });
+
+  docUnloadsCounter = new Counter({
+    name: METRIC_COLLAB_DOC_UNLOADS_TOTAL,
+    help: 'Total collaboration documents unloaded from memory',
+    registers: [registry],
+  });
+
+  connectTimeoutsCounter = new Counter({
+    name: METRIC_COLLAB_CONNECT_TIMEOUTS_TOTAL,
+    help: 'Total collaboration connection setup timeouts',
+    registers: [registry],
+  });
+
+  collabConnectHist = new Histogram({
+    name: METRIC_COLLAB_CONNECT_DURATION,
+    help: 'Collaboration connection acceptance duration in seconds (onConnect→connected)',
+    buckets: COLLAB_BUCKETS,
+    registers: [registry],
+  });
+
+  collabAuthHist = new Histogram({
+    name: METRIC_COLLAB_AUTH_DURATION,
+    help: 'Collaboration onAuthenticate duration in seconds',
+    buckets: COLLAB_BUCKETS,
+    registers: [registry],
+  });
+
+  mcpToolHist = new Histogram({
+    name: METRIC_MCP_TOOL_DURATION,
+    help: 'MCP tool-call duration in seconds, by tool name',
+    labelNames: ['tool'],
+    buckets: MCP_TOOL_BUCKETS,
+    registers: [registry],
+  });
 }
 
 // Runs once when this module is first imported. Safe to call again (idempotent).
@@ -121,6 +210,46 @@ export function observeJobDuration(queue: string, seconds: number): void {
   jobHist?.observe({ queue }, seconds);
 }
 
-export function observeCollabStore(seconds: number): void {
-  collabHist?.observe(seconds);
+export function observeCollabStore(bytes: number, seconds: number): void {
+  collabHist?.observe({ size_bucket: sizeBucket(bytes) }, seconds);
+}
+
+export function observeCollabLoad(bytes: number, seconds: number): void {
+  collabLoadHist?.observe({ size_bucket: sizeBucket(bytes) }, seconds);
+}
+
+/**
+ * Register the live open-document count source for the collab_docs_open gauge.
+ * Called ONCE, gated by isMetricsEnabled(), by the collaboration gateway. The
+ * gauge reads this on every scrape (collect()); nothing inc/dec's it.
+ */
+export function registerDocsOpenSource(fn: () => number): void {
+  docsOpenSource = fn;
+}
+
+export function incDocLoad(): void {
+  docLoadsCounter?.inc();
+}
+
+export function incDocUnload(): void {
+  docUnloadsCounter?.inc();
+}
+
+export function incConnectTimeout(): void {
+  connectTimeoutsCounter?.inc();
+}
+
+export function observeCollabConnect(seconds: number): void {
+  collabConnectHist?.observe(seconds);
+}
+
+export function observeCollabAuth(seconds: number): void {
+  collabAuthHist?.observe(seconds);
+}
+
+export function observeMcpTool(tool: string, seconds: number): void {
+  // `tool` MUST be a bounded, registration-derived MCP tool name (the caller
+  // guarantees it comes from the registered-tool set) — never free-form input —
+  // so this label stays low-cardinality with no 'other' bucketing needed.
+  mcpToolHist?.observe({ tool }, seconds);
 }

apps/server/src/integrations/metrics/metrics.spec.ts

@@ -1,6 +1,23 @@
 import { FastifyRequest } from 'fastify';
 import { resolveRouteLabel } from './http-metrics.hook';
-import { firstSqlToken, isStreamingResponse } from './metrics.constants';
+import {
+  firstSqlToken,
+  isStreamingResponse,
+  sizeBucket,
+} from './metrics.constants';
+import {
+  getMetricsRegistry,
+  incConnectTimeout,
+  incDocLoad,
+  incDocUnload,
+  isMetricsEnabled,
+  observeCollabAuth,
+  observeCollabConnect,
+  observeCollabLoad,
+  observeCollabStore,
+  observeMcpTool,
+  registerDocsOpenSource,
+} from './metrics.registry';
 
 describe('resolveRouteLabel (histogram route label)', () => {
   it('uses the ROUTE TEMPLATE, never the raw URL', () => {
@@ -123,3 +140,67 @@ describe('firstSqlToken (bounded db label)', () => {
     expect(firstSqlToken('vacuum analyze')).toBe('other');
   });
 });
+
+describe('sizeBucket (#402 bounded size label)', () => {
+  it('maps sizes to the four fixed buckets at their boundaries', () => {
+    // Boundaries are exclusive-upper: <65536 → lt64k, etc.
+    expect(sizeBucket(0)).toBe('lt64k');
+    expect(sizeBucket(65535)).toBe('lt64k');
+    expect(sizeBucket(65536)).toBe('lt256k');
+    expect(sizeBucket(262143)).toBe('lt256k');
+    expect(sizeBucket(262144)).toBe('lt1m');
+    expect(sizeBucket(1048575)).toBe('lt1m');
+    expect(sizeBucket(1048576)).toBe('ge1m');
+    expect(sizeBucket(5_000_000)).toBe('ge1m');
+  });
+
+  it('falls back to the smallest bucket for invalid sizes', () => {
+    // Non-finite / negative / nullish collapse to the smallest, safe default.
+    expect(sizeBucket(-1)).toBe('lt64k');
+    expect(sizeBucket(NaN)).toBe('lt64k');
+    expect(sizeBucket(Infinity)).toBe('lt64k');
+    expect(sizeBucket(undefined)).toBe('lt64k');
+    expect(sizeBucket(null)).toBe('lt64k');
+  });
+
+  it('only ever returns one of the four fixed labels (bounded cardinality)', () => {
+    const labels = new Set(
+      [0, 65536, 262144, 1048576, -5, NaN].map((b) => sizeBucket(b)),
+    );
+    for (const l of labels) {
+      expect(['lt64k', 'lt256k', 'lt1m', 'ge1m']).toContain(l);
+    }
+  });
+});
+
+describe('metrics helpers are safe no-ops when METRICS_PORT is unset', () => {
+  // These specs run without METRICS_PORT, so the registry is never created and
+  // every observe/inc/set helper must be a cheap `?.` no-op that never throws.
+  beforeAll(() => {
+    // Guard the contract this suite depends on: if a CI env set METRICS_PORT,
+    // the assertions below would be meaningless, so fail loudly instead.
+    expect(process.env.METRICS_PORT).toBeUndefined();
+  });
+
+  it('reports metrics disabled and a null registry', () => {
+    expect(isMetricsEnabled()).toBe(false);
+    expect(getMetricsRegistry()).toBeNull();
+  });
+
+  it('does not throw from any #402 collab/MCP helper', () => {
+    expect(() => {
+      observeCollabLoad(123456, 0.01);
+      observeCollabStore(123456, 0.02);
+      observeCollabConnect(0.03);
+      observeCollabAuth(0.04);
+      observeMcpTool('some-tool', 0.05);
+      incDocLoad();
+      incDocUnload();
+      incConnectTimeout();
+      // Registering a source must not create the gauge or invoke the fn.
+      registerDocsOpenSource(() => {
+        throw new Error('docsOpenSource must NOT be called when disabled');
+      });
+    }).not.toThrow();
+  });
+});

apps/server/src/main.ts

@@ -21,10 +21,24 @@ import { recordHttpResponse } from './integrations/metrics/http-metrics.hook';
 import { startMetricsServer } from './integrations/metrics/metrics.server';
 
 async function bootstrap() {
+  // Fastify JSON body cap. Fastify defaults to 1 MiB, which a long AI-chat
+  // research turn exceeds: the client resends the FULL message history (every
+  // tool call + search result) on each turn, so a deep conversation's POST to
+  // /api/ai-chat/stream can be several MB and would otherwise be rejected with
+  // FST_ERR_CTP_BODY_TOO_LARGE (413). Raise the cap; override with
+  // HTTP_JSON_BODY_LIMIT (bytes). A missing/invalid/non-positive value keeps the
+  // 25 MiB default. Multipart uploads are unaffected (their own @fastify/multipart
+  // limits apply); this only bounds JSON/urlencoded request bodies.
+  const bodyLimitEnv = Number(process.env.HTTP_JSON_BODY_LIMIT);
+  const bodyLimit =
+    Number.isFinite(bodyLimitEnv) && bodyLimitEnv > 0
+      ? bodyLimitEnv
+      : 25 * 1024 * 1024;
   const app = await NestFactory.create<NestFastifyApplication>(
     AppModule,
     new FastifyAdapter({
       trustProxy: resolveTrustProxy(process.env.TRUST_PROXY),
+      bodyLimit,
       routerOptions: {
         maxParamLength: 1000,
         ignoreTrailingSlash: true,

docs/reading-ai-logs.md

@@ -0,0 +1,270 @@
+# Reading the AI dialog logs (how agents call tools, and where they fail)
+
+How to inspect the agent conversation history in the database — and, more
+importantly, the **one non-obvious trap that will make you report the wrong
+answer**: the persisted history *silently hides hard tool failures*. Written from
+real pain (a "which tools fail most?" analysis that confidently answered
+"patchNode: 0 errors" while the UI was visibly full of red `patchNode` failures).
+
+Read the **Gotchas** section before you trust any error count.
+
+## TL;DR
+
+- Agent chats live in Postgres, DB `docmost`, tables `ai_chat_*`.
+- Each tool invocation is stored as **two** array elements (a `tool-call` part and
+  a `tool-result` part), so naive counting double-counts.
+- **A tool that *throws* writes no result part at all.** Its error text is nowhere
+  in the DB — not in `tool_calls`, `content`, or `metadata`. It is shown live in
+  the UI only. So `isError` / `success=false` scans under-report by design.
+- To find where agents fail you need **three** sources: (1) soft-failure markers in
+  `tool_calls`, (2) the orphan-gap proxy for thrown errors, (3) server logs / the
+  live UI for the actual error text.
+
+## Where the data lives
+
+Host `island.lc` (`10.31.40.120`), container `gitmost-postgresql`
+(`pgvector/pgvector:pg18`), database `docmost`.
+
+```bash
+ssh island.lc
+# one-off query:
+docker exec gitmost-postgresql psql -U docmost -d docmost -P pager=off -c "SELECT ..."
+# interactive:
+docker exec -it gitmost-postgresql psql -U docmost -d docmost
+```
+
+The main app container is `gitmost` (`DATABASE_URL=postgresql://docmost:...@db:5432/docmost`).
+All workspaces (vvzvlad / wb / asakusa / …) share this **single** database — they
+are rows in `workspaces`, not separate deployments.
+
+### Relevant tables
+
+| Table | What it holds |
+| --- | --- |
+| `ai_chats` | one row per conversation (`title`, `role_id`, `page_id`, `creator_id`) |
+| `ai_chat_messages` | every message; tool calls live in `tool_calls` jsonb |
+| `ai_chat_runs` | one row per agent run (turn): `status`, `error`, `step_count` |
+| `ai_agent_roles` | agent definitions (`instructions`, `model_config`) |
+| `ai_mcp_servers` | configured MCP tool servers per workspace |
+
+`ai_chat_messages` columns that matter: `role` (`user` | `assistant` — there is **no**
+separate `tool` role), `content` (text), `tool_calls` (jsonb array), `metadata`
+(jsonb, holds run `error` + rendered `parts`), `status`, `tsv` (full-text index).
+
+## How tool calls are stored — READ THIS
+
+Tool calls are **not** one-object-per-call. Each logical invocation is split into
+two consecutive elements of the `tool_calls` array:
+
+```text
+index 0: { "toolName": "getPage",  "input":  { "pageId": "…" } }   ← tool-call   (has input, NO output)
+index 1: { "toolName": "getPage",  "output": { … } }                ← tool-result (has output, NO input)
+```
+
+The **only** keys that ever appear on an element are `toolName`, `input`, `output`.
+There is no `state`, no `errorText`, no `type`. Consequences:
+
+1. **Real invocation count = elements that have `output`.** Counting every element
+   double-counts (you get ~2× and a spurious "~50% of every tool has no output").
+2. **Pairing:** a successful call = a `tool-call` part followed by its `tool-result`
+   part. Both carry `toolName`, so you can group by tool on either.
+
+## The two classes of failure (and which the DB can see)
+
+### 1. Soft failures — tool RAN and returned an error-shaped result → PERSISTED ✅
+
+These are visible in the `tool-result` `output`. The marker differs per tool:
+
+| Tool(s) | Error marker in `output` |
+| --- | --- |
+| `editPageText` | `failed` is a **non-empty** array of `{find, reason}` (e.g. `text not found in the document`, `matches N times — provide a longer fragment or set replaceAll`). Also a soft `warning` when the `find` string contained markdown that only matched after stripping. |
+| `semanticSearch` | `{ "unavailable": true, "reason": "semantic search unavailable" }` (feature/infra, not the agent's fault) |
+| MCP passthrough (`Habr_*`, some `Search_*`) | `output` is an **array** (raw MCP content) whose text starts with `Error executing tool … validation error …` |
+| generic | `output.isError = true` or `output.success = false` |
+
+Note `editPageText` returns `failed: []` on success — filtering on the *presence*
+of the key gives false positives; filter on **non-empty**.
+
+### 2. Hard failures — tool THREW → NOT PERSISTED ❌ (the trap)
+
+When a tool throws (the classic one is `patchNode` / `insertNode` / `tableUpdateCell`
+→ `Failed to encode document to Yjs (fromJSON): Unknown node type: undefined`), the
+runtime writes **no `tool-result` part**. The orphaned `tool-call` part stays, but
+the error text is **nowhere in the DB**. It is streamed to the UI live and (until
+rotation) to server logs — that is it.
+
+So any query like `count(*) FILTER (WHERE output.success = false)` will happily
+return **0** for `patchNode` even when the chat is visibly full of red failures.
+That is survivorship bias, not reliability.
+
+The only DB-side proxy for a thrown error is an **orphan**: a `tool-call` part with
+no matching `tool-result`. Caveat: orphans also appear when a run is **aborted**
+mid-flight (server restart), so a high-volume tool (`createComment`, `searchInPage`,
+`Search_web_search`) shows orphans from aborts, not from real errors. Treat the
+orphan gap as an *upper bound* on hard errors, and cross-check the tool: a gap on a
+structural editor (`patchNode`, `insertNode`, `updatePageJson`, `transformPage`) is
+almost certainly a thrown Yjs-encode error; a gap on `createComment` is mostly aborts.
+
+### 3. Run-level failures → `ai_chat_runs`
+
+`status` ∈ `succeeded | aborted | failed | running`; `error` holds the text. Seen in
+the wild: `Run interrupted by a server restart.` (aborts) and
+`Failed after N attempts. Last error: The service may be temporarily overloaded`
+(LLM provider 529). These are infra/provider, not agent tool misuse.
+
+## Ready-to-use queries
+
+Run all of these via `docker exec gitmost-postgresql psql -U docmost -d docmost -P pager=off -c "…"`.
+
+**Real invocation count per tool** (result parts only — the correct denominator):
+
+```sql
+SELECT elem->>'toolName' AS tool, count(*) AS calls
+FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
+WHERE jsonb_typeof(m.tool_calls) = 'array' AND elem ? 'output'
+GROUP BY 1 ORDER BY 2 DESC;
+```
+
+**Soft errors per tool** (everything the DB can honestly see):
+
+```sql
+WITH res AS (
+  SELECT elem->>'toolName' AS tool, elem->'output' AS o
+  FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
+  WHERE jsonb_typeof(m.tool_calls) = 'array' AND elem ? 'output'
+)
+SELECT tool, count(*) AS calls,
+       sum(COALESCE(
+         (o->>'isError') = 'true'
+         OR (o->>'success') = 'false'
+         OR (jsonb_typeof(o->'failed') = 'array' AND o->'failed' <> '[]'::jsonb)
+         OR (o->>'unavailable') = 'true'
+         OR o::text ~* 'error executing tool|validation error'
+       , false)::int) AS soft_errors
+FROM res GROUP BY tool HAVING sum(COALESCE(
+         (o->>'isError') = 'true' OR (o->>'success') = 'false'
+         OR (jsonb_typeof(o->'failed') = 'array' AND o->'failed' <> '[]'::jsonb)
+         OR (o->>'unavailable') = 'true' OR o::text ~* 'error executing tool|validation error'
+       , false)::int) > 0
+ORDER BY soft_errors DESC;
+```
+
+**`editPageText` failure reasons** (the most common real agent mistake — bad `find`):
+
+```sql
+WITH res AS (
+  SELECT elem->'output' AS o
+  FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
+  WHERE jsonb_typeof(m.tool_calls) = 'array'
+    AND elem->>'toolName' = 'editPageText' AND elem ? 'output'
+)
+SELECT f->>'reason' AS reason, count(*)
+FROM res, jsonb_array_elements(o->'failed') f
+WHERE jsonb_typeof(o->'failed') = 'array'
+GROUP BY 1 ORDER BY 2 DESC;
+```
+
+**Hard-error proxy — orphan gap per tool, WITH a spread column** (call parts minus
+result parts, plus how many distinct chats the gap is spread across):
+
+```sql
+WITH parts AS (
+  SELECT m.chat_id, elem->>'toolName' AS tool,
+         (elem ? 'input' AND NOT (elem ? 'output')) AS is_call,
+         (elem ? 'output')                          AS is_result
+  FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
+  WHERE jsonb_typeof(m.tool_calls) = 'array' AND m.role = 'assistant'
+),
+per_chat AS (
+  SELECT tool, chat_id, sum(is_call::int) - sum(is_result::int) AS gap
+  FROM parts GROUP BY tool, chat_id
+)
+SELECT tool,
+       sum(gap) FILTER (WHERE gap > 0)   AS missing_results,
+       count(*) FILTER (WHERE gap > 0)   AS chats_spread,   -- disambiguates!
+       max(gap)                          AS worst_single_chat
+FROM per_chat GROUP BY tool
+HAVING sum(gap) FILTER (WHERE gap > 0) > 0
+ORDER BY missing_results DESC;
+```
+
+**`missing_results` mixes thrown errors AND aborted/interrupted runs — you cannot
+split them from `output` alone** (a positional "what follows the orphan" heuristic
+breaks on parallel tool batches, which persist as `call,call,…,result,result`). Use
+`chats_spread` to disambiguate:
+
+- **spread across many chats** (e.g. `createComment` 96 over 29 chats) → a **systemic
+  real error** (here: inline-comment anchor text not found on the page).
+- **concentrated in one chat** (e.g. `searchInPage` 55, of which 51 in a single chat)
+  → **one runaway/aborted session**, not a real per-call error — discount it.
+- a gap on a **structural editor** (`patchNode`, `insertNode`, `tableUpdateCell`,
+  `updatePageJson`, `transformPage`) is almost always a thrown Yjs-encode error.
+
+**Run-level failures:**
+
+```sql
+SELECT status, count(*), min(error) AS sample_error
+FROM ai_chat_runs GROUP BY status ORDER BY 2 DESC;
+```
+
+**Full-text search across messages.** The `tsv` GIN index is built as
+`to_tsvector('english', unaccent(content))` — so it **stems English** but **not
+Russian** (Russian lexemes are stored unstemmed, so only exact word forms match).
+Most content here is Russian, so prefer `ILIKE` for substring search:
+
+```sql
+-- Russian / substring — reliable:
+SELECT chat_id, left(content, 120)
+FROM ai_chat_messages WHERE content ILIKE '%иранск%' LIMIT 20;
+
+-- English phrase — can use the index:
+SELECT chat_id, left(content, 120)
+FROM ai_chat_messages
+WHERE tsv @@ websearch_to_tsquery('english', 'some phrase') LIMIT 20;
+```
+
+## Don't blow up your context
+
+A single `tool_calls` row can be **300–400 KB** (results embed full page content and
+search payloads). Never `SELECT tool_calls` (or `jsonb_pretty(tool_calls)`) raw.
+Always project just the keys you need and truncate:
+
+```sql
+SELECT elem->>'toolName',
+       left(regexp_replace((elem->'output')::text, '\s+', ' ', 'g'), 200)
+FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
+WHERE elem ? 'output' LIMIT 5;
+```
+
+## Server logs & live UI (for the error text the DB drops)
+
+```bash
+docker logs -f --tail=100 gitmost            # main app
+docker compose -p gitmost logs -f --tail=100 # whole stack
+```
+
+Logging is `json-file`, `max-size=10m max-file=5` → ~50 MB retained, then rotated,
+and **wiped on container recreate**. So thrown-tool error text is only reliably
+caught **in real time** (or in the live chat UI, which renders the failed part with
+its message). There is no durable, queryable store of hard tool errors today — if you
+need one, that is a feature to add (persist `output-error` parts, or emit a
+`tool_calls_total{tool,status}` metric to VictoriaMetrics).
+
+## Gotchas checklist
+
+- [ ] Counting every `tool_calls` element → **2× overcount**. Count elements with `output`.
+- [ ] `isError` / `success=false` ≈ 0 does **not** mean "no errors" — thrown errors aren't persisted.
+- [ ] `editPageText.failed` is `[]` on success — test for **non-empty**, not presence.
+- [ ] Orphan gap mixes thrown errors **and** aborted runs — split by tool before concluding.
+- [ ] `aborted` runs = server restarts, `failed` runs = provider overload — not agent mistakes.
+- [ ] Never dump a raw `tool_calls` cell — it can be hundreds of KB.
+- [ ] Logs are ephemeral (≤50 MB, wiped on recreate) — grab hard-error text live.
+
+## Snapshot (2026-07-07, illustrative — rerun the queries for current numbers)
+
+- 226 chats, 732 messages, 46 runs; ~4 400 real tool invocations.
+- Soft errors (persisted): `editPageText` 4/79 (bad/non-unique `find`) + 9 markdown-in-`find` warnings; `semanticSearch` 3/4 (`unavailable`); `Habr_update_draft_from_docmost` 1/2 (`doc` sent as object, not string).
+- Missing-result proxy, read WITH the spread column:
+  - **Systemic (spread) → real errors:** `createComment` 96 over **29 chats** (comment anchor text not found — the biggest real error hotspot); `editPageText` 31 over 12 chats (+ the 4 soft above); structural-editor Yjs throws `insertNode` 10 / `updatePageContent` 9 / `tableUpdateCell` 6 / `patchNode` 5 / `updatePageJson` 2 / `transformPage` 2.
+  - **Concentrated → NOT real errors:** `searchInPage` 55 (51 in one chat); `Search_web_search` 15 & `Search_searxng_web_search` 6 (timeouts/aborts in long research sessions).
+- Runs: 34 succeeded, 10 aborted (server restart), 1 failed (provider overload).

packages/mcp/src/client.ts

@@ -40,6 +40,7 @@ import {
   deleteNodeById,
   assertUnambiguousMatch,
   insertNodeRelative,
+  blockPlainText,
   buildOutline,
   getNodeByRef,
   readTable,
@@ -59,10 +60,12 @@ import { getCollabToken, performLogin } from "./lib/auth-utils.js";
 import { diffDocs, summarizeChange } from "./lib/diff.js";
 import {
   applyAnchorInDoc,
-  canAnchorInDoc,
   countAnchorMatches,
   getAnchoredText,
+  resolveAnchorSelection,
+  normalizeForMatch,
 } from "./lib/comment-anchor.js";
+import { closestBlockHint } from "./lib/text-normalize.js";
 import {
   blockText,
   walk,
@@ -137,6 +140,15 @@ export type DocmostMcpConfig = { apiUrl: string } & (
       has?: (uri: string) => boolean;
       evict?: (uri: string) => void;
     };
+    // Dependency-neutral metrics sink. When present, the client emits generic
+    // (name, value, labels) samples; the HOST maps those names onto its own
+    // metrics registry (the package never depends on prom-client or the server).
+    // Absent in standalone/stdio mode → the client is a complete no-op here.
+    onMetric?: (
+      name: string,
+      value: number,
+      labels?: Record<string, string>,
+    ) => void;
   };
 
 // Canonical UUID shape (versions 1–8, matching the `uuid` package's `validate`
@@ -173,6 +185,11 @@ export class DocmostClient {
   // op's image blobs if the final doc put throws. Null when the sink omits them.
   private sandboxHas: ((uri: string) => boolean) | null = null;
   private sandboxEvict: ((uri: string) => void) | null = null;
+  // Optional dependency-neutral metrics sink (see DocmostMcpConfig.onMetric).
+  // Null on the legacy positional form and whenever the host omits it → no-op.
+  private onMetricFn:
+    | ((name: string, value: number, labels?: Record<string, string>) => void)
+    | null = null;
   // In-flight login dedup: when the token expires, the 401 interceptor,
   // ensureAuthenticated, getCollabTokenWithReauth and the two multipart retries
   // can all call login() at once. Memoizing a single promise collapses that
@@ -222,6 +239,8 @@ export class DocmostClient {
       this.sandboxHas = config.sandbox.has ?? null;
       this.sandboxEvict = config.sandbox.evict ?? null;
     }
+    // Legacy positional form carries no onMetric → null (complete no-op).
+    this.onMetricFn = config.onMetric ?? null;
     this.client = axios.create({
       baseURL: this.apiUrl,
       // Default request timeout so a hung connection cannot wedge a per-page
@@ -447,6 +466,10 @@ export class DocmostClient {
       };
 
       connectTimer = setTimeout(() => {
+        // Only the actual 25s collab connect timeout fires here — the agent's
+        // collab connection to the server never became ready. This is the
+        // connect-vs-unload signal; the other finish() paths must NOT emit it.
+        this.onMetricFn?.("collab_connect_timeouts_total", 1);
         finish(new Error("Connection timeout to collaboration server"));
       }, CONNECT_TIMEOUT_MS);
 
@@ -2454,6 +2477,64 @@ export class DocmostClient {
     };
   }
 
+  /** Plain text of each TOP-LEVEL block of `doc`, for anchor-failure hints. */
+  private topLevelBlockTexts(doc: any): string[] {
+    const content = doc && Array.isArray(doc.content) ? doc.content : [];
+    return content
+      .map((b: any) => blockPlainText(b))
+      .filter((t: string) => t.length > 0);
+  }
+
+  /**
+   * True when per-block anchoring failed but the (normalized) selection DOES
+   * appear in the blocks' joined plain text — i.e. it straddles a block
+   * boundary. Blocks are joined with a newline (collapsed to one space by
+   * normalizeForMatch) so a selection whose parts are separated by a paragraph
+   * break still matches. Callers only reach here after single-block anchoring
+   * (incl. the markdown-strip fallback) has already failed.
+   */
+  private selectionSpansMultipleBlocks(
+    blockTexts: string[],
+    selection: string,
+  ): boolean {
+    const normSel = normalizeForMatch(selection).norm.trim();
+    if (normSel.length === 0) return false;
+    const joined = normalizeForMatch(blockTexts.join("\n")).norm;
+    return joined.indexOf(normSel) !== -1;
+  }
+
+  /**
+   * Build the actionable error for a create_comment anchor MISS, porting
+   * edit_page_text's self-correction affordances: an explicit "spans multiple
+   * blocks" message when the selection straddles a block boundary, otherwise a
+   * "closest block text" hint quoting the block that holds the selection's
+   * longest token. `live` switches the wording between the pre-check (reading the
+   * persisted page) and the post-create live-anchor failure (which rolls back).
+   */
+  private anchorNotFoundError(
+    doc: any,
+    selection: string,
+    live: boolean,
+  ): Error {
+    const blockTexts = this.topLevelBlockTexts(doc);
+    const rolled = live ? " The comment was rolled back." : "";
+    if (this.selectionSpansMultipleBlocks(blockTexts, selection)) {
+      return new Error(
+        "create_comment: the selection spans multiple blocks; anchor on a " +
+          "contiguous fragment within a SINGLE paragraph/block (<=250 chars)." +
+          rolled,
+      );
+    }
+    const where = live ? "in the live document" : "in the page";
+    return new Error(
+      `create_comment: could not find the selection text ${where} to anchor ` +
+        "the comment. Provide the EXACT contiguous text from a single " +
+        "paragraph/block (<=250 chars)." +
+        closestBlockHint(blockTexts, selection) +
+        rolled,
+    );
+  }
+
   /**
    * Create an inline comment anchored to its `selection` text, or a reply.
    *
@@ -2515,6 +2596,10 @@ export class DocmostClient {
     // Captured in the pre-check below (which already reads the page) and used as
     // payload.selection. Ordinary comments keep sending the raw agent selection.
     let anchoredSelection: string | null = null;
+    // Set when the anchor matched only after stripping markdown from the
+    // selection (the strip fallback); surfaced as a soft warning like
+    // edit_page_text does, so a stale-markdown selection is flagged.
+    let anchorNormalized = false;
 
     // For a top-level comment, fail BEFORE creating anything when the selection
     // is not present in the persisted document — this avoids leaving an orphan
@@ -2530,10 +2615,7 @@ export class DocmostClient {
           // rejected BEFORE creating the comment.
           const matches = countAnchorMatches(page.content, selection);
           if (matches === 0) {
-            throw new Error(
-              "create_comment: could not find the selection text in the page to anchor the comment. " +
-                "Provide the EXACT contiguous text from a single paragraph/block (<=250 chars).",
-            );
+            throw this.anchorNotFoundError(page.content, selection, false);
           }
           if (matches >= 2) {
             throw new Error(
@@ -2547,18 +2629,27 @@ export class DocmostClient {
           // null despite countAnchorMatches===1 (shouldn't happen), fall back to
           // the raw agent selection below rather than crash.
           anchoredSelection = getAnchoredText(page.content, selection);
-        } else if (!canAnchorInDoc(page.content, selection)) {
-          throw new Error(
-            "create_comment: could not find the selection text in the page to anchor the comment. " +
-              "Provide the EXACT contiguous text from a single paragraph/block (<=250 chars).",
-          );
+          anchorNormalized = resolveAnchorSelection(
+            page.content,
+            selection,
+          ).normalized;
+        } else {
+          const resolved = resolveAnchorSelection(page.content, selection);
+          if (!resolved.found) {
+            throw this.anchorNotFoundError(page.content, selection, false);
+          }
+          anchorNormalized = resolved.normalized;
         }
       } catch (e) {
-        // Rethrow our own "not found"/"ambiguous" errors; swallow read/network
-        // errors so the live anchor step can still try (and enforce) anchoring.
+        // Rethrow our own "not found"/"ambiguous"/"spans multiple blocks" errors;
+        // swallow read/network errors so the live anchor step can still try (and
+        // enforce) anchoring.
         if (
           e instanceof Error &&
           (e.message.startsWith("create_comment: could not find the selection") ||
+            e.message.startsWith(
+              "create_comment: the selection spans multiple blocks",
+            ) ||
             e.message.startsWith(
               "create_comment: the suggestion's selection is ambiguous",
             ))
@@ -2630,6 +2721,10 @@ export class DocmostClient {
     // Set inside the transform when a suggestion's live anchor is ambiguous
     // (>=2 occurrences), so the rollback path can surface the right error.
     let ambiguousInLiveDoc = false;
+    // Captured inside the transform on a not-found abort, so the rollback path
+    // can surface the closest-block / spans-multiple-blocks hint built from the
+    // LIVE document (the pre-check page is not in scope there).
+    let liveNotFoundError: Error | null = null;
     try {
       const collabToken = await this.getCollabTokenWithReauth();
       // Open the collab doc by the canonical UUID, never the slugId (#260). The
@@ -2657,6 +2752,13 @@ export class DocmostClient {
             const liveCount = countAnchorMatches(doc, selection as string);
             if (liveCount !== 1) {
               ambiguousInLiveDoc = liveCount >= 2;
+              if (liveCount === 0) {
+                liveNotFoundError = this.anchorNotFoundError(
+                  doc,
+                  selection as string,
+                  true,
+                );
+              }
               return null;
             }
           }
@@ -2666,6 +2768,11 @@ export class DocmostClient {
           }
           // Selection text not found in the LIVE document: abort the write. The
           // rollback + throw below turns this into a hard error.
+          liveNotFoundError = this.anchorNotFoundError(
+            doc,
+            selection as string,
+            true,
+          );
           return null;
         },
       );
@@ -2682,13 +2789,28 @@ export class DocmostClient {
       // suggestion, was ambiguous) in the live document. Roll back the comment
       // and surface a hard error.
       await this.safeDeleteComment(newCommentId);
-      throw new Error(
-        ambiguousInLiveDoc
-          ? "create_comment: the suggestion's selection is ambiguous in the live document (multiple occurrences); the comment was rolled back. Expand the selection with surrounding context so it is unique."
-          : "create_comment: failed to anchor the comment (selection not found in the live document); the comment was rolled back",
+      if (ambiguousInLiveDoc) {
+        throw new Error(
+          "create_comment: the suggestion's selection is ambiguous in the live document (multiple occurrences); the comment was rolled back. Expand the selection with surrounding context so it is unique.",
+        );
+      }
+      throw (
+        liveNotFoundError ??
+        new Error(
+          "create_comment: failed to anchor the comment (selection not found in the live document); the comment was rolled back",
+        )
       );
     }
 
+    // Soft warning (like edit_page_text): the selection only matched after
+    // stripping markdown, so the caller likely quoted a styled fragment.
+    if (anchorNormalized) {
+      result.warning =
+        "The selection matched only after stripping markdown syntax; the comment " +
+        "was anchored on the document's plain text. Copy the selection verbatim " +
+        "from get_page / search_in_page output to avoid this.";
+    }
+
     result.anchored = true;
     return result;
   }

packages/mcp/src/index.ts

@@ -64,6 +64,33 @@ const jsonContent = (data: any) => ({
  * REST + the collaboration WebSocket using the provided service-account
  * credentials and auto-re-authenticates.
  */
+/**
+ * Wrap a tool handler so its wall-clock duration is reported through the host's
+ * dependency-neutral sink as `mcp_tool_duration_seconds` (labelled by tool
+ * name). Pure and side-effect-free apart from the optional `onMetric` call:
+ *  - preserves the handler's exact return value (awaited);
+ *  - observes in a `finally`, so it records on BOTH success and throw, then
+ *    rethrows the original error unchanged (never swallowed);
+ *  - with no `onMetric` (standalone/stdio) it is a transparent pass-through.
+ * Exported so the timing contract can be unit-tested without a live transport.
+ */
+export function timeToolHandler(
+  name: string,
+  handler: (...args: any[]) => any,
+  onMetric?: (name: string, value: number, labels?: Record<string, string>) => void,
+): (...args: any[]) => Promise<any> {
+  return async (...handlerArgs: any[]) => {
+    const start = performance.now();
+    try {
+      return await handler(...handlerArgs);
+    } finally {
+      onMetric?.("mcp_tool_duration_seconds", (performance.now() - start) / 1000, {
+        tool: name,
+      });
+    }
+  };
+}
+
 export function createDocmostMcpServer(config: DocmostMcpConfig): McpServer {
   // Pass the whole config union through: the client branches internally on
   // credentials vs. getToken, so both the external /mcp (creds) and the
@@ -78,6 +105,26 @@ export function createDocmostMcpServer(config: DocmostMcpConfig): McpServer {
     { instructions: SERVER_INSTRUCTIONS },
   );
 
+  // Single choke point for MCP tool timing. Both `registerShared` (below) and
+  // the inline `server.registerTool(...)` calls funnel through this one method,
+  // so monkeypatching it HERE — before any tool is registered and before
+  // `registerShared` captures a reference to it — times every tool with no
+  // per-tool boilerplate. The wrapped handler records wall-clock duration and,
+  // in a `finally`, feeds the host's dependency-neutral sink
+  // `config.onMetric("mcp_tool_duration_seconds", seconds, { tool })`. The tool
+  // name is the registration name (bounded cardinality). When no onMetric is
+  // provided (standalone/stdio) the wrapper is a pure pass-through: it still
+  // returns the original result and rethrows the original error unchanged.
+  const originalRegisterTool = server.registerTool.bind(server) as (
+    ...args: any[]
+  ) => any;
+  (server as any).registerTool = (...args: any[]) => {
+    const name = args[0] as string;
+    const handler = args[args.length - 1];
+    const timedHandler = timeToolHandler(name, handler, config.onMetric);
+    return originalRegisterTool(...args.slice(0, -1), timedHandler);
+  };
+
   // Register a tool from the shared, zod-agnostic spec registry. The spec owns
   // the canonical name + model-facing description + (optional) schema builder;
   // only the execute body is supplied per call. buildShape is invoked with THIS
@@ -380,43 +427,10 @@ registerShared(SHARED_TOOL_SPECS.deleteNode, async ({ pageId, nodeId }) => {
 });
 
 // Tool: insert_image
-// MCP-only by design (NOT in the shared registry): the in-app AI-chat agent
-// exposes no image tools (insert/replace), so there is no second layer to unify
-// — a SHARED_TOOL_SPECS entry's tier/catalogLine are in-app metadata and the
-// catalog-partition test forbids a spec without a live in-app tool (#294).
-server.registerTool(
-  "insert_image",
-  {
-    description:
-      "Download an image from a web (http/https) URL and insert it into " +
-      "a page in one step. By default " +
-      "appends the image at the end of the page. With replaceText, replaces the " +
-      "first top-level block whose text contains that string (handy for " +
-      'swapping a text placeholder like "[image: foo.png]" for the real image). ' +
-      "With afterText, inserts the image right after the first block containing " +
-      "that string. Preserves all other block ids.",
-    inputSchema: {
-      pageId: z.string().min(1),
-      imageUrl: z
-        .string()
-        .min(1)
-        .describe("http(s) URL of the image to download and upload"),
-      align: z.enum(["left", "center", "right"]).optional(),
-      alt: z.string().optional(),
-      replaceText: z
-        .string()
-        .optional()
-        .describe(
-          "Replace the first top-level block whose text contains this string with the image",
-        ),
-      afterText: z
-        .string()
-        .optional()
-        .describe(
-          "Insert the image right after the first top-level block whose text contains this string",
-        ),
-    },
-  },
+// Schema + description now live in the shared registry (#410) so BOTH this MCP
+// server and the in-app AI-chat agent expose it. The execute body is unchanged.
+registerShared(
+  SHARED_TOOL_SPECS.insertImage,
   async ({ pageId, imageUrl, align, alt, replaceText, afterText }) => {
     const result = await docmostClient.insertImage(pageId, imageUrl, {
       align,
@@ -429,34 +443,9 @@ server.registerTool(
 );
 
 // Tool: replace_image
-// MCP-only by design (see insert_image): no in-app equivalent, stays inline.
-server.registerTool(
-  "replace_image",
-  {
-    description:
-      "Replace an existing image on a page with a new image fetched from a web " +
-      "(http/https) URL: uploads the new file as a NEW " +
-      "attachment (fresh clean URL that renders and busts browser caches), then " +
-      "repoints every image node referencing the old attachmentId (recursively, " +
-      "incl. callouts/tables) via the live document, preserving comments, " +
-      "alignment and alt. The old attachment is left as an unreferenced orphan " +
-      "(Docmost has no API to delete a single attachment; it is removed only when " +
-      "the page/space is deleted). In-place byte overwrite is avoided because some " +
-      "Docmost versions corrupt the attachment (HTTP 500) on overwrite.",
-    inputSchema: {
-      pageId: z.string().min(1),
-      attachmentId: z
-        .string()
-        .min(1)
-        .describe("attachmentId of the image currently in the page to replace"),
-      imageUrl: z
-        .string()
-        .min(1)
-        .describe("http(s) URL of the new image to download"),
-      align: z.enum(["left", "center", "right"]).optional(),
-      alt: z.string().optional(),
-    },
-  },
+// Schema + description now live in the shared registry (#410).
+registerShared(
+  SHARED_TOOL_SPECS.replaceImage,
   async ({ pageId, attachmentId, imageUrl, align, alt }) => {
     const result = await docmostClient.replaceImage(
       pageId,
@@ -779,36 +768,10 @@ server.registerTool(
 );
 
 // Tool: insert_footnote
-// MCP-only by design (see insert_image): the in-app AI-chat agent exposes no
-// footnote tool, so there is no second layer to unify — stays inline (#294).
-server.registerTool(
-  "insert_footnote",
-  {
-    description:
-      "Insert an AUTHOR-INLINE footnote: you specify only WHERE (anchorText) " +
-      "and WHAT (text). The footnote marker is placed right after anchorText in " +
-      "the body, and the bottom footnotes list + the numbering are derived " +
-      "deterministically server-side. You do NOT assign a number, and you " +
-      "never see or edit the footnotes list — so footnotes cannot end up out " +
-      "of order, orphaned, or as a raw '[^id]' block. If a footnote with the " +
-      "SAME text already exists, its number is REUSED (one definition, several " +
-      "references). The write is atomic and won't clobber concurrent edits; if " +
-      "anchorText is not found, nothing is written and an error is returned.",
-    inputSchema: {
-      pageId: z.string().min(1),
-      anchorText: z
-        .string()
-        .min(1)
-        .describe(
-          "A snippet of existing body text; the footnote marker is inserted " +
-            "immediately after its first occurrence (mark-safe).",
-        ),
-      text: z
-        .string()
-        .min(1)
-        .describe("The footnote content as markdown (becomes the definition)."),
-    },
-  },
+// Schema + description now live in the shared registry (#410) so the in-app
+// AI-chat agent exposes it too. The execute body is unchanged.
+registerShared(
+  SHARED_TOOL_SPECS.insertFootnote,
   async ({ pageId, anchorText, text }) => {
     const result = await docmostClient.insertFootnote(pageId, anchorText, text);
     return jsonContent(result);

packages/mcp/src/lib/comment-anchor.ts

@@ -17,8 +17,23 @@
  * comparing and match across maximal runs of consecutive text nodes within a
  * single block, while mapping every normalized character back to its raw index
  * so the mark lands on the exact original characters.
+ *
+ * MARKDOWN-STRIP FALLBACK: when the agent copies a selection that still carries
+ * inline markdown (`**bold**`, `` `code` ``, `[t](u)`), the raw locator will not
+ * match the document's plain text. Exactly like edit_page_text's json-edit
+ * fallback, we first try the verbatim selection and, ONLY if it anchors nowhere
+ * in the whole document, retry with `stripInlineMarkdown` applied. `canAnchorInDoc`,
+ * `getAnchoredText` and `applyAnchorInDoc` share this decision via
+ * `resolveAnchorSelection`. `countAnchorMatches` keeps its OWN parallel exact-wins
+ * implementation (it needs a raw match COUNT, not a single resolved locator), kept
+ * deliberately in sync with `resolveAnchorSelection`: raw match ⇒ use raw, else fall
+ * back to the stripped count. All four therefore agree on which locator matched —
+ * the suggestion-uniqueness gate depends on count and can/get never disagreeing, so
+ * these two exact-wins implementations MUST stay in sync if either is changed.
  */
 
+import { stripInlineMarkdown } from "./text-normalize.js";
+
 /** Typographic double-quote variants mapped to ASCII `"`. */
 const DOUBLE_QUOTES = "«»„“”‟〝〞＂";
 /** Typographic single-quote/apostrophe variants mapped to ASCII `'`. */
@@ -214,15 +229,17 @@ function reconstructRawText(blockContent: any[], match: AnchorMatch): string {
  * un-appliable (spurious 409).
  */
 export function getAnchoredText(doc: any, selection: string): string | null {
+  const { selection: effective, found } = resolveAnchorSelection(doc, selection);
+  if (!found) return null;
   const visit = (node: any, depth: number): string | null => {
     if (depth > MAX_DEPTH || !node || typeof node !== "object") return null;
     if (!Array.isArray(node.content)) return null;
-    const match = findAnchorInBlock(node.content, selection);
+    const match = findAnchorInBlock(node.content, effective);
     if (match) return reconstructRawText(node.content, match);
     for (const child of node.content) {
       if (child && typeof child === "object" && Array.isArray(child.content)) {
-        const found = visit(child, depth + 1);
-        if (found !== null) return found;
+        const foundText = visit(child, depth + 1);
+        if (foundText !== null) return foundText;
       }
     }
     return null;
@@ -231,12 +248,11 @@ export function getAnchoredText(doc: any, selection: string): string | null {
 }
 
 /**
- * Depth-first, document-order check for whether `selection` can be anchored
- * anywhere in `doc`. At each node with an array `content`, first try to match
- * within that node's own content, then recurse into children that themselves
- * have a `content` array.
+ * RAW (no markdown-strip fallback) depth-first check that `selection` anchors
+ * somewhere in `doc`. This is the primitive `resolveAnchorSelection` builds on;
+ * public callers should use `canAnchorInDoc`, which adds the strip fallback.
  */
-export function canAnchorInDoc(doc: any, selection: string): boolean {
+function rawCanAnchorInDoc(doc: any, selection: string): boolean {
   const visit = (node: any, depth: number): boolean => {
     if (depth > MAX_DEPTH || !node || typeof node !== "object") return false;
     if (!Array.isArray(node.content)) return false;
@@ -251,6 +267,43 @@ export function canAnchorInDoc(doc: any, selection: string): boolean {
   return visit(doc, 0);
 }
 
+/**
+ * Decide the locator that ACTUALLY anchors `selection` in `doc`, applying the
+ * markdown-strip fallback once (so every public entry point agrees):
+ *  - EXACT WINS: if the verbatim selection anchors anywhere, use it as-is.
+ *  - FALLBACK: only if the verbatim selection anchors nowhere, and the
+ *    markdown-stripped form differs and DOES anchor, use the stripped form and
+ *    flag `normalized` so callers can surface a soft warning.
+ *  - otherwise `found` is false and `selection` is returned unchanged.
+ *
+ * The stripped form is used ONLY to LOCATE the anchor; getAnchoredText still
+ * reconstructs and stores the RAW document substring, so the strip never leaks
+ * into what gets persisted.
+ */
+export function resolveAnchorSelection(
+  doc: any,
+  selection: string,
+): { selection: string; found: boolean; normalized: boolean } {
+  if (rawCanAnchorInDoc(doc, selection)) {
+    return { selection, found: true, normalized: false };
+  }
+  const stripped = stripInlineMarkdown(selection);
+  if (stripped !== selection && rawCanAnchorInDoc(doc, stripped)) {
+    return { selection: stripped, found: true, normalized: true };
+  }
+  return { selection, found: false, normalized: false };
+}
+
+/**
+ * Depth-first, document-order check for whether `selection` can be anchored
+ * anywhere in `doc` (with the markdown-strip fallback). At each node with an
+ * array `content`, first try to match within that node's own content, then
+ * recurse into children that themselves have a `content` array.
+ */
+export function canAnchorInDoc(doc: any, selection: string): boolean {
+  return resolveAnchorSelection(doc, selection).found;
+}
+
 /**
  * Split the matched text nodes and splice the comment mark across the range.
  * `blockContent` is mutated IN PLACE. `match.startChild..endChild` are all text
@@ -315,7 +368,7 @@ function spliceCommentMark(
  * not use this. (Note: counts OCCURRENCES, not just matching blocks, so two
  * occurrences inside one block are correctly reported as 2.)
  */
-export function countAnchorMatches(doc: any, selection: string): number {
+function rawCountAnchorMatches(doc: any, selection: string): number {
   const normSel = normalizeForMatch(selection).norm.trim();
   if (normSel.length === 0) return 0;
 
@@ -369,6 +422,25 @@ export function countAnchorMatches(doc: any, selection: string): number {
   return total;
 }
 
+/**
+ * Uniqueness gate for suggestions, with the SAME markdown-strip fallback as the
+ * other entry points so count never disagrees with can/get/apply. EXACT WINS: if
+ * the verbatim selection occurs at all, return its raw occurrence count (so a
+ * selection that is unique raw stays unique — the fallback never runs and cannot
+ * introduce a spurious second match). Only when the verbatim selection is absent
+ * do we count occurrences of the markdown-stripped form.
+ */
+export function countAnchorMatches(doc: any, selection: string): number {
+  const raw = rawCountAnchorMatches(doc, selection);
+  if (raw > 0) return raw;
+  const stripped = stripInlineMarkdown(selection);
+  if (stripped !== selection) {
+    const strippedCount = rawCountAnchorMatches(doc, stripped);
+    if (strippedCount > 0) return strippedCount;
+  }
+  return 0;
+}
+
 /**
  * Depth-first (same order as canAnchorInDoc) over `doc`; on the FIRST block
  * whose content matches `selection`, splice the comment mark across the matched
@@ -380,10 +452,12 @@ export function applyAnchorInDoc(
   selection: string,
   commentId: string,
 ): boolean {
+  const { selection: effective, found } = resolveAnchorSelection(doc, selection);
+  if (!found) return false;
   const visit = (node: any, depth: number): boolean => {
     if (depth > MAX_DEPTH || !node || typeof node !== "object") return false;
     if (!Array.isArray(node.content)) return false;
-    const match = findAnchorInBlock(node.content, selection);
+    const match = findAnchorInBlock(node.content, effective);
     if (match) {
       spliceCommentMark(node.content, match, commentId);
       return true;

packages/mcp/src/lib/json-edit.ts

@@ -12,7 +12,11 @@
  * re-import for small wording fixes.
  */
 
-import { stripInlineMarkdown, stripBalancedWrappers } from "./text-normalize.js";
+import {
+  stripInlineMarkdown,
+  stripBalancedWrappers,
+  closestBlockHint,
+} from "./text-normalize.js";
 
 export interface TextEdit {
   find: string;
@@ -305,6 +309,21 @@ export function applyTextEdits(
       continue;
     }
 
+    // HARD-REFUSE inline footnote tokens (#410). `^[...]` in a `replace` is
+    // markdown that only becomes a real footnote when a whole markdown body is
+    // written (create_page / update_page_content / import_page_markdown). Written
+    // through edit_page_text it stays a LITERAL string in the text — the exact
+    // failure mode #410 fixes — so refuse it here (defense-in-depth) and point the
+    // caller at insert_footnote, mirroring the formatting-marker refusal above.
+    if (/\^\[[\s\S]*?\]/.test(edit.replace)) {
+      failed.push({
+        find: edit.find,
+        reason:
+          "edit_page_text writes the replacement as LITERAL text, so a `^[...]` footnote token does not parse into a real footnote (it would appear verbatim in the page). To add a footnote to existing text, use insert_footnote (anchorText = where, text = the note).",
+      });
+      continue;
+    }
+
     // Gather every inline block in document order (recurse the whole tree so
     // nested containers — callouts, list items, table cells, blockquotes — are
     // all covered).
@@ -366,29 +385,9 @@ export function applyTextEdits(
       } else {
         // Append a bounded "closest text" hint: find the FIRST block that
         // contains the longest whitespace-delimited token (>= 3 chars) of the
-        // (stripped, then raw) locator, and quote that block's plain text.
-        reason = "text not found in the document.";
-        const tokenSource = stripped.length > 0 ? stripped : edit.find;
-        const longestToken = tokenSource
-          .split(/\s+/)
-          .filter((t) => t.length >= 3)
-          .sort((a, b) => b.length - a.length)[0];
-        if (longestToken) {
-          const hitBlock = blockPlain.find((plain) =>
-            plain.includes(longestToken),
-          );
-          if (hitBlock) {
-            // Truncate by code point (spread iterates by code point) so a
-            // surrogate pair is never split; append the ellipsis only when the
-            // text was actually longer than the limit.
-            const points = [...hitBlock];
-            const snippet =
-              points.length > 120
-                ? points.slice(0, 120).join("") + "…"
-                : hitBlock;
-            reason += ` Closest block text: "${snippet}".`;
-          }
-        }
+        // (stripped, then raw) locator, and quote that block's plain text. Shared
+        // with create_comment via closestBlockHint so both give the same hint.
+        reason = "text not found in the document." + closestBlockHint(blockPlain, edit.find);
       }
       failed.push({ find: edit.find, reason });
       continue;

packages/mcp/src/lib/text-normalize.ts

@@ -114,3 +114,37 @@ export function stripInlineMarkdown(s: string): string {
 
   return out;
 }
+
+/**
+ * Build a bounded "closest text" hint for an anchor/find MISS, shared by
+ * edit_page_text (json-edit) and create_comment (client) so both surface the
+ * same self-correction affordance.
+ *
+ * Take the longest whitespace-delimited token (>= 3 chars) of the locator
+ * (markdown-stripped first, so `**bold**` contributes `bold`), find the FIRST
+ * of `blockTexts` that contains it, and return ` Closest block text: "…".` with
+ * the block quoted (truncated to 120 code points + ellipsis). Returns "" when
+ * no token qualifies or no block contains it, so the caller can append it
+ * unconditionally.
+ */
+export function closestBlockHint(
+  blockTexts: string[],
+  locator: string,
+): string {
+  if (typeof locator !== "string" || locator.length === 0) return "";
+  const stripped = stripInlineMarkdown(locator);
+  const tokenSource = stripped.length > 0 ? stripped : locator;
+  const longestToken = tokenSource
+    .split(/\s+/)
+    .filter((t) => t.length >= 3)
+    .sort((a, b) => b.length - a.length)[0];
+  if (!longestToken) return "";
+  const hitBlock = blockTexts.find((plain) => plain.includes(longestToken));
+  if (!hitBlock) return "";
+  // Truncate by code point (spread iterates by code point) so a surrogate pair
+  // is never split; append the ellipsis only when the text was actually longer.
+  const points = [...hitBlock];
+  const snippet =
+    points.length > 120 ? points.slice(0, 120).join("") + "…" : hitBlock;
+  return ` Closest block text: "${snippet}".`;
+}

packages/mcp/src/tool-specs.ts

@@ -771,9 +771,13 @@ export const SHARED_TOOL_SPECS = {
       'The comment is anchored inline to the given exact `selection` text ' +
       '(which gets highlighted); page-level comments are NOT supported. A ' +
       'new top-level comment REQUIRES a `selection`. Replies inherit the ' +
-      "parent's anchor and take no selection. If the call fails with a " +
-      '"selection not found" error, retry with a corrected EXACT selection ' +
-      'copied verbatim from a single paragraph/block. You may also attach a ' +
+      "parent's anchor and take no selection. Always COPY the `selection` " +
+      'VERBATIM from get_page / search_in_page output — do NOT quote it from ' +
+      'memory (stale-memory quoting is the top cause of anchor misses). If the ' +
+      'call fails with a "selection not found" error, the error quotes the ' +
+      "closest block text (or says the selection spans multiple blocks); retry " +
+      "with a corrected EXACT selection copied verbatim from a single " +
+      'paragraph/block. You may also attach a ' +
       '`suggestedText` proposing a replacement for the `selection` (a human ' +
       'applies it from the UI); when set, the `selection` must occur exactly ' +
       'once in the page. Reversible via the comment UI.',
@@ -1003,4 +1007,116 @@ export const SHARED_TOOL_SPECS = {
       text: z.string().describe('The new cell text.'),
     }),
   },
+
+  // --- footnote + image write tools (promoted from inline MCP-only, #410) ---
+  //
+  // These three were previously registered inline in index.ts as MCP-only,
+  // because the in-app AI-chat agent had no equivalent. #410 promotes them so the
+  // in-app agent (esp. the Researcher role) can attach real footnotes/images
+  // instead of writing literal `^[...]` / placeholder text via editPageText. The
+  // schema + description are MOVED VERBATIM from the old inline registrations so
+  // external MCP clients see identical tool names, fields and text.
+
+  insertFootnote: {
+    mcpName: 'insert_footnote',
+    inAppKey: 'insertFootnote',
+    description:
+      'Insert an AUTHOR-INLINE footnote: you specify only WHERE (anchorText) ' +
+      'and WHAT (text). The footnote marker is placed right after anchorText in ' +
+      'the body, and the bottom footnotes list + the numbering are derived ' +
+      'deterministically server-side. You do NOT assign a number, and you ' +
+      "never see or edit the footnotes list — so footnotes cannot end up out " +
+      "of order, orphaned, or as a raw '[^id]' block. If a footnote with the " +
+      'SAME text already exists, its number is REUSED (one definition, several ' +
+      "references). The write is atomic and won't clobber concurrent edits; if " +
+      'anchorText is not found, nothing is written and an error is returned.',
+    // CORE for the in-app agent (#410): keeping it deferred would recreate the
+    // original asymmetry (footnote tool hidden while editPageText is core), which
+    // is exactly what makes the agent fall back to literal `^[...]`.
+    tier: 'core',
+    catalogLine:
+      'insertFootnote — attach a numbered footnote right after a snippet of existing body text.',
+    buildShape: (z) => ({
+      pageId: z.string().min(1),
+      anchorText: z
+        .string()
+        .min(1)
+        .describe(
+          'A snippet of existing body text; the footnote marker is inserted ' +
+            'immediately after its first occurrence (mark-safe).',
+        ),
+      text: z
+        .string()
+        .min(1)
+        .describe('The footnote content as markdown (becomes the definition).'),
+    }),
+  },
+
+  insertImage: {
+    mcpName: 'insert_image',
+    inAppKey: 'insertImage',
+    description:
+      'Download an image from a web (http/https) URL and insert it into ' +
+      'a page in one step. By default ' +
+      'appends the image at the end of the page. With replaceText, replaces the ' +
+      'first top-level block whose text contains that string (handy for ' +
+      'swapping a text placeholder like "[image: foo.png]" for the real image). ' +
+      'With afterText, inserts the image right after the first block containing ' +
+      'that string. Preserves all other block ids.',
+    tier: 'deferred',
+    catalogLine:
+      'insertImage — download a web image and insert it into a page.',
+    buildShape: (z) => ({
+      pageId: z.string().min(1),
+      imageUrl: z
+        .string()
+        .min(1)
+        .describe('http(s) URL of the image to download and upload'),
+      align: z.enum(['left', 'center', 'right']).optional(),
+      alt: z.string().optional(),
+      replaceText: z
+        .string()
+        .optional()
+        .describe(
+          'Replace the first top-level block whose text contains this string with the image',
+        ),
+      afterText: z
+        .string()
+        .optional()
+        .describe(
+          'Insert the image right after the first top-level block whose text contains this string',
+        ),
+    }),
+  },
+
+  replaceImage: {
+    mcpName: 'replace_image',
+    inAppKey: 'replaceImage',
+    description:
+      'Replace an existing image on a page with a new image fetched from a web ' +
+      '(http/https) URL: uploads the new file as a NEW ' +
+      'attachment (fresh clean URL that renders and busts browser caches), then ' +
+      'repoints every image node referencing the old attachmentId (recursively, ' +
+      'incl. callouts/tables) via the live document, preserving comments, ' +
+      'alignment and alt. The old attachment is left as an unreferenced orphan ' +
+      '(Docmost has no API to delete a single attachment; it is removed only when ' +
+      'the page/space is deleted). In-place byte overwrite is avoided because some ' +
+      'Docmost versions corrupt the attachment (HTTP 500) on overwrite.',
+    tier: 'deferred',
+    catalogLine:
+      'replaceImage — swap an existing page image for one fetched from a web URL.',
+    buildShape: (z) => ({
+      pageId: z.string().min(1),
+      attachmentId: z
+        .string()
+        .min(1)
+        .describe('attachmentId of the image currently in the page to replace'),
+      imageUrl: z
+        .string()
+        .min(1)
+        .describe('http(s) URL of the new image to download'),
+      align: z.enum(['left', 'center', 'right']).optional(),
+      alt: z.string().optional(),
+    }),
+  },
 } satisfies Record<string, SharedToolSpec>;

packages/mcp/test/mock/create-comment.test.mjs

@@ -548,3 +548,94 @@ test("suggestedText: the stored selection is the doc's RAW typographic substring
   );
   assert.equal(createPayload.suggestedText, "goodbye");
 });
+
+// -----------------------------------------------------------------------------
+// 8) #408: a not-found selection error QUOTES the closest block text so the
+//    model can self-correct instead of blind-retrying.
+// -----------------------------------------------------------------------------
+test("a not-found selection error includes a 'Closest block text' hint", async () => {
+  let createCalls = 0;
+  const { baseURL } = await spawn(async (req, res) => {
+    await readBody(req);
+    if (req.url === "/api/auth/login") {
+      sendJson(res, 200, { success: true }, {
+        "Set-Cookie": "authToken=t; Path=/; HttpOnly",
+      });
+      return;
+    }
+    if (req.url === "/api/pages/info") {
+      sendJson(res, 200, {
+        data: {
+          id: "page-1",
+          content: {
+            type: "doc",
+            content: [
+              { type: "paragraph", content: [{ type: "text", text: "The quick brown fox jumps" }] },
+            ],
+          },
+        },
+      });
+      return;
+    }
+    if (req.url === "/api/comments/create") {
+      createCalls++;
+      sendJson(res, 200, { data: { id: "should-not-happen" } });
+      return;
+    }
+    sendJson(res, 404, { message: "not found" });
+  });
+
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+  await assert.rejects(
+    () => client.createComment("page-1", "body", "inline", "quick brown cat"),
+    /Closest block text: "The quick brown fox jumps"/,
+    "a not-found selection must quote the closest block text",
+  );
+  assert.equal(createCalls, 0, "/comments/create must NOT be called on a miss");
+});
+
+// -----------------------------------------------------------------------------
+// 9) #408: a selection that straddles two blocks gets the explicit
+//    "spans multiple blocks" message instead of a bare not-found.
+// -----------------------------------------------------------------------------
+test("a selection spanning multiple blocks gets the explicit spans-multiple-blocks message", async () => {
+  let createCalls = 0;
+  const { baseURL } = await spawn(async (req, res) => {
+    await readBody(req);
+    if (req.url === "/api/auth/login") {
+      sendJson(res, 200, { success: true }, {
+        "Set-Cookie": "authToken=t; Path=/; HttpOnly",
+      });
+      return;
+    }
+    if (req.url === "/api/pages/info") {
+      sendJson(res, 200, {
+        data: {
+          id: "page-1",
+          content: {
+            type: "doc",
+            content: [
+              { type: "paragraph", content: [{ type: "text", text: "the quick brown" }] },
+              { type: "paragraph", content: [{ type: "text", text: "fox jumps over" }] },
+            ],
+          },
+        },
+      });
+      return;
+    }
+    if (req.url === "/api/comments/create") {
+      createCalls++;
+      sendJson(res, 200, { data: { id: "should-not-happen" } });
+      return;
+    }
+    sendJson(res, 404, { message: "not found" });
+  });
+
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+  await assert.rejects(
+    () => client.createComment("page-1", "body", "inline", "brown fox"),
+    /spans multiple blocks/,
+    "a cross-block selection must report the spans-multiple-blocks hint",
+  );
+  assert.equal(createCalls, 0, "/comments/create must NOT be called on a miss");
+});

packages/mcp/test/mock/tool-timing-server.test.mjs

@@ -0,0 +1,87 @@
+// #402 — INTEGRATION test that locks the registerTool monkeypatch installed by
+// createDocmostMcpServer (src/index.ts). The sibling unit test
+// (test/unit/tool-timing.test.mjs) only exercises the timeToolHandler helper in
+// ISOLATION; it never constructs the server, so nothing there proves the factory
+// actually (a) wraps every registered tool through that helper and (b) labels
+// each sample with the tool's REGISTRATION name.
+//
+// Here we stand up a real McpServer via the factory, connect a real MCP Client
+// over the SDK's in-memory transport, invoke one registered tool, and assert the
+// host's onMetric sink received `("mcp_tool_duration_seconds", <number>, { tool
+// })` with tool === the exact registration name. This locks both the "monkeypatch
+// wraps tools" and "label = registration name" halves of the contract, so a
+// mutation to args.slice(0, -1) / the handler-arg detection / the capture order
+// is caught.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+
+import { createDocmostMcpServer } from "../../build/index.js";
+
+// The tool we drive. get_workspace has NO input schema, so protocol-level input
+// validation cannot short-circuit before the handler runs — the wrapped handler
+// is guaranteed to execute (and then fail on the unreachable backend, which is
+// exactly what we want: the wrapper times in a finally on throw too).
+const TOOL_NAME = "get_workspace";
+
+test("the factory's registerTool monkeypatch times a live tool call and labels it with the registration name", async () => {
+  const calls = [];
+  const onMetric = (name, value, labels) => calls.push({ name, value, labels });
+
+  // Minimal valid credentials config. apiUrl points at a port that refuses
+  // connections immediately so the tool's backend call fails FAST (ECONNREFUSED)
+  // rather than hanging — the wrapper still emits the metric from its finally.
+  const server = createDocmostMcpServer({
+    apiUrl: "http://127.0.0.1:1",
+    email: "x@example.com",
+    password: "pw",
+    onMetric,
+  });
+
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair();
+
+  const client = new Client(
+    { name: "test-client", version: "0.0.0" },
+    { capabilities: {} },
+  );
+
+  await Promise.all([
+    server.connect(serverTransport),
+    client.connect(clientTransport),
+  ]);
+
+  try {
+    // Invoke the tool. The backend is unreachable, so this either resolves with
+    // an error result (isError) or rejects — both are fine. What matters is that
+    // the handler ran through the timing wrapper, which fires onMetric either way.
+    try {
+      await client.callTool({ name: TOOL_NAME, arguments: {} });
+    } catch {
+      // Tolerate the expected backend failure surfacing as a thrown protocol error.
+    }
+
+    // The wrapper must have fed exactly the timing sample for THIS tool.
+    const timing = calls.filter(
+      (c) => c.name === "mcp_tool_duration_seconds",
+    );
+    assert.ok(
+      timing.length >= 1,
+      "onMetric must receive a mcp_tool_duration_seconds sample from the wrapped handler",
+    );
+
+    const sample = timing.find((c) => c.labels && c.labels.tool === TOOL_NAME);
+    assert.ok(
+      sample,
+      `a timing sample must be labelled with the registration name "${TOOL_NAME}"; ` +
+        `got labels: ${JSON.stringify(timing.map((c) => c.labels))}`,
+    );
+    assert.equal(typeof sample.value, "number");
+    assert.ok(sample.value >= 0, "duration must be non-negative seconds");
+  } finally {
+    await client.close();
+    await server.close();
+  }
+});

packages/mcp/test/unit/client-host-contract.test.mjs

@@ -28,8 +28,9 @@ import { DocmostClient } from "../../build/index.js";
 // in the server's DocmostClientLike interface (the in-app per-user tool adapter
 // only — it is a SUBSET of the DocmostClient surface — covers only what the in-app adapter
 // consumes; the standalone MCP transport (packages/mcp/src/index.ts) calls additional
-// client methods (insertImage/replaceImage/deleteComment/updateComment/insertFootnote)
-// that this guard does NOT track — the MCP transport's own typecheck covers those). Full type-derivation
+// client methods (deleteComment/updateComment) that this guard does NOT track — the
+// MCP transport's own typecheck covers those. insertImage/replaceImage/insertFootnote
+// were MCP-only but are now in-app-consumed too (#410), so they ARE tracked below. Full type-derivation
 // of DocmostClientLike from this class is deferred (see the staged plan in
 // docmost-client.loader.ts): the package emits no declarations and the real
 // (inferred, concrete) return types conflict with the host's loose
@@ -76,6 +77,10 @@ const HOST_CONTRACT_METHODS = [
   "restorePageVersion",
   "transformPage",
   "stashPage",
+  // write (image / footnote) — MCP-only until #410 promoted them to in-app tools
+  "insertImage",
+  "replaceImage",
+  "insertFootnote",
   // write (comment)
   "createComment",
   "resolveComment",

packages/mcp/test/unit/comment-anchor.test.mjs

@@ -8,6 +8,7 @@ import {
   applyAnchorInDoc,
   countAnchorMatches,
   getAnchoredText,
+  resolveAnchorSelection,
 } from "../../build/lib/comment-anchor.js";
 
 const COMMENT_ID = "cmt-123";
@@ -308,3 +309,70 @@ test("getAnchoredText returns null when the selection does not anchor", () => {
   const doc = paragraphDoc([{ type: "text", text: "hello world" }]);
   assert.equal(getAnchoredText(doc, "not present"), null);
 });
+
+// ---------------------------------------------------------------------------
+// #408 MARKDOWN-STRIP FALLBACK. A selection copied with inline markdown still
+// carries `**`/`` ` ``/`[t](u)` markers the plain document text lacks. When the
+// verbatim selection anchors nowhere, all four entry points retry with the
+// markdown stripped — consistently, so the suggestion-uniqueness gate stays
+// coherent — while what gets STORED remains the raw document substring.
+// ---------------------------------------------------------------------------
+test("a markdown-styled selection anchors against plain doc text via the strip fallback", () => {
+  const doc = paragraphDoc([{ type: "text", text: "a bold word here" }]);
+  // The agent quoted "**bold** word" from a styled view; the doc is plain text.
+  const sel = "**bold** word";
+  const resolved = resolveAnchorSelection(doc, sel);
+  assert.equal(resolved.found, true, "strip fallback finds the anchor");
+  assert.equal(resolved.normalized, true, "reports the soft-warning flag");
+  assert.equal(canAnchorInDoc(doc, sel), true);
+  assert.equal(countAnchorMatches(doc, sel), 1);
+
+  const ok = applyAnchorInDoc(doc, sel, COMMENT_ID);
+  assert.equal(ok, true);
+  const marked = doc.content[0].content.filter((p) => commentMark(p));
+  assert.equal(marked.map((m) => m.text).join(""), "bold word",
+    "the mark lands on the plain-text span");
+});
+
+test("getAnchoredText stores the RAW doc substring even when matched via the strip fallback", () => {
+  // Doc uses a smart apostrophe; the agent typed ASCII + markdown emphasis.
+  const doc = paragraphDoc([{ type: "text", text: "it’s bold now" }]);
+  const stored = getAnchoredText(doc, "it's **bold**");
+  assert.equal(stored, "it’s bold",
+    "stored selection is the raw document text, not the stripped/ASCII locator");
+});
+
+test("the strip fallback does not flip a raw-unique selection to ambiguous", () => {
+  // "config" appears twice, but the raw phrase "config value" appears once.
+  const doc = {
+    type: "doc",
+    content: [
+      { type: "paragraph", content: [{ type: "text", text: "the config value here" }] },
+      { type: "paragraph", content: [{ type: "text", text: "another config here" }] },
+    ],
+  };
+  // Raw phrase is unique -> exactly 1, and no strip happens (nothing to strip).
+  assert.equal(countAnchorMatches(doc, "config value"), 1);
+  assert.equal(resolveAnchorSelection(doc, "config value").normalized, false);
+});
+
+test("EXACT WINS: a raw match short-circuits the strip fallback (count reflects raw)", () => {
+  // A literal "**" run exists raw once; its stripped form would also appear.
+  const doc = paragraphDoc([{ type: "text", text: "use **stars** and stars" }]);
+  // Raw "**stars**" occurs once -> count 1 from the verbatim locator; the
+  // fallback (which would find two "stars") never runs.
+  assert.equal(countAnchorMatches(doc, "**stars**"), 1);
+  assert.equal(resolveAnchorSelection(doc, "**stars**").normalized, false);
+});
+
+test("a markdown selection whose stripped form is ambiguous is counted as ambiguous", () => {
+  const doc = {
+    type: "doc",
+    content: [
+      { type: "paragraph", content: [{ type: "text", text: "first config here" }] },
+      { type: "paragraph", content: [{ type: "text", text: "second config here" }] },
+    ],
+  };
+  // Verbatim "**config**" matches nothing; stripped "config" matches twice.
+  assert.equal(countAnchorMatches(doc, "**config**"), 2);
+});

packages/mcp/test/unit/json-edit-refuse.test.mjs

@@ -140,6 +140,36 @@ test("typo fix wrapped in markdown still applies (not refused)", () => {
   assert.deepEqual(node.marks, [{ type: "bold" }]);
 });
 
+// ---------------------------------------------------------------------------
+// (iv) #410 footnote token: a `replace` containing `^[...]` is refused into
+// failed[] (it would be written as a LITERAL string, never a real footnote).
+// Nothing is applied; the reason points at insert_footnote.
+// ---------------------------------------------------------------------------
+test("replace containing a `^[...]` footnote token is refused, not applied", () => {
+  const input = doc(paragraph(textNode("The claim stands.")));
+  const snapshot = JSON.parse(JSON.stringify(input));
+
+  const { doc: out, results, failed } = applyTextEdits(input, [
+    { find: "The claim stands.", replace: "The claim stands.^[See source, p.42]" },
+  ]);
+
+  assert.equal(results.length, 0, "nothing applied");
+  assert.equal(failed.length, 1, "one refused edit");
+  assert.equal(failed[0].find, "The claim stands.");
+  assert.match(failed[0].reason, /insert_footnote/);
+  // The document is byte-for-byte untouched — no literal `^[` was written.
+  assert.deepEqual(out, snapshot);
+});
+
+test("a plain replace with no footnote token still applies (no false positive)", () => {
+  const input = doc(paragraph(textNode("a caret ^ and a bracket ] apart")));
+  const { results, failed } = applyTextEdits(input, [
+    { find: "apart", replace: "separate" },
+  ]);
+  assert.equal(failed.length, 0, "not refused");
+  assert.equal(results.length, 1, "applied");
+});
+
 // ---------------------------------------------------------------------------
 // A plain text fix is unaffected by the refuse logic.
 // ---------------------------------------------------------------------------

packages/mcp/test/unit/tool-timing.test.mjs

@@ -0,0 +1,67 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { timeToolHandler } from "../../build/index.js";
+
+// #402 — the registerTool wrapper times every tool through a single choke point
+// and feeds the host's dependency-neutral onMetric sink. These assert the
+// timing contract without a live transport (the factory monkeypatches
+// server.registerTool with exactly this helper).
+
+test("times a tool and preserves the handler's return value", async () => {
+  const calls = [];
+  const onMetric = (name, value, labels) => calls.push({ name, value, labels });
+
+  const handler = async (arg) => ({ ok: true, echo: arg });
+  const wrapped = timeToolHandler("get_page", handler, onMetric);
+
+  const result = await wrapped("hello");
+  // Return value passes through untouched.
+  assert.deepEqual(result, { ok: true, echo: "hello" });
+
+  // Exactly one sample, correct name/labels, numeric non-negative duration.
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].name, "mcp_tool_duration_seconds");
+  assert.deepEqual(calls[0].labels, { tool: "get_page" });
+  assert.equal(typeof calls[0].value, "number");
+  assert.ok(calls[0].value >= 0, "duration must be non-negative seconds");
+});
+
+test("standalone (no onMetric) is a transparent pass-through", async () => {
+  const handler = async (a, b) => a + b;
+  const wrapped = timeToolHandler("noop_tool", handler, undefined);
+
+  // No throw, result unchanged, and nothing to observe.
+  const result = await wrapped(2, 3);
+  assert.equal(result, 5);
+});
+
+test("still observes on throw, then rethrows the original error", async () => {
+  const calls = [];
+  const onMetric = (name, value, labels) => calls.push({ name, value, labels });
+
+  const boom = new Error("handler failed");
+  const handler = async () => {
+    throw boom;
+  };
+  const wrapped = timeToolHandler("boom_tool", handler, onMetric);
+
+  await assert.rejects(() => wrapped(), (err) => err === boom);
+
+  // Observed exactly once despite the throw.
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].name, "mcp_tool_duration_seconds");
+  assert.deepEqual(calls[0].labels, { tool: "boom_tool" });
+});
+
+test("standalone still rethrows the original error (no swallow, no observe)", async () => {
+  const boom = new Error("standalone failure");
+  const wrapped = timeToolHandler(
+    "boom_standalone",
+    async () => {
+      throw boom;
+    },
+    undefined,
+  );
+  await assert.rejects(() => wrapped(), (err) => err === boom);
+});