[EPIC] B: First-Run Experience

[wbreza]

Problem / User Value

New azd users face a "blank slate" problem — they don't know which Azure tools they need, and the documentation spreads tool installation across dozens of pages. A guided first-run experience minimizes decisions for newcomers (one confirm installs everything recommended) while providing an escape hatch for advanced users who want to customize.

Definition of Done

First-run triggers on first azd init/up/provision/deploy. Single-confirm path installs all recommended tools. Customize path provides MultiSelect picker. Skip mechanisms work (AZD_SKIP_FIRST_RUN, --no-prompt, config). Post-install summary with next-step hints displayed.

Tasks

• B-1: Implement first-run trigger middleware (M) — Create cmd/middleware/tool_firstrun.go per §7.1. Triggers when ~/.azd/tool-check-timestamp is absent, terminal is interactive, and command is init/up/provision/deploy (not tool/*, version, config). Register after telemetry middleware, before hooks. Detects missing recommended tools via ToolManager.Check(). Writes timestamp on completion.
  • AC: Triggers on first init/up/provision/deploy; does NOT trigger on tool/*/version/config commands; does NOT trigger with --no-prompt or non-interactive terminal; timestamp prevents re-triggering; registered after telemetry, before hooks
• B-2: Build streamlined first-run UX (single-confirm + customize paths) (L) — Default path: display recommended tools list, then "Install recommended tools? [Y/n]" single confirm → install all. n → MultiSelect picker with all tools (recommended pre-checked). Per-tool progress with bar-fill spinner and (✓)/(x)/(-) states. Colors per UX design: bold title, highlighted names, gray versions.
  • AC: Single Y/n prompt installs all recommended; n opens MultiSelect with recommended pre-checked; per-tool progress display; partial failure continues + WARNING summary; all-already-installed shows appropriate message; colors match UX spec
• B-3: Add skip mechanisms (env var, --no-prompt, config) (S) — AZD_SKIP_FIRST_RUN=true env var, --no-prompt flag, and azd config set tool.firstRunCompleted true all suppress the first-run middleware. Update docs/environment-variables.md.
  • AC: All three skip mechanisms work; docs/environment-variables.md updated; unit tests for each skip path
• B-4: Add post-install summary with next-step hints (S) — After install completes, show installed/skipped/failed counts. Next-step hint: azd tool doctor to verify. Failed tools get individual retry hints. SUCCESS/WARNING formatting per azd style guide.
  • AC: Summary with counts; next-step hint includes azd tool doctor; failed tools get retry hints; SUCCESS format on full success, WARNING on partial failure

Sequencing

B-1 ──┬──> B-2 ──> B-4
      └──> B-3

• B-2 and B-3 can run in parallel after B-1
• B-4 depends on B-2

Dependencies

• Epic A (Core Engine): A-5 (ToolManager) must be complete — first-run middleware depends on it
• Epic F (Research): ✅ Complete — F-2's UX recommendations inform B-2's design

Discussion Traceability

Discussion Item	Task
F5 (first-run simplify: "one confirm, not N checkboxes")	B-2

Design References

• docs/design/azd-tool/plan.md — Phase 2a
• docs/design/azd-tool-architecture.md — §7.1 (middleware), UX design §Flow 1
• docs/design/azd-tool/todos.md — detailed acceptance criteria