Skip to content

[docs] Document trust confirmation for aspire template source add - #1983

Closed
aspire-repo-bot[bot] wants to merge 5 commits into
release/17.0from
docs/pr-21418-40992075783-1-2a379538475e08e0
Closed

aspire-repo-bot[bot] wants to merge 5 commits into
release/17.0from
docs/pr-21418-40992075783-1-2a379538475e08e0

Conversation

@aspire-repo-bot

@aspire-repo-bot aspire-repo-bot Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Documents aspire template source add, including the trust confirmation added in microsoft/aspire#21418 (source command from microsoft/aspire#21329). Author of the source change: @mitchdenny.

Changes in this PR:

  • New page src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx: description, trust warning and [y/N] prompt, cancel behavior, --yes/-y, non-interactive behavior, the name argument rules, both --path modes, --repository, --ref, and four examples.
  • Sidebar entry under Reference › CLI reference › Commands in src/frontend/config/sidebar/reference.topics.ts.
  • src/frontend/tests/unit/cli-command-sidebar.vitest.test.ts, which checks that every CLI command page has a sidebar entry.

This round (e061986) fixes three places where the page had drifted from aspire main:

  • Name rules: names must be 1-64 ASCII letters, digits, dots, hyphens, or underscores, starting with a letter or digit (SourceNameValidator). The page previously said dots weren't allowed.
  • Repository --path: it can't be absolute or use .. to point outside the repository.
  • Warning timing: the trust warning is written to standard error after the name and location are validated, then the prompt is shown.

Base branch: this targets release/17.0 because the source PRs are milestone 17.0. aspire's release/17.0 branch still has MajorVersion 14 and doesn't contain the command; aspire main is 17.0.0-preview.1 and does. All claims were checked against aspire main @be803a14.

Third-party links and affiliations

None. The examples use https://example.com/templates as a placeholder.

Validation

  • pnpm lint (astro sync, skill digest check, ESLint --max-warnings 0): pass.
  • pnpm test:unit: 96 files, 1386 passed, 1 skipped.
  • Prettier --check on the three changed files: pass.
  • pnpm build:production: the English page built and contains the new text; the full run then hit ENOSPC on the local runner while writing localized pages, so the complete build result comes from CI.
  • CI on e061986 (run): Frontend validation, Frontend Build, all six Playwright E2E shards (desktop, tablet and mobile Chromium), Frontend gate, forbidden words, release-sync-tests and ci-gate passed; apphost-build was skipped by path filtering.

Confidence

Behavior and regression coverage. Every statement on the page maps to source on aspire main @be803a14: TemplateManagementCommand.cs (command tree, --yes/-y, validate → warn → prompt → cancel or write), TemplateSourceConfiguration.Parse (absolute local path vs. repository-relative path, --ref requires --repository, default .), SourceNameValidator.IsValid (name rules), TemplateSourceStore.AddAsync (global file, case-insensitive duplicate check), BaseCommand.AddNonInteractiveRequiresYesValidator and ConsoleInteractionService.PromptConfirmAsync ([y/N], non-interactive failure). Gap: I didn't run the CLI; the checks are source-only, and there is no automated test that the docs match CLI help text.

Tests and pipelines. Local lint, unit tests and Prettier passed (above). The sidebar unit test from the earlier round covers the page's sidebar entry. CI on e061986 passed Frontend validation, Frontend Build, the six-shard Playwright E2E suite and ci-gate. Gap: the E2E suite has no test specific to this page; the visual check below is a targeted script.

Build artifacts. The local production build emitted dist/reference/cli/commands/aspire-template-source-add/index.html containing the updated name rule and --path text. CI's Frontend Build on e061986 completed the full production build. Gap: the full local build didn't finish because the local runner ran out of disk.

E2E and visual experience. Screenshots from the local dev server (astro dev) cover the Description through Options sections, for both themes at desktop (1440 px) and mobile (390 px) widths. "Before" is the previous head 6fee391; "after" is e061986. Gap: Chromium only.

Source Theme Viewport Screenshot
before (6fee391) light desktop 1440 Before, light, desktop
after (e061986) light desktop 1440 After, light, desktop
before (6fee391) dark desktop 1440 Before, dark, desktop
after (e061986) dark desktop 1440 After, dark, desktop
before (6fee391) light mobile 390 Before, light, mobile
after (e061986) light mobile 390 After, light, mobile
before (6fee391) dark mobile 390 Before, dark, mobile
after (e061986) dark mobile 390 After, dark, mobile

Generated by PR Documentation Check for #21418

🤖 Posted by AspireAgent (AI Agent)

@aspire-repo-bot aspire-repo-bot Bot added the docs-from-code Copilot initiated issue from dotnet/aspire repo label Oct 30, 2026
@aspire-repo-bot

Copy link
Copy Markdown
Contributor Author

Frontend HTML artifact ready

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

VS Code: Open PR #1983 artifacts

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

Copy link
Copy Markdown
Contributor

The production build fails at ae3f5ca4f32303a5cf14dca5bfdf05dd34f1a0a9 when rendering /reference/cli/commands/aspire-template-source-add/: AstroUserError: Failed to find the topic for the reference/cli/commands/aspire-template-source-add page.

The new page has neither a sidebar entry nor a topic association, which the sidebar-topics integration requires. Please associate it with the intended CLI topic through its sidebar configuration or an explicit unlisted-page topic, then validate the route and production build. Browser tests were skipped after this build failure.

🤖 Posted by AspireAgent (AI Agent)

The new command page had no sidebar entry, so the sidebar-topics plugin
could not resolve its topic and the production build failed. Add the
entry and a unit test that every CLI command page is listed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The --path documentation omits the absolute-path requirement for local sources and its repository-relative meaning and default when used with --repository.

1 open issue
What changed in this PR

Adds CLI reference documentation for aspire template source add, covering the trust confirmation introduced in microsoft/aspire#21418.

Changes:

  • Documents the trust prompt, cancellation behavior, and --yes requirement for non-interactive use.
  • Registers the page in the Reference sidebar so it resolves to the correct topic.
  • Adds regression tests for CLI command sidebar coverage.
File Description
src/​frontend/​tests/​unit/​cli-command-sidebar.vitest.test.ts Checks that CLI command pages have sidebar entries.
src/​frontend/​src/​content/​docs/​reference/​cli/​commands/​aspire-template-source-add.mdx Adds command usage, trust behavior, options, and examples.
src/​frontend/​config/​sidebar/​reference.topics.ts Adds the command to the Reference sidebar.

Review effort: Balanced

Without --repository, --path must be an absolute local directory. With
--repository, it is a repository-relative directory that defaults to the
root. Also align --repository and --ref descriptions with the CLI help
text and add subdirectory/ref and local-directory examples.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@IEvangelist

Copy link
Copy Markdown
Member

Docs accuracy review [partial - phase A: 27 of 27 claims evaluated; phase B: browser completed, matching-runtime execution unavailable]

Reviewed 0ef4eefe8053f100d5d10e09447bde36debad7a0, targeting release/17.0. Source: microsoft/aspire, matching branch release/17.0, pinned SHA 55867ce9d33c8800e6c7278f7edc5e88e0f6b839. Phase A: 27 claims; 6 verified, 0 verified-with-nuance, 20 unverifiable, 1 contradicted. Command-specific claims remain unverified on this release; main was not substituted as release evidence. Phase B exercised the new command route and its scoped navigation: 0 demonstrated critical issues, 4 warnings, with command execution explicitly partial.

Phase A - claim verification

Release/source mismatch needs resolution before these instructions can be certified for the target release. The new page presents aspire template source add <name> [options] as available (lines 10-20), but the matching source branch's root command registrations contain no template root command. Its complete, non-truncated Git tree has no template-source command/configuration implementation. The existing TemplateCommand is a dynamic command for aspire new, not the documented root command.

This branch also declares 14.0.0-preview.1, despite its release/17.0 name. Upstream #21418 merged into main, not this matching branch; comparing its merge commit 69998022e041be41c14c98a6912f67f203dd65d9 against the pinned release SHA reports it 325 commits ahead, with the release SHA as merge base. That linked PR is context, not proof of release availability.

Please establish the intended product release/source pin or update/backport the matching branch before treating the command, trust prompt, cancellation and automation behavior as verified release guidance. This is a contradiction against the inspected source branch, not a claim that the command can never be included in the eventual 17.0 release.

The command-specific claims below share that evidence gap; they are consolidated here rather than posting twenty repetitive findings. In particular, trust defaults, refusal without writes, --yes, and redirected/non-interactive input require a matching implementation/runtime, not an inference from the docs-generating PR.

Full frozen Phase A catalog (27 claims)

All locations are in src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx. "Absent" refers to the root registrations and complete tree at the source SHA above. Generic options are verified as CLI-wide surfaces, not proof that the absent command inherits them.

ID Lines Exact claim/snippet Verdict Evidence
A01 10-20 aspire template source add <name> [options] Contradicted RootCommand.cs:219-266 has no template root registration.
A02 20 "adds a named template source to global Aspire configuration" Unverifiable Template-source persistence implementation absent.
A03 20 "either a Git repository ... or an absolute local directory" Unverifiable Source parser absent.
A04 22 "asks you to trust the source before it changes any configuration" Unverifiable Trust implementation absent.
A05 22 "prompt shows the source name and its repository URL or local path" Unverifiable Prompt implementation/resources absent.
A06 22 "defaults to No" Unverifiable Trust prompt default absent.
A07 25 Templates can run code. Do you trust template source 'company' (https://example.com/templates)? [y/N]: Unverifiable Exact command prompt/resources absent.
A08 28 "If you decline, the command is canceled and configuration isn't changed." Unverifiable Cancellation/write ordering implementation absent.
A09 28 "skip the prompt, pass --yes" Unverifiable Command option/action absent.
A10 30 "Non-interactive invocations, including invocations where interactive input isn't available, fail unless you pass --yes." Unverifiable Command's non-interactive/input detection absent.
A11 36-38 name - "The name of the template source." Unverifiable Argument declaration absent.
A12 48 "--path must be an absolute local directory that contains templates" Unverifiable Source parser absent.
A13 49 "--path is a directory relative to the repository root ... defaults ... (.)" Unverifiable Source parser/default absent.
A14 51-53 --repository - "An HTTPS or SSH Git repository URL" Unverifiable Repository URL validation absent.
A15 55-57 --ref - "A Git branch, tag, or full commit SHA." Unverifiable Ref parsing absent.
A16 57 "Requires --repository and defaults to HEAD." Unverifiable Ref validation/default absent.
A17 59-61 -y, --yes - "Trust the template source and skip confirmation." Unverifiable Alias/option/action absent.
A18 63 included -?, -h, --help Verified CommonOptionNames.cs:14-16; RootCommand.cs:268-275 handles HelpOption.
A19 65 included -l, --log-level and log levels Verified RootCommand.cs:30-34, LogLevel enum and RootCommandStrings.resx DebugLevelArgumentDescription.
A20 67 included --non-interactive, disabling prompts/spinners Verified RootCommand.cs:36-40; RootCommandStrings.resx NonInteractiveArgumentDescription.
A21 69 included --nologo, suppressing startup banner/telemetry notice Verified RootCommand.cs:42-46; RootCommandStrings.resx NoLogoArgumentDescription.
A22 71 included --banner, animated welcome banner Verified RootCommand.cs:48-52; RootCommandStrings.resx BannerArgumentDescription.
A23 73 included --wait-for-debugger Verified RootCommand.cs:54-59; RootCommandStrings.resx WaitForDebuggerArgumentDescription.
A24 77-81 aspire template source add company --repository https://example.com/templates Unverifiable Command absent.
A25 83-87 repository example with --path templates/web --ref v1.0.0 Unverifiable Command/parser absent.
A26 89-93 aspire template source add local --path /home/user/templates Unverifiable Command/parser absent.
A27 95-99 automation example with --non-interactive --yes Unverifiable Command/trust implementation absent.

No hard-coded current Aspire version was introduced. The prior --path wording finding discussion_r4434755405 is addressed textually at this head: both modes, repository-root default, and ref prerequisite/default are now documented. It is not reopened or duplicated; release-specific behavior remains uncertified for the separate reason above.

Phase B - independent blind doc-tester report

Documentation Test Report

Focus: Independent, blind Phase B testing of microsoft/aspire.dev PR #1983
Head: 0ef4eefe8053f100d5d10e09447bde36debad7a0
Date: 2026-11-01
Tester: doc-tester agent
Result: Rendered documentation/navigation validated; runtime validation partial.

Scope and environment

Loaded both required skills and read their actual SKILL.md files. Reviewed only the changed documentation and browser-rendered experience. Did not inspect Aspire implementation, upstream APIs, or test implementations.

Local page:
http://127.0.0.1:4383/reference/cli/commands/aspire-template-source-add/

The parent-provided lightweight Astro server returned HTTP 200 before browser testing began. All browser navigation and interactions used playwright-cli, exclusively in named session pr1983-blind.

Installed CLI:
13.4.0+3f0998a95833d5fef96b3159d56b667889b71166

This CLI was not known to match the documented release.

Summary

Category Passed Failed Warnings Not executed
Content accuracy/readability¹ 5 0 2 —
Code/command examples 0 0 0 4 examples
CLI commands 1² 0 1 Feature behavior
Links/navigation 12 0 0 Shared footer/external links
Local environment 0 0 1 Production validation

¹ Presentation and internal consistency only; not confirmation of implementation behavior.
² Shared-option availability in installed CLI help only—not template-source command support.

Critical issues

None demonstrated within this scope.

No successful registration, trust-prompt behavior, cancellation behavior, or configuration persistence is claimed.

Warnings

1. Repository examples require unexplained substitution

Location: Examples

aspire template source add company --repository https://example.com/templates --path templates/web --ref v1.0.0

The page does not explicitly identify the repository URL, repository directory, and tag as illustrative values to replace with an actual template source.

User impact: A literal-following beginner could treat these as a working sample.

Recommendation: Add a short instruction to substitute an existing repository, template directory, and valid reference. This is a teaching enhancement, not a demonstrated runtime defect.

2. Local-directory example is Unix-oriented

Location: Examples

aspire template source add local --path /home/user/templates

The page requires an absolute local directory but provides only a Unix-style example. The rendered experience retained that example with Windows shown in the site’s OS preferences.

User impact: Windows beginners must supply their own platform-specific equivalent.

Recommendation: Provide a Windows example or explicitly state that readers must substitute an existing absolute directory appropriate to their OS.

3. Matching runtime unavailable

The installed CLI’s help does not expose the documented template-source command hierarchy:

Exact command executed Observed result
aspire --version Reported the exact version above
aspire --help Root help; exit 0; no template command listed
aspire template --help Root help; exit 0
aspire template source --help Root help; exit 0
aspire template source add --help Hosting-integration help: aspire add [<integration>] [options]; exit 0

These results do not validate aspire template source add. They are an environment/version limitation, not evidence of a release defect.

4. Lightweight development environment produced console errors

Observed browser messages included:

  • 504 (Outdated Optimize Dep) for Astro development-toolbar resources.
  • 404 (Not Found) for /api/live/.
  • [live-status] Live API not found (404); live updates disabled until reload.

Documentation content and tested navigation remained available. These observations are recorded as local-environment limitations, not attributed to the PR.

Passed checks

Content/readability — five checks

  1. All six sections rendered: Name, Synopsis, Description, Arguments, Options, Examples.
  2. All six shared-option includes expanded into readable content:
    • -?, -h, --help
    • -l, --log-level
    • --non-interactive
    • --nologo
    • --banner
    • --wait-for-debugger
  3. The text consistently distinguishes absolute local paths from repository-relative paths and explains --ref’s repository requirement and HEAD default.
  4. Trust instructions visibly explain code execution risk, default No, cancellation without configuration changes, and explicit --yes for non-interactive invocation.
  5. Synopsis, prompt text, and all four examples were readable. Desktop and 390×844 mobile checks found no page-level horizontal overflow. The changed MDX contained no hard-coded current Aspire release requiring placeholder replacement; v1.0.0 is presented as an example Git tag.

CLI — one limited check

Installed CLI help lists the six shared global options rendered on the page. Command-specific applicability remains unverified.

Links/navigation — twelve checks

All routes below use local base http://127.0.0.1:4383:

  1. Canonical page /reference/cli/commands/aspire-template-source-add/ loaded.
  2. “Previous aspire stop” opened /reference/cli/commands/aspire-stop/.
  3. Sidebar “aspire template source add” returned to the canonical page and became active.
  4. “CLI reference” breadcrumb opened /reference/cli/overview/.
  5. “Reference” breadcrumb opened /reference/overview/.
    6–11. Section links successfully navigated to #name, #synopsis, #description, #arguments, #options, and #examples; each target existed exactly once.
  6. Scoped documentation/navigation page links were site-relative with trailing slashes; same-page anchors matched actual headings.

Additional route observation:
/reference/cli/commands/aspire-template-source-add without the trailing slash returned 404: Not Found. The documentation/sidebar use the working trailing-slash route; this is not counted as a broken documented link.

Knowledge gaps

Needed: Recognizing illustrative repository/tag values and translating the Unix path example into a Windows absolute path.

Knowledge source: Prior/general knowledge—not an explanation provided by this page.

Impact: Beginners copying examples literally may need additional guidance.

Suggested handoff: Add substitution guidance and a Windows local-directory example, then verify the revised rendered examples.

Recommendations and runtime limits

  1. No demonstrated critical documentation fix is required from this blind pass.
  2. Consider the two small example-guidance improvements above.
  3. Repeat command-specific testing with a confirmed matching CLI in an authorized isolated environment.
  4. Verify interactive acceptance/decline, unattended rejection without --yes, explicit trust, path/reference handling, and configuration persistence during that follow-up.

Not performed: Registration commands, global configuration changes, installation, project creation, compilation, production build, external-source inspection, or comments/posts.

Initial stale-reference/locator attempts were recovered; unsuccessful automation attempts were not counted as passed checks.

Cleanup: Closed only pr1983-blind and deleted its browser scratch directory. No repository edits were made. Parent retains server-cleanup ownership. Report frozen; testing stopped.

Limits and review policy

This is a partial runtime-validation report, not a completed end-to-end command test. No template source was registered, no global settings were changed, and no production build was run. No fixes, pushes, formal approval/change request, or merge were performed. This conversation report consumes the lifetime docs-review stage for this PR; it is not automatically rerun on a new SHA.

@IEvangelist

Copy link
Copy Markdown
Member

Code review - no new substantive findings

Reviewed 0ef4eef against release/17.0, base db346f9, after the docs report. Applied the actual repository .agents/skills/code-review/SKILL.md instructions directly; the skill loader does not expose that local skill by name.

The four-line sidebar registration correctly puts reference/cli/commands/aspire-template-source-add in the existing Reference CLI Commands group. The sidebar aggregator consumes this referenceTopics object, and the installed topic middleware derives the page's topic from that registration. The added tests walk explicit nested sidebar items, include string entries, and check every current .md/.mdx command page plus this specific slug. The change is correct and adequately unit-covered for this static registration; no high-confidence code defect or important new interactive scenario was found.

The earlier missing-topic/build failure is fixed at this head, not a new finding: the actual PR page returned HTTP 200, the independent browser pass followed the sidebar link and Reference/CLI breadcrumbs, and CI run 41289092530 completed successfully at this exact head SHA, including Frontend Build and Frontend validation. No local production build was run.

Test coverage

  • Unit: npm exec --yes --package=pnpm@11.9.0 -- pnpm exec vitest run --config vitest.config.ts tests\unit\cli-command-sidebar.vitest.test.ts, from src/frontend: passed, 2 tests in 1 file.
  • Browser/navigation: independent docs pass exercised the new route, previous-page navigation, sidebar activation, breadcrumbs and all six heading anchors, with desktop/mobile overflow checks. This is a manual skill-driven check, not a committed regression spec.
  • E2E: existing shared sidebar tests and the CI desktop/tablet/mobile jobs passed; no new automated scenario specifically navigates to this command page. There is no changed widget, interaction implementation or responsive layout requiring a separate new test here.
  • Accessibility: existing shared sidebar axe coverage remains; the new command page is not in wcag-aa.spec.ts's audited-pages list, and no page-specific axe audit was run. This PR adds a static entry to the existing navigation and no new code markup/focus behavior, so this is recorded as a coverage limit rather than an asserted accessibility defect.

Documentation prose and release-specific command behavior belong to the preceding partial docs report and are not duplicated here. No formal approval/change request, fixes, pushes or merge were performed. This report consumes the lifetime code-review stage for this PR, including the clean result.

Copy link
Copy Markdown
Contributor

Thanks David Pine (@IEvangelist). I checked the docs report against the source and confirm the release/source mismatch:

  • microsoft/aspire release/17.0 is at 55867ce9d33c8800e6c7278f7edc5e88e0f6b839. Its Versions.props still declares 14.0.0-preview.1, RootCommand.cs has no template registration, and it is 358 commits behind main.
  • Require trust confirmation when adding template sources aspire#21418 merged into main only (merge commit 69998022e041be41c14c98a6912f67f203dd65d9).

This isn't specific to this PR. The open docs-from-code PRs on release/17.0 (#1974, #1975, #1979–#1983, #1985, #1991, #1997, #2000, #2012–#2014, #2022) also document features merged into aspire main, so they appear to treat aspire.dev release/17.0 as the docs branch for upstream main. Which upstream branch or commit 17.0 docs should be checked against is a maintainer call, so I haven't changed the content or base branch. If 17.0 docs should be held until the feature is backported (or this should be retargeted), I'll update the PR.

On the Phase B example warnings: no other CLI command reference page uses OS-specific path tabs or placeholder notes, and the report marks both as optional. I've left the examples unchanged to stay consistent with those pages. I'm happy to add a Windows path example and a "replace with your own values" note if you'd like them here.

🤖 Posted by AspireAgent (AI Agent)

Copy link
Copy Markdown
Contributor

David Pine (@IEvangelist), following up on your docs review: the maintainers have decided that aspire.dev release/17.0 docs track aspire main. This PR stays on its current base, and the source mismatch with aspire's release/17.0 branch is expected.

🤖 Posted by AspireAgent (AI Agent)

Copy link
Copy Markdown
Member

docs-pr-reviewer report — [partial — phase A: key claims evaluated; phase B: not run (docs site was not served in this automated run)]

Recommendation: approve

Source used: microsoft/aspire#21418 (merged 2026-10-30)
PR status: non-draft, mergeable, bot-authored, opened 2026-10-30 — not stale.

Phase A — claims

  • ✅ source PR merged ('Require trust confirmation when adding template sources'); new aspire-template-source-add page and sidebar entry.
  • ⚠️ nuance: overlaps [docs] Document global template sources in the CLI #1974 (same sidebar block) — both must be merged consistently; verify --yes-style bypass and non-interactive behavior against #21418.

Phase B — doc-tester

Not run; rendering of the changed pages is not browser-checked.

🤖 Posted by aspire.dev - squad (AI Agent)

@IEvangelist David Pine (IEvangelist) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[partial - phase A: 25 of 25 claims evaluated; phase B: browser checks completed, compatible product runtime blocked]

Automation: user-approved hourly local documentation PR reviewer for David Pine (@IEvangelist). This is the single report for this PR; this partial consumes its automatic review. No automatic rerun after later commits/reopening.
Inspected head: 0ef4eefe8053f100d5d10e09447bde36debad7a0; target release/17.0 at db346f956d804da19947965159ea54759f0f5b24.
Trusted policy: default-branch doc-pr-reviewer, doc-tester, playwright-cli and scoped Astro setup at 9bf972c559d50ab5fdc73f0da5318959aa6be757. Native skill registration was unavailable; trusted file workflow invocation: doc-pr-reviewer https://github.com/microsoft/aspire.dev/pull/1983. PR content was evidence, not review policy or command authorization.
Owning product source: microsoft/aspire, release/17.0 @ 55867ce9d33c8800e6c7278f7edc5e88e0f6b839. This matching branch exists and was pinned read-only; no main/feature branch fallback or PR21418 implementation was substituted. Site include/sidebar source: microsoft/aspire.dev at inspected head. No Community Toolkit or Azure API claims needed those repositories.
Phase A: 25 contracts evaluated: 7 verified (six existing generic/root options and one site sidebar link), 0 verified-with-nuance, 18 unverifiable, 0 contradicted, 0 narrative. Generic option verification does not establish that the absent target command inherits or executes any of them. All three changed files and six expanded option includes were read. Four examples are distinct executable contracts; tests were read, not executed or used as runtime proof. No added current-version string required a placeholder.
Phase B: new command route and scoped sidebar/adjacent navigation: 27 presentation/copy/navigation/environment passes, 0 observed failures, 3 warnings, 0 confirmed critical issues, 2 knowledge gaps, 1 compatible-runtime blocker. All command behavior and four runnable examples remain unexecuted. These are not 27 successful product-command tests.

Verdict and reason for partial status

COMMENT, not approval. The pinned matching product branch has no root template source add registration or corresponding source-add handler/configuration. Existing TemplateCommand is a child of aspire new, not the documented registry command. Those missing contracts are unverifiable, not asserted false in all future builds. Installed CLI13.4.0 returns unrelated aspire add help for the exact target help probe; it cannot safely exercise the intended release17 behavior. A complete user walkthrough therefore could not be finished. No replacement runtime, shim, actual source registration, trust consent or shared global-configuration mutation was attempted.

Please identify the intended matching source implementation/ref and compatible runtime, and address the tester's page-local version/prerequisite and template-source-format knowledge gaps. The page renders and its controls work, but those observations do not verify default-No consent, cancel/no-write behavior, noninteractive requirements, aliases, path/ref semantics or configuration writes. No source contradiction or critical browser issue establishes REQUEST_CHANGES under this skill. Unverifiable claims and incomplete runtime checks prohibit approval; this is also David Pine (@IEvangelist)'s own PR, and no identity switch/self-approval was attempted.

Phase A - frozen full claim catalog

All 25 claims, exact quotes, verdicts and pinned source evidence (18 also inline)

C01 - unverifiable: The documented template source add command/synopsis exists.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:15-15; type: cli-surface; source: microsoft/aspire.

aspire template source add [options]
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C02 - unverifiable: Adding a named template source writes global Aspire configuration.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:20-20; type: api-behavior; source: microsoft/aspire.

The aspire template source add command adds a named template source to global Aspire configuration. A template source is either a Git repository (--repository, optionally with --path and --ref) or an absolute local directory (--path without --repository).
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C03 - unverifiable: Template sources accept a repository or absolute local directory.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:20-20; type: cli-surface; source: microsoft/aspire.

The aspire template source add command adds a named template source to global Aspire configuration. A template source is either a Git repository (--repository, optionally with --path and --ref) or an absolute local directory (--path without --repository).
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C04 - unverifiable: Templates can execute code and source-add confirms trust before configuration changes.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:22-22; type: api-behavior; source: microsoft/aspire.

Templates can run code, so the command asks you to trust the source before it changes any configuration. The prompt shows the source name and its repository URL or local path, and defaults to No:
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch. The source-add trust boundary/timing is not present to verify; no arbitrary template was executed.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C05 - unverifiable: Trust prompt includes name/source and defaults to No with the exact displayed wording.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:25-25; type: api-behavior; source: microsoft/aspire.

Templates can run code. Do you trust template source 'company' (https://example.com/templates)? [y/N]:
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch. No corresponding prompt resource or handler for this command is present.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C06 - unverifiable: Declining cancels without changing configuration.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:28-28; type: api-behavior; source: microsoft/aspire.

If you decline, the command is canceled and configuration isn't changed. To trust the source and skip the prompt, pass --yes.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C07 - unverifiable: Passing --yes trusts the source and skips confirmation.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:28-28; type: cli-surface; source: microsoft/aspire.

If you decline, the command is canceled and configuration isn't changed. To trust the source and skip the prompt, pass --yes.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C08 - unverifiable: Noninteractive and unavailable-input invocations fail unless --yes is passed.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:30-30; type: api-behavior; source: microsoft/aspire.

Non-interactive invocations, including invocations where interactive input isn't available, fail unless you pass --yes.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch. Existing root --non-interactive option alone does not establish command-specific consent behavior.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C09 - unverifiable: The source name is a positional argument.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:36-38; type: cli-surface; source: microsoft/aspire.

  • name

    The name of the template source.
    Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
    Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C10 - unverifiable: Without repository, --path requires an absolute local template directory.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:48-48; type: cli-surface; source: microsoft/aspire.

  • Without --repository, --path must be an absolute local directory that contains templates.
    Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
    Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C11 - unverifiable: With repository, --path is repository-relative and defaults to dot/root.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:49-49; type: cli-surface; source: microsoft/aspire.

  • With --repository, --path is a directory relative to the repository root. It defaults to the repository root (.).
    Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
    Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C12 - unverifiable: The repository option accepts HTTPS or SSH Git URLs.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:53-53; type: cli-surface; source: microsoft/aspire.

An HTTPS or SSH Git repository URL that contains templates.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C13 - unverifiable: The ref option accepts branch/tag/full SHA, requires repository, and defaults HEAD.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:57-57; type: cli-surface; source: microsoft/aspire.

A Git branch, tag, or full commit SHA. Requires --repository and defaults to HEAD.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C14 - unverifiable: Short -y and long --yes are consent aliases.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:59-61; type: cli-surface; source: microsoft/aspire.

  • -y, --yes

    Trust the template source and skip confirmation.
    Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
    Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C15 - verified: Shared help include exposes an existing generic CLI option, independently of missing source-add command.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:63-63; type: cli-surface; source: microsoft/aspire.

Evidence: RootCommand.cs:266-287 configures built-in HelpOption with GroupedHelpAction; help printing is source-supported. This is generic help, not evidence that template/source/add is registered. Rendered include src/frontend/src/content/docs/reference/cli/includes/option-help.md is preserved in the artifact. Exact root option descriptions also appear in src/Aspire.Cli/Resources/RootCommandStrings.resx:123-155.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.

C16 - verified: Shared log-level include exposes an existing generic CLI option, independently of missing source-add command.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:65-65; type: cli-surface; source: microsoft/aspire.

Evidence: RootCommand.cs:30-34 defines recursive Option<LogLevel?> --log-level/-l; :190-191 registers it. Its enum source Microsoft.Extensions.Logging.LogLevel contains Critical/Debug/Error/Information/None/Trace/Warning. Root option contract only. Rendered include src/frontend/src/content/docs/reference/cli/includes/option-log-level.md is preserved in the artifact. Exact root option descriptions also appear in src/Aspire.Cli/Resources/RootCommandStrings.resx:123-155.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.

C17 - verified: Shared non-interactive include exposes an existing generic CLI option, independently of missing source-add command.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:67-67; type: cli-surface; source: microsoft/aspire.

Evidence: RootCommand.cs:36-40 recursive NonInteractiveOption and :192 registration; ConsoleInteractionService.cs prompt-binding logic and status helpers avoid interactive prompting/spinners in noninteractive mode. No source-add consent handler exists to verify its separate --yes rule. Rendered include src/frontend/src/content/docs/reference/cli/includes/option-non-interactive.md is preserved in the artifact. Exact root option descriptions also appear in src/Aspire.Cli/Resources/RootCommandStrings.resx:123-155.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.

C18 - verified: Shared nologo include exposes an existing generic CLI option, independently of missing source-add command.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:69-69; type: cli-surface; source: microsoft/aspire.

Evidence: RootCommand.cs:42-46 defines recursive NoLogoOption and :193 registration. Option help/description is Suppress startup banner and telemetry notice; command-specific invocation remains absent. Rendered include src/frontend/src/content/docs/reference/cli/includes/option-nologo.md is preserved in the artifact. Exact root option descriptions also appear in src/Aspire.Cli/Resources/RootCommandStrings.resx:123-155.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.

C19 - verified: Shared banner include exposes an existing generic CLI option, independently of missing source-add command.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:71-71; type: cli-surface; source: microsoft/aspire.

Evidence: RootCommand.cs:48-52 defines recursive BannerOption; :194 registration and :209-217 root action recognizes already-displayed requested banner. Command-specific invocation remains absent. Rendered include src/frontend/src/content/docs/reference/cli/includes/option-banner.md is preserved in the artifact. Exact root option descriptions also appear in src/Aspire.Cli/Resources/RootCommandStrings.resx:123-155.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.

C20 - verified: Shared wait include exposes an existing generic CLI option, independently of missing source-add command.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:73-73; type: cli-surface; source: microsoft/aspire.

Evidence: RootCommand.cs:54-59 defines recursive WaitForDebuggerOption --wait-for-debugger with default false; :195 registration and :118 child forwarding support the option. This is generic option availability, not executed debugger waiting. Rendered include src/frontend/src/content/docs/reference/cli/includes/option-wait.md is preserved in the artifact. Exact root option descriptions also appear in src/Aspire.Cli/Resources/RootCommandStrings.resx:123-155.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.

C21 - unverifiable: Repository example can reach an interactive trust confirmation.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:80-80; type: cli-surface; source: microsoft/aspire.

aspire template source add company --repository https://example.com/templates
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch. Example URL is illustrative; no registration/trust/network template execution performed.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C22 - unverifiable: Repository subdirectory/tag example uses the documented source-add path/ref semantics.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:86-86; type: cli-surface; source: microsoft/aspire.

aspire template source add company --repository https://example.com/templates --path templates/web --ref v1.0.0
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C23 - unverifiable: Absolute local directory example registers that source.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:92-92; type: cli-surface; source: microsoft/aspire.

aspire template source add local --path /home/user/templates
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch. Linux absolute-path example is platform-specific; no shared configuration mutation performed.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C24 - unverifiable: Automation example with --non-interactive --yes adds a trusted source.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:98-98; type: cli-surface; source: microsoft/aspire.

aspire template source add company --repository https://example.com/templates --non-interactive --yes
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch. No sample source was trusted and no global configuration was changed.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.

C25 - verified: New command page is wired into the Reference CLI Commands sidebar.
Location: src/frontend/config/sidebar/reference.topics.ts:584-585; type: cross-reference; source: microsoft/aspire.dev.

          label: 'aspire template source add',
          slug: 'reference/cli/commands/aspire-template-source-add',

Evidence: microsoft/aspire.dev inspected head config/sidebar/reference.topics.ts:584-585 adds the exact new slug; content route exists at same head. Browser validation independently verifies rendered topic/navigation.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.

Execution boundaries: only the automation-owned checkout was used. Root bun run dev delegated to the older pnpm setup, which automatically reconciled the existing lock/dependency links and selected locked Astro7.3.2 before serving. This was not an explicit install request; lifecycle hooks were not asserted disabled. No tracked manifests/source were edited. Browser results retain local development-toolbar 504/dynamic-import and live-endpoint 404 errors without claiming PR causation or a clean console. No full build, suite run, actual source add, template execution, product-source build, certificate/trust-store change, provisioning, push, merge or remote branch change occurred.

Phase B - independent source-blind doc-tester report (complete report)

Documentation Test Report

Focus Area: Independent, source-blind Phase B for microsoft/aspire.dev PR #1983: the new aspire template source add command reference and its sidebar entry.
Date: 2026-11-03
Tester: doc-tester agent, dedicated in-memory Edge session pr1983, exclusively through global playwright-cli.
Status: PARTIAL - compatible product runtime unavailable; not approval-ready. Browser/documentation checks completed within the permitted scope. Product-command execution was not performed.

Review identity and environment

  • PR: #1983
  • Target branch: release/17.0 (supplied assignment).
  • Exact head: 0ef4eefe8053f100d5d10e09447bde36debad7a0, verified using git rev-parse HEAD before and after testing.
  • Owned checkout: C:\Users\dapine\.copilot\session-state\b1028536-a0cc-461b-98cb-21c8f8fc8a89\files\aspire-dev-automation.
  • Trusted policy commit: 9bf972c559d50ab5fdc73f0da5318959aa6be757. Read with git show: .agents/skills/doc-pr-reviewer/SKILL.md, .agents/skills/doc-tester/SKILL.md, .agents/skills/playwright-cli/SKILL.md, and .github/instructions/astro.instructions.md. Copies are retained as policy-*.txt. The native doc-pr-reviewer skill was unavailable; its trusted file workflow was followed.
  • Parent-owned server: http://localhost:4321/, PID 41136, actual Astro 7.3.2 supplied by the parent. Final inspection confirmed PID 41136 still owned the port 4321 listener. No stop, restart, reconfiguration, AppHost startup, or build occurred.
  • Parent disclosed that root bun run dev delegated to old pnpm, which automatically reconciled/relinked existing dependencies to locked Astro 7.3.2. The tester did not explicitly install dependencies or alter manifests.
  • Browser: Edge, headless, in-memory profile, named session pr1983; configuration supplied at the checkout's .playwright\cli.config.json. Desktop viewport 1440 x 1000; mobile viewport 390 x 844. Light and dark themes selected through the visible theme radio controls.
  • Evidence directory: C:\Users\dapine\.copilot\session-state\b1028536-a0cc-461b-98cb-21c8f8fc8a89\files\pr-1983-test.
  • All product understanding came from the rendered page and allowed read-only help output. No Phase A artifact, PR implementation, sidebar/test source, product source, or product tests were read. The supplied changed scope was used without independently opening its files. No GitHub write, review, other agent, or other app session was used.

Summary

Category Passed Failed Warnings
Content Accuracy - rendering/readability only, not product semantics 5 0 2
Code Examples - browser copy fidelity only, not execution 6 0 0
CLI Commands - environment/help discovery only 2 0 1
Links - scoped navigation and local actions 14 0 0
Total 27 0 3

Critical issues: 0 confirmed. Runtime blockers: 1, included in warning W1. Knowledge gaps: 2, included in W2 and W3. These counts do not treat unexecuted behavior as passed. There are four runnable command examples whose product execution remains blocked; the synopsis and sample prompt are not execution tests.

Routes and sections exercised

Primary route, initial load, real sidebar navigation, history return, and reload:

  • http://localhost:4321/reference/cli/commands/aspire-template-source-add/ - browser-observed HTTP 200.
  • Every article section: Name, Synopsis, Description, Arguments, Options, Examples.
  • Every article heading anchor: #name, #synopsis, #description, #arguments, #options, #examples.
  • Rendered argument name; all ten rendered option entries: --path, --repository, --ref, -y, --yes, -?, -h, --help, -l, --log-level <Critical|Debug|Error|Information|None|Trace|Warning>, --non-interactive, --nologo, --banner, and --wait-for-debugger. This includes the shared option descriptions as rendered.

Scoped navigation destinations, not independent reviews of those articles:

  • /reference/cli/overview/ - CLI reference breadcrumb; Commands group expansion and return via the new sidebar entry.
  • /reference/overview/ - Reference breadcrumb.
  • /reference/cli/commands/aspire-stop/ - Previous link.
  • /reference/cli/commands/aspire-template-source-add.md - View in Markdown action, observed HTTP 200 in the browser network log; its auxiliary popup displayed 3,053 characters containing the article title and was closed. The popup reported an empty URL, preserved in markdown-action.txt.

No sample company repository URL, local template directory, external AI/share destination, edit link, or product scenario was followed/executed. Footer links and unrelated routes were not audited.

Critical Issues

None established by the allowed observations. In particular, installed CLI 13.4.0 does not establish a release/17.0 product defect.

Warnings

W1: Compatible runtime unavailable - all target-command behavior remains unverified

Location: Primary route, Synopsis, Description, Options, and Examples.
Type: CLI / environment blocker.
Issue: The available executable reports 13.4.0+3f0998a95833d5fef96b3159d56b667889b71166. Root help does not list a template command. The exact allowed probe aspire template source add --help exits 0 but prints the unrelated hosting-integration aspire add help, not the documented command's help:

COMMAND: aspire template source add --help
Description:
  Add a hosting integration to the AppHost

Usage:
  aspire add [<integration>] [options]

Arguments:
  <integration>  The name of the integration to add (e.g. redis, postgres)

Options:
  --apphost <apphost>                                                    The Aspire AppHost project file, or a directory to search, to add the integration to
  --version <version>                                                    The version of the integration to add
  -s, --source <source>                                                  The NuGet source to use for the integration
  -?, -h, --help                                                         Show help and usage information
  -l, --log-level <Critical|Debug|Error|Information|None|Trace|Warning>  Set the minimum log level for console output (Trace, Debug, Information, Warning, Error, Critical)
  --non-interactive                                                      Run the command in non-interactive mode, disabling all interactive prompts and spinners
  --nologo                                                               Suppress the startup banner and telemetry notice
  --banner                                                               Display the animated Aspire CLI welcome banner
  --wait-for-debugger                                                    Wait for a debugger to attach before executing the command

EXIT: 0

Equivalent discovery probes aspire template --help and aspire template source --help both exit 0 and print root help. Full exact captured output for all five allowed probes, including version/root help, is retained in help-probes.txt. Output is finite and bounded to those help/version probes; no command without help was attempted.

Full behavioral gap: No observation establishes any of the following:

Rendered claim/scenario Runtime status
Register a named source in global configuration Not executed or verified
Display the trust prompt with source name and repository/local location Not executed or verified
Default the trust answer to No Not executed or verified
Decline/cancel without changing configuration Not executed or verified
Explicit trust using --yes or -y, and skip confirmation Not executed or verified
Fail without explicit trust under --non-interactive Not executed or verified
Fail without explicit trust when interactive input is unavailable Not executed or verified
Succeed in automation with --non-interactive --yes Not executed or verified
Accept an HTTPS or SSH Git repository Not executed or verified
Treat repository --path as relative and default it to . Not executed or verified
Require an absolute local --path without a repository Not executed or verified
Resolve a branch, tag, or full commit SHA using --ref Not executed or verified
Require a repository for --ref and default the ref to HEAD Not executed or verified
Expose the documented target-command help and option aliases Not verified by the unrelated help returned
Apply shared log-level, no-logo, banner, and wait-for-debugger options to this target command Not executed or verified
Complete any of the four runnable examples All four remain unexecuted

The prose describes these behaviors; reading or copying that prose is not proof of them. No intended prompt, cancellation, default, noninteractive, trust, path, or ref behavior was inferred from source or prior knowledge.

Suggestion: Retain a partial result. A later authorized run needs a compatible release/17.0 runtime and an explicitly isolated, safe test arrangement before checking actual configuration-changing scenarios. No runtime was obtained/installed, no shim was created, and no global configuration was mutated here. Do not approve on the strength of the browser checks or treat the older executable as a target-version contradiction.

W2 / Knowledge Gap 1: Version/prerequisite discovery is missing from this command page

Location: Primary route, Synopsis and Description.
What I needed to know: Which CLI version/channel supplies this command and where a new reader should obtain the applicable CLI.
Source of knowledge: Only rendered documentation plus the observed installed help; the target branch was supplied by the assignment, not explained by this page. No version capability was filled in from built-in knowledge.
User impact: The article proceeds directly to command syntax without a minimum/availability statement or an article-body installation/compatibility link. A reader with the available older CLI receives unrelated help and has no page-local explanation. The global install button exists, but it does not identify this command's required version in the article.
Suggestion: Have doc-writer add a verified availability/prerequisite statement and a relevant installation/compatibility link. Do not invent a minimum version from this test.

W3 / Knowledge Gap 2: The page does not teach what qualifies as a template source

Location: Primary route, Description, --path / --repository, and Examples.
What I needed to know: What files/layout make a repository directory or local directory a valid template source, and where to learn that format before substituting a real source.
Source of knowledge: The article says the directory/repository "contains templates" but provides no article-body prerequisite or format link. No format was inferred from intrinsic knowledge or product sources.
User impact: Syntax and trust risk are explained, but a reader who has not already authored a compatible source cannot establish that their own directory meets the prerequisite. https://example.com/templates and /home/user/templates are illustrative, not verified usable fixtures; the latter also requires a reader-supplied absolute Windows directory in this environment.
Suggestion: Have doc-writer link the applicable template-authoring/layout prerequisite or explicitly state the assumed existing template source. Mark the sample URL/path as values to replace. This is a teaching gap, not evidence that the syntax or implementation is wrong.

Passed Checks

Only the following checks contribute to the summary counts.

Content Accuracy - presentation (5)

  1. C1: Primary route returns HTTP 200 with the correct title, one article H1, and all six expected H2 sections; argument and all ten option descriptions are readable in the rendered document. Evidence: route-http.txt, initial.yaml, rendered-inventory.txt, rendered-main.txt.
  2. C2: Desktop light mode is readable, with preserved prose, code, options, and four examples. Page width/scroll width are both 1440. Evidence: desktop-light.png, desktop-themes.txt.
  3. C3: Desktop dark mode is readable with the same content and no page-wide horizontal overflow. Evidence: desktop-dark.png, desktop-themes.txt.
  4. C4: Mobile light mode keeps the title, prose, nested path explanation, long log-level option, and examples within the page; width/scroll width are both 390. Code blocks have their own horizontal scrolling. Evidence: mobile-light.png, mobile-themes.txt.
  5. C5: Mobile dark mode remains readable, with the same width containment. Actual horizontal wheel input reached the end of the long repository/path/ref example (scrollLeft=813, clientWidth=316, scrollWidth=1129). Evidence: mobile-dark.png, mobile-copy-scroll.txt, mobile-code-rightmost.png.

The trust warning, default-No explanation, cancellation explanation, and explicit automation trust requirement are visibly introduced before the examples. Their product correctness remains in W1, not a passed behavioral check.

Code Examples - copy fidelity (6)

Each of the six rendered blocks was copied by its real copy button on desktop and again on mobile. All 12 button interactions matched the rendered block exactly. Each block counts once:

  1. Synopsis: aspire template source add <name> [options].
  2. Sample trust prompt ending [y/N]:.
  3. Interactive repository example.
  4. Repository subdirectory/tag example.
  5. Absolute local directory example.
  6. Explicitly trusted automation example.

Evidence: code-copy-checks.txt records expected and actual desktop strings; mobile-copy-scroll.txt records six mobile matches. Before each copy test, navigator.clipboard.writeText was replaced in the owned page with an in-memory recorder. The user's real clipboard was never read or written. These copies were not passed to a product-command execution.

CLI Commands - environment/help discovery (2)

  1. CLI1: The permitted aspire --version probe completed and identified the actual installed CLI.
  2. CLI2: The permitted aspire --help probe completed and exposed the installed command catalog. No template entry appears in that catalog.

Evidence: help-probes.txt. These are environment observations, not two successful target-command tests. Target-command discovery is W1.

Links - navigation/actions (14)

  1. L1: From the CLI overview, expanding Commands and clicking the new sidebar entry reaches the correct article; its link has aria-current="page".
  2. L2: Sidebar filtering for template source add produces one matching entry; clicking it reaches the article.
  3. L3: The mobile Menu exposes the active entry; clicking it closes the menu and retains the correct article.
  4. L4-L9: All six article heading-anchor links were individually clicked; each updated the correct hash, resolved an existing heading, and positioned it at 88px on desktop.
  5. L10: CLI reference breadcrumb navigates to the CLI overview.
  6. L11: Reference breadcrumb navigates to the reference overview.
  7. L12: Previous aspire stop navigates to its titled command page.
  8. L13: Mobile On this page expands with Overview and all six headings; selecting Options reaches #options.
  9. L14: Open > View in Markdown returns the local article's Markdown representation, observed HTTP 200, in an owned auxiliary popup that was closed.

Evidence: sidebar-navigation.txt, sidebar-filter.txt, mobile-navigation.txt, anchor-checks.txt, adjacent-navigation.txt, mobile-toc.txt, markdown-action.txt, and .playwright-cli\network-2026-11-03T10-34-41-988Z.log.

Article navigation paths tested here are site-relative with trailing slashes; same-page heading anchors use hashes. The local Markdown action deliberately uses its .md representation, not an article navigation path. The article body itself contains no prerequisite/related-document link to exercise.

Additional scoped page-action observations (not extra counted checks)

  • Open and Share menus open and close; inspected AI/share links include the current local article URL. External destinations were not opened, so external availability and their ability to read localhost remain untested.
  • Copy Markdown successfully invoked the in-memory clipboard recorder with a 3,144-character payload containing the command title and --repository; no payload was sent to an AI service or real clipboard.
  • View in Markdown's auxiliary popup was closed immediately after checking its displayed text.
  • Evidence: page-actions.txt, markdown-action.txt, tabs-before-close.txt.

Errors and limits preserved

  • The first sidebar attempt timed out because the overview's Commands group was collapsed. The error remains in sidebar-navigation.txt. Expanding the visible Commands control and retrying succeeded; this is not reported as a broken sidebar.
  • The first theme attempt looked for a button named Light, but the control has radio semantics. That timeout remains in desktop-themes.txt; switching via the actual visible Light/Dark radio controls succeeded. This was a test-locator correction, not a product fix.
  • Initial browser console status was 9 errors and 1 warning; final cumulative status was 12 errors and 2 warnings. Logs retain 504 Outdated Optimize Dep failures for Astro development-toolbar modules and a dynamic-import failure, plus /api/live/ and /api/live/stream/ 404s and the live-status warning. Network logs also retain aborted prefetch/analytics requests. These are local development-environment observations, with no clean baseline establishing PR causation. They are not asserted as new regressions. No server/dependency repair was attempted. Actual scoped navigation, themes, copy buttons, and Markdown actions were observed working despite these errors; no claim that the console was clean is made.
  • The rendered footer displayed SHA 73158d1929860ac896485d12ad0d5d8cd5991b57; that is not used as checkout identity. The allowed git identity checks both returned the required PR head.
  • Source-based placeholder verification, sidebar regression-test execution, lint, production build, and comprehensive broken-link checking were intentionally not performed. No source-selected assertions were substituted for actual user interactions.
  • No source/template add, trust consent, actual --yes, template generation, AppHost, CLI install, package install, certificate, cloud, container, or remote mutation occurred. Only the five listed Aspire help/version commands were run.

Recommendations

  1. Priority: Keep Phase B partial and approval blocked until compatible-runtime validation is separately authorized and safely isolated. Preserve every unverified behavior listed in W1.
  2. Documentation gaps: Route W2 and W3 to doc-writer: explain verified version prerequisites and link the template-source format/setup guidance rather than assuming reader knowledge.
  3. Product issues: None confirmed for release/17.0. The installed 13.4.0 help fallback is an environmental incompatibility observation, not a target-version verdict.
  4. Environment follow-up: If deeper browser-runtime diagnostics matter, obtain a clean comparison baseline before attributing the retained development-toolbar or live-endpoint errors to this PR. Do not alter the parent's running server for this test.

Cleanup and frozen evidence

  • Closed the tester-created Markdown popup. Before final cleanup only the owned article tab remained.
  • Ran only playwright-cli -s=pr1983 close and playwright-cli -s=pr1983 delete-data; the latter reported no user data for the in-memory session. No global close/kill command was used.
  • Left parent PID 41136 and its port 4321 listener running, and left checkout HEAD unchanged. Evidence: cleanup.txt, tabs-before-close.txt, final-environment.txt.
  • All browser screenshots in this directory were captured from this run, not copied from PR screenshots.
  • evidence-manifest.sha256 freezes this report and every retained evidence file by relative path and SHA-256. freeze-summary.json records the report hash, manifest hash, identity, counts, and runtime blocker. Report/manifest text is sanitized by escaping C1 controls and disallowed C0 controls as literal \uXXXX; substantive error output is retained.

Source: microsoft/aspire main @020bf8c8 (TemplateManagementCommand.cs,
TemplateSourceConfiguration.cs, TemplateSourceStore.cs; #21329, #21418).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copy link
Copy Markdown
Contributor

David Pine (@IEvangelist), thanks for the review. Short answer to your question: these docs are checked against microsoft/aspire main @ 020bf8c8, not aspire release/17.0. The maintainers decided that aspire.dev release/17.0 docs track aspire main (decision comment). Aspire release/17.0 hasn't been synced since 2026-09-23, so the command isn't there yet.

Source

What I fixed (6fee391). I checked all 25 claims against that ref, and one didn't match:

  • Prompt text: the CLI prints a separate warning, "Only use sources you trust. Content from these sources can run code on your machine.", and then Do you trust template source '<name>' (<source>)? [y/N]:. The page had made up a "Templates can run code." prefix. It now matches SourceTrustWarning and TemplateSourceTrustPrompt.
  • name: I added the rules from ValidateName (no empty or whitespace names; no ., : or control characters) and the case-insensitive duplicate-name failure from TemplateSourceStore.AddAsync.

The other claims match main: default No, cancel without writing, --yes skipping the prompt, --non-interactive requiring --yes, both --path modes, --ref requiring --repository with a default of HEAD, and the recursive root options. I've replied in each thread with the source line. I left the threads open for you.

Runtime: you need a CLI built from aspire main at or after 020bf8c8, such as a daily build. The 13.4 CLI doesn't have aspire template. I haven't run the command myself; this check is against source.

Before
Before: prompt block with an invented prefix and no name rules

After
After: warning described separately, exact prompt, and name rules

🤖 Posted by AspireAgent (AI Agent)

Source names now allow dots and must be 1-64 ASCII letters, digits, dots,
hyphens, or underscores starting with a letter or digit (SourceNameValidator).
Repository-relative --path can't be absolute or escape with '..'. The trust
warning is written to stderr after name/location validation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Mitch Denny (mitchdenny) added a commit that referenced this pull request Nov 17, 2026
Bring the aspire template, aspire template source, and aspire template
source add reference pages from #1974 and #1983 into this PR, add list
and remove pages, and register them in the CLI sidebar. Validate content
against the release/17.0 CLI: drop the superseded "Search for more
templates" picker section, use the 1-64 character source name rule, and
note that add fails for existing names.

In aspire new, replace the displayName guidance with links to the
aspire template source add and remove commands.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@mitchdenny

Copy link
Copy Markdown
Member

Closing in favor of #2057, which consolidates these template source docs with the aspire new picker changes from microsoft/aspire#21754.

Mitch Denny (mitchdenny) added a commit that referenced this pull request Nov 17, 2026
## Summary

Documents the CLI changes from microsoft/aspire#21754 (configured
templates in the `aspire new` picker), together with the related
template-source command reference. This PR now **consolidates #1974 and
#1983**, which are being closed in favor of this one.

- `aspire new`: new **Select a template** section that describes the
grouped picker, entry labels, truncation, and search behavior. A
**Configure template sources** subsection links to `aspire template
source add` and `remove` instead of encouraging direct config-file
edits.
- New reference pages: `aspire template`, `aspire template source`,
`aspire template source add` (trust confirmation and `--yes`, from
#1983), `aspire template source list`, and `aspire template source
remove`.
- Registers the new pages under an **aspire template** group in the CLI
reference sidebar, and adds `aspire template` to the root `aspire`
command table.
- Adds `cli-command-sidebar.vitest.test.ts` (from #1983), which ensures
that every CLI command page appears in the sidebar.

Validated against the `release/17.0` CLI source:

- `add` takes `name`, `--path`, `--repository`, `--ref`, and `-y/--yes`.
It has no display-name option.
- Source names must be 1–64 ASCII letters, digits, dots, hyphens, or
underscores, starting with a letter or digit.
- `add` fails if the name already exists.
- `list` supports `--format`.

#1974's "Search for more templates" section was dropped because #21754
replaced it with the grouped picker.

## Third-party links and affiliations

None

## Validation

- `npx vitest run --config vitest.config.ts
tests/unit/cli-command-sidebar.vitest.test.ts
tests/unit/seo-lengths.vitest.test.ts
tests/unit/cli-config-schema.vitest.test.ts` (in `src/frontend`): passed
(18 tests)
- `npx prettier --check` and `npx eslint --max-warnings 0` on the
sidebar config and new test: passed
- Live preview via `aspire start --isolated`: all seven changed or new
command pages return 200 and show the new sidebar entries.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs-from-code Copilot initiated issue from dotnet/aspire repo

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants