Skip to content

[docs] Document Traces page Spans column overflow tooltip - #1876

Closed
aspire-repo-bot[bot] wants to merge 9 commits into
release/17.0from
docs/pr-20840-38273836913-1-0ff79d0494d0ec1b
Closed

aspire-repo-bot[bot] wants to merge 9 commits into
release/17.0from
docs/pr-20840-38273836913-1-0ff79d0494d0ec1b

Conversation

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Documents changes from microsoft/aspire#20840

@TessaIO

Target branch

Targeting release/17.0 based on the source PR milestone 17.0 (exact match found on microsoft/aspire.dev).

Why this is needed

microsoft/aspire#20840 fixed an ArgumentOutOfRangeException that could occur when rendering the resource overflow tooltip in the Traces page's Spans column, and reworked the tooltip to filter stale/invalid indexes while preserving resource tags, span counts, and tooltip presentation. The PR's "User-facing usage" section states:

On the dashboard Traces page, resource tags that do not fit in the Spans column appear in the overflow tooltip. Delayed overflow measurements after a resource-list update no longer crash tooltip rendering; valid resource tags remain visible in the tooltip.

The existing dashboard/explore.mdx page described the Spans column only as "The resources involved in the request," with no mention of the overflow/tooltip behavior for resource tags that don't fit in the column. This left a documentation gap for a user-visible dashboard feature.

What changed

  • src/frontend/src/content/docs/dashboard/explore.mdx: Expanded the Spans bullet in the Traces page description to explain that overflowing resource tags collapse into a +N indicator, and hovering over it shows the remaining resources and their span counts in a tooltip.

No new pages were created; this is a small, targeted update to an existing page.

Validation

Documentation-only change; no build/test commands were run per repository guidance for doc-only edits.

Generated by PR Documentation Check for #20840 · copilot · auto · 60.7 AIC · ⌖ 10.5 AIC · ⊞ 20.4K · ◷

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@aspire-repo-bot aspire-repo-bot Bot added the docs-from-code Copilot initiated issue from dotnet/aspire repo label Oct 12, 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 #1876. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #1876 artifacts

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

## Summary

<!-- Describe what this pull request changes and why. -->

Improve mobile navigation, reading, and catalogs across aspire.dev while
preserving the site's identity, content, and desktop information
architecture.

- Use the 34px **On this page** scale for secondary controls, with 12px
horizontal page-action padding and natural grouped wrapping. Keep
primary calls to action larger and code-copy glyphs at 16px.
- Make announcement links ordinary underlined text, with a separate
dismiss column that cannot overlap the copy. Preserve dismissal, expiry,
and reduced-motion behavior.
- Show page hierarchy as one conventional wrapping breadcrumb trail:
underlined ancestor links and a plain current page, without a back arrow
or page-selector-like dropdown. The in-page TOC is unchanged.
- Balance headings and wrap technical identifiers at meaningful
boundaries without changing their text. Match integration-card code
borders to surrounding light-theme controls.
- Match Hub search to other fields on every viewport: 34px on
phone/coarse layouts and 48px on desktop. Glossary topic/alphabet
filters and equivalent API filters share the 34px control scale.
- Preserve dedicated API search, keyboard/focus behavior, accessible
filter disclosure, bounded menus, client-side navigation cleanup, and
contained API/table scrolling.
- Fix production rich-doc link styling and native Pagefind/catalog
padding parity, and update the broader CI contracts to use real
mobile-menu navigation rather than hidden desktop-only controls.

### Current screenshots

65 mobile captures and 8 desktop checks replace the earlier screenshots.
They include final Hub/glossary size comparisons, 320px and doubled-text
cases, and expanded controls. Fonts, transitions, visible images, and
filter results were settled before capture. Click an image for its
full-size view.

<details><summary>Homepage</summary>

![Homepage, 390px
light](https://github.com/user-attachments/assets/a87fca0e-5bbe-44d5-8894-1226e4d9c215)

</details>

<details><summary>Documentation</summary>

| Documentation landing | First-app tutorial |
| --- | --- |
| ![Documentation landing, 390px
light](https://github.com/user-attachments/assets/7fa955e2-ac39-4c15-bac7-2001dcae4fe0)
| ![First-app tutorial, 390px
light](https://github.com/user-attachments/assets/e7259b00-d9c9-401f-9cb7-f1087a832e74)
|

| CLI installation | CLI reference |
| --- | --- |
| ![CLI installation, 390px
light](https://github.com/user-attachments/assets/f8120fcf-a405-4dc0-a2ee-2ce4659d3e49)
| ![CLI reference, 390px
light](https://github.com/user-attachments/assets/104427d4-248f-4e17-aa4c-5b4c6efb28d2)
|

</details>

<details><summary>Integrations, dashboard, and deployment</summary>

| Integrations landing | Integration gallery |
| --- | --- |
| ![Integrations landing, 390px
light](https://github.com/user-attachments/assets/1e2c44b4-54df-4f24-8d96-247e63e58400)
| ![Integration gallery, 390px
light](https://github.com/user-attachments/assets/2c3a41f4-41ce-40bb-8841-51536f3048cd)
|

| Redis integration guide | Dashboard landing |
| --- | --- |
| ![Redis integration guide, 390px
light](https://github.com/user-attachments/assets/ec0f32c3-fd5e-436b-a90d-c348d8f5404b)
| ![Dashboard landing, 390px
light](https://github.com/user-attachments/assets/6d8d949e-9462-4ff7-a9a4-e1da557bd265)
|

![Deployment landing, 390px
light](https://github.com/user-attachments/assets/cd24c8f0-0672-484d-a941-f1afac198386)

</details>

<details><summary>Community and media</summary>

| Community landing | Live videos |
| --- | --- |
| ![Community landing, 390px
light](https://github.com/user-attachments/assets/033009e9-1cbd-49f9-9e6a-07910548c53a)
| ![Live videos, 390px
light](https://github.com/user-attachments/assets/39e156ed-19be-4e06-b4d1-07a8b65ec7e5)
|

| Contributors | Acknowledgements |
| --- | --- |
| ![Contributors, 390px
light](https://github.com/user-attachments/assets/7f4322bf-cbae-4df6-9cf8-4c46f00b3960)
| ![Acknowledgements, 390px
light](https://github.com/user-attachments/assets/ce0d4f58-03dd-499e-8d5d-6d1c3e979444)
|

![Conference page, 390px
light](https://github.com/user-attachments/assets/f2adb6da-ef8d-4af4-9cb7-e9a6e91b29a2)

</details>

<details><summary>Catalogs and resource hub</summary>

| Samples | Sample details |
| --- | --- |
| ![Samples, 390px
light](https://github.com/user-attachments/assets/205d58c1-86bf-4d3c-89a0-46504f4fd8bf)
| ![Sample details, 390px
light](https://github.com/user-attachments/assets/a751fac1-2f97-423b-bfb1-0ee664056e16)
|

| Container images | Hub with matched search height |
| --- | --- |
| ![Container images, 390px
light](https://github.com/user-attachments/assets/13074f66-2cad-4c6b-8251-93de6fa3a67b)
| ![Hub, 390px
light](https://github.com/user-attachments/assets/70b3078f-fa0d-4c37-bc75-7a256931a355)
|

| Resource browser | Glossary with matched filter heights |
| --- | --- |
| ![Resource browser, 390px
light](https://github.com/user-attachments/assets/39fa2bb2-defe-4ca2-a156-a60e8c3ab960)
| ![Glossary, 390px
light](https://github.com/user-attachments/assets/ec37a8e9-a08a-4ac8-a637-96befe2d2e29)
|

![Long glossary title, 390px
light](https://github.com/user-attachments/assets/bc5c0f12-b936-47f7-a8c8-7b9409a6a2bf)

</details>

<details><summary>Localization and supporting pages</summary>

| Release notes | Translation dashboard |
| --- | --- |
| ![Release notes, 390px
light](https://github.com/user-attachments/assets/8321368a-ad8b-464c-94b5-946e2311da17)
| ![Translation dashboard, 390px
light](https://github.com/user-attachments/assets/f3fe6bc1-ea4a-4289-86c0-877a80e4df0a)
|

| 404 | German tutorial |
| --- | --- |
| ![404, 390px
light](https://github.com/user-attachments/assets/faa6a12d-df8a-4a2d-84e6-98f59c816d41)
| ![German tutorial, 390px
light](https://github.com/user-attachments/assets/a7c98792-aa99-4ae5-ab8f-be71af5501b1)
|

![Japanese tutorial, 390px
light](https://github.com/user-attachments/assets/3c1d1e85-f7d3-43a2-98ce-2c76b6987d85)

</details>

<details><summary>API reference</summary>

| C# index | C# package |
| --- | --- |
| ![C# index, 390px
light](https://github.com/user-attachments/assets/de892034-6f9d-4cff-9cd8-a3f1ea75fc68)
| ![C# package, 390px
light](https://github.com/user-attachments/assets/5428d7b9-4ca3-4811-8650-dc35655d3d19)
|

| C# type | C# members |
| --- | --- |
| ![C# type, 390px
light](https://github.com/user-attachments/assets/0306ea1f-65a1-44e8-92e9-ad13d7afb39b)
| ![C# members, 390px
light](https://github.com/user-attachments/assets/0c43194f-c166-4022-82e8-6f9e220cbe69)
|

| TypeScript index | TypeScript module |
| --- | --- |
| ![TypeScript index, 390px
light](https://github.com/user-attachments/assets/9ef75ba4-741a-4689-8762-ef29f79dae34)
| ![TypeScript module, 390px
light](https://github.com/user-attachments/assets/0758d449-a7f3-4367-8369-24baa413fe1d)
|

| TypeScript type | TypeScript member |
| --- | --- |
| ![TypeScript type, 390px
light](https://github.com/user-attachments/assets/2e8cdbf9-cfa6-4309-b062-a18472558b13)
| ![TypeScript member, 390px
light](https://github.com/user-attachments/assets/12390475-6c27-4037-8844-daafa73ea422)
|

</details>

<details><summary>Expanded controls</summary>

| Site menu | Documentation menu |
| --- | --- |
| ![Site menu, 390px
light](https://github.com/user-attachments/assets/b75d0422-33d7-469b-8dd0-7c134fc6b4a4)
| ![Documentation menu, 390px
light](https://github.com/user-attachments/assets/7c95a723-70c0-47db-beac-ef7f5d4a9c5d)
|

| API sidebar | Open menu |
| --- | --- |
| ![API sidebar, 390px
light](https://github.com/user-attachments/assets/3059fe0f-7b13-48d3-8789-74ab2a559c50)
| ![Open menu, 390px
light](https://github.com/user-attachments/assets/01b00ce7-6a89-4ee6-9d8f-2b1f78192d15)
|

| Share menu | Resource filters |
| --- | --- |
| ![Share menu, 390px
light](https://github.com/user-attachments/assets/39a75702-c8b4-45aa-b1a2-366b952ef255)
| ![Resource filters, 390px
light](https://github.com/user-attachments/assets/214b1adc-cc29-40ba-abf6-c3cf92c96b4f)
|

| API versions | Sample tags |
| --- | --- |
| ![API versions, 390px
light](https://github.com/user-attachments/assets/2c55c3e2-3999-4dad-816c-388730bf78a3)
| ![Sample tags, 390px
light](https://github.com/user-attachments/assets/f84a6064-47bc-40ab-86cc-900d0cf296af)
|

| Footer preferences | Language preferences |
| --- | --- |
| ![Footer preferences, 390px
light](https://github.com/user-attachments/assets/5f692383-e4af-403e-9eb8-b360b395b921)
| ![Language preferences, 390px
light](https://github.com/user-attachments/assets/d060aae7-8398-4673-9966-9b4ba906528e)
|

| Contained translation table | Long API parameters |
| --- | --- |
| ![Contained translation table, 390px
light](https://github.com/user-attachments/assets/6e0f7614-2318-4d3b-8f80-db7430ddb2e3)
| ![Long API parameters, 390px
light](https://github.com/user-attachments/assets/8defda44-d132-4453-9202-b1933d80ddaa)
|

![Release navigation, 390px
light](https://github.com/user-attachments/assets/16c66cfb-cad9-41e9-893e-91613786a40b)

</details>

<details><summary>Conventional page hierarchy</summary>

![Complete wrapping breadcrumb trail, 390px
light](https://github.com/user-attachments/assets/673f55c0-b14f-4f57-be21-85ed74084011)

</details>

<details><summary>Dark theme</summary>

| Homepage | Integration gallery |
| --- | --- |
| ![Homepage, 390px
dark](https://github.com/user-attachments/assets/459ae41b-5451-4bc4-81ad-fc7367470ddc)
| ![Integration gallery, 390px
dark](https://github.com/user-attachments/assets/efe255c8-50fb-4cd6-b501-49eeb1bb36ea)
|

| API members | Resource browser |
| --- | --- |
| ![API members, 390px
dark](https://github.com/user-attachments/assets/12a34c2f-a042-43b3-8ace-5437d8ca117d)
| ![Resource browser, 390px
dark](https://github.com/user-attachments/assets/4cbe3bb6-c451-4544-aeb7-2a53423f5d52)
|

![Site menu, 390px
dark](https://github.com/user-attachments/assets/8e56809c-3855-4c0b-a70e-ad558931e5b7)

</details>

<details><summary>Narrow phones</summary>

| Homepage | CLI installation |
| --- | --- |
| ![Homepage, 320px
light](https://github.com/user-attachments/assets/2a50fead-eb40-4469-b61f-df56a75d8d5e)
| ![CLI installation, 320px
light](https://github.com/user-attachments/assets/fcad8551-b35c-4656-85bc-588aeef8fa4c)
|

| API parameter types | Translation table |
| --- | --- |
| ![API parameter types, 320px
light](https://github.com/user-attachments/assets/2f03713f-e4a1-4ff0-b0ea-daded9bad473)
| ![Translation table, 320px
light](https://github.com/user-attachments/assets/65ec4064-1ddc-4421-91ba-52fbf496eeb4)
|

![CLI code-copy control, 320px
light](https://github.com/user-attachments/assets/376409ba-6014-4ad5-b4ac-c24274339516)

</details>

<details><summary>Code and long labels</summary>

| Compact code-copy control | Longest integration name |
| --- | --- |
| ![Compact code-copy control, 390px
light](https://github.com/user-attachments/assets/7e03fd75-248f-46f1-bd52-d4db88d7b62d)
| ![Longest integration name, 390px
light](https://github.com/user-attachments/assets/ce2073ec-0087-4bce-9023-edb37c04c0d3)
|

</details>

<details><summary>Enlarged text</summary>

| Banner at 200% text | Documentation at 200% text |
| --- | --- |
| ![Banner at 200% text,
390px](https://github.com/user-attachments/assets/7446c894-923e-46c0-a705-2417bfa8a274)
| ![Documentation at 200% text,
390px](https://github.com/user-attachments/assets/9f28bf51-e529-47ff-9fc0-7484ff06c063)
|

</details>

<details><summary>Desktop checks</summary>

| Homepage | Documentation |
| --- | --- |
| ![Homepage, 1440px
light](https://github.com/user-attachments/assets/8cbf19b3-66ba-4ae8-8616-5af76d1c2e1b)
| ![Documentation, 1440px
light](https://github.com/user-attachments/assets/93b0291b-ac68-44a7-841a-a6393585036b)
|

| API members | Homepage dark |
| --- | --- |
| ![API members, 1440px
light](https://github.com/user-attachments/assets/ea967af7-76c6-44c2-a579-8a6cc9e8d528)
| ![Homepage, 1440px
dark](https://github.com/user-attachments/assets/20627d06-91a7-44b9-aff6-93e9250d9dcb)
|

</details>

<details><summary>Final matched search and filter sizes</summary>

| Resource Hub mobile dark | Glossary mobile dark |
| --- | --- |
| ![Resource Hub, 390px
dark](https://github.com/user-attachments/assets/21477fa8-1b72-4113-bcec-8c208b833b19)
| ![Glossary, 390px
dark](https://github.com/user-attachments/assets/ff94b11f-b398-4447-b62d-7b74cea903d2)
|

| Resource Hub desktop light | Glossary desktop light |
| --- | --- |
| ![Resource Hub, 1440px
light](https://github.com/user-attachments/assets/10b17fe8-b745-485e-9207-a01cd1094439)
| ![Glossary, 1440px
light](https://github.com/user-attachments/assets/c975d0d7-10fb-485a-b0c5-6ea78052f4c8)
|

| Resource Hub desktop dark | Glossary desktop dark |
| --- | --- |
| ![Resource Hub, 1440px
dark](https://github.com/user-attachments/assets/a256f1f7-2c1e-4674-ac17-c994932bf7dd)
| ![Glossary, 1440px
dark](https://github.com/user-attachments/assets/2d3893c4-7ed1-490c-a780-b719130663cd)
|

</details>

## Third-party links and affiliations

<!--
List any third-party links added or changed by this pull request and
disclose any
material affiliation with the linked organizations, such as employment,
sponsorship, or ownership. Write "None" if this pull request doesn't add
or
change third-party links.
-->

None. Existing third-party destinations are preserved.

## Validation

<!-- List the checks you ran or explain why validation isn't needed. -->

Commands run from `src\frontend`:

- `pnpm exec vitest run --config vitest.config.ts` - **passed: 1,024
tests in 78 files; 1 intentionally skipped**, against the updated CI
base.
- `pnpm lint` - **passed**, including Astro synchronization,
skill-digest verification, and complete ESLint checking.
- `pnpm exec playwright test gallery-search-contract.spec.ts
dev-glossary.spec.ts dev-layout.spec.ts --workers=2 --reporter=list
--grep 'Hub search and glossary filters|glossary toolbar|typography and
glossary controls|full-size search input geometry|integration query,
facets'` - **passed: 16 tests; 2 intentionally skipped**, confirming
common Hub/Browse/Glossary/API sizing across phone, tablet, and desktop.
- `pnpm exec vitest run --config vitest.config.ts
tests\unit\search-presentation.vitest.test.ts
tests\unit\custom-components.vitest.test.ts
tests\unit\navigation-theme.vitest.test.ts` - **passed: 130 tests in 3
files** after the final sizing adjustment.
- `pnpm exec playwright test mobile-ux.spec.ts --workers=2
--reporter=list --grep 'breadcrumbs show|integration-card code
borders|secondary controls match'` - **passed: 9 tests**, checking
conventional hierarchy, 12px action padding, and matching light-theme
code borders.
- `pnpm exec playwright test mobile-ux.spec.ts
api-search-contract.spec.ts dev-glossary.spec.ts dev-grain.spec.ts
dev-layout.spec.ts dev-browse.spec.ts gallery-search-contract.spec.ts
site-search.spec.ts deployment-navigation.spec.ts
custom-components.spec.ts homepage.spec.ts ui-regressions.spec.ts
--workers=3 --reporter=list --grep 'API full-size input visual
parity|glossary toolbar|grain is fine|Dev Hub uses consistent|typography
and glossary|share content alignment|sidebar zero matches|native
Pagefind input presentation|same-deployment navigation|changed
deployment|missing deployment|samples grid hydrates|history returns
focus|localized navigation|section 08 pairs|compact editorial
rhythm|docs search survives|docs reading hierarchy|aligns the
scroll|breadcrumbs show|secondary controls match|integration-card code
borders|mobile controls and content'` - **77 passed; 8 skipped; 11
failed initially**. All failures were corrected and verified below; no
tests were disabled.
- `pnpm exec playwright test custom-components.spec.ts
dev-layout.spec.ts dev-glossary.spec.ts site-search.spec.ts --workers=2
--reporter=list --grep 'samples grid hydrates|typography and
glossary|glossary toolbar|Dev Hub uses consistent|docs search survives'`
- **passed: 16 tests; 2 intentionally skipped**, confirming corrected
disclosure, navigation, and responsive-loop behavior.
- `pnpm exec tsc --noEmit --pretty false` - **not clean: 239 existing
diagnostics**. Comparison with the prior verified baseline found 239
before and after, with no introduced diagnostics.

No local production build was run, in accordance with repository
guidance. Production search is a CI/preview check. Physical iPhone,
Android, and Safari checks were unavailable; browser emulation is not
device or accessibility certification.

### CI repairs

Correct production JSX-link underline scoping, Pagefind/catalog padding
parity, stale responsive assertions, hidden mobile-menu/sample-tag
interactions, and scroll-to-top geometry. The grain check retains strict
decoded interior pixels and all texture statistics; the prior mismatch
was only three outer-border pixels. The homepage editorial-height budget
excludes its independently changing announcement.

The updated base also had a failing dashboard-persistence test after its
documentation correctly moved the writable volume to `/home/app`.
Preserve the upstream example and correct only its two stale test
expectations. The feature branch was merged with current main, not
rebased or replaced.

Full remote production validation is tracked in [the final CI
run](https://github.com/microsoft/aspire.dev/actions/runs/38281519132).

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…e naming, and networking (#454)

Addresses gaps identified from 20K+ Discord community messages where
users had no documentation for several common AppHost scenarios.

## New pages

- **`app-host/resource-naming.mdx`** — How resource names map to env
vars (`ConnectionStrings__<name>`, `services__<name>__<endpoint>__0`),
the dash→underscore transformation (`my-service` →
`ConnectionStrings__my_service`), naming best practices (dashes
preferred, underscores valid), and resource name validation rules (links
to ASPIRE006 diagnostic).

- **`app-host/console-apps.mdx`** — Adding .NET console/worker projects
to AppHost via `AddProject`, plus links to `AddExecutable`,
`AddPythonApp`, and `AddNodeApp` for non-.NET apps. Covers wiring
service discovery on non-ASP.NET Core hosts, `BackgroundService`
patterns, `WithExplicitStart()` for interactive apps, and dashboard
console output.

- **`app-host/cors-configuration.mdx`** — When CORS is (and isn't)
needed with Aspire, ASP.NET Core Minimal API middleware setup with
`AddCors`/`UseCors`, environment-based origins, using
`WithReference(frontend)` to auto-inject the frontend URL into API CORS
config, common failure patterns (middleware ordering, preflight,
credentials), and dashboard CORS env var.

## Updated pages

- **`fundamentals/networking-overview.mdx`** — Two new sections:
- *Binding to all interfaces for LAN access* — 0.0.0.0 configuration for
ASP.NET Core projects, containers (clarifying `WithHttpEndpoint` maps
ports only; the app must also bind via `WithEnvironment`), and
executables
- *Container-to-host networking* — host gateway address platform table,
`WithReference` for automatic cross-platform host resolution,
`AddConnectionString` for existing host services, and
`KnownNetworkIdentifiers`

## Sidebar

Added all three new pages under the AppHost section in `docs.topics.ts`
with Japanese (`ja`) translations.

<!-- START COPILOT ORIGINAL PROMPT -->



<details>

<summary>Original prompt</summary>

> 
> ----
> 
> *This section details on the original issue you should resolve*
> 
> <issue_title>[Discord Feedback] App Model API gaps - CORS, console
apps, naming, networking</issue_title>
> <issue_description>## Summary
> 
> Based on analysis of 20,415 Discord messages + 147 #help threads from
the Aspire community (April 2025 - February 2026), several App Model API
features lack documentation.
> 
> ## Missing Documentation
> 
> ### 1. CORS Configuration (10+ questions)
> 
> **Current State:** Zero documentation
> 
> **Customer Quotes:**
> > "Wait.. hold on, hold on, hold on, hold on, hold on.... What? do we
need to configure cors?"
> 
> > "I seem to be having some CORS issues with a test deployment. Would
this also have to be something I configure somewhere in my project?"
> 
> **Requested Documentation:**
> - [ ] When CORS configuration is needed with Aspire
> - [ ] How to configure CORS for dev vs prod
> - [ ] Common CORS issues and solutions
> 
> ---
> 
> ### 2. Console Application Integration (17 questions)
> 
> **Customer Quotes:**
> > "if I want to hook up a Console project with Aspire, so that it can
still (maybe?) use service discovery, service defaults, etc. with Aspire
resources... is that possible?"
> 
> > "Colleague asked how to start a console app with aspire. I got it to
connect to another resource (redis) and write a kv.... but then was
wondering how to 'launch the console window' so one could interact with
Console.Readline."
> 
> **Requested Documentation:**
> - [ ] Adding Console apps to Aspire AppHost
> - [ ] Service discovery in Console apps (non-ASP.NET Core)
> - [ ] Background worker / hosted service patterns
> - [ ] Interactive console apps with stdin/stdout
> 
> ---
> 
> ### 3. Resource Naming Conventions
> 
> **Customer Quote:**
> > "How does `WithReference` treat names that have dashes? e.g.
`AddWhatever("my-service")` and then will it be like
`MY_SERVICE_[PROPERTY]`? Or `MY-SERVICE_[PROPERTY]`?"
> 
> **Requested Documentation:**
> - [ ] How resource names map to environment variables
> - [ ] Dashes → underscores transformation rules
> - [ ] Best practices for naming resources
> 
> ---
> 
> ### 4. Network Binding (0.0.0.0 / LAN Access)
> 
> **From #help thread:** "How to bind services to 0.0.0.0 for LAN
access?"
> 
> **Requested Documentation:**
> - [ ] Exposing services to external network
> - [ ] Binding to 0.0.0.0 vs localhost
> - [ ] LAN development scenarios
> 
> ---
> 
> ### 5. Container-to-Host Networking
> 
> **Customer Quote:**
> > "I'm struggling to get endpoints resolved in the context of a
container. If I use `KnownNetworkIdentifiers.LocalhostNetwork`, it
always comes back with localhost not `host.docker.internal`"
> 
> **From #help:** "Containers can't reach localhost SQL"
> 
> **Requested Documentation:**
> - [ ] `host.docker.internal` behavior
> - [ ] `KnownNetworkIdentifiers` enum usage
> - [ ] Container-to-localhost SQL Server connectivity
> 
> ---
> 
> ## Data Source
> 
> - **Discord channels:** #💫│general, #🔵│azure, #🔨│building-resources
> - **Help threads:** 147 analyzed from #🆘│help
> - **Total messages:** 20,415
> - **Date range:** April 2025 - February 2026</issue_description>
> 
> <agent_instructions>Please address this issue, while using the
`.github/skills/doc-writer/SKILL.md`. Be certain to also take into
account, related issues, pull requests, and comments that are directly
linked as well as comments.</agent_instructions>
> 
> ## Comments on the Issue (you are @copilot in this section)
> 
> <comments>
> </comments>
> 


</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes #327

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for
you](https://github.com/microsoft/aspire.dev/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Maddy Montaquila <maleger@microsoft.com>
Co-authored-by: Alistair Matthews <alistairwebdojo@live.com>
Copilot-Session: 0d21fabc-759d-45d9-b1fb-41733ff02aa0
## Summary

`Update Release Branch` currently fails on every push to `main` once a
merge into `release/X.Y` has a real conflict that the helper can't
auto-resolve (e.g. runs 38433783235 and 38436114463 on
`component-props.contracts.ts`). It stays red until someone notices and
repairs the branch by hand.

- The merge helper now exits `3` for "conflicts need human review"
(merge aborted, release untouched) instead of a generic failure.
- A new `--commit-conflicts` mode commits the merge with conflict
markers left in the unresolved files, keeping both parents, and writes
the conflicted paths to `$RELEASE_SYNC_CONFLICTS_FILE`.
- On exit `3` the workflow pushes a rolling `release-sync/X.Y` branch
and opens a **draft** PR into `release/X.Y` that lists the conflicts and
the "Create a merge commit, never squash" instructions. The run finishes
green with a warning and summary link.
- Before doing any work, the workflow checks for an open PR from
`release-sync/X.Y`. If one exists it skips the sync, so pushes to `main`
no longer repeat the same failure while a human resolves it. After the
repair merges, the next push resumes syncing.
- The app token now requests `pull-requests: write` (already granted for
`update-integration-data.yml`).

Non-conflict failures (push rejection, fatal git errors) still fail the
job as before. This is independent of #1701 (push-race retry) and #1666
(version config conflicts) and composes with them.

## Third-party links and affiliations

None

## Validation

- `bash .github/scripts/test-merge-main-into-release.sh`: all cases
pass, including new exit-code `3`, `--commit-conflicts` with conflicts,
and `--commit-conflicts` on a clean merge.
- `bash -n` on the three workflow `run` blocks (extracted from the
YAML): passed.
- `prettier --check` on the workflow: passed after `--write`.
- Dry run against the real `origin/release/17.0` and `origin/main` in a
temporary worktree: the default mode aborts with exit `3`, and
`--commit-conflicts` produces a two-parent merge listing
`src/frontend/tests/typecheck/component-props.contracts.ts` with a clean
working tree.
- Not run: the workflow end-to-end (PR creation and the skip check need
Actions with the app token).

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
## Summary

<!-- Describe what this pull request changes and why. -->

Adds a scheduled workflow that tells IndexNow search engines (Bing,
Yandex, Naver, Seznam, Yep, Amazon) about aspire.dev URLs, so new docs
are discovered quickly, especially right after a release ships.

**How it works** (`.github/workflows/indexnow.yml` +
`src/frontend/scripts/indexnow.ts`, also runnable locally with `pnpm
indexnow`)

- Every run reads the live sitemap (about 32k URLs) and compares it with
the URL list saved by the previous run. It sends **one request**
(IndexNow takes at most 10,000 URLs in one) with the removed and new
URLs first, then the next window of a rotation through the whole
sitemap: English pages, then the API reference, then localized pages.
- **Daily (06:43 UTC):** the window is 1,000 URLs. Its position is a
cursor over a stable order, so it survives pages being added or removed.
- **Release:** merging a `release/X.Y` pull request into `main` waits up
to 45 minutes for that release's "What's new" page to be live (the docs
slot swap), then starts a burst of up to 10,000 URLs per run that the
daily runs finish (about 4 runs today). After that the slow rotation
resumes. The sitemap has no `lastmod`, so the script can't tell an
updated page from an unchanged one; the burst sends all English pages
first, which is where the new and updated docs are.
- **Manual:** `workflow_dispatch` with `mode` (daily or flush), `limit`,
`release`, `dry_run` and `allow_shrink`.
- The state is a single `state.json` in the `indexnow-state` Actions
artifact (90 days). Losing it only causes a cold start that re-seeds the
known list without submitting everything.
- A failed request (a 429 included) fails the job and leaves the
progress alone, so the next run tries again. A failed flush still starts
its release pass, and a failed cold start still seeds the known list.

**What the script assumes about the site** (listed at the top of
`indexnow.ts`; everything else is in
`src/frontend/config/indexnow.json`)

- `/reference/api/` is the generated API reference, and the locale
folders in `config/locales.ts` hold the translations. Both are sent
after the English pages.
- Release X.Y is merged from a `release/X.Y` branch and publishes
`/whats-new/aspire-X-Y/` (`aspire-X` for X.0).

**No repository secret is needed.** An IndexNow key is public by design:
the key file has to be downloadable from the site root so engines can
verify ownership. The key is committed
(`src/frontend/config/indexnow.json` and
`src/frontend/public/<key>.txt`). The workflow only uses the automatic
token with `contents` and `actions` read access.

**Safety rails:** a key-file preflight (a cold start skips softly until
the key file has deployed), refusal of a sitemap that shrank by more
than 20% (`allow_shrink` overrides), state read from an artifact is
checked (and artifacts from fork runs are ignored), `--limit` is a hard
cap, and 5xx and network errors retry with back-off.

**Rollout**

1. Merge, and let the deploy publish
`https://aspire.dev/c5f794ab28dc0cb92f48bd970500daa3.txt` (until then
the first run skips).
2. Run the workflow manually with `dry_run` to see the plan.
3. The first real run seeds the state and submits the first 1,000-URL
window.
4. The next release merge triggers the burst, or dispatch `mode: flush`
with `release: X.Y`. Verify in Bing Webmaster Tools under IndexNow.

**Notes**

- IndexNow doesn't publish its rate limits, so the budgets (`release`
10,000 and `rotation` 1,000) live in `config/indexnow.json`. A test
keeps them within one request.
- A page that is new while a pass is running can be sent twice: when it
appears and when the rotation reaches it.
- The release-merge path (the `closed` pull request event) first runs on
the next release and can't be exercised before merging. The trigger
matches a merged pull request from `release/X.Y` in this repository,
which is what the 13.4, 13.5 and 13.6 content pull requests are. The
pull request that merges the release branch back is not a trigger; a
manual `flush` covers repairs.
- The job-level `concurrency` uses `queue: max`, which GitHub documents.
actionlint 1.7.12 doesn't know it yet, and the repository doesn't run
actionlint in CI.
- Follow-up: accurate `lastmod` values in the sitemap would let search
engines (Bing and Google use them to schedule crawls) and this script
tell updated pages apart.

## Third-party links and affiliations

<!--
List any third-party links added or changed by this pull request and
disclose any
material affiliation with the linked organizations, such as employment,
sponsorship, or ownership. Write "None" if this pull request doesn't add
or
change third-party links.
-->

- `https://www.indexnow.org/documentation` (referenced in a code
comment) and the `https://api.indexnow.org/indexnow` endpoint (in
`config/indexnow.json`) are the IndexNow protocol's documentation and
submission endpoint. IndexNow is an open protocol launched by Microsoft
Bing and Yandex, and aspire.dev is also a Microsoft site. This change
adds no sponsorship or other affiliation.

## Validation

<!-- List the checks you ran or explain why validation isn't needed. -->

From `src/frontend`:

- `pnpm exec vitest run --config vitest.config.ts
tests/unit/indexnow.vitest.test.ts`: passed, 83 tests.
- `pnpm test:unit`: passed, 81 files and 1,121 tests (1 skipped).
- `pnpm lint`: passed.
- `actionlint` 1.7.12 on the workflow, with the `queue: max` line
removed because actionlint doesn't know it: passed.
- Mutation checks: nine deliberate breakages of the behavior that
matters (a flush sending its new URLs ahead of its window, a failed
flush forgetting them, no shrink guard, a failed flush or cold start not
saving state, retrying client errors, no one-request clamp, state
entries not checked against the host, a fork's release pull request
accepted, a cold start not skipping while the key is missing) each fail
at least one test.
- Real data: the planner against the live sitemap (32,336 URLs) runs a
release burst in 4 requests (10,000, 10,000, 10,000 and 2,336 URLs),
covers every URL once, and sends all 611 English docs first (the 13.6
What's new page is at position 602 of day 1).
- The workflow's submit step run under bash with a stubbed `pnpm` for
the `schedule`, `pull_request` and `workflow_dispatch` triggers builds
the expected arguments.
- The real CLI against the live site as dry runs: a daily run plans
1,000 URLs, `--mode flush --release 13.6` plans 10,000, neither writes
state, and an invalid `--limit` exits 1. The 404 warning for the key
file is expected until it deploys.

Not run: `pnpm build` (left to CI), a real IndexNow submission (the key
file isn't deployed yet) and the pull-request-triggered path (first
exercised by the next release merge).

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
… docs (#1892)

## Summary

<!-- Describe what this pull request changes and why. -->

Removes packages that are deprecated, retired, or superseded from the
integration catalog, API reference data, and docs, so the gallery,
`/reference/api/`, and the integrations section stop advertising them.
NuGet deprecation flags alone missed most of these, so the audit also
used package READMEs and nuspecs, the Aspire CLI's hidden-package list,
Community Toolkit release notes, and the Toolkit source tree.

| Package | Why it's removed |
| --- | --- |
| `CommunityToolkit.Aspire.Hosting.Bun` | Deprecated on NuGet and in
Toolkit 13.4.0, removed from the Toolkit in 13.6.0. Bun support now
ships in `Aspire.Hosting.JavaScript`. |
| `Aspire.Hosting.GitHub.Models` | GitHub Models was retired on July 30,
2026. The package README says it's deprecated, and the Aspire CLI hides
it from `aspire add`. |
| `CommunityToolkit.Aspire.Hosting.Minio`,
`CommunityToolkit.Aspire.Minio.Client` | Deprecated in Toolkit 13.3.0,
removed in 13.6.0. |
| `CommunityToolkit.Aspire.Hosting.Python.Extensions` | Deprecated in
Toolkit 13.0.0. Use `Aspire.Hosting.Python`. |
| `CommunityToolkit.Aspire.Hosting.Dapr.AzureRedis` | Orphaned and
superseded by `Azure.Dapr` and `Azure.Dapr.Redis`. It has no source in
the Toolkit repository. |
| `CommunityToolkit.Aspire.Hosting.Java`,
`CommunityToolkit.Aspire.Hosting.Rust` | Deprecated in Toolkit 13.6.0 in
favor of the first-party `Aspire.Hosting.Java` and
`Aspire.Hosting.Rust`. |

**What changed** (all under `src/frontend/`)

- `scripts/update-integrations.ts`: added each package to
`EXCLUDED_PACKAGES`. The updater falls back to the newest non-deprecated
version, which is how Bun came back at 13.3.0, so the exclusion has to
be explicit.
- `src/data/aspire-integrations.json` (from 217 to 209 entries) and
`src/data/integration-docs.json` (from 165 to 160 mappings): removed the
entries.
- `src/data/pkgs/` and `src/data/ts-modules/`: deleted the C# and
TypeScript API data for the removed packages (14 files).
`src/data/twoslash/aspire.d.ts` is regenerated.
- `src/content/docs/integrations/ai/github-models/`: deleted the three
GitHub Models pages (get started, host, connect) and their sidebar group
in `config/sidebar/integrations.topics.ts`.
- `config/redirects.mjs`: the old GitHub Models URLs (the section root,
get started, host, connect, and the legacy `-client` route) now redirect
to the matching Microsoft Foundry pages instead of returning 404.
- `src/content/docs/whats-new/`: fixed links to the removed pages. The
13.6 note no longer links to the deleted migration guide, and the 13.2
connection-properties example drops "Connect to GitHub Models". The 9.4
and 9.5 notes linked to absolute `aspire.dev` URLs that would now land
on a Foundry page, so those links are removed.
- `src/assets/icons/`: deleted `github-icon.png` (only the removed pages
used it), plus `github-light-icon.png` and `minio-icon.png`, which the
home-page rail change orphaned.
- `HomeIntegrationRail.astro`: three tiles (GitHub, MinIO, Bun) no
longer matched any gallery entry, so they now show Apache Kafka,
ClickHouse, and PowerShell. That keeps 12 tiles per lane and 36 unique
names.
- The Bun, Python, Java, and Rust pages stay. They document the
first-party replacements and carry the Toolkit migration guidance.

**Review notes**

- Deleting the GitHub Models pages also removes the "Migrate Aspire apps
from GitHub Models" guide. The 13.5 and 13.6 what's-new notes still
announce the retirement and link to the Foundry integration. Say if
you'd rather fold a short migration section into the Foundry docs.
- `Dapr.AzureRedis`, Toolkit `Java`, and Toolkit `Rust` aren't flagged
on NuGet. Java and Rust are announced as deprecated but still publish
betas, so drop them from this PR if you'd rather wait for the Toolkit to
remove them.
- `rust-host.mdx` still points to the Toolkit Rust package for Bacon
support (`AddBaconApp`). That stays accurate while the package is on
NuGet.
- The home-page tile swap is a judgment call. Say if you'd prefer
different integrations.
- Checked and kept because they aren't deprecated: the Elasticsearch
packages (partner-maintained by Elastic), the Toolkit Dapr packages and
EF Core SQLite (preview-only since their last stable),
`Aspire.Hosting.DocumentDB`, and the 13.6.0 preview packages.

## Third-party links and affiliations

<!--
List any third-party links added or changed by this pull request and
disclose any
material affiliation with the linked organizations, such as employment,
sponsorship, or ownership. Write "None" if this pull request doesn't add
or
change third-party links.
-->

None.

## Validation

<!-- List the checks you ran or explain why validation isn't needed. -->

Run from `src/frontend/`:

- `pnpm test:unit`: passed (81 files, 1,121 tests, 1 skipped). Covers
the redirect, Astro config, resource catalog, API reference, TypeScript
API, Twoslash, and updater tests.
- `pnpm test:unit:structured-data`: passed (5 files, 99 tests).
- `pnpm validate:api-data`: passed (209 catalog package identities
reconciled, 140 TypeScript modules matched to C# provenance).
- `node scripts/generate-twoslash-types.ts`: succeeded and produced no
diff against the committed `aspire.d.ts`.
- `pnpm exec eslint config/redirects.mjs
config/sidebar/integrations.topics.ts --max-warnings 0`: passed.
- A script check that every home-page rail tile's search term still
matches at least one catalog entry: 36 tiles, 36 unique names, 0 dead
tiles.
- A script check of the docs removal: all 182 redirects resolve to an
existing page or another redirect, every integrations sidebar slug has a
page, and no docs page links internally to the removed `github-models`
URLs.

Not run locally: `pnpm build` (which runs the
`starlight-links-validator` link check) and the Playwright e2e suite. CI
covers them.

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2c9eea84-ba1a-4852-88a7-886ceddb7f4f
…erator (#1895)

## Summary

`Particular.Aspire.Hosting.ServicePlatform` (added in #1380) was removed
by the automated refresh in #1389, because `update-integrations.ts` only
searches for `owner:aspire`, `Aspire.Hosting.` and
`CommunityToolkit.Aspire`, and only keeps IDs starting with `aspire.` or
`communitytoolkit.aspire`. Re-adding the JSON entry by hand (see #1894)
would be reverted again on the next run.

This PR:

- Adds an explicit `THIRD_PARTY_PACKAGES` allow list to
`update-integrations.ts`, fetched from nuget.org by exact `packageid:`.
- Lets allow-listed IDs through `filterAndTransform` (still requires
verified and non-deprecated).
- Restores the catalog entry with current NuGet metadata (1.1.0).
- Adds unit tests for the allow list. The existing
`integration-docs.json` mapping keeps the card linking to
https://docs.particular.net/platform/aspire/; the package link continues
to go to NuGet.

Supersedes #1894.

## Third-party links and affiliations

None added beyond those already in #1380.

## Validation

`npx vitest run --config vitest.config.ts
tests/unit/update-integrations.vitest.test.ts` (48 passed). Confirmed
the nuget.org `packageid:` query returns the package as verified and
listed.

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <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

Missing-property access aborts API generation, and duplicate constants prevent TypeScript contract checking.

2 open findings
What changed in this PR

Documents the dashboard’s Spans overflow tooltip. The diff also expands integration catalog tooling and removes older integration documentation and generated API data.

Changes:

  • Explains the +N resource tooltip and reorders resource-naming examples.
  • Adds third-party catalog support and API-generation exclusions.
  • Removes selected integration data and redirects GitHub Models documentation to Microsoft Foundry.
File Description
src/​tools/​PackageJsonGenerator/​generate-package-json.ps1 Filters API-reference exclusions.
src/​frontend/​tests/​unit/​validate-generated-api-data.vitest.test.ts Tests excluded catalog entries.
src/​frontend/​tests/​unit/​update-integrations.vitest.test.ts Tests third-party catalog support.
src/​frontend/​tests/​typecheck/​component-props.contracts.ts Adds ReadableText contracts.
src/​frontend/​src/​data/​twoslash/​aspire.d.ts Removes corresponding API declarations.
src/​frontend/​src/​data/​ts-modules/​CommunityToolkit.Aspire.Hosting.Rust.13.5.0.json Removes Rust TypeScript metadata.
src/​frontend/​src/​data/​ts-modules/​CommunityToolkit.Aspire.Hosting.Python.Extensions.13.5.0.json Removes Python extensions TypeScript metadata.
src/​frontend/​src/​data/​ts-modules/​CommunityToolkit.Aspire.Hosting.Minio.13.5.0.json Removes MinIO TypeScript metadata.
src/​frontend/​src/​data/​ts-modules/​CommunityToolkit.Aspire.Hosting.Java.13.5.0.json Removes Java TypeScript metadata.
src/​frontend/​src/​data/​ts-modules/​CommunityToolkit.Aspire.Hosting.Bun.13.3.0.json Removes Bun TypeScript metadata.
src/​frontend/​src/​data/​ts-modules/​Aspire.Hosting.GitHub.Models.13.5.4.json Removes GitHub Models TypeScript metadata.
src/​frontend/​src/​data/​pkgs/​CommunityToolkit.Aspire.Minio.Client.13.5.0.json Removes MinIO client API metadata.
src/​frontend/​src/​data/​pkgs/​CommunityToolkit.Aspire.Hosting.Rust.13.5.0.json Removes Rust API metadata.
src/​frontend/​src/​data/​pkgs/​CommunityToolkit.Aspire.Hosting.Python.Extensions.13.5.0.json Removes Python extensions API metadata.
src/​frontend/​src/​data/​pkgs/​CommunityToolkit.Aspire.Hosting.Minio.13.5.0.json Removes MinIO hosting API metadata.
src/​frontend/​src/​data/​pkgs/​CommunityToolkit.Aspire.Hosting.Dapr.AzureRedis.9.1.1-beta.197.json Removes Dapr Azure Redis API metadata.
src/​frontend/​src/​data/​pkgs/​CommunityToolkit.Aspire.Hosting.Bun.13.3.0.json Removes Bun API metadata.
src/​frontend/​src/​data/​integration-docs.json Removes selected package mappings.
src/​frontend/​src/​data/​aspire-integrations.json Updates catalog membership.
src/​frontend/​src/​content/​docs/​whats-new/​aspire-9-5.mdx Removes GitHub Models documentation link.
src/​frontend/​src/​content/​docs/​whats-new/​aspire-9-4.mdx Unlinks GitHub Models mention.
src/​frontend/​src/​content/​docs/​whats-new/​aspire-13-6.mdx Removes migration-guide link.
src/​frontend/​src/​content/​docs/​whats-new/​aspire-13-2.mdx Removes GitHub Models connection link.
src/​frontend/​src/​content/​docs/​integrations/​ai/​github-models/​github-models-host.mdx Deletes hosting reference.
src/​frontend/​src/​content/​docs/​integrations/​ai/​github-models/​github-models-get-started.mdx Deletes migration guide.
src/​frontend/​src/​content/​docs/​integrations/​ai/​github-models/​github-models-connect.mdx Deletes connection guide.
src/​frontend/​src/​content/​docs/​dashboard/​explore.mdx Explains Spans overflow tooltip.
src/​frontend/​src/​content/​docs/​app-host/​resource-naming.mdx Places C# examples first.
src/​frontend/​src/​components/​home/​HomeIntegrationRail.astro Refreshes featured integrations.
src/​frontend/​scripts/​validate-generated-api-data.ts Allows API-reference exclusions.
src/​frontend/​scripts/​update-integrations.ts Adds third-party discovery and download parsing.
src/​frontend/​scripts/​update-integration-data.ps1 Skips excluded packages in version tracking.
src/​frontend/​config/​sidebar/​integrations.topics.ts Removes GitHub Models navigation.
src/​frontend/​config/​redirects.mjs Redirects GitHub Models pages to Foundry.

🧠 Review effort: Balanced


💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment on lines +80 to +84
const validReadableTextProps = { text: 'RedisResource.withModule' } satisfies PropsOf<typeof ReadableText>;
void validReadableTextProps;
// @ts-expect-error Identifier content is required and must remain a string.
const invalidReadableTextProps = { text: 123 } satisfies PropsOf<typeof ReadableText>;
void invalidReadableTextProps;
@(Get-Content $integrationsFile -Raw | ConvertFrom-Json)
# Entries marked `"apiReference": false` (third-party packages) are not documented here.
@(Get-Content $integrationsFile -Raw | ConvertFrom-Json |
Where-Object { $_.apiReference -ne $false })
@IEvangelist

Copy link
Copy Markdown
Member

Project docs accuracy review [partial - phase A: 22 of 22 claims evaluated; phase B: browser pass complete, product runtime unexecuted]

Reviewed PR #1876 at bb8065610cc1ee4139e063e4969e628e1a8dd424, against release/17.0 base 76c496a5c02be2ca4adde68a9996dd627f4311fd. This is a top-level conversation report, not a formal approval or request for changes. This Project stage is recorded once for the PR lifetime.

Scope: all 39 changed files, not only the tooltip sentence: redirects/sidebar; catalog updater and API-generation/validation scripts; homepage rail; resource-naming tab reordering; dashboard prose; three deleted GitHub Models guides; four historical release-note edits; integration catalog/mappings; eight deleted C# API files, six deleted TypeScript modules and declaration removals; contracts and unit tests. Implementation correctness belongs to the subsequent code report.

Blind browser summary: six affected narrative pages, five retired-guide redirect chains, retained anchored links, homepage/gallery changes, both API indexes and 14 removed package landing routes exercised; 0 critical issues established, 4 warning categories. Remaining validation: no matching Aspire 17.0 runtime was used to execute the real tooltip or resource-naming samples; ClickHouse image decoding was inconclusive. This partial stage is recorded once and will not automatically rerun on later commits.

Phase A - Claim verification

22 deduplicated claims evaluated: 21 verified, 0 verified-with-nuance, 1 unverifiable, 0 contradicted. The new Spans tooltip description matches the release source. All seven C#/TypeScript blocks in resource-naming are identical to the base as an unordered multiset; only tab order changed. The moved C# API calls were nevertheless checked.

Sources were queried read-only at these pinned commits:

Owning source Applicable ref Commit
microsoft/aspire release/17.0 55867ce9d33c8800e6c7278f7edc5e88e0f6b839
CommunityToolkit/Aspire main fallback: release/17.0 does not exist (branch API 404) 72da68ca3884e8e7483540053dc4ac0cc1240d06
Particular/Particular.Aspire.Hosting.ServicePlatform Version tag 1.1.0, dereferenced to commit 389982a2fa1f4834cfc3c5facb2c5f175dae33e5
ClickHouse/ClickHouse.Aspire Existing package 13.5.3 source commit cabd9edc0899714407e6ad81dc4954eb01302af0

The Toolkit fallback cannot establish release/17.0-specific compatibility. No newly changed Azure SDK type or provisioning signature required Azure/azure-sdk-for-net.

Unverifiable snapshot, not an asserted defect: src/frontend/src/data/aspire-integrations.json:3823 records "downloads": 5608 for Particular. Source-controlled product code cannot establish the historical NuGet counter when this catalog was generated; today's advancing counter is not evidence that the earlier snapshot was wrong. No change is requested on that basis.

Verified claims and pinned evidence (A01-A21)

Repeated calls and equivalent redirect destinations are deduplicated below. Local route evidence refers to this PR's exact head, not the live public website.

ID Changed location and claim Evidence
A01 dashboard/explore.mdx:419: overflow tags become +N Traces.razor:147-159: FluentOverflow and OverflowCount.
A02 Same line: hover reveals remaining resources Traces.razor:161-175: tooltip anchors to the more button and renders ItemsOverflow.
A03 Same line: tooltip includes span counts Traces.razor:226-232: resource name plus TotalSpans.
A04 app-host/resource-naming.mdx:39,104,197: CreateBuilder(args) DistributedApplication.cs:166-174.
A05 Lines 41,201: AddRedis("cache") RedisBuilderExtensions.cs:64-68: remaining arguments optional.
A06 Lines 43,107,109,204: AddProject<Projects.*>(name) ProjectResourceBuilderExtensions.cs:68-74; the page already states the project-reference prerequisite.
A07 Lines 44,110,205-207: connection-resource WithReference(...) ResourceBuilderExtensions.cs:1113: connection-string-resource overload.
A08 Line 111: service-resource WithReference(catalog) ResourceBuilderExtensions.cs:1265: service-discovery-resource overload.
A09 Lines 106,199: AddPostgres("postgres") PostgresBuilderExtensions.cs:48-52.
A10 Lines 106,200: .AddDatabase("app-db") PostgresBuilderExtensions.cs:148-154.
A11 Line 202: AddRabbitMQ("message-bus") RabbitMQBuilderExtensions.cs:31-35.
A12 Lines 46,113,209: Build() returns the application DistributedApplicationBuilder.cs:872.
A13 Same lines: the built application exposes Run() DistributedApplication.cs:601-604.
A14 config/redirects.mjs:147-148, release-note link: Foundry get-started destination azure-ai-foundry-get-started.mdx exists at head; Aspire.Hosting.Foundry.csproj identifies the product integration.
A15 config/redirects.mjs:149: Foundry hosting destination azure-ai-foundry-host.mdx exists at head.
A16 config/redirects.mjs:68,150: Foundry connection destination azure-ai-foundry-connect.mdx exists at head.
A17 Homepage rail offers Apache Kafka Aspire.Hosting.Kafka.csproj:6-9; kafka matches three current catalog entries.
A18 Homepage rail offers ClickHouse Owning Aspire.Hosting.ClickHouse.csproj:9-11 and ClickHouseBuilderExtensions.cs:35-51; matching catalog entry retained.
A19 Homepage rail offers PowerShell CommunityToolkit.Aspire.Hosting.PowerShell.csproj:4-6; matching catalog entry retained.
A20 Catalog adds Particular.Aspire.Hosting.ServicePlatform version 1.1.0 Owning version tag resolves to 389982a2...; the version is also listed by NuGet. This is a fixed package snapshot, not a claim that it is today's latest version.
A21 Catalog description names ServiceControl and ServicePulse Exact match in owning Particular.Aspire.Hosting.ServicePlatform.csproj:7 and platform builder at lines 19-23.

Removal audit: all eight removed packages are absent consistently from the catalog and their C#/TypeScript generated output sets. GitHub Models guide/sidebar links and corresponding declarations are removed together; the former guide routes have explicit Foundry destinations. Toolkit Java, Python.Extensions and Rust still exist on the pinned Toolkit fallback, including Toolkit-only AddBaconApp; catalog exclusion is therefore treated as site curation, not as evidence that these APIs no longer exist. Historical claims in deleted guides and unchanged release-note paragraphs were not re-certified. No new hard-coded current Aspire version requiring a placeholder was introduced.

Phase B - Independent blind doc-tester

Phase C reconciliation (separate from the frozen blind report): Warning 2 is explained by the site's existing, configured TypeScript-first transformation: astro.config.mjs:85 registers remarkTypeScriptFirstAppHostTabs, which moves TypeScript first in aspire-lang groups. The MDX reorder therefore does not change the rendered language order. This is not a new regression. The independent tester's original wording is preserved unchanged below; its source blindness was maintained until both artifacts were frozen.

Documentation Test Report

Focus Area: Independent Phase B, microsoft/aspire.dev PR #1876
Date: 2026-10-30
Tester: doc-tester agent
Status: FROZEN — browser/navigation pass complete; product-runtime validation partial.

Served URL: http://127.0.0.1:43876/
Verified HEAD: bb8065610cc1ee4139e063e4969e628e1a8dd424, detached
Comparison base: 76c496a5c02be2ca4adde68a9996dd627f4311fd, release/17.0

Summary

Category Passed Failed Warnings
Content Accuracy 0 0 1
Code Examples 0 0 1
CLI Commands 0 0 1
Links 10 0 1

Accuracy/example/CLI warnings denote unexecuted product-runtime validation, not three discovered defects. Link passes count five redirect chains, two retained anchored links, and three homepage integration destinations. Removed API landing pages are reported separately below, not counted as unexpected link failures. Rendering observations do not establish Aspire runtime accuracy.

Critical Issues

None established by this independent browser pass. This is not a full runtime accuracy sign-off.

Warnings

Warning 1: Product behavior and examples were not executed

Location: /dashboard/explore/#traces-page and /app-host/resource-naming/ examples.

Issue: The documentation renders, but no Aspire 17.0 application, real dashboard trace list, overflow tooltip, resource-name configuration, C# compilation, or TypeScript AppHost execution was tested. The rendered +N is documentation text, not an interactive dashboard control. No installed CLI version was used as evidence for 17.0.

Suggestion: Separately validate the actual overflow tooltip and samples with a matching product runtime. Do not treat this report as that validation.

Warning 2: C#-first source reorder is not the observed rendered order

Location: All three example tab groups on /app-host/resource-naming/.

Issue: The scope diff places C# before TypeScript. The browser displayed TypeScript, C# in every group, including after clearing local storage and in a new JavaScript-disabled browser context. C# and TypeScript selections nevertheless worked, synchronized across all three groups, displayed their matching panels, and TypeScript selection survived reload.

Suggestion: Confirm whether a documentation-site transformation intentionally controls final tab order. This is an observed discrepancy with the source reorder, not an established functional regression; implementation was deliberately not inspected.

Warning 3: Removed API landing URLs now return 404

Location: The 14 API landing routes listed under Passed Checks.

Issue: Retired package entries are absent from both live API indexes, and their former landing URLs display Page not found | Aspire, HTTP 404. There are no observed redirects for these API URLs, unlike the retired narrative GitHub Models documentation.

Suggestion: Decide explicitly whether dropping historical API deep links is intended, or whether archival/deprecation landing pages are desirable. These removals are in scope and are not classified as unexpected failures.

Warning 4: Development-environment limitations

Issue: Initial Vite dependency optimization produced 504 Outdated Optimize Dep errors and navigation interruptions. A fresh-cache server restart and separate browser tabs allowed completion. Direct lightweight serving produced /api/live/ and /api/live/stream/ 404s with live updates disabled; these are not the removed package API routes. The footer displayed stale SHA 105c108, so it was not used for checkout identification. Git HEAD and the server's command/path were checked independently.

Apache Kafka and PowerShell rail icons loaded successfully after scrolling into view. ClickHouse's asset reported natural width 592, but complete image decoding was not established: the animated/offscreen lazy image remained incomplete, and a final decode attempt was stopped after 60 seconds. No broken-image defect is asserted. Pointer clicks timed out on moving/clipped rail items; the visible pause control enabled Kafka/PowerShell pointer navigation, and ClickHouse keyboard activation succeeded.

Passed Checks

Documentation routes and changed sections

  • /dashboard/explore/: loaded successfully. The Traces page section rendered: “Spans: The resources involved in the request. When there are more resource tags than fit in the column, the extra tags are summarized as +N — hover over the +N indicator to see the remaining resources and their span counts in a tooltip.” No broken completed images were observed on this page. The explanation identifies both the hover target and the expected resource/span-count content clearly.
  • /app-host/resource-naming/: loaded successfully. All three groups contained readable C# and TypeScript examples. Clicking the first C# tab selected C# in all three groups; selecting TypeScript did likewise and exposed all three corresponding TypeScript panels. Reload retained TypeScript. Final tab ordering is qualified in Warning 2.
  • /whats-new/aspire-13-2/: HTTP 200. Under Connection property suffix, the property-catalog sentence retained Azure Cosmos DB and SQL Server examples and no GitHub Models link. Both remaining local links were exercised:
    • /integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-connect/#connection-properties: HTTP 200, exactly one matching anchor.
    • /integrations/databases/sql-server/sql-server-connect/#connection-properties: HTTP 200, exactly one matching anchor.
  • /whats-new/aspire-13-6/: HTTP 200. Under Integration updates, “GitHub Models integration removed” retained the retirement/deprecation explanation and the Microsoft Foundry migration link; the removed migration-guide link was absent.
  • /whats-new/aspire-9-4/: HTTP 200. Under GitHub Models integration, “The GitHub Models integration provides:” remained readable as plain text; the removed integration documentation link was absent.
  • /whats-new/aspire-9-5/: HTTP 200. Under GitHub Models and Azure AI Foundry typed catalogs, the “For more information, see:” list retained Azure AI Foundry and no GitHub Models documentation link.
  • Browser inspection found no /github-models/ links in the main content of any of these four release-note pages. Historical claims/examples themselves were not product-validated.

Retired narrative-page redirects

Each chain was observed through real browser navigation: one HTTP 301 followed by HTTP 200 with a matching Foundry page title/heading.

Requested old route Resolved destination
/integrations/ai/github-models/ /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/
/integrations/ai/github-models/github-models-get-started/ /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/
/integrations/ai/github-models/github-models-host/ /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/
/integrations/ai/github-models/github-models-connect/ /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/
/integrations/ai/github-models/github-models-client/ /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/

The actual diff contains no changed MinIO redirect. No unrelated legacy MinIO narrative routes were tested. The kickoff's hypothetical /integrations/ai/microsoft-foundry/ destination was not assumed.

Homepage integration rail and gallery

  • /: rendered accessible rail links Explore Apache Kafka integrations, Explore ClickHouse integrations, and Explore PowerShell integrations with the corresponding gallery-query URLs.
  • After using Pause integration animation, Apache Kafka and PowerShell links were activated by ordinary pointer clicks. ClickHouse was activated by focusing its link and pressing Enter.
  • /integrations/gallery/?search=kafka: displayed two results, including Aspire.Hosting.Kafka and CommunityToolkit.Aspire.Hosting.RedPanda.
  • /integrations/gallery/?search=powershell: displayed one result, CommunityToolkit.Aspire.Hosting.PowerShell.
  • /integrations/gallery/?search=clickhouse: HTTP 200, displayed one result, Aspire.Hosting.ClickHouse.
  • /integrations/gallery/?search=github: HTTP 200, displayed No matching integrations, 0 of 153.
  • /integrations/gallery/?search=minio: HTTP 200, displayed No matching integrations, 0 of 153. This is the affected package catalog, not an unrelated legacy redirect.
  • The scope was the actual replacements GitHub → Apache Kafka, MinIO → ClickHouse, and Bun → PowerShell. No Python icon or .NET/JavaScript replacement was assumed.

API indexes and removed package routes

  • /reference/api/csharp/: HTTP 200; rendered 178 packages. Exact retired-package landing links were absent.
  • /reference/api/typescript/: HTTP 200; rendered 140 modules. Exact retired-module landing links were absent. Similar live names such as JavaScript.Extensions and RustFs were not misclassified as the removed Java and Rust packages.

Each of these C# landing routes was navigated and returned HTTP 404:

  1. /reference/api/csharp/aspire.hosting.github.models/
  2. /reference/api/csharp/communitytoolkit.aspire.hosting.bun/
  3. /reference/api/csharp/communitytoolkit.aspire.hosting.dapr.azureredis/
  4. /reference/api/csharp/communitytoolkit.aspire.hosting.java/
  5. /reference/api/csharp/communitytoolkit.aspire.hosting.minio/
  6. /reference/api/csharp/communitytoolkit.aspire.hosting.python.extensions/
  7. /reference/api/csharp/communitytoolkit.aspire.hosting.rust/
  8. /reference/api/csharp/communitytoolkit.aspire.minio.client/

Each of these TypeScript landing routes was navigated and returned HTTP 404:

  1. /reference/api/typescript/aspire.hosting.github.models/
  2. /reference/api/typescript/communitytoolkit.aspire.hosting.bun/
  3. /reference/api/typescript/communitytoolkit.aspire.hosting.java/
  4. /reference/api/typescript/communitytoolkit.aspire.hosting.minio/
  5. /reference/api/typescript/communitytoolkit.aspire.hosting.python.extensions/
  6. /reference/api/typescript/communitytoolkit.aspire.hosting.rust/

Recommendations

  1. Priority fixes: None demonstrated as a blocking documentation defect by this browser pass.
  2. Documentation gaps: Confirm the desired rendered tab order and the historical API deep-link retirement policy.
  3. Product issues: None established. Validate the real Traces overflow tooltip and resource-naming samples with a matching Aspire runtime before making runtime-accuracy claims.

Knowledge Gaps

  • No product-source, product-test, parent-finding, or external implementation knowledge was used. Only the documentation PR diff was read for scope; rendered content and browser behavior supplied the test evidence.
  • The new tooltip explanation was understandable without filling in missing product behavior, but the tooltip itself remains unverified.
  • No documentation teaching gap was demonstrated by the changed prose alone. Existing release-note claims, package availability, migration completeness, cloud prerequisites, and example execution remain outside the established evidence.

Execution Limits and Remaining Scope

  • Invoked doc-tester and playwright-cli; every browser interaction used playwright-cli, including its run-code facility.
  • Bun was absent from PATH and the usual local user path. pnpm was not initially on PATH. The existing-node fallback first failed with MODULE_NOT_FOUND, establishing that frontend dependencies were genuinely missing.
  • Focused restore: npx --yes pnpm@11.9.0 --dir .\src\frontend install --frozen-lockfile — succeeded, using the existing package cache; no global installation.
  • Root delegation attempt: npx --yes pnpm@11.9.0 run dev -- --host 127.0.0.1 --port 4321 — failed because the extra separator reached Astro as an invalid command. Port 4321 already served another process; its briefly opened homepage was excluded from PR evidence and that process was not stopped.
  • Direct root Astro attempt with --root .\src\frontend — failed because Lunaria expected frontend-relative working-directory configuration.
  • Successful fallback, run from src\frontend: node .\node_modules\astro\bin\astro.mjs dev --host 127.0.0.1 --port 43876; then restarted with --force to clear the content cache. This is a lightweight development server, not the requested unavailable Bun command and not a production build.
  • No production build, Aspire orchestration, runtime sample project, package-installation example, cloud deployment, external-link audit, exhaustive page-wide link audit, localization audit, mobile/theme visual matrix, individual API member-page crawl, or regenerated-data semantic validation was performed.
  • No microsoft/aspire, CommunityToolkit/Aspire, Azure implementation source, or product tests were inspected. No parent findings were read. No GitHub review/comment, push, branch switch, fix, or new app session occurred.

Cleanup

  • Both owned development-server runs were stopped. The final own listener was PID 2972 on port 43876; a subsequent Get-NetTCPConnection -LocalPort 43876 -State Listen check found no listener.
  • The owned browser session pr1876-phaseb was closed. An unfinished image-decode helper was stopped.
  • Restored automatically generated tracked icon-cache files and the tracked root lockfile to the exact PR head. Stat-only markers were refreshed only after checking that the affected file blob hashes already matched HEAD.
  • Final git status --short was empty; both staged and unstaged git diff --exit-code checks passed. HEAD remained bb8065610cc1ee4139e063e4969e628e1a8dd424.
  • Dependency directories remain available for the parent's focused unit run. Browser snapshots, console captures, this frozen report, and pr1876-phaseb-server.log are confined to this session's files directory. Ignored development/dependency caches created by serving/restoring remain in their normal repository locations.

@IEvangelist

Copy link
Copy Markdown
Member

Project code review

Reviewed all 10 applicable code/config/component/test files in PR #1876 at bb8065610cc1ee4139e063e4969e628e1a8dd424, against release/17.0 base 76c496a5c02be2ca4adde68a9996dd627f4311fd, applying .agents/skills/code-review/SKILL.md. This is not a docs-only change. The docs accuracy report was posted first. This is a top-level conversation report, not a formal approval or request for changes, and records the Project code stage once for this PR's lifetime.

No additional high-confidence findings beyond the two already reported. Both existing findings still reproduce at the inspected head; this is not a clean bill of health. I have linked the existing threads rather than creating duplicate findings or inline comments.

High - existing findings confirmed, not reposted

Existing finding Current evidence
Duplicate ReadableText contract declarations src/frontend/tests/typecheck/component-props.contracts.ts:80,86: an isolated TypeScript compiler diagnostic comparison produces TS2451 twice at head, versus zero matching redeclaration diagnostics at base. The intentionally invalid prop cases have error directives, but the duplicate valid declarations are unsuppressed.
Missing apiReference guard under PowerShell strict mode src/tools/PackageJsonGenerator/generate-package-json.ps1:112: executing only the new predicate against the actual first catalog object under Set-StrictMode -Version Latest throws "The property 'apiReference' cannot be found on this object." The base's unfiltered catalog read accepts the same object. This was reproduced without running the mutating package generator or restoring any NuGet packages.

Scope checked

Changed surface Review coverage
config/redirects.mjs, config/sidebar/integrations.topics.ts All five former GitHub Models entry routes, destination existence, removal of dead sidebar entries. Actual route experience belongs to the preceding blind docs report.
scripts/update-integrations.ts Exact third-party allowlist; case-insensitive filtering; verified/deprecated package gates; registration path and release reconciliation; apiReference: false propagation; HTML download parser; warning/fallback path; external documentation mapping retained.
scripts/update-integration-data.ps1 Property-existence guard and excluded-package handling in old/new version maps; downstream regeneration trigger.
scripts/validate-generated-api-data.ts Excluded-catalog handling while retaining validation of generated files and current package/module provenance.
src/components/home/HomeIntegrationRail.astro Kafka/ClickHouse/PowerShell assets and catalog search matches; existing localized links, accessible names, duplicate-lane tab exclusion, motion controls and responsive code remain unchanged. No remaining source imports reference the three deleted icon assets.
tests/typecheck/component-props.contracts.ts Both valid/invalid added contracts and the pre-existing adjacent declarations; base-controlled diagnostic reproduction above.
tests/unit/update-integrations.vitest.test.ts, tests/unit/validate-generated-api-data.vitest.test.ts Third-party inclusion/rejection, generation exclusion, parser totals/no-result case, external docs mapping, and excluded packages without API output.
src/tools/PackageJsonGenerator/generate-package-json.ps1 Strict-mode catalog load and its use for default/selective generation and version lookup; failure confirmed above.

Because generator behavior changed, generated data was included rather than blanket-excluded: all eight removed catalog packages are also absent from their generated C#/TypeScript output sets; all deleted package/module JSON identities and removed declarations were inventoried. The actual surviving catalog/API/declaration set passes semantic validation. This does not certify every historical deleted API, nor assert that removed Toolkit packages cease to exist.

Test coverage and validation

  • Focused unit tests: pnpm --dir src\frontend exec vitest run --config vitest.config.ts tests/unit/update-integrations.vitest.test.ts tests/unit/validate-generated-api-data.vitest.test.ts tests/unit/redirects.vitest.test.ts tests/unit/ts-api-route-catalog.vitest.test.ts tests/unit/twoslash-types-generator.vitest.test.ts --maxWorkers=2 - passed: 5 files, 94 tests; 1 skipped.
  • Actual generated data: pnpm --dir src\frontend exec tsx scripts/validate-generated-api-data.ts - passed: 210 catalog identities, 140 TypeScript modules matched to C# provenance, 74 DTO shapes and 2,867 handle inheritance chains. The validator's attribute comparison uses HEAD; the separate removal inventory supplies the base-to-head deletion check.
  • PowerShell: both changed scripts parse with zero syntax errors. Syntax success does not negate the reproduced strict-mode runtime failure.
  • Type contracts: the isolated compiler comparison above confirms the existing regression. This was not a full project-wide Astro/TypeScript check.
  • Desktop/tablet/mobile and axe: existing homepage.spec.ts covers rail motion controls, reduced motion, duplicate-lane tab exclusion, icon containment, theming and responsive behavior; wcag-aa.spec.ts audits / with axe-core. The PR's CI run is successful at this exact head, including all six desktop/tablet/mobile shards and frontend validation/build. Those are CI results, not claims of a local rerun.
  • Remaining local validation: no full production build, full e2e/axe rerun, full twoslash-block audit, live NuGet generation/publishing, or full project typecheck was run. The two existing failures are not caught by the selected passing unit tests; keep the existing threads open and add focused regression coverage with their fixes.

No fixes, source-branch edits/pushes, merges, formal approvals, or formal change requests were made.

David Pine (IEvangelist) pushed a commit that referenced this pull request Nov 1, 2026
## Summary

Fixes seven broken internal links in the English docs. Every locale
falls back to these pages, so each broken link appears on all 15
locales. The links validator didn't flag them because it never inspects
these two kinds of link:

- `starlight-links-validator` runs with `errorOnRelativeLinks: false`,
so it skips `./` and `../` links entirely.
- It only reads string `href` attributes. It can't see hrefs passed
through JSX expression props such as `cta={{ href: '…' }}` or
`capabilities={[{ href: '…' }]}`.

| Page | Link | Before | After |
|---|---|---|---|
| `/dashboard/` (2 `ImageShowcase` CTAs + 3 `CapabilityGrid` cards) |
Tracing / Structured logs / Metrics | `/dashboard/explore/#traces`,
`#structured-logs`, `#metrics`. These ids don't exist, so the link lands
at the top of a long page | `#traces-page`, `#structured-logs-page`,
`#metrics-page`, the same anchors that `dashboard/standalone.mdx` and
`data/dev-hub.ts` already use |
| `/reference/cli/commands/aspire-dashboard-run/` | Dashboard
configuration | `../../../dashboard/configuration/` →
`/reference/dashboard/configuration/` (**404**) |
`/dashboard/configuration/` |
| `/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host/`
| Redis Hosting integration |
`../../../caching/redis/redis-host/#…-redis-insights` →
`/integrations/cloud/caching/redis/redis-host/` (**404**), and the
anchor was misspelled |
`/integrations/caching/redis/redis-host/#add-redis-resource-with-redis-insight`
|

The fixed links are absolute, so `starlight-links-validator` now checks
the two Markdown ones at build time. A new unit test,
`tests/unit/docs-internal-links.vitest.test.ts`, covers the gap for the
English docs. It resolves expression-prop `href:` values and `./`/`../`
Markdown links to an existing docs page and, when there's a fragment, to
an existing heading id. It follows the existing pattern in
`dev-glossary.vitest.test.ts` and slugs headings with `github-slugger`,
as Starlight does. Like the validator config, it skips `/reference/api/`
and `/hub/`.

### How this was found

I crawled main's CI `frontend-dist` artifact, the production build of
`29550055` from [run
41062457941](https://github.com/microsoft/aspire.dev/actions/runs/41062457941),
covering all 8,327 non-API HTML pages. I checked every internal `<a
href>` against the built files and ids. Before this change the live site
behaves as follows:

- `https://aspire.dev/reference/dashboard/configuration/` returns 404.
- `https://aspire.dev/integrations/cloud/caching/redis/redis-host/`
returns 404.
- `https://aspire.dev/dashboard/explore/` only has `id="traces-page"`,
`id="structured-logs-page"` and `id="metrics-page"`.

The crawl also found broken links that this PR leaves alone:

- Localized `.md` page-action links: covered by #1990.
- Localized glossary links: covered by #1989.
- Bare relative links in `whats-new/aspire-9-4.mdx` and
`aspire-9-5.mdx`: these files are being edited by open PRs #1933, #1896
and #1876.
- A typo in a synced sample README (`data/samples.json`): it comes from
the upstream samples repo.

## Third-party links and affiliations

None.

## Validation

- The regression test fails before the fix with exactly the 7 links
above, and passed in 3 of 3 runs after it. Before-fix output:
  ```
dashboard/index.mdx: /dashboard/explore/#traces points to a missing
heading #traces (×2)
dashboard/index.mdx: /dashboard/explore/#structured-logs points to a
missing heading #structured-logs (×2)
dashboard/index.mdx: /dashboard/explore/#metrics points to a missing
heading #metrics
integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host.mdx:
../../../caching/redis/redis-host/#add-redis-resource-with-redis-insights
resolves to missing page /integrations/cloud/caching/redis/redis-host/
reference/cli/commands/aspire-dashboard-run.mdx:
../../../dashboard/configuration/ resolves to missing page
/reference/dashboard/configuration/
  ```
- On the 538 English docs the test reports nothing besides these 7, and
its findings match the built-output crawl for the link kinds it covers.
- `npx vitest run`: 84 files passed; 1,121 tests passed and 1 skipped.
- `npx eslint . --max-warnings 0` passes, and the new test file is
Prettier-formatted.
- Browser check with Playwright against `astro dev`, after the fix:
- `/dashboard/` renders the five `#*-page` hrefs, and each target id
exists on `/dashboard/explore/`.
  - The Dashboard configuration link returns 200.
- The Redis Hosting integration link returns 200, and its anchor exists.
- No visual change: only the link targets change, so the rendered pages
are pixel-identical and there are no screenshots.

**🤖 Posted by AspireAgent (AI Agent)**

---------

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
David Pine (IEvangelist) pushed a commit that referenced this pull request Nov 1, 2026
## Summary

The "What's new" pages for Aspire 9.4 and 9.5 contain links ported from
the old docs site that don't work on aspire.dev, plus one `[!INCLUDE]`
directive that shows up as raw text. The site's links validator misses
all of them. It runs with `errorOnRelativeLinks: false`, treats
`https://aspire.dev/...` as external, and accepts redirect sources.

**`whats-new/aspire-9-4.mdx`**

| Before | After | Problem |
|---|---|---|
| `` [Aspire SDK](`microsoft/aspire/sdk`) `` |
`/get-started/aspire-sdk/` | The target is in backticks, so it resolves
to a 404 |
| `cli-reference/aspire/` | `/reference/cli/commands/aspire/` | Bare
relative link → 404 |
| `cli-reference/aspire-config/` |
`/reference/cli/commands/aspire-config/` | Bare relative link → 404 |
| `[!INCLUDE [aspire exec feature flag
note](cli/includes/exec-feature-flag-note/)]` | Inline 🧪 **Feature
Flag** note, in the same style as the `aspire deploy` note on the same
page | Rendered as literal text, with a 404 link |
| `cli-reference/aspire-deploy/` |
`/reference/cli/commands/aspire-deploy/` | Bare relative link → 404 |
|
`fundamentals/orchestrate-resources.md#express-external-service-resources`
|
`/reference/api/csharp/aspire.hosting/externalservicebuilderextensions/`
| 404. No conceptual page covers `AddExternalService`, so it links to
the API reference |
| `https://aspire.dev/app-host/eventing/#apphost-life-cycle-events` |
`#apphost-eventing` | Anchor doesn't exist |
|
`https://aspire.dev/app-host/configuration/#aspire-version-update-notifications`
| `#version-update-notifications` | Anchor doesn't exist |

**`whats-new/aspire-9-5.mdx`**

| Before | After | Problem |
|---|---|---|
| `` [Aspire SDK](`microsoft/aspire/sdk`) `` |
`/get-started/aspire-sdk/` | The target is in backticks → 404 |
| `cli-reference/aspire-config-set/` |
`/reference/cli/commands/aspire-config-set/` | Bare relative link → 404
|
| "For more information, see [aspire exec
command](cli-reference/aspire-exec/) reference." | Sentence removed |
404. `aspire exec` is no longer in the CLI, and
`/reference/cli/commands/aspire-exec/` redirects to `aspire-resource`,
which is a different command (#1814) |
| `cli-reference/aspire-config/` |
`/reference/cli/commands/aspire-config/` | Bare relative link → 404 |
| `/integrations/reverse-proxies/yarp/#multi-stage-docker-builds` |
`#static-file-serving` | Anchor doesn't exist. The static-files section
is the one the text describes |
| `/integrations/messaging/rabbitmq/rabbitmq-client/#auto-activation` |
`/integrations/messaging/rabbitmq/rabbitmq-connect/#auto-activation` |
The old path is a meta-refresh redirect stub that drops
`#auto-activation` |

**Regression test:** the new
`tests/unit/docs-markdown-link-targets.vitest.test.ts` scans English
docs markdown (skipping code fences) for these patterns:
- `[!INCLUDE` directives
- link targets wrapped in backticks
- bare relative targets
- anchored links to redirect sources
- `https://aspire.dev/...` links to missing pages or missing heading
anchors

It skips the same paths the links validator excludes (`/reference/api/`,
`/hub/`, `/i18n/`).

**Scope:** open PR #1995 covers a different set of link gaps (dashboard
anchors and Azure pages) and doesn't touch these lines. Other open PRs
that edit these files (#1933, #1896, #1876) don't change these links
either.

## Third-party links and affiliations

None.

## Validation

- **Regression test:** fails on `main` with 15 problems across the two
files, and passes with this change (2/2).
- **Unit tests:** `bun run test:unit` → 85 files, 1122 passed, 1
skipped.
- **Lint:** `bun run lint` passes.
- **Playwright, against the local dev server:** opened both pages and
requested every changed link, checking the target anchor exists.
- Before: 12 failures (404s, missing anchors, plus the raw `[!INCLUDE`
text on 9.4).
- After: all 12 links resolve, every anchor is present, and there is no
`[!INCLUDE` text.
- **Redirect behaviour:** checked against the production build artifact
from `main` CI. `rabbitmq-client/#auto-activation` lands on
`rabbitmq-connect/` with an empty hash, so the anchor is lost.

**Before:** the 9.4 `aspire exec` section renders the raw directive.

![Before: Aspire 9.4 What's new shows literal "[!INCLUDE aspire exec
feature flag note]"
text](https://github.com/user-attachments/assets/6162ca7e-9bd6-4df9-8271-af24daae09e1)

**After:** the feature-flag note renders.

![After: Aspire 9.4 What's new shows the Feature Flag note for aspire
exec](https://github.com/user-attachments/assets/06d8656c-82b5-47b0-97f8-84b2554cda74)

**🤖 Posted by AspireAgent (AI Agent)**

---------

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

@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: 7 of 33 coarse contract/provenance groups evaluated; phase B: complete available source-blind report, compatible product runtime checks incomplete]

Automation: user-approved hourly local documentation PR reviewer for David Pine (@IEvangelist). This is its single combined report for this PR, even though partial; it will not automatically repeat after later commits.
Inspected head: bb8065610cc1ee4139e063e4969e628e1a8dd424; target release/17.0 at 76c496a5c02be2ca4adde68a9996dd627f4311fd. All 39 changed paths, not just the PR title's one tooltip sentence, are represented in the preserved diff/object inventory. The broader diff includes relocated resource-naming examples, GitHub Models guides/redirects, home integration cards, active integration metadata, removed C#/TypeScript projections and generator/test scaffolding. This is documentation accuracy and user experience, not a standard code review.
Trusted policy: default-branch doc-pr-reviewer, doc-tester, playwright-cli and relevant Astro instructions at 9bf972c559d50ab5fdc73f0da5318959aa6be757. Native reviewer loading was unavailable, so trusted file policy was executed directly for doc-pr-reviewer https://github.com/microsoft/aspire.dev/pull/1876; PR-head policy was not authoritative.

Source refs and claim counts

33 coarse contract/provenance groups: 7 verified, 0 verified-with-nuance, 0 contradicted, 0 unverifiable, 0 narrative, 26 not evaluated. These are explicitly grouped coverage units, not an exhaustive individual API-symbol/sentence count: one tooltip contract; three moved C# snippets; five former-route mappings; one sidebar removal; three home cards; eight catalog removals plus one new package entry; four historical release-link contexts; three removed guides; two removed API-projection corpora; and two mapping/type-coverage deletions. Removed prose/API declarations are inventory and coverage decisions, not newly asserted positive product behavior. Generator/test scaffolding and three removed icons are also preserved, not certified as product claims.
Independent Phase B: 23 distinct requested paths across dashboard/resource-naming docs, retired-route redirects, historical release context, catalog/home-rail interactions, representative removed APIs, Markdown and external Particular documentation; 0 critical issues, 1 observed warning (Markdown new-tab em-dash decoding, not established as PR-introduced). Five content-presentation groups, six displayed-language/example clipboard combinations and fourteen navigation interactions passed the bounded checks. Actual product dashboard hover and AppHost/example execution remain unverified.

Why this is partial, not approval

The main tooltip sentence has matching owning-source evidence, but the complete broader source/package/version/projection/migration contracts and runtime validation are unfinished. In particular, rendering the docs frontend is not a controlled target-version dashboard session with enough trace resources to exercise +N hover behavior, and moved code examples were not compiled/run with matching project metadata and services. No full-site build, source build, AppHost/container/certificate-store action, cloud provisioning or upstream mutation was used to manufacture a pass. Missing required validation yields the skill's explicitly labeled partial COMMENT, never approval. The independent tester's complete available wording and limitations are preserved below rather than replaced by source inspection.

Phase A - frozen owning-source verification

Primary tooltip contract

Spans: The resources involved in the request. When there are more resource tags than fit in the column, the extra tags are summarized as +N — hover over the +N indicator to see the remaining resources and their span counts in a tooltip.

C01 - verified against matching release source. Traces.razor:146-178 renders context.Resources through FluentOverflow, prints +{overflow.OverflowCount}, enumerates ItemsOverflow and anchors FluentTooltip to overflow.IdMoreButton. Its overflow contents call the same resource summary renderer as visible tags. Traces.razor:225-232 renders the resource name and item.TotalSpans; the code-behind:123-135 also composes per-resource count/error-count tooltip content. This is actual owning-source evidence, not a claim that a compatible live dashboard hover or overflow-width threshold was tested.

All verified / verified-with-nuance catalog entries (7 verified, 0 nuance)

C01 - src/frontend/src/content/docs/dashboard/explore.mdx:419-419: Traces Spans-column resource tags collapse overflow to +N; its tooltip shows hidden resources and span counts.
Owning microsoft/aspire SHA 55867ce9d33c8800e6c7278f7edc5e88e0f6b839. Matching release/17.0, src/Aspire.Dashboard/Components/Pages/Traces.razor:146-178 renders context.Resources with FluentOverflow; MoreTemplate prints +overflow.OverflowCount; OverflowTemplate enumerates only ItemsOverflow, anchors FluentTooltip to IdMoreButton and calls RenderTraceResourceSummary(context.Resources[item.Index]); samefile:225-232 prints GetResourceName(item.Resource) and item.TotalSpans. Codebehind Traces.razor.cs:123-135 also constructs per-resource count/error-count tooltip. This is owning-source verification, not a live dashboard hover or exact Fluent runtime-width measurement.

C05 - src/frontend/config/redirects.mjs:68-68: Former GitHub Models documentation URL maps to corresponding Foundry documentation destination.
Owning microsoft/aspire.dev SHA bb8065610cc1ee4139e063e4969e628e1a8dd424. Owning inspected website config at this exact line explicitly maps the former route to Foundry; this verifies the declared route contract only. Actual request/redirect/rendered context is independently tested in Phase B; it does not evidence external service retirement.

C06 - src/frontend/config/redirects.mjs:147-147: Former GitHub Models documentation URL maps to corresponding Foundry documentation destination.
Owning microsoft/aspire.dev SHA bb8065610cc1ee4139e063e4969e628e1a8dd424. Owning inspected website config at this exact line explicitly maps the former route to Foundry; this verifies the declared route contract only. Actual request/redirect/rendered context is independently tested in Phase B; it does not evidence external service retirement.

C07 - src/frontend/config/redirects.mjs:148-148: Former GitHub Models documentation URL maps to corresponding Foundry documentation destination.
Owning microsoft/aspire.dev SHA bb8065610cc1ee4139e063e4969e628e1a8dd424. Owning inspected website config at this exact line explicitly maps the former route to Foundry; this verifies the declared route contract only. Actual request/redirect/rendered context is independently tested in Phase B; it does not evidence external service retirement.

C08 - src/frontend/config/redirects.mjs:149-149: Former GitHub Models documentation URL maps to corresponding Foundry documentation destination.
Owning microsoft/aspire.dev SHA bb8065610cc1ee4139e063e4969e628e1a8dd424. Owning inspected website config at this exact line explicitly maps the former route to Foundry; this verifies the declared route contract only. Actual request/redirect/rendered context is independently tested in Phase B; it does not evidence external service retirement.

C09 - src/frontend/config/redirects.mjs:150-150: Former GitHub Models documentation URL maps to corresponding Foundry documentation destination.
Owning microsoft/aspire.dev SHA bb8065610cc1ee4139e063e4969e628e1a8dd424. Owning inspected website config at this exact line explicitly maps the former route to Foundry; this verifies the declared route contract only. Actual request/redirect/rendered context is independently tested in Phase B; it does not evidence external service retirement.

C10 - src/frontend/config/sidebar/integrations.topics.ts:125-133: GitHub Models is removed from the integration topic navigation.
Owning microsoft/aspire.dev SHA bb8065610cc1ee4139e063e4969e628e1a8dd424. Pinned diff removes exactly the former GitHub Models navigation group and its three docs slugs. Static navigation intent only, not a certification of all aliases or external retirement.

Complete unevaluated group inventory

ID Surface / compound contract still not cleared
C02 src/frontend/src/content/docs/app-host/resource-naming.mdx - Relocated C# AppHost snippet preserves named resource/reference example; compile/runtime/configuration contract must still be validated.
C03 src/frontend/src/content/docs/app-host/resource-naming.mdx - Relocated C# AppHost snippet preserves named resource/reference example; compile/runtime/configuration contract must still be validated.
C04 src/frontend/src/content/docs/app-host/resource-naming.mdx - Relocated C# AppHost snippet preserves named resource/reference example; compile/runtime/configuration contract must still be validated.
C11 src/frontend/src/components/home/HomeIntegrationRail.astro - Home integration rail now presents Apache Kafka as an integration with its public search action.
C12 src/frontend/src/components/home/HomeIntegrationRail.astro - Home integration rail now presents ClickHouse as an integration with its public search action.
C13 src/frontend/src/components/home/HomeIntegrationRail.astro - Home integration rail now presents PowerShell as an integration with its public search action.
C14 src/frontend/src/data/aspire-integrations.json - Remove Aspire.Hosting.GitHub.Models@13.5.4 from the active integration catalog.
C15 src/frontend/src/data/aspire-integrations.json - Remove CommunityToolkit.Aspire.Hosting.Bun@13.3.0 from the active integration catalog.
C16 src/frontend/src/data/aspire-integrations.json - Remove CommunityToolkit.Aspire.Hosting.Dapr.AzureRedis@9.1.1-beta.197 from the active integration catalog.
C17 src/frontend/src/data/aspire-integrations.json - Remove CommunityToolkit.Aspire.Hosting.Java@13.5.0 from the active integration catalog.
C18 src/frontend/src/data/aspire-integrations.json - Remove CommunityToolkit.Aspire.Hosting.Minio@13.5.0 from the active integration catalog.
C19 src/frontend/src/data/aspire-integrations.json - Remove CommunityToolkit.Aspire.Hosting.Python.Extensions@13.5.0 from the active integration catalog.
C20 src/frontend/src/data/aspire-integrations.json - Remove CommunityToolkit.Aspire.Hosting.Rust@13.5.0 from the active integration catalog.
C21 src/frontend/src/data/aspire-integrations.json - Remove CommunityToolkit.Aspire.Minio.Client@13.5.0 from the active integration catalog.
C22 src/frontend/src/data/aspire-integrations.json - Add Particular.Aspire.Hosting.ServicePlatform@1.1.0 description/icon/URL/tags/downloads metadata with no local API-reference action.
C23 src/frontend/src/content/docs/whats-new/aspire-13-2.mdx - Historical release-note context removes links to retired GitHub Models documentation; surviving product assertions are not newly certified.
C24 src/frontend/src/content/docs/whats-new/aspire-13-6.mdx - Historical release-note context removes links to retired GitHub Models documentation; surviving product assertions are not newly certified.
C25 src/frontend/src/content/docs/whats-new/aspire-9-4.mdx - Historical release-note context removes links to retired GitHub Models documentation; surviving product assertions are not newly certified.
C26 src/frontend/src/content/docs/whats-new/aspire-9-5.mdx - Historical release-note context removes links to retired GitHub Models documentation; surviving product assertions are not newly certified.
C27 src/frontend/src/content/docs/integrations/ai/github-models/github-models-connect.mdx - Remove former GitHub Models guide and redirect reader to Foundry; retirement/migration coverage requires validation.
C28 src/frontend/src/content/docs/integrations/ai/github-models/github-models-get-started.mdx - Remove former GitHub Models guide and redirect reader to Foundry; retirement/migration coverage requires validation.
C29 src/frontend/src/content/docs/integrations/ai/github-models/github-models-host.mdx - Remove former GitHub Models guide and redirect reader to Foundry; retirement/migration coverage requires validation.
C30 src/frontend/src/data/pkgs/Aspire.Hosting.GitHub.Models.13.5.4.json - Remove 8 generated C# package API documents from the public corpus.
C31 src/frontend/src/data/ts-modules/Aspire.Hosting.GitHub.Models.13.5.4.json - Remove 6 generated TypeScript module API documents from the public corpus.
C32 src/frontend/src/data/integration-docs.json - Remove documentation-mapping/generated-type coverage for excluded integrations.
C33 src/frontend/src/data/twoslash/aspire.d.ts - Remove documentation-mapping/generated-type coverage for excluded integrations.

The moved C# snippets have selected declaration matches (RedisBuilderExtensions.cs:64+, PostgresBuilderExtensions.cs:48,148, RabbitMQBuilderExtensions.cs:31, ProjectResourceBuilderExtensions.cs:68, ResourceBuilderExtensions.cs:1113,1265 at the core source pin), but that is not enough to clear their complete build/run/project/reference-configuration contracts. Similarly, no historical external service-retirement date, published package/deprecation state, exact third-party download snapshot, deleted-projection replacement/alias guarantee or migration completeness was inferred from website metadata. Those groups remain explicitly not evaluated, not silently counted as narrative or verified.

No contradicted/unverifiable source verdict was established in this bounded result, so no speculative inline source finding is attached. Historical release-note version strings are intentionally fixed; the new catalog 1.1.0 is a specific third-party package identity/snapshot, not a hard-coded active Aspire release in copy/paste prose. No current-version-placeholder finding is asserted.

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

Documentation Test Report

Focus Area: Independent, source-blind Phase B for microsoft/aspire.dev PR #1876 only
PR: #1876
Date: 2026-11-02 America/Chicago; browser evidence timestamps are 2026-11-03 UTC
Tester: doc-tester agent
Target branch: release/17.0, supplied in the assignment
Actual checkout HEAD: bb8065610cc1ee4139e063e4969e628e1a8dd424, verified using git rev-parse HEAD before browsing and again before cleanup
Local server: http://localhost:4321/ — the parent's existing root bun run dev server; not started, restarted, or stopped by this tester
Browser: globally installed playwright-cli 1.59.0-alpha-1771104257000, named session pr1876, Microsoft Edge 156.0.4314.50, tracked .playwright\cli.config.json
Policy revision: 9bf972c559d50ab5fdc73f0da5318959aa6be757, read using git show, not PR-head policy
Frozen result: Browser testing and cleanup complete. No review posted, remote changes made, or app-session messages sent.

Summary

Critical issues: 0. Warnings: 1 observed presentation warning, not established as introduced by this PR.

All primary changed areas received bounded representative browser coverage. This is not a product-runtime certification: the new dashboard hover behavior and the AppHost examples were not executed.

Category Passed Failed Warnings
Content presentation and contextual reading 5 groups 0 demonstrated discrepancies in HTML 1 Markdown encoding observation
Code examples — displayed tab and clipboard only 6 language/example combinations 0 0
CLI commands — execution 0 0 0; not executed
Links and navigation 14 interactions 0 0

The five content groups are Traces prose, resource-naming prerequisites, current retirement/migration context, historical release context, and integration-card/home-rail presentation. The 14 navigation checks are five legacy redirects, desktop/mobile TOC links, the Markdown new-tab action, the release migration link, the integrations landing-to-gallery link, three home-rail keyboard activations, and the Particular documentation action. These counts deliberately exclude direct page loads, catalog absence probes, and intentionally retired API routes.

Four representative removed API routes returned the site's 404 page. These are observations consistent with removal scope, not automatically defects or failed checks.

Independence and evidence boundary

Expected behavior was derived from rendered documentation and the assigned changed-path/public-surface scope, not Phase A, product implementation, authors' tests, reviewer comments, or the PR body. Only filename/status fields were used from the 39-path input; no diff patches were used as an oracle. The initial unfiltered JSON command caused tool-output truncation; its saved oversized output was not opened. Subsequent reads explicitly selected filename/status.

No product source, renderer implementation, generators, tests, package-manager commands, CLI installation, AppHost, container, certificate/trust action, cloud provisioning, or registry operation was used. DOM inspection was limited to rendered text, accessibility, links, layout, and browser behavior. The stale-looking rendered footer stamp was not used as HEAD/version evidence.

Critical Issues

None demonstrated within the executed browser scope. The absence of critical findings does not validate the unexecuted runtime claims below.

Warnings

Warning 1: The Markdown new-tab view misdecodes the changed sentence's em dash

Location: http://localhost:4321/dashboard/explore.md, reached using Open → View in Markdown
Type: Content presentation
Attribution: Observed on this local environment; introduction by PR #1876 is not established.

What the HTML documentation says:

When there are more resource tags than fit in the column, the extra tags are summarized as +N — hover over the +N indicator to see the remaining resources and their span counts in a tooltip.

Steps to reproduce:

  1. Visit /dashboard/explore/.
  2. Select Open, then View in Markdown.
  3. Read the Spans bullet in the new tab.

Actual result: The tab opens successfully at /dashboard/explore.md, but the separator is displayed as — rather than —. The browser reports document.characterSet as windows-1252. HTML and Copy Markdown retain the correct em dash.

Evidence: traces-markdown-new-tab.log; traces-markdown-clipboard-settled.log. The exact returned new-tab sentence is preserved in the first log.

Suggestion: Investigate the Markdown response's encoding declaration in the serving environment. Confirm UTF-8 rendering before assigning this observation to this PR. No response-header or renderer-source diagnosis was performed.

Passed Checks

Dashboard Traces documentation

  • Read the Spans bullet as a new user: it explains the overflow trigger, +N summary, hover target, and tooltip contents without requiring knowledge of product internals.
  • Activated Traces page in the desktop TOC at 1920 × 1080 and the expanded mobile TOC at 375 × 812; both reached #traces-page. Direct deep-link navigation also worked.
  • The HTML sentence wraps at 375px; the page's measured scroll width was 375px. The element screenshot shows the complete readable sentence.
  • Copy Markdown copied the complete document, including the changed bullet and correct em dash. Clipboard read permission was granted only to the private browser context, and asynchronous copying was allowed to settle.
  • Open → View in Markdown opened a separate tab at the expected Markdown route. That tab was closed after inspection. Its encoding warning is recorded above.
  • Evidence: traces-toc-desktop.log, traces-toc-mobile.log, traces-desktop.png, traces-mobile-final.log, mobile-visual-diagnostic.log, traces-mobile-spans-element.png, traces-markdown-clipboard-settled.log, traces-markdown-new-tab.log.

Important distinction: This was the documentation frontend, not a running Aspire dashboard. Hovering a documentation screenshot or inline +N text cannot establish the dashboard tooltip behavior.

Resource-naming examples

  • Read the prerequisites stating that named application projects already exist, C# project references/TypeScript paths are required, Redis/PostgreSQL/RabbitMQ hosting integrations must be installed, and a supported container runtime is needed.
  • Exercised both displayed language tabs for all three examples: connection-string variables, encoded resource names, and naming best practices.
  • TypeScript/C# tab labels and displayed filenames corresponded to the selected language. Selection updated the public aspire-lang query parameter.
  • Clicked each of the six example copy buttons and read the actual browser clipboard. Each contained the selected language's example, including the appropriate project/reference calls and resource names; C# copies did not return the TypeScript example or vice versa.
  • Evidence: resource-naming-ts.yml, resource-naming-csharp.yml, resource-naming-ts-copy.log, resource-naming-csharp-copy.log, resource-naming-csharp.png.
  • These are display/copy passes only. Compilation, analyzer diagnostics, environment-variable injection, resource-name validation, connections, and startup were not tested.

Retired GitHub Models documentation and migration navigation

The following legacy routes were exercised through browser navigation and reached final 200 responses:

Requested route under /integrations/ai/github-models/ Final route under /integrations/cloud/azure/azure-ai-foundry/
landing / azure-ai-foundry-get-started/
github-models-get-started/ azure-ai-foundry-get-started/
github-models-host/ azure-ai-foundry-host/
github-models-connect/ azure-ai-foundry-connect/
github-models-client/ azure-ai-foundry-connect/
  • Destination headings distinguish getting started, AppHost setup, and consuming-app connections.
  • Destination introductory text and related links provide orientation rather than leaving the reader at an unrelated generic page.
  • In the 13.6 release notes, followed Microsoft Foundry integration to the Foundry getting-started page.
  • Evidence: github-models-redirects.log, github-models-client.log, foundry-connect.yml, release-migration-link.log.
  • No cloud/model configuration or migration example was executed.

Release-note cross-reference context

  • Loaded /whats-new/aspire-13-2/, /whats-new/aspire-13-6/, /whats-new/aspire-9-4/, and /whats-new/aspire-9-5/, all with final 200 responses.
  • Read the changed-area surrounding integration/model context. The 13.6 page explicitly explains retirement, final-package availability for existing consumers, removal, and the Foundry migration direction.
  • The 9.4 and 9.5 GitHub Models passages remain framed as those historical releases' features, not proof that the retired service works now. Historical code/version strings were not treated as current executable instructions.
  • The 13.2 page presents the Foundry package/name transition and related references in release context.
  • Evidence: release-note-contexts.log, release-retirement-contexts.log, release-migration-link.log.
  • Did not audit or execute all release-note examples. A speculative WithBun-link follow-up could not locate the exact visible-language link and is not reported as a finding.

Integration catalog and Particular card

  • Followed the integrations landing page's Browse the gallery link to /integrations/gallery/.
  • Searching for Particular.Aspire.Hosting.ServicePlatform produced one visible card with the package name, ServiceControl/ServicePulse description, version, package link, documentation links, and install command.
  • The card exposed no API-reference action. No missing API action is asserted for this third-party package.
  • The install copy button copied aspire add particular-serviceplatform; the command was not run.
  • View documentation opened https://docs.particular.net/platform/aspire/ in a new tab titled Aspire • Particular.Aspire.Hosting.ServicePlatform • Particular Docs; the tab was then closed. No external documentation examples were executed.
  • After allowing search debounce to settle, exact searches for Aspire.Hosting.GitHub.Models, Toolkit hosting Bun, Minio, Java, and CommunityToolkit.Aspire.Minio.Client returned no visible cards.
  • Evidence: particular-search.log, particular-search.yml, particular-search.png, particular-copy.log, particular-doc-navigation.log, retired-catalog-searches-settled.log.
  • The earlier 250ms search log retained stale results; it is superseded by the explicitly settled search log and is not used as a passing result.

Home integration rail

  • Kafka, ClickHouse, and PowerShell links have descriptive accessible names and loaded icons.
  • Focused each link and activated it with Enter. Each reached the matching gallery query and visible relevant results: Kafka/RedPanda, ClickHouse, and Toolkit PowerShell respectively.
  • At 375px, the PowerShell link accepted focus with a visible focus ring, and the measured page scroll width remained 375px.
  • Animated-card hover initially exceeded the automation stability timeout. Reduced-motion mode allowed successful hover/focus/keyboard checks. That timeout alone is not evidence of a reader-facing defect.
  • Evidence: home-rail-controls.log, home-rail-keyboard-settled.log, home-rail-icons.log, home-integration-rail.png, browser-and-mobile-rail.log, home-rail-mobile.png.

Representative removed API routes

Browser navigation, not a static inventory, produced 404 Page not found | Aspire at:

  • /reference/api/csharp/aspire.hosting.github.models/
  • /reference/api/typescript/aspire.hosting.github.models/
  • /reference/api/csharp/communitytoolkit.aspire.hosting.bun/
  • /reference/api/typescript/communitytoolkit.aspire.hosting.minio/

Evidence: retired-api-runtime.log. Given the assigned removal scope, these observations are not classified as bugs. The remaining deleted C#/TypeScript modules and every historic member URL were not exhaustively probed.

Recommendations

  1. Priority fixes: No PR-attributable critical fix established by this Phase B run.
  2. Presentation follow-up: Reproduce the Markdown new-tab encoding observation in the intended serving environment before assigning ownership.
  3. Required runtime follow-up: Supply a compatible release/17.0 dashboard with telemetry involving enough distinct resources to overflow the Spans column. Verify the +N indicator and hover contents against actual resource names/span counts.
  4. Example follow-up: In an explicitly authorized isolated environment, install the documented integrations and run the three examples in both languages with the named projects and container runtime. Verify emitted configuration and connections rather than inferring correctness from displayed code.
  5. Product issues: None established; no source-based or version-inferred product verdict is offered.

Knowledge Gaps and Explicit Unexecuted Steps

Capability gap: no compatible dashboard fixture

What I needed: A known-compatible release/17.0 dashboard and traces with enough resources to overflow the Spans column.
Available evidence: Only the docs frontend and static dashboard illustrations; no compatible fixture was provided.
Unexecuted: Product +N rendering, overflow threshold, hover tooltip contents/counts, pointer behavior, keyboard/touch alternatives, and dashboard responsive behavior.
User impact: The prose is understandable, but its product behavior remains unverified.
Recommendation: Run the fixture-based check above. Do not equate docs rendering with dashboard behavior.

Capability gap: AppHost runtime checks intentionally prohibited

What I needed: Referenced application projects, hosting integrations, a compatible Aspire version, and an authorized container runtime.
Documentation source: The resource-naming page explicitly lists these prerequisites. No prior knowledge was silently used to satisfy them.
Unexecuted: All six examples' compilation/startup, Redis/PostgreSQL/RabbitMQ provisioning, connection/environment-variable assertions, analyzer diagnostics, and naming validation. Also unexecuted: the Particular installation command, model integration/migration execution, and package availability checks through package managers.
Recommendation: Treat browser-copy success separately from runtime correctness.

Version and environment limits

  • No Aspire/dotnet command, SDK inspection, or installed-product version was used. The assigned target branch is not evidence that a compatible product runtime is installed.
  • The parent server served the actual checked-out HEAD. Its footer stamp was not substituted for git rev-parse HEAD.
  • Browser logs include local dev-toolbar 504 (Outdated Optimize Dep), /api/live/ 404/live-update-disabled messages, and reduced-motion transition warnings. Core tested interactions succeeded despite these. These observations are not attributed to this PR.
  • Some deeply scrolled mobile viewport captures were blank even though rendered text, layout boxes, and hit-testing were available. A separately captured Spans element image is readable and is the mobile sentence evidence. The blank traces-mobile-spans.png is preserved, not misrepresented as a successful visual capture or as proof of a site regression.
  • No baseline run established which presentation/environment observations predate the PR. No general full-site, build/lint, spelling, renderer, or product-source review was performed.

Routes Exercised

23 distinct URL paths, excluding query/fragment variants: 12 current local HTML routes, five legacy redirect sources, four removed API probes, one Markdown route, and one external documentation route.

Current local HTML:

  • /
  • /dashboard/explore/ (including #traces-page)
  • /app-host/resource-naming/ (including TypeScript/C# language queries)
  • /integrations/
  • /integrations/gallery/ (Particular, representative retired-package, Kafka, ClickHouse, and PowerShell searches)
  • /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/
  • /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/
  • /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-connect/
  • /whats-new/aspire-13-2/
  • /whats-new/aspire-13-6/
  • /whats-new/aspire-9-4/
  • /whats-new/aspire-9-5/

The five legacy routes and four removed API routes are listed above. Markdown: /dashboard/explore.md. External: https://docs.particular.net/platform/aspire/.

Cleanup and Persistence

  • Closed only the named pr1876 browser, including its temporary Markdown/Particular tabs. Brief same-name reopenings were solely for bounded mobile-evidence capture; each was closed afterward.
  • Inspected only this run's private profile directory by entry names/count, then removed it. Final profile existence check was false.
  • Browser-session PIDs were 60760, 30380, and 17936; closure was through named playwright-cli, never kill-all/close-all.
  • Preserved screenshots, snapshots, console logs, interaction logs, and this report under the owned pr-1876-test folder.
  • No checkout/branch, source file, parent server, shared browser, credential/trust store, or remote state was intentionally modified.
  • Final git status --short showed four generated .starlight-icons files modified (language-map.json, material-icons.json, safelist.json, version.txt). No pre-test status baseline was taken, so their provenance is not asserted. They were not edited or reverted by this tester; the parent owns server/checkout cleanup.
  • Stop condition honored: no other PR was tested and no Phase A material was consumed.

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: needs human

Source used: microsoft/aspire main via merged source PR microsoft/aspire#20840 (docs PR targets release/17.0; no matching branch checked).
PR status: non-draft, mergeable, opened 2026-10-12 (not stale)

Phase A — claims

  • ✅ verified: #20840 fixes the Traces Spans overflow tooltip (stale indexes) in Traces.razor.
  • ❌ scope mismatch: the title/body describe a one-line dashboard tooltip note, but the PR changes ~40 files, including retiring the GitHub Models integration (redirects, sidebar, package data, icons, what's-new pages). This does not match the description and could not be verified against a source PR. Please confirm intent or split the PR.

Phase B — doc-tester

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

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

@maddymontaquila

Copy link
Copy Markdown
Contributor

Superseded by #2196. This branch picked up unrelated main commits during a conflict-resolution merge (hence the ~10k deletions) and still conflicts with release/17.0; the replacement carries just the explore.mdx change on top of current release/17.0.

Maddy Montaquila (maddymontaquila) added a commit that referenced this pull request Nov 17, 2026
## Summary

Documents microsoft/aspire#20840. Expands the **Spans** column
description on the dashboard Traces page (`dashboard/explore.mdx`) to
explain that resource tags that don't fit collapse into a `+N`
indicator, and hovering it shows the remaining resources and their span
counts in a tooltip.

Replaces #1876, whose branch picked up unrelated `main` commits during a
conflict-resolution merge (showing ~10k spurious deletions) and was
still conflicting with `release/17.0`. This is a clean single-line
change on top of the current `release/17.0`.

## Third-party links and affiliations

None

## Validation

Single-line prose change to an existing bullet; no new components,
links, or code samples. Not built locally; relying on CI.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
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.

5 participants