> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build And CI

> The Make, Cargo, BuildBuddy, and release validation surfaces used by Meerkat contributors.

Make is the developer-facing command surface. Cargo is the default backend.
BuildBuddy/Bazel is an opt-in acceleration backend for machines with access to
the GCP-backed runner pool.

## Local Commands

Use these commands for normal development:

```bash theme={null}
make build
make check
make lint
make test
make agent-gate
```

Avoid raw `cargo` for normal repo work. When you need targeted Cargo commands,
use `./scripts/repo-cargo` so output roots and multi-agent work stay isolated.

## BuildBuddy Opt-In

Set `MEERKAT_BUILDBUDDY=1` to route the same Make lanes through the BuildBuddy
backend:

```bash theme={null}
MEERKAT_BUILDBUDDY=1 make build
MEERKAT_BUILDBUDDY=1 make check
MEERKAT_BUILDBUDDY=1 make lint
MEERKAT_BUILDBUDDY=1 make test
MEERKAT_BUILDBUDDY=1 make e2e-fast
MEERKAT_BUILDBUDDY=1 make e2e-system
MEERKAT_BUILDBUDDY=1 make e2e-live
MEERKAT_BUILDBUDDY=1 make e2e-smoke
```

Use `BUILDBUDDY_DRY_RUN=1` with explicit BuildBuddy Make targets to inspect the
selected command without running it.

The Make targets delegate through `scripts/run-build-backend-lane`; when
BuildBuddy is enabled, that switch calls `scripts/buildbuddy-dev`.

## Test Lanes

| Lane              | Scope                                                          |
| ----------------- | -------------------------------------------------------------- |
| `make test-unit`  | Fast unit coverage.                                            |
| `make test-int`   | Integration-fast coverage without e2e scenarios.               |
| `make e2e-fast`   | Deterministic end-to-end lane.                                 |
| `make e2e-system` | Local real-resource scenarios.                                 |
| `make e2e-live`   | Targeted live-provider checks when credentials are configured. |
| `make e2e-smoke`  | Compound live-provider smoke scenarios.                        |

The canonical e2e lane taxonomy lives in
`tests/integration/src/e2e_lanes.rs`. Scripts and BuildBuddy targets route to
that taxonomy rather than inventing separate lane names.

## Architecture Gates

Machine and surface contracts have direct Make targets:

```bash theme={null}
make verify-version-parity
make verify-schema-freshness
make verify-rpc-surface-alignment
make verify-sdk-wrapper-freshness
make machine-check-drift
make machine-verify
make seam-inventory
make audit-generated-headers
```

These gates protect generated schemas, SDK wrappers, machine artifacts, and
runtime authority invariants.

## CI Shape

GitHub Actions runs the Cargo lane for normal contributor and main-branch CI:

* path-classified Cargo jobs cover formatting, lint, deterministic tests,
  generated artifacts, SDK suites, and release configuration
* the final gate emits a small attestation that binds the successful result to
  the exact commit SHA, Git tree SHA, workflow run, and workflow attempt
* attestations are emitted only for successful pushes to `main`

The tag release workflow consumes that exact-tree attestation instead of
re-running the same validation suite. It still builds and publishes the
platform-specific release artifacts from the attested source. Manual recovery
dispatches retain the explicit release-validation lanes because old release
commits may predate attestation artifacts.

The repository pre-push dispatcher follows the same identity rule. A complete
successful hook run writes a local Git-tree-keyed evidence stamp. A later push
of the identical tree, including its release tag, validates the pushed object
and checked-out `HEAD` identity and then reuses the complete gate result.

BuildBuddy remains an opt-in developer and release-recovery backend. Its
control-plane workflow starts the executor pool, submits the selected lanes,
and scales the pool down when the work completes.

## Doctor

Run:

```bash theme={null}
make buildbuddy-doctor
```

The doctor checks the API key, pinned `bb` CLI, generated Bazel files, selector
behavior, lane isolation, and docs wiring without printing secrets.

## Multi-Agent Work

Separate Git worktrees are already isolated by path hash. If multiple agents
share one checkout, set a distinct `RUST_LANE_ID` per agent when you want stable
warm local output roots.

## See Also

* [CD and distribution](/guides/cd-and-distribution)
* [Machine Authority](/reference/machine-authority)