Establish the device architecture from primary sources

CLAUDE.md

@@ -0,0 +1,54 @@
+# termio
+
+## What termio is
+
+**A terminal-first agentic development environment, including its own remote server.**
+
+Coding agents live in terminals. termio is the place those agents run, on machines
+the user already owns — a laptop, a VPS, a devbox — supervised from a native Mac
+app and an iPhone. `termiod` is the durable session host that makes "on any box"
+one code path instead of four.
+
+The category is crowded (Zed remote, VS Code Remote, Codespaces, Warp). That is a
+known and accepted cost of this position, not an oversight. **Do not re-argue the
+positioning.** Build it.
+
+## What makes it different (aim here, not at editors)
+
+- **The session lives on the box, not in the connection.** Detach ≠ kill. An agent
+  keeps working while the laptop is shut; reattach restores the exact screen.
+  Zed and VS Code tie remote work to a live connection; termio does not.
+- **The user's machines, not our cloud.** termio never provisions compute and never
+  runs a hosted control plane. The code never leaves hardware the user controls —
+  the only trust story that survives giving an agent shell access to a private repo.
+- **Agent-native at the protocol level.** Workstream status (`working` / `idle` /
+  `needs-you` / `done`) is a first-class protocol object, not a heuristic scraped
+  off the screen.
+- **Terminal-first is a commitment, not a stage.** The terminal *is* the interface.
+  Chat UIs have been built and fully reverted twice. Don't rebuild them.
+
+## Architectural non-negotiables
+
+These come from `docs/design/termiod-session-protocol.md` §A and §H. Violating one
+is a design regression, not a tradeoff:
+
+1. **Anti-100× invariant** — byte delivery never blocks on host-side VT parse. The
+   authoritative VT is a sidecar for snapshots; any per-frame grid encoder between
+   the PTY and the pipe rebuilds the tmux tax and is rejected.
+2. **State sync only at boundaries** — snapshots on attach / resize / resync, never
+   per frame. `grid_diff` is an opt-in bad-network degrade, never the default.
+3. **Never embed SSH or crypto.** System OpenSSH, tailnets, and OS keychains are the
+   security team we didn't hire. The user's `~/.ssh/config` is authoritative — read
+   it, never override it.
+4. **One protocol, versioned and transport-agnostic.** Unix socket, SSH stdio, and
+   later QUIC carry the *same* framed messages. No second protocol for the phone.
+5. **No nested window manager in the host.** One PTY per session; panes and layout
+   are client concerns.
+6. **Single writer, many readers.** Observers never claim the write token.
+
+## Working style
+
+- Elegance is a small surface area. No grand architecture, no cut-rate MVP.
+- Verify before claiming done; report failures with the actual output.
+- Name mechanisms, not agents.
+- Don't re-pitch ideas that were built and dropped — the design docs record why.

docs/README.md

@@ -76,6 +76,8 @@ from the real front matter).
 | draft | design | [移动端 Agent UI 协议 —— PTY 之上的旁路结构面（ACP 词汇）](design/mobile-agent-ui-protocol.md) |
 | draft | design | [调研：下一批 AgentAdapter 的落盘格式（OpenCode / Pi / Amp / Cursor / Kimi）](design/agent-transcript-survey.md) |
 | draft | design | ["Markdown preview — Apple-grade reading typography"](design/markdown-preview-reading-typography.md) |
+| draft | design | [Device Architecture — one server per device, every UI a client](design/termiod-device-architecture.md) |
+| draft | design | [Hot path, attach join point, and client classes](design/termiod-hot-path-and-client-classes.md) |
 | draft | design | [Issue Triage → 本地 agent（GitHub / Linear 事件驱动 termio session）](design/issue-triage-local-agent.md) |
 | draft | design | [Mac retention analytics (no app changes)](design/mac-retention-analytics.md) |
 | draft | design | [Remote Projects (open an SSH/VPS box like a local project)](design/remote-projects.md) |