fix - change trigger and output behavior

.github/workflows/www-tests.yml

@@ -8,6 +8,7 @@ on:
       - 'apps/www/**/*.ts*'
       - 'apps/www/package.json'
       - 'apps/www/turbo.jsonc'
+      - 'apps/www/vercel.json'
       - 'scripts/upload-static-assets.sh'
       - 'packages/common/sentry.ts'
       - 'packages/common/sentry.test.ts'
@@ -15,6 +16,7 @@ on:
       - 'apps/www/next.config.js'
       - 'apps/www/lib/**/*.js'
       - 'apps/www/lib/**/*.mjs'
+      - 'apps/www/lib/**/*.json'
       - 'apps/www/content/md/**'
       - 'apps/www/scripts/**/*.mjs'
       - 'apps/www/internals/**/*.mjs'
@@ -67,6 +69,12 @@ jobs:
       - name: Install deps
         run: pnpm install --frozen-lockfile
 
+      - name: Check docs-redirects-md-variants.json is up to date
+        run: |
+          pnpm run generate:docs-redirects-md-variants
+          git diff --exit-code -- lib/bulk-redirects/docs-redirects-md-variants.json
+        working-directory: ./apps/www
+
       - name: Run tests
         run: pnpm run test
         working-directory: ./apps/www

AGENTS.md

@@ -44,7 +44,7 @@ pnpm api:codegen             # platform Management API types → packages/api-ty
 
 Every PR must pass typecheck + lint (one workflow), Prettier, and a typos check. Other checks are path-filtered: Studio unit tests/build and the lint ratchet (ESLint warning count must not increase) run on `apps/studio/**` changes and the Tailwind class rules (`shadcn/*`) for `www`, `docs`, `design-system`, `ui-library`, and `learn`; app-specific test suites run on their own paths.
 
-Never hand-edit generated files: `packages/api-types/types/**`, `**/routeTree.gen.ts`, `**/__generated__/**`, `apps/docs/features/docs/generated/**`, `apps/www/.generated/**`, `supabase/functions/common/database-types.ts`, `apps/docs/content/_partials/access-control/scoped_pat_*.mdx` (run `make -C apps/docs/spec generate.partials.access-control`).
+Never hand-edit generated files: `packages/api-types/types/**`, `**/routeTree.gen.ts`, `**/__generated__/**`, `apps/docs/features/docs/generated/**`, `apps/www/.generated/**`, `supabase/functions/common/database-types.ts`, `apps/docs/content/_partials/access-control/scoped_pat_*.mdx` (run `make -C apps/docs/spec generate.partials.access-control`), `apps/www/lib/bulk-redirects/docs-redirects-md-variants.json` (run `pnpm run generate:docs-redirects-md-variants` in `apps/www`).
 
 ## Conventions
 

apps/www/lib/bulk-redirects/README.md

@@ -16,10 +16,19 @@ Add static redirects (simple `/old → /new` mappings with **no** `:path*`, `:ma
 
 ## Markdown Variants
 
-The build process automatically generates `.md` variants for any `/docs/guides/` redirects in `docs.json`. For example:
+**`docs-redirects-md-variants.json` is a generated file — do not hand-edit it.**
+
+It's derived from any `/docs/guides/` redirects in `docs.json`. For example:
 
 - `/docs/guides/api/api-keys` → generates `/docs/guides/api/api-keys.md`
-- This is written to `docs-md-variants.json` which Vercel also reads
+
+Regenerate it after changing `docs.json`:
+
+```bash
+pnpm run generate:docs-redirects-md-variants
+```
+
+CI fails the build if this file is out of sync with `docs.json` (see `.github/workflows/www-tests.yml`).
 
 ## Dynamic Redirects
 
@@ -27,4 +36,4 @@ Redirects with path matching patterns (`:path*`, `:match*`, regex) stay in `lib/
 
 ## Deployment
 
-The `prebuild` hook runs `generate-docs-md-variants.mjs` before each build, creating `.md` variants. Vercel then reads all `.json` files from this folder and serves them at the edge.
+Vercel reads all `.json` files from this folder (via `vercel.json`'s `bulkRedirectsPath`) and serves them at the edge. There's no build-time generation step — `docs-redirects-md-variants.json` is committed directly, like `docs.json` and `blog.json`.

apps/www/lib/bulk-redirects/docs-redirects-md-variants.json

@@ -0,0 +1,7 @@
+[
+  {
+    "permanent": true,
+    "source": "/docs/guides/api/api-keys.md",
+    "destination": "/docs/guides/getting-started/api-keys.md"
+  }
+]

apps/www/package.json

@@ -6,7 +6,8 @@
   "scripts": {
     "preinstall": "npx only-allow pnpm",
     "dev": "pnpm run content:build:core && next --port 3000",
-    "prebuild": "node scripts/generate-docs-md-variants.mjs && pnpm --filter=docs run build:federated-content && pnpm --filter=docs run build:guides-markdown && pnpm run content:build",
+    "prebuild": "pnpm --filter=docs run build:federated-content && pnpm --filter=docs run build:guides-markdown && pnpm run content:build",
+    "generate:docs-redirects-md-variants": "node scripts/generate-docs-redirects-md-variants.mjs",
     "build": "turbo run build:next --filter=www",
     "build:next": "next build && node ./internals/generate-sitemap.mjs",
     "export": "next export",

apps/www/scripts/generate-docs-redirects-md-variants.mjs

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 /**
- * Generate .md variants for /docs/guides/ redirects
- * Matches the logic in next.config.mjs line 215-222
+ * Generates lib/bulk-redirects/docs-redirects-md-variants.json — a checked-in
+ * generated file, not a build step. Run after editing lib/bulk-redirects/docs.json:
+ *   pnpm run generate:docs-redirects-md-variants
+ * CI verifies this output is in sync (see .github/workflows/www-tests.yml).
+ * Matches the .md-variant logic in next.config.mjs's redirects().
  */
 
 import fs from 'fs'
@@ -10,7 +13,7 @@ import { fileURLToPath } from 'url'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const docsPath = path.join(__dirname, '../lib/bulk-redirects/docs.json')
-const outputPath = path.join(__dirname, '../lib/bulk-redirects/docs-md-variants.json')
+const outputPath = path.join(__dirname, '../lib/bulk-redirects/docs-redirects-md-variants.json')
 
 const docs = JSON.parse(fs.readFileSync(docsPath, 'utf-8'))
 
@@ -25,7 +28,7 @@ const mdVariants = docs
 
 if (mdVariants.length > 0) {
   fs.writeFileSync(outputPath, JSON.stringify(mdVariants, null, 2) + '\n')
-  console.log(`✓ docs-md-variants.json (${mdVariants.length} variants)`)
+  console.log(`✓ docs-redirects-md-variants.json (${mdVariants.length} variants)`)
 } else {
   if (fs.existsSync(outputPath)) fs.unlinkSync(outputPath)
 }