Whitepaper route check — debugging and recovery

A whitepaper chapter can be missing from the live site (rig-docs.pages.dev) even when its source .md file is in main and CI shows green. This runbook covers the diagnostic tree and recovery steps.

Symptoms

• /whitepaper/<slug>/ returns 404
• gh api repos/dashecorp/rig-docs/contents/src/content/docs/whitepaper/<slug>.md returns the file
• GitHub Actions deploy.yml shows success for the build job

Root causes (ordered by likelihood)

#	Cause	Signal
1	Build cancelled by concurrent run	cancel-in-progress: true in deploy.yml — a later push or scheduled run may have cancelled the merge-triggered build mid-deploy
2	Frontmatter fails Zod schema (silent exclusion)	Page absent from dist/ even when npm run build exits 0 — Astro may warn but not fail on certain schema violations
3	draft: true in frontmatter	Astro drops draft pages in production builds
4	CF Pages serving stale cache	Direct upload via wrangler should prevent this but can occur during edge propagation

Diagnostic steps

1. Check whether the page was in the last dist/

Look at the most recent successful workflow run on main. Download the dist artifact and confirm:

unzip dist.zip dist/whitepaper/<slug>/index.html
echo $?  # 0 = present, non-zero = absent

If absent → the build silently excluded the page. Move to step 2. If present → the deploy didn’t propagate. Move to step 4.

2. Check frontmatter against the schema

Compare the file’s frontmatter with src/content.config.ts:

# Run locally to surface Astro validation warnings
npm run build 2>&1 | grep -i 'warn\|error\|invalid\|<slug>'

Key fields the Zod schema enforces:

Field	Allowed values
type	research, proposal, decision, postmortem, reference, user-story, runbook, story, whitepaper
audience	human, agent, both
updated	Any string (date recommended)
topic	Any string

Note: audience values in the schema are singular (human, agent) not plural.

3. Check for draft flag

head -20 src/content/docs/whitepaper/<slug>.md | grep draft

If draft: true is present, remove it.

4. Force a fresh deploy

Push a trivial commit (e.g. touch the .md file or add a redirect in astro.config.mjs). This triggers a new build+deploy that bypasses any cached or cancelled state:

git commit --allow-empty -m "chore: force redeploy for /whitepaper/<slug>/"
git push

5. Verify via CI check

The CI check added in #256 catches this class of failure automatically:

npm run build && node scripts/check-whitepaper-routes.mjs

If check-whitepaper-routes.mjs exits 1, the page was not generated — fix the frontmatter and rebuild. If it exits 0, the page is in dist/ — investigate the deploy step.

Prevention

The check-whitepaper-routes.mjs script runs in CI after every build (added in #256). Any future missing route fails the workflow before the artifact is uploaded or deployed.

When adding a new whitepaper chapter:

1. Add the .md to src/content/docs/whitepaper/.
2. Add a '/whitepapers/<slug>/': '/whitepaper/<slug>/' redirect to astro.config.mjs.
3. Run npm run build && node scripts/check-whitepaper-routes.mjs locally before pushing.