# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Current state

Boxmaker is a sovereign personal agent harness written in Rust. As of this file's creation the
repo holds only `docs/design.md`: no code, no Cargo workspace, no Makefile, and no git history.
Work proceeds one milestone per session (M0–M7, table in `docs/design.md` Part 3). Before doing
anything, check which milestone artifacts exist (`spike/`, `docs/inference-contract.md`,
`AGENTS.md`, `Cargo.toml`) to work out where the project is.

`docs/design.md` is the binding design brief. Part 1 is the design; Part 2 is the session 1 prompt
(M0 spike plus M1 skeleton); Part 3 is the milestone table and the per-milestone prompt template.
If the brief looks wrong or conflicts with a measurement, stop and say so. Don't work around it.
Propose changes to `docs/design.md` as their own commit before building on them.

Once they exist, read `AGENTS.md` (project standards, how to run the gate, how to verify against
straylight) and `docs/inference-contract.md` (M0 measurements) alongside the brief.

## Commands (planned in M1, not yet present)

- `make gate` runs `cargo fmt --check`, clippy with warnings denied, `cargo test`, `cargo-deny`,
  and a check that fails on any source file over 500 lines. Run it before calling any work done,
  and report the exit status and last lines.
- Single test: `cargo test -p <crate> <test_name>`.
- `bxctl` is the owner CLI (`bxctl chat` from M2, `bxctl reindex` from M5).

## Architecture in brief

Separate binaries in one Cargo workspace. Each role holds as little authority as possible:

- `loopd` owns sessions, prompt assembly and memory. It has no credentials and no network. Its
  only I/O is Unix sockets to `gatewayd`, `brokerd` and `inferproxy`.
- `brokerd` is the only place authority lives. It reads owner-written grants (it cannot write
  them), runs each approved tool call in a fresh rootless container, and writes a hash-chained
  JSONL audit log.
- `gatewayd` is the Mattermost channel. Outbound only, no listening port; approvals arrive as
  replies or reactions over the WebSocket.
- `inferproxy` is a ~100-line byte forwarder to `llama-server`. Drop it if M0 shows
  `llama-server` can serve a Unix socket on the same host.
- `proto` holds shared types. `toolkit` holds tool container entrypoints.

Structural rules that span crates:

- No crate depends on another role's crate. Crates depend only on `proto`.
- Authority is encoded in types. A tool can't run without a `Decision`, and only `brokerd`'s
  policy module can construct one (covered by a compile-fail test).
- No source file over 500 lines.
- Files are the source of truth (`sessions/`, `memory/`, `grants/`, `audit/`). SQLite is only
  for rebuildable indexes and queues.

## Inference contract (the constraint most likely to be broken by accident)

Prompt processing on straylight is slow, and the hybrid-attention model can't partially rewind
its KV cache, so any change to an earlier byte of the prompt forces an expensive full re-read.

- Each turn's request must be a strict extension of the previous one. Volatile content (time,
  heartbeat notes, memory refreshes, recalled memory) goes only in the newest message, never in
  the system prompt or earlier history.
- Tool results are size-capped when first appended and never trimmed later.
- The baseline (system prompt, tool schemas, `memory/core.md`) stays at 3,000 tokens or less,
  measured with the server's tokenizer. Extra tool schemas are added through `find_tool`, not
  put in the baseline.
- Compaction happens only when the session is idle, and starts a new epoch
  (`sessions/<id>/<epoch>.jsonl`). Old logs are kept.
- Main session, subagents and scheduled jobs each use their own server slot.
- Streaming always. Timeouts are "no bytes for N seconds", never total deadlines.

## Working rules from the brief

- Verify every external crate API on docs.rs, and every llama-server or Mattermost request field
  against primary docs, before use. Crate names and server parameters in the brief come from
  memory and aren't verified. If you can't fetch the docs, say so; don't guess.
- Keep dependencies few. Justify each in `docs/dependencies.md`. Any outbound call must be listed
  in `docs/egress.md`. No telemetry and no update checks.
- If a feature isn't in the brief, propose it; don't build it. Stay inside the current
  milestone's scope.
- Write tests first. Make one logical change per commit. Never commit runtime data, secrets, or
  spike output that contains conversation content.