@danieljvdm/dev-kit 0.11.3 → 0.12.0

package/README.md

@@ -198,9 +198,9 @@ tool versions. A project-local process lock also prevents concurrent applies.
 ```
 
 - `dev-kit` installs guidance for operating the toolkit itself.
-- `effect` expands to the `effect-ts` umbrella, whose lazy references include
-  Effect Atom HTTP data fetching and Effect DateTime guidance. The former
-  `effect-atom-data-fetching` selector remains an alias for compatibility.
+- `effect` expands to the package-guidance `effect-ts` bootstrap, the
+  opinionated `effect-architecture-audit`, and `build-effect-apis` for shared
+  HTTP contracts, Effect Atom clients, TanStack Start, and Cloudflare Workers.
 - Prefer individual external skills such as `workers-best-practices` and
   `wrangler`, selected after scanning the project for relevant technologies.
 - `serve-sim` selects the approved Evan Bacon simulator skill directly.
@@ -284,9 +284,35 @@ worktree converges its own copy during install while the project-owned
 
 ## Vite+ quality setup
 
-Vite+/Effect repositories opt into the canonical Vite config and GitHub Actions
+The repository always owns `vite.config.ts`. Compose Dev Kit's quality defaults
+from that project-owned config, then opt into the hardened GitHub Actions
 workflow independently:
 
+```ts
+import { createRecommendedVitePlusConfig } from "@danieljvdm/dev-kit/vite-plus";
+import { defineConfig } from "vite-plus";
+
+const recommended = createRecommendedVitePlusConfig({
+  ignorePatterns: ["apps/api/worker-configuration.d.ts", "apps/web/src/routeTree.gen.ts"],
+});
+
+export default defineConfig({
+  ...recommended,
+  // Project-owned Vite, test, build, and framework options stay local.
+  server: { port: 5173 },
+});
+```
+
+Spread the returned top-level config before local options. When overriding a
+`fmt`, `lint`, `run`, or `staged` block, spread that returned block as well so
+its defaults remain composed.
+
+The factory configures `vp staged`, matching Oxlint/Oxfmt ignores for Dev Kit's
+tool-owned paths, and separate `vp run check` and pure `vp run typecheck` tasks.
+Project and framework-generated paths belong in `ignorePatterns` as shown;
+custom harness target paths belong there too. Dev Kit does not grow a global
+framework ignore list.
+
 ```jsonc
 {
   "include": ["dev-kit", "effect"],
@@ -295,7 +321,6 @@ workflow independently:
     "vitePlus": {
       "hooks": { "enabled": true },
       "quality": {
-        "config": { "enabled": true },
         "workflow": { "enabled": true },
       },
     },
@@ -303,47 +328,28 @@ workflow independently:
 }
 ```
 
-`quality.config.enabled` owns `vite.config.ts`; `quality.workflow.enabled` owns
-`.github/workflows/check.yml`. Selecting one does not impose the other resource's
-config, scripts, or TypeScript topology. Both require direct
+`quality.workflow.enabled` owns `.github/workflows/check.yml` but never reads,
+rewrites, adopts, or removes `vite.config.ts`. Workflow setup requires direct
 `@danieljvdm/dev-kit`, `vite-plus`, `effect`, `@effect/tsgo`, and native
 TypeScript dependencies with `setup.effectTsgo.enabled`. The installed Vite+
 must satisfy Dev Kit's peer range.
 
-The managed Vite config composes the shared Oxfmt and Oxlint presets, configures
-`vp staged`, and defines separate `vp run check` and pure `vp run typecheck`
-tasks. It rejects conflicting root scripts. The default `single-project`
-strategy requires a root `tsconfig.json` without project references. Workspaces
-can instead select Vite Task orchestration explicitly:
+Workspaces select bounded, dependency-ordered typechecking in their config:
 
-```jsonc
-{
-  "setup": {
-    "effectTsgo": { "enabled": true },
-    "vitePlus": {
-      "quality": {
-        "config": {
-          "enabled": true,
-          "typecheck": {
-            "strategy": "workspace",
-            "concurrency": 4,
-            "packages": ["apps/web", "packages/core"],
-          },
-        },
-      },
+```ts
+export default defineConfig(
+  createRecommendedVitePlusConfig({
+    typecheck: {
+      strategy: "workspace",
+      concurrency: 4,
+      packages: ["apps/web", "packages/core"],
     },
-  },
-}
+  }),
+);
 ```
 
-Workspace mode requires `package.json#workspaces` and an explicit list of
-package directories with pure `typecheck` scripts. The generated task uses
-dependency order, caching, `--fail-if-no-match`, and bounded concurrency.
-Project-reference builds remain custom because their `.tsbuildinfo` inputs and
-outputs are repository-specific.
-
-Repositories with a custom Vite config can still adopt only the hardened CI
-workflow and declare repository-specific preparation and typecheck commands:
+Each listed package must expose a pure `typecheck` script. Repositories can
+also declare workflow-specific preparation and typecheck commands:
 
 ```jsonc
 {
@@ -370,16 +376,12 @@ workflow and declare repository-specific preparation and typecheck commands:
 }
 ```
 
-Workflow-only setup does not validate or take ownership of the Vite config,
-scripts, or TypeScript topology. It performs one frozen, script-suppressed
-install, runs `dev-kit apply --locked`, and only then runs custom preparation,
-formatting, linting, tests, and typechecking. Its default typecheck command is
-`vp run typecheck`; `workflow.typecheck` replaces it. Vite+ maps install flags
-to the detected package manager. The template installs the consumer's declared
-Bun version, follows the maintained `setup-bun@v2` tag, and names the current
-`setup-vp` release because that action's `v1` tag is frozen. Existing
-workflows remain user-owned until their rendered content matches exactly—Dev
-Kit never merges YAML. See the primary
+The workflow performs one frozen, script-suppressed install, runs
+`dev-kit apply --locked`, and only then runs preparation, formatting, linting,
+tests, and typechecking. Its default typecheck command is `vp run typecheck`;
+`workflow.typecheck` replaces it. Existing workflows remain user-owned until
+their rendered content matches exactly—Dev Kit never merges YAML. See the
+primary
 [`setup-vp` versioning guidance](https://github.com/voidzero-dev/setup-vp#versioning),
 [Vite+ install guide](https://viteplus.dev/guide/install), and
 [Vite Task run guide](https://viteplus.dev/guide/run) when maintaining the
@@ -427,7 +429,7 @@ Pin the compatible packages in the consuming project:
 {
   "devDependencies": {
     "@danieljvdm/dev-kit": "^0.2.0",
-    "@effect/tsgo": "0.24.3",
+    "@effect/tsgo": "0.33.0",
     "typescript": "7.0.2",
   },
 }
@@ -477,8 +479,16 @@ bun x dev-kit add @tanstack/ai#ai-core
 That writes `@tanstack/ai#ai-core` to `dev-kit.jsonc` and, unless
 `--no-apply` is passed, installs it through the normal ownership-safe sync
 path. The qualifier prevents ambiguity when two dependencies publish the same
-skill name. Two selected skills that would both write the same destination are
-rejected before any output is changed.
+skill name, and the installed output carries it too: the copied directory is
+named by flattening the package name (drop `@`, turn every other
+non-alphanumeric run into one dash) and appending the skill name, so
+`@tanstack/ai#ai-core` installs as `tanstack-ai-ai-core`. Agent harnesses
+identify a project skill by its directory name, so the copied `SKILL.md`
+frontmatter `name:` is rewritten to that same install name; all other content
+is copied verbatim. Symlink-mode targets link straight into `node_modules`, so
+only the link itself carries the qualified name while the linked frontmatter
+keeps the upstream bare name. Two selected skills that would both write the
+same destination are rejected before any output is changed.
 
 The initial compatibility boundary is intentionally small and deterministic:
 
@@ -496,9 +506,9 @@ and frontmatter-name invariants expected by Agent Skills targets. Dev Kit does
 not rewrite nested names or ask Intent to manage agent configuration.
 
 The project `dev-kit.lock.json` records the selected package name, installed
-version, skill name, and content digest. `apply --locked` therefore rejects
-package-version or skill-content drift. Dev Kit never downloads a missing
-package or substitutes a registry version.
+version, original bare skill name, and the `node_modules` content digest.
+`apply --locked` therefore rejects package-version or skill-content drift.
+Dev Kit never downloads a missing package or substitutes a registry version.
 
 See TanStack's
 [Agent Skills documentation](https://tanstack.com/ai/latest/docs/getting-started/agent-skills)
@@ -554,34 +564,18 @@ approved Git content.
 
 ## Oxlint and Oxfmt configurations
 
-Dev Kit exports one typed Oxlint ruleset and one typed Oxfmt configuration for
-both standalone Oxc projects and Vite+ projects. A Vite+ project composes them
-in `vite.config.ts`:
+Dev Kit exports typed Oxlint/Oxfmt presets for standalone Oxc projects. The
+Vite+ factory composes both presets and keeps their tool-path ignores aligned:
 
 ```ts
-import { recommendedOxlintConfig } from "@danieljvdm/dev-kit/oxlint";
-import { recommendedOxfmtConfig } from "@danieljvdm/dev-kit/oxfmt";
+import { createRecommendedVitePlusConfig } from "@danieljvdm/dev-kit/vite-plus";
 import { defineConfig } from "vite-plus";
 
-export default defineConfig({
-  fmt: {
-    ...recommendedOxfmtConfig,
-  },
-  lint: {
-    extends: [recommendedOxlintConfig],
-    rules: {
-      // Add repository-specific rules here.
-    },
-  },
-});
+export default defineConfig(createRecommendedVitePlusConfig());
 ```
 
-Use `lint.extends` rather than a shallow object spread so Vite+ composes the
-nested plugin and rule configuration correctly. Oxfmt has no `extends`, so
-spread its configuration before project-local formatter options. The shared
-lint preset enables `typeAware` for semantic lint rules but leaves `typeCheck`
-disabled. Managed quality config uses this composition; custom Vite configs
-compose the exports manually. Effect TypeScript-Go projects run:
+The shared lint preset enables `typeAware` for semantic lint rules but leaves
+`typeCheck` disabled. Effect TypeScript-Go projects run:
 
 ```sh
 vp fmt --check

package/dev-kit.example.jsonc

@@ -9,10 +9,6 @@
     "vitePlus": {
       "hooks": { "enabled": true },
       "quality": {
-        "config": {
-          "enabled": true,
-          "typecheck": { "strategy": "single-project" },
-        },
         "workflow": { "enabled": true },
       },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.11.3",
+  "version": "0.12.0",
   "private": false,
   "description": "Declarative project development toolkit with portable agent skills.",
   "license": "MIT",
@@ -38,6 +38,10 @@
       "types": "./src/oxfmt.ts",
       "default": "./src/oxfmt.js"
     },
+    "./vite-plus": {
+      "types": "./src/vite-plus.ts",
+      "default": "./src/vite-plus.js"
+    },
     "./oxlint-plugin-effect": {
       "types": "./src/oxlint-plugin-effect.d.ts",
       "default": "./src/oxlint-plugin-effect.js"
@@ -65,17 +69,17 @@
     "catalog:check": "./bin/dev-kit.mjs catalog verify"
   },
   "dependencies": {
-    "@effect/platform-bun": "4.0.0-beta.102",
+    "@effect/platform-bun": "4.0.0-beta.105",
     "@stylistic/eslint-plugin": "5.10.0",
-    "effect": "4.0.0-beta.102",
+    "effect": "4.0.0-beta.105",
     "jsonc-parser": "3.3.1",
     "semver": "7.8.5"
   },
   "devDependencies": {
     "@changesets/cli": "3.0.0-next.10",
-    "@effect/platform-node": "4.0.0-beta.102",
-    "@effect/tsgo": "0.24.3",
-    "@effect/vitest": "4.0.0-beta.102",
+    "@effect/platform-node": "4.0.0-beta.105",
+    "@effect/tsgo": "0.33.0",
+    "@effect/vitest": "4.0.0-beta.105",
     "@types/node": "25.9.1",
     "@types/semver": "7.8.0",
     "oxfmt": "0.60.0",

package/schema/dev-kit.schema.json

@@ -161,32 +161,15 @@
       }
     },
     "vitePlusQualitySetup": {
-      "description": "Opt into independently managed Vite+ quality resources for supported Effect TypeScript-Go repositories.",
+      "description": "Manage the Vite+ quality workflow while the repository owns and extends vite.config.ts.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "config": {
-          "$ref": "#/$defs/vitePlusQualityConfigSetup"
-        },
         "workflow": {
           "$ref": "#/$defs/vitePlusQualityWorkflowSetup"
         }
       }
     },
-    "vitePlusQualityConfigSetup": {
-      "description": "Manage the canonical root Vite config without requiring Dev Kit to own CI.",
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "enabled": {
-          "type": "boolean",
-          "default": false
-        },
-        "typecheck": {
-          "$ref": "#/$defs/vitePlusQualityTypecheckSetup"
-        }
-      }
-    },
     "vitePlusQualityWorkflowSetup": {
       "description": "Manage the canonical GitHub Actions check workflow without requiring Dev Kit to own the Vite config.",
       "type": "object",
@@ -235,34 +218,6 @@
         }
       }
     },
-    "vitePlusQualityTypecheckSetup": {
-      "description": "Select the managed typecheck topology. Single-project is the default; workspace mode runs explicitly scoped package scripts through Vite Task.",
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "strategy": {
-          "enum": ["single-project", "workspace"],
-          "default": "single-project"
-        },
-        "concurrency": {
-          "description": "Maximum concurrent workspace typecheck tasks.",
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 32,
-          "default": 4
-        },
-        "packages": {
-          "description": "Project-relative workspace package directories whose typecheck scripts should run.",
-          "type": "array",
-          "items": {
-            "type": "string",
-            "minLength": 1
-          },
-          "uniqueItems": true,
-          "default": []
-        }
-      }
-    },
     "target": {
       "type": "object",
       "additionalProperties": false,

package/skills/build-effect-apis/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: build-effect-apis
+description: Build and consume contract-first Effect HTTP APIs. Use when defining shared HttpApiEndpoint/HttpApiGroup contracts, implementing HttpApiBuilder or HttpApiServer handlers and middleware, deriving HttpApiClient or Effect Atom clients, or integrating those APIs with TanStack Start and Cloudflare Workers/effect-cf.
+---
+
+# Build Effect APIs
+
+Treat the shared `HttpApi` value as the **contract spine**: schemas, server,
+OpenAPI, and clients all derive from it. Keep transport contracts isomorphic;
+keep runtime behavior in handlers, services, layers, and client state modules.
+
+Effect HTTP and reactivity APIs are version-sensitive. Read the target
+repository's manifests and lockfile, inspect its existing imports, and confirm
+exact signatures from the installed package declarations before editing. In
+current Effect v4 betas the server module is `HttpApiBuilder`; a request that
+mentions `HttpApiServer` may refer to the same server-building responsibility
+from another version.
+
+## Build the contract spine
+
+1. Inventory the existing API root, groups, endpoints, schemas, transport
+   errors, middleware, handler layers, client construction, and runtime edge.
+   Finish when every existing contract consumer and provider is identified.
+2. Read [shared-contracts.md](references/shared-contracts.md), then change the
+   shared domain package first: schemas and errors, one endpoint contract,
+   group composition, root API composition, and public exports. Finish when
+   server and client can import the same API value without runtime-specific
+   dependencies entering the domain package.
+3. Read [server-and-middleware.md](references/server-and-middleware.md), then
+   implement middleware and every changed group handler. Keep handlers as
+   decoded boundary adapters into application services and assemble all
+   requirements at the runtime edge. Finish when each endpoint identifier has
+   exactly one handler and every declared middleware has a provided layer.
+4. Choose the consumer branch:
+   - For React server state, read
+     [effect-atom-client.md](references/effect-atom-client.md) and
+     [effect-atom-lifecycle.md](references/effect-atom-lifecycle.md), then
+     derive one `AtomHttpApi.Service`, stable query atoms or families, mutation
+     atoms, and one reactivity-key vocabulary.
+   - For non-React Effect code, use the direct `HttpApiClient` branch in
+     [effect-atom-client.md](references/effect-atom-client.md).
+
+   Finish when consumers call the shared contract rather than redefining wire
+   types or using ad hoc `fetch` for declared endpoints.
+
+5. Read [verification.md](references/verification.md). Run the repository's
+   format, lint, typecheck, and test commands. Finish when changed schemas
+   round-trip, middleware failures use declared error channels, server and
+   client agree on every request shape, and changed atom lifecycles have
+   deterministic coverage.
+
+## Optional branches
+
+- Read [runtime-assembly.md](references/runtime-assembly.md) when wiring a
+  conventional Node/Bun server, generated API docs, process entrypoint, or
+  serverless web handler.
+- Read [effect-atom-testing.md](references/effect-atom-testing.md) when changing
+  Atom cache retention, SWR, polling, invalidation, cancellation, aggregation,
+  provider placement, SSR, or hydration behavior.
+- Read [tanstack-start.md](references/tanstack-start.md) when the client is
+  TanStack Start, SSR, hydration, `ClientOnly`, loaders, server functions, or a
+  proxied separate API.
+- Read [cloudflare-workers.md](references/cloudflare-workers.md) when the server
+  runs on Cloudflare Workers or uses `effect-cf`, bindings, Durable Objects,
+  Queues, WebSockets, streaming, or raw byte routes.
+
+## Boundary rules
+
+- Let schemas own wire validation, encoding, status metadata, and branded IDs.
+- Let endpoint files own route inputs, success, and expected transport errors.
+- Let middleware own cross-cutting request behavior and request-scoped services.
+- Let handlers own transport-to-application mapping and boundary invariants.
+- Let application services own orchestration, persistence, retries, and
+  transactions.
+- Let client data modules own API services, query identity, cache policy,
+  invalidation keys, and mutation atoms; let UI action owners own navigation,
+  toasts, optimistic presentation, and form reset.

package/skills/build-effect-apis/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Build Effect APIs"
+  short_description: "Build and consume typed Effect HTTP APIs"
+  default_prompt: "Use $build-effect-apis to build a shared Effect HTTP API and consume it from the application client."

package/skills/build-effect-apis/references/cloudflare-workers.md

@@ -0,0 +1,71 @@
+# Cloudflare Workers and effect-cf
+
+Use `effect-cf` to turn Worker bindings and entrypoints into Effect services and
+layers. Confirm its compatibility with the repository's exact Effect v4 beta.
+
+## Runtime edge
+
+Assemble application services, `HttpApiBuilder` routes, the Effect HTTP
+platform/router requirements, and binding layers once, then hand the final
+layer and fetch effect to `Worker.make` or another effect-cf definition.
+
+```ts
+import { Effect, Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { Worker } from "effect-cf";
+
+const WorkerLive = Layer.mergeAll(ApplicationServicesLive, ApiRoutesLive);
+
+const fetch = Effect.gen(function* () {
+  const request = yield* Worker.NativeRequest;
+  const router = yield* HttpRouter.HttpRouter;
+  return yield* router.asHttpEffect();
+});
+
+export default Worker.make(WorkerLive, { fetch });
+```
+
+The concrete Effect HTTP platform prerequisites differ by version and runtime.
+Let the `HttpApiBuilder.layer` requirements drive the layer graph and verify it
+with typecheck plus a Worker startup/dry-run command.
+
+## Typed bindings
+
+Represent D1, R2, KV, Queues, Durable Object namespaces, and configuration as
+services/layers at the Worker boundary. Application services depend on those
+tags, not on a raw `env` object. Keep Wrangler binding names synchronized with
+the layers and generated Worker types.
+
+`effect-cf` typed Durable Object and Queue definitions can serve both as the
+contract and as the producer/namespace service. Use deterministic Durable
+Object names for domain ownership, keep RPC errors typed, and design Queue
+consumers for at-least-once delivery.
+
+## Raw route escape hatches
+
+JSON request/response routes fit `HttpApi`. WebSocket upgrades, streaming
+responses, passthrough `Response` values, and large or direct byte transfers may
+need a raw adapter at the Worker edge.
+
+Dispatch raw routes before `router.asHttpEffect()`, decode every path/query/
+header value with shared schemas, then fall through to the generated API router.
+Mirror all relevant security, tenancy, tracing, and rate-limit behavior because
+`HttpApi` middleware does not run for routes that bypass it.
+
+For uploads, verify declared size, maximum size, media type, capability, and
+checksum before storage. For WebSockets, validate the upgrade request and
+identity before forwarding it to a Durable Object or session service.
+
+Apply runtime-wide CORS around both raw and `HttpApi` routes. Include every
+custom request header and method, and test preflight behavior. Treat OpenAPI as
+documentation only for declared `HttpApi` endpoints; document raw routes
+separately when clients need them.
+
+## Operational checks
+
+- Generate Worker binding types after Wrangler binding changes.
+- Run local migrations before local server tests.
+- Run the repository's startup or deployment dry-run check after layer changes.
+- Keep remote resource creation, migrations, and deployment as explicit
+  user-authorized operations.
+- Test Queue idempotency, Durable Object naming, and raw-route middleware parity.

package/skills/build-effect-apis/references/effect-atom-client.md

@@ -0,0 +1,161 @@
+# Effect API clients
+
+Derive clients from the shared `HttpApi`; keep request types, response types,
+and expected errors owned by the contract.
+
+- [Inventory the client boundary](#inventory-the-client-boundary)
+- [Build one Atom API service](#build-one-atom-api-service)
+- [Define queries](#define-queries)
+- [Define mutations and invalidation](#define-mutations-and-invalidation)
+- [Use a direct client outside React](#use-a-direct-client-outside-react)
+
+## Inventory the client boundary
+
+Before changing Atom code, locate every `RegistryProvider`, runtime factory,
+`AtomHttpApi.Service`, query atom, mutation atom, reactivity-key constructor,
+and route aggregate. Confirm the installed `effect` and `@effect/atom-react`
+versions before copying signatures.
+
+## Build one Atom API service
+
+Create one module-scoped runtime factory and one `AtomHttpApi.Service`. Share a
+memo map when multiple client services must reuse layers.
+
+```ts
+import { Effect, Layer } from "effect";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { HttpApiMiddleware } from "effect/unstable/httpapi";
+import { Atom, AtomHttpApi } from "effect/unstable/reactivity";
+import { ApplicationApi, Authenticate } from "@app/domain";
+
+export const AuthenticateClient = HttpApiMiddleware.layerClient(
+  Authenticate,
+  Effect.fn("AuthenticateClient")(function* ({ next, request }) {
+    const token = yield* readAccessToken;
+    return yield* next(HttpClientRequest.bearerToken(request, token));
+  }),
+);
+
+const ApiHttpClient = Layer.mergeAll(FetchHttpClient.layer, AuthenticateClient);
+
+export const appRuntime = Atom.context({
+  memoMap: Layer.makeMemoMapUnsafe(),
+});
+
+export const ApiClient = AtomHttpApi.Service()("ApiClient", {
+  api: ApplicationApi,
+  httpClient: ApiHttpClient,
+  runtime: appRuntime,
+  baseUrl: "/api",
+  transformClient: (client) =>
+    HttpClient.mapRequest(client, (request) =>
+      HttpClientRequest.setHeader(request, "x-request-id", requestId()),
+    ),
+});
+```
+
+Define the runtime, service, key constructors, queries, and mutations outside
+React renders. Keep browser-only identity access behind the client boundary.
+When contract middleware sets `requiredForClient`, satisfy it with
+`HttpApiMiddleware.layerClient` in the `httpClient` layer. Reserve
+`transformClient` for transport-wide behavior such as correlation headers,
+base URL changes, tracing, or retries; do not bypass declared API security with
+an unrelated raw header transform.
+
+## Define queries
+
+```ts
+export const projectKeys = {
+  collection: ["projects"] as const,
+  project: (id: ProjectId) => [`project:${id}`] as const,
+};
+
+export const projectAtom = Atom.family((projectId: ProjectId) =>
+  ApiClient.query("projects", "getProject", {
+    params: { projectId },
+    timeToLive: "5 minutes",
+    reactivityKeys: projectKeys.project(projectId),
+  }).pipe(Atom.swr({ staleTime: "30 seconds", revalidateOnMount: true })),
+);
+```
+
+`query(group, endpoint, request)` returns an `Atom<AsyncResult<...>>`. The
+service memoizes encoded request keys internally; a public `Atom.family` still
+expresses domain ownership and cache policy through a stable scalar or Effect
+`Hash`/`Equal` key.
+
+Query options have distinct jobs:
+
+- `timeToLive` controls idle registry retention;
+- `reactivityKeys` registers invalidation subscriptions;
+- `serializationKey` enables decoded-only hydration serialization and is not
+  the runtime cache key;
+- `responseMode` changes the response and error shape.
+
+Keep secrets out of serialization keys, URL state, hydration payloads, and
+client-visible layers.
+
+## Define mutations and invalidation
+
+```ts
+export const updateProjectMutation = ApiClient.mutation("projects", "updateProject");
+
+const updateProject = useAtomSet(updateProjectMutation, { mode: "promise" });
+
+await updateProject({
+  params: { projectId },
+  payload: patch,
+  reactivityKeys: [...projectKeys.collection, ...projectKeys.project(projectId)],
+});
+```
+
+Successful mutations invalidate matching keys; failed mutations do not.
+Centralize reactivity-key constructors because mismatched strings fail silently.
+When one mutation affects several exact keys, flatten their arrays; an array
+containing key arrays registers those nested arrays as different keys.
+
+Exact array keys invalidate only exact matches. Record-form keys are
+hierarchical in current Effect v4 implementations: a property registers both
+its broad name and each `property:id` combination. Confirm this against the
+installed version before relying on it.
+
+Choose invalidation breadth from the server write:
+
+- invalidate an entity key when only its detail changed;
+- invalidate the collection when membership, ordering, totals, or filters can
+  change;
+- invalidate every affected namespace when a write crosses aggregates.
+
+Combine invalidation with manual refresh only when two requests are intended.
+Keep navigation, toasts, form reset, and presentation-level optimistic state
+with the initiating UI.
+
+## Use a direct client outside React
+
+```ts
+import { Effect } from "effect";
+import { FetchHttpClient, HttpClientRequest } from "effect/unstable/http";
+import { HttpApiClient, HttpApiMiddleware } from "effect/unstable/httpapi";
+import { ApplicationApi, Authenticate } from "@app/domain";
+import { AccessToken, AccessTokenLive } from "./AccessToken";
+
+const AuthenticateClient = HttpApiMiddleware.layerClient(
+  Authenticate,
+  Effect.fn("AuthenticateClient")(function* ({ next, request }) {
+    const token = yield* AccessToken;
+    return yield* next(HttpClientRequest.bearerToken(request, token.value));
+  }),
+);
+
+const program = Effect.gen(function* () {
+  const client = yield* HttpApiClient.make(ApplicationApi, {
+    baseUrl: "https://api.example.com",
+  });
+  return yield* client.projects.getProject({ params: { projectId } });
+}).pipe(Effect.provide([FetchHttpClient.layer, AuthenticateClient, AccessTokenLive]));
+```
+
+Use the direct client in services, scripts, tests, and non-React applications.
+Provide every required contract middleware at the client composition root.
+Transform the underlying `HttpClient` once for non-contract headers, tracing,
+retry, or base behavior rather than repeating it at every call site.