docs: add an illustrated how-to walkthrough

A step-by-step guide to the workflow — give the Board a task, approve,
the cells build/review/document, the Main PM opens the final PR — each
step illustrated with a panel screenshot. The screenshots live under the
tracked docs/images/ (the source logos/ tree is gitignored, so embedding
from there would render broken on the public repo).

docs/how-to.md

@@ -0,0 +1,138 @@
+# How RoboCo works
+
+RoboCo is a virtual software company — 18 AI agents and one human: you. You don't
+micromanage it; you run it like a CEO. Drop work at the top, and the
+organization carries it all the way through planning, building, review, and
+documentation, then brings it back to your desk for the final word. This page
+follows a single piece of work through that whole journey, with screenshots from
+the control panel.
+
+> The panel is your one window into the company. Every task, agent, message,
+> journal, and pull request is live in front of you.
+
+![The RoboCo Command Center: per-cell health, the CEO approval queue, live metrics, auditor alerts, and recent activity.](images/overview_dashboard.png)
+
+*The **Command Center** — a glance tells you how each cell is doing, what's
+waiting on your approval, how fast work is moving, and what just happened.*
+
+---
+
+## The shape of the company
+
+Work in RoboCo is always a **task**, and tasks nest into a tree that mirrors the
+org itself:
+
+```
+CEO (you, the human)
+ └── Board ── Product Owner · Head of Marketing · Auditor (silent)
+      └── Main PM (coordinates the cells)
+           ├── UX/UI cell    ── PM · Dev · QA · Documenter
+           ├── Frontend cell ── PM · 2 Devs · QA · Documenter
+           └── Backend cell  ── PM · 2 Devs · QA · Documenter
+```
+
+In practice, one feature becomes a small tree of work — a parent task at the top,
+a branch for each cell underneath, every node carrying its own status, git
+branch, and pull request:
+
+![The task tree for a feature: a Main PM parent task fanned out to UX/UI, Frontend, and Backend cell tasks, each with a live status and a GitHub branch.](images/run.png)
+
+*A feature in motion. The parent task fans out to the UX/UI, Frontend, and
+Backend cells, and each child moves through its own lifecycle — in progress,
+awaiting review, completed — on its own branch.*
+
+---
+
+## Following a task through the company
+
+### 1 · It starts with you
+
+You describe what you want — a feature, a fix, an entire product — and hand it to
+the **Board**. Their job is to pin it down: the Product Owner and Head of
+Marketing turn a loose request into a concrete spec, with the acceptance criteria
+that define what "finished" actually means. The Auditor watches the whole time
+but never interferes.
+
+![A Board review session: the Product Owner writing out requirements and acceptance criteria for a task.](images/chat_session.png)
+
+*The Product Owner working a task over — pinning down the requirements and the
+must-haves before anyone writes a line of code.*
+
+### 2 · Nothing moves without your green light
+
+The Board hands the reviewed task back to you as a **notification** and waits.
+You make one call: send it forward, or send it back. Approve it, and the **Main
+PM** picks it up, splits it across the cells, and sets them running.
+
+![The board-review notification waiting on the CEO's decision to start the work or send it back.](images/notifications.png)
+
+*The Board's verdict lands in your notifications and pauses there. A single
+approval is what turns the whole company on.*
+
+<!-- TODO: add the screenshot of the green "Approve & Start" button on the task. -->
+
+### 3 · The cells take over
+
+Underneath the Main PM are three cells — **UX/UI, Frontend, Backend** — each a
+small team with its own PM. Those PMs run their cells like engineering managers:
+parcelling out the work, clearing blockers, and stepping in when something
+stalls. UX/UI usually leads and sets the contracts; Frontend and Backend build
+against them.
+
+![The Dev Kanban: cards moving from Backlog through Ready, Assigned, In Progress, and Blocked.](images/kanban.png)
+
+*A cell at work, seen as a board — tasks flow from backlog to done, and the
+role tabs let you watch it from the developer's, QA's, or PM's seat.*
+
+### 4 · The work gets done — and checked
+
+This is where it's actually built. Developers write the code and open pull
+requests from their own branches. QA doesn't rubber-stamp — it reads the real
+diff and decides whether the work ships or comes back for another pass.
+Documenters write down what was built so the next agent (and you) aren't starting
+cold. None of it happens in the dark: agents narrate their reasoning as they go,
+and each keeps a running journal of what it learned and why it chose what it
+chose.
+
+![Agent Journals: per-agent reflections, decision logs, and learnings.](images/journaling.png)
+
+*Every agent keeps a journal — reflections, decisions, and lessons. Between that
+and the Documenters, there's a paper trail for everything the company does.*
+
+### 5 · The work converges
+
+Once a cell's piece is green and documented, its PM folds those branches up into
+the Main PM's integration branch. Three independent streams of work come back
+together into one. Each task brings its branch, pull request, commits, and docs
+along with it:
+
+![A completed task showing its branch, pull request, commits, and documentation.](images/task_details.png)
+
+*One finished unit — branch, pull request, commits, and docs all attached. This
+is the thing that travels up the merge chain.*
+
+<!-- TODO: add the Git view showing each cell's PR merging into the Main PM branch. -->
+
+### 6 · The last call is yours
+
+With everything merged, the Main PM opens the **final pull request** and lets you
+know it's ready. The decision comes back to where it started — with you. Merge it
+and it ships, or send it around for another lap. You're the only one who ever
+touches `master`, and anything waiting on you sits in the **CEO Approval Queue**
+on the Command Center until you act.
+
+<!-- TODO: add the final "done" notification + the approve / merge button. -->
+
+---
+
+## And round it goes
+
+You handed the company a task; it scoped it, built it, reviewed it, documented
+it, and merged it; and it landed back on your desk for sign-off. That's one
+complete pass — and you can keep as many running at once, across as many
+projects, as you want.
+
+---
+
+*RoboCo is early-stage, work-in-progress software (v0) — expect rough edges. The
+[README](../README.md) covers setup, architecture, and the security model.*