Process — Docs Publish Flow

Process — Docs Publish Flow

Sub-system: 11 — docs-site Related spec: ../specs/2026-05-23-11-docs-site-design.md

Author edits a spec MD in docs/superpowers/ → PR → CI build → sync script copies into docs-site/src/content/docs/ → Astro builds → Cloudflare Pages deploys → DNS at docs.nowyourlink.com resolves the new build.

Sequence

Failure modes

Step	Failure	Handling
sync-specs.mjs	Secret pattern detected in spec MD	Build fails; author rewrites spec, removes secret, force-pushes.
link-check.mjs	Cross-link broken after rename	Build fails with suggested redirect; author adds entry to _redirects or fixes the link.
astro build	Mermaid parse error	Build fails; author fixes diagram syntax in source MD.
Pagefind postbuild	Index too large (>50 MB)	Warning only at MVP; tracked for Phase 2 (incremental indexing).
CF Pages upload	Build artifact >25 MB single file	Fail; investigate (usually an accidentally committed image).
DNS	docs.nowyourlink.com not resolving	Check Terraform state; CNAME flattening at apex zone (D24).
CF Access	/internal/* returns 500 not 302	Verify ACCESS_AUD env in Pages settings matches the docs-internal application audience.

Cadence & invariants

• Every merge to main triggers production deploy. No scheduled rebuilds.
• The source-of-truth for spec content is always docs/superpowers/. The docs-site/src/content/docs/sub-systems/ tree is regenerated on every build and is .gitignore-d.
• Preview deploys are publicly reachable (matches build-in-the-open posture); confidential drafts use status: confidential front-matter and are skipped by sync-specs.mjs.