docs: add architecture diagram to README

[cyyeh]

Summary

• Add a comprehensive ASCII architecture diagram to the README covering the full system stack
• Diagram includes: browser frontend, FastAPI backend, MCP server, sidecar container, Bifrost LLM gateway, agent model hierarchy, data flow, and persistence layer

Test plan

• Verify the diagram renders correctly in GitHub markdown preview

🤖 Generated with Claude Code

[claude]

Claude finished @cyyeh's task in 2m 19s —— View job

---

Code Review: Architecture Diagram

• Gather context and understand the request
• Review README.md changes
• Provide comprehensive review feedback

---

Overall, this is a valuable addition to the documentation. The architecture diagram is comprehensive and covers the full system stack clearly. A few factual inaccuracies need attention (this PR is already merged, so these could be fixed in a follow-up).

---

What's Good

• Comprehensive coverage — The diagram covers all major layers (browser, backend, sidecar, Bifrost, agent hierarchy, persistence) in one place, giving a quick mental model of the whole system.
• Data flow walkthrough — The step-by-step SSE event flow (lines 470–491) is especially useful for new contributors; it connects the dots between all the components.
• SSE event types list — Documenting thinking | answer | thinking_done | tool_call | ... inline is a nice quick reference.
• Agent model hierarchy box — Clearly shows the orchestrator/subagent split with their respective tool sets and rationale (lightweight/cost-efficient haiku for SQL).
• Persistence layer — The three-column breakdown (DuckDB, SQLite, Filesystem) is clean and easy to scan.

---

Issues Found

1. Bifrost port is incorrect (factual error)

README.md line 447:

│  Port 8081                   │

Port 8081 is Bifrost's Web UI port (see line 147: "Bifrost's Web UI at http://localhost:8081"). The actual API port used by the agent is 8080 (see line 227: ANTHROPIC_BASE_URL=http://bifrost:8080/anthropic and the existing mini-diagram at line 268: Bifrost Gateway (:8080/anthropic)).

The diagram should read Port 8080 (API) to be accurate, or note both: Port 8080 (API) / Port 8081 (Web UI).

Fix this →

---

2. Idle timeout value is wrong (factual error)

README.md line 455:

│  - Idle timeout (10 min)  │

The env var table at line 321 shows CONTAINER_IDLE_TIMEOUT_SECONDS defaults to 900 seconds = 15 minutes, not 10 minutes. This should be corrected to "Idle timeout (15 min)".

Fix this →

---

3. Code fence language specifier

README.md line 342:

```markdown                                                                                                                

Using ```markdown for an ASCII art block is semantically incorrect — GitHub may attempt markdown-within-markdown interpretation (though in practice it renders as text). The conventional choice for plain-text/ASCII diagrams is ```text or just ``` (no language). There's also significant trailing whitespace after markdown on that line that should be trimmed.

Fix this →

---

4. Minor: hardcoded model names may become stale

Lines 498 and 508 reference claude-sonnet-4-6 and haiku directly. These will need manual updates whenever the default models change. Consider noting that these are defaults controlled by environment variables (e.g., SQL_SUBAGENT_MODEL), which is already documented elsewhere in the README. This is low-priority but worth noting for long-term maintainability.

---

5. Data flow step 4 omits container reuse

Line 474:

4. Backend spawns sidecar Docker container

The prose at line 277 correctly notes "spins up a gVisor container or reuses an existing one for the session". The diagram simplification is understandable for brevity, but could be slightly more accurate as: "Backend spawns or reuses sidecar Docker container". Minor nit.

---

Summary

Severity	Issue
🔴 High	Bifrost port shown as 8081 (should be 8080 for API)
🔴 High	Idle timeout shown as 10 min (should be 15 min / 900s)
🟡 Medium	Code fence language should be text not markdown
🟢 Low	Hardcoded model names may go stale
🟢 Low	Data flow omits container reuse

The two factual errors (Bifrost port and idle timeout) should be corrected in a follow-up PR.