Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

docs: make the README sell the product and move the codebase map into docs/ (#419)

Chaitanya Girie19bc2036287
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
new file mode 100644
index 00000000..9df484f9
--- /dev/null
+++ b/.github/CODEOWNERS
@@ -0,0 +1,21 @@
+# Every pull request gets a review request automatically, so nothing sits waiting
+# for someone to notice it. Ownership here is about routing, not permission.
+#
+# Last match wins, so the specific rules below override the catch-all.
+
+* @chaitanyagiri
+
+# Release, signing and CI plumbing. Breaking these breaks shipping for everyone.
+/.github/workflows/ @chaitanyagiri
+/electron-builder.yml @chaitanyagiri
+/RELEASE.md @chaitanyagiri
+/RELEASE-CHECKLIST.md @chaitanyagiri
+
+# Licensing and attribution. Changes here have legal weight.
+/LICENSE @chaitanyagiri
+/LICENSE-ASSETS @chaitanyagiri
+/src/renderer/src/assets/ATTRIBUTION.md @chaitanyagiri
+
+# Security and privacy surface.
+/SECURITY.md @chaitanyagiri
+/TELEMETRY.md @chaitanyagiri
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index cd04d907..094d0c70 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -48,13 +48,20 @@
- OS:
- Steps:
-## Discord (optional)
+## Credit (optional)
-<!-- For the `employee of the month` role in our Discord when this merges.
- Join first so we can find you: https://discord.gg/SEDzP5ZPk5 -->
+<!-- Both are optional and neither affects whether this merges.
+
+ Discord gets you the `employee of the month` role when this lands. Join
+ first so we can find you: https://discord.gg/SEDzP5ZPk5
+
+ X is so we can credit you by name when we post about what shipped. Leave it
+ blank if you would rather we did not. -->
Discord:
+X:
+
## Checklist
- [ ] **Before and after evidence is attached above**, under both headings.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e11be8af..4407152f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -9,6 +9,29 @@ conventions that keep the codebase coherent.
This project follows the [Contributor Covenant](./CODE_OF_CONDUCT.md). By
participating, you agree to uphold it.
+## Before you start
+
+These are the constraints most pull requests trip over. Reading them first is
+much cheaper than finding out in review.
+
+- **Keep the change scoped to one clear improvement, fix, or refactor.** A fix
+ plus a rename plus a refactor is three pull requests, and all three merge
+ faster than the one.
+- **Munder Difflin targets macOS, Windows and Linux.** Every change has to work
+ on all three unless it sits behind an explicit runtime platform check. Most
+ of our cross-platform bugs are paths: use `path.join` and the Node path
+ helpers, never a hand-built `"a/b"` string.
+- **Paths with spaces are real.** Several shipped bugs came from a hive folder
+ living under a directory with a space in its name. Quote, and test one.
+- **We support twelve agent CLIs and counting.** Keep shared behaviour provider
+ neutral and put provider specific logic behind an explicit check. Anything
+ that assumes Claude Code specifically will break the other eleven.
+- **Do not assume the local machine.** Agents run against their own working
+ directories and their own environments; a process, file, credential or shell
+ that exists on yours may not exist on theirs.
+- **New UI derives from the design tokens.** [`DESIGN.md`](./DESIGN.md) is
+ canonical. No ad-hoc colors, spacing or fonts.
+
## Development setup
### Prerequisites
@@ -89,11 +112,20 @@ something visible will cost you more time than the screenshot would have.
change one, change both.
6. **Read your own diff.** Every line of it. Debug logging, commented-out code,
and reformatting of files you didn't otherwise touch all get a PR sent back.
+7. **Run your coding agent over your own PR, and paste what it found.** We ship
+ an agent harness; use one. Ask it to check specifically for cross-platform
+ behaviour, paths with spaces, whether the change stays provider neutral
+ across the supported CLIs, performance in hot paths, and obvious security
+ risk. A short honest summary including what it flagged and you decided not to
+ change is worth more than a clean one, and it usually saves a review round
+ trip. This is asked for, not required.
-## What gets a PR closed
+## Where the bar is
-We are getting more pull requests than we can review carefully, so the bar has
-gone up. These are closed rather than negotiated:
+We get more pull requests than we can review carefully, so the bar is high and
+it is easier for everyone if it is written down. Clear the list above and you
+are almost certainly fine. The items below are the ones we close rather than
+negotiate, and every one of them is cheaper to avoid than to fix in review:
- **No before/after evidence**, and no `no-visual-change` label.
- **More than one change in one PR.** A fix plus a refactor plus a rename is
@@ -124,8 +156,8 @@ someone who has.
| `src/renderer/` | React UI, Pixi.js office scene (`scene/office/`), components, design system, stores. |
| `tools/mapgen/` | Python helpers for building/rendering the Tiled office map. |
-See the [Architecture](./README.md#architecture) section of the README for the
-data-flow overview.
+See [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the data-flow overview,
+the module by module layout, and the design system.
## Good first areas
diff --git a/README.md b/README.md
index 42a13ff0..befe45a4 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,7 @@ visualized as avatars at work on a shared office floor.
<p>
<a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-F4D35E.svg?style=flat-square&labelColor=6E1423"></a>
<a href="./CHANGELOG.md"><img alt="Version: 0.4.6" src="https://img.shields.io/badge/version-0.4.6-F4D35E.svg?style=flat-square&labelColor=6E1423"></a>
+ <a href="https://github.com/chaitanyagiri/munder-difflin/releases"><img alt="Downloads across all releases" src="https://img.shields.io/github/downloads/chaitanyagiri/munder-difflin/total?style=flat-square&label=downloads&color=F4D35E&labelColor=6E1423"></a>
<img alt="Status: pre-release" src="https://img.shields.io/badge/status-pre--release-F4F1EA.svg?style=flat-square&labelColor=6E1423">
<img alt="Platform: macOS | Windows | Linux" src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-F4F1EA.svg?style=flat-square&labelColor=6E1423">
<a href="./CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-F4D35E.svg?style=flat-square&labelColor=6E1423"></a>
@@ -45,6 +46,12 @@ visualized as avatars at work on a shared office floor.
<a href="https://github.com/chaitanyagiri/munder-difflin/raw/main/docs/media/hero.mp4">▶ Watch the floor — Munder Difflin running a hive of Claude Code agents</a>
</video>
+<br><br>
+
+**[⬇ Download for macOS, Windows or Linux](https://github.com/chaitanyagiri/munder-difflin/releases/latest)**
+
+<sub>macOS builds are signed and notarized. You do not need to build from source to use it.</sub>
+
</div>
---
@@ -59,19 +66,42 @@ visualized as avatars at work on a shared office floor.
## Contents
+- [Supported agents](#supported-agents)
- [What it is](#what-it-is)
- [How it works](#how-it-works)
- [Features](#features)
- [Getting started](#getting-started)
-- [Architecture](#architecture)
-- [Project structure](#project-structure)
-- [Design system](#design-system)
+- [Architecture & project structure](./docs/ARCHITECTURE.md)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [Telemetry](#telemetry)
- [License](#license)
- [Acknowledgements](#acknowledgements)
+## Supported agents
+
+**Bring the CLI you already pay for.** Every one of these runs as a real process in its own
+terminal, with your existing subscription and its hourly limits. If it runs in a terminal, it
+can run here.
+
+<p>
+ <a href="https://docs.claude.com/en/docs/claude-code"><kbd>Claude Code</kbd></a>
+ <a href="https://github.com/openai/codex"><kbd>Codex · GPT</kbd></a>
+ <a href="https://x.ai/cli"><kbd>Grok · xAI</kbd></a>
+ <a href="https://www.kimi.com/code"><kbd>Kimi Code</kbd></a>
+ <a href="https://github.com/google-gemini/gemini-cli"><kbd>Gemini CLI</kbd></a>
+ <a href="https://antigravity.google/docs/cli-overview"><kbd>Antigravity · Gemini</kbd></a>
+ <a href="https://github.com/QwenLM/qwen-code"><kbd>Qwen</kbd></a>
+ <a href="https://opencode.ai/docs"><kbd>OpenCode</kbd></a>
+ <a href="https://github.com/charmbracelet/crush"><kbd>Crush · Charm</kbd></a>
+ <a href="https://pi.dev/docs/latest"><kbd>Pi</kbd></a>
+ <a href="https://docs.github.com/copilot/concepts/agents/about-copilot-cli"><kbd>GitHub Copilot</kbd></a>
+ <a href="https://cursor.com/docs/cli/install"><kbd>Cursor</kbd></a>
+ <kbd>+ any custom command</kbd>
+</p>
+
+Plus **bring your own keys** and **local models** through Ollama, LM Studio or vLLM.
+
## What it is
Munder Difflin is a desktop app that wraps **real terminal-agent CLIs** as fully-capable agents,
@@ -123,6 +153,88 @@ terminal/event plane, and [`DESIGN.md`](./DESIGN.md) for the visual system.
## Features
+<table>
+<tr>
+<td width="50%" valign="middle">
+
+### Talk to one agent, not twelve
+
+Michael is your clone and the only agent you brief. He assigns the work, routes the traffic, and
+escalates the few things that actually need you.
+
+</td>
+<td width="50%">
+ <a href="https://github.com/chaitanyagiri/munder-difflin/raw/main/docs/media/demo/orchestrator.mp4"><img src="./docs/media/demo/orchestrator-poster.jpg" alt="Briefing Michael, the orchestrator agent, from the Command Center" width="100%"></a>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Hire an agent in a few clicks
+
+Pick the CLI, the model and the autonomy, give it a desk, and it starts working. Import a
+ready made role from the [Agent Gallery](https://munderdiffl.in/hires/) if you would rather not
+start from scratch.
+
+</td>
+<td width="50%">
+ <img src="./docs/screenshots/add-agent.png" alt="The add agent dialog: choosing a provider, model and role" width="100%">
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Memory that survives the session
+
+Every agent keeps markdown memory that is mined into a shared, searchable palace. Close the app,
+come back tomorrow, and they still know what they learned.
+
+</td>
+<td width="50%">
+ <img src="./docs/screenshots/memory.png" alt="Searching the shared memory palace across every agent" width="100%">
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Autonomy with a leash
+
+Set how far each agent may go on its own. Spend, scope and destructive operations come back to
+you, and a circuit breaker steers, constrains, then stops anything that loops or runs away.
+
+</td>
+<td width="50%">
+ <img src="./docs/screenshots/autonomy.png" alt="Per agent autonomy and approval settings" width="100%">
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Watch the whole floor work
+
+Agents walk to stations as they work and envelopes fly desk to desk when they message each other.
+Click any desk to read that terminal live, and type straight back into it.
+
+</td>
+<td width="50%">
+ <a href="https://github.com/chaitanyagiri/munder-difflin/raw/main/docs/media/demo/agents.mp4"><img src="./docs/media/demo/agents-poster.jpg" alt="Agents working in parallel on the office floor" width="100%"></a>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="middle">
+
+### Set up once
+
+The onboarding wizard checks what you already have, and offers to install what is missing rather
+than sending you to a docs page.
+
+</td>
+<td width="50%">
+ <a href="https://github.com/chaitanyagiri/munder-difflin/raw/main/docs/media/demo/setup.mp4"><img src="./docs/media/demo/setup-poster.jpg" alt="The first run setup wizard" width="100%"></a>
+</td>
+</tr>
+</table>
+
**The floor**
- **Every terminal is a real agent.** Claude Code, Antigravity (Gemini), OpenAI Codex, xAI Grok, Kimi Code, Gemini CLI, Qwen, OpenCode, Crush, pi.dev, GitHub Copilot CLI, Cursor, or a custom command — each in its own `node-pty` PTY, rendered with xterm.js.
- **Every agent is an avatar.** A Pixi.js office floor where agents walk to stations, envelopes fly desk to desk, and avatar state reflects real work.
@@ -181,6 +293,20 @@ terminal/event plane, and [`DESIGN.md`](./DESIGN.md) for the visual system.
## Getting started
+### Download the app
+
+**Most people want this one.** Signed and notarized macOS builds, plus Windows and Linux, are on
+the [latest release](https://github.com/chaitanyagiri/munder-difflin/releases/latest). Install it,
+open it, and the wizard takes you the rest of the way. You do not need Node, a toolchain, or this
+repository.
+
+You do still need at least one agent CLI on your machine, and the app can install missing ones for
+you from **Settings → Prerequisites**.
+
+### Build from source
+
+Everything below is for contributors and for people who want to run an unreleased build.
+
### Prerequisites
- **macOS, Windows, or Linux**.
@@ -223,88 +349,18 @@ npm run typecheck # type-check the node (main/preload) and web (renderer) proje
## Architecture
-Two data planes feed one renderer:
+Two data planes feed one renderer: a **terminal plane** that owns the PTYs, the filesystem and git,
+and an **event plane** that runs the hive, the hook server and the router. The renderer talks to
+both only through a typed bridge.
-```
-┌───────────────────────────────────────────────────────────────┐
-│ Electron Renderer (React) │
-│ ┌──────────────────┐ ┌──────────────────────────────┐ │
-│ │ Office Floor │ │ Terminal + Command Bar │ │
-│ │ (Pixi.js) │ │ Files + Git tabs (xterm.js) │ │
-│ └─────────▲────────┘ └────────────▲─────────────────┘ │
-│ │ avatar state │ pty bytes / fs / git │
-└─────────────┼──────────────────────────┼───────────────────────┘
- │ IPC (contextBridge: window.cth)
- ┌──────┴──────────┐ ┌──────┴─────────────┐
- │ Event Plane │ │ Terminal Plane │
- │ hooks / hive │ │ node-pty PTYs │
- │ router + GOD │ │ + fs + git │
- └────────▲────────┘ └──────▲─────────────┘
- │ hook payloads │ stdin / stdout
- └─────────┬──────────────┘
- ┌──────┴──────────────┐
- │ claude / agy / codex│
- └─────────────────────┘
-```
-
-- **Terminal plane.** The main process owns a `PtyManager` that spawns each agent as a `node-pty`
- process and streams output over per-id IPC (`pty:data:<id>`). The renderer talks only through a
- typed `window.cth` bridge ([`src/preload/index.ts`](./src/preload/index.ts)), which also exposes
- sandboxed filesystem and git helpers.
-- **Hive / event plane.** `hive.ts` is the on-disk multi-agent layer; `hooks.ts` runs the hook
- server that provider bridges POST lifecycle payloads to (`cth-hook` for Claude Code, `agy-hook`
- for Antigravity). `memory.ts` wraps the semantic memory CLI. The router delivers messages, drains
- provider outboxes, the GOD agent adjudicates, and idle/inbox wakeups keep workers draining mail.
-
-## Project structure
-
-```
-src/
- main/ Electron main process (Node)
- index.ts window, IPC handlers, quit guard
- pty.ts node-pty manager (spawn/write/resize/kill/stream)
- hive.ts on-disk multi-agent layer (memory, mailboxes, router)
- hooks.ts hook server + provider hook shims (`cth-hook`, `agy-hook`)
- memory.ts semantic memory layer (CLI wrapper, degrade-to-noop)
- config.ts harness config persistence + home setup
- transcript.ts reads ~/.claude/projects/ JSONL transcripts for real token/cost telemetry
- telemetry.ts live OTel collector + usage/cost feed for observability
- usage.ts / pricing.ts UsageProvider seam + per-model cost attribution
- breaker.ts / control.ts cost/runaway circuit breaker (steer/constrain/stop) + HITL gate / steer / stop
- reflect.ts MemoryReflector — memory condensation
- db.ts SQLite durable store (window bounds + history) + durable cost ledger
- github.ts GitHub issue + CI run ingestion via the gh CLI
- shellEnv.ts resolve PATH and shell env for child processes
- fs.ts / git.ts sandboxed filesystem + git bridges
- preload/ contextBridge → typed window.cth API
- renderer/src/
- App.tsx top-level layout + wiring
- design/ tokens.css / tokens.ts / global.css (design source of truth)
- components/ PixelPanel, AgentDetailPanel, CommandBar, ApprovalsPanel, MemoryPanel, …
- CommandCenterPanel, Michael's control surface (Terminal/Floor/Memory/Activity/Tasks/Triggers/Handbook tabs)
- ToolWaterfall, per-agent tool-span waterfall for the observability view
- TasksKanban, dependency-aware kanban board (Tasks tab)
- ThreadsPanel, hive message conversation viewer (Messages tab)
- MessageQueueComposer, park messages for a busy agent
- scene/office/ Pixi office floor: OfficeFloor, Character, Camera, cast, pathfinding, …
- store/ · hooks/ zustand store, event loop, PTY parser, typewriter
- assets/ tilesets, maps, character sheets (see ATTRIBUTION.md)
-docs/ `logo.png`, `banner.png`, landing page (GitHub Pages → munderdiffl.in)
-docs/media/ `og.png` (social previews) + rendered Remotion clips
-landing-remotion/ Remotion project that renders the landing page's "how it works" clips
-HIVE.md · SPEC.md · DESIGN.md multi-agent · terminal/event · visual design
-docs/message-queue.md who may type into an agent's terminal, and when
-```
+**The full diagrams, the module by module project structure, and the design system live in
+[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).** They moved out of this file so it can explain
+the product rather than the codebase. Also see [`HIVE.md`](./HIVE.md) for the multi-agent design,
+[`SPEC.md`](./SPEC.md) for the terminal and event plane, and [`DESIGN.md`](./DESIGN.md) for the
+visual system.
<div align="right">(<a href="#munder-difflin">↑ back to top</a>)</div>
-## Design system
-
-The aesthetic is **Animal Crossing × Earthbound × SNES menu UI** — pixel-snapped, chunky, friendly.
-[`DESIGN.md`](./DESIGN.md) is canonical; every component derives from its tokens. The Munder Difflin
-brand layers a **Dunder-Mifflin maroon** (`#6E1423`) and **gold** (`#F4D35E`) on top for logo and
-chrome. The 15 avatars are the cast of *The Office*, differentiated by hair/skin/shirt recipes.
-
## Roadmap
Shipped through **v0.4.6**: a Simplified Chinese and Arabic interface with right to left support
@@ -342,6 +398,14 @@ first areas: wiring real hook events, the add-agent flow, the config drawer, and
Questions, bugs, or want to show off your office? Join the Discord: **<https://discord.gg/SEDzP5ZPk5>**. Add your Discord handle to a PR and you'll get the `employee of the month` role when it merges.
+**Looking for somewhere to start?** The
+[`good first issue`](https://github.com/chaitanyagiri/munder-difflin/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+list is kept stocked with small, self contained work that has a clear finish line.
+
+<a href="https://github.com/chaitanyagiri/munder-difflin/graphs/contributors">
+ <img src="https://contrib.rocks/image?repo=chaitanyagiri/munder-difflin" alt="Munder Difflin contributors">
+</a>
+
## Telemetry
Official builds send a **small set of anonymous usage events** (app opened, agent spawned, feature
@@ -362,7 +426,7 @@ source — forks compile with no key and send nothing) are documented in
The **source code** is licensed under the **MIT License** — see [`LICENSE`](./LICENSE). The MIT grant
covers the code only; the bundled pixel art is licensed separately from LimeZu and is carved out in
-the `LICENSE` scope note. *Munder Difflin* is an affectionate parody and is not affiliated with NBC's *The Office* or
+[`LICENSE-ASSETS`](./LICENSE-ASSETS). *Munder Difflin* is an affectionate parody and is not affiliated with NBC's *The Office* or
Dunder Mifflin.
## Acknowledgements
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 00000000..eb380e76
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,89 @@
+# Architecture, project structure and design system
+
+_Moved out of the README so that document can do its job of explaining the product._
+_This is the contributor's map. Start here before your first pull request._
+
+## Architecture
+
+Two data planes feed one renderer:
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│ Electron Renderer (React) │
+│ ┌──────────────────┐ ┌──────────────────────────────┐ │
+│ │ Office Floor │ │ Terminal + Command Bar │ │
+│ │ (Pixi.js) │ │ Files + Git tabs (xterm.js) │ │
+│ └─────────▲────────┘ └────────────▲─────────────────┘ │
+│ │ avatar state │ pty bytes / fs / git │
+└─────────────┼──────────────────────────┼───────────────────────┘
+ │ IPC (contextBridge: window.cth)
+ ┌──────┴──────────┐ ┌──────┴─────────────┐
+ │ Event Plane │ │ Terminal Plane │
+ │ hooks / hive │ │ node-pty PTYs │
+ │ router + GOD │ │ + fs + git │
+ └────────▲────────┘ └──────▲─────────────┘
+ │ hook payloads │ stdin / stdout
+ └─────────┬──────────────┘
+ ┌──────┴──────────────┐
+ │ claude / agy / codex│
+ └─────────────────────┘
+```
+
+- **Terminal plane.** The main process owns a `PtyManager` that spawns each agent as a `node-pty`
+ process and streams output over per-id IPC (`pty:data:<id>`). The renderer talks only through a
+ typed `window.cth` bridge ([`src/preload/index.ts`](../src/preload/index.ts)), which also exposes
+ sandboxed filesystem and git helpers.
+- **Hive / event plane.** `hive.ts` is the on-disk multi-agent layer; `hooks.ts` runs the hook
+ server that provider bridges POST lifecycle payloads to (`cth-hook` for Claude Code, `agy-hook`
+ for Antigravity). `memory.ts` wraps the semantic memory CLI. The router delivers messages, drains
+ provider outboxes, the GOD agent adjudicates, and idle/inbox wakeups keep workers draining mail.
+
+## Project structure
+
+```
+src/
+ main/ Electron main process (Node)
+ index.ts window, IPC handlers, quit guard
+ pty.ts node-pty manager (spawn/write/resize/kill/stream)
+ hive.ts on-disk multi-agent layer (memory, mailboxes, router)
+ hooks.ts hook server + provider hook shims (`cth-hook`, `agy-hook`)
+ memory.ts semantic memory layer (CLI wrapper, degrade-to-noop)
+ config.ts harness config persistence + home setup
+ transcript.ts reads ~/.claude/projects/ JSONL transcripts for real token/cost telemetry
+ telemetry.ts live OTel collector + usage/cost feed for observability
+ usage.ts / pricing.ts UsageProvider seam + per-model cost attribution
+ breaker.ts / control.ts cost/runaway circuit breaker (steer/constrain/stop) + HITL gate / steer / stop
+ reflect.ts MemoryReflector — memory condensation
+ db.ts SQLite durable store (window bounds + history) + durable cost ledger
+ github.ts GitHub issue + CI run ingestion via the gh CLI
+ shellEnv.ts resolve PATH and shell env for child processes
+ fs.ts / git.ts sandboxed filesystem + git bridges
+ preload/ contextBridge → typed window.cth API
+ renderer/src/
+ App.tsx top-level layout + wiring
+ design/ tokens.css / tokens.ts / global.css (design source of truth)
+ components/ PixelPanel, AgentDetailPanel, CommandBar, ApprovalsPanel, MemoryPanel, …
+ CommandCenterPanel, Michael's control surface (Terminal/Floor/Memory/Activity/Tasks/Triggers/Handbook tabs)
+ ToolWaterfall, per-agent tool-span waterfall for the observability view
+ TasksKanban, dependency-aware kanban board (Tasks tab)
+ ThreadsPanel, hive message conversation viewer (Messages tab)
+ MessageQueueComposer, park messages for a busy agent
+ scene/office/ Pixi office floor: OfficeFloor, Character, Camera, cast, pathfinding, …
+ store/ · hooks/ zustand store, event loop, PTY parser, typewriter
+ assets/ tilesets, maps, character sheets (see ATTRIBUTION.md)
+docs/ `logo.png`, `banner.png`, landing page (GitHub Pages → munderdiffl.in)
+docs/media/ `og.png` (social previews) + rendered Remotion clips
+landing-remotion/ Remotion project that renders the landing page's "how it works" clips
+HIVE.md · SPEC.md · DESIGN.md multi-agent · terminal/event · visual design
+docs/message-queue.md who may type into an agent's terminal, and when
+```
+
+<div align="right">(<a href="#munder-difflin">↑ back to top</a>)</div>
+
+## Design system
+
+The aesthetic is **Animal Crossing × Earthbound × SNES menu UI** — pixel-snapped, chunky, friendly.
+[`DESIGN.md`](../DESIGN.md) is canonical; every component derives from its tokens. The Munder Difflin
+brand layers a **Dunder-Mifflin maroon** (`#6E1423`) and **gold** (`#F4D35E`) on top for logo and
+chrome. The 15 avatars are the cast of *The Office*, differentiated by hair/skin/shirt recipes.
+
diff --git a/docs/pr-evidence/readme-after.jpg b/docs/pr-evidence/readme-after.jpg
new file mode 100644
index 00000000..180ff4eb
Binary files /dev/null and b/docs/pr-evidence/readme-after.jpg differ
diff --git a/docs/pr-evidence/readme-before.jpg b/docs/pr-evidence/readme-before.jpg
new file mode 100644
index 00000000..a6091191
Binary files /dev/null and b/docs/pr-evidence/readme-before.jpg differ