@amd-gaia/gaia 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -12,18 +12,69 @@ into the terminal UI. Before this there was no packaged path at all — the flag
 agent had to be run from a repo checkout with a Python environment, and reaching
 the terminal UI meant building it from source.
 
+### Fixed
+
+- Windows npm launchers now find the Python daemon CLI even when npm passes the
+  package script as argv[1], preserving unrelated tools in shared PATH directories.
+
 ### Added
 
+- **Image generation, reachable out of the box.** "Draw me a red bicycle" now
+  generates a PNG with local Stable Diffusion and reports the path; previously
+  the tools existed behind a flag nothing turned on, so the agent just said it
+  couldn't. Adds `generate_image`, `list_sd_models`, and `get_generation_history`
+  (70 tools → 73) plus an `image_gen` bundle so per-turn selection can find them.
+  Generating swaps the resident model, so the next reply waits for the chat model
+  to reload. The `image-gen` starter skill covers prompt expansion and iterating
+  on the previous image.
+- TUI provider setup for Local, Fireworks AI, and AMD LLM Gateway, with masked
+  runtime API keys, discovered models, and remote-inference status.
+
+- **A project map at task start.** In a code repository the agent now opens
+  every task knowing the directory shape, the likely entry points, which
+  commands are installed, and the three platform differences that change
+  command syntax — instead of discovering each one through a failed tool call.
+  Capped at 600 prompt tokens. If the repository has no code index the map
+  starts one in the background; `GAIA_PROJECT_MAP_AUTO_INDEX=0` turns that off,
+  and `GAIA_PROJECT_ROOT` picks the project when the working directory is not
+  it. See SKILL §11.
 - **`503` from `/query` at session capacity.** When every retained session
   slot is busy and none is idle enough to evict, starting a new session
   returns `503` with the reason in `detail` — retryable, distinct from a
   bug-shaped `500`. See SPEC §5.2.
+- **Three further client-visible refusals from `/query`.** Reusing a `run_id`
+  that is still in flight gets `409` — it used to replace the live run, leaving
+  it with no way to be cancelled. Supplying a `model` that differs from the one
+  the `session_id` was built with gets `409` rather than silently answering on
+  the old model. A request with an absent or empty `Host` header gets `400`
+  rather than being served, closing a DNS-rebinding check that failed open.
+  See SPEC §5 and §5.2.
 - **Per-turn skill-body selection.** A loaded skill stays loaded, but its body
   only renders in the prompt on turns whose query matches its description; the
   rest collapse to a one-line menu the model re-activates with `load_skill`.
   `GAIA_DYNAMIC_SKILLS=0` turns the selection off, `GAIA_DYNAMIC_SKILLS_TAU`
   overrides the match threshold, and an embedder outage disables it for the
   session (every body renders — capability is never lost to a failed match).
+- **Per-turn tool selection, now on by default for the flagship `full`
+  profile.** The model is sent at most 26 of its 71 tools on any one call — a
+  fixed core plus whichever cohesion bundles the query matched — instead of the
+  whole registry every time. No capability is lost: `load_tools` is an escape
+  hatch the model calls mid-turn to pull in a bundle the selector missed.
+  `GAIA_DYNAMIC_TOOLS=0` turns the selection off, `GAIA_DYNAMIC_TOOLS_MAX`
+  moves the cap and `GAIA_DYNAMIC_TOOLS_TAU` the match threshold.
+- **One bundled skill ships enabled: `gaia-voice`.** It is a manifest `skills:`
+  entry, so it is always on and rendered in full on every LLM call — 676 tokens
+  of every prompt, and it declares no tools. It is the agent's honesty floor
+  (don't claim work you didn't do, don't present empty output as a result,
+  don't substitute a near-miss and report success), which is why it is not in an
+  opt-in bundle the way a task skill is. No *skill set* ships enabled: the
+  manifest's `skill_sets:` / `default_skill_set:` blocks stay commented out until
+  an eval measures what loading several bodies costs. See SKILL.md §10.
+- **A materially smaller fixed prompt on every call.** That always-on
+  `gaia-voice` guidance was rewritten from 2,129 tokens to 676 with all of its
+  behavioural rules intact. It had been a rationale document — every rule
+  followed by the incident that motivated it — and the model needs the rule,
+  not the incident report.
 - **`gaia run` (the default command)** — resolves the host platform, fetches and
   SHA-256 verifies both binaries, then launches the terminal UI and propagates its
   exit code. Arguments after a bare `--` are forwarded to the TUI verbatim.
@@ -64,6 +115,101 @@ the terminal UI meant building it from source.
 - **Programmatic exports** — `fetchAll`, `startSidecar`, `shutdown`, `runTui`, the
   platform helpers, and the typed error classes, for embedding GAIA in another
   app.
+- **The `.installed` record is written after a verified sidecar install.**
+  Staging the binary was only half an install: the daemon and the terminal UI
+  both key "this agent is installed" on `~/.gaia/agents/gaia/.installed`, and
+  without it the UI ran the REST sidecar as its own stdio child and the chat
+  filled with uvicorn's startup log. It is written on a cache hit as well as a
+  fresh download, so an install left by an earlier version repairs itself, and
+  only for this host's own platform — a `--platform` fetch stages a binary for a
+  different machine and records nothing. See SPEC §4.1.
+- **`--allow-insecure-base-url`** — opt-in for a non-`https` `--base-url`, for a
+  trusted local mirror.
+
+### Changed
+
+- **A `LEMONADE_BASE_URL` that already carries a path is now used exactly as
+  written.** Previously any URL not ending in `/api/v1` had that suffix appended,
+  so a reverse proxy configured as `https://proxy.example/lemonade` was silently
+  rewritten to `https://proxy.example/lemonade/api/v1`. It now resolves to
+  `https://proxy.example/lemonade` unchanged, and only a bare origin with no path
+  at all gains `/api/v1`. If a proxied install starts returning `404` after
+  upgrading, append the API path to the variable yourself.
+
+### Fixed
+
+- **A second `gaia serve` no longer reports success against a server it does not
+  own.** With the port already taken, the incumbent answered `/health` while our
+  own sidecar was still unpacking, so the start "succeeded", printed a ready URL
+  for someone else's server, and the child then died of `EADDRINUSE`. The port is
+  now checked before anything is spawned, and a taken one fails naming the port
+  and how to find the process holding it.
+- **Importing the package no longer changes a host app's error handling.** The
+  crash and signal handlers reaped every sidecar *before* checking whether the
+  host had its own handler, so an exception the host handled killed the sidecar
+  and the host's next request got an unexplained `ECONNREFUSED`.
+- **`gaia run` no longer breaks the terminal UI's `PATH`.** Hiding our own `gaia`
+  shim removed the whole bin directory, which on a Homebrew or pipx layout also
+  took `python3`, `lemonade-server`, and the real `gaia` with it — so the UI
+  reported a missing CLI that we had hidden. A shared directory now moves to the
+  end of `PATH` instead of being dropped.
+- **Flags a command does not read are refused, not ignored.** `run --port 9000`
+  parsed fine and came up on the default port; likewise `serve --component` and
+  `serve --cache-dir`.
+- **A failed install says what to do.** A download that could not be moved into
+  place — usually a running sidecar holding the file on Windows — printed a raw
+  stack trace.
+- **`taskkill` failures name their reason.** Its exit code and stderr were
+  discarded, so "Access is denied" surfaced ten seconds later as a generic
+  timeout.
+- **A sidecar that survives shutdown is still reaped at exit.** `shutdown`
+  de-registered it before killing it, so one that survived both kill windows
+  became a permanent orphan holding the port.
+- **`serve` removes its signal handlers once it stops**, so Ctrl+C keeps working
+  afterwards, and a repeat Ctrl+C during a slow teardown now says what it is
+  waiting for instead of looking frozen.
+- **A non-JSON reply from a sidecar probe raises a typed error** rather than a
+  bare `SyntaxError` — the case where a proxy answers `200` with an HTML page.
+- **`--port` no longer accepts what `Number()` would coerce**, so `--port 0x2710`
+  is rejected instead of quietly binding 10000.
+
+### Security
+
+- **A desktop notification can no longer run code.** On Windows, `notify_desktop`
+  rendered its message box by pasting the title and body into a PowerShell command
+  string, so a `'` in either — text the model picks, and prompt-injected content
+  can steer it — closed the string literal and the remainder ran as PowerShell.
+  The command is now a fixed script that reads both values from the child's
+  environment, and the tool now needs your approval before it runs, like the
+  other tools that spawn a process (SKILL.md §8).
+- **`resolveSidecarPath` / `resolveTuiPath` verify the binary before returning a
+  path that gets spawned.** Both fed `spawn()` from a predictable cache path with
+  no integrity check, so anything able to write `~/.gaia/agents/gaia/` got code
+  run — despite the package documenting the SHA verify as its security boundary.
+  They now re-hash against `binaries.lock.json`; pass `{ verify: false }` for a
+  binary you built yourself. Note this makes them proportional to the binary's
+  size — resolve once at startup, not per request.
+- **`--base-url` requires `https`** unless `--allow-insecure-base-url` is passed.
+  The pinned SHA already made a plaintext mirror non-exploitable, but tampering
+  surfaced as a confusing `IntegrityError` instead of the transport failure it is.
+- **A ~200MB artifact is never held in memory whole.** Downloads stream to disk,
+  and the cache-hit check that re-hashes an already-installed binary — which runs
+  on every `gaia run` — reads it in bounded chunks. Both hashes are computed
+  incrementally, and a download is still verified *before* the file is moved into
+  place.
+
+### Fixed
+
+- **Esc stops a running turn in the terminal UI without killing the agent.**
+  The TUI used to kill the agent process, and on the released one-file binary
+  that killed only the launcher: the cancelled tool call ran to completion and
+  the surviving process consumed the next message. The first Esc now sends the
+  agent a `cancel` control message, so the turn ends and the session keeps its
+  loaded skills, "always" grants, history and bypass mode. A second Esc stops
+  the whole process tree.
+- **A restart after a hard stop no longer turns bypass permissions back on.**
+  The replacement agent is launched in the session's current permission mode
+  instead of from the original flags, and the TUI says what the restart lost.
 
 ### Notes
 
@@ -83,11 +229,16 @@ the terminal UI meant building it from source.
   building its own TUI. Each terminal-hub artifact is additionally cross-checked
   against the hub's own server-side SHA-256 before its hash enters the lock.
 - Requires Node.js 18+ (built-in `fetch`), a running Lemonade Server for
-  inference, and the `gaia` Python CLI on `PATH` for the daemon the TUI starts.
+  inference, and the `gaia` Python CLI 0.23.1+ on `PATH` for the daemon the TUI
+  starts. 0.23.1 is the first core whose daemon knows how to supervise this
+  agent; on 0.23.0 the UI starts with nothing behind it.
 - The sidecar has no arm64 Linux or arm64 Windows build. On those platforms the
   run stops with an error naming the platform and the supported set rather than
   launching a UI with no agent behind it.
-- `gaia_agent` 0.1.1 has no caller-auth token, so unlike
-  `@amd-gaia/agent-email` this package mints and sends none.
+- `gaia_agent` enforces a per-session caller-auth bearer on every `/v1/gaia/*`
+  request, plus a loopback `Host` allowlist and non-loopback `Origin` rejection.
+  This package mints no token, so a sidecar it spawns comes up in dev mode (token
+  check skipped, loudly warned, Host/Origin still enforced) — pass your own
+  through `spawnSidecar`'s `env` to turn it on. See SPEC §5.4.
 - Tracks sidecar contract `apiVersion` **2.12**; a differing major raises
   `VersionMismatchError`.

package/README.md

@@ -9,7 +9,11 @@ npx @amd-gaia/gaia
 That fetches the two binaries GAIA needs — the agent sidecar and the terminal UI —
 verifies both against a checksum manifest that ships inside this package, and drops
 you into the terminal UI. No Python to install, no repo to clone, no build step.
-Everything runs locally on your machine; nothing you type or index leaves it.
+Local inference is the default. The TUI can explicitly select Fireworks AI or AMD
+LLM Gateway through Lemonade; remote chat sends conversation history to that provider. The
+terminal UI's `--use-claude` flag, which would send a conversation to the
+Anthropic API, is refused for the agent this package installs — see
+[`SPEC.md` §5.5](./SPEC.md#55-other-transports).
 
 The terminal UI you get here is the published **`terminal-hub`** component — the
 exact same binary a full GAIA install runs as `gaia tui`, not a separate build. So
@@ -33,8 +37,10 @@ however you arrive at the terminal UI, it behaves identically.
 - **Node.js 18+** (for the built-in `fetch`).
 - **[Lemonade Server](https://amd-gaia.ai/docs/reference/dev)** running locally —
   it hosts the model the agent thinks with. GAIA tells you if it isn't up.
-- The `gaia` Python CLI on `PATH` for the daemon the terminal UI starts. Install it
-  with `curl -fsSL https://amd-gaia.ai/install.sh | sh` (Windows:
+- The `gaia` Python CLI **0.23.1 or newer** on `PATH` for the daemon the terminal
+  UI starts. Earlier cores start a daemon that has no entry for this agent, so the
+  UI comes up with nothing behind it. Install it with
+  `curl -fsSL https://amd-gaia.ai/install.sh | sh` (Windows:
   `irm https://amd-gaia.ai/install.ps1 | iex`).
 
 ## Supported platforms
@@ -75,14 +81,19 @@ npx @amd-gaia/gaia -- --debug
 
 Common options:
 
-| Flag                  | Meaning                                                       |
-| --------------------- | ------------------------------------------------------------- |
-| `--base-url <url>`    | Override the download base URL from `binaries.lock.json`       |
-| `--cache-dir <dir>`   | Where to cache the terminal UI binary                          |
-| `--sidecar-dir <dir>` | Where to install the agent sidecar (default `~/.gaia/agents/gaia`) |
-| `--platform <key>`    | Fetch for another platform (`fetch` only)                      |
-| `--force`             | Re-download even when a verified binary is already cached      |
-| `--port <n>`          | Sidecar bind port for `serve` (default `8141`)                 |
+| Flag                  | Meaning                                                       | Accepted by |
+| --------------------- | ------------------------------------------------------------- | ----------- |
+| `--base-url <url>`    | Override the download base URL from `binaries.lock.json`. Must be `https:` | `run`, `fetch`, `serve` |
+| `--allow-insecure-base-url` | Permit a non-`https` `--base-url` (a trusted local mirror) | `run`, `fetch`, `serve` |
+| `--sidecar-dir <dir>` | Where to install the agent sidecar (default `~/.gaia/agents/gaia`) | `run`, `fetch`, `serve` |
+| `--cache-dir <dir>`   | Where to cache the terminal UI binary                          | `run`, `fetch` |
+| `--force`             | Re-download even when a verified binary is already cached      | `run`, `fetch`, `serve` |
+| `--platform <key>`    | Fetch for another platform                                     | `fetch` |
+| `--component <name>`  | Fetch only `sidecar` or `tui`                                  | `fetch` |
+| `--port <n>`          | Sidecar bind port (default `8141`)                             | `serve` |
+
+A flag a command does not read is **refused**, not ignored — `gaia run --port
+9000` exits 2 rather than silently coming up on the default port.
 
 Set `DEBUG=gaia` for download, spawn, and sidecar output on stderr. Diagnostics
 never touch stdout, which the terminal UI owns.
@@ -92,6 +103,7 @@ never touch stdout, which the terminal UI owns.
 | What            | Path                                     |
 | --------------- | ---------------------------------------- |
 | Agent sidecar   | `~/.gaia/agents/gaia/gaia-agent[.exe]`   |
+| Install record  | `~/.gaia/agents/gaia/.installed`         |
 | Terminal UI     | `~/.gaia/npm-cache/gaia-<version>/gaia-tui[.exe]` |
 
 The sidecar goes into the GAIA daemon's own cache directory on purpose: the daemon
@@ -99,6 +111,13 @@ is what spawns and supervises it, and it does its own SHA-256 check on the way.
 putting an already-verified binary there we save a second download rather than
 racing one.
 
+The `.installed` record next to it is what the daemon and the terminal UI read to
+know the agent is installed — without it the UI would run the sidecar as its own
+stdio child instead of letting the daemon supervise it. It is rewritten even when
+the binary was already cached, so an install left by an earlier version repairs
+itself the next time you run. A `--platform` fetch stages a binary for a
+*different* machine, so it deliberately leaves no record.
+
 The terminal UI is installed as `gaia-tui`, **never** as `gaia` — a file named
 `gaia` in a cache directory would shadow the `gaia` shim npm puts on your `PATH`.
 
@@ -126,6 +145,12 @@ curl http://127.0.0.1:8141/health
 It waits for `GET /health`, checks the contract version, and tears the whole
 process tree down on Ctrl+C. See [`SPEC.md`](./SPEC.md) for the endpoints.
 
+The sidecar normally requires a per-session bearer token on `/v1/gaia/*`, but
+neither `serve` nor `startSidecar` mints one, so both leave it in dev mode — the
+token check off, `Host`/`Origin` still enforced. This agent has shell and file
+tools, so before you expose it to anything, supply a token of your own: see
+[`SPEC.md` §5.4](./SPEC.md#54-caller-authentication).
+
 ## Programmatic use
 
 ```ts

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
@@ -187,6 +191,30 @@ 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.
 
 Or skip the code entirely and let the CLI own it:
 
@@ -210,7 +238,7 @@ Request body (`extra: "forbid"` — an unknown field is a **422**, not ignored):
 | `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. |
 | `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. |
+| `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**. |
 | `max_steps` | no | ≥ 1. |
 
@@ -220,7 +248,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,
@@ -290,14 +322,20 @@ Rules a client must respect:
   **200**, not a 404, because a cancel racing a normal completion is expected.
   Dropping the HTTP connection also cancels the run.
 
-## 8. Confirmation-gated tools are **refused, not prompted**
+## 8. Over `/v1/gaia/query`, confirmation-gated tools are **refused, not prompted**
 
-Read this before you design a workflow around it.
+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.
 
-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.
+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 —
+**`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
@@ -314,11 +352,13 @@ data: {"type":"needs_confirmation","run_id":"…","action":"write_file","summary
 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.
+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.
 
 ## 9. File-access scope
 
@@ -328,6 +368,16 @@ 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.
 
+**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.
+
 **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
@@ -339,7 +389,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
@@ -355,19 +405,52 @@ threshold. Manifest `skills:` entries are always-on and never collapse. 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 676 tokens (tiktoken `cl100k`).
+
+**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. 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
+`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 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.
+
+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.
+
+## 12. Ports
 
 | Service | Port |
 |---|---|
@@ -379,11 +462,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 +494,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 seven 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.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.
 - **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
@@ -463,11 +558,40 @@ 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 — `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.
+- **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.
+
 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; `/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.