diff --git a/backends.go b/backends.go
index 0f26083..723119e 100644
--- a/backends.go
+++ b/backends.go
@@ -142,16 +142,16 @@ type PermissionBackend interface {
 	Check(permission string) bool
 }
 
-// Permissions checks the current caller's effective permissions: the same
-// built-in permissions, legacy role permissions, and plugin-declared custom
-// permissions evaluated by the requirePermissions route middleware, plus any
-// custom permission granted to the caller's project/global role. Use it from
-// route handlers to enforce authorization finer-grained than the single
-// all-or-nothing scope declared on the route's manifest entry — e.g. "is the
-// caller the record's owner OR do they hold time_logging.manage_all".
+// Permissions checks whether the current caller may perform an IAM action
+// ("<domain>:<verb>", built-in such as "tasks:write" or plugin-declared such
+// as "time_logging:manage_all"), decided by the host's IAM engine exactly as
+// the requireActions route middleware decides it. Use it from route handlers
+// to enforce authorization finer-grained than the single all-or-nothing
+// requireActions gate on the route's manifest entry — e.g. "is the caller the
+// record's owner OR may they time_logging:manage_all".
 type Permissions struct {
 	backend PermissionBackend
 }
 
-// Check reports whether the current caller holds the given permission key.
+// Check reports whether the current caller may perform the given IAM action.
 func (p *Permissions) Check(permission string) bool { return p.backend.Check(permission) }
diff --git a/plugintest/backends.go b/plugintest/backends.go
index 9bdfa2c..55414e9 100644
--- a/plugintest/backends.go
+++ b/plugintest/backends.go
@@ -651,7 +651,7 @@ func (c *InMemoryConfig) Get(key string) (string, bool) {
 // FakePermissions is an in-memory plugin.PermissionBackend for tests. All
 // permissions are denied by default; call Grant to simulate a caller who
 // holds a given permission (typically a plugin-declared custom permission,
-// e.g. "time_logging.manage_all").
+// e.g. "time_logging:manage_all").
 type FakePermissions struct {
 	mu      sync.Mutex
 	granted map[string]bool
diff --git a/wasm_imports.go b/wasm_imports.go
index 0d5bfaa..3ae725b 100644
--- a/wasm_imports.go
+++ b/wasm_imports.go
@@ -96,7 +96,8 @@ func hostActivityRecord(payloadPtr, payloadLen int64) int32
 //go:noescape
 func hostConfigGet(keyPtr, keyLen, valuePtrPtr, valueLenPtr int64)
 
-// paca.permission_check(permissionPtr i64, permissionLen i64) -> ok i32
+// paca.permission_check(actionPtr i64, actionLen i64) -> ok i32 — whether
+// the caller may perform the given IAM action ("<domain>:<verb>").
 //
 //go:wasmimport paca permission_check
 //go:noescape