docs: add Sessions, Code Mode, headless/CI guide, and expand the CLI reference

docs/configuration/agents/index.md

@@ -32,7 +32,7 @@ agents:
     add_prompt_files: [list] # Optional: include additional prompt files
     add_description_parameter: bool # Optional: add description to tool schema
     redact_secrets: boolean # Optional: scrub detected secrets out of tool args, outgoing chat messages, and tool output
-    code_mode_tools: boolean # Optional: enable code mode tool format
+    code_mode_tools: boolean # Optional: let the agent write JavaScript to orchestrate tool calls (see Code Mode)
     max_iterations: int # Optional: max tool-calling loops
     max_consecutive_tool_calls: int # Optional: max identical consecutive tool calls
     max_old_tool_call_tokens: int # Optional: token budget for old tool call content (disabled unless positive)
@@ -96,7 +96,7 @@ agents:
 | `add_prompt_files`          | array   | ✗        | List of file paths whose contents are appended to the system prompt. Useful for including coding standards, guidelines, or additional context.                                |
 | `add_description_parameter` | boolean | ✗        | When `true`, adds agent descriptions as a parameter in tool schemas. Helps with tool selection in multi-agent scenarios.                                                      |
 | `redact_secrets`            | boolean | ✗        | When `true`, scrubs detected secrets (API keys, tokens, private keys, etc.) out of tool-call arguments, outgoing chat messages, and tool output before they reach a tool, the model, or downstream consumers. See [Redacting Secrets](#redacting-secrets) below.   |
-| `code_mode_tools`           | boolean | ✗        | When `true`, formats tool responses in a code-optimized format with structured output schemas. Useful for MCP gateway and programmatic access.                                |
+| `code_mode_tools`           | boolean | ✗        | When `true`, replaces the agent's individual tools with a single tool that runs a JavaScript script calling as many of them as needed in one turn. See [Code Mode](../../features/code-mode/index.md). |
 | `max_iterations`            | int     | ✗        | Maximum number of tool-calling loops. Default: unlimited (0). Set this to prevent infinite loops.                                                                             |
 | `max_consecutive_tool_calls` | int     | ✗        | Maximum consecutive identical tool calls before the agent is terminated, preventing degenerate loops. Default: `5`.                                                          |
 | `max_old_tool_call_tokens`  | int     | ✗        | Maximum number of tokens to keep from old tool call arguments and results. Older tool calls beyond this budget have their content replaced with a placeholder, saving context space. Tokens are approximated as `len/4`. Truncation is disabled by default; set a positive value to enable it. Set to `-1` to disable truncation (unlimited). |

docs/configuration/permissions/index.md

@@ -104,7 +104,7 @@ Permissions support glob-style patterns with optional argument matching:
 | -------------- | ------------------------------ |
 | `shell`        | Exact match for `shell` tool   |
 | `read_*`       | Any tool starting with `read_` |
-| `mcp:github:*` | Any GitHub MCP tool            |
+| `github_*`     | Any GitHub MCP tool            |
 | `*`            | All tools                      |
 
 ### Argument Matching
@@ -219,13 +219,13 @@ Control MCP tools by their qualified names:
 permissions:
   allow:
     # Allow all GitHub read operations
-    - "mcp:github:get_*"
-    - "mcp:github:list_*"
-    - "mcp:github:search_*"
+    - "github_get_*"
+    - "github_list_*"
+    - "github_search_*"
   deny:
     # Block destructive GitHub operations
-    - "mcp:github:delete_*"
-    - "mcp:github:close_*"
+    - "github_delete_*"
+    - "github_close_*"
 ```
 
 ## Combining with Hooks

docs/data/nav.yml

@@ -122,6 +122,8 @@
       url: /features/snapshots/
     - title: Kanban Board
       url: /features/board/
+    - title: Sessions
+      url: /features/sessions/
     - title: CLI Reference
       url: /features/cli/
     - title: MCP Mode
@@ -140,6 +142,8 @@
       url: /features/evaluation/
     - title: Skills
       url: /features/skills/
+    - title: Code Mode
+      url: /features/code-mode/
     - title: Remote MCP Servers
       url: /features/remote-mcp/
 
@@ -220,6 +224,8 @@
           url: /guides/go-sdk/
         - title: Managing Context & Compaction
           url: /guides/compaction/
+        - title: Running Agents Headless & in CI
+          url: /guides/headless/
     - label: Community
       items:
         - title: Contributing

docs/features/cli/index.md

@@ -30,14 +30,14 @@ $ docker agent run [config] [message...] [flags]
 | `-a, --agent <name>`                    | Run a specific agent from the config                                                                                                      |
 | `--yolo`                                | Auto-approve tool calls (unless explicitly denied)                                                                                        |
 | `--model <ref>`                         | Override model(s). Use `provider/model` for all agents, or `agent=provider/model` for specific agents. Comma-separate multiple overrides. |
-| `--session <id>`                        | Resume a previous session. Supports relative refs (`-1` = last, `-2` = second to last). An explicit ID that does not exist yet is created with that ID, so a supervisor can own the session ID upfront and reuse it across runs. |
+| `--session <id>`                        | Resume a previous session. Supports relative refs (`-1` = newest by creation time, `-2` = second-newest, … — creation order, not last-used). An explicit ID that does not exist yet is created with that ID, so a supervisor can own the session ID upfront and reuse it across runs. |
 | `-s, --session-db <path>`               | Path to the SQLite session database (default: `<data-dir>/session.db`, so `~/.cagent/session.db` unless `--data-dir` is set)              |
 | `--session-read-only`                   | Open the TUI in read-only mode: conversation history is displayed but no new messages can be sent to the LLM. Cannot be used with `--exec`. |
 | `--prompt-file <path>`                  | Include file contents as additional system context (repeatable)                                                                           |
 | `--attach <path>`                       | Attach an image file to the initial message                                                                                               |
 | `--dry-run`                             | Initialize the agent without executing anything (useful for validating a config)                                                          |
-| `--remote <addr>`                       | Use a remote runtime at the given address instead of running the agent locally                                                            |
-| `--listen <addr>`                       | Expose this run's control plane over HTTP so an external process can drive the running TUI (send follow-ups, stream events, read the title). Accepts `host:port` or `unix://`, `npipe://`, `fd://`. See the [API Server](../api-server/index.md#listen). |
+| `--remote <addr>`                       | Use a remote runtime at the given address instead of running the agent locally. Mutually exclusive with `--sandbox`, `--worktree`, `--worktree-pr`, `--worktree-base`, `--session`, `--session-db`, `--record`, and `--fake` — a remote runtime owns its own session storage and execution environment, so these local-only concerns don't apply. |
+| `--listen <addr>`                       | Expose this run's control plane over HTTP so an external process can drive the running TUI (send follow-ups, stream events, read the title). Accepts `host:port` or `unix://`, `npipe://`, `fd://`. Hidden from `docker agent run --help` — like `debug`, it's a stable but advanced/automation-oriented flag rather than a day-to-day one. See the [API Server](../api-server/index.md#listen) guide for the full walkthrough. |
 | `--lean`                                | Use a simplified, non-alternate-screen TUI. Unlike the default full-screen TUI, this renders inline in the normal terminal buffer — useful in environments where an alternate screen is unwanted (e.g. inside tmux panes, CI with a tty, or log-friendly pipelines). Displays an ASCII art banner on startup. |
 | `--app-name <name>`                     | Override the application name label shown in the TUI (status bar, window title, "/exit" notifications).                                   |
 | `--sidebar`                             | Control sidebar visibility. Set to `--sidebar=false` to hide the sidebar and disable the Ctrl+B toggle (default: `true`).                 |
@@ -177,6 +177,16 @@ $ docker agent new --model openai/gpt-5
 $ docker agent new --model dmr/ai/gemma3-qat:12B --max-iterations 15
 ```
 
+### `docker agent getting-started`
+
+Run a short (about 2 minutes), skippable interactive tour inside the chat UI: sending messages, approving tool calls, the command palette (<kbd>Ctrl</kbd>+<kbd>K</kbd>), slash commands, and how agents are configured. Aliased as `docker agent tour`. Requires an interactive terminal.
+
+```bash
+$ docker agent getting-started
+```
+
+Replay it anytime with this command, or with the `/getting-started` slash command inside a running TUI session.
+
 ### `docker agent models`
 
 List models available for use with `--model`. By default only shows models for providers you have credentials for. Aliases: `docker agent models list`, `docker agent models ls`.
@@ -577,6 +587,72 @@ $ docker agent sandbox deny api.example.com
 
 Entries are unioned with the gateway, the kit-resolved tool install hosts, and any `runtime.network_allowlist` declared by the agent. The launch summary lists every source separately so you can see which holes were punched by which layer.
 
+### `docker agent debug`
+
+Troubleshooting subcommands for inspecting how an agent config resolves and generating diagnostic output — useful when a config isn't behaving the way you expect. `debug` doesn't appear in `docker agent --help` (it's a diagnostic surface, not a day-to-day command), but every subcommand below is stable and fully supported.
+
+```bash
+$ docker agent debug <subcommand> [flags]
+```
+
+| Subcommand | Description |
+| ---------- | ----------- |
+| `config <agent-file>` | Print the fully-resolved, canonical form of an agent's configuration (defaults applied, references resolved). |
+| `toolsets <agent-file>` | List every toolset each agent in the config exposes, with each tool's name and description. |
+| `skills <agent-file>` | List the skills discovered for each agent, marking forked skills. |
+| `title <agent-file> <question>` | Generate a session title for `<question>` using the same title-generation path the TUI uses (including any configured `title_model`), without starting a session. See [Session Titles](../sessions/index.md#session-titles). |
+| `auth` | Print parsed Docker Desktop authentication info from the locally stored JWT (subject, issuer, expiry, username/email). Add `--json` for machine-readable output. |
+| `oauth list` | List stored MCP OAuth tokens (resource, scope, expiry, redacted access token). Add `--json` for machine-readable output. |
+| `oauth remove <resource-url>` | Remove a stored MCP OAuth token. |
+| `oauth login <agent-file> <mcp-name>` | Perform an interactive OAuth login for a remote MCP server declared in the config, by its name or URL. See [Remote MCP Servers](../remote-mcp/index.md). |
+
+```bash
+# Examples
+$ docker agent debug config agent.yaml
+$ docker agent debug toolsets agent.yaml
+$ docker agent debug skills agent.yaml
+$ docker agent debug title agent.yaml "How do I configure a fallback model?"
+$ docker agent debug auth --json
+$ docker agent debug oauth list
+$ docker agent debug oauth login agent.yaml github
+```
+
+> [!WARNING]
+> **`debug auth --json` prints the full bearer token**
+>
+> The text output of `debug auth` truncates the token to a short preview, but `--json` includes the complete, unredacted JWT in its `token` field. Never paste `debug auth --json` output into logs, issue trackers, or bug reports — anyone with that token can act as you against Docker Desktop's backend. Use the plain-text output (or redact the `token` field yourself) when sharing diagnostic output.
+
+The `config`, `toolsets`, `skills`, and `title` subcommands also accept [runtime configuration flags](#runtime-configuration-flags) (`--working-dir`, `--models-gateway`, …); `title` additionally accepts `--model` to override the model used to resolve the config before generating the title.
+
+### `docker agent completion`
+
+Generate a shell completion script for `bash`, `zsh`, `fish`, or `powershell`.
+
+```bash
+$ docker agent completion <bash|zsh|fish|powershell>
+
+# Examples
+# Bash: load for the current session
+$ source <(docker agent completion bash)
+
+# Zsh: install permanently (adjust the path for your $fpath)
+$ docker agent completion zsh > "${fpath[1]}/_docker-agent"
+```
+
+Run `docker agent completion <shell> --help` for shell-specific installation instructions.
+
+### Self-update
+
+When installed from a standalone GitHub release binary, Docker Agent can opt in to updating itself. It's disabled by default; set `DOCKER_AGENT_AUTO_UPDATE` to a truthy value (`1`, `true`, `yes`, `on`) to enable it for a command or a shell session:
+
+```bash
+$ DOCKER_AGENT_AUTO_UPDATE=1 docker agent run
+```
+
+When enabled, every command checks the latest GitHub release before running. If a newer release exists, an interactive session asks whether to install it; a non-interactive session (CI, piped input) proceeds automatically. On yes, Docker Agent downloads the asset for your OS/architecture, verifies its checksum, replaces the current binary, and re-executes with the same arguments. The whole mechanism is fail-safe: any failure at any step falls back to running the current binary. Self-update never triggers for `version`, `help`, `--help`/`-h` (including per-subcommand help), `completion`, or the Docker CLI plugin metadata handshake.
+
+See [Optional Self-Updates](../../getting-started/installation/index.md#optional-self-updates) for the full walkthrough. Docker Desktop and Homebrew installs already manage updates and don't need this.
+
 ## Global Flags
 
 These flags are available on every `docker agent` command:
@@ -616,6 +692,7 @@ These flags are accepted by every command that loads an agent (`run`, `run --exe
 | `--hook-session-end <cmd>`      | Add a session-end hook command (repeatable).                                                                             |
 | `--hook-on-user-input <cmd>`    | Add an on-user-input hook command (repeatable).                                                                          |
 | `--hook-stop <cmd>`             | Add a stop hook command, fired when the model finishes responding (repeatable).                                          |
+| `--mcp-oauth-redirect-uri <url>` | Public HTTPS URL to advertise as the OAuth `redirect_uri` for MCP servers running in unmanaged OAuth mode. When set, docker-agent drives PKCE and the code exchange in-process instead of expecting the client to. See [Remote MCP](../remote-mcp/index.md) for details. |
 
 ## Agent References