# Getting Started with cubie-tf

> New here? This page is the front door. Ten facts, three commands, and a map.
> Every command below was executed and verified on 2026-06-11 (Windows 11, stable Rust).

## What this repo is

**cubie-tf** is the Centillion unified monorepo: **Cubie** (a geometric trust compiler —
admission decisions computed as Rubik's-cube topology states, formally proven in three
proof kernels) plus **TrustFortress** (the admission runtime, MCP server, and EU AI Act
compliance layer). Five source repos were unified here on 2026-05-27; this repo is canonical.

It is **proprietary** (see [LICENSE](../LICENSE)) and embodies patents
US 11,956,363 B2, US 12,073,439 B2, and US 2024/0195628 A1. Never change the license
identifier — `LicenseRef-Proprietary` is load-bearing for patent protection.

## The ten facts

1. **One multi-crate workspace across several subsystems.** Top-level `cubie-*` crates are the math/runtime
   core; `crates/cubie-eu-*` is EU AI Act compliance; `controlplane/`, `core-manifold/`,
   `ebpf-dataplane/`, `tests/` are the TrustFortress runtime layers; `apps/trustfortress/` is the
   MCP server + Cloudflare Workers; `verus/`+`coq/`+`lean/`+`proofs/` is the proof corpus.
   Run `cargo metadata` when an exact workspace-member count matters.
2. **The layer directory NAMES are legally load-bearing.** `controlplane/` ↔ EU AI Act Article 14
   (human oversight), `core-manifold/` ↔ Article 15 (robustness), `ebpf-dataplane/` ↔ Articles
   12+13 (record-keeping + transparency), `tests/` ↔ assurance evidence. Never flatten or rename them.
3. **Three proof kernels are measured continuously, but not all proofs bind shipping code.**
   Run `bash tools/cubie_corpus_metrics.sh` for current proof-corpus metrics and
   `python tools/cub_alloc.py list` for allocated CUB IDs. New proof work must be
   closed proof/source only: no `sorry`, `Admitted`, `admit`, dummy, or planned-gap
   stubs. External claims must distinguish corpus parity from proofs bound to real
   Rust exec functions. The canonical, scope-bounded statement of every headline
   claim (proof corpus, TEP FAR=0, agentic waste, EU AI Act) is the
   [Grounded Claims Registry](https://lib.trustfortress.ai/claims) —
   [`resource-library/CLAIMS.md`](resource-library/CLAIMS.md) in-repo.
4. **The admit hot path has bounded-latency engineering guidance, not a public nanosecond claim.**
   Read [HARD_BLOCKERS.md](../HARD_BLOCKERS.md) §0 (the read-before-any-commit list) and the
   forbidden-patterns quick reference (§16 at v2.3; section numbers shift, so trust the doc's
   own table of contents) before touching
   `cubie-core` or `cubie-platform`. Cite measured latency only from current benchmark
   artifacts when a technical review actually needs it.
5. **CUB-IDs are allocated from live source inventory, never from prose.** Counts
   in docs are snapshots. Use `python tools/cub_alloc.py ceiling`,
   `python tools/cub_alloc.py next`, and targeted `rg "CUB-NNNN|CUB_NNNN|cub_NNNN"`
   before authoring or citing a CUB ID.
6. **Default branch is `main`.** Micro-PRs, merge commits, never rebase/force-push, never
   close a PR without confirming its commits are reachable from main.
7. **Every `.rs` file carries a 4-line proprietary header** (`TrustFortress.ai`, `Patents:`,
   `Cut:`, `CG:` lines). CI hard-fails without it — see `tools/check_headers.sh`.
8. **Mock mode means no special hardware.** Everything below runs on a laptop; Intel TDX
   silicon paths are simulated via mock DOE/SPDM (`--features std,mock` and the mock crates).
9. **CI changes with the repo** — see [CI_GATES.md](architecture/CI_GATES.md) for
   the current workflow inventory, which checks block, and how to fix each. Run
   the gate commands locally before pushing.
10. **Demos must label data scope honestly.** GPU-fleet and TEP demos use recorded
    or published datasets; do not generalize demo results beyond the documented
    evidence pack. See [DEMOS.md](DEMOS.md).

## Build and test (verified commands)

```powershell
# Full workspace compile check (≈13 s warm, minutes cold)
cargo check --workspace --all-targets

# Full test suites
cargo test --workspace
cargo test --manifest-path bare-metal-tests/Cargo.toml

# The lint gates CI enforces (run before every push).
# On Windows, use the package-batched wrapper to avoid CreateProcess error 206.
pwsh tools/cargo_fmt_workspace.ps1 -Check
cargo clippy --workspace --no-default-features --exclude tf-bridge-bin -- -D warnings
./tools/check_headers.sh
```

## See it work in 3 commands (verified)

```powershell
# 1. The TDX cold path, end to end, in mock mode — prints all 10 stages
cargo test --manifest-path bare-metal-tests/Cargo.toml --test e2e_full_cold_path --release -- --nocapture

# 2. Scalar vs AVX-2 admit pipeline must agree on every verdict (and does)
cargo build --release -p cubie-tor-bench --bin fair_bench
./target/release/fair_bench --workloads 20000

# 3. Live GPU-fleet dashboard on real trace data (needs "TF Logs 2 LARGE" in Downloads)
pwsh demo/run_demo.ps1 -Live
```

More demos, expected output, and the math each one exercises: [DEMOS.md](DEMOS.md).

## Where things live

| You want to… | Go to |
|---|---|
| See a visual repo map | [docs/about/repo-map.html](about/repo-map.html) |
| Load the curated docs navigation | [docs.json](../docs.json) |
| Give an agent the compact repo index | [llms.txt](../llms.txt) |
| Understand file placement rules | [NAVIGATION.md](../NAVIGATION.md) (auto-router fixes misplaced files on PR) |
| See active work / claim a task | [TODO.md](../TODO.md) |
| Check architectural constraints | [HARD_BLOCKERS.md](../HARD_BLOCKERS.md) |
| Read decisions (ADRs) | [docs/architecture/adr/](architecture/adr/) (post-merge) and [docs/adr/](adr/) (pre-merge cubie-math era) |
| Understand CI | [docs/architecture/CI_GATES.md](architecture/CI_GATES.md) |
| Repo rules for agents/humans | [CLAUDE.md](../CLAUDE.md) + [governance/REPO_RULES.md](../governance/REPO_RULES.md) |
| Browse external resource packs | [docs/resource-library/README.md](resource-library/README.md) and `https://lib.trustfortress.ai` |
| EU AI Act article ↔ code mapping | README.md §Layout + `crates/cubie-eu-articles` |
| Find a theorem | `rg "CUB-NNNN" verus/ coq/ lean/ proofs/` |

## Development workflow (the pipeline)

Math first, always: **theorem → Verus spec → Coq file → Lean 4 file → Rust → FFI → tests**.
No Rust exec code lands without its CUB theorem existing in a Verus spec. One logical unit of
work = one commit = one micro-PR. Verify CUB-ID is unused before authoring
(`grep -rln "CUB-NNNN\|CUB_NNNN\|cub_NNNN" coq/ lean/ verus/`).