docs: a quickstart that is two commands, and CLIs called by their names

The home page's Run a flow listed eleven agent strings in a table, set a shell variable,
and walked through chat, hmz exec, a loop and a trace before anybody had run anything.
It is now: install it, make a repository with a bug in it, pick your CLI from a tab, and
run ralph_loop -- once at the prompt and once without it. Nothing else, and no
environment variable to export.

Everywhere else, a backend is called what its makers call it. The short name stays where
it is the thing you type -- an -a spec, a binary on PATH, a row key in a reference table
-- and Antigravity CLI, Grok Build, DeepSeek Harness and the rest are spelled out in
prose. cursor-agent was missing from both lists of what may be on PATH.

Author: futrime

README.md

@@ -50,9 +50,9 @@ npm install --global @deepseek-ai/dsh
 dsh web
 ```
 
-Needs Python ≥ 3.12 and at least one supported backend: `agy`, `claude`, `codex`, `grok`,
-`kimi`, `pi`, `qwen`, `opencode`, `mimo` or `zcode` on your PATH — or none of them, since
-DeepSeek Harness arrives with humanize. See
+Needs Python ≥ 3.12 and at least one supported backend: `agy`, `claude`, `codex`,
+`cursor-agent`, `grok`, `kimi`, `pi`, `qwen`, `opencode`, `mimo` or `zcode` on your PATH — or
+none of them, since DeepSeek Harness arrives with humanize. See
 [Installation](https://docs.humanfia.ai/humanize2/user/installation).
 
 ## Usage

docs/index.md

@@ -15,7 +15,7 @@ import { withBase } from 'vitepress'
 ## Run a flow
 
 ::: warning Use a scratch directory
-humanize runs every agent with permission prompts disabled. An agent under it edits files
+humanize runs every agent with permission prompts disabled: an agent under it edits files
 without asking. Do this in a throwaway git repository, and read [Security](/user/security)
 before you point it at work you care about.
 :::
@@ -26,141 +26,136 @@ already log in.
 
 ```sh
 pip install git+https://github.com/humanfia/humanize2.git
-hmz --version
 ```
 
-### Name an agent
-
-An agent is written `cli/model:effort` — the CLI that runs the turn, the model it asks for, and
-how hard that model should think. Put yours in a shell variable, and every command below is one
-you can paste:
+Then make something for it to fix. `calc.py` subtracts where it should add, and that bug is the
+work:
 
 ```sh
-AGENT=claude/claude-opus-4-8:high
+mkdir -p ~/tmp/humanize-demo && cd ~/tmp/humanize-demo && git init -q
+printf 'def add(a, b):\n    return a - b\n' > calc.py
+git add -A && git commit -qm "a calculator with a bug in it"
 ```
 
-| CLI | Write it as |
-| --- | --- |
-| Claude Code | `claude/claude-opus-4-8:high` |
-| Codex | `codex/gpt-5.6-sol:high` |
-| Kimi Code | `kimi/kimi-code/k3:high` |
-| Qwen Code | `qwen/qwen3-coder-plus:high` |
-| Grok Build | `grok/grok-4.6:high` |
-| Antigravity CLI | `agy/gemini-3.7-flash-high:high` |
-| pi | `pi/openai-codex/gpt-5.6-luna:high` |
-| opencode | `opencode/opencode/big-pickle:high` |
-| mimocode | `mimo/mimo/mimo-auto:high` |
-| ZCode | `zcode/zai/glm-5.3:high` |
-| DeepSeek Harness | `dsh/deepseek-v4-flash:high`, with `export DEEPSEEK_API_KEY=sk-…` |
-
-Those are examples, not a fixed list, and not every backend humanize drives is in it — [Many
-backends, one agent](/features/backends) is all of them against what a flow may ask of each. A
-model id is whatever that CLI shipped this week, and which ones you may name depends on the
-account you are logged in as — `pi`, `opencode`, `mimo` and `zcode` write a model as
-`provider/id`, which is the extra slash in their rows. To see what yours offers, open `/flow`
-in the interface and turn to its agents. Get the id wrong and the backend says so on the first
-turn:
+Both ways below run the same flow, `ralph_loop`: it gives the agent the same task over and over
+in a fresh conversation each time, so it restarts from the task and the repository rather than
+from a context window full of its own earlier attempts. Pick the tab for the CLI you have.
 
-```console
-[claude-code:unrecognized_model] {"model":"not-a-real-model","query_source":"sdk"}
+### At the prompt
+
+::: code-group
+
+```sh [Claude Code]
+hmz -f ralph_loop -a claude/claude-opus-4-8:high
 ```
 
-### Say something
+```sh [Codex]
+hmz -f ralph_loop -a codex/gpt-5.6-sol:high
+```
 
-```sh
-mkdir -p ~/tmp/humanize-demo && cd ~/tmp/humanize-demo && git init -q
-printf 'def add(a, b):\n    return a - b\n' > calc.py
-git add -A && git commit -qm "a calculator with a bug in it"
-hmz
+```sh [Antigravity CLI]
+hmz -f ralph_loop -a agy/gemini-3.7-flash-high:high
 ```
 
-`calc.py` subtracts where it should add — that bug is the work. `hmz` is the only way into the
-terminal interface; there is no `hmz tui`. Type a line and press enter, and the agent takes a
-**turn**: one exchange with the model, which may run tools and may take minutes.
+```sh [Qwen Code]
+hmz -f ralph_loop -a qwen/qwen3-coder-plus:high
+```
 
-| While a turn is running | |
-| --- | --- |
-| Type another line | It goes *into* the turn rather than starting a new one — [Talking to a running turn](/user/steering) |
-| `/details` | Show the tool calls and the thinking, or only what the agent says |
-| `/status` | Who is working, who handed to whom, and what it has cost |
-| `/` | Every command, with a line about each; **tab** takes the highlighted one |
+```sh [Kimi Code]
+hmz -f ralph_loop -a kimi/kimi-code/k3:high
+```
+
+```sh [Grok Build]
+hmz -f ralph_loop -a grok/grok-4.6:high
+```
 
-Underneath, humanize is running a **flow** called `chat` — one agent, one conversation, and
-every line you type is the next turn of it. `/exit` leaves. The run is [held apart from this
-terminal](/reference/daemon), so it goes on running if you say to leave it, which is what
-`/detach` says outright.
+```sh [ZCode]
+hmz -f ralph_loop -a zcode/zai/glm-5.3:high
+```
 
-### Run it unattended
+:::
 
-```sh
-hmz exec -f chat -a "$AGENT" "What does calc.py do?"
+That opens the terminal interface, set up and waiting. Type the task and press enter:
+
+```
+Fix the bug in calc.py.
 ```
 
-`-f` names the flow, `-a` describes one agent and is repeated once for every agent the flow
-drives in the order the flow takes them, and the last argument is the task. Get the count wrong
-and humanize refuses before any agent runs, rather than failing hours in:
+The agent takes a **turn** — one exchange with the model, which may run tools and may take
+minutes — and then the loop gives it the same task again. Type another line while it is working
+and it goes *into* the running turn rather than starting a new one. `/` lists every command,
+**ctrl+c** twice stops the loop, and `/exit` leaves.
 
-```console
-$ hmz exec -f official/rlar -a claude/claude-opus-4-8:high "fix the build"
-hmz exec: error: official/rlar: the flow drives 2 agents, 1 given
+### Or without the interface
+
+The same flow, the same agent, with the task on the line instead:
+
+::: code-group
+
+```sh [Claude Code]
+hmz exec -f ralph_loop -a claude/claude-opus-4-8:high "Fix the bug in calc.py."
 ```
 
-### Put a loop around it
+```sh [Codex]
+hmz exec -f ralph_loop -a codex/gpt-5.6-sol:high "Fix the bug in calc.py."
+```
 
-A **Ralph loop** gives the agent the same task over and over, in a fresh conversation each
-time, so it restarts from the task and the repository instead of from a context window full of
-its own earlier attempts.
+```sh [Antigravity CLI]
+hmz exec -f ralph_loop -a agy/gemini-3.7-flash-high:high "Fix the bug in calc.py."
+```
 
-```sh
-hmz exec -f ralph_loop -a "$AGENT" "Fix the bug in calc.py."
+```sh [Qwen Code]
+hmz exec -f ralph_loop -a qwen/qwen3-coder-plus:high "Fix the bug in calc.py."
 ```
 
-::: warning A Ralph loop does not stop on its own
-That is what it is for — you leave one running for hours. Press **ctrl+c** twice when you have
-seen enough. Every round is written down, so stopping loses nothing.
-:::
+```sh [Kimi Code]
+hmz exec -f ralph_loop -a kimi/kimi-code/k3:high "Fix the bug in calc.py."
+```
 
-```diff
- def add(a, b):
--    return a - b
-+    return a + b
+```sh [Grok Build]
+hmz exec -f ralph_loop -a grok/grok-4.6:high "Fix the bug in calc.py."
 ```
 
-It made that edit with **no permission prompt**. There is no setting that turns them back on.
+```sh [ZCode]
+hmz exec -f ralph_loop -a zcode/zai/glm-5.3:high "Fix the bug in calc.py."
+```
+
+:::
 
-### Read the whole run back
+`-f` names the flow and `-a` names one agent, written `cli/model:effort` — the CLI that runs
+the turn, the model it asks for, and how hard that model should think. A Ralph loop does not
+stop on its own, which is what it is for: **ctrl+c** at the command line when you have seen
+enough. Every round is written down, so stopping loses nothing.
 
-Every run writes down what it was: the flow, the agents, and the id of every conversation they
-opened. Turn that plus the backends' own transcripts into one timeline:
+Either way, check the work:
 
 ```sh
-hmz trace collect
+git diff
 ```
 
-```console
-~/.humanize/epics/-tmp-humanize-demo/20260817T021608.271Z-e000e6/traces/20260817T022635Z.trace.json of 20260817T021608.271Z-e000e6: 15 sessions, 240 slices
+```diff
+ def add(a, b):
+-    return a - b
++    return a + b
 ```
 
-Drag that file into [ui.perfetto.dev](https://ui.perfetto.dev). Each agent becomes a process,
-each of its conversations a track, and each slice one thing the agent did — with the prompt,
-the reasoning, the tool input and the tool output attached. For a nine-hour run it is the only
-view that fits on a screen.
+It made that edit with **no permission prompt**, and there is no setting that turns them back
+on. That is the one thing to have understood before pointing this at a real repository.
 
-| What you now know | |
-| --- | --- |
-| **turn** | One exchange with the model |
-| **session** | A conversation held across turns |
-| **flow** | A directory of Python driving one or more agents |
-| **epic** | One run of a flow, written down under `~/.humanize/epics/` |
-| `hmz` | The interface |
-| `hmz exec -f FLOW -a CLI/MODEL:EFFORT "task"` | The same flows, unattended |
-| `hmz trace collect` | The run as a timeline |
-
-**Next.** The [User Guide](/user/) has a page per thing humanize does, and its tutorials each
-take a real piece of work from start to finish: [Beat a benchmark](/user/tutorials/take-home),
-[Port a project](/user/tutorials/port-a-project), and [Build a coding
-agent](/user/tutorials/build-an-agent). For the words above, properly defined, read
-[Concepts](/user/concepts).
+::: details The model id is wrong, or your CLI is not above
+A model id is whatever that CLI shipped this week, and which ones you may name depends on the
+account you are logged in as. Open `/flow` in the interface and turn to its agents: humanize
+asks each CLI once and keeps the answer. Every backend it drives, including the ones not in
+those tabs, is in [Many backends, one agent](/features/backends);
+[Installation](/user/installation) is how to sign each one in.
+:::
+
+**Next.** [`hmz trace collect`](/user/tracing) turns the whole run into one timeline you can
+open in Perfetto. The [User Guide](/user/) has a page per thing humanize does, and its
+tutorials each take a real piece of work start to finish: [Beat a
+benchmark](/user/tutorials/take-home), [Port a project](/user/tutorials/port-a-project), and
+[Build a coding agent](/user/tutorials/build-an-agent). For the words above, properly defined,
+read [Concepts](/user/concepts).
 
 ## Weave a flow
 

docs/reference/agents.md

@@ -139,7 +139,8 @@ it finds out the account went down, how many times it was tried, and where the t
 Two edges worth knowing. A model is the account's: a chain that lands on an account whose
 catalogue does not hold this agent's model fails for a second, unrelated reason, and moving an
 agent's account is not moving its model. And whatever the agent was holding open — a Claude
-process, a Codex server, a dsh runtime — was started as the account it has left, so it is let
+process, a Codex server, a DeepSeek Harness runtime — was started as the account it has left,
+so it is let
 go of as the agent moves and the next turn opens one as whoever the agent now is.
 
 ## A CLI of your own

docs/reference/flows.md

@@ -381,8 +381,8 @@ Several moments are several arguments.
 
 **A goal is asked for the same way.** `agent.pursue(objective)` is the backend's own goal
 feature — the agent decides for itself that the objective has been met, and until it does, a
-turn that would have ended starts another. Five backends have one (Claude Code, codex, dsh,
-Kimi, ZCode), so a flow built on it says so:
+turn that would have ended starts another. Five backends have one (Claude Code, Codex, DeepSeek
+Harness, Kimi Code and ZCode), so a flow built on it says so:
 
 ```python
 from hmz.flows import Agent, Goal

docs/reference/providers.md

@@ -89,7 +89,7 @@ An answer in parentheses is what a question takes when you say nothing. A way wi
 its own runs it on this terminal, under the provider's paths, and what it writes is the provider;
 a way that is only answers keeps them as the variables the backend reads them under.
 
-**claude**
+**Claude Code** (`claude`)
 
 | Way | | Asks for |
 | --- | --- | --- |
@@ -100,7 +100,7 @@ a way that is only answers keeps them as the variables the backend reads them un
 | `bedrock` | Anthropic's models on an AWS account of yours. Also sets `CLAUDE_CODE_USE_BEDROCK=1`. | `AWS_PROFILE`, `AWS_REGION` (`us-east-1`) |
 | `vertex` | Anthropic's models on a Google Cloud project of yours. Also sets `CLAUDE_CODE_USE_VERTEX=1`. | `ANTHROPIC_VERTEX_PROJECT_ID`, `CLOUD_ML_REGION` (`us-east5`) |
 
-**codex**
+**Codex** (`codex`)
 
 | Way | | Asks for |
 | --- | --- | --- |
@@ -115,7 +115,7 @@ Codex takes a provider as settings rather than as variables, so a turn under `ga
 `config.toml` is written. The key of the `key` way is read by `codex login` off its standard
 input and kept in codex's own store, so it is not kept a second time as a variable.
 
-**kimi**
+**Kimi Code** (`kimi`)
 
 | Way | | Asks for |
 | --- | --- | --- |
@@ -136,28 +136,28 @@ input and kept in codex's own store, so it is not kept a second time as a variab
 | `wellknown` | A provider that hands out its own credential, by URL. Runs `opencode auth login <url>`. | `OPENCODE_WELLKNOWN`, the URL answering at `/.well-known/opencode` |
 | `zen` | An OpenCode Zen key, which its own models run on. | `OPENCODE_API_KEY` |
 
-**mimo**
+**mimocode** (`mimo`)
 
 | Way | | Asks for |
 | --- | --- | --- |
 | `login` | mimocode's own provider list, and whichever way that one takes. Runs `mimo auth login`. | — |
 | `key` | A MiMo key, which its own models run on. | `XIAOMI_API_KEY` |
 
-**`agy`**
+**Antigravity CLI** (`agy`)
 
 | Way | | Asks for |
 | --- | --- | --- |
 | `login` | Sign in to a Google account, in a session opened for it. Runs `agy` and hands you the terminal. | — |
 | `key` | A Gemini API key, from AI Studio. | `GEMINI_API_KEY` |
 | `adc` | Google Application Default Credentials, for a service account. Also sets `AGY_ADC_AUTH=1`. | `GOOGLE_APPLICATION_CREDENTIALS` |
 
-**`dsh`**
+**DeepSeek Harness** (`dsh`)
 
 | Way | | Asks for |
 | --- | --- | --- |
 | `key` | A DeepSeek API key, from the platform. | `DEEPSEEK_API_KEY` |
 
-**`grok`**
+**Grok Build** (`grok`)
 
 | Way | | Asks for |
 | --- | --- | --- |
@@ -167,14 +167,14 @@ input and kept in codex's own store, so it is not kept a second time as a variab
 | `gateway` | An endpoint speaking Grok Build's own protocol; its models are listed at `/models`. | `GROK_MODELS_BASE_URL`, `XAI_API_KEY` |
 | `oidc` | Your own identity provider, for an organisation that signs in through one. | `GROK_OIDC_ISSUER`, `GROK_OIDC_CLIENT_ID` |
 
-**`qwen`**
+**Qwen Code** (`qwen`)
 
 | Way | | Asks for |
 | --- | --- | --- |
 | `login` | Sign in to a Qwen account, in a session opened for it. Runs `qwen` and hands you the terminal: `/auth`, then `/quit`. | — |
 | `key` | A key for the OpenAI-compatible endpoint it runs against. | `OPENAI_API_KEY`, `OPENAI_BASE_URL` (`https://dashscope.aliyuncs.com/compatible-mode/v1`) |
 
-**`zcode`**
+**ZCode** (`zcode`)
 
 | Way | | Asks for |
 | --- | --- | --- |
@@ -183,7 +183,7 @@ input and kept in codex's own store, so it is not kept a second time as a variab
 | `key` | A Z.AI or BigModel coding plan key, which its own models run on. | `ZCODE_API_KEY` |
 | `gateway` | An endpoint speaking ZCode's own protocol — a proxy, a router, another vendor. | `ZCODE_BASE_URL`, `ZCODE_API_KEY` |
 
-**Every backend but `dsh`, as well as its own:**
+**Every backend but DeepSeek Harness, as well as its own:**
 
 | Way | | Asks for |
 | --- | --- | --- |

docs/reference/remote-execution.md

@@ -92,7 +92,8 @@ the agent once it exits, and when the session ends nothing it started is left ru
 - The agent's own runtime executables and re-execs. For any CLI installed by npm that includes
   the interpreter its `#!/usr/bin/env` line names, at every path on `PATH` the search for it may
   reach; for Codex, the native CLI and its code-mode host besides.
-- Its state directory, and anything the agent runs from inside it — grok keeps its native binary
+- Its state directory, and anything the agent runs from inside it — Grok Build keeps its native
+  binary
   under `~/.grok/bin` and re-execs it. All twelve known CLIs are known by name — `agy`, `claude`,
   `codex`, `cursor`, `dsh`, `grok`, `kimi`, `mimo`, `opencode`, `pi`, `qwen`, `zcode` — as is
   humanize's own `~/.humanize`; any other agent keeping state inside the workspace has to be

docs/reference/tui.md

@@ -597,8 +597,9 @@ CLI lets go of the model**, which belonged to the CLI before it.
 
 **The arrows step a row that is a rung in an order** — the effort, what it may do, swarm mode,
 whether goals are available, whether it may search the web. Everything else opens a sheet of its
-own and comes back. `web search` is a row only for a CLI that can be told: claude, codex, grok,
-qwen, opencode, mimo and zcode. A switch for something the backend would go on doing either
+own and comes back. `web search` is a row only for a CLI that can be told: Claude Code, Codex,
+Grok Build, Qwen Code, opencode, mimocode and ZCode. A switch for something the backend would
+go on doing either
 way is a switch that lies, so for every other CLI the question is not put. `where` is
 a row only for an agent [the flow says may be pointed at a machine](#where-each-agent-works);
 for one the flow put in a container it is read rather than opened, and for one that works here