Contributing · 2. Repository tour

corecruxd is the only top of the dependency graph, corecrux-segment is the only true leaf, and crux-mcp is compiled into the daemon while corecruxctl is not. Those four facts explain most of the layout. This chapter is the reference for the rest.

This is reference material. Look things up in it; do not read it end to end.

If you want the runtime architecture, ports, auth modes, the data directory layout, the RFC 7807 error shape, read the Crux Daemon developer guide chapter 1 instead. This chapter is about the source tree.

2.0 In plain English

Opening an unfamiliar repository of a third of a million lines is disorienting in a specific way: you can read any individual file and still have no idea which files matter. This chapter is the orientation. It says what each directory is for, what each of the 28 crates does, and which crates depend on which, so that you can find the code you need without reading the code you do not.

The organising idea is layering. The crates are arranged so that dependencies point one way and never form a cycle. That gives the tree a natural reading order: the bottom layer is types and file formats with no dependencies of their own, and it is genuinely the best place to start, because you can understand a leaf crate completely without holding anything else in your head. The daemon binary sits at the top and depends on nearly everything.

You will use this chapter in one specific moment, and §2.5 is built for it: you have decided to change something, and you need to know which files to open and in what order. That table turns "I want to change X" into an ordered file list. The rest of the chapter is lookup material for when that table does not cover your case.

The thing people get wrong is assuming file size tracks importance, or that a crate's name predicts where its code lives. Neither holds here. The daemon binary alone is about 43% of the workspace's Rust and holds the large majority of the domain logic, so a great deal of what looks as though it should live in a library crate does not. If you are hunting for behaviour and the obviously-named crate turns out to be thin, look in the daemon before you conclude the behaviour does not exist.

2.1 The top-level map

Path	What it is
`crates/`	The 28-member cargo workspace (Cargo.toml:2)
`shells/desktop/`	Tauri v2 desktop shell, excluded from the workspace. Section 2.2
`proto/`	Flat protobuf layout: `corecrux_dataplane_v1.proto` and `corecrux_observe_v1.proto`, consumed by corecrux-proto/build.rs:12
`fuzz/`	A separate cargo workspace for `cargo-fuzz`, four targets. See 4.7
`tests/`	Fixture and gate data only. Not a cargo test directory, the repo root has no `[package]`. See 4.6
`docs/`	Operator, agent and developer documentation; index at `docs/README.md`
`docs/agent/`	The CI-verified agent doc set. Section 2.6
`scripts/`	Over 40 shell scripts. The CI gates live here, not in the workflow YAML
`packaging/`	`deb/` (nfpm), `homebrew/crux.rb`, `systemd/crux.service`, `install.sh`, `tests/install-smoke.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`). Released on their own tags, see 9.8
`content/`	Curated content assets under the separate CueCrux Content Licence v1.0
`UI-prototype/`	Console prototypes. Not shipped
`.agent/notes/`	Engineering notes: the mutation-testing audit, probe findings

Root markdown a contributor should know:

File	Why you care
`README.md`	What the product is
`CONTRIBUTING.md`	70 lines. This set supersedes it
`AGENTS.md`	The index for machine readers, plus the 60-second trust-core tour and the "Ask first" and "Never" boundary lists
`CLAUDE.md`	Repo-scoped agent instructions; states the CPU-only rule and the fixed 14800 port
`LICENSE`	Apache License, Version 2.0. See chapter 8
`NOTICE`	Attribution text redistributors must pass on
`TRUST-CONTRACT.md`	The five clauses the daemon claims to satisfy
`SECURITY.md`	Disclosure route. Not a GitHub issue
`CHANGELOG.md`	Keep a Changelog format. See 9.7
`CITATION.cff`	Machine-readable citation metadata; drives GitHub's "Cite this repository" button
`llms.txt` and `llms-full.txt`	Machine-reader entry points. `llms-full.txt` is CI-checked for freshness

Six milestone reports also sit at the root (M1-REPORT.md, M2-REPORT.md, M3-REPORT.md, M5-REPORT.md, M-P1A-REPORT.md, M-P1B-REPORT.md). They are internal artefacts from closed plans, not contributor documentation.

2.2 The desktop shell, and why it is excluded

Cargo.toml:37 excludes two paths from the workspace:

exclude = ["shells/desktop/lifecycle", "shells/desktop/app"]

The comment above it gives the reason: the Tauri app pulls the webkit2gtk stack, which will not build on the CI, self-hosted or WSL toolchains, and each shell crate carries its own [workspace] table. It is built separately by .github/workflows/desktop-shell.yml, whose desktop app compile gate (linux) job is one of the eleven required checks, so a change that breaks the shell still blocks your PR even though the shell is not in the workspace.

One inconsistency to be aware of: shells/desktop/connection is not named in exclude even though the comment says every shell crate is. It is harmless today because that crate does carry its own [workspace] table, but do not rely on the exclude list being complete.

2.3 The crate atlas

docs/agent/CODEMAP.md is the canonical atlas and it is CI-verified: every symbol it names is asserted to exist by scripts/check-agent-docs.sh against docs/agent/repo-manifest.yaml. Read it when you need public symbols. The table below is the orientation layer.

Trust core, read these first.

Crate	Owns	Approx LOC
`corecrux-frame`	Canonical v1 frame encoding and hash helpers	0.3k
`corecrux-segment`	Sealed segment format `.ccxseg`, build, seal, decode, hash binding	4.1k
`corecrux-storage`	Append-only shard store; sealing, integrity scan, seal material	12.4k
`corecrux-receipts`	Receipt formats, Ed25519 signing, strict verification, witness anchoring, export bundles	12.0k
`rcx-capability-token`	RCX capability token v1.0, schema lock, CBOR and JSON mirror, validation	1.1k

Memory and retrieval.

Crate	Owns	Approx LOC
`corecrux-memory`	Versioned fact store and session store; decay, supersession, CROWN receipts	11.7k
`corecrux-index`	Companion inverted index `.ccxi`, built at seal time; powers BM25	1.1k
`corecrux-retrieval`	Fused retrieval, BM25 plus graph-signal fusion over `.ccxi`	2.1k
`corecrux-projections`	Living-objects projections and snapshots `.ccxs`, plus a deterministic parity harness	12.4k
`crux-lens-features`	Feature Registry lens over the memory substrate	0.5k

Routing, identity, sessions.

Crate	Owns	Approx LOC
`crux-router`	RCX daemon router primitives, capability, credit, egress	2.2k
`crux-session`	VaultCrux session handshake v1, canonical CBOR, JCS mirror, Ed25519	7.2k
`crux-enterprise-shim`	Enterprise customer-hosted RCX token-validation contract	0.4k
`vaultcrux-local`	Daemon-local classification and content-loading policy; tier boundaries	0.6k

Daemon, CLI, MCP.

Crate	Owns	Approx LOC
`corecruxd`	The daemon binary: axum HTTP on 14800, tonic gRPC on 4007, MCP host on 14801, signing, auth	83.8k
`corecruxctl`	The CLI: `verify-store`, `replay`, `gaps` and about 50 more subcommands	33.1k
`crux-mcp`	Agent-facing MCP server, JSON-RPC 2.0 over axum Streamable HTTP; about 42 tool modules	33.1k
`crux-observe`	Self-observation: ops events and bootstrap docs into memory facts	2.7k
`crux-observe-api`	Wire types for the agent audit-chain data contract	0.8k
`crux-integrations`	Declarative manifest contract for daemon integration packs	2.5k

Supporting and standalone.

Crate	Owns	Approx LOC
`corecrux-types`	Foundational shared event-store types	2.5k
`corecrux-proto`	Protobuf and gRPC types for the data plane, tonic and prost generated	0.1k
`crux-config-wizard`	Composes `CLAUDE.md` and `AGENTS.md` from versioned profile fragments	1.8k
`crux-claude-hooks`	Claude Code lifecycle hook binaries `crux-hook` and `crux-llm-shim`	5.0k
`crux-contrib`	Contribution-manifest builder and Ed25519 envelope signing	0.2k
`crux-cost`	Token-burn cost lens over a Claude Code transcript	2.2k
`crux-sync`	Offline-first outbox sync client to the VaultCrux API	0.7k
`crux-integration-tests`	Cross-crate integration tests. Test-only crate	2.2k

Sizes are the ~LOC column of CODEMAP.md, which the maintainers keep current. crux-console-ui appears in the tree as a built SPA (dist/ only) and is deliberately not a cargo member.

2.4 The dependency shape

Verified with cargo metadata --no-deps, normal dependencies only. This distinction matters: crux-session/Cargo.toml lists corecrux-projections under [dev-dependencies] only, so a naive grep places crux-session four layers higher than it belongs.

L1 (leaves)  corecrux-frame · corecrux-proto · corecrux-segment · corecrux-types
             crux-config-wizard · crux-contrib · crux-cost · crux-observe-api
             crux-session · vaultcrux-local

L2           corecrux-index         -> frame, segment
             corecrux-receipts      -> types
             rcx-capability-token   -> crux-session
             crux-claude-hooks      -> crux-config-wizard, crux-session
             crux-integration-tests -> corecrux-proto

L3           corecrux-storage       -> frame, index, segment
             crux-enterprise-shim   -> rcx-capability-token
             crux-router            -> rcx-capability-token
             crux-sync              -> rcx-capability-token
             crux-integrations      -> receipts, rcx-capability-token

L4           corecrux-projections   -> frame, segment, storage
             corecrux-memory        -> crux-sync, rcx-capability-token

L5           corecrux-retrieval     -> index, projections
             crux-lens-features     -> memory
             crux-observe           -> memory
             corecruxctl            -> frame, index, memory, projections, proto,
                                       receipts, segment, storage, types, cost,
                                       integrations, session

L6           crux-mcp               -> memory, projections, receipts, retrieval,
                                       types, integrations, lens-features, observe,
                                       router, session, rcx-capability-token,
                                       vaultcrux-local

L7 (top)     corecruxd              -> 21 crates including crux-mcp

Four consequences worth internalising:

corecrux-segment is a true leaf. It has no internal path dependencies at all, not even on corecrux-frame, despite index, storage and projections all needing the two side by side. If you are tempted to reach from segment into frame, that is a design change, not a tidy-up.

corecruxd is the unique top. Nothing depends on it inside the workspace.

corecruxctl is not a corecruxd dependency; crux-mcp is. The CLI is a separate binary that talks to the daemon over HTTP. The MCP server is compiled into the daemon process.

crux-integration-tests sits at Cargo-level L2 but architecturally above corecruxd. It drives the compiled corecruxd and corecruxctl binaries as subprocesses over HTTP (ureq) and gRPC (tonic); it does not compile against them. Its only path dependency is corecrux-proto, for the gRPC message types.

2.5 I want to change X

Each row is an ordered file list. Chapter 6 expands the first four into full recipes with the tests that fail when you miss a step.

I want to change	Touch, in this order	Full recipe
Add an HTTP route	`crates/corecruxd/src/http/<name>.rs` (handler) → `http/mod.rs` (the `mod` declaration and the `.route(...)` call) → `http/route_auth.rs` (`classify_route` arm) → `http/openapi.rs` (`const ROUTES` entry) → console generator arrays if the console calls it → tests	6.1
Add an MCP tool	`crates/crux-mcp/src/tools/<name>.rs` → `tools/mod.rs` catalogue `vec![]` → `tools/mod.rs` `call_tool` match arm → `crates/vaultcrux-local/src/tool_surface.rs` if the tool is hosted-gated → bump `TOOL_COUNT`	6.2
Add a config flag	`crates/corecruxd/src/config.rs`: struct field, parse in `load_config`, entry in the `Config { .. }` literal, optional cross-field validation → unit test → `config.example.env`	6.3
Add an on-disk artifact type	`crates/corecrux-storage/src/lib.rs` (extension allowlist) → `crates/corecrux-projections/src/meta.rs` (module registry) → `crates/corecruxd/src/main.rs` (load at startup)	6.4
Add a test	Inline `#[cfg(test)] mod tests` in the module, or `crates/<crate>/tests/`, or `crates/crux-integration-tests/tests/`	6.5
Change a receipt, seal material, or anything under `corecrux-receipts`, `-segment`, `-storage` that an invariant names	Open a discussion first; this is on the "Ask first" list at AGENTS.md:70	-
Change a default port	Do not. Also "Ask first" at AGENTS.md:70	-
Change the CLI surface	`crates/corecruxctl/src/`: one module per subcommand, plus tests under `crates/corecruxctl/tests/`	-
Add a new crate	`Cargo.toml` members list → the crate → `crates/<name>/AGENTS.md`, 60 lines or fewer → escalate the warn-level lints to deny at the crate root	Section 2.6

2.6 The per-crate AGENTS.md contract

Every one of the 28 crates ships a crates/<name>/AGENTS.md. This is not decoration; it is enforced by scripts/check-agent-docs.sh, which backs the required check Verify agent-doc references resolve. The script makes four independent assertions:

Assertion	Fails when
Every symbol, test, crate directory and fuzz target named in `docs/agent/repo-manifest.yaml` under `ci_assertions` still exists	You rename a symbol that agent docs reference
Every local link in `llms.txt` resolves	You move or delete a linked document
Every cargo crate under `crates/` ships an `AGENTS.md` of 60 lines or fewer	You add a crate without one, or let one grow
`llms-full.txt` is fresh, checked by regenerating and diffing	You edit a document linked from `llms.txt` without regenerating

Two rules follow, and CONTRIBUTING.md states neither:

Anchor doc references by symbol name, never by line number. This is on the "Never" list at AGENTS.md:75. Line numbers rot; the CI check greps for symbols.

If you edit any document linked from llms.txt, regenerate llms-full.txt with bash scripts/build-llms-full.sh, or the required check goes red.

Run it yourself before pushing:

bash scripts/check-agent-docs.sh --exec

The --exec flag is how CI calls it; it additionally runs cargo fmt --check.

2.7 Documents in the repo that are stale

Document	Line	Claim	Truth
`docs/agent/repo-manifest.yaml`	10	`workspace_version: "0.5.37"`	Cargo.toml:45 says `0.5.52`. `check-agent-docs.sh` does not verify this field
`AGENTS.md`	56	"workspace version 0.5.37"	The same, in prose
`docs/self-hosted-runner.md`	3	"the workspace builds 26 Rust crates"	28: Cargo.toml:2, CODEMAP.md:7
`docs/README.md`	-	The docs index has First Run, Operator, Developer, Trust Surface and More sections	It never links `CONTRIBUTING.md`. There is no contributor section at all

Sources

Cargo.toml:2, the 28 workspace members
Cargo.toml:37, desktop shell exclusion and its rationale
Cargo.toml:45, workspace version
docs/agent/CODEMAP.md:7, "The workspace has 28 cargo crates"
docs/agent/CODEMAP.md, per-crate purpose, symbols, LOC
docs/agent/repo-manifest.yaml:10, the stale workspace_version
AGENTS.md:56, the same stale version in prose
AGENTS.md:70, the "Ask first" list
AGENTS.md:75, the "Never" list
scripts/check-agent-docs.sh, the four assertions
crates/corecrux-proto/build.rs:12, the proto/ directory reference