🤓 Content for release: 13.6

.agents/skills/doc-pr-reviewer/SKILL.md

@@ -100,13 +100,16 @@ copy/paste guidance that should track the active release, including:
   version.
 - Getting started, installation, or "use this today" examples that should move
   with the release branch.
+- Generic `--version`, `-Version`, or package-installation examples where the
+  exact version is not material to the scenario.
 
 Do **not** require placeholders for intentionally fixed versions, including:
 
 - What's-new or release-note pages that describe a specific historical release.
 - Upgrade examples that deliberately compare old and new versions.
-- CLI examples where the point is pinning a specific version with `--version`,
-  `-Version`, or `Aspire.ProjectTemplates::...`.
+- Compatibility, reproduction, or migration examples where pinning the exact
+  version with `--version`, `-Version`, or `Aspire.ProjectTemplates::...` is
+  material to the scenario.
 - Versioned schema URLs, package compatibility notes, minimum-version
   requirements, third-party dependency versions, container image tags, or issue
   reproduction snippets.

.agents/skills/doc-tester/SKILL.md

@@ -323,6 +323,17 @@ For each documentation page:
 2. **Take a snapshot** to read the page content
 3. **Evaluate the content** - Is it clear? Complete? Accurate?
 4. **Note any confusion** - What would a new user struggle with?
+5. **Inspect current-version references in the source MDX** - Rendered pages
+   show the replaced value, so confirm that current guidance uses the shared
+   placeholders rather than a hard-coded Aspire version:
+   - `%ASPIRE_VERSION%` for the full current stable version
+   - `%ASPIRE_VERSION_MAJOR_MINOR%` for the current major/minor version
+
+Flag hard-coded Aspire versions in current installation instructions, package
+references, AppHost SDK declarations, CLI output, and copy/paste examples.
+Keep fixed versions when the exact version is intentional, such as release
+notes, upgrade comparisons, minimum-version requirements, compatibility notes,
+or issue reproduction steps.
 
 ### Phase 2: Test CLI Commands
 

.agents/skills/doc-writer/SKILL.md

@@ -1003,6 +1003,59 @@ Use standard Markdown links with absolute paths from the docs root:
 For more information, see [Service Defaults](/fundamentals/service-defaults/).
 ```
 
+### Inline API references
+
+Use `ApiReference` selectively to connect an explanation to API reference documentation, not to turn every API mention into a link.
+
+- In ordinary prose, use `<ApiReference />` only on the **first named mention of a given API in an article**, when naming that API helps explain the behavior or accompanying example. Do not introduce an API name just to add a reference link.
+- After that first mention, do **not** repeat the component or API reference link in ordinary prose, including prose in callouts and later sections. Prefer descriptive prose such as "this method" or "the dependency configuration." If repeating the name is necessary for clarity, use unlinked inline code appropriate to the AppHost language being discussed.
+- Apply the ordinary-prose limit **per API, per article**, not per section or language tab. A different API can have its own first reference.
+- In **bulleted or numbered lists**, including language-specific API explanation lists, repeated `<ApiReference />` components are allowed. Treat equivalent API entries consistently, regardless of earlier mentions, rather than mixing linked components and unlinked API names.
+- An optional API reference link in **See also** is also allowed.
+- Keep API names in code samples as code; do not add reference markup inside code fences.
+- Match the reference to the API actually used in the example. A PostgreSQL example calling `withPostgresMcp()` / `WithPostgresMcp()` must be introduced with `Aspire.Hosting.PostgresBuilderExtensions.WithPostgresMcp`, not the generic `WithMcpServer` API.
+
+For example, introduce an API once:
+
+```mdx
+import ApiReference from '@components/ApiReference.astro';
+
+For PostgreSQL, use <ApiReference name="Aspire.Hosting.PostgresBuilderExtensions.WithPostgresMcp" /> to expose MCP tools for a database.
+```
+
+Later in the same article's ordinary prose, refer to "the PostgreSQL MCP helper" rather than repeating the linked API name. In an API explanation list, repeat the component for consistent entries:
+
+```mdx
+- <ApiReference name="Aspire.Hosting.PostgresBuilderExtensions.WithPostgresMcp" /> exposes MCP tools for a database.
+- <ApiReference name="Aspire.Hosting.ResourceBuilderExtensions.WithReference" /> connects resources.
+```
+
+#### Selecting an overload
+
+Author `name`, `package`, and `parameterTypes` as explicit static props. The authoring validator does not evaluate spread objects: it reports `unsupported-spread` when a spread could supply or override any of these props, including optional ones. Remove the spread, or explicitly set all three props after the last spread so their values are known.
+
+By default, `ApiReference` shows the method name **without `()`** and links to the method group. To discuss a specific overload, supply `parameterTypes` as a static array of its **complete declared C# parameter types**, in declaration order. Copy the types from the generated C# catalog, preserving namespaces, generic arguments, and nullability. Include the `this` receiver's type for an extension method, but not the `this` keyword. Use `[]` only for a declaration with no parameters.
+
+```mdx
+<ApiReference
+  name="Aspire.Hosting.ResourceBuilderExtensions.WithEnvironment"
+  parameterTypes={[
+    'Aspire.Hosting.ApplicationModel.IResourceBuilder<T>',
+    'string',
+    'string?',
+  ]}
+/>
+```
+
+This links to the exact C# overload and displays `WithEnvironment(string name, string? value)`. The extension receiver is used for selection but omitted from the visible call signature. In TypeScript mode, the component uses the generated TypeScript export's own name and parameters; several C# overloads may share one TypeScript dispatcher. Do not copy C# parameter types into a TypeScript signature or select overloads by ordinal position. A missing or ambiguous match is an authoring error, not permission to link to the first overload. Use `package` when the same API is declared in multiple packages.
+
+Linked references reuse the code-block headers' C# and TypeScript icons from `material-icon-theme`, centered inside the code background. Do not add a separate icon or empty parentheses manually. `()` is shown only when an explicitly selected API genuinely has no call parameters.
+
+The component derives its top-positioned tooltip from the resolved API's generated summary or description, including the selected overload when specified. Do not duplicate that description in an authored `title` prop. When no description exists, the tooltip identifies the API and language instead. Tooltip titles are capped at 160 characters, including an ASCII `...` suffix when shortened, preferably at a word boundary. This presentation limit also applies to diagnostic titles; full source descriptions, diagnostics, and visible API labels remain unchanged.
+
+Title-based tooltips use the shared `src/frontend/src/scripts/tooltips.ts` lifecycle on initial load and after ClientRouter navigation. Keep API descriptions text-only with `data-tippy-allowhtml="false"`; do not add a competing per-component initializer.
+The lifecycle is installed once per document; HMR disposal removes its listeners, restores titles, and destroys tooltip instances before the replacement module initializes.
+
 ### Reference NuGet Packages
 
 Use the 📦 emoji with links:
@@ -1042,6 +1095,23 @@ The aspire.dev site supports multiple languages. When creating new content:
 
 ### Version-Specific Information
 
+Use the shared build-time placeholders whenever current guidance needs to show
+the active Aspire release:
+
+| Placeholder | Use for |
+| ----------- | ------- |
+| `%ASPIRE_VERSION%` | Full current stable version, including patch |
+| `%ASPIRE_VERSION_MAJOR_MINOR%` | Current major/minor display or installer version |
+
+Use these placeholders in package references, `Aspire.AppHost.Sdk`
+declarations, file-based app directives, CLI/AppHost output, and generic
+installation examples that should advance with the release branch. This
+applies to localized documentation as well as English documentation.
+
+Keep a literal version when the exact version is part of the information being
+documented, such as a what's-new page, upgrade comparison, minimum-version
+requirement, compatibility note, historical package pin, or issue reproduction.
+
 ```mdx
 <Aside type="caution">This feature requires Aspire version 9.0 or later.</Aside>
 ```

.agents/skills/update-integrations/SKILL.md

@@ -51,6 +51,26 @@ The scripts use this precedence on `release/*` branches:
 
 If the Aspire release branch is not publicly reachable yet, set one of the override environment variables above. The scripts intentionally fail on `release/*` if the official release feed cannot be resolved, to avoid accidentally ingesting stale nuget.org packages.
 
+When the commit-specific feed is unavailable but a shared feed contains the required
+build, set `ASPIRE_RELEASE_FEED_URL` and `ASPIRE_RELEASE_VERSION` together. The
+version must be an exact package version matching the release branch, not a range.
+Official packages select only that version; Toolkit packages keep their normal
+nuget.org selection. Packages absent from that build retain an existing catalog
+entry, if any, rather than importing a different release. An unavailable pin for
+the entire integration set, an unlisted/deprecated pinned version, or a pinned
+registration lookup failure stops the update before the catalog is written.
+Selected-version registration metadata supplies release descriptions and tags.
+Where no published nuget.org icon metadata exists, the updater reports use of the
+public Aspire site icon instead of embedding an unpublished or authenticated-feed
+image URL.
+
+For an app-managed worktree whose branch name is not `release/*`, set
+`BUILD_SOURCEBRANCH=refs/heads/release/N.N` in the update process alongside those
+overrides. This supplies the existing branch-resolution context without renaming
+or switching the worktree. Do not set these variables globally. Review the
+resolved source and version before regeneration; C# and TypeScript generators
+consume the resulting catalog's exact versions.
+
 ## Step-by-Step Process
 
 ### 1. Run the update script
@@ -138,10 +158,20 @@ The script performs the following for every package listed in `aspire-integratio
 1. Resolves the correct package source per package: official Aspire packages use the branch-specific release feed on `release/*`, while Community Toolkit packages continue to use nuget.org.
 2. Queries that package source for the latest stable version (falls back to latest preview if no stable exists).
 3. Downloads the package into the local NuGet cache via `dotnet restore` if not already cached.
+   Provisioning SDK overlays restore with the same-version `Aspire.Hosting`
+   reference to model their AppHost context; other packages retain standalone
+   per-package restore graphs. Dependency errors remain fatal.
 4. Selects the best-matching target framework folder (prefers `net10.0`, then `net9.0`, etc.).
 5. Uses Roslyn to analyze the assembly and extract all public types, members, XML docs, and attributes.
 6. Writes a `{Package}.{Version}.json` file to `src/frontend/src/data/pkgs/`.
 
+An assembly that opts into an `AspireExportProvider` can expose generated ATS
+APIs without public C# types. For those assemblies, the generator retains package
+identity and provenance with `types: []` and `package.hasGeneratedExports: true`.
+This record feeds TypeScript generation and requires a corresponding TypeScript
+module at semantic validation. It does not add an empty C# package to API navigation.
+Build-only packages without public types or generated-export opt-ins remain explicit skips.
+
 The generated JSON follows this schema:
 
 ```json
@@ -205,6 +235,29 @@ pnpm --filter ./src/frontend run update:ts-api
 
 The companion `generate-ts-api-json.ps1` script reads the generated C# package JSON files in `src/frontend/src/data/pkgs/`, selects `Aspire.Hosting`, `Aspire.Hosting.*`, and `CommunityToolkit.Aspire.Hosting.*` packages, and passes each package/version through to `aspire sdk dump`. This keeps `src/frontend/src/data/ts-modules/` aligned with the same package set and versions that already flowed through C# API generation.
 
+Radius versions exporting the generic `IDotnetProgramResource` overload are
+scanned with `Aspire.Hosting.Dotnet` as supporting context. Its exact version
+comes from the generated C# metadata, so the scanner can retain the export on
+`DotnetProjectResource` while the concrete overload serves legacy project
+resources. Generate the Dotnet module first when regenerating Radius selectively.
+The transformer excludes core and supporting APIs using their generated modules;
+it preserves Radius's real capability IDs and expanded receiver targets.
+A scanner collision that removes the generic export must be fixed upstream,
+not hidden by changing the C# metadata or weakening API-reference validation.
+
+For generated-export overlays, the script also obtains the matching
+`aspire sdk export --language typescript` document. Referenced SDK enum definitions
+missing from the raw dump are taken from that canonical export, with package identity
+and unambiguous ownership checks. Union members are preserved during transformation;
+missing or unsupported enum definitions fail generation rather than becoming empty
+interface stubs. Semantic validation checks enum members in the final Twoslash bundle.
+The bundle represents enums as string unions with companion constant objects.
+When independent packages export the same enum short name, the shared bundle
+combines their literals; each package's API JSON retains its exact enum surface.
+Use the package-specific SDK to validate behavior that depends on those differences.
+The generator rejects nonzero SDK dump exits and error diagnostics even when a JSON
+file was produced. An incomplete dump isn't a successful API-generation result.
+
 When a TypeScript module is regenerated for a new package version, stale `ts-modules` JSON files for older versions of that same package are deleted automatically. Regenerated modules with no functions or types are omitted from `src/frontend/src/data/ts-modules/`.
 
 After the JSON is refreshed, `update-ts-api` automatically chains `generate-twoslash-types.ts` to rebuild `src/frontend/src/data/twoslash/aspire.d.ts`. This bundle is source-controlled and its diff must be committed alongside the `ts-modules` JSON changes — without it, docs hover tooltips fall back to `any`. If you only need to refresh the bundle (e.g. after a generator script change) without running the full SDK dump, use:

.agents/skills/whatsnew/SKILL.md

@@ -62,6 +62,15 @@ infer from context — e.g. a fresh release with no page → `draft`).
   distinct **"New integrations"** section for brand-new ones; a **"Default container
   image updates"** section for tag bumps. The release-date badge + GitHub release-notes
   link render **automatically** from `publishDate` + slug — never hand-place them.
+- **Resource artwork:** Every new release page must set `resourceImage` to newly
+  captured screenshots demonstrating a feature introduced in that release, with
+  matching `light`/`dark` variants. Verify the running product version and capture
+  its actual UI; do not substitute generic dashboard artwork, an older release's
+  screenshots, or fabricated UI. Store the files in the release's assets folder
+  before adding their paths, and show them beside the feature in the article. The
+  resource directory discovers release pages and consumes this frontmatter
+  automatically; do not add a duplicate catalog entry. Verify the card's image
+  and release metadata in the resource-catalog tests and browser preview.
 
 ### Safety / mechanics
 - **Never run `pnpm build` locally** — validate build-readiness by inspection.

.agents/skills/whatsnew/references/01-draft-scaffold.md

@@ -34,6 +34,16 @@ duplicating.
    the **content-standards taxonomy**: Deployment and Integrations **separate**, plus
    dedicated **"New integrations"** and **"Default container image updates"** sections.
    If the file already exists, reconcile structure without clobbering existing content.
+   The template's `{{RESOURCE_IMAGE_LIGHT}}` and `{{RESOURCE_IMAGE_DARK}}` tokens
+   must resolve to newly captured screenshots of a feature introduced in this
+   release. Verify the running product version, exercise the feature, and capture
+   the same UI state in both themes. Store the files under the release assets folder
+   and then set `resourceImage` to their `~/assets/whats-new/...` paths. Never use
+   generic or older-release artwork, fabricate UI, or point at nonexistent files.
+   If capture isn't possible during scaffolding, omit `resourceImage` temporarily
+   and track it as a required research/polish task; do not consider validation complete.
+   The resource directory automatically includes the page as `release-notes` and
+   reads its image and `publishDate`; no separate catalog entry is needed.
 3. **Version constants.** Update `src/frontend/config/aspire-versions.mjs`:
    `currentAspireMajorMinorVersion = 'N.N'`, `currentAspireVersion` to the latest
    stable `N.N.PATCH`, and `currentAspirePreviewVersion` to the matching full
@@ -55,8 +65,9 @@ duplicating.
    `{ label: 'Aspire N.N', slug: 'whats-new/{SLUG}' }` at the **top** of the What's-new
    `items`. Roll the now-older version into the "Previous versions" group per the
    existing pattern.
-6. **Assets folder.** Create `src/frontend/src/assets/whats-new/aspire-{VERSION_FULL}/`
-   (empty) for screenshots to land later.
+6. **Assets.** Create `src/frontend/src/assets/whats-new/aspire-{VERSION_FULL}/`
+   only when adding actual screenshots. Do not create an empty directory or
+   `.gitkeep`; reused shared artwork needs no release-specific folder.
 7. **Commit the scaffold.** Stage and commit all of the above on `release/{N.N}` so the
    branch has a diff against the default branch (nothing to PR otherwise).
 8. **Draft PR.** *Now* open a **draft** PR from `release/{N.N}` into the repository's
@@ -72,5 +83,8 @@ duplicating.
 
 - Page exists and is structurally sound (frontmatter + imports + section skeleton).
 - Sidebar resolves the new slug; banner points at the new article across locales.
+- Release-specific screenshots exist and `resourceImage` resolves to them, or
+  their capture is explicitly tracked as incomplete. The resource directory
+  discovers one release-notes entry with the expected metadata.
 - Version constants updated; draft PR is open.
 - **No researched prose yet** — only structure and placeholders.

.agents/skills/whatsnew/references/04-validate.md

@@ -34,6 +34,14 @@ then **fix → re-review → repeat** until it converges clean:
   targets.
 - **Banner + version wiring:** banner points at the new article across locales; version
   constants in `aspire-versions.mjs` are correct.
+- **Resource directory:** `resourceImage` is present and every configured image
+  resolves to a newly captured screenshot of a feature introduced in this release.
+  Verify capture provenance (product version, scenario, and actual UI state);
+  generic artwork or older-release screenshots fail this gate even if they exist.
+  Show the screenshots beside the feature in the article with descriptive alt text.
+  Run `dev-resource-catalog.vitest.test.ts` and preview the release card
+  under `/hub/browse/` in both themes. Confirm one `release-notes` entry with the
+  correct link, title, date, and artwork; do not hand-maintain a duplicate catalog.
 
 ## Editorial guardrails enforced here