@promptowl/contextnest-community 1.19.0 → 1.20.0

package/CONFIGURATION.md

@@ -60,7 +60,7 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 | `PROMPTOWL_SIGN_IN_GATE` | `open` | Restrict "Sign in with PromptOwl". `open` = anyone may; `admin-only` = only the license owner (admin) may, everyone else uses email/password (admin opens the login page with `?admin=1`); `disabled` = nobody may. Enforced server-side at `POST /auth/promptowl` and surfaced on the health endpoint. Unknown values fall back to `open`. |
 | `MANUAL_SIGN_IN` | `open` | Email + password sign-in mode. `open` = anyone may log in and self-register a new account; `invite-only` = existing/invited users may log in but brand-new self-registration returns `403` (the admin provisions accounts via invite/share/steward and shares the password — there is no self-service "set password", which would be account takeover without email verification); `disabled` = no email/password sign-in at all (`POST /auth/login` and `POST /auth/register` return `403`). Independent of `PROMPTOWL_SIGN_IN_GATE`, so the two methods are controlled separately (e.g. `invite-only` manual + `admin-only` PromptOwl). Also settable from Settings → General. The server refuses `disabled` while PromptOwl sign-in is also `disabled` (that would leave no way to log in). Unknown values fall back to `open`. |
 | `OFFICIAL_COMMUNITY_SSO_SECRET` | `""` | **Official deployment only — leave unset on self-hosted.** Shared HMAC secret enabling the one-click "Open Community" SSO auto-login from PromptOwl. Must exactly match the same-named var on PromptOwl. When unset, `GET /auth/sso` returns `404` and the feature is disabled; self-hosted users keep using the manual device-code flow. |
-| `PUBLIC_BASE_URL` | `""` | This server's canonical external URL (e.g. `https://community.promptowl.ai`). Three uses. (1) Checked against the SSO ticket's `aud` claim so a ticket minted for this server can't be replayed against another — only when `OFFICIAL_COMMUNITY_SSO_SECRET` is set; when unset, the audience check is skipped. (2) **Set this whenever `OIDC_ENABLED=true`.** It's the base for the OIDC `redirect_uri` sent to your IdP and replayed at token exchange. Unset, that URI is derived from the incoming request's `Host` header — fine when your proxy overwrites `Host` with a trusted value, but a proxy that passes an attacker-supplied `Host` through would feed it straight into the redirect URI. Setting this pins the value regardless of what the proxy forwards. (Your IdP's own redirect-URI allowlist is a second line of defence, not a substitute.) (3) **Set this wherever `POST /nests/:id/context` citations reach users.** The `url` on each node and the `_source:` line in each context block are built from it; unset, they fall back to the request origin, so a proxy forwarding an untrusted `Host` would put an attacker-influenced URL in front of both the model and the reader as a trustworthy citation. |
+| `PUBLIC_BASE_URL` | `""` | This server's canonical external URL (e.g. `https://community.promptowl.ai`). Two uses. (1) Checked against the SSO ticket's `aud` claim so a ticket minted for this server can't be replayed against another — whenever a ticket-signing secret is set (`OFFICIAL_COMMUNITY_SSO_SECRET` on the official deployment, `MCP_SIGNING_SECRET` on a self-hosted one); with neither set no ticket verifies at all, so the audience check is moot. (2) **Set this whenever `OIDC_ENABLED=true`.** It's the base for the OIDC `redirect_uri` sent to your IdP and replayed at token exchange. Unset, that URI is derived from the incoming request's `Host` header — fine when your proxy overwrites `Host` with a trusted value, but a proxy that passes an attacker-supplied `Host` through would feed it straight into the redirect URI. Setting this pins the value regardless of what the proxy forwards. (Your IdP's own redirect-URI allowlist is a second line of defence, not a substitute.) (3) **Set this wherever email- or invite-gated publish links are used.** The magic link mailed by `POST /p/:slug/gate` is built from it; unset, it falls back to the request origin, so a proxy forwarding an attacker-supplied `Host` would send the recipient a one-time access token pointing at the attacker's domain — the classic reset-link poisoning. (4) **Set this wherever `POST /nests/:id/context` citations reach users.** The `url` on each node and the `_source:` line in each context block are built from it; unset, they fall back to the request origin, so a proxy forwarding an untrusted `Host` would put an attacker-influenced URL in front of both the model and the reader as a trustworthy citation. |
 | `OIDC_ENABLED` | `false` | Turn on generic OIDC single sign-on (`GET /auth/oidc/login` / `GET /auth/oidc/callback`). Requires `OIDC_ISSUER`, `OIDC_CLIENT_ID`, and `OIDC_CLIENT_SECRET` — the login-page button only appears once all three are set. Also editable from Settings → Single sign-on. See [Single sign-on (OIDC)](#single-sign-on-oidc). |
 | `OIDC_ISSUER` | `""` | OIDC issuer URL, e.g. `https://login.microsoftonline.com/<tenant>/v2.0` (Microsoft Entra ID) or `https://accounts.google.com` (Google). **`https://` only** — a non-https value is rejected with a warning and SSO stays off. Must serve `<issuer>/.well-known/openid-configuration`. |
 | `OIDC_CLIENT_ID` | `""` | Application (client) ID from your IdP app registration. |
@@ -68,6 +68,11 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 | `OIDC_ALLOWED_DOMAINS` | `""` (any) | Comma-separated email-domain allowlist, e.g. `acme.com, contractors.acme.com`. When set, only accounts whose asserted email is on a listed domain may sign in (others bounce with `domain_not_allowed`). Empty allows any domain the IdP asserts. |
 | `OIDC_AUTO_PROVISION` | `true` | Create a user automatically on first successful OIDC sign-in (display name from the `name` claim). Set `false` to allow only pre-existing (invited/registered) users — unknown emails bounce with `not_invited`. |
 | `OIDC_DEPARTMENT_TAGGING` | `false` | Auto-tag newly **created** documents with the creator's directory department: `dept:<slugified-department>` (lowercase, spaces → dashes, e.g. `dept:customer-success`) is appended to the document's tags, deduped against user-supplied tags. Applies on create only — never on update, never retroactively — and a user without a stored department is a silent no-op. The department is captured from the OIDC `department` ID-token claim on every SSO login (a login without the claim clears it, so directory moves propagate), so this is only meaningful when your IdP emits that claim — see [Department auto-tagging](#department-auto-tagging). Also editable from Settings → Single sign-on. |
+| `SSO_TOKEN_EXCHANGE_ENABLED` | `false` | Master switch for `POST /auth/token-exchange` — an external agent exchanges an IdP ID token for a short-lived MCP bearer. Also needs `MCP_SIGNING_SECRET` and at least one provider; otherwise the endpoint returns `404`. Security-critical — see [Agent SSO (token exchange)](#agent-sso-token-exchange). |
+| `MCP_SIGNING_SECRET` | `""` | HMAC secret **this** server signs its minted MCP bearers with (distinct from `OFFICIAL_COMMUNITY_SSO_SECRET`, so self-hosted deployments can issue their own). Long random string. `/index` and `/mcp` accept a ticket signed with either secret. Write-only on the Settings API. **Clearing it is the revocation switch** — turning `SSO_TOKEN_EXCHANGE_ENABLED` off stops minting but already-minted bearers stay valid until they expire. |
+| `MCP_TOKEN_TTL_SECONDS` | `300` | Lifetime of a minted MCP bearer, clamped to 30–3600. |
+| `MS_TOKEN_EXCHANGE_ENABLED` / `MS_CLIENT_ID` / `MS_TENANT_ID` | `false` / `""` / `""` | Microsoft Entra provider. `MS_CLIENT_ID` is the audience an inbound token must carry; `MS_TENANT_ID` must be the directory **GUID** (it builds the required issuer `https://login.microsoftonline.com/<tenant>/v2.0` — `common`/`organizations`/a domain name will not match the discovery document and every exchange returns `provider_misconfigured`). |
+| `GOOGLE_TOKEN_EXCHANGE_ENABLED` / `GOOGLE_CLIENT_ID` | `false` / `""` | Google provider. Issuer is fixed (`https://accounts.google.com`); `GOOGLE_CLIENT_ID` is the audience an inbound token must carry. |
 | `ENV_FILE_PATH` | `$DATA_ROOT/.env` | Path to an optional `.env` file the server reads at boot (in addition to `$cwd/.env`). **No longer used for persistence** — the License Setup Page and Settings page now write to the database, not this file (see [Runtime settings persistence](#runtime-settings-persistence)). Kept for operators who bootstrap config from a mounted `.env`. |
 | `TELEMETRY_ENABLED` | `"true"` (set to `"false"` to disable) | Batched, anonymized usage events sent to PromptOwl. Off disables the loop entirely. |
 | `TELEMETRY_INTERVAL_MS` | `3600000` (1 hour) | How often buffered telemetry is flushed to PromptOwl. |
@@ -264,6 +269,83 @@ a toast; codes: `disabled`, `not_configured`, `discovery_failed`,
 
 ---
 
+## Agent SSO (token exchange)
+
+`POST /auth/token-exchange` lets an external agent, acting for a user your IdP
+(Microsoft Entra / Google) has **already** authenticated, exchange that IdP's ID
+token for a short-lived MCP bearer — no second login, no static API key.
+RFC 8693-shaped. **Off by default and security-critical**: it trusts a token
+minted elsewhere and hands back access, so read this section before enabling it.
+
+Configure it with the `SSO_TOKEN_EXCHANGE_ENABLED` / `MCP_SIGNING_SECRET` /
+`MS_*` / `GOOGLE_*` vars above, or from **Settings → Single sign-on → Agent SSO**
+(superadmin). It reuses `OIDC_ALLOWED_DOMAINS` and `OIDC_AUTO_PROVISION` — the
+same who-may-sign-in policy as browser login.
+
+**Who this is for — and who it is not.** The minted bearer is short-lived by
+design (`MCP_TOKEN_TTL_SECONDS`, default 300s, hard ceiling 3600s), and there is
+no refresh token: renewal means calling `POST /auth/token-exchange` again with
+the IdP token. So this fits a **programmatic** client — an agent runtime, a
+backend service, a desktop app that already did an MSAL/Google sign-in — that
+can re-exchange in code before a session or on a `401`, with no human involved.
+
+It does **not** fit a client whose credential is typed once into a config file
+(Claude Desktop, Cursor, any `mcpServers` JSON block): nothing here rewrites that
+file, and the ceiling is an hour, so the connection would break repeatedly. Those
+clients keep using a long-lived API key (`cnst_…`) — this endpoint is additive
+and changes nothing about API-key or browser sign-in.
+
+**What is verified** on the inbound `subject_token`, before anything is minted:
+
+- **signature** against the provider's JWKS, algorithm pinned to `RS256`
+- **issuer** — exact per provider (the tenant-scoped Entra issuer, or Google's)
+- **audience** — your configured client id, so a token minted for *another*
+  application cannot be replayed here
+- **expiry** (30s clock tolerance)
+- the same `email_verified` + domain-allowlist policy as browser login
+  (see [Email-verification trust assumption](#email-verification-trust-assumption))
+
+**Trust model / documented tradeoff.** Unlike the browser flow there is no
+session to bind, so the OIDC `nonce` binding is intentionally dropped; trust
+rests on signature + issuer + audience + expiry + `email_verified`. That is the
+standard token-exchange model, and it is why the audience check (and a
+correctly scoped IdP app registration) carries the weight here.
+
+**Provisioning fails closed.** JIT-provisioning from a token minted elsewhere is
+only allowed when `OIDC_ALLOWED_DOMAINS` bounds who may self-create. With
+auto-provision on and an empty allowlist, every exchange for an unknown email is
+refused with `no_account`, and the Settings page refuses to save that
+combination — otherwise any account at a public IdP (Google = the whole
+internet) could sign itself up and mint a bearer.
+
+**Entra caveat (`preferred_username`).** Entra v2 tokens often omit `email` and
+carry the address in `preferred_username`, which is a directory attribute — in a
+tenant where guests or external identities can set their own mail attribute, a
+token can assert an address that matches an existing local account. Pinning
+`MS_TENANT_ID` to your own directory bounds that to identities your tenant
+admits; treat inviting a guest as granting whatever that email address owns here.
+
+**Rate limiting.** The per-IP cap on this endpoint reads the client IP from
+`X-Forwarded-For`, so it is only a real cap behind a proxy that overwrites that
+header. Deploy accordingly — an internet-facing server with a pass-through
+header can be sprayed from a single host.
+
+**Scope.** The minted bearer carries `scope: "mcp"`. That is a *route*
+allowlist, not a reduced permission set: it reaches `/index`, `/mcp`, and the
+ticket-eligible `/nests/:id/*` routes (including MCP write tools) with the
+user's full stewardship rights. Keep `MCP_TOKEN_TTL_SECONDS` short.
+
+**Revocation.** Turning the master flag off stops *minting* but does not revoke
+bearers already issued — they remain valid until they expire (≤ 1h). Clear
+`MCP_SIGNING_SECRET` to invalidate every outstanding bearer at once.
+
+Error codes returned by the endpoint: `disabled` (404), `rate_limited` (429),
+`bad_request`, `provider_disabled`, `provider_misconfigured` (400),
+`invalid_subject_token` (401), `email_not_verified`, `domain_not_allowed`,
+`no_account` (403), `server_error` (500).
+
+---
+
 ## Database backends
 
 The governance/auth metadata (users, sessions, nests registry, stewards, reviews,

package/dist/{chunk-GSYMJ3A4.js → chunk-3LUUJUWS.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-YVMSM7LS.js";
 import {
   getDb
-} from "./chunk-HYSTFMFG.js";
+} from "./chunk-XCFKS65Y.js";
 
 // src/governance/grants-service.ts
 import { v4 as uuid } from "uuid";

package/dist/{chunk-ENDHMQPD.js → chunk-7CPP6FIU.js}

@@ -8,7 +8,7 @@ import {
   config,
   getDb,
   isEmailish
-} from "./chunk-HYSTFMFG.js";
+} from "./chunk-XCFKS65Y.js";
 import {
   ANON_USER_ID
 } from "./chunk-YB3LKF7U.js";
@@ -27,7 +27,7 @@ import { createEngineApi } from "@promptowl/contextnest-engine/api";
 
 // src/nests/service.ts
 import { mkdirSync } from "fs";
-import { v4 as uuid2 } from "uuid";
+import { v4 as uuid3 } from "uuid";
 import { NestStorage } from "@promptowl/contextnest-engine";
 
 // src/shared/paths.ts
@@ -590,7 +590,7 @@ function parseAccessYaml(content) {
 }
 
 // src/governance/teams-service.ts
-import { v4 as uuid } from "uuid";
+import { v4 as uuid2 } from "uuid";
 
 // src/governance/roles.ts
 function collabPermToRole(permission) {
@@ -997,6 +997,9 @@ async function notifyEmailForNest(nestId, message, details) {
     }
   }
 }
+function isEmailConfigured() {
+  return !!config.SMTP_URL && !!config.NOTIFY_EMAIL_FROM;
+}
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function recipientEnvelope(to, from) {
   const recipients = Array.isArray(to) ? to : [to];
@@ -1118,6 +1121,172 @@ async function buildDocContext(nestId, nodeId, baseUrl) {
   };
 }
 
+// src/governance/notify-service.ts
+import { v4 as uuid } from "uuid";
+async function listWatchers(nestId, nodeId) {
+  return await getDb().all(
+    `SELECT id, node_id, user_email, created_by, created_at
+       FROM watchers WHERE nest_id = ? AND node_id = ? ORDER BY created_at`,
+    [nestId, nodeId]
+  );
+}
+async function addWatcher(nestId, nodeId, userEmail, createdBy) {
+  await getDb().run(
+    `INSERT INTO watchers (id, nest_id, node_id, user_email, created_by, created_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(nest_id, node_id, user_email) DO NOTHING`,
+    [uuid(), nestId, nodeId, userEmail.toLowerCase(), createdBy, (/* @__PURE__ */ new Date()).toISOString()]
+  );
+}
+async function removeWatcher(nestId, nodeId, userEmail) {
+  const db = getDb();
+  const row = await db.get(
+    "SELECT id FROM watchers WHERE nest_id = ? AND node_id = ? AND LOWER(user_email) = LOWER(?)",
+    [nestId, nodeId, userEmail]
+  );
+  if (!row) return false;
+  await db.run("DELETE FROM watchers WHERE id = ?", [row.id]);
+  return true;
+}
+async function notifyReviewRequested(params) {
+  const { nestId, nodeId, requestedBy, reviewId } = params;
+  const db = getDb();
+  try {
+    const rows = await db.all(
+      `SELECT DISTINCT w.user_email, w.node_id AS via
+         FROM watchers w
+        WHERE w.nest_id = ?
+          AND (w.node_id = ?
+               OR w.node_id IN (
+                 SELECT e.from_node FROM edges e
+                   JOIN edge_types t ON t.id = e.type_id
+                  WHERE e.nest_id = ? AND e.to_node = ? AND t.is_flow = 1
+               ))`,
+      [nestId, nodeId, nestId, nodeId]
+    );
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const label = await describeNode(nestId, nodeId);
+    let created = 0;
+    for (const r of rows) {
+      if (r.user_email.toLowerCase() === requestedBy.toLowerCase()) continue;
+      await db.run(
+        `INSERT INTO notifications (id, nest_id, user_email, kind, subject_id, message, created_at)
+         VALUES (?, ?, ?, 'review_requested', ?, ?, ?)`,
+        [
+          uuid(),
+          nestId,
+          r.user_email.toLowerCase(),
+          reviewId,
+          r.via === nodeId ? `"${label}" has a new version awaiting review (submitted by ${requestedBy})` : `Agent "${await describeNode(nestId, r.via)}" produced output on "${label}" \u2014 awaiting review`,
+          now
+        ]
+      );
+      created++;
+    }
+    return created;
+  } catch (err) {
+    console.error("[notify] review fan-out failed", nestId, nodeId, err);
+    return 0;
+  }
+}
+async function notifyReviewResolved(params) {
+  const { nestId, nodeId, status, resolvedBy, requestedBy, reviewId } = params;
+  const db = getDb();
+  try {
+    const rows = await db.all(
+      `SELECT DISTINCT w.user_email
+         FROM watchers w
+        WHERE w.nest_id = ?
+          AND (w.node_id = ?
+               OR w.node_id IN (
+                 SELECT e.from_node FROM edges e
+                   JOIN edge_types t ON t.id = e.type_id
+                  WHERE e.nest_id = ? AND e.to_node = ? AND t.is_flow = 1
+               ))`,
+      [nestId, nodeId, nestId, nodeId]
+    );
+    const recipients = new Set(rows.map((r) => r.user_email.toLowerCase()));
+    recipients.add(requestedBy.toLowerCase());
+    recipients.delete(resolvedBy.toLowerCase());
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const label = await describeNode(nestId, nodeId);
+    let created = 0;
+    for (const email of recipients) {
+      await db.run(
+        `INSERT INTO notifications (id, nest_id, user_email, kind, subject_id, message, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+        [
+          uuid(),
+          nestId,
+          email,
+          `review_${status}`,
+          reviewId,
+          `"${label}" was ${status} by ${resolvedBy}`,
+          now
+        ]
+      );
+      created++;
+    }
+    return created;
+  } catch (err) {
+    console.error("[notify] resolution fan-out failed", nestId, nodeId, err);
+    return 0;
+  }
+}
+async function notifyNestInvite(params) {
+  const { nestId, inviteeEmail, permission, nestName: nestName2, viaTeam } = params;
+  const message = viaTeam ? `Your team "${viaTeam}" was given access to "${nestName2}" as ${permissionLabel(permission)}` : `You were added to "${nestName2}" as ${permissionLabel(permission)}`;
+  try {
+    await getDb().run(
+      `INSERT INTO notifications (id, nest_id, user_email, kind, subject_id, message, created_at)
+       VALUES (?, ?, ?, 'nest_invite', ?, ?, ?)`,
+      [
+        uuid(),
+        nestId,
+        inviteeEmail.toLowerCase(),
+        nestId,
+        message,
+        (/* @__PURE__ */ new Date()).toISOString()
+      ]
+    );
+  } catch (err) {
+    console.error("[notify] invite inbox insert failed", nestId, inviteeEmail, err);
+  }
+}
+async function listNotifications(userEmail, opts = {}) {
+  const limit = Math.min(opts.limit ?? 50, 200);
+  return await getDb().all(
+    `SELECT n.id, n.nest_id, n.kind, n.subject_id, n.message, n.created_at, n.read_at,
+            COALESCE(
+              rr.node_id,
+              CASE WHEN dr.target_type = 'document' THEN dr.node_id END
+            ) AS node_id
+       FROM notifications n
+       LEFT JOIN review_requests rr ON rr.id = n.subject_id
+       LEFT JOIN deletion_requests dr ON dr.id = n.subject_id
+      WHERE LOWER(n.user_email) = LOWER(?)${opts.unreadOnly ? " AND n.read_at IS NULL" : ""}
+      ORDER BY n.created_at DESC LIMIT ${limit}`,
+    [userEmail]
+  );
+}
+async function markNotificationsRead(userEmail, ids) {
+  const db = getDb();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  if (ids === "all") {
+    await db.run(
+      "UPDATE notifications SET read_at = ? WHERE LOWER(user_email) = LOWER(?) AND read_at IS NULL",
+      [now, userEmail]
+    );
+    return;
+  }
+  for (const id of ids.slice(0, 200)) {
+    await db.run(
+      "UPDATE notifications SET read_at = ? WHERE id = ? AND LOWER(user_email) = LOWER(?)",
+      [now, id, userEmail]
+    );
+  }
+}
+
 // src/governance/teams-service.ts
 var VALID_TEAM_ROLES = ["admin", "editor", "viewer"];
 function parseMembers(json) {
@@ -1196,7 +1365,7 @@ async function createTeam(params) {
   if (!name) throw new ValidationError("Team name is required");
   const db = getDb();
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  const id = uuid();
+  const id = uuid2();
   await db.run(
     "INSERT INTO teams (id, name, owner_id, members, source, external_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
     [
@@ -1316,10 +1485,10 @@ async function resolveMemberIdentity(params) {
     };
   }
   const { hashPassword } = await import("./keys-CTOGAG3W.js");
-  const userId = uuid();
+  const userId = uuid2();
   await db.run(
     "INSERT INTO users (id, email, name, password_hash, is_invited) VALUES (?, ?, ?, ?, 1)",
-    [userId, requested, null, await hashPassword(uuid())]
+    [userId, requested, null, await hashPassword(uuid2())]
   );
   return { userId, email: requested };
 }
@@ -1408,6 +1577,7 @@ async function listNestTeams(nestId) {
 async function shareTeamWithNest(params) {
   const db = getDb();
   let sharedMembers = [];
+  let sharedTeamName = "";
   const refs = await db.transaction(async (tx) => {
     const team = await tx.get(
       "SELECT id, name, owner_id, members FROM teams WHERE id = ?",
@@ -1434,6 +1604,7 @@ async function shareTeamWithNest(params) {
     ]);
     const members = parseMembers(team.members);
     sharedMembers = members;
+    sharedTeamName = team.name;
     const hasGovernanceRole = members.some(
       (m) => m.role === "viewer" || m.role === "editor"
     );
@@ -1468,6 +1639,16 @@ async function shareTeamWithNest(params) {
         permission: role,
         by: caller?.email || void 0
       });
+      const permission = teamRoleToPermission(role) ?? role;
+      for (const email of emails) {
+        await notifyNestInvite({
+          nestId: params.nestId,
+          inviteeEmail: email,
+          permission,
+          nestName: shareNestName,
+          viaTeam: sharedTeamName
+        });
+      }
     }
   } catch (err) {
     console.error("[notify] team-share email fan-out failed", params.nestId, err);
@@ -1696,6 +1877,17 @@ async function isImportedNest(nestId) {
   );
   return !!row?.is_imported;
 }
+function plainName(name, emptyMessage = "Name cannot be empty") {
+  const typed = (name ?? "").trim();
+  if (!typed) throw new ValidationError(emptyMessage);
+  const stripped = typed.replace(/<[^>]*>/g, "").trim();
+  if (!stripped) {
+    throw new ValidationError(
+      "That's not a valid nest name \u2014 it's only HTML markup. Use plain text."
+    );
+  }
+  return stripped;
+}
 function toSlug(name) {
   return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
@@ -1730,6 +1922,22 @@ async function setStewardshipEnabled(nestId, enabled) {
     nestId
   ]);
 }
+async function setReaderMode(nestId, opts) {
+  const db = getDb();
+  const sets = [];
+  const params = [];
+  if (opts.enabled !== void 0) {
+    sets.push("reader_mode = ?");
+    params.push(opts.enabled ? 1 : 0);
+  }
+  if (opts.homeNode !== void 0) {
+    sets.push("reader_home_node = ?");
+    params.push(opts.homeNode ?? null);
+  }
+  if (sets.length === 0) return;
+  params.push(nestId);
+  await db.run(`UPDATE nests SET ${sets.join(", ")} WHERE id = ?`, params);
+}
 async function nestAllowsSelfApprove(nestId) {
   const db = getDb();
   const row = await db.get(
@@ -1806,8 +2014,7 @@ async function renameNest(nestId, patch) {
   const updates = [];
   const params = [];
   if (patch.name !== void 0) {
-    const trimmed = patch.name.trim();
-    if (!trimmed) throw new ValidationError("Name cannot be empty");
+    const trimmed = plainName(patch.name);
     const slug = toSlug(trimmed);
     if (!slug) throw new ValidationError("Name must contain at least one alphanumeric character");
     const conflict = await db.get(
@@ -1837,10 +2044,9 @@ async function renameNest(nestId, patch) {
   return await db.get("SELECT * FROM nests WHERE id = ?", [nestId]);
 }
 async function createNest(userId, name, description) {
-  const id = uuid2();
+  const id = uuid3();
   const db = getDb();
-  const trimmed = name.trim();
-  if (!trimmed) throw new ValidationError("Name cannot be empty");
+  const trimmed = plainName(name);
   const slug = toSlug(trimmed);
   if (!slug) {
     throw new ValidationError(
@@ -1869,12 +2075,9 @@ async function createNest(userId, name, description) {
   return await db.get("SELECT * FROM nests WHERE id = ?", [id]);
 }
 async function importNest(userId, name) {
-  const nm = (name || "").trim();
-  if (!nm) {
-    throw new ValidationError("name is required");
-  }
+  const nm = plainName(name || "", "name is required");
   const db = getDb();
-  const id = uuid2();
+  const id = uuid3();
   const slug = toSlug(nm);
   const visibility = userId === ANON_USER_ID ? "public" : "private";
   mkdirSync(resolveNestPath(id), { recursive: true });
@@ -2068,6 +2271,21 @@ function isSkippedSegment(segment) {
   return segment.startsWith(".") || segment === "node_modules" || segment === "_suggestions";
 }
 
+// src/nodes/meta-files.ts
+var META_BASENAMES = /* @__PURE__ */ new Set([
+  "INDEX",
+  "CONTEXT",
+  "CLAUDE",
+  "GEMINI",
+  "AGENTS",
+  "QWEN",
+  "README"
+]);
+function isMetaFile(idOrPath) {
+  const base = idOrPath.split(/[/\\]/).pop() ?? "";
+  return META_BASENAMES.has(base.replace(/\.md$/i, ""));
+}
+
 // src/shared/batch.ts
 var IO_CONCURRENCY = 32;
 async function mapBatched(items, fn, concurrency = IO_CONCURRENCY) {
@@ -2079,14 +2297,6 @@ async function mapBatched(items, fn, concurrency = IO_CONCURRENCY) {
 }
 
 // src/nodes/flat-storage.ts
-var META_FILES = /* @__PURE__ */ new Set([
-  "INDEX.md",
-  "CONTEXT.md",
-  "CLAUDE.md",
-  "GEMINI.md",
-  "AGENTS.md",
-  "QWEN.md"
-]);
 var FlatNestStorage = class extends NestStorage2 {
   async discoverDocuments() {
     const root = this.root;
@@ -2100,7 +2310,7 @@ var FlatNestStorage = class extends NestStorage2 {
     const ids = [];
     for (const e of entries) {
       if (!e.isFile() || !e.name.endsWith(".md")) continue;
-      if (META_FILES.has(e.name)) continue;
+      if (isMetaFile(e.name)) continue;
       const dir = e.parentPath ?? e.path ?? root;
       const rel = relative(root, join3(dir, e.name)).split(sep).join("/");
       if (rel.split("/").some(isSkippedSegment)) continue;
@@ -2247,8 +2457,8 @@ async function ensureNodeIndex(nestId) {
   return run;
 }
 async function rebuildNodeIndex(nestId) {
-  const { engineCache: engineCache2 } = await import("./engine-V4DY4PYN.js");
-  const { documentsWithSuggestions } = await import("./external-edit-service-3NK5DGLA.js");
+  const { engineCache: engineCache2 } = await import("./engine-VZTSDUPB.js");
+  const { documentsWithSuggestions } = await import("./external-edit-service-3FVK3OD7.js");
   const { storage, dropDiscoveryCache } = await engineCache2.get(nestId);
   dropDiscoveryCache();
   const startedAt = writeGeneration.get(nestId) ?? 0;
@@ -2345,18 +2555,11 @@ async function indexedFolderCounts(nestId) {
 // src/nodes/engine.ts
 var DISCOVERY_TTL_MS = 3e4;
 var isLive = (node) => node.frontmatter.status !== "rejected";
-var DERIVED_VAULT_FILES = /* @__PURE__ */ new Set([
-  "INDEX.md",
-  "CONTEXT.md",
-  "CLAUDE.md",
-  "GEMINI.md",
-  "AGENTS.md",
-  "README.md"
-]);
 function withDiscoveryCache(nestId, storage) {
   const entries = /* @__PURE__ */ new Map();
   let inflight = null;
-  const discover = storage.discoverDocuments.bind(storage);
+  const rawDiscover = storage.discoverDocuments.bind(storage);
+  const discover = async (options) => (await rawDiscover(options)).filter((d) => !isMetaFile(d.id));
   const readDoc = storage.readDocument.bind(storage);
   const filtersRetired = !(storage instanceof FlatNestStorage);
   let generation = 0;
@@ -2407,6 +2610,7 @@ function withDiscoveryCache(nestId, storage) {
     await markIndexStale(nestId);
   };
   const patch = async (id) => {
+    if (isMetaFile(id)) return;
     generation++;
     inflight = null;
     let node = null;
@@ -2448,8 +2652,7 @@ function withDiscoveryCache(nestId, storage) {
   wrap("init", () => desync());
   wrap("writeVaultFile", (args) => {
     const rel = String(args[0] ?? "");
-    const base = rel.split(/[/\\]/).pop() || "";
-    if (rel.endsWith(".md") && !DERIVED_VAULT_FILES.has(base)) return desync();
+    if (rel.endsWith(".md") && !isMetaFile(rel)) return desync();
   });
   return { storage, invalidate, desync: () => void desync() };
 }
@@ -2513,9 +2716,9 @@ export {
   canEditWith,
   canApproveWith,
   primaryRole,
-  permissionLabel,
   verifySmtp,
   notifyEmailForNest,
+  isEmailConfigured,
   sendEmailToRecipient,
   nestStorageRoot,
   resolveNestPath,
@@ -2525,6 +2728,7 @@ export {
   uniqueNestName,
   isStewardshipEnabled,
   setStewardshipEnabled,
+  setReaderMode,
   nestAllowsSelfApprove,
   setAllowSelfApprove,
   nestReviewsPrimeOnly,
@@ -2563,6 +2767,14 @@ export {
   docLink,
   resolveNodeUrl,
   buildDocContext,
+  listWatchers,
+  addWatcher,
+  removeWatcher,
+  notifyReviewRequested,
+  notifyReviewResolved,
+  notifyNestInvite,
+  listNotifications,
+  markNotificationsRead,
   createTeam,
   findTeamByExternalId,
   listTeamsForUser,

package/dist/{chunk-TNAZJYL5.js → chunk-EY7WOKJR.js}

@@ -4,10 +4,10 @@ import {
   markIndexStale,
   resolveNestPath,
   setSuggestionFlag
-} from "./chunk-ENDHMQPD.js";
+} from "./chunk-7CPP6FIU.js";
 import {
   getDb
-} from "./chunk-HYSTFMFG.js";
+} from "./chunk-XCFKS65Y.js";
 
 // src/governance/external-edit-service.ts
 import { readFile, readdir } from "fs/promises";
@@ -253,7 +253,7 @@ async function listExternalEditVerdicts(nestId, documentId) {
 async function mirrorVersion(input) {
   const { storage } = await engineCache.get(input.nestId);
   const node = await storage.readDocument(input.documentId);
-  const { upsertVersion, setApprovedVersion } = await import("./version-service-G7SFFKFO.js");
+  const { upsertVersion, setApprovedVersion } = await import("./version-service-5PIFT2OY.js");
   await upsertVersion({
     nestId: input.nestId,
     nodeId: input.documentId,