docs: agent-first tutorial rewrite, human-in-the-loop, coordinator orchestration

Rewrite introduction as agent-first (not 3.x-centric); add @RequiresApproval tutorial with wire protocol and React example; expand coordinator with journal, handoffs, routing, eval, long-term memory, testing, LlmJudge; add @command confirm and console UI to agent docs

Author: jfarcand

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

@@ -109,6 +109,32 @@ public String deploy(
 
 Commands appear in the AI Console UI autocomplete and are also exposed via MCP as tools.
 
+### Destructive Command Confirmation
+
+For commands that perform destructive actions, use the `confirm` attribute to require user confirmation before execution:
+
+```java
+@Command(value = "/reset", description = "Reset all data",
+         confirm = "This will delete all data. Are you sure?")
+public String reset() {
+    return dataService.resetAll();
+}
+```
+
+The client receives a confirmation prompt before the command executes.
+
+## Built-in Console UI
+
+Every full-stack `@Agent` is automatically served by the **Atmosphere AI Console** at `/atmosphere/console/`. The console provides:
+
+- Chat interface with streaming responses
+- Tool call visualization in the **AGENT COLLABORATION** panel
+- Approval prompts for `@RequiresApproval` tools
+- Command autocomplete
+- Connection status indicator
+
+No frontend code needed — the console is bundled in `atmosphere-spring-boot-starter`.
+
 ## Tools
 
 `@AiTool` methods are callable by the LLM during inference. They work identically across all backends (built-in, Spring AI, LangChain4j, Google ADK, Embabel).

docs/src/content/docs/agents/coordinator.md

@@ -343,6 +343,120 @@ The same `@Coordinator` code works with any AI runtime. Switch the execution eng
 <artifactId>atmosphere-adk</artifactId>
 ```
 
+## Coordination Journal
+
+Every coordination is automatically journaled — which agents were called, what they returned, timing, success/failure. The journal is a pluggable SPI (`CoordinationJournal`) with an in-memory default, discovered via `ServiceLoader`.
+
+```java
+// After parallel execution, query the journal
+var events = fleet.journal().retrieve(coordinationId);
+var failed = fleet.journal().query(CoordinationQuery.forAgent("weather"));
+```
+
+Event types: `Started`, `Dispatched`, `Completed`, `Failed`, `Evaluated`. Each event includes the agent name, skill/method called, timestamp, duration, and result summary.
+
+## Agent Handoffs
+
+An agent can transfer the conversation — with full history — to another agent. One method call:
+
+```java
+@Prompt
+public void onPrompt(String message, StreamingSession session) {
+    if (message.toLowerCase().contains("billing")) {
+        session.handoff("billing", message);  // conversation history travels with it
+        return;
+    }
+    session.stream(message);
+}
+```
+
+The client receives an `AiEvent.Handoff` event before the target agent responds. Nested handoffs are blocked (cycle guard). The target agent's `@Prompt` method runs with its own tools, system prompt, and interceptor chain.
+
+## Conditional Routing
+
+Route based on agent results — first match wins, with an optional fallback:
+
+```java
+var weather = fleet.agent("weather").call("forecast", Map.of("city", city));
+
+var result = fleet.route(weather, route -> route
+    .when(r -> r.success() && r.text().contains("sunny"),
+          f -> f.agent("outdoor").call("plan", Map.of()))
+    .when(r -> r.success(),
+          f -> f.agent("indoor").call("suggest", Map.of()))
+    .otherwise(f -> AgentResult.failure("router", "route",
+          "Weather unavailable", Duration.ZERO))
+);
+```
+
+Every routing decision is recorded in the `CoordinationJournal`.
+
+## Result Evaluation
+
+Plug in quality assessment via the `ResultEvaluator` SPI. Evaluators run automatically (async, non-blocking, recorded in journal) after each agent call, and can be invoked explicitly:
+
+```java
+var result = fleet.agent("writer").call("draft", Map.of("topic", "AI"));
+var evals = fleet.evaluate(result, call);
+if (evals.stream().allMatch(Evaluation::passed)) {
+    session.stream(result.text());
+}
+```
+
+## Long-Term Memory
+
+Agents remember users across sessions. Configuration-only — no code changes in `@Agent` classes:
+
+```java
+// LongTermMemoryInterceptor (pre): injects stored facts into system prompt
+// LongTermMemoryInterceptor (post): extracts new facts via LLM
+
+// Extraction strategies:
+MemoryExtractionStrategy.onSessionClose()  // default — batch, cost-efficient
+MemoryExtractionStrategy.perMessage()       // real-time, expensive
+MemoryExtractionStrategy.periodic(5)        // every 5 messages
+```
+
+Backed by `InMemoryLongTermMemory` (dev) or any `SessionStore` implementation (Redis, SQLite). The `onDisconnect` lifecycle hook ensures facts are extracted before conversation history is cleared.
+
+## Testing
+
+The coordinator module includes test stubs for exercising `@Prompt` methods without infrastructure or LLM calls:
+
+```java
+var fleet = StubAgentFleet.builder()
+    .agent("weather", "Sunny, 72F in Madrid")
+    .agent("activities", "Visit Retiro Park, Prado Museum")
+    .build();
+
+coordinator.onPrompt("What to do in Madrid?", fleet, session);
+
+CoordinatorAssertions.assertThat(result)
+    .succeeded()
+    .containsText("Madrid")
+    .completedWithin(Duration.ofSeconds(5));
+```
+
+`StubAgentFleet` returns canned responses. `StubAgentTransport` allows predicate-based routing for more complex scenarios.
+
+## Eval Assertions
+
+LLM-as-judge for testing agent response quality. Uses any `AgentRuntime` as the judge model:
+
+```java
+var judge = new LlmJudge(cheapRuntime, "gpt-4o-mini");
+var response = client.prompt("Should I bring an umbrella to Tokyo?");
+
+assertThat(response)
+    .withJudge(judge)
+    .forPrompt("Should I bring an umbrella to Tokyo?")
+    .meetsIntent("Recommends whether to bring an umbrella based on weather data")
+    .isGroundedIn("get_weather")
+    .hasQuality(q -> q.relevance(0.8).coherence(0.7).safety(0.9));
+```
+
+See [AI Testing](/docs/reference/testing/) for the full assertion API.
+
 ## Console UI
 
 The built-in AI Console renders coordinator activity as **tool cards** — showing each specialist agent's work (tool name, input, result) before displaying the synthesized response. This gives users visibility into the multi-agent orchestration process.

docs/src/content/docs/architecture.md

@@ -0,0 +1,141 @@
+---
+title: Architecture
+description: How Atmosphere's transport and application layers compose
+sidebar:
+  order: 2
+---
+
+Atmosphere has two layers. The **transport layer** moves bytes between server and clients. The **application layer** gives those bytes meaning — AI events, tool calls, conversation memory. Understanding how they compose is key to using the framework effectively.
+
+## The Two Layers
+
+```
+Application layer     StreamingSession, AiEvent, AgentFleet, JournalFormat
+                           |
+                           | emit(), stream(), complete()
+                           |
+                           v
+Transport layer       Broadcaster, AtmosphereResource, BroadcastFilter
+                           |
+                           | broadcast(), suspend(), write()
+                           |
+                           v
+Wire protocols        WebSocket, SSE, Long-Polling, gRPC
+```
+
+## Broadcaster (Transport)
+
+A **Broadcaster** is a named pub/sub channel. Resources subscribe to it. When you call `broadcaster.broadcast(message)`, every subscribed resource receives it.
+
+```java
+@ManagedService(path = "/chat/{room}")
+public class Chat {
+
+    @Message
+    public String onMessage(String message) {
+        return message;  // broadcast to all in room
+    }
+}
+```
+
+Key properties:
+- **1:N** — one message fans out to all subscribers
+- **Untyped** — `broadcast(Object)` accepts anything
+- **Long-lived** — persists across connections, survives reconnects
+- **Transport-aware** — BroadcastFilters, BroadcasterCache, clustering (Redis, Kafka)
+
+## StreamingSession (Application)
+
+A **StreamingSession** represents one client's AI conversation. It produces typed events that flow through the Broadcaster to the client.
+
+```java
+@AiEndpoint(path = "/ai/chat")
+public class MyBot {
+
+    @Prompt
+    public void onPrompt(String message, StreamingSession session) {
+        session.emit(new AiEvent.ToolStart("search", Map.of("q", message)));
+        session.emit(new AiEvent.ToolResult("search", results));
+        session.stream(message);   // invoke LLM, stream response tokens
+    }
+}
+```
+
+Key properties:
+- **1:1** — one session serves one client's conversation
+- **Typed** — `emit(AiEvent)` produces structured events (tool cards, progress, errors)
+- **Short-lived** — created per prompt, closed on completion
+- **Application-aware** — conversation memory, LLM runtime, tools, guardrails, metrics
+
+## How They Compose
+
+`StreamingSession` uses a `Broadcaster` internally. When you call `session.emit(event)`, the session serializes the event to JSON and calls `broadcaster.broadcast(new RawMessage(json))`. The Broadcaster delivers it through its filter chain to the client.
+
+```
+session.emit(new AiEvent.ToolStart(...))
+    |
+    v
+DefaultStreamingSession serializes to JSON
+    |
+    v
+broadcaster.broadcast(new RawMessage(json))
+    |
+    v
+BroadcastFilter chain (PII redaction, cost metering, content safety)
+    |
+    v
+AtmosphereResource.write() -> WebSocket frame / SSE event / HTTP chunk
+```
+
+This separation is why **AI filters work**. `PiiRedactionFilter` and `CostMeteringFilter` sit on the Broadcaster's filter chain but understand AI event types. They intercept between "session emits event" and "client receives bytes" — a hook point that only exists because the layers are separate.
+
+## API Comparison
+
+| | `Broadcaster` | `StreamingSession` |
+|---|---|---|
+| Verb | `broadcast()` | `emit()`, `stream()`, `send()` |
+| Cardinality | 1:N (topic to subscribers) | 1:1 (conversation to client) |
+| Lifetime | Long-lived (across connections) | Per-prompt |
+| Type safety | `Object` | `AiEvent` hierarchy |
+| State | Resources, filters, cache | Memory, runtime, tools, guardrails |
+| Processing hooks | `BroadcastFilter` chain | `AiInterceptor` chain |
+
+## When to Use Which
+
+**Use `Broadcaster` directly** when you're building classic real-time features: chat rooms, dashboards, notifications, collaboration. You're working with raw messages and fan-out.
+
+**Use `StreamingSession`** when you're building AI features: chatbots, agents, tool-calling, multi-agent orchestration. You're working with typed events and conversation state.
+
+**Use both** when you need AI features with custom transport behavior — for example, an AI chatbot in a room where other users see the bot's responses. The session emits events, the Broadcaster fans them out to the room.
+
+## AgentFleet (Orchestration)
+
+A third abstraction sits above `StreamingSession` for multi-agent coordinators:
+
+```
+AgentFleet              agent(), parallel(), pipeline(), journal()
+    |
+    v
+StreamingSession        emit(), stream(), complete()
+    |
+    v
+Broadcaster             broadcast() -> filters -> resources
+```
+
+The `AgentFleet` dispatches work to agents and collects results. It uses the `StreamingSession` to stream progress and results back to the client. The fleet's `CoordinationJournal` records every dispatch and completion for observability.
+
+```java
+@Coordinator(name = "ceo",
+        journalFormat = JournalFormat.Markdown.class)
+@Fleet({@AgentRef(type = ResearchAgent.class),
+        @AgentRef(type = WriterAgent.class)})
+public class CeoCoordinator {
+
+    @Prompt
+    public void onPrompt(String message, AgentFleet fleet, StreamingSession session) {
+        var research = fleet.agent("research").call("search", Map.of("q", message));
+        session.stream("Summarize: " + research.text());
+        // journal auto-emitted as a tool card via journalFormat
+    }
+}
+```