@promptowl/contextnest-community 1.23.0 → 1.25.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` | `""` | **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. |
+| `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. (5) It is rendered into the copy-paste setup snippets on **Settings → Connecting agents** — a `bash` block and quoted strings in `config.toml` / `config.yaml` / `mcp.json`. Because those are pasted verbatim into other people's terminals, `PATCH /admin/settings` refuses a value that is not a plain `http(s)` URL, or that contains whitespace, quotes or shell characters (`" ' ` \ $ ; | & < > ( ) { }`). A value stored before that check is not rewritten, so re-save it if the panel shows it oddly. |
 | `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,7 @@ 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`. |
 | `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**. |
+| `SHARED_DEPLOYMENT` | `false` | This server hosts **several unrelated organizations** (the PromptOwl-hosted deployment) rather than one company. A nest's `org` visibility means *every authenticated account on this deployment* — on a single-company self-hosted server that is the organization, so the tier flips in one click; on a shared server it is every customer. With this on: `PATCH /nests/:id/visibility` to `org` requires `acknowledge_public: true` exactly as `public` always does (enforced by the server, not only the UI), and the UI's visibility picker confirms before *Organization* and words both tiers to say who they really reach. Reported on `GET /health` as `shared_deployment`. Also editable from **Settings → General → This server hosts several organizations**. **Turning it on guards future changes only** — nests already at `org` stay readable by every account until their admins reconfirm or narrow them. On an already-populated server, audit them first: the dashboard's *Organization* scope lists every one, or `SELECT id, name, user_id FROM nests WHERE visibility = 'org'`. |
 | `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. |
@@ -80,10 +81,15 @@ 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. |
+| `CONTEXTNEST_AGENT` | `""` | Overrides the `agent` this server derives for caller attribution (`client`, spec §9.4) when a call sends none of its own. Without it the name comes from the MCP `initialize` handshake's `clientInfo.name` when the connection reports one, else the label of the API key the call authenticated with. A caller's own `client.agent` always wins. |
+| `CONTEXTNEST_SESSION_ID` | `""` | Same, for `session_id` — otherwise the MCP transport's session id, or an `Mcp-Session-Id` request header when the client sends one. Left absent when nothing reports one: the `/mcp` endpoints are stateless and issue no session, and a placeholder would be indistinguishable from a real id. |
+| `CONTEXTNEST_NO_ATTRIBUTION` | `""` | Set to `1` to derive nothing at all. What this server derives lands in an append-only version history, so an operator who does not want an agent's name recorded there permanently needs to say so before the first write. A `client` the caller sent explicitly is still recorded — that is the caller's own record to make. |
 | `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. |
+| `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, and the PDF upload route (`POST /nests/:id/nodes/pdf`) up to `PDF_MAX_MB`. |
 | `VIDEO_MAX_MB` | `30` | Max size (in MB) of a video uploaded into a doc. Default `30` keeps it under Cloud Run's ~32 MiB HTTP/1 request-body limit, so an oversized video is rejected with a clear message instead of a bare `413` from the platform. Raise only where the deployment can actually accept larger request bodies (not behind Cloud Run, or on HTTP/2 / direct-to-bucket upload). Images are fixed at 10 MB. |
+| `PDF_MAX_MB` | `25` | Max size (in MB) of a PDF uploaded as a `pdf` document (`POST /nests/:id/nodes/pdf`). A larger file is refused with `413` and nothing is written. Default `25` keeps the request under Cloud Run's ~32 MiB HTTP/1 limit; raise it only where the deployment accepts larger request bodies. The PDF route is exempt from `MAX_BODY_BYTES` up to this cap. |
 | `LOGO_URL` | _(unset)_ | Custom logo shown in the UI header + login screen. Must start with `https://`, `http://`, or `data:image/` — other schemes (`file://`, relative, `javascript:`) are rejected with a warning and the bundled icon is used. |
 | `PROMPTOWL_TEAMS_ENABLED` | _(unset — off)_ | Lets users who signed in with PromptOwl import their PromptOwl teams as local teams. Off by default; set `true` to enable, or toggle from Settings → Advanced. When off, `GET/POST /teams/promptowl` return `404` and the PromptOwl Teams panel is hidden. Independent of `PROMPTOWL_SIGN_IN_GATE`. |
 | `TYPE_ARTIFACT_ENABLED` | `true` | Set `false` to disable creation of **artifact** nodes server-wide (existing artifact nodes stay readable — never data loss). Runnable types (agent/skill/tool) are gated by `FEATURE_WORKFLOW_PLANE`, not here. Also editable from Settings (`/admin/settings`). |

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
@@ -98,13 +134,21 @@ For redistribution, hosted-service, OEM, or regulated-industry licensing, contac
 | Custom logo / branding | ✅ | ✅ |
 | Admin password reset + user removal (in-platform) | ✅ | ✅ |
 | Wiki backlinks, outline, hover-preview, link health | ✅ | ✅ |
-| Rich editor — tables, callouts, toggles, code highlight, find/replace, image & video upload | ✅ | ✅ |
+| Rich editor — tables, callouts, toggles, code highlight, find/replace, image & video upload, YouTube / Vimeo embeds | ✅ | ✅ |
 | Folder organization — nested folders, move documents, lazy folder tree | ✅ | ✅ |
 | Scales to large vaults — nest listings served from a document index, not a disk crawl | ✅ | ✅ |
 | Steward version revert | ✅ | ✅ |
 | 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**.

package/STEWARDSHIP.md

@@ -0,0 +1,253 @@
+# 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.
+
+## Creators review their own documents (`creator_is_reviewer`)
+
+A per-nest flag (**off** by default; nest Settings → "Creators review their own documents") for the GitHub posture: anyone with write access creates documents, and the person who created a document is the one who approves changes to it.
+
+When it's on, creating a document in a governed nest does two things:
+
+1. **The author is stewarded as a document-scope `reviewer`** of that document — exactly the row an admin would otherwise add by hand (`POST /nests/:id/stewards` with `scope: "document"`, or the `documents:` section of `stewards.yaml`). The nest owner is skipped; they already approve everything.
+2. **The first version publishes immediately.** The author is the document's reviewer, so nobody else needs to bless v1. This holds for the owner too: with this on, the owner's own new documents publish at v1 whether or not `allow_self_approve` is on — the two settings are independent, and this one only ever touches v1.
+
+The row is written **before** the publish decision, so v1 only publishes when the author really can approve the next change. If a document-scope row for the author already exists on that id with a lesser role (an admin stewarded the id ahead of time), it is left alone and v1 lands as a draft instead. If the row can't be written, the create fails with nothing written.
+
+Everything after v1 is the ordinary review cycle, and separation of duties is untouched:
+
+| | Who approves |
+|---|---|
+| A teammate edits the document | The creator (plus any tag- or nest-level reviewer, and admins) |
+| The creator edits their own document | Another reviewer — the creator can't approve their own submission |
+
+**Prime wins.** A prime document still lands as a draft: its creator is made its reviewer, but someone else has to approve the first version.
+
+Only **future** creates are affected. Turning it on doesn't steward anyone on existing documents, and turning it off leaves every steward row it created in place — remove them from the Stewards tab like any other. Every create surface participates (the editor, the REST and MCP APIs, and `ctx push` — the pusher authored what they pushed); the derived annotations document is the one exception, since nobody authored it.
+
+Like prime, this only applies to **governed** nests. With stewardship off there is nothing to review, so the flag is inert until you turn stewardship on.
+
+## 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-2YPY2HGZ.js → chunk-2KHM5C7V.js}

@@ -1,5 +1,6 @@
 import {
   buildTitleMap,
+  canApproveWith,
   canEditWith,
   canViewWith,
   collabPermToRole,
@@ -8,19 +9,20 @@ import {
   nestAllowsSelfApprove,
   nestName,
   primaryRole,
+  resolveNestAccess,
   resolveNestPermission,
   resolveTeamRolesForUser,
   sendEmailToRecipient
-} from "./chunk-QLXC6542.js";
+} from "./chunk-7FROMOZM.js";
 import {
   ConflictError,
   ValidationError
-} from "./chunk-YVMSM7LS.js";
+} from "./chunk-LHWOJPFE.js";
 import {
   config,
   getDb,
   isEmailish
-} from "./chunk-QWNXWRWO.js";
+} from "./chunk-JDAOA5KP.js";
 
 // src/governance/stewardship-service.ts
 import { v4 as uuid } from "uuid";
@@ -282,6 +284,38 @@ async function createStewardRecord(params) {
   }
   return results;
 }
+async function stewardDocumentCreator(nestId, nodeId, userEmail) {
+  const email = userEmail.trim().toLowerCase();
+  if (!email) return { canApprove: false };
+  const ownerEmail = (await getNestOwnerEmail(nestId) || "").toLowerCase();
+  if (email === ownerEmail) return { canApprove: true };
+  const row = {
+    nestId,
+    scope: "document",
+    nodePattern: nodeId,
+    userEmail: email,
+    userId: await userIdForEmail(email),
+    role: "reviewer",
+    assignedBy: email,
+    assignedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    isActive: true
+  };
+  try {
+    const created = await assignSteward(row);
+    return { canApprove: true, insertedId: created.id };
+  } catch (err) {
+    if (!isUniqueViolation(err)) throw err;
+  }
+  return {
+    canApprove: canApproveWith(
+      await resolveUserRoles(nestId, email, { nodeId })
+    )
+  };
+}
+function isUniqueViolation(err) {
+  const code = err?.code;
+  return code === "SQLITE_CONSTRAINT_UNIQUE" || code === "23505";
+}
 async function resolveStewardsForNode(nestId, nodeId) {
   return (await resolve(nestId, nodeId)).stewards;
 }
@@ -441,8 +475,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;
@@ -637,6 +671,7 @@ export {
   getStewardsForScope,
   listStewards,
   createStewardRecord,
+  stewardDocumentCreator,
   resolveStewardsForNode,
   resolveStewardsWithFallback,
   getStewardRolesForUser,

package/dist/{chunk-XYD6V2LH.js → chunk-32SZCH36.js}

@@ -2,13 +2,14 @@ import {
   engineCache,
   indexedNodeIds,
   isNestArchived,
+  listSuggestionRows,
   markIndexStale,
   resolveNestPath,
-  setSuggestionFlag
-} from "./chunk-QLXC6542.js";
+  syncSuggestionRows
+} from "./chunk-7FROMOZM.js";
 import {
   getDb
-} from "./chunk-QWNXWRWO.js";
+} from "./chunk-JDAOA5KP.js";
 
 // src/governance/external-edit-service.ts
 import { readFile, readdir } from "fs/promises";
@@ -82,7 +83,7 @@ async function scanDocumentForDriftInternal(nestId, documentId, actor) {
   if (await bodyMatchesLatestVersion(storage, documentId, drift.actualHash)) {
     return null;
   }
-  const { hasUnsealedDraft } = await import("./version-service-RJ6CWZ3O.js");
+  const { hasUnsealedDraft } = await import("./version-service-X4FAG2OZ.js");
   if (await hasUnsealedDraft(nestId, documentId)) {
     return null;
   }
@@ -91,7 +92,7 @@ async function scanDocumentForDriftInternal(nestId, documentId, actor) {
   const existing = await listSuggestions(storage, documentId);
   const dup = existing.find((s) => s.proposed_hash === drift.actualHash);
   if (dup) {
-    await setSuggestionFlag(nestId, documentId, true);
+    await syncSuggestionRows(nestId, documentId, existing);
     return { meta: dup, created: false };
   }
   const result = await stageSuggestion({
@@ -103,13 +104,13 @@ async function scanDocumentForDriftInternal(nestId, documentId, actor) {
     actor,
     docTier: "standard"
   });
-  await setSuggestionFlag(nestId, documentId, true);
+  await syncSuggestionRows(nestId, documentId, [...existing, result.meta]);
   return { meta: result.meta, created: true };
 }
 async function refreshSuggestionFlag(nestId, storage, documentId) {
   try {
     const remaining = await listSuggestions(storage, documentId);
-    await setSuggestionFlag(nestId, documentId, remaining.length > 0);
+    await syncSuggestionRows(nestId, documentId, remaining);
   } catch (err) {
     console.error("[external-edit] flag refresh failed", nestId, documentId, err);
   }
@@ -170,33 +171,27 @@ async function getPendingChange(nestId, documentId) {
   return null;
 }
 async function listNestExternalEdits(nestId) {
+  const rows = await listSuggestionRows(nestId);
+  if (rows.length === 0) return [];
   const { storage } = await engineCache.get(nestId);
-  const docs = await storage.discoverDocuments();
-  const lists = await Promise.all(
-    docs.map(async (doc) => {
-      const metas = await listSuggestions(storage, doc.id);
-      const fresh = [];
-      for (const meta of metas) {
-        if (await bodyMatchesLatestVersion(storage, doc.id, meta.proposed_hash)) {
-          continue;
-        }
-        fresh.push(meta);
-      }
-      return fresh;
-    })
+  const kept = await Promise.all(
+    rows.map(
+      async (r) => await bodyMatchesLatestVersion(storage, r.node_id, r.proposed_hash) ? null : r
+    )
+  );
+  return kept.flatMap(
+    (r) => r ? [{
+      suggestion_id: r.suggestion_id,
+      nest_id: nestId,
+      document_id: r.node_id,
+      source: r.source,
+      detected_at: r.detected_at,
+      actor: r.actor,
+      target_hash: r.target_hash,
+      proposed_hash: r.proposed_hash,
+      note: r.note ?? void 0
+    }] : []
   );
-  const entries = lists.flat().map((meta) => ({
-    suggestion_id: meta.suggestion_id,
-    nest_id: nestId,
-    document_id: meta.document_id,
-    source: meta.source,
-    detected_at: meta.detected_at,
-    actor: meta.actor,
-    target_hash: meta.target_hash,
-    proposed_hash: meta.proposed_hash,
-    note: meta.note
-  }));
-  return entries.sort((a, b) => b.detected_at.localeCompare(a.detected_at));
 }
 async function getExternalEditDetail(nestId, documentId, suggestionId) {
   const { storage } = await engineCache.get(nestId);
@@ -259,7 +254,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-RJ6CWZ3O.js");
+  const { upsertVersion, setApprovedVersion } = await import("./version-service-X4FAG2OZ.js");
   await upsertVersion({
     nestId: input.nestId,
     nodeId: input.documentId,