# AGENTS.md

## Purpose

This repository uses `docs/` as the source of truth for technical documentation and implementation planning.

## Working Rules

1. Keep the root `README.md` short and navigational.
2. Keep detailed technical documentation in `docs/`.
3. Update relevant documentation in the same change whenever implementation changes:
   - architecture
   - protocol or state machine
   - integrations or tool behavior
   - deployment assumptions
   - backlog ordering or exit criteria
4. Treat `docs/backlog.md` as the current phased implementation backlog.
5. Prefer small, safe increments that keep docs and implementation aligned.

## Documentation Map

- `docs/overview.md` — project overview and scope
- `docs/architecture.md` — system structure and pipeline
- `docs/protocol.md` — event contract and state machine
- `docs/integrations.md` — service integrations and tool safety
- `docs/deployment.md` — deployment topology, security, and risks
- `docs/backlog.md` — phased implementation backlog

## Update Expectations During Implementation

- If code changes behavior, update the matching document before considering the work done.
- If implementation reveals a new constraint or decision, document it in the most relevant existing file.
- If a document becomes too broad, split it into smaller files instead of overloading the root `README.md`.
- Do not silently let docs drift from implementation.