Site hosting

The site builds for https://suite.agent-primitives.dev/ with base: '/'. The default GitHub project URL under /suite/ is not supported. Pull requests build and test in the required Documentation job; only main can deploy.

Preview and verify

Use Node.js 22.12 or newer:

npm --prefix docs ci --ignore-scripts
npm --prefix docs run docs:check
npm --prefix docs run docs:dev

The development server binds to loopback. The exact VitePress 2.0.0-alpha.20 pin matches kaimahi's documentation tooling; it is a prerelease, not a stable-framework claim. The lockfile is committed. No external fonts, analytics, hosted search or runtime credentials are used.

The root specification is rendered in place, with GitHub-compatible heading anchors. Schemas are copied unchanged into the build output. Fixtures link back to source rather than becoming another maintained content tree.

Owner setup, in order

These are owner actions, not actions performed by the publishing workflow.

1. Verify the apex domain for the organization before enabling the custom domain. An organization owner must perform this step; organization membership alone is insufficient. Open the agent-primitives organization's Settings > Pages, choose Add a domain, and enter agent-primitives.dev. Add the exact TXT name/value GitHub provides at the DNS provider, then click Verify. The challenge name is _github-pages-challenge-agent-primitives.agent-primitives.dev; the value is generated by GitHub, not a value to invent. Keep that TXT record permanently. This protects immediate subdomains from takeover. Do not add wildcard DNS.

2. Enable Pages using GitHub Actions before merging the site PR. In the suite repository's Settings > Pages > Build and deployment > Source, select GitHub Actions. Equivalent API command if the Pages site does not yet exist:

   gh api --method POST repos/agent-primitives/suite/pages -f build_type=workflow

   If Pages already exists, inspect it first, then use PUT with build_type=workflow instead of creating it again. Leave main protection in place. Review any github-pages environment approval or branch restrictions; only main should deploy.

3. Set the repository custom domain explicitly, after org verification: repository Settings > Pages > Custom domain, suite.agent-primitives.dev, Save. Equivalent API command:

   gh api --method PUT repos/agent-primitives/suite/pages -f cname=suite.agent-primitives.dev

   The committed CNAME file records the intended domain, but GitHub ignores it for custom Actions deployments. It does not replace this settings step.

4. Add the DNS record, after the domain is claimed in Pages:

   Type	Name	Target
   CNAME	suite	agent-primitives.github.io

   The full record is suite.agent-primitives.dev. No scheme, repository path, apex redirect or wildcard. Verify propagation:

   dig +short CNAME suite.agent-primitives.dev

5. Merge the reviewed, CI-green site PR, then rebuild after the domain is set. Main pushes publish automatically. Explicitly run the workflow on main after domain configuration, even if an earlier deployment already ran:

   gh workflow run docs-pages.yml -R agent-primitives/suite --ref main
   gh run list -R agent-primitives/suite --workflow docs-pages.yml --limit 3

   Inspect that run and wait for deployment success. Every build remains at root /; no dependency on configure-pages' inferred project base path.

6. Wait for the certificate, then enforce HTTPS. In repository Pages settings select Enforce HTTPS when available (certificate provisioning can take up to 24 hours). Equivalent API command once ready:

   gh api --method PUT repos/agent-primitives/suite/pages -F https_enforced=true
   gh api repos/agent-primitives/suite/pages --jq '{build_type,cname,protected_domain_state,https_enforced,https_certificate}'
   curl --fail --show-error --silent --head https://suite.agent-primitives.dev/
   curl --fail --show-error --silent https://suite.agent-primitives.dev/spec >/dev/null
   curl --fail --show-error --silent https://suite.agent-primitives.dev/schema/agent.schema.json

For removal, remove the DNS CNAME before disabling Pages or releasing the custom domain; retain the org verification TXT. No DNS/settings changes are automated by CI. Pages and OIDC write permissions belong only to the deployment job. Custom response headers are controlled by Pages, not by this static artifact.

Official references: domain verification, custom domains, and Pages REST API.