deepspace 0.10.0 → 0.10.2

package/dist/worker.js

@@ -340,16 +340,6 @@ var ROLE_ANONYMOUS = "viewer";
 var ROLE_DEFAULT = "member";
 var ROLE_ADMIN = "admin";
 
-// src/shared/users-schema.ts
-var USERS_COLUMNS = [
-  { name: "email", storage: "text", interpretation: "plain" },
-  { name: "name", storage: "text", interpretation: "plain" },
-  { name: "imageUrl", storage: "text", interpretation: "plain" },
-  { name: "role", storage: "text", interpretation: "plain" },
-  { name: "createdAt", storage: "text", interpretation: { kind: "datetime" } },
-  { name: "lastSeenAt", storage: "text", interpretation: { kind: "datetime" } }
-];
-
 // src/server/schemas/registry.ts
 function collectionTableName(name) {
   return `c_${name.replace(/[^a-zA-Z0-9_]/g, "_")}`;
@@ -550,6 +540,14 @@ var SYSTEM_MANAGED_COLUMNS = /* @__PURE__ */ new Set([
   "createdAt",
   "lastSeenAt"
 ]);
+var USERS_COLUMNS = [
+  { name: "email", storage: "text", interpretation: "plain" },
+  { name: "name", storage: "text", interpretation: "plain" },
+  { name: "imageUrl", storage: "text", interpretation: "plain" },
+  { name: "role", storage: "text", interpretation: "plain" },
+  { name: "createdAt", storage: "text", interpretation: { kind: "datetime" } },
+  { name: "lastSeenAt", storage: "text", interpretation: { kind: "datetime" } }
+];
 var BASE_USERS_SCHEMA = {
   name: "users",
   columns: [...USERS_COLUMNS],
@@ -5107,7 +5105,8 @@ var ALLOWED_BINDING_TYPES = /* @__PURE__ */ new Set([
   "queue",
   "browser_rendering",
   "analytics_engine",
-  "hyperdrive"
+  "hyperdrive",
+  "ratelimit"
 ]);
 var RESERVED_BINDING_NAMES = /* @__PURE__ */ new Set([
   "ASSETS",
@@ -5115,6 +5114,7 @@ var RESERVED_BINDING_NAMES = /* @__PURE__ */ new Set([
   "API_WORKER",
   "DEEPSPACE_APP_ID",
   "DEEPSPACE_RESOURCE_ID",
+  "DEEPSPACE_RELEASE_OPERATION_ID",
   "APP_NAME",
   "OWNER_USER_ID",
   "AUTH_JWT_PUBLIC_KEY",
@@ -5205,6 +5205,17 @@ function requiredFieldError(b) {
         return `hyperdrive binding "${b.name}": auto-provisioning not yet supported (provide a real id)`;
       }
       return null;
+    case "ratelimit":
+      if (!/^\d+$/u.test(b.namespace_id) || Number(b.namespace_id) <= 0) {
+        return `ratelimit binding "${b.name}" requires a positive integer namespace_id string`;
+      }
+      if (!Number.isInteger(b.simple?.limit) || b.simple.limit <= 0) {
+        return `ratelimit binding "${b.name}" requires simple.limit (positive integer)`;
+      }
+      if (b.simple.period !== 10 && b.simple.period !== 60) {
+        return `ratelimit binding "${b.name}" requires simple.period (10 or 60)`;
+      }
+      return null;
     case "ai":
     case "browser_rendering":
     case "analytics_engine":
@@ -5282,6 +5293,15 @@ function bindingManifestFromOutputConfig(outputConfig) {
     const id = pluckString(h, "id");
     if (name && id) out.push({ type: "hyperdrive", name, id });
   }
+  for (const r of asObjectArray(outputConfig.ratelimits)) {
+    const name = pluckString(r, "name");
+    const namespace_id = pluckString(r, "namespace_id");
+    const simple = isObject(r.simple) ? r.simple : null;
+    const limit = pluckNumber(simple, "limit");
+    const period = pluckNumber(simple, "period");
+    if (!name || !namespace_id || limit === null || period !== 10 && period !== 60) continue;
+    out.push({ type: "ratelimit", name, namespace_id, simple: { limit, period } });
+  }
   return out;
 }
 function isObject(v) {
@@ -6026,8 +6046,8 @@ function validateAppMigrationIds(value) {
 
 // src/shared/ai-models.ts
 var DEEPSPACE_MODEL_CATALOG_PROVENANCE = {
-  version: "2026-08-03",
-  verifiedAt: "2026-08-03",
+  version: "2026-08-04",
+  verifiedAt: "2026-08-04",
   sources: {
     anthropic: "https://platform.claude.com/docs/en/api/beta/models/list",
     openai: "https://developers.openai.com/api/docs/models/all",
@@ -6118,7 +6138,8 @@ var DEEPSPACE_AGENT_PROFILES = {
   application: {
     id: "application",
     defaultModel: DEEPSPACE_AI_DEFAULTS.agent,
-    maxSteps: 5,
+    maxSteps: 21,
+    maxToolCalls: 20,
     allowedTools: "application-defined"
   },
   documentation: {
@@ -6128,7 +6149,7 @@ var DEEPSPACE_AGENT_PROFILES = {
     // step. The runner disables tools once the tool-call budget is exhausted.
     maxSteps: 21,
     maxToolCalls: 20,
-    allowedTools: ["docs_search", "docs_read"]
+    allowedTools: ["documentation_search", "documentation_read"]
   }
 };
 function getDeepSpaceAIModel(modelId) {
@@ -6149,45 +6170,6 @@ function resolveDeepSpaceAgentModel(modelId, profileId = "application") {
   return { modelId: model.id, provider: model.provider, model, profile };
 }
 
-// src/shared/docs-routing.ts
-var DOCS_RESOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
-  "7z",
-  "avif",
-  "css",
-  "csv",
-  "gif",
-  "gz",
-  "ico",
-  "jpeg",
-  "jpg",
-  "js",
-  "json",
-  "map",
-  "md",
-  "mjs",
-  "mp3",
-  "mp4",
-  "pdf",
-  "png",
-  "svg",
-  "tar",
-  "txt",
-  "wasm",
-  "webm",
-  "webp",
-  "woff",
-  "woff2",
-  "xml",
-  "yaml",
-  "yml",
-  "zip"
-]);
-function isDocsResourcePath(pathname) {
-  const leaf = pathname.slice(pathname.lastIndexOf("/") + 1);
-  const extension = leaf.includes(".") ? leaf.slice(leaf.lastIndexOf(".") + 1).toLowerCase() : "";
-  return extension !== "" && DOCS_RESOURCE_EXTENSIONS.has(extension);
-}
-
 // src/server/utils/cors.ts
 function matchOrigin(origin, patterns) {
   if (!origin) return null;
@@ -6732,11 +6714,7 @@ function streamDeepSpaceAgent(env, options) {
       }
     }
   }
-  const provider = createDeepSpaceAI(
-    env,
-    selection.provider,
-    authToken ? { authToken } : {}
-  );
+  const provider = createDeepSpaceAI(env, selection.provider, authToken ? { authToken } : {});
   const { prepareStep, tools, ...remainingStreamOptions } = streamOptions;
   const boundedTools = limitToolExecutions(tools, selection.profile.maxToolCalls);
   const result = streamText({
@@ -6764,22 +6742,27 @@ function enforceToolCallLimit(prepareStep, maxToolCalls) {
 function limitToolExecutions(tools, maxToolCalls) {
   if (!tools || maxToolCalls === void 0) return tools;
   let executions = 0;
-  return Object.fromEntries(Object.entries(tools).map(([name, definition]) => {
-    if (typeof definition.execute !== "function") return [name, definition];
-    const execute = definition.execute;
-    return [name, {
-      ...definition,
-      execute: (...args) => {
-        if (executions >= maxToolCalls) {
-          return Promise.resolve({
-            error: `The agent tool-call limit of ${maxToolCalls} has been reached`
-          });
+  return Object.fromEntries(
+    Object.entries(tools).map(([name, definition]) => {
+      if (typeof definition.execute !== "function") return [name, definition];
+      const execute = definition.execute;
+      return [
+        name,
+        {
+          ...definition,
+          execute: (...args) => {
+            if (executions >= maxToolCalls) {
+              return Promise.resolve({
+                error: `The agent tool-call limit of ${maxToolCalls} has been reached`
+              });
+            }
+            executions++;
+            return execute(...args);
+          }
         }
-        executions++;
-        return execute(...args);
-      }
-    }];
-  }));
+      ];
+    })
+  );
 }
 function deepSpaceAgentErrorSummary(error, context = {}) {
   const details = [];
@@ -6844,7 +6827,10 @@ function safeLogText(value) {
     const codePoint = character.codePointAt(0) ?? 0;
     return codePoint <= 31 || codePoint === 127 ? " " : character;
   }).join("");
-  return withoutControlCharacters.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]").replace(/\b(api[_ -]?key|authorization|password|secret|token)\b\s*[:=]\s*\S+/gi, "$1=[redacted]").trim().slice(0, 300);
+  return withoutControlCharacters.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]").replace(
+    /\b(api[_ -]?key|authorization|password|secret|token)\b\s*[:=]\s*\S+/gi,
+    "$1=[redacted]"
+  ).trim().slice(0, 300);
 }
 
 // src/server/utils/composio-tools.ts
@@ -7283,11 +7269,10 @@ function formatTranscript(messages) {
 }
 function makeDefaultSummarizer(env, options = {}) {
   return async (messages) => {
-    const model = getDeepSpaceAIModel(DEEPSPACE_AI_DEFAULTS.summarization);
-    if (!model) throw new Error("DeepSpace summarization model is missing from the catalog");
-    const provider = createDeepSpaceAI(env, model.provider, { authToken: options.authToken });
+    const anthropic = createDeepSpaceAI(env, "anthropic", { authToken: options.authToken });
     const { text } = await generateText({
-      model: provider(model.id),
+      // Stable alias — provider bug-fix snapshots roll forward without code change.
+      model: anthropic("claude-haiku-4-5"),
       // 2500 gives the model room to finish a sentence after hitting the
       // "under 2000 tokens" soft limit in the prompt.
       maxOutputTokens: 2500,
@@ -7423,9 +7408,189 @@ async function appendMessage(stub, msg) {
   });
 }
 
-// src/server/utils/docs-assistant.ts
+// src/server/utils/metering.ts
+function meterUsage(env, kind, fields = {}) {
+  const ds = env.USAGE_EVENTS;
+  if (!ds) return false;
+  try {
+    ds.writeDataPoint({
+      indexes: [env.OWNER_USER_ID ?? "unknown"],
+      blobs: [
+        env.DEEPSPACE_RESOURCE_ID ?? env.APP_NAME ?? "unknown",
+        kind,
+        fields.id ?? "",
+        fields.op ?? ""
+      ],
+      doubles: [fields.units ?? 0, fields.count ?? 0]
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function meterAi(env, model, fields = {}) {
+  const calls = fields.calls ?? 1;
+  const inChars = fields.inputChars ?? 0;
+  const outChars = fields.outputChars ?? 0;
+  let ok = true;
+  if (inChars > 0) {
+    ok = meterUsage(env, "ai", { id: model, op: "input", units: inChars, count: calls }) && ok;
+  }
+  if (outChars > 0) {
+    ok = meterUsage(env, "ai", { id: model, op: "output", units: outChars, count: calls }) && ok;
+  }
+  if (inChars === 0 && outChars === 0) {
+    ok = meterUsage(env, "ai", { id: model, op: "call", units: 0, count: calls }) && ok;
+  }
+  return ok;
+}
+function meterVectorize(env, indexName, op, fields = {}) {
+  const vectors = fields.vectors ?? 0;
+  const dims = fields.dims ?? 0;
+  const stored = fields.storedCount ?? 0;
+  const units = op === "query" ? (vectors + stored) * dims : vectors * dims;
+  return meterUsage(env, "vectorize", { id: indexName, op, units, count: vectors });
+}
+var CHARS_PER_TOKEN = 4;
+var AI_EMBED_USD_PER_M_TOKENS = 0.012;
+var VECTORIZE_QUERIED_USD_PER_M_DIMS = 0.01;
+var VECTORIZE_STORED_USD_PER_100M_DIMS = 0.05;
+var COST_RATES = {
+  ai: {
+    /**
+     * USD per character of *embedding input* (bge-m3 / qwen3-embedding tier).
+     * Renamed from `perChar` to make explicit that this rate does NOT
+     * apply to LLM-generation output — see `priceBindingUsageEvent`.
+     */
+    embedInputPerChar: AI_EMBED_USD_PER_M_TOKENS / 1e6 / CHARS_PER_TOKEN
+  },
+  vectorize: {
+    /** USD per queried dimension (per query, per stored vector compared). */
+    queriedPerDim: VECTORIZE_QUERIED_USD_PER_M_DIMS / 1e6,
+    /** USD per stored dimension per month. */
+    storedPerDimPerMonth: VECTORIZE_STORED_USD_PER_100M_DIMS / 1e8
+  }
+};
+function priceBindingUsageEvent(kind, op, units) {
+  if (kind === "ai" && op === "input") {
+    return units * COST_RATES.ai.embedInputPerChar;
+  }
+  if (kind === "vectorize" && op === "query") {
+    return units * COST_RATES.vectorize.queriedPerDim;
+  }
+  return 0;
+}
+
+// src/server/utils/d1-migrations.ts
+var META_TABLE = "_dpc_migrations";
+var META_BOOTSTRAP_SQL = `CREATE TABLE IF NOT EXISTS ${META_TABLE} (idx INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)`;
+async function runMigrations(db, migrations) {
+  await db.prepare(META_BOOTSTRAP_SQL).run();
+  const row = await db.prepare(`SELECT COUNT(*) AS n FROM ${META_TABLE}`).first();
+  const fromVersion = row?.n ?? 0;
+  if (fromVersion >= migrations.length) {
+    return { fromVersion, toVersion: fromVersion, applied: 0 };
+  }
+  let current = fromVersion;
+  for (let i = fromVersion; i < migrations.length; i++) {
+    const statements = splitStatements(migrations[i]);
+    for (const stmt of statements) {
+      try {
+        await db.prepare(stmt).run();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Migration ${i} failed (db at version=${current}): ${msg}`);
+      }
+    }
+    await db.prepare(`INSERT INTO ${META_TABLE} (idx, applied_at) VALUES (?, ?)`).bind(i, (/* @__PURE__ */ new Date()).toISOString()).run();
+    current = i + 1;
+  }
+  return { fromVersion, toVersion: current, applied: current - fromVersion };
+}
+function splitStatements(sql) {
+  return sql.split(";").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+// src/documentation/worker/routes.ts
+import { Hono } from "hono";
+
+// src/documentation/resource-path.ts
+function canonicalNativeDocumentationRequestPath(pathname) {
+  try {
+    return pathname.split("/").map((segment) => encodeURIComponent(decodeURIComponent(segment))).join("/");
+  } catch {
+    return null;
+  }
+}
+
+// src/documentation/worker/assistant.ts
 import { tool as tool2 } from "ai";
 import { z } from "zod/v4";
+
+// src/documentation/types.ts
+var DOCUMENTATION_MANIFEST_VERSION = 2;
+var DocumentationError = class extends Error {
+  code;
+  diagnostics;
+  constructor(message, code, diagnostics = []) {
+    super(message);
+    this.name = "DocumentationError";
+    this.code = code;
+    this.diagnostics = diagnostics;
+  }
+};
+
+// src/documentation/routing.ts
+function collapseRoute(value) {
+  let route = `/${value}`.replace(/\/{2,}/g, "/");
+  if (route.length > 1) route = route.replace(/\/$/, "");
+  return route;
+}
+function normalizeRoute(value) {
+  assertSafeRoute(value);
+  let route = collapseRoute(value);
+  route = route.replace(/\.(?:md|mdx)$/i, "");
+  route = route.replace(/\/index$/i, "");
+  return route || "/";
+}
+function normalizeDocumentationBasePath(value) {
+  if (!value || value === "/") return "";
+  const normalized = normalizeRoute(value);
+  if (normalized === "/_documentation") {
+    throw new DocumentationError("The internal /_documentation namespace cannot be a public documentation base", "documentation_base_invalid");
+  }
+  return normalized;
+}
+function documentationPublicPath(basePath, path) {
+  const base = normalizeDocumentationBasePath(basePath);
+  const suffix = path.startsWith("/") ? path : `/${path}`;
+  if (suffix === "/") return base || "/";
+  return `${base}${suffix}`;
+}
+function assertSafeRoute(value) {
+  if (value.includes("\\") || value.includes("\0")) throw unsafeRoute(value);
+  let decoded = value;
+  for (let pass = 0; pass < 5; pass++) {
+    let next;
+    try {
+      next = decodeURIComponent(decoded);
+    } catch {
+      throw unsafeRoute(value);
+    }
+    if (next === decoded) break;
+    decoded = next;
+  }
+  if (decoded.includes("\\") || decoded.includes("\0") || decoded.split("/").some((segment) => segment === "." || segment === "..")) throw unsafeRoute(value);
+}
+function unsafeRoute(value) {
+  return new DocumentationError(
+    `Documentation route contains an unsafe path segment: ${value}`,
+    "documentation_route_invalid",
+    [{ code: "route_path_escape", message: value }]
+  );
+}
+
+// src/documentation/worker/assistant.ts
 var MAX_CHUNKS = 1e4;
 var MAX_CHUNK_CHARS = 2500;
 var MAX_CORPUS_CHARS = 12e6;
@@ -7472,28 +7637,28 @@ var SEARCH_STOP_WORDS = /* @__PURE__ */ new Set([
   "your"
 ]);
 var indexedChunkCache = /* @__PURE__ */ new WeakMap();
-function parseDocsCorpus(value) {
-  if (!Array.isArray(value)) throw new Error("Docs assistant index must be an array");
+function parseDocumentationCorpus(value) {
+  if (!Array.isArray(value)) throw new Error("Documentation assistant index must be an array");
   if (value.length > MAX_CHUNKS) {
-    throw new Error(`Docs assistant index exceeds ${MAX_CHUNKS} chunks`);
+    throw new Error(`Documentation assistant index exceeds ${MAX_CHUNKS} chunks`);
   }
   const chunks = [];
   let totalChars2 = 0;
   for (let index = 0; index < value.length; index++) {
     const raw = value[index];
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-      throw new Error(`Docs assistant chunk ${index} must be an object`);
+      throw new Error(`Documentation assistant chunk ${index} must be an object`);
     }
     const chunk = raw;
     if (typeof chunk.id !== "string" || !chunk.id || typeof chunk.route !== "string" || !chunk.route.startsWith("/") || typeof chunk.title !== "string" || !chunk.title || typeof chunk.text !== "string" || !chunk.text) {
-      throw new Error(`Docs assistant chunk ${index} has invalid required fields`);
+      throw new Error(`Documentation assistant chunk ${index} has invalid required fields`);
     }
     if (chunk.text.length > MAX_CHUNK_CHARS) {
-      throw new Error(`Docs assistant chunk ${chunk.id} exceeds ${MAX_CHUNK_CHARS} characters`);
+      throw new Error(`Documentation assistant chunk ${chunk.id} exceeds ${MAX_CHUNK_CHARS} characters`);
     }
     totalChars2 += chunk.text.length;
     if (totalChars2 > MAX_CORPUS_CHARS) {
-      throw new Error(`Docs assistant corpus exceeds ${MAX_CORPUS_CHARS} characters`);
+      throw new Error(`Documentation assistant corpus exceeds ${MAX_CORPUS_CHARS} characters`);
     }
     chunks.push({
       id: chunk.id,
@@ -7505,7 +7670,7 @@ function parseDocsCorpus(value) {
   }
   return chunks;
 }
-function searchDocsCorpus(corpus, query, limit = 6) {
+function searchDocumentationCorpus(corpus, query, limit = 6) {
   const normalized = normalize(query);
   const terms = [
     ...new Set(
@@ -7539,8 +7704,8 @@ function searchDocsCorpus(corpus, query, limit = 6) {
     };
   }).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)));
 }
-function readDocsRoute(corpus, route) {
-  const normalizedRoute = normalizeDocsRoute(route);
+function readDocumentationRoute(corpus, route) {
+  const normalizedRoute = collapseRoute(route);
   return corpus.filter((chunk) => chunk.route === normalizedRoute).slice(0, 12).map(({ route: chunkRoute, title, heading, text }) => ({
     route: chunkRoute,
     title,
@@ -7548,40 +7713,44 @@ function readDocsRoute(corpus, route) {
     text
   }));
 }
-function buildDocsAssistantTools(corpus) {
+function buildDocumentationAssistantTools(corpus, basePath = "/docs") {
   return {
-    docs_search: tool2({
+    documentation_search: tool2({
       description: "Search the current documentation. Use this before answering factual or how-to questions.",
       inputSchema: z.object({
         query: z.string().trim().min(2).max(300),
         limit: z.number().int().min(1).max(10).optional()
       }),
       execute: async ({ query, limit }) => ({
-        results: searchDocsCorpus(corpus, query, limit ?? 6)
+        results: searchDocumentationCorpus(corpus, query, limit ?? 6).map((result) => ({
+          ...result,
+          url: documentationPublicPath(basePath, result.route)
+        }))
       })
     }),
-    docs_read: tool2({
-      description: "Read bounded source chunks for one exact documentation route returned by docs_search.",
+    documentation_read: tool2({
+      description: "Read bounded source chunks for one exact documentation route returned by documentation_search.",
       inputSchema: z.object({ route: z.string().trim().startsWith("/").max(500) }),
       execute: async ({ route }) => ({
-        route: normalizeDocsRoute(route),
-        chunks: readDocsRoute(corpus, route)
+        route: collapseRoute(route),
+        url: documentationPublicPath(basePath, route),
+        chunks: readDocumentationRoute(corpus, route)
       })
     })
   };
 }
-function buildDocsAssistantPrompt(appName, currentRoute) {
+function buildDocumentationAssistantPrompt(appName, currentRoute) {
   return [
     `You are the public documentation assistant for "${appName}" on DeepSpace.`,
-    "Answer only from the documentation available through docs_search and docs_read.",
+    "Answer only from the documentation available through documentation_search and documentation_read.",
     "Search before answering unless the user is only greeting you.",
-    "Use docs_read when search excerpts are insufficient or ambiguous.",
+    "Use documentation_read when search excerpts are insufficient or ambiguous.",
     "Never claim access to application records, integrations, private data, or mutation tools.",
     "If the documentation does not support an answer, say so plainly and suggest the closest documented page.",
     "Cite factual answers with Markdown links to the exact documentation routes returned by tools.",
     "Do not invent URLs, APIs, configuration keys, versions, or behavior.",
     "Keep answers concise, practical, and explicit about uncertainty.",
-    ...currentRoute ? [`The reader is currently viewing ${normalizeDocsRoute(currentRoute)}.`] : []
+    ...currentRoute ? [`The reader is currently viewing ${collapseRoute(currentRoute)}.`] : []
   ].join("\n");
 }
 function normalize(value) {
@@ -7589,7 +7758,7 @@ function normalize(value) {
 }
 function canonicalSearchTerm(term) {
   if (SEARCH_STOP_WORDS.has(term)) return term;
-  if (["doc", "docs", "document", "documents", "documentation"].includes(term)) return "docs";
+  if (["doc", "docs", "document", "documents", "documentation"].includes(term)) return "documentation";
   if (["builds", "building", "built", "compile", "compiled", "compiles", "compiling"].includes(term)) {
     return "build";
   }
@@ -7609,11 +7778,6 @@ function indexChunk(chunk) {
   indexedChunkCache.set(chunk, indexed);
   return indexed;
 }
-function normalizeDocsRoute(value) {
-  let route = `/${value}`.replace(/\/{2,}/g, "/");
-  if (route.length > 1) route = route.replace(/\/$/, "");
-  return route;
-}
 function countTerms(tokens, required) {
   const counts = /* @__PURE__ */ new Map();
   for (const token of tokens) {
@@ -7656,130 +7820,67 @@ function excerpt(text, terms) {
   return `${start > 0 ? "\u2026" : ""}${text.slice(start, end).trim()}${end < text.length ? "\u2026" : ""}`;
 }
 
-// src/server/utils/docs-assistant-limiter.ts
-var WINDOW_MS = 6e4;
-var CLIENT_REQUESTS_PER_WINDOW = 12;
-var APP_REQUESTS_PER_WINDOW = 120;
-var MAX_CONCURRENT_REQUESTS = 4;
-var LEASE_TTL_MS = 2 * 6e4;
-var DocsAssistantLimiter = class {
-  sql;
-  constructor(state) {
-    this.sql = state.storage.sql;
-    this.sql.exec(`
-      CREATE TABLE IF NOT EXISTS request_windows (
-        scope TEXT NOT NULL,
-        client_key TEXT NOT NULL,
-        window INTEGER NOT NULL,
-        count INTEGER NOT NULL,
-        PRIMARY KEY (scope, client_key, window)
-      );
-      CREATE TABLE IF NOT EXISTS leases (
-        id TEXT PRIMARY KEY,
-        expires_at INTEGER NOT NULL
-      );
-    `);
-  }
-  async fetch(request) {
-    const url = new URL(request.url);
-    if (request.method !== "POST") return Response.json({ error: "method_not_allowed" }, { status: 405 });
-    if (url.pathname === "/acquire") return this.acquire(request);
-    if (url.pathname === "/release") return this.release(request);
-    return Response.json({ error: "not_found" }, { status: 404 });
-  }
-  async acquire(request) {
-    const body = await request.json().catch(() => null);
-    if (!body || typeof body.clientKey !== "string" || body.clientKey.length !== 64) {
-      return Response.json({ error: "invalid_client_key" }, { status: 400 });
-    }
-    const now = Date.now();
-    const window = Math.floor(now / WINDOW_MS);
-    this.sql.exec("DELETE FROM request_windows WHERE window < ?", window - 1);
-    this.sql.exec("DELETE FROM leases WHERE expires_at <= ?", now);
-    if (!this.consumeWindow("client", body.clientKey, window, CLIENT_REQUESTS_PER_WINDOW)) {
-      return Response.json({ ok: false, reason: "client_rate" }, { status: 429 });
-    }
-    if (!this.consumeWindow("app", "all", window, APP_REQUESTS_PER_WINDOW)) {
-      return Response.json({ ok: false, reason: "app_rate" }, { status: 429 });
-    }
-    const concurrent = this.sql.exec("SELECT COUNT(*) AS count FROM leases").one().count;
-    if (concurrent >= MAX_CONCURRENT_REQUESTS) {
-      return Response.json({ ok: false, reason: "app_concurrency" }, { status: 429 });
-    }
-    const leaseId = crypto.randomUUID();
-    this.sql.exec("INSERT INTO leases (id, expires_at) VALUES (?, ?)", leaseId, now + LEASE_TTL_MS);
-    return Response.json({ ok: true, leaseId });
-  }
-  async release(request) {
-    const body = await request.json().catch(() => null);
-    if (!body || typeof body.leaseId !== "string") {
-      return Response.json({ error: "invalid_lease_id" }, { status: 400 });
-    }
-    this.sql.exec("DELETE FROM leases WHERE id = ?", body.leaseId);
-    return Response.json({ ok: true });
-  }
-  consumeWindow(scope, clientKey, window, limit) {
-    const existing = this.sql.exec(
-      "SELECT count FROM request_windows WHERE scope = ? AND client_key = ? AND window = ?",
-      scope,
-      clientKey,
-      window
-    ).toArray()[0]?.count ?? 0;
-    if (existing >= limit) return false;
-    this.sql.exec(
-      `INSERT INTO request_windows (scope, client_key, window, count)
-       VALUES (?, ?, ?, 1)
-       ON CONFLICT(scope, client_key, window) DO UPDATE SET count = count + 1`,
-      scope,
-      clientKey,
-      window
-    );
-    return true;
-  }
-};
-
-// src/server/utils/docs-published-corpus.ts
+// src/documentation/worker/published-corpus.ts
 var cachedCorpus;
-async function loadDocsPublishedManifest(env, requestUrl = "https://assets.local/") {
-  const response = await env.ASSETS.fetch(new URL("/_docs/manifest.json", requestUrl).toString());
+async function loadDocumentationPublishedManifest(env, requestUrl = "https://assets.local/", assetBasePath = "/_documentation") {
+  const response = await env.ASSETS.fetch(
+    new Request(new URL(`${assetBasePath}/manifest.json`, requestUrl))
+  );
   if (!response.ok) return null;
   const value = await response.json().catch(() => null);
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const manifest = value;
   const assistant = parseAssistantPolicy(manifest.assistant);
-  if (typeof manifest.sourceHash !== "string" || typeof manifest.name !== "string" || !assistant) return null;
+  const mcp = parseMcpPolicy(manifest.mcp);
+  const routes = parsePublishedRoutes(manifest.routes);
+  const resources = parsePublishedPaths(manifest.resources, true);
+  if (manifest.version !== DOCUMENTATION_MANIFEST_VERSION || typeof manifest.sourceHash !== "string" || typeof manifest.name !== "string" || !assistant || !mcp || !routes || !resources)
+    return null;
   return {
     sourceHash: manifest.sourceHash,
     name: manifest.name,
+    routes,
+    resources,
     assistant,
-    // Older docs artifacts did not carry an MCP policy. Fail closed until the
-    // docs bundle is rebuilt by an MCP-aware SDK release.
-    mcp: parseMcpPolicy(manifest.mcp) ?? { access: "disabled" }
+    mcp
   };
 }
-async function loadDocsPublishedCorpus(env, sourceHash, requestUrl = "https://assets.local/") {
+function parsePublishedRoutes(value) {
+  return parsePublishedPaths(value, false);
+}
+function parsePublishedPaths(value, allowEmpty) {
+  if (!Array.isArray(value) || !allowEmpty && value.length === 0) return null;
+  if (value.some((path) => typeof path !== "string" || !path.startsWith("/"))) return null;
+  if (value.some((path) => canonicalNativeDocumentationRequestPath(path) !== path))
+    return null;
+  return [...new Set(value)];
+}
+async function loadDocumentationPublishedCorpus(env, sourceHash, requestUrl = "https://assets.local/", assetBasePath = "/_documentation") {
   if (cachedCorpus?.sourceHash === sourceHash) return cachedCorpus.chunks;
   const response = await env.ASSETS.fetch(
-    new URL("/_docs/assistant-index.json", requestUrl).toString()
+    new Request(new URL(`${assetBasePath}/assistant-index.json`, requestUrl))
   );
   if (!response.ok) throw new Error(`assistant-index.json returned ${response.status}`);
-  const chunks = parseDocsCorpus(await response.json());
+  const chunks = parseDocumentationCorpus(await response.json());
   cachedCorpus = { sourceHash, chunks };
   return chunks;
 }
-async function resolveDocsPublishedCorpus(env, sourceHash, requestUrl = "https://assets.local/") {
+async function resolveDocumentationPublishedCorpus(env, sourceHash, requestUrl = "https://assets.local/", assetBasePath = "/_documentation") {
   try {
-    return { ok: true, chunks: await loadDocsPublishedCorpus(env, sourceHash, requestUrl) };
+    return {
+      ok: true,
+      chunks: await loadDocumentationPublishedCorpus(env, sourceHash, requestUrl, assetBasePath)
+    };
   } catch (error) {
     return { ok: false, error };
   }
 }
-async function readDocsPublishedPage(env, corpus, requestedRoute, requestUrl = "https://assets.local/") {
-  const route = normalizeDocsRoute(requestedRoute.split("#", 1)[0] ?? "/");
+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);
   if (!firstChunk) return null;
-  const pathname = route === "/" ? "/_docs/index.md" : `/_docs${route}.md`;
-  const response = await env.ASSETS.fetch(new URL(pathname, requestUrl).toString());
+  const pathname = route === "/" ? `${assetBasePath}/index.md` : `${assetBasePath}${route}.md`;
+  const response = await env.ASSETS.fetch(new Request(new URL(pathname, requestUrl)));
   if (!response.ok) return null;
   const markdown = await response.text();
   if (markdown.length > 5e5) throw new Error("Documentation page exceeds 500000 characters");
@@ -7801,40 +7902,38 @@ function parseMcpPolicy(value) {
   return { access: policy.access };
 }
 
-// src/server/utils/docs-public-limiter.ts
-async function docsPublicClientKey(value) {
+// src/documentation/worker/public-limiter.ts
+async function documentationPublicClientKey(value) {
   const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
   return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
-async function acquireDocsPublicLease(env, clientKey, logPrefix) {
-  if (!env.DOCS_ASSISTANT_LIMITER) return { ok: false, status: 503 };
-  const id = env.DOCS_ASSISTANT_LIMITER.idFromName(env.DEEPSPACE_APP_ID);
-  const stub = env.DOCS_ASSISTANT_LIMITER.get(id);
-  const response = await stub.fetch("https://docs-limiter/acquire", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ clientKey })
-  }).catch((error) => {
-    console.error(`[${logPrefix}] limiter unavailable:`, error);
-    return null;
+async function checkDocumentationPublicLimit(env, clientKey, logPrefix) {
+  const clientLimiter = env.DOCUMENTATION_CLIENT_RATE_LIMITER;
+  const appLimiter = env.DOCUMENTATION_APP_RATE_LIMITER;
+  if (!clientLimiter || !appLimiter) return { ok: false, status: 503 };
+  try {
+    const client = await clientLimiter.limit({ key: `${env.DEEPSPACE_APP_ID}:${clientKey}` });
+    if (!client.success) return { ok: false, status: 429 };
+    const app = await appLimiter.limit({ key: env.DEEPSPACE_APP_ID });
+    return app.success ? { ok: true } : { ok: false, status: 429 };
+  } catch (error) {
+    console.error(`[${logPrefix}] limiter unavailable: ${documentationLimiterErrorSummary(error)}`);
+    return { ok: false, status: 503 };
+  }
+}
+function documentationLimiterErrorSummary(error) {
+  if (!error || typeof error !== "object") return String(error);
+  const value = error;
+  return JSON.stringify({
+    name: typeof value.name === "string" ? value.name : void 0,
+    message: typeof value.message === "string" ? value.message : void 0,
+    retryable: value.retryable === true,
+    overloaded: value.overloaded === true,
+    cause: typeof value.cause === "string" ? value.cause : void 0
   });
-  if (!response?.ok) {
-    return { ok: false, status: response?.status === 429 ? 429 : 503 };
-  }
-  const body = await response.json().catch(() => null);
-  if (!body || typeof body.leaseId !== "string") return { ok: false, status: 503 };
-  return { ok: true, lease: { leaseId: body.leaseId, stub } };
-}
-async function releaseDocsPublicLease(lease, logPrefix) {
-  if (!lease) return;
-  await lease.stub.fetch("https://docs-limiter/release", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ leaseId: lease.leaseId })
-  }).catch((error) => console.error(`[${logPrefix}] limiter release failed:`, error));
 }
 
-// src/server/utils/request-body.ts
+// src/documentation/worker/request-body.ts
 var RequestBodyTooLargeError = class extends Error {
   constructor(maxBytes) {
     super(`Request body exceeds ${maxBytes} bytes`);
@@ -7868,15 +7967,14 @@ async function readBoundedRequestText(request, maxBytes) {
   return text + decoder.decode();
 }
 
-// src/server/utils/docs-assistant-routes.ts
+// src/documentation/worker/assistant-routes.ts
 var MAX_QUESTION_CHARS = 4e3;
 var MAX_HISTORY_MESSAGES = 12;
 var MAX_HISTORY_CHARS = 2e4;
 var MAX_REQUEST_BYTES = 128 * 1024;
-function registerDocsAssistantRoutes(app, resolveAuth) {
-  app.post("/api/ai/docs", async (c) => {
-    if (c.req.header("x-deepspace-surface") !== "docs") return c.notFound();
-    const manifest = await loadDocsPublishedManifest(c.env, c.req.url);
+function registerDocumentationAssistantRoutes(app, resolveAuth, publicBasePath = "/docs", assetBasePath = "/_documentation") {
+  app.post(`${publicBasePath}/api/ai`, async (c) => {
+    const manifest = await loadDocumentationPublishedManifest(c.env, c.req.url, assetBasePath);
     if (!manifest || manifest.assistant.access === "disabled") return c.notFound();
     let authToken;
     let publicClientKey;
@@ -7890,7 +7988,19 @@ function registerDocsAssistantRoutes(app, resolveAuth) {
       if (!c.env.APP_OWNER_JWT) {
         return c.json({ error: "Public documentation assistant billing is not configured" }, 503);
       }
-      publicClientKey = await docsPublicClientKey(c.req.header("CF-Connecting-IP") ?? "unknown");
+      publicClientKey = await documentationPublicClientKey(
+        c.req.header("CF-Connecting-IP") ?? "unknown"
+      );
+    }
+    const limitResult = publicClientKey ? await checkDocumentationPublicLimit(c.env, publicClientKey, "documentation-assistant") : void 0;
+    if (limitResult && !limitResult.ok) {
+      return c.json(
+        {
+          error: limitResult.status === 429 ? "Documentation assistant rate limit exceeded. Try again shortly." : "Documentation assistant is temporarily unavailable"
+        },
+        limitResult.status,
+        limitResult.status === 429 ? { "Retry-After": "60" } : void 0
+      );
     }
     let body = null;
     try {
@@ -7913,22 +8023,27 @@ function registerDocsAssistantRoutes(app, resolveAuth) {
     const route = typeof body?.route === "string" && body.route.startsWith("/") ? body.route.slice(0, 500) : void 0;
     let history;
     try {
-      history = normalizeDocsAssistantHistory(body?.messages);
+      history = normalizeDocumentationAssistantHistory(body?.messages);
     } catch (error) {
       return c.json({ error: error instanceof Error ? error.message : "messages are invalid" }, 400);
     }
-    const corpusResult = await resolveDocsPublishedCorpus(c.env, manifest.sourceHash, c.req.url);
+    const corpusResult = await resolveDocumentationPublishedCorpus(
+      c.env,
+      manifest.sourceHash,
+      c.req.url,
+      assetBasePath
+    );
     if (!corpusResult.ok) {
-      console.error("[docs-assistant] corpus unavailable:", corpusResult.error);
+      console.error("[documentation-assistant] corpus unavailable:", corpusResult.error);
       return c.json({ error: "Documentation corpus is unavailable" }, 503);
     }
     const corpus = corpusResult.chunks;
-    const selectedModel = resolveDeepSpaceAgentModel(
-      manifest.assistant.model,
-      "documentation"
-    );
+    const selectedModel = resolveDeepSpaceAgentModel(manifest.assistant.model, "documentation");
     if (!selectedModel) {
-      console.error("[docs-assistant] unsupported configured model:", manifest.assistant.model);
+      console.error(
+        "[documentation-assistant] unsupported configured model:",
+        manifest.assistant.model
+      );
       return c.json({ error: "Documentation assistant model is not supported" }, 503);
     }
     const diagnosticContext = {
@@ -7936,66 +8051,40 @@ function registerDocsAssistantRoutes(app, resolveAuth) {
       provider: selectedModel.provider,
       modelId: selectedModel.modelId
     };
-    if (publicClientKey && !c.env.DOCS_ASSISTANT_LIMITER) {
-      return c.json({ error: "Documentation assistant rate limiting is not configured" }, 503);
-    }
-    const leaseResult = publicClientKey ? await acquireDocsPublicLease(c.env, publicClientKey, "docs-assistant") : void 0;
-    if (leaseResult && !leaseResult.ok) {
-      return c.json(
-        {
-          error: leaseResult.status === 429 ? "Documentation assistant rate limit exceeded. Try again shortly." : "Documentation assistant is temporarily unavailable"
-        },
-        leaseResult.status,
-        leaseResult.status === 429 ? { "Retry-After": "60" } : void 0
-      );
-    }
-    const lease = leaseResult?.ok ? leaseResult.lease : void 0;
-    let released = false;
-    const releaseLease = async () => {
-      if (!lease || released) return;
-      released = true;
-      await releaseDocsPublicLease(lease, "docs-assistant");
-    };
     let result;
     try {
       result = streamDeepSpaceAgent(c.env, {
         profile: "documentation",
         modelId: selectedModel.modelId,
         ...authToken ? { authToken } : {},
-        system: buildDocsAssistantPrompt(manifest.name || c.env.APP_NAME, route),
+        system: buildDocumentationAssistantPrompt(manifest.name || c.env.APP_NAME, route),
         messages: [...history, { role: "user", content: question }],
-        tools: buildDocsAssistantTools(corpus),
+        tools: buildDocumentationAssistantTools(corpus, publicBasePath),
         abortSignal: c.req.raw.signal,
-        onAbort: () => releaseLease(),
-        onFinish: releaseLease,
         onError: ({ error }) => {
           console.error(
-            `[docs-assistant] stream error: ${deepSpaceAgentErrorSummary(error, diagnosticContext)}`
+            `[documentation-assistant] stream error: ${deepSpaceAgentErrorSummary(error, diagnosticContext)}`
           );
-          void releaseLease();
         }
       }).result;
     } catch (error) {
       console.error(
-        `[docs-assistant] agent unavailable: ${deepSpaceAgentErrorSummary(error, diagnosticContext)}`
+        `[documentation-assistant] agent unavailable: ${deepSpaceAgentErrorSummary(error, diagnosticContext)}`
       );
-      await releaseLease();
       return c.json({ error: "Documentation assistant is not configured" }, 503);
     }
     return result.toUIMessageStreamResponse({
       sendReasoning: false,
       onError: (error) => {
         console.error(
-          `[docs-assistant] response error: ${deepSpaceAgentErrorSummary(error, diagnosticContext)}`
+          `[documentation-assistant] response error: ${deepSpaceAgentErrorSummary(error, diagnosticContext)}`
         );
-        void releaseLease();
         return "The documentation assistant could not complete this response.";
       }
     });
   });
 }
-var docsAssistantErrorSummary = deepSpaceAgentErrorSummary;
-function normalizeDocsAssistantHistory(value) {
+function normalizeDocumentationAssistantHistory(value) {
   if (value === void 0) return [];
   if (!Array.isArray(value)) throw new TypeError("messages must be an array");
   if (value.length > MAX_HISTORY_MESSAGES) {
@@ -8028,21 +8117,62 @@ function normalizeDocsAssistantHistory(value) {
   }
   return messages;
 }
-function registerDocsStaticRoutes(app) {
-  app.get("/_docs/*", async (c) => {
-    const pathname = new URL(c.req.url).pathname;
-    let response = await c.env.ASSETS.fetch(c.req.raw);
-    let status = response.status;
+function registerDocumentationStaticRoutes(app, publicBasePath = "/docs", assetBasePath = "/_documentation") {
+  const serve = async (c, next) => {
+    const manifest = await loadDocumentationPublishedManifest(c.env, c.req.url, assetBasePath);
+    if (!manifest) return next();
+    const requestUrl = new URL(c.req.url);
+    const pathname = requestUrl.pathname;
+    const publishedPath = documentationRequestPath(pathname, publicBasePath);
+    let response;
+    let status;
+    if (publishedPath && isPublishedDocumentationRequest(publishedPath, manifest.routes, manifest.resources)) {
+      requestUrl.pathname = documentationAssetPath(publishedPath, manifest.resources, assetBasePath);
+      response = await fetchDocumentationAsset(c.env, c.req.raw, requestUrl, assetBasePath);
+      status = response.status;
+    } else {
+      response = new Response(null, { status: 404 });
+      status = 404;
+    }
     if (status === 404) {
       const url = new URL(c.req.url);
-      url.pathname = "/_docs/404.html";
-      response = await c.env.ASSETS.fetch(new Request(url.toString(), c.req.raw));
+      url.pathname = `${assetBasePath}/404.html`;
+      response = await fetchDocumentationAsset(c.env, c.req.raw, url, assetBasePath);
       status = 404;
     }
-    return secureDocsResponse(response, status, pathname);
-  });
+    return secureDocumentationResponse(response, status, pathname);
+  };
+  app.get(publicBasePath || "/", serve);
+  app.get(`${publicBasePath}/*`, serve);
+}
+function isPublishedDocumentationRequest(publishedPath, routes, resources) {
+  return routes.includes(publishedPath) || resources.includes(publishedPath);
+}
+function documentationRequestPath(pathname, publicBasePath) {
+  const logical = pathname === publicBasePath || !publicBasePath && pathname === "/" ? "/" : pathname.slice(publicBasePath.length) || "/";
+  const clean = logical === "/" ? "/" : logical.replace(/\/$/, "");
+  return canonicalNativeDocumentationRequestPath(clean);
+}
+async function fetchDocumentationAsset(env, request, initialUrl, assetBasePath) {
+  let url = initialUrl;
+  for (let redirects = 0; redirects < 3; redirects++) {
+    const response = await env.ASSETS.fetch(new Request(url, request));
+    const location = response.headers.get("Location");
+    if (response.status < 300 || response.status >= 400 || !location) return response;
+    const next = new URL(location, url);
+    if (next.origin !== url.origin || !next.pathname.startsWith(`${assetBasePath}/`)) {
+      return new Response("Invalid documentation asset redirect", { status: 502 });
+    }
+    await response.body?.cancel();
+    url = next;
+  }
+  return new Response("Documentation asset redirect loop", { status: 508 });
+}
+function documentationAssetPath(publishedPath, resources, assetBasePath) {
+  if (publishedPath === "/") return `${assetBasePath}/index.html`;
+  return resources.includes(publishedPath) ? `${assetBasePath}${publishedPath}` : `${assetBasePath}${publishedPath}/index.html`;
 }
-function secureDocsResponse(response, status, pathname) {
+function secureDocumentationResponse(response, status, pathname) {
   const headers = new Headers(response.headers);
   if (status !== 404 && pathname.endsWith(".md")) {
     headers.set("Content-Type", "text/markdown; charset=utf-8");
@@ -8062,7 +8192,14 @@ function secureDocsResponse(response, status, pathname) {
   return new Response(response.body, { status, headers });
 }
 
-// src/server/utils/docs-mcp/protocol.ts
+// 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";
 var SUPPORTED_PROTOCOL_VERSIONS = /* @__PURE__ */ new Set([CURRENT_PROTOCOL_VERSION, "2025-06-18", "2025-03-26"]);
@@ -8077,11 +8214,11 @@ function initializeResponse(request) {
       resources: { subscribe: false, listChanged: false }
     },
     serverInfo: {
-      name: "DeepSpace Docs",
+      name: "DeepSpace Documentation",
       title: "DeepSpace documentation",
       version: MCP_SERVER_VERSION
     },
-    instructions: "Search the published docs before answering, then read exact pages when full context is needed."
+    instructions: "Search the published documentation before answering, then read exact pages when full context is needed."
   });
 }
 function hasValidOrigin(request) {
@@ -8156,10 +8293,10 @@ function mcpSecurityHeaders() {
   };
 }
 
-// src/server/utils/docs-mcp/tools.ts
-var DOCS_TOOLS = [
+// src/documentation/worker/mcp/tools.ts
+var DOCUMENTATION_TOOLS = [
   {
-    name: "docs_search",
+    name: "documentation_search",
     title: "Search documentation",
     description: "Search the published documentation and return ranked, linked excerpts.",
     inputSchema: {
@@ -8184,7 +8321,7 @@ var DOCS_TOOLS = [
     }
   },
   {
-    name: "docs_read",
+    name: "documentation_read",
     title: "Read documentation page",
     description: "Read one complete published documentation page as Markdown.",
     inputSchema: {
@@ -8213,59 +8350,67 @@ var DOCS_TOOLS = [
     }
   }
 ];
-async function callDocsTool(rawRequest, request, corpus, env) {
+async function callDocumentationTool(rawRequest, request, corpus, env, basePath = "/docs", assetBasePath = "/_documentation") {
   const params = objectValue(request.params);
   const name = typeof params?.name === "string" ? params.name : "";
   const args = objectValue(params?.arguments) ?? {};
   const origin = new URL(rawRequest.url).origin;
-  if (name === "docs_search") {
+  if (name === "documentation_search") {
     const query = typeof args.query === "string" ? args.query.trim() : "";
     const limit = args.limit === void 0 ? 6 : args.limit;
     if (query.length < 2 || query.length > 300 || !Number.isInteger(limit) || Number(limit) < 1 || Number(limit) > 10) {
-      return mcpError(request.id, -32602, "Invalid docs_search arguments");
+      return mcpError(request.id, -32602, "Invalid documentation_search arguments");
     }
     const value = {
-      results: searchDocsCorpus(corpus, query, Number(limit)).map((result) => ({
+      results: searchDocumentationCorpus(corpus, query, Number(limit)).map((result) => ({
         ...result,
-        url: new URL(result.route, origin).toString()
+        url: new URL(documentationPublicPath(basePath, result.route), origin).toString()
       }))
     };
     return toolResult(request.id, value);
   }
-  if (name === "docs_read") {
+  if (name === "documentation_read") {
     const route = typeof args.route === "string" ? args.route.trim() : "";
     if (!route.startsWith("/") || route.length > 500) {
-      return mcpError(request.id, -32602, "Invalid docs_read arguments");
+      return mcpError(request.id, -32602, "Invalid documentation_read arguments");
     }
     try {
-      const page = await readDocsPublishedPage(env, corpus, route, rawRequest.url);
+      const page = await readDocumentationPublishedPage(
+        env,
+        corpus,
+        route,
+        rawRequest.url,
+        assetBasePath
+      );
       if (!page) return toolError(request.id, `No published documentation page exists at ${route}`);
       return toolResult(request.id, {
         ...page,
-        url: new URL(page.route, origin).toString()
+        url: new URL(documentationPublicPath(basePath, page.route), origin).toString()
       });
     } catch (error) {
-      console.error("[docs-mcp] page unavailable:", error);
+      console.error("[documentation-mcp] page unavailable:", error);
       return toolError(request.id, "The documentation page could not be read");
     }
   }
   return mcpError(request.id, -32602, `Unknown documentation tool: ${name || "<missing>"}`);
 }
 
-// src/server/utils/docs-mcp-routes.ts
+// src/documentation/worker/mcp-routes.ts
 var MAX_REQUEST_CHARS = 64e3;
 var MAX_REQUEST_BYTES2 = MAX_REQUEST_CHARS * 4;
 var MAX_SKILL_CHARS = 256e3;
-function registerDocsMcpRoutes(app) {
-  app.get("/mcp", async (c) => {
-    if (!await publicManifest(c.req.raw, c.env)) return c.notFound();
+var DOCUMENTATION_BASE_PATH = "/docs";
+function registerDocumentationMcpRoutes(app, publicBasePath = DOCUMENTATION_BASE_PATH, assetBasePath = "/_documentation") {
+  const mcpPath = documentationPublicPath(publicBasePath, "/mcp");
+  app.get(mcpPath, async (c) => {
+    if (!await publicManifest(c.req.raw, c.env, assetBasePath)) return c.notFound();
     return new Response(null, {
       status: 405,
       headers: { Allow: "POST", ...mcpSecurityHeaders() }
     });
   });
-  app.post("/mcp", async (c) => {
-    const manifest = await publicManifest(c.req.raw, c.env);
+  app.post(mcpPath, async (c) => {
+    const manifest = await publicManifest(c.req.raw, c.env, assetBasePath);
     if (!manifest) return c.notFound();
     if (!hasValidOrigin(c.req.raw)) {
       return mcpError(null, -32e3, "Invalid Origin", 403);
@@ -8297,67 +8442,89 @@ function registerDocsMcpRoutes(app) {
     if (request.method === "initialize") return initializeResponse(requestWithId);
     if (request.method === "ping") return mcpResult(requestId, {});
     if (request.method === "tools/list") {
-      return mcpResult(requestId, { tools: DOCS_TOOLS });
+      return mcpResult(requestId, { tools: DOCUMENTATION_TOOLS });
     }
     if (request.method === "resources/list") {
-      return mcpResult(requestId, { resources: [skillResource(c.req.raw, manifest)] });
+      return mcpResult(requestId, {
+        resources: [skillResource(c.req.raw, manifest, publicBasePath)]
+      });
     }
     if (request.method === "resources/read") {
-      return readSkillResource(c.req.raw, requestWithId, manifest, c.env);
+      return readSkillResource(
+        c.req.raw,
+        requestWithId,
+        manifest,
+        c.env,
+        publicBasePath,
+        assetBasePath
+      );
     }
     if (request.method !== "tools/call") {
       return mcpError(requestId, -32601, `Method not found: ${request.method}`);
     }
-    const corpusResult = await resolveDocsPublishedCorpus(c.env, manifest.sourceHash, c.req.url);
-    if (!corpusResult.ok) {
-      console.error("[docs-mcp] corpus unavailable:", corpusResult.error);
-      return mcpError(requestId, -32002, "Documentation corpus is unavailable", 503);
-    }
-    const corpus = corpusResult.chunks;
-    const clientKey = await docsPublicClientKey(c.req.header("CF-Connecting-IP") ?? "unknown");
-    const leaseResult = await acquireDocsPublicLease(c.env, clientKey, "docs-mcp");
-    if (!leaseResult.ok) {
+    const clientKey = await documentationPublicClientKey(
+      c.req.header("CF-Connecting-IP") ?? "unknown"
+    );
+    const limitResult = await checkDocumentationPublicLimit(c.env, clientKey, "documentation-mcp");
+    if (!limitResult.ok) {
       return mcpError(
         requestId,
-        leaseResult.status === 429 ? -32029 : -32002,
-        leaseResult.status === 429 ? "Documentation tool rate limit exceeded. Try again shortly." : "Documentation tools are temporarily unavailable",
-        leaseResult.status,
-        leaseResult.status === 429 ? { "Retry-After": "60" } : void 0
+        limitResult.status === 429 ? -32029 : -32002,
+        limitResult.status === 429 ? "Documentation tool rate limit exceeded. Try again shortly." : "Documentation tools are temporarily unavailable",
+        limitResult.status,
+        limitResult.status === 429 ? { "Retry-After": "60" } : void 0
       );
     }
-    try {
-      return await callDocsTool(c.req.raw, requestWithId, corpus, c.env);
-    } finally {
-      await releaseDocsPublicLease(leaseResult.lease, "docs-mcp");
+    const corpusResult = await resolveDocumentationPublishedCorpus(
+      c.env,
+      manifest.sourceHash,
+      c.req.url,
+      assetBasePath
+    );
+    if (!corpusResult.ok) {
+      console.error("[documentation-mcp] corpus unavailable:", corpusResult.error);
+      return mcpError(requestId, -32002, "Documentation corpus is unavailable", 503);
     }
+    const corpus = corpusResult.chunks;
+    return callDocumentationTool(
+      c.req.raw,
+      requestWithId,
+      corpus,
+      c.env,
+      publicBasePath,
+      assetBasePath
+    );
   });
   for (const path of [
     "/.well-known/mcp",
     "/.well-known/mcp.json",
     "/.well-known/mcp/server-card.json"
   ]) {
-    app.get(path, async (c) => {
-      const manifest = await publicManifest(c.req.raw, c.env);
+    app.get(documentationPublicPath(publicBasePath, path), async (c) => {
+      const manifest = await publicManifest(c.req.raw, c.env, assetBasePath);
       if (!manifest) return c.notFound();
-      return discoveryResponse(c.req.raw, manifest);
+      return discoveryResponse(c.req.raw, manifest, publicBasePath);
     });
   }
-  app.get("/.well-known/mcp/server-cards.json", async (c) => {
-    const manifest = await publicManifest(c.req.raw, c.env);
-    if (!manifest) return c.notFound();
-    return jsonResponse({ servers: [serverCard(c.req.raw, manifest)] }, 200, {
-      "Cache-Control": "public, max-age=300"
-    });
-  });
+  app.get(
+    documentationPublicPath(publicBasePath, "/.well-known/mcp/server-cards.json"),
+    async (c) => {
+      const manifest = await publicManifest(c.req.raw, c.env, assetBasePath);
+      if (!manifest) return c.notFound();
+      return jsonResponse({ servers: [serverCard(c.req.raw, manifest, publicBasePath)] }, 200, {
+        "Cache-Control": "public, max-age=300"
+      });
+    }
+  );
 }
-async function readSkillResource(rawRequest, request, manifest, env) {
+async function readSkillResource(rawRequest, request, manifest, env, publicBasePath, assetBasePath) {
   const params = objectValue(request.params);
   const requestedUri = typeof params?.uri === "string" ? params.uri : "";
-  const resource = skillResource(rawRequest, manifest);
+  const resource = skillResource(rawRequest, manifest, publicBasePath);
   if (requestedUri !== resource.uri) {
     return mcpError(request.id, -32602, "Unknown documentation resource");
   }
-  const assetUrl = new URL("/_docs/skill.md", rawRequest.url);
+  const assetUrl = new URL(`${assetBasePath}/skill.md`, rawRequest.url);
   const response = await env.ASSETS.fetch(new Request(assetUrl, { method: "GET" }));
   if (!response.ok) return mcpError(request.id, -32002, "Documentation skill is unavailable", 503);
   const text = await response.text();
@@ -8368,158 +8535,83 @@ async function readSkillResource(rawRequest, request, manifest, env) {
     contents: [{ uri: resource.uri, mimeType: resource.mimeType, text }]
   });
 }
-function skillResource(request, manifest) {
+function skillResource(request, manifest, publicBasePath) {
+  const subject = documentationSubject(manifest.name);
   return {
-    uri: new URL("/skill.md", request.url).toString(),
-    name: `${manifest.name} documentation skill`,
+    uri: new URL(`${publicBasePath}/skill.md`, request.url).toString(),
+    name: `${subject} skill`,
     title: `Use ${manifest.name}`,
-    description: `Agent instructions grounded in the published ${manifest.name} documentation.`,
+    description: `Agent instructions grounded in the published ${subject}.`,
     mimeType: "text/markdown"
   };
 }
-async function publicManifest(request, env) {
-  if (request.headers.get("x-deepspace-surface") !== "docs") return null;
-  const manifest = await loadDocsPublishedManifest(env, request.url);
+async function publicManifest(request, env, assetBasePath) {
+  const manifest = await loadDocumentationPublishedManifest(env, request.url, assetBasePath);
   return manifest?.mcp.access === "public" ? manifest : null;
 }
-function discoveryResponse(request, manifest) {
-  return jsonResponse(serverCard(request, manifest), 200, {
+function discoveryResponse(request, manifest, publicBasePath) {
+  return jsonResponse(serverCard(request, manifest, publicBasePath), 200, {
     "Cache-Control": "public, max-age=300"
   });
 }
-function serverCard(request, manifest) {
+function serverCard(request, manifest, publicBasePath) {
   return {
     name: manifest.name,
-    description: `Search and read the published ${manifest.name} documentation.`,
+    description: `Search and read the published ${documentationSubject(manifest.name)}.`,
     version: MCP_SERVER_VERSION,
     protocolVersion: CURRENT_PROTOCOL_VERSION,
     transport: {
       type: "streamable-http",
-      url: new URL("/mcp", request.url).toString()
+      url: new URL(`${publicBasePath}/mcp`, request.url).toString()
     },
     authentication: { required: false },
     capabilities: {
-      tools: DOCS_TOOLS.map(({ name, title, description }) => ({ name, title, description })),
-      resources: [skillResource(request, manifest)]
+      tools: DOCUMENTATION_TOOLS.map(({ name, title, description }) => ({
+        name,
+        title,
+        description
+      })),
+      resources: [skillResource(request, manifest, publicBasePath)]
     }
   };
 }
 
-// src/server/utils/docs-routes.ts
-function registerDeepSpaceDocs(app, options) {
-  registerDocsAssistantRoutes(app, options.resolveAuth);
-  registerDocsMcpRoutes(app);
-  registerDocsStaticRoutes(app);
-}
-function docsAssistantLimiterManifestEntry(className) {
-  return {
-    binding: "DOCS_ASSISTANT_LIMITER",
-    className,
-    sqlite: true
-  };
-}
-
-// src/server/utils/metering.ts
-function meterUsage(env, kind, fields = {}) {
-  const ds = env.USAGE_EVENTS;
-  if (!ds) return false;
-  try {
-    ds.writeDataPoint({
-      indexes: [env.OWNER_USER_ID ?? "unknown"],
-      blobs: [
-        env.DEEPSPACE_RESOURCE_ID ?? env.APP_NAME ?? "unknown",
-        kind,
-        fields.id ?? "",
-        fields.op ?? ""
-      ],
-      doubles: [fields.units ?? 0, fields.count ?? 0]
+// src/documentation/worker/routes.ts
+function registerDeepSpaceDocumentation(app, options) {
+  app.use(
+    "*",
+    async (c, next) => isPrivateDocumentationPath(new URL(c.req.url).pathname) ? c.notFound() : next()
+  );
+  const domains = new Set(
+    options.config?.domains?.map((domain) => domain.trim().toLowerCase()) ?? []
+  );
+  if (domains.size) {
+    const root = new Hono();
+    registerDocumentationAssistantRoutes(root, options.resolveAuth, "", "/_documentation-root");
+    registerDocumentationMcpRoutes(root, "", "/_documentation-root");
+    registerDocumentationStaticRoutes(root, "", "/_documentation-root");
+    app.all("*", (c, next) => {
+      const url = new URL(c.req.url);
+      if (!domains.has(url.hostname.toLowerCase()) || url.pathname === "/api/auth" || url.pathname.startsWith("/api/auth/"))
+        return next();
+      return root.fetch(c.req.raw, c.env);
     });
-    return true;
-  } catch {
-    return false;
   }
+  registerDocumentationAssistantRoutes(app, options.resolveAuth);
+  registerDocumentationMcpRoutes(app);
+  registerDocumentationStaticRoutes(app);
 }
-function meterAi(env, model, fields = {}) {
-  const calls = fields.calls ?? 1;
-  const inChars = fields.inputChars ?? 0;
-  const outChars = fields.outputChars ?? 0;
-  let ok = true;
-  if (inChars > 0) {
-    ok = meterUsage(env, "ai", { id: model, op: "input", units: inChars, count: calls }) && ok;
-  }
-  if (outChars > 0) {
-    ok = meterUsage(env, "ai", { id: model, op: "output", units: outChars, count: calls }) && ok;
-  }
-  if (inChars === 0 && outChars === 0) {
-    ok = meterUsage(env, "ai", { id: model, op: "call", units: 0, count: calls }) && ok;
-  }
-  return ok;
-}
-function meterVectorize(env, indexName, op, fields = {}) {
-  const vectors = fields.vectors ?? 0;
-  const dims = fields.dims ?? 0;
-  const stored = fields.storedCount ?? 0;
-  const units = op === "query" ? (vectors + stored) * dims : vectors * dims;
-  return meterUsage(env, "vectorize", { id: indexName, op, units, count: vectors });
-}
-var CHARS_PER_TOKEN = 4;
-var AI_EMBED_USD_PER_M_TOKENS = 0.012;
-var VECTORIZE_QUERIED_USD_PER_M_DIMS = 0.01;
-var VECTORIZE_STORED_USD_PER_100M_DIMS = 0.05;
-var COST_RATES = {
-  ai: {
-    /**
-     * USD per character of *embedding input* (bge-m3 / qwen3-embedding tier).
-     * Renamed from `perChar` to make explicit that this rate does NOT
-     * apply to LLM-generation output — see `priceBindingUsageEvent`.
-     */
-    embedInputPerChar: AI_EMBED_USD_PER_M_TOKENS / 1e6 / CHARS_PER_TOKEN
-  },
-  vectorize: {
-    /** USD per queried dimension (per query, per stored vector compared). */
-    queriedPerDim: VECTORIZE_QUERIED_USD_PER_M_DIMS / 1e6,
-    /** USD per stored dimension per month. */
-    storedPerDimPerMonth: VECTORIZE_STORED_USD_PER_100M_DIMS / 1e8
-  }
-};
-function priceBindingUsageEvent(kind, op, units) {
-  if (kind === "ai" && op === "input") {
-    return units * COST_RATES.ai.embedInputPerChar;
-  }
-  if (kind === "vectorize" && op === "query") {
-    return units * COST_RATES.vectorize.queriedPerDim;
-  }
-  return 0;
-}
-
-// src/server/utils/d1-migrations.ts
-var META_TABLE = "_dpc_migrations";
-var META_BOOTSTRAP_SQL = `CREATE TABLE IF NOT EXISTS ${META_TABLE} (idx INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)`;
-async function runMigrations(db, migrations) {
-  await db.prepare(META_BOOTSTRAP_SQL).run();
-  const row = await db.prepare(`SELECT COUNT(*) AS n FROM ${META_TABLE}`).first();
-  const fromVersion = row?.n ?? 0;
-  if (fromVersion >= migrations.length) {
-    return { fromVersion, toVersion: fromVersion, applied: 0 };
-  }
-  let current = fromVersion;
-  for (let i = fromVersion; i < migrations.length; i++) {
-    const statements = splitStatements(migrations[i]);
-    for (const stmt of statements) {
-      try {
-        await db.prepare(stmt).run();
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(`Migration ${i} failed (db at version=${current}): ${msg}`);
-      }
-    }
-    await db.prepare(`INSERT INTO ${META_TABLE} (idx, applied_at) VALUES (?, ?)`).bind(i, (/* @__PURE__ */ new Date()).toISOString()).run();
-    current = i + 1;
+function isPrivateDocumentationPath(pathname) {
+  let decoded = pathname;
+  for (let round = 0; round < 3; round += 1) {
+    const next = decoded.replace(
+      /%([0-9a-f]{2})/giu,
+      (_sequence, hex) => String.fromCharCode(Number.parseInt(hex, 16))
+    );
+    if (next === decoded) break;
+    decoded = next;
   }
-  return { fromVersion, toVersion: current, applied: current - fromVersion };
-}
-function splitStatements(sql) {
-  return sql.split(";").map((s) => s.trim()).filter((s) => s.length > 0);
+  return /^\/_documentation(?:-root)?(?:\/|$)/u.test(decoded.replace(/\/{2,}/gu, "/"));
 }
 
 // src/server/auth/jwtVerifier.ts
@@ -8975,7 +9067,6 @@ export {
   DIRECTORY_SCHEMAS,
   DeepSpaceAgentModelError,
   DeepSpaceAgentProfileError,
-  DocsAssistantLimiter,
   GLOBAL_DO_TYPES,
   GLOBAL_DO_TYPE_NAMES,
   GameRoom,
@@ -9011,7 +9102,6 @@ export {
   VOTING_SCHEMAS,
   WORKSPACE_SCHEMAS,
   YjsRoom,
-  acquireDocsPublicLease,
   analyzePermissions,
   apiWorkerFetch,
   appendMessage,
@@ -9020,8 +9110,6 @@ export {
   authWorkerFetch,
   bindingManifestFromOutputConfig,
   buildCronContext,
-  buildDocsAssistantPrompt,
-  buildDocsAssistantTools,
   buildTableSelect,
   buildUiParts,
   callRegistry,
@@ -9050,9 +9138,6 @@ export {
   deepSpaceAgentErrorSummary,
   deleteChatCascade,
   dispatch,
-  docsAssistantErrorSummary,
-  docsAssistantLimiterManifestEntry,
-  docsPublicClientKey,
   encode,
   encodeAwarenessMessage,
   encodeSyncStep1,
@@ -9070,15 +9155,12 @@ export {
   handleSyncMessage,
   hasContent,
   isAutoProvision,
-  isDocsResourcePath,
   isOwner,
   isTestAccountClaims,
   isTestAccountEmail,
   isTestAccountTier,
   lintSchema,
   listDeepSpaceAgentModels,
-  loadDocsPublishedCorpus,
-  loadDocsPublishedManifest,
   loadMessages,
   makeDefaultSummarizer,
   matchOrigin,
@@ -9086,33 +9168,22 @@ export {
   meterUsage,
   meterVectorize,
   noopPermissionContext,
-  normalizeDocsAssistantHistory,
-  normalizeDocsRoute,
-  parseDocsCorpus,
   parseQuotaLimit,
   platformCorsPatterns,
   platformWorkerFetch,
   prepareMessagesWithCompaction,
   priceBindingUsageEvent,
-  readDocsPublishedPage,
-  readDocsRoute,
   readVarUint,
   readVarUint8Array,
   registerClientErrorRoute,
-  registerDeepSpaceDocs,
-  registerDocsAssistantRoutes,
-  registerDocsMcpRoutes,
-  registerDocsStaticRoutes,
+  registerDeepSpaceDocumentation,
   registryErrorJson,
   registryStub,
-  releaseDocsPublicLease,
   resolveAppName,
   resolveColumn,
   resolveDeepSpaceAgentModel,
-  resolveDocsPublishedCorpus,
   rowToData,
   runMigrations,
-  searchDocsCorpus,
   serverBuild,
   streamDeepSpaceAgent,
   timingSafeEqualHex,