fix(docs+site): resolve the URLs this repo hands out, gate the rule, retire the undeployed site (#57)

[macanderson]

Summary

This repo advertised absolute URLs for its own artifacts on hosts it does not
deploy, so they 404'd — including the badge every conformant provider is told to
paste into its README. This fixes the live breakage, writes the host boundary
down as ADR 0008, gates it in CI, and retires the undeployed site/ app,
which is the ratified answer to #57's last open question.

Closes #57.

The bug, verified 2026-07-30

One Vercel project (prj_s3lf…, team oxagen) owns contextgraphprotocol.org,
cgp.oxagen.sh, and context-graph-protocol.vercel.app. Its Git integration
points at macanderson/cgp-website, root dir . — not at this repository.
The changeover is in the deploy history: last production from this repo
2026-07-23T21:41:03Z, superseded by cgp-website@main (8958d2e) at
21:51:53Z, still live.

https://cgp.oxagen.sh/badges/conformant.svg                                404
https://contextgraphprotocol.org/schema/contextgraph-envelope.schema.json  404
https://contextgraphprotocol.org/registry/…report.json                     404

docs/registry.md and docs/implementing-a-provider.md hand that first URL to
every provider that earns a registry row — on a page whose own copy said the
badge "never depends on this site's uptime." #58 hit the same wall from the
schema side and fixed $id alone.

Nothing failed loudly because no build step dereferences a URL.

What changed

Fix the URLs, gate the rule

• Badge URLs repointed to this repo's GitHub-raw path (image/svg+xml, so it
  renders in a third-party README).
• ADR 0008 — the verified topology, the host boundary ("advertise an
  artifact URL only on a host this repo serves"), and never-vercel link-this-
  checkout-to-the-apex.
• .github/scripts/check-deploy-hygiene.py + a required CI job: no artifact
  URL on a host we don't deploy, every advertised artifact exists at the path
  its URL names, no checkout linked to the apex project. Offline, no network.
• Scaffold READMEs point at the canonical apex; validate-examples.py's $id
  note cites ADR 0008.

Retire site/ (second commit)

site/ was a fumadocs/Next app built on every PR as a hard gate and
deployed nowhere, holding a second hand-maintained copy of docs/. That
copy had drifted stale, not richer:

• protocol-surface.mdx still documented capabilities.upsert, .subscribe,
  .filters, .writes — the dead surface ADR 0004 removed.
• changelog.mdx was 87 lines against CHANGELOG.md's 353; four more pages
  were partial copies of root files with no docs/ counterpart.

So deleting it removes wrong documentation, not unique documentation, and ends
the three-copies-across-two-repos drift ADR 0007 exists to prevent.

The two genuinely published artifacts moved out first, to homes that don't
depend on an app:

was	now
site/public/badges/conformant.svg	assets/badges/conformant.svg
site/public/registry/…report.json	registry/contextgraph-example-docs.report.json
site/public/schema/…	gone — byte-identical mirror of schema/…

Also removes the docs site builds CI job and tests/docs_site_witness_test.py
(it witnessed the app that no longer exists), and the schema mirror's copy-sync
check. Net: −14,621 / +139.

Note on the raw URLs: they point at main, so they go live on merge. The
guard's "every advertised artifact exists at the path its URL names" check is
the offline proxy that proves the badge move and the URL edit stayed in sync —
it is exactly the check that would have caught this move going wrong.

Verification

• New guard fails on main's four offenders, passes here (and passed in CI on
  the first commit).
• schema/validate-examples.py exits 0.
• .github/workflows/ci.yml parses; 18 jobs, no site.
• No dangling site/ references outside deliberate historical prose.
• No Rust touched.

Two things found in passing (not fixed here)

1. main is red — sdk (go|python|typescript) fail on
   provenance-fixture-consistency, a check Chore/backlog sweep 2026 07 #67 added that skips for the SDK
   example providers, and conformance-external.sh treats a skip as
   non-conformant by design. This PR inherits those three failures; they are not
   from this diff.
2. The stray local Vercel link — .vercel/ and site/.vercel/ in the
   maintainer's checkout still name the apex project; vercel --prod from there
   replaces the public apex. rm -rf .vercel site/.vercel clears it (my delete
   was permission-blocked). The new hygiene check fails locally until it's done.

Checklist

• One logical change per PR — one decision (P0: Vercel deploy topology: the project is Git-linked to the wrong repo, so contextgraphprotocol.org can be silently overwritten #57), enacted in two commits
• Gate is green locally — no Rust touched; schema validator, deploy-hygiene
  guard, and CI YAML parse all green
• A witness test is included — .github/scripts/check-deploy-hygiene.py,
  wired as a required CI job
• Docs updated in the same PR
• All commits signed off (DCO)
• CHANGELOG.md updated under [Unreleased]

Registry submission

• Not applicable — no registry row added or changed (the badge URL and the
  report's path are corrected; the listing itself is untouched)

Protocol-stability impact

• Not applicable — no wire or spec change

[sourcery-ai]

Reviewer's Guide

Fixes broken artifact URLs by pointing them at GitHub-raw, documents the deploy topology and URL rules in ADR 0008, and adds a Python-based CI guard to enforce that only served hosts are advertised and that no checkout is linked to the apex Vercel project, while aligning scaffold READMEs and schema commentary with the new rules.

Sequence diagram for CI deploy-hygiene check

sequenceDiagram
  participant GH as GitHubActions
  participant CI as deploy-hygiene_job
  participant Script as check-deploy-hygiene.py
  participant Git as git
  participant FS as filesystem

  GH->>CI: run job deploy-hygiene
  CI->>Script: python3 .github/scripts/check-deploy-hygiene.py

  Script->>Git: git ls-files -z
  Git-->>Script: tracked file list
  Script->>FS: read_text on tracked files
  Script-->>Script: extract ARTIFACT_URL matches
  Script->>FS: is_file for RAW_PREFIX targets
  Script-->>Script: missing artifact paths
  Script->>Git: git ls-files -- *.vercel/project.json .vercel/*
  Git-->>Script: committed Vercel link files
  Script->>FS: glob **/.vercel/project.json
  FS-->>Script: local Vercel project.json files
  Script->>Script: json.loads projectId

  Script-->>CI: exit 0 on PASS / 1 on FAIL
  CI-->>GH: report job status

Loading

File-Level Changes

Change	Details	Files
Conformance badge URL now resolves via this repo’s GitHub-raw path and related docs explain the host boundary.	Updated the badge URL in docs/registry.md to the raw.githubusercontent.com path for site/public/badges/conformant.svg. Mirrored the badge URL change in site/content/docs/registry.mdx. Updated implementing-a-provider docs in both markdown and MDX to use the GitHub-raw badge URL. Extended registry docs to explain why GitHub-raw is used, referencing ADR 0008 and issue P0: Vercel deploy topology: the project is Git-linked to the wrong repo, so contextgraphprotocol.org can be silently overwritten #57.	docs/registry.md site/content/docs/registry.mdx docs/implementing-a-provider.md site/content/docs/implementing-a-provider.mdx
Deploy topology and artifact URL rules are captured as ADR 0008 and surfaced in contributor documentation.	Added ADR 0008 describing the verified Vercel topology, host boundary for artifact URLs, never-link rule, and open decision about site/. Linked ADR 0008 and P0: Vercel deploy topology: the project is Git-linked to the wrong repo, so contextgraphprotocol.org can be silently overwritten #57 from CONTRIBUTING.md with a new section on sites, URLs, and vercel usage constraints. Clarified in ADR 0008 the distinction between artifact URLs and prose homepage links and the future allowlist change when site/ disposition is decided.	docs/adr/0008-deploy-topology-and-advertised-urls.md CONTRIBUTING.md
New deploy-hygiene Python script and CI job enforce artifact URL host rules and prevent linking this repo to the apex Vercel project.	Introduced .github/scripts/check-deploy-hygiene.py to scan tracked text files for artifact URLs, ensuring they use allowed hosts and point to existing files, and to detect committed or local .vercel links to the apex project. Defined SERVED_HOSTS allowlist and RAW_PREFIX constants, and excluded ADR and changelog paths from enforcement to preserve historical accuracy. Added a deploy-hygiene job in .github/workflows/ci.yml that runs the Python script with Python 3.12 as a required CI check.	.github/scripts/check-deploy-hygiene.py .github/workflows/ci.yml
Scaffolded provider READMEs now point to the canonical protocol homepage domain instead of cgp.oxagen.sh.	Updated the main create-contextgraph-provider README to use https://contextgraphprotocol.org as the protocol homepage URL. Updated the Python and TypeScript template READMEs to use the canonical contextgraphprotocol.org homepage URL. Aligned documentation with Cargo.toml’s homepage and ADR 0008’s distinction between artifact URLs and prose links.	sdk/create-contextgraph-provider/README.md sdk/create-contextgraph-provider/templates/python/README.md sdk/create-contextgraph-provider/templates/typescript/README.md
Schema validation commentary now treats the GitHub-raw $id choice as part of the general deploy-topology rule rather than a one-off workaround.	Extended comments in schema/validate-examples.py to reference ADR 0008 and explain that the GitHub-raw $id choice follows the repo’s host boundary rule. Clarified that the script’s $id handling is “the schema’s half” of the deploy hygiene rule enforced globally by the new CI guard.	schema/validate-examples.py
Changelog documents the broken badge URL issue and the new guard as the fixed behavior under Unreleased.	Added a Fixed entry describing the broken cgp.oxagen.sh badge URL, its impact on providers, and its replacement with the GitHub-raw artifact URL. Documented the new written-down rule and deploy-hygiene CI guard enforcing host-boundary and never-link constraints, referencing ADR 0008 and issue P0: Vercel deploy topology: the project is Git-linked to the wrong repo, so contextgraphprotocol.org can be silently overwritten #57.	CHANGELOG.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery