deepspace 0.20.0 → 0.22.0

package/dist/worker.js

@@ -351,6 +351,9 @@ var MSG = {
   CRON_PAUSE: "cron.pause",
   CRON_RESUME: "cron.resume",
   CRON_STATUS: "cron.status",
+  // Per-mutation receipt, sent only to the socket whose trigger/pause/
+  // resume carried a `requestId` — frames without one stay fire-and-forget.
+  CRON_ACK: "cron.ack",
   // ---- JobRoom ---------------------------------------------------------
   // Background-job queue with durable, alarm-driven execution. See
   // server/rooms/job-room.ts. Clients enqueue and subscribe to updates;
@@ -1063,9 +1066,9 @@ var clientBuild = {
   canvasUndo: () => ({ type: MSG.CANVAS_UNDO, payload: EMPTY }),
   canvasRedo: () => ({ type: MSG.CANVAS_REDO, payload: EMPTY }),
   // Cron
-  cronTrigger: (taskName) => ({ type: MSG.CRON_TRIGGER, payload: { taskName } }),
-  cronPause: (taskName) => ({ type: MSG.CRON_PAUSE, payload: { taskName } }),
-  cronResume: (taskName) => ({ type: MSG.CRON_RESUME, payload: { taskName } }),
+  cronTrigger: (taskName, requestId) => ({ type: MSG.CRON_TRIGGER, payload: { taskName, requestId } }),
+  cronPause: (taskName, requestId) => ({ type: MSG.CRON_PAUSE, payload: { taskName, requestId } }),
+  cronResume: (taskName, requestId) => ({ type: MSG.CRON_RESUME, payload: { taskName, requestId } }),
   // Jobs
   jobEnqueue: (requestId, type, payload, maxAttempts) => ({
     type: MSG.JOB_ENQUEUE,
@@ -1119,6 +1122,14 @@ var serverBuild = {
   cronTasks: (tasks) => ({ type: MSG.CRON_TASKS, payload: { tasks } }),
   cronHistory: (history) => ({ type: MSG.CRON_HISTORY, payload: { history } }),
   cronStatus: (tasks, recentHistory) => ({ type: MSG.CRON_STATUS, payload: { tasks, recentHistory } }),
+  cronAckSuccess: (requestId, taskName) => ({
+    type: MSG.CRON_ACK,
+    payload: { requestId, taskName, ok: true }
+  }),
+  cronAckFailure: (requestId, reason, error, taskName) => ({
+    type: MSG.CRON_ACK,
+    payload: { requestId, taskName, ok: false, reason, error }
+  }),
   // Jobs
   jobSnapshot: (jobs) => ({ type: MSG.JOB_UPDATE, payload: { kind: "snapshot", jobs } }),
   jobEnqueued: (job, requestId) => ({
@@ -3992,40 +4003,88 @@ var CronRoom = class extends BaseRoom {
   }
   async onMessage(ws, user, message) {
     this.ensureInitialized();
-    const { type, payload } = message;
+    const { type, payload = {} } = message;
     if (CRON_WRITE_TYPES.has(type) && !user.canWrite) {
-      this.sendTo(ws, {
-        type: MSG.ERROR,
-        payload: { error: "Write access denied: viewer role cannot modify cron tasks" }
+      const error = "Write access denied: viewer role cannot modify cron tasks";
+      this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+      this.ackMutation(ws, payload.requestId, {
+        ok: false,
+        taskName: payload.taskName,
+        reason: "read_only",
+        error
       });
       return;
     }
+    try {
+      await this.dispatchMessage(ws, type, payload);
+    } catch (error) {
+      try {
+        this.ackMutation(ws, payload.requestId, {
+          ok: false,
+          taskName: payload.taskName,
+          reason: "failed",
+          error: error instanceof Error ? error.message : String(error)
+        });
+      } catch {
+      }
+      throw error;
+    }
+  }
+  async dispatchMessage(ws, type, payload) {
     switch (type) {
       case MSG.CRON_TRIGGER: {
         const taskName = payload.taskName;
         if (!taskName) {
-          this.sendTo(ws, { type: MSG.ERROR, payload: { error: "Missing taskName" } });
+          const error = "Missing taskName";
+          this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+          this.ackMutation(ws, payload.requestId, { ok: false, reason: "failed", error });
           return;
         }
-        if (!await this.executeTask(taskName)) {
-          this.sendTo(ws, {
-            type: MSG.ERROR,
-            payload: { error: `Unknown cron task: ${taskName}` }
+        const execution = await this.executeTask(taskName);
+        if (!execution) {
+          const error = `Unknown cron task: ${taskName}`;
+          this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+          this.ackMutation(ws, payload.requestId, {
+            ok: false,
+            taskName,
+            reason: "unknown_task",
+            error
           });
+          break;
         }
+        this.ackMutation(
+          ws,
+          payload.requestId,
+          execution.success ? { ok: true, taskName } : { ok: false, taskName, reason: "failed", error: execution.error }
+        );
         break;
       }
-      case MSG.CRON_PAUSE: {
-        const taskName = payload.taskName;
-        this.sql.exec(`UPDATE cron_tasks SET paused = 1 WHERE name = ?`, taskName);
-        this.broadcastStatus();
-        break;
-      }
+      case MSG.CRON_PAUSE:
       case MSG.CRON_RESUME: {
         const taskName = payload.taskName;
-        this.sql.exec(`UPDATE cron_tasks SET paused = 0 WHERE name = ?`, taskName);
-        this.scheduleNextAlarm();
+        if (!taskName) {
+          const error = "Missing taskName";
+          this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+          this.ackMutation(ws, payload.requestId, { ok: false, reason: "failed", error });
+          return;
+        }
+        const known = this.sql.exec(`SELECT name FROM cron_tasks WHERE name = ?`, taskName).toArray().length > 0;
+        if (!known) {
+          const error = `Unknown cron task: ${taskName}`;
+          this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+          this.ackMutation(ws, payload.requestId, {
+            ok: false,
+            taskName,
+            reason: "unknown_task",
+            error
+          });
+          break;
+        }
+        const paused = type === MSG.CRON_PAUSE;
+        this.sql.exec(`UPDATE cron_tasks SET paused = ? WHERE name = ?`, paused ? 1 : 0, taskName);
+        if (!paused) this.scheduleNextAlarm();
         this.broadcastStatus();
+        this.ackMutation(ws, payload.requestId, { ok: true, taskName });
         break;
       }
       case MSG.CRON_TASKS: {
@@ -4068,7 +4127,7 @@ var CronRoom = class extends BaseRoom {
   // ==========================================================================
   async executeTask(taskName) {
     const taskRow = this.sql.exec(`SELECT interval_minutes, schedule, timezone FROM cron_tasks WHERE name = ?`, taskName).toArray()[0];
-    if (!taskRow) return false;
+    if (!taskRow) return null;
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const start = Date.now();
     let success = true;
@@ -4104,7 +4163,7 @@ var CronRoom = class extends BaseRoom {
       `DELETE FROM cron_history WHERE id NOT IN (SELECT id FROM cron_history ORDER BY id DESC LIMIT 500)`
     );
     this.broadcastStatus();
-    return true;
+    return { taskName, startedAt, completedAt, success, durationMs, error };
   }
   // ==========================================================================
   // Scheduling
@@ -4174,6 +4233,21 @@ var CronRoom = class extends BaseRoom {
       }
     });
   }
+  /**
+   * Receipt for a mutation frame, addressed only to its sender. Receipts
+   * are opt-in by correlation id: frames without a `requestId` keep the
+   * fire-and-forget contract, so the (untyped) `requestId` from the wire
+   * is the single gate here rather than a check at every call site.
+   * Frames go through the shared `serverBuild` constructors so the wire
+   * shape is enforced by the protocol types, not re-spelled here.
+   */
+  ackMutation(ws, requestId, result) {
+    if (typeof requestId !== "string") return;
+    this.sendTo(
+      ws,
+      result.ok ? serverBuild.cronAckSuccess(requestId, result.taskName) : serverBuild.cronAckFailure(requestId, result.reason, result.error, result.taskName)
+    );
+  }
 };
 function computeNextRunAt(task, from) {
   if (task.interval_minutes) {
@@ -6022,6 +6096,32 @@ var REGISTRY_INSTANCE = "v1:global";
 var APP_ID_RE = /^app_[0-9A-HJKMNP-TV-Z]{26}$/;
 var STRICT_APP_ID_RE = APP_ID_RE;
 var RESOURCE_ID_RE = /^(app_[0-9A-HJKMNP-TV-Z]{26}|[a-z0-9][a-z0-9_-]{0,63})$/;
+var CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function mintUlid(now = Date.now()) {
+  let ts = "";
+  let t = now;
+  for (let i = 0; i < 10; i++) {
+    ts = CROCKFORD[t % 32] + ts;
+    t = Math.floor(t / 32);
+  }
+  const rand = new Uint8Array(10);
+  crypto.getRandomValues(rand);
+  let rs = "";
+  let acc = 0;
+  let bits = 0;
+  for (const byte of rand) {
+    acc = acc << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      rs += CROCKFORD[acc >> bits & 31];
+    }
+  }
+  return `${ts}${rs}`.slice(0, 26);
+}
+function mintAppId(now = Date.now()) {
+  return `app_${mintUlid(now)}`;
+}
 var RegistryClientError = class extends Error {
   constructor(message, code, status) {
     super(message);
@@ -6622,6 +6722,9 @@ function declaredLength(request, what) {
 function isKeyWithinScope(key, prefix, excludedPrefixes) {
   return key.startsWith(prefix) && !excludedPrefixes.some((excluded) => key.startsWith(excluded));
 }
+function scopeRelativeKey(key, prefix) {
+  return key.slice(prefix.length);
+}
 function anchorKey(raw, prefix, excludedPrefixes) {
   const safe = sanitizeSubpath(raw);
   if (safe === null) return fail2(400, "Invalid key: traversal not allowed", "invalid_key");
@@ -6821,7 +6924,7 @@ async function handleUpload(request, url, bucket, prefix, excludedPrefixes, auth
       admission.markerKey,
       admission.markerKey !== null || fileData.byteLength < replacedBytes
     );
-    return storedFileJson(located.key, fileName, url, scope);
+    return storedFileJson(located.key, prefix, fileName, url, scope);
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Upload failed";
     console.error("[handleUpload] Error:", msg, err instanceof Error ? err.stack : "");
@@ -6843,11 +6946,17 @@ function fileMetadata(fileName, userId, reservationId, declaredBytes) {
     uploadedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-function storedFileJson(key, name, url, scope) {
+function storedFileJson(key, prefix, name, url, scope) {
   const fileUrl = new URL(`/api/files/${encodeKeyPath(key)}`, url.origin);
   fileUrl.searchParams.set("scope", scope);
   return Response.json(
-    { success: true, key, url: fileUrl.toString(), name },
+    {
+      success: true,
+      key,
+      relativeKey: scopeRelativeKey(key, prefix),
+      url: fileUrl.toString(),
+      name
+    },
     { headers: CORS_HEADERS4 }
   );
 }
@@ -7127,7 +7236,7 @@ async function completedReservationObject(bucket, session) {
   const object = await bucket.head(session.key);
   return object?.customMetadata?.reservationId === session.reservationId ? object : null;
 }
-async function finishCompletedMultipart(bucket, session, reservation, object, auth, url, scope) {
+async function finishCompletedMultipart(bucket, session, reservation, object, auth, url, scope, prefix) {
   const declaredMetadata = Number(object.customMetadata?.declaredBytes);
   const declaredBytes = reservation?.declaredBytes ?? (Number.isSafeInteger(declaredMetadata) && declaredMetadata >= 0 ? declaredMetadata : MAX_APP_FILE_BYTES);
   const refusal = overCeiling(object.size) ?? (object.size > declaredBytes ? fail2(
@@ -7161,7 +7270,7 @@ async function finishCompletedMultipart(bucket, session, reservation, object, au
     }
   }
   const name = object.customMetadata?.originalName ?? session.uploadKey.split("/").pop() ?? "file";
-  return storedFileJson(session.key, name, url, scope);
+  return storedFileJson(session.key, prefix, name, url, scope);
 }
 async function multipartComplete(request, url, bucket, prefix, excludedPrefixes, auth, scope) {
   const body = await readControlJson(request);
@@ -7182,7 +7291,7 @@ async function multipartComplete(request, url, bucket, prefix, excludedPrefixes,
   if (auth.storage && !reservation) {
     const completed = await completedReservationObject(bucket, session);
     if (completed) {
-      return finishCompletedMultipart(bucket, session, null, completed, auth, url, scope);
+      return finishCompletedMultipart(bucket, session, null, completed, auth, url, scope, prefix);
     }
     await abandonMultipart(bucket, session, auth, null);
     return quotaUnavailable("This upload reservation is missing or does not match.");
@@ -7221,14 +7330,23 @@ async function multipartComplete(request, url, bucket, prefix, excludedPrefixes,
   } catch (error) {
     const completed = await completedReservationObject(bucket, session);
     if (completed) {
-      return finishCompletedMultipart(bucket, session, reservation, completed, auth, url, scope);
+      return finishCompletedMultipart(
+        bucket,
+        session,
+        reservation,
+        completed,
+        auth,
+        url,
+        scope,
+        prefix
+      );
     }
     if (r2ErrorCode(error) === 10024 && reservation) {
       await releaseQuotaMarker(bucket, auth.storage, reservation.key, true);
     }
     return multipartFailure(error);
   }
-  return finishCompletedMultipart(bucket, session, reservation, object, auth, url, scope);
+  return finishCompletedMultipart(bucket, session, reservation, object, auth, url, scope, prefix);
 }
 async function multipartAbort(url, bucket, prefix, excludedPrefixes, auth) {
   const session = resolveSession(url, prefix, excludedPrefixes);
@@ -7248,37 +7366,49 @@ async function handleList(bucket, prefix, excludedPrefixes, url, scope, auth) {
   const listPrefix = `${prefix}${userPrefix}`;
   const requestedLimit = Number(url.searchParams.get("limit") ?? 100);
   const limit = Number.isSafeInteger(requestedLimit) ? Math.min(1e3, Math.max(1, requestedLimit)) : 100;
+  const requestCursor = url.searchParams.get("cursor");
   if (excludedPrefixes.some((excluded) => listPrefix.startsWith(excluded))) {
     return Response.json({ files: [], truncated: false }, { headers: CORS_HEADERS4 });
   }
-  const listed = await bucket.list({ prefix: listPrefix, limit });
+  const withMetadata = (options) => ({ ...options, include: ["customMetadata"] });
+  const listed = await bucket.list(
+    withMetadata({
+      prefix: listPrefix,
+      limit,
+      ...requestCursor ? { cursor: requestCursor } : {}
+    })
+  );
   const visible = listed.objects.filter(
     (object) => isKeyWithinScope(object.key, prefix, excludedPrefixes)
   );
   const seen = new Set(visible.map((object) => object.key));
-  let truncated = listed.truncated;
-  for (const excluded of excludedPrefixes.filter((candidate) => candidate.startsWith(listPrefix))) {
-    if (visible.length >= limit) break;
+  let frontier = listed;
+  let frontierKey = listed.objects.at(-1)?.key;
+  for (const excluded of excludedPrefixes.filter((candidate) => candidate.startsWith(listPrefix)).sort()) {
+    if (!frontier.truncated || visible.length >= limit) break;
     const excludedEnd = `${excluded}\u{10FFFF}`;
-    const lastListedKey = listed.objects.at(-1)?.key;
-    const after = await bucket.list({
-      prefix: listPrefix,
-      startAfter: lastListedKey && lastListedKey > excludedEnd ? lastListedKey : excludedEnd,
-      limit: limit - visible.length
-    });
+    const after = await bucket.list(
+      withMetadata({
+        prefix: listPrefix,
+        startAfter: frontierKey && frontierKey > excludedEnd ? frontierKey : excludedEnd,
+        limit: limit - visible.length
+      })
+    );
     for (const object of after.objects) {
       if (!seen.has(object.key) && isKeyWithinScope(object.key, prefix, excludedPrefixes)) {
         seen.add(object.key);
         visible.push(object);
       }
     }
-    truncated = after.truncated;
+    frontierKey = after.objects.at(-1)?.key ?? frontierKey;
+    frontier = after;
   }
   const files = visible.slice(0, limit).map((obj) => {
     const fileUrl = new URL(`/api/files/${encodeKeyPath(obj.key)}`, url.origin);
     fileUrl.searchParams.set("scope", scope);
     return {
       key: obj.key,
+      relativeKey: scopeRelativeKey(obj.key, prefix),
       size: obj.size,
       uploaded: obj.uploaded.toISOString(),
       url: fileUrl.toString(),
@@ -7293,7 +7423,12 @@ async function handleList(bucket, prefix, excludedPrefixes, url, scope, auth) {
     if (storage && limitBytes !== null) storage.limitBytes = limitBytes;
   }
   return Response.json(
-    { files, truncated, ...storage ? { storage } : {} },
+    {
+      files,
+      truncated: frontier.truncated,
+      ...frontier.truncated ? { cursor: frontier.cursor } : {},
+      ...storage ? { storage } : {}
+    },
     { headers: CORS_HEADERS4 }
   );
 }
@@ -8593,7 +8728,8 @@ function searchDocumentationCorpus(corpus, query, limit = 6) {
       title: chunk.title,
       ...chunk.heading ? { heading: chunk.heading } : {},
       excerpt: excerpt(chunk.text, terms),
-      score
+      score,
+      termCoverage: matchedTerms / terms.length
     };
   }).filter((result) => result.score > 0).sort((left, right) => right.score - left.score || left.route.localeCompare(right.route)).slice(0, Math.max(1, Math.min(limit, 10)));
 }
@@ -8713,6 +8849,25 @@ function excerpt(text, terms) {
   return `${start > 0 ? "\u2026" : ""}${text.slice(start, end).trim()}${end < text.length ? "\u2026" : ""}`;
 }
 
+// src/documentation/text.ts
+function slugify(value) {
+  return value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function documentationSubject(name) {
+  const normalized = name.trim();
+  if (!normalized || /^documentation$/i.test(normalized)) return "documentation";
+  return /(?:\bdocs?|documentation)$/i.test(normalized) ? normalized : `${normalized} documentation`;
+}
+function createSlugger(fallback = "section") {
+  const seen = /* @__PURE__ */ new Map();
+  return (value) => {
+    const base = slugify(value) || fallback;
+    const count = seen.get(base) ?? 0;
+    seen.set(base, count + 1);
+    return count === 0 ? base : `${base}-${count + 1}`;
+  };
+}
+
 // src/documentation/worker/published-corpus.ts
 var cachedCorpus;
 async function loadDocumentationPublishedManifest(env, requestUrl = "https://assets.local/", assetBasePath = "/_documentation") {
@@ -8770,7 +8925,7 @@ async function resolveDocumentationPublishedCorpus(env, sourceHash, requestUrl =
 }
 async function readDocumentationPublishedPage(env, corpus, requestedRoute, requestUrl = "https://assets.local/", assetBasePath = "/_documentation") {
   const route = collapseRoute(requestedRoute.split("#", 1)[0] ?? "/");
-  const firstChunk = corpus.find((chunk) => chunk.route === route);
+  const firstChunk = corpus.find((chunk) => (chunk.route.split("#", 1)[0] ?? "") === route);
   if (!firstChunk) return null;
   const pathname = route === "/" ? `${assetBasePath}/index.md` : `${assetBasePath}${route}.md`;
   const response = await env.ASSETS.fetch(new Request(new URL(pathname, requestUrl)));
@@ -8779,6 +8934,36 @@ async function readDocumentationPublishedPage(env, corpus, requestedRoute, reque
   if (markdown.length > 5e5) throw new Error("Documentation page exceeds 500000 characters");
   return { route, title: firstChunk.title, markdown };
 }
+function documentationPageSection(markdown, fragment) {
+  const target = slugify(fragment);
+  if (!target) return null;
+  const slug = createSlugger();
+  const lines = markdown.split("\n");
+  let fence = null;
+  let start = -1;
+  let startDepth = 0;
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index] ?? "";
+    const fenceMarker = line.match(/^ {0,3}(`{3,}|~{3,})/)?.[1];
+    if (fenceMarker && !fence) {
+      fence = fenceMarker;
+      continue;
+    }
+    if (fence) {
+      if (fenceMarker?.startsWith(fence)) fence = null;
+      continue;
+    }
+    const heading = line.match(/^ {0,3}(#{1,6})\s+(.+)$/);
+    if (!heading) continue;
+    const depth = (heading[1] ?? "").length;
+    if (start !== -1 && depth <= startDepth) return lines.slice(start, index).join("\n").trim();
+    if (start === -1 && slug(heading[2] ?? "") === target) {
+      start = index;
+      startDepth = depth;
+    }
+  }
+  return start === -1 ? null : lines.slice(start).join("\n").trim();
+}
 function parseAssistantPolicy(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const policy = value;
@@ -9028,6 +9213,17 @@ function registerDocumentationStaticRoutes(app, publicBasePath = "/docs", assetB
       status = 404;
     }
     if (status === 404) {
+      if (pathname.endsWith(".md")) {
+        return secureDocumentationResponse(
+          new Response(
+            `No documentation page at ${pathname}. See ${publicBasePath}/llms.txt for every published page.
+`,
+            { status: 404, headers: { "Content-Type": "text/plain; charset=utf-8" } }
+          ),
+          404,
+          pathname
+        );
+      }
       const url = new URL(c.req.url);
       url.pathname = `${assetBasePath}/404.html`;
       response = await fetchDocumentationAsset(c.env, c.req.raw, url, assetBasePath);
@@ -9085,13 +9281,6 @@ function secureDocumentationResponse(response, status, pathname) {
   return new Response(response.body, { status, headers });
 }
 
-// src/documentation/text.ts
-function documentationSubject(name) {
-  const normalized = name.trim();
-  if (!normalized || /^documentation$/i.test(normalized)) return "documentation";
-  return /(?:\bdocs?|documentation)$/i.test(normalized) ? normalized : `${normalized} documentation`;
-}
-
 // src/documentation/worker/mcp/protocol.ts
 var MCP_SERVER_VERSION = "1.0.0";
 var CURRENT_PROTOCOL_VERSION = "2025-11-25";
@@ -9203,7 +9392,7 @@ var DOCUMENTATION_TOOLS = [
     },
     outputSchema: {
       type: "object",
-      properties: { results: { type: "array" } },
+      properties: { notice: { type: "string" }, results: { type: "array" } },
       required: ["results"]
     },
     annotations: {
@@ -9216,11 +9405,11 @@ var DOCUMENTATION_TOOLS = [
   {
     name: "documentation_read",
     title: "Read documentation page",
-    description: "Read one complete published documentation page as Markdown.",
+    description: "Read one published documentation page as Markdown. The route may omit the leading slash, and a #fragment (as returned by documentation_search) narrows the result to that heading section; an unknown fragment returns the whole page with a notice.",
     inputSchema: {
       type: "object",
       properties: {
-        route: { type: "string", minLength: 1, maxLength: 500, pattern: "^/" }
+        route: { type: "string", minLength: 1, maxLength: 500 }
       },
       required: ["route"],
       additionalProperties: false
@@ -9228,6 +9417,7 @@ var DOCUMENTATION_TOOLS = [
     outputSchema: {
       type: "object",
       properties: {
+        notice: { type: "string" },
         route: { type: "string" },
         title: { type: "string" },
         url: { type: "string" },
@@ -9254,19 +9444,24 @@ async function callDocumentationTool(rawRequest, request, corpus, env, basePath
     if (query.length < 2 || query.length > 300 || !Number.isInteger(limit) || Number(limit) < 1 || Number(limit) > 10) {
       return mcpError(request.id, -32602, "Invalid documentation_search arguments");
     }
-    const value = {
-      results: searchDocumentationCorpus(corpus, query, Number(limit)).map((result) => ({
-        ...result,
-        url: new URL(documentationPublicPath(basePath, result.route), origin).toString()
-      }))
-    };
-    return toolResult(request.id, value);
+    const results = searchDocumentationCorpus(corpus, query, Number(limit)).map((result) => ({
+      ...result,
+      url: new URL(documentationPublicPath(basePath, result.route), origin).toString()
+    }));
+    return toolResult(request.id, {
+      ...results[0]?.termCoverage === 1 ? {} : {
+        notice: "No section matches every search term \u2014 the topic may be absent or spread across sections."
+      },
+      results
+    });
   }
   if (name === "documentation_read") {
     const route = typeof args.route === "string" ? args.route.trim() : "";
-    if (!route.startsWith("/") || route.length > 500) {
+    if (!route || route.length > 500) {
       return mcpError(request.id, -32602, "Invalid documentation_read arguments");
     }
+    const hash = route.indexOf("#");
+    const fragment = hash === -1 ? "" : route.slice(hash + 1);
     try {
       const page = await readDocumentationPublishedPage(
         env,
@@ -9276,8 +9471,11 @@ async function callDocumentationTool(rawRequest, request, corpus, env, basePath
         assetBasePath
       );
       if (!page) return toolError(request.id, `No published documentation page exists at ${route}`);
+      const section = fragment ? documentationPageSection(page.markdown, fragment) : null;
       return toolResult(request.id, {
+        ...fragment && section === null ? { notice: `The fragment #${fragment} was not found; returning the whole page.` } : {},
         ...page,
+        ...section === null ? {} : { markdown: section },
         url: new URL(documentationPublicPath(basePath, page.route), origin).toString()
       });
     } catch (error) {
@@ -10085,6 +10283,8 @@ export {
   meterAi,
   meterUsage,
   meterVectorize,
+  mintAppId,
+  mintUlid,
   noopPermissionContext,
   parseQuotaLimit,
   platformCorsPatterns,