docs(tutorials): chapter-by-chapter drift + cross-ref pass

10 fixes "six runtimes" → "seven" (Semantic Kernel). 12 adds OutputLengthZScoreGuardrail tenant partition note, new CostCeilingGuardrail section with TokenPricing + CostAccountingSession wiring, updates the "Together" summary. 14 adds Admin control plane section (triple-gate, favicon, read-auth flag). 15 adds Admin extension section (X-Atmosphere-Auth principal, AdminReadAuthFilter, UT000048 workaround). 17 adds Companion reattach section (RunRegistry + X-Atmosphere-Run-Id + ownership check). 18 adds Business-outcome MDC subsection cross-referencing Chapter 27.

Author: jfarcand

docs/src/content/docs/tutorial/10-ai-tools.md

@@ -503,7 +503,7 @@ The canonical tool-calling sample is:
 
 - **[`samples/spring-boot-ai-tools/`](https://github.com/Atmosphere/atmosphere/tree/main/samples/spring-boot-ai-tools)** — uses the built-in LLM client with `@AiTool` methods (`AssistantTools`), conversation memory, and the `CostMeteringInterceptor`. Run with: `./mvnw spring-boot:run -pl samples/spring-boot-ai-tools`
 
-Because `@AiTool` definitions are framework-agnostic, the same `AssistantTools` class works with any of the six runtimes (built-in, Spring AI, LangChain4j, ADK, Embabel, Koog) by swapping the adapter dependency.
+Because `@AiTool` definitions are framework-agnostic, the same `AssistantTools` class works with any of the seven runtimes (built-in, Spring AI, LangChain4j, ADK, Embabel, Koog, Semantic Kernel) by swapping the adapter dependency.
 
 ## Summary
 

docs/src/content/docs/tutorial/12-ai-filters.md

@@ -245,6 +245,136 @@ Register guardrails on an endpoint:
 @AiEndpoint(path = "/chat", guardrails = {PiiGuardrail.class})
 ```
 
+## Built-in guardrails
+
+Two zero-dep guardrails ship in `org.atmosphere.ai.guardrails`. Both
+resolve through the framework-scoped wiring pattern (Spring bean
+bridge → `ServiceLoader` → annotation — same order
+`FactResolver` uses), so an annotation-declared `@AiEndpoint` picks
+up Spring-registered beans automatically.
+
+### PiiRedactionGuardrail
+
+Regex-based detection of email, phone, credit card number, US SSN,
+and IPv4 in both requests and responses.
+
+**Request path** (default mode) returns `Modify` with a redacted
+message — the model never sees the raw PII. `.blocking()` switches
+to `Block` on match.
+
+**Response path** Blocks on match in both modes. This is an **early
+termination**, not a retroactive redaction — by the time the guardrail
+sees the accumulated response, earlier tokens have already streamed
+to the client. Blocking suppresses *subsequent* tokens and surfaces a
+`SecurityException` on the session; it does not unsend bytes already
+on the wire. For synchronous per-token scrubbing use
+`PiiRedactionFilter` (covered earlier in this page under
+"PiiRedactionFilter") — it runs inside the broadcaster chain and
+rewrites each text frame before it is sent. The guardrail here is a
+safety net that halts the leak before more PII flows and writes the
+hit to the audit log.
+
+Enable via Spring property (recommended):
+
+```properties
+atmosphere.ai.guardrails.pii.enabled=true
+# Optional — default is redact-on-request, block-on-response
+atmosphere.ai.guardrails.pii.blocking=true
+```
+
+Or via annotation:
+
+```java
+@AiEndpoint(path = "/chat",
+            guardrails = { PiiRedactionGuardrail.class })
+```
+
+Patterns bundled:
+
+| Kind     | Example input                | Replacement          |
+|----------|------------------------------|----------------------|
+| email    | `alice@example.com`          | `[redacted-email]`   |
+| phone    | `(555) 123-4567`             | `[redacted-phone]`   |
+| us-ssn   | `123-45-6789`                | `[redacted-us-ssn]`  |
+| credit   | `4111 1111 1111 1111`        | `[redacted-card]`    |
+| ipv4     | `203.0.113.42`               | `[redacted-ip]`      |
+
+Extend by subclassing and adding patterns before calling `super`.
+
+### OutputLengthZScoreGuardrail
+
+Statistical drift detector. Maintains a rolling window of response
+lengths and Blocks any response whose length is more than N standard
+deviations above the window mean. Catches runaway prompts and
+injection payloads that balloon responses without a specific
+signature.
+
+```properties
+atmosphere.ai.guardrails.drift.enabled=true
+atmosphere.ai.guardrails.drift.window-size=50
+atmosphere.ai.guardrails.drift.z-score-threshold=3.0
+atmosphere.ai.guardrails.drift.min-samples=10
+```
+
+The first `min-samples` responses always pass — the guardrail needs a
+baseline before it can flag an outlier. A falling hit rate means the
+model's output distribution is stabilizing; a rising rate is a
+regression signal worth investigating.
+
+**Multi-tenant deployments** — the rolling window partitions by the
+`business.tenant.id` MDC tag (populated by the Business Metadata
+bridge — see [Chapter 27](./27-business-metadata-observability/)).
+A noisy tenant cannot poison another tenant's baseline. Turns without
+a tenant tag share a shared `__default__` bucket, so single-tenant
+apps behave unchanged.
+
+### CostCeilingGuardrail
+
+Blocks outbound `@Prompt` dispatch when a tenant's cumulative LLM
+cost hits a configured budget. Closes the
+observability→enforcement loop: you tag tenants via
+`BusinessMetadata`, the built-in `CostCeilingAccountant` meters
+`TokenUsage` from every runtime, and this guardrail stops the next
+request before it spends more.
+
+```java
+@Bean
+CostCeilingGuardrail costCeiling() {
+    return new CostCeilingGuardrail(/* per-tenant budget USD */ 100.00);
+}
+
+@Bean
+TokenPricing openAiPricing() {
+    // Your provider's per-model input/output dollar-per-token rates.
+    return (usage, model) -> switch (model) {
+        case "gpt-4o" -> usage.inputTokens() * 0.0000025
+                      + usage.outputTokens() * 0.00001;
+        default        -> 0.0;
+    };
+}
+```
+
+Spring Boot auto-wires the `CostAccountingSession` decorator when
+both beans are present: every `@Prompt` session's `TokenUsage` event
+flows into `addCost(tenantId, dollars)` keyed by the same
+`business.tenant.id` MDC tag the drift guardrail uses. Reset
+counters on a monthly boundary via `resetTenant(...)` /
+`resetAll()`.
+
+Request-side blocks surface on the session as a `SecurityException`
+with the reason string `cost ceiling reached for tenant X (spent Y
+of budget Z)`, so the client sees a terminal error envelope rather
+than an infinite hang.
+
+### Together
+
+Register all three in a production deployment — PII for compliance
+(blocks the leak), drift for incident detection (flags a model
+behaving badly), cost ceiling for spend enforcement (halts a runaway
+tenant before the next invoice). None is on by default: the
+framework's position is that a guardrail that fires unexpectedly is
+worse than no guardrail at all, so you opt in explicitly.
+
 ## Model routing
 
 The `ModelRouter` interface (in `org.atmosphere.ai`) mirrors Atmosphere's transport failover pattern (WebSocket -> SSE -> long-polling) applied to the AI layer (GPT-4 -> Claude -> Gemini).

docs/src/content/docs/tutorial/14-spring-boot.md

@@ -48,6 +48,27 @@ Spring Boot's embedded containers do not process `@HandlesTypes` from `ServletCo
 
 The starter also performs a second pass to discover custom annotation types registered via `@AtmosphereAnnotation` processors (e.g., the AI module's `@AiEndpoint` processor), and re-scans user packages for classes annotated with those custom annotations.
 
+### Admin control plane
+
+When `atmosphere-admin` is on the classpath, the starter also registers
+`AtmosphereAdminEndpoint` under `/api/admin/*` (read endpoints open by
+default, write endpoints triple-gated: feature flag → Principal →
+`ControlAuthorizer`), plus `AtmosphereFaviconAutoConfiguration` which
+serves `/favicon.ico` and `/favicon.png` with the framework logo so
+browsers stop logging a 404 on the admin dashboard and every sample.
+
+Two opt-in flags you'll want to know about:
+
+| Property | Default | Effect |
+|----------|---------|--------|
+| `atmosphere.admin.http-write-enabled` | `false` | Enables `POST` / `DELETE` on `/api/admin/*`; still requires a Principal + `ControlAuthorizer` grant. |
+| `atmosphere.admin.http-read-auth-required` | `false` | Requires the same principal chain (minus `ControlAuthorizer`) for `GET` / `HEAD` / `OPTIONS`. Flip for multi-tenant deployments exposing `/api/admin/*` on a routable network. |
+| `atmosphere.favicon.enabled` | `true` | Set to `false` if the application ships its own `/favicon.ico`. |
+
+See [Chapter 29 — Agent-to-Agent Flow Viewer](./29-admin-flow-viewer/)
+and [`modules/admin/README.md`](https://github.com/Atmosphere/atmosphere/blob/main/modules/admin/README.md)
+for the full admin surface and principal-chain wiring.
+
 ## Application class
 
 The application class is a standard Spring Boot entry point:

docs/src/content/docs/tutorial/15-quarkus.md

@@ -164,6 +164,35 @@ The extension supports Quarkus dev mode (`quarkus:dev`) with live reload. The `A
 | Config phase | Runtime | `BUILD_AND_RUN_TIME_FIXED` |
 | SCI handling | Overridden via servlet context attribute | Suppressed via `IgnoredServletContainerInitializerBuildItem` |
 
+## Admin extension
+
+`atmosphere-quarkus-admin-extension` mirrors the Spring `/api/admin/*`
+surface for Quarkus apps, with three Quarkus-shaped deltas:
+
+- **Fourth principal source** — on top of the Spring chain
+  (`SecurityContext` → `org.atmosphere.auth.principal` attribute →
+  `ai.userId` attribute), `AdminResource` also accepts the
+  `X-Atmosphere-Auth` header and validates it constant-time against
+  `atmosphere.admin.auth.token`. Intended for sample fixtures and
+  operator tooling that haven't integrated Jakarta Security yet;
+  production stacks still resolve Jakarta Security first.
+- **`AdminReadAuthFilter`** — Quarkus JAX-RS `@Provider` that
+  enforces the same `atmosphere.admin.http-read-auth-required`
+  opt-in flag as the Spring `AdminApiAuthFilter`. Default off;
+  multi-tenant operators flip it when exposing `/api/admin/*` on a
+  routable network.
+- **Vert.x dispatch** — `resteasy-reactive` runs on Vert.x, so
+  servlet attribute access throws `IllegalStateException: UT000048`.
+  `AdminResource` guards against this and reads `X-Atmosphere-Auth`
+  via `@Context HttpHeaders`, which works on both servlet and
+  reactive transports.
+
+Everything else matches the Spring starter one-for-one — triple-gate
+writes, audit log, `ControlAuthorizer` bean resolution via CDI (the
+Quarkus `AdminProducer` looks up a user-supplied `ControlAuthorizer`
+bean before falling back to `REQUIRE_PRINCIPAL`), and the MCP-tool
+admin surface when `atmosphere-mcp` is also on the classpath.
+
 ## Running the sample
 
 The `quarkus-chat` sample demonstrates a complete chat application:

docs/src/content/docs/tutorial/17-durable-sessions.md

@@ -234,6 +234,35 @@ Two implementations are provided:
 
 These share the same backend connections as the corresponding `SessionStore` implementations. The `PersistentConversationMemory` class handles serialization and sliding-window logic on top of the persistence SPI.
 
+## Companion: mid-stream reattach for `@Prompt` runs
+
+Durable sessions restore room + broadcaster memberships after a
+disconnect — the client sees the same presence and subscriptions it
+had before. But an `@Prompt` that was *actively streaming* when the
+client dropped needs a parallel mechanism: the buffered events the
+client didn't finish receiving.
+
+That's what `RunRegistry` + `X-Atmosphere-Run-Id` do. On every
+`@Prompt` dispatch `AiEndpointHandler` registers a run with an
+`AgentResumeHandle` and returns the run id as the
+`X-Atmosphere-Run-Id` response header. `RunEventCapturingSession`
+mirrors every `session.send` / `complete` / `error` into the run's
+bounded `RunEventReplayBuffer`. When the client reconnects carrying
+the run id, `RunReattachSupport.replayPendingRun` drains the buffer
+onto the new resource so the user catches up on the tokens they
+missed — routed through the broadcaster's filter chain so
+`PiiRedactionFilter` applies identically to replay and live frames.
+
+`DurableSessionInterceptor` stashes the header into the request
+attribute `org.atmosphere.session.runId` so `AiEndpointHandler.onReady`
+sees it without a compile-time dependency on the durable-sessions
+module.
+
+Ownership is enforced: replay refuses when the reconnecting caller's
+`userId` does not match the run's registered `userId`, so a bearer
+token leak cannot replay someone else's conversation. Anonymous runs
+keep the open-mode carve-out for demo deployments.
+
 ## Combining with Clustering
 
 Durable sessions and clustering serve different purposes and work well together:

docs/src/content/docs/tutorial/18-observability.md

@@ -309,6 +309,27 @@ framework.interceptor(new MDCInterceptor());
 
 MDC keys are automatically included as top-level fields in JSON layouts (logstash-logback-encoder, logback-contrib).
 
+### Business-outcome MDC for AI calls
+
+When `atmosphere-ai` is on the classpath, `AiEndpointHandler` layers a
+second MDC snapshot on top of the transport-level keys above. For
+every `@Prompt` turn it publishes the `business.*` keys
+(`tenant.id`, `customer.id`, `customer.segment`, `session.revenue`,
+`session.cost`, `session.currency`, `session.id`, `event.kind`,
+`event.subject`) onto the dispatching virtual thread and clears them
+in `finally`. Any log record emitted during the turn — pipeline,
+runtime, tool calls, guardrails — carries the tags, so Dynatrace /
+Datadog / OpenTelemetry log exporters can join LLM cost and latency
+against per-tenant KPIs without a separate correlation pipeline.
+
+Performance of the snapshot → apply → clear cycle is pinned by
+`BusinessMdcBenchmark` in `modules/benchmarks` (JMH, baseline vs.
+six-key production vs. empty-snapshot) so regressions on the hot
+path show as numbers.
+
+See [Chapter 27 — Tag agent calls with business outcomes](/docs/tutorial/27-business-metadata-observability/)
+for the complete wiring and exporter integration.
+
 ## BackpressureInterceptor
 
 The `BackpressureInterceptor` protects against slow consumers by limiting the number of pending messages per client: