docs: add @coordinator, AI testing, migrate AiSupport → AgentRuntime

- Add @coordinator documentation (agents/coordinator.md): @fleet,
  @AgentRef, AgentFleet API, parallel fan-out, sequential pipelines,
  optional agents, weighted routing, local vs remote transport
- Add AI Testing reference (reference/testing.md): AiTestClient,
  AiResponse, AiAssertions fluent API for JUnit 5
- Migrate AiSupport → AgentRuntime across all docs (reference/ai,
  tutorial/11-ai-adapters, tutorial/12-ai-filters, all integration pages)
- Fix @agent annotation attributes: value→name, skills→skillFile,
  remove nonexistent memory attr, add endpoint attribute
- Update splash page and welcome to balance real-time core and AI stories
- Add @coordinator and AI Testing to sidebar navigation
- Update What's New with multi-agent orchestration and AgentRuntime SPI

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jfarcand

docs/astro.config.mjs

@@ -7,7 +7,7 @@ export default defineConfig({
   integrations: [
     starlight({
       title: 'Atmosphere',
-      description: 'The Java framework for WebSocket, SSE, and AI streaming',
+      description: 'Real-time for the JVM — WebSocket, SSE, gRPC, rooms, presence, AI streaming, and multi-agent orchestration',
       logo: {
         src: './src/assets/logo.svg',
         replacesTitle: false,
@@ -34,6 +34,7 @@ export default defineConfig({
           label: 'Agents',
           items: [
             { label: '@Agent', slug: 'agents/agent' },
+            { label: '@Coordinator', slug: 'agents/coordinator' },
             { label: 'Skills', slug: 'agents/skills' },
             { label: 'A2A Protocol', slug: 'agents/a2a' },
             { label: 'AG-UI Protocol', slug: 'agents/agui' },
@@ -103,6 +104,7 @@ export default defineConfig({
             { label: 'Core Runtime', slug: 'reference/core' },
             { label: 'Rooms & Presence', slug: 'reference/rooms' },
             { label: 'AI / LLM', slug: 'reference/ai' },
+            { label: 'AI Testing', slug: 'reference/testing' },
             { label: 'MCP Server', slug: 'reference/mcp' },
             { label: 'gRPC Transport', slug: 'reference/grpc' },
             { label: 'Kotlin DSL', slug: 'reference/kotlin' },

docs/src/content/docs/agents/a2a.md

@@ -30,7 +30,7 @@ A2A (Agent-to-Agent) is Google's open protocol for agent interoperability. Atmos
 Declares a skill that this agent exposes to other agents. Applied at the class level alongside `@Agent` or `@ManagedService`.
 
 ```java
-@Agent(value = "/translator", headless = true)
+@Agent(name = "translator", headless = true)
 @AgentSkill(
     name = "translate",
     description = "Translates text between languages",
@@ -104,7 +104,7 @@ A2A uses JSON-RPC 2.0 over HTTP. Atmosphere handles serialization, error mapping
 A2A is designed for agent-to-agent communication. Agents that only serve other agents should use `headless = true`:
 
 ```java
-@Agent(value = "/data-enrichment", headless = true)
+@Agent(name = "data-enrichment", headless = true)
 @AgentSkill(name = "enrich", description = "Enriches records with external data")
 public class DataEnrichmentAgent {
 

docs/src/content/docs/agents/agent.md

@@ -25,9 +25,9 @@ description: "The @Agent annotation — wiring AI endpoints, commands, tools, sk
 
 ```java
 @Agent(
-    value = "/my-agent",
-    skills = "classpath:skills/my-agent.skills",
-    memory = true
+    name = "my-agent",
+    skillFile = "skills/my-agent.md",
+    description = "A helpful assistant"
 )
 public class MyAgent {
 
@@ -43,15 +43,26 @@ public class MyAgent {
 }
 ```
 
+## Annotation Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `String` | _(required)_ | Agent name. Used in the registration path (`/atmosphere/agent/{name}`) and in protocol metadata (A2A Agent Card). |
+| `skillFile` | `String` | `""` | Classpath resource path to the skill file (`.md`). The entire file becomes the system prompt. Sections are also extracted for protocol metadata. |
+| `description` | `String` | `""` | Human-readable description for A2A Agent Card metadata. |
+| `endpoint` | `String` | `""` | Custom endpoint path for the agent's A2A protocol endpoint. Overrides the default `/atmosphere/agent/{name}/a2a`. |
+| `version` | `String` | `"1.0.0"` | Agent version for Agent Card metadata and protocol responses. |
+| `headless` | `boolean` | `false` | When `true`, no WebSocket UI handler is registered — agent operates as a headless A2A/MCP service only. |
+
 ## What `@Agent` Wires
 
 | Concern | How it works |
 |---------|-------------|
-| **AI endpoint** | Registers an HTTP/WebSocket endpoint at the path you specify |
+| **AI endpoint** | Registers an HTTP/WebSocket endpoint at `/atmosphere/agent/{name}` |
 | **Commands** | Methods annotated with `@Command` become slash commands with type-safe parameters |
 | **Tools** | Methods annotated with `@AiTool` are registered as portable tools, callable by any LLM backend |
-| **Skill file** | Loaded from the path in `skills`, or auto-discovered at `META-INF/skills/` on the classpath |
-| **Conversation memory** | When `memory = true`, session-scoped conversation history is maintained automatically |
+| **Skill file** | Loaded from the `skillFile` path, or auto-discovered at `META-INF/skills/` by convention |
+| **Conversation memory** | Session-scoped conversation history is enabled by default |
 | **Protocol exposure** | MCP, A2A, and AG-UI protocols are auto-registered based on classpath dependencies |
 
 ## Full-Stack vs Headless Mode
@@ -61,12 +72,27 @@ By default, `@Agent` runs in **full-stack mode** — it serves a built-in AI Con
 Set `headless = true` to run in **headless mode** — no UI is served. The agent is only reachable via its protocol endpoints (MCP, A2A, AG-UI) or programmatic API. This is the right mode for agent-to-agent communication.
 
 ```java
-@Agent(value = "/background-worker", headless = true)
+@Agent(name = "background-worker", headless = true)
 public class BackgroundWorker {
     // reachable via A2A, MCP, or direct API — no browser UI
 }
 ```
 
+Headless mode is also **auto-detected**: if the class has `@AgentSkill`/`@AgentSkillHandler` methods but no `@Prompt` method, it is treated as headless.
+
+### Custom Endpoint
+
+Use the `endpoint` attribute to set a custom A2A path for headless agents:
+
+```java
+@Agent(name = "research",
+       endpoint = "/atmosphere/a2a/research",
+       description = "Web research agent")
+public class ResearchAgent {
+    // A2A endpoint served at /atmosphere/a2a/research
+}
+```
+
 ## Commands
 
 `@Command` methods are user-facing slash commands. Parameters are declared with `@Param` and are type-safe.
@@ -97,14 +123,42 @@ public List<Order> queryOrders(
 }
 ```
 
-Tools are automatically registered with the active LLM backend and are also exposed as MCP tools when the MCP module is on the classpath.
+Tools are automatically registered with the active `AgentRuntime` and are also exposed as MCP tools when the MCP module is on the classpath.
+
+## Skill File
+
+The `skillFile` attribute points to a Markdown file on the classpath that serves as the agent's system prompt. Sections within the file are also extracted for protocol metadata:
+
+- `## Skills` — A2A Agent Card skills
+- `## Tools` — cross-referenced with `@AiTool` methods
+- `## Channels` — included in system prompt
+- `## Guardrails` — included in system prompt (LLM self-enforces)
+
+```java
+@Agent(name = "devops", skillFile = "prompts/devops-skill.md")
+public class DevOpsAgent { ... }
+```
+
+If no `skillFile` is specified, Atmosphere matches by convention — an agent named `devops` will pick up `META-INF/skills/devops.skills` if present.
 
 ## Conversation Memory
 
-When `memory = true`, Atmosphere maintains a session-scoped conversation history. The history is passed to the LLM on every request, giving the agent context about previous exchanges.
+Conversation memory is enabled by default. Atmosphere maintains a session-scoped conversation history — the history is passed to the LLM on every request, giving the agent context about previous exchanges.
 
-Memory is stored in-memory by default. For durable persistence, configure a `MemoryStore` implementation.
+Memory is stored in-memory by default. For durable persistence across restarts, add `atmosphere-durable-sessions-sqlite` or `atmosphere-durable-sessions-redis` to the classpath and a `ConversationPersistence` backend is auto-discovered via `ServiceLoader`.
 
 ## Relationship to `@ManagedService`
 
 `@Agent` builds on top of `@ManagedService`. An `@Agent` is a `@ManagedService` with AI-specific wiring added. You can still use `@ManagedService` directly for non-AI real-time endpoints (chat rooms, presence, pub/sub). Protocol annotations (`@McpTool`, `@AgentSkill`, `@AgUiEndpoint`) work on both.
+
+## Relationship to `@Coordinator`
+
+For multi-agent orchestration, use [`@Coordinator`](/docs/agents/coordinator/) instead. A coordinator subsumes `@Agent` — it adds fleet management on top of the base agent setup. See the [@Coordinator documentation](/docs/agents/coordinator/) for details.
+
+## See Also
+
+- [@Coordinator](/docs/agents/coordinator/) — multi-agent orchestration
+- [Skills](/docs/agents/skills/) — skill files and auto-discovery
+- [A2A Protocol](/docs/agents/a2a/) — agent-to-agent communication
+- [AG-UI Protocol](/docs/agents/agui/) — structured agent events for frontends
+- [@AiTool](/docs/tutorial/10-ai-tools/) — framework-agnostic tool calling