Refresh Community Toolkit catalog and add mapping guardrails

[IEvangelist]

Summary

• refresh the NuGet-backed integration catalog, adding 13 newly published Community Toolkit packages
• remove duplicate and stale Community Toolkit documentation mappings while preserving Bun migration guidance
• add mapping guardrails for catalog membership, unique package IDs, trailing slashes, and real internal destinations
• align integration authoring guidance with current commands and capability-based page shapes

This is the first independently reviewable change in the Community Toolkit documentation audit series.

Validation

• pnpm --dir ./src/frontend test:unit:structured-data (17 tests)
• integration gallery and representative mapped routes verified with Playwright CLI

[Copilot]

Pull request overview

This PR refreshes the NuGet-backed integrations catalog and tightens Community Toolkit documentation mapping guardrails, while also updating the internal agent/skill guidance for maintaining integration docs and data.

Changes:

• Adds unit-test guardrails for CommunityToolkit integration-doc mappings (uniqueness, catalog membership, trailing slashes, and on-disk page existence).
• Removes duplicate/stale CommunityToolkit entries from integration-docs.json.
• Refreshes aspire-integrations.json package metadata (versions/downloads/descriptions) and updates documentation authoring guidance to match current commands/page shapes.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/frontend/tests/unit/update-integrations.vitest.test.ts	Adds mapping guardrail tests for Community Toolkit integration-doc entries.
src/frontend/src/data/integration-docs.json	Removes duplicated/stale Community Toolkit doc mappings.
src/frontend/src/data/aspire-integrations.json	Refreshes the integration catalog data (new Community Toolkit packages + updated package metadata).
.github/agents/community-toolkit-integration-doc-writer.agent.md	Updates agent instructions to use authoritative sources and current multi-page integration doc shapes.
.agents/skills/update-integrations/SKILL.md	Updates the “update integrations” workflow guidance to current pnpm commands and page verification expectations.
.agents/skills/doc-writer/SKILL.md	Aligns doc-writer guidance with the current integration update workflow and structured-data validation.

---

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

[aspire-repo-bot]

Frontend HTML artifact ready

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

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

[IEvangelist]

📋 Docs-accuracy review — PR #1372

Automated two-phase review (doc-pr-reviewer skill). Phase A verifies every factual claim against source of truth; Phase B validates the rendered docs as a blind new user via doc-tester.

Sources of truth used

Repo	Ref	SHA
CommunityToolkit/Aspire	main	b9d40479
microsoft/aspire.dev (self)	PR head dapine/community-docs-mapping-guardrails	00a87805
microsoft/aspire	—	not needed (no core Aspire API claims in this PR)

(merge-base with main: 7e8dd9db)

Phase A — claims: 7 non-narrative claim groups extracted → 7 verified, 1 verified-with-nuance, 0 contradicted, 0 unverifiable.
Phase B — doc-tester: 4 routes + gallery searches + logo rendering exercised on the served PR head → doc-tester reported 1 "critical" and 1 warning. The "critical" was reconciled against source in Phase C and is expected, pre-existing behavior — not a defect in this PR (details below). The warning is a pre-existing logo-asset concern.

Verdict: 🟡 COMMENT — no accuracy defects found. Everything the PR asserts checks out; the only open items are one cosmetic nuance and one pre-existing logo concern, neither blocking.

---

Phase A — Claim verification

Every claim in the PR description and changed guidance was confirmed. No contradicted or unverifiable claims, so there are no blocking inline comments.

⚠️ One nuance worth a look

CommunityToolkit.Aspire.Hosting.Bun catalog entry — icon URL version ≠ listed version. In src/frontend/src/data/aspire-integrations.json, this entry has "version": "13.3.0" (stable) but its "icon" URL points at .../communitytoolkit.aspire.hosting.bun/13.4.1-beta.686/icon. Every other new Community Toolkit entry uses a matching version in both fields. This is a data-generation artifact from update:integrations (not a documentation prose claim), so it's non-blocking — but you may want to confirm the generator is intentionally resolving the icon from a prerelease build for stable-versioned packages.

✅ Verified claims (8) — evidence

1. "13 newly published Community Toolkit packages" — VERIFIED. The catalog delta is exactly +13 / −0 CommunityToolkit.Aspire.* titles, and all 13 exist as src/<PackageId>/ project folders in CommunityToolkit/Aspire@b9d40479: Bitwarden.SecretManager, DuckDB.NET.Data, Hosting.Bitwarden.SecretManager, Hosting.Bun, Hosting.Dbx, Hosting.DuckDB, Hosting.K3s, Hosting.Logto, Hosting.RustFs, Hosting.SeaweedFS, Hosting.Squad, Logto.Client, SeaweedFS.Client.

2. "remove duplicate and stale mappings while preserving Bun migration guidance" — VERIFIED. The 6 removed integration-docs.json entries break down as: 5 exact duplicates — Hosting.Azure.Dapr.Redis, Hosting.Dapr.AzureRedis, Hosting.Flagd, Hosting.GoFeatureFlag, Hosting.PowerShell each appeared twice in the base file with identical match+href and now appear once; and 1 stale mapping — Hosting.Azure.StaticWebApps, whose match is not present in the current catalog. Bun is preserved: CommunityToolkit.Aspire.Hosting.Bun → /integrations/frameworks/bun-apps/ remains, the page frameworks/bun-apps.mdx exists, and the package is now a catalog entry.

3. "mapping guardrails for catalog membership, unique package IDs, trailing slashes, and real internal destinations" — VERIFIED. tests/unit/update-integrations.vitest.test.ts adds exactly three checks (maps each package at most once; only maps packages in the current catalog; trailing-slash links to existing pages via docsPageExists). Re-ran the same logic against head data independently: 40 Community Toolkit mappings — 0 duplicates, all present in the catalog, all trailing-slashed and resolving to a real .mdx/index.mdx. These tests run under pnpm --dir ./src/frontend test:unit:structured-data (confirmed in package.json), matching the PR's stated validation.

4. import { Image } from "astro:assets" (named import) — VERIFIED. All 14 .astro components in src/frontend/src/components use the named import; the prior default import shown in the guidance (import Image from "astro:assets") was incorrect, and this corrects it.

5. ThemeImage light/dark props + automatic fit="contain" — VERIFIED. ThemeImage.astro's Props interface declares light/dark (not lightSrc/darkSrc), and the component now sets fit: 'contain' in both imageOptions and themedImageProps, so "ThemeImage applies contained fitting automatically" holds. The custom-components.vitest.test.ts expectation (fit=contain) is consistent.

6. pnpm --dir ./src/frontend update:integrations / test:unit:structured-data commands — VERIFIED. Both scripts exist in src/frontend/package.json (update:integrations → tsx ./scripts/update-integrations.ts). The old node scripts/update-integrations.js reference in the guidance was outdated (script is now .ts), so the update is accurate.

7. Referenced doc pages — VERIFIED. integrations/caching/redis/redis-get-started.mdx (the new entry-format example target), the three integrations/ai/ollama/ollama-{get-started,host,connect}.mdx pages, and integrations/frameworks/rust.mdx all exist. The previously-referenced databases/kurrentdb.mdx example was correctly dropped — that flat page no longer exists.

8. Sidebar file rename sidebar.topics.ts → integrations.topics.ts — VERIFIED. src/frontend/config/sidebar/integrations.topics.ts exists on head.

---

Phase B — doc-tester results

Served the PR head locally (http://localhost:4326/, HTTP 200) and navigated only with the Playwright CLI, blind to source code. Routes exercised: /integrations/gallery/ (+ ?official=false and package-name searches), /integrations/frameworks/rust/, /integrations/caching/redis/redis-get-started/, /integrations/frameworks/bun-apps/, and NuGet link spot-checks.

🔴 doc-tester "critical" — reclassified as expected behavior (non-blocking)

doc-tester finding: Exact gallery searches returned "No integrations found" for CommunityToolkit.Aspire.Bitwarden.SecretManager, CommunityToolkit.Aspire.DuckDB.NET.Data, CommunityToolkit.Aspire.Logto.Client, and CommunityToolkit.Aspire.SeaweedFS.Client.

Phase C reconciliation — this is intended, and the PR handles it correctly. Those four packages are exactly the four client-tagged entries among the 13 additions (the other nine are hosting and did render). Integrations.astro gates client cards behind a feature flag:

// Default (flag not 'true') hides client cards from the gallery page ...
// The underlying data files, API docs, and content articles continue to be
// generated/updated regardless of this flag.
const showClientIntegrations = import.meta.env.PUBLIC_SHOW_CLIENT_INTEGRATIONS === 'true';
const visibleIntegrations = showClientIntegrations
  ? integrations
  : integrations.filter((i) => !(i.tags ?? []).includes('client'));

So with the default flag value, client-tagged integrations are deliberately excluded from the gallery cards/search, while the data files are still expected to carry them — which is precisely what this PR does. This behavior is pre-existing and independent of PR #1372, so no change is required. (The doc-tester correctly flagged it given its blind-to-source constraint; this is the intended Phase A↔B reconciliation.)

🟡 Warning — Rust logo dark-theme contrast (pre-existing, asset-level)

The Rust logo renders uncropped and correctly sized (the PR's fit="contain" change works), but the transparent logo's dark portions are low-contrast on the dark-theme background. This is a property of the existing rust-icon.png asset, not something this PR introduces or regresses — worth considering a dark-variant/outline later, but not blocking here.

✅ doc-tester passed checks (verbatim)

• Gallery loads at /integrations/gallery/; Community-only filter renders Community Toolkit entries.
• Nine expected hosting cards present: Bun, Dbx, DuckDB, K3s, Logto, RustFs, SeaweedFS, Squad, Hosting.Bitwarden.SecretManager.
• Spot-checked NuGet package links resolved successfully.
• Bun gallery link resolves to /integrations/frameworks/bun-apps/.
• /integrations/caching/redis/redis-get-started/ renders (not a 404).
• Redis and Rust logos render with object-fit: contain, 100×100, no cropping; screenshots captured desktop/mobile × light/dark.

Knowledge gaps: none — only the rendered site and browser-visible evidence were used; no Aspire source repos were read.

---

Bottom line

Everything this PR claims is accurate: the 13 packages are real, the mapping removals are genuinely duplicate/stale, Bun guidance is preserved, the guardrail tests do what the summary says (and pass on head data), and the authoring-guidance corrections (Astro named import, ThemeImage props, fit="contain", pnpm commands, page references) all match the code. The only follow-ups are the optional Bun icon-version nuance and the pre-existing Rust dark-logo contrast — neither blocks this change.

_{🤖 Generated with the doc-pr-reviewer skill.}