Contributor Start
This is the shortest path from a fresh checkout to the document that owns the change you want to make. Start with workflow and safety, find the owning source boundary, then choose the narrowest architecture and QA references for the change.
Read this if you are contributing code or documentation and need to know where to begin.
First Pass
- Read Contributing for pull-request scope, commit conventions, privacy rules, and the baseline validation expectation.
- Use Local Development to install, run, and inspect the source stack.
- Find the source owner in the Repository & Ownership Map before editing.
- Read System Overview for the whole-system shape, then follow the focused reference that owns your boundary.
- Choose checks and product-path coverage from Reliability & QA.
- Recheck Threat Model & Security Engineering for any change that can touch credentials, user data, browser state, network access, or application submission.
Here to use JobCtrl, not change it?
Start with Getting Started. It covers setup, everyday flows, configuration, and local-data boundaries without contributor tooling.
Find The Owning Reference
| If you are changing… | Read first |
|---|---|
| Runtime processes or the TypeScript/Python split | Runtime & Processes |
| Shared domain types, REST DTOs, JSON-RPC, or client boundaries | Contracts, Types & API Boundaries |
| SQLite authority, domain events, projections, SSE, or telemetry separation | Data, Events & Projections |
| A browser-facing route or response | Local TypeScript API, then its focused API reference |
| Temporal workflows, activities, retries, or stage execution | Job Pipeline |
| Backend aggregates, ports, or bounded-context language | Backend Domain Model |
| Frontend state, contexts, ports, or realtime invalidation | Frontend Architecture |
| Documentation structure or wording | Documentation Standards |
Requirements, Decisions, And History
- Requirements records the behavior and technical constraints that implementation must keep true.
- Decisions records accepted architectural choices and later amendments.
docs/plans/contains active delivery plans and implemented records. It is project history, not the source of current product behavior.
Current behavior belongs in the owning guide and in live code, but requirements and accepted decisions can be normative. When they disagree, reconcile the conflict: fix a regression in implementation or explicitly amend the decision before updating the canonical guide. Implemented plans remain historical evidence rather than current instructions.