@orboto/mcp 0.178.0

package/dist/tools/cross-project-links.ee.js

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Orboto-Enterprise-1.0
+/**
+ * ORB-632 / ORB-945 - Cross-Project Linking MCP tools.
+ *
+ * - orboto_list_cross_project_links - GET /tickets/:id/cross-project-links
+ * - orboto_add_cross_project_link - POST /tickets/:id/cross-project-links
+ * - orboto_update_cross_project_link - PATCH /tickets/:id/cross-project-links/:linkId
+ * - orboto_remove_cross_project_link - DELETE /tickets/:id/cross-project-links/:linkId
+ *
+ * Business-tier feature (`.ee.*`). The API records the EE soft-warn
+ * event on mutating calls; the tool surface here is identical to
+ * every other MCP tool and reads the existing license-state via the
+ * Authorization-header path.
+ *
+ * Accepts BOTH a UUID and a ticket-key (`OCP-42`, case-insensitive) on
+ * every input - the API resolves either form.
+ */
+import { z } from 'zod';
+const RELATION_TYPES = ['counterpart', 'depends_on', 'blocks', 'related'];
+// ---------------------------------------------------------------------------
+// orboto_list_cross_project_links
+// ---------------------------------------------------------------------------
+export const listCrossProjectLinksToolConfig = {
+    title: 'List cross-project links on a ticket',
+    description: 'Return every cross-project link touching the ticket - both outgoing (this → other) and incoming (other → this). Each row carries the other end\'s project key, ticket key, title, and current status, so the model can see the linked work\'s state without a follow-up tool call. ACL-filtered: rows whose other-end project the caller cannot read are dropped silently.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3).describe('Ticket key (e.g. "ORB-42") or UUID.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListCrossProjectLinksHandler(client) {
+    return async ({ ticketKey }) => {
+        const rows = await client.get(`/tickets/${encodeURIComponent(ticketKey)}/cross-project-links`);
+        if (rows.length === 0) {
+            return {
+                content: [{ type: 'text', text: `No cross-project links on ${ticketKey}.` }],
+                structuredContent: { links: [] },
+            };
+        }
+        const lines = rows.map((r) => {
+            const arrow = r.direction === 'outgoing' ? '→' : '←';
+            const key = r.otherEnd.ticketKey ?? r.otherEnd.ticketId.slice(0, 8);
+            const status = r.otherEnd.statusName ? ` [${r.otherEnd.statusName}]` : '';
+            const sync = r.link.statusSyncEnabled ? ' (sync)' : '';
+            return `  ${arrow} ${r.link.relationType}${sync}: [${key}] ${r.otherEnd.title}${status}`;
+        });
+        return {
+            content: [{ type: 'text', text: `Cross-project links on ${ticketKey}:\n${lines.join('\n')}` }],
+            structuredContent: { links: rows },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_add_cross_project_link
+// ---------------------------------------------------------------------------
+export const addCrossProjectLinkToolConfig = {
+    title: 'Add a cross-project link between two tickets',
+    description: 'Create a formal relation between two tickets in different projects. Caller must be a member of BOTH the source and target projects. Relation types: counterpart (parallel work in two repos - bidirectional), depends_on (this ticket waits for the other), blocks (the other waits for this), related (loose association). Pass statusSyncEnabled=true to opt into auto-close: when a counterpart-linked ticket moves to done, the other auto-closes too. Off by default.',
+    inputSchema: z.object({
+        sourceTicketKey: z.string().min(3),
+        targetTicketKey: z.string().min(3),
+        relationType: z.enum(RELATION_TYPES),
+        statusSyncEnabled: z.boolean().optional().default(false),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeAddCrossProjectLinkHandler(client) {
+    return async ({ sourceTicketKey, targetTicketKey, relationType, statusSyncEnabled }) => {
+        const row = await client.post(`/tickets/${encodeURIComponent(sourceTicketKey)}/cross-project-links`, { targetTicketKey, relationType, statusSyncEnabled: statusSyncEnabled ?? false });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Linked ${sourceTicketKey} → ${targetTicketKey} (${relationType}${row.statusSyncEnabled ? ', sync enabled' : ''}).`,
+                }],
+            structuredContent: { id: row.id, sourceTicketId: row.sourceTicketId, targetTicketId: row.targetTicketId, relationType: row.relationType, statusSyncEnabled: row.statusSyncEnabled },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_update_cross_project_link
+// ---------------------------------------------------------------------------
+export const updateCrossProjectLinkToolConfig = {
+    title: 'Toggle status-sync on a cross-project link',
+    description: 'Flip the statusSyncEnabled flag on an existing cross-project link. When enabled on a counterpart-typed link, the other end auto-closes when this one moves to done (and vice versa). Other relation types ignore the flag at runtime, so toggling it on them is a no-op as far as status-sync goes.',
+    inputSchema: z.object({
+        sourceTicketKey: z.string().min(3),
+        linkId: z.string().uuid(),
+        statusSyncEnabled: z.boolean(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeUpdateCrossProjectLinkHandler(client) {
+    return async ({ sourceTicketKey, linkId, statusSyncEnabled }) => {
+        const row = await client.patch(`/tickets/${encodeURIComponent(sourceTicketKey)}/cross-project-links/${linkId}`, { statusSyncEnabled });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Link ${linkId} status-sync ${row.statusSyncEnabled ? 'enabled' : 'disabled'}.`,
+                }],
+            structuredContent: { id: row.id, statusSyncEnabled: row.statusSyncEnabled },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_remove_cross_project_link
+// ---------------------------------------------------------------------------
+export const removeCrossProjectLinkToolConfig = {
+    title: 'Remove a cross-project link',
+    description: 'DESTRUCTIVE - drops the cross-project link between two tickets. Caller must be a member of both source and target projects (or super-admin). The underlying tickets are unaffected; only the relation row is deleted.',
+    inputSchema: z.object({
+        sourceTicketKey: z.string().min(3),
+        linkId: z.string().uuid(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeRemoveCrossProjectLinkHandler(client) {
+    return async ({ sourceTicketKey, linkId }) => {
+        await client.delete(`/tickets/${encodeURIComponent(sourceTicketKey)}/cross-project-links/${linkId}`);
+        return {
+            content: [{ type: 'text', text: `Removed cross-project link ${linkId} from ${sourceTicketKey}.` }],
+            structuredContent: { sourceTicketKey, linkId, deleted: true },
+        };
+    };
+}

package/dist/tools/cross-project-links.ee.test.js

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: Orboto-Enterprise-1.0
+/**
+ * ORB-945 - cross-project-link MCP tools.
+ *
+ *   - list: renders outgoing + incoming with arrow + sync marker, empty-state
+ *   - add: POSTs the right body, surfaces sync-on hint
+ *   - update: PATCHes statusSyncEnabled
+ *   - remove: DELETEs the row, bubbles 403 on forbidden
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeListCrossProjectLinksHandler, makeAddCrossProjectLinkHandler, makeUpdateCrossProjectLinkHandler, makeRemoveCrossProjectLinkHandler, } from './cross-project-links.ee.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const LINK_ID = '11111111-2222-3333-4444-555555555555';
+function stubJSON(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({
+            url: url.toString(),
+            method: init?.method ?? 'GET',
+            body: typeof init?.body === 'string' ? JSON.parse(init.body) : init?.body,
+        });
+        const r = responses.shift();
+        if (!r)
+            throw new Error('unexpected extra fetch');
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => '',
+        };
+    });
+    return calls;
+}
+const OUTGOING_LINK = {
+    direction: 'outgoing',
+    link: {
+        id: LINK_ID,
+        sourceTicketId: 'src-1',
+        targetTicketId: 'tgt-1',
+        relationType: 'counterpart',
+        statusSyncEnabled: true,
+        createdBy: 'u1',
+        createdAt: '2026-05-20T16:00:00.000Z',
+    },
+    otherEnd: {
+        ticketId: 'tgt-1',
+        ticketKey: 'OCP-7',
+        title: 'OCP-side counterpart',
+        statusName: 'In Progress',
+        statusColor: '#3b82f6',
+        statusCategory: 'in_progress',
+        projectId: 'p-ocp',
+        projectKey: 'OCP',
+        projectName: 'orboto Control Plane',
+    },
+};
+describe('orboto_list_cross_project_links', () => {
+    it('renders outgoing + sync marker + status', async () => {
+        stubJSON([{ json: [OUTGOING_LINK] }]);
+        const res = await makeListCrossProjectLinksHandler(client)({ ticketKey: 'ORB-42' });
+        const text = res.content[0].text;
+        expect(text).toContain('counterpart');
+        expect(text).toContain('(sync)');
+        expect(text).toContain('OCP-side counterpart');
+        expect(text).toContain('[In Progress]');
+        expect(text).toContain('→');
+    });
+    it('reports the empty-links case', async () => {
+        stubJSON([{ json: [] }]);
+        const res = await makeListCrossProjectLinksHandler(client)({ ticketKey: 'ORB-42' });
+        expect(res.content[0].text).toContain('No cross-project links');
+    });
+});
+describe('orboto_add_cross_project_link', () => {
+    it('POSTs the source path + body', async () => {
+        const calls = stubJSON([{
+                status: 201,
+                json: {
+                    id: LINK_ID,
+                    sourceTicketId: 'src-1',
+                    targetTicketId: 'tgt-1',
+                    relationType: 'counterpart',
+                    statusSyncEnabled: true,
+                    createdBy: 'u1',
+                    createdAt: '2026-05-20T16:00:00.000Z',
+                },
+            }]);
+        await makeAddCrossProjectLinkHandler(client)({
+            sourceTicketKey: 'ORB-42',
+            targetTicketKey: 'OCP-7',
+            relationType: 'counterpart',
+            statusSyncEnabled: true,
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: 'https://orboto.example.com/tickets/ORB-42/cross-project-links',
+            body: { targetTicketKey: 'OCP-7', relationType: 'counterpart', statusSyncEnabled: true },
+        });
+    });
+    it('bubbles up 403 when caller is not a member of both projects', async () => {
+        stubJSON([{ ok: false, status: 403, json: { error: 'You must be a member of both projects' } }]);
+        await expect(makeAddCrossProjectLinkHandler(client)({
+            sourceTicketKey: 'ORB-42',
+            targetTicketKey: 'OCP-7',
+            relationType: 'related',
+        })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+    it('bubbles up 409 on duplicate', async () => {
+        stubJSON([{ ok: false, status: 409, json: { error: 'This link already exists' } }]);
+        await expect(makeAddCrossProjectLinkHandler(client)({
+            sourceTicketKey: 'ORB-42',
+            targetTicketKey: 'OCP-7',
+            relationType: 'counterpart',
+        })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_update_cross_project_link', () => {
+    it('PATCHes statusSyncEnabled on the linkId', async () => {
+        const calls = stubJSON([{
+                json: {
+                    id: LINK_ID,
+                    sourceTicketId: 'src-1',
+                    targetTicketId: 'tgt-1',
+                    relationType: 'counterpart',
+                    statusSyncEnabled: false,
+                    createdBy: 'u1',
+                    createdAt: '2026-05-20T16:00:00.000Z',
+                },
+            }]);
+        await makeUpdateCrossProjectLinkHandler(client)({
+            sourceTicketKey: 'ORB-42',
+            linkId: LINK_ID,
+            statusSyncEnabled: false,
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'PATCH',
+            url: `https://orboto.example.com/tickets/ORB-42/cross-project-links/${LINK_ID}`,
+            body: { statusSyncEnabled: false },
+        });
+    });
+});
+describe('orboto_remove_cross_project_link', () => {
+    it('DELETEs the linkId', async () => {
+        const calls = stubJSON([{ status: 204 }]);
+        const res = await makeRemoveCrossProjectLinkHandler(client)({
+            sourceTicketKey: 'ORB-42',
+            linkId: LINK_ID,
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'DELETE',
+            url: `https://orboto.example.com/tickets/ORB-42/cross-project-links/${LINK_ID}`,
+        });
+        expect(res.structuredContent).toMatchObject({ deleted: true });
+    });
+    it('bubbles up 403 when caller can\'t access both ends', async () => {
+        stubJSON([{ ok: false, status: 403, json: { error: 'Forbidden' } }]);
+        await expect(makeRemoveCrossProjectLinkHandler(client)({ sourceTicketKey: 'ORB-42', linkId: LINK_ID })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});

package/dist/tools/customer-report.js

@@ -0,0 +1,88 @@
+/**
+ * ORB-1383 (epic ORB-1382) - `orboto_customer_report`.
+ *
+ * Generates the customer-facing project report as Markdown. Two presets:
+ * `scope` (proposal: milestones + epics, no progress) and `status` (all
+ * non-private tickets + progress). Private tickets/milestones are always
+ * excluded server-side. Wraps `POST /projects/:id/customer-report/generate`
+ * with `format: 'markdown'`. Money price mode needs budget:view on top of
+ * customer_report:generate (the API returns 403 otherwise).
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveProjectByKey } from './shared.js';
+const LOCALES = ['en', 'de', 'fr', 'it', 'es', 'sv'];
+export const customerReportToolConfig = {
+    title: 'Customer project report',
+    description: 'Generate the customer-facing project report as Markdown. `preset`: "scope" (proposal character - milestones + epics, no progress/status) or "status" (status report - all non-private tickets + progress). '
+        + '`locale` selects the report language (en/de/fr/it/es/sv) independently of your own locale; structure labels are catalog-translated. '
+        + '`priceMode`: "hours" (estimates, default), "money" (customer rates - needs the budget:view permission), or "lumpSum" (a flat price - pass `lumpSumAmount`). '
+        + 'Private tickets and milestones are always excluded, and internal cost/overhead is never included. Toggle sections with `sections` (overview, milestones, epics, tickets, budget). Requires the customer_report:generate permission on the project.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ORB").'),
+        preset: z.enum(['scope', 'status']).default('scope').describe('Report preset (default "scope").'),
+        locale: z.enum(LOCALES).default('en').describe('Report language (default "en").'),
+        priceMode: z.enum(['hours', 'money', 'lumpSum']).default('hours').describe('Pricing mode (default "hours"). "money" needs budget:view.'),
+        lumpSumAmount: z.number().nonnegative().optional().describe('Flat price for priceMode="lumpSum".'),
+        lumpSumCurrency: z.string().min(1).max(8).optional().describe('Currency for the lump sum (default EUR).'),
+        showAssigneeNames: z.boolean().optional().describe('Include assignee names (opt-in, default off).'),
+        showTicketKeys: z.boolean().optional().describe('Show ticket keys in the output (default on).'),
+        sections: z.object({
+            overview: z.boolean().optional(),
+            milestones: z.boolean().optional(),
+            epics: z.boolean().optional(),
+            tickets: z.boolean().optional(),
+            budget: z.boolean().optional(),
+        }).optional().describe('Section toggles on top of the preset default.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeCustomerReportHandler(client) {
+    return async (input) => {
+        const project = await resolveProjectByKey(client, input.projectKey);
+        const priceMode = input.priceMode ?? 'hours';
+        const options = {
+            priceMode,
+            showAssigneeNames: input.showAssigneeNames ?? false,
+            showTicketKeys: input.showTicketKeys ?? true,
+        };
+        if (priceMode === 'lumpSum') {
+            options.lumpSum = {
+                amount: input.lumpSumAmount ?? 0,
+                currency: input.lumpSumCurrency ?? 'EUR',
+            };
+        }
+        const body = {
+            preset: input.preset ?? 'scope',
+            locale: input.locale ?? 'en',
+            options,
+            format: 'markdown',
+        };
+        if (input.sections)
+            body.sections = input.sections;
+        let res;
+        try {
+            res = await client.post(`/projects/${project.id}/customer-report/generate`, body);
+        }
+        catch (err) {
+            if (err instanceof OrbotoApiError && err.status === 403 && priceMode === 'money') {
+                return {
+                    content: [{ type: 'text', text: `Not permitted: money price mode needs the budget:view permission on ${project.key}.` }],
+                    structuredContent: { error: 'forbidden', requiredPermission: 'budget:view' },
+                };
+            }
+            throw err;
+        }
+        return {
+            content: [{ type: 'text', text: res.markdown }],
+            structuredContent: {
+                projectKey: project.key,
+                preset: res.preset,
+                locale: res.locale,
+                priceMode: res.priceMode,
+                aiSkipped: res.aiSkipped,
+                reviewFlags: res.reviewFlags,
+            },
+        };
+    };
+}

package/dist/tools/customer-report.test.js

@@ -0,0 +1,55 @@
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeCustomerReportHandler } from './customer-report.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        const body = init?.body ? JSON.parse(String(init.body)) : undefined;
+        calls.push({ url: url.toString(), body });
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch to ${url}`);
+        const status = r.status ?? 200;
+        return {
+            ok: status < 400, status, statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}), text: async () => '',
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: '', status: 'active' };
+const MD = {
+    markdown: '# Project Report - Acme\n\n## Milestones\n',
+    preset: 'scope', locale: 'de', priceMode: 'hours',
+    aiSkipped: null,
+    reviewFlags: { executiveSummaryGenerated: false, contentTranslated: false, translatedFields: 0 },
+};
+describe('orboto_customer_report (ORB-1383)', () => {
+    it('resolves the project and posts a markdown generate with preset + locale', async () => {
+        const calls = stub([{ json: PROJ }, { json: MD }]);
+        const res = await makeCustomerReportHandler(client)({ projectKey: 'ACME', preset: 'scope', locale: 'de' });
+        expect(calls[1].url).toContain('/projects/p1/customer-report/generate');
+        expect(calls[1].body).toMatchObject({ preset: 'scope', locale: 'de', format: 'markdown' });
+        expect(res.content[0].text).toContain('Project Report');
+        expect(res.structuredContent).toMatchObject({ projectKey: 'ACME', preset: 'scope', locale: 'de', aiSkipped: null });
+    });
+    it('passes lump-sum amount/currency in the options', async () => {
+        const calls = stub([{ json: PROJ }, { json: { ...MD, priceMode: 'lumpSum' } }]);
+        await makeCustomerReportHandler(client)({ projectKey: 'ACME', priceMode: 'lumpSum', lumpSumAmount: 5000, lumpSumCurrency: 'USD' });
+        expect(calls[1].body).toMatchObject({ options: { priceMode: 'lumpSum', lumpSum: { amount: 5000, currency: 'USD' } } });
+    });
+    it('surfaces a budget:view 403 for money mode as a clean structured error', async () => {
+        stub([{ json: PROJ }, { status: 403, json: { error: 'Forbidden' } }]);
+        const res = await makeCustomerReportHandler(client)({ projectKey: 'ACME', priceMode: 'money' });
+        expect(res.structuredContent.requiredPermission).toBe('budget:view');
+        expect(res.content[0].text).toMatch(/budget:view/);
+    });
+    it('defaults to scope preset + hours mode', async () => {
+        const calls = stub([{ json: PROJ }, { json: MD }]);
+        await makeCustomerReportHandler(client)({ projectKey: 'ACME' });
+        expect(calls[1].body).toMatchObject({ preset: 'scope', options: { priceMode: 'hours' } });
+    });
+});

package/dist/tools/doc-attachments.js

@@ -0,0 +1,184 @@
+/**
+ * ORB-914 - doc-attachments MCP tools (epic ORB-911 Phase 3).
+ *
+ * Mirrors the ticket-attachment surface (apps/mcp/src/tools/attach.ts)
+ * for doc pages. Three tools:
+ *
+ * - orboto_upload_doc_attachment - multipart upload + optional embed
+ * - orboto_list_doc_attachments - flat list with download URLs
+ * - orboto_delete_doc_attachment - destructive
+ *
+ * The embed branch on upload PATCHes the doc body to append a Markdown
+ * image-or-link line, same pattern as orboto_attach_to_ticket. Useful
+ * when an agent wants to drop a screenshot into a page in one call.
+ *
+ * MIME / extension policy is enforced server-side via `isAttachmentAllowed`
+ * - the tool just surfaces the 415 as an OrbotoApiError so the caller
+ * can pick a different file.
+ */
+import { z } from 'zod';
+import { resolveDocId } from './docs.js';
+/**
+ * Very small MIME guesser - same shape as attach.ts. The API also sniffs
+ * the filename, so this only needs to land in the right ballpark for the
+ * Blob's Content-Type header.
+ */
+function mimetypeFor(filename) {
+    const lower = filename.toLowerCase();
+    if (lower.endsWith('.png'))
+        return 'image/png';
+    if (lower.endsWith('.jpg') || lower.endsWith('.jpeg'))
+        return 'image/jpeg';
+    if (lower.endsWith('.gif'))
+        return 'image/gif';
+    if (lower.endsWith('.webp'))
+        return 'image/webp';
+    if (lower.endsWith('.pdf'))
+        return 'application/pdf';
+    if (lower.endsWith('.txt') || lower.endsWith('.log'))
+        return 'text/plain';
+    if (lower.endsWith('.md') || lower.endsWith('.markdown'))
+        return 'text/markdown';
+    if (lower.endsWith('.json'))
+        return 'application/json';
+    if (lower.endsWith('.csv'))
+        return 'text/csv';
+    if (lower.endsWith('.docx'))
+        return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+    return 'application/octet-stream';
+}
+function isImage(mimetype) {
+    return mimetype.startsWith('image/');
+}
+// ---------------------------------------------------------------------------
+// orboto_upload_doc_attachment
+// ---------------------------------------------------------------------------
+export const uploadDocAttachmentToolConfig = {
+    title: 'Upload an attachment to a doc page',
+    description: 'Upload a file as an attachment on a wiki doc and return its Markdown image (or link) line + the stable download URL. Bytes come in as base64 (`contentBase64`) so this works without local FS access on the agent side. Set `embed=true` to also PATCH the doc body to append the Markdown line - useful for dropping a screenshot into a page in one call. MIME / extension policy is enforced server-side: blocked types (HTML, SVG, executables) surface a 415.',
+    inputSchema: z.object({
+        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        filename: z.string().min(1).describe('Display filename, e.g. "architecture-diagram.png".'),
+        contentBase64: z.string().min(1).describe('File content, base64-encoded.'),
+        altText: z.string().optional().describe('Alt-text for the Markdown image line. Defaults to filename.'),
+        embed: z.boolean().optional().describe('If true, PATCHes the doc body to append the Markdown line. Idempotent up to duplicate detection - re-running appends another copy.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeUploadDocAttachmentHandler(client) {
+    return async ({ docId, filename, contentBase64, altText, embed }) => {
+        docId = await resolveDocId(client, docId);
+        let arrayBuffer;
+        try {
+            // Buffer → fresh ArrayBuffer copy (see attach.ts for the Blob
+            // type-constraint rationale).
+            const buf = Buffer.from(contentBase64, 'base64');
+            arrayBuffer = new ArrayBuffer(buf.byteLength);
+            new Uint8Array(arrayBuffer).set(buf);
+        }
+        catch {
+            throw new Error('contentBase64 is not valid base64.');
+        }
+        if (arrayBuffer.byteLength === 0) {
+            throw new Error('contentBase64 decoded to 0 bytes - refuse to upload an empty file.');
+        }
+        const form = new FormData();
+        form.append('file', new Blob([arrayBuffer], { type: mimetypeFor(filename) }), filename);
+        const att = await client.postMultipart(`/docs/${docId}/attachments`, form);
+        const alt = altText ?? att.filename;
+        const url = att.downloadUrl ?? `/attachments/${att.id}`;
+        const markdown = isImage(att.contentType)
+            ? `![${alt}](${url})`
+            : `[${alt}](${url})`;
+        let embedded = false;
+        if (embed === true) {
+            // Read the current body first - PATCH /docs/:id replaces, not
+            // appends. Then write the new body in one go.
+            const current = await client.get(`/docs/${docId}`);
+            const existing = current.content ?? '';
+            const next = existing ? `${existing}\n\n${markdown}` : markdown;
+            await client.patch(`/docs/${docId}`, { content: next });
+            embedded = true;
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Attached ${att.filename} (${Math.round(att.sizeBytes / 1024)} KB) to doc ${docId}${embedded ? ' and embedded in body' : ''}.\n${markdown}`,
+                }],
+            structuredContent: {
+                docId,
+                attachmentId: att.id,
+                filename: att.filename,
+                sizeBytes: att.sizeBytes,
+                contentType: att.contentType,
+                downloadUrl: url,
+                markdown,
+                embedded,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_list_doc_attachments
+// ---------------------------------------------------------------------------
+export const listDocAttachmentsToolConfig = {
+    title: 'List attachments on a doc page',
+    description: 'Return the doc\'s attachments newest-first, with stable download URLs the agent can hand to the user. Empty list = no attachments.',
+    inputSchema: z.object({
+        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListDocAttachmentsHandler(client) {
+    return async ({ docId }) => {
+        docId = await resolveDocId(client, docId);
+        const rows = await client.get(`/docs/${docId}/attachments`);
+        if (rows.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No attachments on this doc.' }],
+                structuredContent: { attachments: [] },
+            };
+        }
+        const lines = rows.map((r) => {
+            const url = r.downloadUrl ?? `/attachments/${r.id}`;
+            const kb = Math.round(r.sizeBytes / 1024);
+            return `- ${r.filename}  (${kb} KB, ${r.contentType}) → ${url}`;
+        });
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                attachments: rows.map((r) => ({
+                    id: r.id,
+                    filename: r.filename,
+                    contentType: r.contentType,
+                    sizeBytes: r.sizeBytes,
+                    uploadedAt: r.uploadedAt,
+                    uploadedBy: r.uploadedBy,
+                    downloadUrl: r.downloadUrl ?? `/attachments/${r.id}`,
+                })),
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_delete_doc_attachment
+// ---------------------------------------------------------------------------
+export const deleteDocAttachmentToolConfig = {
+    title: 'Delete an attachment from a doc page',
+    description: 'DESTRUCTIVE - drops the file row + deletes the underlying S3 object. Does NOT rewrite the doc body, so embedded Markdown lines pointing at the deleted URL will surface as broken images / links. Walk those by hand if needed.',
+    inputSchema: z.object({
+        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        attachmentId: z.string().uuid(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeDeleteDocAttachmentHandler(client) {
+    return async ({ docId, attachmentId }) => {
+        docId = await resolveDocId(client, docId);
+        await client.delete(`/docs/${docId}/attachments/${attachmentId}`);
+        return {
+            content: [{ type: 'text', text: `Attachment ${attachmentId} removed from doc ${docId}.` }],
+            structuredContent: { docId, attachmentId, deleted: true },
+        };
+    };
+}