@orboto/mcp 0.178.0

package/dist/session-nudge.js

@@ -0,0 +1,81 @@
+/** The tool whose whole job is to load the rules - never nudge on it. */
+export const SESSION_START_TOOL = 'orboto_session_start';
+/**
+ * The one-time reminder. English, ASCII-only, no em/en-dashes so it
+ * survives every client. Prepended as a leading text block only -
+ * structuredContent and the tool's own content are left untouched.
+ */
+export const SESSION_START_NUDGE = 'NOTE: you have not loaded this workspace\'s binding operating rules yet. ' +
+    'Call `orboto_session_start` now - it returns the rules you must follow ' +
+    'plus your in-progress work.';
+/** Fresh per-session (HTTP) / per-process (stdio) nudge state. `gateEnabled`
+ *  comes from the workspace config fetched at server build (default off). */
+export function createNudgeState(gateEnabled = false) {
+    return { firstToolCallSeen: false, sessionStartRan: false, gateEnabled };
+}
+/**
+ * Advance the state for one dispatch and report whether this dispatch
+ * should carry the nudge. True ONLY for the first tool call of the
+ * session when that call is not `orboto_session_start`. Every later call
+ * - and the session_start-first case - returns false. Idempotent after
+ * the first call because the flag is already set.
+ */
+export function shouldNudge(state, toolName) {
+    if (state.firstToolCallSeen)
+        return false;
+    state.firstToolCallSeen = true;
+    return toolName !== SESSION_START_TOOL;
+}
+/**
+ * Return a copy of the result with the nudge prepended as a leading text
+ * block. Does not mutate the input, does not touch `structuredContent`,
+ * and preserves `isError` and every existing content block.
+ */
+export function prependNudge(result) {
+    return {
+        ...result,
+        content: [
+            { type: 'text', text: SESSION_START_NUDGE },
+            ...(result.content ?? []),
+        ],
+    };
+}
+/**
+ * ORB-1471 - the HARD session-start gate message. Unlike the soft nudge
+ * (which rides along on the tool's real result), the gate REFUSES the tool
+ * call outright and returns this instead. English, ASCII-only.
+ */
+export const SESSION_START_GATE_MESSAGE = 'This workspace requires you to load its binding operating rules before any ' +
+    'other action. Call `orboto_session_start` now - it returns the rules you ' +
+    'must follow plus your in-progress work - then retry this call.';
+/**
+ * ORB-1471 - advance the gate state for one dispatch and report whether this
+ * dispatch must be REFUSED (returned an instructive error without running the
+ * handler).
+ *
+ * Semantics when the gate is enabled: every tool call other than
+ * `orboto_session_start` is refused until `orboto_session_start` has run once
+ * this session. Calling `orboto_session_start` marks the session unlocked
+ * (and is itself never gated). When the gate is disabled, nothing is ever
+ * refused (returns false) - default behaviour is unchanged.
+ *
+ * Idempotent bookkeeping: running `orboto_session_start` flips
+ * `sessionStartRan` so all later calls pass.
+ */
+export function shouldGate(state, toolName) {
+    if (toolName === SESSION_START_TOOL) {
+        // The rule-loading tool always runs, and running it unlocks the session.
+        state.sessionStartRan = true;
+        return false;
+    }
+    if (!state.gateEnabled)
+        return false;
+    return !state.sessionStartRan;
+}
+/** ORB-1471 - the instructive refusal result the gate returns. */
+export function gateResult() {
+    return {
+        isError: true,
+        content: [{ type: 'text', text: SESSION_START_GATE_MESSAGE }],
+    };
+}

package/dist/session-nudge.test.js

@@ -0,0 +1,100 @@
+/**
+ * ORB-1331 - session-start nudge state machine + prepend helper.
+ *
+ * Unit-level proof of the semantics the transport tests then exercise
+ * end-to-end: fire once, only on the first tool call, never when that
+ * call is orboto_session_start, and never mutate structuredContent.
+ */
+import { describe, it, expect } from 'vitest';
+import { SESSION_START_TOOL, SESSION_START_NUDGE, SESSION_START_GATE_MESSAGE, createNudgeState, shouldNudge, shouldGate, gateResult, prependNudge, } from './session-nudge.js';
+describe('shouldNudge (ORB-1331)', () => {
+    it('nudges on the first tool call when it is not session_start, then never again', () => {
+        const state = createNudgeState();
+        expect(shouldNudge(state, 'orboto_list_projects')).toBe(true);
+        // Every subsequent call is clean regardless of tool.
+        expect(shouldNudge(state, 'orboto_get_ticket')).toBe(false);
+        expect(shouldNudge(state, 'orboto_list_projects')).toBe(false);
+        expect(shouldNudge(state, SESSION_START_TOOL)).toBe(false);
+    });
+    it('never nudges when the first call IS session_start', () => {
+        const state = createNudgeState();
+        expect(shouldNudge(state, SESSION_START_TOOL)).toBe(false);
+        // and does not resurface on later calls either.
+        expect(shouldNudge(state, 'orboto_list_projects')).toBe(false);
+    });
+    it('isolates state between sessions/processes (each fresh state nudges once)', () => {
+        const a = createNudgeState();
+        const b = createNudgeState();
+        expect(shouldNudge(a, 'orboto_list_projects')).toBe(true);
+        // b is untouched by a - its own first call still nudges.
+        expect(shouldNudge(b, 'orboto_list_projects')).toBe(true);
+        expect(shouldNudge(a, 'orboto_list_projects')).toBe(false);
+        expect(shouldNudge(b, 'orboto_list_projects')).toBe(false);
+    });
+});
+describe('shouldGate (ORB-1471)', () => {
+    it('never gates when the gate is disabled (default), whatever the tool', () => {
+        const state = createNudgeState(); // gateEnabled defaults false
+        expect(shouldGate(state, 'orboto_list_projects')).toBe(false);
+        expect(shouldGate(state, 'orboto_create_ticket')).toBe(false);
+        expect(shouldGate(state, SESSION_START_TOOL)).toBe(false);
+    });
+    it('when enabled, refuses every non-session-start tool until session_start runs', () => {
+        const state = createNudgeState(true);
+        // Pre session_start: every other tool is gated.
+        expect(shouldGate(state, 'orboto_list_projects')).toBe(true);
+        expect(shouldGate(state, 'orboto_create_ticket')).toBe(true);
+        // session_start itself is never gated AND unlocks the session.
+        expect(shouldGate(state, SESSION_START_TOOL)).toBe(false);
+        // Post session_start: everything passes.
+        expect(shouldGate(state, 'orboto_list_projects')).toBe(false);
+        expect(shouldGate(state, 'orboto_create_ticket')).toBe(false);
+    });
+    it('session_start as the very first call unlocks immediately (one-call cost avoided)', () => {
+        const state = createNudgeState(true);
+        expect(shouldGate(state, SESSION_START_TOOL)).toBe(false);
+        expect(shouldGate(state, 'orboto_get_ticket')).toBe(false);
+    });
+    it('gateResult is an instructive isError result pointing at session_start', () => {
+        const r = gateResult();
+        expect(r.isError).toBe(true);
+        expect(r.content[0]).toEqual({ type: 'text', text: SESSION_START_GATE_MESSAGE });
+    });
+    it('gate message is English, ASCII-only, and free of em/en-dashes', () => {
+        // eslint-disable-next-line no-control-regex
+        expect(/^[\x00-\x7F]*$/.test(SESSION_START_GATE_MESSAGE)).toBe(true);
+        expect(SESSION_START_GATE_MESSAGE).not.toMatch(/[\u2013\u2014]/);
+        expect(SESSION_START_GATE_MESSAGE).toContain('orboto_session_start');
+    });
+});
+describe('SESSION_START_NUDGE text (ORB-1331)', () => {
+    it('is English, ASCII-only, and free of em/en-dashes', () => {
+        // eslint-disable-next-line no-control-regex
+        expect(/^[\x00-\x7F]*$/.test(SESSION_START_NUDGE)).toBe(true);
+        expect(SESSION_START_NUDGE).not.toMatch(/[\u2013\u2014]/); // en/em dash
+        expect(SESSION_START_NUDGE).toContain('orboto_session_start');
+    });
+});
+describe('prependNudge (ORB-1331)', () => {
+    it('prepends the nudge as a leading text block without touching structuredContent or isError', () => {
+        const original = {
+            content: [{ type: 'text', text: 'tool output' }],
+            structuredContent: { projects: [], total: 0 },
+        };
+        const out = prependNudge(original);
+        expect(out.content).toHaveLength(2);
+        expect(out.content[0]).toEqual({ type: 'text', text: SESSION_START_NUDGE });
+        expect(out.content[1]).toEqual({ type: 'text', text: 'tool output' });
+        // structuredContent consumers are unaffected - same reference-equal payload.
+        expect(out.structuredContent).toBe(original.structuredContent);
+        // input is not mutated.
+        expect(original.content).toHaveLength(1);
+    });
+    it('preserves isError on an error result', () => {
+        const errResult = { isError: true, content: [{ type: 'text', text: 'boom' }] };
+        const out = prependNudge(errResult);
+        expect(out.isError).toBe(true);
+        expect(out.content[0]).toEqual({ type: 'text', text: SESSION_START_NUDGE });
+        expect(out.content[1]).toEqual({ type: 'text', text: 'boom' });
+    });
+});

package/dist/session-nudge.transport.test.js

@@ -0,0 +1,100 @@
+/**
+ * ORB-1331 - end-to-end transport proof of the session-start nudge.
+ *
+ * Drives the REAL server (buildOrbotoMcpServer → registerWithMetrics →
+ * withMetrics → prependNudge) over an in-memory MCP transport with a
+ * genuine MCP Client, so the whole JSON-RPC dispatch path is exercised,
+ * not just the helper in isolation.
+ *
+ * Transport semantics both reduce to the lifetime of the per-build nudge
+ * state:
+ *   - HTTP: the transport calls buildOrbotoMcpServer once PER SESSION, so
+ *     each session is an independent server instance with its own state.
+ *   - stdio: buildOrbotoMcpServer is called once PER PROCESS, so a single
+ *     server instance's state is process-local.
+ * We model a "session"/"process" as one built server + one connected
+ * client, and assert the nudge fires exactly once on the first non-
+ * session_start call and never when the first call is session_start.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { buildOrbotoMcpServer } from './server.js';
+import { SESSION_START_NUDGE } from './session-nudge.js';
+// Every API call the tools make resolves to a benign empty payload so
+// the handlers succeed without a live backend. list_projects → [] →
+// "no projects" text + valid structuredContent; session_start's sub-
+// calls are all .catch-guarded so [] is harmless.
+function mockApi() {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        headers: new Headers({ 'content-type': 'application/json' }),
+        json: async () => [],
+        text: async () => '[]',
+    }));
+}
+beforeEach(() => { vi.restoreAllMocks(); mockApi(); });
+afterEach(() => { vi.restoreAllMocks(); });
+/** Build a fresh server ("session"/"process") + a connected MCP client. */
+async function connectSession() {
+    const server = await buildOrbotoMcpServer({ baseUrl: 'http://api.invalid', apiKey: 'orb_test' });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'test-client', version: '0.0.0' });
+    await Promise.all([
+        server.connect(serverTransport),
+        client.connect(clientTransport),
+    ]);
+    return client;
+}
+/** First text block of a tool result. */
+function firstText(res) {
+    const content = res.content;
+    return content[0]?.text ?? '';
+}
+describe('ORB-1331 - HTTP transport (per-session nudge)', () => {
+    it('prepends the nudge exactly once when the first call is orboto_list_projects; the second call is clean', async () => {
+        const client = await connectSession();
+        const first = await client.callTool({ name: 'orboto_list_projects', arguments: {} });
+        expect(firstText(first)).toContain(SESSION_START_NUDGE);
+        // structuredContent must be untouched by the text-block prepend.
+        expect(first.structuredContent).toMatchObject({ projects: [], total: 0 });
+        const second = await client.callTool({ name: 'orboto_list_projects', arguments: {} });
+        expect(firstText(second)).not.toContain(SESSION_START_NUDGE);
+    });
+    it('never nudges a session whose first call is orboto_session_start', async () => {
+        const client = await connectSession();
+        const first = await client.callTool({ name: 'orboto_session_start', arguments: {} });
+        expect(firstText(first)).not.toContain(SESSION_START_NUDGE);
+        const second = await client.callTool({ name: 'orboto_list_projects', arguments: {} });
+        expect(firstText(second)).not.toContain(SESSION_START_NUDGE);
+    });
+    it('isolates the nudge per session - a second, independent session nudges on its own first call', async () => {
+        const a = await connectSession();
+        const b = await connectSession();
+        const aFirst = await a.callTool({ name: 'orboto_list_projects', arguments: {} });
+        expect(firstText(aFirst)).toContain(SESSION_START_NUDGE);
+        // b is a distinct built server → distinct state → still nudges.
+        const bFirst = await b.callTool({ name: 'orboto_list_projects', arguments: {} });
+        expect(firstText(bFirst)).toContain(SESSION_START_NUDGE);
+    });
+});
+describe('ORB-1331 - stdio transport (process-local nudge)', () => {
+    it('fires once for the process: first non-session_start call nudged, all later calls clean', async () => {
+        // stdio builds one server per process → one nudge state reused for
+        // every call on this single connected client.
+        const client = await connectSession();
+        const first = await client.callTool({ name: 'orboto_list_projects', arguments: {} });
+        expect(firstText(first)).toContain(SESSION_START_NUDGE);
+        const second = await client.callTool({ name: 'orboto_session_start', arguments: {} });
+        expect(firstText(second)).not.toContain(SESSION_START_NUDGE);
+        const third = await client.callTool({ name: 'orboto_list_projects', arguments: {} });
+        expect(firstText(third)).not.toContain(SESSION_START_NUDGE);
+    });
+    it('a process whose first call is session_start never sees the nudge', async () => {
+        const client = await connectSession();
+        const first = await client.callTool({ name: 'orboto_session_start', arguments: {} });
+        expect(firstText(first)).not.toContain(SESSION_START_NUDGE);
+    });
+});

package/dist/tool-annotations.test.js

@@ -0,0 +1,97 @@
+/**
+ * ORB-1669 - safety-annotation ratchet for the MCP tool surface.
+ *
+ * MCP clients use `annotations` to decide whether a tool call needs a
+ * confirmation step. The hints DEFAULT badly for us: per the MCP spec a
+ * tool with no annotations is read-only=false / destructive=true /
+ * idempotent=false - so an unannotated read looks dangerous, and (worse,
+ * because it is the silent direction) a write annotated only with
+ * `{ readOnlyHint: false }` still reports destructive=true. Before this
+ * ticket 90 of 168 tools carried nothing at all and `orboto_bulk_close`
+ * was indistinguishable from `orboto_get_ticket`.
+ *
+ * This test enumerates the tools exactly as a client sees them  -
+ * `tools/list` over an in-memory transport, not a source scan - and
+ * fails the build on a new tool that skips its annotations. There is no
+ * allowlist on purpose: unlike the dark-mode / i18n ratchets there is no
+ * legitimate "sanctioned exception", every tool can answer these
+ * questions.
+ *
+ * THE CONVENTION (apply it when you add a tool):
+ *
+ *   readOnlyHint: true    - performs no writes at all.
+ *   destructiveHint: true - the call can DELETE or REMOVE a row, DISCARD
+ *                           content, take over state owned by someone
+ *                           else, or mutate many tickets at once. If ANY
+ *                           argument combination can do that, the tool is
+ *                           destructive - the hint is per-tool and cannot
+ *                           be conditioned on a flag (this is why
+ *                           `orboto_claim` is destructive: `sole=true`
+ *                           strips every other assignee).
+ *   destructiveHint: false- purely additive, or a reversible single-entity
+ *                           field/state update.
+ *   idempotentHint: true  - repeating the call with identical arguments
+ *                           has no further effect.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { buildOrbotoMcpServer } from './server.js';
+/** Anthropic's connector review caps the human-readable tool title. It is
+ *  also just good UI hygiene - a title that long is a description. */
+const TITLE_MAX = 64;
+let tools;
+beforeAll(async () => {
+    // Port 1 is never listened on -> the connect-time /agent-instructions
+    // fetch fails immediately and the server falls back to its built-in
+    // rules. No network, no fixture server, no timeout.
+    // ORB-1520 made the CURATED manifest the default; the annotation contract
+    // covers every registered tool, so this ratchet lists the FULL toolset.
+    const server = await buildOrbotoMcpServer({ baseUrl: 'http://127.0.0.1:1', apiKey: 'orb_test', toolset: 'full' });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'annotation-ratchet', version: '0' });
+    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+    tools = (await client.listTools()).tools;
+    await client.close();
+});
+describe('MCP tool safety annotations (ORB-1669)', () => {
+    it('enumerates the full tool surface', () => {
+        // Guards the guard: if the in-memory handshake ever silently returns
+        // nothing, every expectation below would vacuously pass.
+        expect(tools.length).toBeGreaterThan(150);
+    });
+    it('every tool declares annotations with an explicit readOnlyHint', () => {
+        const offenders = tools
+            .filter((t) => typeof t.annotations?.readOnlyHint !== 'boolean')
+            .map((t) => t.name);
+        expect(offenders, `Tools missing an explicit \`readOnlyHint\`: ${offenders.join(', ')}.\n` +
+            'Add an `annotations` block to the tool config in apps/mcp/src/tools/ - see the convention at the top of this file.').toEqual([]);
+    });
+    it('every write tool declares an explicit destructiveHint', () => {
+        // The load-bearing one. `{ readOnlyHint: false }` alone leaves
+        // destructiveHint defaulting to TRUE, so a harmless write advertises
+        // itself as destructive and the signal stops meaning anything.
+        const offenders = tools
+            .filter((t) => t.annotations?.readOnlyHint === false)
+            .filter((t) => typeof t.annotations?.destructiveHint !== 'boolean')
+            .map((t) => t.name);
+        expect(offenders, `Write tools missing an explicit \`destructiveHint\`: ${offenders.join(', ')}.\n` +
+            'A write with no destructiveHint is reported to clients as destructive (spec default). Set it deliberately, true or false.').toEqual([]);
+    });
+    it('read-only tools never claim to be destructive', () => {
+        const offenders = tools
+            .filter((t) => t.annotations?.readOnlyHint === true && t.annotations?.destructiveHint === true)
+            .map((t) => t.name);
+        expect(offenders, `Contradictory annotations on: ${offenders.join(', ')}`).toEqual([]);
+    });
+    it(`every tool has a human-readable title of at most ${TITLE_MAX} characters`, () => {
+        const missing = tools.filter((t) => !(t.title ?? t.annotations?.title)).map((t) => t.name);
+        expect(missing, `Tools with no title: ${missing.join(', ')}`).toEqual([]);
+        const tooLong = tools
+            .map((t) => ({ name: t.name, title: (t.title ?? t.annotations?.title) }))
+            .filter((t) => t.title.length > TITLE_MAX)
+            .map((t) => `${t.name} (${t.title.length}: "${t.title}")`);
+        expect(tooLong, `Titles over ${TITLE_MAX} characters: ${tooLong.join('; ')}.\n` +
+            'Shorten the `title` - the long form belongs in `description`.').toEqual([]);
+    });
+});

package/dist/tool-docs.js

@@ -0,0 +1,64 @@
+/**
+ * ORB-1741 - the manifest diet (epic ORB-1691).
+ *
+ * Every tool description in the manifest is STANDING context cost: an
+ * eager-loading client pays it on connect, every session. The curated
+ * toolset (ORB-1520) cut the tool COUNT; this module cuts the per-tool
+ * TEXT. At registration time (with-metrics.ts) the full description is
+ * captured here and the wire manifest carries only a one-sentence
+ * summary; `orboto_help { tool }` serves the full guidance lazily - the
+ * same deferred-docs pattern ToolSearch uses for deferred tools.
+ *
+ * The full texts stay where they always lived - in each tool file's
+ * `description` - so authors keep writing complete guidance and nothing
+ * is lost: the summary is DERIVED (first sentence, or a hand-written
+ * override for the few whose first sentence overruns the cap).
+ */
+/** Soft cap for a wire description; the ratchet in manifest-size.test.ts
+ *  enforces the aggregate outcome. */
+export const SUMMARY_MAX_CHARS = 220;
+/**
+ * Hand-written one-liners for tools whose first sentence exceeds the cap
+ * (measured 2026-08-28: 6 of 172). Keep each under SUMMARY_MAX_CHARS and
+ * name the key inputs.
+ */
+const SUMMARY_OVERRIDES = {
+    orboto_create_full_backup: 'Start a full-workspace backup job (all projects, users, config, attachments); returns the job id to poll via orboto_list_backups.',
+    orboto_get_ticket: 'Fetch one ticket by key (ORB-42) or UUID: full detail incl. description, status, assignees, checklists, dependencies and comments.',
+    orboto_requirements_spec: 'Generate a structured requirements spec for a project or milestone from its tickets (scope, actors, functional + non-functional requirements).',
+    orboto_update_doc_space: 'Update a doc space\'s name, description, icon, project binding or access mode (open/restricted) by space id.',
+    orboto_search_docs: 'Full-text search over doc/wiki pages (query, optional space or project filter); returns matching pages with snippets.',
+    orboto_critical_path: 'Compute the dependency-based critical path for a project or milestone: the blocking chain of tickets that determines the earliest finish.',
+};
+/** Runtime registry: tool name -> full guidance text, captured at
+ *  registration. Module-global on purpose - the HTTP transport builds one
+ *  server per session but the docs are identical, so re-capture is an
+ *  idempotent Map.set. */
+const toolDocs = new Map();
+export function captureToolDoc(toolName, fullDescription) {
+    toolDocs.set(toolName, fullDescription);
+}
+export function getToolDoc(toolName) {
+    return toolDocs.get(toolName);
+}
+export function listToolDocNames() {
+    return [...toolDocs.keys()].sort();
+}
+/**
+ * One-sentence wire summary: the override when one exists, else the
+ * first sentence (sentence-end followed by whitespace/EOL). A first
+ * sentence still over the cap falls back to a word-boundary cut - the
+ * summary must never silently exceed what the ratchet budgets for.
+ */
+export function summarizeToolDescription(toolName, full) {
+    const override = SUMMARY_OVERRIDES[toolName];
+    if (override)
+        return override;
+    const match = full.match(/^[\s\S]*?[.!?](?=\s|$)/);
+    let first = (match ? match[0] : full).trim();
+    if (first.length > SUMMARY_MAX_CHARS) {
+        const cut = first.slice(0, SUMMARY_MAX_CHARS - 3);
+        first = `${cut.slice(0, cut.lastIndexOf(' '))}...`;
+    }
+    return first;
+}

package/dist/tool-docs.test.js

@@ -0,0 +1,90 @@
+/**
+ * ORB-1741 - manifest diet: one-line wire descriptions + lazy full docs.
+ *
+ * Pins (1) the summarizer's three paths (override, first sentence,
+ * word-boundary fallback), (2) that the REAL manifest ships only
+ * summaries while orboto_help returns the full captured guidance for
+ * every registered tool - the "no guidance lost" acceptance criterion,
+ * verified against the live registration path, not fixtures.
+ */
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { buildOrbotoMcpServer } from './server.js';
+import { summarizeToolDescription, captureToolDoc, getToolDoc, SUMMARY_MAX_CHARS, } from './tool-docs.js';
+import { makeHelpHandler } from './tools/help.js';
+beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('offline test'));
+    delete process.env.ORBOTO_MCP_TOOLSET;
+});
+afterEach(() => { vi.restoreAllMocks(); });
+describe('summarizeToolDescription', () => {
+    it('takes the first sentence', () => {
+        expect(summarizeToolDescription('orboto_x', 'Does the thing. And much, much more follows here.'))
+            .toBe('Does the thing.');
+    });
+    it('uses the hand-written override when one exists', () => {
+        const s = summarizeToolDescription('orboto_get_ticket', 'A very long first sentence that would otherwise be cut mid-flow because it enumerates every field the response carries and never stops');
+        expect(s).toContain('Fetch one ticket');
+        expect(s.length).toBeLessThanOrEqual(SUMMARY_MAX_CHARS);
+    });
+    it('falls back to a word-boundary cut when the first sentence overruns the cap', () => {
+        const long = `${'word '.repeat(80)}end.`;
+        const s = summarizeToolDescription('orboto_unknown_tool', long);
+        expect(s.length).toBeLessThanOrEqual(SUMMARY_MAX_CHARS);
+        expect(s.endsWith('...')).toBe(true);
+        expect(s).not.toMatch(/\swor\.\.\.$/); // never cuts inside a word
+    });
+});
+describe('orboto_help handler', () => {
+    it('returns the captured full text, resolves the orboto_ prefix, and lists known tools on a miss', async () => {
+        captureToolDoc('orboto_demo_tool', 'Short summary. Long tail of guidance with warnings and workflows.');
+        const handler = makeHelpHandler();
+        const hit = await handler({ tool: 'orboto_demo_tool' });
+        expect(hit.structuredContent).toMatchObject({
+            tool: 'orboto_demo_tool',
+            guidance: expect.stringContaining('Long tail of guidance'),
+        });
+        const prefixed = await handler({ tool: 'demo_tool' });
+        expect(prefixed.structuredContent).toMatchObject({ tool: 'orboto_demo_tool' });
+        const miss = await handler({ tool: 'orboto_nope' });
+        expect(miss.content[0].text).toContain('No guidance registered');
+        expect(miss.content[0].text).toContain('orboto_demo_tool');
+    });
+});
+describe('live manifest vs help registry (no guidance lost)', () => {
+    it('every tool in the full manifest has a one-line wire description and full docs behind orboto_help', async () => {
+        const server = await buildOrbotoMcpServer({
+            baseUrl: 'https://orboto.example.com', apiKey: 'orb_test', toolset: 'full',
+        });
+        const [ct, st] = InMemoryTransport.createLinkedPair();
+        const client = new Client({ name: 'diet-check', version: '0.0.0' });
+        await Promise.all([server.connect(st), client.connect(ct)]);
+        try {
+            const { tools } = await client.listTools({});
+            expect(tools.length).toBeGreaterThan(150);
+            for (const t of tools) {
+                const wire = t.description ?? '';
+                // Acceptance: no registered wire description exceeds the cap.
+                expect(wire.length, `${t.name} wire description too long`).toBeLessThanOrEqual(SUMMARY_MAX_CHARS);
+                // The full text is behind the registry and STARTS where the
+                // summary came from (override tools aside, whose full text is
+                // still captured verbatim).
+                const full = getToolDoc(t.name);
+                expect(full, `${t.name} missing from the help registry`).toBeTruthy();
+                expect(summarizeToolDescription(t.name, full)).toBe(wire);
+            }
+            // Spot-check the measured worst offender end to end via the tool.
+            const res = await client.callTool({ name: 'orboto_help', arguments: { tool: 'orboto_create_ticket' } });
+            // First block can be the ORB-1331 session-start nudge - join all.
+            const text = res.content.map((c) => c.text ?? '').join('\n');
+            expect(text.length).toBeGreaterThan(1000); // the old 2.9k essay, intact
+            expect(text).toContain('Duplicate-detection safety-net');
+        }
+        finally {
+            await client.close();
+            await server.close();
+        }
+    });
+});