feat(azure.ai.agents): enrich manual-vars Next: block with run follow-up (P5.1 C3)

Two-part fix to ResolveAfterInit's MissingManualVars branch:

1. Enrich per-var description: was "supply the agent.yaml variable" →
   now "referenced by agent.yaml but not set in azd env". The command
   column already shows the var name; the description should explain
   WHY the var matters so users new to the project understand they
   aren't just inventing values out of nowhere.

2. Append an `azd ai agent run` follow-up after the env-set lines.
   Pre-C3 the post-init Next: block stopped at the env-set lines:

     Next: azd env set MY_API_KEY <value>   -- referenced by agent.yaml
                                               but not set in azd env
           azd deploy                       -- when ready to deploy to Azure

   Users had to remember the run step themselves. Issue Azure#7975's
   manual-vars example explicitly ends with "Then run 'azd ai agent
   run' to start locally" — surface that as a concrete follow-up so
   the entire "fix env, then run" loop is visible in one Next: block:

     Next: azd env set MY_API_KEY <value>   -- referenced by agent.yaml
                                               but not set in azd env
           azd ai agent run                 -- start the agent locally
                                               once the values above
                                               are set
           azd deploy                       -- when ready to deploy to Azure

Gating: the run follow-up is suppressed when UnresolvedPlaceholders
are also present, preserving the existing invariant from
ResolveAfterInit's "otherwise" branch — running locally with literal
`{{NAME}}` values produces a broken agent, so the placeholder fix-ups
must be finished first. The trailing `azd deploy` reminder still
applies.

Tests:
- TestResolveAfterInit (table) — `wantManualVarKeys` cases bump
  expected length from N+1 to N+2 and assert the run follow-up
  immediately after the env-set lines.
- TestResolveAfterInit_ManualVarsCapAtThree — expected length 4→5,
  asserts the run follow-up sits at slot 3 (between env-set lines
  and trailing deploy).
- TestResolveAfterInit_ToolboxReproRendersAllCategories — asserts
  the run follow-up is intentionally absent when placeholders are
  also present (gating contract).
- TestResolveAfterInit_ManualVarsSingleEmitsEnrichedShape (NEW) —
  locks the single-missing-var canonical case: enriched description
  text + run follow-up + trailing deploy, all in order.

Source of truth: issue Azure#7975 lines 117-127. Phase 5 C3 of the
P5.8 commit plan (Tier A — core fixes).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Antriksh Jain

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/resolver.go

@@ -62,7 +62,12 @@ const (
 //     suggesting `azd ai agent run`. See state.PendingProvisionReasons
 //     for the env-var contract.
 //   - MissingManualVars  → one `azd env set <KEY> <value>` per missing var
-//     (up to maxFixupLines)
+//     (up to maxFixupLines) plus an `azd ai agent run` follow-up so
+//     the user knows what to do after supplying the values. Matches
+//     issue #7975's "Then run 'azd ai agent run' to start locally"
+//     manual-vars example. The run follow-up is suppressed when
+//     UnresolvedPlaceholders are also present, since literal
+//     `{{NAME}}` values would still break the local agent.
 //   - Otherwise          → `azd ai agent run`
 //     Skipped when only UnresolvedPlaceholders are present, because
 //     running locally with literal `{{NAME}}` values is broken too.
@@ -111,11 +116,28 @@ func ResolveAfterInit(state *State) []Suggestion {
 		for _, key := range manual[:limit] {
 			out = append(out, Suggestion{
 				Command:     fmt.Sprintf("azd env set %s <value>", key),
-				Description: "supply the agent.yaml variable",
+				Description: "referenced by agent.yaml but not set in azd env",
 				Priority:    priority,
 			})
 			priority++
 		}
+		// Follow-up: once the user supplies the values above, the next
+		// productive command is `azd ai agent run`. Without this hint
+		// the post-init Next: block stops at the env-set lines and the
+		// user has to remember the run step themselves — that's the
+		// "Then run 'azd ai agent run' to start locally" line in
+		// issue #7975's manual-vars example output. Suppressed when
+		// placeholders are also unresolved — running locally with
+		// literal `{{NAME}}` values produces a broken agent, so the
+		// user must finish the placeholder fix-ups first; the
+		// trailing `azd deploy` reminder still applies.
+		if !hasPlaceholders {
+			out = append(out, Suggestion{
+				Command:     "azd ai agent run",
+				Description: "start the agent locally once the values above are set",
+				Priority:    priority,
+			})
+		}
 	case hasPlaceholders:
 		// Only unresolved placeholders remain — do not emit
 		// `azd ai agent run` because running locally with literal

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/resolver_test.go

@@ -133,12 +133,22 @@ func TestResolveAfterInit(t *testing.T) {
 			assert.True(t, last.Trailing, "last suggestion must be flagged Trailing")
 
 			if len(tt.wantManualVarKeys) > 0 {
-				assert.Len(t, out, len(tt.wantManualVarKeys)+1)
+				// N env-set lines + 1 `azd ai agent run` follow-up + 1
+				// trailing `azd deploy`.
+				assert.Len(t, out, len(tt.wantManualVarKeys)+2)
 				for i, key := range tt.wantManualVarKeys {
 					assert.True(t,
 						strings.HasPrefix(out[i].Command, "azd env set "+key+" "),
 						"got %q", out[i].Command)
 				}
+				// The slot immediately after the env-set lines is the
+				// run follow-up — see ResolveAfterInit's MissingManualVars
+				// branch (issue #7975 manual-vars example).
+				followUp := out[len(tt.wantManualVarKeys)]
+				assert.Equal(t, "azd ai agent run", followUp.Command,
+					"expected `azd ai agent run` follow-up after env-set lines")
+				assert.False(t, followUp.Trailing,
+					"run follow-up must be a primary suggestion, not Trailing")
 			} else {
 				assert.Contains(t, out[0].Command, tt.wantPrimaryHas)
 			}
@@ -154,17 +164,55 @@ func TestResolveAfterInit_ManualVarsCapAtThree(t *testing.T) {
 		MissingManualVars:  []string{"V1", "V2", "V3", "V4", "V5"},
 	}
 	out := ResolveAfterInit(state)
-	// 3 manual + 1 trailing.
-	require.Len(t, out, 4)
-	assert.Equal(t, "azd deploy", out[3].Command)
-	assert.True(t, out[3].Trailing, "deploy footer must be Trailing")
+	// 3 env-set lines (capped) + 1 `azd ai agent run` follow-up + 1
+	// trailing `azd deploy`.
+	require.Len(t, out, 5)
+	for i := range 3 {
+		assert.True(t, strings.HasPrefix(out[i].Command, "azd env set "),
+			"slot %d should be an env-set line, got %q", i, out[i].Command)
+	}
+	assert.Equal(t, "azd ai agent run", out[3].Command,
+		"slot 3 should be the run follow-up")
+	assert.Equal(t, "azd deploy", out[4].Command)
+	assert.True(t, out[4].Trailing, "deploy footer must be Trailing")
 }
 
 func TestResolveAfterInit_NilState(t *testing.T) {
 	t.Parallel()
 	assert.Nil(t, ResolveAfterInit(nil))
 }
 
+// TestResolveAfterInit_ManualVarsSingleEmitsEnrichedShape locks the
+// single-missing-manual-var case end-to-end. Three asserts: the env-set
+// line has the enriched "referenced by agent.yaml but not set in azd
+// env" description, the `azd ai agent run` follow-up immediately follows
+// the env-set lines, and the trailing `azd deploy` reminder is preserved.
+// This is the canonical B2 fix shape from issue #7975's "Example output
+// (project ready, but manual config values missing)".
+func TestResolveAfterInit_ManualVarsSingleEmitsEnrichedShape(t *testing.T) {
+	t.Parallel()
+
+	state := &State{
+		HasProjectEndpoint: true,
+		MissingManualVars:  []string{"MY_API_KEY"},
+	}
+	out := ResolveAfterInit(state)
+	// 1 env-set + 1 run follow-up + 1 trailing.
+	require.Len(t, out, 3)
+
+	assert.Equal(t, "azd env set MY_API_KEY <value>", out[0].Command)
+	assert.Equal(t, "referenced by agent.yaml but not set in azd env", out[0].Description,
+		"enriched description must explain WHY the env-set is needed")
+	assert.False(t, out[0].Trailing)
+
+	assert.Equal(t, "azd ai agent run", out[1].Command)
+	assert.Equal(t, "start the agent locally once the values above are set", out[1].Description)
+	assert.False(t, out[1].Trailing, "run follow-up must be a primary suggestion")
+
+	assert.Equal(t, "azd deploy", out[2].Command)
+	assert.True(t, out[2].Trailing)
+}
+
 // TestResolveAfterInit_ToolboxReproRendersAllCategories locks the full
 // regression for the toolbox-sample bug end-to-end: the state contains
 // BOTH an unresolved manifest placeholder AND a missing manual env var,
@@ -191,6 +239,13 @@ func TestResolveAfterInit_ToolboxReproRendersAllCategories(t *testing.T) {
 	assert.Contains(t, rendered,
 		"azd env set TOOLBOX_WEB_SEARCH_TOOLS_MCP_ENDPOINT <value>",
 		"manual-var fix-up missing — this is the original toolbox-sample regression")
+	// `azd ai agent run` follow-up is intentionally suppressed when
+	// UnresolvedPlaceholders are also present: running locally with
+	// literal `{{NAME}}` values produces a broken agent. The user
+	// must fix the placeholder first; the trailing `azd deploy`
+	// still applies.
+	assert.NotContains(t, rendered, "start the agent locally once the values above are set",
+		"run follow-up should be suppressed while placeholders are unresolved")
 	assert.Contains(t, rendered, "azd deploy", "trailing deploy reminder missing")
 }