Explanation

Understand why. The conceptual spine — architecture, rationale, and the trade-offs behind BoB’s design. (Back to docs home.)

Note	Explains
The bob CLI	What bob is, why BoB has one verb instead of a bin/ full of names, and how nouns and verbs map to the entrypoints they replace — the table behind the router, the help it generates, and how a command is added.
BoB Control	What BoB Control is: one frame on the dashboard server whose navigation is Now, Projects, Fleet and Costs, how each address picks a screen, and why the frame stores nothing.
The Minimal BOB_HOME Core	The #1132 demotion audit — the invariance test, keep/demote classification of every universal item, dependency floor, and context-tax measurement.
BoB Identity	What "BoB" is — the identity definition behind the tooling.
bob viz	What the fleet console is, what feeds it (one reader, published snapshots, the fleet feed over the dashboard’s SSE stream), what each region means, and the honesty rules that keep stale remote state from reading as live.
Client Farms	What a client farm is — a BoB farm in a client-owned cloud account, built from the client’s own declaration — who owns which layer of it, why the host-provider tooling and the farm data live apart, and how a client farm is built, updated and rebuilt (#2216, decision #4219).
Coming Back to a BoB Project	Why the first hour back on a project is a fixed routine — machine, catch-up, your own queue, the plan, the records, memory, rituals and the farm — and how the evidence ranks into one next step.
The Decomposition Machine	Why capability decomposition is BoB’s second state machine, what its six gates reuse, what it shares with warp-drive and what it deliberately leaves out (#2973).
DESIGN.md in BoB	How Google Labs’ DESIGN.md format fits BoB provisioning — placement, opt-in, the design-skill family, Stitch as upstream.
The bob do Machine	Why unstructured work gets a state machine, why the framing gate and the discarded terminal are the whole point, and how bob do relates to warp-drive and bob decompose (#2974).
Doc-Bootstrap	Why doc-bootstrap is shaped this way — one-target/three-verbs, the convergence + fixpoint invariants, tiers, code-grounding.
The Farm	What the farm is — a machine that runs one bounded tick a night under a lock — why it takes only the work you delegate, how you reach it without moving a secret, and how you read what it did the next morning.
Launchpad Design	The Launchpad’s design language: the colour tokens for each theme, the type scale, spacing, depth, motion rules and what each liveness colour means, and the limits the page keeps (no requests, no framework, 60 KB of inline code).
Operators	What an operator is, what its repo declares (identity, forge, people, routes, upstream, secret names), what stays in BOB_SOURCE and BOB_HOME, and how the operator repo is resolved — the #2267 contract behind decision #2266.
Orchestration (section)	The single home for orchestration — the handbook (narrative) and the orchestrator (recommendation engine).
Prime Directive	Declarative, version-controlled, idempotent, one-owner-per-fact — and every conclusion on evidence and merit.
A Week in the Life of a BoB Product	Why BoB puts a vision, capabilities, requirements, a groom and a flight plan above the loop — one small product’s week, from the vision doc to a tagged release.
Project Monitor Exposure Posture	Why the Project Monitor is tailnet-only — what it would take to justify a public URL, and the bind guarantees that enforce the decision in code.
Why BoB Holds Rituals	Why recurring reviews are declared in the manifest, dated from their own issues, prepared by the farm and closed only with durable outputs — one retrospective on a small product, from coming due to closed.
How BoB surfaces its own capabilities	Why BoB teaches itself to its owner from evidence rather than a hand-written list — the ledger, the tour seed, the unknown / parked / in-use grades, and the rule that non-usage is never evidence of uselessness.
Skill evolution: traces, a wiki and skills	Why BoB keeps raw traces, a persistent wiki and executable skills as three separate artifacts — the WikiSkill paper checked against its PDF, where each BoB surface sits, where the wiki lives, and the maintainer and proposer contracts the skill-evolution requirements implement (#1971).
The Surfaces BoB Talks On	Why BoB reaches its operator on six surfaces — terminal, tmux, the desktop app, Telegram, claude.ai remote control and iBoB — what each one carries, and how to pick one for the situation you are in.
The task work type	What a task is, why maintenance work gets its own work type beside req and bug, where it sits outside the cap→req tree, and how it rides the same warp-drive loop with a Verification checklist as its definition of done.
Warp-drive contract	Why the state machine’s phases, transitions and reasoning budget are frozen behind a fixture — the #2042 moratorium, what it pins, how a change lands, and what the status surfaces name.
Warp-drive internals	How the warp-drive loop works inside — phases and overlays, hooks and breakers, scope and discovery, the preflight gate, the warp monitor, streams, segmentation, re-validation and configuration.
Watching BoB Work	Why BoB has a view for each layer — the run, the project, the machine and the fleet — what each one reads, and which view to open when a run is stuck, a machine has drifted, the farm is quiet or GitHub is down.
A Day in the Life of a BoB Workday	One realistic developer day end-to-end — bug fix, feature, docs, parallel, farm — narrated around the seams between commands, with L1/L3 variants.
Writing for the web	Why BoB’s todos, reports and briefings follow the web-read rules WS-4 to WS-10 — what Krug, Nielsen Norman Group and Redish found, how strong that evidence is, where critics qualified it, and what BoB does about each.

See also the product Vision (the living strategy doc, kept at the docs/ root by convention).