@promptowl/contextnest-community 1.6.0 → 1.7.0

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   reject,
   safePublishDocument,
   submitForReview
-} from "./chunk-MZGFKBOK.js";
+} from "./chunk-MOXICJPD.js";
 import {
   checkConflict,
   createVersion,
@@ -25,7 +25,7 @@ import {
   getDisplayStatus,
   getVersions,
   setApprovedVersion
-} from "./chunk-T5L4LYU4.js";
+} from "./chunk-VD5QX2ZQ.js";
 import {
   AppError,
   ConflictError,
@@ -35,10 +35,10 @@ import {
   ValidationError,
   canCreateInNest,
   canManageStewards,
-  canManageWith,
   canUserAccess,
   canUserApprove,
   canUserEdit,
+  collabPermToRole,
   createNest,
   createStewardRecord,
   deleteNest,
@@ -84,14 +84,14 @@ import {
   updateSteward,
   upsertEnvVar,
   validateLicense
-} from "./chunk-2TUMMVBG.js";
+} from "./chunk-43DOX4LH.js";
 import {
   config,
   getDb,
   initDb,
   insertOrIgnore,
   nowExpr
-} from "./chunk-7V33Z6CS.js";
+} from "./chunk-QMLAXQES.js";
 import {
   ANON_EMAIL,
   ANON_USER_ID
@@ -487,7 +487,7 @@ authRoutes.post("/login", async (c) => {
     throw new ValidationError("email and password are required");
   }
   const ip = clientIp(c);
-  const emailLower = body.email.toLowerCase();
+  const emailLower = normalizeEmail(body.email);
   const hasIp = ip !== "unknown";
   const ipKey = `login:ip:${ip}`;
   const emailKey = `login:email:${emailLower}`;
@@ -496,7 +496,7 @@ authRoutes.post("/login", async (c) => {
   }
   const db = getDb();
   const user = await db.get(
-    "SELECT id, email, name, password_hash, is_admin FROM users WHERE LOWER(email) = ?",
+    "SELECT id, email, name, password_hash, is_admin, is_invited FROM users WHERE LOWER(email) = ?",
     [emailLower]
   );
   const check = user ? await verifyPassword(body.password, user.password_hash) : { ok: false, needsRehash: false };
@@ -509,6 +509,12 @@ authRoutes.post("/login", async (c) => {
   console.log(`[auth] login OK \u2014 counter reset ip=${ip} email=${emailLower}`);
   if (hasIp) clear(ipKey);
   clear(emailKey);
+  if (user.is_invited === 1) {
+    try {
+      await db.run("UPDATE users SET is_invited = 0 WHERE id = ?", [user.id]);
+    } catch {
+    }
+  }
   if (check.needsRehash) {
     try {
       const newHash = await hashPassword(body.password);
@@ -810,7 +816,7 @@ authRoutes.post("/password", authMiddleware, async (c) => {
     );
   }
   const newHash = await hashPassword(body.next);
-  await db.run("UPDATE users SET password_hash = ? WHERE id = ?", [
+  await db.run("UPDATE users SET password_hash = ?, is_invited = 0 WHERE id = ?", [
     newHash,
     userId
   ]);
@@ -853,14 +859,13 @@ authRoutes.post("/admin/reset-password/:userId", async (c) => {
       newHash,
       target.id
     ]);
-    await tx.run("DELETE FROM api_keys WHERE user_id = ?", [target.id]);
   });
   await deleteAllSessionsForUser(target.id);
   trackEvent("admin.reset_password", { adminId: callerId, userId: target.id });
   return c.json({
     ok: true,
     email: target.email,
-    keys_revoked: true,
+    keys_revoked: false,
     // Plaintext returned ONCE, only when the server generated it.
     temporary_password: generated ?? void 0
   });
@@ -936,40 +941,40 @@ authRoutes.post("/invite", async (c) => {
       403
     );
   }
-  let user = await db.get(
-    "SELECT id, email FROM users WHERE LOWER(email) = ?",
+  const existing = await db.get(
+    "SELECT id, email, is_invited FROM users WHERE LOWER(email) = ?",
     [email]
   );
-  if (!user) {
-    const userId = uuid();
-    const placeholderHash = await hashPassword(uuid());
+  if (existing && existing.is_invited === 0) {
+    return c.json(
+      {
+        error: "A user with this email already exists. Use Reset password to issue them a new password."
+      },
+      409
+    );
+  }
+  const tempPassword = uuid().replace(/-/g, "").slice(0, 16);
+  const passwordHash = await hashPassword(tempPassword);
+  let userId;
+  if (existing) {
+    userId = existing.id;
+    await db.run("UPDATE users SET password_hash = ? WHERE id = ?", [
+      passwordHash,
+      userId
+    ]);
+  } else {
+    userId = uuid();
     await db.run(
       "INSERT INTO users (id, email, name, password_hash, is_invited) VALUES (?, ?, ?, ?, 1)",
-      [userId, email, null, placeholderHash]
+      [userId, email, null, passwordHash]
     );
-    user = { id: userId, email };
   }
-  const apiKey = generateApiKey();
-  const keyId = uuid();
-  await db.transaction(async (tx) => {
-    await tx.run("DELETE FROM api_keys WHERE user_id = ?", [user.id]);
-    await tx.run(
-      "INSERT INTO api_keys (id, user_id, key_hash, key_prefix, label) VALUES (?, ?, ?, ?, ?)",
-      [
-        keyId,
-        user.id,
-        hashApiKey(apiKey),
-        getKeyPrefix(apiKey),
-        body.label || "teammate"
-      ]
-    );
-  });
-  trackEvent("admin.invite", { adminId: callerId, email: body.email });
+  trackEvent("admin.invite", { adminId: callerId, email });
   return c.json(
     {
-      api_key: apiKey,
-      user: { id: user.id, email: user.email },
-      message: "Copy this key and share it securely \u2014 it won't be shown again."
+      temporary_password: tempPassword,
+      user: { id: userId, email },
+      message: "Share this temporary password securely. Your teammate signs in with their email + this password, then can change it and create their own API key."
     },
     201
   );
@@ -1284,7 +1289,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-MUZYTYMW.js");
+    const { createVersion: createVersion2, setApprovedVersion: setApprovedVersion2 } = await import("./version-service-FJWVTZKR.js");
     await createVersion2({
       nestId: input.nestId,
       nodeId: input.documentId,
@@ -1444,8 +1449,19 @@ async function listNodesForCallerByEmail(nestId, userEmail, filters = {}) {
 }
 async function createNode(nestId, input, userEmail) {
   const { storage, versions: versionManager } = await engineCache.get(nestId);
-  const slug = input.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-  const id = input.id ?? `nodes/${slug}`;
+  const slugify = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  const slug = slugify(input.title);
+  let id = input.id;
+  if (!id) {
+    const folderSegments = (input.folder ?? "").split("/").map(slugify).filter(Boolean);
+    if (folderSegments.length > 8) {
+      throw new ValidationError("folder may nest at most 8 levels deep");
+    }
+    if ([...folderSegments, slug].some((seg) => seg.length > 100)) {
+      throw new ValidationError("each folder or title segment must be at most 100 characters");
+    }
+    id = folderSegments.length > 0 ? `nodes/${folderSegments.join("/")}/${slug}` : `nodes/${slug}`;
+  }
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const tags = (input.tags || []).map(normalizeTag2);
   const hasStewards = await isStewardshipEnabled(nestId);
@@ -1881,7 +1897,18 @@ nestRoutes.get("/", async (c) => {
     const permission = await effectivePermission(n.id, userId);
     const is_owner = permission === "owner";
     let owner_email = null;
-    const roles = is_owner ? ["owner"] : await resolveUserRoles(n.id, callerEmail);
+    let roles;
+    if (is_owner) {
+      roles = ["owner"];
+    } else {
+      const grantRole = collabPermToRole(
+        await getCollaboratorRole(n.id, callerEmail)
+      );
+      const stewardRoles = await getStewardRolesForUser(n.id, callerEmail);
+      roles = [
+        ...new Set([grantRole, ...stewardRoles].filter(Boolean))
+      ];
+    }
     if (!is_owner && n.user_id !== ANON_USER_ID) {
       const row = await db.get(ownerEmailSql, [n.user_id]);
       owner_email = row?.email ?? null;
@@ -1895,7 +1922,25 @@ nestRoutes.get("/", async (c) => {
     seen.add(n.id);
     out.push(await annotate(n));
   }
-  return c.json({ nests: out });
+  const docRows = await db.all(
+    "SELECT nest_id, COUNT(DISTINCT node_id) AS c FROM node_versions GROUP BY nest_id"
+  );
+  const docByNest = new Map(docRows.map((r) => [r.nest_id, r.c]));
+  const collabRows = await db.all(
+    "SELECT nest_id, COUNT(*) AS c FROM nest_collaborators GROUP BY nest_id"
+  );
+  const collabByNest = new Map(collabRows.map((r) => [r.nest_id, r.c]));
+  const stewardRows = await db.all(
+    "SELECT nest_id, COUNT(DISTINCT user_email) AS c FROM stewards WHERE is_active = 1 GROUP BY nest_id"
+  );
+  const stewardByNest = new Map(stewardRows.map((r) => [r.nest_id, r.c]));
+  const withMeta = out.map((n) => ({
+    ...n,
+    document_count: docByNest.get(n.id) ?? 0,
+    collaborator_count: collabByNest.get(n.id) ?? 0,
+    steward_count: stewardByNest.get(n.id) ?? 0
+  }));
+  return c.json({ nests: withMeta });
 });
 nestRoutes.post("/", async (c) => {
   const body = await c.req.json();
@@ -2011,10 +2056,10 @@ nestRoutes.patch("/:nestId/settings", async (c) => {
   const userId = c.get("userId");
   const isServerAdmin = await isLicenseAdminUserId(userId);
   const permission = await effectivePermission(nestId, userId);
-  if (!isServerAdmin && permission !== "owner") {
+  if (!isServerAdmin && permission !== "owner" && permission !== "admin") {
     return c.json(
       {
-        error: "Only the nest owner or the server license-admin can update nest settings."
+        error: "Only a nest admin, the nest owner, or the server license-admin can update nest settings."
       },
       403
     );
@@ -2025,6 +2070,14 @@ nestRoutes.patch("/:nestId/settings", async (c) => {
     if (body.stewardship_enabled) {
       await setStewardshipEnabled(nestId, true);
     } else {
+      if (!isServerAdmin && permission !== "owner") {
+        return c.json(
+          {
+            error: "Only the nest owner or the server license-admin can disable stewardship (this permanently wipes stewards and pending reviews)."
+          },
+          403
+        );
+      }
       wiped = await disableStewardshipAndWipeGovernance(nestId);
     }
   }
@@ -2220,416 +2273,113 @@ function isMarkdownFormat(c) {
   return c.req.query("format") === "markdown";
 }
 
-// src/nodes/routes.ts
-var nodeRoutes = new Hono4();
-function nodeAsMarkdown(response, nodeId) {
-  return nodeToMarkdown({
-    id: nodeId,
-    title: response.title,
-    tags: response.tags,
-    status: response.status,
-    body: response.content
-  });
+// src/annotations/service.ts
+import { v4 as uuid3 } from "uuid";
+
+// src/annotations/projection.ts
+var MAX_CONTEXT_CHARS = 250;
+var MAX_QUOTE_CHARS = 1e3;
+function clampAnchor(raw) {
+  if (!raw) return null;
+  const quote = (raw.quote ?? "").trim().slice(0, MAX_QUOTE_CHARS);
+  if (!quote) return null;
+  const before = (raw.before ?? "").slice(-MAX_CONTEXT_CHARS);
+  const after = (raw.after ?? "").slice(0, MAX_CONTEXT_CHARS);
+  const line = typeof raw.line === "number" && Number.isFinite(raw.line) && raw.line > 0 ? Math.floor(raw.line) : void 0;
+  return { quote, before, after, ...line !== void 0 ? { line } : {} };
 }
-nodeRoutes.get("/", async (c) => {
-  const nestId = c.req.param("nestId");
-  const userId = c.get("userId");
-  const nodes = await listNodesForCaller(nestId, userId);
-  return c.json({ count: nodes.length, nodes });
-});
-nodeRoutes.post("/", async (c) => {
-  const body = await c.req.json();
-  if (!body.title || !body.content) {
-    throw new ValidationError("title and content are required");
+function oneLine(s) {
+  return s.replace(/\s+/g, " ").replace(/--+>/g, "-\u2192").trim();
+}
+function renderAnchor(anchor) {
+  if (!anchor) {
+    return "<!-- anchor: whole-artifact -->";
   }
-  const nestId = c.req.param("nestId");
-  const authorEmail = await getUserEmail(c);
-  const { node } = await createNode(
-    nestId,
-    {
-      title: body.title,
-      content: body.content,
-      type: body.type,
-      tags: body.tags,
-      scope: body.scope,
-      status: body.status
-    },
-    authorEmail
-  );
-  const resolved = await resolveStewardsForNode(nestId, node.id);
-  return c.json({
-    node: toNodeResponse(node),
-    stewards: resolved.length > 0 ? resolved.map((r) => ({
-      email: r.steward.userEmail,
-      role: r.steward.role,
-      source: r.source
-    })) : void 0
-  }, 201);
-});
-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-VIKF3VZB.js");
-  const { stewards, fallbackToOwner, ownerEmail } = await resolveStewardsWithFallback2(
-    nestId,
-    nodeId
+  const linePart = anchor.line !== void 0 ? `line ${anchor.line} \xB7 ` : "";
+  const context = `\u2026${oneLine(anchor.before)}\u3008${oneLine(anchor.quote)}\u3009${oneLine(
+    anchor.after
+  )}\u2026`;
+  return `<!-- anchor: ${linePart}quote "${oneLine(anchor.quote)}" \xB7 context ${context} -->`;
+}
+function statusHeading(thread) {
+  if (thread.status === "resolved") {
+    const who = thread.resolvedBy ? `${thread.resolvedBy}, ` : "";
+    const when = thread.resolvedAt ? `${thread.resolvedAt}` : "";
+    const meta = who || when ? ` (${who}${when})` : "";
+    return `\u2705 RESOLVED${meta}`;
+  }
+  return "\u{1F7E0} OPEN";
+}
+function snapshotLabel(v) {
+  return v == null ? "Unpinned" : `Snapshot v${v}`;
+}
+function orderThreads(threads) {
+  return [...threads].sort((a, b) => {
+    if (a.status !== b.status) return a.status === "open" ? -1 : 1;
+    return a.createdAt.localeCompare(b.createdAt);
+  });
+}
+function projectThreadsToMarkdown(artifactTitle, threads) {
+  const lines = [];
+  lines.push(`# ${artifactTitle} \u2014 Annotations`);
+  lines.push("");
+  lines.push(
+    "> Auto-generated from review comments, grouped by the artifact snapshot each was anchored to. **Open** threads are unresolved feedback for the next iteration; **resolved** threads were already addressed (don't re-break them)."
   );
-  return c.json({
-    nodeId,
-    stewards: stewards.map((r) => ({
-      email: r.steward.userEmail,
-      role: r.steward.role,
-      scope: r.steward.scope,
-      source: r.source,
-      priority: r.priority
-    })),
-    fallbackToOwner,
-    ownerEmail
+  lines.push("");
+  if (threads.length === 0) {
+    lines.push("_No annotations yet._");
+    lines.push("");
+    return lines.join("\n");
+  }
+  const buckets2 = /* @__PURE__ */ new Map();
+  for (const t of threads) {
+    const key = t.snapshotVersion ?? null;
+    (buckets2.get(key) ?? buckets2.set(key, []).get(key)).push(t);
+  }
+  const keys = [...buckets2.keys()].sort((a, b) => {
+    if (a == null) return 1;
+    if (b == null) return -1;
+    return b - a;
   });
-});
-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-MUZYTYMW.js");
-  const allVersions = await getVersions2(nestId, nodeId);
-  const approved = await getApprovedVersion2(nestId, nodeId);
+  for (const key of keys) {
+    lines.push(`## ${snapshotLabel(key)}`);
+    lines.push("");
+    for (const thread of orderThreads(buckets2.get(key))) {
+      lines.push(`### Thread \xB7 ${statusHeading(thread)}`);
+      lines.push(renderAnchor(thread.anchor));
+      for (const comment of thread.comments) {
+        lines.push(
+          `- **${comment.author}** \xB7 ${comment.createdAt} \u2014 ${comment.body}`
+        );
+      }
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/annotations/service.ts
+async function loadComments(threadId) {
   const db = getDb();
-  const resolutions = await db.all(
-    `SELECT version, status, resolved_by, resolved_at
-         FROM review_requests
-        WHERE nest_id = ? AND node_id = ?
-          AND status IN ('approved', 'rejected')
-          AND resolved_by IS NOT NULL
-        ORDER BY resolved_at DESC`,
-    [nestId, nodeId]
+  const rows = await db.all(
+    "SELECT id, author, body, created_at FROM annotation_comments WHERE thread_id = ? ORDER BY created_at ASC, id ASC",
+    [threadId]
   );
-  const byVersion = /* @__PURE__ */ new Map();
-  for (const r of resolutions) {
-    if (!byVersion.has(r.version)) {
-      byVersion.set(r.version, { status: r.status, resolvedBy: r.resolved_by });
-    }
-  }
-  const enriched = allVersions.map((v) => {
-    const r = byVersion.get(v.version);
-    return r ? { ...v, resolvedBy: r.resolvedBy, resolutionStatus: r.status } : v;
-  });
-  return c.json({
-    versions: enriched,
-    approvedVersion: approved,
-    currentVersion: allVersions[0]?.version || 0
-  });
-});
-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-QJ3FBOML.js");
-  const history = await getReviewHistory2(nestId, nodeId);
-  return c.json({ reviews: history });
-});
-nodeRoutes.post("/:nodeId{.+}/revert", async (c) => {
-  const nestId = c.req.param("nestId");
-  const nodeId = c.req.param("nodeId");
-  const { versions: versionManager } = await engineCache.get(nestId);
-  const userId = c.get("userId");
-  const userEmail = await resolveCallerEmail(userId);
-  if (!await canReadNode(nestId, nodeId, userId, userEmail)) {
-    return c.json(
-      { error: "Access denied \u2014 no steward assignment for this node" },
-      403
-    );
-  }
-  const body = await c.req.json().catch(() => ({}));
-  const targetVersion = Number(body.targetVersion);
-  if (!Number.isInteger(targetVersion) || targetVersion < 1) {
-    throw new ValidationError("targetVersion (a positive integer) is required");
-  }
-  let raw;
-  try {
-    raw = await versionManager.reconstructVersion(nodeId, targetVersion);
-  } catch {
-    throw new NotFoundError(
-      `Version ${targetVersion} not found for ${nodeId}`
-    );
-  }
-  const content = bodyOnly(nodeId, raw);
-  const { node, version } = await updateNode(
-    nestId,
-    nodeId,
-    { content, changeNote: `Restored from version ${targetVersion}` },
-    userEmail
-  );
-  await trackEvent("node.revert", { nestId, nodeId, targetVersion });
-  return c.json({ ok: true, version, node: toNodeResponse(node) });
-});
-nodeRoutes.get("/:nodeId{.+}", async (c) => {
-  const nestId = c.req.param("nestId");
-  const nodeId = c.req.param("nodeId");
-  const { storage, versions: versionManager } = await engineCache.get(nestId);
-  const userId = c.get("userId");
-  const userEmail = await resolveCallerEmail(userId);
-  if (!await canReadNode(nestId, nodeId, userId, userEmail)) {
-    return c.json(
-      { error: "Access denied \u2014 no steward assignment for this node" },
-      403
-    );
-  }
-  let node;
-  try {
-    node = await storage.readDocument(nodeId, { verifyChecksum: true });
-  } catch {
-    throw new NotFoundError(`Node not found: ${nodeId}`);
-  }
-  if (node.pendingChange) {
-    try {
-      await scanDocumentForDrift(nestId, nodeId, userEmail || "system:read");
-      const refreshed = await getPendingChange(nestId, nodeId);
-      if (refreshed) node.pendingChange = refreshed;
-    } catch (err) {
-      console.error("[external-edit] stage-on-read failed:", err);
-    }
-    try {
-      const latest = await loadLatestApprovedNode(nestId, nodeId);
-      if (latest) {
-        node = { ...latest, pendingChange: node.pendingChange };
-      }
-    } catch (err) {
-      console.error("[external-edit] reconstruct-latest failed:", err);
-    }
-  }
-  const response = toNodeResponse(node);
-  if (await isPublicReader(nestId, userId)) {
-    const approved = await getApprovedVersion(nestId, nodeId);
-    if (approved != null) {
-      try {
-        const raw = await versionManager.reconstructVersion(
-          nodeId,
-          approved
-        );
-        response.content = bodyOnly(nodeId, raw);
-      } catch (err) {
-        console.error(
-          "reconstructVersion failed (public single)",
-          nodeId,
-          approved,
-          err
-        );
-        response.content = "";
-      }
-      response.version = approved;
-      response.status = "published";
-      if (isMarkdownFormat(c)) {
-        return c.body(nodeAsMarkdown(response, nodeId), 200, {
-          "Content-Type": "text/markdown; charset=utf-8"
-        });
-      }
-      return c.json({ node: response });
-    }
-  }
-  response.status = node.pendingChange ? "external_edit_pending" : await getDisplayStatus(nestId, nodeId);
-  if (response.status === "pending_review") {
-    const pending = await getPendingReview(nestId, nodeId);
-    response.pendingReviewBy = pending?.requestedBy ?? null;
-  }
-  if (isMarkdownFormat(c)) {
-    return c.body(nodeAsMarkdown(response, nodeId), 200, {
-      "Content-Type": "text/markdown; charset=utf-8"
-    });
-  }
-  return c.json({ node: response });
-});
-nodeRoutes.patch("/:nodeId{.+}", async (c) => {
-  const nestId = c.req.param("nestId");
-  const nodeId = c.req.param("nodeId");
-  const body = await c.req.json();
-  const baseVersionHeader = c.req.header("X-Base-Version");
-  if (baseVersionHeader) {
-    const baseVersion = parseInt(baseVersionHeader, 10);
-    const conflict = await checkConflict(nestId, nodeId, baseVersion);
-    if (conflict.conflict) {
-      return c.json(
-        {
-          error: "Version conflict",
-          your_version: baseVersion,
-          current_version: conflict.currentVersion,
-          updated_by: conflict.updatedBy,
-          updated_at: conflict.updatedAt,
-          rejected_content: body.content || body.append || null
-        },
-        409
-      );
-    }
-  }
-  const authorEmail = await getUserEmail(c);
-  const { node, version: responseVersion } = await updateNode(
-    nestId,
-    nodeId,
-    {
-      content: body.content,
-      append: body.append,
-      tags: body.tags,
-      title: body.title,
-      status: body.status,
-      changeNote: body.changeNote
-    },
-    authorEmail
-  );
-  return c.json({ node: toNodeResponse(node), version: responseVersion });
-});
-nodeRoutes.delete("/:nodeId{.+}", async (c) => {
-  const nestId = c.req.param("nestId");
-  const nodeId = c.req.param("nodeId");
-  const { storage } = await engineCache.get(nestId);
-  if (await isStewardshipEnabled(nestId) && await getPendingReview(nestId, nodeId)) {
-    throw new LockedError(
-      "This document is awaiting steward review and is locked. Approve or reject the pending review before deleting."
-    );
-  }
-  try {
-    await storage.deleteDocument(nodeId);
-  } catch {
-    throw new NotFoundError(`Node not found: ${nodeId}`);
-  }
-  await removeNodeFromTagIndex(nestId, nodeId);
-  const db = getDb();
-  await db.transaction(async (tx) => {
-    await tx.run(
-      "DELETE FROM node_versions WHERE nest_id = ? AND node_id = ?",
-      [nestId, nodeId]
-    );
-    await tx.run(
-      "DELETE FROM review_requests WHERE nest_id = ? AND node_id = ?",
-      [nestId, nodeId]
-    );
-    await tx.run(
-      "DELETE FROM approved_versions WHERE nest_id = ? AND node_id = ?",
-      [nestId, nodeId]
-    );
-    await tx.run(
-      `DELETE FROM stewards
-       WHERE nest_id = ? AND scope = 'document' AND node_pattern = ?`,
-      [nestId, nodeId]
-    );
-  });
-  await trackEvent("node.delete", { nestId, nodeId });
-  return c.json({ deleted: true });
-});
-async function getUserEmail(c) {
-  const userId = c.get("userId");
-  const db = getDb();
-  const user = await db.get("SELECT email FROM users WHERE id = ?", [userId]);
-  return user?.email || "anonymous@localhost";
-}
-
-// src/annotations/routes.ts
-import { Hono as Hono5 } from "hono";
-
-// src/annotations/service.ts
-import { v4 as uuid3 } from "uuid";
-
-// src/annotations/projection.ts
-var MAX_CONTEXT_CHARS = 250;
-var MAX_QUOTE_CHARS = 1e3;
-function clampAnchor(raw) {
-  if (!raw) return null;
-  const quote = (raw.quote ?? "").trim().slice(0, MAX_QUOTE_CHARS);
-  if (!quote) return null;
-  const before = (raw.before ?? "").slice(-MAX_CONTEXT_CHARS);
-  const after = (raw.after ?? "").slice(0, MAX_CONTEXT_CHARS);
-  const line = typeof raw.line === "number" && Number.isFinite(raw.line) && raw.line > 0 ? Math.floor(raw.line) : void 0;
-  return { quote, before, after, ...line !== void 0 ? { line } : {} };
-}
-function oneLine(s) {
-  return s.replace(/\s+/g, " ").replace(/--+>/g, "-\u2192").trim();
-}
-function renderAnchor(anchor) {
-  if (!anchor) {
-    return "<!-- anchor: whole-artifact -->";
-  }
-  const linePart = anchor.line !== void 0 ? `line ${anchor.line} \xB7 ` : "";
-  const context = `\u2026${oneLine(anchor.before)}\u3008${oneLine(anchor.quote)}\u3009${oneLine(
-    anchor.after
-  )}\u2026`;
-  return `<!-- anchor: ${linePart}quote "${oneLine(anchor.quote)}" \xB7 context ${context} -->`;
-}
-function statusHeading(thread) {
-  if (thread.status === "resolved") {
-    const who = thread.resolvedBy ? `${thread.resolvedBy}, ` : "";
-    const when = thread.resolvedAt ? `${thread.resolvedAt}` : "";
-    const meta = who || when ? ` (${who}${when})` : "";
-    return `\u2705 RESOLVED${meta}`;
-  }
-  return "\u{1F7E0} OPEN";
-}
-function snapshotLabel(v) {
-  return v == null ? "Unpinned" : `Snapshot v${v}`;
-}
-function orderThreads(threads) {
-  return [...threads].sort((a, b) => {
-    if (a.status !== b.status) return a.status === "open" ? -1 : 1;
-    return a.createdAt.localeCompare(b.createdAt);
-  });
-}
-function projectThreadsToMarkdown(artifactTitle, threads) {
-  const lines = [];
-  lines.push(`# ${artifactTitle} \u2014 Annotations`);
-  lines.push("");
-  lines.push(
-    "> Auto-generated from review comments, grouped by the artifact snapshot each was anchored to. **Open** threads are unresolved feedback for the next iteration; **resolved** threads were already addressed (don't re-break them)."
-  );
-  lines.push("");
-  if (threads.length === 0) {
-    lines.push("_No annotations yet._");
-    lines.push("");
-    return lines.join("\n");
-  }
-  const buckets2 = /* @__PURE__ */ new Map();
-  for (const t of threads) {
-    const key = t.snapshotVersion ?? null;
-    (buckets2.get(key) ?? buckets2.set(key, []).get(key)).push(t);
-  }
-  const keys = [...buckets2.keys()].sort((a, b) => {
-    if (a == null) return 1;
-    if (b == null) return -1;
-    return b - a;
-  });
-  for (const key of keys) {
-    lines.push(`## ${snapshotLabel(key)}`);
-    lines.push("");
-    for (const thread of orderThreads(buckets2.get(key))) {
-      lines.push(`### Thread \xB7 ${statusHeading(thread)}`);
-      lines.push(renderAnchor(thread.anchor));
-      for (const comment of thread.comments) {
-        lines.push(
-          `- **${comment.author}** \xB7 ${comment.createdAt} \u2014 ${comment.body}`
-        );
-      }
-      lines.push("");
-    }
-  }
-  return lines.join("\n");
-}
-
-// src/annotations/service.ts
-async function loadComments(threadId) {
-  const db = getDb();
-  const rows = await db.all(
-    "SELECT id, author, body, created_at FROM annotation_comments WHERE thread_id = ? ORDER BY created_at ASC, rowid ASC",
-    [threadId]
-  );
-  return rows.map((r) => ({
-    id: r.id,
-    author: r.author,
-    body: r.body,
-    createdAt: r.created_at
-  }));
-}
-async function rowToThread(row) {
-  let anchor = null;
-  if (row.anchor_json) {
-    try {
-      anchor = JSON.parse(row.anchor_json);
-    } catch {
-      anchor = null;
+  return rows.map((r) => ({
+    id: r.id,
+    author: r.author,
+    body: r.body,
+    createdAt: r.created_at
+  }));
+}
+async function rowToThread(row) {
+  let anchor = null;
+  if (row.anchor_json) {
+    try {
+      anchor = JSON.parse(row.anchor_json);
+    } catch {
+      anchor = null;
     }
   }
   return {
@@ -2649,9 +2399,21 @@ async function rowToThread(row) {
 async function getThreadRow(threadId) {
   return await getDb().get("SELECT * FROM annotation_threads WHERE id = ?", [threadId]);
 }
+async function countThreadsByNode(nestId) {
+  const rows = await getDb().all(
+    `SELECT node_id, CAST(COUNT(*) AS INTEGER) AS count, MAX(created_at) AS last_at
+         FROM annotation_threads
+        WHERE nest_id = ?
+        GROUP BY node_id`,
+    [nestId]
+  );
+  const out = {};
+  for (const r of rows) out[r.node_id] = { count: r.count, lastAt: r.last_at };
+  return out;
+}
 async function listThreads(nestId, nodeId) {
   const rows = await getDb().all(
-    "SELECT * FROM annotation_threads WHERE nest_id = ? AND node_id = ? ORDER BY created_at ASC, rowid ASC",
+    "SELECT * FROM annotation_threads WHERE nest_id = ? AND node_id = ? ORDER BY created_at ASC, id ASC",
     [nestId, nodeId]
   );
   return Promise.all(rows.map(rowToThread));
@@ -2758,44 +2520,380 @@ function derivedAnnotationsId(sourceNodeId) {
 }
 async function syncAnnotationsNode(nestId, nodeId, userEmail) {
   try {
-    let title = nodeId;
+    let title = nodeId;
+    let type = null;
+    try {
+      const { storage } = await engineCache.get(nestId);
+      const node = await storage.readDocument(nodeId);
+      title = node.frontmatter?.title || nodeId;
+      type = node.frontmatter?.type || "document";
+    } catch {
+    }
+    if (type !== null && type !== "artifact") return;
+    const threads = await listThreads(nestId, nodeId);
+    const derivedTitle = `${title} \u2014 Annotations`;
+    const markdown = projectThreadsToMarkdown(title, threads);
+    const derivedId = derivedAnnotationsId(nodeId);
+    try {
+      await updateNode(nestId, derivedId, { content: markdown }, userEmail);
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        await createNode(
+          nestId,
+          {
+            id: derivedId,
+            title: derivedTitle,
+            content: markdown,
+            type: "document",
+            tags: ["annotations"]
+          },
+          userEmail
+        );
+      } else {
+        throw err;
+      }
+    }
+  } catch (err) {
+    console.warn(
+      `[annotations] failed to sync derived node for ${nestId}/${nodeId}:`,
+      err
+    );
+  }
+}
+
+// src/nodes/routes.ts
+var nodeRoutes = new Hono4();
+function nodeAsMarkdown(response, nodeId) {
+  return nodeToMarkdown({
+    id: nodeId,
+    title: response.title,
+    tags: response.tags,
+    status: response.status,
+    body: response.content
+  });
+}
+nodeRoutes.get("/", async (c) => {
+  const nestId = c.req.param("nestId");
+  const userId = c.get("userId");
+  const nodes = await listNodesForCaller(nestId, userId);
+  return c.json({ count: nodes.length, nodes });
+});
+nodeRoutes.post("/", async (c) => {
+  const body = await c.req.json();
+  if (!body.title || !body.content) {
+    throw new ValidationError("title and content are required");
+  }
+  if (body.folder !== void 0 && typeof body.folder !== "string") {
+    throw new ValidationError('folder must be a string path like "gtm/deals"');
+  }
+  const nestId = c.req.param("nestId");
+  const authorEmail = await getUserEmail(c);
+  const { node } = await createNode(
+    nestId,
+    {
+      title: body.title,
+      content: body.content,
+      type: body.type,
+      tags: body.tags,
+      scope: body.scope,
+      status: body.status,
+      folder: body.folder
+    },
+    authorEmail
+  );
+  const resolved = await resolveStewardsForNode(nestId, node.id);
+  return c.json({
+    node: toNodeResponse(node),
+    stewards: resolved.length > 0 ? resolved.map((r) => ({
+      email: r.steward.userEmail,
+      role: r.steward.role,
+      source: r.source
+    })) : void 0
+  }, 201);
+});
+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 { stewards, fallbackToOwner, ownerEmail } = await resolveStewardsWithFallback2(
+    nestId,
+    nodeId
+  );
+  return c.json({
+    nodeId,
+    stewards: stewards.map((r) => ({
+      email: r.steward.userEmail,
+      role: r.steward.role,
+      scope: r.steward.scope,
+      source: r.source,
+      priority: r.priority
+    })),
+    fallbackToOwner,
+    ownerEmail
+  });
+});
+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 allVersions = await getVersions2(nestId, nodeId);
+  const approved = await getApprovedVersion2(nestId, nodeId);
+  const db = getDb();
+  const resolutions = await db.all(
+    `SELECT version, status, resolved_by, resolved_at
+         FROM review_requests
+        WHERE nest_id = ? AND node_id = ?
+          AND status IN ('approved', 'rejected')
+          AND resolved_by IS NOT NULL
+        ORDER BY resolved_at DESC`,
+    [nestId, nodeId]
+  );
+  const byVersion = /* @__PURE__ */ new Map();
+  for (const r of resolutions) {
+    if (!byVersion.has(r.version)) {
+      byVersion.set(r.version, { status: r.status, resolvedBy: r.resolved_by });
+    }
+  }
+  const enriched = allVersions.map((v) => {
+    const r = byVersion.get(v.version);
+    return r ? { ...v, resolvedBy: r.resolvedBy, resolutionStatus: r.status } : v;
+  });
+  return c.json({
+    versions: enriched,
+    approvedVersion: approved,
+    currentVersion: allVersions[0]?.version || 0
+  });
+});
+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 history = await getReviewHistory2(nestId, nodeId);
+  return c.json({ reviews: history });
+});
+nodeRoutes.post("/:nodeId{.+}/revert", async (c) => {
+  const nestId = c.req.param("nestId");
+  const nodeId = c.req.param("nodeId");
+  const { versions: versionManager } = await engineCache.get(nestId);
+  const userId = c.get("userId");
+  const userEmail = await resolveCallerEmail(userId);
+  if (!await canReadNode(nestId, nodeId, userId, userEmail)) {
+    return c.json(
+      { error: "Access denied \u2014 no steward assignment for this node" },
+      403
+    );
+  }
+  const body = await c.req.json().catch(() => ({}));
+  const targetVersion = Number(body.targetVersion);
+  if (!Number.isInteger(targetVersion) || targetVersion < 1) {
+    throw new ValidationError("targetVersion (a positive integer) is required");
+  }
+  let raw;
+  try {
+    raw = await versionManager.reconstructVersion(nodeId, targetVersion);
+  } catch {
+    throw new NotFoundError(
+      `Version ${targetVersion} not found for ${nodeId}`
+    );
+  }
+  const content = bodyOnly(nodeId, raw);
+  const { node, version } = await updateNode(
+    nestId,
+    nodeId,
+    { content, changeNote: `Restored from version ${targetVersion}` },
+    userEmail
+  );
+  await trackEvent("node.revert", { nestId, nodeId, targetVersion });
+  return c.json({ ok: true, version, node: toNodeResponse(node) });
+});
+nodeRoutes.get("/:nodeId{.+}", async (c) => {
+  const nestId = c.req.param("nestId");
+  const nodeId = c.req.param("nodeId");
+  const { storage, versions: versionManager } = await engineCache.get(nestId);
+  const userId = c.get("userId");
+  const userEmail = await resolveCallerEmail(userId);
+  if (!await canReadNode(nestId, nodeId, userId, userEmail)) {
+    return c.json(
+      { error: "Access denied \u2014 no steward assignment for this node" },
+      403
+    );
+  }
+  let node;
+  try {
+    node = await storage.readDocument(nodeId, { verifyChecksum: true });
+  } catch {
+    throw new NotFoundError(`Node not found: ${nodeId}`);
+  }
+  if (node.pendingChange) {
     try {
-      const { storage } = await engineCache.get(nestId);
-      const node = await storage.readDocument(nodeId);
-      title = node.frontmatter?.title || nodeId;
-    } catch {
+      await scanDocumentForDrift(nestId, nodeId, userEmail || "system:read");
+      const refreshed = await getPendingChange(nestId, nodeId);
+      if (refreshed) node.pendingChange = refreshed;
+    } catch (err) {
+      console.error("[external-edit] stage-on-read failed:", err);
     }
-    const threads = await listThreads(nestId, nodeId);
-    const derivedTitle = `${title} \u2014 Annotations`;
-    const markdown = projectThreadsToMarkdown(title, threads);
-    const derivedId = derivedAnnotationsId(nodeId);
     try {
-      await updateNode(nestId, derivedId, { content: markdown }, userEmail);
+      const latest = await loadLatestApprovedNode(nestId, nodeId);
+      if (latest) {
+        node = { ...latest, pendingChange: node.pendingChange };
+      }
     } catch (err) {
-      if (err instanceof NotFoundError) {
-        await createNode(
-          nestId,
-          {
-            id: derivedId,
-            title: derivedTitle,
-            content: markdown,
-            type: "document",
-            tags: ["annotations"]
-          },
-          userEmail
+      console.error("[external-edit] reconstruct-latest failed:", err);
+    }
+  }
+  const response = toNodeResponse(node);
+  if (await isPublicReader(nestId, userId)) {
+    const approved = await getApprovedVersion(nestId, nodeId);
+    if (approved != null) {
+      try {
+        const raw = await versionManager.reconstructVersion(
+          nodeId,
+          approved
         );
-      } else {
-        throw err;
+        response.content = bodyOnly(nodeId, raw);
+      } catch (err) {
+        console.error(
+          "reconstructVersion failed (public single)",
+          nodeId,
+          approved,
+          err
+        );
+        response.content = "";
+      }
+      response.version = approved;
+      response.status = "published";
+      if (isMarkdownFormat(c)) {
+        return c.body(nodeAsMarkdown(response, nodeId), 200, {
+          "Content-Type": "text/markdown; charset=utf-8"
+        });
       }
+      return c.json({ node: response });
     }
-  } catch (err) {
-    console.warn(
-      `[annotations] failed to sync derived node for ${nestId}/${nodeId}:`,
-      err
+  }
+  response.status = node.pendingChange ? "external_edit_pending" : await getDisplayStatus(nestId, nodeId);
+  if (response.status === "pending_review") {
+    const pending = await getPendingReview(nestId, nodeId);
+    response.pendingReviewBy = pending?.requestedBy ?? null;
+  }
+  if (isMarkdownFormat(c)) {
+    return c.body(nodeAsMarkdown(response, nodeId), 200, {
+      "Content-Type": "text/markdown; charset=utf-8"
+    });
+  }
+  return c.json({ node: response });
+});
+nodeRoutes.patch("/:nodeId{.+}", async (c) => {
+  const nestId = c.req.param("nestId");
+  const nodeId = c.req.param("nodeId");
+  const body = await c.req.json();
+  const baseVersionHeader = c.req.header("X-Base-Version");
+  if (baseVersionHeader) {
+    const baseVersion = parseInt(baseVersionHeader, 10);
+    const conflict = await checkConflict(nestId, nodeId, baseVersion);
+    if (conflict.conflict) {
+      return c.json(
+        {
+          error: "Version conflict",
+          your_version: baseVersion,
+          current_version: conflict.currentVersion,
+          updated_by: conflict.updatedBy,
+          updated_at: conflict.updatedAt,
+          rejected_content: body.content || body.append || null
+        },
+        409
+      );
+    }
+  }
+  const authorEmail = await getUserEmail(c);
+  const { node, version: responseVersion } = await updateNode(
+    nestId,
+    nodeId,
+    {
+      content: body.content,
+      append: body.append,
+      tags: body.tags,
+      title: body.title,
+      status: body.status,
+      changeNote: body.changeNote
+    },
+    authorEmail
+  );
+  return c.json({ node: toNodeResponse(node), version: responseVersion });
+});
+nodeRoutes.delete("/:nodeId{.+}", async (c) => {
+  const nestId = c.req.param("nestId");
+  const nodeId = c.req.param("nodeId");
+  const { storage } = await engineCache.get(nestId);
+  if (await isStewardshipEnabled(nestId) && await getPendingReview(nestId, nodeId)) {
+    throw new LockedError(
+      "This document is awaiting steward review and is locked. Approve or reject the pending review before deleting."
     );
   }
+  try {
+    await storage.deleteDocument(nodeId);
+  } catch {
+    throw new NotFoundError(`Node not found: ${nodeId}`);
+  }
+  await removeNodeFromTagIndex(nestId, nodeId);
+  const derivedId = derivedAnnotationsId(nodeId);
+  try {
+    await storage.deleteDocument(derivedId);
+    await removeNodeFromTagIndex(nestId, derivedId);
+  } catch {
+  }
+  const db = getDb();
+  await db.transaction(async (tx) => {
+    await tx.run(
+      "DELETE FROM node_versions WHERE nest_id = ? AND node_id = ?",
+      [nestId, nodeId]
+    );
+    await tx.run(
+      "DELETE FROM review_requests WHERE nest_id = ? AND node_id = ?",
+      [nestId, nodeId]
+    );
+    await tx.run(
+      "DELETE FROM approved_versions WHERE nest_id = ? AND node_id = ?",
+      [nestId, nodeId]
+    );
+    await tx.run(
+      `DELETE FROM stewards
+       WHERE nest_id = ? AND scope = 'document' AND node_pattern = ?`,
+      [nestId, nodeId]
+    );
+    await tx.run(
+      "DELETE FROM annotation_threads WHERE nest_id = ? AND node_id = ?",
+      [nestId, nodeId]
+    );
+    await tx.run(
+      "DELETE FROM node_versions WHERE nest_id = ? AND node_id = ?",
+      [nestId, derivedId]
+    );
+    await tx.run(
+      "DELETE FROM review_requests WHERE nest_id = ? AND node_id = ?",
+      [nestId, derivedId]
+    );
+    await tx.run(
+      "DELETE FROM approved_versions WHERE nest_id = ? AND node_id = ?",
+      [nestId, derivedId]
+    );
+    await tx.run(
+      "DELETE FROM annotation_threads WHERE nest_id = ? AND node_id = ?",
+      [nestId, derivedId]
+    );
+  });
+  await trackEvent("node.delete", { nestId, nodeId });
+  return c.json({ deleted: true });
+});
+async function getUserEmail(c) {
+  const userId = c.get("userId");
+  const db = getDb();
+  const user = await db.get("SELECT email FROM users WHERE id = ?", [userId]);
+  return user?.email || "anonymous@localhost";
 }
 
+// src/annotations/routes.ts
+import { Hono as Hono5 } from "hono";
+
 // src/annotations/types.ts
 var ARTIFACT_NODE_TYPE = "artifact";
 
@@ -3322,11 +3420,30 @@ queryRoutes.post("/context", async (c) => {
   const maxTokens = Math.max(50, body.max_tokens ?? 4e3);
   const hops = body.hops ?? 2;
   const includeDrafts = body.include_drafts === true;
+  const isVisible = (d) => includeDrafts || d.frontmatter.status === "published";
   let selector = body.selector?.trim() || null;
   let compileDetail = null;
   let titleMatches = [];
+  let resolvedTitleSelector = false;
   const allDocs = await storage.discoverDocuments();
-  if (!selector && body.prompt) {
+  if (selector && selector.includes("[[")) {
+    const parts = selector.split("|").map((p) => p.trim()).filter(Boolean);
+    const wantedTitles = /* @__PURE__ */ new Set();
+    const rest = [];
+    for (const p of parts) {
+      const m = /^\[\[(.+)\]\]$/.exec(p);
+      if (m) wantedTitles.add(m[1].trim().toLowerCase());
+      else rest.push(p);
+    }
+    if (wantedTitles.size > 0) {
+      selector = rest.join("|") || null;
+      resolvedTitleSelector = true;
+      titleMatches = allDocs.filter(
+        (d) => wantedTitles.has(String(d.frontmatter.title || "").toLowerCase()) && isVisible(d)
+      );
+    }
+  }
+  if (!selector && !resolvedTitleSelector && body.prompt) {
     const titles = allDocs.map((d) => d.frontmatter.title);
     compileDetail = await compilePrompt(body.prompt, nestId, titles);
     selector = compileDetail.selector;
@@ -3352,6 +3469,44 @@ queryRoutes.post("/context", async (c) => {
     hopsUsed = result.hopsUsed;
     nodesTraversed = result.nodesTraversed;
   }
+  if (titleMatches.length > 0 && hops > 0) {
+    const byTitle = new Map(
+      allDocs.map((d) => [
+        String(d.frontmatter.title || "").toLowerCase(),
+        d
+      ])
+    );
+    const byId = new Map(allDocs.map((d) => [d.id, d]));
+    const adj = /* @__PURE__ */ new Map();
+    const link = (a, b) => {
+      (adj.get(a) ?? adj.set(a, /* @__PURE__ */ new Set()).get(a)).add(b);
+      (adj.get(b) ?? adj.set(b, /* @__PURE__ */ new Set()).get(b)).add(a);
+    };
+    for (const d of allDocs) {
+      for (const target of extractWikiTargets(d.body || "")) {
+        const t = byId.get(target) ?? byTitle.get(target.toLowerCase());
+        if (t && t.id !== d.id) link(d.id, t.id);
+      }
+    }
+    const seen = new Set(titleMatches.map((d) => d.id));
+    let frontier = titleMatches.map((d) => d.id);
+    for (let depth = 0; depth < hops && frontier.length; depth++) {
+      const next = [];
+      for (const id of frontier) {
+        for (const nb of adj.get(id) ?? []) {
+          if (seen.has(nb)) continue;
+          seen.add(nb);
+          const doc = byId.get(nb);
+          if (!doc || !isVisible(doc)) continue;
+          next.push(nb);
+          titleMatches.push(doc);
+        }
+      }
+      frontier = next;
+      hopsUsed = Math.max(hopsUsed, depth + 1);
+    }
+    nodesTraversed += seen.size;
+  }
   if (titleMatches.length > 0) {
     const seen = new Set(documents.map((d) => d.id));
     for (const t of titleMatches) {
@@ -3500,6 +3655,10 @@ queryRoutes.get("/overview", async (c) => {
     }))
   });
 });
+queryRoutes.get("/comment-counts", async (c) => {
+  const counts = await countThreadsByNode(c.req.param("nestId"));
+  return c.json({ counts });
+});
 queryRoutes.get("/context", async (c) => {
   const { storage } = await engineCache.get(c.req.param("nestId"));
   const content = await storage.readContextMd();
@@ -3621,6 +3780,13 @@ 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",
@@ -3649,7 +3815,11 @@ var TOOL_DEFINITIONS = [
     inputSchema: {
       type: "object",
       properties: {
-        query: { type: "string", description: "Selector query" }
+        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"]
     }
@@ -3690,11 +3860,39 @@ var TOOL_DEFINITIONS = [
         max_tokens: {
           type: "number",
           description: "Approximate token budget (default: 8000)"
+        },
+        hops: {
+          type: "number",
+          description: "Graph traversal depth from the matched nodes (default: 2)"
         }
       },
       required: ["selector"]
     }
   },
+  {
+    name: "context_export",
+    description: "Export the ENTIRE nest as one markdown bundle \u2014 every accessible document's FULL content. Use when you need the whole nest as context rather than a targeted query. Respects an optional token budget.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        max_tokens: {
+          type: "number",
+          description: "Approximate token budget; documents are included until it's reached (omit for no cap)."
+        }
+      }
+    }
+  },
+  {
+    name: "context_comments",
+    description: "Get the review comments/annotations on a document \u2014 anchored quotes, threaded replies, and open/resolved status \u2014 by title or ID. Use to pull human feedback into context.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Title of the node" },
+        id: { type: "string", description: "ID of the node" }
+      }
+    }
+  },
   {
     name: "context_create",
     description: "Create a new knowledge node in the vault.",
@@ -3715,7 +3913,11 @@ var TOOL_DEFINITIONS = [
           items: { type: "string" },
           description: "Tags"
         },
-        scope: { type: "string", description: "Visibility scope" }
+        scope: { type: "string", description: "Visibility scope" },
+        folder: {
+          type: "string",
+          description: 'Folder path under nodes/ (e.g. "gtm/deals"); segments are slugified'
+        }
       },
       required: ["title", "content"]
     }
@@ -3946,8 +4148,16 @@ ${nodeList}`;
 ${results}`;
     }
     case "context_query": {
-      const result = await queryEngine.query(args.query, { hops: 2 });
-      const nodes = result.documents;
+      const result = await queryEngine.query(args.query, {
+        hops: normalizeHops(args.hops)
+      });
+      const visibility = await Promise.all(
+        result.documents.map(async (n) => ({
+          node: n,
+          visible: await resolveLlmBody(ctx, n) !== null
+        }))
+      );
+      const nodes = visibility.filter((e) => e.visible).map((e) => e.node);
       if (!nodes.length) return `No nodes matched: ${args.query}`;
       const list = nodes.map(
         (n, i) => `${i + 1}. **${n.frontmatter.title}** [${n.frontmatter.type || "document"}] ${(n.frontmatter.tags || []).join(" ")}`
@@ -3995,21 +4205,99 @@ ${body || "(no content)"}`;
 ${list}`;
     }
     case "context_resolve": {
-      const result = await queryEngine.query(args.selector, { hops: 2 });
+      const result = await queryEngine.query(args.selector, {
+        hops: normalizeHops(args.hops)
+      });
       const maxTokens = args.max_tokens || 8e3;
       const approxChars = maxTokens * 4;
+      const resolvedBodies = await Promise.all(
+        result.documents.map(async (n) => ({
+          node: n,
+          body: await resolveLlmBody(ctx, n)
+        }))
+      );
       let total = 0;
       const resolved = [];
-      for (const n of result.documents) {
+      for (const { node: n, body } of resolvedBodies) {
+        if (body === null) continue;
         const entry = `## ${n.frontmatter.title}
 
-${n.body || ""}`;
+${body}`;
         if (total + entry.length > approxChars) break;
         resolved.push(entry);
         total += entry.length;
       }
       return resolved.join("\n\n---\n\n") || "No nodes resolved.";
     }
+    case "context_export": {
+      const docs = await storage.discoverDocuments();
+      const approxChars = args.max_tokens ? args.max_tokens * 4 : Infinity;
+      const resolved = await Promise.all(
+        docs.map(async (n) => ({ node: n, body: await resolveLlmBody(ctx, n) }))
+      );
+      let total = 0;
+      let budgetHit = false;
+      const parts = [];
+      for (const { node: n, body } of resolved) {
+        if (body === null) continue;
+        const meta = [
+          `**Title:** ${n.frontmatter.title}`,
+          `**Type:** ${n.frontmatter.type || "document"}`,
+          n.frontmatter.tags?.length ? `**Tags:** ${n.frontmatter.tags.join(" ")}` : null
+        ].filter(Boolean).join("\n");
+        const entry = `${meta}
+
+${body || "(no content)"}`;
+        if (total + entry.length > approxChars) {
+          budgetHit = true;
+          break;
+        }
+        parts.push(entry);
+        total += entry.length;
+      }
+      if (!parts.length) {
+        return budgetHit ? "Token budget reached before any document fit \u2014 raise max_tokens, or use context_query/context_resolve to target." : "No documents available to export.";
+      }
+      const note = budgetHit ? `
+
+_(Token budget reached \u2014 ${parts.length} of ${docs.length} documents included. Raise max_tokens, or use context_query/context_resolve to target.)_` : "";
+      return `# Nest export \u2014 ${parts.length} document(s)
+
+${parts.join(
+        "\n\n---\n\n"
+      )}${note}`;
+    }
+    case "context_comments": {
+      const docs = await storage.discoverDocuments();
+      let node;
+      if (args.title) {
+        node = docs.find(
+          (n) => n.frontmatter.title.toLowerCase() === args.title.toLowerCase()
+        );
+      } else if (args.id) {
+        node = docs.find((n) => n.id === args.id);
+      }
+      if (!node) return `Node not found: ${args.title || args.id}`;
+      if (await resolveLlmBody(ctx, node) === null) {
+        return `Node "${node.frontmatter.title}" has no approved version yet \u2014 not available to AI.`;
+      }
+      const threads = await listThreads(nestId, node.id);
+      if (!threads.length)
+        return `No comments on "${node.frontmatter.title}".`;
+      const openCount = threads.filter((t) => t.status === "open").length;
+      const sections = threads.map((t, i) => {
+        const quote = t.anchor?.quote ? `> ${t.anchor.quote.replace(/\n/g, " ")}
+
+` : "";
+        const head = `### ${i + 1}. [${t.status}]${t.anchor?.quote ? "" : " (whole-document)"}`;
+        const comments = t.comments.map((c) => `- **${c.author}** (${c.createdAt}): ${c.body}`).join("\n");
+        return `${head}
+${quote}${comments}`;
+      }).join("\n\n");
+      return `# Comments on "${node.frontmatter.title}" \u2014 ${threads.length} thread(s), ${openCount} open
+
+${sections}`;
+    }
     case "context_create": {
       if (!await canCreateInNest(nestId, userEmail)) {
         return "You don't have permission to create documents in this nest.";
@@ -4021,7 +4309,8 @@ ${n.body || ""}`;
           content: args.content,
           type: args.type,
           tags: args.tags,
-          scope: args.scope
+          scope: args.scope,
+          folder: args.folder
         },
         userEmail
       );
@@ -4068,8 +4357,8 @@ ${n.body || ""}`;
 
 ${list}`;
       }
-      if (!canManageStewards(ctx.userEmail)) {
-        return "You don't have permission to list stewards. Only the super admin can do this.";
+      if (!await canManageStewards(ctx.nestId, ctx.userId)) {
+        return "You don't have permission to list stewards. Only a nest admin, the nest owner, or the server admin can do this.";
       }
       const allStewards = await getStewardsForNest(ctx.nestId);
       if (allStewards.length === 0) {
@@ -4207,8 +4496,8 @@ ${list}`;
       if (!["nest", "tag", "document"].includes(scope)) {
         return `Invalid scope "${args.scope}". Use: nest, tag, or document.`;
       }
-      if (!canManageStewards(ctx.userEmail)) {
-        return "You don't have permission to manage stewards. Only the super admin can do this.";
+      if (!await canManageStewards(ctx.nestId, ctx.userId)) {
+        return "You don't have permission to manage stewards. Only a nest admin, the nest owner, or the server admin can do this.";
       }
       try {
         await createStewardRecord({
@@ -4226,9 +4515,9 @@ ${list}`;
       }
     }
     case "context_share_nest": {
-      const roles = await resolveUserRoles(ctx.nestId, ctx.userEmail);
-      if (!canManageWith(roles)) {
-        return "You don't have permission to share this nest via this tool (admin only). You can still invite from the UI with write access, or ask a nest admin.";
+      const callerPermission = config.AUTH_MODE === "open" ? "owner" : await resolveNestPermission(ctx.nestId, ctx.userId);
+      if (permissionLevel(callerPermission) < permissionLevel("write")) {
+        return "You don't have permission to share this nest. Sharing needs write access \u2014 ask a nest admin or the owner.";
       }
       const permission = args.permission || "read";
       try {
@@ -4236,7 +4525,8 @@ ${list}`;
           nestId: ctx.nestId,
           email: args.email,
           permission,
-          grantedByEmail: ctx.userEmail
+          grantedByEmail: ctx.userEmail,
+          callerPermission
         });
         const label = permission === "admin" ? "admin" : permission === "write" ? "editor" : "viewer";
         return `Shared this nest with **${args.email}** as ${label}.`;
@@ -5130,6 +5420,7 @@ var openModeMiddleware = createMiddleware2(async (c, next) => {
 function isPublicReadEligiblePath(method, path) {
   if (method !== "GET") return false;
   if (!/^\/nests\/[^/]+(\/.*)?$/.test(path)) return false;
+  if (/^\/nests\/[^/]+\/stewards/.test(path)) return false;
   return !/\/(collaborators|visibility|settings|mcp)/.test(path);
 }
 var flexAuthMiddleware = createMiddleware2(async (c, next) => {
@@ -5416,10 +5707,10 @@ function createApp() {
     const isAnnotationAction = /\/annotations$/.test(path) || /\/annotations\/[^/]+\/(comments|resolve|reopen)$/.test(path);
     const isCommentAction = /\/comments$/.test(path) || /\/comments\/[^/]+\/resolve$/.test(path);
     const isStewardRoster = path.includes("/stewards") && !path.includes("/nodes/");
-    if (isStewardRoster && !canManageStewards(await resolveCallerEmail(userId))) {
+    if (isStewardRoster && permission !== "owner" && permission !== "admin") {
       return c.json(
         {
-          error: "You don't have permission to manage stewards. Only the super admin can do this."
+          error: "You don't have permission to manage stewards. Only a nest admin, the nest owner, or the server admin can do this."
         },
         403
       );