@amd-gaia/gaia 0.1.1 → 0.3.0

package/SKILL.md

@@ -23,7 +23,8 @@ Two ways in:
 > playbook: how *you* wire this package into an app. The agent separately loads
 > **Agent Skills** into its own prompt at runtime from
 > `gaia_agent/skills/<name>/SKILL.md`. Same filename, different artifact —
-> don't ship this one as an agent skill. See [Skills](#10-skills--opt-in-and-empty-in-010).
+> don't ship this one as an agent skill. See
+> [Skills](#10-skills--one-always-on-the-rest-opt-in).
 
 ## 1. Install
 
@@ -51,7 +52,10 @@ built-in `fetch`. Use `import`, not `require`; from CommonJS use
    each against the lock**.
 4. Installs the sidecar into `~/.gaia/agents/gaia/` and the TUI into
    `~/.gaia/npm-cache/gaia-<version>/`.
-5. Execs the TUI, whose exit code becomes ours.
+5. Writes `~/.gaia/agents/gaia/.installed` — the record the daemon and the TUI
+   both read to decide the sidecar is installed. Written on a cache hit too, so
+   an install staged by an earlier release repairs itself.
+6. Execs the TUI, whose exit code becomes ours.
 
 `run` deliberately does **not** spawn a sidecar. The TUI reaches agents through
 the GAIA daemon's relay and never holds a sidecar token, and the daemon is what
@@ -123,9 +127,22 @@ for the version you have.
 The agent thinks with a model hosted by **Lemonade Server**, which this package
 does not install. Required before any query succeeds:
 
-1. Lemonade **10.2.0 or newer**, running (`lemonade-server serve`).
-2. The default model downloaded (`gaia download Gemma-4-E4B-it-GGUF`, or
-   `gaia init`).
+1. Lemonade **10.2.0 or newer**, running. GAIA's daemon starts and supervises
+   one, so `gaia daemon start` is normally all that is needed (`gaia init`
+   also installs and starts it on first run). Qwen3.8 Flash Next needs
+   **v2026.39.1 or newer**, the version `gaia init` installs; older servers
+   cannot load it.
+2. The machine's default chat model downloaded — run `gaia init`. It picks
+   `Qwen3.6-35B-A3B-GGUF` where a GPU holds it (~27 GB for models,
+   weights plus context cache — a 64 GB+ Strix Halo or a 32 GB GPU) and
+   `Gemma-4-E4B-it-GGUF` everywhere else, CPU-only PCs included, and records the pick as
+   `default_model` in `~/.gaia/config.json`. On 128 GB-class PCs the user may
+   switch to the multimodal `user.Qwen3.8-Flash-Next-GGUF` with `gaia config set
+   default_model`. `model.id` below names whichever this machine uses.
+   `gaia download` takes **no** model argument — naming one makes it exit 2. To
+   pull a single model instead, repeat the command `GET /v1/gaia/init` gives
+   you: it names the Lemonade client this machine actually has. Do not invent
+   one.
 
 Do not guess — ask the sidecar. `GET /v1/gaia/init` is a read-only preflight
 (it never pulls or loads) that probes Lemonade, compares its version to the
@@ -146,7 +163,9 @@ alone:
                 "min_version": "10.2.0", "compatible": null },
   "model":    { "id": "Gemma-4-E4B-it-GGUF", "present": false,
                 "loadable": null, "ctx_size": null },
-  "hint": "Local Lemonade Server is not reachable at … — start it with `lemonade-server serve`, or set LEMONADE_BASE_URL to a running server."
+  // The manual fallback ("Otherwise: …") is resolved for the host's Lemonade
+  // install (tray app, macOS app, systemd service, or CLI) — render it verbatim.
+  "hint": "Local Lemonade Server is not reachable at …. GAIA starts it automatically — run `gaia daemon start` if the background service is not running. Otherwise: Start the Lemonade app from Applications, then retry. Or set LEMONADE_BASE_URL to a running server. See https://amd-gaia.ai/docs/guides/gaia."
 }
 ```
 
@@ -187,6 +206,36 @@ await shutdown(proc);   // tree-kill; auto-cleanup also reaps on exit
   on `exit`, `SIGINT`/`SIGTERM`/`SIGHUP`, `uncaughtException`, and
   `unhandledRejection`. A `SIGKILL` of *your* process is the one case nothing
   in-process can catch.
+- **Mint a caller token, or you are running the sidecar unauthenticated.** The
+  sidecar requires `Authorization: Bearer <token>` on every `/v1/gaia/*`
+  request, and skips the check only when neither token env var is set — dev
+  mode, which is what `startSidecar` gives you, because this package mints
+  nothing. Loopback binding is not the boundary: this agent has shell and file
+  tools. Mint your own and pass it through the `env` option (`StartOptions`
+  extends `SpawnOptions`, so it merges over `process.env`):
+
+  ```ts
+  import { randomBytes } from "node:crypto";
+  const token = randomBytes(32).toString("hex");
+  const proc = await startSidecar({
+    binaryPath: sidecar.binaryPath,
+    env: { GAIA_GAIA_SIDECAR_TOKEN: token },   // or ..._TOKEN_FILE, a 0600 path
+  });
+  ```
+
+  Then send `authorization: "Bearer " + token` on every `/v1/gaia/*` call.
+  `/health`, `/version`, and `/v1/gaia/version` are exempt, so `startSidecar`'s
+  own health-and-version handshake works either way. **If you did not spawn the
+  sidecar** — you are talking to one the GAIA daemon started — the token is the
+  daemon's, delivered to the sidecar as `GAIA_GAIA_SIDECAR_TOKEN_FILE` (a `0600`
+  file path); read it from there, don't invent one. A 401 whose `detail` names
+  both env vars means you sent the wrong token or none.
+
+  The programs the agent starts (shell commands, MCP servers, CLI installs and
+  sign-ins, native hub agents, media tools) never inherit this token
+  or GAIA's other internal credentials. To withhold your own variables from
+  them too, list the names in `GAIA_CHILD_ENV_DENY` (comma or space separated);
+  `GAIA_NO_DOTENV=1` stops the sidecar loading `.env` files.
 
 Or skip the code entirely and let the CLI own it:
 
@@ -198,7 +247,7 @@ curl http://127.0.0.1:8141/health
 ## 7. Call `POST /v1/gaia/query`
 
 This is the whole agent surface. There is **no typed query client** in this
-package — call it with plain `fetch`. Contract version **2.12**; the stream is
+package — call it with plain `fetch`. Contract version **2.17**; the stream is
 `text/event-stream` terminated by **exactly one** `final` or `error`.
 
 Request body (`extra: "forbid"` — an unknown field is a **422**, not ignored):
@@ -208,10 +257,11 @@ Request body (`extra: "forbid"` — an unknown field is a **422**, not ignored):
 | `query` | yes | Non-empty. |
 | `run_id` | yes | **You mint it**, and it must be a UUID (non-UUID → 422). It is the cancel handle, valid from the instant the request is sent. |
 | `context` | yes | Transcript slice, pushed in the body — may be `[]`, never absent. Each item `{ role, content }`; `role` ∈ `user` / `assistant` / `system` / `tool`. |
-| `session_id` | no | Contract ≥ 2.12. **Pass it.** The agent persists its indexed-document set per session — without it, it forgets a document between the turn that indexed it and the next question. |
+| `session_id` | no | Contract ≥ 2.12. **Pass it.** The agent persists its indexed-document set per session — without it, it forgets a document between the turn that indexed it and the next question. 1–128 characters from `A-Z a-z 0-9 . _ -` (a UUID works); anything else is a **400**. |
+| `documents` | no | Contract ≥ 2.16. Absolute paths of the files the user attached to this conversation — send the whole set **every turn**. The agent indexes any it has not read yet before the turn runs, granting each exact file and not its folder. A relative path is a **422**. A missing file, a folder, or a refused secret is named as not indexed in the turn's `index_documents` step, and the turn still runs. |
 | `can_answer_questions` | no | Set `false` for one-shot / batch runs so the agent resolves ambiguity itself instead of parking on a question nobody can see. |
-| `model` | no | Overrides the model id for this run. |
-| `provider` | no | Local inference only — anything but `"lemonade"` is a **400**. |
+| `model` | no | Overrides the model id. On a retained `session_id` a different model is **switched in place** (contract ≥ 2.14), keeping the conversation and any loaded skills; a switch that fails is a **409** and leaves the session on its previous model. |
+| `provider` | no | `"lemonade"` (the default backend) or `"claude"`, which sends the conversation to Anthropic's API instead of the local server. Anything else is a **400**. When you name it, `model` must agree: under `"claude"` it must be a `claude-*` id, under `"lemonade"` it must not be. A mismatch is a **400**, on a new session or an existing one. Omit it and the `model` decides instead — a `claude-*` id alone reaches Anthropic, any other id runs locally — so there is nothing to mismatch. On a retained `session_id`, naming a different provider switches the session to it in place, onto `model` or, without one, the provider's default model; omitting both leaves the session where it is. |
 | `max_steps` | no | ≥ 1. |
 
 ```ts
@@ -220,7 +270,11 @@ import { randomUUID } from "node:crypto";
 const runId = randomUUID();
 const res = await fetch(`${proc.baseUrl}/v1/gaia/query`, {
   method: "POST",
-  headers: { "content-type": "application/json", accept: "text/event-stream" },
+  headers: {
+    "content-type": "application/json",
+    accept: "text/event-stream",
+    authorization: `Bearer ${token}`,   // required unless the sidecar is in dev mode — §6
+  },
   body: JSON.stringify({
     query: "Summarize the PDFs in ~/Documents/reports",
     run_id: runId,
@@ -263,11 +317,11 @@ The canonical event shapes, as emitted:
 
 | Event | Shape |
 |---|---|
-| `status` | `{ type, message }` — progress and reasoning narration |
+| `status` | `{ type, message, phase?, words?, chars? }` — progress and reasoning narration. `phase` (`loading_model`, `downloading_model`, `reading`, `reasoning`, `tool_call`) names what the model is doing; show it as the live line, not as narration |
 | `token` | `{ type, delta }` — answer text to append |
 | `tool_call` | `{ type, tool, args }` |
 | `tool_result` | `{ type, tool, data, render? }` |
-| `needs_confirmation` | `{ type, run_id, action, summary }` — no `confirm_url`; see §8 |
+| `needs_confirmation` | `{ type, run_id, action, summary, confirm_id?, always_scope? }` — answer it, or it ends the run; see §8 |
 | `needs_input` | `{ type, run_id, request_id, question, options[], allow_free_text, sensitive, respond_url, timeout_seconds? }` |
 | `final` | `{ type, answer, usage? }` — terminal |
 | `error` | `{ type, detail, status }` — terminal, surface `detail` verbatim |
@@ -281,7 +335,7 @@ Rules a client must respect:
   guarantees one; a close without one means something broke on your side.
 - **Answer `needs_input`, don't restart.** The run is parked on the *same*
   stream. `POST /v1/gaia/query/{run_id}/respond` with
-  `{ request_id, response }` and keep reading the existing stream — a fresh
+  `{ request_id, value }` and keep reading the existing stream — a fresh
   `/query` POST abandons the paused run. Unknown run → **404**; a `request_id` that
   is no longer pending → **409** (both loud, never a silent drop). Render each
   option's `description`, and mask the input when `sensitive` is set.
@@ -289,36 +343,116 @@ Rules a client must respect:
   `{ run_id, cancelled }` — an unknown id reports `cancelled: false` with a
   **200**, not a 404, because a cancel racing a normal completion is expected.
   Dropping the HTTP connection also cancels the run.
+- **Add to a running turn with `POST /v1/gaia/query/{run_id}/followup`**
+  (contract ≥ 2.15, body `{ text }`). The run is not interrupted and no second
+  turn starts: the agent folds the text in at its next step boundary and
+  answers it alongside what it was already doing. Unknown run → **404**, an
+  agent that cannot take one → **409**; both are loud, so hold the message
+  rather than telling the user it was sent. `/query` is stateless, so put a
+  delivered follow-up into the next turn's `context` yourself, between that
+  turn's question and its answer.
+
+## 8. Over `/v1/gaia/query`, a gated tool asks — when you can answer
+
+Read this before you design a workflow around it. This section is about the HTTP
+surface — the agent's other transport can collect an approval; see SPEC §5.5.
+
+Twelve of the agent's 95 tools mutate the machine and need explicit approval
+before they run. Nine sit in the base `TOOLS_REQUIRING_CONFIRMATION` set —
+**`write_file`**, **`edit_file`**, **`run_shell_command`**,
+**`wait_for_condition`**, which re-runs a shell command until it succeeds,
+**`execute_python_file`**, **`run_python`**, **`notify_desktop`**, which spawns
+a PowerShell child on Windows to draw the notification, and **`install_cli`** /
+**`sign_in_cli`**, which install software and sign a CLI in to the user's
+account — and the flagship adds three of its own
+(`CONFIRMATION_REQUIRED_TOOLS`): **`install_skill`**, **`capture_skill`**, and
+**`remove_skill`**, because installing or capturing a skill writes third-party
+content under `~/.gaia/skills` and removing one deletes it. A capture that does
+land is additionally **code-inert**: its instructions load, but any
+`tools.py`/scripts stay unregistered until a human runs
+`gaia skill promote <name>` in a terminal. Everything else — reading,
+indexing, querying, web fetching, memory, and the read-only `check_cli_setup`
+— runs without asking. A write or edit inside the agent's own scratch
+folder (`gaia-scratch-…` under the system temp folder) runs without asking too,
+so running a script from it asks every time and carries no `always_scope`. So does a shell command run there or naming a path there, and a script handed a scratch path as an argument.
+
+The eight live-browser tools are gated by a **hook**, not a set, so a name
+alone does not tell you whether a call will ask. `browser_login` always asks.
+`browser_click` / `browser_type` ask when the call acts inside a session the
+run signed in to, or when the target element's label reads irreversible, and
+run unasked on the open web. The hook **fails closed**: if the browser cannot
+be asked what state it is in, the call is treated as authenticated and prompts.
+Design a workflow around the approval path, not around a fixed tool list.
+
+**Contract ≥ 2.14 can answer one.** Send a `session_id` and leave
+`can_answer_questions` unset (or `true`). The stream emits `needs_confirmation`
+carrying a `confirm_id` and then **stays open** while the agent waits:
 
-## 8. Confirmation-gated tools are **refused, not prompted**
+```
+data: {"type":"needs_confirmation","run_id":"…","action":"run_shell_command","summary":"python -m pytest -q tests/\nCan run any code, with your permissions.","confirm_id":"…","always_scope":"pytest (runs the test code it finds)","risk":"execute"}
+```
+
+Answer it on the same run, then keep reading the stream:
+
+```
+POST /v1/gaia/query/{run_id}/tool_decision
+{ "decision": "allow" | "deny" | "always" | "timeout", "confirm_id": "…" }
+```
 
-Read this before you design a workflow around it.
+`summary` is the command or call itself, shown once — your UI supplies the
+question. For a shell command it can carry two more lines: `in <folder>` when
+the command runs outside the workspace, and one plain sentence on what a `write`
+or `execute` command can do. Show it as-is. A CLI a skill would grant (`git
+commit`, `python script.py`) with no such skill loaded arrives here as a prompt,
+not a refusal. So does a command GAIA's own checks don't cover (`git push`,
+`python -c`, a path outside the project): its `summary` is the exact line the
+shell will run, unshortened, then `in <folder>`, then a risk sentence, and it
+carries no `always_scope` — offer allow-once and deny only. `allow` runs that
+line once; the next call asks again. `risk` says what the call does (`read`, `write`, `execute`,
+`destructive`); label by it rather than by tool name, since `run_shell_command`
+is `pytest` on one call and `rm -rf` on the next. `always` grants the family
+named in `always_scope` for the rest of the session (`pytest` covers every
+spelling of a test run) — say so in your UI, because it stops asking; no
+`always_scope` means don't offer it. If your prompt expires unanswered, send
+`timeout`, not `deny`: it still refuses, but the agent tells the user the
+request timed out instead of claiming they said no. Unknown run → **404**; a
+prompt that is no longer pending → **409**; any other decision → **422**. All loud,
+never a silent drop. Send `confirm_id`: without it a late answer resolves
+whichever prompt replaced the one it was typed against.
+
+To stop being asked for a whole session:
+
+```
+POST /v1/gaia/sessions/{session_id}/bypass
+{ "enabled": true }
+```
 
-Three of the agent's 55 tools write to disk or execute a command, and sit in the
-base `TOOLS_REQUIRING_CONFIRMATION` set: **`write_file`**, **`edit_file`**, and
-**`run_shell_command`**. Everything else — reading, indexing, querying, web
-fetching, memory — runs without asking.
+It applies to the very next gated tool, including one in a turn already running,
+and an unknown session is a **404** rather than a new one. A malformed
+`session_id` is a **400**, same as on `/query`.
 
-Over `/v1/gaia/query` there is **no way to collect an approval**, so the stream
-does not prompt. When the agent reaches one of those tools it emits a
-`needs_confirmation` event, and the server **immediately follows it with a
-terminal `final`** whose `answer` says it stopped before running that action,
-then cancels the run. There is no `confirm_url`, no resume, and no
-`/query/{run_id}/confirm` endpoint — it is a deliberate deny-by-default stub, not
-an oversight.
+**That bypass stops the prompts; it does not open the shell.** The stdio
+transport's `--bypass-permissions` does both — it runs gated tools unasked *and*
+lifts the shell tool's guardrails (redirection and the other shell-only
+operators, the read-only binary allowlist, the rate limit). That second half is
+arbitrary code execution, appropriate for one local parent on a private pipe and
+not for a bound socket, so it stays on stdio: HTTP sessions never lift the shell
+gates, and the request body rejects unknown fields so a client cannot ask. See
+SPEC §5.5.
 
-Concretely, your client sees:
+**A run nobody can answer is still refused.** With `can_answer_questions: false`,
+or with no `session_id`, the server emits `needs_confirmation`, follows it
+immediately with a terminal `final` saying it stopped before running the action,
+and cancels the run:
 
 ```
-data: {"type":"needs_confirmation","run_id":"…","action":"write_file","summary":"Run 'write_file'?"}
 data: {"type":"final","answer":"I stopped before running 'write_file' because it needs your explicit approval, and this streaming surface cannot collect that yet. …"}
 ```
 
-So: **`/query` cannot write files, edit files, or run shell commands.** If your
-integration needs that, drive the agent from a surface that can prompt (the
-terminal UI or the Agent UI), or perform the mutation yourself from your own code
-and let the agent do the reading and reasoning. Treat `needs_confirmation` as an
-early warning that the run is about to end, not as a question you can answer.
+That is deny-by-default, not an oversight: parking a batch run on a prompt
+nobody will ever see reads as a hang. So a one-shot integration cannot run those
+nine tools — pass a `session_id` and answer, or perform the mutation from your
+own code and let the agent do the reading and reasoning.
 
 ## 9. File-access scope
 
@@ -328,10 +462,31 @@ for a personal document agent, and it is still a real boundary — system
 directories, program files, and other users' homes are refused, with the check
 run against the *resolved* path so a symlink out of scope doesn't slip through.
 
-**In 0.1.1 narrowing it is a construction-time setting only.** The packaged
-sidecar exposes no flag or env var for `allowed_paths` (its CLI accepts only
-`--host` and `--port`), so restricting the scope means embedding `GaiaAgent` in
-your own Python process:
+**Being in scope is not the same as being safe, and two denylists apply inside
+it.** Reads refuse secrets — `.env`, `id_rsa`, `credentials.json`, `.netrc`,
+`.pem`/`.key`, and everything under `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.kube` —
+even in an allowed directory. Writes additionally refuse anything that executes
+on its own: shell startup files, PowerShell profiles, `~/.config/autostart/*`,
+systemd user units, `LaunchAgents`, and a repo's `.git/` (hooks and config). Both
+come back as a structured error naming the file and the reason, so do not plan an
+integration around reading a credential file or editing a shell rc — perform
+those from your own code.
+
+The agent also gets its own scratch directory for throwaway scripts and
+intermediate files, so they stay out of the user's project. It is created per
+agent under the system temp dir, deleted when the agent closes, and is the only
+part of the temp dir the agent may use.
+
+**To narrow it for a run, set `GAIA_ALLOWED_PATHS`** in the environment the
+sidecar starts in — absolute folders joined with `;` on Windows and `:` elsewhere.
+The scope becomes the overlap with the default; an entry outside it is ignored
+with a warning and never widens it, and out-of-scope paths are refused without a
+prompt, even under full access. The scratch directory stays writable. An empty,
+relative or missing entry stops the sidecar at startup. It confines the agent's
+tools, not code they run: a `run_python` script or shell command can still read
+anything the OS user can, so isolating a run from files it must not see needs a
+separate OS user, container or VM. Embedding `GaiaAgent` lets you pass an explicit
+list instead (the variable still narrows it):
 
 ```python
 from gaia_agent.agent import GaiaAgent, GaiaAgentConfig
@@ -339,7 +494,7 @@ from gaia_agent.agent import GaiaAgent, GaiaAgentConfig
 agent = GaiaAgent(config=GaiaAgentConfig(allowed_paths=["/home/me/Documents"]))
 ```
 
-## 10. Skills — opt-in, and empty in 0.1.1
+## 10. Skills — one always-on, the rest opt-in
 
 The agent is built to host **Agent Skills** (short playbooks loaded into its own
 prompt, grouped into named sets, one set active per launch), and its bundled
@@ -351,23 +506,75 @@ matching bodies in full — the rest collapse to a one-line menu entry, and the
 model (or the user) re-activates one by calling `load_skill` on it again.
 `GAIA_DYNAMIC_SKILLS=0` disables the per-turn selection (every loaded body
 renders every turn); `GAIA_DYNAMIC_SKILLS_TAU=<float>` overrides the match
-threshold. Manifest `skills:` entries are always-on and never collapse. If the
+threshold. Manifest `skills:` entries are always-on and never collapse, and a
+turn with only always-on skills loaded embeds nothing. If the
 embedder is unavailable, selection disables itself for the session and every
 body renders — capability is never silently lost to a failed match.
 
-**Nothing ships enabled in 0.1.1.** The bundled skill library is empty, and
-`gaia-agent.yaml` ships its `skills:` / `skill_sets:` / `default_skill_set:`
-blocks **commented out** — following the email agent's precedent, because skill
-bodies cost prompt tokens and no eval has measured that trade for this agent yet.
-Re-enabling is uncommenting two blocks; no code change.
-
-So today: no skill set loads, and there is nothing for `GAIA_SKILL_SET` to
-select — leave it unset. Once a release declares sets, `GAIA_SKILL_SET` is the
-selection channel for the packaged sidecar (its CLI has no `--skill-set` flag),
-and an undeclared name raises naming the valid sets rather than falling back to a
-default. Do not document or design around skills being on by default.
-
-## 11. Ports
+**One skill ships enabled: `gaia-voice`.** It is a manifest `skills:` entry, so
+it is always on, always rendered in full, and paid on every LLM call of every
+turn — budget for it. It is not a task recipe but the agent's honesty floor: do
+not claim work you did not do, do not present empty output as a result, do not
+substitute a near-miss and report success. Those failures corrupt an answer
+whatever the task is, which is why it cannot live in an opt-in bundle. It
+declares no tools, and its body measures 790 tokens (tiktoken `cl100k`).
+
+**`document-extract` ships bundled but not enabled.** `gaia-voice` routes a
+request for every item in a document to it, and it drives
+`extract_document_items` and `save_extracted_items` so a long transcript yields
+a complete, source-quoted inventory rather than a summary. A skill turns that
+inventorying on only by listing `extract_document_items` in `tools_required`;
+wording such as "find every call site" in another skill does not. Loading it
+registers the tools at once, so `load_skill` never reports them missing; coverage
+is enforced only when the request itself names a source document or asks for
+every item, and a file the user named as a deliverable is never a source.
+
+**No skill *set* loads.** `gaia-agent.yaml` ships its `skill_sets:` and
+`default_skill_set:` blocks **commented out** — following the email agent's
+precedent, because loading several skill bodies into every prompt costs tokens
+and no eval has measured that trade for this agent yet. Re-enabling is
+uncommenting two blocks; no code change.
+
+So today there is nothing for `GAIA_SKILL_SET` to select — leave it unset; any
+value stops the agent at startup (the sidecar exits non-zero before binding its
+port). Once a release declares sets, `GAIA_SKILL_SET` is the selection channel
+for the packaged sidecar (its CLI accepts only `--host` and `--port`), and an
+undeclared name stops startup naming the valid sets rather than falling back to
+a default. Beyond
+`gaia-voice`, do not design around a skill being on by default.
+
+## 11. The project map — two things it costs you
+
+When the agent's working directory is a code repository, every task starts with
+a **project map** in the system prompt: the root, the directory shape, the
+likely entry points, which commands are installed, and the three platform
+differences that change command syntax. It exists so the agent stops burning
+round trips on "no such file" and "command not found".
+
+Two consequences an integrator needs to plan for:
+
+- **Up to 600 prompt tokens, every turn.** That is the enforced ceiling
+  (1.8% of the NPU profile's 32K window), not a typical value — budget it
+  alongside `gaia-voice`'s 790.
+- **An embedding pass on the first semantic code search.** If the repo has no
+  [code index](https://amd-gaia.ai/docs/guides/code-index), the first
+  `search_code_index` builds it, then searches. On a large monorepo that one
+  search takes minutes of local embedding; a task that never searches pays
+  nothing. `GAIA_PROJECT_MAP_AUTO_INDEX=1` builds it in the background at task
+  start instead.
+
+The sidecar's CLI accepts only `--host` and `--port`, so pointing the map at a
+specific project means `GAIA_PROJECT_ROOT=/path/to/repo` in its environment, or
+`GaiaAgentConfig(project_root=...)` when embedding. A directory that is neither
+a VCS checkout nor holds a recognised manifest gets **no map** — that is the
+designed answer, not a failure.
+
+The same root check also decides whether the shell rides along: when it
+resolves to a repository, `run_shell_command` is offered on every turn instead
+of only when semantic selection guesses the request sounds like a shell
+request. No repository, no change.
+
+## 12. Ports
 
 | Service | Port |
 |---|---|
@@ -379,11 +586,14 @@ Port **4001 is reserved repo-wide**: `spawnSidecar` throws a `RangeError` and
 speaks for the user's documents and memory and has no business on a LAN
 interface.
 
-## 12. Running in a server or long-lived app
+## 13. Running in a server or long-lived app
 
 - **`fetchAll` / `fetchBinary` are a build step**, not per request — network plus
-  a full SHA-256 hash of a large artifact. Run once; `resolveSidecarPath` /
-  `resolveTuiPath` at runtime.
+  a full SHA-256 hash of a large artifact. Run once at install time.
+- **`resolveSidecarPath` / `resolveTuiPath` are startup, not per request.** They
+  re-hash the binary against `binaries.lock.json` before handing back a path that
+  gets spawned, so they cost a full read of a large file. Resolve once and keep
+  the path. `{ verify: false }` skips the check for a binary you built yourself.
 - **Spawn once at boot** and hold the `Sidecar` handle for the process lifetime.
   Never per request.
 - **Low concurrency.** One local Lemonade model slot, so parallel queries
@@ -408,22 +618,31 @@ There is no silent null.
   reachable"** means Lemonade isn't running or isn't reachable — not a bug in
   this package. Start it, or set `LEMONADE_BASE_URL`.
 - **`needs_confirmation` is followed by a refusal and the run ends.** See §8.
-  `write_file` / `edit_file` / `run_shell_command` are unreachable over `/query`.
+  The nine gated tools are unreachable **over `/query`** — the agent itself can
+  run them on a transport that can prompt (SPEC §5.5).
 - **A placeholder hash in `binaries.lock.json` blocks the fetch before any
   network call.** Between releases that is the *expected* state — it is not a
   broken install, and there is no override.
 - **No `linux-arm64` / `win32-arm64` sidecar.** The TUI has both. A `PlatformError`
   on those hosts is the design, not a missing artifact.
-- **There is no caller-auth token at 0.1.1.** Unlike `@amd-gaia/agent-email`, this
-  sidecar mints none and this package sends none — don't add an `Authorization`
-  header looking for one, and don't rely on its absence as a security boundary.
-  Loopback binding is what protects it.
+- **A `401` from `/v1/gaia/*` is the caller-auth token, not a bug.** The sidecar
+  requires `Authorization: Bearer <token>`; `/health`, `/version`, and
+  `/v1/gaia/version` are exempt, which is why a green health check sits happily
+  in front of a 401 on `/query`. It skips the check only in dev mode — neither
+  token env var set — which is what `spawnSidecar` and `gaia serve` produce,
+  because this package mints nothing. Do not treat loopback binding as the
+  boundary; mint a token and pass it (§6).
 - **`run_id` must be a UUID**, and unknown fields in the request body are a
   **422** — the model forbids extras. Typos don't get ignored.
 - **`gaia run` needs the *Python* `gaia` CLI on `PATH`** — the TUI shells out to
-  it to start the daemon. The package deliberately strips its own npm bin
-  directory from the child's `PATH` so the TUI doesn't re-invoke the npm shim; if
-  the Python CLI isn't installed, the daemon never comes up.
+  it to start the daemon. So the TUI doesn't re-invoke our own npm shim, the
+  child's `PATH` is rewritten: a directory holding nothing but our shim (an npx
+  temp dir) is dropped, and a **shared** bin directory is moved to the end
+  instead of removed, so the `python3` / `lemonade-server` / real `gaia` beside
+  it stay reachable. If the Python CLI isn't installed anywhere, the daemon never
+  comes up. It must also be **0.25.0+**: an older core's daemon starts fine but
+  cannot run this agent, which reads as a UI with a dead agent rather than as
+  a version problem.
 - **The TUI is installed as `gaia-tui`, never `gaia`** — the terminal-hub artifact
   *is* called `gaia-<platform>`, and a file named `gaia` in a cache directory would
   shadow the npm bin shim. The lock's `filename` and `executable` differ for that
@@ -452,7 +671,7 @@ Then, in another terminal:
 
 ```bash
 curl -s http://127.0.0.1:8141/health          # {"status":"ok","service":"gaia-agent-gaia"}
-curl -s http://127.0.0.1:8141/version         # {"apiVersion":"2.12","agentVersion":"0.1.1"}
+curl -s http://127.0.0.1:8141/version         # {"apiVersion":"2.17","agentVersion":"0.1.1"}
 curl -s http://127.0.0.1:8141/v1/gaia/init    # 200 + "ready":true, or 503 + a "hint"
 curl -N -X POST http://127.0.0.1:8141/v1/gaia/query \
   -H 'content-type: application/json' \
@@ -463,11 +682,62 @@ A healthy run streams `status` / `token` events and ends with one `final`. If
 `/v1/gaia/init` is 503, fix what its `hint` names and retry — the rest of your
 integration is fine.
 
+That `/query` call carries no `Authorization` header because `gaia serve` starts
+the sidecar in dev mode. Against one started with a token, add
+`-H "authorization: Bearer $TOKEN"` — a **401** here and a green `/health` is
+that and nothing else (§6).
+
 **A 503 from `/query` itself is a different condition**: every retained
 session slot is busy and none is idle enough to evict (SPEC §5.2). Do NOT
 loop on `/v1/gaia/init` — it will report ready. Wait for a running turn to
 finish (or close an idle session) and retry the same `/query`.
 
+**Three more refusals are yours to avoid**, each naming its fix in `detail`
+(SPEC §5.2 has the reasoning):
+
+- **409 — the `run_id` is still in flight.** You mint it, so mint a fresh UUID
+  per request; reusing one would leave the earlier run with no way to be
+  cancelled.
+- **409 — the model switch itself failed** (a missing Claude credential, an
+  unknown local model). The session stays on its previous model, so this is a
+  failed request rather than a broken session; `detail` names the reason.
+- **400 — the `Host` header is absent or empty.** The loopback check fails
+  closed, so omitting the header is refused rather than served. Send
+  `Host: 127.0.0.1:<port>`; every real HTTP client already does.
+
+**After cancelling a turn, send the next `/query` on that session straight
+away.** It is held until the stopped turn's model call returns (up to 240 s),
+then runs. A session whose running turn was NOT cancelled still answers `409`.
+
 For the full wire contract, lock schema, exit codes, and timeout table, see
 [`SPEC.md`](./SPEC.md). For the user-facing overview, see [`README.md`](./README.md)
 and <https://amd-gaia.ai/docs/guides/gaia>.
+
+## TUI inference providers
+
+The stdio TUI supports `/provider` for Local, Fireworks AI, and AMD LLM Gateway.
+Keys are entered in a masked field and sent directly to local Lemonade's runtime
+auth API, never as agent queries. `/model` lists supported discovered cloud and
+downloaded local models, marking the configured default with `(default)`;
+`/model fireworks.gemma-4-31b-it` selects Gemma 4 31B IT
+when available. Cloud chat sends conversation history to the selected provider;
+embeddings remain on Lemonade. The status event names the actual provider and
+marks remote inference. This is a TUI/stdio capability, not an HTTP query command.
+
+## Developer engineering mode
+
+Available only when GAIA was started with `--developer-mode` (or
+`GAIA_DEVELOPER_MODE=1`). If the engineering tools are missing, say that developer
+mode is off; don't route around it with shell or file tools. When describing a
+handoff, claim only what happened:
+
+- Context was shared only after the user approved that exact snapshot in the prompt.
+  Approval can't be remembered, so each share or append asks again.
+- Opening the coding app never creates or submits a task, and for Codex it doesn't
+  prefill a prompt either. Never say the context was "posted" or "sent" to Codex;
+  give the user the directory and the prompt to paste.
+- Preview and test results come from the coding app. Report them as app-reported,
+  not as checks GAIA ran.
+- Revoking stops future reads; it cannot recall data already delivered.
+
+See the [usage guide](https://amd-gaia.ai/docs/guides/harness-engineering).