Stack the azure.ai.agents Next: guidance block with command highlighting (#8731)

* Stack agent "Next:" guidance with indentation and command highlighting

Restyle the post-deploy (and show/init/doctor) "Next:" guidance block in
the azure.ai.agents extension. Each suggestion now renders as a command
line over its description line, indented under a standalone "Next:" header
with a blank line between suggestions, replacing the dense right-aligned
"cmd  -- desc" rows. Runnable azd commands are highlighted blue; "see ..."
and "edit agent.yaml: ..." pointers stay plain.

- format.go: stacked renderer plus highlightCommand helper; FormatNextForNote
  emits a leading blank line and drops the 4-space continuation pre-indent.
- service_target_agent.go: join the appended Next: block with a single
  newline since the block now carries its own leading newline.
- format_test.go: new layout goldens, TestMain color suppression, and a
  highlight-routing test.

* Add CHANGELOG entry for #8731

* Keep Next: artifact note plain to avoid ANSI in --output json

Address Copilot PR review: highlightCommand applied color via
output.WithHighLightFormat, which only self-gates on NO_COLOR/non-TTY --
not azd's --output json mode. Because FormatNextForNote's result is
embedded in an artifact note that azd serializes into
`azd deploy --output json`, and the service-target Deploy path has no
output-format signal, color could leak ANSI escape codes into JSON.

Plumb an explicit colorize signal from call sites: PrintNext/PrintAllNext
take a colorize bool (terminal call sites pass true; doctor threads its
TTY-derived showNext), while FormatNextForNote always renders plain. Fix
the inaccurate doc comment that claimed WithHighLightFormat self-disables
for JSON.

Add regression tests asserting FormatNextForNote never emits ANSI even
with color enabled, and that the terminal path highlights only azd
commands.

* Restore Next: command highlighting in terminal output

Revert the unconditional plain-note change (047b6ff) so the post-deploy
Next: block highlights azd commands again in regular (color) terminal
mode. Highlighting follows the host's color state: azd core sets
FORCE_COLOR for the extension only when core itself is in color mode
(interactive TTY, NO_COLOR unset), so piped/redirected/NO_COLOR runs stay
plain.

Replace the inaccurate doc comment that claimed WithHighLightFormat
self-disables for --output json. It does not; document the actual
FORCE_COLOR-driven behavior and note the residual --output-json-on-a-TTY
gap (closing it fully needs a core change, and the common scripted JSON
case is non-TTY so it is already plain).

Author: therealjohn

cli/azd/extensions/azure.ai.agents/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 0.1.41-preview (2026-06-19)
 
+- [[#8731]](https://github.com/Azure/azure-dev/pull/8731) Improve the post-deploy `Next:` guidance with a stacked layout that puts each command on its own line above its description, adds a blank line between suggestions, and highlights `azd` commands. The new layout applies across deploy, `azd ai agent show`, `init`, and `doctor`. Thanks @therealjohn for the contribution!
 - [[#8645]](https://github.com/Azure/azure-dev/pull/8645) Detect VNET-injected Foundry accounts during `azd ai agent init` and skip remote builds up front so hosted container agents use local builds without a failing remote-build attempt first. Thanks @m5i-work for the contribution!
 - [[#8714]](https://github.com/Azure/azure-dev/pull/8714) Show a tracing disclaimer when `azd ai agent init` connects or adds an Application Insights connection. Thanks @therealjohn for the contribution!
 - [[#8685]](https://github.com/Azure/azure-dev/pull/8685) Default `azd ai agent run` local Python virtual environments to Python >= 3.13 so local runs match the minimum supported Foundry runtime. Thanks @therealjohn for the contribution!

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

@@ -7,30 +7,34 @@ import (
 	"io"
 	"slices"
 	"strings"
+
+	"github.com/azure/azure-dev/cli/azd/pkg/output"
 )
 
 const (
-	// primaryPrefix is the leading label of the first suggestion line.
-	primaryPrefix = "Next:  "
-	// continuationPrefix indents subsequent lines so commands align under
-	// the first command. Width == len(primaryPrefix).
-	continuationPrefix = "       "
-	// commandSeparator separates the (possibly padded) command from its
-	// description. Two-space gap + "-- " per the design spec.
-	commandSeparator = "  -- "
-	// maxRendered caps the block at one primary + one optional secondary
-	// line ("more than two lines drowns out command output").
+	// header labels the guidance block. It sits on its own line; the
+	// suggestions are stacked beneath it, indented by bodyIndent.
+	header = "Next:"
+	// bodyIndent indents each command and description line under the
+	// header, creating a clear visual hierarchy ("Next:" at the margin,
+	// the actionable lines stepped in beneath it).
+	bodyIndent = "  "
+	// maxRendered caps PrintNext at this many suggestions (one primary
+	// plus one optional Trailing footer). PrintAllNext and
+	// FormatNextForNote are uncapped.
 	maxRendered = 2
 )
 
 // PrintNext writes a "Next:" guidance block to w. Suggestions are sorted
 // ascending by Priority (stable; ties preserve input order) and then
-// truncated to a primary + optional secondary line. Empty input produces
-// no output and no write.
+// truncated to a primary plus an optional Trailing suggestion. Empty
+// input produces no output and no write.
 //
 // PrintNext does not inspect TTY state or output-format flags — those
 // decisions live at the call site so the same renderer can serve both
 // interactive stdout writes and string capture for tests / JSON envelopes.
+// Command highlighting is applied by the renderer via output.WithHighLightFormat,
+// which self-gates on color settings (NO_COLOR / non-TTY yield plain text).
 //
 // Use PrintAllNext when the resolver produces multiple REQUIRED follow-up
 // actions (init / doctor fix-ups) where silently dropping any of them
@@ -69,24 +73,25 @@ func PrintAllNext(w io.Writer, suggestions []Suggestion) error {
 // FormatNextForNote renders a "Next:" block as a string suitable for
 // embedding in an artifact's Metadata["note"]. Unlike PrintNext it does
 // not truncate the block (the artifact note is a contained region, not
-// interleaved with command output) and does not include a leading or
-// trailing newline (the artifact renderer adds its own line break).
+// interleaved with command output).
 //
-// Lines 2+ are pre-indented by 4 spaces so the command column stays
-// aligned with line 1 when core azd's artifact renderer (which only
-// indents the first line of the note) is called with the typical caller
-// indent of two spaces — see cli/azd/pkg/project/artifact.go, which
-// writes "\n%s  %s" with the caller's indent on line 1 only. Under
-// deeper or shallower caller indents the lines drift slightly but the
-// note remains readable in both cases.
+// The returned string begins with a newline and has no trailing newline.
+// Core azd's artifact renderer appends the note via "\n%s  %s" with the
+// caller indent applied to the first line only (see
+// cli/azd/pkg/project/artifact.go). The leading newline turns that first,
+// indent-only line into a blank separator, after which the "Next:" header
+// and its stacked, bodyIndent-indented suggestions render beneath the
+// endpoint. The deploy path renders artifacts at the zero indent, so the
+// header lands in the same column as the endpoint bullet and each
+// suggestion steps in by bodyIndent.
 //
 // Empty input returns an empty string.
 func FormatNextForNote(suggestions []Suggestion) string {
 	body := renderRows(suggestions, 0)
 	if body == "" {
 		return ""
 	}
-	return strings.ReplaceAll(strings.TrimSuffix(body, "\n"), "\n", "\n    ")
+	return "\n" + strings.TrimSuffix(body, "\n")
 }
 
 // renderBlock returns the formatted "Next:" block (with a leading blank
@@ -103,8 +108,10 @@ func renderBlock(suggestions []Suggestion, limit int) string {
 	return "\n" + body
 }
 
-// renderRows returns the formatted suggestion lines (one per line,
-// terminated with "\n") with no leading blank line. limit caps the
+// renderRows returns the formatted "Next:" body: a header line followed
+// by each suggestion rendered as an indented command line, its indented
+// description line, and a blank line separating consecutive suggestions.
+// The body has no leading blank line and ends with "\n". limit caps the
 // number of visible suggestions; limit <= 0 means render every
 // suggestion.
 //
@@ -162,27 +169,48 @@ func renderRows(suggestions []Suggestion, limit int) string {
 		return ""
 	}
 
-	cmdWidth := 0
-	for _, s := range rendered {
-		if n := len(s.Command); n > cmdWidth {
-			cmdWidth = n
-		}
-	}
-
 	var b strings.Builder
+	b.WriteString(header)
+	b.WriteByte('\n')
 	for i, s := range rendered {
-		if i == 0 {
-			b.WriteString(primaryPrefix)
-		} else {
-			b.WriteString(continuationPrefix)
-		}
-		b.WriteString(s.Command)
-		if pad := cmdWidth - len(s.Command); pad > 0 {
-			b.WriteString(strings.Repeat(" ", pad))
+		if i > 0 {
+			// Blank line between suggestions so each command/description
+			// pair reads as a distinct step.
+			b.WriteByte('\n')
 		}
-		b.WriteString(commandSeparator)
-		b.WriteString(s.Description)
+		b.WriteString(bodyIndent)
+		b.WriteString(highlightCommand(s.Command))
 		b.WriteByte('\n')
+		if s.Description != "" {
+			b.WriteString(bodyIndent)
+			b.WriteString(s.Description)
+			b.WriteByte('\n')
+		}
 	}
 	return b.String()
 }
+
+// highlightCommand returns cmd wrapped in the highlight (blue) color when
+// it is a runnable azd command (prefix "azd "), and cmd unchanged
+// otherwise. Non-command suggestions — "see <path>/README.md" pointers and
+// "edit agent.yaml: ..." instructions — stay plain.
+//
+// output.WithHighLightFormat gates on color.NoColor. In this extension that
+// flag is driven by the FORCE_COLOR env var azd core sets when core itself
+// is in color mode (interactive TTY, NO_COLOR unset); for piped, redirected,
+// or NO_COLOR runs core omits it, so color.NoColor is true and commands stay
+// plain. This keeps highlighting aligned with the host's color state without
+// the renderer inspecting TTY/output flags directly.
+//
+// Known limitation: core sets FORCE_COLOR from its own TTY state without
+// accounting for --output json, so a block rendered into an artifact note
+// (see FormatNextForNote) during `--output json` from a color TTY can carry
+// ANSI into the JSON. Closing that gap requires a core change (skip
+// FORCE_COLOR for JSON output); the common scripted/piped JSON case is
+// non-TTY, so color.NoColor is already true there and the note stays plain.
+func highlightCommand(cmd string) string {
+	if strings.HasPrefix(cmd, "azd ") {
+		return output.WithHighLightFormat("%s", cmd)
+	}
+	return cmd
+}