opencode-effect-enforcer 0.2.6 → 0.3.0

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.

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

@@ -7,20 +7,20 @@ description: Implement reactive state management with Effect Atom for React appl
 
 Effect Atom is a reactive state management library for Effect that seamlessly integrates with React.
 
-`@effect/atom-react` supports React `>=19.0.0 <20.0.0` (the peer range
-was relaxed). This does not add React 18 support. Keep the adapter aligned with
-the Effect release; core atoms still live in `effect/unstable/reactivity`, and
+`@effect/atom-react@4.0.0` requires React `>=19.0.0 <20.0.0`.
+Keep the adapter at the same version as `effect`; core atoms live in `effect/reactivity`, and
 React bindings live in `@effect/atom-react` (`packages/atom/react` upstream).
+Core reactivity APIs carry `@stability unstable` and may break in minor releases.
 
 ## Effect Source Reference
 
 The Effect v4 source is available at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`.
-Browse and read files there directly to look up APIs, types, and implementations.
+Inspect `git show effect@4.0.0:<path>` there for this baseline; main may be ahead.
 
 Reference this for:
 
-- Atom reactivity: `packages/effect/src/unstable/reactivity/`
-- AsyncResult source: `packages/effect/src/unstable/reactivity/AsyncResult.ts`
+- Atom reactivity: `packages/effect/src/reactivity/`
+- AsyncResult source: `packages/effect/src/reactivity/AsyncResult.ts`
 - Effect source: `packages/effect/src/`
 
 ## Core Concepts
@@ -36,7 +36,7 @@ explicit for state that must survive SSR dehydration.
 Atoms work **by reference** - they are stable containers for reactive state:
 
 ```typescript
-import * as Atom from 'effect/unstable/reactivity/Atom';
+import * as Atom from 'effect/reactivity/Atom';
 
 // Atoms are created once and referenced throughout the app
 export const counterAtom = Atom.make(0);
@@ -47,10 +47,13 @@ export const counterAtom = Atom.make(0);
 
 ### Automatic Cleanup
 
-Atoms automatically reset when no subscribers remain (unless marked with `keepAlive`):
+Registry nodes become eligible for disposal when unused by subscribers and
+dependent atoms. Disposal follows the atom's idle TTL or registry default; it is
+not necessarily synchronous with the last React unmount. `keepAlive` retains the
+node until its registry is reset/disposed:
 
 ```typescript
-// Resets when last subscriber unmounts
+// Disposed after becoming unused, according to the registry's idle policy
 export const temporaryState = Atom.make(initialValue);
 
 // Persists across component lifecycles
@@ -61,10 +64,15 @@ export const persistentState = Atom.make(initialValue).pipe(Atom.keepAlive);
 
 Atom values are computed on-demand when subscribers access them.
 
+Tracked dependencies remain retained while a node is stale and are reconciled
+on its next build. Register cleanup with `get.addFinalizer` or scoped effects so
+superseded builds release resources. Observed failed builds can recover when a
+dependency changes; avoid manual reset workarounds for stale-node propagation.
+
 ## Pattern: Basic Atoms
 
 ```typescript
-import * as Atom from 'effect/unstable/reactivity/Atom';
+import * as Atom from 'effect/reactivity/Atom';
 
 // Simple atom
 export const count = Atom.make(0);
@@ -132,19 +140,29 @@ export const userAtoms = Atom.family((userId: string) =>
 	Atom.make<User | null>(null).pipe(Atom.keepAlive)
 );
 
-// Usage - always returns the same atom for a given ID
+// Reuses the cached live atom for a given ID
 const userAtom = userAtoms(userId);
 ```
 
+Family caches use weak references where supported. Identity is reused while the
+cached atom is live; it is not a permanent store of every key ever requested.
+An old atom's finalizer does not evict a newer cached atom for the same key.
+
 ## Pattern: Atom.fn for Async Actions
 
 Use `Atom.fn` with `Effect.fnUntraced` for async operations:
 
 - Reading gives `AsyncResult<Success, Error>` with automatic `.waiting` flag
 - Triggering via `useAtomSet` runs the effect
+- The callback takes one application argument plus an `Atom.FnContext`; bundle
+  multiple inputs into an object. The second argument is not another payload.
+- By default a new write replaces the current run. Use `{ concurrent: true }`
+  deliberately for overlapping Effect executions. Synchronous successes and
+  failures are retained in concurrent mode; it still exposes one `AsyncResult`,
+  not a per-invocation result log.
 
 ```typescript
-import * as Atom from "effect/unstable/reactivity/Atom"
+import * as Atom from "effect/reactivity/Atom"
 import { useAtomValue, useAtomSet } from "@effect/atom-react"
 import { Effect, Exit } from "effect"
 
@@ -278,7 +296,7 @@ Atom.runtime.addGlobalLayer(
 Atoms can return `AsyncResult` types for explicit error handling:
 
 ```tsx
-import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import * as AsyncResult from 'effect/reactivity/AsyncResult';
 
 export const userData = Atom.make<AsyncResult.AsyncResult<User, Error>>(
 	AsyncResult.initial()
@@ -354,7 +372,7 @@ Use `Atom.kvs` for persisted state:
 
 ```typescript
 import { BrowserKeyValueStore as BrowserKvs } from '@effect/platform-browser';
-import * as Atom from 'effect/unstable/reactivity/Atom';
+import * as Atom from 'effect/reactivity/Atom';
 import * as Schema from 'effect/Schema';
 
 export const userSettings = Atom.kvs({
@@ -452,7 +470,7 @@ export const wsConnection = Atom.make(
 2. **Never Manual Void Wrappers**: Don't wrap Effects in void functions—you lose `waiting` control
 3. **Reference Stability**: Use `Atom.family` for dynamically generated atom sets
 4. **Lazy Evaluation**: Values computed on-demand when accessed
-5. **Automatic Cleanup**: Atoms reset when unused (unless `keepAlive`)
+5. **Automatic Cleanup**: Unused atoms follow idle retention; `keepAlive` lasts until registry reset/disposal
 6. **Derive, Don't Coordinate**: Use computed atoms to derive state
 7. **Result Types**: Handle errors explicitly with AsyncResult.match
 8. **Services in Runtime**: Wrap layers once, use in multiple atoms
@@ -467,7 +485,7 @@ export const wsConnection = Atom.make(
 Use `Atom.fn` with `Effect.fnUntraced` which automatically provides `AsyncResult` with `.waiting` flag:
 
 ```typescript
-import * as Atom from "effect/unstable/reactivity/Atom"
+import * as Atom from "effect/reactivity/Atom"
 import { useAtomValue, useAtomSet } from "@effect/atom-react"
 import { Effect } from "effect"
 
@@ -496,7 +514,7 @@ function UserProfile() {
 
 ```typescript
 export const updateItem = runtime.fn(
-	Effect.fnUntraced(function* (id: string, updates: Partial<Item>) {
+	Effect.fnUntraced(function* ({ id, updates }: { id: string; updates: Partial<Item> }) {
 		const current = yield* Atom.get(itemsAtom);
 
 		// Optimistic update
@@ -569,12 +587,32 @@ Atom.batch(() => {
 	registry.set(ageAtom, 30);
 	registry.set(statusAtom, 'active');
 });
-// Subscribers notified once, not three times
+// Dependents observe the final batched state
 ```
 
 Outside Effect/Atom contexts, use an `AtomRegistry` (`registry.set(...)`) inside the batch. Inside an atom or write context, use that context (`ctx.set(...)`) in the same pattern. `Atom.batch` only batches notifications; it does not introduce a free `set` function.
 
-Use when multiple atoms must update atomically to avoid intermediate renders.
+Batch synchronous writes to avoid intermediate notifications. Writes made by
+commit listeners are processed in subsequent commit work rather than dropped,
+so do not promise exactly one callback when listeners themselves write.
+Batching is not rollback: writes made before a thrown exception are still
+committed and notified, then the first failure is rethrown. Async work after an
+`await` is outside the batch.
+
+## Stale-while-revalidate reads
+
+Wrap an `AsyncResult` query atom with `Atom.swr({ staleTime: '30 seconds' })`.
+Reads return the current result and defer stale-source refresh until after the
+read. The scheduled refresh is skipped if the source becomes fresh or the
+wrapper is disposed; a one-shot unmounted read does not keep background work
+alive. Mount/subscribe for a continuing query lifetime.
+
+`revalidateOnMount` controls initial stale refreshes. `revalidateOnFocus: true`
+respects `staleTime`, while `'always'` forces a refresh. Manual refresh always
+forwards to the source. `staleTime` is a freshness window, distinct from idle TTL.
+Create the wrapper once (module scope, `Atom.family`, or `useMemo`) rather than
+on every render. `swr` returns `WithoutSerializable<R>`; retain the serializable
+source atom for hydration or explicitly serialize the wrapper under its own key.
 
 ## AsyncResult.builder
 

package/skills/effect-batching/SKILL.md

@@ -14,7 +14,7 @@ Reference this for:
 
 - `Request` and `Request.Class` definitions (`packages/effect/src/Request.ts`)
 - `RequestResolver` constructors and combinators (`packages/effect/src/RequestResolver.ts`)
-- `SqlResolver` for SQL-specific batching (`packages/effect/src/unstable/sql/SqlResolver.ts`)
+- `SqlResolver` for SQL-specific batching (`packages/effect/src/sql/SqlResolver.ts`)
 - Batching tutorial (`ai-docs/src/05_batching/10_request-resolver.ts`)
 
 ## The N+1 Problem
@@ -440,10 +440,12 @@ class Users extends Context.Service<
 
 ## SQL Integration with SqlResolver
 
-`SqlResolver` (from `effect/unstable/sql`) provides schema-validated, batched SQL resolvers. Import:
+`SqlResolver` (from `effect/sql`) provides schema-validated, batched SQL resolvers.
+It remains marked `@stability unstable` even though its import path has no
+`unstable` segment; check its release-specific contract when upgrading. Import:
 
 ```typescript
-import { SqlResolver } from 'effect/unstable/sql';
+import { SqlResolver } from 'effect/sql';
 ```
 
 ### SqlResolver.ordered