Automation
What runs automatically, what's still manual, and how to extend each.
Automatic on every PR
| Trigger | Workflow | What runs |
|---|---|---|
| PR opened / pushed to | validate.yml | pnpm install → pnpm typecheck → pnpm test (vitest) → pnpm validate (Zod over docs/**) → pnpm schema:check (codegen drift) → pnpm build (Docusaurus prod build with onBrokenLinks: 'throw') |
| PR opened / pushed to | axe.yml | pnpm install → install Chromium → pnpm build → start serve on 127.0.0.1:3010 → pnpm a11y (Playwright + axe-core, 4 sample pages × 2 colour modes + 360px responsive smoke) |
Both run on ubuntu-latest with Node 20 + pnpm via Corepack. Cached: pnpm store + Playwright browsers (saves ~30s/run).
A failing PR cannot merge to main (assuming branch protection — see Why for the rationale on holding off branch protection until Phase 6).
Automatic on every push to main (Phase 6 — pending)
| Trigger | Workflow | What runs |
|---|---|---|
Push to main | deploy.yml | pnpm build → wrangler pages deploy build --project-name=anatomy-of-marketing → live at wiki.anatomyofmarketing.dev |
Push to main (apex) | deploy-landing.yml | wrangler pages deploy landing --project-name=aom-landing → live at anatomyofmarketing.dev |
Until Phase 6 lands these workflows, deploys happen via local wrangler pages deploy from the operator's machine. No data loss risk — the deploy is just a static-asset upload.
Automatic on tag push (Phase 6 — pending)
| Trigger | Workflow | What runs |
|---|---|---|
Tag v*.*.* pushed | release.yml | pnpm bump-spec-version <tag> → docusaurus docs:version <tag> → snapshot aom.json → /static/versions/aom-vX.Y.Z.json → update version dropdown → gh release create with auto-changelog |
Versioning is gated by a fake v0.0.1-test cut that runs first to exercise the workflow on a throwaway tag. Only after that proves green does the real v26.3.1 cut happen.
Automatic on every build
These run inside pnpm build and don't need their own CI job:
| Step | What it does |
|---|---|
prebuild (pnpm hook) | tsx scripts/generate-search-ignore.ts walks docs/**, collects routes for status: draft pages, emits src/search-ignore.generated.ts (consumed by search-local plugin's ignoreFiles) |
pnpm codegen (in pnpm schema:check) | tsx scripts/codegen.ts re-derives schemas/frontmatter.schema.json + static/admin/config.yml from schemas/source.ts. CI fails on drift. |
generate-aom-json plugin postBuild | Walks docs/** front-matter, writes build/aom.json (60 + 6 + 6 + 8 + 13 entries, deterministically sorted, env-var-aware lastmod) |
inject-defined-term plugin postBuild | JSDOMs every concept HTML and every hat HTML, injects schema.org JSON-LD <script> tags into <head> |
@signalwire/docusaurus-plugin-llms-txt | Emits /llms.txt, /llms-full.txt, and 105 .md mirrors |
Automatic at the edge
When the deployed site receives a request:
| Path | Behaviour |
|---|---|
/<page> with Accept: text/markdown | functions/_middleware.ts rewrites to /<page>.md (content negotiation per AI-09) |
/<asset>.{json,txt,xml,md} | Bypasses middleware; served directly from build/ |
/admin | Static HTML mounts Sveltia CMS bundle from CDN at runtime |
/admin/config.yml | Sveltia reads this for collection definitions (regenerated on every build from Zod) |
/aom.json, /llms.txt, /sitemap.xml, /robots.txt | Direct static-file serve |
Still manual (intentionally)
| Action | Why manual |
|---|---|
| Deploying a fresh Cloudflare Pages project | One-time per project; wrangler pages project create is the canonical setup |
| Creating GitHub OAuth Apps | Only the repo owner can do this via GitHub UI (not API); Phase 5 user-action |
Cutting a real version (v26.3.1) | Should always be a deliberate operator action; run git tag from a clean main |
| Adding a new content type | Schema change in schemas/source.ts → run pnpm codegen → commit. No automation tries to guess the new shape. |
| Onboarding a new contributor | They read CONTRIBUTING.md, fork, PR. Standard Git workflow. |
Where automation could go further
Items in the v2 backlog (REQUIREMENTS.md §v2 Requirements) that would automate more:
- TEL-01: AI-crawler hit telemetry per page (Plausible custom events or CF Worker log)
- VIZ-01/02: auto-generate concept-graph and per-hat journey visualisations from
inputs[]/outputs[]/related[]front-matter - TRANS-02: translator workflow via CMS — auto-create per-locale branches when a draft is saved
For now: keep automation conservative. The methodology is the product. The pipeline is the supporting cast.