xBot documentation

Written before the code, so that the code has something to be measured against. Where a document and the implementation disagree, one of them is wrong and it is worth finding out which — see the last section of CLAUDE.md.

Reading order

Read ADR-0007 first. It re-orders the project after the engine was actually run, and several documents here were written before that and are annotated rather than rewritten.

Then 01 → 03 in order. They establish the problem, the shape of the answer, and the constraints everything else works around. After that, read by area.

Foundations

1. Vision — the product, the user, the promise, the non-goals.
2. Architecture — every service, every port, how a message becomes an action.
3. The OpenBot fork — what we inherit for free, what is actively wrong for our purposes, and how much work each fix is. The most important document here.

Engine

4. Model providers — the router that turns a process-wide environment variable into per-agent choice, and how each vendor plugs in.
5. Container runtime — Docker, Colima, or Apple's Containerization framework, and the state machine the app drives it with.
6. Security — the Keychain, the credential vault, isolation, and the things that must never be written to disk.

Client

5. The Mac app — Swift packages, module boundaries, state ownership.
6. Onboarding — first run, screen by screen, including every failure.
7. Design system — tokens, typography, motion, materials. Derived from Apple's Designing Fluid Interfaces and the eight design principles.
8. UI specification — the rail, the conversation, the panel, settings.

Delivery

11. Packaging and updates — DMG, Developer ID, notarization, Sparkle.
12. Roadmap — milestones, and what "done" means for each.
13. Engine environment mapping — how app settings become the container's env vars.

Decisions

Architecture Decision Records. Each one exists because the decision looks wrong without its context.

#	Decision
0001	Replace the mandatory hosted history service with a local provider
0002	Resolve the model per agent at request time, not per process at boot
0003	Which container runtime the app drives, and how it hedges
0004	Native SwiftUI for the product surface, embedded web for admin
0005	Developer ID and a DMG, not the Mac App Store
0006	Open questions about the name and the visual reference
0007	Wrap OpenBot rather than re-engineer it, and keep Intelligence for v1. Defers 0001 and re-orders the roadmap — read it before 01 or 03

Conventions in these documents

• "The engine" is the forked OpenBot stack running in containers.
• "The app" is the native macOS client.
• "An agent" is what upstream calls a coworker or a Bot. We use agent in code and documentation. The user-facing word is decided in 09-ui-spec.md.
• "The computer" is the container holding one agent's browser, files, and shell. Upstream's term; kept, because it is a good one.
• A line marked ⚠️ is a known risk with no settled answer yet.