diff --git a/README.md b/README.md
index f6bb89ba..79a39e03 100644
--- a/README.md
+++ b/README.md
@@ -76,7 +76,7 @@ Plus any OpenAI-compatible endpoint: `agent --api-base-url http://localhost:8080
 
 File ops, search, shell, git, web, LSP, MCP, notebooks, tasks, and more. Tools execute during LLM streaming for faster turns. [Full list →](docs/reference/tools.mdx)
 
-## 12 Bundled Skills
+## 18 Bundled Skills
 
 | Skill | Purpose |
 |-------|---------|
@@ -92,6 +92,12 @@ File ops, search, shell, git, web, LSP, MCP, notebooks, tasks, and more. Tools e
 | `/advisor` | Architecture and dependency health analysis |
 | `/bughunter` | Systematic bug search |
 | `/plan` | Structured implementation planning |
+| `/changelog` | Generate changelog entries from commit history |
+| `/release` | Cut a versioned release |
+| `/benchmark` | Run and compare benchmarks |
+| `/coverage` | Measure and report test coverage |
+| `/migrate` | Apply codebase-wide migrations |
+| `/docs` | Generate or update documentation |
 
 Add custom skills as markdown files in `.agent/skills/` or `~/.config/agent-code/skills/`.
 
@@ -122,15 +128,21 @@ disable_bypass_permissions = true
 crates/
   lib/   agent-code-lib    Engine: providers, tools, query loop, memory
   cli/   agent-code        Binary: REPL, TUI, commands, setup wizard
+  eval/  agent-code-eval   Evaluation harness for benchmarking the engine
+
+packages/
+  agent_code_client        Dart client library for talking to the engine
+
+client/                    Cross-platform Flutter desktop/web GUI (see client/README.md)
 ```
 
-The engine is a reusable library. The binary is a thin wrapper.
+The engine is a reusable library. The CLI binary is a thin wrapper. The Flutter client in `client/` is a separate front-end that talks to the engine via the `agent_code_client` package.
 
-## 43 Slash Commands
+## 52 Slash Commands
 
 Session management, context control, git operations, agent coordination, configuration, diagnostics, and more. [Full list →](docs/reference/commands.mdx)
 
-Highlights: `/release-notes`, `/summary`, `/feedback`, `/share`, `/update`, `/doctor`, `/plan`, `/model`, `/cost`, `/scroll`, `/rewind`, `/fork`
+Highlights: `/release-notes`, `/summary`, `/feedback`, `/share`, `/update`, `/uninstall`, `/doctor`, `/plan`, `/model`, `/cost`, `/scroll`, `/rewind`, `/fork`
 
 ## Security
 
@@ -151,7 +163,7 @@ Protected directories (`.git/`, `.husky/`, `node_modules/`) are blocked from wri
 git clone https://github.com/avala-ai/agent-code.git
 cd agent-code
 cargo build
-cargo test    # 225+ tests
+cargo test    # 650+ tests
 cargo clippy  # zero warnings
 ```
 
diff --git a/client/README.md b/client/README.md
index 36886a2b..e7f379ce 100644
--- a/client/README.md
+++ b/client/README.md
@@ -1 +1,72 @@
 # Agent Code Client
+
+Cross-platform Flutter front-end for [Agent Code](../README.md). Provides a desktop and web GUI that talks to the Rust engine through the `agent_code_client` Dart package in `../packages/agent_code_client`.
+
+The Rust CLI (`crates/cli`) and this client are independent surfaces over the same engine — neither embeds the other. Use the CLI for terminal workflows; use this client when you want a graphical session view, point-and-click skills, or a browser-hosted agent.
+
+## Platforms
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| macOS    | ✅     | `client/macos/` |
+| Linux    | ✅     | `client/linux/` |
+| Web      | ✅     | `client/web/` |
+| Windows  | ❌     | not yet — contributions welcome |
+
+## Stack
+
+- Flutter `>= 3.19.0`, Dart SDK `>= 3.0.0` (the repo pins **3.41.6** via `.fvmrc`)
+- State management: `flutter_bloc` (`SessionBloc` in `lib/`)
+- Markdown rendering: `flutter_markdown`
+- Local package dependency: `agent_code_client` (`../packages/agent_code_client`) — handles transport to the engine and abstracts native vs. web execution
+
+See `pubspec.yaml` for the full dependency list.
+
+## Quickstart
+
+Install [FVM](https://fvm.app/) so you pick up the pinned Flutter version automatically:
+
+```bash
+cd client
+fvm install            # one-time, reads .fvmrc
+fvm flutter pub get
+fvm flutter run        # picks the connected device; pass -d macos / -d linux / -d chrome
+```
+
+If you don't use FVM, plain `flutter` works too — just make sure your local Flutter is `>= 3.19.0`.
+
+## Tests
+
+```bash
+# Unit / widget tests
+fvm flutter test
+
+# Integration tests (in-process, runs against a real engine)
+fvm flutter test integration_test/app_test.dart -d chrome
+# headless:
+fvm flutter test integration_test/app_test.dart -d web-server
+
+# End-to-end browser tests (Playwright, see e2e/playwright.config.ts)
+cd e2e
+npm install
+npx playwright test
+```
+
+## Layout
+
+```
+client/
+  lib/                   Dart source (app shell, session BLoC, screens, widgets)
+  test/                  Unit and widget tests
+  integration_test/      In-process Flutter integration tests
+  test_driver/           Drivers for `flutter drive`
+  e2e/                   Playwright end-to-end browser tests (separate npm project)
+  macos/  linux/  web/   Per-platform Flutter scaffolding
+  pubspec.yaml           Dart/Flutter manifest
+  analysis_options.yaml  Lint rules (flutter_lints)
+  .fvmrc                 Pinned Flutter version (3.41.6)
+```
+
+## Contributing
+
+The client follows the same contribution flow as the rest of the repo — see [`../CONTRIBUTING.md`](../CONTRIBUTING.md). Run `fvm flutter analyze` and `fvm flutter test` before opening a PR. CI runs the integration suite on Chrome via `chromedriver` and the Playwright e2e suite on the built web bundle.