@promptowl/contextnest-community 1.24.0 → 1.25.0

package/dist/index.js

@@ -38,7 +38,7 @@ import {
   submitForReview,
   withNodeWriteLock,
   withdrawDeletionRequest
-} from "./chunk-5EZOPA47.js";
+} from "./chunk-DTLMBF4W.js";
 import {
   canCreateInNest,
   canManageStewards,
@@ -56,9 +56,10 @@ import {
   resolveStewardsForNode,
   resolveStewardsWithFallback,
   resolveUserRoles,
+  stewardDocumentCreator,
   syncFromConfig,
   updateSteward
-} from "./chunk-2TPQTN4Y.js";
+} from "./chunk-2KHM5C7V.js";
 import {
   createGrant,
   deleteGrant,
@@ -67,7 +68,7 @@ import {
   listGrants,
   listUserGrants,
   resolveNodeGrant
-} from "./chunk-I3CSD6CK.js";
+} from "./chunk-KPGNZLZL.js";
 import {
   generateApiKey,
   getKeyPrefix,
@@ -78,10 +79,14 @@ import {
   verifyPassword
 } from "./chunk-F66VCBLA.js";
 import {
+  attributeRequest,
   checkConflict,
+  clientToolField,
+  connectionClient,
   createVersion,
   deleteSupersededDrafts,
   deleteUnsealedVersions,
+  deserializeClient,
   getApprovedVersion,
   getApprovedVersions,
   getCurrentVersion,
@@ -91,9 +96,12 @@ import {
   getTrackedNodeIds,
   getVersions,
   listMyDrafts,
+  mergeClient,
+  parseClientMetadata,
+  serializeClient,
   setApprovedVersion,
   upsertVersion
-} from "./chunk-ZTT4U4NE.js";
+} from "./chunk-TI7HMP64.js";
 import {
   approveExternalEdit,
   getExternalEditDetail,
@@ -105,7 +113,7 @@ import {
   scanDocumentForDrift,
   scanNestForDrift,
   startDriftScanner
-} from "./chunk-XUIWAWDO.js";
+} from "./chunk-32SZCH36.js";
 import {
   addMember,
   addWatcher,
@@ -162,6 +170,7 @@ import {
   loadServerSettings,
   markNotificationsRead,
   nestAllowsSelfApprove,
+  nestCreatorIsReviewer,
   nestName,
   nestPrimeTags,
   nestReviewsPrimeOnly,
@@ -195,6 +204,7 @@ import {
   restoreNest,
   sendEmailToRecipient,
   setAllowSelfApprove,
+  setCreatorIsReviewer,
   setPrimeOnlyReview,
   setPrimeTags,
   setReaderMode,
@@ -211,25 +221,26 @@ import {
   updateMemberRole,
   validateLicense,
   verifySmtp
-} from "./chunk-KIAAEHWL.js";
+} from "./chunk-7FROMOZM.js";
 import {
   AppError,
   ConflictError,
   ForbiddenError,
   LockedError,
   NotFoundError,
+  PayloadTooLargeError,
   UnauthorizedError,
   ValidationError,
   VaultBusyError,
   isVaultLockTimeout
-} from "./chunk-YVMSM7LS.js";
+} from "./chunk-LHWOJPFE.js";
 import {
   config,
   getDb,
   initDb,
   isEmailListish,
   isEmailish
-} from "./chunk-LA3VTQ22.js";
+} from "./chunk-JDAOA5KP.js";
 import {
   ANON_EMAIL,
   ANON_USER_ID,
@@ -243,7 +254,7 @@ import {
 import { serve } from "@hono/node-server";
 
 // src/app.ts
-import { Hono as Hono25 } from "hono";
+import { Hono as Hono26 } from "hono";
 import { LinearRouter } from "hono/router/linear-router";
 import { createMiddleware as createMiddleware2 } from "hono/factory";
 import { cors } from "hono/cors";
@@ -430,7 +441,7 @@ var authMiddleware = createMiddleware(async (c, next) => {
   if (key) {
     const keyHash = hashApiKey(key);
     const record = await db.get(
-      "SELECT user_id, nest_id FROM api_keys WHERE key_hash = ?",
+      "SELECT user_id, nest_id, label FROM api_keys WHERE key_hash = ?",
       [keyHash]
     );
     if (record) {
@@ -440,10 +451,26 @@ var authMiddleware = createMiddleware(async (c, next) => {
       );
       c.set("userId", record.user_id);
       c.set("nestScope", record.nest_id);
+      if (record.label) c.set("apiKeyLabel", record.label);
       return next();
     }
   }
-  return c.json({ error: "Missing or invalid credentials" }, 401);
+  if (sessionId) {
+    return c.json(
+      { error: "Your session has expired \u2014 sign in again.", code: "session_expired" },
+      401
+    );
+  }
+  if (key) {
+    return c.json(
+      { error: "This API key is invalid or has been revoked \u2014 generate a new one.", code: "invalid_key" },
+      401
+    );
+  }
+  return c.json(
+    { error: "Authentication required \u2014 sign in or provide an API key.", code: "missing_credentials" },
+    401
+  );
 });
 
 // src/shared/rate-limit.ts
@@ -1986,7 +2013,9 @@ import {
   DocumentNotFoundError,
   NODE_TYPES,
   TAG_PATTERN,
-  generateIndexMd
+  generateIndexMd,
+  readPdfBinary,
+  pdfSidecarPath
 } from "@promptowl/contextnest-engine";
 import { rename, mkdir, rm, stat } from "fs/promises";
 import { dirname, join } from "path";
@@ -2566,8 +2595,20 @@ var ACCEPTED_NODE_TYPES = /* @__PURE__ */ new Set([
   ...NODE_TYPES,
   ...RUNNABLE_NODE_TYPES,
   "artifact",
-  "table"
+  "table",
+  "pdf"
 ]);
+var PDF_NODE_TYPE = "pdf";
+var PDF_UPLOAD_HINT = "upload the file to POST /nests/:nestId/nodes/pdf (the Upload PDF action)";
+function pdfEngineError(err) {
+  const code = err?.code;
+  const message = err?.message || "The PDF could not be imported.";
+  if (code === "VALIDATION_FAILED" || code === "INVALID_DOCUMENT_ID") {
+    return new ValidationError(message);
+  }
+  if (code === "DOCUMENT_ALREADY_EXISTS") return new ConflictError(message);
+  return err;
+}
 function assertAcceptedType(type) {
   if (type === "artifact" && !config.TYPE_ARTIFACT_ENABLED) {
     throw new ValidationError("Artifact nodes are disabled on this server");
@@ -2581,6 +2622,13 @@ function assertAcceptedType(type) {
     );
   }
 }
+function assertUpdatableType(storedType) {
+  const type = storedType || "document";
+  if (ACCEPTED_NODE_TYPES.has(type)) return;
+  throw new ValidationError(
+    `node has legacy type "${type}" which this server no longer accepts; include "type": "<accepted type>" in the same PATCH to migrate it (allowed: ${[...ACCEPTED_NODE_TYPES].sort().join(", ")})`
+  );
+}
 function toNodeResponse(node) {
   const fm = node.frontmatter;
   const title = fm.title === void 0 || fm.title === null ? "" : String(fm.title);
@@ -2605,7 +2653,8 @@ function toNodeResponse(node) {
     // 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,
-    prime: documentPrimeFlag(fm.metadata)
+    prime: documentPrimeFlag(fm.metadata),
+    ...fm.type === "pdf" && fm.pdf ? { pdf: fm.pdf } : {}
   };
 }
 async function resolveAuthorship(nestId, nodes) {
@@ -2998,9 +3047,11 @@ async function assertMayFlagPrime(nestId, userEmail) {
     );
   }
 }
-async function autoPublishReason(nestId, userEmail, doc) {
-  if (!await isStewardshipEnabled(nestId)) return "no stewards configured";
+async function autoPublishReason(nestId, userEmail, doc, opts = {}) {
+  const governed = opts.governed ?? await isStewardshipEnabled(nestId);
+  if (!governed) return "no stewards configured";
   if (await isPrimeDocument(nestId, doc.tags, doc.metadata)) return null;
+  if (opts.creatorReviews) return "creator is the document's reviewer";
   if (await nestReviewsPrimeOnly(nestId)) {
     return "prime-only review, document is not prime";
   }
@@ -3030,8 +3081,14 @@ async function createNodeOnce(nestId, input, userEmail, opts = {}) {
     id = `${prefix}${slug || await generatedSlug(storage, prefix)}`;
   }
   const tags = requireTags(input.tags);
-  const requestedType = input.type || "document";
+  const requestedType = input.pdf ? input.type || PDF_NODE_TYPE : input.type || "document";
   assertAcceptedType(requestedType);
+  if (requestedType === PDF_NODE_TYPE && !input.pdf) {
+    throw new ValidationError(`PDF documents can't be created from text \u2014 ${PDF_UPLOAD_HINT}.`);
+  }
+  if (input.pdf && requestedType !== PDF_NODE_TYPE) {
+    throw new ValidationError(`a PDF upload creates a "pdf" node, not "${requestedType}"`);
+  }
   if (input.schedule !== void 0 && !isRunnableType(input.type)) {
     throw new ValidationError(
       `schedule is only valid for runnable node types (${RUNNABLE_NODE_TYPES.join(
@@ -3076,42 +3133,85 @@ async function createNodeOnce(nestId, input, userEmail, opts = {}) {
       ...input.schedule ? { schedule: input.schedule } : {},
       ...input.prime === void 0 ? {} : { prime: input.prime }
     };
-    const publishReason = await autoPublishReason(nestId, userEmail, {
-      tags,
-      metadata
-    });
-    const publishNote = publishReason === null ? void 0 : `Auto-published on create (${publishReason})`;
-    let published = publishReason !== null;
+    const governed = await isStewardshipEnabled(nestId);
+    const creatorReviews = opts.creatorReviews !== false && governed && await nestCreatorIsReviewer(nestId);
+    const creatorSteward = creatorReviews ? await stewardDocumentCreator(nestId, id, userEmail) : null;
+    let published = false;
+    let publishNote;
     try {
-      await engineApi.run(
-        "context_create",
-        {
-          id,
-          title: input.title,
-          content: input.content,
-          type: requestedType,
-          // A skill node is invalid without a skill block, and this surface has
-          // no field for one — default the trigger from the title, same as the
-          // CLI and mcp-server do.
-          ...requestedType === "skill" ? { trigger: `when asked to ${input.title.toLowerCase()}` } : {},
-          ...tags.length ? { tags } : {},
-          ...input.status ? { status: input.status } : {},
-          metadata,
-          publish: published,
-          ...publishNote ? { note: publishNote } : {}
-        },
-        await opContext(nestId, userEmail)
+      const publishReason = await autoPublishReason(
+        nestId,
+        userEmail,
+        { tags, metadata },
+        { creatorReviews: creatorSteward?.canApprove === true, governed }
       );
-    } catch (err) {
-      let onDisk = true;
+      publishNote = publishReason === null ? void 0 : `Auto-published on create (${publishReason})`;
+      published = publishReason !== null;
       try {
-        await storage.readDocument(id);
-      } catch {
-        onDisk = false;
+        if (input.pdf) {
+          try {
+            await engineApi.run(
+              "context_import_pdf",
+              {
+                id,
+                title: input.title,
+                bytes_base64: Buffer.from(input.pdf.bytes).toString("base64"),
+                ...input.pdf.filename ? { filename: input.pdf.filename } : {},
+                ...tags.length ? { tags } : {},
+                publish: published,
+                ...publishNote ? { note: publishNote } : {},
+                ...input.client ? { client: input.client } : {}
+              },
+              await opContext(nestId, userEmail)
+            );
+          } catch (err) {
+            throw pdfEngineError(err);
+          }
+        } else {
+          await engineApi.run(
+            "context_create",
+            {
+              id,
+              title: input.title,
+              content: input.content,
+              type: requestedType,
+              // A skill node is invalid without a skill block, and this surface
+              // has no field for one — default the trigger from the title, same
+              // as the CLI and mcp-server do.
+              ...requestedType === "skill" ? { trigger: `when asked to ${input.title.toLowerCase()}` } : {},
+              ...tags.length ? { tags } : {},
+              ...input.status ? { status: input.status } : {},
+              metadata,
+              publish: published,
+              ...publishNote ? { note: publishNote } : {}
+            },
+            await opContext(nestId, userEmail)
+          );
+        }
+      } catch (err) {
+        let onDisk = true;
+        try {
+          await storage.readDocument(id);
+        } catch {
+          onDisk = false;
+        }
+        if (!onDisk) throw err;
+        console.error("publishDocument failed (node create auto-publish)", err);
+        published = false;
+      }
+    } catch (err) {
+      if (creatorSteward?.insertedId) {
+        try {
+          await removeSteward(creatorSteward.insertedId);
+        } catch (cleanupErr) {
+          console.error(
+            "removeSteward failed while compensating a failed create",
+            id,
+            cleanupErr
+          );
+        }
       }
-      if (!onDisk) throw err;
-      console.error("publishDocument failed (node create auto-publish)", err);
-      published = false;
+      throw err;
     }
     const node = await storage.readDocument(id);
     await syncNodeTags(nestId, id, tags);
@@ -3126,7 +3226,8 @@ async function createNodeOnce(nestId, input, userEmail, opts = {}) {
         author: userEmail,
         status: "published",
         tags,
-        changeNote: publishNote
+        changeNote: publishNote,
+        client: input.client
       });
       await setApprovedVersion(nestId, id, savedVersion, userEmail);
     } else {
@@ -3134,10 +3235,12 @@ async function createNodeOnce(nestId, input, userEmail, opts = {}) {
         nestId,
         nodeId: id,
         version: 1,
-        content: input.content,
+        // A pdf node's body is what the engine extracted, not anything sent.
+        content: input.pdf ? node.body || "" : input.content,
         author: userEmail,
         status: "draft",
-        tags
+        tags,
+        client: input.client
       });
     }
     await trackEvent("node.create", { nestId, nodeId: id });
@@ -3191,7 +3294,7 @@ async function alignOnDiskStatus(nestId, documentId, status) {
     );
   }
 }
-async function registerImportedDocuments(nestId, userEmail) {
+async function registerImportedDocuments(nestId, userEmail, client) {
   const startedAt = Date.now();
   const tracked = await getTrackedNodeIds(nestId);
   (await engineCache.get(nestId)).invalidateDiscovery();
@@ -3221,7 +3324,8 @@ async function registerImportedDocuments(nestId, userEmail) {
       author: userEmail,
       status: d.status,
       changeNote: d.status === "published" ? "Imported from existing folder" : "Imported from existing folder \u2014 could not be published, kept as a draft",
-      tags
+      tags,
+      client
     });
     if (d.status === "published") {
       await setApprovedVersion(nestId, d.id, d.version, userEmail);
@@ -3243,6 +3347,44 @@ async function registerImportedDocuments(nestId, userEmail) {
   await trackEvent("nest.import.documents", { nestId, registered: docs.length });
   return docs.length;
 }
+async function stagePdfImport(nestId, nodeId, pdf, userEmail, client, priorRaw) {
+  const { storage } = await engineCache.get(nestId);
+  const sidecar = pdfSidecarPath(nodeId);
+  let priorSidecar = null;
+  try {
+    priorSidecar = await storage.readVaultBinary(sidecar);
+  } catch {
+  }
+  const sealedBefore = await storage.maxRecordedVersion(nodeId);
+  const rollback = async () => {
+    if (await storage.maxRecordedVersion(nodeId).catch(() => sealedBefore) > sealedBefore) {
+      return;
+    }
+    try {
+      await storage.writeDocument(nodeId, priorRaw);
+      if (priorSidecar) await storage.writeVaultBinary(sidecar, priorSidecar);
+      await storage.regenerateIndex();
+    } catch (err) {
+      console.error("[pdf] could not roll back a failed PDF replace", nestId, nodeId, err);
+    }
+  };
+  try {
+    const result = await engineApi.run(
+      "context_import_pdf",
+      {
+        id: nodeId,
+        bytes_base64: Buffer.from(pdf.bytes).toString("base64"),
+        ...pdf.filename ? { filename: pdf.filename } : {},
+        publish: false,
+        ...client ? { client } : {}
+      },
+      await opContext(nestId, userEmail)
+    );
+    return { unchanged: result.unchanged === true, rollback };
+  } catch (err) {
+    throw pdfEngineError(err);
+  }
+}
 async function updateNode(nestId, nodeId, patch, userEmail, opts = {}) {
   return withNodeWriteLock(nodeWriteKey(nestId, nodeId), async () => {
     try {
@@ -3255,6 +3397,35 @@ async function updateNode(nestId, nodeId, patch, userEmail, opts = {}) {
       } catch {
         throw new NotFoundError(`Node not found: ${nodeId}`);
       }
+      const priorRaw = node.rawContent;
+      let pdfRollback = null;
+      if (patch.type === void 0 || patch.type === node.frontmatter.type) {
+        assertUpdatableType(node.frontmatter.type);
+      }
+      const storedType = node.frontmatter.type || "document";
+      const isPdfNode = storedType === PDF_NODE_TYPE;
+      if (patch.pdf && !isPdfNode) {
+        throw new ValidationError(
+          `${nodeId} is a "${storedType}" node, not a PDF \u2014 a PDF can only replace the PDF of a pdf node.`
+        );
+      }
+      if (patch.type !== void 0 && patch.type !== storedType) {
+        if (isPdfNode || patch.type === PDF_NODE_TYPE) {
+          throw new ValidationError(
+            isPdfNode ? "A PDF document can't be converted to another type \u2014 its body is the text of its PDF." : `A document can't be converted to a PDF \u2014 ${PDF_UPLOAD_HINT}.`
+          );
+        }
+      }
+      if (isPdfNode) {
+        const readOnly = "This is a PDF document: its text is extracted from the PDF and can't be edited directly. Upload a new version of the PDF (Replace PDF) to change it.";
+        if (patch.append) throw new ConflictError(readOnly);
+        if (patch.content !== void 0) {
+          if (patch.content.trim() !== (node.body || "").trim()) {
+            throw new ConflictError(readOnly);
+          }
+          patch = { ...patch, content: void 0 };
+        }
+      }
       const previousBody = node.body || "";
       const opInput = {};
       if (patch.content !== void 0) {
@@ -3350,11 +3521,30 @@ async function updateNode(nestId, nodeId, patch, userEmail, opts = {}) {
       if (publishReason === null || isAuthorEditingOwnReview) {
         const currentVersion = await getCurrentVersion(nestId, nodeId);
         const newVersion = await versionManager.nextVersion(nodeId, currentVersion);
-        await engineApi.run(
-          "context_update",
-          { id: nodeId, ...opInput, publish: false, version: newVersion },
-          await opContext(nestId, userEmail)
-        );
+        if (patch.pdf) {
+          const staged = await stagePdfImport(
+            nestId,
+            nodeId,
+            patch.pdf,
+            userEmail,
+            patch.client,
+            priorRaw
+          );
+          if (staged.unchanged && Object.keys(opInput).length === 0) {
+            return { node, version: node.frontmatter.version || currentVersion || 1 };
+          }
+          if (!staged.unchanged) pdfRollback = staged.rollback;
+        }
+        try {
+          await engineApi.run(
+            "context_update",
+            { id: nodeId, ...opInput, publish: false, version: newVersion },
+            await opContext(nestId, userEmail)
+          );
+        } catch (err) {
+          if (pdfRollback) await pdfRollback();
+          throw err;
+        }
         node = await storage.readDocument(nodeId);
         await syncNodeTags(nestId, nodeId, currentTags);
         await deleteSupersededDrafts(nestId, nodeId, newVersion);
@@ -3366,7 +3556,8 @@ async function updateNode(nestId, nodeId, patch, userEmail, opts = {}) {
           author: userEmail,
           status: "draft",
           tags: currentTags,
-          changeNote: patch.changeNote
+          changeNote: patch.changeNote,
+          client: patch.client
         });
         if (isAuthorEditingOwnReview) {
           await repointPendingReview({ nestId, nodeId, newVersion });
@@ -3375,6 +3566,20 @@ async function updateNode(nestId, nodeId, patch, userEmail, opts = {}) {
       } else {
         const publishNote = patch.changeNote || `Auto-published on edit (${publishReason})`;
         let publishedVersion;
+        if (patch.pdf) {
+          const staged = await stagePdfImport(
+            nestId,
+            nodeId,
+            patch.pdf,
+            userEmail,
+            patch.client,
+            priorRaw
+          );
+          if (staged.unchanged && Object.keys(opInput).length === 0) {
+            return { node, version: node.frontmatter.version || 1 };
+          }
+          if (!staged.unchanged) pdfRollback = staged.rollback;
+        }
         try {
           const result = await engineApi.run(
             "context_update",
@@ -3387,6 +3592,7 @@ async function updateNode(nestId, nodeId, patch, userEmail, opts = {}) {
             "publishDocument failed (node patch auto-publish)",
             err
           );
+          if (pdfRollback) await pdfRollback();
           throw err;
         }
         node = await storage.readDocument(nodeId);
@@ -3399,7 +3605,8 @@ async function updateNode(nestId, nodeId, patch, userEmail, opts = {}) {
           author: userEmail,
           status: "published",
           tags: currentTags,
-          changeNote: publishNote
+          changeNote: publishNote,
+          client: patch.client
         });
         await setApprovedVersion(
           nestId,
@@ -3505,6 +3712,11 @@ async function moveNode(nestId, nodeId, folder, userEmail) {
   } catch {
     throw new NotFoundError(`Node not found: ${nodeId}`);
   }
+  if (node.frontmatter.type === PDF_NODE_TYPE) {
+    throw new ValidationError(
+      "PDF documents can't be moved to another folder yet. Upload the PDF again in the destination folder instead."
+    );
+  }
   await assertNotReviewLocked(nestId, nodeId, userEmail, "moving");
   const leaf = nodeId.split("/").pop();
   const segments = folderToSegments(folder);
@@ -3601,6 +3813,16 @@ async function discardDraft(nestId, nodeId, userEmail) {
     await storage.writeDocument(nodeId, raw);
     await storage.regenerateIndex();
     const restored = parseDocument(`${nodeId}.md`, raw, nodeId);
+    let warning;
+    if (restored.frontmatter.type === PDF_NODE_TYPE) {
+      try {
+        const bytes = await readPdfBinary(storage, nodeId);
+        await storage.writeVaultBinary(pdfSidecarPath(nodeId), bytes);
+      } catch (err) {
+        console.error("[pdf] could not restore the sealed binary on discard", nestId, nodeId, err);
+        warning = `The draft was discarded, but the PDF of version ${sealed} could not be restored (its archived copy is missing or no longer matches). Upload the PDF again, or ask an admin to verify the nest.`;
+      }
+    }
     await syncNodeTags(
       nestId,
       nodeId,
@@ -3608,7 +3830,7 @@ async function discardDraft(nestId, nodeId, userEmail) {
     );
     await deleteUnsealedVersions(nestId, nodeId, sealed);
     await trackEvent("node.discard_draft", { nestId, nodeId, version: sealed });
-    return { deleted: false, version: sealed };
+    return { deleted: false, version: sealed, ...warning ? { warning } : {} };
   });
 }
 async function deleteNode(nestId, nodeId, userEmail) {
@@ -3835,7 +4057,7 @@ function collectMarkdownFiles(dir, root) {
   }
   return out;
 }
-async function syncUnsyncedFolder(userId, folderName, callerEmail) {
+async function syncUnsyncedFolder(userId, folderName, callerEmail, client) {
   console.log(
     `[unsynced] sync requested folder="${folderName}" user="${callerEmail}"`
   );
@@ -3876,7 +4098,7 @@ async function syncUnsyncedFolder(userId, folderName, callerEmail) {
   let documents;
   try {
     await stageImportedFiles(nest.id, files, callerEmail);
-    documents = await registerImportedDocuments(nest.id, callerEmail);
+    documents = await registerImportedDocuments(nest.id, callerEmail, client);
   } catch (err) {
     await deleteNest(nest.id).catch(() => {
     });
@@ -3997,7 +4219,11 @@ nestRoutes.get("/", async (c) => {
     seen.add(n.id);
     deduped.push(n);
   }
-  const out = await Promise.all(deduped.map(annotate));
+  const memberIds = new Set([...owned, ...shared].map((n) => n.id));
+  const out = (await Promise.all(deduped.map(annotate))).map((row) => ({
+    ...row,
+    discovered: !memberIds.has(row.id)
+  }));
   const docRows = await db.all(
     `SELECT nest_id,
             COUNT(DISTINCT CASE
@@ -4096,7 +4322,14 @@ nestRoutes.post("/:nestId", async (c) => {
     }
     const email2 = await resolveCallerEmail(userId);
     if (body.finalize) {
-      return c.json({ nest: nest2, documents: await registerImportedDocuments(target, email2) });
+      return c.json({
+        nest: nest2,
+        documents: await registerImportedDocuments(
+          target,
+          email2,
+          attributeRequest(c, body.client)
+        )
+      });
     }
     const registered = await getDb().get(
       "SELECT COUNT(*) AS c FROM node_versions WHERE nest_id = ?",
@@ -4123,7 +4356,11 @@ nestRoutes.post("/:nestId", async (c) => {
     if (body.partial) {
       return c.json({ nest, rejected }, 201);
     }
-    const documents = await registerImportedDocuments(nest.id, email);
+    const documents = await registerImportedDocuments(
+      nest.id,
+      email,
+      attributeRequest(c, body.client)
+    );
     return c.json({ nest, documents, rejected }, 201);
   } catch (err) {
     await deleteNest(nest.id).catch(() => {
@@ -4153,7 +4390,8 @@ nestRoutes.post("/:nestId/sync", async (c) => {
   const result = await syncUnsyncedFolder(
     userId,
     body.name,
-    await resolveCallerEmail(userId)
+    await resolveCallerEmail(userId),
+    attributeRequest(c, body.client)
   );
   return c.json(result, 201);
 });
@@ -4275,7 +4513,8 @@ nestRoutes.get("/:nestId/settings", async (c) => {
     stewardship_enabled: await isStewardshipEnabled(nestId),
     allow_self_approve: await nestAllowsSelfApprove(nestId),
     prime_only_review: await nestReviewsPrimeOnly(nestId),
-    prime_tags: await nestPrimeTags(nestId)
+    prime_tags: await nestPrimeTags(nestId),
+    creator_is_reviewer: await nestCreatorIsReviewer(nestId)
   });
 });
 nestRoutes.patch("/:nestId/settings", async (c) => {
@@ -4320,11 +4559,15 @@ nestRoutes.patch("/:nestId/settings", async (c) => {
       Array.isArray(body.prime_tags) ? body.prime_tags : [body.prime_tags]
     );
   }
+  if (typeof body.creator_is_reviewer === "boolean") {
+    await setCreatorIsReviewer(nestId, body.creator_is_reviewer);
+  }
   return c.json({
     stewardship_enabled: await isStewardshipEnabled(nestId),
     allow_self_approve: await nestAllowsSelfApprove(nestId),
     prime_only_review: await nestReviewsPrimeOnly(nestId),
     prime_tags: await nestPrimeTags(nestId),
+    creator_is_reviewer: await nestCreatorIsReviewer(nestId),
     wiped
   });
 });
@@ -4539,12 +4782,24 @@ sharingRoutes.patch("/visibility", async (c) => {
   if (!body.visibility || !["private", "org", "public"].includes(body.visibility)) {
     throw new ValidationError("visibility must be private, org or public");
   }
-  if (body.visibility === "public" && body.acknowledge_public !== true) {
+  const ack = body.acknowledge_public === true;
+  const shared = config.SHARED_DEPLOYMENT;
+  if (body.visibility === "public" && !ack) {
     return c.json(
       {
         error: "Publishing this nest requires acknowledgement.",
         requires_acknowledgement: true,
-        warning: "This makes the nest readable by anyone on the internet, outside your organization."
+        warning: shared ? "This makes the nest readable by anyone on the internet \u2014 including every account on this server, which belongs to other organizations too." : "This makes the nest readable by anyone on the internet, outside your organization."
+      },
+      409
+    );
+  }
+  if (body.visibility === "org" && shared && !ack) {
+    return c.json(
+      {
+        error: "Opening this nest to the organization requires acknowledgement.",
+        requires_acknowledgement: true,
+        warning: "This server is shared: 'Organization' makes the nest readable by every account on this server, including other organizations \u2014 not just yours."
       },
       409
     );
@@ -5338,7 +5593,7 @@ async function syncAnnotationsNode(nestId, nodeId, userEmail) {
             tags: ["annotations"]
           },
           userEmail,
-          { notifyMentions: false }
+          { notifyMentions: false, creatorReviews: false }
         );
       } else {
         throw err;
@@ -5504,7 +5759,7 @@ var GATE_EYE_SCRIPT = `<script>
 </script>`;
 function gatePage(row, message) {
   const wantsCode = row.access_mode === "code";
-  const field = wantsCode ? `<label>Access code<span class="wrap">
+  const field2 = wantsCode ? `<label>Access code<span class="wrap">
         <input id="cn-code" name="code" type="password" autocomplete="off" required autofocus>
         <button type="button" id="cn-eye" class="eye" aria-label="Show code" aria-pressed="false">${EYE_SVG}</button>
       </span></label>` : `<label>Your email<input name="email" type="email" autocomplete="email" required autofocus></label>`;
@@ -5528,7 +5783,7 @@ function gatePage(row, message) {
     .err{color:#be123c;font-weight:600}
     .brand{font-size:12px;color:#a8a29e;margin:18px 0 0;text-align:center}
   </style></head><body><form class="card" method="POST" action="/p/${esc(row.slug)}/gate">
-    <h1>Protected document</h1><p>${esc(note)}</p>${err}${field}
+    <h1>Protected document</h1><p>${esc(note)}</p>${err}${field2}
     <button type="submit">${cta}</button>
     <p class="brand">Secured by PromptOwl \xB7 ContextNest</p>
   </form>${wantsCode ? GATE_EYE_SCRIPT : ""}</body></html>`;
@@ -6108,6 +6363,7 @@ function toSearchHit(node, query) {
 
 // src/nodes/routes.ts
 import { Hono as Hono11 } from "hono";
+import { parseDocument as parseDocument3, readPdfBinary as readPdfBinary2 } from "@promptowl/contextnest-engine";
 
 // src/nodes/markdown-export.ts
 import { parseDocument as parseDocument2 } from "@promptowl/contextnest-engine";
@@ -6224,7 +6480,8 @@ nodeRoutes.post("/", async (c) => {
       status: body.status,
       schedule: body.schedule,
       folder: body.folder,
-      prime: body.prime
+      prime: body.prime,
+      client: attributeRequest(c, body.client)
     },
     authorEmail
   );
@@ -6241,7 +6498,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-4DHNRULG.js");
+  const { resolveStewardsWithFallback: resolveStewardsWithFallback2 } = await import("./stewardship-service-S22V2JKG.js");
   const { stewards, fallbackToOwner, ownerEmail } = await resolveStewardsWithFallback2(
     nestId,
     nodeId
@@ -6262,7 +6519,7 @@ nodeRoutes.get("/:nodeId{.+}/stewards", 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-HHGOTO6P.js");
+  const { getReviewHistory: getReviewHistory2 } = await import("./review-service-4G2XUFS6.js");
   const history = await getReviewHistory2(nestId, nodeId);
   return c.json({ reviews: history });
 });
@@ -6283,7 +6540,7 @@ nodeRoutes.post("/:nodeId{.+}/discard", async (c) => {
 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 { storage, versions: versionManager } = await engineCache.get(nestId);
   const userId = c.get("userId");
   const userEmail = await resolveCallerEmail(userId);
   if (!await canReadNode(nestId, nodeId, userId, userEmail)) {
@@ -6305,11 +6562,26 @@ nodeRoutes.post("/:nodeId{.+}/revert", async (c) => {
       `Version ${targetVersion} not found for ${nodeId}`
     );
   }
+  let restoredPdf = null;
+  if (pdfMetaOf(nodeId, raw)) {
+    try {
+      restoredPdf = await readPdfBinary2(storage, nodeId, {
+        version: targetVersion
+      });
+    } catch (err) {
+      console.error("[pdf] revert could not read the version's binary", nestId, nodeId, targetVersion, err);
+      throw new NotFoundError(`The PDF of version ${targetVersion} is not available to restore.`);
+    }
+  }
   const content = bodyOnly(nodeId, raw);
   const { node, version } = await updateNode(
     nestId,
     nodeId,
-    { content, changeNote: `Restored from version ${targetVersion}` },
+    {
+      ...restoredPdf ? { pdf: { bytes: new Uint8Array(restoredPdf) } } : { content },
+      changeNote: `Restored from version ${targetVersion}`,
+      client: attributeRequest(c, body.client)
+    },
     userEmail
   );
   await trackEvent("node.revert", { nestId, nodeId, targetVersion });
@@ -6412,6 +6684,10 @@ nodeRoutes.get("/:nodeId{.+}", async (c) => {
           approved
         );
         response.content = bodyOnly(nodeId, approvedRaw);
+        if (response.type === "pdf") {
+          const approvedPdf = pdfMetaOf(nodeId, approvedRaw);
+          if (approvedPdf) response.pdf = approvedPdf;
+        }
       } catch (err) {
         console.error(
           "reconstructVersion failed (public single)",
@@ -6494,6 +6770,7 @@ nodeRoutes.patch("/:nodeId{.+}", async (c) => {
       changeNote: body.changeNote,
       schedule: body.schedule,
       prime: body.prime,
+      client: attributeRequest(c, body.client),
       type: body.type
     },
     authorEmail
@@ -6506,6 +6783,13 @@ nodeRoutes.delete("/:nodeId{.+}", async (c) => {
   await deleteNode(nestId, nodeId, await getUserEmail(c));
   return c.json({ deleted: true });
 });
+function pdfMetaOf(nodeId, raw) {
+  try {
+    return parseDocument3(`${nodeId}.md`, raw, nodeId).frontmatter.pdf;
+  } catch {
+    return void 0;
+  }
+}
 async function getUserEmail(c) {
   const userId = c.get("userId");
   const db = getDb();
@@ -7231,6 +7515,17 @@ async function buildNestGraph(nestId, userId, userEmail, canSeeIdentities) {
     }
   }
   const tags = [...tagCounts.entries()].map(([name, count]) => ({ name, count })).sort((a, b) => b.count - a.count);
+  for (const docIds of tagToDocs.values()) {
+    const ids = [...docIds].sort();
+    for (let i = 0; i < ids.length; i++) {
+      for (let j = i + 1; j < ids.length; j++) {
+        const key = `${ids[i]}->${ids[j]}`;
+        if (seen.has(key) || seen.has(`${ids[j]}->${ids[i]}`)) continue;
+        seen.add(key);
+        allLinks.push({ source: ids[i], target: ids[j] });
+      }
+    }
+  }
   const exposeStewards = await isStewardshipEnabled(nestId) && !await isPublicReader(nestId, userId);
   const stewardRows = exposeStewards ? (await listStewards({ nestId })).filter(
     // Drop document-scoped rows whose node the caller can't see.
@@ -7879,7 +8174,8 @@ queryRoutes.post("/publish", async (c) => {
           content: doc.content,
           type: doc.type,
           tags: doc.tags,
-          scope: doc.scope
+          scope: doc.scope,
+          folder: doc.folder
         },
         userEmail
       );
@@ -7915,6 +8211,9 @@ import { Hono as Hono15 } from "hono";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 
+// src/mcp/tools.ts
+import { parseDocument as parseDocument4 } from "@promptowl/contextnest-engine";
+
 // src/telemetry/trace-log.ts
 var PRUNE_EVERY = 500;
 var insertsSincePrune = 0;
@@ -7923,8 +8222,8 @@ async function logTraceEvent(e) {
     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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+         (ts, kind, method, path, tool, nest_id, user_id, user_email, status, duration_ms, client_json)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       [
         (/* @__PURE__ */ new Date()).toISOString(),
         e.kind,
@@ -7935,7 +8234,8 @@ async function logTraceEvent(e) {
         e.userId ?? null,
         e.userEmail ?? null,
         e.status ?? null,
-        e.durationMs ?? null
+        e.durationMs ?? null,
+        serializeClient(e.client)
       ]
     );
     if (++insertsSincePrune >= PRUNE_EVERY) {
@@ -7984,7 +8284,13 @@ async function listTraceEvents(filters = {}) {
         LIMIT ? OFFSET ?`,
       [...args, limit, offset]
     );
-    return { events, total };
+    return {
+      events: events.map(({ client_json, ...e }) => {
+        const client = deserializeClient(client_json);
+        return client ? { ...e, client } : e;
+      }),
+      total
+    };
   } catch {
     return { events: [], total: 0 };
   }
@@ -9032,6 +9338,19 @@ function summarizeNode(node, body) {
     body: body ?? void 0
   };
 }
+function pdfSourceLine(node, body) {
+  if ((node.frontmatter.type || "document") !== "pdf") return null;
+  let pdf = node.frontmatter.pdf;
+  if (body && body.startsWith("---")) {
+    try {
+      pdf = parseDocument4(`${node.id}.md`, body, node.id).frontmatter.pdf ?? pdf;
+    } catch {
+    }
+  }
+  if (!pdf) return "**Source file:** PDF";
+  const pages = `${pdf.pages} page${pdf.pages === 1 ? "" : "s"}`;
+  return `**Source file:** PDF, ${pages}${pdf.text_layer ? "" : ", no text layer"}`;
+}
 var TOOL_DEFINITIONS = [
   {
     name: "context_init",
@@ -9262,7 +9581,7 @@ var TOOL_DEFINITIONS = [
         tags: {
           type: "array",
           items: { type: "string" },
-          description: "Tags to add"
+          description: "The node's full tag set \u2014 REPLACES the existing tags (same as the engine catalog). To add one, send the current tags plus the new one; to remove one, send the set without it."
         },
         status: {
           type: "string",
@@ -9431,10 +9750,14 @@ var TOOL_DEFINITIONS = [
       type: "object",
       properties: {
         title: { type: "string", description: "Title of the node to submit" },
+        id: {
+          type: "string",
+          description: 'Node id / path (e.g. "nodes/gtm/deals/win-loss-log"). Use instead of title when two nodes share a title or the title is unknown.'
+        },
         note: { type: "string", description: "Optional note for the reviewer" },
         priority: { type: "string", description: "Priority: low, normal (default), high, urgent" }
-      },
-      required: ["title"]
+      }
+      // One of id or title — see context_update.
     }
   },
   {
@@ -9572,8 +9895,30 @@ async function resolveLlmBody(ctx, node, gate) {
 async function handleToolCall(toolName, args, ctx) {
   const started = Date.now();
   let status = 200;
+  let client;
+  try {
+    client = mergeClient(ctx.client, parseClientMetadata(args.client));
+  } catch (err) {
+    void logTraceEvent({
+      kind: "mcp",
+      tool: toolName,
+      nestId: ctx.nestId,
+      userId: ctx.userId,
+      userEmail: ctx.userEmail,
+      status: 400,
+      durationMs: Date.now() - started
+    });
+    return toolError(err.message, "VALIDATION_FAILED");
+  }
+  const attributed = { ...ctx, client };
+  if ((toolName === "context_create" || toolName === "context_update") && typeof args.content === "string" && /^\s*---\r?\n[\w-]+:/.test(args.content)) {
+    return toolError(
+      "`content` is the markdown body only \u2014 it starts with a YAML frontmatter block, which would be stored as body text. Drop the `---` block and pass tags/status as parameters; the server owns the frontmatter.",
+      "VALIDATION_FAILED"
+    );
+  }
   try {
-    return await runTool(toolName, args, ctx);
+    return await runTool(toolName, args, attributed);
   } catch (err) {
     if (isVaultLockTimeout(err) || err instanceof VaultBusyError) {
       status = 503;
@@ -9592,7 +9937,10 @@ async function handleToolCall(toolName, args, ctx) {
       userId: ctx.userId,
       userEmail: ctx.userEmail,
       status,
-      durationMs: Date.now() - started
+      durationMs: Date.now() - started,
+      // Reads record attribution HERE — the activity trace is this edition's
+      // §9.2 access trace, and a read seals no version to carry it.
+      client
     });
   }
 }
@@ -9787,7 +10135,8 @@ ${list}`,
       const meta = [
         `**Title:** ${node.frontmatter.title}`,
         `**Type:** ${node.frontmatter.type || "document"}`,
-        node.frontmatter.tags?.length ? `**Tags:** ${node.frontmatter.tags.join(" ")}` : null
+        node.frontmatter.tags?.length ? `**Tags:** ${node.frontmatter.tags.join(" ")}` : null,
+        pdfSourceLine(node, body)
       ].filter(Boolean).join("\n");
       return {
         text: `${meta}
@@ -10050,7 +10399,8 @@ ${sections}`;
             type: args.type,
             tags: args.tags,
             scope: args.scope,
-            folder: args.folder
+            folder: args.folder,
+            client: ctx.client
           },
           userEmail
         );
@@ -10078,16 +10428,16 @@ ${sections}`;
           "UNAUTHORIZED_ACTION"
         );
       }
-      const mergedTags = args.tags ? [.../* @__PURE__ */ new Set([...node.frontmatter.tags || [], ...args.tags])] : void 0;
       const { node: updated, version } = await updateNode(
         nestId,
         node.id,
         {
           content: args.content,
           append: args.append,
-          tags: mergedTags,
+          tags: args.tags,
           status: args.status,
-          changeNote: args.changeNote
+          changeNote: args.changeNote,
+          client: ctx.client
         },
         userEmail
       );
@@ -10140,10 +10490,11 @@ Use context_request_deletion to ask a nest owner/admin to delete it, with a reas
         args.folder,
         userEmail
       );
+      const data = { id: moved.id, previous_id: previousId, title: moved.frontmatter.title };
       if (previousId === moved.id) {
-        return `**${moved.frontmatter.title}** is already at \`${moved.id}\` \u2014 nothing to move.`;
+        return { text: `**${moved.frontmatter.title}** is already at \`${moved.id}\` \u2014 nothing to move.`, data };
       }
-      return `Moved **${moved.frontmatter.title}**: \`${previousId}\` \u2192 \`${moved.id}\``;
+      return { text: `Moved **${moved.frontmatter.title}**: \`${previousId}\` \u2192 \`${moved.id}\``, data };
     }
     // ─── Governance Tool Handlers ──────────────────────────────────────
     case "context_stewards": {
@@ -10386,7 +10737,8 @@ Submit one with \`context_submit_review\`.`;
           requestedBy: ctx.userEmail,
           note: args.note,
           priority: args.priority,
-          baseUrl: ctx.baseUrl
+          baseUrl: ctx.baseUrl,
+          client: ctx.client
         });
         const resolved2 = await resolveStewardsForNode(
           ctx.nestId,
@@ -10437,7 +10789,8 @@ ${resolved2.map((r) => `- ${r.steward.userEmail} (${r.source})`).join("\n")}` :
           nodeId: node.id,
           approvedBy: ctx.userEmail,
           note: args.note,
-          baseUrl: ctx.baseUrl
+          baseUrl: ctx.baseUrl,
+          client: ctx.client
         });
         return `Approved "${args.title}" v${request.version}. This version is now live for AI queries.${args.note ? `
 Note: ${args.note}` : ""}`;
@@ -10478,7 +10831,9 @@ Reason: ${args.note}`;
         };
       }
       const list = allVersions.map(
-        (v) => `- **v${v.version}** ${v.status}${v.version === approved ? " (AI-active)" : ""} \u2014 by ${v.editedBy} at ${v.editedAt}${v.changeNote ? ` "${v.changeNote}"` : ""}`
+        (v) => `- **v${v.version}** ${v.status}${v.version === approved ? " (AI-active)" : ""} \u2014 by ${v.editedBy} at ${v.editedAt}${v.changeNote ? ` "${v.changeNote}"` : ""}${// §9.4: which agent wrote it. In the prose as well as the
+        // structured payload — a chat client reads only this half.
+        v.client?.agent ? ` [via ${v.client.agent}]` : ""}`
       ).join("\n");
       return {
         text: `# Version History: ${label}
@@ -10502,7 +10857,11 @@ ${list}`,
             status: v.status,
             edited_by: v.editedBy,
             edited_at: v.editedAt,
-            note: v.changeNote
+            note: v.changeNote,
+            // §9.4: which agent wrote this version, in which session. Omitted
+            // (not `{}`) when the write carried no attribution — "not
+            // attributed" and "attributed to nobody" are different claims.
+            ...v.client ? { client: v.client } : {}
           }))
         }
       };
@@ -10563,8 +10922,8 @@ ${list}`,
       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-UT3EQ3R7.js");
-        const db = (await import("./client-KEY4PYJH.js")).getDb();
+        const { createGrant: createGrant2 } = await import("./grants-service-2OTFS7EH.js");
+        const db = (await import("./client-D44ZHDTJ.js")).getDb();
         const { normalizeEmail: normalizeEmail2 } = await import("./email-R7DFS6E5.js");
         const e = normalizeEmail2(String(args.email || ""));
         if (!e) return "email is required.";
@@ -10613,7 +10972,8 @@ ${list}`;
         const { nest, documents } = await syncUnsyncedFolder(
           userId,
           args.name,
-          userEmail
+          userEmail,
+          ctx.client
         );
         return `Synced folder "${args.name}" \u2192 nest **${nest.name}** (${nest.id}) with ${documents} document(s).`;
       } catch (err) {
@@ -10636,7 +10996,7 @@ async function getUserEmail2(userId) {
   const user = await db.get("SELECT email FROM users WHERE id = ?", [userId]);
   return user?.email || "anonymous@localhost";
 }
-function createMcpServerForNest(nestId, userId, userEmail, baseUrl) {
+function createMcpServerForNest(nestId, userId, userEmail, baseUrl, c) {
   const server = new McpServer(
     { name: `contextnest-${nestId}`, version: "1.0.0" },
     { capabilities: { tools: {} } }
@@ -10647,16 +11007,18 @@ function createMcpServerForNest(nestId, userId, userEmail, baseUrl) {
     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;
-    }
+      let field2;
+      if (def.type === "string") field2 = z.string();
+      else if (def.type === "number") field2 = z.number();
+      else if (def.type === "array") field2 = z.array(z.string());
+      else field2 = z.any();
+      if (!required.includes(key)) field2 = field2.optional();
+      shape[key] = field2;
+    }
+    Object.assign(shape, clientToolField);
     server.tool(tool.name, tool.description, shape, async (args) => {
       const engine = await engineCache.get(nestId);
+      const client = attributeRequest(c, void 0, connectionClient(server));
       const out = await handleToolCall(tool.name, args, {
         storage: engine.storage,
         queryEngine: engine.query,
@@ -10664,7 +11026,8 @@ function createMcpServerForNest(nestId, userId, userEmail, baseUrl) {
         nestId,
         userId,
         userEmail,
-        baseUrl
+        baseUrl,
+        client
       });
       return toCallToolResult(out);
     });
@@ -10679,7 +11042,8 @@ mcpRoutes.all("/", async (c) => {
     nestId,
     userId,
     userEmail,
-    requestBaseUrl(c.req.url)
+    requestBaseUrl(c.req.url),
+    c
   );
   const transport = new WebStandardStreamableHTTPServerTransport({
     sessionIdGenerator: void 0,
@@ -11749,8 +12113,185 @@ assetRoutes.get("/:file", async (c) => {
   });
 });
 
-// src/auth/community-sites-routes.ts
+// src/nodes/pdf-routes.ts
 import { Hono as Hono22 } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { createHash as createHash3 } from "crypto";
+import { isPdf, readPdfBinary as readPdfBinary3 } from "@promptowl/contextnest-engine";
+var pdfNodeRoutes = new Hono22();
+var PDF_UPLOAD_PATH = /^\/nests\/[^/]+\/nodes\/pdf\/?$/;
+function pdfMaxRequestBytes() {
+  return config.PDF_MAX_BYTES + 1024 * 1024;
+}
+function tooLarge(bytes) {
+  return new PayloadTooLargeError(
+    `PDF too large (${(bytes / (1024 * 1024)).toFixed(1)} MB, max ${config.PDF_MAX_BYTES / (1024 * 1024)} MB)`
+  );
+}
+function field(body, name) {
+  const v = body[name];
+  const one = Array.isArray(v) ? v[0] : v;
+  return typeof one === "string" ? one.trim() : "";
+}
+function tagsField(body) {
+  const v = body["tags"];
+  if (v === void 0) return void 0;
+  const raw = (Array.isArray(v) ? v : [v]).filter((x) => typeof x === "string");
+  const tags = raw.flatMap((s) => s.split(",")).map((t) => t.trim().replace(/^#/, "")).filter(Boolean);
+  return tags;
+}
+function titleFromFilename(name) {
+  return name.split(/[/\\]/).pop().replace(/\.pdf$/i, "").replace(/[_]+/g, " ").trim().slice(0, 200);
+}
+pdfNodeRoutes.post(
+  "/pdf",
+  (c, next) => bodyLimit({
+    maxSize: pdfMaxRequestBytes(),
+    onError: (c2) => c2.json(
+      {
+        error: `PDF too large (max ${config.PDF_MAX_BYTES / (1024 * 1024)} MB)`
+      },
+      413
+    )
+  })(c, next),
+  async (c) => {
+    const nestId = c.req.param("nestId");
+    const lenStr = c.req.header("Content-Length");
+    if (lenStr) {
+      const len = parseInt(lenStr, 10);
+      if (Number.isFinite(len) && len > pdfMaxRequestBytes()) throw tooLarge(len);
+    }
+    const body = await c.req.parseBody({ all: true });
+    const fileField = Array.isArray(body["file"]) ? body["file"][0] : body["file"];
+    if (!(fileField instanceof File)) {
+      throw new ValidationError('multipart field "file" (a PDF) is required');
+    }
+    const file = fileField;
+    if (file.size > config.PDF_MAX_BYTES) throw tooLarge(file.size);
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    if (!isPdf(bytes)) {
+      throw new ValidationError("That file is not a PDF (it does not start with %PDF-).");
+    }
+    const userEmail = await resolveCallerEmail(c.get("userId"));
+    const title = field(body, "title");
+    const tags = tagsField(body);
+    const client = attributeRequest(c, void 0);
+    const pdf = { bytes, filename: file.name || void 0 };
+    const targetId = field(body, "nodeId");
+    if (targetId) {
+      assertSafeNodeId(targetId);
+      const changeNote = field(body, "changeNote") || "Replaced the PDF";
+      const { node: node2, version: version2 } = await updateNode(
+        nestId,
+        targetId,
+        {
+          pdf,
+          ...title ? { title } : {},
+          ...tags ? { tags } : {},
+          changeNote,
+          client
+        },
+        userEmail
+      );
+      return c.json({ node: toNodeResponse(node2), version: version2 });
+    }
+    const folder = field(body, "folder");
+    const { node, version } = await createNode(
+      nestId,
+      {
+        title: title || titleFromFilename(file.name || "") || "Untitled PDF",
+        content: "",
+        type: PDF_NODE_TYPE,
+        ...tags ? { tags } : {},
+        ...folder ? { folder } : {},
+        client,
+        pdf
+      },
+      userEmail
+    );
+    const resolved = await resolveStewardsForNode(nestId, node.id);
+    return c.json(
+      {
+        node: toNodeResponse(node),
+        version,
+        stewards: resolved.length > 0 ? resolved.map((r) => ({
+          email: r.steward.userEmail,
+          role: r.steward.role,
+          source: r.source
+        })) : void 0
+      },
+      201
+    );
+  }
+);
+pdfNodeRoutes.get("/:nodeId{.+}/pdf", async (c, next) => {
+  const nestId = c.req.param("nestId");
+  const nodeId = c.req.param("nodeId");
+  const userId = c.get("userId");
+  const userEmail = await resolveCallerEmail(userId);
+  let node;
+  try {
+    node = await getNodeForCaller(nestId, { id: nodeId }, userId, userEmail);
+  } catch {
+    return next();
+  }
+  if (node.frontmatter.type !== PDF_NODE_TYPE) return next();
+  const requested = c.req.query("version");
+  if (requested !== void 0 && !/^[1-9]\d*$/.test(requested)) {
+    throw new ValidationError("version must be a positive integer");
+  }
+  const approvedOnly = c.req.query("approved_only") === "1" || c.req.query("approved_only") === "true";
+  let version;
+  if (approvedOnly || await isPublicReader(nestId, userId)) {
+    const approved = await getApprovedVersion(nestId, nodeId);
+    if (approved == null) {
+      throw new NotFoundError("This document has no approved version yet.");
+    }
+    version = approved;
+  } else if (requested !== void 0) {
+    version = Number(requested);
+  }
+  const { storage } = await engineCache.get(nestId);
+  let bytes;
+  try {
+    bytes = await readPdfBinary3(
+      storage,
+      nodeId,
+      version !== void 0 ? { version } : {}
+    );
+  } catch (err) {
+    const code = err?.code;
+    if (code === "INTEGRITY_ERROR") {
+      console.error("[pdf] integrity failure serving", nestId, nodeId, version, err);
+      throw new AppError(
+        500,
+        "This PDF no longer matches the version history's record of it, so it is not being served. Ask an admin to verify the nest."
+      );
+    }
+    throw new NotFoundError(
+      version !== void 0 ? `Version ${version} of this PDF was not found.` : "This document's PDF was not found."
+    );
+  }
+  const etag = `"sha256:${createHash3("sha256").update(bytes).digest("hex")}"`;
+  const leaf = (nodeId.split("/").pop() || "document").replace(/[^A-Za-z0-9._-]/g, "-");
+  const disposition = c.req.query("download") === "1" ? "attachment" : "inline";
+  const headers = {
+    "Content-Type": "application/pdf",
+    "Content-Disposition": `${disposition}; filename="${leaf}.pdf"`,
+    "Content-Security-Policy": "sandbox",
+    "X-Content-Type-Options": "nosniff",
+    "Cache-Control": "private, no-cache",
+    ETag: etag
+  };
+  const ifNoneMatch = c.req.header("If-None-Match");
+  if (ifNoneMatch && ifNoneMatch.split(",").map((t) => t.trim()).includes(etag)) {
+    return c.body(null, 304, headers);
+  }
+  return c.body(new Uint8Array(bytes), 200, headers);
+});
+
+// src/auth/community-sites-routes.ts
+import { Hono as Hono23 } from "hono";
 var serverAdminAllowed = async (c) => config.AUTH_MODE === "open" || await isServerAdminUserId(c.get("userId"));
 var isHttpUrl = (v) => /^https?:\/\/\S+$/i.test(v);
 var serializeSite = (site) => ({
@@ -11762,7 +12303,7 @@ var serializeSite = (site) => ({
   created_at: site.created_at,
   updated_at: site.updated_at
 });
-var communitySiteRoutes = new Hono22();
+var communitySiteRoutes = new Hono23();
 communitySiteRoutes.get("/", async (c) => {
   if (!await serverAdminAllowed(c))
     return c.json({ error: "Only the server admin can view this." }, 403);
@@ -11850,7 +12391,7 @@ communitySiteRoutes.delete("/:id", async (c) => {
 });
 
 // src/mcp/server-routes.ts
-import { Hono as Hono23 } from "hono";
+import { Hono as Hono24 } 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";
@@ -11973,116 +12514,39 @@ var NEST_ARG_OPTIONAL = {
     description: "Target nest \u2014 id or name. Omit to search/list across ALL accessible nests."
   }
 };
+var SERVER_NEST_TOOLS = [
+  // Fan-out reads — `nest` optional: omit it to span every accessible nest.
+  ...FANOUT_READ_TOOLS,
+  // Targeted reads and writes — `nest` required.
+  "context_get",
+  "context_resolve",
+  "context_comments",
+  "context_versions",
+  "context_create",
+  "context_update",
+  "context_delete",
+  "context_move",
+  "context_submit_review"
+];
+function withNestArg(tool) {
+  const fanout = FANOUT_READ_TOOLS.has(tool.name);
+  const schema = tool.inputSchema;
+  return {
+    name: tool.name,
+    description: fanout ? `${tool.description} On this server-level endpoint, omit \`nest\` to run it across ALL accessible nests (each hit names its nest).` : `${tool.description} On this server-level endpoint, \`nest\` (id, name or slug) is required.`,
+    inputSchema: {
+      ...schema,
+      properties: { ...fanout ? NEST_ARG_OPTIONAL : NEST_ARG, ...schema.properties },
+      required: [...fanout ? [] : ["nest"], ...schema.required ?? []]
+    }
+  };
+}
 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.",
     inputSchema: { type: "object", properties: {} }
   },
-  // ─── Fan-out reads (nest optional) ─────────────────────────────────────
-  {
-    name: "context_query",
-    description: "Run a structured selector query. Omit `nest` to query ALL accessible nests. Selector: #tag, type:X, [[Title]], scope:X, +AND, |OR, -NOT.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...NEST_ARG_OPTIONAL,
-        query: { type: "string", description: "Selector query" },
-        hops: {
-          type: "number",
-          description: "Graph traversal depth from the matches (default: 2)"
-        }
-      },
-      required: ["query"]
-    }
-  },
-  {
-    name: "context_search",
-    description: "Full-text keyword search. Omit `nest` to search ALL accessible nests. Returns count and first `limit` hits.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...NEST_ARG_OPTIONAL,
-        query: { type: "string", description: "Search terms" },
-        limit: {
-          type: "number",
-          description: "Max hits to return (default 20, max 200)"
-        }
-      },
-      required: ["query"]
-    }
-  },
-  {
-    name: "context_list",
-    description: "Browse contents with optional type, tag, or limit filters. Omit `nest` to list ALL accessible nests.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...NEST_ARG_OPTIONAL,
-        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_overview",
-    description: "Map of nests: node count, types, tags, title+snippet per node. Omit `nest` for ALL accessible nests.",
-    inputSchema: {
-      type: "object",
-      properties: { ...NEST_ARG_OPTIONAL }
-    }
-  },
-  // ─── Targeted reads (nest required) ────────────────────────────────────
-  {
-    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_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"]
-    }
-  },
-  {
-    // Read-only, so it belongs on this endpoint: an agent reading a nest's
-    // documents across nests also needs the feedback left on them. Writing a
-    // comment stays on the per-nest endpoint with the other write tools.
-    name: "context_comments",
-    description: "Get the review comments/annotations on a document in a nest \u2014 anchored quotes, threaded replies, and open/resolved status. Use to pull human feedback into context before acting on a document.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        nest: { type: "string", description: "Nest name or id (see nest_index)" },
-        title: { type: "string", description: "Title of the node" },
-        id: { type: "string", description: "ID of the node" }
-      },
-      required: ["nest"]
-    }
-  },
   {
     name: "nest_create",
     description: "Create a new nest owned by the caller. Returns the new nest's id \u2014 target it with the other tools afterwards.",
@@ -12095,93 +12559,18 @@ var SERVER_TOOL_DEFINITIONS = [
       required: ["name"]
     }
   },
-  // ─── Writes (nest required) ────────────────────────────────────────────
-  {
-    name: "context_create",
-    description: "Create a new document in a nest. Needs write permission. A `folder` path creates the folder implicitly.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...NEST_ARG,
-        title: { type: "string", description: "Descriptive title" },
-        content: { type: "string", description: "Markdown content body" },
-        type: { type: "string", description: "Node type (default: document)" },
-        tags: { type: "array", items: { type: "string" }, description: "Tags" },
-        scope: { type: "string", description: "Visibility scope" },
-        folder: {
-          type: "string",
-          description: 'Folder path under nodes/ (e.g. "gtm/deals"); segments are slugified'
-        }
-      },
-      required: ["nest", "title", "content"]
-    }
-  },
-  {
-    name: "context_update",
-    description: "Update an existing node by title or id. Needs write permission. Use `content` to replace, `append` to add.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...NEST_ARG,
-        title: { type: "string", description: "Title of node to update" },
-        id: { type: "string", description: "Node id (use when title is ambiguous)" },
-        content: { type: "string", description: "New content (replaces)" },
-        append: { type: "string", description: "Content to append" },
-        tags: { type: "array", items: { type: "string" }, description: "Tags to add" },
-        status: { type: "string", description: "New status: draft|pending_review|approved|published" },
-        changeNote: { type: "string", description: "Why this changed \u2014 recorded in history" }
-      },
-      required: ["nest"]
-    }
-  },
-  {
-    name: "context_delete",
-    description: "Delete a node by title or id. Needs write permission. Irreversible.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...NEST_ARG,
-        title: { type: "string", description: "Title of node to delete" },
-        id: { type: "string", description: "Node id (use when title is ambiguous)" }
-      },
-      required: ["nest"]
-    }
-  },
-  {
-    name: "context_move",
-    description: "Move a node to a different folder. The id changes; history and links follow. Needs write permission.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...NEST_ARG,
-        title: { type: "string", description: "Title of node to move" },
-        id: { type: "string", description: "Node id (use when title is ambiguous)" },
-        folder: { type: "string", description: 'Destination folder (e.g. "gtm/deals"); "" for root' }
-      },
-      required: ["nest", "folder"]
-    }
-  },
-  {
-    name: "context_submit_review",
-    description: "Submit a node for steward review. Stewards will be notified. Use on governed nests.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...NEST_ARG,
-        title: { type: "string", description: "Title of node to submit" },
-        id: { type: "string", description: "Node id (use when title is ambiguous)" },
-        note: { type: "string", description: "Note for the reviewer" },
-        priority: { type: "string", description: "Priority: low, normal, high, urgent" }
-      },
-      required: ["nest"]
-    }
-  }
+  ...SERVER_NEST_TOOLS.map((name) => {
+    const tool = TOOL_DEFINITIONS.find((t) => t.name === name);
+    if (!tool) throw new Error(`server-level tool ${name} has no per-nest definition`);
+    return withNestArg(tool);
+  })
 ];
-async function handleServerToolCall(toolName, args, userId, userEmail, nestScope, baseUrl) {
+async function handleServerToolCall(toolName, args, userId, userEmail, nestScope, baseUrl, client) {
   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 data = { nests };
+    if (!nests.length) return { text: "No nests accessible with these credentials.", data };
+    return { text: renderNestIndexMarkdown(nests, baseUrl), data };
   }
   if (SERVER_WRITE_TOOLS.has(toolName)) {
     if (isSuspended()) {
@@ -12213,9 +12602,6 @@ async function handleServerToolCall(toolName, args, userId, userEmail, nestScope
     const nests = await buildNestIndex(userId, nestScope);
     if (!nests.length) return "No nests accessible with these credentials.";
     const nonEmpty = nests.filter((n) => (n.document_count ?? 0) > 0);
-    if (!nonEmpty.length) {
-      return "All accessible nests are empty. Use context_create to add documents first.";
-    }
     const results = await Promise.allSettled(
       nonEmpty.map(async (n) => {
         const engine2 = await engineCache.get(n.id);
@@ -12226,25 +12612,66 @@ async function handleServerToolCall(toolName, args, userId, userEmail, nestScope
           nestId: n.id,
           userId,
           userEmail,
-          baseUrl
+          baseUrl,
+          // Same attribution the single-nest branch below passes (§9.4). A
+          // fan-out read is still one call per nest on the trace, and each row
+          // has to name the caller — without this the derived agent/session is
+          // dropped and only an explicit `client` in the args survives.
+          client
         });
         return { nest: n, result };
       })
     );
     const parts = [];
+    let firstError;
+    let firstRejection;
+    const tag = (n, items) => Array.isArray(items) ? items.map((it) => ({ ...it, nest: { id: n.id, name: n.name } })) : [];
+    const perNestDocs = [];
+    const perNestHits = [];
+    let count = 0;
+    let nodesTraversed = 0;
+    let hopsUsed = 0;
+    let mode;
     for (const r of results) {
-      if (r.status === "fulfilled") {
-        const { nest: n, result } = r.value;
-        const text = typeof result === "string" ? result : result.text;
-        parts.push(`## ${n.name} (${n.id})
-
-${text}`);
+      if (r.status !== "fulfilled") {
+        firstRejection ??= r;
+        continue;
       }
+      const { nest: n, result } = r.value;
+      if (typeof result !== "string" && result.isError) {
+        firstError ??= result;
+        continue;
+      }
+      parts.push(`## ${n.name} (${n.id})
+
+${typeof result === "string" ? result : result.text}`);
+      const d = typeof result === "string" ? void 0 : result.data;
+      if (!d) continue;
+      perNestDocs.push(tag(n, d.documents));
+      perNestHits.push(tag(n, d.results));
+      count += d.count ?? 0;
+      nodesTraversed += d.traversal?.nodes_traversed ?? 0;
+      hopsUsed = Math.max(hopsUsed, d.traversal?.hops_used ?? 0);
+      mode ??= d.traversal?.mode;
     }
-    if (!parts.length) {
-      return "No results found across any accessible nests.";
+    const interleave = (lists) => {
+      const out = [];
+      for (let i = 0; lists.some((l) => i < l.length); i++) {
+        for (const l of lists) if (i < l.length) out.push(l[i]);
+      }
+      return out;
+    };
+    if (!parts.length && firstError) return firstError;
+    if (!parts.length && firstRejection) throw firstRejection.reason;
+    const documents = interleave(perNestDocs);
+    const listLimit = typeof args.limit === "number" && args.limit >= 1 ? Math.floor(args.limit) : 50;
+    const data = toolName === "context_search" ? { results: interleave(perNestHits).slice(0, normalizeSearchLimit(args.limit)), count } : toolName === "context_query" ? { documents, traversal: { mode: mode ?? "selector", hops_used: hopsUsed, nodes_traversed: nodesTraversed } } : { documents: documents.slice(0, listLimit) };
+    const reply = (text) => toolName === "context_overview" ? text : { text, data };
+    if (!nonEmpty.length) {
+      return reply("All accessible nests are empty. Use context_create to add documents first.");
     }
-    return parts.join("\n\n---\n\n");
+    if (!parts.length) return reply("No results found across any accessible nests.");
+    return reply(parts.join("\n\n---\n\n"));
   }
   const inaccessible = `Nest not found or not accessible: "${nestArg}". Use nest_index to see what these credentials can read.`;
   if (!nestArg) {
@@ -12262,10 +12689,11 @@ ${text}`);
     nestId: nest.id,
     userId,
     userEmail,
-    baseUrl
+    baseUrl,
+    client
   });
 }
-function createServerMcp(userId, userEmail, nestScope, baseUrl) {
+function createServerMcp(userId, userEmail, nestScope, baseUrl, c) {
   const server = new McpServer2(
     { name: "contextnest-server", version: "1.0.0" },
     { capabilities: { tools: {} } }
@@ -12275,14 +12703,15 @@ function createServerMcp(userId, userEmail, nestScope, baseUrl) {
     const required = tool.inputSchema.required || [];
     const shape = {};
     for (const [key, def] of Object.entries(props)) {
-      let field;
-      if (def.type === "string") field = z2.string();
-      else if (def.type === "number") field = z2.number();
-      else if (def.type === "array") field = z2.array(z2.string());
-      else field = z2.any();
-      if (!required.includes(key)) field = field.optional();
-      shape[key] = field;
-    }
+      let field2;
+      if (def.type === "string") field2 = z2.string();
+      else if (def.type === "number") field2 = z2.number();
+      else if (def.type === "array") field2 = z2.array(z2.string());
+      else field2 = z2.any();
+      if (!required.includes(key)) field2 = field2.optional();
+      shape[key] = field2;
+    }
+    Object.assign(shape, clientToolField);
     server.tool(tool.name, tool.description, shape, async (args) => {
       const out = await handleServerToolCall(
         tool.name,
@@ -12290,14 +12719,15 @@ function createServerMcp(userId, userEmail, nestScope, baseUrl) {
         userId,
         userEmail,
         nestScope,
-        baseUrl
+        baseUrl,
+        attributeRequest(c, void 0, connectionClient(server))
       );
       return toCallToolResult(out);
     });
   }
   return server;
 }
-var serverMcpRoutes = new Hono23();
+var serverMcpRoutes = new Hono24();
 serverMcpRoutes.all("/", async (c) => {
   const userId = c.get("userId");
   const userEmail = await getUserEmail3(userId);
@@ -12305,7 +12735,8 @@ serverMcpRoutes.all("/", async (c) => {
     userId,
     userEmail,
     c.get("nestScope"),
-    requestBaseUrl(c.req.url)
+    requestBaseUrl(c.req.url),
+    c
   );
   const transport = new WebStandardStreamableHTTPServerTransport2({
     sessionIdGenerator: void 0,
@@ -12319,7 +12750,7 @@ serverMcpRoutes.all("/", async (c) => {
     await server.server.close();
   }
 });
-var nestIndexRoutes = new Hono23();
+var nestIndexRoutes = new Hono24();
 nestIndexRoutes.get("/", async (c) => {
   const userId = c.get("userId");
   const nests = await buildNestIndex(userId, c.get("nestScope"));
@@ -12413,6 +12844,20 @@ Write endpoints (need write permission):
 - \`GET ${B}/me/drafts\` \u2014 your documents never submitted for review
 - \`GET ${B}/me/notifications\` \u2014 watcher and review notifications
 
+## Say who you are: \`client\`
+
+Every write body and every MCP tool call takes an optional
+\`client\` object \u2014 \`{ "agent": "claude-code", "session_id": "s-9f2" }\`, plus any
+custom scalar keys. A write that seals a version records it on that version
+(\`GET /nodes/<id>/versions\` and \`context_versions\` serve it back); every call
+records it on this server's activity trace, which is how a READ gets attributed.
+
+Send it. Nothing requires it and no call is refused for omitting it, but a vault
+serving several agents cannot otherwise tell which of you wrote what. It is a
+label, never an identity claim: it is not authenticated, grants nothing, and is
+never part of a hash. Bounded \u2014 scalar values up to 512 chars, at most 16 custom
+keys beyond \`agent\` and \`session_id\`.
+
 ## MCP (Model Context Protocol)
 
 Streamable HTTP, stateless. Two endpoints:
@@ -12421,7 +12866,7 @@ Streamable HTTP, stateless. Two endpoints:
   Tools: \`nest_index\` (call first), then:
   - Fan-out reads (omit \`nest\` to search/list ALL nests): \`context_search\`,
     \`context_list\`, \`context_query\`, \`context_overview\`
-  - Targeted reads (\`nest\` required): \`context_get\`, \`context_resolve\`, \`context_comments\`
+  - Targeted reads (\`nest\` required): \`context_get\`, \`context_resolve\`, \`context_comments\`, \`context_versions\`
   - Writes (\`nest\` required): \`nest_create\`, \`context_create\`, \`context_update\`,
     \`context_delete\`, \`context_move\`, \`context_submit_review\`
 - \`${B}/nests/<nest-id>/mcp\` \u2014 per-nest, the full toolset. Same names as the
@@ -12458,9 +12903,11 @@ on the command line.
 export CONTEXTNEST_API_KEY=<api-key>
 # every nest these credentials can read, through the server-level endpoint
 ctx vault add contextnest --url ${B}/mcp --bearer-env CONTEXTNEST_API_KEY
-# or one nest
+ctx vault list                                  # lists contextnest/<nest> for each nest
+ctx search "pricing" --vault contextnest        # reads span every nest
+ctx update nodes/x --tags a,b --vault contextnest/<nest>   # a write names one nest
+# or pin one nest by its own endpoint
 ctx vault add mynest --url ${B}/nests/<nest-id>/mcp --bearer-env CONTEXTNEST_API_KEY
-ctx query "#gtm" --vault mynest
 \`\`\`
 
 Servers in "open" auth mode: drop \`--bearer-env\`. Pushing a local folder up
@@ -12479,14 +12926,14 @@ is \`ctx push --server ${B} --nest <nest-id>\` with the same env var set.
   through steward review before they become AI-visible.
 `;
 }
-var llmsTxtRoutes = new Hono23();
+var llmsTxtRoutes = new Hono24();
 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 Hono24 } from "hono";
+import { Hono as Hono25 } from "hono";
 
 // src/governance/feed-service.ts
 var SNIPPET_CHARS = 200;
@@ -12918,7 +13365,7 @@ function parseLimit(raw, def = 100, max = 1e3) {
   if (Number.isNaN(n) || n < 1) return def;
   return Math.min(n, max);
 }
-var governanceRoutes = new Hono24();
+var governanceRoutes = new Hono25();
 governanceRoutes.get("/stewards", async (c) => {
   const nestId = c.req.param("nestId");
   const scope = c.req.query("scope");
@@ -13058,6 +13505,7 @@ governanceRoutes.post("/review-queue/bulk", async (c) => {
   }
   const userEmail = await getUserEmail4(c);
   const baseUrl = requestBaseUrl(c.req.url);
+  const client = attributeRequest(c, body.client);
   const results = [];
   for (const nodeId of nodeIds) {
     try {
@@ -13068,7 +13516,8 @@ governanceRoutes.post("/review-queue/bulk", async (c) => {
           approvedBy: userEmail,
           note: body.note,
           override: false,
-          baseUrl
+          baseUrl,
+          client
         });
       } else {
         await reject({
@@ -13286,7 +13735,7 @@ governanceRoutes.get("/activity", async (c) => {
   const activity = await getActivity({ nestId, limit });
   return c.json({ activity });
 });
-var governanceNodeRoutes = new Hono24();
+var governanceNodeRoutes = new Hono25();
 governanceNodeRoutes.get("/:nodeId{.+}/stewards", async (c) => {
   const nestId = c.req.param("nestId");
   const nodeId = c.req.param("nodeId");
@@ -13492,7 +13941,10 @@ governanceNodeRoutes.post("/:nodeId{.+}/submit-review", async (c) => {
       requestedBy: userEmail,
       note: body.note,
       priority: body.priority,
-      baseUrl: requestBaseUrl(c.req.url)
+      baseUrl: requestBaseUrl(c.req.url),
+      // Submitting seals the draft into the engine's append-only chain, so the
+      // block lands on that entry as well as on this request's trace row.
+      client: attributeRequest(c, body.client)
     });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -13626,7 +14078,8 @@ governanceNodeRoutes.post("/:nodeId{.+}/approve", async (c) => {
       approvedBy: userEmail,
       note: body.note,
       override: body.override && isAdmin,
-      baseUrl: requestBaseUrl(c.req.url)
+      baseUrl: requestBaseUrl(c.req.url),
+      client: attributeRequest(c, body.client)
     });
     return c.json({ review: request });
   } catch (err) {
@@ -13641,6 +14094,7 @@ governanceNodeRoutes.post("/:nodeId{.+}/reject", async (c) => {
     throw new ValidationError("Rejection note is required");
   }
   const userEmail = await getUserEmail4(c);
+  attributeRequest(c, body.client);
   try {
     const request = await reject({
       nestId,
@@ -13753,6 +14207,26 @@ function posthogKeyError(value) {
   return null;
 }
 
+// src/shared/public-base-url.ts
+var UNSAFE = /["'`\\$;|&<>(){}\s]/;
+function publicBaseUrlError(value) {
+  const v = value.trim();
+  if (!v) return null;
+  let parsed;
+  try {
+    parsed = new URL(v);
+  } catch {
+    return "Public base URL must be a full http(s) URL, e.g. https://nest.example.com";
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+    return "Public base URL must use http or https, e.g. https://nest.example.com";
+  if (!parsed.hostname)
+    return "Public base URL must include a hostname, e.g. https://nest.example.com";
+  if (UNSAFE.test(v))
+    return "Public base URL must not contain spaces, quotes or shell characters (\" ' ` \\ $ ; | & < > ( ) { }) \u2014 it is pasted into terminal commands and config files.";
+  return null;
+}
+
 // src/app.ts
 import { serveStatic } from "@hono/node-server/serve-static";
 import { fileURLToPath } from "url";
@@ -13802,7 +14276,10 @@ var flexAuthMiddleware = createMiddleware2(async (c, next) => {
     c.set("nestScope", null);
     return next();
   }
-  return c.json({ error: "Missing or invalid credentials" }, 401);
+  return c.json(
+    { error: "Authentication required \u2014 sign in or provide an API key.", code: "missing_credentials" },
+    401
+  );
 });
 function nestPathParts(path) {
   return path.replace(/^\/nests\//, "").split("/").filter(Boolean);
@@ -13820,14 +14297,24 @@ var flexAuthWithPromptowlTicket = createMiddleware2(
       return flexAuthMiddleware(c, next);
     }
     let claims = null;
+    let expired = false;
     for (const secret of secrets) {
       try {
         claims = verifySsoTicket(token, secret);
         break;
-      } catch {
+      } catch (err) {
+        if (err instanceof SsoTokenError && err.message === "Ticket expired") {
+          expired = true;
+        }
       }
     }
     if (!claims) {
+      if (expired) {
+        return c.json(
+          { error: "Service ticket expired \u2014 reconnect to refresh.", code: "ticket_expired" },
+          401
+        );
+      }
       return c.json({ error: "Invalid service ticket" }, 401);
     }
     if (claims.scope !== "mcp" || claims.jti) {
@@ -13874,7 +14361,7 @@ async function canApproveInNest(nestId, email) {
   return ok;
 }
 function createApp() {
-  const app = new Hono25({ router: new LinearRouter() });
+  const app = new Hono26({ router: new LinearRouter() });
   const corsOrigins = config.CORS_ORIGINS;
   app.use(
     "*",
@@ -13892,7 +14379,8 @@ function createApp() {
     const lenStr = c.req.header("Content-Length");
     if (lenStr) {
       const len = parseInt(lenStr, 10);
-      const cap = c.req.method === "POST" && ASSET_UPLOAD_PATH.test(c.req.path) ? Math.max(config.MAX_BODY_BYTES, ASSET_MAX_REQUEST_BYTES) : config.MAX_BODY_BYTES;
+      const isPost = c.req.method === "POST";
+      const cap = isPost && ASSET_UPLOAD_PATH.test(c.req.path) ? Math.max(config.MAX_BODY_BYTES, ASSET_MAX_REQUEST_BYTES) : isPost && PDF_UPLOAD_PATH.test(c.req.path) ? Math.max(config.MAX_BODY_BYTES, pdfMaxRequestBytes()) : config.MAX_BODY_BYTES;
       if (Number.isFinite(len) && len > cap) {
         return c.json(
           {
@@ -13917,7 +14405,10 @@ function createApp() {
       nestId: /^\/nests\/([^/]+)/.exec(path)?.[1] ?? null,
       userId: c.get("userId") ?? null,
       status: c.res.status,
-      durationMs: Date.now() - started
+      durationMs: Date.now() - started,
+      // Set by whichever handler validated the request's `client` block
+      // (§9.4). Absent on a request that sent none.
+      client: c.get("clientMetadata")
     });
   });
   app.get("/health", (c) => {
@@ -13962,6 +14453,11 @@ function createApp() {
       // API would refuse it — existing nodes of the type stay readable.
       type_artifact_enabled: config.TYPE_ARTIFACT_ENABLED,
       type_table_enabled: config.TYPE_TABLE_ENABLED,
+      // This server hosts several organizations (PromptOwl-hosted) rather than
+      // one. The visibility picker words 'Organization' and 'Public' by it and
+      // confirms before 'org'; the server enforces the same in
+      // PATCH /nests/:id/visibility.
+      shared_deployment: config.SHARED_DEPLOYMENT,
       // 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.
@@ -14085,6 +14581,7 @@ function createApp() {
     oidc_auto_provision: config.OIDC_AUTO_PROVISION,
     oidc_department_tagging: config.OIDC_DEPARTMENT_TAGGING,
     people_suggest_all_users: config.PEOPLE_SUGGEST_ALL_USERS,
+    shared_deployment: config.SHARED_DEPLOYMENT,
     // Agent SSO / token-exchange. MCP_SIGNING_SECRET is WRITE-ONLY — only its
     // presence is reported, never the value (same discipline as the OIDC secret).
     sso_token_exchange_enabled: config.SSO_TOKEN_EXCHANGE_ENABLED,
@@ -14137,8 +14634,8 @@ function createApp() {
       return c.json({ error: "Invalid JSON body" }, 400);
     }
     const fieldErrors = {};
-    const addError = (field, message) => {
-      fieldErrors[field] = message;
+    const addError = (field2, message) => {
+      fieldErrors[field2] = message;
     };
     const pending = [];
     if ("promptowl_sign_in_gate" in body) {
@@ -14159,7 +14656,9 @@ function createApp() {
     }
     if ("public_base_url" in body) {
       const v = String(body.public_base_url ?? "").trim().replace(/\/$/, "");
-      pending.push({ name: "PUBLIC_BASE_URL", value: v || null });
+      const err = v ? publicBaseUrlError(v) : null;
+      if (err) addError("public_base_url", err);
+      else pending.push({ name: "PUBLIC_BASE_URL", value: v || null });
     }
     if ("telemetry_enabled" in body) {
       pending.push({ name: "TELEMETRY_ENABLED", value: body.telemetry_enabled ? "true" : "false" });
@@ -14313,6 +14812,12 @@ function createApp() {
         value: body.people_suggest_all_users ? "true" : null
       });
     }
+    if ("shared_deployment" in body) {
+      pending.push({
+        name: "SHARED_DEPLOYMENT",
+        value: body.shared_deployment ? "true" : null
+      });
+    }
     if ("sso_token_exchange_enabled" in body) {
       pending.push({
         name: "SSO_TOKEN_EXCHANGE_ENABLED",
@@ -14363,13 +14868,13 @@ function createApp() {
     const effAllowedDomains = "oidc_allowed_domains" in body ? String(body.oidc_allowed_domains ?? "").split(",").map((d) => d.trim()).filter(Boolean) : config.OIDC_ALLOWED_DOMAINS;
     const effAutoProvision = "oidc_auto_provision" in body ? !!body.oidc_auto_provision : config.OIDC_AUTO_PROVISION;
     if (effAutoProvision && effAllowedDomains.length === 0) {
-      for (const field of [
+      for (const field2 of [
         "ms_token_exchange_enabled",
         "google_token_exchange_enabled"
       ]) {
-        if (body[field])
+        if (body[field2])
           addError(
-            field,
+            field2,
             "Set allowed email domains (or turn auto-provision off) before enabling token exchange \u2014 otherwise anyone with an account at that provider can sign themselves up and mint a token."
           );
       }
@@ -14819,7 +15324,7 @@ function createApp() {
   app.route("/index", nestIndexRoutes);
   app.use("/mcp", flexAuthWithPromptowlTicket);
   app.route("/mcp", serverMcpRoutes);
-  const nestsApp = new Hono25();
+  const nestsApp = new Hono26();
   nestsApp.use("*", async (c, next) => {
     const parts = nestPathParts(c.req.path);
     const ticketEligible = parts.length === 2 && (c.req.method === "POST" && parts[1] === "context" || c.req.method === "GET" && parts[1] === "nodes" || parts[1] === "mcp");
@@ -14976,7 +15481,9 @@ function createApp() {
         stewardEditorBypass = resolved.some(
           (r) => r.steward.userEmail.toLowerCase() === userEmail.toLowerCase() && r.steward.role === "editor"
         );
-      } else if (parts.length === 2 && c.req.method === "POST") {
+      } else if (c.req.method === "POST" && // POST /nodes (create) and POST /nodes/pdf (PDF upload — a create, or
+      // a new version of a pdf node) share the nest-scope editor rule.
+      (parts.length === 2 || parts.length === 3 && parts[2] === "pdf")) {
         const resolved = await resolveStewardsForNode(nestId, "");
         stewardEditorBypass = resolved.some(
           (r) => r.steward.userEmail.toLowerCase() === userEmail.toLowerCase() && r.steward.role === "editor" && r.steward.scope === "nest"
@@ -15038,6 +15545,7 @@ function createApp() {
   });
   nestsApp.route("/", nestRoutes);
   nestsApp.route("/:nestId", governanceRoutes);
+  nestsApp.route("/:nestId/nodes", pdfNodeRoutes);
   nestsApp.route("/:nestId/nodes", annotationRoutes);
   nestsApp.route("/:nestId/nodes", governanceNodeRoutes);
   nestsApp.route("/:nestId/nodes", nodeRoutes);