docs: restructure and expand the product documentation

Splits the old user-guide and exec-mode pages into guides, configuration,
customization and reference sections behind a docs/README.md index, and moves
the plugin docs under customization/ so nothing is orphaned.

New pages cover the TUI, sessions, plan and spec modes, configuration files,
environment variables, data locations, agents, MCP, skills, hooks, themes, the
full CLI surface, tools, slash commands, keybindings, signing in and
troubleshooting. Every flag, key, tool and config key is taken from the clap
definitions and the TUI registries rather than invented, and the vendor model
names left in the imported pages are gone.

Co-authored-by: Mathis <echobt@users.noreply.github.com>

Author: cursoragent

.rules/docs.md

@@ -2,6 +2,9 @@
 
 - README must stay enough to build, log in to `api.cortex.foundation`, run the TUI, and run tests.
 - User-facing docs live in `docs/`. Do not invent a second docs site in-tree.
+- `docs/README.md` is the index. New pages go under `guides/`, `configuration/`, `customization/` or `reference/`, and get a row in the index.
+- Document only what the code supports. Check `cortex <command> --help` and the clap definitions before writing a flag down.
+- The README banner is `docs/media/intro.gif`, regenerated by `./scripts/render-demo-gif.sh`. Do not replace it with a hand-taken screenshot.
 - Product name is **Cortex CLI** / **Cortex Code**. Never Grok / Grok Bot / Grok-core.
 - Document CI secret *names* in `docs/CI_SECRETS.md`. Never commit values.
 - Changelog is `CHANGELOG.md`. Version-bump on `main` is the release note trigger.

AGENTS.md

@@ -73,6 +73,7 @@ Match CI (`.github/workflows/ci.yml`):
 
 | Need | Start here |
 |------|------------|
+| User docs index | [`docs/README.md`](docs/README.md) |
 | Security / exec / sandbox | [`.rules/security.md`](.rules/security.md) |
 | Product-facing errors | [`.rules/errors.md`](.rules/errors.md) |
 | TUI / responsive layout | [`.rules/tui.md`](.rules/tui.md) |

README.md

@@ -1,55 +1,145 @@
-# Cortex CLI / Cortex Code
+<h1 align="center">Cortex CLI</h1>
 
-The Cortex coding-agent harness: a CLI and TUI that talks to [api.cortex.foundation](https://api.cortex.foundation) for Chat/Code turns, tools, computers, plugins, and snapshots.
+<p align="center">
+  <strong>Cortex Code</strong> — a coding agent that runs in your terminal.
+</p>
 
-Auth is WorkOS session / existing `/v1` auth against `auth.cortex.foundation` and `api.cortex.foundation`. Credentials are stored in the OS keyring.
+<p align="center">
+  <a href="https://github.com/CortexLM/cli/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/CortexLM/cli/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="./LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
+  <a href="https://github.com/CortexLM/cli/releases"><img alt="Latest release" src="https://img.shields.io/github/v/tag/CortexLM/cli?label=release&sort=semver"></a>
+  <img alt="Built with Rust" src="https://img.shields.io/badge/built%20with-Rust-dea584.svg">
+</p>
 
-License: [Apache-2.0](./LICENSE).
+<p align="center">
+  <a href="./docs/README.md">Documentation</a> ·
+  <a href="./docs/guides/getting-started.md">Getting started</a> ·
+  <a href="./docs/reference/cli.md">CLI reference</a> ·
+  <a href="https://cortex.foundation">cortex.foundation</a>
+</p>
 
-## Build
+![Demo of Cortex CLI](./docs/media/intro.gif)
 
-Requires current stable Rust (see `rust-toolchain.toml`).
+## What is Cortex CLI
+
+Cortex CLI — also called **Cortex Code** — is a coding agent you run from a
+terminal in your project. Describe the change you want and it works through it:
+searching the codebase, reading the files that matter, editing them, running your
+build and tests, and reporting what it did. Every step shows up in the timeline
+as it happens, and you decide how much it can do without asking.
+
+One binary gives you:
+
+- **An interactive TUI** with a live timeline, tool approvals, plan and build
+  modes, session history, rewind and fork.
+- **Headless one-shot runs** for scripts and CI, with autonomy levels, structured
+  JSON output, and turn and time limits.
+- **The tools a coding agent needs** — search, read, edit, patch, shell
+  execution, language-server queries and web fetch — under an approval policy and
+  a sandbox you control.
+- **Extension points**: MCP servers, skills, custom agents and subagents, shell
+  hooks and WebAssembly plugins.
+
+Cortex CLI talks to the Cortex API at
+[api.cortex.foundation](https://api.cortex.foundation) and signs in through
+[auth.cortex.foundation](https://auth.cortex.foundation). Credentials are stored
+in your OS keyring.
+
+## Install
+
+### Linux and macOS
 
 ```bash
-# Linux deps used by optional audio / desktop crates
-sudo apt-get install -y libasound2-dev pkg-config
+curl -fsSL https://software.cortex.foundation/install.sh | sh
+```
+
+### Windows
+
+```powershell
+irm https://software.cortex.foundation/install.ps1 | iex
+```
 
+### From source
+
+Requires the toolchain pinned in [`rust-toolchain.toml`](./rust-toolchain.toml).
+
+```bash
 cargo build -p cortex-cli --release
 # binary: target/release/Cortex
 ```
 
-A debug build is enough for local work:
+On Linux, the optional audio and desktop crates need ALSA headers:
+`sudo apt-get install -y libasound2-dev pkg-config`.
+
+Full instructions, including Homebrew and WinGet, are in
+[Getting started](./docs/guides/getting-started.md).
+
+## Quick start
 
 ```bash
-cargo build -p cortex-cli
-./target/debug/Cortex --help
+cd ~/code/my-project
+cortex
+```
+
+That opens the session view from the recording above. Type what you want changed
+and press `Enter`:
+
+```
+> add a /healthz endpoint and cover it with a test
+```
+
+Press `Esc` to interrupt a turn, `Shift+Tab` to change how much autonomy the
+agent has, and `?` for help.
+
+Prefer one-shot? Both of these work without a terminal:
+
+```bash
+cortex run "explain the release process"
+cortex exec --auto read-only --git-diff "review my uncommitted changes"
 ```
 
 ## Login
 
 ```bash
-# Device-code / WorkOS browser login against the live Cortex API
-./target/debug/Cortex login
+cortex login
+```
+
+This opens the Cortex sign-in flow in your browser and stores the session in
+your OS keyring. For machines without a browser:
 
-# Or set a key (still stored via the keyring helpers when you login)
-export CORTEX_API_KEY=...
-# optional override; default is https://api.cortex.foundation
-export CORTEX_API_URL=https://api.cortex.foundation
+```bash
+cortex login --device-auth      # device-code flow
+cortex login --sso              # enterprise SSO
+cortex login --with-api-key     # read an API key from stdin
 ```
 
-`cortex login` opens the Cortex auth flow (`auth.cortex.foundation`). On success the session is written to the OS keyring (`cortex-cli` / `auth`).
+Check it worked with `cortex whoami`. See
+[Signing in](./docs/reference/login.md) for the full picture.
+
+## Documentation
 
-## Run the TUI
+| | |
+|---|---|
+| [Getting started](./docs/guides/getting-started.md) | Install, sign in, first session |
+| [The TUI](./docs/guides/tui.md) | Timeline, composer, modes, approvals |
+| [Sessions](./docs/guides/sessions.md) | Resume, export, import, share |
+| [Headless / exec mode](./docs/guides/exec.md) | Scripts and CI |
+| [Plan and Spec modes](./docs/guides/plan.md) | Approve a plan before anything changes |
+| [Configuration](./docs/configuration/config.md) | Files, keys, profiles, permissions |
+| [Agents](./docs/customization/agents.md) · [Skills](./docs/customization/skills.md) · [MCP](./docs/customization/mcp.md) · [Hooks](./docs/customization/hooks.md) · [Plugins](./docs/customization/plugins.md) | Extending Cortex |
+| [CLI reference](./docs/reference/cli.md) · [Tools](./docs/reference/tools.md) · [Slash commands](./docs/reference/slash-commands.md) · [Keyboard](./docs/reference/keyboard.md) | Reference |
+| [Troubleshooting](./docs/troubleshooting.md) | When something does not work |
+
+The index is at [docs/README.md](./docs/README.md).
+
+## Building and testing
 
 ```bash
-./target/debug/Cortex
-# or a one-shot turn
-./target/debug/Cortex "explain this repository"
+cargo build -p cortex-cli
+./target/debug/Cortex --help
 ```
 
-The TUI is the default when stdin is a TTY. If the coding API is unreachable you will see **The coding service is temporarily unavailable** — not a raw provider or HTTP-client name.
-
-## Tests
+The gates CI enforces:
 
 ```bash
 cargo fmt --all -- --check
@@ -59,7 +149,7 @@ cargo audit
 ./scripts/check-cli-version.sh
 ```
 
-Headless TUI / snapshot tests (required when you change a TUI surface):
+Headless TUI and snapshot tests, required whenever a TUI surface changes:
 
 ```bash
 cargo test -p cortex-tui -p cortex-tui-capture -p cortex-tui-components \
@@ -68,20 +158,33 @@ cargo test -p cortex-tui -p cortex-tui-capture -p cortex-tui-components \
   -p cortex-tui-input -p cortex-tui-terminal -p cortex-tui-syntax
 ```
 
-## Install from software.cortex.foundation
-
-Published artifacts (when a release is cut) are at [software.cortex.foundation](https://software.cortex.foundation):
+The banner above is generated from this repository, not captured by hand:
 
 ```bash
-curl -fsSL https://software.cortex.foundation/install.sh | sh
+./scripts/render-demo-gif.sh
 ```
 
+That records the session view headlessly through `cortex-tui-capture` and
+rasterises the frames into `docs/media/intro.gif`.
+
 ## Release and CI secrets
 
-Merges to `main` run `.github/workflows/version-bump.yml` (patch semver + tag). Tags run `.github/workflows/release.yml`, which can publish to R2 / `software.cortex.foundation` via `.github/workflows/publish-r2.yml`.
+Merges to `main` run [`.github/workflows/version-bump.yml`](.github/workflows/version-bump.yml),
+which patch-bumps the version and tags it. Tags run
+[`release.yml`](.github/workflows/release.yml), which can publish to
+[software.cortex.foundation](https://software.cortex.foundation) via
+[`publish-r2.yml`](.github/workflows/publish-r2.yml).
 
-This repo does **not** invent cloud accounts. Secret *names* CI already expects are listed in [docs/CI_SECRETS.md](docs/CI_SECRETS.md). Do not put secret values in git.
+This repository does not invent cloud accounts. The secret *names* CI expects are
+listed in [docs/CI_SECRETS.md](./docs/CI_SECRETS.md). Values never go in git.
 
 ## Contributing
 
-See [AGENTS.md](AGENTS.md), [`.rules/`](.rules/), and [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md). Every PR must fill the attestation list in `.github/PULL_REQUEST_TEMPLATE.md`.
+Start with [docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md), then
+[`AGENTS.md`](./AGENTS.md) and [`.rules/`](./.rules/). Every PR fills the
+attestation list in
+[`.github/PULL_REQUEST_TEMPLATE.md`](./.github/PULL_REQUEST_TEMPLATE.md).
+
+## Licence
+
+[Apache-2.0](./LICENSE).