docs: fix 29 doc hallucinations caught by adversarial audit (incl. one from this session)

Correct broken Spring Boot YAML config keys, fabricated sandbox API, non-existent durable-hitl sample link, wrong rag dep versions, capability-matrix prose (TOOL_CALL_DELTA/CANCELLATION/Alibaba/EmbeddingRuntime), and overclaiming javadoc.

Author: jfarcand

MIGRATION.md

@@ -397,7 +397,7 @@ atmosphere:
   packages: com.yourapp.atmosphere
   servlet-path: /atmosphere/*
   session-support: false
-  heartbeat-interval-in-seconds: 60
+  heartbeat-interval: 60s
   init-params:
     org.atmosphere.websocket.maxIdleTime: "300000"
 ```
@@ -615,7 +615,7 @@ Configuration is done via init-params:
 ## 6. Client Library Migration (atmosphere.js)
 
 This is a **breaking change**. The old `atmosphere.js` (jQuery-based, 2.x/3.x)
-has been replaced with a modern TypeScript library (5.0.0).
+has been replaced with a modern TypeScript library (5.x).
 
 ### Installation
 
@@ -929,8 +929,8 @@ Spring Boot configuration:
 atmosphere:
   durable-sessions:
     enabled: true
-    session-ttl-minutes: 1440
-    cleanup-interval-seconds: 60
+    session-ttl: 1440m
+    cleanup-interval: 60s
 ```
 
 ### AI/LLM Streaming

README.md

@@ -27,7 +27,7 @@ Atmosphere is built for teams that need AI agents to behave like production serv
 | Stream to real clients | WebSocket, SSE, long-polling, and gRPC run through one broadcaster pipeline as always-on defaults; WebTransport over HTTP/3 is optional (needs `jetty-http3-server` or `reactor-netty-http` on the classpath plus a dev cert) |
 | Swap AI integrations | One `AgentRuntime` SPI with twelve runtime adapters and contract-tested capability flags |
 | Govern execution | Policy admission, `@AgentScope`, human approval, plan-and-verify, cost ceilings, PII rewriting, and admin kill switches |
-| Pause for humans | Durable HITL approvals park virtual threads, persist workflow state, and resume through REST approval surfaces |
+| Pause for humans | Durable HITL approvals hibernate without holding a thread, persist workflow state, and resume through REST approval surfaces |
 | Resume long runs | Durable sessions, run IDs, replay buffers, checkpoints, and reconnect-safe continuation |
 | Expose the same agent everywhere | Browser endpoints plus MCP (stateless **2026-07-28** RC + sessions back to 2024-11-05), A2A, AG-UI, Slack, Telegram, Discord, WhatsApp, and Messenger modules |
 
@@ -242,7 +242,6 @@ For Java/Kotlin clients, use [wAsync](modules/wasync/) for async WebSocket, SSE,
 | [startup team](samples/spring-boot-multi-agent-startup-team/) | `@Coordinator` with A2A specialists, governance, checkpoints, skills, admin control plane |
 | [ai-chat](samples/spring-boot-ai-chat/) | Streaming AI chat with auth, caching, and runtime adapter portability |
 | [ai-tools](samples/spring-boot-ai-tools/) | Framework-agnostic `@AiTool` methods and approval gates |
-| [durable-hitl](samples/spring-boot-durable-hitl/) | Human approval gates that persist, resume, and replay across reconnects |
 | [checkpoint-agent](samples/spring-boot-checkpoint-agent/) | Checkpointed `@Coordinator` workflow with REST approval/resume |
 | [ai-classroom](samples/spring-boot-ai-classroom/) | Multi-room collaborative AI with React Native / Expo client |
 | [guarded-email-agent](samples/spring-boot-guarded-email-agent/) | Plan-and-verify taint protection before any email tool fires |

cli/README.md

@@ -190,7 +190,7 @@ Every template sparse-clones the matching sample from `cli/samples.json` into th
 | `guarded-agent` ⭐ | `spring-boot-guarded-email-agent` | Plan-and-Verify (Meijer) — refuses unsafe LLM-emitted plans before any tool fires |
 | `ms-governance` ⭐ | `spring-boot-ms-governance-chat` | Governance demo: policy admission, decision viewer, kill switch, write-gated admin endpoints |
 | `assistant` | `spring-boot-personal-assistant` | Long-lived memory-bearing assistant: AgentState + AgentWorkspace + AgentIdentity + ProtocolBridge |
-| `multi-agent` | `spring-boot-multi-agent-startup-team` | Fleet of 5 independent `@Agent` classes collaborating over A2A |
+| `multi-agent` | `spring-boot-multi-agent-startup-team` | A `@Coordinator` (CEO) dispatching to 4 `@Agent` specialists over A2A |
 | `classroom` | `spring-boot-ai-classroom` | Shared streaming AI responses across web + Expo React Native clients |
 
 ⭐ marks the five **flagship enterprise templates** — the canonical agent

docs/governance-policy-plane.md

@@ -87,10 +87,10 @@ Implementations must be thread-safe, side-effect-free (except for metrics/loggin
 `org.atmosphere.ai.governance.PolicyParser` — parse a declarative artifact into `List<GovernancePolicy>`. The SPI contract supports `java.util.ServiceLoader` discovery; three implementations ship in-tree:
 
 - **`YamlPolicyParser`** (`format() = "yaml"`, `modules/ai`) — SnakeYAML `SafeConstructor` (no arbitrary class instantiation). Auto-detects Atmosphere-native vs Microsoft Agent Governance Toolkit schema by inspecting the root keys. Registered via `META-INF/services/org.atmosphere.ai.governance.PolicyParser`, so adding `atmosphere-ai` to the classpath is enough to wire it up.
-- **`RegoPolicyParser`** (`modules/ai-policy-rego`) — wraps an external OPA process via `RegoEvaluator`. **Wired programmatically**: instantiate with `new RegoPolicyParser(registry)` and pass it where you'd otherwise consume a `YamlPolicyParser`. No `META-INF/services` entry ships today, so adding the dependency alone does not auto-discover it.
-- **`CedarPolicyParser`** (`modules/ai-policy-cedar`) — Cedar policy text via `CedarAuthorizer` / `CedarCliAuthorizer`. Same posture as Rego: programmatic wiring, no `META-INF/services` entry.
+- **`RegoPolicyParser`** (`modules/ai-policy-rego`) — wraps an external OPA process via `RegoEvaluator`. Registered via `META-INF/services/org.atmosphere.ai.governance.PolicyParser` (same as `YamlPolicyParser`), so adding `atmosphere-ai-policy-rego` to the classpath is enough to auto-discover it. Programmatic wiring (`new RegoPolicyParser(registry)`) remains available for callers who want explicit control.
+- **`CedarPolicyParser`** (`modules/ai-policy-cedar`) — Cedar policy text via `CedarAuthorizer` / `CedarCliAuthorizer`. Same posture as Rego: ships a `META-INF/services/org.atmosphere.ai.governance.PolicyParser` entry, so adding `atmosphere-ai-policy-cedar` to the classpath auto-discovers it.
 
-Third-party parsers can register either path. ServiceLoader auto-discovery is the SPI-level recipe (ship a `PolicyParser` impl plus a `META-INF/services/org.atmosphere.ai.governance.PolicyParser` entry); programmatic wiring is the recipe the in-tree Rego/Cedar adapters use today.
+Third-party parsers can register either path. ServiceLoader auto-discovery is the SPI-level recipe (ship a `PolicyParser` impl plus a `META-INF/services/org.atmosphere.ai.governance.PolicyParser` entry); all three in-tree adapters (Yaml/Rego/Cedar) ship such an entry, so they auto-discover from the classpath. Programmatic wiring remains available for callers who want explicit control.
 
 The audit-sink family follows the same posture: `AsyncAuditSink` ships in `modules/ai`; `KafkaAuditSink` (`modules/ai-audit-kafka`) and `JdbcAuditSink` (`modules/ai-audit-postgres`) are wired programmatically as well — no `META-INF/services` entries.
 

docs/runtime-selection.md

@@ -18,7 +18,7 @@ Walk these questions in order; stop at the first match.
 
 1. **Are you new to Atmosphere AI and just need it to work?**
    → **Built-in (`atmosphere-ai`)**. Zero extra deps, OpenAI-compatible
-   client out of the box, one of three runtimes (with Anthropic and Cohere)
+   client out of the box, one of two runtimes (with Cohere)
    that emit `TOOL_CALL_DELTA` for token-streaming tool-call argument deltas. Use
    `--model` / `LLM_API_KEY` to point at OpenAI / Gemini / Ollama / any
    compatible endpoint.
@@ -109,9 +109,9 @@ ordered from "most-general / most-portable" at the top to
 | LangChain4j | Vendor-neutral JVM (Quarkus, Micronaut, Vert.x) | You want OpenAI-only | Token-by-token | ✅ | ✅ |
 | Google ADK | Gemini-native + sub-agent orchestration | You're not using Gemini | Token-by-token | ✅ + `AGENT_ORCHESTRATION` | — |
 | Embabel | Goal-graph planner workflows | You want imperative dispatch | Token-by-token | ✅ + `AGENT_ORCHESTRATION` | ✅ |
-| Koog | Kotlin coroutine + native `CANCELLATION` | You're not on Kotlin | Token-by-token | ✅ + `AGENT_ORCHESTRATION` + `CANCELLATION` | ✅ |
+| Koog | Kotlin coroutine + native cancellation mechanism | You're not on Kotlin | Token-by-token | ✅ + `AGENT_ORCHESTRATION` | ✅ |
 | Semantic Kernel | Microsoft / .NET ecosystem parity on JVM | You don't need SK plugins/planners | Token-by-token | ✅ | ✅ |
-| AgentScope | Qwen-native ReAct, Alibaba Cloud AI Studio | You want anything other than Qwen | Token-by-token | ✅ + `CANCELLATION` | — |
+| AgentScope | Qwen-native ReAct, Alibaba Cloud AI Studio | You want anything other than Qwen | Token-by-token | ✅ | — |
 | Spring AI Alibaba | DashScope / `ReactAgent` graph on Spring Boot 3 | You're on Spring Boot 4 | **Buffered** (one chunk + complete) | ✅ | ✅ |
 | Anthropic | Native Anthropic Messages API without a third-party SDK | You need audio input | Token-by-token | ✅ | — |
 | Cohere | Native Cohere v2 Chat API | You need audio input | Token-by-token | ✅ + `TOOL_CALL_DELTA` | — |
@@ -124,6 +124,8 @@ them once in the pipeline layer or in `AbstractAgentRuntime` — the adapter
 only plugs in where it differs:
 
 - **`TEXT_STREAMING`** (every runtime; Spring AI Alibaba is buffered)
+- **`CANCELLATION`** (every runtime — the mechanism differs per adapter, e.g.
+  native coroutine cancel on Koog, Reactor subscription cancel on AgentScope)
 - **`SYSTEM_PROMPT`** (every runtime)
 - **`STRUCTURED_OUTPUT`** (every runtime — pipeline wraps the session in
   `StructuredOutputCapturingSession` with system-prompt schema injection)
@@ -144,8 +146,7 @@ only plugs in where it differs:
   snapshots `context.history()` into a `CheckpointStore` for the other eleven)
 
 Use the table at the top to decide on the specialized capabilities
-(`AGENT_ORCHESTRATION`, `CANCELLATION`, multi-modal vision/audio,
-`PROMPT_CACHING`).
+(`AGENT_ORCHESTRATION`, multi-modal vision/audio, `PROMPT_CACHING`).
 
 ## Swapping runtimes
 
@@ -161,7 +162,9 @@ atmosphere new my-app --template ai-chat --runtime spring-ai --force
 ```
 
 `--runtime` accepts `builtin`, `spring-ai`, `langchain4j`, `adk`, `embabel`,
-`koog`, `semantic-kernel`, `agentscope`, `spring-ai-alibaba`. The `--force`
+`koog`, `semantic-kernel`, `agentscope`, `spring-ai-alibaba`, `anthropic`,
+`cohere`, `crewai` — any key defined in `cli/runtime-overlays.json` (12 today).
+The `--force`
 flag (only valid with `--runtime`) wipes any existing adapter dependency
 declared in `cli/runtime-overlays.json` from the scaffolded `pom.xml`
 *before* injecting the chosen overlay — required for samples that already

modules/ai/README.md

@@ -49,7 +49,7 @@ The `AgentRuntime` interface is the AI-layer equivalent of `AsyncSupport`. Imple
 | `atmosphere-spring-ai-alibaba` | `SpringAiAlibabaAgentRuntime` | 100 | TEXT_STREAMING (buffered), SYSTEM_PROMPT, STRUCTURED_OUTPUT, CONVERSATION_MEMORY, TOOL_CALLING, TOOL_APPROVAL, TOKEN_USAGE, PER_REQUEST_RETRY, BUDGET_ENFORCEMENT, CONFIDENCE_SCORES, PASSIVATION, VISION, AUDIO, MULTI_MODAL, CANCELLATION (cooperative) *(see runtime caveats below)* |
 | `atmosphere-semantic-kernel` | `SemanticKernelAgentRuntime` | 100 | TEXT_STREAMING, SYSTEM_PROMPT, STRUCTURED_OUTPUT, CONVERSATION_MEMORY, TOKEN_USAGE, TOOL_CALLING, TOOL_APPROVAL, PER_REQUEST_RETRY, BUDGET_ENFORCEMENT, CONFIDENCE_SCORES, PASSIVATION, VISION, MULTI_MODAL, CANCELLATION |
 
-Every runtime emits `TokenUsage` via `StreamingSession.usage()` when the underlying API provides token counts, feeding `ai.tokens.*` metadata into `MetricsCapturingSession` and `MicrometerAiMetrics`. Capability declarations are pinned in each runtime's contract test (`AbstractAgentRuntimeContractTest.expectedCapabilities()`), so the table above cannot drift from the running code without breaking the build. The aggregate counts ("12 runtimes") and the per-row capability lists are additionally pinned against `.harness/capabilities.snapshot.json` by `CapabilitySnapshotTest` and `scripts/validate-capability-claims.sh` (run from pre-push), so prose claims about the matrix break the build alongside code drift.
+Every runtime emits `TokenUsage` via `StreamingSession.usage()` when the underlying API provides token counts, feeding `ai.tokens.*` metadata into `MetricsCapturingSession` and `MicrometerAiMetrics`. Capability declarations are pinned in each runtime's contract test (`AbstractAgentRuntimeContractTest.expectedCapabilities()`), so the table above cannot drift from the running code without breaking the build. The aggregate counts ("12 runtimes") and the per-row capability lists are additionally pinned against `.harness/capabilities.snapshot.json` by `CapabilitySnapshotTest` and `scripts/validate-capability-claims.sh` (run from pre-push). That enforcement covers the structured table rows and the tight count claims (`All N runtimes`, `N AiCapability`/`N capabilities total`) only; free-form per-runtime narrative below is **not** machine-checked, so keep that prose in sync with the table by hand.
 
 Each runtime additionally ships a portable signed manifest at `modules/<X>/SKILLCARD.yaml` (and `SKILLCARD.yaml.sig` after a tagged release). `scripts/regen-skillcards.sh` emits the YAML from the snapshot + module `pom.xml`; `.github/workflows/sign-skillcards.yml` signs every card on tag push via OpenSSF Model Signing (Sigstore keyless OIDC — short-lived Fulcio cert + Rekor transparency-log entry, OIDC identity bound to the workflow path). Both the card and its `.sig` bundle are packaged into each runtime jar at `META-INF/atmosphere/` so a downstream consumer can verify integrity without unpacking the source tree. `SkillCardSnapshotTest` enforces drift detection, shape conformance, and signature verification when a `.sig` is present; verify locally with `./scripts/verify-skillcards.sh --identity https://github.com/Atmosphere/atmosphere/.github/workflows/sign-skillcards.yml@refs/tags/<TAG> --identity-provider https://token.actions.githubusercontent.com`. Cards on `main` between releases are unsigned by design — the workflow runs at tag time.
 
@@ -1090,26 +1090,34 @@ prevention, dynamic routing, and long-pause human-in-the-loop:
   is called per request, and `assembleMessages` also threads a
   `SystemMessage` into the `List<Message>` dispatched to `call(...)`.
   `CONVERSATION_MEMORY` is honored because the same message list carries
-  `context.history()`. `TOKEN_USAGE` is **not** declared because
-  `ReactAgent.call()` returns `org.springframework.ai.chat.messages.AssistantMessage`
-  which has no surface for the `ChatResponse` usage metadata as of v1.1.2.0;
-  the agent framework's `CompiledGraph` captures usage internally but does not
-  return it through the `call(...)` API. `TOOL_CALLING` is not declared because
-  Spring AI Alibaba's tool surface bridges Spring AI `FunctionCallback`s, which
-  would need a separate `SpringAiAlibabaToolBridge` to satisfy
-  `TOOL_APPROVAL`. **Spring Boot 3.5 only**: Spring AI Alibaba 1.1.2.0
+  `context.history()`. `TOKEN_USAGE` is declared because
+  `AtmosphereSpringAiAlibabaAutoConfiguration` wraps the Spring AI `ChatModel`
+  bean in the `UsageCapturingChatModel` decorator (see footnote ² above), which
+  accumulates `ChatResponseMetadata.getUsage()` across every step of the ReAct
+  graph into a per-thread collector the runtime emits via `session.usage(...)`
+  after each dispatch — `ReactAgent.call()` returns an
+  `org.springframework.ai.chat.messages.AssistantMessage` with no usage surface,
+  so the decorator is what closes the gap. `TOOL_CALLING` and `TOOL_APPROVAL`
+  are declared because `doExecute` builds a per-request `ReactAgent` with
+  `SpringAiAlibabaToolBridge` attached when `context.tools()` is non-empty; the
+  bridge routes every tool invocation through
+  `ToolExecutionHelper.executeWithApproval` so `@RequiresApproval` gates fire
+  uniformly. **Spring Boot 3.5 only**: Spring AI Alibaba 1.1.2.0
   transitively pulls Spring AI 1.1.2 which references Spring Boot 3.x
   autoconfigure classes (e.g. `RestClientAutoConfiguration`) that don't exist
   in Spring Boot 4 — the CLI overlay must be applied with `-Pspring-boot3`,
   same situation as Embabel.
-- **`TOOL_CALL_DELTA`** is declared only by `BuiltInAgentRuntime`. Built-in's
-  `OpenAiCompatibleClient` forwards every `delta.tool_calls[].function.arguments`
-  fragment through `session.toolCallDelta(acc.id(), argChunk)` on both the
-  chat-completions and responses-API streaming paths (see
-  `OpenAiCompatibleClient.java` lines ~530 and ~892), so browser UIs receive
-  `ai.toolCall.delta.*` metadata frames before the consolidated `AiEvent.ToolStart`
-  fires. The tool-capable framework bridges (Spring AI, LangChain4j, ADK,
-  Embabel, Koog, Semantic Kernel) honor the default `StreamingSession.toolCallDelta()` no-op
+- **`TOOL_CALL_DELTA`** is declared by `BuiltInAgentRuntime` and
+  `CohereAgentRuntime`. Built-in's `OpenAiCompatibleClient` forwards every
+  `delta.tool_calls[].function.arguments` fragment through
+  `session.toolCallDelta(acc.id(), argChunk)` on both the chat-completions and
+  responses-API streaming paths (see `OpenAiCompatibleClient.java` lines ~530
+  and ~892), and Cohere's `CohereChatClient` emits the same frames via
+  `session.toolCallDelta(acc.id, chunk)` from `handleToolCallDelta`, so browser
+  UIs receive `ai.toolCall.delta.*` metadata frames before the consolidated
+  `AiEvent.ToolStart` fires. The remaining tool-capable framework bridges
+  (Spring AI, LangChain4j, ADK, Embabel, Koog, Semantic Kernel) honor the
+  default `StreamingSession.toolCallDelta()` no-op
   contract but do not emit chunks from their streaming loops — their high-level
   APIs surface only consolidated tool calls, and the negative assertion in
   `modules/integration-tests/e2e/ai-tool-call-delta.spec.ts` pins the gap
@@ -1123,9 +1131,11 @@ Seven `EmbeddingRuntime` implementations are registered via `ServiceLoader`. The
 | Runtime | Module | Priority | Notes |
 |---------|--------|----------|-------|
 | `SpringAiEmbeddingRuntime` | `atmosphere-spring-ai` | 200 | Wraps Spring AI `EmbeddingModel` |
+| `SpringAiAlibabaEmbeddingRuntime` | `atmosphere-spring-ai-alibaba` | 200 | Wraps Spring AI Alibaba `EmbeddingModel` |
 | `LangChain4jEmbeddingRuntime` | `atmosphere-langchain4j` | 190 | Wraps LC4j `EmbeddingModel`; unwraps `Response<Embedding>` |
 | `SemanticKernelEmbeddingRuntime` | `atmosphere-semantic-kernel` | 180 | Wraps SK `TextEmbeddingGenerationService`; `Mono.block()` sync boundary |
 | `EmbabelEmbeddingRuntime` | `atmosphere-embabel` | 170 | Wraps Embabel `EmbeddingService` (1:1 SPI map) |
+| `KoogEmbeddingRuntime` | `atmosphere-koog` | 100 (default) | Wraps Koog `LLMEmbeddingProvider` |
 | `BuiltInEmbeddingRuntime` | `atmosphere-ai` | 50 | HTTP POST to `/v1/embeddings`; zero-dep fallback |
 
 See <https://atmosphere.github.io/docs/reference/ai/> for the Astro reference page (maintained in the `atmosphere.github.io` repo).

modules/ai/src/main/java/org/atmosphere/ai/governance/owasp/OwaspAgenticMatrix.java

@@ -20,11 +20,13 @@
 /**
  * Atmosphere's self-assessment against the <a
  * href="https://genai.owasp.org/resource/agentic-ai-top-10/">OWASP Agentic AI
- * Top 10</a> (December 2025). Every row points at (a) the shipped feature
- * that defends against the threat, (b) a regression test that fires on the
- * evidence path, and (c) a production-consumer grep pattern so reviewers
- * can confirm the primitive is reached on a real turn — per CLAUDE.md
- * "SPI presence ≠ runtime presence."
+ * Top 10</a> (December 2025). Every addressed (COVERED / PARTIAL / DESIGN)
+ * row points at (a) the shipped feature that defends against the threat,
+ * (b) a regression test that fires on the evidence path, and (c) a
+ * production-consumer grep pattern so reviewers can confirm the primitive
+ * is reached on a real turn — per CLAUDE.md "SPI presence ≠ runtime presence."
+ * {@link Coverage#NOT_ADDRESSED} rows carry no evidence and state the gap in
+ * their notes column.
  *
  * <h2>Coverage vocabulary</h2>
  * <ul>