[docs] Update aspire doctor docs with Aspire version checks

[aspire-repo-bot]

Documents changes from microsoft/aspire#17003 by @davidfowl.

Targeting release/13.4 based on the source PR milestone 13.4.

Why this PR is needed

PR microsoft/aspire#17003 added a new Aspire check category to the aspire doctor command. This category reports:

• The current Aspire CLI version (with a warning and aspire update suggestion when a newer version is available)
• The AppHost Aspire SDK version when an AppHost project is discovered in the current directory

The existing aspire-doctor.mdx page did not mention this new check category, did not show the updated sample output with the Aspire section, and had a minimal JSON output example that did not include the new cli-version and apphost-version check shapes.

What changed

Updated src/frontend/src/content/docs/reference/cli/commands/aspire-doctor.mdx:

• Added Aspire checks to the check category list describing what CLI and AppHost version information is reported
• Replaced the sample output with a fuller example showing the Aspire section, including the out-of-date CLI warning with the aspire update suggestion
• Expanded the JSON output format section to include cli-version and apphost-version check examples, including metadata fields and the warning shape when the CLI is out of date

Files modified

• src/frontend/src/content/docs/reference/cli/commands/aspire-doctor.mdx (updated)

Generated by PR Documentation Check for issue #17003 · ● 11.7M · ◷

[Copilot]

Pull request overview

Updates the aspire doctor CLI command reference to document the new Aspire version checks added to the command, including updated sample output and expanded JSON output examples.

Changes:

• Adds an Aspire checks category description covering CLI and AppHost version reporting.
• Updates the table sample output to include the new Aspire section and an out-of-date CLI warning example.
• Expands the JSON output section with cli-version / apphost-version examples and a warning-case example.

Comments suppressed due to low confidence (1)

src/frontend/src/content/docs/reference/cli/commands/aspire-doctor.mdx:178

• In the JSON output example, status is shown as lowercase ("pass"/"warn") for the new checks but as "Pass" for the existing SDK check. Please make the status casing consistent across the whole JSON example and match whatever the CLI actually emits.

  "checks": [
    {
      "category": "aspire",
      "name": "cli-version",
      "status": "pass",
      "message": "Aspire CLI version 13.4.0",
      "metadata": {
        "currentVersion": "13.4.0"
      }
    },
    {
      "category": "apphost",
      "name": "apphost-version",
      "status": "pass",
      "message": "AppHost version 13.4.0 (MyApp.AppHost.csproj)",
      "metadata": {
        "appHostPath": "MyApp.AppHost.csproj",
        "version": "13.4.0"
      }
    },
    {
      "category": "sdk",
      "message": ".NET SDK 10.0.100 or later is installed",
      "status": "Pass"
    }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[IEvangelist]

Docs-from-code review

Source of truth: microsoft/aspire @ release/13.4 (SHA d8c4e9645a029b4fca8ce20eb00def5526806eda)
PR head: cd2e31df907a913606758bd6c3a1d684d04efe8a

Verdict counts

Verdict	Count
verified	12
verified-with-nuance	3
contradicted	4
unverifiable	0

Summary

The new aspire and apphost checks added in microsoft/aspire#17003 are present in the source, and the human-readable / JSON shapes the doc describes are largely correct. Four claims are contradicted by the source on this branch — three in the "Sample output" block and one in the JSON warning example — and are called out inline below. The collapsed block at the bottom lists every claim that was checked.

Verified and verified-with-nuance claims (audit log)

• verified — A new "Aspire checks" category set is added by microsoft/aspire#17003 that reports CLI version and AppHost SDK version. Evidence: src/Aspire.Cli/Utils/EnvironmentChecker/AspireVersionCheck.cs (entire file).
• verified-with-nuance (line 36) — The bullet describes "Aspire checks" as a single category, but the source produces two distinct categories ("aspire" → cli-version, "apphost" → apphost-version) with separate section headers (Aspire and AppHost). The prose simplifies; the category structure is what drives the actual section layout.
• verified — Header Aspire Environment Check followed by a same-length = underline. Evidence: DoctorCommandStrings.resx (EnvironmentCheckHeader); DoctorCommand.OutputHumanReadable writes WriteLine(new string('=', DoctorCommandStrings.EnvironmentCheckHeader.Length)).
• verified-with-nuance (line 88) — Checking Aspire environment... does come from DoctorCommandStrings.resx (CheckingPrerequisites), but ConsoleInteractionService.ShowStatusAsync renders it as a Spectre Status spinner. In an interactive TTY the spinner is transient and is cleared before the header is written; the line only persists in debug / non-interactive mode (DisplaySubtleMessage fallback). Worth noting that a normal interactive run will not show this line above the header.
• verified (line 93) — Aspire header. Evidence: DoctorCommandStrings.resx AspireCategoryHeader = "Aspire".
• verified (line 94) — ✅ Aspire CLI version 13.4.0 matches CliVersionMessageFormat = "Aspire CLI version {0}" for the pass case (no channel suffix).
• verified (line 97-98) — .NET SDK header and ✅ .NET 10.0.203 installed (arm64) match DotNetSdkCheck.cs:67: $".NET {highestVersion} installed ({architecture})" and SdkCategoryHeader = ".NET SDK".
• verified (line 100-101) — Container Runtime sample line format matches the existing ContainerRuntimeCheck output (unchanged from prior sample).
• verified (line 103-104) — Environment header + HTTPS development certificate is trusted. Evidence: EnvironmentCategoryHeader and DevCertsTrustedMessage.
• verified (line 114) — ⚠️ Aspire CLI version {x} is out of date. Latest version is {y} matches CliVersionOutOfDateMessageFormat.
• verified (line 115) — Run 'aspire update' to update Aspire CLI. matches CliVersionOutOfDateFixFormat with status.UpdateCommand defaulting to "aspire update".
• verified (lines 156-163) — JSON pass shape for cli-version: category: "aspire", name: "cli-version", status: "pass", message, metadata.currentVersion. Evidence: AspireVersionCheck.cs:125-132 and EnvironmentCheckResult.cs [JsonPropertyName] attributes.
• verified (lines 164-173) — JSON pass shape for apphost-version: category: "apphost", name: "apphost-version", status: "pass", metadata with appHostPath (always present) and version (present when known). Evidence: AspireVersionCheck.cs:288-305 and BuildAppHostVersionMetadata.
• verified-with-nuance (lines 196-199) — The warning metadata in the doc lists only currentVersion and latestVersion. At runtime BuildCliVersionMetadata also emits updateCommand (when status.UpdateCommand is non-empty, which is the normal out-of-date path) and may emit identityChannel / latestVersionChannel. The example is a valid minimal shape but isn't exhaustive.
• verified (line 203) — "The apphost-version check is only present in the JSON output when an AppHost project is discovered in the current directory." Matches AspireVersionCheck.GetAppHostVersionCheckAsync which returns null on ProjectLocatorFailureReason.NoProjectFileFound / ProjectFileDoesntExist (lines 217-222), and CheckAsync only adds the result when non-null (lines 60-63).

[IEvangelist]

Combined docs-accuracy review

Automated docs-from-code review combining a source-of-truth verification pass (Phase A) and a doc-tester skill pass that exercised the page as a new user would (Phase B).

Source of truth (Phase A)

• Repo: microsoft/aspire
• Branch: release/13.4
• SHA: cbc352350f1a9bafbaff10d14a2c8de4ac186a48
• Backing PR: microsoft/aspire#17003 (Add doctor Aspire version checks), merged with milestone 13.4, present in release/13.4 at commit 2ee7d1b5c

Phase A summary

Verdict	Count
verified	17
verified-with-nuance	4
contradicted	0
unverifiable	0

All [contradicted] items from the previous review were addressed in 89734939. No new contradictions found. Three remaining nuances are flagged inline below; the fourth is folded into the doc-tester section.

Phase B summary

• Skill run: doc-tester (no source code consulted in this phase)
• Route exercised: /reference/cli/commands/aspire-doctor/
• CLI commands run from the docs: aspire doctor, aspire doctor --format Json (Aspire CLI 13.5.0-preview.1.26277.22, channel daily)
• Findings: 0 critical, 4 warnings/knowledge gaps (see Phase B section below)

---

Phase A — verified claims

17 verified + 4 verified-with-nuance (click to expand)

#	Claim	Verdict	Evidence (microsoft/aspire @ cbc352350)
1	"Aspire checks" bullet describes behavior	verified-with-nuance	src/Aspire.Cli/Utils/EnvironmentChecker/AspireVersionCheck.cs + Resources/DoctorCommandStrings.resx CliVersionOutOfDateFixFormat — wording is grammatically truncated (see inline comment)
2	"AppHost checks" bullet — only present when AppHost discovered	verified	AspireVersionCheck.GetAppHostVersionCheckAsync returns null when ProjectLocatorFailureReason.NoProjectFileFound
3	"Checking Aspire environment..." preamble	verified	DoctorCommandStrings.resx: CheckingPrerequisites = "Checking Aspire environment..."
4	"Aspire Environment Check" header + 24 = underline	verified	DoctorCommand.OutputHumanReadable writes new string(''='', DoctorCommandStrings.EnvironmentCheckHeader.Length); header is 24 chars
5	"Aspire" section header (order 0)	verified	DoctorCommand.GetCategoryHeader("aspire") -> AspireCategoryHeader = "Aspire"; GetCategoryOrder("aspire") = 0
6	✅ Aspire CLI version 13.4.0 (2-space indent)	verified	CliVersionMessageFormat = "Aspire CLI version {0}"; Padder(messageGrid, new Padding(2, 0))
7	"AppHost" section header (order 1)	verified	AppHostCategoryHeader = "AppHost"; GetCategoryOrder("apphost") = 1
8	✅ AppHost version 13.4.0 (MyApp.AppHost.csproj)	verified	AppHostVersionMessageFormat = "AppHost version {0} ({1})"
9	.NET 10.0.203 installed (arm64)	verified	DotNetSdkCheck.cs:67: Message = $".NET {highestVersion} installed ({architecture})"
10	"Environment" section ordering after Container Runtime	verified	GetCategoryOrder: container=3, environment=4
11	✅ HTTPS development certificate is trusted	verified	DevCertsTrustedMessage = "HTTPS development certificate is trusted"
12	Summary: 5 passed, 0 warnings, 0 failed	verified	SummaryFormat = "Summary: {0} passed, {1} warnings, {2} failed"; 5 = Aspire+AppHost+SDK+Container+Environment
13	Out-of-date message Aspire CLI version 13.4.0-dev is out of date. Latest version is 13.4.0-preview.1.26262.10	verified	CliVersionOutOfDateMessageFormat = "Aspire CLI version {0} is out of date. Latest version is {1}"
14	7-space-indented Run ''aspire update'' to update Aspire CLI.	verified	CliVersionOutOfDateFixFormat = "Run ''{0}'' to update Aspire CLI."; Padder(detailGrid, new Padding(7, 0)) (DoctorCommand.cs:215)
15	JSON: category, name, status (lowercase), message, metadata shape	verified	EnvironmentCheckResult [JsonPropertyName] attributes + LowercaseEnumConverter
16	JSON: aspire/cli-version/pass with currentVersion metadata	verified	BuildCliVersionMetadata emits currentVersion when non-empty
17	JSON: apphost/apphost-version/pass with appHostPath + version metadata	verified	BuildAppHostVersionMetadata emits appHostPath always, version when non-empty
18	JSON: existing sdk example with lowercase "status": "pass"	verified	LowercaseEnumConverter.Write writes value.ToString().ToLowerInvariant()
19	JSON: summary block { passed, warnings, failed }	verified-with-nuance	DoctorCheckSummary shape correct; the example mixes an abbreviated checks array with a full-count summary — see inline comment
20	JSON: out-of-date warning shape with latestVersion metadata	verified-with-nuance	BuildCliVersionMetadata adds latestVersion; example omits the fix field that the live serializer emits — see inline comment
21	"apphost-version check only present when an AppHost project is discovered"	verified-with-nuance	True for the "no AppHost found" path; warning-status apphost-version entries are still emitted when discovery succeeds but version resolution fails. Not worth a doc change — included for completeness.

---

Phase B — doc-tester findings

Skill: doc-tester (no source code consulted). Route exercised: /reference/cli/commands/aspire-doctor/. Acting as a new user, copying commands verbatim from the proposed page.

Critical issues

None.

Warnings & knowledge gaps

Warning 1: JSON sample omits the installations top-level field

Location: ## JSON output format section, first JSON example.

What the docs say (paraphrased): the JSON response contains checks and summary.

What I observed running the documented command (aspire doctor --format Json):

{
  "checks": [ /* ... */ ],
  "summary": { /* ... */ },
  "installations": [
    {
      "path": "C:\\Users\\dapine\\.aspire\\bin\\aspire.exe",
      "version": "13.5.0-preview.1.26277.22+9a9ddbbf2d4a36b9a2af1e13cba8ed8cd29bc6d6",
      "channel": "daily",
      "pathStatus": "active",
      "status": "ok"
    }
    /* additional installs trimmed */
  ]
}

The installations array always appears. A user writing a parser against the documented shape will be surprised by this extra top-level field. This is plausibly out of scope for this PR (the installations payload comes from a separate feature) but is worth a follow-up doc task or at least a short forward-reference here so the example is not misleading.

Warning 2: identityChannel metadata field not documented

Location: ## JSON output format section, first JSON example (the aspire/cli-version entry).

Documented metadata for the pass case:

"metadata": { "currentVersion": "13.4.0" }

What I observed:

"metadata": {
  "currentVersion": "13.5.0-preview.1.26277.22",
  "identityChannel": "daily"
}

identityChannel is emitted by the same cli-version check this PR documents, whenever the CLI build has a channel identifier. The metadata example should either mention this field or include a brief note that other channel/diagnostic fields may be present.

Warning 3: Sample human-readable output is missing the trailing installations table

Location: ## Sample output section, first code block.

The documented sample ends at Summary: 5 passed, 0 warnings, 0 failed. The actual command output continues with an "Aspire CLI Installations" table for every Aspire install on the machine. Same root cause as Warning 1 — same recommendation: a short note that additional installation details follow, or a separate examples entry in a follow-up doc task.

Warning 4: Out-of-date warning JSON example omits the fix field

See inline comment on the warning JSON example. Without it, an automation consumer reading just the docs may not realize the actionable fix string is part of the JSON shape.

Passed checks

• Page renders cleanly; existing Aside, AsciinemaPlayer, Include imports are still used.
• All three "See also" links return HTTP 200 on the live site (/reference/cli/commands/aspire/, /reference/cli/commands/aspire-run/, /reference/cli/overview/).
• Section order in the documented sample (Aspire → AppHost → .NET SDK → Container Runtime → Environment) matches the section order produced by the command in practice.
• Lowercase JSON enum status ("pass", "warning") matches what the CLI actually emits — the previous review''s "warn" finding has been addressed.
• The Summary 5 passed count now matches the five ✅ rows above it.

Recommendations

1. Either expand the JSON example to include installations and identityChannel, or add a one-line note acknowledging additional fields may appear (Warnings 1, 2, 3).
2. Add "fix": "Run ''aspire update'' to update Aspire CLI." to the warning JSON example (Warning 4, inline).
3. Fix the truncated "when one is" prose in the Aspire-checks bullet (Phase A nuance, inline).

---

Verdict

COMMENT — no factual contradictions remain. Several verified-with-nuance items and doc-tester knowledge gaps are worth surfacing but none are blocking.

[IEvangelist]

Automated docs-accuracy review (hourly bot)

Source of truth (Phase A): microsoft/aspire @ release/13.4 — SHA 11bea2eb9fbb655614bcf9814c55c88a3fdd1126.
PR head reviewed: 0a068a0fb95cccd215cd3bf346417a5d8519b89b.

Phase A — claim verification (20 non-narrative claims extracted from the changed file):

verdict	count
verified	18
verified-with-nuance	1
unverifiable	0
contradicted	1

Phase B — doc-tester run: exercised /reference/cli/commands/aspire-doctor/ with the live Aspire CLI (13.5.0-preview.1.26279.46, channel daily) in both an empty directory and a freshly-templated aspire new aspire-starter project, table and JSON formats. 1 critical issue, 4 warnings, 0 broken links.

Combined verdict: REQUEST_CHANGES — one contradicted claim + one critical doc-tester finding (same underlying issue: the SDK JSON sample message string is stale). The substance of the PR is good; this is a localized fix in the JSON example block plus a handful of small accuracy nits.

---

Phase A — Claim verification

The single contradicted claim is flagged as an inline review comment on the diff (SDK JSON message string).

Verified / verified-with-nuance claims (19 of 20) — click to expand evidence

ID	Where	Verdict	Evidence in microsoft/aspire@release/13.4
C1	L36 — "Aspire checks" bullet	verified	Utils/EnvironmentChecker/AspireVersionCheck.cs:91-122 — emits category:"aspire" / name:"cli-version"; out-of-date sets Status=Warning and Fix = "Run '{aspire update}' to update Aspire CLI."
C2	L37 — "AppHost checks" bullet (current dir only)	verified	AspireVersionCheck.cs:359-386 — searchParentDirectories: false, AppHostDiscoveryScope.ExplicitDirectory, maxDepth: 0
C3	L89 — Checking Aspire environment...	verified	DoctorCommandStrings.resx CheckingPrerequisites; DoctorCommand.cs:87-89
C4	L91-92 — header + = underline	verified	DoctorCommandStrings.resx EnvironmentCheckHeader; DoctorCommand.cs:133-134
C5	L94 — Aspire group header	verified	DoctorCommandStrings.resx AspireCategoryHeader; DoctorCommand.cs:235
C6	L95 — Aspire CLI version 13.4.0 + 2-space indent	verified	CliVersionMessageFormat; DoctorCommand.cs:183 (Padding(2,0))
C7	L97 — AppHost group header	verified	AppHostCategoryHeader
C8	L98 — AppHost version 13.4.0 (MyApp.AppHost.csproj)	verified	AppHostVersionMessageFormat = "AppHost version {0} ({1})"
C9	L100-101 — .NET 10.0.203 installed (arm64)	verified	DotNetSdkCheck.cs:60-68 — $".NET {highestVersion} installed ({architecture})"
C10	L103-107 — Container/Environment lines	verified	unchanged check sources
C11	L109 — Summary: 5 passed, 0 warnings, 0 failed	verified	SummaryFormat + 5 categories observed live
C12	L114-121 — out-of-date sample + 7-space fix indent	verified	CliVersionOutOfDateMessageFormat / CliVersionOutOfDateFixFormat; DoctorCommand.cs:215 (Padding(7,0))
C13	L159-167 — JSON pass cli-version shape	verified-with-nuance	AspireVersionCheck.cs:125-132 confirms fields; BuildCliVersionMetadata (414-449) also writes updateCommand on a successful real run — the doc's "additional metadata" disclaimer covers it, but the field name isn't called out
C14	L168-177 — JSON pass apphost-version shape	verified	AspireVersionCheck.cs:288-305 + BuildAppHostVersionMetadata (451-469)
C16	L181 — "status": "pass"	verified	EnvironmentCheckResult.cs:33,99-117 — LowercaseEnumConverter
C17	L183-188 — summary block fields	verified	DoctorCheckSummary in EnvironmentCheckResult.cs:148-167
C18	L154 — "discovered Aspire CLI installations"	verified	DoctorCheckResponse.Installations + DoctorCommand.cs:84,121
C19	L194-205 — JSON out-of-date cli-version shape	verified	AspireVersionCheck.cs:100-122
C20	L208 — apphost-version only when AppHost discovered	verified	AspireVersionCheck.cs:216-222,327 + CheckAsync line 60 guard

---

Phase B — doc-tester report

Following the doc-tester skill rules: navigated/executed as a new user would, without consulting microsoft/aspire source. The local CLI under test was 13.5.0-preview.1.26279.46 (channel: daily); section ordering, schema, indentation, and message templates are stable across 13.4 → 13.5, so the documented shapes tested cleanly. Only literal version strings and the channel suffix differ.

Scope: /reference/cli/commands/aspire-doctor/ (the only page changed by this PR). Real CLI exercised in two scenarios mirroring the doc's samples: empty directory (no AppHost) and a freshly-templated aspire new aspire-starter project, in both table and JSON formats. See also links resolved against https://aspire.dev/ (all 200).

Category	Passed	Failed	Warnings
Content accuracy	8	1	3
Code/JSON examples	6	1	2
CLI commands	3	0	1
Links	3	0	0

Critical issues

Issue 1 — SDK JSON message is stale; name field missing. Same finding as Phase A C15, observed independently by running the CLI blind to source. See the inline comment on the JSON sdk block.

Warnings

W1 — Aspire CLI Installations table is never mentioned in the human-readable sample. After Summary: … the CLI always prints a second block listing every discovered CLI (path, version, channel, route, PATH status). The doc only references it in the JSON section ("discovered Aspire CLI installations"). A reader following the ## Sample output block will see substantially more output than expected and may wonder whether the installations table is normal.

Suggestion: either add the table to the human-readable sample, or add a single sentence under ## Sample output like "An Aspire CLI Installations table listing every discovered CLI on the machine is also printed after the summary."

W2 — documented version strings omit the (channel: <name>) suffix non-stable builds always emit. Real output on a daily/staging/PR build:

Aspire
  ✅ Aspire CLI version 13.5.0-preview.1.26279.46 (channel: daily)

AppHost
  ✅ AppHost version 13.5.0-preview.1.26279.46 (channel: daily) (MyApp.AppHost\MyApp.AppHost.csproj)

The PR sample uses clean 13.4.0 without suffix. Readers on staging / daily / pr-* channels (the cohort most likely to read freshly-updated docs) will see the suffix and may wonder if their environment is misconfigured.

Suggestion: add a short note after the second sample explaining the inline (channel: <name>) suffix and how it maps to the JSON identityChannel field.

W3 — JSON metadata examples omit channel-related fields that almost always appear in practice.

• Real cli-version metadata on a daily build includes "identityChannel": "daily" in addition to currentVersion.
• Real apphost-version metadata in an aspire new-generated project includes "pinnedChannel": "daily" in addition to appHostPath / version (the template emits aspire.config.json with channel: daily).

The current "actual output … can include additional metadata, such as channel information" disclaimer is technically correct, but identityChannel / pinnedChannel / latestVersionChannel aren't named anywhere in the doc, so a JSON consumer doesn't know what to grep for.

Suggestion: list the channel-related metadata field names in the disclaimer (or include one in the example).

W4 — the out-of-date warning snippet omits the trailing For detailed prerequisites: … line. When warnings > 0 || failed > 0 the doctor command appends a For detailed prerequisites: link line after the summary. The PR's warning snippet is abbreviated (cuts off after the fix), which is fine for an example — a one-line callout that the snippet is abbreviated would make the omission unambiguous to anyone diffing it against their terminal.

Passed checks

• Checking Aspire environment... status line — present and identical.
• Aspire Environment Check bold header underlined by matching-length = row — present and identical.
• Section header strings (Aspire, AppHost, .NET SDK, Container Runtime, Environment) — exact match.
• Section ordering top-to-bottom matches actual output.
• Two-space indent for check rows and seven-space indent for fix suggestions — matches.
• Summary: N passed, N warnings, N failed template — exact match.
• 5 passed corresponds to one entry per category (verified by counting live output in an AppHost dir).
• apphost-version only present when an AppHost is discovered — verified by comparing empty-dir and AppHost-dir runs live.
• status rendered lowercase in JSON — matches.
• DoctorCheckResponse shape (checks, summary, installations) — matches.
• See also links all return 200 from https://aspire.dev/.

Knowledge gaps surfaced by the doc-tester pass

• The Aspire CLI Installations trailing table is never explained on this page; a new user encountering multiple discovered CLIs has no guidance for what to do.
• The (channel: <name>) annotation that appears on non-stable installs has no on-page explanation; a reader has to infer that it correlates with the JSON identityChannel field.

Recommendations

1. Priority: refresh the sdk JSON example so its message mirrors the .NET <version> installed (<arch>) shape from the human sample, and add "name": "dotnet-sdk" for parity with the other JSON entries.
2. Add the Aspire CLI Installations table to the human-readable sample (or a one-line note that it appears).
3. Mention the inline (channel: <name>) version suffix and tie it to the JSON identityChannel field.
4. Spell out the channel-related metadata field names (identityChannel, pinnedChannel, latestVersionChannel) in the abbreviation disclaimer.

---

Out-of-scope items skipped by design: style/voice, grammar, broken-link checking outside the changed file, speculative future behavior.

[IEvangelist]

docs-from-code review (automated, hourly)

Source of truth: microsoft/aspire branch release/13.4 at SHA becb48e2d61099e35ae336d527d3875e928d6594
PR head reviewed: a6397b3e75f7fa667e38f5fdd1583493bebf0527

Phase A (claim verification): 17 claims extracted across the single changed file (reference/cli/commands/aspire-doctor.mdx). Verdict: 17 verified, 0 verified-with-nuance, 0 unverifiable, 0 contradicted. Every category name, check name, message format string, JSON shape, and metadata field shown in the PR matches the implementation in src/Aspire.Cli/Commands/DoctorCommand.cs, src/Aspire.Cli/Utils/EnvironmentChecker/AspireVersionCheck.cs, src/Aspire.Cli/Utils/EnvironmentChecker/EnvironmentCheckResult.cs, src/Aspire.Cli/Utils/EnvironmentChecker/DotNetSdkCheck.cs, src/Aspire.Cli/Commands/InstallationInfoOutput.cs, and src/Aspire.Cli/Resources/DoctorCommandStrings.resx.

Phase B (doc-tester skill): 1 page exercised against a local Aspire dev build (http://localhost:57129/reference/cli/commands/aspire-doctor/) by overlaying the PR head .mdx onto the worktree and re-rendering. Verdict: 0 critical, 4 warnings, 2 knowledge gaps — all enhancement suggestions, no blockers.

Overall verdict: COMMENT — no contradicted claims and no critical doc-tester findings, but several knowledge-gap / missing-example opportunities are worth surfacing to the author for consideration. None of them block merge.

---

Phase A — Claim verification

No contradicted or unverifiable claims this revision, so there are no inline comments from Phase A. Every claim is verified — the catalog below is provided so you can audit my work.

Verified claims (17)

#	Location (PR file)	Claim	Evidence in microsoft/aspire@becb48e2
C1	aspire-doctor.mdx:36	"Aspire checks: Reports the current Aspire CLI version and whether a newer CLI version is available, and suggests running aspire update when a newer one is available"	AspireVersionCheck.cs:91-132 (Category="aspire", Name="cli-version"); AspireVersionCheck.cs:120 Fix uses status.UpdateCommand ?? "aspire update"; resource CliVersionOutOfDateFixFormat = Run '{0}' to update Aspire CLI.
C2	aspire-doctor.mdx:37	"AppHost checks: Reports the AppHost Aspire SDK version when an AppHost project is present in the current directory"	AspireVersionCheck.cs:210-328 GetAppHostVersionCheckAsync returns null when no AppHost is discovered; ResolveAppHostFilesAsync uses searchParentDirectories: false and maxDepth: 0 (AspireVersionCheck.cs:366-376)
C3	aspire-doctor.mdx:90 ("Checking Aspire environment...")	Status banner is "Checking Aspire environment..."	DoctorCommandStrings.resx:92-94 (CheckingPrerequisites); used in DoctorCommand.cs:87-89
C4	aspire-doctor.mdx:92 ("Aspire Environment Check")	Header is "Aspire Environment Check"	DoctorCommandStrings.resx:67-69 (EnvironmentCheckHeader); used in DoctorCommand.cs:133-134
C5	aspire-doctor.mdx:95,98,101,104,107	Category section headers are exactly Aspire, AppHost, .NET SDK, Container Runtime, Environment	DoctorCommandStrings.resx:70-84; mapping in DoctorCommand.cs:230-241 GetCategoryHeader
C6	aspire-doctor.mdx:96 ("Aspire CLI version 13.4.0")	Pass message format Aspire CLI version {0}	DoctorCommandStrings.resx:98-100 (CliVersionMessageFormat); applied in AspireVersionCheck.cs:154-160
C7	aspire-doctor.mdx:99 ("AppHost version 13.4.0 (MyApp.AppHost.csproj)")	AppHost format AppHost version {0} ({1})	DoctorCommandStrings.resx:117-119 (AppHostVersionMessageFormat); applied in AspireVersionCheck.cs:299-303
C8	aspire-doctor.mdx:102 (".NET 10.0.203 installed (arm64)")	SDK pass message is .NET {version} installed ({architecture}) with architecture lowercased	DotNetSdkCheck.cs:60-68 (RuntimeInformation.ProcessArchitecture.ToString().ToLowerInvariant())
C9	aspire-doctor.mdx:111 ("Summary: 5 passed, 0 warnings, 0 failed")	Summary format Summary: {0} passed, {1} warnings, {2} failed	DoctorCommandStrings.resx:85-87 (SummaryFormat); used in DoctorCommand.cs:160
C10	aspire-doctor.mdx:114-116 ("Aspire CLI Installations table … path, version, channel, install route, and PATH status")	Installations table with those 5 columns	InstallationInfoOutput.cs:85-98 adds columns ColumnPath / ColumnVersion / ColumnChannel / ColumnRoute / ColumnPathStatus; header HeaderInstallations = "Aspire CLI Installations" (DoctorCommandStrings.resx:184-186)
C11	aspire-doctor.mdx:121 ("Aspire CLI version 13.4.0-dev is out of date. Latest version is 13.4.0-preview.1.26262.10")	Out-of-date message format Aspire CLI version {0} is out of date. Latest version is {1}	DoctorCommandStrings.resx:102-104 (CliVersionOutOfDateMessageFormat); used in AspireVersionCheck.cs:115-119
C12	aspire-doctor.mdx:122 ("Run 'aspire update' to update Aspire CLI.")	Fix string Run '{0}' to update Aspire CLI. with aspire update fallback	DoctorCommandStrings.resx:106-108 (CliVersionOutOfDateFixFormat); AspireVersionCheck.cs:120 status.UpdateCommand ?? "aspire update"
C13	aspire-doctor.mdx:131 ("For detailed prerequisites: https://aka.ms/aspire-prerequisites printed on warnings or failures")	Link line printed only when there are warnings/failures	DoctorCommand.cs:163-167 if (warnings > 0 || failed > 0) with hard-coded https://aka.ms/aspire-prerequisites and resource DetailedPrerequisitesLink = For detailed prerequisites: {0} (DoctorCommandStrings.resx:88-90)
C14	aspire-doctor.mdx:132 ("inline (channel: <name>) suffix")	Channel suffix format (channel: {0})	DoctorCommandStrings.resx:113-115 (ChannelSuffixFormat); applied via WithChannelSuffix / AppendChannelSuffix in AspireVersionCheck.cs:168-193
C15	aspire-doctor.mdx:133-135 (identityChannel, latestVersionChannel, pinnedChannel, updateCommand metadata)	Those property names exist in CLI / AppHost version metadata	AspireVersionCheck.cs:414-449 (BuildCliVersionMetadata): emits currentVersion, latestVersion, updateCommand, updateCheckError, identityChannel, latestVersionChannel. AspireVersionCheck.cs:451-469 (BuildAppHostVersionMetadata): emits appHostPath, version, pinnedChannel
C16	aspire-doctor.mdx:162-217 (JSON shape: checks[] with category, name, status lowercase, message, optional fix/metadata; plus summary)	JSON shape and lowercase status	EnvironmentCheckResult.cs:11-73 (JsonPropertyName attributes; Status uses LowercaseEnumConverter at lines 99-117 which writes value.ToString().ToLowerInvariant()); DoctorCheckResponse at lines 123-142 (checks, summary, installations)
C17	aspire-doctor.mdx:217 ("The apphost-version check is only present in the JSON output when an AppHost project is discovered in the current directory")	Check is omitted when no AppHost is discovered	AspireVersionCheck.cs:60-65,327 — returns the result only when appHostVersionCheck is not null; returns null when ResolveAppHostFilesAsync finds no candidates

---

Phase B — doc-tester results (blind-user perspective)

The PR head was overlaid into the running aspire.dev worktree and the page was fetched from the local Astro server. Findings below are recorded without consulting microsoft/aspire source — per the doc-tester skill's "test as a new user" contract.

Page exercised: /reference/cli/commands/aspire-doctor/

Summary

Category	Passed	Failed	Warnings
Content accuracy	All visible claims	0	0
Code / output examples	5 rendered fine	0	0
CLI commands	(no commands run — page is reference-only)	0	0
Links	All internal See also links target existing pages	0	0

Critical issues

None.

Warnings

W1: "AppHost Aspire SDK version" vs the sample's "AppHost version"

Location: Description bullet at the top vs Sample output.
Issue: The bullet introduces the AppHost check as reporting the "AppHost Aspire SDK version", but every sample/JSON snippet below renders the message as just "AppHost version 13.4.0 (MyApp.AppHost.csproj)" with no "SDK" in the label. A new reader has to infer the two phrases refer to the same thing.
Suggestion: Either say "AppHost version" in the bullet (matching the runtime output) or add a one-line clarification, e.g., "(displayed as 'AppHost version' in the output, which corresponds to the AppHost project's Aspire.Hosting package version)".

W2: Three channel fields are name-dropped but never explained

Location: Paragraph after the "When the CLI is out of date" snippet, and the JSON output paragraph.
Issue: The text lists identityChannel, latestVersionChannel, pinnedChannel, and updateCommand as metadata fields the JSON "can include". A blind reader sees three different channel-related keys and an updateCommand field, with no indication of what data each carries (e.g., which one is "what this CLI build came from" vs "what channel the latest release lives on" vs "what the AppHost is pinned to") and no example JSON that actually contains any of them.
Suggestion: Add a brief field reference (a definition list or small table) for the optional metadata keys, ideally with a JSON snippet that includes them so users can see the shape. Even one sentence per field would close the gap.

W3: The "(channel: )" inline suffix is described but never shown in any sample

Location: Paragraph after the out-of-date snippet.
Issue: The page says "Some CLI and AppHost version messages include an inline (channel: <name>) suffix". Both the all-pass and out-of-date table samples above this paragraph render messages without the suffix, so a new user has no concrete example of what the suffix looks like in context (e.g., where exactly it appears for the out-of-date case where two versions are mentioned).
Suggestion: Include one short sample line, e.g., Aspire CLI version 13.4.0-dev (channel: local) is out of date. Latest version is 13.4.0-preview.1.26262.10 (channel: prerelease), so users can recognize it when they see it.

W4: The "Aspire CLI Installations" table is described but never rendered as a sample

Location: Paragraph immediately following the all-pass table output.
Issue: The page tells the reader "table output also includes an Aspire CLI Installations table that lists discovered CLI binaries with their path, version, channel, install route, and PATH status," but the sample output stops at Summary: 5 passed, 0 warnings, 0 failed. A blind user can't tell whether the columns are literal text or formatted differently, what PATH status values look like, or how the currently running CLI is distinguished.
Suggestion: Append a small example table to the all-pass sample (even 1-2 rows) showing realistic values for each column, including the visual marker for "this is the currently running CLI". This is a high-value addition because the section heading suggests it's a notable new piece of output.

Knowledge gaps (used intrinsic knowledge to read past)

K1: "13.4.0-dev" in the out-of-date sample is unexplained

What I needed to know: That -dev is an Aspire CLI channel/build label rather than a generic version suffix.
Source of my knowledge: Built-in / prior context — the docs page does not define it.
User impact: Readers seeing 13.4.0-dev in the out-of-date warning may not connect it to the channel concept introduced one paragraph later (identityChannel, etc.), missing the link between "I'm on a dev build" and "the warning is comparing dev → preview".
Suggestion: A single sentence inline ("Here 13.4.0-dev is a dev-channel build of the CLI; see [Aspire CLI channels link]") would close this gap.

K2: "AppHost project is present in the current directory" — discovery scope is unstated

What I needed to know: Whether the AppHost check searches subdirectories, follows the aspire-config.json settings, or only looks at literal cwd.
Source of my knowledge: Built-in / prior context.
User impact: Users running aspire doctor from a repo root that contains the AppHost in a subdirectory may be surprised when the AppHost section is missing from the output (or appears unexpectedly when they're in a sibling project).
Suggestion: Add a clarifying sentence like "Only the current working directory is searched; no recursive scan." or describe the resolution order (explicit settings → single AppHost-looking file in cwd → skipped).

Passed checks

• Page loads cleanly (HTTP 200, 850 KB rendered)
• All five new sample-output snippets and both JSON snippets render correctly with the new line indentation matching what the Aspire / AppHost / .NET SDK sections actually emit at runtime
• Category bullet list is in the same order Aspire prints categories at runtime (Aspire → AppHost → SDK → Container → Environment)
• "Aspire CLI" code-block headers and JSON output titles render
• The Note Aside about aspire setup replacement still surfaces cleanly
• All See also links resolve to existing pages (/reference/cli/commands/aspire/, /reference/cli/commands/aspire-run/, /reference/cli/overview/)
• --format <Table|Json> option block and the includes for --help, --log-level, --non-interactive, --nologo, --banner, --wait-for-debugger all render

Recommendations

1. Address W4 first — the missing "Aspire CLI Installations" sample is the most user-visible new feature documented here.
2. Address W2 second — the four optional metadata fields are explicitly mentioned but undefined, which makes the JSON contract harder to consume than it needs to be.
3. W1 and W3 are smaller wording / single-example fixes.
4. K1 and K2 are nice-to-have clarifications.

---

Posted automatically by the hourly docs-from-code review workflow. Phase A reads microsoft/aspire@becb48e2; Phase B runs the doc-tester skill against a local docs build with the PR head overlaid.