VectorInstitute · ethancjackson · Aug 26, 2026 · Aug 26, 2026
diff --git a/README.md b/README.md
@@ -107,7 +107,7 @@ When you open a **Coder workspace**, startup runs automatically in the backgroun
 
 **Your next step:** run [`00_environment_check.ipynb`](implementations/getting_started/00_environment_check.ipynb) top to bottom. That notebook will confirm that startup succeeded.
 
-**ADK web UI.** `adk web` binds to `localhost` *inside* the workspace, so a browser on your laptop cannot reach it until you tunnel. [Guide 5](guides/05-access-adk-web-via-ssh-tunnel.md) walks through that on macOS, Windows, and Linux. Skip it if you are running the repo locally.
+**ADK web UI.** [Guide 5](guides/05-access-adk-web-via-ssh-tunnel.md) is how you serve the concierge (or any other bootcamp agent) in the browser. On Coder, `adk web` binds to `localhost` *inside* the workspace — the same guide tunnels that port to your laptop (macOS, Windows, and Linux). Skip the tunnel half if you are running the repo locally.
 
 On first boot, keys are verified against live services and your onboarding status is recorded. Workspace restarts reload keys without re-running the full test suite.
 
@@ -205,7 +205,7 @@ uv run pre-commit run --all-files
 ## Documentation
 
 - Per-implementation READMEs under [`implementations/`](implementations/) — the primary user surface.
-- [`guides/`](guides/) — self-contained, step-by-step strategy guides for the most common build-phase tasks: onboarding a dataset, creating an experiment, customizing an agent's strategy, and auditing a result before you believe it. [Guide 5](guides/05-access-adk-web-via-ssh-tunnel.md) is the Coder companion for reaching `adk web` from your laptop.
+- [`guides/`](guides/) — self-contained, step-by-step strategy guides for the most common build-phase tasks: onboarding a dataset, creating an experiment, customizing an agent's strategy, and auditing a result before you believe it. [Guide 5](guides/05-access-adk-web-via-ssh-tunnel.md) is how you serve the concierge or any bootcamp agent under `adk web` (and tunnel that UI from Coder to your laptop).
 - [Architecture atlas](https://vectorinstitute.github.io/agentic-forecasting/architecture-atlas.html) ([source](docs/architecture-atlas.html)) — a self-contained visual atlas of the system architecture: the loop, the temporal fence, predictor families, the harness, agent anatomy, and how each reference implementation instantiates them.
 - [`aieng-forecasting/README.md`](aieng-forecasting/README.md) and [`aieng-forecasting/aieng/forecasting/methods/README.md`](aieng-forecasting/aieng/forecasting/methods/README.md) — the library and the method catalog.
 - [`planning-docs/roadmap.md`](planning-docs/roadmap.md) — architecture principles and extension ideas.

diff --git a/docs/architecture-atlas.html b/docs/architecture-atlas.html
@@ -851,8 +851,8 @@ <h3 class="sub">Where do you land?</h3>
           <td><a class="ext" href="https://github.com/VectorInstitute/agentic-forecasting/blob/main/implementations/sp500_forecasting/README.md">sp500</a> / <a class="ext" href="https://github.com/VectorInstitute/agentic-forecasting/blob/main/implementations/food_price_forecasting/README.md">food_price</a> / <a class="ext" href="https://github.com/VectorInstitute/agentic-forecasting/blob/main/implementations/boc_rate_decisions/README.md">boc</a> README respectively, then Path A on that starter (toggles; guide 3's levers are the same <code class="chip">AgentConfig</code> fields).</td>
         </tr>
         <tr>
-          <td>On Coder and want <code class="chip">adk web</code> in a local browser</td>
-          <td><a class="ext" href="https://github.com/VectorInstitute/agentic-forecasting/blob/main/guides/05-access-adk-web-via-ssh-tunnel.md">guide 5</a> — tunnel <code class="chip">localhost:8000</code> from the workspace to your laptop. Skip it if you are running locally.</td>
+          <td>Want to chat with the concierge or a starter agent in the browser</td>
+          <td><a class="ext" href="https://github.com/VectorInstitute/agentic-forecasting/blob/main/guides/05-access-adk-web-via-ssh-tunnel.md">guide 5</a> — serve it with <code class="chip">adk web</code>. On Coder, the same guide tunnels <code class="chip">localhost:8000</code> to your laptop.</td>
         </tr>
       </tbody>
     </table>

diff --git a/guides/05-access-adk-web-via-ssh-tunnel.md b/guides/05-access-adk-web-via-ssh-tunnel.md
@@ -1,33 +1,21 @@
-# Guide 5 — Accessing the ADK Web UI via SSH tunneling
+# Guide 5 — Serving the concierge and other bootcamp agents in interactive mode
 
-**By the end of this guide** you will have your local browser talking to an ADK agent that is running inside your Coder workspace. The same steps work on **macOS, Windows, and Linux** — where a step differs, look for the OS callout.
+**By the end of this guide** you will have the ADK web UI open in your browser, talking to the **repo concierge** — and you will know how to point the same UI at any other bootcamp agent. The same steps work on **macOS, Windows, and Linux** — where a step differs, look for the OS callout.
 
-This is a Coder-environment companion, not a step on Path A or Path B. Skip it if you are running the repo on your own machine: `adk web` already binds to `localhost` there, and you can open the UI directly.
+`adk web` is **interactive mode**: schema-free conversation (Track 2), not a scored forecast. The concierge answers "how does this codebase work?" questions. Domain starter agents (energy, food, BoC, S&P 500) and energy's adaptive agent work the same way — they just forecast instead of navigating the repo.
 
-**Prerequisites:** a Coder workspace with the repo ready (`uv sync` already done — the bootcamp image does this for you). You will also install the Coder CLI on your **personal computer**, not inside the workspace.
+This is a companion to Paths A and B, not a numbered step on either. Two halves:
 
----
-
-## Prerequisites (inside your Coder workspace)
-
-1. Open your Coder workspace terminal.
+1. **Coder only** — `adk web` binds to `localhost` *inside* the workspace, so a browser on your laptop cannot reach it until you tunnel. Follow Steps 1–4 below.
+2. **Everyone** — serve an agent and chat. That is the last section. **If you are running the repo on your own machine, skip Steps 1–4** and go straight there: `adk web` already binds to `localhost`, and you can open the UI directly.
 
-2. Start an ADK agent on port `8000`. From the **repository root**, for example:
-
-```bash
-uv run adk web implementations/energy_oil_forecasting/
-```
+**Prerequisites:** a working environment (`uv sync` already done — the bootcamp Coder image does this for you). Coder users also install the Coder CLI on their **personal computer**, not inside the workspace.
 
-   Other common targets, also from the repo root:
-
-```bash
-uv run adk web implementations/getting_started/concierge_agent
-uv run adk web implementations/energy_oil_forecasting/starter_agent
-```
+---
 
-   From `implementations/energy_oil_forecasting/` the adaptive-agent notebooks use the shorter `uv run adk web adaptive_agent/`. Any of these is fine — the tunnel does not care which agent is serving.
+## Prerequisites (inside your Coder workspace)
 
-3. Keep this workspace terminal tab open and running.
+Open a workspace terminal and keep it free — you will start `adk web` in the last section, after the tunnel is up. The browser stays connection-refused until both the tunnel *and* an agent are running.
 
 ---
 
@@ -106,17 +94,87 @@ This behaves identically on macOS, Windows, and Linux, and does not depend on yo
 
 ---
 
-## Step 4 — Access the UI
+## Step 4 — Keep the tunnel open
 
-1. Open your local web browser.
-2. Navigate to [http://localhost:8000](http://localhost:8000).
-3. You can now fully interact with the ADK web interface.
+The tunnel is ready. Do **not** close that local terminal. You will open [http://localhost:8000](http://localhost:8000) after you start an agent in the next section.
+
+If you already have `adk web` running in the workspace, you can open the URL now and skip ahead; otherwise the page will refuse the connection until an agent is serving.
+
+---
+
+## Serving the concierge (and other bootcamp agents)
+
+This section is the point of the guide. Run the commands in the **repository root** — in your Coder workspace terminal if you tunneled, or in a local terminal if you skipped Steps 1–4.
+
+### Start the concierge
+
+```bash
+uv run adk web implementations/getting_started/concierge_agent
+```
+
+Keep this terminal open. Then, in your local browser, open [http://localhost:8000](http://localhost:8000).
+
+That loads the same `repo_concierge` agent as [`99_repo_concierge.ipynb`](../implementations/getting_started/99_repo_concierge.ipynb) (`gemini-3.1-flash-lite-preview`), with `search_repo_catalog`, `fetch_repo_artifact`, and the `repo-navigation` skill. It answers onboarding questions from a committed catalog of public `main` — not your local uncommitted files or `data/` cache. It is **not** a forecasting agent.
+
+In the UI, pick `concierge_agent` if a dropdown of apps is shown, then send a message. Try:
+
+- *Where should I go after getting_started if I want to build agents?*
+- *How do I create a new data service?*
+- *What's the difference between `backtest()` and `evaluate()`?*
+
+You should get an answer that cites concrete repo paths. Verify important details against the files themselves (or a facilitator) — like any LLM, it can be wrong.
+
+**Terminal-only equivalent** (no browser): `uv run adk run implementations/getting_started/concierge_agent`. From `implementations/getting_started/`, the shorter `uv run adk run concierge_agent` works too.
+
+### What `adk web` is looking for
+
+ADK serves a directory that contains `agent.py` exposing a module-level `root_agent` (every bootcamp agent does this lazily via `__getattr__`, so the UI gets a schema-free chat agent rather than a structured `Prediction`). You can pass:
+
+- **One agent folder** — the command above. The UI talks to that agent.
+- **A parent folder of several agents** — ADK lists each subdirectory that has `agent.py`, and you pick one in the UI. Energy is the worked example: `uv run adk web implementations/energy_oil_forecasting/` exposes `starter_agent`, `analyst_agent`, and `adaptive_agent`.
+
+One `adk web` process occupies port `8000`. To switch agents, stop it (Ctrl+C) and start another path — or serve a parent folder and switch in the dropdown.
+
+### Other bootcamp agents
+
+Same command shape, still from the **repository root** unless a row says otherwise:
+
+| Agent | Command | What you get |
+| --- | --- | --- |
+| Repo concierge | `uv run adk web implementations/getting_started/concierge_agent` | Onboarding Q&A about the codebase |
+| Energy starter | `uv run adk web implementations/energy_oil_forecasting/starter_agent` | Hackable WTI analyst (news search on by default) |
+| Energy (pick in UI) | `uv run adk web implementations/energy_oil_forecasting/` | Dropdown: starter, analyst, adaptive |
+| Food starter | `uv run adk web implementations/food_price_forecasting/starter_agent` | Hackable food-CPI analyst |
+| BoC starter | `uv run adk web implementations/boc_rate_decisions/starter_agent` | Hackable cut/hold/hike analyst |
+| S&P 500 starter | `uv run adk web implementations/sp500_forecasting/starter_agent` | Hackable S&P 500 analyst |
+| Energy adaptive | see below | Persistent WTI strategy you can keep talking to |
+
+Energy's adaptive agent is launched from *inside* that implementation, because the notebooks and `WTI_STRATEGY_DIR` paths are relative to it:
+
+```bash
+cd implementations/energy_oil_forecasting
+
+# Seed strategy (no training applied yet):
+uv run adk web adaptive_agent/
+
+# Continue from the trained strategy committed after notebook 05:
+WTI_STRATEGY_DIR=adaptive_agent/skills/wti-strategy-trained \
+    uv run adk web adaptive_agent/
+```
+
+> **Local Windows (PowerShell):** set the env var as a separate statement, then start the UI: `$env:WTI_STRATEGY_DIR="adaptive_agent/skills/wti-strategy-trained"; uv run adk web adaptive_agent/`. In the Coder workspace terminal this is bash, so the `WTI_STRATEGY_DIR=... \` form above is the one to use.
+
+Each domain's [`99_starter_agent.ipynb`](../implementations/energy_oil_forecasting/99_starter_agent.ipynb) is the other interactive surface — a notebook cell rather than the browser UI. Use `adk web` when you want a longer back-and-forth; use the notebook when you also want a scored (Track 1) prediction in the same file.
+
+**Check.** The UI loads at [http://localhost:8000](http://localhost:8000), you can send the concierge a question, and the reply cites a path under `implementations/` or `aieng-forecasting/`. If the page will not load, the tunnel (Coder) or the `adk web` process has stopped — see Troubleshooting.
 
 ---
 
 ## Troubleshooting
 
-**"Address already in use" / port 8000 is taken.** Something else on your machine is using `8000`. Remap the *local* side of the tunnel to a free port, then browse to that port:
+**Page won't load / connection refused in the browser.** Confirm `adk web` is still running (the serving section) **and**, on Coder, that the tunnel terminal is still open and "frozen." Both have to be up.
+
+**"Address already in use" / port 8000 is taken.** Something else on *your laptop* is using `8000`. Remap the *local* side of the tunnel to a free port, then browse to that port:
 
 ```bash
 # Option A
@@ -127,6 +185,8 @@ coder port-forward <YOUR_WORKSPACE_NAME> --tcp 8080:8000
 
 Then open [http://localhost:8080](http://localhost:8080). The format is `LOCAL_PORT:localhost:REMOTE_PORT` (Option A) or `LOCAL_PORT:REMOTE_PORT` (Option B) — only change the first number. The agent in the workspace stays on `8000`.
 
+If the error is in the **workspace** terminal instead, another `adk web` (or something else) is already bound to `8000` there. Stop it, or start with `uv run adk web --port 8001 ...` and tunnel that remote port (`ssh -L 8000:localhost:8001 ...` / `coder port-forward <name> --tcp 8000:8001`).
+
 **`ssh: command not found` (Windows).** Enable the OpenSSH Client optional feature or use Git Bash (see Step 3), or switch to Option B.
 
 **`coder: command not found` after install.** Open a new terminal so the updated PATH is picked up, then re-run `coder version`.
@@ -135,7 +195,9 @@ Then open [http://localhost:8080](http://localhost:8080). The format is `LOCAL_P
 
 **Firewall prompt on first connect (Windows/macOS).** Allow access for the SSH/Coder client when prompted — it only opens a local loopback tunnel.
 
-**Page won't load / connection refused in the browser.** Confirm the ADK agent is still running in the workspace terminal (Prerequisites, step 2) and that the tunnel terminal is still open and "frozen."
+**`adk web` starts but the agent list is empty / import fails.** You are probably not in the repository root, or `uv sync` has not been run. The implementations package has to be installed for `from getting_started.concierge_agent ...` (and the sibling starters) to import. Run `uv sync` from the repo root, then retry the `uv run adk web ...` command from there.
+
+**Agent replies with an API / auth error.** On Coder, keys are injected at workspace start — open a new workspace terminal if this one predates onboarding. Locally, run [`00_environment_check.ipynb`](../implementations/getting_started/00_environment_check.ipynb) and fix whatever it flags.
 
 ---
 
@@ -149,10 +211,11 @@ Then open [http://localhost:8080](http://localhost:8080). The format is `LOCAL_P
 | SSH config path | `~/.ssh/config` | `%USERPROFILE%\.ssh\config` |
 | Tunnel (manual) | `ssh -L 8000:localhost:8000 coder.<name> -N` | same |
 | Tunnel (simple) | `coder port-forward <name> --tcp 8000:8000` | same |
+| Serve concierge | `uv run adk web implementations/getting_started/concierge_agent` | same (from the repo root) |
 | Access URL | [http://localhost:8000](http://localhost:8000) | same |
 
 ---
 
 ## Where to go next
 
-If you tunneled the energy starter or adaptive agent, **[guide 3](03-customize-agent-strategy.md)** is the lever map for changing how it thinks. The [repo concierge](../implementations/getting_started/99_repo_concierge.ipynb) is the other common `adk web` target — useful when you want to ask how the repo is put together rather than drive a forecaster.
+The concierge is a map, not a forecaster. When you are ready to *build* one, each domain's `99_starter_agent.ipynb` is the hackable template (food, energy, BoC, S&P 500), and **[guide 3](03-customize-agent-strategy.md)** is the lever map for changing how it thinks. Energy's adaptive-agent notebooks (05–06) pick up from the `adaptive_agent/` row in the table above.