docs(site): make the docs site feel like part of Docker, and explain what Docker Agent is

docs/STYLE.md

@@ -0,0 +1,72 @@
+# Documentation style guide
+
+A short reference for writers and reviewers. Goal: keep voice, naming
+and examples consistent across every page on this site.
+
+## Product naming
+
+| Context | Use | Don't use |
+|---|---|---|
+| Prose, headings, marketing | **Docker Agent** (two words, both capitalised — the proper name of the product) | docker-agent, Docker-Agent, docker agent (in prose) |
+| The CLI command | `docker agent` (lower-case, two words, in monospace) | `docker-agent`, `Docker Agent run` |
+| The repository / module path | `docker/docker-agent` | docker/Docker-Agent |
+| Internal identifiers / package names | as defined in code (e.g. `cagent`) — never invent new spellings in prose | mixing internal identifiers into user-facing copy |
+
+A simple rule of thumb:
+- **Talking about the product?** → "Docker Agent"
+- **Showing a command the user types?** → `docker agent run agent.yaml`
+
+## Voice
+
+- Address the reader as **you**, not "we" or "the user".
+- Prefer present tense and active voice ("the agent reads files",
+  not "files will be read by the agent").
+- Keep sentences short. Two short sentences usually beat one compound
+  one.
+- Avoid "simply", "just", "easily" — they're rarely accurate and
+  often condescending.
+
+## Code samples
+
+- All shell prompts use `$ ` (dollar + space) and the command on the
+  same line. Output, when shown, has no prompt.
+- YAML/HCL examples should be runnable as-is when reasonable, or end
+  in `# ...` to make truncation explicit.
+- The canonical example agent uses `model: anthropic/claude-sonnet-4-5`.
+  Use a different model only when the example is *about* that model.
+- File names in prose are in `monospace` (`agent.yaml`, not "agent.yaml").
+
+## Callouts
+
+Use the existing pattern; the new visual style does the rest:
+
+```markdown
+<div class="callout callout-tip" markdown="1">
+<div class="callout-title">When to use it</div>
+  <p>Body text.</p>
+</div>
+```
+
+- `callout-info` — neutral context
+- `callout-tip` — positive, "consider this"
+- `callout-warning` — caution, breaking, security
+
+Don't prefix the title with an emoji — the icon badge already provides
+one.
+
+## Glossary one-liners
+
+When a page first introduces a term, link to its concept page or use
+one of these standard one-liners:
+
+- **Agent** — an LLM with instructions, tools, and (optionally)
+  sub-agents, defined in YAML or HCL.
+- **Toolset** — a group of related tools the agent can call (e.g.
+  `filesystem`, `shell`, `mcp`).
+- **MCP** — Model Context Protocol, an open standard for tool servers.
+- **A2A** — Agent-to-Agent protocol, used to talk to other agents
+  over HTTP.
+- **TUI** — Terminal User Interface, the default interactive front end
+  Docker Agent ships with.
+- **OCI** — Open Container Initiative; the same registry format used
+  for Docker images. Docker Agent reuses it for sharing agents.

docs/_config.yml

@@ -1,5 +1,6 @@
 title: Docker Agent
-description: Build, run, and share powerful AI agents with a declarative YAML config, rich tool ecosystem, and multi-agent orchestration — by Docker.
+tagline: Run AI agents like containers.
+description: Run AI agents from a YAML file. Define them once, share them through any OCI registry, and run them anywhere — by Docker.
 url: "https://docker.github.io"
 baseurl: "/docker-agent"
 
@@ -25,6 +26,7 @@ relative_links:
 exclude:
   - DEVELOPMENT.md
   - TODO.md
+  - STYLE.md
   - recordings/
   - Gemfile
   - Gemfile.lock

docs/_includes/docker-bar.html

@@ -0,0 +1,17 @@
+<!-- Docker corporate top bar — appears above the product header on every
+     page, mirroring the docs.docker.com / docker.com structure. -->
+<div class="docker-bar" role="navigation" aria-label="Docker corporate links">
+  <div class="docker-bar-inner">
+    <a class="docker-bar-brand" href="https://www.docker.com" target="_blank" rel="noopener">
+      <img src="{{ '/assets/docker-mark.svg' | relative_url }}" alt="" width="22" height="18">
+      <span>Docker</span>
+    </a>
+    <nav class="docker-bar-links">
+      <a href="https://www.docker.com/products/docker-desktop/" target="_blank" rel="noopener">Desktop</a>
+      <a href="https://hub.docker.com" target="_blank" rel="noopener">Hub</a>
+      <a href="https://docs.docker.com" target="_blank" rel="noopener">Docs</a>
+      <a href="https://www.docker.com/products/docker-scout/" target="_blank" rel="noopener">Scout</a>
+      <a href="https://www.docker.com/blog/" target="_blank" rel="noopener">Blog</a>
+    </nav>
+  </div>
+</div>

docs/_includes/footer.html

@@ -0,0 +1,45 @@
+<footer class="site-footer" role="contentinfo">
+  <div class="site-footer-inner">
+    <div class="site-footer-brand">
+      <img src="{{ '/assets/docker-mark.svg' | relative_url }}" alt="" width="28" height="22">
+      <div>
+        <div class="site-footer-product">Docker Agent</div>
+        <div class="site-footer-tagline">Run AI agents like containers.</div>
+      </div>
+    </div>
+
+    <div class="site-footer-cols">
+      <div class="site-footer-col">
+        <h4>Product</h4>
+        <ul>
+          <li><a href="https://www.docker.com/products/docker-desktop/" target="_blank" rel="noopener">Docker Desktop</a></li>
+          <li><a href="https://hub.docker.com" target="_blank" rel="noopener">Docker Hub</a></li>
+          <li><a href="https://www.docker.com/products/docker-scout/" target="_blank" rel="noopener">Docker Scout</a></li>
+          <li><a href="https://www.docker.com/products/build-cloud/" target="_blank" rel="noopener">Build Cloud</a></li>
+        </ul>
+      </div>
+      <div class="site-footer-col">
+        <h4>Resources</h4>
+        <ul>
+          <li><a href="https://docs.docker.com" target="_blank" rel="noopener">Docker Docs</a></li>
+          <li><a href="https://github.com/docker/docker-agent" target="_blank" rel="noopener">GitHub</a></li>
+          <li><a href="https://hub.docker.com/u/agentcatalog" target="_blank" rel="noopener">Agent Catalog</a></li>
+          <li><a href="https://www.docker.com/blog/" target="_blank" rel="noopener">Blog</a></li>
+        </ul>
+      </div>
+      <div class="site-footer-col">
+        <h4>Company</h4>
+        <ul>
+          <li><a href="https://www.docker.com/company/" target="_blank" rel="noopener">About</a></li>
+          <li><a href="https://status.docker.com" target="_blank" rel="noopener">Status</a></li>
+          <li><a href="https://www.docker.com/legal/docker-terms-service/" target="_blank" rel="noopener">Terms</a></li>
+          <li><a href="https://www.docker.com/legal/docker-privacy-policy/" target="_blank" rel="noopener">Privacy</a></li>
+        </ul>
+      </div>
+    </div>
+  </div>
+  <div class="site-footer-bottom">
+    <span>&copy; {{ site.time | date: '%Y' }} Docker Inc. All rights reserved.</span>
+    <span>Docker Agent is open source under the <a href="https://github.com/docker/docker-agent/blob/main/LICENSE" target="_blank" rel="noopener">Apache 2.0 license</a>.</span>
+  </div>
+</footer>

docs/_includes/header.html

@@ -2,13 +2,9 @@
 <header class="header" role="banner">
   <div class="header-inner">
     <a href="{{ '/' | relative_url }}" class="header-logo" aria-label="Docker Agent docs home">
-      <!-- Docker whale logo -->
-      <svg viewBox="0 0 50 36" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
-        <path d="M48.3 16.5c-.3-.2-2.6-1.3-5.1-1.3-.5 0-1 0-1.5.1-.6-2.2-2.6-3.2-2.7-3.3l-.5-.3-.3.5c-.4.8-.7 1.7-.8 2.6-.3 1.8.1 3.5 1.2 4.9-1.8 1-4.7 1.3-5.3 1.3H1.2c-.7 0-1.2.5-1.2 1.2 0 4.4 1.8 8.8 5.2 12C8.5 37.2 13.2 39 19 39c12.5 0 21.7-7.3 26-20.4 1.7 0 3.3-.5 4.1-2.1l.2-.4-.3-.2zM5.3 19.8H9c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3H5.3c-.2 0-.3.1-.3.3v3.8c0 .1.1.3.3.3zm5 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .1.1.3.3.3zm5.1 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .1.1.3.3.3zm5.1 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .1.1.3.3.3zm-10.2-5h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3zm5.1 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3zm5.1 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3zm0-5h3.8c.2 0 .3-.1.3-.3V5.7c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3zm5.1 5h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3z" fill="#1D63ED"/>
-      </svg>
-      <span>Docker Agent</span>
-      <span class="logo-divider"></span>
-      <span class="logo-label">Docs</span>
+      <img class="docker-mark" src="{{ '/assets/docker-mark.svg' | relative_url }}" alt="" width="32" height="26">
+      <span class="product-name">Docker Agent</span>
+      <span class="product-badge">Docs</span>
     </a>
 
     <div class="header-actions">

docs/_layouts/default.html

@@ -3,27 +3,31 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>{% if page.title %}{{ page.title }} – Docker Agent Docs{% else %}Docker Agent – Documentation{% endif %}</title>
+  <title>{% if page.title and page.url != '/' %}{{ page.title }} – Docker Agent Docs{% else %}Docker Agent — Run AI agents from YAML, like containers{% endif %}</title>
   <meta name="description" content="{{ page.description | default: site.description }}">
 
-  <meta property="og:title" content="{% if page.title %}{{ page.title }} – Docker Agent Docs{% else %}Docker Agent – Documentation{% endif %}">
+  <meta property="og:title" content="{% if page.title and page.url != '/' %}{{ page.title }} – Docker Agent Docs{% else %}Docker Agent — Run AI agents from YAML, like containers{% endif %}">
   <meta property="og:description" content="{{ page.description | default: site.description }}">
   <meta property="og:type" content="{% if page.url == '/' %}website{% else %}article{% endif %}">
   <meta property="og:url" content="{{ page.url | absolute_url }}">
+  <meta property="og:site_name" content="Docker Agent Docs">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:site" content="@docker">
 
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+  <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700;900&family=Roboto+Mono:wght@400;500&display=swap" rel="stylesheet">
   <link rel="stylesheet" href="{{ '/css/style.css' | relative_url }}">
-  <!-- Docker whale favicon -->
-  <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 50 36' fill='none'%3E%3Cpath d='M48.3 16.5c-.3-.2-2.6-1.3-5.1-1.3-.5 0-1 0-1.5.1-.6-2.2-2.6-3.2-2.7-3.3l-.5-.3-.3.5c-.4.8-.7 1.7-.8 2.6-.3 1.8.1 3.5 1.2 4.9-1.8 1-4.7 1.3-5.3 1.3H1.2c-.7 0-1.2.5-1.2 1.2 0 4.4 1.8 8.8 5.2 12C8.5 37.2 13.2 39 19 39c12.5 0 21.7-7.3 26-20.4 1.7 0 3.3-.5 4.1-2.1l.2-.4-.3-.2zM5.3 19.8H9c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3H5.3c-.2 0-.3.1-.3.3v3.8c0 .1.1.3.3.3zm5 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .1.1.3.3.3zm5.1 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .1.1.3.3.3zm5.1 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .1.1.3.3.3zm-10.2-5h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3zm5.1 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3zm5.1 0h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3zm0-5h3.8c.2 0 .3-.1.3-.3V5.7c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3zm5.1 5h3.8c.2 0 .3-.1.3-.3v-3.8c0-.2-.1-.3-.3-.3h-3.8c-.2 0-.3.1-.3.3v3.8c0 .2.1.3.3.3z' fill='%231D63ED'/%3E%3C/svg%3E">
+  <link rel="icon" type="image/svg+xml" href="{{ '/assets/docker-mark.svg' | relative_url }}">
 </head>
 <body>
   <a href="#page-content" class="skip-link">Skip to content</a>
 
+  {% include docker-bar.html %}
   {% include header.html %}
 
   <nav class="sidebar" id="sidebar" role="navigation" aria-label="Documentation navigation">
+    <div class="sidebar-tagline">{{ site.tagline | default: 'Run AI agents like containers.' }}</div>
     {% for group in site.data.nav %}
     <div class="sidebar-section">
       <div class="sidebar-heading">{{ group.section }}</div>
@@ -38,13 +42,15 @@
     <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="18" x2="21" y2="18"/></svg>
   </button>
 
-  <main class="main" role="main">
+  <main class="main" id="main-content" role="main">
     <div class="content" id="page-content">
       {{ content }}
       {% unless page.url == '/' %}{% include page-nav.html %}{% endunless %}
     </div>
   </main>
 
+  {% include footer.html %}
+
   <div class="search-overlay" id="search-overlay" role="dialog" aria-label="Search documentation" aria-modal="true">
     <div class="search-modal">
       <input type="text" id="search-modal-input" placeholder="Search documentation…" aria-label="Search query">