Contributing

The one rule

This repo owns no truth. Specs, claims and contracts live in their owning repositories (see Explanation). PRs here change the compiler: rendering, surfaces, gates, tooling — never canonical content.

Local setup

git clone https://github.com/Aftergraph/docs.git
cd docs
npm ci
npm run build          # all 9 gates + build + smoke inputs
node scripts/smoke.mjs http://localhost:4321   # after: npx astro preview

Windows: repo is LF-only (hard gate). Strip before committing: sed -i 's/\r$//' <files>.

What a good PR looks like

New page → Diátaxis mode (one mode per page), provenance entry in src/data/provenance.json, sidebar entry in astro.config.mjs, claims quoted verbatim with their registry SHA.
Gate change → motivating failure case in the PR description; gates fail loudly or do not exist.
Source adoption → use scripts/adopt-source.mjs; show old/new SHAs and affected artifacts in the PR body.
Generated files (build-manifest.json, status.json, context packs) → regenerated by build; commit them as-is, do not hand-edit.

Non-goals

Analytics/trackers, marketing copy, canonical specs hosted here, write paths in the MCP, automatic pin updates. If a PR adds one of these, it will be closed — not because they are bad ideas everywhere, but because they break this plane’s specific trust model.

Reporting problems

Broken link, wrong provenance, drift: issue on Aftergraph/docs.
Wrong claim content: the registry owns it — file against Aftergraph/intelligence-systems-research.
Security: see the org-wide security policy in Aftergraph/.github.

Was this page helpful?