docs(config): colocate [[agents]] with users/groups in example config

pgconsole.example.toml

@@ -181,39 +181,12 @@ labels = ["staging"]
 # [[groups]]
 # id = "dev-team"
 # name = "Development Team"
-# members = ["developer", "alice@example.com"]
+# members = ["developer@example.com", "alice@example.com"]
 #
 # [[groups]]
 # id = "dba"
 # name = "Database Administrators"
-# members = ["admin"]
-
-# =============================================================================
-# IAM Rules (optional - requires auth to be enabled)
-# =============================================================================
-# Controls what users can do on each connection
-# Permissions: read (SELECT), write (INSERT/UPDATE/DELETE), ddl (CREATE/ALTER/DROP),
-#   admin (full access), explain (EXPLAIN), execute (CALL), export (CSV export)
-#   Use "*" to grant all permissions at once
-# Members: "user:username", "group:groupid", or "*" for all users
-# Connection: specific connection id or "*" for all connections
-# Multiple matching rules are unioned (user gets all permissions from all matching rules)
-# Default deny: no matching rule = no access (connection hidden from user)
-#
-# [[iam]]
-# connection = "*"
-# permissions = ["read"]
-# members = ["*"]
-#
-# [[iam]]
-# connection = "local"
-# permissions = ["*"]
-# members = ["user:admin", "group:dba"]
-#
-# [[iam]]
-# connection = "staging"
-# permissions = ["read", "write"]
-# members = ["group:dev-team"]
+# members = ["admin@example.com"]
 
 # =============================================================================
 # Agents (optional) - non-human principals for the MCP server
@@ -233,17 +206,12 @@ labels = ["staging"]
 # Fields: id (required), token (required), name (optional, defaults to id),
 #   on_behalf_of (user email), permissions (delegated only), connections (delegated only)
 #
-# # Pure agent - authorize it with an [[iam]] rule using member "agent:<id>"
+# # Pure agent - authorize it with an [[iam]] rule using member "agent:<id>" (see below)
 # [[agents]]
 # id = "ci-bot"
 # name = "CI Pipeline"
 # token = "generate-a-long-random-secret"   # openssl rand -hex 32
 #
-# [[iam]]
-# connection = "staging"
-# permissions = ["read", "ddl"]
-# members = ["agent:ci-bot"]
-#
 # # Delegated agent - acts as alice, capped to read-only on the local connection
 # [[agents]]
 # id = "alice-assistant"
@@ -252,3 +220,38 @@ labels = ["staging"]
 # on_behalf_of = "alice@example.com"   # must match a [[users]] email
 # permissions = ["read"]               # cap: intersected with alice's IAM grant
 # connections = ["local"]              # cap: connection IDs the agent may touch
+
+# =============================================================================
+# IAM Rules (optional - requires auth to be enabled)
+# =============================================================================
+# Controls what users can do on each connection
+# Permissions: read (SELECT), write (INSERT/UPDATE/DELETE), ddl (CREATE/ALTER/DROP),
+#   admin (full access), explain (EXPLAIN), execute (CALL), export (CSV export)
+#   Use "*" to grant all permissions at once
+# Members: "user:<email>", "group:<id>", "agent:<id>", or "*" (all human users; a pure
+#   agent matches only explicit "agent:<id>" rules, never "*"/"user:"/"group:",
+#   while a delegated agent inherits its user's matches)
+# Connection: specific connection id or "*" for all connections
+# Multiple matching rules are unioned (user gets all permissions from all matching rules)
+# Default deny: no matching rule = no access (connection hidden from user)
+#
+# [[iam]]
+# connection = "*"
+# permissions = ["read"]
+# members = ["*"]
+#
+# [[iam]]
+# connection = "local"
+# permissions = ["*"]
+# members = ["user:admin@example.com", "group:dba"]
+#
+# [[iam]]
+# connection = "staging"
+# permissions = ["read", "write"]
+# members = ["group:dev-team"]
+#
+# # Authorize a pure agent (see the Agents section above)
+# [[iam]]
+# connection = "staging"
+# permissions = ["read", "ddl"]
+# members = ["agent:ci-bot"]