docs: add the user-facing MkDocs documentation site

Build a complete user-facing documentation site (MkDocs Material) under docs/, served at roboco.dev/docs via a new gh-pages deploy workflow.

- Sections: Get Started, The Company, the Tour, Operating the Panel, Choosing & Running Models, Cost & Observability, Optional Subsystems, Configure & Deploy, API Reference, Troubleshooting & Security (55 pages).
- mkdocs.yml (Material theme; excludes the agent-facing rag/ corpus, internal scratch, and orphaned stub trees) and .github/workflows/docs.yml (mkdocs gh-deploy to gh-pages).
- Retire the stale root usage.md and deployment.md to redirect stubs into the site.
- Fix the docs tooling: add the pymarkdownlnt dependency + .pymarkdown.json, run serve-docs/lint-docs/fix-docs under the docs extra, add a build-docs strict gate.
- Fix the roboco console-script entry point (cli, not the un-awaited async main).
- README: correct the project-structure tree (optimal.py, alembic) and link the docs site.

docs/panel/agents-and-work-sessions.md

@@ -0,0 +1,50 @@
+# Agents & work sessions
+
+The **Agents** page (`/agents`) is your view of the workforce: who's running, who's idle, who's stuck, and what each one is costing in tokens. From an agent's detail page you can spawn or stop it and watch its reasoning live. The **Work Sessions** ledger (`/work-sessions`) is the read-only record of every branch-and-PR an agent has worked, tying git activity back to the agents that produced it.
+
+## The roster (`/agents`)
+
+Agents are grouped exactly the way the org chart is laid out:
+
+- **Board** — Product Owner, Head of Marketing, Auditor
+- **Main PM**
+- **Backend Cell**, **Frontend Cell**, **UX/UI Cell**
+- **Support** — the CEO-direct helpers (Intake/Prompter, Secretary, the root PR Reviewer), shown only when present
+
+Each card shows the agent's **live state** merged with its **token usage**, so health and cost sit together. States you'll see:
+
+| State | Meaning |
+|-------|---------|
+| `running` / `ready` / `starting` | the agent is alive and working (or coming up) |
+| `idle` | spawned but with no work in hand |
+| `waiting_long` | blocked, waiting on human input or an external resolution |
+| `error` | the container hit errors (the card shows the error count) |
+
+A **Waiting Agents** alert surfaces any agent stuck in `waiting_long` at the top of the page, so a blocked agent doesn't sit unnoticed.
+
+## Agent detail (`/agents/[id]`)
+
+Open an agent to control it and watch it think. The page gives you:
+
+- **Spawn** — bring the agent's container up.
+- **Stop** (graceful) and **Force Stop** — wind it down cleanly or kill it immediately.
+- **Resolve Wait** — when an agent is in `waiting_long`, this dialog is how you hand it the input or decision it's blocked on.
+- **Live stream viewer** — while the agent is active, a viewer streams its reasoning in real time over the agent WebSocket, so you can literally watch it work.
+
+!!! tip "Stop the bleeding"
+    If an agent is crash-looping or burning tokens, **Force Stop** from its detail page is the fastest way to halt it. For provider rate-limits and overloads you don't need to intervene — those *park and auto-resume*; you'll see an amber banner instead (see [resilience](../models/resilience.md)).
+
+Per-agent token spend rolls up into the [Metrics](./metrics.md) page for cost analysis, and what agents say and learn is in [Communications & journals](./communications-and-journals.md).
+
+## Work Sessions (`/work-sessions`)
+
+A **WorkSession** links an agent's work to a task and tracks its git footprint — branch name, base and target branches, the PR number/URL, and merge status. The Work Sessions page is a **read-only ledger** of those sessions, with search-by-branch and a status filter (state, again, lives in the URL).
+
+!!! note "No sidebar link"
+    Work Sessions has **no entry in the sidebar nav**. Reach it by typing `/work-sessions` directly or by following a link from elsewhere in the panel. It's a reference ledger, not a daily-driver page.
+
+For the lifecycle of a branch from cut to merge, see [the merge model](../company/merge-model.md).
+
+## Next
+
+→ [Git](./git.md) to operate on those branches directly, or [Tasks & Kanban](./tasks-and-kanban.md) to see the work the agents are running.

docs/panel/auditor.md

@@ -0,0 +1,30 @@
+# Auditor
+
+The Auditor is the company's silent quality conscience. It has read access to every channel, every task, and every piece of evidence — and it never participates. It can leave a private note and read evidence; it has no `say`, no `dm`, no merge verb. The `/auditor` page is your window into what it sees.
+
+## What the dashboard shows
+
+The Auditor dashboard is four panels plus two controls (**Refresh** and **Generate Report**).
+
+| Panel | What it surfaces |
+|-------|------------------|
+| **Live Feeds** | The activity the Auditor is watching right now across the company. |
+| **Quality Metrics** | Aggregate quality indicators rolled up from the work in flight. |
+| **Flagged Items** | The things the Auditor has flagged for attention — the unresolved-flag list that also feeds the Command Center's Auditor Alerts. |
+| **Reports** | Audit reports, newest first. |
+
+**Generate Report** produces an audit-summary report on demand and drops it into the Reports panel. **Refresh** re-pulls the live feeds and metrics.
+
+## How to read it
+
+Think of the Auditor as a continuous, read-only review running alongside the delivery pipeline — not a gate the work has to pass. Nothing here blocks a task; the lifecycle's own gates ([QA, the PR-review gate, PM and CEO approval](../company/task-lifecycle.md)) do that. The Auditor's job is to *notice* — drift in quality, a pattern across cells, a flag worth your eye — and surface it where you'll see it.
+
+!!! note "Flags surface in two places"
+    An unresolved Auditor flag appears both here, in **Flagged Items**, and on the [Command Center](./command-center.md) as an Auditor Alert. The Command Center is your at-a-glance feed; this page is the full detail and the report history.
+
+!!! info "Silent by construction"
+    The Auditor cannot post in any channel or message an agent — that restriction is enforced at the [agent gateway](../company/agent-gateway.md), not by convention. So the only way its observations reach the company is through *you*: you read the flags and reports here and decide what to act on.
+
+## Next
+
+→ [Communications & journals](./communications-and-journals.md) for the raw record the Auditor watches · [Metrics](./metrics.md) for velocity and cost analytics · [Org & roles](../company/org-and-roles.md) for where the Auditor sits in the company.

docs/panel/business.md

@@ -0,0 +1,45 @@
+# Business
+
+The Business page (`/business`) is the strategic layer above day-to-day delivery — the company's charter, its live scorecard against that charter, and the Board's pitches awaiting your decision. It's tabbed: **Goals**, **Secretary**, and **Pitches** (the active tab is in the URL as `?tab=`).
+
+For the *story* of how this layer drives work — how a north star shapes what the Board proposes and what the engines watch — see [The business workflow](../how-to/05-the-business-workflow.md). This page documents the panel surface.
+
+## Goals — the company charter
+
+The Goals tab is the CEO-owned charter. It's injected into every agent's briefing, so the whole company stays goal-aware. You edit it directly:
+
+| Field | What it is |
+|-------|-----------|
+| **North star** | The long-term vision in a sentence or two. |
+| **Objectives** | A list of objective rows (metric / target / status, add and remove freely). |
+| **Constraints** | Hard rules, one per line — e.g. "AGPL only", "No external data egress". |
+| **Operating policy** | Free-form policy keys the company operates under. |
+
+**Save charter** persists it; the card shows when it was last updated and by whom.
+
+### The Company Scorecard
+
+Below the charter sits the **Company Scorecard** — a live read of how the company is tracking against the charter, pulled from the cockpit summary. It groups into:
+
+- **Delivery** — tasks in flight, blocked, awaiting CEO, and completed in the last 30 days.
+- **Spend** — 30-day spend, projected monthly, and your **monthly budget cap** (`monthly_budget_cap_usd`). When a cap is set and spend exceeds it, the figure turns red with an "over budget" marker; with no cap it reads "No budget cap set."
+- **Speed** — median lead time against a target of under 24 hours.
+- **Objectives** — a placeholder section; per-objective tracking is not wired up yet.
+
+!!! info "The scorecard is the Cockpit, surfaced"
+    The scorecard reads the same company snapshot the **Cockpit** API exposes (`/api/cockpit/summary`): a read-only roll-up of delivery, spend against the budget cap, lead time, pending pitches, and strategy signals. There is no separate Cockpit page — its data shows up here on the scorecard and as the Strategy Signals panel on the [Command Center](./command-center.md).
+
+## Secretary
+
+The Secretary tab is your on-demand chief-of-staff chat. It reads company state and can run gated CEO directives. It is a human-only seat — the Secretary has no agent chat verbs and runs only when you talk to it. It's part of the company-in-a-box layer; see the [optional subsystems index](../optional/index.md).
+
+## Pitches
+
+The Pitches tab is where Board-originated proposals land for your decision. Each pitch is a card you can **Approve** or **Reject** (both prompt for a required note). Approving a pitch can, with pitch provisioning enabled, auto-provision a project from it.
+
+!!! warning "Pitches need provisioning enabled to act"
+    Pitch provisioning is a default-off subsystem. Flip `ROBOCO_PROVISIONING_ENABLED` on from [Settings → Feature Flags](./settings.md), and read [Pitch provisioning](../optional/pitch-provisioning.md) for what approving actually sets in motion. With it off, the tab still lists pitches but approval won't provision anything.
+
+## Next
+
+→ [The business workflow](../how-to/05-the-business-workflow.md) walks the whole strategic loop end to end · [Optional subsystems](../optional/index.md) covers the engines (strategy, research, provisioning) that this layer drives.

docs/panel/command-center.md

@@ -0,0 +1,63 @@
+# Command Center
+
+The Command Center at **`/overview`** is the panel's home page — the one screen you open to see whether the company is healthy and to act on the two things only you can decide. It pulls everything onto a single board: per-cell health, your decision queues, live metrics and cost, the auditor's open flags, current blockers, and a recent-activity feed. The notifications bell in the top header rides along on every page.
+
+## Team Health
+
+The top section shows a **health card per cell** — Backend, Frontend, UX/UI, and the management line — so you can read the state of the whole workforce at a glance before you scroll into anything detailed. It comes from the CEO-overview endpoint and refreshes with the rest of the board.
+
+A **Quick Actions** bar sits directly under Team Health so the common jumps (author a task, open the kanban, and so on) are reachable without scrolling.
+
+## The two CEO decision surfaces
+
+The Command Center is where the company hands work *up to you*. Two panels exist specifically for that.
+
+### CEO Approval Queue
+
+Every task that a Main PM escalates lands in **`awaiting_ceo_approval`** and appears here. For each one you can:
+
+- **Approve & merge** — the PR is merged and the task moves to `completed`.
+- **Request changes** — the task drops to `needs_revision` and goes back to the cell.
+- **Cancel** — the task is cancelled.
+
+These are the same actions you'd take from the [Task Detail page](./tasks-and-kanban.md#ceo-god-mode), surfaced here so the day's approvals are in one list. See [the task lifecycle](../company/task-lifecycle.md) for how a task reaches this state.
+
+### PR Review Queue
+
+This panel lists **inbound external / fork pull requests** RoboCo discovered on your repositories. For each one you decide:
+
+- **Supersede** — let an internal task take the change forward.
+- **Dismiss** — close it out.
+
+!!! note "Hidden when empty"
+    The PR Review Queue only renders when there's something to decide. An empty board means no external PRs are waiting — not that the feature is off. (Inbound external/internal PR review is itself flag-gated; see [PR review](../optional/pr-review.md).)
+
+## Metrics, alerts, and usage
+
+A three-up row gives you the operational pulse:
+
+- **Key Metrics** — the headline counts from the overview endpoint.
+- **Auditor Alerts** — currently *unresolved* flags raised by the [Auditor](./auditor.md). This is a read-only nudge; the full feed lives on the Auditor page.
+- **Usage overview** — a live token/cost summary. It updates off the `USAGE_SNAPSHOT` stream on `/ws/system` and falls back to polling when that socket is down. The full breakdown — 24h cost, monthly projection, cache savings — is on the [Metrics page](./metrics.md).
+
+### Strategy Signals
+
+Next to the Approval Queue sits a **Strategy Signals** panel. It surfaces charter/strategy-drift notices from the strategy engine, which is **off by default** and armed by `ROBOCO_STRATEGY_ENGINE_ENABLED` (toggled from [Settings → Feature Flags](./settings.md)). With the engine off, the panel simply has nothing to show. See [the strategy engine](../optional/strategy-engine.md).
+
+## Blockers and activity
+
+The bottom row pairs:
+
+- **Active Blockers** — tasks currently sitting in `blocked`, so a stuck dependency doesn't go unnoticed.
+- **Recent Activity** — a rolling feed of what the company did in the last 24 hours.
+
+## Notifications bell
+
+The bell in the top **Header** (present on every dashboard page, not just here) is your inbox for formal notifications — the acknowledgement-required signals PMs and the Board send. Clicking through takes you to the full [Notifications inbox](./communications-and-journals.md#notifications) at `/notifications`, where you can mark items read, acknowledge those that need it, and clear the unread count.
+
+!!! tip "Backend down?"
+    If the orchestrator isn't running, the Command Center (like every page) renders a clear offline state with a **Retry** — it detects a refused connection rather than spinning. Bring the stack up and retry; see [common issues](../troubleshooting/common-issues.md).
+
+## Next
+
+→ [Tasks & Kanban](./tasks-and-kanban.md) to act on individual work, or [Agents & work sessions](./agents-and-work-sessions.md) to watch the workforce run.

docs/panel/communications-and-journals.md

@@ -0,0 +1,39 @@
+# Communications, Journals & Notifications
+
+Three pages are the company's audit trail of *what was said, what was learned, and what needs your attention.* Communications is the live message stream between agents. Journals are each agent's private reflections. Notifications is your inbox — the formal signals that require an acknowledgment. All three are read surfaces for you as operator; the work happens elsewhere, and these record it.
+
+## Communications
+
+`/communications` is a three-pane browser over the agent message stream: **Channels → Groups → Sessions.**
+
+- **Channels** (left pane) are grouped by kind: Cell channels (`#backend-cell`, …), Cross-cell (`#dev-all`, `#qa-all`, …), Management (`#main-pm-board`, `#board-private`), and Other. A lock icon marks a private channel; a hash marks a public one.
+- **Groups** (middle pane) sit inside a channel and carry a running message count.
+- **Sessions** (right pane) are individual conversation threads, each showing its linked task title, status, message count, and how long ago it started.
+
+Open a session to read its full transcript at `/communications/{session}`. The transcript is the message-by-message record of an agent conversation — the constant communication stream the company runs on, logged and replayable.
+
+!!! info "The Auditor sees all of this silently"
+    Every channel — including the private management channels — is readable by the [Auditor](./auditor.md) with no participation. Communication is observed, not gated.
+
+## Journals
+
+`/journals` is the per-agent reflection log. Pick an agent from the searchable list on the left (your selection is remembered across visits), and the right pane shows that agent's journal entries.
+
+Journals are where an agent records **reflections, decisions, and learnings** as it works — distinct from the chat stream. Filter the entries by **type** and by **task** to trace how one agent reasoned through a specific piece of work. A single entry opens at `/journals/{entry}`.
+
+This is the closest you get to an agent's "why." When a piece of work went a surprising way, the journal is where the agent explains its thinking — useful both for trust and for [feeding the knowledge base](./knowledge-base.md), which indexes journals as a retrievable source.
+
+## Notifications
+
+`/notifications` is your acknowledgment-required inbox. Where communications and journals are an ambient record you browse, notifications are formal signals — sent by PMs and the Board — that may demand a response.
+
+- Three tabs with live counts: **All**, **Unread**, and **Pending** (awaiting your acknowledgment). The page opens on Unread, the most actionable view.
+- Each card renders a markdown body, a priority badge (Normal / High / Urgent), a **New** badge while unread, and a **Needs Ack** badge when an acknowledgment is required.
+- Actions per card: **Mark Read** and, where required, **Acknowledge**. **Mark All Read** clears the unread pile in one click.
+
+!!! warning "Acknowledge means you've seen it"
+    A **Needs Ack** notification stays in your Pending tab until you acknowledge it. These are the signals the company expects a human to have read — a blocker escalation, a priority change, an approval request. Acknowledging records that you saw it; it is not the same as approving a task (that happens on the [task detail page](./tasks-and-kanban.md) or the Command Center approval queue).
+
+## Next
+
+→ [Tasks & Kanban](./tasks-and-kanban.md) for the work itself · [Agents & work sessions](./agents-and-work-sessions.md) to watch agents live · [Communication model](../company/org-and-roles.md) for the channel structure.

docs/panel/git.md

@@ -0,0 +1,48 @@
+# Git
+
+The **Git** page (`/git`) is a real working git client over any of your registered projects. You pick a project (and optionally a task), browse the live state of its workspace — status, branches, commit log, and diffs — and run git operations directly from the panel. It's how you inspect what the agents are doing in git, and step in by hand when you need to.
+
+## Picking a project
+
+Choose a project from the dropdown to load its repository. The selection is held in the URL, so a given project's git view is shareable and back-button-safe. Until you pick one, the page prompts you to choose. You can also scope to a specific task.
+
+!!! note "The orchestrator must be up"
+    Git operations run server-side against the agent workspaces, so this page needs the orchestrator running. With the backend down it shows an offline state with a retry rather than failing silently.
+
+## Browsing the repository
+
+Once a project is loaded you get live, refreshable views:
+
+- **Status** — staged and unstaged changes in the workspace.
+- **Branches** — the branch list (including remotes).
+- **Log** — the recent commit history.
+- **Diff** — the staged/unstaged diff viewer for the working tree.
+
+A **Refresh** re-pulls status, log, and branches together.
+
+## Operations you can run
+
+The page wires up the full set of git operations against the selected project:
+
+| Operation | What it does |
+|-----------|--------------|
+| **Commit** | commit staged changes (returns the new commit hash) |
+| **Push** | push the current branch to the remote |
+| **Create branch** | cut a new hierarchical branch for a task (by branch type) |
+| **Checkout** | switch to an existing branch |
+| **Create PR** | open a pull request (returns the PR number) |
+| **Merge PR** | merge a PR into its target branch |
+| **Pull** | pull the current branch from the remote |
+| **Fetch** | fetch from the remote |
+| **Rebase** | rebase the current branch onto a target branch |
+
+Each action confirms with a toast on success (or a clear failure message) and refreshes the relevant view.
+
+!!! warning "This is the live repository"
+    These operations act on the real workspace clone and your real remote — a merge here merges for real. The same branch/PR/merge actions are also available, task-scoped, from the [Task Detail page](./tasks-and-kanban.md#ceo-god-mode), where they run as agent id `ceo`. Remember that **only the CEO merges to master**; see [the merge model](../company/merge-model.md).
+
+Git authentication uses the project's encrypted GitHub token, which you set when you [register the project](../get-started/first-project.md#the-github-token) — the panel never holds or shows the PAT.
+
+## Next
+
+→ [Agents & work sessions](./agents-and-work-sessions.md) to tie branches back to the agents that cut them, or [Projects & products](./projects-and-products.md) to manage the repositories themselves.

docs/panel/index.md

@@ -0,0 +1,22 @@
+# Operating the Panel
+
+The control panel is your one window into the company — every task, agent, message, journal, and pull request is live in front of you, served at `http://localhost:3000`. This section is a reference: one short page per area, describing what you do there and what it shows.
+
+<div class="grid cards" markdown>
+
+-   **[Command Center](command-center.md)** — the home dashboard: cell health, your approval queues, live metrics, and the notifications inbox.
+-   **[Tasks & Kanban](tasks-and-kanban.md)** — the task table, the task detail page (with CEO god-mode), and the dev board.
+-   **[Agents & Work Sessions](agents-and-work-sessions.md)** — the live workforce and the branch/PR ledger.
+-   **[Projects & Products](projects-and-products.md)** — the repositories the company works on, and multi-repo products.
+-   **[Git](git.md)** — browse live git state and run operations per project.
+-   **[Knowledge Base](knowledge-base.md)** — the in-house RAG: search, ask, and reindex.
+-   **[Communications & Journals](communications-and-journals.md)** — the live message stream, agent journals, and your notifications.
+-   **[Auditor](auditor.md)** — read-only quality oversight across the whole company.
+-   **[Business](business.md)** — the charter, the Scorecard, the Cockpit, and pitches.
+-   **[Metrics](metrics.md)** — delivery performance and the token-usage dashboard.
+-   **[Settings](settings.md)** — feature flags, transcript retention, and configuration.
+
+</div>
+
+!!! tip "Provider configuration lives in its own section"
+    Picking which models power the agents is on the **Settings → AI Providers** page — see [Choosing & Running Models](../models/index.md).

docs/panel/knowledge-base.md

@@ -0,0 +1,43 @@
+# Knowledge Base
+
+The **Knowledge Base** page (`/knowledge-base`) is your window into RoboCo's in-house RAG — the pgvector-backed retrieval engine the agents use to find prior context. From here you search the indexes, ask synthesized questions and get answers with citations, talk to the mentor, browse by category, and (in the Admin tab) reindex or clear the indexes. The page is organized into five tabs, with the active tab held in the URL.
+
+## Search
+
+Free-text search across the indexes, with an optional filter to scope the query to specific index types. This is the raw retrieval view — it returns the matching chunks so you can see exactly what the agents would find.
+
+## Ask
+
+The RAG question-and-answer surface. You ask a question in natural language and get a **synthesized answer with citations** back to the source documents, rather than a raw chunk list. This is the layer that turns the indexes into an answer.
+
+## Mentor
+
+A mentor chat — the same `roboco_ask_mentor` capability the agents reach through their gateway, exposed to you conversationally for asking about the codebase and accumulated knowledge.
+
+## Browse
+
+Browse the indexed content **by category** rather than by query, when you want to see what's in an index instead of searching for something specific.
+
+## Admin
+
+The control surface for the indexes themselves. The KB is split into several index types — Documentation, Conversations, Agent Journals, Error Solutions, Standards, Decisions, Code Reviews, and Learnings — and the Admin tab shows **per-index stats** and lets you maintain them:
+
+| Action | Effect |
+|--------|--------|
+| **Reindex all** | rebuild every index from source (force) |
+| **Refresh** *(per index)* | re-pull and re-embed that one index |
+| **Delete** *(per index)* | clear that index's contents |
+
+!!! warning "Delete and reindex are operational actions"
+    Clearing an index removes its embeddings, and a full reindex re-embeds everything from scratch — both take real work and real Ollama time. Delete is guarded behind a confirmation dialog. Treat the Admin tab as a maintenance surface, not a daily one.
+
+## It depends on Ollama
+
+The whole page — search, ask, mentor, and especially reindexing — runs on the embedding model served by **Ollama** (`qwen3-embedding:0.6b`). If Ollama isn't healthy, queries return nothing useful and reindexing can't embed.
+
+!!! info "If results come back empty"
+    A common first-run symptom is an empty or failing KB while Ollama is still pulling models, or when the embedding endpoint is unreachable. Check that the `ollama` service is up and the model is pulled — see [common issues](../troubleshooting/common-issues.md). The RAG engine and its configuration are covered under [deployment](../deploy/deployment.md).
+
+## Next
+
+→ [Communications & journals](./communications-and-journals.md) — the raw conversations and journals that feed several of these indexes — or [the Auditor](./auditor.md) for quality oversight.

docs/panel/metrics.md

@@ -0,0 +1,37 @@
+# Metrics
+
+The Metrics page (`/metrics`) is where you watch the company's throughput and its spend. Two tabs: **Performance** and **Token Usage** (the active tab is in the URL as `?tab=`).
+
+## Performance
+
+The Performance tab is a snapshot of velocity and pipeline health, computed from the live task list and the orchestrator's agent status.
+
+- **Velocity** — completed today, completed this rolling 7 days, total completed all-time, and a completion rate across all tasks.
+- **Task Status** — counts of tasks that are pending, in progress, blocked, awaiting QA, and completed.
+- **Agent Status** — how many agents are running, idle, waiting (need input), or in error.
+- **Team Health** — one card per cell with a health score and its active / blocked / done breakdown. The score is a simple read on blockers: more blocked tasks pulls a cell's health down. A healthy cell sits near 100%; blockers visibly degrade it, so a cell sliding toward red is the signal to look at its [blockers](./command-center.md).
+
+## Token Usage
+
+The Token Usage tab is the cost dashboard, scoped to the last 24 hours unless a panel says otherwise.
+
+- **Summary cards** — tokens in, tokens out, total tokens, total cost over 24h, the trend versus the prior period, and dollars saved by prompt caching.
+- **Time series + model donut** — usage over time, and the split across models.
+- **Per-agent and per-team bars** — who and which cell is spending.
+- **Monthly projection** — projected monthly cost from a rolling-average daily run rate.
+- **Cache efficiency** — cache hit rate and the cost it saved.
+- **Sessions table** — the recent agent spawn sessions behind the numbers.
+
+!!! tip "These panels update live"
+    The token panels subscribe to a live usage stream over `/ws/system` and update in place as agents spend, falling back to periodic HTTP polling when the socket is down. You don't need to refresh to watch cost accrue.
+
+### Where the dollar figures come from
+
+Cost is derived from per-session token counts using provider-aware pricing — and local / Ollama usage is intentionally priced at **$0**, so a self-hosted or Ollama-routed workforce shows tokens but no dollars. The full cost model, the budget cap, and where each number originates are documented in [Cost & usage](../operations/cost-and-usage.md); this page only shows the numbers.
+
+!!! note "Spend against budget lives on the scorecard"
+    Metrics shows raw usage and projection. Your **monthly budget cap** and whether you're over it appear on the Company Scorecard in [Business](./business.md), not here.
+
+## Next
+
+→ [Cost & usage](../operations/cost-and-usage.md) for the pricing model and budget cap · [Health & metrics](../operations/health-and-metrics.md) for operational monitoring · [Command Center](./command-center.md) for the at-a-glance view.

docs/panel/projects-and-products.md

@@ -0,0 +1,45 @@
+# Projects & Products
+
+Two pages define *what* the company builds and *who* builds it. **Projects** (`/projects`) are the git repositories RoboCo is allowed to touch. **Products** (`/products`) group several repositories into one shipping unit and route each delivery cell to the repo it owns. You only need Products when a single thing you ship spans more than one cell.
+
+## Projects
+
+A project is one git repository plus the configuration that tells the company how to build and check it. The Projects page is where you register, search, and edit them.
+
+- **New** opens the create dialog — name, slug, git URL, GitHub token, assigned cell, default branch, and optional per-project gate commands.
+- The list supports **search**, a **cell filter**, and a **show-inactive** toggle so retired repos stay out of the way without being deleted.
+- **Edit** reopens the same form to rotate the token, change the gate commands, or flip the assigned cell. The edit dialog also hosts the per-project **Conventions** tab — see [Architectural conventions](../optional/conventions.md).
+
+The field-by-field detail — what each field means, the token scopes you need, the encryption guarantee, and the default-branch gotcha — lives in [Register your first project](../get-started/first-project.md). Read that page before you create a repo; this page doesn't repeat it.
+
+!!! tip "Set the gate commands"
+    The single biggest lever on output quality is pointing a project's `quality_command` and per-step commands at the *real* checks you'd run locally. The company then gates itself the way you would. Details in [Gate commands](../get-started/first-project.md#gate-commands).
+
+## Products
+
+A **product** maps each delivery cell to the project (repository) it builds for that product. Use it when one deliverable spans multiple cells — a Backend repo and a Frontend repo, say, that ship together.
+
+The page is a straightforward table plus a **New** button. A product carries a name and a set of cell-to-project assignments: Backend → repo A, Frontend → repo B, UX/UI → repo C. A cell with no assignment simply doesn't participate in that product.
+
+### Why the mapping matters
+
+When the Main PM decomposes a product into work and fans it out to the cells, the branch and PR structure follows the mapping. **The Main PM cuts one integration branch per distinct repository in the product.** A cell's work lands on its repo's integration branch; the cell PM opens the cell→root PR within that repo, and the Main PM opens the root→master PR per repo. Two cells assigned the *same* repo share one integration branch; two cells on *different* repos get one each.
+
+```mermaid
+flowchart LR
+    P[Product] --> B[Backend cell → repo A]
+    P --> F[Frontend cell → repo B]
+    A1[repo A: integration branch] --> MA[root→master PR · repo A]
+    B1[repo B: integration branch] --> MB[root→master PR · repo B]
+    B --> A1
+    F --> B1
+```
+
+!!! note "Single-repo work needs no product"
+    If everything you're shipping lives in one repo, you don't need a product at all — register the project and hand the Task Assistant or the Create Task dialog that project directly. Products exist purely to coordinate a multi-repo, multi-cell deliverable.
+
+For how branches assemble and merge once the cells are building, see the [merge model](../company/merge-model.md). For the lifecycle a single task moves through, see the [task lifecycle](../company/task-lifecycle.md).
+
+## Next
+
+→ [Tasks & Kanban](./tasks-and-kanban.md) to author and track the work · [Git](./git.md) to watch the branches and PRs land.

docs/panel/settings.md

@@ -0,0 +1,47 @@
+# Settings
+
+The Settings page (`/settings`) holds two things that genuinely change how the company runs — the **Feature Flags** card and **Transcript Retention** — alongside a handful of cosmetic preferences and read-only connection info. Read the warning below before you trust a switch on this page.
+
+## Feature Flags
+
+The Feature Flags card is the operator's master switchboard for the optional, default-off subsystems. Instead of hand-editing environment variables, you flip a switch here. Each row shows the subsystem's label, a one-line description of what it gates, and a toggle.
+
+| Flag | Gates |
+|------|-------|
+| External PR review | Discovering and reviewing inbound external/fork PRs. |
+| Internal PR review | The read-only safety reviewer on internal branch PRs. |
+| Web research | Letting the Board and PMs run web research. |
+| Strategy engine | Generating and maintaining strategy artifacts (drives the Command Center's Strategy Signals). |
+| Self-healing | Watching RoboCo's own CI and notifying you on a regression. |
+| Self-heal originate | Also opening a *pending* fix task for a regression — needs self-healing on, and the task waits for your approval. |
+| Pitch provisioning | Auto-provisioning projects from approved [pitches](./business.md). |
+| Toolchain match | Provisioning each agent workspace with the target project's own Python and blocking gates when its tests can't run. |
+| Conventions | Enforcing the per-project architectural standard (`.roboco/conventions.yml`). |
+| RAG auto-update | Keeping the [knowledge base](./knowledge-base.md) index refreshed automatically. |
+| Transcript prune | Running the background sweep that prunes old transcripts. |
+
+Each subsystem has a full page in the [optional subsystems section](../optional/index.md) — what it does, the exact `ROBOCO_*` env var behind it, and what turning it on changes.
+
+!!! warning "Flags take effect on the next backend restart"
+    Toggling a flag persists the choice server-side, but it does **not** hot-reload — the backend reads it at startup. The toast says as much: "takes effect on next restart." A flag you've never set falls back to its environment / config default. So: flip it here, then restart the orchestrator for it to take hold.
+
+## Transcript Retention
+
+The Transcript Retention card sets how many days agent transcripts are kept before the prune sweep removes them (default 14). This is a real, server-persisted setting. It only ever prunes *agent-owned* transcripts — never your own Claude sessions. The sweep itself is gated by the **Transcript prune** feature flag above.
+
+## Connection Info (read-only)
+
+This card displays the API and WebSocket base URLs the panel is using (`NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_WS_URL`) — relative by default so nginx dispatches them on a single origin. It's informational; you can't edit it here.
+
+## The cosmetic and mock-state controls
+
+!!! danger "Some switches on this page do nothing"
+    The page also carries **Appearance** (theme, collapsed sidebar — these work and persist locally), a **User Info** card, and a **Data & Refresh** + **Notifications** block. The Auto Refresh, Refresh Interval, Enable Notifications, and Sound Alerts controls — and the page-level **Save Settings** button — are **local component state only.** They are *not* persisted or wired to anything; Save just shows a success toast. Don't rely on them to change runtime behavior. Only **Feature Flags**, **Transcript Retention**, and the **Appearance** preferences actually do something.
+
+## AI provider configuration lives elsewhere
+
+Choosing which model and provider backs each agent is **not** on this page — it's the **AI Providers** page (`/settings/ai-providers`), linked from the sidebar footer. There you set the global routing mode (Anthropic / Grok / Ollama / self-hosted), or pin individual agents in Mix mode, and store the encrypted provider keys. See [Provider routing](../models/provider-routing.md).
+
+## Next
+
+→ [Optional subsystems](../optional/index.md) for every feature flag in detail · [Provider routing](../models/provider-routing.md) for the AI Providers page · [Environment reference](../deploy/env-reference.md) for the `ROBOCO_*` variables behind the flags.

docs/panel/tasks-and-kanban.md

@@ -0,0 +1,59 @@
+# Tasks & Kanban
+
+Tasks are the unit of work in RoboCo — nothing happens without one. The panel gives you three views of them: the **Tasks table** (`/tasks`) for searching and filtering everything, the **Task Detail** page (`/tasks/[id]`) for the full state of one task plus your god-mode overrides, and the **Dev Kanban** (`/kanban`) for a pipeline-style board of where work is in flight.
+
+## The Tasks table (`/tasks`)
+
+The master list of every task. It gives you full-text search and multi-select filters across **status, team, task type, project, and product**, with sortable, paginated, expandable rows. All of that filter/sort/page state lives in the URL query string, so a filtered view is shareable and survives the back button.
+
+The **Create Task** dialog lets you author a task by hand — title, acceptance criteria, project/product, type. If you'd rather describe a rough idea and have an agent read your code and draft a properly-formed task with acceptance criteria, use the conversational [Task Assistant](../get-started/first-task.md) at `/prompter` instead.
+
+## Task Detail (`/tasks/[id]`)
+
+The heaviest operator surface in the panel. The header carries the task's metadata; the body is tabbed (notes, commits, acceptance criteria, and more).
+
+### Clickable branch and PR
+
+When a task has a branch or a pull request, the git badges are **live links** into your repository's web host — the branch jumps to `…/tree/<branch>` and the PR to `…/pull/<n>`, derived from the project's git URL. If the URL can't be parsed into a web link, it falls back to a plain label rather than a broken link, so you always see *something* useful.
+
+### Per-role note sections
+
+The **Notes** tab carries a separate, editable section for each role that touches a task, so the handoff trail is structured rather than a single free-text blob:
+
+| Section | Written by |
+|---------|-----------|
+| **Developer Notes** | the dev (`dev_notes`) |
+| **Documenter Notes** | the documenter (`doc_notes`) |
+| **QA Notes** | QA (`qa_notes`) — with a pass/fail verdict pill from `qa_verified` |
+| **PR Reviewer Notes** | the PR reviewer (`pr_reviewer_notes`) |
+| **Auditor Notes** | the Auditor (`auditor_notes`) |
+
+Empty sections still render so you can see what's expected — and add a note yourself if you need to.
+
+### CEO god-mode { #ceo-god-mode }
+
+The lifecycle is normally enforced role-by-role at the [gateway](../company/agent-gateway.md), but *you* are the CEO and can override any of it from this page. The action set covers the whole lifecycle: claim, start, pause, resume, block, unblock, verify, submit-qa, pass-qa / fail-qa, docs-complete, submit-pm-review, approve-and-merge, escalate-to-ceo, ceo-approve / ceo-reject, and cancel. You can also run git directly — **create a branch, create a PR, merge a PR** — and those operations are performed as agent id **`ceo`**.
+
+This page also exposes **Approve & Start** for a board-reviewed pending task and **Re-draft with board feedback**, which routes back to the Task Assistant (`/prompter?redraft=`).
+
+!!! warning "Every override forces an audit note"
+    The state-changing actions — pass/fail QA, approvals, rejections, cancellation — open a dialog that requires you to type a note before they go through. That note is written permanently to the task's history. God-mode is powerful by design; it is never silent.
+
+See [the task lifecycle](../company/task-lifecycle.md) for what each transition means and [the merge model](../company/merge-model.md) for how PRs flow up to master.
+
+## Dev Kanban (`/kanban`)
+
+A swim-lane board of the delivery pipeline, switched with the `?view=` query param into four boards:
+
+| View | `?view=` | Shows |
+|------|----------|-------|
+| **Developer** | `dev` | tasks in the development states |
+| **QA** | `qa` | tasks awaiting / in QA review |
+| **PR Review** | `pr-review` | assembled PRs at the in-path review gate |
+| **PM** | `pm` | tasks awaiting PM review and merge |
+
+Each board is a read-at-a-glance view of where work sits in the [lifecycle](../company/task-lifecycle.md). Switching tabs updates the URL, so a specific board is shareable.
+
+## Next
+
+→ [Agents & work sessions](./agents-and-work-sessions.md) to see who's working these tasks, or [Git](./git.md) to inspect the branches and PRs they produce.