@promptowl/contextnest-community 1.7.0 → 1.9.0

package/dist/index.js

@@ -1,22 +1,35 @@
 #!/usr/bin/env node
-import {
-  generateApiKey,
-  getKeyPrefix,
-  hashApiKey,
-  hashPassword,
-  parseBearerToken,
-  verifyPassword
-} from "./chunk-XRK6SQSC.js";
 import {
   approve,
   cancelReview,
   getPendingReview,
   getReviewHistory,
   getReviewQueue,
+  notifyNestEvent,
   reject,
   safePublishDocument,
   submitForReview
-} from "./chunk-MOXICJPD.js";
+} from "./chunk-VC3QNHHB.js";
+import {
+  createGrant,
+  deleteGrant,
+  grantCoversNode,
+  hasAnyGrant,
+  listGrants,
+  listUserGrants,
+  resolveNodeGrant
+} from "./chunk-TIO5XOFD.js";
+import {
+  generateApiKey,
+  getKeyPrefix,
+  hashApiKey,
+  hashPassword,
+  parseBearerToken,
+  verifyPassword
+} from "./chunk-XRK6SQSC.js";
+import {
+  normalizeEmail
+} from "./chunk-FRQJWGN3.js";
 import {
   checkConflict,
   createVersion,
@@ -25,14 +38,8 @@ import {
   getDisplayStatus,
   getVersions,
   setApprovedVersion
-} from "./chunk-VD5QX2ZQ.js";
+} from "./chunk-HRQWNRVI.js";
 import {
-  AppError,
-  ConflictError,
-  ForbiddenError,
-  LockedError,
-  NotFoundError,
-  ValidationError,
   canCreateInNest,
   canManageStewards,
   canUserAccess,
@@ -43,6 +50,7 @@ import {
   createStewardRecord,
   deleteNest,
   disableStewardshipAndWipeGovernance,
+  docLink,
   engineCache,
   getCollaboratorRole,
   getCurrentLicense,
@@ -65,6 +73,7 @@ import {
   listStewards,
   loadAccessConfig,
   nestAllowsSelfApprove,
+  nestName,
   nestStorageRoot,
   permissionLevel,
   removeSteward,
@@ -84,14 +93,26 @@ import {
   updateSteward,
   upsertEnvVar,
   validateLicense
-} from "./chunk-43DOX4LH.js";
+} from "./chunk-BYS4HDME.js";
+import {
+  AppError,
+  ConflictError,
+  ForbiddenError,
+  LockedError,
+  NotFoundError,
+  ValidationError
+} from "./chunk-3JTODC3Y.js";
+import {
+  insertOrIgnore,
+  nowExpr
+} from "./chunk-XQ46F76G.js";
 import {
   config,
   getDb,
   initDb,
-  insertOrIgnore,
-  nowExpr
-} from "./chunk-QMLAXQES.js";
+  isEmailListish,
+  isEmailish
+} from "./chunk-DPHV6Q26.js";
 import {
   ANON_EMAIL,
   ANON_USER_ID
@@ -101,7 +122,8 @@ import {
 import { serve } from "@hono/node-server";
 
 // src/app.ts
-import { Hono as Hono9 } from "hono";
+import { Hono as Hono16 } from "hono";
+import { LinearRouter } from "hono/router/linear-router";
 import { createMiddleware as createMiddleware2 } from "hono/factory";
 import { cors } from "hono/cors";
 
@@ -227,11 +249,6 @@ var authMiddleware = createMiddleware(async (c, next) => {
   return c.json({ error: "Missing or invalid credentials" }, 401);
 });
 
-// src/shared/email.ts
-function normalizeEmail(email) {
-  return email.trim().toLowerCase();
-}
-
 // src/shared/rate-limit.ts
 var buckets = /* @__PURE__ */ new Map();
 function liveBucket(key, cutoff) {
@@ -1084,7 +1101,8 @@ async function canReadNode(nestId, nodeId, userId, userEmail) {
     return await getApprovedVersion(nestId, nodeId) !== null;
   }
   if (!await isStewardshipEnabled(nestId)) return true;
-  return (await canUserAccess(nestId, nodeId, userEmail)).allowed;
+  if ((await canUserAccess(nestId, nodeId, userEmail)).allowed) return true;
+  return await resolveNodeGrant(nestId, userId, nodeId) !== null;
 }
 async function filterAccessible(nestId, userId, userEmail, nodes) {
   if (await isPublicReader(nestId, userId)) {
@@ -1097,9 +1115,10 @@ async function filterAccessible(nestId, userId, userEmail, nodes) {
     return filtered;
   }
   if (!await isStewardshipEnabled(nestId)) return nodes;
+  const grants = await listUserGrants(nestId, userId);
   const accessible = [];
   for (const n of nodes) {
-    if ((await canUserAccess(nestId, n.id, userEmail)).allowed) {
+    if ((await canUserAccess(nestId, n.id, userEmail)).allowed || grantCoversNode(grants, n.id)) {
       accessible.push(n);
     }
   }
@@ -1289,7 +1308,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-6J4OWQL6.js");
     await createVersion2({
       nestId: input.nestId,
       nodeId: input.documentId,
@@ -1375,6 +1394,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 +1414,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);
@@ -1407,7 +1436,11 @@ async function listNodesForCaller(nestId, userId, filters = {}) {
     );
   }
   const userEmail = await resolveCallerEmail(userId);
-  const accessible = await filterAccessible(nestId, userId, userEmail, documents);
+  let accessible = await filterAccessible(nestId, userId, userEmail, documents);
+  if (await resolveNestPermission(nestId, userId) === "none" && !await isStewardshipEnabled(nestId)) {
+    const grants = await listUserGrants(nestId, userId);
+    accessible = grants.length ? documents.filter((d) => grantCoversNode(grants, d.id)) : accessible;
+  }
   const publicReader = await isPublicReader(nestId, userId);
   const enriched = await Promise.all(
     accessible.map(async (doc) => {
@@ -1464,6 +1497,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 +1516,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: ""
@@ -1545,9 +1587,18 @@ async function registerImportedDocuments(nestId, userEmail) {
     return 0;
   }
   let registered = 0;
-  for (const doc of docs) {
+  for (let doc of docs) {
     const nodeId = doc.id;
     if (await getCurrentVersion(nestId, nodeId) > 0) continue;
+    if (!doc.frontmatter?.title) {
+      const title = nodeId.split("/").pop() || nodeId;
+      doc = { ...doc, frontmatter: { ...doc.frontmatter, title } };
+      try {
+        await storage.writeDocument(nodeId, serializeDocument(doc));
+      } catch (err) {
+        console.error("import: failed to persist filename title", nodeId, err);
+      }
+    }
     const rawTags = Array.isArray(doc.frontmatter?.tags) ? doc.frontmatter.tags : [];
     const tags = rawTags.map((t) => normalizeTag2(String(t)));
     const fmVersion = Number(doc.frontmatter?.version);
@@ -1605,6 +1656,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)) {
@@ -1849,13 +1911,13 @@ async function syncUnsyncedFolder(userId, folderName, callerEmail) {
   }
   const segments = folderName.split("/").filter(Boolean);
   const baseName = segments[segments.length - 1] || folderName;
-  const nestName = await uniqueNestName(userId, baseName);
-  if (nestName !== baseName) {
+  const nestName2 = await uniqueNestName(userId, baseName);
+  if (nestName2 !== baseName) {
     console.log(
-      `[unsynced] name "${baseName}" already in use, using "${nestName}" instead`
+      `[unsynced] name "${baseName}" already in use, using "${nestName2}" instead`
     );
   }
-  const nest = await importNest(userId, nestName, files);
+  const nest = await importNest(userId, nestName2, files);
   console.log(
     `[unsynced] nest created id=${nest.id} name="${nest.name}" from folder="${folderName}"`
   );
@@ -1913,7 +1975,14 @@ nestRoutes.get("/", async (c) => {
       const row = await db.get(ownerEmailSql, [n.user_id]);
       owner_email = row?.email ?? null;
     }
-    return { ...n, permission, is_owner, owner_email, roles };
+    return {
+      ...n,
+      permission,
+      is_owner,
+      owner_email,
+      roles,
+      stewardship_enabled: await isStewardshipEnabled(n.id)
+    };
   };
   const seen = /* @__PURE__ */ new Set();
   const out = [];
@@ -2165,12 +2234,36 @@ async function addCollaborator(params) {
     "INSERT INTO nest_collaborators (id, nest_id, user_id, permission, granted_by) VALUES (?, ?, ?, ?, ?)",
     [collabId, nestId, userId, params.permission, granterId]
   );
+  const shareNestName = await nestName(nestId);
+  void notifyNestEvent(
+    nestId,
+    `:key: ${params.email || userId} added as *${params.permission}*${params.grantedByEmail ? ` by ${params.grantedByEmail}` : ""}`,
+    {
+      status: "shared",
+      docTitle: shareNestName,
+      path: shareNestName,
+      link: docLink(nestId, void 0, params.baseUrl),
+      actor: params.email || userId,
+      permission: params.permission,
+      by: params.grantedByEmail || void 0
+    }
+  );
   return await db.get(
     "SELECT * FROM nest_collaborators WHERE id = ?",
     [collabId]
   );
 }
 
+// src/shared/base-url.ts
+function requestBaseUrl(reqUrl) {
+  if (config.PUBLIC_BASE_URL) return config.PUBLIC_BASE_URL;
+  try {
+    return new URL(reqUrl).origin;
+  } catch {
+    return "";
+  }
+}
+
 // src/nests/sharing-routes.ts
 var sharingRoutes = new Hono3();
 sharingRoutes.get("/collaborators", async (c) => {
@@ -2207,7 +2300,8 @@ sharingRoutes.post("/collaborators", async (c) => {
     grantedByUserId: c.get("userId"),
     // Enforce the escalation cap against the caller's own nest permission
     // (set by the access guard) — a write collaborator can't grant admin.
-    callerPermission: c.get("nestPermission")
+    callerPermission: c.get("nestPermission"),
+    baseUrl: requestBaseUrl(c.req.url)
   });
   return c.json({ collaborator: collab }, 201);
 });
@@ -2243,15 +2337,93 @@ sharingRoutes.patch("/visibility", async (c) => {
     throw new ValidationError("visibility must be private or public");
   }
   const db = getDb();
-  await db.run("UPDATE nests SET visibility = ? WHERE id = ?", [
+  const nestId = c.req.param("nestId");
+  const result = await db.run("UPDATE nests SET visibility = ? WHERE id = ?", [
     body.visibility,
-    c.req.param("nestId")
+    nestId
+  ]);
+  if (result.changes === 0) {
+    throw new NotFoundError("Nest not found");
+  }
+  const row = await db.get("SELECT visibility FROM nests WHERE id = ?", [
+    nestId
   ]);
-  return c.json({ visibility: body.visibility });
+  return c.json({ visibility: row.visibility });
 });
 
-// src/nodes/routes.ts
+// src/nests/grant-routes.ts
 import { Hono as Hono4 } from "hono";
+import { v4 as uuid3 } from "uuid";
+var grantRoutes = new Hono4();
+async function requireManage(c, nestId) {
+  if (!await canManageStewards(nestId, c.get("userId"))) {
+    throw new ForbiddenError(
+      "Only a nest admin, the nest owner, or the server admin can manage sharing."
+    );
+  }
+}
+async function resolveGrantee(email) {
+  const db = getDb();
+  const e = normalizeEmail(email);
+  const existing = await db.get("SELECT id FROM users WHERE LOWER(email) = ?", [e]);
+  if (existing) return existing.id;
+  const { hashPassword: hashPassword2 } = await import("./keys-73STFJJB.js");
+  const id = uuid3();
+  await db.run(
+    "INSERT INTO users (id, email, name, password_hash, is_invited) VALUES (?, ?, ?, ?, 1)",
+    [id, e, null, await hashPassword2(uuid3())]
+  );
+  return id;
+}
+grantRoutes.post("/", async (c) => {
+  const nestId = c.req.param("nestId");
+  await requireManage(c, nestId);
+  const body = await c.req.json();
+  const targetType = body.target_type;
+  const target = (body.target || "").trim();
+  const role = body.role || "read";
+  if (!["document", "folder"].includes(targetType)) {
+    throw new ValidationError("target_type must be document | folder");
+  }
+  if (!target) throw new ValidationError("target is required");
+  if (!body.email?.trim()) throw new ValidationError("email is required");
+  if (!["read", "write"].includes(role)) {
+    throw new ValidationError("role must be read | write");
+  }
+  const userId = await resolveGrantee(body.email);
+  const grant = await createGrant({
+    nestId,
+    targetType,
+    target,
+    userId,
+    role,
+    grantedBy: await resolveCallerEmail(c.get("userId"))
+  });
+  return c.json({ grant }, 201);
+});
+grantRoutes.get("/", async (c) => {
+  const nestId = c.req.param("nestId");
+  await requireManage(c, nestId);
+  const grants = await listGrants(nestId);
+  const db = getDb();
+  const withEmail = await Promise.all(
+    grants.map(async (g) => {
+      const u = await db.get("SELECT email FROM users WHERE id = ?", [g.user_id]);
+      return { ...g, email: u?.email ?? null };
+    })
+  );
+  return c.json({ count: withEmail.length, grants: withEmail });
+});
+grantRoutes.delete("/:id", async (c) => {
+  const nestId = c.req.param("nestId");
+  await requireManage(c, nestId);
+  const ok = await deleteGrant(nestId, c.req.param("id"));
+  if (!ok) throw new NotFoundError("Grant not found");
+  return c.json({ deleted: true });
+});
+
+// src/nodes/routes.ts
+import { Hono as Hono5 } from "hono";
 
 // src/nodes/markdown-export.ts
 function nodeToMarkdown(node) {
@@ -2274,7 +2446,7 @@ function isMarkdownFormat(c) {
 }
 
 // src/annotations/service.ts
-import { v4 as uuid3 } from "uuid";
+import { v4 as uuid4 } from "uuid";
 
 // src/annotations/projection.ts
 var MAX_CONTEXT_CHARS = 250;
@@ -2424,7 +2596,7 @@ async function createThread(nestId, nodeId, input, authorEmail) {
     throw new Error("comment body is required");
   }
   const db = getDb();
-  const id = uuid3();
+  const id = uuid4();
   const anchor = clampAnchor(input.anchor);
   const snapshot = input.snapshotVersion ?? await getApprovedVersion(nestId, nodeId) ?? null;
   await db.transaction(async (tx) => {
@@ -2443,7 +2615,7 @@ async function createThread(nestId, nodeId, input, authorEmail) {
     );
     await tx.run(
       "INSERT INTO annotation_comments (id, thread_id, author, body) VALUES (?, ?, ?, ?)",
-      [uuid3(), id, authorEmail, body]
+      [uuid4(), id, authorEmail, body]
     );
   });
   return rowToThread(await getThreadRow(id));
@@ -2463,7 +2635,7 @@ async function addComment(nestId, nodeId, threadId, authorEmail, body) {
   await getScopedThreadRow(threadId, nestId, nodeId);
   await getDb().run(
     "INSERT INTO annotation_comments (id, thread_id, author, body) VALUES (?, ?, ?, ?)",
-    [uuid3(), threadId, authorEmail, trimmed]
+    [uuid4(), threadId, authorEmail, trimmed]
   );
   return rowToThread(await getThreadRow(threadId));
 }
@@ -2562,7 +2734,7 @@ async function syncAnnotationsNode(nestId, nodeId, userEmail) {
 }
 
 // src/nodes/routes.ts
-var nodeRoutes = new Hono4();
+var nodeRoutes = new Hono5();
 function nodeAsMarkdown(response, nodeId) {
   return nodeToMarkdown({
     id: nodeId,
@@ -2597,6 +2769,7 @@ nodeRoutes.post("/", async (c) => {
       tags: body.tags,
       scope: body.scope,
       status: body.status,
+      schedule: body.schedule,
       folder: body.folder
     },
     authorEmail
@@ -2614,7 +2787,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-3KCVVXCW.js");
   const { stewards, fallbackToOwner, ownerEmail } = await resolveStewardsWithFallback2(
     nestId,
     nodeId
@@ -2635,7 +2808,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-6J4OWQL6.js");
   const allVersions = await getVersions2(nestId, nodeId);
   const approved = await getApprovedVersion2(nestId, nodeId);
   const db = getDb();
@@ -2667,7 +2840,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-A3XFQTJH.js");
   const history = await getReviewHistory2(nestId, nodeId);
   return c.json({ reviews: history });
 });
@@ -2814,7 +2987,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 +3054,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 });
@@ -2892,13 +3073,13 @@ async function getUserEmail(c) {
 }
 
 // src/annotations/routes.ts
-import { Hono as Hono5 } from "hono";
+import { Hono as Hono6 } from "hono";
 
 // src/annotations/types.ts
 var ARTIFACT_NODE_TYPE = "artifact";
 
 // src/annotations/routes.ts
-var annotationRoutes = new Hono5();
+var annotationRoutes = new Hono6();
 function getNodeId(c) {
   const raw = c.req.param("nodeId");
   try {
@@ -3025,7 +3206,7 @@ annotationRoutes.get("/:nodeId{.+}/hosted", async (c) => {
 });
 
 // src/nodes/query-routes.ts
-import { Hono as Hono6 } from "hono";
+import { Hono as Hono7 } from "hono";
 import { serializeDocument as serializeDocument2 } from "@promptowl/contextnest-engine";
 
 // src/nodes/prompt-compiler.ts
@@ -3247,6 +3428,10 @@ async function resolveExportBody(nestId, nodeId, workingBody) {
 // src/nodes/graph-service.ts
 var MAX_GRAPH_NODES = 150;
 var WIKILINK_RE = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
+function bareSlug(idOrTarget) {
+  const idx = idOrTarget.lastIndexOf("/");
+  return idx >= 0 ? idOrTarget.slice(idx + 1) : idOrTarget;
+}
 function extractWikiTargets(body) {
   const out = [];
   if (!body) return out;
@@ -3264,9 +3449,12 @@ async function buildNestGraph(nestId, userId, userEmail, canSeeIdentities) {
   const accessible = await filterAccessible(nestId, userId, userEmail, docs);
   const idSet = new Set(accessible.map((d) => d.id));
   const titleToId = /* @__PURE__ */ new Map();
+  const slugToId = /* @__PURE__ */ new Map();
   for (const d of accessible) {
     const t = (d.frontmatter?.title || "").toLowerCase().trim();
     if (t && !titleToId.has(t)) titleToId.set(t, d.id);
+    const slug = bareSlug(d.id).toLowerCase();
+    if (slug && !slugToId.has(slug)) slugToId.set(slug, d.id);
   }
   const allNodes = accessible.map((d) => ({
     id: d.id,
@@ -3278,7 +3466,8 @@ async function buildNestGraph(nestId, userId, userEmail, canSeeIdentities) {
   const seen = /* @__PURE__ */ new Set();
   for (const d of accessible) {
     for (const raw of extractWikiTargets(d.body || "")) {
-      const targetId = idSet.has(raw) ? raw : titleToId.get(raw.toLowerCase().trim());
+      const norm = raw.toLowerCase().trim();
+      const targetId = idSet.has(raw) ? raw : titleToId.get(norm) ?? slugToId.get(bareSlug(raw).toLowerCase());
       if (!targetId || targetId === d.id) continue;
       const key = `${d.id}->${targetId}`;
       if (seen.has(key)) continue;
@@ -3387,13 +3576,124 @@ async function buildNestGraph(nestId, userId, userEmail, canSeeIdentities) {
 }
 
 // src/nodes/query-routes.ts
-var queryRoutes = new Hono6();
+var queryRoutes = new Hono7();
+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");
   const userEmail = await resolveCallerEmail(userId);
   const canSeeIdentities = permissionLevel(c.get("nestPermission")) >= permissionLevel("write");
   const graph = await buildNestGraph(nestId, userId, userEmail, canSeeIdentities);
+  if (config.FEATURE_WORKFLOW_PLANE) {
+    const rows = await getDb().all(
+      `SELECT e.from_node, e.to_node, e.condition_mode, t.name as type, t.color, t.is_flow
+         FROM edges e JOIN edge_types t ON t.id = e.type_id
+        WHERE e.nest_id = ?`,
+      [nestId]
+    );
+    const visible = new Set(graph.nodes.map((n) => n.id));
+    graph.typedEdges = rows.filter((r) => visible.has(r.from_node) && visible.has(r.to_node)).map((r) => ({
+      source: r.from_node,
+      target: r.to_node,
+      type: r.type,
+      color: r.color,
+      is_flow: !!r.is_flow,
+      condition_mode: r.condition_mode
+    }));
+  }
   return c.json(graph);
 });
 function approxTokens(text) {
@@ -3775,89 +4075,1262 @@ queryRoutes.post("/publish", async (c) => {
 });
 
 // src/mcp/routes.ts
-import { Hono as Hono7 } from "hono";
+import { Hono as Hono10 } from "hono";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 
-// src/mcp/tools.ts
-var MAX_HOPS = 10;
-function normalizeHops(raw) {
-  if (raw == null) return 2;
-  const n = Number(raw);
-  if (!Number.isFinite(n)) return 2;
-  return Math.max(0, Math.min(MAX_HOPS, Math.floor(n)));
-}
-var TOOL_DEFINITIONS = [
-  {
-    name: "context_init",
-    description: "Load the vault's CONTEXT.md which contains operating instructions and behavioral guidelines. Call this FIRST in every conversation.",
-    inputSchema: { type: "object", properties: {} }
-  },
-  {
-    name: "context_overview",
-    description: "Get a complete map of the vault: total node count, types, tags, and a title+snippet for every node.",
-    inputSchema: { type: "object", properties: {} }
-  },
-  {
-    name: "context_search",
-    description: "Full-text keyword search across all node content, titles, tags, and metadata.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: { type: "string", description: "Search terms" }
-      },
-      required: ["query"]
+// 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]);
     }
-  },
-  {
-    name: "context_query",
-    description: "Run a structured selector query. Supports: #tag, type:X, [[Title]], scope:X. Combine with +AND, |OR, -NOT.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: { type: "string", description: "Selector query" },
-        hops: {
-          type: "number",
-          description: "Graph traversal depth from the matched nodes (default: 2). Use 1 for just the matches + direct links, higher to pull in more of the neighborhood."
-        }
-      },
-      required: ["query"]
+  } 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/workflow-tools.ts
+import { v4 as uuid8 } from "uuid";
+
+// 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)");
     }
-  },
-  {
-    name: "context_get",
-    description: "Get the FULL content of a specific node by title or ID.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        title: { type: "string", description: "Title of the node" },
-        id: { type: "string", description: "ID of the node" }
+  }
+  return id;
+}
+
+// src/workflow/run-service.ts
+import { v4 as uuid5 } from "uuid";
+
+// src/shared/json.ts
+var safeJson = (s) => {
+  if (!s) return null;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+};
+
+// src/workflow/run-service.ts
+var RUNNABLE_TYPES = ["agent", "skill"];
+async function flowSubgraph(nestId, agentNode) {
+  const db = getDb();
+  const rows = await db.all(
+    `SELECT e.id, e.from_node, e.to_node, e.condition_mode, e.condition, e.metadata,
+            t.name as type_name, t.color as type_color
+       FROM edges e JOIN edge_types t ON t.id = e.type_id
+      WHERE e.nest_id = ? AND t.is_flow = 1`,
+    [nestId]
+  );
+  const byFrom = /* @__PURE__ */ new Map();
+  for (const r of rows) {
+    if (!byFrom.has(r.from_node)) byFrom.set(r.from_node, []);
+    byFrom.get(r.from_node).push(r);
+  }
+  const seen = /* @__PURE__ */ new Set([agentNode]);
+  const queue = [agentNode];
+  const edges = [];
+  while (queue.length) {
+    const cur = queue.shift();
+    for (const e of byFrom.get(cur) ?? []) {
+      edges.push(e);
+      if (!seen.has(e.to_node)) {
+        seen.add(e.to_node);
+        queue.push(e.to_node);
       }
     }
-  },
-  {
-    name: "context_list",
-    description: "Browse vault contents with optional type, tag, or limit filters.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        type: { type: "string", description: "Filter by node type" },
-        tag: { type: "string", description: "Filter by tag" },
-        limit: { type: "number", description: "Max nodes to return" }
-      }
+  }
+  return edges.map((e) => ({
+    id: e.id,
+    from_node: e.from_node,
+    to_node: e.to_node,
+    type: { name: e.type_name, color: e.type_color },
+    condition_mode: e.condition_mode,
+    condition: e.condition_mode === "structured" ? safeJson(e.condition) : e.condition,
+    metadata: safeJson(e.metadata)
+  }));
+}
+async function referencedDefinitions(nestId, edges) {
+  const terms = /* @__PURE__ */ new Set();
+  for (const e of edges) {
+    if (e.condition_mode === "structured" && e.condition && typeof e.condition === "object") {
+      const t = e.condition.term;
+      if (typeof t === "string" && t.trim()) terms.add(t.trim());
     }
-  },
-  {
-    name: "context_resolve",
-    description: "Full context resolution \u2014 run a selector and return complete node content, respecting a token budget.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        selector: {
-          type: "string",
-          description: "Selector query string"
-        },
-        max_tokens: {
+  }
+  if (!terms.size) return [];
+  try {
+    const db = getDb();
+    const list = [...terms];
+    const placeholders = list.map(() => "LOWER(?)").join(", ");
+    const rows = await db.all(
+      `SELECT term, definition, linked_tag FROM definitions
+        WHERE nest_id = ? AND LOWER(term) IN (${placeholders})`,
+      [nestId, ...list]
+    );
+    return rows;
+  } catch {
+    return [];
+  }
+}
+async function resolveParentRun(nestId, parentRunId, childAgent) {
+  if (!config.FEATURE_SUBAGENT_RUNS) {
+    throw new ValidationError(
+      "Sub-agent runs are not enabled on this server (FEATURE_SUBAGENT_RUNS)."
+    );
+  }
+  const db = getDb();
+  let cursor = parentRunId;
+  let parentDepth = -1;
+  for (let i = 0; i <= config.SUBAGENT_MAX_DEPTH + 1; i++) {
+    if (!cursor) break;
+    const row = await db.get(
+      "SELECT id, nest_id, agent_node, status, depth, parent_run_id FROM runs WHERE id = ?",
+      [cursor]
+    );
+    if (!row || row.nest_id !== nestId) {
+      throw new NotFoundError(`Parent run not found: ${cursor}`);
+    }
+    if (cursor === parentRunId && row.status !== "running") {
+      throw new ConflictError(
+        `Parent run is ${row.status} \u2014 cannot spawn a sub-agent under a closed run`
+      );
+    }
+    if (row.agent_node === childAgent) {
+      throw new ConflictError(
+        `re-entrancy: "${childAgent}" is already running in this call chain \u2014 sub-agent recursion must be acyclic`
+      );
+    }
+    if (cursor === parentRunId) parentDepth = row.depth;
+    cursor = row.parent_run_id;
+  }
+  const depth = parentDepth + 1;
+  if (depth > config.SUBAGENT_MAX_DEPTH) {
+    throw new ForbiddenError(
+      `sub-agent depth ${depth} exceeds the limit of ${config.SUBAGENT_MAX_DEPTH}`
+    );
+  }
+  return { depth };
+}
+async function loadRun(runId) {
+  return await getDb().get("SELECT * FROM runs WHERE id = ?", [runId]);
+}
+async function triggerRun(opts) {
+  const { nestId, inputs, triggeredBy, storage } = opts;
+  const agentNode = assertSafeNodeId(opts.agentNode);
+  let doc;
+  try {
+    doc = await storage.readDocument(agentNode);
+  } catch {
+    throw new NotFoundError(`Agent node not found: ${agentNode}`);
+  }
+  const nodeType = doc.frontmatter.type || "document";
+  if (!RUNNABLE_TYPES.includes(nodeType)) {
+    throw new ValidationError(
+      `"${agentNode}" is type "${nodeType}" \u2014 only agent/skill nodes are runnable`
+    );
+  }
+  let parentRunId = null;
+  let depth = 0;
+  if (opts.parentRunId !== void 0 && opts.parentRunId !== null) {
+    if (typeof opts.parentRunId !== "string") {
+      throw new ValidationError("parent_run_id must be a string");
+    }
+    ({ depth } = await resolveParentRun(nestId, opts.parentRunId, agentNode));
+    parentRunId = opts.parentRunId;
+  }
+  const edges = await flowSubgraph(nestId, agentNode);
+  const definitions = await referencedDefinitions(nestId, edges);
+  const id = `run_${uuid5()}`;
+  const db = getDb();
+  await db.transaction(async (tx) => {
+    if (parentRunId) {
+      if (db.dialect === "postgres") {
+        await tx.get("SELECT id FROM runs WHERE id = ? FOR UPDATE", [parentRunId]);
+      }
+      const kids = await tx.get(
+        "SELECT COUNT(*) as c FROM runs WHERE parent_run_id = ?",
+        [parentRunId]
+      );
+      if (Number(kids.c) >= config.SUBAGENT_MAX_CHILDREN) {
+        throw new ForbiddenError(
+          `parent run already has ${kids.c} children (limit ${config.SUBAGENT_MAX_CHILDREN})`
+        );
+      }
+    }
+    await tx.run(
+      `INSERT INTO runs (id, nest_id, agent_node, triggered_by, status, inputs, started_at, parent_run_id, depth)
+       VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?)`,
+      [
+        id,
+        nestId,
+        agentNode,
+        triggeredBy,
+        inputs === void 0 ? null : JSON.stringify(inputs),
+        (/* @__PURE__ */ new Date()).toISOString(),
+        parentRunId,
+        depth
+      ]
+    );
+  });
+  return {
+    run_id: id,
+    parent_run_id: parentRunId,
+    depth,
+    agent: {
+      id: agentNode,
+      title: String(doc.frontmatter.title ?? agentNode),
+      type: nodeType,
+      schedule: doc.frontmatter.metadata?.schedule ?? null,
+      content: doc.body || ""
+    },
+    edges,
+    definitions,
+    trace_hint: {
+      retrieval: "POST /context is deterministic \u2014 record selector+hops per read so the run replays to the identical read-set",
+      steps: "POST /runs/{run_id}/steps per action; PATCH /runs/{run_id} to close"
+    }
+  };
+}
+var STEP_ACTIONS = ["read", "write", "branch", "notify", "external"];
+async function appendRunStep(runId, input) {
+  if (typeof input.action !== "string" || !input.action.trim()) {
+    throw new ValidationError("action is required (read|write|branch|notify|external)");
+  }
+  const action = input.action.trim();
+  if (!STEP_ACTIONS.includes(action)) {
+    throw new ValidationError(
+      "action must be read | write | branch | notify | external"
+    );
+  }
+  const nodeId = typeof input.node_id === "string" ? input.node_id : null;
+  const edgeId = typeof input.edge_id === "string" ? input.edge_id : null;
+  const detail = input.detail === void 0 ? null : JSON.stringify(input.detail);
+  const db = getDb();
+  let seq = 0;
+  await db.transaction(async (tx) => {
+    const cur = await tx.get("SELECT status FROM runs WHERE id = ?", [runId]);
+    if (!cur) throw new NotFoundError("Run not found");
+    if (cur.status !== "running") {
+      throw new ConflictError(
+        `Run is ${cur.status} \u2014 steps can't be appended`
+      );
+    }
+    const last = await tx.get(
+      "SELECT MAX(seq) as m FROM run_steps WHERE run_id = ?",
+      [runId]
+    );
+    seq = (Number(last.m) || 0) + 1;
+    if (seq > config.RUN_MAX_STEPS) {
+      throw new ConflictError(
+        `Run has reached the step limit of ${config.RUN_MAX_STEPS} \u2014 no more steps can be appended`
+      );
+    }
+    await tx.run(
+      `INSERT INTO run_steps (run_id, seq, node_id, edge_id, action, detail, at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      [runId, seq, nodeId, edgeId, action, detail, (/* @__PURE__ */ new Date()).toISOString()]
+    );
+  });
+  return { seq };
+}
+var RUN_STATUSES = ["running", "succeeded", "failed", "cancelled"];
+async function closeRun(runId, input) {
+  const status = input.status;
+  if (typeof status !== "string" || !RUN_STATUSES.includes(status)) {
+    throw new ValidationError("status must be running | succeeded | failed | cancelled");
+  }
+  const terminal = status !== "running";
+  const res = await getDb().run(
+    `UPDATE runs SET status = ?, trace = COALESCE(?, trace), finished_at = ?
+      WHERE id = ? AND status = 'running'`,
+    [
+      status,
+      input.trace === void 0 ? null : JSON.stringify(input.trace),
+      terminal ? (/* @__PURE__ */ new Date()).toISOString() : null,
+      runId
+    ]
+  );
+  if (res.changes === 0) {
+    const run = await loadRun(runId);
+    if (!run) throw new NotFoundError("Run not found");
+    throw new ConflictError("Run already terminal \u2014 status can't be changed");
+  }
+  return { status };
+}
+async function getRunTrace(run, opts) {
+  const { canSeeDetail } = opts;
+  const steps = await getDb().all(
+    "SELECT seq, node_id, edge_id, action, detail, at FROM run_steps WHERE run_id = ? ORDER BY seq",
+    [run.id]
+  );
+  return {
+    run: {
+      ...run,
+      inputs: canSeeDetail ? safeJson(run.inputs) : null,
+      trace: canSeeDetail ? safeJson(run.trace) : null
+    },
+    steps: steps.map((s) => ({
+      ...s,
+      detail: canSeeDetail ? safeJson(s.detail) : null
+    }))
+  };
+}
+async function listRuns(nestId, opts) {
+  const db = getDb();
+  let sql = "SELECT * FROM runs WHERE nest_id = ?";
+  const args = [nestId];
+  if (opts.agent) {
+    sql += " AND agent_node = ?";
+    args.push(opts.agent);
+  }
+  if (opts.status) {
+    sql += " AND status = ?";
+    args.push(opts.status);
+  }
+  sql += " ORDER BY started_at DESC LIMIT ?";
+  args.push(Math.min(Math.max(Number(opts.limit) || 50, 1), 500));
+  const rows = await db.all(sql, args);
+  return {
+    count: rows.length,
+    runs: rows.map((r) => ({
+      ...r,
+      inputs: opts.canSeeDetail ? safeJson(r.inputs) : null,
+      trace: opts.canSeeDetail ? safeJson(r.trace) : null
+    }))
+  };
+}
+
+// src/workflow/edge-routes.ts
+import { Hono as Hono9 } from "hono";
+import { v4 as uuid7 } from "uuid";
+
+// src/workflow/edge-type-routes.ts
+import { Hono as Hono8 } from "hono";
+import { v4 as uuid6 } from "uuid";
+var requireWorkflowPlane = async (c, next) => {
+  if (!config.FEATURE_WORKFLOW_PLANE) {
+    return c.json(
+      {
+        error: "The workflow plane is not enabled on this server. An admin can turn it on with FEATURE_WORKFLOW_PLANE=true."
+      },
+      404
+    );
+  }
+  return next();
+};
+async function seedDefaultEdgeTypes(nestId) {
+  const db = getDb();
+  const existing = await db.get(
+    "SELECT COUNT(*) as c FROM edge_types WHERE nest_id = ?",
+    [nestId]
+  );
+  if (existing.c > 0) return;
+  const owner = await db.get(
+    "SELECT u.email FROM nests n JOIN users u ON u.id = n.user_id WHERE n.id = ?",
+    [nestId]
+  );
+  const createdBy = owner?.email ?? "admin@localhost";
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const defaults = [
+    ["next", "Unconditional flow: after the source completes, run the target.", 1, "#16a34a"],
+    ["on-success", "Follow only when the source step succeeded.", 1, "#16a34a"],
+    ["on-failure", "Follow only when the source step failed.", 1, "#ef4444"],
+    ["depends-on", "The source requires the target (ordering/lineage; not conditional flow).", 0, "#3b82f6"],
+    ["owned-by", "Ownership: the target person/team is accountable for the source node.", 0, "#64748b"]
+  ];
+  for (const [name, description, isFlow, color] of defaults) {
+    await db.run(
+      `INSERT INTO edge_types
+         (id, nest_id, name, description, direction, is_flow, condition_schema, color, created_by, created_at, updated_at)
+       VALUES (?, ?, ?, ?, 'directed', ?, NULL, ?, ?, ?, ?)
+       ON CONFLICT DO NOTHING`,
+      [uuid6(), nestId, name, description, isFlow, color, createdBy, now, now]
+    );
+  }
+}
+function parseConditionSchema(raw) {
+  if (raw === void 0 || raw === null || raw === "") return null;
+  const obj = typeof raw === "string" ? safeJson(raw) : raw;
+  if (!obj || typeof obj !== "object" || !Array.isArray(obj.params) || !obj.params.every((p) => typeof p === "string")) {
+    throw new ValidationError(
+      'condition_schema must be {"params": [string\u2026], "mode_default"?: "structured"|"nl"|"open"}'
+    );
+  }
+  const mode = obj.mode_default;
+  if (mode !== void 0 && !["structured", "nl", "open"].includes(mode)) {
+    throw new ValidationError(
+      "condition_schema.mode_default must be structured | nl | open"
+    );
+  }
+  return JSON.stringify({ params: obj.params, mode_default: mode ?? "structured" });
+}
+var edgeTypeToResponse = (r) => ({
+  ...r,
+  is_flow: !!r.is_flow,
+  condition_schema: r.condition_schema ? safeJson(r.condition_schema) : null
+});
+var edgeTypeRoutes = new Hono8();
+edgeTypeRoutes.get("/", requireWorkflowPlane, async (c) => {
+  const nestId = c.req.param("nestId");
+  await seedDefaultEdgeTypes(nestId);
+  const rows = await getDb().all(
+    "SELECT * FROM edge_types WHERE nest_id = ? ORDER BY LOWER(name)",
+    [nestId]
+  );
+  return c.json({ count: rows.length, edge_types: rows.map(edgeTypeToResponse) });
+});
+edgeTypeRoutes.post("/", requireWorkflowPlane, async (c) => {
+  const nestId = c.req.param("nestId");
+  const body = await c.req.json();
+  if (typeof body.name !== "string" || !body.name.trim()) {
+    throw new ValidationError("name is required");
+  }
+  if (typeof body.description !== "string" || !body.description.trim()) {
+    throw new ValidationError("description (the articulation) is required");
+  }
+  const name = body.name.trim();
+  if (name.length > 100 || !/^[a-z0-9][a-z0-9-]*$/i.test(name)) {
+    throw new ValidationError(
+      "name must be alphanumeric-with-dashes, 100 chars max (e.g. escalates-when)"
+    );
+  }
+  const direction = String(body.direction ?? "directed");
+  if (!["directed", "undirected"].includes(direction)) {
+    throw new ValidationError("direction must be directed | undirected");
+  }
+  const conditionSchema = parseConditionSchema(body.condition_schema);
+  const isFlow = body.is_flow === true ? 1 : 0;
+  let color = null;
+  if (body.color !== void 0 && body.color !== null && body.color !== "") {
+    if (typeof body.color !== "string" || !/^#[0-9a-f]{6}$/i.test(body.color)) {
+      throw new ValidationError("color must be a 6-digit hex, e.g. #16a34a");
+    }
+    color = body.color;
+  }
+  const db = getDb();
+  const definedBy = await resolveCallerEmail(c.get("userId"));
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  await seedDefaultEdgeTypes(nestId);
+  let created = false;
+  await db.transaction(async (tx) => {
+    const existing = await tx.get(
+      "SELECT id FROM edge_types WHERE nest_id = ? AND LOWER(name) = LOWER(?)",
+      [nestId, name]
+    );
+    if (existing) {
+      await tx.run(
+        `UPDATE edge_types SET name = ?, description = ?, direction = ?, is_flow = ?,
+           condition_schema = ?, color = ?, updated_at = ? WHERE id = ?`,
+        [name, body.description.trim(), direction, isFlow, conditionSchema, color, now, existing.id]
+      );
+    } else {
+      created = true;
+      await tx.run(
+        `INSERT INTO edge_types
+           (id, nest_id, name, description, direction, is_flow, condition_schema, color, created_by, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [uuid6(), nestId, name, body.description.trim(), direction, isFlow, conditionSchema, color, definedBy, now, now]
+      );
+    }
+  });
+  const row = await db.get(
+    "SELECT * FROM edge_types WHERE nest_id = ? AND LOWER(name) = LOWER(?)",
+    [nestId, name]
+  );
+  return c.json({ edge_type: edgeTypeToResponse(row) }, created ? 201 : 200);
+});
+edgeTypeRoutes.delete("/:id", requireWorkflowPlane, async (c) => {
+  const nestId = c.req.param("nestId");
+  const id = c.req.param("id");
+  await getDb().transaction(async (tx) => {
+    const row = await tx.get(
+      "SELECT id FROM edge_types WHERE id = ? AND nest_id = ?",
+      [id, nestId]
+    );
+    if (!row) throw new NotFoundError("Edge type not found");
+    const inUse = await tx.get(
+      "SELECT COUNT(*) as c FROM edges WHERE type_id = ?",
+      [id]
+    );
+    if (inUse.c > 0) {
+      throw new ValidationError(
+        `Edge type is in use by ${inUse.c} edge${inUse.c === 1 ? "" : "s"} \u2014 delete those first.`
+      );
+    }
+    await tx.run("DELETE FROM edge_types WHERE id = ?", [id]);
+  });
+  return c.json({ deleted: true });
+});
+
+// src/workflow/edge-routes.ts
+function toResponse(e, t) {
+  return {
+    id: e.id,
+    from_node: e.from_node,
+    to_node: e.to_node,
+    type: { id: t.id, name: t.name, color: t.color, is_flow: !!t.is_flow },
+    condition_mode: e.condition_mode,
+    condition: e.condition_mode === "structured" ? safeJson(e.condition) : e.condition,
+    metadata: safeJson(e.metadata),
+    created_by: e.created_by,
+    created_at: e.created_at,
+    updated_at: e.updated_at
+  };
+}
+async function validateCondition(nestId, mode, condition) {
+  if (mode === void 0 || mode === null) {
+    if (condition !== void 0 && condition !== null) {
+      throw new ValidationError("condition requires condition_mode");
+    }
+    return { mode: null, stored: null };
+  }
+  if (!["structured", "nl", "open"].includes(mode)) {
+    throw new ValidationError("condition_mode must be structured | nl | open");
+  }
+  if (condition === void 0 || condition === null || condition === "") {
+    throw new ValidationError(`condition_mode "${mode}" requires a condition`);
+  }
+  if (mode === "structured") {
+    if (typeof condition !== "object" || Array.isArray(condition)) {
+      throw new ValidationError(
+        'structured condition must be an object, e.g. {"term":"CAC","op":">","value":500}'
+      );
+    }
+    const c = condition;
+    if (typeof c.term === "string" && c.term.trim()) {
+      try {
+        const row = await getDb().get(
+          "SELECT id FROM definitions WHERE nest_id = ? AND LOWER(term) = LOWER(?)",
+          [nestId, c.term.trim()]
+        );
+        if (!row) {
+          throw new ValidationError(
+            `structured condition references undefined term "${c.term}" \u2014 define it in the glossary first`
+          );
+        }
+      } catch (err) {
+        if (err instanceof ValidationError) throw err;
+        if (!/no such table/i.test(err?.message ?? "")) throw err;
+      }
+    }
+    return { mode, stored: JSON.stringify(condition) };
+  }
+  if (typeof condition !== "string") {
+    throw new ValidationError(`condition for mode "${mode}" must be a string`);
+  }
+  return { mode, stored: condition };
+}
+async function assertNoFlowCycle(db, nestId, fromNode, toNode) {
+  if (fromNode === toNode) {
+    throw new ConflictError(
+      `cycle: ["${fromNode}","${toNode}"] \u2014 flow edges must form a DAG`
+    );
+  }
+  const rows = await db.all(
+    `SELECT e.from_node, e.to_node FROM edges e
+       JOIN edge_types t ON t.id = e.type_id
+      WHERE e.nest_id = ? AND t.is_flow = 1`,
+    [nestId]
+  );
+  const adj = /* @__PURE__ */ new Map();
+  for (const r of rows) {
+    (adj.get(r.from_node) ?? adj.set(r.from_node, []).get(r.from_node)).push(
+      r.to_node
+    );
+  }
+  const parent = /* @__PURE__ */ new Map();
+  const queue = [toNode];
+  const seen = /* @__PURE__ */ new Set([toNode]);
+  while (queue.length) {
+    const cur = queue.shift();
+    if (cur === fromNode) {
+      const path = [fromNode];
+      let p = fromNode;
+      while (p !== toNode) {
+        p = parent.get(p);
+        path.push(p);
+      }
+      path.reverse().push(toNode);
+      throw new ConflictError(
+        `cycle: ${JSON.stringify(path)} \u2014 flow edges must form a DAG`
+      );
+    }
+    for (const nb of adj.get(cur) ?? []) {
+      if (!seen.has(nb)) {
+        seen.add(nb);
+        parent.set(nb, cur);
+        queue.push(nb);
+      }
+    }
+  }
+}
+var edgeRoutes = new Hono9();
+edgeRoutes.get("/", requireWorkflowPlane, async (c) => {
+  const nestId = c.req.param("nestId");
+  const db = getDb();
+  const typeFilter = c.req.query("type")?.trim();
+  const nodeFilter = c.req.query("node")?.trim();
+  let sql = `SELECT e.*, t.id as t_id, t.name as t_name, t.color as t_color, t.is_flow as t_is_flow
+               FROM edges e JOIN edge_types t ON t.id = e.type_id
+              WHERE e.nest_id = ?`;
+  const args = [nestId];
+  if (typeFilter) {
+    sql += " AND (t.id = ? OR LOWER(t.name) = LOWER(?))";
+    args.push(typeFilter, typeFilter);
+  }
+  if (nodeFilter) {
+    sql += " AND (e.from_node = ? OR e.to_node = ?)";
+    args.push(nodeFilter, nodeFilter);
+  }
+  sql += " ORDER BY e.created_at";
+  const rows = await db.all(sql, args);
+  const edges = rows.map(
+    (r) => toResponse(r, {
+      id: r.t_id,
+      name: r.t_name,
+      color: r.t_color,
+      is_flow: r.t_is_flow
+    })
+  );
+  return c.json({ count: edges.length, edges });
+});
+edgeRoutes.post("/", requireWorkflowPlane, async (c) => {
+  const nestId = c.req.param("nestId");
+  const body = await c.req.json();
+  const fromRaw = typeof body.from_node === "string" ? body.from_node.trim() : "";
+  const toRaw = typeof body.to_node === "string" ? body.to_node.trim() : "";
+  const typeRef = typeof body.type === "string" ? body.type.trim() : "";
+  if (!fromRaw || !toRaw || !typeRef) {
+    throw new ValidationError("from_node, to_node, and type are required");
+  }
+  const fromNode = assertSafeNodeId(fromRaw);
+  const toNode = assertSafeNodeId(toRaw);
+  const db = getDb();
+  const createdBy = await resolveCallerEmail(c.get("userId"));
+  await seedDefaultEdgeTypes(nestId);
+  const type = await db.get(
+    "SELECT * FROM edge_types WHERE nest_id = ? AND (id = ? OR LOWER(name) = LOWER(?))",
+    [nestId, typeRef, typeRef]
+  );
+  if (!type) {
+    throw new ValidationError(
+      `unknown edge type "${typeRef}" \u2014 define it in the registry first`
+    );
+  }
+  const { storage } = await engineCache.get(nestId);
+  for (const nodeId of [fromNode, toNode]) {
+    try {
+      await storage.readDocument(nodeId);
+    } catch {
+      throw new ValidationError(`node not found: "${nodeId}"`);
+    }
+  }
+  const { mode, stored } = await validateCondition(
+    nestId,
+    body.condition_mode,
+    body.condition
+  );
+  const metadata = body.metadata === void 0 || body.metadata === null ? null : JSON.stringify(body.metadata);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const id = uuid7();
+  await db.transaction(async (tx) => {
+    if (type.is_flow) {
+      await assertNoFlowCycle(tx, nestId, fromNode, toNode);
+    }
+    await tx.run(
+      `INSERT INTO edges
+         (id, nest_id, from_node, to_node, type_id, condition_mode, condition, metadata, created_by, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [id, nestId, fromNode, toNode, type.id, mode, stored, metadata, createdBy, now, now]
+    );
+  });
+  const row = await db.get("SELECT * FROM edges WHERE id = ?", [id]);
+  return c.json({ edge: toResponse(row, type) }, 201);
+});
+edgeRoutes.delete("/:id", requireWorkflowPlane, async (c) => {
+  const nestId = c.req.param("nestId");
+  const id = c.req.param("id");
+  const db = getDb();
+  const row = await db.get(
+    "SELECT id FROM edges WHERE id = ? AND nest_id = ?",
+    [id, nestId]
+  );
+  if (!row) throw new NotFoundError("Edge not found");
+  await db.run("DELETE FROM edges WHERE id = ?", [id]);
+  return c.json({ deleted: true });
+});
+
+// src/mcp/workflow-tools.ts
+var WORKFLOW_TOOL_DEFINITIONS = [
+  // ── Execute ──────────────────────────────────────────────────────────
+  {
+    name: "workflow_run",
+    description: "Trigger a governed workflow run for an agent/skill node and get the executable bundle back (agent instructions, the reachable flow-edge subgraph, and referenced glossary definitions) plus a run_id. The server does not execute \u2014 YOU are the runner: walk the edges, then report progress with workflow_run_step and finish with workflow_run_close.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent: { type: "string", description: "Node id of the agent/skill to run" },
+        inputs: { type: "object", description: "Optional caller inputs recorded on the run" },
+        parent_run_id: {
+          type: "string",
+          description: "Optional: spawn this as a sub-agent run under a still-running parent (FEATURE_SUBAGENT_RUNS). Bounded by depth/fan-out and guarded against re-entrancy."
+        }
+      },
+      required: ["agent"]
+    }
+  },
+  {
+    name: "workflow_run_step",
+    description: "Append one step to a run's trace after every action. seq is assigned server-side. For branch steps put the evaluated condition, result and (NL mode) rationale in detail. Fails if the run is already closed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        run_id: { type: "string" },
+        action: { type: "string", description: "read | write | branch | notify | external" },
+        node_id: { type: "string", description: "Node the step touched (optional)" },
+        edge_id: { type: "string", description: "Edge the step followed (optional)" },
+        detail: { type: "object", description: "Freeform payload: reads, condition results, rationale" }
+      },
+      required: ["run_id", "action"]
+    }
+  },
+  {
+    name: "workflow_run_close",
+    description: "Close a run with a terminal status (succeeded | failed | cancelled) and an optional trace summary. Terminal is final \u2014 a second close returns a conflict.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        run_id: { type: "string" },
+        status: { type: "string", description: "succeeded | failed | cancelled (or running to update trace)" },
+        trace: { type: "object", description: "Optional summary/totals recorded on the run" }
+      },
+      required: ["run_id", "status"]
+    }
+  },
+  {
+    name: "workflow_run_get",
+    description: "Fetch one run's full trace (steps in order). Freeform payloads (inputs, trace, step detail) are redacted unless you have write access to the nest.",
+    inputSchema: {
+      type: "object",
+      properties: { run_id: { type: "string" } },
+      required: ["run_id"]
+    }
+  },
+  {
+    name: "workflow_runs_list",
+    description: "List runs in this nest, most recent first. Filter by agent node id and/or status (running|succeeded|failed|cancelled).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent: { type: "string" },
+        status: { type: "string" },
+        limit: { type: "number" }
+      },
+      required: []
+    }
+  },
+  // ── Build: edges ─────────────────────────────────────────────────────
+  {
+    name: "workflow_edges_list",
+    description: "List typed edges in this nest. Optional filters: type (edge-type name or id) and node (id appearing as either endpoint).",
+    inputSchema: {
+      type: "object",
+      properties: { type: { type: "string" }, node: { type: "string" } },
+      required: []
+    }
+  },
+  {
+    name: "workflow_edge_create",
+    description: "Create a typed edge between two existing nodes. The edge type must already exist in the registry. Optional condition in mode structured (JSON predicate {term,op,value}; term must be a defined glossary term), nl (natural-language, judged at run time), or open. Flow-type edges must keep the graph a DAG \u2014 a cycle is rejected.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from_node: { type: "string" },
+        to_node: { type: "string" },
+        type: { type: "string", description: "Edge-type name or id" },
+        condition_mode: { type: "string", description: "structured | nl | open" },
+        condition: { type: "object", description: "Predicate object (structured) or string (nl/open)" },
+        metadata: { type: "object" }
+      },
+      required: ["from_node", "to_node", "type"]
+    }
+  },
+  {
+    name: "workflow_edge_delete",
+    description: "Delete an edge by id.",
+    inputSchema: {
+      type: "object",
+      properties: { edge_id: { type: "string" } },
+      required: ["edge_id"]
+    }
+  },
+  // ── Build: edge types ────────────────────────────────────────────────
+  {
+    name: "workflow_edge_types_list",
+    description: "List this nest's edge-type registry \u2014 the articulated vocabulary of relations. Seeds the five stock flow types on first use.",
+    inputSchema: { type: "object", properties: {}, required: [] }
+  },
+  {
+    name: "workflow_edge_type_upsert",
+    description: "Create or update an edge type by name (case-insensitive). name is a slug (alphanumeric-with-dashes). Set is_flow true for control-flow relations (they get DAG-validated). condition_schema is an optional {params:[string\u2026], mode_default?} template.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        description: { type: "string" },
+        direction: { type: "string", description: "directed | undirected (default directed)" },
+        is_flow: { type: "boolean" },
+        condition_schema: { type: "object" },
+        color: { type: "string", description: "6-digit hex, e.g. #16a34a" }
+      },
+      required: ["name", "description"]
+    }
+  },
+  {
+    name: "workflow_edge_type_delete",
+    description: "Delete an edge type by id. Refused while any edge still references it.",
+    inputSchema: {
+      type: "object",
+      properties: { edge_type_id: { type: "string" } },
+      required: ["edge_type_id"]
+    }
+  }
+];
+var WORKFLOW_TOOL_NAMES = new Set(WORKFLOW_TOOL_DEFINITIONS.map((t) => t.name));
+var isWorkflowTool = (name) => WORKFLOW_TOOL_NAMES.has(name);
+async function nestPermission(ctx) {
+  if (config.AUTH_MODE === "open") return "owner";
+  return resolveNestPermission(ctx.nestId, ctx.userId);
+}
+function requireTier(perm, tier) {
+  if (permissionLevel(perm) < permissionLevel(tier)) {
+    throw new ForbiddenError(
+      `This action needs ${tier} access to the nest.`
+    );
+  }
+}
+async function loadNestRun(ctx, runId) {
+  if (typeof runId !== "string" || !runId) {
+    throw new ValidationError("run_id is required");
+  }
+  const run = await loadRun(runId);
+  if (!run || run.nest_id !== ctx.nestId) throw new NotFoundError("Run not found");
+  return run;
+}
+var json = (v) => JSON.stringify(v, null, 2);
+async function runWorkflowTool(toolName, args, ctx) {
+  const perm = await nestPermission(ctx);
+  switch (toolName) {
+    // ── Execute ────────────────────────────────────────────────────────
+    case "workflow_run": {
+      requireTier(perm, "write");
+      const triggeredBy = await resolveCallerEmail(ctx.userId);
+      const bundle = await triggerRun({
+        nestId: ctx.nestId,
+        agentNode: String(args.agent ?? ""),
+        inputs: args.inputs,
+        triggeredBy,
+        storage: ctx.storage,
+        parentRunId: args.parent_run_id
+      });
+      return json(bundle);
+    }
+    case "workflow_run_step": {
+      requireTier(perm, "write");
+      const run = await loadNestRun(ctx, args.run_id);
+      const { seq } = await appendRunStep(run.id, {
+        action: args.action,
+        node_id: args.node_id,
+        edge_id: args.edge_id,
+        detail: args.detail
+      });
+      return json({ ok: true, run_id: run.id, seq });
+    }
+    case "workflow_run_close": {
+      requireTier(perm, "write");
+      const run = await loadNestRun(ctx, args.run_id);
+      const { status } = await closeRun(run.id, {
+        status: args.status,
+        trace: args.trace
+      });
+      return json({ ok: true, run_id: run.id, status });
+    }
+    case "workflow_run_get": {
+      requireTier(perm, "read");
+      const run = await loadNestRun(ctx, args.run_id);
+      const canSeeDetail = permissionLevel(perm) >= permissionLevel("write");
+      return json(await getRunTrace(run, { canSeeDetail }));
+    }
+    case "workflow_runs_list": {
+      requireTier(perm, "read");
+      const canSeeDetail = permissionLevel(perm) >= permissionLevel("write");
+      return json(
+        await listRuns(ctx.nestId, {
+          agent: typeof args.agent === "string" ? args.agent : void 0,
+          status: typeof args.status === "string" ? args.status : void 0,
+          limit: typeof args.limit === "number" ? args.limit : void 0,
+          canSeeDetail
+        })
+      );
+    }
+    // ── Build: edges ───────────────────────────────────────────────────
+    case "workflow_edges_list": {
+      requireTier(perm, "read");
+      return json(await listEdges(ctx.nestId, args.type, args.node));
+    }
+    case "workflow_edge_create": {
+      requireTier(perm, "write");
+      return json(await createEdge(ctx, args));
+    }
+    case "workflow_edge_delete": {
+      requireTier(perm, "write");
+      const id = String(args.edge_id ?? "");
+      const row = await getDb().get(
+        "SELECT id FROM edges WHERE id = ? AND nest_id = ?",
+        [id, ctx.nestId]
+      );
+      if (!row) throw new NotFoundError("Edge not found");
+      await getDb().run("DELETE FROM edges WHERE id = ?", [id]);
+      return json({ deleted: true, edge_id: id });
+    }
+    // ── Build: edge types ──────────────────────────────────────────────
+    case "workflow_edge_types_list": {
+      requireTier(perm, "read");
+      await seedDefaultEdgeTypes(ctx.nestId);
+      const rows = await getDb().all(
+        "SELECT * FROM edge_types WHERE nest_id = ? ORDER BY LOWER(name)",
+        [ctx.nestId]
+      );
+      return json({ count: rows.length, edge_types: rows.map(edgeTypeToResponse) });
+    }
+    case "workflow_edge_type_upsert": {
+      requireTier(perm, "write");
+      return json(await upsertEdgeType(ctx, args));
+    }
+    case "workflow_edge_type_delete": {
+      requireTier(perm, "write");
+      return json(await deleteEdgeType(ctx.nestId, String(args.edge_type_id ?? "")));
+    }
+    default:
+      return json({ error: `Unknown workflow tool: ${toolName}` });
+  }
+}
+async function listEdges(nestId, type, node) {
+  const db = getDb();
+  let sql = `SELECT e.*, t.id as t_id, t.name as t_name, t.color as t_color, t.is_flow as t_is_flow
+               FROM edges e JOIN edge_types t ON t.id = e.type_id
+              WHERE e.nest_id = ?`;
+  const args = [nestId];
+  if (typeof type === "string" && type.trim()) {
+    sql += " AND (t.id = ? OR LOWER(t.name) = LOWER(?))";
+    args.push(type.trim(), type.trim());
+  }
+  if (typeof node === "string" && node.trim()) {
+    sql += " AND (e.from_node = ? OR e.to_node = ?)";
+    args.push(node.trim(), node.trim());
+  }
+  sql += " ORDER BY e.created_at";
+  const rows = await db.all(sql, args);
+  const edges = rows.map(
+    (r) => toResponse(r, {
+      id: r.t_id,
+      name: r.t_name,
+      color: r.t_color,
+      is_flow: r.t_is_flow
+    })
+  );
+  return { count: edges.length, edges };
+}
+async function createEdge(ctx, args) {
+  const fromNode = typeof args.from_node === "string" ? args.from_node.trim() : "";
+  const toNode = typeof args.to_node === "string" ? args.to_node.trim() : "";
+  const typeRef = typeof args.type === "string" ? args.type.trim() : "";
+  if (!fromNode || !toNode || !typeRef) {
+    throw new ValidationError("from_node, to_node, and type are required");
+  }
+  assertSafeNodeId(fromNode);
+  assertSafeNodeId(toNode);
+  const db = getDb();
+  const createdBy = await resolveCallerEmail(ctx.userId);
+  await seedDefaultEdgeTypes(ctx.nestId);
+  const type = await db.get(
+    "SELECT * FROM edge_types WHERE nest_id = ? AND (id = ? OR LOWER(name) = LOWER(?))",
+    [ctx.nestId, typeRef, typeRef]
+  );
+  if (!type) {
+    throw new ValidationError(
+      `unknown edge type "${typeRef}" \u2014 create it first with workflow_edge_type_upsert`
+    );
+  }
+  for (const nodeId of [fromNode, toNode]) {
+    try {
+      await ctx.storage.readDocument(nodeId);
+    } catch {
+      throw new ValidationError(`node not found: "${nodeId}"`);
+    }
+  }
+  const { mode, stored } = await validateCondition(
+    ctx.nestId,
+    args.condition_mode,
+    args.condition
+  );
+  const metadata = args.metadata === void 0 || args.metadata === null ? null : JSON.stringify(args.metadata);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const id = uuid8();
+  await db.transaction(async (tx) => {
+    if (type.is_flow) {
+      await assertNoFlowCycle(tx, ctx.nestId, fromNode, toNode);
+    }
+    await tx.run(
+      `INSERT INTO edges
+         (id, nest_id, from_node, to_node, type_id, condition_mode, condition, metadata, created_by, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [id, ctx.nestId, fromNode, toNode, type.id, mode, stored, metadata, createdBy, now, now]
+    );
+  });
+  const row = await db.get("SELECT * FROM edges WHERE id = ?", [id]);
+  return { edge: toResponse(row, type) };
+}
+async function upsertEdgeType(ctx, args) {
+  if (typeof args.name !== "string" || !args.name.trim()) {
+    throw new ValidationError("name is required");
+  }
+  if (typeof args.description !== "string" || !args.description.trim()) {
+    throw new ValidationError("description (the articulation) is required");
+  }
+  const name = args.name.trim();
+  if (name.length > 100 || !/^[a-z0-9][a-z0-9-]*$/i.test(name)) {
+    throw new ValidationError(
+      "name must be alphanumeric-with-dashes, 100 chars max (e.g. escalates-when)"
+    );
+  }
+  const direction = String(args.direction ?? "directed");
+  if (!["directed", "undirected"].includes(direction)) {
+    throw new ValidationError("direction must be directed | undirected");
+  }
+  const conditionSchema = parseConditionSchema(args.condition_schema);
+  const isFlow = args.is_flow === true ? 1 : 0;
+  let color = null;
+  if (args.color !== void 0 && args.color !== null && args.color !== "") {
+    if (typeof args.color !== "string" || !/^#[0-9a-f]{6}$/i.test(args.color)) {
+      throw new ValidationError("color must be a 6-digit hex, e.g. #16a34a");
+    }
+    color = args.color;
+  }
+  const db = getDb();
+  const definedBy = await resolveCallerEmail(ctx.userId);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  await seedDefaultEdgeTypes(ctx.nestId);
+  let created = false;
+  await db.transaction(async (tx) => {
+    const existing = await tx.get(
+      "SELECT id FROM edge_types WHERE nest_id = ? AND LOWER(name) = LOWER(?)",
+      [ctx.nestId, name]
+    );
+    if (existing) {
+      await tx.run(
+        `UPDATE edge_types SET name = ?, description = ?, direction = ?, is_flow = ?,
+           condition_schema = ?, color = ?, updated_at = ? WHERE id = ?`,
+        [name, args.description.trim(), direction, isFlow, conditionSchema, color, now, existing.id]
+      );
+    } else {
+      created = true;
+      await tx.run(
+        `INSERT INTO edge_types
+           (id, nest_id, name, description, direction, is_flow, condition_schema, color, created_by, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [uuid8(), ctx.nestId, name, args.description.trim(), direction, isFlow, conditionSchema, color, definedBy, now, now]
+      );
+    }
+  });
+  const row = await db.get(
+    "SELECT * FROM edge_types WHERE nest_id = ? AND LOWER(name) = LOWER(?)",
+    [ctx.nestId, name]
+  );
+  return { created, edge_type: edgeTypeToResponse(row) };
+}
+async function deleteEdgeType(nestId, id) {
+  await getDb().transaction(async (tx) => {
+    const row = await tx.get(
+      "SELECT id FROM edge_types WHERE id = ? AND nest_id = ?",
+      [id, nestId]
+    );
+    if (!row) throw new NotFoundError("Edge type not found");
+    const inUse = await tx.get(
+      "SELECT COUNT(*) as c FROM edges WHERE type_id = ?",
+      [id]
+    );
+    if (inUse.c > 0) {
+      throw new ValidationError(
+        `Edge type is in use by ${inUse.c} edge${inUse.c === 1 ? "" : "s"} \u2014 delete those first.`
+      );
+    }
+    await tx.run("DELETE FROM edge_types WHERE id = ?", [id]);
+  });
+  return { deleted: true, edge_type_id: id };
+}
+
+// src/mcp/tools.ts
+var MAX_HOPS = 10;
+function normalizeHops(raw) {
+  if (raw == null) return 2;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return 2;
+  return Math.max(0, Math.min(MAX_HOPS, Math.floor(n)));
+}
+var TOOL_DEFINITIONS = [
+  {
+    name: "context_init",
+    description: "Load the vault's CONTEXT.md which contains operating instructions and behavioral guidelines. Call this FIRST in every conversation.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "context_overview",
+    description: "Get a complete map of the vault: total node count, types, tags, and a title+snippet for every node.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "context_search",
+    description: "Full-text keyword search across all node content, titles, tags, and metadata.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search terms" }
+      },
+      required: ["query"]
+    }
+  },
+  {
+    name: "context_query",
+    description: "Run a structured selector query. Supports: #tag, type:X, [[Title]], scope:X. Combine with +AND, |OR, -NOT.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Selector query" },
+        hops: {
+          type: "number",
+          description: "Graph traversal depth from the matched nodes (default: 2). Use 1 for just the matches + direct links, higher to pull in more of the neighborhood."
+        }
+      },
+      required: ["query"]
+    }
+  },
+  {
+    name: "context_get",
+    description: "Get the FULL content of a specific node by title or ID.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Title of the node" },
+        id: { type: "string", description: "ID of the node" }
+      }
+    }
+  },
+  {
+    name: "context_list",
+    description: "Browse vault contents with optional type, tag, or limit filters.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { type: "string", description: "Filter by node type" },
+        tag: { type: "string", description: "Filter by tag" },
+        limit: { type: "number", description: "Max nodes to return" }
+      }
+    }
+  },
+  {
+    name: "context_resolve",
+    description: "Full context resolution \u2014 run a selector and return complete node content, respecting a token budget.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selector: {
+          type: "string",
+          description: "Selector query string"
+        },
+        max_tokens: {
           type: "number",
           description: "Approximate token budget (default: 8000)"
         },
@@ -4051,6 +5524,26 @@ var TOOL_DEFINITIONS = [
       required: ["email"]
     }
   },
+  {
+    name: "context_grant",
+    description: "Share a SINGLE document or a FOLDER with a person (not the whole nest). The recipient can reach exactly that document (or everything under that folder) and nothing else. read = view, write = view+edit. Owner/admin only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        email: { type: "string", description: "Email of the person to share with" },
+        target_type: {
+          type: "string",
+          description: "'document' to share one node, or 'folder' to share a path prefix"
+        },
+        target: {
+          type: "string",
+          description: "Node id (e.g. nodes/win-loss-log) for a document, or a folder prefix (e.g. nodes/gtm/deals) for a folder"
+        },
+        role: { type: "string", description: "read (default) or write" }
+      },
+      required: ["email", "target_type", "target"]
+    }
+  },
   // ─── Unsynced Folder Tools ─────────────────────────────────────────
   {
     name: "context_unsynced_list",
@@ -4084,6 +5577,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": {
@@ -4415,7 +5928,8 @@ ${list}`;
           version: currentVersion,
           requestedBy: ctx.userEmail,
           note: args.note,
-          priority: args.priority
+          priority: args.priority,
+          baseUrl: ctx.baseUrl
         });
         const resolved = await resolveStewardsForNode(
           ctx.nestId,
@@ -4443,7 +5957,8 @@ ${resolved.map((r) => `- ${r.steward.userEmail} (${r.source})`).join("\n")}` : "
           nodeId: node.id,
           version: currentVersion,
           approvedBy: ctx.userEmail,
-          note: args.note
+          note: args.note,
+          baseUrl: ctx.baseUrl
         });
         return `Approved "${args.title}" v${currentVersion}. This version is now live for AI queries.${args.note ? `
 Note: ${args.note}` : ""}`;
@@ -4464,7 +5979,8 @@ Note: ${args.note}` : ""}`;
           nodeId: node.id,
           version: currentVersion,
           rejectedBy: ctx.userEmail,
-          note: args.note
+          note: args.note,
+          baseUrl: ctx.baseUrl
         });
         return `Rejected "${args.title}" v${currentVersion}.
 Reason: ${args.note}`;
@@ -4534,104 +6050,796 @@ ${list}`;
         return `Failed to share nest: ${err.message}`;
       }
     }
-    case "context_unsynced_list": {
-      if (config.AUTH_MODE !== "open" && !await isLicenseAdminUserId(userId)) {
-        return "You don't have permission to list unsynced folders. Server admin only.";
+    case "context_grant": {
+      if (!await canManageStewards(ctx.nestId, ctx.userId)) {
+        return "You don't have permission to share documents in this nest (owner/admin only).";
+      }
+      const targetType = String(args.target_type || "");
+      const target = String(args.target || "").trim();
+      const role = String(args.role || "read");
+      if (!["document", "folder"].includes(targetType)) {
+        return "target_type must be 'document' or 'folder'.";
+      }
+      if (!target) return "target is required (a node id or folder prefix).";
+      if (!["read", "write"].includes(role)) return "role must be read or write.";
+      try {
+        const { createGrant: createGrant2 } = await import("./grants-service-MDLRPMZR.js");
+        const db = (await import("./client-GI74NPIW.js")).getDb();
+        const { normalizeEmail: normalizeEmail2 } = await import("./email-R7DFS6E5.js");
+        const e = normalizeEmail2(String(args.email || ""));
+        if (!e) return "email is required.";
+        let row = await db.get("SELECT id FROM users WHERE LOWER(email) = ?", [e]);
+        if (!row) {
+          const { hashPassword: hashPassword2 } = await import("./keys-73STFJJB.js");
+          const { v4: uuid12 } = await import("uuid");
+          const id = uuid12();
+          await db.run(
+            "INSERT INTO users (id, email, name, password_hash, is_invited) VALUES (?, ?, ?, ?, 1)",
+            [id, e, null, await hashPassword2(uuid12())]
+          );
+          row = { id };
+        }
+        await createGrant2({
+          nestId: ctx.nestId,
+          targetType,
+          target,
+          userId: row.id,
+          role,
+          grantedBy: ctx.userEmail
+        });
+        return `Shared ${targetType} \`${target}\` with **${args.email}** as ${role}.`;
+      } catch (err) {
+        return `Failed to share: ${err.message}`;
+      }
+    }
+    case "context_unsynced_list": {
+      if (config.AUTH_MODE !== "open" && !await isLicenseAdminUserId(userId)) {
+        return "You don't have permission to list unsynced folders. Server admin only.";
+      }
+      const folders = listUnsyncedFolders();
+      if (!folders.length) return "No unsynced folders found.";
+      const list = folders.map(
+        (f, i) => `${i + 1}. **${f.label}** \`${f.name}\` \u2014 ${f.mdCount} md file(s), ${f.sizeBytes} bytes`
+      ).join("\n");
+      return `# Unsynced Folders (${folders.length})
+
+${list}`;
+    }
+    case "context_sync_folder": {
+      if (config.AUTH_MODE !== "open" && !await isLicenseAdminUserId(userId)) {
+        return "You don't have permission to sync folders. Server admin only.";
+      }
+      try {
+        const { nest, documents } = await syncUnsyncedFolder(
+          userId,
+          args.name,
+          userEmail
+        );
+        return `Synced folder "${args.name}" \u2192 nest **${nest.name}** (${nest.id}) with ${documents} document(s).`;
+      } catch (err) {
+        return `Failed to sync folder: ${err.message}`;
+      }
+    }
+    default:
+      if (isWorkflowTool(toolName)) {
+        return runWorkflowTool(toolName, args, ctx);
+      }
+      return `Unknown tool: ${toolName}`;
+  }
+}
+
+// src/mcp/routes.ts
+import { z } from "zod";
+var mcpRoutes = new Hono10();
+async function getUserEmail2(userId) {
+  const db = getDb();
+  const user = await db.get("SELECT email FROM users WHERE id = ?", [userId]);
+  return user?.email || "anonymous@localhost";
+}
+function createMcpServerForNest(nestId, userId, userEmail, baseUrl) {
+  const server = new McpServer(
+    { name: `contextnest-${nestId}`, version: "1.0.0" },
+    { capabilities: { tools: {} } }
+  );
+  const toolDefs = config.FEATURE_WORKFLOW_PLANE ? [...TOOL_DEFINITIONS, ...WORKFLOW_TOOL_DEFINITIONS] : TOOL_DEFINITIONS;
+  for (const tool of toolDefs) {
+    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 = z.string();
+      else if (def.type === "number") field = z.number();
+      else if (def.type === "array") field = z.array(z.string());
+      else field = z.any();
+      if (!required.includes(key)) field = field.optional();
+      shape[key] = field;
+    }
+    server.tool(tool.name, tool.description, shape, async (args) => {
+      const engine = await engineCache.get(nestId);
+      const text = await handleToolCall(tool.name, args, {
+        storage: engine.storage,
+        queryEngine: engine.query,
+        versionManager: engine.versions,
+        nestId,
+        userId,
+        userEmail,
+        baseUrl
+      });
+      return { content: [{ type: "text", text }] };
+    });
+  }
+  return server;
+}
+mcpRoutes.all("/", async (c) => {
+  const nestId = c.req.param("nestId");
+  const userId = c.get("userId");
+  const userEmail = await getUserEmail2(userId);
+  const server = createMcpServerForNest(
+    nestId,
+    userId,
+    userEmail,
+    requestBaseUrl(c.req.url)
+  );
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: void 0,
+    enableJsonResponse: true
+  });
+  await server.server.connect(transport);
+  try {
+    const response = await transport.handleRequest(c.req.raw);
+    return response;
+  } finally {
+    await transport.close();
+    await server.server.close();
+  }
+});
+
+// src/workflow/run-routes.ts
+import { Hono as Hono11 } from "hono";
+var runTriggerRoutes = new Hono11();
+runTriggerRoutes.post("/:agentNode{.+}", requireWorkflowPlane, async (c) => {
+  const nestId = c.req.param("nestId");
+  const agentNode = assertSafeNodeId(c.req.param("agentNode"));
+  const body = await c.req.json().catch(() => ({}));
+  const { storage } = await engineCache.get(nestId);
+  const triggeredBy = await resolveCallerEmail(c.get("userId"));
+  const bundle = await triggerRun({
+    nestId,
+    agentNode,
+    inputs: body.inputs,
+    triggeredBy,
+    storage,
+    parentRunId: body.parent_run_id
+  });
+  return c.json(bundle, 201);
+});
+var runListRoutes = new Hono11();
+runListRoutes.get("/", requireWorkflowPlane, async (c) => {
+  const nestId = c.req.param("nestId");
+  const canSeeDetail = permissionLevel(c.get("nestPermission")) >= permissionLevel("write");
+  const result = await listRuns(nestId, {
+    agent: c.req.query("agent") || void 0,
+    status: c.req.query("status") || void 0,
+    limit: Number(c.req.query("limit")) || void 0,
+    canSeeDetail
+  });
+  return c.json(result);
+});
+var runDetailRoutes = new Hono11();
+async function loadRunWithPermission(c, runId, required) {
+  const run = await loadRun(runId);
+  if (!run) throw new NotFoundError("Run not found");
+  const nestScope = c.get("nestScope");
+  if (nestScope && nestScope !== run.nest_id) {
+    throw new ForbiddenError("API key not authorized for this nest");
+  }
+  if (required === "write") {
+    if (isSuspended()) {
+      throw new AppError(503, `Server suspended by PromptOwl: ${getSuspensionReason()}`);
+    }
+    if (!getCurrentLicense()?.valid) {
+      throw new AppError(503, "A valid PromptOwl license is required to write runs.");
+    }
+  }
+  const perm = config.AUTH_MODE === "open" ? "owner" : await resolveNestPermission(run.nest_id, c.get("userId"));
+  if (perm === "none") {
+    throw new NotFoundError("Run not found");
+  }
+  if (permissionLevel(perm) < permissionLevel(required)) {
+    throw new ForbiddenError(
+      `This run belongs to a nest where you lack ${required} access.`
+    );
+  }
+  c.set("runPermission", perm);
+  return run;
+}
+runDetailRoutes.post("/:id/steps", requireWorkflowPlane, async (c) => {
+  const run = await loadRunWithPermission(c, c.req.param("id"), "write");
+  const body = await c.req.json();
+  const { seq } = await appendRunStep(run.id, body);
+  return c.json({ ok: true, seq }, 201);
+});
+runDetailRoutes.patch("/:id", requireWorkflowPlane, async (c) => {
+  const run = await loadRunWithPermission(c, c.req.param("id"), "write");
+  const body = await c.req.json();
+  const { status } = await closeRun(run.id, body);
+  return c.json({ ok: true, status });
+});
+runDetailRoutes.get("/:id", requireWorkflowPlane, async (c) => {
+  const run = await loadRunWithPermission(c, c.req.param("id"), "read");
+  const canSeeDetail = permissionLevel(c.get("runPermission")) >= permissionLevel("write");
+  const result = await getRunTrace(run, { canSeeDetail });
+  return c.json(result);
+});
+
+// src/definitions/routes.ts
+import { Hono as Hono12 } from "hono";
+import { v4 as uuid9 } from "uuid";
+var definitionRoutes = new Hono12();
+definitionRoutes.get("/", async (c) => {
+  const nestId = c.req.param("nestId");
+  const db = getDb();
+  const term = c.req.query("term")?.trim();
+  if (term) {
+    const row = await db.get(
+      "SELECT * FROM definitions WHERE nest_id = ? AND LOWER(term) = LOWER(?)",
+      [nestId, term]
+    );
+    if (!row) throw new NotFoundError(`No definition for "${term}"`);
+    return c.json({ definition: row });
+  }
+  const rows = await db.all(
+    "SELECT * FROM definitions WHERE nest_id = ? ORDER BY LOWER(term)",
+    [nestId]
+  );
+  return c.json({ count: rows.length, definitions: rows });
+});
+definitionRoutes.post("/", async (c) => {
+  const nestId = c.req.param("nestId");
+  const body = await c.req.json();
+  if (body.term !== void 0 && typeof body.term !== "string")
+    throw new ValidationError("term must be a string");
+  if (body.definition !== void 0 && typeof body.definition !== "string")
+    throw new ValidationError("definition must be a string");
+  if (body.linked_tag !== void 0 && body.linked_tag !== null && typeof body.linked_tag !== "string")
+    throw new ValidationError("linked_tag must be a string or null");
+  if (body.editing_id !== void 0 && typeof body.editing_id !== "string")
+    throw new ValidationError("editing_id must be a string");
+  const term = body.term?.trim();
+  const definition = body.definition?.trim();
+  const editingId = body.editing_id?.trim() || void 0;
+  if (!term || !definition) {
+    throw new ValidationError("term and definition are required");
+  }
+  if (term.length > 200) {
+    throw new ValidationError("term must be 200 characters or fewer");
+  }
+  const linkedTagProvided = "linked_tag" in body;
+  const linkedTag = body.linked_tag?.trim() ? `#${body.linked_tag.trim().replace(/^#+/, "").toLowerCase()}` : null;
+  const db = getDb();
+  const definedBy = await resolveCallerEmail(c.get("userId"));
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const applyUpdate = async (tx, id) => {
+    if (linkedTagProvided) {
+      await tx.run(
+        "UPDATE definitions SET term = ?, definition = ?, linked_tag = ?, defined_by = ?, updated_at = ? WHERE id = ?",
+        [term, definition, linkedTag, definedBy, now, id]
+      );
+    } else {
+      await tx.run(
+        "UPDATE definitions SET term = ?, definition = ?, defined_by = ?, updated_at = ? WHERE id = ?",
+        [term, definition, definedBy, now, id]
+      );
+    }
+  };
+  const { row, created } = await db.transaction(async (tx) => {
+    const existing = await tx.get(
+      "SELECT id FROM definitions WHERE nest_id = ? AND LOWER(term) = LOWER(?)",
+      [nestId, term]
+    );
+    let targetId;
+    let wasCreated = false;
+    if (editingId) {
+      const editing = await tx.get(
+        "SELECT id FROM definitions WHERE id = ? AND nest_id = ?",
+        [editingId, nestId]
+      );
+      if (!editing) throw new NotFoundError("Definition not found");
+      if (existing && existing.id !== editingId) {
+        throw new ConflictError(`A definition for "${term}" already exists`);
       }
-      const folders = listUnsyncedFolders();
-      if (!folders.length) return "No unsynced folders found.";
-      const list = folders.map(
-        (f, i) => `${i + 1}. **${f.label}** \`${f.name}\` \u2014 ${f.mdCount} md file(s), ${f.sizeBytes} bytes`
-      ).join("\n");
-      return `# Unsynced Folders (${folders.length})
-
-${list}`;
+      await applyUpdate(tx, editingId);
+      targetId = editingId;
+    } else if (existing) {
+      await applyUpdate(tx, existing.id);
+      targetId = existing.id;
+    } else {
+      targetId = uuid9();
+      wasCreated = true;
+      await tx.run(
+        `INSERT INTO definitions (id, nest_id, term, definition, linked_tag, defined_by, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+        [targetId, nestId, term, definition, linkedTag, definedBy, now, now]
+      );
     }
-    case "context_sync_folder": {
-      if (config.AUTH_MODE !== "open" && !await isLicenseAdminUserId(userId)) {
-        return "You don't have permission to sync folders. Server admin only.";
+    const fresh = await tx.get("SELECT * FROM definitions WHERE id = ?", [
+      targetId
+    ]);
+    return { row: fresh, created: wasCreated };
+  });
+  return c.json({ definition: row }, created ? 201 : 200);
+});
+definitionRoutes.delete("/:id", async (c) => {
+  const nestId = c.req.param("nestId");
+  const id = c.req.param("id");
+  const db = getDb();
+  const row = await db.get(
+    "SELECT id FROM definitions WHERE id = ? AND nest_id = ?",
+    [id, nestId]
+  );
+  if (!row) throw new NotFoundError("Definition not found");
+  await db.run("DELETE FROM definitions WHERE id = ?", [id]);
+  return c.json({ deleted: true });
+});
+
+// src/nests/asset-routes.ts
+import { Hono as Hono13 } from "hono";
+import { v4 as uuid10 } from "uuid";
+import { mkdir, readFile as readFile2, writeFile } from "fs/promises";
+import { join as join3 } from "path";
+var assetRoutes = new Hono13();
+var CONTENT_TYPES = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp"
+};
+var SAFE_NAME = /^[0-9a-f-]{36}\.(png|jpe?g|gif|webp)$/;
+assetRoutes.post("/", async (c) => {
+  const nestId = c.req.param("nestId");
+  const body = await c.req.parseBody();
+  const file = body["file"];
+  if (!(file instanceof File)) {
+    throw new ValidationError('multipart field "file" (an image) is required');
+  }
+  const ext = (file.name.split(".").pop() || "").toLowerCase();
+  if (!CONTENT_TYPES[ext]) {
+    throw new ValidationError(
+      `unsupported image type ".${ext}" \u2014 allowed: ${Object.keys(CONTENT_TYPES).join(", ")}`
+    );
+  }
+  const name = `${uuid10()}.${ext === "jpeg" ? "jpg" : ext}`;
+  const dir = join3(resolveNestPath(nestId), "assets");
+  await mkdir(dir, { recursive: true });
+  await writeFile(join3(dir, name), Buffer.from(await file.arrayBuffer()));
+  return c.json(
+    {
+      file: name,
+      url: `/nests/${nestId}/assets/${name}`,
+      markdown: `![${file.name.replace(/\.[^.]+$/, "")}](/nests/${nestId}/assets/${name})`
+    },
+    201
+  );
+});
+assetRoutes.get("/:file", async (c) => {
+  const nestId = c.req.param("nestId");
+  const name = c.req.param("file");
+  if (!SAFE_NAME.test(name)) {
+    throw new ValidationError("invalid asset name");
+  }
+  let bytes;
+  try {
+    bytes = await readFile2(join3(resolveNestPath(nestId), "assets", name));
+  } catch {
+    throw new NotFoundError("Asset not found");
+  }
+  const ext = name.split(".").pop();
+  return c.body(new Uint8Array(bytes), 200, {
+    "Content-Type": CONTENT_TYPES[ext],
+    // uuid names never change content — cache hard.
+    "Cache-Control": "public, max-age=31536000, immutable"
+  });
+});
+
+// src/mcp/server-routes.ts
+import { Hono as Hono14 } 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 { nest, documents } = await syncUnsyncedFolder(
-          userId,
-          args.name,
-          userEmail
-        );
-        return `Synced folder "${args.name}" \u2192 nest **${nest.name}** (${nest.id}) with ${documents} document(s).`;
-      } catch (err) {
-        return `Failed to sync folder: ${err.message}`;
+        const { storage } = await engineCache.get(n.id);
+        document_count = (await storage.discoverDocuments()).length;
+      } catch {
       }
-    }
-    default:
-      return `Unknown tool: ${toolName}`;
+      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");
 }
-
-// src/mcp/routes.ts
-import { z } from "zod";
-var mcpRoutes = new Hono7();
-async function getUserEmail2(userId) {
-  const db = getDb();
-  const user = await db.get("SELECT email FROM users WHERE id = ?", [userId]);
-  return user?.email || "anonymous@localhost";
+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,
+    baseUrl
+  });
 }
-function createMcpServerForNest(nestId, userId, userEmail) {
-  const server = new McpServer(
-    { name: `contextnest-${nestId}`, version: "1.0.0" },
+function createServerMcp(userId, userEmail, nestScope, baseUrl) {
+  const server = new McpServer2(
+    { name: "contextnest-server", version: "1.0.0" },
     { capabilities: { tools: {} } }
   );
-  for (const tool of TOOL_DEFINITIONS) {
+  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 = z.string();
-      else if (def.type === "number") field = z.number();
-      else if (def.type === "array") field = z.array(z.string());
-      else field = z.any();
+      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 engine = await engineCache.get(nestId);
-      const text = await handleToolCall(tool.name, args, {
-        storage: engine.storage,
-        queryEngine: engine.query,
-        versionManager: engine.versions,
-        nestId,
+      const text = await handleServerToolCall(
+        tool.name,
+        args,
         userId,
-        userEmail
-      });
+        userEmail,
+        nestScope,
+        baseUrl
+      );
       return { content: [{ type: "text", text }] };
     });
   }
   return server;
 }
-mcpRoutes.all("/", async (c) => {
-  const nestId = c.req.param("nestId");
+var serverMcpRoutes = new Hono14();
+serverMcpRoutes.all("/", async (c) => {
   const userId = c.get("userId");
-  const userEmail = await getUserEmail2(userId);
-  const server = createMcpServerForNest(nestId, userId, userEmail);
-  const transport = new WebStandardStreamableHTTPServerTransport({
+  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 {
-    const response = await transport.handleRequest(c.req.raw);
-    return response;
+    return await transport.handleRequest(c.req.raw);
   } finally {
     await transport.close();
     await server.server.close();
   }
 });
+var nestIndexRoutes = new Hono14();
+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 Hono14();
+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 Hono8 } from "hono";
+import { Hono as Hono15 } from "hono";
 
 // src/governance/comment-service.ts
-import { v4 as uuid4 } from "uuid";
+import { v4 as uuid11 } from "uuid";
 async function createComment(params) {
   const db = getDb();
   const body = (params.body ?? "").trim();
@@ -4647,7 +6855,7 @@ async function createComment(params) {
       throw new Error("Parent comment not found on this node");
     }
   }
-  const id = uuid4();
+  const id = uuid11();
   await db.run(
     `INSERT INTO comments
        (id, nest_id, node_id, version, anchor_start, anchor_end, anchor_text,
@@ -4847,7 +7055,7 @@ function rowToComment(row) {
 
 // src/governance/stewards-parser.ts
 import { readFileSync as readFileSync2, existsSync } from "fs";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 function parseStewardsYaml(content) {
   const result = { version: 1 };
   const lines = content.split("\n");
@@ -4913,9 +7121,9 @@ function parseEntry(str) {
 function loadStewardsConfig(nestId) {
   const nestPath = resolveNestPath(nestId);
   const candidates = [
-    join3(nestPath, "stewards.yaml"),
-    join3(nestPath, "stewards.yml"),
-    join3(nestPath, ".context", "stewards.yaml")
+    join4(nestPath, "stewards.yaml"),
+    join4(nestPath, "stewards.yml"),
+    join4(nestPath, ".context", "stewards.yaml")
   ];
   for (const candidatePath of candidates) {
     if (existsSync(candidatePath)) {
@@ -4932,7 +7140,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 Hono15();
 governanceRoutes.get("/stewards", async (c) => {
   const nestId = c.req.param("nestId");
   const scope = c.req.query("scope");
@@ -4961,7 +7169,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 +7244,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 +7268,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 +7278,7 @@ governanceRoutes.get("/activity", async (c) => {
   const activity = await getActivity({ nestId, limit });
   return c.json({ activity });
 });
-var governanceNodeRoutes = new Hono8();
+var governanceNodeRoutes = new Hono15();
 governanceNodeRoutes.get("/:nodeId{.+}/stewards", async (c) => {
   const nestId = c.req.param("nestId");
   const nodeId = c.req.param("nodeId");
@@ -5129,7 +7337,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 +7361,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 +7394,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({
@@ -5195,7 +7403,8 @@ governanceNodeRoutes.post("/:nodeId{.+}/submit-review", async (c) => {
       version: currentVersion,
       requestedBy: userEmail,
       note: body.note,
-      priority: body.priority
+      priority: body.priority,
+      baseUrl: requestBaseUrl(c.req.url)
     });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -5221,7 +7430,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({
@@ -5230,7 +7439,8 @@ governanceNodeRoutes.post("/:nodeId{.+}/approve", async (c) => {
       version: await getCurrentVersion(nestId, nodeId),
       approvedBy: userEmail,
       note: body.note,
-      override: body.override && isAdmin
+      override: body.override && isAdmin,
+      baseUrl: requestBaseUrl(c.req.url)
     });
     return c.json({ review: request });
   } catch (err) {
@@ -5244,14 +7454,15 @@ 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,
       nodeId,
       version: await getCurrentVersion(nestId, nodeId),
       rejectedBy: userEmail,
-      note: body.note
+      note: body.note,
+      baseUrl: requestBaseUrl(c.req.url)
     });
     return c.json({ review: request });
   } catch (err) {
@@ -5261,19 +7472,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 +7517,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 +7553,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 +7574,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 +7582,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(
@@ -5402,12 +7613,12 @@ async function ensureAnonymousUser() {
 // src/app.ts
 import { serveStatic } from "@hono/node-server/serve-static";
 import { fileURLToPath } from "url";
-import { dirname, join as join4, relative as relative2 } from "path";
+import { dirname, join as join5, relative as relative2 } from "path";
 import { existsSync as existsSync2 } from "fs";
 var HERE = dirname(fileURLToPath(import.meta.url));
 var UI_DIR_CANDIDATES = [
-  join4(HERE, "web3"),
-  join4(process.cwd(), "dist", "web3")
+  join5(HERE, "web3"),
+  join5(process.cwd(), "dist", "web3")
 ];
 var UI_DIR_ABS = UI_DIR_CANDIDATES.find((p) => existsSync2(p)) || UI_DIR_CANDIDATES[0];
 var UI_DIR_REL = relative2(process.cwd(), UI_DIR_ABS) || ".";
@@ -5444,7 +7655,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 Hono16({ router: new LinearRouter() });
   const corsOrigins = config.CORS_ORIGINS;
   app.use(
     "*",
@@ -5465,6 +7676,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({
@@ -5474,6 +7701,14 @@ function createApp() {
       auth_mode: config.AUTH_MODE,
       logo_url: config.LOGO_URL,
       promptowl_sign_in_gate: config.PROMPTOWL_SIGN_IN_GATE,
+      // Public feature flags the SPA needs before auth to decide what to
+      // render. Mirrors the server-side route gate so UI and API agree:
+      // flag off → the plane's routes 404 AND its UI stays hidden.
+      workflow_plane_enabled: config.FEATURE_WORKFLOW_PLANE,
+      // Sub-agent runs gate its own recursion surface separately (env-only,
+      // must clear a security review — NOT a UI toggle). Exposed read-only so
+      // the Runs page shows the "spawn sub-agent" option only when it's live.
+      subagent_runs_enabled: config.FEATURE_SUBAGENT_RUNS,
       ...isSuspended() && { suspended_reason: getSuspensionReason() }
     })
   );
@@ -5564,7 +7799,13 @@ 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,
+    workflow_plane_enabled: config.FEATURE_WORKFLOW_PLANE,
+    subagent_runs_enabled: config.FEATURE_SUBAGENT_RUNS,
+    slack_webhook_url: config.SLACK_WEBHOOK_URL ?? "",
+    smtp_url: config.SMTP_URL ?? "",
+    notify_email_from: config.NOTIFY_EMAIL_FROM ?? "",
+    notify_email_to: config.NOTIFY_EMAIL_TO ?? ""
   });
   app.get("/admin/settings", async (c) => {
     if (!await adminSettingsAllowed(c))
@@ -5599,6 +7840,49 @@ function createApp() {
     if ("telemetry_enabled" in body) {
       pending.push({ name: "TELEMETRY_ENABLED", value: body.telemetry_enabled ? "true" : "false" });
     }
+    if ("workflow_plane_enabled" in body) {
+      pending.push({
+        name: "FEATURE_WORKFLOW_PLANE",
+        value: body.workflow_plane_enabled ? "true" : null
+      });
+    }
+    if ("subagent_runs_enabled" in body) {
+      const planeOn = "workflow_plane_enabled" in body ? !!body.workflow_plane_enabled : config.FEATURE_WORKFLOW_PLANE;
+      if (body.subagent_runs_enabled && !planeOn) {
+        errors.push(
+          "subagent_runs_enabled requires workflow_plane_enabled to be on"
+        );
+      } else {
+        pending.push({
+          name: "FEATURE_SUBAGENT_RUNS",
+          value: body.subagent_runs_enabled ? "true" : null
+        });
+      }
+    }
+    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 ("smtp_url" in body) {
+      const v = String(body.smtp_url ?? "").trim();
+      if (v && !/^smtps?:\/\//i.test(v))
+        errors.push("smtp_url must be an smtp:// or smtps:// URL (or empty to disable)");
+      else pending.push({ name: "SMTP_URL", value: v || null });
+    }
+    if ("notify_email_from" in body) {
+      const v = String(body.notify_email_from ?? "").trim();
+      if (v && !isEmailish(v))
+        errors.push("notify_email_from must be a plain email address");
+      else pending.push({ name: "NOTIFY_EMAIL_FROM", value: v || null });
+    }
+    if ("notify_email_to" in body) {
+      const v = String(body.notify_email_to ?? "").trim();
+      if (v && !isEmailListish(v))
+        errors.push("notify_email_to must be a comma-separated list of email addresses");
+      else pending.push({ name: "NOTIFY_EMAIL_TO", 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 +7908,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 +7957,14 @@ function createApp() {
       users: usersRow.c
     });
   });
-  const nestsApp = new Hono9();
+  app.use("/runs/*", flexAuthMiddleware);
+  app.route("/runs", runDetailRoutes);
+  app.route("/llms.txt", llmsTxtRoutes);
+  app.use("/index", flexAuthMiddleware);
+  app.route("/index", nestIndexRoutes);
+  app.use("/mcp", flexAuthMiddleware);
+  app.route("/mcp", serverMcpRoutes);
+  const nestsApp = new Hono16();
   nestsApp.use("*", flexAuthMiddleware);
   nestsApp.use("*", async (c, next) => {
     const localPath = c.req.path.replace(/^\/nests\//, "");
@@ -5698,8 +8012,27 @@ function createApp() {
       return next();
     }
     const permission = await resolveNestPermission(nestId, userId);
+    const isReadQuery = parts.length === 2 && ["context", "query", "search", "export"].includes(parts[1]);
+    let grantRole = null;
+    let grantNestVisible = false;
     if (permission === "none") {
-      return c.json({ error: "Nest not found" }, 404);
+      if (parts[1] === "nodes" && parts.length >= 3) {
+        let targetTail = parts.slice(2).join("/");
+        try {
+          targetTail = decodeURIComponent(targetTail);
+        } catch {
+        }
+        grantRole = await resolveNodeGrant(nestId, userId, targetTail);
+      } else if (parts.length === 1 && c.req.method === "GET") {
+        grantNestVisible = await hasAnyGrant(nestId, userId);
+      } else if (parts[1] === "nodes" && parts.length === 2 && c.req.method === "GET") {
+        grantNestVisible = await hasAnyGrant(nestId, userId);
+      } else if (isReadQuery) {
+        grantNestVisible = await hasAnyGrant(nestId, userId);
+      }
+      if (!grantRole && !grantNestVisible) {
+        return c.json({ error: "Nest not found" }, 404);
+      }
     }
     let required = "read";
     const path = c.req.path;
@@ -5720,7 +8053,7 @@ function createApp() {
       required = "admin";
     } else if (resource === "collaborators") {
       required = c.req.method === "GET" || c.req.method === "POST" ? "write" : "admin";
-    } else if (c.req.method !== "GET" && !isStewardActionPath && !isCommentAction && !isAnnotationAction) {
+    } else if (c.req.method !== "GET" && !isStewardActionPath && !isCommentAction && !isAnnotationAction && !isReadQuery) {
       required = "write";
     }
     const isNodeRevert = c.req.method === "POST" && parts.length >= 4 && parts[parts.length - 1] === "revert";
@@ -5746,7 +8079,9 @@ function createApp() {
         );
       }
     }
-    if (!stewardEditorBypass && permissionLevel(permission) < permissionLevel(required)) {
+    const grantLevel = grantRole ? permissionLevel(grantRole) : grantNestVisible ? permissionLevel("read") : 0;
+    const effectiveLevel = Math.max(permissionLevel(permission), grantLevel);
+    if (!stewardEditorBypass && effectiveLevel < permissionLevel(required)) {
       return c.json(
         {
           error: `You don't have access to perform this action on this nest. Required permission: '${required}', your permission: '${permission}'. Ask the nest owner or a server admin to grant you ${required} access.`,
@@ -5756,16 +8091,30 @@ function createApp() {
         403
       );
     }
-    c.set("nestPermission", permission);
+    c.set(
+      "nestPermission",
+      permission === "none" && grantRole ? grantRole : 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);
+  nestsApp.route("/:nestId/grants", grantRoutes);
+  nestsApp.route("/:nestId/edge-types", edgeTypeRoutes);
+  nestsApp.route("/:nestId/edges", edgeRoutes);
+  nestsApp.route("/:nestId/run", runTriggerRoutes);
+  nestsApp.route("/:nestId/runs", runListRoutes);
+  nestsApp.route("/:nestId/definitions", definitionRoutes);
+  nestsApp.route("/:nestId/assets", assetRoutes);
   nestsApp.route("/:nestId/mcp", mcpRoutes);
   app.route("/nests", nestsApp);
   app.use("/assets/*", serveStatic({ root: UI_DIR_REL }));