docs+website: correct hallucinated claims from validation sweep

Author: jfarcand

docs/src/content/docs/agents/embeddings.md

@@ -179,14 +179,15 @@ Every concrete `EmbeddingRuntime` ships with a contract-test subclass of
 deterministic fake embedder so the bridge plumbing is validated without
 live network calls.
 
-The six parity assertions are:
+The seven parity assertions are:
 
 1. `runtimeHasStableName()` — `name()` returns a non-blank, stable identifier
 2. `embedSingleTextReturnsVectorOfExpectedDimension()` — single-text round-trip
 3. `embedAllReturnsVectorPerInputInOrder()` — batch round-trip preserves order
 4. `embedAllWithEmptyListReturnsEmptyList()` — edge case
 5. `runtimeIsAvailableAfterFakeInjection()` — availability gate flips on injection
 6. `dimensionsAccessorIsNonNegativeOrMinusOne()` — dimension advertising contract
+7. `runtimeDeclaresStablePriority()` — `priority()` returns a stable integer
 
 If you add a new `EmbeddingRuntime` implementation, subclass the base and
 supply a deterministic fake embedder via `installFakeEmbedder()` — no

docs/src/content/docs/integrations/koog.md

@@ -76,10 +76,12 @@ See [ExecutionHandle](../../reference/execution-handle/) for the full cancel con
 |-------|---------|
 | `KoogAgentRuntime` | `AgentRuntime` SPI implementation |
 | `AtmosphereToolBridge` | Converts `ToolDefinition` → Koog `ToolDescriptor` + `ToolRegistry` with approval-gate hooks |
-| `KoogEmbeddingRuntime` | `EmbeddingRuntime` SPI for Koog-provided embedders (deferred — see below) |
 
 ## Capability matrix
 
+This mirrors `KoogAgentRuntime.capabilities()` exactly — runtime truth, not
+aspiration.
+
 | Capability | Status | Notes |
 |------------|:------:|-------|
 | `TEXT_STREAMING` | ✅ | `executeStreaming` flow + `AIAgent.run()` |
@@ -88,14 +90,14 @@ See [ExecutionHandle](../../reference/execution-handle/) for the full cancel con
 | `STRUCTURED_OUTPUT` | ✅ | System-prompt schema injection via the pipeline layer |
 | `SYSTEM_PROMPT` | ✅ | Honored by the Koog prompt builder |
 | `CONVERSATION_MEMORY` | ✅ | Per-session memory threaded through `AgentExecutionContext` |
-| `TOKEN_USAGE` | ✅ | Emitted as `ai.tokens.*` metadata when the Koog client reports it |
 | `AGENT_ORCHESTRATION` | ✅ | Works with `@Coordinator` and `@Fleet` |
+| `TOKEN_USAGE` | — | Not declared. Koog reports usage on its response objects but the bridge does not yet thread it into `StreamingSession.usage(TokenUsage)`. Tier 1 follow-up. |
 | `VISION` | — | Koog 0.7.x does not expose a stable multi-modal input API on the bridge path |
 | `MULTI_MODAL` | — | Same limitation |
 | `PROMPT_CACHING` | — | Koog 0.7.3 only ships Bedrock-specific cache variants; no OpenAI-compatible passthrough |
 | `PER_REQUEST_RETRY` | — | Inherits Koog's native retry layer (not per-request overridable from the bridge) |
 
-Exclusions are **honest** — Koog declares them as absent in its `capabilities()` set so runtime-truth advertising is accurate (Correctness Invariant #5). When Koog upstream adds these surfaces in a future release, the bridge will honor them without a breaking change.
+Exclusions are **honest** — Koog declares them as absent in its `capabilities()` set so runtime-truth advertising is accurate (Correctness Invariant #5). When Koog upstream adds these surfaces in a future release, the bridge will honor them without a breaking change. No `KoogEmbeddingRuntime` ships today — if you need Koog-backed embeddings, wire a Spring AI or LangChain4j `EmbeddingModel` alongside the Koog agent runtime.
 
 ## Samples
 

docs/src/content/docs/integrations/semantic-kernel.md

@@ -83,7 +83,7 @@ Text streaming, system prompts, conversation memory, structured output (via pipe
 | `CONVERSATION_MEMORY` | ✅ | Per-session memory threaded through `AgentExecutionContext` |
 | `STRUCTURED_OUTPUT`   | ✅ | Via pipeline-layer schema injection (no runtime-specific support needed) |
 | `TOKEN_USAGE`         | ✅ | Reported via `TokenUsage` when SK surfaces it |
-| `AGENT_ORCHESTRATION` | ✅ | Works with `@Coordinator` and `@Fleet` |
+| `AGENT_ORCHESTRATION` | — | Not declared. SK can participate in a `@Coordinator` fleet as a worker runtime, but it does not own a multi-agent dispatch loop the way ADK / Embabel / Koog do, so the capability flag is not advertised. |
 | `TOOL_CALLING`        | — | **Deferred in 4.0.36.** SK's Java tool-calling API is still stabilizing; bridging will land in a follow-up. Documented as an honest exclusion in `modules/semantic-kernel/README.md`. |
 | `TOOL_APPROVAL`       | — | Requires `TOOL_CALLING` — see above |
 | `VISION`              | — | SK Java does not yet expose a stable multi-modal input API |

docs/src/content/docs/reference/execution-handle.md

@@ -44,17 +44,19 @@ Each adapter wraps its framework's native cancel mechanism so a single
 | Runtime | Native primitive | Hard cancel |
 |---------|------------------|:-----------:|
 | Built-in        | `HttpClient` request + SSE `InputStream.close()` | ✅ true HTTP-level cancel |
-| Google ADK      | `AdkEventAdapter.whenDone()` + `Flux.dispose()` on Runner subscription | ✅ Reactor disposal |
-| JetBrains Koog  | `coroutineContext[Job].cancel()` captured inside `runBlocking` | ✅ coroutine cancel |
-| Spring AI       | `Disposable.dispose()` on the streaming `Flux` | ✅ Reactor disposal |
-| LangChain4j     | `CompletableFuture.completeExceptionally(CancellationException)` + soft-cancel flag | ⚠️ caller-side unblock; underlying HTTP drains naturally |
-| Embabel         | Soft-cancel flag polled at goal boundaries | ⚠️ cooperative only |
-| Semantic Kernel | Soft-cancel flag polled at message boundaries | ⚠️ cooperative only |
-
-"Hard cancel" means the underlying HTTP or coroutine is actually torn down.
-"Cooperative" means the caller sees cancellation immediately but the
-runtime's internal thread continues draining the stream until the LLM
-finishes — token budgets may still be consumed.
+| Spring AI       | `reactor.core.Disposable.dispose()` on the streaming `Flux` | ✅ Reactor disposal |
+| LangChain4j     | `CompletableFuture.completeExceptionally(CancellationException)` + `AtomicBoolean` soft-cancel flag consulted in the streaming response handler | ⚠️ caller-side unblock; underlying HTTP drains naturally |
+| Google ADK      | `AdkEventAdapter.cancel()` → `io.reactivex.rxjava3.disposables.Disposable.dispose()` on the Runner subscription | ✅ RxJava3 disposal |
+| JetBrains Koog  | `AtomicReference<Job>` captured by `executeInternal` → `Job.cancel()` + virtual-thread `Thread.interrupt()` belt-and-suspenders + immediate `done.complete(null)` fallback | ✅ coroutine cancel |
+| Semantic Kernel | **None**. `SemanticKernelAgentRuntime` does not override `doExecuteWithHandle`, so it inherits `AbstractAgentRuntime`'s default which calls `doExecute(...)` and returns the `ExecutionHandle.completed()` sentinel. `handle.cancel()` is a no-op. | — |
+| Embabel         | **None**. `EmbabelAgentRuntime` does not override `executeWithHandle`, so it inherits the `AgentRuntime` interface default which calls `execute(...)` and returns the `ExecutionHandle.completed()` sentinel. `handle.cancel()` is a no-op. | — |
+
+"Hard cancel" means the underlying HTTP request, coroutine, or Reactor/RxJava
+subscription is actually torn down. "Caller-side unblock" means the caller
+sees cancellation immediately but the runtime's internal thread continues
+draining the stream until the LLM finishes — token budgets may still be
+consumed. **None** means no cancel primitive is wired and `cancel()` is an
+idempotent no-op — a known gap for Embabel and Semantic Kernel.
 
 ## Usage
 

docs/src/content/docs/reference/lifecycle-listener.md

@@ -113,25 +113,41 @@ with another.
 
 ## Runtime coverage
 
-Every tool-calling `AgentRuntime` bridge fires `onToolCall` and `onToolResult`
-through the `AgentLifecycleListener.fireToolCall()` /
-`fireToolResult()` static dispatch helpers. The helpers catch and swallow any
-exception so one broken listener cannot abort the pipeline (Correctness
-Invariant #2 — Terminal Path Completeness).
+Tool-calling runtime bridges fire `onToolCall` and `onToolResult` through the
+`AgentLifecycleListener.fireToolCall()` / `fireToolResult()` static dispatch
+helpers. `onStart` / `onCompletion` / `onError` are fired by
+`AbstractAgentRuntime`'s template-method wrapper via the protected
+`fireStart` / `fireCompletion` / `fireError` helpers — so they fire
+automatically for any runtime that extends `AbstractAgentRuntime`. Runtimes
+that implement `AgentRuntime` directly are responsible for firing lifecycle
+events themselves.
+
+All helpers catch and swallow listener exceptions so one broken listener
+cannot abort the pipeline (Correctness Invariant #2 — Terminal Path
+Completeness).
 
 | Runtime | `onStart` | `onToolCall` | `onToolResult` | `onCompletion` | `onError` |
 |---------|:---------:|:------------:|:--------------:|:--------------:|:---------:|
 | Built-in        | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Spring AI       | ✅ | ✅ | ✅ | ✅ | ✅ |
 | LangChain4j     | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Google ADK      | ✅ | ✅ | ✅ | ✅ | ✅ |
-| JetBrains Koog  | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Embabel         | ✅ |  —  |  —  | ✅ | ✅ |
-| Semantic Kernel | ✅ | ⚠️ | ⚠️ | ✅ | ✅ |
-
-Embabel has no tool-calling path — `onToolCall`/`onToolResult` never fire.
-Semantic Kernel's tool-calling is deferred in 4.0.36 (documented in the
-`modules/semantic-kernel/README.md` exclusion note).
+| Semantic Kernel | ✅ | — | — | ✅ | ✅ |
+| JetBrains Koog  | — | ✅ | ✅ | — | — |
+| Embabel         | — | — | — | — | — |
+
+Built-in / Spring AI / LC4j / ADK / Semantic Kernel all extend
+`AbstractAgentRuntime`, so `onStart` / `onCompletion` / `onError` fire
+automatically in the base-class `execute` wrapper. SK is also honest about
+having no tool-calling path in 4.0.36.
+
+Koog and Embabel implement `AgentRuntime` directly. Koog's `AtmosphereToolBridge`
+fires `onToolCall` / `onToolResult`, but `KoogAgentRuntime.executeWithHandle`
+does not currently call `fireStart` / `fireCompletion` / `fireError` — that's
+a documented gap the bridge will close once it either subclasses
+`AbstractAgentRuntime` or inlines the three calls. Embabel's runtime does
+neither and has no tool path, so no lifecycle events fire today — that is
+also a known gap.
 
 ## Listener error isolation
 
@@ -222,17 +238,39 @@ replay, debugging, or eval harnesses. See
 
 ## Testing
 
-The `AiTestClient` in `atmosphere-ai-test` exposes a capturing listener for
-assertions:
+The easiest pattern is a tiny anonymous subclass that records events into a
+list you can assert against:
 
 ```java
-var captured = new CapturingLifecycleListener();
-var context = testContext.withListeners(List.of(captured));
+var captured = new java.util.ArrayList<String>();
+var listener = new AgentLifecycleListener() {
+    @Override
+    public void onStart(AgentExecutionContext ctx) { captured.add("start"); }
+
+    @Override
+    public void onToolCall(String toolName, java.util.Map<String, Object> args) {
+        captured.add("toolCall:" + toolName);
+    }
+
+    @Override
+    public void onToolResult(String toolName, String resultPreview) {
+        captured.add("toolResult:" + toolName);
+    }
+
+    @Override
+    public void onCompletion(AgentExecutionContext ctx) { captured.add("complete"); }
+
+    @Override
+    public void onError(AgentExecutionContext ctx, Throwable error) {
+        captured.add("error:" + error.getClass().getSimpleName());
+    }
+};
+
+var context = testContext.withListeners(java.util.List.of(listener));
 runtime.execute(context, session);
 
-assertThat(captured.toolCalls()).containsExactly("get_weather");
-assertThat(captured.toolResults()).hasSize(1);
-assertThat(captured.completed()).isTrue();
+assertThat(captured).containsExactly("start", "toolCall:get_weather",
+        "toolResult:get_weather", "complete");
 ```
 
 See [AI Testing](../testing/) for the full contract test surface.

docs/src/content/docs/reference/tool-approval-policy.md

@@ -222,19 +222,21 @@ void denyAllSkipsApprovalGate() {
     var context = testContext()
             .withApprovalPolicy(ToolApprovalPolicy.denyAll());
 
+    // Signature: (toolName, tool, args, session, strategy, policy)
     var result = ToolExecutionHelper.executeWithApproval(
             tool.name(), tool, Map.of(),
+            testSession,                        // streaming session sink
             ApprovalStrategy.autoApprove(),     // strategy should NEVER fire
-            context.approvalPolicy(),
-            context.listeners());
+            context.approvalPolicy());          // DenyAll short-circuits before strategy
 
     assertThat(result).contains("\"status\":\"cancelled\"");
     // Tool executor never ran — the AssertionError is never thrown
 }
 ```
 
-Contract tests in `AbstractAgentRuntimeContractTest.runtimeWithToolApprovalHonorsPolicy()`
-exercise every runtime subclass against all four policy variants.
+Contract assertions in `AbstractAgentRuntimeContractTest` exercise every
+runtime subclass against the four policy variants through
+`hitlPendingApprovalEmitsProtocolEvent` and related assertions.
 
 ## See also
 

docs/src/content/docs/tutorial/24-durable-hitl.md

@@ -43,7 +43,8 @@ Three pieces cooperate:
    the invocation through the `ApprovalStrategy`. You already know this.
 2. **`CheckpointStore`** — SPI that persists the `WorkflowSnapshot` (the
    agent's conversation history, pending tool call, approval ID) to a
-   durable backend (SQLite, Redis, Postgres) before the thread parks.
+   durable backend (SQLite in-tree; Redis/Postgres/etc. are pluggable)
+   before the thread parks.
 3. **`/__approval/<id>/approve`** REST endpoint that accepts the decision
    out-of-band, loads the snapshot, and resumes execution on the new JVM.
 
@@ -53,16 +54,17 @@ for the REST callback.
 
 ## Wiring the CheckpointStore
 
-Atmosphere ships three `CheckpointStore` implementations:
+Atmosphere 4.0.36 ships two `CheckpointStore` implementations in-tree:
 
-- **`InMemoryCheckpointStore`** — default; non-durable (lost on restart)
+- **`InMemoryCheckpointStore`** — default; non-durable (lost on restart).
+  Use in tests and single-process dev environments.
 - **`SqliteCheckpointStore`** — file-backed; survives restarts on the same
-  host (single-node durability)
-- **`RedisCheckpointStore`** — network-backed; survives restarts across a
-  fleet (multi-node durability)
+  host (single-node durability).
 
-Pick SQLite for single-host deployments, Redis for multi-host. Both share
-the same SPI, so your agent code doesn't change.
+The `CheckpointStore` interface is an SPI: you can implement your own
+backing store (Redis, Postgres, DynamoDB, S3…) by writing an adapter that
+implements `save`, `load`, `listByCoordination`, and `delete`. `SqliteCheckpointStore`
+is the reference implementation and the file to copy.
 
 ### Spring Boot configuration
 
@@ -75,19 +77,6 @@ atmosphere:
         path: /var/lib/atmosphere/checkpoints.db
 ```
 
-Or for Redis:
-
-```yaml
-atmosphere:
-  ai:
-    checkpoint:
-      store: redis
-      redis:
-        host: redis.internal
-        port: 6379
-        keyspace: atmosphere:checkpoints
-```
-
 The auto-config wires the chosen store to the coordination journal and to
 the `ApprovalRegistry` so pending approvals land in the store before the
 virtual thread parks.

website/src/components/Atmosphere.astro

@@ -47,7 +47,7 @@ const pillars = [
       { name: '@Coordinator & @Fleet', detail: 'Declarative multi-agent orchestration. A @Coordinator injects an AgentFleet and dispatches work to @Agent beans over local, A2A, or MCP transports. Portable across Spring Boot, Quarkus, and plain JVM.', url: 'https://async-io.org/docs/agents/coordinator/', urlLabel: 'Coordinator Docs' },
       { name: '@RequiresApproval (HITL)', detail: 'Park a virtual thread until a user approves or denies a tool call via the /__approval/ wire protocol. Every @AiTool annotated with @RequiresApproval gates through the ToolApprovalPolicy sealed interface (AllowAll, DenyAll, Annotated, Custom).', url: 'https://async-io.org/docs/reference/tool-approval-policy/', urlLabel: 'ToolApprovalPolicy' },
       { name: 'Agent Handoffs', detail: 'session.handoff("billing", message) transfers a conversation with full history to another @Agent. Built-in cycle guard prevents infinite handoff loops; AiEvent.Handoff surfaces on the wire for UI state transitions.', url: 'https://async-io.org/docs/tutorial/10-ai-tools/', urlLabel: 'Tutorial' },
-      { name: 'Durable HITL', detail: 'CheckpointStore SPI (in-memory, SQLite, Redis) persists parent-chained conversation snapshots. An approval that arrives after a JVM restart resumes the exact turn and resurrects the execution on a fresh virtual thread.', url: 'https://async-io.org/docs/tutorial/24-durable-hitl/', urlLabel: 'Durable HITL Tutorial' },
+      { name: 'Durable HITL', detail: 'CheckpointStore SPI with InMemory and SQLite backends in-tree, pluggable for your own store. Parent-chained conversation snapshots so an approval arriving after a JVM restart resumes the exact turn on a fresh virtual thread.', url: 'https://async-io.org/docs/tutorial/24-durable-hitl/', urlLabel: 'Durable HITL Tutorial' },
       { name: 'ExecutionHandle', detail: 'Cooperative cancel for in-flight agent executions. Each runtime wraps its native cancel primitive (HTTP close, coroutine Job cancel, Reactor Flux dispose). handle.cancel() is idempotent and thread-safe.', url: 'https://async-io.org/docs/reference/execution-handle/', urlLabel: 'ExecutionHandle Docs' },
     ],
     extras: ['LLM-as-judge eval', 'Long-term memory', 'Conditional routing', 'Lifecycle listeners'],

website/src/components/GetStarted.astro

@@ -9,8 +9,8 @@ const steps = [
   {
     n: '02',
     title: 'Create a project',
-    code: 'atmosphere create my-agent --template ai-chat',
-    note: '11 templates: ai-chat, ai-tools, rag-chat, mcp-server, coordinator…',
+    code: 'atmosphere new my-agent --template ai-chat',
+    note: 'Handlers: chat, ai-chat, mcp-server',
   },
   {
     n: '03',
@@ -75,7 +75,7 @@ const steps = [
         First App Tutorial
       </a>
       <a href="https://github.com/Atmosphere/atmosphere/tree/main/samples" class="btn btn-tertiary">
-        Browse 24 samples &rarr;
+        Browse 20 samples &rarr;
       </a>
     </div>
   </div>

website/src/components/WhatsNew.astro

@@ -52,7 +52,7 @@ const highlights = [
   {
     badge: 'Feature',
     title: 'Durable HITL workflows',
-    description: 'CheckpointStore SPI with in-memory, SQLite, and Redis backends. An approval that arrives after a JVM restart resumes the exact turn on a fresh virtual thread.',
+    description: 'CheckpointStore SPI with InMemory + SQLite backends, pluggable for your own backing store. An approval that arrives after a JVM restart resumes the exact turn on a fresh virtual thread.',
     link: 'https://async-io.org/docs/tutorial/24-durable-hitl/',
     linkLabel: 'Durable HITL tutorial',
   },