diff --git a/docs/README.md b/docs/README.md
index 95c804ef..da5f2cd2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -39,7 +39,7 @@ declarations.
 
 ## Trust boundary & security
 
-- **What's the operator/agent trust boundary? What's a capability?** →
+- **What's the operator/agent trust boundary? What's a permission?** →
   [`trust-boundary/boundary.md`](trust-boundary/boundary.md).
 - **Agent trust model, prompt-injection threat model, credential
   isolation?** → [`trust-boundary/security.md`](trust-boundary/security.md).
diff --git a/docs/agent-lifecycle/agent-roster.md b/docs/agent-lifecycle/agent-roster.md
index 83f53945..c8e1ec65 100644
--- a/docs/agent-lifecycle/agent-roster.md
+++ b/docs/agent-lifecycle/agent-roster.md
@@ -36,13 +36,13 @@ One entry per agent _this hive_ has state/config for, in name order.
 Unlike the swarm roster, it's a derived cache: the reconcile pass below
 rebuilds it from what the hive observes locally (config repos cloned, containers spawned), and it
 answers a narrower question than "does this agent exist": _which of
-this hive's local agents the `ManageRootAgent` capability's bind-mounts
+this hive's local agents the `ManageRootAgent` permission's bind-mounts
 should cover._ `topology::all_agents` is the only reader that matters.
 
 That reader is a permission boundary: the set it returns is what an agent
-holding the `ManageRootAgent` capability gets bind-mounted (each other
+holding the `ManageRootAgent` permission gets bind-mounted (each other
 agent's `state` read-write and `config` read-only; never `harness`). An
-agent holding no capability sees its own dirs and nothing else:
+agent holding no permission sees its own dirs and nothing else:
 `ManageRootAgent` is the only grant that reaches another agent's state
 dir. See
 [`persistence.md`](persistence.md)'s _Cross-agent access to state._
@@ -51,7 +51,7 @@ dir. See
 
 `topology.json` may also be a map of `name → parent | null`; the reader
 accepts that shape and takes its keys as the roster. An empty
-roster costs more than a cosmetic gap: every capability holder loses its
+roster costs more than a cosmetic gap: every permission holder loses its
 mounts until the next reconcile pass writes the array form.
 
 ### Why meta, not per-agent `agent.nix`
diff --git a/hive-c0re/README.md b/hive-c0re/README.md
index ee121130..758aed69 100644
--- a/hive-c0re/README.md
+++ b/hive-c0re/README.md
@@ -34,8 +34,8 @@ to track it:
 - **`stores/`** — sqlite-backed stores (broker, queues, audit, power).
 - **`workers/`** — background sweeps (crash watch,
   autoupdate, knowledge sync).
-- **`agent_config/`** — per-agent registries (tool groups,
-  capabilities, resource limits, topology).
+- **`agent_config/`** — per-agent registries (permissions,
+  resource limits, topology).
 - **`stats/`** — dashboard metrics aggregation + OTEL export.
 - **`socket_server/`** — the unix-socket request server shared by
   per-agent + manager sockets.
diff --git a/hive-c0re/src/agent_config/topology.rs b/hive-c0re/src/agent_config/topology.rs
index d25e807c..e7b13b84 100644
--- a/hive-c0re/src/agent_config/topology.rs
+++ b/hive-c0re/src/agent_config/topology.rs
@@ -66,7 +66,7 @@ fn read_from(path: &Path) -> std::io::Result<BTreeSet<String>> {
 
 /// Every agent the roster knows about, in name order. This is the set
 /// a [`hive_sh4re::permissions::Permission::ManageRootAgent`] holder gets
-/// bind-mounted, and it is deliberately unfiltered: that capability means
+/// bind-mounted, and it is deliberately unfiltered: that permission means
 /// "may manage any agent", so the set is all of them.
 ///
 /// An unreadable roster is logged and yields no agents, so the holder
diff --git a/nix/agent-modules/agent-service.nix b/nix/agent-modules/agent-service.nix
index 27d803f0..5350766e 100644
--- a/nix/agent-modules/agent-service.nix
+++ b/nix/agent-modules/agent-service.nix
@@ -19,7 +19,7 @@ let
   # Tools opencode must not offer, mirroring claude's built-in allow-list
   # (hive_sh4re::permissions): no built-in shell (shell is `mcp__bash__run`),
   # no nested agents, no in-session todo list, no web search. `webfetch`
-  # asks, and the harness answers per the `web_tools` tool group. Passed as
+  # asks, and the harness answers per the `web_tools` permission. Passed as
   # OPENCODE_PERMISSION because opencode merges that over every config file,
   # including ones the agent can write.
   opencodePermission = {