amd
diff --git a/‎docs/reference/cli.mdx‎
Lines changed: 118 additions & 72 deletions b/‎docs/reference/cli.mdx‎
Lines changed: 118 additions & 72 deletions
diff --git a/‎docs/spec/agent-hub-restructure.mdx‎
Lines changed: 65 additions & 1 deletion b/‎docs/spec/agent-hub-restructure.mdx‎
Lines changed: 65 additions & 1 deletion
@@ -2371,85 +2371,133 @@ under [Agent Command](#agent-command).
 
 ---
 
-### TUI Control API
+### Terminal hub (`gaia tui`)
 
-The terminal hub (`gaia tui`, the Go/Bubble Tea binary) can expose a loopback
-HTTP API that drives **the session you are looking at** — not a headless copy.
-An assistant navigates, types, and launches agents while the frames render in
-your terminal in real time. It is how the TUI gets tested without a human at
-the keyboard.
+`gaia tui` is the Go/Bubble Tea terminal hub: browse agents, install them, and
+chat with them without leaving the terminal. Building from source the binary is
+`tui/bin/gaia` (`cd tui && make build`).
 
-Off by default. Bound to `127.0.0.1` only, and every request needs a bearer
-token.
+<Note>
+  The binary accepts a leading `tui` word and drops it, so `gaia tui install
+  email` and `gaia install email` are the same command. Running the source build
+  directly, both `./tui/bin/gaia tui list` and `./tui/bin/gaia list` work.
+</Note>
 
 ```bash
-gaia tui --control                 # auto-assign a port
-gaia tui --control-port 8770       # explicit port (implies --control)
-gaia tui --control --debug         # log every injected key, state change, and wait
+gaia tui                                  # open the hub
+gaia tui list                             # what the Agent Hub offers + what you have
+gaia tui list --installed                 # local only, no network call
+gaia tui install email --trust            # download and install
+gaia tui uninstall email                  # stop the agent and remove it
+gaia tui run email                        # interactive chat
+gaia tui run email --query "triage my inbox"   # one-shot: answer on stdout, exit 0/1
+gaia tui status                           # background service + what is installed
 ```
 
+| Command | Description |
+|---------|-------------|
+| `gaia tui` | Open the Agent Hub. |
+| `gaia tui list [--installed]` | List agents with version, install state, download size, and security tier. `--installed` reads the local `~/.gaia/agents/*/.installed` sentinels and never touches the network. |
+| `gaia tui install <id> [--version X] [--trust]` | Install an agent and wait for it to finish. |
+| `gaia tui uninstall <id>` | Stop the agent's sidecar, verify it is gone, remove its install directory. |
+| `gaia tui run <id> [--query "…"] [--model M] [--timeout D]` | Run an agent. `--query` is a genuine one-shot, checked and bounded (`--timeout`, default 15m). |
+| `gaia tui status` | Whether the background service is running, which sidecars it knows, and what is installed. |
+| `gaia tui chat --agent <id>` \| `--subprocess <cmd>` | Chat with an agent by catalog id, or with a binary you spawn directly. With `--agent --query` it is the same one-shot `gaia tui run --query` is, `--timeout` included. |
+| `gaia tui hub` | The hub screen explicitly (same as bare `gaia tui`). |
+
+Install and uninstall are served by the GAIA daemon
+(`POST /daemon/v1/agents/{id}/install`, `DELETE /daemon/v1/agents/{id}`), so the
+TUI, `gaia hub`, and the Agent UI share one integrity check and one install
+lock. The daemon is started automatically for these commands; `gaia tui status`
+only ever attaches, so it reports what *is* running rather than starting
+something.
+
+#### `--trust`: installing a non-verified agent
+
+An agent outside the `verified` security tier runs third-party code on your
+machine. The daemon refuses to install one with **HTTP 403** until the caller
+passes an explicit opt-in — there is no bypass, and nothing retries on your
+behalf.
+
+From the CLI, that opt-in is `--trust`. Without it the command prints exactly
+what you would be agreeing to and exits non-zero:
+
+```console
+$ gaia tui install email
+
+Refusing to install "email" without --trust.
+
+  Agent       email
+  Version     0.5.0
+  Publisher   AMD
+  Security    experimental (not verified by AMD)
+  Download    31.1 MB
+  Access      none declared
+
+If you trust the publisher, re-run:
+  gaia tui install email --trust
+```
+
+In the hub screen the same refusal opens a **Trust & Install** confirmation
+showing the same facts. It defaults to *Cancel*, and only an explicit yes
+re-sends the request with the opt-in.
+
+#### `run --query` is a real one-shot
+
+`--query` does not open the alt screen. The answer goes to stdout, progress to
+stderr, and the exit code is `0` on a terminal answer / `1` on an error — so
+`gaia tui run email --query "…" > answer.txt` captures exactly the answer:
+
+```bash
+gaia tui run email --query "how many unread?" > answer.txt 2> progress.log
+echo $?   # 0
+```
+
+It never waits on something that is not there. Before the query is sent, a
+one-shot over the daemon transport (the agents the background service supervises)
+runs the same readiness check the hub's launch gate runs — background service,
+sidecar, local model server, model, and for email the mailbox — and if one of
+them is not ready it prints that row and its remedy to stderr and exits non-zero.
+Against an unreachable dependency that is about a second; the ceiling is the time
+it takes to start the sidecar. Nothing is sent to the agent, and the gate screen
+is never rendered: a script has nobody to press a key. An agent that runs as a
+local subprocess has no readiness route to probe, so it is launched directly.
+
+```bash
+$ gaia tui run email --query "triage my inbox"   # with the model server down
+❌ Email is not ready — Local AI: not running at http://localhost:8000/api/v1
+   GAIA needs a local model server. It runs on your machine; no message text ever leaves it.
+…
+        run: lemonade-server serve
+$ echo $?   # 1, after about a second
+```
+
+The turn itself is bounded — 15 minutes by default, `--timeout 90s` / `--timeout
+2h` to change it — so an agent that accepts the query and then stops answering is
+reported with what to read next instead of hanging a CI job until the job's own
+timeout kills it. There is no "wait forever": `--timeout 0` is refused. Interactive
+`gaia tui run <id>` is unaffected — a person can read what arrives and press
+ctrl+c.
+
+#### Hub keys
+
+| Key | Action |
+|-----|--------|
+| `enter` | Run the selected agent |
+| `i` | Install it (or update it, when a newer version exists) |
+| `d` | Uninstall it (asks first) |
+| `r` | Refresh the agent list from the Agent Hub |
+| `/` | Search |
+| `tab` / `shift+tab` | Next / previous category |
+| `v` | Vote for a coming-soon agent |
+| `?` | Help |
+| `q`, `ctrl+c` | Quit |
+
 <Note>
-  These are persistent flags on the TUI binary's root command, so they apply to
-  the hub, `hub`, and `chat` alike. Building from source, that binary is
-  `tui/bin/gaia` (`cd tui && make build`).
+  `backspace` is deliberately unbound. It used to share the uninstall binding
+  with `d` and `delete`, which made "go back" a destructive action.
 </Note>
 
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--control` | flag | off | Start the control API on an auto-assigned loopback port. |
-| `--control-port` | integer | `0` | Bind a specific port. Implies `--control`. `0` auto-assigns. Port `4001` is reserved and rejected. |
-| `--debug` | flag | off | Log every injected key, state transition, and wait resolution/timeout to stderr. |
-
-On start the TUI writes `~/.gaia/tui/control.json` (mode `0600`) holding the
-pid, port, and token, and removes it on exit. Clients find the TUI by reading
-that file — the token is never printed to the terminal. A client must verify
-**both** that the recorded pid is alive and that `/control/v1/status` answers
-with a matching pid before trusting the port: after a crash the file can point
-at a port some unrelated process now owns.
-
-<Warning>
-  Anything that can read `~/.gaia/tui/control.json` can drive your TUI — the
-  same trust boundary as `~/.gaia/host/instance.json` for the daemon. Leave
-  `--control` off unless you want a session driven.
-</Warning>
-
-Endpoints (all under `/control/v1`, all requiring `Authorization: Bearer <token>`):
-
-| Endpoint | Purpose |
-|----------|---------|
-| `GET /status` | `running` plus the active view, active agent, streaming, hub tab, selection, terminal size, and `can_return_to_hub`. |
-| `GET /screen` | The current rendered frame. `?format=plain` (default, ANSI stripped) or `?format=ansi`. |
-| `POST /keys` | Inject named keys — `{"keys": ["tab","down","enter"]}`. |
-| `POST /text` | Type a string as runes — `{"text": "triage my inbox"}`. |
-| `POST /wait` | Block until the screen or state matches, or time out. A timeout reports what the screen actually contained. |
-| `GET /frames` | Recent rendered frames (`?since=N`), for debugging what happened. |
-| `POST /resize` | Re-lay-out at a given size — `{"cols":120,"rows":40}`. |
-
-Errors come back as `{"error": {"code", "message", "hint"}}`; a `/wait` timeout is
-HTTP 408 and carries the screen it saw.
-
-Two response details matter when driving this:
-
-- **`settled`** on `/keys`, `/text`, and `/resize`. The call returns only once every
-  injected key has been *consumed and redrawn*, so reading `/screen` straight after
-  is race-free. `settled: false` means the model was still busy — the input is
-  queued, so re-read rather than assume it was ignored. It does **not** promise the
-  consequences are done: pressing `enter` to launch an agent is consumed
-  immediately, while the view switch it kicks off lands later. Use `/wait` for
-  anything asynchronous.
-- **HTTP 503 `not_running`** when the TUI's event loop is not consuming input —
-  it is still starting, or the user has quit. Bubble Tea silently drops messages
-  in that window, so the API refuses instead of reporting a success for keys that
-  went nowhere. Reads (`/status`, `/screen`, `/frames`) keep working.
-
-`can_return_to_hub` exists because `esc` is not universally "go back": in a chat
-opened from the hub it returns there, but in a standalone `gaia chat --subprocess`
-session it **quits the program**. A driver that guesses wrong kills the session it
-was asked to drive, so the state says which.
-
-Most callers should not speak this API directly — the
-[TUI MCP server](/guides/mcp/tui) wraps it as MCP tools.
-
 ---
 
 ### TUI Control API
@@ -2531,8 +2579,6 @@ was asked to drive, so the state says which.
 Most callers should not speak this API directly — the
 [TUI MCP server](/guides/mcp/tui) wraps it as MCP tools.
 
----
-
 ### Cache Command
 
 Inspect or clear GAIA's on-disk caches (document-Q7 metadata, chat history,
 
@@ -66,6 +66,7 @@ src/gaia/agents/                 src/gaia/agents/        ← framework only
 3. **Shared tool mixins promoted to framework.** RAG, FileIO, Shell, CodeIndex mixins move into `src/gaia/agents/tools/` so agents don't depend on each other for tools.
 4. **Entry-point discovery.** Agents register via the `gaia.agent` entry point group. The registry discovers installed agent wheels at startup — no hardcoded agent list.
 5. **Framework-provided generic server.** `src/gaia/agents/base/server.py` wraps any Agent into an OpenAI-compatible REST API + MCP stdio server. Agents don't implement server logic.
+6. **Inherited init.** An agent *declares* what it needs — a model id, a minimum backend version — and the framework serves `GET`/`POST /v1/<id>/init` for it. Agents don't hand-write readiness or provisioning endpoints. See [Inherited init](#inherited-init).
 
 ## Pre-requisite: Promote shared tool mixins
 
@@ -130,6 +131,69 @@ chat = "gaia_agent_chat.agent:ChatAgent"
 
 Agents with cross-agent dependencies (e.g. RoutingAgent uses CodeAgent) declare them as package dependencies: `dependencies = ["amd-gaia>=0.18.0", "gaia-agent-code>=0.1.0"]`.
 
+## Inherited init
+
+An agent that needs a model before it can answer anything should not have to
+hand-write a readiness endpoint to say so. It **declares** the requirement and
+`AgentServer` serves both verbs at `/v1/<id>/init`:
+
+| Verb | Effect | Status |
+|------|--------|--------|
+| `GET` | Read-only readiness probe. Reports backend reachability, version compatibility, and whether the declared model is downloaded — with an actionable `hint` per failure. | `200` ready · `503` not ready, **same body** either way |
+| `POST` | Provisioning. Tells an already-running backend to download the declared model, streaming newline-terminated progress. | `503` before streaming if the backend is down · otherwise a committed `200` |
+
+Declare requirements in `gaia-agent.yaml` (`models:` and
+`requirements.min_lemonade_version`), or pass them explicitly:
+
+```python
+from gaia.agents.base.readiness import AgentRequirements
+from gaia.agents.base.server import AgentServer
+
+server = AgentServer(
+    MyAgent(),
+    agent_id="my-agent",
+    requirements=AgentRequirements(
+        model_id="Gemma-4-E4B-it-GGUF",
+        min_backend_version="10.2.0",
+    ),
+)
+```
+
+An agent that declares nothing gets **no** init routes — a readiness endpoint
+that reports "ready" without having checked anything is worse than a 404,
+because a consumer would trust it.
+
+### Where the boundary sits
+
+Inherited init makes *this agent's* requirements ready: its model, against a
+backend that is already running. **Installing the backend stays with `gaia
+init`.** An agent process cannot bootstrap the server it depends on, so when
+Lemonade is unreachable both verbs fail loudly and name whose job the fix is
+rather than hanging or half-succeeding:
+
+```
+✗ The local Lemonade Server is not reachable at http://127.0.0.1:9099/api/v1.
+✗ Start it with `lemonade-server serve` (or run `gaia init`), then POST to this path again.
+✗ My Agent can't install the backend itself — that's a host prerequisite.
+```
+
+### Reading a provisioning result
+
+Once a streamed `200` is committed the HTTP status can no longer change, so a
+pull that fails half-way still arrives as `200 OK`. **The final line is the
+verdict** — `✓` success, `✗` failure, `⚠` succeeded-but-unverified. Consumers
+must read it rather than the status code; the TUI's preflight gate
+(`tui/internal/ui/preflight`) already does.
+
+Two distinctions the contract preserves deliberately, because each has a
+different remedy:
+
+- **"Could not tell" is not "missing."** If the backend answers `/health` but
+  its model list cannot be read, `present:false` means unknown — reporting it as
+  missing would send the user to re-download a model they may already have.
+- **Indeterminate is not a pass.** A backend that advertises no version yields
+  `compatible: null`, never `true`.
+
 ## Implementation Steps
 
 <Steps>
@@ -155,7 +219,7 @@ Remove agent packages from `setup.py`. Remove `gaia-emr`/`gaia-code` console scr
 Replace ~16 direct agent imports in `cli.py`, `ui/_chat_helpers.py`, `ui/agent_loop.py`, and apps with `registry.create_agent(id)`.
 </Step>
 <Step title="Add framework generic server">
-`src/gaia/agents/base/server.py` wraps any Agent into REST API + MCP server. Enables `gaia agent run <id> --api` and `--mcp`.
+`src/gaia/agents/base/server.py` wraps any Agent into REST API + MCP server. Enables `gaia agent run <id> --api` and `--mcp`, and serves the agent's [inherited init](#inherited-init) routes.
 </Step>
 <Step title="Add CI/CD workflow">
 `.github/workflows/build_agents.yml` matrix-builds the C++ agent binaries;