@orboto/mcp 0.192.0 → 0.194.0

package/dist/tools/doc-export.js

@@ -1,27 +1,8 @@
 /**
  * ORB-915 - doc-export MCP tools (epic ORB-911 Phase 4).
- *
- * - orboto_export_doc_md - GET /docs/:id/export/md   (text/markdown)
- * - orboto_export_doc_pdf - POST /docs/:id/export/pdf (application/pdf)
- *
- * The Markdown export differs from `orboto_get_doc.content` because
- * the server-side renderer strips backlinks / smart-link inflation
- * and emits the raw saved Markdown - useful when the agent wants to
- * pipe the body through another tool without the get-doc envelope.
- *
- * The PDF export returns binary bytes. MCP supports binary resource
- * attachments via the `{ type: 'resource', resource: { uri, blob:
- * <base64>, mimeType } }` content shape; we return the PDF that way.
- *
- * Both endpoints rely on `OrbotoClient.getText` / `postBinary` which
- * landed alongside this phase - JSON-only `get` / `post` would have
- * blown up on the non-JSON response bodies.
  */
 import { z } from 'zod';
 import { resolveDocId } from './docs.js';
-// ---------------------------------------------------------------------------
-// orboto_export_doc_md
-// ---------------------------------------------------------------------------
 export const exportDocMdToolConfig = {
     title: 'Export a doc page as Markdown',
     description: 'Return the doc body as plain Markdown (text/markdown). Differs from orboto_get_doc.content in that the server-side export endpoint emits the canonical saved body - agents pulling docs to feed into another tool should prefer this over get_doc, which wraps the body in get-doc envelope text + backlinks.',
@@ -44,9 +25,6 @@ export function makeExportDocMdHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_export_doc_pdf
-// ---------------------------------------------------------------------------
 export const exportDocPdfToolConfig = {
     title: 'Export a doc page as PDF',
     description: 'Render the doc page to PDF via the workspace\'s PdfService (Puppeteer-backed) and return the bytes as a base64 MCP resource attachment. Requires the PDF engine to be configured - deployments without Chromium / Puppeteer return 503 (errors.pdf.engine_unavailable) which surfaces as an OrbotoApiError.',
@@ -59,8 +37,6 @@ export function makeExportDocPdfHandler(client) {
     return async ({ docId }) => {
         docId = await resolveDocId(client, docId);
         const { bytes, contentType } = await client.postBinary(`/docs/${docId}/export/pdf`);
-        // MCP's `resource` content type takes a base64 blob - Buffer →
-        // base64 is the standard Node path.
         const base64 = Buffer.from(bytes).toString('base64');
         return {
             content: [

package/dist/tools/doc-export.test.js

@@ -1,15 +1,5 @@
 /**
  * ORB-915 - doc-export tool tests.
- *
- * Markdown export: stub fetch returning a string + content-type
- * text/markdown. Verify the tool returns the Markdown verbatim.
- *
- * PDF export: stub fetch returning a Uint8Array body. Verify the
- * tool wraps it as an MCP resource attachment with base64 blob.
- *
- * 503 from a deployment with no PDF engine: verify the
- * OrbotoApiError bubbles up so the model can tell the user what's
- * wrong.
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
@@ -81,7 +71,6 @@ describe('orboto_export_doc_md', () => {
 });
 describe('orboto_export_doc_pdf', () => {
     it('POSTs /docs/:id/export/pdf and wraps the bytes as a base64 MCP resource', async () => {
-        // Pretend the renderer returned a minimal 8-byte PDF header.
         const pdfBytes = new Uint8Array([0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x37]);
         const calls = stubBinary(pdfBytes);
         const res = await makeExportDocPdfHandler(client)({ docId: DOC_ID });
@@ -93,7 +82,6 @@ describe('orboto_export_doc_pdf', () => {
         expect(first.type).toBe('resource');
         expect(first.resource.uri).toBe(`orboto://doc/${DOC_ID}/export.pdf`);
         expect(first.resource.mimeType).toBe('application/pdf');
-        // The blob is the base64 of the bytes - decode it back and compare.
         const decoded = Buffer.from(first.resource.blob, 'base64');
         expect(Array.from(decoded)).toEqual(Array.from(pdfBytes));
         expect(res.structuredContent).toMatchObject({

package/dist/tools/doc-revisions.js

@@ -1,25 +1,8 @@
 /**
  * ORB-916 - doc revision history MCP tools (epic ORB-911 Phase 5).
- *
- * - orboto_list_doc_revisions - GET /docs/:id/revisions  (cursor-paged)
- * - orboto_get_doc_revision - GET /docs/:id/revisions/:rid
- * - orboto_restore_doc_revision - POST /docs/:id/revisions/:rid/restore
- *
- * Revisions are auto-captured by PATCH /docs/:id every time the title
- * or body changes, so by the time an agent wants to roll back there's
- * usually a long history to walk. The list endpoint is cursor-paged
- * (newest-first by editedAt DESC + id tiebreak) - the tool surfaces
- * `nextCursor` in structuredContent so the caller can page through if
- * the default 25-row page isn't enough.
- *
- * Restore writes a new revision capturing the current body before
- * rolling back, so the restore itself is also undoable.
  */
 import { z } from 'zod';
 import { resolveDocId } from './docs.js';
-// ---------------------------------------------------------------------------
-// orboto_list_doc_revisions
-// ---------------------------------------------------------------------------
 export const listDocRevisionsToolConfig = {
     title: 'List the revision history of a doc page',
     description: 'Return saved revisions for a doc page, newest-first. Each row carries the revision id, title at snapshot time, editor user id, and editedAt timestamp; the body content is NOT in this list (use orboto_get_doc_revision to fetch one). Cursor-paged - pass `cursor` to walk older pages.',
@@ -69,9 +52,6 @@ export function makeListDocRevisionsHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_get_doc_revision
-// ---------------------------------------------------------------------------
 export const getDocRevisionToolConfig = {
     title: 'Get a single doc revision',
     description: 'Return the full content + title of one saved revision. Use this to diff against the current doc before deciding whether to restore.',
@@ -101,9 +81,6 @@ export function makeGetDocRevisionHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_restore_doc_revision
-// ---------------------------------------------------------------------------
 export const restoreDocRevisionToolConfig = {
     title: 'Restore a doc page to a saved revision',
     description: 'Roll back the doc to the saved revision. The API snapshots the CURRENT body to a fresh revision row first, so the restore itself is also undoable. Returns the post-restore doc state.',

package/dist/tools/docs-ai.js

@@ -1,34 +1,7 @@
 /**
  * ORB-799 - docs-AI surface (ask + ingest).
- *
- * Three tools that mirror the wrapper's `ask-docs` / `ingest-url` /
- * `ingest-file` subcommands. Together they're the foundation for any
- * agent that needs to "remember this URL" / "add this PDF to our
- * wiki" workflows.
- *
- * - orboto_ask_docs - RAG Q&A across wiki docs, returns answer +
- *                         citations. Requires both `configured` and
- *                         `embeddingsConfigured` on `/ai/status`
- *                         (RAG retrieval needs an embedding-capable
- *                         provider).
- * - orboto_ingest_url - fetch + extract + create doc from a public
- *                         URL via the Readability-fallback pipeline.
- * - orboto_ingest_file - upload + extract + create doc from a local
- *                         file (PDF / DOCX / Markdown / plain text).
- *                         Uses the multipart-upload route, so the MCP
- *                         tool receives the bytes as a base64 string
- *                         to avoid the model needing local FS access.
- *
- * AI-gated note: the `ai_status` tool exists for pre-flight. We do NOT
- * pre-check inside the handlers - the API returns the same gating
- * error regardless and a pre-check would double the latency of every
- * call. Models are expected to call `orboto_ai_status` once per
- * session if they're unsure of workspace shape.
  */
 import { z } from 'zod';
-// ---------------------------------------------------------------------------
-// orboto_ask_docs
-// ---------------------------------------------------------------------------
 export const askDocsToolConfig = {
     title: 'Ask a question against the wiki (RAG)',
     description: 'Run a natural-language question against the wiki via the workspace\'s RAG pipeline. Returns an `answer` (Markdown) + `citations` array `[{index, title, link, spaceName}]`. The model is the workspace\'s configured AI provider; retrieval requires the embedding provider too - call `orboto_ai_status` to verify both before relying on this. Restrict to a single doc space with `spaceId` when scoping a query (e.g. "only the runbooks space"). Latency is dominated by retrieval + LLM round-trip; expect 2-10s.',
@@ -67,9 +40,6 @@ export function makeAskDocsHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_ingest_url
-// ---------------------------------------------------------------------------
 export const ingestUrlToolConfig = {
     title: 'Ingest a public URL into a wiki space',
     description: 'Fetch a public URL, run Readability extraction, store the result as a Markdown doc in `spaceId`. Optionally nest under `parentDocId` to keep the tree tidy. Sets `readabilityFallback: true` when the page didn\'t look like a recognisable article (the body falls back to full-page text - a flag the caller should surface to the operator for review).',
@@ -108,9 +78,6 @@ export function makeIngestUrlHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_ingest_file
-// ---------------------------------------------------------------------------
 function mimetypeFor(filename) {
     const lower = filename.toLowerCase();
     if (lower.endsWith('.pdf'))
@@ -136,7 +103,6 @@ export function makeIngestFileHandler(client) {
     return async ({ spaceId, filename, contentBase64, parentDocId }) => {
         let arrayBuffer;
         try {
-            // See attach.ts for the Buffer → ArrayBuffer copy rationale.
             const buf = Buffer.from(contentBase64, 'base64');
             arrayBuffer = new ArrayBuffer(buf.byteLength);
             new Uint8Array(arrayBuffer).set(buf);

package/dist/tools/docs-ai.test.js

@@ -1,13 +1,5 @@
 /**
  * ORB-799 - docs-AI tools tests.
- *
- * `orboto_ask_docs` happy + AI-not-configured-style 400.
- * `orboto_ingest_url` happy + readability-fallback flag.
- * `orboto_ingest_file` happy + empty-bytes refusal.
- *
- * The multipart upload's wire format is verified by inspecting the
- * FormData body the fetch mock receives - we read the form-fields
- * back to assert filename + parent.
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
@@ -124,9 +116,6 @@ describe('orboto_ingest_url', () => {
 });
 describe('orboto_ingest_file', () => {
     it('POSTs multipart with filename + decoded content', async () => {
-        // Capture the multipart body via the fetch mock - FormData is
-        // opaque to JSON.parse, so we don't decode it; we only assert the
-        // route, method, and the JSON response shape.
         const calls = [];
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
             calls.push({

package/dist/tools/docs.js

@@ -1,30 +1,10 @@
 /**
  * ORB-244 Phase B - doc tools.
  *
- * `orboto_list_doc_spaces` and `orboto_get_doc` share this file for the
- * same reason the milestone tools do - cheap neighbours on the same
- * API root. Docs carry a human-readable key (`ORB-D12` / `DOC-5`,
- * ORB-1004) and spaces carry one too (`ORB-S1` / `SPACE-5`, ORB-1015);
- * both resolve by key or UUID.
- *
- * ORB-912 (epic ORB-911) added the write-path neighbours so an
- * MCP-aware client can do the full space lifecycle without falling
- * back to REST: create / update / delete spaces, list docs in a
- * space, and (in follow-up phases) write / move / attach / export /
- * roll back individual doc pages.
- *
- * Schema alignment: field names match `@orboto/shared-schema`
- * exactly - `content` not `body` on docs, `excerpt` not `snippet` on
- * hits, backlinks carry `{type, id, label, sourceDocId,
- * sourceDocTitle, sourceSpaceId}`. Getting those wrong 500s the tool
- * because the API's Zod response validator rejects off-shape rows
- * before they leave the server.
+ * @see ORB-1004, ORB-1015, ORB-912, ORB-911
  */
 import { z } from 'zod';
 import { resolveProjectByKey } from './shared.js';
-// ---------------------------------------------------------------------------
-// orboto_list_doc_spaces
-// ---------------------------------------------------------------------------
 export const listDocSpacesToolConfig = {
     title: 'List doc spaces',
     description: 'List wiki spaces (global and project-scoped) the caller can read. Each space contains a tree of docs accessed via orboto_get_doc.',
@@ -37,20 +17,12 @@ export function makeListDocSpacesHandler(client) {
         const text = spaces.length === 0
             ? 'No doc spaces visible to this user.'
             : spaces.map((s) => {
-                // `type` is the authoritative scope indicator; `projectId` is
-                // populated when type === 'project'. We use the type flag so
-                // the text rendering doesn't depend on an extra API join.
                 const scope = s.type === 'project' ? 'project-scoped' : 'workspace-wide';
-                // ORB-1161 - show key AND uuid. Doc tools accept the key directly,
-                // but surface the uuid too for any tool that still needs it.
                 return `- ${s.name} (${scope}) - key: ${s.key ?? '(none)'}  id: ${s.id}`;
             }).join('\n');
         return {
             content: [{ type: 'text', text }],
             structuredContent: {
-                // ORB-1700 - metadata only; description/slug/visibility belong to
-                // the follow-up space read. id stays: every doc tool accepts it,
-                // and pre-key spaces have no key to address by.
                 spaces: spaces.map((s) => ({
                     id: s.id,
                     key: s.key ?? null,
@@ -61,13 +33,7 @@ export function makeListDocSpacesHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_get_doc
-// ---------------------------------------------------------------------------
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-// ORB-1084 - every docId-taking tool accepts the human-readable doc
-// key (ORB-D12 / DOC-5) as well; writes were UUID-only while no tool
-// exposed the full UUID, so agents could read but never write.
 export async function resolveDocId(client, docIdOrKey) {
     if (UUID_RE.test(docIdOrKey))
         return docIdOrKey;
@@ -84,8 +50,6 @@ export const getDocToolConfig = {
 };
 export function makeGetDocHandler(client) {
     return async ({ docId }) => {
-        // ORB-1004 - accept a doc key too; resolve via the by-key route, then
-        // use the resolved UUID for the backlinks fetch.
         const doc = UUID_RE.test(docId)
             ? await client.get(`/docs/${docId}`)
             : await client.get(`/docs/by-key/${encodeURIComponent(docId)}`);
@@ -99,10 +63,6 @@ export function makeGetDocHandler(client) {
         if (backlinks.length > 0) {
             lines.push('', `## Backlinks (${backlinks.length})`);
             for (const b of backlinks) {
-                // sourceDocTitle is the doc that links *to* this one; the
-                // `type` + `id` pair identifies the target - same row, target
-                // side. For most backlinks the target is this doc, so we
-                // surface the source.
                 lines.push(`- ${b.sourceDocTitle}`);
             }
         }
@@ -131,9 +91,6 @@ export function makeGetDocHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_create_doc_space  (ORB-912)
-// ---------------------------------------------------------------------------
 export const createDocSpaceToolConfig = {
     title: 'Create a doc space',
     description: 'Create a new wiki space. IMPORTANT: every project ALREADY has an auto-generated general space (slug `<key>-general`, system-generated, holds the AI primer + manual notes) - do NOT create a second space just to hold a project\'s docs. Call orboto_list_doc_spaces first and reuse the existing project space; only create a new one for a genuinely separate collection. `type=global` creates a workspace-wide space (super-admin only); `type=project` creates a space scoped to a project - pass `projectKey` (e.g. "ORB"); a raw `projectId` UUID is still accepted for back-compat. The slug is derived from `name` when omitted. Returns the new space row.',
@@ -152,8 +109,6 @@ export function makeCreateDocSpaceHandler(client) {
     return async (input) => {
         const body = { name: input.name, type: input.type };
         if (input.type === 'project') {
-            // Prefer the key (agent-facing surfaces speak keys); fall back to a raw
-            // UUID for back-compat.
             let projectId = input.projectId;
             if (!projectId && input.projectKey) {
                 projectId = (await resolveProjectByKey(client, input.projectKey)).id;
@@ -187,9 +142,6 @@ export function makeCreateDocSpaceHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_update_doc_space  (ORB-912)
-// ---------------------------------------------------------------------------
 export const updateDocSpaceToolConfig = {
     title: 'Update a doc space',
     description: 'Patch a space\'s name / description / icon / slug, and (ORB-1080) its visibility settings: `visibility` (workspace = every internal member, restricted = explicit allowlist via memberIds), `guestsVisible` (external users see the space only when true). Visibility fields require space-management rights (global spaces: super-admin; project spaces: project:edit) - plain membership gets a 403 for those. `isPublic` is deprecated (replaced by guestsVisible). `type` and `projectId` are immutable; auto-generated primer spaces refuse name/slug edits.',
@@ -219,7 +171,6 @@ export function makeUpdateDocSpaceHandler(client) {
             body.isPublic = input.isPublic;
         if (input.slug !== undefined)
             body.slug = input.slug;
-        // ORB-1080 - visibility settings (manage-gated server-side).
         if (input.visibility !== undefined)
             body.visibility = input.visibility;
         if (input.guestsVisible !== undefined)
@@ -245,9 +196,6 @@ export function makeUpdateDocSpaceHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_delete_doc_space  (ORB-912)
-// ---------------------------------------------------------------------------
 export const deleteDocSpaceToolConfig = {
     title: 'Delete a doc space',
     description: 'DESTRUCTIVE - cascades through every doc in the space (the pages themselves are gone, not just hidden). System-generated project primer spaces refuse deletion (they cascade only when the owning project is deleted). Returns success silently; 404 surfaces as an OrbotoApiError.',
@@ -265,9 +213,6 @@ export function makeDeleteDocSpaceHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_list_docs_in_space  (ORB-912)
-// ---------------------------------------------------------------------------
 export const listDocsInSpaceToolConfig = {
     title: 'List docs inside a space',
     description: 'Return the flat list of doc pages in a space - each carries `parentDocId` so the caller can reconstruct the tree client-side. Use this when an agent needs to find a doc by title rather than asking for a UUID first. Pair with orboto_get_doc to read individual page bodies.',
@@ -285,9 +230,6 @@ export function makeListDocsInSpaceHandler(client) {
                 structuredContent: { docs: [] },
             };
         }
-        // Index by parent so we can render a simple indented tree. The
-        // tree-walk runs in JS - the API hands us the flat list because
-        // sort-order is per-parent and traversal is the caller's concern.
         const byParent = new Map();
         for (const r of rows) {
             const key = r.parentDocId ?? null;
@@ -304,7 +246,6 @@ export function makeListDocsInSpaceHandler(client) {
             for (const c of children) {
                 const indent = '  '.repeat(depth);
                 const iconPart = c.icon ? `${c.icon} ` : '';
-                // ORB-1004 - show the typeable key (falls back to UUID).
                 lines.push(`${indent}- ${iconPart}${c.title}  (${c.docKey ?? c.id})`);
                 walk(c.id, depth + 1);
             }
@@ -328,9 +269,6 @@ export function makeListDocsInSpaceHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_create_doc  (ORB-913)
-// ---------------------------------------------------------------------------
 export const createDocToolConfig = {
     title: 'Create a doc page',
     description: 'Create a new wiki page in `spaceId` with the supplied Markdown body. Unlike orboto_ingest_url / orboto_ingest_file (which derive content from an external source), this is the plain "I have the Markdown, make me a page" path. Title is required; content is optional (creates an empty page). Returns the new doc row including its UUID and its human-readable doc key (e.g. ORB-D12).',
@@ -370,9 +308,6 @@ export function makeCreateDocHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_update_doc  (ORB-913)
-// ---------------------------------------------------------------------------
 export const updateDocToolConfig = {
     title: 'Update a doc page',
     description: 'Patch a doc\'s title / content / visibility / parent / icon. Content-only updates do not require sending the title. Every body or title change snapshots the previous version into the revision history automatically - agents can roll back via orboto_restore_doc_revision (when that tool ships in Phase 5). Re-embeds the doc when content or title change.',
@@ -417,9 +352,6 @@ export function makeUpdateDocHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_delete_doc  (ORB-913)
-// ---------------------------------------------------------------------------
 export const deleteDocToolConfig = {
     title: 'Delete a doc page',
     description: 'DESTRUCTIVE - removes the page from the tree. Revisions are NOT auto-cascaded; the API keeps them so an admin could in principle resurrect from history, but the page itself is gone from listings. System-generated primer docs refuse deletion (the regenerator re-creates them). Returns success silently; 404 is also silent (idempotent).',
@@ -438,9 +370,6 @@ export function makeDeleteDocHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_move_doc  (ORB-913)
-// ---------------------------------------------------------------------------
 export const moveDocToolConfig = {
     title: 'Move a doc page (reparent / reorder / cross-space)',
     description: 'Reparent a doc, change its sort order, or move it into a different space. All three target fields are optional but at least one must be supplied. Distinct from orboto_update_doc\'s parentDocId because the API endpoint emits a different WS event for the tree-rebuild path connected clients care about.',
@@ -477,9 +406,6 @@ export function makeMoveDocHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_duplicate_doc_space  (ORB-918)
-// ---------------------------------------------------------------------------
 export const duplicateDocSpaceToolConfig = {
     title: 'Duplicate a doc space (clone the space + every doc inside it)',
     description: 'Fork a doc space along with its entire doc tree. The new space\'s name becomes `<source> (copy)`, parent-child relationships in the tree are preserved via UUID remap. Useful when an agent wants to iterate on a runbook space without mutating the original.',

package/dist/tools/docs.test.js

@@ -148,7 +148,7 @@ describe('orboto_list_docs_in_space', () => {
         sortOrder: 0,
     };
     it('renders an indented tree text + flat structured list', async () => {
-        stubJSON([{ json: [CHILD, ROOT] /* deliberately unsorted to verify the local sort */ }]);
+        stubJSON([{ json: [CHILD, ROOT] }]);
         const res = await makeListDocsInSpaceHandler(client)({ spaceId: PROJECT_SCOPED_SPACE.id });
         const text = res.content[0].text;
         expect(text.indexOf('Architecture')).toBeLessThan(text.indexOf('Queue worker'));
@@ -229,8 +229,6 @@ describe('orboto_create_doc', () => {
     });
 });
 describe('orboto_update_doc', () => {
-    // ORB-1084 - write tools accept the human-readable doc key: the key
-    // resolves via /docs/by-key, then the PATCH targets the UUID.
     it('resolves a doc key to the UUID before writing', async () => {
         const calls = stubJSON([
             { json: DOC }, // by-key resolve

package/dist/tools/embedding-status.js

@@ -1,15 +1,5 @@
 /**
  * ORB-1309 - `orboto_embedding_status`.
- *
- * Operator diagnostic for the embedding pipeline: provider/model/dims, coverage
- * (embedded vs total, and how many are PENDING - never-embedded / stale - per
- * tickets / comments / docs and overall), the circuit-breaker state, and when
- * the last embedding was written. Wraps GET /admin/ai/embedding-status.
- *
- * `orboto_ai_status` only reports whether embeddings are configured; this is the
- * deeper surface for "why is semantic search / duplicate detection / ask-docs
- * stale" - a tripped breaker, a stuck queue, or a provider that stopped
- * responding. Admin:ai:read gated (403 for non-admin callers).
  */
 import { z } from 'zod';
 export const embeddingStatusToolConfig = {
@@ -52,12 +42,9 @@ export function makeEmbeddingStatusHandler(client) {
             lines.push(`Coverage: ${o.embedded} / ${o.embeddable} embeddable embedded · ${o.pending} pending${o.noContent > 0 ? ` · ${o.noContent} with no embeddable content (excluded)` : ''}`);
             lines.push(`  tickets ${s.coverage.ticket.embedded}/${s.coverage.ticket.embeddable} · comments ${s.coverage.comment.embedded}/${s.coverage.comment.embeddable} · docs ${s.coverage.doc.embedded}/${s.coverage.doc.embeddable} (embeddable)`);
             lines.push(`Circuit breaker: ${s.breaker.tripped ? `TRIPPED - ${s.breaker.lastTrippedReason ?? 'unknown reason'} (${s.breaker.consecutiveFailures} consecutive failures)` : 'ok'}`);
-            // ORB-1715 - a billing gate is the one cause the customer can fix
-            // themselves; name it instead of letting it read as a provider fault.
             if (s.billingGate?.gated) {
                 lines.push(`BILLING GATE: managed AI is paused for billing${s.billingGate.reason ? ` (${s.billingGate.reason})` : ''} since ${s.billingGate.blockedAt ?? 'unknown'}. The workspace admin resolves this in their orboto account; queued items embed automatically after the unblock.`);
             }
-            // ORB-1719 - spend visibility so an agent can warn BEFORE the gate.
             if (s.spend?.allowanceGrantMicrocents != null && s.spend.allowanceConsumedMicrocents != null) {
                 const eur = (mc) => (mc / 1_000_000).toFixed(2);
                 lines.push(`Included AI this month: ${eur(s.spend.allowanceConsumedMicrocents)} of ${eur(s.spend.allowanceGrantMicrocents)} EUR used${s.spend.allowanceRemainingMicrocents != null ? ` · ${eur(s.spend.allowanceRemainingMicrocents)} EUR left` : ''} · overage ${s.spend.overageMode ?? 'unknown'}`);

package/dist/tools/embedding-status.test.js

@@ -57,7 +57,6 @@ describe('tools/embedding-status', () => {
         const text = result.content[0].text;
         expect(text).toContain('BILLING GATE');
         expect(text).toContain('allowance_exhausted');
-        // Contract guarantee: never vendor prose on any surface.
         expect(text).not.toContain('Key is blocked');
     });
     it('surfaces the spend state so agents can warn before the gate (ORB-1719)', async () => {

package/dist/tools/feedback.js

@@ -2,24 +2,12 @@
  * ORB-1910 - `orboto_report_feedback`: file a bug report / feedback / feature
  * request with the operator from inside the workspace (epic ORB-1907).
  *
- * Thin wrapper over the tenant relay (`POST /feedback`, ORB-1908): the
- * instance validates the closed schema, normalises the text and forwards
- * the report to the control plane with its own credential - this tool never
- * talks to the control plane and never learns the reporter's identity. It
- * checks `GET /feedback/availability` first so a self-hosted instance gets a
- * plain refusal naming the public issue tracker instead of a 503.
- *
- * The result carries the report id ONLY. The body is never echoed back into
- * the model's context: a report may quote hostile text (a bug reproduction
- * with an injected instruction), and re-reading it would be the one way this
- * tool could turn data into an instruction.
+ * @see ORB-1908
  */
 import { z } from 'zod';
 const PUBLIC_TRACKER = 'https://github.com/orboto/orboto-cli/issues';
 export const reportFeedbackToolConfig = {
     title: 'Send feedback or a bug report to the operator',
-    // ORB-1805 - kept short: every client pays for this text at connect;
-    // orboto_help serves the full contract (caps, attachment policy, privacy).
     description: 'File a bug report, feedback or feature request with the orboto operator from inside this workspace. Relayed without your identity; up to 3 png/jpeg/txt attachments (2 MB each, base64). Refused on self-hosted instances without an operator link. Answers with the report id only.',
     inputSchema: z.object({
         kind: z.enum(['bug', 'feedback', 'feature']),
@@ -37,8 +25,6 @@ export const reportFeedbackToolConfig = {
             contentBase64: z.string().min(1),
         })).max(3).optional(),
     }).shape,
-    // A write that creates one report on the operator side; nothing is
-    // removed or overwritten, and sending twice files two reports.
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeReportFeedbackHandler(client) {

package/dist/tools/feedback.test.js

@@ -56,7 +56,6 @@ describe('orboto_report_feedback', () => {
             attachments: [{ filename: 'a.txt', mimetype: 'text/plain', contentBase64: 'aGk=' }],
         });
         expect(result.structuredContent).toEqual({ reportId: 'rep-9', kind: 'bug', attachments: 1 });
-        // The body never comes back into the model's context.
         expect(JSON.stringify(result)).not.toContain('Ignore previous instructions');
     });
     it('refuses on an instance without an operator link and names the public tracker - no POST', async () => {

package/dist/tools/get-checklists.js

@@ -1,19 +1,7 @@
 /**
  * ORB-244 Phase B - `orboto_get_checklists`.
  *
- * Dedicated read tool for a ticket's checklists. Two callers want
- * this without paying for the full ticket payload:
- *
- *   1. Models asking "what's still unchecked on ACME-42?" - don't
- *      need description + comments + git activity for that.
- *   2. Phase-C write tools (`orboto_check` / `orboto_uncheck`) - the
- *      user usually wants to confirm the item exists before
- *      toggling it, and this tool is the cheap round-trip.
- *
- * ORB-234 detail exposed here: when a checklist item links to
- * another ticket, `effectiveCompleted` mirrors that ticket's status
- * category. We surface the linked ticket so the model can explain
- * "item is done because [ORB-99] shipped" rather than just "done".
+ * @see ORB-234, ORB-99
  */
 import { z } from 'zod';
 import { resolveTicketByKey } from './shared.js';
@@ -42,7 +30,8 @@ export function makeGetChecklistsHandler(client) {
                 const linkSuffix = i.linkedTicketKey
                     ? ` ↪ [${i.linkedTicketKey}] ${i.linkedTicketTitle ?? ''} (${i.linkedTicketStatusCategory ?? 'unknown'})`
                     : '';
-                lines.push(`- [${i.effectiveCompleted ? 'x' : ' '}] ${i.content}${linkSuffix}`);
+                const metaSuffix = `${i.assigneeName ? ` @${i.assigneeName}` : ''}${i.dueDate ? ` (due ${i.dueDate})` : ''}`;
+                lines.push(`- [${i.effectiveCompleted ? 'x' : ' '}] ${i.content}${linkSuffix}${metaSuffix}`);
             }
             lines.push('');
         }
@@ -59,6 +48,9 @@ export function makeGetChecklistsHandler(client) {
                         id: i.id,
                         content: i.content,
                         done: i.effectiveCompleted,
+                        assignedTo: i.assignedTo ?? null,
+                        assigneeName: i.assigneeName ?? null,
+                        dueDate: i.dueDate ?? null,
                         linkedTicket: i.linkedTicketKey ? {
                             key: i.linkedTicketKey,
                             title: i.linkedTicketTitle,

package/dist/tools/get-project-primer.js

@@ -1,27 +1,7 @@
 /**
  * ORB-408 (Phase 3 of ORB-406) - `orboto_get_project_primer`.
  *
- * Returns the project's auto-generated AI Context Pack as a single
- * markdown blob, token-budget aware. AI agents call this as their
- * first read per session.
- *
- * What's actually in the primer (ORB-563):
- *   - active milestones, ticket counts, recently-closed milestones
- *   - top docs from the project space
- * - structured project facts (the `primer_facts` table - workspace +
- *     project rows)
- *   - recent activity, when the operator enabled it
- *   - repo briefings (e.g. CLAUDE.md / AGENTS.md) ONLY when the
- *     operator configured `repoFiles` AND the API host has those files
- *     on its local filesystem. Most Coolify / SaaS deployments do
- *     neither - agents must NOT assume CLAUDE.md / AGENTS.md content
- *     is in the primer. If the team relies on CLAUDE.md / AGENTS.md
- *     content cross-deployment, those conventions belong in
- *     `primer_facts` instead.
- *
- * Sections that didn't make the budget come back in
- * `truncatedSections` so the agent can decide whether to bump the
- * budget for a follow-up call.
+ * @see ORB-563
  */
 import { z } from 'zod';
 import { resolveProjectByKey } from './shared.js';
@@ -42,10 +22,6 @@ export function makeGetProjectPrimerHandler(client) {
         if (maxTokens !== undefined)
             qs.set('max_tokens', String(maxTokens));
         const res = await client.get(`/projects/${project.id}/ai-primer?${qs.toString()}`);
-        // ORB-1104 - the trimmed-sections note is now appended in-band by
-        // assembleWithBudget, so res.markdown already carries it (and so do
-        // baked snapshots + the raw markdown route). No manual append here,
-        // otherwise it would double up.
         return {
             content: [
                 {