Skip to content

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

feat(ui): let the help panel answer questions about any part of the app (#494)

Rufus5f734e3210a4
diff --git a/packages/core/openexecutive/api/routes/chat.py b/packages/core/openexecutive/api/routes/chat.py
index 6ec12f6d..d87aaa06 100644
--- a/packages/core/openexecutive/api/routes/chat.py
+++ b/packages/core/openexecutive/api/routes/chat.py
@@ -712,16 +712,20 @@ def _build_page_context_block(page_context: PageContext | None) -> str:
lines.append(page_context.summary)
if page_context.guide_section_id:
- from openexecutive.guide.prebuilt import get_prebuilt
+ from openexecutive.orchestrator.guide_tools import section_markdown
- section = get_prebuilt(page_context.guide_section_id)
- markdown = (section or {}).get("markdown", "")
+ markdown = section_markdown(page_context.guide_section_id)
if markdown:
lines.append("")
lines.append(
f"USER GUIDE FOR THIS PAGE ({page_context.guide_section_id}):"
)
lines.append(markdown)
+ lines.append("")
+ lines.append(
+ "For any other part of the app, read its section with read_user_guide "
+ "before answering how it works."
+ )
if page_context.form is not None:
form = page_context.form
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index ad5d7bdd..5b52172f 100644
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@ -361,7 +361,7 @@ caching:
audit rows as a direct call. use_tool accepts only names in
tool_groups.DEFERRED; anything else, or input that is not an object,
gets an error tool result. The everyday tools (consult_specialist,
- propose_form_values, people and memory lookups, follow-ups, the MCP
+ propose_form_values, read_user_guide, people and memory lookups, follow-ups, the MCP
meta-tools) stay direct. This cut the direct list from about 19.5k to
about 6-7k tokens, which every model call of a turn re-sends.
rag_context_placement: User turn (NOT the system prompt) — RAG hits vary per query, would poison the cache if cached.
diff --git a/packages/core/openexecutive/architecture/prebuilt/agents.json b/packages/core/openexecutive/architecture/prebuilt/agents.json
index a79c6292..9e149723 100644
--- a/packages/core/openexecutive/architecture/prebuilt/agents.json
+++ b/packages/core/openexecutive/architecture/prebuilt/agents.json
@@ -1,7 +1,7 @@
{
"section_id": "agents",
"title": "Agent Council",
- "markdown": "The Executive (`openexecutive.orchestrator.executive.Executive`) is a single coherent persona that fans out to specialist sub-agents via Anthropic tool use. Each specialist subclasses `openexecutive.agents.base.BaseAgent`, carrying a `name`, `domain`, and `model`, and exposes `analyze(...)`, which wraps the question in user-turn context and calls Claude through the per-call provider. That context is per call and never cached: `<company_stage>` (the stage from the company profile — specialists never see the profile itself), in solo mode `<principal_role>` (what kind of principal the advice is for, in plain words, with their title and remit — `router.principal_role_context`), `<department_memory>`, `<past_decisions>`, `<failure_cases>`, `<relevant_knowledge>` and `<conversation_context>`, outermost first. The specialist's own system prompt is a static domain constant under one `cache_control` block, so it stays byte-identical across companies and profile edits. A chat turn takes the stage from its session's profile (the one the Executive reasons over, and the one an eval scenario injects); workflow steps and the MCP server's `consult_specialist` read it fresh from the profile on disk. The role tag follows the turn's mode: a chat turn pins the role on its session with the mode (`pin_turn_principal_role`: the session's `principal_role` override, else the workspace settings) and sends it in solo and nothing in team, so the org block, every specialist in the turn and any workflow the turn starts see the same role; callers with no chat turn read it fresh (`load_principal_role`: the current session's mode and role, else the workspace's), and a failed read sends no tag rather than failing the consult. The CFO, CSO and sales prompts key their advice on it: for a bootstrapped, self-funded or solo company they drop venture fundraising benchmarks and work from cash, and raise only if the founder wants to.\n\nRouting uses one `consult_specialist` tool. When to call it is spelled out in the persona's Domain Expertise section (\"Going deeper\") and in the tool's own description: any question that asks for judgment in a specialist's area (a decision, plan, analysis, negotiation, hire, contract term, pricing or fundraising move, board message, or a department's own targets and stance, since the specialist holds that department's memory) is consulted before the answer, several at once across areas; lookups in mail, calendar or documents, scheduling, status checks, routine drafting and questions about how the Executive works are answered without one. Chat eval scenarios hold this: `required_routing` names specialists the turn must consult and `no_routing: true` says it must consult none, and the runner fails a scenario that misses either (`evals.scenarios.routing_check`). Beside it the Executive carries two skill tools, `search_skills` and `load_skill` (skills are shown to users as **playbooks**, and every playbook belongs to a workflow: one that follows it, or its own Quick workflow). Chat finds and reads playbooks but never creates or changes one: work worth repeating is offered as a workflow through `draft_workflow`, with the method written into its steps, because workflows read playbooks at run time (approved scheduled ones included) and this loop also runs on inbound email and chat, so only a person can change what a workflow follows. A hidden built-in is invisible to search and load; each `search_skills` hit lists the `workflows` that follow it, Quick ones included, and the persona routes \"the finished deliverable\" to that workflow and quick or partial asks to the playbook inline; Tool calls made while proactive work is tagged (scheduler dispatch, reflection, research, alert review) feed the Attunement outcome ledger. Goals have three tools: `list_department_goals`, `update_department_goal` (progress the user reports) and `create_goal` (a new goal the principal states, filed under an area by slug or title and creating the area when none matches — see Org). `create_goal` runs only for the principal on a verified surface, and no unattended run is offered it: the tools in `schedule_tools.UNATTENDED_WITHHELD_TOOLS` are dropped from reflection's and research's toolkits by `unattended_toolkit`, and from the chat loop when its Session is marked `unattended` — the scheduler's PROACTIVE TRIGGER run, whose prompt quotes stored intent text; a call the model emits anyway gets an error tool_result. `record_decision_outcome` records how a past decision turned out — the weekly review lists decisions older than 30 days with no outcome as `[decision N]` — writing `decisions.outcome` (`episodic.update_decision`) and auditing the rationale; it has `create_goal`'s gate (the principal on a verified surface only; everyone else gets an audited refusal) and is in `UNATTENDED_WITHHELD_TOOLS` too. A missing or unknown id returns the decisions still waiting on an outcome, so the model can retry with the right one. Its schema is static; the solo persona has one line on it, and team mode learns it from the tool description, so the team persona is byte-identical. Attunement adds `list_open_loops` (what a person owes — everyone's for the principal only in a private conversation, otherwise the caller's own) and `close_open_loop`, which only closes a loop when the turn's resolved speaker is the principal or the loop's owner — an unrostered sender, a signed-in web user not on the roster, and unattended sessions are refused. `assign_open_loop` opens one on request (\"ask Ben to send me the Q3 numbers by Friday\") for the principal or a rostered teammate on a verified surface — never an email, a turn private to the principal or an unattended run, which are also withheld the tool — and only when `task` appears verbatim in what the speaker typed this turn, at most 5 per turn; that turn's extraction pass then opens no second loop for the same owner. The owner is told once on their own channel when someone else assigns it, and the result's `notified` says how that went, so the Executive reports it rather than messaging them as well. The roster write tools (`upsert_person`, `archive_person`, `set_department_head`) are the principal's alone, and only on a surface that verified the speaker — the web chat, the principal's own Slack or Discord, or a private Telegram chat when `TELEGRAM_WEBHOOK_SECRET` is set to a value Telegram can send (Telegram identifies the chat rather than the sender, and without that secret its webhook accepts anyone's update). A teammate, an email (even from the principal's address), Google Chat, the CLI, the MCP server and unattended runs get `status: refused` (audited, and no action chip), because a team member's People row is also the web sign-in and outbound-email allow-list. `upsert_person` takes `kind` (`team` / `contact`; a new person defaults to `contact` in solo mode, an update keeps the current kind) and `email_aliases` (other addresses the person writes from — the full list, replacing the current one; they match mail and may be emailed but never sign in, and one already on someone else is refused), and after every write any pending roster request whose sender now matches someone is closed and its held messages replayed. `resolve_roster_request` answers a **roster request** — someone not on the People list who wrote in and is waiting (see Org): `approve` (a new person; `kind` defaults to team for a company-domain sender, else contact, when the principal did not say), `link` (someone already listed, by `person_id`; `replace_channel_id` only when the principal said so) or `decline`. It has the roster tools' gate (the principal on a verified surface; audited refusal otherwise), is in `UNATTENDED_WITHHELD_TOOLS`, and answers only an id in `Session.trusted_roster_request_ids` — the ids the server printed that turn in a `<roster_requests>` block (`briefing.context.format_roster_requests_for_prompt`, up to 10 pending requests), which `render_and_trust` appends to the `<briefing>` digest on the principal's own verified turn only and records on the session in the same step, so an id the model invents or reads out of a message adds nobody. Each line is server-derived — id, channel, address or account id, the sender's name sanitised and marked unverified, a company-domain hint, the message count — and never what they wrote. The block rides in the **user turn**, like the digest, so the cached system blocks are unchanged; the tool definition is static, and the new tool only extends the sorted tool list. The web chat route resets the trusted set every turn, and a resolved id is removed from it. and `list_people` returns both kinds with `kind` — contacts only on the principal's own verified turn (they are private to the principal; anyone else gets the team as if no contact existed) — while `lookup_person` searches the team only. `ask_about_person` reads a person's peer memory fully only on their own verified turn; anyone else's answers only to a verified principal or teammate, and only when that person turned on \"Share my work style with the team\", framed to how they work and never their view of a colleague, and otherwise returns the same \"hasn't chosen to share\" result whether or not anything is known. A teammate's own mail with the Executive is theirs the same way: every mailbox call the model makes through the MCP gateway (Gmail or Outlook, by `call_tool`, from a script, or a workflow step run from chat) passes through `orchestrator.teammate_mail`. A search excludes every other teammate's address server-side, except on mail the reader is also on, and is filtered again entry by entry; any other call that names a message or thread (read, attachment, reply, forward, label) must use an id a filtered search returned to the same reader in this conversation (`Session.mail_ids_seen`) or the inbound email the turn answers; reads are filtered message by message, so a message naming another teammate is left out unless the reader is in its From / To / Cc; a reply that would quote such a thread, or an Outlook forward, reply or attachment read of such a message, is refused; and a conversation in which a teammate other than the principal was shown their own mail becomes theirs alone, as Act as me's do. Outside mail and the reader's own are untouched; an email turn reads as its sender only when Gmail authenticated it, and any other unverified reader sees no teammate's mail, a background run the model drives reads as the principal and a workflow step outside any session as nobody, an Outlook inbox rule that forwards or names another teammate is refused, and the poller and the brief, which read the mailbox themselves, are unaffected. Their own chats are theirs too: every audit row of a teammate's verified turn is theirs (`people_tools.teammate_turn_owner`, see Audit; the principal sees the actions, never the words), and a teammate's web chat or DM opens for them alone (`chat._session_access`), the principal included. The same verified-principal rule, as `people_tools.contacts_reachable_now()`, decides whether a turn may reach a **contact** at all: `message_person`, the raw DM tools, `create_calendar_event` / `create_instant_meeting` attendees and the MCP gateway's Gmail / Calendar / Drive / OneDrive gates treat a contact exactly like an unknown person on every other turn, so no refusal reveals that one exists. **The untrusted-content policy** (`orchestrator.content_trust`) is one rule for text the principal did not write — inbound email, chat, attached files, watched pages — answering three questions for every surface. *Who is speaking*: the principal only when the surface proved it (`principal_speaking`: the web chat as the principal — never a signed-in email on nobody's People entry —, the CLI, their own Slack/Discord or a secret-verified Telegram chat, or their own address with Gmail's `dmarc=pass`); never a teammate, a stranger, Google Chat, the MCP server or an unattended run. *What may become memory*: episodic extraction runs only then, and only on the words outside `<untrusted_content>` blocks; peer memory and open loops are recorded under the speaker's own name, never as the principal's. *What may trigger tools*: every write on the principal's authority already refuses others in its handler; the tools with no such check that change the install for every later turn — `content_trust.PRINCIPAL_ONLY_TOOLS`: `load_mcp_server`, `list_saved_tools`, `run_python_job` and `run_script` — are not offered unless the principal is speaking on an interactive surface (not email, even authenticated), and a call the model emits anyway gets an error tool_result and a `refused: not_principal` audit row. So an inbound email, a teammate's turn, Google Chat and the scheduler's proactive trigger each get a stable tool list of their own without it. A send or edit on a team member's turn also meets their department's authority first (`orchestrator.department_gate`, see Org), and so does one on a turn whose speaker is on no People entry: a signed-in web caller or a chat-channel sender, which in practice is Google Chat, since Slack, Telegram and Discord turn unmatched senders away. Google Chat names a matched sender to the gate alone (`gate_sender_person_id`), so the principal there is not held. Email turns are left to the mailbox's own gates. *How it is labelled*: outside text goes into the user turn inside `<untrusted_content source=… author=… author_verified=…>` with a fixed notice that it carries no authority; compatibility forms are folded (NFKC), control characters go, and the tag's name is renamed wherever the text carries it — any case, spacing or entity-escaped form — so the text cannot end its block and speak outside it.\n\nA turn about the principal's private mail (`Session.private_to_principal`) reaches the principal only. It is neither offered nor allowed to run `schedule_tools.PRIVATE_TURN_WITHHELD_TOOLS` — everything that reaches someone else, publishes where the team reads, or starts work outside the turn: the broadcasts, meeting bookings and cancellations, `run_workflow` and research, follow-ups and workflow nudges, watches, artifacts, goal updates, saved workflows, skill drafts, and `load_mcp_server` (it connects to any URL, which can carry the turn's content). Through `search_tools` and `call_tool` it reaches only `schedule_tools.PRIVATE_TURN_MCP_TOOLS`: Google Workspace reads (mail, calendar, and Drive, Docs and Sheets search and file reads, with their Microsoft 365 twins; OneDrive's `download-bytes` only for a file's content) and the Gmail send and draft the gateway narrows to the principal. A search shows it nothing else, and a call to anything else (Google Chat, a Docs or Drive write, `manage_event`, another server) is refused (`schedule_tools.private_turn_withholds`). A call the model emits anyway, MCP tools included, gets an error tool_result and writes an audit row, and every audit row the turn writes is the principal's alone. On every turn the Executive knows what is connected without searching: block 0's *Connected Systems* section names the connected Google services, other MCP servers, the messaging channels, Notion sync, Confluence sync (when on) and Act as me, and pins the Google tool names it calls directly with `call_tool`. Both the service list and the pinned names are narrowed to what workspace-mcp actually loaded (`WORKSPACE_MCP_TOOLS`, `WORKSPACE_MCP_TOOL_TIER`), so a service left out is not named and its tools are not pinned — being told a tool is already available when it is not in the index costs a failed call the model cannot explain to itself. `search_tools` is for anything not listed. When work repeats over many items, the Executive can also call `run_script` (`workflows/step_script.py`, offered when the gateway runs, unless `CHAT_SCRIPTS=false`, and only on the principal's own turns — `PRINCIPAL_ONLY_TOOLS`, withheld on an unattended pass too, because it spends the turn's whole call budget on code the model just wrote): one short Python script, run in a sandboxed Monty worker with no files, network or environment, whose only reach is the gateway tools `call_tool` could reach (those `search_tools` has returned; the gateway keeps that set for its own process-wide session, not per conversation). Each call it makes is a `call_tool` in every way that matters — the gateway's discovery, deny-list and recipient gates, Take the lead's gate on an unattended run (or the department gate on a team member's turn, see Org), and the same action chip and `tool_invocation` row (marked `via: run_script`, `ok: false` when it raised), as each call happens; the script itself gets a `kind: script` row with its source and result. Its wall clock is half the turn's deadline, so a long script ends with the list of calls it made rather than being cut off with the turn, and a stopped turn closes it and its worker. A turn private to the principal is not offered it, and the Act as me lockdown withholds it whole. Besides gateway tools, a chat script may call a fixed list of the Executive's own tools (`step_script.CHAT_OWN_TOOLS`: reads, alerts, open loops, goals, the watch list, follow-ups, `message_person`, `upsert_person` — nothing that broadcasts, books calendars, edits memory or skills, or starts workflows or research), each only when the turn is offered it and through the turn's own handler (Take the lead's gate included), with the same chip and a `kind: skill`, `via: run_script` audit row. A direct call needs a `tool_use` each, so a turn's scripts share a budget instead: `CHAT_SCRIPT_MAX_CALLS` (default 200) calls in all, and per-turn caps on own tools that could otherwise act in bulk (`CHAT_OWN_TOOL_CAPS`: `message_person` 10 — messaging the whole roster would be a broadcast — `upsert_person` 25, `create_alert` 50); a refused call tells the model to say what is left. A call stopped mid-flight by the script's clock or the turn still gets a `cancelled` audit row, since it may have run. Because every round re-reads the conversation, the loop also nudges at the moment of choice: after a round whose results include a list of five or more items (`step_script.lists_many`), with `run_script` on offer and not used that round, it adds the constant `FANOUT_HINT` as a text block in that round's user message (never a cached block), once a turn, pointing the per-item work at one built tool. For library work on files (PDFs, spreadsheets, charts, images) the chat also has `run_python_job` (see Workflows → Python jobs): Python with a fixed library set in a Deno-isolated WebAssembly sandbox, fed Knowledge files by name, the message's own attachments as sent, or text it already holds, and able to keep a job that worked as a Custom tool, with result files linked for the principal to download; it is offered only on the principal's own turns and only where the sandbox is installed (not offered otherwise, so the tool prefix stays fixed per process). Agent Activity shows each run as one \"Built tool\" card (debug event `script_run`: ok, the calls it made, how many, how long, and the kept or reused tool's name). The persona's tool-building section is present only when chat scripts can actually run (the setting and Monty installed). `TOOL_BUILDING_ADDENDUM` in the cached persona tells the Executive when to build a tool — a job that looks something up and then checks or acts on each result, paged results, more than about ten items, or an answer that needs three or more reads (find, open, read; the tool returns only what answers the question, not whole documents, and only what is about to be edited or quoted at length is read in full), while a handful of items already named go as direct calls in one turn — and never to say it has none, and to talk about it as building a tool or doing it in one go. On the principal's own verified, interactive turns, a script that works can be saved as a named tool (`save_as`; elsewhere the script runs but is not saved) and run again with `run_script(tool=…, inputs=…)`; `list_saved_tools` (a constant definition, in `PRINCIPAL_ONLY_TOOLS` with `load_mcp_server`, so offered only while the principal is speaking on a verified, interactive surface; `run_script(tool=…)` is refused on any other turn) lists them, and each call a saved tool makes is a gateway call like any other (see Workflows → Saved tools). The tool's definition is a constant, so the cached tool prefix does not move. Multiple parallel `tool_use` blocks in a single assistant turn fan out concurrently through `router.route_parallel`, each running its own domain-filtered ChromaDB query (3 built-in and 2 company chunks by default, see the RAG section) before the specialist sees the question. The fan-out is failure-isolated per call: a specialist that raises or returns no text becomes an `UNAVAILABLE` tool_result (`router.specialist_unavailable_result`) instead of failing the whole turn, and its area — \"finance\", \"legal\", never the specialist's name — is reported to the user under the web reply, or by the Executive in its reply on other channels, unless another call to it answered that turn. A failed specialist does not count as consulted, so it takes no committee seat. Cancellation (Stop) still propagates. The Executive then synthesizes the returned analyses into one reply.\n\n`remember_fact`, `forget_fact` and `update_company_profile` (`orchestrator/fact_tools.py`) make a correction stick: the first two keep or retire a standing fact in `memory.facts`, and the third changes one field of the company profile. They share `record_decision_outcome`'s gate (the principal on a verified surface, an audited refusal for everyone else) and are in `UNATTENDED_WITHHELD_TOOLS`. `remember_fact` alone also admits a rostered teammate on a verified surface (web signed in, their own Slack or Discord): the fact is stored attributed (`recorded_by_role=\"teammate\"`, rendered `(per <name>)`), and is held as a `proposed` row (`awaiting_approval`) until the principal approves it, unless the principal marked that teammate trusted (\"needs my approval\" off; on by default) — and even then when it would replace the principal's fact. All three are also in `PRIVATE_TURN_WITHHELD_TOOLS`, since what they write or retire is read on everyone's turns. On the principal's own authenticated email (primary address, with Gmail's own `Authentication-Results` reporting `dmarc=pass`, not forwarded) the three tools check the request as usual, then hold it as `awaiting_confirmation`. It applies only when the principal replies to a one-time token emailed to their own address (`integrations.fact_confirmation`); the split into a check step and an `apply_*` step lets chat and the confirmed reply share one apply path. Each write also needs a `source_quote` found in the speaker's own words this turn. The active facts reach every specialist as a `<standing_facts>` user-turn tag: `route_to_specialist` reads them (None → the store, \"\" → none) for chat consults and workflow steps alike, and `BaseAgent.analyze` places the tag next to `<past_decisions>`, never in the cached specialist system prompt.\n\nThe ten entries in `SPECIALIST_REGISTRY` (`openexecutive.orchestrator.router`):\n\n| Key | Agent | Domain |\n| --- | --- | --- |\n| `cso` | `StrategyAgent` | strategy |\n| `cfo` | `FinanceAgent` | finance |\n| `chro` | `HRAgent` | hr |\n| `gc` | `LegalAgent` | legal |\n| `coo` | `OperationsAgent` | operations |\n| `cmo` | `MarketingAgent` | marketing |\n| `cpo` | `ProductAgent` | product |\n| `sales` | `SalesAgent` | sales |\n| `board_comms` | `BoardCommsAgent` | board |\n| `triage` | `TriageAgent` | triage |\n\nModels: specialists default to `claude-sonnet-5-5`; the deep-reasoning tier (CSO, CFO, GC, Board) runs on `DEEP_REASONING_MODEL`, `claude-sonnet-5-5` by default, with adaptive thinking; routing/fast classification uses `claude-haiku-5-5`. Requests are fitted to the model's generation on the way out (`feature_gate.fit_claude_generation`): 5-generation Claude models never receive `temperature` / `top_p` / `top_k`, and Haiku 5.5, which thinks unless told otherwise, gets thinking turned off when the caller asked for none. The Council's **Deep reasoning** toggle is honoured on Claude Opus/Sonnet (direct or via OpenRouter) and on any OpenRouter model whose live catalog entry supports `reasoning` (today all OpenAI, Gemini, DeepSeek and Grok entries; not Llama) — the request translator turns Anthropic adaptive thinking + effort into OpenRouter's `reasoning` parameter. It is a silent no-op on models that can't reason, and disabled for Haiku, which rejects adaptive thinking. A PDF `document` block is translated too: it becomes an OpenAI `file` part, and OpenRouter requests carrying one add the `file-parser` plugin (`native` for models whose catalog entry lists `file` input, else `PDF_OPENROUTER_ENGINE`, default `mistral-ocr`). `FeatureSpec.supports_pdf_input` gates it per model — off for a local server unless `LOCAL_PDF_INPUT` — and a gated-off PDF becomes a text note rather than vanishing. The Council picks a model in two steps: a **Provider** dropdown (Anthropic, OpenAI, Google, Meta, DeepSeek, xAI, Local, …), then a **Model** dropdown limited to that provider, with readable names (\"Claude Opus 5.5\") and the raw id and serving route shown underneath. The Anthropic group combines the direct Claude models (`claude-fable-5-1`, `claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5-5`, `claude-sonnet-5`, `claude-haiku-5-5`, `claude-haiku-4-5`) with any Claude generation that exists only on OpenRouter, and never lists a model twice. With `OPENROUTER_ENABLED`, the non-Anthropic entries come from OpenRouter's live `/models` catalog (fetched at startup, refreshed in the background, filtered to tool-capable paid text models from an allowlisted vendor set), falling back to a built-in snapshot if the fetch fails. Every Council agent also takes **additional instructions** (`agent_overrides.instructions`): text appended after its prompt by `agents.overrides.append_instructions` inside an `<additional_instructions>` block. `BaseAgent.base_system_prompt()` is the built-in prompt or its full replacement (what the Council's editor shows); `effective_system_prompt()` is that plus the instructions (what every call sends), and the Executive gets the same text through `build_system_blocks(persona_instructions=…)`. Unlike a replaced prompt, instructions leave the agent on its built-in prompt, so prompt improvements keep reaching it. A **Quality** choice above the agents (`agents.presets`) sets every agent's model and deep reasoning at once: **Fast** puts every agent on a small model (`claude-haiku-5-5`, else `claude-haiku-4-5`) with deep reasoning off, **Balanced** returns each agent to its built-in defaults, and **Thorough** puts the Executive and the domain specialists on the largest allowed model (`claude-opus-5-5`, else `claude-opus-5`) with deep reasoning on where the model supports it, leaving triage and the helpers below on their defaults. Presets change quality only; they never cap spend. Each preset resolves against the install's model allowlist at request time and is offered only when one of its models is allowed. Applying one writes ordinary per-agent overrides (model and deep reasoning only), so history, rollback and later per-agent edits keep working; an agent changed on its own afterwards shows as **Custom**. Each Council agent has a **visibility**: `core` for the Executive and the domain specialists (`BaseAgent.visibility = \"core\"`, which a new specialist must declare) and `internal` (the default) for triage and the helper agents below. Thorough moves only core agents. The Council opens in a **simple view**: the Quality choice, the voice picker, and only the core agents, each with its additional instructions and a model badge. **Show all agents** lists the internal ones too, and **Advanced** opens the full page (the browser remembers the choice). Eight Council-only agents are model/prompt-overridable in the UI but NOT callable via `consult_specialist`, because they are deliberately kept out of `SPECIALIST_REGISTRY`: `quality_judge` (committee review), `utility_fast` (gates, titles, decision parsing), `research` (the `executive_research` fan-out), `fixture_generator` (invents demo companies), `engagement_intake` (models a real client from intake material), `onboarding_interviewer` (interviews a new user about their own company and drafts its profile, people and departments), `workflow_designer` (runs the conversational New workflow wizard on `/jobs/new`: searches the available tools, asks clarifying questions, then drafts a validated dynamic-workflow definition for the user to review), and `workflow_actor` (runs a workflow's `action` steps: a bounded tool-use loop limited to the tools the user approved for that step). `fixture_generator`, `engagement_intake` and `onboarding_interviewer` share one shape — a forced tool call producing a whole company, validated for referential integrity, with a single repair retry — but opposite epistemics: the fixture author invents, the other two extract and leave unstated facts empty rather than guessing. When the workspace is in solo mode, `onboarding_interviewer`'s first user turn is prefixed with a short hint (`interview.solo_hint(role_kind)`, one static constant per role kind from the onboarding role step): the draft names only the principal, as principal, and no departments; an owner is asked about the offer, customers, pricing, cash and runway, an in-house executive about their organisation (drafted as the company — their employer), function, remit, manager, team size as context and what they are measured on, an independent about their practice, clients and pricing, and with no role given the role-neutral `SOLO_HINT` asks which they are. The hint rides in the user turn and the tool array is unchanged, so the cached system prompt and tool prefix are the same in both modes.\n\n**Voice.** The Executive answers in one voice persona, substituted into block 0 at `{VOICE_PERSONA}` (`personas/loader.get_active_body`) from the Executive override's `voice_persona_slug`. Three general voices ship in `personas/builtin/`: **Direct** (`default`, the slug used when none is set: answer first, brief and decisive), **Supportive** (a warm coach who explains the why and checks how the plan sits) and **Analytical** (numbers first, options and trade-offs, then one recommendation). They are offered by a shared picker in setup (`/onboard`, after the workspace choice) and in Settings → Executive, which saves through `PATCH /agents/executive`; a built-in voice's frontmatter carries the picker's one-line `description` and `sample` reply. The named-executive voices are marked `legacy: true`: the picker hides them, but they still load, so an install that picked one keeps it, and the Agent Council lists them under \"Legacy voices\". Voice files hold disposition only; the response-length ladder lives in `prompts/executive_persona.py`, and a test keeps numeric length rules out of every voice file. An eval scenario may set `voice_persona` to answer in a voice; it rides on `Session.voice_persona_slug`, which wins over the override for that session only.\n\nOne more structured-output utility agent sits beside `triage`: `openexecutive.agents.alert_review.AlertReviewAgent` (routing model, one forced `emit_alert_reviews` tool call, never raises). The alert review job hands it a batch of open alerts with evidence and gets back, per alert, a verdict (relevant / changed / resolved / stale), a confidence, the evidence it relied on, a one-line note, why-now, an optional deadline, and a recommended move (none / route / nudge / escalate / draft / suggest_workflow / merge / close) with its parameters. Like `triage`, it never mutates state — `alerts.review.apply_verdict` executes the verdicts deterministically within authority, so the model's job is judgment, not action.\n\n**Solo mode.** When the workspace (or the turn's session) is solo — one person using Open Executive for themselves — the Executive works for that one person, the principal, whatever their role: they may run their own business, lead a function inside a larger organisation, or work independently, and the persona reads which from the context instead of assuming it — the role lines under \"Your Principal\" in the org block, when the principal gave their role (workspace settings: kind, title, reports to, remit, measured on). Its persona swaps the team sections (\"You Are a Member of This Executive Team\", \"Choosing Who to Tell\", \"Departments & Org Coordination\") for \"You Work for One Person\", \"The People in Their World\", \"Who Hears From You\" and \"Goals and Areas\". Solo means only the principal uses Open Executive — not that they have no people: their manager, direct reports, peers, clients, investors and board are contacts. The Executive helps the principal work with them (a 1:1 or review prep, an update or budget case for their manager or board, a negotiation) but does not coordinate them, contacts them only when the principal asks and only if they are a contact, and never offers to loop the principal in. Every specialist stays relevant — HR for the principal's own reports, board and investor communications for reporting upward. Goals are grouped by *area* (the tools' `department_slug` is the area's slug). The chat loop withholds `send_department_message`, `send_company_broadcast` and `set_department_head` from its tool list, and a call to one of them anyway gets a JSON error tool_result instead of running. The mode is resolved once per turn and pinned on the session, so the persona, the org block, the tools and every tool handler agree — a switch made mid-turn applies from the next turn. Team mode is unchanged.\n\nEvery specialist *advises* — each returns domain analysis the Executive synthesizes into one voice. None of them act on the company's behalf; the side-effecting tools in the main loop (schedule, people, departments, broadcast, watchlist, workflows) belong to the Executive, not to a specialist.\n\n`recall_history` (Always in the loop, `orchestrator.history_tools`) reads the speaker's own notes, on the same terms as `ghostwrite_email` below: its own registry, offered only on a verified turn in a conversation private to them with their switch on; its `due` flag lists only dated notes, soonest first (see Memory). The ghostwriter below also gets the writer's notes from mail every recipient was on, as a consistency check (`<writer_noted>`).\n\nThe morning reflection, which has no question to look up and no specialist to consult, gets one more read-only tool of its own: `search_knowledge` (`orchestrator.knowledge_tools`), the same knowledge lookup a chat turn makes, for what the company's documents say about a customer, contract, price or policy before it acts.\n\nA fifth, `remind_me` (`orchestrator.reminder_tools`), sets a plain-text reminder sent to the speaker alone when it is due; it opens no mailbox, so it never locks a turn. A sixth, `propose_actions` (`orchestrator.action_card_tools`), does nothing itself: it leaves the speaker a card of up to five actions (a meeting, a message, a new contact) that happen only when they tap Approve, so it stays on after a turn read mail; it is where what an email itself asks for goes, since that is never done on the email's say-so. Four read-only tools beside it read the speaker's own mailbox on the same terms — `search_my_email`, `read_my_email`, `read_my_email_attachment`, `my_email_awaiting_reply` (`orchestrator.mail_read_tools`) — and `my_calendar` their own calendar while Read my calendar is on, capped per turn, other people's messages and attached files returned as untrusted blocks (see Act as me). One tool writes under someone else's name, and it is fenced in code rather than the prompt. `ghostwrite_email` (**Act as me**, `orchestrator.delegation_tools`) writes an email as the person the Executive is speaking with and saves it as a draft in their own mailbox, Gmail or Outlook (`delegation.gmail.gmail_for` picks the client by the person's credential); chat never sends it (the person sends it themselves, or taps Send on its card). It lives in its own registry, never `_ALL_SKILL_TOOLS`, so reflection, research and workflow toolkits can never carry it. The chat loop adds it only on a turn `delegation.settings.pin_turn_delegation` offered it to — the principal, or a team member once the owner lets them, with it on, verified, in a conversation private to them (the web chat, a Slack or Discord DM, a verified private Telegram chat), on an attended turn — and builds that turn's handler map from both registries, so on any other turn a call to it is an unknown tool. From the round that calls it until the turn ends, the dispatch guard refuses only what opens an outside address, runs a script or workflow, or posts to everyone (`delegation.lockdown`), without changing the offered list; messages and invites to the roster, follow-ups, facts in the person's own words and a contact they name still run, each fenced in its own path. A later turn in the conversation stays private to its owner but holds nothing: the person asking again, having read the reply, is their own request. A contact add the lockdown refuses becomes an approval card in the chat instead (`propose_actions`). Recipients are chosen in code, never by the model (a draft's new email may go to any address, named back to check when it is neither on the roster nor typed), and the text comes from the **ghostwriter** (`delegation.ghostwriter`), a tool-less call with a constant prompt plus the person's \"How I write\" profile. The ghostwriter is deliberately not a Council agent: the Council's edit routes have no principal check. See **Act as Me (Delegation)**. A second tool joins the same way: `recall_history` (`orchestrator.history_tools`, Always in the loop) reads the speaker's own notes of what they said, by email or in chat. It has its own registry and per-turn handler map too, and the loop adds it only when `history_tools.recall_person` finds the speaker verified, in a conversation private to them, on an interactive turn that isn't private to the principal, with their notes switch on. It doesn't need Act as me. After every chat turn the Executive also hands the speaker's own words to `history_chat.schedule_chat_notes`, which takes notes in the background when their switch is on and the surface verified them (see **Memory**).\n\nThe Executive can also launch *any* workflow conversationally: `orchestrator.workflow_run_tools` adds `list_workflows` (the launchable catalog with each workflow's inputs) and `run_workflow` (runs a built-in or custom workflow to completion and returns its artifact, checkpointing approval gates as `awaiting_human`). `run_workflow` runs the weekly review, and in solo mode the morning brief, only for the principal on a verified surface (`Workflow.principal_only_modes`, `create_goal`'s rule); anyone else gets an audited refusal that does not name the rule. A run whose `result` event reports `private_to_principal` (the morning brief on the principal's own verified turn, when it read their private rows) still returns its artifact into that turn, but the stored run keeps `persistence.PRIVATE_RUN_ARTIFACT` instead of the text, since run history is readable by everyone signed in. This makes the `/jobs` catalog reachable from chat — see the Workflows section.\n\nDeliverables are first-class too. `orchestrator.artifact_tools` gives the Executive three tools: `draft_artifact` publishes a memo, web page (`html`), Word document (`docx`), spreadsheet (`xlsx`, from structured `sheets`) or a `link` to something it created in one of the principal's connected apps through the generic MCP gateway (`search_tools` → `call_tool`, any server — no vendor is named), and returns the artifact's id and link; `list_artifacts` and `get_artifact` let it find and reread its own past work (drafts and workflow outputs alike, through the same `artifact_records` read model the API uses). Every artifact belongs to someone: a draft to the person whose turn published it (`artifact_records.current_viewer`; with nobody speaking, the scheduler or the CLI, the principal), and a run someone started by hand to them, while scheduled runs are the team's. The tools, the recall, `message_person`'s link and mail attachments only ever reach the speaker's own (a link is refused when the recipient couldn't open it), not even the principal sees a teammate's, and a speaker who isn't on the People list publishes nothing. A workflow's own session inside someone's turn (the research synthesis) is pinned to that turn's viewer (`Session.documents_viewer`). Revising is `draft_artifact(supersedes=<id>)`, which archives the earlier version. When the principal asks for a deliverable the tool is always used; the \"quiet is the right default\" bar applies only to unprompted drafts. The format enum is a hard-coded sorted tuple so the cached tool schema stays byte-stable. Delivery: `message_person(person_id, text, artifact_id?)` appends the artifact's title and a `UI_BASE_URL/artifacts/<id>` link (through the same outbound guard as any DM; the link needs Open Executive access), and a Gmail send/draft can attach the file itself by `artifact_id` — see Integrations.\n\n**Extensions** (`orchestrator.extensions`). An install can add chat tools and kinds of document without changing this code. `OPENEXECUTIVE_EXTENSIONS` names Python modules. The first turn, or the first Documents read, imports each one and calls its `register()`. A module that fails is logged and skipped. `register_tool` takes an `ExtraTool`: a definition, an async handler, an optional `tool_groups` group (new or existing) and an optional chip. It refuses a name the loop already knows (`executive.builtin_tool_names`). An extension tool is never in `_ALL_SKILL_TOOLS`, so reflection, research and the synthesis never see it. The chat loop adds it per turn, like the Act as me tools, but never on an unattended run, a turn private to the principal or to a speaker who isn't on the People list (mail from a stranger), and only where its own `offered(session)` says. That predicate depends only on the kind of turn, so each kind of turn keeps one cached tool list. Act as me's lockdown refuses it once the turn has read the owner's mail, because it is unclassified and the lockdown fails closed, unless it was registered with `after_mail_read=True`: a tool that only reads the install's own data and carries nothing the model wrote anywhere outside. Its chip goes through `action_chips.summarize_action`, which applies the same no-chip rules for an error or refusal and keeps a link to a path inside the app. `register_collection` adds a kind of document: a drafted artifact tagged `collection:<name>` carries that collection on its record. The Documents page gives each collection its own filter. The collection's `on_change` hears about archive, restore and delete before they happen; if it raises, the change does not happen. `draft_artifact(supersedes=…)` refuses a collection's document. The alert pipeline strips `collection:` tags, so only the extension's own code files a document in its collection. A module that fails partway through `register()` leaves nothing registered. A tool registered with `workflow=True` is also offered to workflow action steps as `oe__<name>` (see Workflows); `read_only=True` marks one that only reads. A step runs with nobody in the turn, so `offered` isn't asked: `extensions.in_workflow_step(name)` is True for that tool, during its call only, and the handler decides what an unattended call may do.\n\nDocuments come in the other way through `read_document` (`orchestrator.document_tools`): it reads a PDF, Word, Excel, CSV, Markdown or text file by `path` — one another tool saved, such as a Gmail attachment (`get_gmail_attachment_content`) or a Drive file (`get_drive_file_download_url`) — or a company document by `filename`, with an optional PDF `pages` range. A scanned PDF is converted (`knowledge.pdf_reader`: local OCR by default; with `PDF_PROVIDER_READING=true`, the deployment's own model through its provider's PDF support, falling back to local OCR) rather than returned empty. Reads are confined to the tool download folders — the same resolve-then-contain check as `oe__read_file` — plus the company docs folder, and it is withheld on turns private to the principal (`PRIVATE_TURN_WITHHELD_TOOLS`): those come from a contact's email, whose own attachments the poller has already read into the turn, and must not steer the Executive into company documents.\n\nThe Executive also backs the **Ask OE** panel's form-fill tier via `orchestrator.form_tools.propose_form_values`: when a chat turn arrives with a `<page_context>` block describing a form on the user's screen, the Executive can propose values for it. The proposal is delivered to the UI as a `form_patch` SSE event and placed into the form as highlighted suggestions — the tool never saves or submits anything; the user reviews and saves manually. The tool is **always** in the tool list (tool definitions sit at the top of the cached prompt prefix, so a conditionally-present tool would invalidate the prompt cache whenever panel and non-panel turns alternate); its description restricts usage to turns that carry a form descriptor.\n\n**Take the lead** (`orchestrator.take_the_lead`) is how the Executive acts on its own, behind one gate. It has two switches, both off until someone turns them on. **As the Executive** is the principal's alone (`PUT /take-the-lead`). With it on, the unattended passes (reflection, research, the scheduler's proactive trigger) keep the acting tools solo mode otherwise withholds from them: booking, starting workflows, and messaging teammates rather than only the principal. `schedule_tools.unattended_toolkit` and the chat loop's unattended path then wrap every acting tool (`ACTING_TOOLS`, plus any MCP tool whose name sends, creates, updates, deletes or shares) in `gated_handlers` / `gated_call_tool`. The principal-only tools (`UNATTENDED_WITHHELD_TOOLS`) stay withheld, and every guard inside a handler still applies, including department approval levels (a booking in a department on Proposes is still a proposal) and the contact-egress rule. New mail or chat (any turn with an `origin_channel`) wakes the existing reflection early (`take_the_lead.wake`): one run waiting at most, five minutes after the first message and no more than every 30 minutes, as a one-off `take_the_lead_wake` scheduled action. Pause holds it like any scheduled work. **As you** is the Handle it for me dial's top step (delegation section).\n\n**The gate** is plain code (`take_the_lead.check`). Six kinds of action wait for a yes first, each with an Ask first switch, all on to start. The switch is the decision ledger's own mode for the class `take_the_lead_action:<kind>` (`propose` asks first, the default; `auto_execute` doesn't). The kinds are money, contracts and legal, hiring and people decisions, deleting/cancelling/sharing, someone new (an address on neither the roster nor the contacts) and big sends (a broadcast or department message, or more than five people). On top of these, the company (set by the principal) and each person (for their own As you) add structured rules: a person or address, a domain, words, or an amount at or above a figure. Added rules always hold, and an error reading them holds the action. The one thing the gate lets straight through is a direct message (`message_person` or a Slack, Telegram or Discord DM) whose only recipient is the principal (`_only_to_principal`): they are who it would wait for, so a card would only ask them to approve a message to themselves. Anything that reaches or acts on anyone else is checked, and a roster that can't be read is not the principal. A held action becomes a `take_the_lead_action` decision instance with a companion `DECISION_ALERT_SOURCE` card on Today, routed to the first teammate holding one of its People approval ranges (`take_the_lead.approval_ranges`, plain code, closest fit first: money to `spend_lt_2k`, `spend_lt_10k` or `spend_gt_10k` by its largest amount, with a higher range able to approve a lower one and no amount read as large, or to `customer_credit` for credit and payment terms; vendor contracts to `vendor_onboarding` then `legal_sign`, other contracts to `legal_sign`; hiring to `hiring_signoff`; anything else about the board or investors to `board_comms`; in Personal as in team mode), or else the principal through the authority gate's fallback (`departments.authority._route_proposal`). Deletes and shares always go to the principal. Only the principal and that approver see or resolve it (`DecisionClassSpec.principal_and_approver`). Approving it claims the row and carries out the exact call once (`take_the_lead.carry_out`: the unwrapped handler, or the gateway's `call_tool`, on an unattended session, with contact egress only when the principal approves). Declining drops it. Everything done or held is a row in `take_the_lead_log`. What it did and what was approved show in Recent activity (`today._build_activity`, kind `took_the_lead`), named but never quoted, since that feed is the team's. The held card's own `decision_resolved` row is left out because its payload quotes the message. `GET /today/activity` also adds the caller's own Handle it sends (kind `sent_as_you`, actor `you`), which are never in the shared feed.\n\n**In training.** The As the Executive switch has three positions: Off, **In training** and On (`take_the_lead.training`). In training, an action the gate would let through still waits, as a `training` hold for the principal alone, unless the principal has allowed that action with that person or thing (`take_the_lead.allowance`: \"Message Priya Nair\" covers a message to her on any channel; \"Book meetings with Priya Nair and Sam Lee\" meetings with exactly them; a workflow by id; a connected tool by name and the file it names, never one that reaches people such as a mail send or a share). The card carries Approve, **Approve + allow**, **Edit** (the message, a meeting's title, times or description, a task and its due date: `take_the_lead.apply_edits`) and Decline. Allowing is the principal's alone and needs a request the API can tie to them, as turning it on does; the six kinds and the added rules hold whatever is allowed. An edit approved with \"Do it like this next time\" is kept as an example (only the edited text, the principal's own words), and `take_the_lead.learned_note` hands the examples and the fact it's in training to the reflection and research passes in their user turn. After `SUGGEST_AFTER` (3) unchanged approvals of the same action in 30 days, Settings suggests allowing it. What it's learned is one list keyed by feature (`take_the_lead_allowed.feature`), so other features that learn from approvals can join it; each keeps its own switch. Act as me is the second (`act_as_me`, per person, `delegation.training`), with a training switch per setting (Replies, Follow-ups, Suggested actions, Drafts): its rows carry the person's id and the setting in their key, are listed and removed by that person alone, count toward their own cap, and never reach `learned_note`.\n\n**AI disclosure.** Nothing the Executive sends to people outside the web chat goes without saying it is an AI: plain code adds the line in the MCP gateway (mail) and at each chat send (Slack, Telegram, Discord, Google Chat replies, its DMs and room posts), never the prompt, so the persona and the cached system blocks are unchanged and a reply the model writes can't drop it. Replies the inbox watcher writes as a person carry their own line by that person's switches. See Integrations → **AI disclosure** and Act as me → **AI line on replies**.\n",
+ "markdown": "The Executive (`openexecutive.orchestrator.executive.Executive`) is a single coherent persona that fans out to specialist sub-agents via Anthropic tool use. Each specialist subclasses `openexecutive.agents.base.BaseAgent`, carrying a `name`, `domain`, and `model`, and exposes `analyze(...)`, which wraps the question in user-turn context and calls Claude through the per-call provider. That context is per call and never cached: `<company_stage>` (the stage from the company profile — specialists never see the profile itself), in solo mode `<principal_role>` (what kind of principal the advice is for, in plain words, with their title and remit — `router.principal_role_context`), `<department_memory>`, `<past_decisions>`, `<failure_cases>`, `<relevant_knowledge>` and `<conversation_context>`, outermost first. The specialist's own system prompt is a static domain constant under one `cache_control` block, so it stays byte-identical across companies and profile edits. A chat turn takes the stage from its session's profile (the one the Executive reasons over, and the one an eval scenario injects); workflow steps and the MCP server's `consult_specialist` read it fresh from the profile on disk. The role tag follows the turn's mode: a chat turn pins the role on its session with the mode (`pin_turn_principal_role`: the session's `principal_role` override, else the workspace settings) and sends it in solo and nothing in team, so the org block, every specialist in the turn and any workflow the turn starts see the same role; callers with no chat turn read it fresh (`load_principal_role`: the current session's mode and role, else the workspace's), and a failed read sends no tag rather than failing the consult. The CFO, CSO and sales prompts key their advice on it: for a bootstrapped, self-funded or solo company they drop venture fundraising benchmarks and work from cash, and raise only if the founder wants to.\n\nRouting uses one `consult_specialist` tool. When to call it is spelled out in the persona's Domain Expertise section (\"Going deeper\") and in the tool's own description: any question that asks for judgment in a specialist's area (a decision, plan, analysis, negotiation, hire, contract term, pricing or fundraising move, board message, or a department's own targets and stance, since the specialist holds that department's memory) is consulted before the answer, several at once across areas; lookups in mail, calendar or documents, scheduling, status checks, routine drafting and questions about how the Executive works are answered without one. Chat eval scenarios hold this: `required_routing` names specialists the turn must consult and `no_routing: true` says it must consult none, and the runner fails a scenario that misses either (`evals.scenarios.routing_check`). Beside it the Executive carries two skill tools, `search_skills` and `load_skill` (skills are shown to users as **playbooks**, and every playbook belongs to a workflow: one that follows it, or its own Quick workflow). Chat finds and reads playbooks but never creates or changes one: work worth repeating is offered as a workflow through `draft_workflow`, with the method written into its steps, because workflows read playbooks at run time (approved scheduled ones included) and this loop also runs on inbound email and chat, so only a person can change what a workflow follows. A hidden built-in is invisible to search and load; each `search_skills` hit lists the `workflows` that follow it, Quick ones included, and the persona routes \"the finished deliverable\" to that workflow and quick or partial asks to the playbook inline; Tool calls made while proactive work is tagged (scheduler dispatch, reflection, research, alert review) feed the Attunement outcome ledger. Goals have three tools: `list_department_goals`, `update_department_goal` (progress the user reports) and `create_goal` (a new goal the principal states, filed under an area by slug or title and creating the area when none matches — see Org). `create_goal` runs only for the principal on a verified surface, and no unattended run is offered it: the tools in `schedule_tools.UNATTENDED_WITHHELD_TOOLS` are dropped from reflection's and research's toolkits by `unattended_toolkit`, and from the chat loop when its Session is marked `unattended` — the scheduler's PROACTIVE TRIGGER run, whose prompt quotes stored intent text; a call the model emits anyway gets an error tool_result. `record_decision_outcome` records how a past decision turned out — the weekly review lists decisions older than 30 days with no outcome as `[decision N]` — writing `decisions.outcome` (`episodic.update_decision`) and auditing the rationale; it has `create_goal`'s gate (the principal on a verified surface only; everyone else gets an audited refusal) and is in `UNATTENDED_WITHHELD_TOOLS` too. A missing or unknown id returns the decisions still waiting on an outcome, so the model can retry with the right one. Its schema is static; the solo persona has one line on it, and team mode learns it from the tool description, so the team persona is byte-identical. Attunement adds `list_open_loops` (what a person owes — everyone's for the principal only in a private conversation, otherwise the caller's own) and `close_open_loop`, which only closes a loop when the turn's resolved speaker is the principal or the loop's owner — an unrostered sender, a signed-in web user not on the roster, and unattended sessions are refused. `assign_open_loop` opens one on request (\"ask Ben to send me the Q3 numbers by Friday\") for the principal or a rostered teammate on a verified surface — never an email, a turn private to the principal or an unattended run, which are also withheld the tool — and only when `task` appears verbatim in what the speaker typed this turn, at most 5 per turn; that turn's extraction pass then opens no second loop for the same owner. The owner is told once on their own channel when someone else assigns it, and the result's `notified` says how that went, so the Executive reports it rather than messaging them as well. The roster write tools (`upsert_person`, `archive_person`, `set_department_head`) are the principal's alone, and only on a surface that verified the speaker — the web chat, the principal's own Slack or Discord, or a private Telegram chat when `TELEGRAM_WEBHOOK_SECRET` is set to a value Telegram can send (Telegram identifies the chat rather than the sender, and without that secret its webhook accepts anyone's update). A teammate, an email (even from the principal's address), Google Chat, the CLI, the MCP server and unattended runs get `status: refused` (audited, and no action chip), because a team member's People row is also the web sign-in and outbound-email allow-list. `upsert_person` takes `kind` (`team` / `contact`; a new person defaults to `contact` in solo mode, an update keeps the current kind) and `email_aliases` (other addresses the person writes from — the full list, replacing the current one; they match mail and may be emailed but never sign in, and one already on someone else is refused), and after every write any pending roster request whose sender now matches someone is closed and its held messages replayed. `resolve_roster_request` answers a **roster request** — someone not on the People list who wrote in and is waiting (see Org): `approve` (a new person; `kind` defaults to team for a company-domain sender, else contact, when the principal did not say), `link` (someone already listed, by `person_id`; `replace_channel_id` only when the principal said so) or `decline`. It has the roster tools' gate (the principal on a verified surface; audited refusal otherwise), is in `UNATTENDED_WITHHELD_TOOLS`, and answers only an id in `Session.trusted_roster_request_ids` — the ids the server printed that turn in a `<roster_requests>` block (`briefing.context.format_roster_requests_for_prompt`, up to 10 pending requests), which `render_and_trust` appends to the `<briefing>` digest on the principal's own verified turn only and records on the session in the same step, so an id the model invents or reads out of a message adds nobody. Each line is server-derived — id, channel, address or account id, the sender's name sanitised and marked unverified, a company-domain hint, the message count — and never what they wrote. The block rides in the **user turn**, like the digest, so the cached system blocks are unchanged; the tool definition is static, and the new tool only extends the sorted tool list. The web chat route resets the trusted set every turn, and a resolved id is removed from it. and `list_people` returns both kinds with `kind` — contacts only on the principal's own verified turn (they are private to the principal; anyone else gets the team as if no contact existed) — while `lookup_person` searches the team only. `ask_about_person` reads a person's peer memory fully only on their own verified turn; anyone else's answers only to a verified principal or teammate, and only when that person turned on \"Share my work style with the team\", framed to how they work and never their view of a colleague, and otherwise returns the same \"hasn't chosen to share\" result whether or not anything is known. A teammate's own mail with the Executive is theirs the same way: every mailbox call the model makes through the MCP gateway (Gmail or Outlook, by `call_tool`, from a script, or a workflow step run from chat) passes through `orchestrator.teammate_mail`. A search excludes every other teammate's address server-side, except on mail the reader is also on, and is filtered again entry by entry; any other call that names a message or thread (read, attachment, reply, forward, label) must use an id a filtered search returned to the same reader in this conversation (`Session.mail_ids_seen`) or the inbound email the turn answers; reads are filtered message by message, so a message naming another teammate is left out unless the reader is in its From / To / Cc; a reply that would quote such a thread, or an Outlook forward, reply or attachment read of such a message, is refused; and a conversation in which a teammate other than the principal was shown their own mail becomes theirs alone, as Act as me's do. Outside mail and the reader's own are untouched; an email turn reads as its sender only when Gmail authenticated it, and any other unverified reader sees no teammate's mail, a background run the model drives reads as the principal and a workflow step outside any session as nobody, an Outlook inbox rule that forwards or names another teammate is refused, and the poller and the brief, which read the mailbox themselves, are unaffected. Their own chats are theirs too: every audit row of a teammate's verified turn is theirs (`people_tools.teammate_turn_owner`, see Audit; the principal sees the actions, never the words), and a teammate's web chat or DM opens for them alone (`chat._session_access`), the principal included. The same verified-principal rule, as `people_tools.contacts_reachable_now()`, decides whether a turn may reach a **contact** at all: `message_person`, the raw DM tools, `create_calendar_event` / `create_instant_meeting` attendees and the MCP gateway's Gmail / Calendar / Drive / OneDrive gates treat a contact exactly like an unknown person on every other turn, so no refusal reveals that one exists. **The untrusted-content policy** (`orchestrator.content_trust`) is one rule for text the principal did not write — inbound email, chat, attached files, watched pages — answering three questions for every surface. *Who is speaking*: the principal only when the surface proved it (`principal_speaking`: the web chat as the principal — never a signed-in email on nobody's People entry —, the CLI, their own Slack/Discord or a secret-verified Telegram chat, or their own address with Gmail's `dmarc=pass`); never a teammate, a stranger, Google Chat, the MCP server or an unattended run. *What may become memory*: episodic extraction runs only then, and only on the words outside `<untrusted_content>` blocks; peer memory and open loops are recorded under the speaker's own name, never as the principal's. *What may trigger tools*: every write on the principal's authority already refuses others in its handler; the tools with no such check that change the install for every later turn — `content_trust.PRINCIPAL_ONLY_TOOLS`: `load_mcp_server`, `list_saved_tools`, `run_python_job` and `run_script` — are not offered unless the principal is speaking on an interactive surface (not email, even authenticated), and a call the model emits anyway gets an error tool_result and a `refused: not_principal` audit row. So an inbound email, a teammate's turn, Google Chat and the scheduler's proactive trigger each get a stable tool list of their own without it. A send or edit on a team member's turn also meets their department's authority first (`orchestrator.department_gate`, see Org), and so does one on a turn whose speaker is on no People entry: a signed-in web caller or a chat-channel sender, which in practice is Google Chat, since Slack, Telegram and Discord turn unmatched senders away. Google Chat names a matched sender to the gate alone (`gate_sender_person_id`), so the principal there is not held. Email turns are left to the mailbox's own gates. *How it is labelled*: outside text goes into the user turn inside `<untrusted_content source=… author=… author_verified=…>` with a fixed notice that it carries no authority; compatibility forms are folded (NFKC), control characters go, and the tag's name is renamed wherever the text carries it — any case, spacing or entity-escaped form — so the text cannot end its block and speak outside it.\n\nA turn about the principal's private mail (`Session.private_to_principal`) reaches the principal only. It is neither offered nor allowed to run `schedule_tools.PRIVATE_TURN_WITHHELD_TOOLS` — everything that reaches someone else, publishes where the team reads, or starts work outside the turn: the broadcasts, meeting bookings and cancellations, `run_workflow` and research, follow-ups and workflow nudges, watches, artifacts, goal updates, saved workflows, skill drafts, and `load_mcp_server` (it connects to any URL, which can carry the turn's content). Through `search_tools` and `call_tool` it reaches only `schedule_tools.PRIVATE_TURN_MCP_TOOLS`: Google Workspace reads (mail, calendar, and Drive, Docs and Sheets search and file reads, with their Microsoft 365 twins; OneDrive's `download-bytes` only for a file's content) and the Gmail send and draft the gateway narrows to the principal. A search shows it nothing else, and a call to anything else (Google Chat, a Docs or Drive write, `manage_event`, another server) is refused (`schedule_tools.private_turn_withholds`). A call the model emits anyway, MCP tools included, gets an error tool_result and writes an audit row, and every audit row the turn writes is the principal's alone. On every turn the Executive knows what is connected without searching: block 0's *Connected Systems* section names the connected Google services, other MCP servers, the messaging channels, Notion sync, Confluence sync (when on) and Act as me, and pins the Google tool names it calls directly with `call_tool`. Both the service list and the pinned names are narrowed to what workspace-mcp actually loaded (`WORKSPACE_MCP_TOOLS`, `WORKSPACE_MCP_TOOL_TIER`), so a service left out is not named and its tools are not pinned — being told a tool is already available when it is not in the index costs a failed call the model cannot explain to itself. `search_tools` is for anything not listed. When work repeats over many items, the Executive can also call `run_script` (`workflows/step_script.py`, offered when the gateway runs, unless `CHAT_SCRIPTS=false`, and only on the principal's own turns — `PRINCIPAL_ONLY_TOOLS`, withheld on an unattended pass too, because it spends the turn's whole call budget on code the model just wrote): one short Python script, run in a sandboxed Monty worker with no files, network or environment, whose only reach is the gateway tools `call_tool` could reach (those `search_tools` has returned; the gateway keeps that set for its own process-wide session, not per conversation). Each call it makes is a `call_tool` in every way that matters — the gateway's discovery, deny-list and recipient gates, Take the lead's gate on an unattended run (or the department gate on a team member's turn, see Org), and the same action chip and `tool_invocation` row (marked `via: run_script`, `ok: false` when it raised), as each call happens; the script itself gets a `kind: script` row with its source and result. Its wall clock is half the turn's deadline, so a long script ends with the list of calls it made rather than being cut off with the turn, and a stopped turn closes it and its worker. A turn private to the principal is not offered it, and the Act as me lockdown withholds it whole. Besides gateway tools, a chat script may call a fixed list of the Executive's own tools (`step_script.CHAT_OWN_TOOLS`: reads, alerts, open loops, goals, the watch list, follow-ups, `message_person`, `upsert_person` — nothing that broadcasts, books calendars, edits memory or skills, or starts workflows or research), each only when the turn is offered it and through the turn's own handler (Take the lead's gate included), with the same chip and a `kind: skill`, `via: run_script` audit row. A direct call needs a `tool_use` each, so a turn's scripts share a budget instead: `CHAT_SCRIPT_MAX_CALLS` (default 200) calls in all, and per-turn caps on own tools that could otherwise act in bulk (`CHAT_OWN_TOOL_CAPS`: `message_person` 10 — messaging the whole roster would be a broadcast — `upsert_person` 25, `create_alert` 50); a refused call tells the model to say what is left. A call stopped mid-flight by the script's clock or the turn still gets a `cancelled` audit row, since it may have run. Because every round re-reads the conversation, the loop also nudges at the moment of choice: after a round whose results include a list of five or more items (`step_script.lists_many`), with `run_script` on offer and not used that round, it adds the constant `FANOUT_HINT` as a text block in that round's user message (never a cached block), once a turn, pointing the per-item work at one built tool. For library work on files (PDFs, spreadsheets, charts, images) the chat also has `run_python_job` (see Workflows → Python jobs): Python with a fixed library set in a Deno-isolated WebAssembly sandbox, fed Knowledge files by name, the message's own attachments as sent, or text it already holds, and able to keep a job that worked as a Custom tool, with result files linked for the principal to download; it is offered only on the principal's own turns and only where the sandbox is installed (not offered otherwise, so the tool prefix stays fixed per process). Agent Activity shows each run as one \"Built tool\" card (debug event `script_run`: ok, the calls it made, how many, how long, and the kept or reused tool's name). The persona's tool-building section is present only when chat scripts can actually run (the setting and Monty installed). `TOOL_BUILDING_ADDENDUM` in the cached persona tells the Executive when to build a tool — a job that looks something up and then checks or acts on each result, paged results, more than about ten items, or an answer that needs three or more reads (find, open, read; the tool returns only what answers the question, not whole documents, and only what is about to be edited or quoted at length is read in full), while a handful of items already named go as direct calls in one turn — and never to say it has none, and to talk about it as building a tool or doing it in one go. On the principal's own verified, interactive turns, a script that works can be saved as a named tool (`save_as`; elsewhere the script runs but is not saved) and run again with `run_script(tool=…, inputs=…)`; `list_saved_tools` (a constant definition, in `PRINCIPAL_ONLY_TOOLS` with `load_mcp_server`, so offered only while the principal is speaking on a verified, interactive surface; `run_script(tool=…)` is refused on any other turn) lists them, and each call a saved tool makes is a gateway call like any other (see Workflows → Saved tools). The tool's definition is a constant, so the cached tool prefix does not move. Multiple parallel `tool_use` blocks in a single assistant turn fan out concurrently through `router.route_parallel`, each running its own domain-filtered ChromaDB query (3 built-in and 2 company chunks by default, see the RAG section) before the specialist sees the question. The fan-out is failure-isolated per call: a specialist that raises or returns no text becomes an `UNAVAILABLE` tool_result (`router.specialist_unavailable_result`) instead of failing the whole turn, and its area — \"finance\", \"legal\", never the specialist's name — is reported to the user under the web reply, or by the Executive in its reply on other channels, unless another call to it answered that turn. A failed specialist does not count as consulted, so it takes no committee seat. Cancellation (Stop) still propagates. The Executive then synthesizes the returned analyses into one reply.\n\n`remember_fact`, `forget_fact` and `update_company_profile` (`orchestrator/fact_tools.py`) make a correction stick: the first two keep or retire a standing fact in `memory.facts`, and the third changes one field of the company profile. They share `record_decision_outcome`'s gate (the principal on a verified surface, an audited refusal for everyone else) and are in `UNATTENDED_WITHHELD_TOOLS`. `remember_fact` alone also admits a rostered teammate on a verified surface (web signed in, their own Slack or Discord): the fact is stored attributed (`recorded_by_role=\"teammate\"`, rendered `(per <name>)`), and is held as a `proposed` row (`awaiting_approval`) until the principal approves it, unless the principal marked that teammate trusted (\"needs my approval\" off; on by default) — and even then when it would replace the principal's fact. All three are also in `PRIVATE_TURN_WITHHELD_TOOLS`, since what they write or retire is read on everyone's turns. On the principal's own authenticated email (primary address, with Gmail's own `Authentication-Results` reporting `dmarc=pass`, not forwarded) the three tools check the request as usual, then hold it as `awaiting_confirmation`. It applies only when the principal replies to a one-time token emailed to their own address (`integrations.fact_confirmation`); the split into a check step and an `apply_*` step lets chat and the confirmed reply share one apply path. Each write also needs a `source_quote` found in the speaker's own words this turn. The active facts reach every specialist as a `<standing_facts>` user-turn tag: `route_to_specialist` reads them (None → the store, \"\" → none) for chat consults and workflow steps alike, and `BaseAgent.analyze` places the tag next to `<past_decisions>`, never in the cached specialist system prompt.\n\nThe ten entries in `SPECIALIST_REGISTRY` (`openexecutive.orchestrator.router`):\n\n| Key | Agent | Domain |\n| --- | --- | --- |\n| `cso` | `StrategyAgent` | strategy |\n| `cfo` | `FinanceAgent` | finance |\n| `chro` | `HRAgent` | hr |\n| `gc` | `LegalAgent` | legal |\n| `coo` | `OperationsAgent` | operations |\n| `cmo` | `MarketingAgent` | marketing |\n| `cpo` | `ProductAgent` | product |\n| `sales` | `SalesAgent` | sales |\n| `board_comms` | `BoardCommsAgent` | board |\n| `triage` | `TriageAgent` | triage |\n\nModels: specialists default to `claude-sonnet-5-5`; the deep-reasoning tier (CSO, CFO, GC, Board) runs on `DEEP_REASONING_MODEL`, `claude-sonnet-5-5` by default, with adaptive thinking; routing/fast classification uses `claude-haiku-5-5`. Requests are fitted to the model's generation on the way out (`feature_gate.fit_claude_generation`): 5-generation Claude models never receive `temperature` / `top_p` / `top_k`, and Haiku 5.5, which thinks unless told otherwise, gets thinking turned off when the caller asked for none. The Council's **Deep reasoning** toggle is honoured on Claude Opus/Sonnet (direct or via OpenRouter) and on any OpenRouter model whose live catalog entry supports `reasoning` (today all OpenAI, Gemini, DeepSeek and Grok entries; not Llama) — the request translator turns Anthropic adaptive thinking + effort into OpenRouter's `reasoning` parameter. It is a silent no-op on models that can't reason, and disabled for Haiku, which rejects adaptive thinking. A PDF `document` block is translated too: it becomes an OpenAI `file` part, and OpenRouter requests carrying one add the `file-parser` plugin (`native` for models whose catalog entry lists `file` input, else `PDF_OPENROUTER_ENGINE`, default `mistral-ocr`). `FeatureSpec.supports_pdf_input` gates it per model — off for a local server unless `LOCAL_PDF_INPUT` — and a gated-off PDF becomes a text note rather than vanishing. The Council picks a model in two steps: a **Provider** dropdown (Anthropic, OpenAI, Google, Meta, DeepSeek, xAI, Local, …), then a **Model** dropdown limited to that provider, with readable names (\"Claude Opus 5.5\") and the raw id and serving route shown underneath. The Anthropic group combines the direct Claude models (`claude-fable-5-1`, `claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5-5`, `claude-sonnet-5`, `claude-haiku-5-5`, `claude-haiku-4-5`) with any Claude generation that exists only on OpenRouter, and never lists a model twice. With `OPENROUTER_ENABLED`, the non-Anthropic entries come from OpenRouter's live `/models` catalog (fetched at startup, refreshed in the background, filtered to tool-capable paid text models from an allowlisted vendor set), falling back to a built-in snapshot if the fetch fails. Every Council agent also takes **additional instructions** (`agent_overrides.instructions`): text appended after its prompt by `agents.overrides.append_instructions` inside an `<additional_instructions>` block. `BaseAgent.base_system_prompt()` is the built-in prompt or its full replacement (what the Council's editor shows); `effective_system_prompt()` is that plus the instructions (what every call sends), and the Executive gets the same text through `build_system_blocks(persona_instructions=…)`. Unlike a replaced prompt, instructions leave the agent on its built-in prompt, so prompt improvements keep reaching it. A **Quality** choice above the agents (`agents.presets`) sets every agent's model and deep reasoning at once: **Fast** puts every agent on a small model (`claude-haiku-5-5`, else `claude-haiku-4-5`) with deep reasoning off, **Balanced** returns each agent to its built-in defaults, and **Thorough** puts the Executive and the domain specialists on the largest allowed model (`claude-opus-5-5`, else `claude-opus-5`) with deep reasoning on where the model supports it, leaving triage and the helpers below on their defaults. Presets change quality only; they never cap spend. Each preset resolves against the install's model allowlist at request time and is offered only when one of its models is allowed. Applying one writes ordinary per-agent overrides (model and deep reasoning only), so history, rollback and later per-agent edits keep working; an agent changed on its own afterwards shows as **Custom**. Each Council agent has a **visibility**: `core` for the Executive and the domain specialists (`BaseAgent.visibility = \"core\"`, which a new specialist must declare) and `internal` (the default) for triage and the helper agents below. Thorough moves only core agents. The Council opens in a **simple view**: the Quality choice, the voice picker, and only the core agents, each with its additional instructions and a model badge. **Show all agents** lists the internal ones too, and **Advanced** opens the full page (the browser remembers the choice). Eight Council-only agents are model/prompt-overridable in the UI but NOT callable via `consult_specialist`, because they are deliberately kept out of `SPECIALIST_REGISTRY`: `quality_judge` (committee review), `utility_fast` (gates, titles, decision parsing), `research` (the `executive_research` fan-out), `fixture_generator` (invents demo companies), `engagement_intake` (models a real client from intake material), `onboarding_interviewer` (interviews a new user about their own company and drafts its profile, people and departments), `workflow_designer` (runs the conversational New workflow wizard on `/jobs/new`: searches the available tools, asks clarifying questions, then drafts a validated dynamic-workflow definition for the user to review), and `workflow_actor` (runs a workflow's `action` steps: a bounded tool-use loop limited to the tools the user approved for that step). `fixture_generator`, `engagement_intake` and `onboarding_interviewer` share one shape — a forced tool call producing a whole company, validated for referential integrity, with a single repair retry — but opposite epistemics: the fixture author invents, the other two extract and leave unstated facts empty rather than guessing. When the workspace is in solo mode, `onboarding_interviewer`'s first user turn is prefixed with a short hint (`interview.solo_hint(role_kind)`, one static constant per role kind from the onboarding role step): the draft names only the principal, as principal, and no departments; an owner is asked about the offer, customers, pricing, cash and runway, an in-house executive about their organisation (drafted as the company — their employer), function, remit, manager, team size as context and what they are measured on, an independent about their practice, clients and pricing, and with no role given the role-neutral `SOLO_HINT` asks which they are. The hint rides in the user turn and the tool array is unchanged, so the cached system prompt and tool prefix are the same in both modes.\n\n**Voice.** The Executive answers in one voice persona, substituted into block 0 at `{VOICE_PERSONA}` (`personas/loader.get_active_body`) from the Executive override's `voice_persona_slug`. Three general voices ship in `personas/builtin/`: **Direct** (`default`, the slug used when none is set: answer first, brief and decisive), **Supportive** (a warm coach who explains the why and checks how the plan sits) and **Analytical** (numbers first, options and trade-offs, then one recommendation). They are offered by a shared picker in setup (`/onboard`, after the workspace choice) and in Settings → Executive, which saves through `PATCH /agents/executive`; a built-in voice's frontmatter carries the picker's one-line `description` and `sample` reply. The named-executive voices are marked `legacy: true`: the picker hides them, but they still load, so an install that picked one keeps it, and the Agent Council lists them under \"Legacy voices\". Voice files hold disposition only; the response-length ladder lives in `prompts/executive_persona.py`, and a test keeps numeric length rules out of every voice file. An eval scenario may set `voice_persona` to answer in a voice; it rides on `Session.voice_persona_slug`, which wins over the override for that session only.\n\nOne more structured-output utility agent sits beside `triage`: `openexecutive.agents.alert_review.AlertReviewAgent` (routing model, one forced `emit_alert_reviews` tool call, never raises). The alert review job hands it a batch of open alerts with evidence and gets back, per alert, a verdict (relevant / changed / resolved / stale), a confidence, the evidence it relied on, a one-line note, why-now, an optional deadline, and a recommended move (none / route / nudge / escalate / draft / suggest_workflow / merge / close) with its parameters. Like `triage`, it never mutates state — `alerts.review.apply_verdict` executes the verdicts deterministically within authority, so the model's job is judgment, not action.\n\n**Solo mode.** When the workspace (or the turn's session) is solo — one person using Open Executive for themselves — the Executive works for that one person, the principal, whatever their role: they may run their own business, lead a function inside a larger organisation, or work independently, and the persona reads which from the context instead of assuming it — the role lines under \"Your Principal\" in the org block, when the principal gave their role (workspace settings: kind, title, reports to, remit, measured on). Its persona swaps the team sections (\"You Are a Member of This Executive Team\", \"Choosing Who to Tell\", \"Departments & Org Coordination\") for \"You Work for One Person\", \"The People in Their World\", \"Who Hears From You\" and \"Goals and Areas\". Solo means only the principal uses Open Executive — not that they have no people: their manager, direct reports, peers, clients, investors and board are contacts. The Executive helps the principal work with them (a 1:1 or review prep, an update or budget case for their manager or board, a negotiation) but does not coordinate them, contacts them only when the principal asks and only if they are a contact, and never offers to loop the principal in. Every specialist stays relevant — HR for the principal's own reports, board and investor communications for reporting upward. Goals are grouped by *area* (the tools' `department_slug` is the area's slug). The chat loop withholds `send_department_message`, `send_company_broadcast` and `set_department_head` from its tool list, and a call to one of them anyway gets a JSON error tool_result instead of running. The mode is resolved once per turn and pinned on the session, so the persona, the org block, the tools and every tool handler agree — a switch made mid-turn applies from the next turn. Team mode is unchanged.\n\nEvery specialist *advises* — each returns domain analysis the Executive synthesizes into one voice. None of them act on the company's behalf; the side-effecting tools in the main loop (schedule, people, departments, broadcast, watchlist, workflows) belong to the Executive, not to a specialist.\n\n`recall_history` (Always in the loop, `orchestrator.history_tools`) reads the speaker's own notes, on the same terms as `ghostwrite_email` below: its own registry, offered only on a verified turn in a conversation private to them with their switch on; its `due` flag lists only dated notes, soonest first (see Memory). The ghostwriter below also gets the writer's notes from mail every recipient was on, as a consistency check (`<writer_noted>`).\n\nThe morning reflection, which has no question to look up and no specialist to consult, gets one more read-only tool of its own: `search_knowledge` (`orchestrator.knowledge_tools`), the same knowledge lookup a chat turn makes, for what the company's documents say about a customer, contract, price or policy before it acts.\n\nA fifth, `remind_me` (`orchestrator.reminder_tools`), sets a plain-text reminder sent to the speaker alone when it is due; it opens no mailbox, so it never locks a turn. A sixth, `propose_actions` (`orchestrator.action_card_tools`), does nothing itself: it leaves the speaker a card of up to five actions (a meeting, a message, a new contact) that happen only when they tap Approve, so it stays on after a turn read mail; it is where what an email itself asks for goes, since that is never done on the email's say-so. Four read-only tools beside it read the speaker's own mailbox on the same terms — `search_my_email`, `read_my_email`, `read_my_email_attachment`, `my_email_awaiting_reply` (`orchestrator.mail_read_tools`) — and `my_calendar` their own calendar while Read my calendar is on, capped per turn, other people's messages and attached files returned as untrusted blocks (see Act as me). One tool writes under someone else's name, and it is fenced in code rather than the prompt. `ghostwrite_email` (**Act as me**, `orchestrator.delegation_tools`) writes an email as the person the Executive is speaking with and saves it as a draft in their own mailbox, Gmail or Outlook (`delegation.gmail.gmail_for` picks the client by the person's credential); chat never sends it (the person sends it themselves, or taps Send on its card). It lives in its own registry, never `_ALL_SKILL_TOOLS`, so reflection, research and workflow toolkits can never carry it. The chat loop adds it only on a turn `delegation.settings.pin_turn_delegation` offered it to — the principal, or a team member once the owner lets them, with it on, verified, in a conversation private to them (the web chat, a Slack or Discord DM, a verified private Telegram chat), on an attended turn — and builds that turn's handler map from both registries, so on any other turn a call to it is an unknown tool. From the round that calls it until the turn ends, the dispatch guard refuses only what opens an outside address, runs a script or workflow, or posts to everyone (`delegation.lockdown`), without changing the offered list; messages and invites to the roster, follow-ups, facts in the person's own words and a contact they name still run, each fenced in its own path. A later turn in the conversation stays private to its owner but holds nothing: the person asking again, having read the reply, is their own request. A contact add the lockdown refuses becomes an approval card in the chat instead (`propose_actions`). Recipients are chosen in code, never by the model (a draft's new email may go to any address, named back to check when it is neither on the roster nor typed), and the text comes from the **ghostwriter** (`delegation.ghostwriter`), a tool-less call with a constant prompt plus the person's \"How I write\" profile. The ghostwriter is deliberately not a Council agent: the Council's edit routes have no principal check. See **Act as Me (Delegation)**. A second tool joins the same way: `recall_history` (`orchestrator.history_tools`, Always in the loop) reads the speaker's own notes of what they said, by email or in chat. It has its own registry and per-turn handler map too, and the loop adds it only when `history_tools.recall_person` finds the speaker verified, in a conversation private to them, on an interactive turn that isn't private to the principal, with their notes switch on. It doesn't need Act as me. After every chat turn the Executive also hands the speaker's own words to `history_chat.schedule_chat_notes`, which takes notes in the background when their switch is on and the surface verified them (see **Memory**).\n\nThe Executive can also launch *any* workflow conversationally: `orchestrator.workflow_run_tools` adds `list_workflows` (the launchable catalog with each workflow's inputs) and `run_workflow` (runs a built-in or custom workflow to completion and returns its artifact, checkpointing approval gates as `awaiting_human`). `run_workflow` runs the weekly review, and in solo mode the morning brief, only for the principal on a verified surface (`Workflow.principal_only_modes`, `create_goal`'s rule); anyone else gets an audited refusal that does not name the rule. A run whose `result` event reports `private_to_principal` (the morning brief on the principal's own verified turn, when it read their private rows) still returns its artifact into that turn, but the stored run keeps `persistence.PRIVATE_RUN_ARTIFACT` instead of the text, since run history is readable by everyone signed in. This makes the `/jobs` catalog reachable from chat — see the Workflows section.\n\nDeliverables are first-class too. `orchestrator.artifact_tools` gives the Executive three tools: `draft_artifact` publishes a memo, web page (`html`), Word document (`docx`), spreadsheet (`xlsx`, from structured `sheets`) or a `link` to something it created in one of the principal's connected apps through the generic MCP gateway (`search_tools` → `call_tool`, any server — no vendor is named), and returns the artifact's id and link; `list_artifacts` and `get_artifact` let it find and reread its own past work (drafts and workflow outputs alike, through the same `artifact_records` read model the API uses). Every artifact belongs to someone: a draft to the person whose turn published it (`artifact_records.current_viewer`; with nobody speaking, the scheduler or the CLI, the principal), and a run someone started by hand to them, while scheduled runs are the team's. The tools, the recall, `message_person`'s link and mail attachments only ever reach the speaker's own (a link is refused when the recipient couldn't open it), not even the principal sees a teammate's, and a speaker who isn't on the People list publishes nothing. A workflow's own session inside someone's turn (the research synthesis) is pinned to that turn's viewer (`Session.documents_viewer`). Revising is `draft_artifact(supersedes=<id>)`, which archives the earlier version. When the principal asks for a deliverable the tool is always used; the \"quiet is the right default\" bar applies only to unprompted drafts. The format enum is a hard-coded sorted tuple so the cached tool schema stays byte-stable. Delivery: `message_person(person_id, text, artifact_id?)` appends the artifact's title and a `UI_BASE_URL/artifacts/<id>` link (through the same outbound guard as any DM; the link needs Open Executive access), and a Gmail send/draft can attach the file itself by `artifact_id` — see Integrations.\n\n**Extensions** (`orchestrator.extensions`). An install can add chat tools and kinds of document without changing this code. `OPENEXECUTIVE_EXTENSIONS` names Python modules. The first turn, or the first Documents read, imports each one and calls its `register()`. A module that fails is logged and skipped. `register_tool` takes an `ExtraTool`: a definition, an async handler, an optional `tool_groups` group (new or existing) and an optional chip. It refuses a name the loop already knows (`executive.builtin_tool_names`). An extension tool is never in `_ALL_SKILL_TOOLS`, so reflection, research and the synthesis never see it. The chat loop adds it per turn, like the Act as me tools, but never on an unattended run, a turn private to the principal or to a speaker who isn't on the People list (mail from a stranger), and only where its own `offered(session)` says. That predicate depends only on the kind of turn, so each kind of turn keeps one cached tool list. Act as me's lockdown refuses it once the turn has read the owner's mail, because it is unclassified and the lockdown fails closed, unless it was registered with `after_mail_read=True`: a tool that only reads the install's own data and carries nothing the model wrote anywhere outside. Its chip goes through `action_chips.summarize_action`, which applies the same no-chip rules for an error or refusal and keeps a link to a path inside the app. `register_collection` adds a kind of document: a drafted artifact tagged `collection:<name>` carries that collection on its record. The Documents page gives each collection its own filter. The collection's `on_change` hears about archive, restore and delete before they happen; if it raises, the change does not happen. `draft_artifact(supersedes=…)` refuses a collection's document. The alert pipeline strips `collection:` tags, so only the extension's own code files a document in its collection. A module that fails partway through `register()` leaves nothing registered. A tool registered with `workflow=True` is also offered to workflow action steps as `oe__<name>` (see Workflows); `read_only=True` marks one that only reads. A step runs with nobody in the turn, so `offered` isn't asked: `extensions.in_workflow_step(name)` is True for that tool, during its call only, and the handler decides what an unattended call may do.\n\nDocuments come in the other way through `read_document` (`orchestrator.document_tools`): it reads a PDF, Word, Excel, CSV, Markdown or text file by `path` — one another tool saved, such as a Gmail attachment (`get_gmail_attachment_content`) or a Drive file (`get_drive_file_download_url`) — or a company document by `filename`, with an optional PDF `pages` range. A scanned PDF is converted (`knowledge.pdf_reader`: local OCR by default; with `PDF_PROVIDER_READING=true`, the deployment's own model through its provider's PDF support, falling back to local OCR) rather than returned empty. Reads are confined to the tool download folders — the same resolve-then-contain check as `oe__read_file` — plus the company docs folder, and it is withheld on turns private to the principal (`PRIVATE_TURN_WITHHELD_TOOLS`): those come from a contact's email, whose own attachments the poller has already read into the turn, and must not steer the Executive into company documents.\n\nThe Executive also backs the **Ask OE** panel's form-fill tier via `orchestrator.form_tools.propose_form_values`: when a chat turn arrives with a `<page_context>` block describing a form on the user's screen, the Executive can propose values for it. The proposal is delivered to the UI as a `form_patch` SSE event and placed into the form as highlighted suggestions — the tool never saves or submits anything; the user reviews and saves manually. The tool is **always** in the tool list (tool definitions sit at the top of the cached prompt prefix, so a conditionally-present tool would invalidate the prompt cache whenever panel and non-panel turns alternate); its description restricts usage to turns that carry a form descriptor. For questions about the product itself, the always-offered `read_user_guide` tool (`orchestrator/guide_tools.py`) returns any `guide/prebuilt/<id>.json` section; its description lists the section ids, fixed at import, so it never changes the cached tools prefix.\n\n**Take the lead** (`orchestrator.take_the_lead`) is how the Executive acts on its own, behind one gate. It has two switches, both off until someone turns them on. **As the Executive** is the principal's alone (`PUT /take-the-lead`). With it on, the unattended passes (reflection, research, the scheduler's proactive trigger) keep the acting tools solo mode otherwise withholds from them: booking, starting workflows, and messaging teammates rather than only the principal. `schedule_tools.unattended_toolkit` and the chat loop's unattended path then wrap every acting tool (`ACTING_TOOLS`, plus any MCP tool whose name sends, creates, updates, deletes or shares) in `gated_handlers` / `gated_call_tool`. The principal-only tools (`UNATTENDED_WITHHELD_TOOLS`) stay withheld, and every guard inside a handler still applies, including department approval levels (a booking in a department on Proposes is still a proposal) and the contact-egress rule. New mail or chat (any turn with an `origin_channel`) wakes the existing reflection early (`take_the_lead.wake`): one run waiting at most, five minutes after the first message and no more than every 30 minutes, as a one-off `take_the_lead_wake` scheduled action. Pause holds it like any scheduled work. **As you** is the Handle it for me dial's top step (delegation section).\n\n**The gate** is plain code (`take_the_lead.check`). Six kinds of action wait for a yes first, each with an Ask first switch, all on to start. The switch is the decision ledger's own mode for the class `take_the_lead_action:<kind>` (`propose` asks first, the default; `auto_execute` doesn't). The kinds are money, contracts and legal, hiring and people decisions, deleting/cancelling/sharing, someone new (an address on neither the roster nor the contacts) and big sends (a broadcast or department message, or more than five people). On top of these, the company (set by the principal) and each person (for their own As you) add structured rules: a person or address, a domain, words, or an amount at or above a figure. Added rules always hold, and an error reading them holds the action. The one thing the gate lets straight through is a direct message (`message_person` or a Slack, Telegram or Discord DM) whose only recipient is the principal (`_only_to_principal`): they are who it would wait for, so a card would only ask them to approve a message to themselves. Anything that reaches or acts on anyone else is checked, and a roster that can't be read is not the principal. A held action becomes a `take_the_lead_action` decision instance with a companion `DECISION_ALERT_SOURCE` card on Today, routed to the first teammate holding one of its People approval ranges (`take_the_lead.approval_ranges`, plain code, closest fit first: money to `spend_lt_2k`, `spend_lt_10k` or `spend_gt_10k` by its largest amount, with a higher range able to approve a lower one and no amount read as large, or to `customer_credit` for credit and payment terms; vendor contracts to `vendor_onboarding` then `legal_sign`, other contracts to `legal_sign`; hiring to `hiring_signoff`; anything else about the board or investors to `board_comms`; in Personal as in team mode), or else the principal through the authority gate's fallback (`departments.authority._route_proposal`). Deletes and shares always go to the principal. Only the principal and that approver see or resolve it (`DecisionClassSpec.principal_and_approver`). Approving it claims the row and carries out the exact call once (`take_the_lead.carry_out`: the unwrapped handler, or the gateway's `call_tool`, on an unattended session, with contact egress only when the principal approves). Declining drops it. Everything done or held is a row in `take_the_lead_log`. What it did and what was approved show in Recent activity (`today._build_activity`, kind `took_the_lead`), named but never quoted, since that feed is the team's. The held card's own `decision_resolved` row is left out because its payload quotes the message. `GET /today/activity` also adds the caller's own Handle it sends (kind `sent_as_you`, actor `you`), which are never in the shared feed.\n\n**In training.** The As the Executive switch has three positions: Off, **In training** and On (`take_the_lead.training`). In training, an action the gate would let through still waits, as a `training` hold for the principal alone, unless the principal has allowed that action with that person or thing (`take_the_lead.allowance`: \"Message Priya Nair\" covers a message to her on any channel; \"Book meetings with Priya Nair and Sam Lee\" meetings with exactly them; a workflow by id; a connected tool by name and the file it names, never one that reaches people such as a mail send or a share). The card carries Approve, **Approve + allow**, **Edit** (the message, a meeting's title, times or description, a task and its due date: `take_the_lead.apply_edits`) and Decline. Allowing is the principal's alone and needs a request the API can tie to them, as turning it on does; the six kinds and the added rules hold whatever is allowed. An edit approved with \"Do it like this next time\" is kept as an example (only the edited text, the principal's own words), and `take_the_lead.learned_note` hands the examples and the fact it's in training to the reflection and research passes in their user turn. After `SUGGEST_AFTER` (3) unchanged approvals of the same action in 30 days, Settings suggests allowing it. What it's learned is one list keyed by feature (`take_the_lead_allowed.feature`), so other features that learn from approvals can join it; each keeps its own switch. Act as me is the second (`act_as_me`, per person, `delegation.training`), with a training switch per setting (Replies, Follow-ups, Suggested actions, Drafts): its rows carry the person's id and the setting in their key, are listed and removed by that person alone, count toward their own cap, and never reach `learned_note`.\n\n**AI disclosure.** Nothing the Executive sends to people outside the web chat goes without saying it is an AI: plain code adds the line in the MCP gateway (mail) and at each chat send (Slack, Telegram, Discord, Google Chat replies, its DMs and room posts), never the prompt, so the persona and the cached system blocks are unchanged and a reply the model writes can't drop it. Replies the inbox watcher writes as a person carry their own line by that person's switches. See Integrations → **AI disclosure** and Act as me → **AI line on replies**.\n",
"mermaid": "flowchart TD\n User([User message]) --> Exec[\"Executive<br/>orchestrator\"]\n Exec -->|consult_specialist| Cso[\"cso: StrategyAgent\"]\n Exec -->|consult_specialist| Cfo[\"cfo: FinanceAgent\"]\n Exec -->|consult_specialist| Gc[\"gc: LegalAgent\"]\n Exec -->|consult_specialist| More[\"chro / coo / cmo / cpo / sales<br/>board_comms / triage\"]\n Mode{{\"Team or solo<br/>(persona + tools per turn)\"}} --> Exec\n Exec -->|\"ghostwrite_email (Act as me)\"| Gw[\"ghostwriter<br/>(tool-less, not a Council agent)\"]\n Cso --> Claude[\"Claude (Anthropic)\"]\n Cfo --> Claude\n Gc --> Claude\n More --> Claude\n Claude --> Exec\n class User entry\n class Exec compute\n class Mode compute\n class Cso compute\n class Cfo compute\n class Gc compute\n class More compute\n class Claude external\n class Gw compute",
- "generated_at": "2026-10-15T00:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/architecture/prebuilt/user_guide.json b/packages/core/openexecutive/architecture/prebuilt/user_guide.json
index 1bb8fb58..ed66fc9e 100644
--- a/packages/core/openexecutive/architecture/prebuilt/user_guide.json
+++ b/packages/core/openexecutive/architecture/prebuilt/user_guide.json
@@ -1,7 +1,7 @@
{
"section_id": "user_guide",
"title": "User Guide Surface",
- "markdown": "The `/guide` page is a **plain-language overview of every user-facing feature** — \"what it is, what it does, how to use it\" — aimed at non-engineers. It is deliberately kept separate from this technical reference: Architecture explains how the system is built; the User Guide explains what each feature does for you.\n\nIt is reached from the **Tools** section of the Settings page (`ADVANCED_ITEMS` in `navConfig.ts`), not the day-to-day nav.\n\n**Served exactly like this page.** Each section is static, hand-authored JSON shipped in the image — `packages/core/openexecutive/guide/prebuilt/<id>.json`, one file per entry in `guide/sections.py` → `GUIDE_SECTIONS`. The route `api/routes/guide.py` exposes `GET /guide/sections` and `GET /guide/sections/{id}`, mirroring the architecture routes. **Nothing on the serving path calls an LLM.**\n\n**Shared loader.** Both surfaces load their files through one class — `openexecutive.utils.prebuilt_store.PrebuiltDocStore` — pointed at each module's own `prebuilt/` directory. The same fields apply (`section_id`, `title`, `markdown`, `mermaid`, `generated_at`), and the same path-traversal guard rejects any id containing a separator or dot segment.\n\n**Shared renderer.** The UI reuses the architecture page's `DynamicSection` component via a `basePath` prop (`\"architecture\"` by default, `\"guide\"` for the guide), so deep links, lazy loading, and Markdown sanitization behave identically. The guide is intentionally diagram-free — its sections carry `mermaid: null`.\n\n**Keeping it current:** when a user-facing feature is added or materially changed, add or update the matching `guide/prebuilt/<id>.json` (and its registry entry in `guide/sections.py` + the mirror list in `app/guide/page.tsx`), the same way technical sections are maintained here. Every section must include a `**How to use:**` walkthrough (and an `**Example:**` where one helps) — `tests/unit/test_guide_prebuilt.py` enforces it. Because Ask OE inlines the current page's section into its user turn, those steps also ground its \"how do I…\" answers. The `custom_tools` section explains, in plain words, the tools the Executive builds and keeps (`run_script`, saved tools) — people see them as **Custom tools**, never as scripts.",
+ "markdown": "The `/guide` page is a **plain-language overview of every user-facing feature** — \"what it is, what it does, how to use it\" — aimed at non-engineers. It is deliberately kept separate from this technical reference: Architecture explains how the system is built; the User Guide explains what each feature does for you.\n\nIt is reached from the **Tools** section of the Settings page (`ADVANCED_ITEMS` in `navConfig.ts`), not the day-to-day nav.\n\n**Served exactly like this page.** Each section is static, hand-authored JSON shipped in the image — `packages/core/openexecutive/guide/prebuilt/<id>.json`, one file per entry in `guide/sections.py` → `GUIDE_SECTIONS`. The route `api/routes/guide.py` exposes `GET /guide/sections` and `GET /guide/sections/{id}`, mirroring the architecture routes. **Nothing on the serving path calls an LLM.**\n\n**Shared loader.** Both surfaces load their files through one class — `openexecutive.utils.prebuilt_store.PrebuiltDocStore` — pointed at each module's own `prebuilt/` directory. The same fields apply (`section_id`, `title`, `markdown`, `mermaid`, `generated_at`), and the same path-traversal guard rejects any id containing a separator or dot segment.\n\n**Shared renderer.** The UI reuses the architecture page's `DynamicSection` component via a `basePath` prop (`\"architecture\"` by default, `\"guide\"` for the guide), so deep links, lazy loading, and Markdown sanitization behave identically. The guide is intentionally diagram-free — its sections carry `mermaid: null`.\n\n**Keeping it current:** when a user-facing feature is added or materially changed, add or update the matching `guide/prebuilt/<id>.json` (and its registry entry in `guide/sections.py` + the mirror list in `app/guide/page.tsx`), the same way technical sections are maintained here. Every section must include a `**How to use:**` walkthrough (and an `**Example:**` where one helps) — `tests/unit/test_guide_prebuilt.py` enforces it. Ask OE inlines the current page's section into its user turn, and the Executive's `read_user_guide` tool (`orchestrator/guide_tools.py`, always offered, a plain file read) reads any other section on demand, so the guide is what grounds every \"how does X work\" answer. `scripts/pr_checks.py` enforces it: a change to a screen under `packages/ui/src/` (map `GUIDE_FOR`) fails the `guide-drift` check unless one of its guide sections changes too, or a commit or the PR carries `Guide: n/a - <reason>`. The `custom_tools` section explains, in plain words, the tools the Executive builds and keeps (`run_script`, saved tools) — people see them as **Custom tools**, never as scripts.",
"mermaid": "flowchart LR\n Settings([\"Settings hub tile\"]) --> Guide[\"/guide page\"]\n Guide --> Route[\"api/routes/guide.py\"]\n Route --> Store{\"PrebuiltDocStore\"}\n Store --> Files[(\"guide/prebuilt/*.json\")]\n ArchRoute[\"api/routes/architecture.py\"] --> Store\n Store --> ArchFiles[(\"architecture/prebuilt/*.json\")]\n class Settings entry\n class Guide entry\n class Route compute\n class ArchRoute compute\n class Store compute\n class Files storage\n class ArchFiles storage",
- "generated_at": "2026-10-07T17:58:29+00:00"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/delegation/lockdown.py b/packages/core/openexecutive/delegation/lockdown.py
index 3d1edde1..26078805 100644
--- a/packages/core/openexecutive/delegation/lockdown.py
+++ b/packages/core/openexecutive/delegation/lockdown.py
@@ -68,6 +68,8 @@ MAIL_TOUCHED_ALLOWED_TOOLS: frozenset[str] = frozenset({
"search_skills",
"search_tools",
"recall_history",
+ # The app's own user guide: a file shipped with it.
+ "read_user_guide",
# The owner's own mailbox (mail_read_tools, delegation_tools).
"ghostwrite_email",
"my_calendar",
diff --git a/packages/core/openexecutive/guide/prebuilt/artifacts.json b/packages/core/openexecutive/guide/prebuilt/artifacts.json
index 57d7a644..56ba760d 100644
--- a/packages/core/openexecutive/guide/prebuilt/artifacts.json
+++ b/packages/core/openexecutive/guide/prebuilt/artifacts.json
@@ -1,7 +1,7 @@
{
"section_id": "artifacts",
"title": "Documents",
- "markdown": "**What it is:** Your library of finished deliverables — memos, web pages, Word documents, spreadsheets, links to things the Executive created in your own apps, and the outputs of workflow runs — in one place.\n\n**What it does:**\n\n- See all active documents, filtered by kind (**Drafts** vs **Workflows** outputs). Anything that isn't plain text shows a small badge: *Web page*, *Word document*, *Spreadsheet*, or the app a link opens.\n- Open any document to read it. Web pages display in a locked-down frame that can't run scripts or load anything from the internet; spreadsheets show as tables; links open straight into the app they live in.\n- Download it in its own format (.md, .html, .docx, .xlsx). Any Markdown document — including every workflow output — can also be downloaded as a Word file.\n- **Send it to someone**: ask the Executive to share a document with a person. It messages them the title and a link on their usual channel (the link opens in Open Executive, so it's for people who have access), or — if Google Workspace is connected — emails the file itself as an attachment (Word, Excel, web page or Markdown).\n- **Revise in chat**: opens a new chat about that document. The Executive rereads it, writes the new version, and archives the old one; the new version links back to the one it replaced.\n- The Executive remembers what it has written: it can list and reread its documents, and past documents surface in its answers when relevant.\n- Archive a document to tuck it away (with a quick undo) and restore it later.\n- Permanently delete one when you're sure, with a confirmation step.\n- Switch between active and archived documents from the **⋯** next to the filter.\n\n**How to use:**\n\n1. Get something in here. Ask the Executive for a deliverable and say the format if you care — *\"as a Word doc\"*, *\"as a spreadsheet\"*, *\"as a one-page web page\"*, or *\"in my Google Sheets / Notion / OneDrive\"*. When you ask, it always publishes the result and replies with a link. For your own apps it uses whatever you've connected; with nothing connected it makes the file itself. It also drafts things unprompted when a finding is worth your time. Drafts appear as a card in **Needs you** on Home, and every workflow run adds its output here automatically.\n2. Open **Work** in the sidebar and pick the **Documents** tab. Filter by **Drafts** or **Workflows**; **Show archived** (in the **⋯** beside the filter) switches to archived documents, and **Show active documents** switches back.\n3. Click a document to read it; use **Copy** or **Download** (pick the format) to take it elsewhere, or **Revise in chat** to ask for changes.\n4. Each row's **⋯** menu has **Archive** (an **Undo** appears for a moment), **Restore** in the archived view, and **Delete permanently** (you'll be asked to confirm). The same actions are in the **⋯** on a document's own page.\n\n**Example:** *\"Put the vendor pricing comparison in a spreadsheet for me.\"* A spreadsheet lands in **Needs you** and in **Documents**, previewed as tables with a **Download .xlsx** button. Later: *\"Add a column for contract length to that pricing spreadsheet\"* — the Executive rereads it, publishes the revised version, and archives the first one.\n\n*Note: archiving is a soft-delete — nothing is lost until you explicitly delete it.*",
+ "markdown": "**What it is:** Your library of finished deliverables — memos, web pages, Word documents, spreadsheets, links to things the Executive created in your own apps, and the outputs of workflow runs — in one place.\n\n**What it does:**\n\n- Lists your active documents, grouped by where they came from: one **Drafts** group for documents the Executive drafted, and one group per workflow for run outputs. Click a group's heading to fold it.\n- Filters by kind: **All**, **Drafts** or **Workflows**, each with a count. An installed extension that keeps its own kind of document adds a filter of its own.\n- Anything that isn't plain text shows a small badge on its row: *Web page*, *Word document*, *Spreadsheet*, or the app a link opens.\n- Opens any document to read it. Web pages display in a locked-down frame that can't run scripts or load anything from the internet. Spreadsheets and Word documents show as a preview; download them for the full file. A link shows its summary and an **Open <app> ↗** button that opens it in the app it lives in.\n- Downloads it in its own format (.md, .html, .docx, .xlsx). Any Markdown document — including every workflow output — can also be downloaded as a Word file.\n- **Send it to someone**: ask the Executive to share a document with a person. It messages them the title and a link on their usual channel (the link opens in Open Executive, so it's for people who have access), or — if your email is connected (Gmail or Outlook) — emails the file itself as an attachment (Word, Excel, web page or Markdown; a Markdown document can go as Word).\n- **Revise in chat**: opens a new chat about that document. The Executive rereads it, writes the new version, and archives the old one; the new version shows **Replaces an earlier version** with a link to the one it replaced.\n- The Executive remembers what it has written: it can list and reread its documents, and past documents surface in its answers when relevant.\n- Archive a document to tuck it away (with a quick undo) and restore it later.\n- Permanently delete one when you're sure, with a confirmation step.\n\n**Who sees what:**\n\n- A document the Executive wrote in a conversation belongs to the person whose conversation it came from. Only they see it. Not even the principal sees a teammate's.\n- A workflow output follows its run: a run someone started by hand is theirs alone; the output of a scheduled or system run is the team's, and everyone signed in sees it.\n- Archiving or deleting a team document archives or deletes it for everyone.\n\n**How to use:**\n\n1. Get something in here. Ask the Executive for a deliverable and say the format if you care — *\"as a Word doc\"*, *\"as a spreadsheet\"*, *\"as a one-page web page\"*, or *\"in my Google Sheets / Notion / OneDrive\"*. When you ask, it always publishes the result and replies with a link. For your own apps it uses whatever you've connected; with nothing connected it makes the file itself. It also drafts things unprompted when a finding is worth your time. Drafts appear as a card in **Needs you** on Home, and every workflow run adds its output here automatically.\n2. Open **Work** in the sidebar and pick the **Documents** tab. Pick a filter. **Show archived** (in the **⋯** beside the filter) switches to archived documents; **Show active documents** in the same menu, or **Back to active**, switches back.\n3. Click a document to read it. The page shows its format, where it came from and when it was created. A draft the Executive made on its own also shows **Why this is worth your time**.\n4. Use **Copy** to copy its text, **Download** to pick a format (*As .md*, *As .docx*, and so on), or **Revise in chat** to ask for changes.\n5. Each row's **⋯** menu has **Archive** (an **Undo** appears for a few seconds), **Restore** in the archived view, and **Delete permanently** (you'll be asked to confirm; it removes the document everywhere and cannot be undone). The same actions are in the **⋯** on a document's own page.\n\n**Example:** *\"Put the vendor pricing comparison in a spreadsheet for me.\"* A spreadsheet lands in **Needs you** and in **Documents**, previewed as tables, with **Download** offering the .xlsx file. Later: *\"Add a column for contract length to that pricing spreadsheet\"* — the Executive rereads it, publishes the revised version, and archives the first one.\n\n*Note: archiving is a soft-delete — nothing is lost until you explicitly delete it.*",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/ask_oe.json b/packages/core/openexecutive/guide/prebuilt/ask_oe.json
index 2be8ada7..f7efc359 100644
--- a/packages/core/openexecutive/guide/prebuilt/ask_oe.json
+++ b/packages/core/openexecutive/guide/prebuilt/ask_oe.json
@@ -1,7 +1,7 @@
{
"section_id": "ask_oe",
- "title": "Ask OE",
- "markdown": "**What it is:** A page-aware assistant panel docked on the right of every screen (except the chat home, which *is* the chat). Open it with the **Ask OE** button in the top bar or **Ctrl/Cmd + .** — it's the same Executive you talk to in chat, but it knows what page you're looking at.\n\n**What it does:**\n\n- **Explains the current page.** Ask \"what does this page do?\" or \"what does authority scope mean?\" and the answer is grounded in this guide's section for the page you're on.\n- **Fills forms for you.** On a screen with a form (the workflow builder, the Add-person dialog, the company profile), describe what you want in plain language and the suggested values land directly in the form, highlighted so you can see what came from the Executive.\n- **You always click Save.** Ask OE never submits a form. Suggested values are just that — review them, edit anything, and save through the form's normal button. An **Undo** on the proposal card restores what was there before, and a highlight clears the moment you edit that field yourself.\n\n**How to use:**\n\n1. On any page, click **Ask OE** in the top bar or press **Ctrl/Cmd + .** (press it again to close).\n2. Ask about the page — \"what's the difference between Flag and Reject here?\" — or, on a form page, describe what you want filled in.\n3. Check the highlighted fields. Edit anything that's off, then click the form's own **Save** / **Create** button. Click **Undo** on the proposal card to put the form back as it was.\n4. Click **New conversation** in the panel header to start fresh.\n\n**Where it works:** every page inside the app shell. Form-filling is wired into the workflow builder (**Work → Workflows**, then **New workflow** in the **⋯** beside **Start**), the **Add person** dialog, and the **Company profile**; other pages get the explain tier, with form support arriving screen by screen.\n\n**Example:** on the workflow builder (**New workflow** in the **⋯** beside **Start** on **Workflows**), open Ask OE and type *\"create a weekly Monday 9am competitor watch where the CMO checks our top three competitors for pricing and product changes, and send it to me\"*. The name, steps and schedule fill in; you review them and click **Create workflow**.\n\n**Good to know:** panel conversations are normal chat sessions — they appear in your session history and the audit log like any other turn.",
+ "title": "Help with this page",
+ "markdown": "**What it is:** A help panel docked on the right of every page inside the app. Home and the chat itself don't have it, since they are the chat. Open it with the sparkle button at the top right of the page, or **Ctrl/Cmd + .**. The panel's title is the name of the page you're on. It's the same Executive you talk to in chat, but it knows which page you're looking at.\n\n**What it does:**\n\n- **Explains the current page.** Ask \"what does this page do?\" or \"what does authority scope mean?\" and the answer is grounded in this guide's section for the page you're on.\n- **Answers questions about the rest of the app.** It can read any section of this guide, so you can ask how another page or feature works (\"what happens when I share a chat?\") from anywhere. If the guide doesn't cover something, it says so.\n- **Fills forms for you.** On a page with a registered form, describe what you want in plain language and the suggested values land directly in the form, highlighted so you can see what came from the Executive.\n- **You always click Save.** The panel never submits a form. A card under the reply says *Filled N fields in the form — review and save.*, lists the fields, and gives the Executive's reason. Fields it didn't recognise are listed as *Skipped (not recognized)*. **Undo** on that card puts back what was there before, and a highlight clears the moment you edit that field yourself.\n- **Works like a chat turn.** You can stop a reply with the stop button, see its **Sources**, copy it and rate it with 👍 / 👎.\n\n**How to use:**\n\n1. On any page, click the sparkle button at the top right or press **Ctrl/Cmd + .** (press it again, or click the close button, to close it). On a phone it opens as a sheet over the page.\n2. Ask about the page, or click a starter: **What does this page do?**, and on a form page **Fill this form in for me:**. The box reads *Ask about this page…*, or *Describe what you want — I'll fill the form…* on a form page.\n3. Check the highlighted fields. Edit anything that's off, then click the form's own **Save** / **Create** button. Click **Undo** on the card to put the form back as it was. If you left the page before the values arrived, the card says *Suggested values arrived, but the form is no longer on screen.* and shows them so you can copy them.\n4. Click **New conversation** (the **+** in the panel header) to start fresh. The conversation otherwise stays in the panel as you move between pages.\n\n**Where it works:** every page inside the app shell. Form-filling works on three forms:\n\n- **New workflow, step by step** (on **Work → Workflows**, in the **⋯** beside **Start**). It fills the name, title, description, section, steps and schedule. The plain **New workflow** conversation does not take form suggestions.\n- The **Add person** dialog on **People**.\n- The **Company profile**. Suggested values open the matching section in edit mode, and you save each section yourself.\n\nOther pages get explanations only.\n\n**Example:** on **Work → Workflows**, choose **New workflow, step by step** in the **⋯** beside **Start**, open the help panel and type *\"create a weekly Monday 9am competitor watch where the CMO checks our top three competitors for pricing and product changes, and send it to me\"*. The name, steps and schedule fill in; you review them and click **Create workflow**.\n\n**Good to know:** panel conversations are normal web chats. They appear on your **Chats** page and in the audit log like any other turn, and the Executive can do anything there it can do in chat.",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/audit.json b/packages/core/openexecutive/guide/prebuilt/audit.json
index ac4d8c44..6f23f28e 100644
--- a/packages/core/openexecutive/guide/prebuilt/audit.json
+++ b/packages/core/openexecutive/guide/prebuilt/audit.json
@@ -1,7 +1,7 @@
{
"section_id": "audit",
"title": "Audit Log",
- "markdown": "**What it is:** A searchable, append-only record of everything the system did — every chat turn, specialist consult, tool call, alert, scheduled action, and inbound integration.\n\n**What it does:**\n\n- Filter events by type, session, date, or free-text search.\n- Open any event to see its full payload — the message, tool input, and result.\n- View a per-session flow chart showing what led to what.\n- See cost and token summaries for each session.\n\n**How to use:**\n\n1. Open **Settings → Advanced → Audit log**. It opens on **Sessions** — one card per conversation.\n2. Click **Open flow chart →** on a session to see it step by step. Click any node to see exactly what the agent saw and did; the side drawer shows the full payload, with **Copy**.\n3. Switch to **Events** for the raw list, and click a row for its full payload. Clicking a session id filters to that session.\n4. Narrow things down with **Search summary…**, the event-type dropdown, **Session id**, and **From / Until**. **Clear filters** resets them.\n\n**Example:** *\"Why did the Executive message our vendor on Tuesday?\"* — search for the vendor's name, set **From / Until** to Tuesday, then open that session's flow chart and follow it from the inbound message to the outbound send.\n\n*Note: the log is immutable — it's the trail for understanding (and trusting) what the Executive did.*",
+ "markdown": "**What it is:** A searchable record of what the Executive did: each chat turn, each question it passed to a specialist, each tool it used, each alert, each scheduled job and each message that came in from a channel. Newest first.\n\n**What it does:**\n\n- Shows activity grouped by conversation (**Sessions**) or as a plain list (**Events**).\n- Filters by text, event type, session id and date range.\n- Opens any event's full payload: the message, the tool input and the result.\n- Draws a flow chart of one session, step by step, with its token counts and cost signals.\n\n**How to use:**\n\n1. Open **Settings → Advanced → Audit log**. It opens on **Sessions**: one card per conversation, showing the channel, the session id, how long ago it ran, how long it took, and a count of each kind of event (for example \"1 inbound · 4 specialists · 6 tools\").\n2. Each card shows its three latest events. Click one to see its details and full payload. **+ N earlier events** shows the rest of that session, and **▴ Collapse** hides them again. Events with no session are gathered in one **unattributed** card at the end.\n3. Click a session id to filter to that session. The page switches to **Events**.\n4. Click **Open flow chart →** on a card to open **Session flow**. Each node is one step (Inbound, Memory, Knowledge, Specialist, Tool, Cache, Committee, Response, Alert, Scheduled). The strip at the top shows the number of events, the channel, model calls, input and output tokens, the share served from cache, and any steps that ran in a reduced way (**degraded**). Click a node to see what the agent saw, then **View full payload →** to open the drawer. **Copy** copies the payload. **← Audit log** goes back.\n5. Switch to **Events** for a table of Time, Type, Actor, Summary and Session. Click a row to see its full payload.\n6. Narrow things down with **Search summary…**, **All event types**, **Session id**, and **From / Until**. **Clear filters** resets them. Results come 100 per page; use **← Prev** and **Next →**.\n7. **Token usage** at the top opens the cost page.\n\nLinks from other pages, such as an item under \"Handled overnight\" in the brief, open the log with the type and search already filled in.\n\n**Who sees what:**\n\n- The owner of the Executive sees every event. A team member's own conversations show as actions only, such as \"Message (Dana's conversation, details private)\". What they said is not shown, and a text search leaves those rows out.\n- Once an owner is on the People list, anyone else sees only their own events.\n- The page has no way to edit or delete events.\n\n**Example:** *\"Why did the Executive message our vendor on Tuesday?\"* Search for the vendor's name, set **From / Until** to Tuesday, then open that session's flow chart and follow it from the inbound message to the outbound send.",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/chat.json b/packages/core/openexecutive/guide/prebuilt/chat.json
index 283ea823..2b260d8c 100644
--- a/packages/core/openexecutive/guide/prebuilt/chat.json
+++ b/packages/core/openexecutive/guide/prebuilt/chat.json
@@ -1,7 +1,7 @@
{
"section_id": "chat",
"title": "Chat & Briefing",
- "markdown": "**What it is:** Where you talk to the Executive in plain language. The app opens on **Home** — a quick read of what's happened across the company and what needs you — and you drop into a chat whenever you want to ask or decide something.\n\n**What it does:**\n\n- Hold a natural conversation with the Executive, which quietly pulls in whichever specialists a question needs.\n- Keep separate chat sessions with full history, so you can pick up where you left off.\n- Attach files to a message — up to 5 per turn, 20 MB each (images, PDF, Word, text, Markdown, CSV) — for the Executive to read alongside your knowledge base.\n- Stop a reply while it is still coming — whatever has been written is kept and marked *Stopped by you*, so you can redirect without waiting the answer out. (Escape works too.)\n- Turn on **Committee review** for a question that matters: a slower pass where reviewers challenge the draft answer before you see it.\n- Continue any item on Home straight into a chat thread, with the context already filled in.\n- Choose **Show agent activity** in the **⋯** menu at the top right to watch what's happening behind a reply — which specialists were consulted and which tools ran.\n- See what an answer drew on: click **Sources** under a reply to list the documents and web pages it looked at — your own documents, the built-in knowledge and any web pages — with links where there are any.\n\n**How to use:**\n\n1. Click **New chat** at the top of the sidebar (on a phone, **New chat** in the middle of the bar at the bottom), or type into the **Ask your Executive anything…** box on Home. Click **Home** any time to get back.\n2. Type your question and press **Enter** to send — **Shift + Enter** starts a new line. When the box is empty, a greyed-out suggested follow-up may appear; press **Tab** or **→** to use it.\n3. To include a file, click the **+** next to the message box, choose **Attach files or photos** and pick up to 5 files. (Drag-and-drop isn't supported in chat.) Attachments are read for that conversation only — to make a document permanently available, add it on the **Knowledge** page.\n4. For a decision that matters, click the **+** next to the message box and choose **Committee review** *before* sending. A **Committee review on** chip appears above the box (click it to turn it off). It applies to that one message; you'll see *Drafting → Committee review → Revising* while it works.\n5. Changed your mind mid-answer? Click the stop button (it replaces Send while a reply is streaming) or press **Esc**.\n6. Rate a reply with 👍 / 👎. Find old conversations under **Chats** in the sidebar: every conversation, including ones from Slack, Telegram and Discord, with a search box and a tab per channel. Delete one from its **⋯** menu.\n7. If part of an answer couldn't be completed — say the finance side — you still get the rest, with a short note under it. Ask again to fill in the missing part.\n\n**Example prompts:**\n\n- \"Here's our Q3 board deck — what questions should I expect from the board?\" *(with the PDF attached)*\n- \"Should we raise prices 10% for new customers? I want the finance and marketing view.\" *(with Committee on)*\n- \"What changed across the company this week that I should know about?\"\n\n*Tip: this is the front door — almost everything else in the app is something the Executive references or acts on from here.*",
+ "markdown": "**What it is:** Where you talk to the Executive in plain language. The app opens on **Home**, a quick read of what's happened across the company and what needs you, and you drop into a chat whenever you want to ask or decide something. Every conversation is kept on the **Chats** page.\n\n**What it does:**\n\n- Hold a natural conversation with the Executive, which quietly pulls in whichever specialists a question needs.\n- Keep every chat with its full history, so you can pick up where you left off.\n- Attach files to a message: up to 5 per message, 20 MB each (PNG, JPEG, GIF and WebP images, PDF, Word, text, Markdown, CSV). The Executive reads them for that message.\n- Stop a reply while it is still coming. Whatever has been written is kept and marked *Stopped by you*. (Escape works too.)\n- Add to a reply while it works: type and send, and your message joins the answer in progress (*Sent while it works*, then *👀 Seen, taking it into this answer*).\n- Redo your last turn in a web chat: **Try again** under the last reply asks the same question again, and **Edit** under your last message lets you change it. Sending an edit replaces that message and its answer.\n- Turn on **Committee review** for a question that matters: a slower pass where reviewers challenge the draft answer before you see it.\n- Continue any item on Home straight into a chat thread, with the context already filled in.\n- Choose **Show agent activity** in the **⋯** menu at the top right to watch what's happening behind a reply: which specialists were consulted and which tools ran.\n- See what an answer drew on: click **Sources (N)** under a reply to list the documents and web pages it looked at (your own documents, the built-in knowledge and any web pages), with links where there are any.\n- Copy a reply with **Copy**, and rate it with 👍 (**Helpful**) or 👎 (**Not helpful**).\n\n**How to use:**\n\n1. Click **New chat** at the top of the sidebar (on a phone, the **+** in the middle of the bar at the bottom), or type into the **Ask your Executive anything…** box on Home. Click **Home** any time to get back.\n2. Type your question and press **Enter** to send. **Shift + Enter** starts a new line. When the box is empty, a greyed-out suggested follow-up may appear; press **Tab** or **→** to use it (on a phone, tap **Use suggestion**).\n3. To include a file, click the **+** next to the message box, choose **Attach files or photos** and pick up to 5 files. Drag-and-drop isn't supported in chat. Attachments are read for that message only. To make a document permanently available, add it on the **Knowledge** page.\n4. For a decision that matters, click the **+** next to the message box and choose **Committee review (slower, reviewed)** before sending. A **Committee review on** chip appears above the box. It stays on for each message you send until you click the chip (or choose **Turn off committee review** in the **+** menu). While it works you see *Drafting → Committee review → Revising*.\n5. Changed your mind mid-answer? Click the stop button (next to the message box while a reply is streaming) or press **Esc**.\n6. In an open chat, the **⋯** menu at the top right has **Pin** / **Unpin**, **Rename**, **Download** and **Show agent activity**. Sharing and deleting are on the **Chats** page.\n7. If part of an answer couldn't be completed (say, the finance side), you still get the rest, with a short note under it. Ask again to fill in the missing part.\n\n**Chats page:** click **Chats** in the sidebar (on a phone, **Chats** in the bar at the bottom). It lists every conversation you own: web chats and the ones that came in through Slack, Telegram, Discord, Email and Google Chat. You only see your own chats here, plus the ones someone shared with you.\n\n- **Channel tabs:** **All** and **Web** are always there. A tab for Slack, Telegram, Discord, Email or Google Chat appears once you have a chat from it. Each tab shows its count. Chats from other channels carry the channel's name on the row.\n- **Groups:** chats are grouped into **Pinned**, **Today**, **Yesterday**, **Previous 7 Days**, **Previous 30 Days** and **Older** (collapsed until you click it). Each group shows 20 chats, then **Show N more**. Each row shows the title, when it was last active and how many messages it has.\n- **Search:** type in **Search titles and messages**. It searches the titles and message text of your own chats (up to 50 results). Each result shows *title match* or how many messages matched, with a snippet that highlights your words. Open a result found in its messages and the chat shows a bar with *match 1 of N* and arrows to step through the matches. Search does not cover chats shared with you.\n- **Row ⋯ menu** (your own chats): **Pin** / **Unpin**, **Rename**, **Share**, **Download** and **Delete chat**.\n - **Pin** moves the chat to the **Pinned** group at the top. Only you see your pins.\n - **Rename** gives the chat a name (up to 120 characters). The automatic title never replaces a name you set.\n - **Download** saves the whole chat as a Markdown (.md) file: each message under who wrote it (the person's name or *Executive*), with each reply's sources listed under it.\n - **Delete chat** asks *Delete this chat? This cannot be undone.* Deleting removes the chat and its messages from Open Executive and ends any sharing of it. Messages in Slack, Telegram or Discord stay in those apps.\n- **New chat** at the top right starts a new web chat.\n\n**Sharing a chat:**\n\n- **Who you can share with:** team members on your **People** list. Contacts, archived people and yourself are not offered. If no one else is on your team, the panel says *There's no one else on your team to share with yet.*\n- **How:** on the **Chats** page, open the chat's **⋯** menu and choose **Share**. The panel *Share this chat to read with:* lists your team with a checkbox each. Tick the people, then click **Save**. It confirms *Shared.* Only the chat's owner can share it. There is no share link: access goes to the named people only.\n- **What they get:** read-only access. The chat appears on their **Chats** page under **Shared with you**, with *Shared by* your name and when it was shared. They are not notified. Opening it shows the conversation with a bar that says *Shared with you by* your name, *You can read it but not write in it*, and a **Download** button. Their row **⋯** menu has **Download** only.\n- **What they see:** every message in the chat, including ones added after you shared it. The page loads the chat when they open it; it does not update live while they have it open, so they reload to see new messages. They see each reply's **Sources** and the actions it took, and they can copy text. They don't see your 👍/👎 ratings or your pin, can't send messages, rename, pin, share or delete it, and don't get **Try again**, **Edit** or suggested follow-ups. Agent activity is not shown. For attachments, they see the text that was read out of an attached document inside your message; photos and the original files are not shown.\n- **Which chats can't be shared:** a chat in which the Executive read or drafted in your own mailbox (**Act as me**) stays yours alone. Saving a share on it fails with *This chat read your own mail, so it stays yours alone.* If a chat you already shared later reads your mail, it disappears from everyone's **Shared with you** list and they can no longer open it. This can't be undone.\n- **How to stop sharing:** open **Share** again, untick the people and click **Save**. With nobody ticked it says *Not shared with anyone.* They lose access straight away; opening it then shows *This chat isn't shared with you any more.* Deleting the chat also ends sharing.\n- **Records:** each change to who a chat is shared with is written to the audit log.\n\n**Example prompts:**\n\n- \"Here's our Q3 board deck. What questions should I expect from the board?\" *(with the PDF attached)*\n- \"Should we raise prices 10% for new customers? I want the finance and marketing view.\" *(with Committee review on)*\n- \"What changed across the company this week that I should know about?\"\n\n*Tip: this is the front door. Almost everything else in the app is something the Executive references or acts on from here.*",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/clients.json b/packages/core/openexecutive/guide/prebuilt/clients.json
index 3361d3fa..bdbdcd69 100644
--- a/packages/core/openexecutive/guide/prebuilt/clients.json
+++ b/packages/core/openexecutive/guide/prebuilt/clients.json
@@ -1,7 +1,7 @@
{
"section_id": "clients",
"title": "Client Companies",
- "markdown": "**What it is:** Multi-client mode for fractional work. Each client is a named **slot** holding a complete, separate company — profile, people, chats, memory, watchlist, everything — and you switch the live workspace between them.\n\n**What it does:**\n\n- Create a client by snapshotting the current company, starting blank, or having AI draft one from your intake notes and attachments.\n- Activate a slot to make it the live company; the previous client's full state is saved back to its slot first.\n- Keep **engagement metadata** on every slot — your role (e.g. Fractional CFO), status, retainer, primary contact, and renewal date — visible across all clients.\n- Get renewal reminders even for clients that are parked.\n\n**How to use:**\n\n1. Open **Settings → Advanced → Client Companies**.\n2. Add a client, one of three ways:\n - **New client** → **From a company** → enter a name → **From current company** (captures what's live now) → **Create**.\n - **New client** → **From a company** → **Blank (onboard fresh)** → **Create**, then **Activate** it and run onboarding.\n - **New client** → **From intake notes** → paste your notes and attach any files → **Draft client** → check it → **Create & activate** (or **Create client** to park it).\n3. Click **Activate** on a client to switch to it. The current client is saved back to its slot first; **Save now** saves it on demand.\n4. Choose **Engagement details** in a client's **⋯** menu to record your role, status, renewal date, retainer, primary contact and notes, then **Save details**.\n\n**Example intake notes:** *\"Kickoff call with Meridian Solar — 120-person residential installer in Arizona, $38M revenue, PE-backed since 2024. I'm their fractional CFO, 10 hours a week, $8K/month retainer, renewal in March. Priorities: 13-week cash forecast and a lender-ready model.\"*\n\n*Note: switching clients swaps the whole working state, so nothing leaks between engagements. Switching is disabled while a simulator company is loaded — unload it first. Single-company users can ignore this screen entirely.*",
+ "markdown": "**What it is:** Multi-client mode for fractional work. Each client is a saved **slot** that holds a complete, separate company: profile, people, chats, schedule, documents, memory, watchlist and MCP tools. One client is active at a time, and you switch between them.\n\n**What it does:**\n\n- Creates a client from the current company, as a blank company, or as a draft written by AI from your intake notes and files.\n- Switches the live workspace to another client. The current client's full state is saved to its slot first.\n- Keeps **engagement details** on each client: your role, status, renewal date, retainer, primary contact and notes.\n- Shows all clients at a glance in the **Practice cockpit** once you have two or more.\n\n**How to use:**\n\n1. Open **Settings → Advanced → Client Companies**.\n2. Click **New client**. Choose one of two tabs:\n - **From a company**: enter the **Client company name**, then under **Start from** choose **From current company** (copies the live company into the new slot and makes it the active client) or **Blank (onboard fresh)** (an empty client; activate it, then run onboarding and upload its documents). Click **Create**.\n - **From intake notes**: paste call notes, a brief or website copy, and use **Attach files** for PDF, Word, Excel, CSV or text files. Click **Draft client**. The AI drafts the profile, people, departments, starter documents and known history from what the material says. Unknowns stay blank and no contact details are imported. Attached files are also saved as the client's documents. Check the name, roster and documents, then click **Create & activate**, or **Create client** to keep it parked. **← Edit notes** goes back.\n3. Click **Activate** on a client to switch to it. The current client is saved to its slot first. If the two clients use different MCP tools, the change applies after the API restarts.\n4. On the active client, **Save now** saves its state to its slot without switching.\n5. In a client's **⋯** menu, **Engagement details** opens your role, **Status** (active, paused, winding down, completed), **Renewal**, **Retainer**, **Primary contact** and **Notes**. Click **Save details**.\n6. **Delete client** in the **⋯** menu removes a parked client's slot. A confirmation asks first. It cannot be undone. The active client cannot be deleted.\n\n**Practice cockpit:**\n\n- With two or more clients, each card shows your role, overdue actions, replies you are waiting on and unread alerts, or \"all quiet\". Parked clients show their state as of their last save.\n- A renewal badge appears 30 days before a client's renewal date and is marked urgent at 7 days or less.\n- **Value report** opens the engagement value report job with that client already filled in.\n- The brief on the active client shows the same summary under **Across your clients**, with a **Manage clients** link back here.\n\n**Good to know:**\n\n- Only the active client is live. Its scheduled actions run and its documents are searched. Parked clients do nothing until you activate them.\n- Your own company is saved automatically the first time you create a client from it or switch to a client.\n- If the install has overnight rotation turned on, each parked client is briefly activated at night to refresh its brief and monitors, then the original client comes back. A notice shows on this page while it runs.\n- While a demo company from the Company Simulator is loaded, you cannot create, switch or save clients. Unload it first.\n- With no clients, nothing changes for single-company use.\n\n**Example intake notes:** *\"Kickoff call with Acme Solar: 120-person residential installer in Arizona, $38M revenue, PE-backed since 2024. I'm their fractional CFO, 10 hours a week, $8K/month retainer, renewal in March. Priorities: 13-week cash forecast and a lender-ready model.\"*",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/company_profile.json b/packages/core/openexecutive/guide/prebuilt/company_profile.json
index 6ad0e230..9822202c 100644
--- a/packages/core/openexecutive/guide/prebuilt/company_profile.json
+++ b/packages/core/openexecutive/guide/prebuilt/company_profile.json
@@ -1,7 +1,7 @@
{
"section_id": "company_profile",
"title": "Company Profile & Onboarding",
- "markdown": "**What it is:** Your company's identity and strategy — mission, market, competitors, financials, and org structure — that grounds everything the Executive says.\n\n**What it does:**\n\n- **Describe your business in your own words** the first time — paste a paragraph, or attach a deck or one-pager. The Executive asks a few follow-up questions, then shows you a filled-in draft profile, team list, and departments.\n- Review and edit that draft before anything is saved; nothing is written until you hit save. Prefer a form? A step-by-step version is linked at the bottom of the setup screen.\n- View and edit every section of the profile inline, any time afterward.\n- Feed this context to all specialists so advice fits *your* company, not a generic one.\n- Kick off background research after setup to suggest things worth watching.\n\n**How to use:**\n\n*First-time setup*\n\n1. Open **Company** in the sidebar and pick the **Set up company** tab (or click **Set up profile →** on the banner in chat).\n2. Describe your business — what you do, who you sell to, roughly how big you are. Optionally **Attach files** (up to 8: a deck, one-pager, or spreadsheet). Click **Get started**.\n3. Answer the follow-up questions (up to 8), or click **Skip ahead — draft my profile now**.\n4. On **Here's what I understood**, edit the profile, **Your team**, and **Departments**. Make sure exactly one person is marked as you. Check **Your sign-in email**: it's filled in with the account you're signed in with, and it's how the Executive knows the person marked as you is you — change it if you're setting this up for someone else. Click **Save & finish setup** — or **Not quite — ask me more questions**.\n\nPrefer filling in fields? Click **Prefer a form? Use the step-by-step version** for a 12-step wizard.\n\n*Afterwards*\n\n- Open **Company** in the sidebar and pick the **Company profile** tab, click **Edit** on any section (Company Basics, Mission & Vision, Target Customer, Competitive Landscape, Strategic Priorities, Financials, and more), make your changes, and click **Save**. List fields take one item per line.\n- **Re-run setup** (in the **⋯** at the top of the profile) takes you back through the conversation. Only the current owner can mark someone else as \"This is me\" when re-running it, because saving makes that person the owner.\n- Ask OE can fill in profile sections for you — you still click **Save**.\n\n**Example description:** *\"We're Northwind Tools — a 40-person B2B SaaS company selling inventory software to independent hardware stores in the US. About $6M ARR, growing 60% a year, Series A last spring. Our main competitors are Lightspeed and spreadsheets. This year's priorities are launching in Canada and getting net revenue retention above 110%.\"*\n\n*Note: until a profile exists, the app nudges you to set one up — it's the foundation the rest builds on.*",
+ "markdown": "**What it is:** Your company's identity and strategy (mission, market, competitors, financials, and org structure) that grounds everything the Executive says. When you use Open Executive just for yourself, it is your **Business profile** (if you own the business) or **Your work**, with the same sections.\n\n**What it does:**\n\n- **Sets up the Executive from your own words** the first time: describe your work, optionally attach a deck, one-pager or CV, and it works out the rest. It asks only about what's missing, then shows you a filled-in draft profile, team list, and departments.\n- Lets you review and edit that draft before anything is saved. Nothing is written until you click **Save & finish setup**. A step-by-step form is linked at the bottom of the setup screen.\n- Lets you view and edit every section of the profile any time afterward.\n- Feeds this context to all specialists so advice fits *your* company, not a generic one.\n- After setup, runs background research and suggests things worth watching.\n\n**How to use:**\n\n*First-time setup*\n\n1. On a new install the app opens setup for you. You can also click **Set up profile →** on the banner on Home, or **Set up company** in the sidebar before a profile exists. Setup opens at `/onboard`, full screen.\n2. **Set up your Executive**: describe your work in the box (what you do, who you sell to, roughly how big you are, what you're focused on this year). Optionally click **+ Attach a one-pager, deck or CV (optional)** (up to 8 files: PDF, Word, Excel, CSV, Markdown or text). Click **Continue**. **Skip, I'll answer questions instead** goes straight to the questions. **I'll do this later** takes you to Home, which keeps setup one tap away.\n3. **Here's what I got** (or **Who is this for?** if you skipped the description): pick **Personal** (your own executive) or **Team** (an executive for the whole company, with a lead for each department) and check what it read: your company and this year's focus, and for Personal your role, title and who you report to. Fix anything that's off and click **Continue**. This saves the mode and your role, which you can change later in **Settings → Workspace**.\n4. Answer the follow-up questions (up to 5; the screen shows how many have been asked). Press Enter to send. Click **Skip ahead — draft my profile now** to stop early.\n5. **Here's what I understood**: edit each profile section. For a team, edit **Your team** (**Add person**, remove someone, tick **This is me** on exactly one person) and **Departments** (**Add department**, each with what it owns, a head and an authority level). For Personal, enter your own name and title. Check **Your sign-in email**: it's filled in with the account you're signed in with, and it's how the Executive knows the person marked as you is you. If you're setting this up for someone else, enter the email they will sign in with. Anything it couldn't work out is listed under **I couldn't determine these**.\n6. Click **Save & finish setup**, or **Not quite — ask me more questions** to go back to the conversation.\n7. **How should your Executive sound?**: pick a voice, or **Skip for now**. You can change it later in Settings.\n8. **Your Executive is ready**: a first question, built from your priorities, is filled in under **Start here**. Edit it and click **Ask your first question**, or **Open Home instead**. The same screen links to connecting the Executive's own email account and letting it read your own mailbox.\n\nA setup in progress survives a refresh or a closed tab: open setup again and it picks up at the same question or draft.\n\nPrefer filling in fields? Click **Prefer a form? Use the step-by-step version** for a wizard of up to 12 questions (fewer for Personal). Later steps are optional and can be skipped.\n\n*Afterwards*\n\n- Open **Company** in the sidebar and pick the **Company profile** tab. Click **Edit** on a section, make your changes, and click **Save** (or **Cancel**). List fields take one item per line. The sections are **Company Basics**, **Mission & Vision**, **Target Customer**, **Competitive Landscape**, **External Dependencies**, **Strategic Priorities**, **Culture & Values**, **Org Structure** and **Financials**.\n- **External Dependencies** holds vendors and tickers. A vendor or ticker named there counts as company data: the Executive starts watching its status page or filings on its own, without asking you first.\n- **Re-run setup**, in the **⋯** at the top of the profile, takes you back through the conversation. A re-run skips the Personal / Team step. Only the current owner can mark someone else as **This is me** when re-running it, because saving makes that person the owner.\n- The help panel (the sparkle button at the top right) can fill in profile sections for you. The section opens with the suggested values and you still click **Save**.\n\n**Who can change it:** anyone signed in can edit the profile sections. Saving setup adds people and makes someone the owner, so once there is an owner only they can hand that role to someone else. The step-by-step form can only be saved by the owner once there is one.\n\n**Example description:** *\"We're Northwind Tools — a 40-person B2B SaaS company selling inventory software to independent hardware stores in the US. About $6M ARR, growing 60% a year, Series A last spring. Our main competitors are Stockly and spreadsheets. This year's priorities are launching in Canada and getting net revenue retention above 110%.\"*\n\n*Note: until a profile exists, Home shows a banner that responses will be generic, with **Set up profile →**.*",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/council.json b/packages/core/openexecutive/guide/prebuilt/council.json
index b58eea32..5751d781 100644
--- a/packages/core/openexecutive/guide/prebuilt/council.json
+++ b/packages/core/openexecutive/guide/prebuilt/council.json
@@ -1,7 +1,7 @@
{
"section_id": "council",
"title": "Agent Council",
- "markdown": "**What it is:** The configuration hub for the specialists behind the Executive — the place to tune how each one thinks and how the Executive sounds.\n\n**What it does:**\n\n- Pick any agent and add instructions, or override its role, system prompt, model, or deep-reasoning toggle.\n- Set the Executive's **voice persona** — the tone it speaks to you in.\n- Test a draft configuration with a one-off query before committing.\n- View version history and roll back, or reset an agent to its built-in default.\n\n**How to use:**\n\n1. Open **Settings → Advanced → Agent Council**. **Quality** at the top sets every agent's model and deep reasoning at once. Under **Your agents**, each main agent is a card with its area and model; an amber dot and **Has your instructions** mean you've already changed it. **Show all agents** lists the internal and helper agents too (**Show fewer agents** hides them again). Click a card to open that agent in a panel with its **Additional instructions**, then click **Save** (or **Cancel**).\n2. For everything else, click **Advanced settings** at the top of the agent's panel (the browser remembers it for every agent; **Simple view** returns, and unsaved edits carry over). The helper agents that are only a model setting (the fast utility model and the research model) always open here. The panel widens and splits the settings into tabs — **Model**, **Instructions**, **Prompt**, **Test** and **History**:\n - **Role** — its one-line job description.\n - **Model** — provider and model; the default is marked *(default)*.\n - **Deep reasoning** — slower, more thorough thinking (not available on Haiku models).\n - **Additional instructions** — a few lines added after its built-in prompt, such as \"Quote figures in EUR\". The agent keeps getting improvements to its built-in prompt. Clear the box to remove them.\n - **System prompt** — its full instructions. Editing it replaces the built-in prompt, so later improvements to it won't reach this agent; prefer **Additional instructions** when you can. **Restore default prompt in editor** brings the original back.\n - **Research focus** — specialists only.\n3. Try it before saving: on the **Test** tab, under **Test this draft**, type a question and click **Run test**. It uses your unsaved settings and changes nothing.\n4. Click **Save** at the bottom of the panel. The change applies on the next call.\n5. To undo, choose **Reset to default** in the **⋯** menu at the bottom of the agent's panel, or open the **History** tab and click **Restore** on an earlier version.\n\n*Change the Executive's voice:* pick one under **Voice** on **Settings → Your Executive**. To write your own, click the **Executive** card in the Council, click **Advanced settings** and open the **Prompt** tab: **Voice Persona** there has the **Active persona** (save it with the main **Save**), and **+ New**, which asks for a display name and a persona body — then click **Create** — or **Duplicate** an existing persona and edit the copy.\n\n**Example persona body:**\n\n```\n- Direct and brief; lead with the recommendation, then the reasoning\n- Plain English, no jargon or buzzwords\n- Numbers over adjectives\n- End with the one decision you need from me\n```\n\n*Note: changes take effect on the next call — no restart needed. This is a power-user surface under Settings.*",
+ "markdown": "**What it is:** The settings page for the agents behind the Executive. You choose how thorough answers are, add instructions to any agent, and change each agent's model and prompt. Changes apply to everyone who uses this Executive.\n\n**What it does:**\n\n- **Quality** sets every agent's model and deep reasoning at once: **Fast**, **Balanced** or **Thorough**.\n- Add **Additional instructions** to any agent, such as \"Quote figures in EUR\".\n- Change an agent's role, model, deep reasoning, system prompt and research focus.\n- Write or edit voice personas for the Executive.\n- Test unsaved settings with a one-off question before you save.\n- Restore an earlier version, or reset an agent to its built-in settings.\n\n**How to use:**\n\n1. Open **Settings → Advanced → Agent Council**.\n2. Pick a preset under **Quality**:\n - **Fast**: a small, fast model for every agent, with deep reasoning off.\n - **Balanced**: each agent's built-in model and deep-reasoning setting.\n - **Thorough**: the largest model for the Executive and the specialists, with deep reasoning on where the model supports it. Background helpers keep their built-in settings.\n A confirmation asks first. Prompts and instructions are not changed, and the earlier settings move to each agent's history. A preset is greyed out when this install offers none of its models. If you change one agent's model by hand, a **Custom** badge appears next to **Quality**.\n3. Under **Your agents**, each card shows the agent's name, its area and a status line: the model name, **Custom ·** followed by the model name when its model differs from the preset, or **Has your instructions** when you changed its instructions, prompt, role or research focus. **Show all agents** adds the internal and helper agents. **Show fewer agents** hides them again.\n4. Click a card to open the agent in a side panel. It opens on **Additional instructions** (up to 4,000 characters). They are added after the agent's built-in prompt on every call, so the agent keeps getting updates to that prompt. Clear the box to remove them.\n5. Click **Save**. The change applies on the next message. **Cancel** drops your edits. Closing the panel another way with unsaved edits asks \"Discard your unsaved changes to this agent?\"\n\n**Advanced settings:**\n\nClick **Advanced settings** in the agent's panel to see every setting. The panel widens into tabs. Your browser remembers this choice for every agent. **Simple view** goes back, and unsaved edits carry over. The two helper agents that are only a model setting (the fast utility model and the research model) always open here.\n\n- **Model** tab: **Role** (its one-line job), **Model** (pick a provider, then a model; the agent's default is marked *(default)*), and **Deep reasoning** (slower, more thorough thinking; not available on Haiku models). The fast utility model has no deep-reasoning switch.\n- **Instructions** tab: the same **Additional instructions** box as the simple view.\n- **Prompt** tab: **System prompt**, the agent's full instructions. Editing it replaces the built-in prompt, so later updates to that prompt will not reach this agent. **Restore default prompt in editor** puts the original back. Specialists also have **Research focus**, the topics they watch in background research scans, with **Restore default research focus in editor**.\n- **Test** tab: under **Test this draft**, type a question and click **Run test**. It uses the unsaved settings in the tabs and saves nothing. The fast utility model has no Test tab.\n- **History** tab: earlier versions of the agent's settings. Click **Restore** on one to go back to it (a confirmation asks first).\n- The **⋯** menu at the bottom of the panel has **Reset to default**. It clears all your changes to that agent and moves them to its history. It is greyed out when the agent has no changes.\n\n**Voice:**\n\nPick the Executive's voice under **Voice** on **Settings → Your Executive**. The Council links there. To write your own voice, open the **Executive** card, click **Advanced settings** and go to the **Prompt** tab. In **Voice Persona**:\n\n- **Active persona** picks the voice. It is saved with the panel's **Save** button.\n- Edit the display name and **Persona body**, then click **Save persona**.\n- **Reset to built-in** undoes your edits to a built-in persona.\n- **Duplicate** makes a copy of the current persona and selects it.\n- **Delete** removes a persona you created (built-in ones cannot be deleted).\n- **+ New** asks for a display name and a persona body. Click **Create**.\n\n**Example persona body:**\n\n```\n- Direct and brief; lead with the recommendation, then the reasoning\n- Plain English, no jargon or buzzwords\n- Numbers over adjectives\n- End with the one decision you need from me\n```\n\n*Note: changes take effect on the next message. No restart is needed.*",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/custom_tools.json b/packages/core/openexecutive/guide/prebuilt/custom_tools.json
index 78d59ab5..db89799e 100644
--- a/packages/core/openexecutive/guide/prebuilt/custom_tools.json
+++ b/packages/core/openexecutive/guide/prebuilt/custom_tools.json
@@ -1,7 +1,7 @@
{
"section_id": "custom_tools",
"title": "Custom Tools",
- "markdown": "**What it is:** When a job needs a tool the Executive doesn't have, it builds one on the spot rather than telling you it can't. A tool it is likely to need again, it keeps — those are your **custom tools**.\n\n**What it does:**\n\n- **Does repetitive work in one go.** \"Create a reminder for each of these renewals\", \"file every scan in this Drive folder\", \"check each of these people's open items\" — instead of working through the list one step at a time, the Executive builds a small tool for the job and runs it once. It's faster, and cheaper in AI usage.\n- **Keeps what works.** When a tool it built did the job and the job will come up again, the Executive keeps it and says so. Next time it reuses the tool instead of building it again.\n- **Works in chat and in workflows.** A workflow step can use the same approach for a folder of hundreds of files. A kept tool is ready in chat straight away; a workflow can use it only after you switch on **Use in workflows** for it, and keeps running the version you switched on until you choose a newer one.\n- **Stays inside the usual limits.** A custom tool can only do what the conversation or workflow using it is already allowed to do: the same tools, the same checks on who it reaches, the same approvals for anything new, and every action in the Audit Log. Only your own conversations can keep a tool or run a kept one — not someone emailing the Executive, a teammate, or a scheduled run.\n\n**How to use:**\n\n1. Just ask for the job — the Executive decides when building a tool makes sense. You can also say \"do that for all of them\" or \"keep that so you can do it again\".\n2. Ask \"what tools have you built?\" to hear what it has kept.\n3. Open **Settings → Advanced → Custom tools** to see each one: what it does, which of your tools it uses, how it works, every version and its recent runs.\n4. Use the switch to turn a tool off, or **Use this one** on an earlier version to go back to it.\n5. Switch on **Use in workflows** to let your workflows use a tool. When the Executive improves it later, workflows stay on the version you approved until you tap **Use version N in workflows**.\n6. See how much work was done this way on **Token usage**, under **Done in one go**.\n\n**Tips:**\n\n- A turned-off tool never runs, and stays off even if the Executive improves it later — only you turn it back on.\n- An operator can switch the whole feature off with `CHAT_SCRIPTS=false` (chat), `WORKFLOW_STEP_SCRIPTS=false` (workflows) or `SAVED_TOOLS_ENABLED=false` (keeping tools).",
+ "markdown": "**What it is:** When a job needs a tool the Executive doesn't have, it builds one on the spot rather than telling you it can't. A tool it is likely to need again, it keeps — those are your **custom tools**.\n\n**What it does:**\n\n- **Does repetitive work in one go.** \"Create a reminder for each of these renewals\", \"file every scan in this Drive folder\", \"check each of these people's open items\" — instead of working through the list one step at a time, the Executive builds a small tool for the job and runs it once. It's faster, and cheaper in AI usage.\n- **Works on files.** For work that needs real file libraries (splitting a PDF, building a spreadsheet, a Word or PowerPoint file, or a chart), it runs Python in a locked-down sandbox with no network access. These file jobs run only in the principal's own chats, never in workflows.\n- **Keeps what works.** When a tool it built did the job and the job will come up again, the Executive keeps it and says so. Next time it reuses the tool instead of building it again. Saving again under the same name adds a new version.\n- **Works in chat and in workflows.** A workflow step can use the same approach for a folder of hundreds of files. A kept tool is ready in the principal's chats straight away. A workflow can use it only after you switch on **Use in workflows** for it, and keeps running the version you switched on until you choose a newer one. Kept file tools (Python) never run in workflows.\n- **Stays inside the usual limits.** A custom tool can only do what the conversation or workflow using it is already allowed to do: the same tools, the same checks on who it reaches, the same approvals for anything new, and every action in the Audit Log.\n\n**Who can keep and run them:**\n\n- Only the principal's own chat turns can keep a tool, or run a kept one in chat. Someone emailing the Executive, or a teammate chatting with it, can't.\n- A workflow (scheduled runs included) runs a kept tool only after the principal switches on **Use in workflows** for it, and only when the workflow step already allows every tool the kept tool uses.\n- Only the account owner can open **Custom tools**. Anyone else sees *Only the account owner can see custom tools.*\n\n**How to use:**\n\n1. Just ask for the job — the Executive decides when building a tool makes sense. You can also say \"do that for all of them\" or \"keep that so you can do it again\".\n2. Ask \"what tools have you built?\" to hear what it has kept.\n3. Open **Settings → Advanced → Custom tools**. Each tool shows its name, what it does, its version, where it was saved from (a chat or a workflow) and when it was last updated, and which of your other tools it uses (a file tool says *Works on files with Python*).\n4. Click **Details, versions and runs** to see **How it works** (the tool's code), every kept **Version** with where it came from, and its **Recent runs** (worked or failed, version, number of tool calls, time taken). **Hide details** closes it.\n5. Use the switch at the top of a tool's card to turn it off or back on. On an earlier version, **Use this one** makes that version the one that runs; the current one says **In use**.\n6. Switch on **Use in workflows** to let your workflows use a tool. When the Executive improves it later, workflows stay on the version you approved until you click **Use version N in workflows**. Turning this on needs signed sign-ins on the server (or a local login), so that nobody else can turn it on for you.\n7. See how much work was done this way on **Token usage**, under **Done in one go** (jobs, actions taken, model turns avoided) and **Work on files** (file jobs, cost of those turns, CPU time, largest job).\n\n**Tips:**\n\n- A turned-off tool never runs, and stays off even if the Executive improves it later — only you turn it back on. Turning a tool off also switches off **Use in workflows**; the workflow switch can't be used while the tool is off.\n- Up to 200 custom tools are kept. Each keeps its 20 newest versions, plus the one in use and the one switched on for workflows.\n- An operator can switch the feature off with `CHAT_SCRIPTS=false` (building tools in chat), `WORKFLOW_STEP_SCRIPTS=false` (in workflows), `PYTHON_JOBS_ENABLED=false` (file jobs) or `SAVED_TOOLS_ENABLED=false` (keeping tools). With `SAVED_TOOLS_ENABLED=false`, the Custom tools page says so: nothing new is kept and none of the kept tools run.",
"mermaid": null,
- "generated_at": "2026-10-07T19:56:34+00:00"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/delegate.json b/packages/core/openexecutive/guide/prebuilt/delegate.json
new file mode 100644
index 00000000..d984ea88
--- /dev/null
+++ b/packages/core/openexecutive/guide/prebuilt/delegate.json
@@ -0,0 +1,7 @@
+{
+ "section_id": "delegate",
+ "title": "Delegate",
+ "markdown": "**What it is:** The place where you decide what the Executive may do without asking you. **Delegate** is in the main menu. It has four tabs: **What it may do**, **Act as me**, **Handle it for me** and **Take the lead**. Clicking **Delegate** opens **What it may do**.\n\n**What it does:**\n\n- **What it may do** lists everything that can go out without asking you, who it goes out as, and the setting that allows it. It only reads. Nothing on it changes a setting.\n- **Act as me** lets the Executive write email drafts *as you*, from your own Gmail or Outlook mailbox. You send them. It can also write first replies to mail in your inbox that needs you.\n- **Handle it for me** lets it send some of those replies, and some follow-ups, on its own from your mailbox.\n- **Take the lead** (the owner only) lets the Executive act in its own name on what it finds, without waiting to be asked.\n- Normally the Executive writes only as itself, from its own email account. Nothing goes out as you unless you set it up here.\n\n**How to use:**\n\n1. Click **Delegate** in the sidebar. (On a phone, open the menu with the button at the top left.)\n2. Read **What it may do** to see what goes out on its own today.\n3. Open **Act as me**, connect your mailbox, and pick what it writes as you.\n4. If you want replies sent for you, open **Handle it for me** and pick how much it sends on its own.\n5. If you are the owner, open **Take the lead** to let the Executive act in its own name.\n\n**What it may do:**\n\n- Three pills: **As you**, **As the Executive** and **Departments**. The number on each pill is how many things go out without asking.\n- **As you** covers your own mailbox: emails you ask for in chat, inbox replies, what Handle it for me sends, what is in training, what it has learned and your own rules.\n- **As the Executive** covers Take the lead, its Always asks first switches, the company's rules and meetings. Only the owner sees this pill.\n- **Departments** shows each department's authority level and what that level covers.\n- Each row has **What**, **Then** and **Why**. The dot by **Then** shows what happens: green goes out, amber waits for you, red always waits, grey is drafts only or off. **Why** links to the tab or page where the setting lives.\n- While the Executive is paused, a note at the top says nothing runs on its own, with a **Resume** link.\n- Someone who is not on the People list sees \"Only people on the team can see this.\"\n\n**Act as me:**\n\n- Who can use it: the owner. Team members can use it once the owner turns on **Let team members use it** (under **Advanced** on this tab). That switch shows only when the install allows it. Anyone else sees \"Act as me isn't available to you here.\"\n- Each person connects their own mailbox and turns it on for themselves. What it reads in your mail, the drafts it writes and your reply cards are yours alone. The owner sees only each team member's name, how many drafts they had written and sent in the last 30 days, and whether inbox replies are on. A conversation in which it read someone's mail can be opened only by that person.\n- **Your mailbox**: until it is connected, the card shows the command to run on a computer with a browser (one for Gmail and, where the install supports it, one for Outlook). Sign in as yourself, put the file it writes where the API reads it, then click **Check again**. Once connected it shows \"Connected to\" your address. It won't connect the Executive's own address as yours.\n- **What it writes as you**: \"Nothing goes out until you send it.\" Pick one:\n - **Off**: the Executive only writes as itself.\n - **When I ask**: ask in chat, \"reply to Dana as me: yes to the 5th\", and the draft waits in your Gmail or Outlook Drafts.\n - **For my inbox too**: it also writes a first reply to mail that needs you, and puts it on Home.\n- You can't move up from **Off** until your mailbox is connected. Moving down asks first, says what stops, and saves when you click **Move down**. Moving to **When I ask** stops inbox replies. Moving to **Off** stops everything it writes as you and turns **Read my calendar** off. Either one also stops Handle it for me if it was sending.\n- **Learn from my edits** (a checkbox once you are above **Off**): when you change a draft before sending, tick **Do it like this next time** and it learns how you write to that person. Nothing more is sent.\n- **Read my calendar**: a switch. On, it reads your own calendar when you ask about your day or week in chat. It never changes your calendar. It stays off while **What it writes as you** is at **Off**. If your mailbox sign-in doesn't include your calendar, the card shows a command to run once to add it.\n- **Suggested actions**: meeting invites and messages your mail calls for. **Always ask** brings each one to you as a card, every time. **In training** also brings each one as a card; tap **Approve + allow** and it does that kind, with those people, on its own next time.\n- **What it's learned**: what it learned from your edits (drafts) and your approvals (suggested actions). Each item says when, how many times it has been used since, and an example. **Remove** forgets it, and it asks you again.\n- **Advanced** (closed by default) holds **How I write**, **AI line on drafts you send** (shown only when the install adds an AI line to mail) and, for the owner, **Let team members use it**.\n\n**Asking in chat:**\n\n- Ask in the web app (signed in), in a direct message to the Executive on Slack or Discord, or in a private Telegram chat: \"reply to Dana as me: yes to the 5th.\"\n- It saves a draft in your own Drafts and shows a card, \"Drafted an email as you to Dana — in your Drafts\". Asking in chat never sends anything.\n- It does not write as you in a shared channel or thread, on Google Chat, from an email, from a scheduled job or in anyone else's conversation.\n- If it isn't sure about something, it asks you instead of guessing.\n- There is a daily limit on drafts written as one person (50 a day unless the install changes it).\n\n**For my inbox too:**\n\n- About every five minutes it looks at new mail in your inbox. For mail that needs a personal reply from you (a question, a request, a meeting to arrange, an introduction or a follow-up), it writes a first reply and puts it at the top of **Needs you** on Home.\n- It only looks at mail that arrives after you turn it on. It leaves out newsletters, notifications, mailing lists, automatic mail, mail you are not in To or Cc on, mail you've already answered and anything that doesn't need you. Mail you answer within ten minutes never gets a draft.\n- The first reply only acknowledges. It repeats only what you've already said in the thread, commits you to nothing and lists what's left for you to decide. Someone you've never written to gets a short holding reply.\n- Under the picker you see how it is doing (for example, that your mailbox needs connecting again) and when it last looked. Click **Check now** to look straight away.\n- **Also save inbox replies in my Gmail Drafts** (or Outlook): off by default, so replies wait on their cards only. Tick it to keep each reply in your Drafts too.\n- On each card on Home: **Send** asks you to confirm who it goes to, then **Send now**. **Send + allow** (in training) sends it and lets replies to that person go on their own from then on. **Edit** changes the words on the card. **Open in Gmail** opens it when it is in your Drafts. **Dismiss** removes the card.\n- Limits: at most 5 drafts a check and 20 a day unless the install changes it, 2 a day per sender (1 for a stranger), and never more than 25 cards open. A card closes when the draft is sent or deleted in your mailbox, when you reply yourself, or after 7 days.\n\n**How I write (under Advanced):**\n\n- Shows your style as a few sentences, with where it came from (\"Learned from N of your sent emails\", or \"Set by you\") and whether it is locked.\n- **Describe it in your own words**: write how you write, the way you'd tell a new assistant (up to 2,000 characters). Buttons add common phrases, such as \"Short and to the point\" or \"No emojis\". Click **Write my style**; it shows the new style with new lines marked **New** and a sample reply. Click **Save** to keep it or **Change it** to edit your words. Nothing changes until you save.\n- **Learn from my sent mail** (or **Learn again from my sent mail**): reads your recent sent emails once and describes how you write. It needs your mailbox connected and is hidden while the style is locked.\n- **Fine-tune details** opens the fields: **Length** (short, medium, long), **Tone** (casual, neutral, formal), a **Greeting** **To your team**, **To your contacts** and **To anyone else** ({first} becomes their first name), **Sign-off**, **Habits** and **Never** (one per line), your **Signature** and **Examples of your writing**.\n- **Save changes** saves the fields. **Lock** stops it being relearned from your mail (you can still edit it); **Unlock** undoes that. **Reset** starts over. **Remove examples** drops the examples.\n- **Signature**: with Gmail, your signature is added to every draft. **Refresh from Gmail** picks up a change you made in Gmail, **Don't add my signature** stops adding it, and **Add my Gmail signature** brings it back. Outlook doesn't share signatures with apps, so Outlook drafts end with your sign-off.\n- **AI line on drafts you send**: a checkbox for whether drafts you approve and send end with the install's AI line. Off unless the install starts it on. A change applies to the next reply it writes.\n\n**Handle it for me:**\n\n- It sends from your own mailbox, on its own, some of the replies Act as me writes for your inbox, and some follow-ups.\n- It needs **For my inbox too** on the Act as me tab. Until then the card says so and offers **Turn on For my inbox too**, or **Connect your mailbox in Act as me** if your mailbox isn't connected.\n- Someone who can't have Act as me sees that Handle it for me isn't available to them.\n- **What it sends on its own**: pick one:\n - **Off**: every reply waits for you to send.\n - **Easy ones**: only short replies to people you know, when it's very sure. Follow-ups are written for you and wait on Home.\n - **People I know**: replies to people you know. Strangers, links and amounts wait for you. Follow-ups go to your team and contacts when they haven't answered a question of yours in a few days.\n - **Most mail**: also strangers and longer replies, and links or amounts when it's very sure. Follow-ups go to anyone you wrote to who hasn't answered a question of yours in a few days.\n - **Everything** (the owner only): it decides what to send as you. Replies with a link, the topics that always wait and your rules still hold it back.\n- The sending steps need signed sign-ins on the server. Without them they are greyed out with \"Needs signed sign-ins on this server.\" Moving down asks first and saves when you click **Move down**.\n- **In training**: every reply comes to you first. Tap **Send + allow** on a card and it handles that person on its own from then on, within the step you picked. You can tick it at **Off** before moving up. **Train follow-ups too** (shown while in training) keeps follow-ups in training as well; untick it to let follow-ups go out while replies stay in training. **Everything** opens only once it's out of training, and training can't be turned on at **Everything**.\n- Money, contracts, legal, hiring, the press and passwords always wait for you. It never writes to anyone the email didn't go to. A reply that names the Executive waits too.\n- **Your rules** (at **Everything**): replies matching one wait for you, on top of the company's rules. Pick **A person**, **A company**, **Words** or **An amount**, type the value and click **Add rule**. **Remove** deletes one.\n- **What it sent** (while it is on): \"Sent N replies on its own today\", then each reply and follow-up from the last week: who it went to, the subject, **Still yours to answer** for questions it left for you, and **Open in your mailbox**.\n- **Who it's allowed to handle**: the people you allowed with **Send + allow**. **Remove** takes one off, and it asks you again.\n- **AI line on replies it sends** (under **Advanced**, when the install adds an AI line): on by default. Turning it off asks you to confirm with **Turn it off** or **Keep it on**.\n- Limits: 20 replies sent on its own a day unless the install changes it, and one a conversation. Past the limit, replies wait on cards.\n\n**Take the lead:**\n\n- The owner's alone. Anyone else sees \"Only the account owner can turn this on.\"\n- **Off**: when it looks over your day, it tells you what it would do, and you do it.\n- **In training**: everything it would do comes to you as a card on Home first. What you allow, it does on its own from then on.\n- **On**: it acts on what it finds while it looks over your day: it messages people, books meetings and starts workflows. Anything under **Always asks first** waits for a yes.\n- **In training** and **On** need signed sign-ins on the server.\n- **What it's learned**: the actions you allowed with **Approve + allow** on a card, or **Send + allow** on an Act as me reply. **Remove** takes one off. Something you approved unchanged three times shows as a suggestion with **Allow**.\n- **Always asks first**: a switch for each: **Money**, **Contracts and legal**, **Hiring and people decisions**, **Deleting, cancelling or sharing**, **Someone new** and **Big sends** (company-wide or department-wide, or more than five people). These wait for you, or for whoever approves that area, with a card on Home. **Meetings asked for in chat** is the last row: meetings you or a teammate ask it to book (in a team, Operations must also act on its own). A meeting it thinks of itself always waits. While Take the lead is off, only the meetings row applies.\n- Department levels don't hold what it does here. The switches and rules do.\n- **Company rules**: anything matching one always waits for a yes, for the Executive and for everyone's sending as themselves. Add them the same way as **Your rules**.\n- **Pause** on **Settings → Your Executive** stops everything on this tab. Anything you tap **Send** or **Approve** on still goes.\n\n**Example prompts:**\n\n- \"Reply to Dana as me: yes to the 5th, and ask her to send the deck first.\"\n- \"Write to the Acme team as me and push our call to Thursday.\"\n- \"What's on my calendar tomorrow?\" (with **Read my calendar** on)\n",
+ "mermaid": null,
+ "generated_at": "2026-10-15T21:00:00Z"
+}
diff --git a/packages/core/openexecutive/guide/prebuilt/departments.json b/packages/core/openexecutive/guide/prebuilt/departments.json
index 465db644..c4537efb 100644
--- a/packages/core/openexecutive/guide/prebuilt/departments.json
+++ b/packages/core/openexecutive/guide/prebuilt/departments.json
@@ -1,7 +1,7 @@
{
"section_id": "departments",
"title": "Departments",
- "markdown": "**What it is:** The org units the Executive works through. Each department has goals, an authority level, a head, and a specialist agent behind it.\n\n**What it does:**\n\n- View every department with its goal count and health (on-track / at-risk / off-track).\n- Create departments and give them a mission, goals, budget, and headcount.\n- Set the **authority level** — act automatically, propose for approval, or always escalate.\n- Wire up a head person and team channels (Slack, Discord, Telegram).\n\n**How to use:**\n\n1. Open **Company** in the sidebar, pick the **Departments** tab, and click **Add department**. Enter a **Name** (and, optionally, a mission) and click **Create**. New departments start at *Proposes, you approve*.\n2. Open the department and click **Edit settings**. The settings open in a side panel, split into tabs (**Charter**, **How it acts**, **Numbers**, **Channels**, **Watched**):\n - **Department head** — the person who owns it.\n - **Authority level** — **Acts on its own**, **Proposes, you approve**, or **Escalates to a person**.\n - **Recurring check-in** — when the department reviews its goals: **Daily** (pick a time), **Weekly** (pick a day and a time) or **Off**. New departments check in weekly, on Monday at 09:00; times are UTC. The department page shows when the next check-in is due, and a change takes effect straight away.\n - **Headcount** and **Budget (USD)**.\n - **Team channels** — a Slack channel ID, Discord channel ID or Telegram chat ID. Leave them blank and messages go to the department head by DM.\n - **Watched entities** — one per line.\n\n Then click **Save settings**.\n3. Click **Add goal**: pick a timeframe (week, month, quarter, year, or ongoing), enter the **Key result** and **Target** (and current progress if you know it), set a status, and click **Add goal**. Each goal's **⋯** menu has **Edit goal** and **Delete goal**.\n4. Keep goals current by just telling the Executive what happened — it updates the matching goal and records why.\n5. Set a new goal the same way: tell the Executive the target, and it adds the goal under the right department (or area), creating that department if you don't have one yet. Only the owner can do this, from the web app or their own Slack or Discord — a teammate, or an email, can't. It adds one goal for each target you actually give it (at most 8 per department this way) — ask it to \"set up some goals\" and it asks you which ones.\n\n**Examples from chat:** *\"We closed 40% of the Q3 ARR target.\"* · *\"We lost the Acme deal.\"* · *\"New Sales goal: 20 paying customers by December 31.\"* · *\"Make Sarah the head of Marketing.\"*\n\n**Goals page:** the **Goals** tab of **Company** (of **You** when you use Open Executive just for yourself) lists every goal in one place, grouped by department — called an **area** when it's just you. Each goal shows its status, timeframe, target and where it stands now, with **Edit goal** and **Delete goal** in its **⋯** menu. Click **Add goal**, pick the department (or **Area**) it belongs to, and fill it in as above; ones with no goals yet are listed at the bottom so you can start one there.\n\n**Just for yourself?** In that mode department check-ins are paused and **Company** becomes **You**, with **Goals** and no **Departments** tab. The departments are still there — open `/departments` to rename an area or change its settings.\n\n*Note: the authority level is what decides whether the Executive acts on its own or asks first within that department's scope.*",
+ "markdown": "**What it is:** The org units the Executive works through. Each department has a mission, goals, an authority level, a head, and a specialist agent behind it.\n\n**What it does:**\n\n- Lists every department as a card with its authority (**Auto**, **Propose** or **Escalate**), the start of its mission, its goal count, and a status pill (on track / at risk / off track).\n- Creates departments and gives them a mission, goals, budget, and headcount.\n- Sets the **authority level**: act on its own, propose for approval, or always escalate.\n- Sets a department head and team channels (Slack, Discord, Telegram).\n- Runs a recurring check-in where the specialist reviews the department's goals.\n\n**How to use:**\n\n1. Open **Company** in the sidebar, pick the **Departments** tab, and click **Add department**. Enter a **Name** (and, optionally, a **Mission**) and click **Create**. New departments start at *Proposes, you approve* and check in weekly.\n2. Open the department. The page shows its specialist, how it acts, its mission, head, headcount, budget, channels, watched entities, its check-in schedule with when the next one is due, and its **In scope** / **Out of scope** lists when it has them. It refreshes every 30 seconds.\n3. Click **Edit settings**. The **Department settings** panel opens with five tabs:\n - **Charter**: the **Mission**.\n - **How it acts**: the **Department head** (a team member; the Executive treats them as the department's owner in routing), the authority level (**Acts on its own**, **Proposes, you approve** or **Escalates to a person**), and the **Recurring check-in**: **Daily** (pick a time), **Weekly** (pick a day and a time) or **Off**. Times are UTC. New departments check in on Monday at 09:00. A change takes effect straight away.\n - **Numbers**: **Headcount** and **Budget (USD)**.\n - **Channels**: a Slack channel ID, Discord channel ID or Telegram chat ID. When set, the Executive can post department updates there. Left blank, messages go to the department head by DM.\n - **Watched**: **Watched entities (one per line)**, such as vendors, competitors or tickers. The Executive starts watching their status pages, filings and feeds on its own and sends what it finds to this department and its head.\n\n Then click **Save settings**, or **Cancel** to drop the changes.\n4. Click **Add goal**. Type **What's the goal?** (the only required field), pick a timeframe chip (**This week**, **This month**, **This quarter**, **This year** or **Ongoing**; the default is this quarter), optionally fill in **Target** and **Where it stands now**, and click **Add goal**. A new goal starts on track until a check-in grades it.\n5. Each goal shows its status, timeframe, target, where it stands now, and when it was last reviewed (marked if that was more than 10 days ago). Its **⋯** menu has **Edit goal** (change the goal, timeframe, status, target and where it stands now, then **Save**) and **Delete goal**.\n6. **Delete department**, in the **⋯** menu next to **Edit settings**, removes the department and all its goals. It can't be undone.\n\n**What the authority level covers:** the department's check-ins, scheduled messages and alerts, and what its team members ask for in chat. Operations also covers meetings people ask for. It doesn't cover what the Executive does on its own under Take the lead; **Always asks first** there holds that.\n\n**From chat:**\n\n- Tell the Executive what happened and it updates the matching goal's status and progress, and records why.\n- Tell it a new target and it adds the goal under the right department (or area), creating that department if you don't have one yet. Only the principal can do this, from the web app or their own Slack or Discord. A teammate or an email can't. It adds one goal for each target you actually give it: at most 5 in one message and at most 8 per department this way. Ask it to \"set up some goals\" and it asks you which ones.\n- Ask it to make someone the head of a department.\n\n**Examples from chat:** *\"We closed 40% of the Q3 ARR target.\"* · *\"We lost the Acme deal.\"* · *\"New Sales goal: 20 paying customers by December 31.\"* · *\"Make Sarah the head of Marketing.\"*\n\n**Goals page:** the **Goals** tab of **Company** (of **You** when you use Open Executive just for yourself) lists every goal in one place, grouped by department (called an **area** when it's just you). The top line counts the goals and how many are off track, at risk and on track. Each goal has **Edit goal** and **Delete goal** in its **⋯** menu. Click **Add goal**, pick the **Department** (or **Area**) it belongs to, and fill it in as above. Departments with no goals yet are listed at the bottom; click one to start a goal there. With no departments at all, add one on the Departments tab first.\n\n**Who can change it:** anyone signed in can add, edit and delete departments and goals on these pages.\n\n**Just for yourself?** In that mode department check-ins are paused (the department page says so) and **Company** becomes **You**, with **Goals** and no **Departments** tab. The departments are still there. Open `/departments` to change an area's settings. A department can't be renamed on these pages.\n\n*Note: the authority level is what decides whether the Executive acts on its own or asks first within that department's scope.*",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/integrations.json b/packages/core/openexecutive/guide/prebuilt/integrations.json
index 3359bfd1..922e7245 100644
--- a/packages/core/openexecutive/guide/prebuilt/integrations.json
+++ b/packages/core/openexecutive/guide/prebuilt/integrations.json
@@ -1,7 +1,7 @@
{
"section_id": "integrations",
"title": "Integrations",
- "markdown": "**What it is:** The channels that connect the Executive to where your team already works — so proposals, updates, and replies flow through familiar tools instead of just the web app.\n\n**What it does:**\n\n- **Slack / Google Chat:** receive messages and thread replies, send proposals and alerts.\n- **Discord / Telegram:** direct-message conversations for proposals and approvals.\n- **Email:** poll for inbound mail and send outbound replies.\n- **Google Workspace:** the Executive can send and draft Gmail (recipients limited to your People roster) and manage Calendar events, including Google Meet links.\n- **Microsoft 365:** the Executive can send, reply to and draft Outlook mail and manage Outlook calendar events with Teams links (recipients and attendees limited to your People roster). Its own inbox and calendar can run on either Google or Microsoft — a per-install setting, not a per-message choice.\n- **MCP:** expose the Executive's specialist council and company context to external AI tools.\n\n**How to use:**\n\n*Before anyone can use a channel,* an administrator turns it on (see *Setup* below) and restarts the app. Then add each person's channel ID under **People → Contact & routing** — Slack, Discord and Telegram only answer people on your roster. **Settings → Advanced → Setup status** then shows whether each channel is working, and what to do if it isn't.\n\n*Talking to the Executive*\n\n- **Slack** — DM the app, or @mention it in a channel; it replies in a thread. Keep replying in that thread without mentioning it again.\n- **Discord** — DM the bot or @mention it (it usually answers in a new thread). Or use the slash commands `/ask` and `/today`.\n- **Telegram** — message the bot directly; text, documents and photos all work.\n- **Google Chat** — DM the app, or add it to a space and @mention it.\n- **Email** — send mail to the Executive's address; it picks up unread inbox mail on a regular poll.\n- **Signing off a paused workflow** — reply in the thread on Slack, Discord or Telegram: \"yes\", \"LGTM\", \"no\", \"not now\".\n\n**Example (Slack):** *\"@Executive what's blocking the Q3 hiring plan?\"* — the answer arrives in a thread, and you can follow up there.\n\n*Setup (administrators)* — each channel is switched on with environment settings:\n\n| Channel | Settings |\n|---|---|\n| Slack | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` (Socket Mode) |\n| Discord | `DISCORD_BOT_TOKEN`, `DISCORD_APP_ID`; enable the bot's Message Content intent (see the README) |\n| Telegram | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`; webhook at `/webhook/telegram` |\n| Google Chat | `GOOGLE_CHAT_PROJECT_NUMBER` plus a service account — see `docs/google_chat_setup.md` |\n| Email, Gmail & Calendar | `EXEC_EMAIL_ADDRESS` plus the Google Workspace connection — see `docs/deployment.md` |\n| Microsoft 365 | `MS365_MCP_CLIENT_ID`, `MS365_MCP_TENANT_ID`, `MS365_MCP_EXPECTED_USERNAME`, then a one-time sign-in with `ms365-mcp-launch.sh --login` — see `docs/deployment.md`. `EMAIL_PROVIDER` / `CALENDAR_PROVIDER` choose whether the Executive's own inbox and calendar are Google or Microsoft |\n\n*Use the Executive from other AI tools (MCP)* — the API serves an MCP endpoint at `/mcp`; clients authenticate with the backend shared secret. In Claude Code:\n\n```bash\nclaude mcp add --transport http open-executive http://localhost:8000/mcp \\\n --header \"x-api-key: YOUR_BACKEND_SHARED_SECRET\"\n```\n\nOther MCP clients take the same URL and `x-api-key` header. They get `ask_executive`, `consult_specialist`, `search_knowledge` and `list_workflows`, plus read-only company context.\n\n*Note: every channel is recorded in the Audit Log. Replying to approve a paused workflow works on Slack, Discord and Telegram only — not email or Google Chat. Channels are turned on with environment configuration, not from this screen.*",
+ "markdown": "**What it is:** The channels that connect the Executive to where your team already works, so proposals, updates and replies reach people in familiar tools instead of only the web app.\n\n**What it does:**\n\n- **Slack / Google Chat:** receive direct messages and mentions, reply in threads, and send proposals and alerts.\n- **Discord / Telegram:** direct-message conversations for questions, proposals and approvals.\n- **Email:** the Executive reads its own inbox on a regular poll and replies from its own address.\n- **Google Workspace:** the Executive can send and draft Gmail (recipients limited to your People roster) and manage Calendar events, including Google Meet links.\n- **Microsoft 365:** the Executive can send, reply to and draft Outlook mail and manage Outlook calendar events with Teams links (recipients and attendees limited to your People roster). Its own inbox and calendar can run on either Google or Microsoft. This is a per-install setting, not a per-message choice.\n- **MCP:** expose the Executive's specialist council and company context to external AI tools.\n- Everything the Executive sends on these channels as itself ends with a line saying it is an AI assistant, unless the install turns that off.\n\n**How to use:**\n\n*Before anyone can use a channel,* an administrator turns it on with environment settings (see *Setup* below) and restarts the app. There is no page in the app for turning channels on or off. Then add each person's channel ID under **People → Contact & routing** (**Slack user ID**, **Discord user ID**, **Telegram chat ID**). The person's **Preferred channel** there decides where proposals routed to them are sent. **Settings → Advanced → Setup status** then shows whether each channel is working, when it last received a message, and what to do if it isn't working.\n\n*Talking to the Executive*\n\n- **Slack**: DM the app, or @mention it in a channel; it replies in a thread. Keep replying in that thread without mentioning it again.\n- **Discord**: DM the bot, or @mention it in a server channel (it answers in a new thread). Or use the slash commands `/ask` and `/today`.\n- **Telegram**: message the bot directly in a private chat. Text, documents and photos all work.\n- **Google Chat**: DM the app, or add it to a space and @mention it.\n- **Email**: send mail to the Executive's address. It picks up unread inbox mail on a regular poll (every 60 seconds unless the install changes it).\n- **Signing off a paused workflow**: reply in the thread on Slack, Discord or Telegram: \"yes\", \"LGTM\", \"no\", \"not now\".\n\n*Who it answers*\n\n- Slack, Discord, Telegram and email answer only people on your People list.\n- When someone who isn't on the list writes to it directly, their message is held. They get one fixed reply saying it arrived and is waiting for confirmation. The owner gets a card on Home and a message on their preferred channel asking who it is. Once the owner confirms them, the held messages are answered.\n- In a Slack channel the \"waiting\" reply is shown only to the sender. In a Telegram group, nothing is sent.\n- Google Chat answers anyone in a space it is in. It reads attached files only from people on your People list.\n- Files shared on Slack, Discord, Telegram and Google Chat are read only for people on your People list.\n\n*Writing as you*\n\n- **Act as me** (under **Delegate**) works in a direct message to the Executive on Slack or Discord and in a private Telegram chat, as well as in the web app. It does not work in a shared channel or thread, on Google Chat or by email. See the Delegate section of this guide.\n\n**Example (Slack):** *\"@Executive what's blocking the Q3 hiring plan?\"* The answer arrives in a thread, and you can follow up there.\n\n*Setup (administrators)* — each channel is switched on with environment settings:\n\n| Channel | Settings |\n|---|---|\n| Slack | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` (Socket Mode). Or, on a server Slack can reach, leave `SLACK_APP_TOKEN` unset, set `SLACK_SIGNING_SECRET` and point the app's Event Subscriptions at `/webhook/slack` |\n| Discord | `DISCORD_BOT_TOKEN`, `DISCORD_APP_ID`; enable the bot's Message Content intent (see the README). Optional: `DISCORD_NOTIFY_CHANNEL_ID` for alerts |\n| Telegram | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`; webhook at `/webhook/telegram`; see `docs/telegram_setup.md` |\n| Google Chat | `GOOGLE_CHAT_PROJECT_NUMBER` plus a service account (`GOOGLE_CHAT_SERVICE_ACCOUNT_FILE` or `GOOGLE_CHAT_SERVICE_ACCOUNT_EMAIL`); webhook at `/webhook/google-chat`; see `docs/google_chat_setup.md` |\n| Email, Gmail & Calendar | `EXEC_EMAIL_ADDRESS` plus the Google Workspace connection — see `docs/deployment.md`. `EMAIL_POLL_INTERVAL_SECONDS` sets how often the inbox is read |\n| Microsoft 365 | `MS365_MCP_CLIENT_ID`, `MS365_MCP_TENANT_ID`, `MS365_MCP_EXPECTED_USERNAME`, then a one-time sign-in with `ms365-mcp-launch.sh --login` — see `docs/deployment.md`. `EMAIL_PROVIDER` / `CALENDAR_PROVIDER` choose whether the Executive's own inbox and calendar are Google or Microsoft |\n\n*Use the Executive from other AI tools (MCP)* — the API serves an MCP endpoint at `/mcp`; clients authenticate with the backend shared secret. In Claude Code:\n\n```bash\nclaude mcp add --transport http open-executive http://localhost:8000/mcp \\\n --header \"x-api-key: YOUR_BACKEND_SHARED_SECRET\"\n```\n\nOther MCP clients take the same URL and `x-api-key` header. They get `ask_executive`, `consult_specialist`, `search_knowledge` and `list_workflows`, plus read-only company context: the company profile, the Today briefing, recent activity, the People roster, department state, and remembered decisions, initiatives and advice.\n\n*Note: every channel is recorded in the Audit Log. Replying to approve a paused workflow works on Slack, Discord and Telegram only, not email or Google Chat. While the Executive is paused, chat and direct messages on every channel still get answers.*\n",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/jobs.json b/packages/core/openexecutive/guide/prebuilt/jobs.json
index 5e4e8224..0f1c5a19 100644
--- a/packages/core/openexecutive/guide/prebuilt/jobs.json
+++ b/packages/core/openexecutive/guide/prebuilt/jobs.json
@@ -1,7 +1,7 @@
{
"section_id": "jobs",
"title": "Workflows",
- "markdown": "**What it is:** Structured, multi-step workflows that produce a *deliverable* — a board deck, a go-to-market plan, a performance review — or *get something done* with your connected tools, like filing emailed bills into a spreadsheet, rather than just a chat reply.\n\n**What it does:**\n\n- Start from **What do you want to get done?** at the top of the page: say what you want done in a sentence, or pick a suggestion.\n- When you use Open Executive just for yourself, the suggestions and the first ready-made picks fit someone running the business alone: a Friday cash and pipeline check, which customers stopped buying, a monthly review, pricing, churn and the quarter's plan. A team sees the board and investor ones.\n- Your own workflows sit under **Your workflows**, each with **Run** and a **⋯** menu (**Edit**, **Delete**). **Browse N ready-made** opens the full ready-made list in a side panel, with search and area chips (**System** holds the workflows Open Executive runs on its own, like the morning brief).\n- Start a run and watch it stream its progress step by step.\n- See your runs under **Runs** (in the switch beside **Your workflows**), split into **Active**, **Awaiting sign-off**, **Done**, and **Error**, and search them by name.\n- Create your own **custom workflow** by describing it: the assistant asks a few clarifying questions, then drafts it for you to review.\n- Let a workflow **use tools** — Gmail, Google Sheets, Drive and anything else connected — to actually do the work, not just write about it.\n- Put a custom workflow on a **schedule** (e.g. every Monday at 09:00) so it runs without being asked.\n- Each finished run produces a document you can read and keep.\n- Read and edit **How it's done** on a workflow's page — the method the Executive follows in that workflow and in chat (see **How it's done** in this guide). **Quick** workflows in the ready-made list are one question, one document. A custom workflow's specialist step can **Follow a playbook** too.\n\n**How to use:**\n\n*Run a workflow*\n\n1. Open **Work** in the sidebar (it opens on **Workflows**), click **Browse N ready-made**, and narrow the list with the chips or the search box. Click a workflow to open it.\n2. Fill in the fields (required ones have a red \\*). **Use example** next to a field, or **Fill with an example** for the whole form, fills in realistic values if you just want to try it.\n3. Click **Continue**, then **Run workflow**. Progress streams step by step; when it finishes you land on the run page, with **Copy** and **Download .md**.\n\n*Build your own*\n\n1. Under **What do you want to get done?**, describe the job in plain words — what it should produce, who it's for, and how often — or pick one of the suggestions, then click **Start**. (The **⋯** beside **Start** has **New workflow**, which opens the same conversation, **New workflow, step by step**, which opens the advanced editor, and **Talk it through in chat**, which starts a chat.)\n2. Answer the clarifying questions (usually two or three) by typing or by clicking a suggested answer. **Draft it now** skips the rest.\n3. Review the draft: its steps, schedule, what you fill in each run, the assumptions it made, and the **tools** each action step will use (ones that can change things are marked).\n4. Click **Create workflow** — this approves those tools, and runs use them without asking again — or **Keep refining** and type what to change, or **Edit details** to fine-tune it field by field. It appears under **Your workflows**, with **Edit** and **Delete** in its **⋯** menu.\n\n*Advanced editor* — reached from **New workflow, step by step** in the **⋯** beside **Start**, **Edit** on a custom workflow, **Edit details** on a draft, or **Use the advanced editor**:\n\n1. **Details:** a unique **Name** in snake_case (e.g. `weekly_competitor_watch`; 3–49 characters, starting with a letter), a title, description, section and estimated minutes.\n2. **Input fields:** click **+ Add field** for anything the person running it must supply. Use a field in a step's goal as `{field_name}`.\n3. **Steps:** add **+ Specialist** steps (pick a specialist, write its goal), **+ Action** steps (write what to get done and where, then **Search tools** and **+ Add** the ones it may use), and, if someone must sign off, an **+ Approval gate** (who to ask, the question, a timeout, and what happens on timeout). New steps are added at the bottom — use **↑** to move them above the synthesis step, which pulls everything together and must stay last; put an approval gate just before it. Up to 12 steps and 16 input fields.\n4. **Schedule (optional):** tick **Run on a schedule**, enter a cadence, and choose who the result is delivered to. Scheduled workflows can't have required inputs or approval gates.\n5. Click **Create workflow** (**Save changes** when editing).\n\nCadences are written like this (times are UTC): `daily@09:00`, `weekly@mon@09:00`, or `quarterly@01-09:00` (the 1st of January, April, July and October).\n\n*Workflows that use tools* — describe the job and where things live, e.g. *\"Every morning, find the bills I email you, read each PDF and add a row (vendor, amount, due date) to my Bill tracker sheet.\"* The assistant finds the right tools (here Gmail search and attachments, reading PDFs, and appending rows to Google Sheets) and asks about anything it needs, like which sheet. While a run works, the run page shows each tool as it's used, and the result lists every action taken. A workflow can only use the tools you approved, and every tool call is recorded in the audit log. You can also ask for one in chat: a workflow that uses tools is saved **switched off**, and the Executive gives you a link. It shows under *Waiting for your approval* at the top of **Your workflows**; open it, check the steps and tools, and click **Turn on workflow** — until then it can't run or follow a schedule.\n\n*Signing off a paused run* — when a run reaches an approval gate it moves to **Awaiting sign-off** and the approver is messaged directly. They answer by replying on Slack, Discord or Telegram — \"yes\", \"LGTM\", \"no\", \"not now\" — or with **Approve** / **Decline** on the run page (the principal can answer any sign-off there too). \"No\" or \"not now\" ends the run.\n\n*The first write somewhere new* — a workflow that uses tools picks where to write each time it runs (this month's tab, the sender of an invoice, a new doc per client). The first time it wants to write somewhere it hasn't written before — a different spreadsheet, a new recipient — that one write waits, the rest of the run carries on, and whoever created the workflow is asked: yes lets it write there now and in future runs, no skips it. The places a workflow may write without asking are listed under **Approved targets** on its page; remove one and it asks again.\n\n**From chat:**\n\n- *\"What workflows can you run?\"* or *\"Run a competitive teardown of Acme.\"* — the Executive runs it and brings the result back into the conversation.\n- *\"Build me a workflow called weekly_competitor_watch: the CMO checks our top three competitors for pricing and product changes, then summarise. Run it every Monday at 09:00 UTC and send it to me.\"* — the Executive drafts it, shows you a summary, and saves it once you say yes.\n\n*Note: outputs are listed in Documents. Ask OE can also fill in the advanced editor form for you.*",
+ "markdown": "**What it is:** Structured, multi-step workflows that produce a *deliverable* — a board deck, a go-to-market plan, a performance review — or *get something done* with your connected tools, like filing emailed bills into a spreadsheet, rather than just a chat reply.\n\n**What it does:**\n\n- Start from **What do you want to get done?** at the top of the page: say what you want done in a sentence, or pick a suggestion chip.\n- When you use Open Executive just for yourself, the suggestions and the **Good places to start** picks fit someone running the business alone: a Friday cash and pipeline check, which customers stopped buying, a monthly review, pricing, churn and the quarter's plan. A team sees the board and investor ones.\n- Your own workflows sit under **Your workflows** as cards. Each card shows its schedule (or its number of steps) and when it last ran, with a **Run** button and a **⋯** menu (**Edit**, **Delete**). A workflow waiting on a sign-off shows **Waiting for sign-off** and a **Review** button instead, with **Run again** in its **⋯**.\n- **Browse N ready-made** opens the ready-made list in a side panel: **Good places to start** first, then a search box and area chips (**All**, **Board**, **Capital**, **Growth & GTM**, **Product**, **People**, **Risk & Legal**, **Operating**, and **System** for the workflows Open Executive runs on its own, like the morning brief).\n- Start a run and watch it stream its progress step by step.\n- See your runs under **Runs** (in the switch beside **Your workflows**; it shows how many are open), split into **Active**, **Awaiting sign-off**, **Done** and **Error**, grouped by workflow, and search them by name.\n- Create your own **custom workflow** by describing it: the assistant asks a few clarifying questions, then drafts it for you to review.\n- Let a workflow **use tools** — Gmail, Google Sheets, Drive and anything else connected — to actually do the work, not just write about it.\n- Put a custom workflow on a **schedule** (e.g. every Monday at 09:00) so it runs without being asked.\n- Each finished run produces a document you can read, copy and download. It is also listed in **Documents**.\n- Read and edit **How it's done** on a workflow's page — the method the Executive follows in that workflow and in chat (see **How it's done** in this guide). **Quick** workflows in the ready-made list are one question, one document. A custom workflow's specialist step can **Follow a playbook** too.\n\n**How to use:**\n\n*Run a workflow*\n\n1. Open **Work** in the sidebar (it opens on **Workflows**). Click **Run** on one of your workflows, or click **Browse N ready-made**, narrow the list with the chips or the search box, and click a workflow to open it.\n2. The page shows **What it does** (its steps) and **What it needs** (the fields to fill in; required ones have a red \\*). **Use example** next to a field, or **Fill with an example** for the whole form, fills in realistic values if you just want to try it.\n3. Click **Run it now**, then **Run workflow** (**Back to the details** returns to the form). Progress streams step by step; when it finishes you land on the run page.\n4. On the run page, **Copy** copies the document and **Download** offers **Markdown (.md)** or **Word (.docx)**. **Inputs** at the bottom shows what the run was given.\n\n*Who sees a run* — a run you start by hand is visible only to you and to anyone a sign-off in it waits on. Not even the principal sees a teammate's own run. Scheduled and system runs belong to the team: everyone signed in to the workspace sees them. A few system workflows can only be started by the principal (the weekly review, and the morning brief when you use Open Executive just for yourself).\n\n*Manage runs* — each run's **⋯** under **Runs** has **Delete run** (you are asked to confirm). A group shows its five newest runs; **Show N more** lists the rest. A failed scheduled run has **Run again** on its page, which the principal or the person it delivers to can use; it delivers the way the scheduled run would have. **Start a new run instead** opens the workflow's form.\n\n*Build your own*\n\n1. Under **What do you want to get done?**, describe the job in plain words — what it should produce, who it's for, and how often — or pick one of the suggestions, then click **Start**. (The **⋯** beside **Start** has **New workflow**, which opens the same conversation empty, **New workflow, step by step**, which opens the advanced editor, and **Talk it through in chat**, which starts a chat.)\n2. Answer the clarifying questions (usually two or three) by typing or by clicking a suggested answer. **Draft it now** skips the rest.\n3. Review the draft: its steps, schedule, what you fill in each run, the assumptions it made, and the **tools** each action step will use (ones that can change things are listed under *Creating this workflow lets it use these tools*).\n4. Click **Create workflow** — this approves those tools, and runs use them without asking again — or **Keep refining** and type what to change, or **Edit details** to fine-tune it field by field in the advanced editor. It appears under **Your workflows**.\n\nThe signed-in person who creates a workflow becomes its owner: they are the one asked when it wants to write somewhere new (see below).\n\n*Change a custom workflow* — **Edit** in its **⋯**, or **Change it** on its page, opens a conversation. Say what to change in your own words (who signs off, when it runs, what a step does). It shows **Proposed changes** next to **How it works now**, and nothing is saved until you click **Save changes**. If the change adds tools that can change things, saving approves them. **Use the advanced editor** opens the form instead. **Delete** in the **⋯** removes the workflow after a confirmation; this cannot be undone.\n\n*Advanced editor* — reached from **New workflow, step by step** in the **⋯** beside **Start**, **Edit details** on a draft, or **Use the advanced editor**. It has four stages; move between them with **Next** and **Back**, and **Cancel** to leave:\n\n1. **Details:** a unique **Name** in snake_case (e.g. `weekly_competitor_watch`; 3–49 lowercase letters, digits or underscores, starting with a letter, and not starting with `quick_`; it can't be changed later), a **Title**, **Description**, **Section** and **Estimated minutes** (1–120).\n2. **Input fields:** click **+ Add field** for anything the person running it must supply, with a **Field name**, **Label** and a **Required** tick. Remove one with **Remove field** in its **⋯**. Use a field in a step's goal as `{field_name}`.\n3. **Steps:** add **+ Specialist** steps (pick a specialist, write its goal, optionally **Follow a playbook**), **+ Action** steps (write what to get done and where, then **Search tools** and **+ Add** the ones it may use), and, if someone must sign off, an **+ Approval gate** (who to ask, the question, a timeout, and what happens on timeout: `escalate`, `auto_proceed` or `fail`). New steps are added at the bottom. Use **Move up** / **Move down** in a step's **⋯** to place them above the synthesis step, which pulls everything together and must stay last; put an approval gate just before it. **Remove step** deletes one. Up to 12 steps and 16 input fields.\n4. **Schedule (optional):** tick **Run on a schedule**, enter a **Cadence**, and pick who the document is delivered to under **Deliver document to**. A scheduled workflow can't have required input fields or approval gates.\n5. Click **Create workflow** (**Save changes** when editing).\n\nCadences are written like this (times are UTC): `daily@09:00`, `weekly@mon@09:00`, or `quarterly@01-09:00` (the 1st of January, April, July and October).\n\n*Workflows that use tools* — describe the job and where things live, e.g. *\"Every morning, find the bills I email you, read each PDF and add a row (vendor, amount, due date) to my Bill tracker sheet.\"* The assistant finds the right tools (here Gmail search and attachments, reading PDFs, and appending rows to Google Sheets) and asks about anything it needs, like which sheet. While a run works, the progress list shows the tool each action step is using, and the step's result ends with **Actions taken**. A workflow can only use the tools you approved, and every tool call is recorded in the audit log. You can also ask for one in chat: a workflow that uses tools is saved **switched off**, and the Executive gives you a link. It shows as **Waiting for your approval** at the top of **Your workflows**; click **Review**, check the steps and tools, and click **Turn on workflow**. Until then it can't run or follow a schedule.\n\n*Signing off a paused run* — when a run reaches an approval gate it moves to **Awaiting sign-off** and the approver is messaged on their usual channel. They answer by replying on Slack, Discord or Telegram — \"yes\", \"LGTM\", \"no\", \"not now\" — or with **Approve** / **Decline** on the run page. Only the person the run waits on, or the principal, can answer. \"No\" or \"not now\" ends the run. If nobody answers before the timeout, the gate's timeout rule applies.\n\n*The first write somewhere new* — a workflow that uses tools picks where to write each time it runs (this month's tab, the sender of an invoice, a new doc per client). The first time it wants to write somewhere it hasn't written before — a different spreadsheet, a new recipient — that one write waits, the rest of the run carries on, and the workflow's owner is asked: yes lets it write there now and in future runs, no skips it. The places a workflow may write without asking are listed under **Approved targets** on its page; **Remove** one and it asks again.\n\n**From chat:**\n\n- *\"What workflows can you run?\"* or *\"Run a competitive teardown of Acme.\"* — the Executive runs it and brings the result back into the conversation.\n- *\"Build me a workflow called weekly_competitor_watch: the CMO checks our top three competitors for pricing and product changes, then summarise. Run it every Monday at 09:00 UTC and send it to me.\"* — the Executive drafts it, shows you a summary, and saves it once you say yes.\n\n*Note: outputs are listed in Documents. The help panel (the sparkle button at the top right) can also fill in the advanced editor form for you.*",
"mermaid": null,
- "generated_at": "2026-10-09T18:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/knowledge.json b/packages/core/openexecutive/guide/prebuilt/knowledge.json
index 4e6ac920..bc7a3dc6 100644
--- a/packages/core/openexecutive/guide/prebuilt/knowledge.json
+++ b/packages/core/openexecutive/guide/prebuilt/knowledge.json
@@ -1,7 +1,7 @@
{
"section_id": "knowledge",
"title": "Knowledge Base",
- "markdown": "**What it is:** Your company's documents, in one place. Add handbooks, past decks, policies and plans, and the Executive reads them when answering. Files from a connected Google Drive folder or Notion workspace show up here too.\n\n**What it does:**\n\n- Opens on **Company documents**: one list of everything the Executive reads about your company, newest first.\n- Marks each document with where it came from — **Uploaded**, **Google Drive** or **Notion** — and when it was added or last synced.\n- Indexes each document automatically so specialists can pull the relevant passages into their reasoning.\n- Keeps connected sources up to date on a schedule, with a **Sync now** button when you can't wait.\n- Under the **Advanced** tab: approve knowledge in the **Review queue**, add your own playbooks and lessons learned under **Built-in playbooks**, browse the **Reference library**, and test retrieval in **Query test**.\n\n**How to use:**\n\n*Add a document*\n\n1. Open **Knowledge** in the sidebar. It opens on the **Company documents** tab.\n2. Drag files onto the drop area, or click **Add documents** (PDF, Word, Markdown or text, up to 50 MB each). You can add several at once.\n3. Once *Adding…* finishes, the document is searchable. Click its name or **View** to read the text the Executive sees; **Delete**, in the row's **⋯** menu, removes it. To replace a document, delete it and add the new version.\n\n*Documents from Google Drive or Notion*\n\n1. An administrator connects them with environment settings (see `docs/drive_sync_setup.md` and the other sync setup guides in `docs/`). Their files then appear in the list with a **Google Drive** or **Notion** badge, the time they were last synced and when they were last edited.\n2. **Open in Google Drive ↗** (or Notion), in the row's **⋯** menu, opens the original. Synced files can't be deleted here — remove them from the shared folder or Notion and they drop off on the next sync.\n3. Each connected source has a card above the list showing when it last synced and how often it syncs. Click **Sync now** to pick up a change straight away. If a sync failed, the card says why and links here.\n\n*Check what the Executive will find*\n\n1. Open the **Advanced** tab, then **Query test**, type a question, and click **Run**.\n2. Optionally narrow by **Specialist**, by source (**Include**), or by **Domains**. The results show which passages would be pulled and which specialists would see them — a lower distance means a closer match.\n\n*Add your own playbook*\n\n1. Open the **Advanced** tab, then **Built-in playbooks**, and click **+ Playbook** (or **+ Failure case** for a lessons-learned case). Pick the domain it belongs to.\n2. Enter a filename and the Markdown content, then click **Create file**.\n3. New playbooks wait in the **Review queue** and aren't used until you approve them — or click **Approve** under the filename. Open any playbook and use **Edit** / **Preview** to change it later; **Flag for revision** and **Delete file** are in its **⋯** menu.\n\n**Example:** add `pricing-policy-2026.pdf`, then in **Query test** ask *\"what discount can sales offer without approval?\"* to confirm the right passage comes back.\n\n*Note: there's also a read-only built-in knowledge base (curated business know-how) that ships with the app. Files attached in chat are not added to Knowledge.*",
+ "markdown": "**What it is:** Your company's documents, in one place. Add handbooks, past decks, policies and plans, and the Executive reads them when answering. Files from a connected Google Drive folder, OneDrive folder or Notion workspace show up here too.\n\n**What it does:**\n\n- Opens on **Company documents**: one list of everything the Executive reads about your company, newest first. The tab shows how many there are.\n- Marks each document with where it came from (**Uploaded**, **Google Drive**, **OneDrive** or **Notion**) and when it was added or last synced.\n- Indexes each document automatically so specialists can pull the relevant passages into their reasoning.\n- Keeps connected sources up to date on a schedule, with a **Sync now** button when you can't wait.\n- Under the **Advanced** tab: approve knowledge in the **Review queue**, add your own playbooks and lessons learned under **Built-in playbooks**, browse the **Reference library**, and test retrieval in **Query test**.\n\n**How to use:**\n\n*Add a document*\n\n1. Open **Knowledge** in the sidebar. It opens on the **Company documents** tab.\n2. Drag files onto the drop area, or click **Add documents**. PDF, Word, Excel, CSV, Markdown or text, up to 50 MB each. You can add several at once.\n3. Once the upload finishes, the document is searchable. Click its name or **View** to read the text the Executive sees, in a side panel. **Delete**, in the row's **⋯** menu, removes it. To replace a document, delete it and add the new version.\n4. With documents from more than one source, chips at the top filter the list by source. With more than 8 documents, **Search by name…** filters by name.\n\n*Documents from Google Drive, OneDrive or Notion*\n\n1. An administrator connects them with environment settings (see `docs/drive_sync_setup.md`, `docs/onedrive_sync_setup.md` and the other sync setup guides in `docs/`). Until one is connected, the page shows **How to connect**, which links here.\n2. Synced files appear in the list with their source, when they were last synced and when they were last edited at the source. A file with no readable text says so and can't be opened here.\n3. **Open in Google Drive ↗** (or OneDrive, or Notion), in the row's **⋯** menu, opens the original. The viewer panel also has **Open original ↗**. Synced files can't be deleted here; the menu says **Managed in *source*: remove it there**. Remove them from the shared folder or Notion and they drop off on the next sync.\n4. Each connected source has a card above the list showing when it last synced, how many files it has, and how often it syncs. Click **Sync now** to pick up a change straight away. If a sync failed, the card says why, with a **How to fix** link.\n\n*Check what the Executive will find*\n\n1. Open the **Advanced** tab, then **Query test**. Type a question and click **Run**.\n2. Optionally narrow by **Specialist**, by source (**Include**: built-in, company, failures, external), or by **Domains** (**Clear** resets them).\n3. The results show the domain filter used, which specialists would see the passages, and the matching passages grouped into **Playbooks**, **Failures**, **Company documents** and **Reference Library**. Each shows its distance: a lower number means a closer match. **Open →** opens a playbook or failure case.\n\n*Add your own playbook*\n\n1. Open the **Advanced** tab, then **Built-in playbooks**. Files are grouped by domain (board, finance, hr, legal, marketing, operations, product, sales, strategy), each split into **Playbooks** and **Failures**. **Filter files…** narrows the list.\n2. Click **+ Playbook** (or **+ Failure case** for a lessons-learned case). Pick the domain, enter a filename (letters, numbers, dashes or underscores) and the Markdown content, then click **Create file**.\n3. New files wait in the **Review queue** and aren't used until you approve them. You can also click **Approve** under the filename.\n4. Open any file to read it. Switch between **edit** and **preview**, then click **Save**. **Flag for revision** and **Delete file** are in its **⋯** menu.\n\n*Reference library*\n\nOpen-licensed textbooks and handbooks the Executive draws on, each marked **Ingested** or **Pending**. Click **Peek** to see the indexed passages. The list is declared in `knowledge/sources.yaml` and refreshed with `openexecutive ingest-oer`.\n\n**Example:** add `pricing-policy-2026.pdf`, then in **Query test** ask *\"what discount can sales offer without approval?\"* to confirm the right passage comes back.\n\n*Note: the built-in knowledge base (curated business know-how) ships with the app and is used right away. Files attached in chat are not added to Knowledge.*",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/people.json b/packages/core/openexecutive/guide/prebuilt/people.json
index 9e20e085..f686b7bf 100644
--- a/packages/core/openexecutive/guide/prebuilt/people.json
+++ b/packages/core/openexecutive/guide/prebuilt/people.json
@@ -1,7 +1,7 @@
{
"section_id": "people",
"title": "People",
- "markdown": "**What it is:** Everyone the Executive knows about, in two tabs. **Team** is the people who work with you — each with a response SLA, a preferred channel and the approvals they hold. **Contacts** is everyone outside the team — clients, contractors, advisors, or anyone else you deal with — and it is private to you.\n\n**What it does:**\n\n- Add team members with their role, email, and chat IDs (Slack / Discord / Telegram).\n- Set a response SLA so the Executive knows when a proposal is overdue.\n- Assign **authority scopes** (e.g. approve spend under $10k, sign off on hiring) so proposals route to the right person.\n- Mark the principal (you) and set availability or on-leave dates.\n- Keep **contacts** so the Executive can email or invite them — but only when you ask it to directly (in the web app, or from your own Slack or Discord). A contact can't sign in, can't message the Executive, never approves anything, and is never chased.\n- Keep contacts **private**: only you see them. Nobody else on your team sees the Contacts tab, finds a contact when they ask the Executive, or sees an alert about one.\n\n**Team member or contact?**\n\n| | Team member | Contact |\n|---|---|---|\n| Signs in to Open Executive (with an email) | Yes | No |\n| Messages the Executive on Slack / Discord / Telegram | Yes | No |\n| Approves proposals, gets check-ins and reminders | Yes | No |\n| The Executive emails or invites them | On any task | Only when you ask directly |\n| Who sees them | Everyone on the team | Only you |\n\n**How to use:**\n\n1. Open **Company** in the sidebar (it opens on **People**), pick the **Team** or **Contacts** tab (only you, the principal, see Contacts), and click **Add person** (or **Add contact**).\n2. Choose **Team member** or **Contact** at the top of the dialog, then enter **Full name** (the only required field) and **Role** — for a contact, their role and company (e.g. *Head of Procurement, Acme*) — and their email. If this is you, tick **This is me — Primary** — this can only be set when adding someone, and you are always on the team.\n3. For a team member, expand **Contact & routing**: the preferred channel, **Expected reply within *N* hours** (their SLA — default 24), email, and Slack / Discord / Telegram IDs. Those IDs are also what lets this person talk to the Executive on those channels.\n4. For a team member, expand **Approval authority** and click each scope they hold:\n\n | Button | They can approve |\n |---|---|\n | Spend <$2K / <$10K / >$10K | Spend up to that amount (>$10K covers large spend) |\n | Hiring | Hiring sign-off |\n | Vendors | New vendor onboarding |\n | Credit | Customer credits |\n | Legal | Legal signatures |\n | Board | Board communications |\n | All (wildcard) | Anything — the catch-all for approvals no one else is scoped for; usually the principal |\n\n5. Click **Add person** (or **Add contact**). Later, open the person and click **Edit** to change their details, scopes, or move them between team and contacts; **On leave until** and **Availability windows** (days, hours, timezone) are on the **Approvals & availability** tab. **Archive person**, in the **⋯** menu next to **Edit**, retires them from the roster.\n\n**Who can change it:** only the principal can add, edit or archive people — until someone is the principal, whoever sets up first can. Everyone signed in can see the team (your contacts stay yours alone), and teammates can still edit their own working style and mark their open loops done on their page.\n\n**Example from chat:** *\"Add Sarah Chen as our fractional CFO — [email protected] — she approves spend under $10k and usually replies within 48 hours.\"* Or: *\"Add Jordan Lee from Acme as a contact — [email protected] — and send them the proposal.\"* Or open **Add person**, press **Ctrl/Cmd + .**, and describe the person — Ask OE fills in the dialog for you to check and save.\n\n**Forward it to the Executive:** forward an email from a client to the Executive's address and it replies to you — not them — with a summary, a draft reply you can send, any dates or commitments, and an offer to add the sender as a contact. Mail a contact sends the Executive directly is summarised for you, never answered on its own. Either way it stays between you and the Executive: it tells no one else, and any alert it raises is yours alone.\n\n**Just for yourself?** When you use Open Executive just for yourself, setup adds only you — marked as the principal, with authority over everything. **People** stays in the sidebar under **You** and opens on **Contacts**: anyone you add from chat is a contact unless you say otherwise, and the **Team** tab shows just you. If you add a team member, Open Executive offers to switch to team mode — or you can keep using it just for yourself. Home doesn't show a People tile in this mode.\n\n*Note: authority scopes are how the Executive figures out who on the team to ask for any given approval.*",
+ "markdown": "**What it is:** Everyone the Executive knows about, in two tabs. **Team** is the people who work with you. Each has a response SLA, a preferred channel and the approvals they hold. **Contacts** is everyone outside the team: clients, contractors, advisors, or anyone else you deal with. Contacts are private to you.\n\n**What it does:**\n\n- Add team members with their role, email, and chat IDs (Slack / Discord / Telegram).\n- Set a response SLA so the Executive knows when a reply is overdue.\n- Assign **authority scopes** (e.g. approve spend under $10K, sign off on hiring) so proposals route to the right person.\n- Mark the principal (you) and set availability windows or on-leave dates.\n- Track **open loops**: what each person owes. You can assign someone a task with a due date, and overdue ones are followed up automatically.\n- Show how each team member answers the Executive's messages, and the writing rules it has learned for them.\n- Keep **contacts** so the Executive can email or invite them, only when you ask it to directly (in the web app, or from your own Slack or Discord). A contact can't sign in, can't message the Executive, never approves anything, and is never chased.\n- Keep contacts **private**: only you see them. Nobody else on your team sees the Contacts tab, finds a contact when they ask the Executive, or sees an alert about one.\n\n**Team member or contact?**\n\n| | Team member | Contact |\n|---|---|---|\n| Signs in to Open Executive (with an email) | Yes | No |\n| Messages the Executive on Slack / Discord / Telegram | Yes | No |\n| Approves proposals, gets check-ins and reminders | Yes | No |\n| The Executive emails or invites them | On any task | Only when you ask directly |\n| Who sees them | Everyone on the team | Only you |\n\n**How to use:**\n\n1. Open **Company** in the sidebar (it opens on **People**). Pick the **Team** or **Contacts** tab and click **Add person** (or **Add contact**). Only you, the principal, see the Contacts tab. Each card shows the person's name, role, preferred channel and one status, such as on leave.\n2. Choose **Team member** or **Contact** at the top of the panel. Enter **Full name** (the only required field), **Role** (for a contact, **Role and company**, e.g. *Head of Procurement, Acme*) and **Email**. If this is you, tick **This is me — Primary**. You can only set this when adding someone, and the principal is always on the team.\n3. For a team member, expand **Contact & routing**: **Preferred channel** (any, slack, discord, telegram or email), **Expected reply within *N* hours** (their SLA, default 24; items show as overdue on Home after that), and their Slack user ID, Discord user ID and Telegram chat ID. Those IDs are also what lets this person talk to the Executive on those channels. For a contact, the same IDs are under **Chat IDs**.\n4. For a team member, expand **Approval authority** and click each scope they hold:\n\n | Button | They receive |\n |---|---|\n | Spend <$2K / <$10K / >$10K | Proposals for spend in that range |\n | Hiring | Proposals related to hiring decisions |\n | Vendors | Proposals for vendor contracts |\n | Credit | Proposals involving credit or debt |\n | Legal | Proposals with legal implications |\n | Board | Proposals before board communications |\n | Meetings | Meetings the Executive wants to book |\n | All (wildcard) | Anything no one else is scoped for. Usually the principal |\n\n5. Click **Add person** (or **Add contact**).\n\n*A person's page*\n\nClick a card to open the person. The page has up to four tabs:\n\n- **Overview**: email, other addresses, how to reach them, and any leave date. Team members also show **Open loops** here.\n- **Approvals & availability**: what they approve, and their **Availability windows** (days, start and end time, timezone). With no windows, they count as always available.\n- **How they respond**: proactive messages sent to them over the last 30 days, and how many they answered. Kinds of message they reliably ignore are sent less often.\n- **How I work with them**: how replies are written for them, learned from their own 👍/👎 and what they ask for in chats. Click **Edit rules** to type up to 8 rules, one per line; typed rules are always kept. The **⋯** menu has **Lock (stop learning)** / **Unlock (keep learning)** and **Reset what was learned**.\n\nA contact's page has only **Overview**. An archived person has no **How they respond** or **How I work with them** tab.\n\n*Change someone*\n\n1. Click **Edit** at the top of their page. On **Overview** you can change the name, role, **Team member or contact**, email, **Other addresses** (one per line: mail from these reaches them and they can be emailed there; only the main email signs in), preferred channel and SLA. **On leave until** and the chat IDs are under **Advanced**.\n2. To change approvals or availability, switch to **Approvals & availability** while editing: click scopes on or off, and use **Add window** / **Remove window**.\n3. Click **Save**.\n4. **Archive person**, in the **⋯** menu next to **Edit**, takes them off routing and the active roster. They get no new assignments; their history is kept. The principal can't be archived.\n\n*Open loops*\n\n- **Open loops** lists things a person committed to, was asked for in conversation, or was assigned. Overdue ones are followed up automatically. Click **Mark done** to close one.\n- To assign a task, type it in **Assign a task** (up to 200 characters), optionally pick a **Due** date, and click **Assign**. The person is told once on their own channel, and the page says whether it reached them.\n\n**Who can see and change it:**\n\n- Only the principal can add, edit or archive people. Until someone is the principal, whoever sets up first can.\n- Everyone signed in sees the team. Contacts stay yours alone.\n- Anyone on the team can assign a task to anyone on the team. Only the principal and the person themselves see that person's open loops, **How they respond** and **How I work with them**, and only they can close a loop or change the working-style rules.\n\n**Someone new wrote in:** when someone who isn't on People messages the Executive, their messages are held and a card **Who is *name*?** appears on Home. Click **Add them** and choose **Add as a new person** (enter their name and pick team or contact) or **Someone already on the list**. Their waiting messages are answered once they're added. **Ignore** is in the card's **⋯** menu. Only the principal sees these cards.\n\n**Example from chat:** *\"Add Sarah Chen as our fractional CFO — [email protected] — she approves spend under $10k and usually replies within 48 hours.\"* Or: *\"Add Jordan Lee from Acme as a contact — [email protected] — and send them the proposal.\"* Or open **Add person**, press **Ctrl/Cmd + .**, and describe the person. The help panel (the sparkle button at the top right) fills in the panel for you to check and save.\n\n**Forward it to the Executive:** forward an email from a client to the Executive's address and it replies to you, not them, with a summary, a draft reply you can send, any dates or commitments, and an offer to add the sender as a contact. Mail a contact sends the Executive directly is summarised for you, never answered on its own. Either way it stays between you and the Executive: it tells no one else, and any alert it raises is yours alone.\n\n**Just for yourself?** When you use Open Executive just for yourself, setup adds only you, marked as the principal, with authority over everything. **People** sits in the sidebar under **You** and opens on **Contacts**. Anyone you add from chat is a contact unless you say otherwise, and the **Team** tab shows just you. Other team members are hidden in this mode; the page says how many. If you add a team member (or move a contact onto the team), Open Executive asks **Switch to team mode?**: click **Switch to team mode** or **Keep it just for me**. Home doesn't show a People tile in this mode.\n\n*Note: authority scopes are how the Executive figures out who on the team to ask for any given approval.*",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/pulse.json b/packages/core/openexecutive/guide/prebuilt/pulse.json
index d4f9329e..cd1441a4 100644
--- a/packages/core/openexecutive/guide/prebuilt/pulse.json
+++ b/packages/core/openexecutive/guide/prebuilt/pulse.json
@@ -1,7 +1,7 @@
{
"section_id": "pulse",
"title": "Pulse (Memory)",
- "markdown": "**What it is:** The Executive's running memory and heartbeat — the decisions it has made with you, the initiatives it's tracking, the advice it has gathered, and the rhythm of work it runs on its own.\n\n**What it does:**\n\n- Browse past **decisions** with their rationale and outcome.\n- Track **initiatives** as planned, active, paused, or completed.\n- Review **advice** collected from specialists, searchable by topic.\n- See your **corrections** — facts you corrected or asked the Executive to keep, where you said them, and what they replaced. They hold everywhere: every conversation, brief, scheduled run and alert review.\n- See the **heartbeat** — the recurring cadence of daily briefs, department check-ins, system scans, and pending scheduled follow-ups.\n- Edit or delete any item to keep the Executive's memory accurate.\n\n**How to use:**\n\n1. Just chat. Decisions, initiatives and advice are pulled out of your conversations automatically after each chat — there's nothing to add by hand.\n2. Click **Pulse** in the sidebar. The **Heartbeat** card shows the last 90 days beside three numbers: what it did today, how long until the next thing it does, and how many days in a row it has been active. **More detail** opens the rest. Below it, under **What it remembers**, a tile for **Decisions**, **Projects**, **Advice**, **Facts you taught it** and **Your notes** opens that list on its own screen; **Pulse** at the top takes you back. Then **Coming up** lists the next few briefs, check-ins and follow-ups (**Full schedule** shows them all, with background scans under **Show background scans**), and **Done recently** lists the last few things it did (**All activity** shows the full feed).\n3. Choose **Edit** in any row's **⋯** menu to correct it — fix a decision's rationale or outcome, change its domain or tags, or move an initiative to *completed* — then **Save**.\n4. Choose **Delete** in the same menu to remove something that's simply wrong. This can't be undone.\n5. To correct a fact, just say it in chat — *\"Maple House is 48 units, not 52\"* or *\"we're 42 people now\"*. The Executive keeps it (a company-profile field such as headcount or burn updates the profile too), and it shows under **Facts you taught it** with your words. Choose **Retire (stop using it)** in a correction's **⋯** menu when it no longer holds; older versions stay under **Show history**. You can also email a correction from your own address: nothing changes until you reply CONFIRM to the confirmation email the Executive sends you. Teammates on your People list can correct facts too, from the web app or their own Slack or Discord. Theirs are marked with their name and wait for your approval at the top of that list (the tile says how many), and they appear in your morning brief. Untick **needs my approval** next to a teammate you trust to let theirs apply straight away; one that would replace yours still waits for you. Only you can retire someone else's correction.\n\n**Example:** tell the Executive *\"we've decided to push the EU launch to Q2 so we can finish SOC 2 first.\"* Afterwards, **Pulse → Decisions** shows that decision with its rationale. If it captured the wrong reason, edit it — future answers build on what's recorded here.\n\n**Just for yourself?** When you use Open Executive just for yourself, the heartbeat leaves out department check-ins and the \"Awaiting people\" list, and the count of active projects takes the department check-ins' place under **More detail**. The same projects appear on Home under **Your projects**.\n\n*Note: this memory is searchable across the system, so what's captured here informs future answers.*",
+ "markdown": "**What it is:** The Executive's running memory and heartbeat — the decisions it has made with you, the initiatives it's tracking, the advice it has gathered, and the rhythm of work it runs on its own.\n\n**What it does:**\n\n- Browse past **decisions** with their rationale and outcome.\n- Track **initiatives** as planned, active, paused, or completed.\n- Review **advice** collected from specialists, labelled by domain.\n- See your **corrections** — facts you corrected or asked the Executive to keep, where you said them, and what they replaced. They hold everywhere: every conversation, brief, scheduled run and alert review.\n- See the **heartbeat** — the recurring cadence of daily briefs, department check-ins, system scans, and pending scheduled follow-ups.\n- Keep **your notes**: what you said, in chat and in replies you approved. Each person sees only their own notes; the owner can't see anyone else's.\n- See **your month**: what the Executive did for you this month, counted from the record. Only the owner sees it.\n- Edit or delete any item to keep the Executive's memory accurate.\n\n**How to use:**\n\n1. Just chat. Decisions, initiatives and advice are pulled out of your conversations automatically after each chat — there's nothing to add by hand.\n2. Click **Pulse** in the sidebar. At the top, **Your month** (owner only) sums up this month in one line; click it for every count against the period before. The **Heartbeat** card shows the last 90 days beside three numbers: what it did today, how long until the next thing it does, and how many days in a row it has been active. **More detail** opens the rest. Below it, under **What it remembers**, a tile for **Decisions**, **Projects**, **Advice**, **Facts you taught it** and **Your notes** opens that list on its own screen; **Pulse** at the top takes you back. Then **Coming up** lists the next few briefs, check-ins and follow-ups (**Full schedule** shows them all, with background scans under **Show background scans**; choose **Cancel follow-up** in a follow-up's **⋯** to drop it), and **Done recently** lists the last few things it did (**All activity** shows the full feed).\n3. Choose **Edit** in any row's **⋯** menu to correct it — fix a decision's summary, rationale or outcome, change its domain or tags, change a project's title, summary or status (*planned*, *active*, *paused*, *completed*), or fix an advice item's question, advice or domain — then **Save**.\n4. Choose **Delete** in the same menu to remove something that's simply wrong. It asks first; this can't be undone.\n5. On **Your notes**, search with **Search your notes**, and use a note's **⋯**: **Correct**, **Pin** / **Unpin**, **Don't remember this** (forgets every note from that conversation and never notes it again) or **Forget** (deletes that one note). Both ask first and can't be undone.\n6. To correct a fact, just say it in chat — *\"Maple House is 48 units, not 52\"* or *\"we're 42 people now\"*. The Executive keeps it (a company-profile field such as headcount or burn updates the profile too), and it shows under **Facts you taught it** with your words. Choose **Retire (stop using it)** in a correction's **⋯** menu when it no longer holds (it asks first); a company-profile change is fixed on the Company profile instead. Older, retired and declined versions stay under **Show history (N)**. You can also email a correction from your own address: nothing changes until you reply CONFIRM to the confirmation email the Executive sends you. Teammates on your People list can correct facts too, from the web app or their own Slack or Discord. Theirs are marked with their name and wait for your approval at the top of that list with **Approve** and **Decline** (the tile says how many), and they appear in your morning brief. Under **Teammates' corrections**, untick **needs my approval** next to a teammate you trust to let theirs apply straight away; one that would replace yours still waits for you. Only you can retire someone else's correction.\n\n**Example:** tell the Executive *\"we've decided to push the EU launch to Q2 so we can finish SOC 2 first.\"* Afterwards, **Pulse → Decisions** shows that decision with its rationale. If it captured the wrong reason, edit it — future answers build on what's recorded here.\n\n**Just for yourself?** When you use Open Executive just for yourself, the heartbeat leaves out department check-ins and the \"Awaiting people\" list, and the count of active projects takes the department check-ins' place under **More detail**. The same projects appear on Home under **Your projects**.\n\n*Note: this memory is searchable across the system, so what's captured here informs future answers.*",
"mermaid": null,
- "generated_at": "2026-10-10T15:40:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/review.json b/packages/core/openexecutive/guide/prebuilt/review.json
index e541200a..ca4d0806 100644
--- a/packages/core/openexecutive/guide/prebuilt/review.json
+++ b/packages/core/openexecutive/guide/prebuilt/review.json
@@ -1,7 +1,7 @@
{
"section_id": "review",
"title": "Review Queue",
- "markdown": "**What it is:** A quality-control queue for incoming knowledge, facts, and information *before* the Executive starts relying on it.\n\n**What it does:**\n\n- List items awaiting review with their status (pending, approved, rejected, needs revision) and priority.\n- Open any item to see its full content and where it came from.\n- Approve, reject, or flag an item for revision — and attach corrections without changing the original.\n- Bulk-approve everything pending, or a whole domain at once when you trust the source.\n\n**How to use:**\n\n1. Open **Knowledge** in the sidebar, pick the **Advanced** tab, then **Review queue** (`/knowledge?view=review` opens it directly). The number on **Advanced** and on **Knowledge** in the sidebar shows how many items are waiting.\n2. On **To review**, choose **View details** in an item's **⋯** menu to read it and see where it came from.\n3. Decide:\n - **Approve** — the button on the item: the Executive can use it.\n - **Flag for revision** (in **⋯**) — mark it *needs revision* as a reminder to follow up. A flagged item stays in use until you reject it.\n - **Reject…** (in **⋯**) — keep it out; you can add a note saying why.\n - **Priority** (in **⋯**: ↑ High / Normal / ↓ Low) orders your queue.\n4. To fix a detail instead of rejecting the whole item, open **View details**, type in *Add a correction or clarification…* and click **Add**. Active corrections are given to the Executive alongside the item; toggle one to **Inactive** to retire it.\n5. Trust a source? Click **Approve all pending**, or on **All items** pick a domain and click **Approve all pending in *domain***.\n\n**Where items come from:** playbook and failure-case files you add or edit under **Built-in playbooks** on the Knowledge page, and any domain you choose to **Curate** — curating holds that domain's built-in knowledge back from the Executive until you approve it (**Stop curating** releases it). Company documents you upload go straight to **Company documents** and don't appear here.\n\n**Example:** you add a *discount-policy* playbook under finance. It shows up here as pending; open it, add the correction *\"Discounts over 15% need CFO sign-off\"*, then **Approve** — the Executive now uses the playbook with your correction attached.\n\n*Tip: when you open a playbook or failure case under **Built-in playbooks**, its review status shows under the filename, with **Approve** right there and **Flag for revision** in its **⋯** menu.*\n\n*Note: approved and flagged items feed retrieval; pending and rejected ones are kept out. Editing an approved playbook flags it for re-review without taking it out of use.*",
+ "markdown": "**What it is:** A quality-control queue for knowledge *before* the Executive starts relying on it: playbooks, failure cases and reference sources.\n\n**What it does:**\n\n- Lists items waiting for review, with their status (pending, approved, rejected, needs revision) and priority.\n- Opens any item to show its full content and where it came from.\n- Approves, rejects, or flags an item for revision, and attaches corrections without changing the original.\n- Bulk-approves everything pending, or a whole domain at once when you trust the source.\n\n**How to use:**\n\n1. Open **Knowledge** in the sidebar, pick the **Advanced** tab, then **Review queue** (`/knowledge?view=review` opens it directly; the old `/review` link still works). The number on **Advanced**, on **Review queue** and on **Knowledge** in the sidebar shows how many items are pending or need revision.\n2. The queue has three tabs: **To review** (pending and needs-revision items), **All items** and **Annotations**.\n3. On **To review**, click **Approve** on an item, or open its **⋯** menu:\n - **View details**: opens the item in a side panel.\n - **Flag for revision**: marks it *needs revision* as a reminder to follow up. A flagged item stays in use until you reject it.\n - **Priority: High / Normal / Low**: approved playbooks marked High are ranked first when the Executive pulls passages, and are labelled as a verified priority source.\n - **Reject…**: keeps it out. A dialog lets you add an optional note on why, then click **Reject**.\n4. In **View details** you can:\n - Read the **Document content** of a playbook or failure case, and click **Edit** to change it there (**Save** / **Cancel**). For a reference source, read its **Source content** passages (**Load 10 more chunks…** shows more).\n - Write **Reviewer notes**. They save when you click away from the box.\n - Fix a detail without rejecting the whole item: type in *Add a correction or clarification…* and click **Add**. Active corrections are given to the Executive alongside the item. Each correction's menu has **Turn off** / **Turn on** and **Delete**.\n - **Approve** and the **⋯** menu sit at the bottom of the panel.\n5. Trust a source? On **To review**, click **Approve all pending**. This approves pending items only; items flagged for revision stay in the queue.\n6. On **All items**, filter by status, domain and type (**Built-in**, **Failure case studies**, **Reference library**). Under **Bulk actions**, pick a domain and click **Approve all pending in *domain***, **Curate *domain***, or **Stop curating *domain***.\n7. **Annotations** lists every active correction across items, each with **Turn off** and **Delete**.\n\n**Where items come from:**\n\n- Playbook and failure-case files you add or edit under **Built-in playbooks** on the Knowledge page.\n- Any domain you choose to **Curate**. The knowledge that ships with Open Executive is trusted by default and never waits here. Curating a domain queues its shipped items and holds them back from the Executive until you approve them; the app asks you to confirm first. **Stop curating** returns the items you haven't reviewed to trusted default. When the queue is empty, **Review a domain yourself** offers the same choice.\n- Company documents you upload go straight to **Company documents** and don't appear here.\n\n**Who can use it:** anyone signed in can review, approve, reject and curate.\n\n**Example:** you add a *discount-policy* playbook under finance. It shows up here as pending. Open it, add the correction *\"Discounts over 15% need CFO sign-off\"*, then **Approve**. The Executive now uses the playbook with your correction attached.\n\n*Tip: when you open a playbook or failure case under **Built-in playbooks**, its review status shows under the filename, with **Approve** right there and **Flag for revision** in its **⋯** menu.*\n\n*Note: approved and flagged (needs revision) items feed retrieval; pending and rejected ones are kept out. Editing an approved or rejected file marks it *needs revision*, which puts it in use until you review it again.*",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/settings.json b/packages/core/openexecutive/guide/prebuilt/settings.json
index 97466d13..ff99ec23 100644
--- a/packages/core/openexecutive/guide/prebuilt/settings.json
+++ b/packages/core/openexecutive/guide/prebuilt/settings.json
@@ -1,7 +1,7 @@
{
"section_id": "settings",
"title": "Settings & Advanced",
- "markdown": "**What it is:** The settings that live outside the day-to-day nav: whether the Executive is running and how it sounds, who Open Executive is for, letting it write email as you, and the admin and power-user tools.\n\n**What it does:**\n\n- Opens on a page of tiles, one per settings page — **Your Executive**, **Workspace**, **Advanced** and **About**. Each tile says what's on its page and, where it can, how things stand now (running or paused, the voice, just you or your team, a newer version). Click a tile to open its page; the **Settings** link at the top of each page takes you back. Old links to a section (such as `/settings#workspace`) land on the matching page. **Act as me**, **Handle it for me** and **Take the lead** are not in Settings: they are tabs of **Delegate** in the main menu, after **What it may do**, which lists everything that goes out without asking you and the setting that allows it.\n- **Your Executive** shows whether the Executive is **running** or **paused**, with one button: **Pause…** opens the pause form; while it is paused, who paused it, the held count and **Resume** stay in view. Below it, **Voice** picks the voice the Executive answers you in.\n- **Workspace** holds, one card each: whether Open Executive is personal or for your team, your role when it's just you, and your time zone. **Company email domains** sits under **Advanced** at the bottom.\n- **Act as me** (a tab of **Delegate** in the main menu) lets you have the Executive write email drafts as you, in your own voice, from your own Gmail — when you ask, and, if you turn it on, for mail in your inbox that needs you, which you can send from Home with one tap. Your mailbox and **What it writes as you** are up front; what it sends on its own is set on the **Handle it for me** tab; **How I write** (and, for the owner, **Let team members use it**) sit under **Advanced** at the bottom.\n- **Advanced** lists the pages that open their own screen, grouped by what you'd use them for: **Check & diagnose** (Setup status, Audit log, Token usage), **Configure** (Agent Council, Company Simulator, Client Companies) and **Learn** (User Guide, Architecture).\n- **About** shows the version this install runs, and whether a newer one is out.\n\n**How to use:**\n\n1. Click **Settings** at the bottom of the sidebar. (On a phone, open the menu with the button at the top left; Settings is at its bottom.)\n2. Click a tile to open that page.\n3. On **Advanced**, click a row to open that page:\n - **Setup status** — check that every part of your setup is working, and see what to do about anything that isn't.\n - **Agent Council** — change a specialist's model or prompt, or the Executive's voice.\n - **Audit log** — find out what the Executive did, and why.\n - **Token usage** — see what you're spending and where.\n - **User Guide** — this guide.\n - **Architecture** — the technical reference for how the system is built.\n - **Company Simulator** — try the Executive on a test company.\n - **Client Companies** — switch between clients if you do fractional work.\n\n**Checking your setup:**\n\n- Open **Settings → Advanced → Setup status**. Each part of your setup gets a light: green is working, amber needs attention, red isn't working, grey isn't set up (and is optional).\n- It tests things for real: the AI key, and each chat app's token, with a quick call that sends nothing. It also checks the Executive's email address, the company setup, the daily schedule, when and where your daily brief goes, and whether anyone on your team list can reach each chat app.\n- Anything that isn't green says what to do in plain words, with a button when the fix is on another page. After you change a setting and restart the app, click **Check again**.\n\n**Workspace:**\n\n- **Using Open Executive** — **Personal** or **Team**. You pick this when you first set up; change it here. Switching asks you to confirm and says what changes:\n - **Personal** pauses department check-ins and renames **Company** in the sidebar to **You**, with **Goals** (grouped by area), **People** and your profile — there is no Departments tab. Nothing is deleted — your departments stay, as the areas your goals are grouped by.\n - **Team** brings back **Company** with its **Departments** tab and their daily check-ins, and the People and Departments tiles on Home.\n- **Your role** (just you) — which describes you best (**Owner / founder**, **Executive inside an organisation**, **Independent or fractional**, or **Other**), your title, who you report to, what you're responsible for and what you're measured on. Every field is optional; click **Save role** after editing. The Executive uses it to fit its advice to your job — a VP gets help making the case to their boss, an owner gets help with a call that's theirs alone to make. It stays saved if you switch to your team.\n- **Time zone** — when your morning brief, end-of-day digest and reflection arrive, and how the Executive reads \"tomorrow at 9\". It suggests the zone your browser is in; **Follow server default** uses the server's setting.\n- **Company email domains** (under **Advanced**, principal only) — mail from these domains matches a teammate by the part before the @, and a new address there is filled in as a teammate when someone writes in. It follows your own address unless you set it here.\n- Only the principal can change the mode, role and time zone. A persona you customised in Council stays in place in either mode.\n\n**Act as me (Delegate → Act as me):**\n\n- Normally the Executive writes only as itself, from its own email account. **Act as me** lets it write an email *as you*: ask in chat — \"reply to Dana as me: yes to the 5th\" — and it saves a draft in **your own Gmail Drafts** for you to read, change and send. Asking in chat never sends anything, and everything else it writes stays in its own name.\n- The owner sees this page, and so does each team member once the owner turns on **Let team members use it** under **Advanced** at the bottom of it (shown only where your install allows it). Each team member connects their own Gmail and turns it on for themselves. What it reads in their mail, the drafts it writes and their **Replies waiting** are theirs alone: the owner sees only who uses it and how many drafts and sends it made, and a conversation in which it read someone's mail can be opened only by that person. Turning the owner's switch off takes it away from the team from their next message. It works when you ask in the web app, in a direct message to the Executive on Slack or Discord, or in a verified private Telegram chat — never in a shared channel or thread, from an email, a scheduled job or anyone else's conversation.\n- **Your Gmail** — connect your own Gmail first. The page shows the command to run on a computer with a browser; sign in as yourself, put the file it writes where your install reads it, then click **Check again**. It won't connect the Executive's own address as yours.\n- **What it writes as you** — **Off**, **When I ask** (it writes a draft when you ask in chat) or **For my inbox too** (it also writes replies to your inbox, below). It stays at **Off** until your Gmail is connected, and moving down asks first and says what stops.\n- **Handle it for me** (its own tab) — **What it sends on its own**: **Off**, **Easy ones**, **People I know** and **Most mail** let it send some replies and follow-ups itself, and the owner also gets **Everything**. It needs **For my inbox too** on Act as me. **In training** has every reply come to you first, and at **Everything**, **Your rules** hold back replies that match them.\n- **For my inbox too** — every few minutes the Executive looks at new mail in your inbox, and for mail that needs a personal reply from you — a question, a request, a meeting to arrange, an introduction or a follow-up — it writes a first reply in your Gmail Drafts and puts it at the top of **Needs you** on Home. Nothing is sent until you tap **Send** there. It only looks at mail that arrives after you turn it on, and leaves out newsletters, notifications, mailing lists, mail you've already answered and anything that doesn't need you; mail you answer within ten minutes never gets a draft. The first reply only acknowledges: it repeats only what you've already said in the thread, commits you to nothing and lists what's left for you to decide. Someone you've never written to gets a short holding reply. While it's on, **Your inbox** says how it's doing (for example, that your Gmail needs connecting again) and when it last looked; click **Check now** to look straight away. Moving to **Off** also turns **Read my calendar** off.\n- **How I write** (under **Advanced**) — click **Learn from my sent mail** and it reads your recent sent emails once and describes how you write (click **Edit how I write** to open the fields): your usual **Length** and **Tone**, a **Greeting** for your team, your contacts and anyone else ({first} stands for their first name), your **Sign-off**, your **Habits**, what you **Never** do, and a few **Examples of your writing** that set the tone. Change any of them and click **Save changes**; **Lock** stops it being relearned from your mail (you can still edit it); **Reset** starts over; **Remove examples** drops the examples. Your Gmail signature is added to every draft: **Refresh from Gmail** picks up a change you made to it in Gmail, **Don't add my signature** stops adding it, and **Add my Gmail signature** brings it back.\n- In chat you get a card, \"Drafted an email as you to …\", that opens the draft in Gmail. If the Executive isn't sure about something, it asks you instead of guessing.\n\n**Setting up just for yourself:**\n\n- The first time you set up, Open Executive asks who it is for — **Personal** or **Team** — before anything else, and saves your time zone from the browser. Re-running setup later skips this; change the mode here instead. Either way you can add teammates later from **People**.\n- **Personal** is for anyone who uses Open Executive just for themselves, whatever their role: your own business, a team you lead inside an organisation, or clients you advise as an independent or fractional executive.\n- Choosing **Personal** then asks **What's your role?** — the same fields as **Your role** above. Fill in what you like, or click **Skip for now**.\n- Just for yourself, the setup conversation asks about your work rather than your team, following the role you gave: an owner about what you offer, your customers, pricing, cash and runway; an executive inside an organisation about that organisation (it becomes your company profile), what you're responsible for, who you report to and what you're measured on; an independent about your practice and clients. Everyone is asked about their goals. On **Here's what I understood** there is a single **You** card (your name and role) next to **Your sign-in email**, instead of the team and department lists.\n- The step-by-step form skips the team size, team members and fractional executives steps.\n- In the sidebar, **You** takes the place of **Company** and holds **Goals**, **People** and your profile: **Business profile** if you own the business, **Your work** for any other role (or none). The profile page follows the same choice: for any other role it is worded around the organisation you work in (**Where You Work** in place of Company Basics). Either way departments are listed there as **Areas**, and your title, who you report to and what you're responsible for stay under **Your role** above.\n\n**Pausing the Executive:**\n\n- Open **Settings → Your Executive** (or **Pause or resume the Executive** in the account menu — the **⋯** next to your name at the bottom of the sidebar) and click **Pause…**. Add a reason if you like, and click **Pause Executive**.\n- While paused, the Executive starts nothing on its own: no briefs, nudges, monitoring, inbox processing or workflow timers. An amber banner appears on every page.\n- Chat and direct messages (Slack, Telegram, Discord, Google Chat) still get answers.\n- Nothing is lost. Work that falls due during the pause waits, and runs when you click **Resume**. The switch shows how many actions are waiting.\n- Anyone who can sign in can pause the Executive, but only the principal can resume it.\n\n*Tip: if you're looking for a feature that isn't in the sidebar, it's probably under **Settings → Advanced**. This guide is also in the account menu (the **⋯** next to your name at the bottom of the sidebar), with **Pause or resume the Executive** and, when you signed in with an account, **Sign out**.*",
+ "markdown": "**What it is:** The settings that live outside the day-to-day menu: whether the Executive is running and how it sounds, your notifications, what it knows about you, who Open Executive is for, the version, and the admin and power-user tools under **Advanced**. What the Executive may do as you or on its own is not here: it is under **Delegate** in the main menu (see the Delegate section of this guide).\n\n**What it does:**\n\n- Opens on a page of tiles, one per settings page: **Your Executive**, **Notifications**, **About you**, **Workspace**, **Advanced** and **About**. Each tile says what's on its page and, where it can, how things stand now: running or paused and the voice, your quiet hours, whether notes are on and how long they last, Personal or Team and the time zone, how many tools are under Advanced, the version and whether an update is available.\n- **Notifications** and **About you** have tiles only for someone on the People list.\n- Click a tile to open its page. The **Settings** link at the top of each page takes you back.\n\n**How to use:**\n\n1. Click **Settings** at the bottom of the sidebar. (On a phone, open the menu with the button at the top left; Settings is at its bottom.)\n2. Click a tile to open that page.\n3. On **Advanced**, click a row to open that tool.\n\n**Your Executive:**\n\n- **Pause everything**: shows **Running** or **Paused**. Click **Pause…**, add a reason if you like (up to 200 characters), and click **Pause Executive**. **Cancel** closes the form.\n- While paused, the card shows since when, who paused it, the reason and how many held actions will run when you resume. **Resume** is shown only to the principal. Anyone who can sign in can pause.\n- **Always does on its own**: what it does with no switch: the morning brief and evening digest, nudges, looking over your day, and research and monitoring. Pause stops these too.\n- A line under it points to **Delegate** for Take the lead, booking meetings and what it sends as you.\n- **Voice**: pick the voice the Executive answers you in. It saves when you pick.\n\n**Pausing the Executive:**\n\n- Open **Settings → Your Executive**, or **Pause or resume the Executive** in the account menu (the **⋯** next to your name at the bottom of the sidebar).\n- While paused, the Executive starts nothing on its own: no briefs, nudges, monitoring, inbox processing, workflow timers or Take the lead. An amber banner appears on every page, and a note on Your Executive says nothing there runs until you resume.\n- Chat and direct messages (Slack, Telegram, Discord, Google Chat) still get answers. Anything you tap **Send** or **Approve** on still goes.\n- Nothing is lost. Work that falls due during the pause waits, and runs when you click **Resume**.\n\n**Notifications:**\n\n- Each person sets their own. Only people on the People list can set them; anyone else is told so.\n- **Quiet hours**: a switch, then **From**, **To** and **Days** (**Every day**, or **Weekdays (weekends quiet all day)**). Click **Save quiet hours** after changing the times. What the Executive would send you on its own (nudges, check-ins on your work, alerts) waits until your quiet hours end. Replies when you message it still come straight away. Times are in your time zone; a link offers your browser's zone if it differs.\n- **How things reach you**: **As they happen**, or **In my briefs**. For the owner, **In my briefs** adds held messages to the next morning brief or end-of-day digest under \"While you were away\". For anyone else, they are sent together in one message when the briefs go out.\n- **Let urgent things through**: on, reminders about things waiting on your approval and critical alerts reach you right away, even in quiet hours or when you get things in your briefs. A question a workflow is waiting on you to answer always comes straight away.\n- A line at the top says how many messages are waiting, if any.\n\n**About you:**\n\n- Everything the Executive keeps about you. Each person sees only their own.\n- **Your profile**: what it has learned from your chats and replies, with your notes. Only you see it. It is read-only, and it is hidden when long-term memory is off.\n- **Share my work style with the team**: off by default. On, the Executive shares how you work (your role, your focus, how you like updates, your working style) with teammates when they ask, and uses it to help them work with you.\n- **Keep track of what happens**: on, it keeps private notes of what you tell it in chat, and of replies it drafted that you send. **Keep my notes for** picks a shorter time for your own notes. **See your notes** opens them on Pulse.\n- **How long notes last**: notes are forgotten after this unless their person pins them. The owner picks it **For everyone**; everyone else sees what it is.\n\n**Workspace:**\n\n- **Using Open Executive**: **Personal** or **Team**. Picking the other one asks you to confirm and says what changes, with **Switch to Personal** / **Switch to Team** and **Cancel**:\n - **Personal** pauses department check-ins and renames **Company** in the sidebar to **You**, with **Goals** (grouped by area), **People** and your profile. There is no Departments tab. Nothing is deleted: your departments stay, as the areas your goals are grouped by.\n - **Team** brings back **Company** with its **Departments** tab and their daily check-ins.\n - A persona you customised in Council stays in place in either mode.\n- **Your role** (Personal only): which describes you best (**Owner / founder**, **Executive inside an organisation**, **Independent or fractional** or **Other**), your title, who you report to, what you're responsible for and what you're measured on. Every field is optional. Click **Save role**, or **Discard changes**. The Executive uses it to fit its advice to your job. It stays saved if you switch to Team.\n- **Time zone**: when your morning brief, end-of-day digest and reflection arrive, and how the Executive reads \"tomorrow at 9\". Pick a zone, **Follow server default**, or click **Use this browser's time zone**. It saves when you pick.\n- **Company email domains** (under **Advanced** at the bottom, principal only): mail from these domains matches a teammate by the part before the @, so anna+invoices@ reaches the Anna already on your People list. Someone new writing from one is suggested as a teammate; you still confirm them. It follows your own address until you set it. **Save** keeps the list; **Use my address** goes back to your own address.\n- Only the principal can change the mode, role and time zone.\n- During first setup, **Who is this for?** asks Personal or Team. You can change it here later, and add teammates any time from **People**.\n\n**Advanced:**\n\n- The tools that open their own screen, grouped by what you'd use them for:\n - **Check & diagnose**: **Setup status**, **Audit log**, **Token usage**.\n - **Configure**: **Agent Council**, **Custom tools**, **Company Simulator**, **Client Companies**.\n - **Learn**: **User Guide**, **Architecture**.\n- **Setup status**: a light for each part of your setup and what to do about anything that isn't working.\n- **Audit log**: a searchable record of everything the Executive did: each chat, each question it passed to an expert, each tool it used and each scheduled job.\n- **Token usage**: what the AI has cost: the total, each day and each model.\n- **Agent Council**: choose how thorough answers are, and change each agent's model, instructions and the Executive's voice.\n- **Custom tools**: tools the Executive built when it didn't have the one it needed. Only the account owner sees them. Each has a switch, **Use in workflows**, and **Details, versions and runs** with **Use this one** to go back a version.\n- **Company Simulator**: load a demo company, save a copy of your data, or have AI make up a new one.\n- **Client Companies**: for fractional work: switch between the companies you work for.\n- **User Guide**: this guide. **Architecture**: the technical reference for how the system is built.\n\n**Checking your setup:**\n\n- Open **Settings → Advanced → Setup status**. Each part gets a light: green **Working**, amber **Needs attention**, red **Not working**, grey **Not set up** (optional).\n- The lights: **Sign-in**, **AI model**, **Company setup**, **Owner**, **The Executive's email address**, **API protection**, **Email (Gmail)**, **Your own mailbox (Act as me)**, **Slack**, **Discord**, **Telegram**, **Google Chat**, **Daily schedule**, **Daily brief** and **Long-term memory (Honcho)**. The page lists the ones that need you first.\n- It tests for real: the AI key, and each chat app's token with a quick call that sends nothing. For each chat app it also checks whether anyone on your People list can reach it, and shows when the last message arrived.\n- Anything that isn't green says what to do in plain words, with a link when the fix is on another page. After you change a setting and restart the app, click **Check again**.\n\n**About:**\n\n- Shows the version this install runs, and whether a newer one is out. When one is, **What's new** and **How to upgrade** open the release notes and the upgrade steps.\n\n**Old links:**\n\n- `/settings/on-its-own` opens **Your Executive**. `/settings/act-as-me` opens **Delegate → Act as me**.\n- Old one-page links still work: `/settings#executive` and `#on-its-own` open Your Executive, `#memory` About you, `#workspace` Workspace, `#tools` Advanced, `#about` About, and `#act-as-me` Delegate → Act as me.\n\n*Tip: if you're looking for a feature that isn't in the sidebar, it's probably under **Settings → Advanced**. The account menu (the **⋯** next to your name at the bottom of the sidebar) has **User Guide**, **Pause or resume the Executive** and, when you signed in with an account, **Sign out**.*\n",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/simulator.json b/packages/core/openexecutive/guide/prebuilt/simulator.json
index 03afa9d0..d9c95349 100644
--- a/packages/core/openexecutive/guide/prebuilt/simulator.json
+++ b/packages/core/openexecutive/guide/prebuilt/simulator.json
@@ -1,7 +1,7 @@
{
"section_id": "simulator",
"title": "Company Simulator",
- "markdown": "**What it is:** A sandbox for loading realistic *test* companies — full profile, org chart, documents, and memory — so you can see the Executive in action before trusting it with real data.\n\n**What it does:**\n\n- Browse and load pre-built company fixtures; your real data is snapshotted before the first load.\n- Generate a brand-new scenario with AI from a short description.\n- Review and edit a generated company before saving it.\n- Unload to restore your snapshot, or reset everything to factory defaults.\n\n**How to use:**\n\n1. Open **Settings → Advanced → Company Simulator**.\n2. Click **Load** on a company, then **Open chat →** and try it out. The first time you load one, your real company is snapshotted automatically. If you've changed your real data since that snapshot, click **Snapshot current as my company** before loading again.\n3. To make your own, click **✨ Create with AI**, describe the company, and click **Generate**. Check the result (you can rename it), then **Save & Load** — or just **Save** to load it later.\n4. When you're done, click **Unload to my company** in the banner to put your own data back.\n5. **Reset everything** (in the Danger zone — type `RESET` to confirm) wipes all data, including your snapshot and any custom skills, and restores the default departments. It can't be undone.\n\n**Example description:** *\"A Series A vertical-SaaS startup selling scheduling software to independent dental practices — 45 people, burning $600K a month, 14 months of runway, and a head of sales who just resigned.\"*\n\n*Note: loading a fixture replaces your live context — but your original state is saved and restorable.*",
+ "markdown": "**What it is:** A sandbox for loading made-up *test* companies, each with a profile, org chart, documents and memory, so you can see how the Executive reasons and decides before you give it your own data.\n\n**What it does:**\n\n- Lists ready-made demo companies. Each card shows the industry, stage, mission, ARR, headcount, number of documents, departments and leadership.\n- Loads one in place of your live company. Your own company is saved first, the first time you load one.\n- Creates a new demo company with AI from a short description, for you to review before saving.\n- Puts your own company back when you are done.\n- Resets everything to a blank install.\n\n**How to use:**\n\n1. Open **Settings → Advanced → Company Simulator**.\n2. Click **Load** on a company. A message confirms how many document chunks were indexed and how many memory items were added. The loaded card shows **Active**, and its button changes to **Reload**. Click **Open chat →** to try it out.\n3. The first time you load one, your own company (profile, documents, memory, people, departments and workspace settings) is saved automatically. **Snapshot current as my company** saves it again by hand, for example after you change your real data. It is only offered while no demo company is loaded.\n4. To make your own, click **✨ Create with AI**, describe the company and scenario, and click **Generate**. Under **Review fixture** you see the industry, stage, team, and counts of people, departments, documents, decisions, initiatives and alerts. You can change the company name. Click **Save & Load** to load it now, **Save** to keep it for later, or **← Edit prompt** to change the description.\n5. Companies made with AI show an **AI** badge and a **Delete** button. **Delete** removes the company right away, with no confirmation. The one that is loaded cannot be deleted. The ready-made ones cannot be deleted.\n6. When you are done, click **Unload to my company** in the banner at the top. It puts your saved company back. The button only appears when a saved copy exists.\n\n**Reset everything:**\n\n**Reset everything** is in the **Danger zone** at the bottom. Type `RESET` and click **Confirm reset**. It clears your live company data and the saved copy of your company: profile, documents, chat history, memory, people, departments, goals, the watchlist, your company's own skills, the audit log and run history. Workspace settings go back to their defaults. No departments are created, as on a new install. There is no undo.\n\n**With client companies:** loading a demo company while a client is active saves that client back to its slot first. You cannot switch or create clients while a demo company is loaded. Unload it first.\n\n**Example description:** *\"A Series A vertical-SaaS startup selling scheduling software to independent dental practices, 45 people, burning $600K a month, 14 months of runway, and a head of sales who just resigned.\"*",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/skills.json b/packages/core/openexecutive/guide/prebuilt/skills.json
index dccf5f73..141e346e 100644
--- a/packages/core/openexecutive/guide/prebuilt/skills.json
+++ b/packages/core/openexecutive/guide/prebuilt/skills.json
@@ -1,7 +1,7 @@
{
"section_id": "skills",
"title": "How it's done",
- "markdown": "**What it is:** every workflow has a **How it's done** section on its page: the method the Executive follows for that piece of work (sometimes called a playbook). It follows the same method when you ask for that work in chat, so changing it changes both.\n\n**Quick workflows:** some methods (a post-mortem, a positioning statement, market sizing, a 1:1 agenda and others) don't belong to a bigger job, so each one is a **Quick** workflow: one question (what it's for), one finished document. They are in the ready-made list with a **Quick** tag. If your company has playbooks of its own, each one shows up as a Quick workflow too.\n\n**What it does:**\n\n- Shows the method on each workflow's page, under **How it's done**.\n- Lets you **Edit** it to fit your company. For a built-in workflow that saves your company's own version, marked **Customized**; **Reset to original** brings the shipped one back.\n- In chat, the Executive finds the method that fits and follows it for a quick answer or a draft, and runs or offers the workflow when you want the finished document.\n\n**How to use:**\n\n1. Open **Work** in the sidebar, then a workflow (use **Browse ready-made** for the built-in ones).\n2. Read **How it's done**. Click **Edit**, change the text (it's Markdown), and **Save**.\n3. Changed your mind? **Reset to original**.\n\n**Saving something you want repeated:** say *\"save this as a workflow\"* in chat after work you liked, or describe it. The Executive drafts a workflow with the method written into its steps and shows it to you; nothing is saved until you confirm. You can also start one from **What do you want to get done?** on the Workflows page.\n\n*Why the Executive won't edit a method from chat: workflows read their method on every run, scheduled ones included, and chat also answers email and other channels, where a crafted message could try to steer it. Methods change only when you edit them on the workflow's page.*\n",
+ "markdown": "**What it is:** every workflow that follows a method has a **How it's done** section on its page: the method the Executive follows for that piece of work (sometimes called a playbook). It follows the same method when you ask for that work in chat, so changing it changes both. There is no separate page for methods: the old Skills address now opens **Workflows**.\n\n**Quick workflows:** some methods (a post-mortem, a positioning statement, market sizing, a 1:1 agenda and others) don't belong to a bigger job, so each one is a **Quick** workflow: one question (what it's for), one finished document. They are in the ready-made list with a **Quick** tag and *One question, one document*. If your company has playbooks of its own, each one shows up as a Quick workflow too. A method that a custom workflow starts following stops being offered as a Quick workflow on its own.\n\n**What it does:**\n\n- Shows the method on each workflow's page, under **How it's done**, with the line *Your Executive follows this for <workflow>, here and in chat.* A long method is cut short; **Show all** opens it in full and **Show less** folds it again. A workflow that follows more than one method shows each one with its name.\n- Lets you **Edit** it to fit your company. For a built-in workflow that saves your company's own version, marked **Customized**; **Reset to original** brings the shipped one back.\n- In chat, the Executive finds the method that fits and follows it for a quick answer or a draft, and runs or offers the workflow when you want the finished document.\n\n**Who it affects:** a method is shared by the whole workspace. An edit changes what the Executive follows for everyone, in that workflow (scheduled runs included) and in chat.\n\n**How to use:**\n\n1. Open **Work** in the sidebar, then a workflow (use **Browse N ready-made** for the built-in ones).\n2. Read **How it's done**. Click **Edit**, change the text (it's Markdown), and click **Save**. **Cancel** drops your changes.\n3. Changed your mind? **Reset to original** asks you to confirm, then brings back the shipped method. Your changes to it are lost.\n\n**Saving something you want repeated:** say *\"save this as a workflow\"* in chat after work you liked, or describe it. The Executive drafts a workflow with the method written into its steps and shows it to you; nothing is saved until you confirm. You can also start one from **What do you want to get done?** on the Workflows page.\n\n*Why the Executive won't edit a method from chat: workflows read their method on every run, scheduled ones included, and chat also answers email and other channels, where a crafted message could try to steer it. Methods change only when someone edits them on the workflow's page.*\n",
"mermaid": null,
- "generated_at": "2026-10-09T18:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/today.json b/packages/core/openexecutive/guide/prebuilt/today.json
index 7fe1b561..b22b9959 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.\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- Gathers everything else under **Everything else** as a row of count tiles — **Departments**, **People**, **Across the team** (waiting on someone else), **In flight**, **Handled overnight**, **Monitoring** — shown only when they have something in them. Click a tile to open its full list in a side panel.\n- The **Departments** tile shows each department's goal health — on-track, at-risk, or off-track — with the at-risk goals called out.\n- The **People** tile lists people with open items, their reply counts, SLA status, and whether they're on leave.\n- **Read today's brief** (next to **Needs you**) opens the written brief — what's going on across the company — in a side panel.\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 **For my inbox too**, the replies the Executive wrote in your Gmail Drafts for mail that needs you come first in **Needs you**. Only you see them.\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 **⋯**) — later today, tomorrow at 9:00 or Monday at 9:00. The card leaves Home and comes back on its own then; **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.\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 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 shows who wrote (and whether Gmail could confirm their address), what they wrote, your draft, and **Decide before sending** — what the draft leaves for you to answer. **Send** asks you once, naming who the reply goes to, then sends the draft from your Gmail exactly as it is there. If you changed who it goes to in Gmail, or they wrote again since, it asks a second time and says what changed. To change the wording, choose **Edit in Gmail** in the card's **⋯**, edit the draft there, then Send here or from Gmail. **Dismiss** (also in **⋯**) deletes the draft, unless you've already edited it in Gmail. On a server, Send needs signed sign-ins; until they're set up, send from Gmail. A card goes away on its own once you send or delete the draft in Gmail, or reply yourself, and after a week.\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.)\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, the tiles are **Due soon**, **Your projects** and **This week's review**, 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** 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- Gathers everything else under **Everything else** as a row of count tiles — **Departments**, **People**, **Across the team** (waiting on someone else), **Under way**, **Handled overnight**, **Monitoring**, and **Across your clients** when you look after client companies — shown only when they have something in them. Click a tile to open its full list in a side panel.\n- The **Departments** tile shows each department's goal health — on-track, at-risk, or off-track — with the at-risk goals called out.\n- The **People** tile lists people with open items, their reply counts, SLA status, and whether they're on leave.\n- **Read today's brief** (next to **Needs you**) opens the written brief — what's going on across the company — in a side panel.\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 **For my inbox too**, 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- Actions the Executive suggested from your email (a meeting, a message to someone, a new contact) 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), **Approve + allow** also lets it do that kind of action on its own from now on (shown while it is still learning), 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- 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, **Approve + allow** also lets it do the same thing with the same person 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 shows who wrote (and *Address not verified* when the address couldn't be confirmed), **What they wrote** (click to open), **Your draft** with who it goes to, *Why it waited for you* when Handle it for me left it for you, **Decide before sending** (what the draft leaves for you to answer) 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 - **Send + allow** (shown while replies are still being learned) sends it and lets replies to that person go on their own from now on while Handle it for me is on.\n - **Edit** 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.)\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, the tiles are **Due soon**, **Your projects** and **This week's review**, 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** 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-13T20:51:09Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/token_usage.json b/packages/core/openexecutive/guide/prebuilt/token_usage.json
index f61e69b5..f5ad25e1 100644
--- a/packages/core/openexecutive/guide/prebuilt/token_usage.json
+++ b/packages/core/openexecutive/guide/prebuilt/token_usage.json
@@ -1,7 +1,7 @@
{
"section_id": "token_usage",
"title": "Token Usage",
- "markdown": "**What it is:** Cost and token accounting — a breakdown of where your AI spend is going.\n\n**What it does:**\n\n- Show total tokens and cost over all time or a date range.\n- Break usage down by source, by day, and by model.\n- Compare fresh input vs cached tokens, so you can see caching paying off.\n- Drill into a single session's cost, turn by turn, from the Audit log.\n\n**How to use:**\n\n1. Open **Settings → Advanced → Token usage**.\n2. Set **From / Until** to look at a date range, or leave them blank for all time. **Clear filters** resets.\n3. Read the cards at the top: **Cost (USD)**, **Calls**, **Cache hit**, **Output tokens**, **Fresh input**, **Cache read**, **Cache write**, and **Searches**. A high cache-hit rate means you're paying the discounted rate for most input.\n4. Use the **By source**, **By model** and **By day (UTC)** tables to find what's driving spend.\n5. For one conversation's cost, go **← Audit log** and open that session.\n\n**Example:** spend jumped last week? Set **From / Until** to that week, check **By day** for the spike, then **By source** and **By model** to see what drove it.\n\n*Note: cached reads cost far less than fresh input — the system is built around caching to keep spend down. Lives under the Audit area in Settings.*",
+ "markdown": "**What it is:** What the AI has cost across every conversation, added up from the audit log: tokens, model calls, web searches and dollars.\n\n**What it does:**\n\n- Shows totals for all time or for a date range.\n- Breaks usage down by source, by model and by day.\n- Splits input into fresh input, cache reads and cache writes, so you can see how much the cache saves.\n- Shows the work the Executive did in one go with a tool it built, and the jobs it ran on files, when there are any.\n\n**How to use:**\n\n1. Open **Settings → Advanced → Token usage**, or click **Token usage** at the top of the Audit log.\n2. Set **From / Until** to look at a date range, or leave them blank for all time. **Clear filters** resets them.\n3. Read the cards at the top: **Cost (USD)**, **Calls**, **Cache hit** (the share of prompt input served from cache), **Output tokens**, **Fresh input**, **Cache read**, **Cache write**, and **Searches** (web searches the model ran).\n4. **Done in one go** appears when the Executive built a tool to repeat work over many items. It shows **Jobs done in one go**, **Actions taken**, **Model turns avoided** and **Time taken**.\n5. **Work on files** appears when the Executive ran Python jobs on files, such as splitting PDFs or building spreadsheets and charts. It shows **File jobs**, **Charged for those turns**, **CPU time** and **Largest job** (peak memory).\n6. Use the **By source**, **By model** and **By day (UTC)** tables to find what drives spend. Each row shows Calls, Input, Cache read, Cache write, Output, Searches, Cached and Cost. **By source** names the part of the system that made the calls, such as chat turns, research specialists, triage or memory extraction.\n7. For one conversation's tokens, open the Audit log with **← Audit log** and open that session's flow chart.\n\n**Good to know:**\n\n- Days are in UTC.\n- Cost is the charge recorded on each call. Calls logged before cost tracking started show tokens with a cost of $0.\n- The owner of the Executive sees everything. Other people see totals that leave out the owner's private activity.\n\n**Example:** spend jumped last week? Set **From / Until** to that week, check **By day (UTC)** for the spike, then **By source** and **By model** to see what drove it.",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/watchlist.json b/packages/core/openexecutive/guide/prebuilt/watchlist.json
index 95fda315..507409a3 100644
--- a/packages/core/openexecutive/guide/prebuilt/watchlist.json
+++ b/packages/core/openexecutive/guide/prebuilt/watchlist.json
@@ -1,7 +1,7 @@
{
"section_id": "watchlist",
"title": "Watch List",
- "markdown": "**What it is:** A set of external monitors that watch the outside world for you — stock tickers, RSS/Atom feeds, vendor status pages, SEC filings, web-search queries, and changes to specific web pages.\n\n**What it does:**\n\n- Add a monitor, choose its type and target, and set a severity range and optional trigger.\n- Enable or disable a monitor without deleting it, and see when it last fired.\n- Let qualifying signals flow into your briefing as proposals — the same path as inbound email or Slack.\n- Review monitors the Executive suggests before they go live.\n- Edit the whole list from chat as well as here.\n\n**How to use:**\n\n1. Open **Work** in the sidebar, pick the **Watch list** tab, and click **+ Add monitor**.\n2. Fill in the **Signal type** and **Target** (see the table below), and optional **Notes**. The rest is under **More options**, with sensible defaults:\n - **Slug** — a short id in lowercase-with-dashes, e.g. `acme-pricing-page`. Left empty, it is named from the type and target.\n - **Trigger (JSON, optional)** — narrows what counts as a hit; leave blank for the defaults.\n - **Cadence** — how often it is checked.\n - **Mode** — `active` raises alerts; `dry_run` records signals without alerting, which is handy for trying out a noisy source.\n - **Severity floor / ceiling** — signals below the floor are logged but never become alerts.\n3. Click **Add monitor**. Use the switch on a card to pause or resume it; click the card (or **Open details** in its **⋯**) to switch mode, edit notes, or **Delete monitor** (in the **⋯** on that page). A monitor the Executive added has **Stop watching** in its **⋯**.\n4. Check **Suggested by the Executive** now and then — **Approve** turns a suggestion on, and **Decline** in its **⋯** removes it, with a reason. Suggestions never alert until approved.\n\n| Signal type | Target | Trigger example |\n|---|---|---|\n| Stock | Ticker, e.g. `AAPL` | `{\"abs_change_pct_gte\": 5}` (default: 5% move) |\n| RSS / Atom | Feed URL | `{\"keywords\": [\"pricing\", \"launch\"]}` |\n| Vendor status | The status page's Atom/RSS feed URL | `{\"keywords\": [\"degraded\", \"outage\"]}` |\n| SEC EDGAR | Ticker or CIK, e.g. `AAPL` or `320193` | `{\"forms\": [\"8-K\"]}` (default: 8-K, 10-K, 10-Q) |\n| Page change | A public page URL | `{\"keywords\": [\"price\"]}` (default: any change) |\n| Web search (billed) | A search query, e.g. `Acme Corp layoffs OR funding` | `{\"keywords\": [\"acquisition\"]}` |\n\n**From chat:** *\"Watch Apple stock and alert me on 5% moves.\"* · *\"What are we watching right now?\"* · *\"Stop watching that competitor's blog, it's too noisy.\"* Chat is also the way to change a monitor's trigger or severity after it's created.\n\n*Note: each source type is checked on its own schedule — stock prices every 15 minutes, feeds and status pages more often than filings, web pages and web searches every 6 hours. Web-search monitors are billed per check, so use them sparingly.*",
+ "markdown": "**What it is:** A set of external monitors that watch the outside world for you — stock tickers, RSS/Atom feeds, vendor status pages, SEC filings, web-search queries, and changes to specific web pages.\n\n**What it does:**\n\n- Add a monitor, choose its type and target, and set a severity range and optional trigger.\n- Lists your monitors grouped by signal type, each card showing its target and when it last fired (or *Hasn't fired yet*). Click a group's heading to fold it.\n- Pause or resume a monitor without deleting it.\n- Let qualifying signals flow into your briefing as proposals — the same path as inbound email or Slack. Signals below a monitor's severity floor, or ones triage drops, never reach you.\n- Review monitors the Executive suggests before they go live.\n- Edit the whole list from chat as well as here.\n\n**How to use:**\n\n1. Open **Work** in the sidebar, pick the **Watch list** tab, and click **+ Add monitor**.\n2. Fill in the **Signal type** and **Target** (see the table below), and optional **Notes** (up to 500 characters). The rest is under **More options**, with defaults:\n - **Slug** — a short id in lowercase-with-dashes, e.g. `acme-pricing-page`. Left empty, it is named from the type and target. It must be unique.\n - **Trigger (JSON, optional)** — narrows what counts as a hit; leave blank for the defaults.\n - **Cadence** — `real_time`, `15min` (default), `hourly`, `daily` or `weekly`. It is stored with the monitor; how often a monitor is actually checked is set by its signal type (see the note below).\n - **Mode** — `active` (default) raises alerts; `dry_run` records signals without alerting, which is handy for trying out a noisy source.\n - **Severity floor / ceiling** — default `low` to `urgent`. Signals below the floor are logged but never become alerts.\n3. Click **Add monitor**. An RSS / Atom target is checked first: it must load as a feed with entries. A URL that loads as a readable page with no feed is added as a **Page change** monitor instead; anything else is refused with the reason.\n4. Use the switch on a card to pause or resume it. A paused monitor is not checked until you switch it back on.\n5. Click the card (or **Open details** in its **⋯**) to open its page. There you can:\n - switch **When it fires** between **Alert me** (`active`) and **Shadow only** (`dry_run`);\n - see its **Configuration**: mode, cadence, severity range, specialist, how often it fired and was dismissed, its trust score, when it was last checked and last fired, its trigger, and who added it;\n - edit **Notes** (saved when you click away);\n - read its **Recent signals**;\n - delete it with **Delete monitor** in the **⋯** at the top, then **Delete** to confirm. Its past signals stay in the audit log.\n6. A monitor the Executive added shows *added by the Executive* and has **Stop watching** choices in its **⋯**, each with a reason:\n - **not relevant** — removes it, and the Executive won't suggest that company or topic again;\n - **too noisy** — keeps it, but only high-severity signals get through;\n - **wrong source** — removes only this feed or page; the topic can still be watched another way.\n7. Check **Suggested by the Executive** now and then. These are sources the research council thought worth watching but couldn't tie firmly enough to your company data to add on its own. Each card shows what it is about, which department it is for (that department's head was asked to review it), when it was suggested, and how many signals it has seen in shadow. **Approve** turns it on. The **⋯** has **Decline** with the same three reasons as **Stop watching**; declining as *too noisy* turns it on with only high-severity signals. Suggestions never alert until approved, and declines are remembered.\n\n| Signal type | Target | Trigger example |\n|---|---|---|\n| Stock | Yahoo Finance ticker, e.g. `AAPL` | `{\"abs_change_pct_gte\": 5}` (default: 5% move) |\n| RSS / Atom | Feed URL | `{\"keywords\": [\"pricing\", \"launch\"]}` |\n| Vendor status | The status page's Atom/RSS feed URL | `{\"keywords\": [\"degraded\", \"outage\"]}` |\n| SEC EDGAR | Ticker or CIK, e.g. `AAPL` or `320193` | `{\"forms\": [\"8-K\"]}` (default: 8-K, 10-K, 10-Q) |\n| Page change | A public page URL | `{\"keywords\": [\"price\"]}` (default: any change) |\n| Web search (billed) | A search query, e.g. `Acme Corp layoffs OR funding` | `{\"keywords\": [\"acquisition\"]}` |\n\n**From chat:** *\"Watch Apple stock and alert me on 5% moves.\"* · *\"What are we watching right now?\"* · *\"Stop watching that competitor's blog, it's too noisy.\"* Chat is also the way to change a monitor's trigger, severity range or cadence after it's created; the page only changes mode, notes and on/off.\n\n*Note: each signal type is checked on its own schedule: vendor status pages every 5 minutes, stock prices every 15 minutes, RSS/Atom feeds every 30 minutes, SEC filings every hour, and page changes and web searches every 6 hours. Web-search monitors run a paid AI web search on every check, so use them sparingly.*",
"mermaid": null,
- "generated_at": "2026-10-03T12:00:00Z"
+ "generated_at": "2026-10-15T21:00:00Z"
}
diff --git a/packages/core/openexecutive/guide/sections.py b/packages/core/openexecutive/guide/sections.py
index a441d201..2a4a5c04 100644
--- a/packages/core/openexecutive/guide/sections.py
+++ b/packages/core/openexecutive/guide/sections.py
@@ -32,8 +32,8 @@ GUIDE_SECTIONS: list[GuideSection] = [
),
GuideSection(
id="ask_oe",
- title="Ask OE",
- sub="The page-aware assistant panel — explains any screen and fills forms for you to review.",
+ title="Help with this page",
+ sub="The sparkle button at the top right: explains any screen, answers how the app works, and fills forms for you to review.",
),
GuideSection(
id="today",
@@ -125,10 +125,15 @@ GUIDE_SECTIONS: list[GuideSection] = [
title="Integrations",
sub="Reach the Executive where you already work — Slack, Discord, Telegram, email, Google Chat, MCP.",
),
+ GuideSection(
+ id="delegate",
+ title="Delegate",
+ sub="What the Executive may do without asking you, writing email as you, and handling things on its own.",
+ ),
GuideSection(
id="settings",
title="Settings & Advanced",
- sub="Your Executive, workspace, Act as me, and the Advanced tools outside the day-to-day nav — including this guide.",
+ sub="Your Executive, workspace, notifications, and the Advanced tools outside the day-to-day nav — including this guide.",
),
]
diff --git a/packages/core/openexecutive/orchestrator/activity_labels.py b/packages/core/openexecutive/orchestrator/activity_labels.py
index 2687671f..cf2cd25e 100644
--- a/packages/core/openexecutive/orchestrator/activity_labels.py
+++ b/packages/core/openexecutive/orchestrator/activity_labels.py
@@ -120,6 +120,8 @@ _LABELS: dict[str, str] = {
# Ask OE panel form fill
"propose_form_values": "Filling in the form…",
+ # How the app itself works (the user guide)
+ "read_user_guide": "Checking the user guide…",
# Act as me: a draft in the speaker's own Gmail (never sent)
"ghostwrite_email": "Drafting an email in your voice…",
diff --git a/packages/core/openexecutive/orchestrator/executive.py b/packages/core/openexecutive/orchestrator/executive.py
index cc18fb72..577ee3e1 100644
--- a/packages/core/openexecutive/orchestrator/executive.py
+++ b/packages/core/openexecutive/orchestrator/executive.py
@@ -105,6 +105,10 @@ from openexecutive.orchestrator.form_tools import (
PROPOSE_FORM_VALUES,
build_form_patch_event,
)
+from openexecutive.orchestrator.guide_tools import (
+ GUIDE_TOOL_HANDLERS,
+ GUIDE_TOOLS,
+)
from openexecutive.orchestrator.history_tools import (
HISTORY_TOOL_HANDLERS,
HISTORY_TOOL_NAMES,
@@ -745,6 +749,7 @@ _ALL_SKILL_TOOLS = [
*WORKFLOW_AUTHORING_TOOLS,
*WORKFLOW_RUN_TOOLS,
*FORM_TOOLS,
+ *GUIDE_TOOLS,
*PYTHON_JOB_TOOLS,
]
@@ -775,6 +780,7 @@ _ALL_SKILL_HANDLERS = {
**WORKFLOW_AUTHORING_TOOL_HANDLERS,
**WORKFLOW_RUN_TOOL_HANDLERS,
**FORM_TOOL_HANDLERS,
+ **GUIDE_TOOL_HANDLERS,
**PYTHON_JOB_TOOL_HANDLERS,
}
diff --git a/packages/core/openexecutive/orchestrator/guide_tools.py b/packages/core/openexecutive/orchestrator/guide_tools.py
new file mode 100644
index 00000000..c8f14fdf
--- /dev/null
+++ b/packages/core/openexecutive/orchestrator/guide_tools.py
@@ -0,0 +1,101 @@
+"""Anthropic tool definition + handler for reading the user guide.
+
+``read_user_guide`` lets the Executive answer "how does X work in Open
+Executive?" from the same hand-written guide the ``/guide`` page shows
+(``guide/prebuilt/<id>.json``), for any part of the app, not only the page
+the Ask OE panel is open on. The panel still sends the current page's
+section inline (``api/routes/chat.py`` ``_build_page_context_block``); this
+tool covers questions about every other part of the product.
+
+Cache note: the definition is static (built once at import from
+``GUIDE_SECTIONS``) and always offered, so it never changes the cached
+tools prefix between turns. A read is a plain file read: no model call.
+"""
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from openexecutive.guide.prebuilt import get_prebuilt
+from openexecutive.guide.sections import GUIDE_SECTIONS, GuideSection
+
+READ_USER_GUIDE = "read_user_guide"
+
+
+def answerable_sections() -> list[GuideSection]:
+ """The guide sections the Executive may read and describe."""
+ return list(GUIDE_SECTIONS)
+
+
+def section_markdown(section_id: str) -> str | None:
+ """The text of one answerable guide section, or None."""
+ if section_id not in {s.id for s in answerable_sections()}:
+ return None
+ content = get_prebuilt(section_id)
+ markdown = (content or {}).get("markdown")
+ return markdown if isinstance(markdown, str) and markdown else None
+
+
+def _tool_definition() -> dict[str, Any]:
+ sections = answerable_sections()
+ index = "\n".join(f"- {s.id}: {s.title}" for s in sections)
+ return {
+ "name": READ_USER_GUIDE,
+ "description": (
+ "Read one section of the Open Executive user guide: what a part of "
+ "the app is, what each control does, who can see or use it, and "
+ "how to use it. Call this when someone asks how Open Executive "
+ "itself works (a page, a button, a setting, sharing, who sees "
+ "what) and the answer is not already in a <page_context> block. "
+ "Answer from what the section says; if it does not cover the "
+ "question, say so plainly. Sections:\n" + index
+ ),
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "section_id": {
+ "type": "string",
+ "enum": [s.id for s in sections],
+ "description": "The section to read.",
+ },
+ },
+ "required": ["section_id"],
+ },
+ }
+
+
+READ_USER_GUIDE_TOOL: dict[str, Any] = _tool_definition()
+
+GUIDE_TOOLS: list[dict[str, Any]] = [READ_USER_GUIDE_TOOL]
+
+
+async def handle_read_user_guide(tool_input: dict[str, Any]) -> str:
+ section_id = str(tool_input.get("section_id", "")).strip()
+ known = {s.id: s for s in answerable_sections()}
+ if section_id not in known:
+ return json.dumps(
+ {"error": f"unknown section {section_id!r}", "sections": sorted(known)}
+ )
+ markdown = section_markdown(section_id)
+ if markdown is None:
+ return json.dumps({"error": f"section {section_id!r} has no content"})
+ return json.dumps(
+ {"section_id": section_id, "title": known[section_id].title, "markdown": markdown}
+ )
+
+
+GUIDE_TOOL_HANDLERS: dict[str, Callable[[dict[str, Any]], Awaitable[str]]] = {
+ READ_USER_GUIDE: handle_read_user_guide,
+}
+
+
+__all__ = [
+ "GUIDE_TOOLS",
+ "GUIDE_TOOL_HANDLERS",
+ "READ_USER_GUIDE",
+ "READ_USER_GUIDE_TOOL",
+ "answerable_sections",
+ "handle_read_user_guide",
+ "section_markdown",
+]
diff --git a/packages/core/tests/unit/test_chat_route_page_context.py b/packages/core/tests/unit/test_chat_route_page_context.py
index d28f73ba..8cd5af71 100644
--- a/packages/core/tests/unit/test_chat_route_page_context.py
+++ b/packages/core/tests/unit/test_chat_route_page_context.py
@@ -133,6 +133,7 @@ def test_page_context_block_reaches_stream_chat(
block = captured["stream_chat"]["page_context_block"]
assert 'PAGE: /jobs/new — "New workflow"' in block
assert "USER GUIDE FOR THIS PAGE (jobs):" in block
+ assert "read_user_guide" in block
assert "GUIDE-MARKDOWN-FOR-JOBS" in block
assert "FORM ON SCREEN (form_id=workflow_builder)" in block
assert '"name":"title"' in block.replace(" ", "")
diff --git a/packages/core/tests/unit/test_guide_tools.py b/packages/core/tests/unit/test_guide_tools.py
new file mode 100644
index 00000000..df959391
--- /dev/null
+++ b/packages/core/tests/unit/test_guide_tools.py
@@ -0,0 +1,48 @@
+"""read_user_guide: the Executive reads any user-guide section on demand."""
+from __future__ import annotations
+
+import asyncio
+import json
+
+from openexecutive.guide.sections import GUIDE_SECTIONS
+from openexecutive.orchestrator import executive
+from openexecutive.orchestrator.guide_tools import (
+ READ_USER_GUIDE,
+ READ_USER_GUIDE_TOOL,
+ handle_read_user_guide,
+)
+
+
+def _read(section_id: object) -> dict:
+ return json.loads(asyncio.run(handle_read_user_guide({"section_id": section_id})))
+
+
+def test_tool_offers_every_guide_section() -> None:
+ enum = READ_USER_GUIDE_TOOL["input_schema"]["properties"]["section_id"]["enum"]
+ assert enum == [s.id for s in GUIDE_SECTIONS]
+ for s in GUIDE_SECTIONS:
+ assert f"- {s.id}: {s.title}" in READ_USER_GUIDE_TOOL["description"]
+
+
+def test_reads_a_section_markdown() -> None:
+ out = _read("chat")
+ assert out["section_id"] == "chat"
+ assert "**How to use:**" in out["markdown"]
+
+
+def test_unknown_or_path_like_section_is_refused() -> None:
+ for bad in ("nope", "../architecture/prebuilt/api", "", None):
+ out = _read(bad)
+ assert "error" in out
+ assert "chat" in out["sections"]
+
+
+def test_executive_offers_and_handles_it() -> None:
+ assert any(t["name"] == READ_USER_GUIDE for t in executive._ALL_SKILL_TOOLS)
+ assert READ_USER_GUIDE in executive._ALL_SKILL_HANDLERS
+
+
+def test_sharing_question_is_answerable_from_the_chat_section() -> None:
+ # Ask OE once could not say what sharing a chat does: the guide must.
+ markdown = _read("chat")["markdown"].lower()
+ assert "share" in markdown and "read-only" in markdown
diff --git a/packages/core/tests/unit/test_pr_checks.py b/packages/core/tests/unit/test_pr_checks.py
index c59e9baa..19b9c9cb 100644
--- a/packages/core/tests/unit/test_pr_checks.py
+++ b/packages/core/tests/unit/test_pr_checks.py
@@ -99,6 +99,62 @@ def test_drift_waiver_needs_own_line_and_reason(text: str) -> None:
assert _level(pr_checks.check_arch_drift, changed=changed, waiver_text=text) == "FAIL"
+# --- guide-drift -------------------------------------------------------------
+
+UI = "packages/ui/src/"
+GUIDE = PKG + "guide/prebuilt/"
+
+
+def test_guide_drift_fails_when_a_screen_changes_without_its_section() -> None:
+ changed = {UI + "app/chats/page.tsx", GUIDE + "people.json"}
+ result = pr_checks.check_guide_drift(Change(changed=changed))
+ assert result.level == "FAIL"
+ assert "app/chats/page.tsx" in result.detail and "chat" in result.detail
+
+
+def test_guide_drift_passes_when_its_section_changes() -> None:
+ changed = {UI + "components/sessions/ShareDialog.tsx", GUIDE + "chat.json"}
+ assert _level(pr_checks.check_guide_drift, changed=changed) == "PASS"
+
+
+def test_guide_drift_longest_prefix_wins() -> None:
+ changed = {UI + "app/settings/tools/page.tsx", GUIDE + "settings.json"}
+ assert _level(pr_checks.check_guide_drift, changed=changed) == "FAIL"
+ changed = {UI + "app/settings/tools/page.tsx", GUIDE + "custom_tools.json"}
+ assert _level(pr_checks.check_guide_drift, changed=changed) == "PASS"
+
+
+def test_guide_drift_ignores_unmapped_paths_tests_and_styles() -> None:
+ changed = {
+ UI + "components/shell/AppShell.tsx",
+ UI + "app/chats/chats.test.ts",
+ UI + "app/globals.css",
+ UI + "app/api/chat/route.ts",
+ PKG + "orchestrator/executive.py",
+ }
+ assert _level(pr_checks.check_guide_drift, changed=changed) == "PASS"
+
+
[email protected]("text", ["Guide: n/a - spacing only", "x\n\nguide: N/A — refactor"])
+def test_guide_drift_waiver_line_passes(text: str) -> None:
+ changed = {UI + "app/people/page.tsx"}
+ assert _level(pr_checks.check_guide_drift, changed=changed, waiver_text=text) == "PASS"
+
+
[email protected]("text", ["see Guide: n/a - x", "Guide: n/a", "Arch-Docs: n/a - x"])
+def test_guide_drift_waiver_needs_own_line_and_reason(text: str) -> None:
+ changed = {UI + "app/people/page.tsx"}
+ assert _level(pr_checks.check_guide_drift, changed=changed, waiver_text=text) == "FAIL"
+
+
+def test_guide_drift_ids_are_guide_sections() -> None:
+ from openexecutive.guide.sections import GUIDE_SECTIONS
+
+ ids = {s.id for s in GUIDE_SECTIONS}
+ for prefix, sections in pr_checks.GUIDE_FOR.items():
+ assert sections <= ids, prefix
+
+
# --- no-stubs ----------------------------------------------------------------
diff --git a/packages/ui/src/app/guide/page.tsx b/packages/ui/src/app/guide/page.tsx
index 947864fd..3f284450 100644
--- a/packages/ui/src/app/guide/page.tsx
+++ b/packages/ui/src/app/guide/page.tsx
@@ -10,7 +10,7 @@ import PageSideNav from '@/components/shell/PageSideNav';
// packages/core/openexecutive/guide/sections.py.
const SECTIONS = [
{ id: 'chat', label: 'Chat & Briefing', sub: "The main surface — talk to the Executive, and land on a briefing of what's happened." },
- { id: 'ask_oe', label: 'Ask OE', sub: 'The page-aware assistant panel — explains any screen and fills forms for you to review.' },
+ { id: 'ask_oe', label: 'Help with this page', sub: 'The sparkle button at the top right: explains any screen, answers how the app works, and fills forms for you to review.' },
{ id: 'today', label: 'Today / Morning Brief', sub: 'What needs you right now: proposals, department health, and people with open items.' },
{ id: 'pulse', label: 'Pulse (Memory)', sub: "The Executive's running memory — decisions made, initiatives in flight, advice gathered, corrections kept." },
{ id: 'review', label: 'Review Queue', sub: 'On Knowledge, under Advanced. Built-in knowledge is trusted by default. Review what you upload or edit, or send a domain for review yourself.' },
@@ -29,7 +29,8 @@ const SECTIONS = [
{ id: 'simulator', label: 'Company Simulator', sub: 'Load a realistic test company to try the Executive before trusting it with real data.' },
{ id: 'clients', label: 'Client Companies', sub: 'Multi-client mode for fractional work — switch the live company between named client slots.' },
{ id: 'integrations', label: 'Integrations', sub: 'Reach the Executive where you already work — Slack, Discord, Telegram, email, Google Chat, MCP.' },
- { id: 'settings', label: 'Settings & Advanced', sub: 'Your Executive, workspace, Act as me, and the Advanced tools outside the day-to-day nav — including this guide.' },
+ { id: 'delegate', label: 'Delegate', sub: 'What the Executive may do without asking you, writing email as you, and handling things on its own.' },
+ { id: 'settings', label: 'Settings & Advanced', sub: 'Your Executive, workspace, notifications, and the Advanced tools outside the day-to-day nav — including this guide.' },
];
interface SectionMeta {
diff --git a/packages/ui/src/components/askoe/AskOEContext.tsx b/packages/ui/src/components/askoe/AskOEContext.tsx
index a3ce2ff0..1f558f27 100644
--- a/packages/ui/src/components/askoe/AskOEContext.tsx
+++ b/packages/ui/src/components/askoe/AskOEContext.tsx
@@ -53,6 +53,9 @@ const ROUTE_GUIDE_MAP: Array<{ prefix: string; guideId: string; title: string }>
{ prefix: "/audit/usage", guideId: "token_usage", title: "Token usage" },
{ prefix: "/audit", guideId: "audit", title: "Audit log" },
{ prefix: "/today", guideId: "today", title: "Today" },
+ { prefix: "/chats", guideId: "chat", title: "Chats" },
+ { prefix: "/delegate", guideId: "delegate", title: "Delegate" },
+ { prefix: "/skills", guideId: "skills", title: "How it's done" },
{ prefix: "/memories", guideId: "pulse", title: "Pulse" },
{ prefix: "/review", guideId: "review", title: "Review queue" },
{ prefix: "/jobs", guideId: "jobs", title: "Workflows" },
@@ -66,12 +69,16 @@ const ROUTE_GUIDE_MAP: Array<{ prefix: string; guideId: string; title: string }>
{ prefix: "/knowledge", guideId: "knowledge", title: "Knowledge" },
{ prefix: "/council", guideId: "council", title: "Agent Council" },
{ prefix: "/demo", guideId: "simulator", title: "Company Simulator" },
+ { prefix: "/clients", guideId: "clients", title: "Client Companies" },
+ { prefix: "/onboard", guideId: "company_profile", title: "Onboarding" },
+ { prefix: "/settings/tools", guideId: "custom_tools", title: "Tools" },
{ prefix: "/settings", guideId: "settings", title: "Settings" },
+ // Home: only "/" itself matches (no route starts with "//").
+ { prefix: "/", guideId: "chat", title: "Home" },
];
// Routes with no guide section yet — still want a readable page title.
const EXTRA_TITLES: Array<{ prefix: string; title: string }> = [
- { prefix: "/clients", title: "Client Companies" },
{ prefix: "/architecture", title: "Architecture" },
{ prefix: "/guide", title: "User Guide" },
];
@@ -110,6 +117,8 @@ interface AskOEContextValue {
markSuggested: (names: string[]) => void;
clearSuggested: (name?: string) => void;
buildPageContext: () => PageContext;
+ /** The current page's name, shown as the panel's title. */
+ pageTitle: string;
}
const AskOECtx = createContext<AskOEContextValue | null>(null);
@@ -190,6 +199,8 @@ export function AskOEProvider({ children }: { children: React.ReactNode }) {
};
}, [pathname]);
+ const pageTitle = resolveRouteMeta(pathname).title;
+
const value = useMemo<AskOEContextValue>(
() => ({
open,
@@ -203,6 +214,7 @@ export function AskOEProvider({ children }: { children: React.ReactNode }) {
markSuggested,
clearSuggested,
buildPageContext,
+ pageTitle,
}),
[
open,
@@ -215,6 +227,7 @@ export function AskOEProvider({ children }: { children: React.ReactNode }) {
markSuggested,
clearSuggested,
buildPageContext,
+ pageTitle,
]
);
diff --git a/packages/ui/src/components/askoe/AskOEPanel.tsx b/packages/ui/src/components/askoe/AskOEPanel.tsx
index b8ae7576..6dacdece 100644
--- a/packages/ui/src/components/askoe/AskOEPanel.tsx
+++ b/packages/ui/src/components/askoe/AskOEPanel.tsx
@@ -319,13 +319,13 @@ export default function AskOEPanel() {
aria-hidden="true"
/>
<aside
- aria-label="Ask OE"
+ aria-label={`Help with ${ctx.pageTitle}`}
className="fixed top-8 bottom-0 right-0 z-40 w-[min(24rem,100vw)] lg:static lg:z-auto lg:w-[380px] flex-shrink-0 border-l border-line bg-surface-elevated flex flex-col"
>
<div className="h-14 px-4 border-b border-line flex items-center justify-between flex-shrink-0">
<div className="flex items-center gap-2 min-w-0">
<Icon name="bolt" size="w-4 h-4" className="text-indigo-300 flex-shrink-0" />
- <span className="text-sm font-semibold text-fg truncate">Ask OE</span>
+ <span className="text-sm font-semibold text-fg truncate">{ctx.pageTitle}</span>
</div>
<div className="flex items-center gap-1">
<button
@@ -341,7 +341,7 @@ export default function AskOEPanel() {
type="button"
onClick={() => ctx.setOpen(false)}
title="Close (Ctrl/Cmd + .)"
- aria-label="Close Ask OE"
+ aria-label="Close help"
className="min-h-touch min-w-touch flex items-center justify-center text-fg-muted hover:text-fg rounded-lg hover:bg-surface-overlay transition-colors"
>
<Icon name="close" size="w-4 h-4" />
diff --git a/packages/ui/src/components/settings/ActAsMeCard.tsx b/packages/ui/src/components/settings/ActAsMeCard.tsx
index 94d8b533..5a95cafc 100644
--- a/packages/ui/src/components/settings/ActAsMeCard.tsx
+++ b/packages/ui/src/components/settings/ActAsMeCard.tsx
@@ -446,7 +446,7 @@ function CalendarSection({
? "Ask about your day or your week in chat and it reads your own calendar. It never changes it."
: actAsMeOn
? "Off: it can't see your calendar. On, it reads it when you ask, and never changes it."
- : "Move How far it goes as you up from Off first."
+ : "Set What it writes as you above Off first."
}
action={
<Switch
diff --git a/packages/ui/src/components/settings/ReachCard.tsx b/packages/ui/src/components/settings/ReachCard.tsx
index c323d54e..c4af106b 100644
--- a/packages/ui/src/components/settings/ReachCard.tsx
+++ b/packages/ui/src/components/settings/ReachCard.tsx
@@ -225,7 +225,7 @@ export function WritesCard({
{
value: "inbox",
label: "For my inbox too",
- line: "It also writes a first reply to mail that needs you and puts it on Today.",
+ line: "It also writes a first reply to mail that needs you and puts it on Home.",
reason: needsMailbox,
},
];
diff --git a/packages/ui/src/components/settings/TakeTheLeadCard.tsx b/packages/ui/src/components/settings/TakeTheLeadCard.tsx
index 4b7ff531..918b12a6 100644
--- a/packages/ui/src/components/settings/TakeTheLeadCard.tsx
+++ b/packages/ui/src/components/settings/TakeTheLeadCard.tsx
@@ -106,7 +106,7 @@ export default function TakeTheLeadCard() {
!lead.available
? "Needs signed sign-ins on this server before it can be turned on."
: mode === "training"
- ? "In training, everything it would do comes to you as a card on Today first. What you allow, it does on its own from then on."
+ ? "In training, everything it would do comes to you as a card on Home first. What you allow, it does on its own from then on."
: mode === "on"
? "It acts on what it finds while it looks over your day: it messages people, books meetings and starts workflows. Anything below waits for a yes first."
: "Off: when it looks over your day it tells you what it would do, and you do it."
@@ -205,7 +205,7 @@ export default function TakeTheLeadCard() {
<div>
<h3 className="text-[15px] font-semibold text-fg">Always asks first</h3>
<p className="mt-1 text-sm text-fg-muted">
- These wait for you, or for whoever approves that area (like spending or hiring), with a card on Today.
+ These wait for you, or for whoever approves that area (like spending or hiring), with a card on Home.
{!lead.enabled && " While Take the lead is off, only the last one applies: the rest are kept for when it's on."}
</p>
<ul className="mt-3 flex flex-col divide-y divide-line rounded-xl border border-line">
diff --git a/packages/ui/src/components/shell/AppShell.tsx b/packages/ui/src/components/shell/AppShell.tsx
index 280578b5..2154bf0f 100644
--- a/packages/ui/src/components/shell/AppShell.tsx
+++ b/packages/ui/src/components/shell/AppShell.tsx
@@ -279,15 +279,14 @@ function AskOEButton() {
<button
type="button"
onClick={toggle}
- title="Ask OE about this page (Ctrl/Cmd + .)"
+ title="Help with this page (Ctrl/Cmd + .)"
+ aria-label="Help with this page"
aria-pressed={open}
- className={`flex min-h-10 items-center gap-1.5 px-3 rounded-lg text-sm font-semibold text-accent transition-colors cursor-pointer ${
+ className={`flex min-h-10 min-w-10 items-center justify-center rounded-lg text-accent transition-colors cursor-pointer ${
open ? "bg-accent/20" : "bg-accent/10 hover:bg-accent/15"
}`}
>
<Icon name="sparkles" size="w-4 h-4" />
- <span className="sm:hidden">Ask</span>
- <span className="hidden sm:inline">Ask OE</span>
</button>
);
}
diff --git a/scripts/pr_checks.py b/scripts/pr_checks.py
index 264c3894..0e791880 100644
--- a/scripts/pr_checks.py
+++ b/scripts/pr_checks.py
@@ -10,6 +10,8 @@ Checks (see CLAUDE.md -> "Architecture Docs" and "PR Requirements"):
- arch-doc-drift FAIL a documented module changed but its
architecture/prebuilt/<section>.json did not
+- guide-drift FAIL a screen changed but its user-guide section
+ (guide/prebuilt/<section>.json) did not
- no-stubs FAIL added code lines carry TODO/FIXME/NotImplementedError
- eval-scenarios FAIL a new agent or a domain-prompt change without an
evals/_scenarios/ change
@@ -26,6 +28,11 @@ check with a line in a commit message or the PR description:
Arch-Docs: n/a - <reason>
+The user guide is what Ask OE answers product questions from, so a change to a
+screen updates its guide section too, or says why not:
+
+ Guide: n/a - <reason>
+
Stdlib only, so it runs without the project's virtualenv.
"""
@@ -81,6 +88,68 @@ SECTIONS_FOR: dict[str, set[str]] = {
"guide": {"user_guide"},
}
+GUIDE_PREBUILT = PKG + "guide/prebuilt/"
+UI_SRC = "packages/ui/src/"
+
+# Screen (path under packages/ui/src/, longest prefix wins) -> the user-guide
+# sections describing it; editing any one satisfies the gate. Paths not listed
+# (the shell, shared ui bits, api routes) are not checked. Keep the ids in step
+# with guide/sections.py (a test checks).
+GUIDE_FOR: dict[str, set[str]] = {
+ "app/page.tsx": {"chat", "today"},
+ "components/Briefing.tsx": {"chat", "today"},
+ "components/briefing/": {"chat", "today"},
+ "components/ActionCards.tsx": {"chat", "today"},
+ "app/chats/": {"chat"},
+ "components/sessions/": {"chat"},
+ "components/Chat.tsx": {"chat"},
+ "components/Message.tsx": {"chat"},
+ "components/AnswerSourcesFooter.tsx": {"chat"},
+ "components/askoe/": {"ask_oe"},
+ "app/today/": {"today"},
+ "app/memories/": {"pulse"},
+ "components/memories/": {"pulse"},
+ "app/review/": {"review"},
+ "components/ReviewQueue.tsx": {"review"},
+ "app/jobs/": {"jobs"},
+ "components/jobs/": {"jobs"},
+ "components/WorkflowRunner.tsx": {"jobs"},
+ "app/skills/": {"skills"},
+ "app/artifacts/": {"artifacts"},
+ "components/ArtifactViewer.tsx": {"artifacts"},
+ "app/watchlist/": {"watchlist"},
+ "app/departments/": {"departments"},
+ "app/goals/": {"departments"},
+ "components/goals/": {"departments"},
+ "app/people/": {"people"},
+ "components/people/": {"people"},
+ "app/company-profile/": {"company_profile"},
+ "components/company-profile/": {"company_profile"},
+ "app/onboard/": {"company_profile"},
+ "components/onboard/": {"company_profile"},
+ "components/OnboardWizard.tsx": {"company_profile"},
+ "app/knowledge/": {"knowledge"},
+ "components/knowledge/": {"knowledge"},
+ "app/council/": {"council"},
+ "app/audit/usage/": {"token_usage"},
+ "app/audit/": {"audit"},
+ "app/demo/": {"simulator"},
+ "app/clients/": {"clients"},
+ "app/delegate/": {"delegate"},
+ "components/delegate/": {"delegate"},
+ "app/settings/act-as-me/": {"delegate"},
+ "app/settings/on-its-own/": {"delegate"},
+ "app/settings/tools/": {"custom_tools"},
+ "app/settings/": {"settings", "integrations"},
+ "components/settings/": {"settings", "integrations"},
+ "components/workspace/": {"settings"},
+ "components/executive/": {"settings"},
+}
+GUIDE_WAIVER_RE = re.compile(
+ r"^[ \t]*Guide:[ \t]*n/?a\b[ \t]*[-\u2013\u2014:][ \t]*\S.*$",
+ re.IGNORECASE | re.MULTILINE,
+)
+
# Needs a reason after the n/a: "Arch-Docs: n/a - renamed a helper".
WAIVER_RE = re.compile(
r"^[ \t]*Arch-Docs:[ \t]*n/?a\b[ \t]*[-\u2013\u2014:][ \t]*\S.*$",
@@ -211,6 +280,44 @@ def check_arch_drift(c: Change) -> Result:
)
+def _guide_sections_for(path: str) -> set[str] | None:
+ if not path.startswith(UI_SRC) or not path.endswith((".ts", ".tsx")):
+ return None
+ if ".test." in path:
+ return None
+ rel = path[len(UI_SRC) :]
+ best = max((p for p in GUIDE_FOR if rel == p or (p.endswith("/") and rel.startswith(p))), key=len, default=None)
+ return GUIDE_FOR[best] if best else None
+
+
+def check_guide_drift(c: Change) -> Result:
+ name = "guide-drift"
+ touched = {
+ p[len(GUIDE_PREBUILT) : -len(".json")]
+ for p in c.changed
+ if p.startswith(GUIDE_PREBUILT) and p.endswith(".json")
+ }
+ missing: dict[str, set[str]] = {}
+ for p in sorted(c.code_changed()):
+ expect = _guide_sections_for(p)
+ if expect and not expect & touched:
+ missing.setdefault(", ".join(sorted(expect)), set()).add(p[len(UI_SRC) :])
+ if not missing:
+ return Result(name, "PASS", f"guide sections={sorted(touched)}")
+ need = "; ".join(f"{', '.join(sorted(files))} (edit one of: {ids})" for ids, files in missing.items())
+ if waived := GUIDE_WAIVER_RE.search(c.waiver_text):
+ return Result(name, "PASS", f"waived ({waived.group(0).strip()}); would need: {need}")
+ return Result(
+ name,
+ "FAIL",
+ "user guide not updated for: "
+ + need
+ + f". Ask OE answers product questions from {GUIDE_PREBUILT}<section>.json: "
+ "update what the change alters there, or add 'Guide: n/a - <reason>' "
+ "to a commit message or the PR description.",
+ )
+
+
def check_no_stubs(c: Change) -> Result:
hits = [
f"{path}: {line.strip()[:80]}"
@@ -293,7 +400,7 @@ def check_pinned_actions(c: Change) -> Result:
return Result("pinned-actions", "PASS", "added workflow steps pin actions by SHA")
-CHECKS = (check_arch_drift, check_no_stubs, check_eval_scenarios, check_tests_present, check_pinned_actions)
+CHECKS = (check_arch_drift, check_guide_drift, check_no_stubs, check_eval_scenarios, check_tests_present, check_pinned_actions)
def run_checks(c: Change) -> list[Result]: