# Documentation

Design and reference documents for Interchange. Code is the source
of truth; these documents explain the _why_ behind it and the shape
of the system at a higher level than any single package.

For development setup see [`DEV.md`](../DEV.md). For code conventions
see [`CONVENTIONS.md`](../CONVENTIONS.md). For the package taxonomy
see [`LAYOUT.md`](../LAYOUT.md).

## Orientation

- [`PRODUCT.md`](./PRODUCT.md) — product brief. What Interchange is
  for and who it is aimed at. Read first.
- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — system architecture.
  Agent composition, the hub/sidecar/harness split, how the pieces
  talk to each other.

## Subsystem design

- [`AUTH.md`](./AUTH.md) — authentication and authorization. Unified
  principal model, tenant-scoped grants, capability evaluation.
- [`CREDENTIALS.md`](./CREDENTIALS.md) — credential storage and
  rotation, harness delivery, background refresh.
- [`HARNESS_DESIGN.md`](./HARNESS_DESIGN.md) — agent harness
  implementation. How the sidecar manages harnesses on behalf of
  the hub.
- [`unified-execution-host-design.md`](./unified-execution-host-design.md)
  — design of record for the workflow-process execution host: how the
  sidecar runs each agent as a supervised workflow-process child. Its
  forward-looking sections are marked not-yet-built.
- [`INFERENCE.md`](./INFERENCE.md) — inference layer. Provider
  adapters, streaming, tool execution, context management, token
  accounting.
- [`MESSAGE.md`](./MESSAGE.md) — message transport. Mail as the
  first-class communication primitive, raw MIME storage, JMAP-style
  client views.

## HTTP API

- [`ROUTES.md`](./ROUTES.md) — routing conventions and the _why_
  behind the route structure.
- [`API.md`](./API.md) — generated route reference. Regenerated by
  `make docs` from the OpenAPI spec at `GET /openapi.json` and
  ArkType introspection over `@intx/types`. Do not edit by
  hand.
- [`GIT_ACCESS.md`](./GIT_ACCESS.md) — operator-facing walkthrough
  for the hub's smart-HTTP git endpoints. Minting tokens, configuring
  stock `git`, and the URL and `refPattern` grammars for the assets
  and agent-state repo families.

## Implementation notes

- [`IMPLEMENTATION.md`](./IMPLEMENTATION.md) — implementation notes.
  Currently covers the SMTP/IMAP message bus.
- [`inference-discovery-anthropic/docs/discovery.md`](../packages/inference-discovery-anthropic/docs/discovery.md) — observed vs
  documented wire behaviour of Anthropic's `/v1/messages` and
  `/v1/files` surfaces. Narrative companion to the discovery fixtures
  and the `SUPPORT_MATRIX`.
- [`inference-discovery-openai/docs/discovery.md`](../packages/inference-discovery-openai/docs/discovery.md) — observed vs
  documented wire behaviour of the OpenCode Zen relay. Narrative
  companion to the discovery fixtures and the `SUPPORT_MATRIX`.
