@@ -9,7 +9,7 @@ The product is the **harness** — the loop that dispatches work, watches it,
 decides what happens next, and reports to the operator. Agent personas and
 skills are content that run inside it.
 
-## Quickstart
+## Install
 
 ### Homebrew (macOS / Linux)
 
@@ -42,201 +42,81 @@ ln -s "$PWD/dist/corbits" ~/.local/bin/corbits
 
 After pulling new changes, re-run `bun run build:bin` to refresh the binary.
 
-## Usage
-
-### TUI (default)
+## First run
 
 ```sh
 corbits "Add JWT auth to the API"
 ```
 
-Full-screen terminal UI (OpenTUI): event log, permission and operator prompts,
-diff and cost visibility, and a chat input for follow-ups. Press **Shift+Tab**
-to cycle reasoning effort for the current model; **Tab** toggles focus between
-the prompt and the transcript. See `docs/TUI.md`.
+That opens the full-screen terminal UI: event log, permission and operator
+prompts, diff and cost visibility, and a chat input for follow-ups. **Tab**
+toggles focus between the prompt and the transcript, **Shift+Tab** cycles
+reasoning effort, **Ctrl+C** interrupts a run, and `/help` lists the rest.
 
-### Exec (non-TUI)
+For scripts and CI, `corbits exec` runs the same directors, tools, permissions,
+MCP, plugins, and hooks without the terminal UI, streaming assistant text to
+stdout:
 
 ```sh
 corbits exec "Add JWT auth to the API"
-# alias:
-corbits run "Add JWT auth to the API"
 ```
 
-Same directors, tools, permissions, MCP, plugins, and hooks as the TUI — without
-the OpenTUI shell. Streams assistant text to stdout for scripts and CI.
-
-### Resume
-
-```sh
-corbits resume
-# or:
-corbits resume <session-id>
-```
-
-Plain `corbits` always starts a fresh conversation. `corbits resume` opens a
-picker of the 10 most recently persisted sessions for this checkout,
-including completed ones. Type to filter by name.
-
-### Mid-run steering
-
-While a run is in progress:
-
-- **Enter** — soft-steer while the parent is busy (in-flight tool / `wait_agents`); starts a new primary turn when the parent is idle with a fleet still running
-- **Alt+Enter** — queue a follow-up delivered when the whole session is idle
-- **Ctrl+C** — interrupt the run
-
-Shortcuts are listed in `/help`. Details live in `docs/PRODUCT.md`.
-
-## Permissions and auto mode
-
-Corbits Code defaults to **auto mode** (`auto = true`). Workspace file
-writes/edits/deletes and unconstrained shell commands run without per-action
-prompts. Pass `--no-auto` to start in ask-on-every-consequential-action mode
-(there is currently no in-session key to toggle auto).
-
-### What auto allows
-
-- File tools inside the workspace: `write_file`, `edit_file`, `delete_file` (and
-  other non-shell built-ins such as `manage_tasks`, `spawn_agent`, `wait_agents`, …)
-- Unconstrained shell (builds, tests, git, one-off commands that match no
-  deny/ask rule)
-- Read-only tools (`read_file`, `grep`, `search_files`, `list_dir`, `lsp`, …)
-  always allow regardless of mode
-
-### What still asks (even in auto)
-
-- Dependency installs and remote runners (`npm install` / `i` / `ci` / `add`,
-  `pip install`, `cargo add`, `brew install`, `npx` / `bunx`, …)
-- Recursive `rm` (`-r` / `-R` / `--recursive`)
-- Force or uncontained git worktree add/remove/prune (contained non-force
-  add/remove/prune and read-only `git worktree list` auto-allow)
-- Shell that references sensitive paths (`.env`, private keys, certs, credential
-  files, …)
-- Opaque shell wrappers the policy cannot statically inspect (variable expansion
-  or command substitution in a wrapper payload)
-- Shell that references a path outside the workspace
-- Writes under the in-workspace session state root, mutating MCP
-  tools, and unknown built-ins
-
-### What auto hard-denies (use the file tools instead)
-
-- File creation or edits via shell: redirects (`>` / `>>`), `tee`, `sed -i` /
-  `perl -i` / similar, interpreter inline programs or heredocs (`python -c`,
-  `node -e`, …)
-
-Wrappers such as `bash -c '…'`, `sh`/`zsh -c`, `xargs`, and transparent prefixes
-(`env`, `nice`, `timeout`) are peeled so the same rules apply to the inner
-command. Unparseable wrappers fall through to ask rather than auto-allow.
-
-Catastrophic patterns (`rm -rf /`, `sudo`, `curl | bash`, force-push, open-ended
-`find`/`rg`/`grep -r`, …) are always denied by authorization, independent of
-auto mode. `--dangerously-skip-permissions` still forces this process; `/yolo`
-persists as the user-global default. Both bypass the permission gate (not
-secret-guard path denies or authz hard blocks).
-
-Details live in `docs/PRODUCT.md` (safety model) and `docs/ARCHITECTURE.md`
-(permission gate and auto-shell policy).
-
-## Stack
-
-- **Runtime:** Bun + TypeScript
-- **Agent loop:** `@intx/agent` with an event-driven reactor
-- **Inference:** `@intx/inference` (vendored) with OpenAI-compatible adapters
-- **Tools:** `@intx/tools-posix` and `@intx/tools-lsp`
-- **Authz:** `@intx/authz` for grant matching; Corbits owns the gate, store, and TUI ask
-- **Persistence:** `@intx/storage-isogit` for git-backed resume
-- **MCP:** Model Context Protocol SDK for external tool servers
-- **TUI:** OpenTUI (`@opentui/core`)
-
-## Architecture
-
-Corbits Code is a single-process CLI built on Interchange primitives. The primary
-session is always the **orchestrator** (Skywalker): it can act directly and
-delegates substantial work through a closed director fleet via `spawn_agent`
-then idle (mailbox mail inbound) and `search_agents`. `wait_agents` stays
-mounted only on headless `corbits exec` primary runs.
-
-```
-CLI (src/index.ts)
-  → load config / settings
-  → runTUI (default) or runExec (corbits exec | run)
-  → create agent with ChatDirector, posix tools, permission gate
-  → mount plugins, MCP, hooks, skills
-  → primary orchestrator turn
-       ↳ spawn_agent then idle → mailbox mail inbound → closed directors (builder, explorer, …)
-  → event stream → OpenTUI host (TUI) or stdout (exec)
-```
+`corbits resume` reopens one of the 10 most recent sessions for this checkout;
+plain `corbits` always starts fresh.
 
-The chat director adds context management on top of the reactor:
+Behavior, keybindings, and steering in depth: `docs/TUI.md` and
+`docs/PRODUCT.md`.
 
-- **Threshold compaction:** As the context window fills, the conversation is
-  compacted at the next safe point.
-- **Idle compaction:** A pending compaction also runs when a turn ends without
-  more work, so a text-only conversation still compacts.
-- **Overflow recovery:** A context-overflow error triggers a bounded
-  compact-and-retry instead of failing the turn.
-- **Workflow nudges:** When a workflow is active, the director keeps the run on
-  the current step and surfaces a visible message if it stalls.
+## Permissions
 
-Deep design: `docs/ARCHITECTURE.md`, `docs/IMPLEMENTATION.md`, `docs/PRODUCT.md`.
+Corbits Code defaults to **auto mode**, where workspace file edits and ordinary
+shell commands run without a prompt so a long task is not interrupted every few
+seconds. It still stops and asks before anything consequential — dependency
+installs, recursive deletes, touching paths outside the workspace or anything
+that looks like a credential — and it refuses outright to edit files through
+shell redirects or `sed -i` when the file tools exist for that. Catastrophic
+patterns are denied by authorization regardless of mode.
 
-## Extensibility
+Start with `--no-auto` to be asked before every consequential action.
 
-- **Plugins** — discovery and manifests: `docs/PLUGINS.md`
-- **MCP** — connect external tool servers: `docs/MCP.md`
-- **Hooks** — lifecycle hooks: `docs/HOOKS.md`
-- **Skills / slash commands** — first-party actions such as `/implement`,
-  `/plan`, `/review`, `/create-issue` ship with the `corbits-skills` plugin (on
-  by default; toggle in `/plugins`)
+The full policy — every rule, what is peeled from wrappers, and how the gate
+composes with authorization — is in `docs/ARCHITECTURE.md`, with the safety
+model behind it in `docs/PRODUCT.md`.
 
-## Agent workspace
+## Where to go next
 
-Corbits Code keeps repository guidance and the closed director fleet separate:
-
-- `AGENTS.md` — shared startup instructions and project context
-- `src/agent/directors/` — closed spawn catalog (`directorProfiles()`). Skywalker
-  is the primary orchestrator; spawnable directors include builder, explorer,
-  counsel, intern, critic, greybeard, neckbeard, bruckheimer, gaasbot, draper,
-  emil, rand, shakespeare, testsmith, tester, gauntlet, prober, migrator, and warden. Closed ids cannot be
-  overridden by plugins or local files.
-- `.agents/agents/` — optional local profile additions; this directory is not
-  required and may be absent
+| Doc                      | Covers                                  |
+| ------------------------ | --------------------------------------- |
+| `docs/PRODUCT.md`        | What we are building and why            |
+| `docs/ARCHITECTURE.md`   | Reactor, directors, permissions, exec   |
+| `docs/IMPLEMENTATION.md` | Runtime, config, CLI flags, persistence |
+| `docs/TUI.md`            | Terminal UI behavior                    |
+| `docs/PLUGINS.md`        | Plugin manifests and discovery          |
+| `docs/MCP.md`            | MCP servers                             |
+| `docs/HOOKS.md`          | Lifecycle hooks                         |
+| `docs/TELEMETRY.md`      | Usage telemetry                         |
+| `docs/PERFTRACE.md`      | Local PerfTrace / OTEL export           |
+| `docs/VENDORING.md`      | Vendored Interchange packages           |
 
-Named workers resolve through `spawn_agent(agent=...)`: closed directors first,
-then enabled agent plugins, then local `.agents/agents/*.json|*.yaml` profiles.
-Use `search_agents` to discover ids before dispatching.
+`AGENTS.md` carries the repository's own instructions to agents working in it —
+conventions, scope discipline, and how to validate a change.
 
 ## Contributing
 
 Before your first commit: `git config core.hooksPath .githooks` and
 `./bin/check-env`.
 
 Every change must pass `bun run check` (lint, typecheck, build, and test).
-Behavior changes come with tests. Coding conventions live in `AGENTS.md`
-(functional TypeScript, no classes, arktype at boundaries); commit, PR, and
-Linear/GitHub linking rules live in `CONTRIBUTING.md`.
+Behavior changes come with tests. Coding conventions live in `AGENTS.md`;
+commit, pull request, and Linear/GitHub linking rules live in
+`CONTRIBUTING.md`, and a pull request that does not follow them will be
+declined.
 
 ```bash
 bun install
 bun run check
 ```
 
-## Docs
-
-| Doc                      | Covers                                  |
-| ------------------------ | --------------------------------------- |
-| `docs/PRODUCT.md`        | What we are building and why            |
-| `docs/ARCHITECTURE.md`   | Reactor, directors, permissions, exec   |
-| `docs/IMPLEMENTATION.md` | Runtime, config, CLI flags, persistence |
-| `docs/TUI.md`            | Terminal UI behavior                    |
-| `docs/PLUGINS.md`        | Plugin manifests and discovery          |
-| `docs/MCP.md`            | MCP servers                             |
-| `docs/HOOKS.md`          | Lifecycle hooks                         |
-| `docs/TELEMETRY.md`      | Usage telemetry                         |
-| `docs/PERFTRACE.md`      | Local PerfTrace / OTEL export           |
-| `docs/VENDORING.md`      | Vendored Interchange packages           |
-
 ## License
 
 Copyright (C) 2026 ABK Labs, Inc.