Merge pull request #1893 from dgageot/doc-fixes

Fixes to the documentation

Author: dgageot

docs/pages/configuration/agents.html

@@ -27,19 +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]
-    sandbox:                       # Optional: shell isolation
-      image: string
-      paths: [list]
     structured_output:             # Optional: constrain output format
       name: string
       schema: object</code></pre>
@@ -128,22 +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>sandbox</code></td><td>object</td><td>✗</td>
-      <td>Run shell commands in an isolated Docker container. See <a href="#configuration/sandbox" onclick="event.preventDefault(); navigate('configuration/sandbox')">Sandbox Mode</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>
@@ -187,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>
 
@@ -290,19 +274,12 @@ <h2>Complete Example</h2>
     toolsets:
       - type: filesystem
       - type: shell
+        sandbox:
+          image: golang:1.23-alpine
+          paths:
+            - "."
       - type: think
       - type: todo
-    permissions:
-      allow:
-        - "read_*"
-        - "shell:cmd=go*"
-        - "shell:cmd=npm*"
-      deny:
-        - "shell:cmd=sudo*"
-    sandbox:
-      image: golang:1.23-alpine
-      paths:
-        - "."
 
   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

@@ -19,11 +19,11 @@ <h2>Configuration</h2>
     instruction: You are a helpful assistant.
     toolsets:
       - type: shell
-    sandbox:
-      image: alpine:latest    # Docker image to use
-      paths:                  # Directories to mount
-        - "."                 # Current directory (read-write)
-        - "/data:ro"          # Read-only mount</code></pre>
+        sandbox:
+          image: alpine:latest    # Docker image to use
+          paths:                  # Directories to mount
+            - "."                 # Current directory (read-write)
+            - "/data:ro"          # Read-only mount</code></pre>
 
 <h2>Properties</h2>
 
@@ -63,12 +63,12 @@ <h2>Example: Development Agent</h2>
       build commands and tests. Your shell runs in a sandbox.
     toolsets:
       - type: shell
-      - type: filesystem
-    sandbox:
-      image: node:20-alpine    # Node.js environment
-      paths:
-        - "."                  # Project directory
-        - "/tmp:rw"            # Temp directory for builds</code></pre>
+        sandbox:
+          image: node:20-alpine    # Node.js environment
+          paths:
+            - "."                  # Project directory
+            - "/tmp:rw"            # Temp directory for builds
+      - type: filesystem</code></pre>
 
 <h2>How It Works</h2>
 
@@ -136,17 +136,18 @@ <h2>Combining with Permissions</h2>
     instruction: You are a helpful assistant.
     toolsets:
       - type: shell
+        sandbox:
+          image: node:20-alpine
+          paths:
+            - ".:rw"
       - type: filesystem
-    sandbox:
-      image: node:20-alpine
-      paths:
-        - ".:rw"
-    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>
 
@@ -181,20 +189,19 @@ <h3>Combine Permissions with Sandbox</h3>
     toolsets:
       - type: filesystem
       - type: shell
-    # Layer 1: Permission controls
-    permissions:
-      allow:
-        - "read_*"
-        - "shell:cmd=go*"
-        - "shell:cmd=npm*"
-      deny:
-        - "shell:cmd=sudo*"
-        - "shell:cmd=rm*-rf*"
-    # Layer 2: Container isolation
-    sandbox:
-      image: golang:1.23-alpine
-      paths:
-        - ".:rw"</code></pre>
+        sandbox:
+          image: golang:1.23-alpine
+          paths:
+            - ".:rw"
+
+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>