Revise README for AI agent terminal features

README.md

@@ -6,7 +6,19 @@
 
 ![Architect Hero](docs/assets/architect-hero.png)
 
-A terminal emulator that displays a configurable grid of interactive terminal sessions with smooth expand/collapse animations. Built on ghostty-vt for terminal emulation and SDL3 for rendering.
+A terminal built for multi-agent AI coding workflows. Run Claude Code, Codex, or Gemini in parallel and see at a glance which agents need your attention.
+
+Built on [ghostty-vt](https://github.com/ghostty-org/ghostty) for terminal emulation and SDL3 for rendering.
+
+## Why Architect?
+
+Running multiple AI coding agents is the new normal. But existing terminals weren't built for this:
+
+- **Agents sit idle** waiting for approval while you're focused elsewhere
+- **Context switching** between tmux panes or tabs kills your flow
+- **No visibility** into which agent needs attention right now
+
+Architect solves this with a grid view that keeps all your agents visible, with **status-aware highlighting** that shows you instantly when an agent is awaiting approval or has completed its task.
 
 > [!WARNING]
 > **This project is in the early stages of development. Use at your own risk.**
@@ -15,6 +27,21 @@ A terminal emulator that displays a configurable grid of interactive terminal se
 
 ![Architect Demo](docs/assets/architect-demo.gif)
 
+## Features
+
+### Agent-Focused
+- **Status highlights** — agents glow when awaiting approval or done, so you never miss a prompt
+- **Grid view** — keep 4+ agents visible simultaneously, expand any one to full screen
+- **Worktree picker** (⌘T) — quickly `cd` into git worktrees for parallel agent work on separate branches
+
+### Terminal Essentials
+- Smooth expand/collapse animations between grid and focused views
+- Keyboard navigation: ⌘+Return to expand, ⌘1–⌘0 to switch, ⌘W to close, ⌘/ for shortcuts
+- Scrollback with trackpad/wheel support and grid indicator when scrolled
+- OSC 8 hyperlink support (Cmd+Click to open)
+- Kitty keyboard protocol for enhanced key handling
+- Persistent window state and font size across sessions
+
 ## Installation
 
 ### Download Pre-built Binary (macOS)
@@ -38,8 +65,9 @@ open Architect.app
 ```
 
 **Note**:
-- The archive contains `Architect.app`. You can launch it with `open Architect.app` or run `./Architect.app/Contents/MacOS/architect` from the terminal. Keep the bundle contents intact.
-- Not sure which architecture? Run `uname -m` - if it shows `arm64`, use the ARM64 version; if it shows `x86_64`, use the Intel version.
+
+* The archive contains `Architect.app`. You can launch it with `open Architect.app` or run `./Architect.app/Contents/MacOS/architect` from the terminal. Keep the bundle contents intact.
+* Not sure which architecture? Run `uname -m` - if it shows `arm64`, use the ARM64 version; if it shows `x86_64`, use the Intel version.
 
 ### Homebrew (macOS)
 
@@ -49,7 +77,6 @@ xcode-select --install
 ```
 
 Install via Homebrew (builds from source):
-
 ```bash
 # Tap the repository (note: requires full repo URL since the formula is in the main repo)
 brew tap forketyfork/architect https://github.com/forketyfork/architect
@@ -62,7 +89,6 @@ cp -r $(brew --prefix)/Cellar/architect/*/Architect.app /Applications/
 ```
 
 Or install directly without tapping:
-
 ```bash
 brew install https://raw.githubusercontent.com/forketyfork/architect/main/Formula/architect.rb
 cp -r $(brew --prefix)/Cellar/architect/*/Architect.app /Applications/
@@ -71,46 +97,41 @@ cp -r $(brew --prefix)/Cellar/architect/*/Architect.app /Applications/
 ### Build from Source
 
 See `docs/development.md` for the full development setup. Quick start:
-
 ```bash
 nix develop
 just build
 ```
 
-## Features
-
-- Configurable grid of terminal sessions with smooth expand/collapse animations
-- Full-window terminal rendering scaled down for grid view
-- Keyboard navigation (⌘+Return to expand, ⌘1–⌘0 to switch, ⌘W to close, ⌘/ for shortcuts, ⌘T for worktrees)
-- Scrollback with hover wheel/trackpad support and a grid indicator when scrolled
-- Worktree picker for quick `cd` into git worktrees
-- Persistent window and font size state; terminal cwd restore on macOS
-- Cmd+Click opening for OSC 8 hyperlinks
-- AI assistant status highlights (awaiting approval / done)
-- Kitty keyboard protocol support for enhanced key handling
-
 ## Configuration
 
 Architect stores configuration in `~/.config/architect/`:
 
-- `config.toml`: read-only user preferences (edit via `⌘,`).
-- `persistence.toml`: runtime state (window position/size, font size), managed automatically.
+* `config.toml`: read-only user preferences (edit via `⌘,`).
+* `persistence.toml`: runtime state (window position/size, font size), managed automatically.
 
 Common settings include font family, theme colors, and grid rows/cols. Remove the files to reset to the default values.
 
 ## Troubleshooting
 
-- **App won’t open (Gatekeeper)**: run `xattr -dr com.apple.quarantine Architect.app` after extracting the release.
-- **Font not found**: ensure the font is installed and set `font.family` in `config.toml`. The app falls back to `SFNSMono` on macOS.
-- **Reset configuration**: delete `~/.config/architect/config.toml` and `~/.config/architect/persistence.toml`.
-- **Known limitations**: emoji fallback is macOS-only; keybindings are currently fixed.
+* **App won't open (Gatekeeper)**: run `xattr -dr com.apple.quarantine Architect.app` after extracting the release.
+* **Font not found**: ensure the font is installed and set `font.family` in `config.toml`. The app falls back to `SFNSMono` on macOS.
+* **Reset configuration**: delete `~/.config/architect/config.toml` and `~/.config/architect/persistence.toml`.
+* **Known limitations**: emoji fallback is macOS-only; keybindings are currently fixed.
 
 ## Documentation
 
-- `docs/architecture.md`: architecture overview and system boundaries.
-- `docs/configuration.md`: detailed configuration reference for `config.toml` and `persistence.toml`.
-- `docs/development.md`: build, test, release, and assistant hook setup.
-- `CLAUDE.md`: agent guidelines for code assistants.
+* `docs/architecture.md`: architecture overview and system boundaries.
+* `docs/configuration.md`: detailed configuration reference for `config.toml` and `persistence.toml`.
+* `docs/development.md`: build, test, release, and assistant hook setup.
+* `CLAUDE.md`: agent guidelines for code assistants.
+
+## Related Tools
+
+Architect is part of a suite of tools I'm building for AI-assisted development:
+
+- [**Stepcat**](https://github.com/forketyfork/stepcat) — Multi-step agent orchestration with Claude Code and Codex
+- [**Marx**](https://github.com/forketyfork/marx) — Run Claude, Codex, and Gemini in parallel for PR code review
+- [**Claude Nein**](https://github.com/forketyfork/claude-nein) — macOS menu bar app to monitor Claude Code spending
 
 ## License