Skip to content

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

docs(guide): add how-to steps and examples to every section (#188)

Rufus8d3d37b5f756
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index 7e223b43..1df5f350 100644
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@ -3486,7 +3486,7 @@ artifacts:
user_guide:
summary: |
`/guide` is a plain-language overview of every user-facing feature —
- "what it is, what it does" — for non-engineers. It is deliberately
+ "what it is, what it does, how to use it" — for non-engineers. It is deliberately
SEPARATE from the `/architecture` technical reference: Architecture
explains how the system is built; the User Guide explains what each
feature does for the user. Reached from a tile on the Settings hub
@@ -3519,8 +3519,12 @@ user_guide:
When a user-facing feature is added or materially changed, add/update
the matching `guide/prebuilt/<id>.json` plus its registry entry in
`guide/sections.py` and the mirror list in `app/guide/page.tsx` (IDs
- must match). The `user_guide` architecture section documents this
- surface for engineers.
+ must match). Every section carries a `**How to use:**` walkthrough
+ (where to click, which fields matter, what to say in chat) and, where
+ it helps, an `**Example:**` — enforced by
+ `tests/unit/test_guide_prebuilt.py`. Ask OE injects the page's section
+ into the user turn, so the how-to steps also ground its answers. The
+ `user_guide` architecture section documents this surface for engineers.
auth:
ui_provider: |
diff --git a/packages/core/openexecutive/architecture/prebuilt/user_guide.json b/packages/core/openexecutive/architecture/prebuilt/user_guide.json
index 70885c90..d7013bc2 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\" — 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 a **tile on the Settings hub** (`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.",
+ "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 a **tile on the Settings hub** (`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.",
"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-06-06T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/artifacts.json b/packages/core/openexecutive/guide/prebuilt/artifacts.json
index 7e132553..a6c6fd5d 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": "Artifacts",
- "markdown": "**What it is:** Your library of finished documents — both drafted memos and the Markdown outputs of workflow runs — in one searchable place.\n\n**What it does:**\n\n- See all active artifacts, filtered by kind (drafts vs workflow outputs) or by source.\n- Archive an artifact 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** views.\n\n*Note: archiving is a soft-delete — nothing is lost until you explicitly delete it.*",
+ "markdown": "**What it is:** Your library of finished documents — both drafted memos and the Markdown outputs of workflow runs — in one searchable place.\n\n**What it does:**\n\n- See all active artifacts, filtered by kind (drafts vs workflow outputs).\n- Open any artifact to read it, copy it, or download it as Markdown.\n- Archive an artifact 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** views.\n\n**How to use:**\n\n1. Get something in here. Ask the Executive to write something up for your review — the Executive decides what's worth a draft, and asking for one explicitly is the most reliable way. Drafts also appear as a card in the Briefing's **Needs you** lane. Every workflow run adds its output here automatically.\n2. Open **Artifacts** in the sidebar. Filter by **Drafts** or **Workflows**, and switch between **Active** and **Archived**.\n3. Click an artifact to read it; use **Copy** or **Download .md** to take it elsewhere.\n4. Hover over a row to **Archive** it (an **Undo** appears for a moment), **Restore** it from the Archived view, or **Delete permanently** (you'll be asked to confirm).\n\n**Example:** *\"Write up a teardown of Acme's new pricing as a memo for me to review.\"* The memo lands in **Needs you** and in **Artifacts**. Once you've read it, click **✓ Mark reviewed** on the Briefing card — the memo stays in your library.\n\n*Note: archiving is a soft-delete — nothing is lost until you explicitly delete it.*",
"mermaid": null,
- "generated_at": "2026-06-06T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/ask_oe.json b/packages/core/openexecutive/guide/prebuilt/ask_oe.json
index d8f31d15..0db8e9d6 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 — \"create a weekly Monday 9am competitor watch with a CFO approval gate\" — 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**Where it works:** every page inside the app shell. Form-filling is wired into the workflow builder (`Jobs → New`), the Add-person dialog, and the Company profile; other pages get the explain tier, with form support arriving screen by screen.\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.",
+ "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 (**Jobs → + New workflow**), 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 **Jobs → + New workflow**, 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.",
"mermaid": null,
- "generated_at": "2026-06-11T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/audit.json b/packages/core/openexecutive/guide/prebuilt/audit.json
index 57e6da38..ca208863 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, actor, 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*Note: the log is immutable — it's the trail for understanding (and trusting) what the Executive did.*",
+ "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 → 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.*",
"mermaid": null,
- "generated_at": "2026-06-06T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/chat.json b/packages/core/openexecutive/guide/prebuilt/chat.json
index 48078ee2..17ff03ce 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:** The home surface where you talk to the Executive in plain language. It opens on a *briefing* — a quick read of what's happened across the company — 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- Toggle **Committee** on a question that matters: a slower pass where reviewers challenge the draft answer before you see it.\n- Continue any briefing item straight into a chat thread, with the context already filled in.\n- Open **Agent activity** in the top bar to watch what's happening behind a reply — which specialists were consulted and which tools ran.\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:** The home surface where you talk to the Executive in plain language. It opens on a *briefing* — a quick read of what's happened across the company — 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- Toggle **Committee** on a question that matters: a slower pass where reviewers challenge the draft answer before you see it.\n- Continue any briefing item straight into a chat thread, with the context already filled in.\n- Open **Agent activity** in the top bar to watch what's happening behind a reply — which specialists were consulted and which tools ran.\n\n**How to use:**\n\n1. Click **New chat** in the sidebar. (Click **Briefing** any time to get back to the briefing.)\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 paperclip next to the message box 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, upload it to the Knowledge Base.\n4. For a decision that matters, click the **Committee** pill next to Send *before* sending. 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 👍 / 👎, and find old conversations under **Recent** in the sidebar (it has a search box).\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.*",
"mermaid": null,
- "generated_at": "2026-06-11T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/clients.json b/packages/core/openexecutive/guide/prebuilt/clients.json
index 28cd38b6..ca123bdd 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, hours per week, and renewal date — visible across all clients.\n- Get renewal reminders even for clients that are parked.\n\n*Note: switching clients swaps the whole working state, so nothing leaks between engagements. Single-company users can ignore this screen entirely.*",
+ "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 → Client Companies**.\n2. Add a client, one of three ways:\n - **New client** → enter a name → **From current company** (captures what's live now) → **Create**.\n - **New client** → **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. Click **Engagement details** 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.*",
"mermaid": null,
- "generated_at": "2026-06-11T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/company_profile.json b/packages/core/openexecutive/guide/prebuilt/company_profile.json
index d68ba019..5b04bb23 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*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.\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. Click **Set up company** in the sidebar (or **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. 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 profile**, 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 →** takes you back through the conversation.\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.*",
"mermaid": null,
- "generated_at": "2026-06-06T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/council.json b/packages/core/openexecutive/guide/prebuilt/council.json
index 2ff609d8..44f294cb 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 override its 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*Note: changes take effect on the next call — no restart needed. This is a power-user surface under Settings.*",
+ "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 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 → Agent Council** and pick an agent from the list. An amber dot means it's already been customized.\n2. Change what you need:\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 - **System prompt** — its full instructions. **Restore default prompt in editor** brings the original back.\n - **Research focus** — specialists only.\n3. Try it before saving: in **Test this draft**, type a question and click **Run test**. It uses your unsaved settings and changes nothing.\n4. Click **Save**. The change applies on the next call.\n5. To undo, click **Reset to default**, or open **Version history** and click **Restore** on an earlier version.\n\n*Change the Executive's voice:* select the Executive and scroll to **Voice Persona**. Choose an **Active persona** and click the main **Save**. To write your own, click **+ New**, give it a display name and a persona body, and 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.*",
"mermaid": null,
- "generated_at": "2026-06-06T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/departments.json b/packages/core/openexecutive/guide/prebuilt/departments.json
index 738fc1e9..bf4c2ef3 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 broadcast channels (Slack, Discord, Telegram).\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 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 **Departments** 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**:\n - **Department head** — the person who owns it.\n - **Authority level** — **Acts on its own**, **Proposes, you approve**, or **Escalates to a human**.\n - **Recurring check-in** — when the department checks in. New departments check in `daily@09:00`; change it to e.g. `daily@14:00` or `weekly@mon@09:00` (times are UTC).\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 has **Edit** and **Delete**.\n4. Keep goals current by just telling the Executive what happened — it updates the matching goal and records why.\n\n**Examples from chat:** *\"We closed 40% of the Q3 ARR target.\"* · *\"We lost the Acme deal.\"* · *\"Make Sarah the head of Marketing.\"*\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-06-06T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/integrations.json b/packages/core/openexecutive/guide/prebuilt/integrations.json
index c99bc172..e84f530a 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- **MCP:** expose the Executive's specialist council and company context to external AI tools.\n\n*Note: every channel uses the same approval flow and is recorded in the Audit Log. 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 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- **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.\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\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.*",
"mermaid": null,
- "generated_at": "2026-06-11T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/jobs.json b/packages/core/openexecutive/guide/prebuilt/jobs.json
index 47f8fb1e..2f232e35 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": "Jobs (Workflows)",
- "markdown": "**What it is:** Structured, multi-step workflows that produce a *deliverable* — a board deck, a go-to-market plan, a performance review — rather than just a chat reply.\n\n**What it does:**\n\n- Browse the workflow catalog, grouped by area, with step counts and rough run time.\n- Start a run and watch it stream its progress step by step.\n- See your runs split into **Active**, **Done**, and **Error**, and search them by name.\n- Build your own **custom workflow**: name it, define its inputs, and chain specialist, synthesis, and approval-gate steps.\n- Put a workflow on a **schedule** (e.g. every Monday at 9:00) so it runs without being asked.\n- Each finished run produces an artifact you can read and keep.\n\n*Note: outputs land in Artifacts; a workflow that needs your sign-off mid-run will pause and ask.*",
+ "markdown": "**What it is:** Structured, multi-step workflows that produce a *deliverable* — a board deck, a go-to-market plan, a performance review — rather than just a chat reply.\n\n**What it does:**\n\n- Browse the workflow catalog, grouped by area, with step counts and rough run time.\n- Start a run and watch it stream its progress step by step.\n- See your runs split into **Active**, **Awaiting sign-off**, **Done**, and **Error**, and search them by name.\n- Build your own **custom workflow**: name it, define its inputs, and chain specialist, approval-gate, and synthesis steps.\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\n**How to use:**\n\n*Run a workflow*\n\n1. Open **Jobs** and click a workflow in the **Catalog**.\n2. Fill in the fields (required ones have a red \\*). **Insert example** or **Load sample run** fills in realistic values if you just want to try it.\n3. Click **Continue**, then **Run job**. 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. Click **+ New workflow**.\n2. **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.\n3. **Input fields:** click **+ Add field** for anything the person running it must supply. Use a field in a step's goal as `{field_name}`.\n4. **Steps:** add **+ Specialist** steps (pick a specialist, write its goal) 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.\n5. **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.\n6. Click **Create workflow**. It appears under **Custom** in the Catalog, with **Edit** and **Delete**.\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*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\". There's no approve button in the web app. \"No\" or \"not now\" ends the run.\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 Artifacts. Ask OE can also fill in the **+ New workflow** form for you.*",
"mermaid": null,
- "generated_at": "2026-06-11T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/knowledge.json b/packages/core/openexecutive/guide/prebuilt/knowledge.json
index 79b85edd..67ce4c6b 100644
--- a/packages/core/openexecutive/guide/prebuilt/knowledge.json
+++ b/packages/core/openexecutive/guide/prebuilt/knowledge.json
@@ -1,7 +1,7 @@
{
"section_id": "knowledge",
"title": "Knowledge Base",
- "markdown": "**What it is:** Your document store. Upload company knowledge — handbooks, past decks, blog posts, policies — and the Executive searches it when answering.\n\n**What it does:**\n\n- Upload documents (Markdown, PDF, Word, plain text), organized by domain like product or finance.\n- Have each document automatically chunked and indexed for fast retrieval.\n- Let specialists pull the most relevant passages into their reasoning.\n- Test retrieval in **Query mode** — type a question and see exactly which passages the Executive would pull.\n- Edit or remove documents without disrupting live queries.\n\n*Note: there's also a read-only built-in knowledge base (curated business know-how) that ships with the app.*",
+ "markdown": "**What it is:** Your document store. Upload company knowledge — handbooks, past decks, blog posts, policies — and the Executive searches it when answering.\n\n**What it does:**\n\n- Upload documents (PDF, Word, Markdown, plain text), organized by domain like product or finance.\n- Have each document automatically chunked and indexed for fast retrieval.\n- Let specialists pull the most relevant passages into their reasoning.\n- Test retrieval in **Query mode** — type a question and see exactly which passages the Executive would pull.\n- Add your own playbooks and lessons learned alongside the built-in ones.\n- Remove documents without disrupting live queries.\n\n**How to use:**\n\n*Upload a document*\n\n1. Open **Knowledge base** and click **Company** in the left-hand tree.\n2. Pick a domain — general, board, finance, hr, legal, marketing, operations, product, or strategy. The domain decides which specialists see it.\n3. Drag a file onto the drop area or click **Browse file** (PDF, DOCX, MD or TXT, up to 50 MB).\n4. Once *Indexing…* finishes, the document is searchable. Use **View** to check it or **Delete** to remove it. Uploaded documents can't be edited here — to replace one, **Delete** it first, then upload the new version.\n\n*Check what the Executive will find*\n\n1. Click **Query mode**, type a question, and click **Run**.\n2. Optionally narrow by **Specialist**, by source (**Include**), or by **Domains**. The results show which passages would be pulled and which specialists would see them — a lower distance means a closer match.\n\n*Add your own playbook*\n\n1. Expand **Built-in**, find the domain, and click **+** next to **Playbooks** (or **Failures** for a lessons-learned case).\n2. Enter a filename and the Markdown content, then click **Create file**.\n3. New playbooks wait in **Review** and aren't used until you approve them. Open any playbook and use **Edit** / **Preview** to change it later.\n\n**Example:** upload `pricing-policy-2026.pdf` under **finance**, then in Query mode ask *\"what discount can sales offer without approval?\"* to confirm the right passage comes back.\n\n*Note: there's also a read-only built-in knowledge base (curated business know-how) that ships with the app. Files attached in chat are not added to the Knowledge Base.*",
"mermaid": null,
- "generated_at": "2026-06-11T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/people.json b/packages/core/openexecutive/guide/prebuilt/people.json
index 27137554..ca9749d1 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:** Your org roster — the humans the Executive coordinates with, each with a response SLA, preferred channel, and the approval authority they hold.\n\n**What it does:**\n\n- Add people 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 / the founder) and set availability or on-leave dates.\n\n*Note: authority scopes are how the Executive figures out who to ask for any given approval.*",
+ "markdown": "**What it is:** Your org roster — the humans the Executive coordinates with, each with a response SLA, preferred channel, and the approval authority they hold.\n\n**What it does:**\n\n- Add people 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 / the founder) and set availability or on-leave dates.\n\n**How to use:**\n\n1. Open **People** and click **+ Add person**.\n2. Enter **Full name** (the only required field) and **Role**. If this is you, tick **This is me — Primary** — this can only be set when adding someone.\n3. 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. 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 founder |\n\n5. Click **Add person**. Later, open the person and click **Edit** to set **On leave until**, add **Availability windows** (days, hours, timezone), or change their scopes; **Archive person** retires them from the roster.\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 open **+ Add person**, press **Ctrl/Cmd + .**, and describe the person — Ask OE fills in the dialog for you to check and save.\n\n*Note: authority scopes are how the Executive figures out who to ask for any given approval.*",
"mermaid": null,
- "generated_at": "2026-06-06T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/pulse.json b/packages/core/openexecutive/guide/prebuilt/pulse.json
index 5f197a63..aa33a0fa 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** through planned → in-progress → done.\n- Review **advice** collected from specialists, searchable by topic.\n- See the **heartbeat** — the recurring cadence of daily briefs, department check-ins, system scans, and pending scheduled follow-ups.\n- Edit, update, or delete any item to keep the Executive's memory accurate.\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, searchable by topic.\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. **Heartbeat** shows the rhythm the Executive runs on; **Memory** has tabs for **decisions**, **initiatives** and **advice** (side by side on a wide screen, stacked on a narrow one).\n3. Hover over any row and click **Edit** to correct it — fix a decision's rationale or outcome, change its domain or tags, or move an initiative to *completed* — then **Save**.\n4. Click **Delete** to remove something that's simply wrong. This can't be undone.\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*Note: this memory is searchable across the system, so what's captured here informs future answers.*",
"mermaid": null,
- "generated_at": "2026-06-11T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/review.json b/packages/core/openexecutive/guide/prebuilt/review.json
index a0f088bf..c98f34a6 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 add a correction without hard-deleting the original.\n- Bulk-approve a whole domain at once when you trust the source.\n\n*Note: approved items feed retrieval; rejected ones are kept out. The Review entry in the nav shows a badge for items still waiting.*",
+ "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. Click **Review** in the sidebar — the badge shows how many items are waiting.\n2. On the **Review queue** tab, click **View** on an item to read it and see where it came from.\n3. Decide:\n - **Approve** — the Executive can use it.\n - **Flag** — mark it *needs revision* as a reminder to follow up. A flagged item stays in use until you reject it.\n - **Reject** — keep it out; you can add a note saying why.\n - Use the priority dropdown (↓ Low / Normal / ↑ High) to order your queue.\n4. To fix a detail instead of rejecting the whole item, open **View**, type in *Add a correction or clarification…* and click **Add**. Active corrections are given to the Executive alongside the item; toggle one to **Inactive** to retire it.\n5. Trust a source? Click **Approve all pending**, or on the **All items** tab use **Approve all pending in *domain***.\n\n**Where items come from:** playbook and failure-case files you add or edit in the Knowledge Base, and any domain you choose to **Curate** — curating holds that domain's built-in knowledge back from the Executive until you approve it (**Stop curating** releases it). Company documents you upload go straight to the Knowledge Base and don't appear here.\n\n**Example:** you add a *discount-policy* playbook under finance. It shows up here as pending; open it, add the correction *\"Discounts over 15% need CFO sign-off\"*, then **Approve** — the Executive now uses the playbook with your correction attached.\n\n*Note: approved and flagged items feed retrieval; pending and rejected ones are kept out. Editing an approved playbook flags it for re-review without taking it out of use.*",
"mermaid": null,
- "generated_at": "2026-06-06T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/settings.json b/packages/core/openexecutive/guide/prebuilt/settings.json
index f6b265a5..0ad5d7fa 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 hub for power-user and admin tools that were pulled out of the day-to-day nav to keep it focused.\n\n**What it does:**\n\n- Links to the Agent Council, Audit Log, Token Usage, Architecture reference, Company Simulator, Client Companies, and this User Guide.\n- Acts as a directory — each tile opens a dedicated screen.\n- Keeps advanced configuration one click away without cluttering the main workspace.\n\n*Tip: if you're looking for a feature that isn't in the sidebar, it's probably here. This guide is also pinned next to Settings at the bottom of the nav.*",
+ "markdown": "**What it is:** The hub for power-user and admin tools that were pulled out of the day-to-day nav to keep it focused.\n\n**What it does:**\n\n- Links to the Agent Council, Audit Log, Token Usage, this User Guide, the Architecture reference, Company Simulator, and Client Companies.\n- Acts as a directory — each tile opens a dedicated screen.\n- Keeps advanced configuration one click away without cluttering the main workspace.\n\n**How to use:**\n\n1. Click **Settings** at the bottom of the sidebar.\n2. Click the tile for what you want to do:\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*Tip: if you're looking for a feature that isn't in the sidebar, it's probably here. This guide is also pinned next to Settings at the bottom of the nav.*",
"mermaid": null,
- "generated_at": "2026-06-11T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/simulator.json b/packages/core/openexecutive/guide/prebuilt/simulator.json
index bda06652..a20160cf 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 first.\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*Note: loading a fixture replaces your live context — but your original state is saved and restorable.*",
+ "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 → 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.*",
"mermaid": null,
- "generated_at": "2026-06-06T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/skills.json b/packages/core/openexecutive/guide/prebuilt/skills.json
index 445821e4..32e7b96c 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": "Skills",
- "markdown": "**What it is:** Reusable how-to procedures the Executive can pull up on demand — checklists, playbooks, and templates for recurring tasks.\n\n**What it does:**\n\n- Browse the skills catalog with each skill's purpose and when to use it.\n- Search by keyword to find the right procedure.\n- Create your own skills with a name, category, when-to-use, and a Markdown body.\n- Update or delete your custom skills (built-in ones are protected).\n\n*Note: skills are indexed so the Executive can discover and apply the right one mid-task.*",
+ "markdown": "**What it is:** Reusable how-to procedures the Executive can pull up on demand — checklists, playbooks, and templates for recurring tasks. Some ship with the app (**Built-in**); the rest are ones you and the Executive save (**Yours**).\n\n**What it does:**\n\n- Browse the skills catalog, grouped by category, with each skill's purpose and when to use it.\n- Search by meaning to find the right procedure.\n- Let the Executive find and follow a matching skill mid-task — when a request looks like work a skill covers, it loads the procedure before answering.\n- Save new skills by asking the Executive. It also saves one on its own after doing repeatable work, and tells you when it does.\n- Update or delete your own skills; built-in ones are protected.\n\n**How to use:**\n\n*Browse and search*\n\n1. Open **Knowledge → Skills** in the sidebar.\n2. Describe what you need in the search box — e.g. *\"cash forecast for next quarter\"* — and click **Search**. Matching looks at each skill's name, description and *when to use*.\n3. Click a skill to read its full procedure.\n\n*Create a custom skill*\n\nThere's no form on this page — you create a skill by asking the Executive, in chat or in the **Ask OE** panel.\n\n1. Tell it what the skill is for, when it should be used, and the steps or template it should follow. Paste an existing checklist if you have one. Or, right after the Executive has done a piece of work you liked, just say *\"save that as a skill\"*.\n2. The Executive fills in the skill's parts:\n - a **name** — letters, numbers, `-` and `_` only, and unique;\n - a **category** — strategy, finance, hr, legal, operations, marketing, product, board, or general;\n - a one-line **description** and a **when to use** line;\n - the procedure itself, written in Markdown.\n3. It's saved straight away — you'll see a *Saved skill: …* chip in the reply — and it appears under **Yours** on this page (refresh if the page is already open).\n4. From then on, whenever a request matches the skill's *when to use*, the Executive loads it and follows it.\n\n*Change or remove a skill*\n\n- **Update:** *\"Update my weekly-pipeline-review skill to add a churn section.\"* An update replaces the whole skill. To rename one, ask for a new skill and delete the old one.\n- **Delete:** select the skill and click **Delete**, or ask in chat. Only skills under **Yours** can be changed or deleted.\n\n**Example:** type this in chat —\n\n> Create a skill called weekly-pipeline-review in the finance category. Use it whenever I ask for a pipeline review or \"how's the pipeline looking\". Gather the pipeline snapshot and this quarter's target first, and ask me if either is missing. Then produce a 3-bullet headline, a coverage-vs-target table, the deals that slipped or are at risk, and the decisions you need from me.\n\nThe Executive saves it as a Markdown skill like this:\n\n```markdown\n---\nname: weekly-pipeline-review\ndescription: One-page weekly pipeline review — coverage, slippage, at-risk deals, decisions\nwhen_to_use: User asks for a pipeline review, weekly sales review, or \"how's the pipeline looking\"\ncategory: finance\n---\n\n# Weekly Pipeline Review\n\n## Inputs to gather first\n1. **Pipeline snapshot** — stage, amount, and close date per deal\n2. **Target for the quarter**\nIf either is missing, stop and ask.\n\n## Output\n1. **Headline** — 3 bullets\n2. **Coverage vs. target** — this week / last week / target\n3. **Slipped or at-risk deals**\n4. **Decisions needed**\n```\n\nNext time you ask *\"how's the pipeline looking?\"*, the Executive finds this skill and follows it.\n\n*Tip: write **when to use** the way you'd actually phrase the request — that's what the Executive matches on. Resetting the Company Simulator deletes your custom skills; built-in ones are never affected.*",
"mermaid": null,
- "generated_at": "2026-06-06T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/today.json b/packages/core/openexecutive/guide/prebuilt/today.json
index c873a436..d4d9ef97 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.\n\n**What it does:**\n\n- Splits items into **Needs you** (waiting on your call) and **Across the team** (everything else in motion).\n- Shows each department's goal health — on-track, at-risk, or off-track — with the at-risk goals called out.\n- Lists people with open items, their reply counts, SLA status, and whether they're on leave.\n- Surfaces proposals and alerts you can click to open a chat thread with full context.\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 the **Briefing**, the screen the app opens on.\n\n**What it does:**\n\n- Splits items into **Needs you** (waiting on your call) and **Across the team** (everything else in motion).\n- Shows each department's goal health — on-track, at-risk, or off-track — with the at-risk goals called out.\n- Lists people with open items, their reply counts, SLA status, and whether they're on leave.\n- Surfaces proposals and alerts you can click to open a chat thread with full context.\n\n**How to use:**\n\n1. Click **Briefing** in the sidebar (or the Open Executive logo).\n2. Work the **Needs you** lane from the top, starting with the **Start here** card. Each card offers:\n - **✓ Approve** — accept the recommendation; a chat opens so the Executive can carry it out.\n - **✎ Edit & approve** — reword the action first, then **✓ Send approval**; your text is used exactly as written.\n - **💬 Discuss** (or click the card) — open a chat with the context already filled in.\n - **✕ Dismiss** — drop it and stay on the briefing.\n - **↪ Nudge *name*** — shown when the best move is chasing someone for a reply.\n3. Some cards are simpler: an artifact card has one **✓ Mark reviewed** button, and a calendar-booking card books (or declines) the meeting directly when you click Approve or Dismiss.\n4. Keep the lane tidy: **✕ Dismiss N older than 7 days** clears stale items, and **⟳ Re-check relevance** asks the Executive to review every open item now.\n5. Click a department card to ask for that department's status in chat.\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*Note: proposals are routed to the right person automatically based on who has authority over them.*",
"mermaid": null,
- "generated_at": "2026-06-06T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/token_usage.json b/packages/core/openexecutive/guide/prebuilt/token_usage.json
index 4e4bbd24..6f3991f1 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 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.\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:** 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 → 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.*",
"mermaid": null,
- "generated_at": "2026-06-06T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/prebuilt/watchlist.json b/packages/core/openexecutive/guide/prebuilt/watchlist.json
index 5d8d3320..e921f549 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, regulatory filings, web-search queries, and changes to specific web pages.\n\n**What it does:**\n\n- Add a monitor, choose its type, and set a cadence, 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- Edit the whole list from chat as well as here.\n\n*Note: stock/filing/page monitors are cheap; web-search monitors cost per check, so prefer slower cadences for those.*",
+ "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 **Watch list** in the sidebar and click **+ Add monitor**.\n2. Fill in:\n - **Slug** — a short id in lowercase-with-dashes, e.g. `acme-pricing-page`.\n - **Signal type** and **Target** — see the table below.\n - **Trigger (JSON, optional)** — narrows what counts as a hit; leave blank for the defaults.\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**. Untick **enabled** on a card to pause it; click **inspect →** to switch mode, edit notes, or **Delete monitor**.\n4. Check **Suggested by the Executive** now and then — **Approve** turns a suggestion on, **Decline…** removes it. 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.*",
"mermaid": null,
- "generated_at": "2026-06-11T00:00:00+00:00"
+ "generated_at": "2026-09-23T00:00:00+00:00"
}
diff --git a/packages/core/openexecutive/guide/sections.py b/packages/core/openexecutive/guide/sections.py
index 9f35b329..ccb86366 100644
--- a/packages/core/openexecutive/guide/sections.py
+++ b/packages/core/openexecutive/guide/sections.py
@@ -1,10 +1,11 @@
"""The fixed registry of user-guide sections.
The ``/guide`` page is a plain-language overview of every user-facing
-feature — "what it is, what it does" — kept separate from the technical
-``/architecture`` reference. Like the architecture page, each section is
-rendered from a static, version-controlled JSON file under
-``guide/prebuilt/<id>.json``; nothing on the serving path calls an LLM.
+feature — "what it is, what it does, how to use it" — kept separate from
+the technical ``/architecture`` reference. Like the architecture page,
+each section is rendered from a static, version-controlled JSON file
+under ``guide/prebuilt/<id>.json``; nothing on the serving path calls an
+LLM.
The section IDs must match the ``GUIDE_SECTIONS`` const in
``packages/ui/src/app/guide/page.tsx`` so deep links keep working and the
diff --git a/packages/core/tests/unit/test_guide_prebuilt.py b/packages/core/tests/unit/test_guide_prebuilt.py
index a555d5f9..053fbec3 100644
--- a/packages/core/tests/unit/test_guide_prebuilt.py
+++ b/packages/core/tests/unit/test_guide_prebuilt.py
@@ -45,6 +45,16 @@ def test_guide_is_diagram_free() -> None:
assert data["mermaid"] is None, f"{spec.id} should have no diagram"
+def test_every_section_has_how_to_use() -> None:
+ # Each section explains how to use the feature, not just what it is.
+ for spec in GUIDE_SECTIONS:
+ data = prebuilt.get_prebuilt(spec.id)
+ assert data is not None
+ assert (
+ "**How to use:**" in data["markdown"]
+ ), f"{spec.id}: add a **How to use:** walkthrough"
+
+
def test_get_prebuilt_unknown_returns_none() -> None:
assert prebuilt.get_prebuilt("does-not-exist") is None