[docs] Add skills bundle validation error troubleshooting

[aspire-repo-bot]

Documents changes from microsoft/aspire#17547 (@IEvangelist).

Targeting release/13.4 — the latest release branch on microsoft/aspire.dev — because release/13.5 (from the source PR milestone 13.5) does not exist there.

Why this PR is needed

PR microsoft/aspire#17547 localized the embedded Aspire skills bundle metadata validation failure messages in the CLI. These error messages — previously hardcoded in English — are now properly routed through the localization system. To ensure users who encounter these errors have actionable guidance, this PR adds a troubleshooting section covering the specific error messages and their resolution.

What was changed

Added a Skills bundle errors subsection to the ## Troubleshooting section of get-started/aspire-mcp-server.mdx, documenting:

• The error messages users may see when aspire agent init encounters an invalid or corrupt embedded skills bundle
• Resolution steps (update or reinstall the Aspire CLI)

Files modified

• src/frontend/src/content/docs/get-started/aspire-mcp-server.mdx — updated (existing page)

Generated by PR Documentation Check for issue #17547 · ● 15.9M · ◷

[Copilot]

Pull request overview

Adds troubleshooting guidance to the Aspire MCP Server getting-started documentation so users encountering embedded skills bundle validation failures during aspire agent init have next steps.

Changes:

• Added a Skills bundle errors subsection under Troubleshooting
• Documented example validation error messages and suggested remediation steps

---

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

[IEvangelist]

Docs accuracy review

Source of truth: microsoft/aspire@cc4b7eaf (release/13.4, fetched 2026-05-29)
PR head: 9d65934bc56acf41fe1cedc16811c46c713340af

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

Verdict: COMMENT. All three quoted error messages and the troubleshooting advice are accurate. One small framing nuance worth surfacing: these errors only fire on the embedded fallback path, after the GitHub release fetch failed.

Doc-tester (UX) notes

A user searching for any of the quoted error strings will find this section and get the right diagnosis — the embedded bundle is part of the CLI binary, so reinstalling/updating the CLI is the correct first step. The slight imprecision is that the docs frame embedded-bundle validation as something that always happens during aspire agent init, when in fact it's the second of two acquisition paths. In practice this rarely matters for troubleshooting because the user only sees these specific error strings when the embedded path is reached.

Verified claims (with evidence)

#	Claim	Evidence
1	Error: Embedded Aspire skills bundle metadata is invalid: <reason>	src/Aspire.Cli/Agents/AspireSkills/AspireSkillsInstaller.cs:198 — return AcquisitionResult.Failed($"Embedded Aspire skills bundle metadata is invalid: {metadataError}");. The <reason> slot is filled by ValidateEmbeddedMetadata(metadata) (:255-282), which can return strings like "must specify a version", "repository '...' does not match expected", "must specify a GitHub release tag", etc.
2	Error: Embedded Aspire skills metadata must specify a version.	AspireSkillsInstaller.cs:259 — return "Embedded Aspire skills metadata must specify a version."; (inside ValidateEmbeddedMetadata).
3	Error: Embedded Aspire skills archive failed SHA-256 verification.	AspireSkillsInstaller.cs:296-300 — ValidateArchiveSha256 throws InvalidOperationException with the format "Embedded Aspire skills archive failed SHA-256 verification. Expected '{0}', got '{1}'." when the actual hash differs from the metadata-declared hash.
4	"Updating the CLI replaces the embedded bundle."	src/Aspire.Cli/Agents/AspireSkills/EmbeddedAspireSkillsBundleProvider.cs:46,57 and Aspire.Cli.csproj show the bundle is shipped via <EmbeddedResource> (a compiled-in resource). Replacing the CLI binary replaces the embedded resources.

Verified-with-nuance

#	Claim	Nuance
5	"When aspire agent init installs skill files, it validates the embedded skills bundle that ships with the CLI."	The CLI tries two paths in order: (a) InstallFromGitHubAsync (AspireSkillsInstaller.cs:75-86) downloads the latest release from microsoft/aspire-skills and verifies via GitHub artifact attestation; (b) only if that returns Unavailable/Failed does InstallFromEmbeddedAsync (:87-91, body at :183-251) validate the embedded metadata and re-hash the embedded archive. The Embedded ... error strings only ever fire on path (b). In practice that's a network-down or attestation-failed scenario — worth a quick "if these errors keep firing on a healthy network, the GitHub fetch is failing first; run with --debug to confirm" sentence. Non-blocking.