docs: audit and fix READMEs across the repo

README.md

@@ -4,19 +4,22 @@ AI-powered assistant platform by Vellum.
 
 ## Architecture
 
-The platform has two main components:
+The platform has three main components:
 
-- **Assistant runtime** (`assistant/`): Bun + TypeScript daemon that owns conversation history, attachment storage, and channel delivery state in a local SQLite database. Exposes an HTTP API consumed by the gateway.
+- **Assistant runtime** (`assistant/`): Bun + TypeScript daemon that owns conversation history, attachment storage, and channel delivery state in a local SQLite database. Exposes a Unix domain socket (macOS) and optional TCP listener (iOS) for native clients, plus an HTTP API consumed by the gateway.
+- **Native clients** (`clients/`): Swift Package with macOS and iOS apps sharing ~45-50% of code via `VellumAssistantShared`. The macOS app is a menu bar assistant with computer-use (accessibility + CGEvent). The iOS app is a chat client supporting standalone mode (direct Anthropic API) and connected-to-Mac mode (TCP proxy through the daemon).
 - **Gateway** (`gateway/`): Standalone Bun + TypeScript service that owns Telegram integration end-to-end. Receives Telegram webhooks, routes to the correct assistant via static settings, forwards to the assistant runtime, and sends replies back to Telegram. Optionally acts as an authenticated reverse proxy for the assistant runtime API (client → gateway → runtime).
 
 ## Repository Structure
 
 ```
 /
-├── assistant/         # Bun-based assistant runtime
-├── clients/           # Desktop clients
+├── assistant/         # Bun-based assistant runtime (daemon, CLI, HTTP API)
+├── clients/           # Native clients (macOS menu bar app + iOS chat app)
 ├── gateway/           # Telegram gateway service
-├── scripts/           # Utility scripts
+├── benchmarking/      # Load testing scripts (gateway webhook/proxy benchmarks)
+├── scripts/           # Utility scripts (publishing, tunneling)
+├── .claude/           # Claude Code slash commands and workflow tools
 └── .github/           # GitHub Actions workflows
 ```
 
@@ -44,7 +47,7 @@ See [.githooks/README.md](./.githooks/README.md) for more details about availabl
 
 ## Assistant Runtime
 
-The assistant runtime lives in `/assistant`. See [assistant/README.md](./assistant/README.md) for details.
+The assistant runtime lives in `/assistant`.
 
 ```bash
 cd assistant

clients/README.md

@@ -124,26 +124,15 @@ Depends only on `VellumAssistantShared` (no macOS frameworks).
 **~45-50% code reuse** between macOS and iOS achieved through:
 
 1. **Shared IPC layer** - Both platforms communicate with daemon (different transport)
-2. **Shared design system** (PR 2) - Tokens and components with conditional compilation
-3. **Shared ViewModels** (PR 3) - ChatViewModel, message models work on both platforms
+2. **Shared design system** - Tokens and components with conditional compilation
+3. **Shared ViewModels** - ChatViewModel, message models work on both platforms
 
 **Platform-specific**:
 - **UI frameworks**: AppKit (macOS) vs UIKit (iOS)
 - **Computer-use**: AXUIElement + CGEvent (macOS only, sandboxing prevents on iOS)
 - **Screen recording**: ScreenCaptureKit (macOS) vs ReplayKit (iOS)
 - **App lifecycle**: NSStatusItem (macOS) vs UIScene (iOS)
 
-## Migration from Single-Platform
-
-This structure was introduced in PR #1821 (iOS shared library foundation). Before this:
-- `clients/macos/Package.swift` - Single-platform package
-- `clients/macos/vellum-assistant/IPC/` - macOS-only IPC code
-
-After migration:
-- `clients/Package.swift` - Multi-platform package
-- `clients/shared/IPC/` - Cross-platform IPC code
-- All 25+ IPC message types have `public` access and explicit `public init()`
-
 ## Development
 
 ### Adding Shared Code

clients/ios/README.md

@@ -103,10 +103,10 @@ Requires the Vellum daemon running on your Mac (either as the macOS desktop app
 ```bash
 cd assistant
 # For simulator (localhost only):
-VELLUM_DAEMON_TCP_ENABLED=1 bun run src/daemon/main.ts
+VELLUM_DAEMON_TCP_ENABLED=1 bun run src/index.ts daemon start
 
 # For real device (all network interfaces):
-VELLUM_DAEMON_TCP_ENABLED=1 VELLUM_DAEMON_TCP_HOST=0.0.0.0 bun run src/daemon/main.ts
+VELLUM_DAEMON_TCP_ENABLED=1 VELLUM_DAEMON_TCP_HOST=0.0.0.0 bun run src/index.ts daemon start
 ```
 
 TCP is opt-in (`VELLUM_DAEMON_TCP_ENABLED=1`) for security — the Unix socket default binds only to the local filesystem. By default the TCP listener binds to `127.0.0.1` (simulator use). Set `VELLUM_DAEMON_TCP_HOST=0.0.0.0` to accept LAN connections from a real device.

clients/macos/README.md

@@ -6,7 +6,7 @@ A native macOS menu bar app that controls your Mac via accessibility APIs and CG
 
 This repository also includes an iOS app target (`vellum-assistant-ios`) that shares ~45-50% of code with the macOS app through the `VellumAssistantShared` library. The iOS app is a chat-focused client that connects to a network-accessible daemon via TCP.
 
-**Status:** Fully functional. The iOS target requires xcodebuild with iOS SDK to build — it cannot be built with `swift build` on macOS due to UIKit dependencies. See [clients/ios/README.md](../ios/README.md) for build instructions.
+**Status:** Fully functional. Build via Xcode (recommended) or `xcodebuild` from the command line — `swift build` on macOS cannot compile the iOS target due to UIKit dependencies. See [clients/ios/README.md](../ios/README.md) for build instructions.
 
 **Code organization:**
 - `clients/shared/` — Shared library (IPC layer, chat models/ViewModels, design system)
@@ -179,13 +179,10 @@ The macOS app is a frontend — all inference (chat, computer-use sessions, ambi
 
 ```bash
 # Start the daemon (from the repo root)
-cd assistant && bun run dev
-
-# Or use the CLI
 cd assistant && bun run src/index.ts daemon start
 ```
 
-The app will auto-reconnect if the daemon restarts. For development, `bun run dev` runs in the foreground with auto-restart on file changes.
+The app will auto-reconnect if the daemon restarts.
 
 ## Permissions