Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

feat(knowledge): put company documents first and list Drive and Notion files (#306)

Rufus7f1acd8dfe0e
diff --git a/packages/core/openexecutive/api/models.py b/packages/core/openexecutive/api/models.py
index 2f71bd6b..87f18ce5 100644
--- a/packages/core/openexecutive/api/models.py
+++ b/packages/core/openexecutive/api/models.py
@@ -131,6 +131,15 @@ class CompanyDocContent(BaseModel):
content: str
+class SyncedDocContent(BaseModel):
+ """One Google Drive file or Notion page as the knowledge base stored it."""
+
+ id: str
+ name: str
+ url: str | None = None
+ content: str
+
+
class HealthResponse(BaseModel):
status: str
builtin_knowledge_chunks: int
diff --git a/packages/core/openexecutive/api/routes/documents.py b/packages/core/openexecutive/api/routes/documents.py
index 25d9cc7e..296b2141 100644
--- a/packages/core/openexecutive/api/routes/documents.py
+++ b/packages/core/openexecutive/api/routes/documents.py
@@ -1,11 +1,21 @@
from __future__ import annotations
+import asyncio
+import logging
import tempfile
+from datetime import UTC, datetime
from pathlib import Path
+from typing import Any, Literal
from fastapi import APIRouter, Form, HTTPException, Request, UploadFile
-from openexecutive.api.models import CompanyDocContent, DocumentUploadResponse
+from openexecutive.api.models import (
+ CompanyDocContent,
+ DocumentUploadResponse,
+ SyncedDocContent,
+)
+
+logger = logging.getLogger(__name__)
router = APIRouter()
@@ -129,6 +139,36 @@ async def upload_document(
)
+def _store(request: Request | None) -> Any:
+ from openexecutive.config import get_settings
+ from openexecutive.knowledge.store import ChromaDBStore
+
+ if request is not None and hasattr(request.app.state, "store"):
+ return request.app.state.store
+ return ChromaDBStore(persist_directory=get_settings().vector_store_path)
+
+
+def _upload_domains(store: Any) -> dict[str, str]:
+ """filename → domain for uploaded documents, from their chunks' metadata.
+
+ The domain is only a label on the list; a store that cannot be read
+ leaves the list untagged rather than failing it.
+ """
+ from openexecutive.knowledge.store import ChromaDBStore
+
+ domains: dict[str, str] = {}
+ try:
+ rows = store.iter_chunk_metadata(ChromaDBStore.COMPANY_COLLECTION)
+ except Exception:
+ logger.exception("documents: could not read upload domains")
+ return domains
+ for _cid, md in rows:
+ filename, domain = md.get("filename"), md.get("domain")
+ if isinstance(filename, str) and isinstance(domain, str):
+ domains.setdefault(filename, domain)
+ return domains
+
+
@router.get("/documents")
async def list_documents(request: Request = None) -> dict: # type: ignore[assignment]
from openexecutive.config import get_settings
@@ -136,7 +176,169 @@ async def list_documents(request: Request = None) -> dict: # type: ignore[assig
settings = get_settings()
docs_dir = settings.company_profile_path.parent / "docs"
- return {"documents": list_company_docs(docs_dir)}
+ docs = list_company_docs(docs_dir)
+ domains = await asyncio.to_thread(_upload_domains, _store(request)) if docs else {}
+ return {
+ "documents": [
+ {**doc, "source": "upload", "domain": domains.get(doc["filename"])} for doc in docs
+ ]
+ }
+
+
+# ---------------------------------------------------------------------------
+# Connected sources (Google Drive, Notion): read-only lists, a viewer, and a
+# "Sync now" that runs one tick of the same sync the scheduler runs. Files
+# from these sources are managed where they live — removing one from the
+# shared folder / Notion integration is what drops it from the knowledge base.
+#
+# Declared before ``/documents/{filename}`` so "sources", "drive" and
+# "notion" are never read as an uploaded file's name.
+# ---------------------------------------------------------------------------
+
+SourceId = Literal["drive", "notion"]
+_SOURCE_LABELS: dict[str, str] = {"drive": "Google Drive", "notion": "Notion"}
+# A manual sync this soon after the last tick is refused: the sync is
+# incremental, so a second run finds nothing new and only spends API quota.
+SYNC_COOLDOWN_S = 60
+# Strong references to running manual syncs (the event loop holds tasks only
+# weakly, so an unreferenced one can be collected mid-run).
+_SYNC_TASKS: set[asyncio.Task[Any]] = set()
+
+
+def _source_module(source: str) -> Any:
+ if source == "drive":
+ from openexecutive.knowledge import drive_sync
+
+ return drive_sync
+ if source == "notion":
+ from openexecutive.knowledge import notion_sync
+
+ return notion_sync
+ raise HTTPException(status_code=404, detail="Unknown source")
+
+
+def _source_enabled(source: str) -> bool:
+ from openexecutive.config import get_settings
+
+ settings = get_settings()
+ if source == "drive":
+ return bool(settings.drive_sync_enabled)
+ return bool(settings.notion_sync_enabled and settings.notion_api_key)
+
+
+def _source_interval(source: str) -> int:
+ from openexecutive.config import get_settings
+
+ settings = get_settings()
+ if source == "drive":
+ return int(settings.drive_sync_interval_minutes)
+ return int(settings.notion_sync_interval_minutes)
+
+
+def _list_source(source: str) -> dict[str, Any]:
+ module = _source_module(source)
+ listing: dict[str, Any] = (
+ module.list_synced_files() if source == "drive" else module.list_synced_pages()
+ )
+ return listing
+
+
+def _source_status(source: str) -> dict[str, Any]:
+ listing = _list_source(source)
+ return {
+ "id": source,
+ "label": _SOURCE_LABELS[source],
+ "enabled": _source_enabled(source),
+ "syncing": bool(_source_module(source).is_syncing()),
+ "last_run": listing["last_run"],
+ "last_error": listing["last_error"],
+ "interval_minutes": _source_interval(source),
+ "file_count": sum(1 for f in listing["files"] if f["indexed"]),
+ }
+
+
[email protected]("/documents/sources")
+async def list_sources() -> dict:
+ return {
+ "sources": [
+ await asyncio.to_thread(_source_status, source) for source in _SOURCE_LABELS
+ ]
+ }
+
+
[email protected]("/documents/sources/{source}/sync", status_code=202)
+async def sync_source(source: SourceId) -> dict:
+ module = _source_module(source)
+ if not _source_enabled(source):
+ raise HTTPException(status_code=409, detail=f"{_SOURCE_LABELS[source]} is not connected")
+ if module.is_syncing():
+ raise HTTPException(status_code=409, detail="A sync is already running")
+ # The cooldown runs from the latest of the last successful tick's start
+ # and the end of the last tick in this process (failed ones included).
+ last_run = (await asyncio.to_thread(_list_source, source))["last_run"]
+ marks: list[datetime] = []
+ if last_run:
+ try:
+ parsed = datetime.fromisoformat(last_run)
+ marks.append(parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC))
+ except (TypeError, ValueError):
+ pass
+ if (finished := module.last_finished_at()) is not None:
+ marks.append(finished)
+ if marks:
+ elapsed = (datetime.now(UTC) - max(marks)).total_seconds()
+ if 0 <= elapsed < SYNC_COOLDOWN_S:
+ raise HTTPException(
+ status_code=429,
+ detail="Synced less than a minute ago. Try again shortly.",
+ headers={"Retry-After": str(int(SYNC_COOLDOWN_S - elapsed) + 1)},
+ )
+ runner = module.run_drive_sync if source == "drive" else module.run_notion_sync
+ task = asyncio.create_task(_run_manual_sync(source, runner))
+ _SYNC_TASKS.add(task)
+ task.add_done_callback(_SYNC_TASKS.discard)
+ return {"source": source, "status": "started"}
+
+
+async def _run_manual_sync(source: str, runner: Any) -> None:
+ try:
+ stats = await runner()
+ logger.info("documents: manual %s sync %s", source, stats)
+ except Exception:
+ # The sync module has already recorded a user-facing last_error.
+ logger.exception("documents: manual %s sync failed", source)
+
+
[email protected]("/documents/drive")
+async def list_drive_documents() -> dict:
+ listing = await asyncio.to_thread(_list_source, "drive")
+ return {"enabled": _source_enabled("drive"), **listing}
+
+
[email protected]("/documents/drive/{file_id}", response_model=SyncedDocContent)
+async def get_drive_document(file_id: str) -> SyncedDocContent:
+ from openexecutive.knowledge.drive_sync import read_synced_file
+
+ doc = await asyncio.to_thread(read_synced_file, file_id)
+ if doc is None:
+ raise HTTPException(status_code=404, detail="Document not found")
+ return SyncedDocContent(**doc)
+
+
[email protected]("/documents/notion")
+async def list_notion_documents() -> dict:
+ listing = await asyncio.to_thread(_list_source, "notion")
+ return {"enabled": _source_enabled("notion"), **listing}
+
+
[email protected]("/documents/notion/{page_id}", response_model=SyncedDocContent)
+async def get_notion_document(page_id: str) -> SyncedDocContent:
+ from openexecutive.knowledge.notion_sync import read_synced_page
+
+ doc = await asyncio.to_thread(read_synced_page, page_id)
+ if doc is None:
+ raise HTTPException(status_code=404, detail="Document not found")
+ return SyncedDocContent(**doc)
@router.get("/documents/{filename}", response_model=CompanyDocContent)
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index c4673e9a..cb67e6a7 100644
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@ -1391,6 +1391,19 @@ knowledge:
(DELETE /documents/{filename}) individual docs. Synced Notion pages
do NOT land here — see NOTION_WIKI.
+ The knowledge page shows ONE Company documents list: these uploads
+ plus synced Drive files and Notion pages (GET /documents/drive,
+ GET /documents/notion, each read from that sync's state file, with a
+ text view at /documents/{drive|notion}/{id} whose path comes from the
+ state record, never the caller). Synced rows are read-only — removing
+ the file from the folder / integration is what drops it. Each
+ connected source shows last_run, last_error and a Sync now button
+ (POST /documents/sources/{id}/sync: 202, or 409 not connected /
+ already running, 429 within 60 s of the last run). Both syncs hold a
+ per-process run lock (`_RUN_LOCK`), so a manual tick and the heartbeat
+ never overlap; the loser returns {"busy": 1}. Uploads from the page
+ no longer pick a domain and go in as `general`.
+
IDENTITY IS THE FILENAME. ingest_file takes an explicit `source_name`
that becomes the filename/source metadata AND the chunk-id namespace
(_make_chunk_id is an MD5 of it). The upload endpoint stages the body
@@ -1553,7 +1566,7 @@ knowledge:
nothing back.
general_catch_all: |
`general` is the domain an upload gets when nobody classified it: the
- default on POST /documents, the default option in the UI's picker, and
+ default on POST /documents (the knowledge page no longer offers a picker), and
what reconcile_company_docs assigns to a recovered document. It maps to no
specialist in DOMAIN_ALIASES, so retriever._with_general widens each
specialist's COMPANY filter to include it — otherwise an unclassified
diff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.json
index d251cc72..282b7ef6 100644
--- a/packages/core/openexecutive/architecture/prebuilt/api.json
+++ b/packages/core/openexecutive/architecture/prebuilt/api.json
@@ -1,7 +1,7 @@
{
"section_id": "api",
"title": "API Reference",
- "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). With local login (`OE_LOCAL_LOGIN=1`, which only `make dev` sets, and only while Google sign-in is not set up) a second middleware answers 403 to any request whose raw `Host` is not `localhost`, `127.0.0.1` or `[::1]` (except a webhook that verifies its caller: Google Chat always, Telegram only with a `TELEGRAM_WEBHOOK_SECRET` Telegram can send), and to any write whose `Sec-Fetch-Site` is present and not `same-origin`/`none`. The UI signs that owner in with no password and this API usually has no secret, so without it a web page in the owner's browser could drive the API as the principal — by DNS-rebinding its own hostname to 127.0.0.1, or by posting a plain form from another site or localhost port. CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat`, `POST /chat/stop` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. Each round of tool calls also emits an `activity` event (`{type, label, tool, iteration}`) naming what is running — progress only, forwarded verbatim and never persisted with the message, unlike an `action_taken` chip. A `session_id` in the body must be a chat the caller may use (the same ownership rule as `sessions`). If it isn't, the turn runs in a fresh chat instead, so nothing is written into someone else's session and the reply looks the same as for an unknown id. An unknown namespaced id (`slack:…`, `telegram:…` and so on) is ignored and a fresh chat is started, because those ids belong to the channel adapters and claiming one first would make the caller its owner. The client mints a `client_turn_id` and sends it with the turn; `POST /chat/stop` takes that id and halts the turn mid-flight, so the button is live from the moment Send is pressed rather than only once the first SSE byte arrives. A stopped turn emits a `stopped` event and then the usual `done` over the same still-open stream — never an `error` — and whatever streamed so far is persisted and flagged. The endpoint returns 404 both for an unknown id and for another caller's turn, so it cannot be used to probe which turns are live. An optional `memory_text` (1–2000 chars) is what peer memory records as the caller's words instead of `message` — the briefing handoffs send it because their seed quotes the Executive's own card; `POST /chat/upload` derives it from the typed text and filenames. Since it never reaches the transcript, the `chat_turn` audit row keeps it beside `message`. After the reply — a stopped or timed-out one too, before the `stopped` / `error` / `done` frames — a turn that looked at anything sends one `sources` event, `{type, session_id, sources: [{kind, title, url}], unavailable: [area]}`: `kind` is `company`, `knowledge`, `notion`, `research`, `document` or `web`, `url` is only ever an http(s) link or, for an earlier document, `/artifacts/<id>`, at most 12 sources (6 from the web, pages the reply cites first), and `unavailable` names parts of the analysis (\"finance\") whose specialist failed or said nothing every time it was asked. It is persisted with the reply as `chat_messages.sources`. A request that carries `x-caller-email` marks its turn signed in (`Session.web_caller_signed_in`), which Act as me needs on a deployment without local login. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}`, `GET /sessions/{id}/messages`, `DELETE /sessions/{id}`, `POST /sessions/{id}/messages/{message_id}/feedback`, `GET /sessions/{id}/followup` | List, read and delete saved chat sessions (assistant messages carry their row `id` and any `feedback`). The list is scoped to the caller. Every per-session route checks ownership, because session ids are guessable (`slack:dm:<user id>`, `telegram:<chat id>`): only the session's owner or the principal gets through, and a legacy row with no owner is the principal's alone. Anyone else gets the same 404 as for an unknown id, so the routes can't be used to find out which chats exist. The one other way in is having started the chat in this process (matched by Person id or verified email, so it survives the caller being added to the roster), which is how a caller the roster can't resolve keeps using their own chat. That record is in memory, so after a restart such an ownerless chat is refused for reads. The principal can continue someone else's ownerless chat without becoming its owner. Deleting a session also drops its in-memory copy, so a later turn naming that id starts fresh. The feedback route records 👍/👎 (`{\"feedback\": \"up\"|\"down\"|null}`) on one assistant reply; only the session's own caller or the principal may rate it. The rater is stored (`feedback_by_person_id`), and a 👎 on a reply to the rater's own message triggers a working-style pass for them (paced; see attunement). The chat stream's `done` event carries `message_id` for the persisted reply. The followup route returns `{\"suggestion\": string|null}` — one suggested next user message, written by the utility-fast model from the last few turns, that the chat composer shows as its greyed placeholder (Tab / → or the inline chip fills it in without sending). It is null unless the session ends on a persisted assistant reply, and null (uncached) when the model fails. Same ownership check as feedback; successful suggestions are cached in-process per (session, reply id). Messages from `GET /sessions/{id}/messages` carry each assistant reply's saved `sources` (the same shape as the chat stream's `sources` event, without `type`), so a reloaded chat shows them again. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily`, `GET /today/brief-delivery`, `GET /today/top-three`, `GET /today/weekly-review` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). `GET /today` carries the viewer's cached \"What's going on\" `narrative` with `narrative_generated_at` (when it was written) and `narrative_stale` (a fresher one is being written — the page re-polls; see Today). A proposal backed by a roster request carries `roster_request` (the new sender's server-derived details and held-message previews; the principal's only) and is answered through the `people` routes below. `brief-delivery` returns the latest morning brief or end-of-day digest that didn't reach the owner, as `{brief, at, problem, fix, readable}` in plain language (`readable` is false when it couldn't be written, so there is nothing to read), or null — null while briefs go out, once the cause is fixed, while the scheduler is off, and for anyone but the owner (`chat._caller_is_principal_or_unclaimed`); it carries no address or channel id. `top-three` and `weekly-review` feed the solo Briefing's own cards and answer only in solo mode and only to the principal (`workflows._caller_is_the_principal`: a principal match or no caller header, never an unclaimed roster); anyone else, and team mode, get null. `top-three` returns `{items: [{key, kind, text, why, slot}]}` — the morning brief's top three from the same code (`build_top_three(principal_due_soon())`), `slot` a free block like `10:00–11:00`, `\"\"` when none is left, null when no calendar was read — and is kept off `GET /today` because its calendar read may take up to 4 s. `weekly-review` returns the latest completed `weekly_review` run as `{run_id, completed_at, period, top_three, excerpt}` (next week's top three as plain text; `excerpt` when that list is empty), or null when none has completed. |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive`, `GET /people/requests`, `GET /people/requests/{id}`, `POST /people/requests/{id}/approve`, `POST /people/requests/{id}/decline`, `GET\\|POST /people/{id}/open-loops`, `POST /open-loops/{loop_id}/close`, `GET /people/{id}/outreach`, `GET\\|PUT\\|DELETE /people/{id}/attunement` | Roster CRUD and scope lookups. Every `Person` carries `kind` (`team` / `contact`). `GET /people` lists team members only unless `?include_contacts=true` (the People page asks for both; the department-head and workflow pickers keep the default); `POST` / `PATCH` accept `kind`, and a principal contact is a 422 either way. They also take `email_aliases` (other addresses the person writes from, at most 10; on `PATCH` the full list replaces the current one, omitted leaves it): an alias matches their mail and may be emailed but never signs in; a malformed one is a 422, and an alias — or a new primary `email` — that is already someone else's address or alias is a 409. Every `POST` / `PATCH` then closes any pending roster request whose sender now matches someone and replays its held messages. Adding, editing and archiving (`POST`, `PATCH`, `/archive`) are the principal's only, or anyone's while no one is principal yet so a first setup can add its owner (`chat._caller_is_principal_or_unclaimed`, the check behind `PUT /workspace`; a request with no `x-caller-email`, such as the CLI or local login, counts as the principal). Anyone else, a person editing their own row included, gets 403 before the person lookup, so it can't probe which ids exist. Contacts are private to the principal (`caller_is_principal`: the signed-in email is the principal's, or no `x-caller-email`; stricter than the owner rule above, so while no one is principal nobody is): for anyone else `include_contacts` is ignored, a contact's id is a 404 on `GET /people/{id}` and open-loops (exactly as for a missing id; `PATCH` and archive are already a 403 for them), and creating a contact or turning someone into one is a 403, even on a first setup with no principal yet. `GET /people/me` returns `{person_id, is_principal}` so the UI offers contacts to the principal only. `GET /people/by-scope/{token}` never returns a contact. Archiving a person closes their open loops. The open-loop routes list what a person owes (soonest due first) and close one (`reason`: done / not_needed / cancelled) — both the principal's or the owner's only (403 otherwise, via `people.store.is_principal_or_self`). `POST /people/{id}/open-loops` `{task, due_date?}` assigns that person a task (201 with the loop; `due_date` is a local date, due 17:00 in the user's timezone, clamped to 60 days, default 2 days): any active team member may assign anyone on the team, 403 for anyone else; 409 for an archived person, a contact (as seen by the principal), a person at the open-loop cap, a duplicate or open loops turned off; 422 for an empty task. Nobody is messaged at assignment — the owner is chased once it is due. `/outreach` returns, per kind of proactive outreach over 30 days, `sent` / `replied` / `acted` / `ignored` / `pending` (voided DMs are excluded) — same access rule, checked before the person lookup so it can't probe which ids exist. `/attunement` reads, replaces (`rules`: up to 4 strings, or omitted to only set `locked`) or resets the person's working-style rules — same access rule, 404 for an archived person; `PUT` rejects a rule that is not purely about style with 422. Archiving a person also drops their working style and frees their aliases. The **roster-request** routes (declared before `/people/{person_id}`) are the principal's alone (`caller_is_principal`; anyone else gets 404, as for a missing id): `GET /people/requests?status=pending|approved|linked|declined|expired|superseded|all` lists up to 100 (`id`, `channel`, `channel_ref`, sanitised `display_name`, `profile_email`, `on_company_domain`, `suggested_kind`, `suggested_person_id` / `_name`, `status`, `resolved_person_id` / `_kind`, `message_count`, timestamps, `ack_sent`, and `previews` of the held messages while pending — shown to the principal, never to a model); `approve` takes either `link_person_id` (+ `replace_channel_id`) or `full_name` + `kind` (no default: 422 without both) + optional `role`; `decline` takes no body. An answered request is a 409, a chat id or address already on someone else is a 409; the held messages are replayed (or dropped) in the background. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. A `cadences` spec that does not parse is rejected with a 422 (empty means no cadence). A new `head_person_id` must be a team member: an unknown id and one of the principal's contacts get the same name-free 422 (`person_id N is not on the team.`), so the route — open to any signed-in user — never reveals that a contact exists; an unchanged head is not re-checked. `POST .../goals` requires only `key_result`: a missing or blank `period_value` is filled with the current period for `period_type` in the user's zone (the same label `create_goal` uses), and `target` defaults to empty. `PATCH .../goals/{id}` rejects a blank `key_result` or `period_value` with a 422; `target` may be cleared. |\n| `agents` | `GET /agents`, `GET /agents/models`, `GET /agents/models/options`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. `/agents/models` is the flat model allowlist the PATCH validator uses; `/agents/models/options` returns the same ids in the same order, each tagged with `provider`, `provider_label`, `route` (`direct` / `openrouter` / `local`) and a display `label`, for the Council's Provider → Model picker. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `GET /artifacts/{id}`, `GET /artifacts/{id}/download?as=`, `POST /artifacts/{id}/archive`, `POST /artifacts/{id}/restore`, `DELETE /artifacts/{id}` | Browsable deliverables in any format — Markdown, HTML, Word, Excel, or a link into a connected app — with `format`, `downloads`, `external_url` and `supersedes_id` on every summary. `download` renders the file (Word/Excel built at request time from the stored text; any Markdown artifact, workflow output included, can export `?as=docx`) and is always an attachment with `nosniff` and a sandbox CSP. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET`/`PUT /decisions/classes/meeting_scheduling`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. An approval whose caller resolves to the principal runs the booking inside `grant_contact_egress()`, so a meeting the principal proposed with a contact can be created. Such a booking's payload is marked `private`: it is proposed to the principal, left out of anyone else's `GET /decisions`, and a 404 for them on `GET /decisions/{id}` and every action route. Reviewed in the briefing — there is no separate proposals page. The class routes read and set how meetings are handled: both return `{decision_class: \"meeting_scheduling\", mode: \"propose\" \\| \"auto_execute\"}` (default `propose`); the `PUT` body is `{mode}`, principal-only (403 otherwise, open before a principal exists — but then only `propose` can be set: `auto_execute` is a 409 until a non-archived principal is on the roster), 422 on any other mode, and a change writes a `decision_class_mode_changed` audit row. In solo mode the class mode decides a booking, and `auto_execute` applies only to a turn the principal started on a verified surface — any other turn gets a proposal. |\n| `delegation` | `GET`/`PUT /delegation`, `GET`/`PUT`/`DELETE /delegation/voice`, `POST /delegation/voice/learn`, `POST /delegation/voice/signature` | Act as me — the **caller's own** delegation only; nobody sets it for anyone else. `GET /delegation` returns `{enabled, gmail: {status, message, email, connect_command}}`, where `status` is `connected`, `not_configured`, `needs_reconnect`, `mismatch`, `no_email`, `shared_mailbox` or `error`, checked live with Google on each call. `PUT` takes `{enabled}` (any other field is a 422); turning it on needs the caller's own Gmail connected, otherwise a 409 whose code says why (`gmail_not_connected`, `gmail_needs_reconnect`, `gmail_mismatch`, `no_email`, `shared_mailbox`, `gmail_error`). The voice routes show, learn (from the caller's sent mail, one pass at a time — a 409 `in_progress`, `locked`, `too_soon`, `not_enough_mail`, `no_profile` or `changed` when it was locked or edited while learning, or a Gmail code), edit and lock, and reset \"How I write\": a typed field that fails validation is a 422 `invalid_voice` listing each `rejected` field, and `clear_exemplars` / `clear_signature` drop those. `POST /delegation/voice/signature` reads the signature from the caller's Gmail settings again and changes nothing else (a locked profile stays locked), with the same Gmail codes as learning: a 409 when their Gmail isn't connected, Google refuses it or the check itself fails (`gmail_error`), and a 502 `gmail_error` when reading the signature fails. A caller `can_delegate` refuses — anyone but the principal, for now — gets 403 `not_available_yet`, which hides the Settings card. A request with no `x-caller-email` is a 403 `sign_in_required` unless the API runs under local login — a header-less call is not a sign-in (the header itself is trusted from whoever holds the shared secret, the UI proxy, as on every principal-only route). Every change writes a private audit row. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts). Rows private to the principal (`private_to_principal`: a turn about their private mail, or a row naming one of their contacts on their own turn) are theirs alone: for any other caller, resolved as for `/alerts`, the list, its `total` and the usage totals leave them out, a private row's id is a 404, and a session shows only its other rows. |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `setup_status` | `GET /setup/status` | Settings → Setup status: one light per part of the install — AI model, company setup, owner, the Executive's address, API protection, Gmail, your own Gmail (Act as me), Slack, Discord, Telegram, Google Chat, the scheduler, the daily brief (when and where it goes) and Honcho — as `{checked_at, checks: [{id, label, state, summary, fix, link, last_activity}]}`, where `state` is `ok`, `warn`, `error` or `off` (optional and not set up), `fix` says what to do in plain language, `link` is an in-app page that helps (`/people`, `/onboard`) and `last_activity` is the channel's latest `integration_inbound` audit time. It tests live, with at most one free read-only call per service, each bounded to 5 s: Anthropic `models.list` (so an organisation key missing `ANTHROPIC_WORKSPACE_ID` shows up), Slack `auth.test`, Telegram `getMe` and `getWebhookInfo`, Discord `users/@me` only while the bot is still connecting, and — once the owner's own Gmail credential exists — Google's token refresh and Gmail `users/me/profile`. It also reads the listeners the lifespan leaves on `app.state` (Slack's socket, the Discord bot and its task, the MCP gateway), the scheduler heartbeat and the pause switch. When `google_workspace` is configured, the lifespan also starts `MCPGateway.prime_pinned_tools()` in the background (held on `app.state.mcp_prime_task`, cancelled at shutdown), so the pinned Google tools named in the prompt are callable without a search. With `DRIVE_SYNC_ENABLED` the lifespan also bootstraps the `drive_sync_scan` heartbeat beside Notion's (see Scheduler); the Drive folder sync has no HTTP route, only the `openexecutive sync-drive` / `purge-drive` CLI. Sample values copied from `.env.example` are named as such without being sent anywhere. No token reaches a response or a log line: probes report a status code, a service's short error code or an exception's class name. Requests within 5 s of a run get that run's answer and concurrent requests share one run (kept per app on `app.state`), so the button can't become a stream of calls to those services. Gated like every other route; the UI adds a sign-in light of its own, from its own settings. |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. Upload is keyed on the filename, so re-uploading a document replaces its chunks rather than duplicating them, and `DELETE` removes the rows as well as the file. `domain` must be one of the nine specialist domains (including `sales`) or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. A scanned PDF is converted (`knowledge.pdf_reader`) before it is indexed and in the text view, as are scanned PDFs in `POST /chat/upload` and the client / onboarding intake uploads. |\n| `executive` | `GET /executive/status`, `POST /executive/pause`, `POST /executive/resume` | Operator pause switch for all autonomous work (scheduler, Gmail poller, workflow resumer); inbound chat and DMs stay live. Status returns `{paused, paused_at, paused_by, reason, held_actions, can_resume}` — `held_actions` counts due `pending` rows that fire on resume. `pause` takes an optional `reason` (≤200 chars) and is idempotent (re-pausing keeps the original start and reason); `paused_by` is the UI proxy's `x-caller-email`, else `api`. Behind the shared-secret middleware — not `SCHEDULED_ADMIN_TOKEN`, which the UI cannot send. Any caller may pause; `resume` is principal-only (`is_principal_or_self`, 403 otherwise; open while no principal is rostered; a header-less caller resolves to the principal as in `chat`), and status carries `can_resume` for the viewer so the UI hides Resume from everyone else. |\n| `workspace` | `GET /workspace`, `PUT /workspace` | Solo/team mode, the user's time zone and the principal's role (`memory.workspace_settings`). Both return `{mode, timezone, effective_timezone, role_kind, role_title, reports_to, remit, measured_on, company_domains, company_domains_custom}` — `timezone` is what the user set (null when unset), `effective_timezone` the zone in effect (`timezone`, else `USER_TIMEZONE`, else UTC), and each role field is null until set. `PUT` is a partial update: only the fields sent change; `mode` is `solo` or `team` (not null), `timezone` an IANA zone, or null/blank to clear it; `role_kind` is `owner`, `in_house`, `independent` or `other`, and `role_title` / `reports_to` / `remit` / `measured_on` are free text (trimmed, at most 120 / 120 / 500 / 300 characters), each null or blank to clear it; an unknown zone, a bad mode or role kind, an over-long role field or an unknown field is a 422 and changes nothing. Switching to solo cancels every pending department check-in, switching to team re-schedules them, and a new zone re-times the pending briefs and reflection; a role change has no side effects (the next turn reads it). `company_domains` is the company's own email domains (a teammate matches by local part on them — see Org): `GET` returns the ones in effect (the stored list, or the domain of the principal's primary address, with `company_domains_custom` false) only to the same caller the role is shown to, `[]` for anyone else; `PUT` takes a list (at most 10 plain domain names, never a free-mail provider's — 422 otherwise, the value never quoted) or null / `[]` to go back to deriving them, and a change is audited with the new list. Each change writes a `workspace_settings_changed` audit row (a role change adds `details.role_fields_changed`, the names of the fields that changed — never their text). The role is the principal's: `GET` returns it only to a caller `PUT` would accept and reads it as nulls for anyone else. `PUT` is the principal's alone (`is_principal_or_self`, 403 otherwise; a header-less caller resolves to the principal as in `chat`) and open while no principal is rostered, so first-run setup can pick a mode. Both work before onboarding — unlike `company-profile`, nothing here needs a profile. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). `DELETE /scheduled/{id}` cancels a `pending` row (409 otherwise). Like pause it only stops work, so any signed-in user may — the UI proxy's `x-caller-email` is trusted when the request also carries the `BACKEND_SHARED_SECRET` `x-api-key` — as may a matching `X-Admin-Token` (`SCHEDULED_ADMIN_TOKEN`) or a loopback caller with no token set; otherwise 401 (token set) or 503. Audited as `scheduled_action_cancelled`. |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom`, `GET\\|DELETE /workflows/custom/{name}/targets`, `POST /workflows/runs/{run_id}/decision`, `GET /workflows/tools/search?q=`, `GET /workflows/tools/describe?names=` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. Custom definitions come back with a server-managed `owner_person_id` (the creator — the web caller on `POST`, set on insert only; a client-sent value is ignored), who is asked to approve a workflow's first write to a new target. `GET /workflows/custom/{name}/targets` lists the targets its tool steps may write to without asking and `DELETE …/targets?value=` forgets one. `POST /workflows/{name}/runs` is a 403 (\"Only the principal can run this workflow.\"), audited, before any run row exists, when the workflow is one only the principal may start in the workspace's mode (`weekly_review` always, `morning_brief` in solo) and the caller is not the principal. A request with no `x-caller-email` counts as the principal; with no principal on the roster, no signed-in caller does. This governs starting a run only: `GET /workflows/runs` and `GET /workflows/runs/{run_id}` read stored runs under their existing rules. `POST /workflows/runs/{run_id}/decision` with `{decision: \"approve\"|\"reject\"}` answers a run awaiting a yes/no sign-off from the web app — 403 unless the caller is the person it waits on or the principal, 409 if it isn't awaiting or needs a written reply — through the same `apply_resolution` a chat reply uses. Custom create/update also rejects (422) any action-step tool that does not resolve, and so does `POST /workflows/custom/{name}/activate` when turning a workflow **on** — that click is the approval for a tool workflow chat saved switched off (turning off is never checked). Turning on a workflow with action steps requires the body `{is_active: true, definition}` carrying the definition the user reviewed; if the stored one differs (ignoring `is_active` and timestamps) it returns 409, and the switch itself is a compare-and-set on the validated revision (`dynamic_store.activate_if_unchanged`, keyed on `updated_at`), so a save that lands while the tool check awaits the gateway — even from another process — is a 409 too, so only what was shown gets switched on. `GET /workflows/custom` lists inactive definitions too; `GET /workflows/{name}` 404s for them. The two `tools` endpoints return `{tools: [{name, description, read_only, source}]}` for the advanced editor's tool picker and the review card; `read_only` is true only when the name says it reads (a label, not a control). The run stream adds a `progress` event (`step_id`, `summary`) while an action step uses tools. Each catalog entry (`WorkflowMeta`) carries `is_custom` and `background` (true for the system-run built-ins the UI files under “System”). The run endpoint streams SSE; its `awaiting_human` event carries `delivery` (`self` \\| `sent` \\| `suppressed` \\| `alerted` \\| `failed`) alongside `person_id` / `question` / `awaiting_until`, because the outbound guard or an unreachable approver means the question may never have been asked — a client must not render “waiting on them” for those. A paused run ends the stream with neither `done` nor `error`, so that `awaiting_human` frame carries `terminal: true` to say so explicitly, plus `resumable` — whether the run continues by itself once answered or stops at the gate. `GET /workflows/runs/{run_id}` returns the run row with the resume payload replaced by a small `resume_progress` summary (`gate_step_id`, `completed_step_ids`, or `null`): the payload holds every completed step's full text, and the run-detail page polls this endpoint while a run is unfinished. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. `/search` is the introspection parallel of `retriever.retrieve` and mirrors its filters — including the `general` catch-all on the company collection — so the panel cannot report a specialist seeing nothing that it does retrieve in chat. It accepts `general` in `domain_filter` for the same reason. `/search` applies the same review gate as `retrieve()` — withheld (pending or rejected) built-in, external and failure rows are dropped, so the panel never advertises knowledge the Executive cannot use; it degrades to unfiltered rather than failing if review state is unreadable. `POST /knowledge/builtin` refuses a name already held by shipped content, and `POST|DELETE /knowledge/failures` now register and deregister for review — without that a user-authored failure case study had no review row, so no SME decision could block it. |\n| `skills` | `/skills`, `/skills/search`, `/skills/{name}/restore` | Skill registry (the UI's **Playbooks**) CRUD and search. `PUT` on a built-in saves a company customization that shadows it; `DELETE` returns `{name, outcome}` — `deleted`, `reverted` (customization removed, built-in back) or `hidden` (built-in hidden for this company); `restore` un-hides; `GET /skills?include_hidden=true` lists hidden built-ins. List and detail carry `used_by` — `[{name, title, is_custom}]` of the workflows that follow the playbook (switched-off custom ones included) (`WorkflowMeta.playbooks` is the other direction). |\n| `skill_drafts` | `/skill-drafts`, `/skill-drafts/{name}`, `/skill-drafts/{name}/approve` | Review queue for playbook changes the Executive proposed from chat. `GET` lists drafts (`action` create / update / delete, the proposed fields, an `id` version token, `current` — the playbook in effect now — and `followers`, the workflows that follow the name); `approve` (body `{id}`) applies exactly the reviewed version through the ordinary skills operations — 409 and the draft is kept if it was replaced since, on a conflict, or if its playbook vanished; `DELETE ?id=` discards that version only. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. `POST /evals/runs` is a 403 when a workflow scenario names a workflow that only the principal may start in the mode it runs in (the weekly review; the morning brief in solo) and the caller is not the principal — the Jobs page's rule for starting a run; stored results are read under the existing `/evals/runs` rules. |\n| `memories` | `/memories/{decisions,initiatives,advice}`, `GET /memories/facts`, `POST /memories/facts/{fact_id}/{retire,approve,decline}`, `GET /memories/facts/approval`, `PUT /memories/facts/approval/{person_id}`, `GET /memories/people`, `GET /memories/people/{person_id}/conclusions` | Episodic-memory record management; the standing facts the Pulse Corrections tab reads (`{facts: [...], can_retire, retirable_ids, can_review}`; each fact carries `recorded_by_role` / `recorded_by_name`; `?include_inactive=` default true, honoured for the principal only; anyone else gets the active rows plus their own `proposed` ones, with the provenance (`session_id`, `turn_id`, `recorded_by_person_id`, `retired_reason`, and `source_quote` except on their own facts) blanked, never retired, replaced or declined text; `?limit=` 1–500) and their retire (the principal any fact, a teammate only one they recorded that the principal has not approved — else 403; the audit row names the teammate; 404 for an unknown or `profile` row, 409 when no longer active; writes a private `fact_retired` audit row); approve / decline a teammate's `proposed` fact (principal only, else 403; 409 when it is not proposed; private `fact_reviewed` row); and the per-teammate \"needs my approval\" switch (on by default; `GET` lists `[{person_id, full_name, needs_approval}]` for every active team member but the principal, `true` for anyone not yet set; `PUT` takes `{needs_approval}`, 404 for anyone else; both principal only; private `fact_approval_changed` row); plus the read-only peer-memory overview the Pulse People tab reads (`{status: ok|disabled|error, people: [...], conclusion_total}`; `?recent=` 1–50, default 5) and one person's full conclusion list, paged newest first (`{status, person_id, items, page, size, total, has_more}`; `?page=` ≥1, `?size=` 1–100, default 50; 404 when the person has no peer). The principal's own peer memory — drawn from all their conversations, contacts included — is shown to the principal only: anyone else's overview omits that entry (and its conclusions from `conclusion_total`), and their `/conclusions` request for the principal is a 404. |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). `commit` answers 403 when the draft would make a different person the owner and the caller is not the current owner (setup demotes the old principal, and any signed-in user can open it). It also takes an optional `owner_email` — the principal's sign-in email, which the review screen pre-fills from the signed-in user — checked before anything is written (422 if it is malformed, already another person's, or would replace the principal's existing email — setup only fills in a missing one; 403 if the caller is not the owner and it is not the address they signed in with, since the roster is the sign-in allow-list) and saved on the principal's People row, so the owner's chats resolve to them from the first turn. |\n| `workflow_designer` | `POST /workflows/designer/start`, `POST /workflows/designer/message`, `POST /workflows/designer/draft`, `GET /workflows/designer/{session_id}` | The conversational New workflow wizard. The `workflow_designer` agent asks clarifying questions (`phase: \"question\"`, with `hint` and up to four suggested `options`), then returns `phase: \"draft\"` with `draft.definition` (exactly the body `POST /workflows/custom` takes), `summary`, and `assumptions`; every response carries the `transcript`. **Nothing is persisted here** — sessions are in memory, and the UI saves through `POST /workflows/custom`. Errors are fixed strings (422 over the 8,000-char message cap or the transcript cap, 404 for an expired session, 409 while another turn on the same session is still running, 502/504 for model failure or timeout). Mounted ahead of the `workflows` router. |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. Its final answer saves the profile and adds people with their emails and a principal, so once there is an owner only they can send it (403, and the session rolls back so the owner can still finish it). `/onboard/start` reads the workspace mode once for the session: solo skips the Team Size, Team Members and Fractional Executives steps. Each status response's `current_step` / `total_steps` count only the steps that session asks, and `optional` says whether the current step can be skipped. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `alerts` (private cards) | `POST /alerts/{id}/ack`, `/reopen`, `/alerts/bulk-ack` | An alert tagged `private:principal` (see Today) is a 404 on ack and reopen for anyone but the principal, and their bulk sweep skips it. A roster-request card (source `roster_request`) is a 409 on `ack` even for the principal — it is answered at `/people/requests/{id}`, since acking would leave the sender waiting with nothing to show it — and, as an exempt source, `bulk-ack` and `reopen` skip it. |\n| `auth` | `GET /auth/allowed-emails` | Non-archived **team members** with an email, offered to the UI's sign-in gate — a contact is never on it, so adding a client to reach them by email no longer lets them sign in. The gate takes the **union** of this roster and its own `ALLOWED_EMAILS` env list, so env entries always work (and are checked first, short-circuiting the fetch) and roster entries are additive — a roster change can never revoke a configured operator. With local login (`make dev` with Google sign-in not set up — the UI then listens on 127.0.0.1 only) the UI signs in without an email, sends no `x-caller-email`, and the backend resolves the caller to the principal, as it does for the CLI. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |",
+ "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). With local login (`OE_LOCAL_LOGIN=1`, which only `make dev` sets, and only while Google sign-in is not set up) a second middleware answers 403 to any request whose raw `Host` is not `localhost`, `127.0.0.1` or `[::1]` (except a webhook that verifies its caller: Google Chat always, Telegram only with a `TELEGRAM_WEBHOOK_SECRET` Telegram can send), and to any write whose `Sec-Fetch-Site` is present and not `same-origin`/`none`. The UI signs that owner in with no password and this API usually has no secret, so without it a web page in the owner's browser could drive the API as the principal — by DNS-rebinding its own hostname to 127.0.0.1, or by posting a plain form from another site or localhost port. CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat`, `POST /chat/stop` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. Each round of tool calls also emits an `activity` event (`{type, label, tool, iteration}`) naming what is running — progress only, forwarded verbatim and never persisted with the message, unlike an `action_taken` chip. A `session_id` in the body must be a chat the caller may use (the same ownership rule as `sessions`). If it isn't, the turn runs in a fresh chat instead, so nothing is written into someone else's session and the reply looks the same as for an unknown id. An unknown namespaced id (`slack:…`, `telegram:…` and so on) is ignored and a fresh chat is started, because those ids belong to the channel adapters and claiming one first would make the caller its owner. The client mints a `client_turn_id` and sends it with the turn; `POST /chat/stop` takes that id and halts the turn mid-flight, so the button is live from the moment Send is pressed rather than only once the first SSE byte arrives. A stopped turn emits a `stopped` event and then the usual `done` over the same still-open stream — never an `error` — and whatever streamed so far is persisted and flagged. The endpoint returns 404 both for an unknown id and for another caller's turn, so it cannot be used to probe which turns are live. An optional `memory_text` (1–2000 chars) is what peer memory records as the caller's words instead of `message` — the briefing handoffs send it because their seed quotes the Executive's own card; `POST /chat/upload` derives it from the typed text and filenames. Since it never reaches the transcript, the `chat_turn` audit row keeps it beside `message`. After the reply — a stopped or timed-out one too, before the `stopped` / `error` / `done` frames — a turn that looked at anything sends one `sources` event, `{type, session_id, sources: [{kind, title, url}], unavailable: [area]}`: `kind` is `company`, `knowledge`, `notion`, `research`, `document` or `web`, `url` is only ever an http(s) link or, for an earlier document, `/artifacts/<id>`, at most 12 sources (6 from the web, pages the reply cites first), and `unavailable` names parts of the analysis (\"finance\") whose specialist failed or said nothing every time it was asked. It is persisted with the reply as `chat_messages.sources`. A request that carries `x-caller-email` marks its turn signed in (`Session.web_caller_signed_in`), which Act as me needs on a deployment without local login. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}`, `GET /sessions/{id}/messages`, `DELETE /sessions/{id}`, `POST /sessions/{id}/messages/{message_id}/feedback`, `GET /sessions/{id}/followup` | List, read and delete saved chat sessions (assistant messages carry their row `id` and any `feedback`). The list is scoped to the caller. Every per-session route checks ownership, because session ids are guessable (`slack:dm:<user id>`, `telegram:<chat id>`): only the session's owner or the principal gets through, and a legacy row with no owner is the principal's alone. Anyone else gets the same 404 as for an unknown id, so the routes can't be used to find out which chats exist. The one other way in is having started the chat in this process (matched by Person id or verified email, so it survives the caller being added to the roster), which is how a caller the roster can't resolve keeps using their own chat. That record is in memory, so after a restart such an ownerless chat is refused for reads. The principal can continue someone else's ownerless chat without becoming its owner. Deleting a session also drops its in-memory copy, so a later turn naming that id starts fresh. The feedback route records 👍/👎 (`{\"feedback\": \"up\"|\"down\"|null}`) on one assistant reply; only the session's own caller or the principal may rate it. The rater is stored (`feedback_by_person_id`), and a 👎 on a reply to the rater's own message triggers a working-style pass for them (paced; see attunement). The chat stream's `done` event carries `message_id` for the persisted reply. The followup route returns `{\"suggestion\": string|null}` — one suggested next user message, written by the utility-fast model from the last few turns, that the chat composer shows as its greyed placeholder (Tab / → or the inline chip fills it in without sending). It is null unless the session ends on a persisted assistant reply, and null (uncached) when the model fails. Same ownership check as feedback; successful suggestions are cached in-process per (session, reply id). Messages from `GET /sessions/{id}/messages` carry each assistant reply's saved `sources` (the same shape as the chat stream's `sources` event, without `type`), so a reloaded chat shows them again. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily`, `GET /today/brief-delivery`, `GET /today/top-three`, `GET /today/weekly-review` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). `GET /today` carries the viewer's cached \"What's going on\" `narrative` with `narrative_generated_at` (when it was written) and `narrative_stale` (a fresher one is being written — the page re-polls; see Today). A proposal backed by a roster request carries `roster_request` (the new sender's server-derived details and held-message previews; the principal's only) and is answered through the `people` routes below. `brief-delivery` returns the latest morning brief or end-of-day digest that didn't reach the owner, as `{brief, at, problem, fix, readable}` in plain language (`readable` is false when it couldn't be written, so there is nothing to read), or null — null while briefs go out, once the cause is fixed, while the scheduler is off, and for anyone but the owner (`chat._caller_is_principal_or_unclaimed`); it carries no address or channel id. `top-three` and `weekly-review` feed the solo Briefing's own cards and answer only in solo mode and only to the principal (`workflows._caller_is_the_principal`: a principal match or no caller header, never an unclaimed roster); anyone else, and team mode, get null. `top-three` returns `{items: [{key, kind, text, why, slot}]}` — the morning brief's top three from the same code (`build_top_three(principal_due_soon())`), `slot` a free block like `10:00–11:00`, `\"\"` when none is left, null when no calendar was read — and is kept off `GET /today` because its calendar read may take up to 4 s. `weekly-review` returns the latest completed `weekly_review` run as `{run_id, completed_at, period, top_three, excerpt}` (next week's top three as plain text; `excerpt` when that list is empty), or null when none has completed. |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive`, `GET /people/requests`, `GET /people/requests/{id}`, `POST /people/requests/{id}/approve`, `POST /people/requests/{id}/decline`, `GET\\|POST /people/{id}/open-loops`, `POST /open-loops/{loop_id}/close`, `GET /people/{id}/outreach`, `GET\\|PUT\\|DELETE /people/{id}/attunement` | Roster CRUD and scope lookups. Every `Person` carries `kind` (`team` / `contact`). `GET /people` lists team members only unless `?include_contacts=true` (the People page asks for both; the department-head and workflow pickers keep the default); `POST` / `PATCH` accept `kind`, and a principal contact is a 422 either way. They also take `email_aliases` (other addresses the person writes from, at most 10; on `PATCH` the full list replaces the current one, omitted leaves it): an alias matches their mail and may be emailed but never signs in; a malformed one is a 422, and an alias — or a new primary `email` — that is already someone else's address or alias is a 409. Every `POST` / `PATCH` then closes any pending roster request whose sender now matches someone and replays its held messages. Adding, editing and archiving (`POST`, `PATCH`, `/archive`) are the principal's only, or anyone's while no one is principal yet so a first setup can add its owner (`chat._caller_is_principal_or_unclaimed`, the check behind `PUT /workspace`; a request with no `x-caller-email`, such as the CLI or local login, counts as the principal). Anyone else, a person editing their own row included, gets 403 before the person lookup, so it can't probe which ids exist. Contacts are private to the principal (`caller_is_principal`: the signed-in email is the principal's, or no `x-caller-email`; stricter than the owner rule above, so while no one is principal nobody is): for anyone else `include_contacts` is ignored, a contact's id is a 404 on `GET /people/{id}` and open-loops (exactly as for a missing id; `PATCH` and archive are already a 403 for them), and creating a contact or turning someone into one is a 403, even on a first setup with no principal yet. `GET /people/me` returns `{person_id, is_principal}` so the UI offers contacts to the principal only. `GET /people/by-scope/{token}` never returns a contact. Archiving a person closes their open loops. The open-loop routes list what a person owes (soonest due first) and close one (`reason`: done / not_needed / cancelled) — both the principal's or the owner's only (403 otherwise, via `people.store.is_principal_or_self`). `POST /people/{id}/open-loops` `{task, due_date?}` assigns that person a task (201 with the loop; `due_date` is a local date, due 17:00 in the user's timezone, clamped to 60 days, default 2 days): any active team member may assign anyone on the team, 403 for anyone else; 409 for an archived person, a contact (as seen by the principal), a person at the open-loop cap, a duplicate or open loops turned off; 422 for an empty task. Nobody is messaged at assignment — the owner is chased once it is due. `/outreach` returns, per kind of proactive outreach over 30 days, `sent` / `replied` / `acted` / `ignored` / `pending` (voided DMs are excluded) — same access rule, checked before the person lookup so it can't probe which ids exist. `/attunement` reads, replaces (`rules`: up to 4 strings, or omitted to only set `locked`) or resets the person's working-style rules — same access rule, 404 for an archived person; `PUT` rejects a rule that is not purely about style with 422. Archiving a person also drops their working style and frees their aliases. The **roster-request** routes (declared before `/people/{person_id}`) are the principal's alone (`caller_is_principal`; anyone else gets 404, as for a missing id): `GET /people/requests?status=pending|approved|linked|declined|expired|superseded|all` lists up to 100 (`id`, `channel`, `channel_ref`, sanitised `display_name`, `profile_email`, `on_company_domain`, `suggested_kind`, `suggested_person_id` / `_name`, `status`, `resolved_person_id` / `_kind`, `message_count`, timestamps, `ack_sent`, and `previews` of the held messages while pending — shown to the principal, never to a model); `approve` takes either `link_person_id` (+ `replace_channel_id`) or `full_name` + `kind` (no default: 422 without both) + optional `role`; `decline` takes no body. An answered request is a 409, a chat id or address already on someone else is a 409; the held messages are replayed (or dropped) in the background. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. A `cadences` spec that does not parse is rejected with a 422 (empty means no cadence). A new `head_person_id` must be a team member: an unknown id and one of the principal's contacts get the same name-free 422 (`person_id N is not on the team.`), so the route — open to any signed-in user — never reveals that a contact exists; an unchanged head is not re-checked. `POST .../goals` requires only `key_result`: a missing or blank `period_value` is filled with the current period for `period_type` in the user's zone (the same label `create_goal` uses), and `target` defaults to empty. `PATCH .../goals/{id}` rejects a blank `key_result` or `period_value` with a 422; `target` may be cleared. |\n| `agents` | `GET /agents`, `GET /agents/models`, `GET /agents/models/options`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. `/agents/models` is the flat model allowlist the PATCH validator uses; `/agents/models/options` returns the same ids in the same order, each tagged with `provider`, `provider_label`, `route` (`direct` / `openrouter` / `local`) and a display `label`, for the Council's Provider → Model picker. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `GET /artifacts/{id}`, `GET /artifacts/{id}/download?as=`, `POST /artifacts/{id}/archive`, `POST /artifacts/{id}/restore`, `DELETE /artifacts/{id}` | Browsable deliverables in any format — Markdown, HTML, Word, Excel, or a link into a connected app — with `format`, `downloads`, `external_url` and `supersedes_id` on every summary. `download` renders the file (Word/Excel built at request time from the stored text; any Markdown artifact, workflow output included, can export `?as=docx`) and is always an attachment with `nosniff` and a sandbox CSP. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET`/`PUT /decisions/classes/meeting_scheduling`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. An approval whose caller resolves to the principal runs the booking inside `grant_contact_egress()`, so a meeting the principal proposed with a contact can be created. Such a booking's payload is marked `private`: it is proposed to the principal, left out of anyone else's `GET /decisions`, and a 404 for them on `GET /decisions/{id}` and every action route. Reviewed in the briefing — there is no separate proposals page. The class routes read and set how meetings are handled: both return `{decision_class: \"meeting_scheduling\", mode: \"propose\" \\| \"auto_execute\"}` (default `propose`); the `PUT` body is `{mode}`, principal-only (403 otherwise, open before a principal exists — but then only `propose` can be set: `auto_execute` is a 409 until a non-archived principal is on the roster), 422 on any other mode, and a change writes a `decision_class_mode_changed` audit row. In solo mode the class mode decides a booking, and `auto_execute` applies only to a turn the principal started on a verified surface — any other turn gets a proposal. |\n| `delegation` | `GET`/`PUT /delegation`, `GET`/`PUT`/`DELETE /delegation/voice`, `POST /delegation/voice/learn`, `POST /delegation/voice/signature` | Act as me — the **caller's own** delegation only; nobody sets it for anyone else. `GET /delegation` returns `{enabled, gmail: {status, message, email, connect_command}}`, where `status` is `connected`, `not_configured`, `needs_reconnect`, `mismatch`, `no_email`, `shared_mailbox` or `error`, checked live with Google on each call. `PUT` takes `{enabled}` (any other field is a 422); turning it on needs the caller's own Gmail connected, otherwise a 409 whose code says why (`gmail_not_connected`, `gmail_needs_reconnect`, `gmail_mismatch`, `no_email`, `shared_mailbox`, `gmail_error`). The voice routes show, learn (from the caller's sent mail, one pass at a time — a 409 `in_progress`, `locked`, `too_soon`, `not_enough_mail`, `no_profile` or `changed` when it was locked or edited while learning, or a Gmail code), edit and lock, and reset \"How I write\": a typed field that fails validation is a 422 `invalid_voice` listing each `rejected` field, and `clear_exemplars` / `clear_signature` drop those. `POST /delegation/voice/signature` reads the signature from the caller's Gmail settings again and changes nothing else (a locked profile stays locked), with the same Gmail codes as learning: a 409 when their Gmail isn't connected, Google refuses it or the check itself fails (`gmail_error`), and a 502 `gmail_error` when reading the signature fails. A caller `can_delegate` refuses — anyone but the principal, for now — gets 403 `not_available_yet`, which hides the Settings card. A request with no `x-caller-email` is a 403 `sign_in_required` unless the API runs under local login — a header-less call is not a sign-in (the header itself is trusted from whoever holds the shared secret, the UI proxy, as on every principal-only route). Every change writes a private audit row. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts). Rows private to the principal (`private_to_principal`: a turn about their private mail, or a row naming one of their contacts on their own turn) are theirs alone: for any other caller, resolved as for `/alerts`, the list, its `total` and the usage totals leave them out, a private row's id is a 404, and a session shows only its other rows. |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `setup_status` | `GET /setup/status` | Settings → Setup status: one light per part of the install — AI model, company setup, owner, the Executive's address, API protection, Gmail, your own Gmail (Act as me), Slack, Discord, Telegram, Google Chat, the scheduler, the daily brief (when and where it goes) and Honcho — as `{checked_at, checks: [{id, label, state, summary, fix, link, last_activity}]}`, where `state` is `ok`, `warn`, `error` or `off` (optional and not set up), `fix` says what to do in plain language, `link` is an in-app page that helps (`/people`, `/onboard`) and `last_activity` is the channel's latest `integration_inbound` audit time. It tests live, with at most one free read-only call per service, each bounded to 5 s: Anthropic `models.list` (so an organisation key missing `ANTHROPIC_WORKSPACE_ID` shows up), Slack `auth.test`, Telegram `getMe` and `getWebhookInfo`, Discord `users/@me` only while the bot is still connecting, and — once the owner's own Gmail credential exists — Google's token refresh and Gmail `users/me/profile`. It also reads the listeners the lifespan leaves on `app.state` (Slack's socket, the Discord bot and its task, the MCP gateway), the scheduler heartbeat and the pause switch. When `google_workspace` is configured, the lifespan also starts `MCPGateway.prime_pinned_tools()` in the background (held on `app.state.mcp_prime_task`, cancelled at shutdown), so the pinned Google tools named in the prompt are callable without a search. With `DRIVE_SYNC_ENABLED` the lifespan also bootstraps the `drive_sync_scan` heartbeat beside Notion's (see Scheduler); the Drive folder sync has no HTTP route, only the `openexecutive sync-drive` / `purge-drive` CLI. Sample values copied from `.env.example` are named as such without being sent anywhere. No token reaches a response or a log line: probes report a status code, a service's short error code or an exception's class name. Requests within 5 s of a run get that run's answer and concurrent requests share one run (kept per app on `app.state`), so the button can't become a stream of calls to those services. Gated like every other route; the UI adds a sign-in light of its own, from its own settings. |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}`, `GET /documents/sources`, `POST /documents/sources/{drive\\|notion}/sync`, `GET /documents/{drive\\|notion}`, `GET /documents/{drive\\|notion}/{id}` | Upload, list, view extracted text, and delete indexed company docs. `GET /documents` rows carry `source: \"upload\"` and the `domain` the upload was indexed under. The connected-source routes back the knowledge page's single Company documents list: `/documents/sources` gives each source's `{id, label, enabled, syncing, last_run, last_error, interval_minutes, file_count}`; `/documents/drive` and `/documents/notion` list synced files from the sync state (`{enabled, last_run, last_error, files: [{id, name, url, modified_at, synced_at, indexed}]}`); `/documents/{drive\\|notion}/{id}` returns the stored text for an id on record (the path comes from the state, never the caller). They are read-only — a synced file is removed where it lives. `POST …/sync` starts one tick of the same sync the scheduler runs as a background task (202); 409 when the source is not connected or a tick is already running (both syncs hold a per-process run lock, so a manual run never overlaps the heartbeat), 429 with `Retry-After` within 60 s of the last successful run or of the end of the last tick in this process, failed ones included, so a failing or slow source can't be re-run back-to-back. The page's text view never loads images from synced content (a remote image would be a read beacon for whoever edits the shared folder). Upload is keyed on the filename, so re-uploading a document replaces its chunks rather than duplicating them, and `DELETE` removes the rows as well as the file. `domain` must be one of the nine specialist domains (including `sales`) or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. A scanned PDF is converted (`knowledge.pdf_reader`) before it is indexed and in the text view, as are scanned PDFs in `POST /chat/upload` and the client / onboarding intake uploads. |\n| `executive` | `GET /executive/status`, `POST /executive/pause`, `POST /executive/resume` | Operator pause switch for all autonomous work (scheduler, Gmail poller, workflow resumer); inbound chat and DMs stay live. Status returns `{paused, paused_at, paused_by, reason, held_actions, can_resume}` — `held_actions` counts due `pending` rows that fire on resume. `pause` takes an optional `reason` (≤200 chars) and is idempotent (re-pausing keeps the original start and reason); `paused_by` is the UI proxy's `x-caller-email`, else `api`. Behind the shared-secret middleware — not `SCHEDULED_ADMIN_TOKEN`, which the UI cannot send. Any caller may pause; `resume` is principal-only (`is_principal_or_self`, 403 otherwise; open while no principal is rostered; a header-less caller resolves to the principal as in `chat`), and status carries `can_resume` for the viewer so the UI hides Resume from everyone else. |\n| `workspace` | `GET /workspace`, `PUT /workspace` | Solo/team mode, the user's time zone and the principal's role (`memory.workspace_settings`). Both return `{mode, timezone, effective_timezone, role_kind, role_title, reports_to, remit, measured_on, company_domains, company_domains_custom}` — `timezone` is what the user set (null when unset), `effective_timezone` the zone in effect (`timezone`, else `USER_TIMEZONE`, else UTC), and each role field is null until set. `PUT` is a partial update: only the fields sent change; `mode` is `solo` or `team` (not null), `timezone` an IANA zone, or null/blank to clear it; `role_kind` is `owner`, `in_house`, `independent` or `other`, and `role_title` / `reports_to` / `remit` / `measured_on` are free text (trimmed, at most 120 / 120 / 500 / 300 characters), each null or blank to clear it; an unknown zone, a bad mode or role kind, an over-long role field or an unknown field is a 422 and changes nothing. Switching to solo cancels every pending department check-in, switching to team re-schedules them, and a new zone re-times the pending briefs and reflection; a role change has no side effects (the next turn reads it). `company_domains` is the company's own email domains (a teammate matches by local part on them — see Org): `GET` returns the ones in effect (the stored list, or the domain of the principal's primary address, with `company_domains_custom` false) only to the same caller the role is shown to, `[]` for anyone else; `PUT` takes a list (at most 10 plain domain names, never a free-mail provider's — 422 otherwise, the value never quoted) or null / `[]` to go back to deriving them, and a change is audited with the new list. Each change writes a `workspace_settings_changed` audit row (a role change adds `details.role_fields_changed`, the names of the fields that changed — never their text). The role is the principal's: `GET` returns it only to a caller `PUT` would accept and reads it as nulls for anyone else. `PUT` is the principal's alone (`is_principal_or_self`, 403 otherwise; a header-less caller resolves to the principal as in `chat`) and open while no principal is rostered, so first-run setup can pick a mode. Both work before onboarding — unlike `company-profile`, nothing here needs a profile. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). `DELETE /scheduled/{id}` cancels a `pending` row (409 otherwise). Like pause it only stops work, so any signed-in user may — the UI proxy's `x-caller-email` is trusted when the request also carries the `BACKEND_SHARED_SECRET` `x-api-key` — as may a matching `X-Admin-Token` (`SCHEDULED_ADMIN_TOKEN`) or a loopback caller with no token set; otherwise 401 (token set) or 503. Audited as `scheduled_action_cancelled`. |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom`, `GET\\|DELETE /workflows/custom/{name}/targets`, `POST /workflows/runs/{run_id}/decision`, `GET /workflows/tools/search?q=`, `GET /workflows/tools/describe?names=` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. Custom definitions come back with a server-managed `owner_person_id` (the creator — the web caller on `POST`, set on insert only; a client-sent value is ignored), who is asked to approve a workflow's first write to a new target. `GET /workflows/custom/{name}/targets` lists the targets its tool steps may write to without asking and `DELETE …/targets?value=` forgets one. `POST /workflows/{name}/runs` is a 403 (\"Only the principal can run this workflow.\"), audited, before any run row exists, when the workflow is one only the principal may start in the workspace's mode (`weekly_review` always, `morning_brief` in solo) and the caller is not the principal. A request with no `x-caller-email` counts as the principal; with no principal on the roster, no signed-in caller does. This governs starting a run only: `GET /workflows/runs` and `GET /workflows/runs/{run_id}` read stored runs under their existing rules. `POST /workflows/runs/{run_id}/decision` with `{decision: \"approve\"|\"reject\"}` answers a run awaiting a yes/no sign-off from the web app — 403 unless the caller is the person it waits on or the principal, 409 if it isn't awaiting or needs a written reply — through the same `apply_resolution` a chat reply uses. Custom create/update also rejects (422) any action-step tool that does not resolve, and so does `POST /workflows/custom/{name}/activate` when turning a workflow **on** — that click is the approval for a tool workflow chat saved switched off (turning off is never checked). Turning on a workflow with action steps requires the body `{is_active: true, definition}` carrying the definition the user reviewed; if the stored one differs (ignoring `is_active` and timestamps) it returns 409, and the switch itself is a compare-and-set on the validated revision (`dynamic_store.activate_if_unchanged`, keyed on `updated_at`), so a save that lands while the tool check awaits the gateway — even from another process — is a 409 too, so only what was shown gets switched on. `GET /workflows/custom` lists inactive definitions too; `GET /workflows/{name}` 404s for them. The two `tools` endpoints return `{tools: [{name, description, read_only, source}]}` for the advanced editor's tool picker and the review card; `read_only` is true only when the name says it reads (a label, not a control). The run stream adds a `progress` event (`step_id`, `summary`) while an action step uses tools. Each catalog entry (`WorkflowMeta`) carries `is_custom` and `background` (true for the system-run built-ins the UI files under “System”). The run endpoint streams SSE; its `awaiting_human` event carries `delivery` (`self` \\| `sent` \\| `suppressed` \\| `alerted` \\| `failed`) alongside `person_id` / `question` / `awaiting_until`, because the outbound guard or an unreachable approver means the question may never have been asked — a client must not render “waiting on them” for those. A paused run ends the stream with neither `done` nor `error`, so that `awaiting_human` frame carries `terminal: true` to say so explicitly, plus `resumable` — whether the run continues by itself once answered or stops at the gate. `GET /workflows/runs/{run_id}` returns the run row with the resume payload replaced by a small `resume_progress` summary (`gate_step_id`, `completed_step_ids`, or `null`): the payload holds every completed step's full text, and the run-detail page polls this endpoint while a run is unfinished. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. `/search` is the introspection parallel of `retriever.retrieve` and mirrors its filters — including the `general` catch-all on the company collection — so the panel cannot report a specialist seeing nothing that it does retrieve in chat. It accepts `general` in `domain_filter` for the same reason. `/search` applies the same review gate as `retrieve()` — withheld (pending or rejected) built-in, external and failure rows are dropped, so the panel never advertises knowledge the Executive cannot use; it degrades to unfiltered rather than failing if review state is unreadable. `POST /knowledge/builtin` refuses a name already held by shipped content, and `POST|DELETE /knowledge/failures` now register and deregister for review — without that a user-authored failure case study had no review row, so no SME decision could block it. |\n| `skills` | `/skills`, `/skills/search`, `/skills/{name}/restore` | Skill registry (the UI's **Playbooks**) CRUD and search. `PUT` on a built-in saves a company customization that shadows it; `DELETE` returns `{name, outcome}` — `deleted`, `reverted` (customization removed, built-in back) or `hidden` (built-in hidden for this company); `restore` un-hides; `GET /skills?include_hidden=true` lists hidden built-ins. List and detail carry `used_by` — `[{name, title, is_custom}]` of the workflows that follow the playbook (switched-off custom ones included) (`WorkflowMeta.playbooks` is the other direction). |\n| `skill_drafts` | `/skill-drafts`, `/skill-drafts/{name}`, `/skill-drafts/{name}/approve` | Review queue for playbook changes the Executive proposed from chat. `GET` lists drafts (`action` create / update / delete, the proposed fields, an `id` version token, `current` — the playbook in effect now — and `followers`, the workflows that follow the name); `approve` (body `{id}`) applies exactly the reviewed version through the ordinary skills operations — 409 and the draft is kept if it was replaced since, on a conflict, or if its playbook vanished; `DELETE ?id=` discards that version only. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. `POST /evals/runs` is a 403 when a workflow scenario names a workflow that only the principal may start in the mode it runs in (the weekly review; the morning brief in solo) and the caller is not the principal — the Jobs page's rule for starting a run; stored results are read under the existing `/evals/runs` rules. |\n| `memories` | `/memories/{decisions,initiatives,advice}`, `GET /memories/facts`, `POST /memories/facts/{fact_id}/{retire,approve,decline}`, `GET /memories/facts/approval`, `PUT /memories/facts/approval/{person_id}`, `GET /memories/people`, `GET /memories/people/{person_id}/conclusions` | Episodic-memory record management; the standing facts the Pulse Corrections tab reads (`{facts: [...], can_retire, retirable_ids, can_review}`; each fact carries `recorded_by_role` / `recorded_by_name`; `?include_inactive=` default true, honoured for the principal only; anyone else gets the active rows plus their own `proposed` ones, with the provenance (`session_id`, `turn_id`, `recorded_by_person_id`, `retired_reason`, and `source_quote` except on their own facts) blanked, never retired, replaced or declined text; `?limit=` 1–500) and their retire (the principal any fact, a teammate only one they recorded that the principal has not approved — else 403; the audit row names the teammate; 404 for an unknown or `profile` row, 409 when no longer active; writes a private `fact_retired` audit row); approve / decline a teammate's `proposed` fact (principal only, else 403; 409 when it is not proposed; private `fact_reviewed` row); and the per-teammate \"needs my approval\" switch (on by default; `GET` lists `[{person_id, full_name, needs_approval}]` for every active team member but the principal, `true` for anyone not yet set; `PUT` takes `{needs_approval}`, 404 for anyone else; both principal only; private `fact_approval_changed` row); plus the read-only peer-memory overview the Pulse People tab reads (`{status: ok|disabled|error, people: [...], conclusion_total}`; `?recent=` 1–50, default 5) and one person's full conclusion list, paged newest first (`{status, person_id, items, page, size, total, has_more}`; `?page=` ≥1, `?size=` 1–100, default 50; 404 when the person has no peer). The principal's own peer memory — drawn from all their conversations, contacts included — is shown to the principal only: anyone else's overview omits that entry (and its conclusions from `conclusion_total`), and their `/conclusions` request for the principal is a 404. |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). `commit` answers 403 when the draft would make a different person the owner and the caller is not the current owner (setup demotes the old principal, and any signed-in user can open it). It also takes an optional `owner_email` — the principal's sign-in email, which the review screen pre-fills from the signed-in user — checked before anything is written (422 if it is malformed, already another person's, or would replace the principal's existing email — setup only fills in a missing one; 403 if the caller is not the owner and it is not the address they signed in with, since the roster is the sign-in allow-list) and saved on the principal's People row, so the owner's chats resolve to them from the first turn. |\n| `workflow_designer` | `POST /workflows/designer/start`, `POST /workflows/designer/message`, `POST /workflows/designer/draft`, `GET /workflows/designer/{session_id}` | The conversational New workflow wizard. The `workflow_designer` agent asks clarifying questions (`phase: \"question\"`, with `hint` and up to four suggested `options`), then returns `phase: \"draft\"` with `draft.definition` (exactly the body `POST /workflows/custom` takes), `summary`, and `assumptions`; every response carries the `transcript`. **Nothing is persisted here** — sessions are in memory, and the UI saves through `POST /workflows/custom`. Errors are fixed strings (422 over the 8,000-char message cap or the transcript cap, 404 for an expired session, 409 while another turn on the same session is still running, 502/504 for model failure or timeout). Mounted ahead of the `workflows` router. |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. Its final answer saves the profile and adds people with their emails and a principal, so once there is an owner only they can send it (403, and the session rolls back so the owner can still finish it). `/onboard/start` reads the workspace mode once for the session: solo skips the Team Size, Team Members and Fractional Executives steps. Each status response's `current_step` / `total_steps` count only the steps that session asks, and `optional` says whether the current step can be skipped. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `alerts` (private cards) | `POST /alerts/{id}/ack`, `/reopen`, `/alerts/bulk-ack` | An alert tagged `private:principal` (see Today) is a 404 on ack and reopen for anyone but the principal, and their bulk sweep skips it. A roster-request card (source `roster_request`) is a 409 on `ack` even for the principal — it is answered at `/people/requests/{id}`, since acking would leave the sender waiting with nothing to show it — and, as an exempt source, `bulk-ack` and `reopen` skip it. |\n| `auth` | `GET /auth/allowed-emails` | Non-archived **team members** with an email, offered to the UI's sign-in gate — a contact is never on it, so adding a client to reach them by email no longer lets them sign in. The gate takes the **union** of this roster and its own `ALLOWED_EMAILS` env list, so env entries always work (and are checked first, short-circuiting the fetch) and roster entries are additive — a roster change can never revoke a configured operator. With local login (`make dev` with Google sign-in not set up — the UI then listens on 127.0.0.1 only) the UI signs in without an email, sends no `x-caller-email`, and the backend resolves the caller to the principal, as it does for the CLI. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |",
"mermaid": null,
- "generated_at": "2026-09-30T01:51:39.035367+00:00"
+ "generated_at": "2026-10-01T14:23:59+00:00"
}
diff --git a/packages/core/openexecutive/architecture/prebuilt/integrations.json b/packages/core/openexecutive/architecture/prebuilt/integrations.json
index d82358e1..5cc69574 100644
--- a/packages/core/openexecutive/architecture/prebuilt/integrations.json
+++ b/packages/core/openexecutive/architecture/prebuilt/integrations.json
@@ -1,7 +1,7 @@
{
"section_id": "integrations",
"title": "Integrations",
- "markdown": "External channels connect callers to the Executive. Each inbound adapter resolves the sender to a Person — the chat adapters via `find_person_by_{slack,discord,telegram}_id`, the email poller via `people.identity.resolve_email_sender` (a primary address or an alias, then the company-domain rule; see Org) — and threads `person_id` into `Executive.chat()`. A sender who resolves to nobody is no longer simply dropped: see **New senders (roster requests)** below.\n\n### Inbound channels\n\n- **Slack** (`integrations.slack_bot`) — async Bolt socket-mode (`AsyncApp` + `AsyncSocketModeHandler`) embedded in the lifespan; responds to `@mention`s, DMs, and thread continuations, with per-conversation session memory (see **Conversation state** below). Text only: there is no interactivity endpoint and no Block Kit, so nothing Slack sends carries a button.\n- **Discord** (`integrations.discord_bot`) — discord.py gateway embedded in the lifespan; per-thread auto-titling, session-scoped memory, author attribution, configurable `@mention` thread promotion.\n- **Telegram** — webhook gating + per-chat history.\n- **Google Chat** — webhook + service-account auth. It resolves no approval gates and has no roster gate (the webhook authenticates Google, not the sender), and it never populates the session's trusted alert ids, so `ack_alert`'s trust check — which now runs on every session rather than only those declaring an `origin_channel` — refuses there by default, and its `<channel>` block says plainly that a sign-off cannot be answered from it.\n- **Email** (`integrations.email_poller`) — Gmail poll loop over the Google Workspace MCP (it starts only once the MCP gateway is up); strips Reply-To, filters auto-replies. Its sessions carry `origin_channel=\"email\"`: the untrusted-content policy (`orchestrator.content_trust`) reads that tag to tell mail from the principal's own surfaces — left empty, as it once was, every stranger's body reached the decision extractor as the principal's words. The mail goes into the turn inside an `<untrusted_content source=\"email\" author=\"<sender>\" author_verified=\"no\">` block that says it carries none of the principal's authority, with the framing line and any `[POLICY]` notice outside it; mail from the principal's primary address that Gmail authenticated (`dmarc=pass`) is their own words — but only their new text goes in unwrapped: when the mail quotes or forwards another message (`_new_text_lines` cut something), the message as received follows in an `<untrusted_content source=\"email_quoted\">` block, since a stranger's text they replied to or passed on is not theirs. While the Executive is paused (`scheduler.pause`) it skips each poll and leaves the inbox unread, so held mail is processed on the first poll after resume; the chat adapters above are not paused. The Executive sees the whole message; peer memory records only `_email_memory_text` — the subject, the sender's new text (cut at the first quoted or forwarded message) and the attachment filenames — parsed without backtracking-prone regexes, since the text is sender-controlled, and only for a rostered sender, the only kind with a peer to record into. The poller's `integration_inbound` row keeps the mail's text for the audit log, the way the reply's `chat_turn` row keeps the Executive's answer: `full.message` is the sender's new text (what web chat keeps for a turn), `full.attachments` the attachment filenames, and `details.preview` the first 120 characters of the new text, so /audit shows what was asked next to what was answered (the summary still reads `Inbound email from <sender>: <subject>`). The whole body with its quoted chain (`full.body`) is kept only on a row private to the principal: the chain is other people's mail — a contact's, on the principal's reply to one — and every signed-in user reads a public row. Each field is cut by its escaped JSON length (20,000 characters of text, 8,000 of attachment names), the measure the logger's 64 KB cap uses, so a long mail in a non-Latin script loses its tail rather than the row's structure. Outbound, the principal briefs and the client-rotation digest are emailed through the same gateway (`google_workspace__send_gmail_message`, from the Executive's own mailbox to the principal's address, subject `<brief title> — <date>`, the date in the user's zone) as formatted HTML — rendered from the brief's Markdown with raw HTML and images off, so text quoted from outside shows as text and opening the email loads nothing remote. Email is first when the principal prefers it, and otherwise the backup after every chat channel, tried only when Slack, Discord and Telegram are missing or fail; an in-band error from the tool counts as a failed send and the next channel is tried. An emailed brief is not a DM, so the per-Person outbound guard below does not apply — the gateway's roster egress gate does.\n\n Two senders get their own framing. Mail from one of the principal's **contacts** (a `kind=\"contact\"` People row — see Org) replaces the non-roster `[POLICY]` notice with a contact one: it names them (name and role/company), says not to reply unless the principal asks and not to tell anyone else, and asks for a summary for the principal instead. Both this turn and the forwarded-by-principal turn below are marked `Session.private_to_principal`: they can email, DM or invite only the principal, an alert they raise is private to the principal, and they are not offered the tools that reach anyone else or start work outside the turn (`schedule_tools.PRIVATE_TURN_WITHHELD_TOOLS`: broadcasts, meeting bookings, workflows, follow-ups, watches, artifacts, goal updates, skill drafts, connecting a new MCP server), and of the MCP tools only Google Workspace reads and the gated Gmail send (see MCP below). Every audit row about such mail is private to the principal (see Audit Log), the poller's two `integration_inbound` rows included (`_private_to_principal_mail`), so the audit log's other readers see none of it. The poller holds `audit.private_rows` for the whole handling of such a mail, because some rows are written before the turn binds its private session: the knowledge retrieval quotes the mail's From line, subject and opening. The rows themselves read exactly like an outside sender's: the `integration_inbound` row is the non-roster one (`accepted_non_roster`), and the notice opens with the non-roster notice's exact sentence. The poller handles each message with no session bound, so one message's private turn never marks the next message's rows. The turn stays unattributed (`person_id` None — no peer memory, no co-presence), and the gateway refuses mail to a contact on a poller turn anyway. Mail **forwarded by the principal** — the sender resolves to the principal and `_new_text_lines` reports a forwarded message — is wrapped in a `<forwarded_by_principal>` block: summarise it, draft a reply the principal could send (as text in the reply, never sent or saved as a Gmail draft), note any commitment or date, and offer to add the original sender as a contact (confirmed from the web app or the principal's Slack / Discord, since an ordinary email turn cannot change the People list — the one email that can is the principal's tokened reply to a roster-request email, which is parsed before any model turn; see below). The reply still goes to the principal only. The From header is unauthenticated, so this framing grants nothing: a spoofed \"forward\" just gets the real principal a summary.\n\nSlack, Discord, and Telegram are roster-gated on inbound: an unrostered sender's message never reaches the Executive (`details.outcome=\"rejected_unknown_sender\"`). The gates look up **team members only** — a contact's Slack, Discord or Telegram id is treated as unknown, so a contact can never talk to the bot (nor count as a co-present peer). What happens next is the roster request below — except for a contact, a thread continuation, a Telegram group or an unverified Telegram webhook, which stay silent. Email is not inbound-gated — non-roster mail flows through with a `[POLICY]` notice so triage can classify it. Slack/Discord thread continuations pass the shared `integrations.response_gate` (utility-fast model, biased toward replying).\n\n### New senders (roster requests)\n\nSomeone who writes in and is not on the People list — and is not one of the principal's contacts — is **held, acknowledged and asked about** instead of dropped (`integrations.roster_intake.intake` over the `people.roster_requests` ledger; lifecycle in Org). Each adapter calls it after its gate:\n\n- **Slack** — a DM or an `@mention` (not a thread continuation: the bot was not addressed there). The name and profile email come from `users_info` (5 s timeout). The acknowledgement goes in the DM, or as an **ephemeral** message for a mention, so nobody else in the channel learns who is and is not on the roster. The held event keeps only a fixed set of keys (text, user, channel, ts, thread, files).\n- **Discord** — a DM or a mention (not a thread the bot merely follows). The acknowledgement goes in the DM, or by DM for a channel mention; `/ask` answers the interaction with an ephemeral acknowledgement first (Discord allows 3 s), then holds the prompt. Its old \"ask the admin to add you\" reply is gone.\n- **Telegram** — only a **private** chat, and only when `TELEGRAM_WEBHOOK_SECRET` is set and valid: Telegram identifies the chat rather than the sender, and without the secret anyone could forge an update. A group, or an unverified webhook, stays silent as before. Attachment file ids are held and downloaded only on replay.\n- **Email** — non-roster mail that is not private to the principal (so never a contact's) and does not look machine-sent (`looks_automated`: a no-reply / notifications / billing-style local part, a `List-Id` / `List-Unsubscribe` / `Auto-Submitted` / bulk `Precedence` header, or a DMARC failure). The mail is **still triaged** by the Executive on this pass; its `[POLICY]` notice now says the sender was already told their message is waiting and the principal was asked who they are, so the model raises no second alert just to add them, and that the email will come back once they are added.\n\nEvery path skips a contact first (`find_person_by_*_id(..., include_contacts=True)`, or the email poller's private-mail rule): a contact has no chat access and gets no request and no acknowledgement, and the team-visible `rejected_unknown_sender` / `accepted_non_roster` rows read the same for a contact as for a stranger.\n\n**The acknowledgement** is one fixed text (`roster_intake.ACK_TEXT` — \"your message arrived … waiting for confirmation\"), never the model and never an echo of what they wrote, so a forged sender gains nothing by triggering it. It is sent at most once per sender per `ROSTER_ACK_WINDOW_DAYS` (7) and at most `ROSTER_ACK_DAILY_CAP` (20) a day across all senders (`claim_ack`, one transaction; a failed send releases its claim). An email acknowledgement is the one send the MCP gateway lets reach an address off the roster: `send_email_ack` sets `mcp_gateway.roster_ack_grant`, a one-shot ContextVar grant that admits a single `send_gmail_message` with exactly the granted recipient (a plain string, no list), subject and body and no other key, then is spent (audited `integration_outbound`, `kind: roster_ack`, private). An email sender is acknowledged only when Gmail authenticated them: once `claim_ack` succeeds, the poller's `send_ack` re-reads the mail as raw MIME and needs Gmail's own topmost `Authentication-Results` reporting `dmarc=pass` for the From domain (`fact_confirmation.sender_authenticated`, fail-closed). The printed headers the poller reads never carry that header, so without the second read a forged From would draw the acknowledgement to whoever it names — backscatter from the Executive's mailbox. An unauthenticated sender makes `send_ack` raise `roster_intake.AckWithheld`: the claim is released, and they are held silently. `authenticated_by_gmail` strips quoted strings and comments before reading the verdict — Gmail copies the envelope sender and DKIM tags into its own stamp, and a quoted local part could otherwise carry a fake `dmarc=pass` — and needs exactly one `dmarc=` verdict reading exactly `dmarc=pass header.from=<domain>` (Gmail may follow it with its own `dara=` resinfo, so its position is not checked). Residual: when Gmail writes no verdict at all (a From domain without DMARC) and echoes an unsanitised `;dmarc=pass header.from=…` elsewhere in its stamp, that echo would read as the verdict; bounded by the acknowledgement caps. A withheld acknowledgement is audited `roster_ack_withheld`. `intake` acknowledges before surfacing the card and telling the principal, and both follow the request's `ack_sent_at`: a withheld, failed or capped acknowledgement reads \"haven't been told anything yet\" on the Today card, in the principal's prompt and in the email `[POLICY]` notice.\n\n**Telling the principal.** A new request puts a private card on the principal's `/today` (see Today) and pushes a prompt on their delivery plan — preferred chat DM, then the others, then email — for a chat sender or an email sender on the company's own domain; an outside email sender waits on the card, as does everything past `ROSTER_REQUEST_DAILY_CAP` (30) pushes a day (the same cap bounds how many requests open a day; a declined sender is not raised again for 30 days). A chat prompt can be answered in place (\"that's Annamarie, add her to the team\"). An email prompt carries a one-time token (`RR-` + 20 base32 characters, stored hashed); the poller checks every inbound mail for one **before** triage (`try_email_roster_answer`): the reply must come from the principal's primary address exactly (not an alias, not the company-domain rule), carry the token of a pending request, not be an automatic reply, and not fail DMARC where the header is visible; and is parsed by `parse_decision`'s `roster_identity` shape — anything else falls through to the ordinary path. The token is hidden (`RR-[hidden]`) in every other Google Workspace result the gateway returns — the confirmation sits in the Executive's Sent folder, and any turn could otherwise read it — except the poller's own fetch of an inbound message (`mcp_gateway.reveal_roster_tokens`); a token-bearing mail that is not an answer is scrubbed before triage.\n\n**Replay.** Once the principal answers (web card, chat tool, email reply) — or a People-page / `upsert_person` write makes the sender match someone (`after_roster_write`) — the held messages are replayed through the adapter that received them (`register_replayer`: Slack re-runs the held event, Discord and Telegram their held text, email re-fetches the message from Gmail and handles it as mail from a known sender), oldest first, now attributed to the new Person. A teammate gets every held message; a new contact only held email (it takes the private contact path; held chat is dropped); a decline drops everything. Replays run in a **fresh `contextvars.Context`**: the answer may have come from the principal's own verified turn, and a stranger's message must never be read with the principal's session — and their contacts — still bound.\n\n### Standing facts by email (confirm by reply)\n\nThe principal can ask for a standing fact, a retirement or a company-profile edit by email, and the fact tools check it exactly as in chat (the own-words gates run on `_email_memory_text`, the sender's new text, not the quoted chain or attachments). An email's From line proves nothing, though, and a standing fact is read by every later prompt as the principal's own account. So an emailed change is **held, never applied**, until the principal's own mailbox confirms it (`integrations.fact_confirmation`, `memory.facts.fact_confirmations`):\n\n- **Who may ask.** The poller stamps every email turn with `Session.email_from` (the bare lowercased From address) and `email_authenticated`. The text the poller reads never carries `Authentication-Results` (workspace-mcp prints a fixed set of headers), so for mail claiming the principal's primary address it reads the message again as raw MIME (`fact_confirmation.sender_authenticated`) and requires Gmail's own stamp: the **topmost** `Authentication-Results` header (Gmail adds it on receipt, above anything the sender wrote), authserv-id `mx.google.com`, reporting `dmarc=pass` for the From address's domain, with the raw From matching (`authenticated_by_gmail`). It fails closed: no header, `dmarc=none`, a temporary error or a failed read all leave the turn unauthenticated. Mail from anyone else costs no second read and is never authenticated. `fact_tools._gate` admits an email turn only from the principal's **primary** address, exactly (no alias, no company-domain rule), authenticated, and not private to the principal (mail they forwarded stays refused, as do contacts, teammates and unknown senders).\n- **The hold.** The tool returns `awaiting_confirmation` (no action chip, and the model is told to say nothing has changed). `request_confirmation` stores the change with the SHA-256 of a fresh one-time token (`FC-` + 20 base32 characters, 100 bits; 7-day expiry; at most 10 waiting at once) and emails the token to the principal's roster address, outside any turn's outbound context. A profile edit is dry-run first, so one that cannot apply is reported in the turn, before any email goes out. If the email fails, nothing is held.\n- **Keeping the token from any model.** The tool result never carries it, and `mcp_gateway.hide_roster_tokens` now scrubs `FC-` tokens as well as `RR-` ones (`FC-[hidden]`) from every Google Workspace result except the poller's own fetch of an inbound message. Act as me's reads of the principal's own Gmail, where the confirmation email lands, hide them too (`delegation.gmail.parse_message` and the thread search), so the drafting model never sees a live token either.\n- **The reply.** `_handle_one_email` hands every message to `try_email_fact_confirmation` right after the roster-answer check, before any model turn. It acts only on a reply from the principal's primary address carrying the token of a **pending** confirmation. A made-up, spent, cancelled or expired reference matches nothing and falls through to the ordinary path with the token hidden, so no old or forged token can make the Executive email the principal. A reply with a live token is read again as raw MIME (`read_raw`) and must pass the same Gmail DMARC check as the request; one that doesn't (or whose raw read fails) is refused, the change keeps waiting, and the principal is told. Then an **automatic reply** is consumed quietly — no answer, no model turn, the change keeps waiting: the printed headers catch a Gmail vacation reply (`Precedence: bulk`), and the raw headers catch what they don't show (`automatic_reply`: `Auto-Submitted` other than `no`, `X-Auto-Response-Suppress` and similar, `Precedence: auto_reply`, an out-of-office subject), since an Exchange out-of-office echoes the token from the principal's own address and may well say \"I'll confirm on my return\". The raw message starts at the tool's exact separator line (`\\n\\n--- RAW MIME ---\\n`), so a sender-written Subject imitating it cannot supply the headers. CONFIRM (or yes / approve) applies the change through `fact_tools.apply_confirmed`, the same apply step chat uses. CANCEL (or no) drops it, and an unclear reply leaves it waiting. The principal gets a one-line result either way. A compare-and-set on the row means two replies can apply it only once.\n- **Audit.** Private `fact_confirmation` rows record held / applied / cancelled / refused. The applied change also writes the fact tools' usual private rows, with `source_channel=\"email\"` as its provenance.\n\n### Checking a channel is set up\n\nSettings → Setup status (`GET /setup/status`, `api/setup_checks.py`) gives each channel a light and a plain-language fix. It tests the credentials with one free read-only call — Slack `auth.test`; Telegram `getMe`, then `getWebhookInfo` (is a webhook registered, is it this app's `/webhook/telegram`, did a delivery fail in the past day); Discord `users/@me`, only while the bot is still connecting — and reads what the lifespan left on `app.state`: the Slack socket's `is_connected()`, the Discord bot's `is_ready()` together with its gateway socket being open (discord.py stays ready while it reconnects after a drop), or the exception its task stopped with (`LoginFailure`, `PrivilegedIntentsRequired`), and the MCP gateway. Because inbound is roster-gated, a connected Slack, Discord or Telegram is amber while nobody on the roster has its id (`slack_user_id`, `discord_user_id`, `telegram_chat_id`), or when its latest `integration_inbound` row is a `Rejected: …` from the past day whose sender still isn't on the roster — the page shows the sender's id, never message text. Local login with no `TELEGRAM_WEBHOOK_SECRET` is red for Telegram, since the local-login gate turns its webhook away. Google Chat and Gmail are checked from configuration: a numeric project number and a readable service-account key; the OAuth client (or service-account key) the workspace-mcp child signs in with.\n\nA channel setting written `KEY= # note` in a `.env` file arrives as the note's text, because python-dotenv strips only a comment that follows a value. `Settings` reads such a value as unset for the Slack, Telegram, Discord and Google Chat credentials, so the line no longer switches a channel on with its own comment as the token. `TELEGRAM_WEBHOOK_SECRET` is the exception, because read as unset a junk secret would turn the webhook's check off. It is kept instead, and since Telegram can only ever send 1–256 of `A-Z a-z 0-9 _ -` (what `setWebhook` accepts), a secret outside that set — a leftover comment, a pasted `<value from Step 2>` — could only be matched by someone who guessed it: while it is set the webhook refuses every update, neither the local-login gate nor the roster tools count it as proof (`Settings.telegram_webhook_secret_valid`), and Setup status shows it red (`.env.example` shipped four such lines; the notes now sit on their own lines).\n\n### Conversation state\n\nEvery adapter keys a deterministic `session_id` off the conversation surface and replays that session's stored turns into `Session.conversation_history`, so a follow-up (\"yes, go ahead\") lands with the question still in context. Slack's ids are `slack:dm:{user}`, `slack:thread:{channel}:{thread_ts}`, and `slack:channel:{channel}:{user}` for a mention that starts a thread; because the bot's reply roots a Slack thread at that message's `ts`, the turn is double-written to that thread's session too, so the first continuation inside it is not cold. A reply inside a thread THAT PERSON ROOTED also offers the parent `slack:channel:{channel}:{user}` id when matching an approval gate, since a gate raised on the mention recorded that session while the answer arrives under the thread's. The root-author check is load-bearing: widening on \"threaded and not a DM\" alone offered one person's channel session inside any thread in that channel, so a remark they made to a colleague could resolve their open gate and post the run's title into that colleague's thread. Discord has the same shape — its auto-thread router promotes a mention reply into a bot-owned thread — and the same alias. An @-mention inside a DM is handled once, by the DM path: Slack fires both events, and taking both forked the conversation across two session ids. The same id is the audit grouping key and the scope passed to `format_for_prompt`. A per-session `asyncio.Lock` serializes turns within one conversation — the inflight semaphore caps fan-out across the workspace, which does nothing to stop two messages in the same thread from both reading history before either writes it. Persistence happens after the reply is sent and its failure is logged, never surfaced: the user already has their answer.\n\nThis was absent on Slack until #136. Every message built a fresh `Session` and minted a per-*message* id (`thread_ts` falls back to the message's own `ts`, so a DM never repeated one), which meant a multi-turn confirmation could not work: the Executive asked whether to send a briefing to Slack, the user said yes, and the next turn had no record of the question.\n\n### What the model is told about the channel\n\nChat adapters pass a `<channel>` block (`integrations.channel_context`) in the **user turn** — never a cached system block. It names the surface, states that the person cannot see the app's cards or buttons, and draws the line the assistant kept crossing: briefing proposals and alerts are actioned on the briefing page; a proposal that books something can only be approved there; a workflow sign-off the Executive is explicitly waiting on *can* be answered in the conversation. The principal's DMs on Slack, Discord and Telegram also receive the open-alert digest (`briefing.context.format_open_alerts_for_prompt`) as the `<briefing>` block, gated to DMs because the board is company-wide and a shared channel must not pull it in. That digest is the ONLY trusted source of an `alert_id` for `ack_alert`. The briefing page's `[Discuss mode — alert_id=N]` primer is a pointer to which item is under discussion, not authority on its own: the server accepts that id only if it is also on the live board it derived itself. An id appearing anywhere else, including inside an alert's own body, is not trusted: alerts are minted from inbound email and chat, so their bodies are attacker-controlled. Two mechanisms enforce that rather than one prompt rule. Every field the digest interpolates is collapsed to a single line, because a newline in an attacker-written headline, suggested action, tag or review note would otherwise forge a whole extra `[N]` line — a fabricated instruction to clear somebody else's alert. And the live board the server derived is recorded on the session, so `ack_alert` refuses any id outside it — on EVERY session, web included; the web previously had no check at all. The recorded set is the whole live board (the cap `/today` renders as cards), not just the rows the digest printed, so a card past the digest's 30-row render cap is still ackable rather than sending the principal back to the page. Be precise about what this buys: it stops an id that is invented, closed, snoozed or expired, including one quoted out of an attacker-written alert body. It does NOT stop the model being argued into acking the wrong LIVE card — one alert's body can still make a case about another id that is genuinely open. Scoping trust to the single item under discussion would need the primer id carried server-side, which it is not.\n\n### Handler failures\n\nAn adapter's catch-all replies \"I encountered an error processing your request.\" On Slack that used to be the whole story — one uncorrelated log line, no audit row, and an unguarded error-send that could itself escape into Bolt. It now logs with the session, sender, channel, thread and mode, and writes an `integration_inbound` row with `details.outcome=\"handler_error\"`, joining the inbound row under the same `session_id`. Upstream, a single crashing tool handler no longer takes the turn down at all: the orchestrator's tool gathers use `return_exceptions=True`, hand the model an error `tool_result`, and audit it with `ok=false` (cancellation is re-raised, not swallowed).\n\n### Attachments\n\n`integrations.attachments` handles web chat, Discord, Telegram, Slack and Google Chat. Images become Anthropic vision blocks; documents (PDF/DOCX/TXT/MD/CSV) are inlined into the turn that carried them — inside an `<untrusted_content source=\"attachment\" author=\"<name>\">` block (`content_trust.wrap_untrusted`, whose closing tag the text cannot forge), under an `[Attached: <name>]` label, which the open-loop pass reads as \"not the speaker's words\" and the decision extractor strips before it reads the turn — and indexed into the ChromaDB `inbound_attachments` collection. 20 MB/file cap; web chat uses `POST /chat/upload`.\n\n**Scanned PDFs** are read, not reported empty. A PDF with no text layer goes through `knowledge.pdf_reader`: with `PDF_PROVIDER_READING=true` (opt-in, off by default) the deployment's own model reads it through its provider's PDF support (Anthropic natively, OpenRouter's `file-parser`, a local server only with `LOCAL_PDF_INPUT`); otherwise, and as the fallback, local OCR (pypdfium2 + RapidOCR, offline, no key) — so every deployment converts them. The label then reads `(converted from scanned pages)`, and an unreadable one says why. The index takes the text already extracted for the turn, so a scan is converted once. A file a channel delivered (everything here except `POST /chat/upload`, where the signed-in user sends it) converts at most `PDF_INBOUND_MAX_PAGES` (30) pages and draws on a rolling `PDF_INBOUND_PAGES_PER_HOUR` (300) budget shared by all senders, so sending scans cannot run up unbounded model spend or CPU.\n\nPer channel:\n- **Slack** — a `file_share` message (previously dropped outright for its `subtype`) is handled like any message; files download only after the roster gate and the response gate, with the bot token sent only to `https://files.slack.com/` (needs the `files:read` scope). History and peer memory record the words plus `(Attached files: …)`, never a document's text.\n- **Google Chat** — uploaded attachments download through `media.download` with the reply credentials (`chat.bot`), checked against the 20 MB cap per chunk, 5 per message; an attachment-only message is no longer dropped. The webhook authenticates Google, not the sender, so files are read only when the event's `user.email` is on the People roster (a team member); anyone else's files are named to the Executive, never downloaded. A Drive file shared into a message is left to the Drive tools, with its id.\n- **Email** — the poller (`integrations.email_attachments`) downloads up to 5 readable attachments of the message itself via `get_gmail_attachment_content` — workspace-mcp in stdio mode saves the file and answers `Saved to: <path>`, which must start its line, be the last such line and end in the answer's `Saved filename:` (the answer echoes the sender-chosen attachment name first, and a name carrying `Saved to: /…` must not redirect the read), then resolve inside the tool download folders — and appends their text to the turn (15k chars each). Only for a sender the principal knows (team, contact, principal); a stranger's files stay a list. It runs outside the model loop, so it works on private turns without adding the attachment tool to `PRIVATE_TURN_MCP_TOOLS`.\n- Anything else (a Drive PDF, a skipped attachment) — the Executive's `read_document` tool.\n\nIndexed chunks are keyed on `attachment:<bare filename>` and tagged `type=attachment`. An attachment's name is chosen by whoever sent the message and the name is the chunk-id namespace, so without the prefix an inbound `strategy-2026.md` would upsert over the curated company document of that name. The prefix separates inbound content from curated uploads and keeps provenance visible; it does not separate senders from one another.\n\nIsolation is the **collection**: `retriever.retrieve` never queries `inbound_attachments` at all, so an attachment cannot resurface as company knowledge in a later, unrelated turn. Attachment processing is roster-gated on Discord too — it previously ran before the gate, so an unrostered sender's file was downloaded and indexed before their message was dropped. These rows still have no operator surface: they are never written to `company/docs/`, so `GET /documents` does not list them.\n\nThis replaced a domain-based scheme that did not work. The chunks lived in `company_docs` under a domain outside the specialist set, on the premise that an unrecognised domain matched no filter. It matched every one — `ChromaDBStore.query` attaches a `where` clause only when a domain filter is present, and an Executive-level retrieval passes none — so attachments came back under “From your company documents”, top-ranked and indistinguishable from a curated upload. Legacy rows are migrated across on boot.\n\n### MCP gateway & outbound\n\nMCP runs in **both directions**. As a *client*, `orchestrator.mcp_gateway.MCPGateway` proxies MCP servers (Gmail, Calendar, Drive — whatever `mcp_servers.json` configures) as Executive tools, with egress gating on Gmail recipients, Calendar attendees, and Drive share grantees against the roster (and a refusal of public / whole-domain Drive sharing). The Gmail gate also accepts only a fixed set of argument keys, so workspace-mcp's `reply_all` (recipients taken from the thread, never checked) and `forward_message_id` / `include_forwarded_attachments` (forwarding any inbox message) are refused; a reply is `thread_id` plus an explicit, roster-checked `to`. Three more refusals close paths around those gates: every Apps Script tool (code running as the Executive's account, outside the gates, and since workspace-mcp 1.29.0 schedulable to keep running); any argument that makes the server fetch a URL (`fileUrl` / `file_url` on the Drive and import tools, a Gmail attachment given as a `url`), since the fetch can carry data out in its query string before any recipient gate matters; and text Google would mail to someone the roster never checked (`rsvp_comment` to an event's organizer, an out-of-office `decline_message` to whoever invites the Executive). Every gate reads its arguments by normalized spelling: workspace-mcp 1.29.0 renames a camelCase key such as `Attendees`, `userGoogleEmail` or `rsvpComment` to the real parameter, so a gate matching the exact key would never see it. Arguments that are not a JSON object are refused for the same reason. Google-side fetches are refused too: any key ending in `url` / `uri` at any depth whose value has a URL scheme (a Slides image or page background, a Docs or Forms image; a document hyperlink and a meeting link are stored, not fetched, and pass, as does a Drive file id), (a value is a URL after the characters a URL parser strips are removed, and `//host` counts), and on every tool that can write cells — the Sheets tools and the Drive create / update / import tools, which turn CSV into a Sheet — any string anywhere holding a formula call that fetches (`IMPORTDATA`, `IMPORTXML`, `IMPORTHTML`, `IMPORTFEED`, `IMAGE`), JSON-encoded or mid-CSV included: a string argument that encodes JSON is read as the server decodes it (one too large to read is refused), text is also scanned with character references decoded and comments / CDATA removed, and an upload that would become a native Sheet may only be text `content` — a `base64_content` or server-side `file_path` upload there is refused, since an XLSX hides its formulas behind zip members and XML encodings; a PNG to Drive or a DOCX to Docs is untouched. Not covered, unverified: whether Drive's HTML / Markdown import fetches an `<img src>` when it converts `content` into a Doc. A `manage_event` call that names no attendees is sent with `send_updates=\"none\"`, so the event's existing guests are not emailed text the gate never checked. The allow-list (`_egress_sets`, built by `_roster_allow_set` as a `people.identity.RosterAllow`) is every team member's email and email aliases plus the Executive's own address, always, and — for a teammate — any address on one of the company's own domains whose local part (`+tag` dropped) matches theirs, the same rule inbound mail is matched by; a **contact's** email joins it only when `people_tools.contacts_reachable_now()` is true — a turn the principal started on a verified surface (web chat, their own Slack or Discord, a verified private Telegram chat), or inside `grant_contact_egress()` (the decisions approve route, when the approver is the principal). On any other turn — an inbound email, a teammate, the scheduler, a workflow, the alert review — a contact's address is refused exactly like a stranger's, so the refusal cannot reveal that it belongs to a contact (contacts are private to the principal). The single exception to the roster rule is the fixed roster-request acknowledgement above, under its one-shot `roster_ack_grant`. A turn about the principal's private mail (`Session.private_to_principal`) narrows the list to the principal's own address and the Executive's. Such a turn may call only the MCP tools in `schedule_tools.PRIVATE_TURN_MCP_TOOLS`: Google Workspace reads (`search_gmail_messages`, `get_gmail_message_content`, `get_events`, `list_calendars`, `query_freebusy`, `search_drive_files`) and the two Gmail tools this gate narrows to the principal (`send_gmail_message`, `draft_gmail_message`). It is an exact allow-list, not a server: workspace-mcp runs at the `complete` tier, where a Google Chat message to a space, a Docs, Sheets or Drive write into a file already shared with others, `manage_event` on a shared calendar (its gate checks attendees and pins notifications, nothing else) reaches people with no recipient check; and every other server has none at all (a Slack or Notion server, the default `fetch` server, whose URL can carry the turn's content, a server loaded at runtime). Its `search_tools` results show only the allowed tools (`workflows.tool_catalog.filter_search_results`; output it cannot parse reads as no match), and a `call_tool` naming anything else is refused with an error tool_result and an audit row private to the principal (`schedule_tools.private_turn_withholds`), a missing name included. `search_tools` and `call_tool` stay offered, so the tool list and its cached prefix do not change. The typed calendar tool (`_resolve_attendees`) and the chat DM tools (`message_person`, `send_telegram_message`, `send_discord_dm` and their person-id recovery) apply the same rule — a contact's id reads as an unknown one off the principal's turn — and a private turn may DM or invite only the principal (`PRIVATE_TURN_REFUSAL` otherwise); `message_person` never falls back to a \"Needs you\" alert for a contact, who cannot sign in to see it. The Google Workspace server (`workspace-mcp`) behind those Gmail/Calendar/Drive tools runs **co-located inside the API** as a stdio child of the gateway — fitting the single-tenant model (one install = one company = one exec Google account), so there's no separate service to operate. It's baked into the API image and launched by `docker/workspace-mcp-launch.sh`, which selects single-user OAuth (token persisted at `/data/google_credentials`) or service-account domain-wide delegation from `GWORKSPACE_AUTH_MODE`. The optional `WORKSPACE_MCP_TOOLS` (comma-separated service names, default `all`) limits which Google services it loads. The gateway forwards the Google secrets to the child via `_FORWARDED_ENV_VARS`. Every `google_workspace__*` call acts as the Executive's own account. workspace-mcp takes the acting account per call (`user_google_email`) and nothing used to check it, so under domain-wide delegation a model-chosen address could open anyone's mailbox in the domain; `mcp_gateway._check_acting_account` now refuses a value naming any other address — before every other gate, with an `integration_outbound_blocked` audit row. An absent value stays allowed (the server's own account). As a *server*, `openexecutive.mcp_server` exposes OE's own company context and specialist council to external MCP clients at `/mcp` — the inverse direction; see the dedicated **MCP Server** section. The gateway launches extensible-mcp as a `uvx` subprocess whose fastembed tool-search index uses an embedding model baked into the API image and loaded offline, so it no longer re-downloads that model from the Hugging Face Hub on every cold start. extensible-mcp is pinned twice over: to a commit, which fixes its own code, and with `--exclude-newer`, which fixes the resolution of its dependencies — without the cutoff uvx re-resolves them against PyPI on every networked start, so a new release of any of them would reach running deployments on restart. Both live in `_EXTENSIBLE_MCP_LAUNCH_ARGS` in `orchestrator/mcp_gateway.py`, the Dockerfile's pre-warm uses the same arguments (a unit test enforces the match), so an image whose pre-warm succeeded starts the gateway with no network. The pre-warm is best-effort (`|| true`): an image built while GitHub was unreachable fetches the pinned commit on its first start instead. Updating the gateway is a deliberate bump of the commit and cutoff; `uv` itself is not pinned. Because the MCP stdio client does not inherit the parent environment, `MCPGateway.start()` explicitly forwards the embedding-cache/offline env vars (`FASTEMBED_CACHE_PATH`, `HF_HUB_OFFLINE`, …) into the child.\n\n**What the model is told is connected.** `MCPGateway.start()` records the configured server names (`server_names`), and the Executive renders them with the channel settings into block 0's *Connected Systems* section (`prompts.connected_systems`; see the caching section). While Google is connected that section pins the Google tool names the Executive uses constantly (`GOOGLE_TOOL_MANIFEST`) and tells it to call them with `call_tool` directly, with no `search_tools` round trip. extensible-mcp only runs a tool one of the session's searches has returned, and remembers it for the session's life, so the gateway does that discovery itself: the lifespan starts `MCPGateway.prime_pinned_tools()` in the background once the gateway is up with `google_workspace` configured (an exact-name search per pinned tool, the way `workflows.tool_catalog.resolve` does it; a name the search no longer finds is logged as workspace-mcp drift). A pinned call that still comes back with extensible-mcp's \"has not been discovered via search_tools\" refusal, for example before priming finished, is discovered and retried once. That happens after every gate has passed the same arguments, and only for pinned names: any other tool still needs the model's own search, and nothing here widens what a call may do, including the private-turn allow-list.\n\n**Emailing an artifact.** A Gmail send or draft may carry `attachments=[{\"artifact_id\": \"alert:12\", \"as\"?: \"docx\"}]`. `call_tool` runs the recipient gate first; only if it passes does `_expand_artifact_attachments` replace each such entry with the rendered file (`content` base64 + `filename` + `mime_type`, workspace-mcp's own attachment shape), produced by `artifact_records.render_artifact_file` — the same renderer as `/artifacts/{id}/download`. Only artifact rows resolve (never an arbitrary alert), links have no file, and an entry mixing `artifact_id` with other keys is refused. A stringified or single-object `attachments` is normalised first, so an artifact entry can never reach workspace-mcp unexpanded (it would silently drop it). At most 5 distinct artifacts per email (repeats are dropped) and 15 MB rendered in total; rendering runs off the event loop via `asyncio.to_thread`. A refusal writes `artifact_attachment_refused`; a successful send writes `artifact_attached` — both carry the recipients. Other attachment entries pass through unchanged.\n\n**Enablement, and why it degrades instead of dying.** `MCP_ENABLED` left unset is inferred from the presence of `mcp_servers_config_path` — dropping an `mcp_servers.json` next to `profile.yaml` turns MCP on with no further configuration. An **explicit** setting always wins in both directions: `MCP_ENABLED=false` keeps MCP off with the file still in place. It did not: `_resolve_mcp` tested `not self.mcp_enabled`, which cannot tell \"never set\" from \"set to false\", so the file's presence silently overrode the operator. The file is probed through `config.mcp_config_file_present`, never `Path.exists` directly — that re-raises an EACCES on a parent directory, and from inside a validator that comes out of `Settings()` itself, which `api/main.py` calls at module level. The check now reads `model_fields_set` (the fields the env actually supplied) and stores that on a private attr behind the read-only `mcp_auto_enabled` property, because the validator's own assignment joins that set and would otherwise make every auto-enable look explicit downstream.\n\nStartup is **best-effort**, in `main._start_mcp_gateway`. Two checks come before the subprocess: MCP off is a no-op, and a config defining no servers under `mcpServers` is logged and skipped — extensible-mcp's own loader raises on that and exits, and because the child is already gone the only thing that surfaces is anyio's \"Attempted to exit cancel scope in a different task\" from `stdio_client` unwinding, a traceback naming nothing about configuration. The start is also bounded (120s, generous because that child may still clone extensible-mcp on a cold start if the image's pre-warm failed): `ClientSession` carries no `read_timeout_seconds`, so `initialize()` waits forever on a child that is *alive but silent*, and an unbounded wait is a lifespan that never yields — the same healthcheck-never-passes symptom, which no `except` can see. A gateway that fails anyway is logged at ERROR with the config path, the servers it named, and whether the config file or an explicit `MCP_ENABLED` turned MCP on, then torn down under its own timeout; the API boots **without MCP tools and without the email poller** rather than refusing to boot. The guard catches `BaseException`, not `Exception`, re-raising a bare `CancelledError` first: the original failure came from anyio, which wraps a task group's failures in `BaseExceptionGroup` as soon as one is a `BaseException` — and that group is not an `Exception`, so `except Exception` would miss the very shape this contains. The teardown is contained too, since it runs from inside that `except` and would otherwise replace the actionable log with the crash it prevents. `configured_server_names` never raises either, and deliberately catches broadly: it reads an operator-owned path during startup, where an exception is the crash loop rather than a bug report — `Path.is_file` re-raises an EACCES on a parent directory, and `json.loads` answers deeply-nested input with `RecursionError`, which is not a `ValueError`. It tests `is_file()` so a directory or a symlink to a FIFO is never opened, and caps the read at 1 MiB. That exception used to propagate out of the lifespan and kill the container — under `restart: unless-stopped`, a crash loop whose only outward symptom was a healthcheck that never passed. Outbound tools: per-Person DMs (`send_slack_dm`, `send_discord_dm`, `send_telegram_message`) plus room-targeted `send_department_message` and `send_company_broadcast`. The per-Person DMs are additionally rate-limited and de-duplicated by the outbound anti-spam guard (below).\n\n### Outbound anti-spam guard\n\nEvery per-Person DM passes a deterministic guard (`orchestrator.outbound_guard.check_outbound_allowed`) after the roster gate and recipient-id recovery but before the network send — the single chokepoint **all** proactive DM paths reach (ad-hoc chat sends, the scheduler's followup/nudge dispatch, principal-brief delivery, the reflection turn, and research-finding routing). On a violation it returns a human-readable reason and the handler **suppresses** the send (`{\"status\":\"suppressed\",\"reason\":…}`), writes a `tool_invocation` audit row with `suppressed=true`, and writes **no** `done` activity row — so a blocked attempt never counts toward its own rate cap, and the Executive can read the reason and hold or `schedule_followup` for the recipient's next window. Three controls: **content dedup** (a near-identical message — whitespace/case-normalized, first 160 chars — already sent to the same recipient within `OUTBOUND_DEDUP_WINDOW_MINUTES`, default 360); a **per-recipient rate cap** (`OUTBOUND_MAX_PER_RECIPIENT_PER_WINDOW`, default 5, over `OUTBOUND_RATE_WINDOW_MINUTES`, default 60); and **quiet hours / availability** (`OUTBOUND_RESPECT_QUIET_HOURS`, default on — refuse while the recipient is on leave or outside their `people.channel` availability windows, surfacing the next open window). Delivery history is read from the existing `status='done'` `scheduled_actions` rows (`episodic.recent_sends_for_channel_ref`), so there is no new table. The guard is **fail-open**: any internal lookup error returns \"allow\", so it can never turn a working send into a crash or a silently-dropped message. Principal briefs and the internal heartbeat kinds use the `__internal__` channel and never reach these handlers, so they are unaffected.\n\n### Calendar & Google Meet\n\nThe Executive books meetings through two typed tools over the Calendar MCP. `create_calendar_event` schedules a **future** meeting (propose→approve by default, or auto-execute once that decision class is promoted) and may be used proactively when a stalled goal warrants a sync. `create_instant_meeting` spins up an **impromptu call starting now**, auto-executing without the approval step and skipping the business-hours/horizon caps, so the Executive can hand back a join link immediately. Both attach a **Google Meet** link by default (`add_google_meet`; opt out for in-person), parsed from the created event's `conferenceData` and surfaced to the caller plus persisted on the decision ledger. Either way the caps that matter still hold — roster membership, principal-protection, max attendees, and a daily booking ceiling.\n\n**Around-the-meeting participation.** The Executive doesn't join the call as a live voice; instead, on every successful booking it schedules a best-effort post-meeting follow-up (~5 min after the end) that DMs a human attendee asking for a quick recap — key decisions and action items. The reply flows back through the same cross-session DM context linkage described below, so the Executive can act on it (summarize, follow up) in a later turn. No meeting-transcript or Drive integration is required.\n\n### Cross-session DM context\n\nWhen the principal says \"DM Alex about X\" in one session, OE sends the DM and — if a live conversation is active and the recipient is not one of the principal's contacts (a contact cannot DM the bot, and quoting the principal's conversation into their email reply's unattended turn would put it in the audit log) — records an `outbound_context` linkage row (recipient, full outbound text, originating session id). Email is covered too but recorded one layer deeper — there is no `send_email` tool, so the linkage is written in `orchestrator.mcp_gateway` after a successful `google_workspace__send_gmail_message`, one row per `to`/`cc` recipient keyed by the bare lowercased address (OE's own address skipped). When Alex later replies on the 1:1 DM path — or by email — the shared helper `integrations.inbound_hydration.hydrate_user_message` (called by the Discord, Telegram, and Slack handlers, and by the email poller keyed on the sender address) looks up the most-recent `open` linkage for that sender within 72h and prepends an `<outbound_reply_context>` block — the outbound text plus a backstory excerpt from the originating session — to the message handed to `Executive.chat()`. So OE knows what the reply is about instead of starting from an empty per-person session. The block is context for the LLM turn only: peer memory strips it before recording what the person said (`strip_outbound_reply_context`, applied in `sync_turn`, `sync_department_turn` and to the prefetch query), so the Executive's own DM is never attributed to the person who replied to it. The block lands in the user turn (caching rule) and is injected into a copy only — the pristine reply is persisted to history. The linkage is one-shot (consumed on first matched reply, race-safe) so an unrelated later DM isn't re-hydrated. This is deterministic and independent of the per-person `peer_memory` (Honcho) layer.\n\nEvery adapter that persists a turn (Slack, Discord, Telegram, and the web route) records the message's **resolved sender** on `chat_messages.sender_person_id` — the rostered Person the adapter matched, or NULL for an unrostered sender — independently of the session owner, which falls back to the principal on Discord and Telegram so those threads stay visible. Attunement's open loops and feedback rely on this so an outsider's words are never read as someone on the roster's.\n\n### Google Drive folder sync\n\nSeparate from the Drive tools the gateway proxies. The optional folder sync (`knowledge.drive_sync`, `DRIVE_SYNC_ENABLED`; setup in `docs/drive_sync_setup.md`) copies the files in `DRIVE_SYNC_FOLDER_IDS` into the isolated `drive_docs` knowledge collection on a scheduler heartbeat, so the Executive knows those folders without searching Drive live (see RAG). It calls the Drive v3 API directly (`knowledge.drive_client`, `httpx`) as a **service account** with the `drive.readonly` scope (`DRIVE_SYNC_SERVICE_ACCOUNT_FILE`), not as the Executive's own account through workspace-mcp. Google enforces the folder scope, because the account sees only what is shared with it, and the sync can change nothing. Structured JSON means no display text to parse, and every file or folder id is checked against `[A-Za-z0-9_-]{1,128}` before it goes into a URL or a query. The two paths meet in two places. A synced chunk carries its Drive file id and sync time, so the Executive can open the live file with its own `get_drive_file_content`. The setup doc says to share each synced folder with the Executive's account too, so that live open works.\n\n### Your own Gmail (Act as me)\n\nA second, separate Gmail connection, for **Act as me** (see **Act as Me (Delegation)**): the principal's *own* mailbox, which `delegation.gmail.DelegateGmail` reads and drafts into over the Gmail REST API. It is never registered with the MCP gateway, so the model can reach it only through the typed `ghostwrite_email` handler — never by tool name through `call_tool`. The credential is one file per person in `DELEGATION_GOOGLE_CREDENTIALS_DIR` (default `company/delegation_google/`, `/data/delegation_google` in Docker), minted on a computer with a browser by `scripts/connect-own-gmail.py --email <you>` with the Executive's own OAuth client and the scopes `gmail.readonly` and `gmail.compose` — the same seed-it-yourself flow as the Executive's token, since the API serves no OAuth callback. It never lives in `WORKSPACE_MCP_CREDENTIALS_DIR`, where workspace-mcp picks a credential by address.\n\nEvery use re-checks with Google that the credential opens the mailbox on the person's People entry, and refuses outright when that address is the Executive's own: a shared mailbox would make everything the Executive writes look like theirs. Drafts are threaded (`In-Reply-To`, `References` of whole ids ending with the parent, `threadId`) and stamped `X-OE-Ghostwritten`; there is no send method. A Gmail rate limit, even as a 403, is an error to retry rather than a reconnect. The voice learner and the thread shown to the ghostwriter keep only each sender's own words through `email_poller.sender_new_text`, the poller's quoted-reply stripper made public. Setup status shows it as **Your own Gmail (Act as me)**.",
+ "markdown": "External channels connect callers to the Executive. Each inbound adapter resolves the sender to a Person — the chat adapters via `find_person_by_{slack,discord,telegram}_id`, the email poller via `people.identity.resolve_email_sender` (a primary address or an alias, then the company-domain rule; see Org) — and threads `person_id` into `Executive.chat()`. A sender who resolves to nobody is no longer simply dropped: see **New senders (roster requests)** below.\n\n### Inbound channels\n\n- **Slack** (`integrations.slack_bot`) — async Bolt socket-mode (`AsyncApp` + `AsyncSocketModeHandler`) embedded in the lifespan; responds to `@mention`s, DMs, and thread continuations, with per-conversation session memory (see **Conversation state** below). Text only: there is no interactivity endpoint and no Block Kit, so nothing Slack sends carries a button.\n- **Discord** (`integrations.discord_bot`) — discord.py gateway embedded in the lifespan; per-thread auto-titling, session-scoped memory, author attribution, configurable `@mention` thread promotion.\n- **Telegram** — webhook gating + per-chat history.\n- **Google Chat** — webhook + service-account auth. It resolves no approval gates and has no roster gate (the webhook authenticates Google, not the sender), and it never populates the session's trusted alert ids, so `ack_alert`'s trust check — which now runs on every session rather than only those declaring an `origin_channel` — refuses there by default, and its `<channel>` block says plainly that a sign-off cannot be answered from it.\n- **Email** (`integrations.email_poller`) — Gmail poll loop over the Google Workspace MCP (it starts only once the MCP gateway is up); strips Reply-To, filters auto-replies. Its sessions carry `origin_channel=\"email\"`: the untrusted-content policy (`orchestrator.content_trust`) reads that tag to tell mail from the principal's own surfaces — left empty, as it once was, every stranger's body reached the decision extractor as the principal's words. The mail goes into the turn inside an `<untrusted_content source=\"email\" author=\"<sender>\" author_verified=\"no\">` block that says it carries none of the principal's authority, with the framing line and any `[POLICY]` notice outside it; mail from the principal's primary address that Gmail authenticated (`dmarc=pass`) is their own words — but only their new text goes in unwrapped: when the mail quotes or forwards another message (`_new_text_lines` cut something), the message as received follows in an `<untrusted_content source=\"email_quoted\">` block, since a stranger's text they replied to or passed on is not theirs. While the Executive is paused (`scheduler.pause`) it skips each poll and leaves the inbox unread, so held mail is processed on the first poll after resume; the chat adapters above are not paused. The Executive sees the whole message; peer memory records only `_email_memory_text` — the subject, the sender's new text (cut at the first quoted or forwarded message) and the attachment filenames — parsed without backtracking-prone regexes, since the text is sender-controlled, and only for a rostered sender, the only kind with a peer to record into. The poller's `integration_inbound` row keeps the mail's text for the audit log, the way the reply's `chat_turn` row keeps the Executive's answer: `full.message` is the sender's new text (what web chat keeps for a turn), `full.attachments` the attachment filenames, and `details.preview` the first 120 characters of the new text, so /audit shows what was asked next to what was answered (the summary still reads `Inbound email from <sender>: <subject>`). The whole body with its quoted chain (`full.body`) is kept only on a row private to the principal: the chain is other people's mail — a contact's, on the principal's reply to one — and every signed-in user reads a public row. Each field is cut by its escaped JSON length (20,000 characters of text, 8,000 of attachment names), the measure the logger's 64 KB cap uses, so a long mail in a non-Latin script loses its tail rather than the row's structure. Outbound, the principal briefs and the client-rotation digest are emailed through the same gateway (`google_workspace__send_gmail_message`, from the Executive's own mailbox to the principal's address, subject `<brief title> — <date>`, the date in the user's zone) as formatted HTML — rendered from the brief's Markdown with raw HTML and images off, so text quoted from outside shows as text and opening the email loads nothing remote. Email is first when the principal prefers it, and otherwise the backup after every chat channel, tried only when Slack, Discord and Telegram are missing or fail; an in-band error from the tool counts as a failed send and the next channel is tried. An emailed brief is not a DM, so the per-Person outbound guard below does not apply — the gateway's roster egress gate does.\n\n Two senders get their own framing. Mail from one of the principal's **contacts** (a `kind=\"contact\"` People row — see Org) replaces the non-roster `[POLICY]` notice with a contact one: it names them (name and role/company), says not to reply unless the principal asks and not to tell anyone else, and asks for a summary for the principal instead. Both this turn and the forwarded-by-principal turn below are marked `Session.private_to_principal`: they can email, DM or invite only the principal, an alert they raise is private to the principal, and they are not offered the tools that reach anyone else or start work outside the turn (`schedule_tools.PRIVATE_TURN_WITHHELD_TOOLS`: broadcasts, meeting bookings, workflows, follow-ups, watches, artifacts, goal updates, skill drafts, connecting a new MCP server), and of the MCP tools only Google Workspace reads and the gated Gmail send (see MCP below). Every audit row about such mail is private to the principal (see Audit Log), the poller's two `integration_inbound` rows included (`_private_to_principal_mail`), so the audit log's other readers see none of it. The poller holds `audit.private_rows` for the whole handling of such a mail, because some rows are written before the turn binds its private session: the knowledge retrieval quotes the mail's From line, subject and opening. The rows themselves read exactly like an outside sender's: the `integration_inbound` row is the non-roster one (`accepted_non_roster`), and the notice opens with the non-roster notice's exact sentence. The poller handles each message with no session bound, so one message's private turn never marks the next message's rows. The turn stays unattributed (`person_id` None — no peer memory, no co-presence), and the gateway refuses mail to a contact on a poller turn anyway. Mail **forwarded by the principal** — the sender resolves to the principal and `_new_text_lines` reports a forwarded message — is wrapped in a `<forwarded_by_principal>` block: summarise it, draft a reply the principal could send (as text in the reply, never sent or saved as a Gmail draft), note any commitment or date, and offer to add the original sender as a contact (confirmed from the web app or the principal's Slack / Discord, since an ordinary email turn cannot change the People list — the one email that can is the principal's tokened reply to a roster-request email, which is parsed before any model turn; see below). The reply still goes to the principal only. The From header is unauthenticated, so this framing grants nothing: a spoofed \"forward\" just gets the real principal a summary.\n\nSlack, Discord, and Telegram are roster-gated on inbound: an unrostered sender's message never reaches the Executive (`details.outcome=\"rejected_unknown_sender\"`). The gates look up **team members only** — a contact's Slack, Discord or Telegram id is treated as unknown, so a contact can never talk to the bot (nor count as a co-present peer). What happens next is the roster request below — except for a contact, a thread continuation, a Telegram group or an unverified Telegram webhook, which stay silent. Email is not inbound-gated — non-roster mail flows through with a `[POLICY]` notice so triage can classify it. Slack/Discord thread continuations pass the shared `integrations.response_gate` (utility-fast model, biased toward replying).\n\n### New senders (roster requests)\n\nSomeone who writes in and is not on the People list — and is not one of the principal's contacts — is **held, acknowledged and asked about** instead of dropped (`integrations.roster_intake.intake` over the `people.roster_requests` ledger; lifecycle in Org). Each adapter calls it after its gate:\n\n- **Slack** — a DM or an `@mention` (not a thread continuation: the bot was not addressed there). The name and profile email come from `users_info` (5 s timeout). The acknowledgement goes in the DM, or as an **ephemeral** message for a mention, so nobody else in the channel learns who is and is not on the roster. The held event keeps only a fixed set of keys (text, user, channel, ts, thread, files).\n- **Discord** — a DM or a mention (not a thread the bot merely follows). The acknowledgement goes in the DM, or by DM for a channel mention; `/ask` answers the interaction with an ephemeral acknowledgement first (Discord allows 3 s), then holds the prompt. Its old \"ask the admin to add you\" reply is gone.\n- **Telegram** — only a **private** chat, and only when `TELEGRAM_WEBHOOK_SECRET` is set and valid: Telegram identifies the chat rather than the sender, and without the secret anyone could forge an update. A group, or an unverified webhook, stays silent as before. Attachment file ids are held and downloaded only on replay.\n- **Email** — non-roster mail that is not private to the principal (so never a contact's) and does not look machine-sent (`looks_automated`: a no-reply / notifications / billing-style local part, a `List-Id` / `List-Unsubscribe` / `Auto-Submitted` / bulk `Precedence` header, or a DMARC failure). The mail is **still triaged** by the Executive on this pass; its `[POLICY]` notice now says the sender was already told their message is waiting and the principal was asked who they are, so the model raises no second alert just to add them, and that the email will come back once they are added.\n\nEvery path skips a contact first (`find_person_by_*_id(..., include_contacts=True)`, or the email poller's private-mail rule): a contact has no chat access and gets no request and no acknowledgement, and the team-visible `rejected_unknown_sender` / `accepted_non_roster` rows read the same for a contact as for a stranger.\n\n**The acknowledgement** is one fixed text (`roster_intake.ACK_TEXT` — \"your message arrived … waiting for confirmation\"), never the model and never an echo of what they wrote, so a forged sender gains nothing by triggering it. It is sent at most once per sender per `ROSTER_ACK_WINDOW_DAYS` (7) and at most `ROSTER_ACK_DAILY_CAP` (20) a day across all senders (`claim_ack`, one transaction; a failed send releases its claim). An email acknowledgement is the one send the MCP gateway lets reach an address off the roster: `send_email_ack` sets `mcp_gateway.roster_ack_grant`, a one-shot ContextVar grant that admits a single `send_gmail_message` with exactly the granted recipient (a plain string, no list), subject and body and no other key, then is spent (audited `integration_outbound`, `kind: roster_ack`, private). An email sender is acknowledged only when Gmail authenticated them: once `claim_ack` succeeds, the poller's `send_ack` re-reads the mail as raw MIME and needs Gmail's own topmost `Authentication-Results` reporting `dmarc=pass` for the From domain (`fact_confirmation.sender_authenticated`, fail-closed). The printed headers the poller reads never carry that header, so without the second read a forged From would draw the acknowledgement to whoever it names — backscatter from the Executive's mailbox. An unauthenticated sender makes `send_ack` raise `roster_intake.AckWithheld`: the claim is released, and they are held silently. `authenticated_by_gmail` strips quoted strings and comments before reading the verdict — Gmail copies the envelope sender and DKIM tags into its own stamp, and a quoted local part could otherwise carry a fake `dmarc=pass` — and needs exactly one `dmarc=` verdict reading exactly `dmarc=pass header.from=<domain>` (Gmail may follow it with its own `dara=` resinfo, so its position is not checked). Residual: when Gmail writes no verdict at all (a From domain without DMARC) and echoes an unsanitised `;dmarc=pass header.from=…` elsewhere in its stamp, that echo would read as the verdict; bounded by the acknowledgement caps. A withheld acknowledgement is audited `roster_ack_withheld`. `intake` acknowledges before surfacing the card and telling the principal, and both follow the request's `ack_sent_at`: a withheld, failed or capped acknowledgement reads \"haven't been told anything yet\" on the Today card, in the principal's prompt and in the email `[POLICY]` notice.\n\n**Telling the principal.** A new request puts a private card on the principal's `/today` (see Today) and pushes a prompt on their delivery plan — preferred chat DM, then the others, then email — for a chat sender or an email sender on the company's own domain; an outside email sender waits on the card, as does everything past `ROSTER_REQUEST_DAILY_CAP` (30) pushes a day (the same cap bounds how many requests open a day; a declined sender is not raised again for 30 days). A chat prompt can be answered in place (\"that's Annamarie, add her to the team\"). An email prompt carries a one-time token (`RR-` + 20 base32 characters, stored hashed); the poller checks every inbound mail for one **before** triage (`try_email_roster_answer`): the reply must come from the principal's primary address exactly (not an alias, not the company-domain rule), carry the token of a pending request, not be an automatic reply, and not fail DMARC where the header is visible; and is parsed by `parse_decision`'s `roster_identity` shape — anything else falls through to the ordinary path. The token is hidden (`RR-[hidden]`) in every other Google Workspace result the gateway returns — the confirmation sits in the Executive's Sent folder, and any turn could otherwise read it — except the poller's own fetch of an inbound message (`mcp_gateway.reveal_roster_tokens`); a token-bearing mail that is not an answer is scrubbed before triage.\n\n**Replay.** Once the principal answers (web card, chat tool, email reply) — or a People-page / `upsert_person` write makes the sender match someone (`after_roster_write`) — the held messages are replayed through the adapter that received them (`register_replayer`: Slack re-runs the held event, Discord and Telegram their held text, email re-fetches the message from Gmail and handles it as mail from a known sender), oldest first, now attributed to the new Person. A teammate gets every held message; a new contact only held email (it takes the private contact path; held chat is dropped); a decline drops everything. Replays run in a **fresh `contextvars.Context`**: the answer may have come from the principal's own verified turn, and a stranger's message must never be read with the principal's session — and their contacts — still bound.\n\n### Standing facts by email (confirm by reply)\n\nThe principal can ask for a standing fact, a retirement or a company-profile edit by email, and the fact tools check it exactly as in chat (the own-words gates run on `_email_memory_text`, the sender's new text, not the quoted chain or attachments). An email's From line proves nothing, though, and a standing fact is read by every later prompt as the principal's own account. So an emailed change is **held, never applied**, until the principal's own mailbox confirms it (`integrations.fact_confirmation`, `memory.facts.fact_confirmations`):\n\n- **Who may ask.** The poller stamps every email turn with `Session.email_from` (the bare lowercased From address) and `email_authenticated`. The text the poller reads never carries `Authentication-Results` (workspace-mcp prints a fixed set of headers), so for mail claiming the principal's primary address it reads the message again as raw MIME (`fact_confirmation.sender_authenticated`) and requires Gmail's own stamp: the **topmost** `Authentication-Results` header (Gmail adds it on receipt, above anything the sender wrote), authserv-id `mx.google.com`, reporting `dmarc=pass` for the From address's domain, with the raw From matching (`authenticated_by_gmail`). It fails closed: no header, `dmarc=none`, a temporary error or a failed read all leave the turn unauthenticated. Mail from anyone else costs no second read and is never authenticated. `fact_tools._gate` admits an email turn only from the principal's **primary** address, exactly (no alias, no company-domain rule), authenticated, and not private to the principal (mail they forwarded stays refused, as do contacts, teammates and unknown senders).\n- **The hold.** The tool returns `awaiting_confirmation` (no action chip, and the model is told to say nothing has changed). `request_confirmation` stores the change with the SHA-256 of a fresh one-time token (`FC-` + 20 base32 characters, 100 bits; 7-day expiry; at most 10 waiting at once) and emails the token to the principal's roster address, outside any turn's outbound context. A profile edit is dry-run first, so one that cannot apply is reported in the turn, before any email goes out. If the email fails, nothing is held.\n- **Keeping the token from any model.** The tool result never carries it, and `mcp_gateway.hide_roster_tokens` now scrubs `FC-` tokens as well as `RR-` ones (`FC-[hidden]`) from every Google Workspace result except the poller's own fetch of an inbound message. Act as me's reads of the principal's own Gmail, where the confirmation email lands, hide them too (`delegation.gmail.parse_message` and the thread search), so the drafting model never sees a live token either.\n- **The reply.** `_handle_one_email` hands every message to `try_email_fact_confirmation` right after the roster-answer check, before any model turn. It acts only on a reply from the principal's primary address carrying the token of a **pending** confirmation. A made-up, spent, cancelled or expired reference matches nothing and falls through to the ordinary path with the token hidden, so no old or forged token can make the Executive email the principal. A reply with a live token is read again as raw MIME (`read_raw`) and must pass the same Gmail DMARC check as the request; one that doesn't (or whose raw read fails) is refused, the change keeps waiting, and the principal is told. Then an **automatic reply** is consumed quietly — no answer, no model turn, the change keeps waiting: the printed headers catch a Gmail vacation reply (`Precedence: bulk`), and the raw headers catch what they don't show (`automatic_reply`: `Auto-Submitted` other than `no`, `X-Auto-Response-Suppress` and similar, `Precedence: auto_reply`, an out-of-office subject), since an Exchange out-of-office echoes the token from the principal's own address and may well say \"I'll confirm on my return\". The raw message starts at the tool's exact separator line (`\\n\\n--- RAW MIME ---\\n`), so a sender-written Subject imitating it cannot supply the headers. CONFIRM (or yes / approve) applies the change through `fact_tools.apply_confirmed`, the same apply step chat uses. CANCEL (or no) drops it, and an unclear reply leaves it waiting. The principal gets a one-line result either way. A compare-and-set on the row means two replies can apply it only once.\n- **Audit.** Private `fact_confirmation` rows record held / applied / cancelled / refused. The applied change also writes the fact tools' usual private rows, with `source_channel=\"email\"` as its provenance.\n\n### Checking a channel is set up\n\nSettings → Setup status (`GET /setup/status`, `api/setup_checks.py`) gives each channel a light and a plain-language fix. It tests the credentials with one free read-only call — Slack `auth.test`; Telegram `getMe`, then `getWebhookInfo` (is a webhook registered, is it this app's `/webhook/telegram`, did a delivery fail in the past day); Discord `users/@me`, only while the bot is still connecting — and reads what the lifespan left on `app.state`: the Slack socket's `is_connected()`, the Discord bot's `is_ready()` together with its gateway socket being open (discord.py stays ready while it reconnects after a drop), or the exception its task stopped with (`LoginFailure`, `PrivilegedIntentsRequired`), and the MCP gateway. Because inbound is roster-gated, a connected Slack, Discord or Telegram is amber while nobody on the roster has its id (`slack_user_id`, `discord_user_id`, `telegram_chat_id`), or when its latest `integration_inbound` row is a `Rejected: …` from the past day whose sender still isn't on the roster — the page shows the sender's id, never message text. Local login with no `TELEGRAM_WEBHOOK_SECRET` is red for Telegram, since the local-login gate turns its webhook away. Google Chat and Gmail are checked from configuration: a numeric project number and a readable service-account key; the OAuth client (or service-account key) the workspace-mcp child signs in with.\n\nA channel setting written `KEY= # note` in a `.env` file arrives as the note's text, because python-dotenv strips only a comment that follows a value. `Settings` reads such a value as unset for the Slack, Telegram, Discord and Google Chat credentials, so the line no longer switches a channel on with its own comment as the token. `TELEGRAM_WEBHOOK_SECRET` is the exception, because read as unset a junk secret would turn the webhook's check off. It is kept instead, and since Telegram can only ever send 1–256 of `A-Z a-z 0-9 _ -` (what `setWebhook` accepts), a secret outside that set — a leftover comment, a pasted `<value from Step 2>` — could only be matched by someone who guessed it: while it is set the webhook refuses every update, neither the local-login gate nor the roster tools count it as proof (`Settings.telegram_webhook_secret_valid`), and Setup status shows it red (`.env.example` shipped four such lines; the notes now sit on their own lines).\n\n### Conversation state\n\nEvery adapter keys a deterministic `session_id` off the conversation surface and replays that session's stored turns into `Session.conversation_history`, so a follow-up (\"yes, go ahead\") lands with the question still in context. Slack's ids are `slack:dm:{user}`, `slack:thread:{channel}:{thread_ts}`, and `slack:channel:{channel}:{user}` for a mention that starts a thread; because the bot's reply roots a Slack thread at that message's `ts`, the turn is double-written to that thread's session too, so the first continuation inside it is not cold. A reply inside a thread THAT PERSON ROOTED also offers the parent `slack:channel:{channel}:{user}` id when matching an approval gate, since a gate raised on the mention recorded that session while the answer arrives under the thread's. The root-author check is load-bearing: widening on \"threaded and not a DM\" alone offered one person's channel session inside any thread in that channel, so a remark they made to a colleague could resolve their open gate and post the run's title into that colleague's thread. Discord has the same shape — its auto-thread router promotes a mention reply into a bot-owned thread — and the same alias. An @-mention inside a DM is handled once, by the DM path: Slack fires both events, and taking both forked the conversation across two session ids. The same id is the audit grouping key and the scope passed to `format_for_prompt`. A per-session `asyncio.Lock` serializes turns within one conversation — the inflight semaphore caps fan-out across the workspace, which does nothing to stop two messages in the same thread from both reading history before either writes it. Persistence happens after the reply is sent and its failure is logged, never surfaced: the user already has their answer.\n\nThis was absent on Slack until #136. Every message built a fresh `Session` and minted a per-*message* id (`thread_ts` falls back to the message's own `ts`, so a DM never repeated one), which meant a multi-turn confirmation could not work: the Executive asked whether to send a briefing to Slack, the user said yes, and the next turn had no record of the question.\n\n### What the model is told about the channel\n\nChat adapters pass a `<channel>` block (`integrations.channel_context`) in the **user turn** — never a cached system block. It names the surface, states that the person cannot see the app's cards or buttons, and draws the line the assistant kept crossing: briefing proposals and alerts are actioned on the briefing page; a proposal that books something can only be approved there; a workflow sign-off the Executive is explicitly waiting on *can* be answered in the conversation. The principal's DMs on Slack, Discord and Telegram also receive the open-alert digest (`briefing.context.format_open_alerts_for_prompt`) as the `<briefing>` block, gated to DMs because the board is company-wide and a shared channel must not pull it in. That digest is the ONLY trusted source of an `alert_id` for `ack_alert`. The briefing page's `[Discuss mode — alert_id=N]` primer is a pointer to which item is under discussion, not authority on its own: the server accepts that id only if it is also on the live board it derived itself. An id appearing anywhere else, including inside an alert's own body, is not trusted: alerts are minted from inbound email and chat, so their bodies are attacker-controlled. Two mechanisms enforce that rather than one prompt rule. Every field the digest interpolates is collapsed to a single line, because a newline in an attacker-written headline, suggested action, tag or review note would otherwise forge a whole extra `[N]` line — a fabricated instruction to clear somebody else's alert. And the live board the server derived is recorded on the session, so `ack_alert` refuses any id outside it — on EVERY session, web included; the web previously had no check at all. The recorded set is the whole live board (the cap `/today` renders as cards), not just the rows the digest printed, so a card past the digest's 30-row render cap is still ackable rather than sending the principal back to the page. Be precise about what this buys: it stops an id that is invented, closed, snoozed or expired, including one quoted out of an attacker-written alert body. It does NOT stop the model being argued into acking the wrong LIVE card — one alert's body can still make a case about another id that is genuinely open. Scoping trust to the single item under discussion would need the primer id carried server-side, which it is not.\n\n### Handler failures\n\nAn adapter's catch-all replies \"I encountered an error processing your request.\" On Slack that used to be the whole story — one uncorrelated log line, no audit row, and an unguarded error-send that could itself escape into Bolt. It now logs with the session, sender, channel, thread and mode, and writes an `integration_inbound` row with `details.outcome=\"handler_error\"`, joining the inbound row under the same `session_id`. Upstream, a single crashing tool handler no longer takes the turn down at all: the orchestrator's tool gathers use `return_exceptions=True`, hand the model an error `tool_result`, and audit it with `ok=false` (cancellation is re-raised, not swallowed).\n\n### Attachments\n\n`integrations.attachments` handles web chat, Discord, Telegram, Slack and Google Chat. Images become Anthropic vision blocks; documents (PDF/DOCX/TXT/MD/CSV) are inlined into the turn that carried them — inside an `<untrusted_content source=\"attachment\" author=\"<name>\">` block (`content_trust.wrap_untrusted`, whose closing tag the text cannot forge), under an `[Attached: <name>]` label, which the open-loop pass reads as \"not the speaker's words\" and the decision extractor strips before it reads the turn — and indexed into the ChromaDB `inbound_attachments` collection. 20 MB/file cap; web chat uses `POST /chat/upload`.\n\n**Scanned PDFs** are read, not reported empty. A PDF with no text layer goes through `knowledge.pdf_reader`: with `PDF_PROVIDER_READING=true` (opt-in, off by default) the deployment's own model reads it through its provider's PDF support (Anthropic natively, OpenRouter's `file-parser`, a local server only with `LOCAL_PDF_INPUT`); otherwise, and as the fallback, local OCR (pypdfium2 + RapidOCR, offline, no key) — so every deployment converts them. The label then reads `(converted from scanned pages)`, and an unreadable one says why. The index takes the text already extracted for the turn, so a scan is converted once. A file a channel delivered (everything here except `POST /chat/upload`, where the signed-in user sends it) converts at most `PDF_INBOUND_MAX_PAGES` (30) pages and draws on a rolling `PDF_INBOUND_PAGES_PER_HOUR` (300) budget shared by all senders, so sending scans cannot run up unbounded model spend or CPU.\n\nPer channel:\n- **Slack** — a `file_share` message (previously dropped outright for its `subtype`) is handled like any message; files download only after the roster gate and the response gate, with the bot token sent only to `https://files.slack.com/` (needs the `files:read` scope). History and peer memory record the words plus `(Attached files: …)`, never a document's text.\n- **Google Chat** — uploaded attachments download through `media.download` with the reply credentials (`chat.bot`), checked against the 20 MB cap per chunk, 5 per message; an attachment-only message is no longer dropped. The webhook authenticates Google, not the sender, so files are read only when the event's `user.email` is on the People roster (a team member); anyone else's files are named to the Executive, never downloaded. A Drive file shared into a message is left to the Drive tools, with its id.\n- **Email** — the poller (`integrations.email_attachments`) downloads up to 5 readable attachments of the message itself via `get_gmail_attachment_content` — workspace-mcp in stdio mode saves the file and answers `Saved to: <path>`, which must start its line, be the last such line and end in the answer's `Saved filename:` (the answer echoes the sender-chosen attachment name first, and a name carrying `Saved to: /…` must not redirect the read), then resolve inside the tool download folders — and appends their text to the turn (15k chars each). Only for a sender the principal knows (team, contact, principal); a stranger's files stay a list. It runs outside the model loop, so it works on private turns without adding the attachment tool to `PRIVATE_TURN_MCP_TOOLS`.\n- Anything else (a Drive PDF, a skipped attachment) — the Executive's `read_document` tool.\n\nIndexed chunks are keyed on `attachment:<bare filename>` and tagged `type=attachment`. An attachment's name is chosen by whoever sent the message and the name is the chunk-id namespace, so without the prefix an inbound `strategy-2026.md` would upsert over the curated company document of that name. The prefix separates inbound content from curated uploads and keeps provenance visible; it does not separate senders from one another.\n\nIsolation is the **collection**: `retriever.retrieve` never queries `inbound_attachments` at all, so an attachment cannot resurface as company knowledge in a later, unrelated turn. Attachment processing is roster-gated on Discord too — it previously ran before the gate, so an unrostered sender's file was downloaded and indexed before their message was dropped. These rows still have no operator surface: they are never written to `company/docs/`, so `GET /documents` does not list them.\n\nThis replaced a domain-based scheme that did not work. The chunks lived in `company_docs` under a domain outside the specialist set, on the premise that an unrecognised domain matched no filter. It matched every one — `ChromaDBStore.query` attaches a `where` clause only when a domain filter is present, and an Executive-level retrieval passes none — so attachments came back under “From your company documents”, top-ranked and indistinguishable from a curated upload. Legacy rows are migrated across on boot.\n\n### MCP gateway & outbound\n\nMCP runs in **both directions**. As a *client*, `orchestrator.mcp_gateway.MCPGateway` proxies MCP servers (Gmail, Calendar, Drive — whatever `mcp_servers.json` configures) as Executive tools, with egress gating on Gmail recipients, Calendar attendees, and Drive share grantees against the roster (and a refusal of public / whole-domain Drive sharing). The Gmail gate also accepts only a fixed set of argument keys, so workspace-mcp's `reply_all` (recipients taken from the thread, never checked) and `forward_message_id` / `include_forwarded_attachments` (forwarding any inbox message) are refused; a reply is `thread_id` plus an explicit, roster-checked `to`. Three more refusals close paths around those gates: every Apps Script tool (code running as the Executive's account, outside the gates, and since workspace-mcp 1.29.0 schedulable to keep running); any argument that makes the server fetch a URL (`fileUrl` / `file_url` on the Drive and import tools, a Gmail attachment given as a `url`), since the fetch can carry data out in its query string before any recipient gate matters; and text Google would mail to someone the roster never checked (`rsvp_comment` to an event's organizer, an out-of-office `decline_message` to whoever invites the Executive). Every gate reads its arguments by normalized spelling: workspace-mcp 1.29.0 renames a camelCase key such as `Attendees`, `userGoogleEmail` or `rsvpComment` to the real parameter, so a gate matching the exact key would never see it. Arguments that are not a JSON object are refused for the same reason. Google-side fetches are refused too: any key ending in `url` / `uri` at any depth whose value has a URL scheme (a Slides image or page background, a Docs or Forms image; a document hyperlink and a meeting link are stored, not fetched, and pass, as does a Drive file id), (a value is a URL after the characters a URL parser strips are removed, and `//host` counts), and on every tool that can write cells — the Sheets tools and the Drive create / update / import tools, which turn CSV into a Sheet — any string anywhere holding a formula call that fetches (`IMPORTDATA`, `IMPORTXML`, `IMPORTHTML`, `IMPORTFEED`, `IMAGE`), JSON-encoded or mid-CSV included: a string argument that encodes JSON is read as the server decodes it (one too large to read is refused), text is also scanned with character references decoded and comments / CDATA removed, and an upload that would become a native Sheet may only be text `content` — a `base64_content` or server-side `file_path` upload there is refused, since an XLSX hides its formulas behind zip members and XML encodings; a PNG to Drive or a DOCX to Docs is untouched. Not covered, unverified: whether Drive's HTML / Markdown import fetches an `<img src>` when it converts `content` into a Doc. A `manage_event` call that names no attendees is sent with `send_updates=\"none\"`, so the event's existing guests are not emailed text the gate never checked. The allow-list (`_egress_sets`, built by `_roster_allow_set` as a `people.identity.RosterAllow`) is every team member's email and email aliases plus the Executive's own address, always, and — for a teammate — any address on one of the company's own domains whose local part (`+tag` dropped) matches theirs, the same rule inbound mail is matched by; a **contact's** email joins it only when `people_tools.contacts_reachable_now()` is true — a turn the principal started on a verified surface (web chat, their own Slack or Discord, a verified private Telegram chat), or inside `grant_contact_egress()` (the decisions approve route, when the approver is the principal). On any other turn — an inbound email, a teammate, the scheduler, a workflow, the alert review — a contact's address is refused exactly like a stranger's, so the refusal cannot reveal that it belongs to a contact (contacts are private to the principal). The single exception to the roster rule is the fixed roster-request acknowledgement above, under its one-shot `roster_ack_grant`. A turn about the principal's private mail (`Session.private_to_principal`) narrows the list to the principal's own address and the Executive's. Such a turn may call only the MCP tools in `schedule_tools.PRIVATE_TURN_MCP_TOOLS`: Google Workspace reads (`search_gmail_messages`, `get_gmail_message_content`, `get_events`, `list_calendars`, `query_freebusy`, `search_drive_files`) and the two Gmail tools this gate narrows to the principal (`send_gmail_message`, `draft_gmail_message`). It is an exact allow-list, not a server: workspace-mcp runs at the `complete` tier, where a Google Chat message to a space, a Docs, Sheets or Drive write into a file already shared with others, `manage_event` on a shared calendar (its gate checks attendees and pins notifications, nothing else) reaches people with no recipient check; and every other server has none at all (a Slack or Notion server, the default `fetch` server, whose URL can carry the turn's content, a server loaded at runtime). Its `search_tools` results show only the allowed tools (`workflows.tool_catalog.filter_search_results`; output it cannot parse reads as no match), and a `call_tool` naming anything else is refused with an error tool_result and an audit row private to the principal (`schedule_tools.private_turn_withholds`), a missing name included. `search_tools` and `call_tool` stay offered, so the tool list and its cached prefix do not change. The typed calendar tool (`_resolve_attendees`) and the chat DM tools (`message_person`, `send_telegram_message`, `send_discord_dm` and their person-id recovery) apply the same rule — a contact's id reads as an unknown one off the principal's turn — and a private turn may DM or invite only the principal (`PRIVATE_TURN_REFUSAL` otherwise); `message_person` never falls back to a \"Needs you\" alert for a contact, who cannot sign in to see it. The Google Workspace server (`workspace-mcp`) behind those Gmail/Calendar/Drive tools runs **co-located inside the API** as a stdio child of the gateway — fitting the single-tenant model (one install = one company = one exec Google account), so there's no separate service to operate. It's baked into the API image and launched by `docker/workspace-mcp-launch.sh`, which selects single-user OAuth (token persisted at `/data/google_credentials`) or service-account domain-wide delegation from `GWORKSPACE_AUTH_MODE`. The optional `WORKSPACE_MCP_TOOLS` (comma-separated service names, default `all`) limits which Google services it loads. The gateway forwards the Google secrets to the child via `_FORWARDED_ENV_VARS`. Every `google_workspace__*` call acts as the Executive's own account. workspace-mcp takes the acting account per call (`user_google_email`) and nothing used to check it, so under domain-wide delegation a model-chosen address could open anyone's mailbox in the domain; `mcp_gateway._check_acting_account` now refuses a value naming any other address — before every other gate, with an `integration_outbound_blocked` audit row. An absent value stays allowed (the server's own account). As a *server*, `openexecutive.mcp_server` exposes OE's own company context and specialist council to external MCP clients at `/mcp` — the inverse direction; see the dedicated **MCP Server** section. The gateway launches extensible-mcp as a `uvx` subprocess whose fastembed tool-search index uses an embedding model baked into the API image and loaded offline, so it no longer re-downloads that model from the Hugging Face Hub on every cold start. extensible-mcp is pinned twice over: to a commit, which fixes its own code, and with `--exclude-newer`, which fixes the resolution of its dependencies — without the cutoff uvx re-resolves them against PyPI on every networked start, so a new release of any of them would reach running deployments on restart. Both live in `_EXTENSIBLE_MCP_LAUNCH_ARGS` in `orchestrator/mcp_gateway.py`, the Dockerfile's pre-warm uses the same arguments (a unit test enforces the match), so an image whose pre-warm succeeded starts the gateway with no network. The pre-warm is best-effort (`|| true`): an image built while GitHub was unreachable fetches the pinned commit on its first start instead. Updating the gateway is a deliberate bump of the commit and cutoff; `uv` itself is not pinned. Because the MCP stdio client does not inherit the parent environment, `MCPGateway.start()` explicitly forwards the embedding-cache/offline env vars (`FASTEMBED_CACHE_PATH`, `HF_HUB_OFFLINE`, …) into the child.\n\n**What the model is told is connected.** `MCPGateway.start()` records the configured server names (`server_names`), and the Executive renders them with the channel settings into block 0's *Connected Systems* section (`prompts.connected_systems`; see the caching section). While Google is connected that section pins the Google tool names the Executive uses constantly (`GOOGLE_TOOL_MANIFEST`) and tells it to call them with `call_tool` directly, with no `search_tools` round trip. extensible-mcp only runs a tool one of the session's searches has returned, and remembers it for the session's life, so the gateway does that discovery itself: the lifespan starts `MCPGateway.prime_pinned_tools()` in the background once the gateway is up with `google_workspace` configured (an exact-name search per pinned tool, the way `workflows.tool_catalog.resolve` does it; a name the search no longer finds is logged as workspace-mcp drift). A pinned call that still comes back with extensible-mcp's \"has not been discovered via search_tools\" refusal, for example before priming finished, is discovered and retried once. That happens after every gate has passed the same arguments, and only for pinned names: any other tool still needs the model's own search, and nothing here widens what a call may do, including the private-turn allow-list.\n\n**Emailing an artifact.** A Gmail send or draft may carry `attachments=[{\"artifact_id\": \"alert:12\", \"as\"?: \"docx\"}]`. `call_tool` runs the recipient gate first; only if it passes does `_expand_artifact_attachments` replace each such entry with the rendered file (`content` base64 + `filename` + `mime_type`, workspace-mcp's own attachment shape), produced by `artifact_records.render_artifact_file` — the same renderer as `/artifacts/{id}/download`. Only artifact rows resolve (never an arbitrary alert), links have no file, and an entry mixing `artifact_id` with other keys is refused. A stringified or single-object `attachments` is normalised first, so an artifact entry can never reach workspace-mcp unexpanded (it would silently drop it). At most 5 distinct artifacts per email (repeats are dropped) and 15 MB rendered in total; rendering runs off the event loop via `asyncio.to_thread`. A refusal writes `artifact_attachment_refused`; a successful send writes `artifact_attached` — both carry the recipients. Other attachment entries pass through unchanged.\n\n**Enablement, and why it degrades instead of dying.** `MCP_ENABLED` left unset is inferred from the presence of `mcp_servers_config_path` — dropping an `mcp_servers.json` next to `profile.yaml` turns MCP on with no further configuration. An **explicit** setting always wins in both directions: `MCP_ENABLED=false` keeps MCP off with the file still in place. It did not: `_resolve_mcp` tested `not self.mcp_enabled`, which cannot tell \"never set\" from \"set to false\", so the file's presence silently overrode the operator. The file is probed through `config.mcp_config_file_present`, never `Path.exists` directly — that re-raises an EACCES on a parent directory, and from inside a validator that comes out of `Settings()` itself, which `api/main.py` calls at module level. The check now reads `model_fields_set` (the fields the env actually supplied) and stores that on a private attr behind the read-only `mcp_auto_enabled` property, because the validator's own assignment joins that set and would otherwise make every auto-enable look explicit downstream.\n\nStartup is **best-effort**, in `main._start_mcp_gateway`. Two checks come before the subprocess: MCP off is a no-op, and a config defining no servers under `mcpServers` is logged and skipped — extensible-mcp's own loader raises on that and exits, and because the child is already gone the only thing that surfaces is anyio's \"Attempted to exit cancel scope in a different task\" from `stdio_client` unwinding, a traceback naming nothing about configuration. The start is also bounded (120s, generous because that child may still clone extensible-mcp on a cold start if the image's pre-warm failed): `ClientSession` carries no `read_timeout_seconds`, so `initialize()` waits forever on a child that is *alive but silent*, and an unbounded wait is a lifespan that never yields — the same healthcheck-never-passes symptom, which no `except` can see. A gateway that fails anyway is logged at ERROR with the config path, the servers it named, and whether the config file or an explicit `MCP_ENABLED` turned MCP on, then torn down under its own timeout; the API boots **without MCP tools and without the email poller** rather than refusing to boot. The guard catches `BaseException`, not `Exception`, re-raising a bare `CancelledError` first: the original failure came from anyio, which wraps a task group's failures in `BaseExceptionGroup` as soon as one is a `BaseException` — and that group is not an `Exception`, so `except Exception` would miss the very shape this contains. The teardown is contained too, since it runs from inside that `except` and would otherwise replace the actionable log with the crash it prevents. `configured_server_names` never raises either, and deliberately catches broadly: it reads an operator-owned path during startup, where an exception is the crash loop rather than a bug report — `Path.is_file` re-raises an EACCES on a parent directory, and `json.loads` answers deeply-nested input with `RecursionError`, which is not a `ValueError`. It tests `is_file()` so a directory or a symlink to a FIFO is never opened, and caps the read at 1 MiB. That exception used to propagate out of the lifespan and kill the container — under `restart: unless-stopped`, a crash loop whose only outward symptom was a healthcheck that never passed. Outbound tools: per-Person DMs (`send_slack_dm`, `send_discord_dm`, `send_telegram_message`) plus room-targeted `send_department_message` and `send_company_broadcast`. The per-Person DMs are additionally rate-limited and de-duplicated by the outbound anti-spam guard (below).\n\n### Outbound anti-spam guard\n\nEvery per-Person DM passes a deterministic guard (`orchestrator.outbound_guard.check_outbound_allowed`) after the roster gate and recipient-id recovery but before the network send — the single chokepoint **all** proactive DM paths reach (ad-hoc chat sends, the scheduler's followup/nudge dispatch, principal-brief delivery, the reflection turn, and research-finding routing). On a violation it returns a human-readable reason and the handler **suppresses** the send (`{\"status\":\"suppressed\",\"reason\":…}`), writes a `tool_invocation` audit row with `suppressed=true`, and writes **no** `done` activity row — so a blocked attempt never counts toward its own rate cap, and the Executive can read the reason and hold or `schedule_followup` for the recipient's next window. Three controls: **content dedup** (a near-identical message — whitespace/case-normalized, first 160 chars — already sent to the same recipient within `OUTBOUND_DEDUP_WINDOW_MINUTES`, default 360); a **per-recipient rate cap** (`OUTBOUND_MAX_PER_RECIPIENT_PER_WINDOW`, default 5, over `OUTBOUND_RATE_WINDOW_MINUTES`, default 60); and **quiet hours / availability** (`OUTBOUND_RESPECT_QUIET_HOURS`, default on — refuse while the recipient is on leave or outside their `people.channel` availability windows, surfacing the next open window). Delivery history is read from the existing `status='done'` `scheduled_actions` rows (`episodic.recent_sends_for_channel_ref`), so there is no new table. The guard is **fail-open**: any internal lookup error returns \"allow\", so it can never turn a working send into a crash or a silently-dropped message. Principal briefs and the internal heartbeat kinds use the `__internal__` channel and never reach these handlers, so they are unaffected.\n\n### Calendar & Google Meet\n\nThe Executive books meetings through two typed tools over the Calendar MCP. `create_calendar_event` schedules a **future** meeting (propose→approve by default, or auto-execute once that decision class is promoted) and may be used proactively when a stalled goal warrants a sync. `create_instant_meeting` spins up an **impromptu call starting now**, auto-executing without the approval step and skipping the business-hours/horizon caps, so the Executive can hand back a join link immediately. Both attach a **Google Meet** link by default (`add_google_meet`; opt out for in-person), parsed from the created event's `conferenceData` and surfaced to the caller plus persisted on the decision ledger. Either way the caps that matter still hold — roster membership, principal-protection, max attendees, and a daily booking ceiling.\n\n**Around-the-meeting participation.** The Executive doesn't join the call as a live voice; instead, on every successful booking it schedules a best-effort post-meeting follow-up (~5 min after the end) that DMs a human attendee asking for a quick recap — key decisions and action items. The reply flows back through the same cross-session DM context linkage described below, so the Executive can act on it (summarize, follow up) in a later turn. No meeting-transcript or Drive integration is required.\n\n### Cross-session DM context\n\nWhen the principal says \"DM Alex about X\" in one session, OE sends the DM and — if a live conversation is active and the recipient is not one of the principal's contacts (a contact cannot DM the bot, and quoting the principal's conversation into their email reply's unattended turn would put it in the audit log) — records an `outbound_context` linkage row (recipient, full outbound text, originating session id). Email is covered too but recorded one layer deeper — there is no `send_email` tool, so the linkage is written in `orchestrator.mcp_gateway` after a successful `google_workspace__send_gmail_message`, one row per `to`/`cc` recipient keyed by the bare lowercased address (OE's own address skipped). When Alex later replies on the 1:1 DM path — or by email — the shared helper `integrations.inbound_hydration.hydrate_user_message` (called by the Discord, Telegram, and Slack handlers, and by the email poller keyed on the sender address) looks up the most-recent `open` linkage for that sender within 72h and prepends an `<outbound_reply_context>` block — the outbound text plus a backstory excerpt from the originating session — to the message handed to `Executive.chat()`. So OE knows what the reply is about instead of starting from an empty per-person session. The block is context for the LLM turn only: peer memory strips it before recording what the person said (`strip_outbound_reply_context`, applied in `sync_turn`, `sync_department_turn` and to the prefetch query), so the Executive's own DM is never attributed to the person who replied to it. The block lands in the user turn (caching rule) and is injected into a copy only — the pristine reply is persisted to history. The linkage is one-shot (consumed on first matched reply, race-safe) so an unrelated later DM isn't re-hydrated. This is deterministic and independent of the per-person `peer_memory` (Honcho) layer.\n\nEvery adapter that persists a turn (Slack, Discord, Telegram, and the web route) records the message's **resolved sender** on `chat_messages.sender_person_id` — the rostered Person the adapter matched, or NULL for an unrostered sender — independently of the session owner, which falls back to the principal on Discord and Telegram so those threads stay visible. Attunement's open loops and feedback rely on this so an outsider's words are never read as someone on the roster's.\n\n### Google Drive folder sync\n\nThe synced files show on the knowledge page's Company documents list as \"Google Drive\" rows (sync time, last edit in Drive, an Open in Drive link and a text view), and the page's source card shows the last run, any sign-in error, and a **Sync now** button that runs one tick on demand.\n\n\nSeparate from the Drive tools the gateway proxies. The optional folder sync (`knowledge.drive_sync`, `DRIVE_SYNC_ENABLED`; setup in `docs/drive_sync_setup.md`) copies the files in `DRIVE_SYNC_FOLDER_IDS` into the isolated `drive_docs` knowledge collection on a scheduler heartbeat, so the Executive knows those folders without searching Drive live (see RAG). It calls the Drive v3 API directly (`knowledge.drive_client`, `httpx`) as a **service account** with the `drive.readonly` scope (`DRIVE_SYNC_SERVICE_ACCOUNT_FILE`), not as the Executive's own account through workspace-mcp. Google enforces the folder scope, because the account sees only what is shared with it, and the sync can change nothing. Structured JSON means no display text to parse, and every file or folder id is checked against `[A-Za-z0-9_-]{1,128}` before it goes into a URL or a query. The two paths meet in two places. A synced chunk carries its Drive file id and sync time, so the Executive can open the live file with its own `get_drive_file_content`. The setup doc says to share each synced folder with the Executive's account too, so that live open works.\n\n### Your own Gmail (Act as me)\n\nA second, separate Gmail connection, for **Act as me** (see **Act as Me (Delegation)**): the principal's *own* mailbox, which `delegation.gmail.DelegateGmail` reads and drafts into over the Gmail REST API. It is never registered with the MCP gateway, so the model can reach it only through the typed `ghostwrite_email` handler — never by tool name through `call_tool`. The credential is one file per person in `DELEGATION_GOOGLE_CREDENTIALS_DIR` (default `company/delegation_google/`, `/data/delegation_google` in Docker), minted on a computer with a browser by `scripts/connect-own-gmail.py --email <you>` with the Executive's own OAuth client and the scopes `gmail.readonly` and `gmail.compose` — the same seed-it-yourself flow as the Executive's token, since the API serves no OAuth callback. It never lives in `WORKSPACE_MCP_CREDENTIALS_DIR`, where workspace-mcp picks a credential by address.\n\nEvery use re-checks with Google that the credential opens the mailbox on the person's People entry, and refuses outright when that address is the Executive's own: a shared mailbox would make everything the Executive writes look like theirs. Drafts are threaded (`In-Reply-To`, `References` of whole ids ending with the parent, `threadId`) and stamped `X-OE-Ghostwritten`; there is no send method. A Gmail rate limit, even as a 403, is an error to retry rather than a reconnect. The voice learner and the thread shown to the ghostwriter keep only each sender's own words through `email_poller.sender_new_text`, the poller's quoted-reply stripper made public. Setup status shows it as **Your own Gmail (Act as me)**.",
"mermaid": "flowchart TD\n Channels[\"Slack / Discord<br/>Telegram / GChat / Email\"]\n Resolve[\"find_person_by_*_id\"]\n Gate[\"roster gate\"]\n Drop[\"drop\"]\n Hold[\"roster request<br/>(hold + fixed ack,<br/>ask the principal)\"]\n Exec[\"Executive.chat()\"]\n Attach[\"attachments<br/>(vision / inbound_attachments)\"]\n MCP[\"MCP gateway\"]\n Guard[\"outbound anti-spam guard<br/>(dedup / rate cap / quiet hours)\"]\n Out[\"DM / department<br/>/ broadcast tools\"]\n Channels --> Resolve\n Resolve --> Gate\n Gate -- \"unknown sender\" --> Hold\n Hold -- \"approved: replay\" --> Exec\n Hold -- \"contact / declined\" --> Drop\n Gate -- \"Person\" --> Exec\n Gate --> Attach\n Attach --> Exec\n Exec --> MCP\n Exec --> Guard\n Guard -- \"suppress\" --> Drop\n Guard -- \"allow\" --> Out\n Out --> Channels\n Own[(\"Principal's own Gmail<br/>(Act as me: REST, drafts only)\")]\n Exec -- \"ghostwrite_email\" --> Own\n class Channels entry\n class Resolve compute\n class Gate compute\n class Drop external\n class Hold compute\n class Exec hot\n class Attach compute\n class MCP external\n class Guard compute\n class Out compute\n class Own external",
- "generated_at": "2026-09-30T12:00:00Z"
+ "generated_at": "2026-10-01T14:23:59+00:00"
}
diff --git a/packages/core/openexecutive/architecture/prebuilt/rag.json b/packages/core/openexecutive/architecture/prebuilt/rag.json
index cf66d1f0..62746d7c 100644
--- a/packages/core/openexecutive/architecture/prebuilt/rag.json
+++ b/packages/core/openexecutive/architecture/prebuilt/rag.json
@@ -1,7 +1,7 @@
{
"section_id": "rag",
"title": "Knowledge & RAG",
- "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. When the caller passes `record_source`, `retrieve` also names every document its block quotes — company uploads by filename, built-in knowledge by a title made from its filename, Notion pages, synced Drive files by name with their Drive link, research notes by date, and earlier published documents with a link to `/artifacts/<id>` — so the web chat can list what an answer looked at: the chat route's own search, and each specialist's that answered (see the Lifecycle and API sections). The recording never raises, and a retrieval that fails leaves the specialist without context rather than failing the turn. Seven collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo, including a `sales` domain (founder-led sales, qualification and pipeline, proposals and pricing conversations, follow-up and forecasting) and solo-founder guides in finance, marketing, legal and HR. Seeded at boot by `loader.seed_builtin_knowledge` (FAILURES by `seed_failures`): the whole tree on an empty collection, otherwise only the `SHIPPED_BUILTIN_FILES` entries with no chunks yet — so a doc added in a later release reaches an install seeded by an earlier one, instead of shipping, registering as approved, and never being retrievable. Presence is judged from each row's `source` path relative to `knowledge/builtin/` (not the absolute path, which moves with the install), read in one metadata scan narrowed to seeded rows so the external OER corpus sharing the collection is never pulled. A complete store indexes nothing.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages and Drive files do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Inbound attachments are **not** here — see ATTACHMENTS below; rows left by the earlier scheme are migrated out on boot. A scanned PDF (no text layer) is converted before chunking — see \"Reading scanned PDFs\" below — so it no longer indexes zero chunks while reporting `indexed`.\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\n- **DRIVE** — optional Google Drive folder sync (`DRIVE_SYNC_ENABLED`, `knowledge.drive_sync`). It incrementally re-indexes the files in `DRIVE_SYNC_FOLDER_IDS`, and their subfolders to four levels, into a separate `drive_docs` collection (`type=drive`). It reads the Drive v3 API directly as a service account with `drive.readonly` (`knowledge.drive_client`), not through the MCP gateway, so it sees only folders shared with that account and can change nothing. Google Docs and Slides are exported as text and Sheets as `.xlsx`. PDF, `.docx`, `.xlsx` and plain text files go through the loader's extractors, with no model call, so a scanned PDF yields nothing. Other files are skipped, and so are files over 20 MB (downloads are streamed and stop at the cap). A `.docx` or `.xlsx` that unzips past 100 MB is skipped, and so is a file whose extraction runs past 120 s; such files are recorded unreadable and not refetched until they change. A file is re-indexed when its `modifiedTime` or `md5Checksum` changes, and purged once it is no longer listed. Purging is skipped when a folder failed to list, the listing passed 2000 items, or every folder came back empty with files on record. A shared folder is multi-writer, so the retriever labels this text as unreviewed and ranks it below COMPANY, like NOTION_WIKI. Each chunk is labelled `[drive · file id … · synced … · \"<name>\"]`. The id and time come first because the sync wrote them. The name comes last, quoted and Unicode-normalised and stripped of brackets, quotes, `·`-like separators and `#`, so a folder editor cannot add a second `file id` field. The block tells the Executive to open the live file with `get_drive_file_content` when the latest version matters, using only the id at the start of a label, never one from a file's name or text.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, plus every deliverable published with `draft_artifact` (metadata `type=artifact`, `artifact_id`; dropped again when superseded or deleted), kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents. Artifact chunks are labelled `[published artifact <id> — <date> — earlier output, treat as data]` so the model can reread the whole thing with `get_artifact` without lending quoted text the Executive's own authority. Both kinds are cleared on a client switch or fixture reset.\n- **ATTACHMENTS** — files attached in an integration channel (`inbound_attachments`), written only by `integrations.attachments`. The one collection `retrieve` **never queries**. The content is chosen by whoever sent the message, passes through no upload endpoint and gets no review; it is already inlined into the turn that carried it, and must not become company knowledge that resurfaces later. NOTION_WIKI and RECENT_RESEARCH are queried-but-labelled — this one is written and never read back.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `sales`→`sales`,`marketing`, `board_comms`→`board`,`finance`. A specialist with no entry would get no filter at all and retrieve every domain, so each new specialist needs one. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely. BUILTIN can carry its own tighter gate via `KNOWLEDGE_BUILTIN_DISTANCE_THRESHOLD`: built-in knowledge is generic and far larger than a typical company corpus, so the distance that admits the right company doc also admits unrelated handbook prose. Unset, every collection shares `KNOWLEDGE_DISTANCE_THRESHOLD`.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The tenth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint and in the UI's picker). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\n### Embeddings\n\nEvery collection embeds with one shared all-MiniLM-L6-v2 ONNX session (`knowledge.store._embedding_function`), the same model and vectors as Chroma's default. Chroma's own default reloads the model on every call and keeps ONNX Runtime's memory arena, so a 300-chunk upload peaked near 760 MB and each query spent ~240 ms reloading. The shared session is built once, runs without the arena and embeds four texts at a time (the model pads every text to 256 tokens, so batch size sets the peak): ~300 MB and ~30 ms. It answers to Chroma's name `default` with an empty config, because every existing collection records that name and Chroma refuses a collection opened with a differently named function; and it must not be a `DefaultEmbeddingFunction` instance, which Chroma swaps for a fresh default on every embed.\n\n### Reading scanned PDFs\n\npypdf returns only a PDF's saved text layer, so a scan, a phone photo saved as PDF, or a deck printed to PDF as images used to come back empty everywhere a PDF is read. `knowledge.pdf_reader.read_pdf_text` tries three readers in order and never raises:\n\n1. **Text layer** (pypdf) — used whenever it yields real text (at least ~20 visible characters per page, so a scan carrying only page numbers still falls through).\n2. **The deployment's own model, through its provider's PDF support** — opt-in, `PDF_PROVIDER_READING=true` (off by default: an upgrade never starts sending scanned PDFs off the server; this also means an Anthropic-direct deployment OCRs scans locally until it opts in) — the pages as a base64 `document` block, transcribed to Markdown by `PDF_VISION_MODEL` (unset: `DEFAULT_MODEL`, the model the deployment already runs on), `PDF_VISION_PAGES_PER_CALL` pages per request (default 20), three requests at a time. Each provider carries the block its own way: Anthropic reads it natively; on OpenRouter the translator makes it an OpenAI `file` part and the provider adds the `file-parser` plugin — engine `native` for Claude or any model the catalog lists with `file` input (OpenAI's GPT-4o and later, Gemini…), else `PDF_OPENROUTER_ENGINE` (default `mistral-ocr`, $2 per 1,000 pages); a local OpenAI-compatible server gets the `file` part only with `LOCAL_PDF_INPUT=true` (e.g. `LOCAL_BASE_URL` pointed at OpenAI's own API). `providers.registry.pdf_input_supported` decides; a model that cannot take one never receives it (the feature gate swaps a stray `document` block for a note). Turning it on sends scanned pages off the server — to the provider, and on OpenRouter possibly to its parser (Mistral OCR) — and the destination is logged once per process.\n3. **Local OCR** — pages rendered with pypdfium2 and read by RapidOCR (ONNX, models bundled in the wheel): offline, no key, no per-page cost. The default reader while step 2 is off, what a local model without PDF input gets, and the fallback on every provider when step 2 errors, refuses or returns nothing. `PDF_OCR_ENABLED=false` turns it off.\n\n`PDF_VISION_MAX_PAGES` (default 100) caps the pages read, with a note saying how many were; a file a channel delivered (`inbound=True`) is capped at `PDF_INBOUND_MAX_PAGES` (30) and metered by a rolling `PDF_INBOUND_PAGES_PER_HOUR` (300) budget. OCR is bounded too: a page renders within a 25-megapixel budget whatever its MediaBox claims (a crafted 20000pt page would otherwise allocate gigabytes), at most two documents OCR at once, and each stops after 240 s with what it has. A PDF of more than 2,000 pages is refused before any page is parsed (the caps above bound conversion, not the text-layer pass). A Claude slice that runs into the output limit is split in half until each part fits; a single page that still does not fit keeps what was written, marked `[transcription cut off here]`, and the note says so. A result is cached in process by the file's sha256 (32 entries) so a re-read does not re-bill; a failure is not cached. `loader.read_document_text` / `extract_text_from_file_async` route a PDF through it and every other type through the sync extractor, and are what `ingest_file` (uploads, boot reconcile), the `/documents/{filename}` preview, intake uploads, chat attachments, the email poller, `oe__read_file` and the Executive's `read_document` tool use.\n\n### The SME review gate\n\nBefore the distance threshold applies, both `retrieve` and `retrieve_failures` drop **withheld** items — anything the review store reports as `pending` or `rejected` (`ReviewStore.get_withheld_filenames`). Approved items with a priority set are then sorted ahead of the rest.\n\nKnowledge shipped with the product registers as a trusted default (`approved`, NULL `reviewed_at`), so nothing is withheld until a human deliberately queues a domain for curation or rejects something. See the **SME Knowledge Review** section for the full state model. The filter matches on the `(domain, filename)` pair Chroma carries. A bare filename was ambiguous *and* caller-choosable — `POST /knowledge/builtin` takes any `(domain, filename)`, so uploading a file named after a shipped doc in another domain silently withheld that shipped doc from every specialist. Failure case studies are keyed in their own namespace, so a user-authored one cannot collide with a shipped one.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.\n\n### Skills (Playbooks) collection\n\nSkills — called **playbooks** in the UI, where they are a tab on Workflows — are Markdown procedures with YAML frontmatter, indexed one document per skill in their own `skills` collection (name + description + when_to_use; the body is fetched by `load_skill`). Built-ins ship under `knowledge/builtin/skills/`; company skills live in `company/skills/`. Customizing a built-in (a `PUT` from the Playbooks tab; the chat tools refuse built-ins) writes a company skill of the same name flagged `customizes_builtin: true`, which **replaces** the built-in: it shadows the built-in everywhere (chat, and the workflows that follow it — see the Workflows section), and deleting it reverts. A built-in cannot be deleted, so \"delete\" **hides** it via `company/skills/.hidden.yaml`; hidden and shadowed built-ins are dropped from the index. `sync_builtin_skill_index` reconciles the built-in rows at startup, after a client-slot restore, and after a fixture reset — so a built-in added in a release reaches an already-seeded index, and a removed one leaves it.\n\n**Drafts.** The Executive's chat tools never change the library directly: `create_skill`, `update_skill` and `delete_skill` save a draft as JSON in `company/skills/.drafts/` (one per name; a newer proposal replaces the pending one). Drafts are not `*.md`, so they are never listed, indexed, searched, loaded or followed. A person approves a draft on the Playbooks tab (`POST /skill-drafts/{name}/approve`), which applies it through the ordinary skills operations, or discards it. Each save gets a fresh `id`, and approve/discard name the version the person saw: a proposal swapped in after review (say by a crafted inbound message) is never applied unseen, and approving never removes a newer draft that arrived meanwhile. This matches the draft → human-approval shape of custom workflows: a crafted inbound message can propose a playbook, but only a person can put one in effect.",
+ "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. When the caller passes `record_source`, `retrieve` also names every document its block quotes — company uploads by filename, built-in knowledge by a title made from its filename, Notion pages, synced Drive files by name with their Drive link, research notes by date, and earlier published documents with a link to `/artifacts/<id>` — so the web chat can list what an answer looked at: the chat route's own search, and each specialist's that answered (see the Lifecycle and API sections). The recording never raises, and a retrieval that fails leaves the specialist without context rather than failing the turn. Seven collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo, including a `sales` domain (founder-led sales, qualification and pipeline, proposals and pricing conversations, follow-up and forecasting) and solo-founder guides in finance, marketing, legal and HR. Seeded at boot by `loader.seed_builtin_knowledge` (FAILURES by `seed_failures`): the whole tree on an empty collection, otherwise only the `SHIPPED_BUILTIN_FILES` entries with no chunks yet — so a doc added in a later release reaches an install seeded by an earlier one, instead of shipping, registering as approved, and never being retrievable. Presence is judged from each row's `source` path relative to `knowledge/builtin/` (not the absolute path, which moves with the install), read in one metadata scan narrowed to seeded rows so the external OER corpus sharing the collection is never pulled. A complete store indexes nothing.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages and Drive files do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Inbound attachments are **not** here — see ATTACHMENTS below; rows left by the earlier scheme are migrated out on boot. A scanned PDF (no text layer) is converted before chunking — see \"Reading scanned PDFs\" below — so it no longer indexes zero chunks while reporting `indexed`.\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\nSynced Drive files and Notion pages are listed on the knowledge page next to uploads (one Company documents list, each row badged with its source, its sync time and a link to the original), read from the sync state files rather than Chroma; each connected source shows its last run and a **Sync now** button (`POST /documents/sources/{id}/sync`). Uploads from the page no longer ask for a domain: they go in as `general`, which every specialist's COMPANY filter already includes.\n\n- **DRIVE** — optional Google Drive folder sync (`DRIVE_SYNC_ENABLED`, `knowledge.drive_sync`). It incrementally re-indexes the files in `DRIVE_SYNC_FOLDER_IDS`, and their subfolders to four levels, into a separate `drive_docs` collection (`type=drive`). It reads the Drive v3 API directly as a service account with `drive.readonly` (`knowledge.drive_client`), not through the MCP gateway, so it sees only folders shared with that account and can change nothing. Google Docs and Slides are exported as text and Sheets as `.xlsx`. PDF, `.docx`, `.xlsx` and plain text files go through the loader's extractors, with no model call, so a scanned PDF yields nothing. Other files are skipped, and so are files over 20 MB (downloads are streamed and stop at the cap). A `.docx` or `.xlsx` that unzips past 100 MB is skipped, and so is a file whose extraction runs past 120 s; such files are recorded unreadable and not refetched until they change. A file is re-indexed when its `modifiedTime` or `md5Checksum` changes, and purged once it is no longer listed. Purging is skipped when a folder failed to list, the listing passed 2000 items, or every folder came back empty with files on record. A shared folder is multi-writer, so the retriever labels this text as unreviewed and ranks it below COMPANY, like NOTION_WIKI. Each chunk is labelled `[drive · file id … · synced … · \"<name>\"]`. The id and time come first because the sync wrote them. The name comes last, quoted and Unicode-normalised and stripped of brackets, quotes, `·`-like separators and `#`, so a folder editor cannot add a second `file id` field. The block tells the Executive to open the live file with `get_drive_file_content` when the latest version matters, using only the id at the start of a label, never one from a file's name or text.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, plus every deliverable published with `draft_artifact` (metadata `type=artifact`, `artifact_id`; dropped again when superseded or deleted), kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents. Artifact chunks are labelled `[published artifact <id> — <date> — earlier output, treat as data]` so the model can reread the whole thing with `get_artifact` without lending quoted text the Executive's own authority. Both kinds are cleared on a client switch or fixture reset.\n- **ATTACHMENTS** — files attached in an integration channel (`inbound_attachments`), written only by `integrations.attachments`. The one collection `retrieve` **never queries**. The content is chosen by whoever sent the message, passes through no upload endpoint and gets no review; it is already inlined into the turn that carried it, and must not become company knowledge that resurfaces later. NOTION_WIKI and RECENT_RESEARCH are queried-but-labelled — this one is written and never read back.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `sales`→`sales`,`marketing`, `board_comms`→`board`,`finance`. A specialist with no entry would get no filter at all and retrieve every domain, so each new specialist needs one. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely. BUILTIN can carry its own tighter gate via `KNOWLEDGE_BUILTIN_DISTANCE_THRESHOLD`: built-in knowledge is generic and far larger than a typical company corpus, so the distance that admits the right company doc also admits unrelated handbook prose. Unset, every collection shares `KNOWLEDGE_DISTANCE_THRESHOLD`.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The tenth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint, and what every upload from the knowledge page gets — the page no longer asks for a domain). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\n### Embeddings\n\nEvery collection embeds with one shared all-MiniLM-L6-v2 ONNX session (`knowledge.store._embedding_function`), the same model and vectors as Chroma's default. Chroma's own default reloads the model on every call and keeps ONNX Runtime's memory arena, so a 300-chunk upload peaked near 760 MB and each query spent ~240 ms reloading. The shared session is built once, runs without the arena and embeds four texts at a time (the model pads every text to 256 tokens, so batch size sets the peak): ~300 MB and ~30 ms. It answers to Chroma's name `default` with an empty config, because every existing collection records that name and Chroma refuses a collection opened with a differently named function; and it must not be a `DefaultEmbeddingFunction` instance, which Chroma swaps for a fresh default on every embed.\n\n### Reading scanned PDFs\n\npypdf returns only a PDF's saved text layer, so a scan, a phone photo saved as PDF, or a deck printed to PDF as images used to come back empty everywhere a PDF is read. `knowledge.pdf_reader.read_pdf_text` tries three readers in order and never raises:\n\n1. **Text layer** (pypdf) — used whenever it yields real text (at least ~20 visible characters per page, so a scan carrying only page numbers still falls through).\n2. **The deployment's own model, through its provider's PDF support** — opt-in, `PDF_PROVIDER_READING=true` (off by default: an upgrade never starts sending scanned PDFs off the server; this also means an Anthropic-direct deployment OCRs scans locally until it opts in) — the pages as a base64 `document` block, transcribed to Markdown by `PDF_VISION_MODEL` (unset: `DEFAULT_MODEL`, the model the deployment already runs on), `PDF_VISION_PAGES_PER_CALL` pages per request (default 20), three requests at a time. Each provider carries the block its own way: Anthropic reads it natively; on OpenRouter the translator makes it an OpenAI `file` part and the provider adds the `file-parser` plugin — engine `native` for Claude or any model the catalog lists with `file` input (OpenAI's GPT-4o and later, Gemini…), else `PDF_OPENROUTER_ENGINE` (default `mistral-ocr`, $2 per 1,000 pages); a local OpenAI-compatible server gets the `file` part only with `LOCAL_PDF_INPUT=true` (e.g. `LOCAL_BASE_URL` pointed at OpenAI's own API). `providers.registry.pdf_input_supported` decides; a model that cannot take one never receives it (the feature gate swaps a stray `document` block for a note). Turning it on sends scanned pages off the server — to the provider, and on OpenRouter possibly to its parser (Mistral OCR) — and the destination is logged once per process.\n3. **Local OCR** — pages rendered with pypdfium2 and read by RapidOCR (ONNX, models bundled in the wheel): offline, no key, no per-page cost. The default reader while step 2 is off, what a local model without PDF input gets, and the fallback on every provider when step 2 errors, refuses or returns nothing. `PDF_OCR_ENABLED=false` turns it off.\n\n`PDF_VISION_MAX_PAGES` (default 100) caps the pages read, with a note saying how many were; a file a channel delivered (`inbound=True`) is capped at `PDF_INBOUND_MAX_PAGES` (30) and metered by a rolling `PDF_INBOUND_PAGES_PER_HOUR` (300) budget. OCR is bounded too: a page renders within a 25-megapixel budget whatever its MediaBox claims (a crafted 20000pt page would otherwise allocate gigabytes), at most two documents OCR at once, and each stops after 240 s with what it has. A PDF of more than 2,000 pages is refused before any page is parsed (the caps above bound conversion, not the text-layer pass). A Claude slice that runs into the output limit is split in half until each part fits; a single page that still does not fit keeps what was written, marked `[transcription cut off here]`, and the note says so. A result is cached in process by the file's sha256 (32 entries) so a re-read does not re-bill; a failure is not cached. `loader.read_document_text` / `extract_text_from_file_async` route a PDF through it and every other type through the sync extractor, and are what `ingest_file` (uploads, boot reconcile), the `/documents/{filename}` preview, intake uploads, chat attachments, the email poller, `oe__read_file` and the Executive's `read_document` tool use.\n\n### The SME review gate\n\nBefore the distance threshold applies, both `retrieve` and `retrieve_failures` drop **withheld** items — anything the review store reports as `pending` or `rejected` (`ReviewStore.get_withheld_filenames`). Approved items with a priority set are then sorted ahead of the rest.\n\nKnowledge shipped with the product registers as a trusted default (`approved`, NULL `reviewed_at`), so nothing is withheld until a human deliberately queues a domain for curation or rejects something. See the **SME Knowledge Review** section for the full state model. The filter matches on the `(domain, filename)` pair Chroma carries. A bare filename was ambiguous *and* caller-choosable — `POST /knowledge/builtin` takes any `(domain, filename)`, so uploading a file named after a shipped doc in another domain silently withheld that shipped doc from every specialist. Failure case studies are keyed in their own namespace, so a user-authored one cannot collide with a shipped one.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.\n\n### Skills (Playbooks) collection\n\nSkills — called **playbooks** in the UI, where they are a tab on Workflows — are Markdown procedures with YAML frontmatter, indexed one document per skill in their own `skills` collection (name + description + when_to_use; the body is fetched by `load_skill`). Built-ins ship under `knowledge/builtin/skills/`; company skills live in `company/skills/`. Customizing a built-in (a `PUT` from the Playbooks tab; the chat tools refuse built-ins) writes a company skill of the same name flagged `customizes_builtin: true`, which **replaces** the built-in: it shadows the built-in everywhere (chat, and the workflows that follow it — see the Workflows section), and deleting it reverts. A built-in cannot be deleted, so \"delete\" **hides** it via `company/skills/.hidden.yaml`; hidden and shadowed built-ins are dropped from the index. `sync_builtin_skill_index` reconciles the built-in rows at startup, after a client-slot restore, and after a fixture reset — so a built-in added in a release reaches an already-seeded index, and a removed one leaves it.\n\n**Drafts.** The Executive's chat tools never change the library directly: `create_skill`, `update_skill` and `delete_skill` save a draft as JSON in `company/skills/.drafts/` (one per name; a newer proposal replaces the pending one). Drafts are not `*.md`, so they are never listed, indexed, searched, loaded or followed. A person approves a draft on the Playbooks tab (`POST /skill-drafts/{name}/approve`), which applies it through the ordinary skills operations, or discards it. Each save gets a fresh `id`, and approve/discard name the version the person saw: a proposal swapped in after review (say by a crafted inbound message) is never applied unseen, and approving never removes a newer draft that arrived meanwhile. This matches the draft → human-approval shape of custom workflows: a crafted inbound message can propose a playbook, but only a person can put one in effect.",
"mermaid": "flowchart TD\n Call[\"Specialist call<br/>(domain-filtered)\"] --> Q[\"retrieve(query, domain)\"]\n Q --> Builtin[(BUILTIN)]\n Q --> Company[(COMPANY)]\n Q --> NotionWiki[(NOTION_WIKI)]\n Q --> DriveDocs[(DRIVE)]\n Q --> Failures[(FAILURES)]\n Q --> Research[(RECENT_RESEARCH)]\n Attach[\"integrations.attachments\"] --> Attachments[(ATTACHMENTS<br/>never queried)]\n Builtin --> Dedupe[\"dedupe by text<br/>+ distance gate\"]\n Company --> Dedupe\n NotionWiki --> Dedupe\n DriveDocs --> Dedupe\n Failures --> Dedupe\n Research --> Dedupe\n Dedupe --> Inject[\"Inject into USER turn<br/>(not cached)\"]\n class Call entry\n class Q compute\n class Dedupe compute\n class Builtin storage\n class Company storage\n class NotionWiki storage\n class DriveDocs storage\n class Failures storage\n class Research storage\n class Attachments storage\n class Attach compute\n class Inject hot",
- "generated_at": "2026-09-30T15:22:47.773079+00:00"
+ "generated_at": "2026-10-01T14:23:59+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/knowledge.json b/packages/core/openexecutive/guide/prebuilt/knowledge.json
index 4319d7c3..b0dd99b3 100644
--- a/packages/core/openexecutive/guide/prebuilt/knowledge.json
+++ b/packages/core/openexecutive/guide/prebuilt/knowledge.json
@@ -1,7 +1,7 @@
{
"section_id": "knowledge",
"title": "Knowledge Base",
- "markdown": "**What it is:** Your document store. Upload company knowledge — handbooks, past decks, blog posts, policies — and the Executive searches it when answering.\n\n**What it does:**\n\n- Upload documents (PDF, Word, Markdown, plain text), organized by domain like product or finance.\n- Have each document automatically chunked and indexed for fast retrieval.\n- Let specialists pull the most relevant passages into their reasoning.\n- Test retrieval in **Query mode** — type a question and see exactly which passages the Executive would pull.\n- Add your own playbooks and lessons learned alongside the built-in ones.\n- Remove documents without disrupting live queries.\n\n**How to use:**\n\n*Upload a document*\n\n1. Open **Knowledge base** and click **Company** in the left-hand tree.\n2. Pick a domain — general, board, finance, hr, legal, marketing, operations, product, or strategy. The domain decides which specialists see it.\n3. Drag a file onto the drop area or click **Browse file** (PDF, DOCX, MD or TXT, up to 50 MB).\n4. Once *Indexing…* finishes, the document is searchable. Use **View** to check it or **Delete** to remove it. Uploaded documents can't be edited here — to replace one, **Delete** it first, then upload the new version.\n\n*Check what the Executive will find*\n\n1. Click **Query mode**, type a question, and click **Run**.\n2. Optionally narrow by **Specialist**, by source (**Include**), or by **Domains**. The results show which passages would be pulled and which specialists would see them — a lower distance means a closer match.\n\n*Add your own playbook*\n\n1. Expand **Built-in**, find the domain, and click **+** next to **Playbooks** (or **Failures** for a lessons-learned case).\n2. Enter a filename and the Markdown content, then click **Create file**.\n3. New playbooks wait in the **Review queue** (top of the tree) and aren't used until you approve them — or click **Approve** under the filename. Open any playbook and use **Edit** / **Preview** to change it later.\n\n**Example:** upload `pricing-policy-2026.pdf` under **finance**, then in Query mode ask *\"what discount can sales offer without approval?\"* to confirm the right passage comes back.\n\n*Note: there's also a read-only built-in knowledge base (curated business know-how) that ships with the app. Files attached in chat are not added to the Knowledge Base.*",
+ "markdown": "**What it is:** Your company's documents, in one place. Add handbooks, past decks, policies and plans, and the Executive reads them when answering. Files from a connected Google Drive folder or Notion workspace show up here too.\n\n**What it does:**\n\n- Opens on **Company documents**: one list of everything the Executive reads about your company, newest first.\n- Marks each document with where it came from — **Uploaded**, **Google Drive** or **Notion** — and when it was added or last synced.\n- Indexes each document automatically so specialists can pull the relevant passages into their reasoning.\n- Keeps connected sources up to date on a schedule, with a **Sync now** button when you can't wait.\n- Under **Advanced**: test retrieval in **Query mode**, browse the **Reference Library**, approve knowledge in the **Review queue**, and add your own playbooks and lessons learned.\n\n**How to use:**\n\n*Add a document*\n\n1. Open **Knowledge base**. It opens on **Company documents**.\n2. Drag files onto the drop area, or click **Add documents** (PDF, Word, Markdown or text, up to 50 MB each). You can add several at once.\n3. Once *Adding…* finishes, the document is searchable. Click its name or **View** to read the text the Executive sees, or **Delete** to remove it. To replace a document, delete it and add the new version.\n\n*Documents from Google Drive or Notion*\n\n1. Connect them in **Settings → Integrations**. Their files then appear in the list with a **Google Drive** or **Notion** badge, the time they were last synced and when they were last edited.\n2. **Open in Google Drive ↗** (or Notion) opens the original. Synced files can't be deleted here — remove them from the shared folder or Notion and they drop off on the next sync.\n3. Each connected source has a card above the list showing when it last synced and how often it syncs. Click **Sync now** to pick up a change straight away. If a sync failed, the card says why and links to the settings.\n\n*Check what the Executive will find*\n\n1. Open **Advanced → Query mode**, type a question, and click **Run**.\n2. Optionally narrow by **Specialist**, by source (**Include**), or by **Domains**. The results show which passages would be pulled and which specialists would see them — a lower distance means a closer match.\n\n*Add your own playbook*\n\n1. Open **Advanced**, expand **Built-in playbooks**, find the domain, and click **+** next to **Playbooks** (or **Failures** for a lessons-learned case).\n2. Enter a filename and the Markdown content, then click **Create file**.\n3. New playbooks wait in the **Review queue** and aren't used until you approve them — or click **Approve** under the filename. Open any playbook and use **Edit** / **Preview** to change it later.\n\n**Example:** add `pricing-policy-2026.pdf`, then in Query mode ask *\"what discount can sales offer without approval?\"* to confirm the right passage comes back.\n\n*Note: there's also a read-only built-in knowledge base (curated business know-how) that ships with the app. Files attached in chat are not added to the Knowledge Base.*",
"mermaid": null,
- "generated_at": "2026-09-23T00:00:00+00:00"
+ "generated_at": "2026-10-01T14:24:24+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/review.json b/packages/core/openexecutive/guide/prebuilt/review.json
index 28ce2147..bff4d519 100644
--- a/packages/core/openexecutive/guide/prebuilt/review.json
+++ b/packages/core/openexecutive/guide/prebuilt/review.json
@@ -1,7 +1,7 @@
{
"section_id": "review",
"title": "Review Queue",
- "markdown": "**What it is:** A quality-control queue for incoming knowledge, facts, and information *before* the Executive starts relying on it.\n\n**What it does:**\n\n- List items awaiting review with their status (pending, approved, rejected, needs revision) and priority.\n- Open any item to see its full content and where it came from.\n- Approve, reject, or flag an item for revision — and attach corrections without changing the original.\n- Bulk-approve everything pending, or a whole domain at once when you trust the source.\n\n**How to use:**\n\n1. Open **Knowledge base** in the sidebar and click **Review queue** at the top of the left-hand tree — the badge on both shows how many items are waiting.\n2. On the **Review queue** tab, click **View** on an item to read it and see where it came from.\n3. Decide:\n - **Approve** — the Executive can use it.\n - **Flag** — mark it *needs revision* as a reminder to follow up. A flagged item stays in use until you reject it.\n - **Reject** — keep it out; you can add a note saying why.\n - Use the priority dropdown (↓ Low / Normal / ↑ High) to order your queue.\n4. To fix a detail instead of rejecting the whole item, open **View**, type in *Add a correction or clarification…* and click **Add**. Active corrections are given to the Executive alongside the item; toggle one to **Inactive** to retire it.\n5. Trust a source? Click **Approve all pending**, or on the **All items** tab use **Approve all pending in *domain***.\n\n**Where items come from:** playbook and failure-case files you add or edit in the Knowledge Base, and any domain you choose to **Curate** — curating holds that domain's built-in knowledge back from the Executive until you approve it (**Stop curating** releases it). Company documents you upload go straight to the Knowledge Base and don't appear here.\n\n**Example:** you add a *discount-policy* playbook under finance. It shows up here as pending; open it, add the correction *\"Discounts over 15% need CFO sign-off\"*, then **Approve** — the Executive now uses the playbook with your correction attached.\n\n*Tip: when you open a playbook or failure case in the Knowledge base, its review status shows under the filename, with **Approve** and **Flag** right there.*\n\n*Note: approved and flagged items feed retrieval; pending and rejected ones are kept out. Editing an approved playbook flags it for re-review without taking it out of use.*",
+ "markdown": "**What it is:** A quality-control queue for incoming knowledge, facts, and information *before* the Executive starts relying on it.\n\n**What it does:**\n\n- List items awaiting review with their status (pending, approved, rejected, needs revision) and priority.\n- Open any item to see its full content and where it came from.\n- Approve, reject, or flag an item for revision — and attach corrections without changing the original.\n- Bulk-approve everything pending, or a whole domain at once when you trust the source.\n\n**How to use:**\n\n1. Open **Knowledge base** in the sidebar and open **Advanced** in the left-hand panel and click **Review queue** — the badge shows how many items are waiting, even while **Advanced** is closed.\n2. On the **Review queue** tab, click **View** on an item to read it and see where it came from.\n3. Decide:\n - **Approve** — the Executive can use it.\n - **Flag** — mark it *needs revision* as a reminder to follow up. A flagged item stays in use until you reject it.\n - **Reject** — keep it out; you can add a note saying why.\n - Use the priority dropdown (↓ Low / Normal / ↑ High) to order your queue.\n4. To fix a detail instead of rejecting the whole item, open **View**, type in *Add a correction or clarification…* and click **Add**. Active corrections are given to the Executive alongside the item; toggle one to **Inactive** to retire it.\n5. Trust a source? Click **Approve all pending**, or on the **All items** tab use **Approve all pending in *domain***.\n\n**Where items come from:** playbook and failure-case files you add or edit in the Knowledge Base, and any domain you choose to **Curate** — curating holds that domain's built-in knowledge back from the Executive until you approve it (**Stop curating** releases it). Company documents you upload go straight to the Knowledge Base and don't appear here.\n\n**Example:** you add a *discount-policy* playbook under finance. It shows up here as pending; open it, add the correction *\"Discounts over 15% need CFO sign-off\"*, then **Approve** — the Executive now uses the playbook with your correction attached.\n\n*Tip: when you open a playbook or failure case in the Knowledge base, its review status shows under the filename, with **Approve** and **Flag** right there.*\n\n*Note: approved and flagged items feed retrieval; pending and rejected ones are kept out. Editing an approved playbook flags it for re-review without taking it out of use.*",
"mermaid": null,
"generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/knowledge/drive_sync.py b/packages/core/openexecutive/knowledge/drive_sync.py
index 09b1af4a..2c299db6 100644
--- a/packages/core/openexecutive/knowledge/drive_sync.py
+++ b/packages/core/openexecutive/knowledge/drive_sync.py
@@ -469,14 +469,48 @@ async def _apply_tick(
"name": name,
"filename": slugify(name, item.id) if chunks else "",
"url": item.link,
+ "synced_at": synced_at,
}
stats["updated"] += 1
logger.info("drive_sync: indexed %s (%d chunks)", item.id, chunks)
state["last_run"] = now.isoformat()
+ state.pop("last_error", None)
save_state(state)
+# One tick at a time per process: the scheduler heartbeat and a "Sync now"
+# from the knowledge page share this, so a manual run can never interleave
+# with a scheduled one. A caller that finds it held skips (``busy`` in the
+# stats) rather than queueing behind a slow network phase.
+_RUN_LOCK = asyncio.Lock()
+
+
+# When the last tick in this process ended, failed or not. ``last_run`` is
+# stamped only on success and with the tick's start time, so a manual-sync
+# cooldown keyed on it alone lets a failing or slow source be re-run
+# back-to-back.
+_last_finished_at: datetime | None = None
+
+
+def is_syncing() -> bool:
+ return _RUN_LOCK.locked()
+
+
+def last_finished_at() -> datetime | None:
+ return _last_finished_at
+
+
+def _record_error(message: str) -> None:
+ """Keep a short, user-facing reason the last tick failed (never a trace)."""
+ try:
+ state = load_state()
+ state["last_error"] = message
+ save_state(state)
+ except Exception:
+ logger.exception("drive_sync: could not record the last error")
+
+
async def run_drive_sync(
*,
store: ChromaDBStore | None = None,
@@ -484,7 +518,31 @@ async def run_drive_sync(
now: datetime | None = None,
reconcile_only: bool = False,
) -> dict[str, int]:
- """One sync tick. Returns counts: seen / updated / skipped / failed / purged / capped."""
+ """One sync tick. Returns counts: seen / updated / skipped / failed / purged / capped
+ (plus ``busy`` when another tick is already running in this process)."""
+ if _RUN_LOCK.locked():
+ logger.info("drive_sync: a tick is already running — skipping")
+ return {"busy": 1}
+ global _last_finished_at
+ async with _RUN_LOCK:
+ try:
+ return await _run_drive_sync_locked(
+ store=store, client=client, now=now, reconcile_only=reconcile_only
+ )
+ except Exception:
+ _record_error("The last sync failed unexpectedly. Check the server logs.")
+ raise
+ finally:
+ _last_finished_at = datetime.now(UTC)
+
+
+async def _run_drive_sync_locked(
+ *,
+ store: ChromaDBStore | None,
+ client: DriveClient | None,
+ now: datetime | None,
+ reconcile_only: bool,
+) -> dict[str, int]:
settings = get_settings()
stats = {"seen": 0, "updated": 0, "skipped": 0, "failed": 0, "purged": 0, "capped": 0}
if not settings.drive_sync_enabled:
@@ -508,6 +566,7 @@ async def run_drive_sync(
token = service_account_token_provider(str(settings.drive_sync_service_account_file))
except Exception:
logger.exception("drive_sync: cannot load DRIVE_SYNC_SERVICE_ACCOUNT_FILE")
+ _record_error("Could not sign in to Google Drive. Check the Drive credentials.")
stats["failed"] += 1
return stats
http = httpx.AsyncClient(timeout=60.0)
@@ -556,6 +615,75 @@ def purge_all_synced(store: ChromaDBStore, state: dict[str, Any] | None = None)
return purged
+def list_synced_files() -> dict[str, Any]:
+ """What the knowledge page shows for Drive: one row per file on record.
+
+ Read from the sync state (not Chroma), so it costs one small JSON read.
+ ``indexed`` is false for a file with no readable text. Entries written
+ before ``synced_at`` was recorded per file fall back to the tick time.
+ """
+ state = load_state()
+ last_run = state.get("last_run") if isinstance(state.get("last_run"), str) else None
+ files: list[dict[str, Any]] = []
+ for fid, rec in state["files"].items():
+ safe = sanitize_drive_id(str(fid))
+ if not safe or not isinstance(rec, dict):
+ continue
+ filename = rec.get("filename") if isinstance(rec.get("filename"), str) else ""
+ files.append(
+ {
+ "id": safe,
+ "name": str(rec.get("name") or filename or safe),
+ "url": _https_or_none(rec.get("url")),
+ "modified_at": rec.get("modified") if isinstance(rec.get("modified"), str) else None,
+ "synced_at": rec.get("synced_at")
+ if isinstance(rec.get("synced_at"), str)
+ else last_run,
+ "indexed": bool(filename),
+ }
+ )
+ files.sort(key=lambda f: f["name"].lower())
+ error = state.get("last_error")
+ return {
+ "last_run": last_run,
+ "last_error": error if isinstance(error, str) else None,
+ "files": files,
+ }
+
+
+def read_synced_file(file_id: str) -> dict[str, Any] | None:
+ """The stored text of one synced file, or None when it is unknown or empty.
+
+ The path comes from the state record for a sanitized id, never from the
+ caller, and must be a ``drive-*.md`` name directly under ``docs/drive/``.
+ """
+ safe = sanitize_drive_id(file_id)
+ if not safe or safe != file_id:
+ return None
+ rec = load_state()["files"].get(safe)
+ if not isinstance(rec, dict):
+ return None
+ filename = Path(str(rec.get("filename") or "")).name
+ if not (filename.startswith("drive-") and filename.endswith(".md")):
+ return None
+ path = _docs_dir() / filename
+ try:
+ text = path.read_text(encoding="utf-8", errors="replace")
+ except OSError:
+ return None
+ text = _FILE_ID_COMMENT.sub("", text, count=1).lstrip()
+ return {
+ "id": safe,
+ "name": str(rec.get("name") or filename),
+ "url": _https_or_none(rec.get("url")),
+ "content": text,
+ }
+
+
+def _https_or_none(value: Any) -> str | None:
+ return value if isinstance(value, str) and value.startswith("https://") else None
+
+
# ---------------------------------------------------------------------------
# Heartbeat
# ---------------------------------------------------------------------------
diff --git a/packages/core/openexecutive/knowledge/notion_sync.py b/packages/core/openexecutive/knowledge/notion_sync.py
index c51b1c82..c64cb0bd 100644
--- a/packages/core/openexecutive/knowledge/notion_sync.py
+++ b/packages/core/openexecutive/knowledge/notion_sync.py
@@ -782,16 +782,22 @@ async def _apply_tick(
state["reconcile_skips"] = 0
if not reconcile_only:
+ synced_at = (now or datetime.now(UTC)).isoformat()
unresolved_times = list(fetch.unresolved_times)
for page, page_id, edited, markdown in fetch.fetched:
try:
chunks = await ingest_page(page, markdown, store)
filename = slugify(page_title(page), page_id)
- state.setdefault("pages", {})[page_id] = {
+ record: dict[str, Any] = {
"last_edited": edited,
"title": page_title(page),
"filename": filename,
+ "synced_at": synced_at,
}
+ url = page.get("url")
+ if isinstance(url, str) and url.startswith("https://"):
+ record["url"] = url
+ state.setdefault("pages", {})[page_id] = record
stats["updated"] += 1
logger.info(
"notion_sync: indexed %s (%d chunks)", page_title(page), chunks
@@ -823,9 +829,39 @@ async def _apply_tick(
state["watermark"] = candidate
state["last_run"] = (now or datetime.now(UTC)).isoformat()
+ state.pop("last_error", None)
save_state(state)
+# One tick at a time per process — see the matching lock in drive_sync.
+_RUN_LOCK = asyncio.Lock()
+
+
+# When the last tick in this process ended, failed or not. ``last_run`` is
+# stamped only on success and with the tick's start time, so a manual-sync
+# cooldown keyed on it alone lets a failing or slow source be re-run
+# back-to-back.
+_last_finished_at: datetime | None = None
+
+
+def is_syncing() -> bool:
+ return _RUN_LOCK.locked()
+
+
+def last_finished_at() -> datetime | None:
+ return _last_finished_at
+
+
+def _record_error(message: str) -> None:
+ """Keep a short, user-facing reason the last tick failed (never a trace)."""
+ try:
+ state = load_state()
+ state["last_error"] = message
+ save_state(state)
+ except Exception:
+ logger.exception("notion_sync: could not record the last error")
+
+
async def run_notion_sync(
*,
store: ChromaDBStore | None = None,
@@ -833,7 +869,31 @@ async def run_notion_sync(
now: datetime | None = None,
reconcile_only: bool = False,
) -> dict[str, int]:
- """One sync tick. Returns counts: seen / updated / skipped / failed / purged / capped."""
+ """One sync tick. Returns counts: seen / updated / skipped / failed / purged / capped
+ (plus ``busy`` when another tick is already running in this process)."""
+ if _RUN_LOCK.locked():
+ logger.info("notion_sync: a tick is already running — skipping")
+ return {"busy": 1}
+ global _last_finished_at
+ async with _RUN_LOCK:
+ try:
+ return await _run_notion_sync_locked(
+ store=store, client=client, now=now, reconcile_only=reconcile_only
+ )
+ except Exception:
+ _record_error("The last sync failed unexpectedly. Check the server logs.")
+ raise
+ finally:
+ _last_finished_at = datetime.now(UTC)
+
+
+async def _run_notion_sync_locked(
+ *,
+ store: ChromaDBStore | None,
+ client: httpx.AsyncClient | None,
+ now: datetime | None,
+ reconcile_only: bool,
+) -> dict[str, int]:
settings = get_settings()
stats = {
"seen": 0,
@@ -998,3 +1058,72 @@ def enqueue_next_notion_sync_scan(
except Exception:
logger.exception("notion_sync.enqueue_next: insert failed")
return None
+
+
+def list_synced_pages() -> dict[str, Any]:
+ """What the knowledge page shows for Notion: one row per page on record.
+
+ Mirrors ``drive_sync.list_synced_files``. Pages recorded before
+ ``synced_at`` / ``url`` were kept per page fall back to the tick time and
+ no link.
+ """
+ state = load_state()
+ last_run = state.get("last_run") if isinstance(state.get("last_run"), str) else None
+ raw_pages = state.get("pages")
+ pages: list[dict[str, Any]] = []
+ for pid, rec in (raw_pages if isinstance(raw_pages, dict) else {}).items():
+ safe = sanitize_notion_id(str(pid))
+ if not safe or not isinstance(rec, dict):
+ continue
+ filename = _safe_filename(str(rec.get("filename") or ""))
+ url = rec.get("url")
+ pages.append(
+ {
+ "id": safe,
+ "name": str(rec.get("title") or filename or safe),
+ "url": url if isinstance(url, str) and url.startswith("https://") else None,
+ "modified_at": rec.get("last_edited")
+ if isinstance(rec.get("last_edited"), str)
+ else None,
+ "synced_at": rec.get("synced_at")
+ if isinstance(rec.get("synced_at"), str)
+ else last_run,
+ "indexed": filename is not None,
+ }
+ )
+ pages.sort(key=lambda p: p["name"].lower())
+ error = state.get("last_error")
+ return {
+ "last_run": last_run,
+ "last_error": error if isinstance(error, str) else None,
+ "files": pages,
+ }
+
+
+def read_synced_page(page_id: str) -> dict[str, Any] | None:
+ """The stored Markdown of one synced page, or None when it is unknown.
+
+ The path comes from the state record for a sanitized id, never from the
+ caller, and must be a ``notion-*.md`` name directly under ``docs/notion/``.
+ """
+ safe = sanitize_notion_id(page_id)
+ if not safe:
+ return None
+ raw_pages = load_state().get("pages")
+ rec = raw_pages.get(safe) if isinstance(raw_pages, dict) else None
+ if not isinstance(rec, dict):
+ return None
+ filename = _safe_filename(str(rec.get("filename") or ""))
+ if filename is None:
+ return None
+ try:
+ text = (_docs_dir() / filename).read_text(encoding="utf-8", errors="replace")
+ except OSError:
+ return None
+ url = rec.get("url")
+ return {
+ "id": safe,
+ "name": str(rec.get("title") or filename),
+ "url": url if isinstance(url, str) and url.startswith("https://") else None,
+ "content": _PAGE_ID_COMMENT.sub("", text, count=1).lstrip(),
+ }
diff --git a/packages/core/tests/unit/test_document_sources_routes.py b/packages/core/tests/unit/test_document_sources_routes.py
new file mode 100644
index 00000000..3ddd73bb
--- /dev/null
+++ b/packages/core/tests/unit/test_document_sources_routes.py
@@ -0,0 +1,201 @@
+"""Routes behind the knowledge page's connected sources (Google Drive, Notion).
+
+The lists and viewers read the sync state files only; "Sync now" starts one
+tick of the same sync the scheduler runs, guarded so it can't overlap a
+running tick or fire again straight after one.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from openexecutive.api.routes import documents
+from openexecutive.knowledge import drive_sync, notion_sync
+
+from ._fake_store import FakeStore
+
+DRIVE_ID = "1docAAAAAAAA"
+PAGE_ID = "11111111-1111-1111-1111-111111111111"
+
+
+def company(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ monkeypatch.setenv("VECTOR_STORE_PATH", str(tmp_path / "chroma"))
+ monkeypatch.setenv("COMPANY_PROFILE_PATH", str(tmp_path / "company" / "profile.yaml"))
+ monkeypatch.setenv("DRIVE_SYNC_ENABLED", "true")
+ monkeypatch.setenv("DRIVE_SYNC_SERVICE_ACCOUNT_FILE", str(tmp_path / "sa.json"))
+ monkeypatch.setenv("DRIVE_SYNC_FOLDER_IDS", "1rootAAAAAAA")
+ monkeypatch.setenv("NOTION_SYNC_ENABLED", "false")
+ # Fresh locks per test: a module-level asyncio.Lock binds to the first
+ # loop that waits on it.
+ monkeypatch.setattr(drive_sync, "_RUN_LOCK", asyncio.Lock())
+ monkeypatch.setattr(notion_sync, "_RUN_LOCK", asyncio.Lock())
+ monkeypatch.setattr(drive_sync, "_last_finished_at", None)
+ monkeypatch.setattr(notion_sync, "_last_finished_at", None)
+ root = tmp_path / "company"
+ (root / "docs" / "drive").mkdir(parents=True)
+ (root / "docs" / "notion").mkdir(parents=True)
+ return root
+
+
+def client(company: Path) -> TestClient:
+ app = FastAPI()
+ app.include_router(documents.router)
+ app.state.store = FakeStore()
+ return TestClient(app)
+
+
+def _seed_drive(company: Path, **state: Any) -> None:
+ (company / "docs" / "drive" / "drive-1docaaaa-plan.md").write_text(
+ f"<!-- drive_file_id: {DRIVE_ID} -->\n\n# Plan\n\nRevenue grows.\n"
+ )
+ (company / "drive_sync_state.json").write_text(
+ json.dumps(
+ {
+ "last_run": "2026-09-30T10:00:00+00:00",
+ "files": {
+ DRIVE_ID: {
+ "name": "Plan",
+ "filename": "drive-1docaaaa-plan.md",
+ "url": f"https://docs.google.com/d/{DRIVE_ID}",
+ "modified": "2026-09-29T08:00:00Z",
+ "synced_at": "2026-09-30T10:00:00+00:00",
+ },
+ "1emptyAAAAAA": {"name": "Scan", "filename": ""},
+ },
+ **state,
+ }
+ )
+ )
+
+
+def test_drive_files_list_and_open(client: TestClient, company: Path) -> None:
+ _seed_drive(company)
+ body = client.get("/documents/drive").json()
+ assert body["enabled"] is True and body["last_run"] == "2026-09-30T10:00:00+00:00"
+ plan = next(f for f in body["files"] if f["id"] == DRIVE_ID)
+ assert plan == {
+ "id": DRIVE_ID,
+ "name": "Plan",
+ "url": f"https://docs.google.com/d/{DRIVE_ID}",
+ "modified_at": "2026-09-29T08:00:00Z",
+ "synced_at": "2026-09-30T10:00:00+00:00",
+ "indexed": True,
+ }
+ doc = client.get(f"/documents/drive/{DRIVE_ID}").json()
+ assert doc["name"] == "Plan" and doc["content"].startswith("# Plan")
+ assert client.get("/documents/drive/1emptyAAAAAA").status_code == 404
+ assert client.get("/documents/drive/unknownAAAAA").status_code == 404
+ assert client.get("/documents/drive/..%2F..%2Fprofile.yaml").status_code == 404
+
+
+def test_notion_pages_list_and_open(client: TestClient, company: Path) -> None:
+ (company / "docs" / "notion" / "notion-11111111-okrs.md").write_text(
+ f"<!-- notion_page_id: {PAGE_ID} -->\n\n# OKRs\n\nShip it.\n"
+ )
+ (company / "notion_sync_state.json").write_text(
+ json.dumps(
+ {
+ "last_run": "2026-09-30T09:00:00+00:00",
+ "pages": {
+ PAGE_ID: {
+ "title": "OKRs",
+ "filename": "notion-11111111-okrs.md",
+ "last_edited": "2026-09-29T00:00:00.000Z",
+ }
+ },
+ }
+ )
+ )
+ body = client.get("/documents/notion").json()
+ assert body["enabled"] is False
+ assert body["files"][0]["name"] == "OKRs"
+ assert body["files"][0]["synced_at"] == "2026-09-30T09:00:00+00:00" # legacy fallback
+ assert "Ship it." in client.get(f"/documents/notion/{PAGE_ID}").json()["content"]
+
+
+def test_sources_report_status(client: TestClient, company: Path) -> None:
+ _seed_drive(company, last_error="Could not sign in to Google Drive.")
+ sources = {s["id"]: s for s in client.get("/documents/sources").json()["sources"]}
+ assert sources["drive"]["enabled"] is True and sources["drive"]["file_count"] == 1
+ assert sources["drive"]["last_error"] == "Could not sign in to Google Drive."
+ assert sources["drive"]["syncing"] is False
+ assert sources["notion"]["enabled"] is False and sources["notion"]["last_run"] is None
+
+
+def test_upload_list_carries_source_and_domain(client: TestClient, company: Path) -> None:
+ (company / "docs" / "plan.md").write_text("# Plan")
+ store: FakeStore = client.app.state.store # type: ignore[attr-defined]
+ store.add_documents(
+ texts=["# Plan"],
+ metadatas=[{"filename": "plan.md", "domain": "finance"}],
+ ids=["c1"],
+ collection="company_docs",
+ )
+ docs = client.get("/documents").json()["documents"]
+ assert [(d["filename"], d["source"], d["domain"]) for d in docs] == [
+ ("plan.md", "upload", "finance")
+ ]
+
+
+def test_sync_now_starts_one_tick(
+ client: TestClient, company: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ calls: list[str] = []
+
+ async def fake_run() -> dict[str, int]:
+ calls.append("drive")
+ return {"updated": 0}
+
+ monkeypatch.setattr(drive_sync, "run_drive_sync", fake_run)
+ resp = client.post("/documents/sources/drive/sync")
+ assert resp.status_code == 202, resp.text
+ # The tick runs as a background task on the client's event loop.
+ deadline = time.monotonic() + 2
+ while not calls and time.monotonic() < deadline:
+ time.sleep(0.01)
+ assert calls == ["drive"]
+
+
+def test_sync_now_refuses_while_running_disabled_or_just_synced(
+ client: TestClient, company: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.setattr(drive_sync, "is_syncing", lambda: True)
+ assert client.post("/documents/sources/drive/sync").status_code == 409
+ monkeypatch.setattr(drive_sync, "is_syncing", lambda: False)
+
+ recent = (datetime.now(UTC) - timedelta(seconds=10)).isoformat()
+ _seed_drive(company, last_run=recent)
+ resp = client.post("/documents/sources/drive/sync")
+ assert resp.status_code == 429 and int(resp.headers["Retry-After"]) > 0
+
+ assert client.post("/documents/sources/notion/sync").status_code == 409 # not connected
+ assert client.post("/documents/sources/dropbox/sync").status_code == 422
+
+
+def test_sync_now_failure_stays_in_the_background(
+ client: TestClient, company: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ async def boom() -> dict[str, int]:
+ raise RuntimeError("network down")
+
+ monkeypatch.setattr(drive_sync, "run_drive_sync", boom)
+ assert client.post("/documents/sources/drive/sync").status_code == 202
+
+
+def test_a_failed_tick_still_starts_the_cooldown(client: TestClient, company: Path) -> None:
+ # A failing source never stamps last_run; the cooldown must still hold,
+ # or it could be re-run back-to-back. The service-account file is missing.
+ _seed_drive(company, last_run="2026-01-01T00:00:00+00:00")
+ asyncio.run(drive_sync.run_drive_sync(store=FakeStore())) # type: ignore[arg-type]
+ assert drive_sync.last_finished_at() is not None
+ assert client.post("/documents/sources/drive/sync").status_code == 429
diff --git a/packages/core/tests/unit/test_drive_sync.py b/packages/core/tests/unit/test_drive_sync.py
index 0b1e32e7..90935332 100644
--- a/packages/core/tests/unit/test_drive_sync.py
+++ b/packages/core/tests/unit/test_drive_sync.py
@@ -5,6 +5,7 @@ from __future__ import annotations
import asyncio
import io
import json
+from datetime import UTC, datetime
from pathlib import Path
from typing import Any
from unittest.mock import AsyncMock
@@ -539,3 +540,72 @@ def test_look_alike_separators_are_stripped_from_names() -> None:
label = _drive_label({"name": "a ∙ file id X [y]", "drive_file_id": DOC})
assert label.count("·") == 2 and "[" not in label and "(" not in label
+
+
+async def test_each_file_records_when_it_was_synced_and_lists_for_the_knowledge_page(
+ tmp_path: Path,
+) -> None:
+ now = datetime(2026, 9, 30, 12, 0, tzinfo=UTC)
+ await _sync(_drive(), FakeStore(), now=now)
+ state = _state(tmp_path)
+ assert state["files"][DOC]["synced_at"] == now.isoformat()
+
+ listing = drive_sync.list_synced_files()
+ assert listing["last_run"] == now.isoformat() and listing["last_error"] is None
+ by_id = {f["id"]: f for f in listing["files"]}
+ assert by_id[DOC]["name"] == "Q3 Finance Plan"
+ assert by_id[DOC]["url"] == f"https://docs.google.com/d/{DOC}"
+ assert by_id[DOC]["synced_at"] == now.isoformat() and by_id[DOC]["indexed"]
+
+ doc = drive_sync.read_synced_file(DOC)
+ assert doc is not None and "Revenue grows 12%" in doc["content"]
+ assert "drive_file_id" not in doc["content"]
+
+
+def test_listing_falls_back_to_last_run_and_drops_unsafe_links(tmp_path: Path) -> None:
+ (tmp_path / "drive_sync_state.json").write_text(
+ json.dumps(
+ {
+ "last_run": "2026-09-01T00:00:00+00:00",
+ "files": {
+ DOC: {"name": "Old", "filename": "", "url": "javascript:alert(1)"},
+ "../etc": {"name": "bad"},
+ },
+ }
+ )
+ )
+ files = drive_sync.list_synced_files()["files"]
+ assert [f["id"] for f in files] == [DOC]
+ assert files[0]["synced_at"] == "2026-09-01T00:00:00+00:00"
+ assert files[0]["url"] is None and files[0]["indexed"] is False
+ # No readable text on record, and ids that are not on record, read as nothing.
+ assert drive_sync.read_synced_file(DOC) is None
+ assert drive_sync.read_synced_file("../etc") is None
+
+
+def test_a_state_filename_outside_the_drive_dir_is_never_read(tmp_path: Path) -> None:
+ (tmp_path / "secret.md").write_text("nope")
+ (tmp_path / "drive_sync_state.json").write_text(
+ json.dumps({"files": {DOC: {"name": "x", "filename": "../secret.md"}}})
+ )
+ assert drive_sync.read_synced_file(DOC) is None
+
+
+async def test_a_second_tick_while_one_runs_is_skipped_as_busy() -> None:
+ async with drive_sync._RUN_LOCK:
+ assert drive_sync.is_syncing()
+ assert await _sync(_drive(), FakeStore()) == {"busy": 1}
+ assert not drive_sync.is_syncing()
+
+
+async def test_a_failed_sign_in_is_recorded_and_cleared_by_the_next_good_tick(
+ tmp_path: Path,
+) -> None:
+ # No client passed, and the service-account file does not exist.
+ await drive_sync.run_drive_sync(store=FakeStore()) # type: ignore[arg-type]
+ assert "sign in" in (drive_sync.list_synced_files()["last_error"] or "")
+ await _sync(_drive(), FakeStore())
+ assert drive_sync.list_synced_files()["last_error"] is None
diff --git a/packages/core/tests/unit/test_notion_sync.py b/packages/core/tests/unit/test_notion_sync.py
index 5a501296..78456338 100644
--- a/packages/core/tests/unit/test_notion_sync.py
+++ b/packages/core/tests/unit/test_notion_sync.py
@@ -822,3 +822,39 @@ async def test_truncated_listing_skips_reconcile_and_counts(
assert PAGE_GONE not in state["pages"]
assert state["reconcile_skips"] == 0
await client.aclose()
+
+
+async def test_synced_pages_list_with_link_and_time_for_the_knowledge_page(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from openexecutive.knowledge import notion_sync
+
+ page = _page(PAGE_NEW, "2026-06-02T00:00:00.000Z", "OKRs")
+ page["url"] = "https://www.notion.so/OKRs-abc"
+ _, _, state_file = await _run_sync(tmp_path=tmp_path, monkeypatch=monkeypatch, pages=[page])
+ record = json.loads(state_file.read_text())["pages"][PAGE_NEW]
+ assert record["url"] == "https://www.notion.so/OKRs-abc" and record["synced_at"]
+
+ with (
+ patch("openexecutive.knowledge.notion_sync._state_path", return_value=state_file),
+ patch("openexecutive.knowledge.notion_sync._docs_dir", return_value=tmp_path / "docs"),
+ ):
+ listing = notion_sync.list_synced_pages()
+ assert [p["name"] for p in listing["files"]] == ["OKRs"]
+ assert listing["files"][0]["url"] == "https://www.notion.so/OKRs-abc"
+ assert listing["files"][0]["synced_at"] == record["synced_at"]
+ assert listing["files"][0]["indexed"] is True
+ doc = notion_sync.read_synced_page(PAGE_NEW)
+ assert doc is not None and "Body" in doc["content"]
+ assert "notion_page_id" not in doc["content"]
+ assert notion_sync.read_synced_page("../../etc/passwd") is None
+
+
+async def test_a_second_notion_tick_while_one_runs_is_skipped_as_busy() -> None:
+ from openexecutive.knowledge import notion_sync
+
+ async with notion_sync._RUN_LOCK:
+ assert notion_sync.is_syncing()
+ assert await run_notion_sync() == {"busy": 1}
diff --git a/packages/ui/scripts/companyDocs.test.mjs b/packages/ui/scripts/companyDocs.test.mjs
new file mode 100644
index 00000000..060e969c
--- /dev/null
+++ b/packages/ui/scripts/companyDocs.test.mjs
@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+ filterDocs,
+ formatInterval,
+ formatSize,
+ mergeDocs,
+} from "../src/lib/companyDocs.ts";
+
+const upload = (filename, secs, domain = "general") => ({
+ filename,
+ size_bytes: 2048,
+ modified_at: secs,
+ domain,
+});
+const synced = (id, name, synced_at, modified_at = null, indexed = true) => ({
+ id,
+ name,
+ url: `https://docs.google.com/d/${id}`,
+ synced_at,
+ modified_at,
+ indexed,
+});
+
+test("uploads, Drive files and Notion pages merge into one list, newest first", () => {
+ const rows = mergeDocs(
+ [upload("plan.pdf", Date.parse("2026-09-01T00:00:00Z") / 1000)],
+ [synced("d1", "Budget", "2026-09-30T10:00:00Z", "2026-09-29T00:00:00Z")],
+ [synced("n1", "OKRs", "2026-09-15T00:00:00Z")],
+ );
+ assert.deepEqual(
+ rows.map((r) => [r.source, r.name]),
+ [
+ ["drive", "Budget"],
+ ["notion", "OKRs"],
+ ["upload", "plan.pdf"],
+ ],
+ );
+ assert.equal(rows[0].editedAt, "2026-09-29T00:00:00Z");
+ assert.equal(rows[2].sizeBytes, 2048);
+});
+
+test("the catch-all domain is not shown as a tag; a real one is", () => {
+ const rows = mergeDocs([upload("a.md", 1), upload("b.md", 2, "finance")], [], []);
+ assert.deepEqual(
+ rows.map((r) => [r.name, r.domain]),
+ [
+ ["b.md", "finance"],
+ ["a.md", null],
+ ],
+ );
+});
+
+test("rows without dates sort by name and unreadable files stay listed", () => {
+ const rows = mergeDocs([], [synced("d2", "Zeta", null, null, false), synced("d1", "Alpha", null)], []);
+ assert.deepEqual(rows.map((r) => r.name), ["Alpha", "Zeta"]);
+ assert.equal(rows[1].indexed, false);
+});
+
+test("filter by source and by name", () => {
+ const rows = mergeDocs([upload("Board deck.pdf", 1)], [synced("d1", "Budget", null)], []);
+ assert.deepEqual(filterDocs(rows, "drive", "").map((r) => r.name), ["Budget"]);
+ assert.deepEqual(filterDocs(rows, "all", "board").map((r) => r.name), ["Board deck.pdf"]);
+});
+
+test("sizes and intervals read naturally", () => {
+ assert.equal(formatSize(512), "512 B");
+ assert.equal(formatSize(2048), "2.0 KB");
+ assert.equal(formatSize(3 * 1024 * 1024), "3.0 MB");
+ assert.equal(formatInterval(60), "every hour");
+ assert.equal(formatInterval(120), "every 2 hours");
+ assert.equal(formatInterval(15), "every 15 min");
+});
diff --git a/packages/ui/src/components/knowledge/CompanyPanel.tsx b/packages/ui/src/components/knowledge/CompanyPanel.tsx
index 8197d3c1..ff3e3978 100644
--- a/packages/ui/src/components/knowledge/CompanyPanel.tsx
+++ b/packages/ui/src/components/knowledge/CompanyPanel.tsx
@@ -1,41 +1,139 @@
"use client";
-import { useEffect, useRef, useState } from "react";
-import ReactMarkdown from "react-markdown";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import Link from "next/link";
+import ReactMarkdown, { type Components } from "react-markdown";
import remarkGfm from "remark-gfm";
import {
deleteDocument,
getDocument,
+ getSyncedDocument,
listDocuments,
+ listSyncSources,
+ listSyncedDocuments,
+ syncSourceNow,
uploadDocument,
+ type SyncSourceStatus,
+ type SyncedDoc,
+ type SyncedSourceId,
type CompanyDoc,
- type CompanyDocContent,
} from "@/lib/api";
+import {
+ SOURCE_LABELS,
+ filterDocs,
+ formatInterval,
+ formatSize,
+ mergeDocs,
+ type DocRow,
+ type DocSource,
+} from "@/lib/companyDocs";
+import { formatRelativeTime } from "@/lib/relativeTime";
+import Icon from "@/components/Icon";
interface CompanyPanelProps {
- domains: string[];
+ /** Reports how many documents are listed, for the sidebar count. */
+ onCountChange?: (count: number) => void;
+}
+
+interface Viewing {
+ source: DocSource;
+ name: string;
+ url: string | null;
+ content: string;
}
+const ACCEPT = ".pdf,.docx,.doc,.md,.txt";
+const POLL_MS = 3000;
+
const PROSE_CLASS =
"prose prose-invert prose-sm max-w-none prose-p:text-fg prose-headings:text-fg prose-strong:text-fg prose-code:text-indigo-300 prose-code:bg-surface-overlay prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded prose-code:text-xs prose-code:before:content-none prose-code:after:content-none prose-pre:bg-surface-overlay prose-pre:border prose-pre:border-line-strong prose-blockquote:border-line-strong prose-blockquote:text-fg-muted prose-ul:text-fg prose-ol:text-fg prose-li:marker:text-fg-muted prose-hr:border-line-strong prose-a:text-indigo-400 prose-a:no-underline hover:prose-a:underline prose-table:text-fg prose-th:text-fg prose-th:border-line-strong prose-td:border-line-strong";
-export default function CompanyPanel({ domains }: CompanyPanelProps) {
- const [docs, setDocs] = useState<CompanyDoc[]>([]);
- const [isUploading, setIsUploading] = useState(false);
+const BADGE_CLASS: Record<DocSource, string> = {
+ upload: "bg-surface-input text-fg-muted border-line-strong",
+ drive: "bg-emerald-500/15 text-emerald-400 border-emerald-500/40",
+ notion: "bg-sky-500/15 text-sky-400 border-sky-500/40",
+};
+
+export default function CompanyPanel({ onCountChange }: CompanyPanelProps) {
+ const [uploads, setUploads] = useState<CompanyDoc[]>([]);
+ const [synced, setSynced] = useState<Record<SyncedSourceId, SyncedDoc[]>>({
+ drive: [],
+ notion: [],
+ });
+ const [sources, setSources] = useState<SyncSourceStatus[]>([]);
+ const [loaded, setLoaded] = useState(false);
+ const [uploadProgress, setUploadProgress] = useState<string | null>(null);
const [dragOver, setDragOver] = useState(false);
- const [domain, setDomain] = useState("general");
const [error, setError] = useState<string | null>(null);
- const [viewing, setViewing] = useState<CompanyDocContent | null>(null);
+ const [sourceFilter, setSourceFilter] = useState<DocSource | "all">("all");
+ const [query, setQuery] = useState("");
+ const [viewing, setViewing] = useState<Viewing | null>(null);
const [viewLoading, setViewLoading] = useState<string | null>(null);
+ const [syncMessage, setSyncMessage] = useState<Partial<Record<SyncedSourceId, string>>>({});
const fileInputRef = useRef<HTMLInputElement>(null);
- useEffect(() => {
- listDocuments()
- .then(setDocs)
- .catch(() => setError("Failed to load documents"));
+ const loadSynced = useCallback(async (ids: SyncedSourceId[]) => {
+ const lists = await Promise.all(
+ ids.map((id) => listSyncedDocuments(id).then((l) => [id, l.files] as const))
+ );
+ setSynced((prev) => {
+ const next = { ...prev };
+ for (const [id, files] of lists) next[id] = files;
+ return next;
+ });
}, []);
- // Close the viewer modal on Escape.
+ const loadAll = useCallback(async () => {
+ try {
+ const [docs, srcs] = await Promise.all([listDocuments(), listSyncSources()]);
+ setUploads(docs);
+ setSources(srcs);
+ // A source that was connected once keeps its files listed until the
+ // next sync purges them, so list any source with a run on record.
+ await loadSynced(srcs.filter((s) => s.enabled || s.last_run).map((s) => s.id));
+ } catch {
+ setError("Failed to load documents");
+ } finally {
+ setLoaded(true);
+ }
+ }, [loadSynced]);
+
+ useEffect(() => {
+ loadAll();
+ }, [loadAll]);
+
+ const rows = useMemo(
+ () => mergeDocs(uploads, synced.drive, synced.notion),
+ [uploads, synced]
+ );
+ const shown = useMemo(() => filterDocs(rows, sourceFilter, query), [rows, sourceFilter, query]);
+
+ useEffect(() => {
+ if (loaded) onCountChange?.(rows.length);
+ }, [loaded, rows.length, onCountChange]);
+
+ // While any source is syncing, poll its status; refresh its files when it
+ // finishes.
+ const syncingIds = sources.filter((s) => s.syncing).map((s) => s.id);
+ const syncingKey = syncingIds.join(",");
+ useEffect(() => {
+ if (!syncingKey) return;
+ const timer = window.setInterval(async () => {
+ try {
+ const next = await listSyncSources();
+ setSources(next);
+ const finished = syncingKey
+ .split(",")
+ .filter((id) => !next.find((s) => s.id === id)?.syncing) as SyncedSourceId[];
+ if (finished.length) await loadSynced(finished);
+ } catch {
+ // keep polling; a transient error shouldn't stop the spinner forever
+ }
+ }, POLL_MS);
+ return () => window.clearInterval(timer);
+ }, [syncingKey, loadSynced]);
+
+ // Close the viewer on Escape.
useEffect(() => {
if (!viewing) return;
const onKey = (e: KeyboardEvent) => {
@@ -45,38 +143,52 @@ export default function CompanyPanel({ domains }: CompanyPanelProps) {
return () => window.removeEventListener("keydown", onKey);
}, [viewing]);
- async function handleFile(file: File) {
- setIsUploading(true);
+ async function handleFiles(files: File[]) {
+ if (!files.length) return;
setError(null);
+ const failed: string[] = [];
+ for (const [i, file] of files.entries()) {
+ setUploadProgress(
+ files.length > 1 ? `Adding ${i + 1} of ${files.length}: ${file.name}…` : `Adding ${file.name}…`
+ );
+ try {
+ await uploadDocument(file);
+ } catch (e) {
+ failed.push(e instanceof Error ? e.message : `Failed to upload ${file.name}`);
+ }
+ }
+ setUploadProgress(null);
+ if (fileInputRef.current) fileInputRef.current.value = "";
+ if (failed.length) setError(failed.join(" · "));
try {
- await uploadDocument(file, domain);
- const updated = await listDocuments();
- setDocs(updated);
- } catch (e) {
- setError(e instanceof Error ? e.message : "Upload failed");
- } finally {
- setIsUploading(false);
- if (fileInputRef.current) fileInputRef.current.value = "";
+ setUploads(await listDocuments());
+ } catch {
+ setError("Failed to refresh documents");
}
}
- async function handleDelete(filename: string) {
- if (!confirm(`Delete "${filename}"? This removes it from the knowledge base.`)) return;
+ async function handleDelete(row: DocRow) {
+ if (!confirm(`Delete "${row.name}"? The Executive will stop using it.`)) return;
setError(null);
try {
- await deleteDocument(filename);
- setDocs((prev) => prev.filter((d) => d.filename !== filename));
+ await deleteDocument(row.ref);
+ setUploads((prev) => prev.filter((d) => d.filename !== row.ref));
} catch {
setError("Failed to delete document");
}
}
- async function handleView(filename: string) {
+ async function handleView(row: DocRow) {
setError(null);
- setViewLoading(filename);
+ setViewLoading(row.key);
try {
- const doc = await getDocument(filename);
- setViewing(doc);
+ if (row.source === "upload") {
+ const doc = await getDocument(row.ref);
+ setViewing({ source: "upload", name: doc.filename, url: null, content: doc.content });
+ } else {
+ const doc = await getSyncedDocument(row.source, row.ref);
+ setViewing({ source: row.source, name: doc.name, url: doc.url, content: doc.content });
+ }
} catch {
setError("Failed to load document");
} finally {
@@ -84,14 +196,45 @@ export default function CompanyPanel({ domains }: CompanyPanelProps) {
}
}
+ async function handleSyncNow(id: SyncedSourceId) {
+ setSyncMessage((m) => ({ ...m, [id]: undefined }));
+ const problem = await syncSourceNow(id);
+ if (problem) {
+ setSyncMessage((m) => ({ ...m, [id]: problem }));
+ return;
+ }
+ setSources((prev) => prev.map((s) => (s.id === id ? { ...s, syncing: true } : s)));
+ }
+
+ const connected = sources.filter((s) => s.enabled);
+ const usedSources = new Set(rows.map((r) => r.source));
+ const filterOptions: (DocSource | "all")[] = [
+ "all",
+ ...(["upload", "drive", "notion"] as DocSource[]).filter((s) => usedSources.has(s)),
+ ];
+
return (
- <div className="space-y-6 max-w-2xl">
- <div>
- <h2 className="text-base font-semibold text-fg">Company documents</h2>
- <p className="text-xs text-fg-muted mt-1">
- Uploaded files indexed into the company knowledge collection. The Executive
- retrieves from these alongside the built-in playbooks.
- </p>
+ <div className="space-y-5 max-w-3xl">
+ <div className="flex items-start justify-between gap-4">
+ <div>
+ <h1 className="text-lg font-semibold text-fg">Company documents</h1>
+ <p className="text-sm text-fg-muted mt-1">
+ Everything here is read by the Executive when it answers questions about your
+ company.
+ </p>
+ </div>
+ <label className="flex-shrink-0 cursor-pointer inline-flex items-center gap-1.5 px-3.5 py-2 rounded-lg bg-indigo-500 hover:bg-indigo-400 text-white text-sm font-medium transition-colors">
+ <Icon name="plus" size="w-4 h-4" />
+ Add documents
+ <input
+ ref={fileInputRef}
+ type="file"
+ multiple
+ className="hidden"
+ accept={ACCEPT}
+ onChange={(e) => handleFiles(Array.from(e.target.files ?? []))}
+ />
+ </label>
</div>
{error && (
@@ -100,6 +243,13 @@ export default function CompanyPanel({ domains }: CompanyPanelProps) {
</p>
)}
+ <SourcesStrip
+ connected={connected}
+ anyKnown={sources.length > 0}
+ messages={syncMessage}
+ onSyncNow={handleSyncNow}
+ />
+
<div
onDragOver={(e) => {
e.preventDefault();
@@ -109,122 +259,295 @@ export default function CompanyPanel({ domains }: CompanyPanelProps) {
onDrop={(e) => {
e.preventDefault();
setDragOver(false);
- const f = e.dataTransfer.files[0];
- if (f) handleFile(f);
+ handleFiles(Array.from(e.dataTransfer.files));
}}
- className={`rounded-xl border-2 border-dashed p-8 text-center transition-colors ${
- dragOver
- ? "border-indigo-500 bg-indigo-500/5"
- : "border-line-strong hover:border-line-strong"
- }`}
+ className={`rounded-xl border-2 border-dashed transition-colors text-center ${
+ rows.length === 0 && loaded ? "p-10" : "px-4 py-4"
+ } ${dragOver ? "border-indigo-500 bg-indigo-500/5" : "border-line-strong"}`}
>
- <p className="text-sm text-fg-muted mb-4">
- Drop a file here, or choose a domain and browse
- </p>
- <div className="flex items-center justify-center gap-3 flex-wrap">
- <select
- value={domain}
- onChange={(e) => setDomain(e.target.value)}
- className="rounded-lg border border-line-strong bg-surface-elevated px-3 py-1.5 text-sm text-fg focus:outline-none focus:ring-2 focus:ring-indigo-500/50"
- >
- <option value="general">general</option>
- {domains.map((d) => (
- <option key={d} value={d}>
- {d}
- </option>
- ))}
- </select>
- <label className="cursor-pointer px-4 py-1.5 rounded-lg bg-surface-input hover:bg-surface-input text-fg text-sm font-medium transition-colors">
- Browse file
- <input
- ref={fileInputRef}
- type="file"
- className="hidden"
- accept=".pdf,.docx,.doc,.md,.txt"
- onChange={(e) => {
- const f = e.target.files?.[0];
- if (f) handleFile(f);
- }}
- />
- </label>
- </div>
- <p className="text-xs text-fg-subtle mt-3">PDF, DOCX, MD, TXT — up to 50 MB</p>
- {isUploading && (
- <p className="mt-3 text-xs text-indigo-400 animate-pulse">Indexing…</p>
+ {uploadProgress ? (
+ <p className="text-sm text-indigo-400 animate-pulse">{uploadProgress}</p>
+ ) : (
+ <p className="text-sm text-fg-muted">
+ {rows.length === 0 && loaded
+ ? "No documents yet. Drop files here to add your first ones."
+ : "Drop files here to add them"}
+ <span className="block text-xs text-fg-subtle mt-1">
+ PDF, Word, Markdown or text, up to 50 MB each
+ </span>
+ </p>
)}
</div>
- {docs.length === 0 ? (
- <p className="text-sm text-fg-subtle text-center py-8">No documents uploaded yet.</p>
- ) : (
- <div className="space-y-2">
- <p className="text-xs font-semibold text-fg-muted uppercase tracking-widest mb-3">
- Uploaded documents
- </p>
- {docs.map((doc) => (
- <div
- key={doc.filename}
- className="flex items-center justify-between px-4 py-3 rounded-xl bg-surface-overlay/60 border border-line-strong/50"
- >
- <div>
- <p className="text-sm text-fg font-medium">{doc.filename}</p>
- <p className="text-xs text-fg-muted mt-0.5">
- {(doc.size_bytes / 1024).toFixed(1)} KB
- {" · "}
- {new Date(doc.modified_at * 1000).toLocaleDateString()}
- </p>
- </div>
- <div className="flex items-center gap-1">
+ {rows.length > 0 && (
+ <div className="space-y-3">
+ <div className="flex items-center gap-2 flex-wrap">
+ {filterOptions.length > 2 &&
+ filterOptions.map((opt) => (
<button
- onClick={() => handleView(doc.filename)}
- disabled={viewLoading === doc.filename}
- className="text-xs text-indigo-400 hover:text-indigo-300 disabled:opacity-50 px-2 py-1 rounded transition-colors"
+ key={opt}
+ onClick={() => setSourceFilter(opt)}
+ className={`text-xs px-2.5 py-1 rounded-full border transition-colors ${
+ sourceFilter === opt
+ ? "bg-surface-input text-fg border-line-strong"
+ : "text-fg-muted border-transparent hover:text-fg"
+ }`}
>
- {viewLoading === doc.filename ? "Loading…" : "View"}
+ {opt === "all" ? `All (${rows.length})` : SOURCE_LABELS[opt]}
</button>
- <button
- onClick={() => handleDelete(doc.filename)}
- className="text-xs text-red-400 hover:text-red-300 px-2 py-1 rounded transition-colors"
- >
- Delete
- </button>
- </div>
- </div>
- ))}
+ ))}
+ {rows.length > 8 && (
+ <input
+ value={query}
+ onChange={(e) => setQuery(e.target.value)}
+ placeholder="Search by name…"
+ className="ml-auto w-48 rounded-lg border border-line bg-surface-elevated px-2.5 py-1 text-xs text-fg placeholder-fg-subtle focus:outline-none focus:ring-2 focus:ring-indigo-500/40"
+ />
+ )}
+ </div>
+
+ <ul className="divide-y divide-line-strong/50 rounded-xl border border-line-strong/50 bg-surface-overlay/40">
+ {shown.map((row) => (
+ <DocListRow
+ key={row.key}
+ row={row}
+ loading={viewLoading === row.key}
+ onView={() => handleView(row)}
+ onDelete={() => handleDelete(row)}
+ />
+ ))}
+ {shown.length === 0 && (
+ <li className="px-4 py-6 text-sm text-fg-subtle text-center">
+ No documents match.
+ </li>
+ )}
+ </ul>
</div>
)}
- {viewing && (
- <div
- className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4"
- onClick={() => setViewing(null)}
- >
+ {viewing && <Viewer doc={viewing} onClose={() => setViewing(null)} />}
+ </div>
+ );
+}
+
+function SourcesStrip({
+ connected,
+ anyKnown,
+ messages,
+ onSyncNow,
+}: {
+ connected: SyncSourceStatus[];
+ anyKnown: boolean;
+ messages: Partial<Record<SyncedSourceId, string>>;
+ onSyncNow: (id: SyncedSourceId) => void;
+}) {
+ if (!anyKnown) return null;
+ if (connected.length === 0) {
+ return (
+ <p className="text-xs text-fg-subtle">
+ Connect Google Drive or Notion to bring documents in automatically.{" "}
+ <Link href="/settings/integrations" className="text-indigo-400 hover:underline">
+ Set up in Settings
+ </Link>
+ </p>
+ );
+ }
+ return (
+ <div className="grid gap-2 sm:grid-cols-2">
+ {connected.map((s) => {
+ const dot = s.syncing
+ ? "bg-indigo-400 animate-pulse"
+ : s.last_error
+ ? "bg-red-400"
+ : s.last_run
+ ? "bg-emerald-400"
+ : "bg-fg-subtle";
+ const message = messages[s.id];
+ return (
<div
- className="flex max-h-[85vh] w-full max-w-3xl flex-col rounded-2xl border border-line-strong bg-surface-elevated shadow-2xl"
- onClick={(e) => e.stopPropagation()}
+ key={s.id}
+ className="rounded-xl border border-line-strong/60 bg-surface-overlay/40 px-3.5 py-2.5"
>
- <div className="flex items-center justify-between gap-3 border-b border-line-strong/60 px-6 py-4">
- <div className="min-w-0">
- <p className="text-xs font-semibold uppercase tracking-widest text-indigo-400">
- Company document
- </p>
- <h3 className="truncate text-base font-semibold text-fg">
- {viewing.filename}
- </h3>
- </div>
+ <div className="flex items-center gap-2">
+ <span className={`h-2 w-2 rounded-full ${dot}`} aria-hidden />
+ <span className="text-sm font-medium text-fg">{s.label}</span>
<button
- onClick={() => setViewing(null)}
- className="flex-shrink-0 rounded-lg px-3 py-1.5 text-xs text-fg-muted hover:bg-surface-overlay hover:text-fg transition-colors"
+ onClick={() => onSyncNow(s.id)}
+ disabled={s.syncing}
+ className="ml-auto text-xs px-2.5 py-1 rounded-lg border border-line-strong text-fg hover:bg-surface-input disabled:opacity-60 disabled:cursor-default transition-colors"
>
- Close
+ {s.syncing ? "Syncing…" : "Sync now"}
</button>
</div>
- <div className={`flex-1 overflow-y-auto px-6 py-5 ${PROSE_CLASS}`}>
- <ReactMarkdown remarkPlugins={[remarkGfm]}>{viewing.content}</ReactMarkdown>
- </div>
+ <p className="text-xs text-fg-muted mt-1">
+ {s.syncing
+ ? "Checking for new and changed files…"
+ : s.last_run
+ ? `Last synced ${formatRelativeTime(s.last_run)} · ${s.file_count} ${
+ s.file_count === 1 ? "file" : "files"
+ }`
+ : "Not synced yet"}
+ <span className="text-fg-subtle"> · syncs {formatInterval(s.interval_minutes)}</span>
+ </p>
+ {(s.last_error || message) && (
+ <p className="text-xs text-red-400 mt-1">
+ {message ?? s.last_error}{" "}
+ {!message && (
+ <Link href="/settings/integrations" className="underline">
+ Check settings
+ </Link>
+ )}
+ </p>
+ )}
</div>
+ );
+ })}
+ </div>
+ );
+}
+
+function DocListRow({
+ row,
+ loading,
+ onView,
+ onDelete,
+}: {
+ row: DocRow;
+ loading: boolean;
+ onView: () => void;
+ onDelete: () => void;
+}) {
+ const details: string[] = [];
+ if (row.source === "upload") {
+ if (row.addedAt) details.push(`Added ${new Date(row.addedAt).toLocaleDateString()}`);
+ if (row.sizeBytes !== null) details.push(formatSize(row.sizeBytes));
+ } else {
+ if (!row.indexed) details.push("No readable text");
+ if (row.addedAt) details.push(`Synced ${formatRelativeTime(row.addedAt)}`);
+ if (row.editedAt)
+ details.push(
+ `edited in ${SOURCE_LABELS[row.source]} ${new Date(row.editedAt).toLocaleDateString()}`
+ );
+ }
+ return (
+ <li className="flex items-center gap-3 px-4 py-3">
+ <Icon name="doc" size="w-4 h-4" className="text-fg-subtle flex-shrink-0" />
+ <div className="min-w-0 flex-1">
+ <div className="flex items-center gap-2 min-w-0">
+ <button
+ onClick={onView}
+ disabled={!row.indexed}
+ className="text-sm text-fg font-medium truncate hover:text-indigo-300 disabled:hover:text-fg text-left transition-colors"
+ >
+ {row.name}
+ </button>
+ <span
+ className={`flex-shrink-0 text-[10px] font-medium px-1.5 py-0.5 rounded border ${BADGE_CLASS[row.source]}`}
+ >
+ {SOURCE_LABELS[row.source]}
+ </span>
+ {row.domain && (
+ <span className="flex-shrink-0 text-[10px] text-fg-subtle capitalize">
+ {row.domain}
+ </span>
+ )}
</div>
- )}
+ <p className="text-xs text-fg-muted mt-0.5 truncate">{details.join(" · ")}</p>
+ </div>
+ <div className="flex items-center gap-1 flex-shrink-0">
+ {row.indexed && (
+ <button
+ onClick={onView}
+ disabled={loading}
+ className="text-xs text-indigo-400 hover:text-indigo-300 disabled:opacity-50 px-2 py-1 rounded transition-colors"
+ >
+ {loading ? "Loading…" : "View"}
+ </button>
+ )}
+ {row.url && (
+ <a
+ href={row.url}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="text-xs text-fg-muted hover:text-fg px-2 py-1 rounded transition-colors"
+ >
+ Open in {SOURCE_LABELS[row.source]} ↗
+ </a>
+ )}
+ {row.source === "upload" ? (
+ <button
+ onClick={onDelete}
+ className="text-xs text-red-400 hover:text-red-300 px-2 py-1 rounded transition-colors"
+ >
+ Delete
+ </button>
+ ) : (
+ <span
+ className="text-[11px] text-fg-subtle px-2"
+ title={`Remove it from ${SOURCE_LABELS[row.source]} and it drops off on the next sync.`}
+ >
+ Managed in {SOURCE_LABELS[row.source]}
+ </span>
+ )}
+ </div>
+ </li>
+ );
+}
+
+function Viewer({ doc, onClose }: { doc: Viewing; onClose: () => void }) {
+ return (
+ <div
+ className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4"
+ onClick={onClose}
+ >
+ <div
+ className="flex max-h-[85vh] w-full max-w-3xl flex-col rounded-2xl border border-line-strong bg-surface-elevated shadow-2xl"
+ onClick={(e) => e.stopPropagation()}
+ >
+ <div className="flex items-center justify-between gap-3 border-b border-line-strong/60 px-6 py-4">
+ <div className="min-w-0">
+ <p className="text-xs font-semibold uppercase tracking-widest text-indigo-400">
+ {doc.source === "upload" ? "Uploaded document" : `From ${SOURCE_LABELS[doc.source]}`}
+ </p>
+ <h3 className="truncate text-base font-semibold text-fg">{doc.name}</h3>
+ </div>
+ <div className="flex items-center gap-1 flex-shrink-0">
+ {doc.url && (
+ <a
+ href={doc.url}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="rounded-lg px-3 py-1.5 text-xs text-fg-muted hover:bg-surface-overlay hover:text-fg transition-colors"
+ >
+ Open original ↗
+ </a>
+ )}
+ <button
+ onClick={onClose}
+ className="rounded-lg px-3 py-1.5 text-xs text-fg-muted hover:bg-surface-overlay hover:text-fg transition-colors"
+ >
+ Close
+ </button>
+ </div>
+ </div>
+ <div className={`flex-1 overflow-y-auto px-6 py-5 ${PROSE_CLASS}`}>
+ <ReactMarkdown remarkPlugins={[remarkGfm]} components={SAFE_MARKDOWN}>
+ {doc.content}
+ </ReactMarkdown>
+ </div>
+ </div>
</div>
);
}
+
+// Synced Drive / Notion text is written by anyone who can edit the shared
+// folder or page, so the viewer never fetches its images (a remote image is a
+// read beacon) and opens its links in a new tab, away from the app.
+const SAFE_MARKDOWN: Components = {
+ img: ({ alt }) => <span className="text-fg-subtle">[image{alt ? `: ${alt}` : ""}]</span>,
+ a: ({ href, children }) => (
+ <a href={href} target="_blank" rel="noopener noreferrer nofollow">
+ {children}
+ </a>
+ ),
+};
diff --git a/packages/ui/src/components/knowledge/KnowledgeWorkspace.tsx b/packages/ui/src/components/knowledge/KnowledgeWorkspace.tsx
index caf45c68..82f2df98 100644
--- a/packages/ui/src/components/knowledge/KnowledgeWorkspace.tsx
+++ b/packages/ui/src/components/knowledge/KnowledgeWorkspace.tsx
@@ -53,9 +53,11 @@ export default function KnowledgeWorkspace() {
const [failureFiles, setFailureFiles] = useState<BuiltinFileMeta[]>([]);
// `/knowledge?view=review` (and the old `/review` route, which redirects
// here) opens straight onto the review queue.
+ // Everything else opens on the company documents.
const [selection, setSelection] = useState<Selection>(() =>
- searchParams.get("view") === "review" ? { kind: "review" } : null
+ searchParams.get("view") === "review" ? { kind: "review" } : { kind: "company" }
);
+ const [companyCount, setCompanyCount] = useState<number | null>(null);
const [reviewCount, setReviewCount] = useState(0);
const [fileReview, setFileReview] = useState<ReviewItem | null>(null);
// Bumped on every review-status request; only the latest may write, so a
@@ -183,7 +185,7 @@ export default function KnowledgeWorkspace() {
selection.fileKind === "builtin" ? deleteBuiltinFile : deleteFailureFile;
try {
await deleter(selection.domain, selection.filename);
- setSelection(null);
+ setSelection({ kind: "company" });
await loadIndex();
} catch {
setError("Failed to delete file");
@@ -212,19 +214,15 @@ export default function KnowledgeWorkspace() {
return (
<div className="flex h-full">
<aside className="w-64 flex-shrink-0 border-r border-line bg-surface/40 px-4 py-5 overflow-y-auto">
- <input
- value={filter}
- onChange={(e) => setFilter(e.target.value)}
- placeholder="Filter files…"
- className="w-full mb-4 rounded-lg border border-line bg-surface-elevated px-2.5 py-1.5 text-xs text-fg placeholder-fg-subtle focus:outline-none focus:ring-2 focus:ring-indigo-500/40"
- />
<SourceTree
domains={DOMAINS}
builtinFiles={builtinFiles}
failureFiles={failureFiles}
selection={selection}
filter={filter}
+ onFilterChange={setFilter}
reviewCount={reviewCount}
+ companyCount={companyCount}
onSelect={setSelection}
/>
</aside>
@@ -236,10 +234,6 @@ export default function KnowledgeWorkspace() {
</div>
)}
- {selection === null && (
- <EmptyState />
- )}
-
{selection?.kind === "file" && selectedContent && (
<FileEditor
file={selectedContent}
@@ -270,12 +264,12 @@ export default function KnowledgeWorkspace() {
onSave={(domain, filename, content) =>
handleCreate(selection.fileKind, domain, filename, content)
}
- onCancel={() => setSelection(null)}
+ onCancel={() => setSelection({ kind: "company" })}
/>
)}
{selection?.kind === "review" && <ReviewQueue />}
- {selection?.kind === "company" && <CompanyPanel domains={DOMAINS} />}
+ {selection?.kind === "company" && <CompanyPanel onCountChange={setCompanyCount} />}
{selection?.kind === "reference" && <ReferencePanel />}
{selection?.kind === "query" && (
<QueryPanel domains={DOMAINS} onOpenFile={openFile} />
@@ -284,41 +278,3 @@ export default function KnowledgeWorkspace() {
</div>
);
}
-
-function EmptyState() {
- return (
- <div className="max-w-xl">
- <h1 className="text-lg font-semibold text-fg mb-2">Knowledge base</h1>
- <p className="text-sm text-fg-muted">
- Select a file in the tree to view or edit it. The Built-in tree holds the
- Executive&apos;s default playbooks (positive guidance) and failure case studies
- (negative learnings) — both are retrieved at chat time.
- </p>
- <ul className="text-sm text-fg-muted mt-4 space-y-1.5 list-disc list-inside">
- <li>
- <span className="text-fg">Playbooks</span> — domain frameworks and
- how-tos used as positive examples.
- </li>
- <li>
- <span className="text-rose-300">Failures</span> — case studies of what went
- wrong, surfaced when the question matches one strongly.
- </li>
- <li>
- <span className="text-fg">Company</span> — your uploaded documents.
- </li>
- <li>
- <span className="text-fg">Reference Library</span> — open-licensed
- textbooks and handbooks.
- </li>
- <li>
- <span className="text-fg">Review queue</span> — approve, reject, or
- correct knowledge before the Executive relies on it.
- </li>
- <li>
- <span className="text-indigo-300">Query mode</span> — see exactly what the
- Executive would retrieve for a question.
- </li>
- </ul>
- </div>
- );
-}
diff --git a/packages/ui/src/components/knowledge/SourceTree.tsx b/packages/ui/src/components/knowledge/SourceTree.tsx
index 24952fee..837664ef 100644
--- a/packages/ui/src/components/knowledge/SourceTree.tsx
+++ b/packages/ui/src/components/knowledge/SourceTree.tsx
@@ -1,6 +1,6 @@
"use client";
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
import type { BuiltinFileMeta } from "@/lib/api";
import Icon, { type IconName } from "@/components/Icon";
@@ -21,20 +21,31 @@ interface SourceTreeProps {
failureFiles: BuiltinFileMeta[];
selection: Selection;
filter: string;
+ onFilterChange: (value: string) => void;
/** Pending + needs-revision items, shown on the Review queue entry. */
reviewCount: number;
+ /** Listed company documents; null until the panel has loaded them. */
+ companyCount: number | null;
onSelect: (sel: Selection) => void;
}
+/** Views that live under "Advanced"; landing on one opens the group. */
+const ADVANCED_KINDS = new Set(["file", "new", "reference", "query", "review"]);
+
export default function SourceTree({
domains,
builtinFiles,
failureFiles,
selection,
filter,
+ onFilterChange,
reviewCount,
+ companyCount,
onSelect,
}: SourceTreeProps) {
+ const [advancedOpen, setAdvancedOpen] = useState(
+ () => selection !== null && ADVANCED_KINDS.has(selection.kind)
+ );
const [collapsedBuiltin, setCollapsedBuiltin] = useState(true);
const [collapsedDomains, setCollapsedDomains] = useState<Set<string>>(new Set());
@@ -63,105 +74,146 @@ export default function SourceTree({
);
}
- return (
- <nav className="text-sm space-y-3">
- <RootButton
- active={selection?.kind === "review"}
- onClick={() => onSelect({ kind: "review" })}
- icon="check-circle"
- badge={reviewCount}
- >
- Review queue
- </RootButton>
- <Section
- label="Built-in"
- icon="grid"
- collapsed={collapsedBuiltin}
- onToggle={() => setCollapsedBuiltin((v) => !v)}
- >
- {domains.map((domain) => {
- const playbooks = (builtinByDomain[domain] ?? []).filter((f) =>
- matches(f.filename)
- );
- const failures = (failuresByDomain[domain] ?? []).filter((f) =>
- matches(f.filename)
- );
- if (normalizedFilter && playbooks.length === 0 && failures.length === 0) {
- return null;
- }
- const isCollapsed = collapsedDomains.has(domain) && !normalizedFilter;
- return (
- <div key={domain}>
- <button
- onClick={() => toggleDomain(domain)}
- className="w-full flex items-center gap-1.5 px-1 text-[11px] font-semibold text-fg-muted uppercase tracking-widest hover:text-fg transition-colors"
- >
- <span className="text-fg-subtle w-3 inline-block">
- {isCollapsed ? "▸" : "▾"}
- </span>
- {domain}
- </button>
- {!isCollapsed && (
- <div className="ml-3 mt-1 space-y-2">
- <FileGroup
- label="Playbooks"
- files={playbooks}
- accent="indigo"
- onClickFile={(f) =>
- onSelect({
- kind: "file",
- fileKind: "builtin",
- domain,
- filename: f.filename,
- })
- }
- onAdd={() => onSelect({ kind: "new", fileKind: "builtin" })}
- isActive={(f) => isActiveFile("builtin", domain, f.filename)}
- />
- <FileGroup
- label="Failures"
- files={failures}
- accent="rose"
- onClickFile={(f) =>
- onSelect({
- kind: "file",
- fileKind: "failures",
- domain,
- filename: f.filename,
- })
- }
- onAdd={() => onSelect({ kind: "new", fileKind: "failures" })}
- isActive={(f) => isActiveFile("failures", domain, f.filename)}
- />
- </div>
- )}
- </div>
- );
- })}
- </Section>
+ // Follow navigation into an advanced view (e.g. `?view=review`).
+ const selectedKind = selection?.kind;
+ useEffect(() => {
+ if (selectedKind && ADVANCED_KINDS.has(selectedKind)) setAdvancedOpen(true);
+ }, [selectedKind]);
- <RootButton
- active={selection?.kind === "company"}
+ return (
+ <nav className="text-sm space-y-4">
+ <button
onClick={() => onSelect({ kind: "company" })}
- icon="building"
- >
- Company
- </RootButton>
- <RootButton
- active={selection?.kind === "reference"}
- onClick={() => onSelect({ kind: "reference" })}
- icon="book"
- >
- Reference Library
- </RootButton>
- <RootButton
- active={selection?.kind === "query"}
- onClick={() => onSelect({ kind: "query" })}
- accent="indigo"
- icon="doc-search"
+ className={`w-full flex items-center gap-2 text-left px-2.5 py-2 rounded-lg text-sm font-semibold transition-colors ${
+ selection?.kind === "company"
+ ? "bg-surface-input text-fg"
+ : "text-fg hover:bg-surface-overlay"
+ }`}
>
- Query mode
- </RootButton>
+ <Icon name="building" size="w-4 h-4" />
+ Company documents
+ {companyCount !== null && (
+ <span className="ml-auto text-xs font-normal text-fg-muted">{companyCount}</span>
+ )}
+ </button>
+
+ <div className="border-t border-line pt-3">
+ <button
+ onClick={() => setAdvancedOpen((v) => !v)}
+ className="w-full flex items-center gap-1.5 px-1 text-[11px] font-semibold text-fg-muted uppercase tracking-widest hover:text-fg transition-colors"
+ >
+ <span className="text-fg-subtle w-3 inline-block">{advancedOpen ? "▾" : "▸"}</span>
+ Advanced
+ {!advancedOpen && reviewCount > 0 && (
+ <span className="ml-auto text-[10px] font-semibold normal-case tracking-normal px-1.5 rounded-full bg-amber-950/60 text-amber-400 border border-amber-900/60">
+ {reviewCount} to review
+ </span>
+ )}
+ </button>
+ {!advancedOpen ? (
+ <p className="px-1 mt-1.5 text-[11px] text-fg-subtle leading-snug">
+ Built-in playbooks, reference library, retrieval testing and review.
+ </p>
+ ) : (
+ <div className="mt-3 space-y-3">
+ <RootButton
+ active={selection?.kind === "review"}
+ onClick={() => onSelect({ kind: "review" })}
+ icon="check-circle"
+ badge={reviewCount}
+ >
+ Review queue
+ </RootButton>
+ <Section
+ label="Built-in playbooks"
+ icon="grid"
+ collapsed={collapsedBuiltin}
+ onToggle={() => setCollapsedBuiltin((v) => !v)}
+ >
+ <input
+ value={filter}
+ onChange={(e) => onFilterChange(e.target.value)}
+ placeholder="Filter files…"
+ className="w-full rounded-lg border border-line bg-surface-elevated px-2.5 py-1.5 text-xs text-fg placeholder-fg-subtle focus:outline-none focus:ring-2 focus:ring-indigo-500/40"
+ />
+ {domains.map((domain) => {
+ const playbooks = (builtinByDomain[domain] ?? []).filter((f) =>
+ matches(f.filename)
+ );
+ const failures = (failuresByDomain[domain] ?? []).filter((f) =>
+ matches(f.filename)
+ );
+ if (normalizedFilter && playbooks.length === 0 && failures.length === 0) {
+ return null;
+ }
+ const isCollapsed = collapsedDomains.has(domain) && !normalizedFilter;
+ return (
+ <div key={domain}>
+ <button
+ onClick={() => toggleDomain(domain)}
+ className="w-full flex items-center gap-1.5 px-1 text-[11px] font-semibold text-fg-muted uppercase tracking-widest hover:text-fg transition-colors"
+ >
+ <span className="text-fg-subtle w-3 inline-block">
+ {isCollapsed ? "▸" : "▾"}
+ </span>
+ {domain}
+ </button>
+ {!isCollapsed && (
+ <div className="ml-3 mt-1 space-y-2">
+ <FileGroup
+ label="Playbooks"
+ files={playbooks}
+ accent="indigo"
+ onClickFile={(f) =>
+ onSelect({
+ kind: "file",
+ fileKind: "builtin",
+ domain,
+ filename: f.filename,
+ })
+ }
+ onAdd={() => onSelect({ kind: "new", fileKind: "builtin" })}
+ isActive={(f) => isActiveFile("builtin", domain, f.filename)}
+ />
+ <FileGroup
+ label="Failures"
+ files={failures}
+ accent="rose"
+ onClickFile={(f) =>
+ onSelect({
+ kind: "file",
+ fileKind: "failures",
+ domain,
+ filename: f.filename,
+ })
+ }
+ onAdd={() => onSelect({ kind: "new", fileKind: "failures" })}
+ isActive={(f) => isActiveFile("failures", domain, f.filename)}
+ />
+ </div>
+ )}
+ </div>
+ );
+ })}
+ </Section>
+ <RootButton
+ active={selection?.kind === "reference"}
+ onClick={() => onSelect({ kind: "reference" })}
+ icon="book"
+ >
+ Reference Library
+ </RootButton>
+ <RootButton
+ active={selection?.kind === "query"}
+ onClick={() => onSelect({ kind: "query" })}
+ accent="indigo"
+ icon="doc-search"
+ >
+ Query mode
+ </RootButton>
+ </div>
+ )}
+ </div>
</nav>
);
}
diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.ts
index 5bebd965..109f4041 100644
--- a/packages/ui/src/lib/api.ts
+++ b/packages/ui/src/lib/api.ts
@@ -462,7 +462,16 @@ export async function uploadDocument(
method: "POST",
body: formData,
});
- if (!res.ok) throw new Error("Failed to upload document");
+ if (!res.ok) {
+ let detail = "";
+ try {
+ const data = await res.json();
+ if (typeof data?.detail === "string") detail = data.detail;
+ } catch {
+ // not JSON
+ }
+ throw new Error(detail || `Failed to upload ${file.name}`);
+ }
return res.json();
}
@@ -470,6 +479,9 @@ export interface CompanyDoc {
filename: string;
size_bytes: number;
modified_at: number;
+ source?: "upload";
+ /** The domain the upload was indexed under ("general" when untagged). */
+ domain?: string | null;
}
export async function listDocuments(): Promise<CompanyDoc[]> {
@@ -497,6 +509,79 @@ export async function getDocument(filename: string): Promise<CompanyDocContent>
return res.json();
}
+// --- Connected sources (Google Drive, Notion) --------------------------------
+
+export type SyncedSourceId = "drive" | "notion";
+
+export interface SyncedDoc {
+ id: string;
+ name: string;
+ url: string | null;
+ modified_at: string | null;
+ synced_at: string | null;
+ indexed: boolean;
+}
+
+export interface SyncedDocList {
+ enabled: boolean;
+ last_run: string | null;
+ last_error: string | null;
+ files: SyncedDoc[];
+}
+
+export interface SyncedDocContent {
+ id: string;
+ name: string;
+ url: string | null;
+ content: string;
+}
+
+export interface SyncSourceStatus {
+ id: SyncedSourceId;
+ label: string;
+ enabled: boolean;
+ syncing: boolean;
+ last_run: string | null;
+ last_error: string | null;
+ interval_minutes: number;
+ file_count: number;
+}
+
+export async function listSyncSources(): Promise<SyncSourceStatus[]> {
+ const res = await fetch(`${API_BASE}/documents/sources`);
+ if (!res.ok) throw new Error("Failed to load connected sources");
+ const data = await res.json();
+ return data.sources;
+}
+
+export async function listSyncedDocuments(source: SyncedSourceId): Promise<SyncedDocList> {
+ const res = await fetch(`${API_BASE}/documents/${source}`);
+ if (!res.ok) throw new Error("Failed to list synced documents");
+ return res.json();
+}
+
+export async function getSyncedDocument(
+ source: SyncedSourceId,
+ id: string
+): Promise<SyncedDocContent> {
+ const res = await fetch(`${API_BASE}/documents/${source}/${encodeURIComponent(id)}`);
+ if (!res.ok) throw new Error("Failed to fetch document content");
+ return res.json();
+}
+
+/** Start one sync now. Resolves to an error message the page can show, or null. */
+export async function syncSourceNow(source: SyncedSourceId): Promise<string | null> {
+ const res = await fetch(`${API_BASE}/documents/sources/${source}/sync`, { method: "POST" });
+ if (res.ok) return null;
+ try {
+ const data = await res.json();
+ if (typeof data?.detail === "string") return data.detail;
+ } catch {
+ // fall through
+ }
+ return "Could not start a sync";
+}
+
export interface BuiltinFileMeta {
domain: string;
filename: string;
diff --git a/packages/ui/src/lib/companyDocs.ts b/packages/ui/src/lib/companyDocs.ts
new file mode 100644
index 00000000..02c476d9
--- /dev/null
+++ b/packages/ui/src/lib/companyDocs.ts
@@ -0,0 +1,117 @@
+/**
+ * The knowledge page's single list of company documents: files uploaded in
+ * the app plus files the Google Drive and Notion syncs pulled in. Pure, so
+ * the merge, ordering and labels are unit-tested (scripts/companyDocs.test.mjs).
+ */
+
+export type DocSource = "upload" | "drive" | "notion";
+
+export interface UploadedDocIn {
+ filename: string;
+ size_bytes: number;
+ /** Unix seconds (file mtime). */
+ modified_at: number;
+ domain?: string | null;
+}
+
+export interface SyncedDocIn {
+ id: string;
+ name: string;
+ url: string | null;
+ /** When it last changed in Drive / Notion (ISO), if known. */
+ modified_at: string | null;
+ /** When the knowledge base last re-read it (ISO). */
+ synced_at: string | null;
+ /** False when the file had no readable text, so nothing was indexed. */
+ indexed: boolean;
+}
+
+export interface DocRow {
+ key: string;
+ source: DocSource;
+ /** Upload: the filename. Drive / Notion: the file or page id. */
+ ref: string;
+ name: string;
+ url: string | null;
+ sizeBytes: number | null;
+ /** Upload: when it was added. Drive / Notion: when it was last synced. */
+ addedAt: string | null;
+ editedAt: string | null;
+ domain: string | null;
+ indexed: boolean;
+}
+
+export const SOURCE_LABELS: Record<DocSource, string> = {
+ upload: "Uploaded",
+ drive: "Google Drive",
+ notion: "Notion",
+};
+
+/** "general" is what an untagged upload gets, so it is not worth a tag. */
+function shownDomain(domain: string | null | undefined): string | null {
+ return domain && domain !== "general" ? domain : null;
+}
+
+export function mergeDocs(
+ uploads: UploadedDocIn[],
+ drive: SyncedDocIn[],
+ notion: SyncedDocIn[],
+): DocRow[] {
+ const rows: DocRow[] = [
+ ...uploads.map((d) => ({
+ key: `upload:${d.filename}`,
+ source: "upload" as const,
+ ref: d.filename,
+ name: d.filename,
+ url: null,
+ sizeBytes: d.size_bytes,
+ addedAt: new Date(d.modified_at * 1000).toISOString(),
+ editedAt: null,
+ domain: shownDomain(d.domain),
+ indexed: true,
+ })),
+ ...[
+ ["drive", drive] as const,
+ ["notion", notion] as const,
+ ].flatMap(([source, files]) =>
+ files.map((f) => ({
+ key: `${source}:${f.id}`,
+ source,
+ ref: f.id,
+ name: f.name,
+ url: f.url,
+ sizeBytes: null,
+ addedAt: f.synced_at,
+ editedAt: f.modified_at,
+ domain: null,
+ indexed: f.indexed,
+ })),
+ ),
+ ];
+ // Most recently added or edited first; ties (and rows with no date) by name.
+ const when = (r: DocRow) =>
+ Math.max(Date.parse(r.editedAt ?? "") || 0, Date.parse(r.addedAt ?? "") || 0);
+ return rows.sort((a, b) => when(b) - when(a) || a.name.localeCompare(b.name));
+}
+
+export function filterDocs(rows: DocRow[], source: DocSource | "all", query: string): DocRow[] {
+ const q = query.trim().toLowerCase();
+ return rows.filter(
+ (r) => (source === "all" || r.source === source) && (!q || r.name.toLowerCase().includes(q)),
+ );
+}
+
+export function formatSize(bytes: number): string {
+ if (bytes < 1024) return `${bytes} B`;
+ if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+ return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** "every 60 min" / "every 2 h" — how often a connected source re-syncs. */
+export function formatInterval(minutes: number): string {
+ if (minutes % 60 === 0 && minutes >= 60) {
+ const h = minutes / 60;
+ return h === 1 ? "every hour" : `every ${h} hours`;
+ }
+ return `every ${minutes} min`;
+}