Contributing · 0. Start here
This is the documentation the Crux Daemon's CONTRIBUTING.md should have been. That file is 70 lines describing a three-command workflow. The repository actually has 20 CI workflows, 11 required status checks, an active merge queue, a licence-header gate, a typo allowlist, an unwrap ratchet, a coverage gate with twelve floors, and a mutation-testing ratchet. This set documents all of it, so that an engineer who has never worked at CueCrux can land a pull request without guessing.
The repository is public: github.com/CueCrux/Crux. It is Apache License, Version 2.0, open source, see chapter 8 for the redistribution conditions before you plan anything commercial.
This chapter is a router. It contains no instructions of its own.
0.0 In plain English
Every established codebase has two sets of rules. There are the written ones, in the contributing guide, and there are the real ones, which live in continuous integration and in the heads of the people who work on it daily. A newcomer discovers the second set the slow way: by submitting a change and watching a check they had never heard of turn red. This set exists to collapse that gap. It documents the rules a change actually has to satisfy, so that you can satisfy them before you push rather than after.
That gap is unusually wide here, and it is worth being blunt about why. The repository's own CONTRIBUTING.md is 70 lines describing a three-command workflow. What a pull request actually meets is 20 CI workflows, 11 required status checks, a merge queue, a licence-header gate, a typo allowlist, an unwrap ratchet, a coverage gate with twelve separate floors, and a mutation-testing ratchet. None of that is unreasonable, and most of it is invisible until it fails.
You will use this chapter as a router rather than reading it. Come here, find your intent in §0.4, and go straight to the chapter that serves it. Build it, run it, test it, submit it, and so on. It deliberately contains no instructions itself, so that there is only ever one place where each instruction lives.
Two things are worth knowing before you start. The first is that the repository is Apache-2.0, open source, with redistribution conditions rather than restrictions; chapter 8 has the detail and you should read it before you write code, not after. The second, in §0.3, is the honest state of the on-ramp: there are currently zero open issues, so the usual "find a good first issue" route does not exist here. That is a gap in our on-ramp rather than a signal that the project is finished, and chapter 10 offers concrete starting points instead.
0.1 Who this is for
| You are | Start at | Because |
|---|---|---|
| An outside engineer who wants to fix something | 1. Build from source then 10. Good first contributions | There are no open issues to pick from. Chapter 10 is your issue tracker. |
| Evaluating whether the trust claims are real | 1. Build from source, then run the verification commands in 4. Testing | The licence explicitly grants you the right to audit. Every claim has a test. |
| A maintainer of a fork or an internal build | 8. Licence, security, governance and 9. Releases and packaging | The licence permits internal modification. The three prohibitions are narrow and specific. |
| Wiring an integration and needing to change the daemon | 2. Repository tour then 6. Recipes | Chapter 6 is a set of ordered file lists, add a route, add an MCP tool, add a config flag. |
| Reporting a security issue | 8. Licence, security, governance section 8.6 | Do not open a GitHub issue. Email security@cuecrux.com. |
If you want to understand the runtime rather than the source tree, ports, auth modes, the data directory, the error shape, read the Crux Daemon developer guide first. This set assumes it and does not repeat it.
0.2 The repository in one table
Tree state this set was written against: main at 93b41a7, workspace version 0.5.52 (Cargo.toml:45).
| Path | What it is |
|---|---|
crates/ | The 28-member cargo workspace (Cargo.toml:2) |
shells/desktop/ | Tauri v2 desktop shell. Excluded from the daemon workspace (Cargo.toml:37); built by its own workflow |
proto/ | Flat protobuf layout, two packages, consumed by corecrux-proto/build.rs:12 |
fuzz/ | Separate cargo workspace for cargo-fuzz, four targets |
tests/ | Fixture and benchmark-gate data only. Not a cargo test directory, the repo root has no [package] |
docs/ | Operator, agent and developer docs; index at docs/README.md |
docs/agent/ | The CI-verified agent doc set: CODEMAP, CLAIMS, INVARIANTS, GLOSSARY, repo-manifest.yaml |
scripts/ | Over 40 CI and ops shell scripts. The gates live here, not in the workflow YAML |
packaging/ | deb/ (nfpm), homebrew/crux.rb, systemd/crux.service, install.sh |
helm/corecrux/ | Helm chart |
integrations/ | claude-code/, codex-cli/, community/, openclaw/, systemd/ |
examples/ | mcp-configs/, quickstart/, rust/, scripts/, eval-profiles/ |
sdks/ | python/ (corecrux-client) and typescript/ (@cuecrux/client) |
content/ | Curated content assets under a separate licence (content/LICENCE-CONTENT.md) |
UI-prototype/ | Console prototypes, not shipped |
.agent/notes/ | Engineering notes (mutation-testing audit, probe findings) |
Root markdown worth knowing: README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, LICENSE, NOTICE, TRUST-CONTRACT.md, CHANGELOG.md, AGENTS.md, CLAUDE.md, CITATION.cff, llms.txt, llms-full.txt.
Six files named M1-REPORT.md, M2-REPORT.md, M3-REPORT.md, M5-REPORT.md, M-P1A-REPORT.md and M-P1B-REPORT.md also sit at the repository root. They are milestone reports from closed internal plans, not contributor documentation. Ignore them.
0.3 The honest state of the on-ramp
This is the part most contributor documentation omits. Read it before you invest an afternoon.
| Fact | Consequence for you |
|---|---|
There are zero open issues. gh issue list --repo CueCrux/Crux --state open returns empty | There is nothing to claim. Chapter 10 supplies ten real candidates instead. |
The good first issue label exists but is applied to nothing | Filtering GitHub by that label returns nothing. This is not a bug in your query. |
Blank issues are disabled (.github/ISSUE_TEMPLATE/config.yml sets blank_issues_enabled: false) | You must use the bug-report or feature-request template, or start a discussion. |
required_approving_review_count is 0 | No human approval is required to merge; the gate is the eleven required checks. But a fork PR needs a maintainer to approve the workflow run before any check starts, see chapter 5 §5.0. |
| All eleven required checks run on a self-hosted runner pool | When that pool is unhealthy, your PR cannot go green, and the documented recovery is an operator action you cannot take. See section 5.9. |
A warm target/ directory reaches 178 GB | Budget disk before you start. See section 1.5. |
Commit subjects carry milestone tags like (M17) that reference a private repository | You cannot resolve them, and you should not imitate them. See section 7.3. |
Four crux-session golden tests are permanently #[ignore]d on a private sibling checkout path | You will see four skips you cannot fix. That is expected, not your fault. |
None of this is a reason not to contribute. It is a reason to read chapter 10 before chapter 1.
0.4 Start here, by intent
| I want to… | Go to |
|---|---|
| Get a binary running on my machine | 1.2 Clone to running binary |
| Understand why my first build failed | 1.6 First-build failures |
| Find out which crate owns a behaviour | 2.3 The crate atlas |
| Know which files to touch for a change | 2.5 I want to change X then 6. Recipes |
| Run the daemon locally with auth off | 3.2 The minimal dev environment |
| Edit console HTML without a Rust rebuild | 3.6 The dev overlay |
| Run the tests the way CI runs them | 4. Testing |
| Understand why my PR is red | 5.2 The eleven required checks |
| Run every gate locally before pushing | 5.11 The pre-push checklist |
| Add an HTTP route | 6.1 |
| Add an MCP tool | 6.2 |
| Add a config flag | 6.3 |
| Add an on-disk artifact type | 6.4, read the three-place wiring rule first |
| Write my commit message correctly | 7.3 The commit convention |
| Know what the licence lets me do | 8.2 Permitted uses and 8.3 Redistribution conditions |
| Report a vulnerability | 8.6 Security disclosure |
| Understand how a release is signed | 9. Releases and packaging |
| Find something to work on | 10. Good first contributions |
0.5 Where this set corrects a published document
A 2026-07-27 audit of the repository found 13 factual errors and 13 structural gaps in the existing contributor documentation. This set states the verified truth and names the stale document, so that a reader who arrives from the old page can tell which is right.
| Published document says | Truth | Chapter |
|---|---|---|
CONTRIBUTING.md:18, README.md:89, README.md:386, docs/getting-started.md:98, protoc / protobuf-compiler is required | Not required. protoc-bin-vendored supplies it | 1.1 |
docs/troubleshooting.md:162, first build takes about 5 minutes | Not plausible for 525 packages with codegen-units = 1 and thin LTO | 1.4 |
docs/getting-started.md:99, links README.md#quickstart | Broken anchor. The README heading is "Up and running in 60 seconds" | 1.7 |
docs/agent/repo-manifest.yaml:10 and AGENTS.md:56, workspace version 0.5.37 | Cargo.toml:45 says 0.5.52 | 2.7 |
docs/testing-and-coverage.md: 4,489 tests, corecruxd 1,537 | Measured 2026-07-27: 5,969 and 2,244 | 4.1 |
docs/self-hosted-runner.md:3, the workspace builds 26 crates | 28 | 5.10 |
docs/self-hosted-runner.md:45, names a CI step and error string | Neither string exists in ci.yml today | 5.10 |
.github/merge-queue-ruleset.README.md:70-72, lists the required checks | Omits two of the eleven | 5.2 |
CHANGELOG.md:30, newest release heading [0.5.38] | Workspace is 0.5.52. Fourteen versions unlogged | 9.7 |
docs/unwrap-triage.md:3, quotes one combined #![deny(...)] | Source has three separate attribute lines | 5.7 |
Fixing several of these is itself a good first pull request. See chapter 10.
0.6 Chapter map
| # | Chapter | Diátaxis mode | What it gives you |
|---|---|---|---|
| 0 | Start here | Explanation | This router |
| 1 | Build from source | Tutorial | Clone to running binary, measured costs, failure modes |
| 2 | Repository tour | Reference | Crate map, dependency layering, change-to-files map |
| 3 | Running locally | How-to | Dev auth, minimal env, corecruxctl, Docker overlays |
| 4 | Testing | Reference | Every tier, how to run it, how long it takes |
| 5 | Quality gates and CI | Reference | The eleven checks, the merge queue, every local gate |
| 6 | Recipes | How-to | Five ordered file lists for five common changes |
| 7 | Submitting a change | How-to | Commit convention, PR conventions, review reality |
| 8 | Licence, security, governance | Reference | Apache-2.0 verbatim, disclosure route, trust contract |
| 9 | Releases and packaging | Reference | Signing, SBOM, provenance, the no-phone-home assertion |
| 10 | Good first contributions | How-to | Ten grounded candidates, because there are no issues |
Sources
- Cargo.toml:2, the 28 workspace members
- Cargo.toml:37, desktop shell exclusion
- Cargo.toml:45, workspace version
0.5.52 - CONTRIBUTING.md, the 70-line original
- AGENTS.md:56, the stale version claim
- docs/agent/repo-manifest.yaml:10, the same stale version
- CHANGELOG.md:30, newest released heading
- LICENSE, Apache License, Version 2.0
- SECURITY.md:5, do not open a public issue