docs: fix permission docs

1 files changed, 36 insertions, 68 deletions

diff --git a/packages/web/src/content/docs/agents.mdx b/packages/web/src/content/docs/agents.mdx
index 82d3c8ccb..7016d6576 100644
--- a/packages/web/src/content/docs/agents.mdx
+++ b/packages/web/src/content/docs/agents.mdx
@@ -362,42 +362,33 @@ Here are all the tools can be controlled through the agent config.
 
 ### Permissions
 
-Permissions control what actions an agent can take.
+You can configure permissions to manage what actions an agent can take. Currently, the permissions for the `edit`, `bash`, and `webfetch` tools can be configured to:
 
-- edit, bash, webfetch
-
-Each permission can be set to allow, ask, or deny.
-
-- allow, ask, deny
-
-Configure permissions globally in opencode.json.
+- `"ask"` — Prompt for approval before running the tool
+- `"allow"` — Allow all operations without approval
+- `"deny"` — Disable the tool
 
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
   "permission": {
-    "edit": "ask",
-    "bash": "allow",
-    "webfetch": "deny"
+    "edit": "deny"
   }
 }
 ```
 
-You can override permissions per agent in JSON.
+You can override these permissions per agent.
 
-```json title="opencode.json" {7-18}
+```json title="opencode.json" {3-5,8-10}
 {
   "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "deny"
+  },
   "agent": {
     "build": {
       "permission": {
-        "edit": "allow",
-        "bash": {
-          "*": "allow",
-          "git push": "ask",
-          "terraform *": "deny"
-        },
-        "webfetch": "ask"
+        "edit": "ask"
       }
     }
   }
@@ -419,83 +410,60 @@ permission:
 Only analyze code and suggest changes.
 ```
 
-Bash permissions support granular patterns for fine-grained control.
-
-```json title="Allow most, ask for risky, deny terraform"
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "bash": {
-      "*": "allow",
-      "git push": "ask",
-      "terraform *": "deny"
-    }
-  }
-}
-```
-
-If you provide a granular bash map, the default becomes ask unless you set \* explicitly.
+You can set permissions for specific bash commands.
 
-```json title="Granular defaults to ask"
+```json title="opencode.json" {7}
 {
   "$schema": "https://opencode.ai/config.json",
-  "permission": {
-    "bash": {
-      "git status": "allow"
-    }
-  }
-}
-```
-
-Agent-level permissions merge over global settings.
-
-- Global sets defaults; agent overrides when specified
-
-Specific bash rules can override a global default.
-
-```json title="Global ask, agent allows safe commands"
-{
-  "$schema": "https://opencode.ai/config.json",
-  "permission": { "bash": "ask" },
   "agent": {
     "build": {
       "permission": {
-        "bash": { "git status": "allow", "*": "ask" }
+        "bash": {
+          "git push": "ask"
+        }
       }
     }
   }
 }
 ```
 
-Permissions affect tool availability and prompts differently.
-
-- deny hides tools (edit also hides write/patch); ask prompts; allow runs
-
-For quick reference, here are common setups.
+This can take a glob pattern.
 
-```json title="Read-only reviewer"
+```json title="opencode.json" {7}
 {
   "$schema": "https://opencode.ai/config.json",
   "agent": {
-    "review": {
-      "permission": { "edit": "deny", "bash": "deny", "webfetch": "allow" }
+    "build": {
+      "permission": {
+        "bash": {
+          "git *": "ask"
+        }
+      }
     }
   }
 }
 ```
 
-```json title="Planning agent that can browse but cannot change code"
+And you can also use the `*` wildcard to manage permissions for all commands.
+Where the specific rule can override the `*` wildcard.
+
+```json title="opencode.json" {8}
 {
   "$schema": "https://opencode.ai/config.json",
   "agent": {
-    "plan": {
-      "permission": { "edit": "deny", "bash": "deny", "webfetch": "ask" }
+    "build": {
+      "permission": {
+        "bash": {
+          "git status": "allow",
+          "*": "ask"
+        }
+      }
     }
   }
 }
 ```
 
-See the full [permissions guide](/docs/permissions) for more patterns.
+[Learn more about permissions](/docs/permissions).
 
 ---