@promptowl/contextnest-community 1.7.0 → 1.8.0

package/dist/index.js

@@ -13,10 +13,11 @@ import {
   getPendingReview,
   getReviewHistory,
   getReviewQueue,
+  notifySlackForNest,
   reject,
   safePublishDocument,
   submitForReview
-} from "./chunk-MOXICJPD.js";
+} from "./chunk-Z3Y46ZGU.js";
 import {
   checkConflict,
   createVersion,
@@ -25,7 +26,7 @@ import {
   getDisplayStatus,
   getVersions,
   setApprovedVersion
-} from "./chunk-VD5QX2ZQ.js";
+} from "./chunk-XNGOO6RI.js";
 import {
   AppError,
   ConflictError,
@@ -84,14 +85,14 @@ import {
   updateSteward,
   upsertEnvVar,
   validateLicense
-} from "./chunk-43DOX4LH.js";
+} from "./chunk-PJTAUVD7.js";
 import {
   config,
   getDb,
   initDb,
   insertOrIgnore,
   nowExpr
-} from "./chunk-QMLAXQES.js";
+} from "./chunk-PLAHCDQG.js";
 import {
   ANON_EMAIL,
   ANON_USER_ID
@@ -101,7 +102,8 @@ import {
 import { serve } from "@hono/node-server";
 
 // src/app.ts
-import { Hono as Hono9 } from "hono";
+import { Hono as Hono10 } from "hono";
+import { LinearRouter } from "hono/router/linear-router";
 import { createMiddleware as createMiddleware2 } from "hono/factory";
 import { cors } from "hono/cors";
 
@@ -1289,7 +1291,7 @@ async function approveExternalEdit(input) {
     const node = await storage.readDocument(input.documentId);
     const versionNum = result.versionEntry.version;
     const tags = node.frontmatter.tags || [];
-    const { createVersion: createVersion2, setApprovedVersion: setApprovedVersion2 } = await import("./version-service-FJWVTZKR.js");
+    const { createVersion: createVersion2, setApprovedVersion: setApprovedVersion2 } = await import("./version-service-B3SDOJQE.js");
     await createVersion2({
       nestId: input.nestId,
       nodeId: input.documentId,
@@ -1375,6 +1377,10 @@ function bodyOnly(nodeId, raw) {
     return raw;
   }
 }
+var RUNNABLE_NODE_TYPES = ["agent", "skill"];
+function isRunnableType(type) {
+  return RUNNABLE_NODE_TYPES.includes(type || "");
+}
 function toNodeResponse(node) {
   const fm = node.frontmatter;
   const title = fm.title === void 0 || fm.title === null ? "" : String(fm.title);
@@ -1391,14 +1397,20 @@ function toNodeResponse(node) {
     created_at: fm.created_at,
     updated_at: fm.updated_at,
     content: node.body || "",
-    pendingChange: node.pendingChange ?? void 0
+    pendingChange: node.pendingChange ?? void 0,
+    // Same YAML-coercion rule as title above: `schedule: 123` parses as a
+    // number — normalize to string at the API boundary.
+    schedule: fm.metadata?.schedule != null ? String(fm.metadata.schedule) : void 0
   };
 }
 async function listNodesForCaller(nestId, userId, filters = {}) {
   const { storage, versions: versionManager } = await engineCache.get(nestId);
   let documents = await storage.discoverDocuments();
   if (filters.type) {
-    documents = documents.filter((n) => n.frontmatter.type === filters.type);
+    const wanted = new Set(
+      Array.isArray(filters.type) ? filters.type : [filters.type]
+    );
+    documents = documents.filter((n) => wanted.has(n.frontmatter.type));
   }
   if (filters.tag) {
     const tag = normalizeTag2(filters.tag);
@@ -1464,6 +1476,11 @@ async function createNode(nestId, input, userEmail) {
   }
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const tags = (input.tags || []).map(normalizeTag2);
+  if (input.schedule !== void 0 && !isRunnableType(input.type)) {
+    throw new ValidationError(
+      `schedule is only valid for runnable node types (${RUNNABLE_NODE_TYPES.join(", ")})`
+    );
+  }
   const hasStewards = await isStewardshipEnabled(nestId);
   const initialStatus = hasStewards ? "draft" : "published";
   const initialVersion = hasStewards ? 1 : 0;
@@ -1478,7 +1495,11 @@ async function createNode(nestId, input, userEmail) {
       version: initialVersion,
       created_at: now,
       updated_at: now,
-      metadata: { owners: ["*"], scope: input.scope || "team" }
+      metadata: {
+        owners: ["*"],
+        scope: input.scope || "team",
+        ...input.schedule ? { schedule: input.schedule } : {}
+      }
     },
     body: input.content,
     rawContent: ""
@@ -1605,6 +1626,17 @@ async function updateNode(nestId, nodeId, patch, userEmail) {
   if (patch.title) {
     node = { ...node, frontmatter: { ...node.frontmatter, title: patch.title } };
   }
+  if (patch.schedule !== void 0) {
+    if (!isRunnableType(node.frontmatter.type)) {
+      throw new ValidationError(
+        `schedule is only valid for runnable node types (${RUNNABLE_NODE_TYPES.join(", ")})`
+      );
+    }
+    const metadata = { ...node.frontmatter.metadata };
+    if (patch.schedule === "") delete metadata.schedule;
+    else metadata.schedule = patch.schedule;
+    node = { ...node, frontmatter: { ...node.frontmatter, metadata } };
+  }
   const hasStewards = await isStewardshipEnabled(nestId);
   const currentTags = node.frontmatter.tags || [];
   if (hasStewards && await getPendingReview(nestId, nodeId)) {
@@ -2165,6 +2197,10 @@ async function addCollaborator(params) {
     "INSERT INTO nest_collaborators (id, nest_id, user_id, permission, granted_by) VALUES (?, ?, ?, ?, ?)",
     [collabId, nestId, userId, params.permission, granterId]
   );
+  void notifySlackForNest(
+    nestId,
+    `:key: ${params.email || userId} added as *${params.permission}*${params.grantedByEmail ? ` by ${params.grantedByEmail}` : ""}`
+  );
   return await db.get(
     "SELECT * FROM nest_collaborators WHERE id = ?",
     [collabId]
@@ -2597,6 +2633,7 @@ nodeRoutes.post("/", async (c) => {
       tags: body.tags,
       scope: body.scope,
       status: body.status,
+      schedule: body.schedule,
       folder: body.folder
     },
     authorEmail
@@ -2614,7 +2651,7 @@ nodeRoutes.post("/", async (c) => {
 nodeRoutes.get("/:nodeId{.+?}/stewards", async (c) => {
   const nestId = c.req.param("nestId");
   const nodeId = c.req.param("nodeId");
-  const { resolveStewardsWithFallback: resolveStewardsWithFallback2 } = await import("./stewardship-service-I2JAFYJU.js");
+  const { resolveStewardsWithFallback: resolveStewardsWithFallback2 } = await import("./stewardship-service-ZXAMFTXO.js");
   const { stewards, fallbackToOwner, ownerEmail } = await resolveStewardsWithFallback2(
     nestId,
     nodeId
@@ -2635,7 +2672,7 @@ nodeRoutes.get("/:nodeId{.+?}/stewards", async (c) => {
 nodeRoutes.get("/:nodeId{.+?}/versions", async (c) => {
   const nestId = c.req.param("nestId");
   const nodeId = c.req.param("nodeId");
-  const { getVersions: getVersions2, getApprovedVersion: getApprovedVersion2 } = await import("./version-service-FJWVTZKR.js");
+  const { getVersions: getVersions2, getApprovedVersion: getApprovedVersion2 } = await import("./version-service-B3SDOJQE.js");
   const allVersions = await getVersions2(nestId, nodeId);
   const approved = await getApprovedVersion2(nestId, nodeId);
   const db = getDb();
@@ -2667,7 +2704,7 @@ nodeRoutes.get("/:nodeId{.+?}/versions", async (c) => {
 nodeRoutes.get("/:nodeId{.+?}/reviews", async (c) => {
   const nestId = c.req.param("nestId");
   const nodeId = c.req.param("nodeId");
-  const { getReviewHistory: getReviewHistory2 } = await import("./review-service-2FSKW425.js");
+  const { getReviewHistory: getReviewHistory2 } = await import("./review-service-G5US3SMG.js");
   const history = await getReviewHistory2(nestId, nodeId);
   return c.json({ reviews: history });
 });
@@ -2814,7 +2851,8 @@ nodeRoutes.patch("/:nodeId{.+}", async (c) => {
       tags: body.tags,
       title: body.title,
       status: body.status,
-      changeNote: body.changeNote
+      changeNote: body.changeNote,
+      schedule: body.schedule
     },
     authorEmail
   );
@@ -2880,6 +2918,13 @@ nodeRoutes.delete("/:nodeId{.+}", async (c) => {
       "DELETE FROM annotation_threads WHERE nest_id = ? AND node_id = ?",
       [nestId, derivedId]
     );
+    await tx.run(
+      `INSERT INTO node_deletions (nest_id, node_id, deleted_by, deleted_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(nest_id, node_id) DO UPDATE
+         SET deleted_by = excluded.deleted_by, deleted_at = excluded.deleted_at`,
+      [nestId, nodeId, await getUserEmail(c), (/* @__PURE__ */ new Date()).toISOString()]
+    );
   });
   await trackEvent("node.delete", { nestId, nodeId });
   return c.json({ deleted: true });
@@ -3388,6 +3433,100 @@ async function buildNestGraph(nestId, userId, userEmail, canSeeIdentities) {
 
 // src/nodes/query-routes.ts
 var queryRoutes = new Hono6();
+queryRoutes.get("/changes", async (c) => {
+  const nestId = c.req.param("nestId");
+  const userId = c.get("userId");
+  const sinceRaw = c.req.query("since");
+  const sinceMs = sinceRaw ? Date.parse(sinceRaw) : NaN;
+  if (!sinceRaw || Number.isNaN(sinceMs)) {
+    throw new ValidationError(
+      "since must be an ISO-8601 date, e.g. ?since=2026-07-01T00:00:00Z"
+    );
+  }
+  const includeContent = ["1", "true"].includes(
+    c.req.query("include_content") || ""
+  );
+  const all = await listNodesForCaller(nestId, userId);
+  const db = getDb();
+  const publicReader = await isPublicReader(nestId, userId);
+  const approvedRows = await db.all(
+    "SELECT node_id, approved_at FROM approved_versions WHERE nest_id = ?",
+    [nestId]
+  );
+  const parseDbTs = (t) => Date.parse(t.includes("T") ? t : `${t.replace(" ", "T")}Z`);
+  const approvedAtMsByNode = new Map(
+    approvedRows.map((r) => [r.node_id, parseDbTs(r.approved_at)])
+  );
+  const publishedSince = new Set(
+    approvedRows.filter((r) => parseDbTs(r.approved_at) > sinceMs).map((r) => r.node_id)
+  );
+  const summarize = (n, updatedOverride) => ({
+    id: n.id,
+    title: n.title,
+    type: n.type,
+    status: n.status,
+    tags: n.tags,
+    created_at: n.created_at,
+    updated_at: updatedOverride ?? n.updated_at,
+    ...includeContent ? { content: n.content } : {}
+  });
+  const created = [];
+  const updated = [];
+  for (const n of all) {
+    if (publicReader) {
+      const approvedMs = approvedAtMsByNode.get(n.id);
+      if (approvedMs === void 0) continue;
+      const approvedIso = new Date(approvedMs).toISOString();
+      const createdAt2 = Date.parse(n.created_at || "");
+      if (!Number.isNaN(createdAt2) && createdAt2 > sinceMs) {
+        created.push(summarize(n, approvedIso));
+      } else if (approvedMs > sinceMs) {
+        updated.push(summarize(n, approvedIso));
+      }
+      continue;
+    }
+    const createdAt = Date.parse(n.created_at || "");
+    const updatedAt = Date.parse(n.updated_at || "");
+    if (!Number.isNaN(createdAt) && createdAt > sinceMs) created.push(summarize(n));
+    else if (!Number.isNaN(updatedAt) && updatedAt > sinceMs) updated.push(summarize(n));
+    else if (publishedSince.has(n.id)) updated.push(summarize(n));
+  }
+  const canSeeDeleted = permissionLevel(c.get("nestPermission")) >= permissionLevel("write");
+  let deleted = null;
+  if (canSeeDeleted) {
+    const rows = await db.all(
+      "SELECT node_id, deleted_by, deleted_at FROM node_deletions WHERE nest_id = ? AND deleted_at > ?",
+      [nestId, new Date(sinceMs).toISOString()]
+    );
+    const liveIds = new Set(all.map((n) => n.id));
+    deleted = rows.filter((r) => !liveIds.has(r.node_id)).map((r) => ({ id: r.node_id, deleted_by: r.deleted_by, deleted_at: r.deleted_at }));
+  }
+  return c.json({
+    since: new Date(sinceMs).toISOString(),
+    now: (/* @__PURE__ */ new Date()).toISOString(),
+    created,
+    updated,
+    deleted
+  });
+});
+queryRoutes.get("/runnables", async (c) => {
+  const nestId = c.req.param("nestId");
+  const userId = c.get("userId");
+  const all = await listNodesForCaller(nestId, userId, {
+    type: RUNNABLE_NODE_TYPES
+  });
+  const runnables = all.map((n) => ({
+    id: n.id,
+    title: n.title,
+    type: n.type,
+    schedule: n.schedule ?? null,
+    status: n.status,
+    tags: n.tags,
+    updated_at: n.updated_at,
+    content: n.content
+  }));
+  return c.json({ count: runnables.length, runnables });
+});
 queryRoutes.get("/graph", async (c) => {
   const nestId = c.req.param("nestId");
   const userId = c.get("userId");
@@ -3779,6 +3918,79 @@ import { Hono as Hono7 } from "hono";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 
+// src/telemetry/trace-log.ts
+var RETENTION_DAYS = 14;
+var PRUNE_EVERY = 500;
+var insertsSincePrune = 0;
+async function logTraceEvent(e) {
+  try {
+    const db = getDb();
+    await db.run(
+      `INSERT INTO api_events
+         (ts, kind, method, path, tool, nest_id, user_id, user_email, status, duration_ms)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        (/* @__PURE__ */ new Date()).toISOString(),
+        e.kind,
+        e.method ?? null,
+        e.path ?? null,
+        e.tool ?? null,
+        e.nestId ?? null,
+        e.userId ?? null,
+        e.userEmail ?? null,
+        e.status ?? null,
+        e.durationMs ?? null
+      ]
+    );
+    if (++insertsSincePrune >= PRUNE_EVERY) {
+      insertsSincePrune = 0;
+      const cutoff = new Date(
+        Date.now() - RETENTION_DAYS * 864e5
+      ).toISOString();
+      await db.run("DELETE FROM api_events WHERE ts < ?", [cutoff]);
+    }
+  } catch {
+  }
+}
+async function listTraceEvents(filters = {}) {
+  const db = getDb();
+  const limit = Number.isFinite(filters.limit) ? Math.min(Math.max(filters.limit, 1), 1e3) : 25;
+  const offset = Number.isFinite(filters.offset) ? Math.max(filters.offset, 0) : 0;
+  const from = "FROM api_events e LEFT JOIN users u ON u.id = e.user_id";
+  const where = [];
+  const args = [];
+  if (filters.kind) {
+    where.push("e.kind = ?");
+    args.push(filters.kind);
+  }
+  if (filters.nestId) {
+    where.push("e.nest_id = ?");
+    args.push(filters.nestId);
+  }
+  if (filters.user) {
+    where.push("(COALESCE(e.user_email, u.email) LIKE ? OR e.user_id = ?)");
+    args.push(`%${filters.user}%`, filters.user);
+  }
+  const whereSql = where.length ? ` WHERE ${where.join(" AND ")}` : "";
+  try {
+    const totalRow = await db.get(
+      `SELECT COUNT(*) AS n ${from}${whereSql}`,
+      args
+    );
+    const total = Number(totalRow?.n ?? 0);
+    const events = await db.all(
+      `SELECT e.*, COALESCE(e.user_email, u.email) AS caller
+         ${from}${whereSql}
+        ORDER BY e.id DESC
+        LIMIT ? OFFSET ?`,
+      [...args, limit, offset]
+    );
+    return { events, total };
+  } catch {
+    return { events: [], total: 0 };
+  }
+}
+
 // src/mcp/tools.ts
 var MAX_HOPS = 10;
 function normalizeHops(raw) {
@@ -4084,6 +4296,26 @@ async function resolveLlmBody(ctx, node) {
   }
 }
 async function handleToolCall(toolName, args, ctx) {
+  const started = Date.now();
+  let status = 200;
+  try {
+    return await runTool(toolName, args, ctx);
+  } catch (err) {
+    status = 500;
+    throw err;
+  } finally {
+    void logTraceEvent({
+      kind: "mcp",
+      tool: toolName,
+      nestId: ctx.nestId,
+      userId: ctx.userId,
+      userEmail: ctx.userEmail,
+      status,
+      durationMs: Date.now() - started
+    });
+  }
+}
+async function runTool(toolName, args, ctx) {
   const { storage, queryEngine, versionManager, nestId, userId, userEmail } = ctx;
   switch (toolName) {
     case "context_init": {
@@ -4627,8 +4859,407 @@ mcpRoutes.all("/", async (c) => {
   }
 });
 
-// src/governance/routes.ts
+// src/mcp/server-routes.ts
 import { Hono as Hono8 } from "hono";
+import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport as WebStandardStreamableHTTPServerTransport2 } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { z as z2 } from "zod";
+async function getUserEmail3(userId) {
+  const db = getDb();
+  const user = await db.get("SELECT email FROM users WHERE id = ?", [
+    userId
+  ]);
+  return user?.email || "anonymous@localhost";
+}
+async function canRead(nestId, userId) {
+  if (config.AUTH_MODE === "open") return true;
+  const perm = await resolveNestPermission(nestId, userId);
+  return permissionLevel(perm) >= permissionLevel("read");
+}
+async function resolveNestRef(ref, userId) {
+  const db = getDb();
+  const byId = await db.get("SELECT * FROM nests WHERE id = ?", [ref]);
+  if (byId) return byId;
+  const byName = await db.all(
+    "SELECT * FROM nests WHERE LOWER(name) = LOWER(?) OR LOWER(slug) = LOWER(?)",
+    [ref, ref]
+  );
+  if (byName.length <= 1) return byName[0] ?? null;
+  const readable = (await Promise.all(
+    byName.map(async (n) => await canRead(n.id, userId) ? n : null)
+  )).filter((n) => n !== null);
+  return readable.length === 1 ? readable[0] : null;
+}
+async function buildNestIndex(userId, nestScope) {
+  const [owned, shared, publicExtras] = await Promise.all([
+    listNests(userId),
+    listSharedNests(userId),
+    listPublicNests(userId)
+  ]);
+  const seen = /* @__PURE__ */ new Set();
+  const rows = [];
+  for (const n of [...owned, ...shared, ...publicExtras]) {
+    if (seen.has(n.id)) continue;
+    if (nestScope && n.id !== nestScope) continue;
+    seen.add(n.id);
+    rows.push(n);
+  }
+  return Promise.all(
+    rows.map(async (n) => {
+      let permission = "read";
+      try {
+        permission = config.AUTH_MODE === "open" ? "owner" : await resolveNestPermission(n.id, userId);
+      } catch {
+      }
+      let document_count = null;
+      try {
+        const { storage } = await engineCache.get(n.id);
+        document_count = (await storage.discoverDocuments()).length;
+      } catch {
+      }
+      return {
+        id: n.id,
+        name: n.name,
+        description: n.description,
+        visibility: n.visibility,
+        permission,
+        document_count
+      };
+    })
+  );
+}
+function renderNestIndexMarkdown(nests, baseUrl) {
+  const lines = [
+    "# Nest index",
+    "",
+    `${nests.length} nest${nests.length === 1 ? "" : "s"} accessible with these credentials. Full interaction manual: ${baseUrl}/llms.txt`,
+    ""
+  ];
+  for (const n of nests) {
+    lines.push(`## ${n.name}`);
+    lines.push("");
+    lines.push(`- id: \`${n.id}\``);
+    if (n.description) lines.push(`- description: ${n.description}`);
+    lines.push(`- permission: ${n.permission} \xB7 visibility: ${n.visibility}`);
+    if (n.document_count !== null)
+      lines.push(`- documents: ${n.document_count}`);
+    lines.push(
+      `- retrieve: \`POST ${baseUrl}/nests/${n.id}/context\` \xB7 mcp: \`${baseUrl}/nests/${n.id}/mcp\` \xB7 export: \`${baseUrl}/nests/${n.id}/export?format=markdown\``
+    );
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+var NEST_ARG = {
+  nest: {
+    type: "string",
+    description: "Target nest \u2014 id, or exact name/slug (case-insensitive)"
+  }
+};
+var SERVER_TOOL_DEFINITIONS = [
+  {
+    name: "nest_index",
+    description: "Grounded index of every nest these credentials can read: name, id, permission, document count. Call this FIRST, then target a nest with the other tools.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "context_query",
+    description: "Run a structured selector query against one nest. Selector grammar: #tag, type:X, [[Title]], scope:X, combined with +AND, |OR, -NOT.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...NEST_ARG,
+        query: { type: "string", description: "Selector query" },
+        hops: {
+          type: "number",
+          description: "Graph traversal depth from the matches (default: 2)"
+        }
+      },
+      required: ["nest", "query"]
+    }
+  },
+  {
+    name: "context_search",
+    description: "Full-text keyword search across one nest.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...NEST_ARG,
+        query: { type: "string", description: "Search terms" }
+      },
+      required: ["nest", "query"]
+    }
+  },
+  {
+    name: "context_get",
+    description: "Get the FULL content of a node in a nest by title or id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...NEST_ARG,
+        title: { type: "string", description: "Title of the node" },
+        id: { type: "string", description: "ID of the node" }
+      },
+      required: ["nest"]
+    }
+  },
+  {
+    name: "context_list",
+    description: "Browse one nest's contents with optional type, tag, or limit filters.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...NEST_ARG,
+        type: { type: "string", description: "Filter by node type" },
+        tag: { type: "string", description: "Filter by tag" },
+        limit: { type: "number", description: "Max nodes to return" }
+      },
+      required: ["nest"]
+    }
+  },
+  {
+    name: "context_overview",
+    description: "Map of one nest: node count, types, tags, title+snippet per node.",
+    inputSchema: {
+      type: "object",
+      properties: { ...NEST_ARG },
+      required: ["nest"]
+    }
+  },
+  {
+    name: "context_resolve",
+    description: "Full deterministic context resolution against one nest \u2014 selector + hops + token budget, complete node bodies.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...NEST_ARG,
+        selector: { type: "string", description: "Selector query string" },
+        max_tokens: {
+          type: "number",
+          description: "Approximate token budget (default: 8000)"
+        },
+        hops: {
+          type: "number",
+          description: "Graph traversal depth from the matches (default: 2)"
+        }
+      },
+      required: ["nest", "selector"]
+    }
+  }
+];
+async function handleServerToolCall(toolName, args, userId, userEmail, nestScope, baseUrl) {
+  if (toolName === "nest_index") {
+    const nests = await buildNestIndex(userId, nestScope);
+    if (!nests.length) return "No nests accessible with these credentials.";
+    return renderNestIndexMarkdown(nests, baseUrl);
+  }
+  const inaccessible = `Nest not found or not accessible: "${args.nest}". Use nest_index to see what these credentials can read.`;
+  const nest = await resolveNestRef(String(args.nest ?? ""), userId);
+  if (!nest) return inaccessible;
+  if (nestScope && nest.id !== nestScope) return inaccessible;
+  if (!await canRead(nest.id, userId)) return inaccessible;
+  const engine = await engineCache.get(nest.id);
+  return handleToolCall(toolName, args, {
+    storage: engine.storage,
+    queryEngine: engine.query,
+    versionManager: engine.versions,
+    nestId: nest.id,
+    userId,
+    userEmail
+  });
+}
+function createServerMcp(userId, userEmail, nestScope, baseUrl) {
+  const server = new McpServer2(
+    { name: "contextnest-server", version: "1.0.0" },
+    { capabilities: { tools: {} } }
+  );
+  for (const tool of SERVER_TOOL_DEFINITIONS) {
+    const props = tool.inputSchema.properties || {};
+    const required = tool.inputSchema.required || [];
+    const shape = {};
+    for (const [key, def] of Object.entries(props)) {
+      let field;
+      if (def.type === "string") field = z2.string();
+      else if (def.type === "number") field = z2.number();
+      else if (def.type === "array") field = z2.array(z2.string());
+      else field = z2.any();
+      if (!required.includes(key)) field = field.optional();
+      shape[key] = field;
+    }
+    server.tool(tool.name, tool.description, shape, async (args) => {
+      const text = await handleServerToolCall(
+        tool.name,
+        args,
+        userId,
+        userEmail,
+        nestScope,
+        baseUrl
+      );
+      return { content: [{ type: "text", text }] };
+    });
+  }
+  return server;
+}
+function requestBaseUrl(reqUrl) {
+  if (config.PUBLIC_BASE_URL) return config.PUBLIC_BASE_URL;
+  try {
+    return new URL(reqUrl).origin;
+  } catch {
+    return "";
+  }
+}
+var serverMcpRoutes = new Hono8();
+serverMcpRoutes.all("/", async (c) => {
+  const userId = c.get("userId");
+  const userEmail = await getUserEmail3(userId);
+  const server = createServerMcp(
+    userId,
+    userEmail,
+    c.get("nestScope"),
+    requestBaseUrl(c.req.url)
+  );
+  const transport = new WebStandardStreamableHTTPServerTransport2({
+    sessionIdGenerator: void 0,
+    enableJsonResponse: true
+  });
+  await server.server.connect(transport);
+  try {
+    return await transport.handleRequest(c.req.raw);
+  } finally {
+    await transport.close();
+    await server.server.close();
+  }
+});
+var nestIndexRoutes = new Hono8();
+nestIndexRoutes.get("/", async (c) => {
+  const userId = c.get("userId");
+  const nests = await buildNestIndex(userId, c.get("nestScope"));
+  if (c.req.query("format") === "json") {
+    return c.json({ count: nests.length, nests });
+  }
+  const md = renderNestIndexMarkdown(nests, requestBaseUrl(c.req.url));
+  return c.text(md, 200, { "Content-Type": "text/markdown; charset=utf-8" });
+});
+function renderLlmsTxt(baseUrl) {
+  const B = baseUrl || "<server-url>";
+  return `# ContextNest Community Server
+
+Self-hosted context governance server. Nests are versioned knowledge vaults
+of markdown documents with tags, wiki-links ([[Title]]), and steward
+governance. This file is the complete interaction manual for agents.
+
+## Authentication
+
+Every request (except this file and /health): \`Authorization: Bearer cnst_<api-key>\`.
+Keys are minted in the web UI (Connect dialog \u2192 Generate Key). A key is
+either user-level (sees every nest the user can read) or scoped to one nest.
+Servers in "open" auth mode need no key.
+
+## Start here
+
+1. \`GET ${B}/index\` \u2014 your grounded nest index (markdown; \`?format=json\` for JSON).
+   One entry per accessible nest: name, id, permission, document count, and
+   the per-nest URLs below.
+2. Pick a nest id, then retrieve with the API or MCP.
+
+## Deterministic retrieval API
+
+Same inputs \u2192 same context, every time. The primary call:
+
+\`\`\`
+POST ${B}/nests/<nest-id>/context
+Content-Type: application/json
+{ "selector": "#gtm", "hops": 2, "max_tokens": 4000, "include_drafts": false }
+\`\`\`
+
+Returns \`{ context, nodes[], trace }\` \u2014 assembled markdown plus a trace with
+\`hops_used\` and \`nodes_traversed\` so you can audit exactly what was pulled.
+
+Selector grammar:
+- \`#tag\` \u2014 nodes carrying a tag
+- \`type:document\` \u2014 nodes of a type
+- \`[[Title]]\` \u2014 a node by exact title
+- \`scope:team\` \u2014 nodes by visibility scope
+- Combine: \`+AND\`, \`|OR\`, \`-NOT\` (e.g. \`#gtm+type:document-#draft\`)
+
+Graph-hop logic: \`hops\` is the traversal depth over wiki-links from the
+selector matches. \`hops: 0\` = exactly the matches; \`hops: 1\` = matches plus
+directly linked nodes; \`hops: 2\` (default) and up walk the link graph
+further out. For an exact set with no expansion, OR the selectors together
+(\`[[A]]|[[B]]\`) and pass \`hops: 0\`.
+
+Skip logic \u2014 what retrieval excludes and why:
+- Draft/unapproved documents are skipped unless \`include_drafts: true\`
+  (and public/read-only callers always get approved content only).
+- \`max_tokens\` is a budget: documents that don't fit are skipped, and the
+  trace reports \`truncated_by_budget\` so silence never means "complete".
+- Documents are deduped by id when a title match and a selector match overlap.
+
+Other read endpoints (all under \`${B}/nests/<nest-id>\`):
+- \`POST /query\` \u2014 \`{ "query": "<selector>", "hops": N }\`; matches + snippets, no bodies
+- \`GET /search?q=<terms>\` \u2014 full-text search
+- \`GET /overview\` \u2014 node count, types, tags
+- \`GET /nodes\` \u2014 list; \`GET /nodes/<node-id>?format=markdown\` \u2014 one document
+- \`GET /export?format=markdown\` \u2014 whole nest as one markdown file (optional \`selector\`, \`max_tokens\`)
+- \`GET /graph\` \u2014 ontology graph (nodes, links, tags, stewards)
+
+Write endpoints (need write permission):
+- \`POST /nodes\` \u2014 \`{ "title", "content", "tags"?, "type"?, "folder"? }\`
+- \`PATCH /nodes/<node-id>\` \u2014 \`{ "content"? , "append"?, "tags"?, "title"? }\`
+- \`DELETE /nodes/<node-id>\`
+- Governance: \`POST /nodes/<id>/submit-review\`, \`/approve\`, \`/reject\`
+
+## MCP (Model Context Protocol)
+
+Streamable HTTP, stateless. Two endpoints:
+
+- \`${B}/mcp\` \u2014 server-level, one connection for everything readable.
+  Tools: \`nest_index\` (call first), then \`context_query\`, \`context_search\`,
+  \`context_get\`, \`context_list\`, \`context_overview\`, \`context_resolve\` \u2014
+  each takes a \`nest\` argument (id or exact name) plus the same
+  selector/hops/max_tokens parameters as the REST API. Read-only.
+- \`${B}/nests/<nest-id>/mcp\` \u2014 per-nest, full toolset including writes and
+  governance (create/update, submit/approve/reject, stewards, sharing).
+
+Claude Code / Cursor / VS Code connect natively via HTTP with the
+\`Authorization: Bearer\` header. Claude Desktop needs the mcp-remote bridge:
+
+\`\`\`
+npx -y mcp-remote ${B}/mcp --header "Authorization: Bearer <api-key>"
+\`\`\`
+
+## ctx CLI (npm: @promptowl/contextnest-cli)
+
+\`npm i -g @promptowl/contextnest-cli\`
+
+- \`ctx push --server ${B} --nest <nest-id> --key <api-key>\` \u2014 upload a local
+  vault into a nest (add \`--include-drafts\` for unpublished nodes).
+- All other ctx commands (\`query\`, \`add\`, \`search\`, \`checkpoint\`) operate on
+  a LOCAL vault directory only. For remote reads use the API or MCP above \u2014
+  there is currently no remote \`ctx query\`.
+
+## npm packages
+
+- \`@promptowl/contextnest-community\` \u2014 this server
+- \`@promptowl/contextnest-cli\` \u2014 the ctx CLI
+- \`@promptowl/contextnest-engine\` \u2014 vault storage + selector/graph engine
+
+## Conventions
+
+- Node ids are paths: \`nodes/<slug>\` or nested \`nodes/<folder>/<slug>\`.
+- Tags are \`#lowercase\`. Wiki-links are \`[[Exact Title]]\`.
+- Every write is versioned and hash-chained; governed nests route writes
+  through steward review before they become AI-visible.
+`;
+}
+var llmsTxtRoutes = new Hono8();
+llmsTxtRoutes.get("/", (c) => {
+  const md = renderLlmsTxt(requestBaseUrl(c.req.url));
+  return c.text(md, 200, { "Content-Type": "text/markdown; charset=utf-8" });
+});
+
+// src/governance/routes.ts
+import { Hono as Hono9 } from "hono";
 
 // src/governance/comment-service.ts
 import { v4 as uuid4 } from "uuid";
@@ -4932,7 +5563,7 @@ function parseLimit(raw, def = 100, max = 1e3) {
   if (Number.isNaN(n) || n < 1) return def;
   return Math.min(n, max);
 }
-var governanceRoutes = new Hono8();
+var governanceRoutes = new Hono9();
 governanceRoutes.get("/stewards", async (c) => {
   const nestId = c.req.param("nestId");
   const scope = c.req.query("scope");
@@ -4961,7 +5592,7 @@ governanceRoutes.get("/stewards", async (c) => {
 governanceRoutes.post("/stewards", async (c) => {
   const nestId = c.req.param("nestId");
   const body = await c.req.json();
-  const assignedBy = await getUserEmail3(c);
+  const assignedBy = await getUserEmail4(c);
   if (!body.scope) throw new ValidationError("scope is required");
   if (body.scope === "folder") {
     throw new ValidationError(
@@ -5036,7 +5667,7 @@ governanceRoutes.get("/review-queue", async (c) => {
     limit,
     offset
   });
-  const email = await getUserEmail3(c);
+  const email = await getUserEmail4(c);
   const canReviewCache = /* @__PURE__ */ new Map();
   const requests = [];
   for (const r of result.requests) {
@@ -5060,7 +5691,7 @@ governanceRoutes.get("/external-edits", async (c) => {
 });
 governanceRoutes.post("/external-edits/scan", async (c) => {
   const nestId = c.req.param("nestId");
-  const actor = await getUserEmail3(c);
+  const actor = await getUserEmail4(c);
   const result = await scanNestForDrift(nestId, actor);
   return c.json(result);
 });
@@ -5070,7 +5701,7 @@ governanceRoutes.get("/activity", async (c) => {
   const activity = await getActivity({ nestId, limit });
   return c.json({ activity });
 });
-var governanceNodeRoutes = new Hono8();
+var governanceNodeRoutes = new Hono9();
 governanceNodeRoutes.get("/:nodeId{.+}/stewards", async (c) => {
   const nestId = c.req.param("nestId");
   const nodeId = c.req.param("nodeId");
@@ -5129,7 +5760,7 @@ governanceNodeRoutes.post("/:nodeId{.+}/comments", async (c) => {
   const nestId = c.req.param("nestId");
   const nodeId = c.req.param("nodeId");
   const body = await c.req.json();
-  const author = await getUserEmail3(c);
+  const author = await getUserEmail4(c);
   try {
     const comment = await createComment({
       nestId,
@@ -5153,7 +5784,7 @@ governanceNodeRoutes.post(
     const nestId = c.req.param("nestId");
     const nodeId = c.req.param("nodeId");
     const commentId = c.req.param("commentId");
-    const resolvedBy = await getUserEmail3(c);
+    const resolvedBy = await getUserEmail4(c);
     try {
       const comment = await resolveComment({
         nestId,
@@ -5186,7 +5817,7 @@ governanceNodeRoutes.post("/:nodeId{.+}/submit-review", async (c) => {
   if (currentVersion === 0) {
     throw new ValidationError("Node has no versions to review");
   }
-  const userEmail = await getUserEmail3(c);
+  const userEmail = await getUserEmail4(c);
   let request;
   try {
     request = await submitForReview({
@@ -5221,7 +5852,7 @@ governanceNodeRoutes.post("/:nodeId{.+}/approve", async (c) => {
   const nestId = c.req.param("nestId");
   const nodeId = c.req.param("nodeId");
   const body = await c.req.json();
-  const userEmail = await getUserEmail3(c);
+  const userEmail = await getUserEmail4(c);
   const isAdmin = isSuperAdmin(userEmail);
   try {
     const request = await approve({
@@ -5244,7 +5875,7 @@ governanceNodeRoutes.post("/:nodeId{.+}/reject", async (c) => {
   if (!body.note) {
     throw new ValidationError("Rejection note is required");
   }
-  const userEmail = await getUserEmail3(c);
+  const userEmail = await getUserEmail4(c);
   try {
     const request = await reject({
       nestId,
@@ -5261,19 +5892,19 @@ governanceNodeRoutes.post("/:nodeId{.+}/reject", async (c) => {
 governanceNodeRoutes.get("/:nodeId{.+}/can-access", async (c) => {
   const nestId = c.req.param("nestId");
   const nodeId = c.req.param("nodeId");
-  const userEmail = await getUserEmail3(c);
+  const userEmail = await getUserEmail4(c);
   return c.json(await canUserAccess(nestId, nodeId, userEmail));
 });
 governanceNodeRoutes.get("/:nodeId{.+}/can-approve", async (c) => {
   const nestId = c.req.param("nestId");
   const nodeId = c.req.param("nodeId");
-  const userEmail = await getUserEmail3(c);
+  const userEmail = await getUserEmail4(c);
   return c.json(await canUserApprove(nestId, nodeId, userEmail));
 });
 governanceNodeRoutes.get("/:nodeId{.+}/can-edit", async (c) => {
   const nestId = c.req.param("nestId");
   const nodeId = c.req.param("nodeId");
-  const userEmail = await getUserEmail3(c);
+  const userEmail = await getUserEmail4(c);
   return c.json(await canUserEdit(nestId, nodeId, userEmail));
 });
 governanceNodeRoutes.get("/:nodeId{.+?}/external-edits", async (c) => {
@@ -5306,7 +5937,7 @@ governanceNodeRoutes.post(
     const nodeId = c.req.param("nodeId");
     const suggestionId = c.req.param("suggestionId");
     const body = await c.req.json().catch(() => ({}));
-    const actor = await getUserEmail3(c);
+    const actor = await getUserEmail4(c);
     try {
       const result = await approveExternalEdit({
         nestId,
@@ -5342,7 +5973,7 @@ governanceNodeRoutes.post(
     if (!body.reason) {
       throw new ValidationError("Rejection reason is required");
     }
-    const actor = await getUserEmail3(c);
+    const actor = await getUserEmail4(c);
     try {
       const result = await rejectExternalEdit({
         nestId,
@@ -5363,7 +5994,7 @@ governanceNodeRoutes.post(
 governanceNodeRoutes.post("/:nodeId{.+}/cancel-review", async (c) => {
   const nestId = c.req.param("nestId");
   const nodeId = c.req.param("nodeId");
-  const userEmail = await getUserEmail3(c);
+  const userEmail = await getUserEmail4(c);
   const request = await cancelReview({
     nestId,
     nodeId,
@@ -5371,7 +6002,7 @@ governanceNodeRoutes.post("/:nodeId{.+}/cancel-review", async (c) => {
   });
   return c.json({ review: request });
 });
-async function getUserEmail3(c) {
+async function getUserEmail4(c) {
   const userId = c.get("userId");
   const db = getDb();
   const user = await db.get(
@@ -5381,6 +6012,30 @@ async function getUserEmail3(c) {
   return user?.email || "anonymous@localhost";
 }
 
+// src/shared/node-id.ts
+function assertSafeNodeId(rawId) {
+  let id = rawId;
+  try {
+    id = decodeURIComponent(rawId);
+  } catch {
+  }
+  if (!id || id.length > 512) {
+    throw new ValidationError("invalid node id");
+  }
+  if (id.includes("\0") || id.includes("\\")) {
+    throw new ValidationError("invalid node id");
+  }
+  if (id.startsWith("/")) {
+    throw new ValidationError("invalid node id (absolute path)");
+  }
+  for (const seg of id.split("/")) {
+    if (seg === "" || seg === "." || seg === "..") {
+      throw new ValidationError("invalid node id (path traversal)");
+    }
+  }
+  return id;
+}
+
 // src/auth/anonymous.ts
 import bcrypt from "bcryptjs";
 async function ensureAnonymousUser() {
@@ -5444,7 +6099,7 @@ var flexAuthMiddleware = createMiddleware2(async (c, next) => {
   return c.json({ error: "Missing or invalid credentials" }, 401);
 });
 function createApp() {
-  const app = new Hono9();
+  const app = new Hono10({ router: new LinearRouter() });
   const corsOrigins = config.CORS_ORIGINS;
   app.use(
     "*",
@@ -5465,6 +6120,22 @@ function createApp() {
     }
     return next();
   });
+  app.use("*", async (c, next) => {
+    const path = c.req.path;
+    const traced = /^\/(nests|auth|admin|stats|license|index|mcp)(\/|$)/.test(path) && !path.endsWith("/mcp");
+    const started = Date.now();
+    await next();
+    if (!traced) return;
+    void logTraceEvent({
+      kind: "api",
+      method: c.req.method,
+      path,
+      nestId: /^\/nests\/([^/]+)/.exec(path)?.[1] ?? null,
+      userId: c.get("userId") ?? null,
+      status: c.res.status,
+      durationMs: Date.now() - started
+    });
+  });
   app.get(
     "/health",
     (c) => c.json({
@@ -5564,7 +6235,8 @@ function createApp() {
     logo_url: config.LOGO_URL,
     telemetry_enabled: config.TELEMETRY_ENABLED,
     public_base_url: config.PUBLIC_BASE_URL,
-    max_body_bytes: config.MAX_BODY_BYTES
+    max_body_bytes: config.MAX_BODY_BYTES,
+    slack_webhook_url: config.SLACK_WEBHOOK_URL ?? ""
   });
   app.get("/admin/settings", async (c) => {
     if (!await adminSettingsAllowed(c))
@@ -5599,6 +6271,12 @@ function createApp() {
     if ("telemetry_enabled" in body) {
       pending.push({ name: "TELEMETRY_ENABLED", value: body.telemetry_enabled ? "true" : "false" });
     }
+    if ("slack_webhook_url" in body) {
+      const v = String(body.slack_webhook_url ?? "").trim();
+      if (v && !/^https:\/\//i.test(v))
+        errors.push("slack_webhook_url must be an https:// URL (or empty to disable)");
+      else pending.push({ name: "SLACK_WEBHOOK_URL", value: v || null });
+    }
     if ("max_body_bytes" in body) {
       const n = Number(body.max_body_bytes);
       if (!Number.isFinite(n) || n < 1024 * 1024 || n > 500 * 1024 * 1024)
@@ -5624,6 +6302,29 @@ function createApp() {
     }
     return c.json({ settings: currentServerSettings() });
   });
+  app.use("/admin/trace", flexAuthMiddleware);
+  const traceAllowed = async (c) => {
+    if (config.AUTH_MODE === "open") return true;
+    const userId = c.get("userId");
+    if (await isLicenseAdminUserId(userId)) return true;
+    return isSuperAdmin(await resolveCallerEmail(userId));
+  };
+  app.get("/admin/trace", async (c) => {
+    if (!await traceAllowed(c))
+      return c.json({ error: "Only the server admin can view this." }, 403);
+    const limitRaw = Number(c.req.query("limit"));
+    const offsetRaw = Number(c.req.query("offset"));
+    const limit = Number.isFinite(limitRaw) ? limitRaw : 25;
+    const offset = Number.isFinite(offsetRaw) ? offsetRaw : 0;
+    const { events, total } = await listTraceEvents({
+      limit,
+      offset,
+      kind: c.req.query("kind"),
+      nestId: c.req.query("nest") || void 0,
+      user: c.req.query("user") || void 0
+    });
+    return c.json({ count: events.length, total, limit, offset, events });
+  });
   app.use("/stats", flexAuthMiddleware);
   app.get("/stats", async (c) => {
     const db = getDb();
@@ -5650,7 +6351,12 @@ function createApp() {
       users: usersRow.c
     });
   });
-  const nestsApp = new Hono9();
+  app.route("/llms.txt", llmsTxtRoutes);
+  app.use("/index", flexAuthMiddleware);
+  app.route("/index", nestIndexRoutes);
+  app.use("/mcp", flexAuthMiddleware);
+  app.route("/mcp", serverMcpRoutes);
+  const nestsApp = new Hono10();
   nestsApp.use("*", flexAuthMiddleware);
   nestsApp.use("*", async (c, next) => {
     const localPath = c.req.path.replace(/^\/nests\//, "");
@@ -5759,10 +6465,14 @@ function createApp() {
     c.set("nestPermission", permission);
     return next();
   });
+  nestsApp.use("/:nestId/nodes/:nodeId{.+}", async (c, next) => {
+    assertSafeNodeId(c.req.param("nodeId"));
+    return next();
+  });
   nestsApp.route("/", nestRoutes);
   nestsApp.route("/:nestId", governanceRoutes);
-  nestsApp.route("/:nestId/nodes", governanceNodeRoutes);
   nestsApp.route("/:nestId/nodes", annotationRoutes);
+  nestsApp.route("/:nestId/nodes", governanceNodeRoutes);
   nestsApp.route("/:nestId/nodes", nodeRoutes);
   nestsApp.route("/:nestId", queryRoutes);
   nestsApp.route("/:nestId", sharingRoutes);