Site workflow

End-to-end build workflow for a11yequitas.org — from Zed + Claude Code in the editor, through orchestrated AI agents, accessibility and security audits, and finally to production on Rocky Linux. Every step gates the next; nothing ships without a clean audit.

10 steps, dev → production

1. Develop in Zed with Claude CodeZed IDE drives editing of the local working tree; Claude Code (this assistant) runs slash commands and skills directly against it.
2. Edit content + structure via AI orchestrationClaude Code agents (caveman investigator / builder / reviewer, ui skill, wcag-aaa-audit skill) operate in parallel. Human spot-checks every diff before commit — no AI-only merges.
3. Audit + auto-fix with Playwright + Vitesttests/a11y.spec.ts runs axe-core + Alfa across all routes × 6 theme/font combos. Vitest covers component-level regressions. Both must pass before commit.
4. Screen-reader checks (VoiceOver, NVDA, TalkBack)Manual AAA-checklist passes: VoiceOver + Safari (macOS/iOS), NVDA + Firefox (Windows), TalkBack + Chrome (Android). Each pass exports JSON to public/reports/screen-readers/ and surfaces on the audit page. Catches what only a listener can hear: announcement quality, reading order, screen-off task completion.
5. Security audit + corrections with Vitest + fallowfallow (Rust-based static security scanner) audits build output for common web-app vulnerabilities. Vitest holds the security regression line. Findings are fixed at source before any push.
6. Commit + push to Codeberg (via Forgejo subtree)Self-hosted Forgejo on a Tailscale-only host is the primary remote; Codeberg receives the a11yequitas.org subtree push (git subtree push --prefix=a11yequitas.org codeberg main). Public mirror, MIT-licensed.
7. Pre-deploy audit pass before pnpm buildFinal 264-test Playwright suite runs end-to-end. Zero violations from axe-core AND Alfa is the only pass criterion. Build only proceeds if both engines clear.
8. Build static export + generate Pagefind indexpnpm build runs next build (static export to out/) then pagefind --site out, which crawls every <main data-pagefind-body> and writes a chunked client-side search index to out/pagefind/. ~3.8k words, zero cloud — search is fully local in the visitor's browser.
9. Final commit + push to CodebergAfter clean audit and successful build + index, the production-ready commit is pushed. Codeberg subtree mirrors the working tree exactly.
10. Deploy to production on Rocky LinuxCode is pushed to Codeberg and pulled onto the Rocky Linux production hosts over Tailscale. Nginx serves the static export — no runtime JS server, no DB.

Why this workflow

  • Two-engine audit (axe-core + Alfa) catches ~1.5× the violations of either engine alone — see the audit page.
  • Local Forgejo + public Codeberg means a11yequitas.org is both privately versioned (Tailscale-only) and publicly inspectable (MIT, open source).
  • Static export served by Nginx on Rocky Linux pods — no runtime JS server, no DB, no surface area for runtime vulnerabilities.
  • Audit gate before build means the deployed site is never more broken than the test suite caught.