Merge pull request #3698 from docker/docs/p2-polish

docs: add tour pointer, prompt-files subsection, and product-naming consistency

Author: aheritier

docs/community/contributing/index.md

@@ -1,12 +1,12 @@
 ---
 title: "Contributing"
-description: "docker-agent is open source. Here's how to set up your development environment and contribute."
+description: "Docker Agent is open source. Here's how to set up your development environment and contribute."
 keywords: docker agent, ai agents, community, contributing
 weight: 10
 canonical: https://docs.docker.com/ai/docker-agent/community/contributing/
 ---
 
-_docker-agent is open source. Here's how to set up your development environment and contribute._
+_Docker Agent is open source. Here's how to set up your development environment and contribute._
 
 ## Development Setup
 
@@ -52,14 +52,14 @@ export ANTHROPIC_API_KEY=your_key_here
 
 ## Dogfooding
 
-Use docker-agent to work on docker-agent! The project includes a specialized developer agent:
+Use Docker Agent to work on Docker Agent! The project includes a specialized developer agent:
 
 ```bash
 cd docker-agent
 docker agent run ./golang_developer.yaml
 ```
 
-This agent is an expert Go developer that understands the docker-agent codebase. Ask it questions, request fixes, or have it implement features.
+This agent is an expert Go developer that understands the Docker Agent codebase. Ask it questions, request fixes, or have it implement features.
 
 ## Core Concepts
 
@@ -121,7 +121,7 @@ Find us on [Slack](https://dockercommunity.slack.com/archives/C09DASHHRU4) for q
 
 ## Code of Conduct
 
-We want to keep the docker-agent community welcoming, inclusive, and collaborative. Key guidelines:
+We want to keep the Docker Agent community welcoming, inclusive, and collaborative. Key guidelines:
 
 - **Be nice** — Be courteous, respectful, and polite. No abuse of any kind will be tolerated.
 - **Encourage diversity** — Make everyone feel welcome regardless of background.

docs/community/opentelemetry/index.md

@@ -1,14 +1,14 @@
 ---
 title: "OpenTelemetry Tracing"
-description: "Export docker-agent traces to any OTLP backend, including Langfuse and LangSmith, for debugging agentic workflows."
+description: "Export Docker Agent traces to any OTLP backend, including Langfuse and LangSmith, for debugging agentic workflows."
 keywords: docker agent, ai agents, community, opentelemetry tracing
 weight: 40
 canonical: https://docs.docker.com/ai/docker-agent/community/opentelemetry/
 ---
 
-_docker-agent can export OpenTelemetry traces of an agent run to any OTLP/HTTP backend. This is separate from [product-analytics telemetry](../telemetry/index.md) and is opt-in via the `--otel` flag._
+_Docker Agent can export OpenTelemetry traces of an agent run to any OTLP/HTTP backend. This is separate from [product-analytics telemetry](../telemetry/index.md) and is opt-in via the `--otel` flag._
 
-When enabled, docker-agent emits OpenTelemetry GenAI (`gen_ai.*`) and MCP (`mcp.*`) spans following the [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). Spans cover the agent turn, model calls (with token usage and cost attributes), tool calls, MCP client/server activity, sub-agent hand-offs, and provider fallbacks. W3C `traceparent` context is propagated so the whole run renders as a single connected trace tree.
+When enabled, Docker Agent emits OpenTelemetry GenAI (`gen_ai.*`) and MCP (`mcp.*`) spans following the [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). Spans cover the agent turn, model calls (with token usage and cost attributes), tool calls, MCP client/server activity, sub-agent hand-offs, and provider fallbacks. W3C `traceparent` context is propagated so the whole run renders as a single connected trace tree.
 
 ## Enabling
 
@@ -20,7 +20,7 @@ Without an exporter endpoint configured, spans are recorded locally as no-ops. T
 
 ## Configuration
 
-docker-agent reads the standard OTLP environment variables:
+Docker Agent reads the standard OTLP environment variables:
 
 | Variable | Purpose |
 | --- | --- |
@@ -32,7 +32,7 @@ docker-agent reads the standard OTLP environment variables:
 > [!NOTE]
 > **Base endpoint, not the full signal URL**
 >
-> Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the **base** endpoint (for example `https://cloud.langfuse.com/api/public/otel`). docker-agent appends `/v1/traces` for you, matching the value documented by Langfuse and LangSmith. A bare `host:port` is also accepted and gets `https://` (or `http://` for localhost).
+> Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the **base** endpoint (for example `https://cloud.langfuse.com/api/public/otel`). Docker Agent appends `/v1/traces` for you, matching the value documented by Langfuse and LangSmith. A bare `host:port` is also accepted and gets `https://` (or `http://` for localhost).
 
 > [!WARNING]
 > **Message content can contain sensitive data**
@@ -88,7 +88,7 @@ docker agent run agent.yaml --otel
 > [!NOTE]
 > **Langfuse and LangSmith ingest traces only**
 >
-> Both backends accept the traces signal only. docker-agent also wires metric and log exporters at the same endpoint, so their periodic exports return `404` against trace-only backends. This is harmless to traces but appears in the debug log. Point a full OTLP collector at the endpoint if you also want metrics and logs.
+> Both backends accept the traces signal only. Docker Agent also wires metric and log exporters at the same endpoint, so their periodic exports return `404` against trace-only backends. This is harmless to traces but appears in the debug log. Point a full OTLP collector at the endpoint if you also want metrics and logs.
 
 ## Inspecting traces locally
 

docs/community/telemetry/index.md

@@ -1,14 +1,14 @@
 ---
 title: "Telemetry"
-description: "docker-agent collects anonymous usage data to help improve the tool. Telemetry can be disabled at any time."
+description: "Docker Agent collects anonymous usage data to help improve the tool. Telemetry can be disabled at any time."
 keywords: docker agent, ai agents, community, telemetry
 weight: 30
 canonical: https://docs.docker.com/ai/docker-agent/community/telemetry/
 ---
 
-_docker-agent collects anonymous usage data to help improve the tool. Telemetry can be disabled at any time._
+_Docker Agent collects anonymous usage data to help improve the tool. Telemetry can be disabled at any time._
 
-On first startup, docker-agent displays a notice about telemetry collection so you're always informed. All events are processed synchronously when recorded.
+On first startup, Docker Agent displays a notice about telemetry collection so you're always informed. All events are processed synchronously when recorded.
 
 ## Disabling Telemetry
 

docs/community/troubleshooting/index.md

@@ -1,12 +1,12 @@
 ---
 title: "Troubleshooting"
-description: "Common issues and how to resolve them when working with docker-agent."
+description: "Common issues and how to resolve them when working with Docker Agent."
 keywords: docker agent, ai agents, community, troubleshooting
 weight: 20
 canonical: https://docs.docker.com/ai/docker-agent/community/troubleshooting/
 ---
 
-_Common issues and how to resolve them when working with docker-agent._
+_Common issues and how to resolve them when working with Docker Agent._
 
 ## Common Errors
 
@@ -29,7 +29,7 @@ The agent hit its `max_iterations` limit without completing the task.
 
 ### Model Fallback Triggered
 
-When the primary model fails, docker-agent automatically switches to fallback models. Look for log messages like `"Switching to fallback model"`.
+When the primary model fails, Docker Agent automatically switches to fallback models. Look for log messages like `"Switching to fallback model"`.
 
 - **429 errors:** Rate limited — the cooldown period keeps using the fallback
 - **5xx errors:** Server issues — retries with exponential backoff first, then falls back
@@ -49,7 +49,7 @@ agents:
 
 ## Missing credentials or model errors
 
-When docker-agent can't find a usable model at startup, it fails fast with an actionable error. The message names the exact next step. `docker agent doctor` is the fastest way to see the full picture — which providers have credentials, whether Docker Model Runner is reachable, and which model `auto` would pick.
+When Docker Agent can't find a usable model at startup, it fails fast with an actionable error. The message names the exact next step. `docker agent doctor` is the fastest way to see the full picture — which providers have credentials, whether Docker Model Runner is reachable, and which model `auto` would pick.
 
 ### Required environment variables not set
 
@@ -109,7 +109,7 @@ If instead you see `cannot query Docker Model Runner at <url>`, Docker Model Run
 
 ## Debug Mode
 
-The first step for any issue is enabling debug logging. This provides detailed information about what docker-agent is doing internally.
+The first step for any issue is enabling debug logging. This provides detailed information about what Docker Agent is doing internally.
 
 ```bash
 # Enable debug logging (writes to ~/.cagent/cagent.debug.log)
@@ -168,7 +168,7 @@ If the agent hangs or times out, check that you can reach the provider's API end
 
 - Ensure the MCP tool command is installed and on your `PATH`
 - Check file permissions — tools need to be executable
-- Test MCP tools independently before integrating with docker-agent
+- Test MCP tools independently before integrating with Docker Agent
 - For Docker-based MCP tools (`ref: docker:*`), ensure Docker Desktop is running
 
 ### Filesystem / shell tool errors
@@ -184,7 +184,7 @@ MCP and LSP toolsets are managed by a supervisor that auto-restarts them when th
 - `/tools` — the unified tools dialog. Its top section lists every toolset with its current state (`Stopped`, `Starting`, `Ready`, `Degraded`, `Restarting`, `Failed`), restart count, and last error; the bottom section lists every tool the agent can call. Start here whenever a tool seems missing or stuck.
 - `/toolset-restart <name>` — force a supervisor-driven reconnect of the named toolset. Useful after completing OAuth, when a remote MCP server has been redeployed, or when a language server like `gopls` is unresponsive.
 
-Remote MCP servers that return `401 invalid_token` (e.g. because the stored OAuth token was revoked or rotated) are now self-healing: docker-agent silently exchanges the refresh token for a new one when possible, or surfaces an OAuth re-authentication prompt on your next message when refresh is not possible. No more stuck toolsets that require a process restart — but if you want to trigger re-auth immediately, `/toolset-restart <name>` forces it right away.
+Remote MCP servers that return `401 invalid_token` (e.g. because the stored OAuth token was revoked or rotated) are now self-healing: Docker Agent silently exchanges the refresh token for a new one when possible, or surfaces an OAuth re-authentication prompt on your next message when refresh is not possible. No more stuck toolsets that require a process restart — but if you want to trigger re-auth immediately, `/toolset-restart <name>` forces it right away.
 
 MCP tools using stdio transport must complete the initialization handshake before becoming available. If tools fail silently:
 
@@ -196,15 +196,15 @@ MCP tools using stdio transport must complete the initialization handshake befor
 > [!NOTE]
 > **Startup tool-listing timeout**
 >
-> At startup, docker-agent queries each toolset for its tool list. If a toolset does not respond within 10 seconds (e.g. a wedged MCP stdio server that never answers `tools/list`), that toolset is skipped with a warning and the remaining toolsets load normally. The sidebar resolves showing whichever tools did load — no infinite spinner. Enable `--debug` to see the warning message, and use `/toolset-restart <name>` once the server becomes responsive.
+> At startup, Docker Agent queries each toolset for its tool list. If a toolset does not respond within 10 seconds (e.g. a wedged MCP stdio server that never answers `tools/list`), that toolset is skipped with a warning and the remaining toolsets load normally. The sidebar resolves showing whichever tools did load — no infinite spinner. Enable `--debug` to see the warning message, and use `/toolset-restart <name>` once the server becomes responsive.
 
 If a toolset keeps crashing in a tight loop, tune the [`lifecycle`](../../configuration/tools/index.md#toolset-lifecycle) block on the toolset (e.g. raise `backoff.initial`, lower `max_restarts`, or switch to the `best-effort` profile) so a flaky dependency does not amplify into a restart storm.
 
 ## Configuration Errors
 
 ### YAML syntax issues
 
-docker-agent validates config at startup and reports errors with line numbers. Common problems:
+Docker Agent validates config at startup and reports errors with line numbers. Common problems:
 
 - Incorrect indentation (YAML is whitespace-sensitive)
 - Missing quotes around values containing special characters (`:`, `#`, `{`, `}`)
@@ -231,7 +231,7 @@ docker-agent validates config at startup and reports errors with line numbers. C
 
 ### Port conflicts
 
-When running docker-agent as an API server or MCP server, ensure the port is not already in use:
+When running Docker Agent as an API server or MCP server, ensure the port is not already in use:
 
 ```bash
 # Check if port 8080 is in use

docs/concepts/agents/index.md

@@ -1,16 +1,16 @@
 ---
 title: "Agents"
-description: "Agents are the core building blocks of docker-agent. Each agent is an AI-powered entity with a model, instructions, tools, and optional sub-agents."
+description: "Agents are the core building blocks of Docker Agent. Each agent is an AI-powered entity with a model, instructions, tools, and optional sub-agents."
 keywords: docker agent, ai agents, concepts, agents
 weight: 10
 canonical: https://docs.docker.com/ai/docker-agent/concepts/agents/
 ---
 
-_Agents are the core building blocks of docker-agent. Each agent is an AI-powered entity with a model, instructions, tools, and optional sub-agents._
+_Agents are the core building blocks of Docker Agent. Each agent is an AI-powered entity with a model, instructions, tools, and optional sub-agents._
 
 ## What is an Agent?
 
-An agent in docker-agent is defined by:
+An agent in Docker Agent is defined by:
 
 - **Model** — The AI model powering it (e.g., Claude, GPT-5, Gemini). See [Models](../models/index.md).
 - **Description** — A brief summary of what the agent does (used by other agents for delegation)
@@ -34,7 +34,7 @@ agents:
 
 ## The Root Agent
 
-Every docker-agent configuration has a **root agent** — the entry point that receives user messages. In a single-agent setup, this is the only agent. In a multi-agent setup, the root agent acts as a coordinator, delegating tasks to specialized sub-agents.
+Every Docker Agent configuration has a **root agent** — the entry point that receives user messages. In a single-agent setup, this is the only agent. In a multi-agent setup, the root agent acts as a coordinator, delegating tasks to specialized sub-agents.
 
 > [!NOTE]
 > **Naming**

docs/concepts/distribution/index.md

@@ -12,7 +12,7 @@ _Package, share, and run agents via OCI-compatible registries — just like cont
 
 ## Overview
 
-docker-agent agents can be pushed to any OCI-compatible registry (Docker Hub, GitHub Container Registry, etc.) and pulled/run anywhere. This makes sharing agents as easy as sharing Docker images.
+Docker Agent agents can be pushed to any OCI-compatible registry (Docker Hub, GitHub Container Registry, etc.) and pulled/run anywhere. This makes sharing agents as easy as sharing Docker images.
 
 > [!TIP]
 > For CLI commands related to distribution, see [CLI Reference](../../features/cli/index.md) (`docker agent share push`, `docker agent share pull`, `docker agent alias`).
@@ -108,7 +108,7 @@ $ docker agent serve api docker.io/username/agent:latest --pull-interval 10
 
 ## Private Repositories
 
-docker-agent supports pulling from private GitHub repositories and registries that require authentication. Use standard Docker login or GitHub authentication:
+Docker Agent supports pulling from private GitHub repositories and registries that require authentication. Use standard Docker login or GitHub authentication:
 
 ```bash
 # Login to a registry
@@ -122,7 +122,7 @@ $ docker agent run docker.io/myorg/private-agent:latest
 > [!NOTE]
 > **Docker Desktop credentials**
 >
-> When pulling or running an agent from a `docker.com` or `*.docker.com` HTTPS URL (e.g. `desktop.docker.com`), docker-agent automatically forwards your Docker Desktop JWT for authentication — no explicit login required when Docker Desktop is running and signed in.
+> When pulling or running an agent from a `docker.com` or `*.docker.com` HTTPS URL (e.g. `desktop.docker.com`), Docker Agent automatically forwards your Docker Desktop JWT for authentication — no explicit login required when Docker Desktop is running and signed in.
 >
 > Note: `docker.io` (the standard Docker Hub registry domain) is a separate domain and is **not** covered by automatic JWT forwarding. Agents pulled from `docker.io` or `registry-1.docker.io` still require `docker login docker.io` for private repositories.
 

docs/concepts/models/index.md

@@ -1,12 +1,12 @@
 ---
 title: "Models"
-description: "Models are the AI brains behind your agents. docker-agent supports multiple providers and flexible configuration."
+description: "Models are the AI brains behind your agents. Docker Agent supports multiple providers and flexible configuration."
 keywords: docker agent, ai agents, concepts, models
 weight: 20
 canonical: https://docs.docker.com/ai/docker-agent/concepts/models/
 ---
 
-_Models are the AI brains behind your agents. docker-agent supports multiple providers and flexible configuration._
+_Models are the AI brains behind your agents. Docker Agent supports multiple providers and flexible configuration._
 
 ## Inline vs. Named Models
 
@@ -63,7 +63,7 @@ agents:
     instruction: You are a helpful assistant.
 ```
 
-At load time, docker-agent selects the first candidate whose credentials are
+At load time, Docker Agent selects the first candidate whose credentials are
 configured. You only need credentials for one candidate. See
 [Model Configuration](../../configuration/models/index.md#first-available-models)
 for details.
@@ -129,11 +129,11 @@ Control how much the model "thinks" before responding:
 | Anthropic  | int or str | 1024–32768 tokens, or `adaptive`, `adaptive/<effort>`, effort level | off                              |
 | Gemini 2.5 | int        | 0 (off), -1 (dynamic), or token count                               | -1 (dynamic)                     |
 | Gemini 3   | string     | `minimal`, `low`, `medium`, `high`                                  | varies                           |
-| All        | string/int | `none` or `0` clears docker-agent's local config                    | —                                |
+| All        | string/int | `none` or `0` clears Docker Agent's local config                    | —                                |
 
 `none` and `0` are not universal API-level disable switches. On genuine OpenAI
 gpt-5.6+ endpoints (Sol/Terra/Luna), `none` is a real `reasoning_effort` value
-that docker-agent sends as-is and the model does not reason. On older OpenAI
+that Docker Agent sends as-is and the model does not reason. On older OpenAI
 models, `none`/`0` only clear the local `thinking_budget` — omitting the field
 has the same effect — and the model falls back to the API's own default effort
 (still reasoning internally for always-reasoning models like the o-series).
@@ -162,7 +162,7 @@ models:
 
 ## Alloy Models
 
-"Alloy models" let you use more than one model in the same conversation — docker-agent alternates between them to leverage the strengths of each:
+"Alloy models" let you use more than one model in the same conversation — Docker Agent alternates between them to leverage the strengths of each:
 
 ```yaml
 agents: