Skip to content

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

feat(briefing): open and reply to Right now's email points from Home (#651)

Rufusddc4429112ac
diff --git a/packages/core/openexecutive/api/routes/delegation.py b/packages/core/openexecutive/api/routes/delegation.py
index a972c989..def66e1e 100644
--- a/packages/core/openexecutive/api/routes/delegation.py
+++ b/packages/core/openexecutive/api/routes/delegation.py
@@ -1031,6 +1031,134 @@ def get_delegation_replies(request: Request) -> RepliesOut:
])
+class MailAttachmentOut(BaseModel):
+ name: str
+ mime_type: str = ""
+ size: int = 0
+
+
+class MailViewOut(BaseModel):
+ """One email in the caller's own mailbox, as Home opens it from a Right
+ now point: who wrote, to whom, what they wrote (without the quoted
+ conversation below), its files, what the caller last wrote in the
+ conversation, a link to it in their mailbox, and the reply card open on
+ the conversation, if any."""
+
+ thread_id: str
+ message_id: str
+ subject: str = ""
+ from_name: str = ""
+ from_email: str = ""
+ to: list[str] = Field(default_factory=list)
+ cc: list[str] = Field(default_factory=list)
+ received_at: str = ""
+ text: str = ""
+ attachments: list[MailAttachmentOut] = Field(default_factory=list)
+ has_attachments: bool = False
+ their_last_words: str = ""
+ link: str = ""
+ reply_card_id: int | None = None
+
+
+class MailReplyIn(BaseModel):
+ model_config = ConfigDict(extra="forbid")
+
+ thread_id: str = Field(min_length=1, max_length=512)
+ message_id: str = Field(min_length=1, max_length=512)
+
+
+class MailReplyOut(BaseModel):
+ decision_id: int
+
+
+# The most of an email's own words Home shows.
+_MAIL_VIEW_MAX_CHARS = 8000
+_MAIL_EARLIER_MAX_CHARS = 400
+
+
+async def _connected_mailbox(person: Person) -> Any:
+ status = await gmail_status(person.email)
+ if status != "connected":
+ raise _refuse(409, _BLOCKING_CODES.get(status, "gmail_error"), STATUS_MESSAGES[status])
+ return gmail_for(person.email or "")
+
+
[email protected]("/delegation/mail", response_model=MailViewOut)
+async def get_delegation_mail(request: Request, thread_id: str, message_id: str) -> MailViewOut:
+ """One email in the caller's own mailbox (Home's View email). Their own
+ mailbox only: the client is theirs, so another person's ids find
+ nothing. Reads; changes nothing."""
+ from openexecutive.delegation.gmail import GmailNotFound, mailbox_link
+ from openexecutive.delegation.inbox import card_payload, open_cards
+ from openexecutive.delegation.inbox_classifier import their_last_words
+ from openexecutive.integrations.email_poller import sender_new_text
+
+ person = _caller(request)
+ person_id = _person_id(person)
+ if not (0 < len(thread_id) <= 512 and 0 < len(message_id) <= 512):
+ raise _refuse(422, "bad_id", "That isn't an email.")
+ client = await _connected_mailbox(person)
+ try:
+ thread = await client.get_thread(thread_id)
+ own = {(person.email or "").strip().lower(), *(a.strip().lower() for a in await client.send_as_addresses())}
+ except GmailNotFound as exc:
+ raise _refuse(404, "not_found", "That email isn't in your mailbox any more.") from exc
+ except GmailAuthError as exc:
+ raise _refuse(409, "gmail_needs_reconnect", STATUS_MESSAGES["needs_reconnect"]) from exc
+ except GmailError as exc:
+ logger.warning("delegation: reading an email failed", exc_info=True)
+ raise _refuse(502, "gmail_error", STATUS_MESSAGES["error"]) from exc
+ message = next((m for m in thread.messages if m.id == message_id), None)
+ if message is None:
+ raise _refuse(404, "not_found", "That email isn't in your mailbox any more.")
+ card = next(
+ (c for c in open_cards(person_id) if card_payload(c).get("thread_id") == thread.id), None
+ )
+ return MailViewOut(
+ thread_id=thread.id,
+ message_id=message.id,
+ subject=message.subject,
+ from_name=message.from_name,
+ from_email=message.from_addr,
+ to=list(message.to),
+ cc=list(message.cc),
+ received_at=message.received_at,
+ text=sender_new_text(message.text or "")[:_MAIL_VIEW_MAX_CHARS].strip(),
+ attachments=[
+ MailAttachmentOut(name=a.name, mime_type=a.mime_type, size=a.size) for a in message.attachments
+ ],
+ has_attachments=bool(message.attachments) or message.has_attachments,
+ their_last_words=their_last_words(thread, message, own)[:_MAIL_EARLIER_MAX_CHARS],
+ link=mailbox_link(person.email or "", thread_id=thread.id, message_id=message.id),
+ reply_card_id=int(card.id) if card is not None else None,
+ )
+
+
[email protected]("/delegation/mail/reply", response_model=MailReplyOut)
+async def reply_to_delegation_mail(request: Request, body: MailReplyIn) -> MailReplyOut:
+ """Write a reply to one email in the caller's own inbox, because they
+ asked (Home's Reply), and put it on a reply card for them
+ (``delegation.inbox.draft_on_request``). The open card already on that
+ conversation when there is one. Sends nothing: the card's Send does."""
+ from openexecutive.delegation.inbox import ASK_REFUSALS, draft_on_request
+
+ person = _caller(request)
+ person_id = _person_id(person)
+ if not is_enabled(person_id):
+ raise _refuse(409, "act_as_me_off", "Turn Act as me on first.")
+ client = await _connected_mailbox(person)
+ try:
+ got = await draft_on_request(person, body.thread_id, body.message_id, gmail=client)
+ except GmailAuthError as exc:
+ raise _refuse(409, "gmail_needs_reconnect", STATUS_MESSAGES["needs_reconnect"]) from exc
+ except GmailError as exc:
+ logger.warning("delegation: writing a reply on request failed", exc_info=True)
+ raise _refuse(502, "gmail_error", STATUS_MESSAGES["error"]) from exc
+ if isinstance(got, str):
+ raise _refuse(409, got, ASK_REFUSALS.get(got, ASK_REFUSALS["not_now"]))
+ return MailReplyOut(decision_id=got)
+
+
@router.put("/delegation/replies/{decision_id}/text", response_model=ReplyCardOut)
async def update_delegation_reply_text(request: Request, decision_id: int, body: ReplyTextUpdate) -> ReplyCardOut:
"""Change the words of one of the caller's reply cards before Send: on
diff --git a/packages/core/openexecutive/api/routes/today.py b/packages/core/openexecutive/api/routes/today.py
index ecf39eb6..553bfe62 100644
--- a/packages/core/openexecutive/api/routes/today.py
+++ b/packages/core/openexecutive/api/routes/today.py
@@ -28,7 +28,7 @@ import asyncio
import json
import logging
from datetime import UTC, datetime, timedelta, tzinfo
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
from fastapi import APIRouter, BackgroundTasks, HTTPException, Query, Request, Response
from pydantic import BaseModel, Field
@@ -503,12 +503,35 @@ class HeldBackItem(BaseModel):
lines: list[str]
+class PointSource(BaseModel):
+ """What a Right now point is about, when Home can open it: an email in
+ the reader's own inbox (``kind`` "mail": its ids, and its reply card
+ when one is open) or a card in Needs you (``kind`` "alert")."""
+
+ kind: Literal["mail", "alert"]
+ message_id: str | None = None
+ thread_id: str | None = None
+ decision_id: int | None = None
+ alert_id: int | None = None
+
+
class NarrativePoint(BaseModel):
- """One point of Right now (the /today header): its Markdown, and when it
- first appeared today (ISO-8601 UTC)."""
+ """One point of Right now (the /today header): its Markdown, when it
+ first appeared today (ISO-8601 UTC), and what it is about."""
text: str
since: str | None = None
+ source: PointSource | None = None
+
+
+def _point_source(raw: dict[str, Any] | None) -> PointSource | None:
+ """A stored point source as the API shows it; None when unreadable."""
+ if not raw:
+ return None
+ try:
+ return PointSource.model_validate(raw)
+ except ValueError:
+ return None
class MorningBriefItem(BaseModel):
@@ -1794,11 +1817,14 @@ def _narrative_context(
mode: str = "team",
scope: str | None = None,
reader: Reader | None | object = _LOOKUP,
+ sources_out: dict[str, dict[str, Any]] | None = None,
) -> tuple[str, list[dict[str, Any]] | None]:
"""``(context, activity)`` — the exact user turn the model would receive.
``reader`` is who the header is written for (``_narrative_reader``); the
regeneration resolves it once and hands the same one to the post-check.
+ ``sources_out``, when given, is filled with Right now's tag → item map
+ (``HeaderContext.sources``), so a point can be opened from Home.
The single source both the cache key and the model call come from, so the
key can never be computed over something the model did not see.
@@ -1819,7 +1845,7 @@ def _narrative_context(
today_data = _with_due_soon(today_data, mode, viewer_desc, scope)
resolved = _narrative_reader(scope, viewer) if reader is _LOOKUP else reader
if viewer_desc is None:
- return _header_context(today_data, viewer, mode, scope, resolved) # type: ignore[arg-type]
+ return _header_context(today_data, viewer, mode, scope, resolved, sources_out) # type: ignore[arg-type]
if _nothing_needs_attention(today_data, mode):
return narrative_cache.QUIET_CONTEXT, None
activity = _narrative_activity(viewer, viewer_desc)
@@ -1840,6 +1866,7 @@ def _header_context(
mode: str,
scope: str | None,
reader: Reader | None,
+ sources_out: dict[str, dict[str, Any]] | None = None,
) -> tuple[str, list[dict[str, Any]] | None]:
"""Right now's context for a whole-company scope
(``briefing.header_context``). With nothing moved today it is one of the
@@ -1903,6 +1930,8 @@ def _header_context(
ctx = render(activity)
if not ctx.moved:
return narrative_cache.NOTHING_MOVED_CONTEXT, None
+ if sources_out is not None:
+ sources_out.update(ctx.sources)
return ctx.text, activity
@@ -2043,11 +2072,17 @@ def _attach_right_now(response: TodayResponse, scope: str, text: str, written_at
from openexecutive.briefing import narrative_cache, right_now
parts = right_now.split_narrative(text)
- times = right_now.point_times(scope, narrative_cache.local_today())
+ day = narrative_cache.local_today()
+ times = right_now.point_times(scope, day)
+ sources = right_now.point_sources(scope, day)
response.narrative_lead = parts.lead
response.narrative_move = parts.move
response.narrative_points = [
- NarrativePoint(text=p, since=times.get(right_now.point_key(p), written_at))
+ NarrativePoint(
+ text=p,
+ since=times.get(right_now.point_key(p), written_at),
+ source=_point_source(sources.get(right_now.point_key(p))),
+ )
for p in parts.points
]
# Only a rostered reader's own scope has a last look (see /today/seen).
@@ -2141,6 +2176,9 @@ async def _regen_briefing_narrative_locked(
started = time.monotonic()
# The new points that need the principal, by key (right_now_ping).
important: set[str] = set()
+ # Tag → item for the lines Home can open, and point key → item.
+ sources: dict[str, dict[str, Any]] = {}
+ pointed: dict[str, dict[str, Any]] = {}
try:
mode = get_workspace().mode
snapshot = _build_today(include_private=expected_scope == narrative_cache.DEFAULT_SCOPE)
@@ -2155,7 +2193,7 @@ async def _regen_briefing_narrative_locked(
return True
reader = _narrative_reader(scope, viewer)
context, activity = _narrative_context(
- today_data, viewer, viewer_desc, mode, scope, reader=reader,
+ today_data, viewer, viewer_desc, mode, scope, reader=reader, sources_out=sources,
)
input_hash = narrative_cache.build_narrative_input_hash(context, scope=scope, mode=mode)
cached = narrative_cache.get(scope)
@@ -2184,6 +2222,10 @@ async def _regen_briefing_narrative_locked(
timeout=25.0 + REWRITE_TIMEOUT_S,
)
if viewer_desc is None and text:
+ from openexecutive.briefing.header_context import point_sources
+ from openexecutive.briefing.right_now import point_key as key_of
+
+ pointed = {key_of(p): src for p, src in point_sources(text, sources)}
if scope == narrative_cache.DEFAULT_SCOPE:
from openexecutive.briefing.header_context import (
needs_you_tags,
@@ -2214,6 +2256,7 @@ async def _regen_briefing_narrative_locked(
from openexecutive.briefing import right_now
recorded = right_now.record_points(scope, text, written_at)
+ right_now.record_sources(scope, written_at, pointed)
if scope == narrative_cache.DEFAULT_SCOPE and recorded.new:
from openexecutive.briefing.right_now_ping import maybe_ping
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index 6dfa0c11..2f518523 100644
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@ -5132,6 +5132,7 @@ today:
- "Live header (briefing.live_signals) — the whole-company narrative scopes (`principal`, `company`) open their context with the principal's world as it is happening, under a NOW line bucketed to the local hour: INBOUND (integration_inbound audit rows whose summary starts 'Inbound ', one row per message id, grouped by sender + subject with a count; an email carries its subject and first line, the principal's own mail reads 'from the principal', an email from the roster says 'the Executive replied' or 'no reply went out' (an open integrations.unanswered_mail card for its thread; principal scope only, the cards are private), and a time on another local day carries its weekday and date — a brief that read yesterday's 'Re: call tomorrow' subject at a bare time put a past meeting under Today, called its reader by name and counted one email handled twice as two asks), STUCK (integration_outbound_blocked rows to a recipient, the inbound 'Accepted non-roster … reply blocked' and Google Chat 'left unanswered' / 'reply not delivered' rows, and chat drafts still waiting: delegation_drafts rows of source chat with no sent_message_id or gone_at; before each scheduled header refresh, each morning brief and the principal's /today view (at most every 2 minutes, today._maybe_settle_on_view, so it holds with the background refresh slowed or off), live_signals.settle_principal_drafts asks the principal's mailbox for each open chat draft from the last two days and sets gone_at on the ones sent or deleted there, or sent another way (one read of their latest 15 sent messages while a draft is left: same subject, one of the same recipients, sent after the draft — a redraft whose other version went out); one draft's failure no longer stops the pass — the count used to be every delegation_drafted row of the day, so a draft the principal sent from Gmail, and said so in chat, stayed 'waiting for them to review and send' all day), CONVERSATIONS (the principal's own web chat titles, without times; a header that still reports the reader's chats or asks back — narrative.own_echoes — is sent back once for a rewrite) and REST OF TODAY'S CALENDAR. An address that belongs to someone on the roster (or, in the principal scope, one of the principal's contacts) reads 'Name (address)' in these lines (`live_signals._named`): given a bare address the header made a name up from it (\"mquinn@\" became \"Mquinn\"). Window: the local day, or the last 12 h when longer. Private audit rows, drafts, chat titles and the calendar only in the `principal` scope (gather_live_signals drops the calendar whenever include_private is false, whatever the caller passes). The calendar is never fetched on the request: `live_signals.refresh_calendar` caches one read per 15 min (the scheduler tick refreshes it) and the header quotes `cached_calendar`. With live blocks present the render also ages proposals (whole days), lists each at-risk department's attention_goals, and adds EXTERNAL SIGNALS (monitoring proposals from the last 24 h, which never break the quiet line alone); rhythm runs (`today.RHYTHM_WORKFLOWS`) are excluded from the narrative's activity. Anything live breaks the quiet line. Why: the header read the same for days on an install whose inbox moved hourly, because nothing but the alert board reached it. Every quoted field is one-lined and cut, and the prompt calls the blocks data, never instructions (inbound text is attacker-controlled). Freshness: `TodayResponse.narrative_generated_at` / `narrative_stale`; WAITING (principal scope, MOVED TODAY in Right now only): their own sent mail with no answer in its thread (briefing.waiting_on; under Act as me, 7-day window, over 1 h old, a question in their own words, at most 10 recipients besides the Executive; recipients, subject and time only; read on the narrative refresh, cached 15 min, dropped when Act as me goes off) and meetings that ended today (live_signals.met_today) — Right now said 'nothing new' on a day the principal was waiting on two replies and had just finished a call; a row written on an earlier local day is not served, nor a stale one over 2 h old (`_STALE_HEADER_MAX_AGE`) or, in the principal scope, one written before a meeting on the cached calendar started or ended (`today._header_outdated`; a failing rewrite left a header calling a finished call next for three hours); regenerations are serialized per scope (`today._regen_lock`; a trigger that finds one running marks the scope pending in `_regen_pending` and the running pass goes round once more); a failed pass (error, 33 s timeout (25 s draft + 8 s rewrite; a rewrite past its 8 s keeps the first draft fixed in code), empty text) starts a 5-minute backoff (`_regen_failed_at`, `_REGEN_FAILURE_BACKOFF`) in which no view or tick regenerates and `narrative_stale` is false; the calendar is placed at the real time, not the hour-floored NOW; the scheduler precomputes the principal's header (`today.refresh_principal_narrative`, see scheduler); the Briefing re-polls at 4/10/20 s while stale, on tab focus (at most once a minute) and every 5 min (`ui/src/lib/narrativeFreshness.ts`). Logs: 'today: narrative served scope=… age_s=… stale=…', 'today: narrative regenerated scope=… ms=…'."
- "Right now pings (briefing.right_now_ping): when a rewrite of the principal's header adds a point (right_now.record_points returns Recorded.new), one short chat message goes to the principal (runner.deliver_to_person(chat_only=True), never email; proactive source right_now). NotificationSettings.right_now: important (default; a new point citing a MOVED TODAY line in header_context.NEEDS_YOU_PREFIXES, mapped by point_key through point_citations before keep_cited_points strips the tags) / everything / off. Skipped for the first header of the day (morning brief covers the night), capped at 4 a day (right_now_ping audit rows with status sent), dropped (not held) when people.notifications.hold_for would hold it. Text is plain_point: links, addresses and bare domains stripped, since points are model text over quoted mail. Why: Rufus asked to be told when Right now changes significantly instead of only seeing it on Home."
- "Own inbox in Right now (live_signals.own_inbox, principal scope, MOVED TODAY in Right now only): the Act as me watcher (delegation.inbox) writes a private delegation_inbox_mail audit row for each message it records (not the reader's own, the Executive's, pre-switch, stale or already answered mail) and for newer mail from someone else on a thread whose reply card is still open (_note_later, from reconcile; a scan passes those threads over, so before this nothing recorded them): sender, subject, received_at, relation, skip reason, card id, never a body. From people the principal deals with (team, contact, correspondent, or any mail drafted/answered or on a card) one line each with the watcher's outcome (delegation.inbox.outcomes); the rest (strangers, mail not addressed to them) never a point; bulk, list and Gmail-tab mail is not recorded at all, so a busy day of it never crowds real mail out of the rows read: /today returns up to three 'Name: subject' labels + a count (inbox_also / inbox_also_total) for Home's 'Also in' line. Why: Braden's Right now read 'Quiet right now' from 6 am on a day a contact replied asking for a call, because it read only mail to the Executive's own address. narrative_checked_at is the request time when the header's key has not moved, so the card says 'Checked 2:20 PM' instead of the hour a quiet header was written."
+ - "Acting on a Right now point: header_context.HeaderContext.sources maps a MOVED TODAY tag to the item it is about (own-inbox mail from OwnInbox.refs: message_id, thread_id, card id; a card raised or re-raised today: alert_id), never in the text. After a rewrite, point_sources (before keep_cited_points strips tags) gives point_key -> item; right_now.record_sources replaces the scope's rows in briefing_point_source; /today serves NarrativePoint.source. Home: View email (GET /delegation/mail, the caller's own mailbox only, the sender's new words, attachment names, their last words, mailbox link, open reply card on the thread) and Reply (POST /delegation/mail/reply -> inbox.draft_on_request: the thread's open card, else the watcher's _draft_card with asked=True, so never sent on its own under Handle it for me; refusals ASK_REFUSALS). Show me jumps to the alert in Needs you. Why: Rufus (2026-10-27) wanted to act on each point; Andrew's reply delivering the LOIs he asked for read 'Nothing is owed back' because the classifier filed it fyi: render_email now names attachments and the prompt says an email delivering what they asked for is a follow_up that needs a short reply."
- "GET /today/activity?limit=N — Returns ActivityResponse(items). Each item is one recent self-initiated Executive action — a fired scheduled_action (DM dispatched, follow-up fired, cadence run, paused workflow resumed) or an extracted decision/advice row. Items carry `kind` (coarse classifier the UI maps to verb + icon — dm_sent, email_sent, nudge_sent, cadence_sent, workflow_resumed, proposal_routed, decision_logged, advice_given, workflow_done, initiative_started, decision_resolved, alert_raised, or action for unclassified), `summary`, `actor` (always Executive for now), `target` (channel ref / person, or null), `department`, `at` (ISO timestamp), and for workflow_done `detail` (one line on what came of the run) and `artifact_id` (`run:<id>` when it kept a write-up); a run's `summary` is its plain name from workflows/run_outcome.py, never its log title. Sources merged — `scheduled_actions` with status=done (excluding `nudge_scan` heartbeat and `__internal__` channel), `decisions`, `advice_given`, completed `workflow_runs` (status=done — briefings/check-ins/research, bucketed at `updated_at`), `initiatives` (kicked-off projects, at `created_at`), resolved `decision_instances` (terminal gated-decision outcomes — approved/rejected/reversed, at `resolved_at`; pending ones stay in `proposals`, not the rail), and `alerts` raised (excluding source=`decision_scheduling`, which is the companion alert for a gated booking already represented by its `decision_resolved` row). `_build_activity(..., include_alert_raised=False)` omits this source entirely. The rail keeps it (history is the point there); only the briefing narrative opts out. This broadens the feed beyond the original messaging-heavy three sources so it reflects all self-initiated Executive activity, not just dispatched messages. Actions on `propose_only` departments are reclassified to `proposal_routed` because the runner marks them done without dispatching (the proposal is surfaced via /today's `proposals` field; the activity rail shows it as 'proposed to <approver>' rather than implying a DM was sent). Sorted by `at DESC`, then capped at `limit` (default 20, clamped to 1..100 via FastAPI Query validation — 422 on out-of-range). The Pulse page polls this endpoint (limit=100) every ~20s so new activity streams into the 'Recent activity' card without a reload; the card scrolls internally at a fixed max-height rather than growing the page."
- "GET /today/activity/daily?days=N — Returns DailyActivityResponse(days), the per-day counts behind the Pulse page's 'heartbeat' heatmap (the GitHub-contributions-style grid at `/memories`). Same source set and exclusions as /today/activity — the union of `decisions`, `advice_given`, status=done `scheduled_actions` (excluding the `nudge_scan` heartbeat and `__internal__` channel), completed `workflow_runs`, `initiatives`, resolved `decision_instances`, and `alerts` — but bucketed by calendar day (UTC) in `episodic.count_activity_by_day` rather than returned as individual items — decisions/advice by their `timestamp`, fired actions by `run_at` (fire time, not `created_at` queue time, so a cadence queued the night before counts on the day it fires), workflow runs by `updated_at` (completion), initiatives by `created_at`, resolved decisions by `resolved_at`, alerts by `created_at`. The `workflow_runs` and `alerts` tables are owned by other stores (not `episodic.initialize_db`), so each UNION arm is included only when its table exists — `count_activity_by_day` checks `sqlite_master` and still counts the sources episodic owns on a DB initialised by episodic alone. The response is DENSE: every calendar day in the window is present (count 0 when nothing fired), oldest→newest, so the UI renders a gap-free grid without client-side fill. A decision instance whose proposed payload is private (`\"private\": true`) and an alert tagged `private:principal` are not counted, as the feed leaves them out. `days` defaults to 90, clamped to 1..365 via FastAPI Query validation (422 on out-of-range). Read-only, unauthenticated (matches /today/activity and /memories/*), uncached."
- "GET /today/top-three — solo only, principal only. Returns TopThreeToday {items: [{key, kind, text, why, slot}]} or null: null in team mode (effective_workspace_mode) and for anyone the stricter principal-only-run rule (`workflows._caller_is_the_principal`: own email on a non-archived principal entry, or no x-caller-email; never an unclaimed roster) does not admit. Built from the morning brief's own inputs and code — `open_loops.principal_due_soon()` handed to `briefing.top_three.build_top_three` — so the items, order and free slots match the solo brief. `slot` is the free block ('10:00–11:00', the user's zone), '' when no block is left, null when no calendar was read (none connected, a failure or the 4 s timeout, a non-business day). A separate route, never part of GET /today, so the Briefing never waits on the calendar read; the UI loads it after /today."
diff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.json
index a816e291..00df790d 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). A request it lets through is marked `request.state.shared_secret_ok`, which is what lets an MCP request turn on \"may act\" with `x-mcp-client-actions: on` (`mcp_server.may_act`; with no secret the header is ignored and `MCP_CLIENT_ACTIONS` decides). With local login (`OE_LOCAL_LOGIN=1`, which only `make dev` sets, and only while neither Google nor SSO sign-in is 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 and Slack 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 the UI origins in `BACKEND_ALLOWED_ORIGINS`, plus the `make dev` UI on `localhost:3000` only when `OE_PUBLIC_DEPLOYMENT` is unset, so a public instance never answers a localhost page with credentials. 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\n**Who is calling** is read in one place, `api/caller.py`, which answers with a `Caller` kind and email; a test fails on any other read of an `x-caller-*` header. By default (`open`) it is the `x-caller-email` the UI proxy stamps from the sign-in, trusted because whoever holds the shared secret is trusted as the proxy, and a request with none runs as the principal. **Signed callers** remove that trust. With `CALLER_ASSERTION_PUBLIC_KEYS` set, the proxy signs every request with an Ed25519 key only the UI holds, and a third middleware checks the `x-caller-assertion` header:\n\n- **What it covers.** It is good for one method, the exact path and query, at most 120 seconds, and one use. The API keeps used ids in memory.\n- **What it names.** A `user`, by email, or the `operator`: local login, which runs as the principal.\n- **No caller header at all** is a `service`, for scripts or MCP clients holding only the secret. It is never the principal, not even on an install with no owner yet, so it can't save a first setup.\n- **Anything else is a 401.** That includes an `x-caller-email` without an assertion (`caller_assertion_required`), and a bad, expired, reused or mismatched assertion (`caller_assertion_invalid`).\n\nPublic keys that can't be read stop the boot, rather than fall back to trusting the header. `scripts/make-caller-keys.py` makes the pair, and `scripts/mint-caller-assertion.py` signs one request for curl. The API holds only public keys. Setup's API-protection check warns while a shared secret is set without them.\n\n**Host origins.** Another app on a sibling host (`OE_HOST_ORIGINS` on the UI, exact origins) may frame the pages and call a short list of routes from its own pages, as the signed-in person. The list is `packages/ui/src/lib/host-list.json`: who is signed in (`GET /auth/me`, the email the call is made as, so the host can warn when that isn't its own user; never `/auth/allowed-emails`), `/today*`, `/decisions` and one decision, conversations (`GET /sessions*`) and the watch list; `ack`, `snooze`, `reopen`, `bulk-ack` and `review` on alerts; `POST /chat`, `/chat/stop`, `/chat/add`, `/chat/upload`, `/chat/transcribe`; and the watch list's describe, add, edit, delete, approve and decline. No card's approve, reject or cancel, no prepare, Act as me, delegation, settings or People (`tests/unit/test_host_list.py` checks each entry against the app's routes and against that rule). The UI's middleware and proxy enforce it: a request whose `Origin` is a listed host origin, with `Sec-Fetch-Site: same-site`, may make only those calls, with CORS for that exact origin and credentials (its preflight answered before the session check, a missing session a `401` with CORS), and anything else from it is a `403`. The proxy then drops the browser's `Origin`, `Referer` and `Sec-Fetch-*`, so the local-login rule above never sees them, and marks the call's **surface** `host`: an optional `surface` claim in the signed assertion and `x-caller-surface`, which must agree with it (`401` otherwise; without signed callers the header is read like the email). `api.caller.from_host` answers it, and a chat turn on that surface (`Session.from_host`) only reads and advises (see Agents). Every page of the UI also sends a `Content-Security-Policy`: scripts only with that response's nonce (no `unsafe-inline`, no `unsafe-eval` outside the dev server) and `frame-ancestors 'self'` plus the host origins. `make embed-outputs` writes the API's OpenAPI description (`scripts/export-openapi.py`), the host list and the UI's navigation for a host app's own checks.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat`, `POST /chat/stop`, `POST /chat/add`, `POST /chat/background`, `GET /chat/voice`, `POST /chat/transcribe` | SSE stream of a live Executive turn, with a `: keepalive` comment every `CHAT_STREAM_KEEPALIVE_S` while the turn is quiet. `POST /chat/background` starts a new chat that the server answers to the end with nobody connected (a phone approving a card, then closing the app): it answers `202` with the new `session_id` once the same caller, access and quota checks as `/chat` pass, the turn saves itself as a `/chat` turn does, and one caller may have three running at once (`429` beyond that). `POST /chat/add` hands the running turn a message the person typed while it works; the turn takes it at its next step and the stream names it in a `message_added` event, and a second `POST /chat` on the same conversation waits for the first to finish. `GET /chat/voice` says whether the chat mic shows (`available`, `max_seconds`); `POST /chat/transcribe` takes one recording (multipart `file`) and answers `{text}` for the message box, nothing kept: `404` when speech to text isn't set up, `400` for a file that isn't audio, `413` over 25 MB, `502` when the speech server fails. 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`. When the turn held steps for an outside read that still wait on the speaker's go (`outside_content.pending_held`), it then sends one `held_steps` event, `{type, session_id, steps: [plain words]}` (not after a stop or a timeout), which the UI shows as Approve / Not now under the reply; Approve sends \"Go ahead\". `GET /sessions/{id}/messages` puts the same `held_steps` on the last reply while they still wait (never for a shared chat's member). When the content check flagged something the turn read (`outside_content.pending_flags`, `orchestrator.content_scan`), it also sends one `flags` event, `{type, session_id, flags: [plain words]}`, shown as \"Something looked off\" under the reply, and `GET /sessions/{id}/messages` puts the same `flags` on the last reply for an hour (never for a shared chat's member). 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/shared-with-me`, `GET /sessions/topics`, `PATCH\\|DELETE /sessions/topics/{topic_id}`, `POST /sessions/topics/{topic_id}/merge`, `POST /sessions/topic-areas/rename`, `POST /sessions/topic-areas/ungroup`, `GET\\|PATCH /sessions/{id}`, `GET /sessions/{id}/messages`, `DELETE /sessions/{id}`, `POST /sessions/{id}/messages/{message_id}/feedback`, `GET /sessions/{id}/followup`, `GET\\|PUT /sessions/{id}/shares`, `DELETE /sessions/{id}/shares/me`, `GET /sessions/{id}/people`, `GET /sessions/{id}/live`, `POST /sessions/{id}/typing`, `GET /sessions/{id}/export`, `POST /sessions/{id}/rewind` | List, read and delete saved chat sessions (assistant messages carry their row `id` and any `feedback`). The list is scoped to the caller, and each chat carries `preview`: its last message as one plain line, Markdown marks stripped and cut at a word near 120 characters, with `You:` before the person's own words. With `?q=` it is a search: the caller's own chats whose title or message text contains the words (case-insensitive, `LIKE` with wildcards escaped), each with `match_count` (messages that contain them; 0 for a title-only match) and `snippet` (the newest matching message, around the match, prefixed `You:` or `Executive:`). Scoped exactly like the list, so nobody else's conversation can match. The Chats page searches this way and opens a result with `?find=`, so the chat starts on that message and steps through the others. Each of the owner's chats also carries `topic_id`, the topic it is filed under (`memory.chat_topics`). `GET /sessions/topics` lists the caller's topics (`id`, `name`, `chat_count`, `kept`, `pinned_at`, `area`, `updated_at`) and, when some of their chats have no topic yet or some topics no area, starts filing them in the background from their titles and answers `organizing: true` until done. `PATCH /sessions/topics/{topic_id}` renames (a name another of their topics has merges the two) or pins one, `POST …/merge` moves its chats into another (`into_id`), and `DELETE` ungroups it, leaving its chats under no topic; another person's topic is a 404. `POST /sessions/topic-areas/rename` (`area`, `name`) renames one of the caller's areas and `…/ungroup` (`area`) drops it, its topics standing alone; an area they don't have is a 404. `PATCH /sessions/{id}` also takes `topic_id` (null for none) or `topic_name` (made if new) to file the chat, which then is never refiled on its own. A chat-app conversation started with /new is left off the list until its first turn (`memory.conversations`). 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. A teammate's own chat (a web chat, a DM, a private Telegram chat; not a channel or group conversation, `chat._shared_space`) is theirs alone, the principal included, as their mail with the Executive is. 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. The owner (not the principal on someone else's chat; the principal for an ownerless one) also has the chat controls. `PATCH` takes `{title?, pinned?}`: a name they give is kept (`sessions.title_locked`, so the automatic title never replaces it) and a pinned chat lists first, newest pin first, with `pinned_at`. `PUT /sessions/{id}/shares {person_ids}` adds exactly those team members to it (not contacts, the archived or the owner: 422), audited `session_shared`; a chat that read its owner's own mail (`mail_private`) is never shared (409) and stops being open to those it was shared with before, and a chat-app conversation is never shared (409). Those added get it from `GET /sessions/shared-with-me` (with `shared_with_you`, `shared_by`, `shared_at`) and **write in it with the owner**: `POST /chat` with its id runs their turn as themselves (`chat._shared_member` widens the turn's access, never its ownership), and they may read it, its messages (without the owner's ratings) and its export. They can't rate, rename, delete, share or redo it, and `DELETE /sessions/{id}/shares/me` takes them out of it (audited `session_shared`, with them under `removed`). In a chat several people are in, messages carry `sender_person_id` and `sender_name` (a message from before it was shared is the owner's), `GET /sessions/{id}/people` returns `{you, people: [{person_id, full_name, owner}]}` (owner first; empty for a chat of one), and redo is refused (409) when the last message is someone else's. `GET /sessions/{id}/live` is a server-sent event stream each open page holds (`api.chat_live`, one in-process broker): `ready` first (with the running turn so far, if any), then `turn_started` (who sent what), the reply's `chunk` / `thinking` / `activity` / `action_taken` / `phase`, `turn_ended` (the page reads the chat again), `typing` (from `POST /sessions/{id}/typing`, at most once per 2 s per person) and `people`. `removed`, `deleted` and `resync` (a page that fell 1024 events behind) end it; the access check runs again on every 20 s keepalive. At most 12 pages per person, 40 per chat and 2000 per process (429). Archiving someone takes them out of every chat shared with them, and their open streams close at the next keepalive. The page closes it while its tab is hidden. `GET /sessions/{id}/export` returns the chat as a Markdown file (`memory.chat_export`: each message under its writer's People name or `Executive`, the reply's sources listed under it). `POST /sessions/{id}/rewind {last_message_id}` takes back the last turn for Try again and Edit: under the conversation's turn lock it deletes the last reply and the messages it answered, but only while that reply is still the chat's last row, and returns those messages' words (`{message}`), which the page sends again as an ordinary `/chat` turn through the usual gates. 409 while a turn is answering, for a stale reply id, and for a chat-app conversation (its reply also lives in Slack, Telegram or Discord); audited `session_rewound`. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily`, `GET /today/brief-delivery`, `GET /today/value`, `GET /today/top-three`, `GET /today/weekly-review`, `POST /today/seen` | Morning-brief aggregation (in the install's first week, for the principal, `first_week_card` `{needs_goal, findings: [{title, summary}], brief_tomorrow}` or null), recent-action rail, Pulse heartbeat heatmap (per-day activity counts), and the owner's month tally for Pulse's Done for you (`GET /today/value?period=month|week&offset=N`: counted lines beside the period before plus the finished reports, owner only, 403 otherwise; see Today). `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), the same text split for Home's Right now card (`narrative_lead`, `narrative_points` `[{text, since}]`, `narrative_move`), `narrative_seen_at` (this reader's last look, which `POST /today/seen` records and returns as `{seen_at}`) and, for the principal, `morning_brief` `{at, text}` and `calendar_next` `[{title, start, all_day}]`. 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` (a `POST` tells the owner once and returns `notified`: `sent` with the channel, `held`, `not_reached` or `skipped`; see Attunement), `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| `contacts` | `GET /contacts/changes?person_id=`, `PUT /contacts/keeper`, `POST /contacts/changes/seen`, `POST /contacts/changes/{id}/undo`, `POST /contacts/changes/{id}/accept`, `POST /contacts/changes/{id}/dismiss`, `GET /contacts/{person_id}/note` | The contact keeper (see Org), principal only (404 for anyone else). `GET /contacts/{person_id}/note` returns what is remembered about one contact or teammate (`note`, `topics`, `last_emailed_at`, `last_heard_at`, `last_met_at`, `next_meeting_at`, `next_meeting_title`, `emailed_count`, `met_count`, `note_written_at`, `updated_at`), 404 when there is nothing yet or they are not active. `GET` returns `{mode, status, last_run_at, changes}`: the switch (`on` / `ask` / `off`), how the last pass went (`ok`, `act_as_me_off`, `not_connected`, …) and the last 30 days of changes (each `id`, `person_id`, `action` add/update, `field`, `email`, `full_name`, `old_value`, `new_value`, `reason`, `evidence`, `status` applied/suggested/undone/dismissed, `seen`, `created_at`); with `person_id`, that person's every change. `PUT` sets the switch; `seen` is Got it; `undo` / `accept` / `dismiss` return the change, 409 when there is nothing to undo or decide. |\n| `chat-directory` | `GET /chat-directory/people`, `GET /chat-directory/channels`, `GET /chat-directory/slack/lookup?email=` | The Slack, Discord and Telegram people and rooms the bots can reach, by name, for the People and department pickers (`integrations/chat_directory.py`). Each answers `{slack, discord, telegram}`, every one `{configured, ok, options: [{id, name, detail, email}], truncated, members_available}`: `configured` false (and no options) when that bot has no token, `ok` false when the provider could not be read, `members_available` false when Discord refuses to list server members (the Server Members intent is off). `lookup` returns `{configured, match}`, the Slack person with that work email or null. Cached in-process for 60 s; tokens are never returned. The principal's alone, like changing the People list (`chat._caller_is_principal_or_unclaimed`); channels also open while no one is principal yet, people and lookup wait for one; a 403 otherwise, and the pickers then keep only the by-hand id field. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals`, `GET\\|POST /goals`, `PATCH\\|DELETE /goals/{id}` | Department state and goals. A goal has an optional department and an optional `owner_person_id` (a non-archived team member, else 422). `GET /goals` lists every goal with `owner_id`/`owner_name` (its own owner, else its department's head, else the principal) and `department_title`. `POST /goals` takes a goal plus `area` (a name, ≤80): an existing department by slug or title, else a new one of that name (no specialist, as with `POST /departments`), else no department when blank. `PATCH /goals/{id}` edits any goal and may move it (`department_slug`, null = none; `owner_person_id`, null = follow the department) — only the fields sent change; `DELETE /goals/{id}` removes any goal. The department-scoped goal routes still reach only that department's goals. `DELETE /departments/{slug}` keeps its goals with no department, on their owners. `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, i.e. the check-in is off); a changed `check_in` cancels the pending check-in and queues the next one on the new schedule. `GET` and `PATCH /departments/{slug}` return the department state plus `next_check_in_at` (ISO UTC of the pending check-in, `null` when it is off, the workspace is solo or none is queued); the list route does not carry it. 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`, `GET /agents/presets`, `POST /agents/presets/{id}`, `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. `AgentDetail` carries `instructions` (additional instructions, appended after `prompt`, which stays the built-in prompt or its replacement); `PATCH` and `/test` accept `instructions` (max 4,000 chars, blank clears it). `GET /agents/presets` lists the Fast, Balanced and Thorough quality presets (each with `available` and the resolved `model` for this install) plus `active` (null when the council is Custom), `base` and `custom_agents`; `POST /agents/presets/{id}` applies one by writing per-agent model and deep-reasoning overrides and returns the same shape (404 unknown preset, 409 when the install allows none of its models). Each `AgentMeta` carries `visibility` (`core` or `internal`) so the Council's simple view can list core agents first. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/approve`, `GET /alerts/approvals/{id}`, `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/snooze`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `approve` (body `{edited_body?}`, 202) carries a proposal card out on the server and records who approved it and when (`alerts.approvals`, see Today): it queues the scheduled action a department-gated card held, or runs one Executive turn as the approver in a new chat (`session_id`). 409 for a card already approved or closed, a decision-backed card (approved at `/decisions`), a roster request or a drafted artifact; 403 unless the caller is the card's routed person or the principal (an unrouted card is the principal's); 429 when the caller already has three background turns running. `GET /alerts/approvals/{id}` reads one back (`running`, then `done` / `failed` with `outcome`) for its approver, the card's person or the principal (404 for anyone else). `snooze` (`until`, an ISO time up to 30 days ahead; `null` clears it, the Undo) hides an `unread` card until then by setting `snoozed_until` (409 on a closed card or a roster request); the TTL then counts from the snooze, so a card snoozed past its TTL still comes back. `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`, `supersedes_id` and, for an extension's kind of document, `collection` / `collection_label` on every summary (`orchestrator.extensions`; archive, restore and delete tell the collection first and answer 502 if it refuses). `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. Every route answers for the signed-in caller (`artifact_records.Viewer`): a drafted artifact is its owner's alone (`alerts.owner_person_id`, the person whose conversation published it; none = the principal's), a workflow output follows its run (`persistence.run_visible_to`), and anything the caller may not see is a 404 like a missing id, the principal included. `POST /alerts/{id}/ack` and `/reopen` answer 404 for someone else's drafted artifact the same way. |\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). What approve/reject/cancel do is per class (`DECISION_CLASSES`, one `DecisionClassSpec` each; meeting booking books on approve and deletes on cancel; `delegation_reply`, an inbox reply card, is its approver's alone (`approver_only`) — hidden from everyone else, the principal included when it is a team member's — sends its Gmail draft on approve and, after a reject, deletes the draft unless it was edited; `delegation_invite`, a meeting invite card, is its approver's alone too, and answers the invite in their own calendar on approve (`edits.answer`) and nothing on reject; `department_action`, a team member's chat send or edit their department held (see Org), is the principal's and its approver's alone (`principal_and_approver`), makes that exact call on approve and audits `department_action_done` / `_failed` / `_declined`), and an instance of a class with no spec gets 409 instead of being carried out as another. Only the principal, or the person the decision went to for approval (`approver_person_id`), may approve, reject or cancel it. Anyone else gets 403, and a decision nobody was asked about, or one private to the principal, is the principal's alone. The resolver is recorded as `resolver_person_id`, and a reject that loses the race to another answer is a 409. `GET /audit/reliability` is the principal's alone (403 otherwise), because it counts private decisions too. 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/describe`, `POST /delegation/voice/signature`, `PUT /delegation/inbox`, `POST /delegation/inbox/check`, `GET /delegation/replies`, `PUT /delegation/replies/{id}/text`, `POST /delegation/drafts/{id}/send`, `PUT /delegation/replies/{id}/recipients`, `POST /delegation/replies/{id}/answer`, `POST /delegation/replies/{id}/change`, `GET /delegation/actions`, `GET /delegation/invites`, `PUT /delegation/handle-it`, `PUT /delegation/disclosure`, `PUT /delegation/training`, `DELETE /delegation/learned/{id}`, `GET /delegation/handled`, `PUT /delegation/team` | Act as me — the **caller's own** delegation only; nobody sets it for anyone else. It answers the principal, and a team member once the owner lets them; anyone else gets 403 `not_available_yet`. `GET /delegation` returns `{enabled, gmail: {status, message, email, connect_command, outlook_connect_command, provider}, inbox: {enabled, status, message, watch_since, last_poll_at, checking}, handle_it: {enabled, mode, available, sent_today, lead, lead_available}, training: {replies, follow_ups, actions, drafts, learned}, disclosure: {enabled, handle_it, approved_sends, line}, team}`, where `team` is the owner's switch for the principal while `DELEGATION_TEAM_MEMBERS` allows it — `{enabled, members: [{person_id, name, enabled, inbox, drafts_30d, sent_30d}]}`, counts only — and `null` otherwise. `PUT /delegation/handle-it` takes `{enabled?, mode?}` (`mode` is `careful`, `balanced` or `bold`; anything else is a 422 `bad_mode`) from a caller the API knows is that person — 403 `not_yours`, 409 `caller_signing_required` with only the shared secret — and turning it on needs Act as me and Draft replies to my inbox on (409 `act_as_me_off` / `inbox_off`); `GET /delegation/handled` returns `{replies: [{decision_id, sent_at, to_name, to_email, subject, body, open_questions, gmail_link, source, summary}]}`, the caller's replies and follow-ups (`source` `follow_up`) sent on its own in the last 7 days, and the meeting invites it accepted on its own (`source` `invite`, `subject` the meeting's title, `summary` one line such as \"Accepted Dana's Pilot review, Wed 21 Oct, 14:30\"); a card on `GET /delegation/replies` carries `source` the same way, `can_allow` while Replies (Follow-ups, on a follow-up) is in training, and `learns_style` while Drafts is. `PUT /delegation/disclosure` takes `{handle_it?, approved_sends?}` (any other field is a 422), the caller's own switches for the AI line on replies sent as them (`disclosure.enabled` is the install's `AI_DISCLOSURE`); turning one on needs no signed sign-in, turning one off does (409 `caller_signing_required`), and a change is audited as `delegation_disclosure_changed`. `PUT /delegation/training` takes `{replies?, follow_ups?, actions?, drafts?, actions_on?}` (any other field is a 422; `actions_on` is Suggested actions On, and `actions` and `actions_on` set true clear each other) and returns the `GET /delegation` shape, whose `training` carries `actions_on` too; putting Replies or Follow-ups in, or Suggested actions out of training or On, needs no signed sign-in, anything else does (409 `caller_signing_required`), and putting Replies or Follow-ups in turns Take the lead as you off (`PUT /delegation/take-the-lead` on answers 409 `in_training` while they are). `training.learned` is `[{id, label, setting, example, uses, created_at}]`, what the caller allowed or kept in training (`setting` `replies`, `follow_ups`, `actions` or `drafts`; the kept example, or \"\"); `DELETE /delegation/learned/{id}` removes one of the caller's own (404 for anyone else's). `PUT /delegation/team` takes `{enabled}` from the principal alone (403 `principal_only`; 409 `not_available` when the install doesn't allow it). The Gmail `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), write it from the caller's own description (`POST /delegation/voice/describe` with `{description}`: one model call applies their words to the profile they have and returns it with a short `sample_reply`, saving nothing, so they review it and save it with `PUT`; a 409 `empty`, `too_long`, `in_progress`, `too_many` past 10 an hour or `no_profile`; no mailbox needed), 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 mailbox isn't connected, it refuses the sign-in or the check itself fails (`gmail_error`), and a 502 `gmail_error` when reading the signature fails. On an Outlook mailbox it is a 409 `signature_unavailable`, since Outlook gives apps no signature to read, and the stored one is left alone. 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 caller is read through `api/caller.py`, as on every principal-only route). `PUT /delegation/inbox` takes `{enabled}` and turns **Draft replies to my inbox** on or off, returning the same shape as `GET /delegation`: on needs Act as me on (409 `act_as_me_off`) and the mailbox connected (the Gmail codes above, which keep their names for an Outlook mailbox too), and turning Act as me off turns it off too. `POST /delegation/inbox/check` starts a scan now in the background and answers 202 with the `inbox` state (409 `inbox_off` or `in_progress`). `GET /delegation/replies` returns `{cards: [...]}`, the caller's open reply cards from the database alone (no Gmail call): the decision id, the sender's name, address, relation and whether it was verified, the subject, when it arrived, what they wrote, a one-line `gist` (what they asked and what the draft says, written with the draft and brought up to date when an answer rewrites it; empty on an older card), the draft's recipients, subject and body, `open_questions`, `flags` and a Gmail link built from a fixed prefix. **Send** is `POST /decisions/{id}/approve`: it sends the card's draft exactly as it is in Gmail, after checking again that the caller is its owner — which on a server needs signed callers (409 `caller_signing_required` otherwise) — that both switches are on (`inbox_off`), no client slot is active (`client_slot`), the Gmail is connected (the Gmail codes), the draft is still there and unanswered (`draft_gone`, `you_replied`) and its recipients are allowed (`no_recipients`, `too_many_recipients`, `executive_recipient`, `not_from_you`). Recipients that changed, or a newer message in the thread, answer 409 `{code: \"confirm\", message, reasons, recipients}`; approving again with `edits: {recipients: <the list shown>, thread_moved_on: true}` is the second yes. Send with the *on its own next time* tick adds `edits.allow: true`: 422 `cant_allow` unless Replies (Follow-ups, on a follow-up card) is in training, 409 `learned_full` when their list is full, both before anything is sent; `edits.example: true` keeps a draft edited in the mailbox as how they write to that person while Drafts is in training. A draft edited in Gmail between those checks and the send is not sent (`draft_changed`). A double tap sends once (`already_handled`); Gmail refusing answers 429 `rate_limited` or 502 `gmail_error` with nothing sent, and a send Gmail didn't confirm answers 502 `send_unconfirmed` and is settled by the next inbox scan. Dismiss is `POST /decisions/{id}/reject`. `GET /delegation/invites` returns `{cards: [...]}`, the caller's own meeting invite cards (`delegation_invite`, Read my calendar on): `decision_id`, `status`, `created_at`, `from_name`, `from_email`, `relation`, `title`, `when` (in the workspace time zone), `start`, `end`, `all_day`, `clashes` (busy times only, `\"14:00–14:30\"`), `clash_checked`, `can_answer` (false for a sign-in that reads but can't answer the calendar; then `connect_command`), `can_allow` (Replies in training) and `waited_because`. **Accept** / **Decline** is `POST /decisions/{id}/approve` with `edits: {answer: \"accept\" | \"decline\"}` (accept is the default; `allow: true` with accept for the *Accept from them on its own next time* tick), on the same caller checks Send uses (403 `not_yours`, 409 `caller_signing_required`); 409 `calendar_write_needed` when the sign-in can't answer (the card stays), `gone` when the event left their calendar, `expired` once the meeting started, `already_handled`; 502 `calendar_error` leaves the card for another try. **Dismiss** is `POST /decisions/{id}/reject` and answers nothing. `GET /delegation/actions` returns `{cards: [...]}`, the caller's own approval cards (`delegation_actions`): the decision id, when it was made, a one-line `why`, and each action's `index`, `kind` (`invite`, `message`, `add_contact`), `summary` and `text` (a message as it will be sent, or a meeting's description). **Approve** is `POST /decisions/{id}/approve` with `edits: {only: [indexes]}` (and `allow: true` for the *Do this on its own next time* tick while Suggested actions is in training: 422 `cant_allow` otherwise or when nothing on it can be allowed, 409 `learned_full`; a card carries `can_allow`); it needs the card's own person signed in (403 `not_yours`, 409 `caller_signing_required`), Act as me on (409 `act_as_me_off`) and a card under a week old (409 `expired`), runs once (409 `already_handled`), and returns the decision with `final_payload_json.results`: per action `done`, `waiting` (sent to whoever approves meetings), `failed` with why, or `skipped`. Every change writes a private audit row. |\n| `history` | `GET /memories/history` (`?q=`), `PUT /memories/history/settings`, `PATCH`/`DELETE /memories/history/{id}`, `POST /memories/history/{id}/forget-conversation` | Always in the loop: the **caller's own** notes and switches only, resolved as for Act as me (a signed-in person on the roster, or the principal under local login; otherwise 403 `sign_in_required` / `not_on_roster`). `GET` returns `{notes, reply_notes, retention_days, effective_retention_days, company_retention_days, retention_choices, can_keep_notes, can_note_replies, can_set_company_retention, share_work_style, can_share_work_style}` (`can_keep_notes`: a team member on the People list may turn notes on; `can_note_replies`: they can use Act as me, so email replies are noted too; `share_work_style`: their own \"Share my work style with the team\" switch, `can_share_work_style`: a team member in a team workspace). `PUT` turns notes on only for someone who may keep them, and `share_work_style` on only for someone who may share it (403 `not_available` for either; turning either off always works), takes a person's retention only when shorter than the company's (422 `invalid_setting`), and the company retention only from the principal (403 `principal_only`). `PATCH` pins or corrects a note; `DELETE` forgets it; `forget-conversation` is \"Don't remember this\". A note that isn't the caller's is 404. Every change is audited privately to its person. |\n| `reflection` | `GET /memories/reflection` (`?person_id=`), `DELETE /memories/reflection/misses/{id}` | Learning: the turns the conversation review graded a miss (`memory.chat_review`), with the person's words, the reply, the tools run, what they wanted instead, the `kind` (`company` / `product`), the finer `cause` (null when the grade gave none) and the signals, plus `weeks` (`{week, graded, misses}` per ISO week, newest first) and `sees_everyone`. The caller is resolved as for `history` (403 `sign_in_required` / `not_on_roster`); each person sees their own, the principal those from chats `chat._session_access` lets them open (a teammate's own web chat or DM and a mail-private conversation stay their owner's; channels and groups are open), or one person's with `?person_id=` (a teammate naming someone else gets 403 `not_yours`); the weekly counts carry no words and are not filtered. The same response carries `lessons` (`memory/lessons.py`: live first, then retired, each with `shown`/`fine_after`/`miss_after` and `retired_reason`), filtered by the same rule, and `DELETE /memories/reflection/lessons/{id}` retires one (204; 404 for a lesson the caller may not see, already retired, or missing). `DELETE` forgets one miss (`is_principal_or_self`; 404 `not_found` otherwise) and writes a `chat_review` audit row. Each miss also carries its nightly replay (`memory/replay.py`): `replay_state` (`open` / `closed` / `evidence`), `replayed_at`, `closed_at`, `replay_notes`; and the response carries `replay` (`{misses, would_pass, evidence, last_run_at}`: of the caller's visible misses from the last 30 days, how many would go right today). |\n| `notifications` | `GET /notifications/settings`, `PUT /notifications/settings` | Settings → Notifications: the **caller's own** settings only, resolved as for the notes (a signed-in person on the People list, or the principal under local login; otherwise 403 `sign_in_required` / `not_on_roster`). `GET` returns `{quiet_hours: {enabled, start, end, days}, delivery, urgent_through, timezone, effective_timezone, held_count, gets_briefs, updated_at}` — `days` is `every_day` or `weekdays`, `delivery` `instant` or `digest`, `timezone` the zone they chose (`\"\"` for the workspace's), `held_count` how many messages wait for their quiet hours or brief (counted, never listed), `gets_briefs` whether they are the principal. `PUT` takes `{quiet_hours, delivery, urgent_through, timezone}` and replaces them (extra fields, equal start and end, a bad time or an unknown zone → 422); switching `digest` → `instant` makes what waited for the brief go now. Audited as `notification_settings_changed`. See Org. |\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), plus `scripts`: how many `run_script` scripts ran (and worked, and in workflows), the tool calls they made, their time, and `turns_avoided` — an upper bound on the model turns those calls would otherwise have needed (each call past a script's first) — and `python_jobs`: how many Python jobs ran (and worked, ran a kept Custom tool, took a chat attachment), their time, CPU, largest peak memory and bytes in and out, and the tokens and charge of the turns that ran one. The Token usage page shows it as a Scripts section. 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 usage totals leave them out. Once a principal is on the roster, anyone else reads only their own rows (a teammate's own turns, their Act as me work) in the list, by id and in a session, and the principal reads those as actions only — what was done, when and in whose conversation, with the text, details and `full` left out, and no text search over them; any other row's id is a 404, and a session shows only the rows the caller reads. |\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. Only `/health` is unauthenticated; `/health/honcho` sits behind the gate like everything else, because the exemption is an exact-path set. `/health` also carries `google_tools_missing`, the pinned Google tools startup priming could not find: `[]` once it has checked and they are all there, a list of names when a workspace-mcp rename or the configured services and tool tier left one out, and `null` for no answer — Google Workspace is not configured, or the probe has not finished or it failed. Only `[]` asserts they are present. It also carries `gateway`, the MCP gateway's state from its supervisor (`orchestrator.gateway_boot`): `state` is `off` (MCP not enabled), `no_servers` (enabled, the config names none), `starting` (an attempt is running), `up` or `down` (every attempt so far failed; `next_retry_at` is the next one), with `attempts`, `up_since` and `email_poller` (whether the poller that rides on the gateway runs); the failure's own text stays out, since the route is open to anyone, and goes to the log and the owner's notice on Home. A hosted instance whose gateway never came up used to answer `ok` here with no email going out or in. Only `[]` asserts the tools are present, so a probe that died cannot read as healthy; Setup status says which of the three `null` means. |\n| `version` | `GET /version` | The running version, the latest release on GitHub and `update_available`, for Settings → About. The GitHub answer is cached 6h, only a semver `tag_name` is used and the release link is built from it; `UPDATE_CHECK_ENABLED=false` skips the call and still returns the running version. No in-app updater: upgrading is host-side (`docs/deployment.md#upgrading`). |\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 mailbox (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. With `CONFLUENCE_SYNC_ENABLED` it bootstraps the `confluence_sync_scan` heartbeat the same way; that sync is run by hand with `openexecutive sync-confluence` / `purge-confluence`. 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\\|onedrive\\|notion}/sync`, `GET /documents/{drive\\|onedrive\\|notion}`, `GET /documents/{drive\\|onedrive\\|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`, `/documents/onedrive` and `/documents/notion` list synced files from the sync state (`{enabled, last_run, last_error, files: [{id, name, url, modified_at, synced_at, indexed}]}`; a Drive row also carries `unreadable_reason`, why a file with `indexed: false` has no text — e.g. a scan OCR could not read — or null); `/documents/{drive\\|onedrive\\|notion}/{id}` returns the stored text (a OneDrive id is `<drive id>:<item id>`) 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 (every sync holds a per-process run lock, so a manual run never overlaps the heartbeat; the route also keeps its own started task per source and re-checks just before starting one, so two simultaneous requests start one tick, not two), 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. The upload is streamed to disk 1 MB at a time and refused with a 413 once it passes 50 MB, and the file is parsed in a short-lived child process (see the RAG section), so a large document does not stay in the API process's memory. A Word or Excel file that cannot be parsed, or whose parse runs out of time, is a 422 with a readable reason. When every parser is busy, the response is a 503 with `Retry-After`. |\n| `executive` | `GET /executive/status`, `POST /executive/pause`, `POST /executive/resume`, `GET`/`PUT /executive/outside-content` | 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, name}` — `held_actions` counts due `pending` rows that fire on resume, and `name` is the Executive's name (`EXEC_DISPLAY_NAME`), which the web chat shows over its replies. `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. `GET /executive/outside-content` returns `{mode, channels, channel_ids, can_change}` for the owner's safety level, \"When should I check with you?\" (`ask` Careful, `outsiders` Balanced or `trust` Hands-off; `orchestrator.outside_mode`): `channels` maps each channel set apart to its own level, and `channel_ids` lists the channels a level can be set on. `PUT` with `{mode, channels?}` changes it for the principal only (403 otherwise; an unknown channel or level is a 422): a channel given a level is set apart, one given `null` follows `mode` again, and channels left out keep theirs. A change writes an `outside_content_mode_changed` audit row. |\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/describe`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. `POST /watchlist/describe` `{text}` drafts a watch from a sentence (one forced tool call on the utility-fast model, `monitoring.describe`; the company profile's name, competitors, vendors and tickers ride in the user turn) and saves nothing: it returns the create fields (`slug`, `signal_type`, `target`, `display_label`, `trigger`, `cadence`, `mode`, `severity_floor`, `severity_ceiling`, `notes`) plus four plain lines (`watching`, `tell_you_when`, `how_often`, `how_loud`) written by code from those fields, after the create route's checks (registered kind, cadence, severity, the URL guard, the rss feed check, a free slug); 422 with a plain reason when it can't be a watch, 429 past 30 drafts an hour, 502/504 when the model fails. `GET /watchlist/{slug}` also returns `noise` `{recent_alerts, recent_dismissed, noisy}` (its last 8 alerts, noisy at 6 dismissed, `monitoring.noise`), and `PATCH` takes `quiet_noise_nudge: true` to stop that question for the alerts so far. `display_label` on create maps to the adapter's label key for every kind. 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`, `POST /workflows/runs/{run_id}/rerun`, `GET /workflows/tools/search?q=`, `GET /workflows/tools/describe?names=` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. A workflow with a step that sends email as its creator (`oe__send_email_as_me`) or reads their mail or calendar (`oe__search_my_email` and the other reads, `delegation.workflow_reads`) can be created, changed (`PUT`, save-edit) or switched on (`activate`) only by that creator, verified as Send on a reply card is; anyone else gets a 403 (`delegation.workflow_email.save_refusal`), as does a save of one that reads and also lists a tool a run may not use after reading mail. `POST /workflows/{name}/runs` answers 403 to anyone but the creator of a workflow that reads their mail. `rerun` queues a failed scheduled run (a department check-in, a saved workflow on a cadence) once more, due now (see Scheduler); the principal may, and for a saved workflow the person it delivers to; 409 for a run that did not fail, one started from `/jobs` (\"Start this one again from its page\") or one already queued again. 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. A run started by hand (this endpoint, or `run_workflow` / research in chat) records its starter as `owner_person_id` and is theirs alone: `GET /workflows/runs` lists the team's (scheduled, no owner) runs plus the caller's own and the ones waiting on them, and `GET` / `DELETE /workflows/runs/{run_id}` and `POST /workflows/runs/{run_id}/decision` are a 404 for anyone else's, the principal included. A signed-in email that is on nobody's People entry cannot start one (403), and a run whose starter can't be read is refused (503); its steps read and draft documents as the starter only. `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`, `background` (true for the system-run built-ins the UI files under “System”) and `quick` (true for a Quick workflow, one per playbook nothing else follows, named `quick_<playbook>`). 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| `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). Peer memory is each person's own: the overview holds only the caller's entry (none for a caller off the roster; `conclusion_total` counts only theirs), the principal included, and `/conclusions` for anyone but the caller 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/understand`, `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/revise`, `/onboard/interview/{id}` (GET resumes, DELETE starts over), `/onboard/interview/commit` | Conversational company setup. `understand` and `start` take multipart `description`, optional `files` and an optional `website` the server reads itself (a non-address is a 422; an unreadable site is no pages, never an error); `start`'s response lists the pages read in `website_pages`, and the draft's profile carries `website`. The `onboarding_interviewer` agent asks up to four quick questions (a question response carries `question_options`, suggested answers to tap), then emits a draft profile + people + `draft_goals` (each `{title, target, owner_name, department_title}`) + departments only when the user listed people by department. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). `revise` changes one earlier answer (0 = the description) and runs the interview again from there. `commit` takes the reviewed `goals` too (422 when one names a person or department not in the draft) and saves them with owners, additively. It 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/edit`, `POST /workflows/designer/message`, `POST /workflows/designer/draft`, `GET /workflows/designer/{session_id}` | The conversational New workflow wizard, and editing a saved workflow by conversation. `/edit` (`{name}`) opens a session on a saved custom workflow with no model call: the stored definition is the starting draft, and every response then carries `editing` (its name) and `original` (the stored definition as the session opened on it); drafts keep that name and its on/off state whatever the model writes (404 for an unknown workflow). The UI saves one with `POST /workflows/custom/{name}/save-edit` (`{session_id, definition}`): the server saves the session's own draft, never a client-sent body, and only when it equals the `definition` the user reviewed (a later message is a 409, so the click saves only what was shown); it re-validates it, keeps the stored on/off state, and writes only if the stored workflow is still the version the conversation opened on — otherwise 409, as it is for a session about another workflow or one with nothing drafted yet. It sits under `/workflows/custom` so anything that limits writes to custom workflows covers it too. 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| `python_jobs` | `GET /python-jobs/{job_id}/{name}` | A result file a Python job (`run_python_job`) wrote, the principal's alone (403 otherwise), served as a download (`Content-Disposition: attachment`, `Content-Security-Policy: sandbox`, `nosniff`, `Cache-Control: no-store`); 404 for a bad id or name or a file past its 7 days. |\n| `saved_tools` | `GET /saved-tools`, `GET\\|PUT /saved-tools/{name}`, `POST /saved-tools/{name}/rollback` | The scripts the Executive saved as tools (Settings → Advanced → Saved tools), the owner's alone (403 otherwise). The list gives each tool's name, description, on/off, current version, `kind` (`script` or `python`, a kept Python job) and the tools it calls, plus whether `SAVED_TOOLS_ENABLED` is on; the detail adds the script, every version and the last 20 runs. `PUT {enabled?, workflows?, version?}` turns one on or off (off also turns it off for workflows, so turning it back on never re-arms unattended runs), and turns the named `version` — the one the owner looked at, never whatever is current by then — on for workflows (or workflows off); a Python tool never turns on for workflows (409) — turning workflows on lets more run unattended, so it needs a request tied to the owner (signed sign-ins or local login, as Take the lead's switches do; 409 otherwise); `rollback {version}` makes that version the one that runs. Both are audited as `saved_tool_changed`. The Executive saves tools itself through `run_script`; there is no create route. |\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| `auth` | `GET /auth/me` | `{email}`: the email the request is made as (`api.caller`, lowercased; `\"\"` when it names no one), nothing more. On the host list, so a host's own screens can warn when the session signed in here is someone else's. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. `POST /fixtures/reset` leaves no departments, like a new install (`departments_seeded` is always 0). |\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`, `POST /webhook/slack` | Inbound integration callbacks (self-verified). `/webhook/slack` answers 503 unless `SLACK_SIGNING_SECRET` is set. |\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, answered as the verified caller (`api.caller`) by the web app's rules. See the MCP Server section. | A card the Executive left for something asked in chat (`app_action`, `orchestrator/app_control.py`) is its person's alone too: its payload holds `action`, `id`, `value`, `title` and the `card` line shown; **Confirm** is `POST /decisions/{id}/approve`, which runs the action through the route its button calls with that request (a refusal comes back as that route's status and words, and the card is marked `failed`), and a card older than a day is turned down with 409.\n\n**What it does for you** (`api/routes/may_do.py`): `GET /what-it-may-do` is read-only. It returns `{paused, sections}`, three sections in order (`as_you`, `executive`, `departments`), each `{key, title, available, unavailable, notes, rows, footer, goes}`, and each row `{id, what, outcome, then, why, setting, items}`: `outcome` is `goes`, `waits`, `always_waits`, `drafts` or `off`, and `setting` names where to change it (`act_as_me`, `handle_it`, `take_the_lead`, `pause`, `department:<slug>`, or empty). `as_you` is the caller's own (`available` false, with why, when they can't have Act as me); `executive` is the principal's alone (`available` false for anyone else); `departments` is everyone's. Any team member on People may call it; a contact, someone not on People, or a request with no caller outside local login gets 403. See Delegation → What it does for you.\n\n**How far it goes as you** (`api/routes/delegation.py`): `PUT /delegation/reach` takes `{step}`, one of `off`, `when_asked`, `inbox`, `careful`, `balanced`, `bold`, `everything`, and answers the caller's delegation state as `GET /delegation` does. Going down turns the switches above the step off, highest first; going up runs each switch's own route in order (`PUT /delegation`, `PUT /delegation/inbox`, `PUT /delegation/handle-it`, `PUT /delegation/take-the-lead`), so the first refusal (409 `gmail_not_connected`, a signed sign-in missing, `in_training`, 403 for Everything when not the owner) stops it at a whole step. See Delegation → How far it goes as you.\n\n**Take the lead** (`api/routes/take_the_lead.py`): `GET /take-the-lead` returns the As the Executive switch, its six Ask first switches (`{kind, label, hint, on}`, the hint a plain line on what each one catches), the company's rules, whether this server can tie a change to the owner (`available`), and whether the Executive is paused. `PUT /take-the-lead` takes `{enabled?, ask_first?}`, and `POST /take-the-lead/rules` / `DELETE /take-the-lead/rules/{id}` add or remove a company rule (`{kind: person|domain|words|amount, value}`, 422 on a bad one). All four are the principal's alone (403). Anything that lets more happen on its own (turning it on, turning an Ask first off, removing a rule) needs a caller the API can tie to them (`delegation.verified.caller_refusal`, else 409). `GET /today/activity` adds `took_the_lead` rows (what Take the lead did, named, not quoted) and, for the caller alone, `sent_as_you` rows for what Handle it for me sent as them (and the meeting invites it accepted as them, \"Accepted Dana's Pilot review, Wed 21 Oct, 14:30\") and, for the principal, one `contacts_kept` row a day the contact keeper changed something (`detail` like \"2 added, 1 updated\"). Under `/delegation`: `PUT /delegation/take-the-lead {enabled}` is Take the lead as you (the owner's only for now; turning it on turns Handle it for me on), and `GET|POST /delegation/take-the-lead/rules` and `DELETE …/rules/{id}` manage the caller's own rules. `HandleItOut` gains `lead` and `lead_available`. A `take_the_lead_action` decision is approved or rejected through the existing `/decisions/{id}/approve|reject`. Training: the response also carries `training` (In training: everything waits unless allowed), `learned` (`{id, label, feature, example, uses, created_at}`: what it was allowed, the edit kept as an example by field) and `suggested` (`{key, label, approvals}`); `PUT` takes `training?` too, and leaving training while on needs the same provable owner as turning it on. `POST /take-the-lead/learned {key}` allows a current suggestion (404 for anything else; provable owner), `DELETE /take-the-lead/learned/{id}` makes it ask first again. `learned` also lists the owner's own Act as me senders (`feature` `act_as_me`), never anyone else's, and Remove works on those too. On a `take_the_lead_action` card, `POST /decisions/{id}/approve` takes `edits.input` (the card's editable fields, 422 for any other; the principal's alone, 403 for an area approver) and `edits.allow: true` (a training card only, 422 otherwise; the principal from a provable request, 403 otherwise), finishing `approved_with_edit` when a field changed.",
+ "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). A request it lets through is marked `request.state.shared_secret_ok`, which is what lets an MCP request turn on \"may act\" with `x-mcp-client-actions: on` (`mcp_server.may_act`; with no secret the header is ignored and `MCP_CLIENT_ACTIONS` decides). With local login (`OE_LOCAL_LOGIN=1`, which only `make dev` sets, and only while neither Google nor SSO sign-in is 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 and Slack 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 the UI origins in `BACKEND_ALLOWED_ORIGINS`, plus the `make dev` UI on `localhost:3000` only when `OE_PUBLIC_DEPLOYMENT` is unset, so a public instance never answers a localhost page with credentials. 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\n**Who is calling** is read in one place, `api/caller.py`, which answers with a `Caller` kind and email; a test fails on any other read of an `x-caller-*` header. By default (`open`) it is the `x-caller-email` the UI proxy stamps from the sign-in, trusted because whoever holds the shared secret is trusted as the proxy, and a request with none runs as the principal. **Signed callers** remove that trust. With `CALLER_ASSERTION_PUBLIC_KEYS` set, the proxy signs every request with an Ed25519 key only the UI holds, and a third middleware checks the `x-caller-assertion` header:\n\n- **What it covers.** It is good for one method, the exact path and query, at most 120 seconds, and one use. The API keeps used ids in memory.\n- **What it names.** A `user`, by email, or the `operator`: local login, which runs as the principal.\n- **No caller header at all** is a `service`, for scripts or MCP clients holding only the secret. It is never the principal, not even on an install with no owner yet, so it can't save a first setup.\n- **Anything else is a 401.** That includes an `x-caller-email` without an assertion (`caller_assertion_required`), and a bad, expired, reused or mismatched assertion (`caller_assertion_invalid`).\n\nPublic keys that can't be read stop the boot, rather than fall back to trusting the header. `scripts/make-caller-keys.py` makes the pair, and `scripts/mint-caller-assertion.py` signs one request for curl. The API holds only public keys. Setup's API-protection check warns while a shared secret is set without them.\n\n**Host origins.** Another app on a sibling host (`OE_HOST_ORIGINS` on the UI, exact origins) may frame the pages and call a short list of routes from its own pages, as the signed-in person. The list is `packages/ui/src/lib/host-list.json`: who is signed in (`GET /auth/me`, the email the call is made as, so the host can warn when that isn't its own user; never `/auth/allowed-emails`), `/today*`, `/decisions` and one decision, conversations (`GET /sessions*`) and the watch list; `ack`, `snooze`, `reopen`, `bulk-ack` and `review` on alerts; `POST /chat`, `/chat/stop`, `/chat/add`, `/chat/upload`, `/chat/transcribe`; and the watch list's describe, add, edit, delete, approve and decline. No card's approve, reject or cancel, no prepare, Act as me, delegation, settings or People (`tests/unit/test_host_list.py` checks each entry against the app's routes and against that rule). The UI's middleware and proxy enforce it: a request whose `Origin` is a listed host origin, with `Sec-Fetch-Site: same-site`, may make only those calls, with CORS for that exact origin and credentials (its preflight answered before the session check, a missing session a `401` with CORS), and anything else from it is a `403`. The proxy then drops the browser's `Origin`, `Referer` and `Sec-Fetch-*`, so the local-login rule above never sees them, and marks the call's **surface** `host`: an optional `surface` claim in the signed assertion and `x-caller-surface`, which must agree with it (`401` otherwise; without signed callers the header is read like the email). `api.caller.from_host` answers it, and a chat turn on that surface (`Session.from_host`) only reads and advises (see Agents). Every page of the UI also sends a `Content-Security-Policy`: scripts only with that response's nonce (no `unsafe-inline`, no `unsafe-eval` outside the dev server) and `frame-ancestors 'self'` plus the host origins. `make embed-outputs` writes the API's OpenAPI description (`scripts/export-openapi.py`), the host list and the UI's navigation for a host app's own checks.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat`, `POST /chat/stop`, `POST /chat/add`, `POST /chat/background`, `GET /chat/voice`, `POST /chat/transcribe` | SSE stream of a live Executive turn, with a `: keepalive` comment every `CHAT_STREAM_KEEPALIVE_S` while the turn is quiet. `POST /chat/background` starts a new chat that the server answers to the end with nobody connected (a phone approving a card, then closing the app): it answers `202` with the new `session_id` once the same caller, access and quota checks as `/chat` pass, the turn saves itself as a `/chat` turn does, and one caller may have three running at once (`429` beyond that). `POST /chat/add` hands the running turn a message the person typed while it works; the turn takes it at its next step and the stream names it in a `message_added` event, and a second `POST /chat` on the same conversation waits for the first to finish. `GET /chat/voice` says whether the chat mic shows (`available`, `max_seconds`); `POST /chat/transcribe` takes one recording (multipart `file`) and answers `{text}` for the message box, nothing kept: `404` when speech to text isn't set up, `400` for a file that isn't audio, `413` over 25 MB, `502` when the speech server fails. 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`. When the turn held steps for an outside read that still wait on the speaker's go (`outside_content.pending_held`), it then sends one `held_steps` event, `{type, session_id, steps: [plain words]}` (not after a stop or a timeout), which the UI shows as Approve / Not now under the reply; Approve sends \"Go ahead\". `GET /sessions/{id}/messages` puts the same `held_steps` on the last reply while they still wait (never for a shared chat's member). When the content check flagged something the turn read (`outside_content.pending_flags`, `orchestrator.content_scan`), it also sends one `flags` event, `{type, session_id, flags: [plain words]}`, shown as \"Something looked off\" under the reply, and `GET /sessions/{id}/messages` puts the same `flags` on the last reply for an hour (never for a shared chat's member). 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/shared-with-me`, `GET /sessions/topics`, `PATCH\\|DELETE /sessions/topics/{topic_id}`, `POST /sessions/topics/{topic_id}/merge`, `POST /sessions/topic-areas/rename`, `POST /sessions/topic-areas/ungroup`, `GET\\|PATCH /sessions/{id}`, `GET /sessions/{id}/messages`, `DELETE /sessions/{id}`, `POST /sessions/{id}/messages/{message_id}/feedback`, `GET /sessions/{id}/followup`, `GET\\|PUT /sessions/{id}/shares`, `DELETE /sessions/{id}/shares/me`, `GET /sessions/{id}/people`, `GET /sessions/{id}/live`, `POST /sessions/{id}/typing`, `GET /sessions/{id}/export`, `POST /sessions/{id}/rewind` | List, read and delete saved chat sessions (assistant messages carry their row `id` and any `feedback`). The list is scoped to the caller, and each chat carries `preview`: its last message as one plain line, Markdown marks stripped and cut at a word near 120 characters, with `You:` before the person's own words. With `?q=` it is a search: the caller's own chats whose title or message text contains the words (case-insensitive, `LIKE` with wildcards escaped), each with `match_count` (messages that contain them; 0 for a title-only match) and `snippet` (the newest matching message, around the match, prefixed `You:` or `Executive:`). Scoped exactly like the list, so nobody else's conversation can match. The Chats page searches this way and opens a result with `?find=`, so the chat starts on that message and steps through the others. Each of the owner's chats also carries `topic_id`, the topic it is filed under (`memory.chat_topics`). `GET /sessions/topics` lists the caller's topics (`id`, `name`, `chat_count`, `kept`, `pinned_at`, `area`, `updated_at`) and, when some of their chats have no topic yet or some topics no area, starts filing them in the background from their titles and answers `organizing: true` until done. `PATCH /sessions/topics/{topic_id}` renames (a name another of their topics has merges the two) or pins one, `POST …/merge` moves its chats into another (`into_id`), and `DELETE` ungroups it, leaving its chats under no topic; another person's topic is a 404. `POST /sessions/topic-areas/rename` (`area`, `name`) renames one of the caller's areas and `…/ungroup` (`area`) drops it, its topics standing alone; an area they don't have is a 404. `PATCH /sessions/{id}` also takes `topic_id` (null for none) or `topic_name` (made if new) to file the chat, which then is never refiled on its own. A chat-app conversation started with /new is left off the list until its first turn (`memory.conversations`). 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. A teammate's own chat (a web chat, a DM, a private Telegram chat; not a channel or group conversation, `chat._shared_space`) is theirs alone, the principal included, as their mail with the Executive is. 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. The owner (not the principal on someone else's chat; the principal for an ownerless one) also has the chat controls. `PATCH` takes `{title?, pinned?}`: a name they give is kept (`sessions.title_locked`, so the automatic title never replaces it) and a pinned chat lists first, newest pin first, with `pinned_at`. `PUT /sessions/{id}/shares {person_ids}` adds exactly those team members to it (not contacts, the archived or the owner: 422), audited `session_shared`; a chat that read its owner's own mail (`mail_private`) is never shared (409) and stops being open to those it was shared with before, and a chat-app conversation is never shared (409). Those added get it from `GET /sessions/shared-with-me` (with `shared_with_you`, `shared_by`, `shared_at`) and **write in it with the owner**: `POST /chat` with its id runs their turn as themselves (`chat._shared_member` widens the turn's access, never its ownership), and they may read it, its messages (without the owner's ratings) and its export. They can't rate, rename, delete, share or redo it, and `DELETE /sessions/{id}/shares/me` takes them out of it (audited `session_shared`, with them under `removed`). In a chat several people are in, messages carry `sender_person_id` and `sender_name` (a message from before it was shared is the owner's), `GET /sessions/{id}/people` returns `{you, people: [{person_id, full_name, owner}]}` (owner first; empty for a chat of one), and redo is refused (409) when the last message is someone else's. `GET /sessions/{id}/live` is a server-sent event stream each open page holds (`api.chat_live`, one in-process broker): `ready` first (with the running turn so far, if any), then `turn_started` (who sent what), the reply's `chunk` / `thinking` / `activity` / `action_taken` / `phase`, `turn_ended` (the page reads the chat again), `typing` (from `POST /sessions/{id}/typing`, at most once per 2 s per person) and `people`. `removed`, `deleted` and `resync` (a page that fell 1024 events behind) end it; the access check runs again on every 20 s keepalive. At most 12 pages per person, 40 per chat and 2000 per process (429). Archiving someone takes them out of every chat shared with them, and their open streams close at the next keepalive. The page closes it while its tab is hidden. `GET /sessions/{id}/export` returns the chat as a Markdown file (`memory.chat_export`: each message under its writer's People name or `Executive`, the reply's sources listed under it). `POST /sessions/{id}/rewind {last_message_id}` takes back the last turn for Try again and Edit: under the conversation's turn lock it deletes the last reply and the messages it answered, but only while that reply is still the chat's last row, and returns those messages' words (`{message}`), which the page sends again as an ordinary `/chat` turn through the usual gates. 409 while a turn is answering, for a stale reply id, and for a chat-app conversation (its reply also lives in Slack, Telegram or Discord); audited `session_rewound`. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily`, `GET /today/brief-delivery`, `GET /today/value`, `GET /today/top-three`, `GET /today/weekly-review`, `POST /today/seen` | Morning-brief aggregation (in the install's first week, for the principal, `first_week_card` `{needs_goal, findings: [{title, summary}], brief_tomorrow}` or null), recent-action rail, Pulse heartbeat heatmap (per-day activity counts), and the owner's month tally for Pulse's Done for you (`GET /today/value?period=month|week&offset=N`: counted lines beside the period before plus the finished reports, owner only, 403 otherwise; see Today). `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), the same text split for Home's Right now card (`narrative_lead`, `narrative_points` `[{text, since, source}]` (`source`: the email or Needs you card a point is about, or null), `narrative_move`), `narrative_seen_at` (this reader's last look, which `POST /today/seen` records and returns as `{seen_at}`) and, for the principal, `morning_brief` `{at, text}` and `calendar_next` `[{title, start, all_day}]`. 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` (a `POST` tells the owner once and returns `notified`: `sent` with the channel, `held`, `not_reached` or `skipped`; see Attunement), `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| `contacts` | `GET /contacts/changes?person_id=`, `PUT /contacts/keeper`, `POST /contacts/changes/seen`, `POST /contacts/changes/{id}/undo`, `POST /contacts/changes/{id}/accept`, `POST /contacts/changes/{id}/dismiss`, `GET /contacts/{person_id}/note` | The contact keeper (see Org), principal only (404 for anyone else). `GET /contacts/{person_id}/note` returns what is remembered about one contact or teammate (`note`, `topics`, `last_emailed_at`, `last_heard_at`, `last_met_at`, `next_meeting_at`, `next_meeting_title`, `emailed_count`, `met_count`, `note_written_at`, `updated_at`), 404 when there is nothing yet or they are not active. `GET` returns `{mode, status, last_run_at, changes}`: the switch (`on` / `ask` / `off`), how the last pass went (`ok`, `act_as_me_off`, `not_connected`, …) and the last 30 days of changes (each `id`, `person_id`, `action` add/update, `field`, `email`, `full_name`, `old_value`, `new_value`, `reason`, `evidence`, `status` applied/suggested/undone/dismissed, `seen`, `created_at`); with `person_id`, that person's every change. `PUT` sets the switch; `seen` is Got it; `undo` / `accept` / `dismiss` return the change, 409 when there is nothing to undo or decide. |\n| `chat-directory` | `GET /chat-directory/people`, `GET /chat-directory/channels`, `GET /chat-directory/slack/lookup?email=` | The Slack, Discord and Telegram people and rooms the bots can reach, by name, for the People and department pickers (`integrations/chat_directory.py`). Each answers `{slack, discord, telegram}`, every one `{configured, ok, options: [{id, name, detail, email}], truncated, members_available}`: `configured` false (and no options) when that bot has no token, `ok` false when the provider could not be read, `members_available` false when Discord refuses to list server members (the Server Members intent is off). `lookup` returns `{configured, match}`, the Slack person with that work email or null. Cached in-process for 60 s; tokens are never returned. The principal's alone, like changing the People list (`chat._caller_is_principal_or_unclaimed`); channels also open while no one is principal yet, people and lookup wait for one; a 403 otherwise, and the pickers then keep only the by-hand id field. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals`, `GET\\|POST /goals`, `PATCH\\|DELETE /goals/{id}` | Department state and goals. A goal has an optional department and an optional `owner_person_id` (a non-archived team member, else 422). `GET /goals` lists every goal with `owner_id`/`owner_name` (its own owner, else its department's head, else the principal) and `department_title`. `POST /goals` takes a goal plus `area` (a name, ≤80): an existing department by slug or title, else a new one of that name (no specialist, as with `POST /departments`), else no department when blank. `PATCH /goals/{id}` edits any goal and may move it (`department_slug`, null = none; `owner_person_id`, null = follow the department) — only the fields sent change; `DELETE /goals/{id}` removes any goal. The department-scoped goal routes still reach only that department's goals. `DELETE /departments/{slug}` keeps its goals with no department, on their owners. `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, i.e. the check-in is off); a changed `check_in` cancels the pending check-in and queues the next one on the new schedule. `GET` and `PATCH /departments/{slug}` return the department state plus `next_check_in_at` (ISO UTC of the pending check-in, `null` when it is off, the workspace is solo or none is queued); the list route does not carry it. 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`, `GET /agents/presets`, `POST /agents/presets/{id}`, `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. `AgentDetail` carries `instructions` (additional instructions, appended after `prompt`, which stays the built-in prompt or its replacement); `PATCH` and `/test` accept `instructions` (max 4,000 chars, blank clears it). `GET /agents/presets` lists the Fast, Balanced and Thorough quality presets (each with `available` and the resolved `model` for this install) plus `active` (null when the council is Custom), `base` and `custom_agents`; `POST /agents/presets/{id}` applies one by writing per-agent model and deep-reasoning overrides and returns the same shape (404 unknown preset, 409 when the install allows none of its models). Each `AgentMeta` carries `visibility` (`core` or `internal`) so the Council's simple view can list core agents first. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/approve`, `GET /alerts/approvals/{id}`, `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/snooze`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `approve` (body `{edited_body?}`, 202) carries a proposal card out on the server and records who approved it and when (`alerts.approvals`, see Today): it queues the scheduled action a department-gated card held, or runs one Executive turn as the approver in a new chat (`session_id`). 409 for a card already approved or closed, a decision-backed card (approved at `/decisions`), a roster request or a drafted artifact; 403 unless the caller is the card's routed person or the principal (an unrouted card is the principal's); 429 when the caller already has three background turns running. `GET /alerts/approvals/{id}` reads one back (`running`, then `done` / `failed` with `outcome`) for its approver, the card's person or the principal (404 for anyone else). `snooze` (`until`, an ISO time up to 30 days ahead; `null` clears it, the Undo) hides an `unread` card until then by setting `snoozed_until` (409 on a closed card or a roster request); the TTL then counts from the snooze, so a card snoozed past its TTL still comes back. `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`, `supersedes_id` and, for an extension's kind of document, `collection` / `collection_label` on every summary (`orchestrator.extensions`; archive, restore and delete tell the collection first and answer 502 if it refuses). `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. Every route answers for the signed-in caller (`artifact_records.Viewer`): a drafted artifact is its owner's alone (`alerts.owner_person_id`, the person whose conversation published it; none = the principal's), a workflow output follows its run (`persistence.run_visible_to`), and anything the caller may not see is a 404 like a missing id, the principal included. `POST /alerts/{id}/ack` and `/reopen` answer 404 for someone else's drafted artifact the same way. |\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). What approve/reject/cancel do is per class (`DECISION_CLASSES`, one `DecisionClassSpec` each; meeting booking books on approve and deletes on cancel; `delegation_reply`, an inbox reply card, is its approver's alone (`approver_only`) — hidden from everyone else, the principal included when it is a team member's — sends its Gmail draft on approve and, after a reject, deletes the draft unless it was edited; `delegation_invite`, a meeting invite card, is its approver's alone too, and answers the invite in their own calendar on approve (`edits.answer`) and nothing on reject; `department_action`, a team member's chat send or edit their department held (see Org), is the principal's and its approver's alone (`principal_and_approver`), makes that exact call on approve and audits `department_action_done` / `_failed` / `_declined`), and an instance of a class with no spec gets 409 instead of being carried out as another. Only the principal, or the person the decision went to for approval (`approver_person_id`), may approve, reject or cancel it. Anyone else gets 403, and a decision nobody was asked about, or one private to the principal, is the principal's alone. The resolver is recorded as `resolver_person_id`, and a reject that loses the race to another answer is a 409. `GET /audit/reliability` is the principal's alone (403 otherwise), because it counts private decisions too. 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/describe`, `POST /delegation/voice/signature`, `PUT /delegation/inbox`, `POST /delegation/inbox/check`, `GET /delegation/replies`, `GET /delegation/mail?thread_id&message_id` (one email in the caller's own mailbox: their words without the quoted mail, attachment names, what they last wrote in the conversation, a mailbox link, the open reply card), `POST /delegation/mail/reply` `{thread_id, message_id}` → `{decision_id}` (a reply card on request, the conversation's open one when there is one; 409 with a code when it can't), `PUT /delegation/replies/{id}/text`, `POST /delegation/drafts/{id}/send`, `PUT /delegation/replies/{id}/recipients`, `POST /delegation/replies/{id}/answer`, `POST /delegation/replies/{id}/change`, `GET /delegation/actions`, `GET /delegation/invites`, `PUT /delegation/handle-it`, `PUT /delegation/disclosure`, `PUT /delegation/training`, `DELETE /delegation/learned/{id}`, `GET /delegation/handled`, `PUT /delegation/team` | Act as me — the **caller's own** delegation only; nobody sets it for anyone else. It answers the principal, and a team member once the owner lets them; anyone else gets 403 `not_available_yet`. `GET /delegation` returns `{enabled, gmail: {status, message, email, connect_command, outlook_connect_command, provider}, inbox: {enabled, status, message, watch_since, last_poll_at, checking}, handle_it: {enabled, mode, available, sent_today, lead, lead_available}, training: {replies, follow_ups, actions, drafts, learned}, disclosure: {enabled, handle_it, approved_sends, line}, team}`, where `team` is the owner's switch for the principal while `DELEGATION_TEAM_MEMBERS` allows it — `{enabled, members: [{person_id, name, enabled, inbox, drafts_30d, sent_30d}]}`, counts only — and `null` otherwise. `PUT /delegation/handle-it` takes `{enabled?, mode?}` (`mode` is `careful`, `balanced` or `bold`; anything else is a 422 `bad_mode`) from a caller the API knows is that person — 403 `not_yours`, 409 `caller_signing_required` with only the shared secret — and turning it on needs Act as me and Draft replies to my inbox on (409 `act_as_me_off` / `inbox_off`); `GET /delegation/handled` returns `{replies: [{decision_id, sent_at, to_name, to_email, subject, body, open_questions, gmail_link, source, summary}]}`, the caller's replies and follow-ups (`source` `follow_up`) sent on its own in the last 7 days, and the meeting invites it accepted on its own (`source` `invite`, `subject` the meeting's title, `summary` one line such as \"Accepted Dana's Pilot review, Wed 21 Oct, 14:30\"); a card on `GET /delegation/replies` carries `source` the same way, `can_allow` while Replies (Follow-ups, on a follow-up) is in training, and `learns_style` while Drafts is. `PUT /delegation/disclosure` takes `{handle_it?, approved_sends?}` (any other field is a 422), the caller's own switches for the AI line on replies sent as them (`disclosure.enabled` is the install's `AI_DISCLOSURE`); turning one on needs no signed sign-in, turning one off does (409 `caller_signing_required`), and a change is audited as `delegation_disclosure_changed`. `PUT /delegation/training` takes `{replies?, follow_ups?, actions?, drafts?, actions_on?}` (any other field is a 422; `actions_on` is Suggested actions On, and `actions` and `actions_on` set true clear each other) and returns the `GET /delegation` shape, whose `training` carries `actions_on` too; putting Replies or Follow-ups in, or Suggested actions out of training or On, needs no signed sign-in, anything else does (409 `caller_signing_required`), and putting Replies or Follow-ups in turns Take the lead as you off (`PUT /delegation/take-the-lead` on answers 409 `in_training` while they are). `training.learned` is `[{id, label, setting, example, uses, created_at}]`, what the caller allowed or kept in training (`setting` `replies`, `follow_ups`, `actions` or `drafts`; the kept example, or \"\"); `DELETE /delegation/learned/{id}` removes one of the caller's own (404 for anyone else's). `PUT /delegation/team` takes `{enabled}` from the principal alone (403 `principal_only`; 409 `not_available` when the install doesn't allow it). The Gmail `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), write it from the caller's own description (`POST /delegation/voice/describe` with `{description}`: one model call applies their words to the profile they have and returns it with a short `sample_reply`, saving nothing, so they review it and save it with `PUT`; a 409 `empty`, `too_long`, `in_progress`, `too_many` past 10 an hour or `no_profile`; no mailbox needed), 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 mailbox isn't connected, it refuses the sign-in or the check itself fails (`gmail_error`), and a 502 `gmail_error` when reading the signature fails. On an Outlook mailbox it is a 409 `signature_unavailable`, since Outlook gives apps no signature to read, and the stored one is left alone. 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 caller is read through `api/caller.py`, as on every principal-only route). `PUT /delegation/inbox` takes `{enabled}` and turns **Draft replies to my inbox** on or off, returning the same shape as `GET /delegation`: on needs Act as me on (409 `act_as_me_off`) and the mailbox connected (the Gmail codes above, which keep their names for an Outlook mailbox too), and turning Act as me off turns it off too. `POST /delegation/inbox/check` starts a scan now in the background and answers 202 with the `inbox` state (409 `inbox_off` or `in_progress`). `GET /delegation/replies` returns `{cards: [...]}`, the caller's open reply cards from the database alone (no Gmail call): the decision id, the sender's name, address, relation and whether it was verified, the subject, when it arrived, what they wrote, a one-line `gist` (what they asked and what the draft says, written with the draft and brought up to date when an answer rewrites it; empty on an older card), the draft's recipients, subject and body, `open_questions`, `flags` and a Gmail link built from a fixed prefix. **Send** is `POST /decisions/{id}/approve`: it sends the card's draft exactly as it is in Gmail, after checking again that the caller is its owner — which on a server needs signed callers (409 `caller_signing_required` otherwise) — that both switches are on (`inbox_off`), no client slot is active (`client_slot`), the Gmail is connected (the Gmail codes), the draft is still there and unanswered (`draft_gone`, `you_replied`) and its recipients are allowed (`no_recipients`, `too_many_recipients`, `executive_recipient`, `not_from_you`). Recipients that changed, or a newer message in the thread, answer 409 `{code: \"confirm\", message, reasons, recipients}`; approving again with `edits: {recipients: <the list shown>, thread_moved_on: true}` is the second yes. Send with the *on its own next time* tick adds `edits.allow: true`: 422 `cant_allow` unless Replies (Follow-ups, on a follow-up card) is in training, 409 `learned_full` when their list is full, both before anything is sent; `edits.example: true` keeps a draft edited in the mailbox as how they write to that person while Drafts is in training. A draft edited in Gmail between those checks and the send is not sent (`draft_changed`). A double tap sends once (`already_handled`); Gmail refusing answers 429 `rate_limited` or 502 `gmail_error` with nothing sent, and a send Gmail didn't confirm answers 502 `send_unconfirmed` and is settled by the next inbox scan. Dismiss is `POST /decisions/{id}/reject`. `GET /delegation/invites` returns `{cards: [...]}`, the caller's own meeting invite cards (`delegation_invite`, Read my calendar on): `decision_id`, `status`, `created_at`, `from_name`, `from_email`, `relation`, `title`, `when` (in the workspace time zone), `start`, `end`, `all_day`, `clashes` (busy times only, `\"14:00–14:30\"`), `clash_checked`, `can_answer` (false for a sign-in that reads but can't answer the calendar; then `connect_command`), `can_allow` (Replies in training) and `waited_because`. **Accept** / **Decline** is `POST /decisions/{id}/approve` with `edits: {answer: \"accept\" | \"decline\"}` (accept is the default; `allow: true` with accept for the *Accept from them on its own next time* tick), on the same caller checks Send uses (403 `not_yours`, 409 `caller_signing_required`); 409 `calendar_write_needed` when the sign-in can't answer (the card stays), `gone` when the event left their calendar, `expired` once the meeting started, `already_handled`; 502 `calendar_error` leaves the card for another try. **Dismiss** is `POST /decisions/{id}/reject` and answers nothing. `GET /delegation/actions` returns `{cards: [...]}`, the caller's own approval cards (`delegation_actions`): the decision id, when it was made, a one-line `why`, and each action's `index`, `kind` (`invite`, `message`, `add_contact`), `summary` and `text` (a message as it will be sent, or a meeting's description). **Approve** is `POST /decisions/{id}/approve` with `edits: {only: [indexes]}` (and `allow: true` for the *Do this on its own next time* tick while Suggested actions is in training: 422 `cant_allow` otherwise or when nothing on it can be allowed, 409 `learned_full`; a card carries `can_allow`); it needs the card's own person signed in (403 `not_yours`, 409 `caller_signing_required`), Act as me on (409 `act_as_me_off`) and a card under a week old (409 `expired`), runs once (409 `already_handled`), and returns the decision with `final_payload_json.results`: per action `done`, `waiting` (sent to whoever approves meetings), `failed` with why, or `skipped`. Every change writes a private audit row. |\n| `history` | `GET /memories/history` (`?q=`), `PUT /memories/history/settings`, `PATCH`/`DELETE /memories/history/{id}`, `POST /memories/history/{id}/forget-conversation` | Always in the loop: the **caller's own** notes and switches only, resolved as for Act as me (a signed-in person on the roster, or the principal under local login; otherwise 403 `sign_in_required` / `not_on_roster`). `GET` returns `{notes, reply_notes, retention_days, effective_retention_days, company_retention_days, retention_choices, can_keep_notes, can_note_replies, can_set_company_retention, share_work_style, can_share_work_style}` (`can_keep_notes`: a team member on the People list may turn notes on; `can_note_replies`: they can use Act as me, so email replies are noted too; `share_work_style`: their own \"Share my work style with the team\" switch, `can_share_work_style`: a team member in a team workspace). `PUT` turns notes on only for someone who may keep them, and `share_work_style` on only for someone who may share it (403 `not_available` for either; turning either off always works), takes a person's retention only when shorter than the company's (422 `invalid_setting`), and the company retention only from the principal (403 `principal_only`). `PATCH` pins or corrects a note; `DELETE` forgets it; `forget-conversation` is \"Don't remember this\". A note that isn't the caller's is 404. Every change is audited privately to its person. |\n| `reflection` | `GET /memories/reflection` (`?person_id=`), `DELETE /memories/reflection/misses/{id}` | Learning: the turns the conversation review graded a miss (`memory.chat_review`), with the person's words, the reply, the tools run, what they wanted instead, the `kind` (`company` / `product`), the finer `cause` (null when the grade gave none) and the signals, plus `weeks` (`{week, graded, misses}` per ISO week, newest first) and `sees_everyone`. The caller is resolved as for `history` (403 `sign_in_required` / `not_on_roster`); each person sees their own, the principal those from chats `chat._session_access` lets them open (a teammate's own web chat or DM and a mail-private conversation stay their owner's; channels and groups are open), or one person's with `?person_id=` (a teammate naming someone else gets 403 `not_yours`); the weekly counts carry no words and are not filtered. The same response carries `lessons` (`memory/lessons.py`: live first, then retired, each with `shown`/`fine_after`/`miss_after` and `retired_reason`), filtered by the same rule, and `DELETE /memories/reflection/lessons/{id}` retires one (204; 404 for a lesson the caller may not see, already retired, or missing). `DELETE` forgets one miss (`is_principal_or_self`; 404 `not_found` otherwise) and writes a `chat_review` audit row. Each miss also carries its nightly replay (`memory/replay.py`): `replay_state` (`open` / `closed` / `evidence`), `replayed_at`, `closed_at`, `replay_notes`; and the response carries `replay` (`{misses, would_pass, evidence, last_run_at}`: of the caller's visible misses from the last 30 days, how many would go right today). |\n| `notifications` | `GET /notifications/settings`, `PUT /notifications/settings` | Settings → Notifications: the **caller's own** settings only, resolved as for the notes (a signed-in person on the People list, or the principal under local login; otherwise 403 `sign_in_required` / `not_on_roster`). `GET` returns `{quiet_hours: {enabled, start, end, days}, delivery, urgent_through, timezone, effective_timezone, held_count, gets_briefs, updated_at}` — `days` is `every_day` or `weekdays`, `delivery` `instant` or `digest`, `timezone` the zone they chose (`\"\"` for the workspace's), `held_count` how many messages wait for their quiet hours or brief (counted, never listed), `gets_briefs` whether they are the principal. `PUT` takes `{quiet_hours, delivery, urgent_through, timezone}` and replaces them (extra fields, equal start and end, a bad time or an unknown zone → 422); switching `digest` → `instant` makes what waited for the brief go now. Audited as `notification_settings_changed`. See Org. |\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), plus `scripts`: how many `run_script` scripts ran (and worked, and in workflows), the tool calls they made, their time, and `turns_avoided` — an upper bound on the model turns those calls would otherwise have needed (each call past a script's first) — and `python_jobs`: how many Python jobs ran (and worked, ran a kept Custom tool, took a chat attachment), their time, CPU, largest peak memory and bytes in and out, and the tokens and charge of the turns that ran one. The Token usage page shows it as a Scripts section. 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 usage totals leave them out. Once a principal is on the roster, anyone else reads only their own rows (a teammate's own turns, their Act as me work) in the list, by id and in a session, and the principal reads those as actions only — what was done, when and in whose conversation, with the text, details and `full` left out, and no text search over them; any other row's id is a 404, and a session shows only the rows the caller reads. |\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. Only `/health` is unauthenticated; `/health/honcho` sits behind the gate like everything else, because the exemption is an exact-path set. `/health` also carries `google_tools_missing`, the pinned Google tools startup priming could not find: `[]` once it has checked and they are all there, a list of names when a workspace-mcp rename or the configured services and tool tier left one out, and `null` for no answer — Google Workspace is not configured, or the probe has not finished or it failed. Only `[]` asserts they are present. It also carries `gateway`, the MCP gateway's state from its supervisor (`orchestrator.gateway_boot`): `state` is `off` (MCP not enabled), `no_servers` (enabled, the config names none), `starting` (an attempt is running), `up` or `down` (every attempt so far failed; `next_retry_at` is the next one), with `attempts`, `up_since` and `email_poller` (whether the poller that rides on the gateway runs); the failure's own text stays out, since the route is open to anyone, and goes to the log and the owner's notice on Home. A hosted instance whose gateway never came up used to answer `ok` here with no email going out or in. Only `[]` asserts the tools are present, so a probe that died cannot read as healthy; Setup status says which of the three `null` means. |\n| `version` | `GET /version` | The running version, the latest release on GitHub and `update_available`, for Settings → About. The GitHub answer is cached 6h, only a semver `tag_name` is used and the release link is built from it; `UPDATE_CHECK_ENABLED=false` skips the call and still returns the running version. No in-app updater: upgrading is host-side (`docs/deployment.md#upgrading`). |\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 mailbox (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. With `CONFLUENCE_SYNC_ENABLED` it bootstraps the `confluence_sync_scan` heartbeat the same way; that sync is run by hand with `openexecutive sync-confluence` / `purge-confluence`. 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\\|onedrive\\|notion}/sync`, `GET /documents/{drive\\|onedrive\\|notion}`, `GET /documents/{drive\\|onedrive\\|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`, `/documents/onedrive` and `/documents/notion` list synced files from the sync state (`{enabled, last_run, last_error, files: [{id, name, url, modified_at, synced_at, indexed}]}`; a Drive row also carries `unreadable_reason`, why a file with `indexed: false` has no text — e.g. a scan OCR could not read — or null); `/documents/{drive\\|onedrive\\|notion}/{id}` returns the stored text (a OneDrive id is `<drive id>:<item id>`) 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 (every sync holds a per-process run lock, so a manual run never overlaps the heartbeat; the route also keeps its own started task per source and re-checks just before starting one, so two simultaneous requests start one tick, not two), 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. The upload is streamed to disk 1 MB at a time and refused with a 413 once it passes 50 MB, and the file is parsed in a short-lived child process (see the RAG section), so a large document does not stay in the API process's memory. A Word or Excel file that cannot be parsed, or whose parse runs out of time, is a 422 with a readable reason. When every parser is busy, the response is a 503 with `Retry-After`. |\n| `executive` | `GET /executive/status`, `POST /executive/pause`, `POST /executive/resume`, `GET`/`PUT /executive/outside-content` | 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, name}` — `held_actions` counts due `pending` rows that fire on resume, and `name` is the Executive's name (`EXEC_DISPLAY_NAME`), which the web chat shows over its replies. `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. `GET /executive/outside-content` returns `{mode, channels, channel_ids, can_change}` for the owner's safety level, \"When should I check with you?\" (`ask` Careful, `outsiders` Balanced or `trust` Hands-off; `orchestrator.outside_mode`): `channels` maps each channel set apart to its own level, and `channel_ids` lists the channels a level can be set on. `PUT` with `{mode, channels?}` changes it for the principal only (403 otherwise; an unknown channel or level is a 422): a channel given a level is set apart, one given `null` follows `mode` again, and channels left out keep theirs. A change writes an `outside_content_mode_changed` audit row. |\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/describe`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. `POST /watchlist/describe` `{text}` drafts a watch from a sentence (one forced tool call on the utility-fast model, `monitoring.describe`; the company profile's name, competitors, vendors and tickers ride in the user turn) and saves nothing: it returns the create fields (`slug`, `signal_type`, `target`, `display_label`, `trigger`, `cadence`, `mode`, `severity_floor`, `severity_ceiling`, `notes`) plus four plain lines (`watching`, `tell_you_when`, `how_often`, `how_loud`) written by code from those fields, after the create route's checks (registered kind, cadence, severity, the URL guard, the rss feed check, a free slug); 422 with a plain reason when it can't be a watch, 429 past 30 drafts an hour, 502/504 when the model fails. `GET /watchlist/{slug}` also returns `noise` `{recent_alerts, recent_dismissed, noisy}` (its last 8 alerts, noisy at 6 dismissed, `monitoring.noise`), and `PATCH` takes `quiet_noise_nudge: true` to stop that question for the alerts so far. `display_label` on create maps to the adapter's label key for every kind. 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`, `POST /workflows/runs/{run_id}/rerun`, `GET /workflows/tools/search?q=`, `GET /workflows/tools/describe?names=` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. A workflow with a step that sends email as its creator (`oe__send_email_as_me`) or reads their mail or calendar (`oe__search_my_email` and the other reads, `delegation.workflow_reads`) can be created, changed (`PUT`, save-edit) or switched on (`activate`) only by that creator, verified as Send on a reply card is; anyone else gets a 403 (`delegation.workflow_email.save_refusal`), as does a save of one that reads and also lists a tool a run may not use after reading mail. `POST /workflows/{name}/runs` answers 403 to anyone but the creator of a workflow that reads their mail. `rerun` queues a failed scheduled run (a department check-in, a saved workflow on a cadence) once more, due now (see Scheduler); the principal may, and for a saved workflow the person it delivers to; 409 for a run that did not fail, one started from `/jobs` (\"Start this one again from its page\") or one already queued again. 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. A run started by hand (this endpoint, or `run_workflow` / research in chat) records its starter as `owner_person_id` and is theirs alone: `GET /workflows/runs` lists the team's (scheduled, no owner) runs plus the caller's own and the ones waiting on them, and `GET` / `DELETE /workflows/runs/{run_id}` and `POST /workflows/runs/{run_id}/decision` are a 404 for anyone else's, the principal included. A signed-in email that is on nobody's People entry cannot start one (403), and a run whose starter can't be read is refused (503); its steps read and draft documents as the starter only. `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`, `background` (true for the system-run built-ins the UI files under “System”) and `quick` (true for a Quick workflow, one per playbook nothing else follows, named `quick_<playbook>`). 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| `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). Peer memory is each person's own: the overview holds only the caller's entry (none for a caller off the roster; `conclusion_total` counts only theirs), the principal included, and `/conclusions` for anyone but the caller 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/understand`, `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/revise`, `/onboard/interview/{id}` (GET resumes, DELETE starts over), `/onboard/interview/commit` | Conversational company setup. `understand` and `start` take multipart `description`, optional `files` and an optional `website` the server reads itself (a non-address is a 422; an unreadable site is no pages, never an error); `start`'s response lists the pages read in `website_pages`, and the draft's profile carries `website`. The `onboarding_interviewer` agent asks up to four quick questions (a question response carries `question_options`, suggested answers to tap), then emits a draft profile + people + `draft_goals` (each `{title, target, owner_name, department_title}`) + departments only when the user listed people by department. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). `revise` changes one earlier answer (0 = the description) and runs the interview again from there. `commit` takes the reviewed `goals` too (422 when one names a person or department not in the draft) and saves them with owners, additively. It 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/edit`, `POST /workflows/designer/message`, `POST /workflows/designer/draft`, `GET /workflows/designer/{session_id}` | The conversational New workflow wizard, and editing a saved workflow by conversation. `/edit` (`{name}`) opens a session on a saved custom workflow with no model call: the stored definition is the starting draft, and every response then carries `editing` (its name) and `original` (the stored definition as the session opened on it); drafts keep that name and its on/off state whatever the model writes (404 for an unknown workflow). The UI saves one with `POST /workflows/custom/{name}/save-edit` (`{session_id, definition}`): the server saves the session's own draft, never a client-sent body, and only when it equals the `definition` the user reviewed (a later message is a 409, so the click saves only what was shown); it re-validates it, keeps the stored on/off state, and writes only if the stored workflow is still the version the conversation opened on — otherwise 409, as it is for a session about another workflow or one with nothing drafted yet. It sits under `/workflows/custom` so anything that limits writes to custom workflows covers it too. 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| `python_jobs` | `GET /python-jobs/{job_id}/{name}` | A result file a Python job (`run_python_job`) wrote, the principal's alone (403 otherwise), served as a download (`Content-Disposition: attachment`, `Content-Security-Policy: sandbox`, `nosniff`, `Cache-Control: no-store`); 404 for a bad id or name or a file past its 7 days. |\n| `saved_tools` | `GET /saved-tools`, `GET\\|PUT /saved-tools/{name}`, `POST /saved-tools/{name}/rollback` | The scripts the Executive saved as tools (Settings → Advanced → Saved tools), the owner's alone (403 otherwise). The list gives each tool's name, description, on/off, current version, `kind` (`script` or `python`, a kept Python job) and the tools it calls, plus whether `SAVED_TOOLS_ENABLED` is on; the detail adds the script, every version and the last 20 runs. `PUT {enabled?, workflows?, version?}` turns one on or off (off also turns it off for workflows, so turning it back on never re-arms unattended runs), and turns the named `version` — the one the owner looked at, never whatever is current by then — on for workflows (or workflows off); a Python tool never turns on for workflows (409) — turning workflows on lets more run unattended, so it needs a request tied to the owner (signed sign-ins or local login, as Take the lead's switches do; 409 otherwise); `rollback {version}` makes that version the one that runs. Both are audited as `saved_tool_changed`. The Executive saves tools itself through `run_script`; there is no create route. |\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| `auth` | `GET /auth/me` | `{email}`: the email the request is made as (`api.caller`, lowercased; `\"\"` when it names no one), nothing more. On the host list, so a host's own screens can warn when the session signed in here is someone else's. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. `POST /fixtures/reset` leaves no departments, like a new install (`departments_seeded` is always 0). |\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`, `POST /webhook/slack` | Inbound integration callbacks (self-verified). `/webhook/slack` answers 503 unless `SLACK_SIGNING_SECRET` is set. |\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, answered as the verified caller (`api.caller`) by the web app's rules. See the MCP Server section. | A card the Executive left for something asked in chat (`app_action`, `orchestrator/app_control.py`) is its person's alone too: its payload holds `action`, `id`, `value`, `title` and the `card` line shown; **Confirm** is `POST /decisions/{id}/approve`, which runs the action through the route its button calls with that request (a refusal comes back as that route's status and words, and the card is marked `failed`), and a card older than a day is turned down with 409.\n\n**What it does for you** (`api/routes/may_do.py`): `GET /what-it-may-do` is read-only. It returns `{paused, sections}`, three sections in order (`as_you`, `executive`, `departments`), each `{key, title, available, unavailable, notes, rows, footer, goes}`, and each row `{id, what, outcome, then, why, setting, items}`: `outcome` is `goes`, `waits`, `always_waits`, `drafts` or `off`, and `setting` names where to change it (`act_as_me`, `handle_it`, `take_the_lead`, `pause`, `department:<slug>`, or empty). `as_you` is the caller's own (`available` false, with why, when they can't have Act as me); `executive` is the principal's alone (`available` false for anyone else); `departments` is everyone's. Any team member on People may call it; a contact, someone not on People, or a request with no caller outside local login gets 403. See Delegation → What it does for you.\n\n**How far it goes as you** (`api/routes/delegation.py`): `PUT /delegation/reach` takes `{step}`, one of `off`, `when_asked`, `inbox`, `careful`, `balanced`, `bold`, `everything`, and answers the caller's delegation state as `GET /delegation` does. Going down turns the switches above the step off, highest first; going up runs each switch's own route in order (`PUT /delegation`, `PUT /delegation/inbox`, `PUT /delegation/handle-it`, `PUT /delegation/take-the-lead`), so the first refusal (409 `gmail_not_connected`, a signed sign-in missing, `in_training`, 403 for Everything when not the owner) stops it at a whole step. See Delegation → How far it goes as you.\n\n**Take the lead** (`api/routes/take_the_lead.py`): `GET /take-the-lead` returns the As the Executive switch, its six Ask first switches (`{kind, label, hint, on}`, the hint a plain line on what each one catches), the company's rules, whether this server can tie a change to the owner (`available`), and whether the Executive is paused. `PUT /take-the-lead` takes `{enabled?, ask_first?}`, and `POST /take-the-lead/rules` / `DELETE /take-the-lead/rules/{id}` add or remove a company rule (`{kind: person|domain|words|amount, value}`, 422 on a bad one). All four are the principal's alone (403). Anything that lets more happen on its own (turning it on, turning an Ask first off, removing a rule) needs a caller the API can tie to them (`delegation.verified.caller_refusal`, else 409). `GET /today/activity` adds `took_the_lead` rows (what Take the lead did, named, not quoted) and, for the caller alone, `sent_as_you` rows for what Handle it for me sent as them (and the meeting invites it accepted as them, \"Accepted Dana's Pilot review, Wed 21 Oct, 14:30\") and, for the principal, one `contacts_kept` row a day the contact keeper changed something (`detail` like \"2 added, 1 updated\"). Under `/delegation`: `PUT /delegation/take-the-lead {enabled}` is Take the lead as you (the owner's only for now; turning it on turns Handle it for me on), and `GET|POST /delegation/take-the-lead/rules` and `DELETE …/rules/{id}` manage the caller's own rules. `HandleItOut` gains `lead` and `lead_available`. A `take_the_lead_action` decision is approved or rejected through the existing `/decisions/{id}/approve|reject`. Training: the response also carries `training` (In training: everything waits unless allowed), `learned` (`{id, label, feature, example, uses, created_at}`: what it was allowed, the edit kept as an example by field) and `suggested` (`{key, label, approvals}`); `PUT` takes `training?` too, and leaving training while on needs the same provable owner as turning it on. `POST /take-the-lead/learned {key}` allows a current suggestion (404 for anything else; provable owner), `DELETE /take-the-lead/learned/{id}` makes it ask first again. `learned` also lists the owner's own Act as me senders (`feature` `act_as_me`), never anyone else's, and Remove works on those too. On a `take_the_lead_action` card, `POST /decisions/{id}/approve` takes `edits.input` (the card's editable fields, 422 for any other; the principal's alone, 403 for an area approver) and `edits.allow: true` (a training card only, 422 otherwise; the principal from a provable request, 403 otherwise), finishing `approved_with_edit` when a field changed.",
"mermaid": null,
- "generated_at": "2026-10-26T18:04:19.435654+00:00"
+ "generated_at": "2026-10-27T18:30:00Z"
}
diff --git a/packages/core/openexecutive/architecture/prebuilt/delegation.json b/packages/core/openexecutive/architecture/prebuilt/delegation.json
index a95784bb..5a0f486b 100644
--- a/packages/core/openexecutive/architecture/prebuilt/delegation.json
+++ b/packages/core/openexecutive/architecture/prebuilt/delegation.json
@@ -1,7 +1,7 @@
{
"section_id": "delegation",
"title": "Act as Me (Delegation)",
- "markdown": "The **delegation** module (`openexecutive.delegation`) is **Act as me**: the one place the Executive writes *as* a person instead of as itself. Everywhere else it has its own Google account and bots and signs as itself. Here — when the person asks, or, with a second switch, for mail in their inbox that needs them — it writes an email in their voice and saves it as a **draft in their own mailbox** — Gmail or Outlook — for them to review and send. The one thing it ever sends is one of those inbox drafts, exactly as it is in their mailbox: when the person taps **Send** on its card, or, with a third switch, **Handle it for me**, on its own when plain-code rules allow it (below). A draft chat wrote as them goes only when they tap **Send** under it in the chat (below); no tool sends. A workflow its creator saved can also write as them: a draft for them to send, or, when they chose **Send as me** when saving it, sent (below). The principal can turn it on for themselves, and so can each team member once the owner lets them. It is off by default, and off changes nothing: the prompts, tool lists and prompt caches are byte-identical to an install without it.\n\n## Who can have it, and when it is offered\n\n`delegation.settings.can_delegate(person)` is the single rule for who may turn it on: the principal (a non-archived team member flagged `is_principal`), and any other non-archived team member — never a contact — once team members may have it (`team_members_enabled`). That takes two things: the install allows it (`DELEGATION_TEAM_MEMBERS`, default off, which offers the owner the switch) and the owner turned on **Let team members use it** (`PUT /delegation/team`, principal only, one row in `delegation_team`). Turning the owner's switch off takes it away from every team member from their next message, and their inbox watchers stop at their next check; their own switches, drafts and cards are kept. Everything is keyed by `person_id`. A person turns it on for themselves (`PUT /delegation`); nobody turns it on for anyone else. The setting is one row per person in `delegation_settings`, and a missing, unreadable or zero row all mean off.\n\nAt the start of every chat turn (`Executive.stream_chat` and the committee path) `pin_turn_delegation(session, speaker_text)` runs next to the workspace-mode pin and records a `TurnDelegation` on the session. `ghostwrite_email` is **offered** only when all of these hold:\n\n- the speaker may have it and turned it on — read fresh every turn, so turning it off applies from the next message;\n- the speaker is on a surface that verified it is them — the principal through `people_tools.is_principal_on_verified_surface`, a team member through `teammate_on_verified_surface` (the web app signed in, their own Slack or Discord, never an email turn) — and a web turn also carried a signed-in caller (`Session.web_caller_signed_in`, set from `x-caller-email`) or runs under local login — a request with no caller header is not a sign-in and never gets it (whoever holds the shared secret is trusted as the UI proxy that stamps that header, as on every principal-only route);\n- the conversation is private to the speaker: the web chat, a Slack or Discord DM, a verified private Telegram chat, or a chat its channel adapter verified the sender of and marked private (`Session.speaker_verified` + `Session.private_chat`) — never a shared channel or thread, where the draft's preview or the matching threads would be posted for everyone and other people's messages sit in the model's context;\n- the turn is neither unattended (the scheduler's proactive run) nor private to the principal (the email poller's turns), so inbound text can never reach it. The MCP server, workflows, reflection and research never carry it at all.\n\nThe mailbox connection is deliberately **not** part of the offer: the handler checks it on every call and says how to fix it, so the cached tool prefix never flips when a token lapses. The pin lives in a context variable for the turn's task as well as on the session, so two turns running at once on one session (a second browser tab) each read their own. It also carries the speaker's own words for the turn (a new email may go to an address they just typed — the turn's message joins the history only once the turn ends), a per-turn draft count, and `touched_mail` (see Privacy). `own_words` reads those words back for every own-words check (addresses here, facts and task assignments elsewhere): it first removes the hydrated `<outbound_reply_context>` backstory by its exact, anchored shape, so a look-alike closing tag quoted inside it cannot pass the rest off as the speaker's, then drops other adapter tag blocks, and returns nothing for a message carrying an attachment.\n\n## The tool: `ghostwrite_email`\n\nIt lives in its own registry (`orchestrator.delegation_tools.DELEGATION_TOOLS` / `DELEGATION_TOOL_HANDLERS`), **never** `_ALL_SKILL_TOOLS`, so no other toolkit can carry it. On a turn it is offered to, the agent loop adds it to the pool *before* the sort and builds that turn's handler map from both registries; on any other turn a call to it is an unknown tool. The handler re-checks the pin and the surface anyway, then:\n\n1. **Caps** — at most 5 drafts per turn, and `DELEGATION_MAX_DRAFTS_PER_DAY` (default 50, at most 1000) per person per UTC day, shared with the inbox watcher (`delegation.caps`). It is counted from `delegation_drafts`, one row of ids per draft saved from either place, with a count kept in the process as a floor in case a row was lost. Each slot is taken before the first await — a round's tool calls run concurrently, so otherwise every call in it would pass the caps before any counted — and handed back if nothing was drafted. If the rows can't be read it refuses rather than guess.\n2. **Marks the turn** — sets `TurnDelegation.touched_mail` *before* its first read of the mailbox.\n3. **Checks the mailbox** — `gmail_status` asks Google or Microsoft whose mailbox the credential opens and compares it with the person's People email, on every call: a roster email can change, and a client slot swaps the roster.\n4. **Finds the thread** — by `thread_id` (checked against the mailbox's own id shape), or a Gmail-style search (`find`; on Outlook, words, `from:`, `to:`, `cc:`, `subject:` and `newer_than:` are kept and other Gmail operators dropped). Several matches return `{status: \"choose\", candidates}` (subject, sender and date — no message text) and draft nothing; none returns `not_found`.\n5. **Sets the recipients in code**, never from the model. A reply goes to the last inbound message's `From` — never its `Reply-To` (a different one is flagged `reply_to_ignored`) — with the thread's other recipients only on `reply_all`. A new email or a forward may go to any well-formed address: it is only a draft, waiting in their own mailbox, where they see who it is to before they send it. An address that is neither on the roster (contacts only when `contacts_reachable_now()`) nor typed by the speaker this turn comes back in `not_in_people`, and the Executive names it for them to check (`delegation_tools.not_in_people`). Mailing-list mail, a thread they replied to last and a reply-all trimmed to 10 recipients are flagged. An address inside a block an adapter added to their message (the backstory hydrated into a DM) is not one they typed, and when the message carries an attachment — a document's inlined text, or a note naming the file — none of its addresses count as typed: neither has an end mark, and a filename is chosen by whoever sent the file, so such an address is named back to check.\n6. **Writes it** (the ghostwriter, below) and saves it with the mailbox client's `create_draft` (Gmail: threaded with `In-Reply-To`, `References` (whole message ids: when the chain is too long for one header the oldest after the thread's first go, never the parent) and `threadId`, and stamped `X-OE-Ghostwritten`; Outlook: Graph's `createReply` on the message it answers, then the text and recipients, and a named property marking it).\n\nThe result is `{status: \"drafted\", draft_id, gmail_link, to, cc, subject, preview, flags, open_questions, note}`, plus `not_in_people` and `check_address` when a recipient needs checking. The link (`gmail.mailbox_link`) is built server-side from a fixed prefix — the thread in Gmail, the draft itself in Outlook on the web — and the note tells the model the preview is the person's draft, to be treated as data. The chat shows an action chip — \"Drafted an email as you to … — in your Drafts\" — that opens it, and only a link under `MAILBOX_LINK_PREFIXES` is ever linked. A sincere \"are you an AI?\" in the thread comes back as an open question for the person to answer themselves.\n\n## Reading their mailbox\n\nFive read-only mail tools ride with `ghostwrite_email` in the same registry (`orchestrator.mail_read_tools`), so they are offered, re-checked and fenced exactly as it is: `search_my_email` (a Gmail-style search through the client's `search_threads`, or with no query the threads that reached their inbox in the last few days through `inbox_message_ids` + `get_message`), `read_my_email` (one thread's last 10 messages, each sender's new text only, drafts left out, with the files attached to them listed by message id and index), `read_my_email_attachment` (one of those files as text: PDF, Word, Excel, CSV or text, up to 20 MB, a scanned PDF converted) and `my_email_awaiting_reply` (their own sent mail from the last 14 days, to at most 10 people besides the Executive, that is still the last message in its thread). They change, label, draft and send nothing.\n\nThe fifth, `my_email_read_before`, lists the threads `read_my_email` opened for the same person before, in this conversation or an earlier one, so a later conversation can open the same email again instead of asking them to search for it. It keeps where, never what (`delegation.mail_reads`, table `delegation_mail_read`): the thread id, its subject and first sender as one line each, the mailbox address it was read from and when, never a message's text, an attachment or a recipient. Rows are the person's own and are listed only from the mailbox open now, newest first, optionally narrowed by words in the subject or sender; anything older than 30 days is never listed and is deleted on the next write, at most 200 are kept per person, and turning Act as me off deletes them all. It opens the mailbox like the other reads, so it sets `touched_mail`, counts as a search, and returns its rows with the same data-not-instructions note. The Act as me addendum tells the model that these tools reach the person's mailbox while any Gmail or Outlook tools of its own account reach only the Executive's, to search theirs (never falling back to its own) for mail sent to them, and to reopen an email from before with `my_email_read_before` and `read_my_email`.\n\nEach sets `touched_mail` and marks the conversation theirs before its first read (`_open_mailbox`, shared with `ghostwrite_email`), so the lockdown below applies from its round on. Each is capped per turn on the pin: 10 searches (`my_email_awaiting_reply` counts as one), 20 thread reads and 5 attachment reads, the slot taken before the first await. In `read_my_email` every message someone else wrote comes back inside its own `<untrusted_content source=\"email\">` block (`content_trust.wrap_untrusted`, which defuses a closing tag in the text); the speaker's own messages — SENT and from their address (`threads.mine`), never a From header alone — are marked \"Yours\" outside any block. An attachment's text comes back in its own `<untrusted_content source=\"attachment\">` block (`attachments.format_attached_text`), parsed in an isolated worker (`knowledge.loader`); unlike a file sent to the Executive it is never added to the company's knowledge. The clients find an attachment by message and position and look its provider id up on each read (Gmail's changes per fetch): Gmail lists a message's files with the message (`MailMessage.attachments`, leaving out images the HTML shows in place), Outlook says only `hasAttachments` until `list_attachments` asks Graph (leaving out inline ones), and `attachment_bytes` reads one; an attached Outlook item or cloud link has no file to read. Results carry a note that subjects, senders and text are other people's words, data rather than instructions. The lockdown refuses tools, not the reply's own text, so what would carry that text out without a click is closed where it is shown: the web chat loads no image from another site, and bot replies go out without link previews (see Integrations).\n\n## Saving a file from their mail\n\nOne more tool rides with the reads: `save_my_email_attachment` (message id and index, as `read_my_email` listed the file) copies one attached file into the storage the Executive itself has connected and shares it with the speaker alone, so they get a link they can open or put in an app. Every call it makes is built in code (`orchestrator.mail_file_save`); the model picks only the attachment. The bytes come from the mailbox client's `attachment_bytes` and never pass through the model, any file type up to 20 MB, under a cleaned name (one line, no path or reserved characters, extension kept). The storage is the one the Executive's own mailbox runs on (`EMAIL_PROVIDER`) when the gateway has that server, else the other: Google Drive through workspace-mcp (`create_drive_file` with `base64_content` into a folder named \"From your email\" in the Executive's My Drive, then `manage_drive_access` granting the speaker's own address the reader role, `send_notification` off) or OneDrive through ms-365-mcp-server (`upload-file-content` into the same kind of folder in the Executive's own drive, with a name no recorded copy has, since an upload overwrites, then `share-drive-item` inviting only the speaker, `requireSignIn`, role `read`, `sendInvitation` off). The folder is always made by the save itself and its id remembered (`delegation_saved_folder`), never found by its name, since a folder someone else made and called that could already be shared with them; when the remembered one is gone or won't take the file, a new one is made and the old id stays recorded. Never a link share, a domain or anyone. Neither connected (or an eval's in-memory mailbox): status `no_storage`, and the model says so and offers to forward the email instead. Saves run one at a time, at most 10 a turn (`TurnDelegation.files_saved`), and the result is the status, the name, where it went and the link (`webViewLink` / `webUrl`); the chat chip says only that a file was saved, never the sender's file name.\n\nIt copies only when the speaker asked in their own words this turn: what they typed (`own_words`, no quoted backstory or attached file's text) must hold one of save, saved, upload or OneDrive, or Drive as a place (\"to my Drive\", \"in Drive\", \"Google Drive\"), checked before a slot is spent or the mailbox opened; otherwise it refuses (`not_asked`) and tells the model to ask them. It stays allowed after the turn read mail (`MAIL_TOUCHED_ALLOWED_TOOLS`): its gateway calls are admitted past the lockdown only as the very objects the handler built (`mcp_gateway.code_built_call`, for its seven Drive and OneDrive tools: folder create, file create or upload, the speaker's share, and OneDrive's `list-drives`), so a model's own `call_tool` on that turn is still refused, and every other gateway gate still runs on them (the acting account, URL fetches, sheet formulas, the share gates' roster check, writes kept to the Executive's own drives).\n\nEach copy is recorded before it is shared (`delegation.saved_files`, table `delegation_saved_files`: the person, the storage, the file id, its name and when; never content or the mail it came from), and the folder in `delegation_saved_folder`. The gateway reads that table on every Google Workspace and Microsoft 365 call: on a turn whose speaker is not the file's owner (the owner is the speaker only when Act as me was offered to them, so a shared chat, a workflow or the poller sees none), a call naming a recorded file id, raw or percent-encoded (OneDrive's `download-bytes` path is decoded by Graph), is refused, and a result, filtered against the table as it stands after the call so a copy recorded while a listing ran is caught too, loses each list entry or line naming one, with any id left masked. It matches ids as text, so a result that names such a file without its id (a notification quoting its title) still shows the name, and a copy someone makes is a new file. The folders are guarded harder, on every turn and for every speaker, the owner too: a model call whose arguments name any recorded folder id, or an OneDrive item path through the folder (`root:/From your email/x.pdf:` or `<folder id>:/x.pdf:`), is refused, so nobody can share, move, rename, copy, list or delete the folder from chat, and folder ids are dropped from or masked in every result; only the save's own code-built calls touch it. When a copy is made but its row can't be written, it is not shared, the save reports `failed` and logs an error, and the copy's id is hidden from every turn, the owner's included, for the life of the process. When the table can't be read, the file tools (`_FILE_TOOL_RE`: Drive, folder, file, Docs, Sheets, Slides and presentation tools, attachment bytes) are refused (fail closed) while mail and calendar run. The rows are kept when Act as me is turned off: the copies stay in the Executive's storage, and the rows keep them out of other people's turns.\n\n## Reading their calendar\n\nA third switch under Act as me, **Read my calendar** (`delegation.calendar`, table `delegation_calendar`: one row per person, absent or unreadable meaning off), lets the Executive read the person's own calendar. The principal's daily briefs read it too: `top_three.read_todays_calendar` merges it with the calendar the Executive reads, listing a meeting on both once. It rides on the same per-person sign-in as their mailbox: `calendar.events` on Google, `Calendars.ReadWrite` on Microsoft, added when they run the connect script with `--calendar` (`scripts/connect-own-gmail.py`, `scripts/connect-own-outlook.py`). The one change it ever makes there is answering a meeting invite (see Meeting invites below); a sign-in made earlier with read-only access (`calendar.readonly`, `Calendars.Read`) keeps reading, and the refresh asks Microsoft for whichever calendar scope the file was minted with. Those scopes are optional, so a mail-only sign-in keeps working for mail; the mailbox clients note the scopes the token refresh reports, and `list_events` raises `CalendarNotGranted` before calling the calendar when the scope is missing (or when the calendar answers 403). Only the person turns it on (`PUT /delegation/calendar`), only while Act as me is on and a one-hour read works; a sign-in without the calendar is refused with `calendar_not_granted` and the command to run. Turning Act as me off turns it off. Changes are audited privately (`delegation_calendar_changed`).\n\n`my_calendar` sits with the mailbox reads, offered and fenced the same way: it refuses while the switch is off (before anything is opened), then takes a search slot, opens the mailbox privately (`_open_mailbox`, so `touched_mail` and the lockdown apply: an invite's title is in the words of whoever sent it) and lists the events from `start` (default today) for `days` days (1 to 31) in the workspace time zone, recurring events expanded and cancelled ones left out: title, start, end, all-day, location, organizer, attendees (25 at most) and the person's own answer, each on one line, with a data-not-instructions note. Google's `events.list` on the primary calendar and Graph's `calendarView` (times asked for in UTC) are its only calls; it changes nothing and keeps nothing. The first week's brief also lists today's meetings from it on the principal's own delivery (see Today).\n\n## Forwarding and reminders\n\n`ghostwrite_email` also forwards: with `forward` (a thread id) and `to`, it drafts a forward of the thread's latest message, or of the earlier one `forward_message_id` names (the one with the files, say, when their own reply came after it), `intent` becoming the short note above it (the ghostwriter writes only the note; the forwarded email's subject, someone else's words, is never put in the intent). Recipients follow the new-email rule (`_new_recipients`: the roster, or addresses the speaker typed this turn). Gmail's draft quotes a forward header and the original's own words under the note and attaches the original's files, up to 10 and 20 MB (`FORWARD_MAX_FILES`, `FORWARD_MAX_BYTES`; any left off are flagged `attachments_left_off`); Outlook uses Graph's `createForward`, which keeps the original and its files, with the note as its comment and the body never patched. It is still only a draft.\n\nThe principal's new email or reply can also carry Google Drive files: `drive_files` takes up to 15 Drive file ids (`drive_attach.MAX_FILES`) (not with a forward; a team member is refused, since the files come from the Executive's own Drive). `orchestrator.drive_attach` sizes each one first and then downloads it with code-built `get_drive_file_permissions` and `get_drive_file_download_url` calls as the Executive's Google account (`mcp_gateway.code_built_call`, so the mail lockdown admits those exact calls). It takes the saved copy only from workspace-mcp's own anchored `Saved to:` line, exactly one, whose name ends in workspace-mcp's uuid (the answer echoes the Drive name first, which whoever shares a file chooses), names the attachment from that saved name, reads the bytes only from the tool download folders, removes the copy, and puts them on the draft under the forward cap's 20 MB. When the turn had read outside content before choosing them, the result asks the Executive to name each file so the person checks it. The file's text never reaches the model, so attaching is not an outside read. A file someone saved from their own mail, or a save folder (`delegation.saved_files`), is refused for anyone else, checked before and after the downloads and failing closed when that record can't be read, and a file that can't be fetched makes no draft. Gmail attaches them in `build_raw`; Outlook uploads each to the new draft (Graph's one-request upload, 3 MB a file, larger ones left off and flagged), and removes the draft if an upload fails. The result lists the attached file names.\n\n`remind_me(text, when)` (`orchestrator.reminder_tools`) rides with the same tools and checks, but opens no mailbox, so it never marks or locks a turn (`MAILBOX_TOOL_NAMES` are the ones that do). It stores the text once cleaned — one line, anything a chat app could turn into a link (a URL of any scheme, an address, a domain-like word, a host and port, an IP address) replaced with \"[link]\", at most 300 characters — with its time (stored in UTC) in `delegation_reminders` (5 a turn, 25 waiting, a year ahead, refused when the person has no channel). When it is due the scheduler sends that text to the person alone, as \"Reminder you set on <date>: …\", running nothing (see Scheduler); the Slack and Discord DMs it may go by turn link previews off. The chat chip shows the text as it will be sent. A reminder that comes due in the person's quiet hours or leave (when `OUTBOUND_RESPECT_QUIET_HOURS` is on) waits unclaimed and goes once they end, rather than being suppressed and lost. It is allowed after mail is read and in later turns of that conversation: it reaches only the speaker, as plain text. `schedule_followup`, which runs a turn with tools and is listed to everyone, stays refused there.\n\n## Approval cards\n\nA turn that read someone's mail may not message anyone, invite anyone or change the roster (see the lockdown above), yet what the mail asks for is often right. `propose_actions` (`orchestrator.action_card_tools`) leaves the speaker a card instead: up to five actions, each spelled out exactly as it will happen, done only when they tap Approve. It rides with the other Act as me tools and checks (`_writer`), opens no mailbox, and is allowed after mail is read because it does nothing on the turn.\n\n- **Kinds.** `invite` (a meeting with people on the roster), `message` (a direct message to someone on the roster, as written) `add_contact` (a new contact; the principal's cards only, since contacts are theirs) and `drive_files` (rename and/or move up to 25 Google Drive files; the principal's cards only). A `drive_files` action always waits for the tap, which is its approval: it runs each change as a code-built `update_drive_file` (`MCPGateway.tapped_drive_change`, `tapped_drive_call`), so the own-file check looks only at the folder it goes to, and a move takes the file out of the folders it was in. The card shows each file's current name and the folder's, read when it is proposed; when Drive isn't connected or a name can't be read, no card is made. A team member's card can't name a contact. Each action is checked when the card is made (`delegation.action_cards.check`) and again when it is carried out, so an archived person or a time that has passed fails that action alone.\n- **Whose.** A card is a `delegation_actions` decision for the speaker, `approver_only` like a reply card: only they see it (`GET /delegation/actions`) or resolve it, a team member's answers 404 to the principal too, and it is never an alert. The same actions still waiting are that card, not a new one. 3 cards a turn, 25 waiting, dropped after 7 days.\n- **Approve.** In the chat, under the reply that left it (the `propose_actions` chip carries the card's `decision_id`, and `ChatActionCards` shows the card while it waits), and on the Briefing's Needs you list, with a box per action. Approve (`POST /decisions/{id}/approve`, `edits.only`) needs the card's person signed in (`verified.caller_refusal`) with Act as me on; the card is claimed first so it runs once, then each ticked action runs as stored with no model call, in an unattended session (the principal's with contact egress) under `rows_for_person`, so every audit row it writes is theirs and nothing reaches the team's activity rail: `message_person` (a direct message or nothing; never its Briefing-alert fallback, which more people read), `create_calendar_event`, or a contact row. Approving also needs the person still allowed Act as me (`can_delegate`) and switched on. An invite is booked straight away when the person approving is the one the meeting gate would ask (`calendar_tools.approved_by`), and otherwise goes to that approver as usual, so a card never widens anyone's authority. Per-action results (`done`, `waiting`, `failed`, `skipped`) are kept on the decision and shown on the card. Dismiss rejects it and does nothing else. With Suggested actions in training the card adds the *Do this on its own next time* tick, and a card of actions all allowed is carried out on its own (see In training above); with Suggested actions On, any card that reaches nobody new is.\n- **Channels.** A card can come from any surface Act as me runs on; it is approved in the web app, since the chat apps have no buttons here.\n\n## The ghostwriter\n\n`delegation.ghostwriter.compose` writes the text. The Executive decides *what* to say (`intent`); this call decides *how* the person would say it, and it is deliberately small:\n\n- a constant `GHOSTWRITER_PROMPT` plus the person's voice block as the system prompt;\n- the thread (each message cut to its sender's own words, every line scrubbed, all labelled alike), then the writer's own earlier words in it (`<writer_said>`, from their sent mail only), the intent and the recipients' names in the user turn — no company profile, memory or roster;\n- with Always in the loop on, `<writer_noted>`: what the writer's own notes say they told these same people in earlier Act as me replies (`memory.history_drafts.notes_for_draft`: only notes from mail **every** recipient of the new draft was on, so nothing told to one person reaches another; chat notes name no recipient and never qualify; at most 8, newest first, the person's own words or their correction, with dates). The prompt's rule 6 makes it a consistency check, never content: a draft that contradicts it is still written as the intent says, and the conflict becomes an open question on the card, which only the writer sees. Both the chat tool and the inbox watcher pass it;\n- **no tools** but the forced `compose_reply` return, so text in the thread can ask for anything and there is nothing to do it with.\n\nIt is not a Council agent — the Council's edit routes have no principal check — and runs on `DELEGATION_COMPOSER_MODEL` (default: the default model), logged as `ghostwriter` usage. `lint` then runs in code on what comes back: a link or an email address survives only if it appears in the intent, the signature or the recipients, so a link planted in the thread is removed and flagged; the Executive's own name is flagged; and the body is capped, cut at a paragraph, line or word break in its last fifth. A draft with nothing left after that is refused. The signature from the person's Gmail settings (or the one already stored, for Outlook) is appended.\n\n## How I write\n\n`delegation.voice` learns how a person writes *their own* email (`attunement.style` learns how the Executive should write *to* someone). `POST /delegation/voice/learn` reads up to 40 recent sent messages, keeps only what they wrote (quoted replies stripped with the email poller's `sender_new_text`), skips automatic mail, every thread chat drafted into, and every sent message that began as a draft written for them (`delegation_drafts.sent_message_id`), and makes one forced-tool call (`record_voice_profile`). Code validates every field before it is stored:\n\n- greetings per audience (their team, their contacts, anyone else), a sign-off of at most two lines, and a usual length and tone (a backslash-n the model wrote instead of a line break is read as one, keeping the first lines that fit, which also repairs a profile stored before that rule);\n- up to 8 habits and 6 things to avoid, through the same deny-list as working-style rules — no actions, links, handles, amounts, tool names or names of people; the conversation review (`memory.chat_review`) adds one when the person states how they write in a chat (`add_conversation_rule`, `updated_by=conversation`; never on a locked or full list, and an edit or lock made meanwhile wins);\n- up to 3 short exemplars, each checked to be verbatim from a sample, with addresses and phone numbers masked — and none while a client slot is active, so one client's mail never lands in another's state.\n\nThe signature comes from Gmail's `sendAs` settings, not the model (Outlook gives apps no way to read one, so a learn keeps the stored signature and `POST /delegation/voice/signature` answers 409 `signature_unavailable` rather than clearing it), as plain text with its lines kept (`gmail.html_to_text`: a `<br>` always ends a line, and a block tag, opening or closing, ends one when it has text, so Gmail's layout of a first line followed by one `<div>` per line comes out line by line). `POST /delegation/voice/signature` reads it again without relearning: nothing else changes and a locked profile stays locked, so it picks up a changed Gmail signature and undoes **Don't add my signature**. A person can also describe their style in their own words: `POST /delegation/voice/describe` applies the description to the profile they have through the same forced tool (a separate system prompt, no exemplars) and the same validation, keeps their signature and writing examples, and returns the result with a short sample reply for them to review. It saves nothing and needs no mailbox; Save stores it as an ordinary edit. The person can edit the profile, lock it (a locked profile is never relearned) and reset it, and every change is kept in `delegation_voice_history`. One learn runs at a time per person, and a lock or an edit made while it runs wins: the learned profile is dropped (`changed`).\n\n## Draft replies to my inbox\n\nA second switch under Act as me, **Draft replies to my inbox** (`delegation.inbox`), has the Executive watch the person's own inbox and write a first reply to mail that needs them. The reply waits on a private card on Today; nothing is sent until they tap **Send** (below). Where the reply lives is the person's choice, **Also save replies in my Gmail Drafts** (`mailbox_drafts`, off by default): off, it lives on the card alone (`delegation.card_drafts`: the card keeps the draft's recipients, subject and thread headers as `draft_spec`, and Send makes the mailbox draft from exactly that just before the send-time checks, taking it back out if they refuse), so their Drafts folder doesn't fill with replies they may never send; on, it is also saved in their Drafts as before. The switch is one row per person in `delegation_inbox_watch`. Turning it on needs Act as me on and their mailbox connected, and sets `watch_since` to now every time, so it never drafts for mail that arrived before; turning Act as me off turns it off too. Off means no mailbox call and no row written, with one exception: a send the person started that the mailbox never confirmed is still followed through until it is settled.\n\n### When it looks\n\nA throttled hook in the scheduler tick (`_maybe_scan_inbox`, after the pause, company-profile and rotation gates) checks each person whose switch is on every `DELEGATION_INBOX_POLL_MINUTES` (default 5). It is not a scheduled action, because those are listed on `/scheduled` for everyone and anyone may cancel them. One scan task runs at a time, one scan per person, and none while a client slot is active. **Check now** on the Settings card runs the same scan. Every row a scan writes is private and the person's own (`audit.rows_for_person`: a team member's rows are hidden from the principal too, see Privacy), and the process log carries counts and codes, never an address or a line of mail. The scan never marks mail read or changes a label.\n\n### What it drafts for\n\nA scan first settles the open cards (below), and stops with `backlog_full` once 25 are waiting, counting the ones it makes. It then lists the inbox since `watch_since` (`inbox_message_ids`) — not chats, not mail from the person, and not the promotions, social, updates or forums tabs (on Outlook: the Focused inbox only) — up to 100 messages, and takes the newest message of each thread that still needs a look, at most 10: settled threads and threads with an open card are passed over first, so a burst of mail, or a pause for a limit or a back-off, never hides older threads for good. `delegation_inbox_messages` is its durable cursor: one row per message (`UNIQUE(person_id, message_id)`) with what happened to it, the reason, how many tries it took, and the draft and card ids. It stores a hash of the sender's address, never the address. A message is skipped, with the reason recorded, when:\n\n- it came before `watch_since`, or more than three days ago;\n- it is from the person or one of their send-as addresses, from the Executive, or one of this module's own drafts;\n- it is automatic — `Auto-Submitted`, a bulk or auto-reply `Precedence`, a bounce, a calendar invite or a no-reply sender — or from a mailing list, or in a Gmail tab, spam or trash (with Read my calendar on, a calendar invite goes to `delegation.invites` instead: see Meeting invites);\n- the person is not in To or Cc, or it has more than 10 recipients;\n- the person replied last, or a draft already sits in the thread.\n\nThree kinds are left unrecorded, so a later scan looks again: mail under 10 minutes old (mail the person answers straight away never gets a card), mail in a thread whose card is still open, and mail a daily limit holds back.\n\n### Deciding, then writing\n\nTwo model calls, and code decides between them. The classifier (`delegation.inbox_classifier`) is one forced-tool call, `classify_email`, returning whether the email needs a personal reply, what kind it is and how sure it is. It sees a few one-lined header lines and the sender's own new words (at most 3000 characters, every line scrubbed) inside one `<email>` block marked as data, after the person's own last email in the thread in a `<their_last_email>` block (`their_last_words`: only mail their own mailbox sent, at most 1500 characters), so a reply to something they asked reads as one: an answer to their request for a call that says when the sender is free, without settling a time, is scheduling and gets a draft even when the sender says they will come back with times. It has no other tools, context or memory, so an email can ask for anything and there is nothing to do it with. A reply is drafted only for a question, a request, scheduling, an introduction or a follow-up, and only when the confidence clears a bar that rises the less the sender is known: 0.6 for their team or a contact (the principal's contacts count only for the principal: a team member's mail is weighed by the team and their own sent mail), 0.7 for someone they have written to before (`has_written_to`, a search of their sent mail), 0.85 for a stranger. Pitches, notes of thanks, FYIs, notifications, newsletters and phishing get nothing, and so does any failure. An email that also went to other people is drafted for only when the person is in To and it asks them themselves: the classifier is told their name, whether they are in To or Cc and how many others it went to, and lists the names the email greets or asks by name (`asked_names`). Code matches those against the person's name, whole name parts only (\"Alexis\" never counts for \"Alex\", and a nickname misses, which means no draft), so mail that greets someone else (\"Good morning, Brennan, could you sign ...\") is never theirs, whatever the model makes of it as a whole. When it names nobody, the model's `asked_of_them` decides, false for a question to the group at large. One that only copies them is never drafted for. Either is recorded `not_needed` with the reason `asks_someone_else`. It runs on `DELEGATION_CLASSIFIER_MODEL`, else the routing model. A sender whose address Gmail couldn't authenticate is handled as a stranger whatever the roster says — anyone can put a colleague's or a client's address in From — so they get the stranger's bar, a holding reply and the stranger limits; the card still says who they claim to be, and that the address isn't verified.\n\nThe reply is written by the same ghostwriter, in the person's voice, but from a fixed intent the module builds rather than words the person typed. Because the intent lets it restate the person's own earlier words, which words are theirs is never written inside the thread, where a sender could imitate any marker with a look-alike: every message there is labelled alike, and the person's own words come in a separate `<writer_said>` block after the thread, taken only from mail their own mailbox sent. Nothing inside the thread can close the thread block or open another. The intent: acknowledge the sender; say again only what the person's *own* earlier messages in the thread already said; commit to nothing new — no yes or no, date, time, price, fact or promise — and say they will get back to them; and put every question it could not answer from their words in **open questions**. A stranger always gets a short holding reply. The lint still strips any link or address that isn't the person's own. The reply goes to the sender (never `Reply-To`) and, on a group email, to everyone else it went to as Cc (reply to all, never the person's own addresses or the Executive); a stranger's holding reply starts with the sender alone. When others were on the email the card offers **Reply to**: the sender only, or everyone (`PUT /delegation/replies/{id}/recipients`, `card_drafts.set_recipients`). It picks between the two lists fixed when the card was written (`reply_others`), never an address from the request, and changes the mailbox draft's To/Cc too. Its `draft_to` lists who it goes to, which Send checks.\n\nThe order: record the message, classify, reserve a slot in the shared daily limit, write, save the draft in Gmail (from the alias the mail went to, when it went to one) and store its id, then create the card (idempotent on the message: a second call finds the open card, and a card dismissed or lapsed under that key doesn't stop a new one, while one sent or settled in the mailbox means no second card, `invites.create_once`) and mark it drafted. Nothing that fails along the way loses the message. A failure that may pass — the classifier or the writer failing, Gmail refusing the draft, a card that couldn't be made (its draft is deleted first, so no draft is left without a card), any other error with that one message — leaves it for a later scan (`retry`), and it is given up on only after three tries; one message's trouble never holds up the rest. A daily limit reached while it was being read leaves it for later without counting as a try.\n\n### The reply cards\n\nA card is a `delegation_reply` decision whose class is **its approver's alone** (`DecisionClassSpec.approver_only`): only the person it was drafted for sees or resolves it on any decisions route — a team member's card answers 404 to the principal too — and it is never an alert: alerts feed chat turns, which would put other people's mail into memory. It carries the sender with who they are to the person and whether Gmail could verify the address (SPF/DKIM/DMARC, through `fact_confirmation.headers_authenticated`), the subject, what they wrote, the draft, the open questions and its warnings. `GET /delegation/replies` lists the open ones from the database alone, so Today never waits on Google.\n\n- **Send** approves the card, which sends its draft exactly as it is in their mailbox (see *Send on your tap*). **Edit** changes the reply's words right on the card (`PUT /delegation/replies/{id}/text`, `card_drafts.edit`): only its own person, from a caller the API can tie to them (as for Send), never while it is being sent on its own; a reply in their Drafts is rewritten there too (`update_draft_text`, every header kept), and only while it is still the version the card last saw, so a change made in the mailbox is never overwritten. A card edit counts as edited (`approved_with_edit`, and **Do it like this next time** keeps it), and one made by hand sets `questions_settled`.\n- **Decide before sending** with taps (`delegation.answers`): the ghostwriter returns each open question with 2 to 4 short answers the person might pick (`choices`) and what it is `about` (time, document, other); plain strings still parse, and `open_questions` stays a list of strings for every other reader, with `question_choices` beside it on the card. After the draft is written, code fills two kinds: a time question gets up to 3 free half hours on the person's own calendar (Read my calendar on; one a day over the next 5 working days, busy times only, no event title reaches a model), \"I checked your calendar: these are free.\"; a document question whose words match a company document's name gets 'I'll send \"<name>\" separately', \"Found \"<name>\" in your documents.\" Nothing is attached: a card's draft is plain text. A tap, or **Something else…**, calls `POST /delegation/replies/{id}/answer` (and **Tell me what to change…** calls `POST /delegation/replies/{id}/change` with their own words, which go to the same rewrite as `<change>`; their words and the Executive's note on what it changed join the card's `conversation`): one composer-model call rewrites the body with the answers in their voice (signature and AI line kept out and put back), `ghostwriter.lint` runs on it, and it is saved through `card_drafts.edit` with the same caller and card checks and the same Drafts update. It returns the card with `changed_sentences`, which the card lightly marks. 30 rewrites an hour per person (429). Send waits until every question with choices is answered, or the words were changed with Edit. A card made before choices shows its plain questions. **Open in Gmail** (or **Open in Outlook**), shown only when the reply is in their Drafts, opens it there.\n- **Dismiss** rejects the card; the class's after-reject step then deletes the draft if nobody edited it — its message id is still the one it was saved with, since Gmail gives an edited draft a new one, and the Outlook client makes a draft's message id `<id>.<changeKey>` so an edit there changes it too — and keeps it otherwise. What happened is recorded even when Gmail fails.\n- Each scan first **settles** what Gmail already settled: a draft sent from Gmail, a draft deleted there, a reply the person wrote themselves, a thread that is gone, or a card left for 7 days (its draft stays in Gmail). Each is a compare-and-set close with the reason. A newer message from someone else brings the card up to date instead (`answers.catch_up`): one composer-model call rewrites the draft with it as `<news>` (data, never the person's facts; a decision only they can make comes back as a new question to tap), saved through `card_drafts.redraft` (the card checks without a caller, since nobody tapped), and the message and the Executive's one-line note join the card's `conversation`. Send then counts newer mail from `caught_up_at`, and asks a second yes unless the card that was tapped showed that version (`edits.seen_caught_up_at`; the card refreshes beside the question). A new question's choices never carry a link or address. Past `MAX_CATCH_UPS` messages on one card, or when the rewrite fails, it only flags the card (`thread_moved_on`), as before. A card being sent at that moment is left alone.\n\n### Send on your tap\n\n`delegation.reply_send` is the only thing in Act as me that sends, and all it can send is a draft by its id (on a card, or written in chat or by a workflow): `DelegateGmail.send_draft` posts `{\"id\": …}` to Gmail's `drafts.send`, and `DelegateOutlook.send_draft` posts an empty body to that draft's Graph `send`, and nothing else, so no text, recipient or header is ever passed. It has four doors: `send_approved_reply`, reached only from `POST /decisions/{id}/approve` — a class only the card's own person may resolve — `send_on_its_own`, reached only from the inbox watcher under Handle it for me (below), `send_for_workflow`, reached only from a workflow step's `oe__send_email_as_me` (below), and `send_chat_draft`, reached only from `POST /delegation/drafts/{id}/send` (Send under a chat draft, below). AST tests pin all four call sites, so no model, chat turn, scheduled job or MCP call can, and a workflow only through that one tool. A tap is checked like this: At send time it checks everything again:\n\n1. **Who is asking.** The caller is the card's person and the API knows it: signed callers are on and the request carries that person's signed assertion (or the operator's, under local login), or the API runs for local login and answers this computer only. Anything else is a 409 `caller_signing_required` — with only the shared secret, whoever holds it could send as the owner — so on a server Send needs signed sign-ins.\n2. **The switches.** Act as me and Draft replies to my inbox are on, and no client slot is active.\n3. **The mailbox.** Their mailbox is connected.\n4. **The draft.** It still exists, in the same thread, and they haven't replied there themselves since; otherwise the card closes.\n5. **Who it goes to.** To, Cc and Bcc hold between 1 and 10 addresses, never the Executive's own, and it is from one of their own addresses.\n6. **What changed.** Recipients that differ from the card's, or a newer message from someone else, need a second yes: the first tap gets a 409 `confirm` naming the recipients and the reason, and the person approves again with what they were shown.\n\nThen it claims the card (`claim_for_execution`, proposed → executing, a compare-and-set, so a double tap sends once) and reads the draft once more: `drafts.send` sends whatever the draft is when Gmail gets the request, so if it was edited since the checks read it — in another tab, by a delegate — nothing is sent and the card comes back (`draft_changed`). Then it sends, and records the result: `approved_with_edit` when the draft was edited in Gmail, the sent message's id, the draft row's `sent_message_id`, and a private `delegation_reply_sent` row. A refusal that proves nothing went — a 4xx, a lapsed sign-in, a rate limit, a draft already gone — hands the card back. A failure that leaves it unclear — a timeout, a 5xx — leaves it `executing` and says to check the Sent folder, and the next scans ask Gmail: their message in the thread means it was sent; anything else is judged on the second scan that sees it: the draft still there and nothing sent means it was not (Gmail deletes a draft it sends), and the card comes back, flagged; the draft gone and nothing sent means it was deleted. Nothing is ever retried on its own. Sending is the person's own act, so it works while the Executive is paused.\n\n### Limits and failures\n\nAt most 5 drafts a scan; `DELEGATION_INBOX_MAX_DRAFTS_PER_DAY` (default 20) a day, inside the shared `DELEGATION_MAX_DRAFTS_PER_DAY` it shares with chat; 200 classifications, 2 drafts per sender (1 for a stranger) and 10 for strangers in all per day; and never more than 25 open cards. A lapsed Gmail sign-in sets the status and is looked at again every 30 minutes; a rate limit, an error reaching Gmail or a crash backs off from 5 minutes, doubling up to 2 hours. Neither turns the switch off: the Settings card shows the status in plain words.\n\n## Handle it for me\n\nA third switch under Act as me, **Handle it for me** (`delegation.handle_it`), lets the inbox watcher send some of its replies itself instead of leaving them on a card. It is one row per person in `delegation_handle_it` (`enabled`, `mode`); no row means off. One setting says how much goes without them, the way quality does on the Agent Council (`handle_it.RULES`): **Easy ones** (`careful`) sends only replies to people they know (someone on their team, a contact or someone they have written to) of at most 400 characters when the classifier is at least 0.9 sure; **People I know** (`balanced`), where it starts, sends replies to people they know up to 1200 characters at 0.8; **Most mail** (`bold`) also answers strangers, up to 2000 characters, and lets a link or an amount through when the classifier is at least 0.9 sure. Everything else waits on a card as before, so turning it on never drafts less. A table from before the setting gets the `mode` column on its next open (`schema._add_handle_it_mode`): someone who had strangers set to send keeps that as Bold, everyone else gets Balanced. Only the person turns it on (`PUT /delegation/handle-it`), from a session the API knows is theirs: the same rule Send uses (`delegation.verified.caller_refusal`), so with only the shared secret it answers 409 `caller_signing_required`. Turning it on needs Act as me and Draft replies to my inbox on, and turning the inbox watcher off (or Act as me, which turns it off) turns it off too.\n\n**In training** (`delegation.training`). Like someone new, each Act as me job can be put in training on its own, from that job's card on the Act as me page, the way Take the lead has it: **Write drafts as me** and **Handle it for me** each pick Off / In training / On (Handle it's In training puts Replies and Follow-ups in training together; its steps show under On only, since in training only allowed people go whatever the step), and **Suggested actions** picks Always ask / In training / On (On is the `actions_on` switch: a card is carried out with no allow, under the same checks, and only when it reaches nobody new: a new contact or anyone on the roster under a week waits; In training wins when both are set); what it learned is listed on each tab for its own jobs (Act as me: *What it's learned*, drafts and suggested actions; Handle it for me: *Who it's allowed to handle*, replies and follow-ups), each item named by its job (`PUT /delegation/training`, one row per person and setting in `delegation_training`, absent means not in training). In training it asks first and learns who and how from what the person approves; what it learns is a `take_the_lead_allowed` row (feature `act_as_me`, the person's id), theirs alone.\n\n- **Replies.** Every reply waits on its card (`handle_it_reason` `training`) whatever the dial says, and a reply card adds **Send + allow**: it sends that reply on the person's own tap, exactly as Send does, then allows replies to that sender (key `act_as_me|person:<id>|reply|<address>`). While Handle it for me is on, a reply to an allowed sender goes on its own under the dial's limits (a stranger they allowed included) and every check above (the topics that always wait, links and amounts, new recipients, once a thread a day, the daily limit); it's checked again at send time, so a sender removed since waits. Take the lead as you lifts nothing in training: putting Replies or Follow-ups in training turns it off, and it can't be turned on while they are (409 `in_training`).\n- **Follow-ups.** Every follow-up waits (`follow_up_training`); Send + allow on a follow-up card allows follow-ups to exactly the people it went to (`…|follow_up|<sorted addresses>`), whoever they are, under every other follow-up check.\n- **Suggested actions.** An action card (below) adds **Approve + allow**: it does the actions on the tap, then allows each one that happened (a message to that person, `…|message|person:<id>`; a meeting with exactly those people, the person left out, `…|invite|people:<ids>`). A new contact is never allowed. A card proposed later whose every action is allowed is carried out at once, with no tap (`action_cards.run_on_its_own`, `gate_mode` `auto_execute`, status `executed`), only if plain code finds nothing against it (`on_its_own_refusal`): still in training, Act as me on, a server that ties the switch to the person, nothing sensitive, no link or amount, a message of at most 1200 characters, and at most 10 actions carried out this way a day (checked one card at a time); anything refused is handed back to wait on its card as before. An invite carried out this way is never booked as approved by the person: the meeting gate decides as for any meeting nobody tapped, so a time taken from someone's mail can't land on a calendar unasked. The tool result and chip say what was done. The message text in such an action is model-written from the mail and goes without anyone reading it; the allowance covers who and what kind, not the words, which is why sensitive topics, links, amounts and long messages are held back.\n- **Drafts.** Nothing is sent. When the person changes a reply's draft in their mailbox before tapping Send (plain or + allow) and ticks **Do it like this next time**, what they sent is kept (its new text, quoted replies dropped, at most 1000 characters, `…|style|<address>`), and the ghostwriter gets it in its user turn as `<writer_example>` when it next writes to that person, from the inbox, a follow-up or a chat draft to that one person: style only, never its facts, and nothing in it can open or close a tag.\n\nSend and Approve with the *on its own next time* tick (`allow`; the tick replaced the separate Send + allow and Approve + allow buttons) are refused before anything is done unless their setting is in training (422 `cant_allow`) and the person's list has room (409 `learned_full`, at most 200 a person); allowing failing afterwards never undoes the send. Putting Replies or Follow-ups in, or Suggested actions out of training or On, only holds more back and works without signed sign-ins; anything else needs a caller the API knows is that person. What it learned is the person's alone: listed on `GET /delegation` (`training.learned`, each with its `setting`), removed with `DELETE /delegation/learned/{id}`, and for the owner also in Take the lead's \"What it's learned\" list; it never reaches anyone else's list or Take the lead's prompts. A dial left on In training by an older version (mode `training`) moves to People I know with Replies and Follow-ups in training (`schema._move_training_off_the_dial`).\n\n**No model decides whether a reply goes.** The watcher's two model calls are unchanged and tool-less, so text in an email can at most change the verdict and the draft. After the draft is written, `handle_it.refusal` — plain code — decides, and anything it refuses becomes the usual card with the reason kept on it (`handle_it_reason`). It refuses when:\n\n- it's off, or the sender is a stranger and the setting isn't Bold, or on a server signed sign-ins are off (`signing_ok`: signed callers, or local login);\n- Gmail couldn't authenticate the sender, whatever the roster says;\n- the email isn't a question, request, scheduling, introduction or follow-up, or the classifier was less sure than the setting needs (0.9 on Easy ones, 0.8 otherwise);\n- the reply goes to anyone the email didn't already go to (its From, To and Cc, less the person's own and the Executive's addresses), leaves out the sender, or goes to more than 10;\n- the email's subject, the sender's new words, or the reply touch money, contracts, legal, hiring, pay, layoffs, the board, investors, mergers, the press, health, or credentials and secrets (passwords, logins, tokens, API keys); or the reply carries an amount, a percentage or a link (a scheme, `www.`, a bare host with a path such as `bit.ly/…`, or a bare host on a common top-level domain) unless it's Bold and at least 0.9 sure, or runs over the setting's length (400, 1200 or 2000 characters);\n- the draft carries any flag but *others on the thread* or *Executive on the thread* (they asked if it's an AI, recipients were trimmed, …);\n- it already sent one in this thread in the last day, or the person's last message in the thread was itself sent on its own (no auto-reply ping-pong);\n- the day's limit is reached (`DELEGATION_HANDLE_IT_MAX_SENDS_PER_DAY`, default 20, within the watcher's drafts limit), or it can't be counted. Any error in the rules counts as a refusal.\n\n**Workflows that email as their creator** (`delegation.workflow_email`). A workflow step can write an email in its creator's voice with `oe__draft_email_as_me` (a draft in their mailbox for them to send, counted and named in the briefs like a chat draft) or `oe__send_email_as_me` (sent). Which one a step lists is the choice the creator makes when they save it; the gateway's mail tools still send from the Executive's own address. Both write only as the workflow's creator (`dynamic_store.get_owner`), never an address the step names, and refuse a run someone else started by hand, a speaker the roster can't place, a run one of the Executive's own unattended passes started (reflection, research, a proactive run: `chat_tools.started_by_a_pass`, inherited by nested workflows), or a run another person's workflow started (`chat_tools.running`); a scheduled run writes as the creator. The creator must be allowed Act as me, have it on and have their own mailbox connected, or the step is told to use the Executive's own email. `to` and `cc` are write targets (`action_step.TargetPolicy`). The creator's own addresses and the addresses in the saved goal of a step that emails as them, nowhere else in the workflow (`workflow_email.chosen_recipients`; only its verified creator saves one, and a definition that differs from the saved copy gets none) go without asking; the first email to any other address waits for the creator's approval and is then remembered. Every email counts against `DELEGATION_MAX_DRAFTS_PER_DAY`, and sends against `DELEGATION_WORKFLOW_MAX_SENDS_PER_DAY` (default 20) as well, counted from `delegation_drafts` rows with source `workflow_sent` (written before the send, so a failed send still counts). Sending needs more: a workflow with `oe__send_email_as_me` can only be created, changed or switched on by its creator from a session the API knows is theirs (`workflow_email.save_refusal`, the `verified.caller_refusal` rule Send uses; a 403 otherwise, from `POST`/`PUT /workflows/custom`, save-edit and activate), and chat's `save_workflow` never replaces one, so nobody else can change what it sends. At send time `reply_send.send_for_workflow` checks again that Act as me is on, `handle_it.signing_ok`, no client slot is active, and the draft it just wrote is unchanged: addressed exactly as written, from one of their own addresses, at most 10 recipients and never the Executive's own address. A send the mailbox didn't confirm is reported as possibly sent and never retried. The step's result (and so the run's report) names who it went to and the subject, never the body; the audit rows (`delegation_drafted`, `delegation_workflow_sent`, `delegation_workflow_send_refused`) are the creator's alone. The workflow designer is told whether the person designing it can have email written as them, and to ask when it isn't clear whether an email should come from them or from the Executive.\n\n**Workflows that read their creator's mail** (`delegation.workflow_reads`). A step may also read the creator's own mailbox and calendar with `oe__search_my_email`, `oe__read_my_email`, `oe__my_email_awaiting_reply` and `oe__my_calendar`: chat's own reads (`mail_read_tools`), run as the workflow's creator through `AS_CREATOR` in place of the chat turn's speaker, with the same per-call caps and the same untrusted-content marking. They read only on a run that is the creator's: started by them by hand (`turn_owner` is them) or by its schedule, and only in the outermost workflow (never one another workflow started, whose later steps would see the mail), never on a run an unattended pass, an inbound message or someone else started. Act as me must be allowed and on and the mailbox connected; `my_calendar` also needs Read my calendar on. Outside chat, the principal's Right now reads their sent mail for the emails nobody has answered yet (`briefing.waiting_on`) whenever Act as me is on and their mailbox opens: recipients, subject and time only, never a body. The inbox watcher also notes each message it looks at (and newer mail on a thread whose card is still open) as a private `delegation_inbox_mail` audit row, sender, subject, time and how well the person knows the sender, never a body, which the principal's Right now reads (`live_signals.own_inbox`). Turning Act as me off drops that read (`settings.set_enabled`). Such a run is the creator's alone: the scheduler creates a scheduled run as theirs (`owner_person_id`, viewer pinned to them), delivers its report and any failure card to them whatever the cadence names, the run route returns 403 to anyone else, and every audit row the run writes (scheduled, from the Jobs page, from chat or resumed, its report's delivery included) is theirs alone, with no send on the shared activity rail (`workflow_reads.private_run`, `rows_for_person`). Chat's `run_workflow` starts one only for its creator on a turn Act as me was offered on, and first marks that turn as one that read their mail (private, and locked down for the rest of it), since the report comes back into it. The lockdown a chat turn gets after a read covers the whole workflow, checked when it is saved (`definition_refusal`, also in chat's `draft_workflow`/`save_workflow`) and at every step (`run_rules`): its steps may list only the reads, the email-as-them tools (`workflow_email.TOOLS`: a send goes without asking only to an address the creator chose, so mail text naming another address gets a card first) and chat tools in `MAIL_TOUCHED_ALLOWED_TOOLS` (no gateway, extension or web-search tool, no `run_workflow`, nothing that posts to everyone), get no `run_script`, and may have no approval gate asking anyone but the creator and no cadence reporting to anyone else. Like one that sends, a workflow that reads can only be created, changed or switched on by its verified creator (`workflow_email.save_refusal`).\n\nA reply the rules allow gets a card with `gate_mode` `auto_execute`, and the watcher sends it at once through `reply_send.send_on_its_own`, the second door into the send path (an AST test pins its callers: the approve route, the watcher, a workflow's `oe__send_email_as_me` and the chat draft route). It runs the same send-time checks as a tap — switches, mailbox, draft, recipients, the claim and the last re-read — with no caller, and adds its own: the card must be `auto_execute`, Handle it for me still on with the setting still allowing that sender (or, for a follow-up, that recipient), signing still on, the once-a-thread-a-day rule and the daily limit counted again, and the draft untouched since it was saved (an edit in Gmail means the person has taken it over: `draft_changed`, the card waits for them). Every refusal hands the card back to the person (`decision_ledger.hand_back`, a compare-and-set to `propose`), with the reason kept on it when there are words for it, and a failure never stops the scan. Every card it left for the person says why on Today (`waited_because` on `GET /delegation/replies`). A reply sent on its own finishes as `executed` (not approved), is recorded in `delegation_handled` (for the per-thread and daily rules) and writes a private `delegation_reply_handled` row; an unconfirmed one is settled by the reconciler the same way. No History note is taken from it, since notes come only from the person's own words. It runs inside the watcher's scan, so it stops while the Executive is paused.\n\n**The last look** (`delegation.injection_check`). A reply the rules would let go gets one more check before it goes: one small classifier-model call, with no tools, reads the sender's own words as plain text (up to 20,000 characters, far more than the classifier) and says whether they carry instructions meant for an assistant rather than the person (to ignore its rules, forward or quote other mail, reveal what it knows, reply somewhere else, or a passage addressed to the assistant). Styling is gone by then, so hidden text is judged by what it says. A yes, a failed call or a malformed answer keeps the reply on its card (`handle_it_reason` `suspicious`). It only ever holds back, on top of the plain-code rules, never instead of them.\n\n**Answering from a workflow** (`delegation.workflow_reply`). A workflow step can hand one thread to the same path with `oe__answer_email_as_me`, passing only `thread_id`: `inbox.answer_thread` takes the newest message not from the person and runs it through the watcher's own `_consider` (classifier, ghostwriter, Handle it for me's rules, the last look, the limits and the once-per-message ledger, so the watcher never answers it twice), bounded only by staleness rather than when the watcher started. The step can't choose the words or the recipients: the reply goes to the people the email already went to, sent on its own when the rules allow and otherwise left on the usual card. It refuses while a scan is running or the backlog is full, writes only as the creator on their own run (`workflow_email.creator_mailbox`), counts as a send for who may save the workflow (`workflow_email.sends`), and may be used in a workflow that reads mail.\n\n**Follow-ups as you** (`delegation.follow_ups`). While Handle it for me is on, the watcher's scan also looks at the person's own sent mail, at most once an hour (`LOOK_EVERY`), for an email of theirs that asked something (a question mark in their own words), is 3 to 10 days old, went to at most 10 people other than the Executive, and is still the last message in its thread. Plain code picks it; each gets one follow-up ever (its `delegation_inbox_messages` row), at most two a look, within the drafts limit. The ghostwriter, tool-less as always, writes a short nudge in their voice from the thread, saved as a draft in that thread to exactly the people the email went to. `handle_it.follow_up_refusal` — plain code — decides whether it goes: by the setting it never goes on Easy ones, goes to their team and contacts on People I know and to anyone they wrote to on Most mail (`follow_up_refused` otherwise: `follow_up_level`); it also refuses on any change of recipients, a sensitive topic, an amount or a link, more than 600 characters, a flag, and the same per-thread and daily counts as replies. It goes through `send_on_its_own` on an ordinary `delegation_reply` card marked `source: follow_up`, which rechecks the setting for that recipient. A refused one waits on Today as **Follow-up waiting**, and closes by itself (its untouched draft deleted) when anyone answers in the thread first.\n\n**What it sent** is the person's alone: `GET /delegation/handled` lists the last 7 days (who, subject, the reply, the questions it left them and a link to the thread in their mailbox), and the Handle it for me tab shows it with how many went today, under its picker.\n\n### Take the lead as you\n\nOn Settings → Act as me, Handle it for me is one dial: **Off**, **Easy ones**, **People I know**, **Most mail** and, for the owner, **Everything**, which uses **Take the lead** (`PUT /delegation/take-the-lead`, one row `person:<id>` in `take_the_lead`; turning it on turns Handle it for me on). While it is on, `handle_it.refusal` drops the setting's limits: strangers, the classifier's confidence, amounts, and the length up to a 4000-character ceiling. A reply with a link still waits for a tap (refusal `link`). In their place it checks the company's and the person's own added rules (`take_the_lead.reply_hit`, refusal `lead_rule`). Everything Handle it always keeps still holds: signed sign-ins, an authenticated sender, a reply kind, exactly the thread's people, the topics that always wait, draft flags, never twice in a row, one a thread a day and the daily limit. Follow-ups under it may go to anyone the person wrote to, with the same sensitive, amount, link and length checks plus the added rules. `reply_send.send_on_its_own` accepts the card while both switches are on. Each person adds and removes their own rules (`/delegation/take-the-lead/rules`). Removing one needs a caller the API can tie to them.\n\n\n### Send under a chat draft\n\n`ghostwrite_email` saves the draft and returns its `delegation_drafts` row id (`draft_row`). The chat chip carries that row with the draft as saved (recipients, subject, the first 800 characters), and the web chat shows it under the reply as **Email as you** with a **Send** button. The tap posts `POST /delegation/drafts/{row}/send`, which `reply_send.send_chat_draft` checks again first:\n\n1. The row is the caller's own, from chat (`SOURCE_CHAT`); anything else is a 404. The caller is that person, the same `verified.caller_refusal` rule as a card's Send (a 409 `caller_signing_required` on a server without signed sign-ins).\n2. Act as me is on, no client slot is active, and their mailbox is connected. Draft replies to my inbox doesn't matter here.\n3. The draft is still there and its message id (Outlook: id and change key) is the one recorded when chat wrote it. One changed in the mailbox since is a 409 `draft_changed`: they send it from there.\n4. Recipients: someone, at most 10, never the Executive's own address, from one of their own addresses.\n5. For a reply: one they sent themselves in that thread since closes it (`you_replied`); a newer message from someone else asks a second yes (409 `confirm`, then `{\"thread_moved_on\": true}`).\n\nThen it claims the row (`drafts.claim_send`, a compare-and-set on `gone_at`, so a double tap sends once and the briefs stop calling it waiting), reads the draft once more and sends only that same version. A failure that shows nothing went hands the claim back; an unconfirmed one keeps it, so another tap can't send it twice. It records `sent_message_id`, a private `delegation_chat_draft_sent` audit row and, when Always in the loop is on, a note of what they sent. Like a card's Send it works while the Executive is paused. **What it may do** says chat emails are \"Drafts, sent on your tap\".\n\n## Meeting invites\n\nWith **Read my calendar** on, a calendar invite in the person's inbox no longer just gets skipped (`delegation.invites`). The watcher applies its usual rules, less the ones about writing a reply (a calendar service's own Sender header doesn't make it automatic; a big meeting isn't too many recipients), and then looks at who sent it: someone the person knows — their team, a contact, or someone they have written to (`inbox.relation_of`), with the sender confirmed by the mail service (`inbox.handling_relation`) — or it is skipped as `invite_stranger` / `invite_unverified`. It then finds the event on their own calendar: on Google by the invite's iCalendar UID (read from its `text/calendar` part, or its attached `.ics`) in their primary calendar, on Outlook as the invite message's own event; only a request counts (a cancellation or someone's answer doesn't). An event that can't be found, isn't organized by the sender, is already answered or has already started is skipped with that reason, as before. **No model is called** for an invite.\n\nWhat's left becomes a card, a `delegation_invite` decision that is its person's alone (`approver_only`) and never an alert, like a reply card: who invited them, the title, when (in the workspace time zone) and any **clash** — the busy times on their calendar that overlap the meeting, computed in code from the calendar read; only start and end times reach the card, never another event's title. **Accept** and **Decline** are `POST /decisions/{id}/approve` with `edits.answer` (`accept`, the default, or `decline`), on the same caller checks Send uses (`verified.caller_refusal`); the card is claimed, then answered with the mailbox client's `answer_invite`. Answering again is harmless, so a failure releases the card for another try; an event that has gone fails it. **Dismiss** (`reject`) answers nothing. A sign-in that reads but can't write the calendar keeps its card, which says to connect again under Read my calendar (with the command) instead of offering Accept. A card closes by itself once the meeting starts or after a week, and its thread waits until it's settled.\n\n**On its own.** Under Handle it for me (On, or Take the lead as you) it accepts with no tap when plain code finds nothing against it (`invites.refusal`): a sender on their team or in their contacts, never one known only from their Sent mail (with Replies in training, only one they ticked **Accept from them on its own next time** for), signed sign-ins or local login, no clash and a calendar it could read, nothing sensitive in the title, a sign-in that can answer, and Handle it for me's daily limit and once-a-day-per-thread rule (`handle_it.count_refusal`, `record_handled`). It never declines on its own. Anything against it leaves the usual card saying why. An accepted invite is listed with the replies it sent: `GET /delegation/handled` (`source: invite`, with a one-line `summary` such as \"Accepted Dana's Pilot review, Wed 21 Oct, 14:30\") and Today's `sent_as_you` activity, the person's alone.\n\n**In training.** With Replies in training, a card has the same tick as a reply card; ticking it and tapping Accept adds `Accept invites from <name>` to their learned list (key `act_as_me|person:<id>|invite_from|<address>`, under Replies), removable like any other.\n\nAudit rows, all private to the person: `delegation_invite_carded`, `delegation_invite_answered`, `delegation_invite_handled`, `delegation_invite_dismissed`.\n\n## AI line on replies\n\nReplies written as a person can end with **\"Drafted and sent by my AI assistant.\"** (`delegation.disclosure.LINE`), by two switches that are each person's own (`PUT /delegation/disclosure`, one row per person in `delegation_disclosure`, NULL following the install): **Handle it**, on by default (`AI_DISCLOSURE_HANDLE_IT`), for a reply Handle it for me will send on its own, which nobody reads before it goes; and **Approved sends**, off by default (`AI_DISCLOSURE_APPROVED_SENDS`), for one that waits on a card for them to send, since they read it first. The line is written into the reply when it is drafted (`disclosure.sign`, in `inbox._consider` and `follow_ups`), once the plain-code checks have decided whether it goes on its own, so the card, the mailbox draft and what is sent are the same words and Send's draft-changed checks see them; a switch changed later applies to the next reply, and a reply drafted to go on its own that is handed back keeps its line for the person to edit. `AI_DISCLOSURE` off turns both off and hides the card. Turning a switch on only adds the line, so it needs no signed sign-in; turning one off does. Each tab shows its own switch under Advanced (**AI line on drafts you send** on Act as me, **AI line on replies it sends** on Handle it for me), and turning off the Handle it line asks first.\n\n## The mailbox client\n\n`delegation.gmail.DelegateGmail` talks to the Gmail REST API directly and is **never registered with the MCP gateway**, so the model reaches the mailbox only through the typed handler. The credential is one file per person in `DELEGATION_GOOGLE_CREDENTIALS_DIR`, named from a hash of the address (0600 in a 0700 directory), minted by `scripts/connect-own-gmail.py` on the Executive's own OAuth client with the scopes `gmail.readonly` and `gmail.compose`. It never lives in `WORKSPACE_MCP_CREDENTIALS_DIR`, where workspace-mcp picks a credential by address. Besides reading threads and saving drafts it lists the inbox and checks whether they have written to an address, reads one message or draft, lists the person's send-as addresses and deletes a draft. Its **one send method**, `send_draft`, sends an existing draft by its id and nothing else — never `messages.send`, which sends any text it is given — and unit tests pin the method set, the endpoint, the request body and its single caller. On the calendar it reads (`list_events`, `find_invite`: an invite's event by its iCalendar UID) and makes one change, `answer_invite`: the person's own attendee answer on one event, with `sendUpdates=all` so the organizer hears (`calendar_write_granted` says whether the sign-in allows it; a read-only one raises `CalendarWriteNotGranted`). A failed request says whether it may have been carried out anyway (a timeout after connecting, a 5xx), which is what the send path needs to know. A parsed message carries when it arrived, whether it is bulk, a bounce or a calendar invite, and whether Gmail's authentication results vouch for its sender.\n\n`gmail_status` answers `connected`, `not_configured`, `needs_reconnect` (Google refused the saved sign-in — an app in Testing mode has its tokens expire after 7 days; a rate limit, though Gmail may send it as a 403, is an `error` to retry, not a reconnect), `mismatch`, `no_email`, `shared_mailbox` or `error`. `shared_mailbox` means the person's address *is* the Executive's; it is refused before asking Google, because then everything the Executive writes would look like theirs. The gateway closes the other door: every `google_workspace__*` call must act as the Executive's own account, and a `user_google_email` naming anyone else is refused and audited (see Integrations).\n\n### Outlook\n\nA person may connect an Outlook mailbox instead (work, school or personal), with `scripts/connect-own-outlook.py`: a device-code sign-in on the Executive's own Entra app (`MS365_MCP_CLIENT_ID`, tenant `MS365_MCP_TENANT_ID` or `common`) asking for `User.Read`, `Mail.ReadWrite`, `Mail.Send` and `offline_access` (and `Calendars.ReadWrite` with `--calendar`; an invite is the invite message's own `eventMessage.event`, answered with Graph's event `accept` or `decline` and `sendResponse`). It writes the same per-person file with `\"provider\": \"microsoft\"`, so a person has one mailbox for Act as me, and `gmail_for` hands back `delegation.outlook.DelegateOutlook`, which keeps `DelegateGmail`'s methods, return types and errors, so every caller above runs unchanged. It talks to Microsoft Graph directly, never through the Microsoft 365 MCP server the Executive's own Outlook uses, and is never registered with the gateway. Microsoft rotates the refresh token on use; the new one is written back into the file (atomically, keeping every other key, and only if the file still holds the old one). Graph is asked for immutable ids, so a sent draft keeps its id; a thread is Outlook's `conversationId`. Gmail's labels are mapped onto what the callers read: `SENT` only for mail in their Sent Items folder (a From line set to their address by someone else never counts), `DRAFT`, `INBOX`, and Focused Inbox's Other read as a tab. A sender counts as authenticated only when the topmost `Authentication-Results` — the one Exchange wrote, above anything the sender added — holds exactly one DMARC verdict, a pass for From's own domain, and Exchange Online Protection's own `compauth=` verdict, so a header the sender wrote on mail EOP never stamped doesn't count. `delete_draft` refuses anything that isn't a draft, and deletes with the draft's etag (`If-Match`), so a draft sent in between — it keeps its id — is left alone. No client secret is ever written into a person's file, and Graph has no signature setting to read.\n\n## Privacy\n\nWhat a person's mailbox touches is theirs. For the principal that means private to the principal, as every private row is. For a team member it means theirs alone, the principal included: an audit row carries `private_to_person` (set by `audit.rows_for_person` around the inbox watcher, a card's Send and Dismiss and their settings changes, and by `people_tools.audit_row_owner` on a turn that read their mail) and is left out of every audit read — the log, a session's timeline, a row by id, the brief — with only the usage totals counting it; their reply cards are theirs alone (above); and the owner's view of their use is counts only (drafts and sends in 30 days, and whether their inbox watcher is on). The conversation itself becomes its owner's alone before the mailbox is first read: `ghostwrite_email` marks the session `mail_private` (`session_store.mark_mail_private`, creating a channel adapter's row early, with its owner) and refuses to read the mailbox if that can't be stored or the conversation already belongs to someone else (which it then leaves unmarked); from then on only its owner may open it (`chat._session_access`), and working-style learning skips it. Every later turn there starts private (`settings.pin_turn_delegation` reads the flag and fails closed, setting `touched_mail`), so a follow-up answered from history alone is still private to its owner and teaches no memory, and the web chat's rows before the turn (the inbound message and the knowledge lookup) are theirs too. It does not start locked down: the lockdown is `read_mail`, set only by a turn that reads the mailbox or notes itself, and it is never carried into the next turn, because history keeps only the speaker's words and the Executive's replies, never the mail a tool returned. Their next message is them asking again, having read that reply, so everything runs again there. Anyone else speaking in it is not offered Act as me.\n\nOnce `touched_mail` is set, every audit row the turn writes is private (`people_tools.audit_row_private_to_principal`), and a team member's is theirs alone: the tool row (its input and result redacted, since `ghostwrite` is a sensitive tool name), the reply's `chat_turn` row that carries the preview, the model-call rows, and the background passes, which run under `private_rows`. The Honcho peer and department syncs are skipped, because peer memory is read on other people's turns. No memory is learned from the turn at all: the episodic, open-loop and working-style passes are skipped too, since its reply quotes a draft built from other people's mail. The `delegation_*` audit events are always private and carry metadata only — ids, counts and flags, never the draft or the thread. The inbox watcher is private the same way: every row a scan or a card action writes is its person's alone, and it starts no chat turn, alert, scheduled action or workflow run and teaches no memory.\n\nThe turn also keeps one door shut (`delegation.lockdown`). Anyone can put text in the inbox, and that text could try to steer the model, so from the round that calls `ghostwrite_email` or one of the mailbox reads — a round's tools run together — until the turn ends, the dispatch guard refuses only what opens the open internet or reaches everyone: outside fetches (`read_document`, research, the watchlist, `load_mcp_server`, and any MCP `call_tool` outside the private-turn set of reads and recipient-checked sends), `run_script` and `run_python_job`, workflows (they run later, unattended, and may fetch or script), broadcasts, department messages and alerts, and changes to who is on the roster or holds authority (`archive_person`, `set_department_head`, `resolve_roster_request`), and text that steers later turns (`schedule_followup`, whose intent runs unattended when due, and goals and decision outcomes, shown to every later turn). Everything else the person asks for runs, because it is fenced on its own: DMs and `message_person` reach only the roster, invites name attendees by person id, the Executive's own email checks every recipient against the roster, standing facts and profile edits keep only the person's own words, and a workflow drafted in chat is saved only once a person confirms it. `upsert_person` runs only for a contact the person asked for (`speaker_named_contact`: a contact, never the team, an approval scope or a chat account, with a word of the name in what they typed, in a message that asks to add, save or change someone, a new contact's address one they typed or one that sent the mail the turn read under the contact's name (`TurnDelegation.mail_senders`), never one the mail's text only mentions, and on an update a changed address they typed), since the roster is what the send checks trust. Any other contact add is refused with a pointer to an approval card (`lockdown.CONTACT_REFUSAL`), so the Executive leaves an `add_contact` card in the chat rather than asking them to type the address. What an email itself asks for is still never done on its say-so; it goes on an approval card. Every tool is classified as allowed or withheld, a test fails on a new unclassified one, and an unknown name is withheld, except an extension tool registered with `after_mail_read` (one that only reads the install's own data). The refusal tells the model to put what the step needs in its reply, since the next turn sees the reply but not the mail, and to do the step then without reading the mail again. A refused call gets a private `tool_invocation` row (`refused: mail_touched`) and tells the model to offer it in the next message. The offered tool list never changes mid-turn, so the cached prefix holds. The handlers that reach outside check again on their own (`outside_reach_refusal`). The server-side web search stays, as on a turn private to the principal. How much of the lockdown holds is the owner's safety level (`orchestrator.outside_mode`), because every mail read is checked like any outside read: after each round, each mailbox or notes read's result goes through `content_scan` (`outside_content.check_mail_read`), which sets `TurnDelegation.mail_held` when the level holds it and `mail_vetted` once the round's reads are checked (`check_mail_reads_done`), and puts `FLAG_NOTICE` or `UNCHECKED_NOTICE` before the result as for other reads (a search's threads are checked entry by entry, `content_scan.scan_list`: a flagged thread's subject and sender name are taken out behind `LEFT_OUT_NOTICE` and the rest passes once a second check finds it clean (else the whole list is flagged), holding nothing below Careful; a thread whose newest message the Executive itself sent, from its own address the mail service authenticated (`ThreadSummary.sender_authenticated`, from Gmail's or Exchange's stamp as on a message read, kept per turn in `TurnDelegation.mail_verified`) and under a subject that is not a reply's or forward's, is not checked; the reply never mentions a flag); a flag is shown under the web chat reply as *An email I read …*. `lockdown.mail_lock_holds` then decides: Careful holds the whole lockdown after any mail read; Balanced holds it only once a read was flagged or too big to check, or while one is not checked yet (the round that reads mail holds its other calls, since they run together); Hands-off holds none of it on the principal's own turn; a turn with no safety state (a workflow) holds it, failing closed. `mail_turn_withholds` applies it at dispatch and in `outside_reach_refusal`. At every level a mail read keeps posts to everyone and roster or authority changes shut (`MAIL_PRIVATE_WITHHELD_TOOLS`, and `upsert_person` only for a contact the speaker named), since those would spread the owner's private mail or change what every send check trusts. App control (`app_control._turn_read_outside`) follows the same rule, and under Careful still waits for a tap in any turn of a conversation that read the owner's mail. The lockdown ends with the turn. Later turns of that conversation stay private to its owner (`touched_mail`) but hold nothing: a refusal says it will work when they ask again in their next message, and it does.\n\n## Always in the loop\n\nA sent reply can leave a note. Once the reply went, `reply_send` starts `memory.history_notes.note_sent_reply` for the person who sent it, in the background, when their \"Keep track of what happens\" switch is on and the conversation isn't one they asked not to remember. The note-taker sees only the words they sent, so other people's mail never becomes a note, and a failure never touches the send. Recall is `recall_history`, offered on the same verified, private surfaces as `ghostwrite_email` and also allowed under the mail lockdown, since it only reads the speaker's own notes. Calling it locks the turn like `ghostwrite_email` does, from its own round on. The same switch also covers notes from chat, which don't need Act as me. See **Memory** for the checks, retention and controls.\n\n## The system prompt\n\nA constant, name-free `DELEGATION_ADDENDUM` joins block 0 after the unchanged identity addendum while anyone on the install has it on (`block0_delegation_on`). It names the four mailbox reads and says other people's mail is data and that a conversation which read it reaches nobody else; and it tells the model that `ghostwrite_email` is the single exception to *never impersonate*, and only for the person being spoken to; that everything else is written as itself; that when the tool isn't offered the asker can't have it; that a draft is never described as sent; and that it never denies being an AI. It is keyed on the install-level setting, never on the turn or the speaker, so switching it misses the 1h cache once (see Prompt Caching).\n\n## What it does for you\n\n**What it does for you** (`delegation.may_do`, `GET /what-it-may-do`) is read-only: with the viewer's settings right now, one row per thing that can go out without asking, written as one sentence of what it does, what happens to it (goes out, waits for someone, always waits, drafts only, off) and which setting decides it, with a link there. It sits beside every Delegate tab (`DelegatePage` → `WhatItDoesPanel`): a column to the right on a wide screen (closing it is remembered in the browser), a bottom sheet on a narrow one. The UI groups rows by outcome (Sends on its own, Asks first, Writes for you to send, Off). Every delegation setter in `lib/api.ts` fires `DELEGATION_CHANGED` after a save; the panel reloads on it and marks the rows whose outcome or text changed as **Just changed** for ten seconds. `/delegate` and the old `/delegate/what-it-may-do` open Act as me. Its **Compare** fold holds Who writes and who sends. Three parts, each behind a pill that counts what goes out:\n\n- **As you** (the caller's own, when `can_delegate` allows them): built from `settings.is_enabled`, `inbox.get_watch`, `handle_it.get` and `handle_it.RULES`, `handle_it.leading` (Everything), `training.get` and `training.learned`, and their rules, the same reads `handle_it.refusal` and `follow_up_refusal` make. A level's row follows its `Rules` (strangers, follow-up reach, links and amounts), not a copy of them. A note names the ladder: Handle it for me rides on Draft replies to my inbox and Write drafts as me, and Everything also drops when Replies or Follow-ups go into training.\n- **As the Executive** (the principal's alone, as `GET /take-the-lead`): the switch and its training, each Ask first kind, the company's rules, and meetings. A meeting it thinks of on its own always waits: both meeting gates need someone on a verified surface in the turn, which an unattended run never is. A meeting someone asks for in chat follows **Always asks first → Meetings asked for in chat** (on means it waits: `meeting_scheduling`'s class mode is `propose`; off means `auto_execute`) and, in a team workspace, Operations' level too.\n- **Departments**: each level, and what a level covers (department-scoped scheduled work, check-ins, alert review, team members' chat sends, and Operations' meetings), and that it doesn't cover what the Executive does under Take the lead.\n\nIt also says when the Executive is paused, and when nothing can be sent as anyone because signed sign-ins are off. Nothing on it writes or reads mail. A contact, someone not on People, or a request with no caller (outside local login) gets 403.\n\n## How far it goes as you\n\nOne setting replaces the switches that used to turn each other off out of sight. The UI shows it as two pickers (`ReachCard.tsx`): **What it writes as you** (`WritesCard`) on the Act as me tab and **What it sends on its own** (`SendsCard`) on the Handle it for me tab; What it does for you links each row to its own picker. Its steps, each adding to the one before: **Off**, **Drafts when I ask** (Write drafts as me), **Drafts for my inbox** (Draft replies to my inbox), then the Handle it for me steps that send, **Easy ones**, **People I know** and **Most mail** (`careful`, `balanced`, `bold`), and for the owner **Everything** (Take the lead as you). Act as me shows the first three as **Off**, **When I ask** and **Draft replies automatically** (any sending step reads as Draft replies automatically there). Handle it for me shows **Off** (saved as the inbox step) and the sending steps, and opens only once Act as me is at Draft replies automatically, with a button that turns that on; moving Act as me below it says Handle it for me stops too. `PUT /delegation/reach` (`{step}`) moves it, and `reach_of` reads the step back from the switches, so the stored switches stay the source of truth and every gate reads them as before.\n\nGoing down turns the switches above the target off, highest first (`_lead_off`, then Handle it, then the inbox watcher, then Write drafts as me), so nothing is ever on above a switch that's off; the UI says what stops and asks before it saves. A lower sending level only holds more back and is set directly, so it needs no signed sign-in. Going up calls each switch's own route in order, so every check it makes still applies: the mailbox connected, signed sign-ins for sending, the owner alone and not in training for Everything. The first that refuses stops the move at a whole step and answers with that route's error. Handle it for me's own Off / In training / On (Replies and Follow-ups together) and, at Everything, **Your rules** sit with its picker, and **Learn from my edits** (drafts training) under the Act as me one; neither picker changes training.\n\n## Surfaces\n\n- **Settings → Act as me** (`ActAsMeCard`, hidden unless `GET /delegation` answers, so a team member sees it once the owner lets them): the mailbox connection (`provider` says which) with both connect commands (Gmail and Outlook) and **Check again**, **What it writes as you** (above), with the inbox watcher's status under Draft replies automatically (in plain words, when it last checked, **Check now** and **Also save inbox replies in my Gmail Drafts**), and **How I write**: length and tone, a greeting per audience (`{first}` is their first name), the sign-off, habits and never-rules in fields that grow to show every line, the signature with **Refresh from Gmail** and **Don't add my signature** (or **Add my Gmail signature** when none is added; on Outlook only **Don't add my signature**, with why), and each example quoted with **Remove examples**. The owner also gets **Let team members use it** where the install allows it, with each team member who has it on listed by name and counts only.\n- **Today → Replies waiting** (`RepliesWaiting`, the top of the left column; hidden unless `GET /delegation/replies` answers with cards): each card starts closed (who wrote, the gist, what's left to decide, Send or Review, Dismiss); open, everything shows at once as a conversation: what they wrote as plain text, the Executive's word on the reply with the open questions (each with answers to tap and **Something else…**, and where they came from) and the answered ones (**Change** to pick again), then the card's `conversation` (newer email marked **New**, what the person asked to change, the Executive's note on what it did), then **Your reply** with its Reply to choice, **Edit the words myself** (a text box on the card with Save and Cancel), **Tell me what to change…**, its warnings, and **Send** (a confirm naming who it goes to, and a second one when that or the thread changed), **Open in Gmail** or **Open in Outlook** when the reply is in their Drafts, and **Dismiss**.\n- **Today → Needs you, invites** (`InviteCards`, next to the reply cards; hidden unless `GET /delegation/invites` answers with cards): the meeting, when, who invited them and who they are to them, any clash (times only), and **Accept**, **Decline** and **Dismiss**, or the reconnect note for a read-only sign-in; with Replies in training, the **Accept from them on its own next time** tick.\n- **Setup status**: a **Your own mailbox (Act as me)** light (`your_gmail`), amber while the inbox watcher can't reach the mailbox, is being rate-limited or has 25 replies waiting.\n- **Delegate** (main menu): **Act as me** (where `/delegate` and `/settings/act-as-me` land), **Handle it for me** (which step the dial is at, with **Change in Act as me**, then **What it sent**: how many went today and what it sent this week, as you) and **Take the lead** (the switch, then **Always asks first**, shown even while the switch is off and ending in **Meetings asked for in chat**, and the company's rules, as the Executive). Each switch that turns another off says so beside it. The pause is on **Settings → Your Executive**.\n- **API**: `GET`/`PUT /delegation`, `GET`/`PUT`/`DELETE /delegation/voice`, `POST /delegation/voice/learn`, `POST /delegation/voice/describe`, `POST /delegation/voice/signature`, `PUT /delegation/inbox` (`{enabled?, mailbox_drafts?}`), `POST /delegation/inbox/check`, `GET /delegation/replies`, `PUT /delegation/replies/{id}/text`, `GET /delegation/invites`, `PUT /delegation/handle-it`, `PUT /delegation/reach` (`{step}`, the dial), `PUT /delegation/training`, `DELETE /delegation/learned/{id}` and `GET /delegation/handled` — the caller's own delegation only — and `PUT /delegation/team`, the owner's switch (see API Reference). `GET /what-it-may-do` is the read-only summary above. Send (and an invite's Accept or Decline, with `edits.answer`) is `POST /decisions/{id}/approve`; Dismiss is `POST /decisions/{id}/reject`.\n- **Evals**: a scenario's `delegation:` block runs the turn against an in-memory mailbox (`evals.mailbox.ScenarioMailbox`) and hands the saved drafts to the judge (`delegation_001`–`003`). A `type: inbox` scenario runs the watcher's two model calls on one thread: whether it drafts must match the scenario, and a draft is judged on saying nothing the person hadn't, copying no link or address, and listing every open question (`delegation_inbox_001`–`007`; the last checks a draft never claims anything was sent).\n\nActing within rules the person sets and standing in for them are later, separate changes, each behind its own switch, off by default.",
+ "markdown": "The **delegation** module (`openexecutive.delegation`) is **Act as me**: the one place the Executive writes *as* a person instead of as itself. Everywhere else it has its own Google account and bots and signs as itself. Here — when the person asks, or, with a second switch, for mail in their inbox that needs them — it writes an email in their voice and saves it as a **draft in their own mailbox** — Gmail or Outlook — for them to review and send. The one thing it ever sends is one of those inbox drafts, exactly as it is in their mailbox: when the person taps **Send** on its card, or, with a third switch, **Handle it for me**, on its own when plain-code rules allow it (below). A draft chat wrote as them goes only when they tap **Send** under it in the chat (below); no tool sends. A workflow its creator saved can also write as them: a draft for them to send, or, when they chose **Send as me** when saving it, sent (below). The principal can turn it on for themselves, and so can each team member once the owner lets them. It is off by default, and off changes nothing: the prompts, tool lists and prompt caches are byte-identical to an install without it.\n\n## Who can have it, and when it is offered\n\n`delegation.settings.can_delegate(person)` is the single rule for who may turn it on: the principal (a non-archived team member flagged `is_principal`), and any other non-archived team member — never a contact — once team members may have it (`team_members_enabled`). That takes two things: the install allows it (`DELEGATION_TEAM_MEMBERS`, default off, which offers the owner the switch) and the owner turned on **Let team members use it** (`PUT /delegation/team`, principal only, one row in `delegation_team`). Turning the owner's switch off takes it away from every team member from their next message, and their inbox watchers stop at their next check; their own switches, drafts and cards are kept. Everything is keyed by `person_id`. A person turns it on for themselves (`PUT /delegation`); nobody turns it on for anyone else. The setting is one row per person in `delegation_settings`, and a missing, unreadable or zero row all mean off.\n\nAt the start of every chat turn (`Executive.stream_chat` and the committee path) `pin_turn_delegation(session, speaker_text)` runs next to the workspace-mode pin and records a `TurnDelegation` on the session. `ghostwrite_email` is **offered** only when all of these hold:\n\n- the speaker may have it and turned it on — read fresh every turn, so turning it off applies from the next message;\n- the speaker is on a surface that verified it is them — the principal through `people_tools.is_principal_on_verified_surface`, a team member through `teammate_on_verified_surface` (the web app signed in, their own Slack or Discord, never an email turn) — and a web turn also carried a signed-in caller (`Session.web_caller_signed_in`, set from `x-caller-email`) or runs under local login — a request with no caller header is not a sign-in and never gets it (whoever holds the shared secret is trusted as the UI proxy that stamps that header, as on every principal-only route);\n- the conversation is private to the speaker: the web chat, a Slack or Discord DM, a verified private Telegram chat, or a chat its channel adapter verified the sender of and marked private (`Session.speaker_verified` + `Session.private_chat`) — never a shared channel or thread, where the draft's preview or the matching threads would be posted for everyone and other people's messages sit in the model's context;\n- the turn is neither unattended (the scheduler's proactive run) nor private to the principal (the email poller's turns), so inbound text can never reach it. The MCP server, workflows, reflection and research never carry it at all.\n\nThe mailbox connection is deliberately **not** part of the offer: the handler checks it on every call and says how to fix it, so the cached tool prefix never flips when a token lapses. The pin lives in a context variable for the turn's task as well as on the session, so two turns running at once on one session (a second browser tab) each read their own. It also carries the speaker's own words for the turn (a new email may go to an address they just typed — the turn's message joins the history only once the turn ends), a per-turn draft count, and `touched_mail` (see Privacy). `own_words` reads those words back for every own-words check (addresses here, facts and task assignments elsewhere): it first removes the hydrated `<outbound_reply_context>` backstory by its exact, anchored shape, so a look-alike closing tag quoted inside it cannot pass the rest off as the speaker's, then drops other adapter tag blocks, and returns nothing for a message carrying an attachment.\n\n## The tool: `ghostwrite_email`\n\nIt lives in its own registry (`orchestrator.delegation_tools.DELEGATION_TOOLS` / `DELEGATION_TOOL_HANDLERS`), **never** `_ALL_SKILL_TOOLS`, so no other toolkit can carry it. On a turn it is offered to, the agent loop adds it to the pool *before* the sort and builds that turn's handler map from both registries; on any other turn a call to it is an unknown tool. The handler re-checks the pin and the surface anyway, then:\n\n1. **Caps** — at most 5 drafts per turn, and `DELEGATION_MAX_DRAFTS_PER_DAY` (default 50, at most 1000) per person per UTC day, shared with the inbox watcher (`delegation.caps`). It is counted from `delegation_drafts`, one row of ids per draft saved from either place, with a count kept in the process as a floor in case a row was lost. Each slot is taken before the first await — a round's tool calls run concurrently, so otherwise every call in it would pass the caps before any counted — and handed back if nothing was drafted. If the rows can't be read it refuses rather than guess.\n2. **Marks the turn** — sets `TurnDelegation.touched_mail` *before* its first read of the mailbox.\n3. **Checks the mailbox** — `gmail_status` asks Google or Microsoft whose mailbox the credential opens and compares it with the person's People email, on every call: a roster email can change, and a client slot swaps the roster.\n4. **Finds the thread** — by `thread_id` (checked against the mailbox's own id shape), or a Gmail-style search (`find`; on Outlook, words, `from:`, `to:`, `cc:`, `subject:` and `newer_than:` are kept and other Gmail operators dropped). Several matches return `{status: \"choose\", candidates}` (subject, sender and date — no message text) and draft nothing; none returns `not_found`.\n5. **Sets the recipients in code**, never from the model. A reply goes to the last inbound message's `From` — never its `Reply-To` (a different one is flagged `reply_to_ignored`) — with the thread's other recipients only on `reply_all`. A new email or a forward may go to any well-formed address: it is only a draft, waiting in their own mailbox, where they see who it is to before they send it. An address that is neither on the roster (contacts only when `contacts_reachable_now()`) nor typed by the speaker this turn comes back in `not_in_people`, and the Executive names it for them to check (`delegation_tools.not_in_people`). Mailing-list mail, a thread they replied to last and a reply-all trimmed to 10 recipients are flagged. An address inside a block an adapter added to their message (the backstory hydrated into a DM) is not one they typed, and when the message carries an attachment — a document's inlined text, or a note naming the file — none of its addresses count as typed: neither has an end mark, and a filename is chosen by whoever sent the file, so such an address is named back to check.\n6. **Writes it** (the ghostwriter, below) and saves it with the mailbox client's `create_draft` (Gmail: threaded with `In-Reply-To`, `References` (whole message ids: when the chain is too long for one header the oldest after the thread's first go, never the parent) and `threadId`, and stamped `X-OE-Ghostwritten`; Outlook: Graph's `createReply` on the message it answers, then the text and recipients, and a named property marking it).\n\nThe result is `{status: \"drafted\", draft_id, gmail_link, to, cc, subject, preview, flags, open_questions, note}`, plus `not_in_people` and `check_address` when a recipient needs checking. The link (`gmail.mailbox_link`) is built server-side from a fixed prefix — the thread in Gmail, the draft itself in Outlook on the web — and the note tells the model the preview is the person's draft, to be treated as data. The chat shows an action chip — \"Drafted an email as you to … — in your Drafts\" — that opens it, and only a link under `MAILBOX_LINK_PREFIXES` is ever linked. A sincere \"are you an AI?\" in the thread comes back as an open question for the person to answer themselves.\n\n## Reading their mailbox\n\nFive read-only mail tools ride with `ghostwrite_email` in the same registry (`orchestrator.mail_read_tools`), so they are offered, re-checked and fenced exactly as it is: `search_my_email` (a Gmail-style search through the client's `search_threads`, or with no query the threads that reached their inbox in the last few days through `inbox_message_ids` + `get_message`), `read_my_email` (one thread's last 10 messages, each sender's new text only, drafts left out, with the files attached to them listed by message id and index), `read_my_email_attachment` (one of those files as text: PDF, Word, Excel, CSV or text, up to 20 MB, a scanned PDF converted) and `my_email_awaiting_reply` (their own sent mail from the last 14 days, to at most 10 people besides the Executive, that is still the last message in its thread). They change, label, draft and send nothing.\n\nThe fifth, `my_email_read_before`, lists the threads `read_my_email` opened for the same person before, in this conversation or an earlier one, so a later conversation can open the same email again instead of asking them to search for it. It keeps where, never what (`delegation.mail_reads`, table `delegation_mail_read`): the thread id, its subject and first sender as one line each, the mailbox address it was read from and when, never a message's text, an attachment or a recipient. Rows are the person's own and are listed only from the mailbox open now, newest first, optionally narrowed by words in the subject or sender; anything older than 30 days is never listed and is deleted on the next write, at most 200 are kept per person, and turning Act as me off deletes them all. It opens the mailbox like the other reads, so it sets `touched_mail`, counts as a search, and returns its rows with the same data-not-instructions note. The Act as me addendum tells the model that these tools reach the person's mailbox while any Gmail or Outlook tools of its own account reach only the Executive's, to search theirs (never falling back to its own) for mail sent to them, and to reopen an email from before with `my_email_read_before` and `read_my_email`.\n\nEach sets `touched_mail` and marks the conversation theirs before its first read (`_open_mailbox`, shared with `ghostwrite_email`), so the lockdown below applies from its round on. Each is capped per turn on the pin: 10 searches (`my_email_awaiting_reply` counts as one), 20 thread reads and 5 attachment reads, the slot taken before the first await. In `read_my_email` every message someone else wrote comes back inside its own `<untrusted_content source=\"email\">` block (`content_trust.wrap_untrusted`, which defuses a closing tag in the text); the speaker's own messages — SENT and from their address (`threads.mine`), never a From header alone — are marked \"Yours\" outside any block. An attachment's text comes back in its own `<untrusted_content source=\"attachment\">` block (`attachments.format_attached_text`), parsed in an isolated worker (`knowledge.loader`); unlike a file sent to the Executive it is never added to the company's knowledge. The clients find an attachment by message and position and look its provider id up on each read (Gmail's changes per fetch): Gmail lists a message's files with the message (`MailMessage.attachments`, leaving out images the HTML shows in place), Outlook says only `hasAttachments` until `list_attachments` asks Graph (leaving out inline ones), and `attachment_bytes` reads one; an attached Outlook item or cloud link has no file to read. Results carry a note that subjects, senders and text are other people's words, data rather than instructions. The lockdown refuses tools, not the reply's own text, so what would carry that text out without a click is closed where it is shown: the web chat loads no image from another site, and bot replies go out without link previews (see Integrations).\n\n## Saving a file from their mail\n\nOne more tool rides with the reads: `save_my_email_attachment` (message id and index, as `read_my_email` listed the file) copies one attached file into the storage the Executive itself has connected and shares it with the speaker alone, so they get a link they can open or put in an app. Every call it makes is built in code (`orchestrator.mail_file_save`); the model picks only the attachment. The bytes come from the mailbox client's `attachment_bytes` and never pass through the model, any file type up to 20 MB, under a cleaned name (one line, no path or reserved characters, extension kept). The storage is the one the Executive's own mailbox runs on (`EMAIL_PROVIDER`) when the gateway has that server, else the other: Google Drive through workspace-mcp (`create_drive_file` with `base64_content` into a folder named \"From your email\" in the Executive's My Drive, then `manage_drive_access` granting the speaker's own address the reader role, `send_notification` off) or OneDrive through ms-365-mcp-server (`upload-file-content` into the same kind of folder in the Executive's own drive, with a name no recorded copy has, since an upload overwrites, then `share-drive-item` inviting only the speaker, `requireSignIn`, role `read`, `sendInvitation` off). The folder is always made by the save itself and its id remembered (`delegation_saved_folder`), never found by its name, since a folder someone else made and called that could already be shared with them; when the remembered one is gone or won't take the file, a new one is made and the old id stays recorded. Never a link share, a domain or anyone. Neither connected (or an eval's in-memory mailbox): status `no_storage`, and the model says so and offers to forward the email instead. Saves run one at a time, at most 10 a turn (`TurnDelegation.files_saved`), and the result is the status, the name, where it went and the link (`webViewLink` / `webUrl`); the chat chip says only that a file was saved, never the sender's file name.\n\nIt copies only when the speaker asked in their own words this turn: what they typed (`own_words`, no quoted backstory or attached file's text) must hold one of save, saved, upload or OneDrive, or Drive as a place (\"to my Drive\", \"in Drive\", \"Google Drive\"), checked before a slot is spent or the mailbox opened; otherwise it refuses (`not_asked`) and tells the model to ask them. It stays allowed after the turn read mail (`MAIL_TOUCHED_ALLOWED_TOOLS`): its gateway calls are admitted past the lockdown only as the very objects the handler built (`mcp_gateway.code_built_call`, for its seven Drive and OneDrive tools: folder create, file create or upload, the speaker's share, and OneDrive's `list-drives`), so a model's own `call_tool` on that turn is still refused, and every other gateway gate still runs on them (the acting account, URL fetches, sheet formulas, the share gates' roster check, writes kept to the Executive's own drives).\n\nEach copy is recorded before it is shared (`delegation.saved_files`, table `delegation_saved_files`: the person, the storage, the file id, its name and when; never content or the mail it came from), and the folder in `delegation_saved_folder`. The gateway reads that table on every Google Workspace and Microsoft 365 call: on a turn whose speaker is not the file's owner (the owner is the speaker only when Act as me was offered to them, so a shared chat, a workflow or the poller sees none), a call naming a recorded file id, raw or percent-encoded (OneDrive's `download-bytes` path is decoded by Graph), is refused, and a result, filtered against the table as it stands after the call so a copy recorded while a listing ran is caught too, loses each list entry or line naming one, with any id left masked. It matches ids as text, so a result that names such a file without its id (a notification quoting its title) still shows the name, and a copy someone makes is a new file. The folders are guarded harder, on every turn and for every speaker, the owner too: a model call whose arguments name any recorded folder id, or an OneDrive item path through the folder (`root:/From your email/x.pdf:` or `<folder id>:/x.pdf:`), is refused, so nobody can share, move, rename, copy, list or delete the folder from chat, and folder ids are dropped from or masked in every result; only the save's own code-built calls touch it. When a copy is made but its row can't be written, it is not shared, the save reports `failed` and logs an error, and the copy's id is hidden from every turn, the owner's included, for the life of the process. When the table can't be read, the file tools (`_FILE_TOOL_RE`: Drive, folder, file, Docs, Sheets, Slides and presentation tools, attachment bytes) are refused (fail closed) while mail and calendar run. The rows are kept when Act as me is turned off: the copies stay in the Executive's storage, and the rows keep them out of other people's turns.\n\n## Reading their calendar\n\nA third switch under Act as me, **Read my calendar** (`delegation.calendar`, table `delegation_calendar`: one row per person, absent or unreadable meaning off), lets the Executive read the person's own calendar. The principal's daily briefs read it too: `top_three.read_todays_calendar` merges it with the calendar the Executive reads, listing a meeting on both once. It rides on the same per-person sign-in as their mailbox: `calendar.events` on Google, `Calendars.ReadWrite` on Microsoft, added when they run the connect script with `--calendar` (`scripts/connect-own-gmail.py`, `scripts/connect-own-outlook.py`). The one change it ever makes there is answering a meeting invite (see Meeting invites below); a sign-in made earlier with read-only access (`calendar.readonly`, `Calendars.Read`) keeps reading, and the refresh asks Microsoft for whichever calendar scope the file was minted with. Those scopes are optional, so a mail-only sign-in keeps working for mail; the mailbox clients note the scopes the token refresh reports, and `list_events` raises `CalendarNotGranted` before calling the calendar when the scope is missing (or when the calendar answers 403). Only the person turns it on (`PUT /delegation/calendar`), only while Act as me is on and a one-hour read works; a sign-in without the calendar is refused with `calendar_not_granted` and the command to run. Turning Act as me off turns it off. Changes are audited privately (`delegation_calendar_changed`).\n\n`my_calendar` sits with the mailbox reads, offered and fenced the same way: it refuses while the switch is off (before anything is opened), then takes a search slot, opens the mailbox privately (`_open_mailbox`, so `touched_mail` and the lockdown apply: an invite's title is in the words of whoever sent it) and lists the events from `start` (default today) for `days` days (1 to 31) in the workspace time zone, recurring events expanded and cancelled ones left out: title, start, end, all-day, location, organizer, attendees (25 at most) and the person's own answer, each on one line, with a data-not-instructions note. Google's `events.list` on the primary calendar and Graph's `calendarView` (times asked for in UTC) are its only calls; it changes nothing and keeps nothing. The first week's brief also lists today's meetings from it on the principal's own delivery (see Today).\n\n## Forwarding and reminders\n\n`ghostwrite_email` also forwards: with `forward` (a thread id) and `to`, it drafts a forward of the thread's latest message, or of the earlier one `forward_message_id` names (the one with the files, say, when their own reply came after it), `intent` becoming the short note above it (the ghostwriter writes only the note; the forwarded email's subject, someone else's words, is never put in the intent). Recipients follow the new-email rule (`_new_recipients`: the roster, or addresses the speaker typed this turn). Gmail's draft quotes a forward header and the original's own words under the note and attaches the original's files, up to 10 and 20 MB (`FORWARD_MAX_FILES`, `FORWARD_MAX_BYTES`; any left off are flagged `attachments_left_off`); Outlook uses Graph's `createForward`, which keeps the original and its files, with the note as its comment and the body never patched. It is still only a draft.\n\nThe principal's new email or reply can also carry Google Drive files: `drive_files` takes up to 15 Drive file ids (`drive_attach.MAX_FILES`) (not with a forward; a team member is refused, since the files come from the Executive's own Drive). `orchestrator.drive_attach` sizes each one first and then downloads it with code-built `get_drive_file_permissions` and `get_drive_file_download_url` calls as the Executive's Google account (`mcp_gateway.code_built_call`, so the mail lockdown admits those exact calls). It takes the saved copy only from workspace-mcp's own anchored `Saved to:` line, exactly one, whose name ends in workspace-mcp's uuid (the answer echoes the Drive name first, which whoever shares a file chooses), names the attachment from that saved name, reads the bytes only from the tool download folders, removes the copy, and puts them on the draft under the forward cap's 20 MB. When the turn had read outside content before choosing them, the result asks the Executive to name each file so the person checks it. The file's text never reaches the model, so attaching is not an outside read. A file someone saved from their own mail, or a save folder (`delegation.saved_files`), is refused for anyone else, checked before and after the downloads and failing closed when that record can't be read, and a file that can't be fetched makes no draft. Gmail attaches them in `build_raw`; Outlook uploads each to the new draft (Graph's one-request upload, 3 MB a file, larger ones left off and flagged), and removes the draft if an upload fails. The result lists the attached file names.\n\n`remind_me(text, when)` (`orchestrator.reminder_tools`) rides with the same tools and checks, but opens no mailbox, so it never marks or locks a turn (`MAILBOX_TOOL_NAMES` are the ones that do). It stores the text once cleaned — one line, anything a chat app could turn into a link (a URL of any scheme, an address, a domain-like word, a host and port, an IP address) replaced with \"[link]\", at most 300 characters — with its time (stored in UTC) in `delegation_reminders` (5 a turn, 25 waiting, a year ahead, refused when the person has no channel). When it is due the scheduler sends that text to the person alone, as \"Reminder you set on <date>: …\", running nothing (see Scheduler); the Slack and Discord DMs it may go by turn link previews off. The chat chip shows the text as it will be sent. A reminder that comes due in the person's quiet hours or leave (when `OUTBOUND_RESPECT_QUIET_HOURS` is on) waits unclaimed and goes once they end, rather than being suppressed and lost. It is allowed after mail is read and in later turns of that conversation: it reaches only the speaker, as plain text. `schedule_followup`, which runs a turn with tools and is listed to everyone, stays refused there.\n\n## Approval cards\n\nA turn that read someone's mail may not message anyone, invite anyone or change the roster (see the lockdown above), yet what the mail asks for is often right. `propose_actions` (`orchestrator.action_card_tools`) leaves the speaker a card instead: up to five actions, each spelled out exactly as it will happen, done only when they tap Approve. It rides with the other Act as me tools and checks (`_writer`), opens no mailbox, and is allowed after mail is read because it does nothing on the turn.\n\n- **Kinds.** `invite` (a meeting with people on the roster), `message` (a direct message to someone on the roster, as written) `add_contact` (a new contact; the principal's cards only, since contacts are theirs) and `drive_files` (rename and/or move up to 25 Google Drive files; the principal's cards only). A `drive_files` action always waits for the tap, which is its approval: it runs each change as a code-built `update_drive_file` (`MCPGateway.tapped_drive_change`, `tapped_drive_call`), so the own-file check looks only at the folder it goes to, and a move takes the file out of the folders it was in. The card shows each file's current name and the folder's, read when it is proposed; when Drive isn't connected or a name can't be read, no card is made. A team member's card can't name a contact. Each action is checked when the card is made (`delegation.action_cards.check`) and again when it is carried out, so an archived person or a time that has passed fails that action alone.\n- **Whose.** A card is a `delegation_actions` decision for the speaker, `approver_only` like a reply card: only they see it (`GET /delegation/actions`) or resolve it, a team member's answers 404 to the principal too, and it is never an alert. The same actions still waiting are that card, not a new one. 3 cards a turn, 25 waiting, dropped after 7 days.\n- **Approve.** In the chat, under the reply that left it (the `propose_actions` chip carries the card's `decision_id`, and `ChatActionCards` shows the card while it waits), and on the Briefing's Needs you list, with a box per action. Approve (`POST /decisions/{id}/approve`, `edits.only`) needs the card's person signed in (`verified.caller_refusal`) with Act as me on; the card is claimed first so it runs once, then each ticked action runs as stored with no model call, in an unattended session (the principal's with contact egress) under `rows_for_person`, so every audit row it writes is theirs and nothing reaches the team's activity rail: `message_person` (a direct message or nothing; never its Briefing-alert fallback, which more people read), `create_calendar_event`, or a contact row. Approving also needs the person still allowed Act as me (`can_delegate`) and switched on. An invite is booked straight away when the person approving is the one the meeting gate would ask (`calendar_tools.approved_by`), and otherwise goes to that approver as usual, so a card never widens anyone's authority. Per-action results (`done`, `waiting`, `failed`, `skipped`) are kept on the decision and shown on the card. Dismiss rejects it and does nothing else. With Suggested actions in training the card adds the *Do this on its own next time* tick, and a card of actions all allowed is carried out on its own (see In training above); with Suggested actions On, any card that reaches nobody new is.\n- **Channels.** A card can come from any surface Act as me runs on; it is approved in the web app, since the chat apps have no buttons here.\n\n## The ghostwriter\n\n`delegation.ghostwriter.compose` writes the text. The Executive decides *what* to say (`intent`); this call decides *how* the person would say it, and it is deliberately small:\n\n- a constant `GHOSTWRITER_PROMPT` plus the person's voice block as the system prompt;\n- the thread (each message cut to its sender's own words, every line scrubbed, all labelled alike), then the writer's own earlier words in it (`<writer_said>`, from their sent mail only), the intent and the recipients' names in the user turn — no company profile, memory or roster;\n- with Always in the loop on, `<writer_noted>`: what the writer's own notes say they told these same people in earlier Act as me replies (`memory.history_drafts.notes_for_draft`: only notes from mail **every** recipient of the new draft was on, so nothing told to one person reaches another; chat notes name no recipient and never qualify; at most 8, newest first, the person's own words or their correction, with dates). The prompt's rule 6 makes it a consistency check, never content: a draft that contradicts it is still written as the intent says, and the conflict becomes an open question on the card, which only the writer sees. Both the chat tool and the inbox watcher pass it;\n- **no tools** but the forced `compose_reply` return, so text in the thread can ask for anything and there is nothing to do it with.\n\nIt is not a Council agent — the Council's edit routes have no principal check — and runs on `DELEGATION_COMPOSER_MODEL` (default: the default model), logged as `ghostwriter` usage. `lint` then runs in code on what comes back: a link or an email address survives only if it appears in the intent, the signature or the recipients, so a link planted in the thread is removed and flagged; the Executive's own name is flagged; and the body is capped, cut at a paragraph, line or word break in its last fifth. A draft with nothing left after that is refused. The signature from the person's Gmail settings (or the one already stored, for Outlook) is appended.\n\n## How I write\n\n`delegation.voice` learns how a person writes *their own* email (`attunement.style` learns how the Executive should write *to* someone). `POST /delegation/voice/learn` reads up to 40 recent sent messages, keeps only what they wrote (quoted replies stripped with the email poller's `sender_new_text`), skips automatic mail, every thread chat drafted into, and every sent message that began as a draft written for them (`delegation_drafts.sent_message_id`), and makes one forced-tool call (`record_voice_profile`). Code validates every field before it is stored:\n\n- greetings per audience (their team, their contacts, anyone else), a sign-off of at most two lines, and a usual length and tone (a backslash-n the model wrote instead of a line break is read as one, keeping the first lines that fit, which also repairs a profile stored before that rule);\n- up to 8 habits and 6 things to avoid, through the same deny-list as working-style rules — no actions, links, handles, amounts, tool names or names of people; the conversation review (`memory.chat_review`) adds one when the person states how they write in a chat (`add_conversation_rule`, `updated_by=conversation`; never on a locked or full list, and an edit or lock made meanwhile wins);\n- up to 3 short exemplars, each checked to be verbatim from a sample, with addresses and phone numbers masked — and none while a client slot is active, so one client's mail never lands in another's state.\n\nThe signature comes from Gmail's `sendAs` settings, not the model (Outlook gives apps no way to read one, so a learn keeps the stored signature and `POST /delegation/voice/signature` answers 409 `signature_unavailable` rather than clearing it), as plain text with its lines kept (`gmail.html_to_text`: a `<br>` always ends a line, and a block tag, opening or closing, ends one when it has text, so Gmail's layout of a first line followed by one `<div>` per line comes out line by line). `POST /delegation/voice/signature` reads it again without relearning: nothing else changes and a locked profile stays locked, so it picks up a changed Gmail signature and undoes **Don't add my signature**. A person can also describe their style in their own words: `POST /delegation/voice/describe` applies the description to the profile they have through the same forced tool (a separate system prompt, no exemplars) and the same validation, keeps their signature and writing examples, and returns the result with a short sample reply for them to review. It saves nothing and needs no mailbox; Save stores it as an ordinary edit. The person can edit the profile, lock it (a locked profile is never relearned) and reset it, and every change is kept in `delegation_voice_history`. One learn runs at a time per person, and a lock or an edit made while it runs wins: the learned profile is dropped (`changed`).\n\n## Draft replies to my inbox\n\nA second switch under Act as me, **Draft replies to my inbox** (`delegation.inbox`), has the Executive watch the person's own inbox and write a first reply to mail that needs them. The reply waits on a private card on Today; nothing is sent until they tap **Send** (below). Where the reply lives is the person's choice, **Also save replies in my Gmail Drafts** (`mailbox_drafts`, off by default): off, it lives on the card alone (`delegation.card_drafts`: the card keeps the draft's recipients, subject and thread headers as `draft_spec`, and Send makes the mailbox draft from exactly that just before the send-time checks, taking it back out if they refuse), so their Drafts folder doesn't fill with replies they may never send; on, it is also saved in their Drafts as before. The switch is one row per person in `delegation_inbox_watch`. Turning it on needs Act as me on and their mailbox connected, and sets `watch_since` to now every time, so it never drafts for mail that arrived before; turning Act as me off turns it off too. Off means no mailbox call and no row written, with one exception: a send the person started that the mailbox never confirmed is still followed through until it is settled.\n\n### When it looks\n\nA throttled hook in the scheduler tick (`_maybe_scan_inbox`, after the pause, company-profile and rotation gates) checks each person whose switch is on every `DELEGATION_INBOX_POLL_MINUTES` (default 5). It is not a scheduled action, because those are listed on `/scheduled` for everyone and anyone may cancel them. One scan task runs at a time, one scan per person, and none while a client slot is active. **Check now** on the Settings card runs the same scan. Every row a scan writes is private and the person's own (`audit.rows_for_person`: a team member's rows are hidden from the principal too, see Privacy), and the process log carries counts and codes, never an address or a line of mail. The scan never marks mail read or changes a label.\n\n### What it drafts for\n\nA scan first settles the open cards (below), and stops with `backlog_full` once 25 are waiting, counting the ones it makes. It then lists the inbox since `watch_since` (`inbox_message_ids`) — not chats, not mail from the person, and not the promotions, social, updates or forums tabs (on Outlook: the Focused inbox only) — up to 100 messages, and takes the newest message of each thread that still needs a look, at most 10: settled threads and threads with an open card are passed over first, so a burst of mail, or a pause for a limit or a back-off, never hides older threads for good. `delegation_inbox_messages` is its durable cursor: one row per message (`UNIQUE(person_id, message_id)`) with what happened to it, the reason, how many tries it took, and the draft and card ids. It stores a hash of the sender's address, never the address. A message is skipped, with the reason recorded, when:\n\n- it came before `watch_since`, or more than three days ago;\n- it is from the person or one of their send-as addresses, from the Executive, or one of this module's own drafts;\n- it is automatic — `Auto-Submitted`, a bulk or auto-reply `Precedence`, a bounce, a calendar invite or a no-reply sender — or from a mailing list, or in a Gmail tab, spam or trash (with Read my calendar on, a calendar invite goes to `delegation.invites` instead: see Meeting invites);\n- the person is not in To or Cc, or it has more than 10 recipients;\n- the person replied last, or a draft already sits in the thread.\n\nThree kinds are left unrecorded, so a later scan looks again: mail under 10 minutes old (mail the person answers straight away never gets a card), mail in a thread whose card is still open, and mail a daily limit holds back.\n\n### Deciding, then writing\n\nTwo model calls, and code decides between them. The classifier (`delegation.inbox_classifier`) is one forced-tool call, `classify_email`, returning whether the email needs a personal reply, what kind it is and how sure it is. It sees a few one-lined header lines and the sender's own new words (at most 3000 characters, every line scrubbed) inside one `<email>` block marked as data, after the person's own last email in the thread in a `<their_last_email>` block (`their_last_words`: only mail their own mailbox sent, at most 1500 characters), so a reply to something they asked reads as one: an answer to their request for a call that says when the sender is free, without settling a time, is scheduling and gets a draft even when the sender says they will come back with times, and an email that delivers what they asked for (the document or figures, often attached) is a follow-up that needs a short reply even when it ends \"let me know if you have any questions\". The header lines name the email's attachments (up to five, or \"yes\" when Outlook only says there are some). It has no other tools, context or memory, so an email can ask for anything and there is nothing to do it with. A reply is drafted only for a question, a request, scheduling, an introduction or a follow-up, and only when the confidence clears a bar that rises the less the sender is known: 0.6 for their team or a contact (the principal's contacts count only for the principal: a team member's mail is weighed by the team and their own sent mail), 0.7 for someone they have written to before (`has_written_to`, a search of their sent mail), 0.85 for a stranger. Pitches, notes of thanks, FYIs, notifications, newsletters and phishing get nothing, and so does any failure. The person can still ask for one: Home's **Reply** on a Right now point (`POST /delegation/mail/reply`, `inbox.draft_on_request`) skips the verdict, returns the open card already on that conversation when there is one, and otherwise writes the reply through the same steps and limits as the watcher (`_draft_card`), always left on a card for them, never sent on its own under Handle it for me. An email that also went to other people is drafted for only when the person is in To and it asks them themselves: the classifier is told their name, whether they are in To or Cc and how many others it went to, and lists the names the email greets or asks by name (`asked_names`). Code matches those against the person's name, whole name parts only (\"Alexis\" never counts for \"Alex\", and a nickname misses, which means no draft), so mail that greets someone else (\"Good morning, Brennan, could you sign ...\") is never theirs, whatever the model makes of it as a whole. When it names nobody, the model's `asked_of_them` decides, false for a question to the group at large. One that only copies them is never drafted for. Either is recorded `not_needed` with the reason `asks_someone_else`. It runs on `DELEGATION_CLASSIFIER_MODEL`, else the routing model. A sender whose address Gmail couldn't authenticate is handled as a stranger whatever the roster says — anyone can put a colleague's or a client's address in From — so they get the stranger's bar, a holding reply and the stranger limits; the card still says who they claim to be, and that the address isn't verified.\n\nThe reply is written by the same ghostwriter, in the person's voice, but from a fixed intent the module builds rather than words the person typed. Because the intent lets it restate the person's own earlier words, which words are theirs is never written inside the thread, where a sender could imitate any marker with a look-alike: every message there is labelled alike, and the person's own words come in a separate `<writer_said>` block after the thread, taken only from mail their own mailbox sent. Nothing inside the thread can close the thread block or open another. The intent: acknowledge the sender; say again only what the person's *own* earlier messages in the thread already said; commit to nothing new — no yes or no, date, time, price, fact or promise — and say they will get back to them; and put every question it could not answer from their words in **open questions**. A stranger always gets a short holding reply. The lint still strips any link or address that isn't the person's own. The reply goes to the sender (never `Reply-To`) and, on a group email, to everyone else it went to as Cc (reply to all, never the person's own addresses or the Executive); a stranger's holding reply starts with the sender alone. When others were on the email the card offers **Reply to**: the sender only, or everyone (`PUT /delegation/replies/{id}/recipients`, `card_drafts.set_recipients`). It picks between the two lists fixed when the card was written (`reply_others`), never an address from the request, and changes the mailbox draft's To/Cc too. Its `draft_to` lists who it goes to, which Send checks.\n\nThe order: record the message, classify, reserve a slot in the shared daily limit, write, save the draft in Gmail (from the alias the mail went to, when it went to one) and store its id, then create the card (idempotent on the message: a second call finds the open card, and a card dismissed or lapsed under that key doesn't stop a new one, while one sent or settled in the mailbox means no second card, `invites.create_once`) and mark it drafted. Nothing that fails along the way loses the message. A failure that may pass — the classifier or the writer failing, Gmail refusing the draft, a card that couldn't be made (its draft is deleted first, so no draft is left without a card), any other error with that one message — leaves it for a later scan (`retry`), and it is given up on only after three tries; one message's trouble never holds up the rest. A daily limit reached while it was being read leaves it for later without counting as a try.\n\n### The reply cards\n\nA card is a `delegation_reply` decision whose class is **its approver's alone** (`DecisionClassSpec.approver_only`): only the person it was drafted for sees or resolves it on any decisions route — a team member's card answers 404 to the principal too — and it is never an alert: alerts feed chat turns, which would put other people's mail into memory. It carries the sender with who they are to the person and whether Gmail could verify the address (SPF/DKIM/DMARC, through `fact_confirmation.headers_authenticated`), the subject, what they wrote, the draft, the open questions and its warnings. `GET /delegation/replies` lists the open ones from the database alone, so Today never waits on Google.\n\n- **Send** approves the card, which sends its draft exactly as it is in their mailbox (see *Send on your tap*). **Edit** changes the reply's words right on the card (`PUT /delegation/replies/{id}/text`, `card_drafts.edit`): only its own person, from a caller the API can tie to them (as for Send), never while it is being sent on its own; a reply in their Drafts is rewritten there too (`update_draft_text`, every header kept), and only while it is still the version the card last saw, so a change made in the mailbox is never overwritten. A card edit counts as edited (`approved_with_edit`, and **Do it like this next time** keeps it), and one made by hand sets `questions_settled`.\n- **Decide before sending** with taps (`delegation.answers`): the ghostwriter returns each open question with 2 to 4 short answers the person might pick (`choices`) and what it is `about` (time, document, other); plain strings still parse, and `open_questions` stays a list of strings for every other reader, with `question_choices` beside it on the card. After the draft is written, code fills two kinds: a time question gets up to 3 free half hours on the person's own calendar (Read my calendar on; one a day over the next 5 working days, busy times only, no event title reaches a model), \"I checked your calendar: these are free.\"; a document question whose words match a company document's name gets 'I'll send \"<name>\" separately', \"Found \"<name>\" in your documents.\" Nothing is attached: a card's draft is plain text. A tap, or **Something else…**, calls `POST /delegation/replies/{id}/answer` (and **Tell me what to change…** calls `POST /delegation/replies/{id}/change` with their own words, which go to the same rewrite as `<change>`; their words and the Executive's note on what it changed join the card's `conversation`): one composer-model call rewrites the body with the answers in their voice (signature and AI line kept out and put back), `ghostwriter.lint` runs on it, and it is saved through `card_drafts.edit` with the same caller and card checks and the same Drafts update. It returns the card with `changed_sentences`, which the card lightly marks. 30 rewrites an hour per person (429). Send waits until every question with choices is answered, or the words were changed with Edit. A card made before choices shows its plain questions. **Open in Gmail** (or **Open in Outlook**), shown only when the reply is in their Drafts, opens it there.\n- **Dismiss** rejects the card; the class's after-reject step then deletes the draft if nobody edited it — its message id is still the one it was saved with, since Gmail gives an edited draft a new one, and the Outlook client makes a draft's message id `<id>.<changeKey>` so an edit there changes it too — and keeps it otherwise. What happened is recorded even when Gmail fails.\n- Each scan first **settles** what Gmail already settled: a draft sent from Gmail, a draft deleted there, a reply the person wrote themselves, a thread that is gone, or a card left for 7 days (its draft stays in Gmail). Each is a compare-and-set close with the reason. A newer message from someone else brings the card up to date instead (`answers.catch_up`): one composer-model call rewrites the draft with it as `<news>` (data, never the person's facts; a decision only they can make comes back as a new question to tap), saved through `card_drafts.redraft` (the card checks without a caller, since nobody tapped), and the message and the Executive's one-line note join the card's `conversation`. Send then counts newer mail from `caught_up_at`, and asks a second yes unless the card that was tapped showed that version (`edits.seen_caught_up_at`; the card refreshes beside the question). A new question's choices never carry a link or address. Past `MAX_CATCH_UPS` messages on one card, or when the rewrite fails, it only flags the card (`thread_moved_on`), as before. A card being sent at that moment is left alone.\n\n### Send on your tap\n\n`delegation.reply_send` is the only thing in Act as me that sends, and all it can send is a draft by its id (on a card, or written in chat or by a workflow): `DelegateGmail.send_draft` posts `{\"id\": …}` to Gmail's `drafts.send`, and `DelegateOutlook.send_draft` posts an empty body to that draft's Graph `send`, and nothing else, so no text, recipient or header is ever passed. It has four doors: `send_approved_reply`, reached only from `POST /decisions/{id}/approve` — a class only the card's own person may resolve — `send_on_its_own`, reached only from the inbox watcher under Handle it for me (below), `send_for_workflow`, reached only from a workflow step's `oe__send_email_as_me` (below), and `send_chat_draft`, reached only from `POST /delegation/drafts/{id}/send` (Send under a chat draft, below). AST tests pin all four call sites, so no model, chat turn, scheduled job or MCP call can, and a workflow only through that one tool. A tap is checked like this: At send time it checks everything again:\n\n1. **Who is asking.** The caller is the card's person and the API knows it: signed callers are on and the request carries that person's signed assertion (or the operator's, under local login), or the API runs for local login and answers this computer only. Anything else is a 409 `caller_signing_required` — with only the shared secret, whoever holds it could send as the owner — so on a server Send needs signed sign-ins.\n2. **The switches.** Act as me and Draft replies to my inbox are on, and no client slot is active.\n3. **The mailbox.** Their mailbox is connected.\n4. **The draft.** It still exists, in the same thread, and they haven't replied there themselves since; otherwise the card closes.\n5. **Who it goes to.** To, Cc and Bcc hold between 1 and 10 addresses, never the Executive's own, and it is from one of their own addresses.\n6. **What changed.** Recipients that differ from the card's, or a newer message from someone else, need a second yes: the first tap gets a 409 `confirm` naming the recipients and the reason, and the person approves again with what they were shown.\n\nThen it claims the card (`claim_for_execution`, proposed → executing, a compare-and-set, so a double tap sends once) and reads the draft once more: `drafts.send` sends whatever the draft is when Gmail gets the request, so if it was edited since the checks read it — in another tab, by a delegate — nothing is sent and the card comes back (`draft_changed`). Then it sends, and records the result: `approved_with_edit` when the draft was edited in Gmail, the sent message's id, the draft row's `sent_message_id`, and a private `delegation_reply_sent` row. A refusal that proves nothing went — a 4xx, a lapsed sign-in, a rate limit, a draft already gone — hands the card back. A failure that leaves it unclear — a timeout, a 5xx — leaves it `executing` and says to check the Sent folder, and the next scans ask Gmail: their message in the thread means it was sent; anything else is judged on the second scan that sees it: the draft still there and nothing sent means it was not (Gmail deletes a draft it sends), and the card comes back, flagged; the draft gone and nothing sent means it was deleted. Nothing is ever retried on its own. Sending is the person's own act, so it works while the Executive is paused.\n\n### Limits and failures\n\nAt most 5 drafts a scan; `DELEGATION_INBOX_MAX_DRAFTS_PER_DAY` (default 20) a day, inside the shared `DELEGATION_MAX_DRAFTS_PER_DAY` it shares with chat; 200 classifications, 2 drafts per sender (1 for a stranger) and 10 for strangers in all per day; and never more than 25 open cards. A lapsed Gmail sign-in sets the status and is looked at again every 30 minutes; a rate limit, an error reaching Gmail or a crash backs off from 5 minutes, doubling up to 2 hours. Neither turns the switch off: the Settings card shows the status in plain words.\n\n## Handle it for me\n\nA third switch under Act as me, **Handle it for me** (`delegation.handle_it`), lets the inbox watcher send some of its replies itself instead of leaving them on a card. It is one row per person in `delegation_handle_it` (`enabled`, `mode`); no row means off. One setting says how much goes without them, the way quality does on the Agent Council (`handle_it.RULES`): **Easy ones** (`careful`) sends only replies to people they know (someone on their team, a contact or someone they have written to) of at most 400 characters when the classifier is at least 0.9 sure; **People I know** (`balanced`), where it starts, sends replies to people they know up to 1200 characters at 0.8; **Most mail** (`bold`) also answers strangers, up to 2000 characters, and lets a link or an amount through when the classifier is at least 0.9 sure. Everything else waits on a card as before, so turning it on never drafts less. A table from before the setting gets the `mode` column on its next open (`schema._add_handle_it_mode`): someone who had strangers set to send keeps that as Bold, everyone else gets Balanced. Only the person turns it on (`PUT /delegation/handle-it`), from a session the API knows is theirs: the same rule Send uses (`delegation.verified.caller_refusal`), so with only the shared secret it answers 409 `caller_signing_required`. Turning it on needs Act as me and Draft replies to my inbox on, and turning the inbox watcher off (or Act as me, which turns it off) turns it off too.\n\n**In training** (`delegation.training`). Like someone new, each Act as me job can be put in training on its own, from that job's card on the Act as me page, the way Take the lead has it: **Write drafts as me** and **Handle it for me** each pick Off / In training / On (Handle it's In training puts Replies and Follow-ups in training together; its steps show under On only, since in training only allowed people go whatever the step), and **Suggested actions** picks Always ask / In training / On (On is the `actions_on` switch: a card is carried out with no allow, under the same checks, and only when it reaches nobody new: a new contact or anyone on the roster under a week waits; In training wins when both are set); what it learned is listed on each tab for its own jobs (Act as me: *What it's learned*, drafts and suggested actions; Handle it for me: *Who it's allowed to handle*, replies and follow-ups), each item named by its job (`PUT /delegation/training`, one row per person and setting in `delegation_training`, absent means not in training). In training it asks first and learns who and how from what the person approves; what it learns is a `take_the_lead_allowed` row (feature `act_as_me`, the person's id), theirs alone.\n\n- **Replies.** Every reply waits on its card (`handle_it_reason` `training`) whatever the dial says, and a reply card adds **Send + allow**: it sends that reply on the person's own tap, exactly as Send does, then allows replies to that sender (key `act_as_me|person:<id>|reply|<address>`). While Handle it for me is on, a reply to an allowed sender goes on its own under the dial's limits (a stranger they allowed included) and every check above (the topics that always wait, links and amounts, new recipients, once a thread a day, the daily limit); it's checked again at send time, so a sender removed since waits. Take the lead as you lifts nothing in training: putting Replies or Follow-ups in training turns it off, and it can't be turned on while they are (409 `in_training`).\n- **Follow-ups.** Every follow-up waits (`follow_up_training`); Send + allow on a follow-up card allows follow-ups to exactly the people it went to (`…|follow_up|<sorted addresses>`), whoever they are, under every other follow-up check.\n- **Suggested actions.** An action card (below) adds **Approve + allow**: it does the actions on the tap, then allows each one that happened (a message to that person, `…|message|person:<id>`; a meeting with exactly those people, the person left out, `…|invite|people:<ids>`). A new contact is never allowed. A card proposed later whose every action is allowed is carried out at once, with no tap (`action_cards.run_on_its_own`, `gate_mode` `auto_execute`, status `executed`), only if plain code finds nothing against it (`on_its_own_refusal`): still in training, Act as me on, a server that ties the switch to the person, nothing sensitive, no link or amount, a message of at most 1200 characters, and at most 10 actions carried out this way a day (checked one card at a time); anything refused is handed back to wait on its card as before. An invite carried out this way is never booked as approved by the person: the meeting gate decides as for any meeting nobody tapped, so a time taken from someone's mail can't land on a calendar unasked. The tool result and chip say what was done. The message text in such an action is model-written from the mail and goes without anyone reading it; the allowance covers who and what kind, not the words, which is why sensitive topics, links, amounts and long messages are held back.\n- **Drafts.** Nothing is sent. When the person changes a reply's draft in their mailbox before tapping Send (plain or + allow) and ticks **Do it like this next time**, what they sent is kept (its new text, quoted replies dropped, at most 1000 characters, `…|style|<address>`), and the ghostwriter gets it in its user turn as `<writer_example>` when it next writes to that person, from the inbox, a follow-up or a chat draft to that one person: style only, never its facts, and nothing in it can open or close a tag.\n\nSend and Approve with the *on its own next time* tick (`allow`; the tick replaced the separate Send + allow and Approve + allow buttons) are refused before anything is done unless their setting is in training (422 `cant_allow`) and the person's list has room (409 `learned_full`, at most 200 a person); allowing failing afterwards never undoes the send. Putting Replies or Follow-ups in, or Suggested actions out of training or On, only holds more back and works without signed sign-ins; anything else needs a caller the API knows is that person. What it learned is the person's alone: listed on `GET /delegation` (`training.learned`, each with its `setting`), removed with `DELETE /delegation/learned/{id}`, and for the owner also in Take the lead's \"What it's learned\" list; it never reaches anyone else's list or Take the lead's prompts. A dial left on In training by an older version (mode `training`) moves to People I know with Replies and Follow-ups in training (`schema._move_training_off_the_dial`).\n\n**No model decides whether a reply goes.** The watcher's two model calls are unchanged and tool-less, so text in an email can at most change the verdict and the draft. After the draft is written, `handle_it.refusal` — plain code — decides, and anything it refuses becomes the usual card with the reason kept on it (`handle_it_reason`). It refuses when:\n\n- it's off, or the sender is a stranger and the setting isn't Bold, or on a server signed sign-ins are off (`signing_ok`: signed callers, or local login);\n- Gmail couldn't authenticate the sender, whatever the roster says;\n- the email isn't a question, request, scheduling, introduction or follow-up, or the classifier was less sure than the setting needs (0.9 on Easy ones, 0.8 otherwise);\n- the reply goes to anyone the email didn't already go to (its From, To and Cc, less the person's own and the Executive's addresses), leaves out the sender, or goes to more than 10;\n- the email's subject, the sender's new words, or the reply touch money, contracts, legal, hiring, pay, layoffs, the board, investors, mergers, the press, health, or credentials and secrets (passwords, logins, tokens, API keys); or the reply carries an amount, a percentage or a link (a scheme, `www.`, a bare host with a path such as `bit.ly/…`, or a bare host on a common top-level domain) unless it's Bold and at least 0.9 sure, or runs over the setting's length (400, 1200 or 2000 characters);\n- the draft carries any flag but *others on the thread* or *Executive on the thread* (they asked if it's an AI, recipients were trimmed, …);\n- it already sent one in this thread in the last day, or the person's last message in the thread was itself sent on its own (no auto-reply ping-pong);\n- the day's limit is reached (`DELEGATION_HANDLE_IT_MAX_SENDS_PER_DAY`, default 20, within the watcher's drafts limit), or it can't be counted. Any error in the rules counts as a refusal.\n\n**Workflows that email as their creator** (`delegation.workflow_email`). A workflow step can write an email in its creator's voice with `oe__draft_email_as_me` (a draft in their mailbox for them to send, counted and named in the briefs like a chat draft) or `oe__send_email_as_me` (sent). Which one a step lists is the choice the creator makes when they save it; the gateway's mail tools still send from the Executive's own address. Both write only as the workflow's creator (`dynamic_store.get_owner`), never an address the step names, and refuse a run someone else started by hand, a speaker the roster can't place, a run one of the Executive's own unattended passes started (reflection, research, a proactive run: `chat_tools.started_by_a_pass`, inherited by nested workflows), or a run another person's workflow started (`chat_tools.running`); a scheduled run writes as the creator. The creator must be allowed Act as me, have it on and have their own mailbox connected, or the step is told to use the Executive's own email. `to` and `cc` are write targets (`action_step.TargetPolicy`). The creator's own addresses and the addresses in the saved goal of a step that emails as them, nowhere else in the workflow (`workflow_email.chosen_recipients`; only its verified creator saves one, and a definition that differs from the saved copy gets none) go without asking; the first email to any other address waits for the creator's approval and is then remembered. Every email counts against `DELEGATION_MAX_DRAFTS_PER_DAY`, and sends against `DELEGATION_WORKFLOW_MAX_SENDS_PER_DAY` (default 20) as well, counted from `delegation_drafts` rows with source `workflow_sent` (written before the send, so a failed send still counts). Sending needs more: a workflow with `oe__send_email_as_me` can only be created, changed or switched on by its creator from a session the API knows is theirs (`workflow_email.save_refusal`, the `verified.caller_refusal` rule Send uses; a 403 otherwise, from `POST`/`PUT /workflows/custom`, save-edit and activate), and chat's `save_workflow` never replaces one, so nobody else can change what it sends. At send time `reply_send.send_for_workflow` checks again that Act as me is on, `handle_it.signing_ok`, no client slot is active, and the draft it just wrote is unchanged: addressed exactly as written, from one of their own addresses, at most 10 recipients and never the Executive's own address. A send the mailbox didn't confirm is reported as possibly sent and never retried. The step's result (and so the run's report) names who it went to and the subject, never the body; the audit rows (`delegation_drafted`, `delegation_workflow_sent`, `delegation_workflow_send_refused`) are the creator's alone. The workflow designer is told whether the person designing it can have email written as them, and to ask when it isn't clear whether an email should come from them or from the Executive.\n\n**Workflows that read their creator's mail** (`delegation.workflow_reads`). A step may also read the creator's own mailbox and calendar with `oe__search_my_email`, `oe__read_my_email`, `oe__my_email_awaiting_reply` and `oe__my_calendar`: chat's own reads (`mail_read_tools`), run as the workflow's creator through `AS_CREATOR` in place of the chat turn's speaker, with the same per-call caps and the same untrusted-content marking. They read only on a run that is the creator's: started by them by hand (`turn_owner` is them) or by its schedule, and only in the outermost workflow (never one another workflow started, whose later steps would see the mail), never on a run an unattended pass, an inbound message or someone else started. Act as me must be allowed and on and the mailbox connected; `my_calendar` also needs Read my calendar on. Outside chat, the principal's Right now reads their sent mail for the emails nobody has answered yet (`briefing.waiting_on`) whenever Act as me is on and their mailbox opens: recipients, subject and time only, never a body. The inbox watcher also notes each message it looks at (and newer mail on a thread whose card is still open) as a private `delegation_inbox_mail` audit row, sender, subject, time and how well the person knows the sender, never a body, which the principal's Right now reads (`live_signals.own_inbox`). Turning Act as me off drops that read (`settings.set_enabled`). Such a run is the creator's alone: the scheduler creates a scheduled run as theirs (`owner_person_id`, viewer pinned to them), delivers its report and any failure card to them whatever the cadence names, the run route returns 403 to anyone else, and every audit row the run writes (scheduled, from the Jobs page, from chat or resumed, its report's delivery included) is theirs alone, with no send on the shared activity rail (`workflow_reads.private_run`, `rows_for_person`). Chat's `run_workflow` starts one only for its creator on a turn Act as me was offered on, and first marks that turn as one that read their mail (private, and locked down for the rest of it), since the report comes back into it. The lockdown a chat turn gets after a read covers the whole workflow, checked when it is saved (`definition_refusal`, also in chat's `draft_workflow`/`save_workflow`) and at every step (`run_rules`): its steps may list only the reads, the email-as-them tools (`workflow_email.TOOLS`: a send goes without asking only to an address the creator chose, so mail text naming another address gets a card first) and chat tools in `MAIL_TOUCHED_ALLOWED_TOOLS` (no gateway, extension or web-search tool, no `run_workflow`, nothing that posts to everyone), get no `run_script`, and may have no approval gate asking anyone but the creator and no cadence reporting to anyone else. Like one that sends, a workflow that reads can only be created, changed or switched on by its verified creator (`workflow_email.save_refusal`).\n\nA reply the rules allow gets a card with `gate_mode` `auto_execute`, and the watcher sends it at once through `reply_send.send_on_its_own`, the second door into the send path (an AST test pins its callers: the approve route, the watcher, a workflow's `oe__send_email_as_me` and the chat draft route). It runs the same send-time checks as a tap — switches, mailbox, draft, recipients, the claim and the last re-read — with no caller, and adds its own: the card must be `auto_execute`, Handle it for me still on with the setting still allowing that sender (or, for a follow-up, that recipient), signing still on, the once-a-thread-a-day rule and the daily limit counted again, and the draft untouched since it was saved (an edit in Gmail means the person has taken it over: `draft_changed`, the card waits for them). Every refusal hands the card back to the person (`decision_ledger.hand_back`, a compare-and-set to `propose`), with the reason kept on it when there are words for it, and a failure never stops the scan. Every card it left for the person says why on Today (`waited_because` on `GET /delegation/replies`). A reply sent on its own finishes as `executed` (not approved), is recorded in `delegation_handled` (for the per-thread and daily rules) and writes a private `delegation_reply_handled` row; an unconfirmed one is settled by the reconciler the same way. No History note is taken from it, since notes come only from the person's own words. It runs inside the watcher's scan, so it stops while the Executive is paused.\n\n**The last look** (`delegation.injection_check`). A reply the rules would let go gets one more check before it goes: one small classifier-model call, with no tools, reads the sender's own words as plain text (up to 20,000 characters, far more than the classifier) and says whether they carry instructions meant for an assistant rather than the person (to ignore its rules, forward or quote other mail, reveal what it knows, reply somewhere else, or a passage addressed to the assistant). Styling is gone by then, so hidden text is judged by what it says. A yes, a failed call or a malformed answer keeps the reply on its card (`handle_it_reason` `suspicious`). It only ever holds back, on top of the plain-code rules, never instead of them.\n\n**Answering from a workflow** (`delegation.workflow_reply`). A workflow step can hand one thread to the same path with `oe__answer_email_as_me`, passing only `thread_id`: `inbox.answer_thread` takes the newest message not from the person and runs it through the watcher's own `_consider` (classifier, ghostwriter, Handle it for me's rules, the last look, the limits and the once-per-message ledger, so the watcher never answers it twice), bounded only by staleness rather than when the watcher started. The step can't choose the words or the recipients: the reply goes to the people the email already went to, sent on its own when the rules allow and otherwise left on the usual card. It refuses while a scan is running or the backlog is full, writes only as the creator on their own run (`workflow_email.creator_mailbox`), counts as a send for who may save the workflow (`workflow_email.sends`), and may be used in a workflow that reads mail.\n\n**Follow-ups as you** (`delegation.follow_ups`). While Handle it for me is on, the watcher's scan also looks at the person's own sent mail, at most once an hour (`LOOK_EVERY`), for an email of theirs that asked something (a question mark in their own words), is 3 to 10 days old, went to at most 10 people other than the Executive, and is still the last message in its thread. Plain code picks it; each gets one follow-up ever (its `delegation_inbox_messages` row), at most two a look, within the drafts limit. The ghostwriter, tool-less as always, writes a short nudge in their voice from the thread, saved as a draft in that thread to exactly the people the email went to. `handle_it.follow_up_refusal` — plain code — decides whether it goes: by the setting it never goes on Easy ones, goes to their team and contacts on People I know and to anyone they wrote to on Most mail (`follow_up_refused` otherwise: `follow_up_level`); it also refuses on any change of recipients, a sensitive topic, an amount or a link, more than 600 characters, a flag, and the same per-thread and daily counts as replies. It goes through `send_on_its_own` on an ordinary `delegation_reply` card marked `source: follow_up`, which rechecks the setting for that recipient. A refused one waits on Today as **Follow-up waiting**, and closes by itself (its untouched draft deleted) when anyone answers in the thread first.\n\n**What it sent** is the person's alone: `GET /delegation/handled` lists the last 7 days (who, subject, the reply, the questions it left them and a link to the thread in their mailbox), and the Handle it for me tab shows it with how many went today, under its picker.\n\n### Take the lead as you\n\nOn Settings → Act as me, Handle it for me is one dial: **Off**, **Easy ones**, **People I know**, **Most mail** and, for the owner, **Everything**, which uses **Take the lead** (`PUT /delegation/take-the-lead`, one row `person:<id>` in `take_the_lead`; turning it on turns Handle it for me on). While it is on, `handle_it.refusal` drops the setting's limits: strangers, the classifier's confidence, amounts, and the length up to a 4000-character ceiling. A reply with a link still waits for a tap (refusal `link`). In their place it checks the company's and the person's own added rules (`take_the_lead.reply_hit`, refusal `lead_rule`). Everything Handle it always keeps still holds: signed sign-ins, an authenticated sender, a reply kind, exactly the thread's people, the topics that always wait, draft flags, never twice in a row, one a thread a day and the daily limit. Follow-ups under it may go to anyone the person wrote to, with the same sensitive, amount, link and length checks plus the added rules. `reply_send.send_on_its_own` accepts the card while both switches are on. Each person adds and removes their own rules (`/delegation/take-the-lead/rules`). Removing one needs a caller the API can tie to them.\n\n\n### Send under a chat draft\n\n`ghostwrite_email` saves the draft and returns its `delegation_drafts` row id (`draft_row`). The chat chip carries that row with the draft as saved (recipients, subject, the first 800 characters), and the web chat shows it under the reply as **Email as you** with a **Send** button. The tap posts `POST /delegation/drafts/{row}/send`, which `reply_send.send_chat_draft` checks again first:\n\n1. The row is the caller's own, from chat (`SOURCE_CHAT`); anything else is a 404. The caller is that person, the same `verified.caller_refusal` rule as a card's Send (a 409 `caller_signing_required` on a server without signed sign-ins).\n2. Act as me is on, no client slot is active, and their mailbox is connected. Draft replies to my inbox doesn't matter here.\n3. The draft is still there and its message id (Outlook: id and change key) is the one recorded when chat wrote it. One changed in the mailbox since is a 409 `draft_changed`: they send it from there.\n4. Recipients: someone, at most 10, never the Executive's own address, from one of their own addresses.\n5. For a reply: one they sent themselves in that thread since closes it (`you_replied`); a newer message from someone else asks a second yes (409 `confirm`, then `{\"thread_moved_on\": true}`).\n\nThen it claims the row (`drafts.claim_send`, a compare-and-set on `gone_at`, so a double tap sends once and the briefs stop calling it waiting), reads the draft once more and sends only that same version. A failure that shows nothing went hands the claim back; an unconfirmed one keeps it, so another tap can't send it twice. It records `sent_message_id`, a private `delegation_chat_draft_sent` audit row and, when Always in the loop is on, a note of what they sent. Like a card's Send it works while the Executive is paused. **What it may do** says chat emails are \"Drafts, sent on your tap\".\n\n## Meeting invites\n\nWith **Read my calendar** on, a calendar invite in the person's inbox no longer just gets skipped (`delegation.invites`). The watcher applies its usual rules, less the ones about writing a reply (a calendar service's own Sender header doesn't make it automatic; a big meeting isn't too many recipients), and then looks at who sent it: someone the person knows — their team, a contact, or someone they have written to (`inbox.relation_of`), with the sender confirmed by the mail service (`inbox.handling_relation`) — or it is skipped as `invite_stranger` / `invite_unverified`. It then finds the event on their own calendar: on Google by the invite's iCalendar UID (read from its `text/calendar` part, or its attached `.ics`) in their primary calendar, on Outlook as the invite message's own event; only a request counts (a cancellation or someone's answer doesn't). An event that can't be found, isn't organized by the sender, is already answered or has already started is skipped with that reason, as before. **No model is called** for an invite.\n\nWhat's left becomes a card, a `delegation_invite` decision that is its person's alone (`approver_only`) and never an alert, like a reply card: who invited them, the title, when (in the workspace time zone) and any **clash** — the busy times on their calendar that overlap the meeting, computed in code from the calendar read; only start and end times reach the card, never another event's title. **Accept** and **Decline** are `POST /decisions/{id}/approve` with `edits.answer` (`accept`, the default, or `decline`), on the same caller checks Send uses (`verified.caller_refusal`); the card is claimed, then answered with the mailbox client's `answer_invite`. Answering again is harmless, so a failure releases the card for another try; an event that has gone fails it. **Dismiss** (`reject`) answers nothing. A sign-in that reads but can't write the calendar keeps its card, which says to connect again under Read my calendar (with the command) instead of offering Accept. A card closes by itself once the meeting starts or after a week, and its thread waits until it's settled.\n\n**On its own.** Under Handle it for me (On, or Take the lead as you) it accepts with no tap when plain code finds nothing against it (`invites.refusal`): a sender on their team or in their contacts, never one known only from their Sent mail (with Replies in training, only one they ticked **Accept from them on its own next time** for), signed sign-ins or local login, no clash and a calendar it could read, nothing sensitive in the title, a sign-in that can answer, and Handle it for me's daily limit and once-a-day-per-thread rule (`handle_it.count_refusal`, `record_handled`). It never declines on its own. Anything against it leaves the usual card saying why. An accepted invite is listed with the replies it sent: `GET /delegation/handled` (`source: invite`, with a one-line `summary` such as \"Accepted Dana's Pilot review, Wed 21 Oct, 14:30\") and Today's `sent_as_you` activity, the person's alone.\n\n**In training.** With Replies in training, a card has the same tick as a reply card; ticking it and tapping Accept adds `Accept invites from <name>` to their learned list (key `act_as_me|person:<id>|invite_from|<address>`, under Replies), removable like any other.\n\nAudit rows, all private to the person: `delegation_invite_carded`, `delegation_invite_answered`, `delegation_invite_handled`, `delegation_invite_dismissed`.\n\n## AI line on replies\n\nReplies written as a person can end with **\"Drafted and sent by my AI assistant.\"** (`delegation.disclosure.LINE`), by two switches that are each person's own (`PUT /delegation/disclosure`, one row per person in `delegation_disclosure`, NULL following the install): **Handle it**, on by default (`AI_DISCLOSURE_HANDLE_IT`), for a reply Handle it for me will send on its own, which nobody reads before it goes; and **Approved sends**, off by default (`AI_DISCLOSURE_APPROVED_SENDS`), for one that waits on a card for them to send, since they read it first. The line is written into the reply when it is drafted (`disclosure.sign`, in `inbox._consider` and `follow_ups`), once the plain-code checks have decided whether it goes on its own, so the card, the mailbox draft and what is sent are the same words and Send's draft-changed checks see them; a switch changed later applies to the next reply, and a reply drafted to go on its own that is handed back keeps its line for the person to edit. `AI_DISCLOSURE` off turns both off and hides the card. Turning a switch on only adds the line, so it needs no signed sign-in; turning one off does. Each tab shows its own switch under Advanced (**AI line on drafts you send** on Act as me, **AI line on replies it sends** on Handle it for me), and turning off the Handle it line asks first.\n\n## The mailbox client\n\n`delegation.gmail.DelegateGmail` talks to the Gmail REST API directly and is **never registered with the MCP gateway**, so the model reaches the mailbox only through the typed handler. The credential is one file per person in `DELEGATION_GOOGLE_CREDENTIALS_DIR`, named from a hash of the address (0600 in a 0700 directory), minted by `scripts/connect-own-gmail.py` on the Executive's own OAuth client with the scopes `gmail.readonly` and `gmail.compose`. It never lives in `WORKSPACE_MCP_CREDENTIALS_DIR`, where workspace-mcp picks a credential by address. Besides reading threads and saving drafts it lists the inbox and checks whether they have written to an address, reads one message or draft, lists the person's send-as addresses and deletes a draft. Its **one send method**, `send_draft`, sends an existing draft by its id and nothing else — never `messages.send`, which sends any text it is given — and unit tests pin the method set, the endpoint, the request body and its single caller. On the calendar it reads (`list_events`, `find_invite`: an invite's event by its iCalendar UID) and makes one change, `answer_invite`: the person's own attendee answer on one event, with `sendUpdates=all` so the organizer hears (`calendar_write_granted` says whether the sign-in allows it; a read-only one raises `CalendarWriteNotGranted`). A failed request says whether it may have been carried out anyway (a timeout after connecting, a 5xx), which is what the send path needs to know. A parsed message carries when it arrived, whether it is bulk, a bounce or a calendar invite, and whether Gmail's authentication results vouch for its sender.\n\n`gmail_status` answers `connected`, `not_configured`, `needs_reconnect` (Google refused the saved sign-in — an app in Testing mode has its tokens expire after 7 days; a rate limit, though Gmail may send it as a 403, is an `error` to retry, not a reconnect), `mismatch`, `no_email`, `shared_mailbox` or `error`. `shared_mailbox` means the person's address *is* the Executive's; it is refused before asking Google, because then everything the Executive writes would look like theirs. The gateway closes the other door: every `google_workspace__*` call must act as the Executive's own account, and a `user_google_email` naming anyone else is refused and audited (see Integrations).\n\n### Outlook\n\nA person may connect an Outlook mailbox instead (work, school or personal), with `scripts/connect-own-outlook.py`: a device-code sign-in on the Executive's own Entra app (`MS365_MCP_CLIENT_ID`, tenant `MS365_MCP_TENANT_ID` or `common`) asking for `User.Read`, `Mail.ReadWrite`, `Mail.Send` and `offline_access` (and `Calendars.ReadWrite` with `--calendar`; an invite is the invite message's own `eventMessage.event`, answered with Graph's event `accept` or `decline` and `sendResponse`). It writes the same per-person file with `\"provider\": \"microsoft\"`, so a person has one mailbox for Act as me, and `gmail_for` hands back `delegation.outlook.DelegateOutlook`, which keeps `DelegateGmail`'s methods, return types and errors, so every caller above runs unchanged. It talks to Microsoft Graph directly, never through the Microsoft 365 MCP server the Executive's own Outlook uses, and is never registered with the gateway. Microsoft rotates the refresh token on use; the new one is written back into the file (atomically, keeping every other key, and only if the file still holds the old one). Graph is asked for immutable ids, so a sent draft keeps its id; a thread is Outlook's `conversationId`. Gmail's labels are mapped onto what the callers read: `SENT` only for mail in their Sent Items folder (a From line set to their address by someone else never counts), `DRAFT`, `INBOX`, and Focused Inbox's Other read as a tab. A sender counts as authenticated only when the topmost `Authentication-Results` — the one Exchange wrote, above anything the sender added — holds exactly one DMARC verdict, a pass for From's own domain, and Exchange Online Protection's own `compauth=` verdict, so a header the sender wrote on mail EOP never stamped doesn't count. `delete_draft` refuses anything that isn't a draft, and deletes with the draft's etag (`If-Match`), so a draft sent in between — it keeps its id — is left alone. No client secret is ever written into a person's file, and Graph has no signature setting to read.\n\n## Privacy\n\nWhat a person's mailbox touches is theirs. For the principal that means private to the principal, as every private row is. For a team member it means theirs alone, the principal included: an audit row carries `private_to_person` (set by `audit.rows_for_person` around the inbox watcher, a card's Send and Dismiss and their settings changes, and by `people_tools.audit_row_owner` on a turn that read their mail) and is left out of every audit read — the log, a session's timeline, a row by id, the brief — with only the usage totals counting it; their reply cards are theirs alone (above); and the owner's view of their use is counts only (drafts and sends in 30 days, and whether their inbox watcher is on). The conversation itself becomes its owner's alone before the mailbox is first read: `ghostwrite_email` marks the session `mail_private` (`session_store.mark_mail_private`, creating a channel adapter's row early, with its owner) and refuses to read the mailbox if that can't be stored or the conversation already belongs to someone else (which it then leaves unmarked); from then on only its owner may open it (`chat._session_access`), and working-style learning skips it. Every later turn there starts private (`settings.pin_turn_delegation` reads the flag and fails closed, setting `touched_mail`), so a follow-up answered from history alone is still private to its owner and teaches no memory, and the web chat's rows before the turn (the inbound message and the knowledge lookup) are theirs too. It does not start locked down: the lockdown is `read_mail`, set only by a turn that reads the mailbox or notes itself, and it is never carried into the next turn, because history keeps only the speaker's words and the Executive's replies, never the mail a tool returned. Their next message is them asking again, having read that reply, so everything runs again there. Anyone else speaking in it is not offered Act as me.\n\nOnce `touched_mail` is set, every audit row the turn writes is private (`people_tools.audit_row_private_to_principal`), and a team member's is theirs alone: the tool row (its input and result redacted, since `ghostwrite` is a sensitive tool name), the reply's `chat_turn` row that carries the preview, the model-call rows, and the background passes, which run under `private_rows`. The Honcho peer and department syncs are skipped, because peer memory is read on other people's turns. No memory is learned from the turn at all: the episodic, open-loop and working-style passes are skipped too, since its reply quotes a draft built from other people's mail. The `delegation_*` audit events are always private and carry metadata only — ids, counts and flags, never the draft or the thread. The inbox watcher is private the same way: every row a scan or a card action writes is its person's alone, and it starts no chat turn, alert, scheduled action or workflow run and teaches no memory.\n\nThe turn also keeps one door shut (`delegation.lockdown`). Anyone can put text in the inbox, and that text could try to steer the model, so from the round that calls `ghostwrite_email` or one of the mailbox reads — a round's tools run together — until the turn ends, the dispatch guard refuses only what opens the open internet or reaches everyone: outside fetches (`read_document`, research, the watchlist, `load_mcp_server`, and any MCP `call_tool` outside the private-turn set of reads and recipient-checked sends), `run_script` and `run_python_job`, workflows (they run later, unattended, and may fetch or script), broadcasts, department messages and alerts, and changes to who is on the roster or holds authority (`archive_person`, `set_department_head`, `resolve_roster_request`), and text that steers later turns (`schedule_followup`, whose intent runs unattended when due, and goals and decision outcomes, shown to every later turn). Everything else the person asks for runs, because it is fenced on its own: DMs and `message_person` reach only the roster, invites name attendees by person id, the Executive's own email checks every recipient against the roster, standing facts and profile edits keep only the person's own words, and a workflow drafted in chat is saved only once a person confirms it. `upsert_person` runs only for a contact the person asked for (`speaker_named_contact`: a contact, never the team, an approval scope or a chat account, with a word of the name in what they typed, in a message that asks to add, save or change someone, a new contact's address one they typed or one that sent the mail the turn read under the contact's name (`TurnDelegation.mail_senders`), never one the mail's text only mentions, and on an update a changed address they typed), since the roster is what the send checks trust. Any other contact add is refused with a pointer to an approval card (`lockdown.CONTACT_REFUSAL`), so the Executive leaves an `add_contact` card in the chat rather than asking them to type the address. What an email itself asks for is still never done on its say-so; it goes on an approval card. Every tool is classified as allowed or withheld, a test fails on a new unclassified one, and an unknown name is withheld, except an extension tool registered with `after_mail_read` (one that only reads the install's own data). The refusal tells the model to put what the step needs in its reply, since the next turn sees the reply but not the mail, and to do the step then without reading the mail again. A refused call gets a private `tool_invocation` row (`refused: mail_touched`) and tells the model to offer it in the next message. The offered tool list never changes mid-turn, so the cached prefix holds. The handlers that reach outside check again on their own (`outside_reach_refusal`). The server-side web search stays, as on a turn private to the principal. How much of the lockdown holds is the owner's safety level (`orchestrator.outside_mode`), because every mail read is checked like any outside read: after each round, each mailbox or notes read's result goes through `content_scan` (`outside_content.check_mail_read`), which sets `TurnDelegation.mail_held` when the level holds it and `mail_vetted` once the round's reads are checked (`check_mail_reads_done`), and puts `FLAG_NOTICE` or `UNCHECKED_NOTICE` before the result as for other reads (a search's threads are checked entry by entry, `content_scan.scan_list`: a flagged thread's subject and sender name are taken out behind `LEFT_OUT_NOTICE` and the rest passes once a second check finds it clean (else the whole list is flagged), holding nothing below Careful; a thread whose newest message the Executive itself sent, from its own address the mail service authenticated (`ThreadSummary.sender_authenticated`, from Gmail's or Exchange's stamp as on a message read, kept per turn in `TurnDelegation.mail_verified`) and under a subject that is not a reply's or forward's, is not checked; the reply never mentions a flag); a flag is shown under the web chat reply as *An email I read …*. `lockdown.mail_lock_holds` then decides: Careful holds the whole lockdown after any mail read; Balanced holds it only once a read was flagged or too big to check, or while one is not checked yet (the round that reads mail holds its other calls, since they run together); Hands-off holds none of it on the principal's own turn; a turn with no safety state (a workflow) holds it, failing closed. `mail_turn_withholds` applies it at dispatch and in `outside_reach_refusal`. At every level a mail read keeps posts to everyone and roster or authority changes shut (`MAIL_PRIVATE_WITHHELD_TOOLS`, and `upsert_person` only for a contact the speaker named), since those would spread the owner's private mail or change what every send check trusts. App control (`app_control._turn_read_outside`) follows the same rule, and under Careful still waits for a tap in any turn of a conversation that read the owner's mail. The lockdown ends with the turn. Later turns of that conversation stay private to its owner (`touched_mail`) but hold nothing: a refusal says it will work when they ask again in their next message, and it does.\n\n## Always in the loop\n\nA sent reply can leave a note. Once the reply went, `reply_send` starts `memory.history_notes.note_sent_reply` for the person who sent it, in the background, when their \"Keep track of what happens\" switch is on and the conversation isn't one they asked not to remember. The note-taker sees only the words they sent, so other people's mail never becomes a note, and a failure never touches the send. Recall is `recall_history`, offered on the same verified, private surfaces as `ghostwrite_email` and also allowed under the mail lockdown, since it only reads the speaker's own notes. Calling it locks the turn like `ghostwrite_email` does, from its own round on. The same switch also covers notes from chat, which don't need Act as me. See **Memory** for the checks, retention and controls.\n\n## The system prompt\n\nA constant, name-free `DELEGATION_ADDENDUM` joins block 0 after the unchanged identity addendum while anyone on the install has it on (`block0_delegation_on`). It names the four mailbox reads and says other people's mail is data and that a conversation which read it reaches nobody else; and it tells the model that `ghostwrite_email` is the single exception to *never impersonate*, and only for the person being spoken to; that everything else is written as itself; that when the tool isn't offered the asker can't have it; that a draft is never described as sent; and that it never denies being an AI. It is keyed on the install-level setting, never on the turn or the speaker, so switching it misses the 1h cache once (see Prompt Caching).\n\n## What it does for you\n\n**What it does for you** (`delegation.may_do`, `GET /what-it-may-do`) is read-only: with the viewer's settings right now, one row per thing that can go out without asking, written as one sentence of what it does, what happens to it (goes out, waits for someone, always waits, drafts only, off) and which setting decides it, with a link there. It sits beside every Delegate tab (`DelegatePage` → `WhatItDoesPanel`): a column to the right on a wide screen (closing it is remembered in the browser), a bottom sheet on a narrow one. The UI groups rows by outcome (Sends on its own, Asks first, Writes for you to send, Off). Every delegation setter in `lib/api.ts` fires `DELEGATION_CHANGED` after a save; the panel reloads on it and marks the rows whose outcome or text changed as **Just changed** for ten seconds. `/delegate` and the old `/delegate/what-it-may-do` open Act as me. Its **Compare** fold holds Who writes and who sends. Three parts, each behind a pill that counts what goes out:\n\n- **As you** (the caller's own, when `can_delegate` allows them): built from `settings.is_enabled`, `inbox.get_watch`, `handle_it.get` and `handle_it.RULES`, `handle_it.leading` (Everything), `training.get` and `training.learned`, and their rules, the same reads `handle_it.refusal` and `follow_up_refusal` make. A level's row follows its `Rules` (strangers, follow-up reach, links and amounts), not a copy of them. A note names the ladder: Handle it for me rides on Draft replies to my inbox and Write drafts as me, and Everything also drops when Replies or Follow-ups go into training.\n- **As the Executive** (the principal's alone, as `GET /take-the-lead`): the switch and its training, each Ask first kind, the company's rules, and meetings. A meeting it thinks of on its own always waits: both meeting gates need someone on a verified surface in the turn, which an unattended run never is. A meeting someone asks for in chat follows **Always asks first → Meetings asked for in chat** (on means it waits: `meeting_scheduling`'s class mode is `propose`; off means `auto_execute`) and, in a team workspace, Operations' level too.\n- **Departments**: each level, and what a level covers (department-scoped scheduled work, check-ins, alert review, team members' chat sends, and Operations' meetings), and that it doesn't cover what the Executive does under Take the lead.\n\nIt also says when the Executive is paused, and when nothing can be sent as anyone because signed sign-ins are off. Nothing on it writes or reads mail. A contact, someone not on People, or a request with no caller (outside local login) gets 403.\n\n## How far it goes as you\n\nOne setting replaces the switches that used to turn each other off out of sight. The UI shows it as two pickers (`ReachCard.tsx`): **What it writes as you** (`WritesCard`) on the Act as me tab and **What it sends on its own** (`SendsCard`) on the Handle it for me tab; What it does for you links each row to its own picker. Its steps, each adding to the one before: **Off**, **Drafts when I ask** (Write drafts as me), **Drafts for my inbox** (Draft replies to my inbox), then the Handle it for me steps that send, **Easy ones**, **People I know** and **Most mail** (`careful`, `balanced`, `bold`), and for the owner **Everything** (Take the lead as you). Act as me shows the first three as **Off**, **When I ask** and **Draft replies automatically** (any sending step reads as Draft replies automatically there). Handle it for me shows **Off** (saved as the inbox step) and the sending steps, and opens only once Act as me is at Draft replies automatically, with a button that turns that on; moving Act as me below it says Handle it for me stops too. `PUT /delegation/reach` (`{step}`) moves it, and `reach_of` reads the step back from the switches, so the stored switches stay the source of truth and every gate reads them as before.\n\nGoing down turns the switches above the target off, highest first (`_lead_off`, then Handle it, then the inbox watcher, then Write drafts as me), so nothing is ever on above a switch that's off; the UI says what stops and asks before it saves. A lower sending level only holds more back and is set directly, so it needs no signed sign-in. Going up calls each switch's own route in order, so every check it makes still applies: the mailbox connected, signed sign-ins for sending, the owner alone and not in training for Everything. The first that refuses stops the move at a whole step and answers with that route's error. Handle it for me's own Off / In training / On (Replies and Follow-ups together) and, at Everything, **Your rules** sit with its picker, and **Learn from my edits** (drafts training) under the Act as me one; neither picker changes training.\n\n## Surfaces\n\n- **Settings → Act as me** (`ActAsMeCard`, hidden unless `GET /delegation` answers, so a team member sees it once the owner lets them): the mailbox connection (`provider` says which) with both connect commands (Gmail and Outlook) and **Check again**, **What it writes as you** (above), with the inbox watcher's status under Draft replies automatically (in plain words, when it last checked, **Check now** and **Also save inbox replies in my Gmail Drafts**), and **How I write**: length and tone, a greeting per audience (`{first}` is their first name), the sign-off, habits and never-rules in fields that grow to show every line, the signature with **Refresh from Gmail** and **Don't add my signature** (or **Add my Gmail signature** when none is added; on Outlook only **Don't add my signature**, with why), and each example quoted with **Remove examples**. The owner also gets **Let team members use it** where the install allows it, with each team member who has it on listed by name and counts only.\n- **Today → Replies waiting** (`RepliesWaiting`, the top of the left column; hidden unless `GET /delegation/replies` answers with cards): each card starts closed (who wrote, the gist, what's left to decide, Send or Review, Dismiss); open, everything shows at once as a conversation: what they wrote as plain text, the Executive's word on the reply with the open questions (each with answers to tap and **Something else…**, and where they came from) and the answered ones (**Change** to pick again), then the card's `conversation` (newer email marked **New**, what the person asked to change, the Executive's note on what it did), then **Your reply** with its Reply to choice, **Edit the words myself** (a text box on the card with Save and Cancel), **Tell me what to change…**, its warnings, and **Send** (a confirm naming who it goes to, and a second one when that or the thread changed), **Open in Gmail** or **Open in Outlook** when the reply is in their Drafts, and **Dismiss**.\n- **Today → Needs you, invites** (`InviteCards`, next to the reply cards; hidden unless `GET /delegation/invites` answers with cards): the meeting, when, who invited them and who they are to them, any clash (times only), and **Accept**, **Decline** and **Dismiss**, or the reconnect note for a read-only sign-in; with Replies in training, the **Accept from them on its own next time** tick.\n- **Setup status**: a **Your own mailbox (Act as me)** light (`your_gmail`), amber while the inbox watcher can't reach the mailbox, is being rate-limited or has 25 replies waiting.\n- **Delegate** (main menu): **Act as me** (where `/delegate` and `/settings/act-as-me` land), **Handle it for me** (which step the dial is at, with **Change in Act as me**, then **What it sent**: how many went today and what it sent this week, as you) and **Take the lead** (the switch, then **Always asks first**, shown even while the switch is off and ending in **Meetings asked for in chat**, and the company's rules, as the Executive). Each switch that turns another off says so beside it. The pause is on **Settings → Your Executive**.\n- **API**: `GET`/`PUT /delegation`, `GET`/`PUT`/`DELETE /delegation/voice`, `POST /delegation/voice/learn`, `POST /delegation/voice/describe`, `POST /delegation/voice/signature`, `PUT /delegation/inbox` (`{enabled?, mailbox_drafts?}`), `POST /delegation/inbox/check`, `GET /delegation/replies`, `PUT /delegation/replies/{id}/text`, `GET /delegation/invites`, `PUT /delegation/handle-it`, `PUT /delegation/reach` (`{step}`, the dial), `PUT /delegation/training`, `DELETE /delegation/learned/{id}` and `GET /delegation/handled` — the caller's own delegation only — and `PUT /delegation/team`, the owner's switch (see API Reference). `GET /what-it-may-do` is the read-only summary above. Send (and an invite's Accept or Decline, with `edits.answer`) is `POST /decisions/{id}/approve`; Dismiss is `POST /decisions/{id}/reject`.\n- **Evals**: a scenario's `delegation:` block runs the turn against an in-memory mailbox (`evals.mailbox.ScenarioMailbox`) and hands the saved drafts to the judge (`delegation_001`–`003`). A `type: inbox` scenario runs the watcher's two model calls on one thread: whether it drafts must match the scenario, and a draft is judged on saying nothing the person hadn't, copying no link or address, and listing every open question (`delegation_inbox_001`–`007`; the last checks a draft never claims anything was sent).\n\nActing within rules the person sets and standing in for them are later, separate changes, each behind its own switch, off by default.",
"mermaid": "flowchart TD\n Ask[\"Principal or team member, verified<br/>'reply to Dana as me: yes'\"] --> Pin[\"pin_turn_delegation<br/>may have it? on? verified? private? attended?\"]\n Pin -->|\"offered\"| Loop[\"Executive tool loop<br/>with ghostwrite_email\"]\n Pin -->|\"not offered\"| Self[\"writes as itself<br/>(unknown tool this turn)\"]\n Loop --> Tool[\"ghostwrite_email handler<br/>caps, mailbox check, recipients in code\"]\n Tool -->|\"touched_mail\"| Private[\"turn's rows and conversation<br/>theirs alone, no memory\"]\n Tool --> Client[\"DelegateGmail or DelegateOutlook<br/>REST, outside the MCP gateway\"]\n Tick[\"Scheduler tick or Check now<br/>Draft replies to my inbox on\"] --> Scan[\"inbox scan, rows theirs alone<br/>skip rules, limits, ledger\"]\n Scan --> Client\n Client --> Box[(\"The person's own Gmail or Outlook\")]\n Scan --> Classify[\"classifier, no tools<br/>needs a reply? kind, confidence\"]\n Classify -->|\"worth a draft\"| Gw\n Voice[(\"delegation_voice<br/>How I write\")] --> Gw[\"ghostwriter<br/>no tools: voice + intent + thread\"]\n Tool --> Gw\n Gw --> Lint[\"lint: links and addresses<br/>only the person's own\"]\n Lint --> Draft[\"create_draft, threaded\"]\n Draft --> Box\n Draft --> Chip[\"chat chip: open the draft<br/>chat never sends\"]\n Draft --> Card[\"Today: Replies waiting<br/>their own card\"]\n Card -->|\"Send, confirmed\"| SendPath[\"reply_send: checks again,<br/>claim, send the draft by id\"]\n SendPath --> Box\n class Ask entry\n class Pin compute\n class Loop compute\n class Self compute\n class Tool compute\n class Private compute\n class Client compute\n class Tick entry\n class Scan compute\n class Classify compute\n class Box external\n class Voice storage\n class Gw compute\n class Lint compute\n class Draft hot\n class Chip entry\n class Card entry\n class SendPath hot",
- "generated_at": "2026-10-26T19:13:19Z"
+ "generated_at": "2026-10-27T18:30:00Z"
}
diff --git a/packages/core/openexecutive/architecture/prebuilt/today.json b/packages/core/openexecutive/architecture/prebuilt/today.json
index c76dc28b..bafc3c8c 100644
--- a/packages/core/openexecutive/architecture/prebuilt/today.json
+++ b/packages/core/openexecutive/architecture/prebuilt/today.json
@@ -1,7 +1,7 @@
{
"section_id": "today",
"title": "Today / Morning Brief",
- "markdown": "`openexecutive.api.routes.today` serves the morning brief — a one-screen, read-only view of what is happening across the org. It is the default landing surface (the Next.js root renders `<Briefing>`). Every signed-in page shares one sidebar (`AppSidebar`). Its Recent list is capped at the 7 newest web chats. The full history, including Slack, Telegram and Discord conversations (recognised by their session-id prefix), lives on `/chats`. A chat opens from any page through `/?session=<id>`.\n\n`GET /today` returns `TodayResponse` assembled by `_build_today()`, which is synchronous and caller-agnostic:\n\n- **`departments`** — per-department goal health, rolling up each department's goal counts (`total`, `at_risk`, `off_track`) plus its awaiting-workflow count, and `attention_goals`: the actual off-track/at-risk goals (worst first, capped at 3) with `key_result`, `current`, `target`, and `status`, so the briefing's Department card shows *which* goal is off and how far without a click. Empty for healthy/inactive departments. Each attention goal also carries `owner_id` and `owner_name` (its own owner, else the department's head, else the principal), and the narrative's goal lines name the owner. Goals with no department get one more row, slug `\"\"` and title **Other goals** (`UNASSIGNED_GOALS_TITLE`), shaped like a department so every reader of `departments` (the header context, the narrative, the reflection, the fingerprint, the digest) counts them; it is added only when such goals exist, links to `/goals` in the UI, and a teammate's slice keeps only the goals on them.\n- **Private cards.** An alert tagged `private:principal` (`alerts.models.PRIVATE_ALERT_TAG` — raised on a turn about mail from one of the principal's contacts or mail they forwarded, or a meeting proposal with a contact) is in `proposals` only when the caller is the principal. The chat's alert digest (`briefing.context.render_and_trust`) shows it, and the roster requests, only on the principal's own verified turn, never in a web chat they shared with others, where everyone reads the reply. `_build_today` leaves it out by default, so the end-of-day digest, the reflection and Discord's `/today` never see it, and the morning brief reads it only on a run for the principal (the scheduler's, or the principal's own verified chat turn in a conversation only they can read — see Workflows). The narrative is written from one only in the principal's own `principal` scope, which nobody else is served; the shared `company` scope an unresolved caller gets, and a teammate's scope, never are. The activity rail skips it, and the chat digest includes it only on the principal's own verified turn.\n- **Raised by a team member.** An alert a team member raised from chat (`AlertEvent.raised_by`, source `team_member`) has its body led by \"Raised by <name>.\" and never goes out on `company_broadcast`: the pipeline drops that channel after `resolve_channels`, so it reaches a person or a department room only. One team member's alert never coalesces into another's (the dedup key is prefixed with who raised it). A team member's saved workflow raises alerts as its creator (`action_step` binds `dynamic_store.get_owner` around `oe__create_alert`). Alerts from email, watches and other sources are unchanged.\n- **Who clears a card.** `POST /alerts/{id}/ack` with `ack` or `dismissed` answers 403 to a team member unless the alert is routed to them (`read` is open to anyone who can see it); only the principal's dismiss applies `mute_topic`, since a mute silences the topic for everyone. `POST /alerts/bulk-ack` from a team member clears only the listed ids routed to them and refuses an `older_than_days` sweep. The principal, or anyone before a principal is set up, clears anything. `ack_alert` in chat follows the same rule.\n- **Roster-request cards.** When someone not on the People list writes in (see Org and Integrations), `people.roster_requests.surface_card` raises an alert of source `roster_request` (medium, tagged `roster_request:<id>` and `private:principal`, routed to the principal), so it follows every private-card rule above. `GET /today` attaches `roster_request` to that proposal (`_roster_request_card`: channel, address or account id, the sender's sanitised and unverified name, profile email, company-domain flag, suggested kind and person, message count, whether they were acknowledged, first seen, and the held messages' first lines) while the request is still pending. The Briefing renders it as its own card (`RosterRequestCard`: add as a new person with a name and an explicit team/contact choice — pre-filled as team on a company domain — or \"someone already on the list\", with a replace-account option for a chat id, or Ignore), which calls `/people/requests/{id}` directly and never hands off to chat, so what a stranger wrote never seeds a turn. The card is kept out of everything that could close it without answering it or put the stranger's words in front of a model: the narrative (`_action_proposals` drops it), the chat's open-alert digest (`<briefing>` — the principal's verified turn gets a separate `<roster_requests>` block instead; see Agents), `ack_alert`, a single ack (`POST /alerts/{id}/ack` is a 409), the \"Dismiss N older than 7 days\" count and the server's bulk ack, reopen, the TTL sweep and the alert review (`roster_request` is in `lifecycle.TTL_EXEMPT_SOURCES`). It ends when the request does: answered (`ack`, or `dismissed` on a decline) or expired after `ROSTER_REQUEST_TTL_DAYS`.\n- **`people`** — an attention-ranked roster of the **team** (the principal's contacts are never listed, and get no insight note). Each person carries `awaiting_action` count, soonest SLA, a `status` (`on_leave` / `needs_reply` / `awaiting` / `clear`), reachability, `overdue`, a server `priority` sort key, and a cached one-line `insight`. Sorted by `(-priority, full_name)`. Stale insight notes are regenerated in the background only when the roster has more than one person: the UI shows the People sidebar only for more than one, so a one-person install (solo, or a team before anyone else is added) does not pay a daily model and peer-memory call for a note nobody sees. Cached notes are still served.\n- **`proposals`** — the *live* unread alerts (workflow approvals, triage-classified inbound, Executive signals, flagged artifacts, and gated calendar bookings; an artifact is listed only to its owner (`alerts.models.visible_alert`; every other build of the board — the briefs, the reflection, the review, the chat digest on anyone else's turn, the activity rail — leaves drafted artifacts out) and carries `artifact_format` / `artifact_url` and a `body` already rendered to Markdown for its format, so the card badges it as a web page, Word doc, spreadsheet or link and offers *Open artifact*): unread, inside their category TTL, not snoozed — see *Alert lifecycle* below. Each carries `score`, `category` (`action` vs `monitoring`), `surfaced_reason` from `openexecutive.briefing.ranking`, the lifecycle fields (`occurrence_count`, `last_seen_at`, `last_reviewed_at`, `review_verdict`, `review_note`, `recommended_move`, `why_now`, `due_at`, `superseded_count`, `suggested_workflow`), and `decision_instance_id` (set only when the proposal is backed by a decision-ledger row — a calendar booking awaiting approval). `failed_run_id` is set only on a `workflow_failed` card (a scheduled run that ended in error, see Scheduler): its main button is **Run again** (`POST /workflows/runs/{id}/rerun`, which also closes the card) and its ⋯ opens the run; it has no Approve. The response also carries `held_back` for the principal alone: the lines grounding left out of the morning brief or end-of-day digest in the last day, which Home lists under **Left out of your brief** (the brief's note names it; Hide is remembered in that browser). The UI splits them into 'mine' vs 'across the team' using `caller_person_id`. Approve is carried out on the server for every card. For decision-backed proposals the card's Approve/Reject call the `/decisions` endpoints (which book or cancel the event server-side and clear the alert), so meeting bookings are reviewed in the briefing itself rather than on a separate page. Every other proposal is approved at `POST /alerts/{id}/approve` (`alerts.approvals`): it records who approved the card and when (an `alert_approvals` row plus `alert_approved`, then `alert_approval_done` / `alert_approval_failed`, audit rows), claims the card in one transaction so a double click or a second approver gets a 409 and the work runs once, then does the work. A card the scheduler filed for a department-gated action is bound to it server-side (`alert_held_actions`, written only as the card is filed, never read from the card's tags or text, which a model reading inbound mail can write), and approving it queues that exact action again with no department, the approval being the consent the gate waited for. Any other proposal runs one Executive turn as the approver in a new chat on the server (`chat.start_background_turn`, the machinery behind `POST /chat/background`), with the edited text verbatim for Edit & approve; it keeps going if the page closes. Only the card's routed person or the principal may approve a routed card, and only the principal an unrouted one (403 otherwise); the card's text reaches the turn as quoted data, not instructions. A row at the top of Needs you follows the approval (`GET /alerts/approvals/{id}`): working on it with a link to the chat, then done, or didn't work with Try again; a card whose last approval failed can be approved again, and one still running at a restart is marked failed on boot. The page no longer acks the card and seeds a chat turn with the proposal, which left no record of the approval and did nothing if the tab closed first.\n- **`narrative`** — a per-viewer Executive-voice header (\"What's going on\") synthesized by `synthesize_briefing_narrative`, cached per scope in `briefing_narrative`: the resolved principal gets the whole-company `principal` scope (which may carry what is private to them), a caller who resolves to no roster row the shared `company` scope (written from what everyone may see), and each teammate a role-scoped `person:<id>` one. `narrative_generated_at` says when the served text was written and `narrative_stale` whether a fresher one is being written now. Home shows it as **Right now**, a card above Needs you, because the text is rewritten through the day: When a rewrite of the principal's header adds a point (`right_now.record_points` returns the points whose key is new today), `briefing.right_now_ping` sends them one short message on their own chat app (`scheduler.runner.deliver_to_person(chat_only=True)`, tagged `right_now` so their notification settings apply): on **Important only** (the default; Settings → Notifications, `NotificationSettings.right_now`) only for a point citing a MOVED TODAY line that needs them (`header_context.NEEDS_YOU_PREFIXES`: mail or chat in, own-inbox mail, stuck, a decision raised today, their overdue item, a reply overdue, a chat ask it couldn't do), on **Everything** for any new point. Never for the first header of the day, at most 4 a day (`right_now_ping` audit rows), and dropped, not held, during quiet hours or \"In my briefs\". The points are model text over quoted mail, so every link, address and bare domain is stripped before sending (`plain_point`). `briefing.right_now.split_narrative` splits the served text into `narrative_lead` (the bold opener), `narrative_points` (`{text, since}`) and `narrative_move`. `since` is when that point first appeared today, kept per scope and local day in `briefing_point_seen` (keyed by the point's bold subject, so a reworded point keeps its time; recorded when a header is written, earlier days pruned then). `narrative_seen_at` is when this reader last looked, from `briefing_reader_seen`, set by `POST /today/seen` (same scope resolution as `GET /today`; the shared `company` scope of unrostered callers keeps no look, so one stranger's visit never resets another's); the page fixes it as the baseline for the visit, marks points after it with a green dot and *N new since …*, and only counts a look from earlier the same day. For the principal the response also carries `morning_brief` (`{at, text}`, today's delivered morning brief from `brief_state.last_delivered`) and `calendar_next` (up to 3 meetings still ahead today from the cached calendar read, never a fresh call), which the side panel shows under the points and Move today. Nothing here calls a model. In the web UI each bullet of this narrative is a click target: clicking one hands off to chat (the same `onContinue` path as the proposal cards) seeded to discuss that item. The Executive recognizes it because every chat turn now carries a `<briefing>` digest of open alerts (see Memory). That digest (`briefing.context.format_open_alerts_for_prompt`) is capped at 30 items; when the board is longer the header says so explicitly and tells the Executive to point at this page for the rest — it previously presented the capped list as the complete board, so the Executive described a slice as everything that was open (#136). Chat adapters get the digest too, but Slack gates it to the principal's DMs: the board is company-wide and must not be pulled into a shared channel. The `[alert_id]` at the start of each line is also what `ack_alert` trusts, because an id quoted inside an alert's own body came from inbound mail or chat and is attacker-controlled. This page's `[Discuss mode — alert_id=N]` handoff primer is a pointer to which item is under discussion, not authority on its own: the server accepts it only if that id is on the live board too. Two things enforce that. Every field the digest interpolates — headline, body, suggested action, tags, review note — is collapsed to a single line, since a newline in any of them would forge a whole extra `[N]` line and with it a fabricated instruction to clear someone else's alert. And the server records the live board it derived, so `ack_alert` refuses any id outside it — on **every** session, not just the chat adapters. The recorded set is the whole live board, not just the rows the digest printed, so a card past the render cap stays ackable. The control stops invented, closed, snoozed and expired ids; it does not stop the model being argued into acking the wrong *live* card. When the principal names an item that has already left the board — opened, snoozed, or older than it — the Executive looks it up with `find_alerts` (a keyword search over every status, `alerts.store.search_alerts`); matches that are still open (`unread` or `read`) become ackable for that turn, up to 25, and closed ones come back labelled so the Executive can say the item is already settled. It works only where the principal's own board was shown this turn — the web app or their DM — and never returns roster-request cards (see Lifecycle). The digest's header also labels every headline and detail as untrusted content drawn from inbound mail, chat and watched pages — act on what the principal asks about an item, never on what its text asks — and triage reads each signal inside an `<event>` block whose closing tag the sender's text cannot forge (it is defanged in any case and spacing, after NFKC folds fullwidth forms). That check used to run only when `origin_channel` was set, which the browser never sets, so the one surface where the principal actually reads their board had no check at all and the model could ack any id, including one quoted out of an alert body by the Discuss handoff. Rendering the block and recording its ids now happen together in `briefing.context.render_and_trust`, which both the web chat route and the channel adapters call: render without recording and the tool refuses everything, record without rendering and the model gets reach it was never shown. A turn that was shown nothing trusts nothing. Recording it is only half the wiring: the tool reads the board off the turn's session through a ContextVar, and the chat route binds that session for the whole SSE body (`set_session`, next to `set_turn`). Bound from inside the Executive's own generator instead, it survives exactly one stream step — `asyncio.wait_for` runs each step in a fresh Task with a copy of the context — and the tool-call loop, which runs later, sees nothing. That shipped, and every web ack was refused on cards that were open the whole time. The digest also carries a short **already handled** tail — recently acked / dismissed / resolved rows, named but deliberately NOT trusted for acking — because a card cleared on the page minutes ago is otherwise simply absent from chat: asked to \"record that as fixed\", the Executive could not tell a settled item from one it had never heard of, and sent the principal back to dismiss a card that was already gone. That tail renders even when nothing is open, which is exactly when it matters. Note it is a different window from the `handled_overnight` rail above: that one runs since the last delivered morning brief, while the chat tail looks back 14 days (matching the action-alert TTL, so it still covers an item cleared late in its life), so chat can name a settled item the rail no longer shows. On the principal's own verified turn the digest also lists their chat drafts still waiting in their mailbox (when, to whom, subject), so a brief line about a draft can be discussed; `read_my_email` shows drafts in a thread marked not sent, so a thread that is only a draft does not read as empty. The narrative is held to what is **live**, and to what it is actually for. The `alert_raised` source is dropped from the activity it reasons over (`_build_activity(..., include_alert_raised=False)`): a closed alert reads as work the principal already settled, and a *live* one is worse than redundant — `lifecycle.is_live` is the very predicate behind `list_live_alerts`, so every live raise is already a proposal card below the header, which the prompt forbids re-listing. The `/today/activity` rail keeps the whole source, because a raise really happened. The activity block is only labelled \"since last brief\" when the caller bounded it with `since` (the standalone briefs do; the header does not), since calling an unbounded history rail a delta made the header present weeks-old rows as overnight news. When the viewer's slice holds nothing that wants a decision — no action proposal, no at-risk/off-track department, nobody awaiting — the regen skips the model call entirely and writes the fixed quiet line (`Quiet right now — nothing pressing.`, or `… nothing needs you.` for a teammate). **The cache key is a hash of the rendered context itself** (`today._narrative_context` builds it once and both the hot path and the background task key off that one string, which is also handed to the model verbatim). That makes the key a function of the model's input: everything the prompt renders is covered, and nothing it omits can trigger a regeneration. Keying on hand-picked fields broke one half or the other each time — headlines alone left the rendered activity block uncovered, while the proposals' review fields are never rendered by this header yet are rewritten with fresh prose by every `alerts.review` pass, so they regenerated each viewer's narrative several times a day to re-synthesize identical input. A quiet board keys off a fixed sentinel instead, so a moving rail cannot re-key an entry whose text is constant. Together: on a fully dismissed board every other input was empty, the rail became the only context, and the model synthesized a confident header out of closed items.\n\n **Right now's context and its check.** The whole-company header (Home's Right now card, directly above Needs you) is written from `briefing.header_context.render_header_context`, not `render_briefing_context`. **MOVED TODAY** lists, each tagged `[M1]`, `[M2]`…, what happened or came due today: INBOUND mail and chat from other people, STUCK replies and waiting drafts, decisions raised today (with their why-now) or re-raised today, the principal's own open loops due today or overdue (`due_soon`, now in team mode too on the principal's scope), the Executive's follow-ups (`in_flight`) due today or overdue, overdue replies from people it waits on (team only), things it could not do from a chat (the brief-requests raise lines), work it finished today (activity rows from the local day, minus `advice_given` / `decision_logged`, which come from the reader's chats) and today's watchlist signals. **COMING UP TODAY** is the rest of the calendar, tagged the same way. In the principal's own header MOVED TODAY also lists the meetings that ended today (`live_signals.met_today`, latest three) and their own emails nobody has answered yet (`briefing.waiting_on`): sent from their own mailbox under Act as me in the last 7 days and over an hour ago, asking something (a question mark in their own words), to at most 10 people besides the Executive, and still the last message in the thread. It also lists mail to their own inbox that the Act as me watcher looked at today (`live_signals.own_inbox`, from the watcher's private `delegation_inbox_mail` audit rows: sender, subject and when, never a body), including newer mail on a thread whose reply card is still open, which a scan otherwise passes over: from people they deal with (team, contacts, people they have written to) one line each with what the watcher did (drafted, answered, no reply needed). Mail from anyone else is never a point (bulk, list and Gmail-tab mail is not recorded at all, so a busy day of it never crowds real mail out): `/today` returns up to three `Name: subject` labels and a count as `inbox_also` / `inbox_also_total`, which Home shows as one \"Also in: 2 others — …\" line under the points. Only who it went to, the subject and when reach the model. The read runs in the background (`today.refresh_principal_narrative`, with the calendar), is cached for 15 minutes, and is dropped when Act as me is turned off; the briefs neither render these lines nor count them. **STILL OPEN** is what sits in Needs you and did not move (older decisions, later due dates, later follow-ups, goals at risk): background for ranking, never a point. **BACKGROUND** holds the reader's chat titles and own messages, only to judge what matters most to them. The rest of the history rail is never read: it made the header report yesterday's DMs as news, and chat titles made it claim work in progress (\"I'm combining the PDFs now\") hours after it was done. The prompt (`_header_prompt`) asks for a bold opener, **one to three** bullets that each end with the tag of the line they are about, and a **Move today** line for the reader. After the model, `header_context.keep_cited_points` deletes any bullet citing no tag the context had (`tags_in`), strips the tags and keeps at most three; a draft left with no cited point (an opener or Move today alone included) is replaced by the fixed nothing-new line, unless it is just the quiet line. The cache key also carries the brief model, so switching the Executive's model rewrites the header on the next view. With no MOVED TODAY line (a calendar alone does not count) there is no model call: an empty board writes the quiet line (`QUIET_CONTEXT`), and open items with nothing new write `Nothing new today — what's open is below.` (`NOTHING_MOVED_CONTEXT`). Every brief (this header, a teammate's header, the morning brief, the end-of-day digest) is written with `narrative.brief_model()`: the Executive's own model (its Council pick, else `DEFAULT_MODEL`), not the background `ROUTING_MODEL`. Every brief call goes through `create_brief_text` with room for the model's own thinking (`BRIEF_MAX_TOKENS`, 4000; the 5.5 models think by default and some cannot turn it off): a reply cut off at the limit or with no text is asked for once more with twice the room, then raises `BriefNotWritten`. An unwritten brief is never sent, and never stands in as the quiet line: the morning brief and end-of-day digest fail the run, and the /today header keeps its last cached text. A teammate's header keeps the older render below. The paragraphs that follow describe the live signals MOVED TODAY reads.\n\n**Live, not just the board.** The header used to reason over the alert board, goal health and the Executive's own bookkeeping only — mail and chat handled that day, replies the gate held and the next meeting never reached it, so it read the same for days while the principal's day moved on. The whole-company scopes now open the context with the principal's world as it is happening (`briefing.live_signals.gather_live_signals`, rendered by `render_live_blocks`), under a `NOW:` line: **INBOUND** (`integration_inbound` audit rows that carry a message, one per message id, grouped by sender and subject, with an email's first line; the principal's own mail reads \"from the principal\", an email from the roster says \"the Executive replied\" only when a reply was logged in its thread after it (`unanswered_mail.record_reply`) and \"no reply went out\" while its `unanswered_mail` card is open (on the principal's own read only), and a time on another day carries its weekday and date), **STUCK** (`integration_outbound_blocked` to a recipient, the inbound \"reply blocked at outbound gate\" and Google Chat \"left unanswered\" / \"not delivered\" rows, and chat drafts Act as me saved in the principal's mailbox that are still there: `delegation_drafts` rows not yet marked sent or `gone_at`; before each scheduled header refresh, each morning brief and, at most every 2 minutes, the principal opening `/today` (`today._maybe_settle_on_view`, which runs `refresh_principal_narrative` after the response, so this holds even with the background header refresh slowed or off), `live_signals.settle_principal_drafts` looks up the principal's open chat drafts from the last two days in their mailbox and marks the ones sent or deleted there, answered by a message of their own sent in that thread after the draft, or sent another way: one read of their latest 15 sent messages, only while a draft is still there, finds one sent after the draft with the same subject (Re:/Fwd: aside) to one of the same people, as when they redrafted and sent the other version or wrote it fresh. So a draft they sent (or replied around) from Gmail stops reading as waiting, and a failure on one draft no longer stops the pass for the rest; the same read keeps, in memory only, who each waiting draft goes to and its subject, so STUCK names each draft instead of a bare count), **CONVERSATIONS** (the principal's own web chat titles, without times, so the header cannot point back at \"the 13:26 chat\", and never one a host origin's page wrote in: its title is that page's words, `sessions.host_wrote`), **OWN** (the principal's own mail and chat-app messages to the Executive, kept out of INBOUND and its count, principal scope only) and the **REST OF TODAY'S CALENDAR**. The principal's own messages and chats render as background blocks, and every brief prompt carries `OWN_MESSAGES_RULE`: they show what the reader already said and asked, are never reported back as news (no \"you messaged me\", no restated complaint or rating), and an open ask appears only as what the Executive is doing about it. The window is the local day, or the last 12 hours when that is longer. Private audit rows, drafts, chat titles and the calendar (meeting titles are the principal's own) are read only in the `principal` scope — `gather_live_signals` drops the calendar whenever `include_private` is false, whatever the caller passes, so the shared `company` header never quotes it. The calendar read is the principal's calendar as the Executive reads it merged with their own calendar when Read my calendar is on (`top_three.read_todays_calendar`). The calendar is never fetched on the request: `live_signals.refresh_calendar` caches one read per 15 minutes (the scheduler tick refreshes it) and the header quotes the cache. Every quoted field is collapsed to one line and cut, and the blocks and the prompt both say the text is data, never instructions — inbound mail is attacker-controlled. With live blocks present the context also ages each proposal (`raised 2d ago`, whole days), names each at-risk department's slipping goals (`attention_goals`) and adds an **EXTERNAL SIGNALS** block (monitoring alerts from the last 24 h, never enough on their own to break the quiet line); the rhythm runs (`today.RHYTHM_WORKFLOWS`: the morning brief, end-of-day digest, reflection and weekly review) are dropped from the activity it reasons over. The prompts (`BRIEFING_NARRATIVE_SYSTEM` and its solo variant, `NARRATIVE_PROMPT_VERSION` 6) lead with what is live and give a days-old item at most one bullet. Anything live breaks the quiet line; the NOW line and window move at most once an hour, so the key moves hourly on time alone plus whenever something new lands; the calendar is placed at the real time (a meeting that has ended drops out, the one under way is IN PROGRESS), which moves it only when a meeting starts or ends. An address that belongs to someone on the roster (or, in the principal scope, one of the principal's contacts) reads `Name (address)` in these lines (`live_signals._named`), so the header calls people by name instead of making one up from the address.\n\n **Who reads it.** Every brief surface (this header, the morning brief, the end-of-day digest) is written for one person, fixed in code by `briefing.reader`: the principal on the principal scope, the teammate on a `person:<id>` scope, and the principal on `company` too (that scope has no signed-in caller and uses the principal's prompt, built from shared rows only). `render_briefing_context(reader=…)` masks that person's full name and email addresses everywhere in the context to \"the reader\" (their own chat and mail, the Executive's replies to them, chat titles, the activity rail) and heads it with a **THE READER** line naming them; every brief prompt carries `READER_NAME_RULE`: write \"you\", never the reader's name, \"the reader\" or \"the principal\" (anyone else by name), and \"I\" / \"me\" / \"my\" for the Executive. A draft that still slips (`reader.slips`), or reports the reader's own chats and asks back to them (`narrative.own_echoes`: \"you asked me\", \"your chat\", \"a chat with me\", \"the 13:26 … chat\", which `OWN_MESSAGES_RULE` forbids), is sent back once to be rewritten, and what is left of the reader slips after that is fixed in code (`reader.fix_slips`: the reader → you/your, \"the principal\" → the owner's name on a teammate's brief, the Executive → I/me/my).\n\n **Fresh without a reload.** The daily floor in the key and the PERIOD line are the principal's **local** date (`narrative_cache.local_today`), not UTC's, and a row written on an earlier local day is not served as today's. Nor is a stale row more than two hours old, or (the principal's header) one written before a meeting on the cached calendar started or ended (`today._header_outdated`): with the rewrite failing, a 1:45 PM header still called a 2:30 PM call next at 4:40 PM. Regenerations are serialized per scope; a trigger that finds one running marks the scope pending and the running pass goes round once more (it built its context before that trigger's news landed), and after a failed pass (model error, the 33 s timeout: 25 s for the draft and 8 s for a rewrite, empty text) no view or tick starts another for 5 minutes and `narrative_stale` reads false, so the page drops its placeholder instead of spending a model call per view. They log `today: narrative served scope=… age_s=… stale=…` and `today: narrative regenerated scope=… ms=…`, and no longer need a page view: every `BRIEFING_NARRATIVE_REFRESH_MINUTES` (10) between `BRIEFING_NARRATIVE_REFRESH_START_HOUR` and `_END_HOUR` (06–22 local) the scheduler runs `today.refresh_principal_narrative`, which refreshes the calendar cache and rewrites the principal's header only when its key moved (see Scheduler). The Briefing re-polls `/today` at 4, 10 and 20 s while `narrative_stale` is true, re-pulls it when the tab comes back (at most once a minute) and every 5 minutes while visible, shows \"Checked 2:20 PM\" beside the heading (`narrative_checked_at`: the time of the request when nothing the header reads has moved since it was written, so a quiet header doesn't read as stuck at the hour it was written; \"Updated …\" from `narrative_generated_at` otherwise), and shows \"Catching up on today…\" while the first header of the day is written (`lib/narrativeFreshness.ts`, tested by `npm test`).\n\n In **solo mode** (one person using Open Executive for themselves) the header speaks to the principal, whatever their role: a solo prompt over a context that lists goals at risk by *area* and has no \"people waiting on you\" block, and the quiet check ignores who is awaiting. The cache key carries the mode for solo only, so solo and team never share a cached narrative while every team key stays exactly what it was — no team cache is invalidated. The response shape does not change. For the principal's own view the solo context also carries a **DUE THIS WEEK** block — the principal's open loops that are overdue or due within 7 days (`today._with_due_soon` → `open_loops.principal_due_soon`, labelled OVERDUE / due today / due <weekday>) — which counts as needing attention in the quiet check and moves the cache key when an item is added, closed or falls due; a teammate's scoped view and team mode never get it. The header never gets the morning brief's *top three today* block — that is the DM brief's (see Workflows); the page shows the same top three in a card of its own (see *Solo focus cards* below). It does get the rest of today's calendar through the live blocks above, from the cached read.\n- **`in_flight`** / **`awaiting`** — upcoming Executive commitments and people we are waiting on.\n- **`handled_overnight`** — the autonomous moves the Executive *completed* since the last delivered morning brief: the alert review's (routed, nudged, escalated, drafted, merged, closed) plus the research watch policy's (`watching` — a watch added on its own because it was grounded in company data; `stopped_watching` — a research watch auto-disabled as noisy or dead; no alert id, re-enable from `/watchlist`). A `changed` verdict (the review rewrote an open alert's headline / body / severity) is deliberately **not** here: the alert is still open in \"Needs you\" and its card carries the note, so the brief reports it under \"what changed\" (a REWRITTEN block) rather than as done. Each row is structured, not just a sentence: `kind`, the audit `summary` (nudge bookkeeping marker stripped), `at`, `alert_id`, `event_type` (for a pre-filtered `/audit` deep link), `headline` (the alert's headline at move time; a watch's slug), `target` (person name for routed / nudged, survivor headline for merged, new severity for escalated, draft title, workflow name), `detail` (the cited evidence or the watch policy's reason), `outcome` (`resolved` | `dismissed` for a close, `proposed` for a route that went through the authority gate), `evidence_ref` (S1 / R2 / A3), `superseded_by_alert_id`, and `status` — the alert's lifecycle state **now** (`open` = live in the queue per `lifecycle.is_live` | `resolved` | `dismissed` | `expired` | `merged` | `acked` | `inactive` for snoozed / past-TTL rows), looked up per row so a close the principal already undid renders as reopened instead of offering a second Undo, and a \"still open\" jump link only appears when there is a card to land on. Audit rows private to the principal (say, one naming their contact) are in this list only on the principal's own `/today`: `brief_state.handled_since` leaves them out unless asked, and the written briefs never ask, since a brief can be read by others. The Pulse heatmap's per-day counts (`GET /today/activity/daily`) likewise leave out a private decision or private alert, as the activity rail does. The morning brief also carries a one-line count of research watch suggestions waiting on `/watchlist`.\n\n**From your chats.** `briefing.brief_requests` holds what the principal asked of their brief in conversation: `leave_out` lines from `leave_out_of_brief` (\"take the Halcyon renewal out of my brief\", kept 14 days) and `raise` lines the conversation review could not fix itself (`raise_in_brief`, kept 2 days), at most 20 live. A line is at most 12 words (leave out) or 30 (raise), with no link, handle, markup, identifier or talk of instructions, and only lines written under the principal's own id render. `render_briefing_context(brief_requests=True)` adds the raise lines before the quiet-day check, so they are raised even on a quiet day, and the leave-out list as the very last block; both sit inside the rendered string the /today header hashes. A teammate's brief or header passes `False`: they are the principal's own words.\n\n**Standing facts.** `render_briefing_context` appends the standing facts (`memory.facts`: corrections kept from chat, a teammate's marked `(per <name>)`) as its last block, after the quiet-day check, so a fact never makes a quiet day look busy. Every brief prompt (this header, the teammate header, the morning brief and the end-of-day digest) carries `narrative.STANDING_FACTS_RULE`: use the facts quietly, never mention one or that it was saved, and leave an item a fact settles out without saying it was dropped. A fact settles only what it plainly says. Without it, a fact saved in chat came back as the header's top point, stretched to an item it never named. The morning brief also carries **TEAMMATE CORRECTIONS SINCE LAST BRIEF** (`facts.render_teammate_changes(since)`: each teammate fact recorded in the window that is in use now, plus — only when the brief is the principal's own private one (`_private_ok`), which then keeps the run out of the shared history — those waiting for their approval, since other teammates may run the brief and never see a proposal that is not theirs) before the quiet check — it is news, the principal's only FYI of it — and in the brief's fingerprint (`build_brief_fingerprint(teammate_changes=)`), so a correction alone un-suppresses an otherwise unchanged brief. Every other caller passes none, so its context is unchanged. The /today header hashes that rendered string as its cache key, so a new or retired fact marks the header stale and it is rewritten with the correction. The morning brief (standalone) and the teammate-scoped header get the same block. On the scheduler's delivery to the owner alone, with their Always in the loop switch on, `render_briefing_context(owner_notes=)` also carries FROM YOUR NOTES — DUE SOON (their own notes of what they promised or asked, overdue to a week ahead; `memory.history_brief`), which counts against a quiet day, enters the fingerprint and marks the run private; both standalone prompts turn it into a **From your notes** section. The /today header never gets it. **The first week.** For seven days from the principal's People row (`briefing.first_week`), `render_briefing_context(getting_started=)` carries a GETTING STARTED block right after the live blocks: the install's goal rows (department, key result, target, period) or, while there are none (setup saves no goal rows, so this is a fresh install's usual case), this year's priorities and north star from the saved profile (`strategic_priorities`, up to five, keys `priority:<text>`), departments with no `head_person_id`, and, on the scheduler's delivery to the principal alone with Act as me and Draft replies to my inbox both on and the mailbox connected (the inbox watcher's consent), up to five people who wrote to their own mailbox in the last 48 hours as sender and subject only (`inbox_message_ids` + headers of `get_message`, bulk and automated mail skipped; the same \"where, never what\" rule as `delegation.mail_reads`) and, with Act as me and Read my calendar on, up to eight of today's events on their own calendar as time and title (declined ones left out). It counts against a quiet day, enters the fingerprint (`getting_started=` keys, no dates; a meeting's key is its event id) and, with the inbox or calendar part, marks the run private. Both standalone prompts open with a **Getting started** section and take the Top call from it (`GETTING_STARTED_RULE`). The /today header does not get the block: in the first week it is the same header as any other day. Home's top slot is instead the **first-week card**, built in code with no model call (`first_week.first_week_card`): `needs_goal` while no goal row exists (fixed ask \"Give me one goal with a date, and I'll track it every day.\" and a **Set a goal** button to `/goals?add=1`, which opens the add form), up to two findings from the latest finished team `executive_research` run (the run history keeps only the artifact, so `executive_research.parse_artifact_findings` reads back its \"Findings reviewed\" lines; most severe and most certain first, headline plus the summary's first sentence) with a line linking `/watchlist`, and `brief_tomorrow` on the setup day until the first morning brief is delivered. No goal still to set and no findings means no card. `GET /today` sets `first_week_card` and `first_week` (whether there is a card) for the principal only; while there is one the Briefing hides the \"Quiet day\" banner and an all-zero summary line reads \"Your first week. Start below.\" The last setup screen (`OnboardDone`) offers one first question built from the saved priorities (`firstQuestion`) and hands it to Home through session storage (`oe.onboard.firstQuestion`, never the URL), which asks it once. A teammate's scoped header never gets it. The alert review's `render_batch` puts the same block ahead of the alerts (read once per pass), so a note, rewrite or routed DM never repeats a figure the principal already corrected.\n\n**When a brief isn't sent.** Above the Briefing, the owner sees a one-line notice when their latest morning brief, end-of-day digest or (in solo mode) weekly review wasn't sent — \"Your morning brief wasn't sent: nothing is set up to send it to you\" — with the day, what fixes it, a link to read the brief on the Artifacts page (left out when the brief couldn't be written at all) and one to Setup status. It comes from `GET /today/brief-delivery` (the scheduler records each run's outcome), shows nothing while briefs go out or while the scheduler is off, and clears once the cause is fixed. When the Executive's mail connection wasn't running (the MCP gateway failed to start and is retrying), the notice says that instead of blaming the owner's setup; a send that failed on every channel names what each channel answered, from the recorded `detail`, with addresses left out. Teammates never see it.\n\n**Replies waiting.** With Act as me's **Draft replies to my inbox** on, the top of the Briefing's left column lists the replies the Executive drafted in the owner's own Gmail for mail that needs them (`RepliesWaiting`, from `GET /delegation/replies` — see Act as Me). They belong to the owner alone: the route answers only the person who can have Act as me, the decisions behind the cards (`delegation_reply`) are principal-only and carry `private: true`, so `/today/activity` and the heatmap leave them out, and none is ever an alert, so nothing of them reaches `GET /today`, the header or the briefs. Each card shows who wrote and who they are to the owner, whether their address was verified, the subject, what they wrote (as plain text), the draft, **Decide before sending** (its open questions) and its warnings, with **Send**, **Edit in Gmail** (the thread in their Gmail) and **Dismiss** (which deletes the draft unless they edited it). **Send** asks first, naming who the reply goes to, then sends the draft exactly as it is in Gmail (`POST /decisions/{id}/approve`); when its recipients changed in Gmail or a newer message arrived, the backend's 409 `confirm` becomes a second question naming them. The card hides itself when nothing is waiting.\n\n**Solo focus cards.** `GET /today/top-three` and `GET /today/weekly-review` feed two solo-only cards, so a principal who only uses the web app — no chat app, no Google Workspace — sees today's top three and the weekly review instead of finding them only in the Workflows run history. Both answer only in solo mode (`effective_workspace_mode`) and only to the principal, by the stricter rule for starting a principal-only run (`workflows._caller_is_the_principal`: the caller's own email on a principal entry that is not archived, or no `x-caller-email` at all — never \"nobody is principal yet\"); a teammate, any other signed-in caller and team mode get null. `top-three` hands `open_loops.principal_due_soon()` to `briefing.top_three.build_top_three` — the morning brief's own inputs and code, so the items, their order and their free slots are the brief's — and returns `{items: [{key, kind, text, why, slot}]}`: `slot` is the free block (\"10:00–11:00\", the user's zone), \"\" when none is left, or null when no calendar was read (none connected, a failure or the 4 s timeout, a weekend); `items` is empty when there is nothing to pick. It is a route of its own, never part of `GET /today`, so the Briefing never waits on the calendar. `weekly-review` returns the latest `weekly_review` run with status `done` (`persistence.list_runs(..., status=\"done\", limit=1)`, newest `updated_at` first; failed and running runs never count) as `{run_id, completed_at, period, top_three, excerpt}`: `weekly_review.summarize_review` reads the artifact's title line and its last *Next week's top 3* section back as plain text, and `excerpt` stands in when that list is empty (the section's own note, else the review's first lines). Null when no review has completed or the run store cannot be read.\n\nThe route resolves the caller from `x-caller-email`, serves the viewer's cached narrative and, when its key moved, rewrites it in a `BackgroundTask` so the request never blocks on an LLM call (the page re-polls while `narrative_stale` is true). `GET /today/activity` returns the recent self-initiated action rail — merged from fired scheduled actions (DMs, follow-ups, nudges, cadences), logged decisions, saved advice, completed workflow runs (briefings/check-ins/research), kicked-off initiatives, resolved gated decisions, and raised alerts, so it reflects all of the Executive's activity rather than just dispatched messages. A brief or digest delivered to its reader (`scheduler.runner._deliver_to_principal`) records its send as kind `brief_delivery` (`schedule_tools.recorded_as`): the outbound guard still counts it, but the rail and the heatmap leave it out, because every later brief reads the rail and used to repeat its own last top call as work done. A completed run is named in plain words, never by its log title (`workflows/run_outcome.py`: \"Researched your market\", \"Checked in with Sales\", or the name it was started with, less any date or how-it-started note), and carries `detail`, one line on what came of it read from its stored artifact (research: updates looked at, messages sent, alerts raised, things now watched; a check-in: actions proposed; the weekly review: next week's top item; other runs: the first sentence; none for briefs and the reflection), and `artifact_id` (`run:<id>`) when it kept a write-up (never for the reflection, which reads the principal's live alerts), so Pulse's Done for you and All activity link **Read it** to `/artifacts/run:<id>`. The Pulse page (`/memories`) polls it (limit 100) every ~20s so new events stream into the 'Recent activity' card, which scrolls internally at a fixed height instead of growing the page. The `morning_brief` workflow calls `_build_today()` directly to build the standalone DM (via a different, enumerated prompt; solo mode has its own, with goals at risk by area and no waiting-on section). `GET /morning-brief` is a deprecated alias.\n\n**Solo mode in the UI.** The response is the same in both modes; the briefing reads the workspace mode from the app-wide `WorkspaceProvider` (which reads team while loading or on error, so a team install never flashes solo) and, in solo, drops the team surfaces: the Departments card, the People card, the \"Across the team\" lane (every action proposal is the one user's, so all of them land in \"Needs you\"), the people-awaiting, people-overdue and departments-at-risk status pills, and the quiet-day \"Set up a check-in\" link. A \"N goals at risk\" pill (at-risk plus off-track goals, from `departments`) links to `/goals` instead, so the strip never reads \"All clear\" over a goal that is slipping. In the Departments card's place, **Your projects** lists the initiatives with status `active` (`GET /memories/initiatives`): **Done** marks one `completed` through `PATCH /memories/initiatives/{id}` (only `completed` takes an initiative out of the Executive's active context), and **Drop** deletes it through `DELETE /memories/initiatives/{id}` after a confirm. Under **Needs you**, a **Due soon** card lists the principal's open loops that are overdue or due within 7 days — their dated commitments and what others asked of them — read from `GET /people/{id}/open-loops` for the principal (the oldest principal in `people`, the backend's rule), labelled by `lib/dueSoon.ts` (tested by `npm test`: \"Overdue since Sep 23\" / \"Due today\" / \"Due Mon, Sep 28\", with a count of anything due later); **Done** closes one through `POST /open-loops/{id}/close`, which also stops the nudge engine chasing it. Above it, **Top three today** numbers the morning brief's three (`GET /today/top-three`) with each one's reason and, when a calendar was read, its free slot (or \"No free time left today\"); at the top of the right-hand column, **This week's review** (`GET /today/weekly-review`) shows the period, when it ran, next week's top three (or the excerpt) and a *Read the review* link to its run page (`/jobs/runs/{id}`). Each card fetches on its own once the Briefing has loaded, so a slow calendar never holds the page up, and renders nothing when the API returns null or an empty list. A commitment in the top three reads as the owner's own (\"Send the proposal\") through `lib/dueSoon.ts`'s `loopText`, as in Due soon; the cards' wording lives in `lib/rhythmCards.ts` (tested by `npm test`). The Pulse page hides its \"Department check-ins\" and \"Awaiting people\" blocks in solo, and its header shows active projects in place of the department check-in count. Team rendering is unchanged.\n\n**Your month (`GET /today/value`).** The owner's own tally of what the Executive did for them, `briefing.value_summary.summarize(period, offset)`: the calendar `month` or `week` (Monday first) in the user's zone, `offset` periods back (0–24), each line beside the period before. Every number is a `COUNT(*)` of rows that prove it happened, never a model's: messages sent for the owner (the DM handlers' own `kind=outbound` sent rows to anyone but the owner, plus Gmail / Outlook send-tool calls that didn't come back with an error, so mail sent from a chat turn counts), replies drafted and sent from the owner's inbox (their Act as me rows), meetings booked (calendar create calls), briefs delivered (the scheduler's `delivered` row), reports (finished team workflow runs, minus the daily rhythm runs and any run a teammate started for themselves, which stays theirs alone; the latest ten listed with links), follow-ups and nudges sent, tasks tracked and closed as done, proposals decided, alerts flagged and requests answered (`chat_turn` out rows). No \"hours saved\" and no cost line: nothing recorded supports the first, and cost next to what the owner got reads as a bill; it has `GET /audit/usage`. The owner's alone (403 for anyone else): it counts rows private to the owner, never a row private to another member. Pulse shows it as the top line of the overview's **Done for you** panel (\"October 2026: 42 messages sent, 6 reports, 3 meetings booked\") and a focused screen, `/memories?tab=value`, with a month / week switch and previous / next. On the first weekday of each month, in daytime (09:00–18:00 local), a scheduler tick hook sends the owner last month's lines and a link (`value_summary.maybe_send_monthly`, claimed once per month under `briefing_narrative` scope `value_summary:YYYY-MM`), in solo and team mode alike; nothing is sent for an empty month. Off with `VALUE_SUMMARY_MONTHLY_ENABLED=false`.\n\n## Alert lifecycle & the Executive review\n\nAlerts used to be write-once: raised, then never looked at again, so the \"Needs you\" queue grew without bound and the briefs re-listed it daily. Four things now keep it live and true:\n\n- **Time-to-live** (`openexecutive.alerts.lifecycle`). Action items expire after `ALERT_TTL_DAYS_ACTION` (14 d), unrouted low/medium monitoring signals after `ALERT_TTL_DAYS_MONITORING` (3 d). Every surface reads `list_live_alerts` (the same predicate the scheduler's 15-minute sweep persists as status `expired`), so `/today` is right even before the sweep runs. Artifacts and decision-backed alerts are exempt. `POST /alerts/{id}/reopen` is the Undo. **Snooze** (a card's ⋯: later today, tomorrow 9:00, Monday 9:00, in the viewer's clock; `POST /alerts/{id}/snooze`) hides a card until `snoozed_until`, with an Undo; the TTL anchor is the latest of `created_at`, `last_seen_at` and `snoozed_until`, so a snoozed card comes back rather than expiring unseen.\n- **Coalescing** (`alerts.pipeline` + `store.coalesce_alert`). A repeat of an open alert with the same `(source, dedup_key)` updates that row — `occurrence_count`, `last_seen_at`, severity max — instead of stacking a second card, and only re-pings when severity rose to high/urgent. Monitoring alerts carry a stable `watch:<slug>` key, so one watch means one card.\n- **Collection tags** (`alerts.pipeline`). A triaged alert never carries a `collection:<name>` tag: the pipeline strips them before inserting. Only an installed extension's own code files a document into its collection (`orchestrator.extensions`), so injected text can't make a card that the extension would treat as its own.\n- **The review** (`openexecutive.alerts.review`, heartbeat `alert_review_scan`, every 6 h and right before the morning brief). For each open alert the Executive sees what changed since it was raised — newer signals from the same watch, related alerts, activity since, the roster with SLAs (team members only — an alert routed to a contact never puts them in the slice, so they are never routed to, nudged or chased; a private card is never reviewed at all, nor used as evidence for another), department authority — and returns a verdict (relevant / changed / resolved / stale) plus a recommended move. Deterministic policy then acts: **route** (assign + DM the owner; `propose_via_alert` for propose-only departments), **nudge**, **escalate** (severity + `due_at` + DM the principal only), **draft** (`draft_artifact`), **suggest a workflow** (a link, never a run), **merge** (`superseded_by_alert_id`), or **resolve** — only on high confidence citing a server-minted evidence ref (a newer signal, a related alert, an activity item shown for that alert); free text never closes a card, and anything weaker is annotated `likely_stale`, demoted 30 ranking points, and left for one click. Everything that came from outside is rendered as inert data inside the review prompt, so an injected email body cannot steer the batch. Board / comp / legal matters only ever go to a scope-holder or the principal and keep their text. Route and escalate are idempotent across passes, every DM carries an \"[Alert review] Re: …\" header, outbound moves are capped per pass, passes are single-flight, `ALERT_REVIEW_ENABLED=false` stops every caller, every move is audited with its evidence and prior state, and a distinct `resolved` status keeps Executive closes separate from `ack` (user approved). A review DM is proactive outreach, so the recipient's notification settings apply: one held for their quiet hours or brief counts as a route made but not as a nudge toward the cap (and no second nudge is held while one waits), and one about an alert whose severity is (or becomes) `urgent` is marked urgent (`notifications.urgent_send`) and gets through when they let urgent things through.\n- **Grounded text** (`openexecutive.briefing.grounding`). Nobody reads an alert's text before it is dispatched, so what the model wrote onto it must be supported by what it read. After triage (`alerts.pipeline._ground_decision`, before coalescing or inserting), a headline naming a person or figure the event does not hold — sources are the event's subject, sender, title and body, the initiatives triage was shown and the company profile — is replaced by the event's own subject, such body sentences are dropped (all of them → the event body cut to 280 chars); both fallbacks are raw event text, so they are made inert first — links masked, Markdown and Slack `<…>` syntax and @-mentions stripped — because a broadcast posts them as written, and such a suggested action is dropped. A review `changed` rewrite is checked against the alert's own text and the evidence it was reviewed with (signals, related alerts, activity, the roster slice), plus the standing facts the batch was shown, so a rewrite that corrects a card to one of the principal's corrections is grounded; an ungrounded rewrite keeps the old text, still applies a severity change, and audits `text_ungrounded`. A name counts as grounded only when one source line holds all of it; a figure only when a source number matches it within the precision it is written with. Each finding writes a `grounding` audit row; `GROUNDING_CHECKS=report` records without changing anything.\n\nOn the page, cards read as decisions: the one-line \"what changed since you last looked\" (`review_note`) leads, the recommended move is the primary control (Nudge <owner> → chat; Run <workflow> → `/jobs/<name>`), with chips for age, seen ×N, why-now / due, folded-in and draft-ready, a \"Reviewed <ago>\" footer, and an amber Likely-stale treatment with one-click Dismiss. \"Needs you\" shows *Start here* + 8 cards + \"Show N more\", a \"Dismiss N older than 7 days\" footer (explicit ids to `POST /alerts/bulk-ack` — never a server-side age sweep, which would hit teammates' routed items), and \"Re-check relevance\" (`POST /alerts/review`). The handled rail (anchor of the \"Executive handled N overnight\" pill) is deliberately one sentence by default: a first-person heading built from counts only — \"Since your last brief: N off your plate (closes still standing, and merges whose survivor is not itself listed; a merge into a listed survivor counts on that survivor's row), N in others' hands (routed / nudged), N waiting on you (escalated)\", plus \"N drafts ready\", \"N workflows suggested\", \"N watch changes\", \"N other moves\" (a kind the UI does not know) and \"N back on your plate\" (a close that is open again) when present — with the rows behind a \"details\" disclosure, and nothing rendered at all when the grouped rows are empty. The pure logic (grouping, headline, links) lives in `packages/ui/src/lib/handled.ts` and is covered by `npm test`. Expanded, it shows one first-person row per alert (\"Resolved *X* — evidence\", \"Dismissed *X* as stale — evidence\", \"Handed *X* to Dana Kim\" / \"Proposed *X* to Dana Kim (awaiting their approval)\", \"Chased Dana Kim on *X*\", \"Raised *X* to high\", \"Drafted *T* from *X*\", \"Folded *X* into *Y*\", \"Started watching *slug*\"), escalations first; rows sharing an alert collapse to the newest move with the others as an \"also …\" trailer — a close always keeps the visible slot (it carries Undo), otherwise an escalation beats routed / nudged / drafted; a merge whose survivor is listed becomes \"N duplicates folded in\" on the survivor. Every row links its `evidence_ref` (or \"evidence\") to `/audit?event_type=…&q=…` (the audit page pre-fills those filters from the query string), a still-open row jumps to its card (`#alert-<id>`), drafted rows link `/artifacts`, watch rows `/watchlist`. Undo is offered only while the close still stands (`status` not `open`); a reverted close shows \"Reopened\". Dismissing a watch-sourced alert lowers that watch's `trust_score` (which discounts ranking and is shown to the review as evidence); the ack body may carry `mute_topic`. Acknowledging or resolving an alert — including the review closing it itself — marks the review's DMs about it `acted` in the Attunement outcome ledger, for the person it is routed to and the principal only; dismissing it, finding it stale or letting it expire voids them (counted neither way). Review DMs are tagged `alert_review` with `alert:<id>`.\n\n## Multi-client practice section\n\nIn multi-client practice mode (2+ client slots — see the Client Companies section), the response gains an additive `practice_clients` list: rollup cards for the **parked** clients (overdue follow-ups, awaiting replies, unread alerts, onboarding due soon, renewal countdowns), each stamped with the save point its data reflects. Single-company installs always receive an empty list and the UI renders nothing.",
+ "markdown": "`openexecutive.api.routes.today` serves the morning brief — a one-screen, read-only view of what is happening across the org. It is the default landing surface (the Next.js root renders `<Briefing>`). Every signed-in page shares one sidebar (`AppSidebar`). Its Recent list is capped at the 7 newest web chats. The full history, including Slack, Telegram and Discord conversations (recognised by their session-id prefix), lives on `/chats`. A chat opens from any page through `/?session=<id>`.\n\n`GET /today` returns `TodayResponse` assembled by `_build_today()`, which is synchronous and caller-agnostic:\n\n- **`departments`** — per-department goal health, rolling up each department's goal counts (`total`, `at_risk`, `off_track`) plus its awaiting-workflow count, and `attention_goals`: the actual off-track/at-risk goals (worst first, capped at 3) with `key_result`, `current`, `target`, and `status`, so the briefing's Department card shows *which* goal is off and how far without a click. Empty for healthy/inactive departments. Each attention goal also carries `owner_id` and `owner_name` (its own owner, else the department's head, else the principal), and the narrative's goal lines name the owner. Goals with no department get one more row, slug `\"\"` and title **Other goals** (`UNASSIGNED_GOALS_TITLE`), shaped like a department so every reader of `departments` (the header context, the narrative, the reflection, the fingerprint, the digest) counts them; it is added only when such goals exist, links to `/goals` in the UI, and a teammate's slice keeps only the goals on them.\n- **Private cards.** An alert tagged `private:principal` (`alerts.models.PRIVATE_ALERT_TAG` — raised on a turn about mail from one of the principal's contacts or mail they forwarded, or a meeting proposal with a contact) is in `proposals` only when the caller is the principal. The chat's alert digest (`briefing.context.render_and_trust`) shows it, and the roster requests, only on the principal's own verified turn, never in a web chat they shared with others, where everyone reads the reply. `_build_today` leaves it out by default, so the end-of-day digest, the reflection and Discord's `/today` never see it, and the morning brief reads it only on a run for the principal (the scheduler's, or the principal's own verified chat turn in a conversation only they can read — see Workflows). The narrative is written from one only in the principal's own `principal` scope, which nobody else is served; the shared `company` scope an unresolved caller gets, and a teammate's scope, never are. The activity rail skips it, and the chat digest includes it only on the principal's own verified turn.\n- **Raised by a team member.** An alert a team member raised from chat (`AlertEvent.raised_by`, source `team_member`) has its body led by \"Raised by <name>.\" and never goes out on `company_broadcast`: the pipeline drops that channel after `resolve_channels`, so it reaches a person or a department room only. One team member's alert never coalesces into another's (the dedup key is prefixed with who raised it). A team member's saved workflow raises alerts as its creator (`action_step` binds `dynamic_store.get_owner` around `oe__create_alert`). Alerts from email, watches and other sources are unchanged.\n- **Who clears a card.** `POST /alerts/{id}/ack` with `ack` or `dismissed` answers 403 to a team member unless the alert is routed to them (`read` is open to anyone who can see it); only the principal's dismiss applies `mute_topic`, since a mute silences the topic for everyone. `POST /alerts/bulk-ack` from a team member clears only the listed ids routed to them and refuses an `older_than_days` sweep. The principal, or anyone before a principal is set up, clears anything. `ack_alert` in chat follows the same rule.\n- **Roster-request cards.** When someone not on the People list writes in (see Org and Integrations), `people.roster_requests.surface_card` raises an alert of source `roster_request` (medium, tagged `roster_request:<id>` and `private:principal`, routed to the principal), so it follows every private-card rule above. `GET /today` attaches `roster_request` to that proposal (`_roster_request_card`: channel, address or account id, the sender's sanitised and unverified name, profile email, company-domain flag, suggested kind and person, message count, whether they were acknowledged, first seen, and the held messages' first lines) while the request is still pending. The Briefing renders it as its own card (`RosterRequestCard`: add as a new person with a name and an explicit team/contact choice — pre-filled as team on a company domain — or \"someone already on the list\", with a replace-account option for a chat id, or Ignore), which calls `/people/requests/{id}` directly and never hands off to chat, so what a stranger wrote never seeds a turn. The card is kept out of everything that could close it without answering it or put the stranger's words in front of a model: the narrative (`_action_proposals` drops it), the chat's open-alert digest (`<briefing>` — the principal's verified turn gets a separate `<roster_requests>` block instead; see Agents), `ack_alert`, a single ack (`POST /alerts/{id}/ack` is a 409), the \"Dismiss N older than 7 days\" count and the server's bulk ack, reopen, the TTL sweep and the alert review (`roster_request` is in `lifecycle.TTL_EXEMPT_SOURCES`). It ends when the request does: answered (`ack`, or `dismissed` on a decline) or expired after `ROSTER_REQUEST_TTL_DAYS`.\n- **`people`** — an attention-ranked roster of the **team** (the principal's contacts are never listed, and get no insight note). Each person carries `awaiting_action` count, soonest SLA, a `status` (`on_leave` / `needs_reply` / `awaiting` / `clear`), reachability, `overdue`, a server `priority` sort key, and a cached one-line `insight`. Sorted by `(-priority, full_name)`. Stale insight notes are regenerated in the background only when the roster has more than one person: the UI shows the People sidebar only for more than one, so a one-person install (solo, or a team before anyone else is added) does not pay a daily model and peer-memory call for a note nobody sees. Cached notes are still served.\n- **`proposals`** — the *live* unread alerts (workflow approvals, triage-classified inbound, Executive signals, flagged artifacts, and gated calendar bookings; an artifact is listed only to its owner (`alerts.models.visible_alert`; every other build of the board — the briefs, the reflection, the review, the chat digest on anyone else's turn, the activity rail — leaves drafted artifacts out) and carries `artifact_format` / `artifact_url` and a `body` already rendered to Markdown for its format, so the card badges it as a web page, Word doc, spreadsheet or link and offers *Open artifact*): unread, inside their category TTL, not snoozed — see *Alert lifecycle* below. Each carries `score`, `category` (`action` vs `monitoring`), `surfaced_reason` from `openexecutive.briefing.ranking`, the lifecycle fields (`occurrence_count`, `last_seen_at`, `last_reviewed_at`, `review_verdict`, `review_note`, `recommended_move`, `why_now`, `due_at`, `superseded_count`, `suggested_workflow`), and `decision_instance_id` (set only when the proposal is backed by a decision-ledger row — a calendar booking awaiting approval). `failed_run_id` is set only on a `workflow_failed` card (a scheduled run that ended in error, see Scheduler): its main button is **Run again** (`POST /workflows/runs/{id}/rerun`, which also closes the card) and its ⋯ opens the run; it has no Approve. The response also carries `held_back` for the principal alone: the lines grounding left out of the morning brief or end-of-day digest in the last day, which Home lists under **Left out of your brief** (the brief's note names it; Hide is remembered in that browser). The UI splits them into 'mine' vs 'across the team' using `caller_person_id`. Approve is carried out on the server for every card. For decision-backed proposals the card's Approve/Reject call the `/decisions` endpoints (which book or cancel the event server-side and clear the alert), so meeting bookings are reviewed in the briefing itself rather than on a separate page. Every other proposal is approved at `POST /alerts/{id}/approve` (`alerts.approvals`): it records who approved the card and when (an `alert_approvals` row plus `alert_approved`, then `alert_approval_done` / `alert_approval_failed`, audit rows), claims the card in one transaction so a double click or a second approver gets a 409 and the work runs once, then does the work. A card the scheduler filed for a department-gated action is bound to it server-side (`alert_held_actions`, written only as the card is filed, never read from the card's tags or text, which a model reading inbound mail can write), and approving it queues that exact action again with no department, the approval being the consent the gate waited for. Any other proposal runs one Executive turn as the approver in a new chat on the server (`chat.start_background_turn`, the machinery behind `POST /chat/background`), with the edited text verbatim for Edit & approve; it keeps going if the page closes. Only the card's routed person or the principal may approve a routed card, and only the principal an unrouted one (403 otherwise); the card's text reaches the turn as quoted data, not instructions. A row at the top of Needs you follows the approval (`GET /alerts/approvals/{id}`): working on it with a link to the chat, then done, or didn't work with Try again; a card whose last approval failed can be approved again, and one still running at a restart is marked failed on boot. The page no longer acks the card and seeds a chat turn with the proposal, which left no record of the approval and did nothing if the tab closed first.\n- **`narrative`** — a per-viewer Executive-voice header (\"What's going on\") synthesized by `synthesize_briefing_narrative`, cached per scope in `briefing_narrative`: the resolved principal gets the whole-company `principal` scope (which may carry what is private to them), a caller who resolves to no roster row the shared `company` scope (written from what everyone may see), and each teammate a role-scoped `person:<id>` one. `narrative_generated_at` says when the served text was written and `narrative_stale` whether a fresher one is being written now. Home shows it as **Right now**, a card above Needs you, because the text is rewritten through the day: When a rewrite of the principal's header adds a point (`right_now.record_points` returns the points whose key is new today), `briefing.right_now_ping` sends them one short message on their own chat app (`scheduler.runner.deliver_to_person(chat_only=True)`, tagged `right_now` so their notification settings apply): on **Important only** (the default; Settings → Notifications, `NotificationSettings.right_now`) only for a point citing a MOVED TODAY line that needs them (`header_context.NEEDS_YOU_PREFIXES`: mail or chat in, own-inbox mail, stuck, a decision raised today, their overdue item, a reply overdue, a chat ask it couldn't do), on **Everything** for any new point. Never for the first header of the day, at most 4 a day (`right_now_ping` audit rows), and dropped, not held, during quiet hours or \"In my briefs\". The points are model text over quoted mail, so every link, address and bare domain is stripped before sending (`plain_point`). `briefing.right_now.split_narrative` splits the served text into `narrative_lead` (the bold opener), `narrative_points` (`{text, since}`) and `narrative_move`. `since` is when that point first appeared today, kept per scope and local day in `briefing_point_seen` (keyed by the point's bold subject, so a reworded point keeps its time; recorded when a header is written, earlier days pruned then). `narrative_seen_at` is when this reader last looked, from `briefing_reader_seen`, set by `POST /today/seen` (same scope resolution as `GET /today`; the shared `company` scope of unrostered callers keeps no look, so one stranger's visit never resets another's); the page fixes it as the baseline for the visit, marks points after it with a green dot and *N new since …*, and only counts a look from earlier the same day. For the principal the response also carries `morning_brief` (`{at, text}`, today's delivered morning brief from `brief_state.last_delivered`) and `calendar_next` (up to 3 meetings still ahead today from the cached calendar read, never a fresh call), which the side panel shows under the points and Move today. Nothing here calls a model. In the web UI each bullet of this narrative is a click target: clicking one hands off to chat (the same `onContinue` path as the proposal cards) seeded to discuss that item. The Executive recognizes it because every chat turn now carries a `<briefing>` digest of open alerts (see Memory). That digest (`briefing.context.format_open_alerts_for_prompt`) is capped at 30 items; when the board is longer the header says so explicitly and tells the Executive to point at this page for the rest — it previously presented the capped list as the complete board, so the Executive described a slice as everything that was open (#136). Chat adapters get the digest too, but Slack gates it to the principal's DMs: the board is company-wide and must not be pulled into a shared channel. The `[alert_id]` at the start of each line is also what `ack_alert` trusts, because an id quoted inside an alert's own body came from inbound mail or chat and is attacker-controlled. This page's `[Discuss mode — alert_id=N]` handoff primer is a pointer to which item is under discussion, not authority on its own: the server accepts it only if that id is on the live board too. Two things enforce that. Every field the digest interpolates — headline, body, suggested action, tags, review note — is collapsed to a single line, since a newline in any of them would forge a whole extra `[N]` line and with it a fabricated instruction to clear someone else's alert. And the server records the live board it derived, so `ack_alert` refuses any id outside it — on **every** session, not just the chat adapters. The recorded set is the whole live board, not just the rows the digest printed, so a card past the render cap stays ackable. The control stops invented, closed, snoozed and expired ids; it does not stop the model being argued into acking the wrong *live* card. When the principal names an item that has already left the board — opened, snoozed, or older than it — the Executive looks it up with `find_alerts` (a keyword search over every status, `alerts.store.search_alerts`); matches that are still open (`unread` or `read`) become ackable for that turn, up to 25, and closed ones come back labelled so the Executive can say the item is already settled. It works only where the principal's own board was shown this turn — the web app or their DM — and never returns roster-request cards (see Lifecycle). The digest's header also labels every headline and detail as untrusted content drawn from inbound mail, chat and watched pages — act on what the principal asks about an item, never on what its text asks — and triage reads each signal inside an `<event>` block whose closing tag the sender's text cannot forge (it is defanged in any case and spacing, after NFKC folds fullwidth forms). That check used to run only when `origin_channel` was set, which the browser never sets, so the one surface where the principal actually reads their board had no check at all and the model could ack any id, including one quoted out of an alert body by the Discuss handoff. Rendering the block and recording its ids now happen together in `briefing.context.render_and_trust`, which both the web chat route and the channel adapters call: render without recording and the tool refuses everything, record without rendering and the model gets reach it was never shown. A turn that was shown nothing trusts nothing. Recording it is only half the wiring: the tool reads the board off the turn's session through a ContextVar, and the chat route binds that session for the whole SSE body (`set_session`, next to `set_turn`). Bound from inside the Executive's own generator instead, it survives exactly one stream step — `asyncio.wait_for` runs each step in a fresh Task with a copy of the context — and the tool-call loop, which runs later, sees nothing. That shipped, and every web ack was refused on cards that were open the whole time. The digest also carries a short **already handled** tail — recently acked / dismissed / resolved rows, named but deliberately NOT trusted for acking — because a card cleared on the page minutes ago is otherwise simply absent from chat: asked to \"record that as fixed\", the Executive could not tell a settled item from one it had never heard of, and sent the principal back to dismiss a card that was already gone. That tail renders even when nothing is open, which is exactly when it matters. Note it is a different window from the `handled_overnight` rail above: that one runs since the last delivered morning brief, while the chat tail looks back 14 days (matching the action-alert TTL, so it still covers an item cleared late in its life), so chat can name a settled item the rail no longer shows. On the principal's own verified turn the digest also lists their chat drafts still waiting in their mailbox (when, to whom, subject), so a brief line about a draft can be discussed; `read_my_email` shows drafts in a thread marked not sent, so a thread that is only a draft does not read as empty. The narrative is held to what is **live**, and to what it is actually for. The `alert_raised` source is dropped from the activity it reasons over (`_build_activity(..., include_alert_raised=False)`): a closed alert reads as work the principal already settled, and a *live* one is worse than redundant — `lifecycle.is_live` is the very predicate behind `list_live_alerts`, so every live raise is already a proposal card below the header, which the prompt forbids re-listing. The `/today/activity` rail keeps the whole source, because a raise really happened. The activity block is only labelled \"since last brief\" when the caller bounded it with `since` (the standalone briefs do; the header does not), since calling an unbounded history rail a delta made the header present weeks-old rows as overnight news. When the viewer's slice holds nothing that wants a decision — no action proposal, no at-risk/off-track department, nobody awaiting — the regen skips the model call entirely and writes the fixed quiet line (`Quiet right now — nothing pressing.`, or `… nothing needs you.` for a teammate). **The cache key is a hash of the rendered context itself** (`today._narrative_context` builds it once and both the hot path and the background task key off that one string, which is also handed to the model verbatim). That makes the key a function of the model's input: everything the prompt renders is covered, and nothing it omits can trigger a regeneration. Keying on hand-picked fields broke one half or the other each time — headlines alone left the rendered activity block uncovered, while the proposals' review fields are never rendered by this header yet are rewritten with fresh prose by every `alerts.review` pass, so they regenerated each viewer's narrative several times a day to re-synthesize identical input. A quiet board keys off a fixed sentinel instead, so a moving rail cannot re-key an entry whose text is constant. Together: on a fully dismissed board every other input was empty, the rail became the only context, and the model synthesized a confident header out of closed items.\n\n **Right now's context and its check.** The whole-company header (Home's Right now card, directly above Needs you) is written from `briefing.header_context.render_header_context`, not `render_briefing_context`. **MOVED TODAY** lists, each tagged `[M1]`, `[M2]`…, what happened or came due today: INBOUND mail and chat from other people, STUCK replies and waiting drafts, decisions raised today (with their why-now) or re-raised today, the principal's own open loops due today or overdue (`due_soon`, now in team mode too on the principal's scope), the Executive's follow-ups (`in_flight`) due today or overdue, overdue replies from people it waits on (team only), things it could not do from a chat (the brief-requests raise lines), work it finished today (activity rows from the local day, minus `advice_given` / `decision_logged`, which come from the reader's chats) and today's watchlist signals. **COMING UP TODAY** is the rest of the calendar, tagged the same way. In the principal's own header MOVED TODAY also lists the meetings that ended today (`live_signals.met_today`, latest three) and their own emails nobody has answered yet (`briefing.waiting_on`): sent from their own mailbox under Act as me in the last 7 days and over an hour ago, asking something (a question mark in their own words), to at most 10 people besides the Executive, and still the last message in the thread. It also lists mail to their own inbox that the Act as me watcher looked at today (`live_signals.own_inbox`, from the watcher's private `delegation_inbox_mail` audit rows: sender, subject and when, never a body), including newer mail on a thread whose reply card is still open, which a scan otherwise passes over: from people they deal with (team, contacts, people they have written to) one line each with what the watcher did (drafted, answered, no reply needed). Mail from anyone else is never a point (bulk, list and Gmail-tab mail is not recorded at all, so a busy day of it never crowds real mail out): `/today` returns up to three `Name: subject` labels and a count as `inbox_also` / `inbox_also_total`, which Home shows as one \"Also in: 2 others — …\" line under the points. A point can be opened from Home: `HeaderContext.sources` maps each own-inbox line to its email (`{kind: \"mail\", message_id, thread_id, decision_id?}`, from `OwnInbox.refs`) and each card raised today to its alert (`{kind: \"alert\", alert_id}`); after a rewrite `header_context.point_sources` reads which line each bullet cites and `right_now.record_sources` keeps point key → item for that header alone (`briefing_point_source`). The ids never reach the model. `/today` serves them as each point's `source`, and Home shows **View email** / **Reply** (an email, opened with `GET /delegation/mail` and answered on a reply card through `POST /delegation/mail/reply`) or **Show me** (the card in Needs you) under it. Only who it went to, the subject and when reach the model. The read runs in the background (`today.refresh_principal_narrative`, with the calendar), is cached for 15 minutes, and is dropped when Act as me is turned off; the briefs neither render these lines nor count them. **STILL OPEN** is what sits in Needs you and did not move (older decisions, later due dates, later follow-ups, goals at risk): background for ranking, never a point. **BACKGROUND** holds the reader's chat titles and own messages, only to judge what matters most to them. The rest of the history rail is never read: it made the header report yesterday's DMs as news, and chat titles made it claim work in progress (\"I'm combining the PDFs now\") hours after it was done. The prompt (`_header_prompt`) asks for a bold opener, **one to three** bullets that each end with the tag of the line they are about, and a **Move today** line for the reader. After the model, `header_context.keep_cited_points` deletes any bullet citing no tag the context had (`tags_in`), strips the tags and keeps at most three; a draft left with no cited point (an opener or Move today alone included) is replaced by the fixed nothing-new line, unless it is just the quiet line. The cache key also carries the brief model, so switching the Executive's model rewrites the header on the next view. With no MOVED TODAY line (a calendar alone does not count) there is no model call: an empty board writes the quiet line (`QUIET_CONTEXT`), and open items with nothing new write `Nothing new today — what's open is below.` (`NOTHING_MOVED_CONTEXT`). Every brief (this header, a teammate's header, the morning brief, the end-of-day digest) is written with `narrative.brief_model()`: the Executive's own model (its Council pick, else `DEFAULT_MODEL`), not the background `ROUTING_MODEL`. Every brief call goes through `create_brief_text` with room for the model's own thinking (`BRIEF_MAX_TOKENS`, 4000; the 5.5 models think by default and some cannot turn it off): a reply cut off at the limit or with no text is asked for once more with twice the room, then raises `BriefNotWritten`. An unwritten brief is never sent, and never stands in as the quiet line: the morning brief and end-of-day digest fail the run, and the /today header keeps its last cached text. A teammate's header keeps the older render below. The paragraphs that follow describe the live signals MOVED TODAY reads.\n\n**Live, not just the board.** The header used to reason over the alert board, goal health and the Executive's own bookkeeping only — mail and chat handled that day, replies the gate held and the next meeting never reached it, so it read the same for days while the principal's day moved on. The whole-company scopes now open the context with the principal's world as it is happening (`briefing.live_signals.gather_live_signals`, rendered by `render_live_blocks`), under a `NOW:` line: **INBOUND** (`integration_inbound` audit rows that carry a message, one per message id, grouped by sender and subject, with an email's first line; the principal's own mail reads \"from the principal\", an email from the roster says \"the Executive replied\" only when a reply was logged in its thread after it (`unanswered_mail.record_reply`) and \"no reply went out\" while its `unanswered_mail` card is open (on the principal's own read only), and a time on another day carries its weekday and date), **STUCK** (`integration_outbound_blocked` to a recipient, the inbound \"reply blocked at outbound gate\" and Google Chat \"left unanswered\" / \"not delivered\" rows, and chat drafts Act as me saved in the principal's mailbox that are still there: `delegation_drafts` rows not yet marked sent or `gone_at`; before each scheduled header refresh, each morning brief and, at most every 2 minutes, the principal opening `/today` (`today._maybe_settle_on_view`, which runs `refresh_principal_narrative` after the response, so this holds even with the background header refresh slowed or off), `live_signals.settle_principal_drafts` looks up the principal's open chat drafts from the last two days in their mailbox and marks the ones sent or deleted there, answered by a message of their own sent in that thread after the draft, or sent another way: one read of their latest 15 sent messages, only while a draft is still there, finds one sent after the draft with the same subject (Re:/Fwd: aside) to one of the same people, as when they redrafted and sent the other version or wrote it fresh. So a draft they sent (or replied around) from Gmail stops reading as waiting, and a failure on one draft no longer stops the pass for the rest; the same read keeps, in memory only, who each waiting draft goes to and its subject, so STUCK names each draft instead of a bare count), **CONVERSATIONS** (the principal's own web chat titles, without times, so the header cannot point back at \"the 13:26 chat\", and never one a host origin's page wrote in: its title is that page's words, `sessions.host_wrote`), **OWN** (the principal's own mail and chat-app messages to the Executive, kept out of INBOUND and its count, principal scope only) and the **REST OF TODAY'S CALENDAR**. The principal's own messages and chats render as background blocks, and every brief prompt carries `OWN_MESSAGES_RULE`: they show what the reader already said and asked, are never reported back as news (no \"you messaged me\", no restated complaint or rating), and an open ask appears only as what the Executive is doing about it. The window is the local day, or the last 12 hours when that is longer. Private audit rows, drafts, chat titles and the calendar (meeting titles are the principal's own) are read only in the `principal` scope — `gather_live_signals` drops the calendar whenever `include_private` is false, whatever the caller passes, so the shared `company` header never quotes it. The calendar read is the principal's calendar as the Executive reads it merged with their own calendar when Read my calendar is on (`top_three.read_todays_calendar`). The calendar is never fetched on the request: `live_signals.refresh_calendar` caches one read per 15 minutes (the scheduler tick refreshes it) and the header quotes the cache. Every quoted field is collapsed to one line and cut, and the blocks and the prompt both say the text is data, never instructions — inbound mail is attacker-controlled. With live blocks present the context also ages each proposal (`raised 2d ago`, whole days), names each at-risk department's slipping goals (`attention_goals`) and adds an **EXTERNAL SIGNALS** block (monitoring alerts from the last 24 h, never enough on their own to break the quiet line); the rhythm runs (`today.RHYTHM_WORKFLOWS`: the morning brief, end-of-day digest, reflection and weekly review) are dropped from the activity it reasons over. The prompts (`BRIEFING_NARRATIVE_SYSTEM` and its solo variant, `NARRATIVE_PROMPT_VERSION` 6) lead with what is live and give a days-old item at most one bullet. Anything live breaks the quiet line; the NOW line and window move at most once an hour, so the key moves hourly on time alone plus whenever something new lands; the calendar is placed at the real time (a meeting that has ended drops out, the one under way is IN PROGRESS), which moves it only when a meeting starts or ends. An address that belongs to someone on the roster (or, in the principal scope, one of the principal's contacts) reads `Name (address)` in these lines (`live_signals._named`), so the header calls people by name instead of making one up from the address.\n\n **Who reads it.** Every brief surface (this header, the morning brief, the end-of-day digest) is written for one person, fixed in code by `briefing.reader`: the principal on the principal scope, the teammate on a `person:<id>` scope, and the principal on `company` too (that scope has no signed-in caller and uses the principal's prompt, built from shared rows only). `render_briefing_context(reader=…)` masks that person's full name and email addresses everywhere in the context to \"the reader\" (their own chat and mail, the Executive's replies to them, chat titles, the activity rail) and heads it with a **THE READER** line naming them; every brief prompt carries `READER_NAME_RULE`: write \"you\", never the reader's name, \"the reader\" or \"the principal\" (anyone else by name), and \"I\" / \"me\" / \"my\" for the Executive. A draft that still slips (`reader.slips`), or reports the reader's own chats and asks back to them (`narrative.own_echoes`: \"you asked me\", \"your chat\", \"a chat with me\", \"the 13:26 … chat\", which `OWN_MESSAGES_RULE` forbids), is sent back once to be rewritten, and what is left of the reader slips after that is fixed in code (`reader.fix_slips`: the reader → you/your, \"the principal\" → the owner's name on a teammate's brief, the Executive → I/me/my).\n\n **Fresh without a reload.** The daily floor in the key and the PERIOD line are the principal's **local** date (`narrative_cache.local_today`), not UTC's, and a row written on an earlier local day is not served as today's. Nor is a stale row more than two hours old, or (the principal's header) one written before a meeting on the cached calendar started or ended (`today._header_outdated`): with the rewrite failing, a 1:45 PM header still called a 2:30 PM call next at 4:40 PM. Regenerations are serialized per scope; a trigger that finds one running marks the scope pending and the running pass goes round once more (it built its context before that trigger's news landed), and after a failed pass (model error, the 33 s timeout: 25 s for the draft and 8 s for a rewrite, empty text) no view or tick starts another for 5 minutes and `narrative_stale` reads false, so the page drops its placeholder instead of spending a model call per view. They log `today: narrative served scope=… age_s=… stale=…` and `today: narrative regenerated scope=… ms=…`, and no longer need a page view: every `BRIEFING_NARRATIVE_REFRESH_MINUTES` (10) between `BRIEFING_NARRATIVE_REFRESH_START_HOUR` and `_END_HOUR` (06–22 local) the scheduler runs `today.refresh_principal_narrative`, which refreshes the calendar cache and rewrites the principal's header only when its key moved (see Scheduler). The Briefing re-polls `/today` at 4, 10 and 20 s while `narrative_stale` is true, re-pulls it when the tab comes back (at most once a minute) and every 5 minutes while visible, shows \"Checked 2:20 PM\" beside the heading (`narrative_checked_at`: the time of the request when nothing the header reads has moved since it was written, so a quiet header doesn't read as stuck at the hour it was written; \"Updated …\" from `narrative_generated_at` otherwise), and shows \"Catching up on today…\" while the first header of the day is written (`lib/narrativeFreshness.ts`, tested by `npm test`).\n\n In **solo mode** (one person using Open Executive for themselves) the header speaks to the principal, whatever their role: a solo prompt over a context that lists goals at risk by *area* and has no \"people waiting on you\" block, and the quiet check ignores who is awaiting. The cache key carries the mode for solo only, so solo and team never share a cached narrative while every team key stays exactly what it was — no team cache is invalidated. The response shape does not change. For the principal's own view the solo context also carries a **DUE THIS WEEK** block — the principal's open loops that are overdue or due within 7 days (`today._with_due_soon` → `open_loops.principal_due_soon`, labelled OVERDUE / due today / due <weekday>) — which counts as needing attention in the quiet check and moves the cache key when an item is added, closed or falls due; a teammate's scoped view and team mode never get it. The header never gets the morning brief's *top three today* block — that is the DM brief's (see Workflows); the page shows the same top three in a card of its own (see *Solo focus cards* below). It does get the rest of today's calendar through the live blocks above, from the cached read.\n- **`in_flight`** / **`awaiting`** — upcoming Executive commitments and people we are waiting on.\n- **`handled_overnight`** — the autonomous moves the Executive *completed* since the last delivered morning brief: the alert review's (routed, nudged, escalated, drafted, merged, closed) plus the research watch policy's (`watching` — a watch added on its own because it was grounded in company data; `stopped_watching` — a research watch auto-disabled as noisy or dead; no alert id, re-enable from `/watchlist`). A `changed` verdict (the review rewrote an open alert's headline / body / severity) is deliberately **not** here: the alert is still open in \"Needs you\" and its card carries the note, so the brief reports it under \"what changed\" (a REWRITTEN block) rather than as done. Each row is structured, not just a sentence: `kind`, the audit `summary` (nudge bookkeeping marker stripped), `at`, `alert_id`, `event_type` (for a pre-filtered `/audit` deep link), `headline` (the alert's headline at move time; a watch's slug), `target` (person name for routed / nudged, survivor headline for merged, new severity for escalated, draft title, workflow name), `detail` (the cited evidence or the watch policy's reason), `outcome` (`resolved` | `dismissed` for a close, `proposed` for a route that went through the authority gate), `evidence_ref` (S1 / R2 / A3), `superseded_by_alert_id`, and `status` — the alert's lifecycle state **now** (`open` = live in the queue per `lifecycle.is_live` | `resolved` | `dismissed` | `expired` | `merged` | `acked` | `inactive` for snoozed / past-TTL rows), looked up per row so a close the principal already undid renders as reopened instead of offering a second Undo, and a \"still open\" jump link only appears when there is a card to land on. Audit rows private to the principal (say, one naming their contact) are in this list only on the principal's own `/today`: `brief_state.handled_since` leaves them out unless asked, and the written briefs never ask, since a brief can be read by others. The Pulse heatmap's per-day counts (`GET /today/activity/daily`) likewise leave out a private decision or private alert, as the activity rail does. The morning brief also carries a one-line count of research watch suggestions waiting on `/watchlist`.\n\n**From your chats.** `briefing.brief_requests` holds what the principal asked of their brief in conversation: `leave_out` lines from `leave_out_of_brief` (\"take the Halcyon renewal out of my brief\", kept 14 days) and `raise` lines the conversation review could not fix itself (`raise_in_brief`, kept 2 days), at most 20 live. A line is at most 12 words (leave out) or 30 (raise), with no link, handle, markup, identifier or talk of instructions, and only lines written under the principal's own id render. `render_briefing_context(brief_requests=True)` adds the raise lines before the quiet-day check, so they are raised even on a quiet day, and the leave-out list as the very last block; both sit inside the rendered string the /today header hashes. A teammate's brief or header passes `False`: they are the principal's own words.\n\n**Standing facts.** `render_briefing_context` appends the standing facts (`memory.facts`: corrections kept from chat, a teammate's marked `(per <name>)`) as its last block, after the quiet-day check, so a fact never makes a quiet day look busy. Every brief prompt (this header, the teammate header, the morning brief and the end-of-day digest) carries `narrative.STANDING_FACTS_RULE`: use the facts quietly, never mention one or that it was saved, and leave an item a fact settles out without saying it was dropped. A fact settles only what it plainly says. Without it, a fact saved in chat came back as the header's top point, stretched to an item it never named. The morning brief also carries **TEAMMATE CORRECTIONS SINCE LAST BRIEF** (`facts.render_teammate_changes(since)`: each teammate fact recorded in the window that is in use now, plus — only when the brief is the principal's own private one (`_private_ok`), which then keeps the run out of the shared history — those waiting for their approval, since other teammates may run the brief and never see a proposal that is not theirs) before the quiet check — it is news, the principal's only FYI of it — and in the brief's fingerprint (`build_brief_fingerprint(teammate_changes=)`), so a correction alone un-suppresses an otherwise unchanged brief. Every other caller passes none, so its context is unchanged. The /today header hashes that rendered string as its cache key, so a new or retired fact marks the header stale and it is rewritten with the correction. The morning brief (standalone) and the teammate-scoped header get the same block. On the scheduler's delivery to the owner alone, with their Always in the loop switch on, `render_briefing_context(owner_notes=)` also carries FROM YOUR NOTES — DUE SOON (their own notes of what they promised or asked, overdue to a week ahead; `memory.history_brief`), which counts against a quiet day, enters the fingerprint and marks the run private; both standalone prompts turn it into a **From your notes** section. The /today header never gets it. **The first week.** For seven days from the principal's People row (`briefing.first_week`), `render_briefing_context(getting_started=)` carries a GETTING STARTED block right after the live blocks: the install's goal rows (department, key result, target, period) or, while there are none (setup saves no goal rows, so this is a fresh install's usual case), this year's priorities and north star from the saved profile (`strategic_priorities`, up to five, keys `priority:<text>`), departments with no `head_person_id`, and, on the scheduler's delivery to the principal alone with Act as me and Draft replies to my inbox both on and the mailbox connected (the inbox watcher's consent), up to five people who wrote to their own mailbox in the last 48 hours as sender and subject only (`inbox_message_ids` + headers of `get_message`, bulk and automated mail skipped; the same \"where, never what\" rule as `delegation.mail_reads`) and, with Act as me and Read my calendar on, up to eight of today's events on their own calendar as time and title (declined ones left out). It counts against a quiet day, enters the fingerprint (`getting_started=` keys, no dates; a meeting's key is its event id) and, with the inbox or calendar part, marks the run private. Both standalone prompts open with a **Getting started** section and take the Top call from it (`GETTING_STARTED_RULE`). The /today header does not get the block: in the first week it is the same header as any other day. Home's top slot is instead the **first-week card**, built in code with no model call (`first_week.first_week_card`): `needs_goal` while no goal row exists (fixed ask \"Give me one goal with a date, and I'll track it every day.\" and a **Set a goal** button to `/goals?add=1`, which opens the add form), up to two findings from the latest finished team `executive_research` run (the run history keeps only the artifact, so `executive_research.parse_artifact_findings` reads back its \"Findings reviewed\" lines; most severe and most certain first, headline plus the summary's first sentence) with a line linking `/watchlist`, and `brief_tomorrow` on the setup day until the first morning brief is delivered. No goal still to set and no findings means no card. `GET /today` sets `first_week_card` and `first_week` (whether there is a card) for the principal only; while there is one the Briefing hides the \"Quiet day\" banner and an all-zero summary line reads \"Your first week. Start below.\" The last setup screen (`OnboardDone`) offers one first question built from the saved priorities (`firstQuestion`) and hands it to Home through session storage (`oe.onboard.firstQuestion`, never the URL), which asks it once. A teammate's scoped header never gets it. The alert review's `render_batch` puts the same block ahead of the alerts (read once per pass), so a note, rewrite or routed DM never repeats a figure the principal already corrected.\n\n**When a brief isn't sent.** Above the Briefing, the owner sees a one-line notice when their latest morning brief, end-of-day digest or (in solo mode) weekly review wasn't sent — \"Your morning brief wasn't sent: nothing is set up to send it to you\" — with the day, what fixes it, a link to read the brief on the Artifacts page (left out when the brief couldn't be written at all) and one to Setup status. It comes from `GET /today/brief-delivery` (the scheduler records each run's outcome), shows nothing while briefs go out or while the scheduler is off, and clears once the cause is fixed. When the Executive's mail connection wasn't running (the MCP gateway failed to start and is retrying), the notice says that instead of blaming the owner's setup; a send that failed on every channel names what each channel answered, from the recorded `detail`, with addresses left out. Teammates never see it.\n\n**Replies waiting.** With Act as me's **Draft replies to my inbox** on, the top of the Briefing's left column lists the replies the Executive drafted in the owner's own Gmail for mail that needs them (`RepliesWaiting`, from `GET /delegation/replies` — see Act as Me). They belong to the owner alone: the route answers only the person who can have Act as me, the decisions behind the cards (`delegation_reply`) are principal-only and carry `private: true`, so `/today/activity` and the heatmap leave them out, and none is ever an alert, so nothing of them reaches `GET /today`, the header or the briefs. Each card shows who wrote and who they are to the owner, whether their address was verified, the subject, what they wrote (as plain text), the draft, **Decide before sending** (its open questions) and its warnings, with **Send**, **Edit in Gmail** (the thread in their Gmail) and **Dismiss** (which deletes the draft unless they edited it). **Send** asks first, naming who the reply goes to, then sends the draft exactly as it is in Gmail (`POST /decisions/{id}/approve`); when its recipients changed in Gmail or a newer message arrived, the backend's 409 `confirm` becomes a second question naming them. The card hides itself when nothing is waiting.\n\n**Solo focus cards.** `GET /today/top-three` and `GET /today/weekly-review` feed two solo-only cards, so a principal who only uses the web app — no chat app, no Google Workspace — sees today's top three and the weekly review instead of finding them only in the Workflows run history. Both answer only in solo mode (`effective_workspace_mode`) and only to the principal, by the stricter rule for starting a principal-only run (`workflows._caller_is_the_principal`: the caller's own email on a principal entry that is not archived, or no `x-caller-email` at all — never \"nobody is principal yet\"); a teammate, any other signed-in caller and team mode get null. `top-three` hands `open_loops.principal_due_soon()` to `briefing.top_three.build_top_three` — the morning brief's own inputs and code, so the items, their order and their free slots are the brief's — and returns `{items: [{key, kind, text, why, slot}]}`: `slot` is the free block (\"10:00–11:00\", the user's zone), \"\" when none is left, or null when no calendar was read (none connected, a failure or the 4 s timeout, a weekend); `items` is empty when there is nothing to pick. It is a route of its own, never part of `GET /today`, so the Briefing never waits on the calendar. `weekly-review` returns the latest `weekly_review` run with status `done` (`persistence.list_runs(..., status=\"done\", limit=1)`, newest `updated_at` first; failed and running runs never count) as `{run_id, completed_at, period, top_three, excerpt}`: `weekly_review.summarize_review` reads the artifact's title line and its last *Next week's top 3* section back as plain text, and `excerpt` stands in when that list is empty (the section's own note, else the review's first lines). Null when no review has completed or the run store cannot be read.\n\nThe route resolves the caller from `x-caller-email`, serves the viewer's cached narrative and, when its key moved, rewrites it in a `BackgroundTask` so the request never blocks on an LLM call (the page re-polls while `narrative_stale` is true). `GET /today/activity` returns the recent self-initiated action rail — merged from fired scheduled actions (DMs, follow-ups, nudges, cadences), logged decisions, saved advice, completed workflow runs (briefings/check-ins/research), kicked-off initiatives, resolved gated decisions, and raised alerts, so it reflects all of the Executive's activity rather than just dispatched messages. A brief or digest delivered to its reader (`scheduler.runner._deliver_to_principal`) records its send as kind `brief_delivery` (`schedule_tools.recorded_as`): the outbound guard still counts it, but the rail and the heatmap leave it out, because every later brief reads the rail and used to repeat its own last top call as work done. A completed run is named in plain words, never by its log title (`workflows/run_outcome.py`: \"Researched your market\", \"Checked in with Sales\", or the name it was started with, less any date or how-it-started note), and carries `detail`, one line on what came of it read from its stored artifact (research: updates looked at, messages sent, alerts raised, things now watched; a check-in: actions proposed; the weekly review: next week's top item; other runs: the first sentence; none for briefs and the reflection), and `artifact_id` (`run:<id>`) when it kept a write-up (never for the reflection, which reads the principal's live alerts), so Pulse's Done for you and All activity link **Read it** to `/artifacts/run:<id>`. The Pulse page (`/memories`) polls it (limit 100) every ~20s so new events stream into the 'Recent activity' card, which scrolls internally at a fixed height instead of growing the page. The `morning_brief` workflow calls `_build_today()` directly to build the standalone DM (via a different, enumerated prompt; solo mode has its own, with goals at risk by area and no waiting-on section). `GET /morning-brief` is a deprecated alias.\n\n**Solo mode in the UI.** The response is the same in both modes; the briefing reads the workspace mode from the app-wide `WorkspaceProvider` (which reads team while loading or on error, so a team install never flashes solo) and, in solo, drops the team surfaces: the Departments card, the People card, the \"Across the team\" lane (every action proposal is the one user's, so all of them land in \"Needs you\"), the people-awaiting, people-overdue and departments-at-risk status pills, and the quiet-day \"Set up a check-in\" link. A \"N goals at risk\" pill (at-risk plus off-track goals, from `departments`) links to `/goals` instead, so the strip never reads \"All clear\" over a goal that is slipping. In the Departments card's place, **Your projects** lists the initiatives with status `active` (`GET /memories/initiatives`): **Done** marks one `completed` through `PATCH /memories/initiatives/{id}` (only `completed` takes an initiative out of the Executive's active context), and **Drop** deletes it through `DELETE /memories/initiatives/{id}` after a confirm. Under **Needs you**, a **Due soon** card lists the principal's open loops that are overdue or due within 7 days — their dated commitments and what others asked of them — read from `GET /people/{id}/open-loops` for the principal (the oldest principal in `people`, the backend's rule), labelled by `lib/dueSoon.ts` (tested by `npm test`: \"Overdue since Sep 23\" / \"Due today\" / \"Due Mon, Sep 28\", with a count of anything due later); **Done** closes one through `POST /open-loops/{id}/close`, which also stops the nudge engine chasing it. Above it, **Top three today** numbers the morning brief's three (`GET /today/top-three`) with each one's reason and, when a calendar was read, its free slot (or \"No free time left today\"); at the top of the right-hand column, **This week's review** (`GET /today/weekly-review`) shows the period, when it ran, next week's top three (or the excerpt) and a *Read the review* link to its run page (`/jobs/runs/{id}`). Each card fetches on its own once the Briefing has loaded, so a slow calendar never holds the page up, and renders nothing when the API returns null or an empty list. A commitment in the top three reads as the owner's own (\"Send the proposal\") through `lib/dueSoon.ts`'s `loopText`, as in Due soon; the cards' wording lives in `lib/rhythmCards.ts` (tested by `npm test`). The Pulse page hides its \"Department check-ins\" and \"Awaiting people\" blocks in solo, and its header shows active projects in place of the department check-in count. Team rendering is unchanged.\n\n**Your month (`GET /today/value`).** The owner's own tally of what the Executive did for them, `briefing.value_summary.summarize(period, offset)`: the calendar `month` or `week` (Monday first) in the user's zone, `offset` periods back (0–24), each line beside the period before. Every number is a `COUNT(*)` of rows that prove it happened, never a model's: messages sent for the owner (the DM handlers' own `kind=outbound` sent rows to anyone but the owner, plus Gmail / Outlook send-tool calls that didn't come back with an error, so mail sent from a chat turn counts), replies drafted and sent from the owner's inbox (their Act as me rows), meetings booked (calendar create calls), briefs delivered (the scheduler's `delivered` row), reports (finished team workflow runs, minus the daily rhythm runs and any run a teammate started for themselves, which stays theirs alone; the latest ten listed with links), follow-ups and nudges sent, tasks tracked and closed as done, proposals decided, alerts flagged and requests answered (`chat_turn` out rows). No \"hours saved\" and no cost line: nothing recorded supports the first, and cost next to what the owner got reads as a bill; it has `GET /audit/usage`. The owner's alone (403 for anyone else): it counts rows private to the owner, never a row private to another member. Pulse shows it as the top line of the overview's **Done for you** panel (\"October 2026: 42 messages sent, 6 reports, 3 meetings booked\") and a focused screen, `/memories?tab=value`, with a month / week switch and previous / next. On the first weekday of each month, in daytime (09:00–18:00 local), a scheduler tick hook sends the owner last month's lines and a link (`value_summary.maybe_send_monthly`, claimed once per month under `briefing_narrative` scope `value_summary:YYYY-MM`), in solo and team mode alike; nothing is sent for an empty month. Off with `VALUE_SUMMARY_MONTHLY_ENABLED=false`.\n\n## Alert lifecycle & the Executive review\n\nAlerts used to be write-once: raised, then never looked at again, so the \"Needs you\" queue grew without bound and the briefs re-listed it daily. Four things now keep it live and true:\n\n- **Time-to-live** (`openexecutive.alerts.lifecycle`). Action items expire after `ALERT_TTL_DAYS_ACTION` (14 d), unrouted low/medium monitoring signals after `ALERT_TTL_DAYS_MONITORING` (3 d). Every surface reads `list_live_alerts` (the same predicate the scheduler's 15-minute sweep persists as status `expired`), so `/today` is right even before the sweep runs. Artifacts and decision-backed alerts are exempt. `POST /alerts/{id}/reopen` is the Undo. **Snooze** (a card's ⋯: later today, tomorrow 9:00, Monday 9:00, in the viewer's clock; `POST /alerts/{id}/snooze`) hides a card until `snoozed_until`, with an Undo; the TTL anchor is the latest of `created_at`, `last_seen_at` and `snoozed_until`, so a snoozed card comes back rather than expiring unseen.\n- **Coalescing** (`alerts.pipeline` + `store.coalesce_alert`). A repeat of an open alert with the same `(source, dedup_key)` updates that row — `occurrence_count`, `last_seen_at`, severity max — instead of stacking a second card, and only re-pings when severity rose to high/urgent. Monitoring alerts carry a stable `watch:<slug>` key, so one watch means one card.\n- **Collection tags** (`alerts.pipeline`). A triaged alert never carries a `collection:<name>` tag: the pipeline strips them before inserting. Only an installed extension's own code files a document into its collection (`orchestrator.extensions`), so injected text can't make a card that the extension would treat as its own.\n- **The review** (`openexecutive.alerts.review`, heartbeat `alert_review_scan`, every 6 h and right before the morning brief). For each open alert the Executive sees what changed since it was raised — newer signals from the same watch, related alerts, activity since, the roster with SLAs (team members only — an alert routed to a contact never puts them in the slice, so they are never routed to, nudged or chased; a private card is never reviewed at all, nor used as evidence for another), department authority — and returns a verdict (relevant / changed / resolved / stale) plus a recommended move. Deterministic policy then acts: **route** (assign + DM the owner; `propose_via_alert` for propose-only departments), **nudge**, **escalate** (severity + `due_at` + DM the principal only), **draft** (`draft_artifact`), **suggest a workflow** (a link, never a run), **merge** (`superseded_by_alert_id`), or **resolve** — only on high confidence citing a server-minted evidence ref (a newer signal, a related alert, an activity item shown for that alert); free text never closes a card, and anything weaker is annotated `likely_stale`, demoted 30 ranking points, and left for one click. Everything that came from outside is rendered as inert data inside the review prompt, so an injected email body cannot steer the batch. Board / comp / legal matters only ever go to a scope-holder or the principal and keep their text. Route and escalate are idempotent across passes, every DM carries an \"[Alert review] Re: …\" header, outbound moves are capped per pass, passes are single-flight, `ALERT_REVIEW_ENABLED=false` stops every caller, every move is audited with its evidence and prior state, and a distinct `resolved` status keeps Executive closes separate from `ack` (user approved). A review DM is proactive outreach, so the recipient's notification settings apply: one held for their quiet hours or brief counts as a route made but not as a nudge toward the cap (and no second nudge is held while one waits), and one about an alert whose severity is (or becomes) `urgent` is marked urgent (`notifications.urgent_send`) and gets through when they let urgent things through.\n- **Grounded text** (`openexecutive.briefing.grounding`). Nobody reads an alert's text before it is dispatched, so what the model wrote onto it must be supported by what it read. After triage (`alerts.pipeline._ground_decision`, before coalescing or inserting), a headline naming a person or figure the event does not hold — sources are the event's subject, sender, title and body, the initiatives triage was shown and the company profile — is replaced by the event's own subject, such body sentences are dropped (all of them → the event body cut to 280 chars); both fallbacks are raw event text, so they are made inert first — links masked, Markdown and Slack `<…>` syntax and @-mentions stripped — because a broadcast posts them as written, and such a suggested action is dropped. A review `changed` rewrite is checked against the alert's own text and the evidence it was reviewed with (signals, related alerts, activity, the roster slice), plus the standing facts the batch was shown, so a rewrite that corrects a card to one of the principal's corrections is grounded; an ungrounded rewrite keeps the old text, still applies a severity change, and audits `text_ungrounded`. A name counts as grounded only when one source line holds all of it; a figure only when a source number matches it within the precision it is written with. Each finding writes a `grounding` audit row; `GROUNDING_CHECKS=report` records without changing anything.\n\nOn the page, cards read as decisions: the one-line \"what changed since you last looked\" (`review_note`) leads, the recommended move is the primary control (Nudge <owner> → chat; Run <workflow> → `/jobs/<name>`), with chips for age, seen ×N, why-now / due, folded-in and draft-ready, a \"Reviewed <ago>\" footer, and an amber Likely-stale treatment with one-click Dismiss. \"Needs you\" shows *Start here* + 8 cards + \"Show N more\", a \"Dismiss N older than 7 days\" footer (explicit ids to `POST /alerts/bulk-ack` — never a server-side age sweep, which would hit teammates' routed items), and \"Re-check relevance\" (`POST /alerts/review`). The handled rail (anchor of the \"Executive handled N overnight\" pill) is deliberately one sentence by default: a first-person heading built from counts only — \"Since your last brief: N off your plate (closes still standing, and merges whose survivor is not itself listed; a merge into a listed survivor counts on that survivor's row), N in others' hands (routed / nudged), N waiting on you (escalated)\", plus \"N drafts ready\", \"N workflows suggested\", \"N watch changes\", \"N other moves\" (a kind the UI does not know) and \"N back on your plate\" (a close that is open again) when present — with the rows behind a \"details\" disclosure, and nothing rendered at all when the grouped rows are empty. The pure logic (grouping, headline, links) lives in `packages/ui/src/lib/handled.ts` and is covered by `npm test`. Expanded, it shows one first-person row per alert (\"Resolved *X* — evidence\", \"Dismissed *X* as stale — evidence\", \"Handed *X* to Dana Kim\" / \"Proposed *X* to Dana Kim (awaiting their approval)\", \"Chased Dana Kim on *X*\", \"Raised *X* to high\", \"Drafted *T* from *X*\", \"Folded *X* into *Y*\", \"Started watching *slug*\"), escalations first; rows sharing an alert collapse to the newest move with the others as an \"also …\" trailer — a close always keeps the visible slot (it carries Undo), otherwise an escalation beats routed / nudged / drafted; a merge whose survivor is listed becomes \"N duplicates folded in\" on the survivor. Every row links its `evidence_ref` (or \"evidence\") to `/audit?event_type=…&q=…` (the audit page pre-fills those filters from the query string), a still-open row jumps to its card (`#alert-<id>`), drafted rows link `/artifacts`, watch rows `/watchlist`. Undo is offered only while the close still stands (`status` not `open`); a reverted close shows \"Reopened\". Dismissing a watch-sourced alert lowers that watch's `trust_score` (which discounts ranking and is shown to the review as evidence); the ack body may carry `mute_topic`. Acknowledging or resolving an alert — including the review closing it itself — marks the review's DMs about it `acted` in the Attunement outcome ledger, for the person it is routed to and the principal only; dismissing it, finding it stale or letting it expire voids them (counted neither way). Review DMs are tagged `alert_review` with `alert:<id>`.\n\n## Multi-client practice section\n\nIn multi-client practice mode (2+ client slots — see the Client Companies section), the response gains an additive `practice_clients` list: rollup cards for the **parked** clients (overdue follow-ups, awaiting replies, unread alerts, onboarding due soon, renewal countdowns), each stamped with the save point its data reflects. Single-company installs always receive an empty list and the UI renders nothing.",
"mermaid": "flowchart TD\n REQ[\"GET /today\"]\n BUILD[\"_build_today()\"]\n DEPTS[\"departments<br/>(per-dept goal health)\"]\n ROSTER[\"people<br/>(attention-ranked roster)\"]\n PROPS[\"proposals<br/>(unread alerts, routed)\"]\n INFLIGHT[\"in_flight<br/>(pending follow-ups / nudges)\"]\n AWAIT[\"awaiting<br/>(replies we await)\"]\n NARR[\"viewer-scoped narrative (BackgroundTask)\"]\n MB[\"morning_brief workflow\"]\n TOP3[\"GET /today/top-three<br/>(solo, principal only)\"]\n PICK[\"build_top_three()<br/>(calendar read, 4 s cap)\"]\n WREV[\"GET /today/weekly-review<br/>(solo, principal only)\"]\n RUNS[\"workflow_runs<br/>(latest done weekly_review)\"]\n LIVE[\"live_signals<br/>(inbound / held replies / chats,<br/>cached calendar)\"]\n TICK[\"scheduler tick<br/>(every 10 min, 06–22 local)\"]\n CACHE[\"briefing_narrative<br/>(principal / company / person:id)\"]\n REQ --> BUILD\n BUILD --> DEPTS\n BUILD --> ROSTER\n BUILD --> PROPS\n BUILD --> INFLIGHT\n BUILD --> AWAIT\n REQ -->|\"resolve caller, attach\"| NARR\n LIVE --> NARR\n TICK -->|\"refresh_principal_narrative\"| NARR\n NARR --> CACHE\n MB -->|\"since last brief\"| LIVE\n MB -->|\"calls directly for standalone DM\"| BUILD\n MB -->|\"same pick for the DM\"| PICK\n TOP3 --> PICK\n WREV --> RUNS\n class REQ entry\n class BUILD compute\n class DEPTS storage\n class ROSTER storage\n class PROPS storage\n class INFLIGHT storage\n class AWAIT storage\n class NARR compute\n class MB compute\n class TOP3 entry\n class PICK compute\n class WREV entry\n class RUNS storage\n class LIVE compute\n class TICK entry\n class CACHE storage",
- "generated_at": "2026-10-26T19:09:12Z"
+ "generated_at": "2026-10-27T18:30:00Z"
}
diff --git a/packages/core/openexecutive/briefing/header_context.py b/packages/core/openexecutive/briefing/header_context.py
index 2c24ef00..39d7147c 100644
--- a/packages/core/openexecutive/briefing/header_context.py
+++ b/packages/core/openexecutive/briefing/header_context.py
@@ -71,6 +71,10 @@ class HeaderContext:
# Tags of MOVED TODAY lines only (not the calendar): with none, nothing
# moved and no model call is needed.
moved: frozenset[str] = field(default_factory=frozenset)
+ # Tag → the item a line is about, for the lines Home can open from a
+ # point: ``{"kind": "mail", "message_id", "thread_id"?, "decision_id"?}``
+ # or ``{"kind": "alert", "alert_id"}``. Never part of the text.
+ sources: dict[str, dict[str, Any]] = field(default_factory=dict)
def _one_line(value: Any, limit: int = 160) -> str:
@@ -133,6 +137,7 @@ def render_header_context(
solo = mode == "solo"
moved = _Tagger()
still_open: list[str] = []
+ sources: dict[str, dict[str, Any]] = {}
if live is not None:
for line in live.inbound:
@@ -146,8 +151,11 @@ def render_header_context(
moved.add(f"{n} draft{'s' if n != 1 else ''} in the reader's own mailbox, waiting for them to send")
for line in live.waiting:
moved.add(f"The reader's own email, waiting on an answer: {_one_line(line, 300)}")
- for line in live.inbox:
- moved.add(f"Email to the reader's own inbox: {_one_line(line, 400)}")
+ refs = list(live.inbox_refs)
+ for i, line in enumerate(live.inbox):
+ tag = moved.add(f"Email to the reader's own inbox: {_one_line(line, 400)}")
+ if i < len(refs) and refs[i].get("message_id"):
+ sources[tag] = dict(refs[i])
for line in live.met_today:
moved.add(f"Meeting that ended today: {_one_line(line, 200)}")
@@ -158,9 +166,13 @@ def render_header_context(
line = f"New for the reader to decide ({age}): {headline}"
if p.get("why_now"):
line += f" (why now: {_one_line(p['why_now'], 100)})"
- moved.add(line)
+ _cite_alert(sources, moved.add(line), p)
elif _local_day(p.get("last_seen_at"), tz) == today and int(p.get("occurrence_count") or 1) > 1:
- moved.add(f"Came up again today ({age}, {p.get('occurrence_count')} times so far): {headline}")
+ _cite_alert(
+ sources,
+ moved.add(f"Came up again today ({age}, {p.get('occurrence_count')} times so far): {headline}"),
+ p,
+ )
else:
still_open.append(f"decision waiting ({age}): {headline}")
@@ -276,9 +288,34 @@ def render_header_context(
text="\n".join(head_lines) + "\n" + text_body,
tags=frozenset(moved.tags),
moved=frozenset(moved_tags),
+ sources=sources,
)
+def _cite_alert(sources: dict[str, dict[str, Any]], tag: str, proposal: dict[str, Any]) -> None:
+ alert_id = proposal.get("alert_id")
+ if isinstance(alert_id, int) and not isinstance(alert_id, bool):
+ sources[tag] = {"kind": "alert", "alert_id": alert_id}
+
+
+def point_sources(
+ draft: str, sources: dict[str, dict[str, Any]]
+) -> list[tuple[str, dict[str, Any]]]:
+ """Each bullet of ``draft`` (as ``point_citations`` reads it) with the
+ item its first cited tag that has one is about. A bullet citing none of
+ ``sources`` is left out."""
+ out: list[tuple[str, dict[str, Any]]] = []
+ for point, cited in point_citations(draft):
+ tag = next((t for t in sorted(cited, key=_tag_order) if t in sources), None)
+ if tag is not None:
+ out.append((point, sources[tag]))
+ return out
+
+
+def _tag_order(tag: str) -> int:
+ return int(tag[1:]) if tag[1:].isdigit() else 0
+
+
def tags_in(context: str) -> frozenset[str]:
"""The tags a rendered context gives its MOVED TODAY and COMING UP TODAY
lines, read only inside those two blocks (each block runs to the next
@@ -390,6 +427,7 @@ __all__ = [
"keep_cited_points",
"needs_you_tags",
"point_citations",
+ "point_sources",
"render_header_context",
"tags_in",
]
diff --git a/packages/core/openexecutive/briefing/live_signals.py b/packages/core/openexecutive/briefing/live_signals.py
index 90a2ab29..95acf4c1 100644
--- a/packages/core/openexecutive/briefing/live_signals.py
+++ b/packages/core/openexecutive/briefing/live_signals.py
@@ -235,6 +235,9 @@ class LiveSignals:
inbox: tuple[str, ...] = ()
inbox_others: tuple[str, ...] = ()
inbox_others_total: int = 0
+ # Which email each ``inbox`` line is, in the same order, so Home can open
+ # it from the point that cites it. Never rendered or keyed.
+ inbox_refs: tuple[dict[str, Any], ...] = ()
# Stable identities for the brief's "unchanged" fingerprint — no times.
# The reader's own messages are left out: chatting with the Executive
# is not a reason to send a brief.
@@ -647,6 +650,8 @@ class OwnInbox:
lines: tuple[str, ...] = ()
others: tuple[str, ...] = ()
others_total: int = 0
+ # Per line: the email's ids and its open reply card, if any.
+ refs: tuple[dict[str, Any], ...] = ()
def own_inbox(since: datetime, tz: tzinfo, now: datetime | None = None) -> OwnInbox:
@@ -688,6 +693,7 @@ def own_inbox(since: datetime, tz: tzinfo, now: datetime | None = None) -> OwnIn
picked.sort(key=lambda d: d["_at"], reverse=True)
done = watcher.outcomes(principal.id, [str(d["message_id"]) for d in picked])
lines: list[str] = []
+ refs: list[dict[str, Any]] = []
others: list[str] = []
others_total = 0
for d in picked:
@@ -724,7 +730,18 @@ def own_inbox(since: datetime, tz: tzinfo, now: datetime | None = None) -> OwnIn
what = ""
line = f"[{at}] from {who}: \"{subject}\""
lines.append(f"{line} — {what}" if what else line)
- return OwnInbox(tuple(lines), tuple(others), others_total)
+ refs.append(_mail_ref(d))
+ return OwnInbox(tuple(lines), tuple(others), others_total, tuple(refs))
+
+
+def _mail_ref(d: dict[str, Any]) -> dict[str, Any]:
+ """What Home needs to open one email from a Right now point."""
+ ref: dict[str, Any] = {"kind": "mail", "message_id": str(d.get("message_id") or "")}
+ if d.get("thread_id"):
+ ref["thread_id"] = str(d["thread_id"])
+ if isinstance(d.get("card_id"), int):
+ ref["decision_id"] = d["card_id"]
+ return ref
def _waiting_lines(items: list[Any], now: datetime, tz: tzinfo) -> list[str]:
@@ -865,6 +882,7 @@ def gather_live_signals(
inbox=mail.lines,
inbox_others=mail.others,
inbox_others_total=mail.others_total,
+ inbox_refs=mail.refs,
keys={
"inbound": sorted(inbound_keys),
"stuck": sorted(s.split("] ", 1)[-1] for s in stuck),
diff --git a/packages/core/openexecutive/briefing/right_now.py b/packages/core/openexecutive/briefing/right_now.py
index 863fa6d0..ac4d16f1 100644
--- a/packages/core/openexecutive/briefing/right_now.py
+++ b/packages/core/openexecutive/briefing/right_now.py
@@ -10,6 +10,9 @@ of state that needs, next to the header's own table:
bold subject) first appeared in a written header. Recorded when a header is
written, so a point keeps its time across rewrites that reword it.
- ``briefing_reader_seen``: per scope, when the reader last looked at it.
+- ``briefing_point_source``: per scope and local day, what each point of the
+ latest header is about (an email, a card), so Home can open it. Replaced
+ whole on every write.
``split_narrative`` parses the header's fixed shape (bold opener, bullets, a
``**Move today:**`` line) for the card; text in any other shape comes back as
@@ -17,10 +20,12 @@ the opener alone. Nothing here calls a model.
"""
from __future__ import annotations
+import json
import logging
import re
from dataclasses import dataclass, field
from datetime import UTC, datetime
+from typing import Any
from openexecutive.briefing import narrative_cache
@@ -94,6 +99,17 @@ def initialize_db() -> None:
)
"""
)
+ conn.execute(
+ """
+ CREATE TABLE IF NOT EXISTS briefing_point_source (
+ scope TEXT NOT NULL,
+ day TEXT NOT NULL,
+ point_key TEXT NOT NULL,
+ source TEXT NOT NULL,
+ PRIMARY KEY (scope, day, point_key)
+ )
+ """
+ )
conn.execute(
"""
CREATE TABLE IF NOT EXISTS briefing_reader_seen (
@@ -173,6 +189,48 @@ def point_times(scope: str, day: str) -> dict[str, str]:
return {r["point_key"]: r["first_seen"] for r in rows}
+def record_sources(scope: str, written_at: str, sources: dict[str, dict[str, Any]]) -> None:
+ """Keep what each point of the header written at ``written_at`` is
+ about (``point_key`` → item), in place of the last header's. Never
+ raises."""
+ day = _day_of(written_at)
+ if day is None:
+ return
+ try:
+ initialize_db()
+ with narrative_cache._get_conn() as conn:
+ conn.execute("DELETE FROM briefing_point_source WHERE scope = ?", (scope,))
+ conn.executemany(
+ "INSERT OR REPLACE INTO briefing_point_source (scope, day, point_key, source) VALUES (?, ?, ?, ?)",
+ [(scope, day, k, json.dumps(v, sort_keys=True)) for k, v in sorted(sources.items()) if k],
+ )
+ except Exception:
+ logger.exception("right_now: recording point sources failed (scope=%s)", scope)
+
+
+def point_sources(scope: str, day: str) -> dict[str, dict[str, Any]]:
+ """``point_key`` → what it is about, for one scope's header of ``day``."""
+ try:
+ initialize_db()
+ with narrative_cache._get_conn() as conn:
+ rows = conn.execute(
+ "SELECT point_key, source FROM briefing_point_source WHERE scope = ? AND day = ?",
+ (scope, day),
+ ).fetchall()
+ except Exception:
+ logger.exception("right_now: reading point sources failed (scope=%s)", scope)
+ return {}
+ out: dict[str, dict[str, Any]] = {}
+ for r in rows:
+ try:
+ value = json.loads(r["source"])
+ except ValueError:
+ continue
+ if isinstance(value, dict):
+ out[r["point_key"]] = value
+ return out
+
+
def mark_seen(scope: str, at: str | None = None) -> str | None:
"""Record that the reader looked at Right now; returns the time stored,
or None when it could not be written. Never raises."""
@@ -211,8 +269,10 @@ __all__ = [
"initialize_db",
"mark_seen",
"point_key",
+ "point_sources",
"point_times",
"record_points",
+ "record_sources",
"seen_at",
"split_narrative",
]
diff --git a/packages/core/openexecutive/delegation/inbox.py b/packages/core/openexecutive/delegation/inbox.py
index 9ca6b224..4c769855 100644
--- a/packages/core/openexecutive/delegation/inbox.py
+++ b/packages/core/openexecutive/delegation/inbox.py
@@ -1259,18 +1259,7 @@ async def _consider(
"""Handle one message. True when the rest of the scan should stop.
Once claimed, a message is finished or left for a later scan
(``_retry_later``); a Gmail failure is raised for the scan to back off."""
- from openexecutive.config import get_settings
- from openexecutive.delegation import (
- caps,
- card_drafts,
- drafts,
- handle_it,
- injection_check,
- invites,
- )
- from openexecutive.delegation import disclosure as ai_disclosure
- from openexecutive.delegation.ghostwriter import ComposeError
- from openexecutive.delegation.gmail import DraftSpec, GmailError
+ from openexecutive.delegation import invites
from openexecutive.delegation.inbox_classifier import (
addressing,
classify,
@@ -1278,7 +1267,6 @@ async def _consider(
wants_draft,
)
- email = (person.email or "").strip().lower()
thread = await client.get_thread(thread_id)
message = next((m for m in thread.messages if m.id == message_id), None)
if message is None:
@@ -1327,6 +1315,27 @@ async def _consider(
_set_outcome(person.id, message.id, NOT_NEEDED, reason=reason)
result.not_needed += 1
return False
+ return await _draft_card(
+ person, client, message, thread, relation=relation, known_as=known_as, verdict=verdict,
+ own=own, exec_address=exec_address, now=now, result=result,
+ )
+
+
+async def _draft_card(
+ person: Any, client: Any, message: Any, thread: Any, *, relation: str, known_as: str, verdict: Any,
+ own: set[str], exec_address: str, now: datetime, result: ScanResult, asked: bool = False,
+) -> bool:
+ """Write the reply to ``message`` (already claimed, ``PROCESSING``) and
+ put it on a card, within the day's draft limit; under Handle it for me
+ it may go on its own, unless the person ``asked`` for it (from Home).
+ True when the rest of the scan should stop (the limit)."""
+ from openexecutive.config import get_settings
+ from openexecutive.delegation import caps, card_drafts, drafts, handle_it, injection_check
+ from openexecutive.delegation import disclosure as ai_disclosure
+ from openexecutive.delegation.ghostwriter import ComposeError
+ from openexecutive.delegation.gmail import DraftSpec, GmailError
+
+ email = (person.email or "").strip().lower()
settings = get_settings()
if caps.reserve(person.id, settings.delegation_max_drafts_per_day) is not None:
# Chat took the day's last draft while this one was being read: it
@@ -1353,11 +1362,12 @@ async def _consider(
# Handle it for me: plain code decides whether this reply may go on
# its own. The two model calls above have no tools, so the email's
# text can only change their answers, never this.
- handling = handle_it.get(person.id)
+ # Asked for from Home, it is always a card for them to look at.
+ on_its_own_allowed = handle_it.get(person.id).enabled and not asked
held = handle_it.refusal(
person.id, message, thread, reply, verdict, relation=relation, own=own,
exec_address=exec_address, now=now,
- ) if handling.enabled else "level"
+ ) if on_its_own_allowed else "level"
if held is None and await injection_check.held_back(message, relation=relation):
# One more look, only ever holding back: an email that tries to
# steer an assistant waits for the person.
@@ -1402,7 +1412,7 @@ async def _consider(
try:
decision_id = _create_card(
person, message, thread, reply, draft, relation=known_as, handled_as=relation, verdict=verdict,
- on_its_own=held is None, handle_it_reason=held if handling.enabled else None,
+ on_its_own=held is None, handle_it_reason=held if on_its_own_allowed else None,
kept=None if draft.draft_id else card_drafts.card_fields(spec, key),
)
except Exception as exc:
@@ -1430,13 +1440,104 @@ async def _consider(
"relation": relation,
"kind": verdict.kind,
"flags": reply.flags,
- **({"handle_it": held or "send"} if handling.enabled else {}),
+ **({"handle_it": held or "send"} if on_its_own_allowed else {}),
})
if held is None and decision_id is not None:
await _send_on_its_own(person, client, decision_id, result, now=now)
return False
+# Why Home's Reply couldn't make a card, by code.
+ASK_REFUSALS: dict[str, str] = {
+ "not_found": "That email isn't in your mailbox any more.",
+ "theirs_last": "You wrote last in that conversation.",
+ "backlog_full": "Too many replies are waiting for you. Send or dismiss some first.",
+ "daily_limit": "That's today's limit of replies. Try again tomorrow.",
+ "busy": "I'm already working on that one. Try again in a minute.",
+ "not_now": "I couldn't write that reply just now. Try again in a minute.",
+}
+
+
+def _row_for(person_id: int, message_id: str, db_path: Path | None = None) -> dict[str, Any] | None:
+ conn = _connect(db_path)
+ try:
+ row = conn.execute(
+ f"SELECT outcome, decision_id FROM {INBOX_MESSAGES_TABLE} " # noqa: S608 — constant table name
+ "WHERE person_id = ? AND message_id = ?",
+ (person_id, message_id),
+ ).fetchone()
+ finally:
+ conn.close()
+ return dict(row) if row else None
+
+
+async def draft_on_request(
+ person: Any, thread_id: str, message_id: str, *, gmail: Any = None, now: datetime | None = None
+) -> int | str:
+ """A reply card for one email in ``person``'s own inbox, because they
+ asked for one (Home's Reply), whatever the watcher judged of it. The
+ open card already on its conversation when there is one (the watcher
+ brings its draft up to date with newer mail), else a new card, always
+ left for them: never sent on its own. Returns the card's decision id, or
+ a code from ``ASK_REFUSALS``. A Gmail failure is raised."""
+ from openexecutive.config import get_settings
+ from openexecutive.delegation.gmail import GmailNotFound, gmail_for
+ from openexecutive.delegation.inbox_classifier import Verdict
+
+ now = now or datetime.now(UTC)
+ person_id = int(person.id)
+ email = (person.email or "").strip().lower()
+ cards = open_cards(person_id)
+ on_thread = next((c for c in cards if card_payload(c).get("thread_id") == thread_id), None)
+ if on_thread is not None:
+ return int(on_thread.id)
+ if len(cards) >= OPEN_CARDS_MAX:
+ return "backlog_full"
+ client = gmail if gmail is not None else gmail_for(email)
+ try:
+ thread = await client.get_thread(thread_id)
+ except GmailNotFound:
+ return "not_found"
+ own = {email, *(a.strip().lower() for a in await client.send_as_addresses())}
+ shown = [m for m in thread.messages if "DRAFT" not in m.labels]
+ message = next((m for m in shown if m.id == message_id), None)
+ if message is None:
+ return "not_found"
+ if shown[-1].from_addr.strip().lower() in own:
+ return "theirs_last"
+ exec_address = (get_settings().exec_email_address or "").strip().lower()
+ known_as = await relation_of(message.from_addr, client, contacts=bool(person.is_principal))
+ relation = handling_relation(known_as, message)
+ row = _row_for(person_id, message_id)
+ if row is not None and row["outcome"] == PROCESSING:
+ return "busy"
+ if row is None:
+ if not _claim(person_id, message, relation=relation, outcome=PROCESSING, now=now):
+ return "busy"
+ _note_mail(person_id, message, relation=relation)
+ else:
+ _set_outcome(person_id, message_id, PROCESSING, reason="asked")
+ # They asked: the reply is theirs to write, so no verdict is needed.
+ verdict = Verdict(needs_reply=True, kind="request", confidence=1.0, asked_of_them=True)
+ result = ScanResult("ok")
+ try:
+ await _draft_card(
+ person, client, message, thread, relation=relation, known_as=known_as, verdict=verdict,
+ own=own, exec_address=exec_address, now=now, result=result, asked=True,
+ )
+ except Exception:
+ # Never left PROCESSING (every later Reply would say "busy"): it
+ # goes back to the watcher for a later scan, as a scan's failure does.
+ left = _row_for(person_id, message_id)
+ if left is not None and left["outcome"] == PROCESSING:
+ _retry_later(person_id, message_id, "error")
+ raise
+ if result.drafted:
+ done = _row_for(person_id, message_id)
+ if done is not None and isinstance(done["decision_id"], int):
+ return int(done["decision_id"])
+ return "daily_limit" if result.status == "daily_limit" else "not_now"
+
async def _send_on_its_own(person: Any, client: Any, decision_id: int, result: ScanResult, *, now: datetime) -> None:
"""Send the reply on card ``decision_id`` under Handle it for me. A
refusal hands the card back to the person as an ordinary card that says
diff --git a/packages/core/openexecutive/delegation/inbox_classifier.py b/packages/core/openexecutive/delegation/inbox_classifier.py
index 3ef331f3..255b35e0 100644
--- a/packages/core/openexecutive/delegation/inbox_classifier.py
+++ b/packages/core/openexecutive/delegation/inbox_classifier.py
@@ -40,6 +40,8 @@ MAX_BODY_CHARS = 3000
# Of the person's own last email in the thread: enough for what they asked.
MAX_EARLIER_CHARS = 1500
_MAX_TOKENS = 200
+# Attachment names shown in the email's header lines.
+_MAX_ATTACHMENT_NAMES = 5
KINDS: tuple[str, ...] = (
"question",
@@ -110,6 +112,13 @@ Thursday at 11 suit?" waits on their yes, so it is scheduling and needs_reply \
is true. When the email settles what they asked and leaves nothing for them \
to do (it accepts a time they offered), it needs no reply.
+When the email delivers what this person asked for in <their_last_email> \
+(the document, figures or changes they wanted, often attached), it is a \
+follow_up and needs_reply is true, even when it ends with "let me know if \
+you have any questions": they owe a short word back, that it arrived and \
+what happens next, and the deal or task waits on them. A plain thanks or \
+an "ok, will do" that delivers nothing needs no reply.
+
When unsure, say needs_reply false."""
_CLASSIFY_TOOL: dict[str, Any] = {
@@ -241,6 +250,13 @@ def render_email(
header += [
f"Subject: {one_line(getattr(message, 'subject', '') or '', 200)}",
]
+ files = [one_line(a.name, 80) for a in getattr(message, "attachments", None) or [] if getattr(a, "name", "")]
+ if files:
+ shown = ", ".join(files[:_MAX_ATTACHMENT_NAMES])
+ more = len(files) - _MAX_ATTACHMENT_NAMES
+ header.append(f"Attachments: {shown}" + (f" and {more} more" if more > 0 else ""))
+ elif getattr(message, "has_attachments", False):
+ header.append("Attachments: yes")
lines = [scrub_block_line(line, "</email>") for line in [*header, "", *body.splitlines()]]
# The text can't open or close a tag, in any spelling.
text = no_tags("\n".join(lines)).strip()
diff --git a/packages/core/openexecutive/evals/_scenarios/delegation_inbox_016.yaml b/packages/core/openexecutive/evals/_scenarios/delegation_inbox_016.yaml
new file mode 100644
index 00000000..3ce7354f
--- /dev/null
+++ b/packages/core/openexecutive/evals/_scenarios/delegation_inbox_016.yaml
@@ -0,0 +1,41 @@
+id: delegation_inbox_016
+domain: delegation
+type: inbox
+description: "Inbox watcher: the person asked a broker for two separate letters of intent, and the broker sends them attached with \"let me know if you have any questions\". It delivers what they asked for and the deal waits on them, so a short reply is drafted."
+inbox:
+ person:
+ full_name: Olivia Owner
+ relation: contact
+ expect: draft
+ thread:
+ id: t-lois
+ subject: "Re: property figures"
+ messages:
+ - from: "Olivia Owner <[email protected]>"
+ text: |
+ Hi Marco,
+
+ We're good to go with the second offer. Before counsel looks at it,
+ could you have them split the LOI in two, one per property, with
+ the price shown for each?
+
+ Olivia
+ - from: "Marco Reyes <[email protected]>"
+ text: |
+ Attached are the clean versions of the two LOIs, one for Elm Court
+ and one for Bayside Commons. Let me know if you have any questions.
+
+ Marco
+ attachments:
+ - name: LOI Elm Court.pdf
+ text: "Letter of intent: Elm Court. Price $2,400,000."
+ - name: LOI Bayside Commons.pdf
+ text: "Letter of intent: Bayside Commons. Price $2,250,000."
+quality_criteria:
+ acknowledges_the_two_lois_arrived: true
+ says_or_asks_about_the_next_step_without_inventing_commitments: true
+ promises_nothing_new_on_price_or_terms: true
+ brief: true
diff --git a/packages/core/openexecutive/guide/prebuilt/today.json b/packages/core/openexecutive/guide/prebuilt/today.json
index e37c743a..87ef5005 100644
--- a/packages/core/openexecutive/guide/prebuilt/today.json
+++ b/packages/core/openexecutive/guide/prebuilt/today.json
@@ -1,7 +1,7 @@
{
"section_id": "today",
"title": "Today / Morning Brief",
- "markdown": "**What it is:** A single screen of *what needs you right now* — the proactive digest the Executive prepares so you're not the one chasing status. In the app it's **Home**, the screen the app opens on.\n\n**What it does:**\n\n- Opens with a greeting, one line summing up the day (click a part of it — *2 awaiting reply*, *1 department at risk* — to open that list), and an **Ask your Executive anything…** box that starts a chat. On a quiet day the line names one **Move today:** instead.\n- Puts what's waiting on your call up front under **Needs you**: the first card large, the next two below it, and **Show N more** for the rest.\n- Sums up the rest under **At a glance** as a row of count tiles, shown only when they have something in them: **Act as me** (what it sent or accepted for you this week), **Due soon** (what you owe by a date), **Goals** (how many, and how many are at risk), **Workflows** (yours that run on a schedule, and how often they ran this week), **Watching** (what's on your watch list, and any new signals), **Handled**, **Departments**, **People**, **Across the team** (waiting on someone else), **Under way**, and **Across your clients** when you look after client companies. Click a tile to open its list in a side panel, or its page (**Act as me**, **Goals**, **Workflows**, **Watch list**).\n- The **Departments** tile appears once you have departments. It shows each department's goal health — on-track, at-risk, or off-track — with the at-risk goals called out and who each is on. Goals with no department appear there too, as **Other goals**; click it to open **Goals**.\n- The **People** tile lists people with open items, their reply counts, SLA status, and whether they're on leave.\n- In your first week, a **Your first week** card at the top asks for one goal with a date (**Set a goal** opens the add form on **Goals**) until you have one, lists up to two things the Executive found when it researched your company and industry during setup, and links to the **Watch list** with what it keeps watching for you. It goes away after seven days, or sooner once you have a goal and there's nothing to show.\n- **Right now**, above **Needs you**, is the Executive's read of the day, rewritten as things change: when it was last checked, one line on what matters most, and the top points, each with the time it came in. Points that came in since you last looked get a green dot, with *N new since …* beside the title. With **Draft replies to my inbox** on, it also covers mail to your own inbox from people you deal with, including a new reply on a thread whose reply card is still waiting for you; mail from anyone else gets one short **Also in** line at the bottom. **See the whole picture** opens all of it in a side panel: what's new, what's still open, the **Move today** line, what's next on your calendar and, under **Earlier today**, the morning brief you were sent. Tap a point there to talk it through.\n- If your latest morning brief, end-of-day digest or weekly review couldn't be sent to you, a line at the top says why and what to connect. It goes away once that's fixed.\n- When your morning brief or end-of-day digest left out lines that named people or figures the Executive couldn't match to your data, **Left out of your brief** under **Needs you** lists them for a day. **Hide** clears it.\n- With **Delegate → Act as me → What it writes as you** at **Draft replies automatically**, the replies the Executive wrote as you for mail that needs you come first in **Needs you**, marked **Reply waiting** (or **Follow-up waiting** when nobody answered an email you sent). Only you see them.\n- With **Read my calendar** on, a meeting invite from someone you know appears as a card in **Needs you**, marked **Invite**: the meeting, when it is, who invited you and anything on your calendar it clashes with (only the times). **Accept** or **Decline** answers it in your own calendar, and your calendar lets them know; **Dismiss** removes the card without answering. While replies are still being learned, ticking **Accept from <name> on its own next time** before **Accept** lets it accept their invites on its own when nothing clashes. If your calendar sign-in can't answer invites yet, the card says to connect again under **Read my calendar** instead. Only you see them.\n- Actions the Executive suggested from your email (a meeting, a message to someone, a new contact, a rename or move of files in your Drive) appear as cards in **Needs you**, each spelled out with a box to untick. **Approve** does the ticked ones (**Approve N** when you untick some), ticking **Do this on its own next time** first (shown while it is still learning) also lets it do that kind of action on its own from now on, and **Dismiss** drops the card. Only you see them.\n- A send or edit a team member asked for in chat that their department held waits as a card marked **Waiting on you**, with the reason and the exact details. **Approve** carries it out as shown; **Decline** drops it.\n- An item a team member asked the Executive to raise starts with **Raised by** and their name. It goes to a person or a department, never to the whole company. Team members can dismiss only items assigned to them; the owner can dismiss any item.\n- Under **Take the lead**, something the Executive wanted to do on its own that you haven't allowed yet comes as a card: **Approve** does it once (tick **Do this on its own next time** first and it does the same thing with the same person on its own from now on), **Edit** changes it first (tick **Do it like this next time** to keep your edit as an example and allow it), and **Decline** drops it.\n- Surfaces proposals and alerts you can click to open a chat thread with full context.\n\n**How to use:**\n\n1. Click **Home** in the sidebar (or the Open Executive logo). On a phone, **Home** is the first button in the bar at the bottom.\n2. Work **Needs you** from the top. Each card has one main button and **Discuss**; everything else is in the card's **⋯** menu:\n - **Approve** — accept the recommendation; the Executive carries it out right away. A line at the top of **Needs you** shows it working and then done, with a link to the chat where it did the work. If it didn't work, **Try again** is on that line. Usually the main button.\n - **Discuss** — open a chat with the context already filled in.\n - **Edit & approve** (in **⋯**) — reword the action first, then **Send approval**; your text is used exactly as written.\n - **Dismiss** (in **⋯**) — drop it and stay on Home. When the Executive thinks a card is stale, **Dismiss** is the main button instead.\n - **Snooze until …** (in **⋯**) — three hours from now (while that is still today), **tomorrow 9:00**, or **Monday 9:00** (not offered on a Sunday). The card leaves Home and comes back on its own then; *Snoozed until …* with **Undo** under **Needs you** brings it back now.\n - **Nudge *name*** — the main button when the best move is chasing someone for a reply; **Run *workflow*** when the best move is a workflow.\n - **Open *name*'s page** (in **⋯**) — the person the item is waiting on.\n - A **Monitoring** signal leads with **Discuss**; its **⋯** has **Dismiss signal**.\n3. Some cards are simpler: when a scheduled run didn't finish (a department check-in, or a workflow you set to run on a schedule), its card's main button is **Run again**, which runs it now and sends the result where it normally goes (**Open the run** in **⋯** shows what went wrong); a document card's main button is **Open document** (**Mark reviewed** is in its **⋯**, and **Open in app** when the document lives in another app), and a calendar-booking card books (or declines) the meeting directly when you click Approve or Dismiss. Only the person a booking was sent to for approval, or the owner, can approve or decline it.\n4. Keep it tidy from the **⋯** next to **Needs you**: **Dismiss N older than 7 days** clears stale items, and **Re-check relevance** asks the Executive to review every open item now.\n5. Open the **Departments** tile and click a department to ask for its status in chat.\n6. Work the replies waiting to be sent (they come first in **Needs you**). Each card starts closed: who wrote (and *Address not verified* when the address couldn't be confirmed), a line or two on what they asked and what your draft says, how many things are left to decide and who it goes to, with **Send** when nothing is left (or **Review** when something is) and **Dismiss**. Click the card or **Review** to open it. Open, everything shows at once, like a conversation: *Why it waited for you* when Handle it for me left it for you, what they wrote, then the Executive's note on your reply with what's left to decide (short answers to tap) and what you already decided (**Change** to pick again), then **Your reply** with who it goes to (**Reply to**: just them or everyone). Tap an answer, or **Something else…** to type your own, and the reply is rewritten with it; the new words are lightly marked. Type in **Tell me what to change…** (\"make it shorter\", \"offer Thursday instead\") and it rewrites the reply that way and says what it changed. If they write again in the same conversation before you send, the new email shows on the card marked **New**, and the Executive brings your reply up to date with it and asks you anything only you can decide. For a time it can offer free slots from your calendar, when Read my calendar is on, and for a document one from your documents to say you'll send. **Send** waits until each of these is answered, or until you change the words yourself) and any warnings. The buttons:\n - **Send** asks once, naming who the reply goes to, then **Send now** sends it from your own mailbox (Gmail or Outlook). If the recipients changed or they wrote again since, it asks again, says what changed, and offers **Send anyway**.\n - **Reply to <name> on its own next time** (a tick shown while replies are still being learned): tick it before **Send** and replies to that person go on their own from now on while Handle it for me is on.\n - **Edit the words myself** changes the words right on the card; **Save** keeps them (and updates the draft in your mailbox when it is kept there too). When it is learning how you write, **Do it like this next time (if you changed it)** appears as you send.\n - **Open in Gmail** (or Outlook) opens the draft there, when it is kept in your Drafts.\n - **Dismiss** drops the card, and deletes the draft from your Drafts unless you changed it there.\n On a server, Send needs signed sign-ins; until they're set up, send from your mailbox. A card goes away on its own once you send or delete the draft in your mailbox, or reply yourself, and after 7 days.\n\n**Example:** in a Discuss thread, just say *\"go ahead\"* to approve the proposal or *\"drop it\"* to dismiss it — no need to go back to the card. (Calendar bookings still need the Approve button. When you asked for the meeting in a chat, its card is under that reply too.)\n\n**Just for yourself?** If you use Open Executive just for yourself (**Settings → Workspace → Personal**), Home leaves out the team parts: there are no Departments, People or Across the team tiles — everything that needs a decision is in **Needs you**. When a goal is slipping, the summary line at the top says how many goals are at risk; click it to open **Goals**. Instead, it adds the **Your projects** and **This week's review** tiles, each opening its list in a side panel. **Your projects** lists the projects the Executive is tracking for you. Click **Done** when one is finished, or **Drop** to stop tracking it (it asks first, and removes the project from Pulse). **Due soon** (on every Home) lists what you've promised by a date and what others have asked of you, due in the next week — say *\"I'll send Northwind the proposal by Friday\"* in the web chat or your own Slack or Discord and it shows up here, and the Executive reminds you when it's due. Click **Done** once it's handled; **All open items** opens the full list. **Top three today**, right under **Needs you**, shows the three things to focus on today — the same three your morning brief opens with — each with a free slot in today's working hours when the Executive can read your calendar. **This week's review** shows your latest weekly review: when it ran and next week's top three. Click **Read the review** to see all of it.\n\nYour morning brief also opens with a **top three for today**, picked from what's overdue or due, goals that are slipping and the projects you're driving. When Google Workspace is connected and the Executive can read your calendar (it is your own account, or you shared your calendar with it), each of the three gets a free slot in today's working hours and the brief lists today's meetings; otherwise the three come without times. Every Friday afternoon (in your time zone) a **weekly review** arrives the same way: your goals graded by area, what's due or overdue, projects that went quiet, the week's decisions, a few older decisions to look back on, and next week's top three. Both also show up on Home (see above), so you see them even when no chat app or email is connected. When it asks how an older decision turned out, just tell the Executive in the web chat or your own Slack or Discord and it records the outcome against that decision.\n\n*Note: proposals are routed to the right person automatically based on who has authority over them.*",
+ "markdown": "**What it is:** A single screen of *what needs you right now* — the proactive digest the Executive prepares so you're not the one chasing status. In the app it's **Home**, the screen the app opens on.\n\n**What it does:**\n\n- Opens with a greeting, one line summing up the day (click a part of it — *2 awaiting reply*, *1 department at risk* — to open that list), and an **Ask your Executive anything…** box that starts a chat. On a quiet day the line names one **Move today:** instead.\n- Puts what's waiting on your call up front under **Needs you**: the first card large, the next two below it, and **Show N more** for the rest.\n- Sums up the rest under **At a glance** as a row of count tiles, shown only when they have something in them: **Act as me** (what it sent or accepted for you this week), **Due soon** (what you owe by a date), **Goals** (how many, and how many are at risk), **Workflows** (yours that run on a schedule, and how often they ran this week), **Watching** (what's on your watch list, and any new signals), **Handled**, **Departments**, **People**, **Across the team** (waiting on someone else), **Under way**, and **Across your clients** when you look after client companies. Click a tile to open its list in a side panel, or its page (**Act as me**, **Goals**, **Workflows**, **Watch list**).\n- The **Departments** tile appears once you have departments. It shows each department's goal health — on-track, at-risk, or off-track — with the at-risk goals called out and who each is on. Goals with no department appear there too, as **Other goals**; click it to open **Goals**.\n- The **People** tile lists people with open items, their reply counts, SLA status, and whether they're on leave.\n- In your first week, a **Your first week** card at the top asks for one goal with a date (**Set a goal** opens the add form on **Goals**) until you have one, lists up to two things the Executive found when it researched your company and industry during setup, and links to the **Watch list** with what it keeps watching for you. It goes away after seven days, or sooner once you have a goal and there's nothing to show.\n- **Right now**, above **Needs you**, is the Executive's read of the day, rewritten as things change: when it was last checked, one line on what matters most, and the top points, each with the time it came in. Points that came in since you last looked get a green dot, with *N new since …* beside the title. With **Draft replies to my inbox** on, it also covers mail to your own inbox from people you deal with, including a new reply on a thread whose reply card is still waiting for you; mail from anyone else gets one short **Also in** line at the bottom. **See the whole picture** opens all of it in a side panel: what's new, what's still open, the **Move today** line, what's next on your calendar and, under **Earlier today**, the morning brief you were sent. Tap a point there to talk it through. A point about an email to you has **View email** and **Reply** under it: View opens the email right there, with its files and what you last wrote to them, and the reply already waiting for it if there is one; Reply writes one in your voice for you to send, change or edit (nothing goes until you tap Send). A point about something waiting for your decision has **Show me**, which takes you to it under Needs you.\n- If your latest morning brief, end-of-day digest or weekly review couldn't be sent to you, a line at the top says why and what to connect. It goes away once that's fixed.\n- When your morning brief or end-of-day digest left out lines that named people or figures the Executive couldn't match to your data, **Left out of your brief** under **Needs you** lists them for a day. **Hide** clears it.\n- With **Delegate → Act as me → What it writes as you** at **Draft replies automatically**, the replies the Executive wrote as you for mail that needs you come first in **Needs you**, marked **Reply waiting** (or **Follow-up waiting** when nobody answered an email you sent). Only you see them.\n- With **Read my calendar** on, a meeting invite from someone you know appears as a card in **Needs you**, marked **Invite**: the meeting, when it is, who invited you and anything on your calendar it clashes with (only the times). **Accept** or **Decline** answers it in your own calendar, and your calendar lets them know; **Dismiss** removes the card without answering. While replies are still being learned, ticking **Accept from <name> on its own next time** before **Accept** lets it accept their invites on its own when nothing clashes. If your calendar sign-in can't answer invites yet, the card says to connect again under **Read my calendar** instead. Only you see them.\n- Actions the Executive suggested from your email (a meeting, a message to someone, a new contact, a rename or move of files in your Drive) appear as cards in **Needs you**, each spelled out with a box to untick. **Approve** does the ticked ones (**Approve N** when you untick some), ticking **Do this on its own next time** first (shown while it is still learning) also lets it do that kind of action on its own from now on, and **Dismiss** drops the card. Only you see them.\n- A send or edit a team member asked for in chat that their department held waits as a card marked **Waiting on you**, with the reason and the exact details. **Approve** carries it out as shown; **Decline** drops it.\n- An item a team member asked the Executive to raise starts with **Raised by** and their name. It goes to a person or a department, never to the whole company. Team members can dismiss only items assigned to them; the owner can dismiss any item.\n- Under **Take the lead**, something the Executive wanted to do on its own that you haven't allowed yet comes as a card: **Approve** does it once (tick **Do this on its own next time** first and it does the same thing with the same person on its own from now on), **Edit** changes it first (tick **Do it like this next time** to keep your edit as an example and allow it), and **Decline** drops it.\n- Surfaces proposals and alerts you can click to open a chat thread with full context.\n\n**How to use:**\n\n1. Click **Home** in the sidebar (or the Open Executive logo). On a phone, **Home** is the first button in the bar at the bottom.\n2. Work **Needs you** from the top. Each card has one main button and **Discuss**; everything else is in the card's **⋯** menu:\n - **Approve** — accept the recommendation; the Executive carries it out right away. A line at the top of **Needs you** shows it working and then done, with a link to the chat where it did the work. If it didn't work, **Try again** is on that line. Usually the main button.\n - **Discuss** — open a chat with the context already filled in.\n - **Edit & approve** (in **⋯**) — reword the action first, then **Send approval**; your text is used exactly as written.\n - **Dismiss** (in **⋯**) — drop it and stay on Home. When the Executive thinks a card is stale, **Dismiss** is the main button instead.\n - **Snooze until …** (in **⋯**) — three hours from now (while that is still today), **tomorrow 9:00**, or **Monday 9:00** (not offered on a Sunday). The card leaves Home and comes back on its own then; *Snoozed until …* with **Undo** under **Needs you** brings it back now.\n - **Nudge *name*** — the main button when the best move is chasing someone for a reply; **Run *workflow*** when the best move is a workflow.\n - **Open *name*'s page** (in **⋯**) — the person the item is waiting on.\n - A **Monitoring** signal leads with **Discuss**; its **⋯** has **Dismiss signal**.\n3. Some cards are simpler: when a scheduled run didn't finish (a department check-in, or a workflow you set to run on a schedule), its card's main button is **Run again**, which runs it now and sends the result where it normally goes (**Open the run** in **⋯** shows what went wrong); a document card's main button is **Open document** (**Mark reviewed** is in its **⋯**, and **Open in app** when the document lives in another app), and a calendar-booking card books (or declines) the meeting directly when you click Approve or Dismiss. Only the person a booking was sent to for approval, or the owner, can approve or decline it.\n4. Keep it tidy from the **⋯** next to **Needs you**: **Dismiss N older than 7 days** clears stale items, and **Re-check relevance** asks the Executive to review every open item now.\n5. Open the **Departments** tile and click a department to ask for its status in chat.\n6. Work the replies waiting to be sent (they come first in **Needs you**). Each card starts closed: who wrote (and *Address not verified* when the address couldn't be confirmed), a line or two on what they asked and what your draft says, how many things are left to decide and who it goes to, with **Send** when nothing is left (or **Review** when something is) and **Dismiss**. Click the card or **Review** to open it. Open, everything shows at once, like a conversation: *Why it waited for you* when Handle it for me left it for you, what they wrote, then the Executive's note on your reply with what's left to decide (short answers to tap) and what you already decided (**Change** to pick again), then **Your reply** with who it goes to (**Reply to**: just them or everyone). Tap an answer, or **Something else…** to type your own, and the reply is rewritten with it; the new words are lightly marked. Type in **Tell me what to change…** (\"make it shorter\", \"offer Thursday instead\") and it rewrites the reply that way and says what it changed. If they write again in the same conversation before you send, the new email shows on the card marked **New**, and the Executive brings your reply up to date with it and asks you anything only you can decide. For a time it can offer free slots from your calendar, when Read my calendar is on, and for a document one from your documents to say you'll send. **Send** waits until each of these is answered, or until you change the words yourself) and any warnings. The buttons:\n - **Send** asks once, naming who the reply goes to, then **Send now** sends it from your own mailbox (Gmail or Outlook). If the recipients changed or they wrote again since, it asks again, says what changed, and offers **Send anyway**.\n - **Reply to <name> on its own next time** (a tick shown while replies are still being learned): tick it before **Send** and replies to that person go on their own from now on while Handle it for me is on.\n - **Edit the words myself** changes the words right on the card; **Save** keeps them (and updates the draft in your mailbox when it is kept there too). When it is learning how you write, **Do it like this next time (if you changed it)** appears as you send.\n - **Open in Gmail** (or Outlook) opens the draft there, when it is kept in your Drafts.\n - **Dismiss** drops the card, and deletes the draft from your Drafts unless you changed it there.\n On a server, Send needs signed sign-ins; until they're set up, send from your mailbox. A card goes away on its own once you send or delete the draft in your mailbox, or reply yourself, and after 7 days.\n\n**Example:** in a Discuss thread, just say *\"go ahead\"* to approve the proposal or *\"drop it\"* to dismiss it — no need to go back to the card. (Calendar bookings still need the Approve button. When you asked for the meeting in a chat, its card is under that reply too.)\n\n**Just for yourself?** If you use Open Executive just for yourself (**Settings → Workspace → Personal**), Home leaves out the team parts: there are no Departments, People or Across the team tiles — everything that needs a decision is in **Needs you**. When a goal is slipping, the summary line at the top says how many goals are at risk; click it to open **Goals**. Instead, it adds the **Your projects** and **This week's review** tiles, each opening its list in a side panel. **Your projects** lists the projects the Executive is tracking for you. Click **Done** when one is finished, or **Drop** to stop tracking it (it asks first, and removes the project from Pulse). **Due soon** (on every Home) lists what you've promised by a date and what others have asked of you, due in the next week — say *\"I'll send Northwind the proposal by Friday\"* in the web chat or your own Slack or Discord and it shows up here, and the Executive reminds you when it's due. Click **Done** once it's handled; **All open items** opens the full list. **Top three today**, right under **Needs you**, shows the three things to focus on today — the same three your morning brief opens with — each with a free slot in today's working hours when the Executive can read your calendar. **This week's review** shows your latest weekly review: when it ran and next week's top three. Click **Read the review** to see all of it.\n\nYour morning brief also opens with a **top three for today**, picked from what's overdue or due, goals that are slipping and the projects you're driving. When Google Workspace is connected and the Executive can read your calendar (it is your own account, or you shared your calendar with it), each of the three gets a free slot in today's working hours and the brief lists today's meetings; otherwise the three come without times. Every Friday afternoon (in your time zone) a **weekly review** arrives the same way: your goals graded by area, what's due or overdue, projects that went quiet, the week's decisions, a few older decisions to look back on, and next week's top three. Both also show up on Home (see above), so you see them even when no chat app or email is connected. When it asks how an older decision turned out, just tell the Executive in the web chat or your own Slack or Discord and it records the outcome against that decision.\n\n*Note: proposals are routed to the right person automatically based on who has authority over them.*",
"mermaid": null,
- "generated_at": "2026-10-26T19:13:19Z"
+ "generated_at": "2026-10-27T18:30:00Z"
}
diff --git a/packages/core/tests/unit/test_delegation_inbox.py b/packages/core/tests/unit/test_delegation_inbox.py
index 5d430176..212433f2 100644
--- a/packages/core/tests/unit/test_delegation_inbox.py
+++ b/packages/core/tests/unit/test_delegation_inbox.py
@@ -643,6 +643,17 @@ def test_their_last_email_cannot_end_its_block_or_open_another() -> None:
assert ic.render_email(_msg("m1", "t1"), relation="team").startswith("<email>")
+def test_the_email_turn_names_its_attachments() -> None:
+ from openexecutive.delegation.gmail import MailAttachment
+
+ files = [MailAttachment(index=n, name=f"LOI {n}.pdf") for n in range(1, 8)]
+ turn = ic.render_email(_msg("m1", "t1", attachments=files), relation="contact")
+ assert "Attachments: LOI 1.pdf, LOI 2.pdf, LOI 3.pdf, LOI 4.pdf, LOI 5.pdf and 2 more" in turn
+ # Outlook says only that there are some.
+ assert "Attachments: yes" in ic.render_email(_msg("m1", "t1", has_attachments=True), relation="contact")
+ assert "Attachments" not in ic.render_email(_msg("m1", "t1"), relation="contact")
+
+
def test_mail_to_the_executive_that_copies_them_gets_no_draft(
db: Path, owner: Any, models: dict[str, Any]
) -> None:
@@ -1294,3 +1305,75 @@ def test_the_writers_notes_for_the_sender_and_everyone_copied_reach_the_composer
_scan(owner, mailbox)
assert asked == [(owner.id, [DANA, "[email protected]"])]
assert '<writer_noted>\n[2026-09-28] agreed: "Friday works"\n</writer_noted>' in models["composed"][-1]
+
+
+# ── Reply from Home (draft_on_request) ───────────────────────────────────────
+
+
+def _ask(person: Any, mailbox: FakeInbox, thread_id: str, message_id: str) -> int | str:
+ return asyncio.run(inbox.draft_on_request(person, thread_id, message_id, gmail=mailbox, now=NOW))
+
+
+def test_reply_from_home_drafts_what_the_watcher_passed_over(
+ db: Path, owner: Any, models: dict[str, Any]
+) -> None:
+ from openexecutive.delegation import handle_it
+
+ # Handle it for me is on, yet a reply they asked for waits for them.
+ handle_it.set_(owner.id, enabled=True, mode="bold", updated_by="test")
+ models["verdicts"]["LOIs"] = {"needs_reply": False, "kind": "fyi", "asked_of_them": True, "confidence": 0.9}
+ mailbox = FakeInbox()
+ mailbox.add(_msg("m1", "t1", text="Attached are the two LOIs. Let me know if you have any questions."))
+ assert _scan(owner, mailbox).not_needed == 1
+
+ got = _ask(owner, mailbox, "t1", "m1")
+
+ [card] = inbox.open_cards(owner.id)
+ assert got == card.id and card.status == "proposed"
+ assert mailbox.sent == [] and len(mailbox.specs) == 1
+ assert _ledger(db)["m1"][0] == "drafted"
+ # Asked again: the same card, no second draft.
+ assert _ask(owner, mailbox, "t1", "m1") == card.id and len(mailbox.specs) == 1
+
+
+def test_reply_from_home_reuses_the_card_on_the_conversation(owner: Any, models: dict[str, Any]) -> None:
+ mailbox = FakeInbox()
+ mailbox.add(_msg("m1", "t1"))
+ _scan(owner, mailbox)
+ [card] = inbox.open_cards(owner.id)
+ mailbox.add(_msg("m2", "t1", minutes_ago=5, text="Also, can you bring the deck?"))
+ assert _ask(owner, mailbox, "t1", "m2") == card.id
+ assert len(mailbox.specs) == 1
+
+
+def test_reply_from_home_refuses_what_it_cannot_answer(db: Path, owner: Any, models: dict[str, Any]) -> None:
+ mailbox = FakeInbox()
+ mailbox.add(_msg("m1", "t1"), _msg("r1", "t1", sender=OWNER, labels=("SENT",), minutes_ago=5))
+ assert _ask(owner, mailbox, "t1", "m1") == "theirs_last"
+ assert _ask(owner, mailbox, "nope", "m1") == "not_found"
+ assert _ask(owner, mailbox, "t1", "gone") == "not_found"
+ assert set(inbox.ASK_REFUSALS) >= {"theirs_last", "not_found", "busy", "daily_limit", "not_now"}
+ assert mailbox.specs == [] and inbox.open_cards(owner.id) == []
+
+
+def test_reply_from_home_that_fails_is_not_left_busy(
+ db: Path, owner: Any, models: dict[str, Any], monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from openexecutive.delegation import handle_it
+
+ real = handle_it.get
+ broken = {"on": True}
+
+ def flaky(person_id: int) -> Any:
+ if broken["on"]:
+ raise RuntimeError("db down")
+ return real(person_id)
+
+ mailbox = FakeInbox()
+ mailbox.add(_msg("m1", "t1"))
+ monkeypatch.setattr(handle_it, "get", flaky)
+ with pytest.raises(RuntimeError):
+ _ask(owner, mailbox, "t1", "m1")
+ assert _ledger(db)["m1"][0] == "retry"
+ broken["on"] = False
+ assert isinstance(_ask(owner, mailbox, "t1", "m1"), int)
diff --git a/packages/core/tests/unit/test_delegation_inbox_routes.py b/packages/core/tests/unit/test_delegation_inbox_routes.py
index 6d7b5115..bd2b59ec 100644
--- a/packages/core/tests/unit/test_delegation_inbox_routes.py
+++ b/packages/core/tests/unit/test_delegation_inbox_routes.py
@@ -280,3 +280,45 @@ def test_choosing_who_a_reply_goes_to(
resp = client.put(url, json={"everyone": False}, headers=OWNER)
assert resp.json()["draft_to"] == [sender] and mailbox.drafts["d1"].message.cc == []
assert client.put("/delegation/replies/9999/recipients", json={"everyone": True}, headers=OWNER).status_code == 404
+
+
+def test_view_an_email_from_home(client: TestClient, ids: dict[str, int], monkeypatch: pytest.MonkeyPatch) -> None:
+ from openexecutive.delegation.gmail import MailAttachment
+
+ set_enabled(ids["principal"], True, updated_by="t")
+ mailbox = FakeInbox()
+ mailbox.add(
+ _msg("r0", "t1", sender="[email protected]", labels=("SENT",), minutes_ago=90, text="Two LOIs, please."),
+ _msg(
+ "m1", "t1", text="Attached are the two LOIs.\n\nOn Mon, Olivia wrote:\n> Two LOIs, please.",
+ attachments=[MailAttachment(index=1, name="LOI Elm.pdf", mime_type="application/pdf", size=10)],
+ ),
+ )
+ mailbox.email = "[email protected]"
+ monkeypatch.setattr(route, "gmail_for", lambda email: mailbox)
+
+ body = client.get("/delegation/mail", params={"thread_id": "t1", "message_id": "m1"}, headers=OWNER).json()
+ assert body["from_email"] == "[email protected]" and body["subject"] == "Thursday call"
+ assert body["text"] == "Attached are the two LOIs." # their own words, not the quoted mail
+ assert body["attachments"] == [{"name": "LOI Elm.pdf", "mime_type": "application/pdf", "size": 10}]
+ assert body["their_last_words"] == "Two LOIs, please."
+ assert body["link"].startswith("https://mail.google.com/") and body["reply_card_id"] is None
+ missing = client.get("/delegation/mail", params={"thread_id": "t1", "message_id": "x"}, headers=OWNER)
+ assert missing.status_code == 404
+ # Someone without Act as me reads nothing.
+ assert client.get("/delegation/mail", params={"thread_id": "t1", "message_id": "m1"}, headers=TEAMMATE).status_code == 403
+
+
+def test_reply_from_home_makes_a_card(client: TestClient, ids: dict[str, int], monkeypatch: pytest.MonkeyPatch) -> None:
+ mailbox, card_id = _card(ids["principal"], monkeypatch)
+ monkeypatch.setattr(route, "gmail_for", lambda email: mailbox)
+ # The conversation's open card is the answer.
+ resp = client.post("/delegation/mail/reply", json={"thread_id": "t1", "message_id": "m1"}, headers=OWNER)
+ assert resp.status_code == 200 and resp.json() == {"decision_id": card_id}
+ view = client.get("/delegation/mail", params={"thread_id": "t1", "message_id": "m1"}, headers=OWNER).json()
+ assert view["reply_card_id"] == card_id
+ gone = client.post("/delegation/mail/reply", json={"thread_id": "t9", "message_id": "m9"}, headers=OWNER)
+ assert gone.status_code == 409 and gone.json()["detail"]["code"] == "not_found"
+ set_enabled(ids["principal"], False, updated_by="t")
+ off = client.post("/delegation/mail/reply", json={"thread_id": "t1", "message_id": "m1"}, headers=OWNER)
+ assert off.status_code == 409 and off.json()["detail"]["code"] == "act_as_me_off"
diff --git a/packages/core/tests/unit/test_header_context.py b/packages/core/tests/unit/test_header_context.py
index e49ae42b..3cb681c4 100644
--- a/packages/core/tests/unit/test_header_context.py
+++ b/packages/core/tests/unit/test_header_context.py
@@ -419,3 +419,57 @@ def test_needs_you_tags_and_point_citations() -> None:
("**Andy Agee** — wants a call.", frozenset({"M1"})),
("**Update call** — done.", frozenset({"M2"})),
]
+
+
+def test_inbox_lines_and_cards_raised_today_carry_what_they_are_about() -> None:
+ from openexecutive.briefing.header_context import point_sources
+
+ ref = {"kind": "mail", "message_id": "m1", "thread_id": "t1"}
+ ctx = _render(
+ today_data={"proposals": [
+ {"alert_id": 12, "headline": "Approve the Acme quote", "created_at": TODAY},
+ {"alert_id": 13, "headline": "Old one", "created_at": LAST_WEEK},
+ ]},
+ live=LiveSignals(
+ inbox=('[14:12] from Andy Agee ([email protected]): "Re: loan figures"',),
+ inbox_refs=(ref,),
+ met_today=("14:30–15:15 Update call",),
+ ),
+ )
+ sources = ctx.sources # type: ignore[attr-defined]
+ assert sources == {"M1": ref, "M3": {"kind": "alert", "alert_id": 12}}
+ assert "m1" not in ctx.text # type: ignore[attr-defined] # ids never reach the model
+
+ draft = (
+ "**Two things.**\n\n- **Loan figures** — Andy sent them. [M2] [M1]\n"
+ "- **Update call** — done. [M2]\n- **Acme quote** — waiting on you. [M3]"
+ )
+ assert point_sources(draft, sources) == [
+ ("**Loan figures** — Andy sent them.", ref),
+ ("**Acme quote** — waiting on you.", {"kind": "alert", "alert_id": 12}),
+ ]
+
+
+def test_a_point_on_home_says_which_email_it_is(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ from openexecutive.api.routes import today as today_route
+ from openexecutive.briefing import narrative as briefing_narrative
+ from tests.unit.test_today_route import _make_client, _seed_live_action_alert, _setup_isolated_db
+
+ db = tmp_path / "rn-source.db"
+ _setup_isolated_db(db, monkeypatch)
+ _seed_live_action_alert(db)
+ ref = {"kind": "mail", "message_id": "m1", "thread_id": "t1"}
+ live = LiveSignals(inbox=('[14:12] from Andy Agee ([email protected]): "Re: loan figures"',), inbox_refs=(ref,))
+ monkeypatch.setattr(today_route, "_header_live", lambda **_kw: (live, "today so far", "NOW"))
+
+ async def _draft(**_kw: object) -> str:
+ return "**Andy sent the figures.**\n\n- **Loan figures** — Andy sent them. [M1]"
+
+ monkeypatch.setattr(briefing_narrative, "synthesize_briefing_narrative", _draft)
+ c = _make_client()
+ c.get("/today")
+ points = c.get("/today").json()["narrative_points"]
+ assert points[0]["text"] == "**Loan figures** — Andy sent them."
+ assert points[0]["source"] == {
+ "kind": "mail", "message_id": "m1", "thread_id": "t1", "decision_id": None, "alert_id": None,
+ }
diff --git a/packages/core/tests/unit/test_live_signals.py b/packages/core/tests/unit/test_live_signals.py
index 55f7e30f..2481c409 100644
--- a/packages/core/tests/unit/test_live_signals.py
+++ b/packages/core/tests/unit/test_live_signals.py
@@ -704,6 +704,9 @@ def test_own_inbox_splits_people_they_deal_with_from_the_rest(
assert "on a card waiting" in mail.lines[0]
assert sorted(mail.others) == ["Kim: All hands", "Yardi: Webinar"]
assert mail.others_total == 2
+ # Which email the line is, for Home to open it.
+ assert len(mail.refs) == 1
+ assert mail.refs[0]["kind"] == "mail" and mail.refs[0]["message_id"] == "m1"
def test_newer_mail_on_an_open_card_is_news_and_noted_once(
@@ -727,6 +730,7 @@ def test_newer_mail_on_an_open_card_is_news_and_noted_once(
assert len(mail.lines) == 1
assert "reply card is still open" in mail.lines[0]
+ assert mail.refs[0] == {"kind": "mail", "message_id": "r1", "thread_id": "t1", "decision_id": 39}
rows = live_signals._audit_rows(inbox.MAIL_SEEN_EVENT, now - timedelta(days=1), True)
assert len([r for r in rows if r.details.get("message_id") == "r1"]) <= 1
diff --git a/packages/core/tests/unit/test_right_now.py b/packages/core/tests/unit/test_right_now.py
index 9586a952..9ea520ca 100644
--- a/packages/core/tests/unit/test_right_now.py
+++ b/packages/core/tests/unit/test_right_now.py
@@ -82,3 +82,16 @@ def test_record_points_says_what_is_new_today() -> None:
"principal", HEADER + "\n- **Board deck** — draft is in.", now.isoformat(),
)
assert later.new == ["**Board deck** — draft is in."]
+
+
+def test_point_sources_are_the_latest_headers_alone() -> None:
+ now = datetime.now(UTC)
+ day = narrative_cache.local_today(now)
+ mail = {"kind": "mail", "message_id": "m1", "thread_id": "t1"}
+ right_now.record_sources("principal", now.isoformat(), {"northwind contract": mail})
+ assert right_now.point_sources("principal", day) == {"northwind contract": mail}
+ # The next header replaces them: a point it no longer has opens nothing.
+ card = {"kind": "alert", "alert_id": 4}
+ right_now.record_sources("principal", now.isoformat(), {"lakeside renewal": card})
+ assert right_now.point_sources("principal", day) == {"lakeside renewal": card}
+ assert right_now.point_sources("person:7", day) == {}
diff --git a/packages/ui/scripts/rightNow.test.mjs b/packages/ui/scripts/rightNow.test.mjs
index d3afe352..f4fc01d3 100644
--- a/packages/ui/scripts/rightNow.test.mjs
+++ b/packages/ui/scripts/rightNow.test.mjs
@@ -1,7 +1,7 @@
import assert from "node:assert/strict";
import { test } from "node:test";
-import { alsoInLine, checkedLabel, clockLabel, isNewSince, newSinceLabel, seenBaseline } from "../src/lib/rightNow.ts";
+import { alsoInLine, checkedLabel, clockLabel, isNewSince, newSinceLabel, pointTarget, seenBaseline } from "../src/lib/rightNow.ts";
const at = (h, m) => {
const d = new Date();
@@ -59,3 +59,14 @@ test("alsoInLine names a few and counts the rest", () => {
);
assert.equal(alsoInLine([], 3), "Also in: 3 others.");
});
+
+test("a point opens the email or card it is about", () => {
+ assert.deepEqual(
+ pointTarget({ text: "a", source: { kind: "mail", message_id: "m1", thread_id: "t1", decision_id: 4 } }),
+ { kind: "mail", threadId: "t1", messageId: "m1", cardId: 4 },
+ );
+ assert.deepEqual(pointTarget({ text: "a", source: { kind: "alert", alert_id: 9 } }), { kind: "alert", alertId: 9 });
+ // An email without its conversation, or no source, opens nothing.
+ assert.equal(pointTarget({ text: "a", source: { kind: "mail", message_id: "m1" } }), null);
+ assert.equal(pointTarget({ text: "a" }), null);
+});
diff --git a/packages/ui/src/components/Briefing.tsx b/packages/ui/src/components/Briefing.tsx
index b94145ca..816ddb1f 100644
--- a/packages/ui/src/components/Briefing.tsx
+++ b/packages/ui/src/components/Briefing.tsx
@@ -443,6 +443,10 @@ export default function Briefing({ onContinue, showHeader = false, firstName, ba
}, 120);
};
+ // What Right now's points open: the email (and its reply card, shared
+ // with Needs you) or the card in Needs you.
+ const rightNowActions = { replies, onShowAlert: jumpToAlert, onContinue };
+
const dateLabel = new Date().toLocaleDateString("en-US", { weekday: "long", month: "long", day: "numeric" });
const departments = today?.departments ?? [];
@@ -909,6 +913,7 @@ export default function Briefing({ onContinue, showHeader = false, firstName, ba
baseline={rightNowBaseline?.at ?? null}
updatedLabel={briefFreshness}
onOpen={() => setOpenPanel("brief")}
+ actions={rightNowActions}
/>
)}
@@ -1064,7 +1069,12 @@ export default function Briefing({ onContinue, showHeader = false, firstName, ba
}
width="lg"
>
- <RightNowBody today={today} baseline={rightNowBaseline?.at ?? null} onContinue={onContinue} />
+ <RightNowBody
+ today={today}
+ baseline={rightNowBaseline?.at ?? null}
+ onContinue={onContinue}
+ actions={rightNowActions}
+ />
</SidePanel>
<SidePanel
open={openPanel === "departments"}
diff --git a/packages/ui/src/components/RepliesWaiting.tsx b/packages/ui/src/components/RepliesWaiting.tsx
index 13d85afa..a7d457ea 100644
--- a/packages/ui/src/components/RepliesWaiting.tsx
+++ b/packages/ui/src/components/RepliesWaiting.tsx
@@ -137,9 +137,12 @@ export function ReplyCardItem({
onRefresh,
onChanged,
emphasized = false,
+ defaultOpen = false,
}: {
card: ReplyCard;
emphasized?: boolean;
+ // Start open (Right now's View email shows the reply straight away).
+ defaultOpen?: boolean;
onGone: (id: number, note?: string) => void;
onRefresh: () => Promise<void>;
onChanged?: (card: ReplyCard) => void;
@@ -147,7 +150,7 @@ export function ReplyCardItem({
const [step, setStep] = useState<Step>({ kind: "idle" });
const [error, setError] = useState<string | null>(null);
// Closed until tapped: the summary, what's left to decide, one main button.
- const [open, setOpen] = useState(false);
+ const [open, setOpen] = useState(defaultOpen);
// Edit: the draft's words in a box on the card, until Save or Cancel.
const [editing, setEditing] = useState<string | null>(null);
// Drafts in training: keep what you sent as an example when you changed it first.
diff --git a/packages/ui/src/components/briefing/RightNow.tsx b/packages/ui/src/components/briefing/RightNow.tsx
index e8ca34f0..ebfe3f3d 100644
--- a/packages/ui/src/components/briefing/RightNow.tsx
+++ b/packages/ui/src/components/briefing/RightNow.tsx
@@ -1,19 +1,34 @@
"use client";
-import { useState } from "react";
+import { useEffect, useState } from "react";
import ReactMarkdown from "react-markdown";
import remarkGfm from "remark-gfm";
-import type { Today } from "@/lib/api";
+import { ReplyCardItem, type useReplyCards } from "@/components/RepliesWaiting";
+import Button, { buttonClass } from "@/components/ui/Button";
+import { getMail, replyToMail, type MailView, type Today } from "@/lib/api";
import { MEMORY_ACTIONS, briefingMemoryLine } from "@/lib/briefing-memory";
-import { alsoInLine, clockLabel, isNewSince, newSinceLabel, type TimedPoint } from "@/lib/rightNow";
+import {
+ alsoInLine,
+ clockLabel,
+ isNewSince,
+ newSinceLabel,
+ pointTarget,
+ type PointTarget,
+ type TimedPoint,
+} from "@/lib/rightNow";
+import { mailboxName, safeGmailLink } from "@/lib/replyCards";
import { buildNarrativeSeed, type ContinueHandler } from "./shared";
// Right now: the Executive's live read of the day (the /today header, which
// is rewritten as things change), shown as a card at the top of Home with
// the whole picture in a side panel. Points that appeared since the reader
-// last looked today get a green dot.
+// last looked today get a green dot. A point about an email in your own
+// inbox has View email and Reply under it: View opens the email right there
+// (GET /delegation/mail), with the reply card already on its conversation;
+// Reply writes one (POST /delegation/mail/reply) and shows it to send,
+// change or edit. A point about a card in Needs you has Show me.
// How many points the Home card shows; the panel has them all.
const CARD_POINTS = 3;
@@ -33,15 +48,34 @@ function plainText(text: string): string {
return text.replace(/\*\*|__|`/g, "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").trim();
}
+type Replies = ReturnType<typeof useReplyCards>;
+
+// What a point's buttons need from Home.
+export interface PointActions {
+ replies?: Replies;
+ onShowAlert?: (alertId: number) => void;
+ onContinue?: ContinueHandler;
+ // A point with nothing to open is a button that talks it through (the
+ // panel), or plain text (the Home card).
+ plainRows?: boolean;
+}
+
function PointRow({
point,
isNew,
- onContinue,
+ actions,
}: {
point: TimedPoint;
isNew: boolean;
- onContinue?: ContinueHandler;
+ actions?: PointActions;
}) {
+ const [open, setOpen] = useState<"view" | "reply" | null>(null);
+ const target = pointTarget(point);
+ const onContinue = actions?.onContinue;
+ const text = plainText(point.text);
+ const talk = onContinue
+ ? () => onContinue(buildNarrativeSeed(text), briefingMemoryLine(MEMORY_ACTIONS.narrative, text))
+ : undefined;
const when = clockLabel(point.since);
const body = (
<>
@@ -56,24 +90,183 @@ function PointRow({
{when && <span className="flex-shrink-0 pt-0.5 text-xs tabular-nums text-fg-muted">{when}</span>}
</>
);
- if (!onContinue) {
- return <li className="flex items-start gap-2.5 border-t border-line py-2 first:border-t-0">{body}</li>;
+ // No email or card behind it: the whole row talks it through, as before.
+ if (!target || (target.kind === "alert" && !actions?.onShowAlert) || (target.kind === "mail" && !actions?.replies)) {
+ if (!talk || actions?.plainRows) {
+ return <li className="flex items-start gap-2.5 border-t border-line py-2 first:border-t-0">{body}</li>;
+ }
+ return (
+ <li className="border-t border-line first:border-t-0">
+ <button
+ type="button"
+ onClick={talk}
+ aria-label={`Discuss: ${text}`}
+ className="-mx-2 flex w-[calc(100%+1rem)] items-start gap-2.5 rounded-xl px-2 py-2 text-left transition hover:bg-accent/10 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
+ >
+ {body}
+ </button>
+ </li>
+ );
}
- const text = plainText(point.text);
return (
- <li className="border-t border-line first:border-t-0">
- <button
- type="button"
- onClick={() => onContinue(buildNarrativeSeed(text), briefingMemoryLine(MEMORY_ACTIONS.narrative, text))}
- aria-label={`Discuss: ${text}`}
- className="-mx-2 flex w-[calc(100%+1rem)] items-start gap-2.5 rounded-xl px-2 py-2 text-left transition hover:bg-accent/10 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
- >
- {body}
- </button>
+ <li className="border-t border-line py-2 first:border-t-0">
+ <div className="flex items-start gap-2.5">{body}</div>
+ {target.kind === "mail" && open ? (
+ <MailPanel
+ target={target}
+ replies={actions!.replies!}
+ startWithReply={open === "reply"}
+ onTalk={talk}
+ onClose={() => setOpen(null)}
+ />
+ ) : (
+ <div className="ml-[18px] mt-2 flex flex-wrap gap-2">
+ {target.kind === "mail" ? (
+ <>
+ <Button size="sm" onClick={() => setOpen("view")}>View email</Button>
+ <Button size="sm" onClick={() => setOpen("reply")}>Reply</Button>
+ </>
+ ) : (
+ <Button size="sm" onClick={() => actions!.onShowAlert!(target.alertId)}>Show me</Button>
+ )}
+ {talk && <Button size="sm" onClick={talk}>Talk it through</Button>}
+ </div>
+ )}
</li>
);
}
+type MailTarget = Extract<NonNullable<PointTarget>, { kind: "mail" }>;
+
+// One email opened from its point: what they wrote, their files, what you
+// last wrote to them, and the reply card for it (the one already open on
+// the conversation, or one written when you tap Reply).
+function MailPanel({
+ target,
+ replies,
+ startWithReply,
+ onTalk,
+ onClose,
+}: {
+ target: MailTarget;
+ replies: Replies;
+ startWithReply: boolean;
+ onTalk?: () => void;
+ onClose: () => void;
+}) {
+ const [mail, setMail] = useState<MailView | null>(null);
+ const [error, setError] = useState<string | null>(null);
+ const [cardId, setCardId] = useState<number | null>(target.cardId);
+ const [writing, setWriting] = useState(false);
+ const { refresh } = replies;
+ const { threadId, messageId } = target;
+
+ const reply = async () => {
+ setWriting(true);
+ setError(null);
+ try {
+ const id = await replyToMail(threadId, messageId);
+ await refresh();
+ setCardId(id);
+ } catch (err) {
+ setError(err instanceof Error ? err.message : "Couldn't write that reply.");
+ } finally {
+ setWriting(false);
+ }
+ };
+
+ useEffect(() => {
+ const controller = new AbortController();
+ getMail(threadId, messageId, controller.signal)
+ .then((m) => {
+ setMail(m);
+ if (m.reply_card_id !== null) setCardId(m.reply_card_id);
+ // Reply tapped on the point: write it once the email is open, unless
+ // a card is already there.
+ else if (startWithReply && target.cardId === null) void reply();
+ })
+ .catch((err: unknown) => {
+ if (controller.signal.aborted) return;
+ setError(err instanceof Error ? err.message : "Couldn't open that email.");
+ });
+ return () => controller.abort();
+ // Opened once per email; `reply` and the flags are read as they were then.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [threadId, messageId]);
+
+ const card = cardId !== null ? replies.cards.find((c) => c.decision_id === cardId) : undefined;
+ const link = mail ? safeGmailLink(mail.link) : "";
+ const files = mail?.attachments ?? [];
+ const who = mail ? mail.from_name.trim() || mail.from_email : "";
+ const others = mail ? mail.cc.map((a) => a.split("@")[0]).join(", ") : "";
+ return (
+ <div className="ml-[18px] mt-2 rounded-xl border border-line bg-surface p-3">
+ {!mail && !error && <p className="animate-pulse text-sm text-fg-muted">Opening the email…</p>}
+ {mail && (
+ <>
+ <p className="text-sm">
+ <span className="font-semibold text-fg">{who}</span>
+ <span className="text-fg-muted">
+ {" "}· to you{others ? `, cc ${others}` : ""}
+ {clockLabel(mail.received_at) ? ` · ${clockLabel(mail.received_at)}` : ""}
+ </span>
+ </p>
+ {mail.subject && <p className="mt-0.5 text-sm text-fg-muted">{mail.subject}</p>}
+ <p className="mt-2 whitespace-pre-line break-words text-[15px] text-fg">{mail.text || "(No words, just the files.)"}</p>
+ {(files.length > 0 || mail.has_attachments) && (
+ <div className="mt-2 flex flex-wrap gap-2">
+ {files.length > 0 ? (
+ files.map((f, i) => (
+ <span key={`${i}-${f.name}`} className="rounded-lg border border-line px-2.5 py-1 text-sm text-fg">
+ 📎 {f.name}
+ </span>
+ ))
+ ) : (
+ <span className="text-sm text-fg-muted">📎 Has attachments</span>
+ )}
+ </div>
+ )}
+ {mail.their_last_words && (
+ <p className="mt-2 text-sm text-fg-muted">
+ Replying to you: &ldquo;{mail.their_last_words.replace(/\s+/g, " ").slice(0, 160)}
+ {mail.their_last_words.length > 160 ? "…" : ""}&rdquo;
+ </p>
+ )}
+ </>
+ )}
+ {card ? (
+ <div className="mt-3">
+ <ReplyCardItem
+ card={card}
+ onGone={(id, note) => {
+ replies.gone(id, note);
+ setCardId(null);
+ }}
+ onRefresh={replies.refresh}
+ onChanged={replies.replace}
+ defaultOpen
+ />
+ </div>
+ ) : writing ? (
+ <p className="mt-3 animate-pulse text-sm text-fg-muted">Writing a reply…</p>
+ ) : null}
+ {error && <p className="mt-2 text-sm text-rose-600 dark:text-rose-300">{error}</p>}
+ <div className="mt-3 flex flex-wrap gap-2">
+ {!card && mail && !writing && (
+ <Button size="sm" variant="primary" onClick={() => void reply()}>Reply</Button>
+ )}
+ {link && (
+ <a href={link} target="_blank" rel="noopener noreferrer" className={buttonClass("secondary", "sm")}>
+ Open in {mailboxName(link)}
+ </a>
+ )}
+ {onTalk && <Button size="sm" onClick={onTalk}>Talk it through</Button>}
+ <Button size="sm" variant="ghost" onClick={onClose}>Close</Button>
+ </div>
+ </div>
+ );
+}
+
function Lead({ today }: { today: Today }) {
const lead = today.narrative_lead;
if (lead) return <p className="text-[17px] font-semibold leading-snug text-fg">{lead}</p>;
@@ -94,11 +287,13 @@ export function RightNowCard({
baseline,
updatedLabel,
onOpen,
+ actions,
}: {
today: Today;
baseline: Date | null;
updatedLabel: string | null;
onOpen: () => void;
+ actions?: PointActions;
}) {
const points = today.narrative_points ?? [];
const badge = newSinceLabel(points, baseline);
@@ -126,7 +321,12 @@ export function RightNowCard({
{points.length > 0 && (
<ul className="mt-2">
{points.slice(0, CARD_POINTS).map((p, i) => (
- <PointRow key={`${i}-${p.text}`} point={p} isNew={isNewSince(p, baseline)} />
+ <PointRow
+ key={`${i}-${p.text}`}
+ point={p}
+ isNew={isNewSince(p, baseline)}
+ actions={actions ? { ...actions, plainRows: true } : undefined}
+ />
))}
</ul>
)}
@@ -167,10 +367,12 @@ export function RightNowBody({
today,
baseline,
onContinue,
+ actions,
}: {
today: Today;
baseline: Date | null;
onContinue?: ContinueHandler;
+ actions?: PointActions;
}) {
const [showMorning, setShowMorning] = useState(false);
if (!today.narrative) {
@@ -189,7 +391,7 @@ export function RightNowBody({
const list = (items: TimedPoint[], isNew: boolean) => (
<ul>
{items.map((p, i) => (
- <PointRow key={`${i}-${p.text}`} point={p} isNew={isNew} onContinue={onContinue} />
+ <PointRow key={`${i}-${p.text}`} point={p} isNew={isNew} actions={{ ...actions, onContinue }} />
))}
</ul>
);
diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.ts
index dbda3007..f9570eb1 100644
--- a/packages/ui/src/lib/api.ts
+++ b/packages/ui/src/lib/api.ts
@@ -2613,6 +2613,43 @@ export async function getReplyCards(signal?: AbortSignal): Promise<ReplyCard[] |
return body.cards;
}
+// One email in your own mailbox, as Right now opens it (GET /delegation/mail).
+export interface MailView {
+ thread_id: string;
+ message_id: string;
+ subject: string;
+ from_name: string;
+ from_email: string;
+ to: string[];
+ cc: string[];
+ received_at: string;
+ text: string;
+ attachments: { name: string; mime_type: string; size: number }[];
+ has_attachments: boolean;
+ their_last_words: string;
+ link: string;
+ reply_card_id: number | null;
+}
+
+export async function getMail(threadId: string, messageId: string, signal?: AbortSignal): Promise<MailView> {
+ const q = new URLSearchParams({ thread_id: threadId, message_id: messageId });
+ const res = await fetch(`${API_BASE}/delegation/mail?${q}`, { signal });
+ if (!res.ok) throw await delegationError(res, "Couldn't open that email.");
+ return (await res.json()) as MailView;
+}
+
+// A reply to one email, on a card for you (the conversation's open card
+// when there is one). Sends nothing.
+export async function replyToMail(threadId: string, messageId: string): Promise<number> {
+ const res = await fetch(`${API_BASE}/delegation/mail/reply`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ thread_id: threadId, message_id: messageId }),
+ });
+ if (!res.ok) throw await delegationError(res, "Couldn't write that reply.");
+ return ((await res.json()) as { decision_id: number }).decision_id;
+}
+
// Why a Send didn't go: the backend's code (draft_gone, you_replied,
// already_handled, send_unconfirmed, caller_signing_required, …) and what to
// tell you.
@@ -5337,6 +5374,17 @@ export interface NarrativePoint {
text: string;
// When the point first appeared today (ISO UTC).
since?: string | null;
+ // What the point is about, when Home can open it: an email in your own
+ // inbox, or a card in Needs you.
+ source?: PointSource | null;
+}
+
+export interface PointSource {
+ kind: "mail" | "alert";
+ message_id?: string | null;
+ thread_id?: string | null;
+ decision_id?: number | null;
+ alert_id?: number | null;
}
export interface MorningBriefItem {
diff --git a/packages/ui/src/lib/rightNow.ts b/packages/ui/src/lib/rightNow.ts
index 403abb47..e1d97620 100644
--- a/packages/ui/src/lib/rightNow.ts
+++ b/packages/ui/src/lib/rightNow.ts
@@ -8,6 +8,30 @@
export interface TimedPoint {
text: string;
since?: string | null;
+ source?: {
+ kind: "mail" | "alert";
+ message_id?: string | null;
+ thread_id?: string | null;
+ decision_id?: number | null;
+ alert_id?: number | null;
+ } | null;
+}
+
+/** What a point's buttons open: an email (by its ids), a card in Needs you,
+ * or nothing (the point is only talked through). */
+export type PointTarget =
+ | { kind: "mail"; threadId: string; messageId: string; cardId: number | null }
+ | { kind: "alert"; alertId: number }
+ | null;
+
+export function pointTarget(point: TimedPoint): PointTarget {
+ const s = point.source;
+ if (!s) return null;
+ if (s.kind === "mail" && s.message_id && s.thread_id) {
+ return { kind: "mail", threadId: s.thread_id, messageId: s.message_id, cardId: s.decision_id ?? null };
+ }
+ if (s.kind === "alert" && typeof s.alert_id === "number") return { kind: "alert", alertId: s.alert_id };
+ return null;
}
/** "2:31 PM" in the browser's zone, or null for a missing/bad time. */