diff --git a/AGENTS.md b/AGENTS.md
index b764044..562fb24 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -137,3 +137,22 @@ hook utils — add new auto-updated fields there.
 
 The hook files are deployed by hand into the PB server's `pb_hooks/`
 (like select values, it's a manual step on the live instance).
+# Giellie agent (`/giellie`) — tools come from the MCP, policy lives in one file
+
+The sidebar "Giellie Agent" is a MiniMax chat agent (`src/lib/server/giellie-*.ts`,
+routes under `/api/v1/giellie/*`, chats in the `giellie_chats` PB collection).
+It calls the **same MCP handler** as Hermes/n8n (`src/app/api/mcp/route.ts`),
+in-process — a new MCP tool is automatically available to Giellie.
+
+- Safety lives in `src/lib/server/giellie-tool-policy.ts`: `*.delete` and secret/base64
+  tools are denied; only tools in `READ_TOOLS` run without approval; everything else
+  (including brand-new tools) pauses for an Approve/Reject card; email/PO sends always
+  ask. **When you add a read-only MCP tool, add it to `READ_TOOLS`** or Giellie will
+  ask approval for every call.
+- Every `/api/v1/giellie/*` route authenticates with `getBrowserSessionUser(req)`
+  (PB token in `Authorization`). These routes hold `AGENT_API_KEY`; never expose one
+  without that check.
+- Config (key, model, base URL, on/off) is the existing `/settings/ai` row; Giellie
+  uses its own system prompt in `giellie-system-prompt.ts`.
+- The `giellie_chats` collection is created by `npm run pb:migrate:giellie-chats`
+  (manual step on the live PB, like select values and pb_hooks).