fix(docs): correct third-party dep versions and stale citations (doc-drift audit)

Third-party deps (google-adk, grpc, spring-ai, langchain4j) were stamped with Atmosphere 4.0.54 -> real upstream versions; Spring AI M6->2.0.0 GA prose; NVIDIA placeholder URL fixed in skillcard generator + SKILLCARDS.md; added missing browser-agent template row. New validate-doc-thirdparty-versions.sh gates the version-stamping class.

Author: jfarcand

.harness/drift-log.md

@@ -1529,3 +1529,57 @@ hot-path) — it is the auditor's / a scheduled CI lane's job.
   shipped-without-consumer drift) or it bot-blocks the probe. Needs the maintainer to
   confirm the repo exists or correct the references — deliberately NOT allowlisted, so the
   link checker keeps flagging it.
+
+---
+
+## 2026-06-16 — doc-drift-audit run: third-party version stamping + stale citations
+
+Ran the `doc-drift-audit` workflow (16 groups, 98 agents) across both repos. It
+confirmed 46 drifts (the verify pass and synthesis were partly truncated by an
+upstream rate-limit, so the real count is higher). The dominant, clearly-real
+main-repo cluster is fixed here, plus a structural gate for the worst class.
+
+### Third-party dependency versions stamped with Atmosphere's release number
+
+**Claim:** dependency-block examples named third-party artifacts at Atmosphere's
+version: `com.google.adk:google-adk:4.0.54` (modules/adk/README.md:26),
+`io.grpc:grpc-netty-shaded:4.0.54` (modules/wasync/README.md:110),
+`org.springframework.ai:spring-ai-vector-store:4.0.54` (modules/rag/README.md:165),
+`dev.langchain4j:langchain4j-core:4.0.54` (modules/rag/README.md:188), plus four on
+the website (semantickernel-api / -aiservices-openai, jakarta.inject-api,
+jackson-databind).
+
+**Truth:** the real upstream versions are google-adk 1.2.0, grpc 1.81.0, Spring AI
+2.0.0, langchain4j 1.15.0, Semantic Kernel 1.5.0 (verified against pom.xml
+properties). A release-bump find/replace rewrote every `<version>4.0.x</version>`
+in the docs — including the ones inside non-Atmosphere `<dependency>` blocks. A
+reader copying the snippet gets a Maven artifact that does not exist. Same class as
+the hand-fixed Z3 binding (commit aaf1fbf2fb); this time the audit found the whole
+set at once.
+
+**Gate added:** `scripts/validate-doc-thirdparty-versions.sh` (+ pom-derived 4.0.5x
+band, allowlist, pre-push wiring) — parses `<dependency>` blocks in docs and fails
+when a non-`org.atmosphere` groupId carries an Atmosphere version. Main-repo
+hard-fail, sibling advisory (per #20). All four main-repo instances fixed; the four
+sibling instances are advisory, left for the website's lifecycle.
+
+### Stale framework-version + citation prose (also fixed)
+
+- **Spring AI 2.0.0-M6 → 2.0.0 (GA).** The adapter upgraded to GA in f844e80691
+  (2026-06-12) but four narrative mentions lagged: README.md:150,
+  modules/ai/README.md:67 & :283, modules/spring-ai/README.md:85. Same drift class
+  as #12/#18 (prose trailing a pom property); fixed.
+- **NVIDIA citation was a truncated placeholder.** `…/nvidia-verified-agent-skills-...`
+  (a literal ellipsis) 404s; the canonical post is `…-provide-capability-governance-for-ai-agents/`
+  (verified 200). Fixed in the generator (scripts/regen-skillcards.sh,
+  sign-skillcards.sh) AND the generated SKILLCARDS.md so a regen won't reintroduce it.
+- **`browser-agent` template missing from the cli/README.md table.** It exists in the
+  `cmd_new` map, `cli/samples.json`, and the prose list, but the "Available Templates"
+  table under-enumerated it (12 of 13). Row added.
+
+### Not auto-fixed (surfaced)
+
+The remaining audit findings — many `capability_contradiction` hits that on
+inspection are honest "NOT supported" doc sections (likely audit false positives),
+and the sibling-repo items above — need per-item human verification before editing
+and are left for a follow-up pass rather than mass-applied.

.harness/thirdparty-version-allowlist.txt

@@ -0,0 +1,4 @@
+# Allowlist for scripts/validate-doc-thirdparty-versions.sh (substring match
+# against "<file>: <groupId>:<artifactId>:<version>"). Use ONLY for a genuine
+# third-party artifact whose real upstream version legitimately sits on a 4.0.x
+# line. None known today.

README.md

@@ -147,7 +147,7 @@ Capabilities are intentionally not identical. The authoritative matrix is pinned
 | Runtime adapter | Backing framework | Spring Boot | Capability highlights | Notes |
 |---|---|---|---|---|
 | `atmosphere-ai` (Built-in) | OpenAI-compatible HTTP client | 3.5 / 4.0 | tool calling, JSON mode, vision, audio, prompt caching, token usage, native retry, tool-call deltas | Default. Works with OpenAI-compatible endpoints such as OpenAI, Gemini compatibility endpoints, Ollama, and local proxies. |
-| `atmosphere-spring-ai` | Spring AI 2.0.0-M6 | 4.0 | tool calling, structured output, vision, audio, prompt caching, token usage | Best fit for Spring Boot applications already using Spring AI. |
+| `atmosphere-spring-ai` | Spring AI 2.0.0 | 4.0 | tool calling, structured output, vision, audio, prompt caching, token usage | Best fit for Spring Boot applications already using Spring AI. |
 | `atmosphere-langchain4j` | LangChain4j 1.15.0 | 4.0 | tool calling, structured output, vision, audio, prompt caching, token usage | Best fit for LangChain4j tool ecosystems and non-Spring services. |
 | `atmosphere-adk` | Google ADK 1.2.0 | 4.0 | agent orchestration, tool calling, multi-modal, prompt caching | Multi-agent runtime with `AGENT_ORCHESTRATION`. |
 | `atmosphere-koog` | JetBrains Koog 1.0.0 | 4.0 | agent orchestration, tool calling, multi-modal, prompt caching, cancellation | Multi-agent runtime. |

SKILLCARDS.md

@@ -14,7 +14,7 @@ at `META-INF/atmosphere/SKILLCARD.yaml[.sig]`, so downstream consumers
 can verify integrity without re-fetching from this repository.
 
 Inspired by NVIDIA's verified-agent-skills catalog
-(<https://developer.nvidia.com/blog/nvidia-verified-agent-skills-...>);
+(<https://developer.nvidia.com/blog/nvidia-verified-agent-skills-provide-capability-governance-for-ai-agents/>);
 the signature envelope is the same OpenSSF Model Signing format
 NVIDIA uses (`https://github.com/sigstore/model-transparency`).
 

cli/README.md

@@ -192,6 +192,7 @@ Every template sparse-clones the matching sample from `cli/samples.json` into th
 | `assistant` | `spring-boot-personal-assistant` | Long-lived memory-bearing assistant: AgentState + AgentWorkspace + AgentIdentity + ProtocolBridge |
 | `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 |
+| `browser-agent` | `spring-boot-browser-agent` | Code-as-action agent — the model writes Playwright that drives a headless browser in an isolated sandbox container; screenshots stream to the Console live (requires Docker) |
 
 ⭐ marks the five **flagship enterprise templates** — the canonical agent
 shapes most teams reach for first. Each one is a real sample with a working

modules/adk/README.md

@@ -23,7 +23,7 @@ Browser ← WS/SSE/gRPC → Broadcaster ← AdkEventAdapter ← Flowable<Event>
 <dependency>
     <groupId>com.google.adk</groupId>
     <artifactId>google-adk</artifactId>
-    <version>4.0.54</version>
+    <version>1.2.0</version>
 </dependency>
 ```
 

modules/ai/README.md

@@ -64,7 +64,7 @@ Capability flags advertise a coarse contract: "this runtime cooperates with the
 
 If a per-runtime cell needs a caveat, document it in the row footnote (Spring AI Alibaba already does for buffered streaming) rather than weakening the capability semantics across all rows.
 
-**Spring AI Alibaba runtime — Spring Boot 3 only today.** Spring AI Alibaba `1.1.2.0` is compiled against Spring AI `1.1.2` and `spring-ai-alibaba-graph-core-1.1.2.0` hardcodes references to Spring AI 1.1.2-only types (e.g. `org.springframework.ai.deepseek.DeepSeekAssistantMessage`), so the runtime requires Spring AI 1.1.2 on the classpath. Spring AI 1.1.2 in turn requires Spring Boot 3 (it references the SB3-era FQN `org.springframework.boot.autoconfigure.web.client.RestClientAutoConfiguration`; Spring Boot 4 has the same class but at the renamed FQN `org.springframework.boot.restclient.autoconfigure.RestClientAutoConfiguration`). Net result: `atmosphere-spring-ai-alibaba` runs end-to-end on Spring Boot 3 today (verified via chrome-devtools through the bundled Console against Ollama, qwen2.5:0.5b round-trip succeeded); a Spring Boot 4 path will become possible once Alibaba publishes a Spring AI 2.x-aligned `spring-ai-alibaba-agent-framework`. Forcing Spring AI 2.0.0-M6 across the classpath today fails at `ReactAgent` construction with `NoClassDefFoundError`. AgentScope (`atmosphere-agentscope`) is unaffected — it builds its OpenAI-compatible client through `AiConfig` directly and is validated end-to-end on Spring Boot 4.
+**Spring AI Alibaba runtime — Spring Boot 3 only today.** Spring AI Alibaba `1.1.2.0` is compiled against Spring AI `1.1.2` and `spring-ai-alibaba-graph-core-1.1.2.0` hardcodes references to Spring AI 1.1.2-only types (e.g. `org.springframework.ai.deepseek.DeepSeekAssistantMessage`), so the runtime requires Spring AI 1.1.2 on the classpath. Spring AI 1.1.2 in turn requires Spring Boot 3 (it references the SB3-era FQN `org.springframework.boot.autoconfigure.web.client.RestClientAutoConfiguration`; Spring Boot 4 has the same class but at the renamed FQN `org.springframework.boot.restclient.autoconfigure.RestClientAutoConfiguration`). Net result: `atmosphere-spring-ai-alibaba` runs end-to-end on Spring Boot 3 today (verified via chrome-devtools through the bundled Console against Ollama, qwen2.5:0.5b round-trip succeeded); a Spring Boot 4 path will become possible once Alibaba publishes a Spring AI 2.x-aligned `spring-ai-alibaba-agent-framework`. Forcing Spring AI 2.0.0 across the classpath today fails at `ReactAgent` construction with `NoClassDefFoundError`. AgentScope (`atmosphere-agentscope`) is unaffected — it builds its OpenAI-compatible client through `AiConfig` directly and is validated end-to-end on Spring Boot 4.
 
 ### AiInterceptor
 
@@ -280,7 +280,7 @@ enforcement when the upstream library exposes a mappable knob.
 | Built-in (`BuiltInAgentRuntime`) | ✓ native | ✓ native | `OpenAiCompatibleClient.doStreamWithToolLoop` reads `ChatCompletionRequest.toolLoopPolicy()` every iteration |
 | Koog (`KoogAgentRuntime`) | ✓ native + guard | ✓ native | `executeWithAgent` reads `ToolLoopPolicies.fromOrDefault(ctx)` and translates to `AIAgent.maxIterations × 2` (Koog counts LLM rounds + tool steps) |
 | LangChain4j (`LangChain4jAgentRuntime`) | ✓ via guard | hint via sidecar (caller-controlled) | When the caller routes through the `LangChain4jAiServices` sidecar, the cap lives on `AiServices.builder().maxSequentialToolsInvocations(int).build()` (set once at construction) |
-| Spring AI (`SpringAiAgentRuntime`) | ✓ via guard | hint only — falls through to Spring AI default | Spring AI 2.0.0-M6 exposes `OpenAiChatModel.Builder.toolExecutionEligibilityPredicate(...)` at ChatModel construction time (not per-request); per-request wiring would require Atmosphere to wrap user-supplied ChatModels |
+| Spring AI (`SpringAiAgentRuntime`) | ✓ via guard | hint only — falls through to Spring AI default | Spring AI 2.0.0 exposes `OpenAiChatModel.Builder.toolExecutionEligibilityPredicate(...)` at ChatModel construction time (not per-request); per-request wiring would require Atmosphere to wrap user-supplied ChatModels |
 | Spring AI Alibaba | ✓ via guard | hint only | Inherits Spring AI's lack of per-request knob. `ReactAgent` and Alibaba's `RunnableConfig` do not expose an iteration cap |
 | ADK (`AdkAgentRuntime`) | ✓ via guard | hint only — native wiring planned | ADK 1.0.0 ships `LlmAgent.Builder.maxSteps(int)` at agent construction. Native per-request wiring (rebuild leaf `LlmAgent` per request, or counting `BeforeModelCallback` reading session state) is tractable but not yet implemented |
 | Semantic Kernel (`SemanticKernelAgentRuntime`) | ✓ via guard | hint only | SK 1.4.0 `ToolCallBehavior.getMaximumAutoInvokeAttempts()` is a getter only; the constructor and `allowAllKernelFunctions(...)` factory chain do not accept a max-attempts integer. Subclassing requires reflection on package-private fields |

modules/rag/README.md

@@ -162,7 +162,7 @@ Add Spring AI to your dependencies:
 <dependency>
     <groupId>org.springframework.ai</groupId>
     <artifactId>spring-ai-vector-store</artifactId>
-    <version>4.0.54</version>
+    <version>2.0.0</version>
 </dependency>
 ```
 
@@ -185,7 +185,7 @@ Add LangChain4j to your dependencies:
 <dependency>
     <groupId>dev.langchain4j</groupId>
     <artifactId>langchain4j-core</artifactId>
-    <version>4.0.54</version>
+    <version>1.15.0</version>
 </dependency>
 ```
 

modules/spring-ai/README.md

@@ -82,4 +82,4 @@ across all runtimes.
 
 - Java 21+
 - `atmosphere-ai` (transitive)
-- Spring AI 2.0.0-M6+
+- Spring AI 2.0.0+

modules/wasync/README.md

@@ -107,7 +107,7 @@ Connect to an Atmosphere gRPC server using bidirectional streaming. Requires `at
 <dependency>
     <groupId>io.grpc</groupId>
     <artifactId>grpc-netty-shaded</artifactId>
-    <version>4.0.54</version>
+    <version>1.81.0</version>
 </dependency>
 ```