AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
Merge origin/main into claude/81md-review-backlog-te066i
Claude31398797ada7
diff --cc packages/core/openexecutive/architecture/prebuilt/clients.jsonindex 8aed28e1,c360733b..1f3b48b9--- a/packages/core/openexecutive/architecture/prebuilt/clients.json+++ b/packages/core/openexecutive/architecture/prebuilt/clients.json@@@ -1,7 -1,7 +1,7 @@@{"section_id": "clients","title": "Client Companies (Slots)",- "markdown": "The **clients** module (`openexecutive.clients`) adds **multi-client mode** for fractional executives: one Open Executive instance serving several client companies, exactly **one active at a time**. It generalizes the fixture switcher's swap machinery into named, durable *slots* — save files of the full company context. Single-company installs are untouched: nothing changes until a slot is explicitly created, and the `/clients` page shows only an intro until then.\n\n## What a slot contains\n\nEach slot lives at `company/_client_slots/<slug>/` (gitignored — client data is never committable):\n\n| Artifact | What it carries |\n| --- | --- |\n| `state.db` | A transactionally-consistent copy of the shared SQLite DB — chat history, scheduled actions, onboarding plans, talent pipeline, departments, people, watchlist, audit/run history |\n| `profile.yaml` | The company profile |\n| `docs/`, `skills/` | Company documents (all file types) and company-authored skills |\n| `mcp_servers.json` | Per-client external MCP tools (e.g. one client's Crayon or Google Workspace credentials) |\n| `meta.json` | Display name + created/saved timestamps |\n\n## Switching\n\n`POST /clients/{slug}/activate` saves the current client back to its slot (`VACUUM INTO` for the DB copy), then restores the target: the DB through sqlite3's online **backup API** (the live file's inode never changes, so handles held elsewhere stay valid), the company artifacts by replacement, and the ChromaDB `company_docs` collection + company skills re-indexed from the restored directories. Idempotent schema initializers re-run after every restore, so a slot saved before a schema-adding deploy gains the new tables. Activating a **blank** slot (created with `source: \"blank\"`, no `state.db` yet) factory-wipes the per-client tables and re-seeds defaults — departments, onboarding templates, principal briefs, cadences — so the new client's Today page works without a restart. That wipe covers the **derived caches** — `briefing_narrative` and `person_insights` — as well as authored state. They are regenerable, but `/today` serves them from cache and only regenerates in a background task, so a surviving row renders the *outgoing* client's briefing text under the incoming one, and `person_insights` reaches Discord, the MCP server, and the morning/end-of-day digests as well as the UI. Switching into a slot that already has `state.db` was never exposed: the sqlite backup API truncates the destination to an exact copy of the source.\n\nThe first activation from single-company mode auto-snapshots the original company to `_user_backup` (the same restore point the fixture switcher uses); `POST /fixtures/unload` brings it back and exits client mode.\n\n## Invariants\n\n- At most one slot is active — recorded in an allowlist-validated `.active_client` sentinel.\n- **Only the active client is live**: its scheduled actions fire, its docs are indexed; parked clients sleep. The single-instance scheduler constraint is unchanged.\n- Slot operations share the fixture switcher's destructive-op lock, so fixture loads, snapshots, resets, and slot switches serialize against each other. The Notion sync tick coordinates with the same lock without queueing on it: it skips its tick while the lock is held, fetches from Notion unlocked, and takes the lock only for its short local write phase — aborting without writing if the active client changed mid-fetch (in-process only; a CLI run is a separate process the lock cannot see). A fixture and a client are never active simultaneously (slot ops refuse with 409 while a fixture is loaded); loading a fixture saves an active client back to its slot first, so demos can never destroy client work. Factory reset clears the active-client sentinel but preserves slot directories.\n- `generated_fixtures` is operator-level (the demo library) and is preserved verbatim across switches.\n- **Every path that swaps the live company wipes the derived caches**, from one shared list (`cli.fixture_loader.PER_CLIENT_CACHE_TABLES`): blank/seed slot activation, factory reset, and fixture load *and* unload. Three hand-maintained copies of that list is what let the leak survive in two paths after being fixed in one — a new per-company cache table goes in the constant, once. On the fixture path the wipe runs in `_apply_state_from_source`, unconditionally: a fixture needs only `profile.yaml`, so gating it on `memory.json` would skip exactly the loads that still swap the company.\n- Do **not** treat `person_insights`' `input_hash` as a guard against this. It covers per-person signals (role, principal flag, status, counters, availability, authority and department scope, bucketed timestamps, the UTC day) but carries no person, name or company identity, and the cache key is `person_id` — a reused autoincrement PK. An outgoing principal and a freshly seeded incoming one hash identically whenever those signals coincide, which is ordinary steady state for a seeded slot.\n- Each client gets a stable Honcho workspace (`openexec-client-<slug>`) so peer memory survives parking; fixture teardown paths recognise the prefix and never delete these.\n\n## Caveats\n\n`mcp_servers.json` is read by the MCP gateway at process startup — a switch that changes it takes effect on the next API restart (the activate response carries `mcp_config_changed`). Scheduled actions whose `run_at` passed while a client was parked are claimed on the first tick after activation; authority gates still apply, but expect the returning client's overdue follow-ups to fire shortly after a switch.\n\nTwo residuals. `/today`'s background regeneration tasks capture the outgoing company's data and can write it back into the live DB for up to roughly 25 seconds after the wipe — on **every** swapping path, fixture load/unload and slot activation alike, since those writers neither take the destructive-op lock nor check company identity. For `person_insights` it does not self-heal: the late write stores the outgoing `input_hash`, which the incoming person's signals often match, so the stale note survives until the UTC-day bucket rolls. Closing this needs company identity in the cache hash or those writers taking the lock. Second, and blank-slot only, `dynamic_workflows` / `eval_scenarios` are client-scoped but **not** wiped: they are authored rather than derived, and the first-activation snapshot captures only profile, docs, `memory.json`, people and departments — so wiping them before extending that snapshot would destroy the operator's own work. Until then the outgoing client's workflow definitions stay registered and active on the blank path, runnable against the incoming client's data and readable via `/workflows`.\n\n## Setting up a new engagement with AI\n\n`POST /clients/generate` turns **real intake material** into a reviewable draft of the client: profile, org, roster, starter docs, and known history. Intake material is pasted text (kickoff-call notes, a brief, website copy) and/or **file attachments** (PDF, Word, Excel, CSV, Markdown/text; the request is multipart). Each attachment's extracted text both feeds the draft and is appended to the bundle as a `source_<name>.md` company doc, so it lands in the seed slot and is indexed into the `company_docs` collection on activation alongside the AI-written docs (extracted text, not the original binary; legacy `.xls` is unsupported). It runs the Council-configurable `engagement_intake` agent — the grounded sibling of the demo fixture generator (same bundle schema, validation, and repair-retry; the Company Simulator's fictional path is unchanged). Grounding rules: extract, don't invent — unstated numbers stay null, only people named in the material appear, docs are engagement working documents (intake brief, current-state summary, stakeholder map, open questions), and **no contact handles are ever imported**, even if present in the notes.\n\nSaving the reviewed draft (`POST /clients` with `source: \"generated\"`) writes a **seed slot**: profile and docs as normal slot artifacts, plus `people.yaml` / `departments.yaml` / `memory.json` in the same shapes curated fixtures use. Nothing touches live state until activation, when the blank-restore path applies the seed files with the fixture loader's seeders and skips the default-department reseed (the draft supplied the org). After the first save-back writes `state.db`, the seed files remain as the engagement's birth record but are no longer consulted; `meta.json` records `origin: \"generated\"` and the intake notes.\n\n## The practice layer: engagement metadata + cockpit\n\nEach slot's `meta.json` carries optional **engagement metadata** — your role for the client, engagement status (active/paused/winding down/completed), start and renewal dates, retainer (display only), and primary contact — editable via `PATCH /clients/{slug}` for active *and* parked slots, because meta.json lives outside the swapped client state. Renewal awareness deliberately lives here and never as scheduled actions (those swap with the client and would vanish when parked).\n\nThe **practice cockpit** (`GET /clients/cockpit`) gives cross-client awareness without touching the one-active-client ceiling: the active client is counted from the live DB, and each parked client's `state.db` is opened **read-only, in place** — no activation, no lock. Cards roll up pending/overdue follow-ups, awaiting replies, unread alerts, onboarding tasks due within a week, and renewal countdowns. Parked data is as fresh as the slot's last save point and every card says so; one broken slot degrades to a single error-flagged card, never a failed board. Cockpit cards link to the **engagement value report** — a workflow that turns the client's own record (decisions, deliverables, follow-through) into a renewal-ready artifact, reading parked clients without activating them. With two or more clients, `/today` gains an \"Across your clients\" section for the parked ones — single-company installs see none of this, anywhere.\n\n## Overnight rotation (cockpit v2)\n\nWith `CLIENT_ROTATION_ENABLED=true` (off by default), a nightly scheduled job (`CLIENT_ROTATION_TIME`, default 03:30 UTC) activates each parked client in turn, generates its morning brief as an artifact in that client's own record, runs its monitor scan, saves it back, and **always restores the original active client** — then delivers one cross-client digest via the original client's principal channel. Two safety rails matter: the scheduler **pauses claiming** while the rotation's `.rotation_in_progress` marker exists (so a just-activated client's overdue outbound backlog can never fire at 3am — rotation does brief + monitors only, never outbound), and the rotation row is re-seeded after every slot activation because scheduled rows swap with the client. Completed engagements and never-activated slots sleep through rotation; per-client failures are skipped and reported in the digest.\n\n## API + UI\n\n`GET /clients` (list + active + fixture status), `POST /clients` (`source: \"current\"` captures the live company and activates; `\"blank\"` creates an empty client to onboard fresh; `\"generated\"` saves a reviewed intake draft as a seed slot), `POST /clients/generate` (grounded AI draft from intake notes and/or file attachments; multipart), `PATCH /clients/{slug}` (engagement metadata), `GET /clients/cockpit` (practice board), `POST /clients/save` (checkpoint without switching), `POST /clients/{slug}/activate`, `DELETE /clients/{slug}` (refuses the active slot). The `/clients` page lives under Settings → advanced tools.\n\n**Knowledge review state per slot.** `_ensure_schemas` re-runs the idempotent schema inits after a restore, including `ReviewStore.initialize_db` followed by `sync_builtin_registrations`. Without that second call a freshly activated slot carried an empty `review_items` table until the next process restart; now it gets the shipped docs as trusted defaults straight away, matching a normal boot.",- "markdown": "The **clients** module (`openexecutive.clients`) adds **multi-client mode** for fractional executives: one Open Executive instance serving several client companies, exactly **one active at a time**. It generalizes the fixture switcher's swap machinery into named, durable *slots* — save files of the full company context. Single-company installs are untouched: nothing changes until a slot is explicitly created, and the `/clients` page shows only an intro until then.\n\n## What a slot contains\n\nEach slot lives at `company/_client_slots/<slug>/` (gitignored — client data is never committable):\n\n| Artifact | What it carries |\n| --- | --- |\n| `state.db` | A transactionally-consistent copy of the shared SQLite DB — chat history, scheduled actions, onboarding plans, talent pipeline, departments, people, watchlist, audit/run history |\n| `profile.yaml` | The company profile |\n| `docs/`, `skills/` | Company documents (all file types) and company-authored skills |\n| `mcp_servers.json` | Per-client external MCP tools (e.g. one client's Crayon or Google Workspace credentials) |\n| `meta.json` | Display name + created/saved timestamps |\n\n## Switching\n\n`POST /clients/{slug}/activate` saves the current client back to its slot (`VACUUM INTO` for the DB copy), then restores the target: the DB through sqlite3's online **backup API** (the live file's inode never changes, so handles held elsewhere stay valid), the company artifacts by replacement, and the ChromaDB `company_docs` collection + company skills re-indexed from the restored directories. The isolated per-company collections are wiped in the same pass — `recent_research`, `notion_wiki`, and `inbound_attachments` (attachments are dropped and recreated rather than re-indexed: they have no source directory to rebuild from, and a row surviving a slot switch would be one client's attachment visible to the next). Idempotent schema initializers re-run after every restore, so a slot saved before a schema-adding deploy gains the new tables. Activating a **blank** slot (created with `source: \"blank\"`, no `state.db` yet) factory-wipes the per-client tables and re-seeds defaults — departments, onboarding templates, principal briefs, cadences — so the new client's Today page works without a restart. That wipe covers the **derived caches** — `briefing_narrative` and `person_insights` — as well as authored state. They are regenerable, but `/today` serves them from cache and only regenerates in a background task, so a surviving row renders the *outgoing* client's briefing text under the incoming one, and `person_insights` reaches Discord, the MCP server, and the morning/end-of-day digests as well as the UI. Switching into a slot that already has `state.db` was never exposed: the sqlite backup API truncates the destination to an exact copy of the source.\n\nThe first activation from single-company mode auto-snapshots the original company to `_user_backup` (the same restore point the fixture switcher uses); `POST /fixtures/unload` brings it back and exits client mode.\n\n## Invariants\n\n- At most one slot is active — recorded in an allowlist-validated `.active_client` sentinel.\n- **Only the active client is live**: its scheduled actions fire, its docs are indexed; parked clients sleep. The single-instance scheduler constraint is unchanged.\n- Slot operations share the fixture switcher's destructive-op lock, so fixture loads, snapshots, resets, and slot switches serialize against each other. The Notion sync tick coordinates with the same lock without queueing on it: it skips its tick while the lock is held, fetches from Notion unlocked, and takes the lock only for its short local write phase — aborting without writing if the active client changed mid-fetch (in-process only; a CLI run is a separate process the lock cannot see). A fixture and a client are never active simultaneously (slot ops refuse with 409 while a fixture is loaded); loading a fixture saves an active client back to its slot first, so demos can never destroy client work. Factory reset clears the active-client sentinel but preserves slot directories.\n- `generated_fixtures` is operator-level (the demo library) and is preserved verbatim across switches.\n- **Every path that swaps the live company wipes the derived caches**, from one shared list (`cli.fixture_loader.PER_CLIENT_CACHE_TABLES`): blank/seed slot activation, factory reset, and fixture load *and* unload. Three hand-maintained copies of that list is what let the leak survive in two paths after being fixed in one — a new per-company cache table goes in the constant, once. On the fixture path the wipe runs in `_apply_state_from_source`, unconditionally: a fixture needs only `profile.yaml`, so gating it on `memory.json` would skip exactly the loads that still swap the company.\n- Do **not** treat `person_insights`' `input_hash` as a guard against this. It covers per-person signals (role, principal flag, status, counters, availability, authority and department scope, bucketed timestamps, the UTC day) but carries no person, name or company identity, and the cache key is `person_id` — a reused autoincrement PK. An outgoing principal and a freshly seeded incoming one hash identically whenever those signals coincide, which is ordinary steady state for a seeded slot.\n- Each client gets a stable Honcho workspace (`openexec-client-<slug>`) so peer memory survives parking; fixture teardown paths recognise the prefix and never delete these.\n\n## Caveats\n\n`mcp_servers.json` is read by the MCP gateway at process startup — a switch that changes it takes effect on the next API restart (the activate response carries `mcp_config_changed`). Scheduled actions whose `run_at` passed while a client was parked are claimed on the first tick after activation; authority gates still apply, but expect the returning client's overdue follow-ups to fire shortly after a switch.\n\nTwo residuals. `/today`'s background regeneration tasks capture the outgoing company's data and can write it back into the live DB for up to roughly 25 seconds after the wipe — on **every** swapping path, fixture load/unload and slot activation alike, since those writers neither take the destructive-op lock nor check company identity. For `person_insights` it does not self-heal: the late write stores the outgoing `input_hash`, which the incoming person's signals often match, so the stale note survives until the UTC-day bucket rolls. Closing this needs company identity in the cache hash or those writers taking the lock. Second, and blank-slot only, `dynamic_workflows` / `eval_scenarios` are client-scoped but **not** wiped: they are authored rather than derived, and the first-activation snapshot captures only profile, docs, `memory.json`, people and departments — so wiping them before extending that snapshot would destroy the operator's own work. Until then the outgoing client's workflow definitions stay registered and active on the blank path, runnable against the incoming client's data and readable via `/workflows`.\n\n## Setting up a new engagement with AI\n\n`POST /clients/generate` turns **real intake material** into a reviewable draft of the client: profile, org, roster, starter docs, and known history. Intake material is pasted text (kickoff-call notes, a brief, website copy) and/or **file attachments** (PDF, Word, Excel, CSV, Markdown/text; the request is multipart). Each attachment's extracted text both feeds the draft and is appended to the bundle as a `source_<name>.md` company doc, so it lands in the seed slot and is indexed into the `company_docs` collection on activation alongside the AI-written docs (extracted text, not the original binary; legacy `.xls` is unsupported). It runs the Council-configurable `engagement_intake` agent — the grounded sibling of the demo fixture generator (same bundle schema, validation, and repair-retry; the Company Simulator's fictional path is unchanged). Grounding rules: extract, don't invent — unstated numbers stay null, only people named in the material appear, docs are engagement working documents (intake brief, current-state summary, stakeholder map, open questions), and **no contact handles are ever imported**, even if present in the notes.\n\nSaving the reviewed draft (`POST /clients` with `source: \"generated\"`) writes a **seed slot**: profile and docs as normal slot artifacts, plus `people.yaml` / `departments.yaml` / `memory.json` in the same shapes curated fixtures use. Nothing touches live state until activation, when the blank-restore path applies the seed files with the fixture loader's seeders and skips the default-department reseed (the draft supplied the org). After the first save-back writes `state.db`, the seed files remain as the engagement's birth record but are no longer consulted; `meta.json` records `origin: \"generated\"` and the intake notes.\n\n## The practice layer: engagement metadata + cockpit\n\nEach slot's `meta.json` carries optional **engagement metadata** — your role for the client, engagement status (active/paused/winding down/completed), start and renewal dates, retainer (display only), and primary contact — editable via `PATCH /clients/{slug}` for active *and* parked slots, because meta.json lives outside the swapped client state. Renewal awareness deliberately lives here and never as scheduled actions (those swap with the client and would vanish when parked).\n\nThe **practice cockpit** (`GET /clients/cockpit`) gives cross-client awareness without touching the one-active-client ceiling: the active client is counted from the live DB, and each parked client's `state.db` is opened **read-only, in place** — no activation, no lock. Cards roll up pending/overdue follow-ups, awaiting replies, unread alerts, onboarding tasks due within a week, and renewal countdowns. Parked data is as fresh as the slot's last save point and every card says so; one broken slot degrades to a single error-flagged card, never a failed board. Cockpit cards link to the **engagement value report** — a workflow that turns the client's own record (decisions, deliverables, follow-through) into a renewal-ready artifact, reading parked clients without activating them. With two or more clients, `/today` gains an \"Across your clients\" section for the parked ones — single-company installs see none of this, anywhere.\n\n## Overnight rotation (cockpit v2)\n\nWith `CLIENT_ROTATION_ENABLED=true` (off by default), a nightly scheduled job (`CLIENT_ROTATION_TIME`, default 03:30 UTC) activates each parked client in turn, generates its morning brief as an artifact in that client's own record, runs its monitor scan, saves it back, and **always restores the original active client** — then delivers one cross-client digest via the original client's principal channel. Two safety rails matter: the scheduler **pauses claiming** while the rotation's `.rotation_in_progress` marker exists (so a just-activated client's overdue outbound backlog can never fire at 3am — rotation does brief + monitors only, never outbound), and the rotation row is re-seeded after every slot activation because scheduled rows swap with the client. Completed engagements and never-activated slots sleep through rotation; per-client failures are skipped and reported in the digest.\n\n## API + UI\n\n`GET /clients` (list + active + fixture status), `POST /clients` (`source: \"current\"` captures the live company and activates; `\"blank\"` creates an empty client to onboard fresh; `\"generated\"` saves a reviewed intake draft as a seed slot), `POST /clients/generate` (grounded AI draft from intake notes and/or file attachments; multipart), `PATCH /clients/{slug}` (engagement metadata), `GET /clients/cockpit` (practice board), `POST /clients/save` (checkpoint without switching), `POST /clients/{slug}/activate`, `DELETE /clients/{slug}` (refuses the active slot). The `/clients` page lives under Settings → advanced tools.",++ "markdown": "The **clients** module (`openexecutive.clients`) adds **multi-client mode** for fractional executives: one Open Executive instance serving several client companies, exactly **one active at a time**. It generalizes the fixture switcher's swap machinery into named, durable *slots* — save files of the full company context. Single-company installs are untouched: nothing changes until a slot is explicitly created, and the `/clients` page shows only an intro until then.\n\n## What a slot contains\n\nEach slot lives at `company/_client_slots/<slug>/` (gitignored — client data is never committable):\n\n| Artifact | What it carries |\n| --- | --- |\n| `state.db` | A transactionally-consistent copy of the shared SQLite DB — chat history, scheduled actions, onboarding plans, talent pipeline, departments, people, watchlist, audit/run history |\n| `profile.yaml` | The company profile |\n| `docs/`, `skills/` | Company documents (all file types) and company-authored skills |\n| `mcp_servers.json` | Per-client external MCP tools (e.g. one client's Crayon or Google Workspace credentials) |\n| `meta.json` | Display name + created/saved timestamps |\n\n## Switching\n\n`POST /clients/{slug}/activate` saves the current client back to its slot (`VACUUM INTO` for the DB copy), then restores the target: the DB through sqlite3's online **backup API** (the live file's inode never changes, so handles held elsewhere stay valid), the company artifacts by replacement, and the ChromaDB `company_docs` collection + company skills re-indexed from the restored directories. The isolated per-company collections are wiped in the same pass — `recent_research`, `notion_wiki`, and `inbound_attachments` (attachments are dropped and recreated rather than re-indexed: they have no source directory to rebuild from, and a row surviving a slot switch would be one client's attachment visible to the next). Idempotent schema initializers re-run after every restore, so a slot saved before a schema-adding deploy gains the new tables. Activating a **blank** slot (created with `source: \"blank\"`, no `state.db` yet) factory-wipes the per-client tables and re-seeds defaults — departments, onboarding templates, principal briefs, cadences — so the new client's Today page works without a restart. That wipe covers the **derived caches** — `briefing_narrative` and `person_insights` — as well as authored state. They are regenerable, but `/today` serves them from cache and only regenerates in a background task, so a surviving row renders the *outgoing* client's briefing text under the incoming one, and `person_insights` reaches Discord, the MCP server, and the morning/end-of-day digests as well as the UI. Switching into a slot that already has `state.db` was never exposed: the sqlite backup API truncates the destination to an exact copy of the source.\n\nThe first activation from single-company mode auto-snapshots the original company to `_user_backup` (the same restore point the fixture switcher uses); `POST /fixtures/unload` brings it back and exits client mode.\n\n## Invariants\n\n- At most one slot is active — recorded in an allowlist-validated `.active_client` sentinel.\n- **Only the active client is live**: its scheduled actions fire, its docs are indexed; parked clients sleep. The single-instance scheduler constraint is unchanged.\n- Slot operations share the fixture switcher's destructive-op lock, so fixture loads, snapshots, resets, and slot switches serialize against each other. The Notion sync tick coordinates with the same lock without queueing on it: it skips its tick while the lock is held, fetches from Notion unlocked, and takes the lock only for its short local write phase — aborting without writing if the active client changed mid-fetch (in-process only; a CLI run is a separate process the lock cannot see). A fixture and a client are never active simultaneously (slot ops refuse with 409 while a fixture is loaded); loading a fixture saves an active client back to its slot first, so demos can never destroy client work. Factory reset clears the active-client sentinel but preserves slot directories.\n- `generated_fixtures` is operator-level (the demo library) and is preserved verbatim across switches.\n- **Every path that swaps the live company wipes the derived caches**, from one shared list (`cli.fixture_loader.PER_CLIENT_CACHE_TABLES`): blank/seed slot activation, factory reset, and fixture load *and* unload. Three hand-maintained copies of that list is what let the leak survive in two paths after being fixed in one — a new per-company cache table goes in the constant, once. On the fixture path the wipe runs in `_apply_state_from_source`, unconditionally: a fixture needs only `profile.yaml`, so gating it on `memory.json` would skip exactly the loads that still swap the company.\n- Do **not** treat `person_insights`' `input_hash` as a guard against this. It covers per-person signals (role, principal flag, status, counters, availability, authority and department scope, bucketed timestamps, the UTC day) but carries no person, name or company identity, and the cache key is `person_id` — a reused autoincrement PK. An outgoing principal and a freshly seeded incoming one hash identically whenever those signals coincide, which is ordinary steady state for a seeded slot.\n- Each client gets a stable Honcho workspace (`openexec-client-<slug>`) so peer memory survives parking; fixture teardown paths recognise the prefix and never delete these.\n\n## Caveats\n\n`mcp_servers.json` is read by the MCP gateway at process startup — a switch that changes it takes effect on the next API restart (the activate response carries `mcp_config_changed`). Scheduled actions whose `run_at` passed while a client was parked are claimed on the first tick after activation; authority gates still apply, but expect the returning client's overdue follow-ups to fire shortly after a switch.\n\nTwo residuals. `/today`'s background regeneration tasks capture the outgoing company's data and can write it back into the live DB for up to roughly 25 seconds after the wipe — on **every** swapping path, fixture load/unload and slot activation alike, since those writers neither take the destructive-op lock nor check company identity. For `person_insights` it does not self-heal: the late write stores the outgoing `input_hash`, which the incoming person's signals often match, so the stale note survives until the UTC-day bucket rolls. Closing this needs company identity in the cache hash or those writers taking the lock. Second, and blank-slot only, `dynamic_workflows` / `eval_scenarios` are client-scoped but **not** wiped: they are authored rather than derived, and the first-activation snapshot captures only profile, docs, `memory.json`, people and departments — so wiping them before extending that snapshot would destroy the operator's own work. Until then the outgoing client's workflow definitions stay registered and active on the blank path, runnable against the incoming client's data and readable via `/workflows`.\n\n## Setting up a new engagement with AI\n\n`POST /clients/generate` turns **real intake material** into a reviewable draft of the client: profile, org, roster, starter docs, and known history. Intake material is pasted text (kickoff-call notes, a brief, website copy) and/or **file attachments** (PDF, Word, Excel, CSV, Markdown/text; the request is multipart). Each attachment's extracted text both feeds the draft and is appended to the bundle as a `source_<name>.md` company doc, so it lands in the seed slot and is indexed into the `company_docs` collection on activation alongside the AI-written docs (extracted text, not the original binary; legacy `.xls` is unsupported). It runs the Council-configurable `engagement_intake` agent — the grounded sibling of the demo fixture generator (same bundle schema, validation, and repair-retry; the Company Simulator's fictional path is unchanged). Grounding rules: extract, don't invent — unstated numbers stay null, only people named in the material appear, docs are engagement working documents (intake brief, current-state summary, stakeholder map, open questions), and **no contact handles are ever imported**, even if present in the notes.\n\nSaving the reviewed draft (`POST /clients` with `source: \"generated\"`) writes a **seed slot**: profile and docs as normal slot artifacts, plus `people.yaml` / `departments.yaml` / `memory.json` in the same shapes curated fixtures use. Nothing touches live state until activation, when the blank-restore path applies the seed files with the fixture loader's seeders and skips the default-department reseed (the draft supplied the org). After the first save-back writes `state.db`, the seed files remain as the engagement's birth record but are no longer consulted; `meta.json` records `origin: \"generated\"` and the intake notes.\n\n## The practice layer: engagement metadata + cockpit\n\nEach slot's `meta.json` carries optional **engagement metadata** — your role for the client, engagement status (active/paused/winding down/completed), start and renewal dates, retainer (display only), and primary contact — editable via `PATCH /clients/{slug}` for active *and* parked slots, because meta.json lives outside the swapped client state. Renewal awareness deliberately lives here and never as scheduled actions (those swap with the client and would vanish when parked).\n\nThe **practice cockpit** (`GET /clients/cockpit`) gives cross-client awareness without touching the one-active-client ceiling: the active client is counted from the live DB, and each parked client's `state.db` is opened **read-only, in place** — no activation, no lock. Cards roll up pending/overdue follow-ups, awaiting replies, unread alerts, onboarding tasks due within a week, and renewal countdowns. Parked data is as fresh as the slot's last save point and every card says so; one broken slot degrades to a single error-flagged card, never a failed board. Cockpit cards link to the **engagement value report** — a workflow that turns the client's own record (decisions, deliverables, follow-through) into a renewal-ready artifact, reading parked clients without activating them. With two or more clients, `/today` gains an \"Across your clients\" section for the parked ones — single-company installs see none of this, anywhere.\n\n## Overnight rotation (cockpit v2)\n\nWith `CLIENT_ROTATION_ENABLED=true` (off by default), a nightly scheduled job (`CLIENT_ROTATION_TIME`, default 03:30 UTC) activates each parked client in turn, generates its morning brief as an artifact in that client's own record, runs its monitor scan, saves it back, and **always restores the original active client** — then delivers one cross-client digest via the original client's principal channel. Two safety rails matter: the scheduler **pauses claiming** while the rotation's `.rotation_in_progress` marker exists (so a just-activated client's overdue outbound backlog can never fire at 3am — rotation does brief + monitors only, never outbound), and the rotation row is re-seeded after every slot activation because scheduled rows swap with the client. Completed engagements and never-activated slots sleep through rotation; per-client failures are skipped and reported in the digest.\n\n## API + UI\n\n`GET /clients` (list + active + fixture status), `POST /clients` (`source: \"current\"` captures the live company and activates; `\"blank\"` creates an empty client to onboard fresh; `\"generated\"` saves a reviewed intake draft as a seed slot), `POST /clients/generate` (grounded AI draft from intake notes and/or file attachments; multipart), `PATCH /clients/{slug}` (engagement metadata), `GET /clients/cockpit` (practice board), `POST /clients/save` (checkpoint without switching), `POST /clients/{slug}/activate`, `DELETE /clients/{slug}` (refuses the active slot). The `/clients` page lives under Settings → advanced tools.\n\n**Knowledge review state per slot.** `_ensure_schemas` re-runs the idempotent schema inits after a restore, including `ReviewStore.initialize_db` followed by `sync_builtin_registrations`. Without that second call a freshly activated slot carried an empty `review_items` table until the next process restart; now it gets the shipped docs as trusted defaults straight away, matching a normal boot.","mermaid": "flowchart TD\n UI[\"/clients page (Settings)\"] -->|\"activate slug\"| Lock[\"destructive-op lock (shared with fixtures)\"]\n Lock --> SaveBack[\"save-back: VACUUM INTO state.db + copy profile / docs / skills / mcp\"]\n SaveBack --> SlotA[(\"slot A dir\")]\n SlotB[(\"slot B dir\")] --> Restore[\"restore: sqlite backup API + artifact replacement\"]\n Lock --> Restore\n Restore --> Live[(\"live company context\")]\n Restore --> Chroma[\"reindex company_docs + skills\"]\n Restore -.stable workspace.-> Honcho[\"Honcho peer memory\"]\n Live --> Scheduler[\"scheduler: only the ACTIVE client's actions fire\"]",- "generated_at": "2026-09-16T09:20:23.406805+00:00"- }- "generated_at": "2026-09-16T12:33:27.680504+00:00"++ "generated_at": "2026-09-16T22:54:43.608081+00:00"+ }diff --cc packages/core/openexecutive/architecture/prebuilt/rag.jsonindex adbc2dd4,d29e3fe0..8c358897--- a/packages/core/openexecutive/architecture/prebuilt/rag.json+++ b/packages/core/openexecutive/architecture/prebuilt/rag.json@@@ -1,7 -1,7 +1,7 @@@{"section_id": "rag","title": "Knowledge & RAG",- "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. Five collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Chat/email attachments share the collection but are namespaced `attachment:<name>`, since the sender picks that name and an unprefixed one would overwrite the curated document it collides with; they also carry a non-specialist domain, so they are not retrieved (see Integrations).\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `board_comms`→`board`,`finance`. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The ninth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint and in the UI's picker). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\n### The SME review gate\n\nBefore the distance threshold applies, both `retrieve` and `retrieve_failures` drop **withheld** items — anything the review store reports as `pending` or `rejected` (`ReviewStore.get_withheld_filenames`). Approved items with a priority set are then sorted ahead of the rest.\n\nKnowledge shipped with the product registers as a trusted default (`approved`, NULL `reviewed_at`), so nothing is withheld until a human deliberately queues a domain for curation or rejects something. See the **SME Knowledge Review** section for the full state model. The filter matches on the `(domain, filename)` pair Chroma carries. A bare filename was ambiguous *and* caller-choosable — `POST /knowledge/builtin` takes any `(domain, filename)`, so uploading a file named after a shipped doc in another domain silently withheld that shipped doc from every specialist. Failure case studies are keyed in their own namespace, so a user-authored one cannot collide with a shipped one.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.",- "mermaid": "flowchart TD\n Call[\"Specialist call<br/>(domain-filtered)\"] --> Q[\"retrieve(query, domain)\"]\n Q --> Builtin[(BUILTIN)]\n Q --> Company[(COMPANY)]\n Q --> NotionWiki[(NOTION_WIKI)]\n Q --> Failures[(FAILURES)]\n Q --> Research[(RECENT_RESEARCH)]\n Builtin --> Dedupe[\"dedupe by text<br/>+ distance gate\"]\n Company --> Dedupe\n NotionWiki --> Dedupe\n Failures --> Dedupe\n Research --> Dedupe\n Dedupe --> Inject[\"Inject into USER turn<br/>(not cached)\"]\n class Call entry\n class Q compute\n class Dedupe compute\n class Builtin storage\n class Company storage\n class NotionWiki storage\n class Failures storage\n class Research storage\n class Inject hot",- "generated_at": "2026-09-16T13:15:55.101359+00:00"- "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. Six collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Inbound attachments are **not** here — see ATTACHMENTS below; rows left by the earlier scheme are migrated out on boot.\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents.\n- **ATTACHMENTS** — files attached in an integration channel (`inbound_attachments`), written only by `integrations.attachments`. The one collection `retrieve` **never queries**. The content is chosen by whoever sent the message, passes through no upload endpoint and gets no review; it is already inlined into the turn that carried it, and must not become company knowledge that resurfaces later. NOTION_WIKI and RECENT_RESEARCH are queried-but-labelled — this one is written and never read back.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `board_comms`→`board`,`finance`. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The ninth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint and in the UI's picker). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.",++ "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. Six collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Inbound attachments are **not** here — see ATTACHMENTS below; rows left by the earlier scheme are migrated out on boot.\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents.\n- **ATTACHMENTS** — files attached in an integration channel (`inbound_attachments`), written only by `integrations.attachments`. The one collection `retrieve` **never queries**. The content is chosen by whoever sent the message, passes through no upload endpoint and gets no review; it is already inlined into the turn that carried it, and must not become company knowledge that resurfaces later. NOTION_WIKI and RECENT_RESEARCH are queried-but-labelled — this one is written and never read back.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `board_comms`→`board`,`finance`. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The ninth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint and in the UI's picker). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\n### The SME review gate\n\nBefore the distance threshold applies, both `retrieve` and `retrieve_failures` drop **withheld** items — anything the review store reports as `pending` or `rejected` (`ReviewStore.get_withheld_filenames`). Approved items with a priority set are then sorted ahead of the rest.\n\nKnowledge shipped with the product registers as a trusted default (`approved`, NULL `reviewed_at`), so nothing is withheld until a human deliberately queues a domain for curation or rejects something. See the **SME Knowledge Review** section for the full state model. The filter matches on the `(domain, filename)` pair Chroma carries. A bare filename was ambiguous *and* caller-choosable — `POST /knowledge/builtin` takes any `(domain, filename)`, so uploading a file named after a shipped doc in another domain silently withheld that shipped doc from every specialist. Failure case studies are keyed in their own namespace, so a user-authored one cannot collide with a shipped one.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.",+ "mermaid": "flowchart TD\n Call[\"Specialist call<br/>(domain-filtered)\"] --> Q[\"retrieve(query, domain)\"]\n Q --> Builtin[(BUILTIN)]\n Q --> Company[(COMPANY)]\n Q --> NotionWiki[(NOTION_WIKI)]\n Q --> Failures[(FAILURES)]\n Q --> Research[(RECENT_RESEARCH)]\n Attach[\"integrations.attachments\"] --> Attachments[(ATTACHMENTS<br/>never queried)]\n Builtin --> Dedupe[\"dedupe by text<br/>+ distance gate\"]\n Company --> Dedupe\n NotionWiki --> Dedupe\n Failures --> Dedupe\n Research --> Dedupe\n Dedupe --> Inject[\"Inject into USER turn<br/>(not cached)\"]\n class Call entry\n class Q compute\n class Dedupe compute\n class Builtin storage\n class Company storage\n class NotionWiki storage\n class Failures storage\n class Research storage\n class Attachments storage\n class Attach compute\n class Inject hot",- "generated_at": "2026-09-16T12:26:36.985695+00:00"++ "generated_at": "2026-09-16T22:54:43.608081+00:00"}diff --cc packages/core/openexecutive/knowledge/shipped_manifest.pyindex 684a90a2,00000000..f88a4b65mode 100644,000000..100644--- a/packages/core/openexecutive/knowledge/shipped_manifest.py+++ b/packages/core/openexecutive/knowledge/shipped_manifest.py@@@ -1,113 -1,0 +1,114 @@@+"""The built-in knowledge files that SHIP with Open Executive.++This list is the *only* source of truth for content provenance. It cannot be+derived from the filesystem at runtime: `POST /knowledge/builtin` writes a+user's own document into the very same `knowledge/builtin/<domain>/` tree+(`api/routes/knowledge._resolve_path`), so "there is a .md file at this path"+is equally true of shipped content and of a confidential draft someone just+uploaded. Re-deriving provenance from the tree marked those uploads as shipped+and auto-approved them into retrieval.++`ReviewStore.sync_builtin_registrations` registers exactly these paths as+trusted defaults. Anything else in the tree belongs to the user and reaches+`review_items` through `ReviewStore.register()`, which never sets+`trusted_default`.++Regenerate after adding or removing a built-in knowledge doc:++ git ls-files 'packages/core/openexecutive/knowledge/builtin/**/*.md' \+ | grep -v '/skills/' \+ | sed 's#packages/core/openexecutive/knowledge/builtin/##' | sort++`tests/unit/test_review_store.py::test_shipped_manifest_matches_git` fails if+this drifts from the tracked files.+"""++from __future__ import annotations++# Paths are POSIX-relative to `knowledge/builtin/`.+SHIPPED_BUILTIN_FILES: frozenset[str] = frozenset(+ (- "board/audit_and_comp_committees.md",- "board/board_communication.md",- "board/board_composition_and_governance.md",- "board/ceo_succession.md",- "board/investor_relations.md",- "board/special_situations.md",- "failures/board/credit-suisse.md",- "failures/board/theranos.md",- "failures/finance/enron.md",- "failures/finance/silicon-valley-bank.md",- "failures/finance/wework-ipo.md",- "failures/hr/twitter-x-acquisition.md",- "failures/hr/uber-culture.md",- "failures/hr/yahoo-talent-exodus.md",- "failures/legal/ftx-collapse.md",- "failures/marketing/new-coke.md",- "failures/operations/boeing-737-max.md",- "failures/operations/spirit-airlines.md",- "failures/product/quibi.md",- "failures/strategy/aol-time-warner.md",- "failures/strategy/google-glass.md",- "failures/strategy/kodak-digital.md",- "failures/strategy/peloton.md",- "finance/accounting_basics.md",- "finance/capital_allocation.md",- "finance/financial_modeling.md",- "finance/financial_statements.md",- "finance/fundraising.md",- "finance/ipo_and_late_stage_readiness.md",- "finance/saas_metrics.md",- "finance/unit_economics.md",- "finance/valuation_methods.md",- "hr/compensation_design.md",- "hr/culture_and_values.md",- "hr/hiring_frameworks.md",- "hr/layoffs_and_rifs.md",- "hr/manager_effectiveness.md",- "hr/org_design.md",- "hr/performance_management.md",- "hr/talent_development.md",- "legal/ai_and_data_law.md",- "legal/commercial_contracts.md",- "legal/data_privacy_and_security.md",- "legal/employment_law_for_managers.md",- "legal/ip_strategy.md",- "legal/ma_legal_essentials.md",- "legal/securities_and_cap_table.md",- "legal/startup_legal_basics.md",- "marketing/brand_strategy.md",- "marketing/content_marketing.md",- "marketing/customer_marketing.md",- "marketing/demand_generation.md",- "marketing/go_to_market.md",- "marketing/positioning_and_messaging.md",- "marketing/pricing_and_packaging.md",- "operations/ai_and_automation.md",- "operations/business_continuity.md",- "operations/customer_support_operations.md",- "operations/procurement_and_vendor_management.md",- "operations/project_management.md",- "operations/quality_and_process.md",- "operations/scaling_operations.md",- "operations/security_operations.md",- "product/experimentation.md",- "product/launch_playbooks.md",- "product/prioritization_frameworks.md",- "product/product_analytics.md",- "product/product_discovery.md",- "product/product_led_growth.md",- "product/product_market_fit.md",- "product/product_strategy.md",- "product/roadmapping.md",- "strategy/business_model_frameworks.md",- "strategy/competitive_analysis.md",- "strategy/corporate_strategy.md",- "strategy/growth_strategy.md",- "strategy/mergers_acquisitions.md",- "strategy/okr_frameworks.md",- "strategy/partnerships_and_alliances.md",- "strategy/scenario_planning.md",- "strategy/startup_lifecycle.md",++ "board/audit_and_comp_committees.md",++ "board/board_communication.md",++ "board/board_composition_and_governance.md",++ "board/ceo_succession.md",++ "board/investor_relations.md",++ "board/special_situations.md",++ "failures/board/credit-suisse.md",++ "failures/board/theranos.md",++ "failures/finance/enron.md",++ "failures/finance/silicon-valley-bank.md",++ "failures/finance/wework-ipo.md",++ "failures/hr/twitter-x-acquisition.md",++ "failures/hr/uber-culture.md",++ "failures/hr/yahoo-talent-exodus.md",++ "failures/legal/ftx-collapse.md",++ "failures/legal/waymo-v-uber.md",++ "failures/marketing/new-coke.md",++ "failures/operations/boeing-737-max.md",++ "failures/operations/spirit-airlines.md",++ "failures/product/quibi.md",++ "failures/strategy/aol-time-warner.md",++ "failures/strategy/google-glass.md",++ "failures/strategy/kodak-digital.md",++ "failures/strategy/peloton.md",++ "finance/accounting_basics.md",++ "finance/capital_allocation.md",++ "finance/financial_modeling.md",++ "finance/financial_statements.md",++ "finance/fundraising.md",++ "finance/ipo_and_late_stage_readiness.md",++ "finance/saas_metrics.md",++ "finance/unit_economics.md",++ "finance/valuation_methods.md",++ "hr/compensation_design.md",++ "hr/culture_and_values.md",++ "hr/hiring_frameworks.md",++ "hr/layoffs_and_rifs.md",++ "hr/manager_effectiveness.md",++ "hr/org_design.md",++ "hr/performance_management.md",++ "hr/talent_development.md",++ "legal/ai_and_data_law.md",++ "legal/commercial_contracts.md",++ "legal/data_privacy_and_security.md",++ "legal/employment_law_for_managers.md",++ "legal/ip_strategy.md",++ "legal/ma_legal_essentials.md",++ "legal/securities_and_cap_table.md",++ "legal/startup_legal_basics.md",++ "marketing/brand_strategy.md",++ "marketing/content_marketing.md",++ "marketing/customer_marketing.md",++ "marketing/demand_generation.md",++ "marketing/go_to_market.md",++ "marketing/positioning_and_messaging.md",++ "marketing/pricing_and_packaging.md",++ "operations/ai_and_automation.md",++ "operations/business_continuity.md",++ "operations/customer_support_operations.md",++ "operations/procurement_and_vendor_management.md",++ "operations/project_management.md",++ "operations/quality_and_process.md",++ "operations/scaling_operations.md",++ "operations/security_operations.md",++ "product/experimentation.md",++ "product/launch_playbooks.md",++ "product/prioritization_frameworks.md",++ "product/product_analytics.md",++ "product/product_discovery.md",++ "product/product_led_growth.md",++ "product/product_market_fit.md",++ "product/product_strategy.md",++ "product/roadmapping.md",++ "strategy/business_model_frameworks.md",++ "strategy/competitive_analysis.md",++ "strategy/corporate_strategy.md",++ "strategy/growth_strategy.md",++ "strategy/mergers_acquisitions.md",++ "strategy/okr_frameworks.md",++ "strategy/partnerships_and_alliances.md",++ "strategy/scenario_planning.md",++ "strategy/startup_lifecycle.md",+ )+)diff --cc packages/core/tests/unit/test_attachment_isolation.pyindex 00000000,4964db89..fc1b932bmode 000000,100644..100644--- a/packages/core/tests/unit/test_attachment_isolation.py+++ b/packages/core/tests/unit/test_attachment_isolation.py@@@ -1,0 -1,436 +1,436 @@@+ """Integration attachments are isolated from company knowledge.++ Two guarantees, both regressions of a real bug:++ 1. ``retriever.retrieve`` never queries the attachment collection, so an+ attachment cannot resurface as company knowledge in a later turn.+ 2. Rows written by the old path — which put them in ``company_docs`` and+ relied on a non-specialist domain to keep them out — are migrated across+ on boot rather than left behind.++ The bug that motivated both: an unrecognised domain does NOT exclude a row.+ ``ChromaDBStore.query`` builds a ``where`` clause only when ``domain_filter``+ is truthy, and an Executive-level ``retrieve`` passes none, so those chunks+ matched and were rendered under "From your company documents" — top-ranked+ and indistinguishable from a curated upload.+ """+ from __future__ import annotations++ from typing import Any++ from openexecutive.knowledge.loader import (+ ATTACHMENT_DOMAIN,+ ATTACHMENT_SOURCE_PREFIX,+ migrate_attachments_out_of_company_docs,+ )+ from openexecutive.knowledge.store import ChromaDBStore+++ class FakeStore:+ """Collection-aware in-memory store.++ Local rather than the shared ``tests.unit._fake_store``, which is flat and+ drops the ``collection`` argument — it cannot express "this row went to a+ different collection", which is the whole subject here. Same shape as the+ fakes in ``test_recent_research_knowledge`` and ``test_notion_sync``.+ """++ def __init__(self) -> None:+ # collection -> chunk_id -> {"text": str, "metadata": dict}+ self.collections: dict[str, dict[str, dict[str, Any]]] = {}+ self.add_failures: set[str] = set()++ def _col(self, collection: str) -> dict[str, dict[str, Any]]:+ return self.collections.setdefault(collection, {})++ def add_documents(+ self,+ texts: list[str],+ metadatas: list[dict[str, Any]],+ ids: list[str],+ collection: str,+ ) -> None:+ if collection in self.add_failures:+ raise RuntimeError(f"simulated write failure into {collection}")+ col = self._col(collection)+ for chunk_id, text, meta in zip(ids, texts, metadatas, strict=True):+ col[chunk_id] = {"text": text, "metadata": dict(meta)}++ def iter_chunk_metadata(self, collection: str) -> list[tuple[str, dict[str, Any]]]:+ return [(cid, dict(r["metadata"])) for cid, r in self._col(collection).items()]++ def get_documents_by_ids(+ self, collection: str, ids: list[str]+ ) -> list[tuple[str, str, dict[str, Any]]]:+ if not ids:+ return []+ col = self._col(collection)+ return [+ (cid, col[cid]["text"], dict(col[cid]["metadata"]))+ for cid in ids+ if cid in col+ ]++ def delete_by_ids(self, collection: str, ids: list[str]) -> int:+ if not ids:+ return 0+ col = self._col(collection)+ return sum(col.pop(cid, None) is not None for cid in ids)++ def query(+ self,+ query_text: str,+ collection: str,+ domain_filter: list[str] | None = None,+ n_results: int = 5,+ ) -> list[dict[str, Any]]:+ """Models the one behaviour this whole change turns on: a falsy+ domain filter is NO filter, so it matches every row — the same+ `if domain_filter:` gate `ChromaDBStore.query` uses."""+ rows = []+ for r in self._col(collection).values():+ if domain_filter and r["metadata"].get("domain") not in domain_filter:+ continue+ rows.append({"text": r["text"], "metadata": r["metadata"], "distance": 0.1})+ return rows[:n_results]++ # -- helpers ----------------------------------------------------------+ def seed(+ self,+ collection: str,+ chunk_id: str,+ text: str,+ **metadata: Any,+ ) -> None:+ self._col(collection)[chunk_id] = {"text": text, "metadata": metadata}++ def names(self, collection: str) -> set[str]:+ return {r["metadata"].get("filename") for r in self._col(collection).values()}+++ def _seed_legacy_attachment(store: FakeStore, name: str, text: str) -> str:+ """A row exactly as the pre-fix path wrote it: in COMPANY, no type tag."""+ chunk_id = f"id-{name}"+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ chunk_id,+ text,+ domain="company_docs",+ filename=f"{ATTACHMENT_SOURCE_PREFIX}{name}",+ source=f"{ATTACHMENT_SOURCE_PREFIX}{name}",+ chunk_index=0,+ )+ return chunk_id+++ def _migrate(store: FakeStore) -> int:+ return migrate_attachments_out_of_company_docs(store) # type: ignore[arg-type]+++ # ── migration ─────────────────────────────────────────────────────────────+++ def test_legacy_rows_move_to_the_isolated_collection_with_their_text():+ store = FakeStore()+ _seed_legacy_attachment(store, "leak.md", "ACME gross margin is 91 percent.")+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ "id-plan",+ "Curated plan.",+ domain="strategy",+ filename="plan.md",+ source="plan.md",+ chunk_index=0,+ )++ assert _migrate(store) == 1++ assert store.names(ChromaDBStore.COMPANY_COLLECTION) == {"plan.md"}+ attachments = store.collections[ChromaDBStore.ATTACHMENT_COLLECTION]+ assert len(attachments) == 1+ moved = next(iter(attachments.values()))+ # The text has to survive: attachments are never written to company/docs/,+ # so the store holds the only copy and a lossy move destroys it.+ assert moved["text"] == "ACME gross margin is 91 percent."+++ def test_migration_preserves_chunk_ids():+ """Ids are what make a re-ingest of the same attachment upsert rather than+ duplicate, and what make this migration idempotent."""+ store = FakeStore()+ chunk_id = _seed_legacy_attachment(store, "leak.md", "text")++ _migrate(store)++ assert chunk_id in store.collections[ChromaDBStore.ATTACHMENT_COLLECTION]+++ def test_migration_normalizes_domain_and_type():+ store = FakeStore()+ _seed_legacy_attachment(store, "leak.md", "text")++ _migrate(store)++ moved = next(iter(store.collections[ChromaDBStore.ATTACHMENT_COLLECTION].values()))+ assert moved["metadata"]["type"] == "attachment"+ assert moved["metadata"]["domain"] == ATTACHMENT_DOMAIN+++ def test_migration_is_idempotent():+ store = FakeStore()+ _seed_legacy_attachment(store, "leak.md", "text")++ assert _migrate(store) == 1+ before = dict(store.collections[ChromaDBStore.ATTACHMENT_COLLECTION])++ assert _migrate(store) == 0+ assert store.collections[ChromaDBStore.ATTACHMENT_COLLECTION] == before+++ def test_migration_is_a_noop_on_a_clean_store():+ store = FakeStore()+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ "id-plan",+ "Curated plan.",+ domain="strategy",+ filename="plan.md",+ source="plan.md",+ )++ assert _migrate(store) == 0+ assert ChromaDBStore.ATTACHMENT_COLLECTION not in store.collections+ assert store.names(ChromaDBStore.COMPANY_COLLECTION) == {"plan.md"}+++ def test_migration_does_not_match_a_curated_document_named_like_one():+ """`startswith`, not `in` — a real company document about attachments is+ not an attachment."""+ store = FakeStore()+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ "id-policy",+ "How we handle attachments.",+ domain="operations",+ filename="attachments-policy.md",+ source="attachments-policy.md",+ )++ assert _migrate(store) == 0+ assert store.names(ChromaDBStore.COMPANY_COLLECTION) == {"attachments-policy.md"}+++ def test_migration_writes_before_it_deletes():+ """The ordering is the safety property.++ Chroma spans no transaction across two collections. A crash after the+ write leaves a duplicate the next run collapses; a crash after a delete+ destroys the only copy of an attachment, which has no file on disk to be+ re-ingested from. So a failed write must leave COMPANY untouched.+ """+ store = FakeStore()+ _seed_legacy_attachment(store, "leak.md", "irreplaceable")+ store.add_failures.add(ChromaDBStore.ATTACHMENT_COLLECTION)++ try:+ _migrate(store)+ except RuntimeError:+ pass++ assert store.names(ChromaDBStore.COMPANY_COLLECTION) == {+ f"{ATTACHMENT_SOURCE_PREFIX}leak.md"+ }+++ def test_migration_also_catches_rows_already_carrying_the_type_tag():+ """Rows written by an interim build land in COMPANY with the tag but no+ prefix guarantee; both markers have to be recognised."""+ store = FakeStore()+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ "id-tagged",+ "text",+ domain=ATTACHMENT_DOMAIN,+ filename="oddly-named.md",+ source="oddly-named.md",+ type="attachment",+ )++ assert _migrate(store) == 1+ assert store.collections[ChromaDBStore.COMPANY_COLLECTION] == {}+++ # ── retrieval isolation ───────────────────────────────────────────────────+++ def _fake_review_store() -> Any:+ """ReviewStore stub returning empty sets.++ `retrieve` falls back to the real `_default_review_store()`, which opens a+ SQLite file that a clean checkout does not have — so without this the test+ passes or fails depending on whether some earlier test created the DB.+ Same shape as the fixture in `test_retriever_gating`.+ """+ from types import SimpleNamespace++ return SimpleNamespace(- get_rejected_filenames=lambda _ct: set(),- get_rejected_source_ids=lambda: set(),++ get_withheld_keys=lambda _ct: set(),++ get_withheld_source_ids=lambda: set(),+ get_priority_map=lambda _ct: {},+ list_annotations=lambda domains=None, active_only=True: [],+ )+++ def _retrieve_collections_queried(**retrieve_kwargs: Any) -> list[str]:+ """Run the real `retrieve` and report which collections it asked for."""+ from unittest.mock import MagicMock++ from openexecutive.knowledge import retriever++ seen: list[str] = []++ def _query(query_text: str, collection: str, **kwargs: Any) -> list[dict[str, Any]]:+ seen.append(collection)+ return []++ store = MagicMock()+ store.query.side_effect = _query+ retriever.retrieve(+ query="what is the gross margin for the quarter, in detail?",+ store=store,+ review_store=_fake_review_store(),+ **retrieve_kwargs,+ )+ return seen+++ def test_retrieve_never_queries_the_attachment_collection():+ """Both the unfiltered Executive turn and a specialist-routed call."""+ for kwargs in ({"specialist_name": None}, {"specialist_name": "finance"}):+ seen = _retrieve_collections_queried(**kwargs)+ assert ChromaDBStore.COMPANY_COLLECTION in seen, "company still retrieved"+ assert ChromaDBStore.ATTACHMENT_COLLECTION not in seen, (+ f"attachment collection was queried with {kwargs}"+ )+++ def test_a_curated_upload_named_like_an_attachment_is_not_migrated():+ """The prefix is not proof of origin.++ A colon is legal in a filename and `POST /documents` passes one through,+ so a real company document can be called `attachment:q4-plan.md`. Moving+ it would strip it from the collection it belongs in, leave an undeletable+ copy behind, and — because the file is still on disk — have the boot+ reconcile re-index it as `general`, widening an HR document to every+ specialist. The legacy `domain` is what distinguishes the two, and+ UPLOAD_DOMAINS will never accept that value from an upload.+ """+ store = FakeStore()+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ "id-curated",+ "Compensation bands for Q4.",+ domain="hr", # a real upload domain, not the legacy marker+ filename=f"{ATTACHMENT_SOURCE_PREFIX}q4-comp-plan.md",+ source=f"{ATTACHMENT_SOURCE_PREFIX}q4-comp-plan.md",+ )++ assert _migrate(store) == 0+ assert store.names(ChromaDBStore.COMPANY_COLLECTION) == {+ f"{ATTACHMENT_SOURCE_PREFIX}q4-comp-plan.md"+ }+ assert ChromaDBStore.ATTACHMENT_COLLECTION not in store.collections+++ def test_migration_reports_only_what_it_actually_removed():+ """`delete_by_ids` returns 0 when the delete raises — it says so in its own+ docstring precisely so a caller cannot claim rows it did not remove.++ Reporting `len(ids)` regardless would log "moved N chunks" on a boot where+ all N are still in COMPANY and still retrievable: the leak announced as+ closed while it is open.+ """+ store = FakeStore()+ _seed_legacy_attachment(store, "leak.md", "text")+ store.delete_by_ids = lambda collection, ids: 0 # type: ignore[assignment]++ assert _migrate(store) == 0+++ def test_migration_does_not_clobber_a_newer_copy():+ """Ids collide by design — md5 of the same source name on both sides.++ A row already in the destination was written by the post-fix path and is+ newer than the COMPANY copy, so upserting the old text over it would+ resurrect superseded content. Drop the stale original instead.+ """+ store = FakeStore()+ chunk_id = _seed_legacy_attachment(store, "notes.md", "OLD v1")+ store.seed(+ ChromaDBStore.ATTACHMENT_COLLECTION,+ chunk_id,+ "NEW v2",+ domain=ATTACHMENT_DOMAIN,+ filename=f"{ATTACHMENT_SOURCE_PREFIX}notes.md",+ source=f"{ATTACHMENT_SOURCE_PREFIX}notes.md",+ type="attachment",+ )++ assert _migrate(store) == 1+ assert store.collections[ChromaDBStore.COMPANY_COLLECTION] == {}+ assert store.collections[ChromaDBStore.ATTACHMENT_COLLECTION][chunk_id][+ "text"+ ] == "NEW v2"+++ def test_unfiltered_retrieval_matches_every_domain_including_unrecognised_ones():+ """The bug itself, as a standing regression.++ This is the premise the old code got wrong: a domain nothing maps to was+ believed to exclude a row. It does not — a falsy filter is NO filter. If+ this ever stops holding, the isolation rationale needs rewriting, not the+ test.+ """+ store = FakeStore()+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ "id-x",+ "secret",+ domain="a-domain-no-specialist-maps-to",+ filename="x.md",+ )++ unfiltered = store.query("q", ChromaDBStore.COMPANY_COLLECTION, domain_filter=None)+ filtered = store.query(+ "q", ChromaDBStore.COMPANY_COLLECTION, domain_filter=["finance"]+ )++ assert len(unfiltered) == 1, "an absent filter must match every domain"+ assert filtered == [], "an explicit filter must still exclude"+++ def test_migrated_attachment_is_no_longer_reachable_by_an_unfiltered_retrieve():+ """End to end: the leak reproduces before the migration and is gone after.++ Drives the real `retriever.retrieve` on the no-specialist path — the one+ that passes no domain filter — against a store that honours filters the+ way ChromaDB does.+ """+ from openexecutive.knowledge import retriever++ store = FakeStore()+ _seed_legacy_attachment(store, "leak.md", "ACME gross margin is 91 percent.")++ query = "what is the gross margin for the quarter, in detail?"+ rs = _fake_review_store()+ before = retriever.retrieve(+ query=query, specialist_name=None, store=store, review_store=rs+ )+ assert "91 percent" in before, "expected to reproduce the leak pre-migration"++ _migrate(store)++ after = retriever.retrieve(+ query=query, specialist_name=None, store=store, review_store=rs+ )+ assert "91 percent" not in after