AGENTS.md

# AGENTS

Scope: repository-wide.

## Working doctrine

- Product first.
- Use cases before architecture.
- Hotgraph before generation.
- Reduced state before raw repo spelunking.
- Bounded artifacts before grand rewrites.

## Output style

- Always give one clean product one-liner.
- Use matrix grids when comparing options.
- Explain the why in plain terms.
- Prefer Pareto-frontier tradeoffs over absolute claims.

## Local rule

This repo is the standalone product shell.

That means:

- external source repos are bootstrap intake, not the shipped boundary
- `hotgraph/` is the bootstrap reasoning surface
- `policy/`, `benchmarks/`, `api/`, and `ux/` are shipped product slices
- `runs/` holds generated packets, benchmark outputs, and scorecards
- local glue here should stay thin and deterministic

## Agent bootstrap rule

Fresh sessions should not infer the system from raw repo traversal first.

Start here:

1. run `rtk ./bin/bvtctl bootstrap-context`
2. read `api/session_bootstrap.md`
3. refresh live state with `rtk ./bin/bvtctl context`
4. interact through the single API surface via `rtk ./bin/bvtctl "<question>"`

Why:

- the canonical front door is the conversational API
- policy and lineage should arrive as hydrated context, not as guesswork
- manifests and receipts are the bounded action/proof surfaces

Operational rule:

- use `context` for live system position
- use `bootstrap-context` for reusable cross-session handoff
- use `ask` only when binding a bounded manifest to the turn
- do not start with broad repo spelunking unless the API/context path is insufficient

## Generation rule

The sequence is:

1. update source registry
2. build hotgraph
3. inspect graph summary
4. decide local import target
5. generate bounded artifact

Do not skip step 2 unless explicitly forced.