[docs] Update aspire wait and aspire describe docs for reusable resource observation

[aspire-repo-bot]

Documents changes from microsoft/aspire#19567

@adamint

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

Why

PR #19567 refactors CLI resource observation into a reusable, typed
ResourceWaitService and reworks ResourceSnapshotWatcher to use a single
coalesced subscription for both initial state and subsequent updates. Two
user-visible behavior changes result:

• aspire wait <resource> --status down now fails (exit code 18) if the
  resource enters FailedToStart, instead of treating that as a successful
  "down" outcome. The wait service applies one monotonic timeout and always
  treats FailedToStart as terminal failure, "even when waiting for a
  resource to be down" (PR description).
• aspire describe --follow now emits the current state of every resource
  immediately when streaming starts (closing the previous snapshot/watch gap),
  even if no later change occurs, in addition to streaming subsequent updates.

Changes

• reference/cli/commands/aspire-wait.mdx:
  • Updated the exit-code table entry for code 18 to say the resource entered
    FailedToStart, regardless of the target status (previously scoped to
    "waiting for up or healthy").
  • Added a sentence to the Description section clarifying that a
    FailedToStart resource always fails the wait, even when the target
    status is down.
• reference/cli/commands/aspire-describe.mdx:
  • Updated the --follow option description to state that the current state
    of every resource is emitted immediately when streaming starts, even if no
    further changes occur.

No new commands, flags, or public docs-relevant types were introduced by this
PR that require new pages — the new KnownResourceStates well-known states
(FailedToStart, etc.) were already documented on
extensibility/custom-resources.mdx prior to this PR (the type itself just
moved files internally).

Generated by PR Documentation Check for #19567 · auto · 94.5 AIC · ⌖ 10.2 AIC · ⊞ 19.6K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1591. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

[David Pine (IEvangelist)]

🤖 Automated docs-accuracy review — PR #1591

Source of truth: microsoft/aspire@main @ 1cdf7d17248ae78ee018abbc314f772ace5e624d — contains source PR microsoft/aspire#19567 (merge 9456f81156, "Make CLI resource observation reusable").

ℹ️ Branch note (non-blocking). This PR targets release/13.6, which does not exist in microsoft/aspire; verified against main. The changed text makes no explicit version claim, so this is only a sourcing note.

Phase A — claims: 3 non-narrative claims → 3 verified · 0 verified-with-nuance · 0 contradicted · 0 unverifiable.
Phase B — doc-tester: exercised /reference/cli/commands/aspire-wait/ and /reference/cli/commands/aspire-describe/ → both HTTP 200, 0 console errors/warnings; edit targets render cleanly; no new components or links. Knowledge gap: local build predates this PR (new sentences not yet rendered), but all edits are inline prose in already-rendering containers.

Verdict: ✅ APPROVE

Both behavior updates match the source exactly — FailedToStart is terminal even for the down target (exit code 18), and describe --follow emits every resource's current state immediately before streaming updates. No inaccuracies, no nuances, no rendering concerns.

---

Phase A — Claim verification

Claim verdicts (3) with evidence, against microsoft/aspire@1cdf7d17

#	Type	Claim	Verdict & evidence
W1	api-behavior	aspire wait fails with exit code 18 if the resource enters FailedToStart, even when target status is down — never treated as a successful "down"	verified — ResourceWaitService.cs comment: "The AppHost's 'down' predicate treats FailedToStart as terminal. It still represents a failed resource and must not become a successful wait result." Outcome switch evaluates _ when IsTerminalFailureState(response.State) => …Failure before { Success: true }; IsTerminalFailureState returns true iff state == KnownResourceStates.FailedToStart. WaitCommand.cs maps Failure → CliExitCodes.WaitResourceFailed.
W2	cli-surface	Exit code 18 = "Resource entered the FailedToStart state, regardless of the target status"	verified — src/Shared/CliExitCodes.cs:26 WaitResourceFailed = 18; terminal-failure state is exactly FailedToStart for any ResourceWaitTarget. (Minor: 18 is also returned for resource-not-found — an edge the table row doesn't enumerate, unchanged from before; negligible.)
D1	api-behavior	aspire describe --follow emits the current state of every resource immediately when streaming starts, then streams subsequent updates	verified — DescribeCommand.ExecuteWatchAsync: initialCapture = resourceWatcher.CaptureAllResources(); → foreach (var snapshot in currentSnapshots) DisplaySnapshot(...) emits every current resource, then await foreach (var batch in WatchResourceSnapshotBatchesAsync(initialCapture.UpdateSequence, …)) streams updates. ResourceSnapshotWatcher seeds state from an initial GET before watching.

---

Phase B — doc-tester report

Routes: /reference/cli/commands/aspire-wait/, /reference/cli/commands/aspire-describe/ · Tester: doc-tester skill (blind-user; no source reading).

Category	Passed	Failed	Warnings
Content accuracy (rendered)	n/a	0	0
Components / rendering	2	0	0
Links	0 new	0	0

Critical issues: none. Warnings: none.

Passed checks

• aspire-wait → 200, 0 console errors/warnings. Exit-codes table renders (#exit-codes); row 18 and the Description paragraph (the two edit targets) render cleanly.
• aspire-describe → 200, 0 console errors/warnings. The -f, --follow option renders; the inserted sentence lands mid-paragraph before "In table mode…"; pre-existing NDJSON link unchanged.
• No new components or links — all three edits are inline prose/code-span/table-cell text.

Knowledge gap — running build predates PR #1591

• The local frontend still shows the pre-PR text on both pages, so the new sentences couldn't be rendered directly. I validated page health on both routes, that the exact edit targets render cleanly, and that no new components/links are introduced. Pure inline-prose edits ⇒ render failure effectively impossible; wording accuracy is established in Phase A against source.

---

_{Automated review · Phase A read microsoft/aspire@main 1cdf7d17 (source of truth = upstream) · Phase B via doc-tester (blind-user, Playwright).}