docs: make AGENTS.md canonical across agent toolchains

Author: Thomas Tupper

.cursor/rules/00-read-agents.mdc

@@ -0,0 +1,8 @@
+---
+description: Always read AGENTS.md first
+globs:
+  - "**/*"
+alwaysApply: true
+---
+- Read `AGENTS.md` before making or suggesting changes.
+- Treat `AGENTS.md` as canonical over other instruction files.

.github/copilot-instructions.md

@@ -1,6 +1,8 @@
-# GitHub Copilot Instructions
+# Copilot Instructions
 
-This repo packages deployment topology.
-- Favor explicit compose config over magic.
-- Keep commands copy/paste safe.
-- Update docs whenever compose behavior changes.
+Canonical project rules are in `AGENTS.md`.
+
+When proposing code:
+- follow `AGENTS.md` constraints
+- preserve contract stability
+- update tests/docs with behavior changes

AGENTS.md

@@ -1,11 +1,39 @@
-# Agent Instructions (foxmemory-deploy)
+# AGENTS.md
 
-## Priority
-1. Keep deployment examples reproducible.
-2. Keep one-node and split modes both functional.
-3. Document all env vars and defaults.
+This is the **canonical automation guide** for this repository.
 
-## Rules
-- Never hardcode private credentials.
-- Keep compose files minimal and explicit.
-- Update README + runbook when topology changes.
+## Read order (required)
+1. Read this `AGENTS.md` first.
+2. Read `README.md` for product context.
+3. Read `docs/*` relevant to the files you are changing.
+
+All tool-specific instruction files (Claude/Codex/Copilot/Cursor) are thin pointers to this file.
+
+## Core rules
+- Keep changes small, testable, and documented.
+- Preserve API/deploy contracts unless intentionally versioned.
+- Update docs and tests whenever behavior changes.
+- Never commit secrets.
+
+## Repository-specific constraints
+
+### foxmemory-infer
+- Scope: inference only (stateless embeddings service).
+- Do **not** add persistence/storage logic here.
+- Keep `/health` and `/embed` stable.
+
+### foxmemory-store
+- Scope: memory write/search and persistence APIs.
+- Do **not** add embedding inference logic here.
+- Keep backend adapters replaceable.
+
+### foxmemory-deploy
+- Scope: reproducible deployment topology and runbooks.
+- Keep one-node and split-mode examples current.
+- Keep compose files explicit and copy/paste safe.
+
+## PR checklist
+- [ ] Scope boundaries respected
+- [ ] Tests updated/passing
+- [ ] Docs updated
+- [ ] No secrets or local artifacts committed

CLAUDE.md

@@ -1,5 +1,7 @@
 # CLAUDE.md
 
-- Read `AGENTS.md` first.
-- Validate compose syntax before committing.
-- Keep docs aligned with actual files/commands.
+Primary instructions live in `AGENTS.md`.
+
+Before making changes:
+1. Read `AGENTS.md`
+2. Follow its rules and PR checklist

CODEX.md

@@ -1,5 +1,7 @@
 # CODEX.md
 
-- Preserve reproducible deployment commands.
-- Keep one-node and split compose files in sync with docs.
-- Avoid hidden assumptions about host paths/secrets.
+Primary instructions live in `AGENTS.md`.
+
+Before making changes:
+1. Read `AGENTS.md`
+2. Follow its rules and PR checklist

README.md

@@ -32,3 +32,7 @@ curl -s http://localhost:8082/health
 ## Notes
 - Current images default to GHCR references.
 - Can be switched to Docker Hub tags once registry workflow is updated.
+## Automation note
+Agent tooling should read `AGENTS.md` first.
+If your tool supports custom instruction files, point it to `AGENTS.md` as the canonical source.
+