Overview

Add a first-run onboarding experience that teaches the basics of docker agent
by doing, not by reading: a short, skippable, interactive tour inside the TUI,
plus a way to replay it later (docker agent tour and a /tour slash command).

Motivation

The current first-run experience gives no guidance. A new user who runs
docker agent gets a telemetry banner, then lands in a chat UI without knowing:

• that a provider API key (or Docker Model Runner) is required, and how to set one
• that slash commands and a command palette (Ctrl+k) exist
• what an agent.yaml is, and that docker agent new can generate one
• how tool-call approval works (approve / reject / yolo)
• where to find help (Ctrl+h only lists key bindings, there is no /help)

The quickstart docs cover all of this, but outside the terminal. Users who do
not read docs never discover these features.

Current state

Use cases

1. First-time user installs Docker Desktop, types docker agent, has no API key set: gets guided to a working setup instead of an error.
2. New user wants to learn the basics without leaving the terminal: takes the 2-minute tour on first launch.
3. Returning user forgot the shortcuts and concepts: runs docker agent tour (or /tour in the TUI) to replay it.

Proposed solution

Flow

docker agent run          (first run, interactive TTY only)
  |
  +- no provider configured
  |     -> setup step: detect env keys / DMR, show per-provider
  |        instructions, re-check, then continue
  |
  +- provider available
        -> prompt: "First time here. Take the 2-minute tour? [Y/n/never]"
             |
             +- Y     -> scripted tour in the TUI
             +- n     -> normal chat + one-line hint on how to replay
             +- never -> normal chat, never asked again

Tour content (scripted, learn-by-doing)

Short steps rendered by the TUI itself (deterministic, no tokens consumed).
Each step waits for the user to actually perform the action, Esc skips at
any point.

Entry points

Guardrails

• Never shown in non-interactive contexts: --exec, piped stdin/stdout, api, mcp, a2a, acp, serve, eval, CI (no TTY).
• Skippable at every step (Esc), resumable is not required (restart from the beginning is fine).
• "Never" choice persisted; also honor an env var (e.g. DOCKER_AGENT_NO_TOUR=1) for scripted environments, following the existing DOCKER_AGENT_HIDE_TELEMETRY_BANNER precedent.
• State stored next to the existing first-run marker (config dir), separate from session data.
• Existing telemetry banner folds into the new first-run flow instead of stacking on top of it.

Implementation notes

• Reuse the existing dialog framework (pkg/tui/dialog) for the step overlays; the tour is a sequence of dialogs plus event hooks on the actions being taught.
• First-run detection already exists (isFirstRun() in cmd/root/root.go); extend rather than duplicate.
• Provider detection can reuse what the model resolution already knows (env keys, DMR availability).
• Optional: telemetry events for tour started / completed / skipped-at-step-N to measure drop-off.

Alternatives

A and B combine well: the final scripted step can hand off to a built-in tour
agent ("ask me anything about docker agent") as an optional bonus. C works as
the fallback when no provider is configured and the user declines setup. D can
be a separate follow-up.

Open questions

• Command name: tour vs onboarding vs learn vs getting-started (tour is short and matches /tour).
• Auto-offer on first run vs auto-start: prompt-first seems less intrusive.
• Should completing provider setup count as "first run done", or should the tour be offered again next time if it was interrupted?
• Should the tour agent (option B hand-off) ship in pkg/config/builtin-agents like default.yaml and coder.yaml?

Additional context

Related existing pieces: cmd/root/root.go (first-run marker, welcome banner),
pkg/tui/dialog/help.go (key bindings dialog), pkg/tui/commands/commands.go
(slash commands, palette), pkg/config/builtin-agents/ (default and coder
agents), docker agent new (interactive config creator).