diff --git a/docs/conventions.md b/docs/conventions.md
index 7c6f465c..3a94076a 100644
--- a/docs/conventions.md
+++ b/docs/conventions.md
@@ -316,6 +316,46 @@ or `ManagerServer` in `hive-ag3nt/src/mcp.rs`, add its name to the matching
 `ToolGroup::tools()` slice in `hive-sh4re/src/lib.rs`. That's the single
 source of truth; `allowed_mcp_tools` reads it at session start.
 
+## Capabilities
+
+Capabilities gate system-level access that goes beyond the MCP tool surface —
+things an agent can *access*, not just *call*. Parallel to tool groups but
+orthogonal: an agent can have a tool group that registers a tool AND a capability
+that allows the underlying resource access.
+
+| Capability | Effect |
+|---|---|
+| `manage_root_agent` | may lifecycle-manage the root/manager agent via `kill`/`start`/`restart` |
+| `read_host_journal` | `get_host_journal` MCP tool is registered + `GET /journal-host` requests are served |
+| `query_agent_state` | may call `get_loose_ends` / `CountPendingReminders` targeting non-child agents |
+
+**Config storage** — per-agent capabilities live in
+`/var/lib/hyperhive/meta/capabilities.json` alongside `tool-groups.json`.
+Format: `{ "atlas": ["read_host_journal"], "root": ["manage_root_agent"] }`.
+An absent entry means "no extra capabilities". `render_flake` in `meta.rs`
+reads this file and injects `HIVE_CAPABILITIES` (comma-separated
+`snake_case` names) into each agent's systemd service env; absent entries emit
+no env var so agents without capabilities don't trigger a spurious rebuild.
+
+**Setting capabilities** — the operator sets capabilities via the
+C4P4B1L1T13S section in the dashboard's P3RM1SS10NS tab.
+`hive-c0re::capabilities::set_caps(name, caps)` is the write path.
+After a change `meta::sync_agents` commits the updated file; the next agent
+rebuild picks up the new `HIVE_CAPABILITIES` env var.
+
+**Runtime resolution** — at session start the harness reads `HIVE_CAPABILITIES`
+and resolves each token to a `Capability` variant. Unrecognised tokens are
+logged and skipped. An absent or empty var means no extra capabilities.
+
+**Capability NOT configurable from `agent.nix`** — same reasoning as tool
+groups: an agent that could grant its own capabilities via a config commit would
+bypass the operator approval gate.
+
+**Adding a new capability** — add a variant to `Capability` in
+`hive-sh4re/src/lib.rs` + an arm to `as_str`. Add it to `Capability::ALL` (the
+source of truth for the permissions UI columns). Implement the access check in
+the relevant handler (`agent_server.rs`, `mcp.rs`, or `dashboard.rs`).
+
 ## Async forms
 
 Dashboard + per-agent mutating forms carry `data-async`; a delegated