fix: resolve /404 route collision and prerender header warnings

[rachaelrenk]

Summary

Two build-health fixes for the docs site, both surfaced while investigating the token-usage guide PR (#269) Vercel preview:

1. Resolves the /404 route collision (which Astro warns will become a hard error in a future version).
2. Eliminates the Astro.request.headers-on-prerendered-pages warning (~692 per build).

Changes

1. /404 route collision

• Delete src/pages/404.astro — a second /404 route that collided with Starlight's built-in one (@astrojs/starlight/routes/static/404.astro).
• Add src/content/docs/404.mdx — Starlight's supported content-collection 404 override (get404Route → getEntry('docs', '404')), so there is a single prerendered /404 route.
• Add src/components/Docs404Tracking.astro — holds the docs_404 Rudderstack tracking script (kept in an .astro component because MDX parses {/} as expressions).

2. Astro.request.headers warning

• src/middleware.ts (content negotiation) called shouldServeMarkdown(request), reading request.headers on every route. During the static prerender pass there is no real request, so Astro warned "Astro.request.headers is not available on prerendered pages" ~692 times per build. Guarded with context.isPrerendered so the header read only runs for on-demand (SSR) requests. Runtime markdown content negotiation is unchanged.

Preserves the 404 monitoring pipeline

The custom 404 fires a docs_404 Rudderstack event with the broken URL, consumed by the weekly-404-monitor agent (queries docs_404 from BigQuery). This PR keeps that contract identical — same docs_404 event name and broken_url / referrer properties — so the monitor is unaffected. Verified the built 404.html still contains the tracking.

Validation

• npm run build passes (346 pages).
• /404 route-collision warning: gone.
• Astro.request.headers warnings: 692 → 0.
• docs_404 present in both dist/404.html and .vercel/output/static/404.html.
• style_lint: 0 issues on the new page.

Context

Follow-up from the token-usage guide PR (#269): its failing Vercel preview led to investigating these. That Vercel failure was transient and is now green; this PR proactively removes the latent collision and clears the header-warning noise.

Conversation: https://staging.warp.dev/conversation/a00f71f5-5c1a-450b-ada7-0d6180380fe3

Co-Authored-By: Oz oz-agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jul 9, 2026 8:26pm

[oz-for-oss]

@rachaelrenk

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR removes the project-level src/pages/404.astro route that collides with Starlight's injected /404 route, replaces it with Starlight's supported src/content/docs/404.mdx content override, and preserves the existing docs_404 Rudderstack tracking payload in a dedicated Astro component.

Concerns

• No blocking correctness, security, or spec-alignment concerns found in the annotated diff.
• spec_context.md reports that no approved or repository spec context was found, so there was no spec contract to validate beyond the PR description and diff.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[hongyi-chen]

nice fix, ty!