docs: add discovery validation tooling

[desimone]

Add the docs-side validation tooling for discovery and retrieval work.

What changed

• add a standalone docs audit for frontmatter and llms.txt issues
• add a retrieval benchmark scaffold and prompt set for current docs questions
• add a flexible discovery smoke check for root/docs/agent surfaces
• wire the scripts into package.json without making them a default build gate

Why

• ENG-3735 needs reproducible validation, not just one-off manual checks
• the earlier audit/benchmark branch was cut before the repo-wide Prettier normalization and before the shared-LB docs/marketing split was fully accounted for
• the smoke check now understands preview-vs-canonical divergence via --base-url and --canonical-base-url, which matters for www.pomerium.com because root traffic defaults to marketing and docs is path-routed behind the LB

Validation

• yarn build
• yarn run check
• node scripts/retrieval-benchmark.mjs init --output <file>
• node scripts/retrieval-benchmark.mjs score --input <file>
• node scripts/discovery-smoke-check.mjs --base-url https://deploy-preview-2117--pomerium-docs.netlify.app --canonical-base-url https://www.pomerium.com --check robots,docsSitemap,llms
• node scripts/discovery-smoke-check.mjs --base-url https://deploy-preview-2116--pomerium-docs.netlify.app --canonical-base-url https://www.pomerium.com --check llms,llmsFull

Related

• ENG-3735 Discovery Quality Validation and Ops
• supersedes the earlier closed validation attempts in docs: add docs audit and retrieval benchmark scripts #2110 and docs: add discovery smoke check #2115
• pairs with docs: add root robots.txt and tighten primary sitemap #2117 and https://github.com/pomerium/infrastructure/pull/407 for the primary discovery-surface recovery

AI assistance

• Codex drafted the implementation, ran the validation steps above, and refreshed the branch onto current main
• Claude reviewed the final tooling diff and found no material issues; the only follow-up it suggested that I kept was adding a timeout to the smoke-check fetches and using yarn build consistently in the strict audit script

[netlify]

✅ Deploy Preview for pomerium-docs ready!

Name	Link
🔨 Latest commit	ce8ef50
🔍 Latest deploy log	https://app.netlify.com/projects/pomerium-docs/deploys/69bb7d4e9fba7d0008d2efb2
😎 Deploy Preview	https://deploy-preview-2120--pomerium-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.