opencode-effect-enforcer 0.2.8 → 0.3.0

package/skills/effect-ai-streaming/SKILL.md

@@ -5,6 +5,10 @@ description: Master Effect AI streaming response patterns including start/delta/
 
 # Effect AI Streaming
 
+Baseline: `effect@4.0.0`; inspect that tag in the Effect source reference.
+The `effect/ai` APIs remain `@stability unstable` despite their shorter import
+paths and may break in minor releases. Align provider package versions with `effect`.
+
 ## When to Use This Skill
 
 - Real-time streaming responses from language models
@@ -24,7 +28,7 @@ import * as Effect from 'effect/Effect';
 import * as Channel from 'effect/Channel';
 import * as SubscriptionRef from 'effect/SubscriptionRef';
 import * as Match from 'effect/Match';
-import * as Response from 'effect/unstable/ai/Response';
+import * as Response from 'effect/ai/Response';
 ```
 
 ## StreamPart Protocol
@@ -80,8 +84,8 @@ Accumulate stream parts incrementally using mutable state for efficiency:
 ```typescript
 import * as Stream from 'effect/Stream';
 import * as Effect from 'effect/Effect';
-import * as Prompt from 'effect/unstable/ai/Prompt';
-import * as Response from 'effect/unstable/ai/Response';
+import * as Prompt from 'effect/ai/Prompt';
+import * as Response from 'effect/ai/Response';
 import * as SubscriptionRef from 'effect/SubscriptionRef';
 
 const streamWithHistory = Stream.suspend(() => {
@@ -214,14 +218,20 @@ Why checkpoint-based merging:
 - `Prompt.fromResponseParts` routes framework-executed final results into a tool message, but keeps provider-executed final results in the assistant message. It preserves `providerExecuted` and uses `encodedResult` in both cases.
 - Tools requiring approval emit `tool-approval-request`. Append a matching `Prompt.toolApprovalResponsePart` in a tool message and call the model again; approved/denied responses are pre-resolved into final tool results before the next provider call.
 - In OpenAI-specific SSE code, unknown future events decode through `OpenAiSchema.ResponseStreamEvent` and are ignored by `OpenAiLanguageModel`; malformed known events still fail decoding.
+- OpenAI-compatible Chat Completions providers can send null delta fields. The
+  adapter preserves text and tool arguments from the remaining fields; custom
+  adapters should skip null fragments rather than discard the whole chunk.
+- Manual `Toolkit.handle` execution requires handler services on both the outer
+  Effect and its returned Stream. Even return-mode streams can fail with
+  `AiError` during result encoding; keep that error channel when composing streams.
 
 ## Complete Example
 
 <!-- typecheck -->
 ```typescript
-import * as Prompt from 'effect/unstable/ai/Prompt';
-import * as Response from 'effect/unstable/ai/Response';
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as Prompt from 'effect/ai/Prompt';
+import * as Response from 'effect/ai/Response';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import * as Stream from 'effect/Stream';
 import * as Channel from 'effect/Channel';
 import * as Effect from 'effect/Effect';
@@ -327,16 +337,21 @@ Stream.mapArrayEffect(Effect.fnUntraced(function* (chunk) {
 ### Source Parts
 
 ```typescript
-{ type: "document-source", id: string, title?: string }
-{ type: "url-source", url: string, title?: string }
+{ type: "source", sourceType: "document", id: string, mediaType: string, title: string }
+{ type: "source", sourceType: "url", id: string, url: URL, title: string }
 ```
 
+The encoded URL source uses a string URL.
+
 ### Metadata Parts
 
 ```typescript
-{ type: "response-metadata", id: string, modelId: string, timestamp: Date }
+{ type: "response-metadata", id?: string, modelId?: string, timestamp?: DateTime.Utc }
 ```
 
+The encoded provider form uses an ISO string for `timestamp`; the decoded part
+uses `DateTime.Utc`.
+
 ### Error Parts
 
 ```typescript
@@ -383,9 +398,9 @@ StreamPart types:
 
 Key modules:
 
-- `effect/unstable/ai/Response` - Response part schemas and constructors
-- `effect/unstable/ai/Prompt` - Prompt construction and merging
-- `effect/Stream` - Stream combinators (`mapChunksEffect`, `runForEach`, `runDrain`)
+- `effect/ai/Response` - Response part schemas and constructors
+- `effect/ai/Prompt` - Prompt construction and merging
+- `effect/Stream` - Stream combinators (`mapArrayEffect`, `runForEach`, `runDrain`)
 - `effect/Channel` - Low-level resource management (`acquireUseRelease`)
 - `effect/SubscriptionRef` - Reactive shared state
 - `effect/Match` - Pattern matching (use `Match.when({ type: ... })` for stream parts)

package/skills/effect-ai-tool/SKILL.md

@@ -9,7 +9,11 @@ Use this skill when implementing tools for AI language models using the Effect A
 
 ## Effect AI Documentation Access
 
-For comprehensive Effect AI documentation, view the Effect v4 repository at `packages/ai/`
+For core AI APIs inspect `packages/effect/src/ai/` at `effect@4.0.0` in the
+Effect source reference; provider implementations live under `packages/ai/`.
+Keep all Effect-family packages on the same version. These APIs are tagged
+`@stability unstable`, so minor releases may break them despite stable-looking
+import paths.
 
 Reference this for:
 
@@ -83,7 +87,7 @@ Use this pattern when the surrounding framework wants an async callback surface
 ### Basic Tool Definition
 
 ```typescript
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as Tool from 'effect/ai/Tool';
 import * as Schema from 'effect/Schema';
 
 const GetCurrentTime = Tool.make('GetCurrentTime', {
@@ -107,7 +111,7 @@ type Result = Tool.Success<typeof GetCurrentTime>;
 If you have an existing domain schema you want to use as a tool, create the tool with `Tool.make` and reference the schema directly:
 
 ```typescript
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as Tool from 'effect/ai/Tool';
 import * as Schema from 'effect/Schema';
 
 const UserResult = Schema.Struct({
@@ -139,7 +143,7 @@ type Success = Tool.Success<typeof GetUserTool>;
 ### Tool with Parameters
 
 ```typescript
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as Tool from 'effect/ai/Tool';
 import { Schema } from 'effect';
 
 const GetWeather = Tool.make('GetWeather', {
@@ -169,7 +173,7 @@ type Success = Tool.Success<typeof GetWeather>;
 ### Tool with Failure Handling
 
 ```typescript
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as Tool from 'effect/ai/Tool';
 import { Schema } from 'effect';
 
 class UserNotFound extends Schema.TaggedError<UserNotFound>()(
@@ -196,10 +200,7 @@ const FindUser = Tool.make('FindUser', {
 		name: Schema.String,
 		email: Schema.String
 	}),
-	failure: Schema.Union([
-		Schema.instanceOf(UserNotFound),
-		Schema.instanceOf(DatabaseError)
-	]),
+	failure: Schema.Union([UserNotFound, DatabaseError]),
 	failureMode: 'error'
 });
 
@@ -222,12 +223,14 @@ annotation and `Tool.FailureOrigin` type. Keep validation, declared handler, and
 internal failures distinct when presenting or reporting them.
 
 - `"error"` (default): Failures go to Effect error channel
-- `"return"`: Failures returned as tool result (captured, not thrown)
+- `"return"`: Parameter and handler failures become failed tool results. Result
+  encoding can still fail the returned Stream with `AiError`; return mode does
+  not make stream consumption infallible.
 
 ### Tool with Service Dependencies
 
 ```typescript
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as Tool from 'effect/ai/Tool';
 import * as Context from 'effect/Context';
 import { Schema } from 'effect';
 
@@ -261,8 +264,8 @@ type Requirements = Tool.HandlerServices<typeof QueryDatabase>;
 ### Basic Toolkit
 
 ```typescript
-import * as Toolkit from 'effect/unstable/ai/Toolkit';
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as Toolkit from 'effect/ai/Toolkit';
+import * as Tool from 'effect/ai/Tool';
 import { Effect, Schema } from 'effect';
 
 const GetCurrentTime = Tool.make('GetCurrentTime', {
@@ -473,7 +476,7 @@ Keep static descriptions on the tool for invariant behavior. Put runtime-specifi
 ### Merging Toolkits
 
 ```typescript
-import * as Toolkit from 'effect/unstable/ai/Toolkit';
+import * as Toolkit from 'effect/ai/Toolkit';
 
 const mathToolkit = Toolkit.make(
 	Tool.make('add', {
@@ -510,7 +513,7 @@ type AllTools = Toolkit.Tools<typeof combined>;
 ### Basic Provider Tool
 
 ```typescript
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as Tool from 'effect/ai/Tool';
 import { Schema } from 'effect';
 
 const AnthropicBash = Tool.providerDefined({
@@ -557,7 +560,7 @@ const nativeTools = Toolkit.make(
 ### Provider Tool with Handler
 
 ```typescript
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as Tool from 'effect/ai/Tool';
 import { Schema } from 'effect';
 
 const WebSearch = Tool.providerDefined({
@@ -614,7 +617,7 @@ declare const performSearch: (query: string) => Effect.Effect<
 ### Understanding ToolCallPart and ToolResultPart
 
 ```typescript
-import * as Prompt from 'effect/unstable/ai/Prompt';
+import * as Prompt from 'effect/ai/Prompt';
 
 const toolCallPart = Prompt.makePart('tool-call', {
 	id: 'call_123',
@@ -725,8 +728,14 @@ const toolkitLayer = LongRunningToolkit.toLayer({
 
 **Key Pattern: toolkit.handle**
 
-- `toolkit.handle(name, params, toolCallId?)` accepts `Tool.ParametersEncoded<Tool>` and returns `Effect<Stream<HandlerResult<Tool>>>`
+- `toolkit.handle(name, params, toolCallId?, options?)` accepts
+  `Tool.ParametersEncoded<T>` and optional schema parse options. Its full shape is
+  `Effect<Stream<HandlerResult<T>, Tool.HandlerError<T> | AiError, Tool.HandlerServices<T>>, AiError, Tool.HandlerServices<T>>`.
 - `handle` decodes the encoded input with the tool's parameter schema before invoking the handler; the handler still receives `Tool.Parameters<Tool>`
+- Provide handler services to the outer Effect as well as the Stream. A
+  service-dependent parameter decoder runs before the Stream exists; providing
+  services only around `Stream.runCollect` is too late. Consuming the Stream
+  inside the same provided `Effect.gen` keeps both stages wired.
 - The optional call ID is forwarded to the handler as `context.toolCallId`
 - `preliminary: true`: progress update; do not persist as final history
 - `preliminary: false`: final result to send/persist
@@ -760,7 +769,7 @@ Passing the decoded `{ times: 3 }` directly to `handle` is now a type error. Use
 ### Tool Annotations
 
 ```typescript
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as Tool from 'effect/ai/Tool';
 import { Schema } from 'effect';
 
 const ReadOnlyQuery = Tool.make('query', {
@@ -786,7 +795,7 @@ MCP emits the first four annotations as tool hints. They are hints, not authoriz
 ### JSON Schema Generation
 
 ```typescript
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as Tool from 'effect/ai/Tool';
 
 const tool = Tool.make('example', {
 	parameters: Schema.Struct({
@@ -815,7 +824,7 @@ const jsonSchema = Tool.getJsonSchema(tool);
 ### Tool Guards
 
 ```typescript
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as Tool from 'effect/ai/Tool';
 
 const userTool = Tool.make('example');
 const providerTool = Tool.providerDefined({
@@ -858,8 +867,8 @@ const executeTool = (toolName: string, params: unknown) =>
 
 <!-- typecheck -->
 ```typescript
-import * as Tool from 'effect/unstable/ai/Tool';
-import * as Toolkit from 'effect/unstable/ai/Toolkit';
+import * as Tool from 'effect/ai/Tool';
+import * as Toolkit from 'effect/ai/Toolkit';
 import * as Schema from 'effect/Schema';
 import { Clock, Context, Effect, Layer, Stream } from 'effect';
 
@@ -946,9 +955,9 @@ manual `handle` calls accept their encoded representation.
 **CRITICAL**: Always use namespace imports:
 
 ```typescript
-import * as Tool from 'effect/unstable/ai/Tool';
-import * as Toolkit from 'effect/unstable/ai/Toolkit';
-import * as Prompt from 'effect/unstable/ai/Prompt';
+import * as Tool from 'effect/ai/Tool';
+import * as Toolkit from 'effect/ai/Toolkit';
+import * as Prompt from 'effect/ai/Prompt';
 import { Schema, Effect, Data, Context, Layer } from 'effect';
 
 const myTool = Tool.make('example');
@@ -958,8 +967,8 @@ const myToolkit = Toolkit.make(myTool);
 **NEVER** do this:
 
 ```typescript
-import { make } from 'effect/unstable/ai/Tool';
-import { make as makeToolkit } from 'effect/unstable/ai/Toolkit';
+import { make } from 'effect/ai/Tool';
+import { make as makeToolkit } from 'effect/ai/Toolkit';
 ```
 
 ## Quality Checklist

package/skills/effect-atom-rpc/SKILL.md

@@ -3,7 +3,11 @@ name: effect-atom-rpc
 description: Build reactive Atom-aware RPC clients for React/Atom UIs using AtomRpc. Provides cached query atoms, invalidating mutation atoms, SSR hydration, and reactivity-key invalidation on top of an RpcGroup.
 ---
 
-You are an Effect TypeScript expert specializing in `effect/unstable/reactivity/AtomRpc` — the reactive RPC client for Atom-driven frontends.
+You are an Effect TypeScript expert specializing in `effect/reactivity/AtomRpc` — the reactive RPC client for Atom-driven frontends.
+
+Baseline: `effect@4.0.0`; inspect that tag in the Effect source reference.
+Core reactivity APIs are `@stability unstable` and may break in minor releases.
+Use matching Effect-family versions; `@effect/atom-react@4.0.0` requires React 19.
 
 ## When to use this skill
 
@@ -35,13 +39,13 @@ handle them when consuming the stream. An explicit zero `timeToLive` disables
 default idle retention, so unmount/remount may dispose and refetch. Omission uses
 the registry default. HttpApi calls accept per-call `sseOptions`.
 
-- `packages/effect/src/unstable/reactivity/AtomRpc.ts` — the whole API (~270 lines)
+- `packages/effect/src/reactivity/AtomRpc.ts` — the whole API
 - `packages/effect/test/reactivity/AtomRpc.test.ts` — minimal usage + serialization test
-- `packages/effect/src/unstable/reactivity/AtomHttpApi.ts` — the cousin pattern for `HttpApi` (same idea, same options)
-- `packages/effect/src/unstable/reactivity/AsyncResult.ts` — the `AsyncResult` type returned by `query`
-- `packages/effect/src/unstable/reactivity/Atom.ts` — `runtime`, `family`, `serializable`, `keepAlive`, `setIdleTTL`
-- `packages/effect/src/unstable/reactivity/Hydration.ts` — SSR dehydrate/hydrate helpers
-- `packages/effect/src/unstable/reactivity/Reactivity.ts` — the `Reactivity` service that powers reactivity keys
+- `packages/effect/src/reactivity/AtomHttpApi.ts` — the cousin pattern for `HttpApi` (same idea, same options)
+- `packages/effect/src/reactivity/AsyncResult.ts` — the `AsyncResult` type returned by `query`
+- `packages/effect/src/reactivity/Atom.ts` — `runtime`, `family`, `serializable`, `keepAlive`, `setIdleTTL`
+- `packages/effect/src/reactivity/Hydration.ts` — SSR dehydrate/hydrate helpers
+- `packages/effect/src/reactivity/Reactivity.ts` — the `Reactivity` service that powers reactivity keys
 
 ## Imports
 
@@ -52,9 +56,9 @@ import {
 	AtomRpc,
 	Hydration,
 	Reactivity
-} from 'effect/unstable/reactivity';
-import { RpcClient, RpcSerialization } from 'effect/unstable/rpc';
-import { FetchHttpClient } from 'effect/unstable/http';
+} from 'effect/reactivity';
+import { RpcClient, RpcSerialization } from 'effect/rpc';
+import { FetchHttpClient } from 'effect/http';
 import { useAtomValue, useAtomSet } from '@effect/atom-react';
 ```
 
@@ -77,9 +81,9 @@ The `runtime` is what powers `query` and `mutation` — internally it builds a `
 
 ```ts
 import { Layer } from 'effect';
-import { AtomRpc } from 'effect/unstable/reactivity';
-import { FetchHttpClient } from 'effect/unstable/http';
-import { RpcClient, RpcSerialization } from 'effect/unstable/rpc';
+import { AtomRpc } from 'effect/reactivity';
+import { FetchHttpClient } from 'effect/http';
+import { RpcClient, RpcSerialization } from 'effect/rpc';
 import { UsersGroup } from '../shared/users-rpc.ts';
 
 export class UsersClient extends AtomRpc.Service<UsersClient>()('UsersClient', {
@@ -124,7 +128,7 @@ AtomRpc.Service<UsersClient>()('UsersClient', {
 	disableTracing: false,
 	generateRequestId: customRequestIdFactory, // for deterministic IDs in tests
 	makeEffect: undefined, // override the default RpcClient.make
-	runtime: Atom.runtime // override the runtime factory (e.g., Atom.runtime.withReactivity)
+	runtime: Atom.runtime // override with another factory, e.g. Atom.context()
 });
 ```
 
@@ -149,6 +153,11 @@ client.query(tag, payload, options?) =>
 
 Query atoms are **cached by request key** — calling `query('GetUser', { id: '1' })` from many components returns the *same* atom, so the rpc fires once and shares the result.
 
+The key also includes headers, reactivity keys, TTL, and serialization key.
+Use matching options to share a cache entry. Union-of-tag arguments retain the
+selected RPCs' payload/result types; they no longer collapse to `never`. Narrow
+the tag when application logic needs to pair a particular payload with its result.
+
 Effect v4 query wrappers preserve serialization and retention metadata while adding reactivity. It is therefore safe to combine `reactivityKeys`, `serializationKey`, and `timeToLive`; hydration identity and idle retention are not discarded by the reactive wrapper.
 
 ```ts
@@ -184,7 +193,11 @@ client.query(tag, payload, {
 ```
 
 - **`reactivityKeys`** — keys this atom listens to. When a `mutation` (or any `Reactivity.invalidate`) fires with overlapping keys, this atom re-fetches.
-- **`timeToLive`** — `Duration.Input | "infinity"`. With a finite duration, the atom is removed from the cache after that long without subscribers (`Atom.setIdleTTL`). With `Duration.infinity`, the atom is `Atom.keepAlive`'d (never evicted). Without `timeToLive`, the atom resets when the last subscriber unmounts.
+- **`timeToLive`** — idle retention via `Atom.setIdleTTL`. A finite duration permits
+  disposal after inactivity; `Duration.infinity` uses `Atom.keepAlive` until the
+  registry is reset/disposed. Omission uses the registry default, while explicit
+  zero bypasses default idle retention. Freshness is separate: use `Atom.swr` for
+  stale-while-revalidate behavior (see `effect-atom-state`).
 - **`serializationKey`** — for non-stream queries, a stable key opts the atom into `Atom.serializable` keyed by `AtomRpc:${tag}:${serializationKey}`. Without a `serializationKey`, the query atom is cached for the current registry but is not serializable/hydratable, so SSR clients will fetch again. Stream rpcs cannot be serializable.
 
 ### Stream rpcs
@@ -291,25 +304,27 @@ Hydration uses `Atom.serializable` (which `query` opts into when you pass `seria
 
 ```ts
 // --- server: render then dehydrate ---
-import { AtomRegistry, Hydration } from 'effect/unstable/reactivity';
-
-const registry = AtomRegistry.make();
-const userAtom = UsersClient.query('GetUser', { id: 'u1' }, {
-	serializationKey: 'u1'
-});
+import { Effect } from 'effect';
+import { AtomRegistry, Hydration } from 'effect/reactivity';
 
-const unmount = registry.mount(userAtom);
-yield* Effect.yieldNow;
-yield* Effect.yieldNow;
-
-const dehydrated = Hydration.toValues(Hydration.dehydrate(registry));
-unmount();
+const dehydrated = yield* Effect.scoped(Effect.gen(function* () {
+	const registry = yield* Effect.acquireRelease(
+		Effect.sync(() => AtomRegistry.make()),
+		(registry) => Effect.sync(() => registry.dispose())
+	);
+	const userAtom = UsersClient.query('GetUser', { id: 'u1' }, {
+		serializationKey: 'u1'
+	});
+	yield* AtomRegistry.mount(registry, userAtom);
+	yield* AtomRegistry.getResult(registry, userAtom);
+	return Hydration.toValues(Hydration.dehydrate(registry));
+}));
 // dehydrated is a JSON-safe array of { key, value } pairs to inline in the HTML
 ```
 
 ```tsx
 // --- client: hydrate before rendering ---
-import { AtomRegistry, Hydration } from 'effect/unstable/reactivity';
+import { AtomRegistry, Hydration } from 'effect/reactivity';
 import { RegistryContext } from '@effect/atom-react';
 
 const registry = AtomRegistry.make();
@@ -327,7 +342,7 @@ Stream rpcs are not serializable — only non-stream `query` atoms with a stable
 `AtomRpc.Service` accepts a `runtime` factory option. The default is `Atom.runtime`. Override it when you want all the atoms produced by this client to share a custom reactivity scope, registry, or annotation:
 
 ```ts
-const myRuntime = Atom.runtime.withReactivity(['shared-namespace']);
+const myRuntime = Atom.context();
 
 export class UsersClient extends AtomRpc.Service<UsersClient>()('UsersClient', {
 	group: UsersGroup,
@@ -336,12 +351,17 @@ export class UsersClient extends AtomRpc.Service<UsersClient>()('UsersClient', {
 }) {}
 ```
 
+`withReactivity(keys)` decorates an atom; it is not a runtime factory. Use
+`reactivityKeys` on queries/mutations for invalidation. Runtime factories use
+registry-scoped layer memoization by default; provide the same registry to
+components that should share state.
+
 ## End-to-end example
 
 ```ts
 // --- shared/users-rpc.ts ---
 import { Schema } from 'effect';
-import { Rpc, RpcGroup } from 'effect/unstable/rpc';
+import { Rpc, RpcGroup } from 'effect/rpc';
 
 export class User extends Schema.Class<User>('User')({
 	id: Schema.String,
@@ -375,9 +395,9 @@ export const UsersGroup = RpcGroup.make(GetUser, ListUsers, CreateUser);
 ```ts
 // --- frontend/clients/users-client.ts ---
 import { Layer } from 'effect';
-import { FetchHttpClient } from 'effect/unstable/http';
-import { AtomRpc } from 'effect/unstable/reactivity';
-import { RpcClient, RpcSerialization } from 'effect/unstable/rpc';
+import { FetchHttpClient } from 'effect/http';
+import { AtomRpc } from 'effect/reactivity';
+import { RpcClient, RpcSerialization } from 'effect/rpc';
 import { UsersGroup } from '../../shared/users-rpc.ts';
 
 export class UsersClient extends AtomRpc.Service<UsersClient>()('UsersClient', {
@@ -393,7 +413,7 @@ export class UsersClient extends AtomRpc.Service<UsersClient>()('UsersClient', {
 ```tsx
 // --- frontend/components/UserList.tsx ---
 import { useAtomValue, useAtomSet } from '@effect/atom-react';
-import { AsyncResult } from 'effect/unstable/reactivity';
+import { AsyncResult } from 'effect/reactivity';
 import { UsersClient } from '../clients/users-client';
 
 export function UserList() {
@@ -455,7 +475,7 @@ export function UserDetail({ id }: { id: string }) {
 If your backend exposes an `HttpApi` instead of an `RpcGroup`, `AtomHttpApi.Service<Self>()(id, options)` is the same idea applied to `HttpApiGroup`/`HttpApiEndpoint`:
 
 ```ts
-import { AtomHttpApi } from 'effect/unstable/reactivity';
+import { AtomHttpApi } from 'effect/reactivity';
 
 class ApiClient extends AtomHttpApi.Service<ApiClient>()('ApiClient', {
 	api: MyHttpApi,
@@ -494,7 +514,8 @@ The `query`/`mutation` arguments differ (you pass `groupName, endpointName, requ
 - One `AtomRpc.Service` class per logical client; module-singleton, never per-component.
 - Always pass `reactivityKeys` to mutations so dependent queries refresh.
 - Pass `serializationKey` to every query you want SSR-hydratable.
-- Pick `timeToLive` deliberately: short (`'10 seconds'`) for hot data, long (`Duration.infinity`) for reference data, omit for "tear down on unmount".
+- Pick idle `timeToLive` deliberately; omit for registry defaults, zero to bypass
+  default idle retention, or `Duration.infinity` to retain until registry disposal.
 - Use `AsyncResult.builder(...).onWaiting(...).onError(...).onSuccess(...)` (or `AsyncResult.matchWithWaiting`) to render — never check `.waiting` and `.error` ad-hoc. Reserve `.onFailure((cause) => ...)` for whole-`Cause` fallbacks after typed error branches.
 - For protocol layers that depend on auth tokens or other reactive state, use the `(get) => Layer` form of `protocol` so the client rebuilds when those atoms change.
 - For typed error recovery, handle declared RPC errors, RPC middleware wire errors, and `RpcClientError`; branch on `_tag` only when the relevant errors are tagged.