feat(schemas): publish meta-schemas to schemas.opendecree.dev via Pages

[zeevdr]

Summary

Phase 1 + Phase 3 of the schemas-publishing work for #125. Adds:

1. .github/workflows/deploy-pages.yml — builds _site/ from schemas/v*/..., validates, uploads as the Pages artifact, deploys via actions/deploy-pages@v4. Triggers: push to main filtered on schemas/** + workflow_dispatch for manual republish.
2. scripts/generate-schema-index.py — stdlib-only generator that walks _site/schema/v*/ and writes _site/index.html (table of versions and links) plus a _site/robots.txt.
3. docs/development/schemas-hosting-runbook.md — one-time setup, publishing flow, immutability policy, troubleshooting.
4. .agents/context/schema-spec.md — resolves the "Hosting target" open question to "Pages on decree itself, custom domain via Cloudflare CNAME (DNS-only)" + cross-links the runbook.

Closes #125 (after the manual one-time DNS + Pages setup below).

Allowlist publishing model

Pages source is set to GitHub Actions (not "Deploy from a branch"). The workflow:

1. Builds a fresh _site/ directory in the runner's tmpfs each invocation.
2. Copies schemas/vX.Y.Z/decree-{schema,config}.json into _site/schema/vX.Y.Z/ (note the dir rename: source is schemas/, URL is /schema/).
3. Generates _site/index.html + _site/robots.txt.
4. Runs an audit step that fails the run if _site/ contains anything other than:
   • _site/index.html
   • _site/robots.txt
   • _site/schema/vX.Y.Z/decree-{schema,config}.json
5. Uploads only _site/ via actions/upload-pages-artifact@v3 (path: _site is an allowlist).

The rest of the repo (README, internal/, docs/, .agents/, etc.) is never exposed at any URL on schemas.opendecree.dev.

Validation

Pre-deploy validation runs three checks:

1. scripts/validate-meta-schemas.py — same script ci.yml already runs on PRs (reuses CI: validate schema YAMLs against meta-schema #124 work). Asserts canonical files validate cleanly and known-invalid fixtures fail.
2. $id-matches-publish-URL assertion — for each schemas/v*/decree-{schema,config}.json, parse $id and compare to the URL it'll be served at. Catches the rare stale-rename case.
3. Audit step described above.

If any of these fail, the run fails before actions/deploy-pages is reached — no broken artifact ever reaches Pages.

⚠️ Bootstrap order — read before merging

The first push to main containing this workflow will trigger a deploy attempt. The deploy will fail with "Pages site not found" (or similar) until:

1. Cloudflare: add CNAME schemas → opendecree.github.io, DNS-only (gray cloud).
2. decree repo Settings → Pages: Source = GitHub Actions, custom domain = schemas.opendecree.dev. If GitHub asks for a TXT verification record, add it via the same Cloudflare DNS panel.
3. Wait for cert provisioning (15–60 min). Verify with curl -I https://schemas.opendecree.dev/.

After step 3, re-trigger via gh workflow run deploy-pages.yml. Subsequent pushes to schemas/** auto-deploy.

The runbook documents these steps in detail.

Out of scope

• Phase 2 (Cloudflare CNAME + Pages settings) is manual user work, not in this PR.
• Submit schemastore.org PR for editor integration #126 (schemastore.org PR) follows after Pages is verified live.

Test plan

• Workflow YAML parses (python3 -c 'import yaml; yaml.safe_load(...)').
• make validate-meta-schemas passes locally on main HEAD.
• Smoke-tested the _site/ build + audit logic locally — produces 4 files, all on the allowlist.
• Smoke-tested the $id-vs-URL check — both v0.1.0 files match.
• Smoke-tested scripts/generate-schema-index.py — produces a valid HTML page listing v0.1.0.
• Cert provisions, curl -I https://schemas.opendecree.dev/ returns 200 (post-merge, after manual setup).
• First successful auto-deploy run after a schemas/** edit (post-merge).