docs(rag): document the 0.4.0 company layer for agents

Add an architecture doc for the company-in-a-box layer (charter, pitches,
strategy engine, cockpit signals, feature toggles) — none of it was in the KB
the agents query — and note the on-demand human-facing roles (prompter,
secretary) in org-structure so they are no longer invisible.

docs/rag/architecture/company-layer.md

@@ -0,0 +1,72 @@
+# Company Layer (Goals, Pitches, Strategy)
+
+The **company layer** sits above day-to-day delivery: the CEO's charter, the
+pitch pipeline, and a background strategy watcher. The charter is always
+available (empty until set); the research, provisioning, and strategy-engine
+pieces are **opt-in and default-off** — the org runs fine without any of them.
+
+## The Charter (Company Goals)
+
+A single, CEO-owned charter is the company's north star. It has four parts:
+
+| Field | Meaning |
+|-------|---------|
+| `north_star` | The one outcome everything serves |
+| `objectives` | Prioritized goals beneath the north star |
+| `constraints` | Hard limits the company must respect |
+| `operating_policy` | Operating rules (e.g. a monthly budget cap) |
+
+The charter is a **singleton**, and it is injected — compactly — into **every
+agent's briefing**, so all work is goal-aware without anyone fetching it.
+
+- `GET /api/company-goals` — read (any agent)
+- `PUT /api/company-goals` — write (CEO only)
+
+It is empty until the CEO sets it; an empty charter simply contributes nothing
+to briefings.
+
+## Pitches
+
+A **pitch** is a proposal for new product work. Its lifecycle is small:
+
+| Status | Meaning |
+|--------|---------|
+| `proposed` | Submitted, awaiting the CEO |
+| `provisioned` | Approved — turned into a product / project(s) |
+| `rejected` | Declined |
+
+When a pitch is approved and **provisioning is enabled**
+(`ROBOCO_PROVISIONING_ENABLED` plus a GitHub token and org), it can auto-create
+the product and its repositories (recorded in `provisioned_product_id` /
+`provisioned_project_ids`). With provisioning off, approval just records the
+decision.
+
+## Strategy Engine
+
+The Strategy Engine is a **notify-only** background watcher
+(`ROBOCO_STRATEGY_ENGINE_ENABLED`, default off). Each cycle it `assess()`es the
+company against its standing goals and emits `StrategyObservation`s — each a
+`kind`, a `summary`, and a `detail` — for example `idle` (capacity sitting
+unused) or `stranded_blocked` (work stuck in `blocked`). It only **observes and
+surfaces**; it never acts on its own.
+
+Those observations are the "needs your attention" signals shown on the
+Dashboard, served by `GET /api/cockpit/signals`.
+
+## The Secretary
+
+The CEO's chief-of-staff reads this layer (`read_company_state` returns the
+charter, task counts, pending pitches, and any directives awaiting
+confirmation) and acts on it via gated directives. See
+`docs/rag/roles/secretary.md`.
+
+## Feature Toggles
+
+| Env | Default | Enables |
+|-----|---------|---------|
+| `ROBOCO_RESEARCH_ENABLED` | off | Board / PM web research |
+| `ROBOCO_STRATEGY_ENGINE_ENABLED` | off | The strategy watcher loop |
+| `ROBOCO_PROVISIONING_ENABLED` | off | Pitch → auto-provisioned repos |
+
+All are additive: with every toggle off, the company layer is just the charter
+plus the pitch record.

docs/rag/architecture/org-structure.md

@@ -32,6 +32,20 @@ CEO (Renzo - Human)
 | Documenters | 3 (1 per cell) |
 | **Total** | **20** (19 AI + 1 human) |
 
+## On-Demand Roles (Human-Facing)
+
+Two roles sit outside the standing delivery org above. They are **human-only**,
+**spawned on demand** as live chat sessions, and are not part of the 20-agent
+count:
+
+| Role | Purpose |
+|------|---------|
+| Prompter (Intake) | Interviews the CEO and drafts a board-ready task |
+| Secretary | The CEO's chief-of-staff; reads company state and runs gated CEO directives |
+
+Neither has lifecycle verbs or outward agent comms. See
+`docs/rag/roles/prompter.md` and `docs/rag/roles/secretary.md`.
+
 ## Cells
 
 | Cell | PM | Developers | QA | Documenter |