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

.github/workflows/pages.yml

@@ -4,23 +4,68 @@ on:
     branches:
       - main
       - master
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+  workflow_dispatch:
 permissions:
   contents: read
   pages: write
   id-token: write
+# Single owner of the GitHub Pages deployment. Both the documentation site and
+# the schema registry are built into one artifact so a docs push and a schema
+# tag can never clobber each other on the single Pages origin.
 concurrency:
   group: "pages"
   cancel-in-progress: false
 jobs:
   build:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      # Build the documentation site first. mkdocs cleans its output directory,
+      # so the registry must be assembled into ./site afterwards.
       - run: pip install mkdocs-material
       - run: mkdocs build
+      - run: npm ci
+      - run: npm test
+      - name: Build every released schema version into ./site/registry
+        shell: bash
+        run: |
+          set -euo pipefail
+          rm -rf registry release-source
+          tags="$(git tag --list "v[0-9]*.[0-9]*.[0-9]*" --sort=version:refname)"
+          if [[ -z "$tags" ]]; then
+            echo "No release tags found; deploying documentation without a schema registry."
+            exit 0
+          fi
+          while IFS= read -r tag; do
+            version="${tag#v}"
+            line="v${version%.*}"
+            mkdir -p "release-source/$version"
+            git archive "$tag" "schemas/$line" | tar -x -C "release-source/$version"
+            node scripts/build-registry.mjs \
+              --version "$version" \
+              --source "release-source/$version/schemas/$line" \
+              --output registry \
+              --append
+          done <<< "$tags"
+          npm run validate:registry -- --registry registry
+          # The registry is served as a sub-path of the single Pages site, so it
+          # must not carry its own CNAME (that would remap the whole origin).
+          rm -f registry/CNAME
+          mkdir -p site/registry
+          cp -R registry/. site/registry/
+      - uses: actions/configure-pages@v5
       - uses: actions/upload-pages-artifact@v3
         with:
           path: ./site

README.md

@@ -59,7 +59,7 @@ Producers should emit records that validate against the declared version. Consum
 
 The schemas are public APIs. Review [versioning and compatibility](docs/VERSIONING.md), [contributing](CONTRIBUTING.md), and [security](SECURITY.md) before proposing changes.
 
-Released schemas are discoverable from `https://coding-autopilot-system.github.io/cas-contracts/index.json`. Use stable `vMAJOR.MINOR` URLs for compatible updates or immutable `releases/vMAJOR.MINOR.PATCH` URLs for reproducible builds. See [schema distribution](docs/DISTRIBUTION.md).
+Released schemas are discoverable from `https://coding-autopilot-system.github.io/cas-contracts/registry/index.json`. Use stable `registry/vMAJOR.MINOR` URLs for compatible updates or immutable `registry/releases/vMAJOR.MINOR.PATCH` URLs for reproducible builds. See [schema distribution](docs/DISTRIBUTION.md).
 
 The v1 `WorkRequest` rejects dispatch unless objective, repositories,
 measurable criteria, constraints, risk, approval and verification policies,

docs/DISTRIBUTION.md

@@ -1,32 +1,33 @@
 # Schema Distribution
 
-Released CAS schemas are distributed from:
+Released CAS schemas are distributed from the schema registry, served as a
+sub-path of the documentation site on a single GitHub Pages origin:
 
 ```text
-https://coding-autopilot-system.github.io/cas-contracts/
+https://coding-autopilot-system.github.io/cas-contracts/registry/
 ```
 
-Schema `$id` values use the reserved canonical namespace `https://schemas.coding-autopilot.dev/`. Until DNS is configured for that domain, consumers must resolve schemas from the live GitHub Pages distribution URL.
+Schema `$id` values use the reserved canonical namespace `https://schemas.coding-autopilot.dev/`. This namespace is the stable *identity* of each schema and is independent of where the schema is hosted. Until DNS is configured for that domain, consumers must resolve schemas from the live GitHub Pages distribution URL above.
 
 ## URL Contract
 
 Use a stable major/minor URL when a consumer should automatically receive compatible patch releases:
 
 ```text
-https://coding-autopilot-system.github.io/cas-contracts/v0.1/prompt-envelope.schema.json
+https://coding-autopilot-system.github.io/cas-contracts/registry/v0.1/prompt-envelope.schema.json
 ```
 
 Use an immutable release URL when builds or evidence must remain reproducible:
 
 ```text
-https://coding-autopilot-system.github.io/cas-contracts/releases/v0.1.0/prompt-envelope.schema.json
+https://coding-autopilot-system.github.io/cas-contracts/registry/releases/v0.1.0/prompt-envelope.schema.json
 ```
 
 Discovery and integrity metadata are available from:
 
-- `/index.json`: available releases and the current release for each major/minor line.
-- `/v0.1/manifest.json`: schemas and SHA-256 digests for the current compatible release.
-- `/releases/v0.1.0/manifest.json`: schemas and SHA-256 digests for one immutable release.
+- `/registry/index.json`: available releases and the current release for each major/minor line.
+- `/registry/v0.1/manifest.json`: schemas and SHA-256 digests for the current compatible release.
+- `/registry/releases/v0.1.0/manifest.json`: schemas and SHA-256 digests for one immutable release.
 
 ## Local Build
 
@@ -39,8 +40,30 @@ The command writes `registry/`, validates the version, preserves relative schema
 
 ## Publication
 
-Pushing a semantic version tag such as `v0.1.1` runs `.github/workflows/publish-registry.yml`. The workflow rebuilds every tagged release, preserves immutable release paths, advances stable major/minor paths, validates the repository, and deploys the result to GitHub Pages.
+The documentation site and the schema registry are published together by a
+single workflow, `.github/workflows/pages.yml`, which is the sole owner of the
+GitHub Pages deployment. It runs on pushes to the default branch **and** on
+semantic version tags such as `v0.1.1`. On each run it builds the mkdocs site,
+rebuilds every tagged release into `site/registry/`, preserves immutable release
+paths, advances stable major/minor paths, validates the repository, and deploys
+a single artifact. Because both artifacts share one deployment, a docs push and
+a schema tag can no longer clobber each other on the single Pages origin.
 
 Repository administrators must configure GitHub Pages to use **GitHub Actions** as its source. Publication uses GitHub's OIDC token and does not require stored deployment credentials.
 
-To activate a verified custom domain, configure its DNS records and set the repository Actions variable `SCHEMA_DOMAIN`. The publication workflow emits `CNAME` only when that variable is explicitly configured.
+## Custom domain (manual follow-up)
+
+Serving the registry under the canonical `schemas.coding-autopilot.dev` `$id`
+namespace requires infrastructure that cannot be provisioned from this
+repository:
+
+1. Configure DNS for `schemas.coding-autopilot.dev` (a `CNAME` to
+   `coding-autopilot-system.github.io`, or the four GitHub Pages `A`/`AAAA`
+   apex records) with the domain registrar.
+2. Because the single Pages origin now hosts the documentation at its root and
+   the registry under `/registry/`, a custom domain would remap the **entire**
+   origin — it cannot point only at the `/registry/` sub-path. Activating
+   `schemas.coding-autopilot.dev` therefore requires a dedicated hosting origin
+   for the registry (for example, a separate Pages project or a CDN) rather than
+   the shared docs site. Until such an origin exists, resolve schemas from the
+   GitHub Pages URL above.