@bli-cockpit/mcp 0.1.61 → 0.1.65

package/README.md

@@ -103,7 +103,7 @@ about what an agent can reach.
 
 <!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
 
-**107 of 112 Tower verbs have an MCP twin.**
+**109 of 114 Tower verbs have an MCP twin.**
 Each tool goes through the SAME door its CLI verb calls, with the same
 collector device token — never a second route and never a service-role
 reader. `src/verb-census.test.ts` fails when a verb is in none of the
@@ -139,8 +139,10 @@ three tables below.
 | `cockpit careers takehome show` | `careers_takehome_show` | `GET /api/careers/takehomes/[role]` |
 | `cockpit correct` | `brief_correct` | `POST /api/jarvis/corrections` |
 | `cockpit docs create` | `docs_create` | `POST /api/docs/documents` |
+| `cockpit docs link` | `docs_link` | `PUT /api/docs/documents/[id]/notion-link` |
 | `cockpit docs list` | `docs_list` | `GET /api/docs/documents` |
 | `cockpit docs read` | `docs_read` | `GET /api/docs/documents/[id]` |
+| `cockpit docs sync-status` | `docs_sync_status` | `GET /api/docs/notion-sync` |
 | `cockpit docs tree` | `docs_tree` | `GET /api/docs/tree` |
 | `cockpit docs update` | `docs_update` | `PATCH /api/docs/documents/[id]` |
 | `cockpit issue comment` | `work_comment_issue` | `POST /api/work/issues/[id]/comments` |
@@ -382,6 +384,8 @@ narrowing who can read something.
 | `docs_read` | `GET /api/docs/documents/[id]` | One document's title and full body, by id or slug (resolved against `docs_list` first). |
 | `docs_create` | `POST /api/docs/documents` | Creates a document. Omitting `body_markdown` creates an empty one. |
 | `docs_update` | `PATCH /api/docs/documents/[id]` | Updates title/body/visibility/parent (a parent change IS a move). Emptying a document that holds text needs `allow_empty: true` (BLI-3757's guard). |
+| `docs_link` | `PUT`/`DELETE /api/docs/documents/[id]/notion-link` | Ties a document to a Notion page for the two-way sync (`notion_page`: a URL or page id), or unties it with `clear: true`. The page becomes the truth: the next sync pulls it over the copy and keeps the copy as a version. |
+| `docs_sync_status` | `GET /api/docs/notion-sync` | Every linked document's sync state (`synced` / `tower_changed` / `never_synced`), or one's by `id`. Tower's half only; metadata, never a body. |
 | `msg_channels` | `GET /api/msg/channels` | Every channel you are a member of. |
 | `msg_read` | `GET /api/msg/channels/[id]/messages` | Recent messages of one channel, newest first. `channel` is an id or a `#name`. |
 | `msg_thread` | `GET /api/msg/channels/[id]/messages?thread_parent_id=` | One thread's replies, oldest first, so it reads as a conversation. |

package/dist/docs-msg-helpers.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Helpers behind the `docs_*` and `msg_*` tools (split out of
+ * `docs-msg-tools.ts` to keep it under the file-size ratchet): id resolution,
+ * list shaping and one-line renderers. No tool is registered here.
+ */
+import { type ToolDeps } from "./tool-result.js";
+/** A canonical uuid: a ref that already IS an id needs no list read to resolve. */
+export declare const UUID_PATTERN: RegExp;
+/** The door's own ceiling on `?limit=` (`/api/docs/documents` `DOCUMENT_LIST_MAX_LIMIT`). */
+export declare const DOCS_LIST_MAX = 1000;
+export type DocsMsgDeps = ToolDeps;
+/** One node of `GET /api/docs/tree`. The door nests; nothing here re-nests. */
+export interface DocTreeNode {
+    id: string;
+    title: string;
+    slug: string | null;
+    children: DocTreeNode[];
+}
+/**
+ * The tree as the text half prints it: id, title, slug, children. The door
+ * also sends visibility, source and a timestamp per node, which nothing here
+ * promised and which made the structured half 48 KB for 226 documents
+ * (BLI-10432). `docs_list` carries those fields for a flat read.
+ */
+export declare function slimTree(nodes: DocTreeNode[]): DocTreeNode[];
+/** Indented lines, deepest last — the same shape `cockpit docs tree` prints. */
+export declare function renderDocTree(nodes: DocTreeNode[], depth: number): string;
+export declare function countTree(nodes: DocTreeNode[]): number;
+export interface DocRow {
+    id: string;
+    title: string;
+    slug: string | null;
+    visibility: string;
+    source?: string | null;
+    parent_id?: string | null;
+    updated_at: string;
+    /** BLI-3737: the body's length, the one fact about a body the LIST still carries. */
+    body_chars?: number;
+}
+/**
+ * The fields `docs_list` promises, and only those. The door's row also carries
+ * `created_by`, `updated_by`, `created_at`, `import_truncated` and
+ * `missing_block_count`: 105 KB for 226 documents before this (BLI-10432).
+ */
+export declare function docListRow(row: DocRow): Record<string, unknown>;
+export declare function docListLine(row: DocRow): string;
+/**
+ * `docs_list`'s narrowing, as the door's own query parameters (BLI-3737).
+ * The list itself is metadata only — asking for a whole library used to cost
+ * every document's prose, so an agent that wants one folder or one phrase
+ * says so here and the database does the filtering.
+ */
+export declare function docsListPath(args: {
+    parent_id?: unknown;
+    query?: unknown;
+    word?: unknown;
+    limit?: unknown;
+}): string;
+export declare function resolveDocumentId(deps: DocsMsgDeps, session: {
+    dashboardUrl: string;
+    deviceToken: string;
+}, ref: string): Promise<{
+    status: "ok";
+    id: string;
+} | {
+    status: "not_found";
+} | {
+    status: "list_failed";
+    text: string;
+}>;
+export interface ChannelRow {
+    id: string;
+    name: string | null;
+    is_private: boolean;
+    is_dm: boolean;
+}
+export declare function resolveChannelId(deps: DocsMsgDeps, session: {
+    dashboardUrl: string;
+    deviceToken: string;
+}, ref: string): Promise<{
+    status: "ok";
+    id: string;
+} | {
+    status: "not_found";
+} | {
+    status: "list_failed";
+    text: string;
+}>;
+/** One message as a line: id (msg_thread's `thread_parent_id`), time, author, text. */
+export declare function messageLine(message: Record<string, unknown>): string;

package/dist/docs-msg-helpers.js

@@ -0,0 +1,110 @@
+/**
+ * Helpers behind the `docs_*` and `msg_*` tools (split out of
+ * `docs-msg-tools.ts` to keep it under the file-size ratchet): id resolution,
+ * list shaping and one-line renderers. No tool is registered here.
+ */
+import { callAgentDoor } from "./agent-door.js";
+import { DEFAULT_LIST_LIMIT, doorFailureText } from "./tool-result.js";
+/** A canonical uuid: a ref that already IS an id needs no list read to resolve. */
+export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+/** The door's own ceiling on `?limit=` (`/api/docs/documents` `DOCUMENT_LIST_MAX_LIMIT`). */
+export const DOCS_LIST_MAX = 1000;
+/**
+ * The tree as the text half prints it: id, title, slug, children. The door
+ * also sends visibility, source and a timestamp per node, which nothing here
+ * promised and which made the structured half 48 KB for 226 documents
+ * (BLI-10432). `docs_list` carries those fields for a flat read.
+ */
+export function slimTree(nodes) {
+    return nodes.map((node) => ({
+        id: node.id,
+        title: node.title,
+        slug: node.slug ?? null,
+        children: slimTree(Array.isArray(node.children) ? node.children : []),
+    }));
+}
+/** Indented lines, deepest last — the same shape `cockpit docs tree` prints. */
+export function renderDocTree(nodes, depth) {
+    return nodes
+        .map((node) => {
+        const line = `${"  ".repeat(depth)}${node.title} (${node.slug ?? node.id})`;
+        const children = node.children?.length ? `\n${renderDocTree(node.children, depth + 1)}` : "";
+        return `${line}${children}`;
+    })
+        .join("\n");
+}
+export function countTree(nodes) {
+    return nodes.reduce((count, node) => count + 1 + countTree(node.children ?? []), 0);
+}
+/**
+ * The fields `docs_list` promises, and only those. The door's row also carries
+ * `created_by`, `updated_by`, `created_at`, `import_truncated` and
+ * `missing_block_count`: 105 KB for 226 documents before this (BLI-10432).
+ */
+export function docListRow(row) {
+    return {
+        id: row.id,
+        slug: row.slug ?? null,
+        title: row.title,
+        visibility: row.visibility,
+        source: row.source ?? null,
+        parent_id: row.parent_id ?? null,
+        updated_at: row.updated_at,
+        body_chars: row.body_chars ?? null,
+    };
+}
+export function docListLine(row) {
+    return `${row.id}  ${row.slug ?? "-"}  ${row.title}  [${row.visibility}${row.source ? `, ${row.source}` : ""}, `
+        + `${row.body_chars ?? "?"} chars, parent ${row.parent_id ?? "root"}, updated ${row.updated_at}]`;
+}
+/**
+ * `docs_list`'s narrowing, as the door's own query parameters (BLI-3737).
+ * The list itself is metadata only — asking for a whole library used to cost
+ * every document's prose, so an agent that wants one folder or one phrase
+ * says so here and the database does the filtering.
+ */
+export function docsListPath(args) {
+    const params = new URLSearchParams();
+    if (typeof args.parent_id === "string" && args.parent_id.length > 0)
+        params.set("parent_id", args.parent_id);
+    const hasQuery = typeof args.query === "string" && args.query.trim().length > 0;
+    if (hasQuery)
+        params.set("query", args.query);
+    // BLI-10451: whole words, the same `word=1` the CLI's `--word` sends.
+    if (hasQuery && args.word === true)
+        params.set("word", "1");
+    if (typeof args.limit === "number" && Number.isInteger(args.limit))
+        params.set("limit", String(args.limit));
+    // No limit named: one page plus one row, so "more exist" is read off the
+    // door instead of guessed from a full page (BLI-10432).
+    else if (args.limit === undefined)
+        params.set("limit", String(DEFAULT_LIST_LIMIT + 1));
+    const search = params.toString();
+    return search.length > 0 ? `/api/docs/documents?${search}` : "/api/docs/documents";
+}
+export async function resolveDocumentId(deps, session, ref) {
+    // An id needs no lookup: the read itself answers 404 by name when it is
+    // wrong. Only a slug costs the whole-library list read (BLI-10432).
+    if (UUID_PATTERN.test(ref))
+        return { status: "ok", id: ref };
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/docs/documents");
+    if (!response.ok)
+        return { status: "list_failed", text: doorFailureText("docs_list", response) };
+    const documents = (Array.isArray(response.body.documents) ? response.body.documents : []);
+    const match = documents.find((doc) => doc.id === ref || doc.slug === ref);
+    return match ? { status: "ok", id: match.id } : { status: "not_found" };
+}
+export async function resolveChannelId(deps, session, ref) {
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/msg/channels");
+    if (!response.ok)
+        return { status: "list_failed", text: doorFailureText("msg_channels", response) };
+    const channels = (Array.isArray(response.body.channels) ? response.body.channels : []);
+    const bare = ref.startsWith("#") ? ref.slice(1) : ref;
+    const match = channels.find((channel) => channel.id === ref || channel.name === bare);
+    return match ? { status: "ok", id: match.id } : { status: "not_found" };
+}
+/** One message as a line: id (msg_thread's `thread_parent_id`), time, author, text. */
+export function messageLine(message) {
+    return `${String(message.id ?? "?")}  ${String(message.created_at ?? "?")}  `
+        + `${String(message.agent_label ?? message.user_id ?? message.slack_author_label ?? "?")}  ${String(message.content ?? "")}`;
+}

package/dist/docs-msg-tools.d.ts

@@ -9,19 +9,9 @@
  * on a machine with no collector pairing at all, so a missing session must
  * fail the ONE call that needed it, never the whole process.
  */
-import { type ToolDeps } from "./tool-result.js";
-export type DocsMsgDeps = ToolDeps;
-/**
- * `docs_list`'s narrowing, as the door's own query parameters (BLI-3737).
- * The list itself is metadata only — asking for a whole library used to cost
- * every document's prose, so an agent that wants one folder or one phrase
- * says so here and the database does the filtering.
- */
-export declare function docsListPath(args: {
-    parent_id?: unknown;
-    query?: unknown;
-    limit?: unknown;
-}): string;
+import { type DocsMsgDeps } from "./docs-msg-helpers.js";
+export { docsListPath } from "./docs-msg-helpers.js";
+export type { DocsMsgDeps } from "./docs-msg-helpers.js";
 export declare function registerDocsMsgTools(server: {
     registerTool: (...args: never[]) => unknown;
 }, deps: DocsMsgDeps): void;

package/dist/docs-msg-tools.js

@@ -12,116 +12,22 @@
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
 import { DEFAULT_LIST_LIMIT, doorFailureText, errorResult, moreNote, registrarFor, textResult, withSession, } from "./tool-result.js";
-/** A canonical uuid: a ref that already IS an id needs no list read to resolve. */
-const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
-/** The door's own ceiling on `?limit=` (`/api/docs/documents` `DOCUMENT_LIST_MAX_LIMIT`). */
-const DOCS_LIST_MAX = 1000;
-/**
- * The tree as the text half prints it: id, title, slug, children. The door
- * also sends visibility, source and a timestamp per node, which nothing here
- * promised and which made the structured half 48 KB for 226 documents
- * (BLI-10432). `docs_list` carries those fields for a flat read.
- */
-function slimTree(nodes) {
-    return nodes.map((node) => ({
-        id: node.id,
-        title: node.title,
-        slug: node.slug ?? null,
-        children: slimTree(Array.isArray(node.children) ? node.children : []),
-    }));
-}
-/** Indented lines, deepest last — the same shape `cockpit docs tree` prints. */
-function renderDocTree(nodes, depth) {
-    return nodes
-        .map((node) => {
-        const line = `${"  ".repeat(depth)}${node.title} (${node.slug ?? node.id})`;
-        const children = node.children?.length ? `\n${renderDocTree(node.children, depth + 1)}` : "";
-        return `${line}${children}`;
-    })
-        .join("\n");
-}
-function countTree(nodes) {
-    return nodes.reduce((count, node) => count + 1 + countTree(node.children ?? []), 0);
-}
-/**
- * The fields `docs_list` promises, and only those. The door's row also carries
- * `created_by`, `updated_by`, `created_at`, `import_truncated` and
- * `missing_block_count`: 105 KB for 226 documents before this (BLI-10432).
- */
-function docListRow(row) {
-    return {
-        id: row.id,
-        slug: row.slug ?? null,
-        title: row.title,
-        visibility: row.visibility,
-        source: row.source ?? null,
-        parent_id: row.parent_id ?? null,
-        updated_at: row.updated_at,
-        body_chars: row.body_chars ?? null,
-    };
-}
-function docListLine(row) {
-    return `${row.id}  ${row.slug ?? "-"}  ${row.title}  [${row.visibility}${row.source ? `, ${row.source}` : ""}, `
-        + `${row.body_chars ?? "?"} chars, parent ${row.parent_id ?? "root"}, updated ${row.updated_at}]`;
-}
-/**
- * `docs_list`'s narrowing, as the door's own query parameters (BLI-3737).
- * The list itself is metadata only — asking for a whole library used to cost
- * every document's prose, so an agent that wants one folder or one phrase
- * says so here and the database does the filtering.
- */
-export function docsListPath(args) {
-    const params = new URLSearchParams();
-    if (typeof args.parent_id === "string" && args.parent_id.length > 0)
-        params.set("parent_id", args.parent_id);
-    if (typeof args.query === "string" && args.query.trim().length > 0)
-        params.set("query", args.query);
-    if (typeof args.limit === "number" && Number.isInteger(args.limit))
-        params.set("limit", String(args.limit));
-    // No limit named: one page plus one row, so "more exist" is read off the
-    // door instead of guessed from a full page (BLI-10432).
-    else if (args.limit === undefined)
-        params.set("limit", String(DEFAULT_LIST_LIMIT + 1));
-    const search = params.toString();
-    return search.length > 0 ? `/api/docs/documents?${search}` : "/api/docs/documents";
-}
-async function resolveDocumentId(deps, session, ref) {
-    // An id needs no lookup: the read itself answers 404 by name when it is
-    // wrong. Only a slug costs the whole-library list read (BLI-10432).
-    if (UUID_PATTERN.test(ref))
-        return { status: "ok", id: ref };
-    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/docs/documents");
-    if (!response.ok)
-        return { status: "list_failed", text: doorFailureText("docs_list", response) };
-    const documents = (Array.isArray(response.body.documents) ? response.body.documents : []);
-    const match = documents.find((doc) => doc.id === ref || doc.slug === ref);
-    return match ? { status: "ok", id: match.id } : { status: "not_found" };
-}
-async function resolveChannelId(deps, session, ref) {
-    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/msg/channels");
-    if (!response.ok)
-        return { status: "list_failed", text: doorFailureText("msg_channels", response) };
-    const channels = (Array.isArray(response.body.channels) ? response.body.channels : []);
-    const bare = ref.startsWith("#") ? ref.slice(1) : ref;
-    const match = channels.find((channel) => channel.id === ref || channel.name === bare);
-    return match ? { status: "ok", id: match.id } : { status: "not_found" };
-}
-/** One message as a line: id (msg_thread's `thread_parent_id`), time, author, text. */
-function messageLine(message) {
-    return `${String(message.id ?? "?")}  ${String(message.created_at ?? "?")}  `
-        + `${String(message.agent_label ?? message.user_id ?? "?")}  ${String(message.content ?? "")}`;
-}
+import { DOCS_LIST_MAX, slimTree, renderDocTree, countTree, docListRow, docListLine, resolveDocumentId, resolveChannelId, messageLine, docsListPath } from "./docs-msg-helpers.js";
+import { runDocsReadTool } from "./docs-read-tool.js";
+export { docsListPath } from "./docs-msg-helpers.js";
 export function registerDocsMsgTools(server, deps) {
     const register = registrarFor(server);
     register("docs_list", {
         title: "List Tower documents",
         description: "Every document you may read: id, slug, title, visibility, source, parent_id and body_chars (how long the body is). "
             + "Never a document's body — call docs_read for that. Narrow before reading: parent_id (a document id, or \"root\" for the "
-            + "top of the tree), query (a case-insensitive substring matched in the database over title AND body, never fuzzy), "
+            + "top of the tree), query (a case-insensitive substring matched in the database over title AND body, never fuzzy; "
+            + "word: true matches it as whole words, so \"ott\" stops matching \"bottom\"), "
             + `limit (1-1000, default ${DEFAULT_LIST_LIMIT}; the answer says when more exist).`,
         inputSchema: {
             parent_id: z.string().min(1).max(64).optional().describe('A document id to list under, or "root" for the top of the tree.'),
             query: z.string().min(1).max(200).optional().describe("Keep only documents whose title or body contains this text."),
+            word: z.boolean().optional().describe("Match query as whole words rather than a substring. Needs query."),
             limit: z.number().int().min(1).max(1000).optional().describe(`At most this many documents. Default ${DEFAULT_LIST_LIMIT}.`),
         },
     }, async (args) => withSession(deps, async (session) => {
@@ -149,21 +55,25 @@ export function registerDocsMsgTools(server, deps) {
     }));
     register("docs_read", {
         title: "Read a Tower document",
-        description: "One document's title and full body, by its id or slug (docs_list returns both).",
-        inputSchema: { id: z.string().min(1).max(200).describe("A document id, or its slug.") },
-    }, async (args) => withSession(deps, async (session) => {
-        const ref = String(args.id ?? "");
-        const resolved = await resolveDocumentId(deps, session, ref);
-        if (resolved.status === "list_failed")
-            return errorResult(resolved.text);
-        if (resolved.status === "not_found")
-            return errorResult(`No document matches "${ref}" — check docs_list for the id or slug.`);
-        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/docs/documents/${encodeURIComponent(resolved.id)}`);
-        if (!response.ok)
-            return errorResult(doorFailureText("docs_read", response));
-        const document = response.body.document;
-        return textResult(`${document?.title ?? ""}\n\n${document?.body_markdown ?? ""}`, { document });
-    }));
+        description: "A document's title and body, by id or slug (docs_list returns both). Three shapes (BLI-10450): "
+            + "`id` — one document, answers { document }. `ids` — several in one call (one shared list resolve, then "
+            + "one GET per document — no bulk body door exists), answers { documents: [{ ref, ok, document|error }] }, "
+            + "one bad ref never losing the rest. `parent_id` + `bodies: true` — every document filed directly under "
+            + "that parent, bodies included, in ONE call, answers { documents: [...] }. "
+            + "`section`/`offset`/`limit` narrow whatever body was fetched, in every shape: `section` slices from a "
+            + "matching Markdown heading (any level, case-insensitive) to the next heading at the same or shallower "
+            + "level, mirroring `cockpit workbook`'s own --section; `offset`/`limit` slice by character range — for a "
+            + "100-225 KB transcript, read it in parts instead of whole.",
+        inputSchema: {
+            id: z.string().min(1).max(200).optional().describe("A document id, or its slug. Omit when passing ids or parent_id."),
+            ids: z.array(z.string().min(1).max(200)).min(1).max(50).optional().describe("Several documents in one call."),
+            parent_id: z.string().min(1).max(64).optional().describe("With bodies: true, read every document filed directly under this one (or \"root\")."),
+            bodies: z.boolean().optional().describe("Only with parent_id: include each document's body_markdown."),
+            section: z.string().min(1).max(200).optional().describe("One section's heading text — slices from there to the next heading at the same or shallower level."),
+            offset: z.number().int().min(0).optional().describe("The body's character offset to start from; paired with limit."),
+            limit: z.number().int().min(1).optional().describe("With an explicit ref: at most this many characters. With parent_id + bodies: at most this many documents (1-50)."),
+        },
+    }, async (args) => runDocsReadTool(deps, args));
     register("docs_create", {
         title: "Create a Tower document",
         description: "Creates a new document. Omitting body creates an empty one, matching the browser's own default.",
@@ -276,7 +186,15 @@ export function registerDocsMsgTools(server, deps) {
         // which is what msg_thread takes. It used to say only "2 message(s)",
         // so a Claude-family client never saw one (BLI-10432).
         const lines = messages.map(messageLine).join("\n");
-        return textResult(`${messages.length} message(s) in ${ref}, newest first; each line is id, time, author, text.${lines ? `\n${lines}` : ""}`, { channelId: resolved.id, messages });
+        // BLI-10449: Tower's own channel, or a Slack snapshot and how fresh —
+        // the door's sentence, word for word, the same line the CLI prints.
+        const provenance = (response.body.provenance ?? null);
+        const limitApplied = typeof response.body.limitApplied === "number" ? response.body.limitApplied : null;
+        const header = [
+            provenance?.sentence ?? null,
+            limitApplied !== null ? `Showing the newest ${limitApplied}: one read returns at most ${limitApplied} messages.` : null,
+        ].filter(Boolean).join("\n");
+        return textResult(`${header ? `${header}\n` : ""}${messages.length} message(s) in ${ref}, newest first; each line is id, time, author, text.${lines ? `\n${lines}` : ""}`, { channelId: resolved.id, provenance, limitApplied, messages });
     }));
     register("msg_thread", {
         title: "Read a Tower message thread",

package/dist/docs-notion-tools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The Notion half of the `docs_*` tools (BLI-10430) — the same door
+ * `cockpit docs link` calls, over this machine's device token. A sibling of
+ * `docs-msg-tools.ts` rather than more of it, the same split the collector
+ * makes (`commands/docs-notion.ts`).
+ *
+ * `docs_link` → `PUT /api/docs/documents/[id]/notion-link` (or `DELETE` with
+ * `clear: true`). A link makes the Notion page the truth: the next sync pulls
+ * it over the Tower copy and keeps the copy as a version.
+ * `docs_sync_status` → `GET /api/docs/notion-sync[?document_id=]`: Tower's half
+ * of the sync state, metadata only.
+ */
+import { type DocsMsgDeps } from "./docs-msg-helpers.js";
+export declare function registerDocsNotionTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: DocsMsgDeps): void;

package/dist/docs-notion-tools.js

@@ -0,0 +1,89 @@
+/**
+ * The Notion half of the `docs_*` tools (BLI-10430) — the same door
+ * `cockpit docs link` calls, over this machine's device token. A sibling of
+ * `docs-msg-tools.ts` rather than more of it, the same split the collector
+ * makes (`commands/docs-notion.ts`).
+ *
+ * `docs_link` → `PUT /api/docs/documents/[id]/notion-link` (or `DELETE` with
+ * `clear: true`). A link makes the Notion page the truth: the next sync pulls
+ * it over the Tower copy and keeps the copy as a version.
+ * `docs_sync_status` → `GET /api/docs/notion-sync[?document_id=]`: Tower's half
+ * of the sync state, metadata only.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { resolveDocumentId } from "./docs-msg-helpers.js";
+import { doorFailureText, errorResult, registrarFor, textResult, withSession } from "./tool-result.js";
+export function registerDocsNotionTools(server, deps) {
+    const register = registrarFor(server);
+    register("docs_link", {
+        title: "Link a Tower document to a Notion page",
+        description: "Ties a document to a Notion page so the two-way sync moves it both ways, or unties it with clear: true. "
+            + "The page becomes the truth: the next sync pulls it over this copy and keeps the copy as a version. "
+            + "Refusals keep Tower's reason: invalid_notion_page, notion_page_already_linked, document_not_writable.",
+        inputSchema: {
+            id: z.string().min(1).max(200).describe("A document id, or its slug."),
+            notion_page: z
+                .string()
+                .min(1)
+                .max(500)
+                .optional()
+                .describe("The Notion page URL (app.notion.com/p/… or notion.so/…) or its page id."),
+            clear: z.boolean().optional().describe("true to untie the document from Notion instead."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const clear = args.clear === true;
+        const notionPage = typeof args.notion_page === "string" ? args.notion_page : undefined;
+        if (clear === Boolean(notionPage)) {
+            return errorResult("docs_link needs exactly one of notion_page (to link) or clear: true (to unlink).");
+        }
+        const ref = String(args.id ?? "");
+        const resolved = await resolveDocumentId(deps, session, ref);
+        if (resolved.status === "list_failed")
+            return errorResult(resolved.text);
+        if (resolved.status === "not_found")
+            return errorResult(`No document matches "${ref}" — check docs_list for the id or slug.`);
+        const path = `/api/docs/documents/${encodeURIComponent(resolved.id)}/notion-link`;
+        const response = clear
+            ? await callAgentDoor(session, deps.fetchImpl, "DELETE", path)
+            : await callAgentDoor(session, deps.fetchImpl, "PUT", path, { notion_page: notionPage });
+        if (!response.ok)
+            return errorResult(doorFailureText("docs_link", response));
+        const outcome = String(response.body.outcome ?? "");
+        const document = response.body.document;
+        return textResult(`${outcome || "done"}: "${document?.title ?? ""}" (${document?.id ?? resolved.id}).`, {
+            outcome,
+            document,
+        });
+    }));
+    register("docs_sync_status", {
+        title: "Read the Tower-Notion sync status",
+        description: "Every document linked to a Notion page (or one, by id or slug) with its sync state: synced (the body is what "
+            + "both sides last agreed on), tower_changed (edited in Tower since; the next write-back pushes it), never_synced "
+            + "(linked, no baseline yet). Tower's half only: a Notion edit shows up at the next pull. Never a body.",
+        inputSchema: {
+            id: z.string().min(1).max(200).optional().describe("A document id or slug, for one document's status."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        let path = "/api/docs/notion-sync";
+        if (typeof args.id === "string" && args.id.length > 0) {
+            const resolved = await resolveDocumentId(deps, session, args.id);
+            if (resolved.status === "list_failed")
+                return errorResult(resolved.text);
+            if (resolved.status === "not_found")
+                return errorResult(`No document matches "${args.id}" — check docs_list for the id or slug.`);
+            path = `${path}?document_id=${encodeURIComponent(resolved.id)}`;
+        }
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", path);
+        if (!response.ok)
+            return errorResult(doorFailureText("docs_sync_status", response));
+        const counts = response.body.counts;
+        const summary = Object.entries(counts?.by_state ?? {})
+            .map(([state, count]) => `${count} ${state}`)
+            .join(", ");
+        return textResult(`${counts?.linked ?? 0} linked: ${summary}.`, {
+            counts,
+            documents: response.body.documents ?? [],
+        });
+    }));
+}

package/dist/docs-read-tool.d.ts

@@ -0,0 +1,23 @@
+import { type DocsMsgDeps } from "./docs-msg-helpers.js";
+import { type ToolResult } from "./tool-result.js";
+/** Mirrors `commands/docs-read.ts` `sliceDocSection` exactly. */
+export declare function sliceDocSection(markdown: string, wanted: string): {
+    text: string;
+    headings: string[];
+} | null;
+/** Mirrors `commands/docs-read.ts` `sliceDocRange` exactly. */
+export declare function sliceDocRange(body: string, offset: number | undefined, limit: number | undefined): {
+    text: string;
+    truncated: boolean;
+    totalChars: number;
+};
+export interface DocsReadArgs {
+    id?: unknown;
+    ids?: unknown;
+    parent_id?: unknown;
+    bodies?: unknown;
+    section?: unknown;
+    offset?: unknown;
+    limit?: unknown;
+}
+export declare function runDocsReadTool(deps: DocsMsgDeps, args: DocsReadArgs): Promise<ToolResult>;

package/dist/docs-read-tool.js

@@ -0,0 +1,175 @@
+/**
+ * `docs_read` (BLI-10450) — the MCP twin of `cockpit docs read`'s three
+ * shapes, split out of `docs-msg-tools.ts` to keep it under the file-size
+ * ratchet:
+ *
+ * 1. `id` — unchanged: one document, `{ document }`.
+ * 2. `ids` — several references in one call. One shared list resolves every
+ *    ref (a uuid ref skips the list read entirely — `resolveDocumentIds`),
+ *    then one GET per document. `{ documents: [{ ref, ok, document|error }] }`.
+ * 3. `parent_id` + `bodies: true` — every document filed directly under that
+ *    parent, bodies included, in ONE call
+ *    (`GET /api/docs/documents?parent_id=...&bodies=true`).
+ *
+ * `section`/`offset`/`limit` narrow whatever body was fetched, in every
+ * shape above — the same slicing `commands/docs-read.ts` runs on the CLI.
+ */
+import { callAgentDoor } from "./agent-door.js";
+import { resolveDocumentId } from "./docs-msg-helpers.js";
+import { doorFailureText, errorResult, textResult, withSession } from "./tool-result.js";
+function headingsOf(markdown) {
+    return markdown
+        .split("\n")
+        .map((line, lineIndex) => ({ lineIndex, line }))
+        .map(({ lineIndex, line }) => {
+        const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+        return match?.[1] && match[2] ? { lineIndex, level: match[1].length, title: match[2] } : null;
+    })
+        .filter((heading) => heading !== null);
+}
+/** Mirrors `commands/docs-read.ts` `sliceDocSection` exactly. */
+export function sliceDocSection(markdown, wanted) {
+    const headings = headingsOf(markdown);
+    const target = headings.find((heading) => heading.title.toLowerCase() === wanted.trim().toLowerCase());
+    if (!target)
+        return null;
+    const lines = markdown.split("\n");
+    const next = headings.find((heading) => heading.lineIndex > target.lineIndex && heading.level <= target.level);
+    const endLine = next ? next.lineIndex : lines.length;
+    return { text: lines.slice(target.lineIndex, endLine).join("\n").trim(), headings: headings.map((h) => h.title) };
+}
+/** Mirrors `commands/docs-read.ts` `sliceDocRange` exactly. */
+export function sliceDocRange(body, offset, limit) {
+    const totalChars = body.length;
+    if (offset === undefined && limit === undefined)
+        return { text: body, truncated: false, totalChars };
+    const start = Math.min(offset ?? 0, totalChars);
+    const end = limit === undefined ? totalChars : Math.min(start + limit, totalChars);
+    return { text: body.slice(start, end), truncated: end < totalChars, totalChars };
+}
+/**
+ * `applyCharRange` is false in `parent_id` + `bodies: true` mode: there,
+ * `limit` already picked the DOCUMENT COUNT (mirrors `commands/docs-read.ts`
+ * — a live-fire probe against production caught this exact overload
+ * silently truncating every body to a handful of characters when `limit`
+ * was passed meaning "N documents").
+ */
+function narrowBody(document, section, offset, limit, applyCharRange) {
+    let body = typeof document.body_markdown === "string" ? document.body_markdown : "";
+    if (section) {
+        const sliced = sliceDocSection(body, section);
+        if (!sliced) {
+            const known = headingsOf(body).map((heading) => heading.title);
+            return { ok: false, text: `No section "${section}" in ${document.id} (${known.join(", ") || "none"}).` };
+        }
+        body = sliced.text;
+    }
+    if (applyCharRange && (offset !== undefined || limit !== undefined))
+        body = sliceDocRange(body, offset, limit).text;
+    document.body_markdown = body;
+    return { ok: true };
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+/** One shared list read for every non-uuid ref, never one per ref. */
+async function resolveDocumentIds(deps, session, refs) {
+    const ids = new Map();
+    const needsList = refs.filter((ref) => !UUID_PATTERN.test(ref));
+    for (const ref of refs)
+        if (UUID_PATTERN.test(ref))
+            ids.set(ref, ref);
+    if (needsList.length === 0)
+        return { status: "ok", ids };
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/docs/documents");
+    if (!response.ok)
+        return { status: "list_failed", text: doorFailureText("docs_list", response) };
+    const documents = (Array.isArray(response.body.documents) ? response.body.documents : []);
+    for (const ref of needsList) {
+        const match = documents.find((doc) => doc.id === ref || doc.slug === ref);
+        if (match)
+            ids.set(ref, match.id);
+    }
+    return { status: "ok", ids };
+}
+async function fetchOneDocument(deps, session, ref, id) {
+    if (!id)
+        return { ref, ok: false, text: `No document matches "${ref}" — check docs_list for the id or slug.` };
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/docs/documents/${encodeURIComponent(id)}`);
+    if (!response.ok)
+        return { ref, ok: false, text: doorFailureText("docs_read", response) };
+    const document = (response.body.document ?? { id });
+    return { ref, ok: true, document };
+}
+export async function runDocsReadTool(deps, args) {
+    return withSession(deps, async (session) => {
+        const section = typeof args.section === "string" ? args.section : undefined;
+        const offset = typeof args.offset === "number" ? args.offset : undefined;
+        const limit = typeof args.limit === "number" ? args.limit : undefined;
+        // Shape 3: --parent + --bodies. Built by hand rather than through
+        // `docsListPath`: that helper defaults a missing limit to
+        // DEFAULT_LIST_LIMIT + 1 for the METADATA list's "more exist" check,
+        // which would overshoot the door's own DOCUMENT_BODIES_MAX_LIMIT (50)
+        // here and turn an unset limit into a refusal.
+        if (typeof args.parent_id === "string" && args.parent_id && args.bodies === true) {
+            const params = new URLSearchParams({ parent_id: args.parent_id, bodies: "true" });
+            if (limit !== undefined)
+                params.set("limit", String(limit));
+            const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/docs/documents?${params.toString()}`);
+            if (!response.ok)
+                return errorResult(doorFailureText("docs_read", response));
+            const documents = (Array.isArray(response.body.documents) ? response.body.documents : []);
+            const misses = [];
+            for (const document of documents) {
+                // `limit` already picked the DOCUMENT COUNT above; `false` keeps it
+                // from being reapplied as a character count.
+                const narrowed = narrowBody(document, section, offset, limit, false);
+                if (!narrowed.ok)
+                    misses.push(narrowed.text);
+            }
+            return textResult(`${documents.length} document(s) under ${String(args.parent_id)}.${misses.length ? `\n${misses.join("\n")}` : ""}`, { documents });
+        }
+        // Shapes 1/2: id, or ids (several).
+        const refs = Array.isArray(args.ids) && args.ids.length > 0
+            ? args.ids.map(String)
+            : [String(args.id ?? "")];
+        if (refs.length === 1 && refs[0] === "") {
+            return errorResult("docs_read needs id, ids, or parent_id + bodies: true.");
+        }
+        const resolved = refs.length === 1
+            ? await (async () => {
+                const one = await resolveDocumentId(deps, session, refs[0]);
+                if (one.status === "list_failed")
+                    return { status: "list_failed", text: one.text };
+                const ids = new Map();
+                if (one.status === "ok")
+                    ids.set(refs[0], one.id);
+                return { status: "ok", ids };
+            })()
+            : await resolveDocumentIds(deps, session, refs);
+        if (resolved.status === "list_failed")
+            return errorResult(resolved.text);
+        const results = await Promise.all(refs.map((ref) => fetchOneDocument(deps, session, ref, resolved.ids.get(ref))));
+        for (const result of results) {
+            if (result.ok) {
+                // Not `--parent --bodies` mode: `limit` here is a CHARACTER count.
+                const narrowed = narrowBody(result.document, section, offset, limit, true);
+                if (!narrowed.ok)
+                    Object.assign(result, { ok: false, text: narrowed.text });
+            }
+        }
+        if (refs.length === 1) {
+            const [result] = results;
+            if (!result?.ok)
+                return errorResult(result?.text ?? "docs_read could not read that document.");
+            return textResult(`${result.document.title ?? ""}\n\n${result.document.body_markdown ?? ""}`, { document: result.document });
+        }
+        const failed = results.filter((result) => !result.ok);
+        const lines = results
+            .map((result) => (result.ok ? `${result.document.title ?? result.ref}\n\n${result.document.body_markdown ?? ""}` : `${result.ref}: ${result.text}`))
+            .join("\n\n---\n\n");
+        return textResult(`${results.length - failed.length}/${results.length} document(s) read.\n\n${lines}`, {
+            documents: results.map((result) => result.ok
+                ? { ref: result.ref, ok: true, document: result.document }
+                : { ref: result.ref, ok: false, error: result.text }),
+        });
+    });
+}

package/dist/notes-meeting-docs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * BLI-10449: the notes library door's pointer at meeting records that live in
+ * Docs, not Notes (`apps/dashboard/src/lib/notes/meeting-docs.ts` decides what
+ * counts and which copy is canonical). `notes_list` prints these lines under
+ * the notes; the CLI's twin is `meetingDocumentLines` in the collector's
+ * `commands/notes-reads.ts`, and the two print the same words.
+ */
+export interface MeetingDocuments {
+    count: number;
+    copies: number;
+    truncated: boolean;
+    items: Array<{
+        id: string;
+        slug: string | null;
+        title: string;
+        meetingDate: string | null;
+        visibility: string;
+        source: string;
+        bodyChars: number;
+        parts: string[];
+        canonical: boolean;
+        duplicateOf: string | null;
+        canonicalReason: string | null;
+    }>;
+}
+export declare function meetingDocumentLines(meeting: MeetingDocuments | null | undefined, readVerb: string): string[];

package/dist/notes-meeting-docs.js

@@ -0,0 +1,26 @@
+/**
+ * BLI-10449: the notes library door's pointer at meeting records that live in
+ * Docs, not Notes (`apps/dashboard/src/lib/notes/meeting-docs.ts` decides what
+ * counts and which copy is canonical). `notes_list` prints these lines under
+ * the notes; the CLI's twin is `meetingDocumentLines` in the collector's
+ * `commands/notes-reads.ts`, and the two print the same words.
+ */
+export function meetingDocumentLines(meeting, readVerb) {
+    if (!meeting || meeting.count === 0)
+        return [];
+    const refOf = new Map(meeting.items.map((item) => [item.id, item.slug ?? item.id]));
+    const copies = meeting.copies > 0 ? `, ${meeting.copies} of them ${meeting.copies === 1 ? "a copy" : "copies"}` : "";
+    const lines = [
+        `Meeting records in Docs, not in Notes (${meeting.count}${copies}). Read one with \`${readVerb} <ref>\`:`,
+    ];
+    for (const item of meeting.items) {
+        const size = `${Math.max(1, Math.round(item.bodyChars / 1000))} KB${item.parts.length > 0 ? ` in ${item.parts.length + 1} parts` : ""}`;
+        const mark = item.canonical
+            ? item.canonicalReason && item.canonicalReason !== "only_copy" ? ` · canonical (${item.canonicalReason})` : ""
+            : ` · copy of ${refOf.get(item.duplicateOf ?? "") ?? item.duplicateOf}`;
+        lines.push(`  ${item.meetingDate ?? "undated   "}  ${refOf.get(item.id)}  ${item.title}  ${item.visibility} · ${item.source} · ${size}${mark}`);
+    }
+    if (meeting.truncated)
+        lines.push("  (the read hit its cap, so there may be more)");
+    return lines;
+}

package/dist/notes-tools.js

@@ -18,6 +18,7 @@ import { registerNoteFolderTools } from "./note-folder-tools.js";
  */
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
+import { meetingDocumentLines } from "./notes-meeting-docs.js";
 import { DEFAULT_LIST_LIMIT, doorFailureText, errorResult, registrarFor, textResult, queryString, withSession, } from "./tool-result.js";
 /**
  * The door's own words for "this answer is narrower than the browser's", or
@@ -82,8 +83,16 @@ export function registerNotesTools(server, deps) {
             return `${shelf.heading} (${shelf.notes.length})\n${notes}`;
         })
             .join("\n\n");
+        const inDocs = meetingDocumentLines(body.meetingDocuments, "docs_read").join("\n");
         return textResult(`${body.count ?? 0} note(s)${body.more ? ", and more exist beyond the limit" : ""}.`
-            + `${lines ? `\n\n${lines}` : ""}${narrowingNote(body)}`, { scope: body.scope ?? null, count: body.count ?? 0, more: body.more ?? false, series });
+            + `${lines ? `\n\n${lines}` : ""}${inDocs ? `\n\n${inDocs}` : ""}${narrowingNote(body)}`, {
+            scope: body.scope ?? null,
+            count: body.count ?? 0,
+            more: body.more ?? false,
+            series,
+            meetingDocuments: body.meetingDocuments ?? null,
+            meetingDocumentsSkipped: body.meetingDocumentsSkipped ?? null,
+        });
     }));
     register("notes_show", {
         title: "Read one Tower meeting note",

package/dist/ops-tools.js

@@ -193,11 +193,15 @@ export function registerOpsTools(server, deps) {
         inputSchema: {
             workspace: z.string().min(1).max(100).optional().describe("One workspace key instead of all of them."),
             stale_only: z.boolean().optional().describe("Report only the stale channels, not the whole breakdown."),
+            // BLI-10450: counts alone could not answer "is there a Kaiben channel?".
+            list: z.boolean().optional().describe("Name every channel and its readable state, not only counts."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const params = new URLSearchParams();
         if (args.workspace)
             params.set("workspace", String(args.workspace));
+        if (args.list)
+            params.set("list", "1");
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/ops/slack/coverage${queryString(params)}`);
         if (!response.ok)
             return errorResult(doorFailureText("slack_coverage", response));
@@ -214,7 +218,13 @@ export function registerOpsTools(server, deps) {
                 ? `  no channel is over ${staleAfter}h since its last sync`
                 : `  ${stale} channel(s) over ${staleAfter}h since last sync`;
             const cursor = args.stale_only ? "" : `\n  newest cursor: ${String(workspace["newestCursorIso"] ?? "never")}`;
-            return `${head}\n${staleLine}${cursor}`;
+            const channels = Array.isArray(workspace["channels"])
+                ? workspace["channels"]
+                : [];
+            const channelLines = channels.length > 0
+                ? `\n${channels.map((channel) => `  #${String(channel["name"] ?? "?")}  ${String(channel["meaning"] ?? "?")}`).join("\n")}`
+                : "";
+            return `${head}\n${staleLine}${cursor}${channelLines}`;
         })
             .join("\n\n");
         return textResult(`${workspaces.length} workspace(s), ${staleTotal} stale channel(s).${lines ? `\n\n${lines}` : ""}`
@@ -227,7 +237,8 @@ export function registerOpsTools(server, deps) {
         inputSchema: {
             person: z.string().min(1).max(200).optional().describe("A person — name, email or Slack member id."),
             channel: z.string().min(1).max(200).optional().describe("One channel name."),
-            query: z.string().min(1).max(500).optional().describe("Text to look for."),
+            query: z.string().min(1).max(500).optional().describe("Text to look for, as a substring."),
+            word: z.boolean().optional().describe("Match query as whole words, so \"excel\" stops matching \"Excellent\"."),
             since: z.string().min(1).max(30).optional().describe("YYYY-MM-DD or ISO-8601."),
             until: z.string().min(1).max(30).optional().describe("YYYY-MM-DD or ISO-8601."),
             limit: z.number().int().min(1).max(500).optional().describe("At most this many messages, newest first."),
@@ -240,6 +251,9 @@ export function registerOpsTools(server, deps) {
         }
         if (typeof args.limit === "number")
             body["limit"] = args.limit;
+        // BLI-10451: the same `word: true` the CLI's `--word` sends.
+        if (args.query && args.word === true)
+            body["word"] = true;
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/ops/slack/read", body);
         if (!response.ok) {
             // The CLI names the open door beside the closed one on a 403; an
@@ -256,9 +270,14 @@ export function registerOpsTools(server, deps) {
             .map((message) => `#${String(message["channel"] ?? "?")}  ${String(message["author"] ?? "?")}  ${String(message["messageTs"] ?? "?")}`
             + `\n  ${String(message["text"] ?? "")}`)
             .join("\n");
-        // The server's own summary first and verbatim: it is the sentence that
-        // keeps an empty answer from reading as "nobody said anything".
-        const summary = typeof read["summary"] === "string" ? read["summary"] : `${messages.length} message(s).`;
+        // BLI-10450: `summary` is built for the JARVIS chat tool, which needs
+        // ONE self-contained string, so it already embeds a bullet line per
+        // message AND the note (tools-slack-render.ts renderSummary). Only
+        // the header (summary's first line) is printed here — it is the
+        // sentence that keeps an empty answer from reading as "nobody said
+        // anything" — and the messages/note print exactly once, not twice.
+        const rawSummary = typeof read["summary"] === "string" ? read["summary"] : `${messages.length} message(s).`;
+        const summary = rawSummary.split("\n")[0] ?? rawSummary;
         const note = typeof read["note"] === "string" && read["note"] ? `\n\n${read["note"]}` : "";
         return textResult(`${summary}${lines ? `\n\n${lines}` : ""}${note}`, {
             status: read["status"] ?? null,

package/dist/server.js

@@ -10,6 +10,7 @@ import { z } from "zod";
 import { registerBriefTools } from "./brief-tools.js";
 import { registerBriefWriteTools } from "./brief-write-tools.js";
 import { registerDocsMsgTools } from "./docs-msg-tools.js";
+import { registerDocsNotionTools } from "./docs-notion-tools.js";
 import { registerJarvisTools } from "./jarvis-tools.js";
 import { registerCalTools } from "./cal-tools.js";
 import { registerMailTools } from "./mail-tools.js";
@@ -415,6 +416,8 @@ export function createServer(deps) {
     // no `cockpit login` pairing yet still serves the three event tools; only a
     // docs/msg call on that machine fails, by name.
     registerDocsMsgTools(server, { fetchImpl: deps.fetchImpl });
+    // BLI-10430: docs_link, the Notion half of the docs tools, on the same path.
+    registerDocsNotionTools(server, { fetchImpl: deps.fetchImpl });
     // BLI-3716: `work_*` — the issue tracker, on the same device-token path as
     // the docs/msg tools above, for the same reason: a coding session should
     // file and move a Tower issue the way it files and moves a Linear one.

package/dist/tool-catalog.d.ts

@@ -10,7 +10,7 @@
  * from `src/` under Node's type stripping, so it may import nothing.
  */
 /** Tools that change nothing. The smoke calls every one. */
-export declare const READ_TOOLS: readonly ["get_ticket_timeline", "get_active_tickets", "docs_list", "docs_tree", "docs_read", "msg_channels", "msg_read", "msg_thread", "work_list_issues", "work_get_issue", "work_issue_history", "work_list_projects", "careers_list", "careers_show", "careers_resume_url", "careers_takehome_show", "careers_settings_show", "usage_people", "usage_sessions", "mail_accounts", "mail_inbox", "mail_read", "mail_search", "mail_attachment", "cal_today", "cal_week", "cal_next", "cal_find", "cal_calendars", "jarvis_ask", "jarvis_trace", "jarvis_check", "models_list", "models_card", "models_compare", "brief_read", "brief_history", "brief_status", "notes_folders", "notes_list", "notes_show", "notes_shelf", "notes_shelves", "notes_place", "notes_accounts", "ops_status", "slack_coverage", "slack_read", "memory_profile", "memory_consolidation", "settings_show", "settings_list", "model_show", "team_members", "team_device_list", "scout_board", "workbook_read", "tower_search"];
+export declare const READ_TOOLS: readonly ["get_ticket_timeline", "get_active_tickets", "docs_list", "docs_tree", "docs_read", "docs_sync_status", "msg_channels", "msg_read", "msg_thread", "work_list_issues", "work_get_issue", "work_issue_history", "work_list_projects", "careers_list", "careers_show", "careers_resume_url", "careers_takehome_show", "careers_settings_show", "usage_people", "usage_sessions", "mail_accounts", "mail_inbox", "mail_read", "mail_search", "mail_attachment", "cal_today", "cal_week", "cal_next", "cal_find", "cal_calendars", "jarvis_ask", "jarvis_trace", "jarvis_check", "models_list", "models_card", "models_compare", "brief_read", "brief_history", "brief_status", "notes_folders", "notes_list", "notes_show", "notes_shelf", "notes_shelves", "notes_place", "notes_accounts", "ops_status", "slack_coverage", "slack_read", "memory_profile", "memory_consolidation", "settings_show", "settings_list", "model_show", "team_members", "team_device_list", "scout_board", "workbook_read", "tower_search"];
 /**
  * Tools that write, but answer a dry run that writes nothing. The smoke calls
  * each one ONLY with its dry-run flag set (`scripts/smoke.ts` says which).
@@ -21,7 +21,7 @@ export declare const DRY_RUN_TOOLS: readonly ["ops_recompile", "memory_requeue"]
  * candidates, share calendars. Never called by the smoke; covered by the unit
  * suites (`write-tools.test.ts` and each family's own).
  */
-export declare const WRITE_TOOLS: readonly ["emit_event", "docs_create", "docs_update", "msg_create_channel", "msg_dm", "msg_send", "work_create_issue", "work_update_issue", "work_move_issue", "work_comment_issue", "careers_rescreen", "careers_send_takehome", "careers_invite", "careers_grade", "careers_decide", "careers_takehome_set", "careers_settings_set", "mail_send", "mail_sync", "mail_detach", "cal_create", "cal_share", "cal_sync", "cal_detach", "jarvis_dispatch", "notes_mkdir", "notes_rmdir", "notes_rename", "notes_upload", "notes_paste", "notes_share", "notes_unshare", "notes_move", "notes_sync", "notes_detach", "memory_experience", "scout_start", "scout_dismiss", "scout_undo", "brief_rewrite", "brief_correct", "brief_done", "brief_undone", "settings_set", "settings_delete", "model_set", "team_invite", "team_role", "team_device_revoke"];
+export declare const WRITE_TOOLS: readonly ["emit_event", "docs_create", "docs_update", "docs_link", "msg_create_channel", "msg_dm", "msg_send", "work_create_issue", "work_update_issue", "work_move_issue", "work_comment_issue", "careers_rescreen", "careers_send_takehome", "careers_invite", "careers_grade", "careers_decide", "careers_takehome_set", "careers_settings_set", "mail_send", "mail_sync", "mail_detach", "cal_create", "cal_share", "cal_sync", "cal_detach", "jarvis_dispatch", "notes_mkdir", "notes_rmdir", "notes_rename", "notes_upload", "notes_paste", "notes_share", "notes_unshare", "notes_move", "notes_sync", "notes_detach", "memory_experience", "scout_start", "scout_dismiss", "scout_undo", "brief_rewrite", "brief_correct", "brief_done", "brief_undone", "settings_set", "settings_delete", "model_set", "team_invite", "team_role", "team_device_revoke"];
 /** Reads that spend a model turn. The smoke's `--no-model` leaves these out. */
 export declare const MODEL_SPENDING_TOOLS: readonly ["jarvis_ask", "jarvis_check"];
 /**

package/dist/tool-catalog.js

@@ -16,6 +16,7 @@ export const READ_TOOLS = [
     "docs_list",
     "docs_tree",
     "docs_read",
+    "docs_sync_status",
     "msg_channels",
     "msg_read",
     "msg_thread",
@@ -84,6 +85,7 @@ export const WRITE_TOOLS = [
     "emit_event",
     "docs_create",
     "docs_update",
+    "docs_link",
     "msg_create_channel",
     "msg_dm",
     "msg_send",

package/dist/verb-census.js

@@ -234,6 +234,8 @@ export const MCP_TWINS = {
     "docs read": { tool: "docs_read", door: "GET /api/docs/documents/[id]" },
     "docs create": { tool: "docs_create", door: "POST /api/docs/documents" },
     "docs update": { tool: "docs_update", door: "PATCH /api/docs/documents/[id]" },
+    "docs link": { tool: "docs_link", door: "PUT /api/docs/documents/[id]/notion-link" },
+    "docs sync-status": { tool: "docs_sync_status", door: "GET /api/docs/notion-sync" },
     "msg channels": { tool: "msg_channels", door: "GET /api/msg/channels" },
     "msg create": { tool: "msg_create_channel", door: "POST /api/msg/channels" },
     "msg dm": { tool: "msg_dm", door: "POST /api/msg/channels (dm)" },

package/dist/work-directory.d.ts

@@ -0,0 +1,15 @@
+import type { DoorSession, ToolDeps } from "./tool-result.js";
+export interface AssigneeIdentity {
+    name: string;
+    email: string | null;
+}
+export declare function resolveAssigneeDirectory(deps: ToolDeps, session: DoorSession, assigneeIds: Array<string | null | undefined>): Promise<Map<string, AssigneeIdentity>>;
+/** `assignee_name`/`assignee_email` alongside the bare id, for structuredContent. */
+export declare function withAssigneeIdentity<T extends {
+    assignee_id?: string | null;
+}>(row: T, directory: Map<string, AssigneeIdentity>): T & {
+    assignee_name: string | null;
+    assignee_email: string | null;
+};
+/** The text-line assignee phrase: a name (and email) when resolved, the bare id otherwise. */
+export declare function assigneeLabel(assigneeId: string | null | undefined, directory: Map<string, AssigneeIdentity>): string;

package/dist/work-directory.js

@@ -0,0 +1,39 @@
+/**
+ * BLI-10450: `work_list_issues`/`work_get_issue` carried only `assignee_id`
+ * (a uuid) — answering "who owns what" needed a second `work_list_projects`-
+ * shaped call to `/api/team/members` and a join done by hand. One call per
+ * tool invocation (never per row), the same door `cockpit team members`
+ * calls, mirroring `commands/issue-directory.ts` on the CLI.
+ */
+import { callAgentDoor } from "./agent-door.js";
+export async function resolveAssigneeDirectory(deps, session, assigneeIds) {
+    const wanted = new Set(assigneeIds.filter((id) => Boolean(id)));
+    const directory = new Map();
+    if (wanted.size === 0)
+        return directory;
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/team/members");
+    if (!response.ok)
+        return directory;
+    const people = (Array.isArray(response.body.people) ? response.body.people : []);
+    for (const person of people) {
+        const userId = person.account?.userId;
+        if (!userId || !wanted.has(userId))
+            continue;
+        directory.set(userId, { name: person.name ?? userId, email: person.email ?? null });
+    }
+    return directory;
+}
+/** `assignee_name`/`assignee_email` alongside the bare id, for structuredContent. */
+export function withAssigneeIdentity(row, directory) {
+    const identity = row.assignee_id ? directory.get(row.assignee_id) : undefined;
+    return { ...row, assignee_name: identity?.name ?? null, assignee_email: identity?.email ?? null };
+}
+/** The text-line assignee phrase: a name (and email) when resolved, the bare id otherwise. */
+export function assigneeLabel(assigneeId, directory) {
+    if (!assigneeId)
+        return "none";
+    const identity = directory.get(assigneeId);
+    if (!identity)
+        return assigneeId;
+    return identity.email ? `${identity.name} <${identity.email}>` : identity.name;
+}

package/dist/work-tools.js

@@ -17,6 +17,7 @@
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
 import { DEFAULT_LIST_LIMIT, doorFailureText, errorResult, moreNote, registrarFor, textResult, withSession, } from "./tool-result.js";
+import { assigneeLabel, resolveAssigneeDirectory, withAssigneeIdentity } from "./work-directory.js";
 /** The closed state vocabulary, verbatim from `lib/work/api-doors.ts` `WORK_ISSUE_STATES`. */
 export const WORK_ISSUE_STATES = [
     "backlog",
@@ -28,12 +29,6 @@ export const WORK_ISSUE_STATES = [
 ];
 /** `/api/work/issues`' own ceiling, and the most a caller may ask for here. */
 const ISSUE_LIST_MAX = 1000;
-/**
- * The fields `work_list_issues` promises. The door's row carries the whole
- * description and a dozen bookkeeping columns; with no limit that was 1,000
- * issues and 4.2 MB, 3.3 MB of it descriptions the tool said it never
- * returned (BLI-10432). work_get_issue reads one issue in full.
- */
 function issueListRow(row) {
     return {
         id: row.id,
@@ -47,6 +42,59 @@ function issueListRow(row) {
         updated_at: row.updated_at ?? null,
     };
 }
+function listCompleteness(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    const status = record["status"];
+    if (status !== "complete" && status !== "partial" && status !== "unknown")
+        return null;
+    return { status, total: typeof record["total"] === "number" ? record["total"] : null };
+}
+function outsideProject(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    if (!Array.isArray(record["issues"]))
+        return null;
+    return { status: String(record["status"] ?? "complete"), issues: record["issues"] };
+}
+/** BLI-10447: sub-issues of the listed issues that live in no project or another one. */
+function outsideNote(outside) {
+    if (!outside)
+        return "";
+    const named = outside.issues.map((issue) => `${issue.identifier} (under ${issue.parent_identifier ?? "?"}, ${issue.project_id ? `project ${issue.project_id}` : "no project"})`);
+    const found = named.length > 0 ? ` ${named.length} sub-issue(s) of these sit outside the project: ${named.join(", ")}.` : "";
+    const gap = outside.status === "failed" ? " The outside-project check failed (read_failed)."
+        : outside.status === "capped" ? " The outside-project check was capped; more may exist." : "";
+    return found + gap;
+}
+/** One issue plus its comments — a comment read that fails does not lose the issue already in hand. */
+async function fetchOneIssue(deps, session, ref) {
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/issues/${encodeURIComponent(ref)}`);
+    if (!response.ok)
+        return { ref, ok: false, text: doorFailureText("work_get_issue", response) };
+    const issue = response.body.issue;
+    const commentsResponse = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/issues/${encodeURIComponent(issue?.id ?? ref)}/comments`);
+    const comments = commentsResponse.ok
+        ? (commentsResponse.body.comments ?? [])
+        : [];
+    return {
+        ref,
+        ok: true,
+        issue,
+        comments,
+        ...(commentsResponse.ok ? {} : { commentsUnread: true }),
+    };
+}
+function renderOneIssue(result, directory) {
+    const { issue, comments } = result;
+    const commentText = comments.map((comment) => `[${comment.created_at ?? ""}] ${comment.body_markdown ?? ""}`).join("\n\n");
+    return `${issue?.identifier ?? result.ref} ${issue?.title ?? ""} (${issue?.state ?? "?"})  ·  assignee ${assigneeLabel(issue?.assignee_id, directory)}`
+        + `\n\n${issue?.description ?? "(no description)"}`
+        + (commentText ? `\n\n--- comments ---\n${commentText}` : "")
+        + (result.commentsUnread ? "\n\n(comments could not be read on this call)" : "");
+}
 /**
  * A row the Linear import could not give state names to says which it is.
  * Printing "(none) -> (none)" is honest and useless; naming the gap keeps
@@ -111,33 +159,72 @@ export function registerWorkTools(server, deps) {
         if (!response.ok)
             return errorResult(doorFailureText("work_list_issues", response));
         const all = (Array.isArray(response.body.issues) ? response.body.issues : []);
-        const more = args.limit === undefined && all.length > DEFAULT_LIST_LIMIT;
-        const issues = more ? all.slice(0, DEFAULT_LIST_LIMIT) : all;
+        // BLI-10447: the door says whether a full read was every match; a named
+        // limit that filled up used to answer "more: false" regardless.
+        const completeness = listCompleteness(response.body.completeness);
+        const more = args.limit === undefined
+            ? all.length > DEFAULT_LIST_LIMIT
+            : completeness?.status === "partial" || completeness?.status === "unknown";
+        const issues = args.limit === undefined && more ? all.slice(0, DEFAULT_LIST_LIMIT) : all;
+        const outside = outsideProject(response.body.outside_project);
+        // BLI-10450: one directory call for the whole page, never one per row.
+        const directory = await resolveAssigneeDirectory(deps, session, issues.map((issue) => issue.assignee_id));
         const lines = issues
             .map((issue) => `${issue.identifier}  ${issue.state}  ${issue.title}`
-            + `  [p${issue.priority ?? 0}, assignee ${issue.assignee_id ?? "none"}, project ${issue.project_id ?? "none"}]`)
+            + `  [p${issue.priority ?? 0}, assignee ${assigneeLabel(issue.assignee_id, directory)}, project ${issue.project_id ?? "none"}]`)
             .join("\n");
-        return textResult(`${issues.length} issue(s).${moreNote(more, ISSUE_LIST_MAX)}${lines ? `\n${lines}` : ""}`, { issues: issues.map(issueListRow), more });
+        const totalNote = completeness?.total != null && completeness.total > issues.length ? ` ${completeness.total} match in all.` : "";
+        return textResult(`${issues.length} issue(s).${totalNote}${moreNote(more, ISSUE_LIST_MAX)}${outsideNote(outside)}${lines ? `\n${lines}` : ""}`, {
+            issues: issues.map((issue) => withAssigneeIdentity(issueListRow(issue), directory)),
+            more,
+            ...(completeness ? { total: completeness.total } : {}),
+            ...(outside ? { outside_project: outside } : {}),
+        });
     }));
     register("work_get_issue", {
         title: "Read a Tower issue",
-        description: "One issue's title, state, priority, assignee, description and every comment on it.",
-        inputSchema: { id: ISSUE_REF },
+        description: "One issue's title, state, priority, assignee (name and email, not just its id), description and every "
+            + "comment on it. `ids` reads several in one call — still one request per issue plus its comments, "
+            + "no bulk door exists yet. A single id answers `{ issue, comments }`; several answer "
+            + "`{ issues: [{ ref, ok, issue, comments } | { ref, ok: false, error, detail }] }` so one bad id never "
+            + "loses the rest.",
+        inputSchema: {
+            id: ISSUE_REF.optional().describe("A single issue. Omit when passing ids."),
+            ids: z.array(ISSUE_REF).min(1).max(50).optional().describe("Several issues in one call. Omit when passing id."),
+        },
     }, async (args) => withSession(deps, async (session) => {
-        const ref = String(args.id ?? "");
-        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/issues/${encodeURIComponent(ref)}`);
-        if (!response.ok)
-            return errorResult(doorFailureText("work_get_issue", response));
-        const issue = response.body.issue;
-        // A comment read that fails does not lose the issue already in hand.
-        const commentsResponse = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/issues/${encodeURIComponent(issue?.id ?? ref)}/comments`);
-        const comments = commentsResponse.ok ? (commentsResponse.body.comments ?? []) : [];
-        const commentText = comments
-            .map((comment) => `[${comment.created_at ?? ""}] ${comment.body_markdown ?? ""}`)
-            .join("\n\n");
-        return textResult(`${issue?.identifier ?? ref} ${issue?.title ?? ""} (${issue?.state ?? "?"})\n\n${issue?.description ?? "(no description)"}`
-            + (commentText ? `\n\n--- comments ---\n${commentText}` : "")
-            + (commentsResponse.ok ? "" : "\n\n(comments could not be read on this call)"), { issue, comments, ...(commentsResponse.ok ? {} : { comments_unread: true }) });
+        const refs = Array.isArray(args.ids) && args.ids.length > 0
+            ? args.ids.map(String)
+            : [String(args.id ?? "")];
+        if (refs.length === 1 && refs[0] === "")
+            return errorResult("work_get_issue needs id or ids.");
+        const results = await Promise.all(refs.map((ref) => fetchOneIssue(deps, session, ref)));
+        const directory = await resolveAssigneeDirectory(deps, session, results.filter((result) => result.ok).map((result) => result.issue?.assignee_id));
+        if (refs.length === 1) {
+            const [result] = results;
+            if (!result?.ok)
+                return errorResult(result?.text ?? "work_get_issue could not read that issue.");
+            return textResult(renderOneIssue(result, directory), {
+                issue: withAssigneeIdentity(result.issue ?? {}, directory),
+                comments: result.comments,
+                ...(result.commentsUnread ? { comments_unread: true } : {}),
+            });
+        }
+        const failed = results.filter((result) => !result.ok);
+        const lines = results
+            .map((result) => (result.ok ? renderOneIssue(result, directory) : `${result.ref}: ${result.text}`))
+            .join("\n\n---\n\n");
+        return textResult(`${results.length - failed.length}/${results.length} issue(s) read.\n\n${lines}`, {
+            issues: results.map((result) => result.ok
+                ? {
+                    ref: result.ref,
+                    ok: true,
+                    issue: withAssigneeIdentity(result.issue ?? {}, directory),
+                    comments: result.comments,
+                    ...(result.commentsUnread ? { comments_unread: true } : {}),
+                }
+                : { ref: result.ref, ok: false, error: result.text }),
+        });
     }));
     register("work_create_issue", {
         title: "File a Tower issue",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.61",
+  "version": "0.1.65",
   "private": false,
   "description": "bli-tower: an MCP server over BLI Cockpit's agent doors: JARVIS (jarvis_*), documents (docs_*), channels (msg_*), issues (work_*), the daily page (brief_*), meeting notes (notes_*), the ops board (ops_status/slack_*), settings/team/model, Scout and the workbook, plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
   "type": "module",