docs: Astro 6 upgrade tracker (apps/docs) — blocked on Starlight

[beeeku]

Context

Dependabot opened #110 to bump astro 5.18.1 → 6.1.8 in apps/docs. CI has been red since 2026-04-21 because the upgrade can't be done as a drive-by — it's a real migration. This issue captures the work so the dependency PR can be closed without losing the intent.

Blockers

From bun.lock:

• @astrojs/starlight@0.33.2 peer-deps astro: ^5.1.5 → no Starlight release supports Astro 6 yet. This is the gating blocker.
• @astrojs/tailwind@6.0.2 peer-deps astro: ^3 || ^4 || ^5. The package itself is being deprecated upstream in favor of the Vite Tailwind v4 plugin path.

Migration shape (when Starlight ships v6 support)

1. Bump @astrojs/starlight to whatever release first declares astro: ^6.
2. Bump astro itself in apps/docs/package.json.
3. Drop @astrojs/tailwind from dependencies; switch astro.config.mjs to the Vite @tailwindcss/vite plugin (Tailwind v4 path) — confirm @astrojs/starlight-tailwind@3.0.x still works against the new wiring or wait for a Starlight Tailwind release that targets v4.
4. Validate: bun --cwd apps/docs run typecheck && bun --cwd apps/docs run build. Spot-check Starlight nav, search (pagefind), code blocks (astro-expressive-code), and the dark theme.
5. wrangler pages deploy preview on a branch deploy before landing.

Risk areas

• Tailwind v3 → v4 config migration (tailwind.config.ts → CSS-first config).
• zod jump from v3 to v4 transitively via Astro 6 — content collections that import z from astro:content may shift behavior.
• vite ^6 → ^7 inside Astro — any custom Vite plugins in astro.config.mjs (currently none, but verify) need a compatibility check.

Acceptance

• apps/docs builds and deploys against astro@^6.
• No @astrojs/tailwind dependency.
• Starlight site renders identically (visual diff acceptable to maintainer).
• Dependabot can resume bumping Astro within v6 once landed.

Refs

• chore(deps): bump astro from 5.18.1 to 6.1.8 in /apps/docs in the npm_and_yarn group across 1 directory #110 — the failing Dependabot PR; recommend closing with @dependabot ignore this major version until this issue is actionable.