@promptowl/contextnest-community 1.22.0 → 1.24.0

package/API.md

@@ -0,0 +1,2092 @@
+# ContextNest Community — API Reference
+
+Base URL: `http://localhost:3838`
+Default port: `3838` (override via `PORT` env)
+
+## Authentication
+
+Two methods, evaluated in order:
+
+1. **Cookie session** — `cnst_session=<id>` (set by `/auth/login` and `/auth/register`). Browser default.
+2. **Bearer API key** — `Authorization: Bearer cnst_<token>` (issued by `/auth/keys`). Use for Postman / external tools.
+
+Anonymous open mode (`AUTH_MODE=open`) bypasses auth on most read endpoints.
+
+All bodies are JSON unless noted. All errors return `{ "error": "msg" }` with appropriate HTTP status.
+
+---
+
+## 1. Auth
+
+### POST `/auth/register`
+Public **self sign-up** — creates a brand-new account only. Gated by `MANUAL_SIGN_IN`: allowed only in `open`; `invite-only` and `disabled` return `403`. It never sets the password on an already-provisioned (invited) account — that returns `409` (no email verification exists, so self-claiming would be account takeover). Invited users get a password from their admin (`/auth/invite` or admin reset), then log in and change it.
+
+Body:
+```json
+{ "email": "user@x.com", "password": "secret123", "name": "Optional Name" }
+```
+
+Behavior:
+- Email not in DB → create user → 201 + session cookie.
+- Email in DB with `is_invited = 1` → **claim flow**: overwrite `password_hash`, set `name` if provided, flip `is_invited → 0`. Same `user.id` retained, so existing `api_keys` / `nest_collaborators` / `stewards` rows stay linked.
+- Email in DB with `is_invited = 0` → 400 `Email already registered`.
+
+Response (201):
+```json
+{ "user": { "id": "uuid", "email": "...", "name": null, "is_admin": false } }
+```
+
+Rate limit: per-IP.
+
+### POST `/auth/login`
+Body:
+```json
+{ "email": "user@x.com", "password": "secret123" }
+```
+200 + session cookie. 401 `Invalid credentials`. Rate-limited per IP and per email. Gated by `MANUAL_SIGN_IN` — returns `403` when set to `disabled` (`invite-only` still allows login).
+
+### POST `/auth/logout`
+Clears session cookie. 200.
+
+### POST `/auth/keys` (auth required)
+Mints an API key for the caller. A user may hold **several** keys — one per place they connect from — so rotating the key for one client doesn't disconnect the rest.
+
+`label` is **required** and must be unique among the caller's keys (compared case-insensitively, after trimming): once the plaintext is gone the name is the only thing that tells two keys apart, so a list of identical entries makes revoking a guess. **400** if it's missing, blank, not a string, or longer than 60 characters; **409** on a duplicate name or at the per-user ceiling (20). Keys created before this rule keep their existing (possibly absent) label.
+```json
+{ "label": "cli", "nest_id": "optional — scope the key to one nest" }
+```
+Response (201):
+```json
+{ "api_key": "cnst_...", "id": "uuid", "key_prefix": "cnst_abc123...", "label": "cli" }
+```
+**Plaintext shown once.** Omit `nest_id` for a **user-level key** (works on every nest the user can access — what the Connect dialog mints); a nest-scoped key is rejected on other nests' MCP/API paths.
+
+### POST `/auth/keys/rotate` (auth required)
+Replaces **one** key and returns its new plaintext; the caller's other keys are untouched.
+
+`key_id` names the target. Omitting it is only accepted when the account holds exactly one key (pre-multi-key clients) — with several keys and no `key_id` the server answers **400** rather than guessing which to replace. **404** if the id isn't the caller's.
+
+Scope resolution on the optional `nest_id` field: **absent** → keep the prior scope; **`null` (or `""`)** → clear to a user-level key; **a nest id** → scope to that nest. Same for `label` (absent keeps the prior label). Supplying a `label` that matches a *different* key of the caller's is **409**; renaming a key to what it is already called is fine.
+```json
+{ "key_id": "uuid", "label": "optional", "nest_id": "optional" }
+```
+
+### GET `/auth/keys` (auth required)
+Lists the caller's keys — id, prefix, label, `nest_id`, `created_at`, `last_used_at` — oldest first. Never returns plaintext.
+
+### DELETE `/auth/keys/:keyId` (auth required)
+Revoke one key. 404 if the id isn't the caller's. Anything still using it stops working immediately.
+
+### POST `/auth/password` (auth required)
+```json
+{ "current_password": "...", "new_password": "..." }
+```
+
+### PATCH `/auth/profile` (auth required)
+Set the caller's display name (≤ 80 chars, trimmed). An empty string clears it, so the UI shows the email. Needs a session or API key even under `AUTH_MODE=open` — the anonymous caller gets `401`.
+```json
+{ "name": "Alan" }
+```
+Response: `{ "ok": true, "name": "Alan" }`
+
+### POST `/auth/invite` (admin only)
+Creates an invited user and returns a **temporary password** (once) for the admin to hand off. No API key is minted — teammates sign in with the temp password, then mint their own key from the Connect modal.
+```json
+{ "email": "teammate@x.com" }
+```
+- New email → user row with `is_invited = 1` and a temporary password.
+- Existing, not-yet-claimed email (`is_invited = 1`, hasn't logged in) → refreshes the temp password.
+- Existing, claimed email (has logged in or set their own password, `is_invited = 0`) → `409`; use Reset password instead.
+
+`is_invited` clears to `0` on the teammate's first successful login (or when they set their own password).
+
+Response (201):
+```json
+{
+  "temporary_password": "...",
+  "user": { "id": "...", "email": "..." },
+  "message": "Share this temporary password securely — it won't be shown again."
+}
+```
+
+### GET `/auth/teammates` (admin only)
+Returns all users + key counts. **Sorted: admins first, then `created_at DESC`.**
+```json
+{
+  "teammates": [
+    {
+      "id": "uuid",
+      "email": "...",
+      "name": null,
+      "is_admin": true,
+      "is_invited": 0,
+      "key_count": 1,
+      "last_active": "2026-05-15T10:00:00Z"
+    }
+  ],
+  "pending_stewards": ["unregistered@x.com"]
+}
+```
+`is_invited = 1` → user was placeholder-created, has not yet claimed the account.
+
+### POST `/auth/admin/reset-password/:userId` (admin only)
+In-platform password reset — **no email server**. Provide a password, or omit it to have one generated and returned **once** for the admin to share.
+```json
+{ "password": "optional, min 8 chars" }
+```
+Response: `{ "ok": true, "email": "...", "keys_revoked": false, "temporary_password": "<only when generated>" }`. Invalidates the user's sessions but **keeps their API keys** (a reset shouldn't break a teammate's CLI/MCP). Revoke a key separately (`DELETE /auth/keys/:keyId`) if it may be compromised. The hash is never returned.
+
+### DELETE `/auth/users/:userId` (admin only)
+Removes a user — revokes api_keys, sessions, steward rows, and collaborator grants, then deletes the account. `400` if you target yourself; `409` if the user still owns nests (transfer/delete them first). Authored docs on disk are unaffected.
+
+### POST `/auth/promptowl`
+SSO via PromptOwl. Used by web UI; not typically called from Postman. Subject to `PROMPTOWL_SIGN_IN_GATE` — when `admin-only`/`disabled`, non-admins (or everyone) get `403` here.
+
+### GET `/auth/admin-status`
+Returns whether the caller is the license admin + license metadata.
+
+### POST `/auth/device` / GET `/auth/device/poll`
+Device-flow login. Also gated by `PROMPTOWL_SIGN_IN_GATE`.
+
+### GET `/auth/sso`
+One-click SSO auto-login from an **official community site** (**not for self-hosted deployments** — see below). A trusted site redirects a signed-in user here with a short-lived, single-use, audience-bound HS256 JWT ticket (`?ticket=...`). The server tries the ticket's signature against every configured official community site's secret (`GET/POST/PATCH/DELETE /admin/community-sites`, plus the legacy `OFFICIAL_COMMUNITY_SSO_SECRET`/`PUBLIC_BASE_URL` env-var pair for backward compatibility), checks `aud` against this deployment's own `PUBLIC_BASE_URL` (not the matched site's `url`, which is a display/uniqueness field only), enforces one-time-use via the ticket's `jti`, then provisions the user and starts a session (same provisioning + `PROMPTOWL_SIGN_IN_GATE` as `/auth/promptowl`). On success → `302` to `/`; on failure → `302` to `/?sso_error=<code>` (the SPA shows a toast). **When no official community site is configured** (i.e. every self-hosted server, by default) the feature is disabled and the endpoint bounces to `/?sso_error=not_supported`. That is the domain lock: without a matching secret no ticket can be verified, so the feature stays exclusive to configured official sites regardless of this redirect. Error codes: `not_supported`, `missing_ticket`, `invalid_ticket`, `bad_audience`, `ticket_used`, `rate_limited`, `sign_in_restricted`, `service_error` (DB/internal fault while redeeming the ticket).
+
+### GET `/auth/oidc/login`
+Starts generic **OIDC single sign-on** (Microsoft Entra ID, Google, or any spec-compliant IdP). Superadmin-configurable via `/admin/settings` (`oidc_*` fields) or the `OIDC_*` env vars — see `CONFIGURATION.md → Single sign-on (OIDC)`. Entirely separate from the PromptOwl flows above.
+
+When enabled and fully configured: fetches the issuer's discovery document (cached in-process ~5 min), mints `state` + `nonce` + a PKCE S256 verifier into three short-lived (10 min) httpOnly `SameSite=Lax` cookies scoped to `Path=/auth/oidc`, and `302`s to the IdP's authorization endpoint with `response_type=code&scope=openid email profile`. When disabled/unconfigured → `302` to `/?sso_error=disabled` / `not_configured`. Rate-limited per IP.
+
+### GET `/auth/oidc/callback`
+The redirect URI (`<base url>/auth/oidc/callback` — register this exact URI at your IdP). Verifies the `state` param against the flow cookie, exchanges the code at the token endpoint (client secret + PKCE verifier), validates the ID token with the issuer's JWKS (signature, `iss`, `aud` = client id, `exp`, and the `nonce` claim against the flow cookie), extracts the email (`email`, falling back to `preferred_username` for Entra; normalized trim+lowercase), and enforces `oidc_allowed_domains`. Existing users are signed in; unknown users are JIT-provisioned when `oidc_auto_provision` is on (name from the `name` claim), else refused. Every successful login also upserts `users.department` from the optional string `department` claim (trimmed, whitespace collapsed, capped at 120 chars; absent claim clears the stored value) — read by the `oidc_department_tagging` feature (see `CONFIGURATION.md → Department auto-tagging`). On success → session cookie (identical to a password login) + `302` to `/`. On any failure → `302` to `/?sso_error=<code>`; codes: `disabled`, `not_configured`, `discovery_failed`, `provider_error`, `state_mismatch`, `exchange_failed`, `invalid_token`, `email_not_verified` (ID token carries `email_verified: false` — an absent claim is trusted; see the trust assumption in `CONFIGURATION.md → Single sign-on (OIDC)`), `domain_not_allowed`, `not_invited`, `rate_limited`, `service_error`. Flow cookies are cleared on every outcome. Rate-limited per IP.
+
+### GET `/auth/oidc/logout`
+RP-initiated logout for an SSO session. Deletes the current session server-side and clears the session cookie plus the `cnst_sso_session` marker. If the issuer advertises an `end_session_endpoint` (Entra/Okta/Keycloak; Google does not), `302`s the browser through it with `post_logout_redirect_uri=<base url>/` so the IdP session ends too; otherwise `302`s straight to `/`. Always clears cookies and always lands on `/`, even if discovery is unreachable. The SPA navigates here (instead of `POST /auth/logout`) only when the non-httpOnly `cnst_sso_session` marker cookie — set on OIDC callback success — is present, so password sessions keep the plain logout.
+
+Related `/admin/settings` fields (GET/PATCH, superadmin only): `oidc_enabled`, `oidc_issuer` (https URL), `oidc_client_id`, `oidc_client_secret` (**write-only** — PATCH sets/replaces, `null` clears; GET returns only `oidc_client_secret_set: boolean`), `oidc_allowed_domains` (comma-separated), `oidc_auto_provision`, `oidc_department_tagging` (append `dept:<slugified-department>` to a new document's tags on create — create-only, no-op for users without a stored department). Enabling is refused unless issuer + client id + secret are all present.
+
+### POST `/auth/token-exchange`
+Exchange an IdP ID token for a short-lived, scoped **MCP bearer** (RFC 8693-shaped) — for an external agent acting on behalf of a user your IdP already authenticated. No session, no API key. **Off by default; security-critical** — see `CONFIGURATION.md → Agent SSO (token exchange)`.
+
+Body: `{ "provider": "microsoft" | "google", "subject_token": "<IdP ID token>" }`. Response `200`: `{ "access_token", "token_type": "Bearer", "expires_in" }` — send it as `Authorization: Bearer <access_token>` to `/index`, `/mcp`, and the ticket-eligible `/nests/:nestId/*` routes.
+
+The `subject_token` is verified for signature (provider JWKS, `RS256` pinned), issuer (exact per provider — the tenant-scoped Entra issuer or Google's), audience (your configured client id, so a token minted for another app can't be replayed), and expiry (30s tolerance); then the same `email_verified` + `oidc_allowed_domains` policy as browser login, then resolve/JIT the user (`oidc_auto_provision`) and mint. JIT **fails closed**: auto-provision with an empty domain allowlist refuses with `no_account`.
+
+`404 disabled` unless `sso_token_exchange_enabled` **and** `mcp_signing_secret` **and** that provider's toggle are all set (a disabled server doesn't advertise the endpoint). Rate-limited per IP (`429 rate_limited`). Other codes: `400` `bad_request` / `provider_disabled` / `provider_misconfigured`, `401` `invalid_subject_token`, `403` `email_not_verified` / `domain_not_allowed` / `no_account`, `500` `server_error`.
+
+Related `/admin/settings` fields (GET/PATCH, superadmin only): `sso_token_exchange_enabled`, `mcp_signing_secret` (**write-only** — GET returns only `mcp_signing_secret_set: boolean`), `mcp_token_ttl_seconds` (30–3600), `ms_token_exchange_enabled`, `ms_client_id`, `ms_tenant_id` (directory GUID), `google_token_exchange_enabled`, `google_client_id`. Enabling a provider is refused while `oidc_auto_provision` is on and `oidc_allowed_domains` is empty.
+
+---
+
+## 2. Nests
+
+A nest = a context vault (folder of markdown documents + governance state).
+
+### GET `/nests`
+Returns owned + shared nests. Archived nests are **absent** — as they are from every other listing, the work inbox, cross-nest search and the MCP index. Each row carries `pinned` — the calling user's own bookmark (see `POST /nests/:nestId/pin`).
+```json
+{ "nests": [{ "id": "...", "user_id": "...", "name": "...", "slug": "...", "visibility": "private", "created_at": "..." }] }
+```
+
+`?archived=1` inverts it: **only** archived nests, and only ones the caller owns (archive, restore and delete are the owner's, so nobody else has an action to take on one). Each row carries `archived_at`.
+
+### POST `/nests`
+```json
+{ "name": "My Nest", "description": "optional" }
+```
+Response (201): `{ "nest": { ... } }`
+
+### GET `/nests/:nestId`
+```json
+{ "nest": { ... }, "permission": "owner" | "admin" | "write" | "read" }
+```
+404 if caller has no permission.
+
+### DELETE `/nests/:nestId`
+Owner only. Permanent — documents, versions and governance state all go.
+
+### POST `/nests/:nestId/archive`
+Owner only (same gate as delete, license-admin caretaker branch included). Puts the nest away without deleting anything: `{ "archived": true }`.
+
+An archived nest is capped at `read` for **everyone**, the owner included — one guard in `resolveNestAccess`, so every REST route, MCP tool and workflow gate refuses writes. It also disappears from `GET /nests`, `/me/work`, `/me/drafts`, `GET /search`, the MCP nest index, and `GET /nests/:nestId/mcp` (404 — a pinned nest id or a nest-scoped key stops answering). Its published `/p/:slug` links return the standard not-found page. Nothing is unpublished or deleted.
+
+**Open mode is included.** `AUTH_MODE=open` grants every caller `owner` without resolving access at all, so the cap cannot reach it either; the nest middleware checks `archived_at` directly on that path — an archived nest answers `403` to anything but a `GET` (bar the lifecycle routes, which must stay open or the nest could never be restored) and `404` on its MCP transport, exactly as in key mode.
+
+Three surfaces sit outside the `/nests/:nestId` auth chain, so the permission cap cannot reach them and each carries its own `archived_at` check: `/p/:slug` (via `getPublishBySlug`), `POST /hooks/:token` (404 while archived — a trigger hook must not keep creating agent runs in a nest that was put away), and `schedulerTick`, which skips archived nests. All three are suspended, not disabled: restoring the nest brings its links, hooks and schedules back with no re-wiring.
+
+Archiving also drops any pending `nest_archive` deletion request for the nest — the ask has been granted, and a row left pending could not be actioned afterwards (the honour route needs write tier, which an archived nest denies everyone). A pending `nest` **deletion** request does survive archiving and cannot be honoured from the queue while archived; the owner deletes the nest directly (`DELETE /nests/:nestId` stays open to them) or restores it first.
+
+### POST `/nests/:nestId/restore`
+Owner only. `{ "restored": true }`. Puts everything back exactly as it was — same documents, versions, stewards, links.
+
+Editors, who cannot archive directly, ask via `POST /nests/:nestId/request-deletion` with `targetType: "nest_archive"` (see *Deletion requests*). Honouring that request archives instead of deleting.
+
+### POST / DELETE `/nests/:nestId/pin`
+The caller's own bookmark on this nest: `{ "pinned": true }` / `{ "pinned": false }`. Idempotent in both directions.
+
+**Read-tier, deliberately.** A pin changes nothing about the nest and is visible to nobody else, so any caller who can see the nest may pin it — a read-only collaborator, and someone who reaches the nest only through a single document or folder share grant, both included. It is not ungated: a caller with no access at all gets `404` (not `403`), so the endpoint can't be used to probe which nest ids exist.
+
+Idempotent under concurrency, not just in sequence: two simultaneous pins of the same nest both answer `200` rather than one tripping the composite primary key.
+
+Pins are per `(user, nest)` in the `nest_pins` table and cascade with the nest. Each row of `GET /nests` carries `pinned` for the calling user, and the dashboard floats pinned nests to the top of the grid under either sort.
+
+### GET `/nests/:nestId/settings`
+```json
+{
+  "stewardship_enabled": false,
+  "allow_self_approve": false,
+  "prime_only_review": false,
+  "prime_tags": ["prime-document"]
+}
+```
+
+### PATCH `/nests/:nestId/settings` (admin/owner)
+```json
+{ "stewardship_enabled": true, "prime_only_review": true, "prime_tags": ["prime-document"] }
+```
+
+Every field is optional; only the ones present are changed.
+
+- `allow_self_approve` — owner/admin writes publish immediately instead of drafting.
+- `prime_only_review` — in a governed nest, only **prime** documents need approval; everything else self-publishes. Off by default.
+- `prime_tags` — tags that mark a document prime. Accepts an array or a comma-separated string; stored and returned normalized (no leading `#`, lowercased, deduped). See `STEWARDSHIP.md → Prime documents`.
+
+Turning stewardship **off** wipes stewards and pending reviews and is owner-only; the other fields are non-destructive and never change the state of anything already published.
+
+### PATCH `/nests/:nestId/visibility` (admin)
+```json
+{ "visibility": "public", "acknowledge_public": true }
+```
+- **`visibility`** is one of:
+  | value | who can read without being added |
+  |---|---|
+  | `private` | nobody — owner, collaborators and stewards only |
+  | `org` | any **authenticated** user of this deployment (a self-hosted install is one organization). Anonymous callers get nothing. |
+  | `public` | anyone, including anonymous callers |
+  `org` and `public` readers see **approved content only** — drafts and pending versions stay with collaborators and stewards.
+  Under `AUTH_MODE=open` every caller resolves to the anonymous user, so there is no "other authenticated user" for `org` to admit: on an open-mode deployment `org` behaves as `private`. Use it on a deployment with real logins.
+- **Outside-org publish guardrail.** Setting `visibility: "public"` **requires** `acknowledge_public: true` (`org` does not — it stays inside the deployment, so it crosses no organizational boundary). Without it the request is rejected `409`:
+  ```json
+  {
+    "error": "Publishing this nest requires acknowledgement.",
+    "requires_acknowledgement": true,
+    "warning": "This makes the nest readable by anyone on the internet, outside your organization."
+  }
+  ```
+  Going back to `private` needs no acknowledgement.
+
+### PATCH `/nests/:nestId/reader-mode` (server-admin / superadmin only)
+Configure **Public Docs Reader Mode** — a clean, read-only public docs view of the nest. Superadmin-gated via `isServerAdminUserId` (license admin OR `access.yaml` super_admins ∪ the DB-granted set; the same gate as `/nests/unsynced` and `/admin/*`). A plain nest-owner/admin who is not a superadmin gets `403`.
+```json
+{ "enabled": true, "home_node": "welcome" }
+```
+- `enabled` (optional boolean) — toggle reader mode. When on, read-only callers (public/anonymous readers) get a stripped three-pane docs reader instead of the tabbed authoring UI; owners/editors/reviewers/admins keep the full UI.
+- `home_node` (optional string | null) — the designated landing/hub node id. `null` (or a blank string) clears it, so the landing node resolves by convention (first node whose id/title is `welcome | index | readme | home | overview`, case-insensitive; else the synthesized Contents table). A non-string, non-null value is rejected `400`.
+- At least one of `enabled` / `home_node` must be present (`400` otherwise).
+- **`home_node` is a soft pointer, not validated at write time.** An id matching no node in the nest is stored as sent, and the reader falls back to the convention as if it were unset — so an API caller gets no signal that the designation missed. The reader matches on either the full node id (`nodes/welcome`) or its bare slug (`welcome`), case-insensitively; the UI picks the id from the nest's document list rather than accepting typed input, so it never sends one that resolves to nothing.
+
+Rejections are the standard error shape:
+```json
+{ "error": "home_node must be a string or null" }
+```
+
+**Reader mode enforces nothing.** It is presentation only: it hides authoring surfaces from callers who are already read-only. It grants no access, gates no route, and changes no permission — who can read the nest is still decided by visibility, collaborators and stewardship.
+
+Response (200) echoes the persisted row:
+```json
+{ "reader_mode": 1, "reader_home_node": "welcome" }
+```
+The two additive columns (`nests.reader_mode`, `nests.reader_home_node`) also surface on `GET /nests/:nestId` via the `SELECT *` nest payload.
+
+### GET `/nests/unsynced` (server-admin only outside open mode)
+Lists folders under `DATA_ROOT` that aren't nests yet — typically dropped in by the starter CLI or copied in manually. Each entry is a sync candidate. Reflects server-side filesystem state, so in non-open mode only a server admin — the license admin or any superadmin (`access.yaml` ∪ granted; same resolution as `/admin/*`) — sees it (everyone else gets `403`).
+
+Response (200):
+```json
+{
+  "folders": [
+    {
+      "name": "nodes/architecture",
+      "label": "architecture",
+      "mdCount": 12,
+      "sizeBytes": 48230
+    }
+  ]
+}
+```
+- `name` — path relative to `DATA_ROOT` (slash-separated; pass back verbatim to `/sync`).
+- `label` — leaf folder name (display only).
+- `mdCount` / `sizeBytes` — totals across all `.md` files under the folder, recursive.
+
+When a top-level dir has no markdown directly but holds subfolders that do (e.g. `nodes/architecture/`, `nodes/standards/`), each subfolder surfaces as its own card so users can sync them as separate nests.
+
+### POST `/nests/unsynced/sync` (server-admin only outside open mode)
+Converts a sibling folder under `DATA_ROOT` into a real nest. The folder's markdown is imported (same flat-layout import as `POST /nests`), governance rows are seeded, and the source folder is removed afterwards so the same content can't be synced twice.
+
+Body:
+```json
+{ "name": "nodes/architecture" }
+```
+- `name` — required, as returned by `GET /nests/unsynced`. Travels in the body because leaf paths contain slashes that would split a path-param across route segments.
+
+Response (201):
+```json
+{
+  "nest": { "id": "...", "name": "architecture", "slug": "architecture", "...": "..." },
+  "documents": 12
+}
+```
+- Nest is named after the leaf segment (`nodes/architecture` → `architecture`). If that name (or its slug) collides for the user, a `" (n)"` suffix is appended so repeat syncs Just Work.
+- `documents` — count of governance-registered docs.
+
+Errors:
+- `400 Invalid folder name` — empty, contains `\`, traversal segment, dot-prefixed segment, or `node_modules`.
+- `400 Folder is not eligible for sync` — reserved top-level (e.g. `nests/`).
+- `400 Folder has no markdown to sync` — empty folder.
+- `404 Folder not found` — path doesn't exist under `DATA_ROOT`.
+- `403 Only the server admin can sync folders` — non-admin in non-open mode.
+
+Source-folder cleanup is best-effort. If `rmSync` fails (locked file etc.) the nest is still fully built; the orphan source dir just keeps showing up in `GET /nests/unsynced` until removed manually. Same admin gate exposed as MCP tools `context_unsynced_list` + `context_sync_folder` on any nest's `/mcp` endpoint.
+
+### DELETE `/nests/unsynced/sync` (server-admin only outside open mode)
+Deletes an unsynced folder outright — for leftover files the user does **not** want as a nest. No nest is created. Same guards as sync (`assertSafeFolderName` + live-nest-storage-root check, so it can never delete a real nest or escape `DATA_ROOT` via traversal) and the same admin gate.
+
+Body:
+```json
+{ "name": "nodes/architecture" }
+```
+- `name` — required, as returned by `GET /nests/unsynced`. In the body (not a path-param) because leaf paths contain slashes.
+
+Response (200):
+```json
+{ "ok": true }
+```
+
+Errors:
+- `400 name is required` — missing/blank name.
+- `400` — unsafe/reserved/hidden name (traversal, `nests`, dot-prefixed, `node_modules`).
+- `404 Folder not found` — path doesn't exist under `DATA_ROOT`.
+- `403 Only the server admin can delete folders` — non-admin in non-open mode.
+
+---
+
+## 3. Collaborators (direct nest sharing)
+
+Separate from stewardship — this grants raw nest access. Stewardship layers governance on top.
+
+### GET `/nests/:nestId/collaborators` (write+)
+```json
+{ "collaborators": [{ "id": "...", "user_id": "...", "email": "...", "permission": "read" }] }
+```
+Write-tier (not read) so a public nest's read tier can't enumerate member emails.
+
+### POST `/nests/:nestId/collaborators` (write+)
+```json
+{ "email": "c@x.com", "permission": "read" }
+```
+- `permission` ∈ `read` / `write` / `admin`.
+- **Inviting no longer requires admin** — any **write+** collaborator can add people, but only **up to their own level** (escalation cap). A `write` collaborator can grant `read`/`write`; only an `admin`/owner can grant `admin`. Exceeding your level → `403`. Read-only collaborators can't invite.
+- Auto-creates placeholder user (`is_invited = 1`) if email unknown.
+
+### PATCH `/nests/:nestId/collaborators/:collabId` (admin)
+```json
+{ "permission": "write" }
+```
+Changing an existing collaborator's level stays admin-only.
+
+### DELETE `/nests/:nestId/collaborators/:collabId` (admin)
+Removing a collaborator stays admin-only.
+
+### GET `/nests/:nestId/mentionable` (read+, members only)
+```json
+{ "people": [{ "email": "owner@x.com", "name": "Olive Owner" }] }
+```
+Everyone who can reach the nest (owner, collaborators, shared-team members, stewards, grant holders) — the roster the `@mention` pickers offer and validate against. With `PEOPLE_SUGGEST_ALL_USERS` on, every registered account follows the roster; mentioning one of them from a write+ account adds them to the nest as a `read` collaborator (see `POST /comments`).
+
+Read-tier, because commenting is read-tier and a read-only reviewer is the person most likely to tag someone. The property `GET /collaborators` protects with its write tier is kept by a narrower rule: **you may see the roster if you are on it.** A caller who reaches the nest only through its visibility (`public`, or `org`) is not on the roster → `403`. Write+ callers pass regardless (they can read the fuller roster anyway).
+
+### GET `/people/suggest?q=&limit=` (auth required)
+```json
+{ "people": [{ "email": "c@x.com", "name": "Carl Colleague", "source": "nest" }] }
+```
+Server-wide, not nest-scoped: the people the caller **already works with** — anyone on a nest they own or collaborate on (its owner, collaborators, active stewards) and anyone on a team they own or belong to. `source` ∈ `nest` / `team` / `directory`. For a server admin the directory is every user; `GET /auth/teammates` remains the admin-only full roster.
+
+Scope is deliberately narrow by default, because a single server may hold several unrelated organisations: `PEOPLE_SUGGEST_ALL_USERS` (off by default, Settings → General → People directory) widens it to every registered account, which is right for a single-company deployment and wrong for a shared one. A server admin always sees every account.
+
+`q` filters on name or address (substring, case-insensitive); `limit` caps the list (default and max 20). Suggestions are a convenience for the add-a-person pickers — an address that appears nowhere here is still valid to submit (that is how you invite someone with no account yet), and the add itself re-checks permission and the escalation cap.
+
+---
+
+## 3a. Share grants (one document / one folder)
+
+A **grant** gives one person access to a **single document** or **everything under one folder**, without making them a nest-wide collaborator. Access only — a grant is not stewardship and confers no approval rights.
+
+Resolution: a grant covers a node when the node id equals `target` or sits under `target + "/"`. `write` outranks `read` when several grants overlap. A grantee with no nest-wide permission sees **only** the nodes their grants cover — `GET /nests/:id/nodes` is filtered to them.
+
+**Discovery.** A grantee finds the nest by logging in: it is listed in `GET /nests`, and `GET /nests/:id` returns it, both with `permission: "read"`, `roles: ["viewer"]`, and `grant_only: true`. The list card is scoped to their slice, not the nest — `document_count` counts only the documents their grants cover, and `collaborator_*` / `steward_*` come back empty, so being shared one document never reveals how large the nest is or who else works in it. Grant-only nests deliberately do **not** enter the work inbox or `/stats`: those are governance surfaces over documents the grantee can't read.
+
+The nest routes report a grantee as a `read` caller so the nest resolves instead of 404ing, but this buys no authority: rename, delete, import, and settings-write still require `owner`/`admin`, and the remaining nest paths (`/settings`, `/stewards`, `/collaborators`, `/review-queue`, `/feed`, …) are not on the grantee's middleware allow-list at all — they answer `404`. A grantee's reachable surface is exactly: `GET /nests/:id`, `GET /nests/:id/nodes` (filtered), the granted nodes themselves, and the read-query routes (`/query`, `/search`, `/context`, `/export`), each scoped to their grants. Note `resolveNestPermission` still returns `none` for them — that is what routes them into the per-node grant checks.
+
+Managing grants is **owner / nest admin / server admin** (`canManageStewards` — same authority as the steward roster). Everyone else gets `403`.
+
+### GET `/nests/:nestId/grants`
+```json
+{ "count": 1, "grants": [{ "id": "...", "target_type": "document", "target": "nodes/win-loss-log", "user_id": "...", "email": "guest@x.com", "role": "read", "granted_by": "owner@x.com", "created_at": "..." }] }
+```
+The whole nest's sharing roster, annotated with the grantee's email.
+
+### POST `/nests/:nestId/grants`
+```json
+{ "target_type": "document", "target": "nodes/win-loss-log", "email": "guest@x.com", "role": "read" }
+```
+- `target_type` ∈ `document` / `folder`; `role` ∈ `read` / `write` (default `read`).
+- `target` is a node id (`nodes/win-loss-log`) or a folder prefix (`nodes/gtm/deals`).
+- A folder target must name a **subfolder**: a bare `nodes` root would match every node and silently share the whole nest → `400`.
+- Re-granting the same `(target_type, target, user)` updates the role rather than duplicating.
+- Auto-creates a placeholder user (`is_invited = 1`) if the email is unknown, same as collaborator invites.
+- `201 { grant }`.
+
+### DELETE `/nests/:nestId/grants/:id`
+`{ "deleted": true }`, or `404` if the grant isn't in this nest.
+
+Moving a document carries its **document** grants to the new id; deleting it drops them. **Folder** grants pin to a path, so a moved document leaves one share and joins another. Grants do not travel in a nest export bundle.
+
+Agent equivalent: the `context_grant` MCP tool takes the same four fields in one call (see §MCP and `/llms.txt`). In the UI: **Share this document** on a document's ⋯ menu, and the share icon on a folder row in the nest view.
+
+---
+
+## 3b. Teams (group sharing)
+
+A **team** is a reusable, owner-managed group of users. Each member carries a
+**role** (`admin` / `editor` / `viewer`) set on the membership and applied
+uniformly on every nest the team is shared to. Sharing a team onto a nest
+records a `{teamId, teamName}` ref on `nests.shared_teams` (no join table);
+every member then resolves to their own role there, combined highest-wins with
+any direct collaborator / steward grant.
+
+Member role → access mapping:
+
+| role | nest permission | governance role |
+|------|-----------------|-----------------|
+| `viewer` | `read` | viewer |
+| `editor` | `write` | editor |
+| `admin` | `admin` | admin |
+
+Sharing a team whose members carry a governance role (`viewer`/`editor`) turns
+`stewardship_enabled` on for the nest (parity with assigning an individual
+steward). An `admin`-only team is collaborator-style and does not.
+
+### Team management (global)
+
+Auth is the shared session/key auth. Management is gated by the caller's role on
+the team (the server/license admin may manage any team): **add people** =
+editor/admin members + owner (escalation-capped — can't grant above your own
+role); **rename / change-role / remove** = admin members + owner; **delete** =
+owner only. Unregistered member emails mint a placeholder user (`is_invited = 1`),
+same as collaborator/steward invites.
+
+- **POST `/teams`** — `{ "name": "Platform" }` → `201 { team }`. Any user may
+  create a team (they become its owner).
+- **GET `/teams`** — teams the caller owns **or is a member of** → `{ teams: [...] }`.
+  Each member is enriched with `registered` (real account vs invited placeholder)
+  and the team with `owner_email`.
+- **GET `/teams/:teamId`** — owner, a member, or the server admin may view →
+  `{ team: { id, name, owner_id, owner_email, members: [{ userId, email, role, registered }], ... } }`.
+- **PATCH `/teams/:teamId`** — `{ "name": "..." }` rename (admin/owner). Also
+  refreshes the cached `teamName` in every nest that shares this team.
+- **DELETE `/teams/:teamId`** — delete (owner/server-admin); strips the team's
+  ref from every nest's `shared_teams`.
+- **POST `/teams/:teamId/members`** — `{ "email"|"user_id", "role" }` add a
+  member (`role` ∈ `admin`/`editor`/`viewer`) → `201 { team }`. Editor/admin
+  members + owner, capped to the caller's own role. Duplicate member → `409`;
+  invalid role → `400`; above your level → `403`.
+- **PATCH `/teams/:teamId/members/:userId`** — `{ "role": "..." }` change role
+  (admin/owner, capped).
+- **DELETE `/teams/:teamId/members/:userId`** — remove a member (admin/owner);
+  their access to every shared nest is revoked immediately (no per-user rows).
+
+A team-shared nest also appears on each member's dashboard (`GET /nests`) with
+their role, so they can open it and act per their role.
+
+### PromptOwl team import (`/teams/promptowl/*`)
+
+Copy the teams the caller owns in PromptOwl into this server. Both routes are
+capped at 10 requests per IP per 15 minutes.
+
+**Only a PromptOwl sign-in can import.** Signing in with PromptOwl parks the
+device token in an httpOnly cookie (`cnst_po_token`, `Path=/teams`, lifetime of
+the session), and these routes read it **from there and nowhere else** — a token
+in the request body is ignored, so a user who signed in another way (SSO, OIDC,
+password) cannot import by supplying one. Hiding the UI is the other half of
+this rule, not the enforcement.
+
+The token is **never written to the database**: PromptOwl hands it over exactly
+once, and a self-hosted server holding live credentials for someone else's SaaS
+is a far worse liability than a cookie that dies with the session. `Path=/teams`
+means the browser only attaches it to these routes. It is scoped upstream to
+`user:read` + `teams:read`, so it cannot act as the user in PromptOwl (no agent
+chat, no credit spend) even if it leaks.
+
+Sign-in also sets `cnst_po_session=1` — a readable, secret-free marker so the
+SPA knows whether to offer the PromptOwl Teams tab. Both cookies are cleared on
+logout.
+
+**`428 Precondition Required`** with `{ code: "promptowl_connect_required" }`
+means "no PromptOwl session — sign in with PromptOwl". It is deliberately **not**
+`401`: the caller is authenticated here, and a `401` would read to the SPA as an
+expired session and bounce them to the login screen. The same 428 is returned
+when PromptOwl rejects the token (revoked upstream), and the cookie is cleared
+so a dead token isn't replayed forever.
+
+An imported team carries `source: "promptowl"` and `external_id` (its PromptOwl
+id); a team created here has `null` for both. `(owner_id, source, external_id)`
+is the import key — a re-import updates that same team rather than duplicating
+it, and survives a rename on either side. Two users importing the same PromptOwl
+team each get their own local team.
+
+- **GET `/teams/promptowl`** — `{ teams: [{ id, name, owned, your_role, source,
+  enterprise, updated_at, members: [{ email, role }] }] }`. Read-only. Returns
+  every team the caller owns **or belongs to** in PromptOwl; `your_role` is
+  their role on it there. No PromptOwl session → `428`; unreachable PromptOwl →
+  `400`.
+- **POST `/teams/promptowl/sync`** — `{ "team_ids": [...] }` →
+  `{ results: [{ team_id, external_id, name, created, added, updated, removed }] }`,
+  where `added`/`updated`/`removed` are member emails. A `team_id` the caller has
+  nothing to do with upstream → `400` (unrelated and nonexistent teams are
+  refused identically, so the error can't be used to probe which ids exist).
+
+  **Importing requires `Owner` or `Editor` upstream** → otherwise `403`, and the
+  whole batch is refused before any writes. The local copy is owned by the
+  importer — free rein to rename it, rewrite its roster, and share it onto a
+  nest. A view-only member of the upstream team holds none of that and must not
+  gain it by copying the team here; that's the same escalation
+  `shareTeamWithNest` already refuses. PromptOwl's `Viewer`, its default `User`,
+  and any unrecognized role all count as no authority.
+
+  **PromptOwl wins.** The local roster is reconciled to match: roles are reset
+  and members no longer in the PromptOwl team are **removed**, including ones
+  added here by hand. Roles map `Owner→admin`, `Editor→editor`, `Viewer→viewer`,
+  and `User`→`viewer` (as does any unrecognized role — an unknown role must never
+  widen access). The importer is the local team's owner and is not written into
+  the roster. Unregistered member emails mint placeholders exactly as
+  `POST /teams/:teamId/members` does.
+
+### Nest team-share (`/nests/:nestId/teams`)
+
+- **GET** `(write+)` — teams shared onto the nest, enriched with members:
+  `{ teams: [{ teamId, teamName, members: [{ userId, email, role }] }] }`.
+  Write-tier (like the collaborator roster) so a read tier can't enumerate emails.
+- **POST** `(admin)` — `{ "team_id": "..." }` share a team → `201 { teams }`.
+  Already shared → `409`. The caller must also be **editor+ on the team**
+  (editor/admin/owner, or server admin); a view-only member sharing → `403`, so
+  a viewer can't project a whole team onto a nest they own.
+- **DELETE `/nests/:nestId/teams/:teamId`** `(admin)` — unshare → `{ teams }`.
+
+---
+
+## 4. Nodes (documents)
+
+`nodeId` = relative path without `.md`, e.g. `nodes/api-design`.
+
+### GET `/nests/:nestId/nodes`
+Lists all readable docs.
+- When `stewardship_enabled = true`, list is filtered by `filterAccessible` — non-steward users only see what they're assigned to.
+
+Optional query params, applied before the per-node enrichment:
+
+| Param | Notes |
+|---|---|
+| `type` | Node type. A doc with no `type:` counts as `document`. |
+| `tag` | Leading `#` optional, case-insensitive. |
+| `status` | `draft` \| `pending_review` \| `approved` \| `published` \| `rejected`; aliases normalized. Retired docs stay in this listing regardless — here they are unpublished docs their stewards may still act on. |
+| `approved_only` | `1`/`true` — only docs with an approved version, each served at that version rather than the live file. The view a public nest gives a stranger, so an owner can preview what going public would expose. |
+| `limit` | Max nodes to return. A non-numeric value is ignored, not an error. |
+| `folder` | Present (even as `""`) → that one folder level only, for a lazily-expanded document tree. Absent → the whole nest. |
+| `content` | `1`/`true` — include document bodies. **Off by default:** the listing is served from the nest's document index, which holds metadata only, so bodies cost a vault crawl and are opt-in. |
+```json
+{
+  "count": 1,
+  "nodes": [{
+    "id": "nodes/foo",
+    "title": "Foo",
+    "type": "document",
+    "tags": ["#api"],
+    "status": "draft" | "pending_review" | "approved" | "rejected",
+    "version": 1,
+    "author": "creator@x.com",
+    "collaborators": ["editor@x.com", "grantee@x.com"],
+    "created_at": "...",
+    "updated_at": "...",
+    "content": "# md body — only with ?content=1",
+    "schedule": "0 6 * * *"
+  }]
+}
+```
+- `schedule` is present only on runnable nodes (`type` `agent`/`skill`); omitted otherwise.
+- `author` = the doc's creator (frontmatter author, else the first version's author); `null` for old imports with neither. `collaborators` = distinct version authors ∪ document-scope grant holders, minus the author, sorted. Both also appear on the single-node GET below.
+- Public readers (callers who reach a `visibility: public` or `visibility: org` nest without being its owner or a collaborator) do **not** receive `collaborators` — the field is omitted, and `author` falls back to the frontmatter value only, never to a version author. The roster is treated as private to the nest's members, like draft content.
+
+### POST `/nests/:nestId/nodes`
+```json
+{
+  "title": "Foo",
+  "content": "# Foo\n\nbody...",
+  "tags": ["api", "v2"],
+  "type": "document",
+  "scope": "team",
+  "status": "draft",
+  "folder": "gtm/deals",
+  "schedule": "0 6 * * *"
+}
+```
+- Slug derived from title → `nodes/<slug>`.
+- Optional `folder` (string) nests the doc → `nodes/<folder>/<slug>`. Each `/`-separated segment is slugified independently (so `../` or absolute paths can't escape the vault); empty segments drop. A leading `nodes/` segment is stripped, so `nodes/gtm/deals` and `gtm/deals` mean the same folder. Max 8 levels deep; each segment (and the title slug) max 100 chars — otherwise `400`.
+- `409` when the derived id is already taken (same folder + same title). The existing document is left untouched — update it, or pick another folder or title. The same title in a *different* folder is still allowed here; MCP `context_create` is stricter and refuses it (see [§9 MCP](#9-mcp)).
+- Optional `schedule` (free-form cron/interval string, opaque to the server) — **only valid when `type` is `agent` or `skill`**; sent on any other type → `400`. Stored in frontmatter metadata and echoed back on every node response. See [§9 `GET /runnables`](#get-nestsnestidrunnables-read).
+- Optional `prime` (boolean) flags the document as **prime** — it then always requires steward approval, whoever writes it. Owner/admin only; any other caller sending the field gets `403`. Omit to inherit from the nest's `prime_tags`; `false` exempts this document from an otherwise-prime tag. Echoed back on every node response as `prime` (absent when inherited). See `STEWARDSHIP.md → Prime documents`.
+- If stewardship enabled → status defaults `draft`. Else `approved`.
+- Auto-syncs tag index for steward resolution.
+
+Response (201): `{ "node": { ... }, "stewards": [...] }`.
+
+### GET `/nests/:nestId/nodes/:nodeId`
+Full node content. 403 if no steward access (when stewardship on).
+Add `?format=markdown` to receive `text/markdown` (frontmatter + body) instead
+of JSON — see [§8 export](#get-nestsnestidexportformatmarkdown--llm-pointed-plain-text-view).
+
+**Direct raw fetch** — `?format=raw` returns the node **body** as plain text
+(no JSON envelope, no synthesized frontmatter):
+
+| Param / header | Effect |
+|---|---|
+| `?format=raw` | Raw node body as text; Content-Type per node type (table below). |
+| `Accept: text/markdown` (header) | Same as `?format=raw` when no `format` param is present. An explicit `format` param always wins (`?format=markdown` keeps the frontmatter+body export; any other `format` value keeps JSON). Exact media-type match only — `text/*` / `*/*` do not trigger it. Matching is presence-based and deliberately ignores q-values: `text/markdown;q=0.1` still triggers raw. |
+| `?frontmatter=1` | Only meaningful with raw: prepends the node's YAML frontmatter block exactly as stored, above the body. |
+
+Content-Type by node `type`:
+
+| Node type | Content-Type |
+|---|---|
+| `document`, `agent`, `skill` (and any other/unset type) | `text/markdown; charset=utf-8` |
+| `artifact` | `text/html; charset=utf-8` |
+| `tool`, `table` | `text/plain; charset=utf-8` |
+
+Access is identical to the JSON GET — same middleware, grants, and
+public-reader semantics. Public readers get the **approved snapshot** body
+(and, with `frontmatter=1`, that snapshot's stored frontmatter); callers
+without read access get the same 403/404 JSON error as the JSON GET, never
+body bytes. Without `format`/`Accept` the response is unchanged JSON.
+
+### POST `/nests/:nestId/nodes/:nodeId/revert`
+Restore an earlier version by writing its content as a **new** version (history is preserved).
+```json
+{ "targetVersion": 3 }
+```
+Response: `{ "ok": true, "version": <new>, "node": { ... } }`. `400` without a valid `targetVersion`; `404` if that version doesn't exist. Only **sealed** versions can be reverted to — a draft revision is not in the version chain (see below).
+
+### POST `/nests/:nestId/nodes/:nodeId/discard`
+
+Throw away the unreviewed work on a document. No body.
+
+Response: `{ "ok": true, "deleted": <bool>, "version": <sealed|null> }`.
+
+Two outcomes, and which one you get depends on the document:
+- It was published before → the file goes back to that version and the draft rows above it are dropped. `deleted: false`, `version` names the version restored.
+- It was **never** published → there is nothing to fall back to, so the document is deleted, exactly as `DELETE /nodes/:nodeId` would. `deleted: true`.
+
+Costs no version either way. A draft save is never appended to the engine's history chain — that chain is append-only and hash-linked, so anything recorded in it can never be taken back. Unreviewed work lives in the file plus one governance row; a version is sealed when the draft is **submitted for review**, and again when it is published. That is what makes discarding cheap, and why `ctx verify` is unaffected by it.
+
+`423` while a review is pending — discarding would pull the document out from under the reviewer. Reject the review first. `400` if the sealed version can no longer be reconstructed from the chain (delete the document instead).
+
+### PATCH `/nests/:nestId/nodes/:nodeId`
+Headers (optional): `X-Base-Version: 3` — server returns 409 on conflict.
+```json
+{
+  "title": "...",
+  "content": "...",
+  "tags": ["..."],
+  "changeNote": "fixed typo",
+  "schedule": "0 7 * * *"
+}
+```
+Requires nest write permission.
+- `schedule` — runnable types (`agent`/`skill`) only; sent for any other type → `400`. Send `""` to clear it.
+- `type` — re-type the node in place (the editor's "Turn into…"): `document`, `artifact`, `table`, `agent`, `skill`, `tool`, or any other engine type. Same gate as create — the artifact/table feature flags and the accepted set (`400` otherwise). The body is kept as-is. Converting to `skill` defaults the trigger from the title; converting away from a runnable type drops its `schedule`.
+- `prime` — owner/admin only (`403` otherwise). `true`/`false` set the document-scope flag, `null` clears it back to tag/nest inheritance. An edit that makes the document prime is itself gated, so it lands as a draft awaiting approval.
+
+### DELETE `/nests/:nestId/nodes/:nodeId`
+Write permission. Hidden in UI for reviewer/viewer; server still enforces.
+
+A node with a pending review is frozen — `423` — for callers who can't clear that review. Approvers (nest owner, admin, assigned reviewer) go through: they can reject and then delete, so the lock only cost them a round trip. Same rule on `POST /nodes/:nodeId/move`; editing under review is unchanged (still author-only).
+
+Purges everything keyed to the node id — version history, review requests, the approved-version pin, tag index, annotations and their comments, review comments, watchers, schedules, trigger hooks, workflow edges, document-scoped stewards and document grants — and leaves a deletion tombstone for `GET /changes`. Node ids derive from titles, so a later document can land on the same id; it must inherit none of the old one's readers, reviewers or history. Run traces are kept: they record what happened, not what exists. `POST /nests/:nestId/nodes/:nodeId/move` carries that same set to the new id instead of dropping it (folder grants excepted — they cover a path prefix, so a moved doc leaves one share and joins another).
+
+### POST `/nests/:nestId/assets`
+Multipart upload (field `file`) of an image or video referenced from documents. Write permission.
+
+Supported types and per-type size caps:
+
+| Type | Extensions | Max size |
+|------|-----------|----------|
+| Image | `png`, `jpg`/`jpeg`, `gif`, `webp` | 10 MB |
+| Video | `mp4`, `webm` | 100 MB |
+
+SVG is deliberately not accepted (stored-XSS surface). Returns `201` with `{ file, url, markdown }` — `markdown` is a ready-to-paste reference: `![alt](url)` for images, the bare asset URL for video (the read view renders same-origin asset video URLs as a player).
+
+### GET `/nests/:nestId/assets/:file`
+Serves the asset bytes with the correct content-type and immutable caching. Read permission. Only server-minted `<uuid>.<ext>` names are accepted.
+
+### Watchers — GET/POST/DELETE `/nests/:nestId/nodes/:nodeId/watchers`
+"Tag a person to this node." Watchers of a document are notified when it changes or lands for review; watchers of an agent hear when its output does. `POST` body `{ email }` (write); `DELETE …/watchers?email=` (write). All three return `{ "watchers": [ … ] }`. Watchers follow a `move` and are purged by a `DELETE` of the node.
+
+---
+
+## 5. Stewardship
+
+### GET `/nests/:nestId/stewards`
+```json
+{ "stewards": [{
+  "id": "...",
+  "userEmail": "rev@x.com",
+  "userId": "...",
+  "scope": "document" | "tag" | "nest",
+  "nodePattern": "nodes/foo" | "<nestId>" | null,
+  "tagName": "api" | null,
+  "role": "editor" | "reviewer" | "viewer"
+}] }
+```
+
+### POST `/nests/:nestId/stewards`
+**Two shapes accepted.**
+
+**Legacy single-user (what the UI sends):**
+```json
+{
+  "scope": "document",
+  "email": "rev@x.com",
+  "role": "reviewer",
+  "nodePattern": "nodes/foo"
+}
+```
+
+Field selection by scope:
+| scope | required field | meaning |
+|---|---|---|
+| `document` | `nodePattern` | exact node id |
+| `tag` | `tagName` | bare tag, no `#` |
+| `nest` | — | covers every node in the nest |
+
+**Multi-user shape:**
+```json
+{
+  "scope": "tag",
+  "tagName": "api",
+  "users": [
+    { "email": "r1@x.com", "role": "reviewer" },
+    { "email": "r2@x.com", "role": "editor" }
+  ]
+}
+```
+For document scope use `documentId`; for nest no target. Sending `scope: "folder"` returns **400** — folder scope was removed.
+
+**Side effects on POST:**
+1. Auto-flips `nests.stewardship_enabled = 1` on the nest.
+2. Auto-creates `users` row with `is_invited = 1` if email unknown.
+3. Auto-inserts `nest_collaborators`: `editor → write`, `reviewer | viewer → read`.
+4. Idempotent — duplicate `(nest, scope, target, email)` returns the existing row.
+
+Response (201): `{ "stewards": [...] }` (multi) or `{ "steward": {...} }` (legacy single).
+
+### DELETE `/nests/:nestId/stewards/:stewardId`
+Soft-removes (`is_active = 0`).
+
+### POST `/nests/:nestId/stewards/sync`
+Re-imports stewards from `<nest>/.context/stewards.yaml` if present.
+Response: `{ "synced": N }`.
+
+### GET `/nests/:nestId/nodes/:nodeId/stewards`
+Resolved stewards for one node (priority `document(1) > tag(2) > nest(3)`).
+```json
+{
+  "nodeId": "nodes/foo",
+  "stewards": [{
+    "email": "rev@x.com",
+    "role": "reviewer",
+    "scope": "document",
+    "source": "document: nodes/foo",
+    "priority": 1
+  }],
+  "fallbackToOwner": false,
+  "ownerEmail": null
+}
+```
+
+### GET `/nests/:nestId/nodes/:nodeId/can-access`
+`{ "allowed": true, "reason": "...", "role": "reviewer" | null }`
+
+### GET `/nests/:nestId/nodes/:nodeId/can-approve`
+Same shape. Allowed iff the caller has a matched steward row with `role: reviewer` covering this node.
+
+### GET `/nests/:nestId/nodes/:nodeId/can-edit`
+Same shape. Reflects nest collaborator permission OR steward `editor` role.
+
+---
+
+## 6. Review workflow
+
+### POST `/nests/:nestId/nodes/:nodeId/submit-review`
+```json
+{ "note": "ready for review", "priority": "low" | "normal" | "high" | "urgent" }
+```
+Sets node status → `pending_review`. UI locks editing.
+
+### POST `/nests/:nestId/nodes/:nodeId/approve`
+```json
+{ "note": "lgtm", "override": false }
+```
+- Server checks caller has a steward row covering this node with `role = 'reviewer'`. **403 `Insufficient permissions`** otherwise.
+- Nest middleware allows `read`-perm collaborators through this path; per-row stewardship enforces real authorization.
+- `override: true` only honored for the super-admin license owner.
+
+Response: `{ "review": { "id": "...", "status": "approved", ... } }`.
+
+### POST `/nests/:nestId/nodes/:nodeId/reject`
+```json
+{ "note": "needs change X" }
+```
+`note` required. Same permission gating as approve (`role = 'reviewer'`).
+
+### POST `/nests/:nestId/nodes/:nodeId/cancel-review`
+Cancels the pending review. Returns node to `draft`.
+
+Allowed for the person who submitted it (withdrawing your own submission) and
+for anyone with approve rights on the node. Anyone else gets 403 — read access
+to the nest alone is not enough.
+
+### GET `/nests/:nestId/external-edits`
+Query: `?refresh=true` to rescan the disk first; `?count=1` to get the total only.
+
+Pending external (on-disk) edits awaiting approval, newest first. The list is computed by scanning every document's suggestions, so `?count=1` saves bytes (`{ "total": n }`), not server time — the UI uses it for the tab badge.
+```json
+{ "entries": [{ "suggestion_id": "...", "document_id": "nodes/foo", "source": "out-of-band-edit", "detected_at": "...", "actor": "..." }], "total": 1 }
+```
+
+### GET `/nests/:nestId/review-queue`
+Query: `?status=pending&limit=50&offset=0`
+
+Returns ALL reviews for the nest (server does not gate by reviewer scope).
+```json
+{
+  "requests": [{
+    "id": "...",
+    "nodeId": "nodes/foo",
+    "version": 3,
+    "requestedBy": "author@x.com",
+    "requestedAt": "...",
+    "status": "pending",
+    "priority": "normal",
+    "requestNote": "..."
+  }],
+  "total": 1
+}
+```
+
+**UI filtering** (recent change) — the React layer hides:
+- Items the caller submitted (separation of duties).
+- Items outside the caller's steward scope. **No admin/owner bypass.**
+
+So Postman will see more rows than the UI; that's expected.
+
+### POST `/nests/:nestId/review-queue/bulk`
+Body: `{ "nodeIds": ["nodes/a", "nodes/b"], "action": "approve" | "reject", "note": "..." }`
+
+One decision applied to several pending documents. Each item runs through the
+same `approve` / `reject` as the per-document routes, so permission resolution,
+state validation, history and notifications are identical — this is a wrapper,
+not a second governance path. A rejection still requires `note`, and there is no
+override: forcing past a refusal stays a per-document decision.
+
+Partial success is the normal outcome, so the call returns `200` with a per-item
+report rather than failing the batch:
+
+```json
+{
+  "action": "approve",
+  "succeeded": 2,
+  "failed": 1,
+  "results": [
+    { "nodeId": "nodes/a", "ok": true },
+    { "nodeId": "nodes/b", "ok": true },
+    { "nodeId": "nodes/c", "ok": false, "error": "Approvals go to assigned reviewers…" }
+  ]
+}
+```
+
+Duplicate ids collapse. Up to **50** ids per call; an empty or oversized
+selection is refused up front (`400`) rather than silently truncated.
+
+### GET `/nests/:nestId/nodes/:nodeId/reviews`
+Full review history for a node.
+
+### POST `/nests/:nestId/nodes/:nodeId/request-deletion`
+Body: `{ "reason": "superseded by the new runbook" }` (required).
+
+**Editor permission.** Asking for a deletion is an editor's act: a viewer of any kind — a `read` collaborator, a viewer steward, someone holding a `read` share grant — gets `403`. What counts as an editor is the same three paths that let someone change the document: nest-wide `write`, an editor steward row covering it, or a `write` share grant on it. Deleting outright stays higher still (owner/admin, or the document's own author), so an editor who spots dead content flags it rather than removing it. `404` comes first for a node the caller can't read or that doesn't exist, so the gate is never an existence oracle.
+
+A flagged node is **not** locked or under review; it stays editable and never appears in the review queue. One pending flag per node (`409` on a second). Returns `201 { request }`.
+
+`GET /nests/:nestId/nodes/:nodeId` carries `deletionRequest` — the node's latest flag (`{ status, requestedBy, reason, resolvedBy?, resolutionNote?, resolvedAt? }`) or `null`. `pending` lets a client badge the document and drop its request affordance rather than discovering the `409`; `declined` carries the resolver's note, which is how the person who asked learns the verdict.
+
+### POST `/nests/:nestId/request-deletion`
+Body: `{ "targetType": "folder" | "nest" | "nest_archive", "target": "api/limits", "reason": "..." }` (`target` ignored for both nest targets).
+
+`nest_archive` asks for the nest to be **archived** rather than destroyed — same table, same queue, same reviewers and the same decline/withdraw paths as any other request; only what honouring it does differs. The two nest targets are independent pending rows, so one of each can be open at once.
+
+Editor permission, same as the per-document route — with one difference: a steward editor needs **nest** scope here, since a row scoped to one document is no mandate over a folder or the whole nest. A folder target is normalized (`/nodes/api/limits/` → `api/limits`) so two people flagging the same folder collide on one pending request rather than raising two; `404` if no documents live under it. One pending flag per (nest, target type, target).
+
+### POST `/nests/:nestId/delete-folder`
+Body: `{ "folder": "api/limits" }`. **Owner/admin only** — a folder delete is many document deletes at once, so it sits at the nest-management tier, not `write`. Deletes every document under the prefix (sub-folders included) through the normal per-node path, so each gets its review-lock check, row purge and tombstone. Returns `{ deleted, nodeIds }`. Non-admins use the request flow above.
+
+Folders are not stored objects — they exist only as segments of the node ids beneath them, so deleting a folder *is* deleting its documents.
+
+### GET `/nests/:nestId/deletion-requests`
+Query: `?status=pending|declined|all` (defaults to `pending`). `all` returns both states newest-first — one call for a client that shows the queue and badges declined nodes.
+
+```json
+{
+  "requests": [{
+    "id": "...",
+    "nodeId": "nodes/foo",
+    "title": "Foo",
+    "requestedBy": "reader@x.com",
+    "reason": "superseded",
+    "status": "pending",
+    "createdAt": "..."
+  }],
+  "total": 1
+}
+```
+
+### POST `/nests/:nestId/deletion-requests/:id/delete`
+Honours the request — write permission, the same tier `DELETE /nodes/:nodeId` requires (including its `423` review lock). Branches on the request's `targetType`: a document goes through `deleteNode`, a folder through the bulk delete above, a nest through `deleteNest`, and `nest_archive` through `archiveNest` (nothing is deleted; the nest can be restored).
+
+Both **nest** targets additionally require owner/admin: acting on a whole nest is the owner's call (`DELETE /nests/:id` and `POST /nests/:id/archive` enforce that), and honouring a request must not be a way around it — a write-tier collaborator gets `403`.
+
+An honoured request always leaves the queue: a document's row is purged with its other node-keyed rows, a nest's cascades with the nest, and a folder's — which is neither — is dropped explicitly.
+
+Raising a request notifies the nest owner + owner/admin collaborators: a `/me/work` inbox row, the `deletion_requested` connector event (Slack/Teams/webhook), and a direct email. Resolving it — either way — notifies the requester the same way (`deletion_deleted` / `deletion_declined`). All delivery is best-effort; a notification failure never fails the action.
+
+`GET /me/work` returns these alongside reviews as items with `type: "deletion"`, carrying `reason` and `request_id`. They land in `items` only for nest owners/admins (the tier that can delete) and in `waiting` for whoever raised them.
+
+### POST `/nests/:nestId/deletion-requests/:id/decline`
+Body: `{ "note": "still referenced by onboarding" }` (required). Write permission. Keeps the node and the row, recording who declined and why. `404` once the request is no longer pending.
+
+### GET `/nests/:nestId/feed`
+Query: `?filter=all|changes|comments&limit=50&offset=0` (filter defaults to `all`, limit caps at 200, offset caps at 10 000)
+
+Nest **activity feed** — pending change submissions (the exact rows
+`/review-queue` shows, every field intact, plus the caller's `canReview`)
+interleaved with annotation activity (new comment threads AND replies),
+newest first. Additive sibling of `/review-queue`; that endpoint and the MCP
+`context_review_queue` tool are unchanged.
+
+Comment items are access-filtered to documents the caller can read (same
+resolution as node listing: public readers see approved docs only; grants and
+steward scope honored). Change items mirror the queue (not access-filtered).
+
+```json
+{
+  "items": [
+    {
+      "type": "comment",
+      "id": "<commentId>",
+      "threadId": "<threadId>",
+      "nodeId": "nodes/foo",
+      "title": "Foo",
+      "author": "reviewer@x.com",
+      "snippet": "First ~200 chars of the comment…",
+      "createdAt": "2026-07-14 11:00:00",
+      "resolved": false,
+      "isReply": true
+    },
+    {
+      "type": "change",
+      "id": "<reviewRequestId>",
+      "nestId": "...",
+      "nodeId": "nodes/foo",
+      "title": "Foo",
+      "version": 3,
+      "requestedBy": "author@x.com",
+      "requestedAt": "2026-07-14 10:00:00",
+      "requestNote": "...",
+      "status": "pending",
+      "priority": "normal",
+      "canReview": true,
+      "createdAt": "2026-07-14 10:00:00"
+    }
+  ],
+  "total": 2,
+  "counts": { "changes": 1, "comments": 1 },
+  "filter": "all",
+  "limit": 50,
+  "offset": 0
+}
+```
+
+`counts` always carries both per-type totals regardless of `filter`; the UI
+tab badge binds to `counts.changes` (actionable items), not the feed length.
+The UI deep-links a comment item to its document with the thread focused via
+`?nest=<id>&doc=<nodeId>&thread=<threadId>`.
+
+### Notification rows (`GET /me/work` → `notifications`, `GET /me/notifications`)
+
+Each row carries `nest_id`, `nest_name` (resolved in the same read, so the inbox navigates without fetching the nest list), `kind`, `message`, `created_at`, `read_at`, and `node_id` when the row is about a document (review verdicts, document deletion flags, mentions); nest-level rows have `node_id: null`.
+
+### GET `/me/drafts`
+
+Query: `?limit=25&offset=0&q=&sort=updated|title` (limit clamps to 1–100, offset to ≥ 0)
+
+`q` matches the title, the nest name and the node id, case-insensitively. `sort` defaults to `updated` (newest first). A title lives on disk rather than in SQL, so `q` and `sort=title` read the whole matching set (capped at 500 rows) and page it in memory — on those two, `total` counts what survives the filter and is exact.
+
+Every document **you** left unsubmitted, across every nest you can see. A draft
+that was never submitted has no `review_requests` row, so it appears in no
+review queue and no `/me/work` bucket — this is the only surface that finds it
+again. Backs the dashboard's "My Drafts" tab.
+
+Included: nodes whose **latest** version row is authored by the caller with
+status `draft` or `rejected`, and that have no pending review request (those
+are already in `/me/work` under `waiting`). Approved/published documents are
+deliberately excluded — they are not stranded work. Rows for deleted documents
+are filtered out.
+
+```json
+{
+  "drafts": [
+    {
+      "nest_id": "<nestId>",
+      "nest_name": "GTM",
+      "node_id": "nodes/gtm/cohere",
+      "title": "Cohere Kill Sheet",
+      "folder": "gtm",
+      "status": "draft",
+      "version": 3,
+      "updated_at": "2026-07-23 09:12:00"
+    }
+  ],
+  "pagination": { "total": 137, "limit": 25, "offset": 0, "has_more": true }
+}
+```
+
+`total` is counted in SQL, before the existence filter that drops orphaned
+version rows (a document deleted outside the app), so it can run one high and
+leave a page one row short. `has_more` is derived from the **requested** page
+size for that reason, not from the number of rows returned.
+
+Submitting one is the ordinary `POST /nests/:nestId/nodes/:nodeId/submit-review`
+— it then leaves this list and appears in `/me/work`.
+
+---
+
+## 7. Versions
+
+### GET `/nests/:nestId/nodes/:nodeId/versions`
+
+Version metadata plus each version's **change log** — the unified diff taking the
+previous version to this one, as the engine stored it. `diff` is absent for v1
+and for keyframe versions (a keyframe is a full snapshot, so there is no patch).
+
+`content` is always `""` here. The list deliberately does **not** carry bodies:
+attaching them means replaying the version chain once per row and shipping N
+full copies of the document just to open the history panel. Fetch the one body
+you need from `GET .../versions/:version` below.
+
+Each version may also include `resolvedBy` + `resolutionStatus`, the steward who
+approved or rejected it, joined from `review_requests` (`node_versions` stores
+the status but not the resolver's email).
+
+`externalEditVerdicts` carries the verdicts on out-of-band (direct filesystem)
+edits, oldest first, read from the engine's append-only chain-event log. They sit
+beside the version list rather than inside it because a **rejection commits no
+content and therefore has no version** — minting one would renumber the chain.
+An approval does commit, so it appears in both: as the version it created, and as
+a verdict here. `note` is the rejection reason, or the approver's comment when
+one was left.
+
+Gated by the same node-level read check as the document itself — `403` when the
+caller can't read the node, which for a public reader means any node without an
+approved version.
+
+```json
+{
+  "currentVersion": 3,
+  "approvedVersion": 2,
+  "versions": [
+    {
+      "version": 3,
+      "editedBy": "author@x.com",
+      "editedAt": "...",
+      "status": "pending_review",
+      "changeNote": "...",
+      "content": "",
+      "diff": "Index: v2\n===...\n--- v2\tv2\n+++ v2\tv3\n@@ -1,4 +1,5 @@\n title: doc\n-old line\n+new line\n"
+    },
+    {
+      "version": 2,
+      "editedBy": "author@x.com",
+      "editedAt": "...",
+      "status": "approved",
+      "changeNote": "...",
+      "content": "",
+      "resolvedBy": "reviewer@x.com",
+      "resolutionStatus": "approved"
+    }
+  ],
+  "externalEditVerdicts": [
+    {
+      "suggestion_id": "20240115T103000-a1b2c3d4",
+      "status": "rejected",
+      "actor": "reviewer@x.com",
+      "at": "2024-01-15T10:34:00.000Z",
+      "note": "not sourced",
+      "source": "out-of-band-edit"
+    }
+  ]
+}
+```
+
+### GET `/nests/:nestId/nodes/:nodeId/versions/:version`
+
+One version's full body, reconstructed on demand from the nearest keyframe plus
+the diffs after it.
+
+`content` is `null` — with HTTP 200, not an error — when that version's chain can
+no longer be replayed (e.g. history grafted by an older import). Callers render
+it as "no content" rather than failing the whole panel.
+
+Same node-level read check as the list above: `403` when the caller can't read
+the node. A public reader can only reach versions of a node that has an approved
+version, so drafts of an unapproved document are never reconstructable this way.
+
+```json
+{ "version": 2, "content": "# Heading\n\nbody as of v2\n" }
+```
+
+---
+
+## 8. Comments & activity
+
+Comments are a standalone collaboration primitive — **not** part of the
+version/hash chain. They thread, carry attribution, anchor to a highlighted
+span, and resolve (Word/Docs-style "Comments", separate from Track Changes).
+Any caller with **read** access to the nest may leave or resolve a comment.
+
+### GET `/nests/:nestId/nodes/:nodeId/comments?status=open`
+List comments on a node. Optional `status` = `open` | `resolved`.
+```json
+{
+  "comments": [
+    {
+      "id": "…",
+      "nestId": "…",
+      "nodeId": "nodes/spec",
+      "version": 1,
+      "anchor": { "start": 8, "end": 19, "text": "first draft" },
+      "parentId": null,
+      "author": "owner@x.com",
+      "body": "This needs a citation.",
+      "status": "open",
+      "createdAt": "…"
+    }
+  ]
+}
+```
+
+### POST `/nests/:nestId/nodes/:nodeId/comments`
+Leave a comment. Body: `{ body, version?, anchor?{start,end,text?}, parentId? }`.
+`parentId` threads a reply. Returns `201 { comment }`. Empty body → `400`.
+
+**`@mentions` notify.** Every name in the comment body — `@user@host`,
+`@localpart`, or `@(Display Name)` — is resolved against the nest's people
+(`GET /nests/:nestId/mentionable`) and each person named gets a `mention` row
+in `GET /me/notifications` linking the document, plus a message on the
+configured connector and an email to their own address when SMTP is set up.
+A channel message names who was mentioned (a room is not a person); the inbox
+row and the email address the recipient directly. The author is never notified
+about their own mention, a name matching nobody
+(or matching two people ambiguously) notifies nobody, and a recipient who
+can't open the document is skipped — so a mention can't disclose a title.
+Unlike a document body, where only names a save *adds* notify, every name in a
+comment notifies: the comment itself is the new event. At most 25 people are
+notified per write (`MAX_MENTION_RECIPIENTS`) — commenting is read-tier and
+unthrottled, so a comment naming a large roster would otherwise be an
+amplifier; names are taken in order of appearance. With `PEOPLE_SUGGEST_ALL_USERS`
+on, a name that matches a registered account off the nest is an invite: a
+write+ author's mention adds them as a `read` collaborator and then notifies;
+a read-only author's mention of an outsider still reaches nobody.
+
+The *stream* of them is bounded too: per nest per 5 minutes, one person may
+cause 50 mention **emails** (`MENTION_DELIVERY_BUDGET`) and 25 mention
+**channel posts** (`MENTION_CHANNEL_BUDGET`) — separate pools, because emails
+scale with how many people were named while a channel post is one message per
+comment. Separate also so the email allowance doesn't depend on something
+invisible: the connector dispatch is a no-op on a nest with no connector
+configured, and a shared pool would have spent the token before it could say
+so, quietly halving the email budget on exactly the deployments least likely to
+have a connector. Past that the comment still posts and the
+inbox rows still land — the queue is the recipient's own record and costs one
+insert — and only the external fan-out is skipped, with a server-log warning.
+The budget sits on delivery rather than on comment creation deliberately: an
+agent working through a review posts a comment per finding, which is exactly
+what `context_comment` is for, and throttling the write would break it. The same applies to the
+annotation thread endpoints (§ Hosted artifacts), which are what the UI's
+comments panel posts.
+
+### POST `/nests/:nestId/nodes/:nodeId/comments/:commentId/resolve`
+Mark a comment resolved. Records `resolvedBy` + `resolvedAt`. Returns `{ comment }`.
+
+### GET `/nests/:nestId/nodes/:nodeId/activity` · GET `/nests/:nestId/activity`
+Per-node (or nest-wide) activity log — "who did what". A read-only aggregation
+over comments + committed edits (`node_versions`) + pending external-edit
+suggestions ("proposed an edit", read from nest storage) + reviews
+(`review_requests`); newest first, `?limit=` (default 100). Each entry:
+`{ type, nodeId, actor, at, detail?, refId? }` where `type` ∈
+`comment | comment_resolved | edit | edit_proposed | review_requested | review_resolved`.
+
+
+### Annotations — anchored threads the editor's Comment mode shows
+
+The comments above are flat per-node threads. **Annotations** are the highlight-anchored threads the editor's Comment mode and the artifact viewer show; MCP's `context_comments` / `context_comment` / `context_resolve_comment` operate on these. Read permission to view, write to post.
+
+- `GET /nests/:nestId/nodes/:nodeId/annotations` — list threads with their replies and `open` / `resolved` status.
+- `POST /nests/:nestId/nodes/:nodeId/annotations` — open a thread. Body: `{ body, anchor?: { start, end, text }, snapshotVersion? }`. No `anchor` = a whole-document (or whole-artifact) thread.
+- `POST /nests/:nestId/nodes/:nodeId/annotations/:threadId/comments` — reply. Body: `{ body }`.
+- `POST /nests/:nestId/nodes/:nodeId/annotations/:threadId/resolve` · `/reopen`.
+- `GET /nests/:nestId/comment-counts` — `{ "<nodeId>": <open thread count>, … }` for the whole nest in one call (the UI's "most commented" sort).
+
+---
+
+## 8b. Glossary definitions
+
+A literal table-based ontology per nest: stewards/editors define and articulate
+terms — existing `#tags` or brand-new vocabulary — and external runtimes (quant
+analysis jobs, agents) pull them in real time. One row per `(nest, term)`,
+case-insensitive. Reads are read-tier; writes are write-tier.
+
+### GET `/nests/:nestId/definitions`
+List the whole glossary, ordered by term.
+```json
+{
+  "count": 1,
+  "definitions": [{
+    "id": "...",
+    "nest_id": "...",
+    "term": "CAC",
+    "definition": "Customer acquisition cost: S&M spend / new customers, 90d.",
+    "linked_tag": "#gtm",
+    "defined_by": "owner@acme.com",
+    "created_at": "...",
+    "updated_at": "..."
+  }]
+}
+```
+
+### GET `/nests/:nestId/definitions?term=CAC`
+Real-time single lookup — one indexed, case-insensitive query. `404` if the term
+isn't defined.
+```json
+{ "definition": { "id": "...", "term": "CAC", "definition": "...", "linked_tag": "#gtm", "defined_by": "...", "created_at": "...", "updated_at": "..." } }
+```
+
+### POST `/nests/:nestId/definitions` (write+)
+Upsert by term text (case-insensitive). New term → `201`; re-defining an existing
+term updates it in place → `200`.
+```json
+{ "term": "CAC", "definition": "...", "linked_tag": "gtm", "editing_id": "<id?>" }
+```
+- `term` required, ≤ 200 chars. `definition` required. Non-string `term`/`definition`/`linked_tag` → `400`.
+- `linked_tag`: omit = leave unchanged on update; `null`/`""` = clear; string = set (normalized to `#lowercase`).
+- `editing_id` (optional): the id of the row being edited. Scopes the upsert to
+  that row so a **rename replaces it in place** instead of overwriting whichever
+  row happens to own the new term. If the new term already belongs to a
+  **different** row → `409` (no data loss). Unknown `editing_id` → `404`. Omit it
+  for the plain add form and real-time writers (pure upsert-by-term).
+
+### DELETE `/nests/:nestId/definitions/:id` (write+)
+```json
+{ "deleted": true }
+```
+`404` if the id isn't in this nest.
+
+---
+
+## 8c. Edge-type registry ("turing" workflow plane)
+
+The vocabulary of connections: the definitions-table move applied to relations.
+Stewards articulate once what `next` or `escalates-when` MEANS in a nest; edges
+then reference the registry. **Feature-flagged** — every route here `404`s
+unless `FEATURE_WORKFLOW_PLANE` is on (env var or the admin-settings toggle).
+Reads are read-tier; writes are write-tier. One row per `(nest, name)`,
+case-insensitive.
+
+On first touch a nest is lazily seeded with five stock types (attributed to the
+nest owner): `next`, `on-success`, `on-failure` (flow types, form the DAG),
+`depends-on`, `owned-by`.
+
+### GET `/nests/:nestId/edge-types`
+List the registry, ordered by name. Seeds the defaults if empty.
+```json
+{
+  "count": 5,
+  "edge_types": [{
+    "id": "...",
+    "nest_id": "...",
+    "name": "next",
+    "description": "Unconditional flow: after the source completes, run the target.",
+    "direction": "directed",
+    "is_flow": true,
+    "condition_schema": null,
+    "color": "#16a34a",
+    "created_by": "owner@acme.com",
+    "created_at": "...",
+    "updated_at": "..."
+  }]
+}
+```
+
+### POST `/nests/:nestId/edge-types` (write+)
+Upsert by name (case-insensitive). New name → `201`; re-defining an existing
+name updates it in place → `200`.
+```json
+{
+  "name": "escalates-when",
+  "description": "Conditional escalation on a metric guardrail.",
+  "direction": "directed",
+  "is_flow": true,
+  "color": "#f59e0b",
+  "condition_schema": { "params": ["term", "op", "value"], "mode_default": "structured" }
+}
+```
+- `name` required, ≤ 100 chars, `^[a-z0-9][a-z0-9-]*$` (alphanumeric-with-dashes). `description` required.
+- `direction`: `directed` (default) | `undirected`. Anything else → `400`.
+- `is_flow`: boolean, default `false`. Flow types form the workflow DAG.
+- `color`: optional 6-digit hex (e.g. `#16a34a`). A malformed color → `400` (not silently dropped).
+- `condition_schema`: optional `{ "params": [string…], "mode_default"?: "structured"|"nl"|"open" }`. Malformed → `400`. Stored normalized (`mode_default` defaults to `structured`).
+
+### DELETE `/nests/:nestId/edge-types/:id` (write+)
+```json
+{ "deleted": true }
+```
+`404` if the id isn't in this nest. `400` if edges still reference the type
+(delete those edges first — the DB enforces this with `ON DELETE RESTRICT`).
+
+---
+
+## 9. Query / Search (read-only consumers)
+
+These power LLM context retrieval. Open-mode friendly.
+
+### GET `/nests/:nestId/search?q=<term>`
+Full-text search.
+```json
+{ "count": N, "nodes": [{ "id": "...", "title": "...", "tags": [...] }] }
+```
+
+### GET `/search?q=<term>&limit=20`
+The same match, run across every nest the caller can see — for finding a
+document without knowing which nest holds it. Each hit is stamped with its
+nest, and per-nest stewardship filtering still applies, so results never
+include a document the caller couldn't open directly.
+
+`limit` caps the returned page (default 20, max 50) while `count` reports
+everything found. `400` if `q` is missing.
+```json
+{
+  "query": "onboarding",
+  "count": 2,
+  "nodes": [
+    {
+      "id": "nodes/onboarding-runbook",
+      "title": "Onboarding Runbook",
+      "type": "document",
+      "tags": ["#hr"],
+      "snippet": "how to onboard a...",
+      "nest_id": "nest_abc",
+      "nest_name": "Team Knowledge"
+    }
+  ]
+}
+```
+
+### POST `/nests/:nestId/context`
+One-call context retrieval for app/agent flows. Returns markdown ready to
+prepend to an LLM prompt, plus a trace + node manifest. **Requires a license**
+(it's a `POST`).
+
+Body (give `prompt` OR `selector`; everything else optional):
+```json
+{
+  "prompt": "how does auth work",
+  "selector": "#auth",
+  "max_tokens": 4000,
+  "hops": 2,
+  "include_drafts": false
+}
+```
+- `prompt` — natural language. Tokens are matched against tag names and titles, and every document is scored against them (title hits weigh most, then tags, then body words); documents under half the top score are dropped as noise. A prompt that matches nothing returns `nodes: []` — never the whole nest. `trace.compiled.fallback` is `"fulltext"` when body scoring alone produced the answer.
+- `selector` — explicit selector grammar (e.g. `#auth`). Wins over `prompt`.
+- `hops` — wikilink expansion depth. Defaults to `0` for a `prompt` (neighbours of a keyword match are not answers to the question) and `2` for a `selector`.
+- `max_tokens` — budget, floored at 50, default 4000. A node that doesn't fit is skipped and the next tried (`trace.truncated_by_budget` counts the skips); only when nothing fits does the first node go through oversized.
+- 400 `prompt or selector is required` if both missing.
+- Each node carries a `url` deep link, and its context block a matching `_source: <url>_` line, so answers can cite sources. Built from `PUBLIC_BASE_URL`, falling back to the request origin; omitted when neither resolves.
+- On the `prompt` path each node also carries `score` (0–1; title hits weigh most, then tags, then body) and `via` (`"title"` | `"tag"` | `"fulltext"` | `"hop"`). `nodes` and the `context` blocks are ordered by score, so the budget keeps the best matches. Cite `via != "hop"`. Selector-path responses omit both fields.
+
+Response (200):
+```json
+{
+  "context": "# Auth Overview\n\n_tags: #auth #security_\n_source: http://localhost:3838/?nest=<nestId>&doc=nodes/auth-overview_\n\n# Auth\n\n...",
+  "nodes": [{ "id": "nodes/auth-overview", "title": "Auth Overview", "url": "http://localhost:3838/?nest=<nestId>&doc=nodes/auth-overview", "tags": ["#auth"], "type": "document", "score": 0.67, "via": "tag" }],
+  "trace": {
+    "selector_used": "#auth",
+    "from_prompt": "how does auth work",
+    "compiled": { "matched_tags": ["auth"], "matched_titles": [], "unmatched_tokens": ["work"], "fallback": null },
+    "included": 1,
+    "permission_filtered": 0,
+    "truncated_by_budget": 0,
+    "approx_tokens": 24,
+    "max_tokens": 4000
+  }
+}
+```
+
+```bash
+curl -X POST 'http://localhost:3838/nests/<nestId>/context' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer cnst_...' \
+  -d '{"prompt":"how does auth work","max_tokens":4000}'
+```
+Permission gating matches `/export` (public readers only see approved bodies).
+
+### GET `/nests/:nestId/export?format=markdown` — LLM-pointed plain-text view
+Stable URL an agent can fetch to get **`text/markdown`** (not JSON): every
+accessible node serialized as YAML frontmatter + body, joined with `---`
+separators. A `GET`, so it works on public nests without a license/credentials.
+
+**Approved-only, for every caller.** Export never emits unapproved drafts —
+not even for the owner. On a governed (stewardship-on) nest, each node's body
+is its **approved version**, and nodes with no approved version yet are
+omitted entirely. On an ungoverned nest there's no draft concept, so the
+current body is exported.
+
+Query params:
+- `format=markdown` — **required** (else 400 `format=markdown is required`).
+- `selector=<grammar>` — optional, narrows the set (e.g. `#auth`).
+- `max_tokens=<n>` — optional budget; full set by default.
+
+Response (`text/markdown; charset=utf-8`):
+```markdown
+---
+title: "Auth Overview"
+tags: ["#auth", "#security"]
+status: "published"
+id: "nodes/auth-overview"
+---
+# Auth
+
+We use device auth + email/password fallback.
+
+---
+
+---
+title: "Rate Limits"
+tags: ["#api"]
+status: "published"
+id: "nodes/rate-limits"
+---
+# Limits
+
+100 req/min per key.
+```
+
+```bash
+# whole nest
+curl 'http://localhost:3838/nests/<nestId>/export?format=markdown'
+
+# narrow by selector
+curl 'http://localhost:3838/nests/<nestId>/export?format=markdown&selector=%23auth'
+
+# cap output size
+curl 'http://localhost:3838/nests/<nestId>/export?format=markdown&max_tokens=2000'
+```
+
+Single node, same shape — add `?format=markdown` to the node read:
+```bash
+curl 'http://localhost:3838/nests/<nestId>/nodes/nodes/auth-overview?format=markdown'
+```
+Public readers receive the **approved** version body, never an unapproved
+working-copy draft (same gate as `/context`).
+
+### GET `/nests/:nestId/export?format=bundle` — portability bundle
+
+Downloads a `.zip` of the nest's documents to move it to another ContextNest host. Each document is serialized from its approved/published state (`status: published`). Any collaborator with nest access (viewer and up) may export — same gate as the markdown export above. There is **no** separate import endpoint — unzip the bundle and bring it in with the existing folder importer (`POST /nests/import`).
+
+- `?includeDrafts=1` — also export unapproved draft documents. Default: approved/published only.
+
+Identities/attribution and the governance overlay (stewards, reviews, comments, definitions, edges, grants) do **not** travel; the importer owns and re-governs the fresh nest.
+
+```bash
+curl -OJ 'http://localhost:3838/nests/<nestId>/export?format=bundle'
+curl -OJ 'http://localhost:3838/nests/<nestId>/export?format=bundle&includeDrafts=1'
+```
+
+### POST `/nests/:nestId/table-query`
+Deterministic fact lookup against a **table** node (CSV body): fetch the exact rows instead of dragging the whole table into context. Same query against the same version always returns the same rows. Read permission; drafts excluded unless `include_drafts: true`.
+```json
+{ "table": "[[Price List]]", "query": "where region = \"EU\" and price > 100 select sku, price limit 5" }
+```
+`table` is a `[[Title]]` or a node id (`nodes/price-list`). Grammar: `where <col> <op> <value> [and …] [select <cols>] [limit N]`. Response:
+```json
+{ "table": "nodes/price-list", "version": 3, "columns": ["sku", "price"], "rows": [["A-1", "120"]], "matched": 7, "returned": 5, "total": 1000 }
+```
+Same operation over MCP: `context_table_query`.
+
+### POST `/nests/:nestId/query`
+Graph query (Cypher-ish).
+
+### GET `/nests/:nestId/overview`
+Nest-level summary stats.
+
+### GET `/nests/:nestId/context`
+Returns CONTEXT.md content.
+
+### GET `/nests/:nestId/folders`
+The nest's folder tree on its own, for callers that want the *shape* of the vault
+(a navigable tree, a folder picker) and none of its content. Per-folder counts come
+from the document index and the folders themselves from the vault's directories —
+no document is opened either way, so this stays cheap on a vault where listing the
+documents would not be. A folder holding no document is listed with `count: 0`.
+
+Query: `?folder=<path>` (that subtree only; defaults to the whole nest),
+`?recursive=0` (direct children of `folder` only).
+
+```json
+{ "folders": [{ "path": "specs", "count": 4, "total": 11 }] }
+```
+
+`count` = documents filed directly in that folder; `total` = the whole subtree
+beneath it. A level that holds only subfolders still gets a row, so it stays
+expandable.
+
+### POST `/nests/:nestId/folders`
+```json
+{ "folder": "gtm/deals" }
+```
+Creates a folder with nothing in it — the directory is created in the vault
+carrying only its generated `INDEX.md`, so no document is added to the nest.
+Each segment is slugified (`GTM/Deals` → `gtm/deals`) and the depth cap applies.
+Creating a folder that already exists is a no-op. Write tier.
+
+```json
+{ "folder": "gtm/deals" }
+```
+Returns 201 with the path actually created.
+
+### GET `/nests/:nestId/census`
+One call for everything a nest overview needs to describe the *whole* nest,
+whatever folder is open — counts by tag, type and status, the folder tree, the
+author roster, and the recently-edited strip. Gated by the same `filterAccessible`
+pass as the listing, so the numbers describe what this caller can actually reach.
+
+```json
+{
+  "census": {
+    "total": 42,
+    "folders": [{ "path": "specs", "count": 4, "total": 11 }],
+    "tags": { "#api": 7 },
+    "types": { "document": 40, "agent": 2 },
+    "statuses": { "approved": 30, "draft": 12 },
+    "authors": ["a@x.com"],
+    "editedLast7d": 5,
+    "recent": [{ "id": "nodes/foo", "title": "Foo", "type": "document", "updated_at": "..." }]
+  }
+}
+```
+
+### POST `/nests/:nestId/reindex` (write+)
+Force-rebuild the nest's document index from the vault, and return how many
+documents were indexed: `{ "indexed": 42 }`.
+
+The index heals itself — anything that could leave it out of step with disk (an
+out-of-band edit, an import, a write that could not be mirrored) marks the nest
+stale, and the next read rebuilds before answering. This is the manual lever for
+when an operator wants that to happen *now*. A rebuild crawls the whole vault, so
+it is write-tier rather than something a read-only caller can trigger at will;
+below that the answer is `403`.
+
+### GET `/nests/:nestId/graph` (read+)
+Ontology graph — a read-only assembly over data the nest already holds, for the
+graph view (links / stewardship overlay / coverage gaps). Gated to what the
+caller can read (same `filterAccessible` pass as the other query routes).
+
+Response `NestGraph`:
+```json
+{
+  "nodes":   [{ "id": "nodes/alpha", "title": "Alpha", "type": "document", "tags": ["market-x"] }],
+  "links":   [{ "source": "nodes/alpha", "target": "nodes/beta" }],
+  "stewards":[{ "id": "jane@acme.com", "label": "jane@acme.com", "role": "reviewer", "scope": "tag", "target": "market-x" }],
+  "stewardEdges":[{ "steward": "jane@acme.com", "target": "tag:market-x", "scope": "tag" }],
+  "tags":    [{ "name": "market-x", "count": 2 }],
+  "signals": {
+    "orphans": [{ "id": "nodes/loose", "title": "Loose" }],
+    "unstewardedTags": [{ "name": "market-y", "count": 1 }],
+    "bottlenecks": [{ "steward": "jane@acme.com", "label": "jane@acme.com", "share": 67 }]
+  },
+  "truncated": false,
+  "totalNodes": 3
+}
+```
+
+Notes:
+- **Identity masking** — steward `id`/`label` are the real email only for **write+**
+  callers (same rule as the collaborators roster, so a public/read tier can't
+  enumerate member emails). Sub-write callers get an opaque `"s1"` id and a
+  `"Steward 1"` label; `bottlenecks[].label` follows suit.
+- **Roster gating** — `stewards`/`stewardEdges` are empty for public/anonymous
+  readers and when the nest has stewardship disabled.
+- **Draw cap** — `nodes`/`links` are capped at 150 (highest-degree kept) with
+  `truncated: true` and `totalNodes` set; `signals` are still computed over the
+  full set so the gap numbers stay accurate.
+
+### GET `/nests/:nestId/runnables` (read+)
+Orchestrator surface: every **runnable** node (`type` `agent` or `skill`) with its
+`schedule` and body in one call, so an external scheduler can connect, discover
+what to run and when, and pull the prompt/skill content. Reuses the same
+per-caller gating as the node list (`listNodesForCaller`), so stewardship and the
+public-reader approved-only rule apply — a read-tier orchestrator key only ever
+sees **approved** agent/skill definitions; unapproved drafts are omitted.
+
+```json
+{
+  "count": 1,
+  "runnables": [{
+    "id": "nodes/nightly-digest-agent",
+    "title": "Nightly Digest Agent",
+    "type": "agent",
+    "schedule": "0 6 * * *",
+    "status": "published",
+    "tags": ["#ops"],
+    "updated_at": "...",
+    "content": "# Agent\n\n..."
+  }]
+}
+```
+- `schedule` is `null` when the node carries no schedule.
+- Filtering to runnable types happens before the per-node governance/version
+  enrichment, so cost scales with the number of runnables, not total nest size.
+
+### POST `/nests/:nestId/publish`
+Bulk-create documents (and/or update `CONTEXT.md`) in one call. Each document
+routes through the same create path as `POST /nests/:nestId/nodes` — same slug
+derivation, same governance rows, same content-type policy gate (a disabled
+`artifact`/`table` type fails the whole batch up front, before any write).
+
+Body: `{ documents?, context_md? }` — at least one required.
+`documents[]` rows are `{ title, content, type?, tags?, scope? }`; rows missing
+`title` or `content` are skipped silently (a shape problem, not a policy one).
+
+A document whose title slugs to an id that already exists is **skipped and
+reported** — never overwritten, so republishing a folder cannot destroy an
+existing document's version history.
+
+A document the create path rejects for its own reasons — a title that is too
+long or carries no sluggable characters, a `type` the engine does not know — is
+**reported in `failed` and the batch continues**. One bad row cannot abandon the
+rest half-written.
+
+```json
+{
+  "published": 2,
+  "context_md_updated": true,
+  "node_ids": ["nodes/alpha", "nodes/beta"],
+  "skipped": ["Existing Doc Title"],
+  "failed": [{ "title": "Bad Row", "error": "..." }]
+}
+```
+
+Returns `201` whenever the batch ran, even if every row landed in `skipped` or
+`failed` — read the arrays, not the status, to know what happened.
+
+`context_md` is written directly rather than through an operation, because none
+exists for it. It is therefore outside the vault write lock and has no `503` to
+return — a `context_md`-only request cannot report contention.
+
+**Partial writes and retries.** The batch is not a transaction: documents are
+created one at a time and the ones written before a failure stay written. The
+one error that stops the batch early is the vault write lock being held past
+its acquire timeout, which answers `503` + `Retry-After`. Retrying is safe and
+finishes the job — every document from the first attempt now exists, so it
+comes back under `skipped` while the remaining ones are created. Expect a
+lower `published` count on the retry; that is the batch converging, not a
+failure.
+
+---
+
+## 8c. Publish links — public hosting of a single document
+
+Expose ONE document as a standalone page at a stable, unguessable
+`/p/<slug>` URL. Distinct from nest visibility (whole-nest read) and from
+grants (authenticated per-user sharing). Managing publish links is owner/admin
+only. Access modes: `public` (no auth), `code` (shared passcode), `email`
+(viewer enters an email → one-time magic link → access logged), `invite`
+(same, but only allow-listed emails get a link). Every served view is logged;
+links are revocable and can carry `expires_at`.
+
+### POST `/nests/:nestId/publications` (owner/admin)
+Body: `{ node_id, access_mode?: "public"|"email"|"code"|"invite",
+comments_enabled?: bool, watermark?: bool, no_download?: bool,
+code?: string (code mode), allowlist?: string[] (invite mode),
+expires_at?: ISO }`. → `201 { publish, link }`.
+
+`watermark` stamps the viewer's email across the page — email/invite gates only,
+since the other two identify nobody. `no_download` blocks copy, right-click,
+drag and printing; both are deterrents, not protection (screenshots and
+developer tools still work). `400` when `node_id` names no document in the nest,
+or when `email`/`invite` is requested on a server with no mail transport
+(`SMTP_URL` + `NOTIFY_EMAIL_FROM`) — their one-time link could never be sent.
+
+### GET `/nests/:nestId/publications` (owner/admin)
+List this nest's publish links with their `link` URLs.
+
+### GET `/nests/:nestId/publications/:id/views` (owner/admin)
+The access log — `{ count, views: [{ email, created_at }] }`.
+
+### DELETE `/nests/:nestId/publications/:id` (owner/admin)
+Revoke — the link 404s immediately.
+
+### Public render surface (no auth chain)
+- `GET /p/:slug` — the document, a gate form (email/code/invite), or — when
+  `comments_enabled` — a reader shell framing the document beside the comment
+  control. Document bodies are served under the strict artifact sandbox
+  (opaque origin); markdown nodes are rendered server-side.
+- `GET /p/:slug/view` — the document itself, always sandboxed. The shell frames
+  it; gated independently, so being the frame source is not authorization.
+- `POST /p/:slug/gate` — submit a code (unlock) or an email (send magic link).
+  Rate limited per link per IP.
+- `GET /p/:slug/verify?token=` — consume a magic link → set session cookie → open.
+  Invite mode re-checks the allow-list here, not only when the link was sent.
+- `POST /p/:slug/comments` — JSON `{ body, email? }`, from the shell's modal.
+  Needs the gate cleared and an identifying email; lands as an unanchored
+  annotation thread for stewards, never on the published page.
+
+Only the approved version is ever served — a document with no approved snapshot
+404s rather than exposing a draft. A revoked, expired or unknown slug answers
+every route above with the same HTML notice, never a hint about which it was.
+
+---
+
+## 9b. Workflow plane ("turing")
+
+**Feature-flagged — every route below `404`s unless `FEATURE_WORKFLOW_PLANE=true`** (Settings → Workflow plane). Typed edges, an edge-type registry, and governed runs. Full contract in [`WORKFLOW_PLANE.md`](./WORKFLOW_PLANE.md). Reads are read-tier, mutations write-tier via the standard nest gate.
+
+### Edge types — the vocabulary of relations
+
+- `GET /nests/:nestId/edge-types` (read) — list the registry. Seeds the five stock flow types (`next`, `on-success`, `on-failure`, `depends-on`, `owned-by`) on first touch.
+- `POST /nests/:nestId/edge-types` (write) — upsert by name (case-insensitive). Body: `{ name, description, direction?, is_flow?, condition_schema?, color? }`. `name` is a slug (`^[a-z0-9][a-z0-9-]*$`); `is_flow` types are DAG-validated; `condition_schema` is `{ params: string[], mode_default? }`. `201` on create, `200` on update.
+- `DELETE /nests/:nestId/edge-types/:id` (write) — refused (`400`) while any edge references it.
+
+### Edges — typed, condition-carrying links
+
+- `GET /nests/:nestId/edges?type=<name|id>&node=<id>` (read) — list, optionally filtered by edge type and/or an endpoint node.
+- `POST /nests/:nestId/edges` (write) — Body: `{ from_node, to_node, type, condition_mode?, condition?, metadata? }`. Both endpoints must be real nodes in the nest; `type` must exist in the registry. `condition_mode` ∈ `structured | nl | open` (`structured` predicates whose `term` must resolve against the glossary). Creating a flow edge that would close a cycle → `409` naming the path.
+- `DELETE /nests/:nestId/edges/:id` (write).
+
+### Runs — the operational trace (server never executes)
+
+- `POST /nests/:nestId/run/:agentNode` (write) — trigger a run. Body: `{ inputs?, parent_run_id? }`. Returns `201` with the executable **bundle**: `{ run_id, parent_run_id, depth, agent{content,…}, edges[<reachable flow subgraph>], definitions[], trace_hint }`. `triggered_by` is derived from auth, never client-supplied. Only `agent`/`skill` nodes are runnable (else `400`). `parent_run_id` spawns a **sub-agent run** nested under a still-running parent (`FEATURE_SUBAGENT_RUNS`, off by default — any `parent_run_id` is `400` while off); it's bounded by `SUBAGENT_MAX_DEPTH` (depth → `403`) and `SUBAGENT_MAX_CHILDREN` (fan-out → `403`, enforced atomically with the insert), rejects re-entrancy of an agent already in the ancestor chain (`409`), and refuses a closed (`409`) or unknown/cross-nest (`404`) parent.
+- `POST /runs/:id/steps` (write) — append one step. Body: `{ action: read|write|branch|notify|external, node_id?, edge_id?, detail? }`. `seq` is server-assigned (monotonic, atomic); any client `seq` is ignored. `409` if the run is already terminal, or once the run hits `RUN_MAX_STEPS`.
+- `PATCH /runs/:id` (write) — close/update. Body: `{ status: running|succeeded|failed|cancelled, trace? }`. Compare-and-swap on `status='running'`: a second close → `409` ("terminal is final").
+- `GET /runs/:id` (read) — full trace `{ run, steps[] }`. Freeform payloads (`run.inputs`, `run.trace`, `steps[].detail`) are redacted to `null` below write tier.
+- `GET /nests/:nestId/runs?agent=&status=&limit=` (read) — run history, newest first (same read-tier redaction).
+
+> The `/runs/:id*` family mounts outside the per-nest gate, so it re-checks nest-scope keys, suspension and license itself before any write — the same guarantees the `/nests/:nestId/*` gate provides.
+
+### Schedules — run an agent on a timer
+
+- `GET /nests/:nestId/schedules` (read) — list.
+- `POST /nests/:nestId/schedules` (write) — Body: `{ agent_node, every_minutes, enabled?, max_runs? }`. `max_runs` stops the schedule after that many runs.
+- `PATCH /nests/:nestId/schedules/:id` (write) — `{ every_minutes?, enabled? }`.
+- `DELETE /nests/:nestId/schedules/:id` (write).
+
+Archived nests are skipped by the scheduler tick; restoring the nest resumes them.
+
+### Inbound hooks — let the outside world trigger a run
+
+- `GET /nests/:nestId/hooks?agent=` (read) — list, tokens masked.
+- `POST /nests/:nestId/hooks` (write) — Body: `{ agent_node, preset }` with `preset` = `slack` | `teams` | `webhook`. Returns the secret URL once.
+- `DELETE /nests/:nestId/hooks/:id` (write) — accepts the full token or the masked id.
+- `POST /hooks/:token` (public — the token is the auth) — fire it. The Slack and Teams presets verify the request signature against `SLACK_SIGNING_SECRET` / `TEAMS_WEBHOOK_SECRET` in the nest's env store; the message text becomes the run's `inputs`. `404` while the nest is archived.
+
+### Env — per-nest secrets for tools and the runner
+
+- `GET /nests/:nestId/env` (write+) — names and masked tails only; values are never read back.
+- `PUT /nests/:nestId/env` (write+) — `{ key, value }` creates or replaces.
+- `DELETE /nests/:nestId/env/:key` (write+).
+
+Values ride to the runner inside the run bundle. `ANTHROPIC_API_KEY` here overrides the server-wide default from Settings.
+
+### Connectors — governance events out to a channel
+
+Not behind the workflow-plane flag: connectors fire on review events too.
+
+- `GET /nests/:nestId/connectors` (read).
+- `POST /nests/:nestId/connectors` (write) — Body: `{ channel, url, events }`. `channel` = `slack` | `teams` | `webhook`; `url` is a literal `https://…` or `env:KEY` to pull it from the env store; `events` is a non-empty array of `review_requested`, `review_approved`, `review_rejected`, `run_failed`, `mention`, or `["*"]`.
+- `PATCH /nests/:nestId/connectors/:id` (write) — `{ enabled?, events?, url? }`.
+- `DELETE /nests/:nestId/connectors/:id` (write).
+
+---
+
+## 9. MCP
+
+### `/nests/:nestId/mcp/*`
+Model Context Protocol endpoints — JSON-RPC over HTTP. Not exercised manually; LLM clients connect here.
+
+**Transport is read-tier.** MCP Streamable HTTP is always POST (even `initialize` / `tools/list`), so the per-nest gate admits any credential with read access; every mutating tool re-checks its own permission inside the tool handler (create/edit via stewardship, approve/reject via reviewer rights, stewards/sharing/sync via their own admin checks).
+
+**Denials are JSON-RPC.** Gate rejections on the MCP transport path return a JSON-RPC error envelope — `{ "jsonrpc": "2.0", "id": <echoed>, "error": { "code": -32000, "message": "<what failed — actionable reason>" } }` — instead of plain `{error}` JSON, so external clients (PromptOwl, Claude Desktop, Cursor) surface *why* a connection failed: key scoped to a different nest, server suspended, license required, or nest not found / no access.
+
+**Titles are unique on this surface.** `context_get`, `context_update`, `context_versions`, `context_delete`, and `context_move` each resolve a document by title or by id (an id wins when both are sent, and an ambiguous title refuses rather than guessing). Title addressing is what makes uniqueness matter, so `context_create` refuses a title already used anywhere in the nest — including in another folder — and answers with the existing node's id plus what to do instead (`context_update` to change it, `context_move` to refile it). A duplicate would otherwise be unreachable by every tool here. REST `POST /nodes` keeps the looser rule (same title in a different folder is fine); both surfaces refuse a create whose id is already taken.
+
+**`context_search` is the REST search.** The tool runs the same index-backed match as `GET /nests/:id/search` — terms against the cached discovery set (title, body, type, tags), title hits first — and gates the *hits* with the same `filterAccessible` rule (public readers: approved-only; governed nests: steward coverage or a share grant), so the two surfaces return the same documents in the same order. It takes an optional `limit` (default 20, max 200) and answers `{ results, count }`: `count` is everything found, `results` the first `limit` hits, each with its LLM-visible body (approved version under stewardship; a hit with no approved version yet is listed but carries no body). It used to resolve every document's gated body *before* matching — one permission lookup plus one version reconstruction per node — which is what timed out `ctx search --vault <remote>` on large governed nests.
+
+**Deletion requests** mirror the REST + UI flow, so an agent isn't left at a dead end when `context_delete` refuses:
+- `context_request_deletion` — flag a document (by title/id), a `folder`, or the whole `nest` with a required `reason`. Read-tier: anyone who can see a thing may ask for its deletion. Nothing is removed; a refused `context_delete` now names this tool.
+- `context_deletion_queue` — pending (or `declined`) requests with their reasons and request ids.
+- `context_resolve_deletion` — `delete` or `decline` (note required) by request id. **Owner/admin only** — the transport is read-tier, so this per-tool check is the only thing between a viewer and a deleted nest.
+
+**Comments read AND write.** `context_comments` reads a document's threads (anchored quotes, replies, open/resolved) — the same annotation store the web UI's comments panel shows. Two write tools close the loop so an agent handed feedback can answer it rather than only read it:
+
+- `context_comment` — leave a comment. Omit `thread` to open a new whole-document thread; pass a `thread` id from `context_comments` to reply into it. One tool for both, because they differ only by that argument.
+- `context_resolve_comment` — resolve a thread, or `reopen: true` to put it back. The caller is recorded as the resolver, exactly as in the UI.
+
+Both are **read-tier**, matching REST (`isAnnotationAction` in `app.ts`): a reviewer who can see the document may comment on it. The transport is read-tier too, so each tool re-checks `canReadNode` itself — that check is the real gate. Deliberately *not* gated on an approved version: a reviewer comments on drafts, and writing a comment discloses nothing (the caller supplies the text), whereas *reading* threads stays gated because anchors quote draft body text. Both run the same side effects the REST routes do — the `@mention` fan-out (so tagging a human notifies them) and the derived `— Annotations` re-projection for artifacts, so an agent's comment doesn't leave that node stale. A `thread` that belongs to another document is refused by name rather than silently opening a new thread.
+
+`context_comments` is also available on the **server-level** endpoint (nest-parameterised, read-only). Comment visibility matches UI node visibility: collaborators/stewards who can read the node may read its threads even before approval; public readers remain blocked until the document is approved. Comment *writes* stay per-nest with the other write tools.
+
+**`context_my_drafts`** mirrors `GET /me/drafts`, nest-scoped: the caller's own unsubmitted (or rejected) documents in this nest, with their path and version. Capped at the 100 most recent; the reply says so explicitly when there are more, so an agent can't read a capped page as the whole set. Self-scoped by construction — it only ever returns rows the caller authored, in a nest they already hold read on, so it needs no permission check of its own. It exists because an agent otherwise cannot see its own unsubmitted work: a draft has no review request, so `context_review_queue` never lists it, and `context_query` skips it (only approved versions are AI-readable). The response names `context_submit_review` as the next step.
+
+Server-admin-only tools (gated by `isLicenseAdminUserId` in non-open mode, same as their REST counterparts):
+- `context_unsynced_list` — mirrors `GET /nests/unsynced`.
+- `context_sync_folder` — mirrors `POST /nests/unsynced/sync`. Args: `name` (folder path relative to `DATA_ROOT`).
+
+Both reuse the same `listUnsyncedFolders` / `syncUnsyncedFolder` service functions the REST routes call, so a single fix lands in both surfaces.
+
+### Workflow-plane tools (only advertised when `FEATURE_WORKFLOW_PLANE=true`)
+
+Let an MCP agent **build and execute** governed workflows without leaving the tool surface. Each shares the exact service/validator code its REST counterpart uses (run-service, edge-routes, edge-type-routes), so the two surfaces can't drift. Write tools require write tier on the nest; run-detail tools additionally scope the `run_id` to the MCP nest.
+
+Build:
+- `workflow_edge_types_list` / `workflow_edge_type_upsert` / `workflow_edge_type_delete` — mirror the `/edge-types` routes.
+- `workflow_edges_list` / `workflow_edge_create` / `workflow_edge_delete` — mirror the `/edges` routes (DAG cycle guard + condition validation included).
+
+Execute (the runner contract — the agent IS the runner):
+- `workflow_run` — trigger; returns the executable bundle (agent body + reachable subgraph + definitions + `run_id`).
+- `workflow_run_step` — append a step (server-assigned `seq`).
+- `workflow_run_close` — close with a terminal status (`409`-equivalent conflict on a second close).
+- `workflow_run_get` / `workflow_runs_list` — read traces/history (freeform payloads redacted below write tier).
+
+### PromptOwl native connection (service-ticket auth)
+
+The official PromptOwl deployment connects on its users' behalf without storing
+a `cnst_` key: it mints a short-lived HS256 **service ticket** signed with the
+shared secret configured for it as an official community site (`/admin/community-sites`,
+or the legacy `OFFICIAL_COMMUNITY_SSO_SECRET` env var — see `CONFIGURATION.md`). The ticket
+carries `scope: "mcp"`, an `aud` bound to this server's `PUBLIC_BASE_URL`, a
+~5-minute `exp`, and **no `jti`**. It resolves to an already-existing account by
+email — native access never auto-provisions.
+
+Accepted as a `Bearer` on exactly these paths (everything else still requires a
+real credential):
+- `GET /index` and the server-level `ALL /mcp` — cross-nest index + read tools (including `context_comments`).
+- `POST /nests/:id/context` and `GET /nests/:id/nodes` — retrieval + doc listing.
+- `ALL /nests/:id/mcp` — the per-nest MCP transport, so a block granted read &
+  write on one nest reaches that nest's write tools. Per-nest permission,
+  suspend, and license gates all apply exactly as for a `cnst_` key.
+
+Two **server-level bootstrap writes** on `ALL /mcp` let a single-connection
+client create content (everything else on server-level `/mcp` is read-only):
+- `nest_create` — new nest owned by the caller (refused for a nest-scoped key).
+- `context_create` — new document in a nest the caller can write to
+  (`canCreateInNest`). Both honor the suspend kill-switch and license gate.
+
+**Ticket kinds don't cross over.** An `mcp`-scoped ticket is refused at
+`GET /auth/sso` (it can't become a login session), and the MCP middleware
+refuses any ticket carrying a `jti` (the mark of a one-time SSO login ticket) —
+enforced on both sides, not by trusting the issuer.
+
+---
+
+## 10. Admin / operator
+
+### GET `/health` (no auth)
+`{ "status": "ok" | "suspended", "version": "<server version>", … }`. Needs no key (like `/llms.txt` and public `/p/:slug` pages) — use it for liveness probes. `suspended` means the license was revoked and writes are refused until a valid key is installed.
+
+### Superadmins — GET/POST `/admin/super-admins`, DELETE `/admin/super-admins/:email` (server-admin only)
+Grant and revoke **superadmins** (server-wide admins) from the API/UI instead of only via `access.yaml`. The effective superadmin set is the union of three sources, surfaced per row as `source`:
+
+- `license` — the PromptOwl account that owns the installed license. Derived live; never revocable here.
+- `config` — `access.yaml` `super_admins`. The authoritative bootstrap: **never revocable via the API** (lockout safety) — edit the file and restart instead.
+- `granted` — rows in the `super_admins` DB table, managed by these endpoints.
+
+All three routes use the same server-admin guard as `GET /admin/trace` (license admin, or any effective superadmin; open mode: always allowed). Emails are case-insensitive and stored lowercased. A superadmin holds `admin` on every nest, sees `/admin/trace` + `/admin/settings`, and can manage teammates (`/auth/teammates`, invite, reset-password, remove).
+
+**GET `/admin/super-admins`** → `200`:
+```json
+{
+  "super_admins": [
+    { "email": "owner@acme.com", "source": "license", "granted_by": null, "granted_at": null, "self": true },
+    { "email": "ops@acme.com",   "source": "config",  "granted_by": null, "granted_at": null, "self": false },
+    { "email": "jane@acme.com",  "source": "granted", "granted_by": "owner@acme.com", "granted_at": "2026-07-17 14:03:22", "self": false }
+  ]
+}
+```
+An email present in several sources shows its least-revocable origin (`license` > `config` > `granted`). `self` marks the caller's own row.
+
+**POST `/admin/super-admins`** with `{ "email": "jane@acme.com" }` → `201 { email, source: "granted", granted_by }`.
+- `400` — missing/malformed email, or no user account with that email exists on this server (invite them as a teammate first).
+- `409` — already an effective superadmin (any source).
+
+**DELETE `/admin/super-admins/:email`** → `200 { ok: true, email }`. Guards:
+- `400` — target is the license admin, or an `access.yaml` entry (file is authoritative; remove from the file + restart).
+- `400` — **last-admin lockout guard**: you can't revoke *yourself* when you're the last effective superadmin (no license admin, no `access.yaml` entries, no other grants) — grant someone else first.
+- `404` — email has no granted row.
+
+Grants persist in the database and are loaded into the in-memory resolution cache at startup and after every grant/revoke, so they survive restarts. Surfaced in the UI on **Teammates → Superadmins** with per-source badges, add-by-email, and confirm-to-revoke.
+
+### Community sites — GET/POST `/admin/community-sites`, PATCH/DELETE `/admin/community-sites/:id` (server-admin only)
+Manage the **official community sites** trusted for one-click SSO auto-login (`GET /auth/sso` — see above). Each row is a `{ name, url, secret, is_active }` connection; `url` is a display/uniqueness field, not used for audience binding. `GET /auth/sso` tries an incoming ticket's signature against every *active* site's secret, and validates the ticket's `aud` claim against this deployment's own `PUBLIC_BASE_URL` (the same value for every candidate). Replaces the single `OFFICIAL_COMMUNITY_SSO_SECRET`/`PUBLIC_BASE_URL` env-var pair with a DB-backed list for the *secret* side — the env-var pair still works as an implicit extra "legacy" entry, so existing single-site deployments are unaffected. Surfaced in the UI at **Settings → Community sites**.
+
+Same server-admin guard as `/admin/super-admins` (license admin, any effective superadmin; open mode: always allowed).
+
+**GET `/admin/community-sites`** → `200 { community_sites: [{ id, name, url, secret_set, is_active, created_at, updated_at }] }`. `secret` is **write-only** — never returned, only whether one is set.
+
+**POST `/admin/community-sites`** with `{ name, url, secret, is_active? }` → `201` with the row shape above (`is_active` defaults to `true`).
+- `400` — missing name, invalid/non-http(s) url, or a secret under 16 characters.
+- `409` — a site with this url already exists.
+
+**PATCH `/admin/community-sites/:id`** — any subset of `{ name, url, secret, is_active }`; omit `secret` to keep the current one. Same validation and `409` as POST. `404` if the id doesn't exist.
+
+**DELETE `/admin/community-sites/:id`** → `200 { ok: true, id }`. `404` if the id doesn't exist.
+
+Active sites are loaded into an in-memory cache at startup and refreshed after every write, so `GET /auth/sso` never blocks on a DB round trip per request.
+
+### GET `/admin/trace` (server-admin only)
+Operator activity trail — one newest-first row per API request and per MCP tool call, so the server admin has a single place to audit what every client and agent did. Server-admin only: the license admin, or a `super_admin` in `access.yaml` (open mode: always allowed). Everyone else gets `403`. Cross-tenant data; not scoped to a nest.
+
+Rows are best-effort fire-and-forget writes to the `api_events` table (a broken trace table never fails a real request) on a rolling retention window of **`TRACE_RETENTION_DAYS`** days (default **14**; `0` = keep forever — see `CONFIGURATION.md`; also editable from Settings → Advanced). API rows come from a global request-logging middleware; MCP rows are logged inside `handleToolCall`, so both per-nest and server-level tool calls — including ones that throw — are captured.
+
+Query params (all optional):
+- `kind` — `api` or `mcp`. Omit for both.
+- `user` — substring match on caller email, or exact user id.
+- `nest` — filter to a single nest id.
+- `limit` — page size, clamped to `1..1000` (default `25`). Non-numeric values fall back to the default rather than erroring.
+- `offset` — rows to skip for pagination (default `0`). The UI pages in blocks of 25 (`offset = page * 25`).
+
+`total` is the full filtered row count (independent of `limit`/`offset`), so the client can render a pager. `count` is the number of rows on the current page.
+
+Response (200):
+```json
+{
+  "count": 2,
+  "total": 137,
+  "limit": 25,
+  "offset": 0,
+  "events": [
+    {
+      "id": 412,
+      "ts": "2026-07-03T13:58:44.812Z",
+      "kind": "mcp",
+      "method": null,
+      "path": null,
+      "tool": "context_overview",
+      "nest_id": "nest_abc",
+      "user_id": "usr_123",
+      "caller": "alice@acme.com",
+      "status": 200,
+      "duration_ms": 14
+    },
+    {
+      "id": 411,
+      "ts": "2026-07-03T13:58:44.790Z",
+      "kind": "api",
+      "method": "POST",
+      "path": "/nests/nest_abc/nodes",
+      "tool": null,
+      "nest_id": "nest_abc",
+      "user_id": "usr_123",
+      "caller": "alice@acme.com",
+      "status": 201,
+      "duration_ms": 23
+    }
+  ]
+}
+```
+- `kind` — `api` (HTTP request) or `mcp` (tool call).
+- `method` / `path` — set on `api` rows; `null` on `mcp` rows.
+- `tool` — set on `mcp` rows; `null` on `api` rows.
+- `caller` — resolved caller email (from the row's stored email or a join on `user_id`).
+- `status` — HTTP status for `api` rows; `200` (success) / `500` (threw) for `mcp` rows.
+- `duration_ms` — wall-clock duration of the call.
+
+Surfaced in the UI under the user menu → **Activity trace** (`ActivityTracePage`), with kind/user filters, 25-per-page pagination, and a refresh button.
+
+### GET `/nests/:id/trace` (nest owner / nest admin)
+The per-nest steward slice of the activity trace. Same response shape, pagination, and `kind` / `user` / `limit` / `offset` query params as `GET /admin/trace`, but every row is **always pinned to this nest server-side** — there is no `nest` param, and one supplied in the query is ignored, so a caller can never read another nest's activity through this endpoint.
+
+Authorization mirrors the grants / steward-roster rule (`canManageStewards`): the nest owner, an `admin` collaborator, the license admin, or an `access.yaml` `super_admin` (open mode: always allowed). Read/write collaborators get `403`; callers with no access to the nest get `404`.
+
+Surfaced in the UI from the nest view's overflow menu → **Activity trace** (owner/nest-admin only), which renders `ActivityTracePage` in nest-scoped mode (nest column hidden).
+
+---
+
+## Permission middleware quick-ref
+
+For any `/nests/:nestId/...` request, the middleware computes:
+- `permission` = effective nest perm: `owner | admin | write | read | none`.
+- Required level by path:
+  - `/collaborators`, `/visibility` → `admin`
+  - `/reader-mode` → `admin` at the middleware, then the handler hard-gates on `isServerAdminUserId` (superadmin only)
+  - Stewardship action paths (`/approve`, `/reject`, `/submit-review`, `/cancel-review`) → `read` (handler enforces fine-grained steward gating)
+  - Other non-GET → `write`
+  - GET → `read`
+
+Returns 403 `Insufficient permissions` if not met. Open-mode (`AUTH_MODE=open`) treats everyone as `owner`.
+
+License gate: any non-GET request OR any governance path requires a valid PromptOwl license (`/license/install`). 503 `License required` otherwise.
+
+---
+
+## Error shapes
+
+| Status | When |
+|---|---|
+| 400 | Validation error (`{ "error": "..." }`) |
+| 401 | Auth required |
+| 403 | Permission denied (`Insufficient permissions`, governance steward mismatch) |
+| 404 | Nest / node / steward not found, or caller has no permission |
+| 409 | Conflict (e.g., key already exists, version conflict) |
+| 429 | Rate limit |
+| 503 | License missing |
+
+---
+
+## Quick test sequence (Postman)
+
+1. `POST /auth/login` → grab session cookie OR `POST /auth/keys` → copy `api_key`.
+2. `POST /nests` → grab `nestId`.
+3. `PATCH /nests/:nestId/settings` → `{ "stewardship_enabled": true }`.
+4. `POST /nests/:nestId/nodes` → grab `node.id`.
+5. `POST /nests/:nestId/stewards` → `{ scope:"document", email:"rev@x.com", role:"reviewer", nodePattern:"<node.id>" }`.
+6. As `rev@x.com` → `POST /auth/register` (claims placeholder) → cookie stored.
+7. `GET /nests` as reviewer → nest visible (proves auto-collab worked).
+8. `GET /nests/:nestId/nodes` as reviewer → only the assigned doc visible (proves stewardship filter).
+9. As original user → `POST /nests/:nestId/nodes/:nodeId/submit-review`.
+10. As reviewer → `POST /nests/:nestId/nodes/:nodeId/approve` → 200.
+11. `GET /nests/:nestId/nodes/:nodeId/versions` → confirm `resolvedBy` populated on the approved version.