CI & Deploy Flow

PR → check-docs fail-on-diff gate → merge → deploy-docs → Cloudflare

Two Workflows, One Generator Set

.github/workflows/check-docs.yml runs on every pull request touching docs/**, plugins/**/SKILL.md, .claude-plugin/marketplace.json, mkdocs.yml, apps/explorer/**, or scripts/**. .github/workflows/deploy-docs.yml runs on push to master (same path filters, plus workflow_dispatch). Both regenerate doc data from the same four generators before building — the gate and the deploy never diverge on what "current" means.

graph TD
  PR["Pull Request
opened / updated"]

  subgraph CHECK["check-docs.yml · pull_request"]
    RG["Regenerate doc data
4 generators"]
    FR["validate-docs-freshness.sh"]
    DRIFT["git diff --exit-code
docs/wiki + explorer/public"]
    STRICT["mkdocs build --strict
--site-dir /tmp/site-check"]
    LINT["markdownlint-cli2
on changed .md"]
    VER["validate-skill-versions.sh
validate-skill-prefixes.sh
version-bump enforcement"]
    RG --> FR --> DRIFT --> STRICT --> LINT --> VER
  end

  MERGE["Merge to master"]

  subgraph DEPLOY["deploy-docs.yml · push(master) / workflow_dispatch"]
    RG2["Regenerate doc data
4 generators"]
    MK2["mkdocs build --strict
--site-dir site"]
    VITE2["cd apps/explorer
npm install && npm run build"]
    COPY["cp explorer dist → site/explorer
cp site-redirects → site/_redirects"]
    WRANGLER["wrangler-action
pages deploy site"]
    RG2 --> MK2 --> COPY
    RG2 --> VITE2 --> COPY
    COPY --> WRANGLER
  end

  CF["Cloudflare Pages
agents-infra-docs"]

  PR --> RG
  VER -->|all green| MERGE
  MERGE --> RG2
  WRANGLER --> CF

  class RG,RG2,MK2,VITE2 trigger;
  class FR,DRIFT,STRICT,LINT,VER gate;
  class COPY,WRANGLER,CF deploy;

check-docs.yml — Gate Steps In Order

#	Step	What it enforces
1	Regenerate doc data from source	Runs all 4 generators against current `plugins/` + `marketplace.json`
2	`validate-docs-freshness.sh`	gate docs freshness
3	Check for data drift	gate `git diff --exit-code` on `docs/wiki` + `apps/explorer/public` — fails PR if generated output wasn't committed
4	`mkdocs build --strict --site-dir /tmp/site-check`	gate broken-link / nav validation
5	`markdownlint-cli2` on changed `.md`	gate markdown lint, PR-scoped
6	`validate-skill-versions.sh`	gate skill version discipline
7	`validate-skill-prefixes.sh`	gate skill prefix / dir-name match
8	Enforce version bumps on changed `SKILL.md`	gate body changed ⇒ `metadata.version` must strictly increase

deploy-docs.yml — Build + Publish

Triggered on push: branches: [master] (path-filtered) or manual workflow_dispatch. After the same 4-generator regeneration:

mkdocs build --strict --site-dir site — continue-on-error: false
cd apps/explorer && npm install && npm run build
Copy apps/explorer/dist/* into site/explorer/, plus scripts/site-redirects into site/_redirects
cloudflare/wrangler-action@v3 — pages deploy site --project-name=agents-infra-docs --branch=main

The fail-on-diff gate is the load-bearing check. check-docs.yml doesn't trust that a contributor regenerated artifacts locally — it regenerates them itself in CI and fails the PR the moment git diff --exit-code finds a difference against what's committed under docs/wiki or apps/explorer/public, with the explicit remediation message "Run scripts/build-docs.sh and commit."