Context

Dependabot opened #347 to bump astro in /site from 6.4.8 → 7.0.1. Astro 7 is a major release with breaking changes, so we held off auto-merging it. This issue tracks the full migration so it can be done safely in one PR.

Close #347 in favor of this issue's PR (or update #347 to also bump Starlight). Astro 7 also requires astro@^7.0.2, so use astro@^7.0.2 or later — not just ^7.0.1.

Scope

Files in scope: everything under /site (Starlight docs site that deploys to GitHub Pages at https://microsoft.github.io/waza). Do not touch /web (the dashboard).

Goal

Upgrade /site to Astro 7 with a compatible Starlight version, verify the docs site still builds and renders correctly, and update CI/docs as needed.

Tasks

• In site/package.json, bump:
  • astro from ^6.4.7 to ^7.0.2 (or latest 7.x)
  • @astrojs/starlight from ^0.40.0 to ^0.41.1 (or latest — this version requires astro@^7.0.2, confirmed via npm registry)
• Run cd site && rm -rf node_modules package-lock.json && npm install to regenerate the lockfile cleanly
• Run cd site && npm run build and ensure it completes with no errors
• Run cd site && npx playwright test (if site/e2e/ tests exist and run in CI) — fix any failures
• Spot-check rendered output for whitespace regressions caused by the compressHTML default change to 'jsx' in Astro 7 (it now strips whitespace using JSX rules by default). If any docs page has visibly broken inline-element spacing, set compressHTML: true in site/astro.config.mjs to preserve the previous HTML-aware behavior. Pay attention to MDX pages with inline <code>, <a>, or custom components.
• Verify site/astro.config.mjs still type-checks (// @ts-check is at the top); update any Starlight option shapes if the new version changed them
• Check that the GitHub Pages deploy workflow still works against Astro 7 (actions/deploy-pages and the build step)
• Close PR chore(deps): Bump astro from 6.4.8 to 7.0.1 in /site #347 once this PR is merged, since it only bumps Astro without Starlight

Non-breaking-but-relevant changes in Astro 7

Reference: https://github.com/withastro/astro/releases

• Vite v8 is now required transitively (no action needed in our site since we don't import Vite directly).
• @astrojs/db removed. ✅ We don't use it (verified — no references in /site), so no action.
• compressHTML default flipped to 'jsx'. ⚠️ See task above.
• New astro dev --background mode for AI agents. Optional, doesn't affect us.

Acceptance criteria

• cd site && npm install && npm run build succeeds locally and in CI
• No visual regressions in the deployed docs site (check Home, Quick Start, all Guides, all Reference pages, About)
• site/package.json lists astro@^7.0.2 (or later) and @astrojs/starlight@^0.41.x (or later)
• site/package-lock.json is regenerated
• PR description notes which Astro 7 breaking changes were evaluated and why each is safe (or what was changed)
• PR closes chore(deps): Bump astro from 6.4.8 to 7.0.1 in /site #347

Out of scope

• Don't touch /web or the Go code
• Don't bump unrelated dependencies in /site (e.g. sharp, @playwright/test) in the same PR — keep this focused on the Astro/Starlight upgrade

Branch & PR conventions

Per AGENTS.md, use squad/{issue-number}-{slug} branch naming and reference this issue with Closes #{issue-number} in the PR body.