Contributing

This is the documentation-site entry point for contributors. Detailed workflow lives in the root repository documents rather than being copied into the site.

Start here

• Contributing guide — setup, scripts, testing, review, and release workflow.
• Architecture — repository structure and stable contracts.
• Governance — project roles and decision-making.
• Security policy — private vulnerability reporting and supported versions.
• Agent orientation — generated owner and agent-document map.
• ADRs — current and historical architecture decisions.
• Public sanitization — rules for public code, docs, tests, examples, and diagnostics.

Common change paths

Change	Start with
Extension behavior	extensions/<id>/index.ts, relevant lib/, and focused tests
Extension metadata or agent-document roles	extensions/<id>/manifest.json
Shared behavior	lib/common/README.md and the owning shared Module
Generated documentation	Change its manifest/source input, then run npm run generate-catalog
Contributor workflow	Root CONTRIBUTING.md
Stable architecture decision	A focused ADR under docs/adr/

Source-of-truth rules

• Code and Behavior Proofs define implemented behavior.
• Manifests declare generated/runtime surfaces and document roles.
• Generated files and generated marker blocks are never hand-edited.
• Extension behavior stays co-located under extensions/<id>/.
• Shared helpers belong in lib/common/ only when multiple extensions need the same behavior.

Validation

Run focused checks while iterating. Before publishing broad changes, use:

npm run lint
npm run validate:ci

Useful documentation checks:

npm run generate-catalog:check
npm run docs:health:check
npm run docs:build

If generated drift is reported, run npm run generate-catalog, review the full diff, and stage the intended outputs explicitly.