docs: add repository agent guidance

AGENTS.md

@@ -0,0 +1,34 @@
+# 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.