[docs] Add troubleshooting note for localhive.sh CLI copy failure on macOS/Linux

[aspire-repo-bot]

Documents changes from microsoft/aspire#17670 by @sebastienros.

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#17670 fixed a bug in localhive.sh where the CLI installation script failed on macOS/Linux when the dotnet publish output contained culture-specific subdirectories (e.g., fr/, de/). The error message Failed to copy CLI files from $CLI_PUBLISH_DIR to $CLI_BIN_DIR is user-visible for anyone building Aspire from source.

The fix changed cp -f "$CLI_PUBLISH_DIR"/* to cp -Rf "$CLI_PUBLISH_DIR"/. which correctly copies both files and subdirectories across BSD/macOS and GNU/Linux.

What documentation was changed

Added a new section "Building from source" to the existing troubleshooting.mdx page with a subsection describing the Failed to copy CLI files error, its cause (culture-specific resource subdirectories in publish output), and the solution (update to the latest localhive.sh).

Files modified

• src/frontend/src/content/docs/get-started/troubleshooting.mdx — updated (new section added)

Note: The docs_required recommendation was triggered by the pr_body_has_cli_flag_mention signal, which fired on dotnet test MTP filter flags (--filter-class, --filter-not-trait) present in the PR's validation section — not on Aspire CLI user-facing flags. This is a likely false positive. A reviewer may choose to close this PR if they determine no documentation update is needed.

Generated by PR Documentation Check for issue #17670 · ● 17.1M · ◷

[Copilot]

Pull request overview

Adds a troubleshooting entry for developers building Aspire from source who encounter localhive.sh copy failures on macOS/Linux.

Changes:

• Adds a new “Building from source” section to the troubleshooting guide.
• Documents the error symptoms, cause, and recommended fix for culture-specific publish output directories.

---

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

[IEvangelist]

Automated docs-accuracy review

Phase A verified against microsoft/aspire release/13.4 @ e258349fd49dd0fdf08f92468d79f0cfaaf13012.
Phase B exercised live aspire.dev/get-started/troubleshooting/ (no PR preview available; assessed PR-branch MDX content alongside live page structure).

Phase A — claim verdicts (8 total)

verdict	count
verified	5
verified-with-nuance	3
contradicted	0
unverifiable	0

The recipe is correct and the script's broken behavior on release/13.4 matches the documented cause exactly. The only concern is that the "update to the latest version" remediation needs a branch qualifier — see the inline comment on line 220.

Per-claim catalog — click to expand

id	claim	verdict	evidence
c1	localhive.sh emits exactly Failed to copy CLI files from <publish_dir> to <bin_dir>	✅ verified	localhive.sh:458 (release/13.4 @ e258349fd) emits error "Failed to copy CLI files from $CLI_PUBLISH_DIR to $CLI_BIN_DIR" — exact match.
c2	macOS/BSD error appears as cp: .../fr is a directory (not copied)	⚠️ verified-with-nuance	localhive.sh:457 invokes cp -f "$CLI_PUBLISH_DIR"/* "$CLI_BIN_DIR"/ with no -R; the fr/ subdir does exist in publish output (XLF translations confirm fr is a supported culture). Wording matches BSD cp's documented behavior; not run on a Mac.
c3	Linux/GNU error appears as cp: -r not specified; omitting directory '...'	⚠️ verified-with-nuance	Same script-level evidence; wording matches GNU coreutils cp documented behavior; not run on Linux.
c4	The CLI publish output contains culture-specific subdirectories (e.g., fr/, de/)	✅ verified	src/Aspire.Cli/Aspire.Cli.csproj uses XLF for *Strings.resx. src/Aspire.Cli/Resources/xlf/ contains 533 XLF files across 13 cultures: cs, de, es, fr, it, ja, ko, pl, pt-BR, ru, tr, zh-Hans, zh-Hant. dotnet publish emits one satellite assembly per culture into a subdirectory named after the culture.
c5	Plain cp without -R cannot copy directories	✅ verified	Standard cp behavior; localhive.sh:457 confirmed to lack any recursive flag.
c6	The script was updated to use cp -Rf "$CLI_PUBLISH_DIR"/. "$CLI_BIN_DIR"/	✅ verified	Fix commit 2cd49bdc2 ("Fix localhive CLI publish copy (#17670)") on main rewrites localhive.sh:457 to exactly that invocation — string-for-string match.
c7	"Update to the latest version of localhive.sh from microsoft/aspire"	⚠️ verified-with-nuance	The fix commit 2cd49bdc2 is on main only. release/13.4 (the target of this PR) still has the BROKEN cp -f at HEAD e258349fd. See inline comment on line 220.
c8	localhive.sh installs a locally built Aspire CLI	✅ verified	localhive.sh:3 header comment; lines 386-488 implement the install-to-$ASPIRE_ROOT/bin flow.

---

Phase B — doc-tester report

Scope: the single PR-affected page, /get-started/troubleshooting/.

Page structure check: existing sections use H2 = problem name, with bold **Symptoms**: / **Solution**: paragraphs. The new section introduces a category H2 (Building from source) with an H3 problem under it, plus a new **Cause**: field. That's a different convention from the rest of the page, but I'll defer styling questions per scope.

Critical issues

None.

Warnings

1. The "Solution" wording can mislead a release/13.4 reader (line 220). It says "update to the latest version of localhive.sh from the microsoft/aspire repository" without naming a branch. A user reading the release/13.4 docs, then cloning microsoft/aspire and checking out release/13.4, gets the broken script. The fix only landed on main (commit 2cd49bdc2, PR #17670). This overlaps with Phase A c7 and is the only substantive issue worth fixing before merge.

Knowledge gaps a new user will hit

1. What is localhive.sh? This page is a get-started troubleshooting guide, and the only reader who hits this issue is someone building Aspire from source — a developer workflow. The audience reading "Build your first app" troubleshooting will likely not know what localhive.sh is or whether the section applies to them. A one-line definition would help (e.g., "localhive.sh is the developer script in the microsoft/aspire repo that installs a locally-built Aspire CLI to $HOME/.aspire/bin.").
2. What are <publish_dir> and <bin_dir>? The error template uses these placeholders; readers without script familiarity can't map them to real paths. Mentioning that <publish_dir> is the dotnet publish output and <bin_dir> is $HOME/.aspire/bin would close the loop.
3. No fallback for users stuck on a release branch. If a user is locked to a specific release/* branch for some reason, the doc gives them no manual remediation other than "update to the latest." A two-line "or patch manually with: sed -i 's|cp -f "$CLI_PUBLISH_DIR"/\\*|cp -Rf "$CLI_PUBLISH_DIR"/.|' localhive.sh" (or even just "edit line 457 of localhive.sh to ...") would be self-contained.
4. No reference to the fix. Linking the actual PR (microsoft/aspire#17670) gives readers a clear pointer to "this is real, here's the change."

Passed checks

• New section uses correct MDX format; code blocks render cleanly.
• Symptoms / Cause / Solution structure is clear and self-explanatory.
• The cp recipe (cp -Rf "$CLI_PUBLISH_DIR"/. "$CLI_BIN_DIR"/) is verbatim correct.
• No broken links from the new content; the only external link (microsoft/aspire) resolves.

Recommendations

• Add a branch qualifier to the "Solution" so users on release/13.4 know they need the fix from main (or cherry-pick PR #17670).
• One-line description of localhive.sh so the audience can self-identify whether this section applies.
• Optional: cite the fix PR (microsoft/aspire#17670) so the source is traceable.

---

Verdict

COMMENT — no Phase A contradictions; no Phase B critical issues. The "update to the latest version" remediation is verified-with-nuance (line 220) because the fix is main-only; the in-line recipe is correct so the doc is still useful, but a branch qualifier would close the gap.

_{Generated by the hourly docs-from-code PR review workflow. Phase A SHA: e258349fd. Reviewer SHA: ce3f8b90ef.}

[IEvangelist]

Verified-with-nuance (Phase A — c7) + Phase B warning — verified against microsoft/aspire release/13.4 @ e258349fd.

The fix commit 2cd49bdc2 (Fix localhive CLI publish copy (#17670)) is on main only. On release/13.4 (the branch this PR targets, so the docs build that ships this page), localhive.sh:457 still has the broken invocation:

if ! cp -f "$CLI_PUBLISH_DIR"/* "$CLI_BIN_DIR"/; then

A reader of these troubleshooting docs who runs git clone microsoft/aspire && git checkout release/13.4 will not get the fix. Two minimal options:

1. Specify the branch: "Update to the latest localhive.sh from the main branch of microsoft/aspire (cherry-pick Fix localhive CLI publish copy aspire#17670 if you are pinned to a release branch)."
2. Or just inline the one-line patch (you already give the exact replacement line right after) so the recipe is self-contained for readers on any branch.

Phase B knowledge gaps worth addressing in the same edit:

• Define localhive.sh in one line — this page lives under Get Started and a general reader has no way to tell whether this section applies to them (it only applies to developers building Aspire from source).
• Define <publish_dir> and <bin_dir> so readers can match the error to real paths (dotnet publish output and C:\Users\dapine/.aspire/bin).