Sources: AGENTS.md CONTRIBUTING.md ai/project-map.yml ai/test-matrix.yml ai/generated-files.yml commit d32b9cc880a8 docs-explanation

Experienced contributor quick index

Use this page when you already know a Cataclysm-family codebase and need the CCB-specific boundaries and validation entry points.

Three rules first

1. CCB source and tests define runtime behaviour; upstream prose does not override CCB implementation.
2. Schemas, LuaLS declarations, registrations, and generated inventories define JSON, Lua, and API contracts.
3. Read the root AGENTS.md, then the nearest nested AGENTS.md on the path you will edit.

Route by task

Task	Inspect first	Narrow validation entry point
C++ behaviour or UI	src/ and related tests/	make astyle-check, then focused tests
Core JSON	data/json/ and its loader/factory	formatter and make -j2 json-check
EOC	EOC JSON, parser, and tests	JSON format, full load, focused parser test
Lua v5	manifest Schema, LuaLS, native registration, generated inventory	Lua contract checks
Bundled mod	data/mods/<mod>/ and dependencies	load the affected mod set
Android	android/	Gradle unit tests; name ABI and variant for builds
CI or packaging	.github/workflows/, build-scripts/	matching workflow or narrow local command
Agent or docs metadata	ai/, tools/agent/	Agent metadata tests

The machine-readable router is ai/project-map.yml; ai/test-matrix.yml maps paths to checks. Never hand-edit a file registered in ai/generated-files.yml.

CCB and upstream

For a port, record the source repository, exact commit or PR, original authors, license, CCB conflicts, and intentional divergences. Review saves, stable JSON IDs, mods, the Lua API, and desktop/Android differences. Passing upstream tests alone does not establish CCB compatibility.

Before submission

• name the Responsible human;
• list commands actually run, platform, results, and skipped checks;
• complete documentation impact, related CCB-Docs PR, stable document IDs, and generated-reference impact;
• inspect the final diff for caches, credentials, machine paths, and unrelated formatting.