Welcome to the ABI multi-AI orchestration framework documentation. ABI is
implemented in Zig 0.17; this hub points at contracts, architecture specs, and
build guides without re-stating frozen CLI or MCP surfaces.

**Primary identity:** Abbey (empathetic polymath), with Aviva (direct expert),
ABI (orchestration), and WDBX (knowledge/memory substrate). See the
[Abbey Core Identity](spec/abbey-core-identity) contract for product direction
and the claim-honest Current / Partial / Proposed evidence map.

<Note type="warning">
  **Source wins.** When docs disagree with `build.zig`, `src/cli/usage.zig`,
  `src/mcp/handlers.zig`, or `tests/contracts/`, trust the executable sources
  and `./build.sh check`. Claim boundaries:
  [External Claims Audit](contracts/external-claims-audit). Local persona
  output is deterministic template generation, not a model-quality or
  distributed-AI claim.
</Note>

## Contracts

Frozen public surfaces and honest external wording. Prefer these over re-listing CLI commands or MCP tools here.

<CardGroup cols={2}>
  <Card title="Public API Contract" href="contracts/public-api">
    Frozen CLI + MCP surfaces and honest wording.
  </Card>
  <Card title="External Claims Audit" href="contracts/external-claims-audit">
    What public collateral may and may not claim.
  </Card>
</CardGroup>

## Architecture / roadmap

Design and north-star docs for Abbey identity, agents, WDBX, and multi-persona
routing.

<CardGroup cols={2}>
  <Card title="Abbey Core Identity" href="spec/abbey-core-identity">
    Canonical Abbey / Aviva / ABI / WDBX identity, operating protocol, and evidence map.
  </Card>
  <Card title="Multi-Persona Technical Overview" href="spec/multi-persona-technical">
    Deterministic local routing, templates, and runtime wiring.
  </Card>
  <Card title="WDBX North-Star" href="spec/wdbx-north-star">
    Vision and roadmap — Current vs. Proposed.
  </Card>
  <Card title="Agent and WDBX Architecture" href="spec/agent-wdbx-architecture">
    Agent runtime and WDBX integration architecture.
  </Card>
  <Card title="ABI Refactor Design" href="spec/abi-refactor-design">
    Refactor design and module boundaries.
  </Card>
  <Card title="WDBX Multiway" href="spec/wdbx-multiway">
    Multiway experiment surface and claim boundaries.
  </Card>
  <Card title="Non-loopback REST Threat Review" href="spec/non-loopback-rest-threat-review">
    Ops guidance for exposing REST/MCP HTTP beyond loopback — not a hardened-expose claim.
  </Card>
  <Card title="Cluster mTLS Ops" href="spec/cluster-mtls-ops">
    Cluster RPC transit encryption and membership — proxy mTLS preferred; not sharding.
  </Card>
  <Card title="Phase D Cutover Plan (HITL)" href="spec/phase-d-cutover-plan">
    Human-gated checklist before any modernized/ → src/ cutover.
  </Card>
</CardGroup>

## Partial design extracts

Labeled **PARTIAL** — design reference only, not active contracts.

<CardGroup cols={2}>
  <Card title="SEA Design Extract (PARTIAL)" href="spec/sea-design-extract">
    Design reference for evidence-augmented self-learning (SEA).
  </Card>
</CardGroup>

## Build

For quick-start commands and current validation status, see [README.md](../README.md). For CLI, MCP, GPU, TUI, and verification examples, see [walkthrough.md](../walkthrough.md).

For source-of-truth rules, claim-safe wording, page organization, and required
validation, see [Contributing to ABI Documentation](contributing).

On macOS/Darwin, prefer `./build.sh ...` for project validation even when plain `zig build` works locally. Primary gate: `./build.sh check`. Full local gate: `./build.sh full-check` (check plus integration tests, benchmarks, and dashboard smoke).

## Instruction files

- [AGENTS.md](../AGENTS.md) — canonical agent instructions
- [CLAUDE.md](../CLAUDE.md) — Claude-oriented conventions
- [GEMINI.md](../GEMINI.md) — Gemini-oriented conventions
- [CHANGELOG.md](../CHANGELOG.md) — release notes

Published vs working drafts: [Docs layout](./README.md). Plans under
[`superpowers/`](./superpowers/README.md) stay out of Mintlify navigation.

## Historical / archived

See the [archive index](superpowers/archive/README.md) — historical only, not
sources of truth. Prefer `docs/spec/*.mdx`, `docs/contracts/*.mdx`, and executable sources.