diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9ad2197
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,67 @@
+# AGENTS.md
+
+## Stack
+
+Two independent packages in one repo:
+
+| Directory | Role | Entry | Build |
+|-----------|------|-------|-------|
+| `src/` | TypeScript OpenClaw plugin | `src/index.ts` | esbuild → `dist/index.js` |
+| `python/` | Python CLI indexer | `obsidian_rag/cli.py` | pip install -e |
+
+## Commands
+
+**TypeScript (OpenClaw plugin):**
+```bash
+npm run build     # esbuild → dist/index.js
+npm run typecheck # tsc --noEmit
+npm run test      # vitest run
+```
+
+**Python (RAG indexer):**
+```bash
+pip install -e python/          # editable install
+obsidian-rag index|sync|reindex|status   # CLI
+pytest python/                 # tests
+ruff check python/              # lint
+```
+
+## OpenClaw Plugin Install
+
+Plugin `package.json` MUST have:
+```json
+"openclaw": {
+  "extensions": ["./dist/index.js"],
+  "hook": []
+}
+```
+- `extensions` = array, string path
+- `hook` = singular, not `hooks`
+
+## Config
+
+User config at `~/.obsidian-rag/config.json` or `./obsidian-rag/` dev config.
+
+Key security fields:
+- `security.require_confirmation_for` — list of categories (e.g. `["health", "financial_debt"]`). Empty list disables guard.
+- `security.auto_approve_sensitive` — `true` bypasses sensitive content prompts.
+- `security.local_only` — `true` blocks non-localhost Ollama.
+
+## Ollama Context Length
+
+`python/obsidian_rag/embedder.py` truncates chunks at `MAX_CHUNK_CHARS = 8000` before embedding. If Ollama 500 error returns, increase this value or reduce `indexing.chunk_size` in config.
+
+## Sensitive Content Guard
+
+Triggered by categories in `require_confirmation_for`. Raises `SensitiveContentError` from `obsidian_rag/indexer.py`.
+
+To disable: set `require_confirmation_for: []` or `auto_approve_sensitive: true` in config.
+
+## Architecture
+
+```
+User query → OpenClaw (TypeScript plugin src/index.ts)
+           → obsidian_rag_* tools (python/obsidian_rag/)
+           → Ollama embeddings (http://localhost:11434)
+           → LanceDB vector store
+```