# Agent & integrator guide

For coding agents and integrators who want to query, understand, or build against
TrustFortress / Cubie. All of this is public.

## 1. Query the knowledge base (fastest path)

- **MCP server:** `https://lib.trustfortress.ai/mcp` — JSON-RPC 2.0, no auth, CORS `*`.
  Tools: `search_library`, `ask_library`, `ai_search` (semantic), `list_collections`,
  `list_claims`, `get_claim`, `read_object`, `get_cub`, `search_cubs`, `list_cubs`,
  and `get_registry_meta`. Connect config + examples: [../MCP.md](../MCP.md).
- **HTTP APIs:**
  - `GET /api/ai-search?q=…` — semantic search (AutoRAG).
  - `POST /api/ask` `{ "question": "…" }` — grounded answer + cited sources.
  - `GET /api/search?q=…` — keyword-rank search.
  - `GET /api/catalog` — D1-backed exact catalog (keys, sizes, SHA-256, source refs).
  - `GET /api/cubs/meta` — current public Registry publication metadata.
  - `GET /api/cubs/<CUB-ID>` — exact public-safe CUB record.
  - `GET /api/cubs?…` — filtered public-safe CUB discovery.
  - `GET /api/claims` — the four headline claims as JSON.
  - `GET /objects/<url-encoded-key>` — fetch any published artifact.
  - `GET /browse/<encoded-prefix>`, `GET /architecture`, `GET /claims`, `GET /llms.txt`.

## 2. The monorepo at a glance

`cubie-tf` is a unified monorepo (cubie-math + cubie-eu + tf-rusty + trustfortress) with
four layers plus the proof kernels. **The layer directory names are load-bearing for EU AI
Act tracing** — do not flatten them.

| Layer | Where | Role |
|---|---|---|
| **Core runtime** | top-level `cubie-*` | no_std geometric trust math + admit pipeline + FFI |
| **EU AI Act** | `crates/cubie-eu-*` | per-article evidence mapping + Annex IV generation |
| **Control plane** | `controlplane/`, `core-manifold/`, `ebpf-dataplane/`, `tests/` | TrustFortress: identity, audit, MCP, robustness, record-keeping, assurance |
| **Proof kernels** | `coq/`, `lean/`, `verus/`, `proofs/` | triple-kernel corpus keyed by CUB theorem IDs |
| **Apps** | `apps/` | TrustFortress app, dashboards, MCP surfaces, this resource library |

Visual map: `GET https://lib.trustfortress.ai/architecture`.

## 3. Crate map (public-safe, one line each)

**Core (cubie-*):**
- `cubie-core` — architecture-neutral geometric trust math (pure logic).
- `cubie-platform` — multi-arch HAL + the L0–L5 admission pipeline.
- `cubie-control` — host-side cold path: FIPS crypto, attestation verification, policy match.
- `cubie-ffi` — C-ABI shared library (`cubie_admit`) for Python/C callers.
- `cubie-projector` / `cubie-projector-api` — cube-topology compilation + HTTP compile/admit API.
- `cubie-tep` — Tennessee-Eastman fault detector (a domain instantiation).
- `cubie-tdx-shim` — Intel TDX guest/host shim + mock (RTMR, SPDM, IDE).
- `cubie-ffi`, `cubie-qec`, `cubie-tor-bench`, `cubie-tools`, `bare-metal` — interop, QEC scaffold, benches, tooling, firmware facade.

**EU AI Act (crates/cubie-eu-*):**
- `cubie-eu-articles` — Article 9/10/11/13/14/15/16/17/50/73 evidence structs.
- `cubie-eu-annex-iv` — Annex IV technical-documentation generator (= Article 11).
- `cubie-eu-api` — axum REST + MCP service (`/api/v1/annex-iv`).
- `cubie-eu-ledger`, `cubie-eu-attest`, `cubie-eu-assurance`, `cubie-eu-tdx-{host,guest}` — dual ledger, attestation, assurance, TDX attestation.

**Control plane (TrustFortress):**
- `controlplane/tf-mcp` — MCP server / tool-call admission (Article 14 oversight).
- `controlplane/tf-server`, `tf-identity`, `tf-attestation`, `tf-audit`, `tf-governance`, `tf-metrics` — orchestration, identity, attestation, Merkle audit, policy, telemetry.
- `core-manifold/*` — formal-verification-backed robustness (Article 15): crypto, schema, orchestrator, core kernel.
- `ebpf-dataplane/*` — eBPF record-keeping + transparency (Articles 12+13).

## 4. Build, test, run

```bash
# Build (std + mock — laptop-friendly, no special hardware)
cargo build --features std,mock

# Run demos (see docs/DEMOS.md for the full set + expected output)
#  - TDX cold path, fairness bench (scalar vs AVX-2), agent harness,
#    GPU-fleet dashboard, TEP detector
cargo test --manifest-path bare-metal-tests/Cargo.toml   # bare-metal integration tests
```

- **Cross-compile targets:** `x86_64-unknown-none`, `aarch64-unknown-none`,
  `riscv32imc-unknown-none-elf`, plus `wasm32` for the Cloudflare edge build. The core is
  `no_std`; `cubie-eu-*` and TrustFortress are `std`.
- **Mock mode** needs no TDX/PUF hardware; hardware paths are feature-gated.
- **CI gates** you'll meet on a PR: `cargo fmt`, `cargo clippy`, bare-metal tests, proof-
  kernel checks, patent-header check. The authoritative gate list is `docs/architecture/CI_GATES.md`.

## 5. Integrating the admission gate

- **In-process (C/Python):** call `cubie_admit` via the `cubie-ffi` C-ABI (`CubeObjectV1` is a
  192-byte struct built from request headers).
- **Over HTTP:** use `cubie-projector-api` (compile → admit) or the TrustFortress MCP server
  for tool-call admission.
- **Verdict:** `allow / allow-degraded / deny`, with an explainable denial code. On DENY, no
  downstream GPU cycle or tool call is spent.

## 6. Contributing proofs (high level)

New theorems follow **math-first**: allocate a CUB-ID (`tools/cub_alloc.py`), write the Verus
spec, then the Coq and Lean files (parity across all three kernels), then bind to Rust. Never
cite prose theorem counts — re-measure with `bash tools/cubie_corpus_metrics.sh`. Deeper
contribution rules live in the repo (agents working *in* the repo read `AGENTS.md` /
`CLAUDE.md` / `NAVIGATION.md` directly).

## 7. Where the evidence is

- Claims + reproduce: <https://lib.trustfortress.ai/claims>
- Source packs (cubie-tep, cubie-eu): `GET /objects/cubie-tf%2Fsource-packs%2F2026-07-04%2F…`
- Proof corpus ZIP + MANIFEST: `.../verified-proofs/2026-07-04/`

## 8. Workload certification evidence

Read [workload-admin-evidence.md](workload-admin-evidence.md) before interpreting
the workload ontology, compiler replay, CUB-3211..3217, or a workload-admin
download.

Keep these three facts separate:

1. `registry_declared_consumption` is what the current Registry publication
   declares.
2. `binary_embedded_receipt` is what the running binary can validate from its
   embedded artifacts and recorded verifier receipts.
3. `runtime_observed_consumption` is request-bound evidence that the local
   runtime actually invoked a consumer.

The admin surface does not freshly execute Lean, Coq, or Verus. Its compiler
preview evaluates hypothetical compiled inputs and remains an
`ADVISORY_SIMULATION`; it is not an admission certificate or release
authorization.

Before citing a Registry digest or source head, requery `/api/cubs/meta`.
Exact-head equality requires two normalized 40-hex commit SHAs. A short head,
prefix match, timeout, or unavailable GitHub credential is `INCONCLUSIVE`, not
`PASS`.