@danieljvdm/dev-kit 0.11.3 → 0.13.0

package/src/vite-plus-quality.ts

@@ -1,37 +1,26 @@
-import { Effect, FileSystem, Path, Schema } from "effect";
-import { parse as parseJsonc, type ParseError } from "jsonc-parser";
+import { Effect, Schema } from "effect";
 
-import type { VitePlusQualityWorkflowStep, VitePlusTypecheckStrategy } from "./manifest.ts";
-import { readDirectDependencyNames, readProjectPackage } from "./project-package.ts";
+import type { VitePlusQualityWorkflowStep } from "./manifest.ts";
+import { readDirectDependencyNames } from "./project-package.ts";
 import { validateInstalledVitePlus } from "./vite-plus-dependency.ts";
 
-export const VITE_PLUS_CONFIG_PATH = "vite.config.ts";
-export const VITE_PLUS_CONFIG_TEMPLATE = "templates/vite-plus/vite.config.ts";
 export const VITE_PLUS_GITHUB_ACTIONS_PATH = ".github/workflows/check.yml";
 export const VITE_PLUS_GITHUB_ACTIONS_TEMPLATE = "templates/vite-plus/github-actions-check.yml";
 
-export class VitePlusQualitySupportError extends Schema.TaggedErrorClass<VitePlusQualitySupportError>()(
+export class VitePlusQualitySupportError extends Schema.TaggedError<VitePlusQualitySupportError>()(
   "VitePlusQualitySupportError",
   { message: Schema.String },
 ) {}
 
-export type VitePlusQualityTypecheck = {
-  readonly strategy: VitePlusTypecheckStrategy;
-  readonly concurrency: number;
-  readonly packages: ReadonlyArray<string>;
-};
-
 export type VitePlusQualityWorkflow = {
   readonly beforeChecks: ReadonlyArray<VitePlusQualityWorkflowStep>;
   readonly typecheck: ReadonlyArray<string>;
 };
 
 export type VitePlusQualitySelection = {
-  readonly config?: VitePlusQualityTypecheck;
-  readonly workflow?: VitePlusQualityWorkflow;
+  readonly workflow: VitePlusQualityWorkflow;
 };
 
-const SINGLE_PROJECT_TYPECHECK_TASK = '      typecheck: "tsc --noEmit",';
 const LOCKED_DEV_KIT_COMMAND =
   "bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked";
 const BEFORE_CHECKS_MARKER =
@@ -53,28 +42,6 @@ const replaceUniqueTemplateMarker = (
   return `${parts[0]}${replacement}${parts[1]}`;
 };
 
-const shellQuote = (value: string): string => `'${value.replaceAll("'", `'"'"'`)}'`;
-
-export const renderVitePlusConfigTemplate = (
-  template: string,
-  typecheck: VitePlusQualityTypecheck,
-): string => {
-  if (typecheck.strategy === "single-project") return template;
-  const filters = typecheck.packages
-    .map((packageDir) => `--filter ${shellQuote(`./${packageDir}`)}`)
-    .join(" ");
-  const command = `vp run --cache --concurrency-limit ${typecheck.concurrency} ${filters} --fail-if-no-match typecheck`;
-
-  return replaceUniqueTemplateMarker(
-    template,
-    SINGLE_PROJECT_TYPECHECK_TASK,
-    `      typecheck: {
-        command: ${JSON.stringify(command)},
-        cache: false,
-      },`,
-  );
-};
-
 export const renderVitePlusWorkflowTemplate = (
   template: string,
   options: {
@@ -137,161 +104,43 @@ export const validateVitePlusQualitySupport = Effect.fn("validateVitePlusQuality
     typescriptPackage: string,
     selection: VitePlusQualitySelection,
   ) {
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const packageJson = yield* readProjectPackage(projectDir);
     const dependencies = yield* readDirectDependencyNames(projectDir);
     const required = new Set(["effect", "@effect/tsgo", typescriptPackage]);
 
     yield* validateInstalledVitePlus(projectDir).pipe(
-      Effect.mapError((error) => new VitePlusQualitySupportError({ message: error.message })),
+      Effect.mapError((error) => VitePlusQualitySupportError.make({ message: error.message })),
     );
 
     if (projectDir !== packageRoot) required.add("@danieljvdm/dev-kit");
     const missing = [...required].filter((dependency) => !dependencies.includes(dependency));
 
     if (missing.length > 0) {
-      return yield* new VitePlusQualitySupportError({
+      return yield* VitePlusQualitySupportError.make({
         message: `setup.vitePlus.quality requires direct dependencies: ${missing.join(", ")}`,
       });
     }
-    if (selection.workflow !== undefined) {
-      if (selection.workflow.typecheck.length === 0) {
-        return yield* new VitePlusQualitySupportError({
-          message: "setup.vitePlus.quality.workflow.typecheck requires at least one command",
-        });
-      }
-      for (const command of selection.workflow.typecheck) {
-        if (command.trim().length === 0) {
-          return yield* new VitePlusQualitySupportError({
-            message: "setup.vitePlus.quality.workflow.typecheck commands must not be empty",
-          });
-        }
-      }
-      for (const step of selection.workflow.beforeChecks) {
-        if (step.name.trim().length === 0 || step.run.length === 0) {
-          return yield* new VitePlusQualitySupportError({
-            message:
-              "setup.vitePlus.quality.workflow.beforeChecks steps require a name and at least one command",
-          });
-        }
-        if (step.run.some((command) => command.trim().length === 0)) {
-          return yield* new VitePlusQualitySupportError({
-            message: "setup.vitePlus.quality.workflow.beforeChecks commands must not be empty",
-          });
-        }
-      }
-    }
-    const typecheck = selection.config;
-
-    if (typecheck === undefined) return;
-    const conflictingScripts = ["check", "typecheck"].filter(
-      (script) => packageJson.scripts?.[script] !== undefined,
-    );
-
-    if (conflictingScripts.length > 0) {
-      return yield* new VitePlusQualitySupportError({
-        message: `setup.vitePlus.quality.config defines Vite tasks that conflict with package scripts: ${conflictingScripts.join(", ")}`,
-      });
-    }
-    if (typecheck.concurrency < 1 || typecheck.concurrency > 32) {
-      return yield* new VitePlusQualitySupportError({
-        message: "setup.vitePlus.quality.config typecheck concurrency must be between 1 and 32",
+    if (selection.workflow.typecheck.length === 0) {
+      return yield* VitePlusQualitySupportError.make({
+        message: "setup.vitePlus.quality.workflow.typecheck requires at least one command",
       });
     }
-    if (typecheck.strategy === "single-project" && typecheck.packages.length > 0) {
-      return yield* new VitePlusQualitySupportError({
-        message:
-          "setup.vitePlus.quality.config single-project typechecking does not accept workspace packages",
-      });
-    }
-    const workspacePatterns = Array.isArray(packageJson.workspaces)
-      ? packageJson.workspaces
-      : typeof packageJson.workspaces === "object" && packageJson.workspaces !== null
-        ? (packageJson.workspaces as { readonly packages?: unknown }).packages
-        : undefined;
-
-    if (
-      typecheck.strategy === "workspace" &&
-      (!Array.isArray(workspacePatterns) ||
-        workspacePatterns.length === 0 ||
-        !workspacePatterns.every((pattern) => typeof pattern === "string"))
-    ) {
-      return yield* new VitePlusQualitySupportError({
-        message:
-          "setup.vitePlus.quality.config workspace typechecking requires package.json workspaces",
-      });
-    }
-    if (typecheck.strategy === "workspace") {
-      if (typecheck.packages.length === 0) {
-        return yield* new VitePlusQualitySupportError({
-          message:
-            "setup.vitePlus.quality.config workspace typechecking requires explicit package directories",
+    for (const command of selection.workflow.typecheck) {
+      if (command.trim().length === 0) {
+        return yield* VitePlusQualitySupportError.make({
+          message: "setup.vitePlus.quality.workflow.typecheck commands must not be empty",
         });
       }
-      const uniquePackages = new Set(typecheck.packages);
-
-      if (uniquePackages.size !== typecheck.packages.length) {
-        return yield* new VitePlusQualitySupportError({
-          message: "setup.vitePlus.quality.config workspace typecheck packages must be unique",
-        });
-      }
-      for (const packageDir of typecheck.packages) {
-        const absolute = path.resolve(projectDir, packageDir);
-        const relative = path.relative(projectDir, absolute);
-
-        if (
-          packageDir.length === 0 ||
-          path.isAbsolute(packageDir) ||
-          relative.length === 0 ||
-          relative === ".." ||
-          relative.startsWith(`..${path.sep}`)
-        ) {
-          return yield* new VitePlusQualitySupportError({
-            message: `setup.vitePlus.quality.config workspace package must be a project-relative subdirectory: ${packageDir}`,
-          });
-        }
-        const workspacePackage = yield* readProjectPackage(absolute).pipe(
-          Effect.mapError(
-            () =>
-              new VitePlusQualitySupportError({
-                message: `setup.vitePlus.quality.config workspace package is missing a valid package.json: ${packageDir}`,
-              }),
-          ),
-        );
-
-        if (workspacePackage.scripts?.typecheck === undefined) {
-          return yield* new VitePlusQualitySupportError({
-            message: `setup.vitePlus.quality.config workspace package requires a typecheck script: ${packageDir}`,
-          });
-        }
-      }
     }
-    if (typecheck.strategy === "single-project") {
-      const tsconfigPath = path.join(projectDir, "tsconfig.json");
-
-      if (!(yield* fs.exists(tsconfigPath))) {
-        return yield* new VitePlusQualitySupportError({
+    for (const step of selection.workflow.beforeChecks) {
+      if (step.name.trim().length === 0 || step.run.length === 0) {
+        return yield* VitePlusQualitySupportError.make({
           message:
-            "setup.vitePlus.quality.config single-project typechecking requires tsconfig.json",
+            "setup.vitePlus.quality.workflow.beforeChecks steps require a name and at least one command",
         });
       }
-      const errors: Array<ParseError> = [];
-      const tsconfig = parseJsonc(yield* fs.readFileString(tsconfigPath), errors, {
-        allowTrailingComma: true,
-      });
-
-      if (errors.length > 0 || typeof tsconfig !== "object" || tsconfig === null) {
-        return yield* new VitePlusQualitySupportError({
-          message: "setup.vitePlus.quality.config requires a valid root tsconfig.json",
-        });
-      }
-      const references = (tsconfig as { readonly references?: unknown }).references;
-
-      if (Array.isArray(references) && references.length > 0) {
-        return yield* new VitePlusQualitySupportError({
-          message:
-            "setup.vitePlus.quality.config single-project typechecking does not support tsconfig project references; select the workspace strategy or use a custom Vite config",
+      if (step.run.some((command) => command.trim().length === 0)) {
+        return yield* VitePlusQualitySupportError.make({
+          message: "setup.vitePlus.quality.workflow.beforeChecks commands must not be empty",
         });
       }
     }

package/src/vite-plus.js

@@ -0,0 +1,81 @@
+import { recommendedOxfmtConfig } from "./oxfmt.js";
+import { recommendedOxlintConfig } from "./oxlint.js";
+import { devKitToolIgnorePatterns } from "./tool-ignore-patterns.js";
+
+export { devKitToolIgnorePatterns } from "./tool-ignore-patterns.js";
+
+const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+
+const validateWorkspacePackage = (packageDir) => {
+  const segments = packageDir.split(/[\\/]/);
+
+  if (
+    packageDir.trim().length === 0 ||
+    packageDir === "." ||
+    packageDir === "./" ||
+    packageDir === ".\\" ||
+    packageDir.startsWith("/") ||
+    packageDir.startsWith("\\") ||
+    /^[A-Za-z]:[\\/]/.test(packageDir) ||
+    segments.includes("..")
+  ) {
+    throw new Error(`workspace package must be a project-relative subdirectory: ${packageDir}`);
+  }
+};
+
+const createTypecheckTask = (options) => {
+  if (options?.strategy !== "workspace") {
+    const command = options?.command ?? "tsc --noEmit";
+
+    if (command.trim().length === 0) throw new Error("typecheck command must not be empty");
+
+    return command;
+  }
+  const concurrency = options.concurrency ?? 4;
+
+  if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 32) {
+    throw new Error("workspace typecheck concurrency must be between 1 and 32");
+  }
+  if (options.packages.length === 0) {
+    throw new Error("workspace typechecking requires at least one package directory");
+  }
+  const packages = [...new Set(options.packages)];
+
+  if (packages.length !== options.packages.length) {
+    throw new Error("workspace typecheck packages must be unique");
+  }
+  for (const packageDir of packages) validateWorkspacePackage(packageDir);
+  const filters = packages
+    .map((packageDir) => `--filter ${shellQuote(`./${packageDir}`)}`)
+    .join(" ");
+
+  return {
+    command: `vp run --cache --concurrency-limit ${concurrency} ${filters} --fail-if-no-match typecheck`,
+    cache: false,
+  };
+};
+
+/** Build composable quality defaults for a project-owned Vite+ config. */
+export const createRecommendedVitePlusConfig = (options = {}) => {
+  const ignorePatterns = [...devKitToolIgnorePatterns, ...(options.ignorePatterns ?? [])];
+
+  return {
+    staged: {
+      "*": "vp check --fix",
+    },
+    fmt: {
+      ...recommendedOxfmtConfig,
+      ignorePatterns,
+    },
+    lint: {
+      ...recommendedOxlintConfig,
+      ignorePatterns,
+    },
+    run: {
+      tasks: {
+        check: ["vp fmt --check", "vp lint", "vp test", "vp run typecheck"],
+        typecheck: createTypecheckTask(options.typecheck),
+      },
+    },
+  };
+};

package/src/vite-plus.ts

@@ -0,0 +1,102 @@
+import { recommendedOxfmtConfig } from "./oxfmt.ts";
+import { recommendedOxlintConfig } from "./oxlint.ts";
+import { devKitToolIgnorePatterns } from "./tool-ignore-patterns.ts";
+
+export { devKitToolIgnorePatterns } from "./tool-ignore-patterns.ts";
+
+export type VitePlusTypecheckOptions =
+  | {
+      readonly strategy?: "single-project";
+      readonly command?: string;
+    }
+  | {
+      readonly strategy: "workspace";
+      readonly packages: ReadonlyArray<string>;
+      readonly concurrency?: number;
+    };
+
+export type RecommendedVitePlusConfigOptions = {
+  /** Additional project-owned generated or vendored paths. */
+  readonly ignorePatterns?: ReadonlyArray<string>;
+  readonly typecheck?: VitePlusTypecheckOptions;
+};
+
+const shellQuote = (value: string): string => `'${value.replaceAll("'", `'"'"'`)}'`;
+
+const validateWorkspacePackage = (packageDir: string): void => {
+  const segments = packageDir.split(/[\\/]/);
+
+  if (
+    packageDir.trim().length === 0 ||
+    packageDir === "." ||
+    packageDir === "./" ||
+    packageDir === ".\\" ||
+    packageDir.startsWith("/") ||
+    packageDir.startsWith("\\") ||
+    /^[A-Za-z]:[\\/]/.test(packageDir) ||
+    segments.includes("..")
+  ) {
+    throw new Error(`workspace package must be a project-relative subdirectory: ${packageDir}`);
+  }
+};
+
+const createTypecheckTask = (options: VitePlusTypecheckOptions | undefined) => {
+  if (options?.strategy !== "workspace") {
+    const command = options?.command ?? "tsc --noEmit";
+
+    if (command.trim().length === 0) throw new Error("typecheck command must not be empty");
+
+    return command;
+  }
+  const concurrency = options.concurrency ?? 4;
+
+  if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 32) {
+    throw new Error("workspace typecheck concurrency must be between 1 and 32");
+  }
+  if (options.packages.length === 0) {
+    throw new Error("workspace typechecking requires at least one package directory");
+  }
+  const packages = [...new Set(options.packages)];
+
+  if (packages.length !== options.packages.length) {
+    throw new Error("workspace typecheck packages must be unique");
+  }
+  for (const packageDir of packages) validateWorkspacePackage(packageDir);
+  const filters = packages
+    .map((packageDir) => `--filter ${shellQuote(`./${packageDir}`)}`)
+    .join(" ");
+
+  return {
+    command: `vp run --cache --concurrency-limit ${concurrency} ${filters} --fail-if-no-match typecheck`,
+    cache: false,
+  };
+};
+
+/**
+ * Build Dev Kit's recommended Vite+ quality defaults without owning the
+ * consuming repository's `vite.config.ts`. Spread the result before local
+ * project configuration.
+ */
+export const createRecommendedVitePlusConfig = (options: RecommendedVitePlusConfigOptions = {}) => {
+  const ignorePatterns = [...devKitToolIgnorePatterns, ...(options.ignorePatterns ?? [])];
+
+  return {
+    staged: {
+      "*": "vp check --fix",
+    },
+    fmt: {
+      ...recommendedOxfmtConfig,
+      ignorePatterns,
+    },
+    lint: {
+      ...recommendedOxlintConfig,
+      ignorePatterns,
+    },
+    run: {
+      tasks: {
+        check: ["vp fmt --check", "vp lint", "vp test", "vp run typecheck"],
+        typecheck: createTypecheckTask(options.typecheck),
+      },
+    },
+  };
+};

package/templates/AGENTS.md

@@ -6,6 +6,6 @@ This project uses `@danieljvdm/dev-kit` to manage portable agent skills and repr
 
 For dev-kit operations, use the `dev-kit` skill and read `{{DEV_KIT_SKILL_PATH}}` before changing managed outputs.
 
-{{PROJECT_COMMAND_POLICY}}
+{{EFFECT_INSTRUCTIONS}}{{PROJECT_COMMAND_POLICY}}
 
 <!-- DEV KIT END -->

package/skills/effect-ts/UPSTREAM.md

@@ -1,28 +0,0 @@
-# Upstream Baseline
-
-The general Effect guides in this skill were adapted from
-[`Effect-TS/skills`](https://github.com/Effect-TS/skills) at commit
-`a8b6bb40d1d4d550b49c0ff7a624b5e6da500a24`.
-
-They have been modified to:
-
-- remove the mandatory `.repos/effect` checkout
-- target the current canonical `Effect-TS/effect` v4 source
-- update version-sensitive guidance from the upstream beta.66 snapshot to
-  beta.102
-- preserve this repository's service ownership, layer construction,
-  schema-first modeling, type-boundary, HTTP, testing, logging, audit, and CLI
-  conventions
-
-## Local Authoring Checkout
-
-This repository keeps an ignored, version-matched Effect checkout for
-validating source paths and beta-sensitive APIs. `vp i` runs the equivalent
-dev-kit setup automatically; it can also be invoked directly:
-
-```bash
-./bin/dev-kit.mjs effect sync
-```
-
-Update the checkout, package dependencies, review baseline, feature index, and
-stale-API tests together when moving to a newer Effect beta.

package/skills/effect-ts/references/atom-cache-lifecycle.md

@@ -1,78 +0,0 @@
-# Effect Atom cache lifecycle
-
-## Registry and runtime scope
-
-`RegistryProvider` creates one `AtomRegistry` on its first render. Its options do not rebuild that registry later. Provider unmount schedules disposal after a short grace period, so a quick React remount can reuse the same registry; moving or keying the provider still changes the cache boundary.
-
-Place one provider around the client application subtree that should share data. Nested or route-local providers create separate caches.
-
-### React mounts and registry disposal
-
-`useAtomValue` keeps an atom active through its value subscription. `useAtomSet` and `useAtomRefresh` mount an atom through a React effect, while `useAtom` combines one value subscription with a setter. Use the combined hook when one component reads and writes the same atom; composing `useAtomValue` and `useAtomSet` adds a second mount and obscures which lifetime owns the work.
-
-Unmount releases only that hook's subscription or mount. The registry removes a node only after it has no remaining consumers and its idle TTL permits removal. Node disposal runs registered finalizers, including cancellation of interruptible Effect work. Therefore component unmount, registry eviction, and `Atom.Interrupt` are distinct events; do not use an unconditional interrupt write as a substitute for releasing a React mount.
-
-An atom runtime and a registry solve different problems:
-
-- the registry stores atom nodes, values, subscriptions, idle timers, and finalizers;
-- `Atom.context({ memoMap })` creates runtimes that share `Layer` construction through one `Layer.MemoMap`;
-- the module-level `Atom.runtime` uses Effect's module-level default memo map.
-
-Create one client runtime factory when several API/services must share layers:
-
-```ts
-import { Layer } from "effect";
-import { Atom } from "effect/unstable/reactivity";
-
-export const appAtomRuntime = Atom.context({
-  memoMap: Layer.makeMemoMapUnsafe(),
-});
-```
-
-Pass `appAtomRuntime` to each `AtomHttpApi.Service`. Do not create a memo map per query or component. On an SSR server, do not put request-specific authentication or services into a process-global memo map; use a request-scoped atom environment or keep the atom data path client-only.
-
-## Stable identity and families
-
-Export fixed queries directly. Use `Atom.family` when a parameter selects the resource:
-
-```ts
-export const projectAtom = Atom.family((projectId: string) =>
-  ApiClient.query("projects", "get", {
-    params: { projectId },
-    timeToLive: "5 minutes",
-    reactivityKeys: { projects: [projectId] },
-  }).pipe(Atom.swr({ staleTime: "30 seconds", revalidateOnMount: true })),
-);
-```
-
-The family must receive a stable key. Prefer a primitive ID. If the key is an object, give it deliberate Effect `Equal`/`Hash` semantics or reuse the same object; repeated object literals can produce distinct family entries.
-
-## Three independent clocks
-
-| Control                                         | Clock starts                      | What happens                                                                                         | What it does not mean                                 |
-| ----------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| Registry/default idle TTL or query `timeToLive` | When an atom becomes unused       | The registry keeps the cached node until idle eviction                                               | The value is fresh during that period                 |
-| `Atom.swr({ staleTime })`                       | From the latest success timestamp | A stale value can revalidate automatically on mount or focus while the prior success remains visible | The node survives an unmount long enough to be reused |
-| `Atom.withRefresh(interval)`                    | While the wrapper is mounted      | A timer force-refreshes the source and is canceled on disposal                                       | Fresh requests are skipped                            |
-
-Set retention long enough for the navigation/remount reuse window. `staleTime` cannot rescue a source that idle eviction already removed. A common policy is a longer `timeToLive`, a shorter `staleTime`, and polling only on screens that truly need it.
-
-Manual `registry.refresh`, `useAtomRefresh`, invalidation, and `Atom.withRefresh` are forceful. They do not consult SWR freshness. Polling stops when the polling wrapper's lifetime is disposed because its finalizer clears the timer; applying `keepAlive` to that wrapper intentionally keeps polling alive.
-
-## The `AsyncResult.all` route reset
-
-`AsyncResult.all` returns the first non-success input. Therefore a route aggregate is only as reusable as its least-stable input:
-
-```ts
-const routeDataAtom = Atom.make((get) =>
-  AsyncResult.all({
-    project: get(projectAtom("p-1")),
-    // Bad if created during render or rebuilt for every route visit:
-    preferences: get(makePreferencesAtom()),
-  }),
-);
-```
-
-If `preferences` is a fresh or evicted atom, it starts at `Initial`; the aggregate also looks initial even though `project` is cached. Fix the input's ownership and retention. Define a singleton/family atom outside render and give it a deliberate idle TTL. Memoizing only the `AsyncResult.all` call does not repair an unstable input atom.
-
-`AsyncResult.all` also constructs a new success container. Keep aggregation inside a derived atom so the registry controls recomputation instead of rebuilding the container ad hoc in render.

package/skills/effect-ts/references/atom-http-and-invalidation.md

@@ -1,97 +0,0 @@
-# Effect Atom HTTP queries and invalidation
-
-## Build one API service
-
-`AtomHttpApi.Service` generates a typed client, a runtime, query atoms, and mutation functions. Pass the shared runtime factory so API services share the intended `Layer.MemoMap`:
-
-```ts
-import { FetchHttpClient } from "effect/unstable/http";
-import { AtomHttpApi } from "effect/unstable/reactivity";
-import { appAtomRuntime } from "./atom-runtime";
-import { Api } from "./api";
-
-export const ApiClient = AtomHttpApi.Service()("ApiClient", {
-  api: Api,
-  httpClient: FetchHttpClient.layer,
-  baseUrl: "/api",
-  runtime: appAtomRuntime,
-});
-```
-
-Compile examples against the installed Effect version; the reactivity and HTTP APIs are unstable.
-
-## Queries
-
-`query(group, endpoint, request)` returns an `Atom<AsyncResult<...>>`. The service internally memoizes request keys with a family. A public `Atom.family` remains useful for expressing domain ownership with a simple, stable parameter and applying one cache policy.
-
-Query options have separate roles:
-
-- `timeToLive`: finite values apply idle TTL; infinity keeps the query alive;
-- `reactivityKeys`: register the query for refresh after matching invalidation;
-- `serializationKey`: make decoded-only results serializable for hydration; it is not the runtime cache key;
-- `responseMode`: changes the response and error shape.
-
-Never place secrets in `serializationKey`, URL state, hydration payloads, or client-visible layers.
-
-## Mutations and action ownership
-
-Create mutation atoms once, then invoke them from the component or workflow that owns the action:
-
-```ts
-export const updateProject = ApiClient.mutation("projects", "update");
-
-// In the initiating component:
-const mutate = useAtomSet(updateProject, { mode: "promise" });
-await mutate({
-  params: { projectId },
-  payload: patch,
-  reactivityKeys: { projects: [projectId] },
-});
-```
-
-The mutation's `reactivityKeys` are invalidated only after the request succeeds. Failed mutations do not invalidate. Keep navigation, toasts, dialog closure, and optimistic UI at the action owner; keep shared server-state refresh in reactivity keys.
-
-If the component also renders the mutation result, use `useAtom(updateProject)` instead of pairing `useAtomValue` with `useAtomSet`. A module-scoped mutation atom is shared registry state, so an unconditional cleanup write of `Atom.Interrupt` can cancel work owned by another consumer and publishes an interrupted failure.
-
-Keep a multi-step mutation sequence in an owner that lives for the whole sequence. When navigation can unmount the initiating route after one request succeeds, a component-owned sequential fan-out can leave a partially completed operation. Use one stable workflow atom or service when client ownership is sufficient; use one server-side command or durable workflow when completion must survive browser navigation or disconnects.
-
-## Use one key vocabulary
-
-Array keys represent independent keys. Record keys support hierarchical broad-plus-entity invalidation:
-
-```ts
-const listKeys = { projects: [] };
-const detailKeys = { projects: [projectId] };
-
-ApiClient.query("projects", "list", { reactivityKeys: listKeys });
-ApiClient.query("projects", "get", { params: { projectId }, reactivityKeys: detailKeys });
-
-// This mutation invalidates the broad namespace and this entity key.
-await mutate({ params: { projectId }, payload: patch, reactivityKeys: detailKeys });
-```
-
-Record semantics register the property name and each `property:id` combination. Consequently, `{ projects: [projectId] }` is hierarchical: it invalidates both the broad `projects` namespace and the specific `projects:projectId` key. Every record-form project query also subscribed to that broad namespace can refresh. Use this when an entity write may affect lists or aggregates.
-
-For exact entity-only invalidation, use namespaced primitive array keys consistently instead:
-
-```ts
-const projectKey = (id: string) => `project:${id}`;
-
-const detailKeys = [projectKey(projectId)];
-const collectionKeys = ["projects"];
-
-ApiClient.query("projects", "get", { params: { projectId }, reactivityKeys: detailKeys });
-await mutate({ params: { projectId }, payload: patch, reactivityKeys: detailKeys });
-```
-
-Use `collectionKeys` for the collection query and for mutations that can change membership or ordering.
-
-Standardize key constructors in one module when several endpoints share them; mismatched strings fail silently.
-
-Choose invalidation breadth from the server write:
-
-- invalidate an exact array-form entity key when only one detail changed;
-- invalidate the collection key, or use hierarchical record keys, when list membership, ordering, totals, or filters can change;
-- invalidate multiple record properties when a write affects related aggregates.
-
-Do not both invalidate and manually refresh the same query unless two requests are intentional.