diff --git a/.cursor/rules/agents.md b/.cursor/rules/agents.md
new file mode 100644
index 000000000000..caf010359708
--- /dev/null
+++ b/.cursor/rules/agents.md
@@ -0,0 +1,6 @@
+---
+description: Project agent context (canonical source)
+alwaysApply: true
+---
+
+The canonical agent context for this repository lives in `AGENTS.md` at the repo root. Read it for commands, structure, conventions, and workflow before making changes.
diff --git a/.gitignore b/.gitignore
index 03eed15562da..3a5ff600ce22 100644
--- a/.gitignore
+++ b/.gitignore
@@ -265,4 +265,8 @@ chroma*/*
 stuff/*
 src/frontend/playwright-report/index.html
 *.bak
-prof/*
\ No newline at end of file
+prof/*
+# HQ context — generated indices and per-developer overrides
+.hq/
+AGENTS.local.md
+CLAUDE.local.md
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000000..05a7763673f8
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,26 @@
+# Project
+
+<!-- Authored by humans. Generated content (commit SHAs, feature state) is
+served from HQ's S3 cache + DB at agent run-time, never written here. -->
+
+## Commands
+- Build:
+- Test:
+- Dev:
+
+## Structure
+- Top-level dirs and what lives in each.
+
+## Conventions
+- Project-specific rules an agent wouldn't guess.
+
+## Gotchas
+- Project-specific traps.
+
+## Workflow
+- Never commit without explicit user request.
+- Never write tests unless explicitly asked.
+
+## Reference
+- Branch/feature runtime context: read live from HQ's DB by the server-side agent.
+- Repo indices (symbols, graph, skeletons): pulled from S3 by the HQ backend at agent run-time.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000000..99e1a578276a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,7 @@
+<!-- HQ pointer stub — do not edit. Canonical context lives in AGENTS.md. -->
+
+# Project
+
+This repository's agent context is maintained in [AGENTS.md](./AGENTS.md).
+
+Claude Code reads `AGENTS.md` natively — see that file for commands, structure, conventions, and workflow.