More fixes to the documentation

Signed-off-by: David Gageot <david.gageot@docker.com>

Author: dgageot

docs/pages/configuration/agents.html

@@ -27,16 +27,12 @@ <h2>Full Schema</h2>
       name: "prompt text"
     welcome_message: string        # Optional: message shown at session start
     handoffs: [list]               # Optional: list of A2A handoff agents
-    defer: [list] or true          # Optional: tools to load on demand
     hooks:                         # Optional: lifecycle hooks
       pre_tool_use: [list]
       post_tool_use: [list]
       session_start: [list]
       session_end: [list]
       on_user_input: [list]
-    permissions:                   # Optional: tool execution control
-      allow: [list]
-      deny: [list]
     structured_output:             # Optional: constrain output format
       name: string
       schema: object</code></pre>
@@ -125,18 +121,10 @@ <h2>Properties Reference</h2>
       <td><code>handoffs</code></td><td>array</td><td>✗</td>
       <td>List of A2A agent configurations this agent can delegate to. See <a href="#features/a2a" onclick="event.preventDefault(); navigate('features/a2a')">A2A Protocol</a>.</td>
     </tr>
-    <tr>
-      <td><code>defer</code></td><td>array/boolean</td><td>✗</td>
-      <td>Tools to load on-demand rather than at startup. Set to <code>true</code> to defer all tools, or provide a list of tool names.</td>
-    </tr>
     <tr>
       <td><code>hooks</code></td><td>object</td><td>✗</td>
       <td>Lifecycle hooks for running commands at various points. See <a href="#configuration/hooks" onclick="event.preventDefault(); navigate('configuration/hooks')">Hooks</a>.</td>
     </tr>
-    <tr>
-      <td><code>permissions</code></td><td>object</td><td>✗</td>
-      <td>Control which tools are auto-approved, require confirmation, or are blocked. See <a href="#configuration/permissions" onclick="event.preventDefault(); navigate('configuration/permissions')">Permissions</a>.</td>
-    </tr>
     <tr>
       <td><code>structured_output</code></td><td>object</td><td>✗</td>
       <td>Constrain agent output to match a JSON schema. See <a href="#configuration/structured-output" onclick="event.preventDefault(); navigate('configuration/structured-output')">Structured Output</a>.</td>
@@ -180,20 +168,23 @@ <h2>Deferred Tool Loading</h2>
     toolsets:
       - type: mcp
         ref: docker:github-official
+        defer: true
       - type: mcp
         ref: docker:slack
-      - type: filesystem
-    # Defer all tools - load when first used
-    defer: true</code></pre>
+        defer: true
+      - type: filesystem</code></pre>
 
-<p>Or defer specific tools:</p>
+<p>Or defer specific tools within a toolset:</p>
 
 <pre><code class="language-yaml">agents:
   root:
     model: openai/gpt-4o
-    defer:
-      - "mcp:github:*"    # Defer all GitHub tools
-      - "mcp:slack:*"     # Defer all Slack tools</code></pre>
+    toolsets:
+      - type: mcp
+        ref: docker:github-official
+        defer:
+          - "list_issues"
+          - "search_repos"</code></pre>
 
 <h2>Fallback Configuration</h2>
 
@@ -280,25 +271,15 @@ <h2>Complete Example</h2>
     description: Expert software developer
     instruction: Write clean, tested, production-ready code.
     max_iterations: 30
-    toolsets:
-      - type: filesystem
-      - type: shell
-      - type: think
-      - type: todo
-    permissions:
-      allow:
-        - "read_*"
-        - "shell:cmd=go*"
-        - "shell:cmd=npm*"
-      deny:
-        - "shell:cmd=sudo*"
     toolsets:
       - type: filesystem
       - type: shell
         sandbox:
           image: golang:1.23-alpine
           paths:
             - "."
+      - type: think
+      - type: todo
 
   researcher:
     model: openai/gpt-4o

docs/pages/configuration/overview.html

@@ -83,7 +83,7 @@ <h2>Config Sections</h2>
   <a class="card" href="#configuration/agents" onclick="event.preventDefault(); navigate('configuration/agents')">
     <div class="card-icon">🤖</div>
     <h3>Agent Config</h3>
-    <p>All agent properties: model, instruction, tools, sub-agents, permissions, hooks, and more.</p>
+    <p>All agent properties: model, instruction, tools, sub-agents, hooks, and more.</p>
   </a>
   <a class="card" href="#configuration/models" onclick="event.preventDefault(); navigate('configuration/models')">
     <div class="card-icon">🧠</div>

docs/pages/configuration/permissions.html

@@ -17,18 +17,19 @@ <h2>Configuration</h2>
     model: openai/gpt-4o
     description: Agent with permission controls
     instruction: You are a helpful assistant.
-    permissions:
-      # Auto-approve these tools (no confirmation needed)
-      allow:
-        - "read_file"
-        - "read_*"           # Glob patterns
-        - "shell:cmd=ls*"    # With argument matching
-      
-      # Block these tools entirely
-      deny:
-        - "shell:cmd=sudo*"
-        - "shell:cmd=rm*-rf*"
-        - "dangerous_tool"</code></pre>
+
+permissions:
+  # Auto-approve these tools (no confirmation needed)
+  allow:
+    - "read_file"
+    - "read_*"           # Glob patterns
+    - "shell:cmd=ls*"    # With argument matching
+  
+  # Block these tools entirely
+  deny:
+    - "shell:cmd=sudo*"
+    - "shell:cmd=rm*-rf*"
+    - "dangerous_tool"</code></pre>
 
 <h2>Pattern Syntax</h2>
 

docs/pages/configuration/sandbox.html

@@ -141,12 +141,13 @@ <h2>Combining with Permissions</h2>
           paths:
             - ".:rw"
       - type: filesystem
-    permissions:
-      allow:
-        - "shell:cmd=npm*"
-        - "shell:cmd=node*"
-        - "shell:cmd=ls*"
-      deny:
-        - "shell:cmd=sudo*"
-        - "shell:cmd=curl*"
-        - "shell:cmd=wget*"</code></pre>
+
+permissions:
+  allow:
+    - "shell:cmd=npm*"
+    - "shell:cmd=node*"
+    - "shell:cmd=ls*"
+  deny:
+    - "shell:cmd=sudo*"
+    - "shell:cmd=curl*"
+    - "shell:cmd=wget*"</code></pre>

docs/pages/guides/tips.html

@@ -65,18 +65,26 @@ <h3>Defer Tools for Faster Startup</h3>
     toolsets:
       - type: mcp
         ref: docker:github-official
+        defer: true
       - type: mcp
         ref: docker:slack
+        defer: true
       - type: mcp
         ref: docker:linear
-    # Load all tools on first use
-    defer: true</code></pre>
+        defer: true</code></pre>
 
-<p>Or defer specific tools:</p>
+<p>Or defer specific tools within a toolset:</p>
 
-<pre><code class="language-yaml">defer:
-  - "mcp:github:*"    # Defer GitHub tools
-  - "mcp:slack:*"     # Defer Slack tools</code></pre>
+<pre><code class="language-yaml">toolsets:
+  - type: mcp
+    ref: docker:github-official
+    defer:
+      - "list_issues"
+      - "search_repos"
+  - type: mcp
+    ref: docker:slack
+    defer:
+      - "list_channels"</code></pre>
 
 <h3>Filter MCP Tools</h3>
 
@@ -185,15 +193,15 @@ <h3>Combine Permissions with Sandbox</h3>
           image: golang:1.23-alpine
           paths:
             - ".:rw"
-    # Permission controls
-    permissions:
-      allow:
-        - "read_*"
-        - "shell:cmd=go*"
-        - "shell:cmd=npm*"
-      deny:
-        - "shell:cmd=sudo*"
-        - "shell:cmd=rm*-rf*"</code></pre>
+
+permissions:
+  allow:
+    - "read_*"
+    - "shell:cmd=go*"
+    - "shell:cmd=npm*"
+  deny:
+    - "shell:cmd=sudo*"
+    - "shell:cmd=rm*-rf*"</code></pre>
 
 <h3>Use Hooks for Audit Logging</h3>