api/README.md

# API

Clean product one-liner: the conversational API contract lives here.

Why: the user should meet one front door over graph state, not raw internal subsystems.

## Local turn runner

```bash
./bin/bvtctl "summarise the current runtime"
./bin/bvtctl ask "run the demo manifest" runtime/examples/demo_manifest.json
./bin/bvtctl chat
./bin/bvtctl context
./bin/bvtctl bootstrap-context
./bin/bvtctl inference
./api/run_turn.sh "summarise the current runtime"
./api/run_turn.sh "run the demo manifest" runtime/examples/demo_manifest.json
./api/build_system_context.sh
./api/write_session_bootstrap.sh
```

Why: `bin/bvtctl` is the operator-facing front door; `api/run_turn.sh`, `api/build_system_context.sh`, and `api/write_session_bootstrap.sh` keep the underlying single API honest and reusable across sessions.

## Inference backend

`inference.yaml` at the repo root is the inference routing surface.

Why: the turn kernel should use one local config to decide whether graph-first reasoning is backed by Codex CLI, so the repo can use the signed-in ChatGPT subscription instead of a separate API key path.

## Self-improve entry

```bash
./bin/bvtctl self-improve "tighten one bounded product slice"
./bin/bvtctl self-improve-apply "add one missing operator doc for the self-improve loop"
```

Why: self-improvement should enter through the same CLI surface and still end in manifests, receipts, and benchmarks rather than free-form repo mutation.