index.md

title	Contributors
description	The shortest path for new contributors to get productive in Gas City.

Read These First

• Codebase Map
• Docs Organization when adding or moving pages in the published docs/ tree
• Architecture Overview
• Primitive Test
• PR Review Handoff Notes
• Reconciler Debugging
• Huma Usage Notes when touching internal/api/, OpenAPI generation, or SSE registration
• Excalidraw Setup when authoring diagrams for the docs
• Hold and Blocked Label Conventions when a bead needs to pause on a specific actor or condition — only hold:mayor and hold:external are canonical
• Release Gate Criteria Conventions when signing off the "Tests pass" criterion on a release-gates/*.md deploy gate — it must cite the CI jobs ci-required actually gates on
• CONTRIBUTING.md
• TESTING.md

Expectations

• Keep current-state behavior in the architecture docs and future changes in the design docs.
• Treat the Primitive Test as the gate before adding new SDK surface area.
• Run make check before you open a PR.
• Run make check-docs when changing navigation, cross-links, or docs structure.

Active Proposals

• Testing Pyramid Audit and Hardening Plan for the proposed test-size, ownership, doubles, synchronization, and E2E direction

When to Update Docs

• Update architecture docs when code behavior changes.
• Update design-doc status when a proposal is accepted, implemented, or superseded.
• Move exploratory notes, audits, and roadmaps into the archive instead of presenting them as current onboarding material.