@promptowl/contextnest-community 1.22.0 → 1.24.0

package/CONFIGURATION.md

@@ -59,7 +59,7 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 | `PROMPTOWL_KEY` | `""` | Your PromptOwl Community License key (`pk_...`). Unlicensed instances still run and serve reads, but every write returns `503` until a valid key is installed. Can also be set via the browser License Setup Page, which persists it to the database (`server_settings` table) so it survives a rebuild and reaches every instance — see [Runtime settings persistence](#runtime-settings-persistence). Setting it here in the deploy environment takes precedence on the next boot. |
 | `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. |
+| `OFFICIAL_COMMUNITY_SSO_SECRET` | `""` | **Legacy — 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. Superseded by the DB-backed **Settings → Community sites** list (`/admin/community-sites`), which supports multiple official sites each with their own name/url/secret/active flag — this env var still works as an implicit extra site for backward compatibility. When no site is configured (env var unset and no DB rows), `GET /auth/sso` returns `404` and the feature is disabled; self-hosted users keep using the manual device-code flow. See `API.md → Community sites`. |
 | `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`. |
@@ -67,6 +67,7 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 | `OIDC_CLIENT_SECRET` | `""` | Client secret from your IdP app registration. Write-only on the Settings API — `GET /admin/settings` reports only `oidc_client_secret_set: true/false`, never the value. |
 | `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`. |
+| `PEOPLE_SUGGEST_ALL_USERS` | `false` | Widen the add-a-person suggestions (`GET /people/suggest`, behind every "add a person" field) and the `@mention` pickers from *people the caller already shares a nest or team with* to **every registered account on this server**. **Leave this off on a server that hosts more than one organisation** — the PromptOwl-hosted deployment does, and turning it on there would offer one customer's staff another customer's email addresses. On a single-company self-hosted server the whole directory is the useful answer, which is what this is for. Suggestions never gate the invite either way: an address that appears in no list is still valid to type. In the `@` pickers the widening is an invite: a write+ author mentioning someone off the nest adds them as a `read` collaborator before notifying (a read-only author's mention of an outsider reaches nobody). A server admin always sees every account (they administer them). Also editable from **Settings → General → People directory**. |
 | `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. |
@@ -79,6 +80,7 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 | `POSTHOG_KEY` | `""` | PostHog project API key for product analytics in the UI. Empty = analytics off (the default — a self-hosted install brings its own project). Served to the browser via `/health`, but only while `TELEMETRY_ENABLED` is on, so that switch turns off everything this server sends outward. Also editable from Settings → Advanced. |
 | `POSTHOG_HOST` | `https://us.i.posthog.com` | PostHog ingestion host. Set it to your own region or self-hosted PostHog. Also editable from Settings → Advanced. |
 | `TRACE_RETENTION_DAYS` | `14` | Activity-trace retention window in days (the `api_events` rows behind `GET /admin/trace` and `GET /nests/:id/trace`). Rows older than this are pruned opportunistically (every ~500 inserts). `0` = keep forever (pruning is skipped entirely). Capped at `3650`; invalid/negative values fall back to `14`. Also editable from Settings → Advanced. |
+| `DRIFT_SCAN_INTERVAL_MS` | `30000` (30 s) | How often the drift scanner walks every nest for files edited outside the app (external edits) and stages them as suggestions for review. Set `0` to disable — do this on a GCS FUSE or other network mount, where the walk is slow and costly. Unset, empty or non-numeric falls back to the default. |
 | `CORS_ORIGINS` | `*` in open mode; `http://localhost:5173,http://localhost:3838` in key mode | Comma-separated allowlist. Set to `*` to allow any origin (**only** safe in open mode — in key mode with Bearer tokens this enables CSRF). |
 | `FRAME_ANCESTORS` | `'self'` | Which origins may embed this server in an iframe, sent as CSP `frame-ancestors`. The default lets nothing but this origin frame the UI, which blocks clickjacking. Deployments that are meant to be embedded list the embedding origin — e.g. the PromptOwl Data Room iframes ContextNest, so that install sets `FRAME_ANCESTORS="https://app.promptowl.ai"`. Comma-separated; `'self'` is always included; `*` allows any site and disables the protection. Note the embedding page must be **same-site** (a sibling subdomain) for the session cookie to survive inside the frame — a genuinely cross-domain embed will render the login page no matter what this is set to. |
 | `MAX_BODY_BYTES` | `10485760` (10 MB) | Reject requests whose `Content-Length` exceeds this. Prevents giant-payload DoS. The asset-upload route (`POST /nests/:id/assets`) is exempt up to the video cap below. |
@@ -152,7 +154,8 @@ plain-text `fallbackText` for clients that cannot render cards.
 Per-nest connector rows post the same Adaptive Card format to a nest-specific
 webhook, with per-event filtering: `POST /nests/:id/connectors` with a JSON
 body like `{"channel": "teams", "url": "https://…", "events":
-["review_requested", "review_rejected"]}` (`events` may also be `["*"]`; the
+["review_requested", "review_rejected"]}` (`events` is any of `review_requested`,
+`review_approved`, `review_rejected`, `run_failed`, `mention`, or `["*"]`; the
 `url` may be an `env:KEY` reference into the nest's env store). Manage rows
 with `GET`/`PATCH`/`DELETE` on the same path.
 

package/README.md

@@ -8,17 +8,19 @@
 
 ## What it is
 
-ContextNest Community Edition is a self-hosted server that lets you:
+A shared knowledge base for your team **and** your AI agents, running on your own machine or infrastructure. Documents live in **nests**; every save is a version; in a stewarded nest a change waits for a reviewer before agents can read it. People write in the browser, agents read and write the same documents over MCP, HTTP or the `ctx` CLI.
 
-- Store, version, and govern markdown-based context documents ("nests"), filed in folders you can reorganize as the vault grows
-- Import an existing folder or vault of markdown files in one step
-- Export a nest as a portable bundle and re-import it on another self-hosted host
-- Apply stewardship workflows — draft, pending review, approved
-- Share nests with collaborators or publish them read-only to the public
-- Serve approved context to AI agents via MCP or HTTP — connect one by pasting a generated setup prompt or downloading a ready `.env`, or register the nest in the ctx CLI (`ctx vault add <alias> --url <server>/nests/<id>/mcp --bearer-env CONTEXTNEST_API_KEY`, then `ctx query "#tag" --vault <alias>`)
-- Sync with the PromptOwl hosted platform for multi-user collaboration
+Concretely, it lets you:
 
-The server runs locally or on your own infrastructure. Your PromptOwl account handles authentication, entitlement, and governance metadata.
+- Write Markdown documents — plus hosted HTML artifacts and CSV tables agents can query row by row — filed in folders, linked with `[[Title]]`, tagged, commented on, and versioned
+- Import an existing folder of Markdown in one step; export a nest as a portable bundle
+- Govern changes — draft → pending review → approved — with stewards per nest, tag or document, and a cross-nest inbox (My Work, My Drafts) for what is waiting on you
+- Share a nest with people or teams, share a single document or folder, or publish read-only to the public
+- Give agents deterministic reads: the same selector returns the same context every time, with a trace of what was pulled
+- Run agents against a nest (Workflows, Beta): an agent is a document whose body is instructions; its output lands as a pending review
+- Sync with the PromptOwl hosted platform for accounts, licensing and teams
+
+Your PromptOwl account handles authentication, entitlement, and governance metadata.
 
 ## Quickstart
 
@@ -73,6 +75,40 @@ The key is read at boot. The server validates against PromptOwl on startup; if v
 
 For redistribution, hosted-service, OEM, or regulated-industry licensing, contact **hoot@promptowl.ai**.
 
+## First five minutes
+
+1. **Create a nest** on the Nests page — or **Import folder** to bring in Markdown you already have.
+2. **Write a document.** `[[Title]]` links another document, `@name` mentions a person, tags go under the title. Every save is a version.
+3. **Turn on stewardship** (nest Settings) if you want review. Saves become drafts; **Submit for review**; a steward approves or rejects. Alone? Allow self-approve and you get the history without the ceremony.
+4. **Connect an agent.** Inside a nest, **Connect** (bottom of the sidebar) gives you the MCP URL and a REST snippet; **Add with AI** (nest overview) is a prompt that has an agent write context in. Mint a key under Workspace → API keys.
+5. **Share.** The whole nest with a person or team, one document or folder, or make it public with a read-only Reader mode.
+
+The in-app **How it works** page (sidebar → Help) is the full tour; **Docs** (header) is the agent manual.
+
+## Around the app
+
+One sidebar, grouped:
+
+| Group | Pages | Who |
+|---|---|---|
+| — | **Nests** — every nest you can see, pinned first | everyone |
+| Work | **My Work** (reviews and handoffs waiting on you, across nests) · **My Drafts** (yours, never submitted) | everyone |
+| Workspace | **Teams** · **API keys** | everyone |
+| Admin | **Teammates** · **Server settings** · **Activity trace** | server admins |
+| Help | **How it works** | everyone |
+
+Inside a nest: the document tree, plus **Board** (documents as cards by folder, status or tag), **Graph** (documents, links, tags, stewards), **Definitions** (the nest's glossary) and **Workflows** (Beta). The user menu (top right) holds **Account** (name, password), keyboard shortcuts and logout. `Ctrl`/`⌘` `K` searches every nest and document; `?` lists shortcuts.
+
+## Connect an agent
+
+Point any agent at `<server>/llms.txt` — it is the complete manual (endpoints, MCP tools, selector grammar). The short version:
+
+- **MCP** — `<server>/mcp` for everything the key can read, `<server>/nests/<id>/mcp` for one nest with the full toolset. Claude Code, Cursor and VS Code connect over HTTP with `Authorization: Bearer cnst_…`; Claude Desktop goes through `npx -y mcp-remote`.
+- **REST** — `POST /nests/<id>/context` with a selector (`#tag`, `[[Title]]`, `type:document`, combined with `+ | -`) returns assembled context plus a trace. Full reference: [API.md](./API.md).
+- **ctx CLI** — `ctx vault add <alias> --url <server>/nests/<id>/mcp --bearer-env CONTEXTNEST_API_KEY`, then `ctx query "#tag" --vault <alias>`.
+
+Keys are minted in the app (Workspace → API keys, or the Connect dialog) — one per client, user-wide or scoped to a nest. Servers in `AUTH_MODE=open` need none.
+
 ## System requirements
 
 - **Node.js** 20.x or later
@@ -105,6 +141,14 @@ For redistribution, hosted-service, OEM, or regulated-industry licensing, contac
 | MCP server for AI agents | ✅ | ✅ |
 | One-shot agent setup — generated connect prompt + `.env` download | ✅ | ✅ |
 | Several API keys per account — one credential per client, rotate one at a time | ✅ | ✅ |
+| Comments on documents — anchored threads, resolve / reopen, same threads over MCP | ✅ | ✅ |
+| Table nodes — CSV facts with deterministic row queries (`POST /table-query`, `context_table_query`) | ✅ | ✅ |
+| Teams — share a nest with a group once; import rosters from PromptOwl | ✅ | ✅ |
+| Cross-nest inbox — My Work (reviews, handoffs) and My Drafts | ✅ | ✅ |
+| Nest views — Board (kanban by folder / status / tag), Graph, Definitions glossary | ✅ | ✅ |
+| Workflow plane (Beta) — agents as documents, runs, schedules, inbound hooks, Slack / Teams / webhook connectors | ✅ | ✅ |
+| Activity trace — every governance action, per nest and server-wide | ✅ | ✅ |
+| Notifications — Slack, Microsoft Teams, email | ✅ | ✅ |
 | Centralized multi-tenant admin console | — | ✅ |
 | Single sign-on (OIDC — Entra ID, Google, Okta, Keycloak) | ✅ | ✅ |
 | SAML / SCIM provisioning | — | ✅ |
@@ -118,6 +162,14 @@ For Enterprise pricing and features, contact **hoot@promptowl.ai** or visit <htt
 
 Release notes live in [CHANGELOG.md](./CHANGELOG.md).
 
+## Documentation
+
+- [CONFIGURATION.md](./CONFIGURATION.md) — every environment variable (port, auth mode, storage, notifications, telemetry)
+- [API.md](./API.md) — complete REST reference with request and response bodies
+- [STEWARDSHIP.md](./STEWARDSHIP.md) — the governance model: modes, stewards, scopes, prime documents, teams, super-admins
+- `<server>/llms.txt` — the agent manual the running server publishes; rendered as **Docs** in the app
+- **How it works** inside the app — a page-by-page tour
+
 ## Licensing
 
 ContextNest Community Edition is **commercial software**. It is **not open source**.
@@ -165,4 +217,4 @@ The Software injects content into large language models. AI output may be inaccu
 **Copyright © 2026 Promptowl LLC.** All rights reserved.
 "ContextNest" and "PromptOwl" are trademarks of Promptowl LLC.
 
-Promptowl LLC · 3060 Mercer University Dr Ste 110 · Atlanta, GA 30341 · USA
+Promptowl LLC · 3060 Mercer University Dr Ste 110 · Atlanta, GA 30341 · USA

package/STEWARDSHIP.md

@@ -0,0 +1,229 @@
+# Stewardship — Quick Guide
+
+A short, practical guide to the governance model the community server implements. The deep strategy lives in `docs/contextnest-whitepaper.md`; this is the "how does this actually work in the product" version.
+
+## The two modes
+
+Every nest is either **ungoverned** or **governed**, controlled by the `stewardship_enabled` flag on the nest.
+
+| | Ungoverned (default) | Governed |
+|---|---|---|
+| New documents | Auto-approved, immediately available to AI | Start as **drafts**; need steward approval |
+| Draft / pending / rejected lifecycle | Not shown | Shown, filterable |
+| Review queue | Hidden | Visible, orderable |
+| Stewards | Not shown | Assignable by scope |
+| Reads gated by permission | No | Yes (in key mode) |
+
+Flip the flag any time via the nest's **Settings → Stewardship**. Existing approved docs stay approved; existing drafts remain drafts.
+
+## What a steward is
+
+A **steward** is a person (identified by email) who governs a subset of the nest. Stewards have one of three roles:
+
+| Role | Can read | Can edit | Can approve / reject |
+|---|---|---|---|
+| **Viewer** | yes | no | no |
+| **Editor** | yes | yes | no |
+| **Reviewer** | yes | yes | **yes** |
+
+> **Authors can't approve their own work.** Even a reviewer-level steward can't approve a version they themselves authored. Separation of duties, enforced server-side.
+
+## Scope — who governs what
+
+Stewards are assigned at one of three scopes. When a document needs a steward (to approve, or to check access), the server resolves them in this order — **first match wins**:
+
+| Priority | Scope | Target | Example |
+|---|---|---|---|
+| 1 | **Document** | Exact node id | `nodes/pricing-policy` — only this one doc |
+| 2 | **Tag** | Tag name (lowercased, no `#`) | `security` — any doc tagged `#security` |
+| 3 | **Nest** | (none — applies to the whole nest) | The fallback for anything not covered above |
+
+If nothing matches and no steward resolves, the **nest owner** is the implicit steward (owner fallback). That keeps a freshly-enabled nest workable even with zero stewards configured.
+
+## The approval flow
+
+1. **Author** creates or edits a doc. In governed mode it saves as a **draft**.
+2. **Author** clicks **Submit for Review**. The doc becomes **pending** and appears in the review queue for anyone whose scope resolves to that doc — and in their **My Work** page across nests. Until someone acts the author can withdraw it back to draft.
+3. A **Reviewer steward** opens the review queue (or My Work), reads the doc, clicks **Approve** or **Reject**. Rejecting requires a note.
+4. On approve, the doc becomes **approved** and is now AI-readable. The approved version number is pinned (`approvedVersion`), so subsequent drafts don't automatically replace it — AI keeps getting the last blessed version until a new one is approved.
+
+### Auto-publish owner & admin edits (`allow_self_approve`)
+
+A per-nest flag (**off** by default; nest Settings → "Auto-publish owner & admin edits"). When it's **on**, a create or edit by the nest **owner** or an **admin** publishes immediately — it skips steps 2–4 entirely instead of landing as a draft. This is a governance *bypass* for the two roles that already hold approval authority, not a separation-of-duties exception. **Editor and reviewer flows are unchanged**: their edits still save as drafts and go through Submit → Review → Approve regardless of the flag. The pending-review edit lock still applies, so an owner/admin can't overwrite a doc a teammate has in review. Turning the flag back off doesn't unpublish anything; it only affects future edits.
+
+## Prime documents
+
+Most content in a nest doesn't need a review gate — call notes, social drafts, scratch research. A small set does: messaging architecture, the sales playbook, pricing policy. **Prime** marks that second set.
+
+A prime document **always** goes through draft → pending → approved, no matter who writes it. It is the one thing `allow_self_approve` does not bypass: an owner editing a prime document still lands a draft.
+
+### How a document becomes prime
+
+Resolution mirrors the steward scope order — **document → tag → nest**, first match wins:
+
+| Priority | Scope | How it's set |
+|---|---|---|
+| 1 | **Document** | The Prime switch in the document editor (owner/admin only). `true` forces prime; `false` **exempts** this one doc from an otherwise-prime tag. |
+| 2 | **Tag** | The doc carries one of the nest's **prime tags** (Settings → Prime tags; `prime-document` out of the box). |
+| 3 | **Nest** | Nothing matched → not prime. |
+
+Only the nest owner or an admin can set or clear the document flag — it's a governance decision, not an authoring one. Otherwise any editor could un-flag the playbook and walk their own edit past the gate.
+
+### Reviewing prime documents only (`prime_only_review`)
+
+A per-nest flag (**off** by default; nest Settings → "Review prime documents only"). It changes what a governed nest's *default* is:
+
+| | `prime_only_review` off (default) | on |
+|---|---|---|
+| Ordinary document, any author | Draft → review → approve (unless the author has a self-approve bypass) | **Publishes immediately** |
+| Prime document, any author | Draft → review → approve | Draft → review → approve |
+
+That's the "most content self-publishes, high-stakes content is gated" posture. Leaving it off preserves the original behaviour, so turning stewardship on doesn't silently change meaning for an existing nest.
+
+While `prime_only_review` is on, `allow_self_approve` has no effect at all — non-prime documents already publish for everyone, and prime documents ignore the bypass. Settings disables that switch and says so rather than leaving a live control that changes nothing.
+
+Prime only applies to **governed** nests. With stewardship off there are no stewards to approve anything, so a prime tag is inert until you turn stewardship on.
+
+### At a glance
+
+Prime documents carry a **Prime** badge in the nest's document list, with a tooltip saying whether it came from the document flag or an inherited tag. To see every document a given prime tag covers, filter the list by that tag.
+
+Flipping any of this only affects **future** writes. Marking a published document prime doesn't unpublish it; the next edit is what needs approval.
+
+## Who sees what
+
+Governance gates two things: who can **approve**, and who can **read**.
+
+- **Approve gate**: server-side, always on when stewardship is enabled. Non-stewards can't approve.
+- **Read gate**: only active in **key mode** (`AUTH_MODE=key`, real user accounts with API keys). In **open mode** — which is the default for a solo/local server — everyone is the same anonymous admin, so read-gating is a no-op.
+
+In key mode, when stewardship is enabled on a nest:
+- Node list / single-read / search / query responses are filtered to docs the caller can access
+- A non-steward gets an empty list or a 403 on the node they asked for
+- The nest **owner** and any resolved **steward (any role)** can read; **super admins** bypass the check
+
+## Server super-admins
+
+Super-admins administer **every** nest on the server without being added per-nest. The effective set is the union of three sources:
+
+- **license** — the PromptOwl account that owns the installed license (always; never revocable)
+- **config** — emails in `access.yaml: super_admins` (the bootstrap; edit the file + restart to change)
+- **granted** — grants managed from **Teammates → Superadmins** in the UI, or `GET/POST /admin/super-admins` (see `API.md`)
+
+A super-admin can:
+
+- Read every document (bypasses the read gate, even with stewardship enabled)
+- Change a nest's visibility (private / org / public)
+- Add, remove, and re-role collaborators
+- Add, remove, and re-role stewards
+- Approve and reject pending versions in any nest's review queue
+- Manage the official community sites trusted for SSO auto-login (**Server settings → Community sites**, or `GET/POST /admin/community-sites` — see `API.md`)
+
+What a super-admin **cannot** do (owner-only operations):
+
+- Delete a nest
+- Transfer ownership
+
+Use this for a small set of platform operators — a CEO, a head of governance, an internal compliance admin — not as a default broad-access mechanism. Day-to-day governance should still flow through per-nest stewards.
+
+## Teams — sharing with a group
+
+Instead of adding people one at a time, you can create a **team** — a reusable,
+owner-managed group — and share it onto a nest. Each team member carries a
+**role** set on the membership (not on the share), and that role applies on
+**every** nest the team is shared to:
+
+| Member role | Nest access | Governance |
+|---|---|---|
+| **viewer** | read | viewer |
+| **editor** | write | editor |
+| **admin** | admin | admin |
+
+Key points:
+
+- A member's role is uniform across nests — set it once on the team. To vary
+  access per nest, use a different team (or a direct collaborator/steward grant).
+- When a user reaches a nest by several paths (a direct collaborator grant **and**
+  team membership), the **highest** access wins.
+- Sharing a team whose members carry a governance role (viewer/editor)
+  **enables stewardship** on the nest — same effect as assigning an individual
+  steward. An `admin`-only team is collaborator-style and doesn't.
+- Removing a member, deleting the team, or unsharing it **revokes access
+  immediately** — there are no per-user rows to clean up.
+- Managing a team is gated by your role on it: editor/admin members (and the
+  owner) can add people, capped to their own level; admins can also change
+  roles and remove members; only the owner can delete the team.
+
+### Importing a team from PromptOwl
+
+If you already run teams in PromptOwl, the Teams page has a **PromptOwl Teams**
+tab listing your teams there with their members. Each one has a **Sync** button
+that copies it here as a normal team owned by you, instead of you retyping every
+member. Members without an account here become invited placeholders, exactly as
+if you'd added them by hand.
+
+**The tab only appears if you signed in with PromptOwl** — that sign-in is what
+gives this server permission to read your teams. Signing in another way (SSO,
+your identity provider, or email and password) means no PromptOwl identity to
+read teams for, so the tab isn't offered.
+
+**You can import a team you're an owner or editor of in PromptOwl.** Teams you're
+view-only on are listed for reference but can't be imported: the copy would be
+yours to control here — rename it, rewrite its roster, share it onto a nest —
+and that's more than PromptOwl lets you do with that team. Ask one of its owners
+or editors to import it instead.
+
+Already-imported teams are marked **Synced** in that tab, and show a **PromptOwl**
+badge in the ContextNest Teams tab. Two things worth knowing before you sync
+one again:
+
+- **PromptOwl is the source of truth on every sync.** The roster is reconciled to
+  match: roles are reset, and anyone no longer in the PromptOwl team is removed —
+  including people you added to this team by hand here. If you need a group that
+  differs from PromptOwl, make it a separate team rather than editing an
+  imported one.
+- **Your PromptOwl access isn't stored on this server.** The connection lives in
+  a cookie in your own browser and ends when your session does — this server's
+  database never holds anything that can reach your PromptOwl account, so a
+  stolen backup of it exposes nothing of yours. The connection is also limited
+  to reading your profile and your teams: it cannot chat as you or spend your
+  credits. Signing out ends it, and revoking the device in PromptOwl's account
+  settings ends it immediately from the other side.
+
+PromptOwl's `User` role — its default membership — maps to **viewer** here, as
+does any role this version doesn't recognize; `Owner` maps to admin, and
+`Editor`/`Viewer` map across as themselves.
+
+Members see the teams they belong to on the **Teams** page and any team-shared
+nest on their dashboard. Manage teams there (create, add/remove members with a
+role); share them from a nest's sharing panel. See `API.md` §3a for the endpoints.
+
+## Picking a scope when you assign a steward
+
+Rules of thumb:
+
+- **Nest scope** — use sparingly. "This person reviews everything in this nest."
+- **Tag scope** — the most common. "Legal reviews anything with `#legal`. Security reviews `#auth` and `#pii`."
+- **Document scope** — override. "This specific doc has a dedicated reviewer regardless of its tags."
+
+You can stack them: a doc tagged `#legal` can have a doc-level steward that overrides the tag steward. Priority order resolves ties.
+
+## `stewards.yaml` (optional)
+
+You can also declare stewards declaratively via a `stewards.yaml` file in the nest's vault directory and run `POST /nests/:id/stewards/sync`. Useful for version-controlled governance. Example:
+
+```yaml
+version: 1
+nest:
+  - email: governance-lead@acme.com
+    role: reviewer
+tags:
+  "#legal":
+    - email: legal@acme.com
+      role: reviewer
+  "#security":
+    - email: security-team@acme.com
+      role: reviewer
+```
+
+Sync replaces all stewards for that nest from the file. Prefer the UI for day-to-day adds; prefer the file for reproducible setups and code review.

package/dist/{chunk-PX3P4FTU.js → chunk-2TPQTN4Y.js}

@@ -8,10 +8,11 @@ import {
   nestAllowsSelfApprove,
   nestName,
   primaryRole,
+  resolveNestAccess,
   resolveNestPermission,
   resolveTeamRolesForUser,
   sendEmailToRecipient
-} from "./chunk-W5ILNGPD.js";
+} from "./chunk-KIAAEHWL.js";
 import {
   ConflictError,
   ValidationError
@@ -20,7 +21,7 @@ import {
   config,
   getDb,
   isEmailish
-} from "./chunk-J2OQ3MEB.js";
+} from "./chunk-LA3VTQ22.js";
 
 // src/governance/stewardship-service.ts
 import { v4 as uuid } from "uuid";
@@ -441,8 +442,8 @@ async function resolveUserRoles(nestId, userEmail, opts) {
 }
 async function canManageStewards(nestId, userId) {
   if (config.AUTH_MODE === "open") return true;
-  const perm = await resolveNestPermission(nestId, userId);
-  return perm === "owner" || perm === "admin";
+  const { rawPermission } = await resolveNestAccess(nestId, userId);
+  return rawPermission === "owner" || rawPermission === "admin";
 }
 async function canCreateInNest(nestId, userEmail) {
   if (config.AUTH_MODE === "open" || isSuperAdmin(userEmail)) return true;

package/dist/{chunk-OQXZ43HG.js → chunk-5EZOPA47.js}

@@ -4,19 +4,19 @@ import {
   resolveNestWideRoles,
   resolveStewardsForNode,
   stewardCoverageForUser
-} from "./chunk-PX3P4FTU.js";
+} from "./chunk-2TPQTN4Y.js";
 import {
   grantCoversNode,
   listUserGrants,
   resolveNodeGrant
-} from "./chunk-MY4JIWQD.js";
+} from "./chunk-I3CSD6CK.js";
 import {
   createVersion,
   getApprovedVersion,
   getApprovedVersions,
   getCurrentVersion,
   setApprovedVersion
-} from "./chunk-6WESEA75.js";
+} from "./chunk-ZTT4U4NE.js";
 import {
   buildDocContext,
   buildTitleMap,
@@ -26,6 +26,7 @@ import {
   insertOrReplace,
   isPublicReader,
   isStewardshipEnabled,
+  markNotificationsReadBySubject,
   nestName,
   notifyEmailForNest,
   notifyReviewRequested,
@@ -36,7 +37,7 @@ import {
   resolveNestPermission,
   sendEmailToRecipient,
   titleForNode
-} from "./chunk-W5ILNGPD.js";
+} from "./chunk-KIAAEHWL.js";
 import {
   ConflictError,
   NotFoundError,
@@ -45,7 +46,7 @@ import {
 import {
   config,
   getDb
-} from "./chunk-J2OQ3MEB.js";
+} from "./chunk-LA3VTQ22.js";
 
 // src/governance/review-service.ts
 import { v4 as uuid2 } from "uuid";
@@ -157,7 +158,9 @@ async function assertFlowGraphAcyclic(nestId, extraFlowTypeId) {
   for (const r of rows) {
     if (r.from_node === r.to_node) {
       throw new ConflictError(
-        `This step loops back on itself: ${await nodeTrail(db, nestId, [r.from_node])}. A flow can't return to a step it already ran.`
+        `This step loops back on itself: ${await nodeTrail(db, nestId, [r.from_node])}.
+
+A flow can't return to a step it already ran.`
       );
     }
     nodes.add(r.from_node);
@@ -544,6 +547,7 @@ async function notifySlack(text) {
 
 // src/notify/dispatch.ts
 var EVENT_EMOJI = {
+  mention: ":speech_balloon:",
   review_requested: ":memo:",
   review_approved: ":white_check_mark:",
   review_rejected: ":x:",
@@ -610,6 +614,27 @@ async function resolveUrl(nestId, raw) {
   }
   return isSafeConnectorUrl(raw) ? raw : null;
 }
+async function hasAnyConnector(nestId, kind) {
+  if ((config.SLACK_WEBHOOK_URL || config.MSTEAMS_WEBHOOK_URL) && !DIGEST_DELIVERED_KINDS.has(kind)) {
+    return true;
+  }
+  try {
+    const rows = await getDb().all(
+      "SELECT events FROM connectors WHERE nest_id = ? AND enabled = 1",
+      [nestId]
+    );
+    return rows.some((r) => {
+      try {
+        const kinds = JSON.parse(r.events);
+        return kinds.includes("*") || kinds.includes(kind);
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
 async function dispatchEvent(ev) {
   const db = getDb();
   const nestName2 = await resolveNestName(ev.nestId);
@@ -1211,7 +1236,8 @@ async function deletionTargetContext(request, baseUrl) {
 async function notifyDeletionRequested(request, baseUrl) {
   try {
     const ctx = await deletionTargetContext(request, baseUrl);
-    const line = `Deletion requested for ${ctx.noun} *${ctx.label}* by ${request.requestedBy} \u2014 "${request.reason}"`;
+    const isArchiveRequest = request.targetType === "nest_archive";
+    const line = isArchiveRequest ? `Archive requested for ${ctx.noun} *${ctx.label}* by ${request.requestedBy} \u2014 "${request.reason}"` : `Deletion requested for ${ctx.noun} *${ctx.label}* by ${request.requestedBy} \u2014 "${request.reason}"`;
     const admins = (await nestAdminEmails(request.nestId)).filter(
       (e) => e !== request.requestedBy.toLowerCase()
     );
@@ -1220,7 +1246,7 @@ async function notifyDeletionRequested(request, baseUrl) {
       admins,
       "deletion_requested",
       request.id,
-      `${ctx.noun === "document" ? "" : `${ctx.noun} `}"${ctx.docTitle}" was flagged for deletion by ${request.requestedBy} \u2014 "${request.reason}"`
+      isArchiveRequest ? `${ctx.noun} "${ctx.docTitle}" was requested to be archived by ${request.requestedBy} \u2014 "${request.reason}"` : `${ctx.noun === "document" ? "" : `${ctx.noun} `}"${ctx.docTitle}" was flagged for deletion by ${request.requestedBy} \u2014 "${request.reason}"`
     );
     void dispatchEvent({
       kind: "deletion_requested",
@@ -1267,9 +1293,11 @@ async function notifyDeletionResolved(params) {
   try {
     const { outcome, resolvedBy, note } = params;
     const archivedInstead = outcome === "deleted" && params.targetType === "nest_archive";
-    const verb = archivedInstead ? "archived" : outcome === "deleted" ? "deleted" : "rejected the deletion of";
+    const isArchiveRequest = params.targetType === "nest_archive";
+    const verb = archivedInstead ? "archived" : outcome === "deleted" ? "deleted" : isArchiveRequest ? "declined the archive request for" : "rejected the deletion of";
     const line = `${resolvedBy} ${verb} *${params.docTitle}*${note ? ` \u2014 "${note}"` : ""}`;
     const recipient = params.requestedBy.toLowerCase();
+    await markNotificationsReadBySubject(params.requestId, "deletion_requested");
     const canInbox = !(params.targetType === "nest" && outcome === "deleted");
     if (canInbox && recipient !== resolvedBy.toLowerCase()) {
       await inboxInsert(
@@ -1277,7 +1305,7 @@ async function notifyDeletionResolved(params) {
         [recipient],
         `deletion_${outcome}`,
         params.requestId,
-        outcome === "deleted" ? `"${params.docTitle}" was ${archivedInstead ? "archived" : "deleted"} by ${resolvedBy} \u2014 your request was accepted` : `Your deletion request for "${params.docTitle}" was rejected by ${resolvedBy}${note ? ` \u2014 "${note}"` : ""}`
+        outcome === "deleted" ? `"${params.docTitle}" was ${archivedInstead ? "archived" : "deleted"} by ${resolvedBy} \u2014 your request was accepted` : `Your ${isArchiveRequest ? "archive" : "deletion"} request for "${params.docTitle}" was rejected by ${resolvedBy}${note ? ` \u2014 "${note}"` : ""}`
       );
     }
     void dispatchEvent({
@@ -1446,6 +1474,7 @@ async function declineDeletion(params) {
       requestedBy: declined.requestedBy,
       resolvedBy: params.declinedBy,
       requestId: declined.id,
+      targetType: declined.targetType,
       note: params.note,
       baseUrl: params.baseUrl
     });
@@ -1507,6 +1536,7 @@ export {
   envRoutes,
   envValues,
   isSafeConnectorUrl,
+  hasAnyConnector,
   dispatchEvent,
   sendTestNotification,
   notifyNestEvent,

package/dist/{chunk-MY4JIWQD.js → chunk-I3CSD6CK.js}

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