[docs] Document aspire start readiness diagnostics and failure output

[aspire-repo-bot]

Documents changes from microsoft/aspire#17141 by @danegsta.

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

Why this PR is needed

aspire start previously detached from the background AppHost process before it reached a stable running state. Early startup failures (TypeScript syntax errors, C# compile errors) were silently lost in the background process. microsoft/aspire#17141 changed aspire start to wait for the AppHost to report readiness and to display a curated failure excerpt when startup fails — but the existing aspire start docs described none of this new behavior.

What was changed

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

• Updated the Description section to state that aspire start waits for the AppHost to reach a stable running state before detaching.
• Added a new Startup readiness and failure diagnostics subsection explaining:
  • Early startup failures (TypeScript syntax errors, C# compile errors) are surfaced in the terminal rather than being silently lost.
  • The curated startup excerpt shown on failure filters out install/audit noise and highlights compiler diagnostics — with both a TypeScript and a .NET example taken from the source PR's ### User-facing output section.
  • The parent log captures replayed child output under DetachedAppHost/... log categories.
  • Pressing Ctrl+C while waiting for readiness terminates startup.

Files modified

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

Generated by PR Documentation Check for issue #17141 · ● 74M · ◷

[Copilot]

Pull request overview

Updates the aspire start CLI reference documentation to reflect the newer behavior where the command waits for the AppHost to reach a stable running/ready state before detaching, and surfaces early startup failures with a curated excerpt.

Changes:

• Clarifies that aspire start detaches only after the AppHost reaches a stable running state.
• Adds a new section describing readiness waiting, Ctrl+C behavior, and the curated failure excerpt (TypeScript + .NET examples).
• Notes where replayed child output appears in logs (DetachedAppHost/... categories).

---

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

[adamint]

@copilot implement this fix. standardize to AppHost

[Copilot]

Standardized to "AppHost" (PascalCase) in frontmatter description, Name section, and Options section in commit 14c9152.

[adamint]

@copilot implement this fix

[Copilot]

Switched both CLI output code blocks from text to bash to match the pattern used in other CLI docs like aspire-doctor in commit 14c9152.

[adamint]

@copilot implement this fix

[Copilot]

Done — replaced both ... placeholders with <log-path> in the TypeScript and .NET sample output blocks in commit 79553e4.

[IEvangelist]

Review generated by running the doc-tester skill against PR #1002 with the docs site served locally via aspire run.

Summary

Small, focused docs change that adds a Startup readiness and failure diagnostics subsection to aspire start.mdx to cover the behavior introduced by microsoft/aspire#17141. The change is internally consistent, renders cleanly on the local docs site, and all internal links resolve. The TypeScript and .NET failure-output blocks are faithful copies of what microsoft/aspire#17141 quotes as user-facing output. No blocking issues found — posting as advisory COMMENT with a few minor suggestions.

Check	Result
Page renders (HTTP 200 on local frontend)	✅
New section appears in the right-side TOC at #startup-readiness-and-failure-diagnostics	✅
Emojis (❌, ℹ️, 📄) round-trip cleanly in the rendered output	✅
text title="Aspire CLI" code blocks render	✅
Internal links — ../aspire-run/, ../aspire-ps/, ../aspire-logs/, ../aspire-stop/, /app-host/hot-reload-and-watch/	✅ all 200
Trailing-slash / site-relative link conventions	✅
Markdown / MDX syntax (no broken includes, no stray components)	✅

Findings

1. “stable running state” is undefined (minor / clarity)

The new description says aspire start "exits after the AppHost reaches a stable running state" and the readiness section repeats the phrase, but the page never defines what "stable running state" means (all resources Running? Healthy? AppHost host process readiness signal?). A new reader landing on this page won't know whether this is the same as the dashboard's Healthy state on resources or something AppHost-process-level.

Suggested wording (no rewrite required — just defining the term once):

aspire start waits for the AppHost to signal that it has finished starting its resources before detaching. This means that early startup failures — such as TypeScript syntax errors in a polyglot AppHost or C# compile errors in a .NET AppHost — are surfaced in the parent terminal instead of being silently lost in the background.

…or add a short parenthetical the first time the phrase is used, e.g. "a stable running state (the AppHost has reported that it is up and resources are no longer starting)".

2. Mixed casing of apphost vs AppHost on the same page (minor / consistency, pre-existing but widened)

The new content correctly uses AppHost (PascalCase) everywhere. The pre-existing frontmatter and Name section still use lowercase apphost:

• Line 3 (frontmatter): description: Learn about the aspire start command and its usage. This command starts an apphost in the background.
• Line 10 (Name): aspire start - Start an apphost in the background.

The PR is the natural place to fix these two strings to AppHost so the page reads consistently after the update. Otherwise the same page now uses both spellings in close proximity.

3. DetachedAppHost/... log categories — no pointer to where those logs live (minor / clarity)

The new section says:

The parent log also captures the replayed child output under DetachedAppHost/... log categories so the log file is self-contained.

The example output already shows 📄 See logs at ..., but a reader doesn't know whether "the parent log" means the same file, the CLI log under ~/.aspire/logs/, or something they need to fetch with aspire logs. Suggest a short cross-link to either aspire logs or a one-line note that the See logs at path is the file containing the replayed DetachedAppHost/... entries.

4. Ctrl+C note could clarify when it applies vs. aspire stop (nit)

Pressing Ctrl+C while aspire start is waiting for the AppHost to start will terminate the startup process.

Reading this in isolation, a user could think Ctrl+C also stops an already-detached AppHost. A short follow-up sentence pointing at aspire stop for the "already detached" case would make the boundary obvious, e.g.:

Pressing Ctrl+C while aspire start is waiting for the AppHost to start will terminate the startup process. To stop an AppHost that has already detached, use aspire stop.

5. Description sentence flow (nit)

"…displays a curated excerpt of the startup output that filters out noise such as package install logs, and highlights the relevant error messages:"

The comma before "and highlights" joining a verb phrase to the same subject reads slightly awkwardly. Optional rewrite:

…displays a curated excerpt of the startup output that filters out noise (such as package install logs) and highlights the relevant error messages:

Suggested wording

Concrete drop-in for the readiness section (incorporating items 1, 3, 4, 5; item 2 is the unrelated casing fix):

### Startup readiness and failure diagnostics

`aspire start` waits for the AppHost to signal that it has finished starting its resources (a _stable running state_) before detaching. This means that early startup failures — such as TypeScript syntax errors in a polyglot AppHost or C# compile errors in a .NET AppHost — are surfaced in the parent terminal instead of being silently lost in the background.

When the AppHost fails to start, `aspire start` displays a curated excerpt of the startup output that filters out noise (such as package install logs) and highlights the relevant error messages:

…(unchanged TypeScript example)…

For a .NET AppHost with a compile error, the output includes the relevant build diagnostics:

…(unchanged .NET example)…

The replayed child output is also written to the parent log under `DetachedAppHost/...` log categories, so the file referenced by `See logs at` is self-contained — you can also retrieve it later with [`aspire logs`](../aspire-logs/).

Pressing **Ctrl+C** while `aspire start` is waiting for the AppHost to start will terminate the startup process. To stop an AppHost that has already detached, use [`aspire stop`](../aspire-stop/).

Knowledge gaps (per doc-tester methodology)

Knowledge Gap: Verifying the actual aspire start behavior end-to-end

What I needed to know: Whether the documented "wait for AppHost readiness, surface curated failure excerpt" behavior actually fires on this branch.

Source of my knowledge: Not verifiable from the docs page alone — readiness depends on a server-side hook in the AppHost.

What I observed locally: The doc site runs against this PR using aspire run against the repo's own Aspire.Dev.AppHost. The CLI used (13.4.0-preview.1) attempted NotifyAppHostReadyAsync and got back RemoteMethodNotFoundException: No method by the name 'NotifyAppHostReadyAsync' is found because the bundled AppHost is on SDK 13.3.0. That error path is exactly the back-compat fallback the readiness feature has to ship with, but it means I could not reproduce the success path of the new readiness wait, nor the curated failure excerpt path, on this branch. The doc's claims are internally consistent with the source PR microsoft/aspire#17141 description, but to fully validate the example output you'd want to run aspire start against an AppHost that has the matching server-side support and intentionally introduce a TS/C# syntax error.

User impact: None for the docs PR itself — but worth flagging that the example outputs in the doc are claims, not currently reproducible against the standard 13.3.0 SDK.

Recommendation:

• (Optional, post-merge) Once 13.4 SDK is the default, re-verify the two example outputs match byte-for-byte what the CLI emits and update if drift has occurred.
• Reasonable to ship as-is, since the strings are taken directly from microsoft/aspire#17141's User-facing output section.

Knowledge Gap: What counts as the "parent log"?

What I needed to know: Where to find the file referenced by 📄 See logs at ... and confirm that DetachedAppHost/... categories show up there.

Source of my knowledge: Inferred from the running CLI's own log path (~/.aspire/logs/cli_*.log) — not stated by the doc.

Recommendation: see finding #3 above.

Verdict

COMMENT — ship after addressing the wording nits if you want; nothing here blocks merge. The content faithfully documents the new behavior, examples are taken straight from the source PR, the page renders correctly and all internal links resolve.