fix(pages): unify docs and schema registry into one pages deploy

[OgeonX-Ai]

Root cause

The repo had two workflows deploying to the single GitHub Pages origin under the same pages concurrency group:

• pages.yml — mkdocs docs, on push to main.
• publish-registry.yml — schema registry (registry/), on version tags.

GitHub Pages serves only one deployment per repository — each deploy-pages run replaces the entire site. So a docs push wiped the registry (every schema $id at .../v0.1/... 404'd) and a tag push wiped the docs. They clobbered each other; whichever ran last won.

Fix

Make pages.yml the sole owner of the Pages deployment and build one artifact containing both:

• pages.yml now triggers on branch pushes and version tags (v[0-9]+.[0-9]+.[0-9]+) plus workflow_dispatch.
• It builds the mkdocs site into ./site, then rebuilds every tagged release into ./site/registry/ (mkdocs cleans its output dir, so the registry is assembled after). Docs live at the site root; the registry is a stable sub-path at /registry/....
• The build runs npm ci && npm test and validate:registry before upload, so a broken registry blocks the deploy.
• A no-tags guard lets the docs deploy on a fresh repo before any release tag exists.
• publish-registry.yml is removed — its only job was the now-conflicting Pages deploy.

Reachable URLs (changed — registry moved to a sub-path)

Purpose	URL
Discovery index	https://coding-autopilot-system.github.io/cas-contracts/registry/index.json
Stable line	https://coding-autopilot-system.github.io/cas-contracts/registry/v0.1/prompt-envelope.schema.json
Immutable release	https://coding-autopilot-system.github.io/cas-contracts/registry/releases/v0.1.0/prompt-envelope.schema.json

docs/DISTRIBUTION.md and README.md are updated accordingly.

Schema $id decision

Schema $id values keep the canonical https://schemas.coding-autopilot.dev/... namespace. That URL is the schema's stable identity (referenced by every schema file and by the test suite); it is not tied to hosting location. Rewriting it to the GitHub Pages sub-path would be a breaking identity change across every schema and test, so it was intentionally left unchanged. lib.mjs is untouched.

Local validation

npm ci        -> 0 vulnerabilities
npm test      -> tests 35 / pass 35 / fail 0

Also simulated the workflow's build+copy steps locally against the repo's actual tags: registry builds into site/registry/ with index.json, releases/, and v0.1/ present, and validate:registry passes.

Manual follow-up (infrastructure — cannot be done from code)

1. GitHub Pages source must be set to GitHub Actions in repo settings (Settings → Pages). Publication uses OIDC; no stored credentials.
2. Custom domain schemas.coding-autopilot.dev — to make the canonical $id URLs directly resolvable requires DNS setup at the registrar. Because the single Pages origin now serves docs at root and the registry under /registry/, a custom domain would remap the whole origin and cannot point at just the sub-path. Activating that domain needs a dedicated hosting origin for the registry (separate Pages project or CDN). This is documented in docs/DISTRIBUTION.md; until then, consumers resolve schemas from the GitHub Pages /registry/ URL above.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 004c3fc704

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve legacy registry URLs

Because the deleted registry workflow uploaded path: registry, the published Pages root previously contained /index.json, /v0.1/..., and /releases/...; copying the rebuilt registry only under site/registry/ means the next unified deployment removes those already documented schema URLs and breaks existing consumers of the public registry. Keep the new /registry paths if desired, but also copy or redirect the legacy root-level registry paths in the same artifact so released schema URLs remain stable.

Useful? React with 👍 / 👎.