1 files changed, 11 insertions, 5 deletions
diff --git a/AGENTS.md b/AGENTS.md
index aef17c2e..cd59a85c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,13 +1,19 @@
 # Agents.md
 
-## Apps
+## Architecture
 
-- Web
-- Desktop
+An ongoing migration is moving all business logic into `rust/`. Each app under `apps/` is a UI shell — it owns rendering, interaction, and platform-specific concerns, but never owns logic. The UI framework for any given app is a replaceable detail.
 
-## Rust
+### `rust/`
 
-Shared code between apps live in `rust/`, not in `packages/`
+The single source of truth for all non-UI code. Everything platform-agnostic belongs here: no components, no hooks, no framework imports.
+
+### `apps/`
+
+Each app is a frontend that calls into Rust. Logic is never duplicated between apps — only UI is, because each platform may use an entirely different framework and language to build it.
+
+- `web/` — Next.js
+- `desktop/` — GPUI
 
 ## Web