james.maesandClaude Opus 4.7
c4c32f7aae
Audit-and-rewrite of root README against current truth (2026-05-12). The previous README was accurate but list-shaped and unillustrated; the rewrite reorients around what a new reader (human or AI agent) needs in 60 seconds. New / changed sections: - Tagline + two-paragraph intro (what / who / why) - Status banner pointing at GitHub Issues + Milestones (canonical) - Screenshots placeholder + shot list under assets/screenshots/ - "Architecture at a glance" with a top-level mermaid flowchart (Swift host + LLM providers + WKWebView, with 14 nodes) - Subsystems table — eight first-class + supporting packages - "Install order" section with a mermaid DAG of the AppDelegate install sequence (vision → agent → voice, plus parallel memory/MCP/replay), matching check-install-order.sh - "Agent turn lifecycle" mermaid showing the orchestrator → single broadcaster fanout, with the strict-mode degradation preamble inject point called out - "Boot-health probes" mermaid for the eight NOT FAKED probes → rollup → menu-bar icon / banner / agent preamble - "Project culture" section codifying the in-code-docs philosophy, NOT FAKED probes, strict-mode escalation, 18 boundary gates, the three-name test-double taxonomy, audit-and-stabilize cadence, and the GitHub-Issues-is-canonical policy - "Roadmap" reorganized around the v0.1 → v1.1 milestones from GitHub Milestones (user-outcome-focused, not subsystem-focused) - Build & run cleaned up; boundary-gates one-liner; opt-in real-hardware test commands kept Also adds assets/screenshots/README.md with a prioritized shot list — eight screenshots in priority order — and a note on why diagrams stay as inline mermaid (GitHub-native, no re-export). Removed: the older "Status" subsystem-state table, which had become a mix of v0.12.0 milestone audit terms (Track A/B/C/D, B-8) that don't map cleanly to the new GitHub Issues taxonomy. Status now points at GitHub Issues + Milestones as the source of truth. Gates: 17/18 pass. check-app-builds.sh fails on the in-flight AppDelegate.swift rewrite (unstaged, owned by a parallel agent) — unrelated to this markdown-only change. Confirmed only README.md + assets/screenshots/README.md are staged here. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Screenshots
The root README.md references images from this
directory but currently ships zero of them — there's no point inventing
screenshots before there's something worth showing.
When a screenshot lands here, name it after its referent (hud-ring-idle.png,
not Screen Shot 2026-05-12 at 4.32.png), keep it under 800 KB (PNG with
pngquant --quality 70-85), and reference it from the README with a
descriptive alt-text.
Shot list (priority order)
When the user has cycles, the highest-signal shots to capture:
hud-ring-idle.png— particle ring at rest, dim cyan. Establishes the visual identity in the README's hero slot.hud-ring-thinking.gif(optional, animated) — ring rotating during a streamed Opus turn. Sells "this is alive."hud-ring-states.png— 2×2 grid of the four agent states (idle / listening / thinking / speaking) for the "Subsystems" section's HUD row.status-panel.png— menu-bar → Status… showing the eight boot-health probes with mixed states (some.ok, one.soft, one.unknown). Demonstrates the NOT-FAKED probe culture concretely.degradation-banner.png— a non-dismissible HUD banner with a critical-severity failure (e.g., "Memory store unreachable — Jarvis will not remember new facts this session"). Shows the strict-mode escalation in action.devoverlay-turns.png— the Dev Overlay's Turns tab during a live conversation, with one expanded turn showing the streamed events timeline. Useful for the "Non-functional requirements" section.devoverlay-bus.png— the Bus tab with a recent message trace. Useful when documenting the Bus contract.menu-bar.png— close-up of the menu-bar icon in normal state beside its red degraded variant. Pairs with the boot-health probe diagram.
Diagrams (different concern)
Architecture / lifecycle / install-order diagrams live as inline
mermaid blocks inside README.md and ARCHITECTURE.md — they render
natively on GitHub and stay in sync with the code without anybody
re-exporting an SVG. Don't replace them with rasterized exports.
If a diagram outgrows mermaid (≳ 20 nodes or needs precise layout), the
right move is to author it in Excalidraw, export
both the .excalidraw source and a .svg into this directory, and
reference the SVG from the README. The .excalidraw source is what keeps
the diagram editable.