@amd-gaia/gaia 0.2.0 → 0.3.0

package/SKILL.md

@@ -127,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
@@ -150,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."
 }
 ```
 
@@ -216,6 +231,12 @@ await shutdown(proc);   // tree-kill; auto-cleanup also reaps on exit
   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:
 
 ```bash
@@ -226,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):
@@ -236,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 — only when the run builds a fresh agent. On a retained `session_id` the agent already exists, so a model that differs from the one it was built with is a **409**, not an override. |
-| `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
@@ -295,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 |
@@ -313,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.
@@ -321,44 +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`, confirmation-gated tools are **refused, not prompted**
+## 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.
 
-Seven of the agent's 71 tools mutate the machine and need explicit approval
-before they run. Five sit in the base `TOOLS_REQUIRING_CONFIRMATION` set —
+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`**,
-**`execute_python_file`**, and **`notify_desktop`**, which spawns a PowerShell
-child on Windows to draw the notification — and the flagship adds two of its
-own, **`install_skill`** and **`remove_skill`**, because installing a skill
-writes third-party code under `~/.gaia/skills` and removing one deletes it.
-Everything else — reading, indexing, querying, web fetching, memory — runs
-without asking.
-
-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.
-
-Concretely, your client sees:
+**`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:
+
+```
+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": "…" }
+```
+
+`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 }
+```
+
+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`.
+
+**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.
+
+**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 run any of those seven tools.** If your integration needs
-that, drive the agent from a surface that can prompt — its stdio transport is the
-one that can, because its control channel carries an approval back to a turn
-already in flight (SPEC §5.5) — 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
 
@@ -378,10 +472,21 @@ come back as a structured error naming the file and the reason, so do not plan a
 integration around reading a credential file or editing a shell rc — perform
 those from your own code.
 
-**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:
+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
@@ -401,7 +506,8 @@ 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.
 
@@ -411,7 +517,17 @@ turn — budget for it. It is not a task recipe but the agent's honesty floor: d
 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 676 tokens (tiktoken `cl100k`).
+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
@@ -419,10 +535,12 @@ 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. 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 raises naming the valid sets rather than falling back to a default. Beyond
+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
@@ -437,12 +555,13 @@ 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 676.
-- **A background embedding pass on first contact with a new repository.** If
-  the repo has no [code index](https://amd-gaia.ai/docs/guides/code-index), the
-  map starts one in a background thread so semantic search is ready when it is
-  needed. On a large monorepo that is minutes of local embedding.
-  `GAIA_PROJECT_MAP_AUTO_INDEX=0` turns it off.
+  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
@@ -450,6 +569,11 @@ specific project means `GAIA_PROJECT_ROOT=/path/to/repo` in its environment, or
 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 |
@@ -494,7 +618,7 @@ 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.
-  The seven gated tools are unreachable **over `/query`** — the agent itself can
+  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
@@ -516,9 +640,9 @@ There is no silent null.
   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.23.1+**: an older core's daemon starts fine but
-  has no sidecar entry for this agent, which reads as a UI with a dead agent
-  rather than as a version problem.
+  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
@@ -547,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' \
@@ -574,14 +698,17 @@ finish (or close an idle session) and retry the same `/query`.
 - **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 — `model` differs from what this `session_id` was built with.** Only
-  construction reads a model, so it cannot be applied to the retained agent.
-  Omit `model` to stay on the session's current one, or start a new
-  `session_id` to switch.
+- **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>.
@@ -591,7 +718,26 @@ and <https://amd-gaia.ai/docs/guides/gaia>.
 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; `/model fireworks.gemma-4-31b-it` selects Gemma 4 31B IT
+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).